@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

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

@@ -93,13 +93,38 @@ export interface ReportTextSection extends ReportSectionBase {
   content: string;
 }
 
+export interface ReportDiagramSectionBase extends ReportSectionBase {
+  type: "diagram";
+}
+
+export interface ReportMermaidDiagramSection extends ReportDiagramSectionBase {
+  mermaid: string;
+  text?: never;
+}
+
+export interface ReportTextDiagramSection extends ReportDiagramSectionBase {
+  text: string;
+  mermaid?: never;
+}
+
+/** Exactly one payload: `mermaid` source drawn by the runtime, or `text` kept as a monospace block. */
+export type ReportDiagramSection = ReportMermaidDiagramSection | ReportTextDiagramSection;
+
+export interface ReportDiffSection extends ReportSectionBase {
+  type: "diff";
+  /** Unified diff as produced by `git diff`. */
+  patch: string;
+}
+
 export type ReportSection =
   | ReportMetadataSection
   | ReportMetricsSection
   | ReportKeyValueSection
   | ReportTableSection
   | ReportStatusesSection
-  | ReportTextSection;
+  | ReportTextSection
+  | ReportDiagramSection
+  | ReportDiffSection;
 
 export interface ReportDocument {
   version: typeof REPORT_DOCUMENT_VERSION;

package/src/cli/commands/shared/companion-selection.ts

@@ -1,35 +1,132 @@
-import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import {
+  CompanionResolver,
+  type CompanionMatch,
+} from "../../../lib/orchestrator/companion-resolver";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
+import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repo-local-registry";
+import { projectWorkingRepositoryBestEffort } from "../../../lib/orchestrator/working-repo-projection";
+import { resolveProjection } from "../../../runtime/projection";
 import { selectCompanion } from "../../companion-selector";
 
 export const launchAmbiguityDeps = {
   resolveCompanionMatches: async (cwd: string) =>
     (await new CompanionResolver(new GlobalConfigStore()).resolveWithDiagnostics(cwd))
       .ambiguousMatches,
+  /**
+   * The resolver reports `ambiguousMatches` as `[]` for an unambiguous link, so
+   * the Linked Companions are that list when populated and the single match
+   * otherwise.
+   */
+  resolveLinkedCompanions: async (cwd: string): Promise<CompanionMatch[]> => {
+    const { match, ambiguousMatches } = await new CompanionResolver(
+      new GlobalConfigStore(),
+    ).resolveWithDiagnostics(cwd);
+    if (ambiguousMatches.length > 0) return ambiguousMatches;
+    return match ? [match] : [];
+  },
   selectCompanion,
+  findRepoLocalLinkedRepository,
+  resolveProjection,
+  projectWorkingRepository: projectWorkingRepositoryBestEffort,
 };
 
+export interface CompanionSelectionOptions {
+  /** Ignore both recorded answers — the launch environment and the projection. */
+  reselect?: boolean;
+  /** Ignore only the projected answer, so an ambiguous repository is asked again. */
+  ignoreProjection?: boolean;
+  /** Outranks the environment, the projection, and the picker. */
+  companion?: string;
+}
+
+function pin(match: Pick<CompanionMatch, "companionPath" | "repositoryId">): void {
+  process.env.MATE_ARTIFACT_PATH = match.companionPath;
+  process.env.MATE_REPO_ID = match.repositoryId;
+}
+
+function reportLinkedCompanions(message: string, matches: CompanionMatch[]): void {
+  process.stderr.write(message);
+  for (const match of matches) {
+    process.stderr.write(`  - ${match.companionPath}\n`);
+  }
+}
+
+/**
+ * Rank 1. Validated against the Linked Companions so a wrap can never record a
+ * companion that does not link the Working Repository.
+ */
+async function pinExplicitCompanion(cwd: string, companion: string): Promise<boolean> {
+  const resolved = path.resolve(companion);
+  const linked = await launchAmbiguityDeps.resolveLinkedCompanions(cwd);
+  const chosen = linked.find((match) => path.resolve(match.companionPath) === resolved);
+  if (!chosen) {
+    reportLinkedCompanions(
+      `${FRAMEWORK_NAME}: ${resolved} does not link this working repo; linked companions are:\n`,
+      linked,
+    );
+    return false;
+  }
+
+  pin(chosen);
+  return true;
+}
+
+/**
+ * Rank 3. Only reached when the link is ambiguous, so `matches` is the full set
+ * of Linked Companions — a projected companion absent from it no longer links
+ * the repository and is ignored rather than pinning a dead path.
+ */
+function projectedCompanion(cwd: string, matches: CompanionMatch[]): CompanionMatch | null {
+  const projected = launchAmbiguityDeps.resolveProjection(cwd);
+  if (!projected) return null;
+
+  const resolved = path.resolve(projected.companionPath);
+  return matches.find((match) => path.resolve(match.companionPath) === resolved) ?? null;
+}
+
+/** Best-effort: a read-only Working Repository warns and the command proceeds. */
+async function recordCompanion(cwd: string, chosen: CompanionMatch): Promise<void> {
+  const repository = await launchAmbiguityDeps.findRepoLocalLinkedRepository(cwd);
+  if (!repository) return;
+
+  await launchAmbiguityDeps.projectWorkingRepository(chosen.companionPath, repository);
+}
+
 /**
  * Pins a companion selection into env vars when the current working repo is
  * linked from multiple companions. Commands that should respect an already
- * selected companion can call this before any context resolution.
+ * selected companion can call this before any context resolution. Resolution
+ * order: explicit companion, launch environment, Projection Root, picker — the
+ * environment above the projection, so no projection can degrade a session Mate
+ * configured. A picked companion is recorded at the Projection Root, so the
+ * question is asked once rather than once per command.
  */
 export async function ensureUnambiguousCompanion(
   cwd: string = process.cwd(),
-  options: { reselect?: boolean } = {},
+  options: CompanionSelectionOptions = {},
 ): Promise<boolean> {
+  if (options.companion) return pinExplicitCompanion(cwd, options.companion);
   if (process.env.MATE_ARTIFACT_PATH && !options.reselect) return true;
 
   const ambiguousMatches = await launchAmbiguityDeps.resolveCompanionMatches(cwd);
   if (ambiguousMatches.length <= 1) return true;
 
+  if (!options.reselect && !options.ignoreProjection) {
+    const projected = projectedCompanion(cwd, ambiguousMatches);
+    if (projected) {
+      pin(projected);
+      return true;
+    }
+  }
+
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    process.stderr.write(
-      "mate: this working repo is linked from multiple companions; re-run in a TTY to choose one, or set MATE_ARTIFACT_PATH.\n",
+    reportLinkedCompanions(
+      `${FRAMEWORK_NAME}: this working repo is linked from multiple companions; re-run in a TTY to choose one, run \`${FRAMEWORK_NAME} wrap --companion <path>\`, or set MATE_ARTIFACT_PATH.\n`,
+      ambiguousMatches,
     );
-    for (const match of ambiguousMatches) {
-      process.stderr.write(`  - ${match.companionPath}\n`);
-    }
     return false;
   }
 
@@ -39,7 +136,7 @@ export async function ensureUnambiguousCompanion(
     return false;
   }
 
-  process.env.MATE_ARTIFACT_PATH = chosen.companionPath;
-  process.env.MATE_REPO_ID = chosen.repositoryId;
+  pin(chosen);
+  await recordCompanion(cwd, chosen);
   return true;
 }

package/src/cli/commands/studio/areas.ts

@@ -0,0 +1,68 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+/**
+ * Inline Area binding a requirement carries in a spec body. Anchored to the
+ * start of its own line, which is where the marker is written: a spec that
+ * merely mentions the marker inside prose or a code span binds no Area by
+ * talking about one.
+ */
+const INLINE_AREA = /^\*\*Area:\*\*[ \t]*`([^`\n]+)`/gm;
+
+function frontmatterAreas(content: string): string[] {
+  if (!content.startsWith("---")) return [];
+  const end = content.indexOf("\n---", 3);
+  if (end < 0) return [];
+  let parsed: unknown;
+  try {
+    parsed = parse(content.slice(3, end));
+  } catch {
+    return [];
+  }
+  if (!parsed || typeof parsed !== "object") return [];
+
+  const document = parsed as { areas?: unknown; scopes?: unknown };
+  const areas = Array.isArray(document.areas)
+    ? document.areas.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  const scoped = Array.isArray(document.scopes)
+    ? document.scopes
+        .map((entry) =>
+          entry && typeof entry === "object" ? (entry as { area?: unknown }).area : undefined,
+        )
+        .filter((area): area is string => typeof area === "string")
+    : [];
+  return [...areas, ...scoped];
+}
+
+/**
+ * Areas one spec binds. No OpenSpec JSON command reports them in bulk — a
+ * per-spec `show --json` would cost one process per spec — so the resolved
+ * spec document is read directly: frontmatter `areas`/`scopes` unioned with the
+ * inline `**Area:**` bindings its requirements carry.
+ */
+export async function readSpecAreas(
+  specsRoot: string,
+  specId: string,
+  readFile: (filePath: string) => Promise<string> = (filePath) => fs.readFile(filePath, "utf8"),
+): Promise<string[]> {
+  let content: string;
+  try {
+    content = await readFile(path.join(specsRoot, specId, "spec.md"));
+  } catch {
+    return [];
+  }
+
+  const areas = new Set(
+    frontmatterAreas(content)
+      .map((area) => area.trim())
+      .filter(Boolean),
+  );
+  for (const match of content.matchAll(INLINE_AREA)) {
+    const area = match[1]?.trim();
+    if (area) areas.add(area);
+  }
+  return [...areas].toSorted((a, b) => a.localeCompare(b));
+}

package/src/cli/commands/studio/index.ts

@@ -0,0 +1,69 @@
+import { FRAMEWORK_NAME } from "../../../framework";
+import { openReportInBrowser } from "../report/delivery";
+import { serveUntilInterrupted, startStudioServer } from "./server";
+
+export interface StudioCommandDeps {
+  startStudioServer?: typeof startStudioServer;
+  serveUntilInterrupted?: typeof serveUntilInterrupted;
+  openInBrowser?: (url: string) => Promise<void>;
+  log?: (message: string) => void;
+  warn?: (message: string) => void;
+}
+
+/**
+ * @command mate studio
+ * @description Serves a local, read-only page over the Companion Repositories
+ * registered on this machine — the workflow drawn from each companion's
+ * resolved schema with its OpenSpec state on it — and opens the platform
+ * browser at it. Runs in the foreground on an operating-system-assigned
+ * loopback port and dies with the process: no daemon, no stop command, and no
+ * state written anywhere.
+ * @remarks Takes no arguments and resolves no Repository Link, so it runs from
+ * any directory.
+ */
+export async function runStudioCommand(
+  argv: string[] = [],
+  deps: StudioCommandDeps = {},
+): Promise<void> {
+  const log = deps.log ?? ((message: string) => process.stdout.write(`${message}\n`));
+  const warn = deps.warn ?? ((message: string) => process.stderr.write(`${message}\n`));
+
+  if (argv.length > 0) {
+    warn(`${FRAMEWORK_NAME}: \`studio\` takes no arguments; unrecognized: ${argv.join(" ")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const start = deps.startStudioServer ?? startStudioServer;
+  const serve = deps.serveUntilInterrupted ?? serveUntilInterrupted;
+  const open = deps.openInBrowser ?? openReportInBrowser;
+
+  let server;
+  try {
+    server = start();
+  } catch (error) {
+    warn(
+      `${FRAMEWORK_NAME}: studio could not bind a port: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  log(server.url);
+  log("Press Ctrl+C to stop.");
+
+  try {
+    await open(server.url);
+  } catch (error) {
+    warn(
+      `${FRAMEWORK_NAME}: studio could not open a browser: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    warn(`${FRAMEWORK_NAME}: open ${server.url} manually; the server keeps serving.`);
+  }
+
+  await serve(server);
+}

package/src/cli/commands/studio/inventory.ts

@@ -0,0 +1,55 @@
+import {
+  collectWorkspaceInventory,
+  type CompanionInventoryHealth,
+  type PairingInventoryHealth,
+} from "../../../lib/orchestrator/workspace-inventory";
+
+export interface StudioInventoryPairing {
+  repositoryId: string;
+  repositoryPath: string;
+  health: PairingInventoryHealth;
+  ambiguous: boolean;
+}
+
+export interface StudioInventoryCompanion {
+  path: string;
+  health: CompanionInventoryHealth;
+  diagnostic?: string;
+  pairings: StudioInventoryPairing[];
+}
+
+export interface StudioInventory {
+  companions: StudioInventoryCompanion[];
+}
+
+export interface StudioInventoryDeps {
+  collectWorkspaceInventory?: typeof collectWorkspaceInventory;
+}
+
+/**
+ * Companion-first projection of the machine-wide workspace inventory. Reads
+ * only the aggregate the workspace surface already resolves — health,
+ * ambiguity, and duplicate collapsing stay owned there.
+ */
+export async function collectStudioInventory(
+  deps: StudioInventoryDeps = {},
+): Promise<StudioInventory> {
+  const collect = deps.collectWorkspaceInventory ?? collectWorkspaceInventory;
+  const inventory = await collect();
+
+  return {
+    companions: inventory.companions.map((companion) => ({
+      path: companion.path,
+      health: companion.health,
+      ...(companion.diagnostic ? { diagnostic: companion.diagnostic } : {}),
+      pairings: inventory.pairings
+        .filter((pairing) => pairing.companionPath === companion.path)
+        .map((pairing) => ({
+          repositoryId: pairing.repository.id,
+          repositoryPath: pairing.repository.path,
+          health: pairing.health,
+          ambiguous: pairing.ambiguous,
+        })),
+    })),
+  };
+}

package/src/cli/commands/studio/mate-inventory.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import path from "node:path";
+
+export interface StudioSkillInventory {
+  claude: string[];
+  opencode: string[];
+  agents: string[];
+}
+
+const SKILL_DIRS = {
+  claude: ".claude",
+  opencode: ".opencode",
+  agents: ".agents",
+} as const;
+
+async function skillNamesAt(companionPath: string, runtimeDir: string): Promise<string[]> {
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(path.join(companionPath, runtimeDir, "skills"), {
+      withFileTypes: true,
+    });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .toSorted();
+}
+
+/**
+ * Reports every skill directory in each Agent Runtime and the shared Agents tree.
+ */
+export async function collectSkillInventory(companionPath: string): Promise<StudioSkillInventory> {
+  const [claude, opencode, agents] = await Promise.all([
+    skillNamesAt(companionPath, SKILL_DIRS.claude),
+    skillNamesAt(companionPath, SKILL_DIRS.opencode),
+    skillNamesAt(companionPath, SKILL_DIRS.agents),
+  ]);
+  return { claude, opencode, agents };
+}

package/src/cli/commands/studio/openspec-cli.ts

@@ -0,0 +1,198 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+import { getWrapperBinPath } from "../../../lib/package-paths";
+
+export interface OpenSpecFailure {
+  command: string;
+  reason: string;
+}
+
+export type OpenSpecResult<T> = { ok: true; value: T } | { ok: false; failure: OpenSpecFailure };
+
+export interface OpenSpecRunOutput {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+}
+
+export interface OpenSpecCliDeps {
+  wrapperPath?: () => string;
+  run?: (bin: string, args: string[], companionPath: string) => Promise<OpenSpecRunOutput>;
+}
+
+/** The Capability whose CLI produces the workflow a companion's changes move through. */
+export const WORKFLOW_CAPABILITY_ID = "openspec";
+
+/** Upper bound on one collection call; a hung wrapper must not hold a request open. */
+const OPENSPEC_TIMEOUT_MS = 60_000;
+
+export function openSpecWrapperPath(): string {
+  return path.join(getWrapperBinPath(), "openspec");
+}
+
+/**
+ * The wrapper resolves its OpenSpec root from `MATE_ARTIFACT_PATH`, so the
+ * companion is selected by environment rather than by cwd — the studio server
+ * has no Repository Link to walk up from.
+ */
+function runOpenSpecWrapper(
+  bin: string,
+  args: string[],
+  companionPath: string,
+): Promise<OpenSpecRunOutput> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, {
+      cwd: companionPath,
+      env: { ...process.env, MATE_ARTIFACT_PATH: companionPath },
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: OPENSPEC_TIMEOUT_MS,
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.once("error", reject);
+    child.once("close", (code) => resolve({ stdout, stderr, code }));
+  });
+}
+
+function firstJsonValue(stdout: string): unknown {
+  const start = stdout.search(/[[{]/);
+  if (start < 0) return undefined;
+  try {
+    return JSON.parse(stdout.slice(start));
+  } catch {
+    return undefined;
+  }
+}
+
+function reasonFor(output: OpenSpecRunOutput): string {
+  const detail = (output.stderr.trim() || output.stdout.trim()).split("\n").slice(-3).join("; ");
+  const status = `exit code ${output.code ?? "unknown"}`;
+  return detail ? `${status}: ${detail}` : status;
+}
+
+/**
+ * Reads one OpenSpec JSON command for a Companion Repository. Never throws:
+ * every failure — spawn, exit status, unparseable output — becomes a typed
+ * failure so one unreadable companion cannot take the server down.
+ */
+export async function readOpenSpecJson<T>(
+  companionPath: string,
+  args: string[],
+  deps: OpenSpecCliDeps = {},
+): Promise<OpenSpecResult<T>> {
+  const bin = (deps.wrapperPath ?? openSpecWrapperPath)();
+  const command = `openspec ${args.join(" ")}`;
+  const run = deps.run ?? runOpenSpecWrapper;
+
+  let output: OpenSpecRunOutput;
+  try {
+    output = await run(bin, args, companionPath);
+  } catch (error) {
+    return {
+      ok: false,
+      failure: { command, reason: error instanceof Error ? error.message : String(error) },
+    };
+  }
+
+  // `validate` exits non-zero when it finds issues, and its JSON report is
+  // exactly what Studio wants in that case — parseable stdout wins over status.
+  const parsed = firstJsonValue(output.stdout);
+  if (parsed !== undefined) return { ok: true, value: parsed as T };
+
+  if (output.code !== 0) return { ok: false, failure: { command, reason: reasonFor(output) } };
+  return { ok: false, failure: { command, reason: `${command} did not return JSON` } };
+}
+
+export interface OpenSpecChangeListEntry {
+  name: string;
+  completedTasks?: number;
+  totalTasks?: number;
+  status?: string;
+  lastModified?: string;
+}
+
+export interface OpenSpecChangeList {
+  changes?: OpenSpecChangeListEntry[];
+}
+
+export interface OpenSpecSpecListEntry {
+  id: string;
+  requirementCount?: number;
+}
+
+export interface OpenSpecSpecList {
+  specs?: OpenSpecSpecListEntry[];
+}
+
+export interface OpenSpecArtifactStatus {
+  id: string;
+  status?: string;
+  outputPath?: string;
+  requires?: string[];
+}
+
+export interface OpenSpecChangeStatusEntry {
+  changeName: string;
+  schemaName?: string;
+  isComplete?: boolean;
+  isPlanningComplete?: boolean;
+  planningHome?: { root?: string; defaultSchema?: string };
+  artifacts?: OpenSpecArtifactStatus[];
+}
+
+export interface OpenSpecAllChangeStatus {
+  changes?: OpenSpecChangeStatusEntry[];
+}
+
+export interface OpenSpecValidationItem {
+  id: string;
+  type?: string;
+  valid?: boolean;
+  issues?: { level?: string; path?: string; message?: string }[];
+}
+
+export interface OpenSpecValidationReport {
+  items?: OpenSpecValidationItem[];
+}
+
+export function listChanges(
+  companionPath: string,
+  deps: OpenSpecCliDeps = {},
+): Promise<OpenSpecResult<OpenSpecChangeList>> {
+  return readOpenSpecJson(companionPath, ["list", "--json"], deps);
+}
+
+export function listSpecs(
+  companionPath: string,
+  deps: OpenSpecCliDeps = {},
+): Promise<OpenSpecResult<OpenSpecSpecList>> {
+  return readOpenSpecJson(companionPath, ["list", "--specs", "--json"], deps);
+}
+
+export function readAllChangeStatus(
+  companionPath: string,
+  deps: OpenSpecCliDeps = {},
+): Promise<OpenSpecResult<OpenSpecAllChangeStatus>> {
+  return readOpenSpecJson(companionPath, ["status", "--all", "--json"], deps);
+}
+
+/**
+ * `validate --json` without a selector prints help and exits non-zero, so the
+ * whole-root report is the `--all` form.
+ */
+export function validateAll(
+  companionPath: string,
+  deps: OpenSpecCliDeps = {},
+): Promise<OpenSpecResult<OpenSpecValidationReport>> {
+  return readOpenSpecJson(companionPath, ["validate", "--all", "--json"], deps);
+}