create-pmos 0.515.0 → 0.517.0

package/workspace/lib/report-cli.js

@@ -37,8 +37,23 @@ const actorLib = require('./actor.js');
 const RS = require('./report-setups.js');
 const { parseArgs } = require('./schedule-cli');
 
-const COMMANDS = { report: ['draft', 'issue', 'list', 'propose', 'definitions', 'setups', 'finder'] };
+const COMMANDS = { report: ['make', 'read', 'find', 'write', 'check', 'rule', 'draft', 'issue', 'list', 'propose', 'definitions', 'setups', 'finder'] };
 const USAGE = [
+  'usage: pmos report make|read|find|write|check|rule — the report engine: brief, read, find, answer, render (any report, any shape)',
+  '  pmos report make <id> [--ask "<the question>"] [--readers "<who>"] [--source <kind:ref>,…] [--slot <date>]',
+  '      Steps 1 to 3: derive the brief (readers, question, window, sources; no section list), read every source PMOS reaches,',
+  '      and find what changed. An ad hoc report needs --ask. Sources: pmos · pack:<state file of readings> · connector:<name> · document:<path>.',
+  '  pmos report read <id> [--slot <date>] --from <file|->',
+  '      File the readings you read through a connector or a document: {"readings":[{id,value,unit,at,source,how,label,n,of,target}],',
+  '      "gaps":[{source,reason}]}. Every reading has a source of the brief, a date and how it was read.',
+  '  pmos report find <id> [--slot <date>] --from <file|->',
+  '      File the findings that answer the question: {"findings":[{text,readings:[ids],kind,question}]}. Each cites readings.',
+  '  pmos report write <id> [--slot <date>] --from <file|->',
+  '      Step 4 to 6: check the report.json you wrote (the outline is yours), render the document and the deck, write the checks.',
+  '      Refused when there is no answer with a reading, or when a figure is not a reading {{r:<id>}}.',
+  '  pmos report check <id> [--slot <date>]       the checks of the last write: substance first, then form',
+  '  pmos report rule <id> list | add <voice|wording|off|keep> "<text or part>" | remove <n>',
+  '      What the readers taught this report: a voice or wording rule, or a part beyond the ask turned off or kept.',
   'usage: pmos report draft|issue|list — cadence reports (for example the biweekly)',
   '  pmos report draft <cadence> [<slot>] [--now <time>] [--redraft]',
   '      Write the draft for a slot (default: today) with every number. Refuses a slot that has a draft;',
@@ -59,8 +74,9 @@ const USAGE = [
   '  every command: [--json] [--root <dir>]. The cadence is the report skill id without "report-", for example biweekly.',
 ];
 const BOOL = new Set(['json', 'redraft', 'help']);
-const VALUE = new Set(['now', 'root']);
-const ALLOWED = { draft: ['json', 'redraft', 'now', 'root'], issue: ['root'], list: ['json', 'root'], propose: ['json', 'root'], definitions: ['json', 'root'], setups: ['json', 'root'], finder: ['json', 'root'] };
+const VALUE = new Set(['now', 'root', 'ask', 'readers', 'source', 'slot', 'from']);
+const ALLOWED = { make: ['json', 'now', 'root', 'ask', 'readers', 'source', 'slot'], read: ['json', 'now', 'root', 'slot', 'from', 'source'], find: ['json', 'now', 'root', 'slot', 'from'],
+  write: ['json', 'now', 'root', 'slot', 'from'], check: ['json', 'root', 'slot'], rule: ['json', 'root'], draft: ['json', 'redraft', 'now', 'root'], issue: ['root'], list: ['json', 'root'], propose: ['json', 'root'], definitions: ['json', 'root'], setups: ['json', 'root'], finder: ['json', 'root'] };
 const CADENCE_RE = /^[a-z][a-z0-9-]{0,39}$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
@@ -129,6 +145,7 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
     return 0;
   }
 
