@uniqbit/mate-core 0.18.3 → 0.18.4

package/src/tools/setup/upgrade-sweep.ts

@@ -0,0 +1,153 @@
+// oxlint-disable no-await-in-loop
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import { removeManagedBlocksForPlugin } from "./context-services";
+import {
+  audiencePluginDeclarations,
+  declaredAudiences,
+  effectivePluginDeclarations,
+  readFrameworkRaw,
+} from "./dynamic-plugins/audiences";
+import { validateDeclaration } from "./dynamic-plugins/declarations";
+import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./dynamic-plugins/loader";
+import type { CapabilityContributionInput, CapabilityPlugin, Plugin, SetupContext } from "./plugin";
+import type { NormalizedRegistration } from "./registry";
+
+/**
+ * Upgrade Sweep: removes what audience plugins leaked into a companion before
+ * the contribution ledger existed. Runs once, when a persisted pass finds no
+ * ledger, and again only for the packages it could not load then.
+ */
+
+/** The companion files Mate's managed guidance blocks live in. */
+const GUIDANCE_FILES = ["CLAUDE.md", "AGENTS.md", path.join(".opencode", "AGENTS.md")];
+
+const MANAGED_BLOCK_START = new RegExp(
+  `<!-- ${FRAMEWORK_NAME}:managed:([^\\n]+):[0-9a-f]+ start -->`,
+  "g",
+);
+
+/** Plugin ids owning a managed guidance block in `text`. */
+export function managedBlockOwners(text: string): string[] {
+  return [...new Set([...text.matchAll(MANAGED_BLOCK_START)].map((match) => match[1]!))];
+}
+
+/** `relative path → owners` for every managed guidance block under `root`. */
+export async function managedGuidanceOwners(root: string): Promise<Map<string, string[]>> {
+  const owners = new Map<string, string[]>();
+  for (const file of GUIDANCE_FILES) {
+    const text = await fs.readFile(path.join(root, file), "utf8").catch(() => null);
+    if (text === null) continue;
+    const found = managedBlockOwners(text);
+    if (found.length > 0) owners.set(file, found);
+  }
+  return owners;
+}
+
+/**
+ * Guidance blocks name their owner, so this needs no plugin loaded: every
+ * block whose owner is not a base registration goes.
+ */
+export async function removeForeignGuidanceBlocks(
+  root: string,
+  baseIds: ReadonlySet<string>,
+): Promise<void> {
+  for (const [file, owners] of await managedGuidanceOwners(root)) {
+    for (const owner of owners) {
+      if (baseIds.has(owner)) continue;
+      await removeManagedBlocksForPlugin(path.join(root, file), FRAMEWORK_NAME, owner);
+    }
+  }
+}
+
+export interface AudienceSweep {
+  /** Disabled inputs for every swept plugin, per runtime. */
+  teardown: Map<string, CapabilityContributionInput[]>;
+  /** Packages that could not be loaded; their non-guidance entries stay until a retry. */
+  unswept: string[];
+  warnings: string[];
+}
+
+export interface AudienceSweepOptions {
+  /** Every registration of the process; an audience plugin already loaded is reused, not reloaded. */
+  registrations: readonly NormalizedRegistration[];
+  /** Restrict the sweep to these packages; every audience declaration when absent. */
+  packages?: ReadonlySet<string>;
+  deps?: DynamicPluginLoadDeps;
+}
+
+/** One distinct package per audience declaration, base packages excluded. */
+function audiencePackages(raw: unknown): Map<string, ReturnType<typeof validateDeclaration>> {
+  const basePackages = new Set(
+    effectivePluginDeclarations(raw, null).flatMap((entry) => {
+      const { declaration } = validateDeclaration(entry);
+      return declaration ? [declaration.package] : [];
+    }),
+  );
+  const found = new Map<string, ReturnType<typeof validateDeclaration>>();
+  for (const audience of declaredAudiences(raw)) {
+    for (const entry of audiencePluginDeclarations(raw, audience)) {
+      const validated = validateDeclaration(entry);
+      const name = validated.declaration?.package;
+      if (!name || basePackages.has(name) || found.has(name)) continue;
+      found.set(name, validated);
+    }
+  }
+  return found;
+}
+
+/**
+ * Collects the declarations of every audience plugin as disabled inputs:
+ * loaded for its declarations only — never activated, no lifecycle hook run.
+ * An unloadable plugin is reported, never fatal.
+ */
+export async function sweepAudienceDeclarations(
+  ctx: SetupContext,
+  options: AudienceSweepOptions,
+): Promise<AudienceSweep> {
+  const sweep: AudienceSweep = { teardown: new Map(), unswept: [], warnings: [] };
+  const raw = await readFrameworkRaw(ctx.companionPath);
+
+  for (const [name, { declaration }] of audiencePackages(raw)) {
+    if (options.packages && !options.packages.has(name)) continue;
+    let plugin: Plugin | undefined = options.registrations.find(
+      (entry) => entry.packageName === name,
+    )?.plugin;
+    if (!plugin) {
+      const loaded = await loadDynamicPlugin(ctx.companionPath, declaration!, options.deps);
+      if (!loaded.ok) {
+        sweep.unswept.push(name);
+        sweep.warnings.push(
+          `audience plugin "${name}" was not swept from the companion: ${loaded.warning} Its entries stay until a pass can load it.`,
+        );
+        continue;
+      }
+      plugin = loaded.plugin;
+    }
+
+    const capability = plugin as CapabilityPlugin;
+    if (plugin.kind !== "capability" || !capability.getRuntimeContributions) continue;
+    try {
+      const byRuntime = await capability.getRuntimeContributions(ctx);
+      for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
+        if (!contributions) continue;
+        const inputs = sweep.teardown.get(runtimeId) ?? [];
+        inputs.push({
+          pluginId: plugin.id,
+          enabled: false,
+          capabilityEnabled: false,
+          contributions,
+        });
+        sweep.teardown.set(runtimeId, inputs);
+      }
+    } catch (error) {
+      sweep.unswept.push(name);
+      sweep.warnings.push(
+        `audience plugin "${name}" was not swept from the companion: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return sweep;
+}

package/src/tools/setup/working-repo-cleanup.ts

@@ -18,6 +18,7 @@ const REPORTED_AS: Partial<
 > = {
   "projection-root": { as: "removed", label: ".mate" },
   "git-excludes": { as: "removed", label: "git-excludes" },
+  "openspec-store-pointer": { as: "removed", label: "openspec/config.yaml" },
   "claude-working-settings": { as: "updated", label: "claude-settings" },
   "legacy-tokensave-claude-md": { as: "updated", label: "claude-settings" },
 };
@@ -36,6 +37,7 @@ export async function cleanupWorkingRepository(
       retained.push(entry.id);
       continue;
     }
+    if (entry.retains && !retained.includes(entry.retains)) retained.push(entry.retains);
     if (entry.state !== "removed") continue;
     const reported = REPORTED_AS[entry.id];
     if (!reported) continue;

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

@@ -118,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);

package/src/tools/setup.ts

@@ -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,14 +73,15 @@ 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(),
+  plugins: PluginRegistration[] = getActiveDistribution().registry.baseRegistrations(),
+  wrapped?: { audience: string; registrations: PluginRegistration[] },
 ): Promise<RenderedRuntimeDocuments> {
   const plan = buildSetupInstallationPlan(config, plugins);
   const ctx: SetupContext = {
@@ -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" "$@"