super-backlog 1.2.0 → 1.3.1

package/README.md

@@ -97,7 +97,7 @@ The router is fully owned by super-backlog and removed by `sbl uninstall`. See t
 
 ## Project Dashboard
 
-`sbl dashboard` starts a local hub that serves a dark, HTS-style cockpit rendered from your Backlog data in seven sections — Board & Quick Actions, Status (donut), Milestones, Tasks (sortable/filterable table; click a row to open a modal detail view with acceptance criteria and dependencies), Feature Cycle (pipeline stepper plus an Up Next / Blocked flow view from task dependencies), Activity (30-day sparkline), and Decisions & Docs. Glossary tooltips explain domain terms inline; extend or override them project-wide via `backlog/docs/glossary.md` (`## Term` heading plus the text below it). No CDNs, no external fonts — works offline when served locally. Bookmark `http://127.0.0.1:6428/p/<project_name>/`. The hub watches `backlog/`, regenerates on change, and serves on port `6428`; connected browser tabs reload automatically via Server-Sent Events. A second repo's `sbl dashboard` attaches to the same hub. `Ctrl+C` in the hub terminal stops all projects.
+`sbl dashboard` starts a local hub that serves an HTS-style cockpit (light/dark theme toggle) rendered from your Backlog data in eight sections — Board & Quick Actions, Status (KPI tiles, donut, and an aging strip for open tasks), Feature Cycle (pipeline stepper plus an Up Next / Blocked flow view from task dependencies), Milestones, Drafts (click a card for details), Tasks (sortable/filterable table; click a row to open a modal detail view with acceptance criteria and dependencies), Activity (a 26-week calendar heatmap; click a day for its tasks), and Decisions & Docs. Glossary tooltips explain domain terms inline; extend or override them project-wide via `backlog/docs/glossary.md` (`## Term` heading plus the text below it). Typefaces load from Google Fonts with full system fallbacks — the one external resource; everything else is inline, and the dashboard still renders offline. Bookmark `http://127.0.0.1:6428/p/<project_name>/`. The hub watches `backlog/`, regenerates on change, and serves on port `6428`; connected browser tabs reload automatically via Server-Sent Events. A second repo's `sbl dashboard` attaches to the same hub. `Ctrl+C` in the hub terminal stops all projects.
 
 ### Keeping it fresh
 

package/dist/dashboard/data.js

@@ -5,6 +5,7 @@ import { basename, join } from 'node:path';
 import { resolveBacklogBin, runCapture } from '../lib/run.js';
 import { isNewerVersion } from '../lib/version-check.js';
 import { readSimpleKeys } from '../lib/yamlmini.js';
+import { computeKpis } from './metrics.js';
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -52,17 +53,29 @@ function normalizeAcs(value) {
     }
     return out;
 }
