@hominis/fireforge 0.30.1 → 0.31.0

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

@@ -10,20 +10,13 @@ import { isValidAppId, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LIC
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 /**
- * Validates a raw config object and returns a typed FireForgeConfig.
- * @param data - Raw data to validate
- * @returns Validated FireForgeConfig
- * @throws Error if validation fails
+ * Parses and validates the four required identity fields (`name`,
+ * `vendor`, `appId`, `binaryName`): all non-empty strings, with
+ * `binaryName` additionally barred from path separators/traversal and
+ * `appId` required to be a reverse-domain identifier.
  */
-export function validateConfig(data) {
-    let rec;
-    try {
-        rec = parseObject(data, 'Config');
-    }
-    catch {
-        throw new ConfigError('Config must be an object');
-    }
-    // Required string fields. Empty strings would technically pass the
+function parseIdentityFields(rec) {
+    // Empty strings would technically pass the
     // typeof-check below but are never valid for any of these identifier
     // fields — rejecting them here prevents downstream code (Firefox build,
     // launcher binary lookup, AppID assertions) from failing with confusing
@@ -54,7 +47,14 @@ export function validateConfig(data) {
     if (!isValidAppId(appId)) {
         throw new ConfigError('Config field "appId" must be a valid reverse-domain identifier (e.g., "org.example.browser")');
     }
-    // Firefox config
+    return { name, vendor, appId, binaryName };
+}
+/**
+ * Parses and validates the required `firefox` block: version shape,
+ * product allowlist, product/version cross-compatibility, and the
+ * optional sha256 digest (normalized to lowercase).
+ */
+function parseFirefoxBlock(rec) {
     let firefoxRec;
     try {
         firefoxRec = rec.object('firefox');
@@ -80,19 +80,14 @@ export function validateConfig(data) {
     if (firefoxSha256 !== undefined && !/^[a-f0-9]{64}$/i.test(firefoxSha256)) {
         throw new ConfigError('Config field "firefox.sha256" must be a 64-character SHA-256 hex digest');
     }
-    // Optional configs
-    const config = {
-        name,
-        vendor,
-        appId,
-        binaryName,
-        firefox: {
-            version: firefoxVersion,
-            product: firefoxProduct,
-            ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
-        },
+    return {
+        version: firefoxVersion,
+        product: firefoxProduct,
+        ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
     };
-    // Build
+}
+/** Parses the optional `build` block (currently just `build.jobs`). */
+function parseBuildBlock(rec, config) {
     const buildRec = optionalConfigObject(rec, 'build');
     if (buildRec) {
         config.build = {};
@@ -104,7 +99,9 @@ export function validateConfig(data) {
             config.build.jobs = jobs;
         }
     }
-    // Wire
+}
+/** Parses the optional `wire` block (currently just `wire.subscriptDir`). */
+function parseWireBlock(rec, config) {
     const wireRec = optionalConfigObject(rec, 'wire');
     if (wireRec) {
         config.wire = {};
@@ -116,7 +113,9 @@ export function validateConfig(data) {
             config.wire.subscriptDir = subscriptDir;
         }
     }
-    // License
+}
+/** Parses the optional `license` field against the supported-license list. */
+function parseLicenseField(rec, config) {
     const licenseRaw = rec.raw('license');
     if (licenseRaw !== undefined) {
         if (typeof licenseRaw !== 'string') {
@@ -127,6 +126,27 @@ export function validateConfig(data) {
         }
         config.license = licenseRaw;
     }
+}
+/**
+ * Validates a raw config object and returns a typed FireForgeConfig.
+ * @param data - Raw data to validate
+ * @returns Validated FireForgeConfig
+ * @throws Error if validation fails
+ */
+export function validateConfig(data) {
+    let rec;
+    try {
+        rec = parseObject(data, 'Config');
+    }
+    catch {
+        throw new ConfigError('Config must be an object');
+    }
+    const identity = parseIdentityFields(rec);
+    const firefox = parseFirefoxBlock(rec);
+    const config = { ...identity, firefox };
+    parseBuildBlock(rec, config);
+    parseWireBlock(rec, config);
+    parseLicenseField(rec, config);
     // Marker comment — appended to lines FireForge writes into upstream files.
     const markerComment = parseMarkerComment(rec.raw('markerComment'));
     if (markerComment !== undefined) {

package/dist/src/core/engine-changes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared collector for "what changed in the engine tree since the last
+ * successful build". Three preflight/audit paths previously carried their
+ * own copy of this logic (`build-audit`, `build-prepare`,
+ * `test-stale-check`), differing only in the verbose-log label; they all
+ * call this module now.
+ */
+import type { BuildBaseline } from './build-baseline-types.js';
+/**
+ * Collects engine-relative paths changed since the baseline's HEAD SHA,
+ * plus any workdir modifications (tracked and untracked). Defensive — git
+ * failures surface as verbose lines and return the files collected so far,
+ * so an empty result means "no drift we can prove" rather than "no drift
+ * occurred". When the baseline is missing or the engine has no HEAD yet,
+ * falls back to workdir-only collection. The result is sorted.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param baseline - Last-build baseline, when one exists
+ * @param contextLabel - Prefix for verbose-log lines (e.g. `Audit`,
+ *   `Auto-configure`, `Stale-build preflight`) so operators can attribute
+ *   the probe that emitted them
+ * @returns Sorted engine-relative POSIX paths
+ */
+export declare function collectChangedEnginePaths(engineDir: string, baseline: BuildBaseline | undefined, contextLabel: string): Promise<string[]>;

package/dist/src/core/engine-changes.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared collector for "what changed in the engine tree since the last
+ * successful build". Three preflight/audit paths previously carried their
+ * own copy of this logic (`build-audit`, `build-prepare`,
+ * `test-stale-check`), differing only in the verbose-log label; they all
+ * call this module now.
+ */
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+/**
+ * Collects engine-relative paths changed since the baseline's HEAD SHA,
+ * plus any workdir modifications (tracked and untracked). Defensive — git
+ * failures surface as verbose lines and return the files collected so far,
+ * so an empty result means "no drift we can prove" rather than "no drift
+ * occurred". When the baseline is missing or the engine has no HEAD yet,
+ * falls back to workdir-only collection. The result is sorted.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param baseline - Last-build baseline, when one exists
+ * @param contextLabel - Prefix for verbose-log lines (e.g. `Audit`,
+ *   `Auto-configure`, `Stale-build preflight`) so operators can attribute
+ *   the probe that emitted them
+ * @returns Sorted engine-relative POSIX paths
+ */
+export async function collectChangedEnginePaths(engineDir, baseline, contextLabel) {
+    const collected = new Set();
+    if (baseline?.engineHeadSha) {
+        try {
+            const output = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
+            for (const line of output.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+        }
+        catch (error) {
+            if (!isMissingHeadError(error)) {
+                verbose(`${contextLabel}: could not diff engine against baseline — ${toError(error).message}`);
+            }
+        }
+    }
+    try {
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+            for (const untracked of await getUntrackedFiles(engineDir)) {
+                collected.add(untracked);
+            }
+        }
+    }
+    catch (error) {
+        verbose(`${contextLabel}: could not enumerate workdir changes — ${toError(error).message}`);
+    }
+    return [...collected].sort();
+}
+//# sourceMappingURL=engine-changes.js.map

package/dist/src/core/firefox-cache.d.ts

@@ -3,11 +3,6 @@
  */
 import type { ResolvedArchive } from './firefox-archive.js';
 import type { ProgressCallback } from './firefox-download.js';
-/**
- * Computes the SHA-256 hex digest of a file.
- * @param filePath - Path to the file
- */
-export declare function sha256File(filePath: string): Promise<string>;
 /**
  * Ensures a valid cached archive exists, downloading it if needed.
  * @param archive - Resolved archive descriptor

package/dist/src/core/firefox-cache.js

@@ -18,7 +18,7 @@ import { downloadFile } from './firefox-download.js';
  * Computes the SHA-256 hex digest of a file.
  * @param filePath - Path to the file
  */
-export async function sha256File(filePath) {
+async function sha256File(filePath) {
     const hash = createHash('sha256');
     const stream = createReadStream(filePath);
     await pipeline(stream, hash);

package/dist/src/core/firefox-download.d.ts

@@ -5,12 +5,6 @@
  * Progress callback for download operations.
  */
 export type ProgressCallback = (downloaded: number, total: number) => void;
-/**
- * Fetches a URL with timeout and bounded retry for transient failures.
- *
- * Non-retryable errors (e.g. 404) are thrown immediately.
- */
-export declare function fetchWithRetry(url: string): Promise<Response>;
 /**
  * Downloads a file from a URL with progress tracking, timeout, and retry.
  * @param url - URL to download

package/dist/src/core/firefox-download.js

@@ -22,7 +22,7 @@ const DOWNLOAD_STALL_TIMEOUT_MS = 30_000;
  *
  * Non-retryable errors (e.g. 404) are thrown immediately.
  */
-export async function fetchWithRetry(url) {
+async function fetchWithRetry(url) {
     let lastError;
     for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
         const controller = new AbortController();

package/dist/src/core/furnace-apply-helpers.d.ts

@@ -29,13 +29,6 @@ export declare function getOverrideEngineTargetPath(engineDir: string, config: O
 export declare function restoreOverrideFileToBaseline(engineDir: string, enginePath: string, journal: RollbackJournal): Promise<'restored' | 'removed' | 'noop'>;
 /** Computes stable checksums for the source files that define a component. */
 export declare function computeComponentChecksums(componentDir: string): Promise<Record<string, string>>;
-/**
- * Returns the filenames present in `previous` that are absent from `current`
- * — i.e. files we know we deployed last time but the workspace has since
- * deleted. The order of returned names is intentionally stable
- * (sorted alphabetically) so test snapshots and CLI output are deterministic.
- */
-export declare function diffDeletedFiles(previous: Record<string, string>, current: Record<string, string>): string[];
 /**
  * Removes engine copies of files that the developer has deleted from a custom
  * component's workspace since the last apply. `.ftl` files live under the
@@ -110,4 +103,4 @@ export declare function applyOverrideComponent(engineDir: string, name: string,
     affectedPaths: string[];
     actions?: DryRunAction[];
 }>;
-export { extractComponentChecksums, prefixChecksums } from './furnace-checksum-utils.js';
+export { diffDeletedFiles, extractComponentChecksums, prefixChecksums, } from './furnace-checksum-utils.js';

package/dist/src/core/furnace-apply-helpers.js

@@ -8,6 +8,7 @@ import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/
 import { verbose } from '../utils/logger.js';
 import { applyCustomFtlFile, describeLocaleFtlJarMnRegistration, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
+import { deployFileWithFragments, describeFragmentExpansion, SHARED_FRAGMENTS_DIR, } from './furnace-css-fragments.js';
 import { addCustomElementRegistration, addJarMnEntries, validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
 import { recordCreatedDir, snapshotFile } from './furnace-rollback.js';
 import { checkRegistrationConsistency } from './furnace-validate-registration.js';
@@ -97,21 +98,6 @@ export async function computeComponentChecksums(componentDir) {
     }
     return checksums;
 }
-/**
- * Returns the filenames present in `previous` that are absent from `current`
- * — i.e. files we know we deployed last time but the workspace has since
- * deleted. The order of returned names is intentionally stable
- * (sorted alphabetically) so test snapshots and CLI output are deterministic.
- */
-export function diffDeletedFiles(previous, current) {
-    const deleted = [];
-    for (const key of Object.keys(previous)) {
-        if (!(key in current)) {
-            deleted.push(key);
-        }
-    }
-    return deleted.sort();
-}
 /**
  * Removes engine copies of files that the developer has deleted from a custom
  * component's workspace since the last apply. `.ftl` files live under the
@@ -300,12 +286,13 @@ async function buildCustomDryRunActions(name, componentDir, engineDir, config, t
             continue;
         if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
             continue;
+        const fragmentNote = await describeFragmentExpansion(join(componentDir, entry.name));
         actions.push({
             component: name,
-            action: 'copy',
+            action: fragmentNote ? 'expand-fragments' : 'copy',
             source: join(componentDir, entry.name),
             target: join(targetDir, entry.name),
-            description: `Copy ${entry.name} to ${config.targetPath}`,
+            description: `Copy ${entry.name} to ${config.targetPath}${fragmentNote}`,
         });
     }
     // Per-component .ftl handling is skipped when the component opts into a
@@ -401,11 +388,15 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
             await snapshotFile(rollbackJournal, dest);
         }
     }
-    // Copy phase (parallel — independent file writes to different paths)
+    // Copy phase (parallel — independent file writes to different paths).
+    // CSS files carrying @fireforge-include directives are written as their
+    // fragment-expanded form (field report D2); the workspace source keeps
+    // only the directive, so shared CSS stays single-sourced.
+    const sharedDir = join(componentDir, '..', '..', SHARED_FRAGMENTS_DIR);
     await Promise.all(filesToCopy.map(async (entry) => {
         const src = join(componentDir, entry.name);
         const dest = join(targetDir, entry.name);
-        await copyFile(src, dest);
+        await deployFileWithFragments(src, dest, sharedDir);
         affectedPaths.push(relative(engineDir, dest));
         copiedFileNames.push(entry.name);
     }));
@@ -499,5 +490,5 @@ export async function applyOverrideComponent(engineDir, name, componentDir, conf
     }
     return { affectedPaths };
 }
-export { extractComponentChecksums, prefixChecksums } from './furnace-checksum-utils.js';
+export { diffDeletedFiles, extractComponentChecksums, prefixChecksums, } from './furnace-checksum-utils.js';
 //# sourceMappingURL=furnace-apply-helpers.js.map

package/dist/src/core/furnace-apply.d.ts

@@ -1,7 +1,7 @@
 import type { ApplyResult, DryRunAction } from '../types/furnace.js';
 import { type FurnaceOperationContext } from './furnace-operation.js';
 import { type RollbackJournal } from './furnace-rollback.js';
-export { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
+export { computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
 /**
  * Applies all override and custom components to the engine source tree.
  *

package/dist/src/core/furnace-apply.js

@@ -14,7 +14,7 @@ import { recordFurnaceRollbackFailure } from './furnace-operation.js';
 import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
 import { runPostApplyConsistencyChecks } from './furnace-validate-registration.js';
-export { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
+export { computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
 function addMissingComponentError(result, name, directoryPath) {
     result.errors.push({
         name,

package/dist/src/core/furnace-checksum-utils.d.ts

@@ -2,3 +2,10 @@
 export declare function extractComponentChecksums(allChecksums: Record<string, string> | undefined, type: string, name: string): Record<string, string>;
 /** Prefixes component checksums so they can be stored in the flattened state format. */
 export declare function prefixChecksums(checksums: Record<string, string>, type: string, name: string): Record<string, string>;
+/**
+ * Returns the filenames present in `previous` that are absent from `current`
+ * — i.e. files we know we deployed last time but the workspace has since
+ * deleted. The order of returned names is intentionally stable
+ * (sorted alphabetically) so test snapshots and CLI output are deterministic.
+ */
+export declare function diffDeletedFiles(previous: Record<string, string>, current: Record<string, string>): string[];

package/dist/src/core/furnace-checksum-utils.js

@@ -21,4 +21,19 @@ export function prefixChecksums(checksums, type, name) {
     }
     return result;
 }
+/**
+ * Returns the filenames present in `previous` that are absent from `current`
+ * — i.e. files we know we deployed last time but the workspace has since
+ * deleted. The order of returned names is intentionally stable
+ * (sorted alphabetically) so test snapshots and CLI output are deterministic.
+ */
+export function diffDeletedFiles(previous, current) {
+    const deleted = [];
+    for (const key of Object.keys(previous)) {
+        if (!(key in current)) {
+            deleted.push(key);
+        }
+    }
+    return deleted.sort();
+}
 //# sourceMappingURL=furnace-checksum-utils.js.map

package/dist/src/core/furnace-config-validate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Section validators for `validateFurnaceConfig`, split out of
+ * `furnace-config.ts` to keep that module inside the per-file line
+ * budget. Each helper owns one shape: the override entry, the stock
+ * list, the named-component maps, and the optional-field tail.
+ */
+import type { FurnaceConfig, OverrideComponentConfig } from '../types/furnace.js';
+/**
+ * Validates an override component config object.
+ * @param data - Raw data to validate
+ * @param name - Component name for error messages
+ */
+export declare function parseOverrideConfig(data: Record<string, unknown>, name: string): OverrideComponentConfig;
+/**
+ * Parses and validates the `stock` component list: lowercase identifiers,
+ * no duplicates.
+ */
+export declare function parseStockList(raw: unknown): string[];
+/**
+ * Parses one of the named-component maps (`overrides` / `custom`): the
+ * map must be an object, every key a lowercase identifier, every value an
+ * object handed to the kind-specific parser.
+ */
+export declare function parseNamedComponentMap<T>(raw: unknown, kind: 'override' | 'custom', key: 'overrides' | 'custom', parse: (value: Record<string, unknown>, name: string) => T): Record<string, T>;
+/**
+ * Copies the validated optional fields (token settings, platform
+ * prefixes, ftl/jsconfig/scan paths) from the migrated raw config onto
+ * the typed config, re-validating the path-shaped ones against
+ * traversal.
+ */
+export declare function applyOptionalFurnaceFields(migrated: Record<string, unknown>, config: FurnaceConfig): void;

package/dist/src/core/furnace-config-validate.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Section validators for `validateFurnaceConfig`, split out of
+ * `furnace-config.ts` to keep that module inside the per-file line
+ * budget. Each helper owns one shape: the override entry, the stock
+ * list, the named-component maps, and the optional-field tail.
+ */
+import { FurnaceError } from '../errors/furnace.js';
+import { isObject, isString } from '../utils/validation.js';
+import { parseStringArray } from './furnace-config-array-utils.js';
+/**
+ * Validates an override component config object.
+ * @param data - Raw data to validate
+ * @param name - Component name for error messages
+ */
+export function parseOverrideConfig(data, name) {
+    const validTypes = ['css-only', 'full'];
+    if (!isString(data['type']) || !validTypes.includes(data['type'])) {
+        throw new FurnaceError(`Furnace config: override "${name}.type" must be one of: ${validTypes.join(', ')}`);
+    }
+    if (!isString(data['description'])) {
+        throw new FurnaceError(`Furnace config: override "${name}.description" must be a string`);
+    }
+    if (!isString(data['basePath'])) {
+        throw new FurnaceError(`Furnace config: override "${name}.basePath" must be a string`);
+    }
+    if (data['basePath'].includes('..')) {
+        throw new FurnaceError(`Furnace config: override "${name}.basePath" must not contain ".." (path traversal)`);
+    }
+    if (!isString(data['baseVersion'])) {
+        throw new FurnaceError(`Furnace config: override "${name}.baseVersion" must be a string`);
+    }
+    return {
+        type: data['type'] === 'css-only' ? 'css-only' : 'full',
+        description: data['description'],
+        basePath: data['basePath'],
+        baseVersion: data['baseVersion'],
+        ...(isString(data['baseCommit']) ? { baseCommit: data['baseCommit'] } : {}),
+    };
+}
+/**
+ * Parses and validates the `stock` component list: lowercase identifiers,
+ * no duplicates.
+ */
+export function parseStockList(raw) {
+    const stock = parseStringArray(raw, 'stock');
+    const stockSet = new Set();
+    for (const name of stock) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            throw new FurnaceError(`Furnace config: stock entry "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
+        }
+        if (stockSet.has(name)) {
+            throw new FurnaceError(`Furnace config: duplicate stock entry "${name}"`);
+        }
+        stockSet.add(name);
+    }
+    return stock;
+}
+/**
+ * Parses one of the named-component maps (`overrides` / `custom`): the
+ * map must be an object, every key a lowercase identifier, every value an
+ * object handed to the kind-specific parser.
+ */
+export function parseNamedComponentMap(raw, kind, key, parse) {
+    if (!isObject(raw)) {
+        throw new FurnaceError(`Furnace config: "${key}" must be an object`);
+    }
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            throw new FurnaceError(`Furnace config: ${kind} name "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
+        }
+        if (!isObject(value)) {
+            throw new FurnaceError(`Furnace config: ${kind} "${name}" must be an object`);
+        }
+        out[name] = parse(value, name);
+    }
+    return out;
+}
+/**
+ * Copies the validated optional fields (token settings, platform
+ * prefixes, ftl/jsconfig/scan paths) from the migrated raw config onto
+ * the typed config, re-validating the path-shaped ones against
+ * traversal.
+ */
+export function applyOptionalFurnaceFields(migrated, config) {
+    if (migrated['tokenPrefix'] !== undefined && isString(migrated['tokenPrefix'])) {
+        config.tokenPrefix = migrated['tokenPrefix'];
+    }
+    if (migrated['tokenAllowlist'] !== undefined) {
+        config.tokenAllowlist = parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
+    }
+    if (migrated['platformPrefixes'] !== undefined) {
+        config.platformPrefixes = parseStringArray(migrated['platformPrefixes'], 'platformPrefixes');
+    }
+    if (migrated['runtimeVariables'] !== undefined) {
+        config.runtimeVariables = parseStringArray(migrated['runtimeVariables'], 'runtimeVariables');
+    }
+    if (migrated['tokenHostDocuments'] !== undefined) {
+        const docs = parseStringArray(migrated['tokenHostDocuments'], 'tokenHostDocuments');
+        config.tokenHostDocuments = docs;
+    }
+    // Validate optional ftlBasePath
+    if (migrated['ftlBasePath'] !== undefined) {
+        if (!isString(migrated['ftlBasePath'])) {
+            throw new FurnaceError('Furnace config: "ftlBasePath" must be a string if provided');
+        }
+        if (migrated['ftlBasePath'].includes('..')) {
+            throw new FurnaceError('Furnace config: "ftlBasePath" must not contain ".." (path traversal)');
+        }
+        config.ftlBasePath = migrated['ftlBasePath'];
+    }
+    // Validate optional typecheckJsconfig — consumer-owned jsconfig whose
+    // chrome-elements `paths` entries Furnace maintains on deploy.
+    if (migrated['typecheckJsconfig'] !== undefined) {
+        const jsconfigPath = migrated['typecheckJsconfig'];
+        if (!isString(jsconfigPath) || jsconfigPath.includes('..')) {
+            throw new FurnaceError('Furnace config: "typecheckJsconfig" must be a string without ".." (path traversal)');
+        }
+        config.typecheckJsconfig = jsconfigPath;
+    }
+    // Validate optional scanPaths
+    if (migrated['scanPaths'] !== undefined) {
+        const paths = parseStringArray(migrated['scanPaths'], 'scanPaths');
+        for (const p of paths) {
+            if (p.includes('..')) {
+                throw new FurnaceError('Furnace config: "scanPaths" entries must not contain ".." (path traversal)');
+            }
+        }
+        config.scanPaths = paths;
+    }
+}
+//# sourceMappingURL=furnace-config-validate.js.map

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

@@ -1,16 +1,8 @@
 import type { FurnaceConfig, FurnaceState } from '../types/furnace.js';
 import { detectComposesCycles } from './furnace-graph-utils.js';
 export { detectComposesCycles };
-/** Name of the furnace configuration file */
-export declare const FURNACE_CONFIG_FILENAME = "furnace.json";
-/** Name of the furnace state file */
-export declare const FURNACE_STATE_FILENAME = "furnace-state.json";
-/** Name of the components directory */
-export declare const COMPONENTS_DIR = "components";
-/** Name of the overrides subdirectory */
-export declare const OVERRIDES_DIR = "overrides";
-/** Name of the custom subdirectory */
-export declare const CUSTOM_DIR = "custom";
+/** Directory name for shared CSS fragments within components/ */
+export declare const SHARED_FRAGMENTS_DIR = "shared";
 /**
  * Paths for furnace-related files and directories.
  */
@@ -23,6 +15,8 @@ interface FurnacePaths {
     overridesDir: string;
     /** Path to components/custom directory */
     customDir: string;
+    /** Path to components/shared directory (CSS fragments) */
+    sharedDir: string;
     /** Path to .fireforge/furnace-state.json */
     furnaceState: string;
 }
@@ -38,22 +32,6 @@ export declare function getFurnacePaths(root: string): FurnacePaths;
  * @returns True if furnace.json exists
  */
 export declare function furnaceConfigExists(root: string): Promise<boolean>;
-/**
- * Migrates a furnace config from an older schema version to the current one.
- * Returns the data unchanged if it is already at the current version.
- *
- * When a future version 2 is introduced, add a `case 1:` that transforms
- * v1 data into v2 shape and falls through to validation. The pattern is:
- *
- * ```
- * case 1:
- *   data = migrateV1ToV2(data);
- *   // fallthrough
- * case 2:
- *   break;
- * ```
- */
-export declare function migrateFurnaceConfig(data: Record<string, unknown>): Record<string, unknown>;
 /**
  * Validates a raw config object and returns a typed FurnaceConfig.
  * @param data - Raw data to validate
@@ -61,12 +39,6 @@ export declare function migrateFurnaceConfig(data: Record<string, unknown>): Rec
  * @throws Error if validation fails
  */
 export declare function validateFurnaceConfig(data: unknown): FurnaceConfig;
-/**
- * Validates a parsed furnace state object and returns a typed FurnaceState.
- * @param data - Parsed JSON state data
- * @returns Validated FurnaceState
- */
-export declare function validateFurnaceState(data: unknown): FurnaceState;
 /**
  * Loads and validates the furnace.json configuration.
  * @param root - Root directory of the project