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

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);
 }
 
@@ -82,8 +118,16 @@ export async function reconcileWorkingRepoCapabilityExcludes(
   if (!excludePath) return false;
   const existing = await readExclude(excludePath);
   const managed = new Set(managedEntries);
+  const desired = new Set(desiredEntries);
+  /**
+   * A desired line stays where it stands: re-appending it would trade places
+   * with a block written after it, like the companion copies', on every pass.
+   */
   const lines = trimTrailingEmptyLines(
-    contentLines(existing).filter((line) => !managed.has(line.trim())),
+    contentLines(existing).filter((line) => {
+      const entry = line.trim();
+      return desired.has(entry) || !managed.has(entry);
+    }),
   );
   for (const entry of desiredEntries) {
     if (!lines.some((line) => line.trim() === entry)) lines.push(entry);
@@ -114,10 +158,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[];
@@ -61,7 +61,7 @@ export async function applySetupCompatibilities(
   companionPath: string,
   config: FrameworkConfig,
   mode: "setup" | "sync",
-  plugins: PluginRegistration[] = getActiveDistribution().registry.getEntries(),
+  plugins: PluginRegistration[] = getActiveDistribution().registry.baseRegistrations(),
   repoPath?: string,
   scope: SetupScope = config.type === "hub" ? "hub" : "companion",
 ): Promise<SetupInstallationOutcome> {
@@ -73,15 +73,16 @@ export async function applySetupCompatibilities(
 
 /**
  * The active Agent Runtimes' documents for a Working Repository, rendered
- * without a write. Runs no plugin phase: the working target reconciles
+ * without a write: base, plus the audience the checkout is wrapped for. Runs no plugin phase: the working target reconciles
  * declarations only, so nothing is written to the companion on its behalf.
  */
 export async function renderWorkingRuntimeDocuments(
   companionPath: string,
   config: FrameworkConfig,
   repoPath: string,
-  plugins: PluginRegistration[] = getActiveDistribution().registry.getAll(),
-): Promise<RenderedRuntimeDocument[]> {
+  plugins: PluginRegistration[] = getActiveDistribution().registry.baseRegistrations(),
+  wrapped?: { audience: string; registrations: PluginRegistration[] },
+): Promise<RenderedRuntimeDocuments> {
   const plan = buildSetupInstallationPlan(config, plugins);
   const ctx: SetupContext = {
     companionPath,
@@ -91,7 +92,7 @@ export async function renderWorkingRuntimeDocuments(
     repoPath,
     target: "working",
   };
-  return renderRuntimeDocuments(ctx, plugins, plan);
+  return renderRuntimeDocuments(ctx, plugins, plan, wrapped);
 }
 
 export async function updateProjectGitignore(
@@ -99,7 +100,9 @@ export async function updateProjectGitignore(
   config: FrameworkConfig,
 ): Promise<void> {
   const ctx: SetupContext = { companionPath, config, mode: "sync", activeProviders: [] };
-  const plugins = getActiveDistribution().registry.getAll();
+  const plugins = getActiveDistribution()
+    .registry.baseRegistrations()
+    .map((entry) => entry.plugin);
   const entries = collectManagedGitignoreEntries(ctx, plugins);
   await writeManagedGitignoreBlock(path.join(companionPath, ".gitignore"), FRAMEWORK_NAME, entries);
 }
@@ -113,7 +116,7 @@ export async function syncCompanionFiles(
     companionPath,
     config,
     "sync",
-    getActiveDistribution().registry.getAll(),
+    getActiveDistribution().registry.baseRegistrations(),
     repoPath,
   );
 }

package/wrappers/bin/openspec

@@ -30,10 +30,12 @@ _mate_same_dir() {
 }
 
 _companion="$MATE_ARTIFACT_PATH"
+_repo="$MATE_REPO_PATH"
 if [ -z "$_companion" ]; then
   _projection="$(_mate_projection_file)"
   if [ -n "$_projection" ]; then
     _companion="$(_mate_projected "$_projection" MATE_ARTIFACT_PATH)"
+    _repo="$(_mate_projected "$_projection" MATE_REPO_PATH)"
     _projected_wrapper_dir="$(_mate_projected "$_projection" MATE_WRAPPER_BIN_PATH)"
     if [ -n "$_companion" ] && ! _mate_same_dir "$_projected_wrapper_dir" "$_this_dir"; then
       {
@@ -92,4 +94,43 @@ if [ "$command" = "templates" ]; then
     fi
   fi
 fi
-exec env -C "$_companion" "$_real" "$@"
+
+_mate_is_under() {
+  case "$1/" in "$2"/*) return 0 ;; esac
+  return 1
+}
+
+# Moves _cwd to the Working Repository root when the caller is inside that
+# repository, outside the companion, and the root carries Mate's pointer.
+_mate_use_store_pointer() {
+  [ -n "$_repo" ] && [ -d "$_repo" ] || return 0
+  local repo_root here companion_root pointer first
+  repo_root="$(cd "$_repo" && pwd -P)"
+  here="$(pwd -P)"
+  companion_root="$(cd "$_companion" 2>/dev/null && pwd -P)"
+  _mate_is_under "$here" "$repo_root" || return 0
+  [ -n "$companion_root" ] && _mate_is_under "$here" "$companion_root" && return 0
+  pointer="$repo_root/openspec/config.yaml"
+  if [ -f "$pointer" ]; then
+    IFS= read -r first < "$pointer" || true
+    case "$first" in
+      "# generated by "*" — do not edit") _cwd="$repo_root" ;;
+    esac
+  elif [ ! -f "$repo_root/openspec/config.yml" ]; then
+    echo "openspec: no OpenSpec store pointer in $repo_root, so edits are scoped to the companion — run \`mate wrap\` to enable Working Repository edit roots" >&2
+  fi
+}
+
+# Commands that resolve an OpenSpec root run from the Working Repository root
+# when it carries Mate's store pointer: OpenSpec then plans in the companion's
+# store and names the repository as the edit root. The root, not the caller's
+# cwd, so a nested openspec/ cannot win. Every other case — including
+# templates, init and update, which do not resolve stores — stays on the
+# companion, exactly as before.
+_cwd="$_companion"
+case "$command" in
+  new|status|instructions|list|show|validate|archive|doctor|context|schemas|view)
+    _mate_use_store_pointer
+    ;;
+esac
+exec env -C "$_cwd" "$_real" "$@"

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: [],
-    };
-  }
-}

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

@@ -1,94 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-import { FRAMEWORK_NAME } from "../../framework";
-import { CompanionRegistryStore } from "./companion-registry-store";
-import { ConfigStore } from "./config-store";
-import { pathIsDirectory, writeRepoLocalRegistryEntry } from "./repo-local-registry";
-import { type CompanionSource, ConfigError, type LinkedRepository } from "./types";
-
-/** Builds a {@link CompanionStore} whose config/registry files live under `<companionPath>/.mate/config`, regardless of `process.cwd()`. */
-export function companionRootedStore(companionPath: string): CompanionStore {
-  const configDir = path.join(path.resolve(companionPath), `.${FRAMEWORK_NAME}`, "config");
-  return new CompanionStore(
-    new ConfigStore(path.join(configDir, "framework.yaml")),
-    new CompanionRegistryStore(path.join(configDir, "registry.yaml")),
-  );
-}
-
-export class CompanionStore {
-  constructor(
-    private readonly configStore = new ConfigStore(),
-    private readonly companionRegistryStore = new CompanionRegistryStore(),
-  ) {}
-
-  async registerRepository(
-    repository: LinkedRepository,
-    options: { companionSource?: CompanionSource } = {},
-  ): Promise<LinkedRepository> {
-    const stats = await fs.stat(repository.path).catch(() => null);
-    if (!stats?.isDirectory()) {
-      throw new ConfigError(
-        `Linked repository path must exist and be a directory: ${repository.path}`,
-      );
-    }
-
-    // A companion's registry.yaml may not exist yet (its first-ever link):
-    // that is not a real error here, unlike a working repo reading its own
-    // missing config, so fall back to an empty registry instead of throwing.
-    const working = await this.companionRegistryStore.load().catch((error) => {
-      if (error instanceof ConfigError) return CompanionRegistryStore.defaultConfig();
-      throw error;
-    });
-
-    // Prune dead entries (path no longer a directory) as part of this same
-    // write, piggybacking on the load/save that registration already does
-    // rather than adding a separate scan; never runs on a read-only list.
-    const checked = await Promise.all(
-      working.repos.map(async (repo) => ({ repo, exists: await pathIsDirectory(repo.path) })),
-    );
-    const survivors: LinkedRepository[] = [];
-    for (const entry of checked) {
-      if (entry.exists) survivors.push(entry.repo);
-    }
-
-    const existing = survivors.findIndex((r) => r.id === repository.id);
-    if (existing >= 0) {
-      survivors[existing] = repository;
-    } else {
-      survivors.push(repository);
-    }
-    working.repos = survivors;
-    await this.companionRegistryStore.save(working);
-
-    // Repo-local registry write is a cache, not the source of truth: the
-    // companion-side write above already succeeded, so a failure here (e.g. a
-    // read-only working tree) must not fail the overall link operation.
-    try {
-      const companionRoot = path.resolve(path.dirname(this.configStore.configPath), "..", "..");
-      await writeRepoLocalRegistryEntry(
-        repository.path,
-        companionRoot,
-        repository,
-        options.companionSource ?? "git",
-      );
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      console.error(
-        `mate: warning: failed to write repo-local registry for ${repository.path}: ${message}`,
-      );
-    }
-
-    return repository;
-  }
-
-  async getRepository(repositoryId: string): Promise<LinkedRepository | undefined> {
-    const working = await this.companionRegistryStore.load();
-    return working.repos.find((r) => r.id === repositoryId);
-  }
-
-  async listRepositories(): Promise<LinkedRepository[]> {
-    const working = await this.companionRegistryStore.load();
-    return working.repos;
-  }
-}