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

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

@@ -0,0 +1,184 @@
+import path from "node:path";
+
+import { readSpecAreas } from "./areas";
+import { collectSkillInventory, type StudioSkillInventory } from "./mate-inventory";
+import {
+  listChanges,
+  listSpecs,
+  readAllChangeStatus,
+  validateAll,
+  type OpenSpecFailure,
+  type OpenSpecValidationItem,
+} from "./openspec-cli";
+import { readWorkflowTopology, type WorkflowTopology } from "./topology";
+
+export interface StudioChangeArtifact {
+  id: string;
+  status?: string;
+}
+
+export interface StudioChange {
+  name: string;
+  completedTasks?: number;
+  totalTasks?: number;
+  status?: string;
+  lastModified?: string;
+  schemaName?: string;
+  artifacts: StudioChangeArtifact[];
+  valid?: boolean;
+  issueCount?: number;
+}
+
+export interface StudioSpec {
+  capability: string;
+  requirementCount?: number;
+  areas: string[];
+  valid?: boolean;
+  issueCount?: number;
+}
+
+export interface StudioCompanionPayload {
+  companionPath: string;
+  changes: StudioChange[];
+  specs: StudioSpec[];
+  /** Flattened names retained for the workflow's skill-availability check. */
+  skills?: string[];
+  skillInventory?: StudioSkillInventory;
+  topology: WorkflowTopology | null;
+  warnings: string[];
+}
+
+export interface StudioCompanionError {
+  error: { companionPath: string; reason: string };
+}
+
+export type StudioCompanionResponse = StudioCompanionPayload | StudioCompanionError;
+
+export interface CompanionPayloadDeps {
+  listChanges?: typeof listChanges;
+  listSpecs?: typeof listSpecs;
+  readAllChangeStatus?: typeof readAllChangeStatus;
+  validateAll?: typeof validateAll;
+  readWorkflowTopology?: typeof readWorkflowTopology;
+  readSpecAreas?: (specsRoot: string, specId: string) => Promise<string[]>;
+  collectSkillInventory?: typeof collectSkillInventory;
+}
+
+function describe(failure: OpenSpecFailure): string {
+  return `${failure.command}: ${failure.reason}`;
+}
+
+function validationOf(
+  items: OpenSpecValidationItem[] | undefined,
+  id: string,
+  type: string,
+): { valid?: boolean; issueCount?: number } {
+  const item = items?.find((entry) => entry.id === id && (entry.type ?? type) === type);
+  if (!item || item.valid === undefined) return {};
+  return { valid: item.valid, issueCount: item.issues?.length ?? 0 };
+}
+
+/**
+ * One Companion Repository's studio payload. Change and spec collection is
+ * load-bearing — its failure becomes the error payload — while topology,
+ * validation, and skills degrade to warnings so a companion missing one of them
+ * still renders.
+ */
+export async function assembleCompanionPayload(
+  companionPath: string,
+  deps: CompanionPayloadDeps = {},
+): Promise<StudioCompanionResponse> {
+  const collectChanges = deps.listChanges ?? listChanges;
+  const collectSpecs = deps.listSpecs ?? listSpecs;
+  const collectStatus = deps.readAllChangeStatus ?? readAllChangeStatus;
+  const collectValidation = deps.validateAll ?? validateAll;
+  const collectTopology = deps.readWorkflowTopology ?? readWorkflowTopology;
+  const collectAreas = deps.readSpecAreas ?? readSpecAreas;
+  const collectSkills = deps.collectSkillInventory ?? collectSkillInventory;
+
+  const [changeList, specList, status, validation, topology, skillInventory] = await Promise.all([
+    collectChanges(companionPath),
+    collectSpecs(companionPath),
+    collectStatus(companionPath),
+    collectValidation(companionPath),
+    collectTopology(companionPath),
+    collectSkills(companionPath).then(
+      (skills) => ({ skills }),
+      (error: unknown) => ({ error }),
+    ),
+  ]);
+
+  for (const required of [changeList, specList, status]) {
+    if (!required.ok) {
+      return { error: { companionPath, reason: describe(required.failure) } };
+    }
+  }
+  if (!changeList.ok || !specList.ok || !status.ok) {
+    return { error: { companionPath, reason: "companion state could not be collected" } };
+  }
+
+  const warnings: string[] = [];
+  if (!topology.ok) warnings.push(describe(topology.failure));
+  if (!validation.ok) warnings.push(describe(validation.failure));
+  if ("error" in skillInventory) {
+    warnings.push(
+      `Mate skill inventory: ${skillInventory.error instanceof Error ? skillInventory.error.message : String(skillInventory.error)}`,
+    );
+  }
+  const validationItems = validation.ok ? validation.value.items : undefined;
+
+  const statusByChange = new Map(
+    (status.value.changes ?? []).map((entry) => [entry.changeName, entry]),
+  );
+
+  const changes: StudioChange[] = (changeList.value.changes ?? []).map((change) => {
+    const changeStatus = statusByChange.get(change.name);
+    return {
+      name: change.name,
+      ...(change.completedTasks === undefined ? {} : { completedTasks: change.completedTasks }),
+      ...(change.totalTasks === undefined ? {} : { totalTasks: change.totalTasks }),
+      ...(change.status === undefined ? {} : { status: change.status }),
+      ...(change.lastModified === undefined ? {} : { lastModified: change.lastModified }),
+      ...(changeStatus?.schemaName ? { schemaName: changeStatus.schemaName } : {}),
+      artifacts: (changeStatus?.artifacts ?? []).map((artifact) => ({
+        id: artifact.id,
+        ...(artifact.status === undefined ? {} : { status: artifact.status }),
+      })),
+      ...validationOf(validationItems, change.name, "change"),
+    };
+  });
+
+  const planningRoot =
+    (status.value.changes ?? []).find((entry) => entry.planningHome?.root)?.planningHome?.root ??
+    companionPath;
+  const specsRoot = path.join(planningRoot, "openspec", "specs");
+
+  const specs: StudioSpec[] = await Promise.all(
+    (specList.value.specs ?? []).map(async (spec) => ({
+      capability: spec.id,
+      ...(spec.requirementCount === undefined ? {} : { requirementCount: spec.requirementCount }),
+      areas: await collectAreas(specsRoot, spec.id),
+      ...validationOf(validationItems, spec.id, "spec"),
+    })),
+  );
+
+  return {
+    companionPath,
+    changes,
+    specs,
+    skills:
+      "skills" in skillInventory
+        ? [
+            ...new Set([
+              ...skillInventory.skills.claude,
+              ...skillInventory.skills.opencode,
+              ...skillInventory.skills.agents,
+            ]),
+          ].toSorted()
+        : [],
+    skillInventory:
+      "skills" in skillInventory ? skillInventory.skills : { claude: [], opencode: [], agents: [] },
+    topology: topology.ok ? topology.value : null,
+    warnings,
+  };
+}

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

