@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/utils/build-info.d.ts

@@ -1,30 +0,0 @@
-/** Source identity of the running build. */
-interface BuildIdentity {
-    shortCommit: string;
-    dirty: boolean;
-    /**
-     * Content hash of the uncommitted diff, present only for a dirty installed
-     * build. Two packs from the same HEAD with different uncommitted content
-     * share `shortCommit` and the `.dirty` marker, so without this they report
-     * byte-identical `--version` strings and a report against
-     * `<semver>+g<sha>.dirty` cannot be traced back to a specific pack. Absent
-     * in a git checkout: identity there comes from live git, and hashing the
-     * full diff on every `--version` call is not worth it.
-     */
-    dirtyHash?: string;
-}
-/** @internal Reads the stamped dist/build-info.json. Null when absent/invalid. */
-export declare function readBuildInfoFile(packageRoot: string): BuildIdentity | null;
-type GitRunner = (args: string[]) => string;
-/** @internal Live git identity of the checkout. Null when git is unusable. */
-export declare function readGitBuildIdentity(runGit?: GitRunner): BuildIdentity | null;
-/**
- * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`. Plain version on
- * null identity. The trailing content hash appears only for a dirty
- * installed build, where `dist/build-info.json` already carries it. Every
- * segment stays valid semver build metadata (dot-separated alphanumerics).
- */
-export declare function formatVersionWithIdentity(version: string, identity: BuildIdentity | null): string;
-/** The `--version` string: semver plus build identity when known. */
-export declare function getCliVersion(): string;
-export {};

package/dist/src/utils/build-info.js

