@cavelang/cli 0.27.3 → 0.29.0

package/src/commands.ts

@@ -0,0 +1,48 @@
+/**
+ * Authoritative inventory of the commands shipped by the `cave` binary.
+ *
+ * `importantOptions` is deliberately smaller than each command's complete
+ * `--help`: it is the review contract for the package README's reference
+ * table. Add a command or an option here when it becomes part of the public
+ * surface; the documentation test then identifies every stale copy.
+ */
+export type CommandReference = {
+  readonly name: string
+  readonly importantOptions: readonly string[]
+  /** The command implementation and detailed help live in another package. */
+  readonly delegated?: true
+}
+
+export const commandRegistry = [
+  { name: 'parse', importantOptions: ['--json'] },
+  { name: 'highlight', importantOptions: [] },
+  { name: 'add', importantOptions: ['--strict', '--check', '--no-prelude', '--no-src'] },
+  { name: 'import', importantOptions: ['--strict', '--no-prelude'] },
+  { name: 'query', importantOptions: ['--json', '--limit', '--cursor', '--all', '--aliases', '--as-of', '--at', '--resolve', '--no-prelude'] },
+  { name: 'resolve', importantOptions: ['--aliases', '--policy', '--json', '--no-prelude'] },
+  { name: 'derive', importantOptions: ['--dry-run', '--full', '--aliases', '--min-conf', '--max-passes', '--list', '--retract', '--json', '--no-prelude'] },
+  { name: 'act', importantOptions: ['--declare', '--list', '--retract', '--dry-run', '--no-check', '--aliases', '--hooks', '--json', '--no-prelude'] },
+  { name: 'automate', importantOptions: ['--once', '--declare', '--list', '--retract', '--hooks', '--agent', '--json', '--no-prelude'], delegated: true },
+  { name: 'check', importantOptions: ['--stale', '--json', '--no-prelude'] },
+  { name: 'backup', importantOptions: ['--out', '--force', '--verify', '--sha256'] },
+  { name: 'restore', importantOptions: ['--db', '--force', '--sha256'] },
+  { name: 'generate', importantOptions: ['--out', '--version', '--no-prelude'] },
+  { name: 'suggest-alias', importantOptions: ['--min', '--limit', '--agent', '--timeout', '--write', '--json', '--no-prelude'] },
+  { name: 'sync', importantOptions: ['--as', '--into', '--dry-run', '--no-record', '--json', '--no-prelude'] },
+  { name: 'export', importantOptions: ['--out', '--current', '--tx', '--max-sensitivity', '--no-prelude'] },
+  { name: 'report', importantOptions: ['--out', '--aliases', '--resolve', '--as-of', '--at', '--max-sensitivity', '--no-prelude'] },
+  { name: 'serve', importantOptions: ['--port', '--host', '--max-sensitivity', '--no-prelude'], delegated: true },
+  { name: 'mcp', importantOptions: ['--read-only', '--permissions', '--tools', '--hooks', '--no-prelude', '--src', '--no-src'], delegated: true },
+  { name: 'ingest', importantOptions: ['--agent', '--stdout', '--lenient', '--plan', '--dry-run', '--json', '--no-prelude'], delegated: true },
+  { name: 'eval', importantOptions: ['--agent', '--judge', '--runs', '--stdout', '--min', '--json', '--no-prelude'], delegated: true },
+  { name: 'connect', importantOptions: ['--map', '--key', '--watch', '--prune', '--query', '--dry-run', '--no-prelude'], delegated: true },
+  { name: 'reconstruct', importantOptions: ['--query', '--agent', '--steps', '--claims', '--timeout', '--trace', '--no-prelude'] },
+  { name: 'doctor', importantOptions: ['--hooks', '--json'] },
+  { name: 'demo', importantOptions: [] },
+  { name: 'version', importantOptions: [] },
+  { name: 'help', importantOptions: [] }
+] as const satisfies readonly CommandReference[]
+
+export const delegatedCommandNames: readonly string[] = commandRegistry
+  .filter(command => 'delegated' in command && command.delegated === true)
+  .map(command => command.name)

