@guilz-dev/belay 0.1.0

package/dist/core/recover-advice.js

@@ -0,0 +1,177 @@
+export const RECOVER_DISCLAIMER = [
+    'Advisory only — belay does not run recovery commands.',
+    '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.',
+];
+export const SHOW_DONT_RUN_LEAD = 'These steps may help undo the observed effect — confirm each step before running:';
+const IRREVERSIBLE_REASON_PREFIXES = ['tier0_'];
+const IRREVERSIBLE_REASONS = new Set([
+    'external_effect',
+    'exfiltration',
+    'force_push',
+    'remote_destructive',
+]);
+const DENIED_RECOVERY_PATTERNS = [
+    /reset\s+--hard/i,
+    /push\s+--force/i,
+    /clean\s+-[a-z]*f/i,
+    /dropdb\b/i,
+    /destroy\b/i,
+];
+export function containsDeniedRecoveryPattern(text) {
+    return DENIED_RECOVERY_PATTERNS.some((pattern) => pattern.test(text));
+}
+function isIrreversibleTarget(target) {
+    if (target.effect === 'external_effect') {
+        return true;
+    }
+    if (target.assessment?.reversibility === 'irreversible') {
+        return true;
+    }
+    if (target.assessment?.external) {
+        return true;
+    }
+    if (IRREVERSIBLE_REASONS.has(target.reason)) {
+        return true;
+    }
+    for (const prefix of IRREVERSIBLE_REASON_PREFIXES) {
+        if (target.reason.startsWith(prefix)) {
+            return true;
+        }
+    }
+    return false;
+}
+function extractPathHints(summary) {
+    const hints = new Set();
+    const patterns = [
+        /\b(?:git\s+)?restore\s+--\s+(\S+)/i,
+        /\b(?:git\s+)?checkout\s+--\s+(\S+)/i,
+        /\brm\s+(?:-[a-z]+\s+)*([^\s;&|]+)/i,
+        /\b(?:edit|write|delete)\s+(\S+)/i,
+    ];
+    for (const pattern of patterns) {
+        const match = summary.match(pattern);
+        if (match?.[1] && !match[1].startsWith('-')) {
+            hints.add(match[1]);
+        }
+    }
+    return [...hints];
+}
+function localMutationAdvice(target, git) {
+    const advice = [];
+    const paths = extractPathHints(target.summary);
+    if (git?.inWorkTree) {
+        if (paths.length > 0) {
+            for (const filePath of paths.slice(0, 3)) {
+                advice.push(`git restore -- ${filePath}`);
+            }
+        }
+        else {
+            advice.push('git status --porcelain  # inspect changed paths first');
+            advice.push('git restore -- <path>  # restore specific tracked files');
+        }
+        if (/commit/i.test(target.summary) || target.reason.includes('commit')) {
+            advice.push('git log -n 5  # identify the commit to revert');
+            advice.push('git revert <commit>  # prefer revert over reset for shared history');
+        }
+        if (git.reflog) {
+            advice.push('git reflog -n 10  # locate a prior HEAD if a local commit was lost');
+        }
+    }
+    else {
+        advice.push('Restore from version control or backups if the change was not committed.');
+        if (paths.length > 0) {
+            advice.push(`Check backups or trash for: ${paths.join(', ')}`);
+        }
+    }
+    return advice.filter((line) => !containsDeniedRecoveryPattern(line));
+}
+function isLowConfidenceAssessment(target, minAssessmentConfidence) {
+    if (typeof target.assessment?.confidence !== 'number' || minAssessmentConfidence === undefined) {
+        return false;
+    }
+    return target.assessment.confidence < minAssessmentConfidence;
+}
+const NO_COMMAND_ADVICE = {
+    low_assessment: [
+        'No reliable recovery path can be determined from the observed assessment confidence.',
+        'Review the audit entry and your VCS or backups manually before attempting undo steps.',
+    ],
+    insufficient_signal: [
+        'Insufficient signal to suggest a safe recovery path.',
+        'Review the audit entry and your VCS or backups manually before attempting undo steps.',
+    ],
+    no_safe_command: [
+        'No safe, specific recovery command can be suggested from the observed audit record.',
+        'Inspect git history, backups, or hosting provider recovery tools manually.',
+    ],
+};
+function noCommandRecoverResult(disclaimer, reason, extraWarnings = []) {
+    return {
+        recoverable: false,
+        confidence: 'medium',
+        disclaimer,
+        advice: NO_COMMAND_ADVICE[reason],
+        warnings: extraWarnings.length > 0
+            ? extraWarnings
+            : ['Low confidence — no specific recovery commands are suggested.'],
+    };
+}
+export function buildRecoverAdvice(input) {
+    const { target, git, minAssessmentConfidence } = input;
+    const warnings = [];
+    const disclaimer = [...RECOVER_DISCLAIMER];
+    if (isIrreversibleTarget(target)) {
+        return {
+            recoverable: false,
+            confidence: 'high',
+            disclaimer,
+            advice: [
+                'This action is likely not recoverable through local undo.',
+                'External or irreversible effects (publish, remote delete, force-push, exfiltration, etc.) cannot be reliably reversed.',
+                'Treat this as incident response: revoke credentials, notify stakeholders, and follow your org runbook.',
+            ],
+            warnings: [
+                'Belay blocked this because it looked catastrophic and irreversible — do not expect a safe automatic undo.',
+            ],
+        };
+    }
+    if (target.effect === 'read_only') {
+        return {
+            recoverable: true,
+            confidence: 'high',
+            disclaimer,
+            advice: ['No local mutation was recorded — there may be nothing to undo.'],
+            warnings: [],
+        };
+    }
+    if (isLowConfidenceAssessment(target, minAssessmentConfidence)) {
+        return noCommandRecoverResult(disclaimer, 'low_assessment');
+    }
+    const advice = [SHOW_DONT_RUN_LEAD];
+    if (target.effect === 'local_mutation' ||
+        target.assessment?.reversibility === 'recoverable_with_cost') {
+        advice.push(...localMutationAdvice(target, git));
+    }
+    else if (inferWouldBlockFromTarget(target)) {
+        advice.push(...localMutationAdvice(target, git));
+        warnings.push('Effect axis was unclear — showing conservative file/git guidance only.');
+    }
+    else {
+        return noCommandRecoverResult(disclaimer, 'insufficient_signal');
+    }
+    const filteredAdvice = advice.filter((line) => !containsDeniedRecoveryPattern(line));
+    if (filteredAdvice.length <= 1) {
+        return noCommandRecoverResult(disclaimer, 'no_safe_command', warnings);
+    }
+    return {
+        recoverable: true,
+        confidence: git?.inWorkTree ? 'high' : 'medium',
+        disclaimer,
+        advice: filteredAdvice,
+        warnings,
+    };
+}
+function inferWouldBlockFromTarget(target) {
+    return target.permission === 'ask' || target.reason === 'unknown_local_effect';
+}

