@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/cli/gate/snapshot.d.ts

@@ -1,37 +1,69 @@
 export declare const SNAPSHOT_BASENAME_PREFIX = "harness.gate-disable.";
 export declare const SNAPSHOT_BASENAME_SUFFIX = ".json";
-export declare const SNAPSHOT_VERSION: 1;
+/** Written by this version. Adds `step` on every removed group and `merges`. */
+export declare const SNAPSHOT_VERSION: 2;
+/** Written by releases before a second disable merged into the live snapshot; still restorable. */
+export declare const LEGACY_SNAPSHOT_VERSION: 1;
+/** A retired snapshot keeps its name with this suffix instead of plain `.json`. */
+export declare const RETIRED_SNAPSHOT_SUFFIX = ".restored.json";
+/** A snapshot whose groups were carried into a snapshot at another place keeps its name with this suffix. */
+export declare const SUPERSEDED_SNAPSHOT_SUFFIX = ".superseded.json";
 export interface RemovedGroup {
     /** Hook event the group lived under, e.g. "PreToolUse". */
     event: string;
-    /** Position of the group inside `hooks[event][]` at the time of removal. */
+    /**
+     * Position of the group inside `hooks[event][]` just before the removal
+     * step that took it out (a later merged disable records positions in the
+     * already-reduced array). Restore therefore undoes the steps newest first.
+     */
     index: number;
+    /** Which disable call removed it: 0 for the first, 1 for the next merged one, and so on. Absent in version 1 snapshots (read as 0). */
+    step?: number;
     /** The literal JSON value of the removed group; preserved verbatim. */
     group: unknown;
 }
+/** A later `gate disable` that was merged into a live snapshot. */
+export interface SnapshotMerge {
+    step: number;
+    createdAt: string;
+    matcher: string;
+    settingsBackupPath: string;
+}
 export interface GateDisableSnapshot {
-    version: typeof SNAPSHOT_VERSION;
+    version: typeof SNAPSHOT_VERSION | typeof LEGACY_SNAPSHOT_VERSION;
     /** ISO-8601 UTC timestamp of the disable call. */
     createdAt: string;
-    /** Absolute path to the settings.json that was mutated. */
+    /**
+     * Absolute path to the settings.json that was mutated (snapshots written
+     * by earlier releases may hold the path as it was typed, relative to a
+     * working directory that is gone). Only its basename is used to tell which
+     * file a snapshot belongs to (snapshots always sit beside their file): the
+     * target must name that directory entry, see `listLiveSnapshots`.
+     */
     settingsPath: string;
     /** Absolute path the pre-mutation copy was written to. */
     settingsBackupPath: string;
     /**
-     * SHA-256 of `settings.json` content BEFORE the removal. `gate enable`
-     * compares the live settings.json sha against this to detect operator
-     * edits since the disable; a mismatch refuses unless `--force`.
+     * SHA-256 of `settings.json` content BEFORE the first removal. When the
+     * live file already has this sha there is nothing to restore (the snapshot
+     * is retired).
      */
     settingsBeforeSha256: string;
-    /** SHA-256 of `settings.json` content AFTER the removal. */
+    /**
+     * SHA-256 of `settings.json` content AFTER the latest removal. `gate
+     * enable` compares the live settings.json sha against this to detect
+     * operator edits since the disable; a mismatch refuses unless `--force`.
+     */
     settingsAfterSha256: string;
-    /** The filter the operator applied — recorded for the audit trail. */
+    /** The filter of the first disable, recorded for the audit trail. */
     filter: {
         matcher?: string;
         event?: string;
     };
-    /** Groups removed, in stable order (sorted by event then ascending index). */
+    /** Groups removed by every step, in the order they were taken out. */
     removed: RemovedGroup[];
+    /** Later disables merged into this snapshot, oldest first (absent when there were none). */
+    merges?: SnapshotMerge[];
 }
 export declare function sha256Hex(input: string | Buffer): string;
 /**
@@ -46,9 +78,17 @@ export declare function backupPath(settingsPath: string, now: Date): string;
  * Return all gate-disable snapshot paths in `settingsDir`, newest-first
  * by mtime. Missing directory returns []. Any file that isn't a valid
  * snapshot is silently skipped — `gate enable` re-parses the candidates
- * and surfaces format errors at that point.
+ * and surfaces format errors at that point. `prefix` selects the snapshot
+ * family: the Claude settings snapshots by default, the Codex ones when the
+ * Codex gate passes its own prefix (`codex-snapshot.ts`).
+ */
+export declare function listSnapshots(settingsDir: string, prefix?: string): string[];
+/**
+ * The reason a parsed snapshot lacks one of the required string fields or
+ * its `filter` object, or null when it has them all. Shared by the Claude
+ * and Codex snapshot readers so the two cannot drift apart.
  */
