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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.3",
+  "version": "0.15.4-canary.3",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [
@@ -14,7 +14,8 @@
     ".": "./src/index.ts",
     "./plugins": "./src/plugins.ts",
     "./runtime": "./src/runtime/index.ts",
-    "./opencode": "./src/opencode/index.ts"
+    "./opencode": "./src/opencode/index.ts",
+    "./tui": "./src/tui.ts"
   },
   "publishConfig": {
     "access": "public",

package/src/cli/commands/companion/hub.ts

@@ -0,0 +1,99 @@
+import readline from "node:readline/promises";
+
+import {
+  addHubMember,
+  discoverHubSource,
+  initializeCompanionHub,
+  syncHub,
+  updateHubPlugins,
+} from "../../../lib/orchestrator/companion-hub";
+import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
+
+function positionalArgs(argv: string[]): string[] {
+  const values: string[] = [];
+  const valueFlags = new Set(["id", "path", "url", "companion", "ref"]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index]!;
+    if (!value.startsWith("--")) {
+      values.push(value);
+      continue;
+    }
+    if (valueFlags.has(value.slice(2))) index += 1;
+  }
+  return values;
+}
+
+function flagValue(argv: string[], name: string): string | undefined {
+  const index = argv.indexOf(`--${name}`);
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+
+async function selectRegisteredCompanion(): Promise<string> {
+  const companions = await new GlobalConfigStore().list();
+  if (companions.length === 0) throw new Error("No registered companions are available.");
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("hub add requires a source path or Git URL outside a TTY.");
+  }
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log("Registered companions:");
+    companions.forEach((candidate, index) => console.log(`  ${index + 1}. ${candidate}`));
+    const answer = await prompt.question("Select a companion: ");
+    const selected = companions[Number.parseInt(answer, 10) - 1];
+    if (!selected) throw new Error("Invalid companion selection.");
+    return selected;
+  } finally {
+    prompt.close();
+  }
+}
+
+async function runHubInit(argv: string[]): Promise<void> {
+  const folder = positionalArgs(argv)[0] ?? process.cwd();
+  const hubPath = await initializeCompanionHub(folder);
+  console.log(`Initialized companion hub: ${hubPath}`);
+}
+
+async function runHubAdd(argv: string[]): Promise<void> {
+  const sourceArg =
+    positionalArgs(argv)[0] ?? flagValue(argv, "url") ?? flagValue(argv, "companion");
+  const source = discoverHubSource(sourceArg ?? (await selectRegisteredCompanion()));
+  const ref = flagValue(argv, "ref");
+  if (ref && source.kind === "git") source.ref = ref;
+  const member = await addHubMember(process.cwd(), source, {
+    id: flagValue(argv, "id"),
+    memberPath: flagValue(argv, "path"),
+  });
+  console.log(`Added hub member ${member.id}: ${member.path}`);
+}
+
+async function runHubSync(argv: string[]): Promise<void> {
+  const results = await syncHub(process.cwd());
+  const plugins = await updateHubPlugins(process.cwd());
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify({ companions: results, plugins }));
+    return;
+  }
+  for (const result of results) console.log(`${result.id}: ${result.status} (${result.message})`);
+  for (const plugin of plugins) {
+    const detail = plugin.status === "failed" ? `: ${plugin.error ?? "failed"}` : "";
+    console.log(`hub plugin ${plugin.package}: ${plugin.status}${detail}`);
+  }
+  if (plugins.some((plugin) => plugin.status === "failed")) process.exitCode = 1;
+}
+
+export async function runHubCommand(argv: string[]): Promise<void> {
+  const [subcommand, ...rest] = argv;
+  switch (subcommand) {
+    case "init":
+      await runHubInit(rest);
+      return;
+    case "add":
+      await runHubAdd(rest);
+      return;
+    case "sync":
+      await runHubSync(rest);
+      return;
+    default:
+      throw new Error("Usage: mate hub <init|add|sync>");
+  }
+}

