@taliesinb/mash 0.0.0-stage → 0.1.0

package/dist/src/behaviors/defs/core.js

@@ -0,0 +1,1084 @@
+/**
+ * Behavior definitions for common POSIX/GNU utilities and developer tools.
+ *
+ * Conventions:
+ * - Paths are resolved with `h.resolve` (relative to the invocation cwd).
+ * - Unknown flags or opaque arguments set `complete: false` rather than
+ *   guessing; the policy then treats the command's effects as unknown.
+ * - `readsStdin` is false when the command has file operands (or never reads stdin).
+ */
+import * as fs from 'node:fs';
+import { concat, concrete, hole, known, knownPrefix } from "../../analysis/value.js";
+import { analyzeDef, define } from "../dsl.js";
+const args = (inv) => inv.argv.slice(1);
+function incomplete(p) {
+    return p.unknownFlags.length > 0;
+}
+const isStdinOperand = (v) => concrete(v) === '-';
+/** A filter that reads its file operands (or stdin when there are none) and writes stdout. */
+function reader(names, spec, summary, more = {}) {
+    return define({ names, summary, spec, operands: 'read*', ...more });
+}
+/** Commands with no file-system effects that never read stdin (arguments are not inspected). */
+function pure(names, summary, stdout) {
+    return { names, summary, analyze: () => ({ effects: [], readsStdin: false, stdout }) };
+}
+const BSD = process.platform === 'darwin';
+const SSH_SPEC = { short: '46AaCfGgKkMNnqsTtVvXxYy', shortWithArg: 'BbcDEeFIiJLlmOoPpQRSWw', posix: true };
+const NET_CLIENTS = {
+    ssh: SSH_SPEC,
+    scp: { short: '346ABCOpqRrTv', shortWithArg: 'cDFiJloPSX' },
+    sftp: { short: '46AaCfNpqrv', shortWithArg: 'BbcDFiJloPRSsX' },
+    nc: { short: '46DdhklnrStUuvzNCF', shortWithArg: 'GwpsxXIOiTVMmeEq' },
+    netcat: { short: '46DdhklnrStUuvzNCF', shortWithArg: 'GwpsxXIOiTVMmeEq' },
+    telnet: { short: '78EFKLNacdfrx', shortWithArg: 'elnbSX' },
+    ftp: { short: '46AadegimnpRtVv', shortWithArg: 'oPqrsTu' },
+    ping: { short: '46aAdDfLnoqQrRvU', shortWithArg: 'bcCgGhiIlmMpPsStTwWzk' },
+    ping6: { short: 'aAdDfHmnNoqtvwyY', shortWithArg: 'bcgGhiIlmpPsSzk' },
+    traceroute: { short: '46adeFIlnrSvxEP', shortWithArg: 'AfgimMpPqsStwz' },
+    traceroute6: { short: 'adIlnrSvU', shortWithArg: 'fgimpqstw' },
+    dig: { short: '46hiruvm', shortWithArg: 'bcfkpqtxy' },
+    host: { short: 'aACdilrsTUvVw46', shortWithArg: 'cNRtWm' },
+    nslookup: { longSingle: true, long: { debug: false, d2: false, nodebug: false } },
+};
+const CHMOD = {
+    spec: { short: 'RfvchHLPN', long: { recursive: '=R', reference: true, verbose: false, changes: false, silent: false, quiet: false, 'no-dereference': false, dereference: false, 'preserve-root': false, 'no-preserve-root': false, from: true } },
+    operands: 'arg write*', recursive: ['R'], stdin: false,
+    when: { reference: { operands: 'write*', flags: { reference: 'read' } } },
+};
+const HEAD_TAIL = { short: 'qvzfFr', shortWithArg: 'ncsb', numeric: 'n', long: { lines: '=n', bytes: '=c', follow: false, quiet: false, silent: false, verbose: false, retry: false, pid: true, 'sleep-interval': '=s', 'zero-terminated': false } };
+export const coreBehaviors = [
+    pure(['true', 'false', ':'], 'no effect'),
+    pure(['echo', 'printf'], 'write arguments to stdout'),
+    pure(['sleep'], 'wait'),
+    pure(['seq'], 'print a sequence', { type: 'int', lines: true }),
+    pure(['date'], 'print the date'),
+    pure(['whoami', 'id', 'groups', 'logname', 'who', 'w', 'users', 'last'], 'print user identity'),
+    pure(['uname', 'hostname', 'arch', 'nproc', 'getconf', 'sw_vers', 'tty', 'locale', 'uptime', 'vm_stat', 'iostat', 'free'], 'print system information'),
+    pure(['ps', 'top', 'pstree', 'lsof', 'netstat'], 'list processes and open files'),
+    pure(['printenv'], 'print environment'),
+    pure(['expr', 'factor'], 'evaluate an expression'),
+    pure(['yes'], 'repeat a string'),
+    pure(['uuidgen'], 'print a UUID', { type: 'string' }),
+    pure(['clear', 'tput', 'stty', 'reset'], 'terminal control'),
+    pure(['which', 'type', 'command', 'whereis'], 'locate a command', { type: 'path' }),
+    {
+        names: ['basename'],
+        summary: 'strip directory and suffix',
+        analyze: () => ({ effects: [], readsStdin: false, stdout: { type: 'filename' } }),
+    },
+    {
+        names: ['dirname'],
+        summary: 'strip last component',
+        analyze: () => ({ effects: [], readsStdin: false, stdout: { type: 'path' } }),
+    },
+    {
+        names: ['pwd'],
+        summary: 'print working directory',
+        analyze: (inv) => ({ effects: [], readsStdin: false, stdout: { type: 'path', value: inv.cwd } }),
+    },
+    define({
+        names: ['realpath', 'readlink'], summary: 'resolve paths',
+        spec: { short: 'esmqzfnLP', long: { canonicalize: false, 'canonicalize-existing': false, 'canonicalize-missing': false, 'no-newline': false, relative: true, 'relative-to': true, 'relative-base': true, quiet: false, zero: false } },
+        operands: 'read*', stdin: false, stdout: { type: 'path' },
+    }),
+    define({
+        names: ['pgrep'], summary: 'find processes by name',
+        spec: { short: 'flvxinoaciLAIwr', shortWithArg: 'dgGPsuUtFqS', long: { full: false, 'list-name': false, 'list-full': false, exact: false, 'ignore-case': false, newest: false, oldest: false, count: false, inverse: false, delimiter: '=d', parent: '=P', uid: '=u', euid: '=U', terminal: '=t', pidfile: '=F', signal: true } },
+        operands: 'pattern*', flags: { F: 'read' }, stdin: false,
+    }),
+    define({
+        names: ['bc'], summary: 'calculator (reads its files, then stdin)',
+        spec: { short: 'hilqsvwcCLP', shortWithArg: 'e', long: { mathlib: false, quiet: false, standard: false, warn: false, version: false, help: false, interactive: false, expression: '=e' } },
+        operands: 'read*', stdin: true, flags: { e: 'code' },
+    }),
+    pure(['envsubst'], 'substitute environment variables (stdin to stdout)'),
+    reader(['cat', 'tac', 'nl', 'rev', 'fold', 'fmt', 'strings', 'hexdump', 'more', 'less', 'bat', 'expand', 'unexpand'], { short: 'AbeEnstTuvrwqpSlc', shortWithArg: 'wnN', long: { number: false, 'show-all': false, squeeze: false, 'number-nonblank': false, 'show-ends': false, 'show-tabs': false, plain: false, paging: true, language: true, style: true, 'line-range': true, color: true, width: true, tabs: true, all: false, initial: false } }, 'read files, write stdout'),
+    reader(['od'], { short: 'bcdDfFhHiIlLoOsvxX', shortWithArg: 'AjNtwS', long: { 'address-radix': '=A', 'skip-bytes': '=j', 'read-bytes': '=N', format: '=t', 'output-duplicates': false, width: true, endian: true } }, 'dump files'),
+    // xxd INFILE [OUTFILE]; -r reverses (still writes OUTFILE)
+    define({ names: ['xxd'], summary: 'hex dump (xxd [in [out]])', spec: { short: 'abCeEhiprRuv', shortWithArg: 'cglosn', long: { autoskip: false, bits: false, include: false, plain: false, revert: false, uppercase: false, cols: '=c', len: '=l', seek: '=s', name: '=n' } }, operands: 'read write?' }),
+    reader(['column'], { short: 'tJLnxerRlH', shortWithArg: 'sOcoNWdET', long: { table: false, separator: '=s', 'output-separator': '=o', 'output-width': '=c', 'table-columns': '=N', json: false } }, 'format columns'),
+    // GNU base64 [-d] [-w N] [FILE]; BSD base64 [-dDh] [-b N] [-i IN] [-o OUT]
+    reader(['base64', 'base32', 'basenc'], { short: 'dDhn', shortWithArg: 'wbio', long: { decode: false, 'ignore-garbage': false, wrap: '=w', input: '=i', output: '=o', break: '=b', base64: false, base64url: false, base32: false, base32hex: false, base16: false } }, 'encode / decode', { flags: { i: 'read', o: 'write' }, when: { i: { stdin: false } } }),
+    reader(['head', 'tail'], HEAD_TAIL, 'print part of files'),
+    reader(['wc'], { short: 'clmwL', long: { bytes: false, chars: false, lines: false, words: false, 'max-line-length': false } }, 'count', { stdout: { type: 'string' } }),
+    reader(['cut'], { short: 'snzw', shortWithArg: 'bcdf', long: { bytes: '=b', characters: '=c', delimiter: '=d', fields: '=f', complement: false, 'only-delimited': false, 'output-delimiter': true, 'zero-terminated': false } }, 'cut fields'),
+    reader(['paste'], { short: 'sz', shortWithArg: 'd', long: { delimiters: '=d', serial: false } }, 'merge lines'),
+    reader(['shuf'], { short: 'erzn', shortWithArg: 'inoS', long: { echo: false, 'input-range': '=i', 'head-count': '=n', output: '=o', 'random-source': true, repeat: false } }, 'shuffle lines', { flags: { o: 'write', 'random-source': 'read' }, when: { e: { operands: 'arg*', stdin: false }, i: { operands: '', stdin: false } } }),
+    reader(['iconv'], { short: 'csl', shortWithArg: 'fto', long: { 'from-code': '=f', 'to-code': '=t', output: '=o', list: false, silent: false } }, 'convert encodings', { flags: { o: 'write' } }),
+    reader(['join'], { short: 'iz', shortWithArg: 'ajoetv12', long: { 'ignore-case': false, 'check-order': false, 'nocheck-order': false, header: false } }, 'join sorted files'),
+    define({
+        names: ['uniq'], summary: 'filter repeated lines (uniq [IN [OUT]])',
+        spec: { short: 'cdDiuz', shortWithArg: 'fsw', long: { count: false, repeated: false, unique: false, 'ignore-case': false, 'skip-fields': '=f', 'skip-chars': '=s', 'check-chars': '=w', 'all-repeated': true, group: true, 'zero-terminated': false } },
+        operands: 'read? write?',
+        // OUT of `-` is stdout
+        extra: (r, { operands }) => (operands[1] && isStdinOperand(operands[1]) ? { ...r, effects: r.effects.filter((e) => e.kind !== 'write') } : r),
+    }),
+    {
+        names: ['csplit'],
+        summary: 'split a file at patterns into pieces named PREFIXnn',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), { short: 'ksqz', shortWithArg: 'fbn', long: { prefix: '=f', 'suffix-format': '=b', digits: '=n', 'keep-files': '=k', quiet: '=q', silent: '=s', 'elide-empty-files': '=z', 'suppress-matched': false } });
+            const [input, ...patterns] = p.operands;
+            for (const pat of patterns)
+                h.role(pat, 'pattern');
+            const effects = [];
+            if (input && !isStdinOperand(input))
+                effects.push({ kind: 'read', path: h.resolve(input) });
+            const f = p.flags.get('f');
+            const target = h.resolve(f && f !== true ? f : known('xx'));
+            effects.push({ kind: 'write', path: { alts: target.alts.map((a) => [...a, { hole: true, type: 'filename', origin: 'csplit suffix' }]) } });
+            return { effects, readsStdin: !input || isStdinOperand(input), complete: !incomplete(p) };
+        },
+    },
+    {
+        names: ['split'],
+        summary: 'split a file into pieces named PREFIX*',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), { short: 'dxe', shortWithArg: 'lbnCa', long: { lines: true, bytes: true, number: true, 'line-bytes': true, 'suffix-length': true, 'numeric-suffixes': false, 'additional-suffix': true, verbose: false } });
+            const [input, prefix] = p.operands;
+            const effects = [];
+            if (input && !isStdinOperand(input))
+                effects.push({ kind: 'read', path: h.resolve(input) });
+            const pre = prefix ?? known('x');
+            const target = h.resolve(pre);
+            effects.push({ kind: 'write', path: { alts: target.alts.map((a) => [...a, { hole: true, type: 'filename', origin: 'split suffix' }]) } });
+            return { effects, readsStdin: !input || isStdinOperand(input), complete: !incomplete(p) };
+        },
+    },
+    reader(['comm'], { short: '123z', long: { 'check-order': false, 'nocheck-order': false, 'output-delimiter': true, total: false } }, 'compare sorted files'),
+    reader(['diff', 'cmp'], { short: 'uqrNbBiwasylcntTpdEZ', shortWithArg: 'UCxXIFS', long: { unified: true, recursive: false, brief: false, color: true, 'ignore-all-space': false, 'ignore-space-change': false, 'ignore-blank-lines': false, 'ignore-case': false, exclude: true, 'exclude-from': '=X', text: false, 'new-file': false, 'side-by-side': false, 'strip-trailing-cr': false, label: true, 'no-dereference': false, normal: false, minimal: false, silent: false, quiet: false, 'ignore-matching-lines': '=I', 'show-function-line': '=F', 'starting-file': '=S', 'width': true, 'suppress-common-lines': false } }, 'compare files', { flags: { X: 'read' }, recursive: ['r', 'recursive'] }),
+    reader(['md5sum', 'sha1sum', 'sha224sum', 'sha256sum', 'sha384sum', 'sha512sum', 'shasum', 'cksum', 'b2sum', 'b3sum', 'sum'], { short: 'bctwzU0sq', shortWithArg: 'aol', long: { check: false, binary: false, text: false, algorithm: '=a', tag: false, quiet: false, status: false, strict: false, warn: false, zero: false, length: '=l', untagged: false, 'ignore-missing': false, raw: false, base64: false } }, 'checksum files'),
+    // BSD md5: -s STRING checksums a string
+    reader(['md5'], { short: 'pqrtxn', shortWithArg: 's' }, 'checksum files', { when: { s: { stdin: false } } }),
+    reader(['file'], { short: 'bcdhiklLNnprsvzZ0SI', shortWithArg: 'fmFeP', long: { brief: false, 'mime-type': false, 'mime-encoding': false, mime: false, dereference: false, 'no-dereference': false, 'files-from': '=f', 'magic-file': '=m', separator: '=F', exclude: '=e', 'keep-going': false, raw: false, special: false, uncompress: false } }, 'inspect files', { flags: { f: 'read', m: 'read' }, stdin: false }),
+    // BSD stat: -f FORMAT, -t TIMEFMT; GNU stat: -c FORMAT, -f = file-system status
+    reader(['stat'], BSD
+        ? { short: 'FLlnqrsx', shortWithArg: 'ftc', long: { format: '=c', dereference: false } }
+        : { short: 'Lfte', shortWithArg: 'c', long: { format: '=c', printf: true, dereference: false, 'file-system': false, terse: false, cached: true } }, 'inspect files', { stdin: false }),
+    reader(['tr'], { short: 'cdsCt', long: { complement: false, delete: false, 'squeeze-repeats': false, truncate: false } }, 'translate characters', { operands: 'arg*', stdin: true }),
+    define({
+        names: ['jq', 'gojq', 'jaq'], summary: 'JSON processor',
+        spec: { short: 'rjcnsSeaCMRxh', shortWithArg: 'fL', long: { arg: 2, argjson: 2, slurpfile: 2, rawfile: 2, args: false, jsonargs: false, 'raw-output': false, 'raw-output0': false, 'join-output': false, 'ascii-output': false, compact: false, 'null-input': false, 'raw-input': false, slurp: false, tab: false, indent: true, 'sort-keys': false, 'color-output': false, 'monochrome-output': false, 'exit-status': false, 'from-file': '=f', seq: false, stream: false, 'stream-errors': false } },
+        operands: 'code read*', flags: { f: 'read', slurpfile: 'read', rawfile: 'read' },
+        when: { f: { operands: 'read*' }, 'args|jsonargs': { operands: 'code arg*', stdin: true }, n: { stdin: false } },
+    }),
+    // grep needs special handling: the first operand is the pattern unless -e/-f
+    {
+        names: ['grep', 'egrep', 'fgrep', 'rg', 'ag'],
+        summary: 'search files',
+        analyze(inv, h) {
+            const rg = inv.name === 'rg' || inv.name === 'ag';
+            const p = h.parseArgs(args(inv), {
+                short: rg ? 'iFwxclLnNHosqvuUzSa.P' : 'EFGPivwxyclLnhHosqbrRUzZaIT',
+                shortWithArg: rg ? 'efgtTmABCjMrE' : 'efmABCdD',
+                long: { regexp: true, file: true, 'ignore-case': false, 'invert-match': false, 'word-regexp': false, 'line-regexp': false, count: false, 'files-with-matches': false, 'files-without-match': false, 'line-number': false, 'no-filename': false, 'with-filename': false, 'only-matching': false, quiet: false, silent: false, recursive: false, 'dereference-recursive': false, include: true, exclude: true, 'exclude-dir': true, 'exclude-from': true, color: true, colour: true, 'max-count': true, context: true, 'after-context': true, 'before-context': true, 'extended-regexp': false, 'fixed-strings': false, 'perl-regexp': false, 'null-data': false, binary: false, text: false, glob: true, iglob: true, type: true, 'type-not': true, 'type-add': true, hidden: false, 'no-ignore': false, 'no-ignore-vcs': false, json: false, 'files': false, 'smart-case': false, 'max-depth': true, 'no-heading': false, heading: false, 'no-messages': false, 'line-buffered': false, multiline: false, 'multiline-dotall': false, replace: true, 'sort': true, 'sortr': true, 'follow': false, 'max-columns': true, 'max-filesize': true, threads: true, 'column': false, 'vimgrep': false, 'stats': false, 'pcre2': false, 'null': false, 'byte-offset': false, 'trim': false, 'passthru': false, 'unrestricted': false, 'no-config': false, 'count-matches': false, 'ignore-file': true, 'label': true, 'initial-tab': false, 'devices': true, 'directories': true, 'binary-files': true }
+            });
+            const operands = [...p.operands];
+            for (const e of [...(p.multi.get('e') ?? []), ...(p.multi.get('regexp') ?? [])])
+                h.role(e, 'pattern');
+            if (!p.flags.has('e') && !p.flags.has('f') && !p.flags.has('regexp') && !p.flags.has('file') && !(rg && (p.flags.has('files') || p.flags.has('type-list')))) {
+                const pat = operands.shift();
+                if (pat)
+                    h.role(pat, 'pattern');
+            }
+            const recursive = rg || p.flags.has('r') || p.flags.has('R') || p.flags.has('recursive') || p.flags.has('dereference-recursive');
+            const files = operands.filter((f) => !isStdinOperand(f));
+            const effects = files.map((f) => ({ kind: 'read', path: h.resolve(f), recursive }));
+            // rg and grep -r search the cwd without operands
+            if (operands.length === 0 && recursive)
+                effects.push({ kind: 'read', path: inv.cwd, recursive: true });
+            const pf = p.flags.get('f') ?? p.flags.get('file');
+            if (pf && pf !== true && !isStdinOperand(pf))
+                effects.push({ kind: 'read', path: h.resolve(pf) });
+            const readsStdin = !rg && !recursive ? operands.length === 0 || operands.some(isStdinOperand) : false;
+            return { effects, readsStdin, complete: !incomplete(p) };
+        },
+    },
+    define({
+        names: ['sort'], summary: 'sort lines',
+        spec: { short: 'bdfgiMhnRrscCumVz', shortWithArg: 'kotST', long: { output: '=o', key: '=k', 'field-separator': '=t', reverse: false, numeric: false, 'numeric-sort': false, unique: false, 'human-numeric-sort': false, 'version-sort': false, 'general-numeric-sort': false, 'ignore-case': false, 'month-sort': false, 'random-sort': false, 'ignore-leading-blanks': false, 'dictionary-order': false, check: false, merge: false, parallel: true, 'buffer-size': '=S', 'temporary-directory': '=T', stable: false, 'zero-terminated': false, 'files0-from': true, 'random-source': true, debug: false } },
+        operands: 'read*', flags: { o: 'write', T: 'write:dir~', 'files0-from': 'read', 'random-source': 'read' },
+    }),
+    define({
+        names: ['tee'], summary: 'copy stdin to files',
+        spec: { short: 'aip', long: { append: '=a', 'ignore-interrupts': '=i', 'output-error': true } },
+        operands: 'write*', stdin: true, when: { a: { operands: 'append*' } },
+    }),
+    define({
+        names: ['ls'], summary: 'list directories', namesOnly: true,
+        spec: { short: '1aAbBcCdfFgGhHiklLmnNopqQrRsStTuUvwxXZ@eO', shortWithArg: BSD ? 'IDP' : 'IP', long: { all: false, 'almost-all': false, color: true, classify: false, human: false, 'human-readable': false, recursive: false, directory: false, 'block-size': true, 'group-directories-first': false, time: true, 'time-style': true, 'full-time': false, sort: true, ignore: true, 'hide': true, si: false, inode: false, 'dereference': false, 'quoting-style': true, literal: false, width: true, format: true, 'indicator-style': true, 'hyperlink': true } },
+        operands: 'read*', cwdIfNone: true, recursive: ['R', 'recursive'], stdin: false,
+        // operands are usually directories (a name with an extension is more likely a file)
+        extra: (r, { h, operands }) => {
+            for (const f of operands)
+                if (!/\.[A-Za-z]\w{0,7}$/.test(concrete(f) ?? ''))
+                    h.role(f, 'dir');
+            return r;
+        },
+    }),
+    define({
+        names: ['tree', 'du'], summary: 'list directory trees', namesOnly: true,
+        spec: { short: '1aAbBcCdfFgGhHiklLmnNopqQrRsStTuUvwxXZ@eDJ', shortWithArg: 'IdLPt', long: { all: false, 'max-depth': '=d', summarize: false, total: false, 'block-size': true, human: false, 'human-readable': false, si: false, apparent: false, 'apparent-size': false, exclude: true, 'one-file-system': false, 'dirsfirst': false, 'noreport': false, charset: true, 'gitignore': false, threshold: '=t', 'time': true, inodes: false, 'null': false, 'count-links': false, 'dereference': false, 'exclude-from': true, 'files0-from': true } },
+        operands: 'read*', cwdIfNone: true, recursive: true, stdin: false,
+    }),
+    pure(['df'], 'report disk usage'),
+    // ---- writers ----
+    define({
+        names: ['touch'], summary: 'create files / update times',
+        spec: { short: 'acmfh', shortWithArg: 'rtdA', long: { 'no-create': false, date: '=d', reference: '=r', time: true, 'no-dereference': false } },
+        operands: 'write*', flags: { r: 'read' }, stdin: false,
+        // -c: only existing files are touched (at runtime the path is known: check it)
+        when: {
+            'c|no-create': {
+                operands: 'write~*',
+                extra: (r, { inv }) => ({ ...r, effects: r.effects.flatMap((e) => {
+                        if (e.kind !== 'write' || !e.maybe)
+                            return [e];
+                        const p = concrete(e.path);
+                        // statically, an earlier command of the snippet may create it
+                        if (p === undefined || inv.mayHaveChanged?.(p))
+                            return [e];
+                        return fs.existsSync(p) ? [{ kind: 'write', path: e.path }] : [];
+                    }) }),
+            },
+        },
+    }),
+    define({ names: ['mkdir'], summary: 'create directories', spec: { short: 'pv', shortWithArg: 'm', long: { parents: false, verbose: false, mode: '=m' } }, operands: 'write:dir*', stdin: false }),
+    define({ names: ['mkfifo', 'mknod'], summary: 'create special files', spec: { short: 'Z', shortWithArg: 'm', long: { mode: '=m' } }, operands: 'write arg*', stdin: false }),
+    define({ names: ['rmdir'], summary: 'remove empty directories', spec: { short: 'pv', long: { parents: false, 'ignore-fail-on-non-empty': false, verbose: false } }, operands: 'delete:dir*', stdin: false }),
+    define({
+        names: ['rm', 'unlink', 'shred'], summary: 'remove files',
+        spec: { short: 'rRfivdIuxzWP', shortWithArg: 'ns', long: { recursive: false, force: false, interactive: true, dir: false, verbose: false, 'one-file-system': false, 'no-preserve-root': false, 'preserve-root': false, iterations: '=n', size: '=s', remove: false, zero: false, exact: false } },
+        operands: 'delete*', recursive: ['r', 'R', 'recursive'], stdin: false,
+        extra: (r, { inv, p }) => {
+            // shred overwrites in place, and removes only with -u
+            if (inv.name === 'shred')
+                return { ...r, effects: r.effects.flatMap((e) => (e.kind === 'delete' ? [{ kind: 'write', path: e.path }, ...(p.flags.has('u') || p.flags.has('remove') ? [e] : [])] : [e])) };
+            // rm -f: a missing operand is not an error (for the opt-in `missingDeletes: 'allow'`)
+            if (inv.name === 'rm' && (p.flags.has('f') || p.flags.has('force')))
+                return { ...r, effects: r.effects.map((e) => (e.kind === 'delete' ? { ...e, ifExists: true } : e)) };
+            return r;
+        },
+    }),
+    {
+        names: ['cp', 'mv', 'install', 'ln', 'rsync'],
+        summary: 'copy / move / link files',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), {
+                short: 'aRrfipnvlsLPHdxubTuUcDzSWeXAEhOJN', shortWithArg: 'tmogSeBM',
+                long: { recursive: false, force: false, interactive: false, 'no-clobber': false, verbose: false, archive: false, symbolic: false, 'target-directory': '=t', 'no-target-directory': false, parents: false, preserve: true, 'no-preserve': true, update: false, backup: true, suffix: true, mode: '=m', owner: '=o', group: '=g', delete: false, 'delete-excluded': false, 'delete-after': false, 'delete-before': false, 'delete-during': false, exclude: true, include: true, 'exclude-from': true, 'include-from': true, 'files-from': true, filter: true, 'dry-run': false, progress: false, compress: false, 'remove-source-files': false, rsh: '=e', 'itemize-changes': false, 'ignore-existing': false, partial: false, 'partial-dir': true, stats: false, info: true, 'human-readable': false, checksum: false, times: false, perms: false, links: false, 'copy-links': false, 'hard-links': false, 'no-dereference': false, dereference: false, 'one-file-system': false, quiet: false, 'size-only': false, existing: false, inplace: false, append: false, 'append-verify': false, 'whole-file': false, 'chmod': true, 'chown': true, 'numeric-ids': false, 'mkpath': false, 'strip-trailing-slashes': false, reflink: true, sparse: true, 'copy-contents': false, 'attributes-only': false, 'relative': false, 'no-relative': false, 'safe-links': false, 'max-size': true, 'min-size': true, 'bwlimit': true, 'timeout': true, 'out-format': true, 'log-file': true, 'link-dest': true, 'compare-dest': true, 'copy-dest': true, 'backup-dir': true, 'temp-dir': true, 'no-motd': false, 'list-only': false, 'prune-empty-dirs': false, 'protect-args': false, 'exclude-dir': true }
+            });
+            // install -d DIR...: creates every operand
+            if (inv.name === 'install' && p.flags.has('d')) {
+                for (const d of p.operands)
+                    h.role(d, 'dir');
+                return { effects: p.operands.map((d) => ({ kind: 'write', path: h.resolve(d) })), readsStdin: false, complete: !incomplete(p) };
+            }
+            // rsync SRC (no destination) lists SRC
+            if (inv.name === 'rsync' && p.operands.length === 1 && !p.flags.has('t')) {
+                const src = p.operands[0];
+                const effects = [{ kind: 'read', path: h.resolve(src), recursive: true }];
+                if (/^[^/]*:/.test(knownPrefix(src)))
+                    effects.push({ kind: 'network', detail: 'remote rsync' });
+                return { effects, readsStdin: false, complete: !incomplete(p) && !p.flags.has('e') };
+            }
+            const ops = [...p.operands];
+            const t = p.flags.get('t');
+            const target = t && t !== true ? t : ops.pop();
+            if (!target)
+                return { effects: [], readsStdin: false, complete: !incomplete(p) };
+            const recursive = inv.name === 'rsync' || p.flags.has('r') || p.flags.has('R') || p.flags.has('a') || p.flags.has('recursive') || inv.name === 'mv';
+            const effects = [];
+            const dryRun = p.flags.has('dry-run') || (inv.name === 'rsync' && (p.flags.has('n') || p.flags.has('list-only')));
+            for (const src of ops) {
+                effects.push({ kind: 'read', path: h.resolve(src), recursive });
+                if (inv.name === 'mv' || p.flags.has('remove-source-files'))
+                    effects.push({ kind: 'delete', path: h.resolve(src), recursive });
+            }
+            if (!dryRun)
+                effects.push({ kind: 'write', path: h.resolve(target), recursive });
+            let complete = !incomplete(p);
+            if (inv.name === 'rsync') {
+                const remote = (v) => /^[^/]*:/.test(knownPrefix(v));
+                if (ops.some(remote) || remote(target))
+                    effects.push({ kind: 'network', detail: 'remote rsync' });
+                for (const k of ['exclude-from', 'include-from', 'files-from']) {
+                    const v = p.flags.get(k);
+                    if (v && v !== true && !isStdinOperand(v))
+                        effects.push({ kind: 'read', path: h.resolve(v) });
+                }
+                const log = p.flags.get('log-file');
+                if (log && log !== true)
+                    effects.push({ kind: 'write', path: h.resolve(log), append: true });
+                // the remote shell runs locally
+                if (p.flags.has('e'))
+                    complete = false;
+            }
+            return { effects, readsStdin: false, complete };
+        },
+    },
+    {
+        names: ['chmod', 'chown', 'chgrp', 'chflags'],
+        summary: 'change file metadata',
+        analyze(inv, h) {
+            // `chmod -x file`: a mode that looks like a flag
+            const a = args(inv);
+            const m = inv.name === 'chmod' ? a.findIndex((v) => /^-[rwxXstugoa]+$/.test(concrete(v) ?? '') && !/^-[RfvchHLPN]+$/.test(concrete(v))) : -1;
+            return analyzeDef(CHMOD, inv, m === -1 ? a : [known('mode'), ...a.slice(0, m), ...a.slice(m + 1)], h);
+        },
+    },
+    // xattr [-lrsvx] [-p|-w|-d|-c] ...
+    define({
+        names: ['xattr'], summary: 'extended attributes',
+        spec: { short: 'lrsvxhpwdc' }, operands: 'read*', recursive: ['r'], stdin: false,
+        when: { p: { operands: 'arg read*' }, d: { operands: 'arg write*' }, c: { operands: 'write*' }, w: { operands: 'arg arg write*' } },
+    }),
+    define({
+        names: ['truncate'], summary: 'shrink or extend files',
+        spec: { short: 'co', shortWithArg: 'sr', long: { size: '=s', reference: '=r', 'no-create': false, 'io-blocks': false } },
+        operands: 'write*', flags: { r: 'read' }, stdin: false,
+    }),
+    {
+        names: ['patch'],
+        summary: 'apply a diff to files',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), {
+                short: 'bcefElnNRstTuvZ',
+                shortWithArg: 'pBdDFgioruVYzx',
+                long: {
+                    strip: '=p', directory: '=d', input: '=i', output: '=o', 'reject-file': '=r', 'dry-run': false, forward: false, reverse: false,
+                    silent: false, quiet: false, force: false, batch: false, unified: false, context: false, normal: false, backup: false,
+                    'remove-empty-files': false, binary: false, posix: false, suffix: '=z', prefix: '=B', 'version-control': '=V', fuzz: '=F', merge: true, verbose: false,
+                },
+            });
+            const flag = (k) => {
+                const v = p.flags.get(k);
+                return v && v !== true ? v : undefined;
+            };
+            const [original, patchfile] = p.operands;
+            const input = flag('i') ?? patchfile;
+            const output = flag('o');
+            const dir = flag('d');
+            const dry = p.flags.has('dry-run');
+            const effects = [];
+            if (input && !isStdinOperand(input))
+                effects.push({ kind: 'read', path: h.resolve(input) });
+            let complete = !incomplete(p);
+            if (original) {
+                const kind = dry || output ? 'read' : 'write';
+                if (dir === undefined)
+                    effects.push({ kind, path: h.resolve(original) });
+                else {
+                    // operands are relative to -d DIR
+                    const d = concrete(h.resolve(dir));
+                    const o = concrete(original);
+                    if (d !== undefined && o !== undefined)
+                        effects.push({ kind, path: h.resolve(known(o.startsWith('/') ? o : `${d}/${o}`)) });
+                    else {
+                        effects.push({ kind, path: h.resolve(dir), recursive: true });
+                        complete = false;
+                    }
+                }
+            }
+            else if (!dry && !output) {
+                // the files named in the diff, below the working (or -d) directory: GNU patch refuses
+                // absolute and `..` names; other implementations may not, so this is incomplete
+                effects.push({ kind: 'write', path: h.resolve(dir ?? known('.')), recursive: true });
+                complete = false;
+            }
+            if (output && !dry && !isStdinOperand(output))
+                effects.push({ kind: 'write', path: h.resolve(output) });
+            const rej = flag('r');
+            if (rej && !dry)
+                effects.push({ kind: 'write', path: h.resolve(rej) });
+            return { effects, readsStdin: !input || isStdinOperand(input), complete };
+        },
+    },
+    {
+        names: ['mktemp'],
+        summary: 'create a temporary file or directory',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), { short: 'dquturt', shortWithArg: 'p', long: { directory: false, quiet: false, 'dry-run': false, tmpdir: true, suffix: true } });
+            const tmp = (concrete(inv.env('TMPDIR') ?? known('/tmp')) ?? '/tmp').replace(/\/+$/, '') || '/tmp';
+            const pdir = p.flags.get('p') ?? p.flags.get('tmpdir');
+            const template = p.operands[0];
+            let under = tmp;
+            if (pdir && pdir !== true)
+                under = concrete(h.resolve(pdir));
+            else if (template) {
+                const t = concrete(template);
+                if (t === undefined)
+                    under = undefined;
+                else if (t.includes('/'))
+                    under = concrete(h.resolve(known(t.slice(0, t.lastIndexOf('/')) || '/')));
+                else if (!p.flags.has('t'))
+                    under = concrete(inv.cwd);
+            }
+            const created = hole('path', '$(mktemp)', under ? { under } : {});
+            return {
+                effects: p.flags.has('u') || p.flags.has('dry-run') ? [] : [{ kind: 'write', path: created }],
+                readsStdin: false,
+                stdout: { type: 'path', under },
+                complete: !incomplete(p),
+            };
+        },
+    },
+    {
+        names: ['dd'],
+        summary: 'convert and copy',
+        analyze(inv, h) {
+            const effects = [];
+            let readsStdin = true;
+            for (const a of args(inv)) {
+                const s = knownPrefix(a);
+                const rest = (prefix) => ({ alts: a.alts.map((alt) => [typeof alt[0] === 'string' ? alt[0].slice(prefix.length) : '', ...alt.slice(1)]) });
+                if (s.startsWith('if=')) {
+                    effects.push({ kind: 'read', path: h.resolve(rest('if=')) });
+                    readsStdin = false;
+                }
+                else if (s.startsWith('of='))
+                    effects.push({ kind: 'write', path: h.resolve(rest('of=')) });
+            }
+            return { effects, readsStdin };
+        },
+    },
+    {
+        names: ['sed', 'gsed'],
+        summary: 'stream editor',
+        analyze(inv, h) {
+            // -i: GNU takes an optional attached suffix (`-i.bak`, never the next word);
+            // BSD sed takes the next word as the suffix (`-i ''`, `-i .bak`)
+            const bsd = BSD && inv.name === 'sed';
+            const a = [];
+            const raw = args(inv);
+            for (let k = 0; k < raw.length; k++) {
+                const s = concrete(raw[k]);
+                const m = s === undefined ? null : /^-([nrEsuzl]*)i(.*)$/.exec(s);
+                if (!m) {
+                    a.push(raw[k]);
+                    if (s === '--')
+                        a.push(...raw.slice(k + 1));
+                    if (s === '--')
+                        break;
+                    continue;
+                }
+                a.push(known(`-${m[1]}i`));
+                if (m[2] === '' && bsd) {
+                    const next = raw[k + 1] === undefined ? undefined : concrete(raw[k + 1]);
+                    if (next !== undefined && (next === '' || /^[.~_-]/.test(next) && next !== '-'))
+                        k++;
+                }
+            }
+            const p = h.parseArgs(a, { short: 'nrEsuzli', shortWithArg: 'efl', long: { expression: '=e', file: '=f', 'in-place': false, quiet: false, silent: false, 'regexp-extended': false, separate: false, 'null-data': false, 'zero-terminated': false, posix: false, sandbox: false, debug: false, 'line-length': '=l', 'follow-symlinks': false, unbuffered: false } });
+            const ops = [...p.operands];
+            const scripts = p.multi.get('e') ?? [];
+            if (scripts.length === 0 && !p.flags.has('f')) {
+                const s = ops.shift();
+                if (s)
+                    scripts.push(s);
+            }
+            for (const s of scripts)
+                h.role(s, 'code');
+            const inPlace = p.flags.has('i') || p.flags.has('in-place');
+            const effects = ops.map((f) => ({ kind: 'read', path: h.resolve(f) }));
+            if (inPlace)
+                for (const f of ops)
+                    effects.push({ kind: 'write', path: h.resolve(f) });
+            const sf = p.flags.get('f');
+            if (sf && sf !== true)
+                effects.push({ kind: 'read', path: h.resolve(sf) });
+            let complete = !incomplete(p);
+            for (const s of scripts) {
+                const texts = programTexts(s);
+                if (texts === undefined) {
+                    complete = false;
+                    continue;
+                }
+                for (const text of texts) {
+                    // `w file` commands and the `e` command
+                    const w = /(?:^|[;\n}])\s*(?:\d+|\/[^/]*\/|\$)?\s*[wW]\s+(\S+)/.exec(text) ?? /\/[^/]*\/[^/]*\/[gpIiMm0-9]*w\s+(\S+)/.exec(text);
+                    if (w)
+                        effects.push({ kind: 'write', path: h.resolve(known(w[1])) });
+                    if (/(?:^|[;\n])\s*e(\s|$)/.test(text) || /\/[gpIiMm0-9]*e[gpIiMm0-9]*\s*(?:$|[;}\n])/.test(text)) {
+                        effects.push({ kind: 'unknown', detail: 'sed e command executes shell commands' });
+                        complete = false;
+                    }
+                }
+            }
+            return { effects, readsStdin: ops.length === 0, complete };
+        },
+    },
+    {
+        names: ['awk', 'gawk', 'mawk', 'nawk'],
+        summary: 'pattern scanning language',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), { short: 'bcCdhlLnNOPrsStV', shortWithArg: 'FvfiE', long: { 'field-separator': '=F', assign: '=v', file: '=f' } });
+            const ops = [...p.operands];
+            let program;
+            const f = p.flags.get('f');
+            const effects = [];
+            if (f && f !== true)
+                effects.push({ kind: 'read', path: h.resolve(f) });
+            else
+                program = ops.shift();
+            if (program)
+                h.role(program, 'code');
+            const files = ops.filter((o) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(knownPrefix(o)));
+            for (const file of files)
+                effects.push({ kind: 'read', path: h.resolve(file) });
+            let complete = !incomplete(p) && program !== undefined;
+            for (const text of (program && programTexts(program)) || [undefined]) {
+                if (text === undefined) {
+                    complete = false;
+                    continue;
+                }
+                if (/\bsystem\s*\(|\|\s*"|"\s*\|\s*getline/.test(text)) {
+                    effects.push({ kind: 'unknown', detail: 'awk program runs shell commands' });
+                    complete = false;
+                }
+                for (const m of text.matchAll(/(?:print|printf)[^;}]*?>>?\s*"([^"]+)"/g))
+                    effects.push({ kind: 'write', path: h.resolve(known(m[1])) });
+                if (/(?:print|printf)[^;}]*?>>?\s*[^"\s]/.test(text))
+                    complete = false;
+            }
+            return { effects, readsStdin: files.length === 0, complete };
+        },
+    },
+    {
+        names: ['find'],
+        summary: 'search a directory tree',
+        analyze(inv, h) {
+            const a = args(inv);
+            const starts = [];
+            let i = 0;
+            while (i < a.length && /^-[HLP]$/.test(concrete(a[i]) ?? ''))
+                i++;
+            for (; i < a.length; i++) {
+                const s = concrete(a[i]);
+                if (s !== undefined && (s.startsWith('-') || s === '(' || s === '!' || s === ')'))
+                    break;
+                starts.push(a[i]);
+            }
+            if (starts.length === 0)
+                starts.push(known('.'));
+            const roots = starts.map(h.resolve);
+            // find itself reads names and metadata; actions (-exec cat {}) report their own reads
+            const effects = roots.map((r) => ({ kind: 'read', path: r, recursive: true, names: true }));
+            let complete = true;
+            // a found path: lies under one of the start dirs
+            const foundPath = () => {
+                const r = roots.length === 1 ? concrete(roots[0]) : undefined;
+                return hole('path', 'find result', r ? { under: r } : {});
+            };
+            for (; i < a.length; i++) {
+                const s = concrete(a[i]);
+                if (s === undefined) {
+                    complete = false;
+                    continue;
+                }
+                // only matching files are deleted, and there may be none: a possible effect
+                if (s === '-delete')
+                    for (const r of roots)
+                        effects.push({ kind: 'delete', path: r, recursive: true, maybe: true });
+                else if (s === '-fprint' || s === '-fprint0' || s === '-fprintf' || s === '-fls') {
+                    const f = a[++i];
+                    if (f)
+                        effects.push({ kind: 'write', path: h.resolve(f) });
+                    if (s === '-fprintf')
+                        i++;
+                }
+                else if (s === '-exec' || s === '-execdir' || s === '-ok' || s === '-okdir') {
+                    // -execdir runs in the match's directory (somewhere under a start dir), with {} as ./NAME
+                    const inDir = s.endsWith('dir');
+                    const r = roots.length === 1 ? concrete(roots[0]) : undefined;
+                    const cmd = [];
+                    for (i++; i < a.length; i++) {
+                        const t = concrete(a[i]);
+                        if (t === ';' || t === '+')
+                            break;
+                        cmd.push(t === '{}' ? (inDir ? concat(known('./'), hole('filename', 'find result')) : foundPath()) : a[i]);
+                    }
+                    const sub = h.subcommand(cmd, { stdin: 'null', ...(inDir ? { cwd: hole('path', 'find result directory', r ? { under: r } : {}) } : {}) });
+                    effects.push(...sub.effects.map(possibly));
+                    if (sub.complete === false)
+                        complete = false;
+                }
+                else if (['-name', '-iname', '-path', '-ipath', '-regex', '-iregex', '-wholename'].includes(s)) {
+                    if (a[i + 1])
+                        h.role(a[i + 1], 'pattern');
+                    i++;
+                }
+                else if (['-name', '-iname', '-path', '-ipath', '-regex', '-iregex', '-type', '-maxdepth', '-mindepth', '-mtime', '-mmin', '-size', '-newer', '-user', '-group', '-perm', '-printf', '-wholename', '-samefile', '-atime', '-ctime', '-links', '-inum', '-uid', '-gid', '-cmin', '-amin', '-newermt', '-context', '-xtype', '-fstype'].includes(s)) {
+                    i++;
+                }
+            }
+            return { effects, readsStdin: false, complete, stdout: { type: 'path', lines: true } };
+        },
+    },
+    {
+        names: ['xargs'],
+        summary: 'build command lines from stdin',
+        analyze(inv, h) {
+            // GNU -i[R], -e[EOF], -l[N] take optional attached arguments only
+            const a = [];
+            const raw = args(inv);
+            for (let k = 0; k < raw.length; k++) {
+                const s = concrete(raw[k]);
+                if (s === undefined || !s.startsWith('-') || s === '--') {
+                    a.push(...raw.slice(k));
+                    break;
+                }
+                const m = /^-([iel])(.*)$/.exec(s);
+                if (s === '--replace')
+                    a.push(known('-I'), known('{}'));
+                else if (!m)
+                    a.push(raw[k]);
+                else if (m[1] === 'i')
+                    a.push(known('-I'), known(m[2] || '{}'));
+                else if (m[1] === 'l')
+                    a.push(known('-L'), known(m[2] || '1'));
+                else if (m[2])
+                    a.push(known('-E'), known(m[2]));
+            }
+            const p = h.parseArgs(a, { short: '0prtxo', shortWithArg: 'EILnPsdaJRS', long: { null: false, 'arg-file': '=a', delimiter: '=d', replace: '=I', 'max-args': '=n', 'max-procs': '=P', 'no-run-if-empty': false, verbose: false, interactive: false, exit: false, 'open-tty': false, 'max-lines': '=L', eof: '=E', 'max-chars': '=s', 'show-limits': false, 'process-slot-var': true }, posix: true });
+            const cmd = p.operands.length > 0 ? p.operands : [known('echo')];
+            const rep = p.flags.get('I') ?? p.flags.get('J');
+            const fromStdin = hole('string', 'xargs input');
+            const argv = rep && rep !== true
+                ? cmd.map((c) => (concrete(c) !== undefined && concrete(rep) !== undefined && concrete(c).includes(concrete(rep)) ? fromStdin : c))
+                : [...cmd, fromStdin];
+            const sub = h.subcommand(argv, { stdin: 'null' });
+            // runs once per input batch, possibly never (empty input)
+            const effects = sub.effects.map(possibly);
+            const af = p.flags.get('a');
+            if (af && af !== true)
+                effects.push({ kind: 'read', path: h.resolve(af) });
+            return { effects, readsStdin: !(af && af !== true), complete: sub.complete !== false && !incomplete(p) };
+        },
+    },
+    // ---- wrappers that run another command ----
+    {
+        names: ['env'],
+        summary: 'run a command in a modified environment',
+        analyze(inv, h) {
+            const a = args(inv);
+            let cwd = inv.cwd;
+            let i = 0;
+            for (; i < a.length; i++) {
+                const s = concrete(a[i]);
+                if (s === undefined)
+                    break;
+                if (s === '-i' || s === '-' || s === '--ignore-environment' || s === '-0' || s === '--null' || s === '-v' || s === '--debug')
+                    continue;
+                if (s === '-C' || s === '--chdir') {
+                    if (a[i + 1])
+                        cwd = h.resolve(a[i + 1]);
+                    i++;
+                    continue;
+                }
+                if (s.startsWith('--chdir=')) {
+                    cwd = h.resolve(known(s.slice('--chdir='.length)));
+                    continue;
+                }
+                if (s === '-u' || s === '-S' || s === '--unset' || s === '--split-string') {
+                    // -S splits its argument into a command line: not modeled
+                    if (s === '-S' || s === '--split-string')
+                        return { effects: [{ kind: 'unknown', detail: 'env -S command line' }], readsStdin: 'maybe', complete: false };
+                    i++;
+                    continue;
+                }
+                if (/^--unset=/.test(s))
+                    continue;
+                if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(s))
+                    continue;
+                break;
+            }
+            if (i >= a.length)
+                return { effects: [], readsStdin: false };
+            return h.subcommand(a.slice(i), { cwd });
+        },
+    },
+    ...['timeout', 'nice', 'nohup', 'time', 'stdbuf', 'ionice', 'caffeinate', 'chrt', 'taskset', 'unbuffer', 'command', 'builtin', 'exec'].map((name) => ({
+        names: [name],
+        summary: 'run another command',
+        analyze(inv, h) {
+            const a = args(inv);
+            let i = 0;
+            const withArg = { timeout: 'sk', nice: 'n', stdbuf: 'ioe', ionice: 'cnp', taskset: '', chrt: '', caffeinate: 'tw', command: '', builtin: '', exec: 'a', nohup: '', time: 'fo', unbuffer: '' };
+            for (; i < a.length; i++) {
+                const s = concrete(a[i]);
+                if (s === undefined || !s.startsWith('-') || s === '-')
+                    break;
+                if (s === '--') {
+                    i++;
+                    break;
+                }
+                if (name === 'command' && (s.includes('v') || s.includes('V')))
+                    return { effects: [], readsStdin: false, stdout: { type: 'path' } };
+                if (s.length === 2 && withArg[name].includes(s[1]))
+                    i++;
+            }
+            if (name === 'timeout')
+                i++; // duration
+            if (name === 'taskset' || name === 'chrt')
+                i++;
+            const rest = a.slice(i);
+            if (rest.length === 0)
+                return { effects: [] };
+            return h.subcommand(rest);
+        },
+    })),
+    {
+        names: ['sudo', 'doas', 'su'],
+        summary: 'run a command as another user',
+        analyze(inv, h) {
+            const a = args(inv);
+            let i = 0;
+            for (; i < a.length; i++) {
+                const s = concrete(a[i]);
+                if (s === undefined || !s.startsWith('-'))
+                    break;
+                if (['-u', '-g', '-C', '-D', '-h', '-p', '-r', '-t', '-U'].includes(s))
+                    i++;
+            }
+            const sub = h.subcommand(a.slice(i));
+            return { ...sub, effects: [{ kind: 'process', detail: 'privilege escalation' }, { kind: 'unknown', detail: 'runs with elevated privileges outside the sandbox' }, ...sub.effects], complete: false };
+        },
+    },
+    {
+        names: ['bash', 'sh', 'zsh', 'dash', 'ksh'],
+        summary: 'run a shell',
+        analyze(inv, h) {
+            const a = args(inv);
+            let i = 0;
+            let script;
+            for (; i < a.length; i++) {
+                const s = concrete(a[i]);
+                if (s === undefined)
+                    break;
+                if (s === '-c') {
+                    script = a[++i];
+                    i++;
+                    break;
+                }
+                if (s === '-o' || s === '-O' || s === '+O' || s === '+o') {
+                    i++;
+                    continue;
+                }
+                if (/^-[a-zA-Z]+$/.test(s) && !s.includes('c'))
+                    continue;
+                if (/^-[a-zA-Z]*c[a-zA-Z]*$/.test(s)) {
+                    script = a[++i];
+                    i++;
+                    break;
+                }
+                break;
+            }
+            if (script)
+                return { ...h.script(script, a.slice(i)), readsStdin: 'maybe' };
+            const file = a[i];
+            if (!file)
+                return { effects: [{ kind: 'unknown', detail: 'shell reads commands from stdin' }], readsStdin: true, complete: false };
+            const text = readScript(h.resolve(file));
+            if (text !== undefined) {
+                const r = h.script(known(text), a.slice(i + 1), { file: concrete(h.resolve(file)) });
+                return { ...r, effects: [{ kind: 'read', path: h.resolve(file) }, ...r.effects], readsStdin: 'maybe' };
+            }
+            return {
+                effects: [{ kind: 'read', path: h.resolve(file) }, { kind: 'unknown', detail: `runs script ${concrete(file) ?? 'file'}` }],
+                readsStdin: 'maybe',
+                complete: false,
+            };
+        },
+    },
+    // ---- network ----
+    {
+        names: ['curl'],
+        summary: 'transfer a URL',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), {
+                short: 'sSfLIkvOJgiNqZ#lRB0123456', shortWithArg: 'oXHdAuFeTxwmrbcEKYyzCQDtP',
+                long: { output: '=o', 'remote-name': false, request: '=X', header: '=H', data: '=d', 'data-raw': true, 'data-binary': true, 'data-urlencode': true, form: '=F', 'upload-file': '=T', user: '=u', silent: false, 'show-error': false, fail: false, location: false, insecure: false, verbose: false, include: false, head: false, 'max-time': '=m', retry: true, 'connect-timeout': true, 'write-out': '=w', cookie: '=b', 'cookie-jar': '=c', 'dump-header': '=D', compressed: false, 'create-dirs': false, json: true, url: true, 'user-agent': '=A', proxy: '=x', 'fail-with-body': false, 'retry-delay': true, 'output-dir': true, 'remote-name-all': false, config: '=K' },
+            });
+            const effects = [];
+            const urls = [...p.operands, ...(p.multi.get('url') ?? [])];
+            for (const u of urls)
+                effects.push({ kind: 'network', target: u, detail: 'curl' });
+            for (const o of p.multi.get('o') ?? [])
+                if (concrete(o) !== '-')
+                    effects.push({ kind: 'write', path: h.resolve(o) });
+            if (p.flags.has('O') || p.flags.has('remote-name'))
+                effects.push({ kind: 'write', path: h.resolve(hole('filename', 'remote name')) });
+            for (const k of ['c', 'D']) {
+                const v = p.flags.get(k);
+                if (v && v !== true && concrete(v) !== '-')
+                    effects.push({ kind: 'write', path: h.resolve(v) });
+            }
+            for (const k of ['T', 'K']) {
+                const v = p.flags.get(k);
+                if (v && v !== true)
+                    effects.push({ kind: 'read', path: h.resolve(v) });
+            }
+            for (const d of [...(p.multi.get('d') ?? []), ...(p.multi.get('data-binary') ?? []), ...(p.multi.get('F') ?? [])]) {
+                const s = knownPrefix(d);
+                if (s.startsWith('@'))
+                    effects.push({ kind: 'read', path: h.resolve({ alts: d.alts.map((alt) => [typeof alt[0] === 'string' ? alt[0].slice(1) : '', ...alt.slice(1)]) }) });
+                const at = /^[^=]*=@/.exec(s);
+                if (at)
+                    effects.push({ kind: 'read', path: h.resolve(known(s.slice(at[0].length))) });
+            }
+            return { effects, readsStdin: false, complete: !incomplete(p) };
+        },
+    },
+    {
+        names: ['wget'],
+        summary: 'download files',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), { short: 'qvcNrkpmb', shortWithArg: 'OPoaltTUe', long: { 'output-document': '=O', 'directory-prefix': '=P', quiet: false, 'no-verbose': false, continue: false, recursive: false, mirror: false, 'no-check-certificate': false, header: true, 'user-agent': '=U', timeout: '=T', tries: '=t' } });
+            const effects = p.operands.map((u) => ({ kind: 'network', target: u, detail: 'wget' }));
+            const out = p.flags.get('O');
+            const dir = p.flags.get('P');
+            if (out && out !== true) {
+                if (concrete(out) !== '-')
+                    effects.push({ kind: 'write', path: h.resolve(out) });
+            }
+            else {
+                const base = dir && dir !== true ? h.resolve(dir) : inv.cwd;
+                effects.push({ kind: 'write', path: base, recursive: true });
+            }
+            return { effects, readsStdin: false, complete: !incomplete(p) };
+        },
+    },
+    ...Object.entries(NET_CLIENTS).map(([name, spec]) => ({
+        names: [name],
+        summary: 'network client',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), spec);
+            const remote = (v) => /^[^/]*:/.test(knownPrefix(v));
+            const ops = p.operands.filter((o) => !(name === 'dig' && knownPrefix(o).startsWith('+')));
+            // the host: dig @server, `host NAME [SERVER]`, `nslookup NAME [SERVER]`; scp's remote operands; else the first operand
+            const server = ops.find((o) => knownPrefix(o).startsWith('@'));
+            let target;
+            if (name === 'dig')
+                target = server ? { alts: server.alts.map((alt) => [typeof alt[0] === 'string' ? alt[0].slice(1) : alt[0], ...alt.slice(1)]) } : ops.find((o) => o !== server && !/^(A|AAAA|MX|NS|TXT|CNAME|SOA|PTR|SRV|ANY|CAA|HTTPS|IN|CH)$/.test(concrete(o) ?? ''));
+            else if (name === 'host' || name === 'nslookup')
+                target = ops[1] ?? ops[0];
+            else if (name === 'scp' || name === 'rsync')
+                target = ops.find(remote);
+            else
+                target = ops[0];
+            const effects = [{ kind: 'network', detail: name, ...(target ? { target } : {}) }];
+            // ssh keys and configuration
+            if (/^(ssh|scp|sftp)$/.test(name)) {
+                for (const k of ['i', 'F'])
+                    for (const v of p.multi.get(k) ?? [])
+                        effects.push({ kind: 'read', path: h.resolve(v) });
+                effects.push({ kind: 'read', path: concat(h.home() ?? known('~'), known('/.ssh')), recursive: true, maybe: true });
+                const log = p.flags.get('E');
+                if (log && log !== true)
+                    effects.push({ kind: 'write', path: h.resolve(log), append: true });
+            }
+            if (name === 'scp') {
+                const files = p.operands;
+                for (const o of files.slice(0, -1))
+                    if (!remote(o))
+                        effects.push({ kind: 'read', path: h.resolve(o), ...(p.flags.has('r') ? { recursive: true } : {}) });
+                const last = files[files.length - 1];
+                if (last && !remote(last))
+                    effects.push({ kind: 'write', path: h.resolve(last), ...(p.flags.has('r') ? { recursive: true } : {}) });
+            }
+            if (name === 'sftp')
+                for (const v of p.multi.get('b') ?? [])
+                    if (concrete(v) !== '-')
+                        effects.push({ kind: 'read', path: h.resolve(v) });
+            if (name === 'dig')
+                for (const k of ['f', 'k'])
+                    for (const v of p.multi.get(k) ?? [])
+                        effects.push({ kind: 'read', path: h.resolve(v) });
+            if (name === 'telnet')
+                for (const v of p.multi.get('n') ?? [])
+                    effects.push({ kind: 'write', path: h.resolve(v) });
+            // queries are complete; sessions may run remote commands, transfer data, or (ProxyCommand, scp -S, nc -e) run local ones
+            const complete = /^(ping|ping6|dig|nslookup|host|traceroute|traceroute6)$/.test(name) && p.unknownFlags.length === 0;
+            if (!complete)
+                effects.push({ kind: 'unknown', detail: `${name} may run remote commands or transfer data` });
+            return { effects, readsStdin: complete ? false : 'maybe', complete };
+        },
+    })),
+    // ---- archives ----
+    {
+        names: ['tar', 'bsdtar', 'gtar'],
+        summary: 'archive files',
+        analyze(inv, h) {
+            const a = args(inv);
+            // first arg may be a bundled flag word without dash: `tar xzf x.tgz`
+            const first = concrete(a[0] ?? known(''));
+            const list = first !== undefined && /^[A-Za-z]+$/.test(first) && !first.startsWith('-') ? [known('-' + first), ...a.slice(1)] : a;
+            const p = h.parseArgs(list, { short: 'cxtrudzjJavpPkmhOSwBiG', shortWithArg: 'fCTXbIL', long: { create: false, extract: false, list: false, file: '=f', directory: '=C', gzip: false, bzip2: false, xz: false, zstd: false, 'auto-compress': false, verbose: false, exclude: true, 'exclude-from': '=X', 'files-from': '=T', null: false, 'no-xattrs': false, xattrs: false, 'keep-old-files': false, 'skip-old-files': false, overwrite: false, 'no-same-owner': false, 'no-same-permissions': false, 'strip-components': true, 'to-stdout': false, append: false, update: false, transform: true, 'exclude-vcs': false, 'owner': true, 'group': true, 'mtime': true, sort: true, 'numeric-owner': false, 'use-compress-program': '=I', wildcards: false, 'no-recursion': false, dereference: false, 'one-file-system': false, totals: false, 'checkpoint': true, 'warning': true, format: true, 'show-transformed-names': false, absolute: false } });
+            const archive = p.flags.get('f');
+            const dir = p.flags.get('C');
+            const base = dir && dir !== true ? h.resolve(dir) : inv.cwd;
+            const effects = [];
+            const resolveIn = (v) => (knownPrefix(v).startsWith('/') ? v : h.resolve(v));
+            const toStdin = !archive || archive === true || concrete(archive) === '-';
+            // member lists from a file (`-T list`, `-T -`) and compress programs: not modeled
+            const filesFrom = p.flags.get('T');
+            let complete = !incomplete(p) && !p.flags.has('I');
+            if (filesFrom && filesFrom !== true) {
+                complete = false;
+                if (concrete(filesFrom) !== '-')
+                    effects.push({ kind: 'read', path: h.resolve(filesFrom) });
+            }
+            const excludeFrom = p.flags.get('X');
+            if (excludeFrom && excludeFrom !== true)
+                effects.push({ kind: 'read', path: h.resolve(excludeFrom) });
+            const listOnStdin = filesFrom !== undefined && filesFrom !== true && concrete(filesFrom) === '-';
+            if (p.flags.has('c') || p.flags.has('r') || p.flags.has('u') || p.flags.has('create')) {
+                for (const o of p.operands)
+                    effects.push({ kind: 'read', path: dir && dir !== true ? concatPath(base, o) : resolveIn(o), recursive: true });
+                if (!toStdin)
+                    effects.push({ kind: 'write', path: h.resolve(archive) });
+                return { effects, readsStdin: listOnStdin, complete };
+            }
+            if (!toStdin)
+                effects.push({ kind: 'read', path: h.resolve(archive) });
+            if (p.flags.has('x') || p.flags.has('extract')) {
+                if (!p.flags.has('O') && !p.flags.has('to-stdout'))
+                    effects.push({ kind: 'write', path: base, recursive: true });
+            }
+            return { effects, readsStdin: toStdin || listOnStdin, complete };
+        },
+    },
+    {
+        names: ['unzip'],
+        summary: 'extract zip archives',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), { short: 'lnoqjpCLtvVXa', shortWithArg: 'dxP' });
+            const effects = [];
+            if (p.operands[0])
+                effects.push({ kind: 'read', path: h.resolve(p.operands[0]) });
+            const d = p.flags.get('d');
+            if (!p.flags.has('l') && !p.flags.has('p') && !p.flags.has('t'))
+                effects.push({ kind: 'write', path: d && d !== true ? h.resolve(d) : inv.cwd, recursive: true });
+            return { effects, readsStdin: false, complete: !incomplete(p) };
+        },
+    },
+    {
+        names: ['zip'],
+        summary: 'create zip archives',
+        analyze(inv, h) {
+            const p = h.parseArgs(args(inv), { short: 'rqvjmTyDXF0123456789', shortWithArg: 'xid' });
+            const [archive, ...files] = p.operands;
+            const effects = files.map((f) => ({ kind: 'read', path: h.resolve(f), recursive: p.flags.has('r') }));
+            if (archive)
+                effects.push({ kind: 'write', path: h.resolve(archive) });
+            if (p.flags.has('m'))
+                for (const f of files)
+                    effects.push({ kind: 'delete', path: h.resolve(f), recursive: p.flags.has('r') });
+            return { effects, readsStdin: false, complete: !incomplete(p) };
+        },
+    },
+    {
+        names: ['gzip', 'gunzip', 'bzip2', 'bunzip2', 'xz', 'unxz', 'zstd', 'unzstd', 'zcat', 'bzcat', 'xzcat'],
+        summary: 'compress / decompress',
+        analyze(inv, h) {
+            const zstd = /zstd/.test(inv.name);
+            const p = h.parseArgs(args(inv), { short: 'cdfklnNqrtvzZ0123456789TeFhHLV', shortWithArg: zstd ? 'SoD' : 'S', long: { stdout: '=c', 'to-stdout': '=c', decompress: '=d', uncompress: '=d', keep: '=k', force: '=f', recursive: '=r', list: '=l', test: '=t', suffix: '=S', quiet: '=q', verbose: '=v', best: false, fast: false, rm: false, output: true, 'no-name': false, name: false, threads: true, ultra: false, long: false, rsyncable: false, extreme: false, format: true } });
+            const toStdout = p.flags.has('c') || /cat$/.test(inv.name) || p.flags.has('t') || p.flags.has('l');
+            const decompress = p.flags.has('d') || /^[gb]?un|cat$/.test(inv.name);
+            const recursive = p.flags.has('r');
+            const sv = p.flags.get('S');
+            const suffix = sv && sv !== true ? sv : known(/bz|bunzip/.test(inv.name) ? '.bz2' : inv.name.includes('xz') ? '.xz' : zstd ? '.zst' : '.gz');
+            // zstd keeps its input unless --rm; -o names the output
+            const keep = p.flags.has('k') || (zstd && !p.flags.has('rm'));
+            const out = p.flags.get('o') ?? p.flags.get('output');
+            const effects = [];
+            for (const f of p.operands) {
+                if (isStdinOperand(f))
+                    continue;
+                const src = h.resolve(f);
+                effects.push({ kind: 'read', path: src, ...(recursive ? { recursive } : {}) });
+                if (toStdout)
+                    continue;
+                if (out && out !== true) {
+                    if (!isStdinOperand(out))
+                        effects.push({ kind: 'write', path: h.resolve(out) });
+                }
+                else if (recursive) {
+                    // every file below is replaced by its (de)compressed sibling
+                    effects.push({ kind: 'write', path: src, recursive: true });
+                }
+                else {
+                    // writes the (de)compressed sibling and removes the original
+                    const sfx = concrete(suffix);
+                    const name = concrete(src);
+                    const target = !decompress
+                        ? concat(src, suffix)
+                        : name !== undefined && sfx !== undefined && name.endsWith(sfx) && name.length > sfx.length
+                            ? known(name.slice(0, -sfx.length))
+                            : name !== undefined && /\.(t?gz|bz2|xz|zst|z|Z|tbz2?|txz|tzst)$/.test(name)
+                                ? known(name.replace(/\.(gz|bz2|xz|zst|z|Z)$/, '').replace(/\.t(gz|bz2?|xz|zst)$/, '.tar'))
+                                : name !== undefined ? concat(known(name.slice(0, name.lastIndexOf('/') + 1)), hole('filename', 'decompressed name')) : hole('path', 'decompressed file');
+                    effects.push({ kind: 'write', path: target });
+                }
+                if (!keep)
+                    effects.push({ kind: 'delete', path: src, ...(recursive ? { recursive } : {}) });
+            }
+            return { effects, readsStdin: p.operands.length === 0 || p.operands.some(isStdinOperand), complete: !incomplete(p) };
+        },
+    },
+    // ---- process control ----
+    {
+        names: ['kill', 'pkill', 'killall'],
+        summary: 'signal processes',
+        analyze: (inv) => ({ effects: [{ kind: 'process', detail: `signal ${args(inv).map((a) => concrete(a) ?? '?').join(' ')}` }], readsStdin: false }),
+    },
+];
+/** Contents of a script file named by a concrete path (behaviors may read, never write). */
+export function readScript(p) {
+    const file = concrete(p);
+    if (file === undefined)
+        return undefined;
+    try {
+        const st = fs.statSync(file);
+        if (!st.isFile() || st.size > 1024 * 1024)
+            return undefined;
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The possible texts of a program argument (sed script, awk program): each
+ * alternative of a finite value, with integer holes (`$((a+1))`) filled in
+ * by a digit, since a number cannot add a command. Undefined when the text
+ * has other unknown parts.
+ */
+function programTexts(v) {
+    const out = [];
+    for (const alt of v.alts) {
+        let s = '';
+        for (const seg of alt) {
+            if (typeof seg === 'string')
+                s += seg;
+            else if (seg.type === 'int')
+                s += '0';
+            else
+                return undefined;
+        }
+        out.push(s);
+    }
+    return out;
+}
+/** The same effect, marked as only possible. */
+function possibly(e) {
+    return e.kind === 'read' || e.kind === 'write' || e.kind === 'delete' ? { ...e, maybe: true } : e;
+}
+function concatPath(base, rel) {
+    if (knownPrefix(rel).startsWith('/'))
+        return rel;
+    return { alts: base.alts.flatMap((b) => rel.alts.map((r) => [...b, '/', ...r])) };
+}
+//# sourceMappingURL=core.js.map