--- title: Overview --- ```js import {API, POLL} from "./components/config.js"; ``` ```js // Live polling — yields {data, ok, ts} every POLL ms const summaryState = (async function*() { while (true) { let data, ok = false; try { const r = await fetch(`${API}/state/summary`); ok = r.ok; data = ok ? await r.json() : {error: `HTTP ${r.status}`}; } catch (e) { data = {error: "API unreachable"}; } yield {data, ok, ts: new Date()}; await new Promise(res => setTimeout(res, POLL)); } })(); ``` ```js const summary = summaryState.data ?? {}; const _ok = summaryState.ok ?? false; const _ts = summaryState.ts; const totals = summary.totals ?? {}; const ws = totals.workstreams ?? {}; const tasks = totals.tasks ?? {}; const decisions = totals.decisions ?? {}; ``` ```js // Blocking decisions — fetched once on load, refreshed only after a resolve action. // Kept separate from the summary poll so in-progress form inputs aren't wiped every 15 s. const blockingDecisions = Mutable([]); const refreshDecisions = async () => { const r = await fetch(`${API}/decisions/?decision_type=pending`).catch(() => null); const all = r?.ok ? await r.json() : []; blockingDecisions.value = all.filter(d => ["open", "escalated"].includes(d.status)); }; refreshDecisions(); ``` ```js // SBOM snapshots — repo coverage and total package count const sbomSnapState = (async function*() { while (true) { let snapshots = [], totalPkgs = 0; try { const r = await fetch(`${API}/sbom/snapshots/`); if (r.ok) { snapshots = await r.json(); totalPkgs = snapshots.reduce((s, sn) => s + (sn.entry_count ?? 0), 0); } } catch {} yield {snapshots, totalPkgs}; await new Promise(res => setTimeout(res, POLL)); } })(); ``` ```js // Registered projects — milestone events tagged with registration const regsState = (async function*() { while (true) { let rows = []; try { const r = await fetch(`${API}/progress/?event_type=milestone&limit=500`); if (r.ok) { const all = await r.json(); rows = all.filter(e => e.summary?.startsWith("Project registered with State Hub:")); } } catch {} yield rows; await new Promise(res => setTimeout(res, POLL)); } })(); ``` ```js // All-workstreams + all-tasks poll — drives the multi-mode chart const wsChartState = (async function*() { while (true) { let wsAll = [], ok = false; try { const [rw, rt, rto, rr] = await Promise.all([ fetch(`${API}/workstreams/`), fetch(`${API}/tasks/?limit=2000`), fetch(`${API}/topics/`), fetch(`${API}/repos/`), ]); ok = rw.ok && rt.ok && rto.ok && rr.ok; if (ok) { const [wsList, taskList, topicList, repoList] = await Promise.all([ rw.json(), rt.json(), rto.json(), rr.json(), ]); const topicMap = Object.fromEntries(topicList.map(t => [t.id, t])); const repoMap = Object.fromEntries(repoList.map(r => [r.id, r])); // Aggregate task counts per workstream const counts = {}; for (const t of taskList) { const wid = t.workstream_id; if (!counts[wid]) counts[wid] = {done: 0, in_progress: 0, blocked: 0, todo: 0, total: 0}; counts[wid].total++; if (t.status === "done") counts[wid].done++; else if (t.status === "in_progress") counts[wid].in_progress++; else if (t.status === "blocked") counts[wid].blocked++; else if (t.status === "todo") counts[wid].todo++; } wsAll = wsList.map(w => ({ ...w, domain: repoMap[w.repo_id]?.domain_slug ?? topicMap[w.topic_id]?.domain_slug ?? "unknown", ...(counts[w.id] ?? {done: 0, in_progress: 0, blocked: 0, todo: 0, total: 0}), })); } } catch {} yield {wsAll, ok}; await new Promise(res => setTimeout(res, POLL)); } })(); ``` ```js const wsAll = wsChartState.wsAll ?? []; ``` # Custodian State Hub ```js import {injectTocTop} from "./components/toc-sidebar.js"; import {withDocHelp} from "./components/doc-overlay.js"; const _liveEl = html`
${_ok ? `Live · updated ${_ts?.toLocaleTimeString()}` : html`Offline — run: cd ~/the-custodian/state-hub && make api`}
`; withDocHelp(_liveEl, "/docs/live-data"); injectTocTop("live-indicator", _liveEl); const _h1 = document.querySelector("#observablehq-main h1"); if (_h1) { _h1.style.position = "relative"; withDocHelp(_h1, "/docs/overview"); } ``` ```js display(html`
⚠️ ${summary.error ?? ''}
`); ``` ## Workstreams by Domain ```js // view() is the idiomatic Observable Framework reactive input: // it displays the element AND returns a reactive value that re-runs dependent blocks. const _chartMode = view(html``); ``` ```js import * as Plot from "npm:@observablehq/plot"; // ── Filter workstreams by selected mode ─────────────────────────────────────── // "active" matches the DB status field directly. // "accepted" = DB status "completed" (explicitly reviewed and signed off). // "finished" = no open tasks remaining (derived from task counts). // "blocked" = has ≥1 blocked task; "stalled" / "oldies" = activity-based. // Time modes filter by updated_at / created_at. const _STATUS_MODES = new Set(["active"]); function _timeCutoff(mode) { const now = new Date(); if (mode === "1h") return new Date(now - 60 * 60 * 1000); if (mode === "1d") return new Date(now - 24 * 60 * 60 * 1000); if (mode === "7d") return new Date(now - 7 * 24 * 60 * 60 * 1000); if (mode === "30d") return new Date(now - 30 * 24 * 60 * 60 * 1000); if (mode === "today") return new Date(now.getFullYear(), now.getMonth(), now.getDate()); if (mode === "week") { const d = new Date(now.getFullYear(), now.getMonth(), now.getDate()); d.setDate(d.getDate() - ((d.getDay() + 6) % 7)); // back to Monday return d; } if (mode === "month") return new Date(now.getFullYear(), now.getMonth(), 1); return null; } const _chartWsFiltered = ( _STATUS_MODES.has(_chartMode) ? wsAll.filter(w => w.status === _chartMode) : _chartMode === "accepted" ? wsAll.filter(w => w.status === "completed") : _chartMode === "finished" ? wsAll.filter(w => (w.todo ?? 0) + (w.in_progress ?? 0) + (w.blocked ?? 0) === 0) : _chartMode === "blocked" ? wsAll.filter(w => (w.blocked ?? 0) > 0) : _chartMode === "stalled" ? wsAll.filter(w => { const staleAt = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000); return new Date(w.updated_at) < staleAt && (w.done ?? 0) > 0 && (w.todo ?? 0) + (w.in_progress ?? 0) + (w.blocked ?? 0) > 0; }) : _chartMode === "oldies" ? wsAll.filter(w => { const oldAt = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000); return new Date(w.created_at) < oldAt && (w.done ?? 0) === 0 && (w.todo ?? 0) + (w.in_progress ?? 0) + (w.blocked ?? 0) > 0; }) : (() => { const since = _timeCutoff(_chartMode); return wsAll.filter(w => new Date(w.updated_at) >= since || new Date(w.created_at) >= since ); })() ); // Sort domains top-to-bottom by most recent workstream update (most active domain first). // Within a domain, most recently updated workstream comes first. const _domainLatest = {}; for (const w of _chartWsFiltered) { const t = new Date(w.updated_at).getTime(); if (!_domainLatest[w.domain] || t > _domainLatest[w.domain]) _domainLatest[w.domain] = t; } const chartWs = [..._chartWsFiltered].sort((a, b) => { const dd = (_domainLatest[b.domain] ?? 0) - (_domainLatest[a.domain] ?? 0); if (dd !== 0) return dd; return new Date(b.updated_at) - new Date(a.updated_at); }); // ── Status weight: bold for notable statuses in mixed-status modes ───────────── // Color is NOT used for status — avoids green-on-green when completed bars fill the row. const _isTimeBased = !_STATUS_MODES.has(_chartMode); function _wsWeight(s) { return (s === "accepted" || s === "blocked" || s === "stalled") ? "bold" : "normal"; } // ── y-axis: domain label for first workstream per group only ────────────────── const _yLabels = {}; const _seen = new Set(); for (const w of chartWs) { _yLabels[w.title] = _seen.has(w.domain) ? "" : w.domain; _seen.add(w.domain); } const statusOrder = ["done", "in progress", "blocked", "todo"]; const statusColors = ["#4caf50", "steelblue", "#ff7043", "#e0e0e0"]; const _taskRows = chartWs.flatMap(w => [ {label: w.title, status: "done", count: w.done ?? 0}, {label: w.title, status: "in progress", count: w.in_progress ?? 0}, {label: w.title, status: "blocked", count: w.blocked ?? 0}, {label: w.title, status: "todo", count: w.todo ?? 0}, ]).filter(d => d.count > 0); // ── Render ──────────────────────────────────────────────────────────────────── if (chartWs.length === 0) { const _emptyMsg = { active: "No active workstreams.", accepted: "No accepted workstreams.", finished: "No finished workstreams.", blocked: "No blocked workstreams.", stalled: "No stalled workstreams — everything is moving.", oldies: "No oldies — all older workstreams have at least one task done.", "1h": "No workstreams changed in the last hour.", "1d": "No workstreams changed in the last 24 hours.", "7d": "No workstreams changed in the last 7 days.", "30d": "No workstreams changed in the last 30 days.", today: "No workstreams changed today.", week: "No workstreams changed this week.", month: "No workstreams changed this month.", }; display(html`

${_emptyMsg[_chartMode] ?? "No workstreams."}

`); } else { display(Plot.plot({ y: { label: null, tickSize: 0, domain: chartWs.map(w => w.title), tickFormat: t => _yLabels[t] ?? "", }, x: {label: "Tasks", grid: true}, color: {domain: statusOrder, range: statusColors, legend: true}, marks: [ Plot.barX(_taskRows, {y: "label", x: "count", fill: "status", tip: true}), // Title label — pushed to lower half of bar row (dy: +7) to separate from count Plot.text(chartWs.filter(w => w.total > 0), { y: "title", x: 0, dx: 6, dy: 7, text: d => d.title.length > 72 ? d.title.slice(0, 70) + "…" : d.title, textAnchor: "start", fontSize: 10, fill: "#1e293b", fontWeight: d => _isTimeBased ? _wsWeight(d.status) : "normal", }), Plot.text(chartWs.filter(w => w.total === 0), { y: "title", x: 0, dx: 6, dy: 7, text: d => `${d.title.length > 48 ? d.title.slice(0, 46) + "…" : d.title} — no tasks yet`, textAnchor: "start", fontSize: 10, fill: "#94a3b8", }), // Count label — pushed to upper half of bar row (dy: -7) to separate from title Plot.text(chartWs.filter(w => w.total > 0), { y: "title", x: "total", text: d => ` ${d.done}/${d.total}`, dx: 4, dy: -7, textAnchor: "start", fontSize: 11, fill: "gray", }), Plot.ruleX([0]), ], marginLeft: 160, marginRight: 70, height: Math.max(80, chartWs.length * 44 + 50), width: 700, })); } ``` ## Contribution & SBOM Health ```js const contribCounts = summary.contribution_counts ?? {}; const licenceRisk = summary.licence_risk_count ?? 0; const totalContribs = ["br","fr","ep","upr"].reduce((s, t) => s + (contribCounts[t] ?? 0), 0); const needsFollowUp = (contribCounts["submitted"] ?? 0) + (contribCounts["acknowledged"] ?? 0); const sbomSnaps = sbomSnapState.snapshots ?? []; const totalPkgs = sbomSnapState.totalPkgs ?? 0; display(html`

