r2mcp 0.2.0

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,123 @@
+/**
+ * All r2mcp MCP tools that participate in the breadcrumb contract (R2).
+ * Adding a new tool requires adding it here AND a BreadcrumbContext variant below.
+ */
+export type ToolName = 'remember' | 'recall' | 'search' | 'stats' | 'meditate' | 'reject' | 'compile' | 'lint' | 'classify' | 'dump_edges_sidecar' | 'extract_entities';
+/**
+ * A single next-step recommendation. All three fields are required and must be non-empty.
+ */
+export interface Breadcrumb {
+    name: string;
+    usage: string;
+    why: string;
+}
+/**
+ * Per-tool context shape — discriminated union. Each variant carries the tool name plus
+ * whatever args/response shape the mappers need to inspect for that tool.
+ *
+ * Tools NOT in the R4 mapping table (search, stats, meditate, reject, compile, classify,
+ * dump_edges_sidecar) use `NoSignalContext` — they always return next_tools: [] for Phase 5.
+ */
+export type BreadcrumbContext = {
+    tool: 'recall';
+    response: RecallResponse;
+    args: RecallArgs;
+} | {
+    tool: 'lint';
+    response: LintResponse;
+    args: LintArgs;
+} | {
+    tool: 'remember';
+    response: RememberResponse;
+    args: RememberArgs;
+} | {
+    tool: 'extract_entities';
+    response: ExtractEntitiesResponse;
+    args: ExtractEntitiesArgs;
+} | {
+    tool: 'search' | 'stats' | 'meditate' | 'reject' | 'compile' | 'classify' | 'dump_edges_sidecar';
+    response: unknown;
+    args: unknown;
+};
+/**
+ * Minimal structural shape of a single recall result. Mirrors
+ * `RecallResult` in src/tools/recall.ts — the only fields the breadcrumb
+ * logic reads. The per-result `signals` field claimed by earlier drafts
+ * of this file does NOT exist on the real response; signals are top-level.
+ */
+export interface RecallResultItem {
+    id: string;
+    content: string;
+}
+/**
+ * Recall response signal — flat shape from src/edges/types.ts `RecallSignal`.
+ * `from_id` is the memory in the recall results whose edge produced the
+ * signal; `to_id` is the partner on the other end.
+ */
+export interface RecallSignal {
+    kind: 'contradicts' | 'superseded_by';
+    from_id: string;
+    to_id: string;
+}
+export interface RecallResponse {
+    results: RecallResultItem[];
+    total_results: number;
+    search_mode: string;
+    tiers_searched: string[];
+    query: string;
+    /** Top-level signals array per SPEC-044 recall response shape. */
+    signals?: RecallSignal[];
+}
+export interface RecallArgs {
+    query?: string;
+    entity?: string;
+}
+export interface LintFinding {
+    check: string;
+    memory_id: string;
+    topic?: string;
+    detail?: string;
+}
+export interface LintResponse {
+    findings: LintFinding[];
+    total_findings: number;
+}
+export interface LintArgs {
+    check?: string;
+}
+/**
+ * Mirrors `RememberResult` in src/tools/remember.ts. The remember handler
+ * sets `id` (no `memory_id`); the breadcrumb mapper reads `id` only.
+ */
+export interface RememberResponse {
+    operation: string;
+    id?: string;
+    message?: string;
+}
+export interface RememberArgs {
+    tier?: string;
+    content?: string;
+}
+export interface ExtractedEntitySummary {
+    canonical_name: string;
+    type: string;
+    confidence?: number;
+}
+export interface ExtractEntitiesResponse {
+    entities_created: number;
+    entities_updated: number;
+    new_entities?: ExtractedEntitySummary[];
+    total_cost_usd?: number;
+}
+export interface ExtractEntitiesArgs {
+    since_days?: number;
+    full?: boolean;
+}
+export declare class InvalidBreadcrumbError extends Error {
+    constructor(field: string, value: unknown);
+}
+export declare function assertBreadcrumb(b: unknown): asserts b is Breadcrumb;
+export declare const MAX_BREADCRUMBS = 3;
+export declare function withBreadcrumbs<T extends object>(response: T, context: BreadcrumbContext): T & {
+    next_tools: Breadcrumb[];
+};

