@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,331 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { pathExists } from '../utils/fs.js';
-import { getProjectPaths, loadConfig } from './config.js';
-import { extractComponentChecksums } from './furnace-checksum-utils.js';
-import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState } from './furnace-config.js';
-import { resolveFtlDir, xpcshellTestParentDir } from './furnace-constants.js';
-import { validateCssFragments } from './furnace-css-fragments.js';
-import { findJsconfigPathsDrift, typecheckJsconfigList } from './furnace-jsconfig.js';
-import { syncFurnaceTagMap } from './furnace-tag-map.js';
-import { validateAccessibility, validateCompatibility, validateJarMnEntries, validateRegistrationPatterns, validateStructure, validateTokenLink, } from './furnace-validate-checks.js';
-import { createIssue } from './furnace-validate-helpers.js';
-import { withRegistrationValidationCache } from './furnace-validate-registration.js';
-import { findOverrideBaseVersionDrift, } from './furnace-version-drift.js';
-function buildOverrideVersionDriftIssues(config, currentVersion, tagName) {
-    return findOverrideBaseVersionDrift(config, currentVersion)
-        .filter((entry) => tagName === undefined || entry.name === tagName)
-        .map((entry) => ({
-        component: entry.name,
-        severity: 'error',
-        check: 'override-base-version-drift',
-        message: `Override targets Firefox ${entry.baseVersion}, but fireforge.json records ${entry.currentVersion}. ` +
-            'Refresh the override if upstream changed, or update baseVersion in furnace.json to acknowledge the new baseline.',
-    }));
-}
-// ---------------------------------------------------------------------------
-// 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)
- * @param config - Optional furnace config for cross-component checks
- * @param root - Optional project root for checks that read outside componentDir
- * @param options - Optional behavior flags. `skipAggregateChecks` suppresses the
- *        per-component registration/jar.mn scan so that an outer caller
- *        (e.g. validateAllComponents) can run the aggregate versions once
- *        without double-reporting the same issues.
- * @returns Combined list of validation issues
- */
-export async function validateComponent(componentDir, tagName, type, config, root, options) {
-    const issues = [];
-    // Pass the matching custom config so structure validation can enforce
-    // the .ftl-when-localized invariant and accessibility validation can
-    // recognize wrapper-over-native components (via `composes` or an
-    // explicit `keyboardCovered` opt-out). Non-custom validations ignore the
-    // parameter, so this is a no-op for stock and override components.
-    const customConfigForTag = type === 'custom' ? config?.custom[tagName] : undefined;
-    issues.push(...(await validateStructure(componentDir, tagName, type, customConfigForTag)));
-    issues.push(...(await validateAccessibility(componentDir, tagName, customConfigForTag, config?.optInChecks)));
-    issues.push(...(await validateCompatibility(componentDir, tagName, type, config, root)));
-    if (root && config && type === 'override') {
-        const forgeConfig = await loadConfig(root);
-        issues.push(...buildOverrideVersionDriftIssues(config, forgeConfig.firefox.version, tagName));
-    }
-    // Check for missing token link across configured chrome host documents.
-    if (root) {
-        issues.push(...(await validateTokenLink(componentDir, tagName, root, config?.tokenPrefix, config?.tokenHostDocuments)));
-    }
-    // CSS fragment checks: missing fragment files are structural errors.
-    // Stale deployed expansions are drift the next deploy refreshes.
-    if (type === 'custom') {
-        const furnacePaths = getFurnacePaths(root ?? join(componentDir, '..', '..', '..'));
-        const engineTargetDir = root && config?.custom[tagName]
-            ? join(getProjectPaths(root).engine, config.custom[tagName].targetPath)
-            : undefined;
-        issues.push(...(await validateCssFragments(componentDir, tagName, furnacePaths.sharedDir, engineTargetDir)));
-    }
-    // Engine-side orphan detection: files a previous deploy placed in the
-    // engine whose workspace source has since been renamed or deleted.
-    // Surfaces as drift even when every current workspace file is in sync,
-    // which is the gap that lets stale jar.mn lines reach a later re-export.
-    if (root && config && type === 'custom') {
-        const state = await loadFurnaceState(root);
-        issues.push(...(await findOrphanedEngineFiles(root, config, tagName, state, resolveFtlDir(config.ftlBasePath))));
-    }
-    // When root is provided and this is a custom component with registration,
-    // also run registration pattern and jar.mn validation for this component.
-    // Skipped when an outer orchestrator (validateAllComponents) will run the
-    // aggregate versions itself. Otherwise the same issues are reported twice.
-    if (root && config && type === 'custom' && !options?.skipAggregateChecks) {
-        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) {
-    // Wrapped so the config parse and the chrome-document scan happen once for
-    // the whole batch instead of once per component. The caches are inert
-    // outside this window, so a direct `validateComponent` caller is never
-    // served a stale read.
-    return await withRegistrationValidationCache(async () => {
-        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.
-            // Skip registration/jar.mn checks inside validateComponent. The aggregate
-            // validators below run them exactly once across all components, which both
-            // surfaces cross-component issues and avoids double-counting.
-            const issues = await validateComponent(componentDir, name, 'custom', config, root, {
-                skipAggregateChecks: true,
-            });
-            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);
-        }
-        // Orphan xpcshell scaffold detection.
-        // `furnace create --with-tests --xpcshell` scaffolds a test directory at
-        // `browser/base/content/test/<binary>-xpcshell/<name>/`. A leftover
-        // scaffold whose `<name>` is not in furnace.json is almost always the
-        // aftermath of an incomplete `furnace remove` or `rename`. Flag it as an
-        // `orphan-xpcshell-scaffold` error so operators delete or re-create the
-        // scaffold instead of discovering the mismatch at test run time. A
-        // missing engine or scaffold parent directory degrades silently, so this
-        // check never adds noise on a project that never used xpcshell
-        // scaffolding.
-        try {
-            const orphanIssues = await findOrphanXpcshellScaffolds(root, config);
-            for (const issue of orphanIssues) {
-                const existing = results.get(issue.component) ?? [];
-                existing.push(issue);
-                results.set(issue.component, existing);
-            }
-        }
-        catch {
-            // Validation degrades gracefully: the absence of an engine
-            // directory, permission denial reading the scaffold tree, or any
-            // other transient fs issue should never cascade into false
-            // "orphan" reports.
-        }
-        // jsconfig chrome-module paths drift: when `typecheckJsconfig` is
-        // configured, deploy maintains a paths mapping per deployed module file
-        // in each listed jsconfig. Missing or stale entries mean typed
-        // cross-module imports are silently degrading to `any` in the
-        // consumer's typecheck. The tag map is checked the same way.
-        for (const issue of await findTypecheckArtifactDrift(root, config)) {
-            const existing = results.get(issue.component) ?? [];
-            existing.push(issue);
-            results.set(issue.component, existing);
-        }
-        return results;
-    });
-}
-/**
- * Drift findings for the Furnace-maintained typecheck files: one
- * `jsconfig-paths-drift` warning per out-of-date `typecheckJsconfig` file,
- * and a `tag-map-drift` warning when `typecheckTagMap` is out of date.
- * Detection never breaks validation: a missing or unparsable jsconfig is
- * reported by deploy, with guidance.
- */
-async function findTypecheckArtifactDrift(root, config) {
-    const issues = [];
-    for (const jsconfig of typecheckJsconfigList(config)) {
-        try {
-            const drift = await findJsconfigPathsDrift(root, config, jsconfig);
-            if (!drift.changed)
-                continue;
-            const detail = [
-                ...drift.added.map((key) => `missing: ${key}`),
-                ...drift.updated.map((key) => `stale: ${key}`),
-                ...drift.pruned.map((key) => `orphaned: ${key}`),
-            ].join('; ');
-            issues.push({
-                component: 'furnace',
-                severity: 'warning',
-                check: 'jsconfig-paths-drift',
-                message: `${jsconfig} chrome-module paths are out of sync with the workspace (${detail}). ` +
-                    'Run "fireforge furnace deploy" to update them.',
-            });
-        }
-        catch {
-            continue;
-        }
-    }
-    try {
-        const tagMap = await syncFurnaceTagMap(root, config, { dryRun: true });
-        if (tagMap?.changed === true) {
-            issues.push({
-                component: 'furnace',
-                severity: 'warning',
-                check: 'tag-map-drift',
-                message: `${tagMap.file} is out of date with the workspace's custom element definitions. ` +
-                    'Run "fireforge furnace deploy" to rewrite it.',
-            });
-        }
-    }
-    catch {
-        // An unreadable component module is reported by the other checks.
-    }
-    return issues;
-}
-/**
- * Scans the per-binary xpcshell scaffold directory for entries whose
- * component name is not present in furnace.json, and returns an
- * `orphan-xpcshell-scaffold` issue for each one.
- */
-async function findOrphanXpcshellScaffolds(root, config) {
-    const forgeConfig = await loadConfig(root);
-    const paths = getProjectPaths(root);
-    const parentRel = xpcshellTestParentDir(forgeConfig.binaryName);
-    const parentAbs = join(paths.engine, parentRel);
-    if (!(await pathExists(parentAbs)))
-        return [];
-    let entries;
-    try {
-        const dirents = await readdir(parentAbs, { withFileTypes: true });
-        entries = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
-    }
-    catch {
-        // An unreadable parent directory yields no sibling component dirs.
-        return [];
-    }
-    const known = new Set([
-        ...Object.keys(config.custom),
-        ...Object.keys(config.overrides),
-        ...config.stock,
-    ]);
-    const issues = [];
-    for (const entry of entries) {
-        if (known.has(entry))
-            continue;
-        const chromeDocPackagingTest = join(parentAbs, entry, `test_${entry}_packaging.js`);
-        if (await pathExists(chromeDocPackagingTest))
-            continue;
-        issues.push({
-            component: entry,
-            severity: 'error',
-            check: 'orphan-xpcshell-scaffold',
-            message: `Stale xpcshell test scaffold at ${parentRel}/${entry}/ — no matching component is declared in furnace.json. ` +
-                'Delete the scaffold directory manually, or re-run `fireforge furnace create --with-tests --xpcshell` for an existing component with the same name.',
-        });
-    }
-    return issues;
-}
-/**
- * Flags engine-side files that a previous deploy of `tagName` left behind
- * after their workspace source was renamed or removed.
- *
- * Detection keys on the furnace state file: every `appliedChecksums` entry
- * under `custom/<tagName>/` whose workspace source no longer exists but whose
- * engine target is still present is an orphan. The next deploy prunes it, but
- * until then jar.mn and the deployed directory disagree with the workspace,
- * and a re-export could capture the stale state into a patch.
- *
- * Custom components only: override undeploys restore the upstream baseline
- * rather than deleting files, so "orphan" has no meaning there.
- */
-export async function findOrphanedEngineFiles(root, config, tagName, state, ftlDir) {
-    const customConfig = config.custom[tagName];
-    if (!customConfig)
-        return [];
-    const previous = extractComponentChecksums(state.appliedChecksums, 'custom', tagName);
-    const fileNames = Object.keys(previous);
-    if (fileNames.length === 0)
-        return [];
-    const { engine: engineDir, componentsDir } = getProjectPaths(root);
-    const componentDir = join(componentsDir, 'custom', tagName);
-    const issues = [];
-    for (const fileName of fileNames) {
-        if (await pathExists(join(componentDir, fileName)))
-            continue;
-        const enginePath = fileName.endsWith('.ftl')
-            ? join(engineDir, ftlDir, fileName)
-            : join(engineDir, customConfig.targetPath, fileName);
-        if (!(await pathExists(enginePath)))
-            continue;
-        issues.push(createIssue(tagName, 'warning', 'orphaned-engine-file', `Engine file ${fileName} was deployed by a previous apply but its workspace source ` +
-            `is gone (renamed or deleted). The deployed copy${customConfig.register ? ' and any stale jar.mn entry' : ''} ` +
-            `will linger until the next deploy prunes it. Run "fireforge furnace deploy ${tagName}".`));
-    }
-    return issues;
-}

