@cavelang/cli 0.15.0 → 0.20.0

package/src/cli.ts

@@ -8,11 +8,14 @@
  * - `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`, `--check`)
- * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`, `--aliases`, `--as-of`)
+ * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`, `--aliases`, `--as-of`, `--resolve`)
+ * - `cave resolve [--db <path>]` — contested facts under the §26 policy (`--aliases`, `--policy`, `--json`)
  * - `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 suggest-alias [--db <path>]` — same-entity candidates (spec §27; async, routed in `main.ts`)
+ * - `cave sync [--db <path>] <source>` — merge another store by row identity (spec §28; `--dry-run`, `--as`, `--into`)
+ * - `cave export [--db <path>]` — canonical text out (`--current`, `--tx`)
  * - `cave connect [--db <path>] <source>` — deterministic structured ingestion (async, routed in `main.ts`)
  * - `cave eval <suite...>` — golden-fixture extraction/query/reconstruction evals (async, routed in `main.ts`)
  * - `cave reconstruct [--db <path>] <seed...>` — §18 reconstruction from seed cues (async, routed in `main.ts`)
@@ -31,7 +34,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 {
+  check as caveCheck, defaultMinScore, defaultStaleDays, gatedIngest, judgePrompt, parseJudgeReply,
+  suggestAliases, writeSuggestions
+} 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'
@@ -40,7 +46,9 @@ import type { ActReport } from '@cavelang/act'
 import {
   Demo, heuristicPolicy, llmPolicy, reconstruct, reconstructAsync, shellComplete, sqliteStore
 } from '@cavelang/loop'
-import { emitClaim } from '@cavelang/canonical'
+import { labelOf, sanitizeLabel, syncFile, syncText } from '@cavelang/sync'
+import type { SyncReport } from '@cavelang/sync'
+import { emitClaim, txOfLine } from '@cavelang/canonical'
 
 export type Output = {
   readonly code: number
@@ -61,12 +69,15 @@ Usage:
   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 query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--aliases] [--as-of <t>] [--resolve] [--no-prelude]
+  cave resolve [--db <path>]               contested facts + winners (spec §26) [--aliases] [--policy] [--json]
   cave derive [--db <path>] [rules.cave..] declare + fire rules (spec §24) [--dry-run] [--full] [--list] [--retract <rule>]
   cave act [--db <path>] <name> [p=v...]   execute an action (spec §25) [--dry-run] [--no-check] [--hooks <file>]
   cave act --declare [file...]             declare actions from a CAVE document; --list / --retract <name> manage them
   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 suggest-alias [--db <path>]         propose same-entity ALIAS candidates (spec §27) [--min <s>] [--agent] [--write]
