@uniqbit/mate-core 0.15.1-canary.3 → 0.15.1-canary.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.1-canary.3",
+  "version": "0.15.1-canary.4",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/main.ts

@@ -22,16 +22,13 @@ import { hydrateDynamicPlugins } from "../tools/setup/dynamic-plugins/hydrate";
 import { findPluginCliCommand } from "./plugin-commands";
 import { usage } from "./usage";
 
-export function isInstallRecoveryCommand(command?: string, subcommand?: string): boolean {
-  return (
-    command === "install" ||
-    command === "update" ||
-    command === "doctor" ||
-    command === "help" ||
-    command === "--help" ||
-    command === "-h" ||
-    (command === "companion" && (subcommand === "setup" || subcommand === "link"))
-  );
+export interface GateNeeds {
+  /** Block the command while an enforced update is pending. */
+  updateGuard?: boolean;
+  /** Require an unambiguous companion (selection wizard on ambiguity) before dispatch. */
+  companion?: boolean;
+  /** Require a complete installation (install preflight) before dispatch. */
+  install?: boolean;
 }
 
 export interface MainDeps {
@@ -54,6 +51,11 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
     return;
   }
 
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    console.log(usage());
+    return;
+  }
+
   // Companion-declared plugins register before cap-command detection so
   // their commands route like compiled-in ones (including MCP servers whose
   // command is their own cap subcommand). Diagnostics stay on stderr; a
@@ -65,73 +67,102 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
   // are suppressed for them.
   const isPluginCommand =
     command === "cap" && findPluginCliCommand(subcommand, rest[0]) !== undefined;
-  if (!isPluginCommand) {
-    const updateStore = new UpdateStateStore();
-    scheduleBackgroundCheck(updateStore);
-    if (
-      !isInstallRecoveryCommand(command, subcommand) &&
-      (await enforceUpdateIfRequired(updateStore))
-    ) {
-      process.exitCode = 1;
-      return;
-    }
-    await showUpdateBannerIfAvailable(updateStore);
-  }
-
-  if (!command || command === "help" || command === "--help" || command === "-h") {
-    console.log(usage());
-    return;
-  }
 
