@guilz-dev/belay 0.6.0 → 0.7.0

package/dist/core/transactional/file-clone.js

@@ -0,0 +1,139 @@
+import { constants as fsConstants } from 'node:fs';
+import { copyFile, lstat, mkdir, mkdtemp, readlink, rm, symlink, utimes, writeFile, } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { buildFileTreeIndex, FILE_CHECKPOINT_QUOTA_EXCEEDED, FileCheckpointDiagnosticError, } from './file-tree.js';
+import { compareRelativePathsBytewise, joinRelativePath } from './file-tree-path.js';
+export const FILE_CHECKPOINT_COPY_FAILED = 'file_checkpoint_copy_failed';
+async function chmodSafe(target, mode) {
+    try {
+        const { chmod } = await import('node:fs/promises');
+        await chmod(target, mode & 0o777);
+    }
+    catch {
+        // best effort
+    }
+}
+async function copyRegularFile(sourcePath, destinationPath, mode, strategy) {
+    await mkdir(path.dirname(destinationPath), { recursive: true });
+    if (strategy === 'clonefile' && fsConstants.COPYFILE_FICLONE !== undefined) {
+        try {
+            await copyFile(sourcePath, destinationPath, fsConstants.COPYFILE_FICLONE);
+            await chmodSafe(destinationPath, mode);
+            return 'clonefile';
+        }
+        catch {
+            await copyFile(sourcePath, destinationPath);
+            await chmodSafe(destinationPath, mode);
+            return 'copy';
+        }
+    }
+    await copyFile(sourcePath, destinationPath);
+    await chmodSafe(destinationPath, mode);
+    return strategy;
+}
+async function copyNode(sourceRoot, destinationRoot, relativePath, strategy) {
+    const sourcePath = joinRelativePath(sourceRoot, relativePath);
+    const destinationPath = joinRelativePath(destinationRoot, relativePath);
+    const info = await lstat(sourcePath);
+    await rm(destinationPath, { force: true, recursive: false });
+    if (info.isDirectory() && !info.isSymbolicLink()) {
+        await mkdir(destinationPath, { recursive: true, mode: info.mode & 0o777 });
+        return strategy;
+    }
+    if (info.isSymbolicLink()) {
+        await mkdir(path.dirname(destinationPath), { recursive: true });
+        await symlink(await readlink(sourcePath), destinationPath);
+        return strategy;
+    }
+    if (!info.isFile()) {
+        throw new Error(FILE_CHECKPOINT_COPY_FAILED);
+    }
+    const usedStrategy = await copyRegularFile(sourcePath, destinationPath, info.mode, strategy);
+    try {
+        await utimes(destinationPath, info.atime, info.mtime);
+    }
+    catch {
+        // best effort
+    }
+    return usedStrategy;
+}
+export async function cloneDirectoryTree(sourceRoot, destinationRoot, options = {}) {
+    const sourceIndex = await buildFileTreeIndex({
+        resourceRoot: sourceRoot,
+        excludedRoots: options.excludedRoots,
+        quotas: options.quotas,
+        deadlineMs: options.deadlineMs,
+    });
+    if (options.quotas && sourceIndex.totalFileBytes * 2 > options.quotas.maxWorkspaceBytes) {
+        throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_QUOTA_EXCEEDED, `estimated workspaceBytes=${sourceIndex.totalFileBytes * 2} exceeds maxWorkspaceBytes=${options.quotas.maxWorkspaceBytes}`);
+    }
+    const sortedPaths = [...sourceIndex.entries]
+        .map((entry) => entry.relativePath)
+        .sort(compareRelativePathsBytewise);
+    const concurrency = options.quotas?.copyConcurrency ?? 1;
+    const strategyState = { value: 'clonefile' };
+    await mapWithConcurrency(sortedPaths, concurrency, async (relativePath) => {
+        const used = await copyNode(sourceRoot, destinationRoot, relativePath, strategyState.value);
+        if (used === 'copy') {
+            strategyState.value = 'copy';
+        }
+    });
+    return { strategy: strategyState.value, sourceIndex };
+}
+async function mapWithConcurrency(items, concurrency, worker) {
+    if (items.length === 0) {
+        return;
+    }
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    let nextIndex = 0;
+    async function runWorker() {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            await worker(items[index]);
+        }
+    }
+    await Promise.all(Array.from({ length: limit }, () => runWorker()));
+}
+export async function probeFileCloneStrategy() {
+    let tempDir = null;
+    try {
+        tempDir = await mkdtemp(path.join(os.tmpdir(), 'belay-clone-probe-'));
+        const source = path.join(tempDir, 'source.txt');
+        const destination = path.join(tempDir, 'dest.txt');
+        await writeFile(source, 'probe\n');
+        if (fsConstants.COPYFILE_FICLONE_FORCE !== undefined) {
+            try {
+                await copyFile(source, destination, fsConstants.COPYFILE_FICLONE_FORCE);
+                return 'clonefile';
+            }
+            catch {
+                // fall through to clonefile or copy
+            }
+        }
+        if (fsConstants.COPYFILE_FICLONE !== undefined) {
+            try {
+                await copyFile(source, destination, fsConstants.COPYFILE_FICLONE);
+                return 'clonefile';
+            }
+            catch {
+                return 'copy';
+            }
+        }
+        return 'copy';
+    }
+    catch {
+        return 'copy';
+    }
+    finally {
+        if (tempDir) {
+            try {
+                await rm(tempDir, { recursive: true, force: true });
+            }
+            catch {
+                // best effort cleanup
+            }
+        }
+    }
+}

