@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -1,16 +1,16 @@
 /**
  * Bounded stdio drain for delayed process exits.
  *
- * `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
+ * `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
+ * 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
+ * The structural slice of `Writable` the drain wait needs. Accepted instead
  * of `NodeJS.WriteStream` so unit tests can drive synthetic streams.
  */
 export interface DrainableStream {
@@ -21,8 +21,8 @@ export interface DrainableStream {
     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.
+ * Waits (bounded by `timeoutMs`) for every given stream (stdout and stderr
+ * by default) to drain. Resolution is unconditional. The caller exits
+ * either way, and 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

@@ -2,12 +2,12 @@
 /**
  * Bounded stdio drain for delayed process exits.
  *
- * `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
+ * `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
+ * 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. */
@@ -16,8 +16,8 @@ function isFlushed(stream) {
 }
 /**
  * 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
+ * `timeoutMs`. Never rejects: `'error'` and `'close'` (an EPIPE'd pipe,
+ * whose error `installBrokenPipeHandler` already swallows) resolve
  * immediately, because a destroyed pipe can never drain and must not stall
  * the exit behind it.
  */
@@ -45,9 +45,9 @@ function waitForStreamDrain(stream, timeoutMs) {
     });
 }
 /**
- * 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.
+ * Waits (bounded by `timeoutMs`) for every given stream (stdout and stderr
+ * by default) to drain. Resolution is unconditional. The caller exits
+ * either way, and 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

@@ -27,9 +27,9 @@ export declare function isPositiveInteger(value: unknown): value is number;
  * orders instead of failing fast.
  *
  * Rejects leading-zero forms ("01"), decimals ("1.5"), whitespace, and
- * non-numeric garbage via a strict regex — only the canonical
- * representation is accepted, so there is no ambiguity between what the user
- * typed and what the value becomes on disk.
+ * non-numeric garbage via a strict regex. Only the canonical representation
+ * is accepted, so there is no ambiguity between what the user typed and what
+ * the value becomes on disk.
  *
  * @param flagName - Flag name to include in the error (e.g. `--order`)
  * @param rawValue - Raw string value from Commander
@@ -57,8 +57,8 @@ export declare function isArray(value: unknown): value is unknown[];
  * Narrows a JSON value to a JSON object node (excludes arrays and `null`).
  *
  * Unlike {@link isObject} this accepts only values already known to be JSON
- * data, so the narrowed `JsonObject` keeps its concrete value contract —
- * use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
+ * data, so the narrowed `JsonObject` keeps its concrete value contract.
+ * Use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
  * @param value - JSON value to check
  * @returns True if value is a JSON object node
  */
@@ -73,55 +73,26 @@ export declare function isValidFirefoxVersion(version: string): boolean;
  * Accepts formats like "build1", "build2", "build12" (no leading zero).
  */
 export declare function isValidFirefoxCandidate(candidate: string): boolean;
-/**
- * Naming contract for this module's checks.
- *
- * `validate*` is easy to spread across incompatible return contracts — some
- * throwing and returning void, some returning an issue list, some a parsed
- * value, some a boolean, some an error MESSAGE — and a caller cannot tell
- * which from the name. Passing a THROWING `validate*` to a clack `validate`
- * callback, which expects a returned message, kills the prompt instead of
- * re-prompting.
- *
- * The two dominant contracts keep the prefix:
- *   - `validate*` — throws on failure, or returns an issue list.
- *   - `is*` / `has*` — a type predicate or boolean.
- * The message-returning minority is `describe*Problem`, which reads as what
- * it is: a description of what is wrong, or `undefined`.
- *
- * `assert*` is uniform throughout: throw-or-continue.
- */
-/**
- * Valid Firefox product identifiers.
- *
- * `satisfies readonly FirefoxProduct[]` links the runtime list to the union
- * 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.
- */
 export declare const FIREFOX_PRODUCTS: readonly ["firefox", "firefox-esr", "firefox-beta", "firefox-devedition"];
 /**
  * Validates a Firefox product string.
  *
- * A type predicate, matching its siblings {@link isValidPatchCategory} and
- * {@link isValidProjectLicense}. Returning plain `boolean` would force
- * `as FirefoxProduct` casts at the call sites even though the `.includes`
- * check IS the runtime proof.
+ * A type predicate, matching its sibling {@link isValidProjectLicense}.
+ * Returning plain `boolean` would force `as FirefoxProduct` casts at the
+ * call sites even though the `.includes` check is the runtime proof.
  */
 export declare const isValidFirefoxProduct: (value: string) => value is "firefox" | "firefox-esr" | "firefox-beta" | "firefox-devedition";
 /**
  * Builds a type predicate from a `readonly` tuple of allowed values.
  *
- * Deriving the type from the list — rather than declaring a union and
- * hand-maintaining a matching array — removes a whole class of drift: a
+ * Deriving the type from the list, rather than declaring a union and
+ * hand-maintaining a matching array, removes a whole class of drift: a
  * union can otherwise accept a stale allowlist with no compile error, and a
  * copy of the member list on the `fireforge.json` read path can silently
  * reject a newly added value.
  *
  * Returning a predicate rather than a boolean is what removes the `as`
- * casts: `.includes` IS the runtime proof, so the caller should not have to
+ * casts: `.includes` is the runtime proof, so the caller should not have to
  * re-assert it. `ParsedRecord.stringEnum` (src/utils/parse.ts) consumes
  * exactly this shape.
  *
@@ -141,10 +112,6 @@ export declare const isValidProjectLicense: (value: string) => value is "EUPL-1.
  * Valid patch categories.
  */
 export declare const PATCH_CATEGORIES: readonly ["branding", "ui", "privacy", "security", "infra"];
