@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,503 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Config schema validation for fireforge.json.
- */
-import { ConfigError } from '../errors/config.js';
-import { verbose } from '../utils/logger.js';
-import { parseObject } from '../utils/parse.js';
-import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
-import { describeProductVersionIncompatibility, FIREFOX_PRODUCTS, isObject, isValidAppId, isValidFirefoxCandidate, isValidFirefoxProduct, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, } from '../utils/validation.js';
-import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
-import { parseBuildAuditConfig } from './config-validate-build-audit.js';
-import { parseCheckConfig } from './config-validate-check.js';
-import { parsePatchLintSizeFields } from './config-validate-file-size.js';
-import { parseHistoryBlock } from './config-validate-history.js';
-import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
-import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
-import { parsePatchLintTokenScales } from './config-validate-token-scales.js';
-/**
- * Parses and validates the four required identity fields (`name`,
- * `vendor`, `appId`, `binaryName`): all non-empty strings, with
- * `binaryName` additionally barred from path separators/traversal and
- * `appId` required to be a reverse-domain identifier.
- */
-function parseIdentityFields(rec) {
-    // Empty strings would technically pass the
-    // typeof-check below but are never valid for any of these identifier
-    // fields. Rejecting them here prevents downstream code (Firefox build,
-    // launcher binary lookup, AppID assertions) from failing with confusing
-    // errors much later.
-    const name = requireConfigString(rec, 'name');
-    const vendor = requireConfigString(rec, 'vendor');
-    const appId = requireConfigString(rec, 'appId');
-    const binaryName = requireConfigString(rec, 'binaryName');
-    for (const [field, value] of [
-        ['name', name],
-        ['vendor', vendor],
-        ['appId', appId],
-        ['binaryName', binaryName],
-    ]) {
-        if (value.trim() === '') {
-            throw new ConfigError(`Config field "${field}" must not be empty`);
-        }
-    }
-    if (binaryName.includes('..') ||
-        binaryName.includes('/') ||
-        binaryName.includes('\\') ||
-        binaryName.includes('\0')) {
-        throw new ConfigError('Config field "binaryName" must not contain path separators, "..", or null bytes');
-    }
-    if (isExplicitAbsolutePath(binaryName)) {
-        throw new ConfigError('Config field "binaryName" must not be an absolute path');
-    }
-    if (!isValidAppId(appId)) {
-        throw new ConfigError('Config field "appId" must be a valid reverse-domain identifier (e.g., "org.example.browser")');
-    }
-    return { name, vendor, appId, binaryName };
-}
-/**
- * Parses and validates the required `firefox` block: version shape,
- * product allowlist, product/version cross-compatibility, and the
- * optional sha256 digest (normalized to lowercase), optional
- * `allowUnverifiedDownload` opt-out, optional candidate directory.
- */
-function parseFirefoxBlock(rec) {
-    let firefoxRec;
-    try {
-        firefoxRec = rec.object('firefox');
-    }
-    catch {
-        throw new ConfigError('Config field "firefox" must be an object');
-    }
-    const firefoxVersion = requireConfigString(firefoxRec, 'version', 'firefox.version');
-    if (!isValidFirefoxVersion(firefoxVersion)) {
-        throw new ConfigError('Config field "firefox.version" must be a valid Firefox version (e.g., "145.0")');
-    }
-    const firefoxProduct = requireConfigString(firefoxRec, 'product', 'firefox.product');
-    // Uses the shared guard rather than a separate copy of the member list.
-    // This is the fireforge.json read path: a product added to the union but
-    // not to a local copy would be silently rejected from every project
-    // config.
-    if (!isValidFirefoxProduct(firefoxProduct)) {
-        throw new ConfigError(`Config field "firefox.product" must be one of: ${FIREFOX_PRODUCTS.join(', ')}`);
-    }
-    // Cross-field validation: product and version must be compatible
-    const compatError = describeProductVersionIncompatibility(firefoxVersion, firefoxProduct);
-    if (compatError) {
-        throw new ConfigError(compatError);
-    }
-    const firefoxSha256 = optionalConfigString(firefoxRec, 'sha256', 'firefox.sha256');
-    if (firefoxSha256 !== undefined && !/^[a-f0-9]{64}$/i.test(firefoxSha256)) {
-        throw new ConfigError('Config field "firefox.sha256" must be a 64-character SHA-256 hex digest');
-    }
-    const allowUnverifiedDownload = firefoxRec.raw('allowUnverifiedDownload');
-    if (allowUnverifiedDownload !== undefined && typeof allowUnverifiedDownload !== 'boolean') {
-        throw new ConfigError('Config field "firefox.allowUnverifiedDownload" must be a boolean');
-    }
-    const firefoxCandidate = optionalConfigString(firefoxRec, 'candidate', 'firefox.candidate');
-    if (firefoxCandidate !== undefined && !isValidFirefoxCandidate(firefoxCandidate)) {
-        throw new ConfigError('Config field "firefox.candidate" must look like "buildN" (e.g. "build2")');
-    }
-    return {
-        version: firefoxVersion,
-        product: firefoxProduct,
-        ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
-        ...(allowUnverifiedDownload !== undefined ? { allowUnverifiedDownload } : {}),
-        ...(firefoxCandidate !== undefined ? { candidate: firefoxCandidate } : {}),
-    };
-}
-/** Parses the optional `build` block (currently just `build.jobs`). */
-function parseBuildBlock(rec, config) {
-    const buildRec = optionalConfigObject(rec, 'build');
-    if (buildRec) {
-        config.build = {};
-        const jobs = buildRec.raw('jobs');
-        if (jobs !== undefined) {
-            if (typeof jobs !== 'number' || !Number.isInteger(jobs) || jobs <= 0) {
-                throw new ConfigError('Config field "build.jobs" must be a positive integer');
-            }
-            config.build.jobs = jobs;
-        }
-    }
-}
-/** Parses the optional `wire` block (currently just `wire.subscriptDir`). */
-function parseWireBlock(rec, config) {
-    const wireRec = optionalConfigObject(rec, 'wire');
-    if (wireRec) {
-        config.wire = {};
-        const subscriptDir = optionalConfigString(wireRec, 'subscriptDir', 'wire.subscriptDir');
-        if (subscriptDir !== undefined) {
-            if (!isContainedRelativePath(subscriptDir)) {
-                throw new ConfigError('Config field "wire.subscriptDir" must stay within engine/');
-            }
-            config.wire.subscriptDir = subscriptDir;
-        }
-    }
-}
-/** Parses the optional `license` field against the supported-license list. */
-function parseLicenseField(rec, config) {
-    const licenseRaw = rec.raw('license');
-    if (licenseRaw !== undefined) {
-        if (typeof licenseRaw !== 'string') {
-            throw new ConfigError('Config field "license" must be a string');
-        }
-        if (!isValidProjectLicense(licenseRaw)) {
-            throw new ConfigError(`Config field "license" must be one of: ${PROJECT_LICENSES.join(', ')}`);
-        }
-        config.license = licenseRaw;
-    }
-}
-/**
- * Validates a raw config object and returns a typed FireForgeConfig.
- * @param data - Raw data to validate
- * @returns Validated FireForgeConfig
- * @throws Error if validation fails
- */
-export function validateConfig(data) {
-    let rec;
-    try {
-        rec = parseObject(data, 'Config');
-    }
-    catch {
-        throw new ConfigError('Config must be an object');
-    }
-    const identity = parseIdentityFields(rec);
-    const firefox = parseFirefoxBlock(rec);
-    const config = { ...identity, firefox };
-    parseBuildBlock(rec, config);
-    const buildAuditRaw = rec.raw('buildAudit');
-    if (buildAuditRaw !== undefined) {
-        config.buildAudit = parseBuildAuditConfig(buildAuditRaw);
-    }
-    parseTestBlock(rec, config);
-    parseHistoryBlock(rec, config);
-    parseExternalToolchainsBlock(rec, config);
-    parseWireBlock(rec, config);
-    parseLicenseField(rec, config);
-    // Marker comment, appended to lines FireForge writes into upstream files.
-    const markerComment = parseMarkerComment(rec.raw('markerComment'));
-    if (markerComment !== undefined) {
-        config.markerComment = markerComment;
-    }
-    // PatchLint
-    const patchLintRec = optionalConfigObject(rec, 'patchLint');
-    if (patchLintRec) {
-        config.patchLint = parsePatchLintBlock(patchLintRec);
-    }
-    // PatchPolicy
-    const patchPolicyRec = optionalConfigObject(rec, 'patchPolicy');
-    if (patchPolicyRec) {
-        config.patchPolicy = parsePatchPolicyBlock(patchPolicyRec);
-    }
-    // Typecheck (top-level, distinct from patchLint). See TypecheckConfig docs.
-    const typecheckRec = optionalConfigObject(rec, 'typecheck');
-    if (typecheckRec) {
-        config.typecheck = parseTypecheckBlock(typecheckRec);
-    }
-    // `fireforge check` policy and project steps.
-    const checkRaw = rec.raw('check');
-    if (checkRaw !== undefined) {
-        config.check = parseCheckConfig(checkRaw);
-    }
-    // Warn on unknown root keys
-    const knownRootKeys = new Set(SUPPORTED_CONFIG_ROOT_KEYS);
-    for (const key of rec.keys()) {
-        if (!knownRootKeys.has(key)) {
-            verbose(`Unknown config key "${key}" in fireforge.json — it will be ignored.`);
-        }
-    }
-    return config;
-}
-// ── Internal helpers (wrap parseObject errors with ConfigError) ──
-function requireConfigString(rec, key, label) {
-    const value = rec.raw(key);
-    if (typeof value !== 'string') {
-        throw new ConfigError(`Config field "${label ?? key}" must be a string`);
-    }
-    return value;
-}
-function optionalConfigString(rec, key, label) {
-    const value = rec.raw(key);
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== 'string') {
-        throw new ConfigError(`Config field "${label}" must be a string`);
-    }
-    return value;
-}
-/**
- * Validates a raw `markerComment` value. Rejected values: non-strings, empty
- * strings, surrounding whitespace (ambiguous format), newlines (would break
- * source formatting), and `*&#47;` (would terminate an enclosing block comment
- * downstream). Control characters are rejected for the same reason.
- */
-function parseMarkerComment(raw) {
-    if (raw === undefined)
-        return undefined;
-    if (typeof raw !== 'string') {
-        throw new ConfigError('Config field "markerComment" must be a string');
-    }
-    if (raw.trim() === '') {
-        throw new ConfigError('Config field "markerComment" must not be empty');
-    }
-    if (raw !== raw.trim()) {
-        throw new ConfigError('Config field "markerComment" must not have leading or trailing whitespace');
-    }
-    if (/[\n\r]/.test(raw) || raw.includes('*/')) {
-        throw new ConfigError('Config field "markerComment" must not contain newlines or "*/"');
-    }
-    // eslint-disable-next-line no-control-regex -- intentionally rejecting control chars
-    if (/[\x00-\x1f]/.test(raw)) {
-        throw new ConfigError('Config field "markerComment" must not contain control characters');
-    }
-    return raw;
-}
-function optionalConfigObject(rec, key) {
-    const value = rec.raw(key);
-    if (value === undefined)
-        return undefined;
-    try {
-        return rec.object(key);
-    }
-    catch {
-        throw new ConfigError(`Config field "${key}" must be an object`);
-    }
-}
-const SEVERITY_GATE_VALUES = ['off', 'warning', 'error'];
-/** Allowlisted keys for `patchLint.checkJsCompilerOptions` (boolean overrides only). */
-const PATCH_LINT_CHECKJS_COMPILER_OPTION_KEYS = [
-    'strictNullChecks',
-    'strictFunctionTypes',
-    'strictBindCallApply',
-    'noImplicitThis',
-    'useUnknownInCatchVariables',
-    'strictPropertyInitialization',
-    'noUnusedLocals',
-    'noUnusedParameters',
-];
-/**
- * Validates the reviewed `paths` mapping: an object of pattern → string[]
- * targets, each pattern carrying at most one `*`. Lets patch-owned modules
- * be typed from their real sources without an ambient stub shim.
- */
-function parseCheckJsPathsMapping(raw) {
-    if (!isObject(raw)) {
-        throw new ConfigError('Config field "patchLint.checkJsCompilerOptions.paths" must be a plain object');
-    }
-    const rec = raw;
-    const out = {};
-    for (const [pattern, targets] of Object.entries(rec)) {
-        if ((pattern.match(/\*/g) ?? []).length > 1) {
-            throw new ConfigError(`Config field "patchLint.checkJsCompilerOptions.paths" key "${pattern}" may contain at most one "*"`);
-        }
-        if (!Array.isArray(targets) || targets.some((t) => typeof t !== 'string')) {
-            throw new ConfigError(`Config field "patchLint.checkJsCompilerOptions.paths.${pattern}" must be an array of strings`);
-        }
-        out[pattern] = targets;
-    }
-    return out;
-}
-function parsePatchLintCheckJsCompilerOptions(raw) {
-    if (!isObject(raw)) {
-        throw new ConfigError('Config field "patchLint.checkJsCompilerOptions" must be a plain object');
-    }
-    const rec = raw;
-    const allowed = new Set(PATCH_LINT_CHECKJS_COMPILER_OPTION_KEYS);
-    const out = {};
-    for (const key of Object.keys(rec)) {
-        if (key === 'paths') {
-            out.paths = parseCheckJsPathsMapping(rec[key]);
-            continue;
-        }
-        if (!allowed.has(key)) {
-            throw new ConfigError(`Config field "patchLint.checkJsCompilerOptions" has unknown key "${key}"`);
-        }
-        const val = rec[key];
-        if (typeof val !== 'boolean') {
-            throw new ConfigError(`Config field "patchLint.checkJsCompilerOptions.${key}" must be a boolean`);
-        }
-        out[key] = val;
-    }
-    return out;
-}
-function parseSeverityGate(raw, label) {
-    if (raw === undefined)
-        return undefined;
-    if (typeof raw !== 'string' || !SEVERITY_GATE_VALUES.includes(raw)) {
-        throw new ConfigError(`Config field "${label}" must be one of: ${SEVERITY_GATE_VALUES.join(', ')}`);
-    }
-    return raw;
-}
-/**
- * Reads an optional boolean `patchLint` field, rejecting a non-boolean with
- * the field-named message. Three identical inline copies of this shape were
- * part of what held `parsePatchLintBlock` at complexity 25/30.
- */
-function optionalPatchLintBoolean(rec, key) {
-    const value = rec.raw(key);
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== 'boolean') {
-        throw new ConfigError(`Config field "patchLint.${key}" must be a boolean`);
-    }
-    return value;
-}
-/** Severity-gate fields, each parsed and assigned identically. */
-const PATCH_LINT_SEVERITY_GATE_KEYS = [
-    'prettier',
-    'jsdocClassMethods',
-    'testAssertionFloor',
-    'chromeScriptJsDoc',
-    'undefinedIdentifiers',
-];
-function parsePatchLintBlock(rec) {
-    const out = {};
-    const checkJs = optionalPatchLintBoolean(rec, 'checkJs');
-    if (checkJs !== undefined)
-        out.checkJs = checkJs;
-    const checkJsStrict = optionalPatchLintBoolean(rec, 'checkJsStrict');
-    if (checkJsStrict !== undefined)
-        out.checkJsStrict = checkJsStrict;
-    const checkJsCompilerOptionsRaw = rec.raw('checkJsCompilerOptions');
-    if (checkJsCompilerOptionsRaw !== undefined) {
-        out.checkJsCompilerOptions = parsePatchLintCheckJsCompilerOptions(checkJsCompilerOptionsRaw);
-    }
-    const checkJsExtraShim = rec.raw('checkJsExtraShim');
-    if (checkJsExtraShim !== undefined) {
-        out.checkJsExtraShim = parseShimPath(checkJsExtraShim, 'patchLint.checkJsExtraShim');
-    }
-    const checkJsTestFiles = optionalPatchLintBoolean(rec, 'checkJsTestFiles');
-    if (checkJsTestFiles !== undefined)
-        out.checkJsTestFiles = checkJsTestFiles;
-    const checkJsTestShim = rec.raw('checkJsTestShim');
-    if (checkJsTestShim !== undefined) {
-        out.checkJsTestShim = parseShimPath(checkJsTestShim, 'patchLint.checkJsTestShim');
-    }
-    const rawColorAllowlist = rec.raw('rawColorAllowlist');
-    if (rawColorAllowlist !== undefined) {
-        if (!Array.isArray(rawColorAllowlist) ||
-            rawColorAllowlist.some((v) => typeof v !== 'string')) {
-            throw new ConfigError('Config field "patchLint.rawColorAllowlist" must be an array of strings');
-        }
-        out.rawColorAllowlist = rawColorAllowlist;
-    }
-    Object.assign(out, parsePatchLintSizeFields((key) => rec.raw(key)));
-    const forwardRegistration = rec.raw('forwardRegistration');
-    if (forwardRegistration !== undefined) {
-        if (forwardRegistration !== 'support-files' && forwardRegistration !== 'extended') {
-            throw new ConfigError('Config field "patchLint.forwardRegistration" must be one of: support-files, extended');
-        }
-        out.forwardRegistration = forwardRegistration;
-    }
-    const tokenScales = rec.raw('tokenScales');
-    if (tokenScales !== undefined)
-        out.tokenScales = parsePatchLintTokenScales(tokenScales);
-    for (const key of PATCH_LINT_SEVERITY_GATE_KEYS) {
-        const gate = parseSeverityGate(rec.raw(key), `patchLint.${key}`);
-        if (gate !== undefined)
-            out[key] = gate;
-    }
-    if (out.checkJsStrict === true && out.checkJs !== true) {
-        throw new ConfigError('Config field "patchLint.checkJsStrict" requires "patchLint.checkJs": true');
-    }
-    if (out.checkJsCompilerOptions !== undefined && out.checkJsStrict !== true) {
-        throw new ConfigError('Config field "patchLint.checkJsCompilerOptions" requires "patchLint.checkJsStrict": true');
-    }
-    if (out.checkJsTestFiles === true && out.checkJs !== true) {
-        throw new ConfigError('Config field "patchLint.checkJsTestFiles" requires "patchLint.checkJs": true');
-    }
-    if (out.checkJsTestShim !== undefined && out.checkJsTestFiles !== true) {
-        throw new ConfigError('Config field "patchLint.checkJsTestShim" requires "patchLint.checkJsTestFiles": true');
-    }
-    return out;
-}
-/**
- * Validates a path field that should point at a project-relative `.d.ts`
- * file. Shared between `patchLint.checkJsExtraShim` and
- * `typecheck.extraShim` so both fields reject the same absolute-path /
- * traversal / empty-string inputs with consistent error messages. The
- * file's existence is not checked here. That lives at the engine layer,
- * where a missing file produces a typed runtime error pointing at the
- * actual command, rather than blocking config reads for unrelated commands.
- */
-function parseShimPath(raw, label) {
-    if (typeof raw !== 'string' || raw.trim() === '') {
-        throw new ConfigError(`Config field "${label}" must be a non-empty string`);
-    }
-    if (!isContainedRelativePath(raw)) {
-        throw new ConfigError(`Config field "${label}" must be a project-relative path`);
-    }
-    return raw;
-}
-/**
- * Validates the optional top-level `typecheck` block. Empty `projects`
- * is rejected because a silent no-op for `fireforge typecheck` is a
- * footgun, since operators set the block expecting it to do something. Each
- * project path must be a contained relative path so `--project` / CLI
- * scripts can't escape the project root.
- */
-function parseTypecheckBlock(rec) {
-    const projectsRaw = rec.raw('projects');
-    if (projectsRaw === undefined) {
-        throw new ConfigError('Config field "typecheck.projects" is required when "typecheck" is set');
-    }
-    if (!Array.isArray(projectsRaw)) {
-        throw new ConfigError('Config field "typecheck.projects" must be an array of strings');
-    }
-    if (projectsRaw.length === 0) {
-        throw new ConfigError('Config field "typecheck.projects" must not be empty');
-    }
-    const projects = [];
-    for (let i = 0; i < projectsRaw.length; i++) {
-        const entry = projectsRaw[i];
-        if (typeof entry !== 'string' || entry.trim() === '') {
-            throw new ConfigError(`Config field "typecheck.projects[${i}]" must be a non-empty string`);
-        }
-        if (!isContainedRelativePath(entry)) {
-            throw new ConfigError(`Config field "typecheck.projects[${i}]" must be a project-relative path`);
-        }
-        projects.push(entry);
-    }
-    const out = { projects };
-    const extraShim = rec.raw('extraShim');
-    if (extraShim !== undefined) {
-        out.extraShim = parseShimPath(extraShim, 'typecheck.extraShim');
-    }
-    const overrides = parseTypecheckProjectOverrides(rec.raw('projectOverrides'), projects);
-    if (overrides) {
-        out.projectOverrides = overrides;
-    }
-    const undefinedIdentifiers = parseSeverityGate(rec.raw('undefinedIdentifiers'), 'typecheck.undefinedIdentifiers');
-    if (undefinedIdentifiers !== undefined) {
-        out.undefinedIdentifiers = undefinedIdentifiers;
-    }
-    const litTypes = rec.raw('litTypes');
-    if (litTypes !== undefined && typeof litTypes !== 'boolean') {
-        throw new ConfigError('Config field "typecheck.litTypes" must be a boolean');
-    }
-    if (litTypes !== undefined)
-        out.litTypes = litTypes;
-    return out;
-}
-/**
- * Validates the optional `typecheck.projectOverrides` map: keys must name a
- * declared project, values must be either `null` (opt out of the shared extra
- * shim) or a contained relative `.d.ts` path (per-project override). Returns
- * `undefined` when the field is absent.
- */
-function parseTypecheckProjectOverrides(raw, projects) {
-    if (raw === undefined)
-        return undefined;
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        throw new ConfigError('Config field "typecheck.projectOverrides" must be an object');
-    }
-    const known = new Set(projects);
-    const out = {};
-    for (const [key, value] of Object.entries(raw)) {
-        if (!known.has(key)) {
-            throw new ConfigError(`Config field "typecheck.projectOverrides" key "${key}" does not match any entry in "typecheck.projects"`);
-        }
-        out[key] = value === null ? null : parseShimPath(value, `typecheck.projectOverrides["${key}"]`);
-    }
-    return out;
-}

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

