@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/utils/options.js

@@ -1,312 +0,0 @@
-import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { toError } from './errors.js';
-/**
- * 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 function pickDefined(obj) {
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-        if (value !== undefined) {
-            result[key] = value;
-        }
-    }
-    return result;
-}
-/**
- * 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 function commanderArgParser(parse) {
-    return (raw) => {
-        try {
-            return parse(raw);
-        }
-        catch (error) {
-            throw new CommanderInvalidArgumentError(toError(error).message);
-        }
-    };
-}
-/**
- * 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 function stringListOption() {
-    return [(value, previous) => [...previous, value], []];
-}
-/** Wait budget applied when `--wait-lock` is passed without a value. */
-const DEFAULT_WAIT_LOCK_SECONDS = 60;
-/** Environment variable naming a standing wait budget for the whole session. */
-export const WAIT_LOCK_ENV_VAR = 'FIREFORGE_WAIT_LOCK';
-/**
- * Bounds shared by the flag and the environment variable. The ceiling is a
- * day: on a shared engine a re-export or `test --build` queued behind a
- * peer's long series can need more than an hour, and a cap below that turns
- * a longer wait into a requeue after exit 15.
- */
-const MIN_WAIT_LOCK_SECONDS = 1;
-export const MAX_WAIT_LOCK_SECONDS = 86_400;
-/**
- * Parses a wait budget from text, or undefined when it is not an integer in
- * range. Shared by the flag and {@link WAIT_LOCK_ENV_VAR} so the two cannot
- * drift on what they accept.
- */
-function parseWaitLockSeconds(raw) {
-    const n = Number.parseInt(raw, 10);
-    if (!Number.isFinite(n) || n < MIN_WAIT_LOCK_SECONDS || n > MAX_WAIT_LOCK_SECONDS) {
-        return undefined;
-    }
-    return n;
-}
-/**
- * The standing wait budget from {@link WAIT_LOCK_ENV_VAR}, or undefined when
- * it is unset or empty.
- *
- * Exists because a wait budget is a property of the session, not of the
- * invocation: a checkout worked by several concurrent agent sessions has a
- * held lock as its normal state, and an unattended loop would otherwise have
- * to thread `--wait-lock` through every command it issues. That is the one
- * place it is easiest to forget, and the failure only shows up once the loop
- * has already produced a tail of refusals.
- *
- * An unusable value is a usage error rather than a silent fall-back to
- * fail-fast: the operator set it precisely because they did not want to
- * discover the budget at refusal time.
- */
-function waitLockSecondsFromEnv() {
-    const raw = process.env[WAIT_LOCK_ENV_VAR]?.trim();
-    if (raw === undefined || raw.length === 0) {
-        return undefined;
-    }
-    const parsed = parseWaitLockSeconds(raw);
-    if (parsed === undefined) {
-        throw new InvalidArgumentError(`${WAIT_LOCK_ENV_VAR} must be an integer in ${MIN_WAIT_LOCK_SECONDS}..${MAX_WAIT_LOCK_SECONDS} (got "${raw}")`, WAIT_LOCK_ENV_VAR);
-    }
-    return parsed;
-}
-/**
- * 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 function resolveWaitLockSeconds(value) {
-    if (value === undefined || value === false) {
-        return waitLockSecondsFromEnv();
-    }
-    if (value === true) {
-        return DEFAULT_WAIT_LOCK_SECONDS;
-    }
-    if (typeof value === 'number') {
-        return value;
-    }
-    const parsed = parseWaitLockSeconds(value);
-    if (parsed === undefined) {
-        throw new GeneralError(`--wait-lock must be an integer in ${MIN_WAIT_LOCK_SECONDS}..${MAX_WAIT_LOCK_SECONDS} (got "${value}")`);
-    }
-    return parsed;
-}
-/**
- * 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 function sessionWaitLockMs() {
-    const seconds = waitLockSecondsFromEnv();
-    return seconds === undefined ? undefined : seconds * 1000;
-}
-/**
- * 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 function addAcceptedWaitLockOption(command) {
-    return command.option('--wait-lock [seconds]', 'Accepted for scripting uniformity and ignored: this command takes no FireForge lock', commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
-}
-/**
- * True when `command` already declares `--wait-lock` itself. Used by the
- * CLI wiring to add the accept-and-ignore variant only where the honoring
- * one is absent.
- */
-function hasWaitLockOption(command) {
-    return command.options.some((option) => option.long === '--wait-lock');
-}
-/**
- * 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 function ensureWaitLockOptionEverywhere(command) {
-    for (const sub of command.commands) {
-        // Commander groups otherwise capture a trailing leaf option before the
-        // action can see it. Register the uniform flag only on actionable leaves.
-        if (sub.commands.length === 0 && !hasWaitLockOption(sub))
-            addAcceptedWaitLockOption(sub);
-        releasePathShapedOptionalValues(sub);
-        ensureWaitLockOptionEverywhere(sub);
-    }
-}
-/**
- * Optional-value flags whose value is a number and therefore never a path.
- * `--canary [path]` is the counter-example that must stay out: its value IS
- * a path.
- */
-const NUMERIC_OPTIONAL_VALUE_FLAGS = new Set([
-    '--wait-lock',
-    '--wait-browser',
-    '--wait-port',
-    '--shuffle',
-]);
-/**
- * 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 function isPathShapedArgument(token) {
-    if (/^\d+(?:\.\d+)?$/.test(token))
-        return false;
-    return token === '.' || token === '..' || /[\\/]/.test(token) || /\.[A-Za-z][\w-]*$/.test(token);
-}
-/**
- * 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 function releasePathShapedValues(argv, requiredValueFlags) {
-    const kept = [];
-    const released = [];
-    let index = 0;
-    for (; index < argv.length; index += 1) {
-        const token = argv[index] ?? '';
-        if (token === '--')
-            break;
-        const next = argv[index + 1];
-        if (requiredValueFlags.has(token) && next !== undefined) {
-            kept.push(token, next);
-            index += 1;
-            continue;
-        }
-        if (NUMERIC_OPTIONAL_VALUE_FLAGS.has(token) &&
-            next !== undefined &&
-            !next.startsWith('-') &&
-            isPathShapedArgument(next)) {
-            released.push(token);
-            continue;
-        }
-        kept.push(token);
-    }
-    return [...kept, ...released, ...argv.slice(index)];
-}
-/**
- * Installs {@link releasePathShapedValues} on `command` when it registers
- * any numeric optional-value flag.
- */
-function releasePathShapedOptionalValues(command) {
-    const flags = command.options.filter((option) => option.long !== undefined && NUMERIC_OPTIONAL_VALUE_FLAGS.has(option.long));
-    if (flags.length === 0)
-        return;
-    const requiredValueFlags = new Set(command.options
-        .filter((option) => option.required)
-        .flatMap((option) => [option.long, option.short])
-        .filter((flag) => flag !== undefined));
-    const parseOptions = command.parseOptions.bind(command);
-    command.parseOptions = (argv) => parseOptions(releasePathShapedValues(argv, requiredValueFlags));
-}
-/**
- * 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 function addWaitLockOption(command) {
-    return command.option('--wait-lock [seconds]', `Wait up to this many seconds (default 60) for another FireForge command to release EVERY lock this command takes, instead of failing on the default budget. Set ${WAIT_LOCK_ENV_VAR} to apply a budget to every command in a session`, commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
-}

package/dist/src/utils/package-root.d.ts

@@ -1,21 +0,0 @@
-interface PackageMetadata {
-    name: string;
-    version: string;
-    bin?: unknown;
-}
-/**
- * Finds the fireforge package root by walking up from the current module.
- *
- * Works from both the source tree (`src/utils/`) and the compiled
- * tree (`dist/src/utils/`) by looking for a `package.json` that exposes
- * the `fireforge` CLI entrypoint, regardless of the npm package scope.
- *
- * The result is cached after the first call since it is deterministic
- * within a process.
- */
-export declare function getPackageRoot(): string;
-/** @internal */
-export declare function isFireForgePackageMetadata(pkg: PackageMetadata): boolean;
-/** Reads the current package version from the repository root package manifest. */
-export declare function getPackageVersion(): string;
-export {};

