fix(sim-cli): the command inventory describes the operation each command runs (#8874)

The inventory mapped paths back to operations by re-deriving every route, so an operation whose derived path equals a sibling's (undeployWorkflow derives `workflows deploy`) overwrote it. Generated commands now record the operation they run and the inventory reads it.

Author: waleedlatif1

packages/sim-cli/scripts/print-command-inventory.ts

@@ -22,8 +22,8 @@ import {
 } from '#sim-cli/contract/reference'
 import { V2_OPERATIONS, type V2OperationName } from '#sim-cli/generated/v2-api'
 import { buildProgram } from '#sim-cli/program'
-import { calledOperations } from '#sim-cli/runtime/called-operations'
-import { camel, deriveCommandPath } from '#sim-cli/runtime/derive'
+import { calledOperations, operationOf } from '#sim-cli/runtime/called-operations'
+import { camel } from '#sim-cli/runtime/derive'
 import { cursorSlot, flagNameFor } from '#sim-cli/runtime/request'
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..')
@@ -76,21 +76,6 @@ function collectLeaves(command: Command, prefix: string[]): { path: string[]; co
   return children.flatMap((child) => collectLeaves(child, [...prefix, child.name()]))
 }
 
-/**
- * Command path → v2 operation name. Every operation names its command the way the
- * program builder does (`deriveCommandPath`); a contract entry's explicit `command`
- * string overrides that, exactly as it does when the program is built.
- */
-const OPERATION_BY_PATH = new Map<string, V2OperationName>()
-const operations = Object.keys(V2_OPERATIONS) as V2OperationName[]
-for (const operation of operations) {
-  OPERATION_BY_PATH.set(deriveCommandPath(operation).join(' '), operation)
-}
-for (const operation of operations) {
-  const command = CLI_CONTRACT[operation]?.command
-  if (command) OPERATION_BY_PATH.set(command, operation)
-}
-
 const OPENAPI_DOCS: ReferenceDocument[] = fs
   .readdirSync(path.join(ROOT, 'apps/docs'))
   .filter((name) => /^openapi-v2-.*\.json$/.test(name))
@@ -138,7 +123,7 @@ const inventory: InventoryCommand[] = collectLeaves(program, []).map(
         ...(option.defaultValue !== undefined ? { defaultValue: String(option.defaultValue) } : {}),
         ...(option.argChoices ? { choices: option.argChoices } : {}),
       }))
-    const operation = OPERATION_BY_PATH.get(cmdPath.join(' '))
+    const operation = operationOf(command)
     const jsonOptions = new Set(
       options.filter((option) => /<json\|@file>/.test(option.flags)).map((option) => option.name)
     )

packages/sim-cli/src/commands/credentials.ts

@@ -9,6 +9,7 @@ import {
 } from '../generated/v2-api'
 import { SimApiError } from '../http/client'
 import { describeOperation } from '../runtime/build'
+import { callsOperations, runsOperation } from '../runtime/called-operations'
 import { coerce } from '../runtime/request'
 import { renderResult } from '../runtime/result'
 
