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

package/src/tools/setup/runtime-documents.ts

@@ -1,20 +1,23 @@
+import path from "node:path";
+
+import { runtimeOpenCodePluginRoot } from "../../runtime/runtime-directory";
 import {
   CLAUDE_LOCAL_CONFIG_DOCUMENT,
   CLAUDE_SETTINGS_DOCUMENT,
   OPENCODE_CONFIG_DOCUMENT,
-} from "../../lib/orchestrator/projection-runtime-documents";
-import type {
-  ManagedRegion,
-  RenderedRuntimeDocument,
-} from "../../lib/orchestrator/projection-types";
-import { getOpenCodePluginRoot } from "../../lib/package-paths";
+  OPENCODE_MCP_SERVERS_AT,
+  type ManagedRegion,
+  type RenderedRuntimeDocument,
+} from "../../runtime/runtime-document-manifest";
 import type { CapabilityContributionInput, SetupContext } from "./plugin";
 import {
   mateBannerHookGroups,
   mateGuardHookGroups,
   mateGuidanceHookGroups,
+  mateSessionPrepareHookGroups,
 } from "./providers/claude-plugin-hooks";
 import {
+  renderManagedClaudeHookGroups,
   renderManagedClaudeMcpServers,
   renderManagedClaudePermissionEntries,
 } from "./providers/claude";
@@ -22,6 +25,7 @@ import {
   renderCompanionExternalDirectoryPermissions,
   renderManagedOpenCodeMcpServers,
 } from "./providers/opencode";
