owlrunkit 0.14.0 → 0.15.0

package/scripts/runkit-contract/install-codex-skill.mjs

@@ -8,13 +8,20 @@ import {
   mkdtemp,
   readFile,
   readdir,
+  realpath,
   rename,
   rm,
   writeFile,
 } from "node:fs/promises";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
-import { isDirectExecution } from "./core-contract.mjs";
+import {
+  initializeProjectRunKit,
+  inspectProjectUpgradeSafety,
+  isDirectExecution,
+  validateProjectConfigV2,
+} from "./core-contract.mjs";
 
 const MANIFEST_FILE = ".owlcoda-install-manifest.json";
 
@@ -22,6 +29,18 @@ function sha256(value) {
   return createHash("sha256").update(value).digest("hex");
 }
 
+function sameCoreIdentity(left, right) {
+  return [
+    "contractVersion",
+    "coreVersion",
+    "coreManifestSha256",
+    "coreSourceRef",
+  ].every((field) => (
+    typeof left?.[field] === "string"
+    && left[field] === right?.[field]
+  ));
+}
+
 async function exists(filePath) {
   try {
     await lstat(filePath);
@@ -32,6 +51,43 @@ async function exists(filePath) {
   }
 }
 
+async function atomicWriteBytes(filePath, bytes) {
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  await rm(temporaryPath, { force: true });
+  await writeFile(temporaryPath, bytes, { flag: "wx" });
+  await rename(temporaryPath, filePath);
+}
+
+async function nextAvailablePath(parentRoot, baseName) {
+  for (let attempt = 1; ; attempt += 1) {
+    const suffix = attempt === 1
+      ? ""
+      : `-attempt-${String(attempt).padStart(3, "0")}`;
+    const candidate = path.join(parentRoot, `${baseName}${suffix}`);
+    if (!await exists(candidate)) return candidate;
+  }
+}
+
+async function writeAppendOnlyReceipt(receiptsRoot, baseName, receipt) {
+  await mkdir(receiptsRoot, { recursive: true });
+  for (let attempt = 1; ; attempt += 1) {
+    const suffix = attempt === 1
+      ? ""
+      : `-attempt-${String(attempt).padStart(3, "0")}`;
+    const receiptPath = path.join(receiptsRoot, `${baseName}${suffix}.json`);
+    try {
+      await writeFile(
+        receiptPath,
+        `${JSON.stringify(receipt, null, 2)}\n`,
+        { flag: "wx" },
+      );
+      return receiptPath;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+  }
+}
+
 async function fileMap(root, { excludeManifest = true } = {}) {
   const files = {};
   async function walk(directory, prefix = "") {
@@ -137,11 +193,79 @@ export async function inspectInstalledSkill({ targetRoot } = {}) {
   };
 }
 
+async function inspectFleetForSkillChange(workspaceRoots) {
+  if (!Array.isArray(workspaceRoots) || workspaceRoots.length === 0) {
+    throw new Error("skill_update_fleet_preflight_required");
+  }
+  const roots = [];
+  for (const workspaceRoot of workspaceRoots) {
+    if (typeof workspaceRoot !== "string" || workspaceRoot.length === 0) {
+      throw new Error("skill_update_fleet_workspace_invalid");
+    }
+    roots.push(await realpath(workspaceRoot));
+  }
+  const fleet = [...new Set(roots)].sort();
+  const projects = [];
+  for (const workspaceRoot of fleet) {
+    const safety = inspectProjectUpgradeSafety({ workspaceRoot });
+    if (safety.status !== "safe") {
+      const blockers = [
+        ...safety.activeRunIds,
+        ...safety.activeLeaseIds,
+        ...safety.issues,
+      ].join(",");
+      throw new Error(
+        `skill_update_blocked_active_execution:${workspaceRoot}:${blockers}`,
+      );
+    }
+    const configPath = path.join(
+      workspaceRoot,
+      ".owlcoda/runkit/config.json",
+    );
+    const configBytes = await readFile(configPath);
+    let config;
+    try {
+      config = JSON.parse(configBytes.toString("utf8"));
+    } catch {
+      throw new Error(`skill_update_fleet_config_invalid:${workspaceRoot}:invalid_json`);
+    }
+    const configV2 = config?.schemaVersion === "OwlCodaRunKitConfigV2"
+      ? validateProjectConfigV2(config)
+      : null;
+    const supportedV1 = config?.schemaVersion === "OwlCodaRunKitConfigV1"
+      && config?.core?.contractVersion === "0.1"
+      && config?.authorizationPolicy === "external_explicit_authority_required";
+    if (
+      (configV2 !== null && !configV2.valid)
+      || (configV2 === null && !supportedV1)
+    ) {
+      const issues = configV2?.issues?.join(",") ?? "unsupported_config";
+      throw new Error(
+        `skill_update_fleet_config_invalid:${workspaceRoot}:${issues}`,
+      );
+    }
+    projects.push({
+      workspaceRoot,
+      configPath,
+      configBytes,
+      configSha256: sha256(configBytes),
+    });
+  }
+  return projects;
+}
+
+async function restoreProjectConfigs(projects) {
+  for (const project of projects) {
+    await atomicWriteBytes(project.configPath, project.configBytes);
+  }
+}
+
 export async function installCodexSkill({
   repositoryRoot,
   targetRoot,
   archiveRoot,
   expectedUnmanagedManifestSha256 = null,
+  workspaceRoots = null,
 } = {}) {
   if (typeof repositoryRoot !== "string" || typeof targetRoot !== "string" || typeof archiveRoot !== "string") {
     throw new Error("repositoryRoot, targetRoot, and archiveRoot are required");
@@ -176,35 +300,377 @@ export async function installCodexSkill({
       }
       return { status: "unchanged", manifestSha256: desired.manifestSha256, previousInstallation: null };
     }
-
+    const projects = await inspectFleetForSkillChange(workspaceRoots);
     await mkdir(archiveRoot, { recursive: true });
-    const archivePath = path.join(archiveRoot, `owlcoda-runkit-${prior.manifestSha256.slice(7)}`);
-    if (await exists(archivePath)) throw new Error(`archive_already_exists:${archivePath}`);
+    const archivePath = await nextAvailablePath(
+      archiveRoot,
+      `owlcoda-runkit-${prior.manifestSha256.slice(7)}`,
+    );
     await rename(targetRoot, archivePath);
     try {
       await rename(stagingRoot, targetRoot);
       stagingPresent = false;
+      const projectMigrations = [];
+      for (const project of projects) {
+        const initialized = await initializeProjectRunKit({
+          workspaceRoot: project.workspaceRoot,
+        });
+        if (initialized.exitCode !== 0) {
+          throw new Error(
+            `skill_update_project_migration_blocked:${project.workspaceRoot}:${initialized.status}`,
+          );
+        }
+        const currentConfigBytes = await readFile(project.configPath);
+        projectMigrations.push({
+          workspaceRoot: project.workspaceRoot,
+          configPath: project.configPath,
+          fromConfigSha256: project.configSha256,
+          fromConfigBase64: project.configBytes.toString("base64"),
+          toConfigSha256: sha256(currentConfigBytes),
+          migrationReceipt: initialized.migrationReceipt ?? null,
+        });
+      }
+      const receipt = {
+        schemaVersion: "OwlCodaRunKitSkillUpgradeReceiptV1",
+        operation: "upgrade",
+        targetRoot: path.resolve(targetRoot),
+        archiveRoot: path.resolve(archiveRoot),
+        fromManifestSha256: prior.manifestSha256,
+        toManifestSha256: desired.manifestSha256,
+        priorArchivePath: archivePath,
+        projects: projectMigrations,
+        authorizationGranted: false,
+      };
+      const upgradeReceipt = await writeAppendOnlyReceipt(
+        path.join(archiveRoot, "receipts"),
+        `skill-upgrade-${prior.manifestSha256.slice(7)}-to-${desired.manifestSha256.slice(7)}`,
+        receipt,
+      );
+      return {
+        status: "updated",
+        manifestSha256: desired.manifestSha256,
+        previousInstallation: {
+          manifestSha256: prior.manifestSha256,
+          archivePath,
+        },
+        upgradeReceipt,
+        projectMigrations,
+      };
     } catch (error) {
+      if (await exists(targetRoot)) {
+        const failedArchivePath = await nextAvailablePath(
+          archiveRoot,
+          `owlcoda-runkit-failed-${desired.manifestSha256.slice(7)}`,
+        );
+        await rename(targetRoot, failedArchivePath);
+      }
       await rename(archivePath, targetRoot);
+      await restoreProjectConfigs(projects);
       throw error;
     }
-    return {
-      status: "updated",
-      manifestSha256: desired.manifestSha256,
-      previousInstallation: { manifestSha256: prior.manifestSha256, archivePath },
-    };
   } finally {
     if (stagingPresent) await rm(stagingRoot, { recursive: true, force: true });
   }
 }
 
+export async function restoreCodexSkill({
+  targetRoot,
+  archiveRoot,
+  upgradeReceiptPath,
+} = {}) {
+  if (
+    typeof targetRoot !== "string"
+    || typeof archiveRoot !== "string"
+    || typeof upgradeReceiptPath !== "string"
+  ) {
+    throw new Error("targetRoot, archiveRoot, and upgradeReceiptPath are required");
+  }
+  const resolvedTarget = path.resolve(targetRoot);
+  const resolvedArchive = path.resolve(archiveRoot);
+  const resolvedReceipt = path.resolve(upgradeReceiptPath);
+  const receiptRelative = path.relative(
+    path.join(resolvedArchive, "receipts"),
+    resolvedReceipt,
+  );
+  if (
+    receiptRelative.startsWith("..")
+    || path.isAbsolute(receiptRelative)
+    || !receiptRelative.endsWith(".json")
+  ) {
+    throw new Error("skill_rollback_receipt_outside_archive");
+  }
+  const receiptBytes = await readFile(resolvedReceipt);
+  const receipt = JSON.parse(receiptBytes.toString("utf8"));
+  if (
+    receipt.schemaVersion !== "OwlCodaRunKitSkillUpgradeReceiptV1"
+    || receipt.operation !== "upgrade"
+    || receipt.targetRoot !== resolvedTarget
+    || receipt.archiveRoot !== resolvedArchive
+    || receipt.authorizationGranted !== false
+    || !Array.isArray(receipt.projects)
+    || receipt.projects.length === 0
+  ) {
+    throw new Error("skill_rollback_receipt_invalid");
+  }
+  const resolvedPriorArchive = path.resolve(receipt.priorArchivePath);
+  const priorArchiveRelative = path.relative(
+    resolvedArchive,
+    resolvedPriorArchive,
+  );
+  if (
+    receipt.priorArchivePath !== resolvedPriorArchive
+    || priorArchiveRelative.startsWith("..")
+    || path.isAbsolute(priorArchiveRelative)
+    || priorArchiveRelative.length === 0
+    || priorArchiveRelative === "receipts"
+    || priorArchiveRelative.startsWith(`receipts${path.sep}`)
+  ) {
+    throw new Error("skill_rollback_prior_archive_outside_root");
+  }
+  const current = await inspectInstalledSkill({ targetRoot: resolvedTarget });
+  if (!current.valid || current.manifestSha256 !== receipt.toManifestSha256) {
+    throw new Error("skill_rollback_current_identity_mismatch");
+  }
+  const prior = await inspectInstalledSkill({
+    targetRoot: resolvedPriorArchive,
+  });
+  if (!prior.valid || prior.manifestSha256 !== receipt.fromManifestSha256) {
+    throw new Error("skill_rollback_prior_identity_mismatch");
+  }
+  const workspaceRoots = receipt.projects.map((project) => project.workspaceRoot);
+  const currentProjects = await inspectFleetForSkillChange(workspaceRoots);
+  const receiptProjectByRoot = new Map(
+    receipt.projects.map((project) => [project.workspaceRoot, project]),
+  );
+  for (const project of currentProjects) {
+    const expected = receiptProjectByRoot.get(project.workspaceRoot);
+    if (
+      !expected
+      || expected.configPath !== project.configPath
+      || expected.toConfigSha256 !== project.configSha256
+      || typeof expected.fromConfigBase64 !== "string"
+      || sha256(Buffer.from(expected.fromConfigBase64, "base64"))
+        !== expected.fromConfigSha256
+    ) {
+      throw new Error(
+        `skill_rollback_project_identity_mismatch:${project.workspaceRoot}`,
+      );
+    }
+  }
+  const currentArchivePath = await nextAvailablePath(
+    resolvedArchive,
+    `owlcoda-runkit-${current.manifestSha256.slice(7)}`,
+  );
+  await rename(resolvedTarget, currentArchivePath);
+  try {
+    await rename(resolvedPriorArchive, resolvedTarget);
+    for (const project of currentProjects) {
+      const expected = receiptProjectByRoot.get(project.workspaceRoot);
+      await atomicWriteBytes(
+        project.configPath,
+        Buffer.from(expected.fromConfigBase64, "base64"),
+      );
+    }
+    const rollbackReceipt = await writeAppendOnlyReceipt(
+      path.join(resolvedArchive, "receipts"),
+      `skill-rollback-${receipt.toManifestSha256.slice(7)}-to-${receipt.fromManifestSha256.slice(7)}`,
+      {
+        schemaVersion: "OwlCodaRunKitSkillRollbackReceiptV1",
+        operation: "rollback",
+        sourceUpgradeReceiptPath: resolvedReceipt,
+        sourceUpgradeReceiptSha256: sha256(receiptBytes),
+        targetRoot: resolvedTarget,
+        archiveRoot: resolvedArchive,
+        fromManifestSha256: receipt.toManifestSha256,
+        toManifestSha256: receipt.fromManifestSha256,
+        restoredArchivePath: resolvedPriorArchive,
+        replacedInstallationArchivePath: currentArchivePath,
+        projects: receipt.projects.map((project) => ({
+          workspaceRoot: project.workspaceRoot,
+          restoredConfigSha256: project.fromConfigSha256,
+        })),
+        authorizationGranted: false,
+      },
+    );
+    return {
+      status: "restored",
+      manifestSha256: receipt.fromManifestSha256,
+      rollbackReceipt,
+      replacedInstallation: {
+        manifestSha256: receipt.toManifestSha256,
+        archivePath: currentArchivePath,
+      },
+      authorizationGranted: false,
+    };
+  } catch (error) {
+    if (await exists(resolvedTarget)) {
+      await rename(resolvedTarget, resolvedPriorArchive);
+    }
+    await rename(currentArchivePath, resolvedTarget);
+    await restoreProjectConfigs(currentProjects);
+    throw error;
+  }
+}
+
+export async function recoverCodexSkillForActiveFleet({
+  targetRoot,
+  archiveRoot,
+  archivedInstallationPath,
+  workspaceRoots,
+} = {}) {
+  if (
+    typeof targetRoot !== "string"
+    || typeof archiveRoot !== "string"
+    || typeof archivedInstallationPath !== "string"
+    || !Array.isArray(workspaceRoots)
+    || workspaceRoots.length === 0
+  ) {
+    throw new Error(
+      "targetRoot, archiveRoot, archivedInstallationPath, and workspaceRoots are required",
+    );
+  }
+  const resolvedTarget = path.resolve(targetRoot);
+  const resolvedArchive = path.resolve(archiveRoot);
+  const resolvedPrior = path.resolve(archivedInstallationPath);
+  const priorRelative = path.relative(resolvedArchive, resolvedPrior);
+  if (
+    priorRelative.startsWith("..")
+    || path.isAbsolute(priorRelative)
+    || priorRelative.length === 0
+  ) {
+    throw new Error("skill_recovery_archive_outside_root");
+  }
+  const current = await inspectInstalledSkill({ targetRoot: resolvedTarget });
+  const prior = await inspectInstalledSkill({ targetRoot: resolvedPrior });
+  if (!current.valid || !prior.valid) {
+    throw new Error("skill_recovery_installation_identity_invalid");
+  }
+  const archivedCoreModule = await import(pathToFileURL(path.join(
+    resolvedPrior,
+    "scripts/runkit-contract/core-contract.mjs",
+  )).href);
+  const archivedCore = archivedCoreModule.currentCoreIdentity?.();
+  if (!archivedCore || typeof archivedCore.coreManifestSha256 !== "string") {
+    throw new Error("skill_recovery_archived_core_identity_missing");
+  }
+  const fleetRoots = [];
+  for (const workspaceRoot of workspaceRoots) {
+    fleetRoots.push(await realpath(workspaceRoot));
+  }
+  const fleet = [...new Set(fleetRoots)].sort();
+  const projects = [];
+  let activeRunCount = 0;
+  for (const workspaceRoot of fleet) {
+    const configPath = path.join(
+      workspaceRoot,
+      ".owlcoda/runkit/config.json",
+    );
+    const configBytes = await readFile(configPath);
+    const config = JSON.parse(configBytes.toString("utf8"));
+    if (!sameCoreIdentity(config.core, archivedCore)) {
+      throw new Error(
+        `skill_recovery_config_core_mismatch:${workspaceRoot}`,
+      );
+    }
+    const safety = inspectProjectUpgradeSafety({ workspaceRoot });
+    if (safety.issues.length > 0) {
+      throw new Error(
+        `skill_recovery_control_state_invalid:${workspaceRoot}:${safety.issues.join(",")}`,
+      );
+    }
+    const activeRunSet = new Set(safety.activeRunIds);
+    if (safety.activeLeaseIds.some((leaseId) => (
+      !activeRunSet.has(leaseId.split(":", 1)[0])
+    ))) {
+      throw new Error(
+        `skill_recovery_lease_without_matching_active_run:${workspaceRoot}`,
+      );
+    }
+    for (const runId of safety.activeRunIds) {
+      const enginePinPath = path.join(
+        workspaceRoot,
+        ".owlcoda/runkit/executions",
+        runId,
+        "engine-pin.json",
+      );
+      const pinStat = await lstat(enginePinPath);
+      if (pinStat.isSymbolicLink() || !pinStat.isFile()) {
+        throw new Error(
+          `skill_recovery_engine_pin_invalid:${workspaceRoot}:${runId}`,
+        );
+      }
+      const enginePin = JSON.parse(await readFile(enginePinPath, "utf8"));
+      if (!sameCoreIdentity(enginePin, archivedCore)) {
+        throw new Error(
+          `skill_recovery_active_pin_mismatch:${workspaceRoot}:${runId}`,
+        );
+      }
+      activeRunCount += 1;
+    }
+    projects.push({
+      workspaceRoot,
+      configSha256: sha256(configBytes),
+      activeRunIds: safety.activeRunIds,
+      activeLeaseIds: safety.activeLeaseIds,
+    });
+  }
+  if (activeRunCount === 0) {
+    throw new Error("skill_recovery_active_execution_required");
+  }
+  const replacedInstallationArchivePath = await nextAvailablePath(
+    resolvedArchive,
+    `owlcoda-runkit-replaced-${current.manifestSha256.slice(7)}`,
+  );
+  await rename(resolvedTarget, replacedInstallationArchivePath);
+  try {
+    await rename(resolvedPrior, resolvedTarget);
+    const recoveryReceipt = await writeAppendOnlyReceipt(
+      path.join(resolvedArchive, "receipts"),
+      `skill-active-recovery-${current.manifestSha256.slice(7)}-to-${prior.manifestSha256.slice(7)}`,
+      {
+        schemaVersion: "OwlCodaRunKitSkillActiveRecoveryReceiptV1",
+        operation: "active_execution_recovery",
+        targetRoot: resolvedTarget,
+        archiveRoot: resolvedArchive,
+        fromManifestSha256: current.manifestSha256,
+        toManifestSha256: prior.manifestSha256,
+        restoredCore: archivedCore,
+        restoredArchivePath: resolvedPrior,
+        replacedInstallationArchivePath,
+        projects,
+        authorizationGranted: false,
+      },
+    );
+    return {
+      status: "recovered_active_fleet",
+      manifestSha256: prior.manifestSha256,
+      core: archivedCore,
+      recoveryReceipt,
+      replacedInstallationArchivePath,
+      authorizationGranted: false,
+    };
+  } catch (error) {
+    if (await exists(resolvedTarget)) {
+      await rename(resolvedTarget, resolvedPrior);
+    }
+    await rename(replacedInstallationArchivePath, resolvedTarget);
+    throw error;
+  }
+}
+
 function parseOptions(values) {
   const options = {};
   for (let index = 0; index < values.length; index += 2) {
     const flag = values[index];
     const value = values[index + 1];
     if (!flag?.startsWith("--") || value === undefined) throw new Error("Options must be --name value pairs");
-    options[flag.slice(2)] = value;
+    const name = flag.slice(2);
+    if (name === "workspace") {
+      options.workspace ??= [];
+      options.workspace.push(value);
+    } else {
+      options[name] = value;
+    }
   }
   return options;
 }
@@ -219,6 +685,7 @@ export async function runCli(argv = process.argv.slice(2)) {
         targetRoot: options.target,
         archiveRoot: options.archive,
         expectedUnmanagedManifestSha256: options["expected-unmanaged"] ?? null,
+        workspaceRoots: options.workspace ?? null,
       });
       return { exitCode: 0, ...output };
     }
@@ -226,8 +693,35 @@ export async function runCli(argv = process.argv.slice(2)) {
       const output = await inspectInstalledSkill({ targetRoot: options.target });
       return { exitCode: output.valid ? 0 : 2, ...output };
     }
-    throw new Error("Usage: install-codex-skill.mjs <install|inspect> [options]");
+    if (command === "restore") {
+      const output = await restoreCodexSkill({
+        targetRoot: options.target,
+        archiveRoot: options.archive,
+        upgradeReceiptPath: options.receipt,
+      });
+      return { exitCode: 0, ...output };
+    }
+    if (command === "recover-active") {
+      const output = await recoverCodexSkillForActiveFleet({
+        targetRoot: options.target,
+        archiveRoot: options.archive,
+        archivedInstallationPath: options["archived-installation"],
+        workspaceRoots: options.workspace,
+      });
+      return { exitCode: 0, ...output };
+    }
+    throw new Error(
+      "Usage: install-codex-skill.mjs <install|inspect|restore|recover-active> [options]",
+    );
   } catch (error) {
+    const issue = error instanceof Error ? error.message : String(error);
+    if (issue.startsWith("skill_update_blocked_active_execution:")) {
+      return {
+        status: "skill_update_blocked_active_execution",
+        exitCode: 2,
+        issues: [issue],
+      };
+    }
     return { status: "invalid_input", exitCode: 3, issues: [error instanceof Error ? error.message : String(error)] };
   }
 }