incur 0.0.0 → 0.0.2

package/src/Errors.test.ts

@@ -0,0 +1,96 @@
+import { Errors } from 'incur'
+
+describe('BaseError', () => {
+  test('extends Error and sets name', () => {
+    const error = new Errors.BaseError('something went wrong')
+    expect(error).toBeInstanceOf(Error)
+    expect(error.name).toBe('Incur.BaseError')
+    expect(error.shortMessage).toBe('something went wrong')
+    expect(error.message).toBe('something went wrong')
+  })
+
+  test('extracts details from cause', () => {
+    const cause = new Error('connection refused')
+    const error = new Errors.BaseError('request failed', { cause })
+    expect(error.details).toBe('connection refused')
+    expect(error.message).toMatchInlineSnapshot(`
+      "request failed
+
+      Details: connection refused"
+    `)
+  })
+
+  test('walk() returns deepest cause', () => {
+    const inner = new Error('root cause')
+    const middle = new Errors.BaseError('mid', { cause: inner })
+    const outer = new Errors.BaseError('top', { cause: middle })
+    expect(outer.walk()).toBe(inner)
+  })
+
+  test('walk(fn) returns first matching cause', () => {
+    const inner = new Errors.IncurError({ code: 'FOO', message: 'foo' })
+    const outer = new Errors.BaseError('top', { cause: inner })
+    expect(outer.walk((e) => e instanceof Errors.IncurError)).toBe(inner)
+  })
+
+  test('walk() without cause returns self', () => {
+    const error = new Errors.BaseError('standalone')
+    expect(error.walk()).toBe(error)
+  })
+})
+
+describe('IncurError', () => {
+  test('has code, hint, retryable', () => {
+    const error = new Errors.IncurError({
+      code: 'NOT_AUTHENTICATED',
+      message: 'Token not found',
+      hint: 'Set GH_TOKEN env var',
+      retryable: false,
+    })
+    expect(error.name).toBe('Incur.IncurError')
+    expect(error.code).toBe('NOT_AUTHENTICATED')
+    expect(error.hint).toBe('Set GH_TOKEN env var')
+    expect(error.retryable).toBe(false)
+    expect(error).toBeInstanceOf(Errors.BaseError)
+  })
+
+  test('defaults retryable to false', () => {
+    const error = new Errors.IncurError({ code: 'FAIL', message: 'fail' })
+    expect(error.retryable).toBe(false)
+  })
+})
+
+describe('ValidationError', () => {
+  test('has fieldErrors', () => {
+    const error = new Errors.ValidationError({
+      message: 'Invalid arguments',
+      fieldErrors: [
+        {
+          path: 'state',
+          expected: 'open | closed',
+          received: 'invalid',
+          message: 'Invalid enum value',
+        },
+      ],
+    })
+    expect(error.name).toBe('Incur.ValidationError')
+    expect(error.fieldErrors).toEqual([
+      {
+        path: 'state',
+        expected: 'open | closed',
+        received: 'invalid',
+        message: 'Invalid enum value',
+      },
+    ])
+    expect(error).toBeInstanceOf(Errors.BaseError)
+  })
+})
+
+describe('ParseError', () => {
+  test('sets name', () => {
+    const error = new Errors.ParseError({ message: 'Unknown flag: --foo' })
+    expect(error.name).toBe('Incur.ParseError')
+    expect(error.shortMessage).toBe('Unknown flag: --foo')
+    expect(error).toBeInstanceOf(Errors.BaseError)
+  })
+})

package/src/Errors.ts

