@guilz-dev/belay 0.1.0

package/dist/core/shell-unparseable.js

@@ -0,0 +1,96 @@
+/**
+ * Detects shell constructs that agent-belay cannot reliably parse (R1).
+ */
+export function detectUnparseableShell(command) {
+    if (hasProcessSubstitution(command)) {
+        return true;
+    }
+    if (hasSubshell(command)) {
+        return true;
+    }
+    if (hasBraceGroup(command)) {
+        return true;
+    }
+    if (hasUnclosedQuote(command)) {
+        return true;
+    }
+    if (hasUnbalancedDollarParen(command)) {
+        return true;
+    }
+    return false;
+}
+function hasProcessSubstitution(command) {
+    return /<\s*\(/.test(command);
+}
+function hasSubshell(command) {
+    const trimmed = command.trim();
+    if (trimmed.startsWith('(')) {
+        return true;
+    }
+    return /(?:^|[;&|]\s*)\(/.test(trimmed);
+}
+function hasBraceGroup(command) {
+    const stripped = command.replace(/'[^']*'|"[^"]*"/g, ' ');
+    return /\{\s*[^\s}]/.test(stripped) || /;\s*\}/.test(stripped);
+}
+function hasUnclosedQuote(command) {
+    let quote = null;
+    let escaping = false;
+    for (const char of command) {
+        if (escaping) {
+            escaping = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaping = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+        }
+    }
+    return quote !== null;
+}
+function hasUnbalancedDollarParen(command) {
+    let depth = 0;
+    let inSingle = false;
+    let inDouble = false;
+    let escaping = false;
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index];
+        if (escaping) {
+            escaping = false;
+            continue;
+        }
+        if (char === '\\' && (inSingle || inDouble)) {
+            escaping = true;
+            continue;
+        }
+        if (!inDouble && char === "'") {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (!inSingle && char === '"') {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (inSingle || inDouble) {
+            continue;
+        }
+        if (char === '$' && command[index + 1] === '(') {
+            depth += 1;
+            index += 1;
+            continue;
+        }
+        if (char === ')' && depth > 0) {
+            depth -= 1;
+        }
+    }
+    return depth > 0;
+}

package/dist/core/transactional/diff-evaluator.d.ts

@@ -0,0 +1,2 @@
+import type { TransactionalDiffContext, TransactionalDiffEvaluation, TransactionalFileChange } from './types.js';
+export declare function evaluateTransactionalDiff(changes: TransactionalFileChange[], ctx: TransactionalDiffContext): TransactionalDiffEvaluation;

package/dist/core/transactional/diff-evaluator.js

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import { matchesSensitivePath } from '../glob.js';
+import { canonicalPath, pathWithinRoot } from '../path-utils.js';
+function categorizeChange(change, ctx) {
+    const absolutePath = canonicalPath(path.join(ctx.repoRoot, change.relativePath));
+    if (!pathWithinRoot(ctx.repoRoot, absolutePath)) {
+        return 'repo_outside';
+    }
+    if (ctx.protectedRoots.some((root) => pathWithinRoot(root, absolutePath) || root === absolutePath)) {
+        return 'control_plane';
+    }
+    if (matchesSensitivePath(change.relativePath, ctx.sensitivePaths)) {
+        return 'sensitive_path';
+    }
+    return 'repo_local';
+}
+function observedAssessment(evaluation) {
+    const signals = ['transactional_observed'];
+    for (const category of evaluation.categories) {
+        if (category !== 'repo_local') {
+            signals.push(`observed_${category}`);
+        }
+    }
+    if (evaluation.deletedCount > 0) {
+        signals.push('observed_deletions');
+    }
+    if (evaluation.categories.includes('repo_outside') ||
+        evaluation.categories.includes('control_plane') ||
+        evaluation.categories.includes('sensitive_path')) {
+        return {
+            reversibility: 'irreversible',
+            external: evaluation.categories.includes('repo_outside'),
+            blastRadius: evaluation.categories.includes('control_plane')
+                ? 'agent-belay control plane'
+                : evaluation.categories.includes('repo_outside')
+                    ? 'outside the repository'
+                    : 'sensitive path',
+            confidence: 1,
+            signals,
+        };
+    }
+    if (evaluation.categories.includes('large_deletion')) {
+        return {
+            reversibility: 'irreversible',
+            external: false,
+            blastRadius: 'directory tree',
+            confidence: 1,
+            signals,
+        };
+    }
+    return {
+        reversibility: evaluation.deletedCount > 0 ? 'recoverable_with_cost' : 'reversible',
+        external: false,
+        blastRadius: evaluation.changes.length <= 1 ? 'single file' : 'this repository',
+        confidence: 1,
+        signals,
+    };
+}
+export function evaluateTransactionalDiff(changes, ctx) {
+    const categories = new Set();
+    const deletedCount = changes.filter((change) => change.kind === 'deleted').length;
+    for (const change of changes) {
+        categories.add(categorizeChange(change, ctx));
+    }
+    if (deletedCount > ctx.maxDeletionCount) {
+        categories.add('large_deletion');
+    }
+    const categoryList = [...categories];
+    const dangerous = categoryList.includes('repo_outside') ||
+        categoryList.includes('control_plane') ||
+        categoryList.includes('sensitive_path') ||
+        categoryList.includes('large_deletion');
+    const base = {
+        categories: categoryList,
+        changes,
+        deletedCount,
+        verdict: dangerous ? 'deny_pending_approval' : 'allow',
+        reason: dangerous ? 'transactional_observed_risk' : 'transactional_observed_safe',
+    };
+    return {
+        ...base,
+        assessment: observedAssessment(base),
+    };
+}

package/dist/core/transactional/eligibility.d.ts

@@ -0,0 +1,4 @@
+import type { BelayConfigV3 } from '../config.js';
+import type { GatedActionKind } from '../gate-contract.js';
+import type { ClassifyResult } from '../types.js';
+export declare function isTransactionalEligible(config: BelayConfigV3, kind: GatedActionKind, result: ClassifyResult): boolean;

package/dist/core/transactional/eligibility.js

@@ -0,0 +1,44 @@
+const EXCLUDED_REASONS = new Set([
+    'unparseable_shell',
+    'external_effect',
+    'l3_external_hint',
+    'custom_external',
+    'external_script',
+    'outside_repo_redirect',
+    'outside_repo_mutation',
+    'control_plane_mutation',
+    'dynamic_shell_evaluation',
+    'pipe_to_shell',
+    'command_substitution',
+    'agent_assessment_mismatch',
+    'find_dangerous_action',
+    'read_only',
+    'custom_allow',
+]);
+export function isTransactionalEligible(config, kind, result) {
+    const transactional = config.policy.transactional;
+    if (!transactional.enabled) {
+        return false;
+    }
+    if (kind !== 'shell' || !config.gates.shell || !transactional.gates.shell) {
+        return false;
+    }
+    if (EXCLUDED_REASONS.has(result.reason)) {
+        return false;
+    }
+    const { assessment } = result;
+    if (assessment.external) {
+        return false;
+    }
+    if (result.verdict === 'deny_pending_approval') {
+        return false;
+    }
+    if (result.verdict === 'allow' && assessment.confidence >= transactional.maxConfidence) {
+        return false;
+    }
+    const confidence = assessment.confidence;
+    if (confidence < transactional.minConfidence || confidence >= transactional.maxConfidence) {
+        return false;
+    }
+    return result.verdict === 'allow_flagged';
+}

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

@@ -0,0 +1,13 @@
+import type { TransactionalFileChange, TransactionalSnapshot } from './types.js';
+export declare function isGitWorktreeAvailable(repoRoot: string): Promise<boolean>;
+export declare function isDirtyWorktree(repoRoot: string): Promise<boolean>;
+export declare function createGitWorktreeSnapshot(repoRoot: string, stateDir: string): Promise<TransactionalSnapshot>;
+export declare function resolveWorktreeCwd(repoRoot: string, worktreePath: string, cwd: string): string;
+export interface ShellRunResult {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+}
+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[]): Promise<void>;

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

