@cavelang/cli 0.5.0 → 0.13.0

package/README.md

@@ -28,11 +28,12 @@ Every command answers `--help` with its options and examples (also
 | Command | Flags | Behavior |
 |---|---|---|
 | `parse [file…]` | `--json` | Lint (stdin by default). Exit 1 when diagnostics exist; `--json` dumps the AST document. |
-| `add [--db p] [file…]` | `--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 [--db p] [file…]` | `--strict`, `--no-prelude` | Restore/merge a database from CAVE text — same operation as `add`, because canonical text *is* the interchange format. |
+| `add [--db p] [file…]` | `--strict`, `--check`, `--no-prelude`, `--no-src` | Ingest. Lenient by default (problems on stderr, valid lines land); `--strict` rolls back on any problem; `--check` is the shape gate (spec §20.3) — the append rolls back if it introduces new expectation violations; `--no-prelude` starts from an empty registry instead of the standard §5.5 pairs. Claims without a `@src:` context are stamped `@src:cli` (spec §9.5); `--no-src` opts out. |
+| `import [--db p] [file…]` | `--strict`, `--no-prelude` | Restore/merge a database from CAVE text — `add` minus provenance stamping, because canonical text *is* the interchange format and replayed claims must keep their exported claim keys (spec §9.5). |
 | `query [--db p] <pattern…>` | `--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`. |
+| `check [--db p]` | `--stale <days>`, `--json`, `--no-prelude` | Knowledge health report (spec §20, see [`@cavelang/shape`](../shape)): shape violations against in-band `EXPECTS` declarations, stale current beliefs (default horizon 90 days), review candidates (conf 0.3–0.7), alias disagreements, coverage stats. Exit 1 on violations; everything else is advisory. |
 | `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. |
+| `mcp [--db p]` | `--read-only`, `--tools <list>`, `--no-prelude`, `--src <ctx>`, `--no-src` | 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. `--read-only` / `--tools <list>` narrow the served tool surface (the agent permission boundary), composing by intersection. Appends are stamped `@src:agent/<client-name>` (spec §9.5); `--src` replaces the stamp, `--no-src` disables it. |
 | `ingest [--db p] <globs/urls…>` | see `cave ingest --help` | LLM-driven ingestion of files and web pages (fetched and readability-extracted) 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). |
 | `version` | | Print the cave version. |

package/dist/src/cli.d.ts

@@ -7,9 +7,13 @@
  *
  * - `cave parse [file]` — lint / dump the AST (`--json`)
  * - `cave highlight [file]` — ANSI syntax colors (async, routed in `main.ts`)
- * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`)
- * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`)
+ * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`, `--check`)
+ * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`, `--aliases`, `--as-of`)
+ * - `cave derive [--db <path>] [rules.cave…]` — fire rules (`--dry-run`, `--full`, `--list`, `--retract`)
+ * - `cave act [--db <path>] <name> [param=value…]` — execute an action (spec §25; `--declare`, `--list`, `--retract`)
+ * - `cave check [--db <path>]` — knowledge health report (`--stale`, `--json`)
  * - `cave export [--db <path>]` — canonical text out (`--current`)
+ * - `cave connect [--db <path>] <source>` — deterministic structured ingestion (async, routed in `main.ts`)
  * - `cave demo` — the cave-loop multi-hop recovery demo
  * - `cave version` — print the cave version
  * - `cave help [command]` — overview, or one command's help
@@ -22,7 +26,7 @@ export type Output = {
     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 highlight [file...]                 print CAVE text with ANSI syntax colors\n  cave add [--db <path>] [file...]         ingest into a store [--strict] [--no-prelude]\n  cave import [--db <path>] [file...]      restore/merge from CAVE text (same as add)\n  cave query [--db <path>] <pattern>       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 [--db <path>] <globs/urls..> LLM-driven ingestion of files and web pages\n  cave demo                                run the cave-loop reconstruction demo\n  cave version                             print the cave version\n  cave help [command]                      this text, or one command's options and examples\n\nEvery command answers --help. --db defaults to $CAVE_DB, or cave.db in\nthe current directory. The spec lives in the .claude/skills/ directory at\nthe repository root (section index in README.md).";
+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 highlight [file...]                 print CAVE text with ANSI syntax colors\n  cave add [--db <path>] [file...]         ingest into a store [--strict] [--check] [--no-prelude] [--no-src]\n  cave import [--db <path>] [file...]      restore/merge from CAVE text (add without @src: stamping)\n  cave query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--aliases] [--as-of <t>] [--no-prelude]\n  cave derive [--db <path>] [rules.cave..] declare + fire rules (spec \u00A724) [--dry-run] [--full] [--list] [--retract <rule>]\n  cave act [--db <path>] <name> [p=v...]   execute an action (spec \u00A725) [--dry-run] [--no-check] [--hooks <file>]\n  cave act --declare [file...]             declare actions from a CAVE document; --list / --retract <name> manage them\n  cave check [--db <path>]                 knowledge health report (spec \u00A720) [--stale <days>] [--json]\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 [--db <path>] <globs/urls..> LLM-driven ingestion of files and web pages\n  cave connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec \u00A723)\n  cave demo                                run the cave-loop reconstruction demo\n  cave version                             print the cave version\n  cave help [command]                      this text, or one command's options and examples\n\nEvery command answers --help. --db defaults to $CAVE_DB, or cave.db in\nthe current directory. The spec lives in the .claude/skills/ directory at\nthe repository root (section index in README.md).";
 /** Per-command help, printed for \`cave <command> --help\` and \`cave help <command>\`. */
 export declare const commandHelp: Record<string, string>;
 export declare const parseCommand: (argv: readonly string[]) => Output;
@@ -35,16 +39,21 @@ export declare const highlightCommand: (argv: readonly string[]) => Promise<Outp
 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
+ * `add` minus provenance stamping: 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.
+ * replays its claims append-only — and because contexts are part of claim
+ * identity, replay must not add a `@src:` stamp (spec §9.5). 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 deriveCommand: (argv: readonly string[]) => Output;
+export declare const actCommand: (argv: readonly string[]) => Output;
+export declare const checkCommand: (argv: readonly string[]) => Output;
 export declare const exportCommand: (argv: readonly string[]) => Output;
 export declare const demoCommand: () => Output;
 export declare const versionCommand: () => Output;

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,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,2sCAiBgC,CAAA;AAIlD,2FAA2F;AAC3F,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsH9C,CAAA;AAOD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAyBtD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CAM9E,CAAA;AA+BD,eAAO,MAAM,UAAU,SA7BwB,SAAS,MAAM,EAAE,KAAG,MA6BrB,CAAA;AAE9C;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,SAzCqB,SAAS,MAAM,EAAE,KAAG,MAyCf,CAAA;AAEpD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsCtD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAuBvD,CAAA;AAED,eAAO,MAAM,WAAW,QAAO,MACS,CAAA;AAExC,eAAO,MAAM,cAAc,QAAO,MACJ,CAAA;AAE9B,wEAAwE;AACxE,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAcrD,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,IAAI,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAqC9C,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAiBH,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,61DAsBgC,CAAA;AAIlD,2FAA2F;AAC3F,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiP9C,CAAA;AAOD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAyBtD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CAM9E,CAAA;AAuDD,eAAO,MAAM,UAAU,SA1CkC,SAAS,MAAM,EAAE,KAAG,MA0C/B,CAAA;AAE9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,SAxD+B,SAAS,MAAM,EAAE,KAAG,MAwDzB,CAAA;AAEpD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA4CtD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsHvD,CAAA;AA8CD,eAAO,MAAM,UAAU,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsFpD,CAAA;AAqCD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA0BtD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAuBvD,CAAA;AAED,eAAO,MAAM,WAAW,QAAO,MACS,CAAA;AAExC,eAAO,MAAM,cAAc,QAAO,MACJ,CAAA;AAE9B,wEAAwE;AACxE,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAcrD,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,IAAI,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA2C9C,CAAA"}