create-pmos 0.52.0 → 0.53.0

package/workspace/lib/report-cli.js

@@ -0,0 +1,152 @@
+'use strict';
+/* report-cli.js — `pmos report …`: draft a cadence report, issue it, list the reports (pm-os-absorb Run 5, PRD R22,
+ * R24, R25; D86 points 2 and 3).
+ *
+ *   pmos report draft <cadence> [<slot>] [--now <time>] [--redraft] [--json] [--root <dir>]
+ *   pmos report issue <cadence> <slot> [--root <dir>]
+ *   pmos report list [<cadence>] [--json] [--root <dir>]
+ *
+ * `draft` is the script with no model (R22.1): lib/report-draft.js folds the ledgers since the last issue and writes
+ * every number into `<state>/reports/<cadence>/<slot>.md`, with one empty note marker per block. It refuses a slot that
+ * has a draft already (X18, from local files only, never a fetch); `--redraft` writes it again and keeps every note.
+ * `<slot>` defaults to today; `--now` fixes the clock, so two runs with the same inputs write the same bytes.
+ *
+ * `issue` is a PM-only act (R25): pm-guard.js requirePmCli({ act: 'issue' }) asks the PM to type `<cadence>-<slot>`
+ * at an interactive terminal. An agent session, a call with no terminal and a wrong text are refused, and nothing is
+ * written. Then lib/issues.js appendFromCli records the path and the git blob sha, which freezes the report. Nothing
+ * is sent: print the file or copy it as markdown.
+ *
+ * Who writes is decided by the call path, never by an argument (lib/actor.js). The verb never calls the server.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const reportDraft = require('./report-draft.js');
+const issues = require('./issues.js');
+const guard = require('./pm-guard.js');
+const actorLib = require('./actor.js');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = { report: ['draft', 'issue', 'list'] };
+const USAGE = [
+  '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;',
+  '      --redraft writes it again and keeps every note.',
+  '  pmos report issue <cadence> <slot>',
+  '      Freeze the draft. Only the PM can do this, at a terminal, by typing <cadence>-<slot>. Nothing is sent.',
+  '  pmos report list [<cadence>]',
+  '      Show the drafts and the issued reports.',
+  '  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'] };
+const CADENCE_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function parse(argv) {
+  const rest = []; const bools = {};
+  for (const a of argv) {
+    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);
+  return { pos, flags: { ...flags, ...bools } };
+}
+
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+const isDate = (s) => typeof s === 'string' && DATE_RE.test(s) && new Date(s + 'T00:00:00Z').toISOString().slice(0, 10) === s;
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isTTY, env, ask, now } = {}) {
+  const args = argv[0] === 'report' ? argv.slice(1) : argv.slice();
+  const verb = args[0];
+  const { pos, flags } = parse(args.slice(1));
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h' || flags.help) {
+    for (const l of USAGE) say(l);
+    return verb ? 0 : 1;
+  }
+  if (!COMMANDS.report.includes(verb)) { say(`unknown report command "${verb}". Use one of: ${COMMANDS.report.join(', ')}`); return 2; }
+  if ('by' in flags || 'via' in flags) { say(`the call path sets who writes; --${'by' in flags ? 'by' : 'via'} is not an option`); return 2; }
+  for (const k of Object.keys(flags)) {
+    if (!BOOL.has(k) && !VALUE.has(k)) { say(`unknown option --${k}`); return 2; }
+    if (!ALLOWED[verb].includes(k)) { say(`--${k} is not an option of report ${verb}`); return 2; }
+    if (VALUE.has(k) && flags[k] === '') { say(`--${k} needs a value`); return 2; }
+  }
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const json = !!flags.json;
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say(`✗ ${error}`); return code; };
+
+  if (verb === 'list') {
+    const cadence = pos[0];
+    if (cadence !== undefined && !CADENCE_RE.test(cadence)) { say('usage: pmos report list [<cadence>]'); return 2; }
+    let state;
+    try { state = reportDraft.stateRel(root); }
+    catch (e) { return fail(String((e && e.message) || e).slice(0, 200)); }
+    const iss = issues.readIssues(root);
+    const rows = [];
+    let dirs = [];
+    try { dirs = fs.readdirSync(path.join(root, state, 'reports'), { withFileTypes: true }).filter((d) => d.isDirectory() && d.name !== 'definitions').map((d) => d.name); } catch { dirs = []; }
+    for (const c of new Set([...dirs, ...iss.issues.map((r) => r.cadence)])) {
+      if (cadence && c !== cadence) continue;
+      let files = [];
+      try { files = fs.readdirSync(path.join(root, state, 'reports', c)).filter((f) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f)); } catch { files = []; }
+      const slots = new Set([...files.map((f) => f.slice(0, 10)), ...iss.issues.filter((r) => r.cadence === c).map((r) => r.slot)]);
+      for (const slot of slots) {
+        const issued = iss.issues.find((r) => r.cadence === c && r.slot === slot) || null;
+        rows.push({ cadence: c, slot, path: `${state}/reports/${c}/${slot}.md`,
+          issued: issued ? { at: issued.at, by: actorLib.pageName(issued.by), sha: issued.sha } : null });
+      }
+    }
+    rows.sort((a, b) => (a.cadence < b.cadence ? -1 : a.cadence > b.cadence ? 1 : 0) || (a.slot < b.slot ? 1 : a.slot > b.slot ? -1 : 0));
+    if (json) { say(JSON.stringify({ ok: true, reports: rows, flags: iss.flags })); return 0; }
+    if (!rows.length) say(cadence ? `No ${cadence} report yet. Type: pmos report draft ${cadence}` : 'No report yet. Type: pmos report draft biweekly');
+    for (const r of rows) say(`${r.cadence} ${r.slot}  ${r.issued ? `issued ${r.issued.at.slice(0, 10)} by ${r.issued.by}` : 'draft'}  ${r.path}`);
+    for (const f of iss.flags) say(`! issues.jsonl: ${f.why}`);
+    return 0;
+  }
+
+  const [cadence, slot] = pos;
+  if (!cadence || !CADENCE_RE.test(cadence) || pos.length > 2) { say(`usage: pmos report ${verb} <cadence> ${verb === 'issue' ? '<slot>' : '[<slot>]'}`); return 2; }
+  if (slot !== undefined && !isDate(slot)) return fail('the slot must be a date, YYYY-MM-DD', 2);
+
+  if (verb === 'draft') {
+    let clock = 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 draft = reportDraft.draftOf(root, { cadence, slot, now: clock });
+    if (!draft.ok) return fail(draft.error);
+    const who = actorLib.fromCli({ ...(isTTY === undefined ? {} : { isTTY }), ...(env === undefined ? {} : { env }) });
+    const r = reportDraft.writeDraft(root, draft, { actor: who, fresh: !flags.redraft });
+    if (!r.ok) {
+      if (r.status === 409 && !flags.redraft && !/issued/.test(r.error)) {
+        return fail(`${r.error}. To write it again and keep every note, type: pmos report draft ${cadence} ${draft.slot} --redraft`);
+      }
+      return fail(r.error);
+    }
+    if (json) { say(JSON.stringify({ ok: true, path: r.path, sha: r.sha, slot: draft.slot, window: draft.window, blocks: draft.blocks.map((b) => b.id) })); return 0; }
+    say(`✓ ${flags.redraft ? 'Drafted again' : 'Drafted'} ${r.path}: ${draft.blocks.length === 1 ? '1 initiative' : `${draft.blocks.length} initiatives`}, ${draft.window.from} to ${draft.window.to}.`);
+    say('  Write prose only between the note markers. Type no number: the script writes them.');
+    return 0;
+  }
+
+  // issue — the PM types <cadence>-<slot>, so a report is never issued by accident or by an agent.
+  if (!slot) { say('usage: pmos report issue <cadence> <slot>'); return 2; }
+  const g = await guard.requirePmCli({ act: 'issue', expect: `${cadence}-${slot}`,
+    ...(isTTY === undefined ? {} : { isTTY }), ...(env === undefined ? {} : { env }), ask: ask || guard.askAtTerminal });
+  if (!g.ok) return fail(g.error);
+  let rel;
+  try { rel = reportDraft.draftPath(root, cadence, slot); } catch (e) { return fail(String((e && e.message) || e).slice(0, 200)); }
+  let buf;
+  try { buf = fs.readFileSync(path.join(root, rel)); } catch { return fail(`${rel} does not exist. Draft it first: pmos report draft ${cadence} ${slot}`); }
+  const r = issues.appendFromCli(root, [{ ev: 'issued', cadence, slot, path: rel, sha: issues.blobSha(buf) }], { actor: g.actor, now });
+  if (!r.ok) return fail(r.error);
+  say(`✓ Issued ${rel} (blob ${r.written[0].sha.slice(0, 12)}). It is frozen: a draft of this slot is refused from now on.`);
+  say('  Nothing was sent. Print it or copy it as markdown.');
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };