@cavelang/cli 0.27.3 → 0.29.0

package/dist/internal/automate/main.js

@@ -0,0 +1,298 @@
+/**
+ * `cave automate` entry (spec §29.5) — argument parsing, the declare /
+ * list / retract lifecycle, one settle cycle under `--once`, and the
+ * long-running loop: a cheap `MAX(tx)` poll, a cycle whenever it moves.
+ */
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { Registry } from '@cavelang/canonical';
+import { shellComplete } from '@cavelang/cli/loop';
+import { defaultDbPath, open } from '@cavelang/store';
+import { declareAutomations, listAutomations, retractAutomation } from "./declare.js";
+import { defaultAgentTimeoutSeconds, defaultMaxPasses, settle, settled } from "./engine.js";
+const usage = `cave automate — the event-driven loop (spec §29)
+
+Usage:
+  cave automate [--db <path>] [options]        watch the store; settle on change
+  cave automate [--db <path>] --once [--json]  one settle cycle, then exit
+  cave automate [--db <path>] --declare [file...]
+  cave automate [--db <path>] --list [--json]
+  cave automate [--db <path>] --retract <name>
+
+Options:
+  --db <path>          database file (default: $CAVE_DB, or cave.db)
+  --once               run one settle cycle and exit — cron replaces the
+                       daemon; the exit code carries step failures
+  --interval <s>       poll interval in seconds (default 2)
+  --declare            declare the automations of CAVE documents (stdin
+                       when no file); other lines are prelude
+  --list               print the store's current automations and exit
+  --retract <n>        retract an automation's declaration and exit
+  --hooks <file>       JSON file of out-of-band hook command templates,
+                       name → shell template (spec §25.4), shared with
+                       action steps; default: $CAVE_HOOKS
+  --agent <template>   shell agent for prompt steps — the cave ingest/eval
+                       contract: prompt on stdin and {prompt-file}
+                       (substituted shell-quoted), CAVE reply on stdout
+                       (appended, spec §29.3)
+  --timeout <seconds>  per-prompt agent timeout (default ${defaultAgentTimeoutSeconds})
+  --aliases            triggers match through the alias closure (spec §13.6)
+  --no-derive          do not fire the store's rules each pass (spec §29.4)
+  --no-check           skip the shape gate on action steps (spec §25.3)
+  --max-passes <n>     settle guard per cycle (default ${defaultMaxPasses})
+  --json               with --once/--list: emit the report as JSON
+  --no-prelude         open the store without the standard verb registry
+
+An automation pairs a trigger with steps, declared in-band (spec §29.1):
+
+  automation/page-on-spike HAS automation: \`?svc IS service,
+    ?svc HAS error-rate: ?r, ?r > 0.05 =>
+    action/open-incident, hook/page, "investigate the spike on ?svc"\`
+
+New claims matching the trigger fire the steps — a §25 action (parameters
+bound from same-named trigger variables), an out-of-band hook (trigger
+claims on stdin), or an agent prompt whose CAVE reply is recorded. Rules
+(spec §24) fire incrementally each pass. An automation is armed at its
+declaration and never wakes itself; chains across automations converge
+because every write path is idempotent.
+
+Examples:
+  cave automate --db k.db --declare automations.cave
+  cave automate --db k.db --once
+  cave automate --db k.db --hooks hooks.json --agent 'claude -p'
+  cave automate --db k.db --once --json | jq '.automations'`;
+const waitForAbort = (signal) => signal?.aborted === true ? Promise.resolve() : new Promise(resolve => signal?.addEventListener('abort', () => resolve(), { once: true }));
+/** Loads a §25.4 hooks configuration file: name → shell command template. */
+const readHooks = (path) => {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) ||
+        Object.values(parsed).some(value => typeof value !== 'string')) {
+        throw new Error(`${path}: hooks must be a JSON object of name → shell template strings`);
+    }
+    return parsed;
+};
+const readInput = async (files, input) => {
+    if (files.length > 0 && !(files.length === 1 && files[0] === '-')) {
+        return files.map(file => readFileSync(file, 'utf8')).join('\n');
+    }
+    let text = '';
+    for await (const chunk of input) {
+        text += String(chunk);
+    }
+    return text;
+};
+/** Text rendering of one cycle — only what fired, plus problems and notes. */
+const renderReport = (report) => {
+    const lines = [];
+    for (const problem of report.problems) {
+        lines.push(`${problem.subject}: ${problem.problems.join('; ')}`);
+    }
+    for (const automation of report.automations) {
+        if (automation.fired === 0) {
+            continue;
+        }
+        lines.push(`${automation.subject}: fired ${automation.fired} solution(s)` +
+            (automation.description === undefined ? '' : ` ; ${automation.description}`));
+        for (const firing of automation.firings) {
+            const bindings = Object.entries(firing.bindings)
+                .map(([name, value]) => `?${name} = ${value}`)
+                .join('  ');
+            if (bindings !== '') {
+                lines.push(`  ${bindings}`);
+            }
+            for (const step of firing.steps) {
+                lines.push(`    ${step.step}: ${step.outcome}${step.detail === undefined ? '' : ` (${step.detail})`}`);
+            }
+        }
+    }
+    lines.push(...report.notes.map(note => `note: ${note}`));
+    const fired = report.automations.reduce((sum, automation) => sum + automation.fired, 0);
+    const derived = report.derive === undefined ?
+        '' :
+        `; derived +${report.derive.appended} appended, ${report.derive.updated} updated, ${report.derive.retracted} retracted`;
+    lines.push(`settled: ${fired} firing(s) over ${report.passes} pass(es)${derived}`);
+    return lines;
+};
+const settleOptions = (values) => {
+    const hooksPath = values.hooks ?? process.env['CAVE_HOOKS'];
+    const timeoutSeconds = values.timeout === undefined ? defaultAgentTimeoutSeconds : Number(values.timeout);
+    return {
+        aliases: values.aliases === true,
+        derive: values['no-derive'] !== true,
+        check: values['no-check'] !== true,
+        ...values['max-passes'] === undefined ? {} : { maxPasses: Number(values['max-passes']) },
+        ...hooksPath === undefined ? {} : { hooks: readHooks(hooksPath) },
+        ...values.agent === undefined ? {} : { complete: shellComplete(values.agent, { timeoutSeconds }) }
+    };
+};
+const maxTxOf = (store) => store.db.prepare('SELECT MAX(tx) AS t FROM cave_claim').get().t;
+/**
+ * One watch cycle (spec §29.5): settle, report, and return the tx
+ * boundary the poll may treat as seen. The boundary is captured *before*
+ * each settle, and the cycle re-settles until `MAX(tx)` is unchanged
+ * across one — a write landing while a settle runs (or while its report
+ * renders) re-enters the loop instead of being marked seen unprocessed
+ * (BUGS.md watch-watermark-race). Settle's own appends move `MAX(tx)`
+ * too, so a cycle that fired ends with one confirming settle; quiescent
+ * write paths (§29.4) are what make the loop terminate.
+ */
+export const watchCycle = async (store, options, onReport) => {
+    for (;;) {
+        const boundary = maxTxOf(store);
+        onReport(await settle(store, options));
+        if (maxTxOf(store) === boundary) {
+            return boundary;
+        }
+    }
+};
+/** The daemon (spec §29.5): settle at startup, then settle when MAX(tx) moves. */
+const runWatch = async (store, options, intervalSeconds, io) => {
+    let seen = null;
+    let running = false;
+    const onReport = (report) => {
+        const fired = report.automations.some(automation => automation.fired > 0);
+        if (fired || report.problems.length > 0 || report.notes.length > 0) {
+            io.stdout.write(`${renderReport(report).join('\n')}\n`);
+        }
+    };
+    const cycle = async () => {
+        running = true;
+        try {
+            seen = await watchCycle(store, options, onReport);
+        }
+        catch (error) {
+            io.stderr.write(`cave automate: ${error instanceof Error ? error.message : String(error)}\n`);
+            // `seen` stays put: the next tick retries the pending events —
+            // settling is idempotent (§29.3) — instead of stalling them
+            // behind an unrelated later append.
+        }
+        running = false;
+    };
+    let active = cycle();
+    await active;
+    io.stdout.write(`watching (poll every ${intervalSeconds}s, ctrl-c to stop)\n`);
+    const timer = setInterval(() => {
+        if (!running && maxTxOf(store) !== seen) {
+            active = cycle();
+            void active;
+        }
+    }, intervalSeconds * 1000);
+    await waitForAbort(io.signal);
+    clearInterval(timer);
+    await active;
+    return 0;
+};
+export const runAutomate = async (argv, context = {}) => {
+    const io = {
+        stdin: context.stdin ?? process.stdin,
+        stdout: context.stdout ?? process.stdout,
+        stderr: context.stderr ?? process.stderr,
+        ...context.signal === undefined ? {} : { signal: context.signal }
+    };
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            once: { type: 'boolean' },
+            interval: { type: 'string' },
+            declare: { type: 'boolean' },
+            list: { type: 'boolean' },
+            retract: { type: 'string' },
+            hooks: { type: 'string' },
+            agent: { type: 'string' },
+            timeout: { type: 'string' },
+            aliases: { type: 'boolean' },
+            'no-derive': { type: 'boolean' },
+            'no-check': { type: 'boolean' },
+            'max-passes': { type: 'string' },
+            json: { type: 'boolean' },
+            'no-prelude': { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' }
+        },
+        allowPositionals: true
+    });
+    if (values.help === true) {
+        io.stdout.write(`${usage}\n`);
+        return 0;
+    }
+    const intervalSeconds = values.interval === undefined ? 2 : Number(values.interval);
+    if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0) {
+        io.stderr.write(`cave automate: --interval must be a positive number of seconds, got '${values.interval}'\n`);
+        return 1;
+    }
+    const maxPasses = values['max-passes'] === undefined ? undefined : Number(values['max-passes']);
+    if (maxPasses !== undefined && (!Number.isInteger(maxPasses) || maxPasses < 1)) {
+        io.stderr.write(`cave automate: --max-passes expects a positive integer, got '${values['max-passes']}'\n`);
+        return 1;
+    }
+    const timeoutSeconds = values.timeout === undefined ? undefined : Number(values.timeout);
+    if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
+        io.stderr.write(`cave automate: --timeout must be a positive number of seconds, got '${values.timeout}'\n`);
+        return 1;
+    }
+    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        if (values.declare === true) {
+            const declaration = declareAutomations(store, await readInput(positionals, io.stdin));
+            for (const problem of declaration.problems) {
+                io.stderr.write(`line ${problem.line}: ${problem.message}\n`);
+            }
+            io.stdout.write(`declared ${declaration.declared} automation(s)` +
+                (declaration.unchanged > 0 ? `, ${declaration.unchanged} unchanged` : '') +
+                (declaration.prelude > 0 ? `, +${declaration.prelude} prelude claim(s)` : '') + '\n');
+            return declaration.problems.length > 0 ? 1 : 0;
+        }
+        if (values.list === true) {
+            const automations = listAutomations(store);
+            if (values.json === true) {
+                io.stdout.write(`${JSON.stringify(automations, undefined, 2)}\n`);
+                return 0;
+            }
+            if (automations.length === 0) {
+                io.stdout.write('no automations\n');
+                return 0;
+            }
+            for (const automation of automations) {
+                io.stdout.write(`${automation.subject} \`${automation.text}\`` +
+                    `${automation.description === undefined ? '' : ` ; ${automation.description}`}\n`);
+                if (!automation.ok) {
+                    io.stdout.write(`  problems: ${automation.problems.join('; ')}\n`);
+                }
+            }
+            return 0;
+        }
+        if (values.retract !== undefined) {
+            const outcome = retractAutomation(store, values.retract);
+            if (!outcome.ok) {
+                io.stderr.write(`cave automate: ${outcome.error}\n`);
+                return 1;
+            }
+            io.stdout.write(`retracted ${outcome.subject} — what past firings recorded stays recorded (spec §29.1)\n`);
+            return 0;
+        }
+        if (positionals.length > 0) {
+            io.stderr.write(`cave automate: unexpected argument ${JSON.stringify(positionals[0])} — files go with --declare\n`);
+            return 1;
+        }
+        const options = settleOptions(values);
+        if (values.once === true) {
+            const report = await settle(store, options);
+            if (values.json === true) {
+                io.stdout.write(`${JSON.stringify(report, undefined, 2)}\n`);
+            }
+            else {
+                io.stdout.write(`${renderReport(report).join('\n')}\n`);
+            }
+            return settled(report) ? 0 : 1;
+        }
+        return await runWatch(store, options, intervalSeconds, io);
+    }
+    catch (error) {
+        io.stderr.write(`cave automate: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        store.close();
+    }
+};
+//# sourceMappingURL=main.js.map

package/dist/internal/automate/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/main.ts"],"names":[],"mappings":"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"}

package/dist/internal/connect/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@cavelang/cli/connect` — deterministic structured ingestion (spec §23).
+ *
+ * ```sh
+ * cave connect people.csv --map people.map.cave --db k.db --key id
+ * ```
+ *
+ * Library API:
+ *
+ * ```ts
+ * import { Source, Template, connect } from '@cavelang/cli/connect'
+ * import { open } from '@cavelang/store'
+ *
+ * const store = open('k.db')
+ * const { mapping } = Template.parse(mappingText)
+ * const { records } = await Source.load('people.csv')
+ * const report = connect(store, mapping!, records, { name: 'people', key: 'id' })
+ * ```
+ */
+export * as Source from './source.ts';
+export * as Template from './template.ts';
+export { connect, digestAttribute, digestOf, federatedQuery, isConnected, provenanceContext } from './run.ts';
+export type { ConnectOptions, Failure, FederatedOutcome, Report } from './run.ts';
+export { runConnect } from './main.ts';
+export type { RunContext as ConnectRunContext, ScheduleLike, WatchLike } from './main.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/internal/connect/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC7G,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,YAAY,EAAE,UAAU,IAAI,iBAAiB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA"}

package/dist/internal/connect/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@cavelang/cli/connect` — deterministic structured ingestion (spec §23).
+ *
+ * ```sh
+ * cave connect people.csv --map people.map.cave --db k.db --key id
+ * ```
+ *
+ * Library API:
+ *
+ * ```ts
+ * import { Source, Template, connect } from '@cavelang/cli/connect'
+ * import { open } from '@cavelang/store'
+ *
+ * const store = open('k.db')
+ * const { mapping } = Template.parse(mappingText)
+ * const { records } = await Source.load('people.csv')
+ * const report = connect(store, mapping!, records, { name: 'people', key: 'id' })
+ * ```
+ */
+export * as Source from "./source.js";
+export * as Template from "./template.js";
+export { connect, digestAttribute, digestOf, federatedQuery, isConnected, provenanceContext } from "./run.js";
+export { runConnect } from "./main.js";
+//# sourceMappingURL=index.js.map

package/dist/internal/connect/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAE7G,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA"}

package/dist/internal/connect/main.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `cave connect` entry — argument parsing, pass orchestration (single,
+ * `--watch`, `--query`), and report rendering around `run.ts`.
+ */
+import * as Source from './source.ts';
+export type RunContext = {
+    readonly stdout?: NodeJS.WritableStream;
+    readonly stderr?: NodeJS.WritableStream;
+    readonly signal?: AbortSignal;
+    /** URL transport injection for deterministic integrations. */
+    readonly fetchImpl?: Source.FetchLike;
+    /** Directory-watcher injection; production uses `node:fs.watch`. */
+    readonly watch?: WatchLike;
+    /** Debounce scheduler injection; production waits 200ms. */
+    readonly schedule?: ScheduleLike;
+    readonly cancelScheduled?: (handle: unknown) => void;
+};
+export type WatchLike = (path: string, listener: (event: string, filename: string | Buffer | null) => void) => {
+    close(): void;
+};
+export type ScheduleLike = (callback: () => Promise<void>, delayMs: number) => unknown;
+export declare const runConnect: (argv: readonly string[], context?: RunContext) => Promise<number>;
+//# sourceMappingURL=main.d.ts.map

package/dist/internal/connect/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAuErC,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAA;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAA;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,SAAS,CAAA;IACrC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;CACrD,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,CACtB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,KAAK,IAAI,KAChE;IAAE,KAAK,IAAI,IAAI,CAAA;CAAE,CAAA;AAEtB,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;AAyOtF,eAAO,MAAM,UAAU,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,UAAe,KAAG,OAAO,CAAC,MAAM,CA6ElG,CAAA"}