@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/behaviors/defs/devtools.ts

@@ -0,0 +1,400 @@
+/**
+ * Behavior definitions for developer tools: git, package managers,
+ * interpreters and build tools. Interpreters and build tools run arbitrary
+ * code, so they report `unknown` effects (and `complete: false`) — the OS
+ * sandbox stays responsible for confining them.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+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 { Behavior, BehaviorHelpers, BehaviorResult, Invocation } from '../types.ts'
+
+const args = (inv: Invocation): AValue[] => inv.argv.slice(1)
+
+/** Find the directory containing `marker` at or above `dir` (only for concrete paths). */
+function findUp(dir: string, marker: string): string | undefined {
+  let cur = dir
+  for (;;) {
+    if (fs.existsSync(path.join(cur, marker))) return cur
+    const parent = path.dirname(cur)
+    if (parent === cur) return undefined
+    cur = parent
+  }
+}
+
+const GIT_READ = new Set([
+  'status', 'log', 'diff', 'show', 'rev-parse', 'ls-files', 'ls-tree', 'blame', 'grep', 'describe', 'shortlog', 'reflog',
+  'cat-file', 'symbolic-ref', 'for-each-ref', 'merge-base', 'name-rev', 'rev-list', 'help', 'version', 'check-ignore',
+  'whatchanged', 'count-objects', 'show-ref', 'var', 'verify-commit', 'difftool', 'range-diff', 'annotate', 'cherry',
+  'diff-tree', 'diff-index', 'diff-files', 'fsck', 'show-branch', 'check-attr', 'check-ref-format', 'check-mailmap', 'verify-pack',
+  'verify-tag', 'patch-id', 'get-tar-commit-id', 'column', 'fmt-merge-msg', 'stripspace', 'interpret-trailers', 'show-index',
+])
+const GIT_WRITE = new Set([
+  'add', 'commit', 'checkout', 'switch', 'restore', 'reset', 'rm', 'mv', 'merge', 'rebase', 'cherry-pick', 'revert', 'stash',
+  'init', 'apply', 'am', 'gc', 'update-index', 'notes', 'clean', 'worktree', 'prune', 'repack', 'update-ref', 'mergetool',
+  'bisect', 'sparse-checkout', 'format-patch', 'commit-tree', 'read-tree', 'write-tree', 'hash-object', 'replace', 'restore',
+  'maintenance', 'lfs',
+])
+const GIT_NETWORK = new Set(['fetch', 'pull', 'push', 'ls-remote', 'clone', 'submodule', 'remote'])
+
+const GIT_NESTED = new Set(['stash', 'remote', 'worktree', 'submodule', 'bisect', 'notes', 'lfs', 'sparse-checkout', 'maintenance', 'reflog'])
+
+/** Subcommands that read stdin (patches, object lists, messages): never cut off from it. */
+const GIT_STDIN = new Set(['apply', 'am', 'hash-object', 'patch-id', 'stripspace', 'interpret-trailers', 'fmt-merge-msg', 'mktree', 'mailinfo', 'mailsplit', 'fast-import', 'pack-objects', 'unpack-objects', 'index-pack', 'credential', 'cat-file', 'update-index'])
+
+function gitBehavior(): Behavior {
+  return {
+    names: ['git'],
+    summary: 'version control',
+    analyze(inv, h) {
+      const r = analyzeGit(inv, h)
+      if (r.readsStdin === false) {
+        const a = args(inv).map((x) => concrete(x))
+        const sub = a.find((x) => x !== undefined && !x.startsWith('-'))
+        if ((sub && GIT_STDIN.has(sub)) || a.includes('--stdin') || a.includes('-') || a.includes('--batch') || a.includes('--batch-check')) return { ...r, readsStdin: 'maybe' }
+      }
+      return r
+    },
+  }
+}
+
+function analyzeGit(inv: Invocation, h: BehaviorHelpers): BehaviorResult {
+  {
+    {
+      const a = args(inv)
+      let cwd = inv.cwd
+      let i = 0
+      for (; i < a.length; i++) {
+        const s = concrete(a[i])
+        if (s === undefined) return { effects: [{ kind: 'unknown', detail: 'git with unknown arguments' }], complete: false, readsStdin: false }
+        if (s === '-C') {
+          const d = a[++i]
+          if (d) cwd = h.resolve(d)
+          continue
+        }
+        if (s === '-c' || s === '--git-dir' || s === '--work-tree' || s === '--namespace') {
+          i++
+          continue
+        }
+        if (s.startsWith('-')) continue
+        break
+      }
+      const sub = concrete(a[i] ?? known('')) ?? ''
+      if (a[i]) h.role(a[i], 'subcommand')
+      // second-level subcommands: `git stash pop`, `git remote add`, `git worktree list`
+      if (GIT_NESTED.has(sub)) {
+        const next = a.slice(i + 1).find((x) => !knownPrefix(x).startsWith('-'))
+        if (next && /^[a-z][a-z-]*$/.test(concrete(next) ?? '')) h.role(next, 'subcommand')
+      }
+      const rest = a.slice(i + 1)
+      const cwdStr = concrete(cwd)
+      const root = cwdStr ? findUp(cwdStr, '.git') : undefined
+      const repo: AValue = root ? known(root) : cwdStr ? hole('path', 'git repository root') : hole('path', 'git repository root')
+      const effects: Effect[] = []
+      const restOps = rest.filter((r) => !knownPrefix(r).startsWith('-'))
+      const hasFlag = (...f: string[]): boolean => rest.some((r) => f.includes(concrete(r) ?? ''))
+      if (sub === '' || sub === '--version' || sub === 'version' || sub === 'help') return { effects: [], readsStdin: false }
+      if (sub === 'config') {
+        const write = !hasFlag('--get', '--get-all', '--list', '-l', '--get-regexp', '--show-origin') && restOps.length >= 2
+        if (hasFlag('--global')) effects.push({ kind: write ? 'write' : 'read', path: { alts: [[...(h.home()?.alts[0] ?? ['~']), '/.gitconfig']] } })
+        else effects.push({ kind: write ? 'write' : 'read', path: { alts: [[...repo.alts[0], '/.git/config']] } })
+        return { effects, readsStdin: false }
+      }
+      if (sub === 'branch' || sub === 'tag') {
+        const write = hasFlag('-d', '-D', '-m', '-M', '-c', '-C', '-a', '-s', '-f', '--delete', '--move', '--copy', '--set-upstream-to', '-u') || (restOps.length > 0 && !hasFlag('--list', '-l', '--contains', '--merged', '--no-merged', '--points-at'))
+        effects.push({ kind: write ? 'write' : 'read', path: repo, recursive: true })
+        return { effects, readsStdin: false }
+      }
+      if (sub === 'stash' && (restOps.length === 0 ? false : ['list', 'show'].includes(concrete(restOps[0]) ?? ''))) {
+        return { effects: [{ kind: 'read', path: repo, recursive: true }], readsStdin: false }
+      }
+      if (sub === 'remote' && !['add', 'remove', 'rm', 'rename', 'set-url', 'set-head', 'prune', 'update'].includes(concrete(restOps[0] ?? known('')) ?? '')) {
+        return { effects: [{ kind: 'read', path: repo, recursive: true }], readsStdin: false }
+      }
+      if (sub === 'merge-tree') {
+        // --write-tree (the default in modern git) stores the merged trees as objects
+        effects.push({ kind: 'read', path: repo, recursive: true })
+        if (!hasFlag('--trivial-merge')) effects.push({ kind: 'write', path: { alts: [[...repo.alts[0], '/.git']] }, recursive: true, maybe: true })
+        return { effects, readsStdin: hasFlag('--stdin') }
+      }
+      if (sub === 'archive' || sub === 'bundle') {
+        effects.push({ kind: 'read', path: repo, recursive: true })
+        if (sub === 'archive') {
+          if (hasFlag('--remote') || rest.some((r) => knownPrefix(r).startsWith('--remote='))) effects.push({ kind: 'network', detail: 'git archive --remote' })
+          for (let j = 0; j < rest.length; j++) {
+            const s = concrete(rest[j]) ?? ''
+            if ((s === '-o' || s === '--output') && rest[j + 1]) effects.push({ kind: 'write', path: h.resolve(rest[j + 1]) })
+            else if (s.startsWith('--output=')) effects.push({ kind: 'write', path: h.resolve(known(s.slice('--output='.length))) })
+          }
+          return { effects, readsStdin: false }
+        }
+        const verb = concrete(restOps[0] ?? known('')) ?? ''
+        const file = restOps[1]
+        if (verb === 'create' && file && concrete(file) !== '-') effects.push({ kind: 'write', path: h.resolve(file) })
+        else if ((verb === 'verify' || verb === 'list-heads') && file) effects.push({ kind: 'read', path: h.resolve(file) })
+        else if (verb === 'unbundle') effects.push({ kind: 'write', path: repo, recursive: true })
+        else if (verb !== 'create') return { effects: [...effects, { kind: 'unknown', detail: `git bundle ${verb}` }], readsStdin: 'maybe', complete: false }
+        return { effects, readsStdin: verb === 'unbundle' }
+      }
+      if (sub === 'filter-branch' || sub === 'credential' || sub === 'filter-repo') {
+        // filters and credential helpers are shell commands
+        return { effects: [{ kind: 'write', path: repo, recursive: true }, { kind: 'unknown', detail: `git ${sub} runs commands` }], readsStdin: 'maybe', complete: false }
+      }
+      if (GIT_READ.has(sub)) {
+        effects.push({ kind: 'read', path: repo, recursive: true })
+        return { effects, readsStdin: false, stdout: sub === 'rev-parse' && hasFlag('--show-toplevel') ? { type: 'path', value: root ? known(root) : undefined } : undefined }
+      }
+      if (sub === 'clone') {
+        const cp = h.parseArgs(rest, {
+          short: 'lsqvn', shortWithArg: 'bojcu',
+          long: { depth: true, branch: '=b', origin: '=o', config: '=c', reference: true, 'reference-if-able': true, 'separate-git-dir': true, 'upload-pack': '=u', template: true, filter: true, jobs: '=j', 'shallow-since': true, 'shallow-exclude': true, 'bundle-uri': true, 'server-option': true, 'ref-format': true, recursive: false, 'recurse-submodules': true, 'single-branch': false, 'no-single-branch': false, 'no-tags': false, 'shallow-submodules': false, bare: false, mirror: false, quiet: false, verbose: false, progress: false, 'no-checkout': false, local: false, shared: false, dissociate: false, sparse: false, 'also-filter-submodules': false, 'remote-submodules': false, 'no-hardlinks': false, 'no-reject-shallow': false, 'reject-shallow': false },
+        })
+        const [url, dir] = cp.operands
+        const dest = dir ? h.resolve(dir) : { alts: cwd.alts.map((c) => [...c, '/', hole('filename', 'repository name').alts[0][0]]) }
+        if (url) effects.push({ kind: 'network', target: url, detail: 'git clone' })
+        effects.push({ kind: 'write', path: dest, recursive: true })
+        const sep = cp.flags.get('separate-git-dir')
+        if (sep && sep !== true) effects.push({ kind: 'write', path: h.resolve(sep), recursive: true })
+        // --upload-pack runs a command
+        return { effects, readsStdin: false, complete: cp.unknownFlags.length === 0 && !cp.flags.has('u') }
+      }
+      if (sub === 'init') {
+        effects.push({ kind: 'write', path: restOps[0] ? h.resolve(restOps[0]) : cwd, recursive: true })
+        return { effects, readsStdin: false }
+      }
+      if (GIT_NETWORK.has(sub)) {
+        effects.push({ kind: 'network', detail: `git ${sub}` })
+        if (sub !== 'push' && sub !== 'ls-remote') effects.push({ kind: 'write', path: repo, recursive: true })
+        else effects.push({ kind: 'read', path: repo, recursive: true })
+        if (sub === 'push') effects.push({ kind: 'write', path: { alts: [[...repo.alts[0], '/.git']] }, recursive: true })
+        return { effects, readsStdin: false }
+      }
+      if (GIT_WRITE.has(sub)) {
+        effects.push({ kind: 'write', path: repo, recursive: true })
+        if (sub === 'clean' && (hasFlag('-f', '-ff', '-fd', '-fdx', '-df', '-xdf', '--force'))) effects.push({ kind: 'delete', path: cwd, recursive: true })
+        // `--fixup=<commit>` needs no message (`--fixup=amend:`/`reword:` open an editor)
+        const fixup = rest.some((r) => /^--fixup=(?!amend:|reword:)./.test(concrete(r) ?? ''))
+        if (sub === 'commit' && !fixup && !hasFlag('-m', '-F', '--message', '--file', '-C', '--no-edit') && !rest.some((r) => /^-[a-zA-Z]*m|^--(message|file|reuse-message)=/.test(knownPrefix(r)))) {
+          effects.push({ kind: 'unknown', detail: 'git commit may open an editor' })
+          return { effects, readsStdin: false, complete: false }
+        }
+        return { effects, readsStdin: false }
+      }
+      return { effects: [{ kind: 'read', path: repo, recursive: true }, { kind: 'unknown', detail: `git ${sub}` }], complete: false, readsStdin: 'maybe' }
+    }
+  }
+}
+
+const PM_INSTALL = new Set(['install', 'i', 'ci', 'add', 'remove', 'rm', 'uninstall', 'un', 'update', 'up', 'upgrade', 'link', 'unlink', 'prune', 'dedupe', 'rebuild', 'import'])
+const PM_READ = new Set(['ls', 'list', 'view', 'info', 'show', 'outdated', 'why', 'explain', 'audit', 'search', 'config', 'get', 'root', 'bin', 'prefix', 'whoami', 'help', '-v', '--version', 'version', '-h', '--help', 'doctor', 'licenses'])
+
+function packageManager(): Behavior {
+  return {
+    names: ['npm', 'pnpm', 'yarn', 'bun', 'npx', 'pnpx', 'bunx', 'uvx'],
+    summary: 'JavaScript package managers',
+    analyze(inv, h) {
+      const a = args(inv)
+      if (inv.name === 'npx' || inv.name === 'pnpx' || inv.name === 'bunx' || inv.name === 'uvx') {
+        // npx [-y] [-p pkg] <binary> args…: the binary is analyzed like any command
+        let j = 0
+        for (; j < a.length; j++) {
+          const s = concrete(a[j])
+          if (s === undefined || !s.startsWith('-')) break
+          if (['-p', '--package', '--from', '--with', '--python', '--with-requirements', '--index-url', '--index'].includes(s)) j++
+        }
+        const net: Effect = { kind: 'network', detail: `${inv.name} may download packages` }
+        if (j >= a.length || concrete(a[j]) === undefined) return { effects: [net, { kind: 'unknown', detail: `${inv.name} runs package binaries` }], complete: false, readsStdin: 'maybe' }
+        const sub = h.subcommand(a.slice(j))
+        return { ...sub, effects: [net, ...sub.effects], complete: false }
+      }
+      let i = 0
+      let dir = inv.cwd
+      for (; i < a.length; i++) {
+        const s = concrete(a[i])
+        if (s === undefined) break
+        if (s === '-C' || s === '--dir' || s === '--prefix' || s === '--cwd') {
+          const d = a[++i]
+          if (d) dir = h.resolve(d)
+          continue
+        }
+        if (s === '--filter' || s === '-F' || s === '-w' || s === '--workspace') {
+          i++
+          continue
+        }
+        if (s.startsWith('-') && !PM_READ.has(s)) continue
+        break
+      }
+      const sub = concrete(a[i] ?? known('')) ?? (a[i] ? '?' : '')
+      if (a[i] && sub !== '?' && !sub.startsWith('-')) {
+        h.role(a[i], 'subcommand')
+        // `npm run build`, `pnpm exec tsc`: the script or binary is a subcommand too
+        if (['run', 'run-script', 'exec', 'x', 'dlx'].includes(sub) && a[i + 1] && !knownPrefix(a[i + 1]).startsWith('-')) h.role(a[i + 1], 'subcommand')
+      }
+      const global = a.some((x) => ['-g', '--global'].includes(concrete(x) ?? ''))
+      if (PM_READ.has(sub)) return { effects: [{ kind: 'read', path: dir, recursive: true, maybe: true }, ...(sub === 'view' || sub === 'info' || sub === 'outdated' || sub === 'audit' || sub === 'search' ? [{ kind: 'network', detail: `${inv.name} ${sub}` } as Effect] : [])], readsStdin: false }
+      if (PM_INSTALL.has(sub) || (sub === '' && inv.name !== 'npm')) {
+        const effects: Effect[] = [
+          { kind: 'network', detail: `${inv.name} ${sub || 'install'}` },
+          { kind: 'write', path: global ? hole('path', 'global package directory') : dir, recursive: true },
+          { kind: 'unknown', detail: 'install scripts may run arbitrary code' },
+        ]
+        return { effects, readsStdin: false, complete: false }
+      }
+      // run / exec / test / start / custom scripts
+      return { effects: [{ kind: 'read', path: dir, recursive: true, maybe: true }, { kind: 'unknown', detail: `${inv.name} ${sub} runs project scripts` }], readsStdin: 'maybe', complete: false }
+    },
+  }
+}
+
+function interpreter(names: string[], codeFlags: string[], argFlags: string[]): Behavior {
+  return {
+    names,
+    summary: 'language interpreter',
+    analyze(inv, h) {
+      const a = args(inv)
+      for (let i = 0; i < a.length; i++) {
+        const s = concrete(a[i])
+        if (s === undefined) break
+        if (s === '--version' || s === '-V' || s === '-version' || (s === '-v' && names.includes('node'))) return { effects: [], readsStdin: false }
+        if (codeFlags.includes(s)) {
+          if (a[i + 1]) h.role(a[i + 1], 'code')
+          return { effects: [{ kind: 'unknown', detail: `${inv.name} ${s} runs inline code` }], readsStdin: 'maybe', complete: false }
+        }
+        if (s === '-m' && names.includes('python3')) {
+          const mod = concrete(a[i + 1] ?? known('')) ?? ''
+          // `python3 -m pip install x`: the module and its first operand read as subcommands
+          if (a[i + 1]) h.role(a[i + 1], 'subcommand')
+          const op = a.slice(i + 2).find((x) => !knownPrefix(x).startsWith('-'))
+          if (op && mod === 'pip' && /^[a-z][a-z-]*$/.test(concrete(op) ?? '')) h.role(op, 'subcommand')
+          if (mod === 'pip') {
+            const sub = concrete(a[i + 2] ?? known('')) ?? ''
+            if (['install', 'uninstall', 'download', 'wheel'].includes(sub)) return { effects: [{ kind: 'network', detail: 'pip' }, { kind: 'write', path: hole('path', 'python site-packages') }, { kind: 'unknown', detail: 'package build scripts' }], complete: false, readsStdin: false }
+            return { effects: [{ kind: 'read', path: hole('path', 'python site-packages') }], readsStdin: false }
+          }
+          if (mod === 'venv') {
+            const d = a.slice(i + 2).find((x) => !knownPrefix(x).startsWith('-'))
+            return { effects: d ? [{ kind: 'write', path: h.resolve(d), recursive: true }] : [], readsStdin: false }
+          }
+          if (mod === 'json.tool') return { effects: a.slice(i + 2).filter((x) => !knownPrefix(x).startsWith('-')).map((f) => ({ kind: 'read' as const, path: h.resolve(f) })), readsStdin: true }
+          return { effects: [{ kind: 'unknown', detail: `python module ${mod}` }], readsStdin: 'maybe', complete: false }
+        }
+        if (argFlags.includes(s)) {
+          i++
+          continue
+        }
+        if (s.startsWith('-')) continue
+        if (s === '-') break
+        return { effects: [{ kind: 'read', path: h.resolve(a[i]) }, { kind: 'unknown', detail: `runs script ${s}` }], readsStdin: 'maybe', complete: false }
+      }
+      return { effects: [{ kind: 'unknown', detail: `${inv.name} reads a program from stdin` }], readsStdin: true, complete: false }
+    },
+  }
+}
+
+function buildTool(names: string[]): Behavior {
+  return {
+    names,
+    summary: 'build tool',
+    analyze(inv, h: BehaviorHelpers) {
+      const a = args(inv)
+      if (a.some((x) => ['--version', '-v', 'version', '--help'].includes(concrete(x) ?? '')) && a.length === 1) return { effects: [], readsStdin: false }
+      let dir = inv.cwd
+      for (let i = 0; i < a.length; i++) if (['-C', '--directory'].includes(concrete(a[i]) ?? '') && a[i + 1]) dir = h.resolve(a[i + 1])
+      return { effects: [{ kind: 'read', path: dir, recursive: true, maybe: true }, { kind: 'write', path: dir, recursive: true, maybe: true }, { kind: 'unknown', detail: `${inv.name} runs build recipes` }], readsStdin: false, complete: false }
+    },
+  }
+}
+
+function systemPackageManager(names: string[], roots: string[]): Behavior {
+  return {
+    names,
+    summary: 'system package manager',
+    analyze(inv) {
+      const sub = concrete(args(inv).find((x) => !knownPrefix(x).startsWith('-')) ?? known('')) ?? ''
+      if (['install', 'upgrade', 'remove', 'uninstall', 'reinstall', 'update', 'tap', 'link', 'unlink', 'cleanup', 'autoremove', 'purge'].includes(sub)) {
+        return { effects: [{ kind: 'network', detail: `${inv.name} ${sub}` }, ...roots.map((r): Effect => ({ kind: 'write', path: known(r), recursive: true }))], readsStdin: false }
+      }
+      return { effects: roots.map((r): Effect => ({ kind: 'read', path: known(r), recursive: true })), readsStdin: false }
+    },
+  }
+}
+
+/** Where CLIs keep their credentials (relative to HOME), and the subcommands that print them. */
+const CREDENTIAL_STORES: Record<string, { stores: string[]; secret: RegExp }> = {
+  gh: { stores: ['.config/gh'], secret: /^auth (token|status)/ },
+  glab: { stores: ['.config/glab-cli'], secret: /^(auth status|config get token)/ },
+  aws: { stores: ['.aws'], secret: /^(configure (get|list|export-credentials)|sts get-session-token|ecr get-login-password|ecr-public get-login-password|codeartifact get-authorization-token)/ },
+  gcloud: { stores: ['.config/gcloud'], secret: /^(auth (print-access-token|print-identity-token|application-default print-access-token)|config config-helper)/ },
+  az: { stores: ['.azure'], secret: /^account get-access-token/ },
+  kubectl: { stores: ['.kube'], secret: /^config view/ },
+  helm: { stores: ['.kube'], secret: /(?!)/ },
+  docker: { stores: ['.docker/config.json'], secret: /^(login|logout|credential)/ },
+  podman: { stores: ['.docker/config.json'], secret: /^(login|logout)/ },
+  heroku: { stores: ['.netrc'], secret: /^(auth:token|auth token)/ },
+  op: { stores: ['.config/op'], secret: /^(read|inject|item get|document get|run|signin|account get)/ },
+  doctl: { stores: ['.config/doctl'], secret: /^auth/ },
+  vault: { stores: ['.vault-token'], secret: /^(read|kv get|token lookup|print token|login)/ },
+  terraform: { stores: ['.terraform.d/credentials.tfrc.json'], secret: /^login/ },
+  tofu: { stores: ['.terraform.d/credentials.tfrc.json'], secret: /^login/ },
+}
+
+export const devtoolBehaviors: Behavior[] = [
+  gitBehavior(),
+  packageManager(),
+  interpreter(['python', 'python3', 'python2'], ['-c'], ['-W', '-X', '-Q']),
+  interpreter(['node', 'deno', 'tsx', 'ts-node'], ['-e', '--eval', '-p', '--print'], ['-r', '--require', '--import', '--loader']),
+  interpreter(['ruby'], ['-e'], ['-r', '-I']),
+  interpreter(['perl'], ['-e', '-E'], ['-I', '-M']),
+  interpreter(['php'], ['-r'], ['-d']),
+  interpreter(['java', 'kotlin', 'scala', 'groovy', 'jshell'], [], ['-cp', '-classpath', '--class-path', '-p', '--module-path', '-jar', '-D']),
+  interpreter(['lua', 'luajit', 'Rscript', 'julia'], ['-e', '--eval'], ['-l']),
+  buildTool(['make', 'gmake', 'cmake', 'ninja', 'cargo', 'go', 'mvn', 'gradle', 'gradlew', 'bazel', 'xcodebuild', 'swift', 'rustc', 'gcc', 'cc', 'clang', 'g++', 'clang++', 'tsc', 'vite', 'webpack', 'esbuild', 'vitest', 'jest', 'pytest', 'tox', 'swiftc', 'zig', 'ld', 'javac', 'kotlinc', 'svelte-check', 'svelte-kit', 'next', 'nuxt', 'astro', 'rollup', 'parcel', 'turbo', 'nx', 'playwright', 'mocha', 'ava', 'eslint', 'prettier', 'stylelint', 'xcodegen', 'tuist', 'bundle', 'rake', 'mix', 'dotnet', 'sbt', 'lein', 'stack', 'cabal', 'ghc', 'dune', 'nim', 'crystal', 'meson', 'scons', 'just', 'task']),
+  systemPackageManager(['brew'], ['/opt/homebrew', '/usr/local']),
+  systemPackageManager(['apt', 'apt-get', 'dpkg', 'yum', 'dnf', 'apk', 'pacman', 'zypper'], ['/usr', '/var/lib', '/etc']),
+  {
+    names: ['pip', 'pip3', 'uv', 'pipx', 'poetry', 'conda'],
+    summary: 'Python package managers',
+    analyze(inv, h) {
+      const sub = concrete(args(inv).find((x) => !knownPrefix(x).startsWith('-')) ?? known('')) ?? ''
+      if (['install', 'uninstall', 'add', 'remove', 'sync', 'lock', 'update', 'upgrade', 'download', 'venv', 'create'].includes(sub)) {
+        return { effects: [{ kind: 'network', detail: `${inv.name} ${sub}` }, { kind: 'write', path: inv.name === 'pip' || inv.name === 'pip3' ? hole('path', 'python site-packages') : inv.cwd, recursive: true }, { kind: 'unknown', detail: 'package build scripts' }], complete: false, readsStdin: false }
+      }
+      if (['run', 'exec', 'shell'].includes(sub)) return { effects: [{ kind: 'unknown', detail: `${inv.name} ${sub}` }], complete: false, readsStdin: 'maybe' }
+      return { effects: [{ kind: 'read', path: inv.cwd, recursive: true }], readsStdin: false }
+    },
+  },
+  {
+    names: ['docker', 'podman', 'container', 'docker-compose', 'kubectl', 'helm', 'terraform', 'tofu', 'pulumi', 'gcloud', 'aws', 'az', 'gh', 'glab', 'vercel', 'fly', 'flyctl', 'heroku', 'wrangler', 'firebase', 'supabase', 'stripe', 'op', 'doctl', 'vault'],
+    summary: 'cloud / container CLIs',
+    analyze(inv, h) {
+      const a = args(inv)
+      const sub = concrete(a.find((x) => !knownPrefix(x).startsWith('-')) ?? known('')) ?? ''
+      if (a.length === 1 && ['--version', '-v', 'version', 'help', '--help', '-h'].includes(concrete(a[0]) ?? '')) return { effects: [], readsStdin: false }
+      const effects: Effect[] = [{ kind: 'network', detail: `${inv.name} ${sub}` }]
+      // the credential store: read by (nearly) every call, definitely by the commands that print secrets
+      const cred = CREDENTIAL_STORES[inv.name]
+      if (cred) {
+        const words = a.map((x) => concrete(x) ?? '?').filter((w) => !w.startsWith('-')).join(' ')
+        const secret = cred.secret.test(words)
+        for (const store of cred.stores) {
+          const path = store.startsWith('/') ? known(store) : concat(h.home() ?? known('~'), known('/' + store))
+          effects.push({ kind: 'read', path, recursive: true, ...(secret ? {} : { maybe: true }) })
+        }
+      }
+      effects.push({ kind: 'unknown', detail: `${inv.name} ${sub} acts on remote or container state` })
+      return { effects, complete: false, readsStdin: 'maybe' }
+    },
+  },
+  {
+    names: ['open', 'xdg-open', 'osascript', 'say', 'pbcopy', 'pbpaste', 'systemctl', 'afplay', 'shortcuts', 'automator'],
+    summary: 'desktop / system integration',
+    analyze(inv) {
+      if (inv.name === 'pbpaste' || inv.name === 'say') return { effects: [], readsStdin: inv.name === 'say' }
+      if (inv.name === 'pbcopy') return { effects: [{ kind: 'process', detail: 'writes the clipboard' }], readsStdin: true }
+      return { effects: [{ kind: 'unknown', detail: `${inv.name} acts outside the shell` }], complete: false, readsStdin: false }
+    },
+  },
+]