@guilz-dev/belay 0.6.0 → 0.8.0

package/dist/core/process-runner.js

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+const PROCESS_OUTPUT_TAIL_BYTES = 16_384;
+const EXIT_OUTPUT_GRACE_MS = 25;
+const TIMEOUT_KILL_GRACE_MS = 250;
+const WINDOWS_TASKKILL_TIMEOUT_MS = 5_000;
+function appendOutputTail(current, chunk) {
+    const next = Buffer.concat([current, Buffer.from(chunk)]);
+    return next.length > PROCESS_OUTPUT_TAIL_BYTES ? next.subarray(-PROCESS_OUTPUT_TAIL_BYTES) : next;
+}
+export function windowsProcessTreeKillArgs(pid) {
+    return ['/pid', String(pid), '/t', '/f'];
+}
+function forceKillWindowsProcessTree(pid, fallback) {
+    return new Promise((resolve) => {
+        const taskkill = spawn('taskkill', windowsProcessTreeKillArgs(pid), {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        let settled = false;
+        const finish = (succeeded) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            if (!succeeded) {
+                fallback();
+            }
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            taskkill.kill();
+            finish(false);
+        }, WINDOWS_TASKKILL_TIMEOUT_MS);
+        taskkill.on('error', () => finish(false));
+        taskkill.on('close', (code) => finish(code === 0));
+    });
+}
+export function runProcessWithBoundedOutput(file, args, options, timeoutMs) {
+    return new Promise((resolve) => {
+        const detached = process.platform !== 'win32';
+        const child = spawn(file, args, {
+            ...options,
+            detached,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let timedOut = false;
+        let settled = false;
+        let windowsCleanupPending = false;
+        let exitTimer;
+        child.stdout.on('data', (chunk) => {
+            stdout = appendOutputTail(stdout, chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr = appendOutputTail(stderr, chunk);
+        });
+        const finish = (exitCode, signal) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeoutTimer);
+            if (exitTimer) {
+                clearTimeout(exitTimer);
+            }
+            child.stdout.destroy();
+            child.stderr.destroy();
+            resolve({
+                exitCode,
+                signal: signal ? String(signal) : null,
+                timedOut,
+                stdout: stdout.toString('utf8'),
+                stderr: stderr.toString('utf8'),
+            });
+        };
+        const kill = (signal) => {
+            try {
+                if (detached && child.pid) {
+                    process.kill(-child.pid, signal);
+                    return;
+                }
+                child.kill(signal);
+            }
+            catch {
+                // The process may already have exited between the state check and kill.
+            }
+        };
+        const timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            if (process.platform === 'win32' && child.pid) {
+                windowsCleanupPending = true;
+                void forceKillWindowsProcessTree(child.pid, () => child.kill('SIGKILL')).then(() => {
+                    windowsCleanupPending = false;
+                    finish(child.exitCode, child.signalCode ?? 'SIGKILL');
+                });
+                return;
+            }
+            kill('SIGTERM');
+            setTimeout(() => {
+                kill('SIGKILL');
+                finish(null, 'SIGKILL');
+            }, TIMEOUT_KILL_GRACE_MS);
+        }, timeoutMs);
+        child.on('error', (error) => {
+            stderr = appendOutputTail(stderr, error.message);
+            finish(1, null);
+        });
+        child.on('exit', (exitCode, signal) => {
+            clearTimeout(timeoutTimer);
+            if (windowsCleanupPending) {
+                return;
+            }
+            exitTimer = setTimeout(() => finish(exitCode, signal), EXIT_OUTPUT_GRACE_MS);
+        });
+        child.on('close', (exitCode, signal) => {
+            if (windowsCleanupPending) {
+                return;
+            }
+            finish(exitCode, signal);
+        });
+    });
+}

package/dist/core/recover-advice.js

@@ -1,5 +1,6 @@
 export const RECOVER_DISCLAIMER = [
-    'Advisory only — belay does not run recovery commands.',
+    'Advisory only — this report is not proof that the selected action executed. Only a checkpoint receipt shown by `belay recover list` is an executable recovery point.',
+    '`belay recover advice` does not run recovery commands; checkpoint restore requires a separate one-shot human approval.',
     'Advice is based on what belay observed through hooks; actions outside hook scope may not be visible.',
     'Recovery commands themselves pass through belay hooks — destructive undo steps may be blocked again.',
 ];

package/dist/core/recovery/artifact-store.d.ts

