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

package/src/lib/orchestrator/projection-runtime-documents.ts

@@ -1,44 +1,38 @@
-import crypto from "node:crypto";
+import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-
-import { repoLocalDirPath } from "../../runtime/repo-local";
+import { promisify } from "node:util";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import { gitEnvironment } from "../../runtime/companion-git";
+import {
+  documentRegions,
+  readManifest,
+  updateManifest,
+  withDocument,
+  withoutDocuments,
+  type ManagedRegion,
+  type RenderedRuntimeDocument,
+} from "../../runtime/runtime-document-manifest";
+import { writeAtomic } from "../../runtime/write-atomic";
 import { pruneEmptyAncestors } from "../../tools/setup/utils";
-import type { ManagedRegion, RenderedRuntimeDocument } from "./projection-types";
+
+export {
+  CLAUDE_LOCAL_CONFIG_DOCUMENT,
+  CLAUDE_MCP_DOCUMENT,
+  CLAUDE_SETTINGS_DOCUMENT,
+  OPENCODE_CONFIG_DOCUMENT,
+} from "../../runtime/runtime-document-manifest";
 
 /**
  * Places the documents an Agent Runtime discovers by its own upward walk from
  * the current directory. A Runtime Surface renders one as a value; this module
  * writes it, records the regions it wrote at the Projection Root, and removes
  * exactly those again — which is what makes a working-target document swept by
- * `mate working cleanup` without cleanup holding a list of them.
- */
-
-const MANIFEST_FILE = "runtime-documents.json";
-
-/**
- * The three destinations, repo-relative with POSIX separators. Declared here
- * rather than beside the renderers so the entry catalogue names a destination
- * without reaching into an Agent Runtime's Runtime Surface.
- */
-export const CLAUDE_SETTINGS_DOCUMENT = ".claude/settings.local.json";
-export const CLAUDE_MCP_DOCUMENT = ".mcp.json";
-export const OPENCODE_CONFIG_DOCUMENT = ".opencode/opencode.json";
-
-/**
- * The one destination outside the Working Repository. Claude Code has no
- * project file that declares a pre-approved MCP server: `.mcp.json` servers sit
- * "pending approval" until a human accepts them in a session, and the settings
- * document can only enable a server `.mcp.json` already declares. Local scope —
- * `projects[<repo>].mcpServers` in the user's `~/.claude.json`, what
- * `claude mcp add --scope local` writes — is the only channel that is live on
- * first use.
- *
- * Written `~`-prefixed rather than resolved so the manifest recording it stays
- * machine-independent, and so an external target is identifiable as one.
+ * `mate working cleanup` without cleanup holding a list of them. The manifest
+ * — format, I/O and queries — belongs to `runtime/runtime-document-manifest`.
  */
