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

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

@@ -0,0 +1,199 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { readOpenSpecProjectSchema } from "../cap/openspec";
+import {
+  readAllChangeStatus,
+  readOpenSpecJson,
+  WORKFLOW_CAPABILITY_ID,
+  type OpenSpecResult,
+} from "./openspec-cli";
+
+export interface WorkflowArtifact {
+  id: string;
+  description?: string;
+  generates?: string;
+  requires: string[];
+}
+
+export interface WorkflowEdge {
+  from: string;
+  to: string;
+}
+
+export interface WorkflowApplyStep {
+  requires: string[];
+  tracks?: string;
+}
+
+export interface WorkflowTopology {
+  schemaName: string;
+  /** Capability that owns this workflow, so a consumer can tell which skills drive it. */
+  workflowCapabilityId: string;
+  schemaVersion?: number;
+  description?: string;
+  source: "project" | "package";
+  artifacts: WorkflowArtifact[];
+  edges: WorkflowEdge[];
+  apply: WorkflowApplyStep;
+}
+
+export interface SchemaLocation {
+  path: string;
+}
+
+export interface WorkflowTopologyDeps {
+  readProjectSchemaName?: (companionPath: string) => string | undefined;
+  defaultSchemaName?: (companionPath: string) => Promise<string | undefined>;
+  locateSchema?: (
+    companionPath: string,
+    schemaName: string,
+  ) => Promise<OpenSpecResult<SchemaLocation>>;
+  readFile?: (filePath: string) => Promise<string>;
+}
+
+const FALLBACK_SCHEMA_NAME = "spec-driven";
+
+async function readDefaultSchemaName(companionPath: string): Promise<string | undefined> {
+  const status = await readAllChangeStatus(companionPath);
+  if (!status.ok) return undefined;
+  return status.value.changes?.find((change) => change.planningHome?.defaultSchema)?.planningHome
+    ?.defaultSchema;
+}
+
+function locateSchemaViaCli(
+  companionPath: string,
+  schemaName: string,
+): Promise<OpenSpecResult<SchemaLocation>> {
+  return readOpenSpecJson(companionPath, ["schema", "which", schemaName, "--json"]);
+}
+
+function toStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string")
+    : [];
+}
+
+function parseTopology(
+  content: string,
+  fallbackName: string,
+  source: WorkflowTopology["source"],
+): WorkflowTopology | { reason: string } {
+  let parsed: unknown;
+  try {
+    parsed = parse(content);
+  } catch (error) {
+    return { reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (!parsed || typeof parsed !== "object") return { reason: "schema is not a mapping" };
+
+  const document = parsed as Record<string, unknown>;
+  if (!Array.isArray(document.artifacts)) {
+    return { reason: "schema declares no artifacts list" };
+  }
+
+  const artifacts: WorkflowArtifact[] = [];
+  for (const entry of document.artifacts) {
+    if (!entry || typeof entry !== "object") continue;
+    const artifact = entry as Record<string, unknown>;
+    if (typeof artifact.id !== "string") continue;
+    artifacts.push({
+      id: artifact.id,
+      ...(typeof artifact.description === "string" ? { description: artifact.description } : {}),
+      ...(typeof artifact.generates === "string" ? { generates: artifact.generates } : {}),
+      requires: toStringArray(artifact.requires),
+    });
+  }
+
+  const declared = new Set(artifacts.map((artifact) => artifact.id));
+  const edges: WorkflowEdge[] = [];
+  for (const artifact of artifacts) {
+    for (const requirement of artifact.requires) {
+      if (declared.has(requirement)) edges.push({ from: requirement, to: artifact.id });
+    }
+  }
+
+  const applyBlock =
+    document.apply && typeof document.apply === "object"
+      ? (document.apply as Record<string, unknown>)
+      : {};
+
+  return {
+    schemaName: typeof document.name === "string" ? document.name : fallbackName,
+    workflowCapabilityId: WORKFLOW_CAPABILITY_ID,
+    ...(typeof document.version === "number" ? { schemaVersion: document.version } : {}),
+    ...(typeof document.description === "string" ? { description: document.description } : {}),
+    source,
+    artifacts,
+    edges,
+    apply: {
+      requires: toStringArray(applyBlock.requires),
+      ...(typeof applyBlock.tracks === "string" ? { tracks: applyBlock.tracks } : {}),
+    },
+  };
+}
+
+/**
+ * Reads the workflow graph of whichever schema a Companion Repository
+ * resolves. Nothing about a particular schema is assumed: artifacts, their
+ * dependency edges, and the apply step all come from the schema document, so a
+ * schema that gains an artifact renders without a code change.
+ */
+export async function readWorkflowTopology(
+  companionPath: string,
+  deps: WorkflowTopologyDeps = {},
+): Promise<OpenSpecResult<WorkflowTopology>> {
+  const readSchemaName = deps.readProjectSchemaName ?? readOpenSpecProjectSchema;
+  const readDefaultName = deps.defaultSchemaName ?? readDefaultSchemaName;
+  const locate = deps.locateSchema ?? locateSchemaViaCli;
+  const readFile = deps.readFile ?? ((filePath: string) => fs.readFile(filePath, "utf8"));
+
+  const schemaName =
+    readSchemaName(companionPath) ?? (await readDefaultName(companionPath)) ?? FALLBACK_SCHEMA_NAME;
+  const command = `workflow topology for ${schemaName}`;
+
+  let content: string | undefined;
+  let source: WorkflowTopology["source"] = "project";
+  try {
+    content = await readFile(
+      path.join(companionPath, "openspec", "schemas", schemaName, "schema.yaml"),
+    );
+  } catch {
+    /** No project-local schema: fall through to the CLI-resolved location. */
+  }
+
+  if (content === undefined) {
+    const located = await locate(companionPath, schemaName);
+    if (!located.ok) {
+      return {
+        ok: false,
+        failure: {
+          command,
+          reason: `could not locate schema ${schemaName}: ${located.failure.reason}`,
+        },
+      };
+    }
+    try {
+      content = await readFile(path.join(located.value.path, "schema.yaml"));
+      source = "package";
+    } catch (error) {
+      return {
+        ok: false,
+        failure: {
+          command,
+          reason: `could not read schema ${schemaName}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        },
+      };
+    }
+  }
+
+  const topology = parseTopology(content, schemaName, source);
+  if ("reason" in topology) {
+    return { ok: false, failure: { command, reason: `schema ${schemaName}: ${topology.reason}` } };
+  }
+  return { ok: true, value: topology };
+}

package/src/cli/commands/studio/views/client.ts

@@ -0,0 +1,197 @@
+import { COMPANION_DIGEST_PATTERN, COMPANION_PARAM } from "../selection";
+
+export const THEME_STORAGE_KEY = "mate-studio-theme";
+export const COMPANION_STORAGE_KEY = "mate-studio-companion";
+
+/**
+ * Runs in `<head>` before first paint. A server-rendered document arrives with
+ * its markup already in place, so a remembered appearance applied after load
+ * would paint the other one first and then repaint, and a remembered companion
+ * restored after load would paint the picker before leaving it.
+ *
+ * The restore names the companion in the URL and reloads, because the URL is
+ * what the server answers. A companion parameter that is present and empty is
+ * a deliberate "no companion" and is left alone, so the redirect cannot loop
+ * and the picker stays reachable.
+ */
+export const STUDIO_PREPAINT_SCRIPT = `(function () {
+  try {
+    var chosen = localStorage.getItem(${JSON.stringify(THEME_STORAGE_KEY)});
+    if (chosen === "dark" || chosen === "light") {
+      document.documentElement.setAttribute("data-theme", chosen);
+    }
+  } catch (error) {
+    /* a blocked web store only costs the preference, never the page */
+  }
+
+  try {
+    var params = new URLSearchParams(location.search);
+    var last = localStorage.getItem(${JSON.stringify(COMPANION_STORAGE_KEY)});
+    if (!params.has(${JSON.stringify(COMPANION_PARAM)}) && ${String(COMPANION_DIGEST_PATTERN)}.test(last || "")) {
+      params.set(${JSON.stringify(COMPANION_PARAM)}, last);
+      location.replace(location.pathname + "?" + params.toString());
+    }
+  } catch (error) {
+    /* a blocked web store only costs the restore, never the page */
+  }
+})();`;
+
+/**
+ * The only browser code Studio ships: cycling the appearance, remembering the
+ * companion on screen, switching workflow schema tabs, and copying a prompt.
+ * Each needs an API the server does not have, and nothing else here renders,
+ * fetches, or holds state.
+ */
+export const STUDIO_CLIENT_SCRIPT = `(function () {
+  var THEME_KEY = ${JSON.stringify(THEME_STORAGE_KEY)};
+  var COMPANION_KEY = ${JSON.stringify(COMPANION_STORAGE_KEY)};
+  var THEME_CYCLE = ["system", "dark", "light"];
+  var toastTimer;
+
+  function readTheme() {
+    try {
+      var stored = localStorage.getItem(THEME_KEY);
+      return THEME_CYCLE.indexOf(stored) === -1 ? "system" : stored;
+    } catch (error) {
+      return "system";
+    }
+  }
+
+  function storeTheme(theme) {
+    try {
+      localStorage.setItem(THEME_KEY, theme);
+    } catch (error) {
+      /* a blocked web store only costs the preference, never the page */
+    }
+  }
+
+  var theme = readTheme();
+
+  function applyTheme(next) {
+    theme = next;
+    var root = document.documentElement;
+    if (next === "system") root.removeAttribute("data-theme");
+    else root.setAttribute("data-theme", next);
+    var control = document.getElementById("studio-theme");
+    if (control) {
+      control.textContent = "Theme: " + next;
+      control.setAttribute("data-theme-state", next);
+    }
+  }
+
+  function announce(message) {
+    var toast = document.getElementById("studio-toast");
+    if (!toast) return;
+    toast.textContent = message;
+    toast.setAttribute("data-shown", "true");
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(function () {
+      toast.setAttribute("data-shown", "false");
+    }, 1400);
+  }
+
+  function copy(text, label) {
+    return navigator.clipboard.writeText(text).then(
+      function () {
+        announce("copied " + label);
+      },
+      function () {
+        /* a blocked clipboard costs the copy, never the page */
+        announce("copying is blocked in this browser");
+      },
+    );
+  }
+
+  function rememberCompanion() {
+    var scope = document.querySelector("[data-companion]");
+    var current = scope && scope.getAttribute("data-companion");
+    if (!current) return;
+    try {
+      localStorage.setItem(COMPANION_KEY, current);
+    } catch (error) {
+      /* a blocked web store only costs the next visit, never the page */
+    }
+  }
+
+  function wireWorkflowSchemaTabs() {
+    document.querySelectorAll("[data-workflow-schema-root]").forEach(function (root) {
+      var tabs = root.querySelectorAll("[data-workflow-schema-profile]");
+      var panels = root.querySelectorAll("[data-workflow-schema-panel]");
+
+      function select(profile) {
+        tabs.forEach(function (tab) {
+          tab.setAttribute(
+            "aria-selected",
+            tab.getAttribute("data-workflow-schema-profile") === profile ? "true" : "false",
+          );
+        });
+        panels.forEach(function (panel) {
+          panel.setAttribute(
+            "data-active",
+            panel.getAttribute("data-workflow-schema-panel") === profile ? "true" : "false",
+          );
+        });
+      }
+
+      tabs.forEach(function (tab) {
+        tab.addEventListener("click", function () {
+          select(tab.getAttribute("data-workflow-schema-profile"));
+        });
+      });
+
+      var selected = root.querySelector('[aria-selected="true"]');
+      if (selected) select(selected.getAttribute("data-workflow-schema-profile"));
+    });
+  }
+
+  function wireSkillTabs() {
+    document.querySelectorAll("[data-skills-root]").forEach(function (root) {
+      var tabs = root.querySelectorAll("[data-skill-profile]");
+      var panels = root.querySelectorAll("[data-skill-panel]");
+
+      function select(profile) {
+        tabs.forEach(function (tab) {
+          tab.setAttribute(
+            "aria-selected",
+            tab.getAttribute("data-skill-profile") === profile ? "true" : "false",
+          );
+        });
+        panels.forEach(function (panel) {
+          var active = panel.getAttribute("data-skill-panel") === profile;
+          panel.setAttribute("data-active", active ? "true" : "false");
+          panel.setAttribute("aria-hidden", active ? "false" : "true");
+        });
+      }
+
+      tabs.forEach(function (tab) {
+        tab.addEventListener("click", function () {
+          select(tab.getAttribute("data-skill-profile"));
+        });
+      });
+
+      var selected = root.querySelector('[aria-selected="true"]');
+      if (selected) select(selected.getAttribute("data-skill-profile"));
+    });
+  }
+
+  applyTheme(theme);
+  rememberCompanion();
+  wireWorkflowSchemaTabs();
+  wireSkillTabs();
+
+  var toggle = document.getElementById("studio-theme");
+  if (toggle) {
+    toggle.addEventListener("click", function () {
+      var next = THEME_CYCLE[(THEME_CYCLE.indexOf(theme) + 1) % THEME_CYCLE.length];
+      applyTheme(next);
+      storeTheme(next);
+    });
+  }
+
+  document.querySelectorAll("[data-copy]").forEach(function (node) {
+    node.addEventListener("click", function () {
+      var text = node.getAttribute("data-copy");
+      if (text) copy(text, node.getAttribute("data-copy-label") || "prompt");
+    });
+  });
+})();`;

package/src/cli/commands/studio/views/companion-picker.tsx

@@ -0,0 +1,91 @@
+/** @jsxImportSource hono/jsx */
+
+import type { StudioInventory, StudioInventoryCompanion } from "../inventory";
+import { companionDigest, type StudioSelection } from "../selection";
+import { healthNote } from "./model";
+
+interface CompanionPickerProps {
+  inventory: StudioInventory;
+  selection: StudioSelection;
+}
+
+/** Kept short so a card leads with what distinguishes it, not the shared prefix. */
+const PAIRING_CHIP_LIMIT = 3;
+
+function companionName(companionPath: string): string {
+  const segments = companionPath.split(/[\\/]+/).filter(Boolean);
+  return segments[segments.length - 1] ?? companionPath;
+}
+
+/**
+ * The unselected main content. One submit button per companion, so the first
+ * choice is a click on the thing being chosen rather than a trip through the
+ * sidebar dropdown — the same GET navigation either way.
+ */
+export function CompanionPicker({ inventory, selection }: CompanionPickerProps) {
+  const companions = inventory.companions;
+
+  if (companions.length === 0) {
+    return (
+      <section className="panel">
+        <h3>No Companion Repository</h3>
+        <p className="empty">No Companion Repository is registered on this machine.</p>
+        <p className="muted">
+          Run <span className="mono">mate companion setup</span> in a Working Repository to register
+          one.
+        </p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="panel">
+      <h3>Choose a Companion Repository</h3>
+      <p className="note">
+        Studio serves one companion at a time, and remembers the one you choose for your next visit.
+      </p>
+      <form method="get" action="/">
+        {selection.view === "dashboard" ? null : (
+          <input type="hidden" name="view" value={selection.view} />
+        )}
+        <div className="picker-grid">
+          {companions.map((companion) => (
+            <CompanionCard key={companionDigest(companion.path)} companion={companion} />
+          ))}
+        </div>
+      </form>
+    </section>
+  );
+}
+
+function CompanionCard({ companion }: { companion: StudioInventoryCompanion }) {
+  const note = healthNote(companion);
+  const pairings = companion.pairings.slice(0, PAIRING_CHIP_LIMIT);
+  const hidden = companion.pairings.length - pairings.length;
+
+  return (
+    <button
+      type="submit"
+      name="companion"
+      value={companionDigest(companion.path)}
+      className="picker-card"
+      data-unready={companion.health === "ready" ? undefined : "true"}
+    >
+      <span className="picker-card-name">{companionName(companion.path)}</span>
+      <span className="picker-card-path mono">{companion.path}</span>
+      <span className="picker-card-meta">
+        {note ? <span className="chip chip-invalid">{note}</span> : null}
+        {companion.pairings.length === 0 ? (
+          <span className="chip">no linked working repository</span>
+        ) : (
+          pairings.map((pairing) => (
+            <span key={pairing.repositoryPath} className="chip">
+              {pairing.repositoryId}
+            </span>
+          ))
+        )}
+        {hidden > 0 ? <span className="chip">+{hidden} more</span> : null}
+      </span>
+    </button>
+  );
+}

package/src/cli/commands/studio/views/companion-selector.tsx

@@ -0,0 +1,90 @@
+/** @jsxImportSource hono/jsx */
+
+import type { StudioInventoryCompanion } from "../inventory";
+import { companionDigest, resolveCompanion, type StudioSelection } from "../selection";
+import { healthNote, type StudioPage } from "./model";
+
+interface CompanionSelectorProps {
+  inventory: StudioPage["inventory"];
+  selection: StudioSelection;
+}
+
+/**
+ * A GET form, so choosing a companion is a navigation to the URL naming it. The
+ * change is deliberately not carried over: it belongs to the companion being
+ * left behind.
+ */
+export function CompanionSelector({ inventory, selection }: CompanionSelectorProps) {
+  const companions = inventory.companions;
+  const selected = resolveCompanion(inventory, selection.companionDigest);
+
+  return (
+    <form className="sidebar-scope" method="get" action="/">
+      <span className="sidebar-label">Scope</span>
+      {selection.view === "dashboard" ? null : (
+        <input type="hidden" name="view" value={selection.view} />
+      )}
+      {/* eslint-disable-next-line react/no-unknown-property -- raw HTML attribute: hono/jsx server-renders this inline handler */}
+      <select name="companion" aria-label="Companion Repository" onchange="this.form.submit()">
+        <PlaceholderOption companionCount={companions.length} selected={selected} />
+        {companions.map((companion) => {
+          const digest = companionDigest(companion.path);
+          const note = healthNote(companion);
+          const unready = companion.health !== "ready";
+          return (
+            <option
+              key={digest}
+              value={digest}
+              selected={digest === selection.companionDigest}
+              className={unready ? "unready" : undefined}
+              data-unready={unready ? "true" : undefined}
+            >
+              {note ? `${companion.path} (${note})` : companion.path}
+            </option>
+          );
+        })}
+      </select>
+      <SelectorNote companionCount={companions.length} selected={selected} />
+    </form>
+  );
+}
+
+interface EmptyStateProps {
+  companionCount: number;
+  selected: StudioInventoryCompanion | null;
+}
+
+/**
+ * Without it the browser shows the first companion as if it were chosen, which
+ * a null selection is not. Disabled so it cannot be chosen back, and dropped
+ * once a companion resolves.
+ */
+function PlaceholderOption({ companionCount, selected }: EmptyStateProps) {
+  if (companionCount === 0) {
+    return (
+      <option value="" className="placeholder">
+        no companion registered
+      </option>
+    );
+  }
+  if (selected) return null;
+  return (
+    <option value="" selected disabled className="placeholder">
+      select a companion…
+    </option>
+  );
+}
+
+function SelectorNote({ companionCount, selected }: EmptyStateProps) {
+  if (!selected) {
+    return (
+      <p className="note">
+        {companionCount === 0
+          ? "No Companion Repository is registered on this machine."
+          : "Select a Companion Repository to see its state."}
+      </p>
+    );
+  }
+  const note = healthNote(selected);
+  return note ? <p className="note unready">{note}</p> : null;
+}

package/src/cli/commands/studio/views/dashboard/changes.tsx

@@ -0,0 +1,107 @@
+/** @jsxImportSource hono/jsx */
+
+import type { StudioChange } from "../../payload";
+
+interface ChangesProps {
+  changes: StudioChange[];
+}
+
+function progressLabel(change: StudioChange): string {
+  const total = change.totalTasks ?? 0;
+  return total === 0 ? "no tasks" : `${change.completedTasks ?? 0} / ${total}`;
+}
+
+function progressPercent(change: StudioChange): number {
+  const total = change.totalTasks ?? 0;
+  if (total === 0) return 0;
+  return Math.min(100, Math.round(((change.completedTasks ?? 0) / total) * 100));
+}
+
+export function Changes({ changes }: ChangesProps) {
+  return (
+    <section className="panel lookup-panel">
+      <div className="section-header">
+        <div>
+          <h3>Changes</h3>
+          <p className="section-note">Active work tracked by this Companion Repository.</p>
+        </div>
+        <span className="section-count">
+          {changes.length} {changes.length === 1 ? "change" : "changes"}
+        </span>
+      </div>
+      {changes.length === 0 ? (
+        <p className="empty">No changes in this companion.</p>
+      ) : (
+        <div className="scroll">
+          <table className="lookup-table">
+            <thead>
+              <tr>
+                <th scope="col">Change</th>
+                <th scope="col">Status</th>
+                <th scope="col">Progress</th>
+                <th scope="col">Artifacts</th>
+              </tr>
+            </thead>
+            <tbody>
+              {changes.map((change) => (
+                <tr key={change.name}>
+                  <td data-label="Change">
+                    <div className="change-cell">
+                      <span className="mono">{change.name}</span>
+                      {change.valid === false ? (
+                        <span className="chip chip-invalid">
+                          {`${change.issueCount ?? 0} issues`}
+                        </span>
+                      ) : null}
+                    </div>
+                  </td>
+                  <td data-label="Status">
+                    <span className="status-chip" data-status={change.status ?? "unknown"}>
+                      {change.status ?? "unknown"}
+                    </span>
+                  </td>
+                  <td className="numeric" data-label="Progress">
+                    <span className="progress-label">{progressLabel(change)}</span>
+                    {(change.totalTasks ?? 0) === 0 ? null : (
+                      <span
+                        className="bar"
+                        role="progressbar"
+                        aria-valuemin="0"
+                        aria-valuemax="100"
+                        aria-valuenow={progressPercent(change)}
+                        aria-label={`${progressLabel(change)} tasks complete`}
+                      >
+                        <span
+                          className="bar-fill"
+                          style={{ width: `${progressPercent(change)}%` }}
+                        />
+                      </span>
+                    )}
+                  </td>
+                  <td data-label="Artifacts">
+                    {change.artifacts.length === 0 ? (
+                      <span className="muted">—</span>
+                    ) : (
+                      <div className="artifact-list">
+                        {change.artifacts.map((artifact) => (
+                          <span
+                            key={artifact.id}
+                            className={
+                              artifact.status === "done" ? "chip chip-done" : "chip chip-pending"
+                            }
+                          >
+                            {artifact.id}
+                          </span>
+                        ))}
+                      </div>
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </section>
+  );
+}