incur 0.4.0 → 0.4.2

package/src/Mcp.ts

@@ -1,7 +1,9 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server'
 import type { Readable, Writable } from 'node:stream'
+import { 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. */
@@ -24,13 +26,22 @@ export async function serve(
       tool.name,
       {
         ...(tool.description ? { description: tool.description } : undefined),
-        ...(hasInput ? { inputSchema: mergedShape } : undefined),
-      },
+        ...(hasInput ? { inputSchema: z.object(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,
+          sendNotification: (n) => server.server.notification(n),
+          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,85 @@ 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?: {
+      mcpReq?: { _meta?: { progressToken?: string | number } }
+    }
+    sendNotification?: (n: ProgressNotification) => 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?.mcpReq?._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.sendNotification)
+          await options.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,
     }
+
+  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 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'
-  )
+/** @internal A progress notification sent during streaming tool calls. */
+type ProgressNotification = {
+  method: 'notifications/progress'
+  params: { progressToken: string | number; progress: number; message: string }
 }
 
 /** @internal A resolved tool entry from the command tree. */
@@ -139,21 +160,37 @@ 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) {
+    if ('_alias' in entry) continue
     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),
       })
     }
   }
@@ -178,18 +215,3 @@ function buildToolSchema(
   if (required.length > 0) return { type: 'object', properties, required }
   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/Openapi.test.ts

@@ -1,4 +1,9 @@
-import { describe, expect, test } from 'vitest'
+import { describe, expect, test, vi } from 'vitest'
+
+vi.mock('./SyncSkills.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./SyncSkills.js')>()
+  return { ...actual, readHash: () => undefined }
+})
 
 import { app as prefixedApp } from '../test/fixtures/hono-api-prefixed.js'
 import { app } from '../test/fixtures/hono-api.js'
@@ -42,6 +47,13 @@ describe('generateCommands', () => {
     const cmd = commands.get('listUsers')!
     expect(cmd.description).toBe('List users')
   })
