@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/utils/logger.js

@@ -1,270 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-/** Whether verbose mode is enabled */
-let verboseMode = false;
-/**
- * Whether machine-output mode is active (`--json` / `--raw`).
- *
- * In machine mode, stdout belongs exclusively to the machine-readable
- * payload: all human-facing diagnostics (intro/outro banners, info, warn,
- * error, steps, notes) are routed to stderr as plain unstyled lines.
- * Otherwise clack's log helpers write styled warnings to stdout before the
- * JSON body, and a truncated-directory warning during `status --json` breaks
- * every `JSON.parse(stdout)` consumer.
- */
-let machineOutputMode = false;
-/**
- * Enables or disables verbose mode.
- * @param enabled - Whether to enable verbose output
- */
-export function setVerbose(enabled) {
-    verboseMode = enabled;
-}
-/**
- * Switches the logger into (or out of) machine-output mode. Commands with
- * `--json`/`--raw` flags call this before producing any output.
- */
-export function setMachineOutputMode(enabled) {
-    machineOutputMode = enabled;
-}
-/** True when machine-output mode is active. */
-export function isMachineOutputMode() {
-    return machineOutputMode;
-}
-/**
- * Whether stdout is sealed behind a machine-readable final line.
- *
- * The `FIREFORGE-VERDICT:` contract promises that line as the run's last
- * stdout write, but emit-then-throw failure paths rethrow into
- * `withErrorHandling`, whose clack error/cancel rendering lands on stdout
- * in non-machine mode, displacing the verdict from the final line. The
- * verdict sink seals stdout the moment it writes. Every later logger call
- * routes to stderr through the same diagnostic channel machine mode uses.
- * `withErrorHandling`'s finally clears the seal (alongside machine mode).
- */
-let stdoutSealed = false;
-/** Seals (or unseals) stdout after a machine-readable final line. */
-export function setStdoutSealed(sealed) {
-    stdoutSealed = sealed;
-}
-/**
- * True when a machine-readable payload already owns stdout.
- *
- * The CLI error boundary consults this before emitting a `--json` error
- * envelope: a command that wrote its payload and THEN refused (e.g.
- * `status --json --fail-on`) must not have a second JSON document appended,
- * which would break the "exactly one document" half of the contract in
- * docs/machine-output.md.
- */
-export function isStdoutSealed() {
-    return stdoutSealed;
-}
-/** True when human output must avoid stdout. */
-function routeToStderr() {
-    return machineOutputMode || stdoutSealed;
-}
-/** Writes a plain diagnostic line to stderr (machine-mode side channel). */
-function writeDiagnostic(prefix, message) {
-    process.stderr.write(`${prefix}${message}\n`);
-}
-/**
- * Checks if verbose mode is enabled.
- *
- * Exported so the CLI error boundary can decide whether to walk an error's
- * `cause` chain.
- *
- * @returns True if verbose mode is enabled
- */
-export function isVerbose() {
-    return verboseMode;
-}
-/**
- * Displays a verbose/debug message (only shown if verbose mode is enabled).
- * @param message - Message to display
- */
-export function verbose(message) {
-    if (!isVerbose())
-        return;
-    if (routeToStderr()) {
-        writeDiagnostic('[debug] ', message);
-        return;
-    }
-    p.log.info(`[debug] ${message}`);
-}
-function supportsInteractiveSpinner() {
-    return process.stdout.isTTY && process.stderr.isTTY;
-}
-/** Displays the top-level intro banner for a command. */
-export function intro(message) {
-    if (routeToStderr())
-        return;
-    p.intro(message);
-}
-/** Displays the closing outro banner for a command. */
-export function outro(message) {
-    if (routeToStderr())
-        return;
-    p.outro(message);
-}
-/** Logs an informational message. */
-export function info(message) {
-    if (routeToStderr()) {
-        writeDiagnostic('', message);
-        return;
-    }
-    p.log.info(message);
-}
-/** Logs a success message. */
-export function success(message) {
-    if (routeToStderr()) {
-        writeDiagnostic('', message);
-        return;
-    }
-    p.log.success(message);
-}
-/** Logs a warning message. */
-export function warn(message) {
-    if (routeToStderr()) {
-        writeDiagnostic('warning: ', message);
-        return;
-    }
-    p.log.warn(message);
-}
-/**
- * Prefix that marks a line as FireForge's own explanatory output rather
- * than a defect. Kept greppable so downstream filters can whitelist it.
- */
-export const NOTICE_PREFIX = '[FireForge] NOTICE:';
-/**
- * Logs one of FireForge's own "why this is happening / why this is slow"
- * explanations at warning severity.
- *
- * These lines are not warnings about the operator's code. They explain a
- * decision FireForge just made (escalating an incremental build to a full
- * one, sharding a run, skipping a step). Emitted through `info` they are
- * silently dropped by agent-facing output filters that keep only warnings
- * and errors, leaving a multi-minute build with no explanation and reading
- * as a hang. There are very few such lines and they are exactly the ones a
- * non-interactive operator needs, so they ride the warning channel and carry
- * {@link NOTICE_PREFIX} so a reader can still tell them apart from a real
- * warning.
- */
-export function notice(message) {
-    if (routeToStderr()) {
-        writeDiagnostic('warning: ', `${NOTICE_PREFIX} ${message}`);
-        return;
-    }
-    p.log.warn(`${NOTICE_PREFIX} ${message}`);
-}
-/** Logs an error message. */
-export function error(message) {
-    if (routeToStderr()) {
-        writeDiagnostic('error: ', message);
-        return;
-    }
-    p.log.error(message);
-}
-/** Logs an in-progress step message. */
-export function step(message) {
-    if (routeToStderr()) {
-        writeDiagnostic('', message);
-        return;
-    }
-    p.log.step(message);
-}
-/** Logs a plain message without a status prefix. */
-export function message(message) {
-    if (routeToStderr()) {
-        writeDiagnostic('', message);
-        return;
-    }
-    p.log.message(message);
-}
-/** Formats text using the success color without logging it. */
-export function formatSuccessText(message) {
-    return pc.green(message);
-}
-/** Formats text using the error color without logging it. */
-export function formatErrorText(message) {
-    return pc.red(message);
-}
-/**
- * Creates a spinner for long-running operations.
- * @param initialMessage - Initial message to display
- * @returns Spinner handle with message(), stop(), and error() methods
- */
-export function spinner(initialMessage) {
-    if (routeToStderr()) {
-        // Spinner progress is diagnostics. Keep stdout clean for the payload.
-        return {
-            message: (msg) => {
-                writeDiagnostic('', msg);
-            },
-            stop: (msg) => {
-                if (msg)
-                    writeDiagnostic('', msg);
-            },
-            error: (msg) => {
-                writeDiagnostic('error: ', msg ?? 'Failed');
-            },
-        };
-    }
-    if (!supportsInteractiveSpinner()) {
-        let latestMessage = initialMessage;
-        return {
-            message: (msg) => {
-                latestMessage = msg;
-                p.log.step(msg);
-            },
-            stop: (msg) => {
-                p.log.step(msg ?? latestMessage);
-            },
-            error: (msg) => {
-                p.log.error(msg ?? 'Failed');
-            },
-        };
-    }
-    const s = p.spinner();
-    s.start(initialMessage);
-    return {
-        message: (msg) => {
-            s.message(msg);
-        },
-        stop: (msg) => {
-            s.stop(msg ?? initialMessage);
-        },
-        error: (msg) => {
-            s.stop();
-            p.log.error(msg ?? 'Failed');
-        },
-    };
-}
-/** Emits a cancellation message. */
-export function cancel(message) {
-    if (routeToStderr()) {
-        writeDiagnostic('cancelled: ', message);
-        return;
-    }
-    p.cancel(message);
-}
-/**
- * Checks whether a prompt result represents a user cancellation.
- *
- * Narrows to `symbol`: clack returns its cancel sentinel as a symbol and
- * `p.isCancel` is itself a type predicate. Returning plain `boolean` erases
- * that narrowing and forces `as string` / `as PatchCategory` casts across
- * the command modules on the non-cancelled branch, where the value is
- * already known not to be the sentinel. Keep the predicate form.
- */
-export function isCancel(value) {
-    return p.isCancel(value);
-}
-/** Displays a titled note block for follow-up details. */
-export function note(message, title) {
-    if (routeToStderr()) {
-        writeDiagnostic('', title ? `${title}: ${message}` : message);
-        return;
-    }
-    p.note(message, title);
-}