@@ -0,0 +1,29 @@
+import type { RecoveryCheckpointManifest, RecoveryCheckpointState, RecoveryCheckpointStateV1, RecoveryReceiptV1 } from './types.js';
+export declare const RECOVERY_CHECKPOINT_CORRUPT = "recovery_checkpoint_corrupt";
+export interface PreparedRecoveryCheckpoint {
+    checkpointId: string;
+    manifest: RecoveryCheckpointManifest;
+    manifestHash: string;
+    proofHash: string;
+}
+export interface RecoveryArtifact {
+    artifactDir: string;
+    manifest: RecoveryCheckpointManifest;
+    state: RecoveryCheckpointStateV1;
+    manifestHash: string;
+    receipt?: RecoveryReceiptV1;
+}
+export declare function checkpointsRoot(stateDir: string): string;
+export declare function checkpointDir(stateDir: string, checkpointId: string): string;
+export declare function fsyncPath(filePath: string): Promise<void>;
+export declare function atomicWriteJson(filePath: string, value: unknown): Promise<void>;
+export declare function writeRecoveryState(artifactDir: string, state: RecoveryCheckpointState, manifestHash: string, detail?: string): Promise<void>;
+export declare function directorySize(root: string): Promise<number>;
+export declare function readRecoveryArtifact(stateDir: string, checkpointId: string): Promise<RecoveryArtifact>;
+export declare function ensureRecoveryReceipt(artifactDir: string, manifest: RecoveryCheckpointManifest, manifestHash: string): Promise<RecoveryReceiptV1>;
+export declare function checkpointIds(stateDir: string): Promise<string[]>;
+export declare function artifactRepoRoot(stateDir: string, checkpointId: string): Promise<string | null>;
+export declare function checkpointIdsForRepo(stateDir: string, repoRoot: string): Promise<string[]>;
+export declare function cleanupOrphanedStaging(stateDir: string): Promise<void>;
+export declare function markRecoveryCheckpointApplying(stateDir: string, checkpoint: PreparedRecoveryCheckpoint): Promise<void>;
+export declare function markRecoveryCheckpointApplied(stateDir: string, checkpoint: PreparedRecoveryCheckpoint): Promise<RecoveryReceiptV1>;

package/dist/core/recovery/artifact-store.js

