@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/patch-export-metadata.d.ts

@@ -1,46 +0,0 @@
-/**
- * Manifest metadata mutation helpers for patch export commands.
- */
-import type { PatchMetadata } from '../types/commands/index.js';
-import type { PatchDirectoryLockOptions } from './patch-lock.js';
-/**
- * Optional `PatchMetadata` keys safe to clear via the helpers below.
- */
-export type ClearablePatchMetadataField = 'tier' | 'lintIgnore' | 'stagedDependencies';
-/**
- * Updates metadata for a patch in the manifest.
- *
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename
- * @param updates - Field values to set
- * @param unsetFields - Optional fields to remove from the entry
- * @param lockOptions - `--wait-lock` budget and the command name recorded in
- *   the lock's owner metadata. Threaded from the CLI so a caller that waits
- *   is not silently given the default 30s budget.
- */
-export declare function updatePatchMetadata(patchesDir: string, filename: string, updates: Partial<PatchMetadata>, unsetFields?: ReadonlyArray<ClearablePatchMetadataField>, lockOptions?: PatchDirectoryLockOptions): Promise<void>;
-/** Return shape from a `mutatePatchMetadata` mutator. */
-export interface PatchMetadataMutation {
-    /** Field values to set on the entry. */
-    set?: Partial<PatchMetadata>;
-    /** Optional fields to remove from the entry entirely. */
-    unset?: ReadonlyArray<ClearablePatchMetadataField>;
-}
-/** Result of a successful `mutatePatchMetadata` call. */
-export interface PatchMetadataMutationResult {
-    /** Pre-mutation snapshot of the patch's metadata. */
-    before: PatchMetadata;
-    /** Post-mutation state of the patch's metadata. */
-    after: PatchMetadata;
-}
-/**
- * Reads a patch's metadata under the directory lock, applies a mutator
- * function to compute the update, and writes the result back.
- *
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename
- * @param mutator - Computes the update from the existing metadata
- * @param lockOptions - `--wait-lock` budget and owner-metadata command name
- * @returns Before/after metadata, or null when the patch was not found
- */
-export declare function mutatePatchMetadata(patchesDir: string, filename: string, mutator: (existing: PatchMetadata) => PatchMetadataMutation, lockOptions?: PatchDirectoryLockOptions): Promise<PatchMetadataMutationResult | null>;

package/dist/src/core/patch-export-metadata.js

@@ -1,47 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Manifest metadata mutation helpers for patch export commands.
- */
-import { withPatchDirectoryLock } from './patch-apply.js';
-import { mutatePatchRowsInManifest } from './patch-manifest.js';
-/**
- * Updates metadata for a patch in the manifest.
- *
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename
- * @param updates - Field values to set
- * @param unsetFields - Optional fields to remove from the entry
- * @param lockOptions - `--wait-lock` budget and the command name recorded in
- *   the lock's owner metadata. Threaded from the CLI so a caller that waits
- *   is not silently given the default 30s budget.
- */
-export async function updatePatchMetadata(patchesDir, filename, updates, unsetFields = [], lockOptions = {}) {
-    await withPatchDirectoryLock(patchesDir, async () => {
-        await mutatePatchRowsInManifest(patchesDir, [filename], () => ({
-            set: updates,
-            unset: unsetFields,
-        }));
-    }, lockOptions);
-}
-/**
- * Reads a patch's metadata under the directory lock, applies a mutator
- * function to compute the update, and writes the result back.
- *
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename
- * @param mutator - Computes the update from the existing metadata
- * @param lockOptions - `--wait-lock` budget and owner-metadata command name
- * @returns Before/after metadata, or null when the patch was not found
- */
-export async function mutatePatchMetadata(patchesDir, filename, mutator, lockOptions = {}) {
-    return await withPatchDirectoryLock(patchesDir, async () => {
-        const result = await mutatePatchRowsInManifest(patchesDir, [filename], (existing) => {
-            const { set = {}, unset = [] } = mutator(existing);
-            return { set, unset };
-        });
-        const changed = result?.[0];
-        if (!changed)
-            return null;
-        return { before: changed.before, after: changed.after };
-    }, lockOptions);
-}

package/dist/src/core/patch-export-update.d.ts