@@ -0,0 +1,139 @@
+/** Base error with shortMessage, details from cause chain, and walk(). */
+export class BaseError extends Error {
+  override name = 'Incur.BaseError'
+  /** The short, human-readable error message (without details). */
+  shortMessage: string
+  /** Details extracted from the cause's message, if any. */
+  details: string | undefined
+
+  constructor(shortMessage: string, options: BaseError.Options = {}) {
+    const details = options.cause instanceof Error ? options.cause.message : undefined
+    const message = details ? `${shortMessage}\n\nDetails: ${details}` : shortMessage
+    super(message, options.cause ? { cause: options.cause } : undefined)
+    this.shortMessage = shortMessage
+    this.details = details
+  }
+
+  /**
+   * Traverses the cause chain.
+   * Without a callback, returns the deepest cause.
+   * With a callback, returns the first cause where `fn` returns `true`.
+   */
+  walk(fn?: ((error: unknown) => boolean) | undefined): unknown {
+    return walk(this, fn)
+  }
+}
+
+export declare namespace BaseError {
+  /** Options for constructing a BaseError. */
+  type Options = {
+    /** The underlying cause of this error. */
+    cause?: Error | undefined
+  }
+}
+
+/** CLI error with code, hint, and retryable flag. */
+export class IncurError extends BaseError {
+  override name = 'Incur.IncurError'
+  /** Machine-readable error code (e.g. `'NOT_AUTHENTICATED'`). */
+  code: string
+  /** Actionable hint for the user. */
+  hint: string | undefined
+  /** Whether the operation can be retried. */
+  retryable: boolean
+
+  constructor(options: IncurError.Options) {
+    super(options.message, options.cause ? { cause: options.cause } : undefined)
+    this.code = options.code
+    this.hint = options.hint
+    this.retryable = options.retryable ?? false
+  }
+}
+
+export declare namespace IncurError {
+  /** Options for constructing a IncurError. */
+  type Options = {
+    /** Machine-readable error code. */
+    code: string
+    /** Human-readable error message. */
+    message: string
+    /** Actionable hint for the user. */
+    hint?: string | undefined
+    /** Whether the operation can be retried. Defaults to `false`. */
+    retryable?: boolean | undefined
+    /** The underlying cause. */
+    cause?: Error | undefined
+  }
+}
+
+/** A field-level validation error detail. */
+export type FieldError = {
+  /** The field path that failed validation. */
+  path: string
+  /** The expected value or type. */
+  expected: string
+  /** The value that was received. */
+  received: string
+  /** Human-readable validation message. */
+  message: string
+}
+
+/** Validation error with per-field error details. */
+export class ValidationError extends BaseError {
+  override name = 'Incur.ValidationError'
+  /** Per-field validation errors. */
+  fieldErrors: FieldError[]
+
+  constructor(options: ValidationError.Options) {
+    super(options.message, options.cause ? { cause: options.cause } : undefined)
+    this.fieldErrors = options.fieldErrors ?? []
+  }
+}
+
+export declare namespace ValidationError {
+  /** Options for constructing a ValidationError. */
+  type Options = {
+    /** Human-readable error message. */
+    message: string
+    /** Per-field validation errors. */
+    fieldErrors?: FieldError[] | undefined
+    /** The underlying cause. */
+    cause?: Error | undefined
+  }
+}
+
+/** Error thrown when argument parsing fails (unknown flags, missing values). */
+export class ParseError extends BaseError {
+  override name = 'Incur.ParseError'
+
+  constructor(options: ParseError.Options) {
+    super(options.message, options.cause ? { cause: options.cause } : undefined)
+  }
+}
+
+export declare namespace ParseError {
+  /** Options for constructing a ParseError. */
+  type Options = {
+    /** Human-readable error message. */
+    message: string
+    /** The underlying cause. */
+    cause?: Error | undefined
+  }
+}
+
+/** Walks the cause chain, returning the deepest cause or the first matching cause. */
+function walk(error: unknown, fn?: ((error: unknown) => boolean) | undefined): unknown {
+  if (fn) {
+    // Find first matching cause (not self)
+    let current = (error as any)?.cause
+    while (current) {
+      if (fn(current)) return current
+      current = (current as any)?.cause
+    }
+    return undefined
+  }
+  // Return deepest cause
+  let current = error
+  while ((current as any)?.cause) current = (current as any).cause
+  return current
+}

package/src/Formatter.test.ts

