@patwoodman/dsh-sdlc-flow-ui 0.4.0-beta.23 → 0.4.0-beta.24

package/README.md

@@ -5,6 +5,7 @@ sidebar, plus the host routes that feed it.
 
 | Panel | What it shows |
 |---|---|
+| Flow | live task DAG, subagent runs, routing, gates, locks, escalations and events |
 | Status | live project, task and spend summary from `sdlc.db` |
 | Board | tasks grouped by state-machine state |
 | Config | a validated editor for `.sdlc/config.yml` (writes are rejected when validation fails) |
@@ -12,7 +13,13 @@ sidebar, plus the host routes that feed it.
 
 Host routes: `/api/sdlc.status`, `/api/sdlc.board`, `/api/sdlc.task`,
 `/api/sdlc.compare`, `/api/sdlc.config` (GET + validated POST),
-`/api/sdlc.metrics`.
+`/api/sdlc.metrics`, `/api/sdlc.flow` (bounded visualizer snapshot).
+
+The tab is registered as a right-sidebar page with a guide entry, so a new
+session can open it from the guide's **SDLC Flow** capsule. With
+`autoOpen: true` (the shipped default) it also opens once for the first session
+that has an SDLC project; the Flow panel polls every 5 s and keeps the last
+snapshot as *stale* when a poll fails.
 
 `lib/client.js` is a prebuilt closure-factory bundle that registers into the
 right-sidebar slot system; it needs no build step on the consumer's machine.
@@ -31,7 +38,7 @@ It must never be mounted in the headless worker profile (E6).
 ## Requirements
 
 - `@deepseek-ai/dsh` `>=0.2.0-rc.2 <0.3.0-0`
-- Node.js ≥ 22.5
+- Node.js ≥ 22.13
 - a profile whose client platform is `web`
 
 ## License

package/cordis.patch.yml

@@ -8,4 +8,5 @@
 - insert:
     - id: sdlc-ui
       name: '@patwoodman/dsh-sdlc-flow-ui'
-      config: {}
+      config:
+        autoOpen: true

package/lib/client/SdlcTab.css

@@ -36,3 +36,164 @@
 .sdlc-root ul {
   padding-left: 20px;
 }