package/dist/src/utils/machine-output.d.ts

@@ -1,12 +0,0 @@
-import { ExitCode } from '../errors/codes.js';
-/** Current envelope version. Bump only with a documented migration. */
-export declare const MACHINE_OUTPUT_SCHEMA_VERSION = 1;
-/**
- * Writes the machine-readable error envelope to stdout and throws the
- * sentinel that carries the exit code to the entrypoint. Never returns.
- *
- * @param code - Stable machine-readable reason tag, e.g. `engine-missing`
- * @param message - Human-readable explanation, identical to the non-JSON text
- * @param exitCode - Exit code to terminate with
- */
-export declare function emitMachineError(code: string, message: string, exitCode?: ExitCode): never;

package/dist/src/utils/machine-output.js

@@ -1,33 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * The `--json` envelope contract, in one place.
- *
- * Without a single owner, machine-readable output drifts into unrelated
- * shapes: two commands sharing a `schemaVersion: 1` envelope can still
- * disagree on failure, so a scripted consumer gets a parseable refusal from
- * one and a bare non-zero exit from the other.
- *
- * The contract, documented in `docs/machine-output.md`:
- *   1. Success writes exactly one JSON document to stdout.
- *   2. Failure writes exactly one `{ schemaVersion, error, code }` document
- *      to stdout, then exits non-zero.
- *   3. Machine mode is engaged before any output, so every diagnostic,
- *      including one rendered later by `withErrorHandling`, routes to
- *      stderr and cannot corrupt the payload.
- */
-import { CommandError } from '../errors/base.js';
-import { ExitCode } from '../errors/codes.js';
-/** Current envelope version. Bump only with a documented migration. */
-export const MACHINE_OUTPUT_SCHEMA_VERSION = 1;
-/**
- * Writes the machine-readable error envelope to stdout and throws the
- * sentinel that carries the exit code to the entrypoint. Never returns.
- *
- * @param code - Stable machine-readable reason tag, e.g. `engine-missing`
- * @param message - Human-readable explanation, identical to the non-JSON text
- * @param exitCode - Exit code to terminate with
- */
-export function emitMachineError(code, message, exitCode = ExitCode.GENERAL_ERROR) {
-    process.stdout.write(`${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, error: message, code })}\n`);
-    throw new CommandError(exitCode);
-}

