@hominis/fireforge 0.30.1 → 0.32.0

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

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Maintains `compilerOptions.paths` entries in a consumer-owned jsconfig
+ * so typed cross-module imports of multi-file Furnace components work
+ * (field report D3).
+ *
+ * When a main widget imports a sibling helper via its deployed chrome URL
+ * (`chrome://global/content/elements/<helper>.mjs`), a wildcard module
+ * shim swallows the import: value imports degrade to `any` and
+ * `import(...).SomeType` typedefs fail with TS2694. The fix is a `paths`
+ * mapping from the chrome URL to the real workspace source. Furnace
+ * already owns the jar.mn side of that mapping, so it can maintain the
+ * jsconfig side automatically on every deploy.
+ *
+ * Ownership contract: only entries whose key starts with
+ * `chrome://global/content/elements/` AND whose mapped path resolves into
+ * the Furnace custom-components workspace are managed (added, updated,
+ * pruned). Everything else in the jsconfig — including hand-written
+ * `paths` entries pointing elsewhere — is preserved verbatim. No
+ * `baseUrl` is required or written: relative `paths` resolve against the
+ * config file's directory.
+ */
+import { readdir } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { info } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+import { getFurnacePaths } from './furnace-config.js';
+/** Chrome URL prefix under which registered custom-element files deploy. */
+const CHROME_ELEMENTS_URL_PREFIX = 'chrome://global/content/elements/';
+/**
+ * Computes the desired managed `paths` entries: one per `.mjs` file of
+ * every registered custom component, keyed by its deployed chrome URL and
+ * mapped to the workspace source relative to the jsconfig directory.
+ *
+ * Workspace sources (not deployed engine copies) are the mapping target —
+ * they are the files developers edit, and they exist even when the engine
+ * has not been deployed yet.
+ */
+async function computeDesiredChromePathEntries(config, customDir, jsconfigAbsPath) {
+    const jsconfigDir = dirname(jsconfigAbsPath);
+    const entries = {};
+    for (const [name, customConfig] of Object.entries(config.custom)) {
+        if (!customConfig.register)
+            continue;
+        const componentDir = join(customDir, name);
+        if (!(await pathExists(componentDir)))
+            continue;
+        const files = await readdir(componentDir);
+        for (const file of files.sort()) {
+            if (!file.endsWith('.mjs'))
+                continue;
+            // Emit a `./`-prefixed relative value. TypeScript treats a bare
+            // `paths` value (`moz-widget/moz-widget.mjs`) as non-relative and
+            // rejects it without `baseUrl` (TS5090); a `./`-prefixed value
+            // resolves against the jsconfig directory with no `baseUrl` (which
+            // TS6 deprecates, TS5101). `../`-prefixed paths are already relative
+            // and left untouched.
+            const rel = normalizePathSlashes(relative(jsconfigDir, join(componentDir, file)));
+            const sourcePath = rel.startsWith('.') ? rel : `./${rel}`;
+            entries[`${CHROME_ELEMENTS_URL_PREFIX}${file}`] = [sourcePath];
+        }
+    }
+    return entries;
+}
+/**
+ * Compares two `paths` values treating a leading `./` as insignificant, so
+ * the reconciler does not churn between `./x` and bare `x` forms (either
+ * direction). Used to decide whether a managed entry is stale.
+ */
+function samePathValue(a, b) {
+    const strip = (p) => (p.startsWith('./') ? p.slice(2) : p);
+    return strip(a) === strip(b);
+}
+/** True when `key`/`value` is a Furnace-managed chrome-elements mapping. */
+function isManagedEntry(key, value, jsconfigDir, customDir) {
+    if (!key.startsWith(CHROME_ELEMENTS_URL_PREFIX))
+        return false;
+    if (!Array.isArray(value) || value.length !== 1 || typeof value[0] !== 'string')
+        return false;
+    const target = resolve(jsconfigDir, value[0]);
+    return target.startsWith(resolve(customDir) + '/') || target === resolve(customDir);
+}
+/**
+ * Reconciles the managed `compilerOptions.paths` entries of the configured
+ * jsconfig against the current Furnace workspace. Idempotent; writes only
+ * when something actually changes; dry-run returns the diff without
+ * writing.
+ *
+ * The consumer owns the jsconfig file: a missing file is an error with
+ * guidance rather than a silent scaffold, and JSONC (comments/trailing
+ * commas) is unsupported for the managed file — `readJson` is a strict
+ * JSON parser, so the error message says so explicitly.
+ *
+ * @param root - Project root directory
+ * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
+ * @param options - `dryRun` skips the write but still reports the diff
+ */
+export async function syncFurnaceJsconfigPaths(root, config, options) {
+    const result = { added: [], updated: [], pruned: [], changed: false };
+    const jsconfigRel = config.typecheckJsconfig;
+    if (!jsconfigRel)
+        return result;
+    const jsconfigAbs = resolve(root, jsconfigRel);
+    if (!(await pathExists(jsconfigAbs))) {
+        throw new FurnaceError(`furnace.json sets "typecheckJsconfig": "${jsconfigRel}", but the file does not exist. ` +
+            'Create the jsconfig (it stays consumer-owned; Furnace only maintains the ' +
+            `"compilerOptions.paths" entries under ${CHROME_ELEMENTS_URL_PREFIX}*), ` +
+            'or remove the setting.');
+    }
+    let jsconfig;
+    try {
+        jsconfig = await readJson(jsconfigAbs);
+    }
+    catch (error) {
+        throw new FurnaceError(`Could not parse ${jsconfigRel} as JSON: ${error instanceof Error ? error.message : String(error)}. ` +
+            'Furnace manages paths entries only in plain-JSON jsconfig files — JSONC comments ' +
+            'and trailing commas are not supported for the managed file.');
+    }
+    const furnacePaths = getFurnacePaths(root);
+    const desired = await computeDesiredChromePathEntries(config, furnacePaths.customDir, jsconfigAbs);
+    const jsconfigDir = dirname(jsconfigAbs);
+    const currentPaths = { ...(jsconfig.compilerOptions?.paths ?? {}) };
+    const nextPaths = {};
+    // Preserve every unmanaged entry verbatim; prune managed entries that are
+    // no longer desired; update managed entries whose target moved.
+    for (const [key, value] of Object.entries(currentPaths)) {
+        if (!isManagedEntry(key, value, jsconfigDir, furnacePaths.customDir)) {
+            nextPaths[key] = value;
+            continue;
+        }
+        const want = desired[key];
+        if (want === undefined) {
+            result.pruned.push(key);
+            continue;
+        }
+        // Treat `./x` and bare `x` as equal so a previously-synced bare value (or
+        // a hand-written `./` prefix) is not rewritten as "stale" on every run.
+        // The existing value is kept verbatim when equivalent — no churn either
+        // way; only a genuinely different target updates (to the `./` form).
+        if (!samePathValue(value[0] ?? '', want[0] ?? '')) {
+            result.updated.push(key);
+            nextPaths[key] = want;
+        }
+        else {
+            nextPaths[key] = value;
+        }
+    }
+    for (const [key, want] of Object.entries(desired)) {
+        if (!(key in nextPaths)) {
+            result.added.push(key);
+            nextPaths[key] = want;
+        }
+    }
+    result.changed = result.added.length > 0 || result.updated.length > 0 || result.pruned.length > 0;
+    if (!result.changed || options?.dryRun === true)
+        return result;
+    const nextJsconfig = {
+        ...jsconfig,
+        compilerOptions: {
+            ...(jsconfig.compilerOptions ?? {}),
+            paths: nextPaths,
+        },
+    };
+    await writeJson(jsconfigAbs, nextJsconfig);
+    return result;
+}
+/**
+ * Computes jsconfig `paths` drift for `furnace validate`: managed entries
+ * that are missing or stale relative to the current workspace. Read-only —
+ * delegates to {@link syncFurnaceJsconfigPaths} in dry-run mode.
+ */
+export async function findJsconfigPathsDrift(root, config) {
+    return syncFurnaceJsconfigPaths(root, config, { dryRun: true });
+}
+/**
+ * Runs the jsconfig paths sync after a successful deploy/sync and reports
+ * the diff. No-op when `typecheckJsconfig` is unset. Shared by
+ * `furnace deploy` and `furnace sync` so both report identically.
+ */
+export async function reportJsconfigPathsSync(root, config, dryRun) {
+    if (!config.typecheckJsconfig)
+        return;
+    const sync = await syncFurnaceJsconfigPaths(root, config, { dryRun });
+    if (!sync.changed)
+        return;
+    info(`${dryRun ? '[dry-run] Would update' : 'Updated'} ${config.typecheckJsconfig} chrome-module paths: ` +
+        `+${sync.added.length} added, ~${sync.updated.length} updated, -${sync.pruned.length} pruned`);
+}
+//# sourceMappingURL=furnace-jsconfig.js.map

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