package/dist/src/utils/package-root.js

@@ -1,70 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { getNodeErrorCode, toError } from './errors.js';
-import { parseObject } from './parse.js';
-import { isObject } from './validation.js';
-function readPackageMetadata(filePath) {
-    const raw = readFileSync(filePath, 'utf-8');
-    const parsed = parseObject(JSON.parse(raw), 'package.json');
-    return { name: parsed.string('name'), version: parsed.string('version'), bin: parsed.raw('bin') };
-}
-let cachedPackageRoot;
-/**
- * Finds the fireforge package root by walking up from the current module.
- *
- * Works from both the source tree (`src/utils/`) and the compiled
- * tree (`dist/src/utils/`) by looking for a `package.json` that exposes
- * the `fireforge` CLI entrypoint, regardless of the npm package scope.
- *
- * The result is cached after the first call since it is deterministic
- * within a process.
- */
-export function getPackageRoot() {
-    if (cachedPackageRoot !== undefined) {
-        return cachedPackageRoot;
-    }
-    let current = dirname(fileURLToPath(import.meta.url));
-    for (;;) {
-        const packagePath = join(current, 'package.json');
-        try {
-            const pkg = readPackageMetadata(packagePath);
-            if (isFireForgePackageMetadata(pkg)) {
-                cachedPackageRoot = current;
-                return current;
-            }
-        }
-        catch (error) {
-            // Absent package.json: keep walking. A package.json that exists but
-            // fails to parse is a different case: walking past it could bind
-            // to a wrong ancestor package (any parent exposing bin.fireforge) or
-            // end in the unhelpful generic "could not locate" error, hiding the
-            // actual syntax problem.
-            const code = getNodeErrorCode(error);
-            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
-                throw new Error(`Found ${packagePath} but could not parse it: ` + toError(error).message, {
-                    cause: error,
-                });
-            }
-        }
-        const parent = dirname(current);
-        if (parent === current) {
-            throw new Error('Could not locate the fireforge package root');
-        }
-        current = parent;
-    }
-}
-/** @internal */
-export function isFireForgePackageMetadata(pkg) {
-    if (!isObject(pkg.bin)) {
-        return false;
-    }
-    const bin = pkg.bin;
-    return typeof bin['fireforge'] === 'string';
-}
-/** Reads the current package version from the repository root package manifest. */
-export function getPackageVersion() {
-    const packageRoot = getPackageRoot();
-    return readPackageMetadata(join(packageRoot, 'package.json')).version;
-}

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

