@seanmars/tospec 0.23.0 → 0.26.0-beta

package/assets/dashboard/lib/derive.js

@@ -0,0 +1,375 @@
+// Pure derivations from snapshot payloads: no DOM, no fetch, so vitest can
+// import this file directly. Every value here is recomputed from what the
+// project's files say on each render; nothing is remembered between renders
+// except the line-colour slots (a display preference, not product state).
+
+/**
+ * The four stations every change passes, whatever its schema: the stations
+ * read only artifact completion, task progress and the derived phase, so a
+ * custom schema with different artifacts still lands on the same line.
+ */
+export const STATIONS = [
+  { id: 'plan', label: 'plan', hint: '寫 artifact' },
+  { id: 'apply', label: 'apply', hint: '勾 task' },
+  { id: 'sync', label: 'sync', hint: '驗證 spec' },
+  { id: 'archive', label: 'archive', hint: '歸檔' },
+];
+
+const DAY_MS = 86400000;
+export const DEFAULT_STALE_DAYS = 14;
+
+/**
+ * Where a change whose metadata will not parse stands. Its counts are zeros,
+ * not measurements, so any station it was drawn at would be a fallback the
+ * files never said; the map parks it before the line starts instead.
+ */
+export const UNKNOWN_STATION = 'unknown';
+
+/** Which station a change stands at. */
+export function stationOf(change) {
+  if (change.unreadable) return UNKNOWN_STATION;
+  if (change.phase === 'archiving') return 'archive';
+  if (change.phase === 'ready') return 'sync';
+  const { done, total } = change.artifactSummary;
+  // `total > 0` mirrors deriveChangePhase: 0 === 0 must not promote a change
+  // whose schema could not be read past planning.
+  if (total > 0 && done === total) return 'apply';
+  return 'plan';
+}
+
+export function stationIndex(id) {
+  return STATIONS.findIndex((s) => s.id === id);
+}
+
+export function stationLabel(id) {
+  const station = STATIONS.find((s) => s.id === id);
+  return station ? station.label : '無法判斷階段';
+}
+
+export function idleDays(change, now) {
+  const then = new Date(change.lastModified).getTime();
+  if (Number.isNaN(then)) return 0;
+  return Math.max(0, Math.floor((now - then) / DAY_MS));
+}
+
+/**
+ * The one signal a change's marker shows, most urgent first.
+ *
+ * `blocked` artifacts are deliberately absent: blocked means "a dependency is
+ * not written yet", which is every fresh change's normal state (tasks waits on
+ * specs and design). Only metadata that will not parse stops a line.
+ */
+export function signalOf(change, staleDays, now) {
+  if (change.unreadable) return 'stop';
+  if (change.phase === 'ready' || change.phase === 'archiving') return 'call';
+  if (idleDays(change, now) > staleDays) return 'idle';
+  if (change.phase === 'applying') return 'running';
+  return 'moving';
+}
+
+/**
+ * One word per marker, in the project's own terms: the map borrows a transit
+ * look, never transit words, so a label always names a tospec state.
+ * `running` and `moving` share the solid marker and so share its word; the
+ * flowing segment is what says "being worked on now". `parked` is a change in
+ * a project with no session: its files may have moved since the snapshot.
+ */
+export const SIGNAL_LABEL = {
+  stop: '無法解析',
+  call: '待處理',
+  idle: '閒置',
+  running: '進行中',
+  moving: '進行中',
+  parked: '離線',
+};
+
+/**
+ * A session's state as its mod last reported it. A session whose mod predates
+ * activity reports, or has not sent one yet, reads as idle rather than as
+ * working: claiming work nobody reported would be the worse error.
+ */
+export function sessionStatus(session) {
+  return session.status === 'working' || session.status === 'waiting' ? session.status : 'idle';
+}
+
+/** A project's state at a glance: its most pressing session, waiting first. */
+export function projectActivity(project) {
+  if (!project.online || !project.sessions.length) return 'offline';
+  const statuses = project.sessions.map(sessionStatus);
+  if (statuses.includes('waiting')) return 'waiting';
+  if (statuses.includes('working')) return 'working';
+  return 'idle';
+}
+
+export const ACTIVITY_LABEL = {
+  working: '工作中',
+  waiting: '等你回覆',
+  idle: '閒置',
+  offline: '離線',
+};
+
+/** How long, in words: `3 分鐘`, `2 小時`, under a minute `不到 1 分鐘`. */
+export function durationText(since, now) {
+  const then = since instanceof Date ? since.getTime() : new Date(since).getTime();
+  const mins = Number.isNaN(then) ? 0 : Math.floor((now - then) / 60000);
+  if (mins < 1) return '不到 1 分鐘';
+  if (mins < 60) return `${mins} 分鐘`;
+  const hours = Math.floor(mins / 60);
+  return hours < 24 ? `${hours} 小時` : `${Math.floor(hours / 24)} 天`;
+}
+
+/** What a session's open ask is about, in one line. */
+export function askSummary(ask) {
+  if (!ask) return '';
+  if (ask.kind === 'permission') return `允許 ${ask.tool}${ask.target ? ' ' + ask.target : ''}?`;
+  return ask.questions.map((q) => q.question).join(' / ');
+}
+
+/**
+ * What changed since the last look that the person should hear about: a
+ * session that began waiting on a question (or moved on to a new one), and a
+ * session whose turn just ended. `seen` maps `<key>/<session>` to the state
+ * last seen; the returned `seen` is the one to pass next time. A session not
+ * seen before is news only if it already waits: one that arrives idle never
+ * worked under the person's eyes.
+ */
+export function sessionAlerts(seen, projects) {
+  const next = new Map();
+  const alerts = [];
+  for (const project of projects) {
+    for (const session of project.sessions) {
+      const id = project.key + '/' + session.id;
+      const status = sessionStatus(session);
+      // Keyed by the ask too: a second question right after the first is news.
+      const state = status === 'waiting' && session.ask ? 'waiting:' + session.ask.id : status;
+      next.set(id, state);
+      const before = seen.get(id);
+      if (state === before) continue;
+      if (status === 'waiting') alerts.push({ kind: 'wait', project, session });
+      else if (status === 'idle' && before === 'working') alerts.push({ kind: 'idle', project, session });
+    }
+  }
+  return { seen: next, alerts };
+}
+
+/**
+ * The words beside a session's dot: the tool it runs while working, the
+ * question while waiting, how long it has idled.
+ */
+export function sessionDetail(session, now) {
+  const status = sessionStatus(session);
+  if (status === 'working') return session.action || '';
+  if (status === 'waiting') return askSummary(session.ask);
+  return session.statusSince ? durationText(session.statusSince, now) : '';
+}
+
+/** The signal as drawn on a project's line: offline lines park their moving trains. */
+export function lineSignal(signal, online) {
+  return !online && (signal === 'moving' || signal === 'running') ? 'parked' : signal;
+}
+
+/**
+ * The parse failure behind a stopped train, cut down to what fits a row: the
+ * file, the line when the parser names one, and the parser's own words.
+ */
+export function unreadableInfo(change) {
+  const raw = String(change.unreadable || '');
+  const line = /line (\d+)/i.exec(raw);
+  const colon = raw.indexOf(': ');
+  let reason = colon >= 0 ? raw.slice(colon + 2) : raw;
+  if (reason.length > 72) reason = reason.slice(0, 71) + '…';
+  return {
+    file: `tospec/changes/${change.name}/.tospec.yaml`,
+    summary: line ? `.tospec.yaml 第 ${line[1]} 行無法解析` : '.tospec.yaml 無法解析',
+    reason,
+  };
+}
+
+/**
+ * What the change is missing to leave its station. A planning change names
+ * the artifacts that can be written now when its detail is known; without the
+ * detail it falls back to counts rather than guessing names.
+ */
+export function gapOf(change, detail) {
+  if (change.unreadable) return unreadableInfo(change).summary;
+  const station = stationOf(change);
+  if (station === 'archive') return 'sync 通過, 可 archive';
+  if (station === 'sync') return 'task 全部完成, 等 sync';
+  if (station === 'apply') {
+    const { completed, total } = change.taskProgress;
+    return total === 0 ? '沒有 task' : `task ${completed}/${total}`;
+  }
+  if (detail && Array.isArray(detail.artifacts)) {
+    const ready = detail.artifacts.filter((a) => a.status === 'ready').map((a) => a.id);
+    const stub = detail.artifacts.filter((a) => a.status === 'stub').map((a) => a.id);
+    if (stub.length) return '待補完 ' + stub.join(', ');
+    if (ready.length) return '可寫 ' + ready.join(', ');
+  }
+  const { done, total } = change.artifactSummary;
+  return `artifact ${done}/${total}`;
+}
+
+/**
+ * Cross-project items that need the user, most urgent first. Offline projects
+ * are not items: their line already says so, and nothing in them can change
+ * until a session returns.
+ */
+export function noticeItems(projects, dataByKey, now) {
+  // A session blocked on a question comes first: work stops until it is answered.
+  const rank = { wait: 0, stop: 1, call: 2, idle: 3, drift: 4 };
+  const items = [];
+  for (const project of projects) {
+    for (const session of project.sessions) {
+      if (sessionStatus(session) === 'waiting') {
+        items.push({ kind: 'wait', project, session, text: askSummary(session.ask) });
+      }
+    }
+    const data = dataByKey.get(project.key);
+    const overview = data && data.overview;
+    if (!overview) continue;
+    const staleDays = staleDaysOf(data);
+    for (const change of overview.changes) {
+      const signal = signalOf(change, staleDays, now);
+      if (signal === 'stop') {
+        const info = unreadableInfo(change);
+        items.push({ kind: 'stop', project, change, text: `${info.summary}: ${info.reason}`, hint: `修正 ${info.file} 後, 下一次快照就會恢復.` });
+      } else if (signal === 'call') {
+        items.push({ kind: 'call', project, change, text: gapOf(change) });
+      } else if (signal === 'idle') {
+        items.push({
+          kind: 'idle',
+          project,
+          change,
+          text: `閒置 ${idleDays(change, now)} 天, 目前在 ${stationLabel(stationOf(change))} 階段 (${gapOf(change, data.details && data.details.get(change.name))})`,
+        });
+      }
+    }
+    for (const ticket of overview.tickets || []) {
+      if (ticket.parseError) {
+        items.push({ kind: 'stop', project, ticket, text: 'ticket frontmatter 無法解析', hint: `修正 ${ticket.file} 的 frontmatter.` });
+      }
+    }
+    if (data.activity && data.activity.available && data.activity.specDrift) {
+      items.push({ kind: 'drift', project, text: '近 7 天程式碼有變動, tospec/ 沒有' });
+    }
+  }
+  return items.sort(
+    (a, b) => rank[a.kind] - rank[b.kind] || a.project.name.localeCompare(b.project.name)
+  );
+}
+
+export function staleDaysOf(data) {
+  return (data && data.activity && data.activity.staleDays) || DEFAULT_STALE_DAYS;
+}
+
+// --- time ------------------------------------------------------------------
+
+/**
+ * `20260713_123649` (archive and decision stamps), `2026-07-13T12:36:49` or
+ * `2026-07-13` (change metadata `created`, new and older changes) as a local
+ * Date; anything else through Date, or null.
+ */
+export function parseLooseDate(value) {
+  if (!value) return null;
+  const stamp = /^(\d{4})(\d{2})(\d{2})(?:_(\d{2})(\d{2})(\d{2}))?$/.exec(value);
+  if (stamp) {
+    const [, y, mo, d, h = '0', mi = '0', s = '0'] = stamp;
+    return new Date(+y, +mo - 1, +d, +h, +mi, +s);
+  }
+  // A bare ISO date parses as UTC midnight, which lands on the previous day
+  // west of Greenwich; read it as the local calendar date it names. The
+  // zoneless datetime is read here too rather than left to Date, so neither
+  // spelling depends on how the engine treats a value without an offset.
+  const iso = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}):(\d{2}))?$/.exec(value);
+  if (iso) {
+    const [, y, mo, d, h = '0', mi = '0', s = '0'] = iso;
+    return new Date(+y, +mo - 1, +d, +h, +mi, +s);
+  }
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+export function relTime(value, now) {
+  const date = value instanceof Date ? value : parseLooseDate(value);
+  if (!date) return '';
+  const mins = Math.floor((now - date.getTime()) / 60000);
+  if (mins < 1) return '剛剛';
+  if (mins < 60) return `${mins} 分鐘前`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours} 小時前`;
+  const days = Math.floor(hours / 24);
+  if (days <= 30) return `${days} 天前`;
+  return formatDate(date);
+}
+
+export function formatDate(date) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+export function formatStamp(value) {
+  const date = parseLooseDate(value);
+  if (!date) return value || '';
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${formatDate(date)} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+/** Local midnight of the Monday on or before `date`. */
+export function weekStart(date) {
+  const d = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+  const offset = (d.getDay() + 6) % 7;
+  d.setDate(d.getDate() - offset);
+  return d;
+}
+
+/** Archived changes per week for the last `weeks` weeks, oldest first. */
+export function weeklyArchiveCounts(archivedChanges, now, weeks = 12) {
+  const current = weekStart(new Date(now));
+  const buckets = [];
+  for (let i = weeks - 1; i >= 0; i--) {
+    const start = new Date(current);
+    start.setDate(start.getDate() - i * 7);
+    buckets.push({ start, count: 0 });
+  }
+  const first = buckets[0].start.getTime();
+  for (const change of archivedChanges) {
+    const date = parseLooseDate(change.stamp);
+    if (!date || date.getTime() < first) continue;
+    const index = Math.floor((weekStart(date).getTime() - first) / (7 * DAY_MS) + 0.5);
+    if (index >= 0 && index < buckets.length) buckets[index].count += 1;
+  }
+  return buckets;
+}
+
+// --- line colours ------------------------------------------------------------
+
+export const LINE_SLOTS = 6;
+
+/**
+ * Gives each project a line-colour slot that survives reorders and restarts:
+ * a project keeps the slot it was first given, and a new one takes the lowest
+ * slot no listed project holds. Colour follows the project, never its rank in
+ * a list that re-sorts on every push. Past six projects slots repeat; the
+ * project name beside every line still identifies it.
+ */
+export function assignLineSlots(keys, saved) {
+  const result = new Map();
+  const taken = new Set();
+  for (const key of keys) {
+    const slot = saved[key];
+    if (Number.isInteger(slot) && slot >= 1 && slot <= LINE_SLOTS && !taken.has(slot)) {
+      result.set(key, slot);
+      taken.add(slot);
+    }
+  }
+  let overflow = 0;
+  for (const key of keys) {
+    if (result.has(key)) continue;
+    let slot = 1;
+    while (taken.has(slot) && slot <= LINE_SLOTS) slot++;
+    if (slot > LINE_SLOTS) slot = (overflow++ % LINE_SLOTS) + 1;
+    result.set(key, slot);
+    taken.add(slot);
+  }
+  return result;
+}

package/assets/dashboard/lib/dom.js

@@ -0,0 +1,121 @@
+// DOM helpers shared by every view. All text goes in as textContent, never
+// innerHTML, so snapshot data cannot inject markup; the one innerHTML in the
+// app is markdown the project side already sanitized (core/markdown-render.ts).
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** Minimal element builder; `text` sets textContent, null props and children are skipped. */
+export function el(tag, props = {}, children = []) {
+  const node = document.createElement(tag);
+  setProps(node, props);
+  appendChildren(node, children);
+  return node;
+}
+
+export function svg(tag, props = {}, children = []) {
+  const node = document.createElementNS(SVG_NS, tag);
+  setProps(node, props);
+  appendChildren(node, children);
+  return node;
+}
+
+function setProps(node, props) {
+  for (const [key, value] of Object.entries(props)) {
+    if (value == null || value === false) continue;
+    if (key === 'class') node.setAttribute('class', value);
+    else if (key === 'text') node.textContent = value;
+    else node.setAttribute(key, value === true ? '' : String(value));
+  }
+}
+
+function appendChildren(node, children) {
+  for (const child of [].concat(children)) {
+    if (child == null || child === false) continue;
+    node.append(child.nodeType ? child : document.createTextNode(String(child)));
+  }
+}
+
+/**
+ * Points a subtree at a project's line colour. Set through the CSSOM rather
+ * than a style attribute, and as a reference to the theme variable rather than
+ * a hex value, so a theme switch recolours every line without a re-render.
+ */
+export function paintLine(node, slot) {
+  node.style.setProperty('--line', `var(--line-${slot})`);
+  // Spelled out here, not derived from --line in the stylesheet: a custom
+  // property that reads another resolves where it is declared, so a :root
+  // definition would mix the root's colour, never this line's.
+  node.style.setProperty('--line-soft', `color-mix(in oklab, var(--line-${slot}) 14%, var(--surface))`);
+  return node;
+}
+
+// --- icons -------------------------------------------------------------------
+
+/**
+ * The marker a change carries on its line. Shape alone tells the signals
+ * apart, so the map still reads without colour (CVD, forced colours, print).
+ */
+export function marker(signal, size = 14) {
+  const box = { width: size, height: size, viewBox: '0 0 14 14', 'aria-hidden': 'true', focusable: 'false' };
+  const cls = `marker marker-${signal}`;
+  if (signal === 'stop') {
+    return svg('svg', { ...box, class: cls }, [svg('rect', { x: 1.5, y: 1.5, width: 11, height: 11, rx: 1.5 })]);
+  }
+  if (signal === 'call') {
+    return svg('svg', { ...box, class: cls }, [svg('circle', { cx: 7, cy: 7, r: 5 })]);
+  }
+  if (signal === 'idle') {
+    return svg('svg', { ...box, class: cls }, [svg('circle', { cx: 7, cy: 7, r: 5 })]);
+  }
+  if (signal === 'parked') {
+    return svg('svg', { ...box, class: cls }, [
+      svg('rect', { x: 3, y: 2, width: 3, height: 10, rx: 1 }),
+      svg('rect', { x: 8, y: 2, width: 3, height: 10, rx: 1 }),
+    ]);
+  }
+  return svg('svg', { ...box, class: cls }, [svg('circle', { cx: 7, cy: 7, r: 5.5 })]);
+}
+
+/**
+ * A session's (or a project's) live state. Shape and motion carry it, as the
+ * markers do: a pulsing disc works, a half-filled one waits on the user, a
+ * ring idles, a dash is offline.
+ */
+export function activityDot(activity) {
+  return el('span', { class: 'activity-dot activity-' + activity, 'aria-hidden': 'true' });
+}
+
+const ICON_PATHS = {
+  refresh: 'M13.5 3.5v3.2h-3.2M2.5 12.5V9.3h3.2M3.2 6.2a5 5 0 0 1 9-1.6l1.3 1.1M12.8 9.8a5 5 0 0 1-9 1.6L2.5 10.3',
+  chevron: 'M4 6l4 4 4-4',
+  back: 'M10 3L5 8l5 5',
+  search: 'M7 12A5 5 0 1 0 7 2a5 5 0 0 0 0 10zM10.6 10.6L14 14',
+  lock: 'M4.5 7V5.5a3.5 3.5 0 0 1 7 0V7M3.5 7h9v6.5h-9z',
+  menu: 'M2.5 4h11M2.5 8h11M2.5 12h11',
+  overview: 'M2.5 2.5h4.5v4.5H2.5zM9 2.5h4.5v4.5H9zM2.5 9h4.5v4.5H2.5zM9 9h4.5v4.5H9z',
+  copy: 'M5.5 5.5h8v8h-8zM10.5 5.5v-3h-8v8h3',
+  close: 'M3.5 3.5l9 9M12.5 3.5l-9 9',
+  log: 'M2.5 3.5h11M2.5 6.5h11M2.5 9.5h7M2.5 12.5h9',
+  bell: 'M4 11.5V7a4 4 0 0 1 8 0v4.5l1.2 1.3H2.8zM6.6 14a1.5 1.5 0 0 0 2.8 0',
+  'bell-off': 'M4 11.5V7a4 4 0 0 1 8 0v4.5l1.2 1.3H2.8zM6.6 14a1.5 1.5 0 0 0 2.8 0M2 2l12 12',
+};
+
+export function icon(name, size = 16) {
+  return svg('svg', {
+    class: 'icon icon-' + name,
+    width: size,
+    height: size,
+    viewBox: '0 0 16 16',
+    'aria-hidden': 'true',
+    focusable: 'false',
+  }, [svg('path', { d: ICON_PATHS[name] })]);
+}
+
+/** The project's line badge: a short bar of its colour beside its name. */
+export function lineBadge(name, slot, tag = 'span') {
+  return paintLine(el(tag, { class: 'line-badge' }, [el('span', { class: 'line-swatch', 'aria-hidden': 'true' }), el('span', { class: 'line-name', text: name })]), slot);
+}
+
+export function note(text, cls = 'note') {
+  return el('p', { class: cls, text });
+}

package/assets/dashboard/lib/routes.js

@@ -0,0 +1,52 @@
+// Hash routes. The project lives in the hash, not the query string, so moving
+// between projects is a route change rather than a page load.
+
+const enc = encodeURIComponent;
+
+export const routes = {
+  home: () => '#/',
+  project: (key) => `#/p/${key}`,
+  change: (key, name) => `#/p/${key}/changes/${enc(name)}`,
+  spec: (key, id) => `#/p/${key}/specs/${enc(id)}`,
+  decisions: (key, file) => (file ? `#/p/${key}/decisions/${enc(file)}` : `#/p/${key}/decisions`),
+};
+
+/** `#/p/<key>/changes/<name>` -> { view: 'change', key, name }. Unknown hashes fall back home. */
+export function parseRoute(hash) {
+  const parts = hash.replace(/^#\/?/, '').split('/').filter(Boolean);
+  if (parts[0] !== 'p' || !parts[1]) return { view: 'home' };
+  const key = parts[1];
+  const rest = parts.slice(3).map((p) => {
+    try {
+      return decodeURIComponent(p);
+    } catch {
+      return p;
+    }
+  });
+  switch (parts[2]) {
+    case undefined:
+      return { view: 'project', key };
+    case 'changes':
+      return rest[0] ? { view: 'change', key, name: rest[0] } : { view: 'project', key };
+    case 'specs':
+      return rest[0] ? { view: 'spec', key, id: rest[0] } : { view: 'project', key };
+    case 'decisions':
+      return { view: 'decisions', key, file: rest[0] || null };
+    default:
+      return { view: 'project', key };
+  }
+}
+
+/**
+ * Bookmarks from the single-project dashboard read `?project=<key>#/changes/x`.
+ * Returns the equivalent hash route, or null when the URL is already current.
+ */
+export function legacyRoute(search, hash) {
+  const key = new URLSearchParams(search).get('project');
+  if (!key) return null;
+  const inner = hash.replace(/^#\/?/, '');
+  if (inner.startsWith('changes/') || inner.startsWith('specs/') || inner.startsWith('decisions')) {
+    return `#/p/${key}/${inner}`;
+  }
+  return `#/p/${key}`;
+}