@uniqbit/mate-core 0.15.1 → 0.15.2-canary.1

package/src/cli/commands/report/types.ts

@@ -36,7 +36,84 @@ export interface ReportData {
   netSpend: number;
 }
 
+export const REPORT_DOCUMENT_VERSION = 1 as const;
+
+export type ReportValue = string | number | boolean | null;
+
+export interface ReportKeyValue {
+  label: string;
+  value: ReportValue;
+}
+
+export interface ReportMetric {
+  label: string;
+  value: ReportValue;
+  detail?: string;
+}
+
+export interface ReportStatus {
+  label: string;
+  status: string;
+  detail?: string;
+}
+
+export interface ReportSectionBase {
+  id: string;
+  title: string;
+}
+
+export interface ReportMetadataSection extends ReportSectionBase {
+  type: "metadata";
+  items: ReportKeyValue[];
+}
+
+export interface ReportMetricsSection extends ReportSectionBase {
+  type: "metrics";
+  items: ReportMetric[];
+}
+
+export interface ReportKeyValueSection extends ReportSectionBase {
+  type: "key-value";
+  items: ReportKeyValue[];
+}
+
+export interface ReportTableSection extends ReportSectionBase {
+  type: "table";
+  columns: string[];
+  rows: ReportValue[][];
+}
+
+export interface ReportStatusesSection extends ReportSectionBase {
+  type: "statuses";
+  items: ReportStatus[];
+}
+
+export interface ReportTextSection extends ReportSectionBase {
+  type: "text";
+  content: string;
+}
+
+export type ReportSection =
+  | ReportMetadataSection
+  | ReportMetricsSection
+  | ReportKeyValueSection
+  | ReportTableSection
+  | ReportStatusesSection
+  | ReportTextSection;
+
+export interface ReportDocument {
+  version: typeof REPORT_DOCUMENT_VERSION;
+  title: string;
+  generatedAt: string;
+  period?: string;
+  context?: string;
+  metadata: ReportKeyValue[];
+  summary: ReportMetric[];
+  sections: ReportSection[];
+}
+
 export interface ReportOptions {
   days: number;
   json: boolean;
+  input?: string;
 }

package/src/cli/main.ts

@@ -51,17 +51,18 @@ 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
+  // ambiguous companion makes this a no-op.
+  await deps.hydrateDynamicPlugins();
+
   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
-  // missing or ambiguous companion makes this a no-op.
-  await deps.hydrateDynamicPlugins();
-
   // 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.

package/src/cli/plugin-commands.ts

@@ -95,11 +95,36 @@ export async function ensureCapabilityEnabled(
   return false;
 }
 