package/dist/core/recover-git-probe.d.ts

@@ -0,0 +1,8 @@
+export interface GitProbeResult {
+    inWorkTree: boolean;
+    porcelain?: string;
+    reflog?: string;
+    notes: string[];
+}
+export declare function isReadOnlyGitProbe(commandKey: string): boolean;
+export declare function probeGitState(repoRoot: string): Promise<GitProbeResult>;

package/dist/core/recover-git-probe.js

@@ -0,0 +1,50 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const GIT_PROBE_TIMEOUT_MS = 5_000;
+const READ_ONLY_GIT_COMMANDS = new Set([
+    'rev-parse --is-inside-work-tree',
+    'status --porcelain',
+    'reflog -n 10',
+]);
+export function isReadOnlyGitProbe(commandKey) {
+    return READ_ONLY_GIT_COMMANDS.has(commandKey);
+}
+async function runGit(repoRoot, args) {
+    try {
+        const { stdout } = await execFileAsync('git', args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: 1024 * 1024,
+            timeout: GIT_PROBE_TIMEOUT_MS,
+        });
+        return { ok: true, stdout: stdout.trimEnd() };
+    }
+    catch {
+        return { ok: false, stdout: '' };
+    }
+}
+export async function probeGitState(repoRoot) {
+    const notes = [];
+    const workTree = await runGit(repoRoot, ['rev-parse', '--is-inside-work-tree']);
+    if (!workTree.ok || workTree.stdout !== 'true') {
+        return {
+            inWorkTree: false,
+            notes: ['Not a git work tree — file-level git restore advice may not apply.'],
+        };
+    }
+    const status = await runGit(repoRoot, ['status', '--porcelain']);
+    if (status.ok) {
+        notes.push('Read git status (porcelain) for context.');
+    }
+    const reflog = await runGit(repoRoot, ['reflog', '-n', '10']);
+    if (reflog.ok) {
+        notes.push('Read recent reflog entries for context.');
+    }
+    return {
+        inWorkTree: true,
+        porcelain: status.ok ? status.stdout : undefined,
+        reflog: reflog.ok ? reflog.stdout : undefined,
+        notes,
+    };
+}

