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

package/src/lib/orchestrator/projection-opencode-copies.ts

@@ -0,0 +1,230 @@
+import crypto from "node:crypto";
+import type { Dirent } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  copies,
+  readManifest,
+  updateManifest,
+  withCopies,
+  type CopyRecord,
+} from "../../runtime/runtime-document-manifest";
+import { writeAtomic } from "../../runtime/write-atomic";
+import { pruneEmptyAncestors } from "../../tools/setup/utils";
+import { reconcileWorkingRepoCopyExcludes } from "../../tools/setup/working-repo-local-state";
+import type { ProjectionWriteReport } from "./projection-types";
+
+/**
+ * Copies the companion's `.opencode/` into the Working Repository's own
+ * `.opencode/`, the one slot OpenCode reads beside the user's global config.
+ * Regular files, not links: OpenCode does not live-reload a linked folder.
+ * Mate touches only the files its manifest records as owned.
+ */
+
+const OPENCODE_DIR = ".opencode";
+/** `opencode.json` is merged into the wrapped document instead of copied. */
+const SKIPPED_TOP_LEVEL = new Set(["opencode.json"]);
+const SKIPPED_NAMES = new Set(["node_modules", ".DS_Store"]);
+
+interface CopySource {
+  absolute: string;
+  content: Buffer;
+  sha256: string;
+}
+
+function sha256(content: Buffer): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+async function walk(dir: string, relative: string, into: Map<string, CopySource>): Promise<void> {
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name))) {
+    if (SKIPPED_NAMES.has(entry.name)) continue;
+    if (relative === "" && SKIPPED_TOP_LEVEL.has(entry.name)) continue;
+    const absolute = path.join(dir, entry.name);
+    const rel = relative ? `${relative}/${entry.name}` : entry.name;
+    // oxlint-disable-next-line no-await-in-loop -- sequential walk keeps the order stable
+    const stat = await fs.stat(absolute).catch(() => null);
+    if (!stat) continue;
+    if (stat.isDirectory()) {
+      // oxlint-disable-next-line no-await-in-loop
+      await walk(absolute, rel, into);
+      continue;
+    }
+    if (!stat.isFile()) continue;
+    // oxlint-disable-next-line no-await-in-loop
+    const content = await fs.readFile(absolute);
+    into.set(`${OPENCODE_DIR}/${rel}`, { absolute, content, sha256: sha256(content) });
+  }
+}
+
+async function companionSources(companionPath: string): Promise<Map<string, CopySource>> {
+  const sources = new Map<string, CopySource>();
+  await walk(path.join(companionPath, OPENCODE_DIR), "", sources);
+  return sources;
+}
+
+function destination(repoPath: string, relativePath: string): string {
+  return path.join(path.resolve(repoPath), ...relativePath.split("/"));
+}
+
+/** `null` when absent; a directory or other non-file reads as a foreign entry. */
+async function readDestination(target: string): Promise<Buffer | "foreign" | null> {
+  const stat = await fs.lstat(target).catch(() => null);
+  if (!stat) return null;
+  if (!stat.isFile()) return "foreign";
+  return fs.readFile(target);
+}
+
+async function writeCopy(target: string, content: Buffer): Promise<void> {
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await writeAtomic(target, content);
+}
+
+async function deleteCopy(repoPath: string, relativePath: string): Promise<void> {
+  const target = destination(repoPath, relativePath);
+  await fs.rm(target, { force: true });
+  await pruneEmptyAncestors(path.dirname(target), path.resolve(repoPath));
+}
+
+interface CopyPlan {
+  write: Array<{ relativePath: string; source: CopySource; warning?: string }>;
+  remove: string[];
+  shadowed: Array<{ relativePath: string; source: CopySource }>;
+  records: Record<string, CopyRecord>;
+  previous: Record<string, CopyRecord>;
+}
+
+async function planCopies(repoPath: string, companionPath: string): Promise<CopyPlan> {
+  const previous = copies(await readManifest(repoPath), "opencode");
+  const sources = await companionSources(companionPath);
+  const plan: CopyPlan = { write: [], remove: [], shadowed: [], records: {}, previous };
+
+  for (const [relativePath, source] of sources) {
+    const owned = previous[relativePath];
+    // oxlint-disable-next-line no-await-in-loop -- one stat per file
+    const current = await readDestination(destination(repoPath, relativePath));
+    if (current === "foreign" || (!owned && current !== null)) {
+      plan.shadowed.push({ relativePath, source });
+      continue;
+    }
+    const currentSha = current === null ? null : sha256(current);
+    const edited = owned !== undefined && currentSha !== null && currentSha !== owned.sha256;
+    /** Local edit survives until its companion source changes. */
+    const keepEdit = edited && source.sha256 === owned.sha256;
+    if (currentSha !== source.sha256 && !keepEdit) {
+      plan.write.push({
+        relativePath,
+        source,
+        warning: edited
+          ? `${relativePath} was edited locally; the edit was replaced from the companion. Edit ${source.absolute} instead.`
+          : undefined,
+      });
+    }
+    plan.records[relativePath] = { runtime: "opencode", sha256: source.sha256 };
+  }
+  for (const relativePath of Object.keys(previous)) {
+    if (!sources.has(relativePath)) plan.remove.push(relativePath);
+  }
+  return plan;
+}
+
+function sameRecords(a: Record<string, CopyRecord>, b: Record<string, CopyRecord>): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function shadowWarning(relativePath: string, source: CopySource): string {
+  return `${relativePath} in the working repository shadows the companion file ${source.absolute}; the repository file wins.`;
+}
+
+/**
+ * Adds, updates and deletes owned copies; an unowned path is never touched.
+ * Excludes widen and new paths are recorded before any write, so an
+ * interrupted reconcile leaves no unrecorded copy and none Git would list.
+ */
+export async function reconcileCompanionCopies(
+  repoPath: string,
+  companionPath: string,
+): Promise<ProjectionWriteReport> {
+  const plan = await planCopies(repoPath, companionPath);
+  const warnings = plan.shadowed.map(({ relativePath, source }) =>
+    shadowWarning(relativePath, source),
+  );
+
+  const covering = [...new Set([...Object.keys(plan.previous), ...Object.keys(plan.records)])];
+  const excludesWidened = await reconcileWorkingRepoCopyExcludes(repoPath, covering);
+  /** Previous records win: a path not yet rewritten keeps the hash on disk. */
+  const interim = { ...plan.records, ...plan.previous };
+  if (!sameRecords(interim, plan.previous)) {
+    await updateManifest(repoPath, (manifest) => withCopies(manifest, "opencode", interim));
+  }
+
+  for (const { relativePath, source, warning } of plan.write) {
+    // oxlint-disable-next-line no-await-in-loop -- bounded by the companion folder
+    await writeCopy(destination(repoPath, relativePath), source.content);
+    if (warning) warnings.push(warning);
+  }
+  for (const relativePath of plan.remove) {
+    // oxlint-disable-next-line no-await-in-loop
+    await deleteCopy(repoPath, relativePath);
+  }
+
+  const recordsWritten = !sameRecords(plan.records, plan.previous);
+  if (recordsWritten) {
+    await updateManifest(repoPath, (manifest) => withCopies(manifest, "opencode", plan.records));
+  }
+  const excludesNarrowed = await reconcileWorkingRepoCopyExcludes(
+    repoPath,
+    Object.keys(plan.records),
+  );
+
+  const written = plan.write.map(({ relativePath }) => relativePath);
+  return {
+    state:
+      written.length > 0 ||
+      plan.remove.length > 0 ||
+      recordsWritten ||
+      excludesWidened ||
+      excludesNarrowed
+        ? "written"
+        : "current",
+    warnings,
+    changed: { written, removed: plan.remove },
+  };
+}
+
+/**
+ * Deletes every owned copy, then its exclude line, and prunes what that
+ * emptied: a copy is never on disk without the line that hides it.
+ */
+export async function withdrawCompanionCopies(repoPath: string): Promise<ProjectionWriteReport> {
+  const owned = Object.keys(copies(await readManifest(repoPath), "opencode"));
+  for (const relativePath of owned) {
+    // oxlint-disable-next-line no-await-in-loop
+    await deleteCopy(repoPath, relativePath);
+  }
+  if (owned.length > 0) {
+    await updateManifest(repoPath, (manifest) => withCopies(manifest, "opencode", {}));
+  }
+  const excludesChanged = await reconcileWorkingRepoCopyExcludes(repoPath, []);
+  return {
+    state: owned.length > 0 || excludesChanged ? "written" : "current",
+    changed: { written: [], removed: owned },
+  };
+}
+
+export async function removeCompanionCopies(repoPath: string): Promise<"removed" | "absent"> {
+  return (await withdrawCompanionCopies(repoPath)).state === "written" ? "removed" : "absent";
+}
+
+/** Whether any owned copy is recorded. */
+export async function companionCopiesPresent(repoPath: string): Promise<boolean> {
+  return Object.keys(copies(await readManifest(repoPath), "opencode")).length > 0;
+}

