@uniqbit/mate-core 0.18.3-canary.0 → 0.18.3

package/src/runtime/claude-hook-group.ts

@@ -0,0 +1,21 @@
+/**
+ * Claude hook-group shape and its one identity. A `runtime/` leaf so hooks and
+ * Wrap State can compare groups without loading setup code.
+ */
+
+export interface ClaudeHookCommand {
+  type?: string;
+  command?: string;
+  args?: string[];
+  timeout?: number;
+}
+
+export interface ClaudeHookGroup {
+  matcher?: string;
+  hooks?: ClaudeHookCommand[];
+}
+
+/** The one hook-group identity: structurally identical groups are the same group. */
+export function hookGroupKey(group: ClaudeHookGroup): string {
+  return JSON.stringify(group);
+}

package/src/runtime/companion-lock.ts

@@ -0,0 +1,121 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import crypto from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { mateHome } from "./runtime-directory";
+
+/**
+ * Per-companion lock under `<mate home>/locks/`, outside the companion's tree;
+ * repos share a companion, so a per-repo lock would race pulls. Re-entrant per
+ * async call chain, not per process.
+ */
+
+export interface CompanionLockOptions {
+  homeDir?: string;
+  /** `false` tries once and returns `acquired: false` at once when the lock is held. */
+  wait?: boolean;
+  /** How long to wait for another holder before giving up. */
+  timeoutMs?: number;
+  pollMs?: number;
+  /** Called once, when the lock is found held and the caller starts waiting. */
+  onWait?: () => void;
+}
+
+export type CompanionLockResult<T> = { acquired: true; value: T } | { acquired: false };
+
+function companionKey(companionPath: string): string {
+  let resolved = path.resolve(companionPath);
+  try {
+    resolved = fsSync.realpathSync(resolved);
+  } catch {
+    /* an unresolvable companion is still keyed by its spelling */
+  }
+  return crypto.createHash("sha256").update(resolved).digest("hex").slice(0, 32);
+}
+
+export function companionLockPath(companionPath: string, homeDir?: string): string {
+  return path.join(mateHome(homeDir), "locks", `${companionKey(companionPath)}.lock`);
+}
+
+const heldLocks = new AsyncLocalStorage<ReadonlySet<string>>();
+
+/** An unreadable holder id is only trusted this long, so a corrupt lock cannot block forever. */
+const UNREADABLE_LOCK_GRACE_MS = 10_000;
+
+async function holderAlive(lockPath: string, raw: string): Promise<boolean> {
+  const pid = Number.parseInt(raw.trim(), 10);
+  if (!Number.isInteger(pid) || pid <= 0) {
+    const stat = await fs.stat(lockPath).catch(() => null);
+    return stat !== null && Date.now() - stat.mtimeMs < UNREADABLE_LOCK_GRACE_MS;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * The holder's pid is written to a private file first and hard-linked into
+ * place, so the lock never exists without its holder: a contender reading an
+ * empty file in between would otherwise take it as stale and remove it.
+ */
+async function tryAcquire(lockPath: string): Promise<boolean> {
+  const tempPath = `${lockPath}.${crypto.randomUUID()}.tmp`;
+  await fs.writeFile(tempPath, String(process.pid));
+  try {
+    await fs.link(tempPath, lockPath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  } finally {
+    await fs.rm(tempPath, { force: true });
+  }
+  const raw = await fs.readFile(lockPath, "utf8").catch(() => null);
+  if (raw === null || (await holderAlive(lockPath, raw))) return false;
+  /** A dead holder's lock is removed only if it is still the one just read. */
+  if ((await fs.readFile(lockPath, "utf8").catch(() => null)) === raw) {
+    await fs.rm(lockPath, { force: true });
+  }
+  return false;
+}
+
+/**
+ * Runs `task` while holding the companion's lock; `acquired: false` after the
+ * bounded wait, or at once with `wait: false`. A caller already holding it in
+ * this call chain runs `task` directly.
+ */
+export async function withCompanionLock<T>(
+  companionPath: string,
+  options: CompanionLockOptions,
+  task: () => Promise<T>,
+): Promise<CompanionLockResult<T>> {
+  const lockPath = companionLockPath(companionPath, options.homeDir);
+  const held = heldLocks.getStore() ?? new Set<string>();
+  if (held.has(lockPath)) return { acquired: true, value: await task() };
+
+  const timeoutMs = options.wait === false ? 0 : (options.timeoutMs ?? 30_000);
+  const pollMs = options.pollMs ?? 200;
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+
+  const deadline = Date.now() + timeoutMs;
+  let waiting = false;
+  // oxlint-disable-next-line no-await-in-loop -- polling is the point
+  while (!(await tryAcquire(lockPath))) {
+    if (Date.now() >= deadline) return { acquired: false };
+    if (!waiting) {
+      waiting = true;
+      options.onWait?.();
+    }
+    // oxlint-disable-next-line no-await-in-loop
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  try {
+    return { acquired: true, value: await heldLocks.run(new Set([...held, lockPath]), task) };
+  } finally {
+    await fs.rm(lockPath, { force: true });
+  }
+}

package/src/runtime/companion-sync.ts

@@ -30,6 +30,7 @@ import {
   type CompanionForkState,
   type CompanionGit,
 } from "./companion-git";
+import { withCompanionLock } from "./companion-lock";
 import { hasLaunchEnvironment } from "./env";
 import { FRAMEWORK_NAME } from "./framework";
 import { readCompanionPolicy } from "./policy";
@@ -37,10 +38,20 @@ import { readCompanionPolicy } from "./policy";
 /** The one command that finishes what the unattended half declines to do. */
 export const COMPANION_SYNC_COMMAND = `${FRAMEWORK_NAME} companion sync`;
 
+/** OpenCode's recovery is the managed launch: it runs the sync at a terminal that can answer Git. */
+export const OPENCODE_LAUNCH_COMMAND = `${FRAMEWORK_NAME} opencode`;
+
+/** A Claude-wrapped repository's equivalent: the attended launch reconciles the wrap. */
+export const CLAUDE_LAUNCH_COMMAND = `${FRAMEWORK_NAME} claude`;
+
+/** Which runtime's operator reads the note; it decides the recovery named. */
+export type StalenessAudience = "claude" | "opencode";
+
 /** A cold link costs this once; the recorded completion then suppresses retries. */
 export const COMPANION_SYNC_TIMEOUT_MS = 20_000;
 
-export type UnattendedSyncStatus = "not-applicable" | "fresh" | "complete" | "unfinished";
+/** `busy`: another operation held the companion lock; nothing ran and nothing is owed. */
+export type UnattendedSyncStatus = "not-applicable" | "fresh" | "busy" | "complete" | "unfinished";
 
 export interface UnattendedSyncOutcome {
   status: UnattendedSyncStatus;
@@ -58,6 +69,12 @@ export interface UnattendedSyncOptions {
   homeDir?: string;
   /** Environment Git runs with. */
   env?: Record<string, string | undefined>;
+  /**
+   * `wait` (the default) queues behind another holder of the companion lock,
+   * within the time budget; `try` skips at once, for a hook that must not
+   * stall a session start.
+   */
+  lock?: "wait" | "try";
 }
 
 const UNFINISHED_GIT_PATHS = [
@@ -115,6 +132,24 @@ export async function syncCompanionUnattended(
     return { status: "fresh", changed: false, companionPath };
   }
 
+  const locked = await withCompanionLock(
+    companionPath,
+    { homeDir, wait: options.lock !== "try", timeoutMs },
+    () => syncHoldingLock(companionPath, { timeoutMs, now, homeDir, env }),
+  );
+  return locked.acquired ? locked.value : { status: "busy", changed: false, companionPath };
+}
+
+async function syncHoldingLock(
+  companionPath: string,
+  options: {
+    timeoutMs: number;
+    now: Date;
+    homeDir?: string;
+    env?: Record<string, string | undefined>;
+  },
+): Promise<UnattendedSyncOutcome> {
+  const { timeoutMs, now, homeDir, env } = options;
   const git = companionGit(companionPath, {
     prompt: "never",
     budgetMs: timeoutMs,
@@ -191,13 +226,36 @@ export async function syncCompanionUnattended(
  * answer a credential prompt and no way to tell a fast-forward from a
  * conflicted rebase.
  */
-export function unattendedSyncStalenessLines(outcome: UnattendedSyncOutcome): string[] {
+export function unattendedSyncStalenessLines(
+  outcome: UnattendedSyncOutcome,
+  audience: StalenessAudience = "claude",
+): string[] {
   if (outcome.status !== "unfinished") return [];
+  const reason = outcome.reason ?? "unknown reason";
+  if (audience === "opencode") return launchRecoveryStalenessLines(outcome, ["opencode"]);
   return [
-    `companion Git synchronization unfinished: ${outcome.reason ?? "unknown reason"} — run \`${COMPANION_SYNC_COMMAND}\``,
+    `companion Git synchronization unfinished: ${reason} — run \`${COMPANION_SYNC_COMMAND}\``,
   ];
 }
 
+/**
+ * The note for a session prepare, naming the managed launch of each wrapped
+ * runtime as the recovery: it runs the sync at a terminal that can answer Git.
+ */
+export function launchRecoveryStalenessLines(
+  outcome: UnattendedSyncOutcome,
+  runtimes: readonly StalenessAudience[],
+): string[] {
+  if (outcome.status !== "unfinished") return [];
+  const reason = outcome.reason ?? "unknown reason";
+  const wrapped = new Set(runtimes);
+  const launches = [
+    ...(wrapped.has("claude") ? [CLAUDE_LAUNCH_COMMAND] : []),
+    ...(wrapped.has("opencode") || wrapped.size === 0 ? [OPENCODE_LAUNCH_COMMAND] : []),
+  ].map((command) => `\`${command}\``);
+  return [`Companion not updated: ${reason}. Restart with ${launches.join(" or ")} to fix it.`];
+}
+
 /**
  * The note a session-state reader surfaces, taken from the persisted record so
  * a render costs no Git. Operator-facing only, exactly as the live note is.
@@ -205,16 +263,15 @@ export function unattendedSyncStalenessLines(outcome: UnattendedSyncOutcome): st
 export function persistedCompanionGitStalenessLines(
   companionPath: string,
   homeDir?: string,
+  audience: StalenessAudience = "claude",
 ): string[] {
   if (!companionPath) return [];
   const reason = readCompanionGitRecord(companionPath, homeDir).unfinishedReason;
   if (!reason) return [];
-  return unattendedSyncStalenessLines({
-    status: "unfinished",
-    changed: false,
-    companionPath,
-    reason,
-  });
+  return unattendedSyncStalenessLines(
+    { status: "unfinished", changed: false, companionPath, reason },
+    audience,
+  );
 }
 
 export interface ForkGuardOptions {

package/src/runtime/runtime-directory.ts

@@ -0,0 +1,43 @@
+import os from "node:os";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "./framework";
+
+/**
+ * Stable, install-independent paths to the installed Mate runtime assets.
+ * Documents written into a Working Repository name these, never the
+ * version-bound install path, so a reinstall or Node switch is repaired by the
+ * next `mate` run instead of a re-wrap.
+ */
+
+/** `HOME` first, matching the companion Git state: an OpenCode service inherits the user's. */
+export function mateHome(homeDir?: string): string {
+  return path.join(homeDir || process.env.HOME || os.homedir(), `.${FRAMEWORK_NAME}`);
+}
+
+export function runtimeDirectoryPath(homeDir?: string): string {
+  return path.join(mateHome(homeDir), "runtime");
+}
+
+export function runtimeOpenCodePluginRoot(homeDir?: string): string {
+  return path.join(runtimeDirectoryPath(homeDir), "opencode-plugin");
+}
+
+export function runtimeClaudePluginRoot(homeDir?: string): string {
+  return path.join(runtimeDirectoryPath(homeDir), "claude-plugin");
+}
+
+export function runtimeWrapperBinPath(homeDir?: string): string {
+  return path.join(runtimeDirectoryPath(homeDir), "wrappers", "bin");
+}
+
+export function runtimeMateBin(
+  homeDir?: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  return path.join(
+    runtimeDirectoryPath(homeDir),
+    "bin",
+    platform === "win32" ? `${FRAMEWORK_NAME}.cmd` : FRAMEWORK_NAME,
+  );
+}

package/src/runtime/runtime-document-manifest.ts

@@ -0,0 +1,335 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { repoLocalDirPath } from "./repo-local";
+import { writeAtomic } from "./write-atomic";
+
+/**
+ * Runtime document manifest at the Projection Root; sole owner of its format.
+ * Pure queries plus a thin I/O shell; readers go through Wrap State (`./wrap-state`).
+ */
+
+const RUNTIME_DOCUMENT_MANIFEST_FILE = "runtime-documents.json";
+
+/** Destinations, repo-relative POSIX. Here so the plugin needn't load the projection owner. */
+export const CLAUDE_SETTINGS_DOCUMENT = ".claude/settings.local.json";
+export const CLAUDE_MCP_DOCUMENT = ".mcp.json";
+export const OPENCODE_CONFIG_DOCUMENT = ".opencode/opencode.json";
+
+/**
+ * Only destination outside the repo: local-scope `projects[<repo>].mcpServers`
+ * is the sole channel live on first use (`.mcp.json` servers await approval).
+ * `~`-prefixed so the manifest stays machine-independent.
+ */
+export const CLAUDE_LOCAL_CONFIG_DOCUMENT = "~/.claude.json";
+
+/** Where in {@link OPENCODE_CONFIG_DOCUMENT} the wrap renders its MCP servers. */
+export const OPENCODE_MCP_SERVERS_AT: readonly string[] = Object.freeze(["mcp", "servers"]);
+
+/** The Agent Runtimes a wrap places documents or copies for. */
+export type WrapRuntime = "claude" | "opencode";
+
+/**
+ * A Mate-maintained region, recorded (JSON has no comments): `list` appends,
+ * `map` sets by key, `value` sets one key; removal takes back exactly those.
+ * `stripPrefix` also deletes matching keys Mate didn't write, never restored.
+ * A yielding `value` gives way to an existing key at placement. Only applied
+ * regions are recorded.
+ */
+export type ManagedRegion =
+  | { readonly at: string[]; readonly kind: "list"; readonly values: unknown[] }
+  | {
+      readonly at: string[];
+      readonly kind: "map";
+      readonly entries: Record<string, unknown>;
+      readonly stripPrefix?: string;
+    }
+  | {
+      readonly at: string[];
+      readonly kind: "value";
+      readonly value: unknown;
+      /** Applied only when the key is absent once the prior pass is withdrawn. */
+      readonly yields?: true;
+    };
+
+/**
+ * What a Runtime Surface hands the Projection Root: the managed content of one
+ * document, without a destination. The surface renders; the entry places.
+ */
+export interface RenderedRuntimeDocument {
+  /** Repo-relative with POSIX separators, or `~/`-prefixed for a user-global target. */
+  readonly path: string;
+  readonly regions: readonly ManagedRegion[];
+}
+
+/** An owned companion copy: the hash of what Mate last wrote there. */
+export interface CopyRecord {
+  runtime: WrapRuntime;
+  sha256: string;
+}
+
+/** A link Mate created; `target` is absolute, so a repointed link no longer matches. */
+export interface LinkRecord {
+  runtime: WrapRuntime;
+  target: string;
+}
+
+/** `runtimes` sits beside `documents` so `documents` keeps its region-array shape. */
+export interface Manifest {
+  readonly documents: Readonly<Record<string, ManagedRegion[]>>;
+  readonly runtimes: Readonly<Record<string, WrapRuntime>>;
+  readonly copies: Readonly<Record<string, CopyRecord>>;
+  readonly links: Readonly<Record<string, LinkRecord>>;
+}
+
+export const EMPTY_MANIFEST: Manifest = Object.freeze({
+  documents: Object.freeze({}),
+  runtimes: Object.freeze({}),
+  copies: Object.freeze({}),
+  links: Object.freeze({}),
+});
+
+/** Legacy manifests carry no tag; every destination Mate ever wrote is runtime-specific by path. */
+export function documentRuntime(documentPath: string): WrapRuntime {
+  return documentPath.startsWith(".opencode/") ? "opencode" : "claude";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Never throws: an absent, unparseable or foreign manifest reads as empty — Mate can rebuild it. */
+export function parseManifest(raw: string | null): Manifest {
+  if (raw === null) return EMPTY_MANIFEST;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return EMPTY_MANIFEST;
+  }
+  return isRecord(parsed) ? manifestOf(parsed) : EMPTY_MANIFEST;
+}
+
+/** For readers that rewrite on its strength: a manifest present but unparseable throws. */
+export function parseManifestStrict(raw: string | null): Manifest {
+  if (raw === null) return EMPTY_MANIFEST;
+  const parsed = JSON.parse(raw) as unknown;
+  if (!isRecord(parsed)) throw new Error("runtime document manifest is not a JSON object");
+  return manifestOf(parsed);
+}
+
+function manifestOf(parsed: Record<string, unknown>): Manifest {
+  return {
+    documents: isRecord(parsed.documents) ? (parsed.documents as Manifest["documents"]) : {},
+    runtimes: isRecord(parsed.runtimes) ? (parsed.runtimes as Manifest["runtimes"]) : {},
+    copies: isRecord(parsed.copies) ? (parsed.copies as Manifest["copies"]) : {},
+    links: isRecord(parsed.links) ? (parsed.links as Manifest["links"]) : {},
+  };
+}
+
+function recordedRuntime(manifest: Manifest, documentPath: string): WrapRuntime {
+  return manifest.runtimes[documentPath] ?? documentRuntime(documentPath);
+}
+
+/**
+ * `null` means the manifest records nothing and its file should not exist.
+ * `runtimes` is rebuilt from `documents`, so a legacy manifest is tagged on its
+ * next write and a withdrawn document leaves no stale tag behind.
+ */
+export function serializeManifest(manifest: Manifest): string | null {
+  const recorded = Object.keys(manifest.documents);
+  const copied = Object.keys(manifest.copies);
+  const linked = Object.keys(manifest.links);
+  if (recorded.length === 0 && copied.length === 0 && linked.length === 0) return null;
+  const runtimes = Object.fromEntries(
+    recorded.map((documentPath) => [documentPath, recordedRuntime(manifest, documentPath)]),
+  );
+  return `${JSON.stringify(
+    {
+      documents: manifest.documents,
+      ...(recorded.length > 0 ? { runtimes } : {}),
+      ...(copied.length > 0 ? { copies: manifest.copies } : {}),
+      ...(linked.length > 0 ? { links: manifest.links } : {}),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * Every destination the manifest records, in the order it recorded them,
+ * optionally only one runtime's. The manifest is written only by a pass that
+ * placed a runtime document or a copy, and `mate wrap` is the only such pass.
+ */
+export function documents(manifest: Manifest, runtime?: WrapRuntime): string[] {
+  return Object.keys(manifest.documents).filter(
+    (documentPath) => !runtime || recordedRuntime(manifest, documentPath) === runtime,
+  );
+}
+
+/** One destination's recorded regions; `undefined` when unrecorded or malformed. */
+export function documentRegions(
+  manifest: Manifest,
+  documentPath: string,
+): readonly ManagedRegion[] | undefined {
+  const recorded: unknown = manifest.documents[documentPath];
+  return Array.isArray(recorded) ? (recorded as ManagedRegion[]) : undefined;
+}
+
+/** Owned companion copies, keyed by repo-relative POSIX path. */
+export function copies(manifest: Manifest, runtime?: WrapRuntime): Record<string, CopyRecord> {
+  return Object.fromEntries(
+    Object.entries(manifest.copies).filter(
+      ([, record]) => !runtime || (isRecord(record) && record.runtime === runtime),
+    ),
+  );
+}
+
+/** Links Mate created, keyed by repo-relative POSIX path. */
+export function links(manifest: Manifest, runtime?: WrapRuntime): Record<string, LinkRecord> {
+  return Object.fromEntries(
+    Object.entries(manifest.links).filter(
+      ([, record]) =>
+        isRecord(record) &&
+        typeof record.target === "string" &&
+        (!runtime || record.runtime === runtime),
+    ),
+  );
+}
+
+function isAt(at: unknown, address: readonly string[]): boolean {
+  return (
+    Array.isArray(at) &&
+    at.length === address.length &&
+    at.every((key, index) => key === address[index])
+  );
+}
+
+/**
+ * The keys of the `map` regions recorded at `at` in one document. Shapes are
+ * checked rather than trusted: a hand-edited manifest reads as no keys, never
+ * as a throw.
+ */
+export function recordedMapKeys(
+  manifest: Manifest,
+  documentPath: string,
+  at: readonly string[],
+): string[] {
+  return (documentRegions(manifest, documentPath) ?? []).flatMap((region: unknown) =>
+    isRecord(region) && region.kind === "map" && isAt(region.at, at) && isRecord(region.entries)
+      ? Object.keys(region.entries)
+      : [],
+  );
+}
+
+/** Every value of the `list` regions recorded under `prefix` in one document. */
+export function recordedListValues(
+  manifest: Manifest,
+  documentPath: string,
+  prefix: readonly string[],
+): unknown[] {
+  return (documentRegions(manifest, documentPath) ?? []).flatMap((region: unknown) =>
+    isRecord(region) &&
+    region.kind === "list" &&
+    Array.isArray(region.at) &&
+    isAt(region.at.slice(0, prefix.length), prefix) &&
+    Array.isArray(region.values)
+      ? region.values
+      : [],
+  );
+}
+
+/** Records a destination's regions, or withdraws it when `regions` is undefined. */
+export function withDocument(
+  manifest: Manifest,
+  documentPath: string,
+  regions: readonly ManagedRegion[] | undefined,
+): Manifest {
+  if (regions === undefined) return withoutDocuments(manifest, [documentPath]);
+  return {
+    ...manifest,
+    documents: { ...manifest.documents, [documentPath]: [...regions] },
+  };
+}
+
+export function withoutDocuments(manifest: Manifest, documentPaths: readonly string[]): Manifest {
+  const removed = new Set(documentPaths);
+  return {
+    ...manifest,
+    documents: Object.fromEntries(
+      Object.entries(manifest.documents).filter(([documentPath]) => !removed.has(documentPath)),
+    ),
+  };
+}
+
+/** Replaces one runtime's records, leaving every other record as it is. */
+function replaceRuntimeRecords<T>(
+  existing: Readonly<Record<string, T>>,
+  runtime: WrapRuntime,
+  records: Readonly<Record<string, T>>,
+): Record<string, T> {
+  const kept = Object.entries(existing).filter(
+    ([, record]) => !(isRecord(record) && record.runtime === runtime),
+  );
+  return { ...Object.fromEntries(kept), ...records };
+}
+
+export function withCopies(
+  manifest: Manifest,
+  runtime: WrapRuntime,
+  records: Readonly<Record<string, CopyRecord>>,
+): Manifest {
+  return { ...manifest, copies: replaceRuntimeRecords(manifest.copies, runtime, records) };
+}
+
+export function withLinks(
+  manifest: Manifest,
+  runtime: WrapRuntime,
+  records: Readonly<Record<string, LinkRecord>>,
+): Manifest {
+  return { ...manifest, links: replaceRuntimeRecords(manifest.links, runtime, records) };
+}
+
+export function manifestPath(repoPath: string): string {
+  return path.join(repoLocalDirPath(repoPath), RUNTIME_DOCUMENT_MANIFEST_FILE);
+}
+
+/**
+ * The runtime document manifest at the Projection Root; empty when absent. A
+ * read that failed for a reason other than absence throws, so a writer never
+ * replaces a manifest it could not read.
+ */
+export async function readManifest(repoPath: string): Promise<Manifest> {
+  return parseManifest(await readManifestText(repoPath));
+}
+
+/** `null` when absent; any other read failure throws. */
+export async function readManifestText(repoPath: string): Promise<string | null> {
+  try {
+    return await fsp.readFile(manifestPath(repoPath), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    return null;
+  }
+}
+
+/**
+ * The one way the manifest changes: read, edit, then write it atomically — or
+ * delete it once it records nothing. Every writer goes through here, so none
+ * can drop another's records.
+ */
+export async function updateManifest(
+  repoPath: string,
+  edit: (manifest: Manifest) => Manifest,
+): Promise<Manifest> {
+  const next = edit(await readManifest(repoPath));
+  const target = manifestPath(repoPath);
+  const contents = serializeManifest(next);
+  if (contents === null) {
+    await fsp.unlink(target).catch(() => {});
+  } else {
+    await fsp.mkdir(path.dirname(target), { recursive: true });
+    await writeAtomic(target, contents);
+  }
+  return next;
+}