package/dist/core/recover-select.d.ts

@@ -0,0 +1,10 @@
+import type { AuditRecord } from './audit-types.js';
+import type { RecoverTargetInput } from './recover-advice.js';
+export interface RecoverSelectOptions {
+    since?: string;
+    fingerprint?: string;
+    limit?: number;
+}
+export declare function recoverCandidatePriority(record: AuditRecord): number;
+export declare function recordToRecoverTarget(record: AuditRecord): RecoverTargetInput;
+export declare function selectRecoverTarget(records: AuditRecord[], options?: RecoverSelectOptions): RecoverTargetInput | null;

package/dist/core/recover-select.js

@@ -0,0 +1,60 @@
+import { filterAuditRecords, inferWouldBlock, isApprovalRecorded, isGateRecord, isSilentPassRecord, parseTimestamp, recordStringField, } from './audit-query.js';
+function isRecoverCandidate(record) {
+    if (!isGateRecord(record) || isApprovalRecorded(record)) {
+        return false;
+    }
+    if (inferWouldBlock(record)) {
+        return true;
+    }
+    const effect = recordStringField(record, 'effect');
+    return effect === 'local_mutation' || effect === 'external_effect';
+}
+export function recoverCandidatePriority(record) {
+    const effect = recordStringField(record, 'effect');
+    if (effect === 'local_mutation') {
+        return isSilentPassRecord(record) ? 0 : 1;
+    }
+    if (inferWouldBlock(record) || effect === 'external_effect') {
+        return 2;
+    }
+    return 3;
+}
+function compareRecoverCandidates(left, right) {
+    const priorityDelta = recoverCandidatePriority(left) - recoverCandidatePriority(right);
+    if (priorityDelta !== 0) {
+        return priorityDelta;
+    }
+    const leftMs = parseTimestamp(left.timestamp) ?? 0;
+    const rightMs = parseTimestamp(right.timestamp) ?? 0;
+    return rightMs - leftMs;
+}
+export function recordToRecoverTarget(record) {
+    return {
+        timestamp: record.timestamp,
+        fingerprint: recordStringField(record, 'fingerprint') || undefined,
+        summary: recordStringField(record, 'summary'),
+        reason: recordStringField(record, 'reason') || 'unknown',
+        effect: recordStringField(record, 'effect') || undefined,
+        location: recordStringField(record, 'location') || undefined,
+        permission: recordStringField(record, 'permission') || undefined,
+        assessment: record.assessment,
+    };
+}
+export function selectRecoverTarget(records, options = {}) {
+    const filtered = filterAuditRecords(records, {
+        since: options.since,
+        fingerprint: options.fingerprint,
+    });
+    const candidates = filtered.filter(isRecoverCandidate);
+    if (candidates.length === 0) {
+        return null;
+    }
+    candidates.sort(compareRecoverCandidates);
+    const limit = options.limit ?? 1;
+    const index = Math.min(limit, candidates.length) - 1;
+    const selected = candidates[index] ?? candidates[0];
+    if (!selected) {
+        return null;
+    }
+    return recordToRecoverTarget(selected);
+}

package/dist/core/scrub.d.ts

@@ -0,0 +1,3 @@
+import type { ScrubOptions } from './types.js';
+export declare function scrubString(value: string, options?: ScrubOptions): string;
+export declare function scrubValue(value: unknown, options?: ScrubOptions): unknown;

package/dist/core/scrub.js

