@cavelang/cli 0.33.0 → 0.35.0

package/dist/src/cli.js

@@ -40,7 +40,8 @@ import { parseArgs } from 'node:util';
 import { Version } from '@cavelang/core';
 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 { backup as backupStore, defaultDbPath, kindOf, LocateError, openAt, restoreBackup, Sensitivity, verifyBackup } from '@cavelang/store';
+import { Declared, assemble as assembleSources } from '@cavelang/cli/connect';
 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 } from '@cavelang/cli/shape';
 import { declareRules, defaultMaxPasses, defaultMinConf, derive, listRules, retractRule } from '@cavelang/cli/rules';
@@ -115,9 +116,11 @@ Usage:
   cave help [command]                      this text, or one command's options and examples
 
 Every command answers --help. --db defaults to $CAVE_DB, or cave.db in
-the current directory. The spec lives in the .claude/skills/ directory at
+the current directory, and names a SQLite store or a CAVE text file: text
+replays into an in-memory store for commands that only read (writes refuse
+it), and a read never creates a missing database. The spec lives in the .claude/skills/ directory at
 the repository root (section index in README.md).`;
-const dbHelp = `--db <path>    database file (default: $CAVE_DB, or cave.db)`;
+const dbHelp = `--db <path>    store: a SQLite file, or CAVE text read into memory (default: $CAVE_DB, or cave.db)`;
 /** Per-command help, printed for \`cave <command> --help\` and \`cave help <command>\`. */
 export const commandHelp = {
     doctor: `cave doctor — diagnose runtime, installation, and store health
