config-audit/scanners/campaign-write-cli.mjs

#!/usr/bin/env node

/**
 * campaign-write-cli — the human-approved WRITE half of the durable campaign ledger
 * (v5.7 Fase 2, Block 3c).
 *
 * Sibling of the read-only `campaign-cli`: where that one only reports, this one mutates.
 * Every mutation is routed through the pure, invariant-enforcing lib transforms
 * (`createLedger`/`addRepo`/`setRepoStatus`) + `saveLedger` — so path normalization/dedup,
 * idempotent add, the status-lifecycle guard, and the `updatedDate` bump are never
 * re-implemented by hand. The `/config-audit campaign` command is a thin opus orchestrator:
 * it reports (via campaign-cli), proposes a change, and only on explicit human approval
 * invokes a single subcommand here (Verifiseringsplikt). It NEVER auto-writes.
 *
 * Determinism mirrors the lib + the knowledge-refresh CLI: `--reference-date` is the only
 * place the clock is read (defaulting to today), and it is passed to the transforms as the
 * injected `now`, so the persisted stamps are fully testable.
 *
 * Naming: `-cli` suffix → NOT an orchestrated scanner (the scan-orchestrator only loads
 * scanner modules), so the scanner count is unchanged and the snapshot suite stays
 * byte-stable.
 *
 * Usage:
 *   node campaign-write-cli.mjs init        [--ledger-file <p>] [--reference-date <YYYY-MM-DD>]
 *   node campaign-write-cli.mjs add <path>... [--name <n>] [--ledger-file <p>] [--reference-date <d>]
 *   node campaign-write-cli.mjs set-status <path> <status>
 *                                            [--findings '<json>'] [--session <id>]
 *                                            [--ledger-file <p>] [--reference-date <d>]
 *   node campaign-write-cli.mjs refresh-tokens [--ledger-file <p>] [--reference-date <d>]
 *   (all accept [--output-file <p>] to write the result payload to a file instead of stdout)
 *
 * `refresh-tokens` is the live cross-repo token sweep (v5.9 B2b): for every tracked
 * repo it runs the manifest's always-loaded accounting (readActiveConfig → buildManifest)
 * and splits each source into the shared global layer vs the repo's per-repo delta
 * (splitManifestByOwnership). The shared layer is HOME-derived and identical across
 * repos, so it is captured ONCE (from the first successful read) and stored at the
 * ledger root; each repo gets only its delta. This is the IO half of the machine-wide
 * token roll-up whose pure data model shipped in B2a.
 *
 * Exit codes: 0 = write performed (or no repos to sweep, a benign no-op), 1 = advisory
 * no-op (init when already initialized), 3 = error (unknown subcommand, bad args,
 * invalid status, untracked repo, no/corrupt ledger).
 */

import { resolve } from 'node:path';
import { stat } from 'node:fs/promises';
import { writeOutputFile } from './lib/write-output.mjs';
import {
  createLedger,
  addRepo,
  setRepoStatus,
  setSharedGlobal,
  setRepoTokens,
  rollUp,
  loadLedger,
  saveLedger,
  defaultLedgerPath,
} from './lib/campaign-ledger.mjs';
import { readActiveConfig } from './lib/active-config-reader.mjs';
import { buildManifest, splitManifestByOwnership } from './manifest.mjs';
import { findArgError } from './lib/cli-args.mjs';

const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;

/**
 * Usage error. Throws rather than calling process.exit(): exit() discards
 * unflushed stdout when stdout is a pipe. The top-level catch prints the same
 * `Error: ` text and sets the same exit code 3, so callers see no difference.
 */
class CliUsageError extends Error {}

function fail(message) {
  throw new CliUsageError(message);
}

/** Flag surface, measured 2026-08-09. The gate runs BEFORE the loop below, so the
 * loop no longer needs to re-check that a value followed its flag. */
const ARG_SPEC = {
  value: ['--ledger-file', '--reference-date', '--output-file', '--name', '--findings', '--session'],
};

