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

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

@@ -0,0 +1,146 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { McpEntryDescriptor } from "./claude-format";
+
+// OpenCode runtime config format primitives: parse/serialize for
+// `opencode.json`/`tui.json`, plugin-reference array handling, and MCP entry
+// shapes. This module owns the file formats only — which entries are
+// Mate-managed is the callers' (Runtime Surface) knowledge.
+
+export type OpenCodeConfig = Record<string, unknown>;
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Tolerant read; `present` distinguishes absent/malformed from empty. */
+export async function readOpenCodeConfig(
+  configPath: string,
+): Promise<{ present: boolean; config: OpenCodeConfig }> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(configPath, "utf8")) as unknown;
+    if (isRecord(parsed)) {
+      return { present: true, config: parsed };
+    }
+  } catch {
+    // Absent or unparseable — start from an empty object.
+  }
+  return { present: false, config: {} };
+}
+
+export async function writeOpenCodeConfig(
+  configPath: string,
+  config: OpenCodeConfig,
+): Promise<void> {
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+export function getOpenCodePluginReferences(config: OpenCodeConfig): unknown[] {
+  return Array.isArray(config.plugin) ? config.plugin : [];
+}
+
+/** Replace the plugin array in place; an empty list removes the key. */
+export function setOpenCodePluginReferences(config: OpenCodeConfig, references: unknown[]): void {
+  if (references.length === 0) {
+    delete config.plugin;
+    return;
+  }
+  config.plugin = references;
+}
+
+function mergeConfig(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const [key, sourceValue] of Object.entries(source)) {
+    const targetValue = target[key];
+    if (isRecord(targetValue) && isRecord(sourceValue)) {
+      mergeConfig(targetValue, sourceValue);
+      continue;
+    }
+
+    target[key] = sourceValue;
+  }
+}
+
+/**
+ * Merge an overlay into the launch-time `OPENCODE_CONFIG_CONTENT` env value
+ * (overlay wins on scalar conflicts) and return the serialized result. Invalid
+ * inherited content is ignored rather than breaking the launch.
+ */
+export function mergeOpenCodeConfigContent(
+  overlay: Record<string, unknown>,
+  env: NodeJS.ProcessEnv = process.env,
+  options: { appendSkillPaths?: string[] } = {},
+): string {
+  let config: Record<string, unknown> = {};
+  const existing = env.OPENCODE_CONFIG_CONTENT;
+
+  if (existing) {
+    try {
+      const parsed = JSON.parse(existing) as unknown;
+      if (isRecord(parsed)) {
+        config = parsed;
+      }
+    } catch {
+      // Ignore invalid inherited config content rather than breaking launch.
+    }
+  }
+
+  mergeConfig(config, overlay);
+
+  if (options.appendSkillPaths && options.appendSkillPaths.length > 0) {
+    const skills = isRecord(config.skills) ? config.skills : {};
+    const paths = Array.isArray(skills.paths) ? skills.paths : [];
+    const existingPaths = new Set(paths);
+    skills.paths = [
+      ...paths,
+      ...options.appendSkillPaths.filter((skillPath) => !existingPaths.has(skillPath)),
+    ];
+    config.skills = skills;
+  }
+
+  return JSON.stringify(config);
+}
+
+/** Map a provider-agnostic MCP descriptor to OpenCode's `mcp` entry shape. */
+export function toOpenCodeMcpEntry(descriptor: McpEntryDescriptor): Record<string, unknown> {
+  if (descriptor.url) {
+    return { type: "remote", url: descriptor.url, enabled: true };
+  }
+  return {
+    type: "local",
+    command: [descriptor.command ?? "", ...(descriptor.args ?? [])].filter(Boolean),
+    ...(descriptor.env ? { environment: descriptor.env } : {}),
+    enabled: true,
+  };
+}
+
+/**
+ * Reconcile a single server entry in the `mcp` map while preserving every
+ * unrelated key. `entry: null` removes the server; removal never creates the
+ * file, and an emptied `mcp` map is dropped entirely.
+ */
+export async function updateOpenCodeMcpServer(
+  configPath: string,
+  name: string,
+  entry: Record<string, unknown> | null,
+): Promise<void> {
+  const { present, config } = await readOpenCodeConfig(configPath);
+  if (entry === null && !present) return;
+
+  const mcp: Record<string, unknown> = isRecord(config.mcp) ? { ...config.mcp } : {};
+  if (entry === null) {
+    if (!(name in mcp)) return;
+    delete mcp[name];
+  } else {
+    mcp[name] = entry;
+  }
+
+  const next = { ...config };
+  if (Object.keys(mcp).length > 0) {
+    next.mcp = mcp;
+  } else {
+    delete next.mcp;
+  }
+  await writeOpenCodeConfig(configPath, next);
+}

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