@@ -0,0 +1,245 @@
+import { decode } from '@toon-format/toon'
+import { Formatter } from 'incur'
+
+describe('format', () => {
+  test('formats success envelope as TOON', () => {
+    const result = Formatter.format({
+      ok: true,
+      data: { message: 'hello world' },
+      meta: { command: 'greet', duration: '0ms' },
+    })
+
+    expect(result).toMatchInlineSnapshot(`
+      "ok: true
+      data:
+        message: hello world
+      meta:
+        command: greet
+        duration: 0ms"
+    `)
+  })
+
+  test('formats error envelope as TOON', () => {
+    const result = Formatter.format({
+      ok: false,
+      error: { code: 'UNKNOWN', message: 'boom' },
+      meta: { command: 'fail', duration: '0ms' },
+    })
+
+    expect(result).toMatchInlineSnapshot(`
+      "ok: false
+      error:
+        code: UNKNOWN
+        message: boom
+      meta:
+        command: fail
+        duration: 0ms"
+    `)
+  })
+
+  test('round-trips through TOON decode', () => {
+    const envelope = {
+      ok: true,
+      data: { items: [1, 2, 3] },
+      meta: { command: 'list', duration: '5ms' },
+    }
+
+    const result = decode(Formatter.format(envelope))
+    expect(result).toMatchObject(envelope)
+  })
+
+  test('formats as TOON (explicit)', () => {
+    const result = Formatter.format({ message: 'hello' }, 'toon')
+    expect(result).toMatchInlineSnapshot(`"message: hello"`)
+  })
+
+  test('formats as JSON', () => {
+    const result = Formatter.format({ message: 'hello' }, 'json')
+    expect(result).toMatchInlineSnapshot(`
+      "{
+        "message": "hello"
+      }"
+    `)
+  })
+
+  test('formats as YAML', () => {
+    const result = Formatter.format({ message: 'hello' }, 'yaml')
+    expect(result).toMatchInlineSnapshot(`
+      "message: hello
+      "
+    `)
+  })
+
+  test('defaults to TOON when no format specified', () => {
+    const result = Formatter.format({ message: 'hello' })
+    expect(result).toMatchInlineSnapshot(`"message: hello"`)
+  })
+
+  test('formats string value as-is', () => {
+    expect(Formatter.format('hello world')).toBe('hello world')
+    expect(Formatter.format('hello world', 'json')).toBe('"hello world"')
+    expect(Formatter.format('hello world', 'md')).toBe('hello world')
+  })
+
+  test('formats number value', () => {
+    expect(Formatter.format(42)).toBe('42')
+    expect(Formatter.format(42, 'json')).toBe('42')
+  })
+})
+
+describe('format md', () => {
+  test('formats flat object as key-value table', () => {
+    const result = Formatter.format({ message: 'hello', status: 'ok' }, 'md')
+    expect(result).toMatchInlineSnapshot(`
+      "| Key     | Value |
+      |---------|-------|
+      | message | hello |
+      | status  | ok    |"
+    `)
+  })
+
+  test('formats array of objects as columnar table', () => {
+    const result = Formatter.format(
+      {
+        items: [
+          { name: 'a', state: 'open' },
+          { name: 'b', state: 'closed' },
+        ],
+      },
+      'md',
+    )
+    expect(result).toMatchInlineSnapshot(`
+      "## items
+
+      | name | state  |
+      |------|--------|
+      | a    | open   |
+      | b    | closed |"
+    `)
+  })
+
+  test('formats mixed top-level with headings', () => {
+    const result = Formatter.format({ items: [{ name: 'a' }], total: 2 }, 'md')
+    expect(result).toMatchInlineSnapshot(`
+      "## items
+
+      | name |
+      |------|
+      | a    |
+
+      ## total
+
+      2"
+    `)
+  })
+
+  test('formats nested objects with dot-delimited path heading', () => {
+    const result = Formatter.format({ config: { db: { host: 'localhost', port: 5432 } } }, 'md')
+    expect(result).toMatchInlineSnapshot(`
+      "## config.db
+
+      | Key  | Value     |
+      |------|-----------|
+      | host | localhost |
+      | port | 5432      |"
+    `)
+  })
+
+  test('formats deeply nested with multiple branches', () => {
+    const result = Formatter.format(
+      {
+        server: {
+          http: { host: '0.0.0.0', port: 3000 },
+          tls: { enabled: true, cert: '/etc/ssl/cert.pem' },
+        },
+        database: {
+          primary: { host: 'db1.internal', port: 5432, pool: 10 },
+        },
+      },
+      'md',
+    )
+    expect(result).toMatchInlineSnapshot(`
+      "## server.http
+
+      | Key  | Value   |
+      |------|---------|
+      | host | 0.0.0.0 |
+      | port | 3000    |
+
+      ## server.tls
+
+      | Key     | Value             |
+      |---------|-------------------|
+      | enabled | true              |
+      | cert    | /etc/ssl/cert.pem |
+
+      ## database.primary
+
+      | Key  | Value        |
+      |------|--------------|
+      | host | db1.internal |
+      | port | 5432         |
+      | pool | 10           |"
+    `)
+  })
+
+  test('formats mixed scalars, arrays, and nested at top level', () => {
+    const result = Formatter.format(
+      {
+        name: 'my-project',
+        version: '1.0.0',
+        dependencies: [
+          { name: 'zod', version: '4.3.6' },
+          { name: 'yaml', version: '2.8.2' },
+        ],
+        config: { debug: false, logLevel: 'info' },
+      },
+      'md',
+    )
+    expect(result).toMatchInlineSnapshot(`
+      "## name
+
+      my-project
+
+      ## version
+
+      1.0.0
+
+      ## dependencies
+
+      | name | version |
+      |------|---------|
+      | zod  | 4.3.6   |
+      | yaml | 2.8.2   |
+
+      ## config
+
+      | Key      | Value |
+      |----------|-------|
+      | debug    | false |
+      | logLevel | info  |"
+    `)
+  })
+
+  test('formats single-key wrapper with array of objects', () => {
+    const result = Formatter.format(
+      {
+        users: [
+          { id: 1, name: 'Alice', role: 'admin' },
+          { id: 2, name: 'Bob', role: 'user' },
+          { id: 3, name: 'Charlie', role: 'user' },
+        ],
+      },
+      'md',
+    )
+    expect(result).toMatchInlineSnapshot(`
+      "## users
+
+      | id | name    | role  |
+      |----|---------|-------|
+      | 1  | Alice   | admin |
+      | 2  | Bob     | user  |
+      | 3  | Charlie | user  |"
+    `)
+  })
+})

