@aetherai/aether 0.0.7 → 0.0.9

package/dist/CLI/packages/core/src/permissions/shell-semantics.js

@@ -1,1377 +0,0 @@
-/**
- * @license
- * Copyright 2025 Qwen team
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * Shell command semantic analysis for permission matching.
- *
- * Analyzes simple shell commands to extract "virtual tool operations" so that
- * Read / Edit / Write / WebFetch / ListFiles permission rules can match their
- * shell equivalents and prevent bypass via the shell tool.
- *
- * @example
- *   extractShellOperations('cat /etc/passwd', '/home/user')
- *   // → [{ virtualTool: 'read_file', filePath: '/etc/passwd' }]
- *
- * @example
- *   extractShellOperations('curl https://example.com/api', '/home/user')
- *   // → [{ virtualTool: 'web_fetch', domain: 'example.com' }]
- *
- * @example
- *   extractShellOperations('echo hi > /etc/motd', '/home/user')
- *   // → [{ virtualTool: 'write_file', filePath: '/etc/motd' }]
- *
- * Known limitations (cannot be statically analysed):
- *   - Shell variable expansion: `cat $FILE`
- *   - Command substitution: `cat $(find .)`
- *   - Interpreter scripts: `python script.py`, `node x.js`
- *   - Pipe targets: `find . | xargs cat`
- *   - Complex dynamic expressions: `eval "cat $f"`
- */
-import nodePath from 'node:path';
-import os from 'node:os';
-// ─────────────────────────────────────────────────────────────────────────────
-// Tokenizer
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Tokenize a shell command string, respecting single/double quotes and
- * backslash escapes, splitting on unquoted whitespace.
- *
- * The input should be a single simple command (already split from compound
- * commands via `splitCompoundCommand`).
- */
-function tokenize(command) {
-    const tokens = [];
-    let current = '';
-    let inSingle = false;
-    let inDouble = false;
-    let escaped = false;
-    for (let i = 0; i < command.length; i++) {
-        const ch = command[i];
-        if (escaped) {
-            current += ch;
-            escaped = false;
-            continue;
-        }
-        if (ch === '\\' && !inSingle) {
-            escaped = true;
-            continue;
-        }
-        if (ch === "'" && !inDouble) {
-            inSingle = !inSingle;
-            continue;
-        }
-        if (ch === '"' && !inSingle) {
-            inDouble = !inDouble;
-            continue;
-        }
-        if (!inSingle && !inDouble && (ch === ' ' || ch === '\t')) {
-            if (current) {
-                tokens.push(current);
-                current = '';
-            }
-            continue;
-        }
-        current += ch;
-    }
-    if (current)
-        tokens.push(current);
-    return tokens;
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Path helpers
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Resolve a path argument to an absolute POSIX-style path.
- * Handles `~` home-directory expansion and relative paths.
- *
- * Always returns paths with forward-slash separators so that the resolved
- * paths are consistent across platforms and compatible with picomatch / the
- * permission rule matching system.
- */
-function resolvePath(p, cwd) {
-    // Normalize inputs to forward slashes for consistent cross-platform handling
-    const normP = p.replace(/\\/g, '/');
-    const normCwd = cwd.replace(/\\/g, '/');
-    if (normP === '~' || normP.startsWith('~/')) {
-        const homeDir = os.homedir().replace(/\\/g, '/');
-        const rest = normP.slice(1); // '' or '/some/path'
-        // nodePath.posix.join handles the rest correctly:
-        // join('C:/Users/foo', '/.ssh/id_rsa') → 'C:/Users/foo/.ssh/id_rsa'
-        return rest ? nodePath.posix.join(homeDir, rest) : homeDir;
-    }
-    // isAbsolute check: handle both POSIX (/foo) and Windows (C:\foo) absolute paths
-    if (nodePath.isAbsolute(normP) || normP.startsWith('/')) {
-        return normP;
-    }
-    return nodePath.posix.join(normCwd, normP);
-}
-/**
- * Return true if a token looks like a file/directory path argument, as
- * opposed to a flag, shell variable, number, or script expression.
- */
-function looksLikePath(s) {
-    if (!s)
-        return false;
-    // Shell variable references
-    if (s.startsWith('$'))
-        return false;
-    // Flags
-    if (s.startsWith('-'))
-        return false;
-    // Pure integers — likely a count/size/mode argument (e.g. -n 10, chmod 755)
-    if (/^\d+$/.test(s))
-        return false;
-    // Script-like expressions (awk/sed programs, brace expansions)
-    if (s.includes('{') || s.includes('}'))
-        return false;
-    // URLs are handled separately by the web-fetch handlers
-    if (s.includes('://'))
-        return false;
-    return true;
-}
-/**
- * Extract I/O redirections from a token array.
- *
- * Modifies `tokens` in-place to remove redirect operators and their targets.
- * Returns the absolute paths of redirect targets as read / write operations.
- *
- * Handles:
- *   `> file`   `>> file`  `< file`   (with or without space)
- *   `2> file`  `2>> file` `&> file`  `&>> file`
- *   Combined forms: `>file`, `>>file`, `2>/dev/null`
- */
-function extractRedirects(tokens, cwd) {
-    const readFiles = [];
-    const writeFiles = [];
-    const toRemove = new Set();
-    for (let i = 0; i < tokens.length; i++) {
-        const tok = tokens[i];
-        // ── Separate-token redirect operators ─────────────────────────────────
-        if (tok === '>' || tok === '1>') {
-            const target = tokens[i + 1];
-            if (target && looksLikePath(target)) {
-                writeFiles.push(resolvePath(target, cwd));
-                toRemove.add(i);
-                toRemove.add(i + 1);
-                i++;
-            }
-        }
-        else if (tok === '>>' || tok === '1>>') {
-            const target = tokens[i + 1];
-            if (target && looksLikePath(target)) {
-                writeFiles.push(resolvePath(target, cwd));
-                toRemove.add(i);
-                toRemove.add(i + 1);
-                i++;
-            }
-        }
-        else if (tok === '<') {
-            const target = tokens[i + 1];
-            if (target && looksLikePath(target)) {
-                readFiles.push(resolvePath(target, cwd));
-                toRemove.add(i);
-                toRemove.add(i + 1);
-                i++;
-            }
-        }
-        else if (tok === '2>' || tok === '2>>' || tok === '&>' || tok === '&>>') {
-            // stderr / combined redirect — consume target
-            const target = tokens[i + 1];
-            if (target) {
-                if (target !== '/dev/null' && looksLikePath(target)) {
-                    writeFiles.push(resolvePath(target, cwd));
-                }
-                toRemove.add(i);
-                toRemove.add(i + 1);
-                i++;
-            }
-        }
-        // ── Combined redirect tokens without space: `>file`, `>>file`, etc. ───
-        else {
-            const m = tok.match(/^(>>|>|2>>|2>|&>>|&>|<)(.+)$/);
-            if (m) {
-                const op = m[1];
-                const target = m[2];
-                if (target !== '/dev/null' && looksLikePath(target)) {
-                    if (op === '<') {
-                        readFiles.push(resolvePath(target, cwd));
-                    }
-                    else {
-                        writeFiles.push(resolvePath(target, cwd));
-                    }
-                }
-                toRemove.add(i);
-            }
-        }
-    }
-    // Remove redirect tokens from the array in-place
-    const filtered = tokens.filter((_, idx) => !toRemove.has(idx));
-    tokens.length = 0;
-    tokens.push(...filtered);
-    return { readFiles, writeFiles };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Argument parsing
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Extract positional (non-flag) arguments from a token list.
- *
- * Flags starting with `-` are skipped. Flags listed in `flagsWithValue`
- * also consume the immediately following token (their value).
- */
-function getPositionalArgs(args, flagsWithValue = new Set()) {
-    const positional = [];
-    let skipNext = false;
-    for (const arg of args) {
-        if (skipNext) {
-            skipNext = false;
-            continue;
-        }
-        if (!arg.startsWith('-')) {
-            positional.push(arg);
-            continue;
-        }
-        // Flag: check if it consumes the next token
-        if (flagsWithValue.has(arg)) {
-            skipNext = true;
-        }
-        // Flags combined with their value in the same token (`-n10`) are ignored
-        // because looksLikePath will filter out anything starting with `-`.
-    }
-    return positional;
-}
-/** Build read_file operations from positional path arguments. */
-function readOps(args, cwd, flagsWithValue) {
-    return getPositionalArgs(args, flagsWithValue)
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'read_file',
-        filePath: resolvePath(p, cwd),
-    }));
-}
-/** Build list_directory operations from positional path arguments.
- *  Defaults to cwd when no path args are given. */
-function listOps(args, cwd, flagsWithValue) {
-    const dirs = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-    if (dirs.length === 0)
-        return [{ virtualTool: 'list_directory', filePath: cwd }];
-    return dirs.map((p) => ({
-        virtualTool: 'list_directory',
-        filePath: resolvePath(p, cwd),
-    }));
-}
-/** Extract URL domain and return a web_fetch operation, or null on failure. */
-function webOp(url) {
-    try {
-        const normalized = url.includes('://') ? url : `https://${url}`;
-        const domain = new URL(normalized).hostname;
-        return domain ? { virtualTool: 'web_fetch', domain } : null;
-    }
-    catch {
-        return null;
-    }
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// Command dispatch table
-// ─────────────────────────────────────────────────────────────────────────────
-const COMMANDS = {
-    // ── File-read commands ────────────────────────────────────────────────────
-    cat: (a, d) => readOps(a, d),
-    tac: (a, d) => readOps(a, d),
-    nl: (a, d) => readOps(a, d),
-    zcat: (a, d) => readOps(a, d),
-    bzcat: (a, d) => readOps(a, d),
-    xzcat: (a, d) => readOps(a, d),
-    gzcat: (a, d) => readOps(a, d),
-    lzcat: (a, d) => readOps(a, d),
-    head: (a, d) => readOps(a, d, new Set(['-n', '-c', '--lines', '--bytes'])),
-    tail: (a, d) => readOps(a, d, new Set(['-n', '-c', '-s', '--lines', '--bytes', '--sleep-interval'])),
-    less: (a, d) => readOps(a, d, new Set(['-b', '-h', '-j', '-p', '-x', '-y', '-z', '--shift', '--tabs'])),
-    more: (a, d) => readOps(a, d),
-    most: (a, d) => readOps(a, d),
-    wc: (a, d) => readOps(a, d),
-    file: (a, d) => readOps(a, d, new Set([
-        '-m',
-        '-e',
-        '-F',
-        '-P',
-        '--magic-file',
-        '--exclude',
-        '--extension',
-        '--separator',
-    ])),
-    stat: (a, d) => readOps(a, d, new Set(['-c', '-f', '--format', '--printf', '--file-system'])),
-    readlink: (a, d) => readOps(a, d, new Set([
-        '-e',
-        '-f',
-        '-m',
-        '-q',
-        '-s',
-        '-v',
-        '-z',
-        '--canonicalize',
-        '--canonicalize-existing',
-        '--canonicalize-missing',
-        '--no-newline',
-        '--quiet',
-        '--silent',
-        '--verbose',
-        '--zero',
-    ])),
-    realpath: (a, d) => readOps(a, d, new Set([
-        '--relative-to',
-        '--relative-base',
-        '-e',
-        '-m',
-        '-s',
-        '-z',
-        '--canonicalize-existing',
-        '--canonicalize-missing',
-        '--logical',
-        '--physical',
-        '--no-symlinks',
-        '--quiet',
-        '--strip',
-        '--zero',
-    ])),
-    diff: (a, d) => readOps(a, d, new Set([
-        '-u',
-        '-U',
-        '-c',
-        '-C',
-        '-I',
-        '-x',
-        '-X',
-        '-W',
-        '--label',
-        '--to-file',
-        '--from-file',
-        '--width',
-        '--horizon-lines',
-        '--strip-trailing-cr',
-        '--ignore-matching-lines',
-        '--exclude',
-        '--exclude-from',
-    ])),
-    diff3: (a, d) => readOps(a, d, new Set([
-        '-m',
-        '-T',
-        '-A',
-        '-E',
-        '-e',
-        '-x',
-        '-X',
-        '-3',
-        '-i',
-        '--label',
-    ])),
-    sdiff: (a, d) => readOps(a, d, new Set(['-o', '-w', '-W', '-s', '-i', '-b', '-B', '-E', '-H'])),
-    cmp: (a, d) => readOps(a, d, new Set([
-        '-i',
-        '-l',
-        '-n',
-        '-s',
-        '--ignore-initial',
-        '--bytes',
-        '--print-bytes',
-        '--quiet',
-        '--silent',
-        '--verbose',
-        '--zero',
-    ])),
-    md5sum: (a, d) => readOps(a, d),
-    sha1sum: (a, d) => readOps(a, d),
-    sha256sum: (a, d) => readOps(a, d),
-    sha512sum: (a, d) => readOps(a, d),
-    sha224sum: (a, d) => readOps(a, d),
-    sha384sum: (a, d) => readOps(a, d),
-    cksum: (a, d) => readOps(a, d),
-    b2sum: (a, d) => readOps(a, d),
-    sum: (a, d) => readOps(a, d),
-    strings: (a, d) => readOps(a, d, new Set([
-        '-n',
-        '-t',
-        '-e',
-        '-o',
-        '-a',
-        '--min-len',
-        '--radix',
-        '--encoding',
-        '--file',
-        '--print-file-name',
-        '--data',
-        '--all',
-    ])),
-    hexdump: (a, d) => readOps(a, d, new Set([
-        '-n',
-        '-s',
-        '-l',
-        '-C',
-        '-b',
-        '-c',
-        '-d',
-        '-o',
-        '-x',
-        '-e',
-        '-f',
-        '-v',
-    ])),
-    xxd: (a, d) => readOps(a, d, new Set([
-        '-l',
-        '-s',
-        '-c',
-        '-g',
-        '-o',
-        '-n',
-        '-b',
-        '-e',
-        '-i',
-        '-p',
-        '-r',
-        '-u',
-        '-E',
-    ])),
-    od: (a, d) => readOps(a, d, new Set([
-        '-N',
-        '-j',
-        '-w',
-        '-s',
-        '-t',
-        '-A',
-        '-v',
-        '--address-radix',
-        '--endian',
-        '--format',
-        '--read-bytes',
-        '--skip-bytes',
-        '--strings',
-        '--output-duplicates',
-        '--width',
-    ])),
-    sort: (a, d) => readOps(a, d, new Set([
-        '-k',
-        '-t',
-        '-T',
-        '--output',
-        '-o',
-        '--field-separator',
-        '--key',
-        '--temporary-directory',
-        '--compress-program',
-        '--batch-size',
-        '--parallel',
-        '--random-source',
-        '--sort',
-    ])),
-    uniq: (a, d) => readOps(a, d, new Set([
-        '-f',
-        '-s',
-        '-w',
-        '-n',
-        '--skip-fields',
-        '--skip-chars',
-        '--check-chars',
-    ])),
-    cut: (a, d) => readOps(a, d, new Set([
-        '-b',
-        '-c',
-        '-d',
-        '-f',
-        '--delimiter',
-        '--fields',
-        '--bytes',
-        '--characters',
-        '--output-delimiter',
-    ])),
-    paste: (a, d) => readOps(a, d, new Set(['-d', '-s', '--delimiters', '--serial'])),
-    join: (a, d) => readOps(a, d, new Set([
-        '-t',
-        '-1',
-        '-2',
-        '-j',
-        '-o',
-        '-a',
-        '-e',
-        '--field',
-        '--header',
-        '--check-order',
-        '--nocheck-order',
-        '--zero-terminated',
-    ])),
-    column: (a, d) => readOps(a, d, new Set([
-        '-t',
-        '-s',
-        '-n',
-        '-c',
-        '-o',
-        '-x',
-        '--table',
-        '--separator',
-        '--output-separator',
-        '--fillrows',
-    ])),
-    fold: (a, d) => readOps(a, d, new Set(['-w', '-b', '-s', '--width', '--bytes', '--spaces'])),
-    expand: (a, d) => readOps(a, d, new Set(['-t', '--tabs', '--initial'])),
-    unexpand: (a, d) => readOps(a, d, new Set(['-t', '-a', '--tabs', '--all', '--first-only'])),
-    base64: (a, d) => readOps(a, d, new Set(['-d', '-i', '-w', '--decode', '--ignore-garbage', '--wrap'])),
-    base32: (a, d) => readOps(a, d, new Set(['-d', '-i', '-w', '--decode', '--ignore-garbage', '--wrap'])),
-    tr: (a, d) => readOps(a, d),
-    // ── Grep / search commands ────────────────────────────────────────────────
-    grep: (args, cwd) => {
-        const hasPatternFlag = args.some((a) => a === '-e' || a === '-f' || a.startsWith('-e') || a.startsWith('-f'));
-        const isRecursive = args.some((a) => ['-r', '-R', '--recursive', '--dereference-recursive'].includes(a));
-        const flagsWithValue = new Set([
-            '-e',
-            '-f',
-            '-m',
-            '-A',
-            '-B',
-            '-C',
-            '--context',
-            '--include',
-            '--exclude',
-            '--exclude-dir',
-            '--max-count',
-            '--after-context',
-            '--before-context',
-            '-n',
-            '--line-number',
-            '--label',
-            '-D',
-            '--devices',
-            '--max-depth',
-            '-X',
-            '--exclude-from',
-        ]);
-        const positional = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-        // If -e/-f was used, there is no positional pattern; all positionals are paths.
-        // Otherwise, the first positional is the pattern and the rest are paths.
-        const filePaths = hasPatternFlag ? positional : positional.slice(1);
-        const tool = isRecursive
-            ? 'list_directory'
-            : 'read_file';
-        return filePaths.map((p) => ({
-            virtualTool: tool,
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    egrep: (a, d) => COMMANDS['grep'](a, d),
-    fgrep: (a, d) => COMMANDS['grep'](a, d),
-    zgrep: (a, d) => COMMANDS['grep'](a, d),
-    bzgrep: (a, d) => COMMANDS['grep'](a, d),
-    rg: (args, cwd) => {
-        // ripgrep: recursive by default; first non-flag positional = pattern
-        const hasPatternFlag = args.some((a) => a === '-e' || a === '-f');
-        const flagsWithValue = new Set([
-            '-e',
-            '-f',
-            '-m',
-            '-A',
-            '-B',
-            '-C',
-            '-t',
-            '-T',
-            '-g',
-            '--iglob',
-            '--glob',
-            '--type',
-            '--type-not',
-            '--max-count',
-            '--max-depth',
-            '--context',
-            '--after-context',
-            '--before-context',
-            '-M',
-            '--max-columns',
-            '--field-match-separator',
-        ]);
-        const positional = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-        const filePaths = hasPatternFlag ? positional : positional.slice(1);
-        return filePaths.map((p) => ({
-            virtualTool: 'list_directory',
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    ag: (args, cwd) => {
-        const hasPatternFlag = args.some((a) => a === '-e');
-        const flagsWithValue = new Set([
-            '-e',
-            '-m',
-            '-A',
-            '-B',
-            '-C',
-            '--depth',
-            '--file-search-regex',
-            '--file-search-regex-i',
-            '--ignore',
-            '--ignore-dir',
-            '-n',
-        ]);
-        const positional = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-        const filePaths = hasPatternFlag ? positional : positional.slice(1);
-        return filePaths.map((p) => ({
-            virtualTool: 'list_directory',
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    ack: (args, cwd) => {
-        const flagsWithValue = new Set([
-            '-m',
-            '-A',
-            '-B',
-            '-C',
-            '--type',
-            '--ignore-dir',
-            '--ignore-file',
-            '--ignore-directory',
-            '-n',
-        ]);
-        // ack: first positional = pattern, rest = paths
-        const positional = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-        return positional.slice(1).map((p) => ({
-            virtualTool: 'list_directory',
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    // ── Directory-listing commands ────────────────────────────────────────────
-    ls: (a, d) => listOps(a, d),
-    dir: (a, d) => listOps(a, d),
-    vdir: (a, d) => listOps(a, d),
-    exa: (a, d) => listOps(a, d, new Set([
-        '-L',
-        '--level',
-        '--sort',
-        '--color',
-        '--colour',
-        '--group',
-        '-I',
-        '--ignore-glob',
-    ])),
-    eza: (a, d) => listOps(a, d, new Set([
-        '-L',
-        '--level',
-        '--sort',
-        '--color',
-        '--colour',
-        '--group',
-        '-I',
-        '--ignore-glob',
-    ])),
-    lsd: (a, d) => listOps(a, d, new Set([
-        '--depth',
-        '--color',
-        '--icon',
-        '--icon-theme',
-        '--date',
-        '--size',
-        '--blocks',
-        '--header',
-        '--classic',
-        '--no-symlink',
-        '--ignore-glob',
-        '-I',
-    ])),
-    find: (args, cwd) => {
-        // `find [starting-point...] [expression]`
-        // Starting points come before any expression keyword beginning with `-` or `(`.
-        const expressionKeywords = new Set([
-            '-name',
-            '-iname',
-            '-path',
-            '-ipath',
-            '-regex',
-            '-iregex',
-            '-type',
-            '-maxdepth',
-            '-mindepth',
-            '-newer',
-            '-mtime',
-            '-atime',
-            '-ctime',
-            '-size',
-            '-user',
-            '-group',
-            '-perm',
-            '-links',
-            '-inum',
-            '-exec',
-            '-execdir',
-            '-ok',
-            '-okdir',
-            '-print',
-            '-print0',
-            '-ls',
-            '-delete',
-            '-prune',
-            '-depth',
-            '-empty',
-            '-readable',
-            '-writable',
-            '-executable',
-            '-follow',
-            '-xdev',
-            '-mount',
-            '-true',
-            '-false',
-            '-not',
-            '!',
-            '-a',
-            '-and',
-            '-o',
-            '-or',
-        ]);
-        const startingPoints = [];
-        for (const arg of args) {
-            if (arg.startsWith('-') ||
-                arg === '(' ||
-                arg === ')' ||
-                expressionKeywords.has(arg))
-                break;
-            if (looksLikePath(arg))
-                startingPoints.push(resolvePath(arg, cwd));
-        }
-        if (startingPoints.length === 0) {
-            return [{ virtualTool: 'list_directory', filePath: cwd }];
-        }
-        return startingPoints.map((p) => ({
-            virtualTool: 'list_directory',
-            filePath: p,
-        }));
-    },
-    tree: (args, cwd) => listOps(args, cwd, new Set([
-        '-L',
-        '-P',
-        '-I',
-        '-o',
-        '-n',
-        '-H',
-        '-T',
-        '--charset',
-        '--filelimit',
-        '--matchdirs',
-        '--dirsfirst',
-        '-J',
-        '-X',
-        '--du',
-        '--si',
-    ])),
-    du: (args, cwd) => listOps(args, cwd, new Set([
-        '-d',
-        '--max-depth',
-        '--threshold',
-        '-t',
-        '--block-size',
-        '-B',
-        '--time-style',
-        '--exclude',
-        '-X',
-        '--time',
-        '--output',
-    ])),
-    // ── File-write commands (create or overwrite) ─────────────────────────────
-    touch: (args, cwd) => getPositionalArgs(args, new Set(['-t', '-r', '--reference', '--date', '-d', '--time']))
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'write_file',
-        filePath: resolvePath(p, cwd),
-    })),
-    mkdir: (args, cwd) => getPositionalArgs(args, new Set(['-m', '--mode', '-Z', '--context']))
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'write_file',
-        filePath: resolvePath(p, cwd),
-    })),
-    mkfifo: (args, cwd) => getPositionalArgs(args, new Set(['-m', '--mode', '-Z']))
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'write_file',
-        filePath: resolvePath(p, cwd),
-    })),
-    tee: (args, cwd) => getPositionalArgs(args)
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'write_file',
-        filePath: resolvePath(p, cwd),
-    })),
-    cp: (args, cwd) => {
-        const flagsWithValue = new Set([
-            '-S',
-            '--suffix',
-            '-t',
-            '--target-directory',
-            '--backup',
-            '--no-target-directory',
-            '--sparse',
-            '--reflink',
-            '-Z',
-            '--context',
-            '--copy-contents',
-        ]);
-        const positional = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-        if (positional.length === 0)
-            return [];
-        if (positional.length === 1) {
-            return [
-                {
-                    virtualTool: 'read_file',
-                    filePath: resolvePath(positional[0], cwd),
-                },
-            ];
-        }
-        const srcs = positional.slice(0, -1);
-        const dst = positional[positional.length - 1];
-        return [
-            ...srcs.map((p) => ({
-                virtualTool: 'read_file',
-                filePath: resolvePath(p, cwd),
-            })),
-            { virtualTool: 'write_file', filePath: resolvePath(dst, cwd) },
-        ];
-    },
-    mv: (args, cwd) => {
-        const flagsWithValue = new Set([
-            '-S',
-            '--suffix',
-            '-t',
-            '--target-directory',
-            '--backup',
-            '-Z',
-            '--context',
-        ]);
-        const positional = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-        if (positional.length < 2)
-            return [];
-        const srcs = positional.slice(0, -1);
-        const dst = positional[positional.length - 1];
-        return [
-            // The source files are edited (moved away — their original location changes)
-            ...srcs.map((p) => ({
-                virtualTool: 'edit',
-                filePath: resolvePath(p, cwd),
-            })),
-            { virtualTool: 'write_file', filePath: resolvePath(dst, cwd) },
-        ];
-    },
-    install: (args, cwd) => {
-        const flagsWithValue = new Set([
-            '-m',
-            '--mode',
-            '-o',
-            '--owner',
-            '-g',
-            '--group',
-            '-S',
-            '--suffix',
-            '-t',
-            '--target-directory',
-            '-T',
-            '--no-target-directory',
-            '-Z',
-            '--context',
-            '-C',
-            '--compare',
-        ]);
-        const positional = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-        if (positional.length < 2)
-            return [];
-        const dst = positional[positional.length - 1];
-        return [{ virtualTool: 'write_file', filePath: resolvePath(dst, cwd) }];
-    },
-    dd: (args, cwd) => {
-        // dd if=input of=output — arguments are key=value pairs, not flags
-        const ops = [];
-        for (const arg of args) {
-            if (arg.startsWith('if=')) {
-                const p = arg.slice(3);
-                if (looksLikePath(p)) {
-                    ops.push({ virtualTool: 'read_file', filePath: resolvePath(p, cwd) });
-                }
-            }
-            else if (arg.startsWith('of=')) {
-                const p = arg.slice(3);
-                if (looksLikePath(p)) {
-                    ops.push({
-                        virtualTool: 'write_file',
-                        filePath: resolvePath(p, cwd),
-                    });
-                }
-            }
-        }
-        return ops;
-    },
-    ln: (args, cwd) => {
-        // ln [-s] TARGET LINKNAME — the link being created is a write operation
-        const positional = getPositionalArgs(args, new Set(['-S', '--suffix', '-t', '--target-directory', '-b', '--backup'])).filter(looksLikePath);
-        if (positional.length < 2)
-            return [];
-        const linkname = positional[positional.length - 1];
-        return [
-            { virtualTool: 'write_file', filePath: resolvePath(linkname, cwd) },
-        ];
-    },
-    // ── File-edit commands (modify or delete existing content) ────────────────
-    rm: (args, cwd) => getPositionalArgs(args, new Set(['--interactive']))
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'edit',
-        filePath: resolvePath(p, cwd),
-    })),
-    rmdir: (args, cwd) => getPositionalArgs(args, new Set(['--ignore-fail-on-non-empty', '-p', '--parents']))
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'edit',
-        filePath: resolvePath(p, cwd),
-    })),
-    unlink: (args, cwd) => getPositionalArgs(args)
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'edit',
-        filePath: resolvePath(p, cwd),
-    })),
-    shred: (args, cwd) => getPositionalArgs(args, new Set(['-n', '--iterations', '-s', '--size', '--random-source']))
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'edit',
-        filePath: resolvePath(p, cwd),
-    })),
-    truncate: (args, cwd) => getPositionalArgs(args, new Set([
-        '-s',
-        '--size',
-        '-r',
-        '--reference',
-        '-o',
-        '-I',
-        '-c',
-        '--io-blocks',
-        '--no-create',
-    ]))
-        .filter(looksLikePath)
-        .map((p) => ({
-        virtualTool: 'edit',
-        filePath: resolvePath(p, cwd),
-    })),
-    chmod: (args, cwd) => {
-        // chmod [opts] MODE file... — the mode is the first positional arg.
-        // Apply slice(1) BEFORE filter so that numeric modes like '755' (which are
-        // filtered by looksLikePath) don't cause the file path to be dropped.
-        const positional = getPositionalArgs(args, new Set(['-f', '--reference', '--from']));
-        return positional
-            .slice(1)
-            .filter(looksLikePath)
-            .map((p) => ({
-            virtualTool: 'edit',
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    chown: (args, cwd) => {
-        // chown [opts] OWNER[:GROUP] file... — the owner spec is the first positional.
-        const positional = getPositionalArgs(args, new Set(['--from', '--reference']));
-        return positional
-            .slice(1)
-            .filter(looksLikePath)
-            .map((p) => ({
-            virtualTool: 'edit',
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    chgrp: (args, cwd) => {
-        const positional = getPositionalArgs(args, new Set(['--reference']));
-        return positional
-            .slice(1)
-            .filter(looksLikePath)
-            .map((p) => ({
-            virtualTool: 'edit',
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    rename: (args, cwd) => {
-        // rename FROM TO file... — skip first two positionals (the from/to patterns)
-        const positional = getPositionalArgs(args).filter(looksLikePath);
-        return positional.slice(2).map((p) => ({
-            virtualTool: 'edit',
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    sed: (args, cwd) => {
-        // sed [-i] SCRIPT file... or sed -e SCRIPT file...
-        // With -i: in-place edit (virtualTool = 'edit'); otherwise read (virtualTool = 'read_file')
-        const hasInPlace = args.some((a) => a === '-i' || a.startsWith('-i'));
-        const hasExplicitScript = args.some((a) => a === '-e' || a === '-f' || a.startsWith('-e'));
-        const flagsWithValue = new Set([
-            '-e',
-            '-f',
-            '--expression',
-            '--file',
-            // NOTE: -i is intentionally absent — it is an optional-suffix flag
-            // (e.g. `-i`, `-i.bak`) and does NOT consume the next token as a value.
-            '-l',
-            '--line-length',
-            '--sandbox',
-            '-s',
-            '--separate',
-        ]);
-        const positional = getPositionalArgs(args, flagsWithValue).filter(looksLikePath);
-        // If -e/-f was used, all positionals are file paths.
-        // Otherwise, the first positional is the script expression.
-        const filePaths = hasExplicitScript ? positional : positional.slice(1);
-        const tool = hasInPlace ? 'edit' : 'read_file';
-        return filePaths.map((p) => ({
-            virtualTool: tool,
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    awk: (args, cwd) => {
-        // awk [-F sep] [-v var=val] PROGRAM file...
-        // The PROGRAM is the first positional — it will contain `{...}` which is
-        // filtered out by looksLikePath, so we don't need special handling.
-        const flagsWithValue = new Set([
-            '-F',
-            '-f',
-            '-v',
-            '-m',
-            '-W',
-            '-M',
-            '--source',
-            '--include',
-            '--load',
-            '-b',
-            '--characters-as-bytes',
-            '-c',
-            '--traditional',
-            '-d',
-            '-D',
-            '--debug',
-            '-e',
-            '--exec',
-            '-h',
-            '--help',
-            '-i',
-            '--lint',
-            '-o',
-            '-p',
-            '-r',
-            '-s',
-            '-S',
-            '-t',
-            '-V',
-        ]);
-        return getPositionalArgs(args, flagsWithValue)
-            .filter(looksLikePath)
-            .map((p) => ({
-            virtualTool: 'read_file',
-            filePath: resolvePath(p, cwd),
-        }));
-    },
-    // ── WebFetch commands ─────────────────────────────────────────────────────
-    curl: (args) => {
-        const flagsWithValue = new Set([
-            '-o',
-            '-O',
-            '--output',
-            '-u',
-            '--user',
-            '-A',
-            '--user-agent',
-            '-H',
-            '--header',
-            '-d',
-            '--data',
-            '--data-binary',
-            '--data-raw',
-            '--data-urlencode',
-            '-X',
-            '--request',
-            '-F',
-            '--form',
-            '-e',
-            '--referer',
-            '-T',
-            '--upload-file',
-            '--cacert',
-            '--capath',
-            '--cert',
-            '--key',
-            '--pass',
-            '-m',
-            '--max-time',
-            '--connect-timeout',
-            '-r',
-            '--range',
-            '--limit-rate',
-            '-b',
-            '--cookie',
-            '-c',
-            '--cookie-jar',
-            '--proxy',
-            '-U',
-            '--proxy-user',
-            '-K',
-            '--config',
-            '--netrc-file',
-            '--resolve',
-            '--connect-to',
-            '-w',
-            '--write-out',
-            '-x',
-            '-Y',
-            '--speed-limit',
-            '--speed-time',
-            '-y',
-            '--max-filesize',
-            '--proto',
-            '--proto-redir',
-            '-E',
-            '--cert-type',
-            '--key-type',
-        ]);
-        return getPositionalArgs(args, flagsWithValue)
-            .filter((p) => p.includes('://') || /^https?:\/\//.test(p) || /^ftp:\/\//.test(p))
-            .flatMap((url) => {
-            const op = webOp(url);
-            return op ? [op] : [];
-        });
-    },
-    wget: (args) => {
-        const flagsWithValue = new Set([
-            '-O',
-            '--output-document',
-            '-P',
-            '--directory-prefix',
-            '-o',
-            '--output-file',
-            '-a',
-            '--append-output',
-            '-U',
-            '--user-agent',
-            '--header',
-            '-e',
-            '--execute',
-            '--tries',
-            '-t',
-            '-T',
-            '--timeout',
-            '--wait',
-            '-w',
-            '--quota',
-            '-Q',
-            '--bind-address',
-            '--limit-rate',
-            '--user',
-            '--password',
-            '--proxy-user',
-            '--proxy-password',
-            '-i',
-            '--input-file',
-            '--base',
-            '--config',
-            '--referer',
-            '-D',
-            '--domains',
-            '--exclude-domains',
-            '-I',
-            '--include-directories',
-            '-X',
-            '--exclude-directories',
-            '--regex-type',
-            '-A',
-            '-R',
-            '--accept',
-            '--reject',
-            '--no-check-certificate',
-            '--ca-certificate',
-            '--ca-directory',
-            '--certificate',
-            '--private-key',
-        ]);
-        return getPositionalArgs(args, flagsWithValue)
-            .filter((p) => p.includes('://') || /^https?:\/\//.test(p))
-            .flatMap((url) => {
-            const op = webOp(url);
-            return op ? [op] : [];
-        });
-    },
-    fetch: (args) => {
-        // BSD `fetch` utility
-        const flagsWithValue = new Set([
-            '-o',
-            '-q',
-            '-v',
-            '-a',
-            '-T',
-            '-S',
-            '--no-verify-peer',
-            '--no-verify-hostname',
-            '--ca-cert',
-        ]);
-        return getPositionalArgs(args, flagsWithValue)
-            .filter((p) => p.includes('://'))
-            .flatMap((url) => {
-            const op = webOp(url);
-            return op ? [op] : [];
-        });
-    },
-};
-// ─────────────────────────────────────────────────────────────────────────────
-// Transparent prefix commands
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Flags that consume the next argument as their value, for specific prefix
- * commands.  Used by the prefix-stripping logic to correctly skip flag values
- * (e.g. `-u root` in `sudo -u root cat /etc/shadow`).
- */
-const PREFIX_COMMAND_FLAGS_WITH_VALUE = new Map([
-    [
-        'sudo',
-        new Set([
-            '-u',
-            '--user',
-            '-g',
-            '--group',
-            '-C',
-            '--close-from',
-            '-c',
-            '--login-class',
-            '-D',
-            '--chdir',
-            '-p',
-            '--prompt',
-            '-r',
-            '--role',
-            '-t',
-            '--type',
-            '-T',
-            '--command-timeout',
-            '-U',
-            '--other-user',
-        ]),
-    ],
-    ['timeout', new Set(['-s', '--signal', '-k', '--kill-after'])],
-]);
-/**
- * Commands that act as transparent wrappers around the actual command.
- * When encountered, the prefix is stripped and the analysis recurses on
- * the remaining command string.
- *
- * Examples:
- *   `sudo cat /etc/shadow`     → analyse `cat /etc/shadow`
- *   `timeout 10 wget http://…` → analyse `wget http://…`
- */
-const PREFIX_COMMANDS = new Set([
-    'sudo',
-    'doas', // OpenBSD sudo alternative
-    'env',
-    'time',
-    'nice',
-    'ionice',
-    'nohup',
-    'timeout',
-    'unbuffer',
-    'stdbuf',
-]);
-// ─────────────────────────────────────────────────────────────────────────────
-// Main entry point
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Extract virtual file/network operations from a single simple shell command.
- *
- * This function expects a **single simple command** (no `&&`, `||`, `;`, `|`
- * operators).  Use `splitCompoundCommand()` before calling this for compound
- * commands.
- *
- * Returns an empty array for:
- *   - Commands not in the known command table (safe default)
- *   - Empty or whitespace-only input
- *   - Pure environment variable assignments (`FOO=bar`)
- *
- * @param simpleCommand - A single shell command without compound operators.
- * @param cwd           - Working directory for resolving relative paths.
- */
-export function extractShellOperations(simpleCommand, cwd) {
-    if (!simpleCommand.trim())
-        return [];
-    const tokens = tokenize(simpleCommand);
-    if (tokens.length === 0)
-        return [];
-    // Extract I/O redirections before dispatching to the command handler.
-    // This mutates `tokens` in-place by removing redirect tokens.
-    const { readFiles: redirectReads, writeFiles: redirectWrites } = extractRedirects(tokens, cwd);
-    const cmdName = tokens[0];
-    if (!cmdName) {
-        // Only redirections were present (e.g. `> file` or `< file`)
-        return [
-            ...redirectReads.map((p) => ({
-                virtualTool: 'read_file',
-                filePath: p,
-            })),
-            ...redirectWrites.map((p) => ({
-                virtualTool: 'write_file',
-                filePath: p,
-            })),
-        ];
-    }
-    // Skip pure environment variable assignments: `FOO=bar`, `FOO=bar BAR=baz`
-    if (cmdName.includes('='))
-        return [];
-    const ops = [];
-    // ── Transparent prefix commands ───────────────────────────────────────────
-    if (PREFIX_COMMANDS.has(cmdName)) {
-        const flagsWithVal = PREFIX_COMMAND_FLAGS_WITH_VALUE.get(cmdName);
-        // Find where the actual command starts (after flags, flag-values, and env
-        // variable assignments).  For example:
-        //   sudo -u root cat /file  →  startIdx skips '-u' AND 'root'
-        let startIdx = 1;
-        while (startIdx < tokens.length) {
-            const t = tokens[startIdx];
-            if (t.startsWith('-')) {
-                // Skip the flag itself
-                startIdx++;
-                // If this flag takes a separate value argument, skip that too
-                if (flagsWithVal?.has(t) &&
-                    startIdx < tokens.length &&
-                    !tokens[startIdx].startsWith('-')) {
-                    startIdx++;
-                }
-            }
-            else if (t.includes('=')) {
-                // Environment variable assignment: skip
-                startIdx++;
-            }
-            else {
-                break;
-            }
-        }
-        // `timeout DURATION command` — the duration is a numeric positional that
-        // precedes the actual command.  Skip it.
-        if (cmdName === 'timeout' &&
-            startIdx < tokens.length &&
-            /^\d/.test(tokens[startIdx])) {
-            startIdx++;
-        }
-        if (startIdx < tokens.length) {
-            // Reconstruct the inner command and recurse
-            const innerCommand = tokens.slice(startIdx).join(' ');
-            ops.push(...extractShellOperations(innerCommand, cwd));
-        }
-    }
-    else {
-        // ── Dispatch to the known-command handler ─────────────────────────────
-        const handler = COMMANDS[cmdName];
-        if (handler) {
-            const args = tokens.slice(1);
-            ops.push(...handler(args, cwd));
-        }
-        // Unknown commands: return no ops (safe — we don't guess what we don't know)
-    }
-    // Append redirect-derived operations
-    ops.push(...redirectReads.map((p) => ({
-        virtualTool: 'read_file',
-        filePath: p,
-    })), ...redirectWrites.map((p) => ({
-        virtualTool: 'write_file',
-        filePath: p,
-    })));
-    return ops;
-}
-//# sourceMappingURL=shell-semantics.js.map