package/dist/breadcrumbs.js

@@ -0,0 +1,135 @@
+// src/breadcrumbs.ts
+// SPEC-047 Phase 5 — Tool-response breadcrumbs (Tao of Mac: "servers plan, models walk").
+// Pure, no I/O, no DB, no LLM. All decisions are inspection of (response, context).
+export class InvalidBreadcrumbError extends Error {
+    constructor(field, value) {
+        super(`Invalid breadcrumb: field "${field}" must be a non-empty string; got ${JSON.stringify(value)}`);
+        this.name = 'InvalidBreadcrumbError';
+    }
+}
+export function assertBreadcrumb(b) {
+    if (!b || typeof b !== 'object') {
+        throw new InvalidBreadcrumbError('breadcrumb', b);
+    }
+    const obj = b;
+    for (const field of ['name', 'usage', 'why']) {
+        const v = obj[field];
+        if (typeof v !== 'string' || v.length === 0) {
+            throw new InvalidBreadcrumbError(field, v);
+        }
+    }
+}
+export const MAX_BREADCRUMBS = 3;
+// Per-tool mappers.
+function mapRecall(ctx) {
+    // Production shape (SPEC-044): RecallResponse.signals is a TOP-LEVEL flat
+    // array of {kind, from_id, to_id, ...}. The earlier nested per-result
+    // `r.signals.contradictions[]` shape claimed by this mapper never existed
+    // on the real response — see claw-sup7.
+    const seen = new Set();
+    const breadcrumbs = [];
+    for (const s of ctx.response.signals ?? []) {
+        if (s.kind !== 'contradicts')
+            continue;
+        if (seen.has(s.from_id))
+            continue;
+        seen.add(s.from_id);
+        breadcrumbs.push({
+            name: 'lint',
+            usage: `lint --check=contradictions --memory-id=${s.from_id}`,
+            why: 'recall flagged a contradiction on this memory; lint diagnoses it',
+        });
+    }
+    return breadcrumbs;
+}
+function mapLint(ctx) {
+    // R6 truncation ranking: by descending contradiction count per topic; alphabetical for ties.
+    const counts = new Map();
+    for (const f of ctx.response.findings) {
+        if (f.check !== 'contradictions')
+            continue;
+        if (!f.topic)
+            continue;
+        counts.set(f.topic, (counts.get(f.topic) ?? 0) + 1);
+    }
+    const ordered = Array.from(counts.entries()).sort((a, b) => {
+        if (b[1] !== a[1])
+            return b[1] - a[1]; // descending count
+        return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0; // alpha tiebreak
+    });
+    return ordered.map(([topic]) => ({
+        name: 'compile',
+        usage: `compile --topic=${topic}`,
+        why: 'Contradictions on this topic; recompile the wiki view',
+    }));
+}
+const QUERY_SNIPPET_MAX = 80;
+function mapRemember(ctx) {
+    // Production shape: RememberResult exposes `id` only (no `memory_id`).
+    // The breadcrumb fires for ADD/UPDATE/REJECTION (which set id) and skips
+    // NOOP / unresolved ARCHIVE (which leave id undefined). claw-sup7.
+    if (!ctx.response.id)
+        return [];
+    const content = ctx.args.content ?? '';
+    if (!content.trim())
+        return [];
+    const snippet = content.slice(0, QUERY_SNIPPET_MAX).replace(/\s+/g, ' ').trim();
+    const tier = ctx.args.tier;
+    const usage = tier
+        ? `recall --query=${JSON.stringify(snippet)} --tier=${tier}`
+        : `recall --query=${JSON.stringify(snippet)}`;
+    return [
+        {
+            name: 'recall',
+            usage,
+            why: 'Verify the memory was indexed correctly',
+        },
+    ];
+}
+function mapExtractEntities(ctx) {
+    // R4 trigger: entities_created > 0
+    if ((ctx.response.entities_created ?? 0) <= 0)
+        return [];
+    const entities = ctx.response.new_entities ?? [];
+    if (entities.length === 0)
+        return [];
+    // Open Question 3 resolution: pick by highest confidence; alphabetical tiebreak.
+    const ranked = [...entities].sort((a, b) => {
+        const ca = a.confidence ?? 0;
+        const cb = b.confidence ?? 0;
+        if (cb !== ca)
+            return cb - ca;
+        return a.canonical_name < b.canonical_name ? -1 : a.canonical_name > b.canonical_name ? 1 : 0;
+    });
+    const top = ranked[0];
+    return [
+        {
+            name: 'recall',
+            usage: `recall --entity=${top.canonical_name}`,
+            why: 'Confirm the newly extracted entity links to expected memories',
+        },
+    ];
+}
+function dispatchMapper(ctx) {
+    switch (ctx.tool) {
+        case 'recall':
+            return mapRecall(ctx);
+        case 'lint':
+            return mapLint(ctx);
+        case 'remember':
+            return mapRemember(ctx);
+        case 'extract_entities':
+            return mapExtractEntities(ctx);
+        // No-signal tools always return empty for Phase 5 — see R4.
+        default:
+            return [];
+    }
+}
+export function withBreadcrumbs(response, context) {
+    const candidates = dispatchMapper(context);
+    // Validate each candidate before truncation — bad breadcrumbs throw at construction.
+    for (const b of candidates)
+        assertBreadcrumb(b);
+    const next_tools = candidates.slice(0, MAX_BREADCRUMBS);
+    return { ...response, next_tools };
+}

