@hominis/fireforge 0.30.0 → 0.31.0

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

@@ -0,0 +1,171 @@
+// 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;
+            const sourcePath = normalizePathSlashes(relative(jsconfigDir, join(componentDir, file)));
+            entries[`${CHROME_ELEMENTS_URL_PREFIX}${file}`] = [sourcePath];
+        }
+    }
+    return entries;
+}
+/** 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;
+        }
+        if (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-file-ops.d.ts

@@ -5,18 +5,6 @@ import type { GitStatusEntry } from './git-base.js';
  * @param filePath - Path to the file (relative to repo)
  */
 export declare function restoreTrackedPath(repoDir: string, filePath: string): Promise<void>;
-/**
- * Removes an untracked path from disk.
- * @param repoDir - Repository directory
- * @param filePath - Path to the file (relative to repo)
- */
-export declare function removeUntrackedPath(repoDir: string, filePath: string): Promise<void>;
-/**
- * Removes a path that is present only in the index/worktree and not in HEAD.
- * @param repoDir - Repository directory
- * @param filePath - Path to remove
- */
-export declare function removeAddedPath(repoDir: string, filePath: string): Promise<void>;
 /**
  * Discards a status entry according to its git state.
  * @param repoDir - Repository directory

package/dist/src/core/git-file-ops.js

@@ -19,7 +19,7 @@ export async function restoreTrackedPath(repoDir, filePath) {
  * @param repoDir - Repository directory
  * @param filePath - Path to the file (relative to repo)
  */
