feat(folders): add the generic resourceType-driven folder engine (#6037)

- Replaces the workflow-hardcoded folder orchestration with a config-driven engine: one implementation parameterized by `FOLDER_RESOURCES`, with `lib/workflows/orchestration/folder-lifecycle.ts` reduced from 620 lines to thin wrappers so no existing caller moved
- Threads `resourceType` through all four folder routes and the React Query keys; contract widened to `workflow | knowledge_base | table`
- Folder locking moved behind a `supportsLocking` capability rather than scattered `resourceType === 'workflow'` checks
- Folder restore now matches dependents by the cascade timestamp, so a schedule or webhook archived independently before a folder delete stays archived (deliberate behavior change, documented in the PR)
- 25 cascade tests including a fixed-statement-count assertion guarding against N+1 regressions

Author: waleedlatif1

apps/sim/app/api/folders/[id]/duplicate/route.ts

@@ -112,7 +112,8 @@ export const POST = withRouteHandler(
           tx,
           targetWorkspaceId,
           targetParentId,
-          name
+          name,
+          'workflow'
         )
 
         await tx.insert(folderTable).values({

apps/sim/app/api/folders/[id]/restore/route.ts

@@ -5,8 +5,9 @@ import { restoreFolderContract } from '@/lib/api/contracts'
 import { parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { restoreFolder } from '@/lib/folders/lifecycle'
+import { folderMutationStatus } from '@/lib/folders/status'
 import { captureServerEvent } from '@/lib/posthog/server'
-import { performRestoreFolder } from '@/lib/workflows/orchestration/folder-lifecycle'
 import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
 
 const logger = createLogger('RestoreFolderAPI')
@@ -23,29 +24,36 @@ export const POST = withRouteHandler(async (request: NextRequest, context: Route
     const parsed = await parseRequest(restoreFolderContract, request, context)
     if (!parsed.success) return parsed.response
     const { id: folderId } = parsed.data.params
-    const { workspaceId } = parsed.data.body
+    const { workspaceId, resourceType } = parsed.data.body
 
     const permission = await getUserEntityPermissions(session.user.id, 'workspace', workspaceId)
     if (permission !== 'admin' && permission !== 'write') {
       return NextResponse.json({ error: 'Insufficient permissions' }, { status: 403 })
     }
 
-    const result = await performRestoreFolder({
+    const result = await restoreFolder({
+      resourceType,
       folderId,
       workspaceId,
       userId: session.user.id,
     })
 
     if (!result.success) {
-      return NextResponse.json({ error: result.error }, { status: 400 })
+      return NextResponse.json(
+        { error: result.error },
+        { status: folderMutationStatus(result.errorCode) }
+      )
     }
 
-    logger.info(`Restored folder ${folderId}`, { restoredItems: result.restoredItems })
+    logger.info(`Restored folder ${folderId}`, {
+      resourceType,
+      restoredItems: result.restoredItems,
+    })
 
     captureServerEvent(
       session.user.id,
       'folder_restored',
-      { folder_id: folderId, workspace_id: workspaceId },
+      { folder_id: folderId, workspace_id: workspaceId, resource_type: resourceType },
       { groups: { workspace: workspaceId } }
     )
 

apps/sim/app/api/folders/[id]/route.test.ts

@@ -8,16 +8,14 @@ import {
   authMockFns,
   createMockRequest,
   dbChainMockFns,
+  foldersLifecycleMock,
+  foldersLifecycleMockFns,
   type MockUser,
   permissionsMock,
   permissionsMockFns,
   queueTableRows,
   resetDbChainMock,
   schemaMock,
-  workflowsOrchestrationMock,
-  workflowsOrchestrationMockFns,
-  workflowsUtilsMock,
-  workflowsUtilsMockFns,
 } from '@sim/testing'
 import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
 
@@ -36,8 +34,11 @@ const { mockLogger } = vi.hoisted(() => {
   }
 })
 
-const mockPerformDeleteFolder = workflowsOrchestrationMockFns.mockPerformDeleteFolder
-const mockPerformUpdateFolder = workflowsOrchestrationMockFns.mockPerformUpdateFolder
+const mockDeleteFolder = foldersLifecycleMockFns.mockDeleteFolder
+const mockUpdateFolder = foldersLifecycleMockFns.mockUpdateFolder
+
+/** Parent ids the mocked engine treats as closing a cycle for the folder under test. */
+const cyclicParentIds = new Set<string>()
 
 const mockGetUserEntityPermissions = permissionsMockFns.mockGetUserEntityPermissions
 
@@ -48,8 +49,7 @@ vi.mock('@sim/logger', () => ({
   getRequestContext: () => undefined,
 }))
 vi.mock('@/lib/workspaces/permissions/utils', () => permissionsMock)
-vi.mock('@/lib/workflows/orchestration', () => workflowsOrchestrationMock)
-vi.mock('@/lib/workflows/utils', () => workflowsUtilsMock)
+vi.mock('@/lib/folders/lifecycle', () => foldersLifecycleMock)
 
 import { DELETE, PUT } from '@/app/api/folders/[id]/route'
 
@@ -101,25 +101,19 @@ describe('Individual Folder API Route', () => {
     resetDbChainMock()
 
     mockGetUserEntityPermissions.mockResolvedValue('admin')
-    mockPerformDeleteFolder.mockResolvedValue({
+    mockDeleteFolder.mockResolvedValue({
       success: true,
       deletedItems: { folders: 1, workflows: 0 },
     })
-    mockPerformUpdateFolder.mockImplementation(async (params) => {
+    mockUpdateFolder.mockImplementation(async (params) => {
       if (params.parentId && params.parentId === params.folderId) {
         return {
           success: false,
           error: 'Folder cannot be its own parent',
           errorCode: 'validation',
         }
       }
-      if (
-        params.parentId &&
-        (await workflowsUtilsMockFns.mockCheckForCircularReference(
-          params.folderId,
-          params.parentId
-        ))
-      ) {
+      if (params.parentId && cyclicParentIds.has(params.parentId)) {
         return {
           success: false,
           error: 'Cannot create circular folder reference',
@@ -140,7 +134,7 @@ describe('Individual Folder API Route', () => {
         },
       }
     })
-    workflowsUtilsMockFns.mockCheckForCircularReference.mockResolvedValue(false)
+    cyclicParentIds.clear()
   })
 
   describe('PUT /api/folders/[id]', () => {
@@ -250,6 +244,26 @@ describe('Individual Folder API Route', () => {
       expect(data).toHaveProperty('folder')
     })
 
+    it('rejects a locked write on a resource type that has no lock semantics', async () => {
+      mockAuthenticatedUser()
+      queueFolderLookup()
+
+      const req = createMockRequest(
+        'PUT',
+        { locked: true },
+        {},
+        'http://localhost:3000/api/folders/folder-1?resourceType=knowledge_base'
+      )
+      const params = Promise.resolve({ id: 'folder-1' })
+
+      const response = await PUT(req, { params })
+
+      expect(response.status).toBe(400)
+      const data = await response.json()
+      expect(data.error).toBe('Folder locking is only supported for workflow folders')
+      expect(mockUpdateFolder).not.toHaveBeenCalled()
+    })
+
     it('should return 400 when trying to set folder as its own parent', async () => {
       mockAuthenticatedUser()
 
@@ -368,7 +382,7 @@ describe('Individual Folder API Route', () => {
         workspaceId: 'workspace-123',
       })
 
-      workflowsUtilsMockFns.mockCheckForCircularReference.mockResolvedValue(true)
+      cyclicParentIds.add('folder-1')
 
       const req = createMockRequest('PUT', {
         name: 'Updated Folder 3',
@@ -382,9 +396,8 @@ describe('Individual Folder API Route', () => {
 
       const data = await response.json()
       expect(data).toHaveProperty('error', 'Cannot create circular folder reference')
-      expect(workflowsUtilsMockFns.mockCheckForCircularReference).toHaveBeenCalledWith(
-        'folder-3',
-        'folder-1'
+      expect(mockUpdateFolder).toHaveBeenCalledWith(
+        expect.objectContaining({ folderId: 'folder-3', parentId: 'folder-1' })
       )
     })
   })
@@ -405,14 +418,34 @@ describe('Individual Folder API Route', () => {
       const data = await response.json()
       expect(data).toHaveProperty('success', true)
       expect(data).toHaveProperty('deletedItems')
-      expect(mockPerformDeleteFolder).toHaveBeenCalledWith({
+      expect(mockDeleteFolder).toHaveBeenCalledWith({
+        resourceType: 'workflow',
         folderId: 'folder-1',
         workspaceId: 'workspace-123',
         userId: TEST_USER.id,
         folderName: 'Test Folder',
       })
     })
 
+    it('surfaces a delete-locked resource as 423, not a generic 500', async () => {
+      mockAuthenticatedUser()
+      queueFolderLookup()
+      mockDeleteFolder.mockResolvedValueOnce({
+        success: false,
+        error: 'Cannot delete folder: table Ledger is delete-locked',
+        errorCode: 'locked',
+      })
+
+      const req = createMockRequest('DELETE')
+      const params = Promise.resolve({ id: 'folder-1' })
+
+      const response = await DELETE(req, { params })
+
+      expect(response.status).toBe(423)
+      const data = await response.json()
+      expect(data.error).toBe('Cannot delete folder: table Ledger is delete-locked')
+    })
+
     it('should return 401 for unauthenticated delete requests', async () => {
       mockUnauthenticated()
 
@@ -458,7 +491,7 @@ describe('Individual Folder API Route', () => {
 
       const data = await response.json()
       expect(data).toHaveProperty('success', true)
-      expect(mockPerformDeleteFolder).toHaveBeenCalled()
+      expect(mockDeleteFolder).toHaveBeenCalled()
     })
 
     it('should allow folder deletion for admin permissions', async () => {
@@ -476,7 +509,7 @@ describe('Individual Folder API Route', () => {
 
       const data = await response.json()
       expect(data).toHaveProperty('success', true)
-      expect(mockPerformDeleteFolder).toHaveBeenCalled()
+      expect(mockDeleteFolder).toHaveBeenCalled()
     })
 
     it('should handle database errors during deletion', async () => {