fix(cli): refuse what the help already says is invalid

Live testing of the published package found a set of flags the CLI
documents as constrained and then transmits anyway. `--limit` on the two
filtered row mutations says "0 is not accepted" and sent 0, -1 and 1.5;
`--max-bytes` leaked its validator's own wording for a fraction or an
oversized value; `--recipe` named no accepted values though the server
takes four; a blank message or a malformed conversation id reached the
wire, and an empty `-c` was dropped from the body so the turn silently
started a new conversation.

Selecting rows to delete by neither filter nor id reported the opposite
mistake, because the only message came from the refinement that also
catches passing both.

`workflows activate create` chooses which existing version serves live
traffic, exactly as `rollback` does, and `rollback` is gated where it was
not. `deploy` is left alone: it publishes the draft the caller just typed,
it is additive, and rollback undoes it.

`--limit 0` with run state walked the whole table in pages the server
accepts one at a time, which is what its own rule exists to prevent.

`--workspace` is a root flag, so it is parsed for the thirty-nine
operations that have nowhere to put it and then dropped. That silence is
what made a correctly-scoped route look like it was ignoring scope, so it
warns now rather than refusing — too many commands take it harmlessly for
a refusal to be safe.

Messages that named a request field the caller cannot type were only ever
half rewritten, because a single-word field is indistinguishable from an
English word. A message is now translated whole or left as the server sent
it, so no sentence mixes the two vocabularies.

Author: waleedlatif1

packages/sim-cli/src/commands/protocol/chat.test.ts

@@ -100,6 +100,9 @@ function written(spy: WriteSpy): string {
   return spy.mock.calls.map((call) => String(call[0])).join('')
 }
 
