@uniqbit/mate-core 0.18.3-canary.1 → 0.18.4

package/src/runtime/guidance.ts

@@ -1,3 +1,5 @@
+import path from "node:path";
+
 /**
  * Versioned companion guidance contract. The CLI builds the guidance data
  * from its playbooks at launch time and delivers it through the
@@ -16,6 +18,12 @@ export type MateGuidanceFile = {
   companionGuidance: string;
   codebaseExplorationGuidance: string;
   errors: string[];
+  /**
+   * The active audience's layer, for a launch that hosts its own server only.
+   * The plugin applies it only from a payload it trusts; a masked payload
+   * carries none, so the shared service and bare sessions never see one.
+   */
+  audienceLayer?: string;
 };
 
 export type GuidanceValidation = {
@@ -76,12 +84,21 @@ export function validateGuidanceData(value: unknown): GuidanceValidation {
     errors.push("injected codebase exploration guidance is malformed");
   }
 
+  const audienceLayer =
+    typeof value.audienceLayer === "string" && path.isAbsolute(value.audienceLayer)
+      ? value.audienceLayer
+      : undefined;
+  if (value.audienceLayer !== undefined && audienceLayer === undefined) {
+    errors.push("injected audience layer is not an absolute path");
+  }
+
   return {
     guidance: {
       version: GUIDANCE_FILE_VERSION,
       companionGuidance,
       codebaseExplorationGuidance,
       errors,
+      ...(audienceLayer ? { audienceLayer } : {}),
     },
     errors,
   };

package/src/runtime/opencode-audience-layer.ts

@@ -0,0 +1,176 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { layerGuidanceText } from "./audience-layer";
+import { OPENCODE_MCP_SERVERS_AT } from "./runtime-document-manifest";
+
+/**
+ * Reads an audience layer the OpenCode Runtime Surface wrote, as what the Mate
+ * OpenCode plugin applies through the plugin API. The surface re-exports it as
+ * its own reader; it lives under `runtime/` only so the import-isolated plugin
+ * can reach it. The plugin parses no OpenCode document itself.
+ */
+
+export interface LayerMcpServer {
+  name: string;
+  /** The entry exactly as the surface wrote it under `mcp.servers`. */
+  config: Record<string, unknown>;
+}
+
+export interface LayerSkill {
+  id: string;
+  name: string;
+  description?: string;
+  /** The skill's `SKILL.md`. */
+  path: string;
+  content: string;
+}
+
+export type LayerAgentMode = "subagent" | "primary" | "all";
+
+export interface LayerAgent {
+  id: string;
+  description?: string;
+  mode: LayerAgentMode;
+  /** The agent's prompt: the definition's body. */
+  system: string;
+}
+
+export interface OpenCodeLayerContents {
+  mcpServers: LayerMcpServer[];
+  skills: LayerSkill[];
+  agents: LayerAgent[];
+  /** The layer's guidance sections, managed-block markers removed. */
+  guidance: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function splitFrontmatter(content: string): { fields: string; body: string } {
+  const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  return match
+    ? { fields: match[1]!, body: content.slice(match[0].length) }
+    : { fields: "", body: content };
+}
+
+function frontmatterScalarFromFields(fields: string, key: string): string | undefined {
+  const value = fields.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim();
+  return value?.replace(
+    /^(?:"([\s\S]*)"|'([\s\S]*)')$/,
+    (_all, doubleQuoted?: string, singleQuoted?: string) => doubleQuoted ?? singleQuoted ?? "",
+  );
+}
+
+/** One scalar of a simple YAML frontmatter, quotes removed. */
+export function frontmatterScalar(content: string, key: string): string | undefined {
+  return frontmatterScalarFromFields(splitFrontmatter(content).fields, key);
+}
+
+/** An id OpenCode accepts for a skill or agent name. */
+export function contributionId(name: string, fallback: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || fallback
+  );
+}
+
+async function findSkillFiles(directory: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    const nested = await Promise.all(
+      entries.map((entry) => {
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isFile() && entry.name === "SKILL.md") return Promise.resolve([entryPath]);
+        return entry.isDirectory() ? findSkillFiles(entryPath) : Promise.resolve([]);
+      }),
+    );
+    return nested.flat().toSorted();
+  } catch {
+    return [];
+  }
+}
+
+/** Every `SKILL.md` under `roots`; an unreadable skill is skipped, never fatal. */
+export async function loadSkillInfos(roots: readonly string[]): Promise<LayerSkill[]> {
+  const files = (await Promise.all(roots.map(findSkillFiles))).flat();
+  const skills = await Promise.all(
+    files.map(async (filePath): Promise<LayerSkill | null> => {
+      try {
+        const content = await fs.readFile(filePath, "utf8");
+        const { fields } = splitFrontmatter(content);
+        const name =
+          frontmatterScalarFromFields(fields, "name") || path.basename(path.dirname(filePath));
+        const description = frontmatterScalarFromFields(fields, "description");
+        return {
+          id: contributionId(name, "mate-skill"),
+          name,
+          ...(description ? { description } : {}),
+          path: filePath,
+          content,
+        };
+      } catch {
+        return null;
+      }
+    }),
+  );
+  return skills.filter((skill) => skill !== null);
+}
+
+async function readMcpServers(root: string): Promise<LayerMcpServer[]> {
+  const parsed = await fs
+    .readFile(path.join(root, ".opencode", "opencode.json"), "utf8")
+    .then((text) => JSON.parse(text) as unknown)
+    .catch(() => null);
+  let servers: unknown = parsed;
+  for (const key of OPENCODE_MCP_SERVERS_AT) servers = isRecord(servers) ? servers[key] : undefined;
+  if (!isRecord(servers)) return [];
+  return Object.entries(servers)
+    .filter((entry): entry is [string, Record<string, unknown>] => isRecord(entry[1]))
+    .map(([name, config]) => ({ name, config }))
+    .toSorted((left, right) => left.name.localeCompare(right.name));
+}
+
+function agentMode(value: string | undefined): LayerAgentMode {
+  return value === "subagent" || value === "primary" ? value : "all";
+}
+
+async function readAgents(root: string): Promise<LayerAgent[]> {
+  const dir = path.join(root, ".opencode", "agents");
+  const names = await fs.readdir(dir).catch(() => [] as string[]);
+  const agents = await Promise.all(
+    names
+      .filter((name) => name.endsWith(".md"))
+      .toSorted()
+      .map(async (name): Promise<LayerAgent | null> => {
+        const content = await fs.readFile(path.join(dir, name), "utf8").catch(() => null);
+        if (content === null) return null;
+        const { fields, body } = splitFrontmatter(content);
+        const description = frontmatterScalarFromFields(fields, "description");
+        return {
+          id: contributionId(path.basename(name, ".md"), "mate-agent"),
+          ...(description ? { description } : {}),
+          mode: agentMode(frontmatterScalarFromFields(fields, "mode")),
+          system: body.trim(),
+        };
+      }),
+  );
+  return agents.filter((agent) => agent !== null);
+}
+
+async function readGuidance(root: string): Promise<string> {
+  return layerGuidanceText(await fs.readFile(path.join(root, "AGENTS.md"), "utf8").catch(() => ""));
+}
+
+export async function readOpenCodeAudienceLayer(root: string): Promise<OpenCodeLayerContents> {
+  const [mcpServers, skills, agents, guidance] = await Promise.all([
+    readMcpServers(root),
+    loadSkillInfos([path.join(root, ".agents", "skills")]),
+    readAgents(root),
+    readGuidance(root),
+  ]);
+  return { mcpServers, skills, agents, guidance };
+}

