@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/behaviors/defs/core.ts

@@ -0,0 +1,970 @@
+/**
+ * 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 type { AValue } from '../../analysis/value.ts'
+import { concat, concrete, hole, known, knownPrefix } from '../../analysis/value.ts'
+import type { Effect } from '../../policy/effects.ts'
+import type { ArgSpec, Behavior, BehaviorResult, Invocation } from '../types.ts'
+import { analyzeDef, define, type Def } from '../dsl.ts'
+
+const args = (inv: Invocation): AValue[] => inv.argv.slice(1)
+
+function incomplete(p: { unknownFlags: string[] }): boolean {
+  return p.unknownFlags.length > 0
+}
+
+const isStdinOperand = (v: AValue): boolean => concrete(v) === '-'
+
+/** A filter that reads its file operands (or stdin when there are none) and writes stdout. */
+function reader(names: string[], spec: ArgSpec, summary: string, more: Def = {}): Behavior {
+  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: string[], summary: string, stdout?: BehaviorResult['stdout']): Behavior {
+  return { names, summary, analyze: () => ({ effects: [], readsStdin: false, stdout }) }
+}
+
+const BSD = process.platform === 'darwin'
+const SSH_SPEC: ArgSpec = { short: '46AaCfGgKkMNnqsTtVvXxYy', shortWithArg: 'BbcDEeFIiJLlmOoPpQRSWw', posix: true }
+const NET_CLIENTS: Record<string, ArgSpec> = {
+  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: Def = {
+  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: ArgSpec = { 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: Behavior[] = [
+  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: Effect[] = []
+      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: Effect[] = []
+      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: Effect[] = 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): Effect[] => {
+          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): Effect[] => (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): Effect => ({ 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: Effect[] = [{ 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: Effect[] = []
+      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: AValue): boolean => /^[^/]*:/.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: string): AValue | undefined => {
+        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: Effect[] = []
+      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: string | undefined = 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: Effect[] = []
+      let readsStdin = true
+      for (const a of args(inv)) {
+        const s = knownPrefix(a)
+        const rest = (prefix: string): AValue => ({ 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: AValue[] = []
+      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: Effect[] = 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: AValue | undefined
+      const f = p.flags.get('f')
+      const effects: Effect[] = []
+      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: AValue[] = []
+      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: Effect[] = 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 = (): AValue => {
+        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: AValue[] = []
+          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: AValue[] = []
+      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): Behavior => ({
+    names: [name],
+    summary: 'run another command',
+    analyze(inv, h) {
+      const a = args(inv)
+      let i = 0
+      const withArg: Record<string, string> = { 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: AValue | undefined
+      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: Effect[] = []
+      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: Effect[] = 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]): Behavior => ({
+    names: [name],
+    summary: 'network client',
+    analyze(inv, h) {
+      const p = h.parseArgs(args(inv), spec)
+      const remote = (v: AValue): boolean => /^[^/]*:/.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: AValue | undefined
+      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: Effect[] = [{ 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: Effect[] = []
+      const resolveIn = (v: AValue): AValue => (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 as AValue) })
+        return { effects, readsStdin: listOnStdin, complete }
+      }
+      if (!toStdin) effects.push({ kind: 'read', path: h.resolve(archive as AValue) })
+      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: Effect[] = []
+      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: Effect[] = 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: Effect[] = []
+      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: AValue = !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: AValue): string | undefined {
+  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: AValue): string[] | undefined {
+  const out: string[] = []
+  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: Effect): Effect {
+  return e.kind === 'read' || e.kind === 'write' || e.kind === 'delete' ? { ...e, maybe: true } : e
+}
+
+function concatPath(base: AValue, rel: AValue): AValue {
+  if (knownPrefix(rel).startsWith('/')) return rel
+  return { alts: base.alts.flatMap((b) => rel.alts.map((r) => [...b, '/', ...r])) }
+}