agent-skillboard 0.2.17 → 0.3.0

package/src/migration/v2-journal.mjs

@@ -0,0 +1,169 @@
+import { readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import {
+  atomicWrite,
+  optionalRead,
+  relativeInventoryPath,
+  removeBackupSet,
+  removeDurably,
+  restoreSnapshot,
+  sha256
+} from "./v2-files.mjs";
+
+const JOURNAL_FORMAT_VERSION = 1;
+
+export async function beginMigrationTransaction(configPath, inventoryPath, backup) {
+  const journalPath = journalPathFor(configPath);
+  const journal = {
+    format_version: JOURNAL_FORMAT_VERSION,
+    pid: process.pid,
+    phase: "prepared",
+    target_config: basename(configPath),
+    target_inventory: relativeInventoryPath(configPath, inventoryPath),
+    config_backup: basename(backup.configBackupPath),
+    inventory_backup: backup.inventoryBackupPath === null ? null : basename(backup.inventoryBackupPath),
+    inventory_existed: backup.inventoryExisted,
+    config_mode: backup.configMode,
+    inventory_mode: backup.inventoryMode,
+    input_sha256: sha256(await readFile(backup.configBackupPath)),
+    inventory_input_sha256: backup.inventoryBackupPath === null
+      ? null
+      : sha256(await readFile(backup.inventoryBackupPath))
+  };
+  await atomicWrite(journalPath, Buffer.from(`${JSON.stringify(journal, null, 2)}\n`), 0o600);
+  return journalPath;
+}
+
+export async function commitMigrationTransaction(journalPath) {
+  const journal = parseJournal(await readFile(journalPath, "utf8"));
+  await atomicWrite(
+    journalPath,
+    Buffer.from(`${JSON.stringify({ ...journal, phase: "committed" }, null, 2)}\n`),
+    0o600
+  );
+}
+
+export async function finishMigrationTransaction(journalPath) {
+  await removeDurably(journalPath);
+}
+
+export async function completeMigrationRecovery(journalPath, backup) {
+  const journal = parseJournal(await readFile(journalPath, "utf8"));
+  await writePhase(journalPath, journal, "recovered");
+  await removeBackupSet(backup);
+  await removeDurably(journalPath);
+}
+
+export async function recoverInterruptedMigration(configPath, inventoryPath, failpoint) {
+  const journalPath = journalPathFor(configPath);
+  const bytes = await optionalRead(journalPath);
+  if (bytes === null) return false;
+  const journal = parseJournal(bytes.toString("utf8"));
+  validateTargets(journal, configPath, inventoryPath);
+  if (processIsAlive(journal.pid)) {
+    throw new Error("Another migration is already using this config.");
+  }
+  const backup = backupFromJournal(journal, configPath);
+  if (journal.phase === "prepared") {
+    await validateBackupHashes(backup, journal);
+    await restoreSnapshot(configPath, inventoryPath, backup, {
+      afterConfigRename: () => terminateRecoveryAt(failpoint, "after-config-rename"),
+      afterInventoryRename: () => terminateRecoveryAt(failpoint, "after-inventory-rename")
+    });
+    await completeMigrationRecovery(journalPath, backup);
+  } else if (journal.phase === "recovered") {
+    await removeBackupSet(backup);
+    await removeDurably(journalPath);
+  } else {
+    await removeDurably(journalPath);
+  }
+  await removeDurably(`${configPath}.migrate.lock`);
+  return true;
+}
+
+export function journalPathFor(configPath) {
+  return `${configPath}.migrate.transaction.json`;
+}
+
+function parseJournal(text) {
+  const value = JSON.parse(text);
+  if (value?.format_version !== JOURNAL_FORMAT_VERSION
+    || !Number.isInteger(value.pid)
+    || value.pid <= 0
+    || !["prepared", "committed", "recovered"].includes(value.phase)) {
+    throw new Error("Invalid migration transaction journal; recovery was not attempted.");
+  }
+  return value;
+}
+
+async function writePhase(journalPath, journal, phase) {
+  await atomicWrite(
+    journalPath,
+    Buffer.from(`${JSON.stringify({ ...journal, phase }, null, 2)}\n`),
+    0o600
+  );
+}
+
+function terminateRecoveryAt(failpoint, point) {
+  if (failpoint === `terminate-recovery-${point}`) process.exit(87);
+}
+
+function validateTargets(journal, configPath, inventoryPath) {
+  if (journal.target_config !== basename(configPath)
+    || journal.target_inventory !== relativeInventoryPath(configPath, inventoryPath)) {
+    throw new Error("Migration transaction target mismatch; recovery was not attempted.");
+  }
+  if (typeof journal.config_backup !== "string"
+    || basename(journal.config_backup) !== journal.config_backup
+    || !journal.config_backup.startsWith(`${basename(configPath)}.`)) {
+    throw new Error("Invalid migration transaction backup reference; recovery was not attempted.");
+  }
+  const validInventoryBackup = journal.inventory_existed === false && journal.inventory_backup === null
+    || journal.inventory_existed === true
+      && typeof journal.inventory_backup === "string"
+      && basename(journal.inventory_backup) === journal.inventory_backup;
+  const validModes = Number.isInteger(journal.config_mode)
+    && journal.config_mode >= 0
+    && journal.config_mode <= 0o777
+    && (journal.inventory_existed === false
+      ? journal.inventory_mode === null
+      : Number.isInteger(journal.inventory_mode)
+        && journal.inventory_mode >= 0
+        && journal.inventory_mode <= 0o777);
+  if (!validInventoryBackup || !validModes) {
+    throw new Error("Invalid migration transaction backup metadata; recovery was not attempted.");
+  }
+}
+
+function backupFromJournal(journal, configPath) {
+  const directory = dirname(configPath);
+  return {
+    configBackupPath: join(directory, journal.config_backup),
+    inventoryBackupPath: journal.inventory_backup === null ? null : join(directory, journal.inventory_backup),
+    inventoryExisted: journal.inventory_existed,
+    configMode: journal.config_mode,
+    inventoryMode: journal.inventory_mode,
+    manifestPath: `${join(directory, journal.config_backup)}.manifest.json`
+  };
+}
+
+async function validateBackupHashes(backup, journal) {
+  if (sha256(await readFile(backup.configBackupPath)) !== journal.input_sha256) {
+    throw new Error("Migration transaction backup hash mismatch; recovery was not attempted.");
+  }
+  if (backup.inventoryExisted
+    && sha256(await readFile(backup.inventoryBackupPath)) !== journal.inventory_input_sha256) {
+    throw new Error("Migration transaction inventory hash mismatch; recovery was not attempted.");
+  }
+}
+
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error?.code === "ESRCH") return false;
+    if (error?.code === "EPERM") return true;
+    throw error;
+  }
+}

