incur 0.3.3 → 0.3.5

package/dist/internal/command.js

@@ -0,0 +1,275 @@
+import { z } from 'zod';
+import { IncurError, ValidationError } from '../Errors.js';
+import * as Parser from '../Parser.js';
+/** @internal Sentinel symbol for `ok()` and `error()` return values. */
+const sentinel = Symbol.for('incur.sentinel');
+/** @internal Unified command execution used by CLI, HTTP, and MCP transports. */
+export async function execute(command, options) {
+    const { argv, inputOptions, agent, format, formatExplicit, name, path, version, envSource = process.env, env: envSchema, vars: varsSchema, middlewares = [], } = options;
+    const parseMode = options.parseMode ?? 'argv';
+    const varsMap = varsSchema ? varsSchema.parse({}) : {};
+    let result;
+    // For streaming with middleware: runCommand suspends on streamConsumed so middleware "after"
+    // runs after the stream is consumed. The wrapped generator resolves it in its finally block.
+    // resultReady signals that result has been set (for streams, before the chain finishes).
+    let streamConsumed;
+    let resolveStreamConsumed;
+    let resolveResultReady;
+    const resultReady = new Promise((r) => {
+        resolveResultReady = r;
+    });
+    const runCommand = async () => {
+        // Parse args and options
+        let args;
+        let parsedOptions;
+        if (parseMode === 'argv') {
+            // CLI mode: parse both args and options from argv tokens
+            const parsed = Parser.parse(argv, {
+                alias: command.alias,
+                args: command.args,
+                options: command.options,
+            });
+            args = parsed.args;
+            parsedOptions = parsed.options;
+        }
+        else if (parseMode === 'split') {
+            // 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) : {};
+        }
+        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) : {};
+        }
+        // Parse env
+        const commandEnv = command.env ? Parser.parseEnv(command.env, envSource) : {};
+        // Build sentinel helpers
+        const okFn = (data, meta = {}) => ({ [sentinel]: 'ok', data, cta: meta.cta });
+        const errorFn = (opts) => ({ [sentinel]: 'error', ...opts });
+        const raw = command.run({
+            agent,
+            args,
+            env: commandEnv,
+            error: errorFn,
+            format,
+            formatExplicit,
+            name,
+            ok: okFn,
+            options: parsedOptions,
+            var: varsMap,
+            version,
+        });
+        // Streaming: wrap the generator so middleware "after" runs after consumption.
+        // When middleware is active, runCommand suspends until the stream is fully consumed,
+        // keeping the middleware chain alive around the stream's lifetime.
+        if (isAsyncGenerator(raw)) {
+            if (middlewares.length > 0) {
+                streamConsumed = new Promise((r) => {
+                    resolveStreamConsumed = r;
+                });
+                async function* wrapped() {
+                    try {
+                        yield* raw;
+                    }
+                    finally {
+                        resolveStreamConsumed();
+                    }
+                }
+                result = { stream: wrapped() };
+                resolveResultReady();
+                await streamConsumed;
+            }
+            else {
+                result = { stream: raw };
+            }
+            return;
+        }
+        const awaited = await raw;
+        if (isSentinel(awaited)) {
+            if (awaited[sentinel] === 'ok') {
+                const ok = awaited;
+                result = { ok: true, data: ok.data, ...(ok.cta ? { cta: ok.cta } : undefined) };
+            }
+            else {
+                const err = awaited;
+                result = {
+                    ok: false,
+                    error: {
+                        code: err.code,
+                        message: err.message,
+                        ...(err.retryable !== undefined ? { retryable: err.retryable } : undefined),
+                    },
+                    ...(err.cta ? { cta: err.cta } : undefined),
+                    ...(err.exitCode !== undefined ? { exitCode: err.exitCode } : undefined),
+                };
+            }
+            return;
+        }
+        result = { ok: true, data: awaited };
+    };
+    try {
+        // Parse CLI-level env
+        const cliEnv = envSchema ? Parser.parseEnv(envSchema, envSource) : {};
+        if (middlewares.length > 0) {
+            const errorFn = (opts) => {
+                // Side-effect: set result directly (handles both `return c.error()` and bare `c.error()`)
+                result = {
+                    ok: false,
+                    error: {
+                        code: opts.code,
+                        message: opts.message,
+                        ...(opts.retryable !== undefined ? { retryable: opts.retryable } : undefined),
+                    },
+                    ...(opts.cta ? { cta: opts.cta } : undefined),
+                    ...(opts.exitCode !== undefined ? { exitCode: opts.exitCode } : undefined),
+                };
+                return undefined;
+            };
+            const mwCtx = {
+                agent,
+                command: path,
+                env: cliEnv,
+                error: errorFn,
+                format: format,
+                formatExplicit,
+                name,
+                set(key, value) {
+                    varsMap[key] = value;
+                },
+                var: varsMap,
+                version,
+            };
+            const composed = middlewares.reduceRight((next, mw) => async () => {
+                await mw(mwCtx, next);
+            }, runCommand);
+            // Start the chain and race against resultReady. For streams with middleware,
+            // runCommand suspends on streamConsumed (keeping middleware "after" deferred)
+            // but signals resultReady so we can return the stream immediately. The transport
+            // consumes the stream, which resolves streamConsumed, letting middleware "after" run.
+            const chainPromise = composed();
+            await Promise.race([chainPromise, resultReady]);
+            if (streamConsumed)
+                return result;
+            await chainPromise;
+        }
+        else {
+            await runCommand();
+        }
+    }
+    catch (error) {
+        if (error instanceof ValidationError)
+            return {
+                ok: false,
+                error: {
+                    code: 'VALIDATION_ERROR',
+                    message: error.message,
+                    fieldErrors: error.fieldErrors,
+                },
+            };
+        return {
+            ok: false,
+            error: {
+                code: error instanceof IncurError ? error.code : 'UNKNOWN',
+                message: error instanceof Error ? error.message : String(error),
+                ...(error instanceof IncurError ? { retryable: error.retryable } : undefined),
+            },
+            ...(error instanceof IncurError && error.exitCode !== undefined
+                ? { exitCode: error.exitCode }
+                : undefined),
+        };
+    }
+    return result ?? { ok: true, data: undefined };
+}
+/** @internal Splits flat params into args vs options using schema shapes. */
+function splitParams(params, command) {
+    const argKeys = new Set(command.args ? Object.keys(command.args.shape) : []);
+    const a = {};
+    const o = {};
+    for (const [key, value] of Object.entries(params))
+        if (argKeys.has(key))
+            a[key] = value;
+        else
+            o[key] = value;
+    return { args: a, options: o };
+}
+/** @internal Type guard for sentinel results. */
+function isSentinel(value) {
+    return typeof value === 'object' && value !== null && sentinel in value;
+}
+/** @internal Type guard for async generators. */
+function isAsyncGenerator(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        Symbol.asyncIterator in value &&
+        typeof value.next === 'function');
+}
+/** @internal Creates a builtin subcommand with typesafe alias inference. */
+function subcommand(def) {
+    return def;
+}
+/** Supported shell names for completions. */
+export const shells = ['bash', 'fish', 'nushell', 'zsh'];
+/** Built-in command metadata shared by help, completions, and handler logic. */
+export const builtinCommands = [
+    {
+        name: 'completions',
+        description: 'Generate shell completion script',
+        args: z.object({
+            shell: z.enum(shells).describe('Shell to generate completions for'),
+        }),
+        hint(name) {
+            const rows = [
+                ['bash', `eval "$(${name} completions bash)"`, '# add to ~/.bashrc'],
+                ['fish', `${name} completions fish | source`, '# add to ~/.config/fish/config.fish'],
+                ['nushell', `see \`${name} completions nushell\``, '# add to config.nu'],
+                ['zsh', `eval "$(${name} completions zsh)"`, '# add to ~/.zshrc'],
+            ];
+            const shellW = Math.max(...rows.map((r) => r[0].length));
+            const cmdW = Math.max(...rows.map((r) => r[1].length));
+            return ('Setup:\n' +
+                rows
+                    .map(([s, cmd, comment]) => `  ${s.padEnd(shellW)}  ${cmd.padEnd(cmdW)}  ${comment}`)
+                    .join('\n'));
+        },
+    },
+    {
+        name: 'mcp',
+        description: 'Register as MCP server',
+        subcommands: [
+            subcommand({
+                name: 'add',
+                description: 'Register as MCP server',
+                alias: { command: 'c' },
+                options: z.object({
+                    agent: z
+                        .string()
+                        .optional()
+                        .describe('Target a specific agent (e.g. claude-code, cursor)'),
+                    command: z
+                        .string()
+                        .optional()
+                        .describe('Override the command agents will run (e.g. "pnpm my-cli --mcp")'),
+                    noGlobal: z.boolean().optional().describe('Install to project instead of globally'),
+                }),
+            }),
+        ],
+    },
+    {
+        name: 'skills',
+        description: 'Sync skill files to agents',
+        subcommands: [
+            subcommand({
+                name: 'add',
+                description: 'Sync skill files to agents',
+                options: z.object({
+                    depth: z.number().optional().describe('Grouping depth for skill files (default: 1)'),
+                    noGlobal: z.boolean().optional().describe('Install to project instead of globally'),
+                }),
+            }),
+        ],
+    },
+];
+//# sourceMappingURL=command.js.map