package/dist/src/utils/options.d.ts

@@ -1,155 +0,0 @@
-import type { Command } from 'commander';
-/**
- * Filters an object to only include keys whose values are not undefined.
- * Designed for use with exactOptionalPropertyTypes: the result can be
- * spread into typed option objects without assigning undefined to optional
- * properties.
- *
- * Constrained to `object`, not `Record<string, unknown>`: a named interface
- * has no index signature, so the narrower constraint rejects exactly the
- * annotations this helper is most useful with. Nothing in the body needs the
- * index signature, since the key walk goes through `Object.keys`.
- *
- * @param obj - Object to filter
- * @returns The same object with every `undefined`-valued key removed
- */
-export declare function pickDefined<T extends object>(obj: T): DefinedProps<T>;
-/** `T` with every property optional and `undefined` removed: what {@link pickDefined} returns. */
-export type DefinedProps<T> = {
-    [K in keyof T]+?: Exclude<T[K], undefined>;
-};
-/**
- * Wraps an option-argument parser so its failures surface through
- * commander's own invalid-argument channel.
- *
- * Commander only treats errors whose `code` is `'commander.invalidArgument'`
- * as argument-validation failures. Anything else re-throws out of
- * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
- * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
- * That covers a plain Error, a `GeneralError`, and even a FireForge
- * `InvalidArgumentError`, whose `code` is a numeric ExitCode. Every
- * `.argParser()`/option-parser callback must be wrapped with this helper (or
- * throw commander's InvalidArgumentError directly).
- */
-export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw: string) => T;
-/**
- * Commander plumbing for a repeatable string option, as a spreadable
- * `[accumulator, default]` pair:
- *
- * ```ts
- * .option('--mach-arg <arg>', 'Repeatable.', ...stringListOption())
- * ```
- *
- * Commander types the default slot as `unknown`, so every open-coded copy
- * carries an `[] as string[]` cast, and it is easy to mutate the accumulator
- * in place instead of returning a new array. Returning a fresh array per
- * call also means the default cannot be shared between two `.option()`
- * registrations.
- */
-export declare function stringListOption(): [(value: string, previous: string[]) => string[], string[]];
-/** Environment variable naming a standing wait budget for the whole session. */
-export declare const WAIT_LOCK_ENV_VAR = "FIREFORGE_WAIT_LOCK";
-export declare const MAX_WAIT_LOCK_SECONDS = 86400;
-/**
- * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
- * in seconds for `withEngineSessionLock`:
- * - absent (`undefined`) → {@link WAIT_LOCK_ENV_VAR} if set, else `undefined`
- *   (the ~1 s fail-fast),
- * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
- * - explicit value → integer validated into 1..86400.
- *
- * The flag always wins over the environment: the environment expresses a
- * default for a session, and an invocation that names a budget has said
- * something more specific than the session did.
- *
- * Accepts the raw string too, so it doubles as the option's arg parser (wrap
- * with {@link commanderArgParser} so failures surface through commander's
- * invalid-argument channel). In that role the value is never `undefined`, so
- * the environment fallback cannot leak into flag parsing, only into flag
- * absence, which is where it belongs.
- */
-export declare function resolveWaitLockSeconds(value: string | number | boolean | undefined): number | undefined;
-/**
- * The session-wide wait budget in milliseconds, or undefined when none is
- * set. Sourced from {@link WAIT_LOCK_ENV_VAR} only.
- *
- * Exists for the secondary locks a command takes after the one its
- * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
- * session lock and then `.fireforge/furnace.lock`. Only the first had a
- * budget, so a contended deploy died on the file lock's fixed 30 s while
- * its operator believed a much larger budget was in force. Every furnace
- * leaf that takes the furnace lock threads its own `--wait-lock` into it;
- * this is the fallback when the flag is absent, and the only budget for
- * callers that do not thread one (doctor's furnace repair, the
- * pre-build apply).
- *
- * Env-only: a flag belongs to one invocation and is passed
- * explicitly where it applies, while the environment is exactly the place a
- * session-wide default is expressed. An explicit budget at a call site
- * always wins over this.
- *
- * @returns The session budget in milliseconds, or undefined
- */
-export declare function sessionWaitLockMs(): number | undefined;
-/**
- * Registers `--wait-lock [seconds]` on a command that takes no lock, so a
- * scripted sequence can blanket-append the flag without hitting a usage
- * error. A command that rejects it with "unknown option" kills the whole
- * sequence with a usage error instead of a lock message.
- *
- * The flag is accepted and ignored here, never silently repurposed, and
- * the help text says so, so nobody reads its presence as evidence that this
- * command waits for anything.
- *
- * The value is parsed and validated exactly as the honoring variant does:
- * `--wait-lock nonsense` must still be a usage error everywhere, or the
- * uniformity would be a lie.
- */
-export declare function addAcceptedWaitLockOption(command: Command): Command;
-/**
- * Recursively gives every leaf command in the tree a `--wait-lock` flag: the
- * honoring registration where one already exists, the accept-and-ignore
- * one everywhere else.
- */
-export declare function ensureWaitLockOptionEverywhere(command: Command): void;
-/**
- * True for a token that reads as a path rather than a number: it has a
- * path separator or a file extension, or is `.`/`..`. A bare word such as
- * `nonsense` is not path-shaped, so `--wait-lock nonsense` stays the usage
- * error it always was.
- */
-export declare function isPathShapedArgument(token: string): boolean;
-/**
- * Rewrites a command's option tokens so a path-shaped argument after a
- * numeric optional-value flag is an operand, and the flag takes its
- * default.
- *
- * Commander binds the next non-dash token to an optional value, so
- * `fireforge test --build --wait-lock browser_x.js` failed with
- * "--wait-lock must be an integer in 1..86400 (got "browser_x.js")": the
- * help says the value is optional, and the obvious spelling refused. The
- * released flag moves to the end of the option section (before any `--`),
- * where nothing follows it, so commander reads it bare. Operands keep their
- * relative order. The value of a required-value option (`--mach-arg
- * --wait-lock`) is never mistaken for a flag.
- *
- * @param argv - The tokens commander passes to `parseOptions`
- * @param requiredValueFlags - This command's flags that always take a value
- * @returns The rewritten tokens
- */
-export declare function releasePathShapedValues(argv: readonly string[], requiredValueFlags: ReadonlySet<string>): string[];
-/**
- * Registers the shared `--wait-lock [seconds]` flag on a lock-taking
- * command (the engine session lock for engine-mutating commands, the patch
- * directory lock for queue-mutating ones). The parsed option value is `true`
- * for the bare flag or a validated integer. Feed it through
- * {@link resolveWaitLockSeconds} at the call site to obtain the
- * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
- *
- * A command can take more than one lock (a furnace mutation takes the
- * engine session lock and then `.fireforge/furnace.lock`) and the budget
- * has to reach all of them or the flag is a half-truth. The secondary locks
- * read the session budget through {@link sessionWaitLockMs} rather than
- * having it threaded to every call site.
- */
-export declare function addWaitLockOption(command: Command): Command;