@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/behaviors/defs/tools.ts

@@ -0,0 +1,596 @@
+/**
+ * Behavior definitions for common command-line tools beyond coreutils:
+ * databases, document and media tools, downloaders, crypto, and local
+ * service CLIs. Most are table definitions (see ../dsl.ts); tools whose
+ * argument syntax the table cannot express (ffmpeg, sqlite3) are written out.
+ */
+
+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 { define, type Def } from '../dsl.ts'
+import type { Behavior, Invocation } from '../types.ts'
+
+const args = (inv: Invocation): AValue[] => inv.argv.slice(1)
+const isDash = (v: AValue): boolean => concrete(v) === '-'
+const isUrl = (v: AValue): boolean => /^[a-z][a-z0-9+.-]*:\/\//i.test(knownPrefix(v))
+
+/** Accepts any flags and operands; no effects of its own (query subcommands). */
+const QUERY: Def = { anyFlags: true, operands: 'arg*', stdin: false }
+/** Changes state the definition cannot describe. */
+const opaque = (detail: string): Def => ({ anyFlags: true, operands: 'arg*', opaque: detail, stdin: 'maybe' })
+
+/** The directory part of a path value (`dir/` for `dir/x`), or undefined. */
+function dirOf(p: AValue): AValue | undefined {
+  const s = concrete(p)
+  if (s === undefined) return undefined
+  const i = s.lastIndexOf('/')
+  return known(i <= 0 ? (i === 0 ? '/' : '.') : s.slice(0, i))
+}
+
+/** `x.typ` → `x.<ext>`: a sibling with another extension (unknown if the name is). */
+function sibling(p: AValue, ext: string): AValue {
+  const s = concrete(p)
+  if (s !== undefined) return known(s.replace(/\.[^./]*$/, '') + ext)
+  const d = dirOf(p)
+  return d ? concat(d, known('/'), hole('filename', 'output name')) : hole('path', 'output file')
+}
+
+// ---------------------------------------------------------------------------
+// sqlite3
+// ---------------------------------------------------------------------------
+
+/** Dot commands that only print or set display options. */
+const SQLITE_SAFE_DOT = /^\.(tables|schema|indexes|indices|headers?|mode|width|timer|timeout|nullvalue|separator|print|quit|exit|help|databases|changes|eqp|stats|bail|echo|show|dbinfo|fullschema|lint|selftrace|parameter|limits?|explain|columns|prompt|dump|version|vfsinfo|vfsname|vfslist|sha3sum|binary|crnl|expert|scanstats)\b/
+
+function sqlTexts(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'
+      // a string inside quotes can only be data if it has no quote of its own: not knowable
+      else return undefined
+    }
+    out.push(s)
+  }
+  return out
+}
+
+const SQL_MODIFIES = /\b(insert|update|delete|replace|upsert|create|drop|alter|vacuum|reindex|analyze|begin|commit|savepoint|release|restore)\b|\bpragma\s+\w+(\.\w+)?\s*=|^\s*\.(restore|import)\b/im
+const unquote = (w: string): string => w.replace(/^(['"])(.*)\1$/, '$2')
+
+/**
+ * The files this SQL (with dot commands) touches beyond the database, or
+ * undefined when it can reach outside what can be described: other databases,
+ * extensions, the shell's file functions, `.read` scripts, pipes to commands.
+ */
+function sqlFiles(text: string): { kind: 'read' | 'write'; file: string }[] | undefined {
+  const files: { kind: 'read' | 'write'; file: string }[] = []
+  for (const line of text.split('\n')) {
+    const t = line.trim()
+    if (!t.startsWith('.') || SQLITE_SAFE_DOT.test(t)) continue
+    const [cmd, ...words] = t.split(/\s+/).map(unquote)
+    const ops = words.filter((w) => !w.startsWith('-'))
+    const last = ops[ops.length - 1]
+    if (/^\.(backup|save|output|once)$/.test(cmd)) {
+      if (cmd === '.backup' || cmd === '.save' ? !last : false) return undefined
+      if (last === undefined) continue // `.output` alone: back to stdout
+      if (last.startsWith('|') || words.some((w) => /^-[ex]$/.test(w))) return undefined // to a command or an editor
+      files.push({ kind: 'write', file: last })
+    } else if (cmd === '.import' && ops[0] && !ops[0].startsWith('|')) files.push({ kind: 'read', file: ops[0] })
+    else return undefined
+  }
+  if (/\battach\b|\bvacuum\s+into\b|\b(load_extension|writefile|readfile|edit|fsdir|zipfile|sqlar_compress|sqlar_uncompress|lsmode)\s*\(/i.test(text.split('\n').filter((l) => !l.trim().startsWith('.')).join('\n'))) return undefined
+  return files
+}
+
+const sqlite3: Behavior = {
+  names: ['sqlite3', 'sqlite'],
+  summary: 'SQLite shell (sqlite3 [opts] DB [SQL...])',
+  analyze(inv, h) {
+    const p = h.parseArgs(args(inv), {
+      longSingle: true,
+      long: {
+        readonly: false, header: false, noheader: false, column: false, csv: false, json: false, line: false, list: false, box: false, markdown: false, table: false, html: false, tabs: false, quote: false, ascii: false,
+        batch: false, bail: false, echo: false, interactive: false, safe: false, nofollow: false, stats: false, version: false, help: false, memtrace: false, unsafe_testing: false,
+        separator: true, newline: true, nullvalue: true, cmd: true, init: true, vfs: true, mmap: true, append: false, deserialize: false, maxsize: true, nonce: true, A: true, zip: false,
+      },
+    })
+    if (p.flags.has('version') || p.flags.has('help')) return { effects: [], readsStdin: false }
+    const [db, ...sql] = p.operands
+    const effects: Effect[] = []
+    let complete = p.unknownFlags.length === 0 && !p.flags.has('A') && !p.flags.has('zip')
+    const init = p.flags.get('init')
+    if (init && init !== true) {
+      effects.push({ kind: 'read', path: h.resolve(init) })
+      complete = false
+    }
+    const programs = [...sql, ...(p.multi.get('cmd') ?? [])]
+    for (const s of programs) {
+      h.role(s, 'code')
+      for (const text of sqlTexts(s) ?? [undefined]) {
+        const files = text === undefined ? undefined : sqlFiles(text)
+        if (!files) complete = false
+        for (const f of files ?? []) effects.push({ kind: f.kind, path: h.resolve(known(f.file)) })
+      }
+    }
+    const name = db === undefined ? '' : concrete(db)
+    if (db !== undefined && name !== '' && name !== ':memory:') {
+      if (knownPrefix(db).startsWith('file:')) complete = false
+      const path = h.resolve(db)
+      effects.push({ kind: 'read', path })
+      if (!p.flags.has('readonly')) {
+        // statements that change the database write it; unknown or stdin SQL may
+        const texts = programs.map((v) => sqlTexts(v))
+        const modifies = texts.some((t) => t?.some((x) => SQL_MODIFIES.test(x)))
+        const unknown = texts.some((t) => t === undefined) || sql.length === 0
+        if (modifies || unknown) effects.push({ kind: 'write', path, ...(modifies ? {} : { maybe: true }) })
+        // even reads may create the -wal/-shm/-journal siblings
+        effects.push({ kind: 'write', path: { alts: ['-wal', '-shm', '-journal'].flatMap((sfx) => path.alts.map((a) => [...a, sfx])) }, maybe: true })
+      }
+    }
+    // no SQL arguments: statements come from stdin
+    if (sql.length === 0) {
+      if (programs.length === 0) complete = false
+      return { effects, readsStdin: true, complete }
+    }
+    return { effects, readsStdin: false, complete }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// typst
+// ---------------------------------------------------------------------------
+
+const TYPST_GLOBAL = { short: 'hV', long: { help: false, version: false, color: true, cert: true } }
+const TYPST_WORLD = {
+  root: true, input: true, 'font-path': true, 'ignore-system-fonts': false, 'ignore-embedded-fonts': false, 'package-path': true, 'package-cache-path': true,
+  'creation-timestamp': true, features: true, 'diagnostic-format': true, jobs: '=j', format: '=f', ppi: true, pages: true, 'pdf-standard': true, 'no-pdf-tags': false,
+  'make-deps': true, deps: true, 'deps-format': true, open: true, timings: true, field: true, one: false, target: true, pretty: false, 'no-serve': false, 'no-reload': false, port: true,
+}
+
+/** typst compile/watch/query: reads the project (input's directory or --root), may fetch packages. */
+function typstCompile(withOutput: boolean): Def {
+  return {
+    spec: { shortWithArg: 'jf', long: TYPST_WORLD },
+    operands: withOutput ? 'read write?' : 'read pattern?',
+    flags: { 'font-path': 'read:dir', 'make-deps': 'write', deps: 'write', timings: 'write' },
+    extra: (r, { inv, h, p, operands }) => {
+      const effects = [...r.effects]
+      const [input, output] = operands
+      const rootFlag = p.flags.get('root')
+      const root = rootFlag && rootFlag !== true ? h.resolve(rootFlag) : input && !isDash(input) ? dirOf(h.resolve(input)) : inv.cwd
+      if (root) effects.push({ kind: 'read', path: root, recursive: true })
+      if (withOutput && input && !output && !isDash(input)) {
+        const fmt = concrete((p.flags.get('f') as AValue | undefined) ?? known('pdf')) ?? 'pdf'
+        effects.push({ kind: 'write', path: sibling(h.resolve(input), '.' + fmt) })
+      }
+      // `@preview` packages are downloaded into the cache on first use
+      effects.push({ kind: 'network', detail: 'typst packages', maybe: true })
+      const cache = p.flags.get('package-cache-path')
+      effects.push(cache && cache !== true
+        ? { kind: 'write', path: h.resolve(cache), recursive: true, maybe: true }
+        : { kind: 'write', path: concat(h.home() ?? known('~'), known(process.platform === 'darwin' ? '/Library/Caches/typst' : '/.cache/typst')), recursive: true, maybe: true })
+      const complete = r.complete !== false && !p.flags.has('open')
+      return { ...r, effects, complete, readsStdin: input !== undefined && isDash(input) }
+    },
+  }
+}
+
+const typst = define({
+  names: ['typst'], summary: 'typesetting', spec: TYPST_GLOBAL,
+  subcommands: {
+    'compile|c': typstCompile(true),
+    'watch|w': typstCompile(true),
+    'query|q': { ...typstCompile(false), stdout: { type: 'string' } },
+    fonts: { spec: { long: { 'font-path': true, 'ignore-system-fonts': false, 'ignore-embedded-fonts': false, variants: false } }, flags: { 'font-path': 'read:dir' }, stdin: false },
+    'init|update': opaque('typst downloads templates or updates itself'),
+    help: QUERY,
+  },
+})
+
+// ---------------------------------------------------------------------------
+// ffmpeg / ffprobe
+// ---------------------------------------------------------------------------
+
+const FFMPEG_BOOL = new Set([
+  '-y', '-n', '-nostdin', '-stdin', '-hide_banner', '-stats', '-nostats', '-an', '-vn', '-sn', '-dn', '-shortest', '-re', '-benchmark', '-benchmark_all', '-copyts', '-start_at_zero',
+  '-accurate_seek', '-noaccurate_seek', '-autorotate', '-noautorotate', '-ignore_unknown', '-copy_unknown', '-dump', '-hex', '-xerror', '-bitexact', '-debug_ts', '-version', '-h', '-help',
+  '-formats', '-codecs', '-encoders', '-decoders', '-filters', '-pix_fmts', '-layouts', '-sample_fmts', '-protocols', '-muxers', '-demuxers', '-devices', '-bsfs', '-buildconf', '-hwaccels',
+  '-show_format', '-show_streams', '-show_packets', '-show_frames', '-show_chapters', '-show_programs', '-show_error', '-show_data', '-show_private_data', '-show_program_version',
+  '-show_library_versions', '-show_versions', '-show_pixel_formats', '-count_frames', '-count_packets', '-pretty', '-unit', '-prefix', '-byte_binary_prefix', '-sexagesimal', '-show_optional_fields',
+  '-shortest_buf_duration', '-dts_delta_threshold', '-vsync', '-fix_sub_duration', '-apad', '-nostdin',
+])
+/** Options whose value names a file read or written. */
+const FFMPEG_READS = new Set(['-filter_complex_script', '-filter_script', '-attach', '-i'])
+const FFMPEG_WRITES = new Set(['-vstats_file', '-passlogfile', '-progress', '-o'])
+const FFMPEG_PATH_VALUE = new Set([...FFMPEG_READS, ...FFMPEG_WRITES, '-dump_attachment'])
+
+const ffmpeg: Behavior = {
+  names: ['ffmpeg', 'ffprobe', 'ffplay'],
+  summary: 'audio/video conversion',
+  analyze(inv, h) {
+    const a = args(inv)
+    const probe = inv.name !== 'ffmpeg'
+    const effects: Effect[] = []
+    const inputs: AValue[] = []
+    const outputs: AValue[] = []
+    let complete = true
+    let nostdin = probe
+    let stdinInput = false
+    for (let i = 0; i < a.length; i++) {
+      const s = concrete(a[i])
+      if (s === undefined) {
+        // an unknown word that may be an option (and then perhaps take a value): not known
+        if (knownPrefix(a[i]).startsWith('-')) complete = false
+        else (probe ? inputs : outputs).push(a[i])
+        continue
+      }
+      if (s === '-' || !s.startsWith('-')) {
+        ;(probe ? inputs : outputs).push(a[i])
+        continue
+      }
+      if (s === '-nostdin') nostdin = true
+      if (FFMPEG_BOOL.has(s) || (/^-(no)?(show|count)_/.test(s) && s !== '-show_entries' && s !== '-show_optional_fields')) continue
+      if (s === '-report') {
+        effects.push({ kind: 'write', path: concat(inv.cwd, known('/'), hole('filename', 'ffmpeg report')) })
+        continue
+      }
+      const v = a[++i]
+      if (v === undefined) break
+      const name = s.replace(/:.*$/, '')
+      // a path-like value for an option not known to take one: maybe a boolean option we do not know, then an output file
+      if (!FFMPEG_PATH_VALUE.has(name) && /\/|\.[A-Za-z0-9]{2,4}$/.test(concrete(v) ?? '') && !/^-(metadata|vf|af|filter|filter_complex|lavfi|map|ss|t|to|sseof|f|c|codec|tag)$/.test(name)) complete = false
+      if (name === '-i') inputs.push(v)
+      else if (FFMPEG_READS.has(name)) effects.push({ kind: 'read', path: h.resolve(v) })
+      else if (FFMPEG_WRITES.has(name)) {
+        if (!isDash(v) && !isUrl(v) && concrete(v) !== 'pipe:1') effects.push({ kind: 'write', path: h.resolve(v) })
+      } else if (/^-(vf|af|filter|filter_complex|lavfi)$/.test(name)) {
+        h.role(v, 'code')
+        // filters can open (movie=, subtitles=) or write (file=, stats_file=) files
+        const t = concrete(v)
+        if (t === undefined || /\b(movie|amovie|subtitles|ass|lut3d|lut1d|haldclut|sendcmd|asendcmd|zmq|azmq|file|filename|stats_file|result|f|ocr)\s*=/.test(t) || /\bf=/.test(t)) complete = false
+      } else if (name === '-f' && /^(concat|lavfi|tee|segment|hls|dash|image2pipe|fifo)$/.test(concrete(v) ?? '')) {
+        // inputs listing other files, filter-graph inputs, several outputs
+        if (!/^(segment|hls|dash)$/.test(concrete(v)!)) complete = false
+      }
+    }
+    for (const v of inputs) {
+      const t = concrete(v)
+      if (t === '-' || t === 'pipe:' || t === 'pipe:0') stdinInput = true
+      else if (isUrl(v)) effects.push({ kind: 'network', target: v, detail: inv.name })
+      else if (t !== undefined && /^[a-z]+:/.test(t) && !/^file:/.test(t)) complete = false // concat:, subfile:, … protocols
+      else effects.push({ kind: 'read', path: h.resolve(v) })
+    }
+    for (const v of outputs) {
+      const t = concrete(v)
+      if (t === '-' || t === 'pipe:' || t === 'pipe:1') continue
+      if (isUrl(v)) effects.push({ kind: 'network', target: v, detail: inv.name })
+      else effects.push({ kind: 'write', path: h.resolve(v) })
+    }
+    // ffmpeg reads keyboard commands from stdin unless -nostdin
+    return { effects, readsStdin: stdinInput || (nostdin ? false : 'maybe'), complete }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// yt-dlp
+// ---------------------------------------------------------------------------
+
+const ytdlp = define({
+  names: ['yt-dlp', 'youtube-dl'], summary: 'download videos',
+  spec: {
+    short: 'FqvsjJgeixwciUN', shortWithArg: 'foPNraRIS',
+    long: {
+      format: '=f', 'list-formats': '=F', output: '=o', paths: '=P', 'concurrent-fragments': '=N', quiet: '=q', verbose: '=v', 'no-progress': false, progress: false, 'no-part': false,
+      'cookies-from-browser': true, cookies: true, 'extractor-args': true, 'skip-download': false, print: true, 'print-to-file': 2, 'flat-playlist': false, 'dump-json': '=j', 'dump-single-json': '=J',
+      simulate: '=s', 'no-simulate': false, version: false, help: false, 'get-url': '=g', 'get-title': '=e', 'extract-audio': '=x', 'audio-format': true, 'audio-quality': true, 'merge-output-format': true,
+      'remux-video': true, 'recode-video': true, 'write-subs': false, 'write-auto-subs': false, 'sub-langs': true, 'sub-format': true, 'embed-subs': false, 'write-thumbnail': false, 'embed-thumbnail': false,
+      'embed-metadata': false, 'no-playlist': false, 'yes-playlist': false, 'playlist-items': '=I', 'limit-rate': '=r', retries: '=R', 'batch-file': '=a', 'no-warnings': false, 'no-overwrites': '=w',
+      continue: '=c', newline: false, 'restrict-filenames': false, impersonate: true, 'user-agent': true, referer: true, 'add-header': true, 'socket-timeout': true, 'sleep-interval': true,
+      'ignore-errors': '=i', 'abort-on-error': false, 'download-sections': true, 'force-overwrites': false, 'no-mtime': false, 'write-info-json': false, 'write-description': false, 'list-subs': false,
+      'list-thumbnails': false, 'get-filename': false, 'no-cache-dir': false, 'cache-dir': true, proxy: true, 'geo-bypass': false, 'match-filters': true, 'match-filter': true, 'download-archive': true,
+      'js-runtimes': true, 'remote-components': true, 'format-sort': '=S', 'no-color': false, 'max-downloads': true, 'min-filesize': true, 'max-filesize': true, 'date': true, 'dateafter': true, 'datebefore': true,
+      'exec': true, 'update': '=U', 'external-downloader': true, 'downloader': true, 'postprocessor-args': true, 'ppa': true, 'ffmpeg-location': true, 'split-chapters': false, 'trim-filenames': true, 'windows-filenames': false,
+    },
+  },
+  operands: 'url*', stdin: false,
+  flags: { a: 'read', cookies: 'read', 'download-archive': 'append', 'print-to-file': 'append', P: 'write:dir' },
+  extra: (r, { inv, h, p }) => {
+    const effects = [...r.effects]
+    const noDownload = ['F', 'j', 'J', 's', 'g', 'e', 'skip-download', 'list-subs', 'list-thumbnails', 'get-filename', 'version', 'help', 'print'].some((k) => p.flags.has(k)) && !p.flags.has('no-simulate')
+    if (p.flags.has('version') || p.flags.has('help')) return { effects: [], readsStdin: false }
+    if (!noDownload) {
+      const o = p.flags.get('o')
+      const P = p.flags.get('P')
+      const base = P && P !== true ? h.resolve(P) : inv.cwd
+      // the output template (and the merged/temporary files next to it); a template may add directories
+      const out = o && o !== true && !isDash(o) ? (knownPrefix(o).startsWith('/') ? o : concat(base, known('/'), o)) : concat(base, known('/'), hole('filename', 'video title'))
+      if (!(o && o !== true && isDash(o))) effects.push({ kind: 'write', path: out })
+    }
+    const cookies = p.flags.get('cookies')
+    if (cookies && cookies !== true) effects.push({ kind: 'write', path: h.resolve(cookies), maybe: true })
+    // the browser's profile (cookie store)
+    if (p.flags.has('cookies-from-browser')) effects.push({ kind: 'read', path: concat(h.home() ?? known('~'), known(process.platform === 'darwin' ? '/Library' : '/.config')), recursive: true, maybe: true })
+    if (!p.flags.has('no-cache-dir')) effects.push({ kind: 'write', path: concat(h.home() ?? known('~'), known('/.cache/yt-dlp')), recursive: true, maybe: true })
+    // --exec runs commands; --update replaces the program; external downloaders run other programs
+    const complete = r.complete !== false && !['exec', 'U', 'external-downloader', 'downloader', 'postprocessor-args', 'ppa'].some((k) => p.flags.has(k))
+    // URLs from a batch file (or none given): still network
+    if (!effects.some((e) => e.kind === 'network')) effects.unshift({ kind: 'network', detail: inv.name })
+    return { ...r, effects, complete, readsStdin: p.flags.has('a') && isDash(p.flags.get('a') as AValue) }
+  },
+})
+
+// ---------------------------------------------------------------------------
+// PDF tools (poppler), ImageMagick identify
+// ---------------------------------------------------------------------------
+
+const POPPLER_SHORT = { short: 'qvh', shortWithArg: 'flrxyWH' }
+const POPPLER_LONG = { opw: true, upw: true, q: false, v: false, h: false, help: false, enc: true, f: true, l: true, r: true, x: true, y: true, W: true, H: true, cropbox: false, nodiag: false }
+
+const pdftools: Behavior[] = [
+  define({
+    names: ['pdftotext'], summary: 'PDF to text (pdftotext in.pdf [out.txt|-])',
+    spec: { ...POPPLER_SHORT, longSingle: true, long: { ...POPPLER_LONG, layout: false, fixed: true, raw: false, htmlmeta: false, bbox: false, 'bbox-layout': false, tsv: false, eol: true, nopgbrk: false, colspacing: true } },
+    operands: 'read write?', stdin: false,
+    extra: (r, { h, operands }) => {
+      const [input, output] = operands
+      if (output && isDash(output)) return { ...r, effects: r.effects.filter((e) => e.kind !== 'write') }
+      if (input && !output && !isDash(input)) return { ...r, effects: [...r.effects, { kind: 'write', path: sibling(h.resolve(input), '.txt') }] }
+      return r
+    },
+  }),
+  define({
+    names: ['pdfinfo', 'pdffonts', 'pdfsig', 'pdfdetach'], summary: 'inspect PDFs',
+    spec: { ...POPPLER_SHORT, longSingle: true, long: { ...POPPLER_LONG, box: false, meta: false, js: false, struct: false, 'struct-text': false, rawdates: false, isodates: false, dests: false, url: false, listenc: false, subst: false, list: false, nodump: false } },
+    operands: 'read*', stdin: false,
+    when: { saveall: { opaque: 'pdfdetach writes attachments' }, save: { opaque: 'pdfdetach writes attachments' } },
+  }),
+  define({
+    names: ['pdftoppm', 'pdftocairo', 'pdfimages'], summary: 'render PDF pages to images (… in.pdf ROOT)',
+    spec: { ...POPPLER_SHORT, longSingle: true, long: { ...POPPLER_LONG, png: false, jpeg: false, tiff: false, ppm: false, pdf: false, ps: false, eps: false, svg: false, j: false, all: false, list: false, p: false, print: false, 'scale-to': true, 'scale-to-x': true, 'scale-to-y': true, singlefile: false, gray: false, mono: false, jpegopt: true, aa: true, aaVector: true, rx: true, ry: true, sep: true, forcenum: false, 'transp': false, 'hide-annotations': false, 'o': false, 'e': false, 'struct': false } },
+    operands: 'read arg?', stdin: false,
+    // pages are written as ROOT-N.ext (or ROOT.ext): a name starting with ROOT
+    extra: (r, { h, operands }) => {
+      const root = operands[1]
+      if (!root || isDash(root)) return r
+      const base = h.resolve(root)
+      return { ...r, effects: [...r.effects, { kind: 'write', path: { alts: base.alts.map((a) => [...a, hole('filename', 'page suffix').alts[0][0]]) } }] }
+    },
+  }),
+  define({ names: ['pdfunite'], summary: 'merge PDFs (pdfunite in... out)', spec: { short: 'vh', longSingle: true, long: { help: false } }, operands: 'read* write', stdin: false }),
+  define({ names: ['pdfseparate'], summary: 'split a PDF (pdfseparate in out-%d.pdf)', spec: { short: 'vh', shortWithArg: 'fl', longSingle: true }, operands: 'read write', stdin: false }),
+  define({
+    names: ['identify'], summary: 'describe images (ImageMagick)',
+    spec: { longSingle: true, long: { format: true, verbose: false, ping: false, quiet: false, 'regard-warnings': false, density: true, units: true, precision: true, define: true, moments: false, features: true, unique: false, size: true, depth: true, list: true, version: false, help: false, colorspace: true, channel: true, alpha: true, auto_orient: false, debug: true, limit: 2, monitor: false } },
+    operands: 'read*', stdin: false,
+    // `@list` reads file names from a file; coders like `msl:` run scripts
+    extra: (r, { operands }) => (operands.some((o) => /^@|^[a-z]{2,}:/i.test(knownPrefix(o)) || concrete(o) === undefined && knownPrefix(o) === '') ? { ...r, complete: false } : r),
+  }),
+]
+
+// ---------------------------------------------------------------------------
+// crypto and keys
+// ---------------------------------------------------------------------------
+
+/** openssl SUBCOMMAND with single-dash options: -in/-key/… read, -out/-keyout write. */
+const OPENSSL_READ = new Set(['-in', '-key', '-inkey', '-CAfile', '-CA', '-CAkey', '-cert', '-certfile', '-config', '-signature', '-extfile', '-paramfile', '-kfile', '-verify', '-prverify', '-peerkey', '-sigfile', '-untrusted', '-chain', '-CRLfile', '-passin', '-dcert', '-dkey', '-reqin', '-signkey', '-CAserial', '-rand'])
+const OPENSSL_WRITE = new Set(['-out', '-keyout', '-sessout', '-msgfile', '-signer', '-pubout_file'])
+const OPENSSL_READONLY = new Set(['version', 'rand', 'x509', 'dgst', 'md5', 'sha1', 'sha256', 'sha384', 'sha512', 'base64', 'enc', 'req', 'rsa', 'ec', 'pkey', 'pkeyutl', 'verify', 'asn1parse', 'crl', 'pkcs7', 'pkcs12', 'cms', 'smime', 'genrsa', 'genpkey', 'ecparam', 'dhparam', 'prime', 'passwd', 'list', 'help', 'speed', 'errstr', 'ciphers', 'kdf', 'mac', 'storeutl', 'nseq', 'spkac', 'ts', 'rsautl', 'gendsa', 'dsa', 'dsaparam', 'crl2pkcs7', 'sess_id', 'info'])
+
+const openssl: Behavior = {
+  names: ['openssl'],
+  summary: 'cryptography toolkit',
+  analyze(inv, h) {
+    const a = args(inv)
+    const sub = concrete(a[0] ?? known('')) ?? ''
+    if (a[0]) h.role(a[0], 'subcommand')
+    const effects: Effect[] = []
+    if (sub === 's_client' || sub === 's_time' || sub === 'ocsp') {
+      return { effects: [{ kind: 'network', detail: `openssl ${sub}`, target: a.slice(1).find((_, k) => concrete(a[k]) === '-connect') }], readsStdin: true, complete: true }
+    }
+    if (!OPENSSL_READONLY.has(sub)) return { effects: [{ kind: 'unknown', detail: `openssl ${sub || '(interactive)'}` }], readsStdin: 'maybe', complete: false }
+    let complete = true
+    let readsIn = false
+    let explicitIn = false
+    const operands: AValue[] = []
+    for (let i = 1; i < a.length; i++) {
+      const s = concrete(a[i])
+      if (s === undefined) {
+        complete = false
+        continue
+      }
+      if (!s.startsWith('-') || s === '-') {
+        operands.push(a[i])
+        continue
+      }
+      const v = a[i + 1]
+      if (OPENSSL_READ.has(s) && v) {
+        i++
+        if (s === '-in') explicitIn = true
+        const t = concrete(v)
+        if (s === '-passin') {
+          if (t?.startsWith('file:')) effects.push({ kind: 'read', path: h.resolve(known(t.slice(5))) })
+          continue
+        }
+        if (t === '-' || t === 'stdin') readsIn = true
+        else effects.push({ kind: 'read', path: h.resolve(v) })
+      } else if (OPENSSL_WRITE.has(s) && v) {
+        i++
+        if (!isDash(v)) effects.push({ kind: 'write', path: h.resolve(v) })
+      } else if (s === '-engine' || s === '-provider-path' || s === '-provider') {
+        // loads code
+        complete = false
+        i++
+      } else if (s === '-sign' || s === '-hmac' || s === '-mac' || s === '-pass' || s === '-passout' || s === '-subj' || s === '-days' || s === '-newkey' || s === '-name' || s === '-digest' || s === '-cipher' || s === '-pkeyopt' || s === '-sigopt' || s === '-nameopt' || s === '-certopt' || s === '-set_serial' || s === '-addext' || s === '-extensions' || s === '-section' || s === '-K' || s === '-iv' || s === '-S' || s === '-md' || s === '-iter' || s === '-inform' || s === '-outform' || s === '-keyform' || s === '-certform' || s === '-algorithm' || s === '-macopt' || s === '-kdfopt' || s === '-keylen' || s === '-bits' || s === '-group' || s === '-servername' || s === '-connect') {
+        if (s === '-sign' && v) effects.push({ kind: 'read', path: h.resolve(v) })
+        if (s === '-passout' && concrete(v ?? known(''))?.startsWith('file:')) effects.push({ kind: 'write', path: h.resolve(known(concrete(v!)!.slice(5))) })
+        i++
+      }
+    }
+    // dgst/sha*/x509 … take files as operands; rand/prime take numbers
+    const fileOps = ['dgst', 'md5', 'sha1', 'sha256', 'sha384', 'sha512', 'asn1parse'].includes(sub)
+    if (fileOps) for (const o of operands) if (!isDash(o)) effects.push({ kind: 'read', path: h.resolve(o) })
+    const usesStdin = !explicitIn && !['version', 'rand', 'help', 'list', 'genrsa', 'genpkey', 'ecparam', 'prime', 'speed', 'errstr', 'ciphers', 'kdf', 'passwd', 'dhparam', 'gendsa', 'dsaparam'].includes(sub) && !(fileOps && operands.length > 0)
+    return { effects, readsStdin: readsIn || usesStdin, complete }
+  },
+}
+
+const sshKeygen: Behavior = {
+  names: ['ssh-keygen'],
+  summary: 'create and inspect SSH keys',
+  analyze(inv, h) {
+    const p = h.parseArgs(args(inv), { short: 'ABcDeEHiklLmMpqQrRuUvyYgK', shortWithArg: 'abCEfFgIJjmNnOPrRstVwYzZDTGSM' })
+    const effects: Effect[] = []
+    const home = h.home() ?? known('~')
+    const f = p.flags.get('f')
+    const file = f && f !== true ? h.resolve(f) : undefined
+    const knownHosts = file ?? concat(home, known('/.ssh/known_hosts'))
+    const query = ['l', 'y', 'B', 'e', 'i', 'D', 'k', 'Q', 'L'].some((k) => p.flags.has(k))
+    let complete = p.unknownFlags.length === 0
+    if (p.flags.has('R') || p.flags.has('H')) effects.push({ kind: 'write', path: knownHosts })
+    else if (p.flags.has('F')) effects.push({ kind: 'read', path: knownHosts })
+    else if (p.flags.has('Y')) {
+      const mode = concrete(p.flags.get('Y') as AValue) ?? ''
+      if (file) effects.push({ kind: 'read', path: file })
+      for (const o of p.operands) {
+        effects.push({ kind: 'read', path: h.resolve(o) })
+        if (mode === 'sign') effects.push({ kind: 'write', path: concat(h.resolve(o), known('.sig')) })
+      }
+      if (mode !== 'sign' && mode !== 'verify' && mode !== 'check-novalidate' && mode !== 'find-principals') complete = false
+    } else if (query || p.flags.has('p') || p.flags.has('c')) {
+      if (file) effects.push({ kind: (p.flags.has('p') || p.flags.has('c')) ? 'write' : 'read', path: file })
+      else complete = false // prompts for the file
+    } else {
+      // key generation: FILE and FILE.pub (default ~/.ssh/id_TYPE, asked interactively)
+      if (file) effects.push({ kind: 'write', path: file }, { kind: 'write', path: concat(file, known('.pub')) })
+      else {
+        effects.push({ kind: 'write', path: concat(home, known('/.ssh/'), hole('filename', 'key name')) })
+        complete = false
+      }
+    }
+    return { effects, readsStdin: !p.flags.has('N') || !file ? 'maybe' : false, complete }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// developer tools that do not run project code
+// ---------------------------------------------------------------------------
+
+/** tsc: reads the project; emits only without --noEmit (outDir comes from tsconfig: not known). */
+const TSC_VALUE = new Set(['-p', '--project', '--module', '-m', '--moduleResolution', '--target', '-t', '--lib', '--jsx', '--types', '--typeRoots', '--outDir', '--rootDir', '--rootDirs', '--baseUrl', '--declarationDir', '--outFile', '--tsBuildInfoFile', '--generateTrace', '--locale', '--maxNodeModuleJsDepth', '--ignoreDeprecations', '--moduleDetection', '--newLine', '--paths', '--customConditions', '--watchFile', '--watchDirectory', '--fallbackPolling', '--excludeDirectories', '--excludeFiles', '--jsxFactory', '--jsxFragmentFactory', '--jsxImportSource', '--importsNotUsedAsValues', '--moduleSuffixes', '--plugins', '--extendedDiagnostics', '--generateCpuProfile', '--explainFiles', '--listEmittedFiles', '--diagnostics'])
+const tsc: Behavior = {
+  names: ['tsc'],
+  summary: 'TypeScript compiler',
+  analyze(inv, h) {
+    const a = args(inv)
+    const s = a.map((x) => concrete(x))
+    if (s.length === 1 && ['-v', '--version', '-h', '--help', '--all'].includes(s[0] ?? '')) return { effects: [], readsStdin: false }
+    let dir: AValue = inv.cwd
+    const effects: Effect[] = []
+    const files: AValue[] = []
+    let noEmit = false
+    let complete = true
+    for (let i = 0; i < a.length; i++) {
+      const t = s[i]
+      if (t === undefined) {
+        complete = false
+        continue
+      }
+      if (t === '--noEmit' && s[i + 1] !== 'false') noEmit = true
+      if (TSC_VALUE.has(t) && a[i + 1]) {
+        const v = a[++i]
+        if (t === '-p' || t === '--project') dir = h.resolve(v)
+        else if (t === '--generateTrace' || t === '--tsBuildInfoFile' || t === '--generateCpuProfile') effects.push({ kind: 'write', path: h.resolve(v), recursive: t === '--generateTrace' })
+        else if (t === '--outDir' || t === '--declarationDir' || t === '--outFile') effects.push({ kind: 'write', path: h.resolve(v), recursive: t !== '--outFile', maybe: true })
+        continue
+      }
+      if (t.startsWith('-')) {
+        if (s[i + 1] === 'true' || s[i + 1] === 'false') i++
+        continue
+      }
+      files.push(a[i])
+    }
+    for (const f of files) effects.push({ kind: 'read', path: h.resolve(f) })
+    effects.unshift({ kind: 'read', path: dir, recursive: true })
+    if (!noEmit) {
+      // emits next to the sources or into tsconfig's outDir
+      effects.push({ kind: 'write', path: dir, recursive: true, maybe: true })
+      complete = false
+    }
+    return { effects, readsStdin: false, complete }
+  },
+}
+
+/** Linters and formatters: read their operands (or the cwd); fix/write flags rewrite them. */
+const LINT: Def = {
+  anyFlags: true, operands: 'read*', cwdIfNone: true, recursive: true, stdin: false,
+  spec: { long: { fix: false, write: false, unsafe: false, 'unsafe-fixes': false, 'fix-only': false, 'fix-dangerously': false, apply: false, 'apply-unsafe': false, diff: false, check: false, config: true, 'config-path': true, format: true, 'output-format': true, select: true, ignore: true, 'extend-select': true, 'target-version': true, 'line-length': true, 'max-diagnostics': true, reporter: true, severity: true, shell: true, exclude: true, include: true } },
+  flags: { config: 'read', 'config-path': 'read' },
+  when: { 'fix|write|unsafe|unsafe-fixes|fix-only|fix-dangerously|apply|apply-unsafe': { operands: 'write*' } },
+}
+const lintTools = [
+  define({ names: ['oxlint', 'shellcheck', 'markdownlint', 'markdownlint-cli2', 'actionlint', 'hadolint', 'yamllint', 'eslint_d'], summary: 'linters (read files; --fix rewrites them)', ...LINT }),
+  define({
+    names: ['ruff', 'biome', 'taplo'], summary: 'linters / formatters', spec: { long: { version: false, help: false } },
+    subcommands: {
+      'check|lint|ci': LINT,
+      // `ruff format` and `taplo fmt` rewrite files unless --check/--diff; `biome format` only with --write
+      'format|fmt': { ...LINT, extra: (r, { inv, p }) => (inv.name !== 'biome' && !p.flags.has('check') && !p.flags.has('diff') ? { ...r, effects: r.effects.map((e) => (e.kind === 'read' ? { kind: 'write', path: e.path, recursive: true } : e)) } : r) },
+      'version|help|rule|explain|rage|config|linter|analyze': QUERY,
+      '*': opaque('linter subcommand'),
+    },
+  }),
+]
+
+// ---------------------------------------------------------------------------
+// local daemons and services
+// ---------------------------------------------------------------------------
+
+const lms = define({
+  names: ['lms'], summary: 'LM Studio CLI', spec: { short: 'h', long: { help: false, version: false } },
+  subcommands: {
+    'ps|ls|status|version|help|log': QUERY,
+    'load|unload|server': { ...QUERY, effects: [{ kind: 'process', detail: 'LM Studio server state' }] },
+    get: { ...QUERY, effects: [{ kind: 'network', detail: 'lms get' }, { kind: 'write', path: '~/.lmstudio', recursive: true, maybe: true }] },
+    '*': opaque('lms'),
+  },
+})
+
+const tailscale = define({
+  names: ['tailscale'], summary: 'Tailscale CLI', spec: { long: { socket: true, help: false, version: false } },
+  subcommands: {
+    'status|ip|version|whoami|dns|exit-node|metrics|licenses|bugreport|help|completion': QUERY,
+    'ping|netcheck|nc': { ...QUERY, effects: [{ kind: 'network', detail: 'tailscale' }] },
+    'switch': { ...QUERY, when: { list: QUERY }, opaque: 'tailscale switch changes the account' },
+    'serve|funnel': { ...opaque('tailscale serve changes the node configuration'), when: { json: QUERY } },
+    '*': opaque('tailscale changes the node configuration'),
+  },
+})
+
+const netlify = define({
+  names: ['netlify', 'ntl'], summary: 'Netlify CLI', spec: { long: { version: false, help: false, debug: false, auth: true } },
+  subcommands: {
+    'status|sites:list|sites:create|api|env:list|env:get|open:admin|watch|logs|logs:function|functions:list|teams:list|help|status:hooks|unlink|switch': { ...QUERY, effects: [{ kind: 'network', detail: 'netlify' }] },
+    // builds run project code unless --no-build
+    deploy: { anyFlags: true, operands: 'arg*', stdin: false, spec: { long: { dir: true, functions: true, 'no-build': false, prod: false, site: true, message: true, alias: true, json: false } }, flags: { dir: 'read:dir', functions: 'read:dir' }, effects: [{ kind: 'network', detail: 'netlify deploy' }, { kind: 'write', path: '.netlify', recursive: true, maybe: true }], recursive: true, opaque: 'netlify deploy may run the build', when: { 'no-build': { opaque: undefined } } },
+    '*': opaque('netlify runs project scripts or changes the site'),
+  },
+})
+
+const hf = define({
+  names: ['hf', 'huggingface-cli'], summary: 'Hugging Face CLI', spec: { long: { help: false, version: false, token: true } },
+  subcommands: {
+    'whoami|env|version|help': { ...QUERY, effects: [{ kind: 'network', detail: 'hf', maybe: true }] },
+    download: { ...QUERY, spec: { long: { 'local-dir': true, 'cache-dir': true } }, flags: { 'local-dir': 'write:dir', 'cache-dir': 'write:dir' }, effects: [{ kind: 'network', detail: 'hf download' }, { kind: 'write', path: '~/.cache/huggingface', recursive: true, maybe: true }] },
+    upload: { anyFlags: true, operands: 'arg read*', stdin: false, recursive: true, effects: [{ kind: 'network', detail: 'hf upload' }] },
+    '*': opaque('hf'),
+  },
+})
+
+export const toolBehaviors: Behavior[] = [
+  sqlite3, typst, ffmpeg, ytdlp, ...pdftools, openssl, sshKeygen, tsc, ...lintTools, lms, tailscale, netlify, hf,
+]
+