@cavelang/cli 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @cavelang/cli
+
+The `cave` command — the whole stack behind one binary. Runs directly from
+TypeScript sources via Node's type stripping; no build step.
+
+```
+$ echo 'auth USES jwt @ 90%' | pnpm exec cave parse
+ok: 1 claim
+
+$ pnpm exec cave add notes.cave --db knowledge.db
+added 12 claim(s), 3 edge(s)
+
+$ pnpm exec cave query '?x USES jwt' --db knowledge.db
+?x = auth/middleware
+?x = api/gateway
+
+$ pnpm exec cave query '?cause CAUSE app/crash' 'WHERE conf >= 0.7' --db knowledge.db
+$ pnpm exec cave export --db knowledge.db --current
+$ pnpm exec cave demo
+```
+
+## Commands
+
+| Command | Flags | Behavior |
+|---|---|---|
+| `parse [file]` | `--json` | Lint (stdin by default). Exit 1 when diagnostics exist; `--json` dumps the AST document. |
+| `add [file…] --db p` | `--strict`, `--no-prelude` | Ingest. Lenient by default (problems on stderr, valid lines land); `--strict` rolls back on any problem; `--no-prelude` starts from an empty registry instead of the standard §5.5 pairs. |
+| `import [file…] --db p` | `--strict`, `--no-prelude` | Restore/merge a database from CAVE text — same operation as `add`, because canonical text *is* the interchange format. |
+| `query <pattern…> --db p` | `--json`, `--all`, `--no-prelude` | CAVE-Q. Extra positionals join as lines, so `WHERE` filters ride as separate arguments. Bindings print as `?x = value`; fully bound patterns print the matched raw line (or the pattern itself for transitive matches, which carry no row). `--no-prelude` aligns the read-time registry with a store written via `add --no-prelude`. |
+| `export --db p` | `--out <file>`, `--current`, `--no-prelude` | Canonical CAVE text — all rows in tx order, or current beliefs only. Stdout by default; `--out` writes a file and reports the claim count. |
+| `mcp --db p` | `--no-prelude` | Serve the engine as an MCP server on stdio (see [`@cavelang/mcp`](../mcp)) — tools for add/query/search/about/neighbors/reconstruct/export/lint, with the §22 spec card as server instructions. |
+| `ingest <globs…> --db p` | see `cave ingest --help` | LLM-driven ingestion of files through any headless agent (see [`@cavelang/ingest`](../ingest)): batching, instructions markdown, hybrid knowledge context, MCP or stdout agents, incremental digests, `--plan` NDJSON for SDK drivers. |
+| `demo` | | The cave-loop multi-hop recovery demo (§18). |
+
+## Text backup / interchange
+
+```
+$ cave export --db knowledge.db --out backup.cave
+exported 812 claim(s) to backup.cave
+
+$ cave import backup.cave --db restored.db
+added 812 claim(s), 37 edge(s)
+```
+
+The text round trip preserves every claim with its metadata, the **full
+belief-series order** (rows export in tx order and re-ingest with fresh
+monotonic tx ids, so latest-tx-wins resolution is unchanged),
+qualifier/grouping edges, and in-band registry declarations (`REVERSE`,
+`X IS verb`) — a restored database answers queries identically, inverse
+reads included. Original transaction timestamps are re-minted: canonical
+CAVE text carries no transaction identity. Use `--current` for a compact
+backup of current beliefs only (history intentionally dropped).
+
+Everything is testable without spawning: each command is a pure function
+`(argv) → { code, out, err }` (`@cavelang/cli` exports them), and `main.ts` is
+a four-line dispatcher. Tests cover both layers.

package/dist/src/cli.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `cave` command implementation — pure functions from parsed arguments to
+ * `{ code, out, err }`, so tests can call commands directly and `main.ts`
+ * stays a thin dispatcher.
+ *
+ * Commands:
+ *
+ * - `cave parse [file]` — lint / dump the AST (`--json`)
+ * - `cave add [file…] --db <path>` — ingest into a store (`--strict`)
+ * - `cave query '<pattern>' --db <path>` — CAVE-Q (`--json`, `--all`)
+ * - `cave export --db <path>` — canonical text out (`--current`)
+ * - `cave demo` — the cave-loop multi-hop recovery demo
+ *
+ * `file` defaults to stdin (`-`).
+ */
+export type Output = {
+    readonly code: number;
+    readonly out: string;
+    readonly err: string;
+};
+export declare const usage = "cave \u2014 Compressed Atomic Verb Expressions\n\nUsage:\n  cave parse [file] [--json]             lint CAVE text (stdin when no file)\n  cave add [file...] --db <path>         ingest into a store [--strict] [--no-prelude]\n  cave import [file...] --db <path>      restore/merge a database from CAVE text (same as add)\n  cave query <pattern> --db <path>       run a CAVE-Q pattern [--json] [--all] [--no-prelude]\n  cave export --db <path> [--out <file>] emit canonical CAVE text [--current] [--no-prelude]\n  cave mcp --db <path>                   serve the engine as an MCP server on stdio [--no-prelude]\n  cave ingest <globs...> --db <path>     LLM-driven ingestion of files (cave ingest --help)\n  cave demo                              run the cave-loop reconstruction demo\n  cave help                              this text\n\nThe spec lives in the .claude/skills/ directory at the repository root\n(section index in README.md).";
+export declare const parseCommand: (argv: readonly string[]) => Output;
+export declare const addCommand: (argv: readonly string[]) => Output;
+/**
+ * `cave import` — restore/merge a knowledge database from CAVE text files.
+ * Identical to `add` by design: canonical CAVE text *is* the interchange
+ * format (spec §2.2), so importing a file exported with `cave export`
+ * replays its claims append-only. What the text round trip preserves:
+ * every claim with metadata, full belief-series order (rows export in tx
+ * order and re-ingest with fresh monotonic tx ids), qualifier/grouping
+ * edges, and in-band registry declarations. Original tx timestamps are
+ * re-minted — the text format carries no transaction identity.
+ */
+export declare const importCommand: (argv: readonly string[]) => Output;
+export declare const queryCommand: (argv: readonly string[]) => Output;
+export declare const exportCommand: (argv: readonly string[]) => Output;
+export declare const demoCommand: () => Output;
+/** Dispatches one invocation. */
+export declare const cave: (argv: readonly string[]) => Output;
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB,CAAA;AAQD,eAAO,MAAM,KAAK,86BAcY,CAAA;AAO9B,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAyBtD,CAAA;AAkCD,eAAO,MAAM,UAAU,SAhCwB,SAAS,MAAM,EAAE,KAAG,MAgCrB,CAAA;AAE9C;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,SA5CqB,SAAS,MAAM,EAAE,KAAG,MA4Cf,CAAA;AAEpD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAyCtD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA0BvD,CAAA;AAED,eAAO,MAAM,WAAW,QAAO,MACS,CAAA;AAExC,iCAAiC;AACjC,eAAO,MAAM,IAAI,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA4B9C,CAAA"}

package/dist/src/cli.js

