@hominis/fireforge 0.9.0

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

@@ -0,0 +1,239 @@
+/**
+ * Command option types for CLI commands.
+ */
+import type { FirefoxProduct, ProjectLicense } from '../config.js';
+import type { PatchCategory } from './patches.js';
+/**
+ * Options for the setup command.
+ */
+export interface SetupOptions {
+    /** Browser name */
+    name?: string;
+    /** Vendor/company name */
+    vendor?: string;
+    /** Application ID (reverse-domain format) */
+    appId?: string;
+    /** Binary name (executable name) */
+    binaryName?: string;
+    /** Firefox version to base on */
+    firefoxVersion?: string;
+    /** Firefox product type (firefox, firefox-esr, firefox-beta) */
+    product?: FirefoxProduct;
+    /** Overwrite existing configuration without prompting */
+    force?: boolean;
+    /** Project license SPDX identifier */
+    license?: ProjectLicense;
+}
+/**
+ * Options for the download command.
+ */
+export interface DownloadOptions {
+    /** Force re-download, deleting existing engine/ */
+    force?: boolean;
+}
+/**
+ * Options for the build command.
+ */
+export interface BuildOptions {
+    /** Fast UI-only rebuild */
+    ui?: boolean;
+    /** Number of parallel jobs */
+    jobs?: number;
+    /** Brand to build (stable, esr, etc.) */
+    brand?: string;
+}
+/**
+ * Options for the export command.
+ */
+export interface ExportOptions {
+    /** Name/description for the patch */
+    name?: string;
+    /** Category classification */
+    category?: PatchCategory;
+    /** Detailed description of what the patch does */
+    description?: string;
+    /** Allow superseding multiple existing patches without confirmation */
+    supersede?: boolean;
+    /** Skip patch lint checks (downgrade errors to warnings) */
+    skipLint?: boolean;
+}
+/**
+ * Options for the reset command.
+ */
+export interface ResetOptions {
+    /** Skip confirmation prompt */
+    force?: boolean;
+    /** Show what would be reset without doing it */
+    dryRun?: boolean;
+}
+/**
+ * Options for the discard command.
+ */
+export interface DiscardOptions {
+    /** Show what would be discarded without doing it */
+    dryRun?: boolean;
+    /** Skip confirmation prompt */
+    force?: boolean;
+}
+/**
+ * Options for the package command.
+ */
+export interface PackageOptions {
+    /** Brand to package */
+    brand?: string;
+}
+/**
+ * Options for the import command.
+ */
+export interface ImportOptions {
+    /** Specific patches to apply (by name) */
+    patches?: string[];
+    /** Continue applying patches even if one fails */
+    continue?: boolean;
+    /** Force import even when engine HEAD has drifted from base commit */
+    force?: boolean;
+}
+/**
+ * Options for the re-export command.
+ */
+export interface ReExportOptions {
+    /** Re-export all patches */
+    all?: boolean;
+    /** Scan directories for new/removed files and update filesAffected */
+    scan?: boolean;
+    /** Show what would change without writing */
+    dryRun?: boolean;
+    /** Skip patch lint checks (downgrade errors to warnings) */
+    skipLint?: boolean;
+}
+/**
+ * Options for the rebase command.
+ */
+export interface RebaseOptions {
+    /** Resume a previously interrupted rebase session */
+    continue?: boolean;
+    /** Cancel the current rebase session and restore engine */
+    abort?: boolean;
+    /** Show what would happen without modifying anything */
+    dryRun?: boolean;
+    /** Maximum fuzz factor for git apply (default 3) */
+    maxFuzz?: number;
+    /** Skip dirty-tree confirmation prompt */
+    force?: boolean;
+}
+/**
+ * Options for the run command.
+ */
+export interface RunOptions {
+    /** Additional arguments to pass to the browser */
+    args?: string[];
+}
+/**
+ * Options for the test command.
+ */
+export interface TestOptions {
+    /** Run tests in headless mode */
+    headless?: boolean;
+    /** Run incremental UI build before testing */
+    build?: boolean;
+}
+/**
+ * Options for the furnace apply command.
+ */
+export interface FurnaceApplyOptions {
+    /** Show what would be changed without writing */
+    dryRun?: boolean;
+}
+/**
+ * Options for the furnace preview command.
+ */
+export interface FurnacePreviewOptions {
+    /** Force reinstall Storybook dependencies */
+    install?: boolean;
+}
+/**
+ * Options for the furnace deploy command.
+ */
+export interface FurnaceDeployOptions {
+    /** Show what would be changed without writing */
+    dryRun?: boolean;
+}
+/**
+ * Options for the furnace override command.
+ */
+export interface FurnaceOverrideOptions {
+    /** Override type: css-only or full */
+    type?: 'css-only' | 'full';
+    /** Description of the override */
+    description?: string;
+}
+/**
+ * Options for the furnace remove command.
+ */
+export interface FurnaceRemoveOptions {
+    /** Skip confirmation prompt */
+    force?: boolean;
+}
+/**
+ * Options for the furnace create command.
+ */
+export interface FurnaceCreateOptions {
+    /** Component description */
+    description?: string;
+    /** Include Fluent l10n support */
+    localized?: boolean;
+    /** Register in customElements.js (default: true) */
+    register?: boolean;
+    /** Scaffold Mochitest directory and register in moz.build */
+    withTests?: boolean;
+    /** Stock component tag names composed internally by this component */
+    compose?: string[];
+}
+/**
+ * Options for the wire command.
+ */
+export interface WireOptions {
+    init?: string;
+    destroy?: string;
+    dom?: string;
+    dryRun?: boolean;
+    after?: string;
+    subscriptDir?: string;
+}
+/**
+ * Options for the register command.
+ */
+export interface RegisterOptions {
+    dryRun?: boolean;
+    after?: string;
+}
+/**
+ * Options for the status command.
+ */
+export interface StatusOptions {
+    raw?: boolean;
+    unmanaged?: boolean;
+}
+/**
+ * Options for the token add command.
+ */
+export interface TokenAddOptions {
+    category: string;
+    mode: string;
+    description?: string;
+    darkValue?: string;
+    dryRun?: boolean;
+}
+/**
+ * Options for the doctor command.
+ */
+export interface DoctorOptions {
+    repairPatchesManifest?: boolean;
+}
+/**
+ * Global CLI options available to all commands.
+ */
+export interface GlobalOptions {
+    /** Enable verbose/debug output */
+    verbose?: boolean;
+}

