@seanmars/tospec 0.23.0 → 0.24.0

package/assets/dashboard/views/session.js

@@ -0,0 +1,270 @@
+// The session panel: one session's live log, and the question it waits on.
+// The page answers what a session asked and nothing more: there is no box to
+// type a prompt into, so every instruction still comes from the terminal. It
+// sits beside whatever page is open and survives navigation.
+//
+// Built once per opened session and updated in place on every push: a
+// rebuilt panel would wipe a half-chosen answer and steal the keyboard focus.
+
+import { el, icon, activityDot, lineBadge } from '../lib/dom.js';
+import { sessionStatus, sessionDetail, ACTIVITY_LABEL } from '../lib/derive.js';
+import { store, projectByKey, slotOf, logId, loadSessionLog, forgetSessionLog, answerAsk } from '../lib/store.js';
+
+const KIND_LABEL = { prompt: '你', reply: 'Claude', ask: '問題', answer: '回答', permission: '權限' };
+const LOG_LIMIT = 200;
+
+const panel = {
+  key: null,
+  session: null,
+  opener: null,
+  /** The highest event number drawn, so a push appends only what is new. */
+  drawnSeq: 0,
+  /** The ask drawn in the ask area; undefined until the first draw. */
+  askId: undefined,
+  dom: null,
+};
+
+function host() {
+  return document.getElementById('session-panel');
+}
+
+export function isSessionPanelOpen(key, session) {
+  return panel.key === key && panel.session === session;
+}
+
+export function openSessionPanel(key, session) {
+  if (panel.key && !isSessionPanelOpen(key, session)) forgetSessionLog(panel.key, panel.session);
+  const opener = document.activeElement;
+  Object.assign(panel, { key, session, opener, drawnSeq: 0, askId: undefined });
+  build();
+  const node = host();
+  node.hidden = false;
+  document.body.classList.add('has-session-panel');
+  loadSessionLog(key, session);
+  updateSessionPanel();
+  panel.dom.title.focus({ preventScroll: true });
+}
+
+export function closeSessionPanel() {
+  if (!panel.key) return;
+  forgetSessionLog(panel.key, panel.session);
+  const opener = panel.opener;
+  Object.assign(panel, { key: null, session: null, opener: null, dom: null });
+  host().hidden = true;
+  host().replaceChildren();
+  document.body.classList.remove('has-session-panel');
+  if (opener && opener.isConnected) opener.focus({ preventScroll: true });
+}
+
+function build() {
+  const close = el('button', { type: 'button', class: 'icon-button', title: '關閉' }, [icon('close', 14), el('span', { class: 'sr-only', text: '關閉 session 面板' })]);
+  close.addEventListener('click', closeSessionPanel);
+  const title = el('h2', { id: 'session-panel-title', class: 'sp-title', tabindex: '-1' }, [
+    el('span', { text: 'Session ' }),
+    el('span', { class: 'mono', text: panel.session.slice(0, 8) }),
+  ]);
+  const dot = el('span', { class: 'sp-dot' });
+  const status = el('p', { class: 'sp-status' });
+  const log = el('ol', { class: 'sp-log', 'aria-label': 'session log', 'aria-live': 'polite' });
+  const logNote = el('p', { class: 'sp-log-note' });
+  const ask = el('section', { class: 'sp-ask', 'aria-label': '等待回答' });
+  ask.hidden = true;
+  const foot = el('p', { class: 'sp-foot' });
+  const node = host();
+  node.setAttribute('aria-labelledby', 'session-panel-title');
+  node.replaceChildren(
+    el('header', { class: 'sp-head' }, [el('div', { class: 'sp-head-row' }, [dot, title, close]), status]),
+    el('div', { class: 'sp-scroll' }, [logNote, log]),
+    ask,
+    foot
+  );
+  node.onkeydown = (event) => {
+    if (event.key === 'Escape') closeSessionPanel();
+  };
+  panel.dom = { title, dot, status, log, logNote, ask, foot };
+}
+
+/** Brings the open panel up to date with the store; cheap when nothing changed. */
+export function updateSessionPanel() {
+  if (!panel.key || !panel.dom) return;
+  const project = projectByKey(panel.key);
+  const session = project && project.sessions.find((s) => s.id === panel.session);
+  const dom = panel.dom;
+  const now = Date.now();
+
+  const status = session ? sessionStatus(session) : 'offline';
+  dom.dot.replaceChildren(activityDot(status));
+  const detail = session ? sessionDetail(session, now) : '這個 session 已經離開 dashboard.';
+  // Filtered: the native replaceChildren writes a null out as the text "null".
+  dom.status.replaceChildren(...[
+    project ? lineBadge(project.name, slotOf(project.key)) : null,
+    el('strong', { text: ACTIVITY_LABEL[status] }),
+    detail ? el('span', { class: 'sp-detail', text: detail }) : null,
+  ].filter(Boolean));
+
+  drawLog();
+  drawAsk(session);
+  dom.foot.textContent = store.interactive
+    ? '這裡只能回答 session 提出的問題; 其他指示請在 terminal 輸入.'
+    : '這個 dashboard 對外開放 (--allow-remote), 只能檢視.';
+}
+
+function drawLog() {
+  const dom = panel.dom;
+  const log = store.logs.get(logId(panel.key, panel.session));
+  if (!log) {
+    dom.logNote.textContent = '正在讀取 log.';
+    return;
+  }
+  dom.logNote.textContent = log.error ? 'log 讀取失敗: ' + log.error : log.events.length ? '' : '這個 session 還沒有活動. 它下一次動作時會出現在這裡.';
+  const events = log.events;
+  const last = events.length ? events[events.length - 1].seq : 0;
+  // Numbers restart when a session expires and comes back: draw the log anew.
+  if (last < panel.drawnSeq) {
+    dom.log.replaceChildren();
+    panel.drawnSeq = 0;
+  }
+  const fresh = events.filter((e) => e.seq > panel.drawnSeq);
+  if (!fresh.length) return;
+  const scroller = dom.log.parentElement;
+  const atBottom = scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight < 48;
+  for (const event of fresh) dom.log.append(logRow(event));
+  while (dom.log.children.length > LOG_LIMIT) dom.log.firstElementChild.remove();
+  panel.drawnSeq = last;
+  if (atBottom) scroller.scrollTop = scroller.scrollHeight;
+}
+
+function clock(at) {
+  const d = new Date(at);
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+function logRow(event) {
+  const isTool = event.kind === 'tool';
+  const failed = event.ok === false;
+  const body = isTool
+    ? [el('span', { class: 'mono sp-target', text: event.target || '' }), el('span', { class: 'sp-mark', text: failed ? '失敗' : '完成' })]
+    : event.kind === 'permission'
+      ? [el('span', { class: 'mono sp-target', text: `${event.tool || ''} ${event.target || ''}`.trim() }), ' ', event.text || '']
+      : [event.text || ''];
+  return el('li', { class: 'sp-entry kind-' + event.kind + (failed ? ' is-fail' : '') }, [
+    el('time', { class: 'sp-time num', datetime: event.at, text: clock(event.at) }),
+    el('span', { class: 'sp-who' + (isTool ? ' mono' : ''), text: isTool ? event.tool : KIND_LABEL[event.kind] || event.kind }),
+    el('span', { class: 'sp-body' }, body),
+  ]);
+}
+
+// --- what the session waits on -------------------------------------------------------
+
+function drawAsk(session) {
+  const dom = panel.dom;
+  const ask = session && session.ask;
+  const id = ask ? ask.id : null;
+  if (id === panel.askId) return;
+  panel.askId = id;
+  dom.ask.hidden = !ask;
+  if (!ask) {
+    dom.ask.replaceChildren();
+    return;
+  }
+  dom.ask.replaceChildren(...(ask.kind === 'permission' ? permissionForm(ask) : questionForm(ask)).filter(Boolean));
+}
+
+function readOnlyNote() {
+  return store.interactive ? null : el('p', { class: 'sp-hint', text: '這個 dashboard 對外開放 (--allow-remote), 只能檢視; 請在 terminal 回答.' });
+}
+
+async function submitAnswer(ask, answer, controls, status) {
+  const { key, session } = panel;
+  for (const control of controls) control.disabled = true;
+  status.textContent = '正在送出.';
+  try {
+    await answerAsk(key, session, ask.id, answer);
+    status.textContent = '已送出.';
+  } catch (e) {
+    // 404: the terminal answered first, and the question is being withdrawn.
+    status.textContent = e.status === 404 ? '這個問題已經在 terminal 回答, 或已撤回.' : '沒有送出: ' + e.message;
+    if (e.status !== 404) for (const control of controls) control.disabled = false;
+  }
+}
+
+function questionForm(ask) {
+  const status = el('p', { class: 'sp-hint', 'aria-live': 'polite' });
+  const controls = [];
+  const fields = ask.questions.map((q, qi) => {
+    const name = 'sp-q-' + qi;
+    const type = q.multiSelect ? 'checkbox' : 'radio';
+    const options = q.options.map((option) => {
+      const input = el('input', { type, name, value: option.label });
+      controls.push(input);
+      return el('label', { class: 'sp-option' }, [
+        input,
+        el('span', {}, [el('strong', { text: option.label }), option.description ? el('span', { class: 'sp-option-desc', text: option.description }) : null]),
+      ]);
+    });
+    const otherPick = el('input', { type, name, value: '' });
+    const other = el('input', { type: 'text', class: 'sp-other', placeholder: '其他 (自行輸入)', 'aria-label': q.question + ' 其他答案' });
+    other.addEventListener('input', () => {
+      otherPick.checked = other.value.trim() !== '';
+    });
+    controls.push(otherPick, other);
+    return {
+      q,
+      node: el('fieldset', { class: 'sp-question' }, [
+        el('legend', {}, [q.header ? el('span', { class: 'tag', text: q.header }) : null, ' ', q.question]),
+        ...options,
+        el('label', { class: 'sp-option sp-option-other' }, [otherPick, other]),
+      ]),
+      read: () => {
+        const picked = [...document.getElementsByName(name)].filter((i) => i.checked && i.value).map((i) => i.value);
+        const typed = otherPick.checked ? other.value.trim() : '';
+        if (typed) picked.push(typed);
+        // AskUserQuestion's own form joins a multi-select answer with commas.
+        return picked.join(', ');
+      },
+    };
+  });
+  const send = el('button', { type: 'submit', class: 'button button-primary', text: '送出回答' });
+  controls.push(send);
+  const form = el('form', { class: 'sp-ask-form' }, [
+    el('p', { class: 'sp-ask-title', text: 'Claude 在問你' }),
+    el('p', { class: 'sp-hint sp-ask-hint', text: 'Terminal 也在詢問; 先回答的一方有效, 另一方會自動撤回.' }),
+    ...fields.map((f) => f.node),
+    el('div', { class: 'sp-form-foot' }, [status, send]),
+    readOnlyNote(),
+  ]);
+  if (!store.interactive) for (const control of controls) control.disabled = true;
+  form.addEventListener('submit', (event) => {
+    event.preventDefault();
+    const answers = {};
+    for (const field of fields) {
+      const value = field.read();
+      if (!value) {
+        status.textContent = '每一題都要回答: ' + field.q.question;
+        return;
+      }
+      answers[field.q.question] = value;
+    }
+    submitAnswer(ask, { answers }, controls, status);
+  });
+  return [form];
+}
+
+function permissionForm(ask) {
+  const status = el('p', { class: 'sp-hint', 'aria-live': 'polite' });
+  const allow = el('button', { type: 'button', class: 'button button-primary', text: '允許' });
+  const deny = el('button', { type: 'button', class: 'button', text: '拒絕' });
+  const controls = [allow, deny];
+  if (!store.interactive) for (const control of controls) control.disabled = true;
+  allow.addEventListener('click', () => submitAnswer(ask, { allow: true }, controls, status));
+  deny.addEventListener('click', () => submitAnswer(ask, { allow: false }, controls, status));
+  return [
+    el('p', { class: 'sp-ask-title', text: 'Claude 要求權限' }),
+    el('p', { class: 'sp-permission' }, [el('strong', { class: 'mono', text: ask.tool }), ' ', el('code', { class: 'sp-target', text: ask.target })]),
+    el('p', { class: 'sp-hint', text: 'Terminal 也在詢問; 先回答的一方有效, 另一方會自動撤回.' }),
+    el('div', { class: 'sp-actions' }, [deny, allow]),
+    status,
+    readOnlyNote(),
+  ];
+}

package/assets/dashboard/views/sidebar.js

@@ -0,0 +1,131 @@
+// The sidebar: every project with its live sessions, each expandable to its
+// changes, so any page is one click from the overview, its project, or a
+// sibling change. Below 960px it becomes a drawer the sign bar opens.
+
+import { el, marker, paintLine, icon, activityDot } from '../lib/dom.js';
+import { signalOf, lineSignal, staleDaysOf, projectActivity, sessionStatus, ACTIVITY_LABEL, SIGNAL_LABEL } from '../lib/derive.js';
+import { store, dataOf, slotOf } from '../lib/store.js';
+import { routes } from '../lib/routes.js';
+
+/** key -> open, for projects the person toggled; the current project is open unless closed. */
+const toggled = new Map();
+let lastSignature = null;
+
+function isOpen(key, route) {
+  return toggled.has(key) ? toggled.get(key) : key === route.key;
+}
+
+/**
+ * Everything the sidebar draws, so a push that changes none of it (most do:
+ * a snapshot of a project whose list is the same) leaves the DOM, and the
+ * keyboard focus inside it, alone.
+ */
+function signature(route, now) {
+  return JSON.stringify([
+    route.view,
+    route.key,
+    route.name,
+    [...toggled],
+    store.projects.map((p) => {
+      const data = dataOf(p.key);
+      const staleDays = staleDaysOf(data);
+      const changes = data.overview ? data.overview.changes.map((c) => [c.name, lineSignal(signalOf(c, staleDays, now), p.online)]) : null;
+      return [p.key, p.name, slotOf(p.key), p.online, p.sessions.map(sessionStatus), changes];
+    }),
+  ]);
+}
+
+export function renderSidebar(host, route) {
+  const now = Date.now();
+  const sig = signature(route, now);
+  if (sig === lastSignature) return;
+  lastSignature = sig;
+
+  // A redraw replaces the links; put the focus back on the one that had it.
+  const focusedHref = host.contains(document.activeElement) ? document.activeElement.getAttribute('href') : null;
+
+  const sessionTotal = store.projects.reduce((n, p) => n + p.sessions.length, 0);
+  const working = store.projects.reduce((n, p) => n + p.sessions.filter((s) => sessionStatus(s) === 'working').length, 0);
+  const waiting = store.projects.reduce((n, p) => n + p.sessions.filter((s) => sessionStatus(s) === 'waiting').length, 0);
+
+  const list = el('ul', { class: 'side-projects' }, store.projects.map((project) => projectItem(project, route, now)));
+  const foot = [`${sessionTotal} 個 session`];
+  if (working) foot.push(`${working} 個工作中`);
+  if (waiting) foot.push(`${waiting} 個等你回覆`);
+
+  host.replaceChildren(
+    el('a', { class: 'side-home', href: routes.home(), 'aria-current': route.view === 'home' ? 'page' : null }, [icon('overview', 16), el('span', { text: '總覽' })]),
+    el('h2', { class: 'side-title' }, ['Projects', el('span', { class: 'count', text: String(store.projects.length) })]),
+    store.projects.length ? list : el('p', { class: 'side-empty', text: store.projectsLoaded ? '還沒有 project 註冊.' : '正在讀取.' }),
+    el('p', { class: 'side-foot num', text: foot.join(' · ') })
+  );
+
+  if (focusedHref) {
+    const again = [...host.querySelectorAll('a')].find((a) => a.getAttribute('href') === focusedHref);
+    if (again) again.focus({ preventScroll: true });
+  }
+}
+
+function projectItem(project, route, now) {
+  const data = dataOf(project.key);
+  const open = isOpen(project.key, route);
+  const activity = projectActivity(project);
+  const listId = 'side-changes-' + project.key;
+  const here = route.key === project.key;
+
+  const toggle = el('button', {
+    type: 'button',
+    class: 'side-toggle',
+    'aria-expanded': open ? 'true' : 'false',
+    'aria-controls': listId,
+    title: open ? '收合 change 清單' : '展開 change 清單',
+  }, [icon('chevron', 14), el('span', { class: 'sr-only', text: project.name + ' 的 change' })]);
+  toggle.addEventListener('click', () => {
+    toggled.set(project.key, !open);
+    renderSidebar(toggle.closest('.sidebar'), route);
+    // The redraw replaced this button; keep the keyboard on its successor.
+    const again = document.querySelector(`[aria-controls="${listId}"]`);
+    if (again) again.focus({ preventScroll: true });
+  });
+
+  const n = project.sessions.length;
+  const sessionsTitle = activity === 'offline' ? '沒有 session 連線' : `${n} 個 session · ${ACTIVITY_LABEL[activity]}`;
+  const item = paintLine(el('li', { class: 'side-project' + (here ? ' is-current' : '') + (project.online ? '' : ' is-offline') }), slotOf(project.key));
+  item.append(
+    el('div', { class: 'side-row' }, [
+      toggle,
+      el('a', { class: 'side-link', href: routes.project(project.key), 'aria-current': route.view === 'project' && here ? 'page' : null }, [
+        el('span', { class: 'line-swatch', 'aria-hidden': 'true' }),
+        el('span', { class: 'side-name', text: project.name }),
+      ]),
+      el('span', { class: 'side-sessions num', title: sessionsTitle }, [
+        activityDot(activity),
+        el('span', { text: String(n) }),
+        el('span', { class: 'sr-only', text: ' ' + sessionsTitle }),
+      ]),
+    ])
+  );
+
+  const changes = el('ul', { class: 'side-changes', id: listId });
+  changes.hidden = !open;
+  const overview = data.overview;
+  if (!overview) {
+    changes.append(el('li', { class: 'side-empty', text: data.error ? '快照讀取失敗' : '正在讀取.' }));
+  } else if (!overview.changes.length) {
+    changes.append(el('li', { class: 'side-empty', text: '沒有進行中的 change' }));
+  } else {
+    const staleDays = staleDaysOf(data);
+    for (const change of overview.changes) {
+      const signal = lineSignal(signalOf(change, staleDays, now), project.online);
+      const current = route.view === 'change' && here && route.name === change.name;
+      changes.append(el('li', {}, [
+        el('a', { class: 'side-change signal-' + signal, href: routes.change(project.key, change.name), 'aria-current': current ? 'page' : null, title: `${change.name} · ${SIGNAL_LABEL[signal]}` }, [
+          marker(signal, 10),
+          el('span', { class: 'side-change-name', text: change.name }),
+        ]),
+      ]));
+    }
+  }
+  item.append(changes);
+  return item;
+}

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAgD,MAAM,WAAW,CAAC;AAmIlF,QAAA,MAAM,OAAO,SAAgB,CAAC;AAghB9B,OAAO,EAAE,OAAO,EAAE,CAAC;AAiBnB;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,WAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAqC/D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAgD,MAAM,WAAW,CAAC;AAgIlF,QAAA,MAAM,OAAO,SAAgB,CAAC;AAggB9B,OAAO,EAAE,OAAO,EAAE,CAAC;AAiBnB;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,WAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAqC/D"}

package/dist/cli/index.js

@@ -9,10 +9,9 @@ import { UpdateCommand, UPDATE_FAILURE_PAYLOAD } from '../core/update.js';
 import { INIT_FAILURE_PAYLOAD } from '../core/init.js';
 import { RULES_FAILURE_PAYLOAD } from '../core/rules.js';
 import { MigrateCommand, MIGRATE_FAILURE_PAYLOAD } from '../core/migrate.js';
-import { resolveRootForCommand, resolveTospecRoot, isRootSelectionError, toRootOutput, } from '../core/root-selection.js';
+import { resolveRootForCommand, toRootOutput, } from '../core/root-selection.js';
 import { ValidateCommand, VALIDATE_FAILURE_PAYLOAD } from '../commands/validate.js';
 import { ShowCommand, SHOW_FAILURE_PAYLOAD } from '../commands/show.js';
-import { isInteractive } from '../utils/interactive.js';
 import { registerConfigCommand, CONFIG_FAILURE_PAYLOADS } from '../commands/config.js';
 import { registerDecisionCommand, DECISION_NEW_FAILURE_PAYLOAD, DECISION_LIST_FAILURE_PAYLOAD, } from '../commands/decision.js';
 import { registerMetricsCommand } from '../commands/metrics.js';
@@ -420,106 +419,86 @@ newCmd
         failWithError(error);
     }
 });