package/src/connect.ts

@@ -0,0 +1,2 @@
+/** Compatibility subpath for deterministic structured ingestion. */
+export * from '@cavelang/connect'

package/src/dispatch.ts

@@ -0,0 +1,141 @@
+/** One promise-based command dispatcher and process lifecycle for every command. */
+
+import { cave, highlightCommand, reconstructCommand, suggestAliasCommand } from './cli.ts'
+import { delegatedCommandNames } from './commands.ts'
+import type { Output } from './cli.ts'
+
+export type CommandRuntime = {
+  readonly stdin: NodeJS.ReadableStream
+  readonly stdout: NodeJS.WritableStream
+  readonly stderr: NodeJS.WritableStream
+  readonly signal?: AbortSignal
+  /** Include stack traces for unexpected exceptions. */
+  readonly debug?: boolean
+}
+
+const processRuntime = (): CommandRuntime => ({
+  stdin: process.stdin,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  debug: process.env['CAVE_DEBUG'] === '1'
+})
+
+const delegatedHelp = new Set<string>(delegatedCommandNames)
+
+const normalizedArgs = (raw: readonly string[]): readonly string[] =>
+  raw[0] === 'help' && raw[1] !== undefined && delegatedHelp.has(raw[1]) ? [raw[1], '--help'] : raw
+
+const write = (runtime: CommandRuntime, output: Output): number => {
+  if (output.out !== '') runtime.stdout.write(output.out)
+  if (output.err !== '') runtime.stderr.write(output.err)
+  return output.code
+}
+
+const runOutput = async (
+  runtime: CommandRuntime,
+  argv: readonly string[],
+  handler: (args: readonly string[]) => Output | Promise<Output>
+): Promise<number> => {
+  runtime.signal?.throwIfAborted()
+  const output = await handler(argv.slice(1))
+  runtime.signal?.throwIfAborted()
+  return write(runtime, output)
+}
+
+const execute = async (raw: readonly string[], runtime: CommandRuntime): Promise<number> => {
+  const argv = normalizedArgs(raw)
+  const [command, ...rest] = argv
+  const context = {
+    stdin: runtime.stdin,
+    stdout: runtime.stdout,
+    stderr: runtime.stderr,
+    ...runtime.signal === undefined ? {} : { signal: runtime.signal }
+  }
+  switch (command) {
+    case 'mcp': {
+      const { runMcp } = await import('@cavelang/mcp')
+      return await runMcp(rest, context)
+    }
+    case 'ingest': {
+      const { runIngest } = await import('@cavelang/ingest')
+      return await runIngest(rest, context)
+    }
+    case 'eval': {
+      const { runEval } = await import('@cavelang/eval')
+      return await runEval(rest, context)
+    }
+    case 'connect': {
+      const { runConnect } = await import('@cavelang/connect')
+      return await runConnect(rest, context)
+    }
+    case 'automate': {
+      const { runAutomate } = await import('@cavelang/automate')
+      return await runAutomate(rest, context)
+    }
+    case 'serve': {
+      const { runServe } = await import('@cavelang/view')
+      return await runServe(rest, context)
+    }
+    case 'reconstruct':
+      return await runOutput(runtime, argv, reconstructCommand)
+    case 'suggest-alias':
+      return await runOutput(runtime, argv, suggestAliasCommand)
+    case 'highlight':
+      if (!rest.includes('--help') && !rest.includes('-h')) {
+        return await runOutput(runtime, argv, highlightCommand)
+      }
+      break
+  }
+
+  runtime.signal?.throwIfAborted()
+  const output = await Promise.resolve(cave(argv))
+  runtime.signal?.throwIfAborted()
+  const colorize = output.code === 0 && command === 'export' && !rest.includes('--out') &&
+    output.out !== '' && runtime.stdout === process.stdout && process.stdout.isTTY === true &&
+    process.env['NO_COLOR'] === undefined
+  if (!colorize) return write(runtime, output)
+  const { highlighter } = await import('@cavelang/highlight')
+  return write(runtime, { ...output, out: (await highlighter()).ansi(output.out) })
+}
+
+/** Dispatch one invocation through the shared argument, I/O, error, and exit path. */
+export const dispatch = async (
+  argv: readonly string[],
+  runtime: CommandRuntime = processRuntime()
+): Promise<number> => {
+  try {
+    return await execute(argv, runtime)
+  } catch (error) {
+    if (runtime.signal?.aborted === true) return 0
+    const command = argv[0] === 'q' ? 'query' : argv[0]
+    const message = runtime.debug === true && error instanceof Error && error.stack !== undefined ?
+      error.stack : error instanceof Error ? error.message : String(error)
+    runtime.stderr.write(`cave${command === undefined || command.startsWith('-') ? '' : ` ${command}`}: ${message}\n`)
+    return 1
+  }
+}
+
+const signalExitCode = { SIGINT: 130, SIGTERM: 143 } as const
+
+/** Run the process lifecycle, aborting handlers and awaiting their cleanup on signals. */
+export const runCli = async (
+  argv: readonly string[],
+  runtime: CommandRuntime = processRuntime()
+): Promise<number> => {
+  const controller = new AbortController()
+  let received: keyof typeof signalExitCode | undefined
+  const handlers = {
+    SIGINT: (): void => { received = 'SIGINT'; controller.abort() },
+    SIGTERM: (): void => { received = 'SIGTERM'; controller.abort() }
+  }
+  process.once('SIGINT', handlers.SIGINT)
+  process.once('SIGTERM', handlers.SIGTERM)
+  const signal = runtime.signal === undefined ? controller.signal : AbortSignal.any([runtime.signal, controller.signal])
+  try {
+    const code = await dispatch(argv, { ...runtime, signal })
+    return received === undefined ? code : signalExitCode[received]
+  } finally {
+    process.removeListener('SIGINT', handlers.SIGINT)
+    process.removeListener('SIGTERM', handlers.SIGTERM)
+  }
+}

