@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/core/patch-manifest-io.d.ts

@@ -1,199 +0,0 @@
-/**
- * Manifest I/O: load, save, and mutating operations for patches.json.
- *
- * Mutations (add / remove / renumber) are intended to be the only sanctioned
- * way to change on-disk manifest state. They run under the shared patch
- * directory lock so concurrent commands cannot race each other into
- * inconsistent manifests.
- */
-import { FireForgeError } from '../errors/base.js';
-import type { PatchesManifest, PatchMetadata, PatchRetiredSlot } from '../types/commands/index.js';
-import type { JsonObject } from '../types/json.js';
-/** Filename for the patches manifest */
-export declare const PATCHES_MANIFEST = "patches.json";
-/** Internal state returned by loadPatchesManifestState. */
-export interface LoadedManifestState {
-    exists: boolean;
-    manifest: PatchesManifest | null;
-    parseError: Error | undefined;
-}
-/** Field-level mutation returned by a row-scoped manifest mutator. */
-export interface PatchManifestRowMutation {
-    /** Metadata fields to set on the selected manifest row. */
-    set?: Partial<PatchMetadata>;
-    /** Metadata fields to delete from the selected manifest row. */
-    unset?: ReadonlyArray<string>;
-}
-/** Result for one manifest row changed by {@link mutatePatchRowsInManifest}. */
-export interface PatchManifestRowMutationResult {
-    /** Validated row before the mutation. */
-    before: PatchMetadata;
-    /** Validated row after the mutation. */
-    after: PatchMetadata;
-}
-/**
- * Loads and validates the patches manifest, returning full state information.
- * @param patchesDir - Path to the patches directory
- */
-export declare function loadPatchesManifestState(patchesDir: string): Promise<LoadedManifestState>;
-/**
- * Loads the patches manifest if it exists.
- *
- * Read-only callers only: this collapses "absent" and "corrupt" into null.
- * Any code path that writes the manifest (or deletes patch files based
- * on its content) must use {@link loadPatchesManifestForWrite} instead.
- * Treating a corrupt manifest as empty and then saving destroys every
- * existing patch's metadata.
- *
- * @param patchesDir - Path to the patches directory
- * @returns PatchesManifest or null if not found
- */
-export declare function loadPatchesManifest(patchesDir: string): Promise<PatchesManifest | null>;
-/**
- * Loads the patches manifest for a mutating operation.
- *
- * Returns null only when the manifest genuinely does not exist. A manifest
- * that exists but fails to parse/validate throws
- * {@link PatchManifestCorruptError} so the caller aborts instead of
- * rebuilding an empty queue over the top of the corrupt file.
- */
-export declare function loadPatchesManifestForWrite(patchesDir: string): Promise<PatchesManifest | null>;
-/**
- * Saves the patches manifest.
- * @param patchesDir - Path to the patches directory
- * @param manifest - Manifest to save
- */
-export declare function savePatchesManifest(patchesDir: string, manifest: PatchesManifest): Promise<void>;
-/**
- * Mutates selected manifest rows while preserving the raw JSON fields of every
- * untouched row. This avoids serializing reader-only fallback fields, such as
- * `sourceVersion` derived from legacy `sourceEsrVersion`, into unrelated patch
- * entries during partial metadata updates.
- *
- * Every row's keys (and the manifest's own) are written in canonical order,
- * not only the changed rows', so the working copy matches what `patch stage`
- * and full saves write and no commit flips untouched rows' key order.
- */
-export declare function mutatePatchRowsInManifest(patchesDir: string, filenames: readonly string[], mutator: (existing: PatchMetadata, rawExisting: Readonly<JsonObject>) => PatchManifestRowMutation | null): Promise<PatchManifestRowMutationResult[] | null>;
-/**
- * Adds or updates a patch entry in the manifest.
- * @param patchesDir - Path to the patches directory
- * @param metadata - Patch metadata to add/update
- * @param removeFilenames - Optional filenames to remove in the same read-modify-write cycle
- */
-export declare function addPatchToManifest(patchesDir: string, metadata: PatchMetadata, removeFilenames?: string[]): Promise<void>;
-/**
- * Removes a single patch entry from the manifest by filename. Leaves the
- * ordinal gap in place. Callers wanting to close the gap must use
- * {@link renumberPatchesInManifest} explicitly. This matches the spec: delete
- * is a row removal, not a resequencing.
- *
- * Not atomic with any on-disk patch file deletion. Callers are expected to
- * remove the .patch file separately under the same lock.
- *
- * @param patchesDir - Path to the patches directory
- * @param filename - Filename of the patch to remove from the manifest
- * @param retiredSlot - Optional placeholder to record for the removed order
- * @returns True when the manifest was written (i.e. an entry was removed),
- *   false when no matching entry existed
- */
-export declare function removePatchFromManifest(patchesDir: string, filename: string, retiredSlot?: PatchRetiredSlot): Promise<boolean>;
-/**
- * A single rename step in a {@link renumberPatchesInManifest} plan.
- */
-export interface PatchRenameEntry {
-    /** New filename (e.g. `005-ui-sidebar.patch`). */
-    newFilename: string;
-    /** New numeric order. Must match the prefix of `newFilename`. */
-    newOrder: number;
-}
-/**
- * Rewrites `stagedDependencies.forwardImports[].owner` and
- * `stagedDependencies.registrations[].owner` references on one patch
- * through a rename lookup. Owners embed exact patch filenames, so any
- * renumber (compact, reorder, placement export, rename) that does not remap
- * them leaves dangling references that surface as false forward-import
- * errors on the next lint.
- *
- * Pure and allocation-conservative: returns the input object unchanged when
- * no owner matches the lookup, so callers can map whole manifests cheaply.
- *
- * @param patch - Manifest row to rewrite
- * @param renameLookup - Maps an old patch filename to its new filename, or
- *   undefined when the filename is not being renamed
- * @returns The same row, or a copy with remapped owners
- */
-export declare function rewriteStagedDependencyOwners(patch: PatchMetadata, renameLookup: (oldFilename: string) => string | undefined): PatchMetadata;
-/**
- * Renames patch files on disk and rewrites the corresponding manifest rows
- * atomically-ish: file renames use a two-phase staging strategy (rename each
- * entry to a unique temp filename first, then rename the temp to its final
- * target) so cycles like `003 → 005` while `005` also moves do not collide.
- *
- * The manifest is rewritten once at the end with all new filenames and
- * orders. Failure semantics:
- *
- *   - **Phase 1 (stage)**: rolls back by renaming staged files back to
- *     their originals. Manifest is untouched. Best-effort: a rollback
- *     rename failure is warned but not re-thrown.
- *   - **Phase 2 (stage → final)**: rolls back to the pre-operation state
- *     by reversing every partial step: files already at their final
- *     names are renamed back to staging, and all staged files are then
- *     renamed back to their originals. The manifest is untouched. If
- *     the rollback itself fails midway, the thrown error is augmented
- *     with a description of the residue so the operator can inspect.
- *   - **Phase 3 (manifest write)**: by this point all files are on disk
- *     at their new names. A manifest write failure will roll the files
- *     back to their original names before re-throwing so the directory
- *     and manifest stay in agreement. A rollback failure at this stage
- *     is warned (manifest was never mutated) and the original error is
- *     re-thrown.
- *
- * Does not sort the rename map for the caller. The map is the authoritative
- * plan. Entries not present in the map keep their existing filename and
- * order.
- *
- * @param patchesDir - Path to the patches directory
- * @param renameMap - Map from existing filename → new filename/order
- */
-export declare function renumberPatchesInManifest(patchesDir: string, renameMap: Map<string, PatchRenameEntry>): Promise<void>;
-/**
- * Thrown when {@link removePatchFileAndManifest} cannot complete the file
- * delete and cannot restore the manifest row afterward, so the on-disk
- * state and manifest state are known to disagree. Carries both the
- * primary delete error and the rollback error so the caller (and the
- * operator) can see the full failure chain instead of only the original
- * error with a warning about the rollback buried in logs.
- *
- * Extends {@link FireForgeError} so the CLI top-level handler routes it
- * through the rich-error formatter rather than the generic unexpected-error
- * path. The dedicated `.name` is kept so programmatic callers and tests
- * can still distinguish it with `instanceof PatchDeleteRollbackError`.
- */
-export declare class PatchDeleteRollbackError extends FireForgeError {
-    readonly filename: string;
-    readonly deleteError: Error;
-    readonly rollbackError: Error;
-    readonly code: 6;
-    constructor(filename: string, deleteError: Error, rollbackError: Error);
-}
-/**
- * Deletes both a patch file on disk and its manifest row under the caller's
- * lock. This is a convenience for the `patch delete` command. Callers that
- * need different ordering (e.g. deleting the file first without touching the
- * manifest) should call the primitives separately.
- *
- * Failure semantics: if the manifest row was already removed and the
- * file deletion then fails, the original manifest is restored best-effort
- * and the delete error is re-thrown. If the restore itself also fails,
- * a {@link PatchDeleteRollbackError} is thrown that carries both the
- * delete error and the rollback error so neither is hidden behind a
- * warning log. Callers can detect the compound failure with
- * `instanceof PatchDeleteRollbackError`.
- *
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename to delete
- * @param retiredSlot - When set (`patch retire`), the placeholder written in
- *   the same manifest update that removes the row
- */
-export declare function removePatchFileAndManifest(patchesDir: string, filename: string, retiredSlot?: PatchRetiredSlot): Promise<void>;