@@ -0,0 +1,189 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalPath } from '../path-utils.js';
+function execGit(repoRoot, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['-C', repoRoot, ...args], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => stdout.push(Buffer.from(chunk)));
+        child.stderr.on('data', (chunk) => stderr.push(Buffer.from(chunk)));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(Buffer.concat(stdout).toString('utf8'));
+                return;
+            }
+            reject(new Error(`git ${args.join(' ')} failed (${code}): ${Buffer.concat(stderr).toString('utf8').trim()}`));
+        });
+    });
+}
+export async function isGitWorktreeAvailable(repoRoot) {
+    try {
+        await execGit(repoRoot, ['rev-parse', '--git-dir']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function isDirtyWorktree(repoRoot) {
+    try {
+        const status = await execGit(repoRoot, ['status', '--porcelain', '--untracked-files=no']);
+        return status.trim().length > 0;
+    }
+    catch {
+        return true;
+    }
+}
+export async function createGitWorktreeSnapshot(repoRoot, stateDir) {
+    const worktreePath = path.join(stateDir, `tx-${randomUUID().replaceAll('-', '')}`);
+    await mkdir(stateDir, { recursive: true });
+    await execGit(repoRoot, ['worktree', 'add', '--detach', worktreePath, 'HEAD']);
+    return {
+        worktreePath,
+        cleanup: async () => {
+            try {
+                await execGit(repoRoot, ['worktree', 'remove', '--force', worktreePath]);
+            }
+            catch {
+                await rm(worktreePath, { recursive: true, force: true });
+                try {
+                    await execGit(repoRoot, ['worktree', 'prune']);
+                }
+                catch {
+                    // best effort
+                }
+            }
+        },
+    };
+}
+export function resolveWorktreeCwd(repoRoot, worktreePath, cwd) {
+    const resolvedCwd = canonicalPath(cwd);
+    const relative = path.relative(canonicalPath(repoRoot), resolvedCwd);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return worktreePath;
+    }
+    if (relative === '') {
+        return worktreePath;
+    }
+    return path.join(worktreePath, relative);
+}
+export function runShellCommand(command, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            stdio: 'ignore',
+            env: process.env,
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        child.on('error', () => {
+            clearTimeout(timer);
+            resolve({ exitCode: 1, signal: null, timedOut });
+        });
+        child.on('close', (exitCode, signal) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode,
+                signal: signal ? String(signal) : null,
+                timedOut,
+            });
+        });
+    });
+}
+function parseStatusLine(line) {
+    if (line.length < 4) {
+        return null;
+    }
+    const status = line.slice(0, 2);
+    const relativePath = line.slice(3).trim();
+    if (!relativePath) {
+        return null;
+    }
+    if (status.includes('D')) {
+        return { relativePath, kind: 'deleted' };
+    }
+    if (status === '??') {
+        return { relativePath, kind: 'added' };
+    }
+    if (status.includes('A') || status.includes('?')) {
+        return { relativePath, kind: 'added' };
+    }
+    return { relativePath, kind: 'modified' };
+}
+export async function collectWorktreeChanges(worktreePath) {
+    const status = await execGit(worktreePath, ['status', '--porcelain']);
+    const changes = [];
+    const seen = new Set();
+    for (const line of status.split('\n')) {
+        if (!line.trim()) {
+            continue;
+        }
+        const change = parseStatusLine(line);
+        if (!change || seen.has(change.relativePath)) {
+            continue;
+        }
+        seen.add(change.relativePath);
+        changes.push(change);
+    }
+    return changes;
+}
+async function rollbackAppliedChanges(actions) {
+    for (const action of [...actions].reverse()) {
+        try {
+            if (action.type === 'restore') {
+                await mkdir(path.dirname(action.target), { recursive: true });
+                await copyFile(action.backupPath, action.target);
+            }
+            else {
+                await rm(action.target, { force: true });
+            }
+        }
+        catch {
+            // best effort
+        }
+    }
+}
+export async function applyWorktreeChanges(worktreePath, repoRoot, changes) {
+    const backupRoot = await mkdtemp(path.join(os.tmpdir(), 'belay-tx-rollback-'));
+    const rollbackActions = [];
+    try {
+        for (const change of changes) {
+            const target = path.join(repoRoot, change.relativePath);
+            if (existsSync(target)) {
+                const backupPath = path.join(backupRoot, change.relativePath);
+                await mkdir(path.dirname(backupPath), { recursive: true });
+                await copyFile(target, backupPath);
+                rollbackActions.push({ type: 'restore', target, backupPath });
+            }
+            else if (change.kind !== 'deleted') {
+                rollbackActions.push({ type: 'remove', target });
+            }
+            if (change.kind === 'deleted') {
+                await rm(target, { force: true });
+                continue;
+            }
+            const source = path.join(worktreePath, change.relativePath);
+            await mkdir(path.dirname(target), { recursive: true });
+            await copyFile(source, target);
+        }
+    }
+    catch (error) {
+        await rollbackAppliedChanges(rollbackActions);
+        throw error;
+    }
+    finally {
+        await rm(backupRoot, { recursive: true, force: true });
+    }
+}

