@hominis/fireforge 0.9.0

package/dist/src/core/furnace-validate-registration.js

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { createHash } from 'node:crypto';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { warn } from '../utils/logger.js';
+import { stripJsComments } from '../utils/regex.js';
+import { getProjectPaths, loadConfig } from './config.js';
+import { getFurnacePaths } from './furnace-config.js';
+import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
+import { getTokensCssPath } from './token-manager.js';
+/**
+ * Validates that all Furnace-managed .mjs components are registered in the
+ * DOMContentLoaded/importESModule block (Pattern B), not the loadSubScript
+ * block (Pattern A).
+ *
+ * @param root - Project root directory
+ * @param config - Furnace configuration
+ * @returns Array of validation issues for mis-placed registrations
+ */
+export async function validateRegistrationPatterns(root, config) {
+    const issues = [];
+    const { engine: engineDir } = getProjectPaths(root);
+    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
+    if (!(await pathExists(filePath))) {
+        return issues;
+    }
+    const content = await readText(filePath);
+    // Find the DOMContentLoaded block boundary (handles multi-line addEventListener)
+    const dclMatch = /document\.addEventListener\(\s*["']DOMContentLoaded["']/.exec(content);
+    if (!dclMatch) {
+        return issues;
+    }
+    const domContentLoadedIdx = dclMatch.index;
+    // Get all custom component tag names that use .mjs (all custom components do)
+    for (const [name, customConfig] of Object.entries(config.custom)) {
+        if (!customConfig.register)
+            continue;
+        // Check if this tag is referenced before the DOMContentLoaded block
+        const contentBeforeDCL = stripJsComments(content.slice(0, domContentLoadedIdx));
+        const tagPattern = new RegExp(`"${name}"`);
+        if (tagPattern.test(contentBeforeDCL)) {
+            issues.push({
+                component: name,
+                severity: 'error',
+                check: 'wrong-registration-pattern',
+                message: `${name} is registered in the loadSubScript block (Pattern A) instead of the DOMContentLoaded/importESModule block (Pattern B). .mjs components must use Pattern B or they will fail at runtime.`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Checks registration consistency for a single custom component.
+ *
+ * Compares source files, engine target files, jar.mn entries, and
+ * customElements.js registration for a given component.
+ *
+ * @param root - Project root directory
+ * @param name - Component tag name
+ * @param config - Custom component configuration
+ * @returns Registration status with per-check booleans and drift info
+ */
+export async function checkRegistrationConsistency(root, name, config) {
+    const { engine: engineDir } = getProjectPaths(root);
+    const furnacePaths = getFurnacePaths(root);
+    const componentDir = join(furnacePaths.customDir, name);
+    const status = {
+        sourceExists: false,
+        targetExists: false,
+        filesInSync: true,
+        jarMnCss: false,
+        jarMnMjs: false,
+        customElementsPresent: false,
+        customElementsCorrectBlock: false,
+        driftedFiles: [],
+        missingTargetFiles: [],
+    };
+    // Check source directory
+    status.sourceExists = await pathExists(componentDir);
+    if (!status.sourceExists)
+        return status;
+    // Check target directory
+    const targetDir = join(engineDir, config.targetPath);
+    status.targetExists = await pathExists(targetDir);
+    // Compare files (sourceExists is guaranteed true — we early-returned above)
+    if (status.targetExists) {
+        const entries = await readdir(componentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
+                continue;
+            const srcPath = join(componentDir, entry.name);
+            const destPath = join(targetDir, entry.name);
+            if (!(await pathExists(destPath))) {
+                status.missingTargetFiles.push(entry.name);
+                status.filesInSync = false;
+                continue;
+            }
+            const srcContent = await readText(srcPath);
+            const destContent = await readText(destPath);
+            const srcHash = createHash('sha256').update(srcContent).digest('hex');
+            const destHash = createHash('sha256').update(destContent).digest('hex');
+            if (srcHash !== destHash) {
+                status.driftedFiles.push(entry.name);
+                status.filesInSync = false;
+            }
+        }
+    }
+    else {
+        status.filesInSync = false;
+    }
+    // Check jar.mn entries
+    const jarMnPath = join(engineDir, JAR_MN);
+    if (await pathExists(jarMnPath)) {
+        const jarContent = await readText(jarMnPath);
+        status.jarMnCss = jarContent.includes(`content/global/elements/${name}.css`);
+        status.jarMnMjs = jarContent.includes(`content/global/elements/${name}.mjs`);
+    }
+    // Check customElements.js registration
+    const cePath = join(engineDir, CUSTOM_ELEMENTS_JS);
+    if (await pathExists(cePath)) {
+        const ceContent = await readText(cePath);
+        status.customElementsPresent =
+            ceContent.includes(`"${name}"`) || ceContent.includes(`'${name}'`);
+        if (status.customElementsPresent) {
+            // Check it's in the correct block (after DOMContentLoaded)
+            const dclMatch = /document\.addEventListener\(\s*["']DOMContentLoaded["']/.exec(ceContent);
+            if (dclMatch) {
+                const afterDcl = ceContent.slice(dclMatch.index);
+                status.customElementsCorrectBlock =
+                    afterDcl.includes(`"${name}"`) || afterDcl.includes(`'${name}'`);
+            }
+        }
+    }
+    return status;
+}
+/**
+ * Validates that each custom component with `register: true` has its .mjs and
+ * .css entries in jar.mn.
+ *
+ * @param root - Project root directory
+ * @param config - Furnace configuration
+ * @returns Array of validation issues for missing jar.mn entries
+ */
+export async function validateJarMnEntries(root, config) {
+    const issues = [];
+    const { engine: engineDir } = getProjectPaths(root);
+    const jarMnPath = join(engineDir, JAR_MN);
+    if (!(await pathExists(jarMnPath))) {
+        return issues;
+    }
+    const jarContent = await readText(jarMnPath);
+    for (const [name, customConfig] of Object.entries(config.custom)) {
+        if (!customConfig.register)
+            continue;
+        if (!jarContent.includes(`content/global/elements/${name}.mjs`)) {
+            issues.push({
+                component: name,
+                severity: 'error',
+                check: 'missing-jar-mn-mjs',
+                message: `${name}.mjs is not registered in jar.mn. Run "fireforge furnace deploy" to register.`,
+            });
+        }
+        if (!jarContent.includes(`content/global/elements/${name}.css`)) {
+            issues.push({
+                component: name,
+                severity: 'warning',
+                check: 'missing-jar-mn-css',
+                message: `${name}.css is not registered in jar.mn.`,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Validates that components using design tokens have the tokens CSS
+ * linked in browser.xhtml. Without the link, tokens silently resolve to nothing.
+ */
+export async function validateTokenLink(componentDir, tagName, root, tokenPrefix) {
+    const issues = [];
+    const cssPath = join(componentDir, `${tagName}.css`);
+    if (!(await pathExists(cssPath)))
+        return issues;
+    if (!tokenPrefix)
+        return issues;
+    const cssContent = await readText(cssPath);
+    // Check if the component CSS references any tokens with the configured prefix
+    if (!cssContent.includes(tokenPrefix))
+        return issues;
+    // Check if browser.xhtml links the token CSS file
+    const { engine: engineDir } = getProjectPaths(root);
+    const browserXhtmlPath = join(engineDir, 'browser/base/content/browser.xhtml');
+    if (!(await pathExists(browserXhtmlPath)))
+        return issues;
+    let tokensCssFile;
+    try {
+        const forgeConfig = await loadConfig(root);
+        const segments = getTokensCssPath(forgeConfig.binaryName).split('/');
+        tokensCssFile = segments[segments.length - 1] ?? '';
+    }
+    catch (error) {
+        const reason = toError(error).message;
+        warn(`Could not resolve token CSS link target for ${tagName} during validation: ${reason}`);
+        return issues;
+    }
+    const xhtmlContent = await readText(browserXhtmlPath);
+    if (!xhtmlContent.includes(tokensCssFile)) {
+        issues.push({
+            component: tagName,
+            severity: 'warning',
+            check: 'missing-token-link',
+            message: `Component uses ${tokenPrefix}* tokens but browser.xhtml does not link ${tokensCssFile}. Tokens will silently resolve to nothing.`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=furnace-validate-registration.js.map

package/dist/src/core/furnace-validate-structure.d.ts

@@ -0,0 +1,6 @@
+import type { ComponentType, ValidationIssue } from '../types/furnace.js';
+/**
+ * Validates the file structure of a component directory.
+ * Checks for required files and naming conventions.
+ */
+export declare function validateStructure(componentDir: string, tagName: string, type: ComponentType): Promise<ValidationIssue[]>;

package/dist/src/core/furnace-validate-structure.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+/**
+ * Validates the file structure of a component directory.
+ * Checks for required files and naming conventions.
+ */
+export async function validateStructure(componentDir, tagName, type) {
+    const issues = [];
+    const mjsPath = join(componentDir, `${tagName}.mjs`);
+    const cssPath = join(componentDir, `${tagName}.css`);
+    // .mjs must exist for custom components
+    if (type === 'custom' && !(await pathExists(mjsPath))) {
+        issues.push({
+            component: tagName,
+            severity: 'error',
+            check: 'missing-mjs',
+            message: `Required file ${tagName}.mjs not found.`,
+        });
+    }
+    // .css should exist
+    if (!(await pathExists(cssPath))) {
+        issues.push({
+            component: tagName,
+            severity: 'warning',
+            check: 'missing-css',
+            message: `No ${tagName}.css found. Consider adding styles.`,
+        });
+    }
+    // File names should match tag name
+    const entries = await readdir(componentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
+            continue;
+        const fileName = entry.name;
+        if (/\.(test|spec|stories)\./.test(fileName))
+            continue;
+        const expectedPrefix = tagName;
+        const nameWithoutExt = entry.name.replace(/\.(mjs|css)$/, '');
+        if (nameWithoutExt !== expectedPrefix && !nameWithoutExt.startsWith(expectedPrefix + '-')) {
+            issues.push({
+                component: tagName,
+                severity: 'error',
+                check: 'filename-mismatch',
+                message: `File "${entry.name}" does not match expected naming convention "${tagName}.*".`,
+            });
+        }
+    }
+    // override.json must exist for overrides
+    if (type === 'override') {
+        const overrideJsonPath = join(componentDir, 'override.json');
+        if (!(await pathExists(overrideJsonPath))) {
+            issues.push({
+                component: tagName,
+                severity: 'error',
+                check: 'missing-override-json',
+                message: 'Required file override.json not found for override component.',
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=furnace-validate-structure.js.map

package/dist/src/core/furnace-validate.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentType, FurnaceConfig, ValidationIssue } from '../types/furnace.js';
+/**
+ * Runs all validation checks on a single component.
+ * @param componentDir - Path to the component directory
+ * @param tagName - Component tag name
+ * @param type - Component type (stock, override, custom)
+ * @returns Combined list of validation issues
+ */
+export declare function validateComponent(componentDir: string, tagName: string, type: ComponentType, config?: FurnaceConfig, root?: string): Promise<ValidationIssue[]>;
+/**
+ * Validates all components registered in furnace.json.
+ * Stock components are skipped (no local files to validate).
+ * @param root - Project root directory
+ * @returns Map of component name to its validation issues
+ */
+export declare function validateAllComponents(root: string): Promise<Map<string, ValidationIssue[]>>;

package/dist/src/core/furnace-validate.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { getFurnacePaths, loadFurnaceConfig } from './furnace-config.js';
+import { validateAccessibility, validateCompatibility, validateJarMnEntries, validateRegistrationPatterns, validateStructure, validateTokenLink, } from './furnace-validate-checks.js';
+// ---------------------------------------------------------------------------
+// Aggregate validators
+// ---------------------------------------------------------------------------
+/**
+ * Runs all validation checks on a single component.
+ * @param componentDir - Path to the component directory
+ * @param tagName - Component tag name
+ * @param type - Component type (stock, override, custom)
+ * @returns Combined list of validation issues
+ */
+export async function validateComponent(componentDir, tagName, type, config, root) {
+    const issues = [];
+    issues.push(...(await validateStructure(componentDir, tagName, type)));
+    issues.push(...(await validateAccessibility(componentDir, tagName)));
+    issues.push(...(await validateCompatibility(componentDir, tagName, type, config, root)));
+    // Check for missing token link in browser.xhtml
+    if (root) {
+        issues.push(...(await validateTokenLink(componentDir, tagName, root, config?.tokenPrefix)));
+    }
+    // When root is provided and this is a custom component with registration,
+    // also run registration pattern and jar.mn validation for this component.
+    if (root && config && type === 'custom') {
+        const customConfig = config.custom[tagName];
+        if (customConfig?.register) {
+            const singleConfig = {
+                ...config,
+                custom: { [tagName]: customConfig },
+            };
+            issues.push(...(await validateRegistrationPatterns(root, singleConfig)));
+            issues.push(...(await validateJarMnEntries(root, singleConfig)));
+        }
+    }
+    return issues;
+}
+/**
+ * Validates all components registered in furnace.json.
+ * Stock components are skipped (no local files to validate).
+ * @param root - Project root directory
+ * @returns Map of component name to its validation issues
+ */
+export async function validateAllComponents(root) {
+    const config = await loadFurnaceConfig(root);
+    const furnacePaths = getFurnacePaths(root);
+    const results = new Map();
+    // Override components
+    for (const name of Object.keys(config.overrides)) {
+        const componentDir = join(furnacePaths.overridesDir, name);
+        if (!(await pathExists(componentDir))) {
+            results.set(name, [
+                {
+                    component: name,
+                    severity: 'error',
+                    check: 'missing-component-dir',
+                    message: `Component directory not found: components/overrides/${name}`,
+                },
+            ]);
+            continue;
+        }
+        const issues = await validateComponent(componentDir, name, 'override', config, root);
+        results.set(name, issues);
+    }
+    // Custom components
+    for (const name of Object.keys(config.custom)) {
+        const componentDir = join(furnacePaths.customDir, name);
+        if (!(await pathExists(componentDir))) {
+            results.set(name, [
+                {
+                    component: name,
+                    severity: 'error',
+                    check: 'missing-component-dir',
+                    message: `Component directory not found: components/custom/${name}`,
+                },
+            ]);
+            continue;
+        }
+        // Pass root so that per-component token link validation runs.
+        // Per-component registration/jar.mn checks are also included, but that's
+        // acceptable as the aggregate validators below deduplicate by component name.
+        const issues = await validateComponent(componentDir, name, 'custom', config, root);
+        results.set(name, issues);
+    }
+    // Registration pattern validation (customElements.js Pattern A vs B)
+    const registrationIssues = await validateRegistrationPatterns(root, config);
+    for (const issue of registrationIssues) {
+        const existing = results.get(issue.component) ?? [];
+        existing.push(issue);
+        results.set(issue.component, existing);
+    }
+    // jar.mn entry validation
+    const jarMnIssues = await validateJarMnEntries(root, config);
+    for (const issue of jarMnIssues) {
+        const existing = results.get(issue.component) ?? [];
+        existing.push(issue);
+        results.set(issue.component, existing);
+    }
+    return results;
+}
+//# sourceMappingURL=furnace-validate.js.map

package/dist/src/core/git-base.d.ts

@@ -0,0 +1,47 @@
+/** Default timeout for `git add -A` on large trees (10 minutes). */
+export declare const GIT_ADD_TIMEOUT_MS: number;
+/** Timeout for chunked `git add` per top-level directory (20 minutes). */
+export declare const GIT_ADD_CHUNK_TIMEOUT_MS: number;
+/**
+ * Structured git status entry derived from `git status --porcelain=v1 -z`.
+ */
+export interface GitStatusEntry {
+    /** Two-character XY status as reported by porcelain output. */
+    status: string;
+    /** Index status character. */
+    indexStatus: string;
+    /** Worktree status character. */
+    worktreeStatus: string;
+    /** Canonical current path for the entry. */
+    file: string;
+    /** Original path for rename/copy entries. */
+    originalPath?: string | undefined;
+    /** True when the entry is an untracked path. */
+    isUntracked: boolean;
+    /** True when the entry represents a rename or copy. */
+    isRenameOrCopy: boolean;
+    /** True when the entry represents a deletion in either index or worktree. */
+    isDeleted: boolean;
+}
+/**
+ * Ensures git is available in the system.
+ * @throws GitNotFoundError if git is not installed
+ */
+export declare function ensureGit(): Promise<void>;
+/**
+ * Runs a git command in the specified directory.
+ * @param args - Git command arguments
+ * @param cwd - Working directory
+ * @returns Command output
+ */
+export declare function git(args: string[], cwd: string, options?: {
+    timeout?: number;
+    env?: Record<string, string>;
+}): Promise<string>;
+/**
+ * Configures git performance settings for large trees.
+ * Enables index preloading, untracked cache, and the manyFiles feature
+ * flag which significantly reduces `git add` / `git status` time on
+ * repositories with hundreds of thousands of files.
+ */
+export declare function configureGitPerformance(repoDir: string): Promise<void>;

package/dist/src/core/git-base.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { GitError, GitNotFoundError } from '../errors/git.js';
+import { exec, executableExists } from '../utils/process.js';
+/** Default timeout for `git add -A` on large trees (10 minutes). */
+export const GIT_ADD_TIMEOUT_MS = 10 * 60_000;
+/** Timeout for chunked `git add` per top-level directory (20 minutes). */
+export const GIT_ADD_CHUNK_TIMEOUT_MS = 20 * 60_000;
+/**
+ * Ensures git is available in the system.
+ * @throws GitNotFoundError if git is not installed
+ */
+export async function ensureGit() {
+    if (!(await executableExists('git'))) {
+        throw new GitNotFoundError();
+    }
+}
+/**
+ * Runs a git command in the specified directory.
+ * @param args - Git command arguments
+ * @param cwd - Working directory
+ * @returns Command output
+ */
+export async function git(args, cwd, options) {
+    const execOptions = { cwd };
+    if (options?.timeout !== undefined) {
+        execOptions.timeout = options.timeout;
+    }
+    if (options?.env !== undefined) {
+        execOptions.env = options.env;
+    }
+    const result = await exec('git', args, execOptions);
+    if (result.exitCode !== 0) {
+        throw new GitError(result.stderr.trim() || 'Git command failed', args.join(' '));
+    }
+    return result.stdout;
+}
+/**
+ * Configures git performance settings for large trees.
+ * Enables index preloading, untracked cache, and the manyFiles feature
+ * flag which significantly reduces `git add` / `git status` time on
+ * repositories with hundreds of thousands of files.
+ */
+export async function configureGitPerformance(repoDir) {
+    await git(['config', 'core.preloadindex', 'true'], repoDir);
+    await git(['config', 'core.untrackedCache', 'true'], repoDir);
+    // Explicitly disable fsmonitor to avoid daemon issues on freshly-created repos
+    await git(['config', 'core.fsmonitor', 'false'], repoDir);
+    await git(['config', 'feature.manyFiles', 'true'], repoDir);
+}
+//# sourceMappingURL=git-base.js.map

package/dist/src/core/git-diff.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Gets the diff for a specific file.
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ * @returns Diff content
+ */
+export declare function getFileDiff(repoDir: string, filePath: string): Promise<string>;
+/**
+ * Generates a unified diff for a new (untracked) file.
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ * @returns Diff content in unified diff format
+ */
+export declare function generateNewFileDiff(repoDir: string, filePath: string): Promise<string>;
+/**
+ * Generates a patch for a file.
+ * If the file is tracked in HEAD, it generates a standard contextual diff.
+ * If the file is untracked (new), it generates a "new file" format patch (snapshot).
+ * This ensures standard 3-way mergeable context diffs for existing Mozilla files.
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ * @returns Diff content in unified diff format
+ */
+export declare function generateFullFilePatch(repoDir: string, filePath: string): Promise<string>;
+/**
+ * Generates a unified diff between base content and current file content.
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ * @param baseContent - The base content to diff against
+ * @returns Unified diff in git format
+ */
+export declare function generateModificationDiff(repoDir: string, filePath: string, baseContent: string): Promise<string>;
+/**
+ * Gets the diff for all modified files, including untracked (new) files.
+ * @param repoDir - Repository directory
+ * @returns Diff content
+ */
+export declare function getAllDiff(repoDir: string): Promise<string>;
+/**
+ * Builds a combined diff against HEAD for the provided files without touching
+ * the real git index. Tracked files use `git diff HEAD`; untracked files use
+ * synthesized new-file diffs.
+ * @param repoDir - Repository directory
+ * @param files - File paths to diff (relative to repo root)
+ * @returns Combined diff content
+ */
+export declare function getDiffForFilesAgainstHead(repoDir: string, files: string[]): Promise<string>;
+/**
+ * Generates a combined diff for staged files against HEAD.
+ * @param repoDir - Repository directory
+ * @param files - File paths to diff (relative to repo)
+ * @returns Diff content for the staged files
+ */
+export declare function getStagedDiffForFiles(repoDir: string, files: string[]): Promise<string>;
+/**
+ * Generates a GIT binary patch for a binary file.
+ * For tracked files, uses `git diff --binary HEAD`.
+ * For untracked files, temporarily stages with `--intent-to-add` to produce a diff.
+ * @param repoDir - Repository directory
+ * @param filePath - File path (relative to repo root)
+ * @returns The binary diff string, or empty string if no diff
+ */
+export declare function generateBinaryFilePatch(repoDir: string, filePath: string): Promise<string>;