@uniqbit/mate-core 0.15.0-canary.2 → 0.15.0-canary.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.0-canary.2",
+  "version": "0.15.0-canary.3",
   "license": "MIT",
   "files": [
     "src/",

package/src/cli/commands/cap/index.ts

@@ -2,6 +2,7 @@ import { runGraphifyCapCommand } from "./graphify";
 import { runHeadroomCapCommand } from "./headroom";
 import { runOpenspecCapCommand } from "./openspec";
 import { runIndexCapCommand } from "./index-cmd";
+import { runPluginCliCommand } from "../../plugin-commands";
 
 /**
  * @command mate cap <capability> [...args]
@@ -9,9 +10,10 @@ import { runIndexCapCommand } from "./index-cmd";
  * `headroom`, `openspec` (each forwards `[...args]` to the underlying CLI tool,
  * scoped to the resolved companion/working repo), or `index` (re-syncs
  * capability indexes such as tokensave/graphify after code changes; `sync` is
- * accepted as a compatibility alias for `index`). Prints
- * usage and sets a non-zero exit code when no capability name or an unknown one
- * is given.
+ * accepted as a compatibility alias for `index`). Names not claimed by the
+ * framework dispatch to plugin-declared CLI commands as
+ * `mate cap <namespace> <command>`. Prints usage and sets a non-zero exit code
+ * when no capability name or an unknown one is given.
  */
 export async function runCapCommand(
   capabilityName: string | undefined,
@@ -40,6 +42,7 @@ export async function runCapCommand(
       await runIndexCapCommand(args);
       return;
     default:
+      if (await runPluginCliCommand(capabilityName, args[0], args.slice(1))) return;
       process.stderr.write(`mate: unknown capability command: ${capabilityName}\n`);
       process.exitCode = 1;
   }

package/src/cli/commands/launch/claude.ts

@@ -1,9 +1,4 @@
-import {
-  ensureUnambiguousCompanion,
-  parseDirectLaunchArgs,
-  parseLaunchArgs,
-  runLaunchToolCommand,
-} from "./shared";
+import { makeLaunchCommand } from "./shared";
 
 /**
  * @command mate claude [-- ...agentArgs]
@@ -17,20 +12,4 @@ import {
  * alias), all args before `--` are treated as agent args rather than being
  * parsed as launch options.
  */
-export async function runLaunchClaudeCommand(
-  args: string[],
-  options: { directPassthrough?: boolean } = {},
-): Promise<void> {
-  const parsed = options.directPassthrough ? parseDirectLaunchArgs(args) : parseLaunchArgs(args);
-  if (!parsed) return;
-
-  if (!(await ensureUnambiguousCompanion())) {
-    process.exitCode = 1;
-    return;
-  }
-
-  await runLaunchToolCommand("claude", parsed.agentArgs, {
-    skipConfirmation: !!process.stdin.isTTY,
-    skipGit: parsed.skipGit,
-  });
-}
+export const runLaunchClaudeCommand = makeLaunchCommand("claude");

package/src/cli/commands/launch/opencode.ts

@@ -1,9 +1,4 @@
-import {
-  ensureUnambiguousCompanion,
-  parseDirectLaunchArgs,
-  parseLaunchArgs,
-  runLaunchToolCommand,
-} from "./shared";
+import { makeLaunchCommand } from "./shared";
 
 /**
  * @command mate opencode [-- ...agentArgs]
@@ -17,20 +12,4 @@ import {
  * opencode` alias), all args before `--` are treated as agent args rather
  * than being parsed as launch options.
  */
-export async function runLaunchOpenCodeCommand(
-  args: string[],
-  options: { directPassthrough?: boolean } = {},
-): Promise<void> {
-  const parsed = options.directPassthrough ? parseDirectLaunchArgs(args) : parseLaunchArgs(args);
-  if (!parsed) return;
-
-  if (!(await ensureUnambiguousCompanion())) {
-    process.exitCode = 1;
-    return;
-  }
-
-  await runLaunchToolCommand("opencode", parsed.agentArgs, {
-    skipConfirmation: !!process.stdin.isTTY,
-    skipGit: parsed.skipGit,
-  });
-}
+export const runLaunchOpenCodeCommand = makeLaunchCommand("opencode");

package/src/cli/commands/launch/shared.ts

@@ -128,3 +128,28 @@ export async function runLaunchToolCommand(
     throw error;
   }
 }
+
+/**
+ * Builds the `mate <tool>` command handler: parses launch args (direct
+ * passthrough or flagged), guards against ambiguous companions, then launches
+ * via {@link runLaunchToolCommand} with confirmation skipped in a TTY.
+ */
+export function makeLaunchCommand(tool: LaunchTarget) {
+  return async function runLaunchCommand(
+    args: string[],
+    options: { directPassthrough?: boolean } = {},
+  ): Promise<void> {
+    const parsed = options.directPassthrough ? parseDirectLaunchArgs(args) : parseLaunchArgs(args);
+    if (!parsed) return;
+
+    if (!(await ensureUnambiguousCompanion())) {
+      process.exitCode = 1;
+      return;
+    }
+
+    await runLaunchToolCommand(tool, parsed.agentArgs, {
+      skipConfirmation: !!process.stdin.isTTY,
+      skipGit: parsed.skipGit,
+    });
+  };
+}

package/src/cli/commands/update.ts

@@ -7,20 +7,30 @@ import {
   warmOpenCodePluginCache,
 } from "../../lib/opencode-plugin-package";
 import { installPublicPackageSync, isPackageInstalledAtNpmGlobalRoot } from "../../lib/public-npm";
-import { fetchLatestVersion, getCurrentVersion, isNewer } from "../../lib/update-checker";
+import {
+  fetchLatestVersion,
+  getCurrentVersion,
+  getUpdateConfig,
+  isNewer,
+} from "../../lib/update-checker";
 import { confirmPrompt } from "../../lib/components/confirm-prompt";
 
 type InstallResult = ReturnType<typeof installPublicPackageSync>;
 
 function writeNpmOnlyRecoveryMessage(): void {
+  const { packageName, registry } = getUpdateConfig();
   process.stderr.write(
     `${frameworkConfig.name}: self-update is only supported for npm-installed Mate.\n`,
   );
+  if (packageName.startsWith("@uniqbit/")) {
+    process.stderr.write(
+      "If you previously configured the legacy GitLab registry override, remove it first:\n",
+    );
+    process.stderr.write("  npm config delete @uniqbit:registry --global\n");
+  }
   process.stderr.write(
-    "If you previously configured the legacy GitLab registry override, remove it first:\n",
+    `Then reinstall with: npm install -g ${packageName} --registry ${registry}\n`,
   );
-  process.stderr.write("  npm config delete @uniqbit:registry --global\n");
-  process.stderr.write(`Then reinstall with: npm install -g @uniqbit/${frameworkConfig.name}\n`);
 }
 
 export const updateCommandDeps = {
@@ -31,10 +41,12 @@ export const updateCommandDeps = {
   isNpmManagedInstall: () =>
     isPackageInstalledAtNpmGlobalRoot(
       path.resolve(import.meta.dirname, "../../.."),
-      `@uniqbit/${frameworkConfig.name}`,
+      getUpdateConfig().packageName,
     ),
-  installLatest: (latest: string): InstallResult =>
-    installPublicPackageSync(`@uniqbit/${frameworkConfig.name}@${latest}`),
+  installLatest: (latest: string): InstallResult => {
+    const { packageName, registry } = getUpdateConfig();
+    return installPublicPackageSync(`${packageName}@${latest}`, registry);
+  },
   saveUpdateState: async (latest: string) => {
     const { UpdateStateStore } = await import("../../lib/update-checker");
     const store = new UpdateStateStore();
@@ -51,7 +63,8 @@ export const updateCommandDeps = {
     const args = [entrypoint, "install", ...(skipConfirm ? ["--yes"] : [])];
     return spawnSync(process.execPath, args, { stdio: "inherit" }) as InstallResult;
   },
-  warmOpenCodePluginCache: (latest: string) => warmOpenCodePluginCache(latest),
+  warmOpenCodePluginCache: (latest: string) =>
+    warmOpenCodePluginCache(latest, process.env, getUpdateConfig().registry),
 };
 
 /**

package/src/cli/main.ts

@@ -16,6 +16,7 @@ import { runUpdateCommand } from "./commands/update";
 import { runInstallCommand } from "./commands/install";
 import { inspectInstallPreflight } from "../lib/install";
 import { ensureUnambiguousCompanion } from "./commands/shared/companion-selection";
+import { findPluginCliCommand } from "./plugin-commands";
 import { usage } from "./usage";
 
 export function isInstallRecoveryCommand(command?: string, subcommand?: string): boolean {
@@ -48,9 +49,16 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
     return;
   }
 
-  const updateStore = new UpdateStateStore();
-  await showUpdateBannerIfAvailable(updateStore);
-  scheduleBackgroundCheck(updateStore);
+  // Plugin commands (`mate cap <namespace> <command>`) own their stdout (an
+  // MCP server speaks JSON-RPC over it), so banners and background chatter
+  // are suppressed for them.
+  const isPluginCommand =
+    command === "cap" && findPluginCliCommand(subcommand, rest[0]) !== undefined;
+  if (!isPluginCommand) {
+    const updateStore = new UpdateStateStore();
+    await showUpdateBannerIfAvailable(updateStore);
+    scheduleBackgroundCheck(updateStore);
+  }
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
     console.log(usage());

package/src/cli/plugin-commands.ts

@@ -0,0 +1,104 @@
+import { getActiveDistribution } from "../distribution";
+import { resolveInstallContext } from "../lib/install";
+import type { FrameworkConfig } from "../lib/orchestrator/types";
+import type { Plugin, PluginCliCommand } from "../tools/setup/plugin";
+
+function namespaceOf(plugin: Plugin): string {
+  return plugin.cliNamespace ?? plugin.id;
+}
+
+function pluginForNamespace(namespace: string): Plugin | undefined {
+  return getActiveDistribution()
+    .registry.getAll()
+    .find((candidate) => namespaceOf(candidate) === namespace);
+}
+
+/**
+ * Dispatch `<distribution> cap <namespace> <name>` to a plugin-declared CLI
+ * command. Returns true when the namespace belongs to a plugin that declares
+ * CLI commands (the invocation is then fully handled here, including
+ * unknown-subcommand errors); false when no plugin claims the namespace so
+ * the caller can report an unknown command. Framework `cap` subcommands are
+ * dispatched before this is consulted, so they can never be shadowed.
+ *
+ * Commands are mounted independently of plugin selection: the MCP descriptors
+ * written during setup must stay launchable even when enablement is evaluated
+ * lazily. Commands guard their own preconditions.
+ */
+export async function runPluginCliCommand(
+  namespace: string,
+  commandName: string | undefined,
+  argv: string[],
+): Promise<boolean> {
+  const plugin = pluginForNamespace(namespace);
+  const commands = plugin?.cliCommands;
+  if (!plugin || !commands || commands.length === 0) return false;
+
+  const command = findPluginCliCommand(namespace, commandName);
+  if (!command) {
+    console.error(
+      commandName
+        ? `Unknown command: cap ${namespace} ${commandName}`
+        : `Missing subcommand for: cap ${namespace}`,
+    );
+    console.error(usageFor(plugin));
+    process.exitCode = 1;
+    return true;
+  }
+
+  await command.run(argv);
+  return true;
+}
+
+/**
+ * Look up a plugin-declared CLI command without running it. Used by `main` to
+ * detect plugin-owned invocations early — plugin commands own their stdout
+ * (e.g. an MCP server speaking JSON-RPC), so the CLI must not print banners
+ * before dispatching to one.
+ */
+export function findPluginCliCommand(
+  namespace: string | undefined,
+  commandName: string | undefined,
+): PluginCliCommand | undefined {
+  if (!namespace || !commandName) return undefined;
+  return pluginForNamespace(namespace)?.cliCommands?.find(
+    (candidate) => candidate.name === commandName,
+  );
+}
+
+export interface EnsureCapabilityEnabledDeps {
+  loadConfig?: () => Promise<FrameworkConfig>;
+}
+
+/**
+ * Guard for plugin CLI commands: verifies the owning plugin's capability is
+ * enabled in the resolved companion configuration. On failure it prints a
+ * message naming the capability and how to enable it, sets a non-zero exit
+ * code, and returns false so the command can bail out without side effects.
+ */
+export async function ensureCapabilityEnabled(
+  pluginId: string,
+  deps: EnsureCapabilityEnabledDeps = {},
+): Promise<boolean> {
+  const distribution = getActiveDistribution();
+  const plugin = distribution.registry.getAll().find((candidate) => candidate.id === pluginId);
+  const loadConfig = deps.loadConfig ?? (async () => (await resolveInstallContext()).config);
+  if (plugin?.isEnabled(await loadConfig())) return true;
+
+  const name = distribution.config.name;
+  console.error(
+    `${name}: the "${pluginId}" capability is not enabled for this companion. ` +
+      `Enable it via \`${name} companion setup\`.`,
+  );
+  process.exitCode = 1;
+  return false;
+}
+
+function usageFor(plugin: Plugin): string {
+  const distributionName = getActiveDistribution().config.name;
+  const namespace = namespaceOf(plugin);
+  const lines = (plugin.cliCommands ?? []).map(
+    (command) => `  ${distributionName} cap ${namespace} ${command.name}  ${command.description}`,
+  );
+  return ["Available commands:", ...lines].join("\n");
+}

package/src/create-mate.ts

@@ -26,9 +26,9 @@ export interface MateCli {
  */
 export function createMate({ config, plugins }: CreateMateOptions): MateCli {
   const registry = new PluginRegistry([
+    ...plugins,
     { plugin: createBunPlugin(), policy: "required" },
     { plugin: createUvPlugin(), policy: "required" },
-    ...plugins,
     createGitignorePlugin(config.name),
   ]);
   setActiveDistribution({ config, registry });

package/src/distribution.ts

@@ -1,14 +1,22 @@
 import type { PluginRegistry } from "./tools/setup/registry";
 
+export interface DistributionUpdateConfig {
+  /** npm package whose versions are checked and installed by `mate update`. */
+  packageName: string;
+  /** npm registry used for update checks and downloads. */
+  registry: string;
+}
+
 /** Identity and version of the distribution assembled through `createMate`. */
 export interface DistributionConfig {
   name: string;
   legacyNames?: string[];
   runtime: "bun";
-  supportedAdapters: string[];
   version: string;
   /** Asset directories that override the framework defaults, highest precedence first. */
   assetRoots?: string[];
+  /** Optional update source; defaults to `@uniqbit/<name>` on public npm. */
+  update?: DistributionUpdateConfig;
 }
 
 export interface ActiveDistribution {

package/src/framework.ts

@@ -16,7 +16,4 @@ export const frameworkConfig = {
   get runtime(): string {
     return getActiveDistribution().config.runtime;
   },
-  get supportedAdapters(): string[] {
-    return getActiveDistribution().config.supportedAdapters;
-  },
 };

package/src/index.ts

@@ -13,18 +13,21 @@ export {
   setFallbackDistribution,
   type ActiveDistribution,
   type DistributionConfig,
+  type DistributionUpdateConfig,
 } from "./distribution";
 export {
   normalizeRegistration,
   PluginRegistry,
   type NormalizedRegistration,
 } from "./tools/setup/registry";
+export { ensureCapabilityEnabled, type EnsureCapabilityEnabledDeps } from "./cli/plugin-commands";
 export type {
   CapabilityPlugin,
   InstructionsService,
   McpServerDescriptor,
   McpService,
   Plugin,
+  PluginCliCommand,
   PluginPolicy,
   PluginRegistration,
   ProviderHosting,

package/src/lib/fs-utils.ts

@@ -1,4 +1,20 @@
+import { accessSync, constants } from "node:fs";
 import fs from "node:fs/promises";
+import path from "node:path";
+
+export function isCommandOnPath(command: string, pathValue: string): boolean {
+  if (!pathValue) return false;
+  for (const dir of pathValue.split(path.delimiter)) {
+    if (!dir) continue;
+    try {
+      accessSync(path.join(dir, command), constants.X_OK);
+      return true;
+    } catch {
+      // continue
+    }
+  }
+  return false;
+}
 
 export async function fileExists(filePath: string): Promise<boolean> {
   try {

package/src/lib/opencode-plugin-package.ts

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
+import { PUBLIC_NPM_REGISTRY } from "./public-npm";
 import { getCurrentVersion } from "./update-checker";
 
 export const OPENCODE_PLUGIN_PACKAGE_NAME = "@uniqbit/mate-opencode-plugin";
@@ -35,8 +36,8 @@ export interface WarmPluginCacheResult {
 }
 
 export const opencodePluginCacheDeps = {
-  runInstall: (cwd: string) =>
-    spawnSync("npm", ["install", "--no-audit", "--no-fund", "--silent"], {
+  runInstall: (cwd: string, registry: string) =>
+    spawnSync("npm", ["install", "--no-audit", "--no-fund", "--silent", "--registry", registry], {
       cwd,
       encoding: "utf8" as const,
       stdio: ["ignore", "pipe", "pipe"] as const,
@@ -52,6 +53,7 @@ export const opencodePluginCacheDeps = {
 export async function warmOpenCodePluginCache(
   version: string = getCurrentVersion(),
   env: NodeJS.ProcessEnv = process.env,
+  registry = PUBLIC_NPM_REGISTRY,
 ): Promise<WarmPluginCacheResult> {
   // Escape hatch for tests and intentionally offline environments: skip the
   // pre-fetch entirely instead of attempting a registry install.
@@ -70,7 +72,7 @@ export async function warmOpenCodePluginCache(
       "utf8",
     );
 
-    const result = opencodePluginCacheDeps.runInstall(specDir);
+    const result = opencodePluginCacheDeps.runInstall(specDir, registry);
     if (result.error) {
       return { ok: false, detail: result.error.message };
     }

package/src/lib/orchestrator/adapters/base.ts

@@ -1,8 +1,8 @@
 import { spawn } from "node:child_process";
-import { accessSync, constants } from "node:fs";
 import path from "node:path";
 
 import { version } from "../../../../package.json";
+import { isCommandOnPath } from "../../fs-utils";
 import { frameworkConfig } from "../../../framework";
 import { getReactDoctorBinPath, getWrapperBinPath } from "../../package-paths";
 import {
@@ -229,19 +229,3 @@ export abstract class LaunchAdapter {
     });
   }
 }
-
-function isCommandOnPath(command: string, pathValue: string): boolean {
-  if (!pathValue) return false;
-
-  for (const dir of pathValue.split(path.delimiter)) {
-    if (!dir) continue;
-    try {
-      accessSync(path.join(dir, command), constants.X_OK);
-      return true;
-    } catch {
-      // continue
-    }
-  }
-
-  return false;
-}

package/src/lib/orchestrator/launcher.ts

@@ -81,21 +81,6 @@ export class FrameworkLauncher {
     return (await this.prepare(request)).execute();
   }
 
-  async getAllowedTargets(): Promise<Set<string> | null> {
-    try {
-      const { configStore, workingRepoStore, repositoryId, repository } =
-        await this.resolveConfig();
-      const config = await configStore.load();
-      const store = new CompanionStore(configStore, workingRepoStore);
-      const policy = repository
-        ? resolvePolicyFromConfig(config, [repository], repository.id)
-        : await store.resolvePolicy(repositoryId);
-      return new Set(policy.allowedAgents);
-    } catch {
-      return null;
-    }
-  }
-
   private async resolveLaunchState(request: LaunchRequest): Promise<ResolvedLaunchState> {
     const {
       configStore,

package/src/lib/public-npm.ts

@@ -27,15 +27,33 @@ export const publicNpmDeps = {
   rmSync: fs.rmSync,
 };
 
-function getPublicNpmUserConfig(): string {
-  return `registry=${PUBLIC_NPM_REGISTRY}\n@uniqbit:registry=${PUBLIC_NPM_REGISTRY}\n`;
+function packageNameFromSpec(packageSpec: string): string {
+  const separator = packageSpec.startsWith("@")
+    ? packageSpec.indexOf("@", 1)
+    : packageSpec.indexOf("@");
+  return separator === -1 ? packageSpec : packageSpec.slice(0, separator);
 }
 
-async function withPublicNpmConfig<T>(run: (env: NodeJS.ProcessEnv) => Promise<T>): Promise<T> {
+function getPublicNpmUserConfig(packageName: string, registry: string): string {
+  const scope = packageName.startsWith("@") ? packageName.slice(0, packageName.indexOf("/")) : null;
+  return [`registry=${registry}`, ...(scope ? [`${scope}:registry=${registry}`] : []), ""].join(
+    "\n",
+  );
+}
+
+async function withPublicNpmConfig<T>(
+  packageName: string,
+  registry: string,
+  run: (env: NodeJS.ProcessEnv) => Promise<T>,
+): Promise<T> {
   const tempDir = await publicNpmDeps.mkdtemp(path.join(os.tmpdir(), "mate-public-npm-"));
   const userConfigPath = path.join(tempDir, ".npmrc");
 
-  await publicNpmDeps.writeFile(userConfigPath, getPublicNpmUserConfig(), "utf8");
+  await publicNpmDeps.writeFile(
+    userConfigPath,
+    getPublicNpmUserConfig(packageName, registry),
+    "utf8",
+  );
 
   try {
     return await run({
@@ -47,11 +65,19 @@ async function withPublicNpmConfig<T>(run: (env: NodeJS.ProcessEnv) => Promise<T
   }
 }
 
-function withPublicNpmConfigSync<T>(run: (env: NodeJS.ProcessEnv) => T): T {
+function withPublicNpmConfigSync<T>(
+  packageName: string,
+  registry: string,
+  run: (env: NodeJS.ProcessEnv) => T,
+): T {
   const tempDir = publicNpmDeps.mkdtempSync(path.join(os.tmpdir(), "mate-public-npm-"));
   const userConfigPath = path.join(tempDir, ".npmrc");
 
-  publicNpmDeps.writeFileSync(userConfigPath, getPublicNpmUserConfig(), "utf8");
+  publicNpmDeps.writeFileSync(
+    userConfigPath,
+    getPublicNpmUserConfig(packageName, registry),
+    "utf8",
+  );
 
   try {
     return run({
@@ -63,8 +89,11 @@ function withPublicNpmConfigSync<T>(run: (env: NodeJS.ProcessEnv) => T): T {
   }
 }
 
-export async function fetchPublicPackageVersion(packageName: string): Promise<string> {
-  const { stdout } = await withPublicNpmConfig((env) =>
+export async function fetchPublicPackageVersion(
+  packageName: string,
+  registry = PUBLIC_NPM_REGISTRY,
+): Promise<string> {
+  const { stdout } = await withPublicNpmConfig(packageName, registry, (env) =>
     publicNpmDeps.execFile("npm", ["view", packageName, "version"], {
       timeout: 10_000,
       env,
@@ -74,8 +103,8 @@ export async function fetchPublicPackageVersion(packageName: string): Promise<st
   return stdout.trim();
 }
 
-export function installPublicPackageSync(packageSpec: string) {
-  return withPublicNpmConfigSync((env) =>
+export function installPublicPackageSync(packageSpec: string, registry = PUBLIC_NPM_REGISTRY) {
+  return withPublicNpmConfigSync(packageNameFromSpec(packageSpec), registry, (env) =>
     publicNpmDeps.spawnSync("npm", ["install", "-g", packageSpec], {
       stdio: "inherit",
       env,

package/src/lib/update-checker.ts

@@ -1,9 +1,9 @@
 import os from "node:os";
 import path from "node:path";
 
-import { getActiveDistribution } from "../distribution";
+import { getActiveDistribution, type DistributionUpdateConfig } from "../distribution";
 import { frameworkConfig } from "../framework";
-import { fetchPublicPackageVersion } from "./public-npm";
+import { fetchPublicPackageVersion, PUBLIC_NPM_REGISTRY } from "./public-npm";
 import { YamlFileStore } from "./orchestrator/yaml-file-store";
 
 const parse = (v: string): number[] => v.split(".").slice(0, 3).map(Number);
@@ -34,6 +34,14 @@ export function getCurrentVersion(): string {
   return getActiveDistribution().config.version;
 }
 
+export function getUpdateConfig(): DistributionUpdateConfig {
+  const { name, update } = getActiveDistribution().config;
+  return {
+    packageName: update?.packageName ?? `@uniqbit/${name}`,
+    registry: update?.registry ?? PUBLIC_NPM_REGISTRY,
+  };
+}
+
 export function isCanaryVersion(version: string = getCurrentVersion()): boolean {
   return version.includes("-canary");
 }
@@ -62,7 +70,8 @@ export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Prom
 }
 
 export async function fetchLatestVersion(): Promise<string> {
-  return fetchPublicPackageVersion(`@uniqbit/${frameworkConfig.name}`);
+  const { packageName, registry } = getUpdateConfig();
+  return fetchPublicPackageVersion(packageName, registry);
 }
 
 export function scheduleBackgroundCheck(store: UpdateStateStore): void {

package/src/templates/providers/opencode/opencode.json

@@ -3,12 +3,11 @@
   "compaction": {
     "auto": true,
     "prune": true,
-    "preserve_recent_tokens": 1500,
-    "reserved": 8000
+    "reserved": 15000
   },
   "tool_output": {
-    "max_lines": 200,
-    "max_bytes": 8192
+    "max_lines": 500,
+    "max_bytes": 20000
   },
   "references": {
     "mate": ".."

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

@@ -1,4 +1,3 @@
-import { execFileSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 
@@ -12,18 +11,7 @@ import {
 } from "../utils";
 import { confirm } from "../../../cli/confirm";
 import { frameworkConfig } from "../../../framework";
-
-function defaultIsInstalledViaUvTool(pkgName: string): boolean {
-  try {
-    const output = execFileSync("uv", ["tool", "list"], {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    return output.includes(pkgName);
-  } catch {
-    return false;
-  }
-}
+import { isInstalledViaUvTool } from "../package-managers/uv";
 
 // Storage contract: <companionPath>/.graphify/<repositoryId>/graphify-out/
 export const GRAPHIFY_STORE_SEGMENT = ".graphify";
@@ -336,7 +324,7 @@ export interface GraphifyPluginDeps {
 export function createGraphifyPlugin(deps: GraphifyPluginDeps = {}): CapabilityPlugin {
   const askConfirm = deps.confirm ?? confirm;
   const checkPath = deps.isCommandOnPath ?? isCommandOnPath;
-  const checkUvTool = deps.isInstalledViaUvTool ?? defaultIsInstalledViaUvTool;
+  const checkUvTool = deps.isInstalledViaUvTool ?? isInstalledViaUvTool;
   const runCommand = deps.runCommand ?? runShellCommand;
   const runProviderInstall = deps.runProviderInstall ?? runCommandSilently;
 

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

@@ -1,9 +1,8 @@
-import { execFileSync } from "node:child_process";
-
 import type { CapabilityPlugin, SetupContext } from "../plugin";
 import type { InstallRequirement } from "../install-contract";
 import { isCommandOnPath, runShellCommand, runShellCommandSilently } from "../utils";
 import { confirm } from "../../../cli/confirm";
+import { isInstalledViaUvTool } from "../package-managers/uv";
 
 const HEADROOM_GITIGNORE_ENTRIES = ["# headroom", ".headroom/"];
 
@@ -32,18 +31,6 @@ const RTK_UNINSTALL_COMMANDS: Record<string, string> = {
   opencode: "rtk init -g --uninstall --opencode",
 };
 
-function defaultIsInstalledViaUvTool(pkgName: string): boolean {
-  try {
-    const output = execFileSync("uv", ["tool", "list"], {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    return output.includes(pkgName);
-  } catch {
-    return false;
-  }
-}
-
 type HeadroomDeps = {
   confirm?: typeof confirm;
   isCommandOnPath?: typeof isCommandOnPath;
@@ -57,7 +44,7 @@ type HeadroomDeps = {
 export function createHeadroomPlugin(deps: HeadroomDeps = {}): CapabilityPlugin {
   const askConfirm = deps.confirm ?? confirm;
   const checkPath = deps.isCommandOnPath ?? isCommandOnPath;
-  const checkUvTool = deps.isInstalledViaUvTool ?? defaultIsInstalledViaUvTool;
+  const checkUvTool = deps.isInstalledViaUvTool ?? isInstalledViaUvTool;
   const checkRtkPath = deps.isRtkOnPath ?? defaultIsRtkOnPath;
   const checkBrew = deps.isBrewAvailable ?? defaultIsBrewAvailable;
   const runRtkInstall = deps.runRtkInstallCmd ?? runShellCommand;

package/src/tools/setup/package-managers/uv.ts

@@ -1,8 +1,22 @@
+import { execFileSync } from "node:child_process";
+
 import type { Plugin, SetupContext } from "../plugin";
 import type { InstallRequirement } from "../install-contract";
 import { confirm } from "../../../cli/confirm";
 import { isCommandOnPath, runCommand, runShellCommand } from "../utils";
 
+export function isInstalledViaUvTool(pkgName: string): boolean {
+  try {
+    const output = execFileSync("uv", ["tool", "list"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return output.includes(pkgName);
+  } catch {
+    return false;
+  }
+}
+
 export interface PackageManagerSetupDeps {
   confirm?: typeof confirm;
   isCommandOnPath?: (command: string, pathValue: string) => boolean;

package/src/tools/setup/plugin.ts

@@ -60,6 +60,20 @@ export interface ProviderPlugin extends Plugin {
   hosting?: ProviderHosting;
 }
 
+/**
+ * A CLI subcommand contributed by a plugin. `createMate` mounts each entry on
+ * the distribution binary as `<distribution> cap <namespace> <name>` (the
+ * namespace defaults to the plugin id, overridable via `cliNamespace`),
+ * independent of plugin selection — commands guard their own preconditions
+ * (see `ensureCapabilityEnabled`). Framework `cap` subcommands always win
+ * over plugin namespaces.
+ */
+export interface PluginCliCommand {
+  name: string;
+  description: string;
+  run(argv: string[]): Promise<void>;
+}
+
 export interface Plugin {
   id: string;
   kind: "provider" | "capability" | "packageManager" | "integration" | "root";
@@ -72,6 +86,9 @@ export interface Plugin {
   gitignoreEntries?(ctx: SetupContext): string[];
   persistGitignoreEntries?: boolean;
   getInstallRequirements?(ctx: InstallRequirementContext): InstallRequirement[];
+  cliCommands?: PluginCliCommand[];
+  /** CLI namespace for `cliCommands` under `<distribution> cap`; defaults to `id`. */
+  cliNamespace?: string;
 }
 
 /**

package/src/tools/setup/utils.ts

@@ -35,19 +35,7 @@ export async function pruneEmptyAncestors(dir: string, stopAt: string): Promise<
   }
 }
 
-export function isCommandOnPath(command: string, pathValue: string): boolean {
-  if (!pathValue) return false;
-  for (const dir of pathValue.split(path.delimiter)) {
-    if (!dir) continue;
-    try {
-      accessSync(path.join(dir, command), constants.X_OK);
-      return true;
-    } catch {
-      // continue
-    }
-  }
-  return false;
-}
+export { isCommandOnPath } from "../../lib/fs-utils";
 
 export function resolveCommandOnPath(command: string, pathValue: string): string | undefined {
   if (!pathValue) return undefined;

package/src/lib/lcov-to-cobertura.ts

@@ -1,174 +0,0 @@
-import path from "node:path";
-
-type CoverageLine = {
-  hits: number;
-  lineNumber: number;
-};
-
-type CoverageFile = {
-  filePath: string;
-  lines: CoverageLine[];
-};
-
-type CoberturaOptions = {
-  projectRoot?: string;
-  timestamp?: number;
-};
-
-function escapeXml(value: string): string {
-  return value
-    .replaceAll("&", "&")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&apos;");
-}
-
-function normalizeCoveragePath(filePath: string, projectRoot: string): string {
-  if (!path.isAbsolute(filePath)) {
-    return filePath.split(path.sep).join("/");
-  }
-
-  const relativePath = path.relative(projectRoot, filePath);
-  if (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)) {
-    return relativePath.split(path.sep).join("/");
-  }
-
-  return filePath.split(path.sep).join("/");
-}
-
-function finalizeRecord(
-  records: CoverageFile[],
-  activePath: string | null,
-  activeLines: Map<number, number>,
-  projectRoot: string,
-) {
-  if (!activePath) {
-    return;
-  }
-
-  const lines = [...activeLines.entries()]
-    .toSorted(([left], [right]) => left - right)
-    .map(([lineNumber, hits]) => ({ hits, lineNumber }));
-
-  records.push({
-    filePath: normalizeCoveragePath(activePath, projectRoot),
-    lines,
-  });
-}
-
-export function parseLcov(lcov: string, projectRoot = process.cwd()): CoverageFile[] {
-  const records: CoverageFile[] = [];
-  let activePath: string | null = null;
-  let activeLines = new Map<number, number>();
-
-  for (const rawLine of lcov.split(/\r?\n/)) {
-    if (rawLine.startsWith("SF:")) {
-      finalizeRecord(records, activePath, activeLines, projectRoot);
-      activePath = rawLine.slice(3).trim();
-      activeLines = new Map<number, number>();
-      continue;
-    }
-
-    if (rawLine.startsWith("DA:")) {
-      const [lineNumberText, hitsText] = rawLine.slice(3).split(",");
-      const lineNumber = Number.parseInt(lineNumberText ?? "", 10);
-      const hits = Number.parseInt(hitsText ?? "", 10);
-
-      if (Number.isFinite(lineNumber) && Number.isFinite(hits)) {
-        activeLines.set(lineNumber, hits);
-      }
-      continue;
-    }
-
-    if (rawLine === "end_of_record") {
-      finalizeRecord(records, activePath, activeLines, projectRoot);
-      activePath = null;
-      activeLines = new Map<number, number>();
-    }
-  }
-
-  finalizeRecord(records, activePath, activeLines, projectRoot);
-  return records;
-}
-
-export function lcovToCobertura(
-  lcov: string,
-  { projectRoot = process.cwd(), timestamp = Date.now() }: CoberturaOptions = {},
-): string {
-  const files = parseLcov(lcov, projectRoot);
-  const packages = new Map<string, CoverageFile[]>();
-
-  for (const file of files) {
-    const packageName = path.posix.dirname(file.filePath);
-    const bucket = packages.get(packageName) ?? [];
-    bucket.push(file);
-    packages.set(packageName, bucket);
-  }
-
-  const totalLinesValid = files.reduce((sum, file) => sum + file.lines.length, 0);
-  const totalLinesCovered = files.reduce(
-    (sum, file) => sum + file.lines.filter((line) => line.hits > 0).length,
-    0,
-  );
-  const totalLineRate = totalLinesValid === 0 ? 0 : totalLinesCovered / totalLinesValid;
-
-  const packageXml = [...packages.entries()]
-    .toSorted(([left], [right]) => left.localeCompare(right))
-    .map(([packageName, packageFiles]) => {
-      const packageLinesValid = packageFiles.reduce((sum, file) => sum + file.lines.length, 0);
-      const packageLinesCovered = packageFiles.reduce(
-        (sum, file) => sum + file.lines.filter((line) => line.hits > 0).length,
-        0,
-      );
-      const packageLineRate = packageLinesValid === 0 ? 0 : packageLinesCovered / packageLinesValid;
-
-      const classesXml = packageFiles
-        .toSorted((left, right) => left.filePath.localeCompare(right.filePath))
-        .map((file) => {
-          const fileLinesCovered = file.lines.filter((line) => line.hits > 0).length;
-          const fileLineRate = file.lines.length === 0 ? 0 : fileLinesCovered / file.lines.length;
-          const linesXml = file.lines
-            .map(
-              (line) =>
-                `          <line number="${line.lineNumber}" hits="${line.hits}" branch="false"/>`,
-            )
-            .join("\n");
-
-          return [
-            `      <class name="${escapeXml(path.posix.basename(file.filePath))}" filename="${escapeXml(file.filePath)}" line-rate="${fileLineRate.toFixed(4)}" branch-rate="0" complexity="0">`,
-            "        <methods/>",
-            "        <lines>",
-            linesXml,
-            "        </lines>",
-            "      </class>",
-          ].join("\n");
-        })
-        .join("\n");
-
-      return [
-        `    <package name="${escapeXml(packageName)}" line-rate="${packageLineRate.toFixed(4)}" branch-rate="0" complexity="0">`,
-        "      <classes>",
-        classesXml,
-        "      </classes>",
-        "    </package>",
-      ].join("\n");
-    })
-    .join("\n");
-
-  return [
-    '<?xml version="1.0" encoding="UTF-8"?>',
-    '<!DOCTYPE coverage SYSTEM "http://cobertura.sourceforge.net/xml/coverage-04.dtd">',
-    `<coverage lines-covered="${totalLinesCovered}" lines-valid="${totalLinesValid}" line-rate="${totalLineRate.toFixed(4)}" branches-covered="0" branches-valid="0" branch-rate="0" complexity="0" version="mate-lcov-to-cobertura" timestamp="${Math.floor(
-      timestamp / 1000,
-    )}">`,
-    "  <sources>",
-    "    <source>.</source>",
-    "  </sources>",
-    "  <packages>",
-    packageXml,
-    "  </packages>",
-    "</coverage>",
-    "",
-  ].join("\n");
-}