@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/commands/verify.d.ts

@@ -1,58 +0,0 @@
-/**
- * `fireforge verify`: read-only fsck for the patch queue.
- *
- * Combines the manifest consistency check (orphan files, missing entries,
- * files-affected mismatch, duplicate entries) with the cross-patch lint
- * rules (duplicate /dev/null creation, forward imports). Does not run
- * `planExport` per patch. That is out of scope because it
- * would couple verify to engine state and make the command too slow to be
- * useful as a pre-flight gate. Engine-level patch application issues are
- * still covered by the existing `fireforge doctor` and `fireforge import`
- * paths.
- *
- * Exits non-zero when any error-severity finding is reported so CI can
- * treat the output as pass/fail.
- */
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-import { type VerifyScope } from './verify-scope.js';
-interface VerifyIssueGroup {
-    title: string;
-    issues: string[];
-    errorCount: number;
-    warningCount: number;
-}
-export interface PatchQueueHealth {
-    hasPatchesDirectory: boolean;
-    groups: VerifyIssueGroup[];
-    errorCount: number;
-    warningCount: number;
-}
-/**
- * Collects the same queue-health findings reported by `fireforge verify`
- * without printing. Used by doctor recovery paths that need a read-only
- * "is this queue healthy?" decision before clearing stale state.
- *
- * @param projectRoot - Project root directory
- * @param scope - `verify --patches`: keep only the findings that name these
- *   patches (see verify-scope.ts). Omitted, every finding counts.
- */
-export declare function collectPatchQueueHealth(projectRoot: string, scope?: VerifyScope): Promise<PatchQueueHealth>;
-/**
- * Runs the `verify` command: manifest consistency + cross-patch lint.
- * Read-only. Exits non-zero on any error-severity finding.
- *
- * @param projectRoot - Project root directory
- * @param options - `patches`: the raw `--patches` values
- */
-export declare function verifyCommand(projectRoot: string, options?: {
-    patches?: string[];
-}): Promise<void>;
-/**
- * Registers the `verify` command on the CLI program.
- *
- * @param program - Commander root program
- * @param context - Shared CLI registration context
- */
-export declare function registerVerify(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;
-export {};

package/dist/src/commands/watch.d.ts

@@ -1,9 +0,0 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-/**
- * Runs the watch command for auto-rebuilding.
- * @param projectRoot - Root directory of the project
- */
-export declare function watchCommand(projectRoot: string): Promise<void>;
-/** Registers the watch command on the CLI program. */
-export declare function registerWatch(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/wire.d.ts

@@ -1,13 +0,0 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-import type { WireOptions } from '../types/commands/index.js';
-/**
- * Wires a chrome subscript into the browser.
- *
- * @param projectRoot - Root directory of the project
- * @param name - Subscript name (without .js extension)
- * @param options - Command options
- */
-export declare function wireCommand(projectRoot: string, name: string, options?: WireOptions): Promise<void>;
-/** Registers the wire command on the CLI program. */
-export declare function registerWire(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/core/ast-utils.d.ts

@@ -1,73 +0,0 @@
-import * as acorn from 'acorn';
-import type * as estree from 'estree';
-import { walk } from 'estree-walker';
-/**
- * An ESTree node augmented with acorn's character-offset positions.
- * At runtime `acorn.parse` produces objects that carry both the ESTree
- * shape and `start`/`end` indices, but the type system doesn't know that.
- * This intersection type bridges the gap so we can safely use both APIs.
- */
-export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
-    start: number;
-    end: number;
-};
-/**
- * Parse JavaScript source as a script, not an ES module.
- * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
- * `customElements.js`, etc.) are scripts that run in a privileged scope.
- *
- * @param content - Source text to parse
- * @param onComment - Optional array that acorn fills with comment nodes
- * @returns Parsed program AST with character-offset positions
- */
-export declare function parseScript(content: string, onComment?: acorn.Comment[]): AcornESTreeNode<estree.Program>;
-/**
- * Parse JavaScript source as an ES module.
- * Used for `.sys.mjs` files which use static import/export syntax.
- *
- * @param content - Source text to parse
- * @param onComment - Optional array that acorn fills with comment nodes
- * @returns Parsed program AST with character-offset positions
- */
-export declare function parseModule(content: string, onComment?: acorn.Comment[]): AcornESTreeNode<estree.Program>;
-/**
- * Convenience cast from `acorn.Node` (or the generic ESTree union returned
- * by estree-walker callbacks) to a positioned, narrowly-typed node.
- *
- * Caller obligation: you must already have discriminated on `node.type`.
- * This performs no runtime check. It exists to attach acorn's `start`/`end`
- * offsets to a node the caller has already narrowed, typically inside an
- * `if (node.type === 'CallExpression')` branch or an equivalent walker
- * guard. Calling it on an undiscriminated node produces a value whose type
- * is wrong.
- *
- * No runtime `type` assertion: every call site sits in the hot loop of a lint
- * or registration walker and is already post-narrowing, so the check would
- * cost traversal time on every node to re-prove what the enclosing branch
- * established.
- */
-export declare function asEstree<T extends estree.Node>(node: estree.Node): AcornESTreeNode<T>;
-/**
- * Type-safe wrapper around estree-walker's `walk()` that bridges the
- * acorn→estree type gap. Centralises the single `as unknown as` cast so
- * callers don't need it.
- */
-export declare function walkAST(ast: AcornESTreeNode<estree.Program>, visitors: Parameters<typeof walk>[1]): ReturnType<typeof walk>;
-/**
- * Read backward from `position` to the preceding newline (or start of
- * string) and return the leading whitespace.  This is the "visual indent"
- * of whatever token begins at `position`.
- *
- * ```
- * "  try {\n    foo();\n  }"
- *                          ^  detectIndent(…, 26) → "  "
- * ```
- */
-export declare function detectIndent(content: string, position: number): string;
-/**
- * Extract the raw source text for a node's range.
- */
-export declare function getNodeSource(content: string, node: {
-    start: number;
-    end: number;
-}): string;

package/dist/src/core/ast-utils.js

@@ -1,105 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import * as acorn from 'acorn';
-import { walk } from 'estree-walker';
-/**
- * Bridges acorn's return type to the positioned ESTree program type.
- * `acorn.parse` produces nodes that carry both the ESTree shape and
- * `start`/`end` offsets at runtime, but its static `acorn.Program` type is
- * nominally distinct from `estree.Program`, so the compiler cannot verify
- * the conversion structurally, hence the double assertion. This helper is the
- * only sanctioned crossing point between the two types.
- */
-function toPositionedProgram(program) {
-    // eslint-disable-next-line no-restricted-syntax -- the sanctioned acorn→estree bridge this rule's message points at
-    return program;
-}
-/**
- * Parse JavaScript source as a script, not an ES module.
- * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
- * `customElements.js`, etc.) are scripts that run in a privileged scope.
- *
- * @param content - Source text to parse
- * @param onComment - Optional array that acorn fills with comment nodes
- * @returns Parsed program AST with character-offset positions
- */
-export function parseScript(content, onComment) {
-    const opts = {
-        sourceType: 'script',
-        ecmaVersion: 'latest',
-    };
-    if (onComment)
-        opts.onComment = onComment;
-    return toPositionedProgram(acorn.parse(content, opts));
-}
-/**
- * Parse JavaScript source as an ES module.
- * Used for `.sys.mjs` files which use static import/export syntax.
- *
- * @param content - Source text to parse
- * @param onComment - Optional array that acorn fills with comment nodes
- * @returns Parsed program AST with character-offset positions
- */
-export function parseModule(content, onComment) {
-    const opts = {
-        sourceType: 'module',
-        ecmaVersion: 'latest',
-        locations: true,
-    };
-    if (onComment)
-        opts.onComment = onComment;
-    return toPositionedProgram(acorn.parse(content, opts));
-}
-/**
- * Convenience cast from `acorn.Node` (or the generic ESTree union returned
- * by estree-walker callbacks) to a positioned, narrowly-typed node.
- *
- * Caller obligation: you must already have discriminated on `node.type`.
- * This performs no runtime check. It exists to attach acorn's `start`/`end`
- * offsets to a node the caller has already narrowed, typically inside an
- * `if (node.type === 'CallExpression')` branch or an equivalent walker
- * guard. Calling it on an undiscriminated node produces a value whose type
- * is wrong.
- *
- * No runtime `type` assertion: every call site sits in the hot loop of a lint
- * or registration walker and is already post-narrowing, so the check would
- * cost traversal time on every node to re-prove what the enclosing branch
- * established.
- */
-export function asEstree(node) {
-    return node;
-}
-/**
- * Type-safe wrapper around estree-walker's `walk()` that bridges the
- * acorn→estree type gap. Centralises the single `as unknown as` cast so
- * callers don't need it.
- */
-export function walkAST(ast, visitors) {
-    return walk(ast, visitors);
-}
-/**
- * Read backward from `position` to the preceding newline (or start of
- * string) and return the leading whitespace.  This is the "visual indent"
- * of whatever token begins at `position`.
- *
- * ```
- * "  try {\n    foo();\n  }"
- *                          ^  detectIndent(…, 26) → "  "
- * ```
- */
-export function detectIndent(content, position) {
-    let i = position - 1;
-    while (i >= 0 && content[i] !== '\n') {
-        i--;
-    }
-    // i is now at the newline (or -1 for start-of-string)
-    const lineStart = i + 1;
-    const slice = content.slice(lineStart, position);
-    const match = /^(\s*)/.exec(slice);
-    return match?.[1] ?? '';
-}
-/**
- * Extract the raw source text for a node's range.
- */
-export function getNodeSource(content, node) {
-    return content.slice(node.start, node.end);
-}

package/dist/src/core/brand-validation.d.ts

@@ -1,7 +0,0 @@
-/**
- * Validates that a brand override matches the configured brand.
- * @param configuredBrand - The brand configured in fireforge.json
- * @param requestedBrand - The brand requested via CLI flag
- * @throws InvalidArgumentError if the brands don't match
- */
-export declare function validateBrandOverride(configuredBrand: string, requestedBrand?: string): void;

package/dist/src/core/brand-validation.js

@@ -1,14 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { InvalidArgumentError } from '../errors/base.js';
-/**
- * Validates that a brand override matches the configured brand.
- * @param configuredBrand - The brand configured in fireforge.json
- * @param requestedBrand - The brand requested via CLI flag
- * @throws InvalidArgumentError if the brands don't match
- */
-export function validateBrandOverride(configuredBrand, requestedBrand) {
-    if (!requestedBrand || requestedBrand === configuredBrand) {
-        return;
-    }
-    throw new InvalidArgumentError(`Brand override "${requestedBrand}" is not supported yet. FireForge currently operates only on the configured brand "${configuredBrand}".`, 'brand');
-}

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

@@ -1,86 +0,0 @@
-import { FireForgeError } from '../errors/base.js';
-import type { ProjectLicense } from '../types/config.js';
-/**
- * Error thrown when the generated `mozconfig` references a `--with-branding`
- * directory that does not match the branding tree FireForge set up. The
- * mismatch is a silent-corruption hazard: `mach configure` picks the value
- * from mozconfig but the scaffolded branding lives elsewhere, so the build
- * fails deep inside moz.build resolution with a confusing "path does not
- * exist" message. Surface it as an actionable preflight instead.
- *
- * Setup renders templates under `configs/` with `${binaryName}` baked in. A
- * later edit to `fireforge.json`'s `binaryName` (or a re-setup without
- * re-templating) leaves those names stale while `setupBranding` keeps using
- * the current value. Both directions produce the same class of build break.
- */
-export declare class BrandingMozconfigMismatchError extends FireForgeError {
-    readonly expectedBrandingDir: string;
-    readonly mozconfigBrandingDir: string;
-    readonly reason: 'mozconfig-missing-branding' | 'name-mismatch' | 'branding-dir-missing';
-    readonly code: 6;
-    constructor(expectedBrandingDir: string, mozconfigBrandingDir: string, reason: 'mozconfig-missing-branding' | 'name-mismatch' | 'branding-dir-missing');
-    get userMessage(): string;
-}
-/**
- * Full branding configuration.
- */
-export interface BrandingConfig {
-    /** Display name (e.g., "MyBrowser") */
-    name: string;
-    /** Vendor name (e.g., "My Company") */
-    vendor: string;
-    /** Application ID in reverse-domain format (e.g., "org.mybrowser.browser") */
-    appId: string;
-    /** Binary/branding directory name (e.g., "mybrowser") */
-    binaryName: string;
-    /**
-     * Project license (from fireforge.json). Used to stamp the generated
-     * `configure.sh`, `brand.properties`, and `brand.ftl` files with the
-     * matching header so `patch-lint` does not flag them for
-     * `missing-license-header` when the project is not MPL-2.0. Optional.
-     * Falls back to {@link DEFAULT_LICENSE}.
-     */
-    license?: ProjectLicense;
-}
-/**
- * Splits the reverse-domain `appId` for macOS bundle identity. Upstream
- * `toolkit/moz.configure` composes `CFBundleIdentifier` as
- * `<--with-distribution-id>.<MOZ_MACBUNDLE_ID>` (the distribution id
- * defaults to `org.mozilla`), so branding `configure.sh` must carry only the
- * leaf segment while the generated mozconfig carries the remainder as
- * `--with-distribution-id`. Writing the full appId into `MOZ_MACBUNDLE_ID`
- * double-prefixes the shipped bundle id. Config validation guarantees a
- * reverse-domain id, so the split always has both halves.
- */
-export declare function splitAppId(appId: string): {
-    distributionId: string;
-    leaf: string;
-};
-/**
- * Sets up the custom branding directory for the browser.
- *
- * This creates a branding directory based on Firefox's unofficial branding,
- * with customized values for:
- * - configure.sh: MOZ_APP_DISPLAYNAME, MOZ_MACBUNDLE_ID
- * - brand.properties: brandShorterName, brandShortName, brandFullName
- * - brand.ftl: -brand-shorter-name, -brand-short-name, etc.
- *
- * @param engineDir - Path to the engine directory
- * @param config - Branding configuration
- */
-export declare function setupBranding(engineDir: string, config: BrandingConfig): Promise<void>;
-/**
- * Checks if branding has been set up for the given configuration.
- *
- * @param engineDir - Path to the engine directory
- * @param config - Branding configuration to check for
- * @returns true if branding is already set up
- */
-export declare function isBrandingSetup(engineDir: string, config: BrandingConfig): Promise<boolean>;
-/**
- * Checks whether a file path belongs to the tool-managed branding directory.
- * @param file - File path (relative to engine root)
- * @param binaryName - The configured binary name (used as branding directory name)
- * @returns true if the path is managed by branding tooling
- */
-export declare function isBrandingManagedPath(file: string, binaryName: string): boolean;