@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/check.js

@@ -1,160 +1,47 @@
 // SPDX-License-Identifier: EUPL-1.2
-/**
- * `fireforge check`: the composed static gate. Runs status, verify,
- * per-patch lint, typecheck, Furnace validation and token coverage, plus
- * the project's `check.extraSteps[]`, in parallel, and ends with one
- * `FIREFORGE-VERDICT:` line over a per-step table (or one JSON document
- * under `--json`).
- *
- * Each step is the real command in a child process (see check-steps.ts for
- * why), so a step behaves exactly as it does when run on its own.
- */
-import { availableParallelism } from 'node:os';
-import { Command } from 'commander';
-import { getProjectPaths, loadConfig } from '../core/config.js';
-import { furnaceConfigExists } from '../core/furnace-config.js';
-import { loadPatchesManifest } from '../core/patch-manifest.js';
-import { selectPatchSubset } from '../core/patch-subset.js';
-import { GeneralError, InvalidArgumentError, LockContentionError } from '../errors/base.js';
-import { ConfigError } from '../errors/config.js';
-import { toError } from '../utils/errors.js';
-import { info, intro, isMachineOutputMode, note, outro, setMachineOutputMode, } from '../utils/logger.js';
-import { formatCheckTable, judgeCheck, writeCheckJson, writeCheckVerdictLine, } from './check-report.js';
-import { runCheckSteps } from './check-run.js';
-import { buildCheckPlan } from './check-steps.js';
-import { resolveStatusCheckPolicy } from './status-check.js';
-function parseNameList(raw) {
-    if (raw === undefined)
-        return undefined;
-    return raw
-        .split(',')
-        .map((name) => name.trim())
-        .filter((name) => name.length > 0);
-}
-/**
- * Applies `--only` and `--skip` to the plan. A step left out this way is
- * dropped from the table rather than shown as skipped: the caller asked
- * for a narrower gate, not a report of what it chose not to run.
- */
-export function selectCheckSteps(plan, options) {
-    const known = plan.map((step) => step.name);
-    const only = parseNameList(options.only);
-    const skip = parseNameList(options.skip);
-    for (const [flag, names] of [
-        ['--only', only],
-        ['--skip', skip],
-    ]) {
-        const unknown = (names ?? []).filter((name) => !known.includes(name));
-        if (unknown.length > 0) {
-            throw new InvalidArgumentError(`Unknown ${flag} step "${unknown.join('", "')}". Steps: ${known.join(', ')}.`, flag);
-        }
-    }
-    return plan.filter((step) => (only === undefined || only.includes(step.name)) && skip?.includes(step.name) !== true);
-}
-/** Parses `--jobs`: a positive integer. Defaults to one slot per CPU. */
-export function parseCheckJobs(raw) {
-    if (raw === undefined)
-        return availableParallelism();
-    const jobs = Number(raw);
-    if (!Number.isInteger(jobs) || jobs < 1) {
-        throw new InvalidArgumentError('--jobs must be a positive integer.', '--jobs');
-    }
-    return jobs;
-}
-/**
- * Refuses a `check.status` policy the status step would refuse, before any
- * step runs, as the config error it is.
- */
-function assertStatusPolicy(config) {
-    const policy = config.check?.status;
-    if (policy === undefined)
-        return;
-    try {
-        resolveStatusCheckPolicy({
-            check: true,
-            ...(policy.failOn !== undefined ? { failOn: policy.failOn.join(',') } : {}),
-            ...(policy.allow !== undefined ? { allow: policy.allow.join(',') } : {}),
-            ...(policy.failOnUnknown === true ? { failOnUnknown: true } : {}),
+import { checkJson, renderCheck, runCheck } from '../check/index.js';
+import { defineCommand, lockWaitMs, opt } from '../cli/command.js';
+import { FireForgeError } from '../kernel/errors.js';
+import { loadProject } from '../project/index.js';
+import { workspaceOptions } from './workspace.js';
+export const check = defineCommand({
+    name: 'check',
+    summary: 'Run the static checks as one judgement',
+    description: 'Runs status, verify, lint, typecheck, furnace-validate, token-coverage, token-lint and the ' +
+        "project's check.extraSteps, side by side where they do not depend on each other, and ends " +
+        'with one verdict line. A step with nothing to run is skipped. The steps that work in an ' +
+        'engine share one workspace.',
+    group: 'Daily',
+    options: {
+        only: opt.list('Run only this step; repeat for several', { valueName: 'step' }),
+        skip: opt.list('Leave this step out; repeat for several', { valueName: 'step' }),
+        ...workspaceOptions,
+    },
+    constraints: { exclusive: [['only', 'skip']] },
+    json: true,
+    verdict: true,
+    run: async (ctx, _args, opts) => {
+        const project = await loadProject(ctx.cwd, ctx.env);
+        const report = await runCheck(project, {
+            only: opts.only,
+            skip: opts.skip,
+            workspace: opts.workspace,
+            waitMs: lockWaitMs(opts.waitLock),
+        });
+        for (const line of renderCheck(report))
+            ctx.out.line(line);
+        ctx.out.json(checkJson(report));
+        const count = (status) => report.steps.filter((step) => step.status === status).length;
+        ctx.out.verdict(report.pass, {
+            ...(report.pass ? {} : { reason: 'check-failed', failed: report.failed.join(',') }),
+            steps: report.steps.length,
+            passed: count('pass'),
+            skipped: count('skipped'),
         });
-    }
-    catch (error) {
-        throw new ConfigError(`Config field "check.status" is invalid: ${toError(error).message}`);
-    }
-}
-/** Resolves `--patches` once, so a typo fails here rather than in three steps. */
-async function resolvePatchScope(patchesDir, requested) {
-    if (requested === undefined || requested.length === 0)
-        return undefined;
-    const manifest = await loadPatchesManifest(patchesDir);
-    if (!manifest || manifest.patches.length === 0) {
-        throw new GeneralError('--patches needs a patch queue, but patches.json lists no patches.');
-    }
-    return selectPatchSubset(manifest, requested, '--patches selects patches (filename, stem, order number, manifest name, or slug).').map((patch) => patch.filename);
-}
-/**
- * Runs the composed gate.
- *
- * @param projectRoot - Project root directory
- * @param options - See {@link CheckCommandOptions}
- */
-export async function checkCommand(projectRoot, options = {}) {
-    const previousMachineOutputMode = isMachineOutputMode();
-    // `--json` owns stdout from the first byte. On a throw the mode stays
-    // engaged and withErrorHandling resets it after routing the refusal.
-    if (options.json === true)
-        setMachineOutputMode(true);
-    await runCheck(projectRoot, options);
-    if (isMachineOutputMode() !== previousMachineOutputMode) {
-        setMachineOutputMode(previousMachineOutputMode);
-    }
-}
-async function runCheck(projectRoot, options) {
-    intro('FireForge Check');
-    const jobs = parseCheckJobs(options.jobs);
-    const config = await loadConfig(projectRoot);
-    assertStatusPolicy(config);
-    const patches = await resolvePatchScope(getProjectPaths(projectRoot).patches, options.patches);
-    const plan = selectCheckSteps(buildCheckPlan({
-        projectRoot,
-        config,
-        furnaceConfigured: await furnaceConfigExists(projectRoot),
-        patches,
-    }), options);
-    const runnable = plan.filter((step) => step.skipReason === undefined).length;
-    info(`Running ${runnable} step(s), up to ${Math.min(jobs, Math.max(1, runnable))} at once${patches ? `, judging ${patches.join(', ')}` : ''}.`);
-    const results = await runCheckSteps(plan, jobs);
-    const verdict = judgeCheck(results, { failOnSkipped: config.check?.failOnSkipped });
-    if (options.json === true) {
-        writeCheckJson(results, verdict);
-    }
-    else {
-        note(formatCheckTable(results), 'Steps');
-        for (const result of results) {
-            if (result.status === 'fail' && result.outputTail) {
-                note(result.outputTail, `${result.name}: ${result.command}`);
-            }
+        if (!report.pass) {
+            throw new FireForgeError('check-failed', `Check failed: ${report.failed.join(', ')}.`, {
+                hint: 'Fix what each failed step reports above; "fireforge check --only <step>" runs one step.',
+            });
         }
-        outro(verdict.passed ? 'Check passed' : `Check failed: ${verdict.failed.join(', ')}`);
-        writeCheckVerdictLine(verdict);
-    }
-    if (verdict.reason === 'lock-timeout') {
-        throw new LockContentionError(`fireforge check: ${verdict.failed.join(', ')} could not take their locks in time. Re-run when the holder is done.`);
-    }
-    if (!verdict.passed) {
-        throw new GeneralError(`fireforge check failed: ${verdict.failed.join(', ')}. Run a failing step on its own for its full output.`);
-    }
-}
-/** Registers the `check` command on the CLI program. */
-export function registerCheck(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('check')
-        .description('Composed static gate: status, verify, per-patch lint, typecheck, Furnace validation, token coverage and fireforge.json check.extraSteps in parallel, with one FIREFORGE-VERDICT line')
-        .option('--json', 'Write one JSON document (verdict plus a result per step) instead of the table')
-        .option('--patches <names...>', 'Judge only these patches in the status, verify and lint steps (filename, stem, order number, manifest name, or slug)')
-        .option('--only <steps>', 'Comma-separated steps to run, leaving out the rest')
-        .option('--skip <steps>', 'Comma-separated steps to leave out')
-        .option('--jobs <n>', 'Steps to run at once (default: one per CPU)')
-        .action(withErrorHandling(async (options) => {
-        await checkCommand(getProjectRoot(), options);
-    }));
-}
+    },
+});

package/dist/src/commands/config.js

@@ -1,229 +1,53 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { Command } from 'commander';
-import { configExists, loadRawConfigDocument, mutateConfig, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, validateConfig, withConfigFileLock, writeConfigDocument, } from '../core/config.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { ConfigError } from '../errors/config.js';
-import { toError } from '../utils/errors.js';
-import { info, intro, outro, success, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
-import { isJsonObject } from '../utils/validation.js';
-/**
- * Gets a nested value from a raw config document using dot notation.
- * @param doc - Document to traverse
- * @param path - Dot-separated path (e.g., "firefox.version")
- * @returns The value at the path, or undefined if not found
- */
-function getNestedValue(doc, path) {
-    let current = doc;
-    for (const part of path.split('.')) {
-        if (current === null || current === undefined || typeof current !== 'object') {
-            return undefined;
-        }
-        current = Array.isArray(current) ? current[Number(part)] : current[part];
-    }
-    return current;
-}
-/** Config keys that must always be stored as strings. */
-const STRING_TYPED_KEYS = new Set([
-    'name',
-    'vendor',
-    'appId',
-    'binaryName',
-    'firefox.version',
-    'firefox.product',
-    'firefox.sha256',
-    'firefox.candidate',
-    'license',
-    'wire.subscriptDir',
-    'history.path',
-]);
-/**
- * Parses a string value into the appropriate type.
- * Keys listed in STRING_TYPED_KEYS are always stored as strings to prevent
- * accidental type coercion (e.g. `fireforge config firefox.version 128` would
- * otherwise become the number 128 instead of the string "128").
- */
-function parseValue(value, key) {
-    // For known string-typed keys, always return as string
-    if (key && STRING_TYPED_KEYS.has(key)) {
-        return value;
-    }
-    // Try to parse as JSON first (handles numbers, booleans, arrays, objects).
-    try {
-        // JSON.parse can only ever produce JSON values.
-        const parsed = JSON.parse(value);
-        if (typeof parsed !== 'string') {
-            warn(`Value "${value}" was interpreted as ${typeof parsed}. Use '"${value}"' for a string.`);
-        }
-        return parsed;
-    }
-    catch {
-        // Fall back to string
-        return value;
-    }
-}
-/**
- * Formats a value for display.
- */
-function formatValue(value) {
-    if (value === undefined) {
+import { arg, defineCommand } from '../cli/command.js';
+import { getConfigValue, setConfigValue } from '../config/index.js';
+import { findProjectRoot } from '../project/index.js';
+function shown(value) {
+    if (value === undefined)
         return '(not set)';
-    }
-    if (typeof value === 'string')
-        return value;
-    if (typeof value === 'number' || typeof value === 'boolean') {
-        return String(value);
-    }
-    return JSON.stringify(value, null, 2);
-}
-/**
- * Runs the config command to get or set configuration values.
- * @param projectRoot - Root directory of the project
- * @param key - Configuration key (dot notation)
- * @param value - Optional value to set
- */
-export async function configCommand(projectRoot, key, value, options = {}) {
-    intro('FireForge Config');
-    // Check if config exists
-    if (!(await configExists(projectRoot))) {
-        throw new GeneralError('No fireforge.json found. Run "fireforge setup" to create a project.');
-    }
-    if (value === undefined) {
-        // Get mode: read the raw document rather than the validated config so
-        // keys persisted via `fireforge config <key> --force` remain readable.
-        // `validateConfig` builds a typed clone containing only the known schema
-        // fields, so relying on it here would hide forced-write keys and surface
-        // "Unknown config key" even though the key sits plainly inside
-        // fireforge.json.
-        const rawConfig = await loadRawConfigDocument(projectRoot);
-        const currentValue = getNestedValue(rawConfig, key);
-        if (currentValue === undefined) {
-            if (SUPPORTED_CONFIG_PATHS.includes(key)) {
-                info(`${key} = ${formatValue(currentValue)}`);
-                outro('');
-                return;
-            }
-            throw new InvalidArgumentError(`Unknown config key: ${key}`);
-        }
-        else {
-            info(`${key} = ${formatValue(currentValue)}`);
-        }
-    }
-    else {
-        // Set mode: validate key prefix
-        const topLevelKey = key.split('.')[0] ?? key;
-        if (!SUPPORTED_CONFIG_ROOT_KEYS.includes(topLevelKey) &&
-            !options.force) {
-            throw new InvalidArgumentError(`Unknown config key prefix: "${topLevelKey}". Known keys: ${SUPPORTED_CONFIG_ROOT_KEYS.join(', ')}. Use --force to set anyway.`);
-        }
-        if (!SUPPORTED_CONFIG_PATHS.includes(key) && !options.force) {
-            throw new InvalidArgumentError(`Unknown config key: "${key}". Known keys: ${SUPPORTED_CONFIG_PATHS.join(', ')}. Use --force to set anyway.`);
-        }
-        const parsedValue = parseValue(value, key);
-        const keyIsKnown = SUPPORTED_CONFIG_PATHS.includes(key);
-        let unchanged;
-        try {
-            // Serialise the read → mutate → write round-trip behind the sidecar
-            // config lock so two concurrent `fireforge config` invocations cannot
-            // each read the pre-state, mutate their own copy, and clobber each
-            // other on write, both exiting 0 with one key silently lost. Atomic
-            // file writes (temp + rename) are not enough on their own: the lost
-            // update happens before the rename, inside the read-modify step.
-            // Readers stay lock-free (see `withConfigFileLock`).
-            unchanged = await withConfigFileLock(projectRoot, async () => {
-                // Short-circuit when the new value matches the current on-disk
-                // value, so a harmless re-set neither rewrites the file nor bumps
-                // its mtime. The check uses the raw on-disk document so forced keys
-                // round-trip the same as known keys. A real change is written by
-                // `writeConfigDocument`, which edits only the changed value in place.
-                const rawConfig = await loadRawConfigDocument(projectRoot);
-                const currentValue = getNestedValue(rawConfig, key);
-                if (deepEqual(currentValue, parsedValue)) {
-                    return true;
-                }
-                // `--force` is an escape hatch for unknown keys. It must not also
-                // let the user write a structurally invalid value for a known key.
-                // Strict validation applies whenever the key is listed in
-                // SUPPORTED_CONFIG_PATHS, regardless of --force.
-                //
-                // Both branches seed the mutation from the raw on-disk document.
-                // Round-tripping the known-key branch through `loadConfig` →
-                // `validateConfig` builds a typed clone containing only the known
-                // schema fields, so any ordinary `fireforge config <key> <value>`
-                // would silently drop every previously --force-written key from
-                // fireforge.json.
-                if (options.force && !keyIsKnown) {
-                    const updatedConfig = mutateConfig(rawConfig, key, parsedValue, true);
-                    await writeConfigDocument(projectRoot, updatedConfig);
-                }
-                else {
-                    // Mutate the raw document (preserving unknown keys), then run
-                    // strict validation on the result. validateConfig checks the
-                    // known schema fields and ignores unknown keys, so this keeps
-                    // exactly the old validation strength while writing the
-                    // unstripped document.
-                    const updatedConfig = mutateConfig(rawConfig, key, parsedValue, true);
-                    validateConfig(updatedConfig);
-                    await writeConfigDocument(projectRoot, updatedConfig);
-                }
-                return false;
-            });
-        }
-        catch (error) {
-            // Only value/validation problems are the user's "invalid value".
-            // Lock-acquisition timeouts and I/O failures must keep their own
-            // types and messages. Re-labelling a lock timeout as `Invalid value
-            // for "<key>"` points diagnosis at the value (and returns the wrong
-            // exit-code class) when the real problem is a concurrent fireforge
-            // process holding the config lock.
-            if (error instanceof ConfigError) {
-                throw new InvalidArgumentError(`Invalid value for "${key}": ${toError(error).message}`, key);
-            }
-            throw error;
-        }
-        if (unchanged) {
-            info(`${key} = ${formatValue(parsedValue)} (unchanged)`);
-        }
-        else {
-            success(`Set ${key} = ${formatValue(parsedValue)}`);
-        }
-    }
-    outro('');
-}
-/**
- * Structural equality check covering the shapes `fireforge config` accepts:
- * primitives (strings, numbers, booleans), `null`, arrays of primitives, and
- * nested objects. Used to short-circuit no-op writes: when the parsed value
- * matches the current on-disk value, the mutate + write step is skipped
- * entirely.
- */
-function deepEqual(a, b) {
-    if (a === b)
-        return true;
-    if (Array.isArray(a)) {
-        if (!Array.isArray(b))
-            return false;
-        if (a.length !== b.length)
-            return false;
-        return a.every((v, i) => deepEqual(v, b[i]));
-    }
-    if (!isJsonObject(a) || !isJsonObject(b)) {
-        // Primitives (and null) compare by identity, handled above.
-        return false;
-    }
-    const keysA = Object.keys(a);
-    const keysB = Object.keys(b);
-    if (keysA.length !== keysB.length)
-        return false;
-    return keysA.every((k) => deepEqual(a[k], b[k]));
-}
-/** Registers the config command on the CLI program. */
-export function registerConfig(program, { getProjectRoot, withErrorHandling }) {
-    program
-        .command('config <key> [value]')
-        .description('Get or set configuration values')
-        .option('-f, --force', 'Allow setting unknown config keys')
-        .action(withErrorHandling(async (key, value, options) => {
-        await configCommand(getProjectRoot(), key, value, pickDefined(options));
-    }));
+    return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
 }
+const get = defineCommand({
+    name: 'get',
+    summary: 'Print a key of fireforge.json',
+    args: { key: arg.string('Key path, such as firefox.version or gate.lanes[0].files') },
+    json: true,
+    run: async (ctx, { key }) => {
+        const entry = await getConfigValue(await findProjectRoot(ctx.cwd), key);
+        const fallback = entry.value === undefined && entry.defaultValue !== undefined
+            ? ` (default ${shown(entry.defaultValue)})`
+            : '';
+        ctx.out.line(`${shown(entry.value)}${fallback}`);
+        ctx.out.json({
+            key,
+            value: entry.value ?? null,
+            default: entry.defaultValue ?? null,
+            type: entry.type,
+            doc: entry.doc ?? null,
+        });
+    },
+});
+const set = defineCommand({
+    name: 'set',
+    summary: 'Set a key of fireforge.json, validating the whole file first',
+    description: 'The value is read as JSON when the key accepts that (4, true, ["a"]) and as text otherwise. ' +
+        'Only the changed value is rewritten; the rest of the file keeps its layout. "mode" is not ' +
+        'changed this way: "fireforge migrate --to-source" moves a project to source mode, and the way back is ' +
+        '"fireforge export", then setting "mode" to "patches" and removing "source" by hand.',
+    args: {
+        key: arg.string('Key path, such as build.jobs'),
+        value: arg.string('The new value'),
+    },
+    json: true,
+    run: async (ctx, { key, value }) => {
+        const edit = await setConfigValue(await findProjectRoot(ctx.cwd), key, value);
+        ctx.out.line(`${key} = ${shown(edit.value)}${edit.changed ? '' : ' (unchanged)'}`);
+        ctx.out.json({ key, value: edit.value, changed: edit.changed });
+    },
+});
+export const config = defineCommand({
+    name: 'config',
+    summary: 'Read or edit fireforge.json through its schema',
+    group: 'Project',
+    subcommands: [get, set],
+});