incur 0.4.7 → 0.4.9

package/src/Parser.ts

@@ -257,7 +257,7 @@ function setOption(
 }
 
 /** Wraps zod schema.parse(), converting ZodError to ValidationError. */
-function zodParse(schema: z.ZodObject<any>, data: Record<string, unknown>) {
+export function zodParse(schema: z.ZodObject<any>, data: Record<string, unknown>) {
   try {
     return schema.parse(data)
   } catch (err: any) {
@@ -330,6 +330,137 @@ function coerce(value: unknown, name: string, schema: z.ZodObject<any>): unknown
   return value
 }
 
+/** Parses known global options from argv, passing unknown flags and positionals through to `rest`. */
+export function parseGlobals<const globals extends z.ZodObject<any>>(
+  argv: string[],
+  schema: globals,
+  alias?: Record<string, string>,
+  options: parseGlobals.Options = {},
+): { parsed: z.output<globals>; rest: string[] } {
+  const optionNames = createOptionNames(schema, alias)
+
+  const rest: string[] = []
+  const rawOptions: Record<string, unknown> = {}
+
+  let i = 0
+  while (i < argv.length) {
+    const token = argv[i]!
+
+    if (token === '--') {
+      for (let j = i; j < argv.length; j++) rest.push(argv[j]!)
+      break
+    }
+
+    if (token.startsWith('--no-') && token.length > 5) {
+      const name = normalizeOptionName(token.slice(5), optionNames)
+      if (!name) {
+        rest.push(token)
+      } else {
+        rawOptions[name] = false
+      }
+      i++
+    } else if (token.startsWith('--')) {
+      const eqIdx = token.indexOf('=')
+      if (eqIdx !== -1) {
+        // --flag=value
+        const raw = token.slice(2, eqIdx)
+        const name = normalizeOptionName(raw, optionNames)
+        if (!name) {
+          rest.push(token)
+        } else {
+          setOption(rawOptions, name, token.slice(eqIdx + 1), schema)
+        }
+        i++
+      } else {
+        // --flag [value]
+        const name = normalizeOptionName(token.slice(2), optionNames)
+        if (!name) {
+          // Unknown flag — pass through as-is
+          rest.push(token)
+          i++
+        } else if (isCountOption(name, schema)) {
+          rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+          i++
+        } else if (isBooleanOption(name, schema)) {
+          rawOptions[name] = true
+          i++
+        } else {
+          const value = argv[i + 1]
+          if (value === undefined)
+            throw new ParseError({ message: `Missing value for flag: ${token}` })
+          setOption(rawOptions, name, value, schema)
+          i += 2
+        }
+      }
+    } else if (token.startsWith('-') && !token.startsWith('--') && token.length >= 2) {
+      // Short flag(s)
+      const chars = token.slice(1)
+      let allKnown = true
+      for (let j = 0; j < chars.length; j++) {
+        if (!optionNames.aliasToName.has(chars[j]!)) {
+          allKnown = false
+          break
+        }
+      }
+
+      if (!allKnown) {
+        // Unknown short flag — pass through as-is
+        rest.push(token)
+        i++
+      } else {
+        for (let j = 0; j < chars.length; j++) {
+          const short = chars[j]!
+          const name = optionNames.aliasToName.get(short)!
+          const isLast = j === chars.length - 1
+          if (!isLast) {
+            if (isCountOption(name, schema)) {
+              rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+            } else if (isBooleanOption(name, schema)) {
+              rawOptions[name] = true
+            } else {
+              throw new ParseError({
+                message: `Non-boolean flag -${short} must be last in a stacked alias`,
+              })
+            }
+          } else if (isCountOption(name, schema)) {
+            rawOptions[name] = ((rawOptions[name] as number) ?? 0) + 1
+          } else if (isBooleanOption(name, schema)) {
+            rawOptions[name] = true
+          } else {
+            const value = argv[i + 1]
+            if (value === undefined)
+              throw new ParseError({ message: `Missing value for flag: -${short}` })
+            setOption(rawOptions, name, value, schema)
+            i++
+          }
+        }
+        i++
+      }
+    } else {
+      // Positional — pass through
+      rest.push(token)
+      i++
+    }
+  }
+
+  if (options.validate === false) return { parsed: rawOptions as z.output<globals>, rest }
+
+  // Coerce raw option values before zod validation
+  for (const [name, value] of Object.entries(rawOptions))
+    rawOptions[name] = coerce(value, name, schema)
+
+  const parsed = zodParse(schema, rawOptions) as z.output<globals>
+  return { parsed, rest }
+}
+
+export declare namespace parseGlobals {
+  /** Options for parsing global flags. */
+  type Options = {
+    /** Whether to validate parsed globals against the schema. */
+    validate?: boolean | undefined
+  }
+}
+
 /** Returns the best available env source for the current runtime. */
 export function defaultEnvSource(): Record<string, string | undefined> {
   if (typeof globalThis !== 'undefined') {

package/src/Skill.test.ts

@@ -204,6 +204,12 @@ describe('hash', () => {
     expect(a).not.toBe(b)
   })
 
+  test('changes when hint changes', () => {
+    const a = Skill.hash([{ name: 'ping', hint: 'Read status.' }])
+    const b = Skill.hash([{ name: 'ping', hint: 'Delete status.' }])
+    expect(a).not.toBe(b)
+  })
+
   test('changes when schema changes', () => {
     const a = Skill.hash([{ name: 'greet', args: z.object({ name: z.string() }) }])
     const b = Skill.hash([{ name: 'greet', args: z.object({ name: z.string(), age: z.number() }) }])

package/src/Skill.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto'
-import { stringify as yamlStringify } from 'yaml'
 import type { z } from 'zod'
 
+import * as Yaml from './internal/yaml.js'
 import * as Schema from './Schema.js'
 
 /** Information about a single command, passed to `generate()`. */
@@ -137,10 +137,12 @@ function renderGroup(
     ? `${desc.replace(/\.$/, '')}. Run \`${title} --help\` for usage details.`
     : `Run \`${title} --help\` for usage details.`
 
-  const fm = yamlStringify(
-    { name: slugify(title), description, requires_bin: cli, command: title },
-    { lineWidth: 0 },
-  ).trimEnd()
+  const fm = Yaml.loadSync()
+    .stringify(
+      { name: slugify(title), description, requires_bin: cli, command: title },
+      { lineWidth: 0 },
+    )
+    .trimEnd()
   const fmBlock = `---\n${fm}\n---`
 
   const body = cmds.map((cmd) => renderCommandBody(cli, cmd)).join('\n\n---\n\n')
@@ -245,6 +247,7 @@ export function hash(commands: CommandInfo[]): string {
   const data = commands.map((cmd) => ({
     name: cmd.name,
     description: cmd.description,
+    hint: cmd.hint,
     args: cmd.args ? Schema.toJsonSchema(cmd.args) : undefined,
     env: cmd.env ? Schema.toJsonSchema(cmd.env) : undefined,
     options: cmd.options ? Schema.toJsonSchema(cmd.options) : undefined,

package/src/Skillgen.test.ts

@@ -60,13 +60,20 @@ test('collects group descriptions', async () => {
 test('includes args, options, and examples in output', async () => {
   const cli = Cli.create('tool', {
     description: 'A tool',
-  }).command('greet', {
-    description: 'Greet someone',
-    args: z.object({ name: z.string().describe('Name to greet') }),
-    options: z.object({ loud: z.boolean().default(false).describe('Shout') }),
-    examples: [{ args: { name: 'world' }, description: 'Greet the world' }],
-    run: () => ({}),
   })
+    .command('greet', {
+      description: 'Greet someone',
+      aliases: ['hi'],
+      args: z.object({ name: z.string().describe('Name to greet') }),
+      options: z.object({ loud: z.boolean().default(false).describe('Shout') }),
+      output: z.object({ message: z.string() }),
+      examples: [{ args: { name: 'world' }, description: 'Greet the world' }],
+      run: () => ({ message: 'hi' }),
+    })
+    .command('api', {
+      description: 'Proxy API',
+      fetch: () => new Response('{}'),
+    })
   vi.mocked(importCli).mockResolvedValue(cli)
 
   const files = await generate('fake-input', tmp, 0)
@@ -74,4 +81,46 @@ test('includes args, options, and examples in output', async () => {
   expect(content).toContain('Name to greet')
   expect(content).toContain('Shout')
   expect(content).toContain('Greet the world')
+  expect(content).toContain('## Output')
+  expect(content).toContain('Fetch gateway. Pass path segments')
+  expect(content).not.toContain('# tool hi')
+})
+
+test('appends confirmation hint for destructive commands', async () => {
+  const cli = Cli.create('tool')
+    .command('destroy', {
+      description: 'Destroy data',
+      destructive: true,
+      hint: 'Deletes all data.',
+      run: () => ({}),
+    })
+    .command('status', {
+      description: 'Check status',
+      hint: 'Shows current status.',
+      run: () => ({}),
+    })
+  vi.mocked(importCli).mockResolvedValue(cli)
+
+  const files = await generate('fake-input', tmp, 0)
+  const content = readFileSync(files[0]!, 'utf-8')
+  expect(content).toContain(
+    'Deletes all data. Confirm with the user before executing this destructive command.',
+  )
+  expect(content).toContain('Shows current status.')
+  expect(content).not.toContain(
+    'Shows current status. Confirm with the user before executing this destructive command.',
+  )
+})
+
+test('uses MCP destructiveHint when generating skill files', async () => {
+  const cli = Cli.create('tool').command('deploy', {
+    description: 'Deploy',
+    mcp: { annotations: { destructiveHint: true } },
+    run: () => ({}),
+  })
+  vi.mocked(importCli).mockResolvedValue(cli)
+
+  const files = await generate('fake-input', tmp, 0)
+  const content = readFileSync(files[0]!, 'utf-8')
+  expect(content).toContain('Confirm with the user before executing this destructive command.')
 })

package/src/Skillgen.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 
 import * as Cli from './Cli.js'
 import { importCli } from './internal/utils.js'
+import * as Yaml from './internal/yaml.js'
 import * as Skill from './Skill.js'
 
 /** Imports a CLI from `input`, generates Markdown skill files, and writes them to `output`. */
@@ -13,7 +14,14 @@ export async function generate(input: string, output: string, depth = 1): Promis
 
   const groups = new Map<string, string>()
   if (cli.description) groups.set(cli.name, cli.description)
-  const entries = collectEntries(commands, [], groups)
+  const entries = Cli.collectSkillCommands(
+    commands,
+    [],
+    groups,
+    Cli.toRootDefinition.get(cli as unknown as Cli.Root),
+  )
+  // Pre-load yaml for `Skill.split`'s sync call path.
+  await Yaml.load()
   const files = Skill.split(cli.name, entries, depth, groups)
 
   if (depth > 0) await fs.rm(output, { recursive: true, force: true })
@@ -30,37 +38,3 @@ export async function generate(input: string, output: string, depth = 1): Promis
 
   return written
 }
-
-/** Recursively collects leaf commands as `Skill.CommandInfo` and group descriptions. */
-function collectEntries(
-  commands: Map<string, any>,
-  prefix: string[],
-  groups: Map<string, string> = new Map(),
-): Skill.CommandInfo[] {
-  const result: Skill.CommandInfo[] = []
-  for (const [name, entry] of commands) {
-    const path = [...prefix, name]
-    if ('_group' in entry && entry._group) {
-      if (entry.description) groups.set(path.join(' '), entry.description)
-      result.push(...collectEntries(entry.commands, path, groups))
-    } else {
-      const cmd: Skill.CommandInfo = { name: path.join(' ') }
-      if (entry.description) cmd.description = entry.description
-      if (entry.args) cmd.args = entry.args
-      if (entry.env) cmd.env = entry.env
-      if (entry.hint) cmd.hint = entry.hint
-      if (entry.options) cmd.options = entry.options
-      if (entry.output) cmd.output = entry.output
-      const examples = Cli.formatExamples(entry.examples)
-      if (examples) {
-        const cmdName = path.join(' ')
-        cmd.examples = examples.map((e) => ({
-          ...e,
-          command: e.command ? `${cmdName} ${e.command}` : cmdName,
-        }))
-      }
-      result.push(cmd)
-    }
-  }
-  return result.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''))
-}

package/src/SyncMcp.test.ts

@@ -123,6 +123,95 @@ test('register with agents: ["amp"] skips add-mcp', async () => {
   expect(result.agents).toEqual(['Amp'])
 })
 
+test('register handles quoted command paths with spaces', async () => {
+  const { execFile } = await import('node:child_process')
+  vi.mocked(execFile).mockClear()
+
+  const result = await register('my-cli', {
+    command: '"/path/to my/cli" --mcp',
+    agents: ['amp'],
+  })
+
+  expect(result.agents).toEqual(['Amp'])
+
+  const configPath = join(fakeHome!, '.config', 'amp', 'settings.json')
+  const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+  expect(config['amp.mcpServers']['my-cli']).toEqual({
+    command: '/path/to my/cli',
+    args: ['--mcp'],
+  })
+})
+
+test('register uses bare name for global binary installs', async () => {
+  process.argv[1] = '/usr/local/bin/my-cli'
+
+  const { execFile } = await import('node:child_process')
+  vi.mocked(execFile).mockClear()
+
+  const result = await register('my-cli', { agents: ['amp'] })
+
+  expect(result.command).toBe('my-cli --mcp')
+
+  const configPath = join(fakeHome!, '.config', 'amp', 'settings.json')
+  const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+  expect(config['amp.mcpServers']['my-cli']).toEqual({
+    command: 'my-cli',
+    args: ['--mcp'],
+  })
+})
+
+test('register uses runner for source entrypoints outside node_modules', async () => {
+  process.argv[1] = join(tmp, 'dist', 'bin.js')
+
+  const { execFile } = await import('node:child_process')
+  vi.mocked(execFile).mockClear()
+
+  const result = await register('my-cli', { agents: ['amp'] })
+
+  expect(result.command).toMatch(/^(npx|pnpx|bunx)\s/)
+  expect(result.command).toContain('my-cli --mcp')
+})
+
+test('register uses bare name for global package entrypoints under node_modules', async () => {
+  process.argv[1] = join(tmp, 'global', 'node_modules', 'my-cli', 'dist', 'bin.js')
+
+  const { execFile } = await import('node:child_process')
+  vi.mocked(execFile).mockClear()
+
+  const result = await register('my-cli', { agents: ['amp'] })
+
+  expect(result.command).toBe('my-cli --mcp')
+})
+
+test('register uses runner for project dev dependency entrypoints under node_modules', async () => {
+  writeFileSync(
+    join(tmp, 'package.json'),
+    JSON.stringify({ devDependencies: { 'my-cli': '1.0.0' } }),
+  )
+  process.argv[1] = join(tmp, 'node_modules', 'my-cli', 'dist', 'bin.js')
+
+  const { execFile } = await import('node:child_process')
+  vi.mocked(execFile).mockClear()
+
+  const result = await register('my-cli', { agents: ['amp'] })
+
+  expect(result.command).toMatch(/^(npx|pnpx|bunx)\s/)
+  expect(result.command).toContain('my-cli --mcp')
+})
+
+test('register uses runner for node_modules installs', async () => {
+  process.argv[1] = join(tmp, 'node_modules', '.bin', 'my-cli')
+
+  const { execFile } = await import('node:child_process')
+  vi.mocked(execFile).mockClear()
+
+  const result = await register('my-cli', { agents: ['amp'] })
+
+  // Should include a runner prefix (npx, pnpx, or bunx)
+  expect(result.command).toMatch(/^(npx|pnpx|bunx)\s/)
+  expect(result.command).toContain('--mcp')
+})
+
 test('register writes amp config to existing settings', async () => {
   const configDir = join(fakeHome!, '.config', 'amp')
   mkdirSync(configDir, { recursive: true })

package/src/SyncMcp.ts

@@ -11,7 +11,7 @@ export async function register(
   options: register.Options = {},
 ): Promise<register.Result> {
   const runner = detectRunner()
-  const command = options.command ?? `${runner} ${detectPackageSpecifier(name)} --mcp`
+  const command = options.command ?? defaultCommand(name, runner)
   const targetAgents = options.agents ?? []
   const ampOnly = targetAgents.length === 1 && targetAgents[0] === 'amp'
 
@@ -64,7 +64,7 @@ function registerAmp(name: string, command: string): boolean {
     }
   }
 
-  const [cmd, ...args] = command.split(' ')
+  const [cmd, ...args] = splitCommand(command)
   if (!cmd) return false
 
   const servers: Record<string, any> = config['amp.mcpServers'] ?? {}
@@ -98,16 +98,56 @@ export declare namespace register {
   }
 }
 
-/** @internal Detects the package specifier used to run this CLI (handles dlx/npx URL and version installs). */
-export function detectPackageSpecifier(name: string): string {
+/** @internal Builds the default MCP command for the current launch mode. */
+function defaultCommand(name: string, runner: string): string {
+  return shouldUseBareCommand(name)
+    ? `${name} --mcp`
+    : `${runner} ${detectPackageSpecifier(name)} --mcp`
+}
+
+/** @internal Returns node_modules path details for the current entrypoint. */
+function nodeModulesInfo(): { entry: string; root: string } | null {
+  const normalized = process.argv[1]?.replace(/\\/g, '/')
+  const match = normalized?.match(/^(.+)\/node_modules\/(.+)$/)
+  if (!match) return null
+  return { root: match[1]!, entry: match[2]! }
+}
+
+/** @internal Uses the bare command only when the binary is expected on PATH. */
+function shouldUseBareCommand(name: string): boolean {
   const bin = process.argv[1]
-  if (!bin) return name
+  if (!bin) return false
+
+  const info = nodeModulesInfo()
+  if (info) return !info.entry.startsWith('.bin/') && !packageDependsOn(info.root, name)
 
-  const match = bin.match(/^(.+)[/\\]node_modules[/\\]/)
-  if (!match) return name
+  const file = bin.replace(/\\/g, '/').split('/').pop()
+  return file === name || file === `${name}.cmd` || file === `${name}.ps1`
+}
 
+/** @internal Checks whether the entrypoint came from a project dependency install. */
+function packageDependsOn(root: string, name: string): boolean {
   try {
-    const pkg = JSON.parse(readFileSync(join(match[1]!, 'package.json'), 'utf-8'))
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8'))
+    const dependencyFields = [
+      pkg.dependencies,
+      pkg.devDependencies,
+      pkg.optionalDependencies,
+      pkg.peerDependencies,
+    ]
+    return dependencyFields.some((dependencies) => name in (dependencies ?? {}))
+  } catch {
+    return false
+  }
+}
+
+/** @internal Detects the package specifier used to run this CLI (handles dlx/npx URL and version installs). */
+export function detectPackageSpecifier(name: string): string {
+  const info = nodeModulesInfo()
+  if (!info) return name
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(info.root, 'package.json'), 'utf-8'))
     const deps = pkg.dependencies ?? {}
     const spec = deps[name]
     if (!spec || Object.keys(deps).length !== 1) return name
@@ -119,6 +159,30 @@ export function detectPackageSpecifier(name: string): string {
   return name
 }
 
+/** Splits a command string into tokens, respecting single and double quotes. */
+function splitCommand(input: string): string[] {
+  const tokens: string[] = []
+  let current = ''
+  let quote: string | null = null
+
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]!
+    if (quote) {
+      if (ch === quote) quote = null
+      else current += ch
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+    } else if (ch === ' ') {
+      if (current) tokens.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  if (current) tokens.push(current)
+  return tokens
+}
+
 /** Promisified execFile with stderr in error message. */
 function exec(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
   return new Promise((resolve, reject) => {

package/src/SyncSkills.test.ts

@@ -1,4 +1,4 @@
-import { Cli, SyncSkills } from 'incur'
+import { Cli, SyncSkills, z } from 'incur'
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -161,6 +161,45 @@ test('installed SKILL.md contains frontmatter', async () => {
   rmSync(tmp, { recursive: true, force: true })
 })
 
+test('installed SKILL.md marks destructive commands', async () => {
+  const tmp = join(tmpdir(), `clac-destructive-test-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+
+  const cli = Cli.create('my-tool')
+  cli.command('destroy', {
+    description: 'Destroy data',
+    destructive: true,
+    hint: 'Deletes all data.',
+    run: () => ({}),
+  })
+  cli.command('status', {
+    description: 'Check status',
+    hint: 'Shows current status.',
+    run: () => ({}),
+  })
+
+  const commands = Cli.toCommands.get(cli)!
+  const installDir = join(tmp, 'install')
+  mkdirSync(join(installDir, '.agents', 'skills'), { recursive: true })
+
+  const result = await SyncSkills.sync('my-tool', commands, {
+    depth: 0,
+    global: false,
+    cwd: installDir,
+  })
+
+  const content = readFileSync(join(result.paths[0]!, 'SKILL.md'), 'utf8')
+  expect(content).toContain(
+    'Deletes all data. Confirm with the user before executing this destructive command.',
+  )
+  expect(content).toContain('Shows current status.')
+  expect(content).not.toContain(
+    'Shows current status. Confirm with the user before executing this destructive command.',
+  )
+
+  rmSync(tmp, { recursive: true, force: true })
+})
+
 test('sync returns unquoted descriptions from YAML frontmatter', async () => {
   const tmp = join(tmpdir(), `clac-quoted-description-test-${Date.now()}`)
   mkdirSync(tmp, { recursive: true })
@@ -288,6 +327,44 @@ test('list includes root command skill', async () => {
   expect(names).toContain('test-ping')
 })
 
+test('sync uses CLI skill projection for aliases, fetch gateways, examples, and output', async () => {
+  const tmp = join(tmpdir(), `clac-sync-drift-test-${Date.now()}`)
+  mkdirSync(tmp, { recursive: true })
+
+  const cli = Cli.create('tool')
+    .command('real', {
+      description: 'Real command',
+      aliases: ['r'],
+      options: z.object({ dryRun: z.boolean().default(false) }),
+      output: z.object({ value: z.string() }),
+      examples: [{ options: { dryRun: true }, description: 'Preview' }],
+      run: () => ({ value: 'ok' }),
+    })
+    .command('api', { description: 'Raw API', fetch: () => new Response('{}') })
+
+  const commands = Cli.toCommands.get(cli)!
+  const listed = await SyncSkills.list('tool', commands)
+  const names = listed.map((skill) => skill.name)
+  expect(names).toContain('tool-api')
+  expect(names).toContain('tool-real')
+  expect(names).not.toContain('tool-r')
+
+  const installDir = join(tmp, 'install')
+  mkdirSync(join(installDir, '.agents', 'skills'), { recursive: true })
+  const synced = await SyncSkills.sync('tool', commands, {
+    depth: 0,
+    global: false,
+    cwd: installDir,
+  })
+  const content = readFileSync(join(synced.paths[0]!, 'SKILL.md'), 'utf8')
+  expect(content).toContain('Preview')
+  expect(content).toContain('## Output')
+  expect(content).toContain('Fetch gateway. Pass path segments')
+  expect(content).not.toMatch(/^# tool r$/m)
+
+  rmSync(tmp, { recursive: true, force: true })
+})
+
 test('list results are sorted alphabetically', async () => {
   const cli = Cli.create('test')
   cli.command('zebra', { description: 'Z command', run: () => ({}) })