+
+  test('coerced number params preserve description', async () => {
+    const commands = await Openapi.generateCommands(spec, app.fetch)
+    const cmd = commands.get('listUsers')!
+    const limitSchema = cmd.options!.shape.limit
+    expect(limitSchema.description).toBe('Max results')
+  })
 })
 
 describe('cli integration', () => {
@@ -130,11 +142,11 @@ describe('cli integration', () => {
     expect(json(output)).toEqual({ ok: true })
   })
 
-  test('--verbose wraps in envelope', async () => {
+  test('--full-output wraps in envelope', async () => {
     const { output } = await serve(createCli(), [
       'api',
       'healthCheck',
-      '--verbose',
+      '--full-output',
       '--format',
       'json',
     ])
@@ -242,11 +254,11 @@ describe('@hono/zod-openapi integration', () => {
     expect(json(output)).toEqual({ ok: true })
   })
 
-  test('--verbose wraps in envelope', async () => {
+  test('--full-output wraps in envelope', async () => {
     const { output } = await serve(createCli(), [
       'api',
       'healthCheck',
-      '--verbose',
+      '--full-output',
       '--format',
       'json',
     ])

package/src/Openapi.ts

@@ -1,7 +1,7 @@
-import { dereference } from '@readme/openapi-parser'
 import { z } from 'zod'
 
 import * as Fetch from './Fetch.js'
+import { dereference } from './internal/dereference.js'
 
 /** A minimal OpenAPI 3.x spec shape. Accepts both hand-written specs and generated ones (e.g. from `@hono/zod-openapi`). */
 export type OpenAPISpec = { paths?: {} | undefined }
@@ -46,7 +46,7 @@ export async function generateCommands(
   fetch: FetchHandler,
   options: { basePath?: string | undefined } = {},
 ): Promise<Map<string, GeneratedCommand>> {
-  const resolved = (await dereference(structuredClone(spec) as any)) as unknown as OpenAPISpec
+  const resolved = dereference(structuredClone(spec)) as OpenAPISpec
   const commands = new Map<string, GeneratedCommand>()
   const paths = (resolved.paths ?? {}) as Record<string, Record<string, unknown>>
 
@@ -186,20 +186,26 @@ function coerceIfNeeded(schema: z.ZodType): z.ZodType {
   const isOptional = schema instanceof z.ZodOptional
   const inner = isOptional ? schema.unwrap() : schema
 
-  // Direct number/boolean
-  if (inner instanceof z.ZodNumber)
-    return isOptional ? z.coerce.number().optional() : z.coerce.number()
-  if (inner instanceof z.ZodBoolean)
-    return isOptional ? z.coerce.boolean().optional() : z.coerce.boolean()
-
-  // Union containing number (e.g. type: ["number", "null"] from OpenAPI 3.1)
-  if (inner instanceof z.ZodUnion) {
-    const options = (inner as any)._zod?.def?.options as z.ZodType[] | undefined
-    if (options?.some((o: z.ZodType) => o instanceof z.ZodNumber))
+  const coerced = (() => {
+    // Direct number
+    if (inner instanceof z.ZodNumber)
       return isOptional ? z.coerce.number().optional() : z.coerce.number()
-    if (options?.some((o: z.ZodType) => o instanceof z.ZodBoolean))
+    // Direct boolean
+    if (inner instanceof z.ZodBoolean)
       return isOptional ? z.coerce.boolean().optional() : z.coerce.boolean()
-  }
+    // Union containing number or boolean (e.g. type: ["number", "null"] from OpenAPI 3.1)
+    if (inner instanceof z.ZodUnion) {
+      const options = (inner as any)._zod?.def?.options as z.ZodType[] | undefined
+      if (options?.some((o: z.ZodType) => o instanceof z.ZodNumber))
+        return isOptional ? z.coerce.number().optional() : z.coerce.number()
+      if (options?.some((o: z.ZodType) => o instanceof z.ZodBoolean))
+        return isOptional ? z.coerce.boolean().optional() : z.coerce.boolean()
+    }
+    // No coercion needed
+    return undefined
+  })()
 
-  return schema
+  if (!coerced) return schema
+  const desc = (schema as any).description ?? (inner as any).description
+  return desc ? coerced.describe(desc) : coerced
 }

package/src/Parser.test-d.ts

@@ -43,3 +43,25 @@ test('narrows both args and options together', () => {
   expectTypeOf(result.args).toEqualTypeOf<{ repo: string }>()
   expectTypeOf(result.options).toEqualTypeOf<{ limit: number }>()
 })
+
+test('defaults are typed from z.input of the options schema', () => {
+  const result = Parser.parse([], {
+    defaults: { limit: '5' },
+    options: z.object({ limit: z.coerce.number().default(30) }),
+  })
+  expectTypeOf(result.options).toEqualTypeOf<{ limit: number }>()
+})
+
+test('defaults do not leak any', () => {
+  type Options = z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>
+    saveDev: z.ZodOptional<z.ZodBoolean>
+  }>
+
+  expectTypeOf<Parser.parse.Options<undefined, Options>>().toEqualTypeOf<{
+    args?: undefined
+    alias?: Record<string, string> | undefined
+    defaults?: Partial<z.input<Options>> | undefined
+    options?: Options
+  }>()
+})

package/src/Parser.test.ts

@@ -252,4 +252,93 @@ describe('parse', () => {
     expect(result.args).toEqual({ repo: 'myrepo' })
     expect(result.options).toEqual({ limit: 5 })
   })
+
+  test('applies config defaults when argv omits an option', () => {
+    const result = Parser.parse([], {
+      defaults: { limit: 10 },
+      options: z.object({ limit: z.number().default(30) }),
+    })
+    expect(result.options).toEqual({ limit: 10 })
+  })
+
+  test('argv overrides config defaults', () => {
+    const result = Parser.parse(['--limit', '5'], {
+      defaults: { limit: 10 },
+      options: z.object({ limit: z.number().default(30) }),
+    })
+    expect(result.options).toEqual({ limit: 5 })
+  })
+
+  test('argv arrays replace config arrays', () => {
+    const result = Parser.parse(['--label', 'bug', '--label', 'feature'], {
+      defaults: { label: ['ops'] },
+      options: z.object({ label: z.array(z.string()).default([]) }),
+    })
+    expect(result.options).toEqual({ label: ['bug', 'feature'] })
+  })
+
+  test('kebab-case config keys map to camelCase schema names', () => {
+    const result = Parser.parse([], {
+      defaults: { 'save-dev': true } as any,
+      options: z.object({ saveDev: z.boolean().default(false) }),
+    })
+    expect(result.options).toEqual({ saveDev: true })
+  })
+
+  test('throws ParseError on unknown config option keys', () => {
+    expect(() =>
+      Parser.parse([], {
+        defaults: { missing: true } as any,
+        options: z.object({ saveDev: z.boolean().default(false) }),
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ParseError' }))
+  })
+
+  test('throws ValidationError for invalid config defaults when argv does not override them', () => {
+    expect(() =>
+      Parser.parse([], {
+        defaults: { limit: 'oops' } as any,
+        options: z.object({ limit: z.number() }),
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ValidationError' }))
+  })
+
+  test('argv overrides invalid config defaults', () => {
+    const result = Parser.parse(['--limit', '5'], {
+      defaults: { limit: 'oops' } as any,
+      options: z.object({ limit: z.number() }),
+    })
+    expect(result.options).toEqual({ limit: 5 })
+  })
+
+  test('defaults with no options schema throws on non-empty defaults', () => {
+    expect(() =>
+      Parser.parse([], {
+        defaults: { limit: 10 } as any,
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ParseError' }))
+  })
+
+  test('defaults with no options schema and empty defaults is a no-op', () => {
+    const result = Parser.parse([], { defaults: {} as any })
+    expect(result.options).toEqual({})
+  })
+
+  test('config array defaults are used when argv omits the option', () => {
+    const result = Parser.parse([], {
+      defaults: { label: ['bug', 'feature'] },
+      options: z.object({ label: z.array(z.string()).default([]) }),
+    })
+    expect(result.options).toEqual({ label: ['bug', 'feature'] })
+  })
+
+  test('refined option schemas validate only the merged winning values', () => {
+    const result = Parser.parse(['--min', '1', '--max', '3'], {
+      defaults: { min: 'oops' } as any,
+      options: z
+        .object({ min: z.number(), max: z.number() })
+        .refine((value) => value.min < value.max, { message: 'min must be less than max' }),
+    })
+    expect(result.options).toEqual({ min: 1, max: 3 })
+  })
 })