@blackwell-systems/gcf 0.1.0

package/dist/encode.d.ts

@@ -0,0 +1,6 @@
+import type { Payload } from './types.js';
+/**
+ * Encode serializes a Payload into GCF text format.
+ */
+export declare function encode(p: Payload): string;
+//# sourceMappingURL=encode.d.ts.map

package/dist/encode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../src/encode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,YAAY,CAAC;AAyBlD;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAuDzC"}

package/dist/encode.js

@@ -0,0 +1,69 @@
+import { KIND_ABBREV } from './constants.js';
+function groupByDistance(symbols) {
+    if (symbols.length === 0)
+        return [];
+    const groups = [];
+    let current = null;
+    for (const s of symbols) {
+        if (current === null || current.distance !== s.distance) {
+            current = { distance: s.distance, symbols: [] };
+            groups.push(current);
+        }
+        current.symbols.push(s);
+    }
+    return groups;
+}
+/**
+ * Encode serializes a Payload into GCF text format.
+ */
+export function encode(p) {
+    const lines = [];
+    // Header line.
+    let header = `GCF tool=${p.tool} budget=${p.tokenBudget} tokens=${p.tokensUsed} symbols=${p.symbols.length}`;
+    if (p.packRoot) {
+        header += ` pack_root=${p.packRoot}`;
+    }
+    lines.push(header);
+    // Build symbol index for edge references.
+    const symIndex = new Map();
+    for (let i = 0; i < p.symbols.length; i++) {
+        symIndex.set(p.symbols[i].qualifiedName, i);
+    }
+    // Group symbols by distance.
+    const groups = groupByDistance(p.symbols);
+    const groupNames = ['targets', 'related', 'extended'];
+    for (const g of groups) {
+        if (g.symbols.length === 0)
+            continue;
+        let name;
+        if (g.distance < groupNames.length) {
+            name = groupNames[g.distance];
+        }
+        else {
+            name = `distance_${g.distance}`;
+        }
+        lines.push(`## ${name}`);
+        for (const s of g.symbols) {
+            const idx = symIndex.get(s.qualifiedName);
+            const kind = KIND_ABBREV[s.kind] || s.kind;
+            lines.push(`@${idx} ${kind} ${s.qualifiedName} ${s.score.toFixed(2)} ${s.provenance}`);
+        }
+    }
+    // Edges section.
+    if (p.edges.length > 0) {
+        lines.push('## edges');
+        for (const e of p.edges) {
+            const srcIdx = symIndex.get(e.source);
+            const tgtIdx = symIndex.get(e.target);
+            if (srcIdx === undefined || tgtIdx === undefined)
+                continue;
+            let line = `@${tgtIdx}<@${srcIdx} ${e.edgeType}`;
+            if (e.status && e.status !== 'unchanged') {
+                line += ` ${e.status}`;
+            }
+            lines.push(line);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=encode.js.map

package/dist/encode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encode.js","sourceRoot":"","sources":["../src/encode.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { Symbol, Edge, Payload, DeltaPayload, Components } from './types.js';
+export { KIND_ABBREV, KIND_EXPAND } from './constants.js';
+export { encode } from './encode.js';
+export { decode } from './decode.js';
+export { Session, encodeWithSession } from './session.js';
+export { encodeDelta } from './delta.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { KIND_ABBREV, KIND_EXPAND } from './constants.js';
+export { encode } from './encode.js';
+export { decode } from './decode.js';
+export { Session, encodeWithSession } from './session.js';
+export { encodeDelta } from './delta.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,31 @@
+import type { Payload, Symbol } from './types.js';
+/**
+ * Session tracks symbols that have been transmitted to a client, enabling
+ * subsequent responses to reference them by ID without full retransmission.
+ * This makes multi-call workflows progressively cheaper.
+ */
+export declare class Session {
+    private symbols;
+    private nextID;
+    /** Returns true if the symbol has been sent in a previous response. */
+    transmitted(qname: string): boolean;
+    /** Returns the session-global ID for a previously transmitted symbol, or -1 if not found. */
+    getID(qname: string): number;
+    /**
+     * Record marks symbols as transmitted and assigns session-global IDs.
+     * Call this after a successful encode to register newly-sent symbols.
+     */
+    record(symbols: Symbol[]): void;
+    /** Returns the number of symbols tracked in this session. */
+    size(): number;
+    /** Clears the session state. */
+    reset(): void;
+}
+/**
+ * Encode a payload using GCF with session deduplication.
+ * Symbols that were already transmitted in prior responses are emitted as
+ * bare references (`@N  # previously transmitted`) instead of full declarations.
+ * After encoding, newly-sent symbols are recorded in the session.
+ */
+export declare function encodeWithSession(p: Payload, sess: Session | null): string;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAIlD;;;;GAIG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,MAAM,CAAa;IAE3B,uEAAuE;IACvE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAInC,6FAA6F;IAC7F,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAK5B;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAS/B,6DAA6D;IAC7D,IAAI,IAAI,MAAM;IAId,gCAAgC;IAChC,KAAK,IAAI,IAAI;CAId;AAqBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,CAwE1E"}

package/dist/session.js

@@ -0,0 +1,127 @@
+import { KIND_ABBREV } from './constants.js';
+import { encode } from './encode.js';
+/**
+ * Session tracks symbols that have been transmitted to a client, enabling
+ * subsequent responses to reference them by ID without full retransmission.
+ * This makes multi-call workflows progressively cheaper.
+ */
+export class Session {
+    symbols = new Map();
+    nextID = 0;
+    /** Returns true if the symbol has been sent in a previous response. */
+    transmitted(qname) {
+        return this.symbols.has(qname);
+    }
+    /** Returns the session-global ID for a previously transmitted symbol, or -1 if not found. */
+    getID(qname) {
+        const id = this.symbols.get(qname);
+        return id !== undefined ? id : -1;
+    }
+    /**
+     * Record marks symbols as transmitted and assigns session-global IDs.
+     * Call this after a successful encode to register newly-sent symbols.
+     */
+    record(symbols) {
+        for (const sym of symbols) {
+            if (!this.symbols.has(sym.qualifiedName)) {
+                this.symbols.set(sym.qualifiedName, this.nextID);
+                this.nextID++;
+            }
+        }
+    }
+    /** Returns the number of symbols tracked in this session. */
+    size() {
+        return this.symbols.size;
+    }
+    /** Clears the session state. */
+    reset() {
+        this.symbols.clear();
+        this.nextID = 0;
+    }
+}
+function groupByDistance(symbols) {
+    if (symbols.length === 0)
+        return [];
+    const groups = [];
+    let current = null;
+    for (const s of symbols) {
+        if (current === null || current.distance !== s.distance) {
+            current = { distance: s.distance, symbols: [] };
+            groups.push(current);
+        }
+        current.symbols.push(s);
+    }
+    return groups;
+}
+/**
+ * Encode a payload using GCF with session deduplication.
+ * Symbols that were already transmitted in prior responses are emitted as
+ * bare references (`@N  # previously transmitted`) instead of full declarations.
+ * After encoding, newly-sent symbols are recorded in the session.
+ */
+export function encodeWithSession(p, sess) {
+    if (!sess) {
+        return encode(p);
+    }
+    const lines = [];
+    // Header with session=true marker.
+    let header = `GCF tool=${p.tool} budget=${p.tokenBudget} tokens=${p.tokensUsed} symbols=${p.symbols.length} session=true`;
+    if (p.packRoot) {
+        header += ` pack_root=${p.packRoot}`;
+    }
+    lines.push(header);
+    // Build local ID mapping for this response.
+    const localIndex = new Map();
+    for (let i = 0; i < p.symbols.length; i++) {
+        localIndex.set(p.symbols[i].qualifiedName, i);
+    }
+    // Track which symbols are new for recording after encode.
+    const newSymbols = [];
+    // Group by distance.
+    const groups = groupByDistance(p.symbols);
+    const groupNames = ['targets', 'related', 'extended'];
+    for (const g of groups) {
+        if (g.symbols.length === 0)
+            continue;
+        let name;
+        if (g.distance < groupNames.length) {
+            name = groupNames[g.distance];
+        }
+        else {
+            name = `distance_${g.distance}`;
+        }
+        lines.push(`## ${name}`);
+        for (const s of g.symbols) {
+            const idx = localIndex.get(s.qualifiedName);
+            if (sess.transmitted(s.qualifiedName)) {
+                // Bare reference: symbol was sent in a prior response.
+                lines.push(`@${idx}  # previously transmitted`);
+            }
+            else {
+                // Full declaration.
+                const kind = KIND_ABBREV[s.kind] || s.kind;
+                lines.push(`@${idx} ${kind} ${s.qualifiedName} ${s.score.toFixed(2)} ${s.provenance}`);
+                newSymbols.push(s);
+            }
+        }
+    }
+    // Edges section.
+    if (p.edges.length > 0) {
+        lines.push('## edges');
+        for (const e of p.edges) {
+            const srcIdx = localIndex.get(e.source);
+            const tgtIdx = localIndex.get(e.target);
+            if (srcIdx === undefined || tgtIdx === undefined)
+                continue;
+            let line = `@${tgtIdx}<@${srcIdx} ${e.edgeType}`;
+            if (e.status && e.status !== 'unchanged') {
+                line += ` ${e.status}`;
+            }
+            lines.push(line);
+        }
+    }
+    // Record all new symbols in the session.
+    sess.record(newSymbols);
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Symbol represents a node in a GCF payload.
+ */
+export interface Symbol {
+    /** Fully qualified identifier (e.g., "pkg/auth.Middleware") */
+    qualifiedName: string;
+    /** Node type: "function", "type", "method", etc. */
+    kind: string;
+    /** Relevance score (0.0 to 1.0) */
+    score: number;
+    /** Discovery method: "lsp_resolved", "ast_inferred", etc. */
+    provenance: string;
+    /** Hops from query center (0=target, 1=related, 2+=extended) */
+    distance: number;
+    /** Optional: function/method signature */
+    signature?: string;
+    /** Optional: score breakdown */
+    components?: Components;
+}
+/**
+ * Components holds the score breakdown for a symbol.
+ */
+export interface Components {
+    blastRadius: number;
+    confidence: number;
+    recency: number;
+    distance: number;
+}
+/**
+ * Edge represents a directed relationship in a GCF payload.
+ */
+export interface Edge {
+    /** Qualified name of source symbol */
+    source: string;
+    /** Qualified name of target symbol */
+    target: string;
+    /** Relationship type (e.g., "calls", "imports", "implements") */
+    edgeType: string;
+    /** Optional: "added", "removed", "unchanged" (for diff responses) */
+    status?: string;
+}
+/**
+ * Payload is the input/output structure for GCF encoding/decoding.
+ */
+export interface Payload {
+    /** Producing tool name (e.g., "context_for_task") */
+    tool: string;
+    /** Token budget requested by the consumer */
+    tokenBudget: number;
+    /** Actual tokens consumed by this payload */
+    tokensUsed: number;
+    /** Content-addressed identity (hex SHA-256), enables delta encoding */
+    packRoot?: string;
+    /** Ordered by score descending within each distance group */
+    symbols: Symbol[];
+    /** Directed relationships between symbols */
+    edges: Edge[];
+}
+/**
+ * DeltaPayload represents the diff between a prior context pack and the
+ * current result. Used for incremental context delivery.
+ */
+export interface DeltaPayload {
+    tool: string;
+    /** pack_root the consumer has */
+    baseRoot: string;
+    /** pack_root of the current result */
+    newRoot: string;
+    removed: Symbol[];
+    added: Symbol[];
+    removedEdges: Edge[];
+    addedEdges: Edge[];
+    deltaTokens: number;
+    fullTokens: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6CAA6C;IAC7C,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,EAAE,IAAI,EAAE,CAAC;IACrB,UAAU,EAAE,IAAI,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@blackwell-systems/gcf",
+  "version": "0.1.0",
+  "description": "TypeScript implementation of GCF (Graph Compact Format) - token-optimized wire format for LLM tool responses",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "gcf": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": [
+    "gcf",
+    "graph",
+    "compact",
+    "format",
+    "llm",
+    "tokens",
+    "mcp",
+    "wire-format"
+  ],
+  "author": "Blackwell Systems",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blackwell-systems/gcf-typescript.git"
+  },
+  "homepage": "https://github.com/blackwell-systems/gcf",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * GCF command-line interface: encode, decode, stats.
+ */
+
+import { readFileSync } from 'node:fs';
+import { encode } from './encode.js';
+import { decode } from './decode.js';
+import type { Payload, Symbol, Edge } from './types.js';
+
+const USAGE = `gcf - token-optimized wire format for LLM tool responses
+
+Usage:
+  gcf encode [file]    Encode JSON payload to GCF (stdin if no file)
+  gcf decode [file]    Decode GCF text to JSON (stdin if no file)
+  gcf stats  [file]    Compare token counts: JSON vs GCF (stdin if no file)
+  gcf version          Print version
+
+Examples:
+  gcf encode < payload.json
+  gcf decode < payload.gcf
+  gcf stats payload.json
+`;
+
+function readInput(args: string[]): string {
+  if (args.length > 0 && args[0] !== '-') {
+    return readFileSync(args[0]!, 'utf-8');
+  }
+  return readFileSync(0, 'utf-8');
+}
+
+function payloadFromJSON(data: string): Payload {
+  const obj = JSON.parse(data);
+  return {
+    tool: obj.tool ?? '',
+    tokenBudget: obj.tokenBudget ?? 0,
+    tokensUsed: obj.tokensUsed ?? 0,
+    packRoot: obj.packRoot ?? '',
+    symbols: (obj.symbols ?? []).map((s: any) => ({
+      qualifiedName: s.qualifiedName,
+      kind: s.kind,
+      score: s.score,
+      provenance: s.provenance,
+      distance: s.distance ?? 0,
+    })),
+    edges: (obj.edges ?? []).map((e: any) => ({
+      source: e.source,
+      target: e.target,
+      edgeType: e.edgeType,
+      status: e.status ?? '',
+    })),
+  };
+}
+
+function payloadToJSON(p: Payload): string {
+  return JSON.stringify({
+    tool: p.tool,
+    tokensUsed: p.tokensUsed,
+    tokenBudget: p.tokenBudget,
+    packRoot: p.packRoot ?? '',
+    symbols: p.symbols.map(s => ({
+      qualifiedName: s.qualifiedName,
+      kind: s.kind,
+      score: s.score,
+      provenance: s.provenance,
+      distance: s.distance,
+    })),
+    edges: p.edges.map(e => ({
+      source: e.source,
+      target: e.target,
+      edgeType: e.edgeType,
+      ...(e.status ? { status: e.status } : {}),
+    })),
+  }, null, 2);
+}
+
+function doEncode(data: string): void {
+  const p = payloadFromJSON(data);
+  process.stdout.write(encode(p));
+}
+
+function doDecode(data: string): void {
+  const p = decode(data);
+  console.log(payloadToJSON(p));
+}
+
+function doStats(data: string): void {
+  const p = payloadFromJSON(data);
+  const gcfOutput = encode(p);
+
+  const jsonTokens = Math.floor(data.trim().length / 4);
+  const gcfTokens = Math.floor(gcfOutput.trim().length / 4);
+
+  const savings = jsonTokens > 0 ? 100 * (1 - gcfTokens / jsonTokens) : 0;
+
+  const barWidth = 30;
+  const jsonBar = '█'.repeat(barWidth);
+  const gcfFilled = jsonTokens > 0 ? Math.round((gcfTokens * barWidth) / jsonTokens) : 0;
+  const gcfBar = '█'.repeat(gcfFilled) + '░'.repeat(barWidth - gcfFilled);
+
+  console.log(`Payload: ${p.symbols.length} symbols, ${p.edges.length} edges\n`);
+  console.log(`  JSON  ${jsonBar}  ${jsonTokens} tokens`);
+  console.log(`  GCF   ${gcfBar}  ${gcfTokens} tokens`);
+  console.log(`\n  Savings: ${Math.round(savings)}% fewer tokens with GCF`);
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+switch (cmd) {
+  case 'encode':
+    doEncode(readInput(args.slice(1)));
+    break;
+  case 'decode':
+    doDecode(readInput(args.slice(1)));
+    break;
+  case 'stats':
+    doStats(readInput(args.slice(1)));
+    break;
+  case 'version':
+    console.log('gcf 0.1.0');
+    break;
+  case '-h':
+  case '--help':
+  case 'help':
+    process.stdout.write(USAGE);
+    break;
+  default:
+    if (!cmd) {
+      process.stderr.write(USAGE);
+      process.exit(1);
+    }
+    process.stderr.write(`unknown command: ${cmd}\n\n`);
+    process.stderr.write(USAGE);
+    process.exit(1);
+}

package/src/constants.ts

@@ -0,0 +1,43 @@
+/**
+ * KindAbbrev maps full kind names to short GCF abbreviations.
+ */
+export const KIND_ABBREV: Record<string, string> = {
+  function: 'fn',
+  type: 'type',
+  method: 'method',
+  interface: 'iface',
+  var: 'var',
+  const: 'const',
+  resource: 'resource',
+  table: 'table',
+  class: 'class',
+  selector: 'selector',
+  field: 'field',
+  route_handler: 'route',
+  external: 'ext',
+  file: 'file',
+  package: 'pkg',
+  service: 'svc',
+};
+
+/**
+ * KindExpand is the reverse of KindAbbrev: maps abbreviations back to full kind names.
+ */
+export const KIND_EXPAND: Record<string, string> = {
+  fn: 'function',
+  type: 'type',
+  method: 'method',
+  iface: 'interface',
+  var: 'var',
+  const: 'const',
+  resource: 'resource',
+  table: 'table',
+  class: 'class',
+  selector: 'selector',
+  field: 'field',
+  route: 'route_handler',
+  ext: 'external',
+  file: 'file',
+  pkg: 'package',
+  svc: 'service',
+};