package/src/Formatter.ts

@@ -0,0 +1,106 @@
+import { encode } from '@toon-format/toon'
+import { stringify as yamlStringify } from 'yaml'
+
+/** Supported output formats. */
+export type Format = 'toon' | 'json' | 'yaml' | 'md' | 'jsonl'
+
+/** Serializes a value to the specified format. Defaults to TOON. */
+export function format(value: unknown, fmt: Format = 'toon'): string {
+  if (fmt === 'json') return JSON.stringify(value, null, 2)
+  if (fmt === 'yaml') return yamlStringify(value)
+  if (fmt === 'md') return formatMarkdown(value)
+  // toon
+  if (isScalar(value)) return String(value)
+  return encode(value as Record<string, unknown>)
+}
+
+/** Whether a value is a scalar (string, number, boolean, null, undefined). */
+function isScalar(value: unknown): boolean {
+  return value === null || value === undefined || typeof value !== 'object'
+}
+
+/** Whether all values in an object are scalars. */
+function isFlat(obj: Record<string, unknown>): boolean {
+  return Object.values(obj).every(isScalar)
+}
+
+/** Whether a value is an array of plain objects. */
+function isArrayOfObjects(value: unknown): value is Record<string, unknown>[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((v) => typeof v === 'object' && v !== null && !Array.isArray(v))
+  )
+}
+
+/** Renders an aligned markdown table from headers and rows. */
+function table(headers: string[], rows: string[][]): string {
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)))
+  const pad = (s: string, i: number) => s.padEnd(widths[i]!)
+  const headerRow = `| ${headers.map(pad).join(' | ')} |`
+  const sep = `|${widths.map((w) => '-'.repeat(w + 2)).join('|')}|`
+  const body = rows.map((r) => `| ${headers.map((_, i) => pad(r[i] ?? '', i)).join(' | ')} |`)
+  return `${headerRow}\n${sep}\n${body.join('\n')}`
+}
+
+/** Renders a key-value table from a flat object. */
+function kvTable(obj: Record<string, unknown>): string {
+  const entries = Object.entries(obj)
+  return table(
+    ['Key', 'Value'],
+    entries.map(([k, v]) => [k, String(v)]),
+  )
+}
+
+/** Renders a columnar table from an array of objects. */
+function columnarTable(items: Record<string, unknown>[]): string {
+  const keys = [...new Set(items.flatMap(Object.keys))]
+  return table(
+    keys,
+    items.map((item) => keys.map((k) => String(item[k] ?? ''))),
+  )
+}
+
+/** Formats a value as Markdown, recursing into nested objects. */
+function formatMarkdown(value: unknown, path: string[] = []): string {
+  if (isScalar(value)) {
+    if (path.length === 0) return String(value)
+    return `## ${path.join('.')}\n\n${String(value)}`
+  }
+
+  if (Array.isArray(value)) {
+    if (isArrayOfObjects(value)) {
+      const table = columnarTable(value)
+      if (path.length === 0) return table
+      return `## ${path.join('.')}\n\n${table}`
+    }
+    return formatMarkdown(String(value), path)
+  }
+
+  const obj = value as Record<string, unknown>
+  const entries = Object.entries(obj)
+
+  // Single flat object at root — no headings needed
+  if (path.length === 0 && isFlat(obj)) return kvTable(obj)
+
+  // Check if we need headings (mixed types or nested at root)
+  const needsHeadings =
+    path.length > 0 || entries.length > 1 || entries.some(([, v]) => !isScalar(v))
+
+  if (needsHeadings) {
+    const sections = entries.map(([key, val]) => {
+      const childPath = [...path, key]
+      if (isScalar(val)) return `## ${childPath.join('.')}\n\n${String(val)}`
+      if (isArrayOfObjects(val)) return `## ${childPath.join('.')}\n\n${columnarTable(val)}`
+      if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+        const nested = val as Record<string, unknown>
+        if (isFlat(nested)) return `## ${childPath.join('.')}\n\n${kvTable(nested)}`
+        return formatMarkdown(nested, childPath)
+      }
+      return `## ${childPath.join('.')}\n\n${String(val)}`
+    })
+    return sections.join('\n\n')
+  }
+
+  return kvTable(obj)
+}

