cairn-ai 0.2.6 → 0.2.7

package/scripts/cairn-lifecycle-transaction-journal.mjs

@@ -0,0 +1,210 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { cairnConfigProjection, readSharedConfigSnapshot, removeCairnConfig } from "./cairn-lifecycle-config.mjs";
+
+export function createTransactionJournal(context) {
+  const {
+    marketplaceRoot, ownershipPath, pluginName, releaseVersion, transactionPath,
+    transactionRoot, expectedManagedTarget, targetDigest,
+  } = context;
+async function createTransaction() {
+  const id = randomUUID();
+  const root = join(transactionRoot, id);
+  const transaction = {
+    schemaVersion: 1,
+    id,
+    state: "active",
+    root,
+    stageRoot: join(root, "stage"),
+    backupRoot: join(root, "backup"),
+    entries: [],
+  };
+  await mkdir(transaction.backupRoot, { recursive: true });
+  await writeTransactionJournal(transaction);
+  return transaction;
+}
+
+async function rollback(transaction) {
+  await rollbackEntries(transaction);
+  await rm(transaction.root, { recursive: true, force: true });
+  await rm(transactionPath, { force: true });
+}
+
+async function finishTransaction(transaction) {
+  transaction.state = "committed";
+  try {
+    await writeTransactionJournal(transaction);
+  } catch (error) {
+    transaction.state = "active";
+    throw error;
+  }
+  await rm(transaction.root, { recursive: true, force: true });
+  await rm(transactionPath, { force: true });
+}
+
+async function writeTransactionJournal(transaction) {
+  const durable = {
+    schemaVersion: transaction.schemaVersion,
+    id: transaction.id,
+    state: transaction.state,
+    entries: transaction.entries,
+  };
+  await durableReplaceFile(transactionPath, `${JSON.stringify(durable, null, 2)}\n`, transaction.id);
+}
+
+async function durableReplaceFile(path, content, nonce = randomUUID()) {
+  await mkdir(dirname(path), { recursive: true });
+  const candidate = `${path}.${nonce}.tmp`;
+  const file = await open(candidate, "w", 0o600);
+  try {
+    await file.writeFile(content, "utf8");
+    await file.sync();
+  } finally {
+    await file.close();
+  }
+  await rename(candidate, path);
+  // Directory fsync is unavailable on some Windows/filesystem combinations. The
+  // file fsync+atomic rename remains the portable floor; directory sync is best effort.
+  try {
+    const directory = await open(dirname(path), "r");
+    try { await directory.sync(); } finally { await directory.close(); }
+  } catch (error) {
+    if (!(["EINVAL", "ENOTSUP", "EISDIR", "EPERM", "EACCES"].includes(error?.code))) throw error;
+  }
+}
+
+async function recoverInterruptedTransaction() {
+  if (!(await exists(transactionPath))) return;
+  let journal;
+  try {
+    journal = JSON.parse(await readFile(transactionPath, "utf8"));
+  } catch {
+    throw new Error(`Lifecycle transaction journal is invalid: ${transactionPath}`);
+  }
+  validateTransactionJournal(journal, { strict: true });
+  if (journal.state === "committed") {
+    await rm(join(transactionRoot, journal.id), { recursive: true, force: true });
+    await rm(transactionPath, { force: true });
+    return;
+  }
+  await rollbackEntries(journal);
+  await rm(join(transactionRoot, journal.id), { recursive: true, force: true });
+  await rm(transactionPath, { force: true });
+}
+
+function validateTransactionJournal(journal, { strict = false } = {}) {
+  if (journal?.schemaVersion !== 1 || typeof journal.id !== "string" || !/^[a-f0-9-]{20,}$/i.test(journal.id)
+      || !["active", "committed"].includes(journal.state) || !Array.isArray(journal.entries)) {
+    throw new Error("Lifecycle transaction journal has an invalid schema.");
+  }
+  if (strict && !sameKeys(journal, ["schemaVersion", "id", "state", "entries"])) throw new Error("Lifecycle transaction journal has unknown fields.");
+  const allowedBackupRoot = resolve(transactionRoot, journal.id, "backup");
+  const ids = new Set();
+  const paths = new Set();
+  for (const entry of journal.entries) {
+    const expected = entry.id === "ownership"
+      ? { phase: "manifest", path: ownershipPath, type: "file" }
+      : entry.id === "previous-codex-runtime"
+        ? previousRuntimeTarget(entry.path)
+      : expectedManagedTarget(entry.id);
+    if (!expected || expected.path !== entry.path || expected.phase !== entry.phase || expected.type !== entry.type
+        || !["prepared", "applied"].includes(entry.status)
+        || !["replace", "remove"].includes(entry.operation)
+        || typeof entry.existed !== "boolean"
+        || !isInside(allowedBackupRoot, entry.backup)
+        || typeof entry.expectedNewDigest !== "string" || typeof entry.previousDigest !== "string") {
+      throw new Error(`Lifecycle transaction journal contains an unsafe entry: ${entry?.id ?? "unknown"}`);
+    }
+    if (strict && !sameKeys(entry, ["id", "phase", "path", "type", "backup", "existed", "previousDigest", "expectedNewDigest", "operation", "status"])) {
+      throw new Error(`Lifecycle transaction journal entry has unknown fields: ${entry.id}`);
+    }
+    if (ids.has(entry.id) || paths.has(entry.path)) throw new Error(`Lifecycle transaction journal contains duplicate targets: ${entry.id}`);
+    if (entry.operation === "remove" && entry.expectedNewDigest !== "missing") throw new Error(`Lifecycle remove entry has an invalid new digest: ${entry.id}`);
+    ids.add(entry.id);
+    paths.add(entry.path);
+  }
+}
+
+function previousRuntimeTarget(path) {
+  const parent = join(marketplaceRoot, pluginName);
+  const relation = relative(parent, resolve(path));
+  if (!relation || relation.includes(sep) || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(relation) || relation === releaseVersion) return null;
+  return { phase: "cleanup", path: join(parent, relation), type: "tree" };
+}
+
+function sameKeys(value, expected) {
+  return Object.keys(value).sort().join("\0") === [...expected].sort().join("\0");
+}
+
+async function rollbackEntries(transaction) {
+  validateTransactionJournal(transaction);
+  for (const entry of [...transaction.entries].reverse()) {
+    const destinationExists = await exists(entry.path);
+    const backupExists = await exists(entry.backup);
+    if (backupExists) {
+      if (entry.type === "config" && entry.status === "prepared") {
+        const previousConfig = (await readSharedConfigSnapshot(entry.backup)).text;
+        if (destinationExists) {
+          const currentConfig = (await readSharedConfigSnapshot(entry.path)).text;
+          await writeFile(entry.path, `${removeCairnConfig(currentConfig)}${cairnConfigProjection(previousConfig)}`);
+          await rm(entry.backup, { force: true });
+        } else {
+          await mkdir(dirname(entry.path), { recursive: true });
+          await rename(entry.backup, entry.path);
+        }
+        continue;
+      }
+      if (!entry.existed) throw new Error(`Cannot recover transaction because an unexpected backup exists: ${entry.path}`);
+      if (await targetDigest(entry.backup, entry.type) !== entry.previousDigest) {
+        throw new Error(`Cannot recover transaction because its durable backup changed: ${entry.path}`);
+      }
+      if (destinationExists) {
+        const current = await targetDigest(entry.path, entry.type);
+        if (current !== entry.expectedNewDigest) throw new Error(`Cannot recover transaction because destination changed: ${entry.path}`);
+        if (entry.type === "config") {
+          const currentConfig = (await readSharedConfigSnapshot(entry.path)).text;
+          const previousConfig = (await readSharedConfigSnapshot(entry.backup)).text;
+          await writeFile(entry.path, `${removeCairnConfig(currentConfig)}${cairnConfigProjection(previousConfig)}`);
+          await rm(entry.backup, { force: true });
+          continue;
+        }
+        await rm(entry.path, { recursive: true, force: true });
+      }
+      await mkdir(dirname(entry.path), { recursive: true });
+      await rename(entry.backup, entry.path);
+    } else if (entry.status === "prepared") {
+      continue;
+    } else if (!entry.existed) {
+      if (destinationExists) {
+        const current = await targetDigest(entry.path, entry.type);
+        if (current !== entry.expectedNewDigest) throw new Error(`Cannot recover new transaction target because it changed: ${entry.path}`);
+        if (entry.type === "config") {
+          const preserved = removeCairnConfig((await readSharedConfigSnapshot(entry.path)).text);
+          if (preserved.length > 0) await writeFile(entry.path, preserved);
+          else await rm(entry.path, { force: true });
+        } else await rm(entry.path, { recursive: true, force: true });
+      }
+    } else {
+      if (!destinationExists || await targetDigest(entry.path, entry.type) !== entry.previousDigest) {
+        throw new Error(`Cannot recover transaction because its durable backup is missing: ${entry.path}`);
+      }
+    }
+  }
+}
+
+  return {
+    createTransaction, finishTransaction, recoverInterruptedTransaction, rollback,
+    writeTransactionJournal,
+  };
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+
+  function isInside(root, candidate) {
+    const path = resolve(candidate);
+    return path === root || path.startsWith(`${root}${sep}`);
+  }
+}

