@hominis/fireforge 0.9.0

package/dist/src/core/branding.js

@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { FireForgeError } from '../errors/base.js';
+import { ExitCode } from '../errors/codes.js';
+import { copyDir, pathExists, readText, writeText } from '../utils/fs.js';
+import { warn } from '../utils/logger.js';
+/**
+ * Error thrown when branding operations fail.
+ */
+export class BrandingError extends FireForgeError {
+    code = ExitCode.PATCH_ERROR;
+    get userMessage() {
+        return `Branding Error: ${this.message}\n\nBranding is required to set MOZ_APP_VENDOR, MOZ_MACBUNDLE_ID, and other Firefox identity values.`;
+    }
+}
+/**
+ * Sets up the custom branding directory for the browser.
+ *
+ * This creates a branding directory based on Firefox's unofficial branding,
+ * with customized values for:
+ * - configure.sh: MOZ_APP_DISPLAYNAME, MOZ_MACBUNDLE_ID
+ * - brand.properties: brandShorterName, brandShortName, brandFullName
+ * - brand.ftl: -brand-shorter-name, -brand-short-name, etc.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param config - Branding configuration
+ */
+export async function setupBranding(engineDir, config) {
+    const brandingDir = join(engineDir, 'browser', 'branding', config.binaryName);
+    const unofficialDir = join(engineDir, 'browser', 'branding', 'unofficial');
+    // Check if unofficial branding exists as our base
+    if (!(await pathExists(unofficialDir))) {
+        throw new BrandingError(`Unofficial branding directory not found at ${unofficialDir}`);
+    }
+    // Copy unofficial branding as base (if our branding doesn't exist yet)
+    if (!(await pathExists(brandingDir))) {
+        await copyDir(unofficialDir, brandingDir);
+    }
+    // Create/update configure.sh with custom values
+    await createConfigureScript(brandingDir, config);
+    // Update localization files
+    await updateBrandProperties(brandingDir, config);
+    await updateBrandFtl(brandingDir, config);
+    // Patch moz.configure for MOZ_APP_VENDOR
+    await patchMozConfigure(engineDir, config);
+}
+/**
+ * Creates the branding configure.sh script.
+ */
+async function createConfigureScript(brandingDir, config) {
+    const configureShPath = join(brandingDir, 'configure.sh');
+    await writeText(configureShPath, buildConfigureScriptContent(config));
+}
+function buildConfigureScriptContent(config) {
+    return `# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+MOZ_APP_DISPLAYNAME="${escapeShellValue(config.name)}"
+MOZ_MACBUNDLE_ID="${escapeShellValue(config.appId)}"
+`;
+}
+/**
+ * Updates the brand.properties localization file.
+ */
+async function updateBrandProperties(brandingDir, config) {
+    const propsPath = join(brandingDir, 'locales', 'en-US', 'brand.properties');
+    if (!(await pathExists(propsPath))) {
+        warn('brand.properties not found in branding directory — browser will use default strings');
+        return;
+    }
+    await writeText(propsPath, buildBrandPropertiesContent(config));
+}
+function buildBrandPropertiesContent(config) {
+    return `# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+brandShorterName=${escapePropertiesValue(config.name)}
+brandShortName=${escapePropertiesValue(config.name)}
+brandFullName=${escapePropertiesValue(config.name)}
+`;
+}
+/**
+ * Updates the brand.ftl localization file.
+ */
+async function updateBrandFtl(brandingDir, config) {
+    const ftlPath = join(brandingDir, 'locales', 'en-US', 'brand.ftl');
+    if (!(await pathExists(ftlPath))) {
+        warn('brand.ftl not found in branding directory — browser will use default strings');
+        return;
+    }
+    await writeText(ftlPath, buildBrandFtlContent(config));
+}
+function buildBrandFtlContent(config) {
+    return `# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+## Brand names
+##
+## These brand names can be used in messages.
+
+-brand-shorter-name = ${escapeFtlValue(config.name)}
+-brand-short-name = ${escapeFtlValue(config.name)}
+-brand-shortcut-name = ${escapeFtlValue(config.name)}
+-brand-full-name = ${escapeFtlValue(config.name)}
+-brand-product-name = ${escapeFtlValue(config.name)}
+-vendor-short-name = ${escapeFtlValue(config.vendor)}
+trademarkInfo = { " " }
+`;
+}
+/**
+ * Patches browser/moz.configure to set custom vendor.
+ *
+ * Mozilla's build system requires MOZ_APP_VENDOR to be set via imply_option
+ * in moz.configure, not through mozconfig.
+ */
+async function patchMozConfigure(engineDir, config) {
+    const mozConfigurePath = join(engineDir, 'browser', 'moz.configure');
+    if (!(await pathExists(mozConfigurePath))) {
+        throw new BrandingError(`browser/moz.configure not found at ${mozConfigurePath}`);
+    }
+    let content = await readText(mozConfigurePath);
+    // Replace MOZ_APP_VENDOR imply_option
+    const vendorRegex = /imply_option\("MOZ_APP_VENDOR",\s*"[^"]*"\)/;
+    if (!vendorRegex.test(content)) {
+        throw new BrandingError('Could not find MOZ_APP_VENDOR imply_option in browser/moz.configure');
+    }
+    content = content.replace(vendorRegex, buildMozConfigureVendorLine(config));
+    await writeText(mozConfigurePath, content);
+}
+function buildMozConfigureVendorLine(config) {
+    return `imply_option("MOZ_APP_VENDOR", "${escapeString(config.vendor)}")`;
+}
+/**
+ * Escapes a string for use in Python/configure file.
+ */
+function escapeString(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+}
+/**
+ * Escapes a string for use inside a shell double-quoted context.
+ * Prevents command injection via $, backticks, !, and escape sequences.
+ */
+function escapeShellValue(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\$/g, '\\$')
+        .replace(/`/g, '\\`')
+        .replace(/!/g, '\\!');
+}
+/**
+ * Escapes a string for use in .properties file values.
+ * Prevents key/value injection via = and : delimiters.
+ */
+function escapePropertiesValue(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+}
+/**
+ * Escapes a string for use in Fluent (.ftl) file values.
+ * Prevents placeables injection via { and }.
+ */
+function escapeFtlValue(value) {
+    return value.replace(/\\/g, '\\\\').replace(/\{/g, '\\{').replace(/\}/g, '\\}');
+}
+/**
+ * Checks if branding has been set up for the given configuration.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param config - Branding configuration to check for
+ * @returns true if branding is already set up
+ */
+export async function isBrandingSetup(engineDir, config) {
+    const brandingDir = join(engineDir, 'browser', 'branding', config.binaryName);
+    const configureShPath = join(brandingDir, 'configure.sh');
+    const propsPath = join(brandingDir, 'locales', 'en-US', 'brand.properties');
+    const ftlPath = join(brandingDir, 'locales', 'en-US', 'brand.ftl');
+    const mozConfigurePath = join(engineDir, 'browser', 'moz.configure');
+    if (!(await pathExists(configureShPath))) {
+        return false;
+    }
+    const configureContent = await readText(configureShPath);
+    if (configureContent !== buildConfigureScriptContent(config)) {
+        return false;
+    }
+    if (await pathExists(propsPath)) {
+        const propsContent = await readText(propsPath);
+        if (propsContent !== buildBrandPropertiesContent(config)) {
+            return false;
+        }
+    }
+    if (await pathExists(ftlPath)) {
+        const ftlContent = await readText(ftlPath);
+        if (ftlContent !== buildBrandFtlContent(config)) {
+            return false;
+        }
+    }
+    if (!(await pathExists(mozConfigurePath))) {
+        return false;
+    }
+    const mozConfigureContent = await readText(mozConfigurePath);
+    return mozConfigureContent.includes(buildMozConfigureVendorLine(config));
+}
+/**
+ * Checks whether a file path belongs to the tool-managed branding directory.
+ * @param file - File path (relative to engine root)
+ * @param binaryName - The configured binary name (used as branding directory name)
+ * @returns true if the path is managed by branding tooling
+ */
+export function isBrandingManagedPath(file, binaryName) {
+    const normalized = file.replace(/\\/g, '/');
+    const brandingRoot = `browser/branding/${binaryName}`;
+    return (normalized === 'browser/moz.configure' ||
+        normalized === brandingRoot ||
+        normalized === `${brandingRoot}/` ||
+        normalized.startsWith(`${brandingRoot}/`));
+}
+//# sourceMappingURL=branding.js.map