/** Parse argv into a subcommand, positional args, and the flag map. */
function parseArgs(argv) {
  const argError = findArgError(argv, ARG_SPEC);
  if (argError) fail(argError);
  const positionals = [];
  const flags = { ledgerFile: null, referenceDate: null, outputFile: null, name: null, findings: null, session: null };
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    if (a === '--ledger-file') flags.ledgerFile = argv[++i];
    else if (a === '--reference-date') flags.referenceDate = argv[++i];
    else if (a === '--output-file') flags.outputFile = argv[++i];
    else if (a === '--name') flags.name = argv[++i];
    else if (a === '--findings') flags.findings = argv[++i];
    else if (a === '--session') flags.session = argv[++i];
    else positionals.push(a);
  }
  return { subcommand: positionals[0], rest: positionals.slice(1), flags };
}

/**
 * Can this path actually be read as a repo right now?
 *
 * `readActiveConfig` resolves any string and its sub-readers all tolerate ENOENT, so a repo
 * that does not exist yields an EMPTY config instead of an error. Without this check the
 * sweep records a phantom repo as successfully swept with 0 tokens, and the machine-wide
 * bill claims coverage it does not have. A missing path is reported, never rejected — an
 * unmounted volume is a legitimate reason for a tracked repo to be absent today.
 */
async function isReadableRepoDir(path) {
  try {
    return (await stat(path)).isDirectory();
  } catch {
    return false;
  }
}

/** Load an existing ledger, treating a parse error as a hard failure (never clobber corrupt data). */
async function loadOrFail(path) {
  try {
    return await loadLedger(path); // null on ENOENT (no ledger yet)
  } catch (err) {
    fail(`could not read ledger at ${path}: ${err.message}`);
  }
}

async function emit(payload, outputFile, exitCode) {
  const json = JSON.stringify(payload, null, 2);
  if (outputFile) await writeOutputFile(outputFile, json, 'utf-8');
  else process.stdout.write(json + '\n');
  process.exitCode = exitCode;
}