-export const CLAUDE_LOCAL_CONFIG_DOCUMENT = "~/.claude.json";
 
 /**
  * A document Mate does not own the surroundings of. Mate's regions are stripped
@@ -50,6 +44,38 @@ export function isExternalDocument(documentPath: string): boolean {
   return documentPath.startsWith("~/");
 }
 
+const execFileAsync = promisify(execFile);
+
+/** Whether Git tracks the repo-relative path; any `ls-files` failure reads as untracked. */
+async function gitTracks(repoPath: string, relativePath: string): Promise<boolean> {
+  try {
+    const { stdout } = await execFileAsync("git", ["ls-files", "-z", "--", relativePath], {
+      cwd: path.resolve(repoPath),
+      encoding: "utf8",
+      env: gitEnvironment(),
+    });
+    return stdout.split("\0").includes(relativePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Excludes don't hide tracked files, so regions with machine-absolute paths
+ * would land in a committed document: warn, still write. Best-effort: any
+ * `ls-files` failure reads as "not tracked".
+ */
+export async function trackedDocumentWarnings(
+  repoPath: string,
+  documentPath: string,
+  repositoryId: string,
+): Promise<string[]> {
+  if (!(await gitTracks(repoPath, documentPath))) return [];
+  return [
+    `${documentPath} is tracked by Git in ${repositoryId}; ${FRAMEWORK_NAME} writes machine-absolute companion paths into it, so committing it would push this machine's paths to everyone else on the repository. Untrack it with \`git rm --cached ${documentPath}\` if those paths should stay local.`,
+  ];
+}
+
 /**
  * Injectable so a test never writes to the real `~/.claude.json`. An external
  * target is the one destination outside a temporary fixture, so it is also the
@@ -59,14 +85,6 @@ export const runtimeDocumentDeps = {
   homeDir: (): string => os.homedir(),
 };
 
-interface Manifest {
-  documents: Record<string, ManagedRegion[]>;
-}
-
-function manifestPath(repoPath: string): string {
-  return path.join(repoLocalDirPath(repoPath), MANIFEST_FILE);
-}
-
 function documentPathIn(repoPath: string, documentPath: string): string {
   if (isExternalDocument(documentPath)) {
     return path.join(runtimeDocumentDeps.homeDir(), ...documentPath.slice("~/".length).split("/"));
@@ -97,26 +115,9 @@ async function readRaw(filePath: string): Promise<string | null> {
   }
 }
 
-function parseObject(raw: string | null): Record<string, unknown> {
-  if (raw === null) return {};
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    if (isRecord(parsed)) return parsed;
-  } catch {
-    /* unparseable — start from an empty object */
-  }
-  return {};
-}
-
 /**
- * The same read for a document Mate does not own, where an unparseable one is
- * refused rather than treated as empty. `parseObject`'s fallback is right for
- * the manifest — Mate wrote it and can rebuild it — and ruinous here: a torn
- * read of `~/.claude.json` would be written back as the handful of keys Mate
- * contributes, taking Claude Code's auth, every project's history and its MCP
- * approvals with it, silently and without a backup. Throwing leaves the file
- * as it was and hands the entry catch in `project()` a failed outcome to
- * report, which is the answer an operator can act on.
+ * Unparseable throws, never reads as empty: writing back a torn
+ * `~/.claude.json` would wipe the user's auth and history.
  */
 function parseDocument(raw: string | null, target: string): Record<string, unknown> {
   if (raw === null) return {};
@@ -130,40 +131,6 @@ function parseDocument(raw: string | null, target: string): Record<string, unkno
   return parsed;
 }
 
-/**
- * Writes via a sibling temp file + `fs.rename()` so an interrupted write cannot
- * leave a half-written document behind. A reader racing this one — a Claude
- * Code session holding `~/.claude.json` open — observes the old file or the new
- * one, never a truncated one.
- */
-async function writeAtomic(target: string, contents: string): Promise<void> {
-  const tempPath = `${target}.${crypto.randomUUID()}.tmp`;
-  try {
-    await fs.writeFile(tempPath, contents, "utf8");
-    await fs.rename(tempPath, target);
-  } catch (error) {
-    await fs.rm(tempPath, { force: true }).catch(() => {});
-    throw error;
-  }
-}
-
-async function readManifest(repoPath: string): Promise<Manifest> {
-  const parsed = parseObject(await readRaw(manifestPath(repoPath)));
-  return {
-    documents: isRecord(parsed.documents) ? (parsed.documents as Manifest["documents"]) : {},
-  };
-}
-
-async function writeManifest(repoPath: string, manifest: Manifest): Promise<void> {
-  const target = manifestPath(repoPath);
-  if (Object.keys(manifest.documents).length === 0) {
-    await fs.unlink(target).catch(() => {});
-    return;
-  }
-  await fs.mkdir(path.dirname(target), { recursive: true });
-  await writeAtomic(target, serialize(manifest));
-}
-
 /** The container holding a region's final key, created on demand when writing. */
 function containerFor(
   document: Record<string, unknown>,
@@ -185,6 +152,11 @@ function containerFor(
   return node;
 }
 
+function keyPresent(document: Record<string, unknown>, at: string[]): boolean {
+  const container = containerFor(document, at, false);
+  return container !== null && Object.hasOwn(container, at.at(-1)!);
+}
+
 function applyRegion(document: Record<string, unknown>, region: ManagedRegion): void {
   const container = containerFor(document, region.at, true)!;
   const key = region.at.at(-1)!;
@@ -295,19 +267,22 @@ export async function placeRuntimeDocument(
   const raw = await readRaw(target);
   const document = parseDocument(raw, target);
 
-  const manifest = await readManifest(repoPath);
-  for (const region of manifest.documents[documentPath] ?? []) revertRegion(document, region);
-  for (const region of rendered.regions) applyRegion(document, region);
+  const prior = documentRegions(await readManifest(repoPath), documentPath);
+  for (const region of prior ?? []) revertRegion(document, region);
+  /** After the revert, a key still present is the human's: a yielding region gives way to it. */
+  const applied = rendered.regions.filter(
+    (region) => !(region.kind === "value" && region.yields && keyPresent(document, region.at)),
+  );
+  for (const region of applied) applyRegion(document, region);
   const next = serialize(document);
 
-  const regions = [...rendered.regions] as ManagedRegion[];
-  const recorded = JSON.stringify(manifest.documents[documentPath]) === JSON.stringify(regions);
+  const recorded = JSON.stringify(prior) === JSON.stringify(applied);
   if (next === raw && recorded) return "current";
 
+  /** The file first: a failed write leaves the manifest naming what is really there. */
   await fs.mkdir(path.dirname(target), { recursive: true });
   await writeAtomic(target, next);
-  manifest.documents[documentPath] = regions;
-  await writeManifest(repoPath, manifest);
+  await updateManifest(repoPath, (manifest) => withDocument(manifest, documentPath, applied));
   return "written";
 }
 
@@ -319,13 +294,11 @@ export async function removeRuntimeDocument(
   repoPath: string,
   documentPath: string,
 ): Promise<"removed" | "absent"> {
-  const manifest = await readManifest(repoPath);
-  const regions = manifest.documents[documentPath];
+  const regions = documentRegions(await readManifest(repoPath), documentPath);
   if (!regions) return "absent";
 
   await revertDocumentOnDisk(repoPath, documentPath, regions);
-  delete manifest.documents[documentPath];
-  await writeManifest(repoPath, manifest);
+  await updateManifest(repoPath, (manifest) => withoutDocuments(manifest, [documentPath]));
   return "removed";
 }
 
@@ -358,10 +331,10 @@ async function revertDocumentOnDisk(
 }
 
 /**
- * Withdraws several destinations against a single read and a single write of the
- * manifest. `removeRuntimeDocument` per destination cannot be run concurrently —
- * each rewrites the whole manifest, so the last write restores the keys the
- * others removed — and running it sequentially rewrites the manifest once per
+ * Withdraws several destinations against a single manifest update.
+ * `removeRuntimeDocument` per destination cannot be run concurrently — each
+ * rewrites the whole manifest, so the last write restores the keys the others
+ * removed — and running it sequentially rewrites the manifest once per
  * document. Reverting the files together and recording the outcome once is both
  * safe and one write.
  *
@@ -375,13 +348,13 @@ export async function removeRuntimeDocuments(
   documentPaths: readonly string[],
 ): Promise<{ removed: string[]; absent: string[]; error?: { document: string; error: Error } }> {
   const manifest = await readManifest(repoPath);
-  const recorded = documentPaths.filter((candidate) => manifest.documents[candidate] !== undefined);
-  const absent = documentPaths.filter((candidate) => manifest.documents[candidate] === undefined);
+  const recorded = documentPaths.filter((candidate) => documentRegions(manifest, candidate));
+  const absent = documentPaths.filter((candidate) => !documentRegions(manifest, candidate));
   if (recorded.length === 0) return { removed: [], absent };
 
   const settled = await Promise.allSettled(
     recorded.map((documentPath) =>
-      revertDocumentOnDisk(repoPath, documentPath, manifest.documents[documentPath]!),
+      revertDocumentOnDisk(repoPath, documentPath, documentRegions(manifest, documentPath)!),
     ),
   );
 
@@ -396,29 +369,9 @@ export async function removeRuntimeDocuments(
       };
       continue;
     }
-    delete manifest.documents[documentPath];
     removed.push(documentPath);
   }
 
-  await writeManifest(repoPath, manifest);
+  await updateManifest(repoPath, (current) => withoutDocuments(current, removed));
   return { removed, absent, ...(failure ? { error: failure } : {}) };
 }
-
-/**
- * Every destination the manifest records, in the order it recorded them. This
- * is what makes a Working Repository "wrapped": the manifest is written only by
- * a pass that placed a runtime document, and `mate wrap` is the only pass that
- * places one. Reported as data so neither the launch refusal nor `mate unwrap`
- * holds a list of destinations that the entry catalogue could outgrow.
- */
-export async function recordedRuntimeDocuments(repoPath: string): Promise<string[]> {
-  return Object.keys((await readManifest(repoPath)).documents);
-}
-
-/** Present when Mate recorded regions for it, not merely when the file exists. */
-export async function runtimeDocumentPresent(
-  repoPath: string,
-  documentPath: string,
-): Promise<boolean> {
-  return (await readManifest(repoPath)).documents[documentPath] !== undefined;
-}

package/src/lib/orchestrator/projection-types.ts

@@ -1,5 +1,6 @@
 import type { GlobalConfigStore } from "./global-config-store";
 import type { ProjectionFile } from "../../runtime/projection";
+import type { RenderedRuntimeDocument, WrapRuntime } from "../../runtime/runtime-document-manifest";
 import type { CompanionSource, FrameworkConfig, LinkedRepository } from "./types";
 
 /**
@@ -24,6 +25,8 @@ export type ProjectionEntryId =
   | "repo-local-framework"
   | "repo-local-registry"
   | "projection-pair"
+  | "openspec-store-exclude"
+  | "openspec-store-pointer"
   | "claude-skill-links"
   | "workspace-document"
   | "capability-excludes"
@@ -32,38 +35,8 @@ export type ProjectionEntryId =
   | "claude-runtime-document"
   | "claude-local-mcp-document"
   | "mcp-runtime-document"
-  | "opencode-runtime-document";
-
-/**
- * A region of a runtime document that Mate maintains. JSON carries no comment
- * syntax, so the region is recorded rather than marked in the file: `list`
- * appends values not already there, `map` sets entries by key, `value` sets one
- * key — and removal takes back exactly those, leaving anything a human added.
- *
- * `stripPrefix` is the one exception to "removal takes back exactly what was
- * written": it deletes keys Mate never wrote, and removal does not restore
- * them. It exists for keys an older Mate wrote and a current one must not
- * leave behind, so a re-wrap heals a repository an old version configured.
- */
-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 };
-
-/**
- * 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[];
-}
+  | "opencode-runtime-document"
+  | "opencode-companion-copies";
 
 export interface ProjectionInput {
   repoPath: string;
@@ -75,6 +48,10 @@ export interface ProjectionInput {
   globalConfigStore?: GlobalConfigStore;
   /** Rendered by the active Runtime Surfaces; placed by the `wrap` scope's entries. */
   runtimeDocuments?: readonly RenderedRuntimeDocument[];
+  /** Restricts runtime-tagged entries to these runtimes; every runtime when absent. */
+  runtimes?: readonly WrapRuntime[];
+  /** The layer directory of the audience the checkout is wrapped for; `null` or absent for base only. */
+  audienceLayerDir?: string | null;
 }
 
 export interface ProjectionRemovalInput {
@@ -86,6 +63,23 @@ export interface ProjectionRemovalInput {
 export type ProjectionWriteState = "written" | "current" | "skipped";
 export type ProjectionRemoveState = "removed" | "absent" | "retained" | "covered";
 
+/** Repo-relative paths an entry maintaining several files wrote or withdrew. */
+export interface ProjectionChangedPaths {
+  written: string[];
+  removed: string[];
+}
+
+/**
+ * What a write may return instead of a bare state, when it has something to
+ * tell the operator. The entry reports; it never prints — the caller presents
+ * warnings and changed paths without knowing which entry produced them.
+ */
+export interface ProjectionWriteReport {
+  state: ProjectionWriteState;
+  warnings?: string[];
+  changed?: ProjectionChangedPaths;
+}
+
 /**
  * Every entry names its inverse. `self` removes its own path, `entry` is covered
  * by another entry's removal, `retained` is deliberately left behind and says
@@ -95,6 +89,8 @@ export type ProjectionEntryRemoval =
   | {
       readonly by: "self";
       remove(input: ProjectionRemovalInput): Promise<"removed" | "absent">;
+      /** What removing this path deliberately leaves outside the repository, named in the outcome. */
+      readonly retains?: string;
     }
   | { readonly by: "entry"; readonly entry: ProjectionEntryId }
   | { readonly by: "retained"; readonly because: string };
@@ -105,8 +101,10 @@ export interface ProjectionEntry {
   /** Repo-relative, POSIX separators. An entry spanning siblings names its primary. */
   readonly path: string;
   readonly scopes: readonly ProjectionScope[];
+  /** Set on entries that belong to one Agent Runtime; see {@link ProjectionInput.runtimes}. */
+  readonly runtime?: WrapRuntime;
   /** `skipped` when an input this entry needs was not supplied. */
-  write(input: ProjectionInput): Promise<ProjectionWriteState>;
+  write(input: ProjectionInput): Promise<ProjectionWriteState | ProjectionWriteReport>;
   /**
    * Whether a failed write is reported without failing the operation that
    * triggered the projection. Only for an entry something else already covers:
@@ -132,6 +130,14 @@ export interface ProjectionEntryOutcome {
   state: ProjectionWriteState | ProjectionRemoveState | "failed";
   error?: Error;
   degradable?: boolean;
+  /** The entry's runtime tag; absent for runtime-neutral entries. */
+  runtime?: WrapRuntime;
+  /** Present only when the entry had something to say. */
+  warnings?: string[];
+  /** Present only when the entry wrote or withdrew paths it reports one by one. */
+  changed?: ProjectionChangedPaths;
+  /** Present only on a removal that leaves something outside the repository behind. */
+  retains?: string;
 }
 
 export interface ProjectionResult {
@@ -159,7 +165,14 @@ export interface ProjectionDescription {
   projection: ProjectionFile | null;
 }
 
-/** A degradable entry's failure is reported in the outcomes and nowhere else. */
+/** Skips a degradable entry's failure: it never fails a pass, only shows in the outcomes. */
 export function firstFailure(outcomes: ProjectionEntryOutcome[]): ProjectionEntryOutcome | null {
   return outcomes.find((outcome) => outcome.state === "failed" && !outcome.degradable) ?? null;
 }
+
+/** Names the failed entry: "the projection" alone would not say what to fix. */
+export function entryFailureMessage(outcome: ProjectionEntryOutcome, repositoryId: string): string {
+  const reason = outcome.error?.message ?? "projection failed";
+  const target = outcome.id === "projection-pair" ? "the projection" : outcome.path;
+  return `failed to write ${target} for ${repositoryId}: ${reason}`;
+}