incur 0.2.0 → 0.2.2

package/src/Errors.ts

@@ -41,12 +41,15 @@ export class IncurError extends BaseError {
   hint: string | undefined
   /** Whether the operation can be retried. */
   retryable: boolean
+  /** Process exit code. When set, `serve()` uses this instead of `1`. */
+  exitCode: number | undefined
 
   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
+    this.exitCode = options.exitCode
   }
 }
 
@@ -61,6 +64,8 @@ export declare namespace IncurError {
     hint?: string | undefined
     /** Whether the operation can be retried. Defaults to `false`. */
     retryable?: boolean | undefined
+    /** Process exit code. When set, `serve()` uses this instead of `1`. */
+    exitCode?: number | undefined
     /** The underlying cause. */
     cause?: Error | undefined
   }

package/src/Filter.test.ts

@@ -0,0 +1,237 @@
+import { Filter } from 'incur'
+
+describe('parse', () => {
+  test('single key', () => {
+    expect(Filter.parse('foo')).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "key": "foo",
+          },
+        ],
+      ]
+    `)
+  })
+
+  test('dot notation', () => {
+    expect(Filter.parse('bar.baz')).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "key": "bar",
+          },
+          {
+            "key": "baz",
+          },
+        ],
+      ]
+    `)
+  })
+
+  test('slice notation', () => {
+    expect(Filter.parse('items[0,3]')).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "key": "items",
+          },
+          {
+            "end": 3,
+            "start": 0,
+          },
+        ],
+      ]
+    `)
+  })
+
+  test('mixed keys and slices', () => {
+    expect(Filter.parse('a.b.c[0,10]')).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "key": "a",
+          },
+          {
+            "key": "b",
+          },
+          {
+            "key": "c",
+          },
+          {
+            "end": 10,
+            "start": 0,
+          },
+        ],
+      ]
+    `)
+  })
+
+  test('multiple paths', () => {
+    expect(Filter.parse('name,age')).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "key": "name",
+          },
+        ],
+        [
+          {
+            "key": "age",
+          },
+        ],
+      ]
+    `)
+  })
+
+  test('slice followed by dot path', () => {
+    expect(Filter.parse('items[0,3].name')).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "key": "items",
+          },
+          {
+            "end": 3,
+            "start": 0,
+          },
+          {
+            "key": "name",
+          },
+        ],
+      ]
+    `)
+  })
+
+  test('comma inside slice is not a separator', () => {
+    expect(Filter.parse('foo,items[0,3],bar')).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "key": "foo",
+          },
+        ],
+        [
+          {
+            "key": "items",
+          },
+          {
+            "end": 3,
+            "start": 0,
+          },
+        ],
+        [
+          {
+            "key": "bar",
+          },
+        ],
+      ]
+    `)
+  })
+})
+
+describe('apply', () => {
+  test('selects single top-level key', () => {
+    const data = { name: 'alice', age: 30, email: 'alice@example.com' }
+    expect(Filter.apply(data, Filter.parse('name'))).toMatchInlineSnapshot(`"alice"`)
+  })
+
+  test('selects nested key with dot notation', () => {
+    const data = { user: { name: 'alice', email: 'alice@example.com' }, status: 'active' }
+    expect(Filter.apply(data, Filter.parse('user.name'))).toMatchInlineSnapshot(`
+      {
+        "user": {
+          "name": "alice",
+        },
+      }
+    `)
+  })
+
+  test('slices array', () => {
+    const data = { items: [1, 2, 3, 4, 5] }
+    expect(Filter.apply(data, Filter.parse('items[0,3]'))).toMatchInlineSnapshot(`
+      {
+        "items": [
+          1,
+          2,
+          3,
+        ],
+      }
+    `)
+  })
+
+  test('selects nested field after slice', () => {
+    const data = {
+      users: [
+        { name: 'alice', age: 30 },
+        { name: 'bob', age: 25 },
+        { name: 'charlie', age: 35 },
+      ],
+    }
+    expect(Filter.apply(data, Filter.parse('users[0,2].name'))).toMatchInlineSnapshot(`
+      {
+        "users": [
+          {
+            "name": "alice",
+          },
+          {
+            "name": "bob",
+          },
+        ],
+      }
+    `)
+  })
+
+  test('multiple filter paths merged', () => {
+    const data = { name: 'alice', age: 30, email: 'alice@example.com' }
+    expect(Filter.apply(data, Filter.parse('name,age'))).toMatchInlineSnapshot(`
+      {
+        "age": 30,
+        "name": "alice",
+      }
+    `)
+  })
+
+  test('returns scalar directly for single key selection', () => {
+    const data = { message: 'hello world', status: 'ok' }
+    const result = Filter.apply(data, Filter.parse('message'))
+    expect(result).toBe('hello world')
+  })
+
+  test('returns object for single key with object value', () => {
+    const data = { user: { name: 'alice' }, status: 'ok' }
+    expect(Filter.apply(data, Filter.parse('user'))).toMatchInlineSnapshot(`
+      {
+        "user": {
+          "name": "alice",
+        },
+      }
+    `)
+  })
+
+  test('returns undefined for missing key', () => {
+    const data = { name: 'alice' }
+    expect(Filter.apply(data, Filter.parse('missing'))).toMatchInlineSnapshot(`undefined`)
+  })
+
+  test('applies filter to each element when data is array', () => {
+    const data = [
+      { name: 'alice', age: 30 },
+      { name: 'bob', age: 25 },
+    ]
+    expect(Filter.apply(data, Filter.parse('name'))).toMatchInlineSnapshot(`
+      [
+        "alice",
+        "bob",
+      ]
+    `)
+  })
+
+  test('empty paths returns data unchanged', () => {
+    const data = { foo: 'bar' }
+    expect(Filter.apply(data, [])).toMatchInlineSnapshot(`
+      {
+        "foo": "bar",
+      }
+    `)
+  })
+})

package/src/Filter.ts

@@ -0,0 +1,139 @@
+/** A single segment in a filter path: either a string key or an array slice. */
+export type Segment = { key: string } | { start: number; end: number }
+
+/** A filter path is an ordered list of segments to traverse. */
+export type FilterPath = Segment[]
+
+/** Parses a filter expression string into structured filter paths. */
+export function parse(expression: string): FilterPath[] {
+  const paths: FilterPath[] = []
+  const tokens: string[] = []
+  let current = ''
+  let depth = 0
+
+  // Split on commas, but commas inside [...] are part of a slice
+  for (let i = 0; i < expression.length; i++) {
+    const ch = expression[i]!
+    if (ch === '[') depth++
+    else if (ch === ']') depth--
+
+    if (ch === ',' && depth === 0) {
+      tokens.push(current)
+      current = ''
+    } else current += ch
+  }
+  if (current) tokens.push(current)
+
+  for (const token of tokens) {
+    const path: FilterPath = []
+    let remaining = token
+
+    while (remaining.length > 0) {
+      const bracketIdx = remaining.indexOf('[')
+
+      if (bracketIdx === -1) {
+        // No more slices — split remaining by dots
+        for (const part of remaining.split('.')) if (part) path.push({ key: part })
+        break
+      }
+
+      // Parse dot-separated keys before the bracket
+      const before = remaining.slice(0, bracketIdx)
+      for (const part of before.split('.')) if (part) path.push({ key: part })
+
+      // Parse the slice [start,end]
+      const closeBracket = remaining.indexOf(']', bracketIdx)
+      const inner = remaining.slice(bracketIdx + 1, closeBracket)
+      const [startStr, endStr] = inner.split(',')
+      path.push({ start: Number(startStr), end: Number(endStr) })
+
+      remaining = remaining.slice(closeBracket + 1)
+      if (remaining.startsWith('.')) remaining = remaining.slice(1)
+    }
+
+    paths.push(path)
+  }
+
+  return paths
+}
+
+/** Applies parsed filter paths to a data value, returning a filtered copy. */
+export function apply(data: unknown, paths: FilterPath[]): unknown {
+  if (paths.length === 0) return data
+
+  // Single key selecting a scalar → return the scalar directly
+  if (paths.length === 1 && paths[0]!.length === 1 && 'key' in paths[0]![0]!) {
+    const key = paths[0]![0]!.key
+    if (Array.isArray(data)) return data.map((item) => apply(item, paths))
+    if (typeof data === 'object' && data !== null) {
+      const val = (data as Record<string, unknown>)[key]
+      if (typeof val !== 'object' || val === null) return val
+      return { [key]: val }
+    }
+    return undefined
+  }
+
+  if (Array.isArray(data)) return data.map((item) => apply(item, paths))
+
+  const result: Record<string, unknown> = {}
+  for (const path of paths) merge(result, data, path, 0)
+  return result
+}
+
+function resolve(data: unknown, segments: Segment[], index: number): unknown {
+  if (index >= segments.length) return data
+  const segment = segments[index]!
+
+  if ('key' in segment) {
+    if (typeof data !== 'object' || data === null) return undefined
+    const val = (data as Record<string, unknown>)[segment.key]
+    return resolve(val, segments, index + 1)
+  }
+
+  // slice segment
+  if (!Array.isArray(data)) return undefined
+  const sliced = data.slice(segment.start, segment.end)
+  if (index + 1 >= segments.length) return sliced
+  return sliced.map((item) => resolve(item, segments, index + 1))
+}
+
+function merge(target: Record<string, unknown>, data: unknown, segments: Segment[], index: number): void {
+  if (index >= segments.length || typeof data !== 'object' || data === null) return
+  const segment = segments[index]!
+
+  if ('key' in segment) {
+    const val = (data as Record<string, unknown>)[segment.key]
+    if (val === undefined) return
+
+    if (index + 1 >= segments.length) {
+      target[segment.key] = val
+      return
+    }
+
+    const next = segments[index + 1]!
+    if ('start' in next) {
+      // Next segment is a slice
+      if (!Array.isArray(val)) return
+      const sliced = val.slice(next.start, next.end)
+      if (index + 2 >= segments.length) {
+        target[segment.key] = sliced
+        return
+      }
+      target[segment.key] = sliced.map((item) => {
+        const sub: Record<string, unknown> = {}
+        merge(sub, item, segments, index + 2)
+        return sub
+      })
+      return
+    }
+
+    // Next segment is a key — recurse into nested object
+    if (typeof val !== 'object' || val === null) return
+    if (!target[segment.key] || typeof target[segment.key] !== 'object')
+      target[segment.key] = {}
+    merge(target[segment.key] as Record<string, unknown>, val, segments, index + 1)
+    return
+  }
+
+  // slice at root level — shouldn't happen in merge (merge starts from object keys)
+}

package/src/Help.test.ts

@@ -25,9 +25,14 @@ describe('formatCommand', () => {
         --limit <number>  Max PRs to return (default: 30)
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
         --verbose                           Show full output envelope"
     `)
   })