package/dist/core/transactional/index.d.ts

@@ -0,0 +1,5 @@
+export { evaluateTransactionalDiff } from './diff-evaluator.js';
+export { isTransactionalEligible } from './eligibility.js';
+export { TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, TRANSACTIONAL_OBSERVED_RISK, } from './reasons.js';
+export { runTransactionalExecution } from './runner.js';
+export type { TransactionalDiffEvaluation, TransactionalExecutionResult, TransactionalFileChange, TransactionalRunnerParams, } from './types.js';

package/dist/core/transactional/index.js

@@ -0,0 +1,4 @@
+export { evaluateTransactionalDiff } from './diff-evaluator.js';
+export { isTransactionalEligible } from './eligibility.js';
+export { TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, TRANSACTIONAL_OBSERVED_RISK, } from './reasons.js';
+export { runTransactionalExecution } from './runner.js';

package/dist/core/transactional/reasons.d.ts

@@ -0,0 +1,4 @@
+export declare const TRANSACTIONAL_ALREADY_APPLIED = "transactional_already_applied";
+export declare const TRANSACTIONAL_OBSERVED_RISK = "transactional_observed_risk";
+export declare const TRANSACTIONAL_APPLY_FAILED = "transactional_apply_failed";
+export declare const TRANSACTIONAL_APPROVAL_BYPASS_REASONS: Set<string>;

