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

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/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);
     }
   }
 }

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) ?? []),