fix(cli): show the -- escape for an id that opens with a dash

Short ids draw from a 64-character alphabet containing one dash, so 1 in 64 open
with one and commander reads it as an unknown option. It reaches `audit-logs
get` and the custom-tool commands, and the escape was documented nowhere.

The hint is appended only for a lone dash followed by two or more characters
carrying an uppercase letter or digit — a shape no flag on this surface has — so
a misspelt flag keeps commander's own suggestion.

Author: waleedlatif1

packages/sim-cli/src/program.ts

@@ -21,7 +21,9 @@ Profiles work like the AWS CLI: settings live in ~/.sim/config, keys in
 with -P, --profile, or SIM_PROFILE.
 
 Workflow, knowledge-base and workspace IDs are bare UUIDs. Table IDs carry a
-tbl_ prefix and file IDs a wf_ one, so wf_ never names a workflow.
+tbl_ prefix and file IDs a wf_ one, so wf_ never names a workflow. An audit-log
+or custom-tool ID can open with a dash, which reads as a flag; put -- in front
+of it, as in sim audit-logs get -- -HlDcD1z76nK6R4crsUp0.
 
 Examples:
   $ sim login                          Authorize the default profile

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

@@ -326,6 +326,52 @@ describe('commands parsed through commander', () => {
     expect(errorOutput).not.toContain('--skillId')
   })
 
+  it('shows the -- escape when an id argument opens with a dash', async () => {
+    const root = program()
+    const auditLogs = root.commands.find((command) => command.name() === 'audit-logs')
+    const get = auditLogs?.commands.find((command) => command.name() === 'get')
+    if (!get) throw new Error('Missing command audit-logs get')
+
+    let errorOutput = ''
+    get.configureOutput({
+      writeErr: (message) => {
+        errorOutput += message
+      },
+    })
+
+    await expect(
+      root.parseAsync(['node', 'sim', 'audit-logs', 'get', '-HlDcD1z76nK6R4crsUp0'])
+    ).rejects.toMatchObject({ code: 'commander.unknownOption' })
+    expect(errorOutput).toContain("error: unknown option '-HlDcD1z76nK6R4crsUp0'")
+    expect(errorOutput).toContain('Example: sim audit-logs get -- -HlDcD1z76nK6R4crsUp0')
+  })
+
+  it("leaves a misspelt flag with commander's own suggestion", async () => {
+    const root = program()
+    const auditLogs = root.commands.find((command) => command.name() === 'audit-logs')
+    const get = auditLogs?.commands.find((command) => command.name() === 'get')
+    if (!get) throw new Error('Missing command audit-logs get')
+
+    let errorOutput = ''
+    get.configureOutput({
+      writeErr: (message) => {
+        errorOutput += message
+      },
+    })
+
+    await expect(
+      root.parseAsync(['node', 'sim', 'audit-logs', 'get', 'log_1', '--organisation'])
+    ).rejects.toMatchObject({ code: 'commander.unknownOption' })
+    expect(errorOutput).toContain("error: unknown option '--organisation'")
+    expect(errorOutput).not.toContain('Example:')
+
+    await expect(
+      root.parseAsync(['node', 'sim', 'audit-logs', 'get', 'log_1', '-organisation'])
+    ).rejects.toMatchObject({ code: 'commander.unknownOption' })
+    expect(errorOutput).toContain("error: unknown option '-organisation'")
+    expect(errorOutput).not.toContain('Example:')
+  })
+
   it('dispatches generated commands through their singular resource alias', async () => {
     const [tablePath] = await run(['table', 'list'])
     expect(tablePath).toBe('/api/v2/tables')

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

@@ -64,18 +64,55 @@ function commandPath(command: Command): string {
   return names.join(' ')
 }
 
-function addMissingArgumentExample(command: Command): Command {
+const UNKNOWN_OPTION_TOKEN = /^error: unknown option '(.+?)'/
+
+/**
+ * Whether an unknown-option token reads as a resource id rather than a flag.
+ *
+ * `generateShortId` draws from a 64-character alphabet holding exactly one
+ * `-`, so one id in 64 opens with a dash and commander parses it as an option
+ * instead of the positional it was typed as — `audit-logs get` and
+ * `custom-tools get/update/delete` all take such an id. A flag on this surface
+ * is either a single-character short (`-w`) or a lowercase kebab-case long
+ * (`--dry-run`), so a lone dash followed by two or more characters of which at
+ * least one is an uppercase letter or a digit is not a flag any caller meant
+ * to type. `--organisation` and every other misspelt flag keeps the plain
+ * error and commander's own suggestion.
+ */
+function looksLikeAnId(token: string): boolean {
+  return (
+    token.length > 2 &&
+    !token.startsWith('--') &&
+    /^-[A-Za-z0-9_-]*[A-Z0-9][A-Za-z0-9_-]*$/.test(token)
+  )
+}
+
+/**
+ * Appends a worked example to the parse errors a positional argument causes.
+ *
+ * Covers the argument being absent and the argument being swallowed as an
+ * option because its id opens with a dash; the second needs the `--` escape,
+ * which commander never mentions.
+ */
+function addArgumentExamples(command: Command): Command {
   const outputError = command.configureOutput().outputError
   if (!outputError) throw new Error('Commander output formatter is not configured')
 
   command.configureOutput({
     outputError: (message, write) => {
       outputError(message, write)
-      if (!message.startsWith('error: missing required argument ')) return
 
-      const syntax = argumentSyntax(command)
-      const example = syntax ? `${commandPath(command)} ${syntax}` : commandPath(command)
-      write(`Example: ${example}\n`)
+      if (message.startsWith('error: missing required argument ')) {
+        const syntax = argumentSyntax(command)
+        const example = syntax ? `${commandPath(command)} ${syntax}` : commandPath(command)
+        write(`Example: ${example}\n`)
+        return
+      }
+
+      if (command.registeredArguments.length === 0) return
+      const token = UNKNOWN_OPTION_TOKEN.exec(message)?.[1]
+      if (!token || !looksLikeAnId(token)) return
+      write(`Example: ${commandPath(command)} -- ${token}\n`)
     },
   })
   return command
@@ -298,7 +335,7 @@ function configureOperation(
 }
 
 function buildLeaf(operation: V2OperationName, spec: CommandSpec, leafName: string): Command {
-  return addMissingArgumentExample(configureOperation(new Command(leafName), operation, spec))
+  return addArgumentExamples(configureOperation(new Command(leafName), operation, spec))
 }
 
 /**