fix(cli): accept positional folder paths

Author: TheodoreSpeaks

packages/sim-cli/README.md

@@ -113,74 +113,77 @@ also accepts its singular form: for example, `sim table list`,
 spellings.
 
 ```bash
-sim workflows ls [--folder </path>] [--search <text>] [--limit <n>]
-sim workflows list [--folder </path>] [--deployed-only] [--limit <n>]
+sim workflows ls [path] [--search <text>] [--limit <n>]
+sim workflows list [--folder <path>] [--deployed-only] [--limit <n>]
 sim workflows get <id>
-sim workflows mv <id> --folder </path>
+sim workflows mv <id> --folder <path>
 sim workflows deploy|undeploy|rollback <id>
 
 sim logs list [--level error] [--workflow <id>…] [--trigger <name>…] [--start <date>]
 sim logs get <id>
 sim logs execution <executionId>
 
-sim tables ls [--folder </path>] [--search <text>] [--limit <n>]
-sim tables list [--folder </path>]
+sim tables ls [path] [--search <text>] [--limit <n>]
+sim tables list [--folder <path>]
 sim tables get <tableId>
-sim tables mv <tableId> --folder </path>
+sim tables mv <tableId> --folder <path>
 sim tables columns <tableId>
 sim tables rows list <tableId> [--limit <n>]
 sim tables rows query <tableId> [--filter <json>] [--sort <json>] [--limit <n>]
 sim tables upsert <tableId> --data <json>
 sim tables rows batch-delete <tableId> (--row <id>… | --filter <json>) --yes
 
-sim files ls [--folder </path>] [--search <text>] [--limit <n>]
-sim files list [--folder </path>]
+sim files ls [path] [--search <text>] [--limit <n>]
+sim files list [--folder <path>]
 sim files get <fileId>
-sim files create --name <name> [--folder </path>] [--content <value>] [--encoding utf-8|base64]
-sim files upload <path> [--name <name>] [--folder </path>]
+sim files create --name <name> [--folder <path>] [--content <value>] [--encoding utf-8|base64]
+sim files upload <path> [--name <name>] [--folder <path>]
 sim files download <fileId> [-o <path>]
-sim files mv --file-ids <id>… [--to </path>]
+sim files mv --file-ids <id>… [--to <path>]
 sim files batch-delete --file-ids <id>… --yes
 sim files delete <fileId>
 
-sim knowledge ls [--folder </path>] [--search <text>] [--limit <n>]
-sim knowledge list [--folder </path>]
+sim knowledge ls [path] [--search <text>] [--limit <n>]
+sim knowledge list [--folder <path>]
 sim knowledge get <id>
-sim knowledge mv <id> --folder </path>
+sim knowledge mv <id> --folder <path>
 sim knowledge documents <id> [--search <text>]
 sim knowledge documents upload <id> <path> [--tag <value>...]
 sim knowledge search --query <text> --kb <id>… [--search-mode vector|hybrid]
 ```
 
-`ls` is a directory view: it combines the resources at `--folder` with that
-folder's direct child folders. Its `ref` column is the resource ID or canonical
-folder path to pass to the next command. Use `list` when you want resources only,
-or `folders ls` when you want folders only.
+`ls` is a directory view: it combines the resources at its optional path with
+that folder's direct child folders. It never includes deeper descendants. Its
+`ref` column is the resource ID or canonical folder path to pass to the next
+command. Use `list` when you want resources only, or `folders ls` when you want
+folders only.
 
 Each folder-backed resource has the same path commands:
 
 ```bash
-sim tables folders ls --parent /Reports
-sim tables mkdir /Reports/Quarterly
-sim tables folders create /Reports/Quarterly
-sim tables folders mv /Reports/Quarterly /Archive/Quarterly
-sim tables folders delete /Archive/Quarterly --recursive false --yes
+sim tables ls Reports
+sim tables folders ls --parent Reports
+sim tables mkdir Reports/Quarterly
+sim tables folders create Reports/Quarterly
+sim tables folders mv Reports/Quarterly Archive/Quarterly
+sim tables folders delete Archive/Quarterly --recursive false --yes
 ```
 
 `mkdir` is the concise form of `folders create`. Replace `tables` with `files`,
