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

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

@@ -1,88 +1,72 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { getReactDoctorBinPath } from "../../../lib/package-paths";
 import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
-import { removeLegacyOpenCodeSkills } from "../providers/agents-skill-root";
+import { removeLegacyOpenCodeSkills, removeSharedSkills } from "../providers/agents-skill-root";
 import { pruneEmptyAncestors } from "../utils";
 
-const SKILL_NAME = "react-doctor";
+const SKILL_NAME = "mate-react-doctor";
+// The upstream skill earlier releases installed under its own name.
+const LEGACY_SKILL_NAME = "react-doctor";
 
 const SKILL_SRC = path.join(
   import.meta.dirname,
-  "../../../templates/capabilities/react-doctor/skill",
-);
-export const CLAUDE_HOOK_SRC = path.join(
-  import.meta.dirname,
-  "../../../templates/capabilities/react-doctor/claude/hooks/react-doctor.sh",
+  "../../../templates/capabilities/react-doctor/mate-react-doctor",
 );
 
+/** Removes the skill copies earlier releases installed under the upstream name. */
+async function removeLegacySkills(companionPath: string): Promise<void> {
+  const claudeSkillsDir = path.join(companionPath, ".claude", "skills");
+  await fs.rm(path.join(claudeSkillsDir, LEGACY_SKILL_NAME), { recursive: true, force: true });
+  await pruneEmptyAncestors(claudeSkillsDir, companionPath);
+  await removeSharedSkills(companionPath, [LEGACY_SKILL_NAME]);
+  await removeLegacyOpenCodeSkills(companionPath, [LEGACY_SKILL_NAME]);
+}
+
+/** Removes the post-edit hook script earlier releases copied into the companion. */
+async function removeLegacyHookScript(companionPath: string): Promise<void> {
+  const hooksDir = path.join(companionPath, ".claude", "hooks");
+  await fs.rm(path.join(hooksDir, "react-doctor.sh"), { force: true });
+  await pruneEmptyAncestors(hooksDir, companionPath);
+}
+
 export function createReactDoctorPlugin(): CapabilityPlugin {
   return {
     id: "react-doctor",
     kind: "capability",
     label: "React Doctor",
-    description: "Install React Doctor skills and Claude post-edit scans.",
+    description: "Install the mate-react-doctor skill that verifies React changes during apply.",
     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"`;
+    // React Doctor runs only when an agent invokes the skill (the shared Mate
+    // verification rule adds it to OpenSpec task lists), so the capability
+    // contributes no hooks: just the skill and its permission pre-seeds.
+    getRuntimeContributions(): RuntimeContributionsByRuntime {
       const skillTrees = [{ name: SKILL_NAME, 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 *)",
-          ],
+          permissionEntries: [`Skill(${SKILL_NAME})`, `Bash(${getReactDoctorBinPath()}:*)`],
           skillTrees,
         },
         opencode: { skillTrees },
       };
     },
     async apply(ctx: SetupContext) {
-      await removeLegacyOpenCodeSkills(ctx.companionPath, [SKILL_NAME]);
+      await removeLegacySkills(ctx.companionPath);
     },
     async teardown(ctx: SetupContext) {
-      await removeLegacyOpenCodeSkills(ctx.companionPath, [SKILL_NAME]);
+      await removeLegacySkills(ctx.companionPath);
     },
+    // Cleanup only: stale hook groups are stripped by settings-sync through the
+    // `react-doctor.sh` managed marker; the script file itself is removed here.
     forProvider: {
       claude: {
         async apply(ctx: SetupContext) {
-          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);
+          await removeLegacyHookScript(ctx.companionPath);
         },
         async teardown(ctx: SetupContext) {
-          try {
-            await fs.unlink(path.join(ctx.companionPath, ".claude", "hooks", "react-doctor.sh"));
-          } catch {
-            /* not present */
-          }
-          await pruneEmptyAncestors(
-            path.join(ctx.companionPath, ".claude", "hooks"),
-            ctx.companionPath,
-          );
+          await removeLegacyHookScript(ctx.companionPath);
         },
       },
     },

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