package/dist/core/transactional/file-tree-path.d.ts

@@ -0,0 +1,7 @@
+export declare const FILE_CHECKPOINT_PATH_ESCAPE = "file_checkpoint_path_escape";
+export declare function validateRelativePath(relativePath: string): void;
+export declare function joinRelativePath(root: string, relativePath: string): string;
+export declare function isRootGitMetadataPath(relativePath: string): boolean;
+export declare function isNestedGitPath(relativePath: string): boolean;
+export declare function isExcludedTreePath(relativePath: string, excludedRoots: string[], resourceRoot: string): boolean;
+export declare function compareRelativePathsBytewise(left: string, right: string): number;

package/dist/core/transactional/file-tree-path.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { canonicalPath, isPathOutsideRoot, pathWithinRoot } from '../path-utils.js';
+export const FILE_CHECKPOINT_PATH_ESCAPE = 'file_checkpoint_path_escape';
+export function validateRelativePath(relativePath) {
+    if (!relativePath || relativePath.includes('\0')) {
+        throw new Error(FILE_CHECKPOINT_PATH_ESCAPE);
+    }
+    if (path.isAbsolute(relativePath)) {
+        throw new Error(FILE_CHECKPOINT_PATH_ESCAPE);
+    }
+    if (isPathOutsideRoot(relativePath)) {
+        throw new Error(FILE_CHECKPOINT_PATH_ESCAPE);
+    }
+    const normalized = path.normalize(relativePath);
+    if (normalized === '..' || normalized.startsWith(`..${path.sep}`)) {
+        throw new Error(FILE_CHECKPOINT_PATH_ESCAPE);
+    }
+}
+export function joinRelativePath(root, relativePath) {
+    validateRelativePath(relativePath);
+    return path.join(canonicalPath(root), relativePath);
+}
+export function isRootGitMetadataPath(relativePath) {
+    return relativePath === '.git' || relativePath.startsWith(`.git${path.sep}`);
+}
+export function isNestedGitPath(relativePath) {
+    const segments = relativePath.split(path.sep).filter(Boolean);
+    if (segments.length === 0) {
+        return false;
+    }
+    if (segments[0] === '.git') {
+        return false;
+    }
+    return segments.includes('.git');
+}
+export function isExcludedTreePath(relativePath, excludedRoots, resourceRoot) {
+    if (isRootGitMetadataPath(relativePath)) {
+        return true;
+    }
+    if (excludedRoots.length === 0) {
+        return false;
+    }
+    const absolutePath = joinRelativePath(resourceRoot, relativePath);
+    return excludedRoots.some((root) => pathWithinRoot(root, absolutePath) ||
+        root === absolutePath ||
+        pathWithinRoot(absolutePath, root));
+}
+export function compareRelativePathsBytewise(left, right) {
+    return Buffer.from(left, 'utf8').compare(Buffer.from(right, 'utf8'));
+}

