@cybedefend/vibedefend 1.5.0 → 1.6.0

package/dist/guards-evaluator/normalize.js

@@ -0,0 +1,716 @@
+/**
+ * Level 0 core — de-obfuscate + normalize a raw Bash command STRING into the
+ * list of EFFECTIVE simple commands it will actually run.
+ *
+ * The current evaluator matches its rule regexes against the RAW command, so
+ * trivial rewrites (`/bin/rm`, `\rm`, `--recursive --force`, `.e""nv`,
+ * `bash -c "<here>"`, `eval "<here>"`, `$( … )`, a heredoc body, `xargs`,
+ * `find … -exec`) slip through as `allow`. `normalizeCommand` unfolds those
+ * rewrites so a downstream triage pass (triage.ts) can reason about what runs,
+ * not about how it was spelled.
+ *
+ * Design contract (see analysis-types.ts):
+ *   - PURE: no I/O, no network, no clock. Disk resolution lives elsewhere.
+ *   - NEVER THROWS: any blindness (unbalanced quotes, an indirect executable,
+ *     nesting past the cap) sets `incomplete: true` with a stable note and
+ *     returns what was recovered. Blindness fails toward "look closer".
+ *   - ALLOCATION-LIGHT: this runs on every Bash tool call on the hot path.
+ *
+ * The tokenizer is `shell-quote` (`parse`), the same one `preprocess.ts` and
+ * `shell-writes.ts` use, driven with an env function `(k) => '$' + k` so a
+ * `$VAR` reference is preserved verbatim instead of being substituted to the
+ * empty string (which would delete the literal every rule matches on).
+ */
+import { parse as shellParse } from 'shell-quote';
+// ---------------------------------------------------------------------------
+// Tunables (bounds keep a pathological input from blowing up the hot path)
+// ---------------------------------------------------------------------------
+/** Deepest nesting level we expand; past it we stop and note 'depth-cap'. */
+const MAX_DEPTH = 3;
+/** Hard ceiling on emitted commands, so a fork-bomb of segments can't blow up. */
+const MAX_COMMANDS = 256;
+/** Hard ceiling on substitutions pulled from one command. */
+const MAX_SUBST = 64;
+/** The stored `raw` field is bounded; the tokenizer still sees the full text. */
+const RAW_CLIP = 2000;
+/** env function for shell-quote: keep `$VAR` as the literal `$VAR`. */
+const SQ_ENV = (key) => '$' + key;
+// ---------------------------------------------------------------------------
+// Wrapper / prefix / interpreter vocabulary
+// ---------------------------------------------------------------------------
+/** Interpreters whose `-c` argument is itself a shell command. */
+const SHELL_INTERPRETERS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh']);
+/** Interpreters whose heredoc body is code worth re-reading. */
+const HEREDOC_INTERPRETERS = new Set([
+    'bash',
+    'sh',
+    'zsh',
+    'dash',
+    'ksh',
+    'python',
+    'python2',
+    'python3',
+    'node',
+    'nodejs',
+    'ruby',
+    'perl',
+    'php',
+]);
+/** Transparent leading wrappers that don't change what ultimately runs. */
+const TRANSPARENT_PREFIXES = new Set([
+    'sudo',
+    'doas',
+    'nohup',
+    'command',
+    'time',
+    'nice',
+    'stdbuf',
+    'setsid',
+    'env',
+]);
+/**
+ * Per-prefix options that CONSUME the following token as their value, so the
+ * peeler does not mistake that value for the wrapped command. e.g. in
+ * `sudo -u root rm …`, `-u` eats `root`; `rm` is the real command.
+ */
+const PREFIX_VALUE_OPTS = {
+    sudo: new Set([
+        '-u', '--user', '-g', '--group', '-p', '--prompt', '-C', '--close-from',
+        '-h', '--host', '-r', '--role', '-t', '--type', '-U', '--other-user',
+        '-R', '--chroot', '-D', '--chdir',
+    ]),
+    doas: new Set(['-u', '-C']),
+    env: new Set(['-u', '--unset', '-S', '--split-string', '-C', '--chdir']),
+    nice: new Set(['-n', '--adjustment']),
+    stdbuf: new Set(['-i', '--input', '-o', '--output', '-e', '--error']),
+    time: new Set(['-o', '--output', '-f', '--format']),
+    command: new Set(),
+    nohup: new Set(),
+    setsid: new Set(),
+};
+/** `xargs` options that consume the following token as their value. */
+const XARGS_VALUE_OPTS = new Set([
+    '-I', '--replace', '-n', '--max-args', '-L', '--max-lines', '-P',
+    '--max-procs', '-s', '--max-chars', '-d', '--delimiter', '-E', '--eof',
+    '-a', '--arg-file', '--process-slot-var',
+]);
+/** Operators that end a simple command (segment boundary). */
+const SEPARATOR_OPS = new Set([';', '&&', '||', '|', '|&']);
+/** Operators whose following token is a redirect target, not an argument. */
+const REDIRECT_OPS = new Set([
+    '>', '>>', '<', '>|', '&>', '&>>', '<>', '>&', '<&', '<<<', '<<', '<<-',
+]);
+/**
+ * A small, documented, extensible per-executable long→short flag map, so
+ * `rm --recursive --force` contributes the same `{'r','f'}` as `rm -rf`.
+ * Keyed by canonical (lower-cased) executable; letters carry the real case
+ * the tool uses (chmod/chown recursive is `-R`, grep recursive is `-r`).
+ * Unknown long flags add no letter — they still appear in `longFlags`.
+ */
+const LONG_TO_SHORT = {
+    rm: { recursive: 'r', force: 'f', verbose: 'v', interactive: 'i', dir: 'd' },
+    rmdir: { verbose: 'v', parents: 'p' },
+    cp: {
+        recursive: 'r', force: 'f', verbose: 'v', interactive: 'i',
+        archive: 'a', link: 'l', 'symbolic-link': 's', 'no-clobber': 'n',
+    },
+    mv: { force: 'f', verbose: 'v', interactive: 'i', 'no-clobber': 'n' },
+    chmod: { recursive: 'R', verbose: 'v', changes: 'c', silent: 'f', quiet: 'f' },
+    chown: { recursive: 'R', verbose: 'v', changes: 'c', silent: 'f', quiet: 'f' },
+    grep: {
+        recursive: 'r', 'ignore-case': 'i', 'invert-match': 'v',
+        'line-number': 'n', 'word-regexp': 'w', count: 'c',
+        'files-with-matches': 'l', 'extended-regexp': 'E', 'fixed-strings': 'F',
+    },
+    ls: {
+        all: 'a', 'almost-all': 'A', recursive: 'R', reverse: 'r',
+        'human-readable': 'h', directory: 'd', inode: 'i', size: 's',
+    },
+};
+/** Opening token of a heredoc redirect: `<<EOF`, `<<-EOF`, `<<'EOF'`, `<<"EOF"`. */
+const HEREDOC_OPEN = /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/;
+function isGlob(t) {
+    return typeof t === 'object' && t !== null && 'pattern' in t;
+}
+function isOperator(t) {
+    return typeof t === 'object' && t !== null && 'op' in t && !('pattern' in t);
+}
+/** A glob keeps its pattern text; an operator/comment has no argv text. */
+function tokenText(t) {
+    if (typeof t === 'string')
+        return t;
+    if (isGlob(t))
+        return t.pattern;
+    return null;
+}
+function clip(s, n) {
+    return s.length > n ? s.slice(0, n) : s;
+}
+function emit(acc, cmd) {
+    if (acc.commands.length >= MAX_COMMANDS) {
+        acc.incomplete = true;
+        acc.notes.add('command-cap');
+        return false;
+    }
+    acc.commands.push(cmd);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Executable canonicalization & prefix peeling
+// ---------------------------------------------------------------------------
+/** True when the executable is supplied indirectly (`$X`, `${X}`, `$(…)`, `` `…` ``). */
+function isIndirect(tok) {
+    return /^\$/.test(tok) || tok.includes('`');
+}
+/**
+ * Canonical executable name: strip the directory, strip a single leading
+ * backslash, lower-case the basename. `/usr/bin/rm` → `rm`, `\rm` → `rm`,
+ * `RM` → `rm`.
+ */
+function canonicalExec(raw) {
+    let base = raw.split('/').pop() ?? raw;
+    if (base.startsWith('\\'))
+        base = base.slice(1);
+    return base.toLowerCase();
+}
+/**
+ * Peel leading `VAR=value` assignments and transparent wrappers (`sudo`,
+ * `env FOO=bar`, `nice -n 10`, …) so the first remaining token is the real
+ * command. Returns the remainder; an empty remainder means the segment was
+ * all assignments/wrappers (the caller then keeps the original argv).
+ */
+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++; // leading VAR=value assignment
+            continue;
+        }
+        if (TRANSPARENT_PREFIXES.has(tok)) {
+            const prefix = tok;
+            i++;
+            const valueOpts = PREFIX_VALUE_OPTS[prefix] ?? new Set();
+            while (i < argv.length) {
+                const a = argv[i];
+                // `env VAR=val cmd` — drop env's own assignments too.
+                if (prefix === 'env' && /^[A-Za-z_][A-Za-z0-9_]*=/.test(a)) {
+                    i++;
+                    continue;
+                }
+                if (a.startsWith('-') && a.length > 1) {
+                    if (!a.includes('=') && valueOpts.has(a))
+                        i += 2;
+                    else
+                        i++;
+                    continue;
+                }
+                break;
+            }
+            continue;
+        }
+        break;
+    }
+    return argv.slice(i);
+}
+// ---------------------------------------------------------------------------
+// Segment splitting & argv collection (token level)
+// ---------------------------------------------------------------------------
+/**
+ * Split a line's tokens into segments on `;`, `&&`, `||`, `|`, `|&`, `&`.
+ * `&` is a separator UNLESS it is the `&>` redirect spelled as two ops.
+ */
+function splitSegments(tokens) {
+    const segs = [];
+    let cur = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        if (isOperator(tok)) {
+            const op = tok.op;
+            if (op === '&') {
+                const nxt = tokens[i + 1];
+                if (isOperator(nxt) && (nxt.op === '>' || nxt.op === '>>')) {
+                    cur.push(tok); // part of `&>` / `&>>`
+                    continue;
+                }
+                segs.push(cur);
+                cur = [];
+                continue;
+            }
+            if (SEPARATOR_OPS.has(op)) {
+                segs.push(cur);
+                cur = [];
+                continue;
+            }
+            cur.push(tok);
+            continue;
+        }
+        cur.push(tok);
+    }
+    segs.push(cur);
+    return segs.filter((s) => s.length > 0);
+}
+/**
+ * Collect the argv of one segment: the string/glob tokens that are the
+ * executable, flags and arguments. Command-substitution content (`$( … )`)
+ * is dropped (it is recovered separately via `findSubstitutions`), a
+ * substitution standing in the executable position leaves a `$(` marker so
+ * the command is flagged indirect, and redirect targets are dropped.
+ */
+function collectArgv(tokens) {
+    const argv = [];
+    let substDepth = 0;
+    let skipTarget = false;
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        if (isOperator(tok)) {
+            const op = tok.op;
+            if (op === '(') {
+                // A `$(` command substitution only when preceded by the `$` marker.
+                if (tokens[i - 1] === '$') {
+                    if (substDepth === 0 && argv.length === 0)
+                        argv.push('$(');
+                    substDepth++;
+                }
+                continue;
+            }
+            if (op === ')') {
+                if (substDepth > 0)
+                    substDepth--;
+                continue;
+            }
+            if (substDepth > 0)
+                continue;
+            if (REDIRECT_OPS.has(op)) {
+                // `2> err` — drop the fd number that precedes the redirect.
+                if (argv.length > 0 && /^\d+$/.test(argv[argv.length - 1]))
+                    argv.pop();
+                skipTarget = true;
+                continue;
+            }
+            continue; // any other op inside a segment is structural, ignore
+        }
+        if (substDepth > 0)
+            continue;
+        const text = tokenText(tok);
+        if (text === null)
+            continue; // a comment
+        // The `$` marker just before a `$(` substitution is not an argument.
+        const next = tokens[i + 1];
+        if (text === '$' && isOperator(next) && next.op === '(')
+            continue;
+        if (skipTarget) {
+            skipTarget = false;
+            continue;
+        }
+        argv.push(text);
+    }
+    return argv;
+}
+// ---------------------------------------------------------------------------
+// Building one EffectiveCommand
+// ---------------------------------------------------------------------------
+function buildEffectiveCommand(eff, via, depth, rawText, acc) {
+    const rawExecutable = eff[0] ?? '';
+    let executable;
+    if (isIndirect(rawExecutable)) {
+        executable = '';
+        acc.incomplete = true;
+        acc.notes.add('indirect-exec');
+    }
+    else {
+        executable = canonicalExec(rawExecutable);
+    }
+    const flagLetters = new Set();
+    const longFlags = [];
+    const args = [];
+    let endOfOpts = false;
+    for (let i = 1; i < eff.length; i++) {
+        const t = eff[i];
+        if (endOfOpts) {
+            args.push(t);
+            continue;
+        }
+        if (t === '--') {
+            endOfOpts = true;
+            continue;
+        }
+        if (t.startsWith('--') && t.length > 2) {
+            const m = /^--([A-Za-z][A-Za-z0-9-]*)/.exec(t);
+            if (m) {
+                longFlags.push(m[1]);
+                const letter = LONG_TO_SHORT[executable]?.[m[1]];
+                if (letter)
+                    flagLetters.add(letter);
+            }
+            continue;
+        }
+        if (t.startsWith('-') && t.length > 1) {
+            const m = /^-([A-Za-z]+)/.exec(t);
+            if (m)
+                for (const ch of m[1])
+                    flagLetters.add(ch);
+            continue;
+        }
+        args.push(t);
+    }
+    return {
+        executable,
+        rawExecutable,
+        args,
+        flagLetters,
+        longFlags,
+        raw: clip(rawText, RAW_CLIP),
+        via,
+        depth,
+    };
+}
+// ---------------------------------------------------------------------------
+// Per-segment nested-construct extraction
+// ---------------------------------------------------------------------------
+/** The command a shell interpreter runs via `-c` (`-c`, `-lc`, `-xc`, …). */
+function shellCArg(eff) {
+    for (let i = 1; i < eff.length; i++) {
+        if (/^-[A-Za-z]*c[A-Za-z]*$/.test(eff[i])) {
+            return i + 1 < eff.length ? eff[i + 1] : null;
+        }
+    }
+    return null;
+}
+/** The command `xargs` will run: skip xargs' own options (and their values). */
+function xargsCommand(eff) {
+    let i = 1; // skip `xargs`
+    while (i < eff.length) {
+        const a = eff[i];
+        if (a.startsWith('-') && a.length > 1) {
+            if (!a.includes('=') && XARGS_VALUE_OPTS.has(a))
+                i += 2;
+            else
+                i++;
+            continue;
+        }
+        break;
+    }
+    if (i >= eff.length)
+        return null;
+    return eff.slice(i).join(' ');
+}
+/** The command `find … -exec`/`-execdir` will run, up to its `;`/`+` terminator. */
+function findExecCommand(eff) {
+    let idx = -1;
+    for (let i = 1; i < eff.length; i++) {
+        const t = eff[i];
+        if (t === '-exec' || t === '-execdir' || t === '-ok' || t === '-okdir') {
+            idx = i;
+            break;
+        }
+    }
+    if (idx < 0 || idx + 1 >= eff.length)
+        return null;
+    const rest = eff.slice(idx + 1);
+    const term = rest.findIndex((t) => t === ';' || t === '+' || t === '\\;');
+    const cmdTokens = term >= 0 ? rest.slice(0, term) : rest;
+    if (cmdTokens.length === 0)
+        return null;
+    return cmdTokens.join(' ');
+}
+// ---------------------------------------------------------------------------
+// Heredoc extraction
+// ---------------------------------------------------------------------------
+/** First command word of a line, with prefixes peeled and canonicalized. */
+function firstCommandWord(line) {
+    const parts = line.trim().split(/\s+/).filter(Boolean);
+    const peeled = peelPrefixes(parts);
+    const eff = peeled.length > 0 ? peeled : parts;
+    return eff.length > 0 && !isIndirect(eff[0]) ? canonicalExec(eff[0]) : '';
+}
+/**
+ * Pull heredoc BODIES out of the command so their content (which may contain
+ * shell operators) never corrupts segmentation, and so an interpreter-fed
+ * body can be re-normalized. The opener line is kept with its `<<DELIM`
+ * redirect removed; `cat <<EOF` (data, not code) is still stripped but its
+ * `cat` interpreter is not in HEREDOC_INTERPRETERS, so it is never recursed.
+ */
+function extractHeredocs(raw) {
+    if (raw.indexOf('<<') === -1)
+        return { scrubbed: raw, heredocs: [] };
+    const lines = raw.split('\n');
+    const out = [];
+    const heredocs = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const m = HEREDOC_OPEN.exec(line);
+        if (!m) {
+            out.push(line);
+            i++;
+            continue;
+        }
+        const delim = m[2];
+        const openerNoHeredoc = line.slice(0, m.index) + line.slice(m.index + m[0].length);
+        out.push(openerNoHeredoc);
+        const interpreter = firstCommandWord(openerNoHeredoc);
+        i++;
+        const body = [];
+        while (i < lines.length && lines[i].trim() !== delim) {
+            body.push(lines[i]);
+            i++;
+        }
+        if (i < lines.length)
+            i++; // consume the terminator line
+        heredocs.push({ interpreter, body: body.join('\n') });
+    }
+    return { scrubbed: out.join('\n'), heredocs };
+}
+// ---------------------------------------------------------------------------
+// Command-substitution extraction (`$( … )` and backticks)
+// ---------------------------------------------------------------------------
+function captureParen(text, start) {
+    let depth = 1;
+    let i = start;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === '(')
+            depth++;
+        else if (c === ')') {
+            depth--;
+            if (depth === 0)
+                return { inner: text.slice(start, i), end: i + 1 };
+        }
+        i++;
+    }
+    return { inner: text.slice(start), end: text.length }; // unterminated
+}
+/** Skip an arithmetic expansion `$(( … ))` (not a command). */
+function skipArithmetic(text, at) {
+    let depth = 0;
+    let j = at + 1; // at the first '('
+    while (j < text.length) {
+        const c = text[j];
+        if (c === '(')
+            depth++;
+        else if (c === ')') {
+            depth--;
+            if (depth === 0)
+                return j + 1;
+        }
+        j++;
+    }
+    return text.length;
+}
+function findUnescapedBacktick(text, from) {
+    let i = from;
+    while (i < text.length) {
+        if (text[i] === '\\') {
+            i += 2;
+            continue;
+        }
+        if (text[i] === '`')
+            return i;
+        i++;
+    }
+    return -1;
+}
+/**
+ * Every command-substitution body in `text` (`$( … )` and backticks),
+ * honouring shell quoting: a substitution inside SINGLE quotes does not run
+ * (`echo '$(rm -rf ~)'`), so it is not extracted — avoiding a false positive;
+ * one inside DOUBLE quotes does run and is extracted. Arithmetic `$(( … ))`
+ * is skipped. Pure string scan, no tokenizer.
+ */
+function findSubstitutions(text) {
+    const out = [];
+    let i = 0;
+    let single = false;
+    let double = false;
+    while (i < text.length && out.length < MAX_SUBST) {
+        const c = text[i];
+        if (c === '\\' && !single) {
+            i += 2;
+            continue;
+        }
+        if (c === "'" && !double) {
+            single = !single;
+            i++;
+            continue;
+        }
+        if (c === '"' && !single) {
+            double = !double;
+            i++;
+            continue;
+        }
+        if (single) {
+            i++;
+            continue;
+        }
+        if (c === '$' && text[i + 1] === '(') {
+            if (text[i + 2] === '(') {
+                i = skipArithmetic(text, i + 1);
+                continue;
+            }
+            const { inner, end } = captureParen(text, i + 2);
+            if (inner.trim().length > 0)
+                out.push(inner);
+            i = end;
+            continue;
+        }
+        if (c === '`') {
+            const close = findUnescapedBacktick(text, i + 1);
+            if (close > i) {
+                const inner = text.slice(i + 1, close);
+                if (inner.trim().length > 0)
+                    out.push(inner);
+                i = close + 1;
+            }
+            else {
+                i = text.length; // unterminated
+            }
+            continue;
+        }
+        i++;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Recursion driver
+// ---------------------------------------------------------------------------
+function recurse(inner, via, depth, acc) {
+    if (depth > MAX_DEPTH) {
+        acc.incomplete = true;
+        acc.notes.add('depth-cap');
+        return;
+    }
+    if (acc.commands.length >= MAX_COMMANDS) {
+        acc.incomplete = true;
+        acc.notes.add('command-cap');
+        return;
+    }
+    analyze(inner, via, depth, acc);
+}
+/** Emit one best-effort command from a naive whitespace split (parse fallback). */
+function pushNaive(text, via, depth, acc) {
+    const parts = text.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return;
+    const peeled = peelPrefixes(parts);
+    const eff = peeled.length > 0 ? peeled : parts;
+    emit(acc, buildEffectiveCommand(eff, via, depth, text, acc));
+}
+function processSegment(segTokens, via, depth, acc) {
+    const argvFull = collectArgv(segTokens);
+    if (argvFull.length === 0)
+        return;
+    const peeled = peelPrefixes(argvFull);
+    const eff = peeled.length > 0 ? peeled : argvFull;
+    const rawText = argvFull.join(' ');
+    const cmd = buildEffectiveCommand(eff, via, depth, rawText, acc);
+    if (!emit(acc, cmd))
+        return;
+    const exe = cmd.executable;
+    if (exe === '')
+        return; // indirect executable: nothing concrete to recurse
+    const nextDepth = depth + 1;
+    if (SHELL_INTERPRETERS.has(exe)) {
+        const body = shellCArg(eff);
+        if (body !== null && body.trim().length > 0)
+            recurse(body, 'bash-c', nextDepth, acc);
+    }
+    else if (exe === 'eval') {
+        const body = eff.slice(1).join(' ');
+        if (body.trim().length > 0)
+            recurse(body, 'eval', nextDepth, acc);
+    }
+    else if (exe === 'xargs') {
+        const body = xargsCommand(eff);
+        if (body !== null && body.trim().length > 0)
+            recurse(body, 'xargs', nextDepth, acc);
+    }
+    else if (exe === 'find') {
+        const body = findExecCommand(eff);
+        if (body !== null && body.trim().length > 0)
+            recurse(body, 'exec', nextDepth, acc);
+    }
+}
+function analyze(raw, via, depth, acc) {
+    if (acc.commands.length >= MAX_COMMANDS) {
+        acc.incomplete = true;
+        acc.notes.add('command-cap');
+        return;
+    }
+    const { scrubbed, heredocs } = extractHeredocs(raw);
+    // Top-level segments, one tokenize per logical line (newline is a boundary
+    // that shell-quote otherwise flattens away).
+    for (const line of scrubbed.split('\n')) {
+        if (acc.commands.length >= MAX_COMMANDS)
+            break;
+        if (line.trim().length === 0)
+            continue;
+        let tokens;
+        try {
+            tokens = shellParse(line, SQ_ENV);
+        }
+        catch {
+            acc.incomplete = true;
+            acc.notes.add('parse-failed');
+            pushNaive(line, via, depth, acc);
+            continue;
+        }
+        for (const seg of splitSegments(tokens))
+            processSegment(seg, via, depth, acc);
+    }
+    // Command substitutions anywhere in this (heredoc-stripped) command.
+    for (const inner of findSubstitutions(scrubbed))
+        recurse(inner, 'subst', depth + 1, acc);
+    // Interpreter-fed heredoc bodies are code; re-normalize them.
+    for (const hd of heredocs) {
+        if (HEREDOC_INTERPRETERS.has(hd.interpreter) && hd.body.trim().length > 0) {
+            recurse(hd.body, 'heredoc', depth + 1, acc);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Normalize one raw Bash command string into the effective simple commands it
+ * will run. Pure and never throws: on any failure it returns what it recovered
+ * with `incomplete: true` and a stable note.
+ */
+export function normalizeCommand(raw) {
+    const acc = { commands: [], incomplete: false, notes: new Set() };
+    try {
+        if (typeof raw !== 'string') {
+            return { commands: [], incomplete: true, notes: ['invalid-input'] };
+        }
+        if (raw.trim().length === 0) {
+            return { commands: [], incomplete: false, notes: [] };
+        }
+        analyze(raw, 'top', 0, acc);
+        if (acc.commands.length === 0) {
+            // A non-empty input always yields at least one command.
+            pushNaive(raw, 'top', 0, acc);
+        }
+    }
+    catch {
+        acc.incomplete = true;
+        acc.notes.add('internal-error');
+        if (acc.commands.length === 0) {
+            try {
+                pushNaive(raw, 'top', 0, acc);
+            }
+            catch {
+                /* give up: return whatever we have, never throw */
+            }
+        }
+    }
+    return {
+        commands: acc.commands,
+        incomplete: acc.incomplete,
+        notes: [...acc.notes],
+    };
+}
+//# sourceMappingURL=normalize.js.map