@hominis/fireforge 0.15.9 → 0.16.1

package/dist/src/core/test-stale-check.js

@@ -23,6 +23,9 @@
  * plugin, etc.) can legitimately have a fresh `dist/` with no
  * FireForge-recorded baseline update.
  */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
 import { isPackageablePath } from './build-audit.js';
@@ -90,7 +93,32 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
         return { stale: false, changedPaths: [], truncated: 0, baseline: undefined };
     }
     const changed = await collectChangedEnginePaths(engineDir, baseline);
-    const packageable = changed.filter((path) => isPackageablePath(path)).sort();
+    let packageable = changed.filter((path) => isPackageablePath(path)).sort();
+    // Content-hash comparison: when the baseline carries a fingerprint set,
+    // fold each candidate path through a live re-hash and drop paths whose
+    // current content matches the baseline. Pre-0.16.0 baselines have no
+    // `packageableFingerprints` field; those fall through and the
+    // path-only comparison behaves as before (every workdir-dirty
+    // packageable path is reported as stale). The concrete motivating
+    // case: a project with imported patches + Furnace-applied components
+    // always has a persistent workdir diff against HEAD. Before the
+    // fingerprint layer, `git diff --name-only HEAD` returned that diff
+    // on every build, so the stale check fired immediately after a
+    // successful build even though nothing had actually changed. The
+    // fingerprints capture "these files had this content when the build
+    // ran"; a path stays stale only when its live hash diverges.
+    const fingerprints = baseline.packageableFingerprints;
+    if (fingerprints) {
+        const staleAfterHashCheck = [];
+        for (const path of packageable) {
+            const recorded = fingerprints[path];
+            const live = await hashEngineFile(engineDir, path);
+            if (recorded === undefined || live === undefined || recorded !== live) {
+                staleAfterHashCheck.push(path);
+            }
+        }
+        packageable = staleAfterHashCheck;
+    }
     if (packageable.length === 0) {
         return { stale: false, changedPaths: [], truncated: 0, baseline };
     }
@@ -98,6 +126,23 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     const truncated = Math.max(0, packageable.length - head.length);
     return { stale: true, changedPaths: head, truncated, baseline };
 }
+/**
+ * Reads a file under the engine directory and returns a hex-encoded
+ * SHA-256 of its contents, matching the hash the baseline writer
+ * produces. Returns `undefined` on any IO error (missing file,
+ * permission denied, etc.) so the caller can treat the path as still
+ * stale rather than crashing the preflight.
+ */
+async function hashEngineFile(engineDir, relPath) {
+    try {
+        const buffer = await readFile(join(engineDir, relPath));
+        return createHash('sha256').update(buffer).digest('hex');
+    }
+    catch (error) {
+        verbose(`Stale-build preflight: could not hash ${relPath} for baseline comparison — ${toError(error).message}`);
+        return undefined;
+    }
+}
 /**
  * Formats a human-readable warning body from a {@link StaleBuildResult}.
  * Kept separate from the probe so test code can assert on the structured

package/dist/src/core/token-manager.js

@@ -93,8 +93,56 @@ async function assertTokenCategoryExists(engineDir, tokensCssPath, category) {
             }
         }
     }
-    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}. ` +
-        'Available categories are defined by /* =... category ...= */ comment headers.');
+    const discoveredCategories = discoverCategoryHeaders(lines);
+    const available = discoveredCategories.length > 0
+        ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
+        : 'The file currently has no category headers. Add one by hand near the top of the :root { … } block — the format is "/* = My Category = */" — or run "fireforge furnace init --force" to re-scaffold the default seed set.';
+    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
+        `${available}\n\n` +
+        'Categories are declared by comment headers. Single-line shape: /* = My Category = */. ' +
+        'Multi-line shape: /* =============\\n * My Category\\n * ============= */.');
+}
+/**
+ * Scans a tokens CSS file for category header comments and returns the
+ * category names in document order. Used to enrich the "category not
+ * found" error body with concrete alternatives the operator can copy.
+ *
+ * Mirrors the shapes `findCategorySection` already recognises:
+ * - Single-line: `/* = Foo = *\/`
+ * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
+ *   closing `*\/`.
+ *
+ * This helper exists as a pure inspector; it never throws on malformed
+ * headers and silently skips shapes it cannot parse.
+ */
+function discoverCategoryHeaders(lines) {
+    const categories = new Set();
+    const singleLinePattern = /\/\*\s*=+\s*(.+?)\s*=+\s*\*\//;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const singleMatch = singleLinePattern.exec(line);
+        if (singleMatch?.[1]) {
+            const extracted = singleMatch[1].trim();
+            if (extracted.length > 0)
+                categories.add(extracted);
+            continue;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (/\*\//.test(blockLine))
+                    break;
+                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
+                if (trimmed.length === 0)
+                    continue;
+                if (/^=+$/.test(trimmed))
+                    continue;
+                categories.add(trimmed);
+                break;
+            }
+        }
+    }
+    return [...categories];
 }
 /**
  * Validates token-add inputs without mutating files.
@@ -187,8 +235,13 @@ function findCategorySection(lines, category, tokensCssPath) {
         }
     }
     if (categoryLine === -1) {
-        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}. ` +
-            'Available categories are defined by /* =... category ...= */ comment headers.');
+        const discoveredCategories = discoverCategoryHeaders(lines);
+        const available = discoveredCategories.length > 0
+            ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
+            : 'The file currently has no category headers.';
+        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
+            `${available}\n\n` +
+            'Add a header by hand inside the :root block (format: "/* = My Category = */") or re-run "fireforge furnace init --force" to re-seed the default categories.');
     }
     // Find the end of this category section (next section header or closing })
     // Handles both single-line (/* =...= */) and multi-line (/* ===...) section delimiters