package/dist/src/core/browser-wire.d.ts

@@ -0,0 +1,40 @@
+import type { RegisterResult } from './manifest-register.js';
+export declare const DEFAULT_BROWSER_SUBSCRIPT_DIR = "browser/base/content";
+/**
+ * Result of a wire operation.
+ */
+export interface WireResult {
+    /** Whether the subscript was added to browser-main.js */
+    subscriptAdded: boolean;
+    /** Whether the init expression was added to browser-init.js */
+    initAdded: boolean;
+    /** Whether the destroy expression was added to browser-init.js */
+    destroyAdded: boolean;
+    /** Whether the DOM fragment was inserted into browser.xhtml */
+    domInserted: boolean;
+    /** Result of jar.mn registration */
+    jarMnResult: RegisterResult;
+}
+export interface WireOptions {
+    /** Init expression to add to browser-init.js onLoad() */
+    init?: string | undefined;
+    /** Destroy expression to add to browser-init.js onUnload() */
+    destroy?: string | undefined;
+    /** Path to `.inc.xhtml` file relative to engine root */
+    domFilePath?: string | undefined;
+    /** Dry run — don't write any files */
+    dryRun?: boolean | undefined;
+    /** Insert init block after the block containing this name */
+    after?: string | undefined;
+    /** Subscript directory relative to engine/ (default: "browser/base/content") */
+    subscriptDir?: string | undefined;
+}
+/**
+ * Wires a chrome subscript into the browser.
+ *
+ * @param root - Project root directory
+ * @param name - Subscript name (without .js extension)
+ * @param options - Wire options
+ * @returns Wire result
+ */
+export declare function wireSubscript(root: string, name: string, options?: WireOptions): Promise<WireResult>;

