incur 0.3.4 → 0.3.5

package/src/Completions.test.ts

@@ -294,27 +294,24 @@ describe('completions built-in command', () => {
     expect(output).toMatchInlineSnapshot(`
       "mycli completions — Generate shell completion script
 
-      Usage: mycli completions <shell>
+      Usage: mycli completions <bash|fish|nushell|zsh>
 
-      Shells:
-        bash
-        fish
-        nushell
-        zsh
+      Arguments:
+        shell  Shell to generate completions for
 
       Setup:
         bash     eval "$(mycli completions bash)"  # add to ~/.bashrc
-        zsh      eval "$(mycli completions zsh)"   # add to ~/.zshrc
         fish     mycli completions fish | source   # add to ~/.config/fish/config.fish
         nushell  see \`mycli completions nushell\`   # add to config.nu
+        zsh      eval "$(mycli completions zsh)"   # add to ~/.zshrc
       "
     `)
   })
 
-  test('errors on missing shell argument', async () => {
+  test('shows help on missing shell argument', async () => {
     const cli = makeCli()
     const output = await serve(cli, ['completions'])
-    expect(output).toContain('Missing shell argument')
+    expect(output).toContain('Generate shell completion script')
   })
 
   test('errors on unknown shell', async () => {
@@ -391,6 +388,35 @@ describe('serve integration', () => {
     expect(output).toContain('db')
   })
 
+  test('COMPLETE=bash includes built-in commands at root', async () => {
+    const cli = makeCli()
+    const output = await serve(cli, ['--', 'mycli', ''], {
+      COMPLETE: 'bash',
+      _COMPLETE_INDEX: '1',
+    })
+    expect(output).toContain('completions')
+    expect(output).toContain('mcp')
+    expect(output).toContain('skills')
+  })
+
+  test('COMPLETE=bash suggests add for skills subcommand', async () => {
+    const cli = makeCli()
+    const output = await serve(cli, ['--', 'mycli', 'skills', ''], {
+      COMPLETE: 'bash',
+      _COMPLETE_INDEX: '2',
+    })
+    expect(output).toContain('add')
+  })
+
+  test('COMPLETE=bash suggests add for mcp subcommand', async () => {
+    const cli = makeCli()
+    const output = await serve(cli, ['--', 'mycli', 'mcp', ''], {
+      COMPLETE: 'bash',
+      _COMPLETE_INDEX: '2',
+    })
+    expect(output).toContain('add')
+  })
+
   test('COMPLETE=zsh with words outputs candidates in zsh format', async () => {
     const cli = makeCli()
     const output = await serve(cli, ['--', 'mycli', '--'], {

package/src/Completions.ts

@@ -1,7 +1,6 @@
 import type { z } from 'zod'
 
-/** Supported shells for completion generation. */
-export type Shell = 'bash' | 'fish' | 'nushell' | 'zsh'
+import type { Shell } from './internal/command.js'
 
 /** A completion candidate with an optional description. */
 export type Candidate = {

package/src/Help.test.ts

@@ -88,6 +88,17 @@ describe('formatCommand', () => {
     `)
   })
 
+  test('synopsis uses key name for non-union args and expanded values for enums', () => {
+    const result = Help.formatCommand('tool run', {
+      args: z.object({
+        port: z.number().describe('Port number'),
+        verbose: z.boolean().optional().describe('Verbose'),
+        mode: z.enum(['fast', 'slow']).describe('Mode'),
+      }),
+    })
+    expect(result).toContain('Usage: tool run <port> [verbose] <fast|slow>')
+  })
+
   test('shows count type in help for meta count', () => {
     const result = Help.formatCommand('tool run', {
       options: z.object({

package/src/Help.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
 
+import { builtinCommands } from './internal/command.js'
+
 /** Formats help text for a router CLI or command group. */
 export function formatRoot(name: string, options: formatRoot.Options = {}): string {
   const { aliases, description, version, commands = [], root = false } = options
@@ -67,6 +69,8 @@ export declare namespace formatCommand {
     examples?: { command: string; description?: string }[] | undefined
     /** Plain text hint displayed after examples and before global options. */
     hint?: string | undefined
+    /** Hide global options section. */
+    hideGlobalOptions?: boolean | undefined
     /** Zod schema for named options/flags. */
     options?: z.ZodObject<any> | undefined
     /** Show root-level built-in commands and flags. */
@@ -195,7 +199,7 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
     }
   }
 
-  lines.push(...globalOptionsLines(root))
+  if (!options.hideGlobalOptions) lines.push(...globalOptionsLines(root))
 
   // Environment Variables
   if (env) {
@@ -223,8 +227,11 @@ export function formatCommand(name: string, options: formatCommand.Options = {})
 function buildSynopsis(name: string, args?: z.ZodObject<any>): string {
   if (!args) return name
   const parts = [name]
-  for (const [key, schema] of Object.entries(args.shape))
-    parts.push((schema as z.ZodType)._zod.optout === 'optional' ? `[${key}]` : `<${key}>`)
+  for (const [key, schema] of Object.entries(args.shape)) {
+    const type = resolveTypeName(schema)
+    const label = type.includes('|') ? type : key
+    parts.push((schema as z.ZodType)._zod.optout === 'optional' ? `[${label}]` : `<${label}>`)
+  }
   return parts.join(' ')
 }
 
@@ -330,15 +337,19 @@ function globalOptionsLines(root = false): string[] {
   const lines: string[] = []
 
   if (root) {
-    const builtins = [
-      { name: 'completions', desc: 'Generate shell completion script' },
-      { name: 'mcp add', desc: 'Register as MCP server' },
-      { name: 'skills add', desc: 'Sync skill files to agents' },
-    ]
+    const builtins = builtinCommands.flatMap((b) => {
+      if (!b.subcommands) return [{ name: b.name, desc: b.description }]
+      if (b.subcommands.length === 1)
+        return [
+          { name: `${b.name} ${b.subcommands[0]!.name}`, desc: b.subcommands[0]!.description },
+        ]
+      const names = b.subcommands.map((s) => s.name).join(', ')
+      return [{ name: b.name, desc: `${b.description} (${names})` }]
+    })
     const maxCmd = Math.max(...builtins.map((b) => b.name.length))
     lines.push(
       '',
-      'Built-in Commands:',
+      'Integrations:',
       ...builtins.map((b) => `  ${b.name}${' '.repeat(maxCmd - b.name.length)}  ${b.desc}`),
     )
   }

package/src/Mcp.test.ts

@@ -216,6 +216,149 @@ describe('Mcp', () => {
     ])
   })
 
+  test('middleware runs for tool calls', async () => {
+    const commands = new Map<string, any>()
+    commands.set('secret', {
+      description: 'Protected command',
+      run: () => ({ secret: 'data' }),
+    })
+    const middlewares = [
+      async (_c: any, next: () => Promise<void>) => {
+        _c.set('ran', true)
+        await next()
+      },
+    ]
+    const input = new PassThrough()
+    const output = new PassThrough()
+    const chunks: string[] = []
+    output.on('data', (chunk: Buffer) => chunks.push(chunk.toString()))
+
+    const done = Mcp.serve('test-cli', '1.0.0', commands, {
+      input,
+      output,
+      middlewares,
+      vars: z.object({ ran: z.boolean().default(false) }),
+    })
+
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: initParams })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 10))
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'secret', arguments: {} } })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 20))
+    input.end()
+    await done
+
+    const responses = chunks.map((c) => JSON.parse(c.trim()))
+    const callRes = responses.find((r: any) => r.id === 2)
+    expect(callRes.result.content).toEqual([{ type: 'text', text: '{"secret":"data"}' }])
+  })
+
+  test('middleware error blocks tool call', async () => {
+    const commands = new Map<string, any>()
+    commands.set('secret', {
+      description: 'Protected',
+      run: () => ({ secret: true }),
+    })
+    const middlewares = [
+      (c: any) => {
+        c.error({ code: 'FORBIDDEN', message: 'not allowed' })
+      },
+    ]
+    const input = new PassThrough()
+    const output = new PassThrough()
+    const chunks: string[] = []
+    output.on('data', (chunk: Buffer) => chunks.push(chunk.toString()))
+
+    const done = Mcp.serve('test-cli', '1.0.0', commands, {
+      input,
+      output,
+      middlewares,
+    })
+
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: initParams })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 10))
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'secret', arguments: {} } })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 20))
+    input.end()
+    await done
+
+    const responses = chunks.map((c) => JSON.parse(c.trim()))
+    const callRes = responses.find((r: any) => r.id === 2)
+    expect(callRes.result.isError).toBe(true)
+    expect(callRes.result.content[0].text).toBe('not allowed')
+  })
+
+  test('group middleware runs for nested tool calls', async () => {
+    const commands = new Map<string, any>()
+    const groupMiddleware = async (c: any, next: () => Promise<void>) => {
+      c.set('group', 'admin')
+      await next()
+    }
+    commands.set('admin', {
+      _group: true,
+      description: 'Admin commands',
+      middlewares: [groupMiddleware],
+      commands: new Map([
+        [
+          'status',
+          {
+            description: 'Admin status',
+            run: (c: any) => ({ group: c.var.group }),
+          },
+        ],
+      ]),
+    })
+
+    const input = new PassThrough()
+    const output = new PassThrough()
+    const chunks: string[] = []
+    output.on('data', (chunk: Buffer) => chunks.push(chunk.toString()))
+
+    const done = Mcp.serve('test-cli', '1.0.0', commands, {
+      input,
+      output,
+      vars: z.object({ group: z.string().default('none') }),
+    })
+
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: initParams })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 10))
+    input.write(
+      `${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'admin_status', arguments: {} } })}\n`,
+    )
+    await new Promise((r) => setTimeout(r, 20))
+    input.end()
+    await done
+
+    const responses = chunks.map((c) => JSON.parse(c.trim()))
+    const callRes = responses.find((r: any) => r.id === 2)
+    expect(callRes.result.content).toEqual([{ type: 'text', text: '{"group":"admin"}' }])
+  })
+
+  test('env schema is parsed for tool calls', async () => {
+    const commands = new Map<string, any>()
+    commands.set('check-env', {
+      description: 'Check env',
+      env: z.object({ MY_VAR: z.string().default('default-val') }),
+      run: (c: any) => ({ val: c.env.MY_VAR }),
+    })
+
+    const [, res] = await mcpSession(commands, [
+      { id: 1, method: 'initialize', params: initParams },
+      { id: 2, method: 'tools/call', params: { name: 'check-env', arguments: {} } },
+    ])
+    const data = JSON.parse(res.result.content[0].text)
+    expect(data.val).toBe('default-val')
+  })
+
   test('streaming command sends progress notifications', async () => {
     const input = new PassThrough()
     const output = new PassThrough()

package/src/Mcp.ts

@@ -1,7 +1,10 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import type { Readable, Writable } from 'node:stream'
+import type { z } from 'zod'
 
+import * as Command from './internal/command.js'
+import type { Handler as MiddlewareHandler } from './middleware.js'
 import * as Schema from './Schema.js'
 
 /** Starts a stdio MCP server that exposes commands as tools. */
@@ -25,12 +28,20 @@ export async function serve(
       {
         ...(tool.description ? { description: tool.description } : undefined),
         ...(hasInput ? { inputSchema: mergedShape } : undefined),
-      },
+        ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : undefined),
+      } as never,
       async (...callArgs: any[]) => {
         // registerTool passes (args, extra) when inputSchema is set, (extra) when not
         const params = hasInput ? (callArgs[0] as Record<string, unknown>) : {}
         const extra = hasInput ? callArgs[1] : callArgs[0]
-        return callTool(tool, params, extra)
+        return callTool(tool, params, {
+          extra,
+          name,
+          version,
+          middlewares: options.middlewares,
+          env: options.env,
+          vars: options.vars,
+        })
       },
     )
   }
@@ -44,10 +55,18 @@ export async function serve(
 export declare namespace serve {
   /** Options for the MCP server. */
   type Options = {
+    /** CLI-level env schema. */
+    env?: z.ZodObject<any> | undefined
     /** Override input stream. Defaults to `process.stdin`. */
     input?: Readable | undefined
+    /** Middleware handlers registered on the root CLI. */
+    middlewares?: MiddlewareHandler[] | undefined
     /** Override output stream. Defaults to `process.stdout`. */
     output?: Writable | undefined
+    /** Vars schema for middleware variables. */
+    vars?: z.ZodObject<any> | undefined
+    /** CLI version string. */
+    version?: string | undefined
   }
 }
 
@@ -55,83 +74,73 @@ export declare namespace serve {
 export async function callTool(
   tool: ToolEntry,
   params: Record<string, unknown>,
-  extra?: {
-    _meta?: { progressToken?: string | number }
-    sendNotification?: (n: any) => Promise<void>
-  },
-): Promise<{ content: { type: 'text'; text: string }[]; isError?: boolean }> {
-  try {
-    const { args, options } = splitParams(params, tool.command)
-    const parsedArgs = tool.command.args ? tool.command.args.parse(args) : {}
-    const parsedOptions = tool.command.options ? tool.command.options.parse(options) : {}
-    const parsedEnv = tool.command.env ? tool.command.env.parse(process.env) : {}
-
-    const sentinel = Symbol.for('incur.sentinel')
-    const okFn = (data: unknown): never => ({ [sentinel]: 'ok', data }) as never
-    const errorFn = (opts: { code: string; message: string }): never =>
-      ({ [sentinel]: 'error', ...opts }) as never
-
-    const raw = tool.command.run({
-      args: parsedArgs,
-      env: parsedEnv,
-      options: parsedOptions,
-      ok: okFn,
-      error: errorFn,
-    })
-
+  options: {
+    extra?: {
+      _meta?: { progressToken?: string | number }
+      sendNotification?: (n: any) => Promise<void>
+    }
+    name?: string | undefined
+    version?: string | undefined
+    middlewares?: MiddlewareHandler[] | undefined
+    env?: z.ZodObject<any> | undefined
+    vars?: z.ZodObject<any> | undefined
+  } = {},
+): Promise<{ content: { type: 'text'; text: string }[]; structuredContent?: Record<string, unknown>; isError?: boolean }> {
+  const allMiddleware = [
+    ...(options.middlewares ?? []),
+    ...((tool.middlewares as MiddlewareHandler[] | undefined) ?? []),
+    ...((tool.command.middleware as MiddlewareHandler[] | undefined) ?? []),
+  ]
+
+  const result = await Command.execute(tool.command, {
+    agent: true,
+    argv: [],
+    env: options.env,
+    format: 'json',
+    formatExplicit: true,
+    inputOptions: params,
+    middlewares: allMiddleware,
+    name: options.name ?? tool.name,
+    parseMode: 'flat',
+    path: tool.name,
+    vars: options.vars,
+    version: options.version,
+  })
+
+  if ('stream' in result) {
     // Streaming: send progress notifications per chunk, then return buffered result
-    if (isAsyncGenerator(raw)) {
-      const chunks: unknown[] = []
-      const progressToken = extra?._meta?.progressToken
-      let i = 0
-      for await (const chunk of raw) {
-        if (typeof chunk === 'object' && chunk !== null && sentinel in chunk) {
-          const tagged = chunk as any
-          if (tagged[sentinel] === 'error')
-            return {
-              content: [{ type: 'text', text: tagged.message ?? 'Command failed' }],
-              isError: true,
-            }
-        }
+    const chunks: unknown[] = []
+    const progressToken = options.extra?._meta?.progressToken
+    let i = 0
+    try {
+      for await (const chunk of result.stream) {
         chunks.push(chunk)
-        if (progressToken !== undefined && extra?.sendNotification)
-          await extra.sendNotification({
+        if (progressToken !== undefined && options.extra?.sendNotification)
+          await options.extra.sendNotification({
             method: 'notifications/progress' as const,
             params: { progressToken, progress: ++i, message: JSON.stringify(chunk) },
           })
       }
-      return { content: [{ type: 'text', text: JSON.stringify(chunks) }] }
-    }
-
-    const awaited = await raw
-
-    if (typeof awaited === 'object' && awaited !== null && sentinel in awaited) {
-      const tagged = awaited as any
-      if (tagged[sentinel] === 'error')
-        return {
-          content: [{ type: 'text', text: tagged.message ?? 'Command failed' }],
-          isError: true,
-        }
-      return { content: [{ type: 'text', text: JSON.stringify(tagged.data ?? null) }] }
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],
+        isError: true,
+      }
     }
+    return { content: [{ type: 'text', text: JSON.stringify(chunks) }] }
+  }
 
-    return { content: [{ type: 'text', text: JSON.stringify(awaited ?? null) }] }
-  } catch (err) {
+  if (!result.ok)
     return {
-      content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],
+      content: [{ type: 'text', text: result.error.message ?? 'Command failed' }],
       isError: true,
     }
-  }
-}
 
-/** @internal Type guard for async generators. */
-function isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown, unknown, unknown> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    Symbol.asyncIterator in value &&
-    typeof (value as any).next === 'function'
-  )
+  const data = result.data ?? null
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data) }],
+    ...(data !== null && tool.outputSchema ? { structuredContent: data as Record<string, unknown> } : undefined),
+  }
 }
 
 /** @internal A resolved tool entry from the command tree. */
@@ -139,21 +148,34 @@ export type ToolEntry = {
   name: string
   description?: string | undefined
   inputSchema: { type: 'object'; properties: Record<string, unknown>; required?: string[] }
+  outputSchema?: Record<string, unknown> | undefined
   command: any
+  middlewares?: MiddlewareHandler[] | undefined
 }
 
 /** @internal Recursively collects leaf commands as tool entries. */
-export function collectTools(commands: Map<string, any>, prefix: string[]): ToolEntry[] {
+export function collectTools(
+  commands: Map<string, any>,
+  prefix: string[],
+  parentMiddlewares: MiddlewareHandler[] = [],
+): ToolEntry[] {
   const result: ToolEntry[] = []
   for (const [name, entry] of commands) {
     const path = [...prefix, name]
-    if ('_group' in entry && entry._group) result.push(...collectTools(entry.commands, path))
-    else {
+    if ('_group' in entry && entry._group) {
+      const groupMw = [
+        ...parentMiddlewares,
+        ...((entry.middlewares as MiddlewareHandler[] | undefined) ?? []),
+      ]
+      result.push(...collectTools(entry.commands, path, groupMw))
+    } else {
       result.push({
         name: path.join('_'),
         description: entry.description,
         inputSchema: buildToolSchema(entry.args, entry.options),
+        ...(entry.output ? { outputSchema: Schema.toJsonSchema(entry.output) as Record<string, unknown> } : undefined),
         command: entry,
+        ...(parentMiddlewares.length > 0 ? { middlewares: parentMiddlewares } : undefined),
       })
     }
   }
@@ -179,17 +201,3 @@ function buildToolSchema(
   return { type: 'object', properties }
 }
 
-/** @internal Splits flat params into args vs options using schema shapes. */
-function splitParams(
-  params: Record<string, unknown>,
-  command: any,
-): { args: Record<string, unknown>; options: Record<string, unknown> } {
-  const argKeys = new Set(command.args ? Object.keys(command.args.shape) : [])
-  const a: Record<string, unknown> = {}
-  const o: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(params)) {
-    if (argKeys.has(key)) a[key] = value
-    else o[key] = value
-  }
-  return { args: a, options: o }
-}

package/src/Skill.ts

@@ -127,7 +127,11 @@ function renderGroup(
       ? `${descParts.join('. ')}. Run \`${title} --help\` for usage details.`
       : `Run \`${title} --help\` for usage details.`
 
-  const slug = title.replace(/\s+/g, '-')
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '')
   const fm = ['---', `name: ${slug}`]
   fm.push(`description: ${description}`)
   fm.push(`requires_bin: ${cli}`)

package/src/SyncSkills.ts

@@ -150,7 +150,17 @@ function collectEntries(
 function resolvePackageRoot(): string {
   const bin = process.argv[1]
   if (!bin) return process.cwd()
-  let dir = path.dirname(fsSync.realpathSync(bin))
+  let dir = path.dirname(
+    (() => {
+      try {
+        // resolve symlinks for normal bin scripts
+        return fsSync.realpathSync(bin)
+      } catch {
+        // Bun compiled binaries use a virtual `/$bunfs/` path for argv[1]
+        return process.execPath
+      }
+    })(),
+  )
   const root = path.parse(dir).root
   while (dir !== root) {
     try {

package/src/e2e.test.ts

@@ -963,7 +963,7 @@ describe('help', () => {
         stream-throw   Stream that throws
         validate-fail  Fails validation
 
-      Built-in Commands:
+      Integrations:
         completions  Generate shell completion script
         mcp add      Register as MCP server
         skills add   Sync skill files to agents
@@ -1738,7 +1738,7 @@ describe('root command with subcommands', () => {
         info     Show info
         version  Show version
 
-      Built-in Commands:
+      Integrations:
         completions  Generate shell completion script
         mcp add      Register as MCP server
         skills add   Sync skill files to agents
@@ -2441,6 +2441,18 @@ describe('fetch api', () => {
           },
           "meta": {
             "command": "project create",
+            "cta": {
+              "commands": [
+                {
+                  "command": "app project get p-new",
+                  "description": "View "MyProject"",
+                },
+                {
+                  "command": "app project list",
+                },
+              ],
+              "description": "Suggested commands:",
+            },
             "duration": "<stripped>",
           },
           "ok": true,
@@ -2524,21 +2536,22 @@ describe('fetch api', () => {
     const cli = createApp()
     expect(await fetchJson(cli, new Request('http://localhost/explode-clac')))
       .toMatchInlineSnapshot(`
-      {
-        "body": {
-          "error": {
-            "code": "QUOTA_EXCEEDED",
-            "message": "Rate limit exceeded",
-          },
-          "meta": {
-            "command": "explode-clac",
-            "duration": "<stripped>",
+        {
+          "body": {
+            "error": {
+              "code": "QUOTA_EXCEEDED",
+              "message": "Rate limit exceeded",
+              "retryable": true,
+            },
+            "meta": {
+              "command": "explode-clac",
+              "duration": "<stripped>",
+            },
+            "ok": false,
           },
-          "ok": false,
-        },
-        "status": 500,
-      }
-    `)
+          "status": 500,
+        }
+      `)
   })
 
   test('validation error → 400', async () => {