package/src/lib/orchestrator/projection-openspec-store.ts

@@ -0,0 +1,164 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { generatedHeader } from "../../runtime/projection";
+import { reconcileWorkingRepoCapabilityExcludes } from "../../tools/setup/working-repo-local-state";
+import { ensureStoreRegistration } from "./openspec-store";
+import type { ProjectionWriteReport, ProjectionWriteState } from "./projection-types";
+
+/**
+ * The store pointer: an `openspec/config.yaml` in the Working Repository that
+ * declares the companion's OpenSpec store. Run from inside the repository,
+ * OpenSpec then plans in the store and names the repository as the edit root.
+ *
+ * The pointer's whole `openspec/` folder is hidden only through
+ * `.git/info/exclude`, never the repository's own `.gitignore`: all planning
+ * lives in the store, so nothing under it belongs to the repository. Mate
+ * never writes it where the repository already owns an OpenSpec root.
+ */
+
+const execFileAsync = promisify(execFile);
+
+export const OPENSPEC_POINTER_PATH = path.join("openspec", "config.yaml");
+/** The exclusion line, outside the managed block so a core-block rewrite keeps it. */
+export const OPENSPEC_POINTER_EXCLUDE = "/openspec/";
+/** The earlier file-only line; still managed so a refresh replaces it. */
+const LEGACY_POINTER_EXCLUDE = "/openspec/config.yaml";
+const MANAGED_POINTER_EXCLUDES = [OPENSPEC_POINTER_EXCLUDE, LEGACY_POINTER_EXCLUDE];
+
+export type StorePointer = { kind: "absent" } | { kind: "foreign" } | { kind: "mate"; id: string };
+
+function pointerFile(repoPath: string): string {
+  return path.join(repoPath, OPENSPEC_POINTER_PATH);
+}
+
+function renderPointer(id: string): string {
+  return `${generatedHeader()}\nstore: ${id}\n`;
+}
+
+async function exists(candidate: string): Promise<boolean> {
+  return fs
+    .access(candidate)
+    .then(() => true)
+    .catch(() => false);
+}
+
+export async function readStorePointer(repoPath: string): Promise<StorePointer> {
+  const content = await fs.readFile(pointerFile(repoPath), "utf8").catch(() => null);
+  if (content === null) return { kind: "absent" };
+  const [first, ...rest] = content.split(/\r?\n/);
+  if (first !== generatedHeader()) return { kind: "foreign" };
+  const store = rest.map((line) => /^store:\s*(\S+)\s*$/.exec(line)?.[1]).find(Boolean);
+  return { kind: "mate", id: store ?? "" };
+}
+
+/**
+ * Why Mate may not point this repository at a store, or `null` when it may: a
+ * config Mate did not write, or a planning root of the repository's own.
+ */
+export async function storePointerIneligibility(repoPath: string): Promise<string | null> {
+  if ((await readStorePointer(repoPath)).kind === "foreign") {
+    return `${pointerFile(repoPath)} is not Mate's`;
+  }
+  for (const dir of ["specs", "changes"]) {
+    const planningRoot = path.join(repoPath, "openspec", dir);
+    // oxlint-disable-next-line no-await-in-loop -- two probes, first hit wins
+    if (await exists(planningRoot)) return `${planningRoot} is the repository's own OpenSpec root`;
+  }
+  return null;
+}
+
+/**
+ * Whether Git would show the pointer, asked of Git itself so a re-including
+ * rule anywhere above the exclude file counts. `null` when the pointer stays
+ * out of every diff, including outside a Git work tree.
+ */
+export async function pointerIgnoreProblem(repoPath: string): Promise<string | null> {
+  const pointer = OPENSPEC_POINTER_PATH.split(path.sep).join("/");
+  try {
+    await execFileAsync("git", ["check-ignore", "-q", pointer], { cwd: repoPath });
+    return null;
+  } catch (error) {
+    if ((error as { code?: unknown }).code !== 1) return null;
+  }
+  const { stdout } = await execFileAsync("git", ["check-ignore", "-v", "-n", pointer], {
+    cwd: repoPath,
+  }).catch(() => ({ stdout: "" }));
+  const [source, line, pattern] = stdout.split("\t")[0]?.split(":") ?? [];
+  return pattern
+    ? `${pointer} is re-included by "${pattern}" (${source}:${line})`
+    : `${pointer} is not ignored by Git`;
+}
+
+async function persistPointer(repoPath: string, id: string): Promise<void> {
+  await fs.mkdir(path.dirname(pointerFile(repoPath)), { recursive: true });
+  await fs.writeFile(pointerFile(repoPath), renderPointer(id), "utf8");
+}
+
+export async function writeStorePointer(
+  repoPath: string,
+  id: string,
+): Promise<"written" | "current"> {
+  const current = await readStorePointer(repoPath);
+  if (current.kind === "mate" && current.id === id) return "current";
+  await persistPointer(repoPath, id);
+  return "written";
+}
+
+/** Only Mate's pointer; `openspec/` goes too when nothing else is left in it. */
+export async function removeStorePointer(repoPath: string): Promise<"removed" | "absent"> {
+  if ((await readStorePointer(repoPath)).kind !== "mate") return "absent";
+  await fs.rm(pointerFile(repoPath));
+  await fs.rmdir(path.dirname(pointerFile(repoPath))).catch(() => {});
+  return "removed";
+}
+
+export async function storePointerPresent(repoPath: string): Promise<boolean> {
+  return (await readStorePointer(repoPath)).kind === "mate";
+}
+
+/** Keeps the exclusion line exactly while the repository may carry Mate's pointer. */
+export async function reconcileStorePointerExclude(repoPath: string): Promise<boolean> {
+  const eligible = (await storePointerIneligibility(repoPath)) === null;
+  return reconcileWorkingRepoCapabilityExcludes(
+    repoPath,
+    eligible ? [OPENSPEC_POINTER_EXCLUDE] : [],
+    MANAGED_POINTER_EXCLUDES,
+  );
+}
+
+export async function removeStorePointerExclude(repoPath: string): Promise<"removed" | "absent"> {
+  return (await reconcileWorkingRepoCapabilityExcludes(repoPath, [], MANAGED_POINTER_EXCLUDES))
+    ? "removed"
+    : "absent";
+}
+
+function pointerNotWritten(reason: string): ProjectionWriteReport {
+  return { state: "skipped", warnings: [`OpenSpec store pointer not written: ${reason}`] };
+}
+
+/**
+ * Eligibility, then registration, then the pointer: a pointer naming a store
+ * OpenSpec cannot resolve would break every root-resolving command. Git is
+ * asked about the pointer only before it is created or rewritten, so a
+ * steady-state refresh spawns nothing.
+ */
+export async function projectStorePointer(
+  repoPath: string,
+  companionPath: string,
+): Promise<ProjectionWriteState | ProjectionWriteReport> {
+  /** A companion without OpenSpec has no store to point at; nothing to say. */
+  if (!(await exists(path.join(companionPath, "openspec")))) return "skipped";
+  const ineligible = await storePointerIneligibility(repoPath);
+  if (ineligible) return pointerNotWritten(ineligible);
+  const registration = await ensureStoreRegistration(companionPath);
+  if (registration.state === "skipped") return pointerNotWritten(registration.reason);
+  const current = await readStorePointer(repoPath);
+  if (current.kind === "mate" && current.id === registration.id) return registration.state;
+  const ignoreProblem = await pointerIgnoreProblem(repoPath);
+  if (ignoreProblem) return pointerNotWritten(ignoreProblem);
+  await persistPointer(repoPath, registration.id);
+  return "written";
+}

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

