create-pmos 0.51.0 → 0.53.0

package/workspace/lib/routes-timeline.js

@@ -0,0 +1,197 @@
+'use strict';
+/* routes-timeline.js — GET /api/timeline?ws=<id>: the rows of Initiatives › Timeline (pm-os-absorb Run 4, slice 4C;
+ * PRD R20 A, D86 point 4).
+ *
+ *   → { ok: true, ws, view: 'timeline', sig: { placements, items, records }, now, today,
+ *       range: { start, end, clipped } | null,        whole months, 'YYYY-MM-DD'; null when no initiative has a date;
+ *                                                      at most 24 months, `clipped` true when a date falls outside them
+ *       horizons: { now: [row…], next: [row…], later: [row…] } }       each in its placed order, first is top
+ *
+ *   row = { id, title, lane, horizon, rank, placed, dormant, dated,   `placed`: the reader's order holds it (a line, or
+ *                                                                      a day-one row 2C seeds), so a `placed … after:
+ *                                                                      <this row>` finds it
+ *           span: { start, due } | null,              the initiative's own span, over every dated item
+ *           stages: [{ id, label, start, due, done, total }],     one per stage that holds an item, in stage order, from
+ *                                                                  planTree.layout (an unknown stage is "Other", as in the
+ *                                                                  Breakdown); start and due are null for an undated stage
+ *           milestones: ['YYYY-MM-DD'…],              the dates of milestone items, for the ◆
+ *           progress: { done, total } }
+ *
+ * A READ ONLY ROUTE. Nothing here writes a ledger, and no date is computed from anything but the items' own start and due
+ * (lib/item-spans.js, the one engine the Breakdown's Timeline and the report's strip also use). An initiative bar is never
+ * written: the page reorders rows through POST /api/placements (Run 2, slice 2C), and that is the only write.
+ *
+ * WORK LANES ONLY (D86 point 4). A row exists for an initiative whose lane has `group: 'work'` in scripts/lane-defs.js,
+ * read through the engine, never from a list in this file. A held, closed or cancelled initiative has no row.
+ *
+ * TODAY is the local date of the machine the server runs on, which is the PM's (the workspace is a local app). The range
+ * holds every date and today, but never more than MAX_MONTHS months: the window then starts a few months before today (or at
+ * the first date, if later) and a date outside it is cut off, which `range.clipped` says.
+ *
+ * HORIZON AND ORDER come from lib/placements.js readPlacements and horizonOf, so an initiative without a placement reads
+ * Later, as it does on the Roadmap. An initiative the ledger has not placed follows the placed ones of its horizon, in id
+ * order.
+ *
+ * `sig` is made of the ledgerSig of every ledger this route reads (placements, plan-items) and one signature of the
+ * records it lists (their names, sizes and times, and lifecycle.jsonl). The page watches it with sig-watch.js watchSig.
+ *
+ * 400 without `ws`; 404 for a workspace that is not registered (getWs would answer the home workspace for it); 405 for any
+ * method but GET. The workflow board is NOT read: it is capped and derived in a child process, and this route needs only
+ * the records, the two ledgers and the stage names.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const ledgers = require('./plan-ledgers.js');
+const placements = require('./placements.js');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const itemSpans = require('./item-spans.js');
+const consoleState = require('./console-state');
+
+const MIN_MONTHS = 3;
+const MAX_MONTHS = 24;
+const LEAD_MONTHS = 6;   // a clipped window opens this many months before today
+const OTHER_ID = 'other';
+const OTHER_LABEL = 'Other';   // the Breakdown's word for items whose stage the lane does not have (breakdown-copy.js)
+const pad = (n) => String(n).padStart(2, '0');
+const ymd = (d) => `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+const localYmd = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+
+/** The whole months that hold every date and today: the first of the first month to the last day of the last. More than
+ *  MAX_MONTHS of them are cut to a window that holds today and opens LEAD_MONTHS before it (or at the first date). */
+function rangeOf(dates, today) {
+  const all = dates.concat([today]).sort();
+  const a = new Date(all[0] + 'T00:00:00Z');
+  const b = new Date(all[all.length - 1] + 'T00:00:00Z');
+  const t = new Date(today + 'T00:00:00Z');
+  const idx = (d) => d.getUTCFullYear() * 12 + d.getUTCMonth();
+  let first = idx(a);
+  let months = idx(b) - first + 1;
+  if (months > MAX_MONTHS) {
+    first = Math.min(Math.max(first, idx(t) - LEAD_MONTHS), idx(t));
+    months = MAX_MONTHS;
+  } else if (months < MIN_MONTHS) months = MIN_MONTHS;
+  const start = new Date(Date.UTC(Math.floor(first / 12), first % 12, 1));
+  const last = new Date(Date.UTC(Math.floor(first / 12), (first % 12) + months, 0));
+  const out = { start: ymd(start), end: ymd(last) };
+  out.clipped = all.some((d) => d < out.start || d > out.end);
+  return out;
+}
+
+/** One signature for the records this route lists: their names, sizes and times, and the lifecycle ledger. */
+function recordsSig(root, engine) {
+  const L = engine.layout(root);
+  const h = crypto.createHash('sha1');
+  let names = [];
+  try { names = fs.readdirSync(L.initiatives).filter((n) => n.endsWith('.md')).sort(); } catch { /* no records */ }
+  for (const n of names) {
+    try { const st = fs.statSync(path.join(L.initiatives, n)); h.update(`${n}:${st.size}:${st.mtimeMs};`); } catch { /* gone mid-scan */ }
+  }
+  try { const st = fs.statSync(path.join(L.runsDir, 'lifecycle.jsonl')); h.update(`lc:${st.size}:${st.mtimeMs}:${st.ino}`); } catch { /* none */ }
+  return h.digest('hex');
+}
+
+/** The initiatives that get a row: [{ id, title, lane }] in id order. */
+function workInitiatives(root, engine) {
+  const { profile, defs } = engine.lanesFor(root);
+  const fallback = profile === 'pm-artifacts' ? 'prd' : 'feature';
+  const stopped = engine.readLifecycle(root);
+  const out = [];
+  for (const id of engine.listInitiatives(root)) {
+    const file = planTree.recordPath(root, id);
+    if (!file) continue;
+    let fm = {};
+    try { fm = engine.parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')) || {}; } catch { fm = {}; }
+    const declared = String(fm.lane || '').trim();
+    const lane = declared && defs[declared] ? declared : fallback;
+    if (!defs[lane] || defs[lane].group !== 'work') continue;
+    const lc = stopped.get(id);
+    if (lc && lc.state !== 'active') continue;
+    out.push({ id, title: String(fm.title || id), lane });
+  }
+  return out;
+}
+
+/** One initiative's row, without its horizon. `live` is its items from the plan-items fold, proposed ones left out. The
+ *  stage rows come from planTree.layout, the Breakdown's own layout: an item whose stage the lane does not know is in
+ *  "Other", as there, so the rows' totals add up to the row's progress. */
+function rowOf(root, init, fold, live, now) {
+  const lay = planTree.layout({ root, initiative: init.id, fold, ladder: null, now });
+  const spans = itemSpans.spansOf(live, { stages: lay.stages.map((s) => s.id) });
+  const byItem = new Map(spans.map((s) => [s.id, s]));
+  const groups = lay.stages.map((s) => ({ id: s.id, label: s.label, ids: new Set(s.items) }));
+  if (lay.other.items.length) groups.push({ id: OTHER_ID, label: OTHER_LABEL, ids: new Set(lay.other.items) });
+  const stageRows = [];
+  for (const g of groups) {
+    const mine = live.filter((it) => g.ids.has(it.id));
+    if (!mine.length) continue;
+    const dated = mine.map((it) => byItem.get(it.id)).filter((sp) => sp && !sp.milestone);
+    stageRows.push({
+      id: g.id, label: g.label,
+      start: dated.length ? dated.reduce((m, sp) => (sp.start < m ? sp.start : m), dated[0].start) : null,
+      due: dated.length ? dated.reduce((m, sp) => (sp.due > m ? sp.due : m), dated[0].due) : null,
+      done: mine.filter((it) => it.state === 'done').length, total: mine.length,
+    });
+  }
+  const span = itemSpans.initiativeSpan(spans);
+  return {
+    id: init.id, title: init.title, lane: init.lane, span, dated: !!span, stages: stageRows,
+    milestones: spans.filter((sp) => sp.milestone).map((sp) => sp.due).sort(),
+    progress: { done: lay.progress.done, total: lay.progress.total },
+  };
+}
+
+function build(w, now) {
+  const root = w.root;
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) return { ok: false, status: 500, error: loaded.error };
+  const engine = loaded.engine;
+  const sig = { placements: ledgers.ledgerSig(root, 'placements'), items: ledgers.ledgerSig(root, 'plan-items'), records: recordsSig(root, engine) };
+  const inits = workInitiatives(root, engine);
+  const fold = planItems.readFold(root, { now });
+  const placed = placements.readPlacements(root, { now, records: inits.map((i) => ({ id: i.id, lane: i.lane })) });
+  const rows = new Map();
+  for (const init of inits) {
+    const live = Object.values(fold.items).filter((it) => it.initiative === init.id && !it.proposed);
+    const row = rowOf(root, init, fold, live, now);
+    const p = placed.byInit[init.id] || null;
+    row.horizon = placements.horizonOf(placed, init.id);
+    row.dormant = !!(p && p.dormant);
+    row.placed = ((placed.order && placed.order[row.horizon]) || []).includes(init.id);
+    rows.set(init.id, row);
+  }
+  const horizons = { now: [], next: [], later: [] };
+  for (const h of placements.HORIZONS) {
+    const seen = new Set();
+    for (const id of (placed.order && placed.order[h]) || []) {
+      const row = rows.get(id);
+      if (!row || row.horizon !== h || seen.has(id)) continue;
+      seen.add(id); horizons[h].push(row);
+    }
+    for (const row of rows.values()) if (row.horizon === h && !seen.has(row.id)) horizons[h].push(row);
+    horizons[h].forEach((row, i) => { row.rank = i; });
+  }
+  const dates = [];
+  for (const row of rows.values()) if (row.span) dates.push(row.span.start, row.span.due);
+  const today = localYmd(new Date(now));
+  return { ok: true, ws: w.id, view: 'timeline', sig, now: new Date(now).toISOString(), today, range: dates.length ? rangeOf(dates, today) : null, horizons };
+}
+
+module.exports = {
+  prefixes: ['/api/timeline'],
+  handle: async (req, res, url, ctx) => {
+    if (url.pathname !== '/api/timeline') return false;
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET /api/timeline only reads; the page reorders rows through /api/placements' }, 405); return true; }
+    const id = String(url.searchParams.get('ws') || '');
+    if (!id) { ctx.json(res, { ok: false, error: 'ws is required: the id of a registered workspace' }, 400); return true; }
+    const w = ctx.getWs(id);
+    if (!w || w.id !== id || !w.root) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
+    let out;
+    try { out = build(w, Date.now()); }
+    catch (e) { out = { ok: false, status: 500, error: 'the timeline could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }; }
+    ctx.json(res, out, out.ok ? 200 : out.status || 500);
+    return true;
+  },
+  _rangeOf: rangeOf,
+};

package/workspace/lib/routes-today.js

@@ -0,0 +1,32 @@
+'use strict';
+/* routes-today.js — GET /api/today?ws=<id> (pm-os-absorb Run 3, slice 3B, PRD R12 and R24).
+ *
+ * The ranked list of what needs the PM, the same list `pmos today` prints and Today draws (lib/today.js). Read-only:
+ * it answers a GET and writes nothing, so it takes no press (seams §5.1). A workspace id the server does not know reads
+ * as the home workspace, the same as GET /api/needs.
+ *
+ *   { ok, ws, count, cards: [{ id, run_id, ws, kind 1..8, source, row_kind, initiative_id, cause, evidence,
+ *     act: { label, cli? }, detail? }], banner: [{ source, error }], next, stall_days, sig }
+ *
+ * `banner` holds the sources that could not be read. An unreadable source is said here and never turned into an empty
+ * list. `sig` changes whenever the list changes.
+ */
+const path = require('path');
+const today = require('./today.js');
+
+module.exports = {
+  prefixes: ['/api/today'],
+  handle: async (req, res, url, ctx) => {
+    if (url.pathname !== '/api/today') return false;
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
+    const w = ctx.getWs(url.searchParams.get('ws'));
+    if (!w) { ctx.json(res, { ok: false, error: 'no workspace is registered' }, 404); return true; }
+    let sessions = [];
+    try { sessions = ctx.sessionList(); } catch { /* a session list that cannot be read adds no session card */ }
+    // ctx.getWs answers the home workspace for an id it does not hold, so a root counts as registered only when the answer is that root
+    const registered = (root) => { const x = ctx.getWs(today.wsIdOf(root)); return !!x && path.resolve(x.root) === path.resolve(root); };
+    const out = today.todayFor(w, { stateDir: ctx.stateDirFor(w), sessions, registered });
+    ctx.json(res, out, out.ok ? 200 : 500);
+    return true;
+  },
+};

package/workspace/lib/today-cli.js

@@ -0,0 +1,99 @@
+'use strict';
+/* today-cli.js — `pmos today`: what needs you, ranked as Today shows it (pm-os-absorb Run 3, slice 3B, PRD R24).
+ *
+ *   pmos today [--ws <id>] [--json]
+ *   pmos today --root <dir> [--json]
+ *
+ * The same list as GET /api/today (lib/today.js). With a workspace server running it asks the server, so a waiting
+ * session is in the list. With none, it reads the repository itself (--root, or the git root of the current directory) and
+ * says that sessions were not read. It writes nothing. Exit codes: 0 done (an empty list is done), 1 the list could not be
+ * read, 2 usage.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const today = require('./today.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { today: [] };
+const USAGE = [
+  'usage: pmos today [--ws <id>] [--json]',
+  '       pmos today --root <dir> [--json] [--wait]',
+  'Prints what needs you, ranked as Today shows it: the kind first (1 a gate is owed, 2 a session is waiting, 3 a step was',
+  'returned to you, 4 work to check, 5 a breakdown to keep, 6 a capture, 7 a cycle review, 8 needs repair), then the card.',
+  'With a workspace server running it asks the server. Without one it reads the repository and does not read sessions.',
+  'Without a server the Cycle review and missing-anchor cards need the initiative records read, which takes time: they show',
+  'as pending. Add --wait to read them now (about a quarter of a second per record).',
+];
+const BOOL = new Set(['json', 'help', 'wait']);
+const VALUE = new Set(['ws', 'root']);
+
+function isDir(d) { try { return fs.statSync(d).isDirectory(); } catch { return false; } }
+
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+
+function print(say, out, { sessions }) {
+  say(`${out.count} ${out.count === 1 ? 'needs' : 'need'} you`);
+  for (const c of out.cards) {
+    say(`${c.kind}  ${c.cause}${c.evidence ? ' — ' + c.evidence : ''}`);
+    say(`   ${c.act.label}${c.act.cli ? ' · ' + c.act.cli : ''}${c.initiative_id ? ' · ' + c.initiative_id : ''}`);
+  }
+  for (const b of out.banner || []) say(`!  ${b.source}: ${b.error}`);
+  if (!out.count) say(out.next ? `Nothing needs you. Next: ${out.next.label}.` : 'Nothing needs you.');
+  if (!sessions) say('No server is running, so waiting sessions were not read.');
+}
+
+async function run(argv, { say, call }) {
+  const rest = []; const bools = {};
+  for (const a of argv.slice(1)) {
+    if (a.startsWith('--') && BOOL.has(a.slice(2))) bools[a.slice(2)] = true;
+    else if (a === '-h') bools.help = true;
+    else rest.push(a);
+  }
+  const { pos, flags } = parseArgs(rest);
+  const f = { ...flags, ...bools };
+  if (f.help) { USAGE.forEach((l) => say(l)); return 0; }
+  const bad = Object.keys(f).find((k) => !BOOL.has(k) && !VALUE.has(k));
+  if (bad || pos.length) { say(`✗ ${bad ? '--' + bad : pos[0]} is not an option of pmos today`); USAGE.forEach((l) => say(l)); return 2; }
+  const empty = ['ws', 'root'].find((k) => k in f && (typeof f[k] !== 'string' || !f[k]));
+  if (empty) { say(`✗ --${empty} needs a value`); USAGE.forEach((l) => say(l)); return 2; }
+  if (f.ws && f.root) { say('✗ --ws and --root name two different things: use one'); USAGE.forEach((l) => say(l)); return 2; }
+  const root = path.resolve(f.root ? f.root : repoRoot(process.cwd()));
+  if (f.root && !isDir(root)) { say(`✗ ${root} is not a directory`); return 1; }
+  let out = null;
+  let sessions = false;
+  if (!f.root) {
+    // ask the server about the repository of this directory, unless --ws names one
+    let ws = f.ws || null;
+    if (!ws) {
+      const list = await call('GET', '/api/workspaces');
+      const mine = list && Array.isArray(list.workspaces) ? list.workspaces.find((x) => x && x.root && path.resolve(x.root) === root) : null;
+      ws = mine ? mine.id : null;
+    }
+    if (ws) { out = await call('GET', '/api/today?ws=' + encodeURIComponent(ws)); sessions = !!(out && out.ok); }
+    if (f.ws) {
+      // a named workspace is never swapped for a local read; the server answers the home workspace for an id it does not hold
+      if (!out) { say(`✗ the workspace ${f.ws} could not be reached: no workspace server answered. Start it, or give --root <dir>.`); return 1; }
+      if (!out.ok) { say('✗ ' + out.error); return 1; }
+      if (out.ws !== f.ws) { say(`✗ no workspace has the id ${f.ws}`); return 1; }
+    }
+  }
+  if (!out || !out.ok) {
+    // a local read: nothing in this process would read a background derivation, so none starts; --wait derives now
+    const rowsLib = require('./initiative-rows.js');
+    const was = rowsLib.setBackground(false);
+    try {
+      if (f.wait) rowsLib.deriveNow(root);
+      out = today.todayFor({ id: 'local', root }, {});
+    } finally { rowsLib.setBackground(was); }
+  }
+  if (!out.ok) { say('✗ ' + out.error); return 1; }
+  if (f.json) say(JSON.stringify(out));
+  else print(say, out, { sessions });
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };