mlai-code 0.0.0-stage → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/README.md +12 -2
  2. package/bin/mlai.mjs +3 -0
  3. package/package.json +18 -3
  4. package/src/browser-setup.mjs +77 -0
  5. package/src/cli-ext.mjs +146 -0
  6. package/src/cli.mjs +534 -0
  7. package/src/cloud.mjs +29 -0
  8. package/src/completion.mjs +159 -0
  9. package/src/credentials.mjs +54 -0
  10. package/src/deploy.mjs +134 -0
  11. package/src/distribution.mjs +373 -0
  12. package/src/engine-key.mjs +4 -0
  13. package/src/engine.mjs +167 -0
  14. package/src/headless.mjs +196 -0
  15. package/src/home.mjs +22 -0
  16. package/src/host.mjs +123 -0
  17. package/src/local-models.mjs +64 -0
  18. package/src/modes.mjs +38 -0
  19. package/src/netbox.mjs +97 -0
  20. package/src/netjail.py +59 -0
  21. package/src/offline.mjs +98 -0
  22. package/src/parity.mjs +86 -0
  23. package/src/project.mjs +68 -0
  24. package/src/relay.mjs +140 -0
  25. package/src/render.mjs +73 -0
  26. package/src/restricted.mjs +47 -0
  27. package/src/review.mjs +70 -0
  28. package/src/runner.mjs +127 -0
  29. package/src/runtime.mjs +75 -0
  30. package/src/sandbox.mjs +135 -0
  31. package/src/sdk.mjs +11 -0
  32. package/src/server.mjs +110 -0
  33. package/src/session.mjs +290 -0
  34. package/src/settings.mjs +135 -0
  35. package/src/shared-data.mjs +3 -0
  36. package/src/tui/acp.mjs +145 -0
  37. package/src/tui/agents-cli.mjs +114 -0
  38. package/src/tui/agents-local.mjs +65 -0
  39. package/src/tui/ansi.mjs +123 -0
  40. package/src/tui/app.mjs +710 -0
  41. package/src/tui/approval.mjs +88 -0
  42. package/src/tui/bg.mjs +172 -0
  43. package/src/tui/bgterm.mjs +79 -0
  44. package/src/tui/chat.mjs +230 -0
  45. package/src/tui/clipboard.mjs +74 -0
  46. package/src/tui/cloud-cli.mjs +57 -0
  47. package/src/tui/cloud-run.mjs +123 -0
  48. package/src/tui/cmd-agents.mjs +130 -0
  49. package/src/tui/cmd-auto-review.mjs +94 -0
  50. package/src/tui/cmd-cloud.mjs +17 -0
  51. package/src/tui/cmd-config.mjs +104 -0
  52. package/src/tui/cmd-core.mjs +160 -0
  53. package/src/tui/cmd-distribution.mjs +15 -0
  54. package/src/tui/cmd-ecosystem.mjs +169 -0
  55. package/src/tui/cmd-extensibility.mjs +333 -0
  56. package/src/tui/cmd-remote.mjs +18 -0
  57. package/src/tui/cmd-review.mjs +58 -0
  58. package/src/tui/cmd-session-extra.mjs +152 -0
  59. package/src/tui/cmd-tui.mjs +200 -0
  60. package/src/tui/commands.mjs +160 -0
  61. package/src/tui/custom-commands.mjs +98 -0
  62. package/src/tui/diff.mjs +60 -0
  63. package/src/tui/editor.mjs +190 -0
  64. package/src/tui/ext-state.mjs +16 -0
  65. package/src/tui/extensions-local.mjs +140 -0
  66. package/src/tui/files.mjs +72 -0
  67. package/src/tui/handoff.mjs +110 -0
  68. package/src/tui/import-setups.mjs +151 -0
  69. package/src/tui/init.mjs +104 -0
  70. package/src/tui/keymap.mjs +70 -0
  71. package/src/tui/keys.mjs +101 -0
  72. package/src/tui/loop.mjs +75 -0
  73. package/src/tui/markdown.mjs +118 -0
  74. package/src/tui/mcp-config.mjs +225 -0
  75. package/src/tui/mcp-oauth.mjs +162 -0
  76. package/src/tui/permissions.mjs +189 -0
  77. package/src/tui/plain.mjs +32 -0
  78. package/src/tui/plugins-local.mjs +103 -0
  79. package/src/tui/remote.mjs +125 -0
  80. package/src/tui/review-cli.mjs +332 -0
  81. package/src/tui/review-github.mjs +59 -0
  82. package/src/tui/screen.mjs +60 -0
  83. package/src/tui/session-ops.mjs +104 -0
  84. package/src/tui/skills-local.mjs +92 -0
  85. package/src/tui/snapshots.mjs +87 -0
  86. package/src/tui/statusline.mjs +98 -0
  87. package/src/tui/transcript.mjs +116 -0
  88. package/src/two-words.mjs +36 -0
  89. package/src/wakeups.mjs +53 -0
  90. package/src/winenv.mjs +94 -0
  91. package/src/winsandbox.py +351 -0
  92. package/src/workspace-api.mjs +621 -0
  93. package/src/worktree.mjs +128 -0
  94. package/vendor/client-sdk/controller.cjs +115 -0
  95. package/vendor/client-sdk/files.cjs +38 -0
  96. package/vendor/client-sdk/index.cjs +133 -0
  97. package/vendor/client-sdk/login.cjs +52 -0
  98. package/vendor/client-sdk/updates.cjs +41 -0
  99. package/vendor/cloud-cli/mlai.mjs +394 -0
  100. package/worker/architecture_parse.cjs +23 -0
  101. package/worker/architecture_worker.py +394 -0
  102. package/worker/ask_first.py +96 -0
  103. package/worker/attachment_reader.py +66 -0
  104. package/worker/background_jobs.py +111 -0
  105. package/worker/brief_questions.py +56 -0
  106. package/worker/browser_local.py +49 -0
  107. package/worker/browser_pane.py +89 -0
  108. package/worker/browser_tool.py +101 -0
  109. package/worker/build_planner.py +187 -0
  110. package/worker/chat_fork.py +277 -0
  111. package/worker/checkpoints.py +133 -0
  112. package/worker/cloud_pty.py +351 -0
  113. package/worker/command_policy.py +39 -0
  114. package/worker/command_safety.py +717 -0
  115. package/worker/computer_card.sh +23 -0
  116. package/worker/computer_setup.sh +86 -0
  117. package/worker/computer_use.py +221 -0
  118. package/worker/connector_search.py +43 -0
  119. package/worker/context_manager.py +60 -0
  120. package/worker/conversation.py +144 -0
  121. package/worker/deploy_pack.py +116 -0
  122. package/worker/design_director.py +240 -0
  123. package/worker/dev_jobs.py +166 -0
  124. package/worker/edit_guard.py +99 -0
  125. package/worker/env_setup.py +129 -0
  126. package/worker/evidence.py +109 -0
  127. package/worker/fast_search.py +24 -0
  128. package/worker/git_sync.py +333 -0
  129. package/worker/goals.py +156 -0
  130. package/worker/handover.py +98 -0
  131. package/worker/harness_memory.py +194 -0
  132. package/worker/image_generation.py +173 -0
  133. package/worker/intelligence.py +149 -0
  134. package/worker/intent_model.py +78 -0
  135. package/worker/intent_weights.json +1 -0
  136. package/worker/ios_simulator.py +87 -0
  137. package/worker/kimi_bridge.py +997 -0
  138. package/worker/kimi_compact.py +93 -0
  139. package/worker/kimi_gates.py +304 -0
  140. package/worker/kimi_hook.py +617 -0
  141. package/worker/lifecycle.py +95 -0
  142. package/worker/lsp.py +77 -0
  143. package/worker/mcp_local.py +293 -0
  144. package/worker/memory.py +99 -0
  145. package/worker/mlai_auto_review.py +177 -0
  146. package/worker/mlai_hooks.py +966 -0
  147. package/worker/mlai_mcp.py +441 -0
  148. package/worker/mlai_permissions.py +283 -0
  149. package/worker/model_stream.py +75 -0
  150. package/worker/nested_repos.py +76 -0
  151. package/worker/offline_guard.py +17 -0
  152. package/worker/preview.py +806 -0
  153. package/worker/proc_watch.py +124 -0
  154. package/worker/project_context.py +72 -0
  155. package/worker/project_rules.py +99 -0
  156. package/worker/quality.py +180 -0
  157. package/worker/reply_language.py +56 -0
  158. package/worker/repo_hygiene.py +132 -0
  159. package/worker/repo_memory.py +101 -0
  160. package/worker/repo_policy.py +269 -0
  161. package/worker/roles.json +3173 -0
  162. package/worker/roles.py +303 -0
  163. package/worker/runner.py +1795 -0
  164. package/worker/runtime_control.py +205 -0
  165. package/worker/secret_scan.py +168 -0
  166. package/worker/session_hub.py +80 -0
  167. package/worker/skill_library.py +129 -0
  168. package/worker/skill_pack.py +533 -0
  169. package/worker/subagents.py +91 -0
  170. package/worker/task_controller.py +139 -0
  171. package/worker/task_skills.py +159 -0
  172. package/worker/team_checkpoint.py +33 -0
  173. package/worker/token_count.py +32 -0
  174. package/worker/tool_catalog.py +38 -0
  175. package/worker/upload_storage.py +531 -0
  176. package/worker/verification.py +725 -0
  177. package/worker/vision.py +84 -0
  178. package/worker/wakeups.py +63 -0
  179. package/worker/web_tools.py +203 -0
  180. package/worker/winproc.py +135 -0
  181. package/worker/work_ledger.py +117 -0
  182. package/worker/worktrees.py +79 -0
@@ -0,0 +1,717 @@
1
+ """Command-safety classifier for Bash calls (port of the Pixis `command-safety` pipeline to Python).
2
+
3
+ lex -> split into simple commands (pipes, lists, subshells, substitutions, heredocs) -> walk wrappers (sudo, env, xargs,
4
+ timeout, nohup, bash -c) -> evaluate each simple command to one EFFECT -> aggregate worst-wins -> apply the mode budget.
5
+
6
+ The classifier is a total function: anything it cannot read becomes `ask` with a reason, never `allow`.
7
+ The floor sits above every budget: catastrophic targets and writes to the harness state are denied in every mode;
8
+ destructive commands and privilege escalation are never answered automatically.
9
+
10
+ Effects, mildest first:
11
+ read inspection only (ls, cat, grep, git status ...)
12
+ check tests, builds, type checks, linters (the verification gate counts these)
13
+ write creates or changes files inside the workspace
14
+ exec runs project code or scripts whose effects are unknown (node script.js, ./run.sh, npm run x)
15
+ install package managers fetching dependencies (npm install, pip install, apt-get install ...)
16
+ service starting or stopping local services (service postgresql start, docker run ...)
17
+ network talks to the internet or pushes code (curl, wget, ssh, git push ...)
18
+ external writes outside the workspace (home dotfiles, other directories)
19
+ destructive recursive deletes, history rewrites, force pushes, drop/truncate, mass kills
20
+ privilege sudo/su for anything but installs and services, writes to system directories
21
+ catastrophic rm -rf / or ~, mkfs, dd to a device, fork bombs, reboot, harness state tampering
22
+ """
23
+ import os, re, shlex
24
+ from pathlib import PurePosixPath
25
+
26
+ EFFECTS = ('read', 'check', 'write', 'exec', 'install', 'service', 'network', 'external', 'destructive', 'privilege', 'catastrophic')
27
+ RANK = {e: i for i, e in enumerate(EFFECTS)}
28
+
29
+ READ_PROGRAMS = frozenset(('ls', 'cat', 'head', 'tail', 'wc', 'grep', 'rg', 'egrep', 'fgrep', 'pwd', 'echo', 'printf', 'tree', 'stat', 'file', 'du', 'df', 'which', 'whereis', 'type',
30
+ 'whoami', 'id', 'date', 'uname', 'hostname', 'jq', 'yq', 'sort', 'uniq', 'cut', 'tr', 'basename', 'dirname', 'realpath', 'readlink', 'diff', 'cmp', 'true', 'false', 'nl',
31
+ 'column', 'awk', 'less', 'more', 'md5sum', 'sha256sum', 'sha1sum', 'xxd', 'od', 'strings', 'env', 'printenv', 'ps', 'top', 'free', 'nproc', 'lscpu', 'uptime', 'lsof',
32
+ 'ss', 'netstat', 'test', '[', 'seq', 'expr', 'bc', 'sleep', 'wait', 'cd', 'export', 'set', 'unset', 'alias', 'ulimit', 'fd', 'fdfind', 'ag', 'ack', 'tac', 'rev',
33
+ 'paste', 'join', 'comm', 'tee', 'ldd', 'getent', 'locale', 'tput', 'clear', 'history', 'help', 'man', 'info', 'look', 'fold', 'fmt', 'expand', 'unexpand', 'split',
34
+ 'base64', 'tail', 'shasum', 'cksum', 'numfmt', 'timeout', 'gzip', 'gunzip', 'zcat', 'xz', 'unxz', 'bzip2', 'bunzip2', 'exit', 'return', 'break', 'continue', 'shift',
35
+ 'read', 'local', 'declare', 'typeset', 'readonly', 'let', 'eval_echo', 'ip', 'ifconfig', 'route', 'dig', 'nslookup', 'host', 'ping', 'command', 'builtin', 'hash'))
36
+ # Programs that write files given as arguments (the paths decide whether the write is inside the workspace).
37
+ WRITE_PROGRAMS = frozenset(('mkdir', 'touch', 'cp', 'mv', 'ln', 'rmdir', 'tar', 'unzip', 'zip', 'patch', 'install', 'rsync', 'truncate', 'mktemp', 'chmod', 'chown', 'chgrp', 'ed', 'tee', 'sed', 'perl',
38
+ 'dos2unix', 'unix2dos', 'sqlite3', 'convert', 'ffmpeg', 'pandoc', 'magick', 'gzip', 'gunzip', 'xz', 'bzip2', 'wget_out', 'prettier', 'black', 'isort', 'gofmt', 'rustfmt', 'eslint_fix'))
39
+ GIT_READ = frozenset(('status', 'diff', 'log', 'show', 'branch', 'ls-files', 'ls-tree', 'rev-parse', 'remote', 'blame', 'describe', 'shortlog', 'grep', 'config', 'cat-file', 'rev-list', 'tag', 'stash_list',
40
+ 'reflog', 'count-objects', 'help', 'version', 'var', 'check-ignore', 'name-rev', 'merge-base', 'whatchanged', 'for-each-ref', 'show-ref', 'symbolic-ref'))
41
+ GIT_WRITE = frozenset(('add', 'commit', 'checkout', 'switch', 'restore', 'merge', 'rebase', 'stash', 'cherry-pick', 'revert', 'mv', 'rm', 'init', 'apply', 'am', 'worktree', 'submodule', 'notes', 'bisect', 'update-index', 'reset'))
42
+ GIT_NETWORK = frozenset(('push', 'fetch', 'pull', 'clone', 'ls-remote', 'remote_update', 'lfs'))
43
+ NETWORK_PROGRAMS = frozenset(('curl', 'wget', 'ssh', 'scp', 'sftp', 'rsync_remote', 'nc', 'ncat', 'netcat', 'telnet', 'ftp', 'gh', 'glab', 'hub', 'aws', 'gcloud', 'az', 'vercel', 'netlify', 'wrangler',
44
+ 'heroku', 'fly', 'flyctl', 'railway', 'supabase', 'firebase', 'doctl', 'kubectl', 'helm', 'terraform', 'pulumi', 'ansible', 'docker_push', 'twine', 'gem_push', 'http', 'https', 'httpie', 'wscat', 'openssl_s_client', 'mail', 'sendmail'))
45
+ INSTALLERS = {'npm': ('install', 'i', 'add', 'ci', 'update', 'up', 'uninstall', 'remove', 'rm', 'un', 'link', 'dedupe', 'prune', 'rebuild'), 'pnpm': ('install', 'i', 'add', 'update', 'up', 'remove', 'rm', 'uninstall', 'link', 'dedupe', 'prune', 'rebuild', 'import'),
46
+ 'yarn': ('install', 'add', 'remove', 'upgrade', 'up', 'link', 'import'), 'bun': ('install', 'i', 'add', 'remove', 'rm', 'update', 'link', 'pm'), 'pip': ('install', 'uninstall', 'download', 'wheel'), 'pip3': ('install', 'uninstall', 'download', 'wheel'),
47
+ 'uv': ('pip', 'add', 'remove', 'sync', 'lock', 'tool', 'python', 'venv'), 'poetry': ('install', 'add', 'remove', 'update', 'lock'), 'pipx': ('install', 'uninstall', 'upgrade', 'inject'), 'conda': ('install', 'create', 'update', 'remove', 'env'), 'mamba': ('install', 'create', 'update', 'remove', 'env'),
48
+ 'cargo': ('add', 'install', 'remove', 'update', 'fetch'), 'go': ('get', 'install', 'mod'), 'gem': ('install', 'uninstall', 'update'), 'bundle': ('install', 'update', 'add', 'remove'), 'composer': ('install', 'update', 'require', 'remove'),
49
+ 'apt': ('install', 'remove', 'purge', 'update', 'upgrade', 'autoremove', 'dist-upgrade', 'full-upgrade'), 'apt-get': ('install', 'remove', 'purge', 'update', 'upgrade', 'autoremove', 'dist-upgrade', 'build-dep', 'clean', 'autoclean'),
50
+ 'dnf': ('install', 'remove', 'update', 'upgrade'), 'yum': ('install', 'remove', 'update', 'upgrade'), 'apk': ('add', 'del', 'update', 'upgrade'), 'brew': ('install', 'uninstall', 'upgrade', 'update', 'tap', 'remove'), 'snap': ('install', 'remove', 'refresh'),
51
+ 'rustup': ('install', 'update', 'default', 'toolchain', 'target', 'component'), 'nvm': ('install', 'use', 'alias'), 'pyenv': ('install', 'global', 'local'), 'corepack': ('enable', 'prepare', 'use'), 'mix': ('deps.get', 'local.hex', 'archive.install'), 'dotnet': ('add', 'restore', 'tool')}
52
+ # Checks are read effects with a verifiable exit status: the verification gate counts them.
53
+ CHECK = re.compile(r'^(pytest|py\.test|unittest|tsc|vitest|jest|mocha|ava|tap|playwright|cypress|eslint|biome|prettier|ruff|mypy|pyright|flake8|pylint|black|isort|golangci-lint|staticcheck|shellcheck|hadolint|stylelint|tsx_test|phpunit|rspec|rubocop|ctest|cmake_test|dotnet_test|swift_test|gradle|gradlew|mvn|mvnw|cargo_check)$')
54
+ CHECK_SUBCOMMAND = {'npm': ('test', 't', 'tst', 'run-script_test'), 'pnpm': ('test', 't'), 'yarn': ('test',), 'bun': ('test',), 'deno': ('test', 'check', 'lint', 'fmt'), 'go': ('test', 'build', 'vet', 'fmt'), 'cargo': ('test', 'build', 'check', 'clippy', 'fmt', 'doc'),
55
+ 'make': ('test', 'check', 'build', 'lint', 'all', ''), 'mvn': ('test', 'verify', 'compile', 'package'), 'gradle': ('test', 'build', 'check'), 'dotnet': ('test', 'build'), 'mix': ('test', 'compile', 'format'), 'swift': ('test', 'build'), 'flutter': ('test', 'analyze'), 'dart': ('test', 'analyze'),
56
+ 'python': ('-m pytest', '-m unittest', '-m mypy', '-m ruff', '-m flake8', '-m py_compile', '-m compileall'), 'python3': ('-m pytest', '-m unittest', '-m mypy', '-m ruff', '-m flake8', '-m py_compile', '-m compileall'), 'node': ('--test', '--check', '-c')}
57
+ CHECK_SCRIPTS = frozenset(('test', 'build', 'lint', 'typecheck', 'type-check', 'check', 'test:unit', 'test:ci', 'test:e2e', 'lint:fix', 'format:check', 'compile', 'verify', 'coverage', 'tsc'))
58
+ INTERPRETERS = frozenset(('node', 'nodejs', 'python', 'python3', 'python2', 'ruby', 'perl', 'php', 'deno', 'bun', 'tsx', 'ts-node', 'java', 'go', 'dotnet', 'swift', 'lua', 'Rscript', 'julia', 'elixir', 'erl', 'ghc', 'runghc', 'scala', 'kotlin', 'kotlinc'))
59
+ SERVICE_PROGRAMS = frozenset(('service', 'systemctl', 'docker', 'docker-compose', 'podman', 'pg_ctl', 'pg_ctlcluster', 'redis-server', 'mongod', 'mysqld', 'nginx', 'supervisorctl', 'pm2', 'forever', 'minikube', 'kind', 'colima', 'brew_services'))
60
+ SHELLS = frozenset(('bash', 'sh', 'zsh', 'dash', 'ksh', 'fish'))
61
+ WRAPPERS = frozenset(('env', 'command', 'exec', 'nohup', 'nice', 'ionice', 'time', 'timeout', 'stdbuf', 'unbuffer', 'script_wrap', 'caffeinate', 'chronic', 'builtin', 'doas_placeholder', 'setsid', 'watch', 'strace', 'ltrace', 'valgrind'))
62
+ FORK_BOMB = re.compile(r':\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&?\s*\}\s*;?\s*:')
63
+ SYSTEM_DIRS = ('/etc', '/usr', '/bin', '/sbin', '/lib', '/lib64', '/boot', '/var', '/opt', '/root', '/sys', '/proc', '/dev', '/snap', '/srv')
64
+ CATASTROPHIC_TARGETS = frozenset(('/', '/*', '~', '~/', '~/*', '/home', '/home/*', '/etc', '/usr', '/bin', '/sbin', '/lib', '/boot', '/var', '/dev', '/proc', '/sys', '.', './', '*', './*', '..', '../', '../*'))
65
+ TOOL_FILES = ('.mini', '.kimi', 'kimi-approve-all', 'pending.json', 'decision-')
66
+ DEVICE = re.compile(r'^/dev/(sd|hd|nvme|vd|xvd|mmcblk|disk|mapper|dm-|loop|md)')
67
+ OPTION_WITH_VALUE = {'xargs': ('-I', '-n', '-P', '-L', '-d', '-E', '-s', '--max-args', '--max-procs', '--delimiter', '--replace'), 'timeout': ('-s', '-k', '--signal', '--kill-after'), 'env': ('-u', '-C', '-S', '--unset', '--chdir'), 'sudo': ('-u', '-g', '-p', '-C', '-h', '-r', '-t', '-U', '-T'), 'nice': ('-n',), 'ionice': ('-c', '-n', '-p'), 'stdbuf': ('-i', '-o', '-e'), 'watch': ('-n', '-d')}
68
+
69
+
70
+ class Verdict(dict):
71
+ """{'decision': allow|ask|deny, 'effect': ..., 'reason': ..., 'paths': [...], 'programs': [...]}"""
72
+ decision = property(lambda s: s['decision']); effect = property(lambda s: s['effect']); reason = property(lambda s: s['reason'])
73
+
74
+
75
+ # ------------------------------------------------------------------------------------------------------------ lexing
76
+ def _strip_heredocs(command):
77
+ """Return (command without heredoc bodies, list of (program-hint, body)). The body is data unless fed to a shell."""
78
+ bodies = []
79
+ lines = command.split('\n')
80
+ out, i = [], 0
81
+ while i < len(lines):
82
+ line = lines[i]
83
+ m = re.search(r'<<-?\s*([\'"]?)([A-Za-z_][A-Za-z0-9_]*)\1', line)
84
+ if m and '<<<' not in line:
85
+ term = m.group(2); body = []
86
+ j = i + 1
87
+ while j < len(lines) and lines[j].strip() != term and lines[j] != term: body.append(lines[j]); j += 1
88
+ bodies.append((line[:m.start()], '\n'.join(body)))
89
+ out.append(line[:m.start()] + ' ' + line[m.end():])
90
+ i = j + 1
91
+ continue
92
+ out.append(line); i += 1
93
+ return '\n'.join(out), bodies
94
+
95
+
96
+ def split_statements(text):
97
+ """Split a shell text into simple-command strings at ; & && || | newline, honouring quotes and nesting.
98
+ Subshells (...) and groups {...} contribute their inner statements; $(...) / `...` / <(...) contribute theirs too."""
99
+ out, buf, depth_paren, depth_brace, i, n = [], [], 0, 0, 0, len(text)
100
+ quote = None
101
+ subs = []
102
+ while i < n:
103
+ c = text[i]
104
+ if quote:
105
+ buf.append(c)
106
+ if c == '\\' and quote == '"' and i + 1 < n: buf.append(text[i + 1]); i += 2; continue
107
+ if c == quote: quote = None
108
+ elif quote == '"' and c == '$' and i + 1 < n and text[i + 1] == '(':
109
+ inner, end = _balanced(text, i + 1)
110
+ subs.append(inner); buf.append(text[i + 1:end]); i = end; continue
111
+ elif quote == '"' and c == '`':
112
+ end = text.find('`', i + 1)
113
+ if end == -1: end = n
114
+ subs.append(text[i + 1:end]); buf.append(text[i + 1:end + 1]); i = end + 1; continue
115
+ i += 1; continue
116
+ if c == '\\' and i + 1 < n: buf.append(c); buf.append(text[i + 1]); i += 2; continue
117
+ if c in ('"', "'"): quote = c; buf.append(c); i += 1; continue
118
+ if c == '`':
119
+ end = text.find('`', i + 1)
120
+ if end == -1: end = n
121
+ subs.append(text[i + 1:end]); buf.append('__SUBST__'); i = end + 1; continue
122
+ if c == '$' and i + 1 < n and text[i + 1] == '(':
123
+ inner, end = _balanced(text, i + 1)
124
+ subs.append(inner); buf.append('__SUBST__'); i = end; continue
125
+ if c in '<>' and i + 1 < n and text[i + 1] == '(':
126
+ inner, end = _balanced(text, i + 1)
127
+ subs.append(inner); buf.append('/dev/fd/__PROCSUB__'); i = end; continue
128
+ if c == '(':
129
+ inner, end = _balanced(text, i)
130
+ # Subshell: its statements are top-level statements of their own.
131
+ if ''.join(buf).strip(): out.append(''.join(buf)); buf = []
132
+ out.extend(split_statements(inner)); i = end; continue
133
+ if c == '{' and (not buf or ''.join(buf).strip() == '' or ''.join(buf).rstrip().endswith(('&&', '||', '|', ';'))) and (i + 1 < n and text[i + 1] in ' \t\n'):
134
+ inner, end = _balanced(text, i, '{', '}')
135
+ if ''.join(buf).strip(): out.append(''.join(buf)); buf = []
136
+ out.extend(split_statements(inner)); i = end; continue
137
+ if c == '\n' or c == ';': out.append(''.join(buf)); buf = []; i += 1; continue
138
+ if c == '&' and i + 1 < n and text[i + 1] == '&': out.append(''.join(buf)); buf = []; i += 2; continue
139
+ if c == '&' and i > 0 and text[i - 1] == '>': buf.append(c); i += 1; continue # 2>&1, &>file
140
+ if c == '|' and i + 1 < n and text[i + 1] == '|': out.append(''.join(buf)); buf = []; i += 2; continue
141
+ if c == '|' and not (i + 1 < n and text[i + 1] == '&'): out.append(''.join(buf)); buf = []; i += 1; continue
142
+ if c == '|': out.append(''.join(buf)); buf = []; i += 2; continue
143
+ if c == '&' and i + 1 < n and text[i + 1] == '>': buf.append(c); i += 1; continue
144
+ if c == '&': out.append(''.join(buf)); buf = []; i += 1; continue
145
+ buf.append(c); i += 1
146
+ if quote: raise ValueError('unterminated quote')
147
+ out.append(''.join(buf))
148
+ statements = [s.strip() for s in out if s.strip()]
149
+ for s in subs: statements.extend(split_statements(s))
150
+ return statements
151
+
152
+
153
+ def _balanced(text, start, open_c='(', close_c=')'):
154
+ """text[start] is open_c; return (inner text, index after the matching close)."""
155
+ depth, i, n, quote = 0, start, len(text), None
156
+ while i < n:
157
+ c = text[i]
158
+ if quote:
159
+ if c == '\\': i += 2; continue
160
+ if c == quote: quote = None
161
+ elif c in ('"', "'"): quote = c
162
+ elif c == '\\': i += 2; continue
163
+ elif c == open_c: depth += 1
164
+ elif c == close_c:
165
+ depth -= 1
166
+ if depth == 0: return text[start + 1:i], i + 1
167
+ i += 1
168
+ raise ValueError('unbalanced ' + open_c)
169
+
170
+
171
+ def _words(statement):
172
+ """shlex words plus the redirect targets ([(kind, path)])."""
173
+ redirects = []
174
+ # Strip the harmless forms first.
175
+ s = re.sub(r'\s2>&1|\s[12]?>\s*/dev/null|\s&>\s*/dev/null|\s<\s*/dev/null', ' ', statement)
176
+ def take(m):
177
+ op, target = m.group(1), m.group(2)
178
+ redirects.append(('write' if '>' in op else 'read', target)); return ' '
179
+ s = re.sub(r'(?:^|\s)(\d*>>?|&>>?|<)\s*([^\s;&|<>]+)', take, s)
180
+ s = s.replace('__SUBST__', 'x')
181
+ words = shlex.split(s, posix=True)
182
+ return words, redirects
183
+
184
+
185
+ # ----------------------------------------------------------------------------------------------------------- walking
186
+ def _strip_wrappers(words):
187
+ """Peel sudo/env/xargs/timeout/... and return (words of the real command, flags) where flags has 'sudo', 'xargs'."""
188
+ flags = set()
189
+ guard = 0
190
+ while words and guard < 12:
191
+ guard += 1
192
+ prog = words[0].rsplit('/', 1)[-1]
193
+ if re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*=.*', words[0]) and not words[0].startswith('='):
194
+ words = words[1:]; continue
195
+ if prog in ('sudo', 'doas', 'pkexec'):
196
+ user = next((words[i + 1] for i, w in enumerate(words) if w in ('-u', '--user') and i + 1 < len(words)), None)
197
+ flags.add('sudo' if user in (None, 'root', '0', '#0') else 'sudo_user'); words = _skip_options(words[1:], OPTION_WITH_VALUE.get('sudo', ())); continue
198
+ if prog in ('su',):
199
+ flags.add('sudo'); flags.add('su'); return words, flags
200
+ if prog == 'xargs':
201
+ flags.add('xargs'); words = _skip_options(words[1:], OPTION_WITH_VALUE['xargs'])
202
+ if not words: words = ['echo']
203
+ continue
204
+ if prog in WRAPPERS or prog in ('nice', 'ionice', 'timeout', 'env', 'stdbuf', 'watch'):
205
+ rest = _skip_options(words[1:], OPTION_WITH_VALUE.get(prog, ()))
206
+ if prog == 'timeout' and rest and re.fullmatch(r'[\d.]+[smhd]?', rest[0]): rest = rest[1:]
207
+ if prog == 'env':
208
+ while rest and re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*=.*', rest[0]): rest = rest[1:]
209
+ if not rest: return ['env'], flags
210
+ words = rest; continue
211
+ if prog in ('find',) :
212
+ return words, flags
213
+ break
214
+ return words, flags
215
+
216
+
217
+ def _skip_options(words, with_value):
218
+ i = 0
219
+ while i < len(words) and words[i].startswith('-') and words[i] != '-' and words[i] != '--':
220
+ opt = words[i]
221
+ i += 1
222
+ if opt in with_value and i < len(words): i += 1
223
+ if i < len(words) and words[i] == '--': i += 1
224
+ return words[i:]
225
+
226
+
227
+ # -------------------------------------------------------------------------------------------------------- evaluating
228
+ def _norm(path, cwd):
229
+ p = os.path.expanduser(path) if path.startswith('~') else path
230
+ if not p.startswith('/'): p = os.path.join(cwd, p)
231
+ return os.path.normpath(p)
232
+
233
+
234
+ def _inside(path, root):
235
+ root = os.path.normpath(root)
236
+ return path == root or path.startswith(root + '/')
237
+
238
+
239
+ def _classify_paths(paths, repo, cwd, home):
240
+ """Worst location class of the given paths: 'repo' | 'tmp' | 'home' | 'system' | 'harness' | 'other'."""
241
+ worst = 'repo'
242
+ order = {'repo': 0, 'tmp': 0, 'other': 1, 'home': 2, 'system': 3, 'harness': 4}
243
+ classes = []
244
+ for raw in paths:
245
+ p = _norm(raw, cwd)
246
+ if any(seg in TOOL_FILES or seg.startswith('decision-') for seg in p.split('/')) or _inside(p, os.path.join(os.path.dirname(os.path.normpath(repo)), '.mini')): cls = 'harness'
247
+ elif _inside(p, repo): cls = 'repo'
248
+ elif p.startswith('/tmp') or p.startswith('/var/tmp') or p.startswith('/dev/shm') or p.startswith('/dev/null') or p.startswith('/dev/fd') or p.startswith('/dev/stdout') or p.startswith('/dev/stderr'): cls = 'tmp'
249
+ elif any(p == d or p.startswith(d + '/') for d in SYSTEM_DIRS): cls = 'system'
250
+ elif home and _inside(p, home): cls = 'home'
251
+ else: cls = 'other'
252
+ classes.append(cls)
253
+ if order[cls] > order[worst]: worst = cls
254
+ return worst, classes
255
+
256
+
257
+ REGENERABLE = {'__pycache__', '.pytest_cache', '.mypy_cache', '.ruff_cache', '.tox', '.nox', '.cache', 'node_modules', '.next', '.nuxt', '.svelte-kit', '.turbo', '.parcel-cache', 'dist', 'build', 'out', 'target', 'coverage', '.coverage', 'htmlcov', '.eggs', 'tmp', '.tmp', '.venv', 'venv', '.gradle', 'bin', 'obj', 'storybook-static', '.angular', '.vite'}
258
+ REGENERABLE_SUFFIX = ('.pyc', '.pyo', '.log', '.tsbuildinfo', '.egg-info', '.o', '.class')
259
+
260
+ def _regenerable(target):
261
+ """A build or cache artefact the toolchain recreates: deleting it is routine, not destructive."""
262
+ t = target.rstrip('/')
263
+ if not t or '*' in t or '?' in t or t.startswith(('/', '~', '..')): return False
264
+ name = t.rsplit('/', 1)[-1]
265
+ return name in REGENERABLE or name.endswith(REGENERABLE_SUFFIX)
266
+
267
+ def _is_glob_or_catastrophic(raw, cwd, repo, home):
268
+ r = raw.strip().rstrip('/') or '/'
269
+ if raw.strip() in CATASTROPHIC_TARGETS: return True
270
+ p = _norm(raw, cwd)
271
+ if p == '/' or p == os.path.normpath(home or '/nonexistent') or p == os.path.dirname(os.path.normpath(repo)): return True
272
+ if re.fullmatch(r'/[^/]*\*?', p) and p not in ('/tmp',): return True # top-level system directory or /*
273
+ if any(p == d for d in SYSTEM_DIRS): return True
274
+ if p == os.path.normpath(repo) and raw.strip() in ('.', './', '*', './*'): return True
275
+ if p == os.path.normpath(repo): return True
276
+ return False
277
+
278
+
279
+ def evaluate(words, redirects, flags, repo, cwd, home, body_programs=None):
280
+ """One simple command -> (effect, reason, paths)."""
281
+ if not words: return 'read', 'empty', []
282
+ prog = words[0].rsplit('/', 1)[-1]
283
+ args = words[1:]
284
+ opts = [a for a in args if a.startswith('-')]
285
+ positional = [a for a in args if not a.startswith('-')]
286
+ paths = []
287
+ effect, reason = None, ''
288
+
289
+ def path_effect(targets, base):
290
+ loc, _ = _classify_paths(targets or ['.'], repo, cwd, home)
291
+ if loc == 'harness': return 'catastrophic', 'writes to the harness state (' + ', '.join(targets[:3]) + ')'
292
+ if loc == 'system': return 'privilege', base + ' touches a system directory (' + ', '.join(targets[:3]) + ')'
293
+ if loc in ('home', 'other'): return 'external', base + ' writes outside the workspace (' + ', '.join(targets[:3]) + ')'
294
+ return base, ''
295
+
296
+ if prog in ('rm', 'shred', 'unlink'):
297
+ recursive = any(o in ('-r', '-R', '-rf', '-fr', '-Rf', '-fR', '--recursive') or (o.startswith('-') and not o.startswith('--') and ('r' in o or 'R' in o)) for o in opts)
298
+ targets = positional
299
+ if not targets and 'xargs' in flags: return 'destructive', 'rm fed by xargs removes an unknown list of paths', []
300
+ if not targets: return 'write', 'rm without a target', []
301
+ for t in targets:
302
+ if _is_glob_or_catastrophic(t, cwd, repo, home) and (recursive or prog == 'shred' or t.endswith('*')): return 'catastrophic', 'removes ' + t + ' recursively', targets
303
+ loc, classes = _classify_paths(targets, repo, cwd, home)
304
+ if loc == 'harness': return 'catastrophic', 'removes harness state', targets
305
+ if loc == 'system': return 'catastrophic', 'removes system files', targets
306
+ if loc in ('home', 'other'): return ('catastrophic' if recursive else 'external'), 'deletes outside the workspace (' + ', '.join(targets[:3]) + ')', targets
307
+ if all(c == 'tmp' for c in classes) and 'xargs' not in flags: return 'write', 'removes scratch files', targets
308
+ if 'xargs' not in flags and prog == 'rm' and all(_regenerable(t) for t in targets): return 'write', 'removes build or cache output (' + ', '.join(targets[:3]) + ')', targets
309
+ if recursive or 'xargs' in flags or any('*' in t for t in targets) or prog == 'shred': return 'destructive', 'recursive or wildcard delete inside the workspace (' + ', '.join(targets[:3]) + ')', targets
310
+ return 'write', '', targets
311
+ if prog in ('mkfs', 'fdisk', 'parted', 'wipefs', 'shutdown', 'reboot', 'halt', 'poweroff', 'init', 'telinit', 'swapoff', 'mkswap') or prog.startswith('mkfs.'): return 'catastrophic', prog + ' changes disks or the machine state', []
312
+ if prog == 'dd':
313
+ for a in args:
314
+ if a.startswith('of=') and (DEVICE.match(a[3:]) or a[3:] in ('/dev/mem', '/dev/kmem')): return 'catastrophic', 'dd writes to a block device', [a[3:]]
315
+ targets = [a[3:] for a in args if a.startswith('of=')]
316
+ return path_effect(targets, 'write') + (targets,)
317
+ for kind, target in redirects:
318
+ if kind == 'write' and DEVICE.match(_norm(target, cwd)): return 'catastrophic', 'redirect to a block device', [target]
319
+ if prog in ('kill', 'killall', 'pkill', 'fuser'):
320
+ if prog == 'kill' and ('-1' in positional or '0' in positional[-1:] if positional else False) : return 'destructive', 'kills every process', []
321
+ if prog in ('killall', 'pkill') and positional and positional[-1] in ('bash', 'sh', 'node', 'python', 'python3', 'kimi', 'init', 'systemd', 'sshd', '-1'): return 'destructive', 'kills shared processes (' + positional[-1] + ')', []
322
+ return 'write', 'stops a process', []
323
+ if prog in ('chmod', 'chown', 'chgrp'):
324
+ recursive = any(o in ('-R', '--recursive') for o in opts) or any(o.startswith('-') and 'R' in o for o in opts)
325
+ targets = positional[1:] if positional else []
326
+ for t in targets:
327
+ if _is_glob_or_catastrophic(t, cwd, repo, home) and recursive: return 'catastrophic', prog + ' -R on ' + t, targets
328
+ if any(re.fullmatch(r'[ugoa]*\+?s|[0-7]?[4267][0-7]{3}', positional[0]) for _ in [0]) if positional else False: return 'privilege', 'sets setuid/setgid bits', targets
329
+ base = 'destructive' if recursive and targets else 'write'
330
+ e, r = path_effect(targets, base); return e, r or (prog + ' -R' if recursive else ''), targets
331
+ if prog == 'git':
332
+ sub = next((a for a in args if not a.startswith('-')), '')
333
+ rest = args[args.index(sub) + 1:] if sub in args else []
334
+ if sub == 'push':
335
+ if any(o in ('-f', '--force', '--force-with-lease', '--delete', '-d', '--mirror') or o.startswith('--force') for o in rest) or any(r.startswith('+') or r.startswith(':') for r in rest): return 'destructive', 'git push rewrites or deletes remote history', []
336
+ return 'network', 'git push publishes commits', []
337
+ if sub in ('fetch', 'pull', 'clone', 'ls-remote') or (sub == 'remote' and rest and rest[0] == 'update') or (sub == 'submodule' and 'update' in rest) or sub == 'lfs': return 'network', 'git ' + sub + ' uses the network', []
338
+ if sub == 'reset' and any(o in ('--hard', '--merge') for o in rest): return 'destructive', 'git reset --hard discards uncommitted work', []
339
+ if sub == 'clean' and any(o.startswith('-') and ('f' in o or 'x' in o or 'd' in o) and not o.startswith('--') for o in rest) or (sub == 'clean' and '--force' in rest): return 'destructive', 'git clean removes untracked files', []
340
+ if sub in ('checkout', 'restore') and (('.' in rest) or ('--' in rest and rest[-1] in ('.', '*')) or any(o in ('--source', '-s') for o in rest) and '.' in rest or (sub == 'checkout' and '--' in rest and len(rest) > rest.index('--') + 1 and rest[rest.index('--') + 1] in ('.', '*'))): return 'destructive', 'git ' + sub + ' . discards working changes', []
341
+ if sub == 'branch' and any(o in ('-D', '--delete', '-d') for o in rest): return 'destructive', 'deletes a branch', []
342
+ if sub == 'tag' and any(o in ('-d', '--delete') for o in rest): return 'destructive', 'deletes a tag', []
343
+ if sub == 'stash' and rest and rest[0] in ('drop', 'clear'): return 'destructive', 'drops stashed work', []
344
+ if sub in ('rebase', 'filter-branch', 'filter-repo', 'replace') or (sub == 'commit' and '--amend' in rest): return 'destructive', 'git ' + sub + ' rewrites history', []
345
+ if sub == 'reflog' and rest and rest[0] in ('expire', 'delete'): return 'destructive', 'git reflog expire', []
346
+ if sub == 'gc' and '--prune' in ' '.join(rest): return 'destructive', 'git gc --prune', []
347
+ if sub == 'config' and ('--global' in rest or '--system' in rest) and len([r for r in rest if not r.startswith('-')]) >= 2: return 'external', 'changes global git config', []
348
+ if sub in GIT_READ or sub == 'stash' and rest[:1] == ['list'] or sub == 'remote' and not rest[:1] or (sub == 'remote' and rest[:1] in (['-v'], ['show'], ['get-url'])) or (sub == 'config' and not any(r for r in rest if not r.startswith('-')) or (sub == 'config' and (rest[:1] in (['--get'], ['--list'], ['-l'], ['--get-regexp']) or (len([r for r in rest if not r.startswith('-')]) == 1)))):
349
+ if sub == 'branch' and rest and not rest[0].startswith('-'): return 'write', 'creates a branch', []
350
+ return 'read', '', []
351
+ if sub in GIT_WRITE or sub in ('remote', 'config', 'tag', 'branch', 'stash'): return 'write', 'git ' + sub, []
352
+ return 'exec', 'git ' + sub, []
353
+ if prog in NETWORK_PROGRAMS:
354
+ if prog in ('curl', 'wget'):
355
+ if any(x in args for x in ('-o', '-O', '--output', '--remote-name', '--output-document')) or prog == 'wget':
356
+ outs = [args[i + 1] for i, a in enumerate(args) if a in ('-o', '--output', '-O', '--output-document') and i + 1 < len(args) and not args[i + 1].startswith('-')]
357
+ e, r = path_effect(outs, 'network') if outs else ('network', '')
358
+ if e == 'network': return 'network', prog + ' downloads from the internet', outs
359
+ return e, r, outs
360
+ urls = [a for a in args if re.match(r'https?://', a)]
361
+ if urls and all(re.match(r'https?://(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(:\d+)?(/|$)', u) for u in urls): return 'read', 'local http request', []
362
+ if any(a in ('-X', '--request') or a.startswith('--request=') or a in ('-d', '--data', '--data-raw', '--data-binary', '-F', '--form', '-T', '--upload-file') for a in args) and urls: return 'network', prog + ' sends data to ' + urls[0][:80], []
363
+ return 'network', prog + ' reaches the internet', []
364
+ if prog in ('gh', 'glab', 'hub'):
365
+ sub = ' '.join(positional[:2])
366
+ if positional and positional[0] in ('auth',) : return 'privilege', 'gh auth changes credentials', []
367
+ if re.match(r'(pr|issue|repo|release|run|api|workflow|gist|search|secret|variable|label|cache|status|browse)\s*(view|list|status|diff|checks|download|comment|ls|get|watch)?$', sub) and not any(w in positional for w in ('create', 'merge', 'close', 'delete', 'edit', 'set', 'push', 'rerun', 'cancel', 'fork', 'clone', 'sync', 'review', 'ready', 'lock', 'unlock', 'transfer', 'archive', 'rename', 'upload')) and not any(a in ('-X', '--method', '-F', '-f', '--field', '--raw-field', '--input') for a in args):
368
+ return 'network', 'gh reads from GitHub', []
369
+ if positional and positional[0] == 'api' and any(a in ('-X', '--method') for a in args) and any(args[i + 1].upper() == 'DELETE' for i, a in enumerate(args) if a in ('-X', '--method') and i + 1 < len(args)): return 'destructive', 'gh api DELETE', []
370
+ if 'delete' in positional or 'archive' in positional or 'transfer' in positional: return 'destructive', 'gh ' + sub + ' deletes or transfers', []
371
+ return 'network', 'gh ' + sub + ' changes GitHub state', []
372
+ if prog in ('aws', 'gcloud', 'az', 'kubectl', 'helm', 'terraform', 'pulumi', 'doctl', 'fly', 'flyctl', 'vercel', 'netlify', 'wrangler', 'heroku', 'railway', 'supabase', 'firebase'):
373
+ if any(w in positional for w in ('delete', 'destroy', 'rm', 'remove', 'purge', 'terminate', 'drop', 'uninstall', 'prune', 'reset', 'force-delete', 'teardown')): return 'destructive', prog + ' deletes cloud resources', []
374
+ if any(w in positional for w in ('describe', 'get', 'list', 'ls', 'logs', 'status', 'show', 'inspect', 'whoami', 'version', 'plan', 'validate', 'diff', 'top', 'env', 'projects', 'teams', 'config')) and not any(w in positional for w in ('apply', 'deploy', 'create', 'set', 'add', 'push', 'promote', 'rollback', 'scale', 'edit', 'patch', 'exec', 'run', 'login')): return 'network', prog + ' reads cloud state', []
375
+ return 'network', prog + ' changes cloud state', []
376
+ return 'network', prog + ' uses the network', []
377
+ if prog in SERVICE_PROGRAMS or (prog == 'sudo'):
378
+ if prog in ('docker', 'podman') and positional:
379
+ if positional[0] in ('system', 'volume', 'image', 'container', 'network') and len(positional) > 1 and positional[1] in ('prune', 'rm', 'rmi', 'remove'): return 'destructive', 'docker ' + ' '.join(positional[:2]) + ' removes data', []
380
+ if positional[0] in ('rm', 'rmi', 'kill') : return 'destructive', 'docker ' + positional[0], []
381
+ if positional[0] in ('ps', 'images', 'logs', 'inspect', 'version', 'info', 'stats', 'top', 'port', 'diff', 'history', 'events'): return 'read', '', []
382
+ if positional[0] in ('push', 'login', 'logout'): return 'network', 'docker ' + positional[0], []
383
+ if positional[0] in ('run', 'exec', 'compose') and any(a in args for a in ('--privileged', '-v', '--volume', '--mount')) and any('/:' in a or a.startswith('/etc') or a.startswith('/var/run/docker.sock') for a in args): return 'privilege', 'docker mounts host paths', []
384
+ return 'service', 'docker ' + positional[0], []
385
+ if prog in ('systemctl', 'service') and positional:
386
+ verbs = set(positional)
387
+ if verbs & {'status', 'is-active', 'is-enabled', 'list-units', 'list-unit-files', 'show', 'cat'}: return 'read', '', []
388
+ if verbs & {'disable', 'mask', 'daemon-reload', 'enable'} and 'sudo' in flags: return 'privilege', prog + ' changes boot configuration', []
389
+ if verbs & {'disable', 'mask'}: return 'privilege', prog + ' changes boot configuration', []
390
+ return 'service', prog + ' ' + ' '.join(positional[:2]), []
391
+ return 'service', prog + ' manages a service', []
392
+ if prog in INSTALLERS:
393
+ sub = positional[0] if positional else ''
394
+ if prog in ('pip', 'pip3') and args and args[0] == '-m': sub = ''
395
+ if prog in ('apt', 'apt-get', 'dnf', 'yum', 'apk', 'snap') and sub in ('remove', 'purge', 'autoremove', 'del', 'dist-upgrade', 'full-upgrade'): return 'privilege', prog + ' ' + sub + ' removes system packages', []
396
+ if prog in ('npm', 'pnpm', 'yarn', 'bun'):
397
+ if sub in ('publish', 'login', 'logout', 'adduser', 'owner', 'deprecate', 'unpublish', 'token', 'access'): return ('destructive' if sub in ('unpublish', 'deprecate') else 'network'), 'npm ' + sub, []
398
+ if sub in ('test', 't', 'tst') or (sub in ('run', 'run-script', 'exec') and len(positional) > 1 and positional[1] in CHECK_SCRIPTS) or (prog in ('pnpm', 'yarn', 'bun') and sub in CHECK_SCRIPTS): return 'check', '', []
399
+ if sub in ('run', 'run-script', 'start', 'exec', 'x', 'dlx', 'create', 'init', 'dev', 'serve', 'preview'): return 'exec', prog + ' ' + ' '.join(positional[:2]), []
400
+ if sub in INSTALLERS[prog] or (sub == '' and prog in ('npm', 'pnpm', 'yarn', 'bun')): return 'install', prog + ' ' + (sub or 'install'), []
401
+ if sub in ('version', 'view', 'ls', 'list', 'outdated', 'why', 'explain', 'audit', 'info', 'show', 'config', 'root', 'bin', 'prefix', 'ping', 'search', 'pack', 'cache', 'doctor', 'help'): return 'read' if sub not in ('search', 'ping', 'view', 'info', 'show', 'audit', 'outdated') else 'network', '', []
402
+ return 'exec', prog + ' ' + sub, []
403
+ if prog in ('cargo', 'go'):
404
+ if sub in CHECK_SUBCOMMAND.get(prog, ()): return 'check', '', []
405
+ if sub in ('run', 'generate', 'bench', 'tool'): return 'exec', prog + ' ' + sub, []
406
+ if sub in INSTALLERS[prog]: return 'install', prog + ' ' + sub, []
407
+ if sub in ('version', 'env', 'list', 'doc', 'metadata', 'tree', 'help', 'search'): return 'read', '', []
408
+ return 'exec', prog + ' ' + sub, []
409
+ if prog in ('uv',):
410
+ if sub == 'run': return 'exec', 'uv run', []
411
+ if sub in ('pip',) and len(positional) > 1 and positional[1] in ('list', 'show', 'freeze', 'check', 'tree'): return 'read', '', []
412
+ if prog in ('mix', 'dotnet', 'gradle', 'mvn') and sub in CHECK_SUBCOMMAND.get(prog, ()): return 'check', '', []
413
+ if sub in INSTALLERS[prog]: return 'install', prog + ' ' + sub + ' installs packages', []
414
+ if sub in ('list', 'show', 'freeze', 'check', 'config', 'version', '--version', 'help', 'info', 'search', 'env', 'which', 'tree', 'outdated', 'audit', 'cache'): return 'read', '', []
415
+ return 'exec', prog + ' ' + sub, []
416
+ if prog in SHELLS:
417
+ if '-c' in args:
418
+ script = args[args.index('-c') + 1] if args.index('-c') + 1 < len(args) else ''
419
+ effects = [evaluate_statement(s, repo, cwd, home) for s in split_statements(script)] if script else [('read', '', [])]
420
+ if 'sudo' in flags: effects.append(('privilege', 'sudo shell', []))
421
+ return _worst(effects)
422
+ scripts = [a for a in positional if not a.startswith('-')]
423
+ if body_programs is not None and not scripts: return _worst([evaluate_statement(s, repo, cwd, home) for s in split_statements(body_programs)] or [('read', '', [])])
424
+ if not scripts: return 'exec', 'interactive shell', []
425
+ return 'exec', 'runs script ' + scripts[0], scripts[:1]
426
+ if prog in ('source', '.'): return 'exec', 'sources ' + (positional[0] if positional else 'a file'), positional[:1]
427
+ if prog == 'eval': return 'exec', 'eval of a dynamic string', []
428
+ if prog == 'crontab' and not any(o in ('-l',) for o in opts): return 'privilege', 'changes the crontab', []
429
+ if prog in ('passwd', 'useradd', 'userdel', 'usermod', 'groupadd', 'visudo', 'chpasswd', 'mount', 'umount', 'modprobe', 'insmod', 'rmmod', 'sysctl', 'iptables', 'nft', 'ufw', 'setcap', 'chroot', 'update-alternatives', 'ldconfig', 'dpkg', 'rpm', 'losetup'):
430
+ if prog in ('dpkg', 'rpm') and any(o in ('-l', '-L', '-s', '-S', '--list', '-q', '-qa', '-ql', '-qi') for o in opts): return 'read', '', []
431
+ if prog == 'sysctl' and not any('=' in a or a in ('-w', '--write', '-p') for a in args): return 'read', '', []
432
+ if prog == 'mount' and not args: return 'read', '', []
433
+ return 'privilege', prog + ' changes the system', []
434
+ if prog in ('ssh-keygen', 'gpg', 'openssl') :
435
+ outs = [args[i + 1] for i, a in enumerate(args) if a in ('-f', '-o', '--output', '-out') and i + 1 < len(args)]
436
+ e, r = path_effect(outs, 'write') if outs else ('write', '')
437
+ if prog == 'ssh-keygen' or any(a in ('--gen-key', '--full-generate-key', '--import', '--delete-key', '--edit-key') for a in args): return max(e, 'external', key=lambda x: RANK[x]), prog + ' changes keys', outs
438
+ return e, r, outs
439
+ if prog == 'find':
440
+ if any(a in args for a in ('-delete',)):
441
+ root = positional[0] if positional and not positional[0].startswith('-') else '.'
442
+ if _is_glob_or_catastrophic(root, cwd, repo, home) and root not in ('.', './'): return 'catastrophic', 'find -delete from ' + root, [root]
443
+ loc, _ = _classify_paths([root], repo, cwd, home)
444
+ return ('destructive' if loc in ('repo', 'tmp') else 'catastrophic'), 'find -delete removes matching files', [root]
445
+ for i, a in enumerate(args):
446
+ if a in ('-exec', '-execdir', '-ok', '-okdir'):
447
+ inner = args[i + 1:]
448
+ stop = next((j for j, w in enumerate(inner) if w in (';', '+')), len(inner))
449
+ sub_words = [w for w in inner[:stop] if w not in ('{}',)] + ['{}']
450
+ return evaluate(sub_words, [], flags | {'xargs'}, repo, cwd, home)
451
+ return 'read', '', []
452
+ if prog in ('sed', 'perl', 'awk', 'gawk', 'ex', 'vi', 'vim', 'nano', 'emacs'):
453
+ inplace = any(o.startswith('-i') or o == '--in-place' or (prog == 'perl' and o.startswith('-p') and 'i' in o) or (prog == 'perl' and o.startswith('-') and 'i' in o and 'e' in o) for o in opts) or prog in ('ex', 'vi', 'vim', 'nano', 'emacs')
454
+ if prog == 'awk' or prog == 'gawk':
455
+ inplace = any(o in ('-i', '--in-place') or o.startswith('-i') for o in opts)
456
+ if prog == 'perl' and not inplace and any(o in ('-e', '-E') for o in opts) and not any(a.endswith('.pl') for a in positional):
457
+ code = ' '.join(args)
458
+ if re.search(r'\b(unlink|rmtree|system|exec|open\s*\(.*[>|])', code): return 'exec', 'perl one-liner with side effects', []
459
+ return 'read', '', []
460
+ if not inplace and not [r for r in redirects if r[0] == 'write']: return 'read', '', []
461
+ files = [a for a in positional[1:]] if prog in ('sed', 'perl') and positional else positional
462
+ files = [f for f in files if not f.startswith('-')]
463
+ e, r = path_effect(files, 'write'); return e, r or (prog + ' edits in place'), files
464
+ if prog in ('python', 'python3', 'python2', 'node', 'nodejs', 'deno', 'bun', 'tsx', 'ts-node', 'ruby', 'php', 'perl', 'java', 'Rscript', 'julia', 'lua', 'elixir', 'swift') or prog in INTERPRETERS:
465
+ joined = ' '.join(args)
466
+ if any(joined.startswith(c) or (' ' + c) in (' ' + joined) and c.startswith('-m ') for c in CHECK_SUBCOMMAND.get(prog, ())) or re.search(r'(^|\s)(--test|--check)\b', joined) and prog in ('node', 'deno') or (prog in ('bun', 'deno') and positional[:1] == ['test']): return 'check', '', []
467
+ if args and args[0] in ('--version', '-V', '-v', 'version'): return 'read', '', []
468
+ if prog in ('python', 'python3') and args[:1] == ['-m'] and len(args) > 1:
469
+ mod = args[1]
470
+ if mod in ('pip', 'pip3', 'ensurepip'): return 'install', 'python -m pip', []
471
+ if mod in ('http.server', 'SimpleHTTPServer', 'venv', 'virtualenv'): return 'service' if mod.endswith('server') else 'write', 'python -m ' + mod, []
472
+ if mod in ('json.tool', 'py_compile', 'compileall', 'pydoc', 'this', 'site', 'sysconfig', 'platform', 'tokenize', 'ast', 'dis'): return 'read', '', []
473
+ scripts = [a for a in positional if re.search(r'\.(py|[cm]?js|ts|tsx|rb|php|pl|jar|R|jl|lua|exs|swift)$', a)]
474
+ if prog in ('deno',) and positional[:1] == ['run'] and any(a.startswith('--allow-net') or a == '-A' for a in args): return 'network', 'deno run --allow-net', []
475
+ inline = any(o in ('-c', '-e', '-E', '-p', '--eval', '--print', '--input-type=module') for o in opts) or '-' in args
476
+ if inline or scripts:
477
+ code = joined if inline else ''
478
+ if body_programs: code += '\n' + body_programs
479
+ if re.search(r'(shutil\.rmtree|os\.remove|os\.unlink|rimraf|fs\.rm\w*Sync?\(|fs\.unlink|rm\s+-rf|subprocess|child_process|execSync|os\.system|FileUtils\.rm_rf)', code): return 'destructive', 'inline script deletes or shells out', scripts
480
+ if re.search(r'(requests\.|urllib|httpx|aiohttp|fetch\(|axios|http\.request|socket\.|net\.connect|smtplib|paramiko)', code): return 'network', 'inline script uses the network', scripts
481
+ if re.search(r'\b(assert|expect\(|unittest|pytest|console\.assert|test\(|describe\()', code) and not re.search(r'(open\([^)]*[\'"]w|writeFile|\.write\(|mkdir|rename|copy)', code): return 'check', '', scripts
482
+ if scripts and re.search(r'(^|/)(test_\w+|\w+_test|\w+\.test|\w+\.spec)\.(py|[cm]?js|ts|tsx)$', scripts[0]): return 'check', '', scripts
483
+ return 'exec', prog + ' runs ' + (scripts[0] if scripts else 'inline code'), scripts
484
+ return 'exec', prog + ' ' + ' '.join(positional[:2]), []
485
+ if prog == 'npx' or prog == 'pnpx' or prog == 'bunx':
486
+ target = next((a for a in positional if not a.startswith('-')), '')
487
+ tname = re.sub(r'@.*$', '', target) if not target.startswith('@') else target
488
+ base = tname.rsplit('/', 1)[-1]
489
+ if CHECK.match(base) or base in ('tsc', 'vitest', 'jest', 'eslint', 'playwright', 'prettier', 'biome', 'mocha', 'ava', 'cypress', 'stylelint', 'tsx_test'):
490
+ if base in ('prettier', 'eslint', 'biome') and any(a in args for a in ('--write', '--fix', 'format')): return 'write', base + ' rewrites files', []
491
+ return 'check', '', []
492
+ if base in ('create-next-app', 'create-vite', 'create-react-app', 'degit', 'giget', 'create', 'sv', 'nuxi', 'shadcn', 'shadcn-ui', 'prisma', 'drizzle-kit', 'supabase', 'vercel', 'netlify', 'wrangler', 'firebase', 'serve', 'http-server', 'vite', 'next', 'nodemon', 'ts-node', 'tsx', 'nx', 'turbo', 'lerna', 'changeset', 'husky', 'lint-staged', 'storybook', 'tailwindcss', 'expo', 'eas', 'ngrok', 'localtunnel', 'cloudflared'):
493
+ if base in ('vercel', 'netlify', 'wrangler', 'firebase', 'supabase', 'expo', 'eas', 'ngrok', 'localtunnel', 'cloudflared') : return 'network', 'npx ' + base + ' uses the network', []
494
+ if base in ('prisma', 'drizzle-kit') and any(w in positional for w in ('reset', 'drop')): return 'destructive', 'npx ' + base + ' resets the database', []
495
+ if base in ('serve', 'http-server', 'vite', 'next', 'nodemon', 'storybook') : return 'service', 'npx ' + base + ' starts a server', []
496
+ return 'exec', 'npx ' + base, []
497
+ if '-y' in args or '--yes' in args or '-p' in args or '--package' in args: return 'install', 'npx fetches ' + (base or 'a package'), []
498
+ return 'exec', 'npx ' + base, []
499
+ if prog in ('make', 'cmake', 'ninja', 'meson', 'bazel', 'buck', 'gradle', 'gradlew', 'mvn', 'mvnw', 'ant', 'sbt', 'lein', 'rake', 'bundle', 'mix'):
500
+ target = positional[0] if positional else ''
501
+ if prog == 'make' and target in ('clean', 'distclean', 'mrproper', 'uninstall') : return 'destructive', 'make ' + target + ' removes build output', []
502
+ if prog in ('make', 'gradle', 'gradlew', 'mvn', 'mvnw', 'rake', 'mix', 'sbt', 'cmake', 'ninja', 'bazel') and (target in CHECK_SUBCOMMAND.get(prog, ('test', 'build', 'check', '', 'compile', 'verify', 'lint', 'all')) or target.startswith('--build') or target in ('test', 'check', 'build', '', 'lint', 'compile', 'verify', 'all', 'typecheck')): return 'check', '', []
503
+ if prog == 'bundle' and target == 'exec' and len(positional) > 1 and positional[1] in ('rspec', 'rubocop', 'rake'): return 'check', '', []
504
+ if prog == 'cmake' and any(a.startswith('-S') or a.startswith('-B') or a.startswith('-D') or a == '..' or a == '.' for a in args): return 'write', 'cmake configures a build', []
505
+ if prog == 'make' and target == 'install': return 'install', 'make install', []
506
+ return 'exec', prog + ' ' + target, []
507
+ if prog == 'tar' or prog == 'unzip' or prog == 'zip':
508
+ if prog == 'tar' and args and ('t' in args[0].lstrip('-') and 'x' not in args[0].lstrip('-') and 'c' not in args[0].lstrip('-')) or (prog == 'unzip' and ('-l' in opts or '-t' in opts or '-Z' in opts)): return 'read', '', []
509
+ outs = [args[i + 1] for i, a in enumerate(args) if a in ('-C', '--directory', '-d') and i + 1 < len(args)] or ['.']
510
+ if prog == 'tar' and args and 'c' in args[0].lstrip('-'):
511
+ files = [a for a in positional[1:] if not a.startswith('-')]
512
+ outs = files[:1] or ['.']
513
+ e, r = path_effect(outs, 'write'); return e, r, outs
514
+ if prog in WRITE_PROGRAMS:
515
+ if prog == 'tee':
516
+ targets = [a for a in positional]
517
+ e, r = path_effect(targets, 'write'); return e, r, targets
518
+ if prog == 'install' and any(a.startswith('/') for a in positional):
519
+ loc, _ = _classify_paths(positional[-1:], repo, cwd, home)
520
+ if loc == 'system': return 'privilege', 'install into a system directory', positional[-1:]
521
+ if prog == 'ln' and 'sudo' in flags: return 'privilege', 'sudo ln', positional
522
+ if prog == 'rsync' and any('@' in a or re.match(r'^[\w.-]+:', a) for a in positional): return 'network', 'rsync to a remote host', positional
523
+ if prog in ('mv', 'cp', 'rsync') and positional:
524
+ srcs, dst = positional[:-1], positional[-1:]
525
+ if prog == 'mv':
526
+ for s in srcs:
527
+ if _is_glob_or_catastrophic(s, cwd, repo, home): return 'catastrophic', 'moves ' + s, srcs
528
+ if s.rstrip('/') in ('.git', './.git') or _norm(s, cwd) == os.path.join(os.path.normpath(repo), '.git'): return 'destructive', 'moves the git directory', srcs
529
+ if prog == 'cp' and any(o in ('-r', '-R', '-a', '-rf', '-Rf', '-ra') for o in opts) and any(_is_glob_or_catastrophic(s, cwd, repo, home) and _norm(s, cwd) != os.path.normpath(repo) for s in srcs): return 'destructive', 'copies a whole system tree', srcs
530
+ e, r = path_effect(dst, 'write')
531
+ if e == 'write' and prog == 'mv': e2, r2 = path_effect(srcs, 'write'); e, r = (e2, r2) if RANK[e2] > RANK[e] else (e, r)
532
+ return e, r, srcs + dst
533
+ if prog == 'truncate' and positional:
534
+ for s in positional:
535
+ if _is_glob_or_catastrophic(s, cwd, repo, home): return 'catastrophic', 'truncates ' + s, positional
536
+ if prog == 'mktemp': return 'write', '', []
537
+ targets = positional if prog not in ('sqlite3',) else positional[:1]
538
+ if prog == 'sqlite3' and re.search(r'\b(drop|delete\s+from|truncate)\b', ' '.join(args), re.I): return 'destructive', 'sqlite3 drops or deletes data', targets
539
+ if prog in ('convert', 'ffmpeg', 'pandoc', 'magick'): targets = positional[-1:]
540
+ e, r = path_effect(targets, 'write'); return e, r, targets
541
+ if prog in ('psql', 'mysql', 'mongosh', 'mongo', 'redis-cli', 'sqlcmd', 'clickhouse-client', 'cqlsh'):
542
+ text = ' '.join(args)
543
+ if re.search(r'\b(drop\s+(database|table|schema|index|collection)|truncate|delete\s+from|flushall|flushdb|dropdatabase)\b', text, re.I): return 'destructive', prog + ' destroys data', []
544
+ if re.search(r'\b(insert|update|alter|create|grant|revoke|set|hset|lpush|rpush|sadd|del)\b', text, re.I): return 'write', prog + ' changes data', []
545
+ return 'read', '', []
546
+ if prog in ('createdb', 'createuser', 'initdb', 'pg_restore', 'mysqladmin', 'mongorestore', 'pg_dump', 'mysqldump', 'mongodump'):
547
+ if prog in ('pg_dump', 'mysqldump', 'mongodump'): return 'read', '', []
548
+ if prog == 'mysqladmin' and 'drop' in positional: return 'destructive', 'mysqladmin drop', []
549
+ return 'write', prog, []
550
+ if prog in ('dropdb', 'dropuser'): return 'destructive', prog + ' drops a database or role', []
551
+ if prog == 'history' and ('-c' in opts): return 'write', '', []
552
+ if prog == 'cd' or prog == 'export' or prog == 'cd' or re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]*=.*', words[0] or ''): return 'read', '', []
553
+ if prog in ('echo', 'printf', 'cat') and redirects:
554
+ pass
555
+ if prog in READ_PROGRAMS:
556
+ if prog == 'gzip' and not ('-d' in opts or '-k' in opts or '-c' in opts or '-t' in opts or '-l' in opts):
557
+ e, r = path_effect(positional, 'write'); return e, r, positional
558
+ return 'read', '', []
559
+ if prog in ('sudo',): return 'privilege', 'sudo', []
560
+ if prog.startswith('./') or '/' in words[0] or prog.endswith(('.sh', '.py', '.js', '.ts', '.rb', '.pl')): return 'exec', 'runs ' + words[0], [words[0]]
561
+ if prog in ('pre-commit', 'husky', 'lint-staged', 'commitlint'): return 'check', '', []
562
+ if prog in ('prettier', 'eslint', 'black', 'isort', 'ruff', 'gofmt', 'rustfmt', 'biome', 'stylelint'):
563
+ if any(a in args for a in ('--write', '--fix', 'format', '-w')) or (prog in ('black', 'isort', 'gofmt', 'rustfmt') and not any(a in args for a in ('--check', '--diff', '-l', '-d'))): return 'write', prog + ' rewrites files', positional
564
+ return 'check', '', []
565
+ if CHECK.match(prog): return 'check', '', []
566
+ if prog in ('wget_out',): return 'network', '', []
567
+ return 'exec', 'unknown program ' + prog, []
568
+
569
+
570
+ def _worst(effects):
571
+ best = ('read', '', [])
572
+ paths = []
573
+ for e in effects:
574
+ paths.extend(e[2] or [])
575
+ if RANK[e[0]] > RANK[best[0]]: best = (e[0], e[1], e[2])
576
+ return best[0], best[1], list(dict.fromkeys(paths))
577
+
578
+
579
+ def evaluate_statement(statement, repo, cwd, home, body=None):
580
+ words, redirects = _words(statement)
581
+ if not words:
582
+ if redirects:
583
+ targets = [t for k, t in redirects if k == 'write']
584
+ if targets:
585
+ loc, _ = _classify_paths(targets, repo, cwd, home)
586
+ return {'harness': 'catastrophic', 'system': 'privilege', 'home': 'external', 'other': 'external'}.get(loc, 'write'), 'redirect to ' + targets[0], targets
587
+ return 'read', '', []
588
+ words, flags = _strip_wrappers(words)
589
+ effect, reason, paths = evaluate(words, redirects, flags, repo, cwd, home, body_programs=body)
590
+ writes = [t for k, t in redirects if k == 'write']
591
+ if writes:
592
+ for t in writes:
593
+ if DEVICE.match(_norm(t, cwd)): return 'catastrophic', 'redirect to a block device', writes
594
+ loc, _ = _classify_paths(writes, repo, cwd, home)
595
+ red_effect = {'harness': 'catastrophic', 'system': 'privilege', 'home': 'external', 'other': 'external'}.get(loc, 'write')
596
+ if RANK[red_effect] > RANK[effect]: effect, reason = red_effect, 'redirect writes to ' + writes[0]
597
+ elif effect == 'read' or effect == 'check': effect = 'write' if RANK[effect] < RANK['write'] else effect; reason = reason or 'redirect writes to ' + writes[0]
598
+ paths = list(dict.fromkeys(paths + writes))
599
+ if 'sudo_user' in flags and 'sudo' not in flags and RANK[effect] < RANK['service']: effect, reason = 'service', 'runs as another service account: ' + ' '.join(words[:2])
600
+ if 'sudo' in flags:
601
+ if effect in ('install', 'service'): reason = 'sudo ' + (reason or effect)
602
+ elif effect == 'catastrophic': pass
603
+ elif RANK[effect] < RANK['privilege']: effect, reason = 'privilege', 'sudo ' + (reason or ' '.join(words[:2]))
604
+ return effect, reason, paths
605
+
606
+
607
+ # --------------------------------------------------------------------------------------------------------- classifying
608
+ def classify(command, repo, cwd=None, home=None):
609
+ """Total: never raises. Returns Verdict without a decision (effect, reason, paths, programs)."""
610
+ repo = os.path.normpath(repo or '/')
611
+ cwd = cwd or repo
612
+ home = home if home is not None else os.path.expanduser('~')
613
+ try:
614
+ text = str(command or '')
615
+ if not text.strip(): return Verdict(decision=None, effect='read', reason='empty command', paths=[], programs=[])
616
+ if len(text) > 60000: return Verdict(decision=None, effect='unknown', reason='command too long to classify', paths=[], programs=[])
617
+ if FORK_BOMB.search(text): return Verdict(decision=None, effect='catastrophic', reason='fork bomb', paths=[], programs=[])
618
+ stripped, bodies = _strip_heredocs(text)
619
+ statements = split_statements(stripped)
620
+ effects, programs = [], []
621
+ for st in statements:
622
+ body = None
623
+ for head, b in bodies:
624
+ if head.strip() and head.strip() in st: body = b
625
+ if '__PROCSUB__' in st: st = st.replace('/dev/fd/__PROCSUB__', '/dev/fd/0')
626
+ e = evaluate_statement(st, repo, cwd, home, body=body)
627
+ effects.append(e)
628
+ try:
629
+ w, _ = _words(st); w, _f = _strip_wrappers(w)
630
+ if w: programs.append(w[0].rsplit('/', 1)[-1])
631
+ except Exception: pass
632
+ if body and (not st.split() or st.split()[0].rsplit('/', 1)[-1] in SHELLS or st.split()[0] == 'sudo'):
633
+ for inner in split_statements(body): effects.append(evaluate_statement(inner, repo, cwd, home))
634
+ if not effects: return Verdict(decision=None, effect='read', reason='empty command', paths=[], programs=[])
635
+ effect, reason, paths = _worst(effects)
636
+ return Verdict(decision=None, effect=effect, reason=reason, paths=paths[:20], programs=list(dict.fromkeys(programs))[:20])
637
+ except Exception as exc:
638
+ return Verdict(decision=None, effect='unknown', reason='could not parse the command (' + type(exc).__name__ + ': ' + str(exc)[:120] + ')', paths=[], programs=[])
639
+
640
+
641
+ # ------------------------------------------------------------------------------------------------------------ budgets
642
+ # What each mode answers by itself. Missing effects fall to `ask`; `scope`/`once` are resolved by the hook.
643
+ BUDGETS = {
644
+ 'plan': {'read': 'allow', 'check': 'deny', 'write': 'deny', 'exec': 'deny', 'install': 'deny', 'service': 'deny', 'network': 'deny', 'external': 'deny', 'destructive': 'deny', 'privilege': 'deny', 'catastrophic': 'deny', 'unknown': 'deny'},
645
+ # Inspect: the user asked for no changes. Reading and running checks reproduce defects; anything that could change the project is refused.
646
+ 'inspect': {'read': 'allow', 'check': 'allow', 'write': 'deny', 'exec': 'ask', 'install': 'deny', 'service': 'deny', 'network': 'deny', 'external': 'deny', 'destructive': 'deny', 'privilege': 'deny', 'catastrophic': 'deny', 'unknown': 'deny'},
647
+ 'approve': {'read': 'allow', 'check': 'allow', 'write': 'scope', 'exec': 'scope', 'install': 'once', 'service': 'once', 'network': 'ask', 'external': 'ask', 'destructive': 'ask', 'privilege': 'ask', 'catastrophic': 'deny', 'unknown': 'ask'},
648
+ 'auto': {'read': 'allow', 'check': 'allow', 'write': 'allow', 'exec': 'allow', 'install': 'allow', 'service': 'allow', 'network': 'allow', 'external': 'allow', 'destructive': 'ask', 'privilege': 'ask', 'catastrophic': 'deny', 'unknown': 'ask'},
649
+ }
650
+ # The floor: no mode, approval or "approve all" relaxes these.
651
+ FLOOR = {'catastrophic': 'deny'}
652
+
653
+
654
+ def decide(verdict, mode, scope=None, approved_kinds=(), approve_all=False, repo=None, cwd=None):
655
+ """Apply the budget for `mode` ('plan' | 'approve' | 'auto') to a classify() verdict.
656
+ scope: list of workspace-relative paths/directories the user approved for Guided mode (None = nothing approved yet).
657
+ approved_kinds: effect names the user already approved once this run ('install', 'service').
658
+ approve_all: the user tapped "approve all" (relaxes everything but the floor and destructive/privilege asks)."""
659
+ effect = verdict.get('effect', 'unknown')
660
+ if effect in FLOOR: return Verdict({**verdict, 'decision': FLOOR[effect], 'reason': verdict.get('reason') or effect})
661
+ budget = BUDGETS.get(mode, BUDGETS['approve'])
662
+ if approve_all and mode != 'plan': budget = {**BUDGETS['auto']}
663
+ rule = budget.get(effect, 'ask')
664
+ if rule == 'once': rule = 'allow' if effect in approved_kinds else 'ask'
665
+ if rule == 'scope':
666
+ paths = verdict.get('paths') or [] if effect != 'exec' else [] # running code is covered by the approved work; only writes need the area
667
+ if scope is None: rule = 'ask'
668
+ elif not paths: rule = 'allow'
669
+ else:
670
+ rel = [relative(p, repo or '/', cwd) for p in paths if relative(p, repo or '/', cwd) is not None or not _norm(p, cwd or repo or '/').startswith(('/tmp', '/var/tmp', '/dev/'))]
671
+ rule = 'allow' if all(r is not None and in_scope(r, scope) for r in rel) else 'ask'
672
+ return Verdict({**verdict, 'decision': rule})
673
+
674
+
675
+ def relative(path, repo, cwd=None):
676
+ """Workspace-relative POSIX path, or None when outside the repo."""
677
+ p = _norm(path, cwd or repo)
678
+ repo = os.path.normpath(repo)
679
+ if p == repo: return '.'
680
+ if not p.startswith(repo + '/'): return None
681
+ return p[len(repo) + 1:]
682
+
683
+
684
+ def in_scope(rel, scope):
685
+ """rel is inside one of the approved scope entries (a file, a directory, or '.' for everything)."""
686
+ rel = rel.strip('/').replace('__PROCSUB__', '')
687
+ for entry in scope or []:
688
+ e = str(entry).strip().strip('/')
689
+ if e in ('.', '', '*', '**'): return True
690
+ if rel == e or rel.startswith(e + '/'): return True
691
+ if '*' in e:
692
+ from fnmatch import fnmatch
693
+ if fnmatch(rel, e) or fnmatch(rel, e.rstrip('*').rstrip('/') + '/*'): return True
694
+ return False
695
+
696
+
697
+ def area(rel):
698
+ """The approval unit for a first-touch edit: the file's directory (two levels deep), or the file itself at the root."""
699
+ parts = PurePosixPath(rel.strip('/')).parts
700
+ if len(parts) <= 1: return parts[0] if parts else '.'
701
+ return '/'.join(parts[:2]) if len(parts) > 2 else parts[0]
702
+
703
+
704
+ def describe(verdict):
705
+ """Short human line for the approval card."""
706
+ effect = verdict.get('effect', 'unknown')
707
+ labels = {'write': 'Writes files', 'exec': 'Runs project code', 'install': 'Installs packages', 'service': 'Starts or stops a service', 'network': 'Uses the network', 'external': 'Writes outside the workspace',
708
+ 'destructive': 'Destructive', 'privilege': 'Needs elevated rights', 'catastrophic': 'Never run', 'unknown': 'Could not classify', 'read': 'Read only', 'check': 'Runs a check'}
709
+ line = labels.get(effect, effect)
710
+ if verdict.get('reason'): line += ': ' + verdict['reason']
711
+ return line
712
+
713
+
714
+ def safe_command(command, repo=None, cwd=None):
715
+ """Read-only or check command that needs no approval in any mode but Plan (compatibility with runtime_control.safe_command)."""
716
+ v = classify(command, repo or os.getenv('MINI_REPO', '/vercel/sandbox/repo'), cwd)
717
+ return v['effect'] in ('read', 'check')