incur 0.4.8 → 0.4.10

package/src/SyncSkills.ts

@@ -2,10 +2,11 @@ import fsSync from 'node:fs'
 import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
-import { parse as yamlParse } from 'yaml'
 
-import { formatExamples } from './Cli.js'
+import { collectSkillCommands, parseSkillFrontmatter } from './Cli.js'
 import * as Agents from './internal/agents.js'
+import * as Yaml from './internal/yaml.js'
+import type * as Mcp from './Mcp.js'
 import * as Skill from './Skill.js'
 
 /** Generates skill files from a command map and installs them natively. */
@@ -17,9 +18,12 @@ export async function sync(
   const { depth = 1, description, global = true } = options
   const cwd = options.cwd ?? (global ? resolvePackageRoot() : process.cwd())
 
+  // Pre-load yaml for the sync call paths below (`Skill.split`, `parseFrontmatter`).
+  await Yaml.load()
+
   const groups = new Map<string, string>()
   if (description) groups.set(name, description)
-  const entries = collectEntries(commands, [], groups, options.rootCommand)
+  const entries = collectSkillCommands(commands, [], groups, options.rootCommand)
   const files = Skill.split(name, entries, depth, groups)
 
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), `incur-skills-${name}-`))
@@ -31,7 +35,7 @@ export async function sync(
         : path.join(tmpDir, 'SKILL.md')
       await fs.mkdir(path.dirname(filePath), { recursive: true })
       await fs.writeFile(filePath, `${file.content}\n`)
-      const meta = parseFrontmatter(file.content)
+      const meta = parseSkillFrontmatter(file.content)
       skills.push({ name: meta.name ?? (file.dir || name), description: meta.description })
     }
 
