syndes 0.1.0 → 0.2.0

package/dashboard/api/team.mjs

@@ -0,0 +1,220 @@
+/**
+ * The Team endpoints, including the live stream.
+ *
+ * "Real time while the dashboard is open" is taken literally: the poll loop
+ * exists only while at least one browser is listening, and stops the moment the
+ * last one disconnects. A tracker that keeps talking to a git remote after you
+ * closed the tab is a background job nobody asked for.
+ *
+ * The sync itself runs in a child process (sync/run-sync.mjs) because git is
+ * reached synchronously; running it here would block every other request for as
+ * long as the remote took to answer.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { join } from 'node:path';
+import { team } from '../../analytics/team.mjs';
+import { joinPool, leave, publish, isEnabled, teamConfig } from '../../sync/index.mjs';
+import { setName } from '../../runtime/identity.mjs';
+import { rawConfig, saveConfig, setPath, resetCache } from '../../runtime/config.mjs';
+import { packageRoot } from '../../runtime/paths.mjs';
+import { securityHeaders } from '../security.mjs';
+import { debug } from '../../runtime/log.mjs';
+
+const run = promisify(execFile);
+const RUNNER = join(packageRoot, 'sync', 'run-sync.mjs');
+
+/** Open event-stream responses. The poller lives exactly as long as this set. */
+const streams = new Set();
+let timer = null;
+let running = false;
+
+export function streamCount() {
+  return streams.size;
+}
+
+// ── Plain endpoints ─────────────────────────────────────────────────────────
+
+export async function teamOverview({ url }) {
+  return { data: await team(url.searchParams.get('range') ?? '7d') };
+}
+
+/**
+ * Setup and control.
+ *
+ * Kept as one POST with an `action` rather than five routes: every one of these
+ * is rare, and the router's default-deny list stays shorter and easier to audit
+ * when the surface does not grow a route per verb.
+ */
+export async function teamAction({ body }) {
+  const { action } = body ?? {};
+
+  try {
+    if (action === 'join') {
+      const result = joinPool({
+        transport: body.transport === 'folder' ? 'folder' : 'git',
+        repo: String(body.repo ?? '').trim(),
+        scope: body.scope,
+      });
+      resetCache();
+      await syncNow();
+      return { data: { ok: true, ...result } };
+    }
+
+    if (action === 'leave') {
+      leave();
+      resetCache();
+      stopPolling();
+      return { data: { ok: true } };
+    }
+
+    if (action === 'name') {
+      const me = setName(body.name);
+      if (isEnabled()) publish();
+      return { data: { ok: true, me: { deviceId: me.deviceId, name: me.name } } };
+    }
+
+    if (action === 'scope') {
+      if (!['summary', 'detailed'].includes(body.scope)) {
+        return { status: 400, data: { error: 'scope must be summary or detailed' } };
+      }
+      const next = rawConfig();
+      setPath(next, 'team.scope', body.scope);
+      saveConfig(next);
+      resetCache();
+      if (isEnabled()) publish();
+      return { data: { ok: true, scope: body.scope } };
+    }
+
+    if (action === 'poll') {
+      const seconds = Math.max(5, Math.min(600, Number(body.seconds) || 30));
+      const next = rawConfig();
+      setPath(next, 'team.pollSeconds', seconds);
+      saveConfig(next);
+      resetCache();
+      restartPolling();
+      return { data: { ok: true, pollSeconds: seconds } };
+    }
+
+    if (action === 'sync') {
+      const state = await syncNow();
+      return { data: { ok: true, sync: state } };
+    }
+
+    return { status: 400, data: { error: 'unknown action' } };
+  } catch (error) {
+    return { status: 400, data: { error: error.message } };
+  }
+}
+
+// ── The live stream ─────────────────────────────────────────────────────────
+
+/**
+ * Server-sent events, chosen over a websocket because this is one-directional
+ * and SSE reconnects by itself. A websocket would mean a second protocol and a
+ * hand-rolled retry loop to deliver numbers that only change every few seconds.
+ */
+export async function teamStream({ req, res, url }) {
+  const range = url.searchParams.get('range') ?? '7d';
+
+  res.writeHead(200, {
+    ...securityHeaders(),
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    Connection: 'keep-alive',
+    // Without this a proxy — or Node's own compression middleware, if one is
+    // ever added — will buffer the stream and nothing arrives until it closes.
+    'X-Accel-Buffering': 'no',
+  });
+  res.write(': connected\n\n');
+
+  const client = { res, range };
+  streams.add(client);
+
+  send(client, 'snapshot', await team(range));
+  startPolling();
+
+  // A comment frame every twenty seconds. Browsers and intermediaries drop an
+  // idle connection, and an SSE stream that silently dies looks to the user
+  // exactly like a dashboard that stopped updating.
+  const beat = setInterval(() => {
+    try { res.write(': beat\n\n'); } catch { /* closing */ }
+  }, 20_000);
+  beat.unref?.();
+
+  const close = () => {
+    clearInterval(beat);
+    streams.delete(client);
+    if (!streams.size) stopPolling();
+  };
+  req.on('close', close);
+  req.on('error', close);
+  res.on('error', close);
+
+  return { stream: true };
+}
+
+function send(client, event, data) {
+  try {
+    client.res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  } catch {
+    streams.delete(client);
+  }
+}
+
+function startPolling() {
+  if (timer || !streams.size) return;
+  const seconds = Math.max(5, Number(teamConfig().pollSeconds ?? 30));
+  timer = setInterval(() => { tick().catch((error) => debug('team tick failed', error?.message)); }, seconds * 1000);
+  timer.unref?.();
+}
+
+function stopPolling() {
+  if (!timer) return;
+  clearInterval(timer);
+  timer = null;
+}
+
+function restartPolling() {
+  stopPolling();
+  startPolling();
+}
+
+/**
+ * One poll: exchange with the pool, then push the fresh numbers to every
+ * listener.
+ *
+ * `running` guards against a slow remote overlapping the next tick. Two syncs at
+ * once would race on the same working copy, and git would be right to refuse.
+ */
+async function tick() {
+  if (running || !streams.size) return;
+  running = true;
+  let state = null;
+  try {
+    state = await syncNow();
+  } finally {
+    running = false;
+  }
+
+  // Ranges differ per listener, so each gets the view it actually asked for.
+  const byRange = new Map();
+  for (const client of [...streams]) {
+    if (!byRange.has(client.range)) byRange.set(client.range, await team(client.range));
+    send(client, 'update', { ...byRange.get(client.range), sync: state ?? byRange.get(client.range).sync });
+  }
+}
+
+/** @returns {Promise<object>} the sync state the child reported */
+async function syncNow() {
+  if (!isEnabled()) return { ok: false, reason: 'sharing is off', at: Date.now() };
+  try {
+    const { stdout } = await run(process.execPath, [RUNNER], { timeout: 60_000, windowsHide: true });
+    return JSON.parse(stdout || '{}');
+  } catch (error) {
+    debug('team sync child failed', error?.message);
+    return { ok: false, at: Date.now(), error: 'sync did not finish — see syndes doctor' };
+  }
+}
+
+export { streams };