package/src/doctor.ts

@@ -0,0 +1,370 @@
+/** Read-only installation, runtime, and store diagnostics for `cave doctor`. */
+
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, parse } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { parseArgs } from 'node:util'
+import { Version } from '@cavelang/core'
+import { Schema, defaultDbPath } from '@cavelang/store'
+import { nodeSqliteAdapter } from '@cavelang/store/adapter/node'
+import type { SqliteDatabase } from '@cavelang/store/adapter'
+
+export type DoctorStatus = 'pass' | 'warn' | 'fail'
+
+export type DoctorCheck = {
+  readonly id: string
+  readonly status: DoctorStatus
+  readonly summary: string
+  readonly remediation?: string
+}
+
+export type DoctorReport = {
+  readonly format: 'cave.doctor'
+  readonly version: 1
+  readonly ok: boolean
+  readonly caveVersion: string
+  readonly runtime: {
+    readonly node: string
+    readonly platform: NodeJS.Platform
+    readonly arch: string
+  }
+  readonly configuration: {
+    readonly database: {
+      readonly source: 'flag' | 'environment' | 'default'
+      readonly kind: 'memory' | 'file'
+      readonly exists: boolean
+      readonly schemaVersion?: number
+      readonly claims?: number
+    }
+    readonly hooks: {
+      readonly source: 'flag' | 'none'
+      readonly exists: boolean
+      readonly entries?: number
+    }
+  }
+  readonly checks: readonly DoctorCheck[]
+}
+
+export type DoctorOutput = {
+  readonly code: number
+  readonly out: string
+  readonly err: string
+}
+
+const requiredNode = '22.18.0'
+
+const versionParts = (value: string): readonly [number, number, number] | undefined => {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value)
+  return match === null ? undefined : [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+const numericVersion = (value: string): string | undefined => {
+  const parts = versionParts(value)
+  return parts === undefined ? undefined : parts.join('.')
+}
+
+const atLeast = (actual: string, required: string): boolean => {
+  const a = versionParts(actual)
+  const b = versionParts(required)
+  if (a === undefined || b === undefined) return false
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index]! !== b[index]!) return a[index]! > b[index]!
+  }
+  return true
+}
+
+const check = (
+  id: string,
+  status: DoctorStatus,
+  summary: string,
+  remediation?: string
+): DoctorCheck => ({ id, status, summary, ...remediation === undefined ? {} : { remediation } })
+
+const nodeCheck = (): DoctorCheck =>
+  atLeast(process.versions.node, requiredNode) ?
+    check('runtime.node', 'pass', `Node ${process.versions.node} satisfies >=${requiredNode}`) :
+    check('runtime.node', 'fail', `Node ${process.versions.node} is unsupported`,
+      `Install Node ${requiredNode} or newer and rerun cave doctor.`)
+
+const sqliteCheck = (): DoctorCheck => {
+  let db: SqliteDatabase | undefined
+  try {
+    db = nodeSqliteAdapter.open(':memory:')
+    db.exec('PRAGMA foreign_keys = ON')
+    const sqlite = db.prepare('SELECT sqlite_version() AS version').get()?.['version']
+    const json = db.prepare(`SELECT json_valid('{}') AS available`).get()?.['available']
+    const foreignKeys = db.prepare('PRAGMA foreign_keys').get()?.['foreign_keys']
+    db.exec('CREATE VIRTUAL TABLE doctor_fts USING fts5(value)')
+    db.exec('DROP TABLE doctor_fts')
+    if (typeof sqlite !== 'string' || json !== 1 || foreignKeys !== 1 ||
+        nodeSqliteAdapter.capabilities.loadExtension === undefined) {
+      throw new Error('capability unavailable')
+    }
+    return check('runtime.sqlite', 'pass',
+      `SQLite ${sqlite} supports FTS5, JSON functions, foreign keys, and extension loading`)
+  } catch {
+    return check('runtime.sqlite', 'fail', 'The Node SQLite runtime lacks a required capability',
+      `Use an official Node ${requiredNode}+ build with SQLite FTS5 and JSON support.`)
+  } finally {
+    db?.close()
+  }
+}
+
+const grammarCheck = (): DoctorCheck => {
+  try {
+    const fromHighlight = createRequire(import.meta.resolve('@cavelang/highlight'))
+    const assets = [
+      fromHighlight.resolve('@cavelang/tree-sitter-cave/wasm'),
+      fromHighlight.resolve('@cavelang/tree-sitter-cave/highlights')
+    ]
+    if (assets.some(asset => !statSync(asset).isFile() || statSync(asset).size === 0)) {
+      throw new Error('asset unavailable')
+    }
+    return check('package.grammar', 'pass', 'Grammar WASM and highlight query are installed')
+  } catch {
+    return check('package.grammar', 'fail', 'Grammar assets are missing from the installed package layout',
+      'Reinstall @cavelang/cli without omitting its production dependencies.')
+  }
+}
+
+type Workspace = { readonly packageManager: string }
+
+const workspaceFrom = (start: string): Workspace | undefined => {
+  let directory = start
+  while (true) {
+    if (existsSync(join(directory, 'pnpm-workspace.yaml'))) {
+      try {
+        const manifest = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8')) as {
+          packageManager?: unknown
+        }
+        if (typeof manifest.packageManager === 'string' && manifest.packageManager.startsWith('pnpm@')) {
+          return { packageManager: manifest.packageManager }
+        }
+      } catch {
+        return { packageManager: 'pnpm' }
+      }
+      return { packageManager: 'pnpm' }
+    }
+    const parent = dirname(directory)
+    if (parent === directory || directory === parse(directory).root) return undefined
+    directory = parent
+  }
+}
+
+const pnpmCheck = (): DoctorCheck => {
+  const workspace = workspaceFrom(process.cwd())
+  if (workspace === undefined) {
+    return check('workspace.pnpm', 'pass', 'pnpm is not required for this installed CLI')
+  }
+  const result = spawnSync('pnpm', ['--version'], {
+    encoding: 'utf8',
+    timeout: 3_000,
+    stdio: ['ignore', 'pipe', 'ignore']
+  })
+  const actual = result.status === 0 ? numericVersion(result.stdout.trim()) : undefined
+  const pinned = workspace.packageManager.startsWith('pnpm@')
+  const required = pinned ? numericVersion(workspace.packageManager.slice('pnpm@'.length)) : undefined
+  if (actual === undefined) {
+    return check('workspace.pnpm', 'fail', 'This workspace requires pnpm, but pnpm is unavailable',
+      'Enable Corepack or install the pnpm version declared by the workspace.')
+  }
+  if (required !== undefined && !atLeast(actual, required)) {
+    return check('workspace.pnpm', 'fail', `pnpm ${actual} is older than the workspace requirement`,
+      `Enable Corepack or install pnpm ${required}.`)
+  }
+  return check('workspace.pnpm', 'pass', `pnpm ${actual} satisfies the workspace requirement`)
+}
+
+type DatabaseConfiguration = DoctorReport['configuration']['database']
+
+const inspectDatabase = (path: string, source: DatabaseConfiguration['source']): {
+  readonly configuration: DatabaseConfiguration
+  readonly checks: readonly DoctorCheck[]
+} => {
+  const memory = path === ':memory:'
+  const exists = memory || existsSync(path)
+  const base: DatabaseConfiguration = { source, kind: memory ? 'memory' : 'file', exists }
+  if (!exists) {
+    return {
+      configuration: base,
+      checks: [check('store.database', 'warn', 'The configured database does not exist yet',
+        'Run cave add to create it, or pass --db for an existing store.')]
+    }
+  }
+
+  let db: SqliteDatabase | undefined
+  let observed = base
+  try {
+    db = nodeSqliteAdapter.open(path, { readOnly: true })
+    const version = db.prepare('PRAGMA user_version').get()?.['user_version']
+    if (typeof version !== 'number') throw new Error('invalid version')
+    const caveObjects = db.prepare(
+      `SELECT count(*) AS count FROM sqlite_schema WHERE name LIKE 'cave_%' OR name LIKE 'idx_cave_%'`
+    ).get()?.['count']
+    const configuration = { ...base, schemaVersion: version }
+    observed = configuration
+
+    if (version > Schema.currentVersion) {
+      return {
+        configuration,
+        checks: [check('store.database', 'fail',
+          `Database schema ${version} is newer than supported schema ${Schema.currentVersion}`,
+          'Upgrade CAVE before opening this database.')]
+      }
+    }
+    if (version === 0 && caveObjects === 0) {
+      return {
+        configuration,
+        checks: [check('store.database', 'warn', 'The database is readable but is not initialized as a CAVE store',
+          'Run cave add to initialize it; cave doctor made no changes.')]
+      }
+    }
+    if (version < Schema.currentVersion) {
+      return {
+        configuration,
+        checks: [check('store.database', 'warn',
+          `Database schema ${version} needs migration to schema ${Schema.currentVersion}`,
+          'Back up the database, then open it with a normal cave command to migrate it.')]
+      }
+    }
+
+    Schema.validate(db, version)
+    const integrity = db.prepare('PRAGMA integrity_check').all()
+    if (integrity.length !== 1 || integrity[0]?.['integrity_check'] !== 'ok') {
+      return {
+        configuration,
+        checks: [check('store.integrity', 'fail', 'SQLite integrity checking failed',
+          'Restore a verified backup or recover the database with SQLite tooling.')]
+      }
+    }
+    const foreignKeys = db.prepare('PRAGMA foreign_key_check').all()
+    if (foreignKeys.length > 0) {
+      return {
+        configuration,
+        checks: [check('store.integrity', 'fail', 'The store contains broken foreign-key references',
+          'Restore a verified backup or repair the affected database rows.')]
+      }
+    }
+    const claims = db.prepare('SELECT count(*) AS count FROM cave_claim').get()?.['count']
+    if (typeof claims !== 'number') throw new Error('invalid count')
+    return {
+      configuration: { ...configuration, claims },
+      checks: [
+        check('store.database', 'pass', `CAVE schema ${version} is compatible (${claims} claim(s))`),
+        check('store.integrity', 'pass', 'SQLite integrity and foreign-key checks passed')
+      ]
+    }
+  } catch {
+    return {
+      configuration: observed,
+      checks: [check('store.database', 'fail', 'The configured database is unreadable or has an incompatible schema',
+        'Check file permissions, restore a verified backup, or pass --db for another store.')]
+    }
+  } finally {
+    db?.close()
+  }
+}
+
+type HooksConfiguration = DoctorReport['configuration']['hooks']
+
+const inspectHooks = (path: string | undefined): {
+  readonly configuration: HooksConfiguration
+  readonly check: DoctorCheck
+} => {
+  if (path === undefined) {
+    return {
+      configuration: { source: 'none', exists: false },
+      check: check('config.hooks', 'pass', 'No optional hooks file was configured')
+    }
+  }
+  const configuration = { source: 'flag' as const, exists: existsSync(path) }
+  if (!configuration.exists) {
+    return {
+      configuration,
+      check: check('config.hooks', 'fail', 'The configured hooks file does not exist',
+        'Create a JSON object of hook names to shell command strings, or omit --hooks.')
+    }
+  }
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) throw new Error('invalid')
+    const entries = Object.entries(parsed)
+    if (entries.some(([name, command]) => name.trim() === '' || typeof command !== 'string')) {
+      throw new Error('invalid')
+    }
+    return {
+      configuration: { ...configuration, entries: entries.length },
+      check: check('config.hooks', 'pass', `Hooks configuration is valid (${entries.length} entr${entries.length === 1 ? 'y' : 'ies'})`)
+    }
+  } catch {
+    return {
+      configuration,
+      check: check('config.hooks', 'fail', 'The configured hooks file is unreadable or malformed',
+        'Use a JSON object whose values are shell command strings.')
+    }
+  }
+}
+
+export const diagnose = (options: { readonly db?: string, readonly hooks?: string } = {}): DoctorReport => {
+  const databasePath = options.db ?? defaultDbPath()
+  const databaseSource: DatabaseConfiguration['source'] = options.db !== undefined ? 'flag' :
+    process.env['CAVE_DB'] !== undefined ? 'environment' : 'default'
+  const database = inspectDatabase(databasePath, databaseSource)
+  const hooks = inspectHooks(options.hooks)
+  const checks = [
+    nodeCheck(),
+    sqliteCheck(),
+    grammarCheck(),
+    pnpmCheck(),
+    ...database.checks,
+    hooks.check
+  ]
+  return {
+    format: 'cave.doctor',
+    version: 1,
+    ok: checks.every(entry => entry.status !== 'fail'),
+    caveVersion: Version.current(),
+    runtime: { node: process.versions.node, platform: process.platform, arch: process.arch },
+    configuration: { database: database.configuration, hooks: hooks.configuration },
+    checks
+  }
+}
+
+const render = (report: DoctorReport): string => {
+  const lines = [`cave doctor ${report.caveVersion}`]
+  for (const entry of report.checks) {
+    lines.push(`${entry.status.toUpperCase().padEnd(4)} ${entry.summary}`)
+    if (entry.remediation !== undefined) lines.push(`     ${entry.remediation}`)
+  }
+  const failures = report.checks.filter(entry => entry.status === 'fail').length
+  const warnings = report.checks.filter(entry => entry.status === 'warn').length
+  lines.push(report.ok ?
+    `result: ready${warnings === 0 ? '' : ` with ${warnings} warning(s)`}` :
+    `result: ${failures} problem(s), ${warnings} warning(s)`)
+  return `${lines.join('\n')}\n`
+}
+
+export const doctorCommand = (argv: readonly string[]): DoctorOutput => {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      hooks: { type: 'string' },
+      json: { type: 'boolean' }
+    },
+    allowPositionals: true
+  })
+  if (positionals.length > 0) {
+    return { code: 2, out: '', err: 'cave doctor: unexpected positional arguments\n' }
+  }
+  const report = diagnose({
+    ...values.db === undefined ? {} : { db: values.db },
+    ...values.hooks === undefined ? {} : { hooks: values.hooks }
+  })
+  return {
+    code: report.ok ? 0 : 1,
+    out: values.json === true ? `${JSON.stringify(report, undefined, 2)}\n` : render(report),
+    err: ''
+  }
+}