@@ -1,55 +0,0 @@
-import type { PatchMetadata } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
-import type { PatchDirectoryLockOptions } from './patch-lock.js';
-/**
- * Optional post-commit hook for {@link updatePatchAndMetadata}. Runs inside
- * the patch directory lock after the mutation has succeeded but before the
- * lock is released.
- */
-export type UpdatePatchCommittedHook = () => Promise<void>;
-/** Optional policy gate run against the under-lock projected manifest. */
-export interface UpdatePatchPolicyGate {
-    config: FireForgeConfig;
-    command: string;
-    forceUnsafe?: boolean;
-    /** Restricts enforcement to these rows' findings (see `enforcePatchPolicy`). */
-    scope?: readonly string[];
-}
-export interface UpdatePatchAndMetadataOptions {
-    /** Patch directory holding the body and `patches.json`. */
-    patchesDir: string;
-    /** Patch file to rewrite. */
-    filename: string;
-    /** New patch body. An identical body skips the write. */
-    newContent: string;
-    /** Manifest-row fields to merge into the patch's metadata. */
-    updates: Partial<PatchMetadata>;
-    /** Manifest-row fields to delete, e.g. a staged block left empty. */
-    unset?: readonly (keyof PatchMetadata)[] | undefined;
-    /** Hook run under the lock after the mutation succeeds. */
-    onCommitted?: UpdatePatchCommittedHook | undefined;
-    /** Policy gate run against the under-lock projected manifest. */
-    policyGate?: UpdatePatchPolicyGate | undefined;
-    /** Wait budget and command name for the patch directory lock. */
-    lockOptions?: PatchDirectoryLockOptions | undefined;
-}
-/**
- * Updates a patch file body and its manifest row under the same patch
- * directory lock. Intended for commands like `re-export --files` where the
- * file body and `filesAffected` metadata must move together.
- *
- * The body write is skipped when the normalized new content is byte-identical
- * to what is already on disk. A bulk `re-export --all` refreshes every patch
- * in the queue, including ones the working tree never touched. Rewriting an
- * unchanged body churns its mtime and reports "Re-exported" for a patch
- * nothing happened to, which is exactly the noise that hides a real
- * unexpected rewrite in `git status`. Metadata still moves either way, and
- * only the redundant byte-for-byte write is elided.
- *
- * @param options - See {@link UpdatePatchAndMetadataOptions}
- * @returns True when the patch body on disk changed, false when it was
- *   already byte-identical to the new content.
- */
-export declare function updatePatchAndMetadata(options: UpdatePatchAndMetadataOptions): Promise<boolean>;
-/** A copy of `row` without `fields`. */
-export declare function withoutFields(row: PatchMetadata, fields: readonly (keyof PatchMetadata)[]): PatchMetadata;

package/dist/src/core/patch-export-update.js

@@ -1,95 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { PatchError } from '../errors/patch.js';
-import { toError } from '../utils/errors.js';
-import { pathExists, readText, writeText } from '../utils/fs.js';
-import { warn } from '../utils/logger.js';
-import { withPatchDirectoryLock } from './patch-apply.js';
-import { loadPatchesManifestForWrite, mutatePatchRowsInManifest } from './patch-manifest.js';
-import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
-/**
- * Updates a patch file body and its manifest row under the same patch
- * directory lock. Intended for commands like `re-export --files` where the
- * file body and `filesAffected` metadata must move together.
- *
- * The body write is skipped when the normalized new content is byte-identical
- * to what is already on disk. A bulk `re-export --all` refreshes every patch
- * in the queue, including ones the working tree never touched. Rewriting an
- * unchanged body churns its mtime and reports "Re-exported" for a patch
- * nothing happened to, which is exactly the noise that hides a real
- * unexpected rewrite in `git status`. Metadata still moves either way, and
- * only the redundant byte-for-byte write is elided.
- *
- * @param options - See {@link UpdatePatchAndMetadataOptions}
- * @returns True when the patch body on disk changed, false when it was
- *   already byte-identical to the new content.
- */
-export async function updatePatchAndMetadata(options) {
-    const { patchesDir, filename, newContent, updates, unset = [], onCommitted, policyGate, lockOptions = {}, } = options;
-    return withPatchDirectoryLock(patchesDir, async () => {
-        const manifest = await loadPatchesManifestForWrite(patchesDir);
-        if (!manifest) {
-            throw new PatchError('Cannot update patch metadata: patches.json is missing.', filename);
-        }
-        const patchIndex = manifest.patches.findIndex((p) => p.filename === filename);
-        if (patchIndex === -1) {
-            throw new PatchError(`Cannot update patch metadata: ${filename} not found in patches.json.`, filename);
-        }
-        const patchPath = join(patchesDir, filename);
-        if (!(await pathExists(patchPath))) {
-            throw new PatchError(`Cannot update patch: patch file is missing on disk: ${filename}`, filename);
-        }
-        const originalContent = await readText(patchPath);
-        const existingPatch = manifest.patches[patchIndex];
-        manifest.patches[patchIndex] = withoutFields({ ...existingPatch, ...updates }, unset);
-        if (policyGate !== undefined) {
-            enforcePatchPolicy({
-                config: policyGate.config,
-                manifest: buildProjectedManifest(manifest, manifest.patches),
-                command: policyGate.command,
-                forceUnsafe: policyGate.forceUnsafe === true,
-                ...(policyGate.scope !== undefined ? { scope: policyGate.scope } : {}),
-            });
-        }
-        const normalized = newContent;
-        const bodyChanged = normalized !== originalContent;
-        let patchWritten = false;
-        try {
-            if (bodyChanged) {
-                await writeText(patchPath, normalized);
-                patchWritten = true;
-            }
-            await mutatePatchRowsInManifest(patchesDir, [filename], () => ({ set: updates, unset }));
-        }
-        catch (error) {
-            if (patchWritten) {
-                try {
-                    await writeText(patchPath, originalContent);
-                }
-                catch (rollbackError) {
-                    warn(`Rollback warning: could not restore ${filename} after metadata write failed: ${toError(rollbackError).message}`);
-                }
-            }
-            throw error;
-        }
-        if (onCommitted) {
-            try {
-                await onCommitted();
-            }
-            catch (hookError) {
-                warn(`History log append failed after updatePatchAndMetadata committed (${filename}): ` +
-                    toError(hookError).message);
-            }
-        }
-        return bodyChanged;
-    }, lockOptions);
-}
-/** A copy of `row` without `fields`. */
-export function withoutFields(row, fields) {
-    if (fields.length === 0)
-        return row;
-    const copy = { ...row };
-    for (const field of fields)
-        Reflect.deleteProperty(copy, field);
-    return copy;
-}