Contributions

${totalContribs}

${needsFollowUp > 0 ? html`${needsFollowUp} awaiting upstream response` : "all up to date"}

Licence Risk

${licenceRisk}

${licenceRisk === 0 ? html`✓ no copyleft in direct deps` : html`copyleft in direct prod deps`}

SBOM

${totalPkgs.toLocaleString()}

${sbomSnaps.length} repo${sbomSnaps.length !== 1 ? "s" : ""} tracked · ${licenceRisk > 0 ? html`${licenceRisk} copyleft risks` : html`✓ no copyleft`}
`); ``` ## Status ```js const blockedTasks = summary.blocked_tasks ?? []; const wsById = Object.fromEntries((summary.open_workstreams ?? []).map(w => [w.id, w])); const todayCount = (summary.recent_progress ?? []).filter(e => e.created_at?.startsWith(new Date().toISOString().slice(0, 10))).length; const decCount = (decisions.open ?? 0) + (decisions.escalated ?? 0); const statusEl = html`

Active Workstreams

${ws.active ?? 0}

${ws.blocked ?? 0} blocked

Blocking Decisions

${decCount}

${decisions.escalated ?? 0} escalated

Events Today

${todayCount}

last 20 shown below
`; statusEl.querySelector('[data-toggle="blocked-panel"]').addEventListener('click', () => { const panel = statusEl.querySelector('#blocked-panel'); const isOpen = panel.style.display !== 'none'; panel.style.display = isOpen ? 'none' : 'block'; statusEl.querySelector('[data-toggle="blocked-panel"] small').textContent = isOpen ? `of ${tasks.total ?? 0} total · click to expand` : `of ${tasks.total ?? 0} total · click to collapse`; }); display(statusEl); ``` ## What's next? ```js // next_steps comes from the summary poll (derived, never persisted) const nextSteps = summary.next_steps ?? []; const typeLabel = { resolved_decision: "Decision resolved", dependency_cleared: "Dependency cleared", unblocked_task: "Task unblocked", }; const typeBadgeClass = { resolved_decision: "ns-badge-decision", dependency_cleared: "ns-badge-dep", unblocked_task: "ns-badge-task", }; if (nextSteps.length === 0) { display(html`

No actionable suggestions right now — all open workstreams are making progress or waiting on decisions.