@@ -42,7 +46,7 @@ export async function sync(
         for await (const match of fs.glob(globPattern, { cwd })) {
           try {
             const content = await fs.readFile(path.resolve(cwd, match), 'utf8')
-            const meta = parseFrontmatter(content)
+            const meta = parseSkillFrontmatter(content)
             const skillName =
               pattern === '_root' ? (meta.name ?? name) : path.basename(path.dirname(match))
             const dest = path.join(tmpDir, skillName, 'SKILL.md')
@@ -68,7 +72,7 @@ export async function sync(
     }
 
     // Write skills hash + names for staleness detection
-    const hashEntries = collectEntries(commands, [], undefined, options.rootCommand)
+    const hashEntries = collectSkillCommands(commands, [], new Map(), options.rootCommand)
     writeMeta(
       name,
       Skill.hash(hashEntries),
@@ -100,8 +104,10 @@ export declare namespace sync {
       | {
           description?: string | undefined
           args?: any
+          destructive?: boolean | undefined
           env?: any
           hint?: string | undefined
+          mcp?: { annotations?: Mcp.ToolAnnotations | undefined } | undefined
           options?: any
           output?: any
           examples?: any[] | undefined
@@ -137,16 +143,19 @@ export async function list(
   const { depth = 1, description } = options
   const cwd = options.cwd ?? process.cwd()
 
+  // Pre-load yaml for the sync call paths below (`Skill.split`, `parseFrontmatter`).
+  await Yaml.load()
+
   const groups = new Map<string, string>()
   if (description) groups.set(name, description)
-  const entries = collectEntries(commands, [], groups, options.rootCommand)
+  const entries = collectSkillCommands(commands, [], groups, options.rootCommand)
   const files = Skill.split(name, entries, depth, groups)
 
   const skills: list.Skill[] = []
   const installed = readInstalledSkills(name, { cwd })
 
   for (const file of files) {
-    const meta = parseFrontmatter(file.content)
+    const meta = parseSkillFrontmatter(file.content)
     const skillName = meta.name ?? (file.dir || name)
     skills.push({
       name: skillName,
@@ -162,7 +171,7 @@ export async function list(
       for await (const match of fs.glob(globPattern, { cwd })) {
         try {
           const content = await fs.readFile(path.resolve(cwd, match), 'utf8')
-          const meta = parseFrontmatter(content)
+          const meta = parseSkillFrontmatter(content)
           const skillName =
             pattern === '_root' ? (meta.name ?? name) : path.basename(path.dirname(match))
           if (!skills.some((s) => s.name === skillName)) {
@@ -204,8 +213,10 @@ export declare namespace list {
       | {
           description?: string | undefined
           args?: any
+          destructive?: boolean | undefined
           env?: any
           hint?: string | undefined
+          mcp?: { annotations?: Mcp.ToolAnnotations | undefined } | undefined
           options?: any
           output?: any
           examples?: any[] | undefined
@@ -223,75 +234,6 @@ export declare namespace list {
   }
 }
 
-/** Recursively collects leaf commands as `Skill.CommandInfo`. */
-function collectEntries(
-  commands: Map<string, any>,
-  prefix: string[],
-  groups: Map<string, string> = new Map(),
-  rootCommand?:
-    | {
-        description?: string | undefined
-        args?: any
-        env?: any
-        hint?: string | undefined
-        options?: any
-        output?: any
-        examples?: any[] | undefined
-      }
-    | undefined,
-): Skill.CommandInfo[] {
-  const result: Skill.CommandInfo[] = []
-  if (rootCommand) {
-    const cmd: Skill.CommandInfo = {}
-    if (rootCommand.description) cmd.description = rootCommand.description
-    if (rootCommand.args) cmd.args = rootCommand.args
-    if (rootCommand.env) cmd.env = rootCommand.env
-    if (rootCommand.hint) cmd.hint = rootCommand.hint
-    if (rootCommand.options) cmd.options = rootCommand.options
-    if (rootCommand.output) cmd.output = rootCommand.output
-    const examples = formatExamples(rootCommand.examples)
-    if (examples) cmd.examples = examples
-    result.push(cmd)
-  }
-  for (const [name, entry] of commands) {
-    const entryPath = [...prefix, name]
-    if ('_group' in entry && entry._group) {
-      if (entry.description) groups.set(entryPath.join(' '), entry.description)
-      result.push(...collectEntries(entry.commands, entryPath, groups))
-    } else {
-      const cmd: Skill.CommandInfo = { name: entryPath.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 = formatExamples(entry.examples)
-      if (examples) {
-        const cmdName = entryPath.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 ?? ''))
-}
-
-function parseFrontmatter(content: string): {
-  description?: string | undefined
-  name?: string | undefined
-} {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-  if (!match) return {}
-
-  const meta = yamlParse(match[1]!)
-  if (!meta || typeof meta !== 'object') return {}
-  return meta as { description?: string | undefined; name?: string | undefined }
-}
-
 /** Resolves the package root from the executing bin script (`process.argv[1]`). Walks up from the bin's directory looking for `package.json`. Falls back to `process.cwd()`. */
 function resolvePackageRoot(): string {
   const bin = process.argv[1]

package/src/bun-compile.test.ts

@@ -70,6 +70,11 @@ cli.serve()
     expect(stdout).toContain('result: HELLO')
   })
 
+  test('runs command with --format yaml (lazy yaml import)', async () => {
+    const { stdout } = await exec(bin, ['ping', '--format', 'yaml'])
+    expect(stdout).toContain('pong: true')
+  })
+
   test('shows help', async () => {
     const { stdout } = await exec(bin, ['--help'])
     expect(stdout).toContain('test-cli')

package/src/e2e.test.ts

@@ -984,7 +984,7 @@ describe('help', () => {
 
       Integrations:
         completions  Generate shell completion script
-        mcp add      Register as MCP server
+        mcp          Register as MCP server (add, doctor)
         skills       Sync skill files to agents (add, list)
 
       Global Options:
@@ -1513,9 +1513,9 @@ describe('--llms', () => {
 
       | Command | Description |
       |---------|-------------|
-      | \`app auth auth login\` | Log in to the service |
-      | \`app auth auth logout\` | Log out of the service |
-      | \`app auth auth status\` | Show authentication status |
+      | \`app auth login\` | Log in to the service |
+      | \`app auth logout\` | Log out of the service |
+      | \`app auth status\` | Show authentication status |
 
       Run \`app auth --llms-full\` for full manifest. Run \`app auth <command> --schema\` for argument details.
       "
@@ -1531,9 +1531,9 @@ describe('--llms', () => {
 
       | Command | Description |
       |---------|-------------|
-      | \`app project deploy project deploy create <env>\` | Create a deployment |
-      | \`app project deploy project deploy rollback <deployId>\` | Rollback a deployment |
-      | \`app project deploy project deploy status <deployId>\` | Check deployment status |
+      | \`app project deploy create <env>\` | Create a deployment |
+      | \`app project deploy rollback <deployId>\` | Rollback a deployment |
+      | \`app project deploy status <deployId>\` | Check deployment status |
 
       Run \`app project deploy --llms-full\` for full manifest. Run \`app project deploy <command> --schema\` for argument details.
       "
@@ -1759,7 +1759,7 @@ describe('root command with subcommands', () => {
 
       Integrations:
         completions  Generate shell completion script
-        mcp add      Register as MCP server
+        mcp          Register as MCP server (add, doctor)
         skills       Sync skill files to agents (add, list)
 
       Global Options:
@@ -2436,7 +2436,7 @@ describe('hosted OpenAPI CLI', () => {
 
         Integrations:
           completions  Generate shell completion script
-          mcp add      Register as MCP server
+          mcp          Register as MCP server (add, doctor)
           skills       Sync skill files to agents (add, list)
 
         Global Options:
@@ -2517,7 +2517,7 @@ describe('hosted OpenAPI CLI', () => {
 
         Integrations:
           completions  Generate shell completion script
-          mcp add      Register as MCP server
+          mcp          Register as MCP server (add, doctor)
           skills       Sync skill files to agents (add, list)
 
         Global Options:
@@ -2598,7 +2598,7 @@ describe('hosted OpenAPI CLI', () => {
   })
 })
 
-async function fetchJson(cli: Cli.Cli<any, any, any>, req: Request) {
+async function fetchJson(cli: Cli.Cli<any, any, any, any>, req: Request) {
   const res = await cli.fetch(req)
   const body = await res.json()
   if (body.meta?.duration) body.meta.duration = '<stripped>'
@@ -2833,6 +2833,8 @@ describe('fetch api', () => {
       .trim()
       .split('\n')
       .map((l) => JSON.parse(l))
+    expect(lines[2].meta.duration).toMatch(/^\d+ms$/)
+    lines[2].meta.duration = '<stripped>'
     expect(lines).toMatchInlineSnapshot(`
       [
         {
@@ -2850,6 +2852,7 @@ describe('fetch api', () => {
         {
           "meta": {
             "command": "stream",
+            "duration": "<stripped>",
           },
           "ok": true,
           "type": "done",
@@ -2947,7 +2950,7 @@ describe('fetch api', () => {
           clientInfo: { name: 'test-client', version: '1.0.0' },
         },
       })
-      const sessionId = res.headers.get('mcp-session-id')!
+      const sessionId = res.headers.get('mcp-session-id') ?? undefined
       await mcpRequest(cli, { jsonrpc: '2.0', method: 'notifications/initialized' }, sessionId)
       return sessionId
     }
@@ -2965,6 +2968,7 @@ describe('fetch api', () => {
         },
       })
       expect(res.status).toBe(200)
+      expect(res.headers.get('mcp-session-id')).toBeNull()
       const body = await res.json()
       expect({
         serverInfo: body.result.serverInfo,
@@ -2980,6 +2984,41 @@ describe('fetch api', () => {
       `)
     })
 
+    test('tools/list works without session state', async () => {
+      const cli = createApp()
+      await mcpRequest(cli, {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-03-26',
+          capabilities: {},
+          clientInfo: { name: 'test-client', version: '1.0.0' },
+        },
+      })
+      const res = await mcpRequest(cli, {
+        jsonrpc: '2.0',
+        id: 2,
+        method: 'tools/list',
+        params: {},
+      })
+      expect(res.status).toBe(200)
+      const body = await res.json()
+      expect(body.result.tools.map((t: any) => t.name).sort()).toContain('ping')
+    })
+
+    test('GET /mcp returns method not allowed in stateless mode', async () => {
+      const cli = createApp()
+      const res = await cli.fetch(
+        new Request('http://localhost/mcp', {
+          method: 'GET',
+          headers: { accept: 'text/event-stream' },
+        }),
+      )
+      expect(res.status).toBe(405)
+      expect(res.headers.get('allow')).toBe('POST')
+    })
+
     test('tools/list → lists all registered tools', async () => {
       const cli = createApp()
       const sessionId = await initSession(cli)
@@ -3172,6 +3211,71 @@ describe('fetch api', () => {
   })
 })
 
+describe('globals', () => {
+  test('global flags flow through middleware for nested commands', async () => {
+    const { output } = await serve(createGlobalsApp(), [
+      'deploy',
+      'status',
+      '--api-token',
+      'secret',
+      '--profile',
+      'production',
+      '--format',
+      'json',
+    ])
+    expect(json(output)).toEqual({
+      command: 'deploy status',
+      profile: 'production',
+      token: 'secret',
+    })
+  })
+
+  test('informational commands do not require required globals', async () => {
+    const cli = createGlobalsApp()
+
+    const help = await serve(cli, ['--help'])
+    expect(help.exitCode).toBeUndefined()
+    expect(help.output).toContain('Custom Global Options:')
+    expect(help.output).toContain('--api-token')
+
+    const schema = await serve(cli, ['whoami', '--schema', '--format', 'json'])
+    expect(schema.exitCode).toBeUndefined()
+    expect(json(schema.output).globals.properties.apiToken).toBeDefined()
+
+    const llms = await serve(cli, ['--llms', '--format', 'json'])
+    expect(llms.exitCode).toBeUndefined()
+    expect(json(llms.output).globals.properties.apiToken).toBeDefined()
+
+    const version = await serve(cli, ['--version'])
+    expect(version.exitCode).toBeUndefined()
+    expect(version.output).toBe('1.0.0\n')
+  })
+
+  test('fetch requests expose globals to middleware and command query params to handlers', async () => {
+    const result = await fetchJson(
+      createGlobalsApp(),
+      new Request('http://localhost/search?apiToken=secret&profile=staging&limit=2'),
+    )
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "limit": 2,
+            "profile": "staging",
+            "token": "secret",
+          },
+          "meta": {
+            "command": "search",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+})
+
 describe('.well-known/skills', () => {
   async function fetchSkills(cli: Cli.Cli<any, any, any>, path: string) {
     const res = await cli.fetch(new Request(`http://localhost${path}`))
@@ -3358,6 +3462,56 @@ function createMiddlewareApp() {
   return { cli, order }
 }
 
+const globalsVars = z.object({
+  apiToken: z.string().default(''),
+  profile: z.string().default(''),
+})
+
+function createGlobalsApp() {
+  const deploy = Cli.create('deploy', {
+    description: 'Deployment commands',
+    vars: globalsVars,
+  }).command('status', {
+    description: 'Show deployment status',
+    run(c) {
+      return {
+        command: 'deploy status',
+        profile: c.var.profile,
+        token: c.var.apiToken,
+      }
+    },
+  })
+
+  return Cli.create('global-app', {
+    version: '1.0.0',
+    globals: z.object({
+      apiToken: z.string().describe('API token'),
+      profile: z.string().default('dev').describe('Profile name'),
+    }),
+    globalAlias: { apiToken: 't' },
+    vars: globalsVars,
+  })
+    .use(async (c, next) => {
+      c.set('apiToken', c.globals.apiToken)
+      c.set('profile', c.globals.profile)
+      await next()
+    })
+    .command('whoami', {
+      description: 'Show active profile',
+      run(c) {
+        return { profile: c.var.profile, token: c.var.apiToken }
+      },
+    })
+    .command('search', {
+      description: 'Search resources',
+      options: z.object({ limit: z.coerce.number().default(10) }),
+      run(c) {
+        return { limit: c.options.limit, profile: c.var.profile, token: c.var.apiToken }
+      },
+    })
+    .command(deploy)
+}
+
 function createApp() {
   const auth = Cli.create('auth', { description: 'Authentication commands' })
     .command('login', {

package/src/internal/command.ts

@@ -44,6 +44,7 @@ export async function execute(command: any, options: execute.Options): Promise<e
     version,
     envSource = process.env,
     env: envSchema,
+    globals = {},
     vars: varsSchema,
     middlewares = [],
   } = options
@@ -81,12 +82,12 @@ export async function execute(command: any, options: execute.Options): Promise<e
       // HTTP mode: positional args from URL path segments, options from body/query
       const parsed = Parser.parse(argv, { args: command.args })
       args = parsed.args
-      parsedOptions = command.options ? command.options.parse(inputOptions) : {}
+      parsedOptions = command.options ? Parser.zodParse(command.options, inputOptions) : {}
     } else {
       // MCP mode: all params come from inputOptions, split into args vs options
       const split = splitParams(inputOptions, command)
-      args = command.args ? command.args.parse(split.args) : {}
-      parsedOptions = command.options ? command.options.parse(split.options) : {}
+      args = command.args ? Parser.zodParse(command.args, split.args) : {}
+      parsedOptions = command.options ? Parser.zodParse(command.options, split.options) : {}
     }
 
     // Parse env
@@ -128,7 +129,7 @@ export async function execute(command: any, options: execute.Options): Promise<e
         })
         async function* wrapped() {
           try {
-            yield* raw as AsyncGenerator<unknown, unknown, unknown>
+            return yield* raw as AsyncGenerator<unknown, unknown, unknown>
           } finally {
             resolveStreamConsumed!()
           }
@@ -201,6 +202,7 @@ export async function execute(command: any, options: execute.Options): Promise<e
         error: errorFn,
         format: format as any,
         formatExplicit,
+        globals,
         name,
         set(key: string, value: unknown) {
           varsMap[key] = value
@@ -285,6 +287,8 @@ export declare namespace execute {
     format: string
     /** Whether the format was explicitly requested. */
     formatExplicit: boolean
+    /** Parsed global options. Defaults to `{}` when not provided. */
+    globals?: Record<string, unknown> | undefined
     /** Raw parsed options (from query params, JSON body, or MCP params). For CLI, pass `{}`. */
     inputOptions: Record<string, unknown>
     /** Middleware handlers (root + group + command, already collected). */
@@ -415,6 +419,10 @@ export const builtinCommands = [
           noGlobal: z.boolean().optional().describe('Install to project instead of globally'),
         }),
       }),
+      subcommand({
+        name: 'doctor',
+        description: 'Validate MCP server startup and tool listing',
+      }),
     ],
   },
   {

package/src/internal/cta.ts

@@ -0,0 +1,58 @@
+/** @internal A CTA block before command names are expanded. */
+export type CtaBlock = {
+  commands: unknown[]
+  description?: string | undefined
+}
+
+/** @internal A formatted CTA block as it appears in output metadata. */
+export type FormattedCtaBlock = {
+  /** Formatted command suggestions. */
+  commands: FormattedCta[]
+  /** Human-readable label for the CTA block. */
+  description: string
+}
+
+/** @internal A formatted CTA as it appears in output metadata. */
+export type FormattedCta = {
+  /** The full command string with args and options folded in. */
+  command: string
+  /** A short description of what the command does. */
+  description?: string | undefined
+}
+
+type Cta =
+  | string
+  | {
+      args?: Record<string, unknown> | undefined
+      command: string
+      description?: string | undefined
+      options?: Record<string, unknown> | undefined
+    }
+
+/** @internal Formats a CTA block into the output metadata shape. */
+export function formatCtaBlock(
+  name: string,
+  block: CtaBlock | undefined,
+): FormattedCtaBlock | undefined {
+  if (!block || block.commands.length === 0) return undefined
+  return {
+    description:
+      block.description ??
+      (block.commands.length === 1 ? 'Suggested command:' : 'Suggested commands:'),
+    commands: block.commands.map((c) => formatCta(name, c as Cta)),
+  }
+}
+
+/** @internal Formats a CTA by prefixing the CLI name. */
+function formatCta(name: string, cta: Cta): FormattedCta {
+  if (typeof cta === 'string') return { command: `${name} ${cta}` }
+  const prefix = cta.command === name || cta.command.startsWith(`${name} `) ? '' : `${name} `
+  let cmd = `${prefix}${cta.command}`
+  if (cta.args)
+    for (const [key, value] of Object.entries(cta.args))
+      cmd += value === true ? ` <${key}>` : ` ${value}`
+  if (cta.options)
+    for (const [key, value] of Object.entries(cta.options))
+      cmd += value === true ? ` --${key} <${key}>` : ` --${key} ${value}`
+  return { command: cmd, ...(cta.description ? { description: cta.description } : undefined) }
+}

package/src/internal/json.ts

@@ -0,0 +1,16 @@
+/** Serializes JSON with BigInt values represented as decimal strings. */
+export function stringify(value: unknown, space?: number): string {
+  return JSON.stringify(
+    value,
+    (_key, value) => {
+      if (typeof value === 'bigint') return value.toString()
+      return value
+    },
+    space,
+  )
+}
+
+/** Converts a value to JSON-compatible data. */
+export function normalize(value: unknown): unknown {
+  return JSON.parse(stringify(value))
+}

package/src/internal/yaml.ts

@@ -0,0 +1,23 @@
+import { createRequire } from 'node:module'
+import type * as yaml from 'yaml'
+
+/** @internal Cached `yaml` module, shared by `load()` and `loadSync()`. */
+let cached: typeof yaml | undefined
+
+/** Loads the `yaml` module on demand, so runs that never touch YAML don't pay its startup cost. */
+export async function load(): Promise<typeof yaml> {
+  cached ??= await import('yaml')
+  return cached
+}
+
+/**
+ * Synchronous variant of `load()` for sync call paths (e.g. `Formatter.format`).
+ *
+ * Falls back to `require` when `load()` hasn't run yet. Async paths should call `load()`
+ * first so environments without synchronous module resolution (e.g. compiled binaries,
+ * bundled workers) never hit the fallback.
+ */
+export function loadSync(): typeof yaml {
+  cached ??= createRequire(import.meta.url)('yaml') as typeof yaml
+  return cached
+}