fix(wrap): bypass commander for argv parsing, give clear error on '--<cmd>'

Reproduces the user-reported bug:

  $ stackguard wrap --claude "test"
  ✓ stackguard: ok
  stackguard wrap: failed to spawn --claude: spawn --claude ENOENT

Root cause: commander's option parser fights with pass-through args
to a wrapped CLI. With allowUnknownOption(true), an invocation like
'stackguard wrap --claude "test"' (no '--' separator) gets '--claude'
deposited into cmd.args[0], which the wrap code then blindly spawned.
The check itself worked — only the spawn step was wrong.

Fix:
- Intercept 'wrap' at the top of index.ts BEFORE commander parses
  anything. Wrap parses its own argv tail via a new pure helper
  parseWrapArgs(argv) that handles --policy, --mode, --help, and
  the optional '--' separator.
- The first non-option token starts the pass-through; everything
  from there forward is forwarded verbatim to the wrapped CLI,
  including option-looking flags like '--some-claude-flag'.
- If the resolved command starts with '-', refuse it with a
  pointed error: "command must not start with '-' (got '--claude').
  Did you forget the '--' separator? Try: stackguard wrap -- claude ..."
- Both 'wrap claude "x"' and 'wrap -- claude "x"' now work; the
  former just for ergonomics.
- The 'wrap' command is still registered with commander as a stub
  so it shows up in --help, but the action handler is unreachable.

Adds 16 unit tests in tests/wrap.test.ts covering: clean parse,
explicit separator, --policy/--mode positions, pass-through of
unknown flags after the command, the bug-reproduction case, empty
argv, missing --policy value, invalid --mode, and --help.

Manually verified against the original failing input and against
'stackguard wrap --policy ./examples/policy.example.md -- echo hello'.

Author: Srikanth-AD

src/commands/wrap.ts

@@ -13,6 +13,111 @@ interface WrapOptions {
   mode?: string
 }
 
+export interface ParsedWrapInvocation {
+  policy?: string
+  mode?: 'warn' | 'block'
+  help: boolean
+  args: string[]
+  error?: string
+}
+
+/**
+ * Parse the argv tail that follows `stackguard wrap`. We do this ourselves
+ * instead of letting commander handle it because commander's option parser
+ * fights with pass-through arguments — `--claude` would be eaten as an
+ * unknown option even with allowUnknownOption(true), and post-`--` args
+ * land in inconsistent places across commander versions.
+ *
+ * Accepted shapes:
+ *   stackguard wrap claude "prompt"
+ *   stackguard wrap -- claude "prompt"
+ *   stackguard wrap --policy ./p.md -- claude "prompt"
+ *   stackguard wrap --mode block -- claude --some-flag "prompt"
+ *
+ * Returns an `error` string when the input is unusable.
+ */
+export function parseWrapArgs(argv: string[]): ParsedWrapInvocation {
+  const result: ParsedWrapInvocation = { help: false, args: [] }
+  let i = 0
+  let sawSeparator = false
+
+  while (i < argv.length) {
+    const a = argv[i]
+
+    if (sawSeparator) {
+      result.args.push(a)
+      i++
+      continue
+    }
+
+    if (a === '--') {
+      sawSeparator = true
+      i++
+      continue
+    }
+
+    if (a === '--help' || a === '-h') {
+      result.help = true
+      i++
+      continue
+    }
+
+    if (a === '--policy') {
+      const next = argv[i + 1]
+      if (!next || next.startsWith('-')) {
+        result.error = '--policy requires a path argument'
+        return result
+      }
+      result.policy = next
+      i += 2
+      continue
+    }
+
+    if (a === '--mode') {
+      const next = argv[i + 1]
+      if (next !== 'warn' && next !== 'block') {
+        result.error = "--mode must be 'warn' or 'block'"
+        return result
+      }
+      result.mode = next
+      i += 2
+      continue
+    }
+
+    // First non-option token is the start of the wrapped command. Everything
+    // from here on is pass-through, even option-looking tokens.
+    sawSeparator = true
+    result.args.push(a)
+    i++
+  }
+
+  if (result.help) return result
+
+  if (result.args.length === 0) {
+    result.error = 'no command specified — usage: stackguard wrap -- <command> [args...]'
+    return result
+  }
+
+  if (result.args[0].startsWith('-')) {
+    result.error = `command must not start with '-' (got '${result.args[0]}'). Did you forget the '--' separator? Try: stackguard wrap -- ${result.args[0].replace(/^-+/, '')} ...`
+    return result
+  }
+
+  return result
+}
+
+const WRAP_HELP = `Usage: stackguard wrap [--policy <path>] [--mode warn|block] -- <command> [args...]
+
+Wrap an AI assistant CLI with stackguard checking. Everything after
+the '--' separator is forwarded to the wrapped command. The last
+non-flag argument is treated as the prompt to check.
+
+Examples:
+  stackguard wrap -- claude "add a database connection"
+  stackguard wrap -- cursor agent "refactor this file"
+  stackguard wrap --mode block -- claude "implement token signing"
+`
+
 function findPromptArgIndex(args: string[]): number {
   for (let i = args.length - 1; i >= 0; i--) {
     const a = args[i]
@@ -56,15 +161,49 @@ function execChild(command: string, args: string[]): void {
   })
 }
 