package/src/eval.ts

@@ -0,0 +1,2 @@
+/** Compatibility subpath for the evaluation tooling. */
+export * from '@cavelang/eval'

package/src/index.ts

@@ -1,7 +1,14 @@
 /**
  * `@cavelang/cli` — the `cave` command (parse / add / query / resolve / derive / act / check / suggest-alias / sync / export / report / reconstruct / demo).
- * Programmatic access to the same implementations lives here.
+ * Programmatic access to the same implementations lives here; `dispatch`
+ * and `runCli` expose the shared awaited command lifecycle.
  */
 
-export { actCommand, addCommand, cave, checkCommand, commandHelp, demoCommand, deriveCommand, exportCommand, helpCommand, highlightCommand, importCommand, parseCommand, queryCommand, reconstructCommand, reportCommand, resolveCommand, suggestAliasCommand, syncCommand, usage, versionCommand } from './cli.ts'
+export { actCommand, addCommand, backupCommand, cave, checkCommand, commandHelp, demoCommand, deriveCommand, exportCommand, generateCommand, helpCommand, highlightCommand, importCommand, parseCommand, queryCommand, reconstructCommand, reportCommand, resolveCommand, restoreCommand, suggestAliasCommand, syncCommand, usage, versionCommand } from './cli.ts'
+export { dispatch, runCli } from './dispatch.ts'
+export type { CommandRuntime } from './dispatch.ts'
+export { commandRegistry } from './commands.ts'
+export type { CommandReference } from './commands.ts'
 export type { Output } from './cli.ts'
