@cybedefend/vibedefend 1.5.0 → 1.6.0

package/dist/hooks/runtime/script-resolve.js

@@ -0,0 +1,695 @@
+/**
+ * Level 1 of the Action Guards hardening: READ A SCRIPT THE AGENT EXECUTES.
+ *
+ * The regex evaluator sees only the launcher command. When an agent runs a
+ * file it wrote — `bash cleanup.sh`, `./deploy.sh`, `python tools/x.py`,
+ * `npm run cleanup` — the guard never sees the dangerous commands INSIDE that
+ * file. This module closes that blind spot: given a raw Bash command, it
+ * detects that the command executes a local file/script, reads it (bounded,
+ * from disk — the hook runs locally), and returns the inner commands/content
+ * so the integrator can re-feed them to Level 0 (normalize → triage → regex).
+ *
+ * It does NOT itself scan for danger and it does NOT recurse into whatever the
+ * inner commands execute — the integrator feeds `shellCommands` back through
+ * Level 0, which may call this module again. One hop per call, bounded reads,
+ * never throws.
+ *
+ * ── What it detects ─────────────────────────────────────────────────────────
+ *   - `bash|sh|zsh|dash|ksh <file>`        → kind 'shell'       (split into lines)
+ *   - `./<file>` / `dir/<file>` (a path)   → kind 'shell' | 'interpreter'
+ *                                            (decided by shebang / extension)
+ *   - `python|python3|node|tsx|ts-node|ruby|perl|php|Rscript|lua <f>`,
+ *     `deno run <f>`, `bun [run] <f.ts|.js>` → kind 'interpreter' (content only)
+ *   - `npm|pnpm|yarn|bun run <script>`     → kind 'npm-script'  (the script body)
+ *   - behind `npx`, `bunx`, `pnpm exec`, `yarn exec`, `uv run`, `poetry run`,
+ *     `pipenv run` (`uv run x.py` runs it with Python)
+ *
+ * For a 'shell' / 'npm-script' result the inner commands are in `shellCommands`
+ * (one per logical command line; heredoc bodies stripped, line continuations
+ * joined, comments and blank lines dropped). A 'shell' or 'interpreter' result
+ * carries the raw file text in `content` and its `language`: the script judge
+ * (guard-check.ts) reads it. Parsing Python/JS/Ruby into shell commands is out
+ * of scope.
+ *
+ * ── Documented limits (deliberately out of scope) ───────────────────────────
+ *   - INLINE code is NOT handled here and returns `null` — `bash -c "…"`,
+ *     `sh -c …`, `python -c …`, `node -e/-p …`, `ruby -e …`, `perl -e/-pe …`.
+ *     De-obfuscating inline interpreter strings is the normalizer's job.
+ *   - `python -m <module>` runs a module, not a resolvable file → `null`.
+ *   - `git apply` / `patch` (targets live inside the patch text) are not read.
+ *   - `source file` / `. file` (sourcing) is NOT followed.
+ *   - No `~` / `$VAR` expansion in script paths; the path is resolved against
+ *     `cwd` literally. A path that does not exist returns `null` — never guess.
+ *   - At most ONE level of `npm run <other>` indirection is followed (noted).
+ *   - Reads are capped at `maxBytes` (default 256 KB); a larger file is read up
+ *     to the cap and `truncated` is set.
+ *
+ * Pure over its inputs except for the injected filesystem (`opts.fs`, default
+ * `node:fs`). Matches the tokenizer and heredoc handling of `shell-writes.ts`:
+ * `shell-quote` with an env function so `$VAR` survives, bodies stripped first.
+ */
+import { parse as shellParse } from 'shell-quote';
+import { isAbsolute, resolve as pathResolve, extname } from 'node:path';
+import * as nodeFs from 'node:fs';
+import { stripHeredocBodies } from './shell-writes.js';
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const HARD_MAX_BYTES = 8 * 1024 * 1024;
+/** Operators that end a simple command and start a new segment. */
+const BOUNDARY_OPS = new Set([';', '&&', '||', '|', '|&', '&', '(', ')', '\n']);
+/** Wrappers that prefix a command without changing which file it executes. */
+const TRANSPARENT_PREFIXES = new Set(['sudo', 'doas', 'nohup', 'command', 'time', 'nice', 'env', 'exec']);
+/** Interpreters whose script argument is a shell script. */
+const SHELL_INTERPRETERS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh', 'ash']);
+/** Package-manager launchers that take a `run <script>` form. */
+const NPM_RUNNERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+const SHELL_SPEC = {
+    // `-c` = command string, `-s` = read from stdin: neither names a file to read.
+    inlineExact: new Set(['-c', '-s']),
+    valueFlags: new Set(['-o', '+o', '-O', '+O']),
+};
+const PYTHON_SPEC = { inlineExact: new Set(['-c']), moduleExact: new Set(['-m']), valueFlags: new Set(['-W', '-X', '-Q']) };
+const NODE_SPEC = {
+    inlineExact: new Set(['-e', '--eval', '-p', '--print']),
+    valueFlags: new Set(['-r', '--require', '--loader', '--import', '--experimental-loader']),
+};
+const INTERPRETERS = new Map([
+    ['python', PYTHON_SPEC],
+    ['python2', PYTHON_SPEC],
+    ['python3', PYTHON_SPEC],
+    ['node', NODE_SPEC],
+    ['nodejs', NODE_SPEC],
+    ['tsx', NODE_SPEC],
+    ['ts-node', NODE_SPEC],
+    ['ruby', { inlineExact: new Set(['-e']), valueFlags: new Set(['-r', '-I', '-C']) }],
+    ['perl', { inlineExact: new Set(['-e', '-E']), inlineRegex: /^-[A-Za-z0-9]*[eE]$/, valueFlags: new Set(['-I']) }],
+    ['php', { inlineExact: new Set(['-r']), valueFlags: new Set(['-c', '-d', '-z']) }],
+    ['rscript', { inlineExact: new Set(['-e']), valueFlags: new Set([]) }],
+    ['lua', { inlineExact: new Set(['-e']), valueFlags: new Set(['-l']) }],
+]);
+/** The language an interpreter runs (a JS runtime reads the file's extension). */
+const INTERPRETER_LANGUAGE = {
+    python: 'python',
+    python2: 'python',
+    python3: 'python',
+    ruby: 'ruby',
+    perl: 'perl',
+    php: 'php',
+    rscript: 'r',
+    lua: 'lua',
+};
+const EXTENSION_LANGUAGE = {
+    '.py': 'python',
+    '.js': 'javascript',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+    '.jsx': 'javascript',
+    '.ts': 'typescript',
+    '.mts': 'typescript',
+    '.cts': 'typescript',
+    '.tsx': 'typescript',
+    '.rb': 'ruby',
+    '.pl': 'perl',
+    '.php': 'php',
+    '.r': 'r',
+    '.lua': 'lua',
+    '.sh': 'shell',
+    '.bash': 'shell',
+    '.zsh': 'shell',
+    '.ksh': 'shell',
+};
+/** Language named by a `#!` line, or null. */
+function shebangLanguage(content) {
+    const nl = content.indexOf('\n');
+    const shebang = (nl === -1 ? content : content.slice(0, nl)).trim();
+    if (!shebang.startsWith('#!'))
+        return null;
+    if (/\bpython[23]?\b/.test(shebang))
+        return 'python';
+    if (/\b(node|nodejs|deno|bun)\b/.test(shebang))
+        return 'javascript';
+    if (/\b(tsx|ts-node)\b/.test(shebang))
+        return 'typescript';
+    if (/\bruby\b/.test(shebang))
+        return 'ruby';
+    if (/\bperl\b/.test(shebang))
+        return 'perl';
+    if (/\bphp\b/.test(shebang))
+        return 'php';
+    if (/\bRscript\b/.test(shebang))
+        return 'r';
+    if (/\blua\b/.test(shebang))
+        return 'lua';
+    if (/\b(sh|bash|zsh|dash|ksh|ash)\b/.test(shebang))
+        return 'shell';
+    return null;
+}
+/** Language of a file an interpreter (or the kernel, via its shebang) runs. */
+function languageOf(abs, content, interpreter) {
+    const byInterpreter = interpreter ? INTERPRETER_LANGUAGE[interpreter] : undefined;
+    if (byInterpreter)
+        return byInterpreter;
+    const byExtension = EXTENSION_LANGUAGE[extname(abs).toLowerCase()];
+    if (interpreter)
+        return byExtension === 'typescript' ? 'typescript' : 'javascript';
+    return shebangLanguage(content) ?? byExtension ?? 'shell';
+}
+/** Extensions a JS runtime (`bun`, `deno`) runs as a file rather than a script name. */
+const JS_RUNTIME_FILE_EXT = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx']);
+/**
+ * `deno run` flags that take a value as the next token. Most deno flags are
+ * written `--flag=value` or carry no value, so the list is short.
+ */
+const DENO_VALUE_FLAGS = new Set(['--config', '-c', '--import-map', '--lock', '--cert', '--location', '--env-file', '--inspect']);
+/** `npx` / `bunx` flags that take a value as the next token. */
+const NPX_VALUE_FLAGS = new Set(['-p', '--package', '-c', '--call']);
+/** `uv run` flags that take a value as the next token. */
+const UV_RUN_VALUE_FLAGS = new Set([
+    '--with',
+    '--with-editable',
+    '--with-requirements',
+    '--python',
+    '-p',
+    '--project',
+    '--directory',
+    '--package',
+    '--extra',
+    '--group',
+    '--env-file',
+    '--index',
+    '--index-url',
+]);
+function isOp(tok) {
+    return typeof tok === 'object' && tok !== null && 'op' in tok;
+}
+function tokenText(tok) {
+    if (typeof tok === 'string')
+        return tok;
+    if (typeof tok === 'object' && tok !== null && 'pattern' in tok)
+        return tok.pattern;
+    return null;
+}
+/** Lower-cased basename of an executable token, leading backslash stripped (`\rm` → `rm`). */
+function canonicalName(tok) {
+    let t = tok;
+    if (t.startsWith('\\'))
+        t = t.slice(1);
+    const base = t.split('/').pop() ?? t;
+    return base.toLowerCase();
+}
+/** Does this executable token name a file path (rather than a bare PATH command)? */
+function isPathToken(tok) {
+    return tok.includes('/');
+}
+function normalizeMaxBytes(v) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0)
+        return DEFAULT_MAX_BYTES;
+    return Math.min(Math.floor(v), HARD_MAX_BYTES);
+}
+const DEFAULT_FS = {
+    existsSync: (p) => nodeFs.existsSync(p),
+    readFileSync: (p, enc) => nodeFs.readFileSync(p, enc),
+    statSync: (p) => {
+        const s = nodeFs.statSync(p);
+        return { size: s.size, isFile: () => s.isFile() };
+    },
+    openSync: (p, flags) => nodeFs.openSync(p, flags),
+    readSync: (fd, buffer, offset, length, position) => nodeFs.readSync(fd, buffer, offset, length, position),
+    closeSync: (fd) => nodeFs.closeSync(fd),
+};
+/** Resolve a (possibly relative) script path against cwd. No `~` / `$VAR` expansion. */
+function resolvePath(cwd, rel) {
+    if (isAbsolute(rel))
+        return rel;
+    return pathResolve(cwd && cwd.length > 0 ? cwd : '.', rel);
+}
+/** Exists AND (when the fs can tell) is a regular file. Never throws. */
+function pathExistsAsFile(fsLike, abs) {
+    try {
+        if (!fsLike.existsSync(abs))
+            return false;
+        try {
+            const st = fsLike.statSync(abs);
+            if (st && typeof st.isFile === 'function' && !st.isFile())
+                return false;
+        }
+        catch {
+            /* existsSync already said yes; stat is only a refinement */
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sliceToBytes(text, maxBytes) {
+    return Buffer.from(text, 'utf8').subarray(0, maxBytes).toString('utf8');
+}
+/** Bounded read. Returns null on any read failure. Never throws. */
+function safeRead(fsLike, abs, maxBytes) {
+    try {
+        let size = -1;
+        try {
+            const st = fsLike.statSync(abs);
+            if (st && typeof st.size === 'number')
+                size = st.size;
+        }
+        catch {
+            /* fall through: read the whole thing and bound by byte length */
+        }
+        // Genuine partial read when the file is oversized and the fd API is present.
+        if (size > maxBytes && typeof fsLike.openSync === 'function' && typeof fsLike.readSync === 'function') {
+            const fd = fsLike.openSync(abs, 'r');
+            try {
+                const buf = Buffer.alloc(maxBytes);
+                const n = fsLike.readSync(fd, buf, 0, maxBytes, 0);
+                return { content: buf.subarray(0, Math.max(0, n)).toString('utf8'), truncated: true };
+            }
+            finally {
+                try {
+                    fsLike.closeSync?.(fd);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+        }
+        const raw = fsLike.readFileSync(abs, 'utf8');
+        const text = typeof raw === 'string' ? raw : raw == null ? '' : String(raw);
+        if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+            return { content: sliceToBytes(text, maxBytes), truncated: true };
+        }
+        return { content: text, truncated: size > maxBytes };
+    }
+    catch {
+        return null;
+    }
+}
+/** Trailing backslash count is odd → the line continues onto the next one. */
+function endsWithOddBackslash(line) {
+    const m = /\\+$/.exec(line);
+    return m ? m[0].length % 2 === 1 : false;
+}
+function pushCommandLine(out, line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0)
+        return;
+    if (trimmed.startsWith('#'))
+        return; // full-line comment
+    out.push(trimmed);
+}
+/**
+ * Split shell-script text into logical command lines. Heredoc bodies are
+ * stripped first (their content is data, not commands), `\`-continuations are
+ * joined, blank and comment-only lines are dropped. Each line is left whole —
+ * the evaluator's own normalizer splits a line on `;`/`&&`/`||`/`|`.
+ */
+function splitShellScriptLines(content) {
+    let stripped;
+    try {
+        stripped = stripHeredocBodies(content);
+    }
+    catch {
+        stripped = content;
+    }
+    const rawLines = stripped.split(/\r?\n/);
+    const out = [];
+    let acc = null;
+    for (const rawLine of rawLines) {
+        const current = acc === null ? rawLine : acc + rawLine;
+        if (endsWithOddBackslash(rawLine)) {
+            acc = current.replace(/\\$/, '');
+            continue;
+        }
+        acc = null;
+        pushCommandLine(out, current);
+    }
+    if (acc !== null)
+        pushCommandLine(out, acc);
+    return out;
+}
+/** Split a command line into simple-command argv arrays on segment boundaries. */
+function segmentsOf(command) {
+    let tokens;
+    try {
+        tokens = shellParse(stripHeredocBodies(command), (key) => `$${key}`);
+    }
+    catch {
+        return [];
+    }
+    const segments = [];
+    let argv = [];
+    const flush = () => {
+        if (argv.length > 0)
+            segments.push(argv);
+        argv = [];
+    };
+    for (const tok of tokens) {
+        if (isOp(tok)) {
+            if (BOUNDARY_OPS.has(tok.op))
+                flush();
+            // Redirect operators and their operands are left out of argv: a redirect
+            // target is never the executable, which is the first non-flag token.
+            continue;
+        }
+        const text = tokenText(tok);
+        if (text !== null)
+            argv.push(text);
+    }
+    flush();
+    return segments;
+}
+/** Skip flags from `i`, consuming the next token after a flag of `valueFlags`. */
+function skipFlags(argv, i, valueFlags) {
+    while (i < argv.length && argv[i].startsWith('-')) {
+        if (valueFlags.has(argv[i]))
+            i++;
+        i++;
+    }
+    return i;
+}
+/**
+ * Drop leading `VAR=value` assignments, transparent wrappers (`sudo`, `env …`)
+ * and the launchers that run a tool from a package environment (`npx`, `bunx`,
+ * `pnpm exec`, `yarn exec`, `uv run`, `poetry run`, `pipenv run`), so the
+ * interpreter they start is what the caller sees. `uv run a.py` runs the file
+ * with Python: it comes back as `python a.py`.
+ */
+function peelPrefixes(argv) {
+    let i = 0;
+    while (i < argv.length) {
+        const tok = argv[i];
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tok)) {
+            i++;
+            continue;
+        }
+        if (TRANSPARENT_PREFIXES.has(tok)) {
+            i++;
+            if (tok === 'env') {
+                while (i < argv.length && (argv[i].startsWith('-') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(argv[i]))) {
+                    if (argv[i] === '-u' || argv[i] === '--unset')
+                        i++;
+                    i++;
+                }
+            }
+            continue;
+        }
+        const name = canonicalName(tok);
+        const sub = argv[i + 1];
+        if (name === 'npx' || name === 'bunx' || name === 'pnpx') {
+            i = skipFlags(argv, i + 1, NPX_VALUE_FLAGS);
+            continue;
+        }
+        if ((name === 'pnpm' && (sub === 'exec' || sub === 'dlx')) || (name === 'yarn' && (sub === 'exec' || sub === 'dlx'))) {
+            i = skipFlags(argv, i + 2, NPX_VALUE_FLAGS);
+            continue;
+        }
+        if (name === 'uv' && sub === 'run') {
+            i = skipFlags(argv, i + 2, UV_RUN_VALUE_FLAGS);
+            const next = argv[i];
+            if (next !== undefined && extname(next).toLowerCase() === '.py')
+                return ['python', ...argv.slice(i)];
+            continue;
+        }
+        if ((name === 'poetry' || name === 'pipenv') && sub === 'run') {
+            i += 2;
+            continue;
+        }
+        break;
+    }
+    return argv.slice(i);
+}
+/** Locate the script-file argument of an interpreter, or report it is inline. */
+function findInterpreterScript(args, spec) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--')
+            return { inline: false, script: args[i + 1] ?? null };
+        if (spec.inlineExact.has(a))
+            return { inline: true, script: null };
+        if (spec.moduleExact?.has(a))
+            return { inline: true, script: null };
+        if (spec.inlineRegex && spec.inlineRegex.test(a))
+            return { inline: true, script: null };
+        if (spec.valueFlags.has(a)) {
+            i++; // this flag consumes the next token as its value
+            continue;
+        }
+        if (a.startsWith('-'))
+            continue; // some other flag
+        return { inline: false, script: a };
+    }
+    return { inline: false, script: null };
+}
+/**
+ * Classify a directly-executed file (`./x`) as a shell or interpreter script:
+ * the shebang first, then the extension; a file with neither is executed as a
+ * program, with nothing better to go on, so its lines are scanned as shell.
+ */
+function classifyDirect(content, abs) {
+    return languageOf(abs, content) === 'shell' ? 'shell' : 'interpreter';
+}
+function readShellFile(abs, fsLike, maxBytes, notes) {
+    const read = safeRead(fsLike, abs, maxBytes);
+    if (!read) {
+        return { kind: 'shell', path: abs, language: 'shell', shellCommands: [], truncated: false, notes: [...notes, 'read-failed'] };
+    }
+    const n = [...notes];
+    if (read.truncated)
+        n.push('truncated');
+    return {
+        kind: 'shell',
+        path: abs,
+        language: 'shell',
+        shellCommands: splitShellScriptLines(read.content),
+        content: read.content,
+        truncated: read.truncated,
+        notes: n,
+    };
+}
+function readInterpreterFile(abs, fsLike, maxBytes, notes, interpreter) {
+    const read = safeRead(fsLike, abs, maxBytes);
+    if (!read) {
+        return {
+            kind: 'interpreter',
+            path: abs,
+            language: languageOf(abs, '', interpreter),
+            shellCommands: [],
+            truncated: false,
+            notes: [...notes, 'read-failed'],
+        };
+    }
+    const n = [...notes];
+    if (read.truncated)
+        n.push('truncated');
+    return {
+        kind: 'interpreter',
+        path: abs,
+        language: languageOf(abs, read.content, interpreter),
+        content: read.content,
+        shellCommands: [],
+        truncated: read.truncated,
+        notes: n,
+    };
+}
+function resolveShellInterpreter(args, cwd, fsLike, maxBytes) {
+    const { script } = findInterpreterScript(args, SHELL_SPEC);
+    if (!script)
+        return null; // inline (`-c`), stdin (`-s`) or no file
+    const abs = resolvePath(cwd, script);
+    if (!pathExistsAsFile(fsLike, abs))
+        return null;
+    return readShellFile(abs, fsLike, maxBytes, ['via:shell-interpreter']);
+}
+function resolveInterpreter(name, args, cwd, fsLike, maxBytes) {
+    const spec = INTERPRETERS.get(name);
+    if (!spec)
+        return null;
+    const { script } = findInterpreterScript(args, spec);
+    if (!script)
+        return null; // inline (`-c`/`-e`), module (`-m`) or no file
+    const abs = resolvePath(cwd, script);
+    if (!pathExistsAsFile(fsLike, abs))
+        return null;
+    return readInterpreterFile(abs, fsLike, maxBytes, [`via:interpreter:${name}`], name);
+}
+/**
+ * `deno run [flags] <file>`. Any other deno subcommand (`eval`, `test`, `fmt`,
+ * `task`…) names no script file to read here.
+ */
+function resolveDeno(args, cwd, fsLike, maxBytes) {
+    if (args[0] !== 'run')
+        return null;
+    for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (DENO_VALUE_FLAGS.has(a)) {
+            i++;
+            continue;
+        }
+        if (a.startsWith('-'))
+            continue;
+        const abs = resolvePath(cwd, a);
+        if (!pathExistsAsFile(fsLike, abs))
+            return null;
+        return readInterpreterFile(abs, fsLike, maxBytes, ['via:interpreter:deno'], 'deno');
+    }
+    return null;
+}
+/**
+ * `bun <file>` / `bun run <file>`: a JS/TS file that exists is run as a file;
+ * anything else (`bun run build`, `bun install`) is left to the package-script
+ * path.
+ */
+function resolveBunFile(args, cwd, fsLike, maxBytes) {
+    let i = 0;
+    while (i < args.length && args[i].startsWith('-'))
+        i++;
+    if (args[i] === 'run') {
+        i++;
+        while (i < args.length && args[i].startsWith('-'))
+            i++;
+    }
+    const candidate = args[i];
+    if (!candidate || !JS_RUNTIME_FILE_EXT.has(extname(candidate).toLowerCase()))
+        return null;
+    const abs = resolvePath(cwd, candidate);
+    if (!pathExistsAsFile(fsLike, abs))
+        return null;
+    return readInterpreterFile(abs, fsLike, maxBytes, ['via:interpreter:bun'], 'bun');
+}
+function resolveDirectExec(cmdTok, cwd, fsLike, maxBytes) {
+    const abs = resolvePath(cwd, cmdTok);
+    if (!pathExistsAsFile(fsLike, abs))
+        return null;
+    const read = safeRead(fsLike, abs, maxBytes);
+    const base = ['via:direct-exec'];
+    if (!read)
+        return { kind: 'shell', path: abs, shellCommands: [], truncated: false, notes: [...base, 'read-failed'] };
+    const notes = [...base];
+    if (read.truncated)
+        notes.push('truncated');
+    if (classifyDirect(read.content, abs) === 'interpreter') {
+        return {
+            kind: 'interpreter',
+            path: abs,
+            language: languageOf(abs, read.content),
+            content: read.content,
+            shellCommands: [],
+            truncated: read.truncated,
+            notes,
+        };
+    }
+    return {
+        kind: 'shell',
+        path: abs,
+        language: 'shell',
+        shellCommands: splitShellScriptLines(read.content),
+        content: read.content,
+        truncated: read.truncated,
+        notes,
+    };
+}
+/** The whole body of a script is exactly `npm|pnpm|yarn run <name>` → the inner name. */
+function matchSinglePmRun(body) {
+    const m = /^\s*(?:npm|pnpm|yarn|bun)\s+(?:run|run-script)\s+([A-Za-z0-9:@._-]+)\s*$/.exec(body);
+    return m ? m[1] : null;
+}
+function resolveNpmScript(args, cwd, fsLike, maxBytes) {
+    let i = 0;
+    while (i < args.length && args[i].startsWith('-'))
+        i++;
+    const sub = args[i];
+    if (sub !== 'run' && sub !== 'run-script')
+        return null;
+    i++;
+    while (i < args.length && args[i].startsWith('-'))
+        i++;
+    const scriptName = args[i];
+    if (!scriptName)
+        return null;
+    const pkgPath = resolvePath(cwd, 'package.json');
+    if (!pathExistsAsFile(fsLike, pkgPath))
+        return null;
+    const read = safeRead(fsLike, pkgPath, maxBytes);
+    if (!read)
+        return null;
+    let pkg;
+    try {
+        pkg = JSON.parse(read.content);
+    }
+    catch {
+        return null;
+    }
+    if (typeof pkg !== 'object' || pkg === null)
+        return null;
+    const scriptsVal = pkg.scripts;
+    if (typeof scriptsVal !== 'object' || scriptsVal === null)
+        return null;
+    const scripts = scriptsVal;
+    const bodyVal = scripts[scriptName];
+    if (typeof bodyVal !== 'string')
+        return null;
+    const notes = ['via:npm-script'];
+    let body = bodyVal;
+    // Follow at most ONE level of `npm run <other>` indirection.
+    const inner = matchSinglePmRun(body);
+    if (inner && inner !== scriptName) {
+        const innerBodyVal = scripts[inner];
+        if (typeof innerBodyVal === 'string') {
+            notes.push(`followed npm run indirection: ${scriptName} -> ${inner}`);
+            body = innerBodyVal;
+            if (matchSinglePmRun(body))
+                notes.push('further npm run indirection not followed');
+        }
+    }
+    return { kind: 'npm-script', scriptName, shellCommands: [body], truncated: read.truncated, notes };
+}
+function detectInSegment(rawArgv, cwd, fsLike, maxBytes) {
+    const argv = peelPrefixes(rawArgv);
+    if (argv.length === 0)
+        return null;
+    const cmdTok = argv[0];
+    const rest = argv.slice(1);
+    const canonical = canonicalName(cmdTok);
+    if (SHELL_INTERPRETERS.has(canonical))
+        return resolveShellInterpreter(rest, cwd, fsLike, maxBytes);
+    if (INTERPRETERS.has(canonical))
+        return resolveInterpreter(canonical, rest, cwd, fsLike, maxBytes);
+    if (canonical === 'deno')
+        return resolveDeno(rest, cwd, fsLike, maxBytes);
+    if (canonical === 'bun') {
+        const file = resolveBunFile(rest, cwd, fsLike, maxBytes);
+        if (file)
+            return file;
+    }
+    if (NPM_RUNNERS.has(canonical))
+        return resolveNpmScript(rest, cwd, fsLike, maxBytes);
+    if (isPathToken(cmdTok))
+        return resolveDirectExec(cmdTok, cwd, fsLike, maxBytes);
+    return null;
+}
+/**
+ * Given a raw Bash command, return the local file/script it executes, read and
+ * ready to re-feed to the evaluator — or `null` when the command executes no
+ * local file (a plain command, an inline interpreter string, a missing file).
+ *
+ * Never throws. Reads are bounded by `opts.maxBytes` (default 256 KB).
+ */
+export function resolveExecutedScript(command, opts) {
+    try {
+        if (typeof command !== 'string' || command.trim().length === 0)
+            return null;
+        const fsLike = opts?.fs ?? DEFAULT_FS;
+        const cwd = typeof opts?.cwd === 'string' ? opts.cwd : '';
+        const maxBytes = normalizeMaxBytes(opts?.maxBytes);
+        for (const argv of segmentsOf(command)) {
+            const r = detectInSegment(argv, cwd, fsLike, maxBytes);
+            if (r)
+                return r;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=script-resolve.js.map