@cavelang/cli 0.4.0 → 0.12.0

package/src/cli.ts

@@ -6,9 +6,13 @@
  * Commands:
  *
  * - `cave parse [file]` — lint / dump the AST (`--json`)
- * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`)
- * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`)
+ * - `cave highlight [file]` — ANSI syntax colors (async, routed in `main.ts`)
+ * - `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 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
@@ -24,6 +28,10 @@ import { parseDocument } from '@cavelang/parser'
 import { Registry, standardRegistry } from '@cavelang/canonical'
 import { defaultDbPath, open } from '@cavelang/store'
 import { query as caveQuery } from '@cavelang/query'
+import { check as caveCheck, defaultStaleDays, gatedIngest } from '@cavelang/shape'
+import type { Report, Violation } from '@cavelang/shape'
+import { declareRules, defaultMaxPasses, defaultMinConf, derive, listRules, retractRule } from '@cavelang/rules'
+import type { Declaration, DeriveReport } from '@cavelang/rules'
 import { Demo } from '@cavelang/loop'
 
 export type Output = {
@@ -42,12 +50,16 @@ export const usage = `cave — Compressed Atomic Verb Expressions
 
 Usage:
   cave parse [file...] [--json]            lint CAVE text (stdin when no file)
-  cave add [--db <path>] [file...]         ingest into a store [--strict] [--no-prelude]
-  cave import [--db <path>] [file...]      restore/merge from CAVE text (same as add)
-  cave query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--no-prelude]
+  cave highlight [file...]                 print CAVE text with ANSI syntax colors
+  cave add [--db <path>] [file...]         ingest into a store [--strict] [--check] [--no-prelude] [--no-src]
+  cave import [--db <path>] [file...]      restore/merge from CAVE text (add without @src: stamping)
+  cave query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--aliases] [--as-of <t>] [--no-prelude]
+  cave derive [--db <path>] [rules.cave..] declare + fire rules (spec §24) [--dry-run] [--full] [--list] [--retract <rule>]
+  cave check [--db <path>]                 knowledge health report (spec §20) [--stale <days>] [--json]
   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 [--db <path>] <globs/urls..> LLM-driven ingestion of files and web pages
+  cave connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec §23)
   cave demo                                run the cave-loop reconstruction demo
   cave version                             print the cave version
   cave help [command]                      this text, or one command's options and examples
