@cavelang/cli 0.32.2 → 0.33.0

package/src/cli.ts

@@ -9,12 +9,13 @@
  * - `cave highlight [file]` — ANSI syntax colors (async)
  * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`, `--check`)
  * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`, `--aliases`, `--as-of`, `--resolve`)
+ * - `cave search [--db <path>] <terms..>` — FTS5 full-text search over claims and comments (`--raw`, `--limit`, `--json`)
  * - `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 automate [--db <path>]` — the event-driven loop (spec §29; async)
  * - `cave check [--db <path>]` — knowledge health report (`--stale`, `--json`)
- * - `cave backup [--db <path>] --out <path>` — exact verified SQLite snapshot
+ * - `cave backup [--db <path>] --out <path>` — exact verified store snapshot
  * - `cave restore <snapshot> --db <path>` — verify and atomically restore a snapshot
  * - `cave generate [--db <path>]` — versioned TypeScript client from EXPECTS declarations
  * - `cave suggest-alias [--db <path>]` — same-entity candidates (spec §27; async)
@@ -38,11 +39,11 @@ import { readFileSync, readSync, statSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { parseArgs } from 'node:util'
 import { Version } from '@cavelang/core'
-import { parseDocument } from '@cavelang/parser'
+import { parseDocument, Token } from '@cavelang/parser'
 import { Registry, standardRegistry } from '@cavelang/canonical'
 import { Sensitivity, backup as backupStore, defaultDbPath, open, restoreBackup, verifyBackup } from '@cavelang/store'
 import type { Store } from '@cavelang/store'
-import { defaultLimit as defaultQueryLimit, page as caveQueryPage } from '@cavelang/query'
+import { defaultLimit as defaultQueryLimit, maxLimit as maxQueryLimit, page as caveQueryPage } from '@cavelang/query'
 import {
   check as caveCheck, defaultMinScore, defaultStaleDays, gatedIngest, judgePrompt, parseJudgeReply,
   generateClient, suggestAliases, writeSuggestions
@@ -115,13 +116,14 @@ Usage:
   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 bounded CAVE-Q page [--limit <n>] [--cursor <token>] [--json]
+  cave search [--db <path>] <terms..>      full-text search over claims and comments (FTS5) [--raw] [--limit <n>] [--json]
   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 automate [--db <path>]              event-driven loop (spec §29): new claims fire rules/actions/hooks/agent prompts [--once]
   cave check [--db <path>]                 knowledge health report (spec §20) [--stale <days>] [--json]
-  cave backup [--db <path>] --out <file>   exact verified SQLite snapshot [--force]
+  cave backup [--db <path>] --out <file>   exact verified store snapshot [--force]
   cave restore <snapshot> --db <path>      verify and atomically restore an exact snapshot [--force]
   cave generate [--db <path>]              generate a typed client from EXPECTS [--out <file>] [--version <n>]
   cave suggest-alias [--db <path>]         propose same-entity ALIAS candidates (spec §27) [--min <s>] [--agent] [--write]
@@ -278,7 +280,9 @@ Options:
 
 Patterns are claim triples with ?variables and optional metadata filters
 (spec §12). A second positional starting with WHERE filters on conf,
-value or tx.
+value or tx. A binding line carries the matched claim's comment
+(?x = value  ; comment), so evidence written next to a claim travels
+with the answer; fully bound patterns print the raw line, comment included.
 
 Examples:
   cave query '?x USES jwt'
@@ -292,6 +296,39 @@ Examples:
   cave query --db k.db 'service HAS owner: ?who' --resolve
   cave query --db k.db '?x ?verb ?y @production' --json`,
 
+  search: `cave search — full-text search over claims and comments (spec §13.2)
+
+Usage:
+  cave search [--db <path>] <terms...> [--raw] [--limit <n>] [--json] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --raw          treat the terms as FTS5 MATCH syntax: AND / OR / NOT,
+                 NEAR(a b), prefix* and column filters such as
+                 comment:heap or subject:auth
+  --limit <n>    matches to print (default ${defaultQueryLimit}, maximum ${maxQueryLimit})
+  --json         emit a versioned cave.search/v1 JSON object whose matches
+                 are cave.claim/v1 records
+  --no-prelude   open the store without the standard verb registry
+
+Searches the full-text index the store maintains over every claim:
+subject, verb, object, attribute name, value text, comment, and the raw
+line as written (so tags, contexts, and inverse spellings match too).
+Terms are one literal phrase by default — safe for hyphenated names such
+as token-expiry, which raw FTS5 syntax would read as a column filter.
+Tokens split on punctuation, so heap-dump also matches "heap dump" and
+auth/middleware matches auth middleware. Results are newest first, one
+raw line each, comments included; retracted and superseded rows stay
+searchable (spec §9.6), so pair a hit with cave query or cave export
+--current when currency matters.
+
+Examples:
+  cave search 'heap dump'
+  cave search --db k.db token-expiry
+  cave search --db k.db --raw 'comment:heap AND subject:auth'
+  cave search --db k.db --raw 'jwt OR oauth*' --limit 20
+  cave search --db k.db 'rotated weekly' --json`,
+
   resolve: `cave resolve — contested facts and their winners (spec §26)
 
 Usage:
@@ -434,7 +471,7 @@ Examples:
   cave check --db k.db --stale 30
   cave check --db k.db --json | jq '.violations'`,
 
-  backup: `cave backup — exact, verified SQLite snapshot (spec §13.2.2)
+  backup: `cave backup — exact, verified store snapshot (spec §13.2.2)
 
 Usage:
   cave backup [--db <path>] --out <file> [--force]
@@ -456,7 +493,7 @@ Examples:
   cave backup --db k.db --out backups/k.db
   cave backup --verify backups/k.db --sha256 <hex>`,
 
-  restore: `cave restore — verify and atomically restore an exact SQLite snapshot (spec §13.2.2)
+  restore: `cave restore — verify and atomically restore an exact store snapshot (spec §13.2.2)
 
 Usage:
   cave restore <snapshot> --db <path> [--force] [--sha256 <hex>]
@@ -712,7 +749,19 @@ topic → fix over a small in-memory store.`,
   version: `cave version — print the cave version
 
 Usage:
-  cave version`
+  cave version`,
+
+  help: `cave help — the overview, or one command's options and examples
+
+Usage:
+  cave help
+  cave help <command>
+
+Every command answers --help with the same text as cave help <command>.
+
+Examples:
+  cave help query
+  cave help serve`
 }
 
 const readStdin = (): string => {
@@ -908,7 +957,14 @@ export const queryCommand = (argv: readonly string[]): Output => {
         .join('  ')
       // A fully bound pattern has no bindings to print; transitive matches
       // additionally carry no row — confirm with the pattern itself.
-      const line = bindings !== '' ? bindings : match.claim?.claim.raw ?? pattern.split('\n')[0]!
+      // Bindings carry the matched claim's comment so the evidence written
+      // next to a claim travels with the answer; raw lines already do. A
+      // multi-line comment (§6.4) opens above the binding line, as it does
+      // above a claim.
+      const comment = match.claim?.claim.comment
+      const line = bindings !== '' ?
+        comment === undefined ? bindings : Token.joinComment(`${bindings} `, comment) :
+        match.claim?.claim.raw ?? pattern.split('\n')[0]!
       // An interpolated trajectory shows its value at the anchor
       // (spec §32.4) — bindings already carry it in the value slot.
       return match.at !== undefined && bindings === '' ?
@@ -923,6 +979,66 @@ export const queryCommand = (argv: readonly string[]): Output => {
   }
 }
 
+export const searchFormat = 'cave.search' as const
+export const searchVersion = 1 as const
+
+/**
+ * `cave search` — the store's FTS5 index (spec §13.2) from the shell:
+ * one literal phrase by default, raw MATCH syntax on request, newest
+ * matches first. Lines print as written, so comments come along.
+ */
+export const searchCommand = (argv: readonly string[]): Output => {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    options: {
+      db: { type: 'string' },
+      raw: { type: 'boolean' },
+      limit: { type: 'string' },
+      json: { type: 'boolean' },
+      'no-prelude': { type: 'boolean' }
+    },
+    allowPositionals: true
+  })
+  const query = positionals.join(' ').trim()
+  if (query === '') {
+    return fail('cave search: search terms are required\n')
+  }
+  const limit = values.limit === undefined ? defaultQueryLimit : Number(values.limit)
+  if (!Number.isInteger(limit) || limit < 1 || limit > maxQueryLimit) {
+    return fail(`cave search: --limit must be an integer from 1 to ${maxQueryLimit}\n`)
+  }
+  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  try {
+    const raw = values.raw === true
+    const found = store.search(query, { raw, limit: limit + 1 })
+    const matches = found.slice(0, limit)
+    const truncated = found.length > limit
+    if (values.json === true) {
+      return ok(`${JSON.stringify({
+        format: searchFormat,
+        version: searchVersion,
+        query,
+        raw,
+        limit,
+        truncated,
+        matches: matches.map(row => store.recordOf(row))
+      }, undefined, 2)}\n`)
+    }
+    if (matches.length === 0) {
+      return ok('no matches\n')
+    }
+    const lines = matches.map(row => row.raw_line)
+    if (truncated) {
+      lines.push(`more matches beyond ${limit}; raise --limit`)
+    }
+    return ok(`${lines.join('\n')}\n`)
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  } finally {
+    store.close()
+  }
+}
+
 /**
  * `cave resolve` — the human view of contradiction resolution (spec §26.4):
  * contested facts with their candidates ranked as the policy sees them,
@@ -1299,7 +1415,7 @@ const snapshotLine = (
   `${action} exact backup (${snapshot.rows} row(s), schema v${snapshot.schemaVersion}, ` +
   `${snapshot.bytes} bytes, sha256:${snapshot.sha256}) at ${snapshot.path}\n`
 
-/** `cave backup` — create or verify an exact SQLite snapshot (§13.2.2). */
+/** `cave backup` — create or verify an exact store snapshot (§13.2.2). */
 export const backupCommand = (argv: readonly string[]): Output => {
   const { values } = parseArgs({
     args: [...argv],
@@ -1717,9 +1833,11 @@ export const reconstructCommand = async (
           ),
           positionals
         )
+      // The trace is a documentary comment block: the blank line after it
+      // keeps it off the first claim when the output is added back (§6.4).
       const lines = [
-        ...values.trace === true ?
-          result.trace.map(step => `; ${step.step}. ${step.cue.entity} @ ${step.cue.score.toFixed(2)} +${step.collected} claim(s)`) :
+        ...values.trace === true && result.trace.length > 0 ?
+          [...result.trace.map(step => `; ${step.step}. ${step.cue.entity} @ ${step.cue.score.toFixed(2)} +${step.collected} claim(s)`), ''] :
           [],
         ...result.claims.map(claim => emitClaim(claim))
       ]
@@ -1732,15 +1850,36 @@ export const reconstructCommand = async (
   }
 }
 
-export const demoCommand = (): Output =>
-  ok(`${Demo.run().lines.join('\n')}\n`)
+/**
+ * Positional arguments of a command that declares no options: an unknown
+ * option throws, which the dispatcher reports as an ordinary problem
+ * (status 1).
+ */
+const positionalsOf = (argv: readonly string[]): readonly string[] =>
+  parseArgs({ args: [...argv], options: {}, allowPositionals: true }).positionals
+
+/** The usage error (status 2) for more positionals than a command takes. */
+const surplusPositionals = (command: string, positionals: readonly string[], max: number): Output | undefined =>
+  positionals.length > max ? fail(`cave ${command}: unexpected positional arguments\n`, 2) : undefined
 
-export const versionCommand = (): Output =>
-  ok(`${Version.current()}\n`)
+export const demoCommand = (argv: readonly string[] = []): Output => {
+  const problem = surplusPositionals('demo', positionalsOf(argv), 0)
+  if (problem !== undefined) return problem
+  return ok(`${Demo.run().lines.join('\n')}\n`)
+}
+
+export const versionCommand = (argv: readonly string[] = []): Output => {
+  const problem = surplusPositionals('version', positionalsOf(argv), 0)
+  if (problem !== undefined) return problem
+  return ok(`${Version.current()}\n`)
+}
 
 /** `cave help [command]` — the overview, or one command's help text. */
 export const helpCommand = (argv: readonly string[]): Output => {
-  const [topic] = argv
+  const positionals = positionalsOf(argv)
+  const problem = surplusPositionals('help', positionals, 1)
+  if (problem !== undefined) return problem
+  const [topic] = positionals
   if (topic === undefined) {
     return ok(`${usage}\n`)
   }
@@ -1772,6 +1911,8 @@ export const cave = (argv: readonly string[]): Output => {
       return importCommand(rest)
     case 'query':
       return queryCommand(rest)
+    case 'search':
+      return searchCommand(rest)
     case 'resolve':
       return resolveCommand(rest)
     case 'derive':
@@ -1795,11 +1936,11 @@ export const cave = (argv: readonly string[]): Output => {
     case 'doctor':
       return doctorCommand(rest)
     case 'demo':
-      return demoCommand()
+      return demoCommand(rest)
     case 'version':
     case '--version':
     case '-v':
-      return versionCommand()
+      return versionCommand(rest)
     case 'help':
       return helpCommand(rest)
     case undefined:

package/src/commands.ts

@@ -19,6 +19,7 @@ export const commandRegistry = [
   { 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: 'search', importantOptions: ['--raw', '--limit', '--json', '--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'] },

package/src/dispatch.ts

@@ -22,8 +22,10 @@ const processRuntime = (): CommandRuntime => ({
 
 const delegatedHelp = new Set<string>(delegatedCommandNames)
 
+// Exactly `help <delegated command>` becomes `<command> --help`; anything
+// longer stays with `cave help`, which rejects the surplus as a usage error.
 const normalizedArgs = (raw: readonly string[]): readonly string[] =>
-  raw[0] === 'help' && raw[1] !== undefined && delegatedHelp.has(raw[1]) ? [raw[1], '--help'] : raw
+  raw.length === 2 && raw[0] === 'help' && delegatedHelp.has(raw[1]!) ? [raw[1]!, '--help'] : raw
 
 const write = (runtime: CommandRuntime, output: Output): number => {
   if (output.out !== '') runtime.stdout.write(output.out)

package/src/doctor.ts

@@ -53,6 +53,7 @@ export type DoctorOutput = {
 }
 
 const requiredNode = '22.18.0'
+const supportedNodeRange = '^22.18.0 || ^24.0.0 || ^26.0.0'
 
 const versionParts = (value: string): readonly [number, number, number] | undefined => {
   const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value)
@@ -74,6 +75,18 @@ const atLeast = (actual: string, required: string): boolean => {
   return true
 }
 
+// Only stable releases are supported: a nightly or release-candidate build such
+// as `26.0.0-nightly20260829` or `24.0.0-rc.1` carries the numeric prefix of a
+// supported line but satisfies neither the engine range nor the CI matrix.
+const stableVersion = /^\d+\.\d+\.\d+$/
+
+export const isSupportedNodeVersion = (value: string): boolean => {
+  if (!stableVersion.test(value)) return false
+  const major = versionParts(value)?.[0]
+  if (major === 22) return atLeast(value, requiredNode)
+  return major === 24 || major === 26
+}
+
 const check = (
   id: string,
   status: DoctorStatus,
@@ -82,10 +95,10 @@ const check = (
 ): 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}`) :
+  isSupportedNodeVersion(process.versions.node) ?
+    check('runtime.node', 'pass', `Node ${process.versions.node} satisfies ${supportedNodeRange}`) :
     check('runtime.node', 'fail', `Node ${process.versions.node} is unsupported`,
-      `Install Node ${requiredNode} or newer and rerun cave doctor.`)
+      `Install Node ${requiredNode}+, Node 24, or Node 26 and rerun cave doctor.`)
 
 const sqliteCheck = (): DoctorCheck => {
   let db: SqliteDatabase | undefined

package/src/index.ts

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