create-pmos 0.132.0 → 0.134.0

package/workspace/lib/vendor/scripts/onboarding/proposals.js

@@ -0,0 +1,98 @@
+'use strict';
+/* proposals.js: the proposal store for the onboarding scan (slice 1). Nothing is applied here.
+ *
+ * One append-only JSONL file per scan. For the real repo the convention is <repo>/onboarding/<scanId>/proposals.jsonl; this
+ * module takes the file as an argument and never writes into the folder that was scanned (propose refuses that).
+ * Every line goes through scripts/trust/ledger.js append, so ids are ULIDs in order, a line cannot carry its own `by`, and a
+ * line is never rewritten. Two events:
+ *   proposed  { id, kind:'proposed', proposal_id, scan_id, candidate, at, why }          written by the scan process
+ *   decided   { id, kind:'decided',  proposal_id, decision: approve|reject|revise, revision?, why, at }   by (and via) from the call path
+ * fold(lines) gives each proposal its state: open | approved | rejected | revised. The latest decision wins; earlier ones stay in `history`.
+ * A decision is a PM press: decide() and approveBulk() take the actor as an argument and refuse anything that is not 'human:'.
+ */
+const fs = require('fs');
+const path = require('path');
+const ledger = require('../trust/ledger.js');
+
+const DECISIONS = ['approve', 'reject', 'revise'];
+const STATE_OF = { approve: 'approved', reject: 'rejected', revise: 'revised' };
+const SCAN_ACTOR = { by: 'process:onboarding-scan', via: 'cli' };
+
+const inside = (child, parent) => { const r = path.relative(path.resolve(parent), path.resolve(child)); return r === '' || (!r.startsWith('..') && !path.isAbsolute(r)); };
+
+/** The actor of a decision as ledger.append wants it ({by, via}). A bare string 'human:wawan' is a PM press; anything else is refused. */
+function humanActor(actor) {
+  const a = typeof actor === 'string' ? { by: actor, via: 'ui' } : actor;
+  if (!a || typeof a.by !== 'string' || !a.by.startsWith('human:') || a.by.length <= 'human:'.length) throw new Error('a decision is a PM press: the actor must be human:<name> (got ' + (a && a.by ? a.by : 'none') + ')');
+  return { by: a.by, via: a.via || 'ui' };
+}
+
+/** Write one `proposed` event per candidate. Idempotent: a proposal id already in the file is skipped. Returns {written, skipped}. */
+function propose(file, scan, opts = {}) {
+  if (scan.root && inside(file, scan.root)) throw new Error('refusing to write proposals inside the scanned folder: ' + file);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const have = new Set(ledger.read(file).filter((l) => l.kind === 'proposed').map((l) => l.proposal_id));
+  const at = opts.now || new Date().toISOString();
+  let written = 0; let skipped = 0;
+  for (const c of scan.candidates) {
+    if (have.has(c.id)) { skipped++; continue; }
+    ledger.append(file, { id: ledger.newId(), kind: 'proposed', proposal_id: c.id, scan_id: scan.scan_id, candidate: c, at, why: 'scan ' + scan.scan_id + ': ' + c.kind + ' from ' + c.source + ' evidence' }, SCAN_ACTOR);
+    written++;
+  }
+  return { written, skipped };
+}
+
+/** fold(lines) -> [{ proposal_id, ...candidate, state, decision, why, by, at, revision, history[] }] in proposal order. */
+function fold(lines) {
+  const by = new Map();
+  for (const l of lines) {
+    if (l.kind === 'proposed') { if (!by.has(l.proposal_id)) by.set(l.proposal_id, Object.assign({}, l.candidate, { proposal_id: l.proposal_id, scan_id: l.scan_id, proposed_at: l.at, state: 'open', decision: null, why: null, by: null, at: null, revision: null, history: [] })); }
+    else if (l.kind === 'decided' && by.has(l.proposal_id)) {
+      const p = by.get(l.proposal_id);
+      p.history.push({ id: l.id, decision: l.decision, why: l.why || null, by: l.by, at: l.at, revision: l.revision || null });
+      Object.assign(p, { state: STATE_OF[l.decision] || p.state, decision: l.decision, why: l.why || null, by: l.by, at: l.at, revision: l.revision || null });
+    }
+  }
+  return [...by.values()];
+}
+const load = (file) => fold(ledger.read(file));
+
+/** One decision by the PM. approve may have no why; reject and revise must say why. */
+function decide(file, { proposal_id, decision, revision, why }, actor, opts = {}) {
+  const a = humanActor(actor);
+  if (!DECISIONS.includes(decision)) throw new Error('decision must be one of ' + DECISIONS.join(', '));
+  const w = typeof why === 'string' ? why.trim() : '';
+  if (decision !== 'approve' && !w) throw new Error(decision + ' needs a why');
+  if (decision === 'revise' && !(revision && typeof revision === 'object' && Object.keys(revision).length)) throw new Error('revise needs a revision (the fields the PM changed)');
+  if (!load(file).some((p) => p.proposal_id === proposal_id)) throw new Error('unknown proposal ' + proposal_id);
+  const ev = { id: ledger.newId(), kind: 'decided', proposal_id, decision, why: w, at: opts.now || new Date().toISOString() };
+  if (decision === 'revise') ev.revision = revision;
+  return ledger.append(file, ev, a, { noWhy: decision === 'approve' });
+}
+
+/** Bulk approve is for a proposal that is high confidence AND mechanical, and still open. Says which were skipped and why. */
+function approveBulk(file, ids, actor, opts = {}) {
+  const a = humanActor(actor);
+  const all = new Map(load(file).map((p) => [p.proposal_id, p]));
+  const approved = []; const skipped = [];
+  for (const id of ids) {
+    const p = all.get(id);
+    if (!p) { skipped.push({ id, reason: 'unknown proposal' }); continue; }
+    if (p.state !== 'open') { skipped.push({ id, reason: 'already ' + p.state }); continue; }
+    if (p.confidence !== 'high') { skipped.push({ id, reason: 'confidence is ' + p.confidence + ', not high' }); continue; }
+    if (p.source !== 'mechanical') { skipped.push({ id, reason: 'source is ' + p.source + ', not mechanical' }); continue; }
+    decide(file, { proposal_id: id, decision: 'approve', why: 'bulk approve: high confidence, mechanical' }, a, opts);
+    approved.push(id);
+  }
+  return { approved, skipped };
+}
+
+/** Counts by kind, state, confidence and source. */
+function summary(lines) {
+  const ps = Array.isArray(lines) && lines.length && lines[0].proposal_id && lines[0].state ? lines : fold(lines);
+  const count = (key) => ps.reduce((o, p) => { o[p[key]] = (o[p[key]] || 0) + 1; return o; }, {});
+  const kinds = {}; for (const p of ps) { const k = (kinds[p.kind] = kinds[p.kind] || { total: 0, open: 0, approved: 0, rejected: 0, revised: 0 }); k.total++; k[p.state]++; }
+  return { total: ps.length, by_kind: kinds, by_state: count('state'), by_confidence: count('confidence'), by_source: count('source') };
+}
+
+module.exports = { propose, fold, load, decide, approveBulk, summary, humanActor, DECISIONS };