@@ -1,92 +0,0 @@
-/**
- * Project configuration barrel module.
- *
- * Re-exports from focused sub-modules:
- *   config-paths.ts:    constants and project path derivation
- *   config-validate.ts: fireforge.json schema validation
- *   config-mutate.ts:   immutable config mutation
- *   config-state.ts:    state file management
- */
-import type { FireForgeConfig } from '../types/config.js';
-import type { JsonObject } from '../types/json.js';
-export { mutateConfig } from './config-mutate.js';
-export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, updateState } from './config-state.js';
-export { validateConfig } from './config-validate.js';
-/**
- * Checks if a fireforge.json exists in the given directory.
- * @param root - Root directory to check
- * @returns True if fireforge.json exists
- */
-export declare function configExists(root: string): Promise<boolean>;
-/**
- * Loads and validates the fireforge.json configuration.
- * @param root - Root directory of the project
- * @returns Validated FireForgeConfig
- * @throws Error if config doesn't exist or is invalid
- */
-export declare function loadConfig(root: string): Promise<FireForgeConfig>;
-/**
- * Reads the raw `fireforge.json` document without running it through
- * {@link validateConfig}. Returns every persisted key, including keys
- * written via `fireforge config <key> --force` that `validateConfig`
- * would strip from the typed result.
- *
- * Callers that need the validated, typed shape must still use
- * {@link loadConfig}. This helper exists specifically for the `config`
- * read path so `fireforge config <key>` can surface keys the write path
- * accepted under `--force`.
- *
- * @param root - Root directory of the project
- * @returns Raw config object as persisted on disk
- * @throws ConfigNotFoundError when fireforge.json is missing
- * @throws ConfigError when the file is not valid JSON
- */
-export declare function loadRawConfigDocument(root: string): Promise<JsonObject>;
-/**
- * Writes a configuration to fireforge.json.
- * @param root - Root directory of the project
- * @param config - Configuration to write
- */
-export declare function writeConfig(root: string, config: FireForgeConfig): Promise<void>;
-/**
- * Writes a raw config document to fireforge.json.
- * This is used by CLI `config --force`, where callers may intentionally write
- * keys or value shapes outside the validated FireForgeConfig schema.
- *
- * An existing file is edited in place: only the values that differ from the
- * document on disk are rewritten, so a one-key change keeps the file's
- * formatting (compact objects and arrays, indentation, key order) and stays
- * a one-hunk diff. A missing or unparseable file is written in full.
- *
- * Individual writes are atomic via {@link writeJson} (temp file + rename),
- * but atomicity alone does not prevent lost updates across concurrent
- * writers: each writer reads an old copy, mutates its own in-memory view,
- * and writes it back, so the second writer's rename clobbers the first
- * writer's changes. Callers that do read → mutate → write must hold
- * {@link withConfigFileLock} for the full round-trip to serialise
- * against other writers.
- */
-export declare function writeConfigDocument(root: string, config: FireForgeConfig | JsonObject): Promise<void>;
-/**
- * Runs an operation while holding a sidecar lock on `fireforge.json`.
- *
- * Two concurrent `fireforge config <key> <value>` invocations each run
- * load → mutate → writeJson against the same document. Without this lock
- * the second rename lands after the first and silently drops the first
- * writer's key, with both commands exiting 0.
- *
- * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
- * always use `writeJson`'s atomic temp-file + rename, so a reader observes
- * either the pre- or post-write document but never a torn file. The lock
- * only serialises writers against other writers.
- *
- * The lock is a sidecar directory `${config}.fireforge-config.lock`, and
- * `withFileLock` handles stale-lock recovery (PID-alive probe, age-based
- * fallback), so a crashed writer does not permanently block future writes.
- *
- * @param root - Root directory of the project
- * @param operation - Async function to run while holding the lock
- * @returns Whatever the operation returns
- */
-export declare function withConfigFileLock<T>(root: string, operation: () => Promise<T>): Promise<T>;