@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/commands/status.js

@@ -1,416 +1,47 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { Command } from 'commander';
-import { readBuildBaseline } from '../core/build-baseline.js';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { assertEngineExists } from '../core/engine-precondition.js';
-import { formatEngineSessionLockStatus, readEngineSessionLockStatus, } from '../core/engine-session-lock.js';
-import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
-import { listUntrackedFilesInDirs, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
-import { renderOwnershipTable } from '../core/ownership-table.js';
-import { readProcessCpuSeconds } from '../core/process-cpu-time.js';
-import { classifyFiles } from '../core/status-classify.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
-import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
-import { emitMachineError } from '../utils/machine-output.js';
-import { policyNeedsOwnership, resolveStatusCheckPolicy, runStatusCheck, } from './status-check.js';
-import { renderJsonStatus, renderJsonSummaryStatus } from './status-json.js';
-import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
-import { buildOwnershipJsonBlock, summarizeOwnership } from './status-ownership.js';
-import { collectScopedOwnershipRows, ownershipConflictPaths, resolveStatusScope, scopeClassified, } from './status-scope.js';
-/**
- * Renders raw worktree status as machine-parseable porcelain-style output.
- * Each line is: STATUS<tab>FILE
- */
-function renderRawStatus(files) {
-    for (const { status, file } of files) {
-        process.stdout.write(`${status.trim()}\t${file}\n`);
-    }
-}
-// Resolved lazily at first use (shared with core/git-status): this module
-// is imported by the command manifest for every command, so a
-// module-load-time parse printed the status-specific env warning during
-// `fireforge build` etc.
-let maxUntrackedFilesPerDir;
-function getMaxUntrackedFilesPerDir() {
-    maxUntrackedFilesPerDir ??= resolveMaxUntrackedFilesPerDir();
-    return maxUntrackedFilesPerDir;
-}
-function renderTruncationBanner(truncations) {
-    if (truncations.length === 0)
-        return;
-    const hidden = truncations.reduce((sum, rec) => sum + (rec.total - rec.shown), 0);
-    const dirList = truncations.map((r) => `${r.dir} (${r.total - r.shown} hidden)`).join(', ');
-    warn(`⚠ Status output is truncated: ${hidden.toLocaleString()} untracked file(s) across ${truncations.length} director(y/ies) are not shown. ` +
-        `Truncated: ${dirList}. ` +
-        `Add a .gitignore entry or clean the directory before exporting, otherwise the export will omit these files.`);
-}
-async function expandDirectoryEntries(files, engineDir) {
-    const expanded = [];
-    const truncations = [];
-    const isCollapsedUntracked = (entry) => entry.file.endsWith('/') && entry.status.includes('?');
-    const untrackedByDir = await listUntrackedFilesInDirs(engineDir, files.filter(isCollapsedUntracked).map((entry) => entry.file));
-    for (const entry of files) {
-        if (isCollapsedUntracked(entry)) {
-            const individualFiles = untrackedByDir.get(entry.file) ?? [];
-            const cap = getMaxUntrackedFilesPerDir();
-            if (individualFiles.length > cap) {
-                // Recorded once here, reported once by renderTruncationBanner. The
-                // previous per-directory warn duplicated the banner's content.
-                truncations.push({
-                    dir: entry.file,
-                    total: individualFiles.length,
-                    shown: cap,
-                });
+import { defineCommand, lockOptions, lockWaitMs, opt } from '../cli/command.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { status as readStatus, withOwnedRead } from '../mode/index.js';
+import { loadProject } from '../project/index.js';
+export const status = defineCommand({
+    name: 'status',
+    summary: 'Show the owned changes and anything unaccounted for',
+    description: 'Patch mode: edits no patch holds, queue files not applied, a paused import or rebase. ' +
+        'Source mode: undeclared edits of upstream files, stale or orphaned override records. ' +
+        '--groups lists the groups of the owned paths by ID: the name patchLint.waivers, ' +
+        'patchPolicy.scopeRules and patchPolicy.reservedRanges select a group by.',
+    group: 'Daily',
+    options: {
+        check: opt.flag('Exit nonzero when anything is unaccounted for'),
+        groups: opt.flag('List every group with its ID, kind and number of paths'),
+        ...lockOptions,
+    },
+    json: true,
+    run: async (ctx, _args, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const report = await withOwnedRead(project, { command: 'status', waitMs: lockWaitMs(opts.waitLock) }, () => readStatus(project));
+        const furnace = report.groups.filter((group) => group.kind === 'furnace').length;
+        ctx.out.line(`${report.owned.length} owned path(s) in ${report.groups.length - furnace} group(s)` +
+            (furnace === 0 ? '' : `, and ${furnace} Furnace component(s)`));
+        if (opts.groups) {
+            for (const group of report.groups) {
+                ctx.out.line(`  ${group.id}  ${group.kind}  ${group.paths} path(s)`);
             }
-            const limited = individualFiles.slice(0, cap);
-            for (const f of limited) {
-                expanded.push({ status: '??', file: f });
-            }
-        }
-        else {
-            expanded.push(entry);
-        }
-    }
-    return { entries: expanded, truncations };
-}
-/**
- * Strips entries whose path matches the atomic-temp-file shape
- * FireForge's own `writeText` produces (see
- * {@link import('../utils/fs.js').FIREFORGE_TMP_PATH_PATTERN}). Those
- * files only exist for the duration of a write + rename and should
- * never appear in `status` output. Filtering them here keeps every
- * status mode (default, raw, unmanaged, ownership, json) symmetric so
- * the operator never sees a `.mozconfig.fireforge-tmp-<pid>-<uuid>`
- * entry mid-write. Files named for unrelated reasons (e.g. a user's
- * `.bashrc.fireforge-tmp-backup` without the PID+UUID tail) do not
- * match the pattern and pass through unfiltered.
- */
-function filterFireForgeTempFiles(files) {
-    return files.filter((entry) => !FIREFORGE_TMP_PATH_PATTERN.test(entry.file));
-}
-/**
- * Renders classified file status as machine-readable JSON to stdout.
- */
-async function classifyStatusFiles(files, paths, projectRoot, binaryName) {
-    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-    return classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
-}
-/**
- * The one worktree scan every classifying mode shares: porcelain status,
- * collapsed-directory expansion, atomic-temp-file filtering, and the
- * truncation banner. A non-git engine degrades to an empty list for
- * `--ownership`, which is why the git probe is a parameter rather than a
- * hard guard.
- *
- * @param engineDir - Path to the engine directory
- * @param requireGitRepository - When false, a non-git engine yields `[]`
- *   instead of being probed
- */
-async function scanEngineStatusFiles(engineDir, requireGitRepository) {
-    if (!requireGitRepository && !(await isGitRepository(engineDir))) {
-        return [];
-    }
-    const { entries, truncations } = await expandDirectoryEntries(await getStatusWithCodes(engineDir), engineDir);
-    renderTruncationBanner(truncations);
-    return filterFireForgeTempFiles(entries);
-}
-/**
- * Emits the `--json` payload (full or `--summary`) and applies the `--check`
- * policy, which stays the only exit driver on this path.
- *
- * `--include-ownership` is a modifier rather than a mode: it appends an
- * ownership block without touching exit semantics. Ownership conflicts
- * fail this path only when the policy names `ownership-conflict` (or
- * leaves it unnamed under `--fail-on-unknown`).
- *
- * @param classified - Classified worktree entries, unscoped
- * @param files - The same entries pre-classification, for ownership rows
- * @param paths - Resolved project paths
- * @param options - Status display options
- * @param checkPolicy - Resolved `--check`/`--fail-on` policy
- * @param scope - The `--patches` scope, when given
- */
-async function renderJsonMode(classified, files, paths, options, checkPolicy, scope) {
-    const rows = options.includeOwnership === true || policyNeedsOwnership(checkPolicy)
-        ? await collectScopedOwnershipRows(paths.patches, files, classified, scope)
-        : [];
-    const context = {
-        policy: checkPolicy,
-        ownershipConflicts: ownershipConflictPaths(rows),
-        ownership: options.includeOwnership === true ? buildOwnershipJsonBlock(rows) : undefined,
-        scope,
-    };
-    const scoped = scopeClassified(classified, scope);
-    if (options.summary === true) {
-        renderJsonSummaryStatus(scoped, context);
-    }
-    else {
-        renderJsonStatus(scoped, context);
-    }
-    runStatusCheck(scoped, checkPolicy, context.ownershipConflicts);
-}
-/**
- * Applies the `--check` policy to the human default view. Builds the
- * ownership rows only when the policy can fail on `ownership-conflict`,
- * which it can on a clean tree too (two patches claiming one path need no
- * worktree change).
- */
-async function runHumanStatusCheck(classified, files, paths, checkPolicy, scope) {
-    const conflicts = policyNeedsOwnership(checkPolicy)
-        ? ownershipConflictPaths(await collectScopedOwnershipRows(paths.patches, files, classified, scope))
-        : [];
-    runStatusCheck(scopeClassified(classified, scope), checkPolicy, conflicts);
-}
-/**
- * Detects the "unborn HEAD" aftermath of an interrupted `fireforge download`:
- * git init succeeded but the initial Firefox source commit was never
- * created, so every file in engine/ reads as untracked. On a ~600 MB
- * Firefox tree this would flood the output with hundreds of thousands of
- * entries and a truncation warning, which is technically correct but not
- * actionable. Throws a `GeneralError` with a single recovery banner
- * pointing at `fireforge download --force`. `raw` / `json` modes skip the
- * banner so their consumers see the structural failure in error form
- * only.
- */
-async function assertEngineHasBaselineCommit(engineDir, options) {
-    try {
-        await getHead(engineDir);
-    }
-    catch (err) {
-        if (!isMissingHeadError(err))
-            throw err;
-        const guidance = 'Engine repository has no baseline commit yet — a previous "fireforge download" was interrupted before git created the initial Firefox source commit. Re-run "fireforge download --force" to recreate the baseline repository cleanly.';
-        if (!options.raw && !options.json) {
-            warn(guidance);
-            outro('Engine baseline missing — re-run download --force');
-        }
-        if (options.json) {
-            // Mirror `--json`'s contract: errors must be machine-parseable too.
-            // Without this branch the human guidance above is suppressed but the
-            // throw still falls through to the styled error renderer in
-            // withErrorHandling, leaving JSON consumers with non-JSON output on
-            // exactly the failure mode they care about catching.
-            process.stdout.write(JSON.stringify({ schemaVersion: 1, error: guidance, code: 'engine-baseline-missing' }) +
-                '\n');
-        }
-        throw new GeneralError(guidance);
-    }
-}
-/**
- * Runs the status command to show modified files.
- * @param projectRoot - Root directory of the project
- * @param options - Status display options
- */
-export async function statusCommand(projectRoot, options = {}) {
-    const previousMachineOutputMode = isMachineOutputMode();
-    const shouldUseMachineOutput = options.json === true || options.raw === true;
-    // Machine modes own stdout exclusively: every diagnostic (clack warnings,
-    // withErrorHandling's styled errors, spinner steps) routes to stderr so
-    // `status --json | jq .` and `--raw` pipes always parse.
-    if (shouldUseMachineOutput) {
-        setMachineOutputMode(true);
-    }
-    // On a throw, machine mode stays engaged: withErrorHandling
-    // routes the styled error to stderr while the mode is on and resets it
-    // centrally. A mid-throw restore here would put the refusal on stdout
-    // after the JSON payload.
-    await runStatusCommandBody(projectRoot, options);
-    if (isMachineOutputMode() !== previousMachineOutputMode) {
-        setMachineOutputMode(previousMachineOutputMode);
-    }
-}
-/**
- * Refuses flag combinations no view can honour, before any output: one
- * mode at most, and the JSON-only and scope modifiers only where they mean
- * something.
- */
-function assertStatusFlagCombination(options) {
-    const modeCount = [
-        options.raw,
-        options.unmanaged,
-        options.ownership,
-        options.testCoverage,
-        options.json,
-        options.lock,
-    ].filter((v) => v === true).length;
-    if (modeCount > 1) {
-        throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, --lock, and --json together. Pick at most one.');
-    }
-    // --summary elides the files[] payload for gate consumers. It only
-    // makes sense on the JSON shape.
-    if (options.summary === true && options.json !== true) {
-        throw new InvalidArgumentError('--summary requires --json.', '--summary');
-    }
-    // --include-ownership adds a block to the JSON payload. It is meaningless
-    // on the human views, where --ownership is the mode that renders the
-    // table.
-    if (options.includeOwnership === true && options.json !== true) {
-        throw new InvalidArgumentError('--include-ownership requires --json. Use --ownership for the human table.', '--include-ownership');
-    }
-    // --patches scopes the classifying views and the ownership table only.
-    if (options.patches !== undefined &&
-        (options.raw === true ||
-            options.unmanaged === true ||
-            options.testCoverage === true ||
-            options.lock === true)) {
-        throw new InvalidArgumentError('--patches cannot be combined with --raw, --unmanaged, --test-coverage, or --lock.', '--patches');
-    }
-}
-/** The status body proper. The machine-mode lifecycle lives in {@link statusCommand}. */
-async function runStatusCommandBody(projectRoot, options) {
-    assertStatusFlagCombination(options);
-    // --check / --fail-on enforcement policy. Applies only
-    // where classification runs (the default view and --json).
-    const checkPolicy = resolveStatusCheckPolicy(options);
-    if (!options.raw && !options.json) {
-        intro('FireForge Status');
-    }
-    // Lock visibility. Placed before every engine/git guard: the
-    // whole point is to answer "who is holding this?" on a checkout that a
-    // concurrent command is busy with, and that answer must not depend on
-    // engine/ being readable.
-    if (options.lock === true) {
-        const snapshot = await readEngineSessionLockStatus(projectRoot);
-        const holderCpuSeconds = snapshot.holder?.alive === true
-            ? await readProcessCpuSeconds(snapshot.holder.pid)
-            : undefined;
-        for (const line of formatEngineSessionLockStatus(snapshot, holderCpuSeconds)) {
-            info(line);
-        }
-        outro('Lock status');
-        return;
-    }
-    // Test-coverage mode needs only the project root (the baseline lives
-    // in .fireforge/), so it short-circuits before any engine/git guards.
-    if (options.testCoverage) {
-        renderTestCoverageStatus(await readBuildBaseline(projectRoot));
-        return;
-    }
-    const paths = getProjectPaths(projectRoot);
-    const config = await loadConfig(projectRoot);
-    const scope = await resolveStatusScope(paths.patches, options.patches);
-    // Shared envelope: see src/utils/machine-output.ts and
-    // docs/machine-output.md. `status` was the only command that had one.
-    // Ownership mode is a flat file→patch table. Sources are the manifest's
-    // filesAffected, any worktree drift, and the cross-patch
-    // duplicate-new-file-creation map produced by walking each patch body. The
-    // last is what keeps `status --ownership` aligned with `fireforge verify`
-    // (see buildOwnershipTable's header). Runs before the default classify
-    // path so it can short-circuit without computing patch-backed state.
-    if (options.ownership) {
-        // Rung 1 only. See the note below on why this branch does not take the
-        // full assertEngineGitReady ladder.
-        await assertEngineExists(paths.engine);
-        // The same scan and the same classification pass as every other mode.
-        // This branch keeps its historical guard shape on purpose:
-        // no baseline-commit assertion, and a non-git engine degrades to an
-        // empty table rather than the recovery banner.
-        const rawFilesOwnership = await scanEngineStatusFiles(paths.engine, false);
-        const rows = await collectScopedOwnershipRows(paths.patches, rawFilesOwnership, await classifyStatusFiles(rawFilesOwnership, paths, projectRoot, config.binaryName), scope);
-        renderOwnershipTable(rows);
-        const { managed, unmanaged, conflicts } = summarizeOwnership(rows);
-        const parts = [`${managed} managed`];
-        if (conflicts > 0)
-            parts.push(`${conflicts} conflict${conflicts === 1 ? '' : 's'}`);
-        if (unmanaged > 0)
-            parts.push(`${unmanaged} unmanaged`);
-        outro(parts.join(', '));
-        if (conflicts > 0) {
-            throw new GeneralError(`${conflicts} path(s) are claimed by more than one patch. ` +
-                'Run "fireforge verify" for full details, then use "re-export --files" or ' +
-                '"patch delete" to resolve.');
-        }
-        return;
-    }
-    // Not routed through assertEngineExists: the --json contract requires a
-    // machine-readable payload on stdout before the throw, so scripted
-    // consumers get a parseable refusal instead of a bare non-zero exit. The
-    // message is kept identical to the helper's on purpose.
-    if (!(await pathExists(paths.engine))) {
-        if (options.json) {
-            emitMachineError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
-        }
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
-    // Check if it's a git repository
-    if (!(await isGitRepository(paths.engine))) {
-        if (options.json) {
-            emitMachineError('engine-not-git', 'Engine directory is not a git repository. Run "fireforge download" to initialize.');
         }
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
-    await assertEngineHasBaselineCommit(paths.engine, options);
-    const files = await scanEngineStatusFiles(paths.engine, true);
-    // `--json` callers expect machine-parseable output on every invocation,
-    // including the clean-tree case. Falling through to the human branch below
-    // silently ignores `--json` and breaks scripts that pipe the output
-    // through a JSON parser precisely when there is nothing to report. Emit
-    // `[]` here and return before the human fallback.
-    if (options.json) {
-        const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
-        await renderJsonMode(classified, files, paths, options, checkPolicy, scope);
-        return;
-    }
-    // `--raw` consumers parse the native `git status --porcelain` output
-    // directly. On a clean tree the raw mode should produce nothing on
-    // stdout: the human "Working tree clean" banner would contaminate the
-    // pipe. Short-circuit before the human clean-tree branch below.
-    if (options.raw && files.length === 0) {
-        return;
-    }
-    if (files.length === 0) {
-        info('No modified files');
-        outro('Working tree clean');
-        await runHumanStatusCheck([], files, paths, checkPolicy, scope);
-        return;
-    }
-    // Raw mode: existing behavior
-    if (options.raw) {
-        renderRawStatus(files);
-        return;
-    }
-    // Patch-aware classification. The full scan is classified (claims need
-    // every file) and the buckets show only what the scope covers.
-    const allClassified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
-    const classified = scopeClassified(allClassified, scope);
-    const buckets = {
-        conflict: classified.filter((f) => f.classification === 'conflict'),
-        unmanaged: classified.filter((f) => f.classification === 'unmanaged'),
-        patchOwnedDrift: classified.filter((f) => f.classification === 'patch-owned-drift'),
-        patchBacked: classified.filter((f) => f.classification === 'patch-backed'),
-        branding: classified.filter((f) => f.classification === 'branding'),
-        furnace: classified.filter((f) => f.classification === 'furnace'),
-        binaryUnsupported: classified.filter((f) => f.classification === 'binary-unsupported'),
-    };
-    // --unmanaged mode: only show unmanaged
-    if (options.unmanaged) {
-        await renderUnmanagedOnly(buckets.unmanaged, files.length, projectRoot, config.binaryName);
-        return;
-    }
-    await renderDefaultStatus(scope ? classified.length : files.length, buckets, projectRoot, config.binaryName);
-    await runHumanStatusCheck(allClassified, files, paths, checkPolicy, scope);
-}
-/** Registers the status command on the CLI program. */
-export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('status')
-        .description('Show modified files in engine/')
-        .option('--raw', 'Show raw worktree status without patch classification')
-        .option('--lock', 'Report the engine session lock instead of file status: holder pid, its command, how long it has held the lock, and how many waiters are queued behind it (read-only; never acquires it)')
-        .option('--unmanaged', 'Show only unmanaged changes (not covered by patches or tools)')
-        .option('--ownership', 'Show a flat path → owning patch table (flags files claimed by multiple patches)')
-        .option('--test-coverage', 'Show what the last recorded build covers for test packaging (full or scoped paths)')
-        .option('--json', 'Output classified file status as JSON')
-        .option('--summary', 'With --json: emit only summary counts (plus offending files when --check/--fail-on is active), omitting the per-file files[] payload')
-        .option('--include-ownership', 'With --json (composes with --summary): append an ownership block (path->owning-patch rows plus managed/unmanaged/conflict counts) to the payload, so one scan serves the classification, ownership, and check views. Does not change exit semantics.')
-        .option('--check', 'Exit non-zero when any unmanaged, patch-owned-drift, or conflict file exists (composes with --json; combine with --fail-on for finer policy)')
-        .option('--fail-on <classifications>', 'Comma-separated classification list that fails --check, replacing the default set (implies --check). Valid: patch-backed, patch-owned-drift, unmanaged, branding, furnace, conflict, binary-unsupported, ownership-conflict (a path claimed by more than one patch)')
-        .option('--allow <classifications>', 'Comma-separated classification list that never fails --check, removed from the fail set (implies --check; same values as --fail-on)')
-        .option('--fail-on-unknown', 'With --allow: also fail on every present classification that neither --fail-on nor --allow names, so a classification added in a later FireForge fails closed (implies --check)')
-        .option('--patches <names...>', 'Judge only the named patches: keeps the files each owns or claims and the ownership rows naming it (filename, stem, order number, manifest name, or slug; repeat, or separate with commas or whitespace). Unmanaged files belong to no patch and drop out. Default view, --json and --ownership only')
-        .action(withErrorHandling(async (options) => {
-        await statusCommand(getProjectRoot(), options);
-    }));
-}
+        for (const problem of report.pending) {
+            const subject = problem.subject === undefined ? '' : `${problem.subject}: `;
+            ctx.out.line(`${problem.code}  ${subject}${problem.message}`);
+            if (problem.hint !== undefined)
+                ctx.out.line(`  ${problem.hint}`);
+        }
+        if (report.pending.length === 0)
+            ctx.out.line('Nothing is unaccounted for.');
+        ctx.out.json({ ...report, clean: report.pending.length === 0 });
+        if (opts.check && report.pending.length > 0) {
+            throw new FireForgeError('status-not-clean', `${report.pending.length} thing(s) are unaccounted for.`, {
+                exitCode: ExitCode.GENERAL_ERROR,
+                hint: 'Each line above names the command that accounts for it.',
+            });
+        }
+    },
+});