package/dist/src/core/token-scaffold.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Scaffolds the default tokens CSS file consumed by `fireforge token add`.
+ *
+ * Before 0.16.0 `fireforge furnace init` wrote `furnace.json` but not the
+ * tokens CSS — every project's first `fireforge token add` hit
+ * `Token CSS file not found: browser/themes/shared/<binaryName>-tokens.css`.
+ * The 0.16.0 init now calls into this module to write a canonical
+ * `:root { … }` shell with a seed set of category headers that
+ * `assertTokenCategoryExists` recognises, and registers the tokens CSS
+ * path in `patchLint.rawColorAllowlist` so the first token that's an
+ * actual color value does not instantly fail `fireforge lint`.
+ */
+import type { ProjectLicense } from '../types/config.js';
+/**
+ * The set of categories seeded by the default scaffold. `token add
+ * --category <name>` accepts any of these without further setup; an
+ * operator who needs another category only has to add a matching
+ * `/* = My Category = *\/` header inside the `:root` block by hand.
+ *
+ * The names intentionally mirror the vocabulary used in Firefox's own
+ * token files (Colors — Canvas, Spacing, …) so operators coming from
+ * upstream don't have to relearn a fork-specific taxonomy.
+ */
+export declare const DEFAULT_TOKEN_CATEGORIES: readonly string[];
+/**
+ * Generates the default tokens CSS body. Extracted from the init
+ * command so tests can assert on the generated shape without running
+ * the interactive scaffold flow.
+ *
+ * @param binaryName - `fireforge.json` `binaryName` used in the
+ *   rendered file banner so operators can identify the fork on-sight.
+ * @param license - Project license; piped through `getLicenseHeader`
+ *   so the scaffold is SPDX-marked and survives `fireforge lint`'s
+ *   license-header checks without operator intervention.
+ */
+export declare function generateDefaultTokensCss(binaryName: string, license: ProjectLicense): string;

