@awak-app/simy-cli 0.4.0 → 0.5.1

package/src/index.js

@@ -2,6 +2,7 @@
 
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
 
 import { startAgent } from "./agent.js";
 import {
@@ -9,6 +10,8 @@ import {
   createCliAutoUpdater,
   readCliPackageInfo,
   restartDaemonProcess,
+  runCliUpdateGate,
+  shouldRetryIncompatibleCli,
   writeUpdateHandoffFromEnvironment,
 } from "./auto-update.js";
 import { openAuthorizationUrl } from "./browser.js";
@@ -20,26 +23,75 @@ import { DEFAULT_WEB_ORIGIN, resolveWebOrigin } from "./web-origin.js";
 
 const argv = process.argv.slice(2);
 const args = new Set(argv);
+const dispatchArgv = argv.filter((value) => value !== "--no-auto-update");
+const entryPath = fileURLToPath(import.meta.url);
+const packageInfo = await readCliPackageInfo();
+const updatesDisabled = args.has("--no-auto-update") || process.env.SIMY_AUTO_UPDATE === "0";
 
-if (argv[0] === "sqm") {
-  const packageInfo = await readCliPackageInfo();
-  try {
-    const { runSqmCommand } = await import("./sqm/command.js");
-    process.exitCode = await runSqmCommand(argv.slice(1), { cliVersion: packageInfo.version });
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 2;
+if (dispatchArgv[0] === "update") {
+  const checkOnly = args.has("--check");
+  const result = await runCliUpdateGate({
+    argv,
+    packageInfo,
+    mode: checkOnly ? "check" : "update",
+    disabled: updatesDisabled,
+    allowMajor: args.has("--yes"),
+    confirmMajor: confirmMajorUpdate,
+  });
+  process.exitCode = ["check_failed", "install_failed"].includes(result.outcome) ? 1 : 0;
+} else {
+  const startupUpdate = await runCliUpdateGate({
+    argv,
+    packageInfo,
+    entryPath,
+    disabled: updatesDisabled,
+  });
+  if (startupUpdate.reexecuted) {
+    process.exitCode = startupUpdate.exitCode;
+  } else {
+    await runCommand();
   }
-  process.exit();
 }
 
-if (args.has("--help") || args.has("-h")) {
-  console.log(`Usage:
+async function runCommand() {
+  if (dispatchArgv[0] === "sqm") {
+    try {
+      const { runSqmCommand } = await import("./sqm/command.js");
+      process.exitCode = await runSqmCommand(dispatchArgv.slice(1), { cliVersion: packageInfo.version });
+    } catch (error) {
+      if (shouldRetryIncompatibleCli(error)) {
+        const retried = await runCliUpdateGate({
+          argv,
+          packageInfo,
+          entryPath,
+          mode: "incompatible",
+          disabled: updatesDisabled,
+          allowMajor: args.has("--yes"),
+          confirmMajor: confirmMajorUpdate,
+          incompatibleRetry: true,
+        });
+        if (retried.reexecuted) {
+          process.exitCode = retried.exitCode;
+          return;
+        }
+        const required = error.minimumVersion ? ` (requires ${error.minimumVersion}+)` : "";
+        console.error(`SQM requires a newer SIMY CLI${required}, but automatic recovery did not install one.`);
+      }
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 2;
+    }
+    return;
+  }
+
+  if (args.has("--help") || args.has("-h")) {
+    console.log(`Usage:
   simy            Start the local SIMY agent
   simy --daemon   Start it in the background
   simy --no-tui   Start the foreground HTTP agent without the interactive console
   simy sqm min-check  Run the fast deterministic SQM diff preflight
   simy sqm check      Run full scenarios, write proof.json, and sign the run
+  simy update --check Check the installed and latest stable CLI versions
+  simy update         Install an eligible stable CLI update
 
 Options:
   --daemon, --deamon  Run detached in the background
@@ -47,73 +99,92 @@ Options:
   --no-open           Do not open the browser when authorization is required
   --port <port>       Bind a specific localhost port
   --host <url>        Connect to a SIMY Web origin (default: ${DEFAULT_WEB_ORIGIN})
-  --no-auto-update    Disable the hourly CLI update check
+  --no-auto-update    Disable update checks and automatic installation
 
 ${autoUpdateHelpText()}
 `);
-  process.exit(0);
-}
+    return;
+  }
 
-const daemon = args.has("--daemon") || args.has("--deamon");
-const interactive = !daemon && !args.has("--no-tui") && process.stdin.isTTY && process.stdout.isTTY;
-const port = readPort(argv);
-const packageInfo = await readCliPackageInfo();
-let webOrigin;
-try {
-  webOrigin = resolveWebOrigin(readOption(argv, "--host"));
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(2);
+  await runLocalAgent();
 }
 
-if (daemon && process.env.SIMY_DAEMON_CHILD !== "1") {
-  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
-    detached: true,
-    stdio: "ignore",
-    env: { ...process.env, SIMY_DAEMON_CHILD: "1" },
-  });
-  child.unref();
-  console.log("SIMY local agent started in the background.");
-  process.exit(0);
-}
+async function runLocalAgent() {
+  const daemon = args.has("--daemon") || args.has("--deamon");
+  const interactive = !daemon && !args.has("--no-tui") && process.stdin.isTTY && process.stdout.isTTY;
+  const port = readPort(argv);
+  let webOrigin;
+  try {
+    webOrigin = resolveWebOrigin(readOption(argv, "--host"));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+    return;
+  }
 
-const updateManager = await createCliAutoUpdater({
-  daemon,
-  interactive,
-  requestedPort: port,
-  disabled: args.has("--no-auto-update") || process.env.SIMY_AUTO_UPDATE === "0",
-  dependencies: { packageInfo },
-});
-const agent = await startAgent({
-  requestedPort: port,
-  daemon,
-  webOrigin,
-  quiet: interactive,
-  updateManager,
-});
-const shutdownAgent = createAgentShutdown(agent);
-installAgentShutdownSignalHandlers({ shutdown: shutdownAgent });
-await writeUpdateHandoffFromEnvironment({ version: packageInfo.version, port: agent.port });
-updateManager.start({
-  registry: agent.registry,
-  restartDaemon: async (targetVersion) => {
-    await restartDaemonProcess({
-      entryPath: fileURLToPath(import.meta.url),
-      argv: process.argv.slice(2),
-      targetVersion,
+  if (daemon && process.env.SIMY_DAEMON_CHILD !== "1") {
+    const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, SIMY_DAEMON_CHILD: "1" },
     });
-    await shutdownAgent();
-  },
-});
-if (agent.loginUrl && !args.has("--no-open")) {
-  await openAuthorizationUrl(agent.loginUrl);
+    child.unref();
+    console.log("SIMY local agent started in the background.");
+    return;
+  }
+
+  const updateManager = await createCliAutoUpdater({
+    daemon,
+    interactive,
+    requestedPort: port,
+    disabled: args.has("--no-auto-update") || process.env.SIMY_AUTO_UPDATE === "0",
+    dependencies: { packageInfo },
+  });
+  const agent = await startAgent({
+    requestedPort: port,
+    daemon,
+    webOrigin,
+    quiet: interactive,
+    updateManager,
+  });
+  const shutdownAgent = createAgentShutdown(agent);
+  installAgentShutdownSignalHandlers({ shutdown: shutdownAgent });
+  await writeUpdateHandoffFromEnvironment({ version: packageInfo.version, port: agent.port });
+  updateManager.start({
+    registry: agent.registry,
+    restartDaemon: async (targetVersion) => {
+      await restartDaemonProcess({
+        entryPath: fileURLToPath(import.meta.url),
+        argv: process.argv.slice(2),
+        targetVersion,
+      });
+      await shutdownAgent();
+    },
+  });
+  if (agent.loginUrl && !args.has("--no-open")) {
+    await openAuthorizationUrl(agent.loginUrl);
+  }
+  if (interactive) {
+    const { runAgenticLoopConsole } = await import("./console/index.js");
+    try {
+      await runAgenticLoopConsole(agent);
+    } finally {
+      await shutdownAgent();
+    }
+  }
 }
-if (interactive) {
-  const { runAgenticLoopConsole } = await import("./console/index.js");
+
+async function confirmMajorUpdate({ currentVersion, latestVersion }) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log(`Major update ${currentVersion} → ${latestVersion} requires confirmation. Re-run with \`simy update --yes\`.`);
+    return false;
+  }
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    await runAgenticLoopConsole(agent);
+    const answer = await prompt.question(`Install major SIMY CLI update ${currentVersion} → ${latestVersion}? [y/N] `);
+    return /^(y|yes)$/i.test(answer.trim());
   } finally {
-    await shutdownAgent();
+    prompt.close();
   }
 }
 

package/src/orchestrator/completion-contract.js

@@ -79,8 +79,14 @@ export function completionEvidenceChecks(charter, attempt) {
   if (contract.version !== COMPLETION_CONTRACT_VERSION) return [];
 
   const uncertainty = normalizeUncertaintyVerification(attempt?.uncertainty_verification);
-  const criterionEvidence = normalizeCriterionEvidence(attempt?.criterion_evidence);
   const rows = acceptanceCriterionRows(charter);
+  const criterionEvidence = normalizeCriterionEvidence(attempt?.criterion_evidence);
+  const expectedCriterionIds = new Set(rows.map((row) => row.id));
+  const unexpectedCriterionIds = uniqueStrings(
+    criterionEvidence
+      .map((item) => item.criterion_id)
+      .filter((criterionId) => !expectedCriterionIds.has(criterionId)),
+  );
   const checks = [
     check(
       "top_uncertainty_recorded",
@@ -110,6 +116,14 @@ export function completionEvidenceChecks(charter, attempt) {
         ? "The executor marked the highest uncertainty resolved with observed evidence."
         : uncertainty.fallback || "The highest uncertainty remains unresolved.",
     ),
+    check(
+      "criterion_evidence_scope",
+      "Criterion evidence matches the charter acceptance criteria",
+      unexpectedCriterionIds.length === 0,
+      unexpectedCriterionIds.length === 0
+        ? "Every criterion evidence row references a chartered acceptance criterion."
+        : `Unexpected criterion evidence: ${unexpectedCriterionIds.join(", ")}.`,
+    ),
   ];
 
   for (const row of rows) {

package/src/sqm/agent-skill.js

@@ -0,0 +1,373 @@
+import { createHash } from "node:crypto";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SQM_AGENT_SKILL_ID = "simy-sqm-pr-check";
+export const SQM_AGENT_SKILL_VERSION = "2.0.0";
+export const SIMY_CODEX_PLUGIN_ID = "simy";
+export const SIMY_CODEX_PLUGIN_VERSION = "0.1.0";
+
+const BUNDLED_CODEX_PLUGIN_ROOT = fileURLToPath(
+  new URL(`../codex-plugins/${SIMY_CODEX_PLUGIN_ID}/`, import.meta.url),
+);
+const MANAGED_PLUGIN_AUTHOR = "Specialist Doctors Inc.";
+const MANAGED_MARKETPLACE_SOURCE = `./plugins/${SIMY_CODEX_PLUGIN_ID}`;
+
+const SKILL_CONTENT = `---
+name: ${SQM_AGENT_SKILL_ID}
+description: Run SIMY Software Quality Monitor checks before creating or proposing a pull request. Use whenever preparing, opening, or updating a PR.
+---
+
+# SIMY SQM PR check
+
+Before creating or proposing a pull request:
+
+1. Run \`simy sqm min-check\` from the repository root.
+2. Run \`simy sqm check --proof proof.json --signed-evidence proof.json.signed.json\`.
+3. Read \`proof.json\` and require \`outcome.status\` to be \`passed\`.
+4. If either command fails, SQM is unavailable, or the proof is not passed, stop. Report the exact blocker and do not create the PR.
+5. Include the proof path and SQM outcome in the PR body when the check passes.
+
+Do not replace SQM with an LLM review, and do not claim the check passed without reading the generated proof.
+`;
+
+const HOOK_SCRIPT = `#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+let raw = "";
+for await (const chunk of process.stdin) raw += chunk;
+let payload = {};
+try { payload = raw ? JSON.parse(raw) : {}; } catch { process.exit(0); }
+const command = String(payload?.tool_input?.command || payload?.tool_input?.cmd || "");
+if (!/(^|[;&|]\\s*)gh\\s+pr\\s+create(?:\\s|$)/.test(command)) process.exit(0);
+
+for (const args of [["sqm", "min-check"], ["sqm", "check"]]) {
+  const result = spawnSync("simy", args, { cwd: process.cwd(), stdio: "inherit" });
+  if (result.error || result.status !== 0) {
+    console.error(result.error ? \`SIMY SQM PR gate failed: \${result.error.message}\` : \`SIMY SQM PR gate blocked the PR (exit \${result.status}).\`);
+    process.exit(2);
+  }
+}
+`;
+
+const TARGETS = {
+  codex: [".agents", "skills", SQM_AGENT_SKILL_ID, "SKILL.md"],
+  claude: [".claude", "skills", SQM_AGENT_SKILL_ID, "SKILL.md"],
+};
+
+export function sqmAgentSkillDigest() {
+  return digestText(SKILL_CONTENT);
+}
+
+export async function inspectSqmAgentSkill({ home = homedir() } = {}) {
+  const digest = sqmAgentSkillDigest();
+  const codexPlugin = await inspectCodexPlugin({ home });
+  const hookPath = managedHookPath(home);
+  const installedHookDigest = await fileDigest(hookPath);
+  const hookMatches = installedHookDigest === digestText(HOOK_SCRIPT);
+  const platforms = {};
+  for (const [platform, segments] of Object.entries(TARGETS)) {
+    const target = path.join(home, ...segments);
+    const installedDigest = await fileDigest(target);
+    const skillMatches = installedDigest === digest;
+    const hookConfigured = await hasManagedHook(platform, home, hookPath);
+    const platformExtraMatches = platform !== "codex" || codexPlugin.installed;
+    platforms[platform] = {
+      path: target,
+      hook_path: platformHookConfigPath(platform, home),
+      installed: skillMatches && hookMatches && hookConfigured && platformExtraMatches,
+      state:
+        installedDigest === null ||
+        !hookConfigured ||
+        installedHookDigest === null ||
+        (platform === "codex" && codexPlugin.state === "missing")
+          ? "missing"
+          : skillMatches && hookMatches && platformExtraMatches
+            ? "installed"
+            : "outdated",
+      ...(platform === "codex" ? { plugin: codexPlugin } : {}),
+    };
+  }
+  return {
+    skill_id: SQM_AGENT_SKILL_ID,
+    version: SQM_AGENT_SKILL_VERSION,
+    digest: `sha256:${digest}`,
+    enforcement: "pre_tool_use",
+    codex_plugin: codexPlugin,
+    installed: Object.values(platforms).every((entry) => entry.installed),
+    platforms,
+  };
+}
+
+export async function installSqmAgentSkill({ home = homedir(), platforms = Object.keys(TARGETS) } = {}) {
+  const requested = [...new Set(platforms)];
+  if (!requested.length || requested.some((platform) => !Object.hasOwn(TARGETS, platform))) {
+    throw new Error("platforms must contain codex and/or claude");
+  }
+  const hookPath = managedHookPath(home);
+  if (requested.includes("codex")) await installCodexPlugin({ home });
+  await atomicText(hookPath, HOOK_SCRIPT, 0o700);
+  for (const platform of requested) {
+    await atomicText(path.join(home, ...TARGETS[platform]), SKILL_CONTENT, 0o600);
+    await installManagedHook(platform, home, hookPath);
+  }
+  return inspectSqmAgentSkill({ home });
+}
+
+export async function inspectCodexPlugin({ home = homedir() } = {}) {
+  const expectedDigest = await directoryDigest(BUNDLED_CODEX_PLUGIN_ROOT);
+  const target = codexPluginPath(home);
+  const installedDigest = await directoryDigest(target, { missing: null });
+  const marketplacePath = codexMarketplacePath(home);
+  const marketplace = await readJsonFile(marketplacePath, { missing: null, invalid: null });
+  const entry = Array.isArray(marketplace?.plugins)
+    ? marketplace.plugins.find((candidate) => candidate?.name === SIMY_CODEX_PLUGIN_ID)
+    : null;
+  const marketplaceMatches = isManagedMarketplaceEntry(entry);
+  const filesMatch = installedDigest === expectedDigest;
+  return {
+    plugin_id: SIMY_CODEX_PLUGIN_ID,
+    version: SIMY_CODEX_PLUGIN_VERSION,
+    path: target,
+    marketplace_path: marketplacePath,
+    digest: `sha256:${expectedDigest}`,
+    installed: filesMatch && marketplaceMatches,
+    state:
+      installedDigest === null || !entry
+        ? "missing"
+        : filesMatch && marketplaceMatches
+          ? "installed"
+          : "outdated",
+  };
+}
+
+async function installCodexPlugin({ home }) {
+  const target = codexPluginPath(home);
+  const marketplacePath = codexMarketplacePath(home);
+  const marketplace = await readJsonFile(marketplacePath, { missing: {}, invalid: "throw" });
+  if (!marketplace || typeof marketplace !== "object" || Array.isArray(marketplace)) {
+    throw new Error(`${marketplacePath} must contain a JSON object before SIMY can install its Codex plugin.`);
+  }
+  const plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+  const collision = plugins.find((entry) => entry?.name === SIMY_CODEX_PLUGIN_ID);
+  if (collision && !isManagedMarketplaceEntry(collision)) {
+    throw new Error(`Codex marketplace already contains an unmanaged ${SIMY_CODEX_PLUGIN_ID} plugin entry.`);
+  }
+  await assertManagedPluginTarget(target);
+
+  const staged = path.join(path.dirname(target), `.${SIMY_CODEX_PLUGIN_ID}.${process.pid}.tmp`);
+  const backup = path.join(path.dirname(target), `.${SIMY_CODEX_PLUGIN_ID}.${process.pid}.bak`);
+  await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  await rm(staged, { recursive: true, force: true });
+  await rm(backup, { recursive: true, force: true });
+  await cp(BUNDLED_CODEX_PLUGIN_ROOT, staged, { recursive: true, errorOnExist: true });
+  let backedUp = false;
+  try {
+    if (await pathExists(target)) {
+      await rename(target, backup);
+      backedUp = true;
+    }
+    await rename(staged, target);
+    if (backedUp) await rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm(staged, { recursive: true, force: true });
+    if (backedUp && !(await pathExists(target))) await rename(backup, target);
+    throw error;
+  }
+
+  const nextMarketplace = {
+    ...marketplace,
+    name: typeof marketplace.name === "string" && marketplace.name.trim()
+      ? marketplace.name
+      : "personal",
+    interface: {
+      displayName: "Personal",
+      ...(marketplace.interface && typeof marketplace.interface === "object"
+        ? marketplace.interface
+        : {}),
+    },
+    plugins: [
+      ...plugins.filter((entry) => entry?.name !== SIMY_CODEX_PLUGIN_ID),
+      managedMarketplaceEntry(),
+    ],
+  };
+  await atomicText(marketplacePath, `${JSON.stringify(nextMarketplace, null, 2)}\n`, 0o600);
+}
+
+function managedMarketplaceEntry() {
+  return {
+    name: SIMY_CODEX_PLUGIN_ID,
+    source: { source: "local", path: MANAGED_MARKETPLACE_SOURCE },
+    policy: { installation: "INSTALLED_BY_DEFAULT", authentication: "ON_INSTALL" },
+    category: "Developer Tools",
+  };
+}
+
+function isManagedMarketplaceEntry(entry) {
+  return entry?.name === SIMY_CODEX_PLUGIN_ID &&
+    entry?.source?.source === "local" &&
+    entry?.source?.path === MANAGED_MARKETPLACE_SOURCE &&
+    entry?.policy?.installation === "INSTALLED_BY_DEFAULT" &&
+    entry?.policy?.authentication === "ON_INSTALL";
+}
+
+async function assertManagedPluginTarget(target) {
+  if (!(await pathExists(target))) return;
+  const manifest = await readJsonFile(path.join(target, ".codex-plugin", "plugin.json"), {
+    missing: null,
+    invalid: null,
+  });
+  if (manifest?.name !== SIMY_CODEX_PLUGIN_ID || manifest?.author?.name !== MANAGED_PLUGIN_AUTHOR) {
+    throw new Error(`${target} already exists and is not a SIMY-managed Codex plugin.`);
+  }
+}
+
+function codexPluginPath(home) {
+  return path.join(home, "plugins", SIMY_CODEX_PLUGIN_ID);
+}
+
+function codexMarketplacePath(home) {
+  return path.join(home, ".agents", "plugins", "marketplace.json");
+}
+
+function managedHookPath(home) {
+  return path.join(home, ".simy", "integrations", "sqm-agent", "pre-pr-hook.mjs");
+}
+
+function platformHookConfigPath(platform, home) {
+  return platform === "codex"
+    ? path.join(home, ".codex", "hooks.json")
+    : path.join(home, ".claude", "settings.json");
+}
+
+function managedHookGroup(hookPath) {
+  return {
+    matcher: "Bash",
+    hooks: [
+      {
+        type: "command",
+        command: `node ${JSON.stringify(hookPath)}`,
+        statusMessage: "Running SIMY SQM PR gate",
+      },
+    ],
+  };
+}
+
+async function installManagedHook(platform, home, hookPath) {
+  const target = platformHookConfigPath(platform, home);
+  let config = {};
+  try {
+    config = JSON.parse(await readFile(target, "utf8"));
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw new Error(`${target} must contain valid JSON before SIMY can merge the SQM hook.`);
+    }
+  }
+  const hooks = config && typeof config === "object" && !Array.isArray(config)
+    ? { ...(config.hooks || {}) }
+    : {};
+  const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+  hooks.PreToolUse = [
+    ...existing.filter((group) => !groupContainsManagedHook(group)),
+    managedHookGroup(hookPath),
+  ];
+  await atomicText(target, `${JSON.stringify({ ...config, hooks }, null, 2)}\n`, 0o600);
+}
+
+async function hasManagedHook(platform, home, hookPath) {
+  try {
+    const config = JSON.parse(await readFile(platformHookConfigPath(platform, home), "utf8"));
+    return Array.isArray(config?.hooks?.PreToolUse) &&
+      config.hooks.PreToolUse.some((group) => groupContainsManagedHook(group, hookPath));
+  } catch (error) {
+    if (error?.code === "ENOENT" || error instanceof SyntaxError) return false;
+    throw error;
+  }
+}
+
+function groupContainsManagedHook(group, expectedPath = null) {
+  if (!Array.isArray(group?.hooks)) return false;
+  return group.hooks.some((hook) => {
+    const command = typeof hook?.command === "string" ? hook.command : "";
+    return expectedPath
+      ? command === `node ${JSON.stringify(expectedPath)}`
+      : command.includes("/.simy/integrations/sqm-agent/pre-pr-hook.mjs") ||
+          command.includes("\\.simy\\integrations\\sqm-agent\\pre-pr-hook.mjs");
+  });
+}
+
+async function fileDigest(target) {
+  try {
+    return digestText(await readFile(target, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+async function directoryDigest(root, { missing = "throw" } = {}) {
+  let rootStat;
+  try {
+    rootStat = await lstat(root);
+  } catch (error) {
+    if (error?.code === "ENOENT" && missing !== "throw") return missing;
+    throw error;
+  }
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new Error(`${root} must be a real directory.`);
+  }
+  const hash = createHash("sha256");
+  const visit = async (directory, prefix = "") => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const target = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`${target} must not be a symbolic link.`);
+      if (entry.isDirectory()) {
+        await visit(target, relative);
+        continue;
+      }
+      if (!entry.isFile()) throw new Error(`${target} must be a regular file.`);
+      hash.update(relative).update("\0").update(await readFile(target)).update("\0");
+    }
+  };
+  await visit(root);
+  return hash.digest("hex");
+}
+
+async function readJsonFile(target, { missing, invalid }) {
+  try {
+    return JSON.parse(await readFile(target, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return missing;
+    if (error instanceof SyntaxError) {
+      if (invalid !== "throw") return invalid;
+      throw new Error(`${target} must contain valid JSON before SIMY can update it.`);
+    }
+    throw error;
+  }
+}
+
+async function pathExists(target) {
+  try {
+    await lstat(target);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function digestText(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function atomicText(target, content, mode) {
+  await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.tmp`;
+  await writeFile(temporary, content, { encoding: "utf8", mode });
+  await rename(temporary, target);
+}