@@ -0,0 +1,87 @@
+const UUID_PATTERN = /\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi;
+const TIMESTAMP_PATTERN = /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\b/g;
+const APPROVAL_ID_PATTERN = /\bbelay_[a-z0-9]{8,}\b/gi;
+const TOKEN_PREFIX_PATTERN = /\/belay-approve\s+\S+/gi;
+const BEARER_PATTERN = /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/gi;
+const AUTH_HEADER_PATTERN = /(?<!["'])\bAuthorization:\s*(?:Bearer|Basic|Token)?\s*\S+/gi;
+const DOUBLE_QUOTED_AUTH_HEADER_PATTERN = /"Authorization:\s*[^"]*"/gi;
+const SINGLE_QUOTED_AUTH_HEADER_PATTERN = /'Authorization:\s*[^']*'/gi;
+const GENERIC_AUTH_HEADER_PATTERN = /(?<!["'])\b(?:X-Api-Key|X-Auth-Token|Private-Token):\s*\S+/gi;
+const DOUBLE_QUOTED_GENERIC_AUTH_HEADER_PATTERN = /"(X-Api-Key|X-Auth-Token|Private-Token):\s*[^"]*"/gi;
+const SINGLE_QUOTED_GENERIC_AUTH_HEADER_PATTERN = /'(X-Api-Key|X-Auth-Token|Private-Token):\s*[^']*'/gi;
+const KEY_VALUE_SECRET_PATTERN = /\b(api[_-]?key|token|secret|password|passwd|credential)\b\s*[:=]\s*['"]?[^\s'"]{4,}/gi;
+const URL_CREDENTIALS_PATTERN = /\b([A-Za-z][A-Za-z0-9+.-]*:\/\/)([^/\s:@]+):([^@\s/]+)@/g;
+const MYSQL_INLINE_PASSWORD_PATTERN = /(\s-p)([^\s]+)/g;
+const HIGH_ENTROPY_PATTERN = /\b[A-Za-z0-9+/]{40,}={0,2}\b/g;
+const DEFAULT_SCRUB_OPTIONS = {
+    maskApprovalIds: true,
+    maskBearerTokens: true,
+    maskAuthHeaders: true,
+    maskKeyValueSecrets: true,
+    maskHighEntropyStrings: true,
+};
+function resolvedScrubOptions(options = {}) {
+    return {
+        maskApprovalIds: options.maskApprovalIds !== false,
+        maskBearerTokens: options.maskBearerTokens !== false,
+        maskAuthHeaders: options.maskAuthHeaders !== false,
+        maskKeyValueSecrets: options.maskKeyValueSecrets !== false,
+        maskHighEntropyStrings: options.maskHighEntropyStrings === true,
+    };
+}
+export function scrubString(value, options = {}) {
+    const resolved = resolvedScrubOptions(options);
+    let scrubbed = value.replace(UUID_PATTERN, '<uuid>').replace(TIMESTAMP_PATTERN, '<timestamp>');
+    if (resolved.maskApprovalIds) {
+        scrubbed = scrubbed
+            .replace(APPROVAL_ID_PATTERN, '<approval-id>')
+            .replace(TOKEN_PREFIX_PATTERN, '/belay-approve <approval-id>');
+    }
+    if (resolved.maskBearerTokens) {
+        scrubbed = scrubbed.replace(BEARER_PATTERN, 'Bearer <redacted>');
+    }
+    if (resolved.maskAuthHeaders) {
+        scrubbed = scrubbed
+            .replace(DOUBLE_QUOTED_AUTH_HEADER_PATTERN, '"Authorization: <redacted>"')
+            .replace(SINGLE_QUOTED_AUTH_HEADER_PATTERN, "'Authorization: <redacted>'")
+            .replace(DOUBLE_QUOTED_GENERIC_AUTH_HEADER_PATTERN, (_match, header) => `"${header}: <redacted>"`)
+            .replace(SINGLE_QUOTED_GENERIC_AUTH_HEADER_PATTERN, (_match, header) => `'${header}: <redacted>'`)
+            .replace(AUTH_HEADER_PATTERN, 'Authorization: <redacted>')
+            .replace(GENERIC_AUTH_HEADER_PATTERN, (match) => {
+            const separatorIndex = match.indexOf(':');
+            return `${match.slice(0, separatorIndex + 1)} <redacted>`;
+        });
+    }
+    if (resolved.maskKeyValueSecrets) {
+        scrubbed = scrubbed
+            .replace(URL_CREDENTIALS_PATTERN, '$1<redacted>:<redacted>@')
+            .replace(MYSQL_INLINE_PASSWORD_PATTERN, '$1<redacted>');
+        scrubbed = scrubbed.replace(KEY_VALUE_SECRET_PATTERN, (match) => {
+            const separatorMatch = match.match(/\s*[:=]\s*/);
+            if (!separatorMatch || separatorMatch.index === undefined) {
+                return '<secret>';
+            }
+            return `${match.slice(0, separatorMatch.index)}${separatorMatch[0]}<redacted>`;
+        });
+    }
+    if (resolved.maskHighEntropyStrings) {
+        scrubbed = scrubbed.replace(HIGH_ENTROPY_PATTERN, '<high-entropy>');
+    }
+    return scrubbed;
+}
+export function scrubValue(value, options = DEFAULT_SCRUB_OPTIONS) {
+    if (typeof value === 'string') {
+        return scrubString(value, options);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => scrubValue(item, options));
+    }
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, child] of Object.entries(value)) {
+            result[key] = scrubValue(child, options);
+        }
+        return result;
+    }
+    return value;
+}