+  cave sync [--db <path>] <source>         merge another store by row identity (spec §28) [--dry-run] [--as] [--into]
+  cave export [--db <path>] [--out <file>] emit canonical CAVE text [--current] [--tx] [--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 eval <suite..> --agent '<command>'  golden-fixture extraction/query/reconstruction evals (items 9, 10)
@@ -153,7 +164,10 @@ 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. Unlike
 \`cave add\`, import never stamps actor provenance — replayed claims must
-keep the claim keys they were exported with (spec §9.5).
+keep the claim keys they were exported with (spec §9.5). Import always
+mints fresh transaction ids — ;@ annotations in a \`cave export --tx\`
+file read as ordinary comments; to merge under the recorded row
+identity, use \`cave sync\` (spec §28.4).
 
 Examples:
   cave export --db old.db --out backup.cave
@@ -162,7 +176,7 @@ Examples:
   query: `cave query — run a CAVE-Q pattern against a store
 
 Usage:
-  cave query [--db <path>] <pattern> [WHERE <filter>] [--json] [--all] [--aliases] [--as-of <t>] [--no-prelude]
+  cave query [--db <path>] <pattern> [WHERE <filter>] [--json] [--all] [--aliases] [--as-of <t>] [--resolve] [--no-prelude]
 
 Options:
   ${dbHelp}
@@ -172,6 +186,11 @@ Options:
   --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
+  --resolve      match resolved winners only (spec §26): contested facts —
+                 same fact from several sources, or opposite polarity —
+                 collapse to the row the resolution policy picks
+                 (precedence class, reliability-weighted confidence, tx);
+                 incompatible with --all
   --no-prelude   open the store without the standard verb registry
 
 Patterns are claim triples with ?variables and optional metadata filters
@@ -185,8 +204,40 @@ Examples:
   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 'service HAS owner: ?who' --resolve
   cave query --db k.db '?x ?verb ?y @production' --json`,
 
+  resolve: `cave resolve — contested facts and their winners (spec §26)
+
+Usage:
+  cave resolve [--db <path>] [--aliases] [--policy] [--json] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --aliases      widen resolution groups through current ALIAS claims
+                 (spec §13.6) — aliased names contest one fact
+  --policy       print the effective resolution policy instead: the
+                 built-in precedence ladder merged with in-band
+                 source/<name> HAS precedence: / HAS reliability: claims
+  --json         emit the report as JSON
+  --no-prelude   open the store without the standard verb registry
+
+Lists every fact more than one belief series currently speaks about —
+same fact from different sources (§9.5 actor stamps, content sources)
+or opposite polarity — with the candidates ranked as the resolution
+policy sees them: precedence class first, reliability-weighted
+confidence second, latest transaction last. The winner is what
+\`cave query --resolve\` matches; the rest are invisible there. Declare
+policy overrides in-band, e.g.:
+
+  source/scanner-a HAS reliability: 60%
+  source/ingest HAS precedence: 1
+
+Examples:
+  cave resolve --db k.db
+  cave resolve --db k.db --aliases
+  cave resolve --db k.db --policy`,
+
   derive: `cave derive — declare and fire rules (spec §24)
 
 Usage:
@@ -296,21 +347,115 @@ Examples:
   cave check --db k.db --stale 30
   cave check --db k.db --json | jq '.violations'`,
 
+  'suggest-alias': `cave suggest-alias — propose same-entity ALIAS candidates for review (spec §27)
+
+Usage:
+  cave suggest-alias [--db <path>] [options]
+
+Options:
+  ${dbHelp}
+  --min <s>            minimum evidence score, 0..1 or N% (default 60%)
+  --limit <n>          at most n suggestions, strongest first
+  --agent <template>   LLM judge filtering the candidates — the cave
+                       ingest/eval shell contract: the prompt (each pair
+                       with both sides' current claims) is piped to stdin
+                       and {prompt-file} is substituted; stdout replies
+                       with a JSON array of confirmed suggestion numbers
+  --timeout <seconds>  judge timeout (default 120)
+  --write              append the suggestions, stamped @src:suggest/alias,
+                       instead of only printing them
+  --json               print suggestions with scores and signals as JSON
+  --no-prelude         open the store without the standard verb registry
+
+Candidates come from string similarity (case/separator drift, segment
+containment, prefixes, typos) and shared rare attribute values; shared
+relations strengthen a candidate but never create one. Suggested claims
+are questions, not merges: confidence 30–50% puts them in cave check's
+review band, and a pair with any recorded ALIAS history — merged,
+rejected or unmerged — is never suggested again.
+
+Output is CAVE text: review it, edit it, pipe it into cave add — or
+--write it and review afterwards. A written suggestion is a positive
+claim, so the opt-in §13.6 closure links it until reviewed:
+
+  confirm   echo 'dupe ALIAS canonical' | cave add --db k.db
+  reject    echo 'dupe ALIAS canonical @src:suggest/alias @ 0%' | cave add --db k.db
+
+(rejection retracts the suggestion's own series — contexts are part of
+claim identity, §9.2, so a plain @ 0% append would start a new series
+and leave the suggested link standing).
+
+Examples:
+  cave suggest-alias --db k.db
+  cave suggest-alias --db k.db --min 80% --limit 10
+  cave suggest-alias --db k.db | cave add --db k.db
+  cave suggest-alias --db k.db --agent 'claude -p' --write`,
+
+  sync: `cave sync — merge another store into this one by row identity (spec §28)
+
+Usage:
+  cave sync [--db <path>] <source> [--as <label>] [--into <label>]
+            [--dry-run] [--no-record] [--json] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --as <label>   origin label in the merge record (default: the source
+                 file's basename stem; stdin defaults to "stdin")
+  --into <label> target label in the merge record (default: the database
+                 file's basename stem)
+  --dry-run      compute the full report inside a rolled-back transaction
+  --no-record    do not append the store/<from> SYNCED-INTO store/<into>
+                 merge record
+  --json         emit the report as JSON
+  --no-prelude   open the store without the standard verb registry
+
+The source is a CAVE store file (recognized by the SQLite header),
+canonical text with ;@ transaction annotations (cave export --tx), or -
+for annotated text on stdin. Rows merge by identity: a row's UUIDv7 is
+its id everywhere, so present rows skip, re-runs merge nothing, and two
+stores syncing each other converge. Contradictions coexist (spec §9.4)
+and resolve at read time (cave resolve, --resolve); everything appended
+after a merge outsorts everything merged, whatever the origin machine's
+clock read (spec §28.2). An effective merge appends one record claim,
+stamped @src:sync — the sync log is its belief series.
+
+Branching (spec §28.6): commit the full annotated export — the text is
+the store — and rebuild working stores from it. A checkout is plumbing
+(--no-record); landing reviewed text into a live store is a real merge
+event (let it record). Never hand-merge exports: sync both sides into
+a fresh store and re-export — the union — which git can run for you as
+a merge driver on *.cave files.
+
+Examples:
+  cave sync --db main.db laptop.db
+  cave sync --db main.db laptop.db --dry-run --json
+  cave export --db laptop.db --tx | cave sync --db main.db -
+  cave sync --db a.db b.db && cave sync --db b.db a.db   # converge both
+  cave sync --db work.db knowledge.cave --no-record      # checkout (§28.6)
+  cave sync --db main.db knowledge.cave --as reorg-auth  # land the branch`,
+
   export: `cave export — emit canonical CAVE text from a store
 
 Usage:
-  cave export [--db <path>] [--out <file>] [--current] [--no-prelude]
+  cave export [--db <path>] [--out <file>] [--current] [--tx] [--no-prelude]
 
 Options:
   ${dbHelp}
   --out <file>   write to a file instead of stdout
   --current      current beliefs only (skip superseded rows)
+  --tx           precede every claim line with its ;@ transaction
+                 annotation (spec §28.4) — the text carries row identity,
+                 so cave sync replays it idempotently; other readers see
+                 ordinary comments
   --no-prelude   open the store without the standard verb registry
 
 Examples:
   cave export --db k.db
   cave export --db k.db --out backup.cave
-  cave export --db k.db --current --out snapshot.cave`,
+  cave export --db k.db --current --out snapshot.cave
+  cave export --db k.db --tx | cave sync --db other.db -
+  cave export --db work.db --tx --out knowledge.cave    # the committed,
+                                    # reviewable store text (spec §28.6)`,
 
   reconstruct: `cave reconstruct — active memory reconstruction from seed cues (spec §18)
 
@@ -479,6 +624,7 @@ export const queryCommand = (argv: readonly string[]): Output => {
       all: { type: 'boolean' },
       aliases: { type: 'boolean' },
       'as-of': { type: 'string' },
+      resolve: { type: 'boolean' },
       'no-prelude': { type: 'boolean' }
     },
     allowPositionals: true
@@ -492,6 +638,7 @@ export const queryCommand = (argv: readonly string[]): Output => {
     const matches = caveQuery(store, pattern, {
       all: values.all === true,
       aliases: values.aliases === true,
+      resolve: values.resolve === true,
       ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] }
     })
     if (values.json === true) {
@@ -516,6 +663,60 @@ export const queryCommand = (argv: readonly string[]): Output => {
   }
 }
 
+/**
+ * `cave resolve` — the human view of contradiction resolution (spec §26.4):
+ * contested facts with their candidates ranked as the policy sees them,
+ * or the effective policy itself under `--policy`.
+ */
+export const resolveCommand = (argv: readonly string[]): Output => {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      aliases: { type: 'boolean' },
+      policy: { type: 'boolean' },
+      json: { type: 'boolean' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: false
+  })
+  const percent = (value: number): string => `${Math.round(value * 1000) / 10}%`
+  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  try {
+    if (values.policy === true) {
+      const policy = store.resolutionPolicy()
+      if (values.json === true) {
+        return ok(`${JSON.stringify(policy, undefined, 2)}\n`)
+      }
+      const width = Math.max(...policy.map(entry => entry.prefix.length + 7))
+      const lines = policy.map(entry => {
+        const subject = entry.prefix === '' ? 'source' : `source/${entry.prefix}`
+        const dimensions = [
+          ...entry.precedence === undefined ? [] : [`precedence ${entry.precedence}`],
+          ...entry.reliability === undefined ? [] : [`reliability ${percent(entry.reliability)}`]
+        ]
+        return `${subject.padEnd(width)}  ${dimensions.join(', ')}`
+      })
+      return ok(`${lines.join('\n')}\n`)
+    }
+    const contested = store.contested({ aliases: values.aliases === true })
+    if (values.json === true) {
+      return ok(`${JSON.stringify(contested, undefined, 2)}\n`)
+    }
+    if (contested.length === 0) {
+      return ok('no contested facts\n')
+    }
+    const lines = contested.flatMap(group =>
+      group.rows.map((row, at) =>
+        `${at === 0 ? '' : '  over '}${row.raw_line} ; class ${row.res_class}, effective ${percent(row.res_conf)}`))
+    return ok(`${lines.join('\n')}\n`)
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  } finally {
+    store.close()
+  }
+}
+
 export const deriveCommand = (argv: readonly string[]): Output => {
   const { values, positionals } = parseArgs({
     args: [...argv],
@@ -831,12 +1032,141 @@ export const checkCommand = (argv: readonly string[]): Output => {
   }
 }
 
+/**
+ * `cave suggest-alias` — alias discovery (spec §27): same-entity
+ * candidates as suggested `ALIAS` claims for review. Async (the optional
+ * judge runs a shell agent), so `main.ts` routes it separately, like
+ * `reconstruct`.
+ */
+export const suggestAliasCommand = async (argv: readonly string[]): Promise<Output> => {
+  try {
+    const { values } = parseArgs({
+      args: [...argv],
+      options: {
+        db: { type: 'string' },
+        min: { type: 'string' },
+        limit: { type: 'string' },
+        agent: { type: 'string' },
+        timeout: { type: 'string' },
+        write: { type: 'boolean' },
+        json: { type: 'boolean' },
+        'no-prelude': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' }
+      },
+      allowPositionals: false
+    })
+    if (values.help === true) {
+      return ok(`${commandHelp['suggest-alias']}\n`)
+    }
+    const minScore = values.min === undefined ?
+      defaultMinScore :
+      values.min.endsWith('%') ? Number(values.min.slice(0, -1)) / 100 : Number(values.min)
+    if (!Number.isFinite(minScore) || minScore < 0 || minScore > 1) {
+      return fail(`cave suggest-alias: --min expects a score in 0..1 or N%, got ${JSON.stringify(values.min)}\n`)
+    }
+    const limit = values.limit === undefined ? undefined : Number(values.limit)
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+      return fail(`cave suggest-alias: --limit expects a positive integer, got ${JSON.stringify(values.limit)}\n`)
+    }
+    const timeoutSeconds = values.timeout === undefined ? undefined : Number(values.timeout)
+    if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
+      return fail(`cave suggest-alias: --timeout must be a positive number of seconds, got '${values.timeout}'\n`)
+    }
+    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+    try {
+      let suggestions = suggestAliases(store, { minScore, ...limit === undefined ? {} : { limit } })
+      if (values.agent !== undefined && suggestions.length > 0) {
+        const reply = await shellComplete(values.agent, timeoutSeconds === undefined ? {} : { timeoutSeconds })(
+          judgePrompt(store, suggestions)
+        )
+        suggestions = parseJudgeReply(reply, suggestions.length).map(index => suggestions[index]!)
+      }
+      if (values.json === true) {
+        return ok(`${JSON.stringify(suggestions, undefined, 2)}\n`)
+      }
+      if (suggestions.length === 0) {
+        return ok('no alias suggestions\n')
+      }
+      const lines = suggestions.map(suggestion => suggestion.line)
+      if (values.write === true) {
+        const { appended } = writeSuggestions(store, suggestions)
+        return ok(`${lines.join('\n')}\nappended ${appended} suggested alias claim(s)\n`)
+      }
+      return ok(`${lines.join('\n')}\n`)
+    } finally {
+      store.close()
+    }
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  }
+}
+
+/**
+ * `cave sync` — store merge (spec §28): another store's rows arrive by
+ * identity — a store file merges through SQL, `;@`-annotated canonical
+ * text (`cave export --tx`, or `-` for stdin) replays under its recorded
+ * ids. Idempotent: re-runs merge nothing and append no record.
+ */
+export const syncCommand = (argv: readonly string[]): Output => {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      as: { type: 'string' },
+      into: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+      'no-record': { type: 'boolean' },
+      json: { type: 'boolean' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: true
+  })
+  const [source, ...extra] = positionals
+  if (source === undefined || extra.length > 0) {
+    return fail('cave sync: exactly one source is required — a CAVE store file, ;@-annotated text, or - for stdin (spec §28.5)\n')
+  }
+  const dbPath = values.db ?? defaultDbPath()
+  const store = open(dbPath, values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  try {
+    const options = {
+      into: values.into === undefined ? labelOf(dbPath) : sanitizeLabel(values.into),
+      record: values['no-record'] !== true,
+      dryRun: values['dry-run'] === true,
+      ...values.as === undefined ? {} : { from: sanitizeLabel(values.as) }
+    }
+    const report: SyncReport = source === '-' ?
+      syncText(store, readFileSync(0, 'utf8'), { from: 'stdin', ...options }) :
+      syncFile(store, source, options)
+    if (values.json === true) {
+      return { code: report.problems.length > 0 ? 1 : 0, out: `${JSON.stringify(report, undefined, 2)}\n`, err: '' }
+    }
+    if (report.problems.length > 0) {
+      const detail = report.problems.map(problem => `  line ${problem.line}: ${problem.message}`).join('\n')
+      return fail(`cave sync: ${source}: ${report.problems.length} problem(s), nothing merged\n${detail}\n`)
+    }
+    const lines = [
+      `merged ${report.merged} claim(s), ${report.edges} edge(s)` +
+      (report.skipped > 0 ? `, ${report.skipped} already present` : '') +
+      (report.dryRun ? ' (dry run)' : '')
+    ]
+    if (report.record !== undefined) {
+      lines.push(`record: ${report.record}`)
+    }
+    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' },
+      tx: { type: 'boolean' },
       out: { type: 'string' },
       'no-prelude': { type: 'boolean' }
     },
@@ -844,12 +1174,12 @@ export const exportCommand = (argv: readonly string[]): Output => {
   })
   const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
   try {
-    const text = store.exportText({ current: values.current === true })
+    const text = store.exportText({ current: values.current === true, tx: values.tx === true })
     if (values.out === undefined) {
       return ok(text)
     }
     writeFileSync(values.out, text)
-    const claims = text === '' ? 0 : text.trimEnd().split('\n').length
+    const claims = text === '' ? 0 : text.trimEnd().split('\n').filter(line => txOfLine(line) === undefined).length
     return ok(`exported ${claims} claim(s) to ${values.out}\n`)
   } finally {
     store.close()
@@ -969,12 +1299,16 @@ export const cave = (argv: readonly string[]): Output => {
         return importCommand(rest)
       case 'query':
         return queryCommand(rest)
+      case 'resolve':
+        return resolveCommand(rest)
       case 'derive':
         return deriveCommand(rest)
       case 'act':
         return actCommand(rest)
       case 'check':
         return checkCommand(rest)
+      case 'sync':
+        return syncCommand(rest)
       case 'export':
         return exportCommand(rest)
       case 'demo':

package/src/index.ts

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

package/src/main.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /** `cave` binary entry point — see `cli.ts` for the command implementations. */
 
-import { cave, highlightCommand, reconstructCommand } from './cli.ts'
+import { cave, highlightCommand, reconstructCommand, suggestAliasCommand } from './cli.ts'
 
 const write = (code: number, out: string, err: string): void => {
   if (out !== '') {
@@ -38,6 +38,10 @@ if (argv[0] === 'mcp') {
   // Async: the LLM policy runs a shell agent once per step.
   const { code, out, err } = await reconstructCommand(argv.slice(1))
   write(code, out, err)
+} else if (argv[0] === 'suggest-alias') {
+  // Async: the optional judge runs a shell agent.
+  const { code, out, err } = await suggestAliasCommand(argv.slice(1))
+  write(code, out, err)
 } 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))