fix(files): resolve a named append inside the chosen folder

cubic raised this twice; I deferred it once and it deserved the fix.

Append resolves a picked file by canonical id, where the folder beside it is
redundant. The advanced entry supplies a name instead, and a name is only unique
within a folder — a workspace-wide lookup takes the oldest match anywhere, so
the folder sat next to the field looking like it scoped the operation while
doing nothing. That is the same objection that had me remove this field earlier
in the branch, reappearing in advanced mode only.

The rule is now stated properly: the folder travels when it is what identifies
the file, and stays behind when the id already does. A named append expands the
chosen folder through the authorized use case, matches the name inside it, and
resolves by the id it finds — so no path-shaped reference is ever built and the
slash-in-a-folder-name hazard cannot arise on this path. A name that is not in
the folder refuses rather than reaching for a same-named file elsewhere.

Tests cover the case that motivated it: two files named notes.md in different
folders, appending to the one in the folder that was picked.

Author: mzxchandra

apps/sim/blocks/blocks/file-folders.test.ts

@@ -190,7 +190,12 @@ describe('file_v5 folder operations produce contract-valid tool input', () => {
      * target. The earlier version of this field was removed precisely because
      * it looked like it scoped the picker without doing so; now it does.
      */
-    it('sends no folder on append even when one narrows the picker', () => {
+    /*
+     * A picked file is a canonical id and already exact, so the folder beside
+     * it would be a second constraint on one target. A typed name is not
+     * exact — that case is the next test.
+     */
+    it('sends no folder when append resolved the file by id', () => {
       const params = paramsFor('file_append', {
         appendFileInput: { id: 'wf_abc', name: 'notes.md' },
         appendContent: 'more',
@@ -201,6 +206,42 @@ describe('file_v5 folder operations produce contract-valid tool input', () => {
       expect(params.folderPaths).toBeUndefined()
     })
 
+    /*
+     * The advanced entry supplies a name, and a name is only unique inside a
+     * folder — without the scope a duplicate resolves to the oldest match
+     * anywhere in the workspace.
+     */
+    it('sends the folder when append resolved the file by name', () => {
+      const params = paramsFor('file_append', {
+        appendFileInput: 'notes.md',
+        appendContent: 'more',
+        folderScopeRef: '/Reports',
+      })
+
+      expect(params.folderPath).toBe('/Reports')
+    })
+
+    it('carries the subfolder scope with a name-based append', () => {
+      expect(
+        paramsFor('file_append', {
+          appendFileInput: 'notes.md',
+          appendContent: 'more',
+          folderScopeRef: '/Reports',
+          folderIncludeSubfolders: 'false',
+        }).includeSubfolders
+      ).toBe(false)
+    })
+
+    it('still sends no folder when the pick carried an id', () => {
+      expect(
+        paramsFor('file_append', {
+          appendFileInput: { id: 'wf_abc', name: 'notes.md' },
+          appendContent: 'more',
+          folderScopeRef: '/Reports',
+        }).folderPath
+      ).toBeUndefined()
+    })
+
     it('appends by the picked file id, not its name', () => {
       expect(
         paramsFor('file_append', {

apps/sim/blocks/blocks/file.ts

@@ -1742,6 +1742,7 @@ export const FileV5Block: BlockConfig<FileParserV3Output> = {
           }
 
           let fileName: string
+          let resolvedById = false
           if (typeof appendInput === 'string') {
             fileName = appendInput.trim()
           } else {
@@ -1755,15 +1756,30 @@ export const FileV5Block: BlockConfig<FileParserV3Output> = {
              * file.
              */
             const pickedId = typeof file?.id === 'string' ? file.id : ''
+            resolvedById = Boolean(pickedId)
             fileName = pickedId || ((file?.name as string) ?? '')
           }
 
           if (!fileName) {
             throw new Error('Could not determine file name')
           }
 
+          /*
+           * The folder travels only when the name is what identifies the file.
+           * A picked file is a canonical id and already exact, so sending the
+           * folder beside it would imply a second constraint on one target.
+           */
+          const appendFolder = resolvedById ? undefined : folderScopePath(params.folderScopeRef)
           return {
             fileName,
+            ...(appendFolder
+              ? {
+                  folderPath: appendFolder,
+                  ...(switchValue(params.folderIncludeSubfolders, true)
+                    ? {}
+                    : { includeSubfolders: false }),
+                }
+              : {}),
             content: params.appendContent,
             workspaceId: params._context?.workspaceId,
           }

apps/sim/lib/api/contracts/tools/file.ts

@@ -57,7 +57,13 @@ export const fileManageAppendBodySchema = z.object({
   operation: z.literal('append'),
   workspaceId: z.string().min(1).optional(),
   fileName: z.string({ error: 'fileName is required for append operation' }).min(1),
+  /**
+   * Folder the name is resolved inside. A name is only unique within a folder,
+   * so without this a duplicate name resolves to the oldest match anywhere.
+   * Ignored when `fileName` is already a canonical id.
+   */
   folderPath: v2FolderPathInputSchema.optional(),
+  includeSubfolders: z.boolean().optional(),
   content: z.string({ error: 'content is required for append operation' }),
   [PRIVATE_SECRET_PROVENANCE_FIELD]: privateSecretProvenanceBundleSchema.optional(),
 })

apps/sim/lib/internal/file/operations.test.ts

@@ -337,6 +337,11 @@ describe('file manage folder wiring', () => {
       key: 'workspace/workspace-1/new.txt',
       url: '/api/files/serve/new-file',
     })
+    mockResolveWorkspaceFileReference.mockImplementation(
+      async ({ reference }: { reference: string }) => workspaceFile(reference)
+    )
+    mockFetchWorkspaceFileBuffer.mockResolvedValue(Buffer.from('before'))
+    mockUpdateWorkspaceFileContent.mockResolvedValue({ file: workspaceFile('file-1') })
   })
 
   it('expands a folder-only read instead of rejecting it', async () => {
@@ -399,6 +404,60 @@ describe('file manage folder wiring', () => {
     )
   })
 
+  /*
+   * The case that motivated this: two files share a name in different folders,
+   * and a typed name alone resolves to the oldest match anywhere. The folder is
+   * the only thing telling them apart.
+   */
+  it('appends to the file in the chosen folder, not a same-named file elsewhere', async () => {
+    mockListAllWorkspaceFiles.mockResolvedValue({
+      files: [
+        { ...workspaceFile('notes-elsewhere'), name: 'notes.md', folderId: null },
+        { ...workspaceFile('notes-in-reports'), name: 'notes.md', folderId: 'folder-reports' },
+      ],
+    })
+    mockGetWorkspaceFile.mockImplementation(async (_ws: string, fileId: string) => ({
+      ...workspaceFile(fileId),
+      name: 'notes.md',
+    }))
+
+    await POST(
+      createMockRequest('POST', {
+        operation: 'append',
+        workspaceId: 'workspace-1',
+        fileName: 'notes.md',
+        folderPath: '/Reports',
+        content: 'more',
+      })
+    )
+
+    // Resolved by the id found inside the folder, never by the bare name.
+    expect(mockResolveWorkspaceFileReference).toHaveBeenCalledWith(
+      'workspace-1',
+      'notes-in-reports'
+    )
+  })
+
+  it('refuses rather than appending to a same-named file outside the folder', async () => {
+    mockListAllWorkspaceFiles.mockResolvedValue({
+      files: [{ ...workspaceFile('notes-elsewhere'), name: 'notes.md', folderId: null }],
+    })
+
+    const response = await POST(
+      createMockRequest('POST', {
+        operation: 'append',
+        workspaceId: 'workspace-1',
+        fileName: 'notes.md',
+        folderPath: '/Reports',
+        content: 'more',
+      })
+    )
+    const body = await response.json()
+
+    expect(body.success).toBe(false)
+    expect(String(body.error)).toContain('No file named notes.md in /Reports')
+  })
+
   it('lists what a folder holds, folders and files together', async () => {
     const response = await POST(
       createMockRequest('POST', { operation: 'list', workspaceId: 'workspace-1' })

apps/sim/lib/internal/file/operations.ts

@@ -578,12 +578,12 @@ export function fileContentJsonResponse(
  * Path resolution itself lives in {@link resolveFolderIdsForPaths}; this is the
  * IO around it.
  */
-async function expandFolderPathsToFileIds(args: {
+async function expandFolderPathsToFiles(args: {
   principal: Principal
   workspaceId: string
   folderPaths: string[] | undefined
   includeSubfolders: boolean | undefined
-}): Promise<string[]> {
+}): Promise<Array<{ id: string; name: string; folderId?: string | null }>> {
   if (!args.folderPaths?.length) return []
 
   const [{ folders }, { files }] = await Promise.all([
@@ -609,9 +609,16 @@ async function expandFolderPathsToFileIds(args: {
     throw new OrchestrationError('not_found', `Folder not found: ${selection.missingPath}`)
   }
 
-  return files
-    .filter((file) => file.folderId && selection.folderIds.has(file.folderId))
-    .map((file) => file.id)
+  return files.filter((file) => file.folderId && selection.folderIds.has(file.folderId))
+}
+
+async function expandFolderPathsToFileIds(args: {
+  principal: Principal
+  workspaceId: string
+  folderPaths: string[] | undefined
+  includeSubfolders: boolean | undefined
+}): Promise<string[]> {
+  return (await expandFolderPathsToFiles(args)).map((file) => file.id)
 }
 
 export async function executeFileManageOperation(
@@ -1187,14 +1194,37 @@ export async function executeFileManageOperation(
       }
 
       case 'append': {
-        const { fileName, content } = body
+        const { fileName, content, folderPath, includeSubfolders } = body
         signal?.throwIfAborted()
 
+        /*
+         * A picked file arrives as a canonical id, which is already exact. A
+         * typed name is not: the same name can exist in several folders, and a
+         * workspace-wide lookup takes the oldest match anywhere. When a folder
+         * was chosen it is the only thing disambiguating the target, so the
+         * name is resolved inside it — by id, so the slash-in-a-folder-name
+         * hazard of a path-shaped reference never arises.
+         */
+        let scopedReference = fileName
+        if (folderPath && !fileName.startsWith('wf_')) {
+          const scoped = await expandFolderPathsToFiles({
+            principal,
+            workspaceId,
+            folderPaths: [folderPath],
+            includeSubfolders,
+          })
+          const match = scoped.find((file) => file.name === fileName)
+          if (!match) {
+            throw new OrchestrationError('not_found', `No file named ${fileName} in ${folderPath}`)
+          }
+          scopedReference = match.id
+        }
+
         const existing = await resolveWorkspaceFileReference({
           principal,
           operation: fileOperations.updateContent,
           workspaceId,
-          reference: fileName,
+          reference: scopedReference,
         })
 
         const lockKey = `file-append:${workspaceId}:${existing.id}`