@@ -3,7 +3,7 @@ import path from "node:path";
 
 import { getActiveDistribution } from "../../../distribution";
 import { FRAMEWORK_NAME } from "../../../framework";
-import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
+import { CompanionResolver } from "../../../lib/orchestrator/repository-link";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import type { Plugin } from "../plugin";
 import type { PluginRegistry } from "../registry";

package/src/tools/setup/engine.ts

@@ -1,8 +1,8 @@
 // oxlint-disable no-await-in-loop
 import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
-import type { RenderedRuntimeDocument } from "../../lib/orchestrator/projection-types";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
+import type { RenderedRuntimeDocument } from "../../runtime/runtime-document-manifest";
 import { collectHostingProviders, ContextServiceMediator } from "./context-services";
 import type {
   CapabilityContributionInput,
@@ -13,7 +13,7 @@ import type {
 } from "./plugin";
 import { reconcileClaudeContributions } from "./providers/claude";
 import { reconcileOpenCodeContributions } from "./providers/opencode";
-import { renderDocumentsForTarget } from "./runtime-documents";
+import { mergeCompanionOpenCodeConfig, renderDocumentsForTarget } from "./runtime-documents";
 import { normalizeRegistration, type NormalizedRegistration } from "./registry";
 
 export interface SetupInstallationPlanAction {
@@ -252,6 +252,12 @@ async function reconcileCapabilityContributions(
   }
 }
 
+/** What a render returns: its warnings are data for the caller, never printed here. */
+export interface RenderedRuntimeDocuments {
+  documents: RenderedRuntimeDocument[];
+  warnings: string[];
+}
+
 /**
  * The same declarations, rendered rather than written: a working-target pass
  * produces the documents and the Projection Root places them, so no Runtime
@@ -261,7 +267,12 @@ export async function renderRuntimeDocuments(
   ctx: SetupContext,
   registrations: PluginRegistration[],
   plan: SetupInstallationPlan,
-): Promise<RenderedRuntimeDocument[]> {
+): Promise<RenderedRuntimeDocuments> {
   const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
-  return renderDocumentsForTarget(ctx, await collectContributionInputs(ctx, plugins, plan));
+  const documents = renderDocumentsForTarget(
+    ctx,
+    await collectContributionInputs(ctx, plugins, plan),
+  );
+  if (ctx.target !== "working") return { documents, warnings: [] };
+  return mergeCompanionOpenCodeConfig(ctx.companionPath, documents);
 }

package/src/tools/setup/mate.ts

@@ -81,7 +81,7 @@ A \`diff\` section carries a unified diff patch as produced by \`git diff\`. The
 { "id": "changes", "title": "Changes", "type": "diff", "patch": "diff --git a/src/acme.ts b/src/acme.ts\\n..." }
 \`\`\`
 
-A report carrying a mermaid payload inlines the diagram runtime; a report without one does not. Either way the page stays a single self-contained file that makes no network request.
+A report carrying a mermaid payload loads the pinned, integrity-checked diagram runtime from a CDN; a report without one does not. Offline, each diagram stays readable as its source. Otherwise the page stays a single self-contained file.
 
 ## Invocation
 

package/src/tools/setup/providers/claude-format.ts

@@ -1,6 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { hookGroupKey, type ClaudeHookGroup } from "../../../runtime/claude-hook-group";
+
 // Structurally matches `McpServerDescriptor` from ../plugin; declared here so
 // the format module stays dependency-free of the plugin contract (which
 // imports hook types from this module).
@@ -17,17 +19,11 @@ export interface McpEntryDescriptor {
 // groups are Mate-managed lives here too, because the companion-side reconcile
 // and the working-repo projection entry must strip the same set.
 
-export interface ClaudeHookCommand {
-  type?: string;
-  command?: string;
-  args?: string[];
-  timeout?: number;
-}
-
-export interface ClaudeHookGroup {
-  matcher?: string;
-  hooks?: ClaudeHookCommand[];
-}
+export {
+  hookGroupKey,
+  type ClaudeHookCommand,
+  type ClaudeHookGroup,
+} from "../../../runtime/claude-hook-group";
 
 export type ClaudeHookMap = Record<string, ClaudeHookGroup[]>;
 
@@ -43,10 +39,6 @@ export interface ClaudeMcpConfig {
   [key: string]: unknown;
 }
 
-function hookGroupKey(group: ClaudeHookGroup): string {
-  return JSON.stringify(group);
-}
-
 /** Append incoming hook groups per event, skipping structurally identical ones. */
 export function mergeClaudeHookGroups(
   existingHooks: ClaudeHookMap,
@@ -84,9 +76,10 @@ export function filterClaudeHookGroups(
 
 // Command substrings that mark a hook group as Mate-managed. The mate plugin
 // hooks (validate-artifact-path, mate-session-banner) now ship in the bundled
-// Claude plugin, and the retired mate-artifact-finish.sh archive hook is gone
-// entirely; their markers are retained migration-only so stale managed groups
-// written by earlier releases keep being stripped, and are never re-added.
+// Claude plugin, and the retired mate-artifact-finish.sh archive hook and
+// react-doctor.sh post-edit scan are gone entirely; their markers are retained
+// migration-only so stale managed groups written by earlier releases keep being
+// stripped, and are never re-added.
 const MANAGED_HOOK_MARKERS = [
   "validate-artifact-path",
   "mate-session-banner",

package/src/tools/setup/providers/claude-plugin-hooks.ts

@@ -3,7 +3,8 @@ import path from "node:path";
 
 import { PROJECTED_BANNER_FLAG } from "../../../hooks/session-banner";
 import { getClaudePluginRoot } from "../../../lib/package-paths";
-import type { ClaudeHookGroup } from "./claude-format";
+import { runtimeClaudePluginRoot } from "../../../runtime/runtime-directory";
+import { hookGroupKey, type ClaudeHookGroup } from "./claude-format";
 
 /**
  * The bundled Claude plugin's hook wiring, read as a value. A managed launch
@@ -17,11 +18,16 @@ import type { ClaudeHookGroup } from "./claude-format";
  * environment is present and so cannot double the prompt the launch already
  * appended; and the banner, whose carried copy is marked so it defers to the
  * launch's.
+ *
+ * The wiring is read from the installed plugin, but every command names
+ * `<mate home>/runtime/claude-plugin`, so a reinstall or Node switch does not
+ * strand a wrapped repository.
  */
 
 const GUARD_HOOK_SHIM = "validate-artifact-path.mjs";
 const GUIDANCE_HOOK_SHIM = "session-guidance.mjs";
 const BANNER_HOOK_SHIM = "session-banner.mjs";
+const PREPARE_HOOK_SHIM = "session-prepare.mjs";
 const PLUGIN_ROOT_TOKEN = "${CLAUDE_PLUGIN_ROOT}";
 
 interface PluginHookWiring {
@@ -50,26 +56,24 @@ function resolveCommands(group: ClaudeHookGroup, pluginRoot: string): ClaudeHook
   };
 }
 
-function runsShim(shim: string): (group: ClaudeHookGroup) => boolean {
-  return (group) => (group.hooks ?? []).some((hook) => (hook.command ?? "").includes(shim));
+function runsShim(group: ClaudeHookGroup, shim: string): boolean {
+  return (group.hooks ?? []).some((hook) => (hook.command ?? "").includes(shim));
 }
 
-function groupsFor(
-  event: string,
-  shim: string,
-  pluginRoot: string = getClaudePluginRoot(),
-): ClaudeHookGroup[] {
-  return (readPluginHookWiring(pluginRoot).hooks?.[event] ?? [])
-    .filter(runsShim(shim))
-    .map((group) => resolveCommands(group, pluginRoot));
+function groupsFor(event: string, shim: string, commandRoot: string): ClaudeHookGroup[] {
+  return (readPluginHookWiring(getClaudePluginRoot()).hooks?.[event] ?? []).flatMap((group) =>
+    runsShim(group, shim) ? [resolveCommands(group, commandRoot)] : [],
+  );
 }
 
 /**
  * The guard's `PreToolUse` groups with `${CLAUDE_PLUGIN_ROOT}` resolved against
- * the running installation, so the command works with no launch environment.
+ * the runtime link, so the command works with no launch environment.
  */
-export function mateGuardHookGroups(pluginRoot: string = getClaudePluginRoot()): ClaudeHookGroup[] {
-  return groupsFor("PreToolUse", GUARD_HOOK_SHIM, pluginRoot);
+export function mateGuardHookGroups(
+  commandRoot: string = runtimeClaudePluginRoot(),
+): ClaudeHookGroup[] {
+  return groupsFor("PreToolUse", GUARD_HOOK_SHIM, commandRoot);
 }
 
 /**
@@ -79,9 +83,9 @@ export function mateGuardHookGroups(pluginRoot: string = getClaudePluginRoot()):
  * flag.
  */
 export function mateGuidanceHookGroups(
-  pluginRoot: string = getClaudePluginRoot(),
+  commandRoot: string = runtimeClaudePluginRoot(),
 ): ClaudeHookGroup[] {
-  return groupsFor("SessionStart", GUIDANCE_HOOK_SHIM, pluginRoot);
+  return groupsFor("SessionStart", GUIDANCE_HOOK_SHIM, commandRoot);
 }
 
 /**
@@ -91,9 +95,9 @@ export function mateGuidanceHookGroups(
  * would print the banner twice.
  */
 export function mateBannerHookGroups(
-  pluginRoot: string = getClaudePluginRoot(),
+  commandRoot: string = runtimeClaudePluginRoot(),
 ): ClaudeHookGroup[] {
-  return groupsFor("SessionStart", BANNER_HOOK_SHIM, pluginRoot).map((group) => ({
+  return groupsFor("SessionStart", BANNER_HOOK_SHIM, commandRoot).map((group) => ({
     ...group,
     hooks: (group.hooks ?? []).map((hook) => ({
       ...hook,
@@ -102,16 +106,49 @@ export function mateBannerHookGroups(
   }));
 }
 
+/**
+ * The session-prepare `SessionStart` group, resolved the same way. Its declared
+ * `timeout` sits above the shim's own bound, so Claude Code never kills a
+ * prepare the shim has not given up on. Inert under a launch environment.
+ */
+export function mateSessionPrepareHookGroups(
+  commandRoot: string = runtimeClaudePluginRoot(),
+): ClaudeHookGroup[] {
+  return groupsFor("SessionStart", PREPARE_HOOK_SHIM, commandRoot);
+}
+
+function mateOwnHookGroups(commandRoot: string): ClaudeHookGroup[] {
+  return [
+    ...mateGuardHookGroups(commandRoot),
+    ...mateGuidanceHookGroups(commandRoot),
+    ...mateBannerHookGroups(commandRoot),
+    ...mateSessionPrepareHookGroups(commandRoot),
+  ];
+}
+
+const ownGroupKeys = new Map<string, ReadonlySet<string>>();
+
+/** Memoized per plugin-root pair; hooks are short-lived, so a refresh mid-process is not tracked. */
+function mateOwnHookGroupKeys(runtimeRoot: string, installRoot: string): ReadonlySet<string> {
+  const memoKey = `${runtimeRoot}\0${installRoot}`;
+  let keys = ownGroupKeys.get(memoKey);
+  if (!keys) {
+    keys = new Set(
+      [...mateOwnHookGroups(runtimeRoot), ...mateOwnHookGroups(installRoot)].map(hookGroupKey),
+    );
+    ownGroupKeys.set(memoKey, keys);
+  }
+  return keys;
+}
+
 /**
  * Whether a hook group is one the working target placed. It matches a managed
  * marker, so the entry that strips managed groups from a Working Repository has
- * to be told to leave these alone.
+ * to be told to leave these alone. Both the runtime-link form and the
+ * install-path form an older release wrote are recognized.
  */
 export function isMateGuardHookGroup(group: ClaudeHookGroup): boolean {
-  const own = new Set(
-    [...mateGuardHookGroups(), ...mateGuidanceHookGroups(), ...mateBannerHookGroups()].map(
-      (candidate) => JSON.stringify(candidate),
-    ),
+  return mateOwnHookGroupKeys(runtimeClaudePluginRoot(), getClaudePluginRoot()).has(
+    hookGroupKey(group),
   );
-  return own.has(JSON.stringify(group));
 }

package/src/tools/setup/providers/claude.ts

@@ -89,6 +89,10 @@ function getBaseManagedPermissionEntries(companionPath: string): string[] {
 const LEGACY_MANAGED_PERMISSION_ENTRIES = [
   "Bash($MATE_COMPANION_BIN_PATH/openspec:*)",
   "Bash($MATE_COMPANION_BIN_PATH/graphify:*)",
+  // React Doctor's pre-seeds before it moved to the pinned mate-react-doctor skill.
+  "Skill(react-doctor)",
+  "Bash(npx react-doctor:*)",
+  "Bash(npx react-doctor@latest *)",
 ];
 
 function getAllManagedPermissionEntries(companionPath: string): Set<string> {
@@ -102,16 +106,12 @@ function getAllManagedPermissionEntries(companionPath: string): Set<string> {
   ]);
 }
 
-// Resolved path of the companion-owned Claude settings document. This is the
-// single source of truth for Mate-managed Claude hooks, permissions, and MCP
-// servers; it is loaded at launch via `claude --settings`.
+/** Companion-owned Claude settings: sole source of Mate-managed hooks, permissions and MCP servers. */
 export function getCompanionClaudeSettingsPath(companionPath: string): string {
   return path.join(companionPath, ".claude", "settings.local.json");
 }
 
-// Resolved path of the companion-owned `.mcp.json`. Mate writes Mate-managed
-// MCP servers here and loads it at launch via `claude --mcp-config`, keeping
-// the MCP surface out of the working repo and out of settings.local.json.
+/** Companion-owned `.mcp.json`; loaded via `--mcp-config` only by a companion-scoped launch. */
 export function getCompanionClaudeMcpConfigPath(companionPath: string): string {
   return path.join(companionPath, ".mcp.json");
 }
@@ -147,6 +147,23 @@ export function renderManagedClaudeMcpServers(
   return servers;
 }
 
+/**
+ * Enabled Capabilities' Claude hook groups per event, in declared order, as a
+ * value: what a Claude wrap carries into the Working Repository.
+ */
+export function renderManagedClaudeHookGroups(
+  contributions: CapabilityContributionInput[] = [],
+): Record<string, ClaudeHookGroup[]> {
+  const hooks: Record<string, ClaudeHookGroup[]> = {};
+  for (const input of contributions) {
+    if (!input.enabled) continue;
+    for (const hook of input.contributions.hookGroups ?? []) {
+      (hooks[hook.event] ??= []).push(hook.group);
+    }
+  }
+  return hooks;
+}
+
 // Reconcile the Mate-managed Claude settings shape (hooks, permissions, MCP
 // servers) on top of whatever already exists in the settings document. Managed
 // groups/entries always lead their arrays so the emitted shape stays stable