@@ -193,7 +194,7 @@ export function attachCredentialCommands(program: Command): void {
 
   acceptNameOnUpdate(credentials)
 
-  credentials
+  const create = credentials
     .command('create')
     .argument('<providerId>', 'Service-account provider to create a credential for')
     .description(
@@ -219,6 +220,8 @@ export function attachCredentialCommands(program: Command): void {
     .action((providerId: string, options: CreateServiceAccountOptions, command: Command) =>
       createServiceAccount(command, providerId, options)
     )
+  callsOperations(create, ['listCredentialProviders', 'createServiceAccountCredential'])
+  runsOperation(create, 'createServiceAccountCredential')
 
   credentials
     .command('connect')

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

@@ -337,7 +337,7 @@ async function downloadToOutput(
 }
 
 export function attachFileGet(files: Command): void {
-  files
+  const get = files
     .command('get')
     .argument('<fileId>', 'File whose content to read')
     .allowExcessArguments(false)
@@ -347,6 +347,7 @@ export function attachFileGet(files: Command): void {
     .action((fileId: string, options: DownloadOutputOptions, command: Command) =>
       downloadToOutput(command, V2_OPERATIONS.downloadFile, { fileId }, options)
     )
+  callsOperations(get, ['downloadFile'])
 }
 
 export function attachFileVersionDownload(versions: Command): void {

packages/sim-cli/src/commands/protocol/knowledge-export.ts

@@ -4,6 +4,7 @@ import { clientFrom } from '../../context'
 import { embedStore } from '../../embed-context'
 import { V2_OPERATIONS } from '../../generated/v2-api'
 import { resolvePath, SimApiError } from '../../http/client'
+import { callsOperations } from '../../runtime/called-operations'
 import { isTerminalSafeContentType, saveToFile, streamToStdout } from './files-get'
 import { printProtocolResult } from './result'
 
@@ -44,7 +45,7 @@ function safeBaseName(name: string): string | null {
 }
 
 export function attachKnowledgeExport(knowledge: Command): void {
-  knowledge
+  const exportCommand = knowledge
     .command('export')
     .argument('<knowledgeBaseId>', 'Knowledge base to export')
     .allowExcessArguments(false)
@@ -106,4 +107,5 @@ export function attachKnowledgeExport(knowledge: Command): void {
         vectors: options.vectors,
       })
     })
+  callsOperations(exportCommand, ['exportKnowledgeBase'])
 }

packages/sim-cli/src/contract/reference.test.ts

@@ -12,19 +12,24 @@ import { cursorSlot } from '#sim-cli/runtime/request'
 
 const ROOT = fileURLToPath(new URL('../../../../', import.meta.url))
 
-/** Read the actual producer, including command aliases and generated API documents. */
-function inventory(): {
+interface InventoryEntry {
   path: string[]
   shape?: string
   body?: string
   mothershipUnavailable?: true
-}[] {
-  return JSON.parse(
+}
+
+let produced: InventoryEntry[] | undefined
+
+/** Read the actual producer, including command aliases and generated API documents. */
+function inventory(): InventoryEntry[] {
+  produced ??= JSON.parse(
     execFileSync('bun', ['run', 'packages/sim-cli/scripts/print-command-inventory.ts'], {
       cwd: ROOT,
       encoding: 'utf8',
     })
-  )
+  ) as InventoryEntry[]
+  return produced
 }
 
 function document(schema: ReferenceSchema): ReferenceDocument {
@@ -51,6 +56,7 @@ describe('CLI reference producer', () => {
     }
     expect(find('tables create').shape).toContain('id:string')
     expect(find('workflows create').shape).toContain('blocks:')
+    expect(find('credentials create').shape).toContain('id:string')
     const rows = find('tables rows create')
     expect(rows.body).toBe('{rows:object[]}|{data:object}')
     expect(rows.shape).toContain('id:string')
@@ -67,6 +73,21 @@ describe('CLI reference producer', () => {
     expect(find('files share get').shape).toContain('|{data:null}')
   })
 
+  it('describes each command by the operation it runs, not one whose route derives the same name', () => {
+    // `undeployWorkflow`, `deleteTableRows` and `deleteKnowledgeTagDefinitions` derive the
+    // path their sibling owns; a lookup by path described the sibling with their output.
+    const commands = inventory()
+    const shape = (path: string) => commands.find((entry) => entry.path.join(' ') === path)?.shape
+    expect(shape('workflows deploy')).toContain('lint:')
+    expect(shape('workflows deploy')).not.toContain('archivedMcpTools')
+    expect(shape('workflows undeploy')).toContain('archivedMcpTools')
+    expect(shape('tables rows delete')).toContain('deleted:true')
+    expect(shape('tables rows batch-delete')).toContain('deletedCount:')
+    expect(shape('knowledge tags delete')).toContain('tagSlot:')
+    expect(shape('knowledge tags cleanup')).toContain('unused:')
+    expect(shape('workflows mv')).toContain('folderPath:')
+  })
+
   it('marks every command that calls a route Mothership is refused', () => {
     const commands = inventory()
     const flag = (path: string) =>

packages/sim-cli/src/runtime/build.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander'
 import { CLI_CONTRACT } from '../contract/commands'
 import type { CommandSpec, CommandVariantSpec } from '../contract/types'
 import { V2_OPERATIONS, type V2OperationName } from '../generated/v2-api'
+import { runsOperation } from './called-operations'
 import { deriveCommandPath } from './derive'
 import { executeOperation } from './execute'
 import { retypeApiError } from './naming'
@@ -248,6 +249,7 @@ function configureOperation(
   spec: CommandSpec
 ): Command {
   const operationSpec = V2_OPERATIONS[operation] as OperationSpec
+  runsOperation(command, operation)
   command.allowExcessArguments(false)
 
   for (const alias of spec.aliases ?? []) command.alias(alias)

packages/sim-cli/src/runtime/called-operations.ts

@@ -2,13 +2,31 @@ import type { Command } from 'commander'
 import type { V2OperationName } from '../generated/v2-api'
 
 const CALLED_OPERATIONS = new WeakMap<Command, readonly V2OperationName[]>()
+const RUNS_OPERATION = new WeakMap<Command, V2OperationName>()
+
+/**
+ * Records the one v2 operation whose request and response a command presents as its
+ * own: every generated command, and a hand-written one that prints a single call's result.
+ *
+ * The command inventory reads it here rather than mapping paths back to operations: a
+ * derived path can equal another operation's (`undeployWorkflow` derives
+ * `workflows deploy`), and a reverse lookup by path then describes the wrong one.
+ */
+export function runsOperation(command: Command, operation: V2OperationName): Command {
+  RUNS_OPERATION.set(command, operation)
+  return command
+}
+
+export function operationOf(command: Command): V2OperationName | undefined {
+  return RUNS_OPERATION.get(command)
+}
 
 /**
  * Records the v2 operations a hand-written command calls.
  *
- * A generated command is one operation and the command inventory finds it by path. A
- * hand-written one is opaque until it says what it calls, and the inventory needs that
- * to describe it truthfully, such as whether every call is open to a Mothership caller.
+ * A hand-written command is opaque until it says what it calls, and the inventory needs
+ * that to describe it truthfully, such as whether every call is open to a Mothership
+ * caller.
  */
 export function callsOperations(command: Command, operations: readonly V2OperationName[]): Command {
   CALLED_OPERATIONS.set(command, operations)