@@ -1,117 +0,0 @@
-/**
- * Lightweight runtime object parsing and field extraction helpers.
- *
- * Reduces repetitive "validate unknown → cast" boilerplate across
- * config validation, manifest parsing, and metadata validation.
- */
-/**
- * A parsed record wrapper that provides typed field extraction
- * with clear error messages. Construct via {@link parseObject}.
- */
-export declare class ParsedRecord {
-    #private;
-    constructor(data: Record<string, unknown>, label: string);
-    /**
-     * Extracts a required string field.
-     * @param key - Field name
-     * @returns The string value
-     * @throws Error if the field is missing or not a string
-     */
-    string(key: string): string;
-    /**
-     * Extracts an optional string field.
-     * @param key - Field name
-     * @returns The string value or undefined
-     * @throws Error if the field is present but not a string
-     */
-    optionalString(key: string): string | undefined;
-    /**
-     * Extracts a required number field.
-     * @param key - Field name
-     * @returns The number value
-     * @throws Error if the field is missing or not a number
-     */
-    number(key: string): number;
-    /**
-     * Extracts an optional number field.
-     * @param key - Field name
-     * @returns The number value or undefined
-     * @throws Error if the field is present but not a number
-     */
-    optionalNumber(key: string): number | undefined;
-    /**
-     * Extracts a required non-negative integer field.
-     * @param key - Field name
-     * @returns The integer value
-     * @throws Error if the field is missing, not a number, or negative
-     */
-    nonNegativeInteger(key: string): number;
-    /**
-     * Extracts an optional non-negative integer field.
-     * @param key - Field name
-     * @returns The integer value or undefined
-     * @throws Error if the field is present but not a non-negative integer
-     */
-    optionalNonNegativeInteger(key: string): number | undefined;
-    /**
-     * Extracts a required string field and validates it against a predicate.
-     * @param key - Field name
-     * @param predicate - Validation function
-     * @param allowed - Description of allowed values for the error message
-     * @returns The validated string value
-     */
-    stringEnum<T extends string>(key: string, predicate: (value: string) => value is T, allowed: string): T;
-    /**
-     * Extracts a required string field and validates it with a custom check.
-     * @param key - Field name
-     * @param check - Validation function returning true if valid
-     * @param constraint - Description of the constraint for the error message
-     * @returns The validated string value
-     */
-    validatedString(key: string, check: (value: string) => boolean, constraint: string): string;
-    /**
-     * Extracts a required array-of-strings field.
-     * @param key - Field name
-     * @returns The string array
-     * @throws Error if the field is missing or not an array of strings
-     */
-    stringArray(key: string): string[];
-    /**
-     * Extracts an optional array-of-strings field.
-     * @param key - Field name
-     * @returns The string array (fresh copy) or undefined when absent
-     * @throws Error if the field is present but not an array of strings
-     */
-    optionalStringArray(key: string): string[] | undefined;
-    /**
-     * Extracts a required nested object field.
-     * @param key - Field name
-     * @returns A new ParsedRecord wrapping the nested object
-     * @throws Error if the field is missing or not an object
-     */
-    object(key: string): ParsedRecord;
-    /**
-     * Extracts an optional nested object field.
-     * @param key - Field name
-     * @returns A new ParsedRecord wrapping the nested object, or undefined
-     * @throws Error if the field is present but not an object
-     */
-    optionalObject(key: string): ParsedRecord | undefined;
-    /**
-     * Returns the raw value of a field without validation.
-     * @param key - Field name
-     */
-    raw(key: string): unknown;
-    /**
-     * Returns all keys in the underlying record.
-     */
-    keys(): string[];
-}
-/**
- * Wraps an unknown value as a ParsedRecord after verifying it is an object.
- * @param data - The unknown value to parse
- * @param label - Label for error messages (e.g. "Config", "patches[0]")
- * @returns A ParsedRecord for typed field extraction
- * @throws Error if data is not a plain object
- */
-export declare function parseObject(data: unknown, label: string): ParsedRecord;