@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/utils/stdio-drain.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Bounded stdio drain for delayed process exits (FORGE I1).
+ *
+ * `process.exit()` discards whatever is still queued in an async writable —
+ * and stdout IS async when it is a pipe, with a 64 KiB kernel buffer on
+ * macOS/Linux. The observed failure: `status --json --fail-on` writes a
+ * 176 KB payload, the refusal makes `bin/fireforge.ts` exit non-zero, and a
+ * piped consumer receives exactly 65 536 bytes. The bin entry point awaits
+ * this helper before every delayed exit; the helper itself never calls
+ * `process.exit` (the process-boundary test keeps that a bin-only right).
+ */
+/**
+ * The structural slice of `Writable` the drain wait needs — accepted instead
+ * of `NodeJS.WriteStream` so unit tests can drive synthetic streams.
+ */
+export interface DrainableStream {
+    readonly destroyed: boolean;
+    readonly writableFinished: boolean;
+    readonly writableLength: number;
+    on(event: 'drain' | 'error' | 'close', listener: () => void): unknown;
+    off(event: 'drain' | 'error' | 'close', listener: () => void): unknown;
+}
+/**
+ * Waits (bounded by `timeoutMs`) for every given stream — stdout and stderr
+ * by default — to drain. Resolution is unconditional; the caller exits
+ * either way, the bound only decides how much queued output survives.
+ */
+export declare function waitForStdioDrain(timeoutMs: number, streams?: readonly DrainableStream[]): Promise<void>;

package/dist/src/utils/stdio-drain.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Bounded stdio drain for delayed process exits (FORGE I1).
+ *
+ * `process.exit()` discards whatever is still queued in an async writable —
+ * and stdout IS async when it is a pipe, with a 64 KiB kernel buffer on
+ * macOS/Linux. The observed failure: `status --json --fail-on` writes a
+ * 176 KB payload, the refusal makes `bin/fireforge.ts` exit non-zero, and a
+ * piped consumer receives exactly 65 536 bytes. The bin entry point awaits
+ * this helper before every delayed exit; the helper itself never calls
+ * `process.exit` (the process-boundary test keeps that a bin-only right).
+ */
+/** True when nothing the process is about to lose remains queued. */
+function isFlushed(stream) {
+    return stream.destroyed || stream.writableFinished || stream.writableLength === 0;
+}
+/**
+ * Resolves once `stream` has drained its queued writes, and always within
+ * `timeoutMs`. Never rejects: `'error'` and `'close'` (an EPIPE'd pipe —
+ * `installBrokenPipeHandler` already swallows the error itself) resolve
+ * immediately, because a destroyed pipe can never drain and must not stall
+ * the exit behind it.
+ */
+function waitForStreamDrain(stream, timeoutMs) {
+    if (isFlushed(stream)) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const settle = () => {
+            clearTimeout(timer);
+            stream.off('drain', onDrain);
+            stream.off('error', settle);
+            stream.off('close', settle);
+            resolve();
+        };
+        const onDrain = () => {
+            if (isFlushed(stream)) {
+                settle();
+            }
+        };
+        const timer = setTimeout(settle, timeoutMs);
+        stream.on('drain', onDrain);
+        stream.on('error', settle);
+        stream.on('close', settle);
+    });
+}
+/**
+ * Waits (bounded by `timeoutMs`) for every given stream — stdout and stderr
+ * by default — to drain. Resolution is unconditional; the caller exits
+ * either way, the bound only decides how much queued output survives.
+ */
+export async function waitForStdioDrain(timeoutMs, streams = [process.stdout, process.stderr]) {
+    await Promise.all(streams.map((stream) => waitForStreamDrain(stream, timeoutMs)));
+}

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

@@ -1,3 +1,4 @@
+import type { FirefoxProduct } from '../types/config.js';
 /**
  * Checks whether a value is a string.
  * @param value - Value to check
@@ -62,11 +63,31 @@ export declare function isValidFirefoxVersion(version: string): boolean;
  * Accepts formats like "build1", "build2", "build12" (no leading zero).
  */
 export declare function isValidFirefoxCandidate(candidate: string): boolean;