package/dist/src/core/browser-wire.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join, relative } from 'node:path';
+import { toRootRelativePath } from '../utils/paths.js';
+import { getProjectPaths } from './config.js';
+import { registerBrowserContent } from './manifest-register.js';
+import { addDestroyToBrowserInit, addDomFragment, addInitToBrowserInit, addSubscriptToBrowserMain, } from './wire-targets.js';
+export const DEFAULT_BROWSER_SUBSCRIPT_DIR = 'browser/base/content';
+const BROWSER_BASE_DIR = 'browser/base';
+/**
+ * Wires a chrome subscript into the browser.
+ *
+ * @param root - Project root directory
+ * @param name - Subscript name (without .js extension)
+ * @param options - Wire options
+ * @returns Wire result
+ */
+export async function wireSubscript(root, name, options = {}) {
+    const { engine: engineDir } = getProjectPaths(root);
+    const subscriptDir = toRootRelativePath(engineDir, options.subscriptDir ?? DEFAULT_BROWSER_SUBSCRIPT_DIR);
+    // Compute jar.mn source path relative to browser/base/
+    let jarMnSourcePath;
+    if (subscriptDir !== DEFAULT_BROWSER_SUBSCRIPT_DIR) {
+        const relPath = relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)).replace(/\\/g, '/');
+        jarMnSourcePath = `${relPath}/${name}.js`;
+    }
+    if (options.dryRun) {
+        return {
+            subscriptAdded: true,
+            initAdded: !!options.init,
+            destroyAdded: !!options.destroy,
+            domInserted: !!options.domFilePath,
+            jarMnResult: {
+                manifest: 'browser/base/jar.mn',
+                entry: `[dry-run] Would register content/browser/${name}.js`,
+                skipped: false,
+            },
+        };
+    }
+    // 1. Add subscript to browser-main.js
+    const subscriptAdded = await addSubscriptToBrowserMain(engineDir, name);
+    // 2. Add init expression to browser-init.js (if provided)
+    let initAdded = false;
+    if (options.init) {
+        initAdded = await addInitToBrowserInit(engineDir, options.init, options.after);
+    }
+    // 3. Add destroy expression to browser-init.js onUnload() (if provided)
+    let destroyAdded = false;
+    if (options.destroy) {
+        destroyAdded = await addDestroyToBrowserInit(engineDir, options.destroy);
+    }
+    // 4. Add #include directive to browser.xhtml (if provided)
+    let domInserted = false;
+    if (options.domFilePath) {
+        domInserted = await addDomFragment(engineDir, toRootRelativePath(engineDir, options.domFilePath));
+    }
+    // 5. Register in jar.mn
+    const jarMnResult = await registerBrowserContent(engineDir, `${name}.js`, undefined, jarMnSourcePath);
+    return {
+        subscriptAdded,
+        initAdded,
+        destroyAdded,
+        domInserted,
+        jarMnResult,
+    };
+}
+//# sourceMappingURL=browser-wire.js.map