@@ -76,24 +88,46 @@ Examples:
   echo 'auth USES jwt @ 90%' | cave parse
   cave parse notes.cave --json | jq '.lines[0]'`,
 
+  highlight: `cave highlight — print CAVE text with ANSI syntax colors
+
+Usage:
+  cave highlight [file...]
+
+Reads stdin when no file (or \`-\`) is given. Colors come from the
+tree-sitter grammar's highlight query (@cavelang/tree-sitter-cave), the
+same source editors use. Output always carries ANSI codes — pipe through
+\`less -R\` to page. \`cave export\` colors its output the same way when
+stdout is a terminal (disable with NO_COLOR).
+
+Examples:
+  cave highlight notes.cave
+  echo 'auth USES jwt @ 90%' | cave highlight
+  cave highlight notes.cave | less -R`,
+
   add: `cave add — ingest CAVE text into a knowledge database
 
 Usage:
-  cave add [--db <path>] [file...] [--strict] [--no-prelude]
+  cave add [--db <path>] [file...] [--strict] [--check] [--no-prelude] [--no-src]
 
 Options:
   ${dbHelp}
   --strict       reject the whole ingest on any problem
+  --check        shape gate (spec §20.3): roll the append back if it
+                 introduces new expectation violations
   --no-prelude   open the store without the standard verb registry
+  --no-src       do not stamp actor provenance on appended claims
 
-Reads stdin when no file (or \`-\`) is given.
+Reads stdin when no file (or \`-\`) is given. Claims that carry no @src:
+context are stamped @src:cli (spec §9.5); use \`cave import\` to replay
+exported text without stamping.
 
 Examples:
   cave add --db k.db notes.cave
   echo 'auth USES jwt @ 90%' | cave add
-  cave add --db k.db --strict reviewed.cave`,
+  cave add --db k.db --strict reviewed.cave
+  cave add --db k.db --check new-services.cave`,
 
-  import: `cave import — restore/merge a database from CAVE text (same as add)
+  import: `cave import — restore/merge a database from CAVE text (add without @src: stamping)
 
 Usage:
   cave import [--db <path>] [file...] [--strict] [--no-prelude]
@@ -105,7 +139,9 @@ Options:
 
 Canonical CAVE text is the interchange format (spec §2.2): importing a
 file written by \`cave export\` replays its claims append-only, preserving
-the belief series, qualifier edges and in-band declarations.
+the belief series, qualifier edges and in-band declarations. Unlike
+\`cave add\`, import never stamps actor provenance — replayed claims must
+keep the claim keys they were exported with (spec §9.5).
 
 Examples:
   cave export --db old.db --out backup.cave
@@ -114,12 +150,16 @@ Examples:
   query: `cave query — run a CAVE-Q pattern against a store
 
 Usage:
-  cave query [--db <path>] <pattern> [WHERE <filter>] [--json] [--all] [--no-prelude]
+  cave query [--db <path>] <pattern> [WHERE <filter>] [--json] [--all] [--aliases] [--as-of <t>] [--no-prelude]
 
 Options:
   ${dbHelp}
   --json         emit matches as JSON
   --all          match all beliefs, not just current ones
+  --aliases      resolve entities through current ALIAS claims (spec §13.6)
+  --as-of <t>    resolve beliefs as of a past moment (spec §12.3): a date
+                 (whole day included), a timestamp (whole second), or a
+                 transaction id — rows recorded later are invisible
   --no-prelude   open the store without the standard verb registry
 
 Patterns are claim triples with ?variables and optional metadata filters
@@ -131,8 +171,71 @@ Examples:
   cave query --db k.db '?x HAS bug: ?bug #security'
   cave query --db k.db '?cause CAUSE app/crash' 'WHERE conf >= 0.5'
   cave query --db k.db 'terrier EXTENDS+ animal'
+  cave query --db k.db '?x USES postgres' --aliases
+  cave query --db k.db 'server IS compromised' --as-of 2026-01-15
   cave query --db k.db '?x ?verb ?y @production' --json`,
 
+  derive: `cave derive — declare and fire rules (spec §24)
+
+Usage:
+  cave derive [--db <path>] [rules.cave...] [--dry-run] [--full] [--aliases]
+              [--min-conf <p>] [--max-passes <n>] [--json] [--no-prelude]
+  cave derive [--db <path>] --list
+  cave derive [--db <path>] --retract <digest|subject>
+
+Options:
+  ${dbHelp}
+  --dry-run      compute and report inside a rolled-back transaction
+  --full         ignore stored watermarks — re-fire every rule (spec §24.4)
+  --aliases      premises match through the alias closure (spec §13.6)
+  --min-conf <p> do not assert conclusions below this confidence
+                 (0..1 or N%, default ${defaultMinConf})
+  --max-passes <n> fixpoint guard (default ${defaultMaxPasses})
+  --list         print the store's current rules and exit
+  --retract <r>  retract a rule (digest, unambiguous prefix, or subject)
+                 together with everything it derived, and exit
+  --json         emit the report as JSON
+  --no-prelude   open the store without the standard verb registry
+
+Rule files are CAVE documents whose \`premises => conclusion\` lines are
+rules (spec §24.1); other lines — verb declarations the rules need — are
+prelude, ingested first. Rules are stored in-band as
+\`rule/<digest> HAS rule: \\\`…\\\`\` claims, so \`cave derive\` with no file
+fires whatever the store already knows. Derived claims are stamped
+@src:rule/<digest>, carry BECAUSE edges to their premise rows and a VIA
+edge to the rule, and update append-only: re-runs are idempotent and
+watermark-incremental, and conclusions whose premises no longer hold are
+retracted (spec §24.2–§24.5).
+
+Examples:
+  cave derive --db k.db rules.cave
+  cave derive --db k.db
+  echo '?x NEEDS ?y, ?y NEEDS ?z => ?x NEEDS ?z' | cave derive --db k.db -
+  cave derive --db k.db --dry-run --json
+  cave derive --db k.db --list
+  cave derive --db k.db --retract 4a0bb974f43c`,
+
+  check: `cave check — knowledge health report (spec §20)
+
+Usage:
+  cave check [--db <path>] [--stale <days>] [--json] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --stale <days> staleness horizon (default: ${defaultStaleDays})
+  --json         emit the full report as JSON
+  --no-prelude   open the store without the standard verb registry
+
+Reads the store against its own in-band EXPECTS declarations (spec §20.1)
+and reports shape violations, stale current beliefs, review candidates
+(conf 0.3–0.7), alias disagreements (spec §13.6) and coverage stats.
+Exits 1 when violations exist; everything else is advisory.
+
+Examples:
+  cave check --db k.db
+  cave check --db k.db --stale 30
+  cave check --db k.db --json | jq '.violations'`,
+
   export: `cave export — emit canonical CAVE text from a store
 
 Usage:
@@ -195,26 +298,63 @@ export const parseCommand = (argv: readonly string[]): Output => {
   return { code: 1, out: `${summary}\n`, err: `${problems}\n` }
 }
 
-const ingestCommand = (name: string) => (argv: readonly string[]): Output => {
+/**
+ * `cave highlight` — ANSI syntax colors from the tree-sitter grammar's own
+ * highlight query. Async (the grammar WASM loads on first use), so `main.ts`
+ * routes it separately, like `mcp` and `ingest`.
+ */
+export const highlightCommand = async (argv: readonly string[]): Promise<Output> => {
+  const { positionals } = parseArgs({ args: [...argv], options: {}, allowPositionals: true })
+  const input = readInput(positionals)
+  const { highlighter } = await import('@cavelang/highlight')
+  const { ansi } = await highlighter()
+  return ok(ansi(input))
+}
+
+/**
+ * Shared by `add` and `import`; the difference is actor provenance
+ * (spec §9.5). `add` records knowledge authored now, so claims without a
+ * `@src:` context are stamped `@src:cli` (`--no-src` opts out); `import`
+ * replays interchange text, which must preserve claim keys as exported,
+ * so it never stamps.
+ */
+const formatViolation = (violation: Violation): string =>
+  `${violation.entity} missing ${violation.expectation.kind} ${violation.expectation.name} ` +
+  `(${violation.entity} IS ${violation.via}; ${violation.expectation.type} EXPECTS ${violation.expectation.name})`
+
+const ingestCommand = (name: 'add' | 'import') => (argv: readonly string[]): Output => {
   const { values, positionals } = parseArgs({
     args: [...argv],
     options: {
       db: { type: 'string' },
       strict: { type: 'boolean' },
-      'no-prelude': { type: 'boolean' }
+      'no-prelude': { type: 'boolean' },
+      ...name === 'add' ? { 'no-src': { type: 'boolean' }, check: { type: 'boolean' } } : {}
     },
     allowPositionals: true
   })
   const input = readInput(positionals)
   const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
   try {
-    const result = store.ingest(input, { strict: values.strict === true })
-    const problems = result.problems
+    const options = {
+      strict: values.strict === true,
+      ...name === 'add' && values['no-src'] !== true ? { source: 'cli' } : {}
+    }
+    // The shape gate (spec §20.3): append + check in one transaction,
+    // rolled back when the append introduces new expectation violations.
+    const outcome = name === 'add' && values.check === true ?
+      gatedIngest(store, input, options) :
+      { ok: true as const, result: store.ingest(input, options) }
+    if (!outcome.ok) {
+      const detail = outcome.violations.map(violation => `  ${formatViolation(violation)}`).join('\n')
+      return fail(`rejected: ${outcome.violations.length} new violation(s), nothing added (spec §20.3)\n${detail}\n`)
+    }
+    const problems = outcome.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`,
+      out: `added ${outcome.result.ids.length} claim(s), ${outcome.result.edges} edge(s)\n`,
       err: problems === '' ? '' : `${problems}\n`
     }
   } catch (error) {
@@ -228,13 +368,15 @@ 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
+ * `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 const importCommand = ingestCommand('import')
 
@@ -245,6 +387,8 @@ export const queryCommand = (argv: readonly string[]): Output => {
       db: { type: 'string' },
       json: { type: 'boolean' },
       all: { type: 'boolean' },
+      aliases: { type: 'boolean' },
+      'as-of': { type: 'string' },
       'no-prelude': { type: 'boolean' }
     },
     allowPositionals: true
@@ -255,7 +399,11 @@ export const queryCommand = (argv: readonly string[]): Output => {
   const pattern = positionals.join('\n')
   const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
   try {
-    const matches = caveQuery(store, pattern, { all: values.all === true })
+    const matches = caveQuery(store, pattern, {
+      all: values.all === true,
+      aliases: values.aliases === true,
+      ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] }
+    })
     if (values.json === true) {
       return ok(`${JSON.stringify(matches, undefined, 2)}\n`)
     }
@@ -278,6 +426,189 @@ export const queryCommand = (argv: readonly string[]): Output => {
   }
 }
 
+export const deriveCommand = (argv: readonly string[]): Output => {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+      full: { type: 'boolean' },
+      aliases: { type: 'boolean' },
+      'min-conf': { type: 'string' },
+      'max-passes': { type: 'string' },
+      list: { type: 'boolean' },
+      retract: { type: 'string' },
+      json: { type: 'boolean' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: true
+  })
+  const minConf = values['min-conf'] === undefined ?
+    undefined :
+    values['min-conf'].endsWith('%') ? Number(values['min-conf'].slice(0, -1)) / 100 : Number(values['min-conf'])
+  if (minConf !== undefined && (!Number.isFinite(minConf) || minConf < 0 || minConf > 1)) {
+    return fail(`cave derive: --min-conf expects a confidence in 0..1 or N%, got ${JSON.stringify(values['min-conf'])}\n`)
+  }
+  const maxPasses = values['max-passes'] === undefined ? undefined : Number(values['max-passes'])
+  if (maxPasses !== undefined && (!Number.isInteger(maxPasses) || maxPasses < 1)) {
+    return fail(`cave derive: --max-passes expects a positive integer, got ${JSON.stringify(values['max-passes'])}\n`)
+  }
+  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  try {
+    if (values.list === true) {
+      const rules = listRules(store)
+      if (values.json === true) {
+        return ok(`${JSON.stringify(rules, undefined, 2)}\n`)
+      }
+      if (rules.length === 0) {
+        return ok('no rules\n')
+      }
+      const lines = rules.map(rule =>
+        `${rule.subject} \`${rule.text}\`${rule.label === undefined ? '' : ` ; ${rule.label}`}` +
+        (rule.ok ? '' : `\n  problems: ${rule.problems.join('; ')}`))
+      return ok(`${lines.join('\n')}\n`)
+    }
+    if (values.retract !== undefined) {
+      const outcome = retractRule(store, values.retract)
+      if (!outcome.ok) {
+        return fail(`cave derive: ${outcome.error}\n`)
+      }
+      return ok(`retracted ${outcome.subjects.join(', ')} and ${outcome.derived} derived claim(s)\n`)
+    }
+
+    const err: string[] = []
+    const out: string[] = []
+    // Unlike parse/add, no positional means "fire the stored rules", never
+    // stdin — pass `-` to read a rule file from stdin explicitly.
+    const input = positionals.length > 0 ? readInput(positionals) : undefined
+    const options = {
+      full: values.full === true,
+      aliases: values.aliases === true,
+      ...minConf === undefined ? {} : { minConf },
+      ...maxPasses === undefined ? {} : { maxPasses }
+    }
+    let declaration: undefined | Declaration
+    let report: DeriveReport
+    if (values['dry-run'] === true) {
+      // A dry run persists nothing — rule declarations from the file
+      // included, so declare + fire share one rolled-back transaction.
+      const rolledBack = Symbol('cave derive --dry-run')
+      let outcome: undefined | { declaration?: Declaration, report: DeriveReport }
+      try {
+        store.transaction(() => {
+          outcome = {
+            ...input === undefined ? {} : { declaration: declareRules(store, input) },
+            report: derive(store, options)
+          }
+          throw rolledBack
+        })
+      } catch (error) {
+        if (error !== rolledBack) {
+          throw error
+        }
+      }
+      declaration = outcome!.declaration
+      report = outcome!.report
+    } else {
+      declaration = input === undefined ? undefined : declareRules(store, input)
+      report = derive(store, options)
+    }
+    if (declaration !== undefined) {
+      err.push(...declaration.problems.map(problem => `rules line ${problem.line}: ${problem.message}`))
+      out.push(`declared ${declaration.declared} rule(s)` +
+        (declaration.unchanged > 0 ? `, ${declaration.unchanged} unchanged` : '') +
+        (declaration.prelude > 0 ? `, +${declaration.prelude} prelude claim(s)` : ''))
+    }
+    if (values.json === true) {
+      return { code: report.problems.length > 0 ? 1 : 0, out: `${JSON.stringify(report, undefined, 2)}\n`, err: err.join('\n') + (err.length > 0 ? '\n' : '') }
+    }
+    for (const problem of report.problems) {
+      err.push(`${problem.subject}: ${problem.problems.join('; ')}`)
+    }
+    for (const rule of report.rules) {
+      const state = rule.fired ?
+        `${rule.solutions} solution(s), +${rule.appended} appended, ${rule.updated} updated, ${rule.retracted} retracted, ${rule.unchanged} unchanged` :
+        'unchanged premises, skipped'
+      out.push(`${rule.subject}: ${state}${rule.label === undefined ? '' : ` ; ${rule.label}`}`)
+      err.push(...rule.problems.map(problem => `${rule.subject}: ${problem}`))
+    }
+    out.push(...report.notes.map(note => `note: ${note}`))
+    out.push(
+      `derived${values['dry-run'] === true ? ' (dry run)' : ''}: ` +
+      `+${report.appended} appended, ${report.updated} updated, ${report.retracted} retracted, ` +
+      `${report.unchanged} unchanged (${report.passes} pass(es))`)
+    const hasProblems = report.problems.length > 0 || report.rules.some(rule => rule.problems.length > 0)
+    return { code: hasProblems ? 1 : 0, out: `${out.join('\n')}\n`, err: err.length === 0 ? '' : `${err.join('\n')}\n` }
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  } finally {
+    store.close()
+  }
+}
+
+/** Text rendering of the §20.2 report: always shape + coverage, non-empty advisory sections. */
+const renderReport = (report: Report, staleDays: number): string => {
+  const lines: string[] = []
+  const { coverage } = report
+  lines.push(`shape: ${coverage.expectations} expectation(s), ${coverage.instances} instance(s), ${coverage.satisfied}/${coverage.checks} satisfied`)
+  if (report.violations.length > 0) {
+    lines.push(`violations (${report.violations.length}):`)
+    lines.push(...report.violations.map(violation => `  ${formatViolation(violation)}`))
+  }
+  if (report.stale.length > 0) {
+    lines.push(`stale (${report.stale.length}, older than ${staleDays} day(s)):`)
+    lines.push(...report.stale.map(({ row, ageDays }) => `  ${row.raw_line} (${ageDays}d)`))
+  }
+  if (report.review.length > 0) {
+    lines.push(`review candidates (${report.review.length}, conf 0.3-0.7):`)
+    lines.push(...report.review.map(row => `  ${row.raw_line}`))
+  }
+  if (report.disagreements.length > 0) {
+    lines.push(`alias disagreements (${report.disagreements.length}):`)
+    for (const disagreement of report.disagreements) {
+      lines.push(`  ${disagreement.about} across ${disagreement.entities.join(', ')}:`)
+      lines.push(...disagreement.rows.map(row => `    ${row.raw_line}`))
+    }
+  }
+  const confidence = coverage.averageConfidence === null ?
+    '' :
+    `; avg conf ${Math.round(coverage.averageConfidence * 100)}%, ${coverage.lowConfidence} low (< 0.3)`
+  lines.push(
+    `coverage: ${coverage.rows} row(s), ${coverage.facts} fact(s) — ` +
+    `${coverage.current} current, ${coverage.retracted} retracted, ${coverage.negated} negated` +
+    `${confidence}; ${coverage.entities} entities, ${coverage.typedEntities} typed`
+  )
+  return `${lines.join('\n')}\n`
+}
+
+export const checkCommand = (argv: readonly string[]): Output => {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      stale: { type: 'string' },
+      json: { type: 'boolean' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: false
+  })
+  const staleDays = values.stale === undefined ? defaultStaleDays : Number(values.stale)
+  if (!Number.isFinite(staleDays) || staleDays < 0) {
+    return fail(`cave check: --stale expects a non-negative number of days, got ${JSON.stringify(values.stale)}\n`)
+  }
+  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  try {
+    const report = caveCheck(store, { staleDays })
+    const out = values.json === true ?
+      `${JSON.stringify(report, undefined, 2)}\n` :
+      renderReport(report, staleDays)
+    // Violations fail the check (spec §20.2); the other sections are advisory.
+    return { code: report.violations.length > 0 ? 1 : 0, out, err: '' }
+  } finally {
+    store.close()
+  }
+}
+
 export const exportCommand = (argv: readonly string[]): Output => {
   const { values } = parseArgs({
     args: [...argv],
@@ -319,8 +650,8 @@ export const helpCommand = (argv: readonly string[]): Output => {
   if (text !== undefined) {
     return ok(`${text}\n`)
   }
-  // mcp and ingest own their help (main.ts forwards `help X` to `X --help`).
-  if (topic === 'mcp' || topic === 'ingest') {
+  // mcp, ingest and connect own their help (main.ts forwards `help X` to `X --help`).
+  if (topic === 'mcp' || topic === 'ingest' || topic === 'connect') {
     return ok(`see: cave ${topic} --help\n`)
   }
   return fail(`cave help: unknown command ${JSON.stringify(topic)}\n\n${usage}\n`, 2)
@@ -344,6 +675,10 @@ export const cave = (argv: readonly string[]): Output => {
         return importCommand(rest)
       case 'query':
         return queryCommand(rest)
+      case 'derive':
+        return deriveCommand(rest)
+      case 'check':
+        return checkCommand(rest)
       case 'export':
         return exportCommand(rest)
       case 'demo':

package/src/index.ts

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

package/src/main.ts

@@ -1,11 +1,21 @@
 #!/usr/bin/env node
 /** `cave` binary entry point — see `cli.ts` for the command implementations. */
 
-import { cave } from './cli.ts'
+import { cave, highlightCommand } from './cli.ts'
 
-// mcp and ingest own their help text, so `cave help X` becomes `cave X --help`.
+const write = (code: number, out: string, err: string): void => {
+  if (out !== '') {
+    process.stdout.write(out)
+  }
+  if (err !== '') {
+    process.stderr.write(err)
+  }
+  process.exitCode = code
+}
+
+// mcp, ingest and connect own their help text, so `cave help X` becomes `cave X --help`.
 const raw = process.argv.slice(2)
-const argv = raw[0] === 'help' && (raw[1] === 'mcp' || raw[1] === 'ingest') ?
+const argv = raw[0] === 'help' && (raw[1] === 'mcp' || raw[1] === 'ingest' || raw[1] === 'connect') ?
   [raw[1], '--help'] :
   raw
 if (argv[0] === 'mcp') {
@@ -16,13 +26,24 @@ if (argv[0] === 'mcp') {
   // Long-running: drives an LLM agent over batches of files.
   const { runIngest } = await import('@cavelang/ingest')
   process.exitCode = await runIngest(argv.slice(1))
+} else if (argv[0] === 'connect') {
+  // Async (URL sources fetch) and potentially long-running (--watch).
+  const { runConnect } = await import('@cavelang/connect')
+  process.exitCode = await runConnect(argv.slice(1))
+} else if (argv[0] === 'highlight' && !argv.includes('--help') && !argv.includes('-h')) {
+  // Async (grammar WASM loads on first use); --help stays on the sync path.
+  const { code, out, err } = await highlightCommand(argv.slice(1))
+  write(code, out, err)
 } else {
   const { code, out, err } = cave(argv)
-  if (out !== '') {
-    process.stdout.write(out)
+  // Canonical CAVE text going to a terminal gets syntax colors from the same
+  // grammar query `cave highlight` uses; piping or NO_COLOR keeps bytes clean.
+  const colorize = code === 0 && argv[0] === 'export' && !argv.includes('--out') &&
+    out !== '' && process.stdout.isTTY === true && process.env['NO_COLOR'] === undefined
+  if (colorize) {
+    const { highlighter } = await import('@cavelang/highlight')
+    write(code, (await highlighter()).ansi(out), err)
+  } else {
+    write(code, out, err)
   }
-  if (err !== '') {
-    process.stderr.write(err)
-  }
-  process.exitCode = code
 }

package/License.md

@@ -1,6 +0,0 @@
-# CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
-
-To the extent possible under law, the authors listed in [Authors.md](./Authors.md) have waived all copyright and related or neighboring rights to this software and associated documentation files (the "Software").
-
-For more information, please see:
-https://creativecommons.org/publicdomain/zero/1.0/