@@ -0,0 +1,336 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { lstat, mkdir, open, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+import { canonicalPath } from '../path-utils.js';
+import { recoveryStateHash, validateRecoverySnapshot, validRecoveryRelativePath, } from './snapshot-node.js';
+export const RECOVERY_CHECKPOINT_CORRUPT = 'recovery_checkpoint_corrupt';
+const RECOVERY_STATES = new Set([
+    'prepared',
+    'applying',
+    'applied',
+    'restoring',
+    'restored',
+    'conflict',
+    'corrupt',
+    'needs_manual_repair',
+]);
+const STAGING_STALE_MS = 5 * 60_000;
+export function checkpointsRoot(stateDir) {
+    return path.join(stateDir, 'recovery', 'checkpoints');
+}
+export function checkpointDir(stateDir, checkpointId) {
+    if (!/^cp_[a-f0-9]{24}$/.test(checkpointId)) {
+        throw new Error('invalid_recovery_checkpoint_id');
+    }
+    return path.join(checkpointsRoot(stateDir), checkpointId);
+}
+export async function fsyncPath(filePath) {
+    const handle = await open(filePath, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function atomicWriteJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.tmp-${randomUUID()}`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    await fsyncPath(temporary);
+    await rename(temporary, filePath);
+    await fsyncPath(path.dirname(filePath));
+}
+export async function writeRecoveryState(artifactDir, state, manifestHash, detail) {
+    const value = {
+        version: 1,
+        state,
+        updatedAt: new Date().toISOString(),
+        manifestHash,
+        ...(detail ? { detail } : {}),
+    };
+    await atomicWriteJson(path.join(artifactDir, 'state.json'), value);
+}
+export async function directorySize(root) {
+    if (!existsSync(root))
+        return 0;
+    let total = 0;
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isDirectory())
+            total += await directorySize(entryPath);
+        else
+            total += (await lstat(entryPath)).size;
+    }
+    return total;
+}
+function isManifestShape(value, checkpointId) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const manifest = value;
+    const proof = manifest.proof;
+    const manifestKeys = [
+        'version',
+        'checkpointId',
+        'backend',
+        'repoRoot',
+        'repoIdentity',
+        'commandFingerprint',
+        'createdAt',
+        'expiresAt',
+        'proof',
+        'entries',
+        ...(manifest.version === 2 ? ['resourceKind'] : []),
+    ];
+    const proofKeys = [
+        'version',
+        'backend',
+        'inputFingerprint',
+        'resourceScope',
+        'baseStateHash',
+        'effectClosure',
+        'issuedAt',
+        'expiresAt',
+        'probeSignals',
+    ];
+    if (![1, 2].includes(manifest.version) ||
+        Object.keys(manifest).length !== manifestKeys.length ||
+        !Object.keys(manifest).every((key) => manifestKeys.includes(key)) ||
+        manifest.checkpointId !== checkpointId ||
+        !['git_worktree', 'file_checkpoint'].includes(String(manifest.backend)) ||
+        typeof manifest.repoRoot !== 'string' ||
+        typeof manifest.repoIdentity !== 'string' ||
+        typeof manifest.commandFingerprint !== 'string' ||
+        typeof manifest.createdAt !== 'string' ||
+        !Number.isFinite(Date.parse(manifest.createdAt)) ||
+        typeof manifest.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(manifest.expiresAt)) ||
+        !Array.isArray(manifest.entries) ||
+        !proof ||
+        Object.keys(proof).length !== proofKeys.length ||
+        !Object.keys(proof).every((key) => proofKeys.includes(key)) ||
+        proof.version !== 1 ||
+        proof.backend !== manifest.backend ||
+        typeof proof.inputFingerprint !== 'string' ||
+        proof.inputFingerprint !== manifest.commandFingerprint ||
+        typeof proof.resourceScope !== 'string' ||
+        proof.resourceScope !== manifest.repoRoot ||
+        typeof proof.baseStateHash !== 'string' ||
+        proof.effectClosure !== 'repo_local_fs_observed' ||
+        typeof proof.issuedAt !== 'string' ||
+        !Number.isFinite(Date.parse(proof.issuedAt)) ||
+        proof.issuedAt !== manifest.createdAt ||
+        typeof proof.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(proof.expiresAt)) ||
+        proof.expiresAt !== manifest.expiresAt ||
+        !Array.isArray(proof.probeSignals) ||
+        !proof.probeSignals.every((signal) => typeof signal === 'string')) {
+        return false;
+    }
+    if (manifest.version === 1)
+        return !('resourceKind' in manifest);
+    return ['git_repository', 'directory'].includes(String(manifest.resourceKind));
+}
+export async function readRecoveryArtifact(stateDir, checkpointId) {
+    const artifactDir = checkpointDir(stateDir, checkpointId);
+    let rawManifest;
+    let state;
+    try {
+        rawManifest = JSON.parse(await readFile(path.join(artifactDir, 'manifest.json'), 'utf8'));
+        state = JSON.parse(await readFile(path.join(artifactDir, 'state.json'), 'utf8'));
+    }
+    catch {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    if (!isManifestShape(rawManifest, checkpointId))
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    const manifest = rawManifest;
+    const manifestHash = hashValue(canonicalStringify(manifest));
+    const stateKeys = state && typeof state === 'object' ? Object.keys(state) : [];
+    const expectedStateKeys = ['version', 'state', 'updatedAt', 'manifestHash'];
+    if (state && typeof state === 'object' && 'detail' in state)
+        expectedStateKeys.push('detail');
+    if (!state ||
+        typeof state !== 'object' ||
+        Array.isArray(state) ||
+        stateKeys.length !== expectedStateKeys.length ||
+        !stateKeys.every((key) => expectedStateKeys.includes(key)) ||
+        state.version !== 1 ||
+        !RECOVERY_STATES.has(state.state) ||
+        typeof state.updatedAt !== 'string' ||
+        !Number.isFinite(Date.parse(state.updatedAt)) ||
+        (state.detail !== undefined && typeof state.detail !== 'string') ||
+        state.manifestHash !== manifestHash) {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    const entryPaths = new Set();
+    for (const entry of manifest.entries) {
+        if (!entry ||
+            typeof entry !== 'object' ||
+            Array.isArray(entry) ||
+            Object.keys(entry).length !== 3 ||
+            !Object.keys(entry).every((key) => ['path', 'before', 'after'].includes(key)) ||
+            typeof entry.path !== 'string' ||
+            !('before' in entry) ||
+            !('after' in entry) ||
+            !validRecoveryRelativePath(entry.path) ||
+            entryPaths.has(path.normalize(entry.path))) {
+            throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+        }
+        entryPaths.add(path.normalize(entry.path));
+        for (const [side, snapshot] of [
+            ['before', entry.before],
+            ['after', entry.after],
+        ]) {
+            await validateRecoverySnapshot({
+                snapshot,
+                side,
+                manifestVersion: manifest.version,
+                artifactDir,
+                corruptReason: RECOVERY_CHECKPOINT_CORRUPT,
+            });
+        }
+    }
+    const receiptPath = path.join(artifactDir, 'receipt.json');
+    let receipt;
+    if (['applied', 'restoring', 'restored', 'conflict'].includes(state.state) ||
+        existsSync(receiptPath)) {
+        receipt = await readAndValidateRecoveryReceipt(artifactDir, manifest, manifestHash);
+    }
+    return { artifactDir, manifest, state, manifestHash, ...(receipt ? { receipt } : {}) };
+}
+async function readAndValidateRecoveryReceipt(artifactDir, manifest, manifestHash) {
+    let rawReceipt;
+    try {
+        rawReceipt = JSON.parse(await readFile(path.join(artifactDir, 'receipt.json'), 'utf8'));
+    }
+    catch {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    if (!rawReceipt || typeof rawReceipt !== 'object' || Array.isArray(rawReceipt)) {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    const receipt = rawReceipt;
+    const receiptKeys = [
+        'version',
+        'checkpointId',
+        'manifestHash',
+        'proofHash',
+        'postStateHash',
+        'appliedAt',
+        'changeCount',
+    ];
+    if (Object.keys(receipt).length !== receiptKeys.length ||
+        !Object.keys(receipt).every((key) => receiptKeys.includes(key)) ||
+        receipt.version !== 1 ||
+        receipt.checkpointId !== manifest.checkpointId ||
+        receipt.manifestHash !== manifestHash ||
+        receipt.proofHash !== hashValue(canonicalStringify(manifest.proof)) ||
+        receipt.postStateHash !== recoveryStateHash(manifest.entries, 'after') ||
+        receipt.changeCount !== manifest.entries.length ||
+        typeof receipt.appliedAt !== 'string' ||
+        !Number.isFinite(Date.parse(receipt.appliedAt))) {
+        throw new Error(RECOVERY_CHECKPOINT_CORRUPT);
+    }
+    return receipt;
+}
+export async function ensureRecoveryReceipt(artifactDir, manifest, manifestHash) {
+    const receiptPath = path.join(artifactDir, 'receipt.json');
+    if (existsSync(receiptPath)) {
+        return readAndValidateRecoveryReceipt(artifactDir, manifest, manifestHash);
+    }
+    const receipt = {
+        version: 1,
+        checkpointId: manifest.checkpointId,
+        manifestHash,
+        proofHash: hashValue(canonicalStringify(manifest.proof)),
+        postStateHash: recoveryStateHash(manifest.entries, 'after'),
+        appliedAt: new Date().toISOString(),
+        changeCount: manifest.entries.length,
+    };
+    await atomicWriteJson(receiptPath, receipt);
+    return receipt;
+}
+export async function checkpointIds(stateDir) {
+    const root = checkpointsRoot(stateDir);
+    if (!existsSync(root))
+        return [];
+    return (await readdir(root, { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory() && /^cp_[a-f0-9]{24}$/.test(entry.name))
+        .map((entry) => entry.name);
+}
+export async function artifactRepoRoot(stateDir, checkpointId) {
+    const artifactDir = checkpointDir(stateDir, checkpointId);
+    try {
+        const manifest = JSON.parse(await readFile(path.join(artifactDir, 'manifest.json'), 'utf8'));
+        if (typeof manifest.repoRoot === 'string' && manifest.repoRoot) {
+            return canonicalPath(manifest.repoRoot);
+        }
+    }
+    catch {
+        // Fall through to the immutable staging owner used for quota attribution.
+    }
+    try {
+        const owner = JSON.parse(await readFile(path.join(artifactDir, 'owner.json'), 'utf8'));
+        return typeof owner.repoRoot === 'string' && owner.repoRoot
+            ? canonicalPath(owner.repoRoot)
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function checkpointIdsForRepo(stateDir, repoRoot) {
+    const expected = canonicalPath(repoRoot);
+    const matching = [];
+    for (const id of await checkpointIds(stateDir)) {
+        if ((await artifactRepoRoot(stateDir, id)) === expected)
+            matching.push(id);
+    }
+    return matching;
+}
+export async function cleanupOrphanedStaging(stateDir) {
+    const root = checkpointsRoot(stateDir);
+    if (!existsSync(root))
+        return;
+    const now = Date.now();
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^\.tmp-cp_[a-f0-9]{24}$/.test(entry.name))
+            continue;
+        const stagingPath = path.join(root, entry.name);
+        let stale = false;
+        try {
+            const owner = JSON.parse(await readFile(path.join(stagingPath, 'owner.json'), 'utf8'));
+            const pid = typeof owner.pid === 'number' ? owner.pid : Number.NaN;
+            const createdAt = typeof owner.createdAt === 'string' ? Date.parse(owner.createdAt) : NaN;
+            let alive = false;
+            if (Number.isInteger(pid) && pid > 0) {
+                try {
+                    process.kill(pid, 0);
+                    alive = true;
+                }
+                catch {
+                    alive = false;
+                }
+            }
+            stale = !alive || !Number.isFinite(createdAt);
+        }
+        catch {
+            const info = await lstat(stagingPath);
+            stale = now - info.mtimeMs >= STAGING_STALE_MS;
+        }
+        if (stale)
+            await rm(stagingPath, { recursive: true, force: true });
+    }
+}
+export async function markRecoveryCheckpointApplying(stateDir, checkpoint) {
+    await writeRecoveryState(checkpointDir(stateDir, checkpoint.checkpointId), 'applying', checkpoint.manifestHash);
+}
+export async function markRecoveryCheckpointApplied(stateDir, checkpoint) {
+    const artifactDir = checkpointDir(stateDir, checkpoint.checkpointId);
+    const receipt = await ensureRecoveryReceipt(artifactDir, checkpoint.manifest, checkpoint.manifestHash);
+    await writeRecoveryState(artifactDir, 'applied', checkpoint.manifestHash);
+    return receipt;
+}

package/dist/core/recovery/checkpoint.d.ts

@@ -0,0 +1,25 @@
+import type { BelayTransactionalConfig } from '../config.js';
+import type { TransactionalFileChange } from '../transactional/types.js';
+import { markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, type PreparedRecoveryCheckpoint, RECOVERY_CHECKPOINT_CORRUPT } from './artifact-store.js';
+import { reconcileRecoveryCheckpoint } from './reconcile.js';
+import { RECOVERY_RESTORE_CONFLICT, RECOVERY_RESTORE_REASON, recoveryRestoreBinding, restoreRecoveryCheckpoint } from './restore.js';
+import type { RecoveryBackend, RecoveryCheckpointSummary } from './types.js';
+export declare const RECOVERY_CHECKPOINT_QUOTA = "recovery_checkpoint_quota_exceeded";
+type CheckpointConfig = NonNullable<BelayTransactionalConfig['checkpoint']>;
+export declare function prepareRecoveryCheckpoint(params: {
+    stateDir: string;
+    repoRoot: string;
+    /** Immutable pre-command source for recovery blobs, when available. */
+    baselinePath?: string;
+    worktreePath: string;
+    commandFingerprint: string;
+    changes: TransactionalFileChange[];
+    protectedRoots?: string[];
+    config: CheckpointConfig;
+    backend?: RecoveryBackend;
+}): Promise<PreparedRecoveryCheckpoint>;
+export declare function discardPreparedRecoveryCheckpoint(stateDir: string, checkpointId: string): Promise<boolean>;
+export declare function listRecoveryCheckpoints(stateDir: string, repoRoot?: string): Promise<RecoveryCheckpointSummary[]>;
+export declare function recoveryCheckpointStorageBytes(stateDir: string, repoRoot?: string): Promise<number>;
+export declare function showRecoveryCheckpoint(stateDir: string, checkpointId: string, expectedRepoRoot?: string): Promise<import("./artifact-store.js").RecoveryArtifact>;
+export { markRecoveryCheckpointApplied, markRecoveryCheckpointApplying, RECOVERY_CHECKPOINT_CORRUPT, RECOVERY_RESTORE_CONFLICT, RECOVERY_RESTORE_REASON, reconcileRecoveryCheckpoint, recoveryRestoreBinding, restoreRecoveryCheckpoint, };