+import { isRecord, readOpenCodeConfig } from "./providers/opencode-format";
 import { projectionRepoRoot } from "./surface-target";
 
 /**
@@ -47,40 +51,39 @@ function document(documentPath: string, regions: ManagedRegion[]): RenderedRunti
 /**
  * The Mate plugin root is what makes an Unmanaged OpenCode session load the
  * companion guidance at all: OpenCode has no config channel for a generated
- * system prompt, so the plugin is the only injection point, and a bare session
- * has no launch overlay to find it in. The root is machine-local, which this
- * git-excluded document tolerates and a committed config would not.
- *
- * A managed launch lists the same root in its `OPENCODE_CONFIG_CONTENT`
- * overlay; OpenCode dedupes identical plugin paths across config sources.
+ * system prompt, so the plugin is the only injection point. It is named through
+ * the runtime directory, so a reinstall does not strand a wrapped repository.
+ * The managed launch carries no overlay of its own, so this document is the one
+ * place every OpenCode session in the repository loads it from.
  */
 
 /**
- * Capability hook groups stay companion-only. A managed session loads this
- * document as its `local` source *alongside* the companion's, so anything here
- * that the launch also delivers runs twice; the guard, the guidance hook and
- * the banner are the contributions whose absence is a correctness hole and
- * whose double run is inert — the guard because its verdict depends only on the
- * tool input, the guidance hook because it yields nothing under a launch
- * environment, and the banner because the copy carried here is flagged
- * `--projected` and defers to the one the launch's own plugin prints.
- *
- * `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` is what a managed launch sets
- * beside `--add-dir`. Without it the companion directories this document
- * already permits are reachable but their `CLAUDE.md` is not loaded, so the
- * permission alone delivers no guidance.
+ * Loaded by a managed session beside the launch's plugin. Mate hooks here run
+ * twice there, inertly: guard is input-pure, guidance/prepare yield under a
+ * launch env, banner is `--projected`. Capability groups run once: the launch
+ * omits them from `--settings`. A launch passes no `--add-dir`; it relies on
+ * `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` for companion `CLAUDE.md`.
  */
 function claudeSettingsRegions(
   ctx: SetupContext,
   inputs: CapabilityContributionInput[],
 ): ManagedRegion[] {
+  const capabilityHooks = renderManagedClaudeHookGroups(inputs);
+  const mateHooks: Record<string, unknown[]> = {
+    PreToolUse: mateGuardHookGroups(),
+    SessionStart: [
+      ...mateBannerHookGroups(),
+      ...mateGuidanceHookGroups(),
+      ...mateSessionPrepareHookGroups(),
+    ],
+  };
+  const events = [...new Set([...Object.keys(mateHooks), ...Object.keys(capabilityHooks)])];
   return [
-    { at: ["hooks", "PreToolUse"], kind: "list", values: mateGuardHookGroups() },
-    {
-      at: ["hooks", "SessionStart"],
+    ...events.map((event): ManagedRegion => ({
+      at: ["hooks", event],
       kind: "list",
-      values: [...mateBannerHookGroups(), ...mateGuidanceHookGroups()],
-    },
+      values: [...(mateHooks[event] ?? []), ...(capabilityHooks[event] ?? [])],
+    })),
     /**
      * `stripPrefix` heals a repository an older Mate wrapped. That version wrote
      * the whole launch environment here, and Claude Code applies `env` to the
@@ -152,10 +155,10 @@ export function renderDocumentsForTarget(
         {
           at: ["plugins"],
           kind: "list",
-          values: [getOpenCodePluginRoot()],
+          values: [runtimeOpenCodePluginRoot()],
         },
         {
-          at: ["mcp", "servers"],
+          at: [...OPENCODE_MCP_SERVERS_AT],
           kind: "map",
           entries: renderManagedOpenCodeMcpServers(inputs),
         },
@@ -164,8 +167,125 @@ export function renderDocumentsForTarget(
           kind: "list",
           values: renderCompanionExternalDirectoryPermissions(ctx.companionPath),
         },
+        {
+          at: ["skills"],
+          kind: "list",
+          values: [path.join(ctx.companionPath, ".agents", "skills")],
+        },
+        { at: ["references"], kind: "map", entries: { mate: ctx.companionPath } },
       ]),
     );
   }
   return documents;
 }
+
+/** Keys Mate renders its own regions for; the companion's values join those regions. */
+const MATE_OPENCODE_KEYS = new Set(["plugins", "permissions", "skills", "mcp", "references"]);
+
+function relativePathValues(value: unknown, at: string[]): string[] {
+  if (typeof value === "string") {
+    return value.startsWith("./") || value.startsWith("../") ? [at.join(".")] : [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((entry, index) => relativePathValues(entry, [...at, String(index)]));
+  }
+  if (isRecord(value)) {
+    return Object.entries(value).flatMap(([key, entry]) => relativePathValues(entry, [...at, key]));
+  }
+  return [];
+}
+
+/** Replaces the region at `at` with what `merge` builds from it, or appends one. */
+function upsertRegion(
+  regions: ManagedRegion[],
+  at: string[],
+  merge: (found: ManagedRegion | undefined) => ManagedRegion,
+): void {
+  const key = JSON.stringify(at);
+  const index = regions.findIndex((region) => JSON.stringify(region.at) === key);
+  if (index === -1) regions.push(merge(undefined));
+  else regions[index] = merge(regions[index]);
+}
+
+/** Mate's own values stay; companion values it does not already list go first. */
+function mergeListRegion(regions: ManagedRegion[], at: string[], extra: unknown[]): void {
+  upsertRegion(regions, at, (found) => {
+    const own = found?.kind === "list" ? found.values : [];
+    const seen = new Set(own.map((value) => JSON.stringify(value)));
+    const values = [...extra.filter((value) => !seen.has(JSON.stringify(value))), ...own];
+    return { at, kind: "list", values };
+  });
+}
+
+/** Mate's own entries win over companion entries of the same name. */
+function mergeMapRegion(
+  regions: ManagedRegion[],
+  at: string[],
+  extra: Record<string, unknown>,
+): void {
+  upsertRegion(regions, at, (found) => {
+    const own = found?.kind === "map" ? found.entries : {};
+    return { at, kind: "map", entries: { ...extra, ...own } };
+  });
+}
+
+/** Relative reference paths resolved against the companion's `.opencode/`. */
+function resolveReferences(
+  references: Record<string, unknown>,
+  companionDir: string,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(references).map(([name, reference]) => [
+      name,
+      typeof reference === "string" && !path.isAbsolute(reference)
+        ? path.resolve(companionDir, reference)
+        : reference,
+    ]),
+  );
+}
+
+/**
+ * Folds the companion's `.opencode/opencode.json` into the wrapped document.
+ * Mate's regions beat companion values; other top-level keys yield to the
+ * repository's. `references` resolve against the companion's `.opencode/`;
+ * other relative paths are reported, not rewritten.
+ */
+export async function mergeCompanionOpenCodeConfig(
+  companionPath: string,
+  documents: RenderedRuntimeDocument[],
+): Promise<{ documents: RenderedRuntimeDocument[]; warnings: string[] }> {
+  const index = documents.findIndex((document) => document.path === OPENCODE_CONFIG_DOCUMENT);
+  const companionConfigPath = path.join(companionPath, ".opencode", "opencode.json");
+  const companion = index === -1 ? null : await readOpenCodeConfig(companionConfigPath);
+  if (!companion?.present) return { documents, warnings: [] };
+
+  const regions = [...documents[index]!.regions] as ManagedRegion[];
+  const warnings: string[] = [];
+
+  const companionDir = path.dirname(companionConfigPath);
+  for (const [key, value] of Object.entries(companion.config)) {
+    if (key === "$schema") continue;
+    if (key === "references" && isRecord(value)) {
+      mergeMapRegion(regions, ["references"], resolveReferences(value, companionDir));
+      continue;
+    }
+    for (const at of relativePathValues(value, [key])) {
+      warnings.push(
+        `${companionConfigPath}: ${at} is a relative path, which resolves against the working repository once merged into ${OPENCODE_CONFIG_DOCUMENT}; use an absolute path.`,
+      );
+    }
+    if (MATE_OPENCODE_KEYS.has(key)) {
+      if (key === "mcp" && isRecord(value) && isRecord(value.servers)) {
+        mergeMapRegion(regions, [...OPENCODE_MCP_SERVERS_AT], value.servers);
+      } else if (Array.isArray(value)) {
+        mergeListRegion(regions, [key], value);
+      }
+      continue;
+    }
+    regions.push({ at: [key], kind: "value", value, yields: true });
+  }
+
+  const next = [...documents];
+  next[index] = { path: OPENCODE_CONFIG_DOCUMENT, regions };
+  return { documents: next, warnings };
+}

package/src/tools/setup/working-repo-local-state.ts

@@ -5,8 +5,17 @@ import { resolveGitInfoExcludePath } from "./git-utils";
 
 const MANAGED_BLOCK_START = "# mate managed: start";
 const MANAGED_BLOCK_END = "# mate managed: end";
-/** `.mcp.json` is the one working-target document no directory entry covers. */
-const CORE_EXCLUDE_ENTRIES = ["/.mate/", "/.claude/", "/.opencode/", "/.agents/", "/.mcp.json"];
+/**
+ * Documents no directory entry covers. `.opencode/` is per file: the repository's
+ * own files there stay visible; copies get the copies block.
+ */
+const CORE_EXCLUDE_ENTRIES = [
+  "/.mate/",
+  "/.claude/",
+  "/.opencode/opencode.json",
+  "/.agents/",
+  "/.mcp.json",
+];
 const LEGACY_CORE_EXCLUDE_ENTRIES = new Set([".mate/", ".claude/settings.local.json"]);
 
 async function readExclude(excludePath: string): Promise<string> {
@@ -60,16 +69,43 @@ async function writeExclude(
   return true;
 }
 
+/** The first `startMarker`…`endMarker` pair, inclusive; `null` when either is missing. */
+function findBlock(
+  lines: string[],
+  startMarker: string,
+  endMarker: string,
+): { start: number; end: number } | null {
+  const start = lines.findIndex((line) => line.trim() === startMarker);
+  if (start === -1) return null;
+  const end = lines.findIndex((line, index) => index > start && line.trim() === endMarker);
+  return end === -1 ? null : { start, end };
+}
+
+function withoutLegacy(lines: string[]): string[] {
+  return withoutManagedBlocks(lines).filter(
+    (line) => !LEGACY_CORE_EXCLUDE_ENTRIES.has(line.trim()),
+  );
+}
+
 export async function ensureWorkingRepoLocalExcludes(repoPath: string): Promise<boolean> {
   const excludePath = await resolveGitInfoExcludePath(repoPath);
   if (!excludePath) return false;
   const existing = await readExclude(excludePath);
-  const lines = trimTrailingEmptyLines(
-    withoutManagedBlocks(contentLines(existing)).filter(
-      (line) => !LEGACY_CORE_EXCLUDE_ENTRIES.has(line.trim()),
-    ),
-  );
-  lines.push(MANAGED_BLOCK_START, ...CORE_EXCLUDE_ENTRIES, MANAGED_BLOCK_END);
+  const current = contentLines(existing);
+  const block = [MANAGED_BLOCK_START, ...CORE_EXCLUDE_ENTRIES, MANAGED_BLOCK_END];
+  /**
+   * Rewritten where it stands, not moved to the end: a block that follows it,
+   * like the companion copies', would otherwise trade places with it on every
+   * pass and turn an unchanged wrap into a write.
+   */
+  const managed = findBlock(current, MANAGED_BLOCK_START, MANAGED_BLOCK_END);
+  const lines = managed
+    ? trimTrailingEmptyLines([
+        ...withoutLegacy(current.slice(0, managed.start)),
+        ...block,
+        ...withoutLegacy(current.slice(managed.end + 1)),
+      ])
+    : [...trimTrailingEmptyLines(withoutLegacy(current)), ...block];
   return writeExclude(excludePath, existing, lines);
 }
 
@@ -114,10 +150,43 @@ export async function removeWorkingRepoLocalExcludes(repoPath: string): Promise<
   const excludePath = await resolveGitInfoExcludePath(repoPath);
   if (!excludePath) return false;
   const existing = await readExclude(excludePath);
-  const lines = trimTrailingEmptyLines(
-    withoutManagedBlocks(contentLines(existing)).filter(
-      (line) => !LEGACY_CORE_EXCLUDE_ENTRIES.has(line.trim()),
-    ),
-  );
+  const lines = trimTrailingEmptyLines(withoutLegacy(contentLines(existing)));
+  return writeExclude(excludePath, existing, lines);
+}
+
+const COPIES_BLOCK_START = "# mate managed copies: start";
+const COPIES_BLOCK_END = "# mate managed copies: end";
+
+/** A literal repo-relative path as an anchored exclude pattern. */
+function literalExcludeEntry(relativePath: string): string {
+  const escaped = relativePath.replace(/[\\*?[\]]/g, "\\$&");
+  return `/${escaped}`;
+}
+
+function withoutCopiesBlock(lines: string[]): string[] {
+  const block = findBlock(lines, COPIES_BLOCK_START, COPIES_BLOCK_END);
+  return block ? [...lines.slice(0, block.start), ...lines.slice(block.end + 1)] : lines;
+}
+
+/**
+ * One exclude line per owned companion copy, in a block of its own so the core
+ * block's rewrite leaves it alone. Per file rather than `/.opencode/`, so a file
+ * the repository adds there itself stays visible to Git.
+ */
+export async function reconcileWorkingRepoCopyExcludes(
+  repoPath: string,
+  relativePaths: readonly string[],
+): Promise<boolean> {
+  const excludePath = await resolveGitInfoExcludePath(repoPath);
+  if (!excludePath) return false;
+  const existing = await readExclude(excludePath);
+  const lines = trimTrailingEmptyLines(withoutCopiesBlock(contentLines(existing)));
+  if (relativePaths.length > 0) {
+    lines.push(
+      COPIES_BLOCK_START,
+      ...relativePaths.toSorted().map(literalExcludeEntry),
+      COPIES_BLOCK_END,
+    );
+  }
   return writeExclude(excludePath, existing, lines);
 }

package/src/tools/setup.ts

@@ -40,9 +40,9 @@ import {
   buildSetupInstallationPlan,
   executeSetupInstallationPlan,
   renderRuntimeDocuments,
+  type RenderedRuntimeDocuments,
   type SetupInstallationOutcome,
 } from "./setup/engine";
-import type { RenderedRuntimeDocument } from "../lib/orchestrator/projection-types";
 
 export interface SetupInput {
   allowedAgents?: string[];
@@ -81,7 +81,7 @@ export async function renderWorkingRuntimeDocuments(
   config: FrameworkConfig,
   repoPath: string,
   plugins: PluginRegistration[] = getActiveDistribution().registry.getAll(),
-): Promise<RenderedRuntimeDocument[]> {
+): Promise<RenderedRuntimeDocuments> {
   const plan = buildSetupInstallationPlan(config, plugins);
   const ctx: SetupContext = {
     companionPath,

package/src/lib/orchestrator/companion-registry-reader.ts

@@ -1,37 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-import { parse } from "yaml";
-
-import { FRAMEWORK_NAME } from "../../framework";
-import type { LinkedRepository } from "./types";
-
-export function companionRegistryPath(companionPath: string): string {
-  return path.join(path.resolve(companionPath), `.${FRAMEWORK_NAME}`, "config", "registry.yaml");
-}
-
-export interface CompanionRegistryReadResult {
-  repos: LinkedRepository[];
-}
-
-/**
- * Parses a companion's `registry.yaml` without the writes {@link
- * CompanionRegistryStore.load} performs (legacy-field migration, stale-pointer
- * cleanup). Callers that must not mutate registry state on a read (e.g.
- * inventory, materialization) use this instead. Throws ENOENT when the file
- * doesn't exist; throws on unparsable YAML.
- */
-export async function readCompanionRegistry(
-  companionPath: string,
-): Promise<CompanionRegistryReadResult> {
-  const raw = await fs.readFile(companionRegistryPath(companionPath), "utf8");
-  const parsed = parse(raw) as { repos?: unknown } | null;
-  const rawRepos = Array.isArray(parsed?.repos) ? parsed.repos : [];
-  const repos = rawRepos
-    .filter(
-      (entry): entry is LinkedRepository =>
-        Boolean(entry) && typeof entry.id === "string" && typeof entry.path === "string",
-    )
-    .map(({ id, path: repoPath }) => ({ id, path: repoPath }));
-  return { repos };
-}

package/src/lib/orchestrator/companion-resolver.ts

@@ -1,179 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-import { parse } from "yaml";
-
-import { readCompanionRegistry } from "./companion-registry-reader";
-import type { GlobalConfigStore } from "./global-config-store";
-import {
-  findRepoLocalRegistryFile,
-  pathIsDirectory,
-  repoLocalRegistryPath,
-  type RepoLocalCompanionPointer,
-  RepoLocalRegistryStore,
-} from "./repo-local-registry";
-
-export interface CompanionMatch {
-  companionPath: string;
-  repositoryId: string;
-}
-
-export interface CompanionResolutionFailure {
-  companionPath: string;
-  message: string;
-}
-
-export interface CompanionResolutionResult {
-  match: CompanionMatch | null;
-  /**
-   * All companions whose registry links the same repo path at the best
-   * (longest) match length as `match`. Populated with more than one entry
-   * only when the same working repo is linked from more than one distinct
-   * companion, so callers that must pick a single companion (e.g. launch
-   * commands) can detect the ambiguity and prompt the user instead of
-   * silently using whichever companion happened to be listed first.
-   */
-  ambiguousMatches: CompanionMatch[];
-  failures: CompanionResolutionFailure[];
-}
-
-export class CompanionResolver {
-  constructor(private readonly globalConfigStore: GlobalConfigStore) {}
-
-  async resolve(cwd: string): Promise<CompanionMatch | null> {
-    return (await this.resolveWithDiagnostics(cwd, { logFailures: true })).match;
-  }
-
-  async resolveWithDiagnostics(
-    cwd: string,
-    options: { logFailures?: boolean } = {},
-  ): Promise<CompanionResolutionResult> {
-    const resolvedCwd = path.resolve(cwd);
-
-    const repoLocalResult = await this.resolveFromRepoLocalRegistry(resolvedCwd, options);
-    if (repoLocalResult) return repoLocalResult;
-
-    return this.resolveFromGlobalRegistry(resolvedCwd);
-  }
-
-  /**
-   * Fallback for when the repo-local cache is missing or unusable: scans
-   * every companion the global registry knows about and matches by
-   * repository path. A single match self-heals the repo-local cache so the
-   * fast path succeeds on the next resolution without repeating this scan.
-   */
-  private async resolveFromGlobalRegistry(resolvedCwd: string): Promise<CompanionResolutionResult> {
-    const candidates = await this.globalConfigStore.list();
-    const found = await Promise.all(
-      candidates.map(async (candidate) => {
-        const companionPath = path.resolve(candidate);
-        try {
-          const { repos } = await readCompanionRegistry(companionPath);
-          const repo = repos.find((r) => path.resolve(r.path) === resolvedCwd);
-          return repo ? { companionPath, repositoryId: repo.id } : null;
-        } catch {
-          return null;
-        }
-      }),
-    );
-
-    const seenCompanionPaths = new Set<string>();
-    const matches = found.filter((match): match is CompanionMatch => {
-      if (!match || seenCompanionPaths.has(match.companionPath)) return false;
-      seenCompanionPaths.add(match.companionPath);
-      return true;
-    });
-
-    if (matches.length === 0) return { match: null, ambiguousMatches: [], failures: [] };
-
-    if (matches.length === 1) {
-      const store = new RepoLocalRegistryStore(repoLocalRegistryPath(resolvedCwd));
-      await store.save({
-        companions: [{ path: matches[0]!.companionPath, repositoryId: matches[0]!.repositoryId }],
-      });
-    }
-
-    return {
-      match: matches[0]!,
-      ambiguousMatches: matches.length > 1 ? matches : [],
-      failures: [],
-    };
-  }
-
-  /**
-   * Fast path: reads the working repo's own `.mate/config/registry.yaml`
-   * before scanning every registered companion. Treats the file as the
-   * working repo's source of truth for companion pointers: existing
-   * directories are accepted immediately, stale paths are dropped, and
-   * absence of usable local data means the repo is not linked.
-   */
-  private async resolveFromRepoLocalRegistry(
-    resolvedCwd: string,
-    options: { logFailures?: boolean },
-  ): Promise<CompanionResolutionResult | null> {
-    const found = await findRepoLocalRegistryFile(resolvedCwd);
-    if (!found) return null;
-
-    let pointers: RepoLocalCompanionPointer[];
-    try {
-      const raw = await fs.readFile(found.registryPath, "utf8");
-      const parsed = parse(raw) as { companions?: unknown } | null;
-      if (!parsed || !Array.isArray(parsed.companions)) return null;
-      pointers = parsed.companions as RepoLocalCompanionPointer[];
-    } catch {
-      return null;
-    }
-
-    if (pointers.length === 0) return null;
-
-    const survivors: RepoLocalCompanionPointer[] = [];
-    const validMatches: CompanionMatch[] = [];
-    let changed = false;
-
-    const checkedPointers = await Promise.all(
-      pointers.map(async (pointer) => {
-        const companionPath = path.resolve(pointer.path);
-        return { pointer, companionPath, exists: await pathIsDirectory(companionPath) };
-      }),
-    );
-
-    for (const { pointer, companionPath, exists } of checkedPointers) {
-      if (exists) {
-        survivors.push({
-          path: companionPath,
-          repositoryId: pointer.repositoryId,
-          source: pointer.source,
-        });
-        validMatches.push({ companionPath, repositoryId: pointer.repositoryId });
-        continue;
-      }
-
-      changed = true;
-      if (options.logFailures) {
-        console.error(
-          `mate: dropping stale repo-local companion pointer (no longer exists): ${companionPath}`,
-        );
-      }
-    }
-
-    if (changed) {
-      const store = new RepoLocalRegistryStore(found.registryPath);
-      await store.save({ companions: survivors });
-    }
-
-    if (validMatches.length === 0) return null;
-
-    const seenCompanionPaths = new Set<string>();
-    const ambiguousMatches = validMatches.filter((match) => {
-      if (seenCompanionPaths.has(match.companionPath)) return false;
-      seenCompanionPaths.add(match.companionPath);
-      return true;
-    });
-
-    return {
-      match: ambiguousMatches[0]!,
-      ambiguousMatches: ambiguousMatches.length > 1 ? ambiguousMatches : [],
-      failures: [],
-    };
-  }
-}