create-pmos 0.188.0 → 0.189.0

package/workspace/lib/scan-cli.js

@@ -1,21 +1,29 @@
 'use strict';
-/* scan-cli.js — `pmos scan …`: the Horizon scan from a terminal (initiative horizon-scan, PRD sections 3 and 5).
+/* scan-cli.js — `pmos scan …`: the Horizon scan from a terminal (initiatives horizon-scan and horizon-scan-portfolio).
  *
  *   pmos scan file --scan <id> --title "<finding>" --why "<one line>" --source label=ref … [--match <initiative>] [--origin web|repo]
  *                                  an agent files one finding. It answers `filed` or `duplicate` and nothing else about earlier findings.
  *   pmos scan file --scan <id> --pages <n>                     the web run says how many public pages it read
- *   pmos scan list --scan <id>                                 the findings of one scan (the repository run reads the web run's)
+ *   pmos scan section --report <id> --heading "<h>" --source label=ref … [--body "<text>"]     (text on stdin when --body is absent)
+ *                                  a run writes one section of a report document. A web section cites only public pages the run read;
+ *                                  a repository section cites paths, Jira keys or notes. lib/scan.js assembles the file when the scan ends.
+ *   pmos scan propose --report <id> --kind create|research|attach --title "<what>" --why "<one line>" --finding "<which finding>" --source label=ref …
+ *                     create: --board <id> --lane <lane> --anchor <KR|health:id> --intent "<one paragraph>"
+ *                     research: --question "<public question>" [--depth quick|standard|deep]      attach: --initiative <id>
+ *                                  the repository run proposes a next step. The PM approves, changes or dismisses it. It answers `filed` or `duplicate`.
+ *   pmos scan list --scan <id> [--sections]                    the findings of one scan (the repository run reads the web run's), and its report sections
  *   pmos scan match <finding> <initiative> --scan <id>         the repository run marks a finding that matches an initiative
- *   pmos scan suggest --board <id> --kind product|domain|approach --name "<what to watch>" --why "<one line>" --from <initiative>
- *                                  the suggest run files one watch list suggestion (at most 8 for a board)
- *   pmos scan status [--board <id>]                            cadence, watch list and the last scan (read)
- *   pmos scan cadence <daily|weekly|off> --board <id>          PM only
- *   pmos scan watch keep|remove <item> --board <id>            PM only
- *   pmos scan watch edit <item> --board <id> [--name …] [--kind …] [--why …]    PM only
- *   pmos scan watch add --board <id> --kind … --name … [--why …]               PM only
+ *   pmos scan suggest [--boards <id,id>] --kind product|domain|approach --name "<what to watch>" --why "<one line>" --from <initiative>
+ *                                  the suggest run files one watch list suggestion (at most 8 a run)
+ *   pmos scan status                                           the setting, the watch list, the last scan and the proposals waiting (read)
+ *   pmos scan setting [--cadence daily|weekly|off] [--repo on|off] [--types benchmark,competitive,insight,productivity]     PM only
+ *   pmos scan cadence <daily|weekly|off>                       PM only (the first scan's verb; it sets the workspace cadence)
+ *   pmos scan watch keep|remove <item>                         PM only
+ *   pmos scan watch edit <item> [--name …] [--kind …] [--why …] [--boards a,b]    PM only
+ *   pmos scan watch add --kind … --name … [--why …] [--boards a,b]               PM only
  *   every command: [--json] [--root <dir>]
  *
- * Who wrote a line is the call path (lib/actor.js), never an argument. The scan runs set two variables the model cannot change: PMOS_SCAN_FILE
+ * Who wrote a line is the call path (lib/actor.js), never an argument. The scan runs set variables the model cannot change: PMOS_SCAN_FILE
  * (the ledger, so the web run, which has no repository, still finds it) and PMOS_SCAN_ORIGIN (web or repo, so a run cannot file as the other).
  * PMOS_SCAN_RUN names the run, so a finding carries the run that filed it.
  * `file` answers only `duplicate` for a repeat: it never prints the earlier finding. Nothing here sends anything outward.
@@ -28,25 +36,32 @@ const actorLib = require('./actor.js');
 const D = require('./driver.js');
 const S = require('./scan.js');
 
-const COMMANDS = { scan: ['file', 'list', 'match', 'suggest', 'status', 'cadence', 'watch'] };
+const COMMANDS = { scan: ['file', 'section', 'propose', 'list', 'match', 'suggest', 'status', 'setting', 'cadence', 'watch'] };
 const USAGE = [
-  'usage: pmos scan file|list|match|suggest|status|cadence|watch — the Horizon scan',
+  'usage: pmos scan file|section|propose|list|match|suggest|status|setting|cadence|watch — the Horizon scan',
   '  pmos scan file --scan <id> --title "<finding>" --why "<one line>" --source label=ref … [--match <initiative>]',
   '      a web finding needs one source that is a public page you read; a repository finding needs a pointer (path, Jira key, note)',
   '  pmos scan file --scan <id> --pages <n>                          how many public pages the web run read',
-  '  pmos scan list --scan <id>                                     the findings of a scan',
+  '  pmos scan section --report <id> --heading "<h>" --source label=ref … [--body "<text>"]     the text is read from stdin without --body',
+  '      a web section cites public pages you read; a repository section cites paths, Jira keys or notes',
+  '  pmos scan propose --report <id> --kind create|research|attach --title "<what>" --why "<one line>" --finding "<which finding>" --source label=ref …',
+  '      create: --board <id> --lane <lane> --anchor <KR|health:id> --intent "<one paragraph>"',
+  '      research: --question "<public question>" [--depth quick|standard|deep]        attach: --initiative <id>',
+  '  pmos scan list --scan <id> [--sections]                         the findings of a scan, and its report sections',
   '  pmos scan match <finding> <initiative> --scan <id>             a finding matches an existing initiative',
-  '  pmos scan suggest --board <id> --kind product|domain|approach --name "<what to watch>" --why "<one line>" --from <initiative>',
-  '  pmos scan status [--board <id>]',
-  '  pmos scan cadence <daily|weekly|off> --board <id>              PM only',
-  '  pmos scan watch keep|remove <item> --board <id>                PM only',
-  '  pmos scan watch edit <item> --board <id> [--name …] [--kind …] [--why …]     PM only',
-  '  pmos scan watch add --board <id> --kind … --name … [--why …]   PM only',
+  '  pmos scan suggest [--boards a,b] --kind product|domain|approach --name "<what to watch>" --why "<one line>" --from <initiative>',
+  '  pmos scan status',
+  '  pmos scan setting [--cadence daily|weekly|off] [--repo on|off] [--types a,b]     PM only',
+  '  pmos scan cadence <daily|weekly|off>                            PM only',
+  '  pmos scan watch keep|remove <item>                              PM only',
+  '  pmos scan watch edit <item> [--name …] [--kind …] [--why …] [--boards a,b]     PM only',
+  '  pmos scan watch add --kind … --name … [--why …] [--boards a,b]                 PM only',
   '  every command: [--json] [--root <dir>]',
-  'A scan reads and files. It sends nothing and creates no initiative: each finding is an ask the PM accepts or declines.',
+  'A scan reads and files. It sends nothing and creates no initiative: each proposal is a step the PM approves, changes or dismisses.',
 ];
-const BOOL = new Set(['json', 'help']);
-const VALUE = new Set(['scan', 'title', 'why', 'source', 'match', 'origin', 'pages', 'board', 'kind', 'name', 'from', 'root']);
+const BOOL = new Set(['json', 'help', 'sections']);
+const VALUE = new Set(['scan', 'title', 'why', 'source', 'match', 'origin', 'pages', 'board', 'boards', 'kind', 'name', 'from', 'root', 'report', 'heading', 'body', 'finding', 'lane', 'anchor',
+  'intent', 'question', 'depth', 'initiative', 'cadence', 'repo', 'types']);
 
 function parse(argv) {
   const pos = []; const flags = {}; const sources = [];
@@ -78,7 +93,22 @@ function sourcesFrom(list) {
   return { sources: out };
 }
 
-async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now } = {}) {
+/** The text a section is made of: the `stdin` option (tests), else standard input. Nothing on standard input for 8 seconds is an empty text, not a hang. */
+function readStdin(given) {
+  if (typeof given === 'string') return Promise.resolve(given);
+  if (process.stdin.isTTY) return Promise.resolve('');
+  return new Promise((resolve) => {
+    let data = ''; let got = false;
+    const quiet = setTimeout(() => { if (!got) { process.stdin.pause(); resolve(''); } }, 8000);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { got = true; data += c; });
+    process.stdin.on('end', () => { clearTimeout(quiet); resolve(data); });
+    process.stdin.on('error', () => { clearTimeout(quiet); resolve(data); });
+  });
+}
+const listOf = (v) => String(v || '').split(',').map((x) => x.trim()).filter(Boolean);
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, now, stdin } = {}) {
   const args = argv[0] === 'scan' ? argv.slice(1) : argv.slice();
   const verb = args[0];
   const { pos, flags, sources } = parse(args.slice(1));
@@ -129,7 +159,7 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
     const count = sc.findings.filter((id) => state.findings.get(id).origin === origin).length;
     const limit = origin === 'web' ? S.LIMITS.web : S.LIMITS.repo;
     // A duplicate is answered before the limit: a repeat costs nothing, and it is counted as skipped.
-    const dup = S.duplicateOf(state, sc.board, c.finding);
+    const dup = S.duplicateOf(state, null, c.finding);   // the whole portfolio: the same page or title on any board
     if (dup) {
       S.append(file, { ev: 'skip', board: sc.board, scan: sc.scan, origin, of: dup.id }, { now });
       if (flags.pages !== undefined && Number.isInteger(Number(flags.pages))) S.append(file, { ev: 'pages', board: sc.board, scan: sc.scan, pages: Number(flags.pages) }, { now });
@@ -143,15 +173,69 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
     return done({ result: 'filed', id }, `filed ${id}`);
   }
 
+  if (verb === 'section') {
+    if (!file) return noState();
+    if (!flags.report) { say('usage: pmos scan section --report <id> --heading "<h>" --source label=ref … [--body "<text>"]'); return 2; }
+    const state = S.fold(S.readLines(file));
+    const rep = state.reports.get(flags.report);
+    const sc = rep ? state.scans.get(rep.scan) : null;
+    if (!rep) return fail('no such report in this ledger');
+    if (!sc || sc.end) return fail('the scan of that report is over; file no more');
+    const origin = (E && (E.PMOS_SCAN_ORIGIN === 'web' || E.PMOS_SCAN_ORIGIN === 'repo')) ? E.PMOS_SCAN_ORIGIN : flags.origin;
+    if (!S.ORIGINS.includes(origin)) { say('say where the section comes from: --origin web or --origin repo'); return 2; }
+    if (rep.type === 'productivity' && origin === 'web') return fail('the productivity report comes from the repository run only');
+    const s = sourcesFrom(sources);
+    if (s.error) return fail(s.error, 2);
+    const body = flags.body !== undefined ? flags.body : await readStdin(stdin);
+    const c = S.checkSection({ heading: flags.heading, body, sources: s.sources }, origin, { state, scanId: sc.scan });
+    if (!c.ok) return fail(c.error);
+    if (rep.sections.some((x) => x.origin === origin && x.heading.toLowerCase() === c.section.heading.toLowerCase())) return fail('that report has a section with that heading already');
+    if (rep.sections.filter((x) => x.origin === origin).length >= S.LIMITS.sections) return fail(`this report holds ${S.LIMITS.sections} sections from the ${origin === 'web' ? 'web' : 'repository'} run already; write no more`);
+    const run = E && S.RUN_RE.test(String(E.PMOS_SCAN_RUN || '')) ? E.PMOS_SCAN_RUN : null;
+    S.append(file, { ev: 'section', board: sc.board, scan: sc.scan, report: rep.id, ...c.section, by: actor.by, ...(run ? { run } : {}) }, { now });
+    return done({ result: 'filed', report: rep.id }, `filed section "${c.section.heading}"`);
+  }
+
+  if (verb === 'propose') {
+    if (!file) return noState();
+    if (!flags.report) { say('usage: pmos scan propose --report <id> --kind create|research|attach --title "<what>" --why "<one line>" --finding "<which finding>" --source label=ref …'); return 2; }
+    const origin = (E && (E.PMOS_SCAN_ORIGIN === 'web' || E.PMOS_SCAN_ORIGIN === 'repo')) ? E.PMOS_SCAN_ORIGIN : flags.origin;
+    if (origin !== 'repo') return fail('only the repository run proposes next steps; the web run files findings and sections');
+    const state = S.fold(S.readLines(file));
+    const rep = state.reports.get(flags.report);
+    const sc = rep ? state.scans.get(rep.scan) : null;
+    if (!rep) return fail('no such report in this ledger');
+    if (!sc || sc.end) return fail('the scan of that report is over; file no more');
+    const s = sourcesFrom(sources);
+    if (s.error) return fail(s.error, 2);
+    const fields = flags.kind === 'create' ? { board: flags.board, lane: flags.lane, anchor: flags.anchor, intent: flags.intent }
+      : flags.kind === 'research' ? { question: flags.question, ...(flags.depth !== undefined ? { depth: flags.depth } : {}) } : { initiative: flags.initiative };
+    const c = S.checkProposal({ kind: flags.kind, title: flags.title, why: flags.why, finding: flags.finding, evidence: s.sources, fields });
+    if (!c.ok) return fail(c.error);
+    // A repeat is answered before the limit, and says nothing about the earlier proposal.
+    if (S.duplicateProposal(state, c.proposal.title)) return done({ result: 'duplicate' }, 'duplicate');
+    if (S.proposalsOf(state, rep.id).length >= S.LIMITS.proposals) return fail(`this report holds ${S.LIMITS.proposals} proposals already; file no more`);
+    const id = S.newId('p', 5);
+    const run = E && S.RUN_RE.test(String(E.PMOS_SCAN_RUN || '')) ? E.PMOS_SCAN_RUN : null;
+    S.append(file, { ev: 'proposal', board: sc.board, scan: sc.scan, report: rep.id, id, ...c.proposal, by: actor.by, ...(run ? { run } : {}) }, { now });
+    return done({ result: 'filed', id }, `filed ${id}`);
+  }
+
   if (verb === 'list') {
     if (!file) return noState();
     const state = S.fold(S.readLines(file));
     const sc = flags.scan ? state.scans.get(flags.scan) : null;
     if (!sc) return fail('no scan under that id');
     const rows = sc.findings.map((id) => state.findings.get(id)).map((f) => ({ id: f.id, origin: f.origin, title: f.title, why: f.why, sources: f.sources, match: f.match }));
-    if (json) { say(JSON.stringify({ ok: true, scan: sc.scan, board: sc.board, findings: rows })); return 0; }
+    const reps = flags.sections ? sc.reports.map((id) => state.reports.get(id)).map((r) => ({ id: r.id, type: r.type, title: r.title, origin: r.origin,
+      sections: r.sections.map((x) => ({ heading: x.heading, origin: x.origin, body: x.body, sources: x.sources })) })) : null;
+    if (json) { say(JSON.stringify({ ok: true, scan: sc.scan, board: sc.board, findings: rows, ...(reps ? { reports: reps } : {}) })); return 0; }
     for (const f of rows) say(`${f.id} · ${f.origin} · ${f.title} — ${f.why}${f.match ? ` · matches ${f.match}` : ''}${f.sources.length ? ` · ${f.sources.map((x) => x.ref).join(', ')}` : ''}`);
     if (!rows.length) say('no findings yet');
+    for (const r of reps || []) {
+      say(`report ${r.id} · ${r.type} · ${r.title}`);
+      for (const x of r.sections) say(`  [${x.origin}] ${x.heading}: ${x.body.replace(/\s+/g, ' ').slice(0, 300)}${x.sources.length ? ` · ${x.sources.map((y) => y.ref).join(', ')}` : ''}`);
+    }
     return 0;
   }
 
@@ -172,53 +256,67 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
 
   if (verb === 'suggest') {
     if (!file) return noState();
-    if (!flags.board) { say('usage: pmos scan suggest --board <id> --kind product|domain|approach --name "<what to watch>" --why "<one line>" --from <initiative>'); return 2; }
     if (!flags.from || !S.ID_RE.test(flags.from)) return fail('--from names the initiative this suggestion came from');
     const c = S.checkWatchItem({ kind: flags.kind, name: flags.name, why: flags.why });
     if (!c.ok) return fail(c.error);
     if (!c.item.why) return fail('--why is one line that says why this is worth watching');
+    const on = listOf(flags.boards || flags.board);
+    if (on.some((b) => !S.ID_RE.test(b)) || on.length > 20) return fail('--boards is a list of board ids');
     const state = S.fold(S.readLines(file));
-    const open = S.scansOf(state, flags.board, 'suggest').find((x) => !x.end);
-    if (!open) return fail('no suggest run is open for that board');
-    const b = state.boards.get(flags.board);
-    const mine = b ? [...b.items.values()].length : 0;
-    if (mine >= S.LIMITS.suggestions) return fail(`a board gets at most ${S.LIMITS.suggestions} suggestions`);
-    if (b && [...b.items.values()].some((i) => i.name.toLowerCase() === c.item.name.toLowerCase())) return done({ filed: false, result: 'duplicate' }, 'duplicate');
+    const open = S.scansOf(state, null, 'suggest').find((x) => !x.end);
+    if (!open) return fail('no suggest run is open');
+    const mine = [...state.itemById.values()].filter((i) => i.scan === open.scan).length;
+    if (mine >= S.LIMITS.suggestions) return fail(`a suggest run files at most ${S.LIMITS.suggestions} suggestions`);
+    if ([...state.itemById.values()].some((i) => i.name.toLowerCase() === c.item.name.toLowerCase())) return done({ filed: false, result: 'duplicate' }, 'duplicate');
     const id = S.newId('w');
-    S.append(file, { ev: 'watch-suggest', board: flags.board, id, ...c.item, ini: flags.from, by: actor.by }, { now });
+    S.append(file, { ev: 'watch-suggest', scan: open.scan, boards: on, id, ...c.item, ini: flags.from, by: actor.by }, { now });
     return done({ filed: true, id }, `filed ${id}`);
   }
 
   if (verb === 'status') {
     if (!file) return noState();
     const state = S.fold(S.readLines(file));
-    const ids = flags.board ? [flags.board] : [...state.boards.keys()];
-    const out = ids.map((id) => { const w = S.watchOf(state, id); const last = S.lastScan(state, id); return { board: id, cadence: S.cadenceOf(state, id), suggested: w.suggested.length, kept: w.kept.length,
-      last: last ? { scan: last.scan, at: last.end, found: last.found, skipped: last.skipped, pages: last.pages, ok: last.ok } : null }; });
-    if (json) { say(JSON.stringify({ ok: true, boards: out })); return 0; }
-    for (const o of out) say(`${o.board} · ${o.cadence} · ${o.kept} kept, ${o.suggested} suggested · ${o.last ? `last scan ${o.last.at}: ${o.last.found} found, ${o.last.skipped} skipped` : 'no scan yet'}`);
-    if (!out.length) say('no scan records yet');
+    const w = S.watchOf(state, null);
+    const last = S.lastScan(state, null);
+    const out = { setting: S.settingOf(state), kept: w.kept.length, suggested: w.suggested.length, proposals_waiting: S.waitingProposals(state).length,
+      last: last ? { scan: last.scan, at: last.end, found: last.found, skipped: last.skipped, pages: last.pages, ok: last.ok } : null };
+    if (json) { say(JSON.stringify({ ok: true, ...out })); return 0; }
+    say(`${out.setting.cadence} · repository ${out.setting.repo ? 'on' : 'off'} · reports ${out.setting.types.join(', ') || 'none'} · ${out.kept} kept, ${out.suggested} suggested · ${out.proposals_waiting} proposals waiting · ${out.last ? `last scan ${out.last.at}: ${out.last.found} found, ${out.last.skipped} skipped` : 'no scan yet'}`);
     return 0;
   }
 
   // ── the PM's verbs ────────────────────────────────────────────────────────────────────────────────
+  if (verb === 'setting') {
+    const g = pmOnly('change the scan setting');
+    if (!g.ok) return fail(g.error);
+    if (!file) return noState();
+    const input = {};
+    if (flags.cadence !== undefined) input.cadence = flags.cadence;
+    if (flags.repo !== undefined) { if (!/^(on|off)$/.test(flags.repo)) return fail('--repo is on or off', 2); input.repo = flags.repo === 'on'; }
+    if (flags.types !== undefined) input.types = listOf(flags.types);
+    const r = S.setSetting(file, input, actor, { now });
+    if (!r.ok) return fail(r.error);
+    return done({ setting: r.setting }, `✓ ${r.setting.cadence} · repository ${r.setting.repo ? 'on' : 'off'} · reports ${r.setting.types.join(', ') || 'none'}`);
+  }
   if (verb === 'cadence') {
     const g = pmOnly('change the scan cadence');
     if (!g.ok) return fail(g.error);
-    if (!pos[0] || !flags.board) { say('usage: pmos scan cadence <daily|weekly|off> --board <id>'); return 2; }
+    if (!pos[0]) { say('usage: pmos scan cadence <daily|weekly|off>'); return 2; }
     if (!file) return noState();
-    const r = S.setCadence(file, flags.board, pos[0], actor, { now });
+    const r = S.setCadence(file, flags.board || null, pos[0], actor, { now });
     if (!r.ok) return fail(r.error);
-    return done({ board: r.board, cadence: r.cadence }, `✓ board ${r.board}: the scan runs ${r.cadence === 'off' ? 'never' : r.cadence}`);
+    return done({ cadence: r.cadence }, `✓ the scan runs ${r.cadence === 'off' ? 'never' : r.cadence}`);
   }
   // watch
   const op = pos[0];
-  if (!['keep', 'edit', 'remove', 'add'].includes(op) || !flags.board) { say('usage: pmos scan watch keep|edit|remove|add [<item>] --board <id>'); return 2; }
+  if (!['keep', 'edit', 'remove', 'add'].includes(op)) { say('usage: pmos scan watch keep|edit|remove|add [<item>]'); return 2; }
   const g = pmOnly('change the watch list');
   if (!g.ok) return fail(g.error);
   if (!file) return noState();
-  const input = op === 'add' ? { kind: flags.kind, name: flags.name, why: flags.why } : { id: pos[1], ...(flags.name !== undefined ? { name: flags.name } : {}), ...(flags.kind !== undefined ? { kind: flags.kind } : {}), ...(flags.why !== undefined ? { why: flags.why } : {}) };
-  const r = S.watchOp(file, op, flags.board, input, actor, { now });
+  const on = flags.boards !== undefined ? listOf(flags.boards) : undefined;
+  const input = op === 'add' ? { kind: flags.kind, name: flags.name, why: flags.why, ...(on ? { boards: on } : {}) }
+    : { id: pos[1], ...(flags.name !== undefined ? { name: flags.name } : {}), ...(flags.kind !== undefined ? { kind: flags.kind } : {}), ...(flags.why !== undefined ? { why: flags.why } : {}), ...(on ? { boards: on } : {}) };
+  const r = S.watchOp(file, op, flags.board || null, input, actor, { now });
   if (!r.ok) return fail(r.error);
   return done({ id: r.id }, `✓ ${op} ${r.id}`);
 }