@cspeach/cli 1.1.30 → 1.1.32

package/dist/register/plan-import.js

@@ -0,0 +1,328 @@
+/**
+ * The Plan sheet, read back (spec 2026-10-06 §8). `team report` writes it; the
+ * lead edits the five columns before the dash in Excel; `team plan import`
+ * reads it here, compares it with what the export said and what the plan says
+ * now, and hands back the changes as the rows of ONE `excel` plan record.
+ *
+ * Read the strict way:
+ *  - the header row is matched by column name (any case, trimmed), unknown columns ignored;
+ *  - rows are matched by Type + Object, never by position; blank rows ignored;
+ *  - a cell is a change only when it differs from what the export wrote AND from
+ *    what the plan says now, so a cell the lead never touched never undoes
+ *    someone else's newer change;
+ *  - a change to a field a newer plan, decision or ruling record touched is a
+ *    clash: shown with both values and skipped, never overwritten;
+ *  - the fact columns after the dash are compared with the export and never read.
+ *
+ * Pure: buffer and register in, rows and counts out. Nothing is written here.
+ */
+import { normalizeKey, objectKey, planRows, PLAN_COLUMNS, } from '@cspeach/register-core';
+import { readSheets } from '../tools/filesystem/extract-xlsx.js';
+import { RegisterError } from './store.js';
+import { EXPORT_STAMP } from './workbooks.js';
+export const NOT_A_PLAN_SHEET = 'This is not a Plan sheet CSPeach wrote.';
+const MAX_NOTE = 300;
+const STAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const SERIAL = /^\d{5}(\.\d+)?$/;
+/** Excel's day zero for serial dates (the 1900 system, after its leap-year bug). */
+const EXCEL_EPOCH = Date.UTC(1899, 11, 30);
+const DASH = PLAN_COLUMNS.indexOf('—');
+const FACT_COLUMNS = PLAN_COLUMNS.slice(DASH + 1);
+const lower = (s) => s.trim().toLowerCase();
+const CANONICAL = new Map(PLAN_COLUMNS.map((c) => [lower(c), c]));
+// The Objects sheet (1.1.32) heads the decided level "Level decided", beside its "Level now".
+CANONICAL.set('level decided', 'Level');
+/**
+ * The Plan sheet and the export stamp of a workbook `team report` wrote.
+ * Throws the one sentence for anything else: not an .xlsx, no Plan sheet, no
+ * stamp in the Read me, or a Plan sheet without Object and Type columns.
+ */
+export function readPlanSheet(buffer) {
+    let sheets;
+    try {
+        sheets = readSheets(buffer);
+    }
+    catch {
+        throw new RegisterError(NOT_A_PLAN_SHEET);
+    }
+    // 1.1.32 writes "Objects" with the stamp on "Summary"; a 1.1.31 workbook has "Plan" and "Read me".
+    const plan = sheets.find((s) => lower(s.name) === 'objects') ?? sheets.find((s) => lower(s.name) === 'plan');
+    const stampCell = sheets.filter((s) => lower(s.name) === 'summary' || lower(s.name) === 'read me')
+        .flatMap((s) => s.rows.flat()).find((c) => lower(c).startsWith(lower(EXPORT_STAMP)));
+    const exportStamp = stampCell ? stampCell.trim().slice(EXPORT_STAMP.length).trim() : '';
+    if (!plan || !STAMP.test(exportStamp) || Number.isNaN(Date.parse(exportStamp)))
+        throw new RegisterError(NOT_A_PLAN_SHEET);
+    const at = plan.rows.findIndex((r) => r.some((c) => c.trim() !== ''));
+    const header = at === -1 ? [] : plan.rows[at].map((c) => c.trim());
+    // Column name → index; the first column of a name wins, names it does not know are ignored.
+    const index = new Map();
+    header.forEach((name, i) => {
+        const canonical = CANONICAL.get(lower(name));
+        if (canonical && !index.has(canonical))
+            index.set(canonical, i);
+    });
+    if (!index.has('Object') || !index.has('Type'))
+        throw new RegisterError(NOT_A_PLAN_SHEET);
+    const rows = [];
+    for (const raw of plan.rows.slice(at + 1)) {
+        const row = {};
+        for (const [name, i] of index)
+            row[name] = (raw[i] ?? '').trim();
+        if (Object.values(row).every((v) => v === ''))
+            continue;
+        rows.push(row);
+    }
+    return { exportStamp, header, rows };
+}
+// ── cells ────────────────────────────────────────────────────────────────────
+/** 1–5 (also `2.0`, ` 2 `), `defer` in any case, '' = blank, undefined = unreadable. */
+function priorityCell(cell) {
+    const v = cell.trim();
+    if (!v)
+        return '';
+    if (lower(v) === 'defer')
+        return 'defer';
+    const m = /^([1-5])(?:\.0+)?$/.exec(v);
+    return m ? Number(m[1]) : undefined;
+}
+/** A real day as YYYY-MM-DD, or an Excel serial (46000 → 2025-12-09); '' = blank; undefined = unreadable. */
+function dateCell(cell) {
+    const v = cell.trim();
+    if (!v)
+        return '';
+    if (DAY.test(v)) {
+        const d = new Date(`${v}T00:00:00Z`);
+        return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === v ? v : undefined;
+    }
+    if (SERIAL.test(v))
+        return new Date(EXCEL_EPOCH + Math.floor(Number(v)) * 86_400_000).toISOString().slice(0, 10);
+    return undefined;
+}
+function scopeCell(cell) {
+    const v = lower(cell);
+    if (!v)
+        return '';
+    // `1`/`0`: a cell Excel saved as a boolean reads back as a number.
+    if (v === 'yes' || v === 'y' || v === 'true' || v === '1')
+        return true;
+    if (v === 'no' || v === 'n' || v === 'false' || v === '0')
+        return false;
+    return undefined;
+}
+/** A lane id from `Owner (id)` (as exported), an owner name or a lane id, any case. '' = blank; undefined = unknown. */
+function laneCell(cell, register, current) {
+    const v = cell.trim();
+    if (!v)
+        return '';
+    const byId = (id) => register.lanes.find((l) => lower(l.id) === lower(id))?.id;
+    const label = /^(.*)\(([^()]+)\)\s*$/.exec(v);
+    if (label) {
+        const id = byId(label[2]);
+        if (id && lower(register.lanes.find((l) => l.id === id).owner) === lower(label[1]))
+            return id;
+    }
+    const id = byId(v);
+    if (id)
+        return id;
+    const owned = register.lanes.filter((l) => lower(l.owner) === lower(v));
+    if (owned.length === 1)
+        return owned[0].id;
+    // An owner of several lanes: the lane the object is in now, if it is one of them.
+    if (owned.length > 1 && owned.some((l) => l.id === current))
+        return current;
+    return undefined;
+}
+// ── values the plan holds for an object ─────────────────────────────────────
+const manualOf = (o) => {
+    const e = o.priority.effective;
+    return e.source === 'set by hand' || e.source === 'Excel plan' ? e.band : null;
+};
+const laneLabel = (register, id) => {
+    const l = id ? register.lanes.find((x) => x.id === id) : undefined;
+    return l ? `${l.owner} (${l.id})` : 'no lane';
+};
+const shownValue = (v) => (v === '' ? 'blank' : v);
+/** The cell as the fact columns compare it: trimmed, and a number read as a number (3 = "3" = "3.0"). */
+function sameFact(a, b) {
+    const x = a === null || a === undefined ? '' : String(a).trim();
+    const y = b === null || b === undefined ? '' : String(b).trim();
+    if (x === y)
+        return true;
+    return x !== '' && y !== '' && Number.isFinite(Number(x)) && Number(x) === Number(y);
+}
+/** field → newest (by, at) of a plan, decision or ruling record newer than the export, per object. */
+function newerTouches(records, stamp) {
+    const out = new Map();
+    const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+    for (const r of records) {
+        if (!isObj(r) || typeof r.at !== 'string' || !(r.at > stamp) || !Array.isArray(r.rows))
+            continue;
+        const by = isObj(r.by) && typeof r.by.name === 'string' ? r.by.name : 'someone';
+        for (const row of r.rows) {
+            if (!isObj(row) || typeof row.key !== 'string')
+                continue;
+            const key = normalizeKey(row.key);
+            if (!key)
+                continue;
+            const fields = [];
+            if (r.recordType === 'decision' || r.recordType === 'ruling')
+                fields.push('Priority');
+            else if (r.recordType === 'plan') {
+                const a = r.action;
+                if (a === 'priority' || (a === 'excel' && 'priority' in row))
+                    fields.push('Priority');
+                if (a === 'assign' || (a === 'excel' && 'lane' in row))
+                    fields.push('Lane');
+                if (a === 'scope' || (a === 'excel' && 'inScope' in row))
+                    fields.push('In scope');
+                if ((a === 'note' || a === 'excel') && 'targetDate' in row)
+                    fields.push('Target date');
+                if ((a === 'note' || a === 'excel') && 'note' in row)
+                    fields.push('Note');
+            }
+            for (const f of fields) {
+                const byField = out.get(key) ?? new Map();
+                const had = byField.get(f);
+                if (!had || r.at > had.at)
+                    byField.set(f, { by, at: r.at });
+                out.set(key, byField);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The changes the sheet asks for. `register` is the plan now; `exported` the
+ * plan as the export saw it (built from the records up to the export stamp),
+ * the current one when not given; `records` every record the folder holds, for
+ * the clashes.
+ */
+export function diffPlan(sheet, register, records, opts = {}) {
+    const exported = opts.exported ?? register;
+    const now = new Map(register.objects.map((o) => [o.key, o]));
+    const then = new Map(exported.objects.map((o) => [o.key, o]));
+    const exportedFacts = new Map();
+    for (const row of planRows(exported)) {
+        exportedFacts.set(objectKey(String(row[1]), String(row[0])), Object.fromEntries(PLAN_COLUMNS.map((c, i) => [c, row[i]])));
+    }
+    const touched = newerTouches(records, sheet.exportStamp);
+    const counts = {
+        priorities: 0, moves: 0, scope: 0, notes: 0, unchanged: 0, notInTeamProject: 0, clashes: 0, factEditsIgnored: 0, unknownLanes: 0, unreadableCells: 0, blankCells: 0,
+    };
+    const out = { rows: [], counts, clashes: [], unknownLanes: [], exportStamp: sheet.exportStamp };
+    const seen = new Set();
+    for (const cells of sheet.rows) {
+        if (Object.values(cells).every((v) => !v || !v.trim()))
+            continue; // a blank row says nothing
+        const type = cells.Type ?? '';
+        const name = cells.Object ?? '';
+        const key = type && name ? objectKey(type, name) : '';
+        const o = key ? now.get(key) : undefined;
+        if (!o) {
+            counts.notInTeamProject += 1;
+            continue;
+        }
+        if (seen.has(key))
+            continue; // the first row of an object counts
+        seen.add(key);
+        const was = then.get(key) ?? o;
+        const row = { key };
+        let unreadable = 0;
+        let blank = 0;
+        let clashed = 0;
+        let unknownLane = false;
+        /** A change the lead made in the sheet: skipped when a newer record touched the same field. */
+        const change = (field, sheetText, nowText, apply) => {
+            const newer = touched.get(key)?.get(field);
+            if (newer) {
+                out.clashes.push({ key, field, sheet: shownValue(sheetText), now: shownValue(nowText), by: newer.by, at: newer.at });
+                clashed += 1;
+                return;
+            }
+            apply();
+        };
+        if ('Priority' in cells) {
+            const v = priorityCell(cells.Priority);
+            if (v === undefined)
+                unreadable += 1;
+            else {
+                const desired = v === '' ? null : v;
+                if (desired !== manualOf(was) && desired !== manualOf(o)) {
+                    change('Priority', cells.Priority, String(o.priority.effective.band), () => { row.priority = desired; counts.priorities += 1; });
+                }
+            }
+        }
+        if ('Lane' in cells) {
+            const v = laneCell(cells.Lane, register, o.lane);
+            const exportedCell = laneLabel(exported, was.lane);
+            if (v === undefined) {
+                // A label the export wrote for a lane removed since is not the lead's edit.
+                if (!sameFact(cells.Lane, exportedCell)) {
+                    unknownLane = true;
+                    out.unknownLanes.push({ key, lane: cells.Lane });
+                }
+            }
+            else if (v === '') {
+                // Blank gives an object the lead moved back to the lane patterns; a pattern lane has nothing to give back.
+                if (was.laneFrom === 'assigned' && o.laneFrom === 'assigned') {
+                    change('Lane', '', laneLabel(register, o.lane), () => { row.lane = null; counts.moves += 1; });
+                }
+                else if (was.laneFrom !== 'assigned' && o.laneFrom !== 'assigned' && o.lane !== null) {
+                    blank += 1; // a lane from the patterns: blank cannot take it away
+                }
+            }
+            else if (v !== was.lane && v !== o.lane) {
+                change('Lane', cells.Lane, laneLabel(register, o.lane), () => { row.lane = v; counts.moves += 1; });
+            }
+        }
+        if ('In scope' in cells) {
+            const v = scopeCell(cells['In scope']);
+            if (v === undefined)
+                unreadable += 1;
+            else if (v === '')
+                blank += 1; // in scope is yes or no, never nothing
+            else if (v !== was.inScope && v !== o.inScope) {
+                change('In scope', cells['In scope'], o.inScope ? 'yes' : 'no', () => { row.inScope = v; counts.scope += 1; });
+            }
+        }
+        let noted = false;
+        if ('Target date' in cells) {
+            const v = dateCell(cells['Target date']);
+            const before = was.plan.targetDate ?? '';
+            const current = o.plan.targetDate ?? '';
+            if (v === undefined)
+                unreadable += 1;
+            else if (v !== before && v !== current) {
+                change('Target date', cells['Target date'], current, () => { row.targetDate = v; noted = true; });
+            }
+        }
+        if ('Note' in cells) {
+            const v = cells.Note;
+            const before = was.plan.note ?? '';
+            const current = o.plan.note ?? '';
+            if (v.length > MAX_NOTE)
+                unreadable += 1;
+            else if (v !== before && v !== current) {
+                change('Note', v, current, () => { row.note = v; noted = true; });
+            }
+        }
+        if (noted)
+            counts.notes += 1;
+        const facts = exportedFacts.get(key);
+        for (const f of FACT_COLUMNS)
+            if (f in cells && facts && !sameFact(cells[f], facts[f]))
+                counts.factEditsIgnored += 1;
+        counts.unreadableCells += unreadable;
+        counts.blankCells += blank;
+        counts.clashes += clashed;
+        if (unknownLane)
+            counts.unknownLanes += 1;
+        const accepted = Object.keys(row).length > 1;
+        if (accepted)
+            out.rows.push(row);
+        else if (!unreadable && !blank && !clashed && !unknownLane)
+            counts.unchanged += 1;
+    }
+    return out;
+}

package/dist/register/records.js

@@ -13,6 +13,7 @@ import path from 'node:path';
 import { classificationFromCcaDetail, fromCcaDetailKey, normalizeKey, normalizeRuleId, objectKey, } from '@cspeach/register-core';
 import { defaultRand, readBaseline } from './store.js';
 import { safeDetailRel, resolveDetailFileSync } from '../projects/detail-path.js';
+import { writeWhole } from './write-whole.js';
 const FIX_STATUSES = new Set(['fixed', 'skipped', 'failed', 'pending']);
 export function writeRecord(joined, recordType, rows, by, opts = {}) {
     const known = new Set(readBaseline(joined.projectDir).map((o) => objectKey(o.type, o.name)));
@@ -63,6 +64,30 @@ export function writeRecord(joined, recordType, rows, by, opts = {}) {
     }
     return { file, written: kept.length, refused };
 }
+/** `20261007T080000Z`: the ISO time without dashes, colons or milliseconds, as every record file name carries it. */
+export const fileStamp = (now) => now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+/**
+ * A record the LEAD writes into one of the lead's own folders (`plan/`,
+ * `baseline/`), whose rows may be empty — a plan header says everything in
+ * its header fields. The caller has already decided which rows belong; this
+ * only writes, whole then renamed. Never under `writers/`.
+ */
+export function writeLeadRecord(dir, projectId, recordType, header, rows, by, opts = {}) {
+    const now = opts.now ?? new Date();
+    const recordId = (opts.rand ?? defaultRand)(6);
+    const name = opts.fileName ? path.basename(opts.fileName) : `${fileStamp(now)}-${recordType}-${recordId.slice(0, 4)}.json`;
+    const file = path.join(dir, name);
+    const own = {
+        kind: 'record', formatVersion: 1, recordId, projectId, recordType,
+        at: now.toISOString(), by: { name: by.name, writer: by.writer },
+    };
+    // A header field never stands in for one of the record's own fields.
+    const extra = Object.fromEntries(Object.entries(header).filter(([k]) => !(k in own) && k !== 'rows'));
+    const record = { ...own, ...extra, rows: [...rows] };
+    writeWhole(file, `${JSON.stringify(record, null, 2)}
+`);
+    return { file, recordId };
+}
 /**
  * Decisions from a saved CCA assessment. The full list lives in the detail
  * file's `objects.json` (the envelope table stops at 50 rows), so that is read
@@ -142,7 +167,15 @@ export function fixRowsFromUpgradeProgress(content, baseline) {
  * per row, clean-core-confirm.ts). The five words map onto the four
  * classifications (spec §4.2); a fix or a rebuild with no target reaches A.
  */
-export function decisionRowsFromCleanCore(content) {
+export function decisionRowsFromCleanCore(content, 
+/**
+ * Who said Yes, and when. With it, a confirmed row whose proposal NAMED the
+ * level its target is read from — a fix/rebuild target, a keep/exception
+ * level — carries `targetBy` (F3, M19): the person's Yes set that target.
+ * A fix with no target in the proposal still records the legacy A, and that
+ * is no target. Absent: rows exactly as before.
+ */
+by) {
     const rows = [];
     for (const r of content.adjudications ?? []) {
         if (r?.confirmed !== true)
@@ -156,11 +189,13 @@ export function decisionRowsFromCleanCore(content) {
         if (!base)
             continue;
         const reason = typeof r.reason === 'string' ? r.reason.trim().slice(0, 300) : '';
+        const named = moves ? !!r.targetLevel : base.classification === 'keep' && !!r.level;
         rows.push({
             key: objectKey(r.objectType, r.objectName), ...base,
             ...(r.level ? { level: r.level } : {}),
             ...(moves ? { targetLevel: r.targetLevel ?? 'A' } : {}),
             ...(reason ? { reason } : {}),
+            ...(by && named ? { targetBy: { name: by.name, at: by.at } } : {}),
         });
     }
     return rows;
@@ -189,8 +224,10 @@ opts = {}) {
         return { ...res, refused: [...res.refused, ...ambiguous.map((n) => `${n} (name matches more than one object type)`)] };
     }
     if (env.artefactType === 'clean-core-decision') {
-        const rows = decisionRowsFromCleanCore(env.content);
-        return writeRecord(joined, 'decision', rows, by, { source, ...opts });
+        // Every row here had a person's Yes (confirmCleanCoreRows / the journey's row card).
+        const at = (opts.now ?? new Date()).toISOString();
+        const rows = decisionRowsFromCleanCore(env.content, { name: by.name, at });
+        return writeRecord(joined, 'decision', rows, by, { source, ...opts, now: opts.now ?? new Date(at) });
     }
     return null;
 }

package/dist/register/rule-proposal.js

@@ -0,0 +1,4 @@
+let slot = null;
+export const setRuleProposal = (p) => { slot = JSON.parse(JSON.stringify(p)); };
+export const ruleProposalFor = (projectId) => (slot && slot.projectId === projectId ? slot : null);
+export const clearRuleProposal = () => { slot = null; };