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

package/src/tools/setup/plugin.ts

@@ -1,5 +1,6 @@
 import type { FrameworkConfig, LinkedRepository } from "../../lib/orchestrator/types";
 import type { InstallRequirement, InstallRequirementContext } from "./install-contract";
+import type { ClaudeHookGroup } from "./providers/claude-format";
 
 export interface SetupContext {
   companionPath: string;
@@ -112,9 +113,89 @@ export type PluginPolicy = "required" | "default" | "optional";
  */
 export type PluginRegistration = Plugin | { plugin: Plugin; policy: PluginPolicy };
 
+/**
+ * A hook group a Capability contributes to a runtime's settings. `marker` is
+ * the command substring that identifies the group as Mate-managed (D4 marker
+ * scheme): reconciliation strips every group whose command contains any
+ * declared marker before re-adding the groups of enabled Capabilities.
+ */
+export interface HookGroupContribution {
+  event: string;
+  marker: string;
+  group: ClaudeHookGroup;
+}
+
+/** A skill directory copied into `<runtime dir>/skills/<name>`. */
+export interface SkillTreeContribution {
+  name: string;
+  sourceDir: string;
+}
+
+/**
+ * A managed guidance section in the runtime's agent instruction file
+ * (CLAUDE.md / AGENTS.md). Reconciled as a framework-managed block; on
+ * teardown a section in a file shared with another active runtime is only
+ * stripped together with the last runtime using that file.
+ */
+export interface GuidanceSectionContribution {
+  content: string;
+}
+
+/**
+ * A plugin reference entry in the runtime's config (OpenCode `plugin` array).
+ * `isManagedReference` identifies entries this contribution owns so stale
+ * variants (e.g. older pins) are replaced and teardown removes only them.
+ */
+export interface PluginReferenceContribution {
+  reference: string;
+  isManagedReference(entry: unknown): boolean;
+  /** Config files to reconcile, relative to the runtime dir. Defaults to both OpenCode configs. */
+  configFiles?: string[];
+}
+
+/**
+ * Declarative Agent Runtime contributions of one Capability for one runtime.
+ * The runtime's Runtime Surface reconciles these symmetrically: applied while
+ * the Capability is enabled, removed when it is not, idempotent across runs.
+ */
+export interface RuntimeContributions {
+  mcpServers?: McpServerDescriptor[];
+  hookGroups?: HookGroupContribution[];
+  permissionEntries?: string[];
+  guidanceSections?: GuidanceSectionContribution[];
+  skillTrees?: SkillTreeContribution[];
+  pluginReferences?: PluginReferenceContribution[];
+}
+
+/**
+ * Contributions keyed by runtime id ("claude", "opencode"). Keyed-by-runtime
+ * because the payload shapes are runtime-specific (hook groups are
+ * Claude-shaped, plugin references OpenCode-shaped); a runtime-agnostic
+ * declaration would only push translation into every capability.
+ */
+export type RuntimeContributionsByRuntime = Partial<Record<string, RuntimeContributions>>;
+
+/**
+ * One Capability's contributions for one runtime, as handed to that runtime's
+ * Runtime Surface reconciliation. Disabled Capabilities participate too: their
+ * declarations define the managed entries to strip.
+ */
+export interface CapabilityContributionInput {
+  pluginId: string;
+  enabled: boolean;
+  contributions: RuntimeContributions;
+}
+
 export interface CapabilityPlugin extends Plugin {
   kind: "capability";
   requires?: { packageManagers: string[] };
+  /**
+   * Declare Agent Runtime contributions as data. Called on every setup/sync
+   * pass for all registered Capabilities — enabled ones contribute their
+   * entries, disabled ones only widen the managed strip set so their previous
+   * entries are removed.
+   */
+  getRuntimeContributions?(ctx: SetupContext): RuntimeContributionsByRuntime;
   forProvider?: Record<
     string,
     {

package/src/tools/setup/plugins/gitignore.ts

@@ -1,6 +1,9 @@
 import { getActiveDistribution } from "../../../distribution";
 import { FRAMEWORK_NAME } from "../../../framework";
-import { PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY } from "../dynamic-plugins/paths";
+import {
+  PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY,
+  PLUGIN_WORKSPACE_NPMRC_GITIGNORE_ENTRY,
+} from "../dynamic-plugins/paths";
 import type { Plugin, SetupContext } from "../plugin";
 
 const MANAGED_START = (name: string) => `# ${name} managed: start`;
@@ -58,22 +61,29 @@ export async function writeManagedGitignoreBlock(
 
 export function collectManagedGitignoreEntries(ctx: SetupContext, plugins: Plugin[]): string[] {
   // Baseline for every companion: node_modules never versions wherever a tool
-  // materializes it, and everything under the dependencies tree (dynamic
-  // plugins, context-mode, future consumers) is regenerated by setup/install —
-  // version pins live in .mate/config and in code, never in the tree itself.
+  // materializes it, and the machine-local distribution-dependencies workspace
+  // (.mate/plugins/.local/ — context-mode, future consumers) is regenerated by
+  // setup/install in full — version pins live in .mate/config and in code,
+  // never in the tree itself. This is distinct from the committed dynamic-
+  // plugins workspace at .mate/plugins/, whose package.json and lockfile stay
+  // trackable.
   const entries = [
     "node_modules/",
-    `.${FRAMEWORK_NAME}/dependencies/`,
+    `.${FRAMEWORK_NAME}/plugins/.local/`,
     ".mcp.json*",
     ...plugins
       .filter((p) => p.kind !== "root" && (p.isEnabled(ctx.config) || p.persistGitignoreEntries))
       .flatMap((p) => p.gitignoreEntries?.(ctx) ?? []),
   ];
-  // Dynamic-plugin loading artifacts: the local override file never versions;
-  // the pin file (plugins.lock.yaml) stays committed and is deliberately not
-  // listed here.
+  // Dynamic-plugin loading artifacts: the local override file and the shared
+  // workspace's local registry credentials never version. The workspace's
+  // installed tree (node_modules) is already covered by the baseline
+  // node_modules/ rule above, since the workspace lives outside the
+  // dependencies tree wildcard; its package.json and committed
+  // package-lock.json are the pin/reproducibility record and are never
+  // touched by any ignore rule.
   if (ctx.config.plugins?.length) {
-    entries.push(PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY);
+    entries.push(PLUGIN_WORKSPACE_NPMRC_GITIGNORE_ENTRY, PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY);
   }
   return entries;
 }

package/src/tools/setup/plugins/guidance.ts

@@ -1,8 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { FRAMEWORK_NAME, frameworkConfig } from "../../../framework";
-import { removeGraphifySection } from "../capabilities/graphify";
+import { FRAMEWORK_NAME } from "../../../framework";
+import { removeGraphifySection } from "../capabilities/graphify-shared";
 
 // Marker names derive from the framework identity, never the invocation name.
 const upperName = () => FRAMEWORK_NAME.toUpperCase();
@@ -12,9 +12,6 @@ function allMateStarts(): string[] {
     `<!-- ${upperName()}:COMPANION:START -->`,
     "<!-- COMPANION:GUIDANCE:START -->",
     `<!-- ${upperName()}:COMPANION:GUIDANCE:START -->`,
-    ...frameworkConfig.legacyNames.map(
-      (n) => `<!-- ${n.toUpperCase()}:COMPANION:GUIDANCE:START -->`,
-    ),
     `<!-- ${upperName()}:GRAPHIFY:START -->`,
   ];
 }
@@ -24,7 +21,6 @@ function allMateEnds(): string[] {
     `<!-- ${upperName()}:COMPANION:END -->`,
     "<!-- COMPANION:GUIDANCE:END -->",
     `<!-- ${upperName()}:COMPANION:GUIDANCE:END -->`,
-    ...frameworkConfig.legacyNames.map((n) => `<!-- ${n.toUpperCase()}:COMPANION:GUIDANCE:END -->`),
     `<!-- ${upperName()}:GRAPHIFY:END -->`,
   ];
 }

package/src/tools/setup/policy.ts

@@ -57,10 +57,7 @@ export interface RequiredPluginDrift {
 export function getRequiredPluginDrift(config: FrameworkConfig): RequiredPluginDrift[] {
   const drift: RequiredPluginDrift[] = [];
   for (const { plugin } of requiredPluginsByKind()) {
-    if (
-      plugin.kind === "provider" &&
-      !(config.profiles.default?.allowedAgents ?? []).includes(plugin.id)
-    ) {
+    if (plugin.kind === "provider" && !(config.allowedAgents ?? []).includes(plugin.id)) {
       drift.push({
         pluginId: plugin.id,
         kind: plugin.kind,
@@ -96,9 +93,9 @@ export function getRequiredPluginDrift(config: FrameworkConfig): RequiredPluginD
 export function applyRequiredSelectionsToConfig(config: FrameworkConfig): void {
   for (const { plugin } of requiredPluginsByKind()) {
     if (plugin.kind === "provider") {
-      const profile = config.profiles.default;
-      if (profile && !profile.allowedAgents.includes(plugin.id)) {
-        profile.allowedAgents.push(plugin.id);
+      const allowedAgents = config.allowedAgents ?? [];
+      if (!allowedAgents.includes(plugin.id)) {
+        config.allowedAgents = [...allowedAgents, plugin.id];
       }
     }
     if (plugin.kind === "packageManager") {

package/src/tools/setup/providers/agent-file-sections.ts

@@ -0,0 +1,78 @@
+// Shared markdown section primitives for agent instruction files (CLAUDE.md,
+// AGENTS.md), plus a thin file-level wrapper for stripping sections in place.
+
+import fs from "node:fs/promises";
+
+export interface RemoveHeadingSectionOptions {
+  /** Matches the heading line that opens the section to remove. */
+  isHeading(line: string): boolean;
+  /** Exact lines (e.g. HTML comment markers) stripped wherever they appear. */
+  markerLines?: string[];
+}
+
+/**
+ * Remove a heading-delimited section (heading line up to the next `#`/`##`
+ * heading or EOF), collapsing leftover blank runs. Marker lines are stripped
+ * even when no section heading is present.
+ */
+export function removeHeadingSection(
+  content: string,
+  options: RemoveHeadingSectionOptions,
+): string {
+  const markerLines = new Set(options.markerLines ?? []);
+  const normalizedLines = content.split("\n").filter((line) => !markerLines.has(line));
+
+  const start = normalizedLines.findIndex(options.isHeading);
+  if (start === -1) {
+    const strippedMarkersOnly = normalizedLines.join("\n");
+    return strippedMarkersOnly === content ? content : strippedMarkersOnly;
+  }
+
+  let end = normalizedLines.length;
+  for (let i = start + 1; i < normalizedLines.length; i++) {
+    if (normalizedLines[i].startsWith("## ") || normalizedLines[i].startsWith("# ")) {
+      end = i;
+      break;
+    }
+  }
+
+  const remaining = [...normalizedLines.slice(0, start), ...normalizedLines.slice(end)].join("\n");
+  const collapsed = remaining.replace(/\n{3,}/g, "\n\n").trim();
+  return collapsed ? collapsed + "\n" : "";
+}
+
+/**
+ * Cut everything from `marker` to EOF. Returns the content unchanged when the
+ * marker is absent, and "" when nothing but whitespace precedes it (callers
+ * typically delete the file then).
+ */
+export function cutFromMarker(content: string, marker: string): string {
+  const idx = content.indexOf(marker);
+  if (idx === -1) return content;
+
+  const before = content.slice(0, idx).replace(/\s+$/, "");
+  return before.length > 0 ? before + "\n" : "";
+}
+
+/**
+ * Strip a heading-delimited section from a file in place. Absent files are a
+ * no-op; a file left without content is deleted.
+ */
+export async function stripSectionFromFile(
+  filePath: string,
+  options: RemoveHeadingSectionOptions,
+): Promise<void> {
+  let content: string;
+  try {
+    content = await fs.readFile(filePath, "utf8");
+  } catch {
+    return;
+  }
+  const stripped = removeHeadingSection(content, options);
+  if (stripped === content) return;
+  if (!stripped.trim()) {
+    await fs.unlink(filePath);
+  } else {
+    await fs.writeFile(filePath, stripped, "utf8");
+  }
+}

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

@@ -0,0 +1,159 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// 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).
+export interface McpEntryDescriptor {
+  name: string;
+  command?: string;
+  args?: string[];
+  url?: string;
+  env?: Record<string, string>;
+}
+
+// Claude runtime config format primitives: parse/merge/serialize for
+// `settings.local.json` (hook maps, permissions) and `.mcp.json`. This module
+// owns the file formats only — which entries are Mate-managed is the callers'
+// (Runtime Surface) knowledge.
+
+export interface ClaudeHookCommand {
+  type?: string;
+  command?: string;
+  args?: string[];
+  timeout?: number;
+}
+
+export interface ClaudeHookGroup {
+  matcher?: string;
+  hooks?: ClaudeHookCommand[];
+}
+
+export type ClaudeHookMap = Record<string, ClaudeHookGroup[]>;
+
+export interface ClaudeSettings {
+  hooks?: ClaudeHookMap;
+  permissions?: { additionalDirectories?: string[]; allow?: string[] } & Record<string, unknown>;
+  mcpServers?: Record<string, { command?: string; args?: string[] }>;
+  [key: string]: unknown;
+}
+
+export interface ClaudeMcpConfig {
+  mcpServers?: Record<string, unknown>;
+  [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,
+  incomingHooks: ClaudeHookMap,
+): ClaudeHookMap {
+  const merged: ClaudeHookMap = { ...existingHooks };
+  for (const [event, groups] of Object.entries(incomingHooks)) {
+    const current = merged[event] ?? [];
+    const seen = new Set(current.map(hookGroupKey));
+    merged[event] = [...current];
+    for (const group of groups ?? []) {
+      const key = hookGroupKey(group);
+      if (seen.has(key)) continue;
+      merged[event].push(group);
+      seen.add(key);
+    }
+  }
+  return merged;
+}
+
+/** Keep only groups matching `keep`; events left empty are dropped. */
+export function filterClaudeHookGroups(
+  hooks: ClaudeHookMap,
+  keep: (group: ClaudeHookGroup) => boolean,
+): ClaudeHookMap {
+  const filtered: ClaudeHookMap = {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    const remaining = (groups ?? []).filter(keep);
+    if (remaining.length > 0) {
+      filtered[event] = remaining;
+    }
+  }
+  return filtered;
+}
+
+/** Tolerant read: absent or malformed settings read as an empty object. */
+export async function readClaudeSettings(settingsPath: string): Promise<ClaudeSettings> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(settingsPath, "utf8")) as unknown;
+    if (parsed && typeof parsed === "object") {
+      return parsed as ClaudeSettings;
+    }
+  } catch {
+    // Absent or unparseable — start from an empty object.
+  }
+  return {};
+}
+
+export async function writeClaudeSettings(
+  settingsPath: string,
+  settings: ClaudeSettings,
+): Promise<void> {
+  await fs.mkdir(path.dirname(settingsPath), { recursive: true });
+  await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+}
+
+/** Tolerant read of `.mcp.json`; `present` distinguishes absent from empty. */
+export async function readClaudeMcpConfig(
+  mcpConfigPath: string,
+): Promise<{ present: boolean; config: ClaudeMcpConfig }> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(mcpConfigPath, "utf8")) as unknown;
+    if (parsed && typeof parsed === "object") {
+      return { present: true, config: parsed as ClaudeMcpConfig };
+    }
+  } catch {
+    // Absent or unparseable — start from an empty object.
+  }
+  return { present: false, config: {} };
+}
+
+export async function writeClaudeMcpConfig(
+  mcpConfigPath: string,
+  config: ClaudeMcpConfig,
+): Promise<void> {
+  await fs.writeFile(mcpConfigPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+/** Map a provider-agnostic MCP descriptor to Claude's `.mcp.json` entry shape. */
+export function toClaudeMcpEntry(descriptor: McpEntryDescriptor): Record<string, unknown> {
+  if (descriptor.url) return { url: descriptor.url };
+  return {
+    command: descriptor.command,
+    ...(descriptor.args ? { args: descriptor.args } : {}),
+    ...(descriptor.env ? { env: descriptor.env } : {}),
+  };
+}
+
+/**
+ * Reconcile a single server entry in `.mcp.json` while preserving every
+ * unrelated key. `entry: null` removes the server; removal never creates the
+ * file.
+ */
+export async function updateClaudeMcpServer(
+  mcpConfigPath: string,
+  name: string,
+  entry: Record<string, unknown> | null,
+): Promise<void> {
+  const { present, config } = await readClaudeMcpConfig(mcpConfigPath);
+  if (entry === null && !present) return;
+
+  const mcpServers: Record<string, unknown> = { ...config.mcpServers };
+  if (entry === null) {
+    if (!(name in mcpServers)) return;
+    delete mcpServers[name];
+  } else {
+    mcpServers[name] = entry;
+  }
+  await writeClaudeMcpConfig(mcpConfigPath, { ...config, mcpServers });
+}