package/src/runtime/policy.ts

@@ -40,6 +40,17 @@ function capabilityNames(value: unknown): string[] {
     .filter((name): name is string => typeof name === "string");
 }
 
+/**
+ * A base-set key from `audiences.base`, the shape a companion is saved in. The
+ * lenient twin of the setup normalizer, which `runtime/` cannot import.
+ */
+function baseAudienceKey(config: Record<string, unknown>, key: string): unknown {
+  const audiences = config.audiences;
+  if (!audiences || typeof audiences !== "object") return undefined;
+  const base = (audiences as Record<string, unknown>).base;
+  return base && typeof base === "object" ? (base as Record<string, unknown>)[key] : undefined;
+}
+
 /**
  * Synchronous so it composes into `readCompanionRuntimeContext`. A missing or
  * unparseable companion config yields an inert policy rather than throwing.
@@ -56,7 +67,9 @@ export function readCompanionPolicy(companionPath: string): CompanionPolicy {
   const config = parsed as Record<string, unknown>;
   return {
     allowedAgents: stringList(config.allowedAgents),
-    enabledCapabilities: capabilityNames(config.capabilities),
+    enabledCapabilities: capabilityNames(
+      config.capabilities ?? baseAudienceKey(config, "capabilities"),
+    ),
     gitAutoMode: config.git === "auto",
   };
 }

package/src/runtime/projection.ts

@@ -88,7 +88,7 @@ export function projectionEnvPath(repoRoot: string): string {
   return path.join(repoLocalDirPath(repoRoot), PROJECTION_ENV_FILE);
 }
 
-const generatedHeader = () => `# generated by ${FRAMEWORK_NAME} — do not edit`;
+export const generatedHeader = (): string => `# generated by ${FRAMEWORK_NAME} — do not edit`;
 
 export function renderProjectionYaml(file: ProjectionFile): string {
   const document: Record<string, string> = { stamp: file.stamp };

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,352 @@
+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>>;
+  /** The audience `mate wrap --audience` recorded; the only source of a bare session's audience. */
+  readonly audience?: string;
+}
+
+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"]) : {},
+    ...(typeof parsed.audience === "string" && parsed.audience
+      ? { audience: parsed.audience }
+      : {}),
+  };
+}
+
+/** The audience the checkout is wrapped for; `null` for base only. */
+export function recordedAudience(manifest: Manifest): string | null {
+  return manifest.audience ?? null;
+}
+
+/** Records the checkout's audience, or none with `null`. */
+export function withAudience(manifest: Manifest, audience: string | null): Manifest {
+  const { audience: _previous, ...rest } = manifest;
+  return audience ? { ...rest, audience } : rest;
+}
+
+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 } : {}),
+      ...(manifest.audience ? { audience: manifest.audience } : {}),
+    },
+    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;
+}