package/dist/src/core/build-prepare.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared pre-flight logic for build and package commands:
+ * story cleanup, branding setup, Furnace component application, and mozconfig generation.
+ */
+import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
+/**
+ * Result of the build preparation phase.
+ */
+export interface BuildPreparation {
+    /** Number of Furnace components applied (0 if none or no furnace.json) */
+    furnaceApplied: number;
+}
+/**
+ * Runs the shared pre-flight steps for build and package commands:
+ * 1. Cleans Furnace stories from engine (prevents leaking into production)
+ * 2. Sets up branding directory if not already done
+ * 3. Applies Furnace components if furnace.json exists
+ * 4. Generates mozconfig
+ *
+ * @param projectRoot - Root directory of the project
+ * @param paths - Resolved project paths
+ * @param config - Loaded FireForge configuration
+ * @returns Preparation results
+ */
+export declare function prepareBuildEnvironment(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig): Promise<BuildPreparation>;

package/dist/src/core/build-prepare.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared pre-flight logic for build and package commands:
+ * story cleanup, branding setup, Furnace component application, and mozconfig generation.
+ */
+import { spinner, warn } from '../utils/logger.js';
+import { isBrandingSetup, setupBranding } from './branding.js';
+import { applyAllComponents } from './furnace-apply.js';
+import { furnaceConfigExists, loadFurnaceConfig } from './furnace-config.js';
+import { cleanStories } from './furnace-stories.js';
+import { generateMozconfig } from './mach.js';
+/**
+ * Runs the shared pre-flight steps for build and package commands:
+ * 1. Cleans Furnace stories from engine (prevents leaking into production)
+ * 2. Sets up branding directory if not already done
+ * 3. Applies Furnace components if furnace.json exists
+ * 4. Generates mozconfig
+ *
+ * @param projectRoot - Root directory of the project
+ * @param paths - Resolved project paths
+ * @param config - Loaded FireForge configuration
+ * @returns Preparation results
+ */
+export async function prepareBuildEnvironment(projectRoot, paths, config) {
+    // Clean stories before build to ensure they don't leak into production binary
+    await cleanStories(paths.engine);
+    // Set up custom branding directory and patch moz.configure
+    const brandingConfig = {
+        name: config.name,
+        vendor: config.vendor,
+        appId: config.appId,
+        binaryName: config.binaryName,
+    };
+    if (!(await isBrandingSetup(paths.engine, brandingConfig))) {
+        const brandingSpinner = spinner('Setting up branding...');
+        try {
+            await setupBranding(paths.engine, brandingConfig);
+            brandingSpinner.stop('Branding configured');
+        }
+        catch (error) {
+            brandingSpinner.error('Failed to set up branding');
+            throw error;
+        }
+    }
+    // Apply Furnace components if furnace.json exists
+    let furnaceApplied = 0;
+    if (await furnaceConfigExists(projectRoot)) {
+        const furnaceConfig = await loadFurnaceConfig(projectRoot);
+        const hasComponents = Object.keys(furnaceConfig.overrides).length > 0 ||
+            Object.keys(furnaceConfig.custom).length > 0;
+        if (hasComponents) {
+            const furnaceSpinner = spinner('Applying Furnace components...');
+            try {
+                const result = await applyAllComponents(projectRoot);
+                furnaceApplied = result.applied.length;
+                if (furnaceApplied > 0) {
+                    furnaceSpinner.stop(`Applied ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'}`);
+                }
+                else {
+                    furnaceSpinner.stop('Components up to date');
+                }
+                if (result.errors.length > 0) {
+                    for (const err of result.errors) {
+                        warn(`Furnace: ${err.name} — ${err.error}`);
+                    }
+                }
+                for (const applied of result.applied) {
+                    if (applied.stepErrors && applied.stepErrors.length > 0) {
+                        for (const stepErr of applied.stepErrors) {
+                            warn(`Furnace: ${applied.name} [${stepErr.step}] ${stepErr.error}`);
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                furnaceSpinner.error('Failed to apply Furnace components');
+                throw error;
+            }
+        }
+    }
+    // Generate mozconfig
+    const mozconfigSpinner = spinner('Generating mozconfig...');
+    try {
+        await generateMozconfig(paths.configs, paths.engine, config);
+        mozconfigSpinner.stop('mozconfig generated');
+    }
+    catch (error) {
+        mozconfigSpinner.error('Failed to generate mozconfig');
+        throw error;
+    }
+    return { furnaceApplied };
+}
+//# sourceMappingURL=build-prepare.js.map

package/dist/src/core/config-mutate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Immutable config mutation with dot-path keys.
+ */
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Creates a mutated copy of a config with a nested key set to a new value,
+ * optionally re-validated.
+ * @param config - Original config
+ * @param key - Dot-separated config path
+ * @param value - New value
+ * @param skipValidation - If true, skip re-validation (for --force)
+ * @returns The mutated config
+ */
+export declare function mutateConfig(config: FireForgeConfig, key: string, value: unknown, skipValidation?: false): FireForgeConfig;
+export declare function mutateConfig(config: FireForgeConfig, key: string, value: unknown, skipValidation: true): Record<string, unknown>;

package/dist/src/core/config-mutate.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Immutable config mutation with dot-path keys.
+ */
+import { ConfigError } from '../errors/config.js';
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { isObject } from '../utils/validation.js';
+import { validateConfig } from './config-validate.js';
+function cloneConfigDocument(config) {
+    const cloned = structuredClone(config);
+    if (!isObject(cloned)) {
+        throw new ConfigError('Config clone unexpectedly produced a non-object value');
+    }
+    return cloned;
+}
+function getOrCreateChildRecord(parent, key) {
+    const existing = parent[key];
+    if (isObject(existing)) {
+        return existing;
+    }
+    const child = {};
+    parent[key] = child;
+    return child;
+}
+export function mutateConfig(config, key, value, skipValidation = false) {
+    const raw = cloneConfigDocument(config);
+    const parts = key.split('.');
+    let current = raw;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (part === undefined)
+            continue;
+        current = getOrCreateChildRecord(current, part);
+    }
+    const lastPart = parts[parts.length - 1];
+    if (lastPart !== undefined) {
+        current[lastPart] = value;
+    }
+    if (!skipValidation) {
+        return validateConfig(raw);
+    }
+    try {
+        validateConfig(raw);
+    }
+    catch (error) {
+        verbose(`Skipping config revalidation for forced mutation on "${key}": ${toError(error).message}`);
+    }
+    return raw;
+}
+//# sourceMappingURL=config-mutate.js.map

package/dist/src/core/config-paths.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Project path derivation from a root directory.
+ */
+import type { ProjectPaths } from '../types/config.js';
+/** Name of the configuration file */
+export declare const CONFIG_FILENAME = "fireforge.json";
+/** Name of the fireforge data directory */
+export declare const FIREFORGE_DIR = ".fireforge";
+/** Name of the state file */
+export declare const STATE_FILENAME = "state.json";
+/** Name of the engine directory */
+export declare const ENGINE_DIR = "engine";
+/** Name of the patches directory */
+export declare const PATCHES_DIR = "patches";
+/** Name of the configs directory */
+export declare const CONFIGS_DIR = "configs";
+/** Name of the source directory */
+export declare const SRC_DIR = "src";
+/** Supported top-level fireforge.json keys backed by the current schema. */
+export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire"];
+/** Supported config paths that can be read or set without --force. */
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir"];
+/**
+ * Gets all project paths based on a root directory.
+ * @param root - Root directory of the project
+ * @returns All project paths
+ */
+export declare function getProjectPaths(root: string): ProjectPaths;

package/dist/src/core/config-paths.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Project path derivation from a root directory.
+ */
+import { join } from 'node:path';
+/** Name of the configuration file */
+export const CONFIG_FILENAME = 'fireforge.json';
+/** Name of the fireforge data directory */
+export const FIREFORGE_DIR = '.fireforge';
+/** Name of the state file */
+export const STATE_FILENAME = 'state.json';
+/** Name of the engine directory */
+export const ENGINE_DIR = 'engine';
+/** Name of the patches directory */
+export const PATCHES_DIR = 'patches';
+/** Name of the configs directory */
+export const CONFIGS_DIR = 'configs';
+/** Name of the source directory */
+export const SRC_DIR = 'src';
+/** Supported top-level fireforge.json keys backed by the current schema. */
+export const SUPPORTED_CONFIG_ROOT_KEYS = [
+    'name',
+    'vendor',
+    'appId',
+    'binaryName',
+    'firefox',
+    'build',
+    'license',
+    'wire',
+];
+/** Supported config paths that can be read or set without --force. */
+export const SUPPORTED_CONFIG_PATHS = [
+    'name',
+    'vendor',
+    'appId',
+    'binaryName',
+    'license',
+    'firefox',
+    'firefox.version',
+    'firefox.product',
+    'build',
+    'build.jobs',
+    'wire',
+    'wire.subscriptDir',
+];
+/**
+ * Gets all project paths based on a root directory.
+ * @param root - Root directory of the project
+ * @returns All project paths
+ */
+export function getProjectPaths(root) {
+    const fireforgeDir = join(root, FIREFORGE_DIR);
+    return {
+        root,
+        config: join(root, CONFIG_FILENAME),
+        fireforgeDir,
+        state: join(fireforgeDir, STATE_FILENAME),
+        engine: join(root, ENGINE_DIR),
+        patches: join(root, PATCHES_DIR),
+        configs: join(root, CONFIGS_DIR),
+        src: join(root, SRC_DIR),
+        componentsDir: join(root, 'components'),
+    };
+}
+//# sourceMappingURL=config-paths.js.map

package/dist/src/core/config-state.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Project state file management (.fireforge/state.json).
+ */
+import type { FireForgeState } from '../types/config.js';
+/**
+ * Validates a parsed project state object and returns a typed FireForgeState.
+ * @param data - Parsed JSON state data
+ * @returns Validated FireForgeState
+ */
+export declare function validateFireForgeState(data: unknown): FireForgeState;
+/**
+ * Loads the fireforge state, or returns defaults if it doesn't exist.
+ * @param root - Root directory of the project
+ * @returns FireForge state
+ */
+export declare function loadState(root: string): Promise<FireForgeState>;
+/**
+ * Saves the fireforge state.
+ * @param root - Root directory of the project
+ * @param state - State to save
+ */
+export declare function saveState(root: string, state: FireForgeState): Promise<void>;
+/**
+ * Updates specific fields in the fireforge state.
+ * @param root - Root directory of the project
+ * @param updates - Fields to update, or a transactional updater function
+ */
+export declare function updateState(root: string, updates: Partial<FireForgeState> | ((current: FireForgeState) => FireForgeState)): Promise<void>;