-  if (!(await deps.ensureUnambiguousCompanion())) {
-    process.exitCode = 1;
-    return;
-  }
+  // Every dispatch case opens with a gate() call declaring what the command
+  // needs before it may run. Declared gates run in fixed order — update
+  // enforcement, companion selection, install preflight — and a blocked gate
+  // sets the exit code, so callers only need `if (!(await gate(...))) return`.
+  const gate = async (needs: GateNeeds): Promise<boolean> => {
+    if (!isPluginCommand) {
+      const updateStore = new UpdateStateStore();
+      scheduleBackgroundCheck(updateStore);
+      if (needs.updateGuard && (await enforceUpdateIfRequired(updateStore))) {
+        process.exitCode = 1;
+        return false;
+      }
+      await showUpdateBannerIfAvailable(updateStore);
+    }
 
-  if (!isInstallRecoveryCommand(command, subcommand)) {
-    const preflight = await deps.inspectInstallPreflight();
-    if (!preflight.ok) {
-      console.error(
-        `${frameworkCommandName()}: ${preflight.reason ?? "installation is incomplete"}`,
-      );
-      console.error(`Run \`${frameworkCommandName()} install\` before continuing.`);
+    if (needs.companion && !(await deps.ensureUnambiguousCompanion())) {
       process.exitCode = 1;
-      return;
+      return false;
     }
-  }
+
+    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.`);
+        process.exitCode = 1;
+        return false;
+      }
+    }
+
+    return true;
+  };
 
   switch (command) {
     case "install":
+      // Builds a companion-scoped context, so it needs an unambiguous
+      // companion — but must stay runnable when installation is incomplete.
+      if (!(await gate({ companion: true }))) return;
       await runInstallCommand(argv.slice(3));
       return;
     case "artifact":
+      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runArtifactCommand(subcommand, rest);
       return;
     case "companion":
+      switch (subcommand) {
+        // setup/link are recovery paths and must never be gated on the
+        // state they exist to repair.
+        case "setup":
+        case "link":
+          if (!(await gate({}))) return;
+          break;
+        // open/tui consume a companion context.
+        case "open":
+        case "tui":
+          if (!(await gate({ updateGuard: true, companion: true }))) return;
+          break;
+        // list and unknown subcommands (which fail inside the command).
+        default:
+          if (!(await gate({ updateGuard: true }))) return;
+      }
       await runCompanionCommand(subcommand, rest);
       return;
     case "claude":
+      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runLaunchClaudeCommand(argv.slice(3), { directPassthrough: true });
       return;
     case "opencode":
+      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runLaunchOpenCodeCommand(argv.slice(3), { directPassthrough: true });
       return;
     case "report":
+      if (!(await gate({ updateGuard: true }))) return;
       await runReportCommand(argv.slice(3));
       return;
     case "config":
+      if (!(await gate({ updateGuard: true }))) return;
       await runConfigCommand(argv.slice(3));
       return;
     case "doctor":
+      if (!(await gate({}))) return;
       await runDoctorCommand(argv.slice(3));
       return;
     case "cap":
+      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
       await runCapCommand(subcommand, rest);
       return;
     case "update":
+      if (!(await gate({}))) return;
       await runUpdateCommand(argv.slice(3));
       return;
     default:
+      // Unknown commands fail fast: no case matched, so no gate ever ran.
       console.error(`Unknown command: ${command}`);
       console.error(usage());
       process.exitCode = 1;

package/src/templates/capabilities/openspec-cap/mate-v1/schema.yaml

@@ -272,4 +272,5 @@ apply:
   tracks: tasks.md
   instruction: |
     Read context files and work through pending tasks only within the proposal's affected Areas. Mark complete as you go.
+    When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc.
     Pause if you hit blockers or need clarification.

package/src/templates/root/TEMPLATE_AGENTS.md

@@ -8,6 +8,7 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 ## Agent Notes
 
 - Use absolute paths when a tool needs a file path. Do not create literal `$MATE_REPO_PATH` or `$MATE_ARTIFACT_PATH` directories.
+- When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (`$MATE_REPO_PATH`) unless the user explicitly asks for it.
 

package/src/templates/root/TEMPLATE_CLAUDE.md

@@ -8,6 +8,7 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 ## Claude Notes
 
 - Use absolute paths when a tool needs a file path. Do not create literal `$MATE_REPO_PATH` or `$MATE_ARTIFACT_PATH` directories.
+- When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc.
 - Claude Code receives `$MATE_ARTIFACT_PATH` via `--add-dir`; if `@` autocomplete does not show companion artifacts, reference them by absolute path.
 - The root `CLAUDE.md` in the companion repo is intentional and loaded by Mate. Do not create another project-level `CLAUDE.md` in the working repo unless the user explicitly asks for one.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.

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

@@ -37,6 +37,3 @@ 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 installed plugin trees (regenerated by install). */
-export const PLUGIN_DEPENDENCIES_GITIGNORE_ENTRY = `.${FRAMEWORK_NAME}/dependencies/plugins/`;

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

@@ -1,8 +1,6 @@
 import { getActiveDistribution } from "../../../distribution";
-import {
-  PLUGIN_DEPENDENCIES_GITIGNORE_ENTRY,
-  PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY,
-} from "../dynamic-plugins/paths";
+import { FRAMEWORK_NAME } from "../../../framework";
+import { PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY } from "../dynamic-plugins/paths";
 import type { Plugin, SetupContext } from "../plugin";
 
 const MANAGED_START = (name: string) => `# ${name} managed: start`;
@@ -59,14 +57,22 @@ export async function writeManagedGitignoreBlock(
 }
 
 export function collectManagedGitignoreEntries(ctx: SetupContext, plugins: Plugin[]): string[] {
-  const entries = 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 and installed
-  // trees never version; the pin file (plugins.lock.yaml) stays committed and
-  // is deliberately not listed here.
+  // 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 —
+  // version pins live in .mate/config and in code, never in the tree itself.
+  const entries = [
+    "node_modules/",
+    `.${FRAMEWORK_NAME}/dependencies/`,
+    ...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.
   if (ctx.config.plugins?.length) {
-    entries.push(PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY, PLUGIN_DEPENDENCIES_GITIGNORE_ENTRY);
+    entries.push(PLUGIN_LOCAL_OVERRIDES_GITIGNORE_ENTRY);
   }
   return entries;
 }