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

package/src/lib/orchestrator/projection-claude-skills.ts

@@ -1,11 +1,26 @@
+// oxlint-disable no-await-in-loop
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { CURRENT_LAYER_LINK } from "../../runtime/audience-layer";
 import { readProjectionFile } from "../../runtime/projection";
+import { realLinkTarget, realOrResolved } from "../fs-utils";
+import {
+  links,
+  readManifest,
+  updateManifest,
+  withLinks,
+  type LinkRecord,
+} from "../../runtime/runtime-document-manifest";
 import { pruneEmptyAncestors } from "../../tools/setup/utils";
 
 const CLAUDE_SKILLS_PATH = path.join(".claude", "skills");
 
+/** The manifest key of a skill link: repo-relative, POSIX separators. */
+function recordKey(name: string): string {
+  return `.claude/skills/${name}`;
+}
+
 async function skillNames(root: string): Promise<string[]> {
   const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
   const names: string[] = [];
@@ -25,13 +40,7 @@ async function skillNames(root: string): Promise<string[]> {
 
 async function linkTarget(link: string): Promise<string | null> {
   const target = await fs.readlink(link).catch(() => null);
-  return target === null ? null : path.resolve(path.dirname(link), target);
-}
-
-async function isManagedSkillLink(link: string, roots: string[]): Promise<boolean> {
-  const target = await linkTarget(link);
-  if (target === null) return false;
-  return roots.some((root) => path.dirname(target) === root);
+  return target === null ? null : realLinkTarget(link, target);
 }
 
 async function registeredSkillRoots(
@@ -45,67 +54,143 @@ async function registeredSkillRoots(
     companionPath ?? "",
     projection?.projection.companionPath ?? "",
   ];
-  return [
-    ...new Set(
-      candidates.filter(Boolean).map((candidate) => path.resolve(candidate, CLAUDE_SKILLS_PATH)),
-    ),
-  ];
+  const roots = await Promise.all(
+    candidates
+      .filter(Boolean)
+      .map((candidate) => realOrResolved(path.resolve(candidate, CLAUDE_SKILLS_PATH))),
+  );
+  return [...new Set(roots)];
 }
 
 async function createSkillLink(target: string, link: string): Promise<void> {
   await fs.symlink(target, link, process.platform === "win32" ? "junction" : "dir");
 }
 
+const CLAUDE_AGENTS_PATH = path.join(".claude", "agents");
+
+/** The manifest key of an agent link: repo-relative, POSIX separators. */
+function agentKey(file: string): string {
+  return `.claude/agents/${file}`;
+}
+
+async function agentFiles(root: string): Promise<string[]> {
+  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  return entries
+    .filter((entry) => (entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith(".md"))
+    .map((entry) => entry.name);
+}
+
+/**
+ * Every link the wrap wants, by manifest key: the companion's skills, then the
+ * wrapped audience's skills and agents. An audience link targets the layer
+ * through its `current` link, so a re-rendered layer never strands it. A
+ * companion skill wins a name both provide.
+ */
+async function wantedLinks(
+  currentRoot: string | null,
+  layerRoot: string | null,
+): Promise<Map<string, string>> {
+  const wanted = new Map<string, string>();
+  if (currentRoot) {
+    for (const name of await skillNames(currentRoot)) {
+      wanted.set(recordKey(name), path.join(currentRoot, name));
+    }
+  }
+  if (layerRoot) {
+    const layerSkills = path.join(layerRoot, "skills");
+    for (const name of await skillNames(layerSkills)) {
+      if (!wanted.has(recordKey(name))) wanted.set(recordKey(name), path.join(layerSkills, name));
+    }
+    const layerAgents = path.join(layerRoot, "agents");
+    for (const file of await agentFiles(layerAgents)) {
+      wanted.set(agentKey(file), path.join(layerAgents, file));
+    }
+  }
+  return wanted;
+}
+
+/**
+ * Recorded link: Mate's while it resolves to its recorded target. Unrecorded:
+ * a skill link is adopted only when it resolves into a registered, current or
+ * projected companion; an agent link never is. Records follow the filesystem,
+ * so a partial failure re-adopts.
+ */
 export async function reconcileWorkingRepoClaudeSkillLinks(
   repoPath: string,
   companionPath: string | null,
   enabled: boolean,
   registeredCompanionPaths: string[] = [],
+  audienceLayerDir: string | null = null,
 ): Promise<"written" | "current"> {
+  const repoRoot = path.resolve(repoPath);
   const currentRoot = companionPath ? path.resolve(companionPath, CLAUDE_SKILLS_PATH) : null;
+  const layerRoot =
+    audienceLayerDir && enabled ? path.join(audienceLayerDir, CURRENT_LAYER_LINK, ".claude") : null;
   const roots = await registeredSkillRoots(repoPath, companionPath, registeredCompanionPaths);
-  const targetRoot = path.join(path.resolve(repoPath), CLAUDE_SKILLS_PATH);
-  const existing = await fs.readdir(targetRoot, { withFileTypes: true }).catch(() => []);
-  const sourceNames: Set<string> =
-    currentRoot && enabled ? new Set(await skillNames(currentRoot)) : new Set<string>();
+  const recorded = links(await readManifest(repoPath), "claude");
+  const wanted = await wantedLinks(enabled ? currentRoot : null, layerRoot);
+  const records: Record<string, LinkRecord> = {};
   let changed = false;
 
-  for (const entry of existing) {
-    if (!entry.isSymbolicLink()) continue;
-    const link = path.join(targetRoot, entry.name);
-    if (!(await isManagedSkillLink(link, roots))) continue;
-
-    const target = await linkTarget(link);
-    if (
-      currentRoot &&
-      enabled &&
-      target === path.join(currentRoot, entry.name) &&
-      sourceNames.has(entry.name)
-    ) {
-      continue;
-    }
+  const linkDirs = [
+    { dir: path.join(repoRoot, CLAUDE_SKILLS_PATH), keyOf: recordKey, adoptable: true },
+    { dir: path.join(repoRoot, CLAUDE_AGENTS_PATH), keyOf: agentKey, adoptable: false },
+  ];
+  for (const { dir, keyOf, adoptable } of linkDirs) {
+    const existing = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of existing) {
+      if (!entry.isSymbolicLink()) continue;
+      const link = path.join(dir, entry.name);
+      const target = await linkTarget(link);
+      if (target === null) continue;
+      const key = keyOf(entry.name);
+      const record = recorded[key];
+      const owned = record
+        ? (await realOrResolved(record.target)) === target
+        : adoptable && roots.some((root) => path.dirname(target) === root);
+      if (!owned) continue;
 
-    await fs.unlink(link);
-    changed = true;
-  }
+      const want = wanted.get(key);
+      if (want && (await realOrResolved(want)) === target) {
+        records[key] = { runtime: "claude", target: want };
+        continue;
+      }
 
-  if (currentRoot && enabled && sourceNames.size > 0) {
-    await fs.mkdir(targetRoot, { recursive: true });
-    for (const name of sourceNames) {
-      const link = path.join(targetRoot, name);
-      const existingLink = await fs.lstat(link).catch(() => null);
-      if (existingLink) continue;
-      await createSkillLink(path.join(currentRoot, name), link);
+      await fs.unlink(link);
       changed = true;
     }
   }
 
+  for (const [key, target] of wanted) {
+    const link = path.join(repoRoot, ...key.split("/"));
+    const existingLink = await fs.lstat(link).catch(() => null);
+    if (existingLink) continue;
+    await fs.mkdir(path.dirname(link), { recursive: true });
+    if (key.startsWith(".claude/agents/")) await fs.symlink(target, link, "file");
+    else await createSkillLink(target, link);
+    records[key] = { runtime: "claude", target };
+    changed = true;
+  }
+
   if (changed || !enabled) {
-    await pruneEmptyAncestors(targetRoot, path.resolve(repoPath));
+    for (const { dir } of linkDirs) await pruneEmptyAncestors(dir, repoRoot);
+  }
+  if (JSON.stringify(sortedEntries(records)) !== JSON.stringify(sortedEntries(recorded))) {
+    await updateManifest(repoPath, (manifest) => withLinks(manifest, "claude", records));
+    changed = true;
   }
   return changed ? "written" : "current";
 }
 
+function sortedEntries(records: Record<string, LinkRecord>): [string, LinkRecord][] {
+  return Object.entries(records)
+    .map(([key, record]): [string, LinkRecord] => [
+      key,
+      { runtime: record.runtime, target: record.target },
+    ])
+    .toSorted(([a], [b]) => a.localeCompare(b));
+}
+
 export async function removeWorkingRepoClaudeSkillLinks(
   repoPath: string,
   registeredCompanionPaths: string[] = [],

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

@@ -13,6 +13,11 @@ import {
   repoLocalDirPath,
   repoLocalRegistryPath,
 } from "../../runtime/repo-local";
+import {
+  documentRuntime,
+  documents as recordedDocuments,
+  readManifest,
+} from "../../runtime/runtime-document-manifest";
 import { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "../../tools/setup/capabilities/tokensave-shared";
 import {
   ensureWorkingRepoLocalExcludes,
@@ -26,6 +31,21 @@ import {
   reconcileWorkingRepoClaudeSkillLinks,
   removeWorkingRepoClaudeSkillLinks,
 } from "./projection-claude-skills";
+import {
+  companionCopiesPresent,
+  reconcileCompanionCopies,
+  removeCompanionCopies,
+  withdrawCompanionCopies,
+} from "./projection-opencode-copies";
+import {
+  OPENSPEC_POINTER_EXCLUDE,
+  OPENSPEC_POINTER_PATH,
+  projectStorePointer,
+  reconcileStorePointerExclude,
+  removeStorePointer,
+  removeStorePointerExclude,
+  storePointerPresent,
+} from "./projection-openspec-store";
 import { buildProjection } from "./projection-record";
 import {
   CLAUDE_WORKING_SETTINGS_PATH,
@@ -41,16 +61,22 @@ import {
   CLAUDE_MCP_DOCUMENT,
   CLAUDE_SETTINGS_DOCUMENT,
   OPENCODE_CONFIG_DOCUMENT,
+  isExternalDocument,
   placeRuntimeDocument,
   removeRuntimeDocument,
-  runtimeDocumentPresent,
+  trackedDocumentWarnings,
 } from "./projection-runtime-documents";
 import {
   upsertRepoLocalCompanionPointer,
   upsertRepoLocalLinkedRepository,
   writeRepoLocalFrameworkConfig,
 } from "./repo-local-store";
-import type { ProjectionEntry, ProjectionInput } from "./projection-types";
+import type {
+  ProjectionEntry,
+  ProjectionInput,
+  ProjectionWriteReport,
+  ProjectionWriteState,
+} from "./projection-types";
 
 const WORKSPACE_DOCUMENT_FILE = "workspace.code-workspace";
 
@@ -68,6 +94,11 @@ async function pathExists(candidatePath: string): Promise<boolean> {
   }
 }
 
+/** Present when Mate recorded regions for it, not merely when the file exists. */
+async function runtimeDocumentRecorded(repoPath: string, documentPath: string): Promise<boolean> {
+  return recordedDocuments(await readManifest(repoPath)).includes(documentPath);
+}
+
 async function writeProjectionPairEntry(input: ProjectionInput): Promise<"written" | "current"> {
   const { companionPath, repository } = input;
   const resolvedCompanionPath = path.resolve(companionPath!);
@@ -96,6 +127,26 @@ async function writeProjectionPairEntry(input: ProjectionInput): Promise<"writte
   return "written";
 }
 
+/**
+ * Places one rendered document and, when this pass wrote Mate's regions into a
+ * file inside the repository, asks Git whether it tracks that file. Only a
+ * write is worth the question: an unchanged document was reported when it was
+ * written, and a removal puts no companion path into it.
+ */
+async function writeRuntimeDocumentEntry(
+  input: ProjectionInput,
+  documentPath: string,
+): Promise<ProjectionWriteState | ProjectionWriteReport> {
+  const state = await placeRuntimeDocument(input.repoPath, documentPath, input.runtimeDocuments);
+  const rendered = input.runtimeDocuments?.some((document) => document.path === documentPath);
+  if (state !== "written" || !rendered || isExternalDocument(documentPath)) return state;
+  const repositoryId = input.repository?.id ?? path.basename(path.resolve(input.repoPath));
+  return {
+    state,
+    warnings: await trackedDocumentWarnings(input.repoPath, documentPath, repositoryId),
+  };
+}
+
 function tokensaveEnabled(input: ProjectionInput): boolean {
   return (input.config?.capabilities ?? []).some((capability) => capability.name === "tokensave");
 }
@@ -198,16 +249,53 @@ function buildEntries(): readonly ProjectionEntry[] {
       id: "projection-pair",
       kind: "owned",
       path: path.join(localDir, PROJECTION_YAML_FILE),
-      scopes: ["session"],
+      scopes: ["session", "wrap"],
       write: async (input) =>
         input.companionPath && input.repository ? writeProjectionPairEntry(input) : "skipped",
       removal: { by: "entry", entry: "projection-root" },
     },
+    /**
+     * The OpenSpec store pointer's exclusion, then the pointer: the line is on
+     * disk before the file it hides. Its own line outside the managed block,
+     * disjoint from `capability-excludes`, so neither strips the other's.
+     */
+    {
+      id: "openspec-store-exclude",
+      kind: "merged",
+      path: path.join(".git", "info", "exclude"),
+      scopes: ["session", "wrap"],
+      write: async (input) =>
+        (await reconcileStorePointerExclude(input.repoPath)) ? "written" : "current",
+      degradable: true,
+      removal: { by: "self", remove: (input) => removeStorePointerExclude(input.repoPath) },
+      present: (repoPath) =>
+        workingRepoCapabilityExcludesPresent(repoPath, [OPENSPEC_POINTER_EXCLUDE]),
+    },
+    /**
+     * Degradable: without it OpenSpec still plans in the companion, it only
+     * names no Working Repository edit root — and the wrapper says so.
+     */
+    {
+      id: "openspec-store-pointer",
+      kind: "owned",
+      path: OPENSPEC_POINTER_PATH,
+      scopes: ["session", "wrap"],
+      write: async (input) =>
+        input.companionPath ? projectStorePointer(input.repoPath, input.companionPath) : "skipped",
+      degradable: true,
+      removal: {
+        by: "self",
+        remove: (input) => removeStorePointer(input.repoPath),
+        retains: "openspec-store-registration",
+      },
+      present: storePointerPresent,
+    },
     {
       id: "claude-skill-links",
       kind: "merged",
       path: path.join(".claude", "skills"),
       scopes: ["wrap"],
+      runtime: "claude",
       removeOnUnwrap: true,
       write: async (input) => {
         if (!input.config) return "skipped";
@@ -219,6 +307,7 @@ function buildEntries(): readonly ProjectionEntry[] {
           input.companionPath ?? null,
           input.config.allowedAgents?.includes("claude") ?? false,
           registeredCompanionPaths,
+          input.audienceLayerDir ?? null,
         );
       },
       removal: {
@@ -236,7 +325,7 @@ function buildEntries(): readonly ProjectionEntry[] {
       id: "capability-excludes",
       kind: "merged",
       path: path.join(".git", "info", "exclude"),
-      scopes: ["launch"],
+      scopes: ["launch", "wrap"],
       write: async (input) => {
         if (!input.config) return "skipped";
         return (await reconcileWorkingRepoCapabilityExcludes(
@@ -259,6 +348,7 @@ function buildEntries(): readonly ProjectionEntry[] {
       kind: "merged",
       path: CLAUDE_WORKING_SETTINGS_PATH,
       scopes: ["launch", "wrap"],
+      runtime: "claude",
       write: async (input) =>
         input.companionPath
           ? syncWorkingRepoClaudeAdditionalDirectories(
@@ -276,14 +366,14 @@ function buildEntries(): readonly ProjectionEntry[] {
     },
     /**
      * Removal-only: Mate never writes this block, an external installer does.
-     * Its `write` is the same strip, so a launch heals a repository the
-     * installer touched without waiting for a cleanup.
+     * Its `write` is the same strip, so a launch or a wrap heals a repository
+     * the installer touched without waiting for a cleanup.
      */
     {
       id: "legacy-tokensave-claude-md",
       kind: "merged",
       path: LEGACY_TOKENSAVE_CLAUDE_MD_PATH,
-      scopes: ["launch"],
+      scopes: ["launch", "wrap"],
       write: async (input) =>
         (await stripTokensaveClaudeMdAppend(input.repoPath)) === "removed" ? "written" : "current",
       removal: { by: "self", remove: (input) => stripTokensaveClaudeMdAppend(input.repoPath) },
@@ -336,6 +426,7 @@ function buildEntries(): readonly ProjectionEntry[] {
       kind: "merged",
       path: CLAUDE_MCP_DOCUMENT,
       scopes: ["launch", "wrap"],
+      runtime: "claude",
       write: async (input) =>
         (await removeRuntimeDocument(input.repoPath, CLAUDE_MCP_DOCUMENT)) === "removed"
           ? "written"
@@ -344,7 +435,7 @@ function buildEntries(): readonly ProjectionEntry[] {
         by: "self",
         remove: (input) => removeRuntimeDocument(input.repoPath, CLAUDE_MCP_DOCUMENT),
       },
-      present: (repoPath) => runtimeDocumentPresent(repoPath, CLAUDE_MCP_DOCUMENT),
+      present: (repoPath) => runtimeDocumentRecorded(repoPath, CLAUDE_MCP_DOCUMENT),
     },
     ...(
       [
@@ -357,15 +448,37 @@ function buildEntries(): readonly ProjectionEntry[] {
       kind: "merged" as const,
       path: documentPath.split("/").join(path.sep),
       scopes: ["launch", "wrap"] as const,
-      write: (input: ProjectionInput) =>
-        placeRuntimeDocument(input.repoPath, documentPath, input.runtimeDocuments),
+      runtime: documentRuntime(documentPath),
+      write: (input: ProjectionInput) => writeRuntimeDocumentEntry(input, documentPath),
       removal: {
         by: "self" as const,
         remove: (input: { repoPath: string }) =>
           removeRuntimeDocument(input.repoPath, documentPath),
       },
-      present: (repoPath: string) => runtimeDocumentPresent(repoPath, documentPath),
+      present: (repoPath: string) => runtimeDocumentRecorded(repoPath, documentPath),
     })),
+    /**
+     * After the OpenCode document, so its copies arrive once the document that
+     * loads them is in place. A companion that dropped OpenCode has the copies
+     * an earlier wrap made withdrawn; the outcome names each copy written or
+     * withdrawn and warns about shadowed and locally edited ones.
+     */
+    {
+      id: "opencode-companion-copies",
+      kind: "merged",
+      path: ".opencode",
+      scopes: ["wrap"],
+      runtime: "opencode",
+      removeOnUnwrap: true,
+      write: async (input) => {
+        if (!input.config || !input.companionPath) return "skipped";
+        return (input.config.allowedAgents?.includes("opencode") ?? false)
+          ? reconcileCompanionCopies(input.repoPath, input.companionPath)
+          : withdrawCompanionCopies(input.repoPath);
+      },
+      removal: { by: "self", remove: (input) => removeCompanionCopies(input.repoPath) },
+      present: companionCopiesPresent,
+    },
   ];
 }