@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

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

@@ -51,10 +51,16 @@ export interface ReportMetric {
   detail?: string;
 }
 
+export const REPORT_STATUS_TONES = ["ok", "warn", "error", "info", "neutral"] as const;
+
+export type ReportStatusTone = (typeof REPORT_STATUS_TONES)[number];
+
 export interface ReportStatus {
   label: string;
   status: string;
   detail?: string;
+  /** Presentation tone; inferred from `status` when absent. */
+  tone?: ReportStatusTone;
 }
 
 export interface ReportSectionBase {
@@ -88,13 +94,21 @@ export interface ReportStatusesSection extends ReportSectionBase {
   items: ReportStatus[];
 }
 
+export const REPORT_TEXT_FORMATS = ["plain", "markdown"] as const;
+
+export type ReportTextFormat = (typeof REPORT_TEXT_FORMATS)[number];
+
 export interface ReportTextSection extends ReportSectionBase {
   type: "text";
   content: string;
+  /** `plain` (default) keeps the text verbatim; `markdown` renders the safe subset. */
+  format?: ReportTextFormat;
 }
 
 export interface ReportDiagramSectionBase extends ReportSectionBase {
   type: "diagram";
+  /** Markdown note rendered beneath the visual. */
+  caption?: string;
 }
 
 export interface ReportMermaidDiagramSection extends ReportDiagramSectionBase {
@@ -114,6 +128,8 @@ export interface ReportDiffSection extends ReportSectionBase {
   type: "diff";
   /** Unified diff as produced by `git diff`. */
   patch: string;
+  /** Markdown note rendered beneath the visual. */
+  caption?: string;
 }
 
 export type ReportSection =

package/src/cli/commands/setup.ts

@@ -9,7 +9,7 @@ import {
 } from "../../lib/orchestrator/setup-preflight";
 import {
   getSetupSelectionsFromConfig,
-  applyOpenSpecSchemaSelection,
+  keepCapabilitySettings,
 } from "../../lib/orchestrator/setup-compatibilities";
 import { confirm } from "../confirm";
 import { selectCompanion } from "../companion-selector";
@@ -19,7 +19,6 @@ import {
   parseCapabilities,
   parseGitMode,
   parseFlags,
-  parseOpenSpecSchema,
   parsePackageManagers,
 } from "../parse-flags";
 
@@ -59,11 +58,10 @@ export async function runSetupCommand(argv: string[]): Promise<void> {
  * via `setup.execute` and prints a summary table of allowed agents, package managers,
  * and capabilities.
  * @flags
- * - `--agents <list>` — parsed via `parseAllowedAgents`.
- * - `--package-managers <list>` — parsed via `parsePackageManagers`.
- * - `--capabilities <list>` — parsed via `parseCapabilities`.
- * - `--openspec-schema <value>` — parsed via `parseOpenSpecSchema`.
- * - `--git-mode <value>` — parsed via `parseGitMode`.
+ * - `--allowed-agent <agent>` — repeatable; parsed via `parseAllowedAgents`.
+ * - `--package-manager <name>` — repeatable; parsed via `parsePackageManagers`.
+ * - `--capability <name>` — repeatable; parsed via `parseCapabilities`.
+ * - `--git-mode <auto|default>` — parsed via `parseGitMode`.
  * @remarks When any flag above is present, the whole selection is treated as
  * explicit and the interactive picker is skipped.
  */
@@ -142,13 +140,11 @@ async function runSetupFlow(
   const flagAllowedAgents = parseAllowedAgents(flags);
   const flagPackageManagers = parsePackageManagers(flags);
   const flagCapabilities = parseCapabilities(flags);
-  const flagOpenSpecSchema = parseOpenSpecSchema(flags);
   const flagGitMode = parseGitMode(flags);
   const hasExplicitSelections =
     flagAllowedAgents !== undefined ||
     flagPackageManagers !== undefined ||
     flagCapabilities !== undefined ||
-    flagOpenSpecSchema !== undefined ||
     flagGitMode !== undefined;
 
   const currentSelections =
@@ -164,12 +160,8 @@ async function runSetupFlow(
     ? {
         allowedAgents: flagAllowedAgents ?? currentSelections.allowedAgents,
         packageManagers: flagPackageManagers ?? currentSelections.packageManagers,
-        capabilities: applyOpenSpecSchemaSelection(
-          flagCapabilities ?? currentSelections.capabilities,
-          flagOpenSpecSchema,
-        ),
+        capabilities: flagCapabilities ?? currentSelections.capabilities,
         git: flagGitMode ?? currentSelections.selectedGitMode,
-        selectedOpenSpecSchema: flagOpenSpecSchema ?? currentSelections.selectedOpenSpecSchema,
         selectedGitMode: flagGitMode ?? currentSelections.selectedGitMode,
       }
     : await selectCompatibilities({ initialSelections: currentSelections });
@@ -183,7 +175,7 @@ async function runSetupFlow(
     {
       allowedAgents: selections.allowedAgents,
       packageManagers: selections.packageManagers,
-      capabilities: selections.capabilities,
+      capabilities: keepCapabilitySettings(selections.capabilities, currentSelections.capabilities),
       git: selections.selectedGitMode,
     },
     { cwd: targetCwd },

package/src/cli/commands/studio/client-asset.ts

@@ -0,0 +1,16 @@
+/** Where Studio serves its own client script: one fixed name, never mapped to a path. */
+export const STUDIO_CLIENT_ROUTE = "/studio/client.js";
+
+/** `null` for any name but the fixed one, so a request never maps to a file. */
+export async function studioClientAsset(pathname: string): Promise<Response | null> {
+  if (pathname !== STUDIO_CLIENT_ROUTE) return null;
+  // Loaded on request, so the CLI's startup never reads the built script.
+  const { STUDIO_CLIENT_BUNDLE } = await import("./views/studio-client.generated");
+  return new Response(STUDIO_CLIENT_BUNDLE, {
+    headers: {
+      "content-type": "text/javascript; charset=utf-8",
+      "cache-control": "no-cache",
+      "x-content-type-options": "nosniff",
+    },
+  });
+}

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

@@ -1,7 +1,4 @@
-import { spawn } from "node:child_process";
-import path from "node:path";
-
-import { getWrapperBinPath } from "../../../lib/package-paths";
+import { runOpenSpec, type OpenSpecRun, type RunOpenSpec } from "../../../lib/openspec-cli";
 
 export interface OpenSpecFailure {
   command: string;
@@ -10,60 +7,16 @@ export interface OpenSpecFailure {
 
 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>;
+  run?: RunOpenSpec;
 }
 
 /** 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. */
+/** Upper bound on one collection call; a hung CLI must not hold a request open. */
 const OPENSPEC_TIMEOUT_MS = 60_000;
 
-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;
@@ -74,29 +27,28 @@ function firstJsonValue(stdout: string): unknown {
   }
 }
 
-function reasonFor(output: OpenSpecRunOutput): string {
+function reasonFor(output: OpenSpecRun): 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.
+ * Reads one OpenSpec JSON command, run in the 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;
+  const run = deps.run ?? runOpenSpec;
 
-  let output: OpenSpecRunOutput;
+  let output: OpenSpecRun;
   try {
-    output = await run(bin, args, companionPath);
+    output = await run(args, { cwd: companionPath, timeout: OPENSPEC_TIMEOUT_MS });
   } catch (error) {
     return {
       ok: false,

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

@@ -5,6 +5,8 @@ export const STUDIO_HOSTNAME = "127.0.0.1";
 export const VAULT_DIR_ROUTE = "/api/vault/dir";
 /** Name-filter matches over the whole listed tree, as an HTML fragment. */
 export const VAULT_FILTER_ROUTE = "/api/vault/filter";
+/** The open file's breadcrumb and pane as an HTML fragment, for opening a file in place. */
+export const VAULT_PANE_ROUTE = "/api/vault/pane";
 /** Server-sent listing generations: a newer one marks the displayed tree stale. */
 export const VAULT_CHANGES_ROUTE = "/api/vault/changes";
 

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

@@ -18,6 +18,7 @@ export const VIEW_PARAM = "view";
 export const REFRESH_PARAM = "refresh";
 export const FILE_PARAM = "path";
 export const DIR_PARAM = "dir";
+export const MODE_PARAM = "mode";
 
 /** Every URL parameter Studio names; no other module writes one out. */
 export const STUDIO_PARAMS: readonly string[] = [
@@ -26,6 +27,7 @@ export const STUDIO_PARAMS: readonly string[] = [
   REFRESH_PARAM,
   FILE_PARAM,
   DIR_PARAM,
+  MODE_PARAM,
 ];
 
 /** Filled into a prompt when no change is named, so a prompt is never half-written. */
@@ -42,9 +44,14 @@ interface SelectionBase {
   refresh: boolean;
 }
 
+/** An open file is read rendered or edited raw; read is every other value. */
+export type VaultMode = "read" | "edit";
+
 export interface StudioVaultSelection extends SelectionBase {
   view: "vault";
   openPath: string | null;
+  /** Only meaningful with an open file, and only where the write path is reached. */
+  mode: VaultMode;
   /** A folder of the listed tree; never looked up on disk. */
   openDir: string | null;
 }
@@ -109,6 +116,7 @@ function readVault(params: URLSearchParams): StudioVaultSelection {
     ...readBase(params),
     view: "vault",
     openPath: readText(params.get(FILE_PARAM)),
+    mode: params.get(MODE_PARAM) === "edit" ? "edit" : "read",
     openDir: readText(params.get(DIR_PARAM)),
   };
 }
@@ -128,7 +136,7 @@ export function parseVaultSelection(url: URL): StudioVaultSelection {
 /** Drops the vault's target. */
 export function switchView(selection: StudioSelection, view: StudioView): StudioSelection {
   const base = { companionDigest: selection.companionDigest, refresh: false };
-  if (view === "vault") return { ...base, view, openPath: null, openDir: null };
+  if (view === "vault") return { ...base, view, openPath: null, mode: "read", openDir: null };
   return { ...base, view };
 }
 
@@ -146,6 +154,7 @@ export function openFile(selection: StudioSelection, path: string): StudioVaultS
     refresh: false,
     view: "vault",
     openPath: path,
+    mode: "read",
     openDir: null,
   };
 }
@@ -157,10 +166,16 @@ export function openFolder(selection: StudioSelection, dir: string | null): Stud
     refresh: false,
     view: "vault",
     openPath: null,
+    mode: "read",
     openDir: dir,
   };
 }
 
+/** The open file in the other mode; a selection with no open file is returned as it is. */
+export function withMode(selection: StudioVaultSelection, mode: VaultMode): StudioVaultSelection {
+  return selection.openPath ? { ...selection, mode, refresh: false } : selection;
+}
+
 export function refresh(selection: StudioSelection): StudioSelection {
   return { ...selection, refresh: true };
 }
@@ -174,6 +189,9 @@ export function toFields(selection: StudioSelection): SelectionField[] {
   if (selection.view !== "dashboard") fields.push({ name: VIEW_PARAM, value: selection.view });
   if (selection.view === "vault") {
     if (selection.openPath) fields.push({ name: FILE_PARAM, value: selection.openPath });
+    if (selection.openPath && selection.mode === "edit") {
+      fields.push({ name: MODE_PARAM, value: "edit" });
+    }
     if (selection.openDir) fields.push({ name: DIR_PARAM, value: selection.openDir });
   }
   if (selection.refresh) fields.push({ name: REFRESH_PARAM, value: "1" });

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

@@ -18,6 +18,7 @@ import {
   VAULT_CHANGES_ROUTE,
   VAULT_DIR_ROUTE,
   VAULT_FILTER_ROUTE,
+  VAULT_PANE_ROUTE,
 } from "./routes";
 import {
   COMPANION_DIGEST_PATTERN,
@@ -37,6 +38,7 @@ import {
   type TerminalConnection,
   type TerminalRegistryOptions,
 } from "./terminal";
+import { studioClientAsset } from "./client-asset";
 import { terminalAsset } from "./terminal-assets";
 import {
   createLaunchResolver,
@@ -143,6 +145,11 @@ async function renderVaultView(page: StudioPage): Promise<string> {
   return views.renderVaultView(page);
 }
 
+async function renderVaultPane(page: StudioPage): Promise<string> {
+  const views = await import("./views/document");
+  return views.renderVaultPane(page);
+}
+
 async function renderVaultChildren(page: StudioPage): Promise<string | null> {
   const views = await import("./views/document");
   return views.renderVaultChildren(page);
@@ -158,12 +165,17 @@ async function collectVaultState(
   vault: VaultManager,
   companionPath: string,
   selection: StudioVaultSelection,
-  options: { tree: "prefetch" | "await" },
+  options: { tree: "prefetch" | "await" | "skip" },
 ): Promise<StudioVaultPage> {
   const { vaultState } = await import("./views/vault/state");
   return vaultState(vault, companionPath, selection, options);
 }
 
+/** A pane is never a refresh, so the listing it skips is not asked to be rebuilt. */
+function plainSelection(selection: StudioVaultSelection): StudioVaultSelection {
+  return { ...selection, refresh: false };
+}
+
 function html(body: string): Response {
   return new Response(body, {
     headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
@@ -435,6 +447,9 @@ export function createStudioFetch(
       );
     }
 
+    const clientAsset = await studioClientAsset(url.pathname);
+    if (clientAsset) return respond(clientAsset);
+
     if (url.pathname.startsWith("/studio/terminal/") && terminal) {
       const asset = await terminalAsset(url.pathname);
       if (asset) return respond(asset);
@@ -527,6 +542,32 @@ export function createStudioFetch(
       );
     }
 
+    if (url.pathname === VAULT_PANE_ROUTE) {
+      const collected = await inventory();
+      const selection = parseVaultSelection(url);
+      const companion = resolveCompanion(collected, selection.companionDigest);
+      if (!companion) return respond(json({ reason: "no registered companion was selected" }, 400));
+      const state = await collectVaultState(vault, companion.path, plainSelection(selection), {
+        tree: "skip",
+      });
+      return respond(
+        new Response(
+          await renderVaultPane({
+            inventory: collected,
+            selection,
+            companion,
+            payload: null,
+            error: null,
+            collectedAt: null,
+            writable,
+            vault: state,
+            terminal: null,
+          }),
+          { headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } },
+        ),
+      );
+    }
+
     if (url.pathname === VAULT_DIR_ROUTE || url.pathname === VAULT_FILTER_ROUTE) {
       const selection = parseVaultSelection(url);
       const selected = await selectedCompanion(selection.companionDigest, inventory);