package/dist/core/shell-substitution.d.ts

@@ -0,0 +1,6 @@
+declare const MAX_SUBSTITUTION_DEPTH = 8;
+export { MAX_SUBSTITUTION_DEPTH };
+/**
+ * Finds inner commands for $(...) and backtick substitution, respecting escapes and nesting.
+ */
+export declare function findCommandSubstitutions(command: string): string[];

package/dist/core/shell-substitution.js

@@ -0,0 +1,130 @@
+const MAX_SUBSTITUTION_DEPTH = 8;
+export { MAX_SUBSTITUTION_DEPTH };
+/**
+ * Finds inner commands for $(...) and backtick substitution, respecting escapes and nesting.
+ */
+export function findCommandSubstitutions(command) {
+    const results = [];
+    let index = 0;
+    let inSingle = false;
+    let inDouble = false;
+    let escaping = false;
+    while (index < command.length) {
+        const char = command[index];
+        if (escaping) {
+            escaping = false;
+            index += 1;
+            continue;
+        }
+        if (char === '\\' && (inSingle || inDouble)) {
+            escaping = true;
+            index += 1;
+            continue;
+        }
+        if (!inDouble && char === "'") {
+            inSingle = !inSingle;
+            index += 1;
+            continue;
+        }
+        if (!inSingle && char === '"') {
+            inDouble = !inDouble;
+            index += 1;
+            continue;
+        }
+        if (inSingle || inDouble) {
+            index += 1;
+            continue;
+        }
+        if (char === '\\' && index + 1 < command.length) {
+            index += 2;
+            continue;
+        }
+        if (char === '`') {
+            const end = findClosingBacktick(command, index + 1);
+            if (end === -1) {
+                break;
+            }
+            const inner = command.slice(index + 1, end).trim();
+            if (inner) {
+                results.push(inner);
+            }
+            index = end + 1;
+            continue;
+        }
+        if (char === '$' && command[index + 1] === '(') {
+            const closed = extractBalancedParenContent(command, index + 2);
+            if (!closed) {
+                index += 1;
+                continue;
+            }
+            const inner = closed.content.trim();
+            if (inner) {
+                results.push(inner);
+            }
+            index = closed.endIndex;
+            continue;
+        }
+        index += 1;
+    }
+    return results;
+}
+function findClosingBacktick(command, start) {
+    let index = start;
+    while (index < command.length) {
+        if (command[index] === '\\' && index + 1 < command.length) {
+            index += 2;
+            continue;
+        }
+        if (command[index] === '`') {
+            return index;
+        }
+        index += 1;
+    }
+    return -1;
+}
+function extractBalancedParenContent(command, start) {
+    let depth = 1;
+    let index = start;
+    let inSingle = false;
+    let inDouble = false;
+    let escaping = false;
+    while (index < command.length && depth > 0) {
+        const char = command[index];
+        if (escaping) {
+            escaping = false;
+            index += 1;
+            continue;
+        }
+        if (char === '\\' && (inSingle || inDouble)) {
+            escaping = true;
+            index += 1;
+            continue;
+        }
+        if (!inDouble && char === "'") {
+            inSingle = !inSingle;
+            index += 1;
+            continue;
+        }
+        if (!inSingle && char === '"') {
+            inDouble = !inDouble;
+            index += 1;
+            continue;
+        }
+        if (!inSingle && !inDouble) {
+            if (char === '(') {
+                depth += 1;
+            }
+            else if (char === ')') {
+                depth -= 1;
+                if (depth === 0) {
+                    return {
+                        content: command.slice(start, index),
+                        endIndex: index + 1,
+                    };
+                }
+            }
+        }
+        index += 1;
+    }
+    return null;
+}

