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

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

@@ -1,8 +1,9 @@
 import fs from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { FRAMEWORK_NAME, frameworkCommandName } from "../../../framework";
+import { FRAMEWORK_NAME } from "../../../framework";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
 import type { Plugin } from "../plugin";
 import { resolveEffectivePluginConfig } from "./config-resolution";
@@ -12,14 +13,9 @@ import {
   type CreatePlugin,
   type PluginHost,
 } from "./host";
-import { pluginPackageRoot } from "./paths";
-import type { PluginPin } from "./pin-store";
+import { dynamicPluginsWorkspaceRoot, pluginPackageRoot } from "./paths";
 
 interface PluginManifest {
-  version?: string;
-  main?: string;
-  module?: string;
-  exports?: unknown;
   mate?: { pluginApiVersion?: unknown };
 }
 
@@ -35,38 +31,17 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function commandName(): string {
-  try {
-    return frameworkCommandName();
-  } catch {
-    return FRAMEWORK_NAME;
-  }
-}
-
-function resolveEntryFromExports(exportsField: unknown): string | undefined {
-  if (typeof exportsField === "string") return exportsField;
-  if (!isRecord(exportsField)) return undefined;
-  const dot = "." in exportsField ? exportsField["."] : exportsField;
-  if (typeof dot === "string") return dot;
-  if (!isRecord(dot)) return undefined;
-  for (const condition of ["bun", "import", "default", "require"]) {
-    const candidate = dot[condition];
-    if (typeof candidate === "string") return candidate;
-    if (isRecord(candidate) && typeof candidate.default === "string") return candidate.default;
-  }
-  return undefined;
-}
-
 /**
- * Loads one declared plugin from its installed tree: pin verification, API
- * version gate before import, dynamic import, factory resolution, effective
- * config, factory invocation. Every failure class returns a single warning
- * instead of throwing, so one broken plugin never takes down the CLI.
+ * Loads one declared plugin from the shared workspace: installed-presence
+ * check, API version gate before import, entry-point resolution via the
+ * shared workspace's own module resolver, dynamic import, factory
+ * resolution, effective config, factory invocation. Every failure class
+ * returns a single warning instead of throwing, so one broken plugin never
+ * takes down the CLI.
  */
 export async function loadDynamicPlugin(
   companionPath: string,
   declaration: PluginDeclaration,
-  pins: PluginPin[],
   deps: DynamicPluginLoadDeps = {},
 ): Promise<DynamicPluginLoadResult> {
   const name = declaration.package;
@@ -80,27 +55,7 @@ export async function loadDynamicPlugin(
   } catch {
     return {
       ok: false,
-      warning: `plugin "${name}" is not installed; run \`${commandName()} install\`.`,
-    };
-  }
-
-  const pin = pins.find((candidate) => candidate.package === name);
-  if (!pin) {
-    return {
-      ok: false,
-      warning: `plugin "${name}" has no recorded pin; run \`${commandName()} install\`.`,
-    };
-  }
-  if (pin.declaredVersion !== declaration.version) {
-    return {
-      ok: false,
-      warning: `plugin "${name}" declares version "${declaration.version}" but was pinned from "${pin.declaredVersion}"; run \`${commandName()} install\`.`,
-    };
-  }
-  if (manifest.version !== pin.resolvedVersion) {
-    return {
-      ok: false,
-      warning: `plugin "${name}" has version ${manifest.version ?? "unknown"} installed but ${pin.resolvedVersion} pinned; run \`${commandName()} install\`.`,
+      warning: `plugin "${name}" is not installed; run \`${FRAMEWORK_NAME} install\`.`,
     };
   }
 
@@ -121,9 +76,19 @@ export async function loadDynamicPlugin(
     };
   }
 