-export async function removeUntrackedPath(repoDir, filePath) {
+async function removeUntrackedPath(repoDir, filePath) {
     const fullPath = join(repoDir, filePath);
     await removeFile(fullPath);
 }
@@ -28,7 +28,7 @@ export async function removeUntrackedPath(repoDir, filePath) {
  * @param repoDir - Repository directory
  * @param filePath - Path to remove
  */
-export async function removeAddedPath(repoDir, filePath) {
+async function removeAddedPath(repoDir, filePath) {
     await ensureGit();
     await git(['reset', 'HEAD', '--', filePath], repoDir);
     await removeUntrackedPath(repoDir, filePath);

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

@@ -2,7 +2,6 @@ import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type PatchQueueContext } from './patch-lint.js';
 export declare const LINT_CACHE_SCHEMA_VERSION = 1;
-export declare const LINT_IMPLEMENTATION_VERSION = 1;
 export interface PerPatchLintCacheEntry {
     key: string;
     patchFilename: string;
@@ -21,24 +20,16 @@ export interface PerPatchLintCacheKeyInput {
     existingFiles: string[];
     config: FireForgeConfig;
     queueContext: PatchQueueContext;
+    engineHeadSha?: string;
     packageVersion?: string;
 }
-type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue | undefined;
-};
-/** Computes a SHA-256 hex digest for text or binary content. */
-export declare function sha256Hex(content: string | Buffer): string;
-/** Computes a stable SHA-256 digest for JSON-compatible data. */
-export declare function stableHash(value: JsonValue): string;
-/** Returns the repo-local per-patch lint cache file path. */
-export declare function getPerPatchLintCachePath(projectRoot: string): string;
+/** Returns the engine git HEAD identity used to guard diff-derived cache hits. */
+export declare function getPerPatchLintCacheHeadSha(engineDir: string): Promise<string>;
 /**
  * Builds the complete per-patch lint cache key for one lintable patch.
  * The key includes source, metadata, config, engine state, and ownership inputs.
  */
 export declare function buildPerPatchLintCacheKey(input: PerPatchLintCacheKeyInput): Promise<string>;
-/** Creates an empty cache document using the current cache schema. */
-export declare function createEmptyPerPatchLintCache(): PerPatchLintCacheFile;
 /** Loads the per-patch lint cache, treating missing or invalid files as empty. */
 export declare function loadPerPatchLintCache(projectRoot: string): Promise<PerPatchLintCacheFile>;
 /** Persists the per-patch lint cache atomically through the shared JSON writer. */
@@ -49,4 +40,3 @@ export declare function clearPerPatchLintCache(projectRoot: string): Promise<voi
 export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string): PatchLintIssue[] | undefined;
 /** Stores per-patch lint issues after a successful lint calculation. */
 export declare function setCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, issues: PatchLintIssue[]): void;
-export {};

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

@@ -5,9 +5,10 @@ import { join, resolve } from 'node:path';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { getPackageVersion } from '../utils/package-root.js';
 import { getFurnacePaths } from './furnace-config.js';
+import { git } from './git-base.js';
 import { collectNewFileCreatorsByPath } from './patch-lint.js';
 export const LINT_CACHE_SCHEMA_VERSION = 1;
-export const LINT_IMPLEMENTATION_VERSION = 1;
+const LINT_IMPLEMENTATION_VERSION = 1;
 const LINT_CACHE_DIRNAME = 'lint-cache';
 const PER_PATCH_CACHE_FILENAME = 'per-patch-v1.json';
 function stableJson(value) {
@@ -25,17 +26,21 @@ function stableJson(value) {
         .join(',')}}`;
 }
 /** Computes a SHA-256 hex digest for text or binary content. */
-export function sha256Hex(content) {
+function sha256Hex(content) {
     return createHash('sha256').update(content).digest('hex');
 }
 /** Computes a stable SHA-256 digest for JSON-compatible data. */
-export function stableHash(value) {
+function stableHash(value) {
     return sha256Hex(stableJson(value));
 }
 /** Returns the repo-local per-patch lint cache file path. */
-export function getPerPatchLintCachePath(projectRoot) {
+function getPerPatchLintCachePath(projectRoot) {
     return join(projectRoot, '.fireforge', LINT_CACHE_DIRNAME, PER_PATCH_CACHE_FILENAME);
 }
+/** Returns the engine git HEAD identity used to guard diff-derived cache hits. */
+export async function getPerPatchLintCacheHeadSha(engineDir) {
+    return (await git(['rev-parse', 'HEAD'], engineDir)).trim();
+}
 async function fileHash(path) {
     if (!(await pathExists(path))) {
         return { exists: false };
@@ -90,6 +95,7 @@ export async function buildPerPatchLintCacheKey(input) {
         };
     return stableHash({
         cacheSchemaVersion: LINT_CACHE_SCHEMA_VERSION,
+        engineHeadSha: input.engineHeadSha ?? null,
         lintImplementationVersion: LINT_IMPLEMENTATION_VERSION,
         packageVersion: input.packageVersion ?? getPackageVersion(),
         patchFile: await fileHash(join(input.patchesDir, input.patch.filename)),
@@ -102,7 +108,7 @@ export async function buildPerPatchLintCacheKey(input) {
     });
 }
 /** Creates an empty cache document using the current cache schema. */
-export function createEmptyPerPatchLintCache() {
+function createEmptyPerPatchLintCache() {
     return { schemaVersion: LINT_CACHE_SCHEMA_VERSION, entries: {} };
 }
 function isCacheEntry(value) {

package/dist/src/core/mach.d.ts

@@ -193,5 +193,9 @@ export declare function watchWithOutput(engineDir: string, options?: {
 export declare function test(engineDir: string, testPaths?: string[], args?: string[]): Promise<number>;
 /**
  * Runs mach test while capturing streamed output for better diagnostics.
+ *
+ * @param env - Optional extra environment variables for the mach process
+ *   (merged over `process.env` by the exec layer). Used by
+ *   `fireforge test --perf-samples` to publish the artifact-path contract.
  */
-export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[]): Promise<MachCommandResult>;
+export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;

package/dist/src/core/mach.js

@@ -312,8 +312,12 @@ export async function test(engineDir, testPaths = [], args = []) {
 }
 /**
  * Runs mach test while capturing streamed output for better diagnostics.
+ *
+ * @param env - Optional extra environment variables for the mach process
+ *   (merged over `process.env` by the exec layer). Used by
+ *   `fireforge test --perf-samples` to publish the artifact-path contract.
  */
-export async function testWithOutput(engineDir, testPaths = [], args = []) {
-    return runMachCapture(['test', ...testPaths, ...args], engineDir);
+export async function testWithOutput(engineDir, testPaths = [], args = [], env) {
+    return runMachCapture(['test', ...testPaths, ...args], engineDir, env ? { env } : {});
 }
 //# sourceMappingURL=mach.js.map

package/dist/src/core/manifest-register.d.ts

@@ -1,22 +1,11 @@
 /**
  * Manifest registration barrel — re-exports all registration targets
- * and provides the shared RegisterResult interface.
+ * and the shared RegisterResult interface (which lives in
+ * `register-result.ts` so the leaf modules can import it without
+ * creating a cycle through this barrel).
  */
-/**
- * Result of a manifest registration operation.
- */
-export interface RegisterResult {
-    /** The manifest file that was modified */
-    manifest: string;
-    /** The entry that was inserted */
-    entry: string;
-    /** The entry after which the new entry was inserted (for user display) */
-    previousEntry?: string | undefined;
-    /** Whether the entry already existed (skipped) */
-    skipped: boolean;
-    /** Whether --after target was not found and fell back to alphabetical */
-    afterFallback?: boolean | undefined;
-}
+import type { RegisterResult } from './register-result.js';
+export type { RegisterResult } from './register-result.js';
 export { registerBrowserContent } from './register-browser-content.js';
 export { registerFireForgeModule } from './register-module.js';
 export { registerSharedCSS } from './register-shared-css.js';

package/dist/src/core/manifest-register.js

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Manifest registration barrel — re-exports all registration targets
- * and provides the shared RegisterResult interface.
+ * and the shared RegisterResult interface (which lives in
+ * `register-result.ts` so the leaf modules can import it without
+ * creating a cycle through this barrel).
  */
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';