package/dist/core/transactional/file-tree.d.ts

@@ -0,0 +1,41 @@
+import type { BelayFileCheckpointConfig } from '../config.js';
+import type { PresentSnapshotNode, SnapshotNode } from './snapshot-node.js';
+import type { TransactionalFileChangeKind } from './types.js';
+export declare const FILE_CHECKPOINT_HARDLINK_UNSUPPORTED = "file_checkpoint_hardlink_unsupported";
+export declare const FILE_CHECKPOINT_UNSUPPORTED_NODE = "file_checkpoint_unsupported_node";
+export declare const FILE_CHECKPOINT_NESTED_REPOSITORY = "file_checkpoint_nested_repository";
+export declare const FILE_CHECKPOINT_QUOTA_EXCEEDED = "file_checkpoint_quota_exceeded";
+export declare const FILE_CHECKPOINT_PREPARE_TIMEOUT = "file_checkpoint_prepare_timeout";
+export declare class FileCheckpointDiagnosticError extends Error {
+    readonly diagnostic: string;
+    constructor(message: string, diagnostic: string);
+}
+export interface FileTreeEntry {
+    relativePath: string;
+    node: PresentSnapshotNode;
+}
+export interface FileTreeIndex {
+    version: 1;
+    entries: FileTreeEntry[];
+    treeHash: string;
+    fileCount: number;
+    directoryCount: number;
+    totalFileBytes: number;
+}
+export interface ObservedFileChange {
+    relativePath: string;
+    kind: TransactionalFileChangeKind;
+    before: SnapshotNode;
+    after: SnapshotNode;
+}
+export interface FileTreeBuildOptions {
+    resourceRoot: string;
+    excludedRoots?: string[];
+    quotas?: Pick<BelayFileCheckpointConfig, 'maxFiles' | 'maxSourceBytes' | 'prepareTimeoutMs'>;
+    deadlineMs?: number;
+}
+export declare function computeTreeHash(entries: FileTreeEntry[]): string;
+export declare function buildFileTreeIndex(options: FileTreeBuildOptions): Promise<FileTreeIndex>;
+export declare function diffFileTreeIndices(baseline: FileTreeIndex, observed: FileTreeIndex): ObservedFileChange[];
+export declare function readObservedChanges(baselineRoot: string, executionRoot: string, relativePaths: string[]): Promise<ObservedFileChange[]>;
+export { hashFileContent, hashFileNode, hashSymlinkTarget } from './snapshot-node.js';

package/dist/core/transactional/file-tree.js

