@cspeach/cli 1.1.14 → 1.1.16

package/dist/commands/project.js

@@ -0,0 +1,301 @@
+/**
+ * `cspeach project …` — the Project Register from the terminal
+ * (spec: docs/superpowers/specs/2026-09-18-project-register-folder-mode.md §6).
+ *
+ *   init <folder>   lead: pull the baseline from SAP, write the project folder
+ *   join <folder>   everyone: start recording against a project
+ *   lane …          lead: who owns which packages
+ *   status [folder] anyone: the register as text
+ *   outbox          what this laptop has recorded, and where
+ *   rule …          lead: settle a disagreement
+ *   leave           stop recording
+ *
+ * Every path written here is one a person typed. Nothing is written to a
+ * network location on CSPeach's own initiative, and none of this is reachable
+ * from a model tool.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildRegister, objectKey } from '@cspeach/register-core';
+import { LOCAL_PACKAGE, listCustomPackages, pullBaseline, BaselineError } from '../register/baseline.js';
+import { BASELINE_FILE, PROJECT_FILE, RegisterError, activeProject, collectRecords, defaultOutboxDir, loadState, projectIdFor, readBaseline, readLanes, readProjectFile, saveState, sha256, writeLanes, writerIdFor, } from '../register/store.js';
+import { writeRecord } from '../register/records.js';
+const CLASSIFICATIONS = ['keep', 'fix', 'retire', 'redesign'];
+const TYPES = ['clean-core', 'upgrade', 'build'];
+function flags(args) {
+    const positional = [];
+    const opts = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            opts[a.slice(2)] = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : 'true';
+        }
+        else
+            positional.push(a);
+    }
+    return { positional, opts };
+}
+const list = (v) => (v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+/** `ZFI_*` style match, used only to expand --packages patterns against the real package list. */
+function matches(pattern, value) {
+    const re = new RegExp(`^${pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`, 'i');
+    return re.test(value);
+}
+export async function runProjectCommand(args, deps) {
+    const [sub, ...rest] = args;
+    try {
+        switch (sub) {
+            case 'init': return await init(rest, deps);
+            case 'join': return join(rest, deps);
+            case 'lane': return lane(rest, deps);
+            case 'status': return status(rest, deps);
+            case 'outbox': return outbox(rest, deps);
+            case 'rule': return rule(rest, deps);
+            case 'leave': return leave(deps);
+            default:
+                deps.print('Usage: cspeach project init|join|lane|status|outbox|rule|leave   (cspeach --help for details)');
+                return sub ? 1 : 0;
+        }
+    }
+    catch (e) {
+        if (e instanceof RegisterError || e instanceof BaselineError) {
+            deps.print(`✗ ${e.message}`);
+            return 1;
+        }
+        throw e;
+    }
+}
+function requireLead(project, deps) {
+    const me = deps.identity().name;
+    if (me.trim().toLowerCase() !== project.lead.name.trim().toLowerCase()) {
+        throw new RegisterError(`Only the project lead (${project.lead.name}) changes this. You are ${me}.`);
+    }
+}
+function joinedOrThrow() {
+    const joined = activeProject();
+    if (!joined)
+        throw new RegisterError('This laptop has not joined a project. Run: cspeach project join <folder>');
+    return joined;
+}
+// ── init ────────────────────────────────────────────────────────────────────
+async function init(args, deps) {
+    const { positional, opts } = flags(args);
+    const folder = positional[0];
+    if (!folder)
+        throw new RegisterError('Usage: cspeach project init <folder> --name "<name>" [--type clean-core|upgrade|build] [--packages ZFI_*,ZSD_*] [--include-local]');
+    const dir = path.resolve(folder);
+    if (fs.existsSync(path.join(dir, PROJECT_FILE)))
+        throw new RegisterError(`${dir} already holds a project. Pick an empty folder.`);
+    const name = opts.name ?? path.basename(dir);
+    const type = (opts.type ?? 'clean-core');
+    if (!TYPES.includes(type))
+        throw new RegisterError(`--type must be one of: ${TYPES.join(', ')}`);
+    if (!deps.connect)
+        throw new RegisterError('init needs a SAP connection to pull the object list.');
+    const { sql, system } = await deps.connect(opts['sap-alias']);
+    deps.print('Reading the package list from SAP…');
+    const all = await listCustomPackages(sql);
+    const patterns = list(opts.packages);
+    let chosen = all.filter((p) => patterns.some((pat) => matches(pat, p.package)));
+    if (!patterns.length && deps.choosePackages) {
+        const picked = new Set(await deps.choosePackages(all));
+        chosen = all.filter((p) => picked.has(p.package));
+    }
+    const local = all.find((p) => p.package === LOCAL_PACKAGE)?.objects ?? 0;
+    if (!opts['include-local'])
+        chosen = chosen.filter((p) => p.package !== LOCAL_PACKAGE);
+    if (!chosen.length) {
+        throw new RegisterError(`No package chosen. ${all.length} customer packages exist; name them with --packages, e.g. --packages "ZFI_*,ZSD_*".`);
+    }
+    deps.print(`Pulling ${chosen.length} package${chosen.length === 1 ? '' : 's'}, checking each against the system's own count…`);
+    const pull = await pullBaseline(sql, { packages: chosen });
+    if (!pull.objects.length)
+        throw new RegisterError('Those packages hold no code objects. Nothing was written.');
+    const now = (deps.now ?? (() => new Date()))();
+    const projectId = projectIdFor(name);
+    const baselineText = `${JSON.stringify({ kind: 'baseline', formatVersion: 1, projectId, objects: pull.objects }, null, 1)}\n`;
+    const project = {
+        kind: 'project', formatVersion: 1, projectId, name, type, lead: { name: deps.identity().name },
+        ...(system ? { system } : {}),
+        ...(opts['atc-variant'] ? { atcVariant: opts['atc-variant'] } : {}),
+        baseline: { file: BASELINE_FILE.replace(/\\/g, '/'), sha256: sha256(baselineText), takenAt: now.toISOString(), objectCount: pull.objects.length },
+        setAside: { local: opts['include-local'] ? 0 : local, generated: pull.setAside.generated, otherTypes: pull.setAside.otherTypes },
+        createdAt: now.toISOString(),
+    };
+    fs.mkdirSync(path.join(dir, 'baseline'), { recursive: true });
+    fs.writeFileSync(path.join(dir, BASELINE_FILE), baselineText);
+    fs.writeFileSync(path.join(dir, PROJECT_FILE), `${JSON.stringify(project, null, 2)}\n`);
+    writeLanes(dir, projectId, []);
+    deps.print(`✓ ${name}: ${pull.objects.length} objects in ${chosen.length} packages. Every package matched the system's count.`);
+    deps.print(`  Set aside, not in scope: ${project.setAside.local} local ($TMP), ${pull.setAside.generated} generated, ${pull.setAside.otherTypes} non-code entries.`);
+    deps.print(`  Written to ${dir}`);
+    deps.print('  Next: cspeach project lane add <id> --owner "<name>" --packages "ZFI_*"   then each person: cspeach project join <folder>');
+    return join([dir], deps);
+}
+// ── join / leave ────────────────────────────────────────────────────────────
+function join(args, deps) {
+    const { positional, opts } = flags(args);
+    if (!positional[0])
+        throw new RegisterError('Usage: cspeach project join <project folder> [--outbox <folder>]');
+    const projectDir = path.resolve(positional[0]);
+    const project = readProjectFile(projectDir);
+    const objects = readBaseline(projectDir).length; // also verifies the checksum
+    const state = loadState();
+    const outboxDir = path.resolve(opts.outbox ?? state.projects[project.projectId]?.outboxDir ?? defaultOutboxDir(project.projectId));
+    const writerId = writerIdFor(deps.identity().name);
+    fs.mkdirSync(path.join(outboxDir, 'writers', writerId, 'records'), { recursive: true });
+    state.projects[project.projectId] = { projectDir, outboxDir, writerId };
+    state.active = project.projectId;
+    saveState(state);
+    deps.print(`✓ Joined "${project.name}" (${objects} objects, lead ${project.lead.name}) as ${writerId}.`);
+    deps.print(`  Your results are recorded on this laptop, in ${outboxDir}`);
+    deps.print('  CSPeach does not send them anywhere. Hand them in by copying that folder\'s "writers" folder into the project folder,');
+    deps.print('  or keep the outbox inside your own synced folder: cspeach project join <folder> --outbox <folder>');
+    return 0;
+}
+function leave(deps) {
+    const state = loadState();
+    if (!state.active) {
+        deps.print('This laptop is not recording against a project.');
+        return 0;
+    }
+    const was = state.active;
+    state.active = null;
+    saveState(state);
+    deps.print(`✓ Stopped recording against ${was}. Files already written stay where they are.`);
+    return 0;
+}
+// ── lane ────────────────────────────────────────────────────────────────────
+function lane(args, deps) {
+    const [verb, ...rest] = args;
+    const { positional, opts } = flags(rest);
+    const joined = joinedOrThrow();
+    const project = readProjectFile(joined.projectDir);
+    const lanes = readLanes(joined.projectDir);
+    if (verb === 'list' || !verb) {
+        if (!lanes.length)
+            deps.print('No lanes yet. cspeach project lane add <id> --owner "<name>" --packages "ZFI_*"');
+        for (const l of lanes)
+            deps.print(`${l.id.padEnd(12)} ${l.owner.padEnd(20)} ${[...l.packages, ...l.namePatterns.map((n) => `name:${n}`)].join(', ')}`);
+        return 0;
+    }
+    requireLead(project, deps);
+    const id = positional[0];
+    if (!id)
+        throw new RegisterError('Usage: cspeach project lane add <id> --owner "<name>" --packages "ZFI_*" [--names "ZCL_TAX_*"]  |  lane remove <id>');
+    if (verb === 'remove') {
+        writeLanes(joined.projectDir, project.projectId, lanes.filter((l) => l.id !== id));
+        deps.print(`✓ Lane ${id} removed.`);
+        return 0;
+    }
+    if (verb !== 'add')
+        throw new RegisterError('lane: use add, remove or list.');
+    const next = { id, owner: opts.owner ?? '', packages: list(opts.packages), namePatterns: list(opts.names) };
+    if (!next.owner || (!next.packages.length && !next.namePatterns.length)) {
+        throw new RegisterError('A lane needs --owner and at least one of --packages or --names.');
+    }
+    writeLanes(joined.projectDir, project.projectId, [...lanes.filter((l) => l.id !== id), next]);
+    const reg = registerFor(joined.projectDir, joined.outboxDir);
+    const mine = reg.register.lanes.find((l) => l.id === id);
+    deps.print(`✓ Lane ${id}: ${next.owner}, ${mine.objects} objects.`);
+    if (reg.register.totals.overlapping)
+        deps.print(`  ! ${reg.register.totals.overlapping} objects now sit in more than one lane.`);
+    if (reg.register.totals.unowned)
+        deps.print(`  ${reg.register.totals.unowned} objects still have no owner.`);
+    return 0;
+}
+// ── status ──────────────────────────────────────────────────────────────────
+function registerFor(projectDir, outboxDir) {
+    const project = readProjectFile(projectDir);
+    const collected = collectRecords(projectDir);
+    // This laptop's own outbox counts too, so a developer sees their work before handing it in.
+    const own = outboxDir && path.resolve(outboxDir) !== path.resolve(projectDir) ? collectRecords(outboxDir) : { records: [], unreadable: 0, files: 0 };
+    const register = buildRegister({
+        project, baseline: readBaseline(projectDir), lanes: readLanes(projectDir),
+        records: [...collected.records, ...own.records],
+    });
+    return { register, files: collected.files + own.files, unreadable: collected.unreadable + own.unreadable };
+}
+const STATE_WORDS = [
+    ['verified', 'verified'], ['clean', 'clean'], ['claimed', 'claimed, not measured since'], ['working', 'in work'],
+    ['decided', 'decided, not started'], ['untouched', 'untouched'], ['did-not-hold', 'fix did not hold'],
+    ['regressed', 'regressed'], ['retired', 'retired'],
+];
+function status(args, deps) {
+    const { positional } = flags(args);
+    const joined = activeProject();
+    const projectDir = positional[0] ? path.resolve(positional[0]) : joined?.projectDir;
+    if (!projectDir)
+        throw new RegisterError('Usage: cspeach project status [<project folder>]');
+    const project = readProjectFile(projectDir);
+    const { register: r, files, unreadable } = registerFor(projectDir, positional[0] ? undefined : joined?.outboxDir);
+    const t = r.totals;
+    deps.print(`${project.name}  (${project.type}, lead ${project.lead.name})`);
+    deps.print(`${t.objects} objects, ${t.active} active. ${t.decided} decided. ${t.byState.verified} verified, ${t.byState.clean} clean.`);
+    deps.print(r.lastMeasuredAt ? `Last measured ${r.lastMeasuredAt.slice(0, 16).replace('T', ' ')} UTC.` : 'Not measured yet: "verified" and "clean" need an ATC run.');
+    deps.print('');
+    for (const [state, word] of STATE_WORDS)
+        if (t.byState[state])
+            deps.print(`  ${String(t.byState[state]).padStart(6)}  ${word}`);
+    deps.print('');
+    if (r.lanes.length) {
+        deps.print('Lane         Owner                Objects  Done  Last record');
+        for (const l of r.lanes) {
+            const done = l.byState.verified + l.byState.clean + l.byState.retired;
+            deps.print(`${l.id.padEnd(12)} ${l.owner.padEnd(20)} ${String(l.objects).padStart(7)} ${String(done).padStart(5)}  ${l.lastRecordAt ? l.lastRecordAt.slice(0, 10) : 'nothing yet'}`);
+        }
+        deps.print('');
+    }
+    if (t.unowned)
+        deps.print(`! ${t.unowned} objects have no owner.`);
+    if (t.overlapping)
+        deps.print(`! ${t.overlapping} objects sit in more than one lane.`);
+    if (t.conflicts) {
+        deps.print(`! ${t.conflicts} objects have conflicting decisions. The lead settles each with: cspeach project rule <TYPE> <NAME> <decision>`);
+        for (const o of r.objects.filter((x) => x.decision?.conflict).slice(0, 10)) {
+            deps.print(`    ${o.key}: ${Object.entries(o.decision.conflict).map(([w, c]) => `${w} says ${c}`).join(', ')}`);
+        }
+    }
+    const s = r.skipped;
+    if (unreadable)
+        deps.print(`  ${unreadable} of ${files} files could not be read yet (still syncing, or damaged).`);
+    if (s.rowsNotInBaseline)
+        deps.print(`  ${s.rowsNotInBaseline} rows named objects that are not in this project: ${r.unknownKeys.slice(0, 5).join(', ')}`);
+    if (s.otherProject)
+        deps.print(`  ${s.otherProject} files belong to another project and were ignored.`);
+    if (s.rulingsNotFromLead)
+        deps.print(`  ${s.rulingsNotFromLead} rulings were not from the lead and were ignored.`);
+    return 0;
+}
+// ── outbox / rule ───────────────────────────────────────────────────────────
+function outbox(_args, deps) {
+    const joined = joinedOrThrow();
+    const dir = path.join(joined.outboxDir, 'writers', joined.writerId, 'records');
+    const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort() : [];
+    deps.print(`Records this laptop has written for ${joined.projectId}: ${files.length}`);
+    deps.print(`  ${dir}`);
+    for (const f of files.slice(-15)) {
+        let rows = '?';
+        try {
+            rows = String(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')).rows.length);
+        }
+        catch { /* listed anyway */ }
+        deps.print(`  ${f}  (${rows} rows)`);
+    }
+    deps.print('Each file is plain JSON: object names, decisions, statuses. No source code. Open one in Notepad to check.');
+    return 0;
+}
+function rule(args, deps) {
+    const { positional, opts } = flags(args);
+    const [type, name, classification] = positional;
+    if (!type || !name || !CLASSIFICATIONS.includes(classification)) {
+        throw new RegisterError(`Usage: cspeach project rule <TYPE> <NAME> ${CLASSIFICATIONS.join('|')} [--reason "<why>"]`);
+    }
+    const joined = joinedOrThrow();
+    requireLead(readProjectFile(joined.projectDir), deps);
+    const res = writeRecord(joined, 'ruling', [{ key: objectKey(type, name), classification, ...(opts.reason ? { reason: opts.reason } : {}) }], deps.identity(), { dir: path.join(joined.projectDir, 'rulings'), now: deps.now?.() });
+    if (!res.file)
+        throw new RegisterError(`${objectKey(type, name)} is not in this project's baseline.`);
+    deps.print(`✓ Ruled ${objectKey(type, name)} = ${classification}.`);
+    return 0;
+}