-  const entryRelative =
-    resolveEntryFromExports(manifest.exports) ?? manifest.module ?? manifest.main ?? "index.js";
-  const entryPath = path.resolve(packageRoot, entryRelative);
+  let entryPath: string;
+  try {
+    const workspaceRequire = createRequire(
+      pathToFileURL(path.join(dynamicPluginsWorkspaceRoot(companionPath), "package.json")),
+    );
+    entryPath = workspaceRequire.resolve(name);
+  } catch (error) {
+    return {
+      ok: false,
+      warning: `plugin "${name}" could not be resolved: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
   const importModule =
     deps.importModule ??
     ((specifier: string) => import(specifier) as Promise<Record<string, unknown>>);

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

@@ -2,34 +2,20 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 
-/** Flattens an npm package name into a single directory segment. */
-export function sanitizePluginDirName(packageName: string): string {
-  return packageName.replace(/^@/, "").replace(/\//g, "-");
+/** Shared workspace root: one package.json + node_modules for every declared plugin. */
+export function dynamicPluginsWorkspaceRoot(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "plugins");
 }
 
-export function dynamicPluginsRoot(companionPath: string): string {
-  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "dependencies", "plugins");
-}
-
-/** Per-plugin install workspace holding a private package.json and node_modules. */
-export function pluginInstallDir(companionPath: string, packageName: string): string {
-  return path.join(dynamicPluginsRoot(companionPath), sanitizePluginDirName(packageName));
-}
-
-/** Root of the installed plugin package itself. */
+/** Root of one installed plugin package inside the shared workspace's node_modules. */
 export function pluginPackageRoot(companionPath: string, packageName: string): string {
   return path.join(
-    pluginInstallDir(companionPath, packageName),
+    dynamicPluginsWorkspaceRoot(companionPath),
     "node_modules",
     ...packageName.split("/"),
   );
 }
 
-/** Committed pin file recording resolved plugin versions. */
-export function pluginPinFilePath(companionPath: string): string {
-  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "plugins.lock.yaml");
-}
-
 /** Gitignored per-machine override file deep-merged over committed plugin config. */
 export function pluginLocalOverridesPath(companionPath: string): string {
   return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "plugins.local.yaml");
@@ -37,3 +23,6 @@ export function pluginLocalOverridesPath(companionPath: string): string {
 
 /** Companion-relative gitignore entry for the local override file. */
 export const PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY = `.${FRAMEWORK_NAME}/config/plugins.local.yaml`;
+
+/** Companion-relative gitignore entry for the shared workspace's local, never-committed registry credentials. */
+export const PLUGIN_WORKSPACE_NPMRC_GITIGNORE_ENTRY = `.${FRAMEWORK_NAME}/plugins/.npmrc`;

package/src/tools/setup/dynamic-plugins/registry-hint.ts

@@ -0,0 +1,14 @@
+/**
+ * A generic, actionable hint printed on install failure — never guesses at
+ * the actual registry URL/host. Private registries stay a plain, standard
+ * npm operation: a one-time `npm config set --global`, or (since the shared
+ * plugin workspace is a real npm project) a project-local, gitignored
+ * `.npmrc` dropped directly in it — either is picked up by `npm install`
+ * with nothing Mate-injected.
+ */
+export function registryConfigHint(packageName: string): string {
+  const scope = packageName.startsWith("@") ? packageName.split("/")[0] : undefined;
+  return scope
+    ? `If "${scope}" lives in a private registry, configure it once with:\n  npm config set "${scope}:registry" "<registry-url>" --global\n  npm config set "//<registry-host>/:_authToken" "<token>" --global`
+    : `If this package lives in a private registry, configure it once via \`npm config set\` (see the npm docs for scoped registries).`;
+}

package/src/tools/setup/mate.ts

@@ -1,13 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { frameworkCommandName } from "../../framework";
 import { pruneEmptyAncestors } from "./utils";
 
 export const MATE_ARTIFACT_SKILLS = ["mate-artifact-finish"] as const;
 export const MATE_SKILLS = ["mate-artifact-finish", "mate-create-report"] as const;
 
-const MATE_COMMAND_PLACEHOLDER = "{{MATE_COMMAND}}";
 const MATE_SKILLS_SOURCE = path.join(
   import.meta.dirname,
   "../../templates/capabilities/openspec-cap/mate-skills",
@@ -16,9 +14,9 @@ const MATE_SKILLS_SOURCE = path.join(
 const MATE_CREATE_REPORT_SKILL = `---
 name: mate-create-report
 description: Create a browser-first Mate report from an explicit structured ReportDocument. Use when a skill needs to present supplied metrics, tables, statuses, metadata, or narrative text.
-allowed-tools: Bash({{MATE_COMMAND}}:*)
+allowed-tools: Bash(mate:*)
 license: MIT
-compatibility: Requires the {{MATE_COMMAND}} CLI and the OpenSpec capability enabled.
+compatibility: Requires the mate CLI and the OpenSpec capability enabled.
 metadata:
   author: mate
   version: "1.0"
@@ -57,22 +55,14 @@ Supported section types are \`metadata\`, \`metrics\`, \`key-value\`, \`table\`,
 ## Invocation
 
 1. Serialize the complete document to a temporary file or pipe it to stdin.
-2. Run \`{{MATE_COMMAND}} report --input <file-or->\`.
+2. Run \`mate report --input <file-or->\`.
 3. Add \`--json\` when the caller needs normalized JSON instead of browser delivery.
 
 The default path writes self-contained HTML to a unique OS temporary directory and opens it in the default browser. The report includes a visible "Print / Save as PDF" control that calls the browser's native print dialog. If HTML delivery fails, the CLI warns on stderr and emits the complete report document as JSON on stdout.
 
-The built-in \`{{MATE_COMMAND}} report\` path collects Mate usage data and adapts it to the same contract and renderer.
+The built-in \`mate report\` path collects Mate usage data and adapts it to the same contract and renderer.
 `;
 
-function currentMateCommand(): string {
-  try {
-    return frameworkCommandName();
-  } catch {
-    return "mate";
-  }
-}
-
 export async function deployMateSkillDir(src: string, dest: string): Promise<void> {
   await fs.mkdir(dest, { recursive: true });
   const entries = await fs.readdir(src, { withFileTypes: true });
@@ -83,31 +73,38 @@ export async function deployMateSkillDir(src: string, dest: string): Promise<voi
       await deployMateSkillDir(srcPath, destPath);
       continue;
     }
-    const content = await fs.readFile(srcPath, "utf8");
-    if (content.includes(MATE_COMMAND_PLACEHOLDER)) {
-      await fs.writeFile(
-        destPath,
-        content.replaceAll(MATE_COMMAND_PLACEHOLDER, currentMateCommand()),
-        "utf8",
-      );
-    } else {
-      await fs.copyFile(srcPath, destPath);
-    }
+    await fs.copyFile(srcPath, destPath);
+  }
+}
+
+const DEFAULT_MATE_SKILLS_BUCKET = "agents";
+
+/**
+ * A skill's source lives under a provider bucket so its folder name always
+ * matches its `name:` frontmatter: `<tool>/<skill>/` when that tool needs its
+ * own behavior (e.g. Claude Code always confirms before `mate artifact
+ * finish` pushes, since a push is a shared-state action), falling back to
+ * `agents/<skill>/` — the shared default every other tool (e.g. opencode,
+ * which pushes automatically) uses.
+ */
+async function resolveMateSkillSource(skill: string, tool: string): Promise<string> {
+  const providerDir = path.join(MATE_SKILLS_SOURCE, tool, skill);
+  try {
+    await fs.access(providerDir);
+    return providerDir;
+  } catch {
+    return path.join(MATE_SKILLS_SOURCE, DEFAULT_MATE_SKILLS_BUCKET, skill);
   }
 }
 
-export async function applyMateSkills(skillsDir: string): Promise<void> {
+export async function applyMateSkills(skillsDir: string, tool: string): Promise<void> {
   for (const skill of MATE_SKILLS) {
     const destination = path.join(skillsDir, skill);
     if (skill === "mate-create-report") {
       await fs.mkdir(destination, { recursive: true });
-      await fs.writeFile(
-        path.join(destination, "SKILL.md"),
-        MATE_CREATE_REPORT_SKILL.replaceAll(MATE_COMMAND_PLACEHOLDER, currentMateCommand()),
-        "utf8",
-      );
+      await fs.writeFile(path.join(destination, "SKILL.md"), MATE_CREATE_REPORT_SKILL, "utf8");
     } else {
-      await deployMateSkillDir(path.join(MATE_SKILLS_SOURCE, skill), destination);
+      await deployMateSkillDir(await resolveMateSkillSource(skill, tool), destination);
     }
   }
 }

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

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

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

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

package/src/tools/setup/providers/claude.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 { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import { getWrapperBinPath } from "../../../lib/package-paths";
 import type { FrameworkConfig } from "../../../lib/orchestrator/types";
@@ -57,11 +57,7 @@ const MANAGED_HOOK_MARKERS = [
 // every file. Claude Code ignores `Glob()` rules for file-permission checks
 // (only Read/Edit rules gate file tools), so no Glob entry is emitted.
 function getBaseManagedPermissionEntries(companionPath: string): string[] {
-  return [
-    `Bash(${frameworkCommandName()}:*)`,
-    `Read(${companionPath}/**)`,
-    `Edit(${companionPath}/**)`,
-  ];
+  return [`Bash(${FRAMEWORK_NAME}:*)`, `Read(${companionPath}/**)`, `Edit(${companionPath}/**)`];
 }
 
 const LEGACY_MANAGED_PERMISSION_ENTRIES = [
@@ -80,14 +76,14 @@ function getCapabilityPermissionEntries(): Record<string, string[]> {
       "Skill(openspec-archive-change)",
       "Skill(mate-artifact-finish)",
       "Bash(openspec:*)",
-      `Bash(${frameworkCommandName()} cap graphify:*)`,
+      `Bash(${FRAMEWORK_NAME} cap graphify:*)`,
       `Bash(${path.join(wrapperBinPath, "openspec")}:*)`,
     ],
     rtk: ["Bash(rtk:*)"],
     graphify: [
       "Skill(graphify)",
       "Bash(graphify:*)",
-      `Bash(${frameworkCommandName()} cap graphify:*)`,
+      `Bash(${FRAMEWORK_NAME} cap graphify:*)`,
       `Bash(${path.join(wrapperBinPath, "graphify")}:*)`,
     ],
     "react-doctor": [
@@ -296,6 +292,22 @@ function buildManagedClaudeSettings(
       },
       ...(hooks.PostToolUse ?? []),
     ];
+    // Catch-all: an archive that the PostToolUse nudge never matched (a human
+    // running the command outside Claude, an unmatched command shape) still
+    // gets caught here before the session ends, by checking the archive dir
+    // against finish tags directly rather than guessing from command text.
+    hooks.Stop = [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: `sh "${companionPath}/.claude/hooks/mate-artifact-finish.sh"`,
+            timeout: 10,
+          },
+        ],
+      },
+      ...(hooks.Stop ?? []),
+    ];
   }
   if (reactDoctorEnabled) {
     // Record edits cheaply, then scan once when the edited turn finishes.

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,
@@ -18,7 +18,6 @@ import { getSetupProvidersRoot, getSetupRootTemplates } from "./utils";
 // 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",
@@ -244,9 +243,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",
   );

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 [

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";

package/src/tools/setup/dynamic-plugins/pin-store.ts

@@ -1,30 +0,0 @@
-import { YamlFileStore } from "../../../lib/orchestrator/yaml-file-store";
-import { pluginPinFilePath } from "./paths";
-
-/** Committed record of one declared plugin's resolved install. */
-export interface PluginPin {
-  package: string;
-  declaredVersion: string;
-  resolvedVersion: string;
-  integrity?: string;
-}
-
-export interface PluginPinFile {
-  plugins: PluginPin[];
-}
-
-export class PluginPinStore extends YamlFileStore<PluginPinFile> {
-  constructor(companionPath: string) {
-    super(pluginPinFilePath(companionPath));
-  }
-
-  override async load(): Promise<PluginPinFile> {
-    const parsed = await super.load();
-    return { plugins: Array.isArray(parsed?.plugins) ? parsed.plugins : [] };
-  }
-
-  protected onMissing(): Promise<PluginPinFile> {
-    // The pin file appears only once install records a resolved plugin.
-    return Promise.resolve({ plugins: [] });
-  }
-}