-`workflows`, or `knowledge`. Paths are canonical, start with `/`, and use `/` for
-root. A slash that belongs to a folder name is percent-encoded as `%2F` rather
-than treated as a separator.
+`workflows`, or `knowledge`. The leading `/` is optional on CLI inputs; the CLI
+adds it before calling the API. Omit the `ls` path to list root. A slash that
+belongs to a folder name is percent-encoded as `%2F` rather than treated as a
+separator.
 
 ### List inputs
 
 Primitive lists take space-separated values. Prefix a path with `@` to read
 one value per line, or use `@-` to read the list from stdin.
 
 ```bash
-sim files mv --file-ids file_1 file_2 --to /Archive
-sim files mv --file-ids @file-ids.txt --to /Archive
-printf 'file_1\nfile_2\n' | sim files mv --file-ids @- --to /Archive
+sim files mv --file-ids file_1 file_2 --to Archive
+sim files mv --file-ids @file-ids.txt --to Archive
+printf 'file_1\nfile_2\n' | sim files mv --file-ids @- --to Archive
 ```
 
 Arrays of objects remain JSON inputs because they cannot be represented as a

packages/sim-cli/src/commands/protocol/files-upload.test.ts

@@ -95,7 +95,7 @@ describe('files upload', () => {
     const logged: string[] = []
     vi.spyOn(console, 'log').mockImplementation((line: string) => logged.push(line))
 
-    await program().parseAsync(['node', 'sim', 'file', 'upload', path, '--folder', '/Reports'])
+    await program().parseAsync(['node', 'sim', 'file', 'upload', path, '--folder', 'Reports'])
 
     expect(fetchMock).toHaveBeenCalledWith(
       'https://storage.example/file',

packages/sim-cli/src/commands/protocol/files-upload.ts

@@ -4,6 +4,7 @@ import type {
   CompleteFileUploadResponse,
   CreateFileUploadResponse,
 } from '../../generated/v2-api.js'
+import { normalizeFolderPath } from '../../runtime/folder-path.js'
 import { contentTypeFor, localFile } from '../../transfer/local-file.js'
 import { finishUploadSession } from '../../transfer/upload-session.js'
 import { printProtocolResult } from './result.js'
@@ -26,7 +27,9 @@ export function attachFileUpload(files: Command): void {
           name,
           contentType: contentTypeFor(name),
           size,
-          ...(options.folder ? { folderPath: options.folder } : {}),
+          ...(options.folder !== undefined
+            ? { folderPath: normalizeFolderPath(options.folder) }
+            : {}),
         },
       })
       const { session, uploadToken, transfer } = created.data

packages/sim-cli/src/commands/protocol/resource-directory.test.ts

@@ -25,6 +25,11 @@ function program(): Command {
   const root = new Command('sim').exitOverride()
   for (const group of buildGeneratedCommands()) root.addCommand(group)
   attachProtocolCommands(root)
+  const override = (command: Command) => {
+    command.exitOverride()
+    command.commands.forEach(override)
+  }
+  override(root)
   return root
 }
 
@@ -77,16 +82,7 @@ describe('resource directory', () => {
     const logged: string[] = []
     vi.spyOn(console, 'log').mockImplementation((line: string) => logged.push(line))
 
-    await program().parseAsync([
-      'node',
-      'sim',
-      'table',
-      'ls',
-      '--folder',
-      '/Reports',
-      '--search',
-      'r',
-    ])
+    await program().parseAsync(['node', 'sim', 'table', 'ls', 'Reports', '--search', 'r'])
 
     expect(mockRequest).toHaveBeenCalledWith('/api/v2/tables/folders', {
       query: {
@@ -140,11 +136,18 @@ describe('resource directory', () => {
     })
     vi.spyOn(console, 'log').mockImplementation(() => {})
 
-    await program().parseAsync(['node', 'sim', 'table', 'mkdir', '/Reports/Quarterly'])
+    await program().parseAsync(['node', 'sim', 'table', 'mkdir', 'Reports/Quarterly'])
 
     expect(mockRequest).toHaveBeenCalledWith('/api/v2/tables/folders', {
       method: 'POST',
       body: { workspaceId: 'ws_local', path: '/Reports/Quarterly' },
     })
   })
+
+  it('rejects extra directory arguments instead of silently ignoring them', async () => {
+    await expect(
+      program().parseAsync(['node', 'sim', 'file', 'ls', 'Reports', 'ignored'])
+    ).rejects.toThrow(/too many arguments/i)
+    expect(mockRequest).not.toHaveBeenCalled()
+  })
 })

packages/sim-cli/src/commands/protocol/resource-directory.ts

@@ -14,6 +14,7 @@ import {
 } from '../../generated/v2-api.js'
 import { SimApiError, type SimClient, type V2Page } from '../../http/client.js'
 import { type Column, printList, text, timestamp } from '../../output/render.js'
+import { normalizeFolderPath } from '../../runtime/folder-path.js'
 import { DEFAULT_LIMIT } from '../../runtime/options.js'
 import { renderResult } from '../../runtime/result.js'
 
@@ -70,7 +71,6 @@ type ResourceDirectoryConfig =
     }
 
 interface ListOptions {
-  folder: string
   search?: string
   limit: string
 }
@@ -163,41 +163,43 @@ export function attachResourceDirectoryCommands(
   config: ResourceDirectoryConfig
 ): void {
   group
-    .command('ls')
+    .command('ls [path]')
+    .allowExcessArguments(false)
     .description(`List ${config.kind} resources and child folders together`)
-    .option('--folder <path>', 'Canonical folder path to list', '/')
     .option('--search <text>', 'Filter folders and resources by name')
     .addOption(
       new Option('--limit <n>', 'Maximum combined items to return (0 for everything)').default(
         String(DEFAULT_LIMIT)
       )
     )
-    .action(async (options: ListOptions, command: Command) => {
+    .action(async (path: string | undefined, options: ListOptions, command: Command) => {
       const rawLimit = Number(options.limit)
       if (!Number.isSafeInteger(rawLimit) || rawLimit < 0) {
         throw new SimApiError('--limit must be a non-negative integer', 0)
       }
 
       const limit = rawLimit === 0 ? Number.POSITIVE_INFINITY : rawLimit
+      const folderPath = normalizeFolderPath(path ?? '/')
       const { client, profile } = clientFrom(command)
       const workspaceId = client.requireWorkspace()
       const [folders, resources] = await Promise.all([
-        listFolders(client, config.folders, workspaceId, options.folder, options.search),
-        listResources(client, config, workspaceId, options.folder, options.search, limit),
+        listFolders(client, config.folders, workspaceId, folderPath, options.search),
+        listResources(client, config, workspaceId, folderPath, options.search, limit),
       ])
       const entries = entriesFor(config, folders, resources)
       printList(profile.output, entries.slice(0, limit), COLUMNS)
     })
 
   group
     .command('mkdir <path>')
+    .allowExcessArguments(false)
     .description(`Create a ${config.kind} directory at a canonical path`)
     .action(async (path: string, _options: Record<string, never>, command: Command) => {
       const { client, profile } = clientFrom(command)
       const operation = V2_OPERATIONS[config.createFolder]
       const result = await client.request<{ data?: unknown }>(operation.path, {
         method: operation.method,
-        body: { workspaceId: client.requireWorkspace(), path },
+        body: { workspaceId: client.requireWorkspace(), path: normalizeFolderPath(path) },
       })
       renderResult(config.createFolder, profile.output, result.data ?? result, {})
     })

packages/sim-cli/src/commands/protocol/tables-import.test.ts

@@ -106,7 +106,7 @@ describe('tables import output', () => {
       '--name',
       'Customers',
       '--folder',
-      '/Reports',
+      'Reports',
       '--no-wait',
     ])
 

packages/sim-cli/src/commands/protocol/tables-import.ts

@@ -8,6 +8,7 @@ import type {
   GetTableImportResponse,
 } from '../../generated/v2-api.js'
 import { SimApiError, type SimClient } from '../../http/client.js'
+import { normalizeFolderPath } from '../../runtime/folder-path.js'
 import { coerce, type FieldSpec } from '../../runtime/request.js'
 import { contentTypeFor, localFile } from '../../transfer/local-file.js'
 import { finishUploadSession } from '../../transfer/upload-session.js'
@@ -139,7 +140,13 @@ export function attachTableImport(tables: Command): void {
         if (!name) {
           throw new SimApiError('Pass --name <name> to say what the new table is called', 0)
         }
-        target = { type: 'new', name, ...(options.folder ? { folderPath: options.folder } : {}) }
+        target = {
+          type: 'new',
+          name,
+          ...(options.folder !== undefined
+            ? { folderPath: normalizeFolderPath(options.folder) }
+            : {}),
+        }
       }
 
       const started = await client.request<CreateTableImportResponse>('/api/v2/tables/imports', {