@rover-studio/answer-me 0.1.0-rc.1

package/lib/npm-cli/main.mjs

@@ -0,0 +1,42 @@
+import { runCommand } from './commands.mjs';
+
+function parseArguments(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return null;
+  const command = argv[0];
+  if (!['install', 'update', 'uninstall', 'doctor'].includes(command)) return null;
+  const options = { json: false, interactive: false };
+  for (const argument of argv.slice(1)) {
+    if (argument === '--json') options.json = true;
+    else if (argument === '--interactive' && command === 'doctor') options.interactive = true;
+    else return null;
+  }
+  return { command, options };
+}
+
+function humanSummary(result) {
+  const usage = result.usageValidation.status === 'not-run'
+    ? 'usageValidation=not-run'
+    : `usageValidation=${result.usageValidation.status}`;
+  const code = result.installation.code ? `; code=${result.installation.code}` : '';
+  const location = result.installation.directory ? `\nDirectory: ${result.installation.directory}` : '';
+  const issue = result.usageValidation.status === 'issue'
+    ? '\nInstallation is retained. Usage validation is incomplete; retry only when requested with: answerme-toolkit doctor --interactive'
+    : '';
+  const warning = result.usageValidation.cleanupWarning
+    ? '\nWarning: temporary validation data could not be cleaned up; installation is retained.'
+    : '';
+  const limitations = result.limitations?.length ? `\nLimitations: ${result.limitations.join(', ')}` : '';
+  return `AnswerMe Toolkit ${result.version}: installation=${result.installation.status}${code}; ${usage}; rollback=${result.rollback.status}${location}${issue}${warning}${limitations}`;
+}
+
+export async function runCli({ argv, write = (value) => process.stdout.write(value), dependencies = {} } = {}) {
+  const parsed = parseArguments(argv);
+  const jsonOnly = parsed?.options.json === true || (Array.isArray(argv) && argv.includes('--json'));
+  const outcome = parsed
+    ? await runCommand(parsed.command, parsed.options, dependencies)
+    : await runCommand('invalid', {}, dependencies);
+  write(jsonOnly ? `${JSON.stringify(outcome.result)}\n` : `${humanSummary(outcome.result)}\n`);
+  return outcome.exitCode;
+}
+
+export const __test = Object.freeze({ parseArguments, humanSummary });

package/lib/npm-cli/package-integrity.mjs

