fix(files): accept files/ VFS paths in v2 file describe, rename and delete

apps/docs/content/docs/cli/files.mdx

@@ -102,7 +102,7 @@ sim files describe <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
 
 </CommandTable>
 
@@ -303,7 +303,7 @@ sim files rename <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
 
 </CommandTable>
 
@@ -613,7 +613,7 @@ sim files delete <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
 
 </CommandTable>
 

apps/docs/content/docs/cli/reference.mdx

@@ -1171,7 +1171,7 @@ sim files delete <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
 
 </CommandTable>
 
@@ -1416,7 +1416,7 @@ sim files describe <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
 
 </CommandTable>
 
@@ -1581,7 +1581,7 @@ sim files rename <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`. |
 
 </CommandTable>
 

apps/docs/openapi-v2-files-audit.json

@@ -2151,13 +2151,12 @@
             "name": "fileId",
             "in": "path",
             "required": true,
-            "description": "File identifier.",
+            "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`.",
             "schema": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 128,
-              "pattern": "^[A-Za-z0-9_-]+$",
-              "description": "File identifier."
+              "maxLength": 4096,
+              "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`."
             }
           },
           {
@@ -2238,13 +2237,12 @@
             "name": "fileId",
             "in": "path",
             "required": true,
-            "description": "File identifier.",
+            "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`.",
             "schema": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 128,
-              "pattern": "^[A-Za-z0-9_-]+$",
-              "description": "File identifier."
+              "maxLength": 4096,
+              "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`."
             }
           }
         ],
@@ -2489,13 +2487,12 @@
             "name": "fileId",
             "in": "path",
             "required": true,
-            "description": "File identifier.",
+            "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`.",
             "schema": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 128,
-              "pattern": "^[A-Za-z0-9_-]+$",
-              "description": "File identifier."
+              "maxLength": 4096,
+              "description": "File identifier, or the file’s VFS path: `files/<folder>/<name>`."
             }
           },
           {

apps/sim/lib/api/contracts/v2/files.ts

@@ -45,6 +45,7 @@ import {
 import { MAX_FOLDER_PATH_BYTES, MAX_FOLDER_PATH_SEGMENTS } from '@/lib/folders/paths'
 import { MAX_WORKSPACE_FILE_SIZE } from '@/lib/uploads/shared/types'
 import { MAX_TEXT_EXTRACTION_BYTES } from '@/lib/uploads/utils/file'
+import { isWorkspaceFileVfsPath } from '@/lib/vfs/path'
 import { MAX_ZIP_DOWNLOAD_FILES } from '@/lib/workspace-files/limits'
 import {
   FILE_SEARCH_DEFAULT_MAX_RESULTS,
@@ -302,6 +303,17 @@ export const v2FileReferenceParamsSchema = z.object({
 
 export type V2FileReferenceParams = z.output<typeof v2FileReferenceParamsSchema>
 
+/** Also takes the `files/…` path `glob` and listings print, so no listing round-trip finds the id. */
+const v2FileIdOrPathParamsSchema = z.object({
+  fileId: requiredFieldSchema('File reference is required')
+    .max(MAX_FOLDER_PATH_BYTES, 'File reference is too long')
+    .refine(
+      (value) => isWorkspaceFileVfsPath(value) || workspaceFileIdSchema.safeParse(value).success,
+      'Invalid file id or path: pass a file id or its `files/<folder>/<name>` VFS path'
+    )
+    .describe('File identifier, or the file’s VFS path: `files/<folder>/<name>`.'),
+})
+
 export const v2CreateFileBodySchema = z
   .object({
     workspaceId: workspaceIdSchema.describe('Workspace in which to create the file.'),
@@ -943,7 +955,7 @@ export const v2ReadFileTextContract = defineRouteContract({
 export const v2GetFileContract = defineRouteContract({
   method: 'GET',
   path: '/api/v2/files/[fileId]/metadata',
-  params: v2FileParamsSchema,
+  params: v2FileIdOrPathParamsSchema,
   query: v2GetFileMetadataQuerySchema,
   response: {
     mode: 'json',
@@ -955,7 +967,7 @@ export const v2RenameFileContract = defineRouteContract({
   method: 'PATCH',
   path: '/api/v2/files/[fileId]',
   query: noInputSchema,
-  params: v2FileParamsSchema,
+  params: v2FileIdOrPathParamsSchema,
   body: v2RenameFileBodySchema,
   response: {
     mode: 'json',
@@ -966,7 +978,7 @@ export const v2RenameFileContract = defineRouteContract({
 export const v2DeleteFileContract = defineRouteContract({
   method: 'DELETE',
   path: '/api/v2/files/[fileId]',
-  params: v2FileParamsSchema,
+  params: v2FileIdOrPathParamsSchema,
   query: v2FileWorkspaceQuerySchema,
   response: {
     mode: 'json',

apps/sim/lib/uploads/contexts/workspace/file-manager.ts

@@ -2342,6 +2342,40 @@ async function getWorkspaceFileByExactReference(
   return folderId ? getWorkspaceFileByName(workspaceId, segments.at(-1) ?? '', { folderId }) : null
 }
 
+/**
+ * The live workspace file whose canonical `files/…` path — as listings print it — is `vfsPath`,
+ * or null. Unlike {@link findWorkspaceFileRecord} there is no virtual `/content` or `/meta.json`
+ * suffix and no leaf-name fallback, so a mutation addressed by path lands only on the file it
+ * names. Two names that display alike are ambiguous and refused. Throws `VfsPathError` if
+ * malformed.
+ */
+export async function getWorkspaceFileByVfsPath(
+  workspaceId: string,
+  vfsPath: string
+): Promise<WorkspaceFileRecord | null> {
+  const segments = decodeVfsReferenceSegments(vfsPath.slice('files/'.length))
+  const leaf = segments.at(-1)
+  if (leaf === undefined) return null
+  const pathKey = segments.map(normalizeVfsSegment).join('/')
+  const candidates = await listWorkspaceFileCandidates(workspaceId, {
+    ids: [],
+    leafNames: [normalizeDisplaySegment(leaf)],
+  })
+  const matches = candidates.filter(
+    (file) =>
+      canonicalWorkspaceFilePath({ folderPath: file.folderPath, name: file.name }).slice(
+        'files/'.length
+      ) === pathKey
+  )
+  if (matches.length > 1) {
+    throw new OrchestrationError(
+      'validation',
+      `"${vfsPath}" names more than one file whose names display alike; pass the file id instead`
+    )
+  }
+  return matches[0] ?? null
+}
+
 /**
  * Resolve a workspace file record from either its id or a VFS/name reference.
  *

apps/sim/lib/vfs/path.ts

@@ -10,6 +10,11 @@ export class VfsPathError extends Error {
   }
 }
 
+/** A `files/…` workspace-file VFS path. File ids are drawn from `[A-Za-z0-9_-]`, so no id is one. */
+export function isWorkspaceFileVfsPath(reference: string): boolean {
+  return reference.startsWith('files/')
+}
+
 /**
  * The name a VFS path segment displays: NFC-composed, trimmed, control characters removed,
  * whitespace runs collapsed. Its SQL twin is `displaySegmentKey` in `@sim/db/schema`, which an