+
+/* Flow visualizer */
+.sdlc-flow {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.sdlc-flow-head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.sdlc-muted {
+  color: #888;
+  font-size: 12px;
+}
+.sdlc-warn {
+  color: #9a6700;
+  background: #9a670014;
+  border: 1px solid #9a670033;
+  border-radius: 6px;
+  padding: 4px 8px;
+}
+.sdlc-bad {
+  color: #b42318;
+}
+.sdlc-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+.sdlc-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  border: 1px solid #8884;
+  border-radius: 999px;
+  padding: 1px 8px;
+  font-size: 12px;
+  white-space: nowrap;
+}
+.sdlc-tone-idle { background: #88888814; }
+.sdlc-tone-ready { background: #2563eb14; }
+.sdlc-tone-running { background: #7c3aed14; }
+.sdlc-tone-verify { background: #0891b214; }
+.sdlc-tone-merge { background: #ca8a0414; }
+.sdlc-tone-good { background: #16803c14; }
+.sdlc-tone-warn { background: #9a670014; }
+.sdlc-tone-bad { background: #b4231814; }
+
+.sdlc-dag {
+  position: relative;
+  overflow: auto;
+  border: 1px solid #8883;
+  border-radius: 8px;
+  background-image: radial-gradient(#8882 1px, transparent 1px);
+  background-size: 16px 16px;
+  min-height: 120px;
+}
+.sdlc-dag-edges {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+.sdlc-edge {
+  fill: none;
+  stroke: #8888;
+  stroke-width: 1.5;
+}
+.sdlc-edge.bad {
+  stroke: #b42318;
+  stroke-dasharray: 4 3;
+}
+.sdlc-node {
+  position: absolute;
+  width: 168px;
+  min-height: 52px;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  text-align: left;
+  padding: 6px 8px;
+  border: 1px solid #8885;
+  border-radius: 8px;
+  background: Canvas;
+  color: CanvasText;
+  font: inherit;
+  cursor: pointer;
+  box-shadow: 0 1px 2px #0001;
+}
+.sdlc-node:hover {
+  border-color: #888;
+}
+.sdlc-node-id {
+  font-weight: 600;
+  font-size: 12px;
+}
+.sdlc-node-state {
+  font-size: 11px;
+  letter-spacing: 0.02em;
+}
+.sdlc-node-meta,
+.sdlc-node-deps {
+  font-size: 11px;
+  color: #777;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.sdlc-flow-section h3 {
+  margin: 8px 0 4px;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: #777;
+}
+.sdlc-run-list,
+.sdlc-routing-list,
+.sdlc-gate-list,
+.sdlc-lock-list,
+.sdlc-escalation-list,
+.sdlc-event-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.sdlc-run {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  align-items: center;
+  padding: 4px 6px;
+  border-radius: 6px;
+  font-size: 12px;
+}
+.sdlc-run-role {
+  font-weight: 600;
+}
+.sdlc-run-id {
+  color: #777;
+  font-family: ui-monospace, SFMono-Regular, monospace;
+}
+.sdlc-route {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  align-items: center;
+  font-size: 12px;
+}
+.sdlc-route-task {
+  font-weight: 600;
+}
+.sdlc-event-list li {
+  font-size: 12px;
+  border-bottom: 1px solid #8882;
+  padding: 2px 0;
+}

package/lib/client/SdlcTab.jsx

@@ -12,17 +12,25 @@
  * onClick below (single-expression arrows are fine).
  */
 
-import { useState, useSyncExternalStore } from 'react';
-import { StatusPanel, BoardPanel, ConfigPanel, ReviewPanel } from './panels.jsx';
+import { useState, useSyncExternalStore, useEffect } from 'react';
+import { StatusPanel, BoardPanel, ConfigPanel, ReviewPanel, FlowPanel } from './panels.jsx';
 
-const PANELS = ['status', 'board', 'config', 'review'];
+const PANELS = ['flow', 'status', 'board', 'config', 'review'];
 
 export function SdlcTab({ stores, t }) {
-  const [panel, setPanel] = useState('status');
+  const [panel, setPanel] = useState('flow');
   const status = useSyncExternalStore(stores.status.subscribe, stores.status.getSnapshot);
   const board = useSyncExternalStore(stores.board.subscribe, stores.board.getSnapshot);
   const config = useSyncExternalStore(stores.config.subscribe, stores.config.getSnapshot);
   const review = useSyncExternalStore(stores.review.subscribe, stores.review.getSnapshot);
+  const flow = useSyncExternalStore(stores.flow.subscribe, stores.flow.getSnapshot);
+
+  useEffect(() => {
+    if (panel !== 'flow') return undefined;
+    stores.loadFlow();
+    const timer = setInterval(() => { stores.loadFlow(); }, 5000);
+    return () => clearInterval(timer);
+  }, [panel, stores]);
 
   const selectPanel = (p) => setPanel(p);
   const openTaskReview = (taskId) => {
@@ -34,6 +42,7 @@ export function SdlcTab({ stores, t }) {
   const reloadConfig = () => stores.loadConfig();
   const saveConfig = (path, value) => stores.saveConfig(path, value);
   const loadCompare = (task, a, b) => stores.loadCompare(task, a, b);
+  const loadFlow = () => stores.loadFlow();
 
   return (
     <div className="sdlc-root">
@@ -44,12 +53,13 @@ export function SdlcTab({ stores, t }) {
             role="tab"
             type="button"
             aria-selected={panel === p}
-            onClick={selectPanel}
+            onClick={() => selectPanel(p)}
           >
             {t(`panel.${p}`)}
           </button>
         ))}
       </div>
+      {panel === 'flow' && <FlowPanel snapshot={flow} onReload={loadFlow} onSelectTask={openTaskReview} t={t} />}
       {panel === 'status' && <StatusPanel snapshot={status} onReload={reloadStatus} />}
       {panel === 'board' && (
         <BoardPanel

package/lib/client/api.js

@@ -8,8 +8,8 @@
 
 import {
   SDLC_STATUS_ROUTE, SDLC_BOARD_ROUTE, SDLC_TASK_ROUTE, SDLC_COMPARE_ROUTE,
-  SDLC_CONFIG_ROUTE, SDLC_METRICS_ROUTE,
-  isStatusPayload, isBoardPayload, isConfigPayload,
+  SDLC_CONFIG_ROUTE, SDLC_METRICS_ROUTE, SDLC_FLOW_ROUTE,
+  isStatusPayload, isBoardPayload, isConfigPayload, isFlowPayload,
 } from '../routes.js';
 
 async function getJson(path) {
@@ -94,6 +94,15 @@ export async function fetchMetrics() {
   }
 }
 
+export async function fetchFlow({ task = null, events = 100, after = 0 } = {}) {
+  const params = new URLSearchParams({ events: String(events), after: String(after) });
+  if (task) params.set('task', task);
+  const res = await getJson(`${SDLC_FLOW_ROUTE}?${params}`);
+  if (!res.available) return res;
+  if (!isFlowPayload(res.data)) return { available: false, reason: 'host returned a malformed flow payload' };
+  return res;
+}
+
 /**
  * The single api face the client consumes. NAMED on purpose: the closure-factory
  * bundle concatenates the client sources into one scope, where a default import
@@ -101,6 +110,6 @@ export async function fetchMetrics() {
  * apply — shipped broken until the entry contract test called apply). The
  * default export stays for source-level ergonomics; the bundler strips it.
  */
-export const api = { fetchStatus, fetchBoard, fetchTask, fetchCompare, fetchConfig, writeConfig, fetchMetrics };
+export const api = { fetchStatus, fetchBoard, fetchTask, fetchCompare, fetchConfig, writeConfig, fetchMetrics, fetchFlow };
 
 export default api;

package/lib/client/definition.js

@@ -17,6 +17,14 @@ export function sdlcDefinition(t) {
     kind: SDLC_KIND,
     priority: 'builtin',
     title: () => t('tab.title'),
+    // The guide is the only user-reachable door for a pure page type: without
+    // an entry the type registers but no new session can ever open it.
+    guide: [{
+      id: 'flow',
+      order: 30,
+      title: () => t('guide.title'),
+      description: () => t('guide.description'),
+    }],
   };
 }
 

package/lib/client/flow.js

@@ -0,0 +1,98 @@
+/**
+ * packages/sdlc-client-ui/src/client/flow.js — pure geometry/labels for the
+ * flow visualizer. No React, no DOM: the panel stays declarative and this can
+ * be unit-tested directly.
+ */
+
+export const STATE_TONE = {
+  BACKLOG: 'idle',
+  READY: 'ready',
+  ASSIGNED: 'running',
+  IN_PROGRESS: 'running',
+  VERIFYING: 'verify',
+  ACCEPTED: 'good',
+  MERGING: 'merge',
+  DONE: 'good',
+  FAILED: 'bad',
+  ESCALATED: 'bad',
+  BLOCKED: 'warn',
+  CANCELLED: 'idle',
+};
+
+export function formatDuration(ms) {
+  if (ms == null) return '—';
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60_000).toFixed(1)}m`;
+}
+
+export function formatTokens(tokens) {
+  return tokens == null ? '—' : Number(tokens).toLocaleString('en-US');
+}
+
+export function formatCost(cost) {
+  return cost == null ? '—' : `$${Number(cost).toFixed(4)}`;
+}
+
+/** Convert the host payload into render-ready geometry. */
+export function buildFlowView(data) {
+  const nodes = Array.isArray(data?.tasks) ? data.tasks : [];
+  const rawEdges = Array.isArray(data?.edges) ? data.edges : [];
+  const byLayer = new Map();
+  for (const node of nodes) {
+    const layer = Number.isFinite(node.layer) ? node.layer : 0;
+    if (!byLayer.has(layer)) byLayer.set(layer, []);
+    byLayer.get(layer).push(node);
+  }
+
+  const X = 210;
+  const Y = 78;
+  const placed = new Map();
+  let maxPerLayer = 1;
+  for (const [layer, list] of [...byLayer.entries()].sort((a, b) => a[0] - b[0])) {
+    list.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+    maxPerLayer = Math.max(maxPerLayer, list.length);
+    list.forEach((node, index) => {
+      placed.set(node.id, { ...node, x: 24 + layer * X, y: 24 + index * Y });
+    });
+  }
+
+  const edges = rawEdges.map((edge) => {
+    const from = placed.get(edge.from);
+    const to = placed.get(edge.to);
+    if (!from || !to) return null;
+    const x1 = from.x + 168;
+    const y1 = from.y + 28;
+    const x2 = to.x;
+    const y2 = to.y + 28;
+    const mid = x1 + Math.max(36, (x2 - x1) / 2);
+    return {
+      ...edge,
+      key: `${edge.from}->${edge.to}`,
+      d: `M ${x1} ${y1} C ${mid} ${y1}, ${mid} ${y2}, ${x2} ${y2}`,
+      bad: Boolean(edge.missing),
+    };
+  }).filter(Boolean);
+
+  const layers = [...byLayer.keys()].sort((a, b) => a - b);
+  return {
+    nodes: [...placed.values()],
+    edges,
+    layers,
+    width: 24 + (layers.length ? (layers.at(-1) + 1) * X : X),
+    height: 24 + maxPerLayer * Y,
+    runs: Array.isArray(data?.runs) ? data.runs : [],
+    routing: Array.isArray(data?.routing) ? data.routing : [],
+    gates: Array.isArray(data?.gates) ? data.gates : [],
+    gateSummary: data?.gateSummary ?? { pass: 0, fail: 0, skipped: 0, unknown: 0, total: 0 },
+    events: Array.isArray(data?.events) ? data.events : [],
+    escalations: Array.isArray(data?.escalations) ? data.escalations : [],
+    locks: data?.locks ?? { cap: 1, resources: [], pathOwners: [], violations: [] },
+    totals: data?.totals ?? {},
+    project: data?.project ?? { available: false, reason: 'no payload' },
+    unavailable: Array.isArray(data?.unavailable) ? data.unavailable : [],
+    tasksTruncated: Boolean(data?.totals?.tasksTruncated),
+  };
+}
+
+export default { buildFlowView, STATE_TONE, formatDuration, formatTokens, formatCost };

package/lib/client/index.js

@@ -8,9 +8,9 @@
  */
 
 import { api } from './api.js';
-import { createSdlcStores } from './store.js';
+import { createSdlcStores, createSdlcStoreHandle } from './store.js';
 import { NS, en, zh } from './locales.js';
-import { SDLC_ID, sdlcDefinition } from './definition.js';
+import { SDLC_ID, SDLC_KIND, sdlcDefinition } from './definition.js';
 import { SdlcTab, SdlcTitle } from './SdlcTab.jsx';
 
 /** Required browser services: tab registry, keyed seats, Remote, copy. */
@@ -20,18 +20,19 @@ export const inject = ['slots', 'locale', 'sidebarRightTabs', 'sidebarRight', 'r
  * Client plugin body: register dictionaries, the tab type, and the tab body.
  * @param ctx - client root context.
  */
-export function apply(ctx) {
+export function apply(ctx, config = {}) {
   const t = ctx.locale.bind(NS);
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'sdlc-ui: dictionaries');
   ctx.effect(() => ctx.sidebarRightTabs.register(sdlcDefinition(t)), 'sdlc-ui: sdlc tab type');
 
   const stores = createSdlcStores(api);
+  const storeHandle = createSdlcStoreHandle(stores);
   ctx.effect(() => () => stores.dispose(), 'sdlc-ui: dispose');
   ctx.on('connection/reset', () => stores.reset());
 
   ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register(
     {
-      name: 'sidebar.right.pane.tab', key: SDLC_ID, locale: NS, store: stores,
+      name: 'sidebar.right.pane.tab', key: SDLC_ID, locale: NS, store: storeHandle,
       inject: () => ({ stores, t }),
     },
     SdlcTab,
@@ -40,6 +41,30 @@ export function apply(ctx) {
     { name: 'sidebar.right.pane.tab.title', key: SDLC_ID },
     (props) => SdlcTitle({ ...props, t }),
   )), 'sdlc-ui: sdlc tab title');
+
+  // The right sidebar has no surface without a session, and a page type is
+  // reachable only through the guide or an explicit openTab. Open the flow
+  // panel once per page load for the first session that has an SDLC project,
+  // so the visualizer is actually seen (config.autoOpen === false opts out).
+  if (config.autoOpen !== false && typeof ctx.sidebarRight?.mounted?.subscribe === 'function') {
+    let opened = false;
+    let checking = false;
+    const maybeOpen = async () => {
+      if (opened || checking || !ctx.sidebarRight.mounted.getSnapshot()) return;
+      checking = true;
+      try {
+        const status = await api.fetchStatus();
+        if (status.available && status.data.tasks.total > 0) {
+          opened = true;
+          try { ctx.sidebarRight.openTab(SDLC_KIND); } catch { /* no surface yet */ }
+        }
+      } finally {
+        checking = false;
+      }
+    };
+    const unsubscribe = ctx.sidebarRight.mounted.subscribe(() => { void maybeOpen(); });
+    ctx.effect(() => () => { unsubscribe?.(); }, 'sdlc-ui: auto-open flow panel');
+  }
 }
 
 // The closure bundle strips this line and re-attaches the same object as

package/lib/client/locales.js

@@ -33,6 +33,31 @@ export const en = {
   'panel.board': 'Board',
   'panel.config': 'Config',
   'panel.review': 'Review',
+  'guide.title': 'SDLC Flow',
+  'guide.description': 'Agents, routing, gates and the live task DAG',
+  'panel.flow': 'Flow',
+  'flow.loading': 'Loading the flow view…',
+  'flow.reload': 'Reload',
+  'flow.tasks': 'tasks',
+  'flow.active': 'active',
+  'flow.estimated': 'est.',
+  'flow.stale': 'Stale snapshot',
+  'flow.truncated': 'Showing the first tasks only; the DAG is truncated.',
+  'flow.empty': 'No tasks yet — the DAG appears once the planner creates work.',
+  'flow.dagLabel': 'Task DAG: {tasks} tasks, {edges} edges',
+  'flow.summary': 'Flow summary',
+  'flow.pass': 'pass',
+  'flow.fail': 'fail',
+  'flow.skipped': 'skipped',
+  'flow.unknown': 'unknown',
+  'flow.subagents': 'Subagents',
+  'flow.noRuns': 'No worker runs yet.',
+  'flow.routing': 'Routing',
+  'flow.gates': 'Gates',
+  'flow.locks': 'Resource locks',
+  'flow.noResources': 'No active resource locks.',
+  'flow.escalations': 'Escalations',
+  'flow.events': 'Recent events',
 };
 
 /** Simplified Chinese dictionary. */
@@ -63,6 +88,31 @@ export const zh = {
   'panel.board': '看板',
   'panel.config': '配置',
   'panel.review': '复核',
+  'guide.title': 'SDLC 流程',
+  'guide.description': '子代理、路由、门禁与实时任务 DAG',
+  'panel.flow': '流程',
+  'flow.loading': '正在加载流程视图…',
+  'flow.reload': '刷新',
+  'flow.tasks': '个任务',
+  'flow.active': '活跃',
+  'flow.estimated': '估算',
+  'flow.stale': '快照已过期',
+  'flow.truncated': '仅显示前部分任务，DAG 已截断。',
+  'flow.empty': '暂无任务 — 规划器创建任务后会出现 DAG。',
+  'flow.dagLabel': '任务 DAG：{tasks} 个任务，{edges} 条边',
+  'flow.summary': '流程摘要',
+  'flow.pass': '通过',
+  'flow.fail': '失败',
+  'flow.skipped': '跳过',
+  'flow.unknown': '未知',
+  'flow.subagents': '子代理',
+  'flow.noRuns': '暂无工作进程运行。',
+  'flow.routing': '路由',
+  'flow.gates': '门禁',
+  'flow.locks': '资源锁',
+  'flow.noResources': '没有活跃的资源锁。',
+  'flow.escalations': '升级',
+  'flow.events': '最近事件',
 };
 
 export default { NS, en, zh };