package/dist/internal/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/internal/command.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -16,7 +16,7 @@
   "[!start-pkg]": "",
   "name": "incur",
   "type": "module",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/Cli.test.ts

@@ -921,7 +921,7 @@ describe('subcommands', () => {
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
@@ -1350,10 +1350,10 @@ describe('help', () => {
       Commands:
         ping  Health check
 
-      Built-in Commands:
+      Integrations:
         completions  Generate shell completion script
-        mcp add      Register as an MCP server
-        skills add   Sync skill files to your agent
+        mcp add      Register as MCP server
+        skills add   Sync skill files to agents
 
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
@@ -1361,7 +1361,7 @@ describe('help', () => {
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
@@ -1388,10 +1388,10 @@ describe('help', () => {
       Commands:
         ping  Health check
 
-      Built-in Commands:
+      Integrations:
         completions  Generate shell completion script
-        mcp add      Register as an MCP server
-        skills add   Sync skill files to your agent
+        mcp add      Register as MCP server
+        skills add   Sync skill files to agents
 
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
@@ -1399,7 +1399,7 @@ describe('help', () => {
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
@@ -1432,7 +1432,7 @@ describe('help', () => {
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
@@ -1466,7 +1466,7 @@ describe('help', () => {
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
@@ -1551,10 +1551,10 @@ describe('help', () => {
       Commands:
         ping  Ping
 
-      Built-in Commands:
+      Integrations:
         completions  Generate shell completion script
-        mcp add      Register as an MCP server
-        skills add   Sync skill files to your agent
+        mcp add      Register as MCP server
+        skills add   Sync skill files to agents
 
       Global Options:
         --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
@@ -1562,7 +1562,7 @@ describe('help', () => {
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
         --mcp                               Start as MCP stdio server
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
@@ -1593,7 +1593,7 @@ describe('help', () => {
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
@@ -1688,7 +1688,7 @@ describe('env', () => {
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms, --llms-full                 Print LLM-readable manifest
-        --schema                            Show JSON Schema for a command
+        --schema                            Show JSON Schema for command
         --token-count                       Print token count of output (instead of output)
         --token-limit <n>                   Limit output to n tokens
         --token-offset <n>                  Skip first n tokens of output
@@ -1726,7 +1726,7 @@ describe('env', () => {
           --format <toon|json|yaml|md|jsonl>  Output format
           --help                              Show help
           --llms, --llms-full                 Print LLM-readable manifest
-          --schema                            Show JSON Schema for a command
+          --schema                            Show JSON Schema for command
           --token-count                       Print token count of output (instead of output)
           --token-limit <n>                   Limit output to n tokens
           --token-offset <n>                  Skip first n tokens of output
@@ -1838,6 +1838,76 @@ describe('env', () => {
   })
 })
 
+describe('built-in commands', () => {
+  test('bare completions shows help', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['completions'])
+    expect(output).toContain('Generate shell completion script')
+  })
+
+  test('completions --help shows help', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['completions', '--help'])
+    expect(output).toContain('test completions')
+    expect(output).toContain('Generate shell completion script')
+  })
+
+  test('bare mcp shows help with subcommands', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['mcp'])
+    expect(output).toContain('test mcp')
+    expect(output).toContain('Register as MCP server')
+    expect(output).toContain('add')
+  })
+
+  test('mcp --help shows help with subcommands', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['mcp', '--help'])
+    expect(output).toContain('test mcp')
+    expect(output).toContain('add')
+  })
+
+  test('mcp add --help shows options', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['mcp', 'add', '--help'])
+    expect(output).toContain('test mcp add')
+    expect(output).toContain('--command')
+    expect(output).toContain('--no-global')
+    expect(output).toContain('--agent')
+  })
+
+  test('bare skills shows help with subcommands', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['skills'])
+    expect(output).toContain('test skills')
+    expect(output).toContain('Sync skill files to agents')
+    expect(output).toContain('add')
+  })
+
+  test('skills --help shows help with subcommands', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['skills', '--help'])
+    expect(output).toContain('test skills')
+    expect(output).toContain('add')
+  })
+
+  test('skills add --help shows options', async () => {
+    const cli = Cli.create('test')
+    cli.command('ping', { run: () => ({ pong: true }) })
+    const { output } = await serve(cli, ['skills', 'add', '--help'])
+    expect(output).toContain('test skills add')
+    expect(output).toContain('--depth')
+    expect(output).toContain('--no-global')
+  })
+})
+
 describe('skills staleness', () => {
   let stderrSpy: ReturnType<typeof vi.spyOn>
 
@@ -3375,6 +3445,83 @@ describe('fetch', () => {
     `)
   })
 
+  test('group middleware runs for nested commands', async () => {
+    const sub = Cli.create('admin', {
+      vars: z.object({ role: z.string().default('none') }),
+    })
+    sub.use(async (c, next) => {
+      c.set('role', 'admin')
+      await next()
+    })
+    sub.command('status', {
+      run: (c) => ({ role: c.var.role }),
+    })
+    const cli = Cli.create('test', {
+      vars: z.object({ role: z.string().default('none') }),
+    })
+    cli.command(sub)
+    expect(await fetchJson(cli, new Request('http://localhost/admin/status')))
+      .toMatchInlineSnapshot(`
+      {
+        "body": {
+          "data": {
+            "role": "admin",
+          },
+          "meta": {
+            "command": "admin status",
+            "duration": "<stripped>",
+          },
+          "ok": true,
+        },
+        "status": 200,
+      }
+    `)
+  })
+
+  test('cli-level env schema is parsed', async () => {
+    const cli = Cli.create('test', {
+      env: z.object({ APP_TOKEN: z.string().default('fallback') }),
+    })
+    cli.use(async (c, next) => {
+      // env should be parsed from envSchema
+      ;(globalThis as any).__testEnv = c.env
+      await next()
+    })
+    cli.command('check', { run: () => ({ ok: true }) })
+    await cli.fetch(new Request('http://localhost/check'))
+    expect((globalThis as any).__testEnv).toEqual({ APP_TOKEN: 'fallback' })
+    delete (globalThis as any).__testEnv
+  })
+
+  test('retryable error is propagated', async () => {
+    const cli = Cli.create('test')
+    cli.command('rate-limit', {
+      run: (c) => c.error({ code: 'RATE_LIMITED', message: 'slow down', retryable: true }),
+    })
+    const { body } = await fetchJson(cli, new Request('http://localhost/rate-limit'))
+    expect(body.ok).toBe(false)
+    expect(body.error.retryable).toBe(true)
+  })
+
+  test('cta block is propagated', async () => {
+    const cli = Cli.create('test')
+    cli.command('done', {
+      run: (c) => c.ok({ id: 1 }, { cta: { commands: ['list'], description: 'Next steps:' } }),
+    })
+    const { body } = await fetchJson(cli, new Request('http://localhost/done'))
+    expect(body.ok).toBe(true)
+    expect(body.meta.cta).toMatchInlineSnapshot(`
+      {
+        "commands": [
+          {
+            "command": "test list",
+          },
+        ],
+        "description": "Next steps:",
+      }
+    `)
+  })
+
   describe('mcp over http', () => {
     function mcpCli() {
       const cli = Cli.create('test', { version: '1.0.0' })