incur 0.4.8 → 0.4.9

package/src/e2e.test.ts

@@ -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.
       "
@@ -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). */

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
+}

package/src/lazy-imports.test.ts

@@ -0,0 +1,94 @@
+import { execFile } from 'node:child_process'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+function exec(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      cmd,
+      args,
+      { cwd: join(import.meta.dirname, '..'), timeout: 30_000 },
+      (error, stdout, stderr) => {
+        if (error) reject(new Error(stderr?.trim() || stdout?.trim() || error.message))
+        else resolve({ stdout, stderr })
+      },
+    )
+  })
+}
+
+let dir: string
+let src: string
+
+describe('lazy imports', () => {
+  beforeAll(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'incur-lazy-'))
+    src = join(dir, 'cli.mts')
+
+    // Records every module loaded during a CLI run, then prints the heavy ones.
+    await writeFile(
+      src,
+      `
+import { registerHooks } from 'node:module'
+
+const loaded: string[] = []
+registerHooks({
+  resolve(specifier, context, next) {
+    const result = next(specifier, context)
+    loaded.push(result.url)
+    return result
+  },
+})
+
+const { Cli, z } = await import('${join(import.meta.dirname, 'index.ts')}')
+
+const cli = Cli.create('lazy-cli', { version: '1.0.0' })
+
+cli.command('ping', {
+  description: 'Health check',
+  options: z.object({ upper: z.boolean().default(false) }),
+  run() {
+    return { pong: true }
+  },
+})
+
+await cli.serve(process.argv.slice(2))
+
+const heavy = loaded.filter(
+  (url) => url.includes('@modelcontextprotocol') || url.includes('node_modules/yaml'),
+)
+console.log(JSON.stringify({ heavy }))
+`,
+    )
+  })
+
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  function parseHeavy(stdout: string): string[] {
+    const line = stdout.trim().split('\n').at(-1)!
+    return (JSON.parse(line) as { heavy: string[] }).heavy
+  }
+
+  test('plain command run does not load yaml or the MCP SDK', async () => {
+    const { stdout } = await exec(process.execPath, ['--import', 'tsx', src, 'ping'])
+    expect(stdout).toContain('pong: true')
+    expect(parseHeavy(stdout)).toEqual([])
+  })
+
+  test('--format yaml loads yaml on demand, but not the MCP SDK', async () => {
+    const { stdout } = await exec(process.execPath, [
+      '--import',
+      'tsx',
+      src,
+      'ping',
+      '--format',
+      'yaml',
+    ])
+    expect(stdout).toContain('pong: true')
+    const heavy = parseHeavy(stdout)
+    expect(heavy.some((url) => url.includes('node_modules/yaml'))).toBe(true)
+    expect(heavy.some((url) => url.includes('@modelcontextprotocol'))).toBe(false)
+  })
+})

package/src/middleware.ts

@@ -10,11 +10,16 @@ type InferVars<vars extends z.ZodObject<any> | undefined> =
 type InferEnv<env extends z.ZodObject<any> | undefined> =
   env extends z.ZodObject<any> ? z.output<env> : {}
 
+/** @internal Infers the output type of a globals schema, or `{}` if undefined. */
+type InferGlobals<globals extends z.ZodObject<any> | undefined> =
+  globals extends z.ZodObject<any> ? z.output<globals> : {}
+
 /** Middleware handler that runs before/after command execution. */
 export type Handler<
   vars extends z.ZodObject<any> | undefined = undefined,
   env extends z.ZodObject<any> | undefined = undefined,
-> = (context: Context<vars, env>, next: () => Promise<void>) => Promise<void> | void
+  globals extends z.ZodObject<any> | undefined = undefined,
+> = (context: Context<vars, env, globals>, next: () => Promise<void>) => Promise<void> | void
 
 /** CTA block for middleware error/ok responses. */
 type CtaBlock = {
@@ -28,6 +33,7 @@ type CtaBlock = {
 export type Context<
   vars extends z.ZodObject<any> | undefined = undefined,
   env extends z.ZodObject<any> | undefined = undefined,
+  globals extends z.ZodObject<any> | undefined = undefined,
 > = {
   /** Whether the consumer is an agent (stdout is not a TTY). */
   agent: boolean
@@ -49,6 +55,8 @@ export type Context<
   format: Formatter.Format
   /** Whether the user explicitly passed `--format` or `--json`. */
   formatExplicit: boolean
+  /** Parsed global options from the CLI-level globals schema. */
+  globals: InferGlobals<globals>
   /** The CLI name. */
   name: string
   /** Set a typed variable for downstream middleware and handlers. */
@@ -59,10 +67,11 @@ export type Context<
   version: string | undefined
 }
 
-/** Creates a strictly typed middleware handler. Pass the vars schema as a generic for typed `c.set()` and `c.var`, and the env schema for typed `c.env`. */
+/** Creates a strictly typed middleware handler. Pass the vars schema as a generic for typed `c.set()` and `c.var`, the env schema for typed `c.env`, and the globals schema for typed `c.globals`. */
 export default function middleware<
   const vars extends z.ZodObject<any> | undefined = undefined,
   const env extends z.ZodObject<any> | undefined = undefined,
->(handler: Handler<vars, env>): Handler<vars, env> {
+  const globals extends z.ZodObject<any> | undefined = undefined,
+>(handler: Handler<vars, env, globals>): Handler<vars, env, globals> {
   return handler
 }