+function formatCommand(
+  distributionName: string,
+  namespace: string,
+  command: PluginCliCommand,
+): string {
+  return `  ${distributionName} cap ${namespace} ${command.name}  ${command.description}`;
+}
+
 function usageFor(plugin: Plugin): string {
   const distributionName = frameworkCommandName();
   const namespace = namespaceOf(plugin);
-  const lines = (plugin.cliCommands ?? []).map(
-    (command) => `  ${distributionName} cap ${namespace} ${command.name}  ${command.description}`,
+  const lines = (plugin.cliCommands ?? []).map((command) =>
+    formatCommand(distributionName, namespace, command),
   );
   return ["Available commands:", ...lines].join("\n");
 }
+
+/**
+ * Cap-command lines contributed by every registered plugin that declares
+ * `cliCommands` (compiled-in or companion-declared/dynamic), formatted as
+ * ` <n> cap <namespace> <name>  <description>`. Used by `usage()` so plugin
+ * commands show up in `mate help` alongside framework builtins.
+ */
+export function pluginCliCommandLines(): string[] {
+  const distributionName = frameworkCommandName();
+  return getActiveDistribution()
+    .registry.getAll()
+    .flatMap((plugin) =>
+      (plugin.cliCommands ?? []).map((command) =>
+        formatCommand(distributionName, namespaceOf(plugin), command),
+      ),
+    );
+}

package/src/cli/usage.ts

@@ -1,5 +1,6 @@
 import { getActiveDistribution } from "../distribution";
 import { FRAMEWORK_NAME, frameworkCommandName } from "../framework";
+import { pluginCliCommandLines } from "./plugin-commands";
 
 export function usage(): string {
   const n = frameworkCommandName();
@@ -17,13 +18,14 @@ export function usage(): string {
     ` ${n} companion tui`,
     ` ${n} artifact finish <change-name> [--type openspec] [--force] [--no-push] [--json]`,
     ` ${n} doctor`,
-    ` ${n} report [--days N] [--json]`,
+    ` ${n} report [--days N] [--input FILE|-] [--json]`,
     ` ${n} config`,
     ` ${n} claude [args...] (use -- --no-git to bypass companion Git sync)`,
     ` ${n} opencode [args...] (use -- --no-git to bypass companion Git sync)`,
     ` ${n} cap openspec <subcommand> [args...]`,
     ` ${n} cap graphify <subcommand> [args...]`,
     ` ${n} cap index [--graphify] [--tokensave]`,
+    ...pluginCliCommandLines(),
     ` ${n} update`,
     ` ${n} update --check`,
     "",

package/src/templates/root/TEMPLATE_AGENTS.md

@@ -8,7 +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
+- 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/tools/setup/capabilities/openspec.ts

@@ -3,7 +3,6 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 
-import { frameworkCommandName } from "../../../framework";
 import { getOpenSpecSchemaSelection } from "../../../lib/orchestrator/setup-compatibilities";
 import { fetchPublicPackageVersion } from "../../../lib/public-npm";
 import { isNewer } from "../../../lib/update-checker";
@@ -18,6 +17,9 @@ import {
   runCommand,
   runCommandSilently,
 } from "../utils";
+import { applyMateSkills, teardownMateSkills } from "../mate";
+
+export { MATE_ARTIFACT_SKILLS, MATE_SKILLS, deployMateSkillDir } from "../mate";
 
 const execFileAsync = promisify(execFileCb);
 
@@ -30,14 +32,8 @@ export const OPENSPEC_SKILLS = [
 
 // Mate-authored skills (not generated by the openspec CLI) that ship alongside the
 // openspec workflow skills and are installed per active provider.
-export const MATE_ARTIFACT_SKILLS = ["mate-artifact-finish"] as const;
 const LEGACY_CLAUDE_STATE_PATTERN = /^mate-artifact-finish\..+\.json$/;
 
-const MATE_SKILLS_SOURCE = path.join(
-  import.meta.dirname,
-  "../../../templates/capabilities/openspec-cap/mate-skills",
-);
-
 const MATE_V1_SCHEMA_SOURCE = path.join(
   import.meta.dirname,
   "../../../templates/capabilities/openspec-cap/mate-v1",
@@ -110,24 +106,14 @@ export async function teardownOpenspecSkills(
   skillsDir: string,
   companionPath: string,
 ): Promise<void> {
-  for (const skill of [...OPENSPEC_SKILLS, ...MATE_ARTIFACT_SKILLS]) {
-    try {
-      await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
-    } catch {
-      /* not present */
-    }
-  }
-  await pruneEmptyAncestors(skillsDir, companionPath);
-}
-
-async function teardownMateOpenspecSkills(skillsDir: string, companionPath: string): Promise<void> {
-  for (const skill of MATE_ARTIFACT_SKILLS) {
+  for (const skill of OPENSPEC_SKILLS) {
     try {
       await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
     } catch {
       /* not present */
     }
   }
+  await teardownMateSkills(skillsDir, companionPath);
   await pruneEmptyAncestors(skillsDir, companionPath);
 }
 
@@ -135,42 +121,13 @@ async function teardownToolRuntime(companionPath: string, tool: OpenSpecTool): P
   await teardownOpenspecSkills(getSkillsDir(companionPath, tool), companionPath);
 }
 
-const MATE_COMMAND_PLACEHOLDER = "{{MATE_COMMAND}}";
-
-// Like mergeDir, but renders the invocation-name placeholder at deploy time.
-// Files without the placeholder are copied byte-identical.
-export async function deployMateSkillDir(src: string, dest: string): Promise<void> {
-  await fs.mkdir(dest, { recursive: true });
-  const entries = await fs.readdir(src, { withFileTypes: true });
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      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, frameworkCommandName()),
-        "utf8",
-      );
-    } else {
-      await fs.copyFile(srcPath, destPath);
-    }
-  }
-}
-
 async function applyMateOpenspecSkills(
   companionPath: string,
   tools: OpenSpecTool[],
 ): Promise<void> {
   for (const tool of tools) {
     const skillsDir = getSkillsDir(companionPath, tool);
-    for (const skill of MATE_ARTIFACT_SKILLS) {
-      await deployMateSkillDir(path.join(MATE_SKILLS_SOURCE, skill), path.join(skillsDir, skill));
-    }
+    await applyMateSkills(skillsDir);
   }
 }
 
@@ -194,7 +151,7 @@ async function reconcileOpenSpecTools(
     await applyMateOpenspecSkills(ctx.companionPath, tools);
   } else {
     for (const tool of tools) {
-      await teardownMateOpenspecSkills(getSkillsDir(ctx.companionPath, tool), ctx.companionPath);
+      await teardownMateSkills(getSkillsDir(ctx.companionPath, tool), ctx.companionPath);
     }
   }
 }
