feat: add gcf output format

.changeset/gcf-output-format.md

@@ -0,0 +1,5 @@
+---
+'incur': patch
+---
+
+Added `gcf` as an output format (`--format gcf`) alongside `toon`, `json`, `yaml`, `md`, and `jsonl`. GCF (Graph Compact Format) is a lossless, zero-runtime-dependency encoding for structured data.

package.json

@@ -46,6 +46,7 @@
     "SKILL.md"
   ],
   "dependencies": {
+    "@blackwell-systems/gcf": "2.4.0",
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/server": "^2.0.0-alpha.2",
     "@scalar/openapi-types": "^0.8.0",

src/Cli.test-d.ts

@@ -271,7 +271,7 @@ test('middleware() without generic gives empty context', () => {
   middleware((c, _next) => {
     expectTypeOf(c.var).toEqualTypeOf<{}>()
     expectTypeOf(c.env).toEqualTypeOf<{}>()
-    expectTypeOf(c.format).toEqualTypeOf<'toon' | 'json' | 'yaml' | 'md' | 'jsonl'>()
+    expectTypeOf(c.format).toEqualTypeOf<'toon' | 'json' | 'yaml' | 'md' | 'jsonl' | 'gcf'>()
     expectTypeOf(c.formatExplicit).toEqualTypeOf<boolean>()
   })
 })
@@ -367,7 +367,7 @@ test('run() context exposes format metadata', () => {
   const cli = Cli.create('test')
   cli.command('ping', {
     run(c) {
-      expectTypeOf(c.format).toEqualTypeOf<'toon' | 'json' | 'yaml' | 'md' | 'jsonl'>()
+      expectTypeOf(c.format).toEqualTypeOf<'toon' | 'json' | 'yaml' | 'md' | 'jsonl' | 'gcf'>()
       expectTypeOf(c.formatExplicit).toEqualTypeOf<boolean>()
       return { pong: true }
     },

src/Cli.ts

@@ -2480,7 +2480,7 @@ declare namespace serveImpl {
 }
 
 /** @internal Extracts built-in flags (--full-output, --format, --json, --llms, --help, --version) from argv. */
-const validFormats = new Set(['toon', 'json', 'yaml', 'md', 'jsonl'] as const)
+const validFormats = new Set(['toon', 'json', 'yaml', 'md', 'jsonl', 'gcf'] as const)
 
 function extractBuiltinFlags(argv: string[], options: extractBuiltinFlags.Options = {}) {
   let fullOutput = false

src/Formatter.test.ts

@@ -1,3 +1,4 @@
+import { decodeGeneric } from '@blackwell-systems/gcf'
 import { decode } from '@toon-format/toon'
 import { Formatter } from 'incur'
 
@@ -53,6 +54,41 @@ describe('format', () => {
     expect(result).toMatchInlineSnapshot(`"message: hello"`)
   })
 
+  test('formats as GCF (explicit)', () => {
+    const result = Formatter.format({ message: 'hello' }, 'gcf')
+    expect(result).toBe('GCF profile=generic\nmessage=hello\n')
+  })
+
+  test('formats an array of records as a GCF table', () => {
+    const result = Formatter.format(
+      {
+        ok: true,
+        data: {
+          users: [
+            { id: 1, name: 'a' },
+            { id: 2, name: 'b' },
+          ],
+        },
+        meta: { command: 'users' },
+      },
+      'gcf',
+    )
+    expect(result).toBe(
+      'GCF profile=generic\nok=true\n## data\n  ## users [2]{id,name}\n  1|a\n  2|b\n## meta\n  command=users\n',
+    )
+  })
+
+  test('round-trips through GCF decode', () => {
+    const envelope = {
+      ok: true,
+      data: { items: [1, 2, 3] },
+      meta: { command: 'list', duration: '5ms' },
+    }
+
+    const result = decodeGeneric(Formatter.format(envelope, 'gcf'))
+    expect(result).toMatchObject(envelope)
+  })
+
   test('formats as JSON', () => {
     const result = Formatter.format({ message: 'hello' }, 'json')
     expect(result).toMatchInlineSnapshot(`

src/Formatter.ts

@@ -1,10 +1,11 @@
+import { encodeGeneric } from '@blackwell-systems/gcf'
 import { encode } from '@toon-format/toon'
 
 import * as Json from './internal/json.js'
 import * as Yaml from './internal/yaml.js'
 
 /** Supported output formats. */
-export type Format = 'toon' | 'json' | 'yaml' | 'md' | 'jsonl'
+export type Format = 'toon' | 'json' | 'yaml' | 'md' | 'jsonl' | 'gcf'
 
 /** Serializes a value to the specified format. Defaults to TOON. */
 export function format(value: unknown, fmt: Format = 'toon'): string {
@@ -26,6 +27,10 @@ export function format(value: unknown, fmt: Format = 'toon'): string {
     if (Array.isArray(value)) return value.map((v) => Json.stringify(v)).join('\n')
     return Json.stringify(value)
   }
+  if (fmt === 'gcf') {
+    if (isScalar(value)) return String(value)
+    return encodeGeneric(value)
+  }
   // toon (default)
   if (isScalar(value)) return String(value)
   return encode(value as Record<string, unknown>)

src/Help.ts

@@ -407,7 +407,7 @@ function globalOptionsLines(
       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: '--format <toon|json|yaml|md|jsonl|gcf>', desc: 'Output format' },
     { flag: '--help', desc: 'Show help' },
     { flag: '--llms, --llms-full', desc: 'Print LLM-readable manifest' },
     ...(root ? [{ flag: '--mcp', desc: 'Start as MCP stdio server' }] : []),