+/**
+ * Valid Firefox product identifiers.
+ *
+ * `satisfies readonly FirefoxProduct[]` links the runtime list to the union at
+ * `types/config.ts:5` in ONE direction: it rejects an entry here that the union
+ * does not declare. It cannot see a union member missing from this list —
+ * widening a `readonly T[]` check never fails for being short. The reverse
+ * direction is covered by the exhaustive switch in
+ * `utils/__tests__/validation.test.ts`, which fails to compile when the union
+ * grows.
+ *
+ * Two further copies of this list existed before 0.41.0 — an inline literal
+ * inside the validator below and `SOURCE_PRODUCTS` in `commands/source.ts` —
+ * neither linked to the union.
+ */
+export declare const FIREFOX_PRODUCTS: readonly ["firefox", "firefox-esr", "firefox-beta", "firefox-devedition"];
 /**
  * Validates a Firefox product string.
- * Accepts: firefox, firefox-esr, firefox-beta, firefox-devedition
+ *
+ * A type predicate, matching its siblings {@link isValidPatchCategory} and
+ * {@link isValidProjectLicense}. It returned plain `boolean` until 0.41.0,
+ * which forced `as FirefoxProduct` casts at both call sites even though the
+ * `.includes` check IS the runtime proof.
  */
-export declare function isValidFirefoxProduct(product: string): boolean;
+export declare function isValidFirefoxProduct(product: string): product is FirefoxProduct;
 /**
  * Valid project license SPDX identifiers.
  */
@@ -128,6 +149,16 @@ export declare function validateTokenName(name: string): string | undefined;
  * @throws InvalidArgumentError if the resulting name is not a valid CSS custom property.
  */
 export declare function normalizeTokenName(name: string): string;
+/**
+ * Normalizes a patch display name against its category (FORGE G13):
+ * strips a trailing `.patch` and any redundant `NNN-<category>-` /
+ * `<category>-` prefixes, case-insensitively and repeatedly, mirroring
+ * the filename slug pipeline's require-the-category-token rule — a bare
+ * leading number is never stripped, so names like `2-step-verification`
+ * survive intact. Falls back to the `.patch`-stripped stem when the
+ * strip would empty the name.
+ */
+export declare function normalizePatchDisplayName(name: string, category: string): string;
 /**
  * Validates a patch name.
  * @param name - The patch name to validate

package/dist/src/utils/validation.js

@@ -4,6 +4,7 @@
  * Used to safely narrow types from unknown values.
  */
 import { InvalidArgumentError } from '../errors/base.js';