async function main() {
  const { subcommand, rest, flags } = parseArgs(process.argv.slice(2));

  if (!subcommand) fail('a subcommand is required: init | add | set-status | refresh-tokens');

  const ledgerPath = resolve(flags.ledgerFile || defaultLedgerPath());
  if (flags.referenceDate && !DATE_RE.test(flags.referenceDate)) fail('--reference-date must be YYYY-MM-DD');
  // The clock is read here ONLY — the transforms take this injected `now` and stay pure.
  const now = flags.referenceDate || new Date().toISOString().slice(0, 10);

  if (subcommand === 'init') {
    const existing = await loadOrFail(ledgerPath);
    if (existing !== null) {
      // Advisory no-op: never wipe an existing campaign.
      return emit(
        { status: 'ok', action: 'init', written: false, alreadyInitialized: true, ledgerPath },
        flags.outputFile,
        1,
      );
    }
    const ledger = createLedger({ now });
    await saveLedger(ledgerPath, ledger);
    return emit(
      {
        status: 'ok', action: 'init', written: true, alreadyInitialized: false, ledgerPath,
        schemaVersion: ledger.schemaVersion, createdDate: ledger.createdDate, updatedDate: ledger.updatedDate,
        repos: ledger.repos, rollUp: rollUp(ledger),
      },
      flags.outputFile,
      0,
    );
  }

  if (subcommand === 'add') {
    const paths = rest;
    if (paths.length === 0) fail('add requires at least one repo path');
    const loaded = await loadOrFail(ledgerPath);
    const autoInitialized = loaded === null;
    let ledger = loaded === null ? createLedger({ now }) : loaded;

    const added = [];
    const addedUnverified = [];
    const skipped = [];
    for (const p of paths) {
      const resolved = resolve(p);
      const present = ledger.repos.some((r) => r.path === resolved);
      // --name applies only to a lone path; multi-add lets the lib derive each basename.
      const name = paths.length === 1 ? flags.name || undefined : undefined;
      ledger = addRepo(ledger, { path: p, name }, { now });
      if (present) skipped.push(resolved);
      else if (await isReadableRepoDir(resolved)) added.push(resolved);
      // Tracked either way, but never silently vouched for: the command reports these
      // separately so a typo does not become a permanent phantom row in the backlog.
      else addedUnverified.push(resolved);
    }
    await saveLedger(ledgerPath, ledger);
    return emit(
      {
        status: 'ok', action: 'add', written: true, autoInitialized, ledgerPath,
        added, addedUnverified, skipped, repos: ledger.repos, rollUp: rollUp(ledger),
      },
      flags.outputFile,
      0,
    );
  }

  if (subcommand === 'set-status') {
    const [path, status] = rest;
    if (!path || !status) fail('set-status requires <path> <status>');
    const ledger = await loadOrFail(ledgerPath);
    if (ledger === null) fail(`no ledger at ${ledgerPath} — run "init" or "add" first`);

    let findingsBySeverity;
    if (flags.findings !== null) {
      try {
        findingsBySeverity = JSON.parse(flags.findings);
      } catch (err) {
        fail(`--findings must be valid JSON: ${err.message}`);
      }
    }
    const opts = { now };
    if (findingsBySeverity !== undefined) opts.findingsBySeverity = findingsBySeverity;
    if (flags.session !== null) opts.sessionId = flags.session;

    let next;
    try {
      next = setRepoStatus(ledger, path, status, opts);
    } catch (err) {
      // RangeError (bad status) or Error (untracked repo) → caller error.
      fail(err.message);
    }
    await saveLedger(ledgerPath, next);
    const resolved = resolve(path);
    return emit(
      {
        status: 'ok', action: 'set-status', written: true, ledgerPath,
        repo: next.repos.find((r) => r.path === resolved), repos: next.repos, rollUp: rollUp(next),
      },
      flags.outputFile,
      0,
    );
  }

  if (subcommand === 'refresh-tokens') {
    const ledger0 = await loadOrFail(ledgerPath);
    if (ledger0 === null) fail(`no ledger at ${ledgerPath} — run "init" or "add" first`);

    let ledger = ledger0;
    const swept = [];
    const skipped = [];
    // The shared global layer is HOME-derived and identical across every repo, so it
    // is captured ONCE (from the first repo that reads cleanly) and stored at the
    // ledger root — the structural guard against the historic shared-layer double-count.
    let sharedSummary = null;

    for (const repo of ledger0.repos) {
      // Check readability FIRST: readActiveConfig returns an empty config for a path that
      // does not exist rather than throwing, so the catch below would never see it and the
      // repo would be recorded as swept with a 0-token delta — a bill that looks complete.
      if (!(await isReadableRepoDir(repo.path))) {
        skipped.push({ path: repo.path, reason: 'repo path is not readable (does not exist or is not a directory)' });
        continue;
      }
      let split;
      try {
        const activeConfig = await readActiveConfig(repo.path, { verbose: false });
        const { sources } = buildManifest(activeConfig);
        split = splitManifestByOwnership(sources);
      } catch (err) {
        skipped.push({ path: repo.path, reason: err.message });
        continue;
      }
      if (sharedSummary === null) sharedSummary = split.shared;
      ledger = setRepoTokens(ledger, repo.path, split.delta, { now });
      swept.push(repo.path);
    }

    if (sharedSummary !== null) ledger = setSharedGlobal(ledger, sharedSummary, { now });

    const written = swept.length > 0;
    if (written) await saveLedger(ledgerPath, ledger);

    return emit(
      {
        status: 'ok', action: 'refresh-tokens', written, ledgerPath,
        swept, skipped, sharedGlobal: ledger.sharedGlobal ?? null, rollUp: rollUp(ledger),
      },
      flags.outputFile,
      0,
    );
  }

  fail(`unknown subcommand "${subcommand}" — expected init | add | set-status | refresh-tokens`);
}

const isDirectRun =
  process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
if (isDirectRun) {
  main().catch((err) => {
    const prefix = err instanceof CliUsageError ? 'Error' : 'Fatal';
    process.stderr.write(`${prefix}: ${err.message}\n`);
    process.exitCode = 3;
  });
}