@cspeach/cli 1.1.30 → 1.1.32

package/dist/commands/team-rules.js

@@ -0,0 +1,187 @@
+/**
+ * `cspeach team rules …` — the decision rules, read and changed from the
+ * terminal (step 2, Task 10; spec 2026-10-08 §7 D7). `/rules` in a session
+ * (repl/rules-menu.ts) saves through the same `saveRuleEdit`.
+ *
+ *   rules                                  anyone: the numbered table
+ *   rules on|off <id>                      lead
+ *   rules set <id> --min-findings N | --max-findings N | --then <disposition> [--target L] | --target L|none
+ *   rules add --template <name>            lead
+ *   rules remove <id>                      lead
+ *   rules reset                            lead: the file names no rules again
+ *
+ * A save is the whole team project file, then renamed (every other key as it
+ * was), and one plan record in the lead's `plan/` so the change is a line of
+ * History and of the CSV events. Never reachable from a model tool.
+ */
+import path from 'node:path';
+import { readDecisionRules } from '@cspeach/register-core';
+import { RegisterError, readProjectFile, TEAM_FILE } from '../register/store.js';
+import { writeLeadRecord } from '../register/records.js';
+import { writeWhole } from '../register/write-whole.js';
+import { addFromTemplate, removeRule, resetRules, rulesTableLines, setOutcome, setTarget, setThreshold, toggleRule, RULE_TEMPLATES, } from '../register/rules-edit.js';
+import { flags, joinedOrThrow, requireLead, whoAmI } from './team.js';
+import { reasonFrom } from './team-plan.js';
+export const RULES_USAGE = 'Usage: cspeach team rules [on|off <id> | set <id> --min-findings N | --max-findings N | --then keep|fix|rebuild|retire-candidate [--target A-D] '
+    + '| --target A-D|none | add --template <name> | remove <id> | reset] [--reason "<why>"]';
+const SET_USAGE = 'Usage: cspeach team rules set <id> --min-findings N | --max-findings N | --then keep|fix|rebuild|retire-candidate [--target A-D] | --target A-D|none';
+const SET_OPTIONS = ['min-findings', 'max-findings', 'then', 'target', 'reason'];
+/** The one line someone who is not the lead gets for any change. */
+export const rulesRefusal = (lead) => `Only the lead (${lead}) changes the rules. You can view them: cspeach team rules`;
+/** The joined team project and its rules as the next read will see them. */
+export function rulesNow(projectDir) {
+    const project = readProjectFile(projectDir);
+    return { project, ...readDecisionRules(project) };
+}
+/** Lead only, in the rules' own words; `requireLead` decides who the lead is. */
+export function requireRulesLead(project, deps) {
+    try {
+        requireLead(project, deps);
+    }
+    catch (e) {
+        if (e instanceof RegisterError)
+            throw new RegisterError(rulesRefusal(project.lead.name));
+        throw e;
+    }
+}
+/** An edit over rules the file holds but this build cannot read would quietly throw them away; only reset may go ahead. */
+export function refuseUnreadable(warning, edit) {
+    if (!warning || edit === 'reset')
+        return;
+    throw new RegisterError(`${warning.replace(/, so the default rules are used\.$/, '.')} Fix the file, or start again from the defaults: cspeach team rules reset`);
+}
+export const stampFor = (deps) => ({ by: whoAmI(deps), at: (deps.now?.() ?? new Date()).toISOString() });
+/** The rules changed between the card and the save (a sync, a second terminal): nothing is written. */
+export const RULES_CHANGED_LINE = 'The rules changed since you opened them. Open /rules again.';
+/** Said before the first save of a project whose file names no rules yet (review round 1). */
+export const DEFAULTS_PINNED_LINE = "Saving writes all rules into this project's file; later CSPeach default changes will not apply here until you Restore defaults.";
+/**
+ * Save one edit: the team project file whole, then renamed — `decisionRules`
+ * replaced, or removed on reset, every other key as it was — then the plan
+ * record that puts it in History. Returns the lines to print.
+ *
+ * The rules in the file must still be the ones the edit was made from: if a
+ * sync or a second terminal changed them meanwhile, nothing is written. A
+ * History record that cannot be written after the file was saved is said, not
+ * hidden; the file keeps the change (it is what the person confirmed).
+ */
+export function saveRuleEdit(projectDir, edit, deps, reason = '') {
+    const joined = joinedOrThrow();
+    const project = readProjectFile(projectDir);
+    requireRulesLead(project, deps);
+    if (edit.basis && JSON.stringify(readDecisionRules(project).rules) !== JSON.stringify(edit.basis)) {
+        throw new RegisterError(RULES_CHANGED_LINE);
+    }
+    const next = { ...project };
+    if (edit.rules === null)
+        delete next.decisionRules;
+    else
+        next.decisionRules = edit.rules;
+    writeWhole(path.join(projectDir, TEAM_FILE), `${JSON.stringify(next, null, 2)}\n`);
+    const lines = [`✓ Saved. ${edit.summary}`];
+    try {
+        writeLeadRecord(path.join(projectDir, 'plan'), project.projectId, 'plan', {
+            action: 'rules',
+            rules: { change: edit.change, ...(edit.id ? { id: edit.id } : {}), summary: edit.summary, before: edit.before, after: edit.after },
+            ...(reason ? { reason } : {}),
+        }, [], { name: whoAmI(deps), writer: joined.writerId }, {
+            ...(deps.now ? { now: deps.now() } : {}), ...(deps.rand ? { rand: deps.rand } : {}),
+        });
+    }
+    catch (e) {
+        const why = (e instanceof Error ? e.message : String(e)).split('\n')[0].replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, 200);
+        lines.push(`! Saved, but no History line was written: ${why}`);
+    }
+    return lines;
+}
+function onlyOptions(opts, known, usage) {
+    for (const name of Object.keys(opts))
+        if (!known.includes(name))
+            throw new RegisterError(`Unknown option --${name}.\n${usage}`);
+}
+/** A flag that needs a value got none: say which, never read "true" as the value. */
+function valueOf(opts, name) {
+    const v = opts[name];
+    return v === 'true' ? '' : v;
+}
+export function rulesCommand(args, deps) {
+    const { positional, opts } = flags(args);
+    const [verb, id, ...extra] = positional;
+    const joined = joinedOrThrow();
+    const now = rulesNow(joined.projectDir);
+    if (!verb || verb === 'list' || verb === 'show') {
+        onlyOptions(opts, [], RULES_USAGE);
+        for (const line of rulesTableLines(now.rules, now.from, now.warning))
+            deps.print(line);
+        deps.print(`Change them in a session with /rules, or: cspeach team rules on|off|set|add|remove|reset   (lead: ${now.project.lead.name})`);
+        return 0;
+    }
+    if (!['on', 'off', 'set', 'add', 'remove', 'reset'].includes(verb))
+        throw new RegisterError(RULES_USAGE);
+    requireRulesLead(now.project, deps);
+    const reason = reasonFrom(opts, false);
+    const stamp = stampFor(deps);
+    let edit;
+    switch (verb) {
+        case 'on':
+        case 'off':
+        case 'remove': {
+            onlyOptions(opts, ['reason'], RULES_USAGE);
+            if (!id || extra.length)
+                throw new RegisterError(RULES_USAGE);
+            refuseUnreadable(now.warning, verb === 'remove' ? 'remove' : verb);
+            edit = verb === 'remove' ? removeRule(now.rules, id) : toggleRule(now.rules, id, verb === 'on', stamp);
+            break;
+        }
+        case 'set': {
+            onlyOptions(opts, SET_OPTIONS, SET_USAGE);
+            if (!id || extra.length)
+                throw new RegisterError(SET_USAGE);
+            refuseUnreadable(now.warning, 'set');
+            const min = valueOf(opts, 'min-findings');
+            const max = valueOf(opts, 'max-findings');
+            const then = valueOf(opts, 'then');
+            const target = valueOf(opts, 'target');
+            const counts = min !== undefined || max !== undefined;
+            if (!counts && then === undefined && target === undefined)
+                throw new RegisterError(SET_USAGE);
+            if (counts && (then !== undefined || target !== undefined))
+                throw new RegisterError(`One change at a time: a threshold, or the outcome.\n${SET_USAGE}`);
+            if (counts) {
+                edit = setThreshold(now.rules, id, { ...(min !== undefined ? { minFindings: min } : {}), ...(max !== undefined ? { maxFindings: max } : {}) }, stamp);
+            }
+            else if (then !== undefined) {
+                const t = target === undefined ? undefined : target.toLowerCase() === 'none' ? null : target.toUpperCase();
+                edit = setOutcome(now.rules, id, then.toLowerCase(), stamp, t);
+            }
+            else {
+                edit = setTarget(now.rules, id, target.toLowerCase() === 'none' ? null : target.toUpperCase(), stamp);
+            }
+            break;
+        }
+        case 'add': {
+            onlyOptions(opts, ['template', 'reason'], RULES_USAGE);
+            const template = valueOf(opts, 'template');
+            if (id || !template)
+                throw new RegisterError(`Usage: cspeach team rules add --template <name>   Templates: ${Object.keys(RULE_TEMPLATES).join(', ')}`);
+            refuseUnreadable(now.warning, 'add');
+            edit = addFromTemplate(now.rules, template, stamp);
+            break;
+        }
+        default: {
+            onlyOptions(opts, ['reason'], RULES_USAGE);
+            if (id)
+                throw new RegisterError(RULES_USAGE);
+            if (now.from === 'default' && !now.warning) {
+                deps.print('The rules are the defaults already. Nothing was written.');
+                return 0;
+            }
+            edit = resetRules(now.rules);
+        }
+    }
+    for (const line of saveRuleEdit(joined.projectDir, edit, deps, reason))
+        deps.print(line);
+    if (now.from === 'default' && edit.rules !== null)
+        deps.print(`  ${DEFAULTS_PINNED_LINE}`);
+    return 0;
+}