package/src/migration/v2-projection.mjs

@@ -0,0 +1,108 @@
+import YAML from "yaml";
+import { sha256 } from "./v2-files.mjs";
+
+const TARGET_VERSION = 2;
+const INVENTORY_FORMAT_VERSION = 1;
+
+export function parseMigrationConfig(text) {
+  const document = YAML.parseDocument(text);
+  if (document.errors.length > 0) {
+    throw new Error(`Invalid YAML config: ${document.errors.map((error) => error.message).join("; ")}`);
+  }
+  const parsed = document.toJS();
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Config root must be an object mapping");
+  }
+  return { document, parsed };
+}
+
+export function renderMigratedPolicy(policy, sourceText, document) {
+  document.set("version", TARGET_VERSION);
+  document.delete("workflows");
+  let skills = document.get("skills", true);
+  if (!YAML.isMap(skills)) {
+    skills = document.createNode({});
+    document.set("skills", skills);
+  }
+  const retainedIds = new Set(Object.keys(policy.skills));
+  for (const item of [...skills.items]) {
+    const id = String(item.key?.value ?? item.key);
+    if (!retainedIds.has(id)) skills.delete(id);
+  }
+  for (const [id, entry] of Object.entries(policy.skills)) {
+    skills.set(id, document.createNode(entry));
+  }
+  for (const key of ["defaults", "capabilities", "harnesses", "install_units"]) {
+    document.delete(key);
+  }
+  const text = String(document);
+  return sourceText.includes("\r\n") ? text.replace(/(?<!\r)\n/g, "\r\n") : text;
+}
+
+export function migrationInventory(mapped, sourceBytes, losses) {
+  return {
+    format_version: INVENTORY_FORMAT_VERSION,
+    generated: true,
+    authoritative_for_availability: false,
+    skills: mapped.skills,
+    install_units: mapped.install_units,
+    migration: {
+      source_version: 1,
+      target_version: TARGET_VERSION,
+      policy_projection_version: TARGET_VERSION,
+      invalidates: ["v1-action-id", "v1-guard-hook", "v1-lock-projection"],
+      input_sha256: sha256(sourceBytes),
+      losses
+    }
+  };
+}
+
+export function migrationReport(before, mapped, inputBytes, configBytes, inventoryBytes) {
+  const skillEntries = Object.entries(before.skills ?? {}).sort(([left], [right]) => left.localeCompare(right));
+  return {
+    target_version: TARGET_VERSION,
+    input_sha256: sha256(inputBytes),
+    config_sha256: sha256(configBytes),
+    inventory_sha256: sha256(inventoryBytes),
+    counts: {
+      skills: skillEntries.length,
+      enabled: Object.values(mapped.policy.skills).filter((skill) => skill.enabled).length,
+      disabled: Object.values(mapped.policy.skills).filter((skill) => !skill.enabled).length,
+      warnings: mapped.warnings.length,
+      losses: mapped.losses.length
+    },
+    skills: skillEntries.map(([id, skill]) => ({
+      id,
+      before: { status: skill.status, invocation: skill.invocation, exposure: skill.exposure },
+      after: mapped.policy.skills[id]
+    })),
+    warnings: [...mapped.warnings],
+    losses: mapped.losses.map(({ path, disposition }) => ({ path, disposition })),
+    ambiguities: mapped.ambiguities,
+    grouped_decision: mapped.ambiguities.length === 0 ? null : {
+      action: "apply_v2_migration",
+      confirmation_option: "--yes",
+      ambiguity_count: mapped.ambiguities.length,
+      skill_count: mapped.ambiguities.reduce((count, ambiguity) => count + ambiguity.skill_ids.length, 0)
+    }
+  };
+}
+
+export function unchangedMigrationResult(inputBytes) {
+  return {
+    mode: "apply",
+    changed: false,
+    target_version: TARGET_VERSION,
+    input_sha256: sha256(inputBytes),
+    config_sha256: sha256(inputBytes),
+    inventory_sha256: null,
+    counts: { skills: 0, enabled: 0, disabled: 0, warnings: 0, losses: 0 },
+    skills: [],
+    warnings: [],
+    losses: [],
+    ambiguities: [],
+    grouped_decision: null,
+    backup: null,
+    manifest: null
+  };
+}