@@ -1,99 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Build identity for `--version`.
- *
- * Distinct builds shipping as the same plain semver leave consumers
- * fingerprinting tarballs by sha256 to know which build a claim was verified
- * against. `--version` reports `<semver>+g<short-sha>[.dirty[.<content-hash>]]`:
- *
- * - In a git checkout (dev runs via tsx), identity comes from live git, so a
- *   stale `dist/build-info.json` from an old build must never win.
- * - In an installed package, it comes from `dist/build-info.json`, stamped
- *   by scripts/generate-build-info.mjs at build/pack time.
- * - When neither yields an identity, `--version` degrades to the plain
- *   semver. Reading identity must never throw.
- *
- * Not wired into the per-patch lint cache key: identity would
- * churn the cache on every commit at the same semver for no correctness gain
- * (`getPackageVersion` stays the cache input).
- */
-import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { getPackageRoot, getPackageVersion } from './package-root.js';
-import { isObject } from './validation.js';
-/** @internal Reads the stamped dist/build-info.json. Null when absent/invalid. */
-export function readBuildInfoFile(packageRoot) {
-    try {
-        const raw = readFileSync(join(packageRoot, 'dist', 'build-info.json'), 'utf-8');
-        const data = JSON.parse(raw);
-        if (!isObject(data) || data['schemaVersion'] !== 1)
-            return null;
-        const shortCommit = data['shortCommit'];
-        const dirty = data['dirty'];
-        if (typeof shortCommit !== 'string' || shortCommit.length === 0)
-            return null;
-        const dirtyHash = data['dirtyHash'];
-        return {
-            shortCommit,
-            dirty: dirty === true,
-            ...(typeof dirtyHash === 'string' && dirtyHash.length > 0 ? { dirtyHash } : {}),
-        };
-    }
-    catch {
-        return null;
-    }
-}
-const defaultGitRunner = (args) => execFileSync('git', args, {
-    cwd: getPackageRoot(),
-    encoding: 'utf-8',
-    stdio: ['ignore', 'pipe', 'ignore'],
-});
-/** @internal Live git identity of the checkout. Null when git is unusable. */
-export function readGitBuildIdentity(runGit = defaultGitRunner) {
-    try {
-        const commit = runGit(['rev-parse', 'HEAD']).trim();
-        if (!/^[0-9a-f]{7,40}$/.test(commit))
-            return null;
-        const status = runGit(['status', '--porcelain']);
-        return { shortCommit: commit.slice(0, 12), dirty: status.length > 0 };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Resolves the running build's identity: live git in a checkout (covers
- * worktrees, whose `.git` is a file), else the stamped build-info file,
- * else null. Never throws.
- */
-function getBuildIdentity() {
-    try {
-        const packageRoot = getPackageRoot();
-        if (existsSync(join(packageRoot, '.git'))) {
-            return readGitBuildIdentity();
-        }
-        return readBuildInfoFile(packageRoot);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`. Plain version on
- * null identity. The trailing content hash appears only for a dirty
- * installed build, where `dist/build-info.json` already carries it. Every
- * segment stays valid semver build metadata (dot-separated alphanumerics).
- */
-export function formatVersionWithIdentity(version, identity) {
-    if (identity === null)
-        return version;
-    if (!identity.dirty)
-        return `${version}+g${identity.shortCommit}`;
-    const contentHash = identity.dirtyHash === undefined ? '' : `.${identity.dirtyHash}`;
-    return `${version}+g${identity.shortCommit}.dirty${contentHash}`;
-}
-/** The `--version` string: semver plus build identity when known. */
-export function getCliVersion() {
-    return formatVersionWithIdentity(getPackageVersion(), getBuildIdentity());
-}

package/dist/src/utils/child-env.d.ts

@@ -1,28 +0,0 @@
-/**
- * Environment construction for spawned children.
- */
-/** The `env` / `envUnset` slice of exec options this module needs. */
-interface ChildEnvOptions {
-    /** Variables to add or overwrite on top of `process.env`. */
-    env?: Record<string, string> | undefined;
-    /** Variables to remove after the merge. */
-    envUnset?: readonly string[] | undefined;
-}
-/**
- * The child's environment: `process.env`, with `env` merged over it, then
- * every `envUnset` key removed.
- *
- * One helper rather than five inline spreads: the removal step is easy to
- * add at four of the five spawn sites and forget at the fifth, which would
- * make the option silently inert exactly where it was not tested.
- *
- * Removal is a real removal rather than an assignment to `''`: mozbuild's
- * `is_running_under_coding_agent()` reads `CLAUDECODE` only for its
- * presence, so an empty value would not unset it. `Reflect.deleteProperty` rather than
- * `delete obj[key]` because the key is computed.
- *
- * @param options - Options carrying `env` / `envUnset`
- * @returns The environment to hand `spawn`
- */
-export declare function buildChildEnv(options: ChildEnvOptions): NodeJS.ProcessEnv;
-export {};

package/dist/src/utils/child-env.js

@@ -1,27 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Environment construction for spawned children.
- */
-/**
- * The child's environment: `process.env`, with `env` merged over it, then
- * every `envUnset` key removed.
- *
- * One helper rather than five inline spreads: the removal step is easy to
- * add at four of the five spawn sites and forget at the fifth, which would
- * make the option silently inert exactly where it was not tested.
- *
- * Removal is a real removal rather than an assignment to `''`: mozbuild's
- * `is_running_under_coding_agent()` reads `CLAUDECODE` only for its
- * presence, so an empty value would not unset it. `Reflect.deleteProperty` rather than
- * `delete obj[key]` because the key is computed.
- *
- * @param options - Options carrying `env` / `envUnset`
- * @returns The environment to hand `spawn`
- */
-export function buildChildEnv(options) {
-    const merged = { ...process.env, ...options.env };
-    for (const key of options.envUnset ?? []) {
-        Reflect.deleteProperty(merged, key);
-    }
-    return merged;
-}

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

@@ -1,8 +0,0 @@
-/**
- * Bounded-concurrency helpers shared by commands that fan out per-file IO
- * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). On failure, stop scheduling new items and await
- * every started operation before rejecting, so callers can safely clean up.
- */
-/** Maps items with at most `limit` in-flight promises. Preserves order. */
-export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/src/utils/concurrency.js

@@ -1,32 +0,0 @@
-/**
- * Bounded-concurrency helpers shared by commands that fan out per-file IO
- * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). On failure, stop scheduling new items and await
- * every started operation before rejecting, so callers can safely clean up.
- */
-/** Maps items with at most `limit` in-flight promises. Preserves order. */
-export async function mapWithConcurrency(items, limit, fn) {
-    if (!Number.isSafeInteger(limit) || limit < 1) {
-        throw new RangeError('Concurrency limit must be a positive integer');
-    }
-    const results = new Array(items.length);
-    let next = 0;
-    const state = {};
-    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-        while (!state.failure) {
-            const index = next++;
-            if (index >= items.length)
-                return;
-            try {
-                results[index] = await fn(items[index], index);
-            }
-            catch (error) {
-                state.failure ??= { error };
-            }
-        }
-    });
-    await Promise.all(workers);
-    if (state.failure)
-        throw state.failure.error;
-    return results;
-}

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

@@ -1,2 +0,0 @@
-/** Returns formatted elapsed time since a start timestamp from Date.now(). */
-export declare function elapsedSince(startedAt: number): string;

package/dist/src/utils/elapsed.js

@@ -1,23 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Formats a duration in milliseconds as `Xm Ys`, or `Ys` under a minute.
- *
- * The single spelling of FireForge's elapsed-time wording: `build` and
- * `package` each hand-rolled the same minute/second split, so a change to
- * the format silently applied to some progress lines and not others.
- *
- * @param ms - Duration in milliseconds. Negative input is clamped to zero.
- * @returns The duration as `Xm Ys`, or `Ys` when under one minute.
- */
-function formatElapsed(ms) {
-    const totalSeconds = Math.max(0, Math.round(ms / 1000));
-    const minutes = Math.floor(totalSeconds / 60);
-    const seconds = totalSeconds % 60;
-    if (minutes === 0)
-        return `${seconds}s`;
-    return `${minutes}m ${seconds}s`;
-}
-/** Returns formatted elapsed time since a start timestamp from Date.now(). */
-export function elapsedSince(startedAt) {
-    return formatElapsed(Date.now() - startedAt);
-}

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

@@ -1,39 +0,0 @@
-/**
- * Throwable normalisation primitives.
- *
- * This module must import nothing. It sits at the very bottom of the
- * dependency graph (81 modules across `core/`, `commands/`, `utils/` and
- * `bin/` reach it), so it is the one place a shared helper can live and be
- * provably cycle-immune. Adding an import here makes that whole subtree
- * reachable from every util, and any future `src/errors/*` module wanting a
- * util back (`errors/git.ts` already carries a mirrored index-lock heuristic
- * that would like `getNodeErrorCode`) then closes the loop and fails the
- * `dpdm --exit-code circular:1` release gate. A helper that needs an import
- * belongs in a sibling leaf module, not here.
- */
-/** Normalizes unknown throwables into an Error instance. */
-export declare function toError(error: unknown): Error;
-/**
- * Extracts a Node errno string (`ENOENT`, `EACCES`, `EPERM`, …) from an
- * unknown throwable, or `undefined` when the value carries no string `code`.
- *
- * The check is structural rather than `error instanceof Error`: a plain
- * object carrying `.code` (exactly the shape {@link toError} exists to
- * normalise) reaches errno consumers through rejected promises and
- * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
- * code".
- */
-export declare function getNodeErrorCode(error: unknown): string | undefined;
-/**
- * Checks whether a process with the given PID is still running, using
- * `kill(pid, 0)`: no signal is sent, only the existence check is performed.
- *
- * Only `ESRCH` ("no such process") means dead. `EPERM` means alive: the
- * process exists but is owned by another uid, which happens routinely with
- * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
- * Reading EPERM as dead in a predicate that gates a recursive delete removes
- * a live build's tree clone or a live furnace lock out from under its owner.
- * Any other errno is treated as "unknown, assume alive", the safe direction
- * for every caller: it refuses rather than destroys.
- */
-export declare function isProcessAlive(pid: number): boolean;

package/dist/src/utils/errors.js

@@ -1,67 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Throwable normalisation primitives.
- *
- * This module must import nothing. It sits at the very bottom of the
- * dependency graph (81 modules across `core/`, `commands/`, `utils/` and
- * `bin/` reach it), so it is the one place a shared helper can live and be
- * provably cycle-immune. Adding an import here makes that whole subtree
- * reachable from every util, and any future `src/errors/*` module wanting a
- * util back (`errors/git.ts` already carries a mirrored index-lock heuristic
- * that would like `getNodeErrorCode`) then closes the loop and fails the
- * `dpdm --exit-code circular:1` release gate. A helper that needs an import
- * belongs in a sibling leaf module, not here.
- */
-/** Normalizes unknown throwables into an Error instance. */
-export function toError(error) {
-    if (error instanceof Error) {
-        return error;
-    }
-    if (typeof error === 'object' &&
-        error !== null &&
-        'message' in error &&
-        typeof error.message === 'string') {
-        return new Error(error.message, { cause: error });
-    }
-    return new Error(typeof error === 'string' ? error : String(error), { cause: error });
-}
-/**
- * Extracts a Node errno string (`ENOENT`, `EACCES`, `EPERM`, …) from an
- * unknown throwable, or `undefined` when the value carries no string `code`.
- *
- * The check is structural rather than `error instanceof Error`: a plain
- * object carrying `.code` (exactly the shape {@link toError} exists to
- * normalise) reaches errno consumers through rejected promises and
- * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
- * code".
- */
-export function getNodeErrorCode(error) {
-    if (typeof error === 'object' &&
-        error !== null &&
-        'code' in error &&
-        typeof error.code === 'string') {
-        return error.code;
-    }
-    return undefined;
-}
-/**
- * Checks whether a process with the given PID is still running, using
- * `kill(pid, 0)`: no signal is sent, only the existence check is performed.
- *
- * Only `ESRCH` ("no such process") means dead. `EPERM` means alive: the
- * process exists but is owned by another uid, which happens routinely with
- * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
- * Reading EPERM as dead in a predicate that gates a recursive delete removes
- * a live build's tree clone or a live furnace lock out from under its owner.
- * Any other errno is treated as "unknown, assume alive", the safe direction
- * for every caller: it refuses rather than destroys.
- */
-export function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return getNodeErrorCode(error) !== 'ESRCH';
-    }
-}

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

@@ -1,113 +0,0 @@
-/**
- * Checks if a path exists.
- * @param path - Path to check
- */
-export declare function pathExists(path: string): Promise<boolean>;
-/**
- * Checks if a path exists while surfacing permission errors.
- * @param path - Path to check
- */
-export declare function pathExistsStrict(path: string): Promise<boolean>;
-/**
- * Ensures a directory exists, creating it recursively if needed.
- * @param path - Directory path to ensure
- */
-export declare function ensureDir(path: string): Promise<void>;
-/**
- * Removes a directory recursively.
- * @param path - Directory path to remove
- */
-export declare function removeDir(path: string): Promise<void>;
-/**
- * Removes a file.
- * @param path - File path to remove
- */
-export declare function removeFile(path: string): Promise<void>;
-/**
- * Returns true when a path exists and is a symbolic link.
- *
- * Uses lstat rather than stat so a symlink to a missing target is still
- * classified as a symlink. That matters for cleanup of stale harness links.
- */
-export declare function isSymlink(path: string): Promise<boolean>;
-/**
- * Copies a file from source to destination.
- * Creates parent directories if needed.
- * @param src - Source file path
- * @param dest - Destination file path
- */
-export declare function copyFile(src: string, dest: string): Promise<void>;
-/**
- * Reads a JSON file and parses it.
- * @param path - Path to JSON file
- * @returns Parsed JSON content
- * @throws Error if file doesn't exist or contains invalid JSON
- */
-export declare function readJson<T>(path: string): Promise<T>;
-/**
- * Writes data to a JSON file with pretty formatting.
- * Creates parent directories if needed.
- * @param path - Path to JSON file
- * @param data - Data to write
- */
-export declare function writeJson(path: string, data: unknown): Promise<void>;
-/**
- * Reads a text file.
- * @param path - Path to text file
- * @returns File content as string
- */
-export declare function readText(path: string): Promise<string>;
-/**
- * Writes text to a file.
- * Creates parent directories if needed.
- * @param path - Path to text file
- * @param content - Content to write
- */
-export declare function writeText(path: string, content: string): Promise<void>;
-/**
- * Writes text to a file only when the content has actually changed.
- * Prevents unnecessary mtime bumps that can trigger downstream rebuilds.
- * @param path - Path to text file
- * @param content - Content to write
- * @returns true if the file was written, false if content was already up to date
- */
-export declare function writeTextIfChanged(path: string, content: string): Promise<boolean>;
-/**
- * Writes content atomically using a temp-file-and-rename strategy.
- * Temp files are created in the destination directory so rename stays atomic.
- * @param path - Destination file path
- * @param content - Content to write. `Uint8Array` rather than `Buffer` so
- *   published types never name a Node global (every `Buffer` still assigns
- *   to it, and `fs.writeFile` accepts both).
- */
-export declare function writeFileAtomic(path: string, content: string | Uint8Array): Promise<void>;
-/**
- * Copies a directory recursively.
- * @param src - Source directory path
- * @param dest - Destination directory path
- */
-export declare function copyDir(src: string, dest: string): Promise<void>;
-/**
- * Matches the atomic-temp-file shape emitted by `createAtomicTempPath`
- * anywhere in a normalised (forward-slash) path. The `.fireforge-tmp-`
- * marker plus a PID/UUID tail is unique to our own rename-based atomic
- * writes, so callers (notably `status`) can filter these mid-flight
- * artefacts out of their listings without racing the rename.
- *
- * Intentionally anchored so a legitimately-named backup file like
- * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is not treated
- * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
- */
-export declare const FIREFORGE_TMP_PATH_PATTERN: RegExp;
-/**
- * Checks available disk space at a path and warns via the provided
- * callback when it falls below `minBytes`.
- *
- * @param path - Directory to check (must exist)
- * @param minBytes - Minimum free bytes before emitting a warning
- * @param onLowSpace - Callback invoked with a human-readable message
- *   when available space is below the threshold
- * @returns The available bytes, or `undefined` when the check could not
- *   be performed (unsupported platform, permission error, etc.)
- */
-export declare function checkDiskSpace(path: string, minBytes: number, onLowSpace: (message: string) => void): Promise<number | undefined>;