@getmikie/cli 1.1.103 → 1.1.104

package/scripts/reconcile-install.mjs

@@ -1,14 +1,39 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 
-import { resolveNativeBinary } from "../lib/launcher.mjs";
+import {
+  materializedRuntimePath,
+  prepareNativeLaunch,
+  resolveNativeBinary,
+  retireHistoricalRuntimes,
+} from "../lib/launcher.mjs";
 import {
   createCommandAdapter,
   parseTrajectoryReconciliationReceipt,
 } from "../lib/update.mjs";
 
 const RECONCILIATION_ARGUMENTS = ["reconcile-trajectory-store-v2", "--json"];
+const CLIENT_REPAIR_ARGUMENTS = ["repair-claude-hooks-v1", "--json"];
+const CLIENT_RECONCILIATION_SCHEMA = "mikie.npm-client-reconciliation.v2";
+const CLIENT_REPAIR_SCHEMA = "mikie.claude-hook-repair.v1";
+const CLIENT_SETTLEMENT_SCHEMA = "mikie.claude-hook-repair-settlement.v1";
 const TRANSACTION_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PUBLIC_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
+const CLIENT_MARKER_NAME = /^[0-9a-f]{64}\.json$/;
+const CLIENT_MARKER_TEMP_NAME =
+  /^([0-9a-f]{64}\.json)\.([1-9][0-9]{0,9})\.([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.tmp$/;
+const MAX_CLIENT_MARKERS = 256;
+const MAX_CLIENT_MARKER_TEMPS = 32;
+const MAX_RETAINED_CLIENT_RUNTIMES = 8;
+
+async function sha256File(filePath) {
+  const digest = createHash("sha256");
+  for await (const chunk of createReadStream(filePath)) digest.update(chunk);
+  return digest.digest("hex");
+}
 
 function pathIdentity(value, platform) {
   const pathApi = platform === "win32" ? path.win32 : path.posix;
@@ -47,11 +72,462 @@ export async function reconcileInstalledTrajectory({
   return parseTrajectoryReconciliationReceipt(result.stdout, { allowNotConfigured: true });
 }
 
+function hasExactKeys(value, keys) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value).sort().join(",") === [...keys].sort().join(",")
+  );
+}
+
+function parseClientRepair(stdout, code) {
+  let receipt;
+  try {
+    receipt = JSON.parse(stdout.trim());
+  } catch {
+    throw new Error("native client reconciliation returned invalid JSON");
+  }
+  const exact = hasExactKeys(receipt, [
+    "schema_version",
+    "before",
+    "after",
+    "action",
+    "restart_required",
+  ]);
+  const current =
+    exact &&
+    receipt.schema_version === CLIENT_REPAIR_SCHEMA &&
+    receipt.before === "current" &&
+    receipt.after === "current" &&
+    receipt.action === "already_current" &&
+    receipt.restart_required === false;
+  const migrated =
+    exact &&
+    receipt.schema_version === CLIENT_REPAIR_SCHEMA &&
+    receipt.before === "outdated_owned" &&
+    receipt.after === "current" &&
+    receipt.action === "migrated" &&
+    receipt.restart_required === true;
+  const absent =
+    exact &&
+    receipt.schema_version === CLIENT_REPAIR_SCHEMA &&
+    receipt.before === "absent" &&
+    receipt.after === "absent" &&
+    receipt.action === "not_configured" &&
+    receipt.restart_required === false;
+  const refused =
+    exact &&
+    receipt.schema_version === CLIENT_REPAIR_SCHEMA &&
+    ["foreign_conflict", "unavailable"].includes(receipt.before) &&
+    receipt.after === receipt.before &&
+    receipt.action === "refused" &&
+    receipt.restart_required === false;
+  if ((code === 0 && !current && !migrated && !absent) || (code !== 0 && !refused)) {
+    throw new Error("native client reconciliation returned an invalid receipt");
+  }
+  return receipt;
+}
+
+function parseClientSettlement(stdout, code, phase) {
+  let receipt;
+  try {
+    receipt = JSON.parse(stdout.trim());
+  } catch {
+    throw new Error("native client reconciliation settlement returned invalid JSON");
+  }
+  if (
+    code !== 0 ||
+    !hasExactKeys(receipt, ["schema_version", "phase", "status"]) ||
+    receipt.schema_version !== CLIENT_SETTLEMENT_SCHEMA ||
+    receipt.phase !== phase ||
+    receipt.status !== "settled"
+  ) {
+    throw new Error("native client reconciliation settlement failed");
+  }
+}
+
+function reconciliationAuthority({ environment, platform, version, runtimeSha256 }) {
+  const profileRoot = environment.USERPROFILE ?? environment.HOME;
+  if (pathIdentity(profileRoot, platform) === null) {
+    throw new Error("installed client reconciliation profile authority is unavailable");
+  }
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const profileIdentity = pathIdentity(profileRoot, platform);
+  const codexIdentity = pathIdentity(
+    environment.CODEX_HOME ?? pathApi.join(profileRoot, ".codex"),
+    platform,
+  );
+  if (codexIdentity === null || !/^[0-9a-f]{64}$/.test(runtimeSha256)) {
+    throw new Error("installed client reconciliation profile authority is unavailable");
+  }
+  return {
+    schema_version: CLIENT_RECONCILIATION_SCHEMA,
+    version,
+    platform,
+    runtime_sha256: runtimeSha256,
+    profile_root: profileIdentity,
+    codex_root: codexIdentity,
+  };
+}
+
+function defaultClientMarkerRoot(environment, platform) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const root =
+    platform === "win32"
+      ? environment.LOCALAPPDATA && pathApi.join(environment.LOCALAPPDATA, "Mikie")
+      : environment.XDG_STATE_HOME
+        ? pathApi.join(environment.XDG_STATE_HOME, "mikie")
+        : environment.HOME && pathApi.join(environment.HOME, ".local", "state", "mikie");
+  if (pathIdentity(root, platform) === null) {
+    throw new Error("installed client reconciliation state authority is unavailable");
+  }
+  return pathApi.join(root, "client-reconciliation-v2");
+}
+
+function defaultClientMarker(environment, platform, authority) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  return pathApi.join(
+    defaultClientMarkerRoot(environment, platform),
+    clientMarkerFileName(authority),
+  );
+}
+
+function clientMarkerFileName(authority) {
+  const scope = JSON.stringify({
+    platform: authority.platform,
+    profile_root: authority.profile_root,
+    codex_root: authority.codex_root,
+  });
+  return `${createHash("sha256").update(scope).digest("hex")}.json`;
+}
+
+function encodeClientMarker(authority) {
+  return `${JSON.stringify(authority)}\n`;
+}
+
+function parseClientMarker(bytes) {
+  let marker;
+  try {
+    marker = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("installed client reconciliation marker is invalid");
+  }
+  if (
+    !hasExactKeys(marker, [
+      "schema_version",
+      "version",
+      "platform",
+      "runtime_sha256",
+      "profile_root",
+      "codex_root",
+    ]) ||
+    marker.schema_version !== CLIENT_RECONCILIATION_SCHEMA ||
+    !PUBLIC_VERSION.test(marker.version ?? "") ||
+    !["win32", "darwin", "linux"].includes(marker.platform) ||
+    !/^[0-9a-f]{64}$/.test(marker.runtime_sha256 ?? "") ||
+    pathIdentity(marker.profile_root, marker.platform) !== marker.profile_root ||
+    pathIdentity(marker.codex_root, marker.platform) !== marker.codex_root ||
+    !bytes.equals(Buffer.from(encodeClientMarker(marker)))
+  ) {
+    throw new Error("installed client reconciliation marker is invalid");
+  }
+  return marker;
+}
+
+async function readStableClientMarker(markerPath) {
+  const before = await lstat(markerPath);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > 2048) {
+    throw new Error("installed client reconciliation marker is invalid");
+  }
+  const bytes = await readFile(markerPath);
+  const after = await lstat(markerPath);
+  if (
+    before.dev !== after.dev ||
+    before.ino !== after.ino ||
+    before.size !== after.size ||
+    before.mtimeMs !== after.mtimeMs
+  ) {
+    throw new Error("installed client reconciliation marker changed during inspection");
+  }
+  return parseClientMarker(bytes);
+}
+
+async function readClientMarker(markerPath, authority) {
+  try {
+    const marker = await readStableClientMarker(markerPath);
+    return Object.keys(authority).every((key) => marker[key] === authority[key]);
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function writeClientMarker(markerPath, authority) {
+  await mkdir(path.dirname(markerPath), { recursive: true });
+  const temporary = `${markerPath}.${process.pid}.${randomUUID()}.tmp`;
+  const body = encodeClientMarker(authority);
+  try {
+    await writeFile(temporary, body, { flag: "wx", mode: 0o600 });
+    await rename(temporary, markerPath);
+  } finally {
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+function processIsAlive(pid) {
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error?.code === "ESRCH") return false;
+    return true;
+  }
+}
+
+async function scavengeCrashedClientMarkerTemp(markerRoot, entry, match, platform) {
+  const temporary = path.join(markerRoot, entry.name);
+  const before = await lstat(temporary);
+  const ownerPrivate =
+    platform === "win32" ||
+    (((before.mode & 0o077) === 0) &&
+      (typeof process.getuid !== "function" || before.uid === process.getuid()));
+  if (
+    !before.isFile() ||
+    before.isSymbolicLink() ||
+    before.size > 2048 ||
+    !ownerPrivate
+  ) {
+    throw new Error("installed client reconciliation marker inventory is invalid");
+  }
+  const pid = Number(match[2]);
+  if (!Number.isSafeInteger(pid) || pid <= 0 || processIsAlive(pid)) {
+    throw new Error("installed client reconciliation marker write is in progress");
+  }
+  const after = await lstat(temporary);
+  if (
+    before.dev !== after.dev ||
+    before.ino !== after.ino ||
+    before.size !== after.size ||
+    before.mtimeMs !== after.mtimeMs
+  ) {
+    throw new Error("installed client reconciliation marker temp changed during inspection");
+  }
+  await rm(temporary);
+}
+
+async function retainedRuntimeDigests(
+  markerRoot,
+  platform,
+  { replacementName, replacementSha256 } = {},
+) {
+  if (
+    (replacementName === undefined) !== (replacementSha256 === undefined) ||
+    (replacementName !== undefined &&
+      (!CLIENT_MARKER_NAME.test(replacementName) ||
+        !/^[0-9a-f]{64}$/.test(replacementSha256)))
+  ) {
+    throw new Error("installed client reconciliation runtime authority is invalid");
+  }
+  let entries;
+  try {
+    const metadata = await lstat(markerRoot);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      throw new Error("installed client reconciliation marker inventory is invalid");
+    }
+    entries = await readdir(markerRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      entries = [];
+    } else {
+      throw error;
+    }
+  }
+  if (entries.length > MAX_CLIENT_MARKERS + MAX_CLIENT_MARKER_TEMPS) {
+    throw new Error("installed client reconciliation marker inventory is invalid");
+  }
+  const markerEntries = [];
+  const temporaryEntries = [];
+  for (const entry of entries) {
+    const temporary = CLIENT_MARKER_TEMP_NAME.exec(entry.name);
+    if (entry.isFile() && !entry.isSymbolicLink() && CLIENT_MARKER_NAME.test(entry.name)) {
+      markerEntries.push(entry);
+    } else if (entry.isFile() && !entry.isSymbolicLink() && temporary !== null) {
+      temporaryEntries.push([entry, temporary]);
+    } else {
+      throw new Error("installed client reconciliation marker inventory is invalid");
+    }
+  }
+  if (
+    markerEntries.length > MAX_CLIENT_MARKERS ||
+    temporaryEntries.length > MAX_CLIENT_MARKER_TEMPS
+  ) {
+    throw new Error("installed client reconciliation marker inventory is invalid");
+  }
+  for (const [entry, match] of temporaryEntries) {
+    await scavengeCrashedClientMarkerTemp(markerRoot, entry, match, platform);
+  }
+  const retained = new Set();
+  let replaced = false;
+  for (const entry of markerEntries) {
+    const marker = await readStableClientMarker(path.join(markerRoot, entry.name));
+    if (marker.platform !== platform || clientMarkerFileName(marker) !== entry.name) {
+      throw new Error("installed client reconciliation marker inventory is invalid");
+    }
+    if (entry.name === replacementName) {
+      retained.add(replacementSha256);
+      replaced = true;
+    } else {
+      retained.add(marker.runtime_sha256);
+    }
+  }
+  if (replacementName !== undefined && !replaced) {
+    retained.add(replacementSha256);
+  }
+  if (retained.size > MAX_RETAINED_CLIENT_RUNTIMES) {
+    throw new Error("installed client reconciliation runtime authority exceeds its bound");
+  }
+  return [...retained];
+}
+
+/** Read the runtime digests still referenced by every authenticated profile marker. */
+export async function installedClientRuntimeDigests({
+  environment = process.env,
+  platform = process.platform,
+} = {}) {
+  return retainedRuntimeDigests(defaultClientMarkerRoot(environment, platform), platform);
+}
+
+/** Reconcile exact-owned client launchers once for this installed package. */
+export async function reconcileInstalledClients({
+  environment = process.env,
+  platform = process.platform,
+  version,
+  markerPath,
+  resolveBinary = resolveNativeBinary,
+  prepareLauncher = (binary) =>
+    prepareNativeLaunch(binary, ["setup", "codex"], { platform, version, environment }),
+  retireLauncher = (launcher, runtimeSha256, preserveSha256) =>
+    retireHistoricalRuntimes(launcher, {
+      expectedSha256: runtimeSha256,
+      preserveSha256,
+    }),
+  commands = createCommandAdapter({ environment, platform }),
+} = {}) {
+  if (isTransactionStagedInstall(environment, platform)) {
+    return { status: "staged_candidate" };
+  }
+  if (!PUBLIC_VERSION.test(version ?? "")) {
+    throw new Error("installed client reconciliation authority is invalid");
+  }
+
+  const binary = await resolveBinary();
+  const initialRuntimeSha256 = await sha256File(binary);
+  const authority = reconciliationAuthority({
+    environment,
+    platform,
+    version,
+    runtimeSha256: initialRuntimeSha256,
+  });
+  const explicitMarker = markerPath !== undefined;
+  const scopedMarker = markerPath ?? defaultClientMarker(environment, platform, authority);
+  if (!path.isAbsolute(scopedMarker)) {
+    throw new Error("installed client reconciliation authority is invalid");
+  }
+  const markerRoot = path.dirname(scopedMarker);
+  if (!explicitMarker) {
+    await retainedRuntimeDigests(markerRoot, platform, {
+        replacementName: path.basename(scopedMarker),
+        replacementSha256: authority.runtime_sha256,
+      });
+  }
+  if (await readClientMarker(scopedMarker, authority)) {
+    const expectedLauncher = materializedRuntimePath({
+      version,
+      sha256: authority.runtime_sha256,
+      platform,
+      environment,
+    });
+    let launcher = expectedLauncher;
+    try {
+      if ((await sha256File(expectedLauncher)) !== authority.runtime_sha256) {
+        throw new Error("cached runtime does not match its reconciliation marker");
+      }
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      if ((await sha256File(binary)) !== initialRuntimeSha256) {
+        throw new Error("installed Mikie runtime changed during client reconciliation");
+      }
+      launcher = await prepareLauncher(binary);
+      if (
+        pathIdentity(launcher, platform) !== pathIdentity(expectedLauncher, platform) ||
+        (await sha256File(binary)) !== initialRuntimeSha256 ||
+        (await sha256File(launcher)) !== initialRuntimeSha256
+      ) {
+        throw new Error("materialized Mikie runtime does not match its reconciliation marker");
+      }
+    }
+    if (!(await readClientMarker(scopedMarker, authority))) {
+      throw new Error("installed client reconciliation marker changed during runtime recovery");
+    }
+    const preserved = explicitMarker
+      ? [authority.runtime_sha256]
+      : await retainedRuntimeDigests(markerRoot, platform);
+    await retireLauncher(launcher, authority.runtime_sha256, preserved);
+    return { status: "current" };
+  }
+  const finalLauncher = await prepareLauncher(binary);
+  if (![binary, finalLauncher].every((value) => typeof value === "string" && path.isAbsolute(value))) {
+    throw new Error("installed client reconciliation authority is invalid");
+  }
+  const baseEnvironment = {
+    MIKIE_DISTRIBUTION_MODE: "npm",
+    MIKIE_NPM_UPDATE_TOPOLOGY: "npm_global",
+    MIKIE_UPDATE_REPAIR_CANDIDATE: binary,
+    MIKIE_UPDATE_REPAIR_LAUNCHER: finalLauncher,
+  };
+  const prepared = await commands.run(binary, CLIENT_REPAIR_ARGUMENTS, {
+    shell: false,
+    capture: true,
+    environment: { ...baseEnvironment, MIKIE_NPM_UPDATE_REPAIR_PHASE: "prepare" },
+  });
+  const preparedReceipt = parseClientRepair(prepared.stdout, prepared.code);
+  const settlementPhase = preparedReceipt.action === "refused" ? "rollback" : "commit";
+  const committed = await commands.run(binary, CLIENT_REPAIR_ARGUMENTS, {
+    shell: false,
+    capture: true,
+    environment: { ...baseEnvironment, MIKIE_NPM_UPDATE_REPAIR_PHASE: settlementPhase },
+  });
+  parseClientSettlement(committed.stdout, committed.code, settlementPhase);
+  if (preparedReceipt.action === "refused") {
+    throw new Error(
+      "Mikie could not authenticate every configured client; close active clients and run `mikie update` before reinstalling",
+    );
+  }
+  if ((await sha256File(binary)) !== initialRuntimeSha256) {
+    throw new Error("installed Mikie runtime changed during client reconciliation");
+  }
+  if ((await sha256File(finalLauncher)) !== initialRuntimeSha256) {
+    throw new Error("materialized Mikie runtime does not match the installed package");
+  }
+  await writeClientMarker(scopedMarker, authority);
+  const preserved = explicitMarker
+    ? [authority.runtime_sha256]
+    : await retainedRuntimeDigests(markerRoot, platform);
+  await retireLauncher(finalLauncher, authority.runtime_sha256, preserved);
+  return { status: "reconciled", finalLauncher };
+}
+
 const scriptIdentity = pathIdentity(fileURLToPath(import.meta.url), process.platform);
 const invokedIdentity = pathIdentity(process.argv[1], process.platform);
 if (scriptIdentity !== null && scriptIdentity === invokedIdentity) {
   try {
     await reconcileInstalledTrajectory();
+    const packageMetadata = JSON.parse(
+      await readFile(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"),
+    );
+    await reconcileInstalledClients({ version: packageMetadata.version });
   } catch (error) {
     console.error(`Mikie install reconciliation failed: ${error.message}`);
     process.exitCode = 1;