package/src/migration/v2-transaction.mjs

@@ -0,0 +1,205 @@
+import { readFile, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { loadWorkspace } from "../workspace.mjs";
+import { mapV1ConfigToV2 } from "./v1-to-v2.mjs";
+import {
+  atomicWrite,
+  canonicalMigrationPaths,
+  createBackup,
+  optionalRead,
+  relativeInventoryPath,
+  restoreSnapshot,
+  sha256,
+  withConfigLock
+} from "./v2-files.mjs";
+import {
+  beginMigrationTransaction,
+  commitMigrationTransaction,
+  completeMigrationRecovery,
+  finishMigrationTransaction,
+  recoverInterruptedMigration
+} from "./v2-journal.mjs";
+import {
+  migrationInventory,
+  migrationReport,
+  parseMigrationConfig,
+  renderMigratedPolicy,
+  unchangedMigrationResult
+} from "./v2-projection.mjs";
+
+const TARGET_VERSION = 2;
+
+export async function migrateV2(options) {
+  const { configPath, inventoryPath } = await canonicalMigrationPaths(options.configPath, options.inventoryPath);
+  await recoverInterruptedMigration(configPath, inventoryPath, options.failpoint);
+  return await withConfigLock(configPath, async () => {
+    if (options.rollbackPath !== undefined) {
+      const requestedRollbackPath = isAbsolute(options.rollbackPath)
+        ? resolve(options.rollbackPath)
+        : resolve(dirname(configPath), options.rollbackPath);
+      const rollbackPath = await realpath(requestedRollbackPath);
+      return await rollbackMigration(configPath, inventoryPath, rollbackPath, options);
+    }
+    return await migrateForward(configPath, inventoryPath, options);
+  });
+}
+
+async function migrateForward(configPath, inventoryPath, options) {
+  const inputBytes = await readFile(configPath);
+  const inputText = inputBytes.toString("utf8");
+  const { document, parsed } = parseMigrationConfig(inputText);
+  const version = parsed.version ?? 1;
+  if (version === TARGET_VERSION) {
+    await validateCurrentV2(configPath, inventoryPath, options.skillsRoot);
+    return unchangedMigrationResult(inputBytes);
+  }
+  if (version !== 1) {
+    throw new Error(`Unsupported config version: ${String(version)}. No files were changed.`);
+  }
+
+  const mapped = mapV1ConfigToV2(parsed);
+  const configBytes = Buffer.from(renderMigratedPolicy(mapped.policy, inputText, document));
+  const inventory = migrationInventory(mapped.inventory, inputBytes, mapped.losses);
+  const inventoryBytes = Buffer.from(`${JSON.stringify(inventory, null, 2)}\n`);
+  const report = migrationReport(parsed, mapped, inputBytes, configBytes, inventoryBytes);
+  if (options.apply !== true) {
+    return { mode: "preview", changed: true, backup: null, ...report };
+  }
+
+  const previousInventory = await optionalRead(inventoryPath);
+  const backup = await createBackup(configPath, inputBytes, inventoryPath, previousInventory);
+  const journalPath = await beginMigrationTransaction(configPath, inventoryPath, backup);
+  try {
+    await atomicWrite(configPath, configBytes, backup.configMode);
+    failAt(options, "after-config-rename");
+    failAt(options, "after-config-write");
+    await atomicWrite(inventoryPath, inventoryBytes, backup.inventoryMode ?? 0o600);
+    failAt(options, "after-inventory-rename");
+    failAt(options, "before-validation");
+    await validateCurrentV2(configPath, inventoryPath, options.skillsRoot);
+    await commitMigrationTransaction(journalPath);
+    failAt(options, "after-commit-journal");
+    await finishMigrationTransaction(journalPath);
+    return {
+      mode: "apply",
+      changed: true,
+      backup: basename(backup.configBackupPath),
+      manifest: basename(backup.manifestPath),
+      ...report
+    };
+  } catch (error) {
+    await restoreSnapshot(configPath, inventoryPath, backup);
+    await completeMigrationRecovery(journalPath, backup);
+    throw error;
+  }
+}
+
+async function rollbackMigration(configPath, inventoryPath, configBackupPath, options) {
+  assertAdjacentBackup(configPath, configBackupPath);
+  const manifestPath = `${configBackupPath}.manifest.json`;
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  validateManifest(manifest, configPath, inventoryPath, configBackupPath);
+  const currentConfig = await readFile(configPath);
+  const currentInventory = await optionalRead(inventoryPath);
+  const snapshot = {
+    configBackupPath,
+    manifestPath,
+    inventoryBackupPath: manifest.inventory_backup === null
+      ? null
+      : join(dirname(configBackupPath), manifest.inventory_backup),
+    inventoryExisted: manifest.inventory_existed,
+    configMode: manifest.config_mode,
+    inventoryMode: manifest.inventory_mode
+  };
+  const backupBytes = await readFile(configBackupPath);
+  if (sha256(backupBytes) !== manifest.input_sha256) {
+    throw new Error("Migration backup hash mismatch; rollback was not attempted.");
+  }
+  if (snapshot.inventoryExisted) {
+    const inventoryBytes = await readFile(snapshot.inventoryBackupPath);
+    if (sha256(inventoryBytes) !== manifest.inventory_input_sha256) {
+      throw new Error("Migration inventory backup hash mismatch; rollback was not attempted.");
+    }
+  }
+
+  const safety = await createBackup(configPath, currentConfig, inventoryPath, currentInventory, "rollback-safety");
+  const journalPath = await beginMigrationTransaction(configPath, inventoryPath, safety);
+  try {
+    await restoreSnapshot(configPath, inventoryPath, snapshot, {
+      afterConfigRename: () => failAt(options, "after-config-rename"),
+      afterInventoryRename: () => failAt(options, "after-inventory-rename")
+    });
+    await commitMigrationTransaction(journalPath);
+    failAt(options, "after-commit-journal");
+    await finishMigrationTransaction(journalPath);
+    return {
+      mode: "rollback",
+      changed: true,
+      target_version: manifest.source_version,
+      input_sha256: sha256(currentConfig),
+      config_sha256: sha256(await readFile(configPath)),
+      inventory_sha256: (await optionalRead(inventoryPath)) === null
+        ? null
+        : sha256(await readFile(inventoryPath)),
+      backup: basename(configBackupPath),
+      safety_backup: basename(safety.configBackupPath)
+    };
+  } catch (error) {
+    await restoreSnapshot(configPath, inventoryPath, safety);
+    await completeMigrationRecovery(journalPath, safety);
+    throw error;
+  }
+}
+
+async function validateCurrentV2(configPath, inventoryPath, skillsRoot) {
+  const workspace = await loadWorkspace({ configPath, inventoryPath, skillsRoot });
+  if (workspace.version !== TARGET_VERSION) {
+    throw new Error("Post-write validation did not load version 2 policy.");
+  }
+  if (workspace.inventory?.integrityErrors?.length > 0) {
+    throw new Error("Post-write inventory validation failed.");
+  }
+  const policyIds = workspace.skills.map(({ id }) => id).sort((left, right) => left.localeCompare(right));
+  const inventoryIds = [...(workspace.inventory?.skillIds ?? [])].sort((left, right) => left.localeCompare(right));
+  if (policyIds.length !== inventoryIds.length
+    || policyIds.some((id, index) => id !== inventoryIds[index])) {
+    throw new Error("Post-write policy and inventory skill-set agreement failed.");
+  }
+}
+
+function validateManifest(manifest, configPath, inventoryPath, backupPath) {
+  if (manifest?.format_version !== 1 || manifest.config_backup !== basename(backupPath)) {
+    throw new Error("Invalid migration backup manifest; rollback was not attempted.");
+  }
+  if (manifest.target_config !== basename(configPath)) {
+    throw new Error("Migration backup belongs to a different config; rollback was not attempted.");
+  }
+  const requestedInventory = relativeInventoryPath(configPath, inventoryPath);
+  if (manifest.target_inventory !== requestedInventory) {
+    throw new Error("Requested inventory target does not match the migration manifest; rollback was not attempted.");
+  }
+  if (!Number.isInteger(manifest.config_mode) || manifest.config_mode < 0 || manifest.config_mode > 0o777
+    || (manifest.inventory_existed === true
+      && (!Number.isInteger(manifest.inventory_mode) || manifest.inventory_mode < 0 || manifest.inventory_mode > 0o777))) {
+    throw new Error("Invalid migration backup mode metadata; rollback was not attempted.");
+  }
+  if (manifest.inventory_existed === true) {
+    const expected = `${basename(backupPath)}.inventory`;
+    if (manifest.inventory_backup !== expected || basename(manifest.inventory_backup) !== manifest.inventory_backup) {
+      throw new Error("Invalid migration inventory backup reference; rollback was not attempted.");
+    }
+  } else if (manifest.inventory_existed !== false || manifest.inventory_backup !== null) {
+    throw new Error("Invalid migration inventory backup state; rollback was not attempted.");
+  }
+}
+
+function assertAdjacentBackup(configPath, backupPath) {
+  if (dirname(configPath) !== dirname(backupPath) || !basename(backupPath).startsWith(`${basename(configPath)}.`)) {
+    throw new Error("Migration rollback backup must be adjacent to the selected config.");
+  }
+}
+
+function failAt(options, point) {
+  if (options.failpoint === `terminate-${point}`) process.exit(86);
+  if (options.failpoint === point) throw new Error(`Injected migration failure at ${point}.`);
+}

package/src/policy.mjs

@@ -14,6 +14,9 @@ const RULES = [
 ];
 
 export function checkPolicy(workspace) {
+  if (workspace.version === 2) {
+    return { ok: true, errors: [], warnings: [] };
+  }
   const ctx = buildPolicyContext(workspace);
   const errors = [];
   const warnings = [];