@opengsd/get-shit-done-redux 1.0.0

package/get-shit-done/bin/lib/installer-migrations.cjs

@@ -0,0 +1,776 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const {
+  validateInstallerMigrationActions,
+  validateInstallerMigrationRecord,
+} = require('./installer-migration-authoring.cjs');
+const { platformWriteSync } = require('./shell-command-projection.cjs');
+
+const MANIFEST_NAME = 'gsd-file-manifest.json';
+const INSTALL_STATE_NAME = 'gsd-install-state.json';
+const INSTALL_MIGRATION_LOCK_NAME = 'gsd-install-migration.lock';
+const DEFAULT_MIGRATIONS_DIR = path.join(__dirname, 'installer-migrations');
+const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
+const STRICT_JSON = Symbol('strict-json');
+
+function sha256File(filePath) {
+  const hash = crypto.createHash('sha256');
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    while (true) {
+      const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+      if (bytesRead === 0) break;
+      hash.update(buffer.subarray(0, bytesRead));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return hash.digest('hex');
+}
+
+function sha256Text(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function readJsonIfPresent(filePath, fallback) {
+  if (!fs.existsSync(filePath)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    if (fallback === STRICT_JSON) {
+      throw new Error(`invalid installer migration state JSON: ${filePath}: ${error.message}`);
+    }
+    return fallback;
+  }
+}
+
+function readInstallManifest(configDir) {
+  const manifest = readJsonIfPresent(path.join(configDir, MANIFEST_NAME), null);
+  if (!manifest || typeof manifest !== 'object') {
+    return { version: null, timestamp: null, mode: null, files: {} };
+  }
+  return {
+    version: manifest.version || null,
+    timestamp: manifest.timestamp || null,
+    mode: manifest.mode || null,
+    files: manifest.files && typeof manifest.files === 'object' ? manifest.files : {},
+  };
+}
+
+function readInstallState(configDir) {
+  const state = readJsonIfPresent(path.join(configDir, INSTALL_STATE_NAME), STRICT_JSON);
+  if (!state || typeof state !== 'object') {
+    return { schemaVersion: 1, appliedMigrations: [] };
+  }
+  return {
+    schemaVersion: state.schemaVersion || 1,
+    appliedMigrations: Array.isArray(state.appliedMigrations) ? state.appliedMigrations : [],
+  };
+}
+
+// Strict atomic write for the install state: must never be left half-written.
+// Bypasses the seam because platformWriteSync falls back to a direct write on
+// rename failure, which would silently violate this invariant.
+function atomicWriteInstallState(configDir, content) {
+  fs.mkdirSync(configDir, { recursive: true });
+  const filePath = path.join(configDir, INSTALL_STATE_NAME);
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    fs.writeFileSync(tmpPath, content, 'utf8');
+    fs.renameSync(tmpPath, filePath);
+  } catch (error) {
+    try { fs.rmSync(tmpPath, { force: true }); } catch { /* best-effort */ }
+    throw error;
+  }
+}
+
+function writeInstallState(configDir, state) {
+  atomicWriteInstallState(configDir, JSON.stringify(state, null, 2) + '\n');
+  return state;
+}
+
+function readJson(configDir, relPath) {
+  const { fullPath } = ensureInsideConfig(configDir, relPath);
+  if (!fs.existsSync(fullPath)) {
+    return { exists: false, value: null, error: null };
+  }
+  try {
+    return { exists: true, value: JSON.parse(fs.readFileSync(fullPath, 'utf8')), error: null };
+  } catch (error) {
+    return { exists: true, value: null, error };
+  }
+}
+
+function normalizeRelPath(relPath) {
+  if (typeof relPath !== 'string' || relPath.trim() === '') {
+    throw new Error('migration action relPath must be a non-empty string');
+  }
+  const normalized = relPath.replace(/\\/g, '/');
+  if (path.isAbsolute(normalized) || path.win32.isAbsolute(normalized)) {
+    throw new Error(`migration action relPath must stay inside configDir: ${relPath}`);
+  }
+  const segments = normalized.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    throw new Error(`migration action relPath must stay inside configDir: ${relPath}`);
+  }
+  return segments.join('/');
+}
+
+function classifyArtifact(configDir, relPath, manifest) {
+  const normalized = normalizeRelPath(relPath);
+  const originalHash = manifest.files[normalized] || null;
+  const fullPath = path.join(configDir, normalized);
+  if (!fs.existsSync(fullPath)) {
+    return { classification: originalHash ? 'managed-missing' : 'missing', originalHash, currentHash: null };
+  }
+  const currentHash = sha256File(fullPath);
+  if (!originalHash) {
+    return { classification: 'unknown', originalHash: null, currentHash };
+  }
+  if (currentHash === originalHash) {
+    return { classification: 'managed-pristine', originalHash, currentHash };
+  }
+  return { classification: 'managed-modified', originalHash, currentHash };
+}
+
+function appliedMigrationIds(state) {
+  return new Set(
+    state.appliedMigrations
+      .filter((entry) => entry && typeof entry.id === 'string')
+      .map((entry) => entry.id)
+  );
+}
+
+function appliedMigrationEntries(state) {
+  const entries = new Map();
+  for (const entry of state.appliedMigrations) {
+    if (entry && typeof entry.id === 'string' && !entries.has(entry.id)) {
+      entries.set(entry.id, entry);
+    }
+  }
+  return entries;
+}
+
+function migrationChecksum(migration) {
+  const checksum = migration.checksum;
+  if (typeof checksum === 'string' && checksum) return checksum;
+  const serializable = {
+    id: migration.id,
+    title: migration.title || null,
+    description: migration.description || null,
+    introducedIn: migration.introducedIn || null,
+    runtimes: migration.runtimes || null,
+    scopes: migration.scopes || null,
+    destructive: migration.destructive === true,
+    runtimeContract: migration.runtimeContract || null,
+    plan: typeof migration.plan === 'function' ? migration.plan.toString() : null,
+  };
+  return `sha256:${sha256Text(JSON.stringify(serializable))}`;
+}
+
+function assertAppliedMigrationChecksums(applied, migrations) {
+  for (const migration of migrations) {
+    const entry = applied.get(migration.id);
+    if (!entry || !entry.checksum) continue;
+    const checksum = migrationChecksum(migration);
+    if (entry.checksum !== checksum) {
+      throw new Error(
+        `applied migration checksum changed for ${migration.id}; create a new fix-forward migration id`
+      );
+    }
+  }
+}
+
+function migrationMatchesContext(migration, { runtime, scope }) {
+  if (Array.isArray(migration.runtimes) && migration.runtimes.length > 0) {
+    if (!runtime || !migration.runtimes.includes(runtime)) return false;
+  }
+  if (Array.isArray(migration.scopes) && migration.scopes.length > 0) {
+    if (!scope || !migration.scopes.includes(scope)) return false;
+  }
+  return true;
+}
+
+function discoverInstallerMigrations({ migrationsDir }) {
+  if (!migrationsDir || !fs.existsSync(migrationsDir)) return [];
+  return fs.readdirSync(migrationsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.cjs'))
+    .map((entry) => entry.name)
+    .sort()
+    .flatMap((fileName) => {
+      const source = path.join(migrationsDir, fileName);
+      delete require.cache[require.resolve(source)];
+      const exported = require(source);
+      const records = Array.isArray(exported) ? exported : [exported];
+      return records.map((record) => validateInstallerMigrationRecord(record, source));
+    });
+}
+
+function journalTimestamp(now) {
+  return now().replace(/[:.]/g, '-');
+}
+
+function migrationRunId(appliedAt) {
+  return `${journalTimestamp(() => appliedAt)}-${crypto.randomBytes(8).toString('hex')}`;
+}
+
+function sleepSync(ms) {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+
+/**
+ * Check whether a given PID is alive on the current host.
+ * Uses process.kill(pid, 0) which works on POSIX and Windows (Node's
+ * implementation maps it to OpenProcess + GetExitCodeProcess on win32).
+ * Returns true if alive or permission-denied (live but not ours),
+ * false if ESRCH (no such process).
+ */
+function isPidAlive(pid) {
+  if (typeof pid !== 'number' || !Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true; // alive (or permission denied — treat as live)
+  } catch (err) {
+    return err.code !== 'ESRCH';
+  }
+}
+
+/**
+ * Try to read and parse the lock file JSON. Returns null on any error
+ * (missing, invalid JSON, I/O failure).
+ */
+function readLockFile(lockPath) {
+  try {
+    const raw = fs.readFileSync(lockPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && typeof parsed.pid === 'number') {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function acquireInstallMigrationLock(configDir, { timeoutMs = DEFAULT_LOCK_TIMEOUT_MS } = {}) {
+  fs.mkdirSync(configDir, { recursive: true });
+  const lockPath = path.join(configDir, INSTALL_MIGRATION_LOCK_NAME);
+  const started = Date.now();
+
+  while (true) {
+    let fd = null;
+    let lockCreatedByUs = false;
+    try {
+      fd = fs.openSync(lockPath, 'wx');
+      // Close the open descriptor before writing so the file handle is
+      // released on Windows before the release closure unlinks it.
+      // Write payload via writeFileSync with the path (not the fd) so we
+      // don't hold an open fd across the lifetime of the lock.
+      fs.closeSync(fd);
+      fd = null;
+      lockCreatedByUs = true; // we own the file; clean it up on any subsequent error
+      fs.writeFileSync(lockPath, JSON.stringify({
+        pid: process.pid,
+        acquiredAt: new Date().toISOString(),
+      }) + '\n');
+      lockCreatedByUs = false; // release closure owns cleanup from here
+      return () => {
+        const failures = [];
+        // Use unlinkSync (not rmSync with { force: true }) so EPERM errors
+        // are NOT silently swallowed. On Windows, if the unlink fails
+        // transiently, the error surfaces via releaseError so the caller
+        // can observe and surface it rather than leaving a stale lock.
+        try { fs.unlinkSync(lockPath); } catch (error) { failures.push(error); }
+        if (failures.length > 0) {
+          const releaseError = new Error(`failed to release installer migration lock: ${lockPath}`);
+          releaseError.failures = failures;
+          throw releaseError;
+        }
+      };
+    } catch (error) {
+      if (fd !== null) {
+        try { fs.closeSync(fd); } catch { /* best-effort */ }
+        try { fs.unlinkSync(lockPath); } catch { /* best-effort */ }
+        fd = null;
+      } else if (lockCreatedByUs) {
+        // fd was closed but writeFileSync threw before we returned the release
+        // closure — the empty lock file is still on disk and must be removed
+        // so it does not orphan as an unreadable (empty/invalid JSON) stale lock.
+        try { fs.unlinkSync(lockPath); } catch { /* best-effort */ }
+      }
+      if (error && error.code === 'EEXIST') {
+        // Stale-lock reclamation: read the on-disk PID and check liveness.
+        // If the PID is dead (ESRCH) or is our own process (same-process
+        // re-entry caused by rmSync silently swallowing an unlink error on
+        // a previous call in the same invocation — the root cause of #3670),
+        // reclaim the lock by removing the stale file and retrying.
+        const lockData = readLockFile(lockPath);
+        if (lockData !== null) {
+          const holderPid = lockData.pid;
+          const isSameProcess = holderPid === process.pid;
+          const isDeadProcess = !isPidAlive(holderPid);
+          if (isSameProcess || isDeadProcess) {
+            // Reclaim: remove the stale lock and loop back to openSync.
+            // Only continue (retry) when unlink actually succeeds — a silent
+            // continue on reclaim failure recreates the original deadlock:
+            // the lock stays on disk and we spin indefinitely.
+            let reclaimed = false;
+            try { fs.unlinkSync(lockPath); reclaimed = true; } catch { /* unlink failed — fall through to timeout path */ }
+            if (reclaimed) continue;
+          }
+        }
+        if (Date.now() - started >= timeoutMs) {
+          const holderInfo = lockData ? ` (held by pid ${lockData.pid} since ${lockData.acquiredAt})` : '';
+          throw new Error(`installer migration lock is held: ${lockPath}${holderInfo}`);
+        }
+        sleepSync(Math.min(50, Math.max(1, timeoutMs - (Date.now() - started))));
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+function ensureInsideConfig(configDir, relPath) {
+  const normalized = normalizeRelPath(relPath);
+  const fullPath = path.resolve(configDir, normalized);
+  const root = path.resolve(configDir);
+  if (fullPath !== root && !fullPath.startsWith(root + path.sep)) {
+    throw new Error(`migration path escapes configDir: ${relPath}`);
+  }
+  return { normalized, fullPath };
+}
+
+function isStructurallyEmpty(value) {
+  if (value === null || value === undefined) return true;
+  if (Array.isArray(value)) return value.length === 0;
+  return typeof value === 'object' && Object.keys(value).length === 0;
+}
+
+
+function journalAction(action, status, extras = {}) {
+  const { value, ...safeAction } = action;
+  return { ...safeAction, ...extras, status };
+}
+
+function planInstallerMigrations({
+  configDir,
+  runtime = null,
+  scope = null,
+  migrations,
+  baselineScan = false,
+  now = () => new Date().toISOString(),
+}) {
+  if (!configDir) throw new Error('configDir is required');
+  if (!Array.isArray(migrations)) throw new Error('migrations must be an array');
+
+  const manifest = readInstallManifest(configDir);
+  const state = readInstallState(configDir);
+  const validatedMigrations = migrations.map((migration) =>
+    validateInstallerMigrationRecord(migration)
+  );
+  const scopedMigrations = validatedMigrations.filter((migration) =>
+    migrationMatchesContext(migration, { runtime, scope })
+  );
+  const applied = appliedMigrationEntries(state);
+  assertAppliedMigrationChecksums(applied, scopedMigrations);
+  const pending = scopedMigrations.filter((migration) => !applied.has(migration.id));
+  const actions = [];
+  const blocked = [];
+  const classifications = new Map();
+  const classify = (relPath) => {
+    const normalized = normalizeRelPath(relPath);
+    if (!classifications.has(normalized)) {
+      classifications.set(normalized, classifyArtifact(configDir, normalized, manifest));
+    }
+    return classifications.get(normalized);
+  };
+
+  for (const migration of pending) {
+    const plannedActions = migration.plan({
+      configDir,
+      runtime,
+      scope,
+      manifest,
+      state,
+      baselineScan,
+      now,
+      classifyArtifact: classify,
+      readJson: (relPath) => readJson(configDir, relPath),
+    });
+    validateInstallerMigrationActions(plannedActions, migration);
+    const checksum = migrationChecksum(migration);
+    for (const rawAction of plannedActions) {
+      const relPath = normalizeRelPath(rawAction.relPath);
+      const classification = rawAction.classification
+        ? {
+            classification: rawAction.classification,
+            originalHash: rawAction.originalHash || null,
+            currentHash: rawAction.currentHash || null,
+          }
+        : classify(relPath);
+      let protectedType = rawAction.type;
+      if (rawAction.type === 'remove-managed' && classification.classification === 'managed-modified') {
+        protectedType = 'backup-and-remove';
+      }
+      if (rawAction.type === 'remove-managed' && classification.classification === 'unknown') {
+        protectedType = 'preserve-user';
+      }
+      const action = {
+        migrationId: migration.id,
+        migrationChecksum: checksum,
+        type: protectedType,
+        relPath,
+        reason: rawAction.reason || migration.description || '',
+        classification: classification.classification,
+        originalHash: classification.originalHash,
+        currentHash: classification.currentHash,
+      };
+      if (action.type !== rawAction.type) {
+        action.requestedType = rawAction.type;
+      }
+      if (action.type === 'backup-and-remove') {
+        action.backupRelPath = null;
+      }
+      if (action.type === 'rewrite-json') {
+        action.value = rawAction.value;
+        action.deleteIfEmpty = rawAction.deleteIfEmpty === true;
+      }
+      if (rawAction.prompt) action.prompt = rawAction.prompt;
+      if (Array.isArray(rawAction.choices)) action.choices = rawAction.choices;
+      if (action.type === 'prompt-user') {
+        blocked.push(action);
+      } else if (
+        action.classification === 'unknown' &&
+        action.type !== 'rewrite-json' &&
+        action.type !== 'record-baseline' &&
+        action.type !== 'baseline-preserve-user'
+      ) {
+        blocked.push(action);
+      }
+      actions.push(action);
+    }
+  }
+
+  return {
+    generatedAt: now(),
+    manifest,
+    state,
+    pendingMigrationIds: pending.map((migration) => migration.id),
+    pendingMigrations: pending,
+    actions,
+    blocked,
+  };
+}
+
+function uniqueActionMigrationIds(actions) {
+  return [...new Set(actions.map((action) => action.migrationId).filter(Boolean))];
+}
+
+function rollbackAppliedMigrationResult({ configDir, journal, journalPath, rollbackRoot, backupRoot, previousInstallStateBytes }) {
+  const failures = [];
+  for (const action of [...journal.actions].reverse()) {
+    if (!action.rollbackRelPath) continue;
+    const rollbackPath = path.join(configDir, action.rollbackRelPath);
+    const dest = path.join(configDir, action.relPath);
+    try {
+      if (fs.existsSync(rollbackPath)) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(rollbackPath, dest);
+      }
+    } catch (error) {
+      failures.push({ relPath: action.relPath, error: error.message });
+    }
+    if (action.backupRelPath) {
+      try {
+        fs.rmSync(path.join(configDir, action.backupRelPath), { force: true });
+      } catch {
+        // backup cleanup is best-effort; preserve restore failures above
+      }
+    }
+  }
+
+  try {
+    if (previousInstallStateBytes === null) {
+      fs.rmSync(path.join(configDir, INSTALL_STATE_NAME), { force: true });
+    } else {
+      atomicWriteInstallState(configDir, previousInstallStateBytes);
+    }
+  } catch (error) {
+    failures.push({ relPath: INSTALL_STATE_NAME, error: error.message });
+  }
+
+  try {
+    fs.rmSync(journalPath, { force: true });
+    fs.rmSync(rollbackRoot, { recursive: true, force: true });
+    fs.rmSync(backupRoot, { recursive: true, force: true });
+  } catch {
+    // journal cleanup is best-effort; the rollback above is the safety-critical part
+  }
+
+  if (failures.length > 0) {
+    const error = new Error('migration rollback incomplete');
+    error.rollbackFailures = failures;
+    throw error;
+  }
+}
+
+function cleanupMigrationRunArtifacts(journalPath, rollbackRoot, backupRoot) {
+  try { fs.rmSync(journalPath, { force: true }); } catch { /* best-effort */ }
+  try { fs.rmSync(rollbackRoot, { recursive: true, force: true }); } catch { /* best-effort */ }
+  try { fs.rmSync(backupRoot, { recursive: true, force: true }); } catch { /* best-effort */ }
+}
+
+function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().toISOString() }) {
+  if (!configDir) throw new Error('configDir is required');
+  if (!plan || !Array.isArray(plan.actions)) throw new Error('plan with actions is required');
+  if (Array.isArray(plan.blocked) && plan.blocked.length > 0) {
+    throw new Error(`migration plan has ${plan.blocked.length} blocked action(s)`);
+  }
+
+  const appliedAt = now();
+  const runId = migrationRunId(appliedAt);
+  const journalRelPath = path.posix.join('gsd-migration-journal', `${runId}.json`);
+  const journalPath = path.join(configDir, journalRelPath);
+  const rollbackRootRelPath = path.posix.join('gsd-migration-journal', `${runId}-rollback`);
+  const rollbackRoot = path.join(configDir, rollbackRootRelPath);
+  const backupRootRelPath = path.posix.join('gsd-migration-journal', `${runId}-backups`);
+  const backupRoot = path.join(configDir, backupRootRelPath);
+  const journal = {
+    schemaVersion: 1,
+    appliedAt,
+    appliedMigrationIds: uniqueActionMigrationIds(plan.actions),
+    actions: [],
+  };
+  const rollback = [];
+  const installStatePath = path.join(configDir, INSTALL_STATE_NAME);
+  const previousInstallStateBytes = fs.existsSync(installStatePath)
+    ? fs.readFileSync(installStatePath, 'utf8')
+    : null;
+
+  try {
+    fs.mkdirSync(path.dirname(journalPath), { recursive: true });
+    platformWriteSync(journalPath, JSON.stringify(journal, null, 2) + '\n');
+
+    for (const action of plan.actions) {
+      if (
+        action.type !== 'remove-managed' &&
+        action.type !== 'backup-and-remove' &&
+        action.type !== 'rewrite-json' &&
+        action.type !== 'record-baseline' &&
+        action.type !== 'baseline-preserve-user'
+      ) {
+        throw new Error(`unsupported migration action type: ${action.type}`);
+      }
+
+      const { normalized, fullPath } = ensureInsideConfig(configDir, action.relPath);
+      if (!fs.existsSync(fullPath)) {
+        journal.actions.push(journalAction(action, 'missing'));
+        continue;
+      }
+
+      if (action.type === 'record-baseline' || action.type === 'baseline-preserve-user') {
+        journal.actions.push(journalAction(action, action.type === 'record-baseline' ? 'recorded' : 'preserved'));
+        continue;
+      }
+
+      const rollbackPath = path.join(rollbackRoot, normalized);
+      fs.mkdirSync(path.dirname(rollbackPath), { recursive: true });
+      fs.copyFileSync(fullPath, rollbackPath);
+      rollback.push({ relPath: normalized, rollbackPath });
+
+      if (action.type === 'rewrite-json') {
+        if (action.deleteIfEmpty && isStructurallyEmpty(action.value)) {
+          fs.rmSync(fullPath, { force: true });
+          journal.actions.push(journalAction(action, 'removed', {
+            rollbackRelPath: path.posix.join(rollbackRootRelPath, normalized),
+          }));
+        } else {
+          platformWriteSync(fullPath, JSON.stringify(action.value, null, 2) + '\n');
+          journal.actions.push(journalAction(action, 'rewritten', {
+            rollbackRelPath: path.posix.join(rollbackRootRelPath, normalized),
+          }));
+        }
+        continue;
+      }
+
+      if (action.type === 'backup-and-remove') {
+        const backupRelPath = action.backupRelPath || path.posix.join(backupRootRelPath, normalized);
+        const backupPath = path.join(configDir, backupRelPath);
+        fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+        fs.copyFileSync(fullPath, backupPath);
+        journal.actions.push(journalAction(action, 'removed', {
+          backupRelPath,
+          rollbackRelPath: path.posix.join(rollbackRootRelPath, normalized),
+        }));
+      } else {
+        journal.actions.push(journalAction(action, 'removed', {
+          rollbackRelPath: path.posix.join(rollbackRootRelPath, normalized),
+        }));
+      }
+      fs.rmSync(fullPath, { force: true });
+    }
+
+    platformWriteSync(journalPath, JSON.stringify(journal, null, 2) + '\n');
+
+    const state = readInstallState(configDir);
+    const applied = appliedMigrationIds(state);
+    const nextApplied = [...state.appliedMigrations];
+    const actionsByMigrationId = new Map();
+    for (const action of plan.actions) {
+      if (action.migrationId && !actionsByMigrationId.has(action.migrationId)) {
+        actionsByMigrationId.set(action.migrationId, action);
+      }
+    }
+    for (const id of journal.appliedMigrationIds) {
+      if (!applied.has(id)) {
+        const action = actionsByMigrationId.get(id);
+        nextApplied.push({
+          id,
+          appliedAt,
+          journal: journalRelPath,
+          checksum: action && action.migrationChecksum ? action.migrationChecksum : null,
+        });
+      }
+    }
+    writeInstallState(configDir, {
+      schemaVersion: 1,
+      appliedMigrations: nextApplied,
+    });
+
+    return {
+      appliedMigrationIds: journal.appliedMigrationIds,
+      journalRelPath,
+      rollback: () => rollbackAppliedMigrationResult({ configDir, journal, journalPath, rollbackRoot, backupRoot, previousInstallStateBytes }),
+    };
+  } catch (error) {
+    const rollbackFailures = [];
+    for (const entry of rollback.reverse()) {
+      const dest = path.join(configDir, entry.relPath);
+      try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(entry.rollbackPath, dest);
+      } catch (rollbackError) {
+        rollbackFailures.push({
+          relPath: entry.relPath,
+          rollbackPath: entry.rollbackPath,
+          error: rollbackError.message,
+        });
+      }
+    }
+    if (rollbackFailures.length > 0) {
+      const rollbackError = new Error(`migration apply failed and rollback incomplete: ${error.message}`);
+      rollbackError.cause = error;
+      rollbackError.rollbackFailures = rollbackFailures;
+      throw rollbackError;
+    }
+    cleanupMigrationRunArtifacts(journalPath, rollbackRoot, backupRoot);
+    throw error;
+  }
+}
+
+function markPendingMigrationsApplied({ configDir, plan, now = () => new Date().toISOString() }) {
+  if (!plan || !Array.isArray(plan.pendingMigrationIds) || plan.pendingMigrationIds.length === 0) {
+    return [];
+  }
+  const appliedAt = now();
+  const state = readInstallState(configDir);
+  const applied = appliedMigrationIds(state);
+  const checksumsByMigrationId = new Map();
+  for (const migration of plan.pendingMigrations || []) {
+    checksumsByMigrationId.set(migration.id, migrationChecksum(migration));
+  }
+  const nextApplied = [...state.appliedMigrations];
+  const newlyApplied = [];
+  for (const id of plan.pendingMigrationIds) {
+    if (applied.has(id)) continue;
+    nextApplied.push({
+      id,
+      appliedAt,
+      journal: null,
+      checksum: checksumsByMigrationId.get(id) || null,
+    });
+    newlyApplied.push(id);
+  }
+  if (newlyApplied.length > 0) {
+    writeInstallState(configDir, {
+      schemaVersion: 1,
+      appliedMigrations: nextApplied,
+    });
+  }
+  return newlyApplied;
+}
+
+function runInstallerMigrations({
+  configDir,
+  runtime = null,
+  scope = null,
+  migrationsDir = DEFAULT_MIGRATIONS_DIR,
+  migrations = discoverInstallerMigrations({ migrationsDir }),
+  baselineScan = false,
+  now = () => new Date().toISOString(),
+  lockTimeoutMs = DEFAULT_LOCK_TIMEOUT_MS,
+} = {}) {
+  const releaseLock = acquireInstallMigrationLock(configDir, { timeoutMs: lockTimeoutMs });
+  let primaryError = null;
+  let completed = false;
+  try {
+    const plan = planInstallerMigrations({ configDir, runtime, scope, migrations, baselineScan, now });
+    if (plan.actions.length === 0) {
+      const appliedMigrationIds = markPendingMigrationsApplied({ configDir, plan, now });
+      completed = true;
+      return {
+        appliedMigrationIds,
+        journalRelPath: null,
+        plan,
+      };
+    }
+    if (plan.blocked.length > 0) {
+      completed = true;
+      return {
+        appliedMigrationIds: [],
+        journalRelPath: null,
+        plan,
+        blocked: plan.blocked,
+      };
+    }
+    const result = applyInstallerMigrationPlan({ configDir, plan, now });
+    completed = true;
+    return { ...result, plan };
+  } catch (error) {
+    primaryError = error;
+    throw error;
+  } finally {
+    try {
+      releaseLock();
+    } catch (releaseError) {
+      if (primaryError) {
+        primaryError.suppressed = [...(primaryError.suppressed || []), releaseError];
+      } else if (completed) {
+        throw releaseError;
+      } else {
+        throw releaseError;
+      }
+    }
+  }
+}
+
+module.exports = {
+  DEFAULT_MIGRATIONS_DIR,
+  INSTALL_MIGRATION_LOCK_NAME,
+  INSTALL_STATE_NAME,
+  MANIFEST_NAME,
+  applyInstallerMigrationPlan,
+  classifyArtifact,
+  discoverInstallerMigrations,
+  planInstallerMigrations,
+  readInstallManifest,
+  readInstallState,
+  runInstallerMigrations,
+  writeInstallState,
+};