claude-bulkhead 0.2.2 → 0.3.0

package/src/dev-servers.js

@@ -1,47 +1,183 @@
 'use strict'
 const fs = require('fs')
+const os = require('os')
 const path = require('path')
+const shell = require('./shell')
 
 // Dev servers and the port each one uses when none is given. `sub` lists the subcommands
-// that start a server; '' means the bare command does, null means any arguments do.
+// that start a server; '' means the bare command does, null means any arguments do. `notSub`
+// is the reverse: every subcommand except these. `test(args)` is an extra gate on the arguments,
+// `need` means the tool serves only when a port flag or environment variable says where, `scan`
+// reads the port out of the joined arguments (`--args='--server.port=3000'`), `version` lists
+// extra flags that only print a version.
 const TOOLS = [
-  { bin: ['next'], sub: ['dev', 'start'], port: 3000, flags: ['-p', '--port'], env: ['PORT'] },
-  { bin: ['vite'], sub: ['', 'dev', 'serve'], port: 5173, flags: ['--port'] },
-  { bin: ['vite'], sub: ['preview'], port: 4173, flags: ['--port'] },
+  { bin: ['next'], sub: ['dev', 'start'], port: 3000, flags: ['-p', '--port'], env: ['PORT'], version: ['-v'] },
+  { bin: ['vite'], sub: ['preview'], port: 4173, flags: ['--port'], version: ['-v'] },
+  // vite [root] and vite dev|serve start the server; build and optimize do not
+  { bin: ['vite'], notSub: ['build', 'optimize', 'preview'], port: 5173, flags: ['--port'], version: ['-v'] },
   { bin: ['astro'], sub: ['dev', 'preview'], port: 4321, flags: ['--port'] },
   { bin: ['nuxt', 'nuxi'], sub: ['dev'], port: 3000, flags: ['-p', '--port'], env: ['NUXT_PORT', 'PORT'] },
   { bin: ['remix'], sub: ['dev'], port: 3000, flags: ['--port'], env: ['PORT'] },
   { bin: ['remix'], sub: ['vite:dev'], port: 5173, flags: ['--port'] },
   { bin: ['expo'], sub: ['start'], port: 8081, flags: ['-p', '--port'], env: ['RCT_METRO_PORT'] },
+  { bin: ['react-native', 'metro'], sub: ['start', 'serve'], port: 8081, flags: ['--port'], env: ['RCT_METRO_PORT'] },
   { bin: ['uvicorn'], sub: null, port: 8000, flags: ['--port'] },
+  { bin: ['hypercorn'], sub: null, port: 8000, flags: ['-b', '--bind'], arg: n => `--bind :${n}` },
+  { bin: ['gunicorn'], sub: null, port: 8000, flags: ['-b', '--bind'], env: ['PORT'], arg: n => `--bind :${n}` },
+  { bin: ['fastapi'], sub: ['dev', 'run'], port: 8000, flags: ['--port'] },
   { bin: ['flask'], sub: ['run'], port: 5000, flags: ['-p', '--port'], env: ['FLASK_RUN_PORT'] },
   { bin: ['rails'], sub: ['s', 'server'], port: 3000, flags: ['-p', '--port'], env: ['PORT'] },
+  { bin: ['puma'], sub: null, port: 9292, flags: ['-p', '--port', '-b', '--bind'], env: ['PORT'], arg: n => `-p ${n}` },
+  { bin: ['rackup'], sub: null, port: 9292, flags: ['-p', '--port'] },
   { bin: ['gatsby'], sub: ['develop'], port: 8000, flags: ['-p', '--port'] },
-  { bin: ['ng'], sub: ['serve'], port: 4200, flags: ['--port'] },
+  { bin: ['gatsby'], sub: ['serve'], port: 9000, flags: ['-p', '--port'] },
+  { bin: ['ng', 'nx', 'ember'], sub: ['serve', 's'], port: 4200, flags: ['--port'] },
   { bin: ['webpack'], sub: ['serve'], port: 8080, flags: ['--port'] },
   { bin: ['webpack-dev-server'], sub: null, port: 8080, flags: ['--port'] },
+  { bin: ['vue-cli-service'], sub: ['serve'], port: 8080, flags: ['--port'] },
+  { bin: ['rspack'], sub: ['serve', 'dev', 's'], port: 8080, flags: ['--port'] },
+  { bin: ['rsbuild'], sub: ['dev'], port: 3000, flags: ['--port'] },
+  { bin: ['react-scripts', 'craco'], sub: ['start'], port: 3000, flags: [], env: ['PORT'] },
+  { bin: ['parcel'], notSub: ['build', 'watch'], port: 1234, flags: ['-p', '--port'] },
   { bin: ['hugo'], sub: ['server', 'serve'], port: 1313, flags: ['-p', '--port'] },
   { bin: ['jekyll'], sub: ['serve', 's'], port: 4000, flags: ['-P', '--port'] },
+  { bin: ['hexo'], sub: ['server', 's'], port: 4000, flags: ['-p', '--port'] },
+  { bin: ['zola'], sub: ['serve'], port: 1111, flags: ['-p', '--port'] },
+  { bin: ['mdbook'], sub: ['serve'], port: 3000, flags: ['-p', '--port'] },
+  { bin: ['mkdocs'], sub: ['serve'], port: 8000, flags: ['-a', '--dev-addr'], arg: n => `-a localhost:${n}` },
+  { bin: ['trunk'], sub: ['serve'], port: 8080, flags: ['--port'] },
+  { bin: ['eleventy', '11ty'], sub: null, port: 8080, flags: ['--port'], test: a => a.includes('--serve') },
+  { bin: ['vuepress', 'vuepress-vite', 'vuepress-webpack'], sub: ['dev'], port: 8080, flags: ['-p', '--port'] },
+  { bin: ['vitepress'], sub: ['dev'], port: 5173, flags: ['--port'] },
+  { bin: ['vitepress'], sub: ['preview', 'serve'], port: 4173, flags: ['--port'] },
   { bin: ['storybook'], sub: ['dev'], port: 6006, flags: ['-p', '--port'] },
   { bin: ['wrangler'], sub: ['dev'], port: 8787, flags: ['--port'] },
+  { bin: ['netlify'], sub: ['dev'], port: 8888, flags: ['-p', '--port'] },
+  { bin: ['vercel', 'vc'], sub: ['dev'], port: 3000, flags: ['-l', '--listen'] },
   { bin: ['docusaurus'], sub: ['start'], port: 3000, flags: ['-p', '--port'] },
-  { bin: ['http-server'], sub: null, port: 8080, flags: ['-p', '--port'] },
+  { bin: ['http-server'], sub: null, port: 8080, flags: ['-p', '--port'], env: ['PORT'] },
+  { bin: ['live-server'], sub: null, port: 8080, flags: ['--port'], env: ['PORT'] },
+  { bin: ['serve'], sub: null, port: 3000, flags: ['-l', '--listen', '-p'], arg: n => `-l ${n}` },
+  { bin: ['json-server'], sub: null, port: 3000, flags: ['-p', '--port'], env: ['PORT'] },
+  { bin: ['lite-server'], sub: null, port: 3000, flags: ['--port'] },
+  { bin: ['browser-sync'], sub: null, port: 3000, flags: ['-p', '--port'] },
+  { bin: ['streamlit'], sub: ['run'], port: 8501, flags: ['--server.port'], env: ['STREAMLIT_SERVER_PORT'] },
+  { bin: ['jupyter'], sub: ['notebook', 'lab', 'server', 'nbclassic'], port: 8888, flags: ['--port', '--NotebookApp.port', '--ServerApp.port'], arg: n => `--port ${n}` },
+  { bin: ['jupyter-lab', 'jupyter-notebook'], sub: null, port: 8888, flags: ['--port', '--NotebookApp.port', '--ServerApp.port'], arg: n => `--port ${n}` },
+  { bin: ['mix'], sub: ['phx.server'], port: 4000, flags: [], env: ['PORT'] },
+  // Spring Boot: 8080 unless a server.port says otherwise
+  { bin: ['gradle', 'gradlew'], sub: null, port: 8080, flags: ['--server.port', '-Dserver.port'], env: ['SERVER_PORT'], scan: /server\.port[=\s]+(\d+)/, arg: n => `--args='--server.port=${n}'`, test: a => a.includes('bootRun') },
+  { bin: ['mvn', 'mvnw'], sub: null, port: 8080, flags: ['--server.port', '-Dserver.port'], env: ['SERVER_PORT'], scan: /server\.port[=\s]+(\d+)/, arg: n => `-Dspring-boot.run.arguments=--server.port=${n}`, test: a => a.includes('spring-boot:run') },
+  // these serve only where an explicit port says so: php -S host:port, java -jar app.jar --server.port=N, dotnet run --urls ...
+  { bin: ['php'], sub: null, flags: ['-S'], need: true, arg: n => `-S localhost:${n}` },
+  { bin: ['ruby'], sub: null, port: 8080, flags: ['-p'], test: a => a.includes('-run') && a.some(x => /^(?:-e)?httpd\b/.test(x)) },
+  { bin: ['java'], sub: null, flags: ['--server.port', '-Dserver.port', '--port'], env: ['SERVER_PORT', 'PORT'], need: true, arg: n => `--server.port=${n}`, test: a => a.includes('-jar') },
+  { bin: ['dotnet'], sub: ['run', 'watch'], flags: ['--urls'], env: ['ASPNETCORE_HTTP_PORTS'], need: true, arg: n => `--urls http://localhost:${n}` },
   // positional ports
   { bin: ['http.server'], sub: null, port: 8000, positional: /^(\d+)$/ },
-  { bin: ['manage.py'], sub: ['runserver'], port: 8000, positional: /^(?:[\w.[\]]*:)?(\d+)$/ },
+  { bin: ['manage.py', 'django-admin', 'django'], sub: ['runserver', 'runserver_plus'], port: 8000, positional: /^(?:[\w.[\]]*:)?(\d+)$/ },
   { bin: ['artisan'], sub: ['serve'], port: 8000, flags: ['--port'] },
 ]
 