-program
-    .command('dashboard [path]')
-    .description('Start a local dashboard; task checkbox updates are the only writes, confined to this tospec root and blocked for archived or sync-certified changes')
-    // Parsed like --concurrency: `Number('')` is 0, so a bare `--port ''` used to
-    // pass the range check and bind an OS-chosen port.
-    .addOption(new Option('-p, --port <n>', 'Port to listen on (0-65535)').default('5620').argParser(portArg))
-    .option('--host <addr>', 'Host to bind', '127.0.0.1')
-    .option('-o, --open', 'Open the dashboard in a browser after starting')
-    .option('-d, --detach', 'Run the dashboard in the background and return immediately')
-    .option('--stop', "Stop this project's dashboard, or pick from all running ones")
-    .option('-l, --list', 'List all running dashboards (any project) and exit')
-    .option('--allow-remote', 'Allow binding a non-loopback --host (exposes the dashboard to the network)')
-    .action(async (targetPath = '.', options) => {
+const dashboardCmd = program
+    .command('dashboard')
+    .description('Manage the dashboard hub: one local server for every tospec project, needing no project of its own. Claude Code sessions register through the tospec-dashboard mod and push snapshots and activity. Task checkbox updates are relayed to a live session that applies them within its tospec root and refuses archived or sync-certified changes; beyond that the page can only answer a session\'s questions (AskUserQuestion, permissions), and only when the hub is bound to loopback');
+/** The bind options `start` takes and hands on, unchanged, to the `serve` child. */
+function withHubServeOptions(command) {
+    return (command
+        // Parsed like --concurrency: `Number('')` is 0, so a bare `--port ''` used
+        // to pass the range check and bind an OS-chosen port.
+        .addOption(new Option('-p, --port <n>', 'Port to listen on (0-65535); the mod looks for 5620 unless TOSPEC_DASHBOARD_URL says otherwise').default('5620').argParser(portArg))
+        .option('--host <addr>', 'Host to bind', '127.0.0.1')
+        .option('-o, --open', 'Open the dashboard in a browser after starting')
+        .option('--allow-remote', 'Allow binding a non-loopback --host (exposes the dashboard to the network)'));
+}
+function hubRunOptions(options, defaultPort) {
+    return {
+        // Already validated by portArg; the default is the only unparsed value.
+        port: Number(options?.port ?? defaultPort),
+        host: options?.host ?? '127.0.0.1',
+        open: options?.open,
+        allowRemote: options?.allowRemote,
+    };
+}
+withHubServeOptions(dashboardCmd.command('start').description('Start the dashboard hub in the background and return once it is listening')).action(async (options) => {
     try {
         const dashboard = await import('../commands/dashboard.js');
-        // --list is global: no tospec project required.
-        if (options?.list) {
-            // Same candidate set as --stop, which points here when it cannot
-            // prompt, so the two never disagree about what is running.
-            const running = await dashboard.collectStoppableDashboards(null);
-            if (running.length === 0) {
-                console.log('No dashboards are running.');
-            }
-            else {
-                console.log('Running dashboards:');
-                for (const d of running) {
-                    console.log(`  ${dashboard.formatRunningDashboard(d)}`);
-                }
-            }
-            return;
-        }
-        const startPath = path.resolve(targetPath);
-        // --stop is project-independent, like --list: a path with no tospec root
-        // has no dashboard of its own, which is the cue to offer the full list
-        // rather than fail.
-        if (options?.stop) {
-            const stopRoot = await resolveTospecRoot({ startPath, allowImplicitRoot: false }).catch((err) => {
-                if (isRootSelectionError(err))
-                    return null;
-                throw err;
-            });
-            const stopRootPath = stopRoot?.path ?? null;
-            const candidates = await dashboard.collectStoppableDashboards(stopRootPath);
-            if (candidates.length === 0) {
-                console.log('No dashboards are running.');
-                return;
-            }
-            let targets = dashboard.selectStopTargets(candidates, stopRootPath);
-            if (targets.length === 0) {
-                // Nothing matches this path, so let the user pick. Reachable
-                // non-interactively too, where there is nobody to answer.
-                const listed = candidates.map((d) => `  ${dashboard.formatRunningDashboard(d, '  ')}`);
-                if (!isInteractive()) {
-                    throw new dashboard.DashboardStopError(['No dashboard for this path, and no terminal to choose one from.', ...listed].join('\n'), 'Re-run from an interactive terminal, or see tospec dashboard --list.');
-                }
-                const { checkbox } = await import('@inquirer/prompts');
-                targets = await checkbox({
-                    message: 'No dashboard for this path. Select dashboards to stop:',
-                    choices: candidates.map((d) => ({
-                        name: dashboard.formatRunningDashboard(d, '  '),
-                        value: d,
-                    })),
-                });
-                if (targets.length === 0) {
-                    console.log('Nothing selected.');
-                    return;
-                }
-            }
-            for (const d of targets) {
-                const refusal = await dashboard.stopRunningDashboard(d);
-                if (refusal === null) {
-                    console.log(`Stopped dashboard (pid ${d.pid}) on port ${d.port}.`);
-                }
-                else {
-                    console.error(`Could not stop dashboard (pid ${d.pid}) on port ${d.port}: ${refusal}.`);
-                    process.exitCode = 1;
-                }
-            }
-            return;
-        }
-        // Already validated by portArg; the default is the only unparsed value.
-        const portValue = Number(options?.port ?? 5620);
-        // Starting a dashboard still requires a root — only --stop is lenient.
-        const root = await resolveTospecRoot({ startPath, allowImplicitRoot: false });
-        const runOpts = {
-            port: portValue,
-            host: options?.host ?? '127.0.0.1',
-            open: options?.open,
-            allowRemote: options?.allowRemote,
-        };
-        if (options?.detach) {
-            await dashboard.detachDashboard(root.path, process.argv[1], { ...runOpts, targetPath });
-            return;
-        }
-        await dashboard.runDashboard(root.path, runOpts);
+        await dashboard.detachDashboard(process.argv[1], hubRunOptions(options, dashboard.DEFAULT_PORT));
+    }
+    catch (error) {
+        failWithError(error);
+    }
+});
+dashboardCmd
+    .command('stop')
+    .description('Stop the running dashboard hub')
+    .action(async () => {
+    try {
+        const { dashboardStopCommand } = await import('../commands/dashboard.js');
+        await dashboardStopCommand();
     }
     catch (error) {
         failWithError(error);
     }
 });
+dashboardCmd
+    .command('status')
+    .description('Show whether the dashboard hub is running, how many Claude Code sessions it serves, and for which projects')
+    .action(async () => {
+    try {
+        const { dashboardStatusCommand } = await import('../commands/dashboard.js');
+        await dashboardStatusCommand();
+    }
+    catch (error) {
+        failWithError(error);
+    }
+});
+// The rest are hidden: `serve` is the process `start` spawns, and `snapshot` /
+// `query` are run by the mod, so `dashboard --help` lists only what a person runs.
+withHubServeOptions(dashboardCmd.command('serve', { hidden: true }).description('Run the dashboard hub in the foreground (the process `dashboard start` spawns)')).action(async (options) => {
+    try {
+        const dashboard = await import('../commands/dashboard.js');
+        await dashboard.runDashboard(hubRunOptions(options, dashboard.DEFAULT_PORT));
+    }
+    catch (error) {
+        failWithError(error);
+    }
+});
+dashboardCmd
+    .command('snapshot', { hidden: true })
+    .description("Print this project's dashboard snapshot as JSON (run by the tospec-dashboard Claude Code mod)")
+    .action(async () => {
+    const { dashboardSnapshotCommand } = await import('../commands/dashboard-relay.js');
+    await dashboardSnapshotCommand();
+});
+dashboardCmd
+    .command('query', { hidden: true })
+    .description('Answer one dashboard request read as JSON from stdin, e.g. {"method":"GET","path":"/api/overview"} (run by the tospec-dashboard Claude Code mod)')
+    .action(async () => {
+    const { dashboardQueryCommand } = await import('../commands/dashboard-relay.js');
+    await dashboardQueryCommand();
+});
 registerConfigCommand(program);
 registerDecisionCommand(program);
 registerMetricsCommand(program);