@@ -42,9 +47,14 @@ describe('formatCommand', () => {
       Usage: tool ping
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
         --verbose                           Show full output envelope"
     `)
   })
@@ -66,9 +76,14 @@ describe('formatCommand', () => {
         title  Title
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
         --verbose                           Show full output envelope"
     `)
   })
@@ -107,9 +122,14 @@ describe('formatRoot', () => {
         issue list  List issues
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
         --verbose                           Show full output envelope"
     `)
   })
@@ -127,9 +147,14 @@ describe('formatRoot', () => {
         ping  Health check
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
         --verbose                           Show full output envelope"
     `)
   })
@@ -151,9 +176,14 @@ describe('formatRoot', () => {
         fetch  Fetch a URL
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
         --verbose                           Show full output envelope"
     `)
   })
@@ -175,9 +205,14 @@ describe('formatRoot', () => {
         url  URL to fetch
 
       Global Options:
+        --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
         --format <toon|json|yaml|md|jsonl>  Output format
         --help                              Show help
         --llms                              Print LLM-readable manifest
+        --schema                            Show JSON Schema for a 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
         --verbose                           Show full output envelope"
     `)
   })

package/src/Help.ts

@@ -326,10 +326,15 @@ function globalOptionsLines(root = false): string[] {
   }
 
   const flags = [
+    { flag: '--filter-output <keys>', desc: 'Filter output by key paths (e.g. foo,bar.baz,a[0,3])' },
     { flag: '--format <toon|json|yaml|md|jsonl>', desc: 'Output format' },
     { flag: '--help', desc: 'Show help' },
     { flag: '--llms', desc: 'Print LLM-readable manifest' },
     ...(root ? [{ flag: '--mcp', desc: 'Start as MCP stdio server' }] : []),
+    { flag: '--schema', desc: 'Show JSON Schema for a command' },
+    { flag: '--token-count', desc: 'Print token count of output (instead of output)' },
+    { flag: '--token-limit <n>', desc: 'Limit output to n tokens' },
+    { flag: '--token-offset <n>', desc: 'Skip first n tokens of output' },
     { flag: '--verbose', desc: 'Show full output envelope' },
     ...(root ? [{ flag: '--version', desc: 'Show version' }] : []),
   ]

package/src/Mcp.ts

@@ -52,7 +52,7 @@ export declare namespace serve {
 }
 
 /** @internal Executes a tool call and returns a CallToolResult. */
-async function callTool(
+export async function callTool(
   tool: ToolEntry,
   params: Record<string, unknown>,
   extra?: {
@@ -135,7 +135,7 @@ function isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown, unkn
 }
 
 /** @internal A resolved tool entry from the command tree. */
-type ToolEntry = {
+export type ToolEntry = {
   name: string
   description?: string | undefined
   inputSchema: { type: 'object'; properties: Record<string, unknown>; required?: string[] }
@@ -143,7 +143,7 @@ type ToolEntry = {
 }
 
 /** @internal Recursively collects leaf commands as tool entries. */
-function collectTools(commands: Map<string, any>, prefix: string[]): ToolEntry[] {
+export function collectTools(commands: Map<string, any>, prefix: string[]): ToolEntry[] {
   const result: ToolEntry[] = []
   for (const [name, entry] of commands) {
     const path = [...prefix, name]