@@ -0,0 +1,2 @@
+/** Loopback only: a payload carries absolute companion paths and change names. */
+export const STUDIO_HOSTNAME = "127.0.0.1";

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

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+
+import type { StudioInventory, StudioInventoryCompanion } from "./inventory";
+
+export type StudioView = "dashboard" | "workflow" | "specs" | "skills";
+
+export const STUDIO_VIEWS: readonly StudioView[] = ["dashboard", "workflow", "specs", "skills"];
+
+export const COMPANION_PARAM = "companion";
+export const VIEW_PARAM = "view";
+export const REFRESH_PARAM = "refresh";
+
+/** Filled into a prompt when no change is named, so a prompt is never half-written. */
+export const CHANGE_PLACEHOLDER = "<change-name>";
+
+const DIGEST_LENGTH = 10;
+
+export interface StudioSelection {
+  companionDigest: string | null;
+  view: StudioView;
+  /**
+   * One-shot: the refresh control asks for it, and it is never carried forward
+   * into the URL another control builds. Switching a view is not a refresh.
+   */
+  refresh: boolean;
+}
+
+/**
+ * Derived from the companion path alone: stable enough to bookmark, and short
+ * enough that no absolute Companion Repository path is written into browser
+ * history, autocomplete, or a shared URL.
+ */
+/** The shape a digest must have to be trusted from outside the server: a URL, a browser store. */
+export const COMPANION_DIGEST_PATTERN = new RegExp(`^[0-9a-f]{${DIGEST_LENGTH}}$`);
+
+export function companionDigest(companionPath: string): string {
+  return createHash("sha256").update(companionPath).digest("hex").slice(0, DIGEST_LENGTH);
+}
+
+/** An unresolvable digest selects nothing rather than failing the request. */
+export function resolveCompanion(
+  inventory: StudioInventory,
+  digest: string | null,
+): StudioInventoryCompanion | null {
+  if (!digest) return null;
+  return (
+    inventory.companions.find((companion) => companionDigest(companion.path) === digest) ?? null
+  );
+}
+
+function readView(value: string | null): StudioView {
+  return STUDIO_VIEWS.includes(value as StudioView) ? (value as StudioView) : "dashboard";
+}
+
+export function parseStudioSelection(url: URL): StudioSelection {
+  return {
+    companionDigest: url.searchParams.get(COMPANION_PARAM)?.trim() || null,
+    view: readView(url.searchParams.get(VIEW_PARAM)),
+    refresh: url.searchParams.get(REFRESH_PARAM) === "1",
+  };
+}

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