+import { escapeRegex } from './regex.js';
 /**
  * Checks whether a value is a string.
  * @param value - Value to check
@@ -94,12 +95,37 @@ export function isValidFirefoxVersion(version) {
 export function isValidFirefoxCandidate(candidate) {
     return /^build[1-9]\d{0,3}$/.test(candidate);
 }
+/**
+ * Valid Firefox product identifiers.
+ *
+ * `satisfies readonly FirefoxProduct[]` links the runtime list to the union at
+ * `types/config.ts:5` in ONE direction: it rejects an entry here that the union
+ * does not declare. It cannot see a union member missing from this list —
+ * widening a `readonly T[]` check never fails for being short. The reverse
+ * direction is covered by the exhaustive switch in
+ * `utils/__tests__/validation.test.ts`, which fails to compile when the union
+ * grows.
+ *
+ * Two further copies of this list existed before 0.41.0 — an inline literal
+ * inside the validator below and `SOURCE_PRODUCTS` in `commands/source.ts` —
+ * neither linked to the union.
+ */
+export const FIREFOX_PRODUCTS = [
+    'firefox',
+    'firefox-esr',
+    'firefox-beta',
+    'firefox-devedition',
+];
 /**
  * Validates a Firefox product string.
- * Accepts: firefox, firefox-esr, firefox-beta, firefox-devedition
+ *
+ * A type predicate, matching its siblings {@link isValidPatchCategory} and
+ * {@link isValidProjectLicense}. It returned plain `boolean` until 0.41.0,
+ * which forced `as FirefoxProduct` casts at both call sites even though the
+ * `.includes` check IS the runtime proof.
  */
 export function isValidFirefoxProduct(product) {
-    return ['firefox', 'firefox-esr', 'firefox-beta', 'firefox-devedition'].includes(product);
+    return FIREFOX_PRODUCTS.includes(product);
 }
 /**
  * Valid project license SPDX identifiers.
@@ -251,6 +277,35 @@ export function normalizeTokenName(name) {
     const stripped = name.replace(/^--/, '');
     return `--${stripped}`;
 }
+/**
+ * Normalizes a patch display name against its category (FORGE G13):
+ * strips a trailing `.patch` and any redundant `NNN-<category>-` /
+ * `<category>-` prefixes, case-insensitively and repeatedly, mirroring
+ * the filename slug pipeline's require-the-category-token rule — a bare
+ * leading number is never stripped, so names like `2-step-verification`
+ * survive intact. Falls back to the `.patch`-stripped stem when the
+ * strip would empty the name.
+ */
+export function normalizePatchDisplayName(name, category) {
+    const stem = name.trim().replace(/\.patch$/i, '');
+    const escaped = escapeRegex(category);
+    const prefixes = [
+        new RegExp(`^\\d+[-_ ]+${escaped}[-_ ]+`, 'i'),
+        new RegExp(`^${escaped}[-_ ]+`, 'i'),
+    ];
+    let stripped = stem;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const prefix of prefixes) {
+            if (prefix.test(stripped)) {
+                stripped = stripped.replace(prefix, '');
+                changed = true;
+            }
+        }
+    }
+    return stripped.length > 0 ? stripped : stem;
+}
 /**
  * Validates a patch name.
  * @param name - The patch name to validate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -18,11 +18,11 @@
   },
   "scripts": {
     "fireforge": "tsx bin/fireforge.ts",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node ./scripts/generate-build-info.mjs",
     "clean": "node ./scripts/clean.mjs",
-    "lint": "eslint src/ bin/ scripts/ eslint.config.js vitest.config.ts vitest.pack.config.ts",
-    "lint:ci": "eslint src/ bin/ scripts/ eslint.config.js vitest.config.ts vitest.pack.config.ts --max-warnings 0",
-    "lint:fix": "eslint src/ bin/ scripts/ eslint.config.js vitest.config.ts vitest.pack.config.ts --fix",
+    "lint": "eslint src/ bin/ scripts/ eslint-rules/ eslint.config.js vitest.config.ts vitest.pack.config.ts",
+    "lint:ci": "eslint src/ bin/ scripts/ eslint-rules/ eslint.config.js vitest.config.ts vitest.pack.config.ts --max-warnings 0",
+    "lint:fix": "eslint src/ bin/ scripts/ eslint-rules/ eslint.config.js vitest.config.ts vitest.pack.config.ts --fix",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "deadcode:check": "knip",
     "cycles:check": "dpdm --no-output --no-tree --no-warning --exit-code circular:1 src/index.ts bin/fireforge.ts",
@@ -34,10 +34,10 @@
     "whitespace:check": "node ./scripts/check-worktree-whitespace.mjs",
     "pack:verify": "vitest run --config vitest.pack.config.ts",
     "pack:dry-run": "npm pack --dry-run --json --silent",
-    "format": "prettier --write --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\" \"docs/**/*.md\" \"knip.json\"",
-    "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\" \"docs/**/*.md\" \"knip.json\"",
+    "format": "prettier --write --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\"",
+    "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\"",
     "prepare": "node -e \"import('./scripts/prepare.mjs').catch((error) => { if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0); throw error; })\"",
-    "prepack": "npm run build",
+    "prepack": "npm run build && node ./scripts/generate-build-info.mjs --loud",
     "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run cycles:check && npm run test:coverage && npm run pack:verify && npm run pack:dry-run",
     "prepublishOnly": "npm run release:check"
   },
@@ -58,7 +58,7 @@
     "commander": "^15.0.0",
     "estree-walker": "^3.0.3",
     "jsonc-parser": "^3.3.1",
-    "magic-string": "^0.30.17",
+    "magic-string": "^1.1.0",
     "picocolors": "^1.1.0"
   },
   "devDependencies": {
@@ -66,16 +66,16 @@
     "@types/estree": "^1.0.8",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.2",
-    "dpdm": "4.2.0",
+    "dpdm": "4.3.0",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsdoc": "^63.0.0",
-    "eslint-plugin-simple-import-sort": "^13.0.0",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.26.0",
+    "knip": "6.32.0",
     "lint-staged": "^17.0.4",
-    "prettier": "3.9.5",
+    "prettier": "3.9.6",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",