package/src/cli/commands/companion/tui.ts

@@ -2,12 +2,14 @@ import { spawn } from "node:child_process";
 import { accessSync } from "node:fs";
 
 import { getActiveDistribution } from "../../../distribution";
+import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-context";
 import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repo-local-registry";
 import { ensureUnambiguousCompanion } from "../launch/shared";
 
 export function renderBanner(repoPath: string, companionPath: string): string {
-  const { name, version } = getActiveDistribution().config;
+  const { version } = getActiveDistribution().config;
+  const name = FRAMEWORK_NAME;
   const lines = [`${name} v${version}`, "", `repo: ${repoPath}`, `${name}: ${companionPath}`];
   const contentWidth = Math.max(...lines.map((l) => l.length));
   const pad = (text: string) => `│ ${text.padEnd(contentWidth)} │`;

package/src/cli/commands/doctor.ts

@@ -1,14 +1,13 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { FRAMEWORK_NAME, frameworkConfig } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import { getActiveDistribution } from "../../distribution";
 import { CompanionResolver } from "../../lib/orchestrator/companion-resolver";
 import { CompanionStore, resolvePolicyFromConfig } from "../../lib/orchestrator/companion-store";
 import { ConfigStore } from "../../lib/orchestrator/config-store";
 import { checkEngineRequirement } from "../../lib/orchestrator/engine-guard";
 import { GlobalConfigStore } from "../../lib/orchestrator/global-config-store";
-import { migrateConfigDir } from "../../lib/orchestrator/migration";
 import { findRepoLocalLinkedRepository } from "../../lib/orchestrator/repo-local-registry";
 import type { CapabilityConfig, FrameworkConfig } from "../../lib/orchestrator/types";
 import { WorkingRepoStore } from "../../lib/orchestrator/working-repo-store";
@@ -43,8 +42,6 @@ function storesForCompanion(companionPath: string): CompanionStores {
 
 async function hasLocalCompanionConfig(cwd: string): Promise<boolean> {
   const localDir = path.join(cwd, `.${FRAMEWORK_NAME}`);
-  const localLegacyDirs = frameworkConfig.legacyNames.map((name) => path.join(cwd, `.${name}`));
-  await migrateConfigDir(localDir, localLegacyDirs);
 
   try {
     await fs.access(path.join(localDir, "config", "framework.yaml"));
@@ -74,10 +71,10 @@ function renderEngineRequirement(
 // diagnostic; foreign distribution keys are ignored entirely.
 function printEngineRequirement(config: FrameworkConfig): void {
   const distribution = getActiveDistribution().config;
-  if (!config.engines?.[distribution.name]) return;
+  if (!config.engines?.[FRAMEWORK_NAME]) return;
   printSection(
     "Version Requirement",
-    renderEngineRequirement(config, distribution.name, distribution.version),
+    renderEngineRequirement(config, FRAMEWORK_NAME, distribution.version),
   );
 }
 

package/src/cli/commands/install.ts

@@ -1,5 +1,5 @@
 import { confirm } from "../confirm";
-import { frameworkCommandName } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import {
   buildInstallPlan,
   inspectInstallPlan,
@@ -14,13 +14,15 @@ import {
   installDeclaredPlugins,
   type PluginInstallResult,
 } from "../../tools/setup/dynamic-plugins/install";
+import { registryConfigHint } from "../../tools/setup/dynamic-plugins/registry-hint";
 
 export function reportPluginInstallResults(results: PluginInstallResult[]): void {
   for (const result of results) {
     if (result.status === "failed") {
       process.stderr.write(
-        `${frameworkCommandName()}: plugin "${result.package}" failed to install: ${result.error ?? "unknown error"}\n`,
+        `${FRAMEWORK_NAME}: plugin "${result.package}" failed to install: ${result.error ?? "unknown error"}\n`,
       );
+      process.stderr.write(`${registryConfigHint(result.package)}\n`);
     } else if (result.status === "installed") {
       console.log(`  installed plugin ${result.package}@${result.resolvedVersion}`);
     }
@@ -72,7 +74,7 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
       const ok = await confirm("Install the missing requirements? [y/N] ");
       if (!ok) {
         process.stderr.write(
-          `Installation declined. Run \`${frameworkCommandName()} install --yes\` to continue.\n`,
+          `Installation declined. Run \`${FRAMEWORK_NAME} install --yes\` to continue.\n`,
         );
         process.exitCode = 1;
         return false;
@@ -83,7 +85,7 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     printPlanText(plan);
     if (!skipConfirm) {
       process.stderr.write(
-        `${frameworkCommandName()}: installation requires confirmation in a TTY. Re-run with \`${frameworkCommandName()} install --yes\`.\n`,
+        `${FRAMEWORK_NAME}: installation requires confirmation in a TTY. Re-run with \`${FRAMEWORK_NAME} install --yes\`.\n`,
       );
       process.exitCode = 1;
       return false;
@@ -103,11 +105,11 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   if (!execution.ok) {
     for (const result of execution.results.filter((item) => item.status === "failed")) {
       process.stderr.write(
-        `${frameworkCommandName()}: ${result.id} failed: ${result.error ?? "unknown error"}\n`,
+        `${FRAMEWORK_NAME}: ${result.id} failed: ${result.error ?? "unknown error"}\n`,
       );
     }
     process.stderr.write(
-      `Installation is incomplete. Re-run \`${frameworkCommandName()} install\` after remediation.\n`,
+      `Installation is incomplete. Re-run \`${FRAMEWORK_NAME} install\` after remediation.\n`,
     );
     process.exitCode = 1;
     return false;
@@ -118,11 +120,9 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {
     process.stderr.write(
-      `${frameworkCommandName()}: installation completed but companion reconciliation failed: ${error instanceof Error ? error.message : String(error)}\n`,
-    );
-    process.stderr.write(
-      `Installation is incomplete. Re-run \`${frameworkCommandName()} install\`.\n`,
+      `${FRAMEWORK_NAME}: installation completed but companion reconciliation failed: ${error instanceof Error ? error.message : String(error)}\n`,
     );
+    process.stderr.write(`Installation is incomplete. Re-run \`${FRAMEWORK_NAME} install\`.\n`);
     process.exitCode = 1;
     return false;
   }

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

@@ -1,4 +1,4 @@
-import { frameworkCommandName } from "../../../framework";
+import { FRAMEWORK_NAME } from "../../../framework";
 import { FrameworkLauncher } from "../../../lib/orchestrator/launcher";
 import {
   LaunchPreflightError,
@@ -43,7 +43,7 @@ export function parseLaunchArgs(argv: string[]): ParsedLaunchArgs | null {
   const agentArgs = separatorIndex >= 0 ? argv.slice(separatorIndex + 1) : [];
 
   for (const arg of optionArgs) {
-    process.stderr.write(`${frameworkCommandName()}: unknown launch option: ${arg}\n`);
+    process.stderr.write(`${FRAMEWORK_NAME}: unknown launch option: ${arg}\n`);
     process.exitCode = 1;
     return null;
   }
@@ -109,7 +109,7 @@ export async function runLaunchToolCommand(
 
     if (error instanceof ToolNotAllowedError) {
       process.stderr.write(
-        `${frameworkCommandName()}: \`${tool}\` is disallowed by active repository policy.\n`,
+        `${FRAMEWORK_NAME}: \`${tool}\` is disallowed by active repository policy.\n`,
       );
       process.exitCode = 1;
       return;
@@ -117,7 +117,7 @@ export async function runLaunchToolCommand(
 
     if (error instanceof RepositoryNotSelectedError) {
       process.stderr.write(`${error.message}\n`);
-      process.stderr.write(`Run \`${frameworkCommandName()} companion link\` first.\n`);
+      process.stderr.write(`Run \`${FRAMEWORK_NAME} companion link\` first.\n`);
       process.exitCode = 1;
       return;
     }

package/src/cli/commands/plugin/install.ts

@@ -0,0 +1,94 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import { resolveInstallContext } from "../../../lib/install";
+import { ConfigStore } from "../../../lib/orchestrator/config-store";
+import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { hydrateDynamicPlugins } from "../../../tools/setup/dynamic-plugins/hydrate";
+import {
+  installDeclaredPlugins,
+  type PluginInstallDeps,
+} from "../../../tools/setup/dynamic-plugins/install";
+import { reportPluginInstallResults } from "../install";
+
+export function parsePackageSpec(spec: string): { package: string; version: string } {
+  const atIndex = spec.startsWith("@") ? spec.indexOf("@", 1) : spec.indexOf("@");
+  if (atIndex === -1) return { package: spec, version: "latest" };
+  return { package: spec.slice(0, atIndex), version: spec.slice(atIndex + 1) };
+}
+
+function withDeclaration(
+  declarations: PluginDeclaration[],
+  packageName: string,
+  version: string,
+): PluginDeclaration[] {
+  const existing = declarations.find((declaration) => declaration.package === packageName);
+  if (existing?.version === version) return declarations;
+  if (!existing) return [...declarations, { package: packageName, version }];
+  return declarations.map((declaration) =>
+    declaration.package === packageName ? { ...declaration, version } : declaration,
+  );
+}
+
+export interface PluginInstallCommandDeps {
+  cwd?: string;
+  installDeps?: PluginInstallDeps;
+}
+
+/**
+ * @command mate plugin install <package>[@version]
+ * @description Declares `<package>` in the companion's `framework.yaml`
+ * `plugins:` list (adding it, or updating its version if already declared)
+ * and installs it immediately into the shared workspace, the same way
+ * `mate install` would on its next run.
+ */
+export async function runPluginInstallCommand(
+  argv: string[],
+  deps: PluginInstallCommandDeps = {},
+): Promise<boolean> {
+  const spec = argv[0];
+  if (!spec) {
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: usage: ${FRAMEWORK_NAME} plugin install <package>[@version]\n`,
+    );
+    process.exitCode = 1;
+    return false;
+  }
+  const { package: packageName, version } = parsePackageSpec(spec);
+
+  const context = await resolveInstallContext(deps.cwd ?? process.cwd());
+  if (context.kind === "ambiguous") {
+    process.stderr.write(`${context.message}\n`);
+    process.exitCode = 1;
+    return false;
+  }
+  if (context.kind !== "companion" || !context.companionPath) {
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: \`plugin install\` requires a companion context; run it from inside a linked working repository.\n`,
+    );
+    process.exitCode = 1;
+    return false;
+  }
+
+  const configPath = path.join(
+    context.companionPath,
+    `.${FRAMEWORK_NAME}`,
+    "config",
+    "framework.yaml",
+  );
+  const store = new ConfigStore(configPath);
+  const nextPlugins = withDeclaration(context.config.plugins ?? [], packageName, version);
+  if (nextPlugins !== context.config.plugins) {
+    await store.save({ ...context.config, plugins: nextPlugins });
+  }
+
+  const results = await installDeclaredPlugins(
+    context.companionPath,
+    nextPlugins,
+    deps.installDeps,
+  );
+  reportPluginInstallResults(results);
+  await hydrateDynamicPlugins({ companionPath: context.companionPath });
+
+  return results.find((result) => result.package === packageName)?.status !== "failed";
+}

package/src/cli/commands/plugin/plugin.ts

@@ -0,0 +1,17 @@
+import { usage } from "../../usage";
+import { runPluginInstallCommand } from "./install";
+
+export async function runPluginCommand(
+  subcommand: string | undefined,
+  argv: string[],
+): Promise<void> {
+  switch (subcommand) {
+    case "install":
+      await runPluginInstallCommand(argv);
+      return;
+    default:
+      console.error(`Unknown plugin command: ${subcommand ?? ""}`);
+      console.error(usage());
+      process.exitCode = 1;
+  }
+}

package/src/cli/commands/setup.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 
-import { FRAMEWORK_NAME, frameworkCommandName } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import { ConfigStore, defaultConfig } from "../../lib/orchestrator/config-store";
 import { executeSetup } from "../../tools/setup";
 import {
@@ -98,7 +98,7 @@ async function runSetupFlow(
     if (await checkWorkingRepo(cwd)) {
       process.stderr.write(
         `Warning: this directory looks like a working repository (project files detected).\n` +
-          `Initializing it as a ${frameworkCommandName()} companion here may not be what you want.\n`,
+          `Initializing it as a ${FRAMEWORK_NAME} companion here may not be what you want.\n`,
       );
     }
     const ok = await askConfirm("Initialize this directory as a Mate companion repository? [y/N] ");

package/src/cli/commands/update.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
-import { frameworkCommandName } from "../../framework";
+import { FRAMEWORK_NAME } from "../../framework";
 import {
   OPENCODE_PLUGIN_PACKAGE_NAME,
   warmOpenCodePluginCache,
@@ -20,7 +20,7 @@ type InstallResult = ReturnType<typeof installPublicPackageSync>;
 function writeNpmOnlyRecoveryMessage(): void {
   const { packageName, registry } = getUpdateConfig();
   process.stderr.write(
-    `${frameworkCommandName()}: self-update is only supported for npm-installed Mate.\n`,
+    `${FRAMEWORK_NAME}: self-update is only supported for npm-installed Mate.\n`,
   );
   if (packageName.startsWith("@uniqbit/")) {
     process.stderr.write(
@@ -87,16 +87,14 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   try {
     latest = await updateCommandDeps.fetchLatestVersion();
   } catch {
-    process.stderr.write(
-      `${frameworkCommandName()}: could not reach registry to check for updates\n`,
-    );
+    process.stderr.write(`${FRAMEWORK_NAME}: could not reach registry to check for updates\n`);
     process.exitCode = 1;
     return;
   }
 
   if (checkOnly) {
     if (updateCommandDeps.isNewer(latest, current)) {
-      console.log(`${frameworkCommandName()}: update available (${current} → ${latest})`);
+      console.log(`${FRAMEWORK_NAME}: update available (${current} → ${latest})`);
       process.exitCode = 1;
     } else {
       console.log("Up to date.");
@@ -127,11 +125,11 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
       process.stderr.write(
-        `${frameworkCommandName()}: npm is required for self-update but was not found on PATH\n`,
+        `${FRAMEWORK_NAME}: npm is required for self-update but was not found on PATH\n`,
       );
     } else {
       process.stderr.write(
-        `${frameworkCommandName()}: could not verify the npm installation used for self-update\n`,
+        `${FRAMEWORK_NAME}: could not verify the npm installation used for self-update\n`,
       );
     }
     writeNpmOnlyRecoveryMessage();
@@ -148,7 +146,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   const result = updateCommandDeps.installLatest(latest);
   if (result.status !== 0 || result.error) {
     process.stderr.write(
-      `${frameworkCommandName()}: upgrade command exited with status ${result.status ?? 1}\n`,
+      `${FRAMEWORK_NAME}: upgrade command exited with status ${result.status ?? 1}\n`,
     );
     process.exitCode = 1;
     return;
@@ -163,7 +161,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   if (!warmed.ok) {
     process.stderr.write(
       [
-        `${frameworkCommandName()}: could not pre-fetch ${OPENCODE_PLUGIN_PACKAGE_NAME}@${latest} for OpenCode.`,
+        `${FRAMEWORK_NAME}: could not pre-fetch ${OPENCODE_PLUGIN_PACKAGE_NAME}@${latest} for OpenCode.`,
         "The next managed OpenCode launch will download it (requires registry access).",
         ...(warmed.detail ? [`Details: ${warmed.detail}`] : []),
       ].join("\n") + "\n",
@@ -173,7 +171,7 @@ export async function runUpdateCommand(argv: string[]): Promise<void> {
   const postInstall = updateCommandDeps.runPostInstall(skipConfirm);
   if (postInstall.status !== 0 || postInstall.error) {
     process.stderr.write(
-      `\nUpgraded to ${latest}, but installation is incomplete. Run \`${frameworkCommandName()} install\`.\n`,
+      `\nUpgraded to ${latest}, but installation is incomplete. Run \`${FRAMEWORK_NAME} install\`.\n`,
     );
     process.exitCode = 1;
     return;

package/src/cli/main.ts

@@ -1,5 +1,5 @@
 import { getActiveDistribution } from "../distribution";
-import { frameworkCommandName } from "../framework";
+import { FRAMEWORK_NAME } from "../framework";
 import {
   enforceUpdateIfRequired,
   scheduleBackgroundCheck,
@@ -9,10 +9,12 @@ import {
 import { runArtifactCommand } from "./commands/artifact/artifact";
 import { runCapCommand } from "./commands/cap";
 import { runCompanionCommand } from "./commands/companion/companion";
+import { runHubCommand } from "./commands/companion/hub";
 import { runConfigCommand } from "./commands/config";
 import { runDoctorCommand } from "./commands/doctor";
 import { runLaunchClaudeCommand } from "./commands/launch/claude";
 import { runLaunchOpenCodeCommand } from "./commands/launch/opencode";
+import { runPluginCommand } from "./commands/plugin/plugin";
 import { runReportCommand } from "./commands/report";
 import { runUpdateCommand } from "./commands/update";
 import { runInstallCommand } from "./commands/install";
@@ -51,10 +53,10 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
     return;
   }
 
-  // Companion-declared plugins register before cap-command detection and
-  // before help text is printed, so their commands route like compiled-in
-  // ones (including MCP servers whose command is their own cap subcommand)
-  // and show up in `mate help`. Diagnostics stay on stderr; a missing or
+  // Dynamic plugins register before cap-command detection and before help
+  // text is printed, so their commands route like compiled-in ones
+  // (including MCP servers whose command is their own cap subcommand) and
+  // show up in `mate help`. Diagnostics stay on stderr; a missing or
   // ambiguous companion makes this a no-op.
   await deps.hydrateDynamicPlugins();
 
@@ -92,10 +94,8 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
     if (needs.install) {
       const preflight = await deps.inspectInstallPreflight();
       if (!preflight.ok) {
-        console.error(
-          `${frameworkCommandName()}: ${preflight.reason ?? "installation is incomplete"}`,
-        );
-        console.error(`Run \`${frameworkCommandName()} install\` before continuing.`);
+        console.error(`${FRAMEWORK_NAME}: ${preflight.reason ?? "installation is incomplete"}`);
+        console.error(`Run \`${FRAMEWORK_NAME} install\` before continuing.`);
         process.exitCode = 1;
         return false;
       }
@@ -111,6 +111,13 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       if (!(await gate({ companion: true }))) return;
       await runInstallCommand(argv.slice(3));
       return;
+    case "plugin":
+      // Declares into framework.yaml and installs on the spot, so it needs
+      // the same gating as `install` — an unambiguous companion, but must
+      // stay runnable when installation is otherwise incomplete.
+      if (!(await gate({ companion: true }))) return;
+      await runPluginCommand(subcommand, rest);
+      return;
     case "artifact":
       if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runArtifactCommand(subcommand, rest);
@@ -123,6 +130,11 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
         case "link":
           if (!(await gate({}))) return;
           break;
+        // Hub commands establish and operate on a local hub root directly;
+        // they must not require a linked working repository or installation.
+        case "hub":
+          if (!(await gate({ updateGuard: true }))) return;
+          break;
         // open/tui consume a companion context.
         case "open":
         case "tui":
@@ -134,6 +146,10 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       }
       await runCompanionCommand(subcommand, rest);
       return;
+    case "hub":
+      if (!(await gate({ updateGuard: true }))) return;
+      await runHubCommand(subcommand ? [subcommand, ...rest] : []);
+      return;
     case "claude":
       if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runLaunchClaudeCommand(argv.slice(3), { directPassthrough: true });

package/src/cli/plugin-commands.ts

@@ -1,5 +1,5 @@
 import { getActiveDistribution } from "../distribution";
-import { frameworkCommandName } from "../framework";
+import { FRAMEWORK_NAME } from "../framework";
 import { resolveInstallContext } from "../lib/install";
 import type { FrameworkConfig } from "../lib/orchestrator/types";
 import type { Plugin, PluginCliCommand } from "../tools/setup/plugin";
@@ -86,7 +86,7 @@ export async function ensureCapabilityEnabled(
   const loadConfig = deps.loadConfig ?? (async () => (await resolveInstallContext()).config);
   if (plugin?.isEnabled(await loadConfig())) return true;
 
-  const name = frameworkCommandName();
+  const name = FRAMEWORK_NAME;
   console.error(
     `${name}: the "${pluginId}" capability is not enabled for this companion. ` +
       `Enable it via \`${name} companion setup\`.`,
@@ -104,7 +104,7 @@ function formatCommand(
 }
 
 function usageFor(plugin: Plugin): string {
-  const distributionName = frameworkCommandName();
+  const distributionName = FRAMEWORK_NAME;
   const namespace = namespaceOf(plugin);
   const lines = (plugin.cliCommands ?? []).map((command) =>
     formatCommand(distributionName, namespace, command),
@@ -119,7 +119,7 @@ function usageFor(plugin: Plugin): string {
  * commands show up in `mate help` alongside framework builtins.
  */
 export function pluginCliCommandLines(): string[] {
-  const distributionName = frameworkCommandName();
+  const distributionName = FRAMEWORK_NAME;
   return getActiveDistribution()
     .registry.getAll()
     .flatMap((plugin) =>

package/src/cli/usage.ts

@@ -1,13 +1,13 @@
 import { getActiveDistribution } from "../distribution";
-import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
+import { FRAMEWORK_NAME } from "../framework";
 import { pluginCliCommandLines } from "./plugin-commands";
 
 export function usage(): string {
-  const n = frameworkCommandName();
+  const n = FRAMEWORK_NAME;
   const packageName =
     getActiveDistribution().config.update?.packageName ?? `@uniqbit/${FRAMEWORK_NAME}`;
   return [
-    `${n.charAt(0).toUpperCase() + n.slice(1)} CLI (${packageName})`,
+    `Mate CLI (${packageName})`,
     "",
     "Commands:",
     ` ${n} install [--yes]`,
@@ -16,6 +16,9 @@ export function usage(): string {
     ` ${n} companion list`,
     ` ${n} companion open`,
     ` ${n} companion tui`,
+    ` ${n} hub init [folder]`,
+    ` ${n} hub add [source] [--id ID] [--path PATH]`,
+    ` ${n} hub sync [--json] (companions + hub plugins)`,
     ` ${n} artifact finish <change-name> [--type openspec] [--force] [--no-push] [--json]`,
     ` ${n} doctor`,
     ` ${n} report [--days N] [--input FILE|-] [--json]`,
@@ -25,6 +28,7 @@ export function usage(): string {
     ` ${n} cap openspec <subcommand> [args...]`,
     ` ${n} cap graphify <subcommand> [args...]`,
     ` ${n} cap index [--graphify] [--tokensave]`,
+    ` ${n} plugin install <package>[@version]`,
     ...pluginCliCommandLines(),
     ` ${n} update`,
     ` ${n} update --check`,

package/src/distribution.ts

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