package/dist/src/core/token-scaffold.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Scaffolds the default tokens CSS file consumed by `fireforge token add`.
+ *
+ * Before 0.16.0 `fireforge furnace init` wrote `furnace.json` but not the
+ * tokens CSS — every project's first `fireforge token add` hit
+ * `Token CSS file not found: browser/themes/shared/<binaryName>-tokens.css`.
+ * The 0.16.0 init now calls into this module to write a canonical
+ * `:root { … }` shell with a seed set of category headers that
+ * `assertTokenCategoryExists` recognises, and registers the tokens CSS
+ * path in `patchLint.rawColorAllowlist` so the first token that's an
+ * actual color value does not instantly fail `fireforge lint`.
+ */
+import { getLicenseHeader } from './license-headers.js';
+/**
+ * The set of categories seeded by the default scaffold. `token add
+ * --category <name>` accepts any of these without further setup; an
+ * operator who needs another category only has to add a matching
+ * `/* = My Category = *\/` header inside the `:root` block by hand.
+ *
+ * The names intentionally mirror the vocabulary used in Firefox's own
+ * token files (Colors — Canvas, Spacing, …) so operators coming from
+ * upstream don't have to relearn a fork-specific taxonomy.
+ */
+export const DEFAULT_TOKEN_CATEGORIES = [
+    'Colors — General',
+    'Colors — Canvas',
+    'Colors — Experiment',
+    'Spacing',
+];
+/**
+ * Generates the default tokens CSS body. Extracted from the init
+ * command so tests can assert on the generated shape without running
+ * the interactive scaffold flow.
+ *
+ * @param binaryName - `fireforge.json` `binaryName` used in the
+ *   rendered file banner so operators can identify the fork on-sight.
+ * @param license - Project license; piped through `getLicenseHeader`
+ *   so the scaffold is SPDX-marked and survives `fireforge lint`'s
+ *   license-header checks without operator intervention.
+ */
+export function generateDefaultTokensCss(binaryName, license) {
+    const header = getLicenseHeader(license, 'css');
+    const categoryBlocks = DEFAULT_TOKEN_CATEGORIES.map((category) => `  /* = ${category} = */\n  /* (add design tokens for "${category}" here; use \`fireforge token add --category "${category}" …\`) */`).join('\n\n');
+    return `${header}
+
+/*
+ * Design tokens for ${binaryName}.
+ *
+ * Scaffolded by \`fireforge furnace init\`. Add new tokens with
+ * \`fireforge token add --category '<name>' -- <token-name> <value>\`
+ * — the command appends into the matching \`/* = <name> = *\\/\` block
+ * below and keeps the per-category ordering stable.
+ *
+ * Raw color literals inside this file are expected — the whole point
+ * of the tokens layer is that every other CSS file consumes \`var(…)\`
+ * instead of literal colors. \`fireforge furnace init\` adds this
+ * file's path to \`patchLint.rawColorAllowlist\` in fireforge.json so
+ * \`fireforge lint\` stops flagging the literals here.
+ */
+
+:root {
+${categoryBlocks}
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    /* Dark-mode overrides land here. Use \`fireforge token add --mode override --dark-value <v>\`
+       to have a token's dark value placed inside this block. */
+  }
+}
+`;
+}
+//# sourceMappingURL=token-scaffold.js.map

package/dist/src/types/commands/options.d.ts

@@ -372,6 +372,16 @@ export interface FurnaceCreateOptions {
      * dry-run faithfully previews the real command's outcome.
      */
     dryRun?: boolean;
+    /**
+     * Bypass the configured `componentPrefix` check for the supplied name.
+     * Without this flag, a name that does not start with the prefix is
+     * rejected before any files are written, so a prefix-mismatched
+     * component cannot leave behind a half-scaffolded state. Pass this
+     * flag only when you know the prefix mismatch is intentional — e.g.
+     * creating an experimental component whose name intentionally breaks
+     * the fork's convention.
+     */
+    allowPrefixMismatch?: boolean;
 }
 /**
  * Options for the wire command.

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

@@ -78,6 +78,18 @@ export declare function writeFileAtomic(path: string, content: string | Buffer):
  * @param dest - Destination directory path
  */
 export declare function copyDir(src: string, dest: string): Promise<void>;
+/**
+ * Matches the atomic-temp-file shape emitted by `createAtomicTempPath`
+ * anywhere in a normalised (forward-slash) path. The `.fireforge-tmp-`
+ * marker plus a PID/UUID tail is unique to our own rename-based atomic
+ * writes, so callers (notably `status`) can filter these mid-flight
+ * artefacts out of their listings without racing the rename.
+ *
+ * Intentionally anchored so a legitimately-named backup file like
+ * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is NOT treated
+ * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
+ */
+export declare const FIREFORGE_TMP_PATH_PATTERN: RegExp;
 /**
  * Checks available disk space at a path and warns via the provided
  * callback when it falls below `minBytes`.

package/dist/src/utils/fs.js

@@ -180,6 +180,18 @@ export async function copyDir(src, dest) {
         }
     }
 }
+/**
+ * Matches the atomic-temp-file shape emitted by `createAtomicTempPath`
+ * anywhere in a normalised (forward-slash) path. The `.fireforge-tmp-`
+ * marker plus a PID/UUID tail is unique to our own rename-based atomic
+ * writes, so callers (notably `status`) can filter these mid-flight
+ * artefacts out of their listings without racing the rename.
+ *
+ * Intentionally anchored so a legitimately-named backup file like
+ * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is NOT treated
+ * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
+ */
+export const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9a-f-]{36}$/i;
 /**
  * Generates a unique temp file path for atomic writes.
  *

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

@@ -1,5 +1,24 @@
 /** Converts Windows path separators to forward slashes for stable comparisons. */
 export declare function normalizePathSlashes(path: string): string;
