akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/storage/sqlite-read-snapshot.js

@@ -0,0 +1,148 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Side-effect-free SQLite snapshots for planning and preview paths.
+ *
+ * A normal SQLite read-only connection can still write lock bytes into an
+ * existing `-shm` file when the source database is in WAL mode. Dry planning
+ * must not do that. This helper copies a stable main/WAL pair and opens that
+ * private copy, so SQLite never attaches to the operator's original
+ * main/WAL/SHM files.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { openDatabaseFinalizing } from "./database.js";
+export class SqliteReadSnapshotUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SqliteReadSnapshotUnavailableError";
+    }
+}
+function pathExists(filePath) {
+    try {
+        fs.lstatSync(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function fileFingerprint(filePath) {
+    try {
+        const stat = fs.statSync(filePath, { bigint: true });
+        return { size: stat.size, mtimeNs: stat.mtimeNs, ctimeNs: stat.ctimeNs };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function databaseFingerprint(dbPath) {
+    const main = fileFingerprint(dbPath);
+    if (!main) {
+        throw new SqliteReadSnapshotUnavailableError("SQLite snapshot source disappeared while it was being inspected");
+    }
+    const wal = fileFingerprint(`${dbPath}-wal`);
+    return { main, ...(wal ? { wal } : {}) };
+}
+function fingerprintsEqual(left, right) {
+    const sameFile = (a, b) => a?.size === b?.size && a?.mtimeNs === b?.mtimeNs && a?.ctimeNs === b?.ctimeNs;
+    return sameFile(left.main, right.main) && sameFile(left.wal, right.wal);
+}
+/**
+ * Open an isolated copy of an existing SQLite database.
+ *
+ * Returns `undefined` only when the source is absent. Committed WAL frames are
+ * copied beside the private main file; the source SHM is intentionally not
+ * copied because SQLite can safely create one inside the disposable directory.
+ * A live rollback-journal database fails closed because a file-level copy
+ * cannot distinguish its committed and uncommitted pages without attaching to
+ * the source.
+ */
+export function openSqliteReadSnapshot(dbPath) {
+    if (!pathExists(dbPath))
+        return undefined;
+    if (pathExists(`${dbPath}-journal`)) {
+        throw new SqliteReadSnapshotUnavailableError("an active SQLite rollback journal is present; a non-mutating point-in-time snapshot is unavailable");
+    }
+    const snapshotDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-sqlite-read-"));
+    const snapshotPath = path.join(snapshotDir, "snapshot.db");
+    let db;
+    try {
+        let copied = false;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                if (pathExists(`${dbPath}-journal`)) {
+                    throw new SqliteReadSnapshotUnavailableError("an active SQLite rollback journal appeared while taking the non-mutating snapshot");
+                }
+                const before = databaseFingerprint(dbPath);
+                fs.copyFileSync(dbPath, snapshotPath);
+                if (before.wal)
+                    fs.copyFileSync(`${dbPath}-wal`, `${snapshotPath}-wal`);
+                else
+                    fs.rmSync(`${snapshotPath}-wal`, { force: true });
+                const after = databaseFingerprint(dbPath);
+                if (fingerprintsEqual(before, after)) {
+                    copied = true;
+                    break;
+                }
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+        }
+        if (!copied) {
+            throw new SqliteReadSnapshotUnavailableError("SQLite main/WAL files kept changing while taking the non-mutating snapshot");
+        }
+        db = openDatabaseFinalizing(snapshotPath, { readonly: true, create: false });
+        const closeSnapshot = db.close.bind(db);
+        let closed = false;
+        const cleanup = (bestEffort) => {
+            if (closed)
+                return;
+            closed = true;
+            process.removeListener("exit", cleanupOnExit);
+            if (bestEffort) {
+                try {
+                    closeSnapshot();
+                }
+                catch {
+                    // Process teardown is already committed; keep removing the copy.
+                }
+                try {
+                    fs.rmSync(snapshotDir, { recursive: true, force: true });
+                }
+                catch {
+                    // Best-effort process-exit backstop. Normal close still surfaces IO errors.
+                }
+                return;
+            }
+            try {
+                closeSnapshot();
+            }
+            finally {
+                fs.rmSync(snapshotDir, { recursive: true, force: true });
+            }
+        };
+        const cleanupOnExit = () => cleanup(true);
+        process.once("exit", cleanupOnExit);
+        db.close = () => cleanup(false);
+        return db;
+    }
+    catch (error) {
+        try {
+            db?.close();
+        }
+        finally {
+            fs.rmSync(snapshotDir, { recursive: true, force: true });
+        }
+        throw error;
+    }
+}

package/dist/tasks/backends/cron.js

@@ -30,7 +30,8 @@ import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
-import { buildScheduledTaskInvocation, parseScheduledTaskArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
+import { assertSchedulerExecutionEvidenceDigest, assertSchedulerExpectationIdentity, assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, assertSchedulerNativeArtifactOwner, assertSchedulerRemovalArtifact, assertSchedulerRollbackArtifactCardinality, schedulerBindingNativeId, schedulerLogicalBindingId, schedulerLogicalBindingOwner, schedulerNativeArtifactKey, } from "../scheduler-binding.js";
+import { buildScheduledBindingInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
 import { nodeFs, throwIfNotOk } from "./exec-utils.js";
 const BEGIN = (id) => `# akm:task ${assertCronValue(id)} BEGIN`;
 const END = (id) => `# akm:task ${assertCronValue(id)} END`;
@@ -38,6 +39,7 @@ const DISABLED_PREFIX = "# akm:disabled ";
 const BLOCK_RE = /^# akm:task ([\w.@:_-]+) BEGIN$/;
 const BLOCK_END_RE = /^# akm:task ([\w.@:_-]+) END$/;
 export const PORTABLE_CRON_LINE_LIMIT = 1000;
+const CRON_SNAPSHOT = Symbol("akm-cron-binding-snapshot");
 export function CRON_BACKEND(options = {}) {
     const exec = options.exec ?? defaultCronExec();
     const fsLike = options.fs ?? nodeFs();
@@ -48,7 +50,9 @@ export function CRON_BACKEND(options = {}) {
     const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext, envPath ?? ""));
     return {
         name: "cron",
-        install(task, opts) {
+        install(task, opts, expected) {
+            if (expected)
+                assertSchedulerExpectationIdentity(expected, task);
             // Create the log directory before writing the crontab line — cron
             // appends with `>>` and the surrounding shell will fail the entire
             // entry if the parent directory doesn't exist.
@@ -56,77 +60,201 @@ export function CRON_BACKEND(options = {}) {
             assertPortableCronLine(cronLine);
             fsLike.ensureDir(logDir);
             const existing = readCrontab(exec);
-            const block = renderBlock(task.id, cronLine, task.enabled);
-            const next = upsertBlock(existing, task.id, block);
+            const nativeId = schedulerBindingNativeId(task);
+            const blocks = listBlocks(existing);
+            const matching = blocks.filter(({ id }) => schedulerNativeArtifactKey(id) === schedulerNativeArtifactKey(nativeId));
+            const artifacts = matching.map((block) => cronArtifact(block.id, block.body));
+            const priorArtifact = expected
+                ? assertSchedulerNativeArtifactCardinality(artifacts, nativeId, expected.state === "absent" ? 0 : 1)
+                : matching.length > 1
+                    ? assertSchedulerNativeArtifactCardinality(artifacts, nativeId, 1)
+                    : artifacts[0];
+            const prior = priorArtifact ? matching.find((block) => block.id === priorArtifact.nativeId) : undefined;
+            if (expected) {
+                assertSchedulerMutationArtifact(priorArtifact, expected);
+            }
+            else if (prior) {
+                assertSchedulerNativeArtifactOwner(prior.id, task, extractCronInvocation(prior.body)?.invocation);
+            }
+            const block = renderBlock(nativeId, cronLine, task.enabled, task.executionEvidenceDigest);
+            const next = upsertBlock(existing, nativeId, block);
             replaceCrontab(exec, existing, next);
         },
-        uninstall(id) {
+        uninstall(nativeId, expected) {
+            if (expected)
+                assertSchedulerExpectationIdentity({ ...expected, state: "present" });
             const existing = readCrontab(exec);
-            const next = removeBlock(existing, id);
+            const matching = listBlocks(existing).filter(({ id }) => schedulerNativeArtifactKey(id) === schedulerNativeArtifactKey(nativeId));
+            const priorArtifact = expected
+                ? assertSchedulerNativeArtifactCardinality(matching.map((block) => cronArtifact(block.id, block.body)), nativeId, 1)
+                : undefined;
+            const prior = expected
+                ? matching.find((block) => block.id === priorArtifact?.nativeId)
+                : matching.find(({ id }) => id === nativeId);
+            if (!prior)
+                return;
+            if (expected) {
+                assertSchedulerRemovalArtifact(nativeId, expected, extractCronInvocation(prior.body)?.invocation, normalizeSignature(prior.body));
+            }
+            const next = removeBlock(existing, nativeId);
             replaceCrontab(exec, existing, next);
         },
-        setEnabled(id, enabled) {
+        setEnabled(nativeId, enabled) {
             const existing = readCrontab(exec);
-            const next = toggleBlock(existing, id, enabled);
+            const next = toggleBlock(existing, nativeId, enabled);
             replaceCrontab(exec, existing, next);
         },
         list() {
-            const existing = readCrontab(exec);
-            const refs = [];
-            for (const { id, body } of listBlocks(existing)) {
-                const installed = extractCronInvocation(body);
-                // An invocation that no longer parses (e.g. a pre-0.9 `tasks run`
-                // entry surviving the scheduler-ABI respelling, or any other
-                // foreign/malformed line between our markers) is an orphan of its
-                // marker id, not a hard failure: omit it here so `akmTasksSync`
-                // treats the id as "not present" and reinstalls it from the current
-                // task file — going through the normal eligibility/`--rebind` gate
-                // exactly like a fresh install.
-                if (!installed)
-                    continue;
-                refs.push({
-                    id,
-                    signature: normalizeSignature(body),
-                    ...(installed.target !== undefined ? { target: installed.target } : {}),
-                    binding: installed.binding,
-                    contextPath: installed.contextPath,
-                });
-            }
-            return refs;
+            return [...inspectCronState(readCrontab(exec)).installed];
         },
         listForRebind() {
             const existing = readCrontab(exec);
             return listBlocks(existing).map(({ id, body }) => {
                 const installed = extractCronInvocation(body);
-                return {
-                    id,
+                const ref = {
+                    id: installed ? schedulerLogicalBindingId(id, installed.invocation) : id,
                     signature: normalizeSignature(body),
                     ...(installed?.target !== undefined ? { target: installed.target } : {}),
                 };
+                Object.defineProperty(ref, "nativeId", { value: id });
+                if (installed)
+                    Object.defineProperty(ref, "invocation", { value: Object.freeze([...installed.invocation]) });
+                return ref;
             });
         },
+        listNativeArtifacts() {
+            return [...inspectCronState(readCrontab(exec)).artifacts];
+        },
+        inspectBindings() {
+            return inspectCronState(readCrontab(exec));
+        },
+        snapshotBindings(ids) {
+            const crontab = readCrontab(exec);
+            const inspection = inspectCronState(crontab);
+            const keys = new Set(ids.map(schedulerNativeArtifactKey));
+            return Object.freeze({
+                kind: CRON_SNAPSHOT,
+                nativeIds: Object.freeze([...ids]),
+                artifacts: Object.freeze(inspection.artifacts.filter((artifact) => keys.has(schedulerNativeArtifactKey(artifact.nativeId)))),
+                crontab,
+            });
+        },
+        restoreBindings(snapshot, expectedCurrent) {
+            if (!isCronBindingSnapshot(snapshot)) {
+                throw new ConfigError("Invalid cron scheduler snapshot.", "INVALID_CONFIG_FILE");
+            }
+            const existing = readCrontab(exec);
+            const current = inspectCronState(existing);
+            const safeNativeIds = [];
+            const errors = [];
+            if (expectedCurrent) {
+                for (const nativeId of snapshot.nativeIds) {
+                    try {
+                        const expected = expectedCurrent.find((candidate) => candidate.nativeId === nativeId);
+                        if (!expected) {
+                            throw new ConfigError(`Missing cron rollback expectation for ${JSON.stringify(nativeId)}.`, "INVALID_CONFIG_FILE");
+                        }
+                        assertSchedulerRollbackArtifactCardinality(current.artifacts, expected);
+                        safeNativeIds.push(nativeId);
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                }
+            }
+            else {
+                safeNativeIds.push(...snapshot.nativeIds);
+            }
+            const priorBlocks = new Map(listBlocks(snapshot.crontab).map((block) => [block.id, block]));
+            let restored = existing;
+            for (const nativeId of safeNativeIds) {
+                const prior = priorBlocks.get(nativeId);
+                restored = prior
+                    ? upsertBlock(restored, nativeId, [BEGIN(nativeId), prior.body, END(nativeId)].join("\n"))
+                    : removeBlock(restored, nativeId);
+            }
+            if (restored !== existing) {
+                try {
+                    replaceCrontab(exec, existing, restored);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            if (errors.length > 0) {
+                throw new AggregateError(errors, "Cron rollback CAS rejected one or more changed native artifacts.");
+            }
+        },
         expectedSignature(task, opts) {
             const cronLine = buildCronLine(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
             assertPortableCronLine(cronLine);
-            return normalizeSignature(cronBlockBody(cronLine, task.enabled));
+            return normalizeSignature(cronBlockBody(cronLine, task.enabled, task.executionEvidenceDigest));
         },
     };
 }
+function inspectCronState(crontab) {
+    const installed = [];
+    const artifacts = [];
+    for (const { id, body } of listBlocks(crontab)) {
+        const parsed = extractCronInvocation(body);
+        const fingerprint = normalizeSignature(body);
+        const artifact = cronArtifact(id, body);
+        artifacts.push(artifact);
+        if (!parsed)
+            continue;
+        const ref = {
+            id: schedulerLogicalBindingId(id, parsed.invocation),
+            signature: fingerprint,
+            ...(parsed.target !== undefined ? { target: parsed.target } : {}),
+            binding: parsed.binding,
+            contextPath: parsed.contextPath,
+        };
+        Object.defineProperty(ref, "nativeId", { value: id });
+        Object.defineProperty(ref, "invocation", { value: Object.freeze([...parsed.invocation]) });
+        installed.push(ref);
+    }
+    return Object.freeze({ installed: Object.freeze(installed), artifacts: Object.freeze(artifacts) });
+}
+function cronArtifact(nativeId, body) {
+    const parsed = extractCronInvocation(body);
+    const owner = parsed ? schedulerLogicalBindingOwner(nativeId, parsed.invocation) : undefined;
+    const artifact = parsed
+        ? {
+            nativeId,
+            ...(owner !== undefined ? { bindingId: owner } : {}),
+            invocation: Object.freeze([...parsed.invocation]),
+        }
+        : { nativeId };
+    Object.defineProperty(artifact, "fingerprint", { value: normalizeSignature(body) });
+    return artifact;
+}
+function isCronBindingSnapshot(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.kind === CRON_SNAPSHOT &&
+        typeof value.crontab === "string");
+}
 // ── helpers (exported for tests) ────────────────────────────────────────────
-export function buildCronLine(task, akmArgv, logDir, contextPath, target) {
-    const spec = parseSchedule(task.schedule, "cron");
+export function buildCronLine(task, akmArgv, logDir, contextPath, _target) {
+    const spec = parseSchedule(task.cron, "cron");
     const cronExpr = translateToCron(spec);
-    const logPath = path.join(logDir, `${task.id}.log`);
-    const invocation = buildScheduledTaskInvocation(akmArgv, task.id, contextPath, target);
+    const logPath = path.join(logDir, `${schedulerBindingNativeId(task)}.log`);
+    const invocation = buildScheduledBindingInvocation(akmArgv, contextPath, task.invocation);
     const cmd = invocation.argv.map((part) => quoteForCron(part)).join(" ");
     return `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
 }
 /** The crontab line as it appears inside a block — commented when disabled. */
-export function cronBlockBody(cronLine, enabled) {
-    return enabled ? cronLine : `${DISABLED_PREFIX}${cronLine}`;
+export function cronBlockBody(cronLine, enabled, executionEvidenceDigest) {
+    const lines = [
+        cronLine,
+        ...(executionEvidenceDigest === undefined
+            ? []
+            : [`# akm:workflow-evidence ${assertSchedulerExecutionEvidenceDigest(executionEvidenceDigest)}`]),
+    ];
+    return (enabled ? lines : lines.map((line) => `${DISABLED_PREFIX}${line}`)).join("\n");
 }
-export function renderBlock(id, cronLine, enabled) {
-    return [BEGIN(id), cronBlockBody(cronLine, enabled), END(id)].join("\n");
+export function renderBlock(id, cronLine, enabled, executionEvidenceDigest) {
+    return [BEGIN(id), cronBlockBody(cronLine, enabled, executionEvidenceDigest), END(id)].join("\n");
 }
 /**
  * Parse the akm-owned blocks out of a crontab, returning each task id with the
@@ -195,7 +323,7 @@ export function extractCronInvocation(body) {
     const redirectIndex = fields.indexOf(">>", commandStart);
     if (redirectIndex === -1)
         return undefined;
-    return parseScheduledTaskArgv(fields.slice(commandStart, redirectIndex));
+    return parseScheduledBindingArgv(fields.slice(commandStart, redirectIndex));
 }
 /** Reverse {@link quoteForCron} for a single whitespace-free token. */
 function splitCronShellWords(value) {

package/dist/tasks/backends/index.js

@@ -5,7 +5,7 @@ import { CRON_BACKEND } from "./cron.js";
 import { LAUNCHD_BACKEND } from "./launchd.js";
 import { SCHTASKS_BACKEND } from "./schtasks.js";
 // WI-9.10e: the former `_setBackendsForTests` module-mutation seam was retired.
-// Tests inject a fake `TaskBackend` directly via the `deps.backend` parameter
+// Tests inject a fake `SchedulerBackend` directly via the `deps.backend` parameter
 // the `akm task` mutation entries already accept (the backend carries its own
 // `name`), so no module-level override binding is needed. `selectBackend`'s
 // `options.platform` covers the platform-steering the seam's second override