package/dist/core/transactional/reasons.js

@@ -0,0 +1,8 @@
+export const TRANSACTIONAL_ALREADY_APPLIED = 'transactional_already_applied';
+export const TRANSACTIONAL_OBSERVED_RISK = 'transactional_observed_risk';
+export const TRANSACTIONAL_APPLY_FAILED = 'transactional_apply_failed';
+export const TRANSACTIONAL_APPROVAL_BYPASS_REASONS = new Set([
+    TRANSACTIONAL_OBSERVED_RISK,
+    TRANSACTIONAL_ALREADY_APPLIED,
+    TRANSACTIONAL_APPLY_FAILED,
+]);

package/dist/core/transactional/runner.d.ts

@@ -0,0 +1,2 @@
+import type { TransactionalExecutionResult, TransactionalRunnerParams } from './types.js';
+export declare function runTransactionalExecution(params: TransactionalRunnerParams): Promise<TransactionalExecutionResult>;

package/dist/core/transactional/runner.js

@@ -0,0 +1,113 @@
+import { evaluateTransactionalDiff } from './diff-evaluator.js';
+import { applyWorktreeChanges, collectWorktreeChanges, createGitWorktreeSnapshot, isDirtyWorktree, isGitWorktreeAvailable, resolveWorktreeCwd, runShellCommand, } from './git-worktree.js';
+import { TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPLY_FAILED, TRANSACTIONAL_OBSERVED_RISK, } from './reasons.js';
+export async function runTransactionalExecution(params) {
+    const { predicted, repoRoot, stateDir, command, cwd, timeoutMs, diffContext } = params;
+    if (!(await isGitWorktreeAvailable(repoRoot))) {
+        return {
+            ok: false,
+            skipped: true,
+            skipReason: 'git_worktree_unavailable',
+            predicted,
+            result: predicted,
+        };
+    }
+    if (await isDirtyWorktree(repoRoot)) {
+        return {
+            ok: false,
+            skipped: true,
+            skipReason: 'dirty_worktree',
+            predicted,
+            result: predicted,
+        };
+    }
+    let snapshot = null;
+    try {
+        snapshot = await createGitWorktreeSnapshot(repoRoot, stateDir);
+        const execCwd = resolveWorktreeCwd(repoRoot, snapshot.worktreePath, cwd);
+        const shellResult = await runShellCommand(command, execCwd, timeoutMs);
+        if (shellResult.timedOut) {
+            return {
+                ok: false,
+                skipped: true,
+                skipReason: 'transactional_timed_out',
+                predicted,
+                result: predicted,
+                commandExitCode: shellResult.exitCode,
+                commandSignal: shellResult.signal,
+                timedOut: true,
+            };
+        }
+        if (shellResult.exitCode !== 0 && shellResult.exitCode !== null) {
+            return {
+                ok: false,
+                skipped: true,
+                skipReason: 'transactional_command_failed',
+                predicted,
+                result: predicted,
+                commandExitCode: shellResult.exitCode,
+                commandSignal: shellResult.signal,
+            };
+        }
+        const changes = await collectWorktreeChanges(snapshot.worktreePath);
+        const observed = evaluateTransactionalDiff(changes, diffContext);
+        if (observed.verdict === 'allow') {
+            try {
+                await applyWorktreeChanges(snapshot.worktreePath, repoRoot, changes);
+            }
+            catch {
+                const result = {
+                    ...predicted,
+                    verdict: 'deny_pending_approval',
+                    reason: TRANSACTIONAL_APPLY_FAILED,
+                    assessment: {
+                        ...observed.assessment,
+                        reversibility: 'irreversible',
+                        confidence: 1,
+                        signals: [...observed.assessment.signals, 'transactional_apply_failed'],
+                    },
+                };
+                return {
+                    ok: true,
+                    predicted,
+                    observed,
+                    result,
+                    worktreePath: snapshot.worktreePath,
+                    commandExitCode: shellResult.exitCode,
+                    commandSignal: shellResult.signal,
+                    timedOut: shellResult.timedOut,
+                };
+            }
+        }
+        const result = {
+            ...predicted,
+            verdict: observed.verdict === 'allow' ? 'allow' : 'deny_pending_approval',
+            reason: observed.verdict === 'allow' ? TRANSACTIONAL_ALREADY_APPLIED : TRANSACTIONAL_OBSERVED_RISK,
+            assessment: observed.assessment,
+        };
+        return {
+            ok: true,
+            predicted,
+            observed,
+            result,
+            worktreePath: snapshot.worktreePath,
+            commandExitCode: shellResult.exitCode,
+            commandSignal: shellResult.signal,
+            timedOut: shellResult.timedOut,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            skipped: true,
+            skipReason: error instanceof Error ? error.message : 'transactional_execution_failed',
+            predicted,
+            result: predicted,
+        };
+    }
+    finally {
+        if (snapshot) {
+            await snapshot.cleanup();
+        }
+    }
+}