@@ -0,0 +1,186 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { compareRelativePathsBytewise, isExcludedTreePath, isNestedGitPath, joinRelativePath, validateRelativePath, } from './file-tree-path.js';
+import { hashDirectoryNode, readSnapshotNode, snapshotNodesEqual } from './snapshot-node.js';
+export const FILE_CHECKPOINT_HARDLINK_UNSUPPORTED = 'file_checkpoint_hardlink_unsupported';
+export const FILE_CHECKPOINT_UNSUPPORTED_NODE = 'file_checkpoint_unsupported_node';
+export const FILE_CHECKPOINT_NESTED_REPOSITORY = 'file_checkpoint_nested_repository';
+export const FILE_CHECKPOINT_QUOTA_EXCEEDED = 'file_checkpoint_quota_exceeded';
+export const FILE_CHECKPOINT_PREPARE_TIMEOUT = 'file_checkpoint_prepare_timeout';
+export class FileCheckpointDiagnosticError extends Error {
+    diagnostic;
+    constructor(message, diagnostic) {
+        super(message);
+        this.diagnostic = diagnostic;
+        this.name = 'FileCheckpointDiagnosticError';
+    }
+}
+function assertWithinDeadline(deadlineMs) {
+    if (deadlineMs !== undefined && Date.now() > deadlineMs) {
+        throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_PREPARE_TIMEOUT, `snapshot preparation exceeded deadlineMs=${deadlineMs}`);
+    }
+}
+function assertWithinQuotas(counters, quotas) {
+    if (!quotas) {
+        return;
+    }
+    const nodeCount = counters.fileCount + counters.directoryCount;
+    if (nodeCount > quotas.maxFiles) {
+        throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_QUOTA_EXCEEDED, `snapshot nodeCount=${nodeCount} exceeds maxFiles=${quotas.maxFiles}`);
+    }
+    if (counters.totalFileBytes > quotas.maxSourceBytes) {
+        throw new FileCheckpointDiagnosticError(FILE_CHECKPOINT_QUOTA_EXCEEDED, `snapshot sourceBytes=${counters.totalFileBytes} exceeds maxSourceBytes=${quotas.maxSourceBytes}`);
+    }
+}
+async function readPresentNode(absolutePath, counters) {
+    const info = await lstat(absolutePath);
+    if (info.nlink > 1 && info.isFile()) {
+        throw new Error(FILE_CHECKPOINT_HARDLINK_UNSUPPORTED);
+    }
+    if (info.isSocket() || info.isFIFO() || info.isBlockDevice() || info.isCharacterDevice()) {
+        throw new Error(FILE_CHECKPOINT_UNSUPPORTED_NODE);
+    }
+    const node = await readSnapshotNode(absolutePath);
+    if (node.kind === 'absent') {
+        throw new Error(FILE_CHECKPOINT_UNSUPPORTED_NODE);
+    }
+    if (node.kind === 'file') {
+        counters.fileCount += 1;
+        counters.totalFileBytes += node.size;
+    }
+    else if (node.kind === 'directory') {
+        counters.directoryCount += 1;
+    }
+    else {
+        counters.fileCount += 1;
+    }
+    return node;
+}
+async function walkDirectory(resourceRoot, relativeDir, excludedRoots, counters, quotas, deadlineMs, entries) {
+    assertWithinDeadline(deadlineMs);
+    assertWithinQuotas(counters, quotas);
+    const absoluteDir = relativeDir
+        ? joinRelativePath(resourceRoot, relativeDir)
+        : path.resolve(resourceRoot);
+    const dirInfo = await lstat(absoluteDir);
+    if (!dirInfo.isDirectory()) {
+        throw new Error(FILE_CHECKPOINT_UNSUPPORTED_NODE);
+    }
+    if (relativeDir) {
+        validateRelativePath(relativeDir);
+        if (isNestedGitPath(relativeDir)) {
+            throw new Error(FILE_CHECKPOINT_NESTED_REPOSITORY);
+        }
+        if (!isExcludedTreePath(relativeDir, excludedRoots, resourceRoot)) {
+            entries.push({
+                relativePath: relativeDir,
+                node: {
+                    kind: 'directory',
+                    mode: dirInfo.mode,
+                    hash: hashDirectoryNode(dirInfo.mode),
+                },
+            });
+            counters.directoryCount += 1;
+            assertWithinQuotas(counters, quotas);
+        }
+    }
+    const names = await readdir(absoluteDir);
+    for (const name of names) {
+        assertWithinDeadline(deadlineMs);
+        const childRelative = relativeDir ? path.join(relativeDir, name) : name;
+        validateRelativePath(childRelative);
+        if (isNestedGitPath(childRelative)) {
+            throw new Error(FILE_CHECKPOINT_NESTED_REPOSITORY);
+        }
+        if (isExcludedTreePath(childRelative, excludedRoots, resourceRoot)) {
+            continue;
+        }
+        const childAbsolute = path.join(absoluteDir, name);
+        const childInfo = await lstat(childAbsolute);
+        if (childInfo.isDirectory() && !childInfo.isSymbolicLink()) {
+            await walkDirectory(resourceRoot, childRelative, excludedRoots, counters, quotas, deadlineMs, entries);
+            continue;
+        }
+        const node = await readPresentNode(childAbsolute, counters);
+        entries.push({ relativePath: childRelative, node });
+        assertWithinQuotas(counters, quotas);
+    }
+}
+export function computeTreeHash(entries) {
+    const sorted = [...entries].sort((left, right) => compareRelativePathsBytewise(left.relativePath, right.relativePath));
+    const hash = createHash('sha256');
+    for (const entry of sorted) {
+        hash.update(entry.relativePath);
+        hash.update('\0');
+        hash.update(entry.node.hash);
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+export async function buildFileTreeIndex(options) {
+    const excludedRoots = options.excludedRoots ?? [];
+    const counters = { fileCount: 0, directoryCount: 0, totalFileBytes: 0 };
+    const deadlineMs = options.deadlineMs ??
+        (options.quotas?.prepareTimeoutMs ? Date.now() + options.quotas.prepareTimeoutMs : undefined);
+    const entries = [];
+    await walkDirectory(options.resourceRoot, '', excludedRoots, counters, options.quotas, deadlineMs, entries);
+    const sortedEntries = [...entries].sort((left, right) => compareRelativePathsBytewise(left.relativePath, right.relativePath));
+    return {
+        version: 1,
+        entries: sortedEntries,
+        treeHash: computeTreeHash(sortedEntries),
+        fileCount: counters.fileCount,
+        directoryCount: counters.directoryCount,
+        totalFileBytes: counters.totalFileBytes,
+    };
+}
+function inferChangeKind(before, after) {
+    if (before.kind === 'absent') {
+        return 'added';
+    }
+    if (after.kind === 'absent') {
+        return 'deleted';
+    }
+    return 'modified';
+}
+export function diffFileTreeIndices(baseline, observed) {
+    const baselineMap = new Map(baseline.entries.map((entry) => [entry.relativePath, entry.node]));
+    const observedMap = new Map(observed.entries.map((entry) => [entry.relativePath, entry.node]));
+    const paths = new Set([...baselineMap.keys(), ...observedMap.keys()]);
+    const changes = [];
+    for (const relativePath of [...paths].sort(compareRelativePathsBytewise)) {
+        const before = baselineMap.get(relativePath) ?? { kind: 'absent' };
+        const after = observedMap.get(relativePath) ?? { kind: 'absent' };
+        if (snapshotNodesEqual(before, after)) {
+            continue;
+        }
+        changes.push({
+            relativePath,
+            kind: inferChangeKind(before, after),
+            before,
+            after,
+        });
+    }
+    return changes;
+}
+export async function readObservedChanges(baselineRoot, executionRoot, relativePaths) {
+    const changes = [];
+    for (const relativePath of relativePaths) {
+        validateRelativePath(relativePath);
+        const before = await readSnapshotNode(joinRelativePath(baselineRoot, relativePath));
+        const after = await readSnapshotNode(joinRelativePath(executionRoot, relativePath));
+        if (snapshotNodesEqual(before, after)) {
+            continue;
+        }
+        changes.push({
+            relativePath,
+            kind: inferChangeKind(before, after),
+            before,
+            after,
+        });
+    }
+    return changes;
+}
+// Re-export for tests that need direct content hashing without full walk.
+export { hashFileContent, hashFileNode, hashSymlinkTarget } from './snapshot-node.js';

package/dist/core/transactional/git-worktree-backend.d.ts

@@ -0,0 +1,2 @@
+import type { TransactionalBackend } from './backend.js';
+export declare const gitWorktreeBackend: TransactionalBackend;

package/dist/core/transactional/git-worktree-backend.js

@@ -0,0 +1,50 @@
+import { collectWorktreeChanges, createGitWorktreeSnapshot, isDirtyWorktree, isGitWorktreeAvailable, } from './git-worktree.js';
+async function probeGitWorktreeBackend(context) {
+    if (!(await isGitWorktreeAvailable(context.repoRoot))) {
+        return {
+            eligible: false,
+            backend: 'git_worktree',
+            reason: 'git_worktree_unavailable',
+            signals: [],
+        };
+    }
+    if (await isDirtyWorktree(context.repoRoot, { ignoreRoots: context.dirtyIgnoreRoots })) {
+        return {
+            eligible: false,
+            backend: 'git_worktree',
+            reason: 'dirty_worktree',
+            signals: ['dirty_git_worktree'],
+        };
+    }
+    return {
+        eligible: true,
+        backend: 'git_worktree',
+        signals: ['clean_git_worktree'],
+    };
+}
+export const gitWorktreeBackend = {
+    id: 'git_worktree',
+    probe: probeGitWorktreeBackend,
+    async prepare(context) {
+        const probe = await probeGitWorktreeBackend(context);
+        if (!probe.eligible) {
+            throw new Error(probe.reason ?? 'git_worktree_unavailable');
+        }
+        const snapshot = await createGitWorktreeSnapshot(context.repoRoot, context.stateDir);
+        return {
+            backend: 'git_worktree',
+            resourceRoot: context.repoRoot,
+            executionRoot: snapshot.worktreePath,
+            resourceKind: 'git_repository',
+            resourceIdentity: '',
+            baselineTreeHash: '',
+            excludedRoots: context.dirtyIgnoreRoots ?? [],
+            async collectChanges() {
+                return collectWorktreeChanges(snapshot.worktreePath);
+            },
+            async cleanup() {
+                await snapshot.cleanup();
+            },
+        };
+    },
+};

package/dist/core/transactional/git-worktree.d.ts

@@ -1,20 +1,18 @@
-import type { TransactionalFileChange, TransactionalSnapshot } from './types.js';
-export declare const TRANSACTIONAL_APPLY_TOCTOU = "transactional_apply_toctou";
-export declare function hashRepoFile(filePath: string): Promise<string>;
-export declare function captureRepoFileHashes(repoRoot: string, changes: TransactionalFileChange[]): Promise<Map<string, string | null>>;
+import { type ShellRunResult } from '../process-runner.js';
+import { buildObservedChangesFromTransactional, TRANSACTIONAL_APPLY_ROLLBACK_FAILED, TRANSACTIONAL_APPLY_TOCTOU } from './apply-observed-changes.js';
+import type { GitWorktreeSnapshot, TransactionalFileChange } from './types.js';
+export { TRANSACTIONAL_APPLY_ROLLBACK_FAILED, TRANSACTIONAL_APPLY_TOCTOU };
 export declare function isGitWorktreeAvailable(repoRoot: string): Promise<boolean>;
 export declare function isDirtyWorktree(repoRoot: string, options?: {
     ignoreRoots?: string[];
 }): Promise<boolean>;
-export declare function createGitWorktreeSnapshot(repoRoot: string, _stateDir: string): Promise<TransactionalSnapshot>;
+export declare function createGitWorktreeSnapshot(repoRoot: string, _stateDir: string): Promise<GitWorktreeSnapshot>;
 export declare function resolveWorktreeCwd(repoRoot: string, worktreePath: string, cwd: string): string;
-export interface ShellRunResult {
-    exitCode: number | null;
-    signal: string | null;
-    timedOut: boolean;
-}
+export type { ShellRunResult } from '../process-runner.js';
 export declare function runShellCommand(command: string, cwd: string, timeoutMs: number): Promise<ShellRunResult>;
 export declare function collectWorktreeChanges(worktreePath: string): Promise<TransactionalFileChange[]>;
 export declare function applyWorktreeChanges(worktreePath: string, repoRoot: string, changes: TransactionalFileChange[], options?: {
-    baseHashes?: Map<string, string | null>;
+    /** Runs while rollback backups are still available. */
+    afterApply?: () => Promise<void>;
+    observedChanges?: Awaited<ReturnType<typeof buildObservedChangesFromTransactional>>;
 }): Promise<void>;