@@ -10,6 +10,7 @@ import {
   GRAPHIFY_OUTPUT_SUBDIR,
   GRAPHIFY_STORE_SEGMENT,
 } from "../../tools/setup/capabilities/graphify";
+import { runtimeWrapperBinPath } from "../../runtime/runtime-directory";
 import { getReactDoctorBinPath, getWrapperBinPath } from "../package-paths";
 import type { LinkedRepository } from "./types";
 
@@ -25,17 +26,22 @@ const COMPANION_GRAPHIFY_REPOSITORY_ID = "__companion__";
  * Both bin paths and `GRAPHIFY_OUT` are unconditional: a path exists whether or
  * not its Capability is enabled, and enablement is a predicate, read live from
  * the companion rather than cached here.
+ *
+ * The persisted record names the runtime directory so it survives a reinstall;
+ * a launch passes the live install path, since its runtime-directory refresh
+ * may only have warned.
  */
 export function buildProjection(
   companionPath: string,
   repository: LinkedRepository,
+  wrapperBinPath: string = runtimeWrapperBinPath(),
 ): MateProjection {
   return {
     version,
     companionPath,
     repositoryPath: repository.path,
     repositoryId: repository.id,
-    wrapperBinPath: getWrapperBinPath(),
+    wrapperBinPath,
     reactDoctorBinPath: getReactDoctorBinPath(),
     graphifyOut: path.join(
       companionPath,