package/dist/src/core/patch-export.d.ts

@@ -1,175 +0,0 @@
-import type { PatchCategory, PatchesManifest, PatchInfo, PatchMetadata } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
-import { type SupersedeCoverageDetail } from './patch-export-coverage.js';
-import type { PatchDirectoryLockOptions } from './patch-lock.js';
-export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
-export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadata.js';
-export { updatePatchAndMetadata } from './patch-export-update.js';
-/**
- * Projects the planning subset out of a wider export input (commit input,
- * dry-run preview input): the fields `planExport` /
- * `computeExportPlanUnderLock` read. Optional fields are copied only when
- * present so the plan input never carries explicit `undefined` keys, which
- * would otherwise leak into the written metadata via spread. The commit
- * path and the dry-run preview both go through this one projection so
- * they cannot drift field by field.
- */
-export declare function buildPlanExportInput(input: PlanExportInput): PlanExportInput;
-/**
- * Gets the next patch number for a new patch.
- * @param patchesDir - Path to the patches directory
- * @param reserved - Orders held by `patch reserve`, skipped
- * @returns Next patch number (e.g., "005" for 4 existing patches)
- */
-export declare function getNextPatchNumber(patchesDir: string, reserved?: ReadonlySet<number>): Promise<string>;
-/**
- * Sanitizes a human-readable name into a filename slug.
- *
- * Exported so `patch rename` can produce a filename slug from its
- * `--to <new-name>` argument using the exact same convention `export`
- * uses, without duplicating the lowercase + non-alnum collapse + length
- * cap rules. Drift between the two would let an operator rename a patch
- * to a slug `export` could never reach.
- */
-export declare function sanitizeName(name: string): string;
-/**
- * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
- * Operators frequently pass the desired filename stem to `--name`
- * (`--name 203-ui-foo --category ui`), which would otherwise double-prefix
- * into `203-ui-203-ui-foo.patch`. The filename builders prepend the order
- * and category themselves, so a matching prefix in the name is always
- * redundant. Applied repeatedly so a twice-prefixed slug also collapses.
- * Exported for direct testing.
- */
-export declare function stripRedundantCategoryPrefix(sanitizedName: string, category: string): string;
-/**
- * Sanitizes a patch name and drops redundant category/full-stem prefixes.
- *
- * A single trailing `.patch` extension is stripped before sanitisation:
- * operators frequently pass a full patch filename where a name is expected
- * (`move-files <from> 348-ui-foo.patch --create`, `rename --to foo.patch`),
- * and slugging the extension produces double-suffixed `...-patch.patch`
- * files. A name that deliberately ends in a literal `-patch` slug segment
- * must be written without the dot form.
- */
-export declare function patchNameSlug(name: string, category: string): string;
-/**
- * Generates the next patch filename with category.
- * @param patchesDir - Path to the patches directory
- * @param category - Patch category
- * @param name - Human-readable name
- * @returns Filename like "001-ui-sidebar.patch"
- */
-export declare function getNextPatchFilename(patchesDir: string, category: PatchCategory, name: string, reserved?: ReadonlySet<number>): Promise<string>;
-export interface CommitExportedPatchInput {
-    patchesDir: string;
-    category: PatchCategory;
-    name: string;
-    description: string;
-    diff: string;
-    filesAffected: string[];
-    sourceEsrVersion: string;
-    sourceProduct?: FireForgeConfig['firefox']['product'];
-    sourceVersion?: string;
-    /** Optional `PatchMetadata.tier` opt-in (only `"branding"` recognised). */
-    tier?: 'branding';
-    /** Optional `PatchMetadata.lintIgnore` (empty array treated as absent). */
-    lintIgnore?: string[];
-    /** Project config, used only when opt-in patchPolicy is present. */
-    config?: FireForgeConfig;
-    /** Mutating command name for policy errors. */
-    policyCommand?: string;
-    /** Whether --force-unsafe was supplied by the mutating command. */
-    forceUnsafe?: boolean;
-    /**
-     * `--wait-lock` budget and the command name recorded in the lock's owner
-     * metadata. Threaded from the CLI so a caller that asked to wait is not
-     * silently given the default budget.
-     */
-    lockOptions?: PatchDirectoryLockOptions;
-}
-export interface CommitExportedPatchResult {
-    patchFilename: string;
-    metadata: PatchMetadata;
-    superseded: PatchInfo[];
-}
-/**
- * Commits a freshly generated patch file and manifest update under an
- * exclusive patch directory lock so concurrent exports cannot allocate the
- * same number. Shares {@link computeExportPlanUnderLock} with
- * {@link planExport} so the dry-run preview cannot drift from the real
- * write: both paths go through the same planning helper, and any bug fix
- * to filename allocation or supersede detection lands in both automatically.
- */
-export declare function commitExportedPatch(input: CommitExportedPatchInput): Promise<CommitExportedPatchResult>;
-/**
- * Updates the content of a patch file.
- * @param patchPath - Path to the patch file
- * @param newContent - New patch content
- */
-export declare function updatePatch(patchPath: string, newContent: string): Promise<void>;
-/**
- * Fully computed plan for a pending export. Returned from
- * {@link planExport} so that `--dry-run` previews can render the full
- * outcome of the hypothetical write without touching disk.
- *
- * Dry-run and the real write both go through {@link computeExportPlanUnderLock}
- * so their filename allocation, supersede detection, and projected
- * post-write manifest cannot drift. `planExport` exposes the rich coverage
- * form for preview rendering. {@link commitExportedPatch} consumes the bare
- * `PatchInfo[]` form of the same underlying data.
- */
-export interface ExportPlan {
-    /** Allocated patch filename (e.g. `005-ui-sidebar.patch`). */
-    patchFilename: string;
-    /** Full metadata row that would be written to the manifest. */
-    metadata: PatchMetadata;
-    /** Existing patches that would be superseded by this export. */
-    superseded: SupersedeCoverageDetail[];
-    /** Manifest state as it existed when the plan was computed. */
-    manifestBefore: PatchesManifest | null;
-    /**
-     * Manifest state the plan would write. Always includes the new patch
-     * metadata and excludes any superseded filenames.
-     */
-    manifestAfter: PatchesManifest;
-}
-export interface PlanExportInput {
-    patchesDir: string;
-    category: PatchCategory;
-    name: string;
-    description: string;
-    filesAffected: string[];
-    sourceEsrVersion: string;
-    sourceProduct?: FireForgeConfig['firefox']['product'];
-    sourceVersion?: string;
-    /**
-     * Optional `PatchMetadata.tier` opt-in carried from the CLI flag.
-     * Only `"branding"` is currently recognised. When provided the field
-     * is written into the new patch's metadata. When absent the field
-     * stays unset and tier resolution falls back to auto-detection.
-     */
-    tier?: 'branding';
-    /**
-     * Optional `PatchMetadata.lintIgnore` carried from the CLI flag.
-     * Empty arrays are treated as "field absent": the validator only
-     * preserves the field when it has at least one entry.
-     */
-    lintIgnore?: string[];
-    /** Project config, used only when opt-in patchPolicy is present. */
-    config?: FireForgeConfig;
-}
-/**
- * Read-only planning function. Computes everything a real export would
- * do without writing anything to disk. Takes the patch directory lock
- * briefly, runs {@link computeExportPlanUnderLock}, releases the lock,
- * and returns the plan for preview rendering.
- *
- * Shares {@link computeExportPlanUnderLock} with {@link commitExportedPatch}
- * so the dry-run preview cannot drift from the real write. The real write
- * path does not reuse a prior plan object (another export may have landed
- * between dry-run and commit, which would stale the filename allocation).
- * It re-runs the same helper under a fresh lock. The guarantee is "same
- * code, possibly different data," not "same plan object."
- */
-export declare function planExport(input: PlanExportInput): Promise<ExportPlan>;