@inetafrica/open-claudia 2.15.0 → 3.0.1

package/test-provider-migration-backup.js

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  MIGRATION_ID,
+  REQUIRED_ACTIVATION_COMPONENTS,
+  defaultMigrationSources,
+  ensureMigrationSnapshot,
+  markMigrationComponentActivated,
+  markMigrationComponentPrepared,
+  readMigrationJournal,
+  rollbackMigrationSnapshot,
+  sha256,
+  validateMigrationSnapshot,
+} = require("./core/migration-backup");
+
+const fixturesRoot = path.join(__dirname, "test-fixtures", "migrations");
+const fixtureNames = [
+  "claude-only",
+  "dual-provider",
+  "cursor-selected",
+  "multi-user",
+  "malformed-partial",
+  "missing-project",
+];
+const fixedDate = new Date("2026-07-10T08:00:00.000Z");
+
+function tempRoot(label) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `open-claudia-migration-${label}-`));
+}
+
+function installFixture(name, root) {
+  const configDir = path.join(root, "config");
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.cpSync(path.join(fixturesRoot, name), configDir, { recursive: true });
+  return configDir;
+}
+
+function options(configDir, extra = {}) {
+  let sequence = 0;
+  return {
+    configDir,
+    sources: defaultMigrationSources({ configDir }),
+    now: () => fixedDate,
+    idFactory: () => `fixture-${String(++sequence).padStart(2, "0")}`,
+    ...extra,
+  };
+}
+
+function rawSources(sources) {
+  const result = new Map();
+  for (const source of sources) {
+    result.set(source.path, fs.existsSync(source.sourcePath) ? fs.readFileSync(source.sourcePath) : null);
+  }
+  return result;
+}
+
+function assertSourcesEqual(sources, expected, label) {
+  for (const source of sources) {
+    const before = expected.get(source.path);
+    const exists = fs.existsSync(source.sourcePath);
+    assert.strictEqual(exists, before !== null, `${label}: presence changed for ${source.path}`);
+    if (before !== null) assert.deepStrictEqual(fs.readFileSync(source.sourcePath), before, `${label}: bytes changed for ${source.path}`);
+  }
+}
+
+function manifestFile(snapshotDir) {
+  return path.join(snapshotDir, "manifest.json");
+}
+
+function backupFile(snapshotDir, logicalPath) {
+  return path.join(snapshotDir, "originals", ...logicalPath.split("/"));
+}
+
+function assertProtectedModes(snapshotDir, manifest) {
+  if (process.platform === "win32") return;
+  assert.strictEqual(fs.statSync(snapshotDir).mode & 0o777, 0o700);
+  assert.strictEqual(fs.statSync(path.join(snapshotDir, "originals")).mode & 0o777, 0o700);
+  assert.strictEqual(fs.statSync(manifestFile(snapshotDir)).mode & 0o777, 0o600);
+  for (const entry of manifest.files.filter((item) => item.present)) {
+    assert.strictEqual(fs.statSync(backupFile(snapshotDir, entry.path)).mode & 0o777, 0o600);
+  }
+}
+
+function assertManifest(snapshot, sources, before, fixtureName) {
+  const { manifest, snapshotDir } = snapshot;
+  assert.strictEqual(manifest.migrationId, MIGRATION_ID);
+  assert.strictEqual(manifest.formatVersion, 1);
+  assert.strictEqual(manifest.createdAt, fixedDate.toISOString());
+  assert.strictEqual(manifest.files.length, sources.length);
+  assert.deepStrictEqual(manifest.files.map((entry) => entry.path), [...manifest.files.map((entry) => entry.path)].sort());
+  const manifestText = fs.readFileSync(manifestFile(snapshotDir), "utf8");
+  assert.ok(!manifestText.includes(path.dirname(snapshotDir)), "manifest must not expose absolute installation paths");
+  assert.ok(!manifestText.includes("SECRET_SENTINEL_DO_NOT_MANIFEST"), "manifest must not echo source contents");
+  for (const entry of manifest.files) {
+    assert.ok(!path.isAbsolute(entry.path));
+    assert.ok(!entry.path.includes(".."));
+    assert.strictEqual(typeof entry.schemaGuess, "string");
+    assert.ok(["archived", "unresolved", "missing"].includes(entry.resolution));
+    const raw = before.get(entry.path);
+    assert.strictEqual(entry.present, raw !== null, `${fixtureName}: manifest presence for ${entry.path}`);
+    if (raw === null) {
+      assert.strictEqual(entry.size, null);
+      assert.strictEqual(entry.sha256, null);
+      continue;
+    }
+    assert.strictEqual(entry.size, raw.length);
+    assert.strictEqual(entry.sha256, sha256(raw));
+    assert.deepStrictEqual(fs.readFileSync(backupFile(snapshotDir, entry.path)), raw);
+  }
+  assertProtectedModes(snapshotDir, manifest);
+}
+
+function fixtureMatrix() {
+  for (const fixtureName of fixtureNames) {
+    const root = tempRoot(fixtureName);
+    try {
+      const configDir = installFixture(fixtureName, root);
+      const opts = options(configDir);
+      const before = rawSources(opts.sources);
+      const snapshot = ensureMigrationSnapshot(opts);
+      assert.strictEqual(snapshot.reused, false);
+      assert.strictEqual(snapshot.journal.stage, "validated");
+      assertManifest(snapshot, opts.sources, before, fixtureName);
+      const validated = validateMigrationSnapshot(snapshot.snapshotDir, { sources: opts.sources, verifySources: true });
+      assert.strictEqual(validated.ok, true);
+      assertSourcesEqual(opts.sources, before, `${fixtureName} snapshot`);
+
+      const rerun = ensureMigrationSnapshot(opts);
+      assert.strictEqual(rerun.reused, true, `${fixtureName}: unchanged rerun reuses snapshot`);
+      assert.strictEqual(rerun.snapshotDir, snapshot.snapshotDir);
+      assert.strictEqual(readMigrationJournal(configDir).stage, "validated");
+
+      const entries = new Map(snapshot.manifest.files.map((entry) => [entry.path, entry]));
+      if (fixtureName === "cursor-selected") {
+        assert.strictEqual(entries.get("state.json").resolution, "unresolved");
+        assert.match(entries.get("state.json").schemaGuess, /cursor/);
+        assert.strictEqual(entries.get("jobs.json").resolution, "unresolved");
+      }
+      if (fixtureName === "malformed-partial") {
+        assert.strictEqual(entries.get("state.json").schemaGuess, "malformed-json");
+        assert.strictEqual(entries.get("state.json").resolution, "unresolved");
+        assert.strictEqual(entries.get("state.json.bak").present, true);
+        assert.strictEqual(entries.get("sessions.json.bak").present, true);
+      }
+      if (fixtureName === "missing-project") {
+        assert.strictEqual(entries.get("state.json").resolution, "unresolved");
+        assert.strictEqual(entries.get("jobs.json").resolution, "unresolved");
+      }
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }
+}
+
+function interruptionProbe() {
+  const points = [
+    "after-copy:state.json",
+    "after-manifest",
+    "after-prepared",
+    "after-validated",
+  ];
+  for (const point of points) {
+    const root = tempRoot(`interrupt-${point.replace(/[^a-z]/gi, "-")}`);
+    try {
+      const configDir = installFixture("cursor-selected", root);
+      const base = options(configDir);
+      const before = rawSources(base.sources);
+      assert.throws(() => ensureMigrationSnapshot({
+        ...base,
+        faultInjector(current) {
+          if (current === point) {
+            const error = new Error(`fixture interruption at ${point}`);
+            error.code = "FIXTURE_INTERRUPTION";
+            throw error;
+          }
+        },
+      }), (error) => error.code === "FIXTURE_INTERRUPTION");
+      assertSourcesEqual(base.sources, before, point);
+      const recovered = ensureMigrationSnapshot(base);
+      assert.strictEqual(recovered.journal.stage, "validated", `${point}: rerun recovers idempotently`);
+      assertSourcesEqual(base.sources, before, `${point} recovery`);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  }
+}
+
+function corruptionAndLockProbe() {
+  const root = tempRoot("corrupt");
+  try {
+    const configDir = installFixture("claude-only", root);
+    const opts = options(configDir);
+    const before = rawSources(opts.sources);
+
+    assert.throws(() => ensureMigrationSnapshot({
+      ...opts,
+      faultInjector(point, context) {
+        if (point === "before-copy-verify:state.json") fs.appendFileSync(context.backupPath, "corrupt");
+      },
+    }), (error) => error.code === "BACKUP_VERIFICATION_FAILED");
+    assertSourcesEqual(opts.sources, before, "copy verification failure");
+
+    const snapshot = ensureMigrationSnapshot(opts);
+    const stateBackup = backupFile(snapshot.snapshotDir, "state.json");
+    fs.appendFileSync(stateBackup, "corrupt");
+    assert.throws(
+      () => validateMigrationSnapshot(snapshot.snapshotDir),
+      (error) => error.code === "BACKUP_CHECKSUM_MISMATCH",
+    );
+    assert.throws(
+      () => markMigrationComponentActivated(snapshot.snapshotDir, "state", { configDir, sources: opts.sources }),
+      (error) => error.code === "BACKUP_CHECKSUM_MISMATCH",
+    );
+    assertSourcesEqual(opts.sources, before, "corrupt backup detection");
+
+    fs.writeFileSync(path.join(configDir, "migration-backups", MIGRATION_ID, ".lock"), "held", { mode: 0o600 });
+    assert.throws(() => ensureMigrationSnapshot(opts), (error) => error.code === "MIGRATION_LOCKED");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+
+  const symlinkRoot = tempRoot("symlink");
+  try {
+    const configDir = path.join(symlinkRoot, "config");
+    fs.mkdirSync(configDir, { recursive: true });
+    const outside = path.join(symlinkRoot, "outside.json");
+    fs.writeFileSync(outside, "{}\n");
+    fs.symlinkSync(outside, path.join(configDir, "state.json"));
+    assert.throws(() => ensureMigrationSnapshot(options(configDir)), (error) => error.code === "UNSAFE_MIGRATION_SOURCE");
+  } finally {
+    fs.rmSync(symlinkRoot, { recursive: true, force: true });
+  }
+}
+
+function activationProbe() {
+  const root = tempRoot("activate");
+  try {
+    const configDir = installFixture("dual-provider", root);
+    const opts = options(configDir);
+    const snapshot = ensureMigrationSnapshot(opts);
+    const migrated = {
+      state: { schemaVersion: 3, users: {} },
+      sessions: { schemaVersion: 3, users: {} },
+      jobs: {
+        schemaVersion: 2,
+        jobs: [],
+        archived: [],
+        legacyCronMigration: {
+          path: "crons.json",
+          present: false,
+          size: null,
+          sha256: null,
+          status: "missing",
+          recordCount: 0,
+          recordHashes: [],
+        },
+      },
+    };
+    for (const component of REQUIRED_ACTIVATION_COMPONENTS) {
+      const prepared = markMigrationComponentPrepared(snapshot.snapshotDir, component, { configDir, sources: opts.sources });
+      assert.ok(prepared.pendingComponents[component]);
+      assert.strictEqual(prepared.components[component], null);
+      fs.writeFileSync(path.join(configDir, `${component}.json`), `${JSON.stringify(migrated[component], null, 2)}\n`);
+      assert.throws(() => markMigrationComponentActivated(snapshot.snapshotDir, component, {
+        configDir,
+        sources: opts.sources,
+        faultInjector(point) {
+          if (point === `after-activation:${component}`) {
+            const error = new Error(`activation interrupted: ${component}`);
+            error.code = "FIXTURE_INTERRUPTION";
+            throw error;
+          }
+        },
+      }), (error) => error.code === "FIXTURE_INTERRUPTION");
+      const journal = markMigrationComponentActivated(snapshot.snapshotDir, component, { configDir, sources: opts.sources });
+      assert.ok(!journal.pendingComponents[component]);
+      const isLast = component === REQUIRED_ACTIVATION_COMPONENTS.at(-1);
+      assert.strictEqual(journal.stage, isLast ? "activated" : "validated");
+    }
+    const rerun = markMigrationComponentActivated(snapshot.snapshotDir, "jobs", { configDir, sources: opts.sources });
+    assert.strictEqual(rerun.stage, "activated");
+    assert.strictEqual(Object.keys(rerun.components).length, REQUIRED_ACTIVATION_COMPONENTS.length);
+
+    fs.appendFileSync(path.join(configDir, "state.json"), "\n");
+    assert.throws(
+      () => markMigrationComponentActivated(snapshot.snapshotDir, "state", { configDir, sources: opts.sources, requireSourceMatch: true }),
+      (error) => error.code === "MIGRATION_SOURCE_CHANGED",
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function rawByteProbe() {
+  const root = tempRoot("raw-bytes");
+  try {
+    const configDir = path.join(root, "config");
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, "state.json"), Buffer.from('{\r\n  "settings": {"backend": "claude"}\r\n}\r\n', "utf8"));
+    fs.writeFileSync(path.join(configDir, "sessions.json"), Buffer.alloc(0));
+    fs.writeFileSync(path.join(configDir, "jobs.json"), Buffer.from('[{"id":"raw-job"}]', "utf8"));
+    const opts = options(configDir);
+    const before = rawSources(opts.sources);
+    const snapshot = ensureMigrationSnapshot(opts);
+    assertManifest(snapshot, opts.sources, before, "raw bytes");
+    fs.writeFileSync(path.join(configDir, "state.json"), "mutated\n");
+    fs.writeFileSync(path.join(configDir, "sessions.json"), "mutated\n");
+    rollbackMigrationSnapshot(snapshot.snapshotDir, { configDir, sources: opts.sources });
+    assertSourcesEqual(opts.sources, before, "raw CRLF/zero-byte rollback");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function rollbackProbe() {
+  const root = tempRoot("rollback");
+  try {
+    const configDir = installFixture("malformed-partial", root);
+    const opts = options(configDir);
+    const before = rawSources(opts.sources);
+    const snapshot = ensureMigrationSnapshot(opts);
+
+    for (const source of opts.sources) {
+      fs.mkdirSync(path.dirname(source.sourcePath), { recursive: true });
+      fs.writeFileSync(source.sourcePath, `mutated:${source.path}\n`);
+    }
+    let interrupted = false;
+    assert.throws(() => rollbackMigrationSnapshot(snapshot.snapshotDir, {
+      configDir,
+      sources: opts.sources,
+      faultInjector(point) {
+        if (!interrupted && point === "after-rollback:jobs.json") {
+          interrupted = true;
+          const error = new Error("rollback interrupted");
+          error.code = "FIXTURE_INTERRUPTION";
+          throw error;
+        }
+      },
+    }), (error) => error.code === "FIXTURE_INTERRUPTION");
+    rollbackMigrationSnapshot(snapshot.snapshotDir, { configDir, sources: opts.sources });
+    assertSourcesEqual(opts.sources, before, "rollback retry");
+
+    // Validation happens before the first restore target is touched.
+    for (const source of opts.sources) {
+      if (fs.existsSync(source.sourcePath)) fs.writeFileSync(source.sourcePath, `second-mutation:${source.path}\n`);
+    }
+    const beforeBlockedRollback = rawSources(opts.sources);
+    fs.appendFileSync(backupFile(snapshot.snapshotDir, "state.json"), "corrupt");
+    assert.throws(
+      () => rollbackMigrationSnapshot(snapshot.snapshotDir, { configDir, sources: opts.sources }),
+      (error) => error.code === "BACKUP_CHECKSUM_MISMATCH",
+    );
+    assertSourcesEqual(opts.sources, beforeBlockedRollback, "blocked rollback");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function sourceChangeProbe() {
+  const root = tempRoot("source-change");
+  try {
+    const configDir = installFixture("claude-only", root);
+    const opts = options(configDir);
+    assert.throws(() => ensureMigrationSnapshot({
+      ...opts,
+      faultInjector(point) {
+        if (point === "before-source-validation") fs.appendFileSync(path.join(configDir, "state.json"), "\n");
+      },
+    }), (error) => error.code === "MIGRATION_SOURCE_CHANGED");
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function integrationAndDocsProbe() {
+  const bot = fs.readFileSync(path.join(__dirname, "bot.js"), "utf8");
+  const scheduler = fs.readFileSync(path.join(__dirname, "core", "scheduler.js"), "utf8");
+  const jobs = fs.readFileSync(path.join(__dirname, "core", "jobs.js"), "utf8");
+  const implementation = fs.readFileSync(path.join(__dirname, "core", "migration-backup.js"), "utf8");
+  const docs = fs.readFileSync(path.join(__dirname, "docs", "PROVIDER_MIGRATION.md"), "utf8");
+  const preflight = bot.indexOf("ensureMigrationSnapshot({");
+  const activation = bot.indexOf("completeProviderMigration({");
+  assert.ok(preflight >= 0);
+  assert.ok(activation > preflight, "provider-aware migration must follow the rollback snapshot");
+  for (const later of [
+    'require("./core/vault-store")',
+    'require("./core/scheduler")',
+    'require("./core/router")',
+    "registry.bootstrap()",
+  ]) {
+    assert.ok(bot.indexOf(later) > activation, `provider migration must complete before ${later}`);
+  }
+  const jobsWrite = jobs.slice(jobs.indexOf("function saveDocument"), jobs.indexOf("function ensureMigrated"));
+  assert.ok(jobsWrite.indexOf('requireMigrationSnapshotForComponent("jobs"') >= 0);
+  assert.ok(jobsWrite.indexOf('requireMigrationSnapshotForComponent("jobs"') < jobsWrite.indexOf('markMigrationComponentPrepared'));
+  assert.ok(jobsWrite.indexOf('markMigrationComponentPrepared') < jobsWrite.indexOf('atomicWriteFileSync'));
+  assert.ok(jobsWrite.indexOf('atomicWriteFileSync') < jobsWrite.indexOf('markMigrationComponentActivated'));
+  const cronMigration = scheduler.slice(scheduler.indexOf("function archiveLegacyCrons"), scheduler.indexOf("function init"));
+  assert.match(cronMigration, /jobsStore\.archive\(/);
+  assert.ok(!/renameSync|unlinkSync|rmSync/.test(cronMigration), "legacy cron source remains untouched after archival");
+  assert.ok(!/sourceRecord\(["']\.env/.test(implementation));
+  assert.ok(!/sourceRecord\(["'](?:vault|auth|identities)/.test(implementation));
+  assert.match(docs, /Stop every Open Claudia bot and scheduler process/);
+  assert.match(docs, /validateMigrationSnapshot/);
+  assert.match(docs, /rollbackMigrationSnapshot/);
+  assert.match(docs, /do not share, publish, or commit/i);
+  assert.match(docs, /Removed-provider[\s\S]*disabled archives[\s\S]*never reassigned/i);
+}
+
+fixtureMatrix();
+interruptionProbe();
+corruptionAndLockProbe();
+activationProbe();
+rollbackProbe();
+sourceChangeProbe();
+rawByteProbe();
+integrationAndDocsProbe();
+console.log("provider migration backup OK");