@@ -373,8 +330,12 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     ],
     async apply(ctx) {
       const tools = deriveOpenSpecTools(ctx.activeProviders);
-      if (tools.length > 0 && (await ensureOpenSpecInstalled(ctx, depsWithDefaults))) {
-        await reconcileOpenSpecTools(ctx, depsWithDefaults.runCommand);
+      if (ctx.mode === "setup" || tools.length > 0) {
+        if (await ensureOpenSpecInstalled(ctx, depsWithDefaults)) {
+          if (tools.length > 0) {
+            await reconcileOpenSpecTools(ctx, depsWithDefaults.runCommand);
+          }
+        }
       }
       await reconcileOpenSpecSchema(ctx);
     },

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

@@ -9,10 +9,11 @@ export { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "./tokensave-shared";
 
 export const TOKENSAVE_SUPPORTED_AGENTS = new Set(["claude", "opencode"]);
 export const TOKENSAVE_STORE_DIR = ".tokensave";
+export const TOKENSAVE_MIN_RUST_VERSION = "1.91.0";
 const TOKENSAVE_CLAUDE_MD_MARKER = "## MANDATORY: No Explore Agents When Tokensave Is Available";
 const TOKENSAVE_STORE_EXCLUDE_ENTRY = `${TOKENSAVE_STORE_DIR}/`;
 const TOKENSAVE_BREW_INSTALL_CMD = "brew install aovestdipaperino/tap/tokensave";
-const TOKENSAVE_CARGO_INSTALL_CMD = "cargo install tokensave";
+const TOKENSAVE_CARGO_INSTALL_CMD = "cargo install --locked tokensave";
 const TOKENSAVE_SCOOP_INSTALL_CMD =
   "scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket && scoop install tokensave";
 
@@ -53,6 +54,17 @@ export const tokensaveDeps = {
   async runShellCommand(command: string): Promise<void> {
     await runShellCommand(command);
   },
+  rustcVersion(): TokensaveRunResult {
+    const result = spawnSync("rustc", ["--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+      ok: result.status === 0 && !result.error,
+      stderr: result.stderr ?? "",
+      stdout: result.stdout ?? "",
+    };
+  },
   platform(): NodeJS.Platform {
     return process.platform;
   },
@@ -148,6 +160,22 @@ function installTokensaveAgentIntegrations(providers: string[], cwd: string): vo
   }
 }
 
+function getCargoRustVersionError(): string | undefined {
+  const result = tokensaveDeps.rustcVersion();
+  const version = `${result.stdout}\n${result.stderr}`.match(/\brustc\s+(\d+)\.(\d+)\.(\d+)/);
+  if (!result.ok || !version) {
+    return `TokenSave requires Rust ${TOKENSAVE_MIN_RUST_VERSION} or newer. Install or upgrade Rust via https://rustup.rs.`;
+  }
+
+  const installed = version.slice(1, 4).map(Number);
+  const minimum = TOKENSAVE_MIN_RUST_VERSION.split(".").map(Number);
+  const firstDifference = installed.findIndex((part, index) => part !== minimum[index]);
+  if (firstDifference !== -1 && installed[firstDifference] < minimum[firstDifference]) {
+    return `TokenSave requires Rust ${TOKENSAVE_MIN_RUST_VERSION} or newer, but rustc ${version[1]}.${version[2]}.${version[3]} is installed. Upgrade Rust via https://rustup.rs.`;
+  }
+  return undefined;
+}
+
 function getTokensaveInstallPlan(): { command: string; run: () => Promise<void> } | undefined {
   const pathValue = tokensaveDeps.pathValue();
   const platform = tokensaveDeps.platform();
@@ -169,7 +197,11 @@ function getTokensaveInstallPlan(): { command: string; run: () => Promise<void>
   if (tokensaveDeps.isCommandOnPath("cargo", pathValue)) {
     return {
       command: TOKENSAVE_CARGO_INSTALL_CMD,
-      run: () => tokensaveDeps.runCommand("cargo", ["install", "tokensave"]),
+      run: async () => {
+        const rustVersionError = getCargoRustVersionError();
+        if (rustVersionError) throw new Error(rustVersionError);
+        await tokensaveDeps.runCommand("cargo", ["install", "--locked", "tokensave"]);
+      },
     };
   }
 
@@ -192,9 +224,10 @@ export async function ensureTokensaveInstalled(repoPath: string): Promise<boolea
   process.stdout.write(`tokensave binary not found. Installing with:\n  ${installPlan.command}\n`);
   try {
     await installPlan.run();
-  } catch {
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
     process.stderr.write(
-      `tokensave: install failed - install manually with \`${installPlan.command}\`\n`,
+      `tokensave: install failed${detail} - install manually with \`${installPlan.command}\`\n`,
     );
     return false;
   }

package/src/tools/setup/mate.ts

@@ -0,0 +1,124 @@
+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",
+);
+
+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}}:*)
+license: MIT
+compatibility: Requires the {{MATE_COMMAND}} CLI and the OpenSpec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+Create a report only from structured data supplied by the calling skill. Do not infer missing facts from conversation state.
+
+## Contract
+
+Write a JSON document with this shape:
+
+\`\`\`json
+{
+  "version": 1,
+  "title": "Report title",
+  "generatedAt": "2026-01-01T00:00:00Z",
+  "period": "Optional reporting period",
+  "context": "Optional context",
+  "metadata": [{ "label": "Owner", "value": "acme" }],
+  "summary": [{ "label": "Requests", "value": 42, "detail": "Optional detail" }],
+  "sections": [
+    { "id": "notes", "title": "Notes", "type": "text", "content": "Narrative text." },
+    {
+      "id": "results",
+      "title": "Results",
+      "type": "table",
+      "columns": ["Name", "Value"],
+      "rows": [["Example", 1]]
+    }
+  ]
+}
+\`\`\`
+
+Supported section types are \`metadata\`, \`metrics\`, \`key-value\`, \`table\`, \`statuses\`, and \`text\`. Use only strings, numbers, booleans, and null values. Section IDs must be unique. Validate required fields before invoking the CLI.
+
+## Invocation
+
+1. Serialize the complete document to a temporary file or pipe it to stdin.
+2. Run \`{{MATE_COMMAND}} 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.
+`;
+
+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 });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      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);
+    }
+  }
+}
+
+export async function applyMateSkills(skillsDir: 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",
+      );
+    } else {
+      await deployMateSkillDir(path.join(MATE_SKILLS_SOURCE, skill), destination);
+    }
+  }
+}
+
+export async function teardownMateSkills(skillsDir: string, companionPath: string): Promise<void> {
+  for (const skill of MATE_SKILLS) {
+    try {
+      await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+    } catch {
+      /* not present */
+    }
+  }
+  await pruneEmptyAncestors(skillsDir, companionPath);
+}

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

@@ -64,6 +64,7 @@ export function collectManagedGitignoreEntries(ctx: SetupContext, plugins: Plugi
   const entries = [
     "node_modules/",
     `.${FRAMEWORK_NAME}/dependencies/`,
+    ".mcp.json*",
     ...plugins
       .filter((p) => p.kind !== "root" && (p.isEnabled(ctx.config) || p.persistGitignoreEntries))
       .flatMap((p) => p.gitignoreEntries?.(ctx) ?? []),