@@ -61,20 +61,6 @@ export declare function stripCssBlockComments(content: string): string;
 export declare function hasRelativeModuleImport(mjsContent: string): boolean;
 /** Detects whether a module defines a custom element at runtime. */
 export declare function hasCustomElementDefineCall(mjsContent: string): boolean;
-/**
- * Detects whether the module's `customElements.define(...)` call includes a
- * literal `extends:` option (third argument). That shape is the marker for
- * a customized built-in element — the class extends a specific
- * `HTMLxxxElement` rather than the autonomous `MozLitElement` path.
- *
- * Firefox's own widgets use this pattern for toolkit anchors (e.g.
- * `moz-support-link` extends `HTMLAnchorElement` with
- * `customElements.define("moz-support-link", ..., { extends: "a" })`), and
- * the validator's `not-moz-lit-element` check must allow them through or
- * `furnace override` of a valid upstream component fails its own
- * `furnace validate` pass with nothing the operator can fix.
- */
-export declare function hasCustomElementExtendsOption(mjsContent: string): boolean;
 /**
  * Checks whether a declared component class extends a valid element base.
  *
@@ -114,3 +100,19 @@ export declare function getTokenPrefixContext(tagName: string, type: ComponentTy
     inheritedOverrideVars: Set<string>;
     runtimeVariables: Set<string>;
 }>;
+/**
+ * Flags engine-side files that a previous deploy of `tagName` left behind
+ * after their workspace source was renamed or removed (field report D1).
+ *
+ * Detection keys on the furnace state file: every `appliedChecksums` entry
+ * under `custom/<tagName>/` whose workspace source no longer exists but
+ * whose engine target is still present is an orphan — the next deploy will
+ * prune it, but until then jar.mn and the deployed directory disagree with
+ * the workspace, and a re-export could capture the stale state into a patch.
+ *
+ * Custom components only: override undeploys restore the upstream baseline
+ * rather than deleting files, so "orphan" has no meaning there.
+ */
+export declare function findOrphanedEngineFiles(root: string, config: FurnaceConfig, tagName: string, state: {
+    appliedChecksums?: Record<string, string>;
+}, ftlDir: string): Promise<ValidationIssue[]>;

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