@@ -0,0 +1,212 @@
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  INSTALL_LEDGER,
+  MANAGED_SKILLS,
+  PACKAGE_NAME,
+  PACKAGE_VERSION,
+} from './constants.mjs';
+import { InstallerError } from './errors.mjs';
+import {
+  assertPlainExisting,
+  readJsonFile,
+  sha256,
+  snapshotPath,
+  snapshotsEqual,
+} from './filesystem.mjs';
+
+const MODULE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const SHA256 = /^[0-9a-f]{64}$/;
+const SAFE_RELATIVE = /^(?![./])(?!.+\/\.\.?\/)[A-Za-z0-9._/-]+$/;
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, keys) {
+  return isRecord(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+export function isValidManagedSnapshot(value) {
+  if (!exactKeys(value, ['exists', 'kind', 'entries'])
+    || value.exists !== true
+    || value.kind !== 'directory'
+    || !Array.isArray(value.entries)) return false;
+  let previous = null;
+  for (const entry of value.entries) {
+    if (!isRecord(entry) || typeof entry.path !== 'string' || !SAFE_RELATIVE.test(entry.path)) return false;
+    if (previous !== null && previous.localeCompare(entry.path, 'en') >= 0) return false;
+    previous = entry.path;
+    if (entry.type === 'directory') {
+      if (!exactKeys(entry, ['path', 'type'])) return false;
+    } else if (entry.type === 'file') {
+      if (!exactKeys(entry, ['path', 'type', 'size', 'sha256'])
+        || !Number.isSafeInteger(entry.size) || entry.size < 0 || !SHA256.test(entry.sha256)) return false;
+    } else return false;
+  }
+  return value.entries.some((entry) => entry.path.toLowerCase() === 'skill.md' && entry.type === 'file');
+}
+
+async function enumerateFiles(root, current = root, output = []) {
+  await assertPlainExisting(current, 'directory');
+  const entries = await readdir(current, { withFileTypes: true });
+  entries.sort((a, b) => a.name.localeCompare(b.name, 'en'));
+  for (const entry of entries) {
+    const absolute = path.join(current, entry.name);
+    if (entry.isDirectory()) await enumerateFiles(root, absolute, output);
+    else if (entry.isFile()) output.push(path.relative(root, absolute).replaceAll('\\', '/'));
+    else throw new InstallerError('package-integrity-invalid');
+  }
+  return output;
+}
+
+function validateMigrationManifest(value) {
+  if (!exactKeys(value, ['schemaVersion', 'profiles']) || value.schemaVersion !== 1 || !Array.isArray(value.profiles)) {
+    throw new InstallerError('package-integrity-invalid');
+  }
+  const allowed = new Set(['0.3.0', '0.4.0', '0.4.1']);
+  if (value.profiles.length !== allowed.size) throw new InstallerError('package-integrity-invalid');
+  for (const profile of value.profiles) {
+    if (!exactKeys(profile, ['version', 'archiveSha256', 'skills'])
+      || !allowed.delete(profile.version)
+      || !SHA256.test(profile.archiveSha256)
+      || !exactKeys(profile.skills, MANAGED_SKILLS)
+      || !MANAGED_SKILLS.every((name) => isValidManagedSnapshot(profile.skills[name]))) {
+      throw new InstallerError('package-integrity-invalid');
+    }
+  }
+  return value;
+}
+
+export async function verifyPackageIntegrity({ packageRoot = MODULE_ROOT } = {}) {
+  await assertPlainExisting(packageRoot, 'directory');
+  const packageJson = await readJsonFile(path.join(packageRoot, 'package.json'));
+  if (!isRecord(packageJson)
+    || packageJson.name !== PACKAGE_NAME
+    || packageJson.version !== PACKAGE_VERSION
+    || packageJson.engines?.node !== '>=20') {
+    throw new InstallerError('package-integrity-invalid');
+  }
+  const manifestPath = path.join(packageRoot, 'distribution', 'npm', 'package-manifest.json');
+  const manifest = await readJsonFile(manifestPath);
+  if (!exactKeys(manifest, ['schemaVersion', 'packageName', 'packageVersion', 'files'])
+    || manifest.schemaVersion !== 1
+    || manifest.packageName !== PACKAGE_NAME
+    || manifest.packageVersion !== PACKAGE_VERSION
+    || !Array.isArray(manifest.files)) {
+    throw new InstallerError('package-integrity-invalid');
+  }
+
+  const roots = [
+    path.join(packageRoot, 'bin'),
+    path.join(packageRoot, 'lib', 'npm-cli'),
+    path.join(packageRoot, 'distribution', 'npm'),
+  ];
+  const observedPaths = [];
+  for (const root of roots) observedPaths.push(...await enumerateFiles(packageRoot, root));
+  const manifestRelative = 'distribution/npm/package-manifest.json';
+  const manifestIndex = observedPaths.indexOf(manifestRelative);
+  if (manifestIndex < 0) throw new InstallerError('package-integrity-invalid');
+  observedPaths.splice(manifestIndex, 1);
+  observedPaths.sort((a, b) => a.localeCompare(b, 'en'));
+
+  const manifestPaths = [];
+  for (const entry of manifest.files) {
+    if (!exactKeys(entry, ['path', 'size', 'sha256'])
+      || typeof entry.path !== 'string'
+      || !SAFE_RELATIVE.test(entry.path)
+      || !Number.isSafeInteger(entry.size)
+      || entry.size < 0
+      || !SHA256.test(entry.sha256)) {
+      throw new InstallerError('package-integrity-invalid');
+    }
+    manifestPaths.push(entry.path);
+  }
+  if (JSON.stringify(manifestPaths) !== JSON.stringify(observedPaths)) {
+    throw new InstallerError('package-integrity-invalid');
+  }
+  for (const entry of manifest.files) {
+    const absolute = path.resolve(packageRoot, ...entry.path.split('/'));
+    if (!absolute.startsWith(`${path.resolve(packageRoot)}${path.sep}`)) throw new InstallerError('package-integrity-invalid');
+    await assertPlainExisting(absolute, 'file');
+    const bytes = await readFile(absolute);
+    if (bytes.length !== entry.size || sha256(bytes) !== entry.sha256) {
+      throw new InstallerError('package-integrity-invalid');
+    }
+  }
+
+  const skillsSource = path.join(packageRoot, 'distribution', 'npm', 'skills');
+  const desiredSkills = {};
+  for (const name of MANAGED_SKILLS) {
+    desiredSkills[name] = await snapshotPath(path.join(skillsSource, name), 'directory');
+    if (!isValidManagedSnapshot(desiredSkills[name])) throw new InstallerError('package-integrity-invalid');
+  }
+  const migrations = validateMigrationManifest(
+    await readJsonFile(path.join(packageRoot, 'distribution', 'npm', 'migrations.json')),
+  );
+  return { packageRoot, skillsSource, desiredSkills, migrations };
+}
+
+function validateLedger(value) {
+  if (!exactKeys(value, ['schemaVersion', 'packageName', 'packageVersion', 'skills'])
+    || value.schemaVersion !== 1
+    || value.packageName !== PACKAGE_NAME
+    || typeof value.packageVersion !== 'string'
+    || !exactKeys(value.skills, MANAGED_SKILLS)
+    || !MANAGED_SKILLS.every((name) => isValidManagedSnapshot(value.skills[name]))) return false;
+  return true;
+}
+
+export function createInstallLedger(desiredSkills) {
+  return {
+    schemaVersion: 1,
+    packageName: PACKAGE_NAME,
+    packageVersion: PACKAGE_VERSION,
+    skills: structuredClone(desiredSkills),
+  };
+}
+
+export async function classifyInstallation(skillsRoot, packageInfo) {
+  const observed = {};
+  for (const name of MANAGED_SKILLS) observed[name] = await snapshotPath(path.join(skillsRoot, name), 'directory');
+  const ledgerPath = path.join(skillsRoot, INSTALL_LEDGER);
+  const ledgerSnapshot = await snapshotPath(ledgerPath, 'file');
+  let ledger = null;
+  if (ledgerSnapshot.exists) {
+    try {
+      ledger = await readJsonFile(ledgerPath);
+    } catch {
+      throw new InstallerError('unknown-existing-files');
+    }
+    if (!validateLedger(ledger)) throw new InstallerError('unknown-existing-files');
+  }
+  const allAbsent = MANAGED_SKILLS.every((name) => observed[name].exists === false);
+  if (allAbsent && !ledger) return { kind: 'absent', observed, ledgerSnapshot };
+  if (allAbsent) throw new InstallerError('unknown-existing-files');
+
+  const exactDesired = MANAGED_SKILLS.every((name) => snapshotsEqual(observed[name], packageInfo.desiredSkills[name]));
+  if (exactDesired && !ledger) return { kind: 'current-unowned', observed, ledgerSnapshot };
+  if (ledger) {
+    const exactLedger = MANAGED_SKILLS.every((name) => snapshotsEqual(observed[name], ledger.skills[name]));
+    if (!exactLedger) throw new InstallerError('unknown-existing-files');
+    if (exactDesired && ledger.packageVersion === PACKAGE_VERSION) {
+      return { kind: 'current', observed, ledgerSnapshot, ledger };
+    }
+  }
+
+  for (const profile of packageInfo.migrations.profiles) {
+    if (MANAGED_SKILLS.every((name) => snapshotsEqual(observed[name], profile.skills[name]))) {
+      if (ledger && !MANAGED_SKILLS.every((name) => snapshotsEqual(ledger.skills[name], profile.skills[name]))) {
+        throw new InstallerError('unknown-existing-files');
+      }
+      return { kind: 'legacy', legacyVersion: profile.version, observed, ledgerSnapshot, ledger };
+    }
+  }
+  if (ledger) throw new InstallerError('untrusted-legacy-installation');
+  throw new InstallerError('unknown-existing-files');
+}
+
+export const __test = Object.freeze({ validateSnapshot: isValidManagedSnapshot, validateMigrationManifest, validateLedger });

package/lib/npm-cli/transaction.mjs

@@ -0,0 +1,375 @@
+import { randomUUID } from 'node:crypto';
+import {
+  mkdir,
+  readdir,
+  rename,
+  rm,
+  rmdir,
+} from 'node:fs/promises';
+import path from 'node:path';
+import {
+  INSTALL_LEDGER,
+  JOURNAL_FILE,
+  JOURNAL_SCHEMA_VERSION,
+  MANAGED_SKILLS,
+  PACKAGE_VERSION,
+  TRANSACTION_DIRECTORY,
+} from './constants.mjs';
+import { InstallerError } from './errors.mjs';
+import {
+  assertPlainExisting,
+  atomicWriteJson,
+  copyPlainTree,
+  normalizePath,
+  pathExists,
+  readJsonFile,
+  removeVerified,
+  snapshotPath,
+  snapshotsEqual,
+} from './filesystem.mjs';
+import { createInstallLedger, isValidManagedSnapshot } from './package-integrity.mjs';
+
+const TRANSACTION_ID = /^[0-9a-f-]{36}$/;
+const ENTRY_NAMES = Object.freeze([...MANAGED_SKILLS, INSTALL_LEDGER]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, keys) {
+  return isRecord(value)
+    && Object.keys(value).length === keys.length
+    && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function kindFor(name) {
+  return name === INSTALL_LEDGER ? 'file' : 'directory';
+}
+
+function locations(codexHome) {
+  const transactionRoot = path.join(codexHome, TRANSACTION_DIRECTORY);
+  return {
+    transactionRoot,
+    journalPath: path.join(transactionRoot, JOURNAL_FILE),
+    stageRoot: path.join(transactionRoot, 'stage'),
+    backupRoot: path.join(transactionRoot, 'backup'),
+  };
+}
+
+function targetPath(skillsRoot, name) {
+  return path.join(skillsRoot, name);
+}
+
+async function snapshotEntries(skillsRoot) {
+  const result = {};
+  for (const name of ENTRY_NAMES) result[name] = await snapshotPath(targetPath(skillsRoot, name), kindFor(name));
+  return result;
+}
+
+function entrySnapshotsEqual(left, right) {
+  return ENTRY_NAMES.every((name) => snapshotsEqual(left[name], right[name]));
+}
+
+function validateJournal(value, binding) {
+  const fields = [
+    'schemaVersion', 'transactionId', 'operation', 'phase', 'packageVersion', 'codexHome', 'skillsRoot',
+    'skillsRootExisted', 'originals', 'desired', 'moved', 'installed',
+  ];
+  if (!exactKeys(value, fields)
+    || value.schemaVersion !== JOURNAL_SCHEMA_VERSION
+    || !TRANSACTION_ID.test(value.transactionId)
+    || !['install', 'update', 'uninstall'].includes(value.operation)
+    || !['prepared', 'committing', 'verifying', 'committed', 'rolling-back', 'rolled-back'].includes(value.phase)
+    || value.packageVersion !== PACKAGE_VERSION
+    || normalizePath(value.codexHome) !== normalizePath(binding.codexHome)
+    || normalizePath(value.skillsRoot) !== normalizePath(binding.skillsRoot)
+    || typeof value.skillsRootExisted !== 'boolean'
+    || !exactKeys(value.originals, ENTRY_NAMES)
+    || !exactKeys(value.desired, ENTRY_NAMES)
+    || !Array.isArray(value.moved)
+    || !Array.isArray(value.installed)
+    || value.moved.some((name) => !ENTRY_NAMES.includes(name))
+    || value.installed.some((name) => !ENTRY_NAMES.includes(name))
+    || new Set(value.moved).size !== value.moved.length
+    || new Set(value.installed).size !== value.installed.length) {
+    throw new InstallerError('recovery-required', { recoveryRequired: true });
+  }
+  for (const name of ENTRY_NAMES) {
+    const original = value.originals[name];
+    const desired = value.desired[name];
+    const valid = name === INSTALL_LEDGER
+      ? [original, desired].every((snapshot) => exactKeys(snapshot, ['exists', 'kind', 'entries'])
+        && snapshot.kind === 'file'
+        && typeof snapshot.exists === 'boolean'
+        && Array.isArray(snapshot.entries)
+        && ((!snapshot.exists && snapshot.entries.length === 0)
+          || (snapshot.exists && snapshot.entries.length === 1
+            && snapshot.entries[0]?.path === '.'
+            && snapshot.entries[0]?.type === 'file'
+            && Number.isSafeInteger(snapshot.entries[0]?.size)
+            && /^[0-9a-f]{64}$/.test(snapshot.entries[0]?.sha256 ?? ''))))
+      : [original, desired].every((snapshot) => (
+        (!snapshot?.exists && exactKeys(snapshot, ['exists', 'kind', 'entries'])
+          && snapshot.kind === 'directory' && snapshot.entries.length === 0)
+        || isValidManagedSnapshot(snapshot)
+      ));
+    if (!valid) {
+      throw new InstallerError('recovery-required', { recoveryRequired: true });
+    }
+  }
+  return value;
+}
+
+async function persistJournal(state) {
+  await atomicWriteJson(state.journalPath, {
+    schemaVersion: JOURNAL_SCHEMA_VERSION,
+    transactionId: state.transactionId,
+    operation: state.operation,
+    phase: state.phase,
+    packageVersion: PACKAGE_VERSION,
+    codexHome: state.codexHome,
+    skillsRoot: state.skillsRoot,
+    skillsRootExisted: state.skillsRootExisted,
+    originals: state.originals,
+    desired: state.desired,
+    moved: state.moved,
+    installed: state.installed,
+  });
+}
+
+async function runHook(hooks, name, context) {
+  if (typeof hooks?.[name] === 'function') await hooks[name](context);
+}
+
+async function verifyDesired(state) {
+  const observed = await snapshotEntries(state.skillsRoot);
+  return entrySnapshotsEqual(observed, state.desired);
+}
+
+async function verifyOriginals(state) {
+  const observed = await snapshotEntries(state.skillsRoot);
+  return entrySnapshotsEqual(observed, state.originals);
+}
+
+async function restoreOne(state, name) {
+  const original = state.originals[name];
+  const desired = state.desired[name];
+  const target = targetPath(state.skillsRoot, name);
+  const backup = path.join(state.backupRoot, name);
+  const observed = await snapshotPath(target, kindFor(name));
+  const backupObserved = await snapshotPath(backup, kindFor(name));
+
+  if (original.exists) {
+    if (snapshotsEqual(observed, original)) return true;
+    if (!snapshotsEqual(backupObserved, original)) return false;
+    if (observed.exists) {
+      if (!snapshotsEqual(observed, desired)) return false;
+      await removeVerified(target, desired);
+    }
+    await rename(backup, target);
+    return snapshotsEqual(await snapshotPath(target, kindFor(name)), original);
+  }
+
+  if (!observed.exists) return true;
+  if (!snapshotsEqual(observed, desired)) return false;
+  await removeVerified(target, desired);
+  return !(await pathExists(target));
+}
+
+async function rollback(state, hooks = {}) {
+  state.phase = 'rolling-back';
+  await persistJournal(state).catch(() => {});
+  await runHook(hooks, 'beforeRollback', state);
+  for (const name of [...ENTRY_NAMES].reverse()) {
+    if (!(await restoreOne(state, name))) return false;
+  }
+  if (!(await verifyOriginals(state))) return false;
+  if (!state.skillsRootExisted) {
+    const children = await readdir(state.skillsRoot).catch(() => null);
+    if (children?.length === 0) await rmdir(state.skillsRoot);
+  }
+  state.phase = 'rolled-back';
+  await persistJournal(state).catch(() => {});
+  await runHook(hooks, 'afterRollback', state);
+  return true;
+}
+
+async function cleanupTransaction(transactionRoot) {
+  await rm(transactionRoot, { recursive: true, force: false });
+}
+
+async function stateFromJournal(binding, journal) {
+  const roots = locations(binding.codexHome);
+  return {
+    ...roots,
+    ...journal,
+    backupRoot: roots.backupRoot,
+  };
+}
+
+export async function recoverPendingTransaction({ codexHome, skillsRoot }, dependencies = {}) {
+  const roots = locations(codexHome);
+  if (!(await pathExists(roots.transactionRoot))) return { status: 'none' };
+  try {
+    await assertPlainExisting(roots.transactionRoot, 'directory');
+    await assertPlainExisting(roots.journalPath, 'file');
+    const journal = validateJournal(await readJsonFile(roots.journalPath), { codexHome, skillsRoot });
+    const state = await stateFromJournal({ codexHome, skillsRoot }, journal);
+    if (journal.phase === 'committed') {
+      if (!(await verifyDesired(state))) throw new InstallerError('recovery-required', { recoveryRequired: true });
+      await cleanupTransaction(roots.transactionRoot);
+      return { status: 'committed-cleaned' };
+    }
+    const restored = await rollback(state, dependencies.hooks);
+    if (!restored) throw new InstallerError('recovery-required', { recoveryRequired: true });
+    await cleanupTransaction(roots.transactionRoot);
+    return { status: 'rolled-back' };
+  } catch (error) {
+    if (error instanceof InstallerError && error.recoveryRequired) throw error;
+    throw new InstallerError('recovery-required', { recoveryRequired: true });
+  }
+}
+
+async function prepareTransaction({ operation, codexHome, skillsRoot, packageInfo }) {
+  if (normalizePath(path.dirname(skillsRoot)) !== normalizePath(codexHome)) {
+    throw new InstallerError('codex-root-untrusted');
+  }
+  await assertPlainExisting(codexHome, 'directory');
+  const roots = locations(codexHome);
+  if (await pathExists(roots.transactionRoot)) throw new InstallerError('transaction-pending');
+  const skillsRootExisted = await pathExists(skillsRoot);
+  if (skillsRootExisted) await assertPlainExisting(skillsRoot, 'directory');
+  const originals = await snapshotEntries(skillsRoot);
+
+  try {
+    await mkdir(roots.transactionRoot, { recursive: false });
+    await mkdir(roots.stageRoot, { recursive: false });
+    await mkdir(roots.backupRoot, { recursive: false });
+    const desired = {};
+    if (operation !== 'uninstall') {
+      for (const name of MANAGED_SKILLS) {
+        const destination = path.join(roots.stageRoot, name);
+        await copyPlainTree(path.join(packageInfo.skillsSource, name), destination);
+        desired[name] = await snapshotPath(destination, 'directory');
+        if (!snapshotsEqual(desired[name], packageInfo.desiredSkills[name])) {
+          throw new InstallerError('package-integrity-invalid');
+        }
+      }
+      const ledger = createInstallLedger(packageInfo.desiredSkills);
+      await atomicWriteJson(path.join(roots.stageRoot, INSTALL_LEDGER), ledger);
+      desired[INSTALL_LEDGER] = await snapshotPath(path.join(roots.stageRoot, INSTALL_LEDGER), 'file');
+    } else {
+      for (const name of MANAGED_SKILLS) desired[name] = { exists: false, kind: 'directory', entries: [] };
+      desired[INSTALL_LEDGER] = { exists: false, kind: 'file', entries: [] };
+    }
+    const state = {
+      ...roots,
+      operation,
+      transactionId: randomUUID(),
+      packageVersion: PACKAGE_VERSION,
+      phase: 'prepared',
+      codexHome,
+      skillsRoot,
+      skillsRootExisted,
+      originals,
+      desired,
+      moved: [],
+      installed: [],
+    };
+    await persistJournal(state);
+    return state;
+  } catch (error) {
+    await rm(roots.transactionRoot, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function commitTransaction(state, hooks = {}) {
+  const drift = await snapshotEntries(state.skillsRoot);
+  if (!entrySnapshotsEqual(drift, state.originals)) throw new InstallerError('target-drift');
+  await runHook(hooks, 'beforeCommit', state);
+  const afterHook = await snapshotEntries(state.skillsRoot);
+  if (!entrySnapshotsEqual(afterHook, state.originals)) throw new InstallerError('target-drift');
+  state.phase = 'committing';
+  await persistJournal(state);
+  if (!state.skillsRootExisted) await mkdir(state.skillsRoot, { recursive: false });
+  for (const name of ENTRY_NAMES) {
+    const target = targetPath(state.skillsRoot, name);
+    if (state.originals[name].exists) {
+      await rename(target, path.join(state.backupRoot, name));
+      state.moved.push(name);
+      await persistJournal(state);
+    }
+    if (state.desired[name].exists) {
+      await rename(path.join(state.stageRoot, name), target);
+      state.installed.push(name);
+      await persistJournal(state);
+    }
+    await runHook(hooks, `after:${name}`, state);
+  }
+  if (!(await verifyDesired(state))) throw new InstallerError('transaction-failed', { mutated: true });
+  state.phase = 'verifying';
+  await persistJournal(state);
+}
+
+export async function finalizeInstallTransaction(state) {
+  if (state.phase !== 'verifying' || !(await verifyDesired(state))) {
+    throw new InstallerError('recovery-required', { mutated: true, recoveryRequired: true });
+  }
+  state.phase = 'committed';
+  await persistJournal(state);
+  try {
+    await cleanupTransaction(state.transactionRoot);
+    return { cleanupWarning: null };
+  } catch {
+    return { cleanupWarning: 'cleanup-warning' };
+  }
+}
+
+export async function abortInstallTransaction(state, dependencies = {}) {
+  const restored = await rollback(state, dependencies.hooks).catch(() => false);
+  if (!restored) throw new InstallerError('recovery-required', { mutated: true, recoveryRequired: true });
+  await cleanupTransaction(state.transactionRoot).catch(() => {});
+  return { rollback: 'completed' };
+}
+
+export async function executeInstallTransaction({ operation, codexHome, skillsRoot, packageInfo }, dependencies = {}) {
+  let state;
+  try {
+    state = await prepareTransaction({ operation, codexHome, skillsRoot, packageInfo });
+    await runHook(dependencies.hooks, 'afterStage', state);
+    await commitTransaction(state, dependencies.hooks);
+    if (dependencies.deferFinalize === true) {
+      return {
+        status: operation === 'uninstall' ? 'removed' : 'completed',
+        rollback: 'not-needed',
+        cleanupWarning: null,
+        transactionHandle: state,
+      };
+    }
+    const finalized = await finalizeInstallTransaction(state);
+    return {
+      status: operation === 'uninstall' ? 'removed' : 'completed',
+      rollback: 'not-needed',
+      cleanupWarning: finalized.cleanupWarning,
+    };
+  } catch (error) {
+    if (!state) throw error;
+    const mutationStarted = state.phase === 'committing' || state.moved.length > 0 || state.installed.length > 0;
+    if (!mutationStarted) {
+      await cleanupTransaction(state.transactionRoot).catch(() => {});
+      throw error;
+    }
+    const restored = await rollback(state, dependencies.hooks).catch(() => false);
+    if (!restored) throw new InstallerError('recovery-required', { mutated: true, recoveryRequired: true });
+    await cleanupTransaction(state.transactionRoot).catch(() => {});
+    return { status: 'failed', code: error?.code ?? 'transaction-failed', rollback: 'completed', cleanupWarning: null };
+  }
+}
+
+export const __test = Object.freeze({
+  validateJournal,
+  snapshotEntries,
+  entrySnapshotsEqual,
+  locations,
+});