+/** A conversation id in the shape the route accepts and the command prints. */
+const CONVERSATION_ID = '3f2a1c4e-0000-4000-8000-000000000000'
+
 const FINAL = {
   type: 'final',
   data: { content: 'Hello there', conversationId: 'conv-1', model: 'sim' },
@@ -127,17 +130,35 @@ describe('sim chat', () => {
     expect(written(stderr)).toContain('conversation: conv-1')
   })
 
+  /**
+   * The route's own refusals name `message` and `conversationId`, and this
+   * command builds its request by hand so nothing retypes them into what the
+   * caller typed. A blank `-c` was worse than misnamed: it is falsy, so it was
+   * dropped from the body and silently started a NEW conversation.
+   */
+  it('refuses a blank message and a malformed -c before the request', async () => {
+    await expect(run('   ')).rejects.toThrow('<message> cannot be empty')
+    await expect(run('-c', '', 'hello')).rejects.toThrow('-c/--conversation must be a')
+    await expect(run('-c', 'conv-1', 'hello')).rejects.toThrow('-c/--conversation must be a')
+    expect(requestRaw).not.toHaveBeenCalled()
+  })
+
+  /**
+   * A conversation id as the command prints it: the route requires a UUID and
+   * the CLI now says so before the request, so a stand-in like `conv-1` is
+   * refused rather than sent.
+   */
   it('passes -c through as the conversation to continue', async () => {
     requestRaw.mockResolvedValue(ndjson([FINAL]))
 
-    await run('-c', 'conv-1', 'And which run on a schedule?')
+    await run('-c', CONVERSATION_ID, 'And which run on a schedule?')
 
     expect(requestRaw).toHaveBeenCalledWith('/api/v2/chat', {
       method: 'POST',
       body: {
         workspaceId: 'ws_local',
         message: 'And which run on a schedule?',
-        conversationId: 'conv-1',
+        conversationId: CONVERSATION_ID,
       },
       headers: { accept: 'application/x-ndjson' },
     })

packages/sim-cli/src/commands/protocol/chat.ts

@@ -142,6 +142,12 @@ function ignoreBrokenPipe(stream: NodeJS.WriteStream): () => void {
  * proxies from idling the connection out. The generated `chat` operation is
  * hidden in the CLI contract in favour of this command.
  */
+/**
+ * The shape the route accepts for `conversationId`: a UUID, which is what the
+ * command prints on stderr at the end of every turn.
+ */
+const CONVERSATION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
 export function attachChat(program: Command): void {
   program
     .command('chat')
@@ -164,6 +170,25 @@ Examples:
 `
     )
     .action(async (message: string, options: ChatOptions, command: Command) => {
+      /**
+       * Refused here so the refusal names what the caller typed. The route says
+       * `message cannot be empty` and `conversationId must be a valid
+       * conversation id` — its own field names, and this command builds its
+       * request by hand so nothing retypes them into `<message>` and
+       * `-c/--conversation`. A blank `-c` was worse than misnamed: it is falsy,
+       * so it was dropped from the body and silently started a NEW conversation
+       * instead of continuing one.
+       */
+      if (message.trim() === '') {
+        throw new SimApiError('<message> cannot be empty', 0)
+      }
+      if (options.conversation !== undefined && !CONVERSATION_ID.test(options.conversation)) {
+        throw new SimApiError(
+          '-c/--conversation must be a conversation id — the one printed on stderr after each turn',
+          0
+        )
+      }
+
       const { client, profile } = clientFrom(command)
       const workspaceId = client.requireWorkspace()
 

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

@@ -213,6 +213,41 @@ describe('knowledge documents upload', () => {
     expect(mockRequest).not.toHaveBeenCalled()
   })
 
+  /**
+   * The route enforces both, and neither said so: the help read "Document
+   * processing recipe" / "Document language code" and the CLI uploaded the file
+   * before the server refused the value. Every other constrained flag in this
+   * CLI uses commander `choices`.
+   */
+  it('states what --recipe and --lang accept, and refuses a recipe before uploading', async () => {
+    const path = join(dir, 'notes.txt')
+    writeFileSync(path, 'hello')
+
+    const help = program()
+      .commands.find((command) => command.name() === 'knowledge')
+      ?.commands.find((command) => command.name() === 'documents')
+      ?.commands.find((command) => command.name() === 'upload')
+      ?.helpInformation()
+      .replace(/\s+/g, ' ')
+    expect(help).toContain('choices: "default", "plain", "markdown", "code"')
+    expect(help).toContain('hyphen-separated letter and digit subtags')
+
+    await expect(
+      program().parseAsync([
+        'node',
+        'sim',
+        'kb',
+        'documents',
+        'upload',
+        'kb_1',
+        path,
+        '--recipe',
+        'super-chunker-9000',
+      ])
+    ).rejects.toThrow(/Allowed choices are default, plain, markdown, code/)
+    expect(mockRequest).not.toHaveBeenCalled()
+  })
+
   it('requires the knowledge-base argument before reading the file', async () => {
     const path = join(dir, 'notes.txt')
     writeFileSync(path, 'hello')

packages/sim-cli/src/commands/protocol/knowledge-document-upload.ts

@@ -1,4 +1,4 @@
-import type { Command } from 'commander'
+import { type Command, Option } from 'commander'
 import { clientFrom } from '../../context'
 import type {
   CompleteKnowledgeDocumentUploadResponse,
@@ -35,6 +35,21 @@ function uploadMetadata(options: KnowledgeDocumentUploadOptions): Record<string,
   return metadata
 }
 
+/**
+ * The recipes the route accepts. Stated as `choices` like every other
+ * constrained flag in this CLI, so `--help` lists them and a typo is refused
+ * before the file is uploaded rather than after.
+ */
+const UPLOAD_RECIPES = ['default', 'plain', 'markdown', 'code'] as const
+
+/**
+ * The route enforces a shape, not BCP-47 conformance, so the help says the
+ * shape and nothing more; a full parser is the route's own deliberate
+ * non-goal and reimplementing one here would refuse tags the server accepts.
+ */
+const LANGUAGE_TAG_HELP =
+  'Document language tag: hyphen-separated letter and digit subtags, for example en or en-US'
+
 export function attachKnowledgeDocumentUpload(documents: Command): void {
   documents
     .command('upload')
@@ -44,8 +59,8 @@ export function attachKnowledgeDocumentUpload(documents: Command): void {
     .description('Upload a document to a knowledge base')
     .option('--name <name>', 'Store it under a different name')
     .option('--tag <value...>', 'Document tags, in tag1 through tag7 order')
-    .option('--recipe <name>', 'Document processing recipe')
-    .option('--lang <code>', 'Document language code')
+    .addOption(new Option('--recipe <name>', 'Document processing recipe').choices(UPLOAD_RECIPES))
+    .option('--lang <code>', LANGUAGE_TAG_HELP)
     .action(
       async (
         knowledgeBaseId: string,

packages/sim-cli/src/commands/protocol/logs-follow.test.ts

@@ -454,7 +454,7 @@ describe('sim logs follow', () => {
   it('rejects a backlog count that is not a whole number of runs', async () => {
     respondWith([])
 
-    await expect(follow('-n', '-1')).rejects.toThrow('--lines must be a non-negative integer')
+    await expect(follow('-n', '-1')).rejects.toThrow('--lines must be a whole number of 0 or more')
     expect(mockRequest).not.toHaveBeenCalled()
   })
 
@@ -517,4 +517,27 @@ describe('sim logs follow', () => {
       expect(ms).toBeGreaterThan(0)
     }
   })
+  /**
+   * Root help states that a `wf_` prefix marks a FILE id and "never names a
+   * workflow", so the example told the reader to pass a file id to
+   * `--workflow`. Workflow ids are bare UUIDs.
+   */
+  it('does not illustrate --workflow with a file-id prefix', () => {
+    const root = new Command('sim').exitOverride()
+    const logs = new Command('logs').exitOverride()
+    root.addCommand(logs)
+    attachLogsFollow(logs)
+    // `helpInformation()` omits `addHelpText('after')`, which is where the
+    // examples live, so the help is captured as the command would print it.
+    let help = ''
+    logs.commands[0].configureOutput({
+      writeOut: (text) => {
+        help += text
+      },
+    })
+    logs.commands[0].outputHelp()
+
+    expect(help).not.toContain('wf_')
+    expect(help).toMatch(/--workflow [0-9a-f]{8}-[0-9a-f]{4}-/)
+  })
 })

packages/sim-cli/src/commands/protocol/logs-follow.ts

@@ -467,7 +467,7 @@ function isTransient(error: unknown): boolean {
 function nonNegativeInteger(raw: string, flag: string): number {
   const value = Number(raw)
   if (!Number.isSafeInteger(value) || value < 0) {
-    throw new SimApiError(`${flag} must be a non-negative integer`, 0)
+    throw new SimApiError(`${flag} must be a whole number of 0 or more`, 0)
   }
   return value
 }
@@ -531,7 +531,7 @@ follow.
 
 Examples:
   $ sim logs follow --level error
-  $ sim logs follow --workflow wf_123 -n 0
+  $ sim logs follow --workflow 00000000-0000-4000-8000-000000000000 -n 0
   $ sim --output json logs follow | jq -r '.runId'
 `
     )

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

@@ -216,6 +216,42 @@ describe('resource directory', () => {
     expect(entries.find((entry) => entry.kind === 'table')?.ref).toBe('tbl_1')
   })
 
+  /**
+   * `files list` announces "showing the first N" off the surviving cursor and
+   * `ls` printed the same capped answer with nothing on stderr, so one command
+   * presented an incomplete listing as complete and its neighbour did not.
+   */
+  it('says the combined listing was capped, as the contract-driven list does', async () => {
+    mockRequest.mockImplementation(
+      async (path: string, options: { query: { cursor?: string } }) => {
+        if (path === '/api/v2/files/folders') return { data: [] }
+        const cursor = Number(options.query.cursor ?? 0)
+        return {
+          data: Array.from({ length: 100 }, (_, index) => ({
+            id: `file_${cursor}_${index}`,
+            name: `file-${cursor}-${index}`,
+            folderPath: '/',
+            updatedAt: '2026-01-01T00:00:00.000Z',
+          })),
+          nextCursor: cursor < 2 ? String(cursor + 1) : null,
+        }
+      }
+    )
+    const written: string[] = []
+    vi.spyOn(process.stderr, 'write').mockImplementation((chunk: string | Uint8Array) => {
+      written.push(String(chunk))
+      return true
+    })
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    await program().parseAsync(['node', 'sim', 'files', 'ls', '--limit', '5'])
+    expect(written.join('')).toContain('showing the first 5')
+
+    written.length = 0
+    await program().parseAsync(['node', 'sim', 'files', 'ls', '--limit', '0'])
+    expect(written.join('')).not.toContain('showing the first')
+  })
+
   it('rejects extra directory arguments instead of silently ignoring them', async () => {
     await expect(
       program().parseAsync(['node', 'sim', 'file', 'ls', 'Reports', 'ignored'])

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

@@ -12,11 +12,11 @@ import {
   V2_OPERATIONS,
   type V2OperationName,
 } from '../../generated/v2-api'
-import { requestAllPages, SimApiError, type SimClient, type V2Page } from '../../http/client'
+import { requestPages, SimApiError, type SimClient, type V2Page } from '../../http/client'
 import { type Column, printList, text, timestamp } from '../../output/render'
 import { DEFAULT_LIMIT } from '../../runtime/options'
 import { encodeFolderPath } from '../../runtime/request'
-import { decodeFolderPath, renderResult } from '../../runtime/result'
+import { decodeFolderPath, renderResult, writeCursorTruncation } from '../../runtime/result'
 
 type FolderListOperation =
   | 'listFileFolders'
@@ -103,17 +103,17 @@ async function listResources(
   folderPath: string,
   search: string | undefined,
   limit: number
-): Promise<DirectoryResource[]> {
+): Promise<{ items: DirectoryResource[]; truncated: boolean }> {
   const query = { workspaceId, folderPath, search, sortBy: 'name', sortOrder: 'asc' }
   const path = operationPath(config.resources)
   const paginated = 'cursor' in V2_OPERATIONS[config.resources].query
 
   if (!paginated) {
     const page = await client.request<V2Page<DirectoryResource>>(path, { query })
-    return page.data.slice(0, limit)
+    return { items: page.data.slice(0, limit), truncated: page.data.length > limit }
   }
 
-  return requestAllPages<DirectoryResource>(client, path, {
+  return requestPages<DirectoryResource>(client, path, {
     query,
     pageSize: DEFAULT_LIMIT,
     limit,
@@ -177,7 +177,7 @@ export function attachResourceDirectoryCommands(
     .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)
+        throw new SimApiError('--limit must be a whole number of 0 or more (0 for everything)', 0)
       }
 
       const limit = rawLimit === 0 ? Number.POSITIVE_INFINITY : rawLimit
@@ -191,8 +191,13 @@ export function attachResourceDirectoryCommands(
         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)
+      const entries = entriesFor(config, folders, resources.items)
+      const shown = entries.slice(0, limit)
+      // Said here for the same reason the contract-driven `list` says it: the
+      // combined listing is capped after the merge, so a full page of folders
+      // can clip the resources even when the resource walk itself finished.
+      writeCursorTruncation(shown.length, resources.truncated || entries.length > limit)
+      printList(profile.output, shown, COLUMNS)
     })
 
   group