@uniqbit/mate-core 0.15.3 → 0.15.4-canary.10

package/src/tools/setup/capabilities/react-doctor.ts

@@ -1,8 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import type { CapabilityPlugin, SetupContext } from "../plugin";
-import { mergeDir, pruneEmptyAncestors } from "../utils";
+import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
+import { pruneEmptyAncestors } from "../utils";
 
 export const SKILL_SRC = path.join(
   import.meta.dirname,
@@ -13,22 +13,6 @@ export const CLAUDE_HOOK_SRC = path.join(
   "../../../templates/capabilities/react-doctor/claude/hooks/react-doctor.sh",
 );
 
-export async function applyReactDoctorSkills(skillsDir: string): Promise<void> {
-  await mergeDir(SKILL_SRC, skillsDir);
-}
-
-export async function teardownReactDoctorSkills(
-  skillsDir: string,
-  companionPath: string,
-): Promise<void> {
-  try {
-    await fs.rm(skillsDir, { recursive: true, force: true });
-  } catch {
-    /* not present */
-  }
-  await pruneEmptyAncestors(path.dirname(skillsDir), companionPath);
-}
-
 export function createReactDoctorPlugin(): CapabilityPlugin {
   return {
     id: "react-doctor",
@@ -37,6 +21,41 @@ export function createReactDoctorPlugin(): CapabilityPlugin {
     description: "Install React Doctor skills and Claude post-edit scans.",
     defaultSelected: true,
     isEnabled: (config) => (config.capabilities ?? []).some((c) => c.name === "react-doctor"),
+    // Skills, session hooks, and permission pre-seeds are declared and
+    // reconciled by each runtime's Runtime Surface. Only the hook script file
+    // itself is copied imperatively below (script files are not a config
+    // format the surface owns).
+    getRuntimeContributions(ctx: SetupContext): RuntimeContributionsByRuntime {
+      const hookCommand = `sh "${ctx.companionPath}/.claude/hooks/react-doctor.sh"`;
+      const skillTrees = [{ name: "react-doctor", sourceDir: SKILL_SRC }];
+      return {
+        claude: {
+          hookGroups: [
+            // Record edits cheaply, then scan once when the edited turn finishes.
+            {
+              event: "PostToolUse",
+              marker: "react-doctor.sh",
+              group: {
+                matcher: "Write|Edit|MultiEdit|NotebookEdit|ApplyPatch",
+                hooks: [{ type: "command", command: hookCommand, timeout: 5 }],
+              },
+            },
+            {
+              event: "Stop",
+              marker: "react-doctor.sh",
+              group: { hooks: [{ type: "command", command: hookCommand, timeout: 45 }] },
+            },
+          ],
+          permissionEntries: [
+            "Skill(react-doctor)",
+            "Bash(npx react-doctor:*)",
+            "Bash(npx react-doctor@latest *)",
+          ],
+          skillTrees,
+        },
+        opencode: { skillTrees },
+      };
+    },
     async apply(ctx: SetupContext) {
       // Migrate: remove legacy shared .agents/skills/react-doctor/ from previous installs.
       try {
@@ -57,18 +76,12 @@ export function createReactDoctorPlugin(): CapabilityPlugin {
     forProvider: {
       claude: {
         async apply(ctx: SetupContext) {
-          const skillsDir = path.join(ctx.companionPath, ".claude", "skills", "react-doctor");
-          await applyReactDoctorSkills(skillsDir);
           const hookDest = path.join(ctx.companionPath, ".claude", "hooks", "react-doctor.sh");
           await fs.mkdir(path.dirname(hookDest), { recursive: true });
           await fs.copyFile(CLAUDE_HOOK_SRC, hookDest);
           await fs.chmod(hookDest, 0o755);
         },
         async teardown(ctx: SetupContext) {
-          await teardownReactDoctorSkills(
-            path.join(ctx.companionPath, ".claude", "skills", "react-doctor"),
-            ctx.companionPath,
-          );
           try {
             await fs.unlink(path.join(ctx.companionPath, ".claude", "hooks", "react-doctor.sh"));
           } catch {
@@ -80,19 +93,6 @@ export function createReactDoctorPlugin(): CapabilityPlugin {
           );
         },
       },
-      opencode: {
-        async apply(ctx: SetupContext) {
-          await applyReactDoctorSkills(
-            path.join(ctx.companionPath, ".opencode", "skills", "react-doctor"),
-          );
-        },
-        async teardown(ctx: SetupContext) {
-          await teardownReactDoctorSkills(
-            path.join(ctx.companionPath, ".opencode", "skills", "react-doctor"),
-            ctx.companionPath,
-          );
-        },
-      },
     },
   };
 }

package/src/tools/setup/capabilities/rtk.ts

@@ -1,4 +1,4 @@
-import type { CapabilityPlugin, SetupContext } from "../plugin";
+import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
 import type { InstallRequirement } from "../install-contract";
 import { isCommandOnPath, runShellCommand, runShellCommandSilently } from "../utils";
 import { confirm } from "../../../cli/confirm";
@@ -52,6 +52,9 @@ export function createRtkPlugin(deps: RtkDeps = {}): CapabilityPlugin {
     defaultSelected: false,
     isEnabled: (config) =>
       (config.capabilities ?? []).some((capability) => capability.name === "rtk"),
+    getRuntimeContributions(): RuntimeContributionsByRuntime {
+      return { claude: { permissionEntries: ["Bash(rtk:*)"] } };
+    },
     getInstallRequirements: (): InstallRequirement[] => {
       const command = checkBrew() ? RTK_INSTALL_CMD_BREW : RTK_INSTALL_CMD_FALLBACK;
       return [

package/src/tools/setup/capabilities/tokensave-shared.ts

@@ -1 +1,7 @@
 export const TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES = [".tokensave/"];
+
+// Marker that identifies the tokensave installer's CLAUDE.md append block.
+// Declared here (capability-owned) and consumed by the Claude Runtime Surface
+// when reconciling working-repo files at launch.
+export const TOKENSAVE_CLAUDE_MD_MARKER =
+  "## MANDATORY: No Explore Agents When Tokensave Is Available";

package/src/tools/setup/capabilities/tokensave.ts

@@ -3,29 +3,20 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { resolveGitInfoExcludePath } from "../git-utils";
-import type { CapabilityPlugin } from "../plugin";
+import type { CapabilityPlugin, RuntimeContributionsByRuntime } from "../plugin";
 import { isCommandOnPath, resolveCommandOnPath, runCommand, runShellCommand } from "../utils";
+import { TOKENSAVE_CLAUDE_MD_MARKER } from "./tokensave-shared";
 export { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "./tokensave-shared";
 
 export const TOKENSAVE_SUPPORTED_AGENTS = new Set(["claude", "opencode"]);
 export const TOKENSAVE_STORE_DIR = ".tokensave";
 export const TOKENSAVE_MIN_RUST_VERSION = "1.91.0";
-const TOKENSAVE_CLAUDE_MD_MARKER = "## MANDATORY: No Explore Agents When Tokensave Is Available";
 const TOKENSAVE_STORE_EXCLUDE_ENTRY = `${TOKENSAVE_STORE_DIR}/`;
 const TOKENSAVE_BREW_INSTALL_CMD = "brew install aovestdipaperino/tap/tokensave";
 const TOKENSAVE_CARGO_INSTALL_CMD = "cargo install --locked tokensave";
 const TOKENSAVE_SCOOP_INSTALL_CMD =
   "scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket && scoop install tokensave";
 
-interface CompanionOpenCodeSettings {
-  mcp?: Record<string, unknown>;
-  [key: string]: unknown;
-}
-
-function getCompanionOpenCodeConfigPath(companionPath: string): string {
-  return path.join(companionPath, ".opencode", "opencode.json");
-}
-
 export interface TokensaveRunResult {
   ok: boolean;
   stderr: string;
@@ -34,10 +25,14 @@ export interface TokensaveRunResult {
 
 export const tokensaveDeps = {
   run(args: string[], cwd: string): TokensaveRunResult {
+    // env is passed explicitly: bun's spawnSync otherwise resolves the binary
+    // against the process's original PATH, ignoring in-process PATH changes
+    // (which test stubs and shell-integration wrappers rely on).
     const result = spawnSync("tokensave", args, {
       cwd,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
     });
     return {
       ok: result.status === 0 && !result.error,
@@ -58,6 +53,7 @@ export const tokensaveDeps = {
     const result = spawnSync("rustc", ["--version"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
     });
     return {
       ok: result.status === 0 && !result.error,
@@ -73,41 +69,6 @@ export const tokensaveDeps = {
   },
 };
 
-async function readCompanionOpenCodeSettings(
-  companionPath: string,
-): Promise<CompanionOpenCodeSettings> {
-  try {
-    const parsed = JSON.parse(
-      await fs.readFile(getCompanionOpenCodeConfigPath(companionPath), "utf8"),
-    ) as unknown;
-    if (parsed && typeof parsed === "object") {
-      return parsed as CompanionOpenCodeSettings;
-    }
-  } catch {
-    /* absent or malformed */
-  }
-  return {};
-}
-
-async function removeOpenCodeMcpServer(companionPath: string): Promise<void> {
-  const configPath = getCompanionOpenCodeConfigPath(companionPath);
-  const settings = await readCompanionOpenCodeSettings(companionPath);
-  if (!settings.mcp || typeof settings.mcp !== "object") {
-    return;
-  }
-
-  const mcp = { ...settings.mcp };
-  delete mcp.tokensave;
-  if (Object.keys(mcp).length > 0) {
-    settings.mcp = mcp;
-  } else {
-    delete settings.mcp;
-  }
-
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.writeFile(configPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-}
-
 async function cleanupRepoLocalTokensaveArtifacts(repoPath: string): Promise<void> {
   const claudeMdPath = path.join(repoPath, "CLAUDE.md");
   try {
@@ -314,22 +275,55 @@ export function createTokensavePlugin(): CapabilityPlugin {
         },
       ];
     },
+    // MCP access, session hooks, and permission pre-seeds are declared below
+    // and reconciled by each runtime's Runtime Surface. The bare `tokensave`
+    // command name in the MCP entry is resolved against PATH at spawn time by
+    // each provider, so it never pins a since-moved/upgraded binary.
+    getRuntimeContributions(): RuntimeContributionsByRuntime {
+      const mcpServers = [{ name: "tokensave", command: "tokensave", args: ["serve"] }];
+      // Hook commands pin the resolved binary path (hooks run without the
+      // launch environment's PATH guarantees).
+      const tokensaveCommandPath =
+        resolveCommandOnPath("tokensave", process.env.PATH ?? "") ?? "tokensave";
+      const hookGroups = [
+        {
+          event: "PreToolUse",
+          marker: "tokensave",
+          group: {
+            matcher: "Agent|Grep|Bash",
+            hooks: [
+              { type: "command", command: tokensaveCommandPath, args: ["hook-pre-tool-use"] },
+            ],
+          },
+        },
+        {
+          event: "UserPromptSubmit",
+          marker: "tokensave",
+          group: {
+            hooks: [
+              { type: "command", command: tokensaveCommandPath, args: ["hook-prompt-submit"] },
+            ],
+          },
+        },
+        {
+          event: "Stop",
+          marker: "tokensave",
+          group: {
+            hooks: [{ type: "command", command: tokensaveCommandPath, args: ["hook-stop"] }],
+          },
+        },
+      ];
+      return {
+        claude: { mcpServers, hookGroups, permissionEntries: ["mcp__tokensave__*"] },
+        opencode: { mcpServers },
+      };
+    },
     async apply(ctx) {
       // Presence only: make sure the tokensave binary is installed so the graph can be
       // built later. The graph build itself (init/sync) lives in `mate cap index`, never
       // in setup or launch-time sync — keeping launch fast and indexing an explicit step.
       if (ctx.activeProviders.filter((p) => TOKENSAVE_SUPPORTED_AGENTS.has(p)).length === 0) return;
 
-      // MCP access is provider-mediated: every active hosting provider gets the
-      // server in its native config, and teardown bookkeeping removes it again.
-      const tokensaveCommandPath =
-        resolveCommandOnPath("tokensave", process.env.PATH ?? "") ?? "tokensave";
-      await ctx.mcp?.register({
-        name: "tokensave",
-        command: tokensaveCommandPath,
-        args: ["serve"],
-      });
-
       const targetPath = ctx.repoPath ?? ctx.companionPath;
       if (!(await ensureTokensaveInstalled(targetPath))) {
         return;
@@ -342,20 +336,5 @@ export function createTokensavePlugin(): CapabilityPlugin {
       if (!ctx.repoPath) return;
       await teardownDriver(ctx.repoPath, ctx.activeProviders);
     },
-    forProvider: {
-      claude: {
-        async apply(_ctx) {},
-        async teardown(_ctx) {},
-      },
-      opencode: {
-        // Registration goes through ctx.mcp now. Teardown stays as a legacy
-        // prune for entries written by releases that predate the bookkeeping
-        // manifest.
-        async apply(_ctx) {},
-        async teardown(ctx) {
-          await removeOpenCodeMcpServer(ctx.companionPath);
-        },
-      },
-    },
   };
 }

package/src/tools/setup/context-services.ts

@@ -99,6 +99,35 @@ export async function upsertManagedBlock(
   await fs.writeFile(filePath, existing + (existing ? separator : "") + block, "utf8");
 }
 
+/**
+ * Remove every managed block a plugin owns in `filePath`, except blocks whose
+ * key is in `keepKeys`. Used by contribution reconciliation: current sections
+ * are upserted (content-hashed keys), then stale keys are swept here.
+ */
+export async function removeManagedBlocksForPlugin(
+  filePath: string,
+  frameworkName: string,
+  pluginId: string,
+  keepKeys: Set<string> = new Set(),
+): Promise<void> {
+  let existing: string;
+  try {
+    existing = await fs.readFile(filePath, "utf8");
+  } catch {
+    return;
+  }
+  const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const keyPattern = new RegExp(
+    `<!-- ${escape(frameworkName)}:managed:(${escape(pluginId)}:[0-9a-f]+) start -->`,
+    "g",
+  );
+  const keys = [...existing.matchAll(keyPattern)].map((match) => match[1]);
+  for (const key of keys) {
+    if (keepKeys.has(key)) continue;
+    await removeManagedBlock(filePath, frameworkName, key);
+  }
+}
+
 /** Remove a marker-delimited block if present. No-op when file or block is absent. */
 export async function removeManagedBlock(
   filePath: string,

package/src/tools/setup/dynamic-plugins/host.ts

@@ -1,4 +1,5 @@
 import { getActiveDistribution } from "../../../distribution";
+import { FRAMEWORK_NAME } from "../../../framework";
 import { ensureCapabilityEnabled } from "../../../cli/plugin-commands";
 import type { CapabilityPlugin, Plugin } from "../plugin";
 
@@ -43,7 +44,7 @@ export function createPluginHost(): PluginHost {
   return {
     apiVersion: PLUGIN_API_VERSION,
     distribution: {
-      name: distribution.config.name,
+      name: FRAMEWORK_NAME,
       version: distribution.config.version,
     },
     ensureCapabilityEnabled: (name) => ensureCapabilityEnabled(name),

package/src/tools/setup/dynamic-plugins/hydrate.ts

@@ -4,14 +4,13 @@ import path from "node:path";
 import { parse } from "yaml";
 
 import { getActiveDistribution } from "../../../distribution";
-import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
+import { FRAMEWORK_NAME } from "../../../framework";
 import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import type { PluginRegistry } from "../registry";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
-import { PluginPinStore } from "./pin-store";
 
 // Packages already registered in this process; re-hydration (e.g. right after
 // an install inside the same run) only picks up plugins that failed before.
@@ -29,14 +28,6 @@ export interface HydrateDynamicPluginsDeps extends DynamicPluginLoadDeps {
   warn?: (message: string) => void;
 }
 
-function commandName(): string {
-  try {
-    return frameworkCommandName();
-  } catch {
-    return FRAMEWORK_NAME;
-  }
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -107,7 +98,7 @@ function validateDeclaration(entry: unknown): { declaration?: PluginDeclaration;
  */
 export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}): Promise<void> {
   const warn =
-    deps.warn ?? ((message: string) => process.stderr.write(`${commandName()}: ${message}\n`));
+    deps.warn ?? ((message: string) => process.stderr.write(`${FRAMEWORK_NAME}: ${message}\n`));
   try {
     const env = deps.env ?? process.env;
     const companionPath =
@@ -117,7 +108,6 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
     const entries = await readDeclarations(companionPath);
     if (entries.length === 0) return;
 
-    const pins = (await new PluginPinStore(companionPath).load()).plugins;
     const registry = deps.registry ?? getActiveDistribution().registry;
 
     for (const entry of entries) {
@@ -129,7 +119,7 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
       if (hydratedPackages.has(declaration.package)) continue;
 
       // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
-      const result = await loadDynamicPlugin(companionPath, declaration, pins, deps);
+      const result = await loadDynamicPlugin(companionPath, declaration, deps);
       if (!result.ok) {
         warn(result.warning);
         continue;