@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/core/judge-fallback-hints.js

@@ -0,0 +1,108 @@
+const INFRASTRUCTURE_FALLBACK_SUFFIXES = [
+    '_cli_nonzero',
+    '_cli_unavailable',
+    '_cli_parse_error',
+    '_cli_spawn_error',
+];
+const INFRASTRUCTURE_FALLBACK_REASONS = new Set([
+    'eval_timeout',
+    'connect_timeout',
+    'parse_timeout',
+    'session_unavailable',
+    'session_disabled',
+    'provider_not_allowlisted',
+    'guard_reset',
+    'kill_switch',
+    'non_json_response',
+    'parse_error',
+    'cli_error',
+    'timeout',
+    'version_mismatch',
+    'shadow_forced_spawn',
+    'unsafe_option_rejected',
+    'broker_busy_reset',
+]);
+function isInfrastructureFallbackReason(reason) {
+    if (INFRASTRUCTURE_FALLBACK_REASONS.has(reason)) {
+        return true;
+    }
+    return INFRASTRUCTURE_FALLBACK_SUFFIXES.some((suffix) => reason.endsWith(suffix));
+}
+function infrastructureSignal(signal) {
+    return isInfrastructureFallbackReason(signal);
+}
+export function extractJudgeFallbackReason(result) {
+    if (result.axes?.judgeFallbackReason) {
+        return result.axes.judgeFallbackReason;
+    }
+    return result.assessment.signals.find((signal) => isInfrastructureFallbackReason(signal));
+}
+export function isJudgeInfrastructureFailure(result) {
+    if (result.axes?.judgeProvider === 'fallback') {
+        return true;
+    }
+    const fallbackReason = extractJudgeFallbackReason(result);
+    if (fallbackReason && isInfrastructureFallbackReason(fallbackReason)) {
+        return true;
+    }
+    return result.assessment.signals.some(infrastructureSignal);
+}
+export function inferProviderIdFromFallbackReason(fallbackReason, fallbackProviderId = 'cursor') {
+    if (!fallbackReason) {
+        return fallbackProviderId;
+    }
+    const match = fallbackReason.match(/^(cursor|claude|codex)_/);
+    return match?.[1] ?? fallbackProviderId;
+}
+export function formatJudgeRecoveryHint(providerId, fallbackReason) {
+    if (!fallbackReason) {
+        return null;
+    }
+    if (fallbackReason.endsWith('_cli_nonzero') || fallbackReason.endsWith('_cli_unavailable')) {
+        switch (providerId) {
+            case 'cursor':
+                return 'Judge CLI is not authenticated. Run: agent login';
+            case 'claude':
+                return 'Claude CLI failed. Run: claude auth login';
+            case 'codex':
+                return 'Codex CLI failed. Check codex auth';
+            default:
+                return `Judge CLI transport failed (${fallbackReason}). Check ${providerId} CLI auth`;
+        }
+    }
+    if (fallbackReason.endsWith('_cli_parse_error')) {
+        return `Judge CLI returned an invalid response (${fallbackReason}). Retry after updating the ${providerId} CLI`;
+    }
+    if (fallbackReason.endsWith('_cli_spawn_error')) {
+        return `Judge CLI could not be started (${fallbackReason}). Install or repair the ${providerId} CLI`;
+    }
+    switch (fallbackReason) {
+        case 'eval_timeout':
+        case 'connect_timeout':
+        case 'parse_timeout':
+        case 'timeout':
+            return 'Judge timed out. Check network or increase judge.timeoutMs';
+        case 'session_unavailable':
+        case 'session_disabled':
+            return 'Judge session transport is unavailable. Run: belay doctor';
+        case 'kill_switch':
+            return 'Judge session kill switch is active. Run: belay judge status';
+        default:
+            if (isInfrastructureFallbackReason(fallbackReason)) {
+                return `Judge transport failed (${fallbackReason}). Run: belay doctor`;
+            }
+            return null;
+    }
+}
+export function formatJudgeInfrastructureDenyMessage(params) {
+    const fallbackReason = params.fallbackReason ?? 'judge_transport_unavailable';
+    const recoveryHint = formatJudgeRecoveryHint(params.providerId, fallbackReason) ??
+        'Judge transport is unavailable. Run: belay doctor';
+    const commandHint = params.command
+        ? ` For details: belay explain --command "${params.command}"`
+        : ' For details: belay explain';
+    return {
+        user_message: `Belay could not reach the Tier1 judge (${fallbackReason}). ${recoveryHint}. Then retry.${commandHint}`,
+        agent_message: `Belay denied this action because the Tier1 judge transport failed (${fallbackReason}). Repair judge infrastructure, then retry the exact same action.`,
+    };
+}