@@ -2,7 +2,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { frameworkCommandName } from "../../../framework";
+import { FRAMEWORK_NAME } from "../../../framework";
 import {
   OPENCODE_PLUGIN_PACKAGE_NAME,
   getOpenCodePluginPackageReference,
@@ -10,15 +10,31 @@ import {
   warmOpenCodePluginCache,
 } from "../../../lib/opencode-plugin-package";
 import { refreshFromTemplate, stripGuidanceBlock } from "../plugins/guidance";
-import type { McpServerDescriptor, ProviderPlugin, SetupContext } from "../plugin";
-import { pruneEmptyAncestors } from "../utils";
+import { stripSectionFromFile, type RemoveHeadingSectionOptions } from "./agent-file-sections";
+import { patchSkillTreeMarkdownFiles } from "./skill-tree";
+import {
+  instructionBlockKey,
+  removeManagedBlocksForPlugin,
+  upsertManagedBlock,
+} from "../context-services";
+import type { CapabilityContributionInput, ProviderPlugin, SetupContext } from "../plugin";
+import { mergeDir, pruneEmptyAncestors } from "../utils";
+import {
+  getOpenCodePluginReferences,
+  isRecord,
+  readOpenCodeConfig,
+  setOpenCodePluginReferences,
+  toOpenCodeMcpEntry,
+  updateOpenCodeMcpServer,
+  writeOpenCodeConfig,
+  type OpenCodeConfig,
+} from "./opencode-format";
 import { getSetupProvidersRoot, getSetupRootTemplates } from "./utils";
 
 // Copied Mate plugin source files from earlier releases. Plugin code is
 // package-owned now; these exact filenames are removed during sync and
 // teardown while every other companion-local plugin is preserved.
 const LEGACY_PLUGIN_FILES = [
-  "kizuna-companion.ts",
   "add-dir.ts",
   "companion.ts",
   "small-model.ts",
@@ -47,10 +63,6 @@ const LEGACY_TUI_DEPENDENCIES = {
   "@opentui/solid": "^0.3.4",
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function mergeConfigDefaults(
   target: Record<string, unknown>,
   defaults: Record<string, unknown>,
@@ -101,25 +113,20 @@ function isLegacyMatePluginConfigEntry(entry: unknown): boolean {
  * references) with the current pinned package reference while preserving
  * every unrelated plugin entry.
  */
-function ensureMatePluginReference(config: Record<string, unknown>, pluginReference: string): void {
-  const existing = Array.isArray(config.plugin) ? config.plugin : [];
-  const preserved = existing.filter(
+function ensureMatePluginReference(config: OpenCodeConfig, pluginReference: string): void {
+  const preserved = getOpenCodePluginReferences(config).filter(
     (entry) => !isMateOpenCodePluginReference(entry) && !isLegacyMatePluginConfigEntry(entry),
   );
-  config.plugin = [...preserved, pluginReference];
+  setOpenCodePluginReferences(config, [...preserved, pluginReference]);
 }
 
-function stripMatePluginReference(config: Record<string, unknown>): void {
+function stripMatePluginReference(config: OpenCodeConfig): void {
   if (!Array.isArray(config.plugin)) return;
 
-  const preserved = config.plugin.filter(
+  const preserved = getOpenCodePluginReferences(config).filter(
     (entry) => !isMateOpenCodePluginReference(entry) && !isLegacyMatePluginConfigEntry(entry),
   );
-  if (preserved.length === 0) {
-    delete config.plugin;
-    return;
-  }
-  config.plugin = preserved;
+  setOpenCodePluginReferences(config, preserved);
 }
 
 async function syncOpenCodeConfigFile(
@@ -141,7 +148,7 @@ async function syncOpenCodeConfigFile(
 
   mergeConfigDefaults(existing, defaults);
   ensureMatePluginReference(existing, pluginReference);
-  await fs.writeFile(destPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+  await writeOpenCodeConfig(destPath, existing);
 }
 
 function normalizeForComparison(value: unknown): unknown {
@@ -188,7 +195,7 @@ async function teardownOpenCodeConfigFile(srcPath: string, destPath: string): Pr
     return;
   }
 
-  await fs.writeFile(destPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+  await writeOpenCodeConfig(destPath, existing);
 }
 
 async function removeLegacyTuiDependencies(dest: string): Promise<void> {
@@ -244,9 +251,9 @@ async function warmPluginCacheForSetup(pluginReference: string): Promise<void> {
 
   process.stderr.write(
     [
-      `${frameworkCommandName()}: could not pre-fetch ${pluginReference} into OpenCode's plugin environment.`,
+      `${FRAMEWORK_NAME}: could not pre-fetch ${pluginReference} into OpenCode's plugin environment.`,
       "The first managed OpenCode launch will download it, which requires registry access.",
-      `Re-run \`${frameworkCommandName()} companion setup\` with network access to warm the cache ahead of time.`,
+      `Re-run \`${FRAMEWORK_NAME} companion setup\` with network access to warm the cache ahead of time.`,
       ...(warmed.detail ? [`Details: ${warmed.detail}`] : []),
     ].join("\n") + "\n",
   );
@@ -327,55 +334,149 @@ function getCompanionOpenCodeConfigPath(companionPath: string): string {
   return path.join(companionPath, ".opencode", "opencode.json");
 }
 
-function opencodeMcpEntry(descriptor: McpServerDescriptor): Record<string, unknown> {
-  if (descriptor.url) {
-    return { type: "remote", url: descriptor.url, enabled: true };
+// ---------------------------------------------------------------------------
+// Runtime Surface escape hatch (spec: runtime-surface). Imperative operations
+// for effects a declaration cannot express. Format knowledge stays here;
+// capabilities pass only predicates.
+// ---------------------------------------------------------------------------
+
+/** Patch markdown files of an externally written `.opencode/skills/<name>` tree. */
+export async function patchOpenCodeSkillTree(
+  companionPath: string,
+  name: string,
+  transform: (content: string) => string,
+  options: { excludeFiles?: readonly string[] } = {},
+): Promise<void> {
+  await patchSkillTreeMarkdownFiles(
+    path.join(companionPath, ".opencode", "skills", name),
+    transform,
+    new Set(options.excludeFiles ?? []),
+  );
+}
+
+/**
+ * Strip a foreign heading section from the OpenCode guidance surfaces: the
+ * shared root AGENTS.md, the per-provider `.opencode/AGENTS.md`, and — when
+ * syncing from a linked repo — the repo-level AGENTS.md. With
+ * `guardSharedFile`, the shared root file is left alone while another active
+ * runtime (Claude) still uses it.
+ */
+export async function stripOpenCodeForeignSections(
+  companionPath: string,
+  options: RemoveHeadingSectionOptions & {
+    repoPath?: string;
+    guardSharedFile?: { activeProviders: string[] };
+  },
+): Promise<void> {
+  const sharedWithActive = options.guardSharedFile?.activeProviders.includes("claude") ?? false;
+  if (!sharedWithActive) {
+    await stripSectionFromFile(path.join(companionPath, "AGENTS.md"), options);
+  }
+  await stripSectionFromFile(path.join(companionPath, ".opencode", "AGENTS.md"), options);
+  if (options.repoPath) {
+    await stripSectionFromFile(path.join(options.repoPath, "AGENTS.md"), options);
   }
-  return {
-    type: "local",
-    command: [descriptor.command ?? "", ...(descriptor.args ?? [])].filter(Boolean),
-    ...(descriptor.env ? { environment: descriptor.env } : {}),
-    enabled: true,
-  };
 }
 
-// Reconcile a single Mate-managed MCP server in `.opencode/opencode.json`
-// while preserving every unrelated key. `entry: null` removes the server.
-async function updateCompanionOpenCodeMcpServer(
+/**
+ * Remove plugin entries matching `isForeign` from `opencode.json`. A config
+ * left empty is deleted; malformed configs are left untouched.
+ */
+export async function removeOpenCodeForeignPluginReferences(
   companionPath: string,
-  name: string,
-  entry: Record<string, unknown> | null,
+  isForeign: (entry: unknown) => boolean,
 ): Promise<void> {
   const configPath = getCompanionOpenCodeConfigPath(companionPath);
-  let existing: Record<string, unknown> = {};
-  let present = false;
+  let raw: string;
   try {
-    const parsed = JSON.parse(await fs.readFile(configPath, "utf8")) as unknown;
-    if (isRecord(parsed)) {
-      existing = parsed;
-      present = true;
-    }
+    raw = await fs.readFile(configPath, "utf8");
   } catch {
-    // Absent or unparseable — start from an empty object.
+    return;
   }
-  if (entry === null && !present) return;
-
-  const mcp: Record<string, unknown> = isRecord(existing.mcp) ? { ...existing.mcp } : {};
-  if (entry === null) {
-    if (!(name in mcp)) return;
-    delete mcp[name];
-  } else {
-    mcp[name] = entry;
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (Array.isArray(parsed.plugin)) {
+      setOpenCodePluginReferences(
+        parsed,
+        parsed.plugin.filter((entry) => !isForeign(entry)),
+      );
+    }
+    if (Object.keys(parsed).length === 0) {
+      await fs.unlink(configPath);
+    } else {
+      await writeOpenCodeConfig(configPath, parsed);
+    }
+  } catch {
+    // JSON parse error — leave file untouched
   }
+}
+
+// ---------------------------------------------------------------------------
+// Runtime Surface reconciliation: apply/remove declared Capability
+// contributions (spec: runtime-surface). Managed identity: named MCP servers,
+// `isManagedReference` for plugin entries, managed guidance blocks, and named
+// skill trees.
+// ---------------------------------------------------------------------------
 
-  const next = { ...existing };
-  if (Object.keys(mcp).length > 0) {
-    next.mcp = mcp;
-  } else {
-    delete next.mcp;
+const OPENCODE_CONTRIBUTION_CONFIG_FILES = ["opencode.json", "tui.json"];
+
+export async function reconcileOpenCodeContributions(
+  ctx: SetupContext,
+  inputs: CapabilityContributionInput[],
+): Promise<void> {
+  const { companionPath } = ctx;
+
+  for (const input of inputs) {
+    for (const descriptor of input.contributions.mcpServers ?? []) {
+      await updateOpenCodeMcpServer(
+        getCompanionOpenCodeConfigPath(companionPath),
+        descriptor.name,
+        input.enabled ? toOpenCodeMcpEntry(descriptor) : null,
+      );
+    }
+
+    for (const pluginReference of input.contributions.pluginReferences ?? []) {
+      const configFiles = pluginReference.configFiles ?? OPENCODE_CONTRIBUTION_CONFIG_FILES;
+      for (const name of configFiles) {
+        const configPath = path.join(companionPath, ".opencode", name);
+        const { present, config } = await readOpenCodeConfig(configPath);
+        if (!input.enabled && !present) continue;
+        const preserved = getOpenCodePluginReferences(config).filter(
+          (entry) => !pluginReference.isManagedReference(entry),
+        );
+        setOpenCodePluginReferences(
+          config,
+          input.enabled ? [...preserved, pluginReference.reference] : preserved,
+        );
+        await writeOpenCodeConfig(configPath, config);
+      }
+    }
+
+    // Guidance sections are managed blocks in AGENTS.md. Capability disable
+    // strips them here; runtime teardown of the shared AGENTS.md is guarded in
+    // the provider teardown paths (kept while another active runtime uses it).
+    const guidancePath = path.join(companionPath, "AGENTS.md");
+    const sections = input.enabled ? (input.contributions.guidanceSections ?? []) : [];
+    const keepKeys = new Set<string>();
+    for (const section of sections) {
+      const blockKey = instructionBlockKey(input.pluginId, section.content);
+      keepKeys.add(blockKey);
+      await upsertManagedBlock(guidancePath, FRAMEWORK_NAME, blockKey, section.content);
+    }
+    if ((input.contributions.guidanceSections ?? []).length > 0) {
+      await removeManagedBlocksForPlugin(guidancePath, FRAMEWORK_NAME, input.pluginId, keepKeys);
+    }
+
+    for (const skillTree of input.contributions.skillTrees ?? []) {
+      const skillDir = path.join(companionPath, ".opencode", "skills", skillTree.name);
+      if (input.enabled) {
+        await mergeDir(skillTree.sourceDir, skillDir);
+      } else {
+        await fs.rm(skillDir, { recursive: true, force: true });
+        await pruneEmptyAncestors(path.join(companionPath, ".opencode", "skills"), companionPath);
+      }
+    }
   }
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.writeFile(configPath, JSON.stringify(next, null, 2) + "\n", "utf8");
 }
 
 export function createOpenCodePlugin(): ProviderPlugin {
@@ -385,18 +486,22 @@ export function createOpenCodePlugin(): ProviderPlugin {
     label: "OpenCode",
     description: "Install the OpenCode plugin workspace.",
     defaultSelected: false,
-    isEnabled: (config) => (config.profiles.default?.allowedAgents ?? []).includes("opencode"),
+    isEnabled: (config) => (config.allowedAgents ?? []).includes("opencode"),
     hosting: {
       mcp: {
-        async register(ctx: SetupContext, descriptor: McpServerDescriptor) {
-          await updateCompanionOpenCodeMcpServer(
-            ctx.companionPath,
+        async register(ctx: SetupContext, descriptor) {
+          await updateOpenCodeMcpServer(
+            getCompanionOpenCodeConfigPath(ctx.companionPath),
             descriptor.name,
-            opencodeMcpEntry(descriptor),
+            toOpenCodeMcpEntry(descriptor),
           );
         },
         async unregister(ctx: SetupContext, name: string) {
-          await updateCompanionOpenCodeMcpServer(ctx.companionPath, name, null);
+          await updateOpenCodeMcpServer(
+            getCompanionOpenCodeConfigPath(ctx.companionPath),
+            name,
+            null,
+          );
         },
       },
       instructions: {

package/src/tools/setup/providers/skill-tree.ts

@@ -0,0 +1,38 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// Escape-hatch support: patch markdown files of a skill tree that an external
+// CLI wrote into a runtime directory (SKILL.md plus references/*.md).
+// Directory-driven so reference files added by future releases are covered.
+
+async function patchMarkdownFile(
+  filePath: string,
+  transform: (content: string) => string,
+): Promise<void> {
+  let content: string;
+  try {
+    content = await fs.readFile(filePath, "utf8");
+  } catch {
+    return; // file absent — nothing to patch
+  }
+  const rewritten = transform(content);
+  if (rewritten !== content) await fs.writeFile(filePath, rewritten, "utf8");
+}
+
+export async function patchSkillTreeMarkdownFiles(
+  skillDir: string,
+  transform: (content: string) => string,
+  excludeFiles: ReadonlySet<string> = new Set(),
+): Promise<void> {
+  await patchMarkdownFile(path.join(skillDir, "SKILL.md"), transform);
+
+  const refsDir = path.join(skillDir, "references");
+  let entries: string[];
+  try {
+    entries = await fs.readdir(refsDir);
+  } catch {
+    return; // no references/ dir
+  }
+  const targets = entries.filter((name) => name.endsWith(".md") && !excludeFiles.has(name));
+  await Promise.all(targets.map((name) => patchMarkdownFile(path.join(refsDir, name), transform)));
+}

package/src/tools/setup.ts

@@ -2,7 +2,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
+import { FRAMEWORK_NAME } from "../framework";
 import { ConfigStore, mergeWithDefaults } from "../lib/orchestrator/config-store";
 import { GlobalConfigStore } from "../lib/orchestrator/global-config-store";
 import {
@@ -91,9 +91,8 @@ export async function syncCompanionFiles(
   );
 }
 
-// Exported for the distribution-identity tests.
 export function mateFolderReadme(): string {
-  const n = frameworkCommandName();
+  const n = FRAMEWORK_NAME;
   const packageName =
     getActiveDistribution().config.update?.packageName ?? `@uniqbit/${FRAMEWORK_NAME}`;
   return [
@@ -121,7 +120,7 @@ export function mateFolderReadme(): string {
     ``,
     `Edit \`.${FRAMEWORK_NAME}/config/framework.yaml\` to configure:`,
     ``,
-    `- **profiles** — per-profile allowed agents list`,
+    `- **allowedAgents** — agents permitted to launch from linked repositories`,
     `- **capabilities** — skill and CLI tool capabilities (e.g. react-doctor, openspec, tokensave, headroom, rtk)`,
     `- **git** — set to \`auto\` to synchronize the companion before agent launches`,
     ``,
@@ -140,7 +139,7 @@ export const setupToolDeps = {
 
 const setup: FrameworkTool<SetupInput, { config: FrameworkConfig }> = {
   name: "setup",
-  description: "Initialize framework runtime, default profiles, and configure .opencode.",
+  description: "Initialize framework runtime, agent policy, and configure .opencode.",
   async execute(input) {
     return setupToolDeps.executeSetup(input);
   },
@@ -161,10 +160,16 @@ export async function executeSetup(
     deps.configStore ??
     new ConfigStore(path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"));
   const config = mergeWithDefaults(await configStore.load());
-  const defaultProfile = config.profiles.default;
+  // Hubs are never companions: no setup entry path (CLI, wizard, or the
+  // setup framework tool) may write agent guidance into a hub root.
+  if (config.type === "hub") {
+    throw new ConfigError(
+      `A companion hub cannot be set up as a companion: ${cwd}. Use \`${FRAMEWORK_NAME} hub\` commands to manage the hub.`,
+    );
+  }
 
   if (input.allowedAgents !== undefined) {
-    defaultProfile.allowedAgents = [...new Set(input.allowedAgents)];
+    config.allowedAgents = [...new Set(input.allowedAgents)];
   }
   if (input.packageManagers !== undefined) {
     config.packageManagers = getSetupSelectionsFromConfig({

package/src/tui.ts

@@ -0,0 +1,5 @@
+export { SelectMenu, type SelectMenuItem } from "./lib/components/select-menu";
+export { WizardFooter } from "./lib/components/wizard-footer";
+export { WizardHeader } from "./lib/components/wizard-header";
+export { TextInputDisplay } from "./lib/components/text-input-display";
+export { ConfirmPromptApp, confirmPrompt } from "./lib/components/confirm-prompt";