-const WRAPPERS = new Set(['npx', 'bunx', 'pnpx', 'nohup', 'exec', 'time', 'env', 'cross-env', 'dotenv', 'sudo', 'nice'])
+// Programs that run a file and read the port from PORT; the port must be named in the command.
+const RUNTIMES = [
+  { bin: /^(?:node|nodemon|tsx|ts-node|bun|deno)$/, ok: a => a.some(x => !x.startsWith('-') && /\.(?:[cm]?[jt]sx?)$/.test(x)) },
+  { bin: /^(?:python[\d.]*|py)$/, ok: a => a.some(x => !x.startsWith('-') && /\.py$/.test(x)) },
+  { bin: /^ruby$/, ok: a => a.some(x => !x.startsWith('-') && /\.rb$/.test(x)) },
+  { bin: /^go$/, ok: a => a[0] === 'run' },
+  { bin: /^cargo$/, ok: a => /^(?:run|watch)$/.test(a[0]) },
+]
+
 const RUNNERS = new Set(['npm', 'pnpm', 'yarn', 'bun'])
+const OPT_WITH_VALUE = /^(?:--prefix|-C|--cwd|--dir|--filter|-F|--workspace|-w|--workspace-root)$/
+
+// A token after which the wrapped command starts, for each wrapper: how many tokens it takes.
+// `skipFlags` passes options, the ones in `valued` also take the next token.
+const skipFlags = (t, i, valued = []) => {
+  while (i < t.length && /^-/.test(t[i]) && t[i] !== '--') i += valued.includes(t[i]) ? 2 : 1
+  return t[i] === '--' ? i + 1 : i
+}
+const afterDashes = (t, i) => {
+  const j = t.indexOf('--', i)
+  return j >= 0 ? j + 1 : -1
+}
+const PKG_FLAGS = ['-p', '--package', '-c', '--call', '-w', '--workspace', '--prefix', '--registry', '--node-options']
+const WRAPPERS = {
+  npx: (t, i) => skipFlags(t, i + 1, PKG_FLAGS),
+  bunx: (t, i) => skipFlags(t, i + 1, PKG_FLAGS),
+  pnpx: (t, i) => skipFlags(t, i + 1, PKG_FLAGS),
+  uvx: (t, i) => skipFlags(t, i + 1, ['--from', '--with', '-p', '--python']),
+  nohup: (t, i) => i + 1,
+  exec: (t, i) => skipFlags(t, i + 1, ['-a']),
+  time: (t, i) => skipFlags(t, i + 1, ['-f', '-o', '--format', '--output']),
+  command: (t, i) => i + 1,
+  builtin: (t, i) => i + 1,
+  setsid: (t, i) => skipFlags(t, i + 1),
+  nice: (t, i) => skipFlags(t, i + 1, ['-n', '--adjustment']),
+  ionice: (t, i) => skipFlags(t, i + 1, ['-c', '-n', '-p']),
+  stdbuf: (t, i) => skipFlags(t, i + 1),
+  unbuffer: (t, i) => skipFlags(t, i + 1),
+  caffeinate: (t, i) => skipFlags(t, i + 1, ['-t', '-w']),
+  sudo: (t, i) => skipFlags(t, i + 1, ['-u', '-g', '-h', '-p', '-C', '-D', '-R', '-T', '-U']),
+  doas: (t, i) => skipFlags(t, i + 1, ['-u', '-C']),
+  env: (t, i) => skipFlags(t, i + 1, ['-u', '-C', '-S', '-P']),
+  'cross-env': (t, i) => skipFlags(t, i + 1),
+  'env-cmd': (t, i) => {
+    const d = afterDashes(t, i + 1)
+    return d >= 0 ? d : skipFlags(t, i + 1, ['-f', '-e', '-r', '--file', '--environments', '--rc-file'])
+  },
+  dotenv: (t, i) => {
+    const d = afterDashes(t, i + 1)
+    return d >= 0 ? d : skipFlags(t, i + 1, ['-e', '-p', '-v', '-c'])
+  },
+  dotenvx: (t, i) => {
+    const d = t[i + 1] === 'run' ? afterDashes(t, i + 2) : -1
+    return d >= 0 ? d : i + 1
+  },
+  timeout: (t, i) => {
+    let j = skipFlags(t, i + 1, ['-s', '--signal', '-k', '--kill-after'])
+    if (/^\d+(?:\.\d+)?[smhd]?$/.test(t[j] || '')) j++
+    return j
+  },
+}
+// `<tool> <verb>` wrappers: npm exec, pnpm dlx, uv run, bundle exec, poetry run ...
+const SUBWRAPPERS = {
+  npm: /^(?:exec|x)$/,
+  pnpm: /^(?:exec|dlx)$/,
+  yarn: /^(?:exec|dlx)$/,
+  bun: /^x$/,
+  bundle: /^exec$/,
+  uv: /^run$/,
+  poetry: /^run$/,
+  pipenv: /^run$/,
+  pdm: /^run$/,
+  rye: /^run$/,
+  hatch: /^run$/,
+  pixi: /^run$/,
+  pipx: /^run$/,
+  mise: /^(?:exec|x)$/,
+  conda: /^run$/,
+  direnv: /^exec$/,
+}
 