package/dist/src/types/commands/options.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Command option types for CLI commands.
+ */
+export {};
+//# sourceMappingURL=options.js.map

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

@@ -0,0 +1,89 @@
+/**
+ * Types for the patch system: patch metadata, manifests, lint, and import results.
+ */
+/**
+ * Patch categories for organizational classification.
+ */
+export type PatchCategory = 'branding' | 'ui' | 'privacy' | 'security' | 'infra';
+/**
+ * Information about a patch file.
+ */
+export interface PatchInfo {
+    /** Full path to patch file */
+    path: string;
+    /** Filename without directory */
+    filename: string;
+    /** Order index (extracted from filename prefix like "001-") */
+    order: number;
+}
+/**
+ * Result of patch application.
+ */
+export interface PatchResult {
+    /** Patch that was applied */
+    patch: PatchInfo;
+    /** Whether application succeeded */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Files that caused conflicts (if failed) */
+    conflictingFiles?: string[];
+    /** Whether the patch was auto-resolved (new file vs existing file conflict) */
+    autoResolved?: boolean;
+}
+/**
+ * Extended patch information with metadata.
+ */
+export interface PatchMetadata {
+    /** Patch filename (e.g., "011-ui-sidebar.patch") */
+    filename: string;
+    /** Numeric order for application sequence */
+    order: number;
+    /** Category classification */
+    category: PatchCategory;
+    /** Human-readable name */
+    name: string;
+    /** Detailed description of what the patch does */
+    description: string;
+    /** ISO timestamp of when the patch was created */
+    createdAt: string;
+    /** ESR version the patch was created against (e.g., "140.0esr") */
+    sourceEsrVersion: string;
+    /** Array of file paths affected by this patch */
+    filesAffected: string[];
+}
+/**
+ * Schema for patches/patches.json file.
+ */
+export interface PatchesManifest {
+    /** Schema version for future compatibility */
+    version: 1;
+    /** Array of patch metadata entries */
+    patches: PatchMetadata[];
+}
+/**
+ * Summary of import operation with continue mode.
+ */
+export interface ImportSummary {
+    /** Total patches processed */
+    total: number;
+    /** Successfully applied patches */
+    succeeded: PatchResult[];
+    /** Failed patches */
+    failed: PatchResult[];
+    /** Skipped patches (not attempted after failure in default mode) */
+    skipped: PatchInfo[];
+}
+/**
+ * A single lint issue found in a patched CSS file.
+ */
+export interface PatchLintIssue {
+    /** File path (relative to engine root) */
+    file: string;
+    /** Check identifier (e.g. "raw-color-value", "token-prefix-violation") */
+    check: string;
+    /** Human-readable description of the issue */
+    message: string;
+    /** Severity: errors block export, warnings are advisory */
+    severity: 'error' | 'warning';
+}