@@ -0,0 +1,201 @@
+import { collectStudioInventory, type StudioInventory } from "./inventory";
+import { assembleCompanionPayload, type StudioCompanionResponse } from "./payload";
+import { STUDIO_HOSTNAME } from "./routes";
+import { parseStudioSelection, resolveCompanion } from "./selection";
+import { createStudioSnapshotCache, type StudioSnapshotCache } from "./snapshot";
+import type { StudioPage } from "./views/model";
+
+export { STUDIO_HOSTNAME } from "./routes";
+
+/** Read methods; every other method is refused before any collection runs. */
+const READ_METHODS = new Set(["GET", "HEAD"]);
+
+export interface StudioServeOptions {
+  port: number;
+  hostname: string;
+  fetch: (request: Request) => Promise<Response>;
+}
+
+export interface StudioBoundServer {
+  port: number;
+  stop(closeActiveConnections?: boolean): void | Promise<void>;
+}
+
+export interface StudioServerHandle {
+  url: string;
+  port: number;
+  hostname: string;
+  stop(): void | Promise<void>;
+}
+
+export interface StudioServerDeps {
+  collectStudioInventory?: () => Promise<StudioInventory>;
+  assembleCompanionPayload?: (companionPath: string) => Promise<StudioCompanionResponse>;
+  renderDocument?: (page: StudioPage) => string | Promise<string>;
+  serve?: (options: StudioServeOptions) => StudioBoundServer;
+  snapshots?: StudioSnapshotCache;
+}
+
+/**
+ * Loaded at the point of use so no other command pays for the renderer: `hono/jsx`
+ * is reachable from the studio path alone.
+ */
+async function renderStudioDocument(page: StudioPage): Promise<string> {
+  const views = await import("./views/document");
+  return views.renderStudioDocument(page);
+}
+
+function html(body: string): Response {
+  return new Response(body, {
+    headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+  });
+}
+
+/**
+ * The studio request handler. Read-only by construction: a non-read method is
+ * refused before any collection runs, and no route writes. The response is
+ * already correct for the URL that asked for it — the companion, the change,
+ * and the view are read from the request rather than reconciled in the browser.
+ * Collection is held in one snapshot cache for the life of the handler, so a
+ * navigation that only names another view of already-collected state serves it
+ * without spawning OpenSpec again.
+ */
+export function createStudioFetch(
+  deps: StudioServerDeps = {},
+): (request: Request) => Promise<Response> {
+  const inventory = deps.collectStudioInventory ?? collectStudioInventory;
+  const companion = deps.assembleCompanionPayload ?? assembleCompanionPayload;
+  const render = deps.renderDocument ?? renderStudioDocument;
+  const snapshots =
+    deps.snapshots ?? createStudioSnapshotCache({ assembleCompanionPayload: companion });
+
+  return async (request: Request): Promise<Response> => {
+    if (!READ_METHODS.has(request.method)) {
+      return new Response("studio serves read requests only", {
+        status: 405,
+        headers: { allow: "GET, HEAD" },
+      });
+    }
+
+    const url = new URL(request.url);
+    const respond = (response: Response) =>
+      request.method === "HEAD"
+        ? new Response(null, { status: response.status, headers: response.headers })
+        : response;
+
+    if (url.pathname !== "/") return respond(new Response("not found", { status: 404 }));
+
+    return respond(html(await render(await collectStudioPage(url, inventory, snapshots))));
+  };
+}
+
+/**
+ * One rendered document's worth of state. An absent or unresolvable companion
+ * is not a failure: the page renders the selector and the server keeps serving.
+ */
+async function collectStudioPage(
+  url: URL,
+  collectInventory: () => Promise<StudioInventory>,
+  snapshots: StudioSnapshotCache,
+): Promise<StudioPage> {
+  const selection = parseStudioSelection(url);
+  const inventory = await collectInventory();
+  const companion = resolveCompanion(inventory, selection.companionDigest);
+  const page: StudioPage = {
+    inventory,
+    selection,
+    companion,
+    payload: null,
+    error: null,
+    collectedAt: null,
+  };
+
+  if (!companion) return page;
+
+  try {
+    const snapshot = await snapshots.read(companion.path, selection.refresh);
+    const collected = { ...page, collectedAt: snapshot.collectedAt };
+    if ("error" in snapshot.response) return { ...collected, error: snapshot.response.error };
+    return { ...collected, payload: snapshot.response };
+  } catch (error) {
+    return {
+      ...page,
+      error: {
+        companionPath: companion.path,
+        reason: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+/**
+ * Bun's server, reached through `globalThis` rather than an ambient global: the
+ * repository typechecks against Node types only, and Studio's dependence on the
+ * Bun runtime is a deliberate constraint worth naming here.
+ */
+interface BunRuntime {
+  serve(options: StudioServeOptions): StudioBoundServer;
+}
+
+function bunServe(options: StudioServeOptions): StudioBoundServer {
+  const runtime = (globalThis as unknown as { Bun?: BunRuntime }).Bun;
+  if (!runtime) throw new Error("studio requires the Bun runtime to serve");
+  return runtime.serve(options);
+}
+
+/**
+ * Binds the studio server to an operating-system-assigned loopback port. A
+ * bind failure propagates: the caller reports it and exits rather than opening
+ * a browser at a URL nothing answers.
+ */
+export function startStudioServer(deps: StudioServerDeps = {}): StudioServerHandle {
+  const serve = deps.serve ?? bunServe;
+  const server = serve({ port: 0, hostname: STUDIO_HOSTNAME, fetch: createStudioFetch(deps) });
+
+  return {
+    url: `http://localhost:${server.port}`,
+    port: server.port,
+    hostname: STUDIO_HOSTNAME,
+    stop: () => server.stop(true),
+  };
+}
+
+export interface ServeUntilInterruptedDeps {
+  onSignal?: (signal: string, handler: () => void) => () => void;
+}
+
+const INTERRUPT_SIGNALS = ["SIGINT", "SIGTERM"] as const;
+
+function subscribeToProcessSignal(signal: string, handler: () => void): () => void {
+  process.on(signal as NodeJS.Signals, handler);
+  return () => process.off(signal as NodeJS.Signals, handler);
+}
+
+/**
+ * Holds the invocation open while the server serves, and stops it on the first
+ * interrupt. Nothing outlives the invocation: no detached process, no
+ * process-identifier file, no registration, and the signal handlers are removed
+ * before the promise settles.
+ */
+export function serveUntilInterrupted(
+  server: StudioServerHandle,
+  deps: ServeUntilInterruptedDeps = {},
+): Promise<void> {
+  const onSignal = deps.onSignal ?? subscribeToProcessSignal;
+
+  return new Promise<void>((resolve) => {
+    const unsubscribes: (() => void)[] = [];
+    let settled = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      for (const unsubscribe of unsubscribes) unsubscribe();
+      void Promise.resolve(server.stop()).then(resolve, resolve);
+    };
+
+    for (const signal of INTERRUPT_SIGNALS) {
+      unsubscribes.push(onSignal(signal, finish));
+    }
+  });
+}

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

@@ -0,0 +1,63 @@
+import { assembleCompanionPayload, type StudioCompanionResponse } from "./payload";
+
+/** One companion's collected state, with the moment it was collected. */
+export interface StudioSnapshot {
+  response: StudioCompanionResponse;
+  collectedAt: number;
+}
+
+export interface StudioSnapshotCache {
+  read(companionPath: string, refresh: boolean): Promise<StudioSnapshot>;
+}
+
+export interface StudioSnapshotCacheDeps {
+  assembleCompanionPayload?: (companionPath: string) => Promise<StudioCompanionResponse>;
+  now?: () => number;
+}
+
+/**
+ * Holds each Companion Repository's collected state for the life of the server
+ * process. Collection costs one OpenSpec subprocess per command, so re-running
+ * it for a view switch would charge the reader a second of process startup to
+ * see the same state twice — and the page already promises that its data moves
+ * only on load or on an explicit refresh. A refresh collects again and replaces
+ * the snapshot; nothing else does.
+ *
+ * Concurrent reads of one companion share a single collection: a second request
+ * arriving mid-collection awaits the first rather than spawning its own.
+ */
+export function createStudioSnapshotCache(deps: StudioSnapshotCacheDeps = {}): StudioSnapshotCache {
+  const assemble = deps.assembleCompanionPayload ?? assembleCompanionPayload;
+  const now = deps.now ?? Date.now;
+  const snapshots = new Map<string, StudioSnapshot>();
+  const inFlight = new Map<string, Promise<StudioSnapshot>>();
+
+  const collect = (companionPath: string): Promise<StudioSnapshot> => {
+    const startedAt = now();
+    const pending = assemble(companionPath).then((response) => {
+      const snapshot: StudioSnapshot = { response, collectedAt: startedAt };
+      /** Two overlapping collections must not leave the older one's state behind. */
+      const held = snapshots.get(companionPath);
+      if (!held || held.collectedAt <= startedAt) snapshots.set(companionPath, snapshot);
+      return snapshot;
+    });
+
+    /** A failed collection leaves no snapshot, so the next read collects again. */
+    inFlight.set(companionPath, pending);
+    return pending.finally(() => {
+      if (inFlight.get(companionPath) === pending) inFlight.delete(companionPath);
+    });
+  };
+
+  return {
+    read(companionPath: string, refresh: boolean): Promise<StudioSnapshot> {
+      if (!refresh) {
+        const cached = snapshots.get(companionPath);
+        if (cached) return Promise.resolve(cached);
+        const pending = inFlight.get(companionPath);
+        if (pending) return pending;
+      }
+      return collect(companionPath);
+    },
+  };
+}