@uniqbit/mate-core 0.17.2-canary.3 → 0.18.0

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

@@ -14,6 +14,12 @@ import {
   type PluginHost,
 } from "./host";
 import { dynamicPluginsWorkspaceRoot, pluginPackageRoot } from "./paths";
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
 
 interface PluginManifest {
   mate?: { pluginApiVersion?: unknown };
@@ -47,6 +53,16 @@ export async function loadDynamicPlugin(
   const name = declaration.package;
   const packageRoot = pluginPackageRoot(companionPath, name);
 
+  /** Fails closed: a malformed policy allows nothing. Checked before any plugin file is touched. */
+  try {
+    if (!isPluginAllowed(readPluginPolicy(deps.env ?? process.env), name)) {
+      return { ok: false, warning: `${disallowedPluginMessage(name)}; not loaded.` };
+    }
+  } catch (error) {
+    if (!(error instanceof PluginPolicyError)) throw error;
+    return { ok: false, warning: `plugin "${name}" not loaded: ${error.message}` };
+  }
+
   let manifest: PluginManifest;
   try {
     manifest = JSON.parse(

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

@@ -0,0 +1,55 @@
+/** Environment variable carrying the appliance's declared-plugin package allowlist. */
+export const ALLOWED_PLUGINS_ENV = "MATE_ALLOWED_PLUGINS";
+
+/**
+ * Parsed allowlist: exact package names and scope-wide `@scope/*` patterns.
+ * An empty list permits no package; the policy's absence permits all.
+ */
+export interface PluginPolicy {
+  exact: string[];
+  scopes: string[];
+}
+
+export class PluginPolicyError extends Error {}
+
+const EXACT_PATTERN = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9._~-]*\/\*$/;
+
+/**
+ * Parses a comma-separated allowlist. `undefined` means no policy; an empty
+ * or blank string is an explicit empty policy. Malformed entries throw so a
+ * typo can never widen or silently narrow the trust decision.
+ */
+export function parseAllowedPlugins(raw: string | undefined): PluginPolicy | null {
+  if (raw === undefined) return null;
+  const policy: PluginPolicy = { exact: [], scopes: [] };
+  if (raw.trim() === "") return policy;
+  for (const part of raw.split(",")) {
+    const entry = part.trim();
+    if (SCOPE_PATTERN.test(entry)) policy.scopes.push(entry.slice(0, entry.indexOf("/") + 1));
+    else if (EXACT_PATTERN.test(entry)) policy.exact.push(entry);
+    else {
+      throw new PluginPolicyError(
+        `${ALLOWED_PLUGINS_ENV}: malformed entry ${JSON.stringify(entry)}; expected an exact package name or a scope pattern such as "@acme/*"`,
+      );
+    }
+  }
+  return policy;
+}
+
+/** Reads the effective policy from an environment; throws on a malformed value. */
+export function readPluginPolicy(
+  env: Record<string, string | undefined> = process.env,
+): PluginPolicy | null {
+  return parseAllowedPlugins(env[ALLOWED_PLUGINS_ENV]);
+}
+
+export function isPluginAllowed(policy: PluginPolicy | null, packageName: string): boolean {
+  if (policy === null) return true;
+  if (policy.exact.includes(packageName)) return true;
+  return policy.scopes.some((scope) => packageName.startsWith(scope));
+}
+
+export function disallowedPluginMessage(packageName: string): string {
+  return `plugin "${packageName}" is not allowed by ${ALLOWED_PLUGINS_ENV}`;
+}

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

@@ -25,16 +25,22 @@ function changedPaths(cwd: string): string[] {
 }
 
 /**
- * Reports what plugins would generate that is not already committed. The
- * projection runs against a disposable clone of the checkout's commit, so edits
- * in the live checkout neither matter nor are touched, and any file that
- * differs afterwards is drift. Nothing is written back to the live checkout.
- * Returns the drifting paths (empty when the commit is complete).
+ * Checks that what plugins would generate is already committed. The live
+ * checkout must have no edits of its own; the projection then runs against a
+ * disposable clone of its commit, and any file that differs afterwards is
+ * drift. Nothing is written back to the live checkout. Returns the drifting
+ * paths (empty when the checkout is complete).
  */
 export async function verifyTrackedPluginOutputs(
   companionPath: string,
   project: StagedProjection,
 ): Promise<string[]> {
+  const pending = changedPaths(companionPath);
+  if (pending.length > 0) {
+    throw new TrackedOutputError(
+      `the checkout has uncommitted changes, which frozen setup will not overwrite: ${pending.join(", ")}`,
+    );
+  }
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "mate-staging-"));
   try {
     const staged = path.join(root, "companion");

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

@@ -5,37 +5,38 @@ import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import { readDeclarations, validateDeclaration } from "./declarations";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 import { pluginPackageRoot } from "./paths";
+import {
+  disallowedPluginMessage,
+  isPluginAllowed,
+  PluginPolicyError,
+  readPluginPolicy,
+} from "./policy";
 
 export interface PluginVerificationFailure {
   package: string;
   reason: string;
 }
 
-export interface PluginInspection {
-  failures: PluginVerificationFailure[];
-  /** IDs of the capabilities the loaded plugins provide. */
-  capabilities: string[];
-}
-
 /**
- * Strict, installation-free check of every declared plugin: installed
+ * Strict, installation-free check of every declared plugin: allowed, installed
  * and loadable with the effective environment. Unlike hydration it fails
- * closed on the first-class problems ordinary commands only warn about.
+ * closed on the first-class problems ordinary commands only warn about. Only
+ * allowlisted packages are imported.
  */
 export async function verifyDeclaredPlugins(
   companionPath: string,
   deps: DynamicPluginLoadDeps = {},
 ): Promise<PluginVerificationFailure[]> {
-  return (await inspectDeclaredPlugins(companionPath, deps)).failures;
-}
-
-export async function inspectDeclaredPlugins(
-  companionPath: string,
-  deps: DynamicPluginLoadDeps = {},
-): Promise<PluginInspection> {
   const env = deps.env ?? process.env;
   const failures: PluginVerificationFailure[] = [];
-  const capabilities: string[] = [];
+  let policy: ReturnType<typeof readPluginPolicy>;
+  try {
+    policy = readPluginPolicy(env);
+  } catch (error) {
+    if (!(error instanceof PluginPolicyError)) throw error;
+    return [{ package: "(allowlist)", reason: error.message }];
+  }
+
   const declarations: PluginDeclaration[] = [];
   for (const entry of await readDeclarations(companionPath)) {
     const { declaration, error } = validateDeclaration(entry);
@@ -45,6 +46,10 @@ export async function inspectDeclaredPlugins(
 
   for (const declaration of declarations) {
     const name = declaration.package;
+    if (!isPluginAllowed(policy, name)) {
+      failures.push({ package: name, reason: disallowedPluginMessage(name) });
+      continue;
+    }
     // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
     const installed = await fs
       .access(pluginPackageRoot(companionPath, name))
@@ -60,7 +65,6 @@ export async function inspectDeclaredPlugins(
     // oxlint-disable-next-line no-await-in-loop -- declared order is part of the contract
     const result = await loadDynamicPlugin(companionPath, declaration, { ...deps, env });
     if (!result.ok) failures.push({ package: name, reason: result.warning });
-    else if (result.plugin.kind === "capability") capabilities.push(result.plugin.id);
   }
-  return { failures, capabilities };
+  return failures;
 }

package/src/tools/setup/engine.ts

@@ -221,7 +221,12 @@ async function collectContributionInputs(
       // are torn down. The surfaces never create files for disabled inputs.
       const runtimeActive = plan.activeProviders.includes(runtimeId);
       const inputs = inputsByRuntime.get(runtimeId) ?? [];
-      inputs.push({ pluginId: capability.id, enabled: enabled && runtimeActive, contributions });
+      inputs.push({
+        pluginId: capability.id,
+        enabled: enabled && runtimeActive,
+        capabilityEnabled: enabled,
+        contributions,
+      });
       inputsByRuntime.set(runtimeId, inputs);
     }
   }

package/src/tools/setup/install-contract.ts

@@ -17,4 +17,6 @@ export interface InstallRequirement {
   detect(): boolean | Promise<boolean>;
   install(): Promise<void>;
   verify?(): boolean | Promise<boolean>;
+  /** Best-effort refresh of an already-satisfied requirement; must never throw. */
+  update?(): Promise<void>;
 }

package/src/tools/setup/mate.ts

@@ -17,6 +17,8 @@ export const MATE_SKILLS = [
   "mate-simplify-code",
 ] as const;
 const LEGACY_MATE_SKILLS = ["mate-artifact-finish", "mate-openspec-artifact-finish"] as const;
+/** Every Mate-owned skill name a skill root may hold, current or retired. */
+export const MANAGED_MATE_SKILL_NAMES = [...MATE_SKILLS, ...LEGACY_MATE_SKILLS] as const;
 
 const MATE_SKILLS_SOURCE = path.join(import.meta.dirname, "../../templates/mate-skills");
 
@@ -147,7 +149,7 @@ export async function applyMateSkills(skillsDir: string, tool: string): Promise<
 }
 
 export async function teardownMateSkills(skillsDir: string, companionPath: string): Promise<void> {
-  for (const skill of [...MATE_SKILLS, ...LEGACY_MATE_SKILLS]) {
+  for (const skill of MANAGED_MATE_SKILL_NAMES) {
     try {
       await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
     } catch {

package/src/tools/setup/plugin.ts

@@ -219,6 +219,8 @@ export type RuntimeContributionsByRuntime = Partial<Record<string, RuntimeContri
 export interface CapabilityContributionInput {
   pluginId: string;
   enabled: boolean;
+  /** Capability enabled regardless of runtime; absent means disabled. */
+  capabilityEnabled?: boolean;
   contributions: RuntimeContributions;
 }
 

package/src/tools/setup/providers/agents-skill-root.ts

@@ -0,0 +1,79 @@
+// oxlint-disable no-await-in-loop
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type { SkillTreeContribution } from "../plugin";
+import { mergeDir, pruneEmptyAncestors } from "../utils";
+
+/**
+ * Agent Runtimes that read the vendor-neutral companion `.agents/skills` root.
+ * Claude is never a member: it reads only `.claude/skills`.
+ */
+export const SHARED_SKILL_ROOT_RUNTIMES = ["opencode"] as const;
+
+export function isSharedSkillRootActive(activeProviders: readonly string[]): boolean {
+  return SHARED_SKILL_ROOT_RUNTIMES.some((runtime) => activeProviders.includes(runtime));
+}
+
+export function getSharedSkillsDir(companionPath: string): string {
+  return path.join(companionPath, ".agents", "skills");
+}
+
+function getLegacyOpenCodeSkillsDir(companionPath: string): string {
+  return path.join(companionPath, ".opencode", "skills");
+}
+
+/** Mate owns skill-root entries only by name; the directory itself is never listed or wiped. */
+async function removeSkillNames(
+  skillsDir: string,
+  names: readonly string[],
+  companionPath: string,
+): Promise<void> {
+  for (const name of names) {
+    await fs.rm(path.join(skillsDir, name), { recursive: true, force: true });
+  }
+  await pruneEmptyAncestors(skillsDir, companionPath);
+}
+
+export async function removeSharedSkills(
+  companionPath: string,
+  names: readonly string[],
+): Promise<void> {
+  await removeSkillNames(getSharedSkillsDir(companionPath), names, companionPath);
+}
+
+export async function removeLegacyOpenCodeSkills(
+  companionPath: string,
+  names: readonly string[],
+): Promise<void> {
+  await removeSkillNames(getLegacyOpenCodeSkillsDir(companionPath), names, companionPath);
+}
+
+export interface SharedSkillTreeState {
+  /** Capability enabled and the reconciling runtime active. */
+  enabled: boolean;
+  /** Capability enabled regardless of runtime; separates disable from runtime deselect. */
+  capabilityEnabled: boolean;
+  activeProviders: readonly string[];
+}
+
+/**
+ * Reconcile one declared skill tree into the shared root. A deselected runtime
+ * keeps the tree while another reading runtime is still active.
+ */
+export async function reconcileSharedSkillTree(
+  companionPath: string,
+  skillTree: SkillTreeContribution,
+  state: SharedSkillTreeState,
+): Promise<void> {
+  await removeLegacyOpenCodeSkills(companionPath, [skillTree.name]);
+  if (state.enabled) {
+    await mergeDir(
+      skillTree.sourceDir,
+      path.join(getSharedSkillsDir(companionPath), skillTree.name),
+    );
+    return;
+  }
+  if (state.capabilityEnabled && isSharedSkillRootActive(state.activeProviders)) return;
+  await removeSharedSkills(companionPath, [skillTree.name]);
+}

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

@@ -11,6 +11,7 @@ import {
 } from "../../../lib/opencode-plugin-package";
 import { refreshFromTemplate, stripGuidanceBlock } from "../plugins/guidance";
 import { stripSectionFromFile, type RemoveHeadingSectionOptions } from "./agent-file-sections";
+import { reconcileSharedSkillTree } from "./agents-skill-root";
 import { patchSkillTreeMarkdownFiles } from "./skill-tree";
 import {
   instructionBlockKey,
@@ -21,7 +22,7 @@ import type { CapabilityContributionInput, ProviderPlugin, SetupContext } from "
 import { surfaceRoot } from "../surface-target";
 import { resolvePreinstalledPluginReference } from "../../../lib/preinstalled-plugins";
 import { getCurrentVersion } from "../../../lib/update-checker";
-import { mergeDir, pruneEmptyAncestors } from "../utils";
+import { pruneEmptyAncestors } from "../utils";
 import {
   getOpenCodePluginReferences,
   isRecord,
@@ -465,7 +466,7 @@ export async function removeOpenCodeForeignPluginReferences(
 // 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.
+// skill trees (written to the shared `.agents/skills` root).
 // ---------------------------------------------------------------------------
 
 const OPENCODE_CONTRIBUTION_CONFIG_FILES = ["opencode.json"];
@@ -530,13 +531,11 @@ export async function reconcileOpenCodeContributions(
     }
 
     for (const skillTree of input.contributions.skillTrees ?? []) {
-      const skillDir = path.join(root, ".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(root, ".opencode", "skills"), root);
-      }
+      await reconcileSharedSkillTree(root, skillTree, {
+        enabled: input.enabled,
+        capabilityEnabled: input.capabilityEnabled ?? false,
+        activeProviders: ctx.activeProviders,
+      });
     }
   }
 }