package/dist/src/types/commands/patches.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Types for the patch system: patch metadata, manifests, lint, and import results.
+ */
+export {};
+//# sourceMappingURL=patches.js.map

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

@@ -0,0 +1,71 @@
+/**
+ * Project diagnostics, status, and token coverage types.
+ */
+/**
+ * Result of a doctor check.
+ */
+export interface DoctorCheck {
+    /** Name of the check */
+    name: string;
+    /** Whether the check passed */
+    passed: boolean;
+    /** Severity of the result */
+    severity?: 'ok' | 'warning' | 'error';
+    /** Description of the result */
+    message: string;
+    /** Suggested fix if check failed */
+    fix?: string;
+    /** Whether this check passed with a warning */
+    warning?: boolean;
+}
+/**
+ * Status of the project.
+ */
+export interface ProjectStatus {
+    /** Whether fireforge.json exists */
+    hasConfig: boolean;
+    /** Whether engine/ exists */
+    hasEngine: boolean;
+    /** Whether patches/ exists */
+    hasPatches: boolean;
+    /** Number of patch files */
+    patchCount: number;
+    /** Whether build output exists */
+    hasBuild: boolean;
+    /** Firefox version from config */
+    firefoxVersion?: string;
+    /** Downloaded Firefox version */
+    downloadedVersion?: string;
+}
+/**
+ * Per-file token coverage breakdown.
+ */
+export interface TokenCoverageFileEntry {
+    /** File path (relative to engine root) */
+    file: string;
+    /** var(--{prefix}*) usages — fully tokenized */
+    tokenUsages: number;
+    /** var(--*) usages referencing allowlisted tokens */
+    allowlisted: number;
+    /** var(--*) usages not in token namespace and not allowlisted */
+    unknownVars: number;
+    /** Raw color values (hex, rgb, hsl) found outside comments */
+    rawColors: number;
+}
+/**
+ * Aggregate token coverage report.
+ */
+export interface TokenCoverageReport {
+    /** Total CSS files scanned */
+    filesScanned: number;
+    /** var(--{prefix}*) usages — fully tokenized */
+    tokenUsages: number;
+    /** var(--*) usages referencing allowlisted tokens */
+    allowlistedUsages: number;
+    /** var(--*) usages not in token namespace and not allowlisted */
+    unknownVarUsages: number;
+    /** Raw color values (hex, rgb, hsl) found outside comments */
+    rawColorCount: number;
+    /** Per-file breakdown */
+    files: TokenCoverageFileEntry[];
+}

package/dist/src/types/commands/project.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Project diagnostics, status, and token coverage types.
+ */
+export {};
+//# sourceMappingURL=project.js.map