-/**
- * Validates a patch category string.
- */
-export declare const isValidPatchCategory: (value: string) => value is "branding" | "ui" | "privacy" | "security" | "infra";
 /**
  * Infers the Firefox product type from a version string.
  * Returns undefined if no clear inference can be made.
@@ -166,10 +133,6 @@ export declare function describeProductVersionIncompatibility(version: string, p
  * Accepts reverse-domain format like "org.example.browser"
  */
 export declare function isValidAppId(appId: string): boolean;
-/**
- * Checks if a value is defined (not undefined or null).
- */
-export declare function isDefined<T>(value: T | undefined | null): value is T;
 /**
  * Validates that a string is a legal CSS custom property identifier (the part after `--`).
  *
@@ -194,7 +157,7 @@ export declare function normalizeTokenName(name: string): string;
  * Normalizes a patch display name against its category:
  * 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
+ * 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.

package/dist/src/utils/validation.js

@@ -19,7 +19,7 @@ export function isString(value) {
  * @returns True if value is a finite number
  */
 export function isNumber(value) {
-    // Number.isFinite matches the documented contract: NaN AND ±Infinity are
+    // Number.isFinite matches the documented contract: NaN and ±Infinity are
     // excluded (a JSON config field of 1e999 parses to Infinity and used to
     // validate as a legal number).
     return typeof value === 'number' && Number.isFinite(value);
@@ -42,9 +42,9 @@ export function isPositiveInteger(value) {
  * orders instead of failing fast.
  *
  * Rejects leading-zero forms ("01"), decimals ("1.5"), whitespace, and
- * non-numeric garbage via a strict regex — only the canonical
- * representation is accepted, so there is no ambiguity between what the user
- * typed and what the value becomes on disk.
+ * non-numeric garbage via a strict regex. Only the canonical representation
+ * is accepted, so there is no ambiguity between what the user typed and what
+ * the value becomes on disk.
  *
  * @param flagName - Flag name to include in the error (e.g. `--order`)
  * @param rawValue - Raw string value from Commander
@@ -83,13 +83,13 @@ export function isArray(value) {
  * Narrows a JSON value to a JSON object node (excludes arrays and `null`).
  *
  * Unlike {@link isObject} this accepts only values already known to be JSON
- * data, so the narrowed `JsonObject` keeps its concrete value contract —
- * use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
+ * data, so the narrowed `JsonObject` keeps its concrete value contract.
+ * Use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
  * @param value - JSON value to check
  * @returns True if value is a JSON object node
  */
 export function isJsonObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return isObject(value);
 }
 /**
  * Validates a Firefox version string.
@@ -110,16 +110,16 @@ export function isValidFirefoxCandidate(candidate) {
 /**
  * Naming contract for this module's checks.
  *
- * `validate*` is easy to spread across incompatible return contracts — some
+ * `validate*` is easy to spread across incompatible return contracts: some
  * throwing and returning void, some returning an issue list, some a parsed
- * value, some a boolean, some an error MESSAGE — and a caller cannot tell
- * which from the name. Passing a THROWING `validate*` to a clack `validate`
+ * value, some a boolean, some an error message. A caller cannot tell which
+ * from the name. Passing a throwing `validate*` to a clack `validate`
  * callback, which expects a returned message, kills the prompt instead of
  * re-prompting.
  *
  * The two dominant contracts keep the prefix:
- *   - `validate*` — throws on failure, or returns an issue list.
- *   - `is*` / `has*` — a type predicate or boolean.
+ *   - `validate*`: throws on failure, or returns an issue list.
+ *   - `is*` / `has*`: a type predicate or boolean.
  * The message-returning minority is `describe*Problem`, which reads as what
  * it is: a description of what is wrong, or `undefined`.
  *
@@ -129,38 +129,38 @@ export function isValidFirefoxCandidate(candidate) {
  * Valid Firefox product identifiers.
  *
  * `satisfies readonly FirefoxProduct[]` links the runtime list to the union
- * 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.
+ * in one direction: it rejects an entry here that the union does not
+ * declare. It cannot see a union member missing from this list, because
+ * widening a `readonly T[]` check never fails for being short. The reverse direction is
+ * covered by the `ExhaustiveFirefoxProductList` operand below, which stops
+ * compiling when the union grows past this list.
  */
-export const FIREFOX_PRODUCTS = [
+const FIREFOX_PRODUCT_VALUES = [
     'firefox',
     'firefox-esr',
     'firefox-beta',
     'firefox-devedition',
 ];
+export const FIREFOX_PRODUCTS = FIREFOX_PRODUCT_VALUES;
 /**
  * Validates a Firefox product string.
  *
- * A type predicate, matching its siblings {@link isValidPatchCategory} and
- * {@link isValidProjectLicense}. Returning plain `boolean` would force
- * `as FirefoxProduct` casts at the call sites even though the `.includes`
- * check IS the runtime proof.
+ * A type predicate, matching its sibling {@link isValidProjectLicense}.
+ * Returning plain `boolean` would force `as FirefoxProduct` casts at the
+ * call sites even though the `.includes` check is the runtime proof.
  */
 export const isValidFirefoxProduct = makeEnumGuard(FIREFOX_PRODUCTS);
 /**
  * Builds a type predicate from a `readonly` tuple of allowed values.
  *
- * Deriving the type from the list — rather than declaring a union and
- * hand-maintaining a matching array — removes a whole class of drift: a
+ * Deriving the type from the list, rather than declaring a union and
+ * hand-maintaining a matching array, removes a whole class of drift: a
  * union can otherwise accept a stale allowlist with no compile error, and a
  * copy of the member list on the `fireforge.json` read path can silently
  * reject a newly added value.
  *
  * Returning a predicate rather than a boolean is what removes the `as`
- * casts: `.includes` IS the runtime proof, so the caller should not have to
+ * casts: `.includes` is the runtime proof, so the caller should not have to
  * re-assert it. `ParsedRecord.stringEnum` (src/utils/parse.ts) consumes
  * exactly this shape.
  *
@@ -182,10 +182,6 @@ export const isValidProjectLicense = makeEnumGuard(PROJECT_LICENSES);
  * Valid patch categories.
  */
 export const PATCH_CATEGORIES = ['branding', 'ui', 'privacy', 'security', 'infra'];
-/**
- * Validates a patch category string.
- */
-export const isValidPatchCategory = makeEnumGuard(PATCH_CATEGORIES);
 /**
  * Checks whether a Firefox version string has an ESR suffix.
  */
@@ -257,12 +253,6 @@ export function describeProductVersionIncompatibility(version, product) {
 export function isValidAppId(appId) {
     return /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/.test(appId);
 }
-/**
- * Checks if a value is defined (not undefined or null).
- */
-export function isDefined(value) {
-    return value !== undefined && value !== null;
-}
 /**
  * Validates that a string is a legal CSS custom property identifier (the part after `--`).
  *
@@ -320,7 +310,7 @@ export function normalizeTokenName(name) {
  * Normalizes a patch display name against its category:
  * 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
+ * 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.

package/docs/README.md

@@ -4,8 +4,8 @@
 
 [`../README.md`](../README.md) is the getting-started page. These files are
 the reference material behind it. `fireforge --help` (and
-`fireforge <command> --help`) stays the authority on flags; the docs cover
-what a flag list cannot state.
+`fireforge <command> --help`) is always the authority on flags. These docs
+cover the things a flag list cannot say.
 
 ## Using FireForge