@thegitai/cli 1.0.0-beta.1

package/dist/src/executor.js

@@ -0,0 +1,924 @@
+import chalk from 'chalk';
+import * as pty from '@homebridge/node-pty-prebuilt-multiarch';
+import { execFileSync, spawn } from 'child_process';
+import { existsSync, statSync } from 'fs';
+import os from 'os';
+import path from 'path';
+import { ARTIFACT_INSPECT_BLOCK_DIRS, getBlockedArtifactInspectDir, relativeProjectPath, } from './artifact-policy.js';
+import { emitCommandOutput, isTuiMode } from './runtime-mode.js';
+const COMMON_TOOLCHAIN_BIN_DIRS = ['/usr/local/go/bin'];
+function detectVenvBin(dir) {
+    for (const name of ['.venv', 'venv', 'env']) {
+        const bin = path.join(dir, name, 'bin');
+        if (existsSync(path.join(bin, 'python')))
+            return bin;
+    }
+    return null;
+}
+const DEFAULT_TIMEOUT = 5 * 60 * 1000;
+const MAX_OUTPUT_CHARS = 6000;
+const MAX_CAPTURE_CHARS = 1024 * 1024;
+const EXPLORATORY_COMMAND_PATTERN = /\b(ls|find|tree|fd|rg)\b/;
+const FILE_INSPECTION_COMMAND_PATTERN = /\b(ls|find|tree|fd|rg|grep|cat|sed|head|tail|less|more)\b/;
+const DETACHED_JOB_PATTERN = /\$!|\b(nohup|disown|setsid)\b/;
+const LONG_RUNNING_SERVER_PATTERN = /\b((npm|pnpm|yarn)\s+run\s+(dev|start|preview)|next\s+dev|next\s+start|nuxi?\s+(dev|preview)|vite(\s+dev)?|webpack(-dev-server)?\s+serve)\b/;
+const BLOCKED_PATH_INSPECT_DIRS = ARTIFACT_INSPECT_BLOCK_DIRS;
+function getUnquotedShellText(command) {
+    let quote = null;
+    let escaped = false;
+    let text = '';
+    for (const char of String(command)) {
+        if (escaped) {
+            escaped = false;
+            text += ' ';
+            continue;
+        }
+        if (char === '\\' && quote !== "'") {
+            escaped = true;
+            text += ' ';
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            text += ' ';
+            continue;
+        }
+        if (char === "'" || char === '"' || char === '`') {
+            quote = char;
+            text += ' ';
+            continue;
+        }
+        text += char;
+    }
+    return text;
+}
+function hasUnquotedBackgroundAmpersand(command) {
+    let quote = null;
+    let escaped = false;
+    const text = String(command);
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === '\\' && quote !== "'") {
+            escaped = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (char !== '&')
+            continue;
+        const previous = text[index - 1] ?? '';
+        const next = text[index + 1] ?? '';
+        if (previous === '&' || next === '&')
+            continue;
+        if (previous === '>' || previous === '<' || next === '>')
+            continue;
+        return true;
+    }
+    return false;
+}
+function hasBackgroundOrDetachedShell(command) {
+    return (DETACHED_JOB_PATTERN.test(getUnquotedShellText(command)) ||
+        hasUnquotedBackgroundAmpersand(command));
+}
+function getBadGhPrCommandReason(command) {
+    const text = getUnquotedShellText(command);
+    if (/\bgh\s+pr\s+diff\s+\S+(?:\s+(?:\d?>&\d+|\d?>\S+|--[A-Za-z0-9-]+(?:=\S+)?))*\s*\|\s*(?:cat|head|tail|sed|awk)\b/i.test(text)) {
+        return 'Do not page or slice whole PR diffs through shell. Use gh pr view <number> --json files,statusCheckRollup for PR metadata, then git diff <base>...HEAD -- <path> for one changed file at a time.';
+    }
+    if (/\bgh\s+pr\s+diff\s+\S+\s+--\s+\S+/i.test(text)) {
+        return 'gh pr diff accepts only a PR number. For a file-scoped PR diff, use git diff <base>...HEAD -- <path>, or run gh pr diff <number> alone.';
+    }
+    if (/\bgh\s+pr\s+view\b(?=[^;&|]*--json\b)(?=[^;&|]*\bdiff\b)/i.test(text)) {
+        return 'gh pr view --json does not expose a diff field. Use gh pr diff <number> for diff text, or gh pr view <number> --json files,statusCheckRollup for structured PR metadata.';
+    }
+    return null;
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function maskNonPathIgnoreDirTokens(command) {
+    let s = String(command);
+    s = s.replace(/\b(npm|pnpm|yarn|npx)\s+run\s+[^\s;&|)]+/gi, '$1 run __pm_script__');
+    for (const dir of BLOCKED_PATH_INSPECT_DIRS) {
+        if (!/^[a-z0-9@._-]+$/i.test(dir))
+            continue;
+        s = s.replace(new RegExp(`\\byarn\\s+${escapeRegex(dir)}\\b`, 'gi'), 'yarn __pm_script__');
+    }
+    s = s.replace(/\b(nuxt|nuxi|next|vite|webpack|rollup)\s+build\b/gi, '$1 __cli_build__');
+    return s;
+}
+function maskHereDocumentBodies(command) {
+    const lines = String(command).split('\n');
+    const masked = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        masked.push(line);
+        const markers = Array.from(line.matchAll(/<<-?\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_]+))/g), (match) => match[1] ?? match[2] ?? match[3] ?? '').filter(Boolean);
+        for (const marker of markers) {
+            i += 1;
+            while (i < lines.length) {
+                const bodyLine = lines[i] ?? '';
+                if (bodyLine.trim() === marker) {
+                    masked.push(bodyLine);
+                    break;
+                }
+                masked.push('');
+                i += 1;
+            }
+        }
+    }
+    return masked.join('\n');
+}
+function splitShellishTokens(text) {
+    return text.match(/"[^"]*"|'[^']*'|`[^`]*`|\S+/g) ?? [];
+}
+function normalizeToken(raw) {
+    let token = String(raw).trim();
+    if (!token)
+        return '';
+    if (token.length >= 2 &&
+        ((token.startsWith('"') && token.endsWith('"')) ||
+            (token.startsWith("'") && token.endsWith("'")) ||
+            (token.startsWith('`') && token.endsWith('`')))) {
+        token = token.slice(1, -1);
+    }
+    token = token.replace(/^[([{]+/, '').replace(/[)\]},;]+$/, '');
+    token = token.replace(/:(\d+)(?::\d+)?$/, '').replace(/:+$/, '');
+    return token;
+}
+function hasPathGlob(token) {
+    return /[*?[\]{}]/.test(token);
+}
+function hasExplicitPathShape(token) {
+    if (!token || token.startsWith('-'))
+        return false;
+    if (token === '.' || token === '..')
+        return true;
+    if (token.startsWith('/') ||
+        token.startsWith('./') ||
+        token.startsWith('../') ||
+        token.startsWith('~/')) {
+        return true;
+    }
+    return token.includes('/') || token.includes('\\');
+}
+function getCommandBaseDir(command, rootDir) {
+    if (!rootDir)
+        return null;
+    const match = String(command).match(/^\s*cd\s+((?:"[^"]*"|'[^']*'|`[^`]*`|\S+))\s*&&/);
+    if (!match)
+        return rootDir;
+    const token = normalizeToken(match[1] ?? '');
+    if (!token || hasPathGlob(token) || token.startsWith('~'))
+        return rootDir;
+    return path.isAbsolute(token)
+        ? path.resolve(token)
+        : path.resolve(rootDir, token);
+}
+function getBlockedProjectPathDir(absPath, rootDir) {
+    const relPath = relativeProjectPath(rootDir, absPath);
+    return relPath ? getBlockedArtifactInspectDir(relPath) : null;
+}
+function isInsideOsTemp(absPath) {
+    const relPath = path.relative(path.resolve(os.tmpdir()), path.resolve(absPath));
+    return (relPath === '' ||
+        (!relPath.startsWith('..') && !path.isAbsolute(relPath)));
+}
+function isExistingDirectory(absPath) {
+    try {
+        return existsSync(absPath) && statSync(absPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function getBlockedOsTempInspection(rawToken, rootDir) {
+    const token = normalizeToken(rawToken);
+    if (!token || !path.isAbsolute(token))
+        return null;
+    const resolved = path.resolve(token);
+    if (!isInsideOsTemp(resolved))
+        return null;
+    if (rootDir) {
+        const resolvedRoot = path.resolve(rootDir);
+        if (resolved === resolvedRoot ||
+            relativeProjectPath(resolvedRoot, resolved) !== null) {
+            return null;
+        }
+    }
+    if (resolved === path.resolve(os.tmpdir()) ||
+        hasPathGlob(token) ||
+        isExistingDirectory(resolved)) {
+        return path.basename(os.tmpdir()) || os.tmpdir();
+    }
+    return null;
+}
+function findBlockedDirForToken(rawToken, rootDir, baseDir, allowBareDirMatch = false) {
+    const token = normalizeToken(rawToken);
+    if (!token || token.startsWith('~') || !rootDir) {
+        return null;
+    }
+    const osTempDir = getBlockedOsTempInspection(rawToken, rootDir);
+    if (osTempDir)
+        return osTempDir;
+    if (hasExplicitPathShape(token)) {
+        const resolved = path.isAbsolute(token)
+            ? path.resolve(token)
+            : path.resolve(baseDir ?? rootDir, token);
+        return getBlockedProjectPathDir(resolved, rootDir);
+    }
+    if (!allowBareDirMatch || !BLOCKED_PATH_INSPECT_DIRS.has(token)) {
+        return null;
+    }
+    const resolved = path.resolve(baseDir ?? rootDir, token);
+    return getBlockedProjectPathDir(resolved, rootDir);
+}
+function isShellControlToken(token) {
+    return (token === '|' ||
+        token === '||' ||
+        token === '&&' ||
+        token === ';' ||
+        token === '(' ||
+        token === ')');
+}
+function getOptionValueRole(commandName, option) {
+    switch (commandName) {
+        case 'grep':
+        case 'rg':
+            if (option === '-e' || option === '--regexp')
+                return 'pattern';
+            if (option === '-f' ||
+                option === '--file' ||
+                option === '-g' ||
+                option === '--glob') {
+                return 'path';
+            }
+            return null;
+        case 'sed':
+            if (option === '-e')
+                return 'pattern';
+            if (option === '-f')
+                return 'path';
+            return null;
+        case 'find':
+            if (option === '-path' ||
+                option === '-ipath' ||
+                option === '-wholename' ||
+                option === '-iwholename') {
+                return 'path';
+            }
+            if (option === '-name' || option === '-iname')
+                return 'pattern';
+            return null;
+        default:
+            return null;
+    }
+}
+function splitOptionToken(token) {
+    const eqIndex = token.indexOf('=');
+    if (eqIndex === -1) {
+        return { optionName: token, inlineValue: null };
+    }
+    return {
+        optionName: token.slice(0, eqIndex),
+        inlineValue: token.slice(eqIndex + 1),
+    };
+}
+function shouldAllowBareBlockedDir(commandName, positionalCount) {
+    switch (commandName) {
+        case 'ls':
+        case 'tree':
+        case 'cat':
+        case 'head':
+        case 'tail':
+        case 'less':
+        case 'more':
+        case 'find':
+            return positionalCount >= 1;
+        case 'grep':
+        case 'rg':
+        case 'fd':
+        case 'sed':
+            return positionalCount >= 2;
+        default:
+            return false;
+    }
+}
+function findBlockedDirInCommandTokens(command, rootDir, baseDir) {
+    if (!rootDir)
+        return null;
+    const tokens = splitShellishTokens(command);
+    let currentCommand = '';
+    let positionalCount = 0;
+    let stopOptions = false;
+    let optionValueRole = null;
+    for (const rawToken of tokens) {
+        const token = normalizeToken(rawToken);
+        if (!token)
+            continue;
+        if (isShellControlToken(token)) {
+            currentCommand = '';
+            positionalCount = 0;
+            stopOptions = false;
+            optionValueRole = null;
+            continue;
+        }
+        if (!currentCommand) {
+            currentCommand = token.toLowerCase();
+            positionalCount = 0;
+            stopOptions = false;
+            optionValueRole = null;
+            continue;
+        }
+        if (optionValueRole) {
+            const blockedDir = findBlockedDirForToken(token, rootDir, baseDir, optionValueRole === 'path');
+            if (blockedDir)
+                return blockedDir;
+            optionValueRole = null;
+            continue;
+        }
+        if (!stopOptions && token === '--') {
+            stopOptions = true;
+            continue;
+        }
+        if (!stopOptions && token.startsWith('-') && token !== '-') {
+            const { optionName, inlineValue } = splitOptionToken(token);
+            const optionRole = getOptionValueRole(currentCommand, optionName);
+            if (inlineValue != null) {
+                const blockedDir = findBlockedDirForToken(inlineValue, rootDir, baseDir, optionRole === 'path');
+                if (blockedDir)
+                    return blockedDir;
+                optionValueRole = null;
+                continue;
+            }
+            optionValueRole = optionRole;
+            continue;
+        }
+        positionalCount += 1;
+        const blockedDir = findBlockedDirForToken(token, rootDir, baseDir, shouldAllowBareBlockedDir(currentCommand, positionalCount));
+        if (blockedDir)
+            return blockedDir;
+    }
+    return null;
+}
+function findIgnoredPathInspection(command, rootDir) {
+    if (!FILE_INSPECTION_COMMAND_PATTERN.test(command)) {
+        return null;
+    }
+    const haystack = maskNonPathIgnoreDirTokens(maskHereDocumentBodies(command));
+    const baseDir = getCommandBaseDir(haystack, rootDir);
+    const blockedDir = findBlockedDirInCommandTokens(haystack, rootDir, baseDir);
+    if (blockedDir) {
+        return blockedDir;
+    }
+    if (!rootDir) {
+        for (const dir of BLOCKED_PATH_INSPECT_DIRS) {
+            const pattern = new RegExp(`(^|[\\s"'./])${escapeRegex(dir)}(?=$|[\\s"'./])`);
+            if (pattern.test(haystack)) {
+                return dir;
+            }
+        }
+    }
+    return null;
+}
+function trimOutput(text) {
+    if (!text)
+        return '';
+    if (text.length <= MAX_OUTPUT_CHARS)
+        return text;
+    return `${text.slice(0, MAX_OUTPUT_CHARS)}\n... (truncated)`;
+}
+function buildCommandPath(basePath, extraDirs = []) {
+    const seen = new Set();
+    const dirs = [];
+    for (const dir of [...extraDirs, ...COMMON_TOOLCHAIN_BIN_DIRS]) {
+        if (!dir || seen.has(dir) || !existsSync(dir))
+            continue;
+        seen.add(dir);
+        dirs.push(dir);
+    }
+    for (const dir of String(basePath ?? '').split(path.delimiter)) {
+        if (!dir || seen.has(dir))
+            continue;
+        seen.add(dir);
+        dirs.push(dir);
+    }
+    return dirs.join(path.delimiter);
+}
+function isExploratoryCommand(command) {
+    return EXPLORATORY_COMMAND_PATTERN.test(command);
+}
+function shouldDropOutputLine(line, rootDir, baseDir) {
+    const tokens = splitShellishTokens(line);
+    if (tokens.length === 1) {
+        return findBlockedDirForToken(tokens[0], rootDir, baseDir, true) != null;
+    }
+    for (const token of splitShellishTokens(line)) {
+        if (findBlockedDirForToken(token, rootDir, baseDir))
+            return true;
+    }
+    return false;
+}
+function isLsDirectoryHeader(line) {
+    return /^\.?\/?.+:$/.test(line) && !line.includes(' ');
+}
+function sanitizeCommandText(command, text, rootDir) {
+    if (!text)
+        return '';
+    const lines = text.split('\n');
+    const filtered = [];
+    let insideIgnoredDir = false;
+    const baseDir = getCommandBaseDir(command, rootDir);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (isLsDirectoryHeader(trimmed)) {
+            const dirPath = trimmed.replace(/^\.\//, '').replace(/:$/, '');
+            if (shouldDropOutputLine(dirPath, rootDir, baseDir)) {
+                insideIgnoredDir = true;
+                continue;
+            }
+            insideIgnoredDir = false;
+        }
+        if (insideIgnoredDir)
+            continue;
+        if (shouldDropOutputLine(trimmed, rootDir, baseDir))
+            continue;
+        filtered.push(line);
+    }
+    return filtered.join('\n');
+}
+function appendCapturedText(current, chunk) {
+    if (!chunk || current.length >= MAX_CAPTURE_CHARS) {
+        return current;
+    }
+    const remaining = MAX_CAPTURE_CHARS - current.length;
+    return current + chunk.slice(0, remaining);
+}
+let activeCommandChild = null;
+let activeCommandPty = null;
+let activeCommandFinish = null;
+function killPty(child, signal) {
+    try {
+        if (process.platform === 'win32') {
+            child.kill();
+            return;
+        }
+        child.kill(signal);
+    }
+    catch { }
+}
+export function cancelActiveCommand() {
+    const child = activeCommandChild;
+    const commandPty = activeCommandPty;
+    const finish = activeCommandFinish;
+    if ((!child && !commandPty) || !finish)
+        return;
+    let killEscalated = false;
+    const killTimer = setTimeout(() => {
+        if (!killEscalated) {
+            killEscalated = true;
+            if (child)
+                terminateChild(child, 'SIGKILL');
+            if (commandPty)
+                killPty(commandPty, 'SIGKILL');
+        }
+    }, 500);
+    killTimer.unref?.();
+    if (child)
+        terminateChild(child, 'SIGTERM');
+    if (commandPty)
+        killPty(commandPty, 'SIGTERM');
+    finish({
+        exitCode: 1,
+        stdout: '',
+        stderr: 'Command cancelled.',
+        output: 'Command cancelled.',
+        timedOut: false,
+        cancelled: true,
+    });
+}
+function terminateChild(child, signal) {
+    if (!child?.pid)
+        return;
+    if (process.platform === 'win32') {
+        try {
+            execFileSync('taskkill', ['/pid', String(child.pid), '/t', '/f'], {
+                stdio: 'ignore',
+            });
+        }
+        catch {
+            try {
+                child.kill(signal);
+            }
+            catch { }
+        }
+        return;
+    }
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch { }
+    }
+}
+export function getBlockedPathInspectDir(command, rootDir) {
+    return findIgnoredPathInspection(command, rootDir);
+}
+export function getBlockedCommandReason(command, hasTimeout, rootDir) {
+    const ignoredDir = findIgnoredPathInspection(command, rootDir);
+    if (ignoredDir) {
+        return `Command inspects an off-limits generated or dependency directory (${ignoredDir}). Avoid that path.`;
+    }
+    const badGhPrCommand = getBadGhPrCommandReason(command);
+    if (badGhPrCommand)
+        return badGhPrCommand;
+    if (hasBackgroundOrDetachedShell(command)) {
+        return 'Command contains an unquoted shell background operator (&). Quote URLs or arguments containing & and run one foreground command.';
+    }
+    if (!hasTimeout && LONG_RUNNING_SERVER_PATTERN.test(command)) {
+        return 'Dev/start/preview server commands require timeout_ms. Use a short timeout to capture startup output.';
+    }
+    if (/\bgit\s+(checkout|restore)\b/.test(command) &&
+        !/\bgit\s+checkout\s+-b\b/.test(command)) {
+        return 'Refusing git checkout or git restore because it can discard local edits. Create a branch with git checkout -b or ask before reverting.';
+    }
+    return null;
+}
+function commandUsesSudo(command) {
+    return /\bsudo\b/.test(getUnquotedShellText(command));
+}
+export function sudoPromptFromTail(text) {
+    const tail = text.slice(-1000).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+    const match = tail.match(/(?:\[sudo\][^\r\n]*password[^\r\n]*: ?|sudo[^\r\n]*password[^\r\n]*: ?|password[^\r\n]*: ?)$/i);
+    return match?.[0] ?? null;
+}
+function isSudoPromptLine(text) {
+    const cleaned = text.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '').trim();
+    return /(?:\[sudo\][^\r\n]*password[^\r\n]*:|sudo[^\r\n]*password[^\r\n]*:|^password[^\r\n]*:)/i.test(cleaned);
+}
+export function stripSudoPromptText(text) {
+    return text
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .filter((line) => !isSudoPromptLine(line))
+        .join('\n');
+}
+function redactSecrets(text, secrets) {
+    let redacted = text;
+    for (const secret of secrets) {
+        if (!secret)
+            continue;
+        redacted = redacted.split(secret).join('[sudo password redacted]');
+    }
+    return redacted;
+}
+function buildCommandEnv(cwd) {
+    const venvBin = detectVenvBin(cwd);
+    const envPath = buildCommandPath(process.env.PATH, venvBin ? [venvBin] : []);
+    return {
+        ...process.env,
+        PATH: envPath,
+        VIRTUAL_ENV: venvBin
+            ? path.dirname(venvBin)
+            : process.env.VIRTUAL_ENV || '',
+        CI: 'true',
+        npm_config_yes: 'true',
+        npm_config_progress: 'false',
+        npm_config_fund: 'false',
+        npm_config_audit: 'false',
+        NUXI_INIT_SKIP_PROMPT: 'true',
+    };
+}
+function sanitizePtyOutput(command, output, cwd, secrets) {
+    return sanitizeCommandText(command, stripSudoPromptText(redactSecrets(output, secrets)), cwd);
+}
+async function runPtyCommand(command, cwd, effectiveTimeout, exploratory, requestSudoPassword) {
+    return new Promise((resolve) => {
+        let output = '';
+        let timedOut = false;
+        let settled = false;
+        let requestingPassword = false;
+        let pendingLiveText = '';
+        let killTimer = null;
+        const sudoPromptAbort = new AbortController();
+        const sudoSecrets = new Set();
+        const shell = process.platform === 'win32'
+            ? (process.env.ComSpec || 'cmd.exe')
+            : (process.env.SHELL || '/bin/sh');
+        const args = process.platform === 'win32'
+            ? ['/d', '/s', '/c', command]
+            : ['-lc', command];
+        const child = pty.spawn(shell, args, {
+            cols: 120,
+            rows: 30,
+            cwd,
+            env: buildCommandEnv(cwd),
+            name: 'xterm-256color',
+        });
+        activeCommandPty = child;
+        const timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            killPty(child, 'SIGTERM');
+            killTimer = setTimeout(() => killPty(child, 'SIGKILL'), 2000);
+            killTimer.unref?.();
+        }, effectiveTimeout);
+        timeoutTimer.unref?.();
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            sudoPromptAbort.abort();
+            if (activeCommandPty === child) {
+                activeCommandPty = null;
+                activeCommandFinish = null;
+            }
+            clearTimeout(timeoutTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve(result);
+        };
+        activeCommandFinish = finish;
+        const flushLiveText = () => {
+            if (!pendingLiveText.trim() || isSudoPromptLine(pendingLiveText)) {
+                pendingLiveText = '';
+                return;
+            }
+            emitCommandOutput(`${pendingLiveText}\n`);
+            pendingLiveText = '';
+        };
+        const tuiMode = isTuiMode();
+        const writeLiveText = (text) => {
+            if (exploratory)
+                return;
+            const visibleText = stripSudoPromptText(redactSecrets(text, sudoSecrets));
+            if (tuiMode) {
+                pendingLiveText += visibleText.replace(/\r\n?/g, '\n');
+                const liveLines = pendingLiveText.split('\n');
+                pendingLiveText = liveLines.pop() ?? '';
+                const complete = liveLines
+                    .filter((line) => line.trim() && !isSudoPromptLine(line))
+                    .join('\n');
+                if (complete)
+                    emitCommandOutput(`${complete}\n`);
+                return;
+            }
+            if (visibleText) {
+                process.stdout.write(visibleText);
+            }
+        };
+        child.onData((text) => {
+            output = appendCapturedText(output, text);
+            writeLiveText(text);
+            const prompt = sudoPromptFromTail(output);
+            if (!prompt || requestingPassword || settled)
+                return;
+            requestingPassword = true;
+            void requestSudoPassword({
+                command,
+                prompt,
+                signal: sudoPromptAbort.signal,
+            })
+                .then((password) => {
+                requestingPassword = false;
+                if (settled)
+                    return;
+                if (password == null) {
+                    killPty(child, 'SIGTERM');
+                    finish({
+                        exitCode: 1,
+                        stdout: '',
+                        stderr: 'Sudo authentication cancelled.',
+                        output: 'Sudo authentication cancelled.',
+                        timedOut: false,
+                        cancelled: true,
+                    });
+                    return;
+                }
+                sudoSecrets.add(password);
+                child.write(`${password}\r`);
+            })
+                .catch(() => {
+                requestingPassword = false;
+                if (settled)
+                    return;
+                killPty(child, 'SIGTERM');
+                finish({
+                    exitCode: 1,
+                    stdout: '',
+                    stderr: 'Sudo authentication failed.',
+                    output: 'Sudo authentication failed.',
+                    timedOut: false,
+                });
+            });
+        });
+        child.onExit(({ exitCode }) => {
+            flushLiveText();
+            const outputText = sanitizePtyOutput(command, output, cwd, sudoSecrets);
+            if (exploratory && !tuiMode && outputText.trim()) {
+                process.stdout.write(outputText);
+                if (!outputText.endsWith('\n'))
+                    process.stdout.write('\n');
+            }
+            if (timedOut) {
+                finish({
+                    exitCode: exitCode || 1,
+                    stdout: outputText,
+                    stderr: '',
+                    output: trimOutput(outputText.trim()),
+                    timedOut: true,
+                });
+                return;
+            }
+            finish({
+                exitCode,
+                stdout: outputText,
+                stderr: '',
+                output: trimOutput(outputText.trim()),
+                timedOut: false,
+            });
+        });
+    });
+}
+export async function runCommand(command, cwd, { requestSudoPassword, timeout, } = {}) {
+    if (!isTuiMode()) {
+        console.log(chalk.cyan(`\n  ▶ Running: ${command}`));
+        console.log(chalk.dim(`    in: ${cwd}\n`));
+    }
+    const hasExplicitTimeout = typeof timeout === 'number' && timeout > 0;
+    const effectiveTimeout = hasExplicitTimeout ? timeout : DEFAULT_TIMEOUT;
+    const blockedReason = getBlockedCommandReason(command, hasExplicitTimeout, cwd);
+    if (blockedReason) {
+        if (!isTuiMode())
+            console.log(chalk.red(`  ✖ ${blockedReason}`));
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: blockedReason,
+            output: blockedReason,
+            timedOut: false,
+            blocked: true,
+        };
+    }
+    const exploratory = isExploratoryCommand(command);
+    if (requestSudoPassword && commandUsesSudo(command)) {
+        return runPtyCommand(command, cwd, effectiveTimeout, exploratory, requestSudoPassword);
+    }
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        let killTimer = null;
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            detached: process.platform !== 'win32',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: buildCommandEnv(cwd),
+        });
+        activeCommandChild = child;
+        child.stdin?.end();
+        const timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            terminateChild(child, 'SIGTERM');
+            killTimer = setTimeout(() => terminateChild(child, 'SIGKILL'), 2000);
+            killTimer.unref?.();
+        }, effectiveTimeout);
+        timeoutTimer.unref?.();
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (activeCommandChild === child) {
+                activeCommandChild = null;
+                activeCommandFinish = null;
+            }
+            clearTimeout(timeoutTimer);
+            if (killTimer) {
+                clearTimeout(killTimer);
+            }
+            resolve(result);
+        };
+        activeCommandFinish = finish;
+        const tuiMode = isTuiMode();
+        child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString('utf-8');
+            stdout = appendCapturedText(stdout, text);
+            if (exploratory || tuiMode) {
+                if (tuiMode && !exploratory)
+                    emitCommandOutput(text);
+                return;
+            }
+            const ok = process.stdout.write(text);
+            if (!ok) {
+                child.stdout?.pause();
+                process.stdout.once('drain', () => child.stdout?.resume());
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            const text = chunk.toString('utf-8');
+            stderr = appendCapturedText(stderr, text);
+            if (exploratory || tuiMode) {
+                if (tuiMode && !exploratory)
+                    emitCommandOutput(text);
+                return;
+            }
+            const ok = process.stderr.write(text);
+            if (!ok) {
+                child.stderr?.pause();
+                process.stderr.once('drain', () => child.stderr?.resume());
+            }
+        });
+        child.on('error', (error) => {
+            const stdoutText = sanitizeCommandText(command, stdout, cwd);
+            const stderrText = sanitizeCommandText(command, appendCapturedText(stderr, error.message ? `${error.message}\n` : ''), cwd);
+            const output = trimOutput([stdoutText, stderrText].filter(Boolean).join('\n').trim());
+            if (exploratory && !tuiMode) {
+                if (stdoutText.trim()) {
+                    process.stdout.write(stdoutText);
+                    if (!stdoutText.endsWith('\n'))
+                        process.stdout.write('\n');
+                }
+                if (stderrText.trim()) {
+                    process.stderr.write(stderrText);
+                    if (!stderrText.endsWith('\n'))
+                        process.stderr.write('\n');
+                }
+            }
+            if (!tuiMode)
+                console.log(chalk.red('\n  ✖ Command exited with code 1'));
+            finish({
+                exitCode: 1,
+                stdout: stdoutText,
+                stderr: stderrText,
+                output,
+                timedOut,
+            });
+        });
+        child.on('close', (code, signal) => {
+            const stdoutText = sanitizeCommandText(command, stdout, cwd);
+            const stderrText = sanitizeCommandText(command, stderr, cwd);
+            if (exploratory && !tuiMode) {
+                if (stdoutText.trim()) {
+                    process.stdout.write(stdoutText);
+                    if (!stdoutText.endsWith('\n'))
+                        process.stdout.write('\n');
+                }
+                if (stderrText.trim()) {
+                    process.stderr.write(stderrText);
+                    if (!stderrText.endsWith('\n'))
+                        process.stderr.write('\n');
+                }
+            }
+            if (timedOut || signal === 'SIGTERM' || signal === 'SIGKILL') {
+                if (!tuiMode && !settled) {
+                    console.log(chalk.red(`\n  ✖ Command timed out after ${effectiveTimeout / 1000}s`));
+                }
+                finish({
+                    exitCode: code ?? 1,
+                    stdout: stdoutText,
+                    stderr: stderrText,
+                    output: trimOutput([stdoutText, stderrText].filter(Boolean).join('\n').trim()),
+                    timedOut: true,
+                });
+                return;
+            }
+            if (code === 0) {
+                if (!tuiMode)
+                    console.log(chalk.green('\n  ✓ Command exited with code 0'));
+                finish({
+                    exitCode: 0,
+                    stdout: stdoutText,
+                    stderr: stderrText,
+                    output: trimOutput(stdoutText.trim()),
+                    timedOut: false,
+                });
+                return;
+            }
+            if (!tuiMode)
+                console.log(chalk.red(`\n  ✖ Command exited with code ${code ?? 1}`));
+            finish({
+                exitCode: code ?? 1,
+                stdout: stdoutText,
+                stderr: stderrText,
+                output: trimOutput([stdoutText, stderrText].filter(Boolean).join('\n').trim()),
+                timedOut: false,
+            });
+        });
+    });
+}