package/workspace/lib/vendor/scripts/onboarding/scan-worker.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+'use strict';
+/* scan-worker.js: the first-run scan in its own process, so a large folder never blocks the workspace server (slice 2).
+ *   node scripts/onboarding/scan-worker.js <root> <overlayDir> <today>
+ * Reads <root> read-only (inferred brief, every initiative kept), writes brief.json, scan.json, firstlook.json and proposals.jsonl
+ * into <overlayDir>, and prints one JSON line { scan_id }. Refuses an overlay inside the scanned root. Exit 0 on success. */
+const fs = require('fs');
+const path = require('path');
+
+function run(root, dir, today) {
+  const r = path.relative(path.resolve(root), path.resolve(dir));
+  if (r === '' || (!r.startsWith('..') && !path.isAbsolute(r))) throw new Error('refusing: the overlay is inside the scanned folder');
+  const { brief, scan } = require('./infer-brief.js').firstRunScan(root, { today });
+  const look = require('./first-look.js').firstLook(scan, today);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'brief.json'), JSON.stringify(brief, null, 2));
+  fs.writeFileSync(path.join(dir, 'scan.json'), JSON.stringify(scan));
+  fs.writeFileSync(path.join(dir, 'firstlook.json'), JSON.stringify({ sentence: look.sentence, numbers: look.numbers, findings: look.findings }));
+  require('./proposals.js').propose(path.join(dir, 'proposals.jsonl'), scan);
+  return { scan_id: scan.scan_id };
+}
+
+if (require.main === module) {
+  try { process.stdout.write(JSON.stringify(run(process.argv[2], process.argv[3], process.argv[4])) + '\n'); }
+  catch (e) { process.stderr.write(String((e && e.message) || e).slice(0, 400) + '\n'); process.exitCode = 1; }
+}
+module.exports = { run };