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

package/src/cli/commands/studio/views/vault/state.ts

@@ -6,15 +6,13 @@ export async function vaultState(
   manager: VaultManager,
   companionPath: string,
   sel: StudioVaultSelection,
-  options: { tree: "prefetch" | "await" },
+  options: { tree: "prefetch" | "await" | "skip" },
 ): Promise<StudioVaultPage> {
   let tree: VaultTreeResult | null = null;
   let failure: string | null = null;
   try {
-    tree =
-      options.tree === "prefetch"
-        ? await manager.prefetch(companionPath, sel.refresh)
-        : await manager.tree(companionPath, sel.refresh);
+    if (options.tree === "prefetch") tree = await manager.prefetch(companionPath, sel.refresh);
+    else if (options.tree === "await") tree = await manager.tree(companionPath, sel.refresh);
   } catch (error) {
     failure = error instanceof Error ? error.message : String(error);
   }

package/src/cli/commands/studio/views/workflow/delivery-path.tsx

@@ -0,0 +1,370 @@
+/** @jsxImportSource hono/jsx */
+
+import type { StudioCompanionPayload } from "../../payload";
+import {
+  bandSpan,
+  edgeMidpoint,
+  edgePath,
+  graphAcross,
+  nodeCenter,
+  percentOf,
+  workflowGraph,
+  type WorkflowGraph,
+} from "./graph";
+import {
+  PHASE_LABELS,
+  workflowPlan,
+  type WorkflowPath,
+  type WorkflowStep,
+  type WorkflowStepBadge,
+} from "./steps";
+
+export function DeliveryPathView({ payload }: { payload: StudioCompanionPayload }) {
+  const plan = workflowPlan({
+    skills: payload.skills && payload.skills.length > 0 ? payload.skills : undefined,
+    topology: payload.topology,
+  });
+
+  return (
+    <section className="workflow-delivery-path" aria-label="Delivery Path">
+      {plan.paths.length > 1 ? (
+        <div className="workflow-schema" data-workflow-schema-root>
+          <label className="view-choice">
+            <span>OpenSpec schema</span>
+            <select data-workflow-schema-select>
+              {plan.paths.map((path, index) => (
+                <option key={path.schema} value={path.schema} selected={index === 0}>
+                  {path.label} – {path.tagline}
+                </option>
+              ))}
+            </select>
+          </label>
+          <div className="workflow-schema-panels">
+            {plan.paths.map((path, index) => (
+              <section
+                key={path.schema}
+                data-workflow-schema-panel={path.schema}
+                data-active={index === 0 ? "true" : "false"}
+              >
+                <PathBody path={path} />
+              </section>
+            ))}
+          </div>
+        </div>
+      ) : (
+        <div className="workflow-schema">
+          <p className="view-choice">
+            <span>OpenSpec schema</span>
+            <code>
+              {plan.paths[0].label} – {plan.paths[0].tagline}
+            </code>
+          </p>
+          <PathBody path={plan.paths[0]} />
+        </div>
+      )}
+    </section>
+  );
+}
+
+/**
+ * The graph is the path; the side panel shows one stage at a time. A node link targets its
+ * card, and CSS shows only the targeted card, so selection needs no script. With nothing
+ * selected the panel shows the path overview.
+ */
+function PathBody({ path }: { path: WorkflowPath }) {
+  return (
+    <div className="workflow-path">
+      <div className="workflow-path-graph">
+        <WorkflowGraphView path={path} />
+        <GraphLegend />
+      </div>
+      <aside className="workflow-detail" aria-label={`${path.label} stage details`}>
+        <div className="workflow-detail-overview" id={overviewId(path)}>
+          <p className="workflow-description">{path.description}</p>
+          {!path.reviewsKnown ? (
+            <p className="workflow-description">
+              The schema&apos;s artifacts could not be read, so its review stages are unknown.
+            </p>
+          ) : null}
+          <p className="workflow-description">
+            A workset is one or more changes published together: after Archive change, start again
+            at the top for the next change, and publish once they are archived.
+          </p>
+          <p className="workflow-detail-hint">
+            Select a node in the graph to see what that stage does and the prompt that runs it.
+          </p>
+        </div>
+        {path.steps.map((step) => (
+          <StageCard key={step.id} path={path} step={step} />
+        ))}
+      </aside>
+    </div>
+  );
+}
+
+const cardId = (path: WorkflowPath, step: WorkflowStep): string =>
+  `workflow-${path.schema}-${step.id}`;
+
+const overviewId = (path: WorkflowPath): string => `workflow-${path.schema}-overview`;
+
+/**
+ * Node links are the only announced part: their document order is the stage order. Bands,
+ * edges, and marks are decorative and hidden from assistive technology.
+ */
+function WorkflowGraphView({ path }: { path: WorkflowPath }) {
+  const graph = workflowGraph(path);
+  return (
+    <nav
+      className="workflow-graph"
+      aria-label="Delivery Path map"
+      style={{ "--graph-columns": String(graph.columns), "--graph-rows": String(graph.rows) }}
+    >
+      <div className="workflow-graph-bands" aria-hidden="true">
+        {graph.bands.map((band) => (
+          <div
+            key={band.phase}
+            className="workflow-graph-band"
+            data-band={band.phase}
+            style={bandSpan(graph, band)}
+          >
+            {band.label}
+          </div>
+        ))}
+        {graph.cycle ? (
+          <div className="workflow-graph-cycle" style={bandSpan(graph, graph.cycle)}>
+            <span>repeats for each change</span>
+          </div>
+        ) : null}
+        <div className="workflow-graph-workset">
+          <span>workset</span>
+        </div>
+      </div>
+      <GraphLayer graph={graph} />
+      <ol className="workflow-graph-nodes">
+        {graph.nodes.map((node) =>
+          node.kind === "start" ? null : (
+            <li
+              key={node.id}
+              className="workflow-graph-node"
+              data-node-kind={node.kind}
+              style={{
+                "--graph-row": String(node.column + 1),
+                "--graph-lane": String(node.row + 1),
+                "--graph-span": String(node.rowSpan),
+              }}
+            >
+              {node.kind === "stage" ? (
+                <NodeLink path={path} step={node.step} box />
+              ) : (
+                <div className="workflow-graph-box workflow-graph-group" data-map-group="human">
+                  <span className="workflow-graph-group-label">Human review</span>
+                  <ol>
+                    {node.steps.map((step) => (
+                      <li key={step.id}>
+                        <NodeLink path={path} step={step} />
+                      </li>
+                    ))}
+                  </ol>
+                </div>
+              )}
+            </li>
+          ),
+        )}
+      </ol>
+    </nav>
+  );
+}
+
+/** Explains the graph's visual marks; the panel states the same facts per stage. */
+function GraphLegend() {
+  return (
+    <ul className="workflow-graph-legend" aria-hidden="true">
+      <li>
+        <i className="workflow-legend-optional" />
+        optional
+      </li>
+      <li>
+        <i className="workflow-graph-openspec" />
+        OpenSpec
+      </li>
+      <li>
+        <i className="workflow-legend-session" />
+        new session
+      </li>
+      <li>
+        <i className="workflow-legend-skip" />
+        can be skipped
+      </li>
+    </ul>
+  );
+}
+
+function GraphLayer({ graph }: { graph: WorkflowGraph }) {
+  return (
+    <svg className="workflow-graph-layer" aria-hidden="true" focusable="false">
+      <svg
+        viewBox={`0 0 ${graphAcross(graph)} ${graph.columns}`}
+        preserveAspectRatio="none"
+        overflow="visible"
+      >
+        {graph.edges.map((edge) => (
+          <path
+            key={`${edge.kind}-${edge.from}-${edge.to}`}
+            className="workflow-graph-edge"
+            d={edgePath(graph, edge)}
+            data-edge-kind={edge.kind}
+            data-edge-from={edge.from}
+            data-edge-to={edge.to}
+            data-new-session={edge.newSession ? "true" : undefined}
+          />
+        ))}
+      </svg>
+      {graph.nodes.map((node) => {
+        if (node.kind !== "start") return null;
+        const { x, y } = percentOf(graph, nodeCenter(node));
+        return <circle key={node.id} className="workflow-graph-start" cx={x} cy={y} r="3.5" />;
+      })}
+      {graph.edges.map((edge) => {
+        if (!edge.newSession) return null;
+        const { x, y } = percentOf(graph, edgeMidpoint(graph, edge));
+        return (
+          <circle
+            key={`${edge.from}-${edge.to}`}
+            className="workflow-graph-session"
+            data-session-mark={edge.to}
+            cx={x}
+            cy={y}
+            r="3.5"
+          />
+        );
+      })}
+    </svg>
+  );
+}
+
+/** `box` marks a standalone node; links inside the review group share its box. */
+function NodeLink({ path, step, box }: { path: WorkflowPath; step: WorkflowStep; box?: boolean }) {
+  return (
+    <a
+      className={box ? "workflow-graph-link workflow-graph-box" : "workflow-graph-link"}
+      href={`#${cardId(path, step)}`}
+      data-map-stage={step.id}
+      data-stage-kind={step.kind}
+      data-optional={step.optional ? "true" : undefined}
+      aria-label={step.kind === "human" ? step.label : undefined}
+    >
+      {/* The legend explains the dot; the panel names the badge in words. */}
+      {step.badges.includes("openspec") ? (
+        <span className="workflow-graph-openspec" aria-hidden="true" />
+      ) : null}
+      {/* Inside the review group the group names the action, so only the artifact shows. */}
+      {step.kind === "human" ? step.artifact : step.label}
+    </a>
+  );
+}
+
+function StageCard({ path, step }: { path: WorkflowPath; step: WorkflowStep }) {
+  return (
+    <article
+      className="workflow-card"
+      id={cardId(path, step)}
+      data-stage={step.id}
+      data-stage-kind={step.kind}
+      data-optional={step.optional ? "true" : undefined}
+    >
+      <header className="workflow-card-header">
+        <div className="workflow-card-heading">
+          <h3>{step.label}</h3>
+          <WorkflowBadges badges={shownBadges(step)} />
+        </div>
+        <p className="workflow-card-meta">
+          <span>{PHASE_LABELS[step.phase]}</span>
+          {step.skill ? <code>{step.skill}</code> : null}
+          {step.sessionBreakBefore ? (
+            <span className="workflow-card-session">New session / clean chat</span>
+          ) : null}
+        </p>
+      </header>
+      <StageRun step={step} />
+      {step.missingSkill ? (
+        <p className="workflow-missing-skill" role="note">
+          Skill not reported for this companion: <code>{step.missingSkill}</code>. Run{" "}
+          <code>mate companion update</code>; this stage is not complete.
+        </p>
+      ) : null}
+      <dl className="workflow-card-explanation">
+        <div>
+          <dt>What</dt>
+          <dd>{step.what}</dd>
+        </div>
+        <div>
+          <dt>Why</dt>
+          <dd>{step.why}</dd>
+        </div>
+      </dl>
+      <footer className="workflow-card-footer">
+        <a href={`#${overviewId(path)}`}>Path overview</a>
+      </footer>
+    </article>
+  );
+}
+
+/** How a stage runs: a person's review, a choice of prompts, or its one prompt. */
+function StageRun({ step }: { step: WorkflowStep }) {
+  if (step.kind === "human") {
+    return (
+      <p className="workflow-card-human">Review {step.artifact} yourself — no skill, no prompt</p>
+    );
+  }
+  if (step.alternatives?.length) return <WorkflowOptions step={step} />;
+  if (!step.prompt) return null;
+  return (
+    <div className="workflow-command">
+      <span className="workflow-command-label">Run</span>
+      <code>{step.prompt}</code>
+      <WorkflowCopy text={step.copyPrompt ?? step.prompt} label={`${step.label} prompt`} />
+    </div>
+  );
+}
+
+function WorkflowOptions({ step }: { step: WorkflowStep }) {
+  if (!step.alternatives?.length) return null;
+  return (
+    <div className="workflow-option-list">
+      {step.alternatives.map((alternative) => (
+        <div key={alternative.name} className="workflow-option">
+          <div className="workflow-command">
+            <span className="workflow-command-label">Option</span>
+            <code>{alternative.prompt}</code>
+            <WorkflowCopy text={alternative.copyPrompt} label={`${alternative.name} prompt`} />
+          </div>
+          <small>{alternative.description}</small>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function WorkflowCopy({ text, label }: { text: string; label: string }) {
+  return (
+    <button type="button" className="runway-step-copy" data-copy={text} data-copy-label={label}>
+      Copy
+    </button>
+  );
+}
+
+/** The skill name already says a stage is a skill stage, so that badge is not shown. */
+const shownBadges = (step: WorkflowStep): WorkflowStepBadge[] =>
+  step.badges.filter((badge) => badge !== "skill");
+
+function WorkflowBadges({ badges }: { badges: WorkflowStepBadge[] }) {
+  return (
+    <span className="workflow-badges">
+      {badges.map((badge) => (
+        <em key={badge} className={`runway-step-badge runway-step-badge-${badge}`}>
+          {badge === "human-review" ? "Human review" : badge}
+        </em>
+      ))}
+    </span>
+  );
+}

package/src/cli/commands/studio/views/workflow/graph.ts

@@ -0,0 +1,220 @@
+import { PHASE_LABELS, type WorkflowPath, type WorkflowPhaseId, type WorkflowStep } from "./steps";
+
+/** Slot on the graph grid: a column per sequential position, a row per stacked peer. */
+interface GraphSlot {
+  column: number;
+  row: number;
+  rowSpan: number;
+}
+
+type ColumnNode =
+  | { id: "start"; kind: "start" }
+  | { id: string; kind: "stage"; step: WorkflowStep }
+  | { id: "reviews"; kind: "review-group"; steps: WorkflowStep[] };
+
+export type WorkflowGraphNode = GraphSlot & ColumnNode;
+
+export interface WorkflowGraphEdge {
+  from: string;
+  to: string;
+  /** A bypass skips an optional stage or run of optional peers. */
+  kind: "flow" | "bypass";
+  /** The stage the edge enters starts a new session. */
+  newSession: boolean;
+}
+
+/** A phase as a column range, `to` exclusive. */
+export interface WorkflowGraphBand {
+  phase: WorkflowPhaseId;
+  label: string;
+  from: number;
+  to: number;
+}
+
+export interface WorkflowGraph {
+  columns: number;
+  /** Node rows; the bypass lane below them is not counted. */
+  rows: number;
+  /** Stage order: columns left to right, peers top to bottom. */
+  nodes: WorkflowGraphNode[];
+  edges: WorkflowGraphEdge[];
+  bands: WorkflowGraphBand[];
+  /** Columns each change of a feature repeats, from the start to Archive change; `to` exclusive. */
+  cycle: { from: number; to: number } | null;
+}
+
+interface Column {
+  nodes: ColumnNode[];
+  optional: boolean;
+  phase: WorkflowPhaseId;
+}
+
+const stageNode = (step: WorkflowStep): ColumnNode => ({ id: step.id, kind: "stage", step });
+
+function columnsOf(path: WorkflowPath): Column[] {
+  const columns: Column[] = path.map.map((entry) => {
+    if (entry.kind === "stage") {
+      return {
+        nodes: [stageNode(entry.step)],
+        optional: entry.step.optional,
+        phase: entry.step.phase,
+      };
+    }
+    if (entry.group === "human") {
+      return {
+        nodes: [{ id: "reviews", kind: "review-group", steps: entry.steps }],
+        optional: false,
+        phase: entry.steps[0].phase,
+      };
+    }
+    return { nodes: entry.steps.map(stageNode), optional: true, phase: entry.steps[0].phase };
+  });
+  // The start marker anchors the bypass of a leading optional run and opens the cycle.
+  columns.unshift({
+    nodes: [{ id: "start", kind: "start" }],
+    optional: false,
+    phase: columns[0]?.phase ?? "plan",
+  });
+  return columns;
+}
+
+function entersNewSession(node: ColumnNode): boolean {
+  if (node.kind === "stage") return Boolean(node.step.sessionBreakBefore);
+  if (node.kind === "review-group") return Boolean(node.steps[0].sessionBreakBefore);
+  return false;
+}
+
+function edgesOf(columns: readonly Column[]): WorkflowGraphEdge[] {
+  const edges: WorkflowGraphEdge[] = [];
+  const link = (
+    from: readonly ColumnNode[],
+    to: readonly ColumnNode[],
+    kind: "flow" | "bypass",
+  ) => {
+    for (const a of from) {
+      for (const b of to)
+        edges.push({ from: a.id, to: b.id, kind, newSession: entersNewSession(b) });
+    }
+  };
+  columns.forEach((column, index) => {
+    const next = columns[index + 1];
+    if (next) link(column.nodes, next.nodes, "flow");
+    const before = columns[index - 1];
+    if (column.optional && before && next) link(before.nodes, next.nodes, "bypass");
+  });
+  return edges;
+}
+
+function bandsOf(columns: readonly Column[]): WorkflowGraphBand[] {
+  const bands: WorkflowGraphBand[] = [];
+  columns.forEach((column, index) => {
+    const band = bands.at(-1);
+    if (band?.phase === column.phase) {
+      band.to = index + 1;
+      return;
+    }
+    bands.push({
+      phase: column.phase,
+      label: PHASE_LABELS[column.phase],
+      from: index,
+      to: index + 1,
+    });
+  });
+  return bands;
+}
+
+/** Changes archive before they publish, so everything up to Archive change repeats per change. */
+function cycleOf(columns: readonly Column[]): WorkflowGraph["cycle"] {
+  const archive = columns.findIndex((column) => column.nodes.some((node) => node.id === "archive"));
+  return archive === -1 ? null : { from: 0, to: archive + 1 };
+}
+
+/** The path's node graph. Single nodes span every row; peers take a row each. */
+export function workflowGraph(path: WorkflowPath): WorkflowGraph {
+  const columns = columnsOf(path);
+  const rows = Math.max(1, ...columns.map((column) => column.nodes.length));
+  const nodes = columns.flatMap((column, index) =>
+    column.nodes.map((node, row): WorkflowGraphNode =>
+      column.nodes.length === 1
+        ? { ...node, column: index, row: 0, rowSpan: rows }
+        : { ...node, column: index, row, rowSpan: 1 },
+    ),
+  );
+  return {
+    columns: columns.length,
+    rows,
+    nodes,
+    edges: edgesOf(columns),
+    bands: bandsOf(columns),
+    cycle: cycleOf(columns),
+  };
+}
+
+/**
+ * Drawing units, top to bottom: one per column down the flow; two per node row across it,
+ * plus one for the bypass lane on the right. Node rows are laid out at `2fr` and the lane
+ * at `1fr` to match.
+ */
+export interface GraphPoint {
+  along: number;
+  across: number;
+}
+
+export const graphAcross = (graph: WorkflowGraph): number => graph.rows * 2 + 1;
+
+export function nodeCenter(node: WorkflowGraphNode): GraphPoint {
+  return { along: node.column + 0.5, across: node.row * 2 + node.rowSpan };
+}
+
+const round = (value: number): number => Math.round(value * 1e4) / 1e4;
+
+const percent = (part: number, whole: number): string => `${round((part / whole) * 100)}%`;
+
+/** An SVG `x y` pair: across is horizontal, along runs down. */
+const pair = ({ along, across }: GraphPoint): string => `${round(across)} ${round(along)}`;
+
+function endpoints(graph: WorkflowGraph, edge: WorkflowGraphEdge): [GraphPoint, GraphPoint] {
+  const at = (id: string): GraphPoint => {
+    const node = graph.nodes.find((candidate) => candidate.id === id);
+    if (!node) throw new Error(`Unknown graph node: ${id}`);
+    return nodeCenter(node);
+  };
+  return [at(edge.from), at(edge.to)];
+}
+
+/** Center to center: nodes are opaque and drawn over the edges, so a line meets each border. */
+export function edgePath(graph: WorkflowGraph, edge: WorkflowGraphEdge): string {
+  const [a, b] = endpoints(graph, edge);
+  if (edge.kind === "bypass") {
+    const lane = graphAcross(graph);
+    return `M ${pair(a)} C ${pair({ along: a.along, across: lane })}, ${pair({ along: b.along, across: lane })}, ${pair(b)}`;
+  }
+  const middle = (a.along + b.along) / 2;
+  return `M ${pair(a)} C ${pair({ along: middle, across: a.across })}, ${pair({ along: middle, across: b.across })}, ${pair(b)}`;
+}
+
+/** Midpoint of an edge's curve, where a new-session mark sits. */
+export function edgeMidpoint(graph: WorkflowGraph, edge: WorkflowGraphEdge): GraphPoint {
+  const [a, b] = endpoints(graph, edge);
+  const along = (a.along + b.along) / 2;
+  if (edge.kind === "bypass") {
+    return { along, across: (a.across + b.across) / 8 + (graphAcross(graph) * 3) / 4 };
+  }
+  return { along, across: (a.across + b.across) / 2 };
+}
+
+/** A point as percentages of the drawing, for undistorted marks. */
+export function percentOf(graph: WorkflowGraph, point: GraphPoint): { x: string; y: string } {
+  return { x: percent(point.across, graphAcross(graph)), y: percent(point.along, graph.columns) };
+}
+
+/** A column range's vertical extent as percentages of the drawing: a band or the cycle. */
+export function bandSpan(
+  graph: WorkflowGraph,
+  band: { from: number; to: number },
+): { top: string; height: string } {
+  return {
+    top: percent(band.from, graph.columns),
+    height: percent(band.to - band.from, graph.columns),
+  };
+}

package/src/cli/commands/studio/views/workflow/index.tsx

@@ -2,7 +2,7 @@
 
 import type { StudioCompanionPayload } from "../../payload";
 import { Warnings } from "../warnings";
-import { WorkflowTranscript } from "./transcript";
+import { DeliveryPathView } from "./delivery-path";
 
 interface WorkflowProps {
   payload: StudioCompanionPayload;
@@ -12,8 +12,7 @@ export function Workflow({ payload }: WorkflowProps) {
   return (
     <>
       <div className="workflow-view">
-        <div className="workflow-eyebrow">Workflow</div>
-        <WorkflowTranscript payload={payload} />
+        <DeliveryPathView payload={payload} />
       </div>
       <Warnings warnings={payload.warnings} />
     </>