package/dist/core/shell-tokenizer.d.ts

@@ -0,0 +1,5 @@
+export declare function tokenizeShell(input: string): string[];
+export declare function normalizeShellCommand(command: string, repoRoot: string, normalizeToken: (t: string, r: string) => string): string;
+export declare function splitTopLevelSegments(tokens: string[]): string[][];
+export declare function commandKey(tokens: string[]): string;
+export declare function extractRedirectTargets(tokens: string[]): string[];

package/dist/core/shell-tokenizer.js

@@ -0,0 +1,129 @@
+const ENV_PREFIX_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S+)$/;
+export function tokenizeShell(input) {
+    const tokens = [];
+    let buffer = '';
+    let quote = null;
+    let escaping = false;
+    const flush = () => {
+        if (buffer.length > 0) {
+            tokens.push(buffer);
+            buffer = '';
+        }
+    };
+    for (let index = 0; index < input.length; index += 1) {
+        const char = input[index];
+        const next = input[index + 1] ?? '';
+        if (escaping) {
+            buffer += char;
+            escaping = false;
+            continue;
+        }
+        if (char === '\\') {
+            escaping = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else {
+                buffer += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === '&' && next === '&') {
+            flush();
+            tokens.push('&&');
+            index += 1;
+            continue;
+        }
+        if (char === '|' && next === '|') {
+            flush();
+            tokens.push('||');
+            index += 1;
+            continue;
+        }
+        if (char === '>' && next === '>') {
+            flush();
+            tokens.push('>>');
+            index += 1;
+            continue;
+        }
+        if (char === '|' || char === ';' || char === '>' || char === '<') {
+            flush();
+            tokens.push(char);
+            continue;
+        }
+        if (char === '\n' || char === '\r') {
+            flush();
+            tokens.push(';');
+            continue;
+        }
+        if (/\s/.test(char)) {
+            flush();
+            continue;
+        }
+        buffer += char;
+    }
+    flush();
+    return tokens;
+}
+export function normalizeShellCommand(command, repoRoot, normalizeToken) {
+    const tokens = tokenizeShell(command);
+    while (tokens.length > 0 && ENV_PREFIX_PATTERN.test(tokens[0] ?? '')) {
+        tokens.shift();
+    }
+    const normalized = tokens.map((token) => normalizeToken(token, repoRoot));
+    return normalized.join(' ').trim();
+}
+export function splitTopLevelSegments(tokens) {
+    const segments = [];
+    let current = [];
+    for (const token of tokens) {
+        if (token === '&&' || token === '||' || token === ';' || token === '|') {
+            if (current.length > 0) {
+                segments.push(current);
+            }
+            current = [];
+            continue;
+        }
+        current.push(token);
+    }
+    if (current.length > 0) {
+        segments.push(current);
+    }
+    return segments;
+}
+export function commandKey(tokens) {
+    const filtered = tokens.filter((token) => token !== 'sudo');
+    const first = filtered[0] ?? '';
+    const second = filtered[1] ?? '';
+    if ((first === 'git' ||
+        first === 'npm' ||
+        first === 'pnpm' ||
+        first === 'docker' ||
+        first === 'terraform' ||
+        first === 'fly' ||
+        first === 'firebase') &&
+        second) {
+        return `${first} ${second}`;
+    }
+    return first;
+}
+export function extractRedirectTargets(tokens) {
+    const targets = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === '>' || token === '>>' || token === '<') {
+            const next = tokens[index + 1];
+            if (next) {
+                targets.push(next);
+            }
+        }
+    }
+    return targets;
+}

package/dist/core/shell-unparseable.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Detects shell constructs that agent-belay cannot reliably parse (R1).
+ */
+export declare function detectUnparseableShell(command: string): boolean;