-export declare function listSnapshots(settingsDir: string): string[];
+export declare function snapshotFieldProblem(filePath: string, obj: Record<string, unknown>, stringFields: string[]): string | null;
 export interface SnapshotReadOk {
     ok: true;
     snapshot: GateDisableSnapshot;
@@ -63,3 +103,240 @@ export interface SnapshotReadErr {
  * settings.json) and not re-validated against a hook schema.
  */
 export declare function readSnapshot(filePath: string): SnapshotReadOk | SnapshotReadErr;
+/** The name a snapshot is renamed to once retired. The file stays for audit. */
+export declare function retiredSnapshotPath(snapPath: string): string;
+/**
+ * Retire `snapPath` as superseded (rename it, keep it for audit) and return
+ * the new path: its groups were merged into a snapshot beside the file they
+ * were removed from, so it is not restored and never offered again.
+ */
+export declare function supersedeSnapshot(snapPath: string): string;
+/** Retire `snapPath` (rename it, keep it for audit) and return the new path. */
+export declare function retireSnapshot(snapPath: string): string;
+export interface LiveSnapshot {
+    path: string;
+    snapshot: GateDisableSnapshot;
+}
+/** A live snapshot beside the target that was taken for another settings file. */
+export interface ForeignSnapshot {
+    /** The snapshot file. */
+    path: string;
+    /** The file it was taken for: its recorded basename in the target's directory. */
+    settingsPath: string;
+    /** Whether a file is at `settingsPath` now (a settings file renamed since the disable is not). */
+    settingsExists: boolean;
+    /** The backup its first disable wrote: the pre-disable copy of that file, the way back when the file is gone. */
+    settingsBackupPath: string;
+}
+export type LiveSnapshotsResult = {
+    ok: true;
+    live: LiveSnapshot[];
+    /** Live snapshots beside the file that name another settings file; never read as this one's. */
+    skippedForeign: ForeignSnapshot[];
+} | {
+    ok: false;
+    reason: string;
+    /** The live snapshot file that could not be read. */
+    path: string;
+};
+/**
+ * Whether `recordedName`, in `dir`, is the directory entry `targetName`
+ * names. The same spelling is, by definition: snapshots sit beside their
+ * file and record its basename, so the name is the identity. A spelling that
+ * differs only in letter case or normalization is the same entry only on a
+ * filesystem that folds those (APFS by default), which `lstat` tells: both
+ * names must resolve to one regular file (neither a symlink) whose link
+ * count is 1, so no second name of that inode could be the one that matched.
+ * Every other name is another entry (a hard link, a symlink, a renamed file):
+ * restoring through it would write a new file at that name and leave the
+ * recorded file as the disable left it.
+ *
+ * `symlinks` lets the entry be a symlink itself (a symlinked Codex config,
+ * which the gate edits at its resolved target): two spellings then name one
+ * entry when `lstat` gives both the same device and inode and a link count of
+ * 1, as for a regular file. The Claude gate never sets it.
+ */
+export declare function namesSameEntry(dir: string, recordedName: string, targetName: string, opts?: {
+    symlinks?: boolean;
+}): boolean;
+/**
+ * The spelling of `settingsPath` the gate builds every other path from: the
+ * backup, the snapshot, the listing beside it, and the atomic write's temp
+ * file. A spelling with a `..` segment is replaced by its directory as the
+ * kernel resolves it (`kernelEntry`, which the Codex gate uses as well), so
+ * no path built from it is folded into another directory; every other
+ * spelling is kept as given and the paths the gate prints read the way they
+ * were written.
+ */
+export declare function settingsOwnEntry(settingsPath: string): string;
+/**
+ * The file `gate disable` and `gate enable` read and write for `settingsPath`.
+ * That is the path itself unless its last component is a symlink (a dotfiles
+ * setup): then it is the entry the link leads to, which may sit in another
+ * directory. Writing through the resolved entry keeps the link a link, and
+ * the snapshots sit beside the file itself, so a disable through either
+ * spelling is found by an enable through the other. Every hop of the chain is
+ * resolved the way the kernel resolves it (`walkLinkChain`, the walker the
+ * Codex gate uses too), so the file is the one reading through the path
+ * gives, `..` in a link text included. A link whose file is gone resolves to
+ * where the file would be, so the snapshots taken for it are still found; a
+ * link whose text passes through a directory that is gone resolves to that
+ * text as written (nothing can sit beside it). A path that is no link, and a
+ * loop, resolve to the path's own entry (`settingsOwnEntry`).
+ */
+export declare function resolveSettingsEntry(settingsPath: string): string;
+/**
+ * The live (not retired) snapshots that were taken for `settingsPath`,
+ * newest first by `createdAt`. Snapshots always sit beside their file, so
+ * only the basename of the recorded settings path counts, never how the
+ * directory was spelled when it was written (relative to some other working
+ * directory, or through a symlink): a snapshot belongs to the file when the
+ * target names the directory entry that basename names (`namesSameEntry`:
+ * the same spelling, or another spelling of the one entry on a
+ * case-insensitive filesystem). When `settingsPath` is itself a symlink
+ * (`resolveSettingsEntry`), the directory of the file it leads to is searched
+ * too, with the resolved entry as the target there: the snapshot of a disable
+ * made through the other spelling sits beside that file. A hard link to the
+ * file, a renamed file, or a snapshot found beside the file a symlink leads
+ * to but recorded under the symlink's own name is another entry, so a
+ * snapshot recorded for one is foreign to the other, whether or not the files
+ * exist. A snapshot for another settings file in the same directory is
+ * listed in `skippedForeign`, never dropped silently. A live snapshot that
+ * cannot be read, or records no target, is an error: its target cannot be
+ * told, so neither disable nor enable may go on as if it did not exist.
+ */
+export declare function listLiveSnapshots(settingsPath: string): LiveSnapshotsResult;
+/** Whether a write failed because the directory or filesystem does not allow it to be written. */
+export declare function isReadOnlyWriteError(err: unknown): boolean;
+/**
+ * What a gate refusal says first when the file a settings symlink leads to
+ * cannot be written where it sits: what the link is and what refuses. EACCES
+ * and EROFS come from the directory (the gate writes a temp file beside the
+ * file and renames it into place); EPERM can come from the file or from the
+ * directory (an immutable flag, a sticky directory), so it names both without
+ * saying which. Each verb adds its own way out.
+ */
+export declare function readOnlyLinkTargetText(settingsPath: string, entry: string, err: unknown): string;
+/** What a read-only refusal tells the operator to make writable: the directory, and for EPERM the file too. */
+export declare function readOnlyWritablePlace(entry: string, err: unknown): string;
+/** The command that puts a copy of the file a symlink leads to in place of the link. */
+export declare function copyOverLinkCommand(settingsPath: string, entry: string): string;
+/**
+ * How a command prints a `--settings` target so that it works as printed: a
+ * path with a character the shell would act on (a space, a quote, `~`, `=`,
+ * `%`, `$`) is single-quoted by the one quoting helper the gate shares.
+ */
+export declare function settingsFlag(settingsPath: string): string;
+/** `PreToolUse matcher="Bash"`: how a message names a removed group. */
+export declare function groupLabel(event: string, group: unknown): string;
+/** The `command` strings of a hook group's hooks, in order; empty for a malformed group. */
+export declare function groupCommands(group: unknown): string[];
+/**
+ * How a refusal names a removed group that is still missing: its event and
+ * matcher plus its commands, so that when another group shares the matcher
+ * the operator can tell which one is out of the file.
+ */
+export declare function missingLabel(entry: RemovedGroup): string;
+/** A snapshot entry and the group of the file with its event and matcher but other content. */
+export interface ChangedGroup {
+    entry: RemovedGroup;
+    /** The group the file holds in its place. */
+    current: unknown;
+}
+/** Names a changed group and the commands of both versions, so the operator can tell whether it is the gate's. */
+export declare function changedLabel(changed: ChangedGroup): string;
+export interface RestorePlan {
+    /** The hooks block with the groups that were still missing spliced back in; the input is not modified. */
+    hooks: Record<string, unknown[]>;
+    /** Entries spliced back in. */
+    restored: RemovedGroup[];
+    /**
+     * Entries the file already holds unchanged (deep-equal, put back by hand
+     * or by an apply). Left alone, never spliced in a second time.
+     */
+    alreadyBack: RemovedGroup[];
+    /**
+     * Entries the file holds no unchanged copy of, but a group with the same
+     * event and matcher and other content. That group may be the gate's,
+     * re-rendered, or another hook that happens to share the matcher, so it is
+     * never taken for the entry on its own: `gate enable` and `gate disable`
+     * refuse while there is one, and only `gate enable --force` accepts it as
+     * back. Never spliced in.
+     */
+    changed: ChangedGroup[];
+}
+/**
+ * What putting a snapshot's removed groups back into `current` would do. The
+ * entries are paired with the groups of the file one to one: first every
+ * entry with a deep-equal group of the same event (`alreadyBack`), then each
+ * entry left over, in the order the snapshot recorded them, with the first
+ * group still unpaired that has its event and matcher (`changed`). The rest
+ * are spliced in at their recorded positions: each removal step recorded its
+ * indices against the array as it stood just before that step, so the steps
+ * are undone newest first, and inside a step by event and ascending index (an
+ * earlier insertion never shifts a later insertion's target index past the
+ * array end).
+ */
+export declare function planRestore(current: Record<string, unknown[]>, snapshot: GateDisableSnapshot): RestorePlan;
+/**
+ * The settings text `gate enable` writes when it puts `plan`'s groups back
+ * into the parsed settings file `obj`: `obj` with its `hooks` key replaced by
+ * `plan.hooks` (and removed when the plan holds no group at all).
+ */
+export declare function restoredSettingsText(obj: Record<string, unknown>, hooks: Record<string, unknown[]>): string;
+/** Why `harness gate enable` needs `--force` for a snapshot; see `claudeEnableRefusal`. */
+export type ClaudeEnableRefusal = "changed-group" | "edited-settings";
+/**
+ * The one decision of why `harness gate enable` refuses a snapshot against
+ * the current settings.json unless it was called with `--force`, or null when
+ * it restores or retires it without one:
+ * - `"changed-group"`: the file holds a group with the event and matcher of a
+ *   removed one but other content, which may be another hook sharing the
+ *   matcher, so it never counts as back on its own;
+ * - `"edited-settings"`: the file is not the state the snapshot left and the
+ *   groups that are still missing do not add up to the pre-disable file, so
+ *   a restore would write over an operator edit.
+ * The current file already matching the pre-disable state, and a snapshot
+ * whose every group is back, never refuse: nothing is put back. A changed
+ * group wins when both hold, as `gate enable` refuses for it before it
+ * reaches the edit check. `gate enable` throws on it, and `harness doctor`
+ * calls it to decide whether its warning for a gate-disabled hook must name
+ * `--force`; the two callers never re-implement the conditions.
+ */
+export declare function claudeEnableRefusal(currentSha: string, currentObj: Record<string, unknown>, plan: RestorePlan, snapshot: GateDisableSnapshot): ClaudeEnableRefusal | null;
+/**
+ * The live snapshots a plain `harness gate enable` applies on its next call,
+ * in the order it applies them, from `listLiveSnapshots`' newest-first list.
+ * `gate enable` restores ONE snapshot per call and retires it, so today it is
+ * the newest alone: an older snapshot waits until that restore changed the
+ * file, which is exactly why its own refusal against the CURRENT file is not
+ * what the next plain enable will decide. `harness doctor` asks this question
+ * before it words the warning for a gate-disabled hook, and `gate enable` takes
+ * its snapshot through it too, so the two cannot drift apart on which one
+ * decides.
+ */
+export declare function nextEnableSnapshots(live: readonly LiveSnapshot[]): readonly LiveSnapshot[];
+export type SettingsHooksParse = {
+    ok: true;
+    hooks: Record<string, unknown[]>;
+} | {
+    ok: false;
+    reason: "hooks-not-object";
+} | {
+    ok: false;
+    reason: "event-not-array";
+    event: string;
+};
+/**
+ * The `hooks` of a parsed settings.json as the gate reads them: an array of
+ * groups per event, each array copied, so a caller never mutates the parsed
+ * document. A `hooks` key that is absent reads as no groups at all; any other
+ * shape the gate refuses to read is a failure reason, not a guess:
+ * `hooks-not-object` when the field itself is not an object, and
+ * `event-not-array` naming the first event whose value is not an array.
+ * `gate enable` turns the two reasons into its two refusal messages, and
+ * `harness doctor` reads them the same way when it asks the gate what a
+ * plain `gate enable` would do with the file it compares; the two never
+ * re-implement the walk.
+ */
+export declare function parseSettingsHooks(doc: Record<string, unknown>): SettingsHooksParse;