@@ -216,7 +219,7 @@ Examples:
     query: `cave query — run a CAVE-Q pattern against a store
 
 Usage:
-  cave query [--db <path>] <pattern> [WHERE <filter>] [--limit <n>] [--cursor <token>] [--json] [--all] [--aliases] [--as-of <t>] [--at <t>] [--resolve] [--no-prelude]
+  cave query [--db <path>] <pattern> [WHERE <filter>] [--limit <n>] [--cursor <token>] [--json] [--all] [--aliases] [--as-of <t>] [--at <t>] [--resolve] [--sources] [--no-prelude]
 
 Options:
   ${dbHelp}
@@ -242,6 +245,12 @@ Options:
                  collapse to the row the resolution policy picks
                  (precedence class, reliability-weighted confidence, tx);
                  incompatible with --all
+  --sources      overlay the store's declared sources (spec §23.4) inside a
+                 rolled-back transaction — federation-lite: external data is
+                 consulted at query time, nothing persists. The answer is
+                 whole (no --cursor, --limit is not a page size); a text
+                 store followed its local sources on open, so only URL
+                 sources are loaded here
   --no-prelude   open the store without the standard verb registry
 
 Patterns are claim triples with ?variables and optional metadata filters
@@ -252,6 +261,7 @@ with the answer; fully bound patterns print the raw line, comment included.
 
 Examples:
   cave query '?x USES jwt'
+  cave query --db notes.cave '?x USES jwt'
   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'
@@ -260,6 +270,7 @@ Examples:
   cave query --db k.db 'revenue IS' --at 2026-07
   cave query --db k.db 'alice WORKS-AT ?org' --at 2021
   cave query --db k.db 'service HAS owner: ?who' --resolve
+  cave query --db k.db '?who WORKS-AT acme' --sources
   cave query --db k.db '?x ?verb ?y @production' --json`,
     search: `cave search — full-text search over claims and comments (spec §13.2)
 
@@ -733,6 +744,54 @@ const readStdin = () => {
         }
     }
 };
+/**
+ * Opens the store `--db` names (spec §13.7): a SQLite file, or a CAVE text
+ * file replayed into memory. `read` never creates, migrates, or changes a
+ * file — a missing path is an error, not an empty database; `scratch` is a
+ * dry run that appends inside a rolled-back transaction, so it may write
+ * but creates and migrates nothing; `write` creates a missing SQLite store,
+ * migrates an older one, and refuses text files with the materialization
+ * hint.
+ */
+const openDb = (values, intent) => openAt(values.db ?? defaultDbPath(), {
+    intent,
+    // A text store follows its declared sources on open (spec §23.4).
+    assemble: assembleSources,
+    ...values['no-prelude'] === true ? { registry: Registry.empty } : {}
+});
+const sourcesRollback = Symbol('cave query --sources rollback');
+/**
+ * Runs `body` with the store's declared sources overlaid (spec §23.4): the
+ * sources, loaded beforehand (URLs included), append inside a transaction
+ * that always rolls back, so external data is consulted at query time and
+ * nothing persists, digests included.
+ */
+const withSources = (store, discovered, body) => {
+    let result;
+    try {
+        store.transaction(() => {
+            // Discovered on a snapshot: if a writer changed the declarations
+            // since, the sequence is stale and the caller rediscovers.
+            if (!Declared.sameDeclarations(discovered.baseline, Declared.declarationState(store))) {
+                throw sourcesRollback;
+            }
+            for (const source of discovered.sequence) {
+                const report = Declared.run(store, source, { force: true });
+                if (report.failures.length > 0) {
+                    throw new LocateError(`source/${source.declared.name}: ${report.failures.map(failure => `${failure.record}: ${failure.problems.join('; ')}`).join('; ')}`);
+                }
+            }
+            result = { value: body() };
+            throw sourcesRollback;
+        });
+    }
+    catch (error) {
+        if (error !== sourcesRollback) {
+            throw error;
+        }
+    }
+    return result;
+};
 const readInput = (files) => files.length === 0 || (files.length === 1 && files[0] === '-') ?
     readStdin() :
     files.map(file => readFileSync(file, 'utf8')).join('\n');
@@ -809,7 +868,7 @@ const ingestCommand = (name) => (argv) => {
         allowPositionals: true
     });
     const input = readInput(positionals);
-    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    const store = openDb(values, 'write');
     try {
         const options = {
             strict: values.strict === true,
@@ -854,39 +913,125 @@ export const addCommand = ingestCommand('add');
  * identity.
  */
 export const importCommand = ingestCommand('import');
-export const queryCommand = (argv) => {
-    const { values, positionals } = parseArgs({
-        args: [...argv],
-        options: {
-            db: { type: 'string' },
-            json: { type: 'boolean' },
-            all: { type: 'boolean' },
-            aliases: { type: 'boolean' },
-            'as-of': { type: 'string' },
-            at: { type: 'string' },
-            resolve: { type: 'boolean' },
-            limit: { type: 'string' },
-            cursor: { type: 'string' },
-            'no-prelude': { type: 'boolean' }
-        },
-        allowPositionals: true
-    });
+const queryOptions = {
+    db: { type: 'string' },
+    json: { type: 'boolean' },
+    all: { type: 'boolean' },
+    aliases: { type: 'boolean' },
+    'as-of': { type: 'string' },
+    at: { type: 'string' },
+    resolve: { type: 'boolean' },
+    sources: { type: 'boolean' },
+    limit: { type: 'string' },
+    cursor: { type: 'string' },
+    'no-prelude': { type: 'boolean' }
+};
+const parseQuery = (argv) => {
+    const { values, positionals } = parseArgs({ args: [...argv], options: queryOptions, allowPositionals: true });
     if (positionals.length === 0) {
-        return fail('cave query: a pattern is required (spec §12.1)\n');
+        return { failure: fail('cave query: a pattern is required (spec §12.1)\n') };
     }
-    const pattern = positionals.join('\n');
-    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    if (values.sources === true && values.cursor !== undefined) {
+        return { failure: fail('cave query: --cursor does not apply to --sources — the overlay exists for one invocation and is answered whole\n') };
+    }
+    return { values, pattern: positionals.join('\n') };
+};
+/**
+ * `cave query --sources` — the store with its declared sources overlaid
+ * (spec §23.4). Asynchronous because the sources load first, URLs
+ * included, before the overlay appends inside a transaction that rolls
+ * back; the dispatcher routes `--sources` here. A text store followed its
+ * local sources on open, so only what assembly could not follow — URL
+ * sources and what they declare — is loaded. The overlay exists for this
+ * invocation alone, so the answer is whole: pages are followed inside the
+ * transaction and no cursor is handed out.
+ */
+export const querySourcesCommand = async (argv, runtime = {}) => {
+    const parsed = parseQuery(argv);
+    if ('failure' in parsed) {
+        return parsed.failure;
+    }
+    const { values, pattern } = parsed;
+    if (values.sources !== true) {
+        return queryCommand(argv);
+    }
+    const root = values.db ?? defaultDbPath();
+    // The overlay appends inside a transaction it rolls back: writable, but
+    // never creating or migrating (spec §13.7).
+    const store = openDb(values, 'scratch');
     try {
-        const limit = values.limit === undefined ? defaultQueryLimit : Number(values.limit);
-        const result = caveQueryPage(store, pattern, {
-            all: values.all === true,
-            aliases: values.aliases === true,
-            resolve: values.resolve === true,
-            limit,
-            ...values.cursor === undefined ? {} : { cursor: values.cursor },
-            ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] },
-            ...values.at === undefined ? {} : { at: values.at }
-        });
+        for (let attempt = 0; attempt < Declared.overlayAttempts; attempt += 1) {
+            const discovered = await Declared.discovery(store, root, {
+                // The overlay applies every source it loads (force), so discovery
+                // simulates that; a text store skips what assembly already followed.
+                force: true,
+                ...kindOf(root) === 'text' ? { skipFollowed: true } : {},
+                ...runtime.fetchImpl === undefined ? {} : { fetchImpl: runtime.fetchImpl }
+            });
+            const page = withSources(store, discovered, () => wholeQuery(store, values, pattern));
+            if (page !== undefined) {
+                return renderQueryPage(store, values, pattern, () => page.value);
+            }
+        }
+        throw Declared.staleOverlay();
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    finally {
+        store.close();
+    }
+};
+export const queryCommand = (argv) => {
+    const parsed = parseQuery(argv);
+    if ('failure' in parsed) {
+        return parsed.failure;
+    }
+    const { values, pattern } = parsed;
+    if (values.sources === true) {
+        // Loading sources cannot be synchronous: the in-process entry for the
+        // overlay is `querySourcesCommand`, which the dispatcher uses.
+        return fail('cave query: --sources loads the declared sources first and runs asynchronously — use querySourcesCommand\n');
+    }
+    const store = openDb(values, 'read');
+    try {
+        return renderQueryPage(store, values, pattern, () => queryPage(store, values, pattern));
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    finally {
+        store.close();
+    }
+};
+/** Every match of the overlay: the pages are followed here, inside the transaction that holds it. */
+const wholeQuery = (store, values, pattern) => {
+    const matches = [];
+    let first;
+    let cursor;
+    for (;;) {
+        const page = queryPage(store, { ...values, limit: '1000', ...cursor === undefined ? {} : { cursor } }, pattern);
+        first ??= page;
+        matches.push(...page.matches);
+        if (page.next === undefined) {
+            const { next: _next, ...rest } = first;
+            return { ...rest, matches };
+        }
+        cursor = page.next;
+    }
+};
+const queryPage = (store, values, pattern) => caveQueryPage(store, pattern, {
+    all: values.all === true,
+    aliases: values.aliases === true,
+    resolve: values.resolve === true,
+    limit: values.limit === undefined ? defaultQueryLimit : Number(values.limit),
+    ...values.cursor === undefined ? {} : { cursor: values.cursor },
+    ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] },
+    ...values.at === undefined ? {} : { at: values.at }
+});
+const renderQueryPage = (store, values, pattern, page) => {
+    {
+        const result = page();
         if (values.json === true) {
             return ok(`${JSON.stringify(result, undefined, 2)}\n`);
         }
@@ -916,12 +1061,6 @@ export const queryCommand = (argv) => {
         });
         return ok(`${lines.join('\n')}\n${result.next === undefined ? '' : `next: ${result.next}\n`}`);
     }
-    catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-    finally {
-        store.close();
-    }
 };
 export const searchFormat = 'cave.search';
 export const searchVersion = 1;
@@ -950,7 +1089,7 @@ export const searchCommand = (argv) => {
     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 } : {});
+    const store = openDb(values, 'read');
     try {
         const raw = values.raw === true;
         const found = store.search(query, { raw, limit: limit + 1 });
@@ -1001,7 +1140,7 @@ export const resolveCommand = (argv) => {
         allowPositionals: false
     });
     const percent = (value) => `${Math.round(value * 1000) / 10}%`;
-    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    const store = openDb(values, 'read');
     try {
         if (values.policy === true) {
             const policy = store.resolutionPolicy();
@@ -1063,7 +1202,11 @@ export const deriveCommand = (argv) => {
     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 } : {});
+    // The intent follows the branch order below: listing reads, retracting
+    // writes, a dry run appends inside a rolled-back transaction.
+    const store = openDb(values, values.list === true ? 'read' :
+        values.retract !== undefined ? 'write' :
+            values['dry-run'] === true ? 'scratch' : 'write');
     try {
         if (values.list === true) {
             const rules = listRules(store);
@@ -1217,7 +1360,13 @@ export const actCommand = (argv) => {
         },
         allowPositionals: true
     });
-    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    // The intent follows the branch order below: declaring and retracting
+    // write, listing reads, a dry-run execution appends inside a rolled-back
+    // transaction.
+    const store = openDb(values, values.declare === true ? 'write' :
+        values.list === true ? 'read' :
+            values.retract !== undefined ? 'write' :
+                values['dry-run'] === true ? 'scratch' : 'write');
     try {
         if (values.declare === true) {
             const declaration = declareActions(store, readInput(positionals));
@@ -1335,7 +1484,7 @@ export const checkCommand = (argv) => {
     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 } : {});
+    const store = openDb(values, 'read');
     try {
         const report = caveCheck(store, { staleDays });
         const out = values.json === true ?
@@ -1379,7 +1528,15 @@ export const backupCommand = (argv) => {
         if (values.out === undefined) {
             return fail('cave backup: --out <file> is required\n');
         }
-        const store = open(values.db ?? defaultDbPath());
+        const dbPath = values.db ?? defaultDbPath();
+        // A text store is replayed into memory, so the backup API cannot see that
+        // the destination aliases the source: refuse before the file could be
+        // replaced by a SQLite snapshot of itself (a SQLite source is covered by
+        // the API's own check).
+        if (sameFile(dbPath, values.out)) {
+            return fail(`cave backup: --out '${values.out}' is the source database — refusing to overwrite it\n`);
+        }
+        const store = openAt(dbPath, { intent: 'read', assemble: assembleSources });
         try {
             return ok(snapshotLine('created', backupStore(store, values.out, { force: values.force === true })));
         }
@@ -1460,7 +1617,7 @@ export const suggestAliasCommand = async (argv, runtime = {}) => {
         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 } : {});
+        const store = openDb(values, values.write === true ? 'write' : 'read');
         try {
             let suggestions = suggestAliases(store, { minScore, ...limit === undefined ? {} : { limit } });
             if (values.agent !== undefined && suggestions.length > 0) {
@@ -1516,7 +1673,7 @@ export const syncCommand = (argv) => {
         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 } : {});
+    const store = openDb(values, values['dry-run'] === true ? 'scratch' : 'write');
     try {
         const options = {
             into: values.into === undefined ? labelOf(dbPath) : sanitizeLabel(values.into),
@@ -1578,7 +1735,10 @@ export const reportCommand = (argv) => {
     if (maximum === undefined) {
         return fail(`cave report: --max-sensitivity expects ${Sensitivity.levels.join(', ')}, got ${JSON.stringify(values['max-sensitivity'])}\n`);
     }
-    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    if (values.out !== undefined && sameFile(values.db ?? defaultDbPath(), values.out)) {
+        return fail(`cave report: --out '${values.out}' is the source database — refusing to overwrite it\n`);
+    }
+    const store = openDb(values, 'read');
     try {
         const rendered = caveReport(store, template, {
             aliases: values.aliases === true,
@@ -1647,7 +1807,7 @@ export const exportCommand = (argv) => {
     if (values.out !== undefined && sameFile(db, values.out)) {
         return fail(`cave export: --out '${values.out}' is the source database — refusing to overwrite it\n`);
     }
-    const store = open(db, values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    const store = openDb(values, 'read');
     try {
         const text = store.exportText({ current: values.current === true, tx: values.tx === true, maxSensitivity: maximum });
         if (values.out === undefined) {
@@ -1687,7 +1847,7 @@ export const generateCommand = (argv) => {
     if (values.out !== undefined && sameFile(db, values.out)) {
         return fail(`cave generate: --out '${values.out}' is the source database — refusing to overwrite it\n`);
     }
-    const store = open(db, values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    const store = openDb(values, 'read');
     try {
         const generated = generateClient(store, version === undefined ? {} : { version });
         if (!generated.ok) {
@@ -1750,7 +1910,7 @@ export const reconstructCommand = async (argv, runtime = {}) => {
         if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
             return fail(`cave reconstruct: --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 } : {});
+        const store = openDb(values, 'read');
         try {
             const graph = sqliteStore(store);
             const result = values.agent === undefined ?
@@ -1825,6 +1985,19 @@ export const cave = (argv) => {
         (rest.includes('--help') || rest.includes('-h'))) {
         return ok(`${commandHelp[canonical]}\n`);
     }
+    try {
+        return run(canonical, rest);
+    }
+    catch (error) {
+        // A --db path that is not what the command needs (spec §13.7) is a
+        // usage failure, reported the way dispatch reports thrown errors.
+        if (error instanceof LocateError) {
+            return fail(`cave ${canonical}: ${error.message}\n`);
+        }
+        throw error;
+    }
+};
+const run = (canonical, rest) => {
     switch (canonical) {
         case 'parse':
             return parseCommand(rest);
@@ -1871,7 +2044,7 @@ export const cave = (argv) => {
         case '-h':
             return ok(`${usage}\n`);
         default:
-            return fail(`cave: unknown command ${JSON.stringify(command)}\n\n${usage}\n`, 2);
+            return fail(`cave: unknown command ${JSON.stringify(canonical)}\n\n${usage}\n`, 2);
     }
 };
 //# sourceMappingURL=cli.js.map