+export { diagnose, doctorCommand } from './doctor.ts'
+export type { DoctorCheck, DoctorOutput, DoctorReport, DoctorStatus } from './doctor.ts'

package/src/ingest.ts

@@ -0,0 +1,2 @@
+/** Compatibility subpath for the agent ingestion tooling. */
+export * from '@cavelang/ingest'

package/src/loop.ts

@@ -0,0 +1,2 @@
+/** Compatibility subpath for reconstruction policies. */
+export * from '@cavelang/loop'

package/src/main.ts

@@ -1,69 +1,6 @@
 #!/usr/bin/env node
-/** `cave` binary entry point — see `cli.ts` for the command implementations. */
+/** `cave` binary entry point — one lifecycle for every command. */
 
-import { cave, highlightCommand, reconstructCommand, suggestAliasCommand } from './cli.ts'
+import { runCli } from './dispatch.ts'
 
-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, connect, eval, automate and serve 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' || raw[1] === 'connect' || raw[1] === 'eval' || raw[1] === 'automate' || raw[1] === 'serve') ?
-  [raw[1], '--help'] :
-  raw
-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 if (argv[0] === 'eval') {
-  // Long-running: drives an agent (and optionally a judge) over eval fixtures.
-  const { runEval } = await import('@cavelang/eval')
-  process.exitCode = await runEval(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] === 'automate') {
-  // Async (prompt steps run a shell agent) and potentially long-running (the loop).
-  const { runAutomate } = await import('@cavelang/automate')
-  process.exitCode = await runAutomate(argv.slice(1))
-} else if (argv[0] === 'serve') {
-  // Long-running: the human read surface serves HTTP until interrupted.
-  const { runServe } = await import('@cavelang/view')
-  process.exitCode = await runServe(argv.slice(1))
-} else if (argv[0] === 'reconstruct') {
-  // 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))
-  write(code, out, err)
-} else {
-  const { code, out, err } = cave(argv)
-  // 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)
-  }
-}
+process.exitCode = await runCli(process.argv.slice(2))

package/src/mcp.ts

@@ -0,0 +1,2 @@
+/** Compatibility subpath for the MCP server API. */
+export * from '@cavelang/mcp'

package/src/rules.ts

@@ -0,0 +1,2 @@
+/** Compatibility subpath for the internal rules engine. */
+export * from '@cavelang/rules'