package/dist/src/types/config.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Firefox product type for downloads.
+ */
+export type FirefoxProduct = 'firefox' | 'firefox-esr' | 'firefox-beta';
+/**
+ * Firefox version configuration.
+ */
+export interface FirefoxConfig {
+    /** Firefox release version (e.g., "140.0esr") */
+    version: string;
+    /** Firefox product type */
+    product: FirefoxProduct;
+}
+/**
+ * Supported project license SPDX identifiers.
+ */
+export type ProjectLicense = 'EUPL-1.2' | 'MPL-2.0' | '0BSD' | 'GPL-2.0-or-later';
+/**
+ * Build configuration options.
+ */
+export interface BuildConfig {
+    /** Number of parallel jobs for mach build */
+    jobs?: number;
+}
+/**
+ * Main fireforge.json configuration schema.
+ */
+export interface FireForgeConfig {
+    /** Display name of the browser */
+    name: string;
+    /** Vendor/company name */
+    vendor: string;
+    /** Application ID (e.g., "org.example.browser") */
+    appId: string;
+    /** Binary name for the executable */
+    binaryName: string;
+    /** Firefox version settings */
+    firefox: FirefoxConfig;
+    /** Build settings */
+    build?: BuildConfig;
+    /** Project license SPDX identifier */
+    license?: ProjectLicense;
+    /** Wire command configuration */
+    wire?: WireConfig;
+}
+/**
+ * Wire command configuration.
+ */
+export interface WireConfig {
+    /** Subscript directory relative to engine/. Default: "browser/base/content" */
+    subscriptDir?: string;
+}
+/**
+ * Build mode for mach.
+ */
+export type BuildMode = 'dev' | 'debug' | 'release';
+/**
+ * Runtime state stored in .fireforge/state.json.
+ */
+export interface FireForgeState {
+    /** Currently active brand */
+    brand?: string;
+    /** Build mode: dev, debug, release */
+    buildMode?: BuildMode;
+    /** Last successful build timestamp (ISO string) */
+    lastBuild?: string;
+    /** Firefox version that was downloaded */
+    downloadedVersion?: string;
+    /** Initial commit hash of the engine (baseline) */
+    baseCommit?: string;
+    /** State for a patch application that needs manual resolution */
+    pendingResolution?: {
+        /** Filename of the patch that failed to apply */
+        patchFilename: string;
+        /** The original error message from the failed apply */
+        originalError: string;
+    };
+}
+/**
+ * Project directory structure.
+ */
+export interface ProjectPaths {
+    /** Root directory of the project */
+    root: string;
+    /** Path to fireforge.json */
+    config: string;
+    /** Path to .fireforge directory */
+    fireforgeDir: string;
+    /** Path to .fireforge/state.json */
+    state: string;
+    /** Path to engine directory (Firefox source) */
+    engine: string;
+    /** Path to patches directory */
+    patches: string;
+    /** Path to configs directory */
+    configs: string;
+    /** Path to src directory */
+    src: string;
+    /** Path to components directory */
+    componentsDir: string;
+}

package/dist/src/types/config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.js.map

