@cspeach/cli 1.1.29 → 1.1.31

package/dist/commands/team-discover.js

@@ -0,0 +1,195 @@
+/**
+ * `cspeach team discover` — the estate inventory before anyone chose a scope
+ * (spec docs/superpowers/specs/2026-10-06-cca-discovery-team-plan-design.md §5, §7).
+ *
+ * Read only: every statement is a fixed one in register/discover.ts and goes
+ * through sap-client's read-only gate. Files go into `<folder>/discovery/`,
+ * each written whole then renamed; older discoveries are never deleted (the
+ * newest stamp wins on read). On a team project folder only its lead may run
+ * it, and that is checked before SAP is even reached.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { NO_USAGE_LINE, estateSheets, estateSummaryOf, objectKey, usageLineWithWindow } from '@cspeach/register-core';
+import { discover } from '../register/discover.js';
+import { DISCOVERY_DIR, RegisterError, TEAM_FILE, loadState, readBaseline, readProjectFile } from '../register/store.js';
+import { fileStamp, writeRecord } from '../register/records.js';
+import { writeWhole } from '../register/write-whole.js';
+import { writeXlsxFile } from '../register/xlsx.js';
+import { HELD } from '../register/workbooks.js';
+import { flags, list, onInterrupt, requireLead, whoAmI } from './team.js';
+export const DISCOVER_USAGE = 'Usage: cspeach team discover [--out <folder>] [--prefixes Z,Y] [--namespaces auto|/ACME/,…] [--sap-alias S4H] '
+    + '[--no-xref] [--no-jobs] [--max-minutes 30]';
+const DISCOVER_OPTIONS = ['out', 'prefixes', 'namespaces', 'sap-alias', 'no-xref', 'no-jobs', 'max-minutes'];
+const DISCOVER_FLAGS = ['no-xref', 'no-jobs'];
+/** 2,931 — every count on the estate line reads the way a person writes it. */
+const n = (v) => v.toLocaleString('en-US');
+/** The usage part of the estate line, from the summary's one sentence. */
+function usageWords(s) {
+    if (s.usageLine === NO_USAGE_LINE)
+        return 'none recorded on this system';
+    return usageLineWithWindow(s).replace(/^Usage /, '').replace(/\.$/, '');
+}
+export function estateLine(s) {
+    const t = s.totals;
+    return `Estate: ${n(t.packages)} packages · ${n(t.codeObjects)} code objects · ${n(t.nonCodeObjects)} non-code · `
+        + `${n(t.local)} outside packages · usage: ${usageWords(s)} · modifications of SAP objects: ${n(t.modifications)} · unknowns: ${n(t.unknowns)}`;
+}
+/** The workbook sheets of an estate summary, as the xlsx writer takes them. */
+export function estateWorkbook(s) {
+    return estateSheets(s).map((sh) => ({ name: sh.name, header: sh.table.header, rows: sh.table.rows }));
+}
+/**
+ * The evidence rows of an objects file, for the objects a baseline holds.
+ * Rows for anything else are not written; they are counted.
+ */
+export function evidenceRows(objects, baselineKeys) {
+    const list = objects?.objects;
+    if (objects?.kind !== 'estate-objects' || !Array.isArray(list))
+        return null;
+    const rows = [];
+    const seen = new Set();
+    let outside = 0;
+    for (const o of list) {
+        if (!o || typeof o.type !== 'string' || typeof o.name !== 'string')
+            continue;
+        const key = objectKey(o.type, o.name);
+        if (!baselineKeys.has(key)) {
+            outside += 1;
+            continue;
+        }
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        rows.push({ key, callers: o.callers, batch: o.batch, usage: o.usage, changed: o.changed });
+    }
+    return { rows, outside };
+}
+export const EVIDENCE_LINE = (count) => `Evidence for ${count} objects written (callers, batch runs, usage, last change).`;
+export const OUTSIDE_LINE = (count) => `${count === 1 ? '1 object' : `${count} objects`} in the inventory ${count === 1 ? 'is' : 'are'} outside this team project.`;
+/** One sentence for a file that could not be written: its name and the code, never the path (it carries the user name). */
+const cannotWrite = (name, code) => `Could not write ${name} in the discovery folder${code ? ` (${code})` : ''}.`;
+function writeIn(name, write) {
+    try {
+        write();
+    }
+    catch (e) {
+        throw new RegisterError(cannotWrite(name, e?.code ?? ''));
+    }
+}
+/**
+ * The stamp, or `<stamp>-2`, `-3`, … when a discovery of the same second is
+ * already there: an older discovery is history and is never overwritten.
+ */
+function freeStamp(folder, stamp) {
+    const taken = (s) => fs.existsSync(path.join(folder, `estate-${s}.json`)) || fs.existsSync(path.join(folder, `objects-${s}.json`));
+    if (!taken(stamp))
+        return stamp;
+    for (let i = 2;; i += 1)
+        if (!taken(`${stamp}-${i}`))
+            return `${stamp}-${i}`;
+}
+/** The same folder, said two ways: on Windows case does not matter, and a trailing separator never does. */
+export function samePath(a, b) {
+    const norm = (p) => {
+        const r = path.resolve(p).replace(/[\\/]+$/, '');
+        return process.platform === 'win32' ? r.toLowerCase() : r;
+    };
+    return norm(a) === norm(b);
+}
+export async function teamDiscover(args, deps) {
+    const { positional, opts } = flags(args, DISCOVER_FLAGS);
+    for (const name of Object.keys(opts)) {
+        if (!DISCOVER_OPTIONS.includes(name))
+            throw new RegisterError(`Unknown option --${name}.\n${DISCOVER_USAGE}`);
+    }
+    // 1.1.31: no --out → the folder you are in (owner: "why doesn't CSPeach remember all that?").
+    if (positional.length || opts.out === 'true')
+        throw new RegisterError(DISCOVER_USAGE);
+    const maxMinutes = opts['max-minutes'] === undefined ? 30 : Number(opts['max-minutes']);
+    if (!Number.isFinite(maxMinutes) || maxMinutes <= 0)
+        throw new RegisterError(`--max-minutes needs a number of minutes, for example: --max-minutes 30\n${DISCOVER_USAGE}`);
+    const namespaces = !opts.namespaces || opts.namespaces === 'true' || opts.namespaces.trim().toLowerCase() === 'auto'
+        ? 'auto' : list(opts.namespaces).map((s) => s.toUpperCase());
+    const prefixes = opts.prefixes && opts.prefixes !== 'true' ? list(opts.prefixes).map((s) => s.toUpperCase()) : ['Z', 'Y'];
+    const dir = path.resolve(opts.out ?? process.cwd());
+    // A team project folder: its lead only, and that is settled before SAP is reached.
+    const isTeam = fs.existsSync(path.join(dir, TEAM_FILE));
+    const project = isTeam ? readProjectFile(dir) : null;
+    if (project)
+        requireLead(project, deps);
+    if (deps.noSap || !deps.connect)
+        throw new RegisterError('discover needs a SAP connection to read the estate.');
+    const { sql, system } = await deps.connect(opts['sap-alias']);
+    const stop = new AbortController();
+    const off = onInterrupt(deps, () => {
+        if (stop.signal.aborted)
+            return;
+        deps.print('  Stopping. What has been read so far will still be written.');
+        stop.abort();
+    });
+    let result;
+    try {
+        deps.print('Reading the estate from SAP (read only). Ctrl-C keeps what has been read.');
+        result = await discover(sql, {
+            prefixes, namespaces, xref: !opts['no-xref'], jobs: !opts['no-jobs'], maxMinutes,
+            signal: stop.signal, by: whoAmI(deps), ...(system ? { system } : {}),
+            ...(deps.now ? { now: deps.now } : {}),
+            onStep: (step, label) => deps.print(`  Step ${step} of 12: ${label}`),
+        });
+    }
+    finally {
+        off();
+    }
+    const folder = path.join(dir, DISCOVERY_DIR);
+    const stamp = freeStamp(folder, fileStamp(new Date(result.estate.takenAt)));
+    const objectsName = `objects-${stamp}.json`;
+    const estateName = `estate-${stamp}.json`;
+    const objectsText = `${JSON.stringify(result.objects, null, 1)}\n`;
+    // The object list first: an estate file on disk always has its object list beside it.
+    writeIn(objectsName, () => writeWhole(path.join(folder, objectsName), objectsText));
+    writeIn(estateName, () => writeWhole(path.join(folder, estateName), `${JSON.stringify(result.estate, null, 1)}\n`));
+    const summary = estateSummaryOf(result.estate, project ? readBaseline(dir) : undefined);
+    // Said as written only when it was: no summary, no workbook.
+    let workbook = !!summary;
+    let held = false;
+    try {
+        if (summary)
+            writeXlsxFile(path.join(folder, 'estate.xlsx'), estateWorkbook(summary));
+    }
+    catch (e) {
+        const code = e?.code ?? '';
+        if (!HELD.has(code))
+            throw new RegisterError(cannotWrite('estate.xlsx', code));
+        workbook = false;
+        held = true;
+    }
+    if (summary)
+        deps.print(estateLine(summary));
+    deps.print(`  Written in the discovery folder: ${estateName}, ${objectsName}${workbook ? ', estate.xlsx' : ''}`);
+    if (held)
+        deps.print('  ! "estate.xlsx" is open in another program, so it was not updated. Close it and run discover again.');
+    if (!project) {
+        deps.print('Next: open the folder on the team page, or start a team project here: cspeach team start <packages>');
+        return 0;
+    }
+    // The lead's own team project folder: the inventory's evidence for its objects, as one record.
+    const joined = Object.entries(loadState().projects).find(([id, p]) => id === project.projectId && samePath(p.projectDir, dir));
+    if (!joined) {
+        deps.print('  No evidence recorded: this laptop has not joined this team project. Run: cspeach team join <folder>');
+        return 0;
+    }
+    const [projectId, p] = joined;
+    const keys = new Set(readBaseline(dir).map((o) => objectKey(o.type, o.name)));
+    const ev = evidenceRows(result.objects, keys);
+    const res = writeRecord({ ...p, projectId }, 'evidence', ev.rows, { name: whoAmI(deps) }, {
+        dir: path.join(dir, 'writers', p.writerId, 'records'),
+        source: { file: objectsName, sha256: createHash('sha256').update(objectsText).digest('hex') },
+        ...(deps.now ? { now: deps.now() } : {}), ...(deps.rand ? { rand: deps.rand } : {}),
+    });
+    deps.print(`  ${EVIDENCE_LINE(res.written)}`);
+    if (ev.outside)
+        deps.print(`  ${OUTSIDE_LINE(ev.outside)}`);
+    return 0;
+}