+/**
+ * Top-level entry point used by index.ts. Parses argv directly, prints help
+ * or errors as needed, and delegates to runWrap on success.
+ */
+export async function wrapEntrypoint(argv: string[]): Promise<void> {
+  const parsed = parseWrapArgs(argv)
+
+  if (parsed.help) {
+    console.log(WRAP_HELP)
+    process.exit(0)
+  }
+
+  if (parsed.error) {
+    console.error(chalk.red(`✗ stackguard wrap: ${parsed.error}`))
+    console.error('')
+    console.error(WRAP_HELP)
+    process.exit(1)
+  }
+
+  await wrapCommand(parsed.args, { policy: parsed.policy, mode: parsed.mode })
+}
+
 export async function wrapCommand(rawArgs: string[], options: WrapOptions): Promise<void> {
   if (rawArgs.length === 0) {
-    console.error(chalk.red('✗ stackguard wrap: no command specified after --'))
+    console.error(chalk.red('✗ stackguard wrap: no command specified'))
+    console.error('')
+    console.error(WRAP_HELP)
     process.exit(1)
   }
 
   const command = rawArgs[0]
   const args = rawArgs.slice(1)
 
+  if (command.startsWith('-')) {
+    // Defense in depth — parseWrapArgs should have caught this already.
+    console.error(
+      chalk.red(`✗ stackguard wrap: command must not start with '-' (got '${command}')`)
+    )
+    console.error('')
+    console.error(WRAP_HELP)
+    process.exit(1)
+  }
+
   // Identify prompt
   const promptIdx = findPromptArgIndex(args)
   let prompt: string | null = null

src/index.ts

@@ -3,94 +3,99 @@ import { auditCommand } from './commands/audit.js'
 import { checkCommand } from './commands/check.js'
 import { initCommand } from './commands/init.js'
 import { policyCommand } from './commands/policy.js'
-import { wrapCommand } from './commands/wrap.js'
+import { wrapEntrypoint } from './commands/wrap.js'
 
-const program = new Command()
+// Special-case `wrap` BEFORE commander parses anything. Commander's option
+// parser doesn't play nicely with pass-through arguments to a wrapped CLI —
+// unknown options like `--claude` get eaten and end up in the wrong place.
+// Wrap parses its own argv tail; everything else goes through commander.
+if (process.argv[2] === 'wrap') {
+  wrapEntrypoint(process.argv.slice(3)).catch((err) => {
+    console.error((err as Error).message ?? err)
+    process.exit(1)
+  })
+} else {
+  const program = new Command()
 
-program
-  .name('stackguard')
-  .description('Pre-prompt policy enforcement for AI coding assistants')
-  .version('0.1.0')
-  .option('--policy <path>', 'path to policy file (overrides config)')
-  .option('--mode <mode>', 'warn or block (overrides config)')
+  program
+    .name('stackguard')
+    .description('Pre-prompt policy enforcement for AI coding assistants')
+    .version('0.1.0')
+    .option('--policy <path>', 'path to policy file (overrides config)')
+    .option('--mode <mode>', 'warn or block (overrides config)')
 
-program
-  .command('init')
-  .description('Set up stackguard.json in the current directory')
-  .action(async () => {
-    try {
-      await initCommand()
-    } catch (err) {
-      console.error((err as Error).message)
-      process.exit(1)
-    }
-  })
+  program
+    .command('init')
+    .description('Set up stackguard.json in the current directory')
+    .action(async () => {
+      try {
+        await initCommand()
+      } catch (err) {
+        console.error((err as Error).message)
+        process.exit(1)
+      }
+    })
 
-program
-  .command('check <prompt>')
-  .description('Check a prompt against the policy')
-  .option('--policy <path>', 'override policySource from config')
-  .option('--mode <mode>', 'override mode from config')
-  .option('--json', 'output JSON result, no interactive UI')
-  .option('--show-hash', 'print policy hash and exit')
-  .action(async (prompt: string, opts: any) => {
-    try {
-      const merged = { ...program.opts(), ...opts }
-      await checkCommand(prompt, merged)
-    } catch (err) {
-      console.error((err as Error).message)
-      process.exit(1)
-    }
-  })
+  program
+    .command('check <prompt>')
+    .description('Check a prompt against the policy')
+    .option('--policy <path>', 'override policySource from config')
+    .option('--mode <mode>', 'override mode from config')
+    .option('--json', 'output JSON result, no interactive UI')
+    .option('--show-hash', 'print policy hash and exit')
+    .action(async (prompt: string, opts: any) => {
+      try {
+        const merged = { ...program.opts(), ...opts }
+        await checkCommand(prompt, merged)
+      } catch (err) {
+        console.error((err as Error).message)
+        process.exit(1)
+      }
+    })
 
-program
-  .command('wrap')
-  .description('Wrap an AI assistant command with stackguard checking')
-  .option('--policy <path>', 'override policySource from config')
-  .option('--mode <mode>', 'override mode from config')
-  .allowUnknownOption(true)
-  .helpOption(false)
-  .action(async (opts: any, cmd: any) => {
-    try {
-      // Everything after `--` is in cmd.args
-      const args: string[] = cmd.args || []
-      const merged = { ...program.opts(), ...opts }
-      await wrapCommand(args, merged)
-    } catch (err) {
-      console.error((err as Error).message)
-      process.exit(1)
-    }
-  })
+  // Note: 'wrap' is intentionally NOT registered with commander. It's
+  // intercepted at the top of this file because commander's option parser
+  // mangles pass-through arguments. We register a stub command here only
+  // so it shows up in `--help`.
+  program
+    .command('wrap')
+    .description('Wrap an AI assistant command (use: stackguard wrap -- <cmd> [args...])')
+    .allowUnknownOption(true)
+    .helpOption(false)
+    .action(() => {
+      // Unreachable — handled at top of file.
+    })
 
-program
-  .command('audit')
-  .description('Show the override audit log')
-  .option('--days <n>', 'only show entries within the last N days')
-  .option('--user <name>', 'filter by user')
-  .option('--json', 'output as JSON')
-  .action(async (opts: any) => {
-    try {
-      await auditCommand(opts)
-    } catch (err) {
-      console.error((err as Error).message)
-      process.exit(1)
-    }
-  })
+  program
+    .command('audit')
+    .description('Show the override audit log')
+    .option('--days <n>', 'only show entries within the last N days')
+    .option('--user <name>', 'filter by user')
+    .option('--json', 'output as JSON')
+    .action(async (opts: any) => {
+      try {
+        await auditCommand(opts)
+      } catch (err) {
+        console.error((err as Error).message)
+        process.exit(1)
+      }
+    })
 
-program
-  .command('policy <subcommand>')
-  .description('Inspect the active policy (show | hash | source)')
-  .action(async (subcommand: string) => {
-    try {
-      const merged = { ...program.opts() }
-      await policyCommand(subcommand, merged)
-    } catch (err) {
-      console.error((err as Error).message)
-      process.exit(1)
-    }
-  })
+  program
+    .command('policy <subcommand>')
+    .description('Inspect the active policy (show | hash | source)')
+    .action(async (subcommand: string) => {
+      try {
+        const merged = { ...program.opts() }
+        await policyCommand(subcommand, merged)
+      } catch (err) {
+        console.error((err as Error).message)
+        process.exit(1)
+      }
+    })
 
-program.parseAsync(process.argv).catch((err) => {
-  console.error(err)
-  process.exit(1)
-})
+  program.parseAsync(process.argv).catch((err) => {
+    console.error(err)
+    process.exit(1)
+  })
+}