package/dist/core/transactional/types.d.ts

@@ -0,0 +1,46 @@
+import type { Assessment, ClassifyResult, HookVerdict } from '../types.js';
+export type TransactionalFileChangeKind = 'added' | 'modified' | 'deleted';
+export interface TransactionalFileChange {
+    relativePath: string;
+    kind: TransactionalFileChangeKind;
+}
+export type TransactionalDiffCategory = 'repo_local' | 'repo_outside' | 'sensitive_path' | 'control_plane' | 'large_deletion';
+export interface TransactionalDiffEvaluation {
+    verdict: HookVerdict;
+    reason: string;
+    categories: TransactionalDiffCategory[];
+    changes: TransactionalFileChange[];
+    deletedCount: number;
+    assessment: Assessment;
+}
+export interface TransactionalExecutionResult {
+    ok: boolean;
+    skipped?: boolean;
+    skipReason?: string;
+    predicted: ClassifyResult;
+    observed?: TransactionalDiffEvaluation;
+    result: ClassifyResult;
+    worktreePath?: string;
+    commandExitCode?: number | null;
+    commandSignal?: string | null;
+    timedOut?: boolean;
+}
+export interface TransactionalSnapshot {
+    worktreePath: string;
+    cleanup: () => Promise<void>;
+}
+export interface TransactionalDiffContext {
+    repoRoot: string;
+    sensitivePaths: string[];
+    protectedRoots: string[];
+    maxDeletionCount: number;
+}
+export interface TransactionalRunnerParams {
+    command: string;
+    cwd: string;
+    repoRoot: string;
+    stateDir: string;
+    timeoutMs: number;
+    predicted: ClassifyResult;
+    diffContext: TransactionalDiffContext;
+}

package/dist/core/transactional/types.js

@@ -0,0 +1 @@
+export {};