package/dashboard/router.mjs

@@ -9,6 +9,7 @@
 import { verifyToken } from './auth.mjs';
 import { parseCookies, COOKIE_NAME } from './security.mjs';
 import * as api from './api/index.mjs';
+import * as teamApi from './api/team.mjs';
 
 /** The only routes reachable without a session. */
 const PUBLIC = new Set([
@@ -37,6 +38,12 @@ export const ROUTES = {
   'POST /api/config': api.writeConfig,
   'POST /api/auth': api.setAuthMode,
   'GET /api/export': api.exportData,
+
+  // Team. Authenticated like everything else: the pool view names people and
+  // their working hours, which is not less sensitive than the solo numbers.
+  'GET /api/team': teamApi.teamOverview,
+  'POST /api/team': teamApi.teamAction,
+  'GET /api/team/stream': teamApi.teamStream,
 };
 
 export function isPublic(key) {

package/dashboard/server.mjs

@@ -16,6 +16,7 @@ import { mintLaunchToken, consumeLaunchToken, issueToken, mode as authMode } fro
 import { hostAllowed, originAllowed, securityHeaders, sessionCookie } from './security.mjs';
 import { resolveRoute, isPublic, authenticate } from './router.mjs';
 import { serveStatic } from './static.mjs';
+import { streamCount } from './api/team.mjs';
 import { debug } from '../runtime/log.mjs';
 
 const HOST = '127.0.0.1';
@@ -46,7 +47,13 @@ export async function startServer({ port, idleTimeoutMinutes } = {}) {
     if (!idleMs) return;
     clearTimeout(idleTimer);
     // A forgotten dashboard should not be left listening for a week.
-    idleTimer = setTimeout(() => { server.close(); }, idleMs);
+    idleTimer = setTimeout(() => {
+      // An open event stream IS the dashboard being used, but it generates no
+      // further requests — so without this check a live Team page would be shut
+      // down underneath the person watching it.
+      if (streamCount() > 0) return touch();
+      server.close();
+    }, idleMs);
     idleTimer.unref();
   };
   server.on('request', touch);
@@ -103,7 +110,9 @@ async function handle(req, res, port) {
     if (body === undefined) return send(res, 413, { error: 'body too large' });
 
     const result = await handler({ req, res, url, body, port });
-    if (res.writableEnded) return undefined;
+    // A handler that returns `stream` owns its response and is still writing to
+    // it. Sending a JSON body here would inject an object into an event stream.
+    if (res.writableEnded || result?.stream) return undefined;
     return send(res, result?.status ?? 200, result?.data ?? result, result?.headers);
   }
 

package/dashboard/web/api.js

@@ -70,6 +70,12 @@ export const api = {
   practices: () => get('/api/practices'),
   practiceAction: (action, rule, ms) => post('/api/practices', { action, rule, ms }),
 
+  team: (range) => get(`/api/team?range=${encodeURIComponent(range)}`),
+  teamAction: (action, payload = {}) => post('/api/team', { action, ...payload }),
+  // Not fetched through request(): an event stream is a live connection, not a
+  // response with a body, so the view owns it and closes it itself.
+  teamStreamUrl: (range) => `/api/team/stream?range=${encodeURIComponent(range)}`,
+
   ledger: (params = {}) => get(`/api/ledger?${new URLSearchParams(params)}`),
   verify: (full) => get(`/api/verify${full ? '?full=1' : ''}`),
 

package/dashboard/web/app.css

@@ -381,7 +381,7 @@ a { color: inherit; text-decoration: none; }
   text-transform: uppercase; color: var(--ink-3); white-space: nowrap;
 }
 .table td { padding: var(--s3); border-top: 1px solid var(--line); font-size: 13px; }
-.table tbody tr { cursor: pointer; }
+.table--rows tbody tr { cursor: pointer; }
 .table tbody tr:hover td { background: var(--surface-3); }
 .table tbody tr:hover td:first-child { border-radius: var(--r-chip) 0 0 var(--r-chip); }
 .table tbody tr:hover td:last-child { border-radius: 0 var(--r-chip) var(--r-chip) 0; }
@@ -514,6 +514,32 @@ a { color: inherit; text-decoration: none; }
 @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
 @media (prefers-reduced-motion: reduce) { .skel { animation: none; } }
 
+/* ── Team ─────────────────────────────────────────────────────────────── */
+
+/* The initials chip. Identity is carried here and by the label, never by hue —
+   the palette has three meanings already and cannot also name N people. */
+.avatar {
+  width: 26px; height: 26px; flex: none;
+  border-radius: var(--r-pill);
+  display: inline-flex; align-items: center; justify-content: center;
+  background: var(--surface-3);
+  font-size: 10px; font-weight: 750; letter-spacing: 0.02em;
+}
+
+.field {
+  height: 40px;
+  padding: 0 var(--s4);
+  border: 0;
+  border-radius: var(--r-pill);
+  background: var(--surface-3);
+  color: var(--ink);
+  font-family: var(--mono);
+  font-size: 13px;
+  width: 100%;
+}
+.field::placeholder { color: var(--ink-3); }
+.field:focus-visible { outline: 2px solid var(--lime); outline-offset: 2px; }
+
 /* ── Responsive ───────────────────────────────────────────────────────── */
 
 @media (max-width: 1240px) {

package/dashboard/web/app.js

@@ -15,6 +15,7 @@ const ROUTES = [
   { id: 'overview', label: 'Overview', title: 'Overview', load: () => import('./views/overview.js') },
   { id: 'sessions', label: 'Sessions', title: 'Sessions', load: () => import('./views/sessions.js') },
   { id: 'habits', label: 'Habits', title: 'Habits', load: () => import('./views/habits.js') },
+  { id: 'team', label: 'Team', title: 'Shared account', load: () => import('./views/team.js') },
   { id: 'ledger', label: 'Ledger', title: 'Ledger', load: () => import('./views/ledger.js') },
   // Reached from the rail, not the top nav: settings is somewhere you go once,
   // and a fifth pill would dilute the four you use every day.

package/dashboard/web/charts.js

@@ -271,3 +271,194 @@ export function dial(score, { size = 168, label = 'efficiency score' } = {}) {
 }
 
 export { TONE };
+
+// ── Team charts ─────────────────────────────────────────────────────────────
+
+/**
+ * The contention grid — the dot field from the reference, carrying real meaning.
+ *
+ * One dot per three-hour band per day. Size is how much work happened in it;
+ * colour is how many people were doing that work at once. On a shared account
+ * that second dimension is the whole point: two people in the same band are
+ * spending the same rate-limit window twice and throttling each other, and
+ * neither of them can see it from their own machine.
+ *
+ * Colour keeps its meaning from everywhere else in this UI — lime is healthy
+ * (one person had the window to themselves), orange is look-at-this (you
+ * overlapped), and the empty track dot is genuinely nothing rather than a small
+ * something, which is why it is drawn at a fixed tiny radius rather than scaled.
+ *
+ * @param {{days: string[], bands: number, cells: object[], peak: number}} grid
+ */
+export function dotMatrix(grid, { label = 'when each of you worked', dayLabel = (d) => d.slice(5) } = {}) {
+  const columns = grid.days.length || 1;
+  const rows = grid.bands;
+  const cell = 26;
+  const left = 34;
+  const top = 6;
+  const width = Math.max(220, left + columns * cell + 8);
+  const height = top + rows * cell + 22;
+  const maxRadius = cell * 0.42;
+  const peak = Math.max(grid.peak, 1);
+
+  const nodes = [];
+
+  // Band labels down the left, every other row so they never collide.
+  for (let row = 0; row < rows; row += 1) {
+    if (row % 2) continue;
+    const hour = row * grid.bandHours;
+    nodes.push(el('text', {
+      x: left - 10, y: top + row * cell + cell / 2,
+      'text-anchor': 'end', 'dominant-baseline': 'middle',
+    }, [txt(`${String(hour).padStart(2, '0')}`)]));
+  }
+
+  const byKey = new Map(grid.cells.map((item) => [`${item.day}|${item.band}`, item]));
+
+  grid.days.forEach((day, column) => {
+    for (let row = 0; row < rows; row += 1) {
+      const item = byKey.get(`${day}|${row}`);
+      const cx = left + column * cell + cell / 2;
+      const cy = top + row * cell + cell / 2;
+      const total = item?.total ?? 0;
+
+      if (!total) {
+        nodes.push(el('circle', { cx, cy, r: 2, fill: 'var(--track)' }));
+        continue;
+      }
+
+      // Square-root scaling, because a dot's AREA is what the eye compares —
+      // scaling the radius linearly makes a busy band look four times worse
+      // than it is.
+      const r = Math.max(3.5, Math.sqrt(total / peak) * maxRadius);
+      const node = el('circle', {
+        class: item.people > 1 ? TONE.orange : TONE.lime,
+        cx, cy, r,
+      });
+      node.appendChild(el('title', {}, [txt(
+        `${day} ${String(item.hour).padStart(2, '0')}:00 · ${total} events · ${item.people} ${item.people === 1 ? 'person' : 'people'}`,
+      )]));
+      nodes.push(node);
+    }
+  });
+
+  grid.days.forEach((day, column) => {
+    if (columns > 10 && column % 2) return;
+    nodes.push(el('text', {
+      x: left + column * cell + cell / 2, y: height - 6, 'text-anchor': 'middle',
+    }, [txt(dayLabel(day))]));
+  });
+
+  return frame(width, height, label, nodes);
+}
+
+/**
+ * One row per day, split into a capsule per person — the reference's timeline,
+ * answering "who took the day".
+ *
+ * Identity lives on the initials chip, not in the colour, because a palette with
+ * three meanings cannot also encode an arbitrary number of people without one of
+ * the two jobs becoming a lie. Colour says self or other; the chip says who.
+ *
+ * @param {{day: string, total: number, segments: object[]}[]} rows
+ */
+export function laneSplit(rows, { label = 'daily split', format = String, dayLabel = (d) => d.slice(5) } = {}) {
+  const width = 640;
+  const left = 46;
+  const rowH = 40;
+  const barH = 28;
+  const height = Math.max(60, rows.length * rowH + 10);
+  const span = width - left - 8;
+  const max = Math.max(...rows.map((row) => row.total), 1);
+
+  const nodes = [];
+
+  rows.forEach((row, index) => {
+    const y = index * rowH + 6;
+    nodes.push(el('text', {
+      x: 0, y: y + barH / 2, 'dominant-baseline': 'middle',
+    }, [txt(dayLabel(row.day))]));
+
+    if (!row.total) {
+      nodes.push(el('rect', { x: left, y: y + 5, width: 18, height: 18, rx: 9, fill: 'var(--track)' }));
+      return;
+    }
+
+    // The row's full width is this day against the busiest day, so the rows
+    // compare to each other; the segments then split that width by person.
+    const rowWidth = Math.max(60, (row.total / max) * span);
+    let cursor = left;
+
+    row.segments.forEach((segment, position) => {
+      const raw = (segment.tokens / row.total) * rowWidth;
+      // A segment narrower than its own end caps renders as a sliver with no
+      // readable shape, so tiny contributions are floored rather than drawn as
+      // a line the reader cannot identify.
+      const segWidth = Math.max(barH, raw) - (position ? 3 : 0);
+      const x = cursor;
+      cursor += segWidth + 3;
+
+      const group = el('g', {});
+      group.appendChild(el('rect', {
+        class: segment.isMe ? TONE.lime : TONE.white,
+        x, y, width: segWidth, height: barH, rx: barH / 2,
+      }));
+      group.appendChild(el('circle', { cx: x + barH / 2, cy: y + barH / 2, r: barH / 2 - 4, fill: 'var(--surface)' }));
+      group.appendChild(el('text', {
+        x: x + barH / 2, y: y + barH / 2 + 0.5,
+        'text-anchor': 'middle', 'dominant-baseline': 'middle',
+        style: 'font-size:9px;font-weight:700;fill:var(--ink)',
+      }, [txt(segment.initials)]));
+
+      if (segWidth > barH + 34) {
+        group.appendChild(el('text', {
+          class: 'cap-label', x: x + segWidth - 10, y: y + barH / 2,
+          'text-anchor': 'end', 'dominant-baseline': 'middle',
+        }, [txt(format(segment.tokens))]));
+      }
+      group.appendChild(el('title', {}, [txt(`${segment.name} · ${format(segment.tokens)} tokens on ${row.day}`)]));
+      nodes.push(group);
+    });
+  });
+
+  return frame(width, height, label, nodes);
+}
+
+/**
+ * The headline split: one capsule, one segment per person, labelled in place.
+ *
+ * Deliberately not a pie. A pie makes two similar shares hard to rank and this
+ * chart exists to answer exactly one question — whose share is bigger.
+ */
+export function splitBar(parts, { height = 44, label = 'share of the pool' } = {}) {
+  const width = 640;
+  const total = parts.reduce((sum, part) => sum + part.value, 0);
+  if (!total) {
+    return frame(width, height, label, [
+      el('rect', { x: 0, y: 6, width, height: height - 12, rx: (height - 12) / 2, fill: 'var(--track)' }),
+    ]);
+  }
+
+  const nodes = [];
+  let cursor = 0;
+
+  parts.forEach((part) => {
+    const raw = (part.value / total) * width;
+    const segWidth = Math.max(height - 12, raw - 4);
+    const x = cursor;
+    cursor += segWidth + 4;
+
+    nodes.push(el('rect', {
+      class: part.tone === 'orange' ? TONE.orange : part.isMe ? TONE.lime : TONE.white,
+      x, y: 6, width: segWidth, height: height - 12, rx: (height - 12) / 2,
+    }));
+    if (segWidth > 58) {
+      nodes.push(el('text', {
+        class: 'cap-label', x: x + 14, y: height / 2, 'dominant-baseline': 'middle',
+      }, [txt(`${Math.round((part.value / total) * 100)}%`)]));
+    }
+    nodes.push(el('title', {}, [txt(`${part.label}: ${Math.round((part.value / total) * 100)}%`)]));
+  });
+
+  return frame(width, height, label, nodes);
+}

package/dashboard/web/ui.js

@@ -315,7 +315,7 @@ export function legend(items, total = null) {
 
 export function table(headers, rows, { align = [], onRow = null } = {}) {
   return h('div.scroll-x', {}, [
-    h('table.table', {}, [
+    h(`table.table${onRow ? '.table--rows' : ''}`, {}, [
       h('thead', {}, [h('tr', {}, headers.map((label, i) =>
         h(`th${align[i] === 'right' ? '.r' : ''}`, { text: label })))]),
       h('tbody', {}, rows.map((cells, index) => h('tr', onRow ? { onclick: () => onRow(index) } : {},