package/dist/core/network-endpoint.d.ts

@@ -0,0 +1,10 @@
+export interface NetworkEndpoint {
+    host: string;
+    port?: number;
+    protocol: string;
+}
+export interface NetworkEndpointParseOptions {
+    allowHostedGitShorthand?: boolean;
+    allowScpStyle?: boolean;
+}
+export declare function parseNetworkEndpoint(spec: string, options?: NetworkEndpointParseOptions): NetworkEndpoint | null;

package/dist/core/network-endpoint.js

@@ -0,0 +1,51 @@
+const SUPPORTED_URL_PROTOCOLS = new Set(['http:', 'https:', 'ssh:', 'git:']);
+const NON_NETWORK_COLON_PREFIXES = new Set([
+    'catalog',
+    'exec',
+    'file',
+    'link',
+    'npm',
+    'patch',
+    'portal',
+    'workspace',
+]);
+const HOSTED_GIT_PREFIXES = {
+    bitbucket: 'bitbucket.org',
+    github: 'github.com',
+    gitlab: 'gitlab.com',
+};
+export function parseNetworkEndpoint(spec, options = {}) {
+    const normalized = spec.trim().replace(/^git\+/, '');
+    if (options.allowHostedGitShorthand) {
+        const hostedGit = normalized.match(/^([a-z]+):(.+)$/i);
+        const hostedGitHost = hostedGit?.[1]
+            ? HOSTED_GIT_PREFIXES[hostedGit[1].toLowerCase()]
+            : undefined;
+        if (hostedGitHost && hostedGit?.[2]) {
+            return { host: hostedGitHost, protocol: 'git' };
+        }
+    }
+    try {
+        const url = new URL(normalized);
+        if (SUPPORTED_URL_PROTOCOLS.has(url.protocol) && url.hostname) {
+            return {
+                host: url.hostname,
+                ...(url.port ? { port: Number(url.port) } : {}),
+                protocol: url.protocol.slice(0, -1),
+            };
+        }
+    }
+    catch { }
+    if (!options.allowScpStyle || /^[A-Za-z]:[\\/]/.test(normalized)) {
+        return null;
+    }
+    const scpStyle = normalized.match(/^(?:([^@/\s:]+)@)?([^:/\s]+):(.+)$/);
+    if (!scpStyle) {
+        return null;
+    }
+    const [, , host, remotePath] = scpStyle;
+    if (!host || !remotePath || NON_NETWORK_COLON_PREFIXES.has(host.toLowerCase())) {
+        return null;
+    }
+    return { host: host.toLowerCase(), protocol: 'ssh' };
+}

package/dist/core/path-utils.d.ts

@@ -5,6 +5,7 @@
  * fs-scope allowlist matching).
  */
 export declare function canonicalPath(targetPath: string): string;
+export declare function isPathOutsideRoot(relativePath: string): boolean;
 export declare function pathWithinRoot(root: string, targetPath: string): boolean;
 export declare function relativeWithinRepo(repoRoot: string, targetPath: string): string | null;
 export type WorkspaceRootMatch = {

package/dist/core/path-utils.js

@@ -36,6 +36,9 @@ export function canonicalPath(targetPath) {
     }
     return current;
 }
+export function isPathOutsideRoot(relativePath) {
+    return relativePath === '..' || relativePath.startsWith(`..${path.sep}`);
+}
 export function pathWithinRoot(root, targetPath) {
     const resolvedRoot = canonicalPath(root);
     const resolvedTarget = canonicalPath(targetPath);
@@ -43,7 +46,7 @@ export function pathWithinRoot(root, targetPath) {
     if (relativePath === '') {
         return true;
     }
-    return !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+    return !isPathOutsideRoot(relativePath) && !path.isAbsolute(relativePath);
 }
 function relativeWithinRoot(root, targetPath, options = {}) {
     const resolvedRoot = options.canonicalizeRoot === false ? path.resolve(root) : canonicalPath(root);
@@ -52,7 +55,7 @@ function relativeWithinRoot(root, targetPath, options = {}) {
     if (relativePath === '') {
         return '.';
     }
-    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    if (isPathOutsideRoot(relativePath) || path.isAbsolute(relativePath)) {
         return null;
     }
     return relativePath;

package/dist/core/process-runner.d.ts

@@ -0,0 +1,10 @@
+import { type SpawnOptionsWithoutStdio } from 'node:child_process';
+export interface ShellRunResult {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    stdout?: string;
+    stderr?: string;
+}
+export declare function windowsProcessTreeKillArgs(pid: number): string[];
+export declare function runProcessWithBoundedOutput(file: string, args: string[], options: SpawnOptionsWithoutStdio, timeoutMs: number): Promise<ShellRunResult>;

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>;