@@ -0,0 +1,218 @@
+/**
+ * `cave` command implementation — pure functions from parsed arguments to
+ * `{ code, out, err }`, so tests can call commands directly and `main.ts`
+ * stays a thin dispatcher.
+ *
+ * Commands:
+ *
+ * - `cave parse [file]` — lint / dump the AST (`--json`)
+ * - `cave add [file…] --db <path>` — ingest into a store (`--strict`)
+ * - `cave query '<pattern>' --db <path>` — CAVE-Q (`--json`, `--all`)
+ * - `cave export --db <path>` — canonical text out (`--current`)
+ * - `cave demo` — the cave-loop multi-hop recovery demo
+ *
+ * `file` defaults to stdin (`-`).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { parseDocument } from '@cavelang/parser';
+import { Registry, standardRegistry } from '@cavelang/canonical';
+import { open } from '@cavelang/store';
+import { query as caveQuery } from '@cavelang/query';
+import { Demo } from '@cavelang/loop';
+const ok = (out) => ({ code: 0, out, err: '' });
+const fail = (err, code = 1) => ({ code, out: '', err });
+export const usage = `cave — Compressed Atomic Verb Expressions
+
+Usage:
+  cave parse [file] [--json]             lint CAVE text (stdin when no file)
+  cave add [file...] --db <path>         ingest into a store [--strict] [--no-prelude]
+  cave import [file...] --db <path>      restore/merge a database from CAVE text (same as add)
+  cave query <pattern> --db <path>       run a CAVE-Q pattern [--json] [--all] [--no-prelude]
+  cave export --db <path> [--out <file>] emit canonical CAVE text [--current] [--no-prelude]
+  cave mcp --db <path>                   serve the engine as an MCP server on stdio [--no-prelude]
+  cave ingest <globs...> --db <path>     LLM-driven ingestion of files (cave ingest --help)
+  cave demo                              run the cave-loop reconstruction demo
+  cave help                              this text
+
+The spec lives in the .claude/skills/ directory at the repository root
+(section index in README.md).`;
+const readInput = (files) => files.length === 0 || (files.length === 1 && files[0] === '-') ?
+    readFileSync(0, 'utf8') :
+    files.map(file => readFileSync(file, 'utf8')).join('\n');
+export const parseCommand = (argv) => {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: { json: { type: 'boolean' } },
+        allowPositionals: true
+    });
+    const input = readInput(positionals);
+    const document = parseDocument(input);
+    if (values.json === true) {
+        return ok(`${JSON.stringify(document, undefined, 2)}\n`);
+    }
+    const counts = new Map();
+    for (const line of document.lines) {
+        counts.set(line.kind, (counts.get(line.kind) ?? 0) + 1);
+    }
+    const summary = [...counts]
+        .map(([kind, count]) => `${count} ${kind}`)
+        .join(', ');
+    if (document.diagnostics.length === 0) {
+        return ok(`ok: ${summary}\n`);
+    }
+    const problems = document.diagnostics
+        .map(diagnostic => `line ${diagnostic.line}: ${diagnostic.message}`)
+        .join('\n');
+    return { code: 1, out: `${summary}\n`, err: `${problems}\n` };
+};
+const ingestCommand = (name) => (argv) => {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            strict: { type: 'boolean' },
+            'no-prelude': { type: 'boolean' }
+        },
+        allowPositionals: true
+    });
+    if (values.db === undefined) {
+        return fail(`cave ${name}: --db <path> is required\n`);
+    }
+    const input = readInput(positionals);
+    const store = open(values.db, values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        const result = store.ingest(input, { strict: values.strict === true });
+        const problems = result.problems
+            .map(problem => `line ${problem.line}: ${problem.message}`)
+            .join('\n');
+        return {
+            code: 0,
+            out: `added ${result.ids.length} claim(s), ${result.edges} edge(s)\n`,
+            err: problems === '' ? '' : `${problems}\n`
+        };
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    finally {
+        store.close();
+    }
+};
+export const addCommand = ingestCommand('add');
+/**
+ * `cave import` — restore/merge a knowledge database from CAVE text files.
+ * Identical to `add` by design: canonical CAVE text *is* the interchange
+ * format (spec §2.2), so importing a file exported with `cave export`
+ * replays its claims append-only. What the text round trip preserves:
+ * every claim with metadata, full belief-series order (rows export in tx
+ * order and re-ingest with fresh monotonic tx ids), qualifier/grouping
+ * edges, and in-band registry declarations. Original tx timestamps are
+ * re-minted — the text format carries no transaction identity.
+ */
+export const importCommand = ingestCommand('import');
+export const queryCommand = (argv) => {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            json: { type: 'boolean' },
+            all: { type: 'boolean' },
+            'no-prelude': { type: 'boolean' }
+        },
+        allowPositionals: true
+    });
+    if (values.db === undefined) {
+        return fail('cave query: --db <path> is required\n');
+    }
+    if (positionals.length === 0) {
+        return fail('cave query: a pattern is required (spec §12.1)\n');
+    }
+    const pattern = positionals.join('\n');
+    const store = open(values.db, values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        const matches = caveQuery(store, pattern, { all: values.all === true });
+        if (values.json === true) {
+            return ok(`${JSON.stringify(matches, undefined, 2)}\n`);
+        }
+        if (matches.length === 0) {
+            return ok('no matches\n');
+        }
+        const lines = matches.map(match => {
+            const bindings = Object.entries(match.bindings)
+                .map(([name, value]) => `?${name} = ${value}`)
+                .join('  ');
+            // A fully bound pattern has no bindings to print; transitive matches
+            // additionally carry no row — confirm with the pattern itself.
+            return bindings !== '' ? bindings : match.row?.raw_line ?? pattern.split('\n')[0];
+        });
+        return ok(`${lines.join('\n')}\n`);
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    finally {
+        store.close();
+    }
+};
+export const exportCommand = (argv) => {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            current: { type: 'boolean' },
+            out: { type: 'string' },
+            'no-prelude': { type: 'boolean' }
+        },
+        allowPositionals: false
+    });
+    if (values.db === undefined) {
+        return fail('cave export: --db <path> is required\n');
+    }
+    const store = open(values.db, values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        const text = store.exportText({ current: values.current === true });
+        if (values.out === undefined) {
+            return ok(text);
+        }
+        writeFileSync(values.out, text);
+        const claims = text === '' ? 0 : text.trimEnd().split('\n').length;
+        return ok(`exported ${claims} claim(s) to ${values.out}\n`);
+    }
+    finally {
+        store.close();
+    }
+};
+export const demoCommand = () => ok(`${Demo.run().lines.join('\n')}\n`);
+/** Dispatches one invocation. */
+export const cave = (argv) => {
+    const [command, ...rest] = argv;
+    try {
+        switch (command) {
+            case 'parse':
+                return parseCommand(rest);
+            case 'add':
+                return addCommand(rest);
+            case 'import':
+                return importCommand(rest);
+            case 'query':
+            case 'q':
+                return queryCommand(rest);
+            case 'export':
+                return exportCommand(rest);
+            case 'demo':
+                return demoCommand();
+            case undefined:
+            case 'help':
+            case '--help':
+            case '-h':
+                return ok(`${usage}\n`);
+            default:
+                return fail(`cave: unknown command ${JSON.stringify(command)}\n\n${usage}\n`, 2);
+        }
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+};
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@cavelang/cli` — the `cave` command (parse / add / query / export / demo).
+ * Programmatic access to the same implementations lives here.
+ */
+export { addCommand, cave, demoCommand, exportCommand, importCommand, parseCommand, queryCommand, usage } from './cli.ts';
+export type { Output } from './cli.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AACzH,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,6 @@
+/**
+ * `@cavelang/cli` — the `cave` command (parse / add / query / export / demo).
+ * Programmatic access to the same implementations lives here.
+ */
+export { addCommand, cave, demoCommand, exportCommand, importCommand, parseCommand, queryCommand, usage } from "./cli.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA"}

package/dist/src/main.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** `cave` binary entry point — see `cli.ts` for the command implementations. */
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/src/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.ts"],"names":[],"mappings":";AACA,gFAAgF"}

package/dist/src/main.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/** `cave` binary entry point — see `cli.ts` for the command implementations. */
+import { cave } from "./cli.js";
+const argv = process.argv.slice(2);
+if (argv[0] === 'mcp') {
+    // Long-running: serves MCP on stdio until the client disconnects.
+    const { runMcp } = await import('@cavelang/mcp');
+    process.exitCode = await runMcp(argv.slice(1));
+}
+else if (argv[0] === 'ingest') {
+    // Long-running: drives an LLM agent over batches of files.
+    const { runIngest } = await import('@cavelang/ingest');
+    process.exitCode = await runIngest(argv.slice(1));
+}
+else {
+    const { code, out, err } = cave(argv);
+    if (out !== '') {
+        process.stdout.write(out);
+    }
+    if (err !== '') {
+        process.stderr.write(err);
+    }
+    process.exitCode = code;
+}
+//# sourceMappingURL=main.js.map

package/dist/src/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/main.ts"],"names":[],"mappings":";AACA,gFAAgF;AAEhF,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAE/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AAClC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;IACtB,kEAAkE;IAClE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAA;IAChD,OAAO,CAAC,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AAChD,CAAC;KAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;IAChC,2DAA2D;IAC3D,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAA;IACtD,OAAO,CAAC,QAAQ,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AACnD,CAAC;KAAM,CAAC;IACN,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC3B,CAAC;IACD,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC3B,CAAC;IACD,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAA;AACzB,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cavelang/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "cave — CLI for parsing, storing, querying and exporting CAVE knowledge.",
+  "license": "CC0-1.0",
+  "author": "Mirek Rusin (https://github.com/mirek)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mirek/cave.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "bin": {
+    "cave": "./dist/src/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./main": {
+      "types": "./dist/src/main.d.ts",
+      "default": "./dist/src/main.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/test",
+    "!dist/tsconfig.tsbuildinfo",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "License.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cavelang/canonical": "0.1.0",
+    "@cavelang/loop": "0.1.0",
+    "@cavelang/core": "0.1.0",
+    "@cavelang/query": "0.1.0",
+    "@cavelang/parser": "0.1.0",
+    "@cavelang/store": "0.1.0",
+    "@cavelang/mcp": "0.1.0",
+    "@cavelang/ingest": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --disable-warning=ExperimentalWarning --test 'test/*.test.ts'",
+    "typecheck": "tsc -b"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,234 @@
+/**
+ * `cave` command implementation — pure functions from parsed arguments to
+ * `{ code, out, err }`, so tests can call commands directly and `main.ts`
+ * stays a thin dispatcher.
+ *
+ * Commands:
+ *
+ * - `cave parse [file]` — lint / dump the AST (`--json`)
+ * - `cave add [file…] --db <path>` — ingest into a store (`--strict`)
+ * - `cave query '<pattern>' --db <path>` — CAVE-Q (`--json`, `--all`)
+ * - `cave export --db <path>` — canonical text out (`--current`)
+ * - `cave demo` — the cave-loop multi-hop recovery demo
+ *
+ * `file` defaults to stdin (`-`).
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { parseArgs } from 'node:util'
+import { parseDocument } from '@cavelang/parser'
+import { Registry, standardRegistry } from '@cavelang/canonical'
+import { open } from '@cavelang/store'
+import { query as caveQuery } from '@cavelang/query'
+import { Demo } from '@cavelang/loop'
+
+export type Output = {
+  readonly code: number
+  readonly out: string
+  readonly err: string
+}
+
+const ok = (out: string): Output =>
+  ({ code: 0, out, err: '' })
+
+const fail = (err: string, code = 1): Output =>
+  ({ code, out: '', err })
+
+export const usage = `cave — Compressed Atomic Verb Expressions
+
+Usage:
+  cave parse [file] [--json]             lint CAVE text (stdin when no file)
+  cave add [file...] --db <path>         ingest into a store [--strict] [--no-prelude]
+  cave import [file...] --db <path>      restore/merge a database from CAVE text (same as add)
+  cave query <pattern> --db <path>       run a CAVE-Q pattern [--json] [--all] [--no-prelude]
+  cave export --db <path> [--out <file>] emit canonical CAVE text [--current] [--no-prelude]
+  cave mcp --db <path>                   serve the engine as an MCP server on stdio [--no-prelude]
+  cave ingest <globs...> --db <path>     LLM-driven ingestion of files (cave ingest --help)
+  cave demo                              run the cave-loop reconstruction demo
+  cave help                              this text
+
+The spec lives in the .claude/skills/ directory at the repository root
+(section index in README.md).`
+
+const readInput = (files: readonly string[]): string =>
+  files.length === 0 || (files.length === 1 && files[0] === '-') ?
+    readFileSync(0, 'utf8') :
+    files.map(file => readFileSync(file, 'utf8')).join('\n')
+
+export const parseCommand = (argv: readonly string[]): Output => {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: { json: { type: 'boolean' } },
+    allowPositionals: true
+  })
+  const input = readInput(positionals)
+  const document = parseDocument(input)
+  if (values.json === true) {
+    return ok(`${JSON.stringify(document, undefined, 2)}\n`)
+  }
+  const counts = new Map<string, number>()
+  for (const line of document.lines) {
+    counts.set(line.kind, (counts.get(line.kind) ?? 0) + 1)
+  }
+  const summary = [...counts]
+    .map(([kind, count]) => `${count} ${kind}`)
+    .join(', ')
+  if (document.diagnostics.length === 0) {
+    return ok(`ok: ${summary}\n`)
+  }
+  const problems = document.diagnostics
+    .map(diagnostic => `line ${diagnostic.line}: ${diagnostic.message}`)
+    .join('\n')
+  return { code: 1, out: `${summary}\n`, err: `${problems}\n` }
+}
+
+const ingestCommand = (name: string) => (argv: readonly string[]): Output => {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      strict: { type: 'boolean' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: true
+  })
+  if (values.db === undefined) {
+    return fail(`cave ${name}: --db <path> is required\n`)
+  }
+  const input = readInput(positionals)
+  const store = open(values.db, values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  try {
+    const result = store.ingest(input, { strict: values.strict === true })
+    const problems = result.problems
+      .map(problem => `line ${problem.line}: ${problem.message}`)
+      .join('\n')
+    return {
+      code: 0,
+      out: `added ${result.ids.length} claim(s), ${result.edges} edge(s)\n`,
+      err: problems === '' ? '' : `${problems}\n`
+    }
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  } finally {
+    store.close()
+  }
+}
+
+export const addCommand = ingestCommand('add')
+
+/**
+ * `cave import` — restore/merge a knowledge database from CAVE text files.
+ * Identical to `add` by design: canonical CAVE text *is* the interchange
+ * format (spec §2.2), so importing a file exported with `cave export`
+ * replays its claims append-only. What the text round trip preserves:
+ * every claim with metadata, full belief-series order (rows export in tx
+ * order and re-ingest with fresh monotonic tx ids), qualifier/grouping
+ * edges, and in-band registry declarations. Original tx timestamps are
+ * re-minted — the text format carries no transaction identity.
+ */
+export const importCommand = ingestCommand('import')
+
+export const queryCommand = (argv: readonly string[]): Output => {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      json: { type: 'boolean' },
+      all: { type: 'boolean' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: true
+  })
+  if (values.db === undefined) {
+    return fail('cave query: --db <path> is required\n')
+  }
+  if (positionals.length === 0) {
+    return fail('cave query: a pattern is required (spec §12.1)\n')
+  }
+  const pattern = positionals.join('\n')
+  const store = open(values.db, values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  try {
+    const matches = caveQuery(store, pattern, { all: values.all === true })
+    if (values.json === true) {
+      return ok(`${JSON.stringify(matches, undefined, 2)}\n`)
+    }
+    if (matches.length === 0) {
+      return ok('no matches\n')
+    }
+    const lines = matches.map(match => {
+      const bindings = Object.entries(match.bindings)
+        .map(([name, value]) => `?${name} = ${value}`)
+        .join('  ')
+      // A fully bound pattern has no bindings to print; transitive matches
+      // additionally carry no row — confirm with the pattern itself.
+      return bindings !== '' ? bindings : match.row?.raw_line ?? pattern.split('\n')[0]!
+    })
+    return ok(`${lines.join('\n')}\n`)
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  } finally {
+    store.close()
+  }
+}
+
+export const exportCommand = (argv: readonly string[]): Output => {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      current: { type: 'boolean' },
+      out: { type: 'string' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: false
+  })
+  if (values.db === undefined) {
+    return fail('cave export: --db <path> is required\n')
+  }
+  const store = open(values.db, values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  try {
+    const text = store.exportText({ current: values.current === true })
+    if (values.out === undefined) {
+      return ok(text)
+    }
+    writeFileSync(values.out, text)
+    const claims = text === '' ? 0 : text.trimEnd().split('\n').length
+    return ok(`exported ${claims} claim(s) to ${values.out}\n`)
+  } finally {
+    store.close()
+  }
+}
+
+export const demoCommand = (): Output =>
+  ok(`${Demo.run().lines.join('\n')}\n`)
+
+/** Dispatches one invocation. */
+export const cave = (argv: readonly string[]): Output => {
+  const [command, ...rest] = argv
+  try {
+    switch (command) {
+      case 'parse':
+        return parseCommand(rest)
+      case 'add':
+        return addCommand(rest)
+      case 'import':
+        return importCommand(rest)
+      case 'query':
+      case 'q':
+        return queryCommand(rest)
+      case 'export':
+        return exportCommand(rest)
+      case 'demo':
+        return demoCommand()
+      case undefined:
+      case 'help':
+      case '--help':
+      case '-h':
+        return ok(`${usage}\n`)
+      default:
+        return fail(`cave: unknown command ${JSON.stringify(command)}\n\n${usage}\n`, 2)
+    }
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * `@cavelang/cli` — the `cave` command (parse / add / query / export / demo).
+ * Programmatic access to the same implementations lives here.
+ */
+
+export { addCommand, cave, demoCommand, exportCommand, importCommand, parseCommand, queryCommand, usage } from './cli.ts'
+export type { Output } from './cli.ts'

package/src/main.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/** `cave` binary entry point — see `cli.ts` for the command implementations. */
+
+import { cave } from './cli.ts'
+
+const argv = process.argv.slice(2)
+if (argv[0] === 'mcp') {
+  // Long-running: serves MCP on stdio until the client disconnects.
+  const { runMcp } = await import('@cavelang/mcp')
+  process.exitCode = await runMcp(argv.slice(1))
+} else if (argv[0] === 'ingest') {
+  // Long-running: drives an LLM agent over batches of files.
+  const { runIngest } = await import('@cavelang/ingest')
+  process.exitCode = await runIngest(argv.slice(1))
+} else {
+  const { code, out, err } = cave(argv)
+  if (out !== '') {
+    process.stdout.write(out)
+  }
+  if (err !== '') {
+    process.stderr.write(err)
+  }
+  process.exitCode = code
+}