+  if (['make', 'read', 'find', 'write', 'check', 'rule'].includes(verb)) return engineVerb(verb, { pos, flags, root, json, say, fail, isTTY, env, stdin, now });
   if (verb === 'definitions' || verb === 'setups' || verb === 'propose' || verb === 'finder') return reportWorkspace(verb, { pos, flags, root, json, say, fail, cwd, isTTY, env, stdin, now });
 
   const [cadence, slot] = pos;
@@ -170,6 +187,98 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
   return 0;
 }
 
+/** The report engine's verbs (lib/report-engine.js). An agent session and the PM may run them; issuing stays the PM's (`pmos report issue`). */
+function engineVerb(verb, { pos, flags, root, json, say, fail, isTTY, env, stdin, now }) {
+  const RE = require('./report-engine.js');
+  const id = pos[0];
+  if (!id || !RE.ID_RE.test(id)) { say(`usage: pmos report ${verb} <id> …   (the id is lower case letters, digits and dashes, for example scarlet-assessment)`); return 2; }
+  let clock = now == null ? Date.now() : now;
+  if (flags.now !== undefined) { clock = Date.parse(flags.now); if (!Number.isFinite(clock)) return fail('--now must be a time, for example 2026-10-16T09:00:00Z', 2); }
+  const slot = flags.slot !== undefined ? flags.slot : undefined;
+  if (slot !== undefined && !isDate(slot)) return fail('--slot must be a date, YYYY-MM-DD', 2);
+  const day = slot || new Date(clock).toISOString().slice(0, 10);
+  const who = actorLib.fromCli({ ...(isTTY === undefined ? {} : { isTTY }), ...(env === undefined ? {} : { env }) });
+  const readFrom = () => {
+    const src = flags.from;
+    if (!src) return { error: `--from <file|-> is required: the JSON to file` };
+    let text;
+    try { text = src === '-' ? (typeof stdin === 'string' ? stdin : fs.readFileSync(0, 'utf8')) : fs.readFileSync(path.resolve(src), 'utf8'); } catch { return { error: `could not read ${src === '-' ? 'standard input' : src}` }; }
+    try { const o = JSON.parse(text); return o && typeof o === 'object' ? { body: o } : { error: 'the JSON is an object' }; } catch { return { error: 'that is not JSON' }; }
+  };
+  const sources = flags.source ? String(flags.source).split(',').map((x) => x.trim()).filter(Boolean) : [];
+  const bad = sources.find((x) => !RE.parseSource(x));
+  if (bad) return fail(`--source ${bad}: write pmos, pack:<file>, connector:<name> or document:<path>`, 2);
+  const summary = (m) => {
+    const f = m.findings; const g = m.readings.gaps;
+    if (json) { say(JSON.stringify({ ok: true, brief: m.brief, readings: m.readings.readings.length, gaps: g, findings: f.findings, none: f.none, paths: m.paths })); return 0; }
+    say(`✓ Brief ${m.paths.brief}: for ${m.brief.readers}. Question: ${m.brief.question}`);
+    say(`  ${m.readings.readings.length} reading(s); ${g.length ? `${g.length} gap(s): ${g.map((x) => `${x.source} (${x.reason})`).join('; ')}` : 'no gap'}.`);
+    say(f.none ? '  No finding, so no draft: nothing to report yet. Read the sources the gaps name and file the readings: pmos report read ' + id + ' --from <file>'
+      : `  ${f.findings.length} finding(s): ${f.findings.slice(0, 3).map((x) => x.text).join(' · ')}`);
+    if (!f.none) say(`  Next: write ${m.paths.report} (the outline is yours) and run: pmos report write ${id}${slot ? ' --slot ' + slot : ''} --from <file>`);
+    return 0;
+  };
+  if (verb === 'make') {
+    const m = RE.make(root, id, { slot: day, ask: flags.ask, readers: flags.readers, sources, now: clock });
+    if (!m.ok) return fail(m.error);
+    return summary(m);
+  }
+  if (verb === 'read' || verb === 'find') {
+    const r = readFrom(); if (r.error) return fail(r.error, 2);
+    const add = verb === 'read' ? { add: r.body.readings || [], gaps: r.body.gaps || [] } : { addFindings: r.body.findings || [] };
+    const m = RE.make(root, id, { slot: day, sources, ...add, now: clock });
+    if (!m.ok) return fail(m.error);
+    return summary(m);
+  }
+  if (verb === 'write') {
+    const r = readFrom(); if (r.error) return fail(r.error, 2);
+    const w = RE.write(root, id, day, r.body, { actor: who, now: clock });
+    if (!w.ok) {
+      if (json) { say(JSON.stringify({ ok: false, error: w.error, checks: w.checks || null, none: !!w.none })); return 1; }
+      say(`✗ ${w.error}`);
+      return 1;
+    }
+    if (json) { say(JSON.stringify({ ok: true, path: w.path, report: w.report, checks: w.checks })); return 0; }
+    say(`✓ Wrote ${w.path} from ${w.report}. The deck is drawn from the same model.`);
+    for (const c of w.checks) say(`  ${c.pass ? '✓' : '✗'} ${c.id}: ${c.reason}`);
+    return 0;
+  }
+  if (verb === 'check') {
+    let P; try { P = RE.paths(root, id, day); } catch (e) { return fail(e.message, 2); }
+    let c; try { c = JSON.parse(fs.readFileSync(P.checks.abs, 'utf8')); } catch { return fail(`${id} ${day} has no checks yet: pmos report write ${id} --from <file>`); }
+    if (json) { say(JSON.stringify({ ok: true, ...c })); return 0; }
+    for (const x of c.checks) say(`${x.pass ? '✓' : '✗'} ${x.id}: ${x.reason}`);
+    return 0;
+  }
+  // rule
+  const act = pos[1] || 'list';
+  if (act === 'list') {
+    const rules = RE.rulesOf(root, id);
+    if (json) { say(JSON.stringify({ ok: true, rules })); return 0; }
+    if (!rules.length) say(`${id} has no rule yet; the default voice applies.`);
+    for (const x of rules) say(`${x.n}  ${x.kind}  ${x.text || x.part}${x.from ? `  (from ${x.from})` : ''}`);
+    return 0;
+  }
+  if (!actorLib.isPm(who) && !actorLib.isAgent(who)) return fail('only the PM or an agent session can change a report\'s rules');
+  if (act === 'add') {
+    const kind = pos[2]; const text = pos.slice(3).join(' ');
+    const r = RE.addRule(root, id, { kind, text: kind === 'off' || kind === 'keep' ? null : text, part: kind === 'off' || kind === 'keep' ? text : null, from: actorLib.isPm(who) ? 'the PM' : 'the writer', by: who.by, now: clock });
+    if (!r.ok) return fail(r.error);
+    if (json) { say(JSON.stringify({ ok: true, rule: r.rule })); return 0; }
+    say(`✓ Rule ${r.rule.n} kept for ${id}: ${r.rule.text || `${r.rule.kind} ${r.rule.part}`}`);
+    return 0;
+  }
+  if (act === 'remove') {
+    const r = RE.removeRule(root, id, Number(pos[2]), { by: who.by, now: clock });
+    if (!r.ok) return fail(r.error);
+    if (json) { say(JSON.stringify({ ok: true })); return 0; }
+    say(`✓ Rule ${pos[2]} removed.`);
+    return 0;
+  }
+  say('usage: pmos report rule <id> list | add <kind> "<text>" | remove <n>');
+  return 2;
+}
+
 /** The report workspace's verbs. `propose` is the one an agent run may call; `finder` is the PM's. */
 function reportWorkspace(verb, { pos, flags, root, json, say, fail, isTTY, env, stdin, now }) {
   const E = env === undefined ? process.env : env;