incur 0.0.0 → 0.0.2

package/src/Mcp.ts

@@ -0,0 +1,195 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import type { Readable, Writable } from 'node:stream'
+
+import * as Schema from './Schema.js'
+
+/** Starts a stdio MCP server that exposes commands as tools. */
+export async function serve(
+  name: string,
+  version: string,
+  commands: Map<string, any>,
+  options: serve.Options = {},
+): Promise<void> {
+  const server = new McpServer({ name, version })
+
+  for (const tool of collectTools(commands, [])) {
+    const mergedShape: Record<string, any> = {
+      ...tool.command.args?.shape,
+      ...tool.command.options?.shape,
+    }
+    const hasInput = Object.keys(mergedShape).length > 0
+
+    server.registerTool(
+      tool.name,
+      {
+        ...(tool.description ? { description: tool.description } : undefined),
+        ...(hasInput ? { inputSchema: mergedShape } : undefined),
+      },
+      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)
+      },
+    )
+  }
+
+  const input = options.input ?? process.stdin
+  const output = options.output ?? process.stdout
+  const transport = new StdioServerTransport(input as any, output as any)
+  await server.connect(transport)
+}
+
+export declare namespace serve {
+  /** Options for the MCP server. */
+  type Options = {
+    /** Override input stream. Defaults to `process.stdin`. */
+    input?: Readable | undefined
+    /** Override output stream. Defaults to `process.stdout`. */
+    output?: Writable | undefined
+  }
+}
+
+/** @internal Executes a tool call and returns a CallToolResult. */
+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,
+    })
+
+    // 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,
+            }
+        }
+        chunks.push(chunk)
+        if (progressToken !== undefined && extra?.sendNotification)
+          await 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) }] }
+    }
+
+    return { content: [{ type: 'text', text: JSON.stringify(awaited) }] }
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],
+      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'
+  )
+}
+
+/** @internal A resolved tool entry from the command tree. */
+type ToolEntry = {
+  name: string
+  description?: string | undefined
+  inputSchema: { type: 'object'; properties: Record<string, unknown>; required?: string[] }
+  command: any
+}
+
+/** @internal Recursively collects leaf commands as tool entries. */
+function collectTools(commands: Map<string, any>, prefix: string[]): 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 {
+      result.push({
+        name: path.join('_'),
+        description: entry.description,
+        inputSchema: buildToolSchema(entry.args, entry.options),
+        command: entry,
+      })
+    }
+  }
+  return result.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/** @internal Builds a merged JSON Schema from args and options Zod schemas. */
+function buildToolSchema(
+  args: any | undefined,
+  options: any | undefined,
+): { type: 'object'; properties: Record<string, unknown>; required?: string[] } {
+  const properties: Record<string, unknown> = {}
+  const required: string[] = []
+
+  for (const schema of [args, options]) {
+    if (!schema) continue
+    const json = Schema.toJsonSchema(schema)
+    Object.assign(properties, (json.properties as Record<string, unknown>) ?? {})
+    required.push(...((json.required as string[]) ?? []))
+  }
+
+  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/Parser.test-d.ts

@@ -0,0 +1,45 @@
+import { Parser, z } from 'incur'
+import { expectTypeOf, test } from 'vitest'
+
+test('narrows args from schema', () => {
+  const result = Parser.parse(['hello'], {
+    args: z.object({ name: z.string() }),
+  })
+  expectTypeOf(result.args).toEqualTypeOf<{ name: string }>()
+})
+
+test('narrows options from schema', () => {
+  const result = Parser.parse(['--state', 'open'], {
+    options: z.object({ state: z.string() }),
+  })
+  expectTypeOf(result.options).toEqualTypeOf<{ state: string }>()
+})
+
+test('defaults to empty objects when no schemas', () => {
+  const result = Parser.parse([])
+  expectTypeOf(result.args).toEqualTypeOf<{}>()
+  expectTypeOf(result.options).toEqualTypeOf<{}>()
+})
+
+test('z.output reflects .default() as non-optional', () => {
+  const result = Parser.parse([], {
+    options: z.object({ limit: z.number().default(30) }),
+  })
+  expectTypeOf(result.options).toEqualTypeOf<{ limit: number }>()
+})
+
+test('z.output reflects .optional() as optional', () => {
+  const result = Parser.parse([], {
+    options: z.object({ verbose: z.boolean().optional() }),
+  })
+  expectTypeOf(result.options).toEqualTypeOf<{ verbose?: boolean | undefined }>()
+})
+
+test('narrows both args and options together', () => {
+  const result = Parser.parse(['myrepo', '--limit', '5'], {
+    args: z.object({ repo: z.string() }),
+    options: z.object({ limit: z.number() }),
+  })
+  expectTypeOf(result.args).toEqualTypeOf<{ repo: string }>()
+  expectTypeOf(result.options).toEqualTypeOf<{ limit: number }>()
+})

package/src/Parser.test.ts

@@ -0,0 +1,118 @@
+import { Parser, z } from 'incur'
+
+describe('parse', () => {
+  test('returns empty args and options when no schemas', () => {
+    expect(Parser.parse([])).toEqual({ args: {}, options: {} })
+  })
+
+  test('parses positional args in schema key order', () => {
+    const result = Parser.parse(['hello', 'world'], {
+      args: z.object({ greeting: z.string(), name: z.string() }),
+    })
+    expect(result.args).toEqual({ greeting: 'hello', name: 'world' })
+  })
+
+  test('parses --flag value options', () => {
+    const result = Parser.parse(['--state', 'open'], {
+      options: z.object({ state: z.string() }),
+    })
+    expect(result.options).toEqual({ state: 'open' })
+  })
+
+  test('parses --flag=value syntax', () => {
+    const result = Parser.parse(['--state=closed'], {
+      options: z.object({ state: z.string() }),
+    })
+    expect(result.options).toEqual({ state: 'closed' })
+  })
+
+  test('parses -f value short aliases', () => {
+    const result = Parser.parse(['-s', 'open'], {
+      options: z.object({ state: z.string() }),
+      alias: { state: 's' },
+    })
+    expect(result.options).toEqual({ state: 'open' })
+  })
+
+  test('parses --verbose as true', () => {
+    const result = Parser.parse(['--verbose'], {
+      options: z.object({ verbose: z.boolean() }),
+    })
+    expect(result.options).toEqual({ verbose: true })
+  })
+
+  test('parses --no-verbose as false', () => {
+    const result = Parser.parse(['--no-verbose'], {
+      options: z.object({ verbose: z.boolean() }),
+    })
+    expect(result.options).toEqual({ verbose: false })
+  })
+
+  test('parses repeated flags as array', () => {
+    const result = Parser.parse(['--label', 'bug', '--label', 'feature'], {
+      options: z.object({ label: z.array(z.string()) }),
+    })
+    expect(result.options).toEqual({ label: ['bug', 'feature'] })
+  })
+
+  test('coerces string to number', () => {
+    const result = Parser.parse(['--limit', '10'], {
+      options: z.object({ limit: z.number() }),
+    })
+    expect(result.options).toEqual({ limit: 10 })
+  })
+
+  test('coerces string to boolean', () => {
+    const result = Parser.parse(['--dry', 'true'], {
+      options: z.object({ dry: z.boolean() }),
+    })
+    expect(result.options).toEqual({ dry: true })
+  })
+
+  test('applies default values for missing options', () => {
+    const result = Parser.parse([], {
+      options: z.object({ limit: z.number().default(30) }),
+    })
+    expect(result.options).toEqual({ limit: 30 })
+  })
+
+  test('allows optional fields to be omitted', () => {
+    const result = Parser.parse([], {
+      options: z.object({ verbose: z.boolean().optional() }),
+    })
+    expect(result.options).toEqual({})
+  })
+
+  test('throws ParseError on unknown flags', () => {
+    expect(() =>
+      Parser.parse(['--unknown', 'val'], {
+        options: z.object({ state: z.string() }),
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ParseError' }))
+  })
+
+  test('throws ValidationError on missing required positional args', () => {
+    expect(() =>
+      Parser.parse([], {
+        args: z.object({ name: z.string() }),
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ValidationError' }))
+  })
+
+  test('throws ValidationError on enum mismatch', () => {
+    expect(() =>
+      Parser.parse(['--state', 'invalid'], {
+        options: z.object({ state: z.enum(['open', 'closed']) }),
+      }),
+    ).toThrow(expect.objectContaining({ name: 'Incur.ValidationError' }))
+  })
+
+  test('parses positional args and options together', () => {
+    const result = Parser.parse(['myrepo', '--limit', '5'], {
+      args: z.object({ repo: z.string() }),
+      options: z.object({ limit: z.number() }),
+    })
+    expect(result.args).toEqual({ repo: 'myrepo' })
+    expect(result.options).toEqual({ limit: 5 })
+  })
+})

package/src/Parser.ts

@@ -0,0 +1,247 @@
+import type { z } from 'zod'
+
+import type { FieldError } from './Errors.js'
+import { ParseError, ValidationError } from './Errors.js'
+
+/** Parses raw argv tokens against Zod schemas for args and options. */
+export function parse<
+  const args extends z.ZodObject<any> | undefined = undefined,
+  const options extends z.ZodObject<any> | undefined = undefined,
+>(argv: string[], options: parse.Options<args, options> = {}): parse.ReturnType<args, options> {
+  const { args: argsSchema, options: optionsSchema, alias } = options
+
+  // Build reverse alias map: short char → long name
+  const aliasToName = new Map<string, string>()
+  if (alias) for (const [name, short] of Object.entries(alias)) aliasToName.set(short, name)
+
+  // Known option names from schema, plus kebab-case → camelCase map
+  const knownOptions = new Set(optionsSchema ? Object.keys(optionsSchema.shape) : [])
+  const kebabToCamel = new Map<string, string>()
+  for (const name of knownOptions) {
+    const kebab = name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+    if (kebab !== name) kebabToCamel.set(kebab, name)
+  }
+
+  // First pass: split argv into positional tokens and raw option values
+  const positionals: string[] = []
+  const rawOptions: Record<string, unknown> = {}
+
+  let i = 0
+  while (i < argv.length) {
+    const token = argv[i]!
+
+    if (token.startsWith('--no-') && token.length > 5) {
+      // --no-flag negation
+      const raw = token.slice(5)
+      const name = kebabToCamel.get(raw) ?? raw
+      if (!knownOptions.has(name)) throw new ParseError({ message: `Unknown flag: ${token}` })
+      rawOptions[name] = false
+      i++
+    } else if (token.startsWith('--')) {
+      const eqIdx = token.indexOf('=')
+      if (eqIdx !== -1) {
+        // --flag=value
+        const raw = token.slice(2, eqIdx)
+        const name = kebabToCamel.get(raw) ?? raw
+        if (!knownOptions.has(name)) throw new ParseError({ message: `Unknown flag: --${raw}` })
+        setOption(rawOptions, name, token.slice(eqIdx + 1), optionsSchema)
+        i++
+      } else {
+        // --flag [value]
+        const raw = token.slice(2)
+        const name = kebabToCamel.get(raw) ?? raw
+        if (!knownOptions.has(name)) throw new ParseError({ message: `Unknown flag: ${token}` })
+        if (isBooleanOption(name, optionsSchema)) {
+          rawOptions[name] = true
+          i++
+        } else {
+          const value = argv[i + 1]
+          if (value === undefined)
+            throw new ParseError({ message: `Missing value for flag: ${token}` })
+          setOption(rawOptions, name, value, optionsSchema)
+          i += 2
+        }
+      }
+    } else if (token.startsWith('-') && token.length === 2) {
+      // -f [value]
+      const short = token.slice(1)
+      const name = aliasToName.get(short)
+      if (!name) throw new ParseError({ message: `Unknown flag: ${token}` })
+      if (isBooleanOption(name, optionsSchema)) {
+        rawOptions[name] = true
+        i++
+      } else {
+        const value = argv[i + 1]
+        if (value === undefined)
+          throw new ParseError({ message: `Missing value for flag: ${token}` })
+        setOption(rawOptions, name, value, optionsSchema)
+        i += 2
+      }
+    } else {
+      positionals.push(token)
+      i++
+    }
+  }
+
+  // Assign positionals to args schema keys in order
+  const rawArgs: Record<string, string> = {}
+  if (argsSchema) {
+    const keys = Object.keys(argsSchema.shape)
+    for (let j = 0; j < keys.length; j++) {
+      const key = keys[j]!
+      if (positionals[j] !== undefined) {
+        rawArgs[key] = positionals[j]!
+      }
+    }
+  }
+
+  // Validate args through zod
+  const args = argsSchema ? zodParse(argsSchema, rawArgs) : {}
+
+  // Coerce raw option values before zod validation
+  if (optionsSchema) {
+    for (const [name, value] of Object.entries(rawOptions)) {
+      rawOptions[name] = coerce(value, name, optionsSchema)
+    }
+  }
+
+  // Validate options through zod
+  const parsedOptions = optionsSchema ? zodParse(optionsSchema, rawOptions) : {}
+
+  return { args, options: parsedOptions } as parse.ReturnType<args, options>
+}
+
+export declare namespace parse {
+  /** Options for parsing. */
+  type Options<
+    args extends z.ZodObject<any> | undefined = undefined,
+    options extends z.ZodObject<any> | undefined = undefined,
+  > = {
+    /** Zod schema for positional arguments. Keys define order. */
+    args?: args
+    /** Zod schema for named options/flags. */
+    options?: options
+    /** Map of option names to single-char aliases. */
+    alias?: Record<string, string> | undefined
+  }
+  /** Parsed result with args and options. */
+  type ReturnType<
+    args extends z.ZodObject<any> | undefined = undefined,
+    options extends z.ZodObject<any> | undefined = undefined,
+  > = {
+    /** Parsed positional arguments. */
+    args: args extends z.ZodObject<any> ? z.output<args> : {}
+    /** Parsed named options. */
+    options: options extends z.ZodObject<any> ? z.output<options> : {}
+  }
+}
+
+/** Unwraps ZodDefault/ZodOptional to get the inner type. */
+function unwrap(schema: z.ZodType): z.ZodType {
+  let s = schema as any
+  while (s._zod?.def?.innerType) s = s._zod.def.innerType
+  return s
+}
+
+/** Checks if an option's inner type is boolean. */
+function isBooleanOption(name: string, schema: z.ZodObject<any> | undefined): boolean {
+  if (!schema) return false
+  const field = schema.shape[name]
+  if (!field) return false
+  return unwrap(field).constructor.name === 'ZodBoolean'
+}
+
+/** Checks if an option's inner type is an array. */
+function isArrayOption(name: string, schema: z.ZodObject<any> | undefined): boolean {
+  if (!schema) return false
+  const field = schema.shape[name]
+  if (!field) return false
+  return unwrap(field).constructor.name === 'ZodArray'
+}
+
+/** Sets an option value, collecting into arrays for array schemas. */
+function setOption(
+  raw: Record<string, unknown>,
+  name: string,
+  value: string,
+  schema: z.ZodObject<any> | undefined,
+) {
+  if (isArrayOption(name, schema)) {
+    const existing = raw[name]
+    if (Array.isArray(existing)) {
+      existing.push(value)
+    } else {
+      raw[name] = [value]
+    }
+  } else {
+    raw[name] = value
+  }
+}
+
+/** Wraps zod schema.parse(), converting ZodError to ValidationError. */
+function zodParse(schema: z.ZodObject<any>, data: Record<string, unknown>) {
+  try {
+    return schema.parse(data)
+  } catch (err: any) {
+    const issues: any[] = err?.issues ?? err?.error?.issues ?? []
+    const fieldErrors: FieldError[] = issues.map((issue: any) => ({
+      path: (issue.path ?? []).join('.'),
+      expected: issue.expected ?? '',
+      received: issue.received ?? '',
+      message: issue.message ?? '',
+    }))
+    throw new ValidationError({
+      message: issues.map((i: any) => i.message).join('; ') || 'Validation failed',
+      fieldErrors,
+      cause: err instanceof Error ? err : undefined,
+    })
+  }
+}
+
+/** Parses environment variables against a Zod schema. Falls back to `process.env` → `Deno.env` when no source is provided. */
+export function parseEnv<const env extends z.ZodObject<any>>(
+  schema: env,
+  source: Record<string, string | undefined> = defaultEnvSource(),
+): z.output<env> {
+  const raw: Record<string, unknown> = {}
+  for (const [key, field] of Object.entries(schema.shape)) {
+    const value = source[key]
+    if (value !== undefined) raw[key] = coerceEnv(value, field as z.ZodType)
+  }
+  return zodParse(schema, raw) as z.output<env>
+}
+
+/** Coerces an env var string to the type expected by the schema field. */
+function coerceEnv(value: string, field: z.ZodType): unknown {
+  const inner = unwrap(field)
+  const typeName = inner.constructor.name
+  if (typeName === 'ZodNumber') return Number(value)
+  if (typeName === 'ZodBoolean') return value === 'true' || value === '1'
+  return value
+}
+
+/** Coerces a raw string value to the type expected by the schema. */
+function coerce(value: unknown, name: string, schema: z.ZodObject<any>): unknown {
+  const field = schema.shape[name]
+  if (!field) return value
+  const inner = unwrap(field)
+  const typeName = inner.constructor.name
+
+  if (typeName === 'ZodNumber' && typeof value === 'string') {
+    return Number(value)
+  }
+  if (typeName === 'ZodBoolean' && typeof value === 'string') {
+    return value === 'true'
+  }
+  return value
+}
+
+/** Returns the best available env source for the current runtime. */
+function defaultEnvSource(): Record<string, string | undefined> {
+  if (typeof globalThis !== 'undefined') {
+    const g = globalThis as any
+    if (g.process?.env) return g.process.env
+    if (g.Deno?.env) return new Proxy({}, { get: (_, key) => g.Deno.env.get(key) }) as any
+  }
+  return {}
+}

package/src/Register.ts

@@ -0,0 +1,18 @@
+/**
+ * Type-safe registration interface. Populate via declaration merging or codegen to enable CTA autocomplete.
+ *
+ * @example
+ * ```ts
+ * // codegen: run `mycli --codegen` to generate this file
+ * declare module 'incur' {
+ *   interface Register {
+ *     commands: {
+ *       get: { args: { id: number }; options: {} }
+ *       list: { args: {}; options: { limit: number } }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: populated via declaration merging
+export interface Register {}