package/src/Help.test.ts

@@ -0,0 +1,124 @@
+import { Help, z } from 'incur'
+
+describe('formatCommand', () => {
+  test('formats leaf command with args and options', () => {
+    const result = Help.formatCommand('gh pr list', {
+      description: 'List pull requests',
+      args: z.object({
+        repo: z.string().optional().describe('Repository in owner/repo format'),
+      }),
+      options: z.object({
+        state: z.string().default('open').describe('Filter by state'),
+        limit: z.number().default(30).describe('Max PRs to return'),
+      }),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "gh pr list — List pull requests
+
+      Usage: gh pr list [repo] [options]
+
+      Arguments:
+        repo  Repository in owner/repo format
+
+      Options:
+        --state <string>  Filter by state (default: open)
+        --limit <number>  Max PRs to return (default: 30)
+
+      Global Options:
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms                              Print LLM-readable manifest
+        --verbose                           Show full output envelope"
+    `)
+  })
+
+  test('omits sections when no schemas', () => {
+    const result = Help.formatCommand('tool ping', {
+      description: 'Health check',
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "tool ping — Health check
+
+      Usage: tool ping
+
+      Global Options:
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms                              Print LLM-readable manifest
+        --verbose                           Show full output envelope"
+    `)
+  })
+
+  test('formats optional args in brackets, required in angle brackets', () => {
+    const result = Help.formatCommand('tool greet', {
+      args: z.object({
+        name: z.string().describe('Name'),
+        title: z.string().optional().describe('Title'),
+      }),
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "tool greet
+
+      Usage: tool greet <name> [title]
+
+      Arguments:
+        name   Name
+        title  Title
+
+      Global Options:
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms                              Print LLM-readable manifest
+        --verbose                           Show full output envelope"
+    `)
+  })
+})
+
+describe('formatRoot', () => {
+  test('formats root with command list', () => {
+    const result = Help.formatRoot('gh', {
+      description: 'GitHub CLI',
+      commands: [
+        { name: 'pr list', description: 'List pull requests' },
+        { name: 'pr view', description: 'View a pull request' },
+        { name: 'issue list', description: 'List issues' },
+      ],
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "gh — GitHub CLI
+
+      Usage: gh <command>
+
+      Commands:
+        pr list     List pull requests
+        pr view     View a pull request
+        issue list  List issues
+
+      Global Options:
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms                              Print LLM-readable manifest
+        --verbose                           Show full output envelope"
+    `)
+  })
+
+  test('formats root with no description', () => {
+    const result = Help.formatRoot('tool', {
+      commands: [{ name: 'ping', description: 'Health check' }],
+    })
+    expect(result).toMatchInlineSnapshot(`
+      "tool
+
+      Usage: tool <command>
+
+      Commands:
+        ping  Health check
+
+      Global Options:
+        --format <toon|json|yaml|md|jsonl>  Output format
+        --help                              Show help
+        --llms                              Print LLM-readable manifest
+        --verbose                           Show full output envelope"
+    `)
+  })
+})