@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/utils/fs.js

@@ -1,337 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { randomUUID } from 'node:crypto';
-import { access, chmod, copyFile as fsCopyFile, lstat, mkdir, open, readdir, readFile, rename, rm, stat, statfs, } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
-import { getNodeErrorCode } from './errors.js';
-import { sleep } from './sleep.js';
-const RETRIABLE_REMOVE_ERRORS = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM']);
-const RETRIABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
-/**
- * Checks if a path exists.
- * @param path - Path to check
- */
-export async function pathExists(path) {
-    try {
-        await access(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Checks if a path exists while surfacing permission errors.
- * @param path - Path to check
- */
-export async function pathExistsStrict(path) {
-    try {
-        await access(path);
-        return true;
-    }
-    catch (error) {
-        const code = getNodeErrorCode(error);
-        if (code === 'ENOENT') {
-            return false;
-        }
-        throw error;
-    }
-}
-/**
- * Ensures a directory exists, creating it recursively if needed.
- * @param path - Directory path to ensure
- */
-export async function ensureDir(path) {
-    await mkdir(path, { recursive: true });
-}
-/**
- * Ensures the parent directory of a file exists.
- * @param filePath - Path to a file
- */
-async function ensureParentDir(filePath) {
-    const parent = dirname(filePath);
-    await ensureDir(parent);
-}
-/**
- * Removes a directory recursively.
- * @param path - Directory path to remove
- */
-export async function removeDir(path) {
-    for (let attempt = 0; attempt < 5; attempt++) {
-        try {
-            await rm(path, { recursive: true, force: true });
-            return;
-        }
-        catch (error) {
-            const code = getNodeErrorCode(error);
-            if (!code || !RETRIABLE_REMOVE_ERRORS.has(code) || attempt === 4) {
-                throw error;
-            }
-            await sleep(50 * (attempt + 1));
-        }
-    }
-}
-/**
- * Removes a file.
- * @param path - File path to remove
- */
-export async function removeFile(path) {
-    await rm(path, { force: true });
-}
-/**
- * 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 async function isSymlink(path) {
-    try {
-        return (await lstat(path)).isSymbolicLink();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Copies a file from source to destination.
- * Creates parent directories if needed.
- * @param src - Source file path
- * @param dest - Destination file path
- */
-export async function copyFile(src, dest) {
-    await ensureParentDir(dest);
-    // Never follow a destination symlink or truncate a shared hardlink:
-    // build/deploy copies must not write through into components/ or a peer.
-    const tempPath = createAtomicTempPath(dest);
-    try {
-        await fsCopyFile(src, tempPath);
-        await renameWithRetries(tempPath, dest);
-        await syncParentDir(dest);
-    }
-    finally {
-        await rm(tempPath, { force: true });
-    }
-}
-/**
- * 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 async function readJson(path) {
-    const content = await readFile(path, 'utf-8');
-    return JSON.parse(content, (key, value) => key === '__proto__' || key === 'constructor' || key === 'prototype' ? undefined : value);
-}
-/**
- * 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 async function writeJson(path, data) {
-    const content = JSON.stringify(data, null, 2) + '\n';
-    await writeText(path, content);
-}
-/**
- * Reads a text file.
- * @param path - Path to text file
- * @returns File content as string
- */
-export async function readText(path) {
-    return readFile(path, 'utf-8');
-}
-/**
- * Writes text to a file.
- * Creates parent directories if needed.
- * @param path - Path to text file
- * @param content - Content to write
- */
-export async function writeText(path, content) {
-    await writeFileAtomic(path, content);
-}
-/**
- * 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 async function writeTextIfChanged(path, content) {
-    if (await pathExists(path)) {
-        const existing = await readText(path);
-        if (existing === content) {
-            return false;
-        }
-    }
-    await writeText(path, content);
-    return true;
-}
-/**
- * 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 async function writeFileAtomic(path, content) {
-    await ensureParentDir(path);
-    let existingMode;
-    try {
-        existingMode = (await stat(path)).mode;
-    }
-    catch (error) {
-        const code = getNodeErrorCode(error);
-        if (code !== 'ENOENT') {
-            throw error;
-        }
-    }
-    const tempPath = createAtomicTempPath(path);
-    const handle = await open(tempPath, 'w');
-    try {
-        await handle.writeFile(content);
-        await handle.sync();
-    }
-    catch (error) {
-        await handle.close();
-        await rm(tempPath, { force: true });
-        throw error;
-    }
-    await handle.close();
-    try {
-        if (existingMode !== undefined) {
-            await chmod(tempPath, existingMode);
-        }
-        await renameWithRetries(tempPath, path);
-        await syncParentDir(path);
-    }
-    catch (error) {
-        await rm(tempPath, { force: true });
-        throw error;
-    }
-}
-/**
- * Renames the temp file over its destination, retrying transient sharing
- * violations. On Windows, a rename onto a target that another writer is
- * concurrently replacing (or that an antivirus/indexer briefly holds open)
- * fails with EPERM/EACCES/EBUSY even though the same rename succeeds a moment
- * later. POSIX renames never hit this. Non-retriable codes and exhausted
- * budgets rethrow, so a genuine permission problem still surfaces.
- */
-async function renameWithRetries(from, to) {
-    for (let attempt = 0;; attempt++) {
-        try {
-            await rename(from, to);
-            return;
-        }
-        catch (error) {
-            const code = getNodeErrorCode(error);
-            if (!code || !RETRIABLE_RENAME_ERRORS.has(code) || attempt === 4) {
-                throw error;
-            }
-            await sleep(25 * (attempt + 1));
-        }
-    }
-}
-async function syncParentDir(path) {
-    let directoryHandle;
-    try {
-        directoryHandle = await open(dirname(path), 'r');
-        await directoryHandle.sync();
-    }
-    catch {
-        // Best-effort durability: a directory that cannot be opened or fsynced
-        // (network mounts, Windows) must not fail the write it was protecting.
-    }
-    finally {
-        try {
-            await directoryHandle?.close();
-        }
-        catch {
-            // Nothing left to do. The handle is being discarded either way.
-        }
-    }
-}
-/**
- * Copies a directory recursively.
- * @param src - Source directory path
- * @param dest - Destination directory path
- */
-export async function copyDir(src, dest) {
-    await ensureDir(dest);
-    const entries = await readdir(src, { withFileTypes: true });
-    for (const entry of entries) {
-        const srcPath = join(src, entry.name);
-        const destPath = join(dest, entry.name);
-        if (entry.isSymbolicLink()) {
-            // Skip symlinks to avoid circular recursion and symlink attacks
-            continue;
-        }
-        if (entry.isDirectory()) {
-            await copyDir(srcPath, destPath);
-        }
-        else {
-            await fsCopyFile(srcPath, destPath);
-        }
-    }
-}
-/**
- * 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 const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9a-f-]{36}$/i;
-/**
- * Generates a unique temp file path for atomic writes.
- *
- * Each invocation gets its own path via PID + UUID, so concurrent writers
- * targeting the same destination never interfere with each other. Cleanup of
- * the temp file is the caller's responsibility on error. We intentionally do
- * not glob-delete peer temp files here to avoid racing with other writers.
- */
-function createAtomicTempPath(path) {
-    const directory = dirname(path);
-    // basename, not slice(dirname.length + 1): when dirname ends with the
-    // separator (filesystem/drive roots, e.g. dirname('/foo') === '/'), the
-    // slice arithmetic chopped the first filename character ('/foo' → 'oo').
-    const filename = basename(path);
-    return join(directory, `.${filename}.fireforge-tmp-${process.pid}-${randomUUID()}`);
-}
-/**
- * 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 async function checkDiskSpace(path, minBytes, onLowSpace) {
-    try {
-        const stats = await statfs(path);
-        // bavail = blocks available to UNPRIVILEGED users. bfree includes the
-        // root-reserved blocks (typically 5% on ext4), so it over-reported free
-        // space and silently suppressed the low-space warning exactly when it
-        // mattered.
-        const availableBytes = stats.bavail * stats.bsize;
-        if (availableBytes < minBytes) {
-            const availableGB = (availableBytes / (1024 * 1024 * 1024)).toFixed(1);
-            const requiredGB = (minBytes / (1024 * 1024 * 1024)).toFixed(1);
-            onLowSpace(`Low disk space: ${availableGB} GB available, ${requiredGB} GB recommended. ` +
-                'The operation may fail if the disk fills up.');
-        }
-        return availableBytes;
-    }
-    catch {
-        // statfs may not be available on all platforms or the path may
-        // not exist yet, so silently degrade rather than blocking the operation.
-        return undefined;
-    }
-}

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

@@ -1,12 +0,0 @@
-/**
- * Computes the hexadecimal SHA-256 digest of a string or buffer.
- *
- * Eleven sites across `src/core/` inlined the same
- * `createHash('sha256').update(input).digest('hex')` chain for cache keys,
- * fingerprints and content addresses. They all share this helper instead, so
- * the digest algorithm and encoding are decided in exactly one place.
- *
- * @param input - Data to digest, as a UTF-8 string or a raw buffer.
- * @returns The 64-character lowercase hexadecimal digest.
- */
-export declare function sha256Hex(input: string | Buffer): string;

package/dist/src/utils/hash.js

@@ -1,16 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { createHash } from 'node:crypto';
-/**
- * Computes the hexadecimal SHA-256 digest of a string or buffer.
- *
- * Eleven sites across `src/core/` inlined the same
- * `createHash('sha256').update(input).digest('hex')` chain for cache keys,
- * fingerprints and content addresses. They all share this helper instead, so
- * the digest algorithm and encoding are decided in exactly one place.
- *
- * @param input - Data to digest, as a UTF-8 string or a raw buffer.
- * @returns The 64-character lowercase hexadecimal digest.
- */
-export function sha256Hex(input) {
-    return createHash('sha256').update(input).digest('hex');
-}

package/dist/src/utils/line-dispatch.d.ts

@@ -1,15 +0,0 @@
-/**
- * Line splitting for the smoke-run stream dispatch in `process.ts`. Kept as
- * a sibling so the exec module stays within its size budget. The contract
- * (terminators, partial-line cap) is documented on the function.
- */
-/**
- * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
- * `\n`, `\r\n`, and lone `\r` as line terminators. The lone-`\r` case
- * matters for progress-bar style output (mach, cargo) that repaints a line
- * with carriage returns and never sends a newline, which otherwise
- * accumulates indefinitely. A single trailing `\r` is held back since it may
- * be the first half of a `\r\n` pair split across chunks. Returns the
- * remaining partial line. Callers keep accumulating into it.
- */
-export declare function dispatchCompleteLines(buffer: string, cb: ((line: string) => void) | undefined): string;

package/dist/src/utils/line-dispatch.js

@@ -1,48 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Line splitting for the smoke-run stream dispatch in `process.ts`. Kept as
- * a sibling so the exec module stays within its size budget. The contract
- * (terminators, partial-line cap) is documented on the function.
- */
-/**
- * Cap on the partial-line tail kept between chunks. A child emitting one
- * enormous line with no terminator (minified JS dumped to stderr, a raw
- * binary blob) would otherwise grow the buffer without bound: the 50 MB cap
- * guards the collector, not these line buffers. When the tail exceeds the
- * cap it is dispatched as a synthetic (oversized) line so the matchers still
- * see its content, then the buffer resets.
- */
-const MAX_PARTIAL_LINE_SIZE = 1024 * 1024;
-/**
- * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
- * `\n`, `\r\n`, and lone `\r` as line terminators. The lone-`\r` case
- * matters for progress-bar style output (mach, cargo) that repaints a line
- * with carriage returns and never sends a newline, which otherwise
- * accumulates indefinitely. A single trailing `\r` is held back since it may
- * be the first half of a `\r\n` pair split across chunks. Returns the
- * remaining partial line. Callers keep accumulating into it.
- */
-export function dispatchCompleteLines(buffer, cb) {
-    let searchFrom = 0;
-    for (;;) {
-        const nl = buffer.indexOf('\n', searchFrom);
-        const cr = buffer.indexOf('\r', searchFrom);
-        const idx = nl === -1 ? cr : cr === -1 ? nl : Math.min(nl, cr);
-        if (idx === -1)
-            break;
-        if (buffer[idx] === '\r' && idx === buffer.length - 1) {
-            // Possible first half of a chunk-split \r\n, so wait for the next chunk.
-            break;
-        }
-        const line = buffer.slice(0, idx);
-        const terminatorLength = buffer[idx] === '\r' && buffer[idx + 1] === '\n' ? 2 : 1;
-        buffer = buffer.slice(idx + terminatorLength);
-        searchFrom = 0;
-        cb?.(line);
-    }
-    if (buffer.length > MAX_PARTIAL_LINE_SIZE) {
-        cb?.(buffer);
-        return '';
-    }
-    return buffer;
-}

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

@@ -1,109 +0,0 @@
-/**
- * Enables or disables verbose mode.
- * @param enabled - Whether to enable verbose output
- */
-export declare function setVerbose(enabled: boolean): void;
-/**
- * Switches the logger into (or out of) machine-output mode. Commands with
- * `--json`/`--raw` flags call this before producing any output.
- */
-export declare function setMachineOutputMode(enabled: boolean): void;
-/** True when machine-output mode is active. */
-export declare function isMachineOutputMode(): boolean;
-/** Seals (or unseals) stdout after a machine-readable final line. */
-export declare function setStdoutSealed(sealed: boolean): void;
-/**
- * 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 declare function isStdoutSealed(): boolean;
-/**
- * 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 declare function isVerbose(): boolean;
-/**
- * Displays a verbose/debug message (only shown if verbose mode is enabled).
- * @param message - Message to display
- */
-export declare function verbose(message: string): void;
-/**
- * Handle returned by the spinner function.
- */
-export interface SpinnerHandle {
-    /** Update the spinner message */
-    message: (msg: string) => void;
-    /** Stop the spinner with a success message */
-    stop: (msg?: string) => void;
-    /** Stop the spinner with an error message */
-    error: (msg?: string) => void;
-}
-/** Displays the top-level intro banner for a command. */
-export declare function intro(message: string): void;
-/** Displays the closing outro banner for a command. */
-export declare function outro(message: string): void;
-/** Logs an informational message. */
-export declare function info(message: string): void;
-/** Logs a success message. */
-export declare function success(message: string): void;
-/** Logs a warning message. */
-export declare function warn(message: string): void;
-/**
- * Prefix that marks a line as FireForge's own explanatory output rather
- * than a defect. Kept greppable so downstream filters can whitelist it.
- */
-export declare 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 declare function notice(message: string): void;
-/** Logs an error message. */
-export declare function error(message: string): void;
-/** Logs an in-progress step message. */
-export declare function step(message: string): void;
-/** Logs a plain message without a status prefix. */
-export declare function message(message: string): void;
-/** Formats text using the success color without logging it. */
-export declare function formatSuccessText(message: string): string;
-/** Formats text using the error color without logging it. */
-export declare function formatErrorText(message: string): string;
-/**
- * Creates a spinner for long-running operations.
- * @param initialMessage - Initial message to display
- * @returns Spinner handle with message(), stop(), and error() methods
- */
-export declare function spinner(initialMessage: string): SpinnerHandle;
-/** Emits a cancellation message. */
-export declare function cancel(message: string): void;
-/**
- * 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 declare function isCancel(value: unknown): value is symbol;
-/** Displays a titled note block for follow-up details. */
-export declare function note(message: string, title?: string): void;