@pennixrv/trellis 0.6.17

package/dist/utils/ablation-store.d.ts

@@ -0,0 +1,123 @@
+/**
+ * External, versioned recovery storage for reversible full Trellis ablation.
+ *
+ * The store intentionally contains only manifest-owned project paths and the
+ * exact `.trellis/` tree. User-authored task/spec/workspace files may contain
+ * sensitive text, so the state root is private and retained only until a
+ * verified restore. Unrelated application files and global host state are
+ * never copied.
+ */
+export declare const ABLATION_SCHEMA_VERSION = 1;
+export declare const FULL_ABLATION_CAPABILITY: "trellis.full";
+export declare const ABLATION_STATE_ROOT_ENV = "TRELLIS_ABLATION_STATE_ROOT";
+export type AblationStatus = "preparing" | "applied" | "restoring" | "conflict";
+export interface AbsentFingerprint {
+    kind: "absent";
+}
+export interface FileFingerprint {
+    kind: "file";
+    sha256: string;
+    size: number;
+    mode: number;
+}
+export interface DirectoryFingerprint {
+    kind: "directory";
+    sha256: string;
+    mode: number;
+}
+export interface SymlinkFingerprint {
+    kind: "symlink";
+    target: string;
+    mode: number;
+}
+export type PathFingerprint = AbsentFingerprint | FileFingerprint | DirectoryFingerprint | SymlinkFingerprint;
+export interface AblationEntry {
+    relativePath: string;
+    pre: PathFingerprint;
+    expectedAblated: PathFingerprint;
+    backupPath?: string;
+}
+export interface AblationStateV1 {
+    schemaVersion: 1;
+    status: AblationStatus;
+    projectRoot: string;
+    projectKey: string;
+    trellisVersion: string;
+    capabilities: [typeof FULL_ABLATION_CAPABILITY];
+    createdAt: string;
+    configuredPlatforms: string[];
+    manifest: Record<string, string>;
+    entries: AblationEntry[];
+}
+export interface TransactionPaths {
+    stateRoot: string;
+    transactionDir: string;
+    stateFile: string;
+    backupDir: string;
+    lockFile: string;
+}
+export interface StagedAblationInput {
+    projectRoot: string;
+    configuredPlatforms: readonly string[];
+    manifest: Record<string, string>;
+    entries: AblationEntry[];
+}
+export interface StageAblationOptions {
+    /** The caller already holds this project's ablation-operation lock. */
+    lockHeld?: boolean;
+}
+export interface LoadedAblationTransaction {
+    paths: TransactionPaths;
+    state: AblationStateV1;
+}
+export interface RestoreAblationOptions {
+    /** Only preflight; do not transition state or restore/delete any path. */
+    dryRun?: boolean;
+    /** Delete the external transaction after verified restoration. */
+    deleteAfterRestore?: boolean;
+}
+export interface AblationConflict {
+    relativePath: string;
+    expected: PathFingerprint;
+    actual: PathFingerprint;
+}
+export declare class AblationConflictError extends Error {
+    readonly conflicts: AblationConflict[];
+    constructor(conflicts: AblationConflict[]);
+}
+/** Fingerprint one path without dereferencing a symlink leaf. */
+export declare function fingerprintPath(absPath: string): PathFingerprint;
+export declare function expectedFileFingerprint(content: string | Uint8Array, mode: number): FileFingerprint;
+export declare function fingerprintsEqual(left: PathFingerprint, right: PathFingerprint): boolean;
+export declare function canonicalProjectRoot(cwd: string): string;
+export declare function projectKey(projectRoot: string): string;
+export declare function getAblationStateRoot(): string;
+export declare function getTransactionPaths(projectRoot: string, stateRoot?: string): TransactionPaths;
+export declare function assertExternalStateRoot(projectRoot: string, stateRoot: string): void;
+/** Parse and validate an external state file. Unknown schemas fail closed. */
+export declare function parseAblationState(value: unknown): AblationStateV1;
+/**
+ * Stage and verify the complete backup, then atomically publish a `preparing`
+ * transaction before the caller mutates the project.
+ */
+export declare function stageAblationTransaction(input: StagedAblationInput, options?: StageAblationOptions): LoadedAblationTransaction;
+export declare function loadAblationTransaction(projectRoot: string, stateRoot?: string): LoadedAblationTransaction | null;
+export declare function transitionAblationState(transaction: LoadedAblationTransaction, status: AblationStatus): AblationStateV1;
+/** Serialize ablate/restore state and project mutations for one project. */
+export declare function withAblationProjectLock<T>(paths: TransactionPaths, operation: () => T): T;
+/** Preflight every affected path before restore writes anything. */
+export declare function collectRestoreConflicts(transaction: LoadedAblationTransaction): AblationConflict[];
+/** Restore exact backup bytes/link identity/modes without running preflight. */
+export declare function restoreTransactionFiles(transaction: LoadedAblationTransaction, options?: {
+    verifyExpectedState?: boolean;
+}): void;
+export declare function verifyRestoredState(transaction: LoadedAblationTransaction): void;
+export declare function verifyAblatedState(transaction: LoadedAblationTransaction): void;
+/** Conflict-safe exact restore. Any mismatch causes zero project writes. */
+export declare function restoreAblationTransaction(transaction: LoadedAblationTransaction, options?: RestoreAblationOptions): void;
+/** Roll back this process's partial ablation while holding the project lock. */
+export declare function rollbackAblationTransaction(transaction: LoadedAblationTransaction, options?: {
+    lockHeld?: boolean;
+}): void;
+export declare function deleteAblationTransaction(transaction: LoadedAblationTransaction): void;
+//# sourceMappingURL=ablation-store.d.ts.map

package/dist/utils/ablation-store.d.ts.map

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