@hominis/fireforge 0.9.0

package/dist/src/types/index.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Re-exports all type definitions.
+ */
+export {};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,2 @@
+/** Normalizes unknown throwables into an Error instance. */
+export declare function toError(error: unknown): Error;

package/dist/src/utils/errors.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** 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 });
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,72 @@
+/**
+ * Checks if a path exists.
+ * @param path - Path to check
+ */
+export declare function pathExists(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>;
+/**
+ * Ensures the parent directory of a file exists.
+ * @param filePath - Path to a file
+ */
+export declare function ensureParentDir(filePath: 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>;
+/**
+ * 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 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
+ */
+export declare function writeFileAtomic(path: string, content: string | Buffer): 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>;

package/dist/src/utils/fs.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { randomUUID } from 'node:crypto';
+import { access, copyFile as fsCopyFile, mkdir, open, readdir, readFile, rename, rm, } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const RETRIABLE_REMOVE_ERRORS = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM']);
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Checks if a path exists.
+ * @param path - Path to check
+ */
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (error) {
+        void error;
+        return false;
+    }
+}
+/**
+ * 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
+ */
+export 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 = error instanceof Error && 'code' in error && typeof error.code === 'string'
+                ? error.code
+                : undefined;
+            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 });
+}
+/**
+ * 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);
+    await fsCopyFile(src, dest);
+}
+/**
+ * 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 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
+ */
+export async function writeFileAtomic(path, content) {
+    await ensureParentDir(path);
+    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 {
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true });
+        throw error;
+    }
+}
+/**
+ * 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);
+        }
+    }
+}
+/**
+ * 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);
+    const filename = path.slice(directory.length + 1);
+    return join(directory, `.${filename}.fireforge-tmp-${process.pid}-${randomUUID()}`);
+}
+//# sourceMappingURL=fs.js.map

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

@@ -0,0 +1,58 @@
+/**
+ * Enables or disables verbose mode.
+ * @param enabled - Whether to enable verbose output
+ */
+export declare function setVerbose(enabled: boolean): void;
+/**
+ * Checks if verbose mode is enabled.
+ * @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;
+/** 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. */
+export declare function isCancel(value: unknown): boolean;
+/** Displays a titled note block for follow-up details. */
+export declare function note(message: string, title?: string): void;

package/dist/src/utils/logger.js

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: EUPL-1.2
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+/** Whether verbose mode is enabled */
+let verboseMode = false;
+/**
+ * Enables or disables verbose mode.
+ * @param enabled - Whether to enable verbose output
+ */
+export function setVerbose(enabled) {
+    verboseMode = enabled;
+}
+/**
+ * Checks if verbose mode is enabled.
+ * @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 (verboseMode) {
+        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) {
+    p.intro(message);
+}
+/** Displays the closing outro banner for a command. */
+export function outro(message) {
+    p.outro(message);
+}
+/** Logs an informational message. */
+export function info(message) {
+    p.log.info(message);
+}
+/** Logs a success message. */
+export function success(message) {
+    p.log.success(message);
+}
+/** Logs a warning message. */
+export function warn(message) {
+    p.log.warn(message);
+}
+/** Logs an error message. */
+export function error(message) {
+    p.log.error(message);
+}
+/** Logs an in-progress step message. */
+export function step(message) {
+    p.log.step(message);
+}
+/** Logs a plain message without a status prefix. */
+export function message(message) {
+    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 (!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) {
+    p.cancel(message);
+}
+/** Checks whether a prompt result represents a user cancellation. */
+export function isCancel(value) {
+    return p.isCancel(value);
+}
+/** Displays a titled note block for follow-up details. */
+export function note(message, title) {
+    p.note(message, title);
+}
+//# sourceMappingURL=logger.js.map

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

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export declare function pickDefined<T extends Record<string, unknown>>(obj: T): {
+    [K in keyof T]+?: Exclude<T[K], undefined>;
+};

package/dist/src/utils/options.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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.
+ */
+export function pickDefined(obj) {
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        if (obj[key] !== undefined) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=options.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * 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` whose
+ * `name` field is `"@hominis/fireforge"`.
+ */
+export declare function getPackageRoot(): string;
+/** Reads the current package version from the repository root package manifest. */
+export declare function getPackageVersion(): string;

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

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function validatePackageMetadata(data, filePath) {
+    if (typeof data !== 'object' || data === null) {
+        throw new Error(`Invalid package metadata in ${filePath}: expected an object`);
+    }
+    const name = 'name' in data ? data.name : undefined;
+    const version = 'version' in data ? data.version : undefined;
+    if (typeof name !== 'string' || typeof version !== 'string') {
+        throw new Error(`Invalid package metadata in ${filePath}: expected string "name" and "version" fields`);
+    }
+    return { name, version };
+}
+function readPackageMetadata(filePath) {
+    const raw = readFileSync(filePath, 'utf-8');
+    return validatePackageMetadata(JSON.parse(raw), filePath);
+}
+/**
+ * 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` whose
+ * `name` field is `"@hominis/fireforge"`.
+ */
+export function getPackageRoot() {
+    let current = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        try {
+            const packagePath = join(current, 'package.json');
+            const pkg = readPackageMetadata(packagePath);
+            if (pkg.name === '@hominis/fireforge') {
+                return current;
+            }
+        }
+        catch (error) {
+            void error;
+            // no package.json here — keep walking
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new Error('Could not locate the fireforge package root');
+        }
+        current = parent;
+    }
+}
+/** Reads the current package version from the repository root package manifest. */
+export function getPackageVersion() {
+    const packageRoot = getPackageRoot();
+    return readPackageMetadata(join(packageRoot, 'package.json')).version;
+}
+//# sourceMappingURL=package-root.js.map

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

@@ -0,0 +1,110 @@
+/**
+ * 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 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;