package/dist/src/core/furnace-version-drift.d.ts

@@ -1,57 +0,0 @@
-/**
- * Detects drift between an override's stored `baseVersion` and the current
- * Firefox version recorded in `fireforge.json`.
- *
- * Overrides are forks of Firefox source files taken at a specific point in
- * time. If Firefox moves forward and the override's `baseVersion` is not
- * refreshed, the override may apply against a file whose upstream shape has
- * changed, which is the single biggest silent failure mode for furnace.
- *
- * Deliberately pure and string-only: no I/O, and no parsing of Firefox
- * version components. String equality is sufficient because `fireforge.json`
- * stores a canonical version string (e.g. `"140.9.0esr"`) and overrides are
- * created with exactly that string copied from
- * `forgeConfig.firefox.version`. Any mismatch is worth surfacing: even
- * "140.0" vs "140.9.0esr" is a real drift signal.
- *
- * The result gates apply/deploy: both warn and then fail without --force
- * (see furnaceApplyCommand / furnaceDeployCommand), and `furnace sync`
- * re-checks it after refresh before applying. Status reports drift alongside
- * the component overview. Keep this doc in sync with the gates. It is not
- * advisory.
- */
-import type { FurnaceConfig } from '../types/furnace.js';
-/** Severity of the version drift between an override's base and the current Firefox version. */
-export type DriftSeverity = 'major' | 'minor' | 'patch';
-export interface OverrideVersionDrift {
-    name: string;
-    /** The version the override was originally created against. */
-    baseVersion: string;
-    /** The Firefox version currently recorded in `fireforge.json`. */
-    currentVersion: string;
-    /** How severe the drift is, based on comparing version components. */
-    severity: DriftSeverity;
-}
-/**
- * Classifies how severe a version drift is by comparing the numeric
- * components of the two version strings. Falls back to `'major'` when
- * either version is unparseable. This ensures that unusual version
- * formats surface with the highest visibility rather than being silently
- * downgraded.
- */
-export declare function classifyDriftSeverity(baseVersion: string, currentVersion: string): DriftSeverity;
-/**
- * Returns every override whose recorded `baseVersion` does not match the
- * current Firefox version. Returns an empty array when everything is in
- * sync, when there are no overrides, or when `currentVersion` is empty
- * (the caller should surface config problems via a different path).
- */
-export declare function findOverrideBaseVersionDrift(config: FurnaceConfig, currentVersion: string): OverrideVersionDrift[];
-/**
- * Formats a single drift entry into a one-line human-readable warning.
- * Kept alongside the detector so the same wording is reused by every
- * command that surfaces drift.
- */
-export declare function formatOverrideBaseVersionDriftWarning(entry: OverrideVersionDrift): string;
-/** Formats a blocking preflight error for one or more stale overrides. */
-export declare function formatOverrideBaseVersionDriftError(entries: OverrideVersionDrift[]): string;