package/dist/cli/classify-edges.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+import '../instrumentation.js';

package/dist/cli/classify-edges.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env tsx
+// OTel instrumentation MUST be imported first — before any other module —
+// so OTEL_TRACEPARENT propagation has an SDK to attach the parent context to
+// (claw-1ejd). Without this import, propagation.extract() is a no-op.
+import '../instrumentation.js';
+/**
+ * SPEC-043 / SPEC-044 edge classifier CLI.
+ *
+ * Usage:
+ *   npm run edges:classify -- [--since=DURATION] [--max-cost=USD] [--dry-run] [--resume=<run_id>] [--provider=<name>]
+ *
+ * Provider selection precedence (D.R3):
+ *   1. --provider=claude-code|anthropic|openrouter
+ *   2. R2MCP_CLASSIFIER_PROVIDER env var
+ *   3. Auto-fallback (claude-code → anthropic → openrouter)
+ *
+ * Examples:
+ *   npm run edges:classify -- --dry-run                       # estimate only
+ *   npm run edges:classify -- --max-cost=5.00                 # full run, $5 cap
+ *   npm run edges:classify -- --since=7d --max-cost=1.00      # incremental
+ *   npm run edges:classify -- --resume=abc123                 # continue prior run
+ *   npm run edges:classify -- --provider=claude-code          # force Max-covered
+ *
+ * Exit codes:
+ *   0 — completed normally OR hit cap gracefully OR dry-run completed
+ *   1 — fatal error (DB unreachable, no provider configured, etc.)
+ */
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { initDb, getPool, closeDb } from '../db.js';
+import { findCandidatePairs } from '../edges/candidate-pairs.js';
+import { stage1HaikuFilter } from '../edges/stage1-haiku.js';
+import { stage2OpusClassify } from '../edges/stage2-opus.js';
+import { StateStore, RunSummaryWriter } from '../edges/state.js';
+import { runClassifier } from '../edges/classifier.js';
+import { withToolSpan } from '../telemetry.js';
+import { selectProvider, isProviderName, ProviderUnavailableError, } from '../providers/index.js';
+import { loadEnvFile } from '../env.js';
+// Load .env from project root — launchd-spawned subprocesses don't inherit
+// shell env, so OTEL_ENABLED + DB URL + provider keys must be loaded here
+// (claw-1ejd; mirrors src/index.ts).
+loadEnvFile(resolve(process.env.PROJECT_ROOT || process.cwd(), '.env'));
+const CLASSIFIER_VERSION = 'edges-v1-2026-05-03';
+function parseArgs(argv) {
+    const out = {
+        maxCostUsd: Number(process.env.R2MCP_EDGE_MAX_USD ?? '1.00'),
+        dryRun: false,
+    };
+    for (const arg of argv) {
+        if (arg === '--dry-run')
+            out.dryRun = true;
+        else if (arg.startsWith('--max-cost='))
+            out.maxCostUsd = Number(arg.split('=')[1]);
+        else if (arg.startsWith('--resume='))
+            out.resumeRunId = arg.split('=')[1];
+        else if (arg.startsWith('--since=')) {
+            const raw = arg.split('=')[1];
+            const m = raw.match(/^(\d+)d$/);
+            if (!m)
+                throw new Error(`--since must be Nd (e.g. 7d), got ${raw}`);
+            out.sinceDays = Number(m[1]);
+        }
+        else if (arg.startsWith('--provider=')) {
+            const raw = arg.split('=')[1];
+            if (!isProviderName(raw)) {
+                throw new Error(`--provider must be one of claude-code|anthropic|openrouter, got ${raw}`);
+            }
+            out.providerFlag = raw;
+        }
+    }
+    return out;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const runId = args.resumeRunId ?? randomUUID();
+    const dataDir = resolve(process.env.R2MCP_EDGE_DATA_DIR ?? 'data');
+    const state = new StateStore(resolve(dataDir, 'edges-state.jsonl'), resolve(dataDir, 'edges-state.last-run'));
+    const summaryWriter = new RunSummaryWriter(resolve(dataDir, 'edges-state.runs'));
+    await initDb();
+    const pool = getPool();
+    // Lazy-create the provider only for non-dry-run paths. Dry-run is read-only
+    // and never calls into a provider, so don't fail if none is configured.
+    const provider = args.dryRun ? null : await selectProvider({ flag: args.providerFlag });
+    const summary = await withToolSpan('classify_edges', {
+        run_id: runId,
+        dry_run: args.dryRun,
+        max_cost_usd: args.maxCostUsd,
+        provider: provider?.name ?? 'dry-run',
+    }, () => runClassifier({ runId, maxCostUsd: args.maxCostUsd, dryRun: args.dryRun, sinceDays: args.sinceDays }, {
+        classifierVersion: CLASSIFIER_VERSION,
+        state,
+        summaryWriter,
+        concurrencyLimit: provider?.concurrencyLimit ?? 1,
+        providerName: provider?.name,
+        findCandidatePairs: (opts) => findCandidatePairs(pool, opts),
+        fetchMemoryById: async (id) => {
+            const r = await pool.query('SELECT id, content, type FROM memories WHERE id = $1', [id]);
+            return r.rows[0] ?? null;
+        },
+        stage1Filter: (pair) => stage1HaikuFilter(provider, pair),
+        stage2Classify: (pair) => stage2OpusClassify(provider, pair),
+        insertEdge: async (fromId, toId, relation, confidence, rationale, version) => {
+            const res = await pool.query(`INSERT INTO memory_edges (from_memory_id, to_memory_id, relation, confidence, rationale, classifier_version)
+             VALUES ($1, $2, $3, $4, $5, $6)
+             ON CONFLICT (from_memory_id, to_memory_id, relation) DO UPDATE
+               SET confidence = EXCLUDED.confidence,
+                   rationale = EXCLUDED.rationale,
+                   updated_at = NOW()
+             RETURNING id`, [fromId, toId, relation, confidence, rationale, version]);
+            return res.rows[0].id;
+        },
+        estimateCost: async (pairs) => {
+            const stage1 = pairs.length * 0.0005;
+            const stage2 = pairs.length * 0.2 * 0.018;
+            return stage1 + stage2;
+        },
+    }));
+    process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+    await closeDb();
+    process.exit(0);
+}
+main().catch((err) => {
+    if (err instanceof ProviderUnavailableError) {
+        process.stderr.write(`${err.message}\n`);
+    }
+    else {
+        process.stderr.write(`ERROR: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    process.exit(1);
+});

package/dist/cli/compile-wiki.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+import '../instrumentation.js';

package/dist/cli/compile-wiki.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env tsx
+// OTel instrumentation MUST be imported first — before any other module —
+// so OTEL_TRACEPARENT propagation has an SDK to attach the parent context to
+// (claw-1ejd). Without this import, propagation.extract() is a no-op.
+import '../instrumentation.js';
+/**
+ * SPEC-044 Section B — wiki compile CLI driver.
+ *
+ * Usage:
+ *   npm run compile-wiki -- [--tier=<name> | --all | --topic=<name>] [--dry-run] [--max-cost=USD] [--provider=<name>]
+ *
+ * Provider selection: same as classify-edges (claude-code → anthropic →
+ * openrouter auto-fallback, --provider= overrides).
+ *
+ * Output goes to `<projectRoot>/memory/compiled/`. The host project gitignores
+ * that path because it is regenerable.
+ *
+ * Exit codes:
+ *   0 — completed normally OR hit cap gracefully
+ *   1 — fatal error (DB, no provider, validation failure, etc.)
+ */
+import { randomUUID } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { initDb, getPool, closeDb } from '../db.js';
+import { selectProvider, isProviderName, ProviderUnavailableError, } from '../providers/index.js';
+import { runCompile } from '../compiler/run.js';
+import { withToolSpan } from '../telemetry.js';
+import { loadEnvFile } from '../env.js';
+const VALID_TIERS = ['preferences', 'project-context', 'conversations'];
+function isTier(s) {
+    return VALID_TIERS.includes(s);
+}
+function parseArgs(argv) {
+    const out = {
+        all: false,
+        dryRun: false,
+        maxCostUsd: Number(process.env.R2MCP_COMPILE_MAX_USD ?? '1.00'),
+    };
+    for (const arg of argv) {
+        if (arg === '--dry-run')
+            out.dryRun = true;
+        else if (arg === '--all')
+            out.all = true;
+        else if (arg.startsWith('--tier=')) {
+            const t = arg.split('=')[1];
+            if (!isTier(t))
+                throw new Error(`--tier must be one of ${VALID_TIERS.join('|')}, got ${t}`);
+            out.tier = t;
+        }
+        else if (arg.startsWith('--topic=')) {
+            out.topic = arg.split('=')[1];
+        }
+        else if (arg.startsWith('--max-cost=')) {
+            out.maxCostUsd = Number(arg.split('=')[1]);
+        }
+        else if (arg.startsWith('--provider=')) {
+            const raw = arg.split('=')[1];
+            if (!isProviderName(raw)) {
+                throw new Error(`--provider must be claude-code|anthropic|openrouter, got ${raw}`);
+            }
+            out.providerFlag = raw;
+        }
+    }
+    return out;
+}
+async function loadMemoriesFromDb(scope) {
+    const pool = getPool();
+    // Load memories — filter at the SQL layer when scope is narrow.
+    let where = `type != 'archived'`;
+    const params = [];
+    if (scope.tier) {
+        params.push(scope.tier);
+        where += ` AND tier = $${params.length}`;
+    }
+    if (scope.topic) {
+        params.push(scope.topic);
+        where += ` AND $${params.length} = ANY(topics)`;
+    }
+    const rows = await pool.query(`SELECT id, tier, type, content, topics, people, created_at::text AS created_at
+     FROM memories WHERE ${where}
+     ORDER BY id`, params);
+    const memories = rows.rows.map((r) => ({
+        id: r.id,
+        tier: r.tier,
+        type: r.type,
+        content: r.content,
+        topics: r.topics ?? [],
+        people: r.people ?? [],
+        created_at: r.created_at,
+    }));
+    // Attach inbound edges for prose framing (B.AC7). Only fetch edges that
+    // touch memories we already have — keeps the query bounded.
+    const ids = memories.map((m) => m.id);
+    if (ids.length > 0) {
+        const edgeRows = await pool.query(`SELECT from_memory_id, to_memory_id, relation, rationale, confidence::float
+       FROM memory_edges
+       WHERE from_memory_id = ANY($1) OR to_memory_id = ANY($1)`, [ids]);
+        const byId = new Map(memories.map((m) => [m.id, m]));
+        for (const e of edgeRows.rows) {
+            const m = byId.get(e.from_memory_id) ?? byId.get(e.to_memory_id);
+            if (!m)
+                continue;
+            m.edges = m.edges ?? [];
+            m.edges.push({
+                from_memory_id: e.from_memory_id,
+                to_memory_id: e.to_memory_id,
+                relation: e.relation,
+                rationale: e.rationale,
+                confidence: e.confidence,
+            });
+        }
+    }
+    return memories;
+}
+function gitSha(cwd) {
+    try {
+        const out = execSync('git rev-parse HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+        return out.toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+// Load .env from project root — launchd-spawned subprocesses don't inherit
+// shell env, so OTEL_ENABLED + DB URL + provider keys must be loaded here
+// (claw-1ejd; mirrors src/index.ts).
+loadEnvFile(resolve(process.env.PROJECT_ROOT || process.cwd(), '.env'));
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (!args.tier && !args.all && !args.topic) {
+        throw new Error('Specify exactly one of --tier=<name> | --all | --topic=<name>');
+    }
+    const projectRoot = process.env.PROJECT_ROOT || process.cwd();
+    const compiledDir = resolve(projectRoot, 'memory/compiled');
+    const runId = randomUUID();
+    const startedAt = new Date().toISOString();
+    const sourceGitSha = gitSha(projectRoot);
+    await initDb();
+    const provider = await selectProvider({ flag: args.providerFlag });
+    const summary = await withToolSpan('compile_wiki', {
+        run_id: runId,
+        dry_run: args.dryRun,
+        max_cost_usd: args.maxCostUsd,
+        provider: provider.name,
+        scope: args.tier ?? args.topic ?? 'all',
+    }, () => runCompile({
+        tier: args.tier,
+        all: args.all,
+        topic: args.topic,
+        dryRun: args.dryRun,
+        maxCostUsd: args.maxCostUsd,
+        runId,
+        startedAt,
+        sourceGitSha,
+        compiledDir,
+    }, {
+        provider,
+        loadMemories: () => loadMemoriesFromDb(args),
+    }));
+    process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+    await closeDb();
+    process.exit(0);
+}
+main().catch((err) => {
+    if (err instanceof ProviderUnavailableError) {
+        process.stderr.write(`${err.message}\n`);
+    }
+    else {
+        process.stderr.write(`ERROR: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    process.exit(1);
+});

package/dist/cli/dump-edges-json.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+export {};

package/dist/cli/dump-edges-json.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env tsx
+/**
+ * Phase 0b sidecar CLI — dump memory_edges + memories to JSON.
+ *
+ * Production callers should use the MCP tool `dump_edges_sidecar` instead.
+ * This script remains as the dev workflow entry point:
+ *   tsx scripts/dump-edges-json.ts --out-dir=memory/compiled
+ */
+import { resolve } from 'node:path';
+import { dumpEdgesJson } from '../tools/dump-edges-sidecar.js';
+const DEFAULT_DIR = 'memory/compiled';
+async function main() {
+    const dirArg = process.argv.find((a) => a.startsWith('--out-dir='));
+    const outDir = resolve(dirArg ? dirArg.split('=')[1] : DEFAULT_DIR);
+    const result = await dumpEdgesJson(outDir);
+    console.log(`Wrote ${result.edges_count} edges + ${result.memories_count} memories to ${result.out_dir}/`);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/cli/extract-entities.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+import '../instrumentation.js';
+import { type ProviderName } from '../providers/index.js';
+export interface CliArgs {
+    sinceDays?: number;
+    maxCostUsd: number;
+    providerFlag?: ProviderName;
+    resume?: string;
+    full: boolean;
+    dataDir: string;
+    contextTopN: number;
+}
+export declare class UsageError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare function parseArgs(argv: string[]): CliArgs;