package/scripts/cairn-lifecycle-transaction-targets.mjs

@@ -0,0 +1,119 @@
+import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { cairnConfigProjection, readSharedConfigSnapshot, removeCairnConfig } from "./cairn-lifecycle-config.mjs";
+
+export function createTransactionTargets(context) {
+  const { targetDigest, writeTransactionJournal } = context;
+async function replaceTarget(target, transaction) {
+  let configProjection = null;
+  if (target.type === "config") {
+    const snapshot = await readSharedConfigSnapshot(target.path);
+    configProjection = cairnConfigProjection((await readSharedConfigSnapshot(target.staged)).text);
+    if (snapshot.digest !== target.configSourceDigest) {
+      await writeFile(target.staged, `${removeCairnConfig(snapshot.text)}${configProjection}`);
+      target.configSourceDigest = snapshot.digest;
+    }
+  }
+  const existed = await exists(target.path);
+  const backup = join(transaction.backupRoot, String(transaction.entries.length));
+  await mkdir(dirname(backup), { recursive: true });
+  const entry = {
+    id: target.id,
+    phase: target.phase,
+    path: target.path,
+    type: target.type,
+    backup,
+    existed,
+    previousDigest: existed ? await targetDigest(target.path, target.type) : "missing",
+    expectedNewDigest: await targetDigest(target.staged, target.type),
+    operation: "replace",
+    status: "prepared",
+  };
+  transaction.entries.push(entry);
+  await writeTransactionJournal(transaction);
+  if (process.env.CAIRN_TEST_MUTATE_AFTER_PREFLIGHT_ID === target.id) {
+    await writeFile(target.path, process.env.CAIRN_TEST_MUTATION_CONTENT ?? "concurrent mutation\n");
+  }
+  if (target.type !== "config" && target.preflightDigest !== undefined
+      && await targetDigest(target.path, target.type) !== target.preflightDigest) {
+    throw new Error(`Managed artifact changed after lifecycle preflight: ${target.path}`);
+  }
+  if (target.type === "config" && process.env.CAIRN_TEST_APPEND_CONFIG_BEFORE_REPLACE) {
+    const snapshot = await readSharedConfigSnapshot(target.path);
+    await writeFile(target.path, `${snapshot.text}${process.env.CAIRN_TEST_APPEND_CONFIG_BEFORE_REPLACE}`);
+  }
+  if (target.type === "config" && process.env.CAIRN_TEST_REMOVE_CONFIG_BEFORE_REPLACE === "1") {
+    await rm(target.path, { force: true });
+  }
+  if (target.type === "config") {
+    let capturedExists = true;
+    try {
+      await renameLifecycleTarget(target.path, backup, target.id);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      capturedExists = false;
+    }
+    if (process.env.CAIRN_TEST_CRASH_AFTER_CONFIG_CAPTURE === "1") process.exit(86);
+    const captured = await readSharedConfigSnapshot(backup);
+    if (capturedExists) await writeFile(target.staged, `${removeCairnConfig(captured.text)}${configProjection}`);
+    else await writeFile(target.staged, configProjection);
+    entry.existed = capturedExists;
+    entry.previousDigest = capturedExists ? await targetDigest(backup, target.type) : "missing";
+    entry.expectedNewDigest = await targetDigest(target.staged, target.type);
+    await writeTransactionJournal(transaction);
+  } else if (existed) await renameLifecycleTarget(target.path, backup, target.id);
+  await mkdir(dirname(target.path), { recursive: true });
+  await renameStagedLifecycleTarget(target.staged, target.path, target.id);
+  entry.status = "applied";
+  await writeTransactionJournal(transaction);
+}
+
+async function renameStagedLifecycleTarget(source, destination, targetId) {
+  if (process.env.CAIRN_TEST_FORCE_EXDEV_ID === targetId) {
+    throw new Error(`Cross-device replacement is not supported safely for lifecycle target: ${targetId}`);
+  }
+  await renameLifecycleTarget(source, destination, targetId);
+}
+
+async function renameLifecycleTarget(source, destination, targetId) {
+  try {
+    await rename(source, destination);
+  } catch (error) {
+    if (error?.code === "EXDEV") {
+      throw new Error(`Cross-device replacement is not supported safely for lifecycle target: ${targetId}`);
+    }
+    throw error;
+  }
+}
+
+async function removeManagedTarget(target, transaction) {
+  if (!(await exists(target.path))) throw new Error(`Managed uninstall target is missing: ${target.path}`);
+  const backup = join(transaction.backupRoot, String(transaction.entries.length));
+  await mkdir(dirname(backup), { recursive: true });
+  const entry = {
+    id: target.id,
+    phase: target.phase,
+    path: target.path,
+    type: target.type,
+    backup,
+    existed: true,
+    previousDigest: await targetDigest(target.path, target.type),
+    expectedNewDigest: "missing",
+    operation: "remove",
+    status: "prepared",
+  };
+  transaction.entries.push(entry);
+  await writeTransactionJournal(transaction);
+  await renameLifecycleTarget(target.path, backup, target.id);
+  entry.status = "applied";
+  await writeTransactionJournal(transaction);
+}
+
+
+  return { removeManagedTarget, replaceTarget };
+
+  async function exists(path) {
+    try { await lstat(path); return true; }
+    catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  }
+}

package/scripts/cairn-lifecycle-transaction.mjs

@@ -0,0 +1,12 @@
+import { createLifecycleLock, DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS } from "./cairn-lifecycle-lock.mjs";
+import { createTransactionJournal } from "./cairn-lifecycle-transaction-journal.mjs";
+import { createTransactionTargets } from "./cairn-lifecycle-transaction-targets.mjs";
+
+export { DEFAULT_LIFECYCLE_LOCK_TIMEOUT_MS };
+
+export function createTransactionManager(context) {
+  const lock = createLifecycleLock(context);
+  const journal = createTransactionJournal(context);
+  const targets = createTransactionTargets({ ...context, writeTransactionJournal: journal.writeTransactionJournal });
+  return { ...journal, ...lock, ...targets };
+}