package/dist/src/core/furnace-version-drift.js

@@ -1,102 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Detects drift between an override's stored `baseVersion` and the current
- * Firefox version recorded in `fireforge.json`.
- *
- * Overrides are forks of Firefox source files taken at a specific point in
- * time. If Firefox moves forward and the override's `baseVersion` is not
- * refreshed, the override may apply against a file whose upstream shape has
- * changed, which is the single biggest silent failure mode for furnace.
- *
- * Deliberately pure and string-only: no I/O, and no parsing of Firefox
- * version components. String equality is sufficient because `fireforge.json`
- * stores a canonical version string (e.g. `"140.9.0esr"`) and overrides are
- * created with exactly that string copied from
- * `forgeConfig.firefox.version`. Any mismatch is worth surfacing: even
- * "140.0" vs "140.9.0esr" is a real drift signal.
- *
- * The result gates apply/deploy: both warn and then fail without --force
- * (see furnaceApplyCommand / furnaceDeployCommand), and `furnace sync`
- * re-checks it after refresh before applying. Status reports drift alongside
- * the component overview. Keep this doc in sync with the gates. It is not
- * advisory.
- */
-/**
- * Parses a version string into its major, minor, and patch numeric
- * components. Non-numeric suffixes (e.g. "esr") are stripped. Returns
- * `[NaN, NaN, NaN]` for unparseable strings.
- */
-function parseVersionComponents(version) {
-    const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(version);
-    if (!match)
-        return [NaN, NaN, NaN];
-    return [
-        Number(match[1]),
-        match[2] !== undefined ? Number(match[2]) : 0,
-        match[3] !== undefined ? Number(match[3]) : 0,
-    ];
-}
-/**
- * Classifies how severe a version drift is by comparing the numeric
- * components of the two version strings. Falls back to `'major'` when
- * either version is unparseable. This ensures that unusual version
- * formats surface with the highest visibility rather than being silently
- * downgraded.
- */
-export function classifyDriftSeverity(baseVersion, currentVersion) {
-    const [baseMajor, baseMinor] = parseVersionComponents(baseVersion);
-    const [curMajor, curMinor] = parseVersionComponents(currentVersion);
-    if (isNaN(baseMajor) || isNaN(curMajor))
-        return 'major';
-    if (baseMajor !== curMajor)
-        return 'major';
-    if (baseMinor !== curMinor)
-        return 'minor';
-    return 'patch';
-}
-/**
- * Returns every override whose recorded `baseVersion` does not match the
- * current Firefox version. Returns an empty array when everything is in
- * sync, when there are no overrides, or when `currentVersion` is empty
- * (the caller should surface config problems via a different path).
- */
-export function findOverrideBaseVersionDrift(config, currentVersion) {
-    if (!currentVersion)
-        return [];
-    const drift = [];
-    for (const [name, override] of Object.entries(config.overrides)) {
-        if (override.baseVersion && override.baseVersion !== currentVersion) {
-            drift.push({
-                name,
-                baseVersion: override.baseVersion,
-                currentVersion,
-                severity: classifyDriftSeverity(override.baseVersion, currentVersion),
-            });
-        }
-    }
-    return drift;
-}
-/**
- * Formats a single drift entry into a one-line human-readable warning.
- * Kept alongside the detector so the same wording is reused by every
- * command that surfaces drift.
- */
-export function formatOverrideBaseVersionDriftWarning(entry) {
-    const severityLabel = entry.severity === 'major'
-        ? ' (major version jump)'
-        : entry.severity === 'minor'
-            ? ' (minor version change)'
-            : ' (patch-level change)';
-    return `Override "${entry.name}" was created against Firefox ${entry.baseVersion}, but fireforge.json records ${entry.currentVersion}${severityLabel}. The upstream component may have changed — re-run "fireforge furnace validate ${entry.name}" and refresh the override if needed.`;
-}
-/** Formats a blocking preflight error for one or more stale overrides. */
-export function formatOverrideBaseVersionDriftError(entries) {
-    const names = entries.map((entry) => entry.name).sort();
-    const summary = entries.length === 1
-        ? `Override "${names[0]}" is stale against the Firefox version recorded in fireforge.json.`
-        : `${entries.length} overrides are stale against the Firefox version recorded in fireforge.json (${names.join(', ')}).`;
-    return (`${summary}\n\n` +
-        'Run "fireforge furnace refresh <name>" to merge upstream changes, ' +
-        'update baseVersion in furnace.json to acknowledge the new baseline, ' +
-        'or pass --force to proceed despite the drift.');
-}