package/dist/src/types/furnace.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Component type classification.
+ */
+export type ComponentType = 'stock' | 'override' | 'custom';
+/**
+ * Override scope.
+ */
+export type OverrideType = 'css-only' | 'full';
+/**
+ * Info about a component discovered by scanning engine/.
+ */
+export interface ScannedComponent {
+    /** Tag name (e.g., "moz-button") */
+    tagName: string;
+    /** Path relative to engine/ (e.g., "toolkit/content/widgets/moz-button") */
+    sourcePath: string;
+    /** Whether it has a .css file */
+    hasCSS: boolean;
+    /** Whether it has a .ftl localization file */
+    hasFTL: boolean;
+    /** Whether it's registered in customElements.js */
+    isRegistered: boolean;
+}
+/**
+ * Metadata for an override component in the workspace.
+ */
+export interface OverrideComponentConfig {
+    /** Override scope */
+    type: OverrideType;
+    /** Description of the override */
+    description: string;
+    /** Path in engine/ where the original lives */
+    basePath: string;
+    /** Firefox version this override was based on */
+    baseVersion: string;
+}
+/**
+ * Metadata for a custom component in the workspace.
+ */
+export interface CustomComponentConfig {
+    /** Description of the custom component */
+    description: string;
+    /** Target path in engine/ where this will be placed */
+    targetPath: string;
+    /** Whether to register in customElements.js */
+    register: boolean;
+    /** Whether this component uses Fluent l10n */
+    localized: boolean;
+    /** Stock component tag names composed internally by this component */
+    composes?: string[];
+}
+/**
+ * The furnace.json schema.
+ */
+export interface FurnaceConfig {
+    /** Schema version */
+    version: 1;
+    /** Prefix for custom component tag names (default: "moz-") */
+    componentPrefix: string;
+    /** Optional CSS custom property prefix for design tokens (e.g. "--mybrowser-") */
+    tokenPrefix?: string;
+    /** Custom properties allowed even though they don't match tokenPrefix (e.g. ["--background-color-box"]) */
+    tokenAllowlist?: string[];
+    /** Stock components tracked for preview */
+    stock: string[];
+    /** Override components */
+    overrides: Record<string, OverrideComponentConfig>;
+    /** Custom components */
+    custom: Record<string, CustomComponentConfig>;
+}
+/**
+ * State tracking for apply operations (stored in .fireforge/furnace-state.json).
+ */
+export interface FurnaceState {
+    /** ISO timestamp of last successful apply */
+    lastApply?: string;
+    /** Checksums of component files at last apply, keyed by relative path */
+    appliedChecksums?: Record<string, string>;
+}
+/**
+ * A registration-step error captured while applying a component.
+ * In non-dry-run apply/deploy workflows, these trigger rollback of touched files.
+ */
+export interface StepError {
+    step: string;
+    error: string;
+}
+/**
+ * Result of applying all components to the engine source tree.
+ */
+export interface ApplyResult {
+    /** Components that were successfully applied */
+    applied: Array<{
+        name: string;
+        type: ComponentType;
+        filesAffected: string[];
+        /** Non-fatal registration step errors */
+        stepErrors?: StepError[];
+    }>;
+    /** Components that were skipped (e.g., no changes) */
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    /** Components that failed to apply */
+    errors: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/**
+ * An action that would be performed during a dry-run deploy.
+ */
+export interface DryRunAction {
+    component: string;
+    action: 'copy' | 'register-ce' | 'register-jar' | 'copy-ftl';
+    source?: string;
+    target?: string;
+    description: string;
+}
+/**
+ * Registration consistency status for a single component.
+ */
+export interface RegistrationStatus {
+    sourceExists: boolean;
+    targetExists: boolean;
+    filesInSync: boolean;
+    jarMnCss: boolean;
+    jarMnMjs: boolean;
+    customElementsPresent: boolean;
+    customElementsCorrectBlock: boolean;
+    driftedFiles: string[];
+    missingTargetFiles: string[];
+}
+/**
+ * Result of syncing Storybook story files.
+ */
+export interface SyncResult {
+    /** Story files that were created */
+    created: string[];
+    /** Story files that were updated (regenerated) */
+    updated: string[];
+    /** Story files that were removed */
+    removed: string[];
+}
+/**
+ * A single validation finding for a furnace component.
+ */
+export interface ValidationIssue {
+    /** Component tag name */
+    component: string;
+    /** Severity: 'error' blocks apply, 'warning' is advisory */
+    severity: 'error' | 'warning';
+    /** Short machine-readable check name (e.g., "missing-mjs", "no-aria-role") */
+    check: string;
+    /** Human-readable description of the issue */
+    message: string;
+}

package/dist/src/types/furnace.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=furnace.js.map

package/dist/src/types/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-exports all type definitions.
+ */
+export type { BuildOptions, DiscardOptions, DoctorCheck, DownloadOptions, ExportOptions, FurnaceCreateOptions, FurnaceOverrideOptions, FurnaceRemoveOptions, GlobalOptions, ImportOptions, ImportSummary, PackageOptions, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, ProjectStatus, ReExportOptions, ResetOptions, RunOptions, SetupOptions, TestOptions, TokenCoverageFileEntry, TokenCoverageReport, } from './commands/index.js';
+export type { BuildConfig, BuildMode, FireForgeConfig, FireForgeState, FirefoxConfig, FirefoxProduct, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
+export type { ApplyResult, ComponentType, CustomComponentConfig, DryRunAction, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, RegistrationStatus, ScannedComponent, StepError, SyncResult, ValidationIssue, } from './furnace.js';