@@ -2,6 +2,7 @@
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { getProjectPaths } from './config.js';
+import { extractComponentChecksums } from './furnace-checksum-utils.js';
 /** Creates a normalized validation issue object. */
 export function createIssue(component, severity, check, message) {
     return { component, severity, check, message };
@@ -282,7 +283,7 @@ export function hasCustomElementDefineCall(mjsContent) {
  * `furnace override` of a valid upstream component fails its own
  * `furnace validate` pass with nothing the operator can fix.
  */
-export function hasCustomElementExtendsOption(mjsContent) {
+function hasCustomElementExtendsOption(mjsContent) {
     // Match `customElements.define(..., { ..., extends: "..." })`. Tolerant of
     // whitespace, line breaks, and other object properties. The `[^)]*` stops
     // the inner greedy match at the closing define call paren so a later
@@ -395,4 +396,42 @@ export async function getTokenPrefixContext(tagName, type, config, root) {
         runtimeVariables,
     };
 }
+/**
+ * Flags engine-side files that a previous deploy of `tagName` left behind
+ * after their workspace source was renamed or removed (field report D1).
+ *
+ * Detection keys on the furnace state file: every `appliedChecksums` entry
+ * under `custom/<tagName>/` whose workspace source no longer exists but
+ * whose engine target is still present is an orphan — the next deploy will
+ * prune it, but until then jar.mn and the deployed directory disagree with
+ * the workspace, and a re-export could capture the stale state into a patch.
+ *
+ * Custom components only: override undeploys restore the upstream baseline
+ * rather than deleting files, so "orphan" has no meaning there.
+ */
+export async function findOrphanedEngineFiles(root, config, tagName, state, ftlDir) {
+    const customConfig = config.custom[tagName];
+    if (!customConfig)
+        return [];
+    const previous = extractComponentChecksums(state.appliedChecksums, 'custom', tagName);
+    const fileNames = Object.keys(previous);
+    if (fileNames.length === 0)
+        return [];
+    const { engine: engineDir, componentsDir } = getProjectPaths(root);
+    const componentDir = join(componentsDir, 'custom', tagName);
+    const issues = [];
+    for (const fileName of fileNames) {
+        if (await pathExists(join(componentDir, fileName)))
+            continue;
+        const enginePath = fileName.endsWith('.ftl')
+            ? join(engineDir, ftlDir, fileName)
+            : join(engineDir, customConfig.targetPath, fileName);
+        if (!(await pathExists(enginePath)))
+            continue;
+        issues.push(createIssue(tagName, 'warning', 'orphaned-engine-file', `Engine file ${fileName} was deployed by a previous apply but its workspace source ` +
+            `is gone (renamed or deleted). The deployed copy${customConfig.register ? ' and any stale jar.mn entry' : ''} ` +
+            `will linger until the next deploy prunes it. Run "fireforge furnace deploy ${tagName}".`));
+    }
+    return issues;
+}
 //# sourceMappingURL=furnace-validate-helpers.js.map

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

@@ -9,6 +9,7 @@ import { stripJsComments } from '../utils/regex.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths } from './furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, FTL_DIR, JAR_MN } from './furnace-constants.js';
+import { expandCssFragments, listFragmentIncludes } from './furnace-css-fragments.js';
 import { isTagInCorrectCustomElementsPlacement } from './furnace-registration-validate.js';
 import { getTokensCssPath } from './token-manager.js';
 /**
@@ -96,7 +97,21 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
                 status.filesInSync = false;
                 continue;
             }
-            const srcContent = await readText(srcPath);
+            // Deploy writes CSS-with-include-directives in fragment-expanded form,
+            // so the drift oracle must compare the *expanded* source — otherwise a
+            // freshly deployed component would read as permanently drifted, and a
+            // fragment edit would never read as drifted at all.
+            let srcContent = await readText(srcPath);
+            if (entry.name.endsWith('.css') && listFragmentIncludes(srcContent).length > 0) {
+                try {
+                    srcContent = (await expandCssFragments(srcContent, furnacePaths.sharedDir)).expanded;
+                }
+                catch {
+                    // Missing fragment: validate reports it as `missing-fragment`;
+                    // for drift purposes fall back to the raw source so the compare
+                    // still happens deterministically.
+                }
+            }
             const destContent = await readText(destPath);
             const srcHash = createHash('sha256').update(srcContent).digest('hex');
             const destHash = createHash('sha256').update(destContent).digest('hex');

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

@@ -3,10 +3,13 @@ import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathExists } from '../utils/fs.js';
 import { getProjectPaths, loadConfig } from './config.js';
-import { getFurnacePaths, loadFurnaceConfig } from './furnace-config.js';
-import { xpcshellTestParentDir } from './furnace-constants.js';
+import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState } from './furnace-config.js';
+import { resolveFtlDir, xpcshellTestParentDir } from './furnace-constants.js';
+import { validateCssFragments } from './furnace-css-fragments.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
+import { findJsconfigPathsDrift } from './furnace-jsconfig.js';
 import { validateAccessibility, validateCompatibility, validateJarMnEntries, validateRegistrationPatterns, validateStructure, validateTokenLink, } from './furnace-validate-checks.js';
+import { findOrphanedEngineFiles } from './furnace-validate-helpers.js';
 import { findOverrideBaseVersionDrift, } from './furnace-version-drift.js';
 function buildOverrideVersionDriftIssues(config, currentVersion, tagName) {
     return findOverrideBaseVersionDrift(config, currentVersion)
@@ -55,6 +58,25 @@ export async function validateComponent(componentDir, tagName, type, config, roo
     if (root) {
         issues.push(...(await validateTokenLink(componentDir, tagName, root, config?.tokenPrefix, config?.tokenHostDocuments)));
     }
+    // CSS fragment checks (field report D2): missing fragment files are
+    // structural errors; stale deployed expansions are drift the next deploy
+    // refreshes.
+    if (type === 'custom') {
+        const furnacePaths = getFurnacePaths(root ?? join(componentDir, '..', '..', '..'));
+        const engineTargetDir = root && config?.custom[tagName]
+            ? join(getProjectPaths(root).engine, config.custom[tagName].targetPath)
+            : undefined;
+        issues.push(...(await validateCssFragments(componentDir, tagName, furnacePaths.sharedDir, engineTargetDir)));
+    }
+    // Engine-side orphan detection (field report D1): files a previous deploy
+    // placed in the engine whose workspace source has since been renamed or
+    // deleted. Surfaces as drift even when every current workspace file is
+    // in sync, which is exactly the gap that let stale jar.mn lines reach a
+    // later re-export.
+    if (root && config && type === 'custom') {
+        const state = await loadFurnaceState(root);
+        issues.push(...(await findOrphanedEngineFiles(root, config, tagName, state, resolveFtlDir(config.ftlBasePath))));
+    }
     // When root is provided and this is a custom component with registration,
     // also run registration pattern and jar.mn validation for this component.
     // Skipped when an outer orchestrator (validateAllComponents) will run the
@@ -202,6 +224,36 @@ export async function validateAllComponents(root) {
         // other transient fs issue should never cascade into false
         // "orphan" reports.
     }
+    // jsconfig chrome-module paths drift (field report D3): when
+    // `typecheckJsconfig` is configured, deploy maintains a paths mapping per
+    // deployed module file; missing or stale entries mean typed cross-module
+    // imports are silently degrading to `any` in the consumer's typecheck.
+    if (config.typecheckJsconfig) {
+        try {
+            const drift = await findJsconfigPathsDrift(root, config);
+            if (drift.changed) {
+                const detail = [
+                    ...drift.added.map((key) => `missing: ${key}`),
+                    ...drift.updated.map((key) => `stale: ${key}`),
+                    ...drift.pruned.map((key) => `orphaned: ${key}`),
+                ].join('; ');
+                const issue = {
+                    component: 'furnace',
+                    severity: 'warning',
+                    check: 'jsconfig-paths-drift',
+                    message: `${config.typecheckJsconfig} chrome-module paths are out of sync with the workspace (${detail}). ` +
+                        'Run "fireforge furnace deploy" to update them.',
+                };
+                const existing = results.get(issue.component) ?? [];
+                existing.push(issue);
+                results.set(issue.component, existing);
+            }
+        }
+        catch {
+            // Drift detection must not break validation when the jsconfig is
+            // missing or unparsable — deploy reports those cases with guidance.
+        }
+    }
     return results;
 }
 /**

package/dist/src/core/git-base.d.ts

@@ -63,6 +63,21 @@ export declare function git(args: string[], cwd: string, options?: {
     timeout?: number;
     env?: Record<string, string>;
 }): Promise<string>;
+/**
+ * Splits a pathspec list into chunks whose joined byte length stays well under
+ * the OS `ARG_MAX` limit, so a single batched `git` invocation over hundreds of
+ * Mozilla-length paths cannot fail with `E2BIG`. The 96 KB budget is
+ * deliberately conservative — even the smallest historical `ARG_MAX` (256 KB)
+ * leaves room for the fixed git arguments plus the inherited environment.
+ *
+ * Chunk boundaries are output-neutral for every batched caller here: each
+ * caller merges the per-chunk results into a single Set/Map keyed by path, so
+ * how the paths are grouped across invocations never affects the result.
+ * @param paths - Pathspecs to chunk
+ * @param budgetBytes - Maximum joined byte length per chunk
+ * @returns Path chunks, each safe to pass as a single argv tail
+ */
+export declare function chunkPathspecs(paths: string[], budgetBytes?: number): string[][];
 /**
  * Configures git performance settings for large trees.
  * Enables index preloading, untracked cache, and the manyFiles feature

package/dist/src/core/git-base.js

@@ -72,6 +72,38 @@ export async function git(args, cwd, options) {
     }
     return result.stdout;
 }
+/**
+ * Splits a pathspec list into chunks whose joined byte length stays well under
+ * the OS `ARG_MAX` limit, so a single batched `git` invocation over hundreds of
+ * Mozilla-length paths cannot fail with `E2BIG`. The 96 KB budget is
+ * deliberately conservative — even the smallest historical `ARG_MAX` (256 KB)
+ * leaves room for the fixed git arguments plus the inherited environment.
+ *
+ * Chunk boundaries are output-neutral for every batched caller here: each
+ * caller merges the per-chunk results into a single Set/Map keyed by path, so
+ * how the paths are grouped across invocations never affects the result.
+ * @param paths - Pathspecs to chunk
+ * @param budgetBytes - Maximum joined byte length per chunk
+ * @returns Path chunks, each safe to pass as a single argv tail
+ */
+export function chunkPathspecs(paths, budgetBytes = 96_000) {
+    const chunks = [];
+    let current = [];
+    let used = 0;
+    for (const path of paths) {
+        const cost = Buffer.byteLength(path) + 1;
+        if (current.length > 0 && used + cost > budgetBytes) {
+            chunks.push(current);
+            current = [];
+            used = 0;
+        }
+        current.push(path);
+        used += cost;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
 /**
  * Configures git performance settings for large trees.
  * Enables index preloading, untracked cache, and the manyFiles feature

package/dist/src/core/git-diff.d.ts

@@ -40,6 +40,14 @@ export declare function getAllDiff(repoDir: string): Promise<string>;
  * Builds a combined diff against HEAD for the provided files without touching
  * the real git index. Tracked files use `git diff HEAD`; untracked files use
  * synthesized new-file diffs.
+ *
+ * Performance: the work is batched into a handful of `git` invocations
+ * (one `ls-tree` to classify, one `diff` over all tracked files, one
+ * `hash-object` over all new text files) rather than the ~2 spawns per file the
+ * previous per-file loop issued — that fan-out dominated the cold-run cost on a
+ * Firefox-sized checkout (~700 serial spawns, ~99s). Binary, directory, and
+ * recursion paths stay per-file because they are rare and (for binary) mutate
+ * the index.
  * @param repoDir - Repository directory
  * @param files - File paths to diff (relative to repo root)
  * @returns Combined diff content