-// Words of one segment. Grouping parentheses and braces, `( npm run dev )`, are not words.
-function tokens(s) {
-  return [...s.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map(m => m[1] ?? m[2] ?? m[3]).filter(t => !/^[(){}]$/.test(t))
+// Words of one command without the keyword in front (`do npm run dev`) and without redirections.
+function cleanWords(words, out = []) {
+  let i = 0
+  while (i < words.length && /^(?:do|then|else|elif|if|while|until|\{|!)$/.test(words[i])) i++
+  for (; i < words.length; i++) {
+    const w = words[i]
+    if (/^\d*(?:>>?|<)$/.test(w)) { i++; continue }
+    if (/^\d*[<>]/.test(w)) continue
+    out.push(w)
+  }
+  return out
 }
 
-function segments(cmd) {
-  return cmd.replace(/\d?>&\d/g, ' ').split(/\n|;|&&|\|\||\||&/).map(s => s.trim()).filter(Boolean)
+// Every simple command in text order, each as its words. Quotes are respected, so
+// grep -E "next dev|vite" is one command with a pattern, not two servers.
+function commandsOf(cmd) {
+  const { cmds } = shell.lex(String(cmd || ''))
+  return cmds.slice().sort((a, b) => a.s - b.s).map(c => cleanWords(c.words.map(w => w.v))).filter(t => t.length)
 }
 
 const binName = t => path.basename(String(t)).replace(/\.(?:cmd|exe|ps1)$/i, '').toLowerCase()
@@ -65,14 +201,18 @@ function takeEnv(t, env) {
   }
 }
 
-// Index of the real command after npx, nohup, python -m and similar.
-function commandStart(t) {
+// Index of the real command after npx, nohup, timeout 60, cross-env PORT=1, python -m and similar.
+// NAME=value words on the way are added to env.
+function commandStart(t, env) {
   let i = 0
   while (i < t.length) {
     const b = binName(t[i])
-    if (WRAPPERS.has(b) || /^-(?:y|-yes)$/.test(t[i]) || /^\w+=/.test(t[i])) i++
-    else if ((b === 'pnpm' || b === 'yarn' || b === 'npm') && /^(?:exec|dlx)$/.test(t[i + 1])) i += 2
-    else if (b === 'bundle' && t[i + 1] === 'exec') i += 2
+    const kv = /^(\w+)=(.*)$/.exec(t[i])
+    if (kv) { env[kv[1].toUpperCase()] = kv[2]; i++ } else if (Object.hasOwn(WRAPPERS, b)) {
+      const j = WRAPPERS[b](t, i)
+      if (!(j > i)) break
+      i = j
+    } else if (Object.hasOwn(SUBWRAPPERS, b) && SUBWRAPPERS[b].test(t[i + 1] || '')) i = skipFlags(t, i + 2, PKG_FLAGS.concat(['--with', '--python', '--from']))
     else if (/^python[\d.]*$|^py$/.test(b) && t[i + 1] === '-m') i += 2
     else if (/^python[\d.]*$|^py$|^php$/.test(b) && /^(?:manage\.py|artisan)$/.test(binName(t[i + 1] || ''))) i += 1
     else break
@@ -80,13 +220,24 @@ function commandStart(t) {
   return i
 }
 
+// The port in a flag value: 3000, :3000, 0.0.0.0:3000, tcp://0.0.0.0:3000, http://localhost:3000;https://x:3001
+function portOf(v) {
+  const s = String(v)
+  if (/^\d+$/.test(s)) return Number(s)
+  const m = /^(?:[\w+.-]+:\/\/)?[^/\s;,]*:(\d+)/.exec(s)
+  return m ? Number(m[1]) : null
+}
+
 // The last port flag wins, as in `npm run dev -- -p 3001` over a script's `next dev -p 3000`.
 function flagPort(args, flags = []) {
   let port
   for (let i = 0; i < args.length; i++) {
     for (const f of flags) {
-      const v = args[i] === f ? args[i + 1] : args[i].startsWith(f + '=') ? args[i].slice(f.length + 1) : undefined
-      if (v !== undefined) port = /^\d+$/.test(v) ? Number(v) : null
+      let v
+      if (args[i] === f) v = args[i + 1]
+      else if (args[i].startsWith(f + '=')) v = args[i].slice(f.length + 1)
+      else if (/^-[a-zA-Z]$/.test(f) && args[i].startsWith(f) && /^\d+$/.test(args[i].slice(2))) v = args[i].slice(2)
+      if (v !== undefined) port = portOf(v)
     }
   }
   return port
@@ -99,36 +250,60 @@ function toolPort(tool, args, env) {
   }
   const flag = flagPort(args, tool.flags)
   if (flag !== undefined) return flag
+  if (tool.scan) {
+    const m = tool.scan.exec(args.join(' '))
+    if (m) return Number(m[1])
+  }
   for (const name of tool.env || []) {
-    if (env[name] !== undefined) return /^\d+$/.test(env[name]) ? Number(env[name]) : null
+    if (env[name] !== undefined) return portOf(env[name])
   }
   return tool.port
 }
 
+const INFO_FLAGS = new Set(['--help', '-h', '--version'])
+
 function matchTool(t, env) {
   const bin = binName(t[0] || '')
   const sub = t[1] && !t[1].startsWith('-') ? t[1] : ''
   for (const tool of TOOLS) {
     if (!tool.bin.includes(bin)) continue
     if (tool.sub && !tool.sub.includes(sub)) continue
-    const argsAt = tool.sub && sub ? 2 : 1
-    return { tool, argsAt, port: toolPort(tool, t.slice(argsAt), env) }
+    if (tool.notSub && tool.notSub.includes(sub)) continue
+    const args = t.slice(1)
+    if (args.some(a => INFO_FLAGS.has(a) || (tool.version || []).includes(a))) continue
+    if (tool.test && !tool.test(args)) continue
+    const argsAt = sub && tool.sub && tool.sub.includes(sub) ? 2 : 1
+    const port = toolPort(tool, t.slice(argsAt), env)
+    if (tool.need && port === undefined) continue
+    return { tool, argsAt, port }
   }
   return null
 }
 
-// npm run dev, npm start, pnpm dev, yarn dev, bun run dev -> { runner, script, extra }
+// npm run dev, npm start, pnpm dev, yarn dev, bun run dev -> { runner, script, extra, at, workspace }
 function scriptCall(t) {
   const runner = binName(t[0] || '')
   if (!RUNNERS.has(runner)) return null
   let i = 1
-  while (/^-/.test(t[i] || '')) i += /^(?:--prefix|-C|--cwd|--dir)$/.test(t[i]) ? 2 : 1
+  let workspace
+  while (/^-/.test(t[i] || '')) {
+    if (/^(?:--filter|-F|--workspace|-w)$/.test(t[i])) workspace = t[i + 1]
+    else if (/^--(?:filter|workspace)=/.test(t[i])) workspace = t[i].split('=')[1]
+    i += OPT_WITH_VALUE.test(t[i]) ? 2 : 1
+  }
   let script = t[i]
+  if (runner === 'yarn' && script === 'workspace') { workspace = t[i + 1]; i += 2; script = t[i] }
   if (script === 'run' || script === 'run-script') script = t[++i]
   else if (runner === 'npm' && script !== 'start') return null
   if (!script || script === 'install' || script === 'test') return null
-  const extra = t.slice(i + 1).filter(a => a !== '--')
-  return { runner, script, extra }
+  const extra = []
+  const after = t.slice(i + 1)
+  for (let k = 0; k < after.length; k++) {
+    if (/^(?:--workspace|-w|--filter|-F)$/.test(after[k]) && after[k + 1]) { workspace = after[++k]; continue }
+    if (/^--(?:workspace|filter)=/.test(after[k])) { workspace = after[k].split('=')[1]; continue }
+    if (after[k] !== '--') extra.push(after[k])
+  }
+  return { runner, script, extra, at: i, workspace }
 }
 
 function prefixDir(t, dir) {
@@ -137,6 +312,7 @@ function prefixDir(t, dir) {
 }
 
 function resolveDir(dir, to) {
+  if (/^~(?:\/|$)/.test(to)) to = path.join(os.homedir(), to.slice(1))
   const win = /^\/([a-z])(?:\/|$)/i.exec(to)
   const target = process.platform === 'win32' && win ? `${win[1]}:/${to.slice(3)}` : to
   return path.resolve(dir || '.', target)
@@ -150,69 +326,193 @@ function readScripts(dir, readFile) {
   }
 }
 
+// `pnpm --filter web dev` runs web's package.json: look in the usual workspace folders.
+function workspaceDir(dir, name, readFile) {
+  const leaf = String(name).split('/').pop()
+  for (const d of [`apps/${leaf}`, `packages/${leaf}`, `services/${leaf}`, leaf]) {
+    const full = path.resolve(dir, d)
+    try {
+      readFile(path.resolve(full, 'package.json'), 'utf8')
+      return full
+    } catch { /* not this one */ }
+  }
+  return dir
+}
+
+const quote = a => (/[\s"]/.test(a) ? `'${a}'` : a)
+
 // Returns null when no known dev server starts, otherwise { port, portArg, hint } where port
 // is null when it cannot be worked out and hint(n) shows how to start the same thing on port n.
+// ports lists every port the command publishes when there is more than one (docker run -p ...).
 function detect(cmd, { cwd = process.cwd(), readFile = fs.readFileSync, depth = 0, env = {} } = {}) {
   env = { ...env }
   let dir = cwd
-  for (const seg of segments(String(cmd || ''))) {
-    let t = tokens(seg)
+  let unknown = null
+  for (let t of commandsOf(cmd)) {
     t = t.slice(takeEnv(t, env))
     if (!t.length) continue
     if (/^(?:cd|pushd|Set-Location|sl)$/i.test(t[0])) {
-      const to = t.slice(1).find(a => !/^[/-]d$/i.test(a))
+      const to = t.slice(1).find(a => !/^[/-]d$/i.test(a) && a !== '--')
       if (to) dir = resolveDir(dir, to)
       continue
     }
-    const skip = commandStart(t)
-    const hit = matchTool(t.slice(skip), env)
-    if (hit) {
-      const flags = hit.tool.flags || []
-      const portArg = n => (flags.length ? `${flags[flags.length - 1]} ${n}` : String(n))
-      const kept = withoutPort(t, skip + hit.argsAt, hit.tool)
-      return { port: hit.port, portArg, hint: n => [...kept.map(quote), portArg(n)].join(' ') }
-    }
-    const call = scriptCall(t.slice(skip))
-    if (!call) {
-      // PORT=3000 node server.js: a script that reads PORT from the environment
-      const direct = envPortServer(t.slice(skip), env)
-      if (direct) return direct
-      continue
-    }
-    if (depth > 2) continue
-    const runDir = prefixDir(t.slice(skip), dir)
-    const body = readScripts(runDir, readFile)[call.script]
-    if (!body) continue
-    const inner = detect([body, ...call.extra].join(' '), { cwd: runDir, readFile, depth: depth + 1, env })
-    if (!inner) continue
-    if (inner.viaEnv && !SERVER_SCRIPT.test(call.script)) continue
-    if (inner.viaEnv) return { port: inner.port, viaEnv: true, portArg: inner.portArg, hint: n => `PORT=${n} ${call.runner} run ${call.script}` }
-    return { port: inner.port, portArg: inner.portArg, hint: n => `${call.runner} run ${call.script} -- ${inner.portArg(n)}` }
+    const skip = commandStart(t, env)
+    const rest = t.slice(skip)
+    const hit = serverHit(t, skip, env) || containerHit(rest, dir, readFile) || scriptHit(t, skip, { dir, readFile, depth, env }) || envPortServer(rest, env)
+    if (!hit) continue
+    if (hit.port) return hit
+    unknown = unknown || hit
   }
-  return null
+  return unknown
+}
+
+function serverHit(t, skip, env) {
+  const hit = matchTool(t.slice(skip), env)
+  if (!hit) return null
+  const { tool } = hit
+  const flags = tool.flags || []
+  const kept = withoutPort(t, skip + hit.argsAt, tool).map(quote)
+  // tools that read the port from the environment only: PORT=n next to the command
+  if (!tool.arg && !flags.length && tool.env) {
+    const portArg = n => `${tool.env[0]}=${n}`
+    return { port: hit.port, portArg, hint: n => [portArg(n), ...kept].join(' ') }
+  }
+  const portArg = tool.arg || (n => (flags.length ? `${flags[flags.length - 1]} ${n}` : String(n)))
+  return { port: hit.port, portArg, hint: n => [...kept, portArg(n)].join(' ') }
+}
+
+function scriptHit(t, skip, { dir, readFile, depth, env }) {
+  const rest = t.slice(skip)
+  const call = scriptCall(rest)
+  if (!call) return null
+  if (depth > 2) return null
+  let runDir = prefixDir(rest, dir)
+  if (call.workspace) runDir = workspaceDir(runDir, call.workspace, readFile)
+  const body = readScripts(runDir, readFile)[call.script]
+  if (!body) {
+    // pnpm vite, yarn next dev, bun vite: no script of that name, so it is a program
+    return call.runner === 'npm' ? null : serverHit(t, skip + call.at, env)
+  }
+  const inner = detect([body, ...call.extra].join(' '), { cwd: runDir, readFile, depth: depth + 1, env })
+  if (!inner) return null
+  if (inner.viaEnv && !SERVER_SCRIPT.test(call.script)) return null
+  if (inner.viaEnv) return { port: inner.port, viaEnv: true, portArg: inner.portArg, hint: n => `PORT=${n} ${call.runner} run ${call.script}` }
+  return { port: inner.port, portArg: inner.portArg, hint: n => `${call.runner} run ${call.script} -- ${inner.portArg(n)}` }
 }
 
 const SERVER_SCRIPT = /^(?:start|dev|serve|server|develop|watch|(?:start|dev|serve):[\w:-]+)$/i
 const envPort = env => (/^\d+$/.test(env.PORT || '') && Number(env.PORT) > 0 && Number(env.PORT) < 65536 ? Number(env.PORT) : null)
 
-// node, nodemon, tsx, ts-node, bun or deno running a file, with PORT set in the command.
+// A program running a file with PORT set in the command: node server.js, go run ., python app.py, cargo run.
 function envPortServer(t, env) {
   const bin = binName(t[0] || '')
   const port = envPort(env)
-  if (port == null || !/^(?:node|nodemon|tsx|ts-node|bun|deno)$/.test(bin)) return null
-  if (!t.slice(1).some(a => !a.startsWith('-') && /\.(?:[cm]?[jt]s)$/.test(a))) return null
+  if (port == null) return null
+  const rt = RUNTIMES.find(r => r.bin.test(bin))
+  if (!rt || !rt.ok(t.slice(1))) return null
   return { port, viaEnv: true, portArg: n => `PORT=${n}`, hint: n => `PORT=${n} ${t.map(quote).join(' ')}` }
 }
 
-const quote = a => (/[\s"]/.test(a) ? `'${a}'` : a)
+// docker run -p 3000:3000 image, docker compose up (ports from the compose file in the directory)
+function containerHit(t, dir, readFile) {
+  const bin = binName(t[0] || '')
+  if (!/^(?:docker|podman|nerdctl|docker-compose|podman-compose)$/.test(bin)) return null
+  const verb = containerVerb(t, bin)
+  if (/^(?:run|container run)$/.test(verb)) {
+    const hosts = publishedPorts(t)
+    if (!hosts.length) return null
+    const ports = hosts.map(h => h.port)
+    return { port: ports[0], ports, portArg: String, hint: n => hostHint(t, hosts[0], n) }
+  }
+  if (!/^(?:compose up|up)$/.test(verb)) return null
+  for (const f of composeFiles(t, dir)) {
+    let text
+    try { text = readFile(f, 'utf8') } catch { continue }
+    const ports = composePorts(String(text))
+    if (ports.length) return { port: ports[0], ports, portArg: String, hint: n => `${t.join(' ')} (publish ${n} instead of ${ports[0]} in ${path.basename(f)})` }
+  }
+  return null
+}
+
+// "run", "container run", "compose up" or "up": the words after the global options.
+function containerVerb(t, bin) {
+  const words = []
+  for (let i = 1; i < t.length && words.length < 2; i++) {
+    if (/^(?:-f|--file|-H|--host|--context|--project-name|--project-directory|--profile|--env-file)$/.test(t[i]) || (t[i] === '-p' && bin !== 'docker')) i++
+    else if (!t[i].startsWith('-')) words.push(t[i])
+    if (words[0] === 'run' || words[0] === 'up') break
+  }
+  return words.join(' ')
+}
+
+function composeFiles(t, dir) {
+  const files = []
+  for (let i = 0; i < t.length; i++) {
+    if (t[i] === '-f' || t[i] === '--file') files.push(path.resolve(dir, t[i + 1] || ''))
+    else if (/^--file=/.test(t[i])) files.push(path.resolve(dir, t[i].slice(7)))
+  }
+  if (files.length) return files
+  return ['compose.yaml', 'compose.yml', 'docker-compose.yml', 'docker-compose.yaml'].map(n => path.resolve(dir, n))
+}
+
+// Host ports of every -p/--publish option: 3000:3000, 127.0.0.1:3000:80/tcp, 8000-8010:8000-8010.
+function publishedPorts(t) {
+  const out = []
+  for (let i = 0; i < t.length; i++) {
+    const m = /^(?:-p|--publish)(?:=(.*))?$/.exec(t[i]) || /^-p(\d[^\s]*)$/.exec(t[i])
+    if (!m) continue
+    const spec = m[1] !== undefined ? m[1] : t[i + 1]
+    const port = hostPort(spec)
+    if (port) out.push({ port, spec, at: i, inline: m[1] !== undefined })
+  }
+  return out
+}
+
+function hostPort(spec) {
+  const parts = String(spec || '').replace(/\/(?:tcp|udp|sctp)$/i, '').split(':')
+  if (parts.length < 2) return null
+  const host = parts[parts.length - 2]
+  const m = /^(\d+)(?:-\d+)?$/.exec(host)
+  return m && Number(m[1]) > 0 && Number(m[1]) < 65536 ? Number(m[1]) : null
+}
+
+function hostHint(t, h, n) {
+  const parts = h.spec.split(':')
+  parts[parts.length - 2] = String(n)
+  const spec = parts.join(':')
+  const out = t.slice()
+  if (h.inline) out[h.at] = out[h.at].replace(h.spec, spec)
+  else out[h.at + 1] = spec
+  return out.map(quote).join(' ')
+}
+
+// The host ports in a compose file's `ports:` lists, read line by line so a missing YAML parser costs nothing.
+function composePorts(text) {
+  const ports = []
+  let indent = -1
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/\s+#.*$/, '')
+    if (!line.trim()) continue
+    const at = line.length - line.trimStart().length
+    if (/^\s*ports:\s*$/.test(line)) { indent = at; continue }
+    if (indent < 0) continue
+    if (at <= indent && !line.trim().startsWith('-')) { indent = -1; continue }
+    const item = line.trim().replace(/^-\s*/, '').replace(/\$\{[^}:]*:?-(\d+)\}/g, '$1')
+    const pub = /^(?:published|host_port):\s*["']?(\d+)/.exec(item)
+    const short = /^["']?([\d.:[\]a-fA-F-]+(?:\/\w+)?)["']?$/.exec(item)
+    const p = pub ? Number(pub[1]) : short ? hostPort(short[1]) : null
+    if (p) ports.push(p)
+  }
+  return ports
+}
 
 // The command as typed, minus redirections and any port it already names.
 function withoutPort(t, argsAt, tool) {
   const out = t.slice(0, argsAt)
   for (let i = argsAt; i < t.length; i++) {
     const a = t[i]
-    if (/^\d?>/.test(a)) { if (/^\d?>>?$/.test(a)) i++; continue }
     if (tool.positional && tool.positional.test(a)) continue
+    if (tool.scan && tool.scan.test(a)) continue
     const flag = (tool.flags || []).find(f => a === f || a.startsWith(f + '='))
     if (flag) { if (a === flag) i++; continue }
     out.push(a)
@@ -220,4 +520,4 @@ function withoutPort(t, argsAt, tool) {
   return out
 }
 
-module.exports = { detect, tokens, segments, TOOLS }
+module.exports = { detect, commandsOf, TOOLS, portOf, composePorts }

package/src/disk-guard.js

@@ -188,13 +188,13 @@ function parallelMessage(cmd, how) {
     'Run one du at a time, in the foreground: du -sh <one folder>.'
 }
 
-if (require.main === module) {
-  runHook('disk-guard', input => {
-    const cmd = input.tool_input && input.tool_input.command
-    const hit = check(cmd, { mode: shell.modeFor(input) })
-    if (!hit) return
-    return blocked('disk-guard', hit.rule, input, `${hit.why}\n${ASK_USER}`)
-  })
+function handle(input) {
+  const cmd = input.tool_input && input.tool_input.command
+  const hit = check(cmd, { mode: shell.modeFor(input) })
+  if (!hit) return
+  return blocked('disk-guard', hit.rule, input, `${hit.why}\n${ASK_USER}`)
 }
 
-module.exports = { check, wholeDisk, isScan }
+if (require.main === module) runHook('disk-guard', handle)
+
+module.exports = { handle, check, wholeDisk, isScan }