`); } else { display(html`
${nextSteps.map(s => html`
${typeLabel[s.type] ?? s.type} ${s.domain ?? "—"}
${s.workstream_title ?? "—"}
${s.task_title ? html`→ ${s.task_title}` : ""}
${s.message}
`)}
`); } ``` ## Registered Projects ```js const regs = regsState ?? []; if (regs.length === 0) { display(html`

No projects registered yet. Run custodian register-project inside a repo.

`); } else { display(Inputs.table(regs.map(e => ({ Project: e.detail?.project_path?.split("/").at(-1) ?? "—", Domain: e.detail?.domain ?? "—", Path: e.detail?.project_path ?? "—", Registered: new Date(e.created_at).toLocaleString(), })), {maxWidth: 900})); } ``` ```js // Registered domains with no workstreams yet — show a getting-started hint const regs = regsState ?? []; const registeredDomains = new Set(regs.map(e => e.detail?.domain).filter(Boolean)); const emptyRegistered = (summary.topics ?? []).filter(t => registeredDomains.has(t.domain_slug) && (t.workstreams ?? []).length === 0 ); if (emptyRegistered.length > 0) { display(html`
💡 Getting started

These registered projects have no workstreams yet:

`); } ``` ## Blocking Decisions ```js // Uses blockingDecisions (Mutable) — only re-renders when refreshDecisions() is called, // not on every summary poll, so in-progress form input is preserved between polls. const blocking = blockingDecisions ?? []; if (blocking.length === 0) { display(html`

✓ No blocking decisions.

`); } else { for (const d of blocking) { const card = html`
${d.title} ${d.escalation_note ? html`⚠ escalated` : ""} ${d.deadline ? html`Due ${new Date(d.deadline).toLocaleDateString()}` : ""}
${d.description ? html`

${d.description}

` : ""} ${d.rationale ? html`

Context: ${d.rationale}

` : ""} ${d.escalation_note ? html`

${d.escalation_note}

` : ""}
Resolve this decision →
`; // Copy to clipboard const copyBtn = card.querySelector(".r-copy"); copyBtn.addEventListener("click", () => { const parts = [ `# ${d.title}`, "", d.description ?? "", d.rationale ? `\n**Context:** ${d.rationale}` : "", d.escalation_note ? `\n**⚠ Escalated:** ${d.escalation_note}` : "", `\n**Status:** ${d.status} | **Created:** ${new Date(d.created_at).toLocaleDateString()}`, d.deadline ? `**Due:** ${new Date(d.deadline).toLocaleDateString()}` : "", ].filter(Boolean).join("\n"); navigator.clipboard.writeText(parts).then(() => { copyBtn.textContent = "✓ Copied"; setTimeout(() => { copyBtn.textContent = "Copy"; }, 1500); }).catch(() => { copyBtn.textContent = "⚠ Failed"; setTimeout(() => { copyBtn.textContent = "Copy"; }, 2000); }); }); // Resolve const btn = card.querySelector(".r-submit"); const msg = card.querySelector(".r-msg"); btn.addEventListener("click", async () => { const rationale = card.querySelector(".r-text").value.trim(); const decidedBy = card.querySelector(".r-by").value.trim() || "human"; if (!rationale) { msg.textContent = "⚠ Please enter a rationale."; return; } btn.disabled = true; btn.textContent = "Saving…"; try { const r = await fetch(`${API}/decisions/${d.id}/resolve`, { method: "POST", headers: {"Content-Type": "application/json"}, body: JSON.stringify({rationale, decided_by: decidedBy}), }); if (r.ok) { await refreshDecisions(); // re-fetches list — resolved decision won't appear } else { const err = await r.json().catch(() => ({})); msg.textContent = `Error ${r.status}: ${err.detail ?? "unknown"}`; btn.disabled = false; btn.textContent = "Record & close"; } } catch (e) { msg.textContent = `Network error: ${e.message}`; btn.disabled = false; btn.textContent = "Record & close"; } }); display(card); } } ``` ## Decisions Due Within 7 Days ```js const in7 = new Date(Date.now() + 7*24*60*60*1000); const due = (summary.blocking_decisions ?? []).filter(d => d.deadline && new Date(d.deadline) <= in7); if (due.length === 0) { display(html`

No decisions due in next 7 days.

`); } else { display(Inputs.table(due.map(d => ({ Title: d.title, Deadline: new Date(d.deadline).toLocaleString(), Status: d.status, })))); } ``` ## Recent Activity ```js display(Inputs.table((summary.recent_progress ?? []).map(e => ({ Time: new Date(e.created_at).toLocaleString(), Type: e.event_type, Author: e.author ?? "—", Summary: e.summary, })), {maxWidth: 900})); ```