@aligndottech/cli 0.46.0 → 0.47.0

package/dist/lib/safe-config-write.d.ts

@@ -0,0 +1,140 @@
+import { chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+export declare const BACKUP_SUFFIX = ".align-backup";
+export type SafeWriteStatus = 'written' | 'unchanged' | 'declined' | 'symlink';
+/** The fs calls the writer makes. A parameter so a test can change the file mid-write. */
+export interface SafeFs {
+    readFileSync: typeof readFileSync;
+    writeFileSync: typeof writeFileSync;
+    renameSync: typeof renameSync;
+    copyFileSync: typeof copyFileSync;
+    lstatSync: typeof lstatSync;
+    readlinkSync: typeof readlinkSync;
+    chmodSync: typeof chmodSync;
+    unlinkSync: typeof unlinkSync;
+    mkdirSync: typeof mkdirSync;
+    readdirSync: typeof readdirSync;
+}
+type Json = Record<string, unknown>;
+/** One value or array element align put in a JSON config. Hashes only, never the value. */
+export interface OwnedItem {
+    path: string[];
+    kind: 'value' | 'array-item';
+    sha256: string;
+    /** Prune ancestors back to this path length if they end up empty (the parents align created). */
+    createdDepth: number;
+    /**
+     * The key existed before align's first write and align overwrote it. `beforeSha256` is the
+     * hash of the user's value; the value itself comes back from align's backup.
+     */
+    replaced?: boolean;
+    beforeSha256?: string;
+    /** Which snapshot holds the user's value: 0 is `<file>.align-backup`, n is `<file>.align-backup.<n>`. */
+    snapshot?: number;
+    /** align's write took this key (or this whole array) away; undo puts the user's original back when it is still gone. */
+    removed?: boolean;
+}
+/** One file align wrote, as the manifest remembers it. */
+export interface WrittenConfig {
+    /** The file did not exist before align's first write. */
+    created: boolean;
+    /** sha256 of what align last wrote. */
+    sha256: string;
+    /**
+     * sha256 of what align wrote FIRST. A whole-file undo needs the file to equal this AND the last
+     * write: a later align rewrite folds the user's edits into the file, so matching only the last
+     * write proves nothing about whether they edited it in between.
+     */
+    firstSha256: string;
+    /** 'made': align made the backup. 'foreign': one was already there and is not trusted. 'none': no original to keep. */
+    backup: 'made' | 'foreign' | 'none';
+    backupSha256?: string;
+    owned?: OwnedItem[];
+    /**
+     * Extra copies of the file taken just before a write that found it changed by someone else
+     * (`<file>.align-backup.<n>`, 0600). Hashes only: the manifest never holds config values.
+     */
+    snapshots?: Array<{
+        n: number;
+        sha256: string;
+    }>;
+    /** Text files: the managed block align wrote. */
+    block?: {
+        start: string;
+        end: string;
+        sha256: string; /** a block was already there, and align's replaced it: the original is in the backup */
+        replaced?: boolean;
+        snapshot?: number;
+    };
+}
+/** Fold one write into what the manifest already holds for that file. */
+export declare function mergeWrittenConfig(prev: WrittenConfig | undefined, next: WrittenConfig): WrittenConfig;
+/**
+ * Where the writer reports each file it wrote (`record`, handed only what THIS write added;
+ * the store merges) and how it reads back what is already recorded (`get`). Installed once by
+ * the CLI (cli.ts), never by a test, so a test that writes a config does not touch the real store.
+ */
+export declare function setWriteRecorder(record: ((file: string, entry: WrittenConfig) => void) | undefined, get?: (file: string) => WrittenConfig | undefined): void;
+export interface SafeWriteOptions {
+    /** One line to the user, stderr. Defaults to console.error. */
+    note?: (line: string) => void;
+    fs?: SafeFs;
+    /** JSON only: end the file with a newline (default false, matching the older writers). */
+    trailingNewline?: boolean;
+    /** Directories at or above this are the user's own and are not checked for links. Default: the home dir. */
+    root?: string;
+    /** Text only: the markers of the block align manages, so undo can take just that block out. */
+    markers?: {
+        start: string;
+        end: string;
+    };
+    /** The tail of the invalid-JSON message: what to do about it. */
+    invalidJsonAdvice?: string;
+}
+export declare class SafeWriteConflictError extends Error {
+    constructor(file: string);
+}
+/** The text form. `compute` gets the current text (null when missing) and returns the new text, or undefined to leave it. */
+export declare function safeWriteText(file: string, compute: (current: string | null) => string | undefined, opts?: SafeWriteOptions): SafeWriteStatus;
+/**
+ * What align changed in a JSON config. Containers (the root and its direct children, such as
+ * `mcpServers` or `hooks`) are walked; a server entry one level further down is a unit:
+ *  - new key: one `value` item (or, under a new container, one item per new entry);
+ *  - existing key whose value changed: ONE `replaced` item holding the hash of the user's value,
+ *    never a diff into it (a diff into `args` would "undo" half an entry);
+ *  - existing array: if align only added elements, those elements; if it REMOVED or changed any
+ *    element it did not put there itself, the whole array is one `replaced` unit;
+ *  - an existing key align took away: a `removed` unit.
+ * `prev` is what an earlier write already recorded, so align's own earlier output is never
+ * mistaken for the user's.
+ */
+export declare function ownedOf(before: Json, after: Json, prev?: OwnedItem[], snapshot?: number): OwnedItem[];
+/**
+ * The JSON form. `update` gets the parsed object ({} for a missing or empty file) and returns
+ * the object to write, or undefined to leave the file alone. A file that does not parse is an
+ * error, never overwritten.
+ */
+export declare function safeWriteJson(file: string, update: (current: Json) => Json | undefined, opts?: SafeWriteOptions): SafeWriteStatus;
+export interface UndoReport {
+    /** Whole file put back from align's own backup. */
+    restored: string[];
+    /** A file align created, removed (it still held exactly what align wrote). */
+    removed: string[];
+    /** Only align's own entries taken out; the rest of the file kept. */
+    cleaned: string[];
+    /** Files left as they are, one line each, with what to do by hand. */
+    skipped: string[];
+    /** The manifest entries that are finished. Skipped files are NOT in here. */
+    done: string[];
+}
+/**
+ * Take align back out of every recorded file.
+ *  - If the file still holds exactly what align last wrote, the whole file goes back: a file
+ *    align created is removed, any other comes back from align's own backup (a regular file
+ *    align made, whose hash matches; anything else at that path is not trusted).
+ *  - Otherwise the user has touched it since, and only align's own entries come out. An entry
+ *    the user edited, or one align overwrote, is left and named.
+ * Skipped files keep their manifest entry and their backup.
+ */
+export declare function undoWrittenConfigs(manifest: Record<string, WrittenConfig>, fs?: SafeFs): UndoReport;
+export {};
+//# sourceMappingURL=safe-config-write.d.ts.map

package/dist/lib/safe-config-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-config-write.d.ts","sourceRoot":"","sources":["../../src/lib/safe-config-write.ts"],"names":[],"mappings":"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"}