+/**
+ * Strips a leading `engine/` (or `engine\\`) segment from a user-supplied
+ * path so the same command invocation accepts both repo-root-relative paths
+ * (`engine/browser/base/content/foo.js`) and engine-relative paths
+ * (`browser/base/content/foo.js`). The match is case-insensitive because
+ * default macOS and Windows filesystems treat `Engine/` and `engine/` as
+ * the same directory; a literal lowercase-only check previously left `mach`
+ * / the manifest writers resolving against a wrongly-cased prefix. Leading
+ * whitespace is ignored so tab-completed inputs don't slip past the strip.
+ *
+ * The return value is trimmed of the same leading whitespace when the
+ * prefix matched, and otherwise passed through verbatim — callers that
+ * care about internal whitespace can trim on their side.
+ *
+ * @param filePath Path as provided by the user
+ * @returns Path relative to the engine directory (or the original when the
+ *          prefix was absent)
+ */
+export declare function stripEnginePrefix(filePath: string): string;
 /** Checks whether a path is explicitly absolute on either POSIX or Windows. */
 export declare function isExplicitAbsolutePath(path: string): boolean;
 /** Resolves a candidate path and returns whether it stays within the given root. */

package/dist/src/utils/paths.js

@@ -2,10 +2,43 @@
 import { isAbsolute, relative, resolve } from 'node:path';
 const WINDOWS_ABSOLUTE_PATH = /^[a-zA-Z]:[\\/]/;
 const RELATIVE_PATH_ROOT = resolve('/__fireforge_path_root__');
+/**
+ * Matches a leading `engine/` or `engine\\` segment (case-insensitive,
+ * tolerates leading whitespace). Shared between `register`, `test`, `lint`,
+ * and `export` so every command that takes an engine-relative path accepts
+ * both the repo-root form (`engine/browser/...`) and the engine-relative
+ * form (`browser/...`) without diverging.
+ */
+const ENGINE_PREFIX_PATTERN = /^\s*engine[/\\]/i;
 /** Converts Windows path separators to forward slashes for stable comparisons. */
 export function normalizePathSlashes(path) {
     return path.replace(/\\/g, '/');
 }
+/**
+ * Strips a leading `engine/` (or `engine\\`) segment from a user-supplied
+ * path so the same command invocation accepts both repo-root-relative paths
+ * (`engine/browser/base/content/foo.js`) and engine-relative paths
+ * (`browser/base/content/foo.js`). The match is case-insensitive because
+ * default macOS and Windows filesystems treat `Engine/` and `engine/` as
+ * the same directory; a literal lowercase-only check previously left `mach`
+ * / the manifest writers resolving against a wrongly-cased prefix. Leading
+ * whitespace is ignored so tab-completed inputs don't slip past the strip.
+ *
+ * The return value is trimmed of the same leading whitespace when the
+ * prefix matched, and otherwise passed through verbatim — callers that
+ * care about internal whitespace can trim on their side.
+ *
+ * @param filePath Path as provided by the user
+ * @returns Path relative to the engine directory (or the original when the
+ *          prefix was absent)
+ */
+export function stripEnginePrefix(filePath) {
+    const match = ENGINE_PREFIX_PATTERN.exec(filePath);
+    if (match) {
+        return filePath.slice(match[0].length);
+    }
+    return filePath;
+}
 /** Checks whether a path is explicitly absolute on either POSIX or Windows. */
 export function isExplicitAbsolutePath(path) {
     return isAbsolute(path) || WINDOWS_ABSOLUTE_PATH.test(path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.15.9",
+  "version": "0.16.1",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",