+function firstAssignee(t) {
+    const list = t['assignees'];
+    if (Array.isArray(list)) {
+        for (const entry of list) {
+            const name = asString(entry);
+            if (name !== undefined)
+                return name;
+        }
+    }
+    return asString(t['assignee']);
+}
 export function normalizeTasks(rawTasks) {
     return rawTasks.map((t) => ({
         id: asString(t['id']) ?? '',
         title: asString(t['title']) ?? '(untitled)',
         status: asString(t['status']) ?? 'Unknown',
         priority: asString(t['priority']),
-        assignee: asString(t['assignee']),
-        updated: asString(t['updated_at']) ?? asString(t['updated']),
+        assignee: firstAssignee(t),
+        created: asString(t['createdAt']) ?? asString(t['created_at']) ?? asString(t['created']),
+        updated: asString(t['updatedAt']) ?? asString(t['updated_at']) ?? asString(t['updated']),
         milestone: asString(t['milestone']),
         description: asString(t['description']),
-        acs: normalizeAcs(t['acceptance_criteria']),
+        acs: normalizeAcs(t['acceptanceCriteria'] ?? t['acceptance_criteria']),
     }));
 }
 export function computeStatuses(tasks) {
@@ -129,20 +142,24 @@ function shiftDay(day, deltaDays) {
     const [y, mo, d] = day.split('-').map(Number);
     return new Date(Date.UTC(y, mo - 1, d) + deltaDays * 86400000).toISOString().slice(0, 10);
 }
-/** Bucket tasks into exactly 30 UTC daily buckets ending at `today`, oldest first. */
+export const ACTIVITY_DAYS = 182;
+/** Bucket tasks into exactly ACTIVITY_DAYS UTC daily buckets ending at `today`, oldest first. */
 export function computeActivity(rawTasks, today) {
-    const counts = new Map();
+    const byDay = new Map();
     for (const t of rawTasks) {
-        const day = isoDay(asString(t['updated_at']) ?? asString(t['updated'])) ??
-            isoDay(asString(t['created_at'])) ??
+        const day = isoDay(asString(t['updatedAt']) ?? asString(t['updated_at']) ?? asString(t['updated'])) ??
+            isoDay(asString(t['createdAt']) ?? asString(t['created_at'])) ??
             today;
-        counts.set(day, (counts.get(day) ?? 0) + 1);
+        const ids = byDay.get(day) ?? [];
+        ids.push(asString(t['id']) ?? '');
+        byDay.set(day, ids);
     }
-    const start = shiftDay(today, -29);
+    const start = shiftDay(today, -(ACTIVITY_DAYS - 1));
     const out = [];
-    for (let i = 0; i < 30; i++) {
+    for (let i = 0; i < ACTIVITY_DAYS; i++) {
         const date = shiftDay(start, i);
-        out.push({ date, count: counts.get(date) ?? 0 });
+        const ids = byDay.get(date) ?? [];
+        out.push({ date, count: ids.length, ids });
     }
     return out;
 }
@@ -219,13 +236,33 @@ function readProjectGlossary(cwd) {
     }
 }
 function readDraftFile(path) {
-    const keys = readSimpleKeys(path, ['id', 'title', 'status']);
+    const keys = readSimpleKeys(path, [
+        'id', 'title', 'status', 'priority', 'assignee',
+        'created_date', 'updated_date', 'created', 'updated',
+    ]);
     const id = asString(keys.id);
     const title = asString(keys.title);
     const status = asString(keys.status);
     if (!id || !title || !status)
         return null;
-    return { id, title, status };
+    let detail = { acs: [] };
+    try {
+        detail = parseTaskFile(readFileSync(path, 'utf8'));
+    }
+    catch {
+        // keys-only draft when the file cannot be re-read
+    }
+    return {
+        id,
+        title,
+        status,
+        description: detail.description,
+        priority: asString(keys.priority),
+        assignee: asString(keys.assignee),
+        created: asString(keys['created_date']) ?? asString(keys['created']),
+        updated: asString(keys['updated_date']) ?? asString(keys['updated']),
+        acs: detail.acs,
+    };
 }
 export function readDrafts(cwd) {
     const draftsDir = join(cwd, 'backlog', 'drafts');
@@ -265,6 +302,67 @@ function readProjectIdentity(cwd) {
     const description = asString(cfg['description']) ?? asString(pkg?.['description']) ?? '';
     return { name, description };
 }
+function sectionBetween(content, begin, end) {
+    const from = content.indexOf(begin);
+    if (from === -1)
+        return undefined;
+    const to = content.indexOf(end, from + begin.length);
+    if (to === -1)
+        return undefined;
+    const text = content.slice(from + begin.length, to).trim();
+    return text === '' ? undefined : text;
+}
+/** Parse one backlog task markdown file via its explicit section markers. */
+export function parseTaskFile(content) {
+    const idMatch = /^id:\s*['"]?([^'"\r\n]+)['"]?\s*$/m.exec(content);
+    const description = sectionBetween(content, '<!-- SECTION:DESCRIPTION:BEGIN -->', '<!-- SECTION:DESCRIPTION:END -->');
+    const acs = [];
+    const acBlock = sectionBetween(content, '<!-- AC:BEGIN -->', '<!-- AC:END -->');
+    if (acBlock !== undefined) {
+        for (const line of acBlock.split(/\r?\n/)) {
+            const m = /^-\s*\[( |x|X)\]\s*(?:#\d+\s*)?(.+)$/.exec(line.trim());
+            if (m)
+                acs.push({ text: m[2].trim(), checked: m[1].toLowerCase() === 'x' });
+        }
+    }
+    return { id: idMatch?.[1]?.trim(), description, acs };
+}
+/**
+ * Fill description/ACs from backlog/tasks/*.md where `task list --json`
+ * (schemaVersion 1) does not carry them. The CLI stays the source of truth
+ * for the list and statuses; files only supply missing detail fields.
+ */
+export function enrichTasksFromFiles(cwd, tasks) {
+    const dir = join(cwd, 'backlog', 'tasks');
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+    }
+    catch {
+        return tasks;
+    }
+    const byId = new Map();
+    for (const file of files) {
+        try {
+            const detail = parseTaskFile(readFileSync(join(dir, file), 'utf8'));
+            if (detail.id !== undefined)
+                byId.set(detail.id.toUpperCase(), detail);
+        }
+        catch {
+            // unreadable file -> no enrichment for that task
+        }
+    }
+    return tasks.map((t) => {
+        const detail = byId.get(t.id.toUpperCase());
+        if (!detail)
+            return t;
+        return {
+            ...t,
+            description: t.description ?? detail.description,
+            acs: t.acs.length > 0 ? t.acs : detail.acs,
+        };
+    });
+}
 function readLatestVersion(home, kitVersion) {
     try {
         const raw = readFileSync(join(home, '.super-backlog', 'version-check.json'), 'utf8');
@@ -281,6 +379,7 @@ export function collectDashboardData(cwd, opts) {
     const today = opts.today && /^\d{4}-\d{2}-\d{2}$/.test(opts.today.trim())
         ? opts.today.trim()
         : new Date().toISOString().slice(0, 10);
+    const activity = computeActivity([], today);
     const base = {
         project: readProjectIdentity(cwd),
         generatedAt: new Date().toISOString(),
@@ -291,8 +390,9 @@ export function collectDashboardData(cwd, opts) {
         tasks: [],
         deps: [],
         drafts: readDrafts(cwd),
-        activity: computeActivity([], today),
+        activity,
         glossary: mergeGlossary(readProjectGlossary(cwd)),
+        kpis: computeKpis([], [], activity, today),
         source: 'fallback-empty',
     };
     try {
@@ -303,14 +403,17 @@ export function collectDashboardData(cwd, opts) {
         if (res.status !== 0)
             return base;
         const rawTasks = parseTasksJson(res.stdout);
-        const tasks = normalizeTasks(rawTasks);
+        const tasks = enrichTasksFromFiles(cwd, normalizeTasks(rawTasks));
+        const deps = computeDeps(rawTasks);
+        const taskActivity = computeActivity(rawTasks, today);
         return {
             ...base,
             tasks,
             statuses: computeStatuses(tasks),
             milestones: computeMilestones(tasks),
-            deps: computeDeps(rawTasks),
-            activity: computeActivity(rawTasks, today),
+            deps,
+            activity: taskActivity,
+            kpis: computeKpis(tasks, deps, taskActivity, today),
             source: 'backlog-json',
         };
     }

package/dist/dashboard/metrics.js

@@ -0,0 +1,97 @@
+function isDone(status) {
+    const s = status.toLowerCase();
+    return s === 'done' || s === 'complete' || s === 'completed';
+}
+function isWip(status) {
+    const s = status.toLowerCase();
+    return s.includes('progress') || s.includes('review');
+}
+function utcDay(value) {
+    if (!value)
+        return null;
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(value.trim());
+    if (m)
+        return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    const t = Date.parse(value);
+    if (Number.isNaN(t))
+        return null;
+    const d = new Date(t);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+const DAY_MS = 86_400_000;
+export function computeKpis(tasks, deps, activity, today) {
+    const todayMs = utcDay(today) ?? Date.UTC(1970, 0, 1);
+    const total = tasks.length;
+    const doneTasks = tasks.filter((t) => isDone(t.status));
+    const done = doneTasks.length;
+    const open = total - done;
+    const progressPct = total > 0 ? Math.round((done / total) * 100) : 0;
+    const doneInWindow = (fromDaysAgo, toDaysAgo) => doneTasks.filter((t) => {
+        const d = utcDay(t.updated);
+        if (d === null)
+            return false;
+        const age = (todayMs - d) / DAY_MS;
+        return age >= toDaysAgo && age < fromDaysAgo;
+    }).length;
+    const velocity7 = doneInWindow(7, 0);
+    const velocityPrev7 = doneInWindow(14, 7);
+    let forecastDate = null;
+    if (velocity7 > 0 && open > 0) {
+        const daysNeeded = Math.ceil((open / velocity7) * 7);
+        forecastDate = new Date(todayMs + daysNeeded * DAY_MS).toISOString().slice(0, 10);
+    }
+    const byId = new Map(tasks.map((t) => [t.id, t]));
+    const unresolved = new Set();
+    for (const dep of deps) {
+        const from = byId.get(dep.from);
+        const to = byId.get(dep.to);
+        if (from && !isDone(from.status) && to && !isDone(to.status))
+            unresolved.add(dep.from);
+    }
+    const openTasks = tasks.filter((t) => !isDone(t.status));
+    const wip = openTasks.filter((t) => isWip(t.status)).length;
+    const blocked = openTasks.filter((t) => t.status.toLowerCase().includes('block') || unresolved.has(t.id)).length;
+    const ages = [];
+    for (const t of openTasks) {
+        const d = utcDay(t.created) ?? utcDay(t.updated);
+        if (d === null)
+            continue;
+        ages.push({ id: t.id, days: Math.max(0, Math.round((todayMs - d) / DAY_MS)) });
+    }
+    ages.sort((a, b) => b.days - a.days);
+    const oldest = ages[0] ?? null;
+    let medianOpenAgeDays = null;
+    if (ages.length > 0) {
+        const mid = Math.floor(ages.length / 2);
+        medianOpenAgeDays =
+            ages.length % 2 === 1 ? ages[mid].days : Math.round((ages[mid - 1].days + ages[mid].days) / 2);
+    }
+    const activityTotal30 = activity.slice(-30).reduce((sum, b) => sum + b.count, 0);
+    const windowTotal = activity.reduce((sum, b) => sum + b.count, 0);
+    const activityAvgPerWeek = activity.length > 0 ? Math.round((windowTotal / (activity.length / 7)) * 10) / 10 : 0;
+    const perWeekday = [0, 0, 0, 0, 0, 0, 0];
+    for (const b of activity) {
+        const d = utcDay(b.date);
+        if (d !== null)
+            perWeekday[new Date(d).getUTCDay()] += b.count;
+    }
+    const maxWeekday = Math.max(...perWeekday);
+    const busiestWeekday = maxWeekday > 0 ? perWeekday.indexOf(maxWeekday) : null;
+    let streakDays = 0;
+    let i = activity.length - 1;
+    if (i >= 0 && activity[i].count === 0)
+        i--; // today may still be empty
+    while (i >= 0 && activity[i].count > 0) {
+        streakDays++;
+        i--;
+    }
+    return {
+        total, done, open, progressPct,
+        velocity7, velocityPrev7, forecastDate,
+        wip, blocked,
+        oldestOpenId: oldest ? oldest.id : null,
+        oldestOpenDays: oldest ? oldest.days : null,
+        medianOpenAgeDays,
+        activityTotal30, activityAvgPerWeek, busiestWeekday, streakDays,
+    };
+}

package/dist/models/dashboard-api.js

@@ -1,18 +1,47 @@
+// src/models/dashboard-api.ts
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { loadConfig } from './config.js';
 import { discoverModels } from './discovery.js';
-export function createModelApiHandler(cwd) {
+import { writeResolvedTiers, writeRouterConfig } from './install.js';
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+}
+function routerInstalled(cwd) {
+    return existsSync(join(cwd, '.super-backlog', 'models.json'));
+}
+export function createModelApiHandler(cwd, deps = {}) {
+    const discover = deps.discover ?? discoverModels;
     return async (req, res) => {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
         if (method === 'GET' && url === '/api/models') {
-            res.writeHead(200, { 'content-type': 'application/json' });
-            res.end(JSON.stringify({ config: loadConfig(cwd), status: 'ok' }));
+            sendJson(res, 200, { config: loadConfig(cwd), installed: routerInstalled(cwd), status: 'ok' });
+            return;
+        }
+        if (method === 'POST' && (url === '/api/models/enable' || url === '/api/models/disable')) {
+            const enabled = url === '/api/models/enable';
+            try {
+                writeRouterConfig(cwd, enabled);
+                sendJson(res, 200, { ok: true, config: loadConfig(cwd), installed: routerInstalled(cwd) });
+            }
+            catch (err) {
+                sendJson(res, 500, { ok: false, message: err instanceof Error ? err.message : String(err) });
+            }
             return;
         }
         if (method === 'POST' && url === '/api/models/discover') {
-            const result = await discoverModels(cwd);
-            res.writeHead(200, { 'content-type': 'application/json' });
-            res.end(JSON.stringify(result ?? { error: 'discovery failed' }));
+            const result = await discover(cwd);
+            if (result) {
+                try {
+                    writeResolvedTiers(cwd, result);
+                }
+                catch {
+                    // discovery result still returned; the modal just won't remember it
+                }
+            }
+            sendJson(res, 200, result ?? { error: 'discovery failed' });
             return;
         }
         res.writeHead(404, { 'content-type': 'text/plain' });

package/dist/models/install.js

@@ -6,13 +6,20 @@ import { loadConfig } from './config.js';
 const CONFIG_DIR = '.super-backlog';
 const CONFIG_FILE = 'models.json';
 export function writeRouterConfig(cwd, enabled) {
+    writeConfigPatch(cwd, { enabled });
+    return true;
+}
+/** Persist discovered tiers so the dashboard shows them across sessions. */
+export function writeResolvedTiers(cwd, resolved) {
+    writeConfigPatch(cwd, { resolved });
+}
+function writeConfigPatch(cwd, patch) {
     const dir = join(cwd, CONFIG_DIR);
     const path = join(dir, CONFIG_FILE);
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
     const current = loadConfig(cwd);
-    const next = { ...current, enabled };
+    const next = { ...current, ...patch };
     atomicWrite(path, `${JSON.stringify(next, null, 2)}\n`);
-    return true;
 }