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

Folder create/update/delete/restore/reorder existed once per resource
type in intent but only once in code, hardcoded to workflows. Extract a
config-driven engine so knowledge bases and tables get folders from the
same implementation instead of a fourth copy.

- lib/folders/config.ts declares FOLDER_RESOURCES: the child table, its
  id/folderId/workspace/soft-delete columns, the TS property key backing
  the soft-delete column, membership scope, audit label, and cascade
  count key. Workflow-only behavior (archiving through the workflow
  lifecycle, the last-workflow delete guard, restoring schedules and
  webhooks) is declared as data on the workflow entry, not branched on.
- lib/folders/cascade.ts performs archive/restore under one shared
  timestamp, in a fixed number of statements regardless of subtree depth.
- lib/folders/lifecycle.ts is the single create/update/delete/restore
  implementation; the workflow perform* functions become thin wrappers so
  existing callers are untouched.
- Widen the folder contract to workflow | knowledge_base | table and
  thread resourceType through all four routes and the React Query hooks,
  including the query keys so the three folder trees stop sharing a cache
  entry.
- Move the folder cycle check out of lib/workflows/utils.ts: it was
  hardcoded to resourceType 'workflow' and could walk out of one
  resource's tree into another's.

Author: waleedlatif1

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 { captureServerEvent } from '@/lib/posthog/server'
-import { performRestoreFolder } from '@/lib/workflows/orchestration/folder-lifecycle'
+import { statusForOrchestrationError } from '@/lib/workflows/orchestration/types'
 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: statusForOrchestrationError(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]', () => {
@@ -368,7 +362,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 +376,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,7 +398,8 @@ 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,
@@ -458,7 +452,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 +470,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 () => {

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

@@ -4,13 +4,13 @@ import { createLogger } from '@sim/logger'
 import { assertFolderMutable, FolderLockedError } from '@sim/platform-authz/workflow'
 import { and, eq } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
-import { updateFolderContract } from '@/lib/api/contracts'
+import { deleteFolderContract, updateFolderContract } 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 { deleteFolder, updateFolder } from '@/lib/folders/lifecycle'
 import { toFolderApi } from '@/lib/folders/queries'
 import { captureServerEvent } from '@/lib/posthog/server'
-import { performDeleteFolder, performUpdateFolder } from '@/lib/workflows/orchestration'
 import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
 
 /** Maps an orchestration errorCode to its HTTP status; mirrors the POST /api/folders route. */
@@ -47,13 +47,13 @@ export const PUT = withRouteHandler(
       if (!parsed.success) return parsed.response
 
       const { id } = parsed.data.params
+      const { resourceType } = parsed.data.query
       const { name, locked, parentId, sortOrder } = parsed.data.body
 
-      // Verify the folder exists
       const existingFolder = await db
         .select()
         .from(folderTable)
-        .where(and(eq(folderTable.id, id), eq(folderTable.resourceType, 'workflow')))
+        .where(and(eq(folderTable.id, id), eq(folderTable.resourceType, resourceType)))
         .then((rows) => rows[0])
 
       if (!existingFolder) {
@@ -81,15 +81,19 @@ export const PUT = withRouteHandler(
         )
       }
 
-      const hasNonLockUpdate = Object.keys(parsed.data.body).some((key) => key !== 'locked')
-      if (hasNonLockUpdate) {
-        await assertFolderMutable(id)
-      }
-      if (parentId !== undefined) {
-        await assertFolderMutable(parentId)
+      // Folder locking is a workflow-only feature; other resource types leave `locked` false.
+      if (resourceType === 'workflow') {
+        const hasNonLockUpdate = Object.keys(parsed.data.body).some((key) => key !== 'locked')
+        if (hasNonLockUpdate) {
+          await assertFolderMutable(id)
+        }
+        if (parentId !== undefined) {
+          await assertFolderMutable(parentId)
+        }
       }
 
-      const result = await performUpdateFolder({
+      const result = await updateFolder({
+        resourceType,
         folderId: id,
         workspaceId: existingFolder.workspaceId,
         userId: session.user.id,
@@ -120,20 +124,22 @@ export const PUT = withRouteHandler(
 
 // DELETE - Delete a folder and all its contents
 export const DELETE = withRouteHandler(
-  async (request: NextRequest, { params }: { params: Promise<{ id: string }> }) => {
+  async (request: NextRequest, context: { params: Promise<{ id: string }> }) => {
     try {
       const session = await getSession()
       if (!session?.user?.id) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
       }
 
-      const { id } = await params
+      const parsed = await parseRequest(deleteFolderContract, request, context)
+      if (!parsed.success) return parsed.response
+      const { id } = parsed.data.params
+      const { resourceType } = parsed.data.query
 
-      // Verify the folder exists
       const existingFolder = await db
         .select()
         .from(folderTable)
-        .where(and(eq(folderTable.id, id), eq(folderTable.resourceType, 'workflow')))
+        .where(and(eq(folderTable.id, id), eq(folderTable.resourceType, resourceType)))
         .then((rows) => rows[0])
 
       if (!existingFolder) {
@@ -153,9 +159,12 @@ export const DELETE = withRouteHandler(
         )
       }
 
-      await assertFolderMutable(id)
+      if (resourceType === 'workflow') {
+        await assertFolderMutable(id)
+      }
 
-      const result = await performDeleteFolder({
+      const result = await deleteFolder({
+        resourceType,
         folderId: id,
         workspaceId: existingFolder.workspaceId,
         userId: session.user.id,
@@ -171,7 +180,7 @@ export const DELETE = withRouteHandler(
       captureServerEvent(
         session.user.id,
         'folder_deleted',
-        { workspace_id: existingFolder.workspaceId },
+        { workspace_id: existingFolder.workspaceId, resource_type: resourceType },
         { groups: { workspace: existingFolder.workspaceId } }
       )
 

apps/sim/app/api/folders/reorder/route.test.ts

@@ -66,6 +66,33 @@ describe('PUT /api/folders/reorder', () => {
     expect(data).toMatchObject({ success: true, updated: 1 })
   })
 
+  it('maps a sibling-name collision from a reparent to a 409', async () => {
+    mockWhere
+      .mockReturnValueOnce([{ id: 'folder-1', workspaceId: 'workspace-123' }])
+      .mockReturnValueOnce([{ id: 'parent-1', workspaceId: 'workspace-123', archivedAt: null }])
+      .mockReturnValueOnce([
+        { id: 'folder-1', parentId: null },
+        { id: 'parent-1', parentId: null },
+      ])
+
+    const uniqueViolation = Object.assign(new Error('duplicate key value'), { code: '23505' })
+    mockDb.transaction.mockImplementationOnce(async () => {
+      throw uniqueViolation
+    })
+
+    const req = createMockRequest('PUT', {
+      workspaceId: 'workspace-123',
+      resourceType: 'knowledge_base',
+      updates: [{ id: 'folder-1', sortOrder: 0, parentId: 'parent-1' }],
+    })
+
+    const response = await PUT(req)
+
+    expect(response.status).toBe(409)
+    const data = await response.json()
+    expect(data.error).toBe('A folder with this name already exists in this location')
+  })
+
   it('rejects a parentId that belongs to another workspace', async () => {
     mockWhere
       .mockReturnValueOnce([{ id: 'folder-1', workspaceId: 'workspace-123' }])