package/dist/src/core/gecko-dom-types.d.ts

@@ -1,2 +0,0 @@
-/** Adds Gecko's cross-compartment DOM predicates to virtual lib.dom constructor types. */
-export declare function withGeckoDomTypes(ts: typeof import('typescript'), host: import('typescript').CompilerHost): import('typescript').CompilerHost;

package/dist/src/core/gecko-dom-types.js

@@ -1,17 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/** Adds Gecko's cross-compartment DOM predicates to virtual lib.dom constructor types. */
-export function withGeckoDomTypes(ts, host) {
-    const original = host.getSourceFile.bind(host);
-    return {
-        ...host,
-        getSourceFile(...args) {
-            const file = original(...args);
-            if (!file || !args[0].endsWith('/lib.dom.d.ts'))
-                return file;
-            const source = file.text.replace(/declare var (\w+): \{\s*prototype: (\w+);/g, (declaration, name, instance) => declaration +
-                `\n    isInstance(value: unknown): value is ${instance};` +
-                (name === 'MouseEvent' ? '\n    readonly MOZ_SOURCE_PEN: number;' : ''));
-            return ts.createSourceFile(args[0], source, args[1], true);
-        },
-    };
-}

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

@@ -1,101 +0,0 @@
-/**
- * Environment variable that overrides the monolithic `git add -A` timeout
- * (milliseconds). Operators on slow or loaded filesystems can legitimately
- * exceed the 10-minute default during a baseline indexing pass. Making the
- * cap overridable lets them retry without recompiling.
- */
-export declare const GIT_ADD_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_TIMEOUT_MS";
-/**
- * Environment variable that overrides the per-chunk `git add -- <dir>`
- * timeout (milliseconds). Paired with {@link GIT_ADD_TIMEOUT_ENV_VAR} so
- * both the monolithic attempt and the chunked fallback can be extended.
- */
-export declare const GIT_ADD_CHUNK_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS";
-/**
- * Resolved timeout for monolithic `git add -A`. Prefers
- * {@link GIT_ADD_TIMEOUT_ENV_VAR} when present (and a positive
- * integer) so operators on slow hosts can extend the default without
- * rebuilding FireForge.
- */
-export declare const GIT_ADD_TIMEOUT_MS: number;
-/**
- * Resolved timeout for each chunk of the chunked fallback path. Generous by
- * design: the fallback is already the last line of defence before aborting,
- * so erring toward "complete the indexing" over "fail fast" matches the
- * real-world recovery workflow.
- */
-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. Memoised after the first successful
- * probe. {@link git} calls it, so callers that go through that wrapper do not
- * need to.
- * @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>;
-/**
- * Splits a pathspec list into chunks whose joined byte length stays well under
- * the OS `ARG_MAX` limit, so a single batched `git` invocation over hundreds of
- * Mozilla-length paths cannot fail with `E2BIG`. The 96 KB budget is
- * conservative on purpose: even the smallest historical `ARG_MAX` (256 KB)
- * leaves room for the fixed git arguments plus the inherited environment.
- *
- * Chunk boundaries are output-neutral for every batched caller here: each
- * caller merges the per-chunk results into a single Set/Map keyed by path, so
- * how the paths are grouped across invocations never affects the result.
- * @param paths - Pathspecs to chunk
- * @param budgetBytes - Maximum joined byte length per chunk
- * @returns Path chunks, each safe to pass as a single argv tail
- */
-export declare function chunkPathspecs(paths: string[], budgetBytes?: number): 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>;
-/**
- * Pins the engine repository's line-ending policy to "store and check out
- * exactly what upstream shipped".
- *
- * Git's Windows installer defaults to a global `core.autocrlf=true`, which
- * rewrites LF to CRLF on checkout and back on staging. FireForge cannot
- * tolerate that: patch bodies are byte diffs of the working tree, and
- * `hashObjectBatch` deliberately delegates to git so `.gitattributes` and
- * `core.autocrlf` do apply to the hashes `status` compares against. Under the
- * global default the same tree hashes differently on Windows than everywhere
- * else, so exported patches and drift detection disagree across machines.
- * Setting it per-repository leaves the developer's global config alone.
- */
-export declare function configureGitLineEndings(repoDir: string): Promise<void>;