claude-bulkhead 0.0.0-stage → 0.2.2

package/src/config-check.js

@@ -0,0 +1,29 @@
+'use strict'
+// SessionStart: one notice when a bulkhead config file is broken. The guards ignore a broken
+// file and run on their defaults, so without this nobody would notice a typo.
+const { load } = require('./config')
+const { shortPath } = require('./cli-util')
+
+function notice(cfg) {
+  if (!cfg.warnings.length) return null
+  const lines = cfg.warnings.slice(0, 3).map(w => `  ${w.replace(/^\S+/, m => shortPath(m))}`)
+  if (cfg.warnings.length > 3) lines.push(`  and ${cfg.warnings.length - 3} more`)
+  return `[bulkhead] config problem, defaults are used where it applies:\n${lines.join('\n')}\nRun \`bulkhead config\` or \`bulkhead doctor\` to check.`
+}
+
+if (require.main === module) {
+  let raw = ''
+  process.stdin.setEncoding('utf8')
+  process.stdin.on('data', d => (raw += d))
+  process.stdin.on('end', () => {
+    try {
+      let input = {}
+      try { input = JSON.parse(raw || '{}') } catch {}
+      const msg = notice(load({ cwd: process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd() }))
+      if (msg) process.stdout.write(JSON.stringify({ systemMessage: msg }))
+    } catch {}
+    process.exit(0)
+  })
+}
+
+module.exports = { notice }

package/src/config-cli.js

@@ -0,0 +1,51 @@
+'use strict'
+const fs = require('fs')
+const { load, KEYS } = require('./config')
+const { useColor, paint, shortPath, table, rejectArgs } = require('./cli-util')
+
+function fileState(file, warnings) {
+  if (!file) return 'none found'
+  if (!fs.existsSync(file)) return 'not found'
+  return warnings.some(w => w.startsWith(file) && /not valid JSON/.test(w)) ? 'INVALID, ignored' : 'loaded'
+}
+
+// The remotes map is long; the table shows the names and `bulkhead remote list` the rest.
+const show = (v, key) => (v === null ? 'auto' : key === 'remotes' ? Object.keys(v).join(', ') || 'none' : JSON.stringify(v))
+
+function render(cfg, { color = false, home } = {}) {
+  const out = []
+  out.push(paint(color, 'bold', 'Files (project wins over global, environment wins over both)'))
+  out.push(`  global   ${shortPath(cfg.files.global, home)}  ${fileState(cfg.files.global, cfg.warnings)}`)
+  out.push(`  project  ${cfg.files.project ? shortPath(cfg.files.project, home) : '<repo>/.claude/bulkhead.json'}  ${fileState(cfg.files.project, cfg.warnings)}`)
+  out.push('')
+  const rows = [['KEY', 'VALUE', 'FROM']]
+  for (const key of Object.keys(KEYS)) {
+    const src = cfg.sources[key]
+    rows.push([key, show(cfg.values[key], key), src === 'default' || src.startsWith('env ') ? src : shortPath(src, home)])
+  }
+  const lines = table(rows)
+  out.push(paint(color, 'bold', lines[0]))
+  lines.slice(1).forEach((l, i) => {
+    const key = rows[i + 1][0]
+    out.push(cfg.sources[key] === 'default' ? paint(color, 'gray', l) : l)
+  })
+  if (cfg.warnings.length) {
+    out.push('')
+    for (const w of cfg.warnings) out.push(paint(color, 'yellow', `WARN ${w}`))
+  }
+  return out.join('\n')
+}
+
+function main(args, { env = process.env, stdout = process.stdout } = {}) {
+  if (rejectArgs('config', args, { flags: ['json'], valued: [] }, process.stderr, null)) return
+  const cfg = load({ env })
+  if (args.includes('--json')) {
+    const settings = {}
+    for (const key of Object.keys(KEYS)) settings[key] = { value: cfg.values[key], from: cfg.sources[key] }
+    stdout.write(JSON.stringify({ files: cfg.files, settings, warnings: cfg.warnings }, null, 2) + '\n')
+    return
+  }
+  stdout.write(render(cfg, { color: useColor(stdout, env) }) + '\n')
+}
+
+module.exports = { main, render }

package/src/config.js

@@ -0,0 +1,236 @@
+'use strict'
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { pathKey } = require('./paths')
+
+// Settings come from three places, later ones winning:
+//   1. defaults below
+//   2. <state dir>/config.json                      (global, usually ~/.claude/bulkhead/config.json)
+//   3. <project>/.claude/bulkhead.json              (project, merged over global)
+//   4. environment variables                        (always win)
+// A file that is not valid JSON is ignored as a whole, so the guards keep their defaults.
+
+const GUARDS = {
+  'kill-guard': 'killGuard',
+  'wait-guard': 'waitGuard',
+  'memory-guard': 'memoryGuard',
+  'port-guard': 'portGuard',
+  'checkout-guard': 'checkoutGuard',
+  'disk-guard': 'diskGuard',
+  basics: 'basics',
+  'orphan-reaper': 'orphanReaper',
+}
+// rules that can be turned off one at a time, inside a guard that stays on
+const RULES = {
+  'rm-root': 'basics.rmRoot',
+  'force-push-main': 'basics.forcePushMain',
+  'discard-changes': 'basics.discardChanges',
+  'agent-author': 'basics.agentAuthor',
+  'stage-all': 'checkoutGuard.stageAll',
+  'remove-session-dir': 'checkoutGuard.removeSessionDir',
+}
+
+const bool = (def, doc) => ({ type: 'boolean', default: def, doc })
+const on = g => bool(true, `Turn ${g} on or off.`)
+// In display order: each section's keys together.
+const KEYS = {
+  'killGuard.enabled': on('kill-guard'),
+  'killGuard.allowNames': { type: 'string[]', default: [], doc: 'Program names to take off the shared list, so killing them by name passes.' },
+  'killGuard.extraSharedNames': { type: 'string[]', default: [], doc: 'More program names that must not be killed by name.' },
+  'waitGuard.enabled': on('wait-guard'),
+  'waitGuard.limitSeconds': { type: 'number', default: 180, env: 'BULKHEAD_WAIT_MAX_SEC', doc: 'Longest foreground wait allowed, in seconds.' },
+  'memoryGuard.enabled': on('memory-guard'),
+  'memory.minFreeGb': { type: 'number', default: null, env: 'BULKHEAD_MIN_FREE_GB', doc: 'Free RAM below which memory-guard blocks heavy commands. Default: 3, or 15% of RAM if less.' },
+  'memory.slotFloorGb': { type: 'number', default: null, env: 'BULKHEAD_SLOT_FLOOR_GB', doc: 'RAM bulkhead-slot keeps free when it starts a second job. Default: 5, or 25% of RAM if less.' },
+  'memory.maxCommitPct': { type: 'number', default: 75, env: 'BULKHEAD_MAX_COMMIT_PCT', doc: 'Windows commit charge above which bulkhead-slot holds a second job.' },
+  'portGuard.enabled': on('port-guard'),
+  'portGuard.ignorePorts': { type: 'number[]', default: [], doc: 'Ports port-guard never checks, for starting servers or for kills by port.' },
+  'checkoutGuard.enabled': on('checkout-guard'),
+  'checkoutGuard.stageAll': bool(true, 'Block git add -A, git add . and git commit -a when another live session works in the same tree.'),
+  'checkoutGuard.removeSessionDir': bool(true, 'Block rm -rf and git worktree remove on a folder another live session works in.'),
+  'diskGuard.enabled': on('disk-guard'),
+  'basics.enabled': on('basics'),
+  'basics.protectedBranches': { type: 'string[]', default: ['main', 'master'], doc: 'Branches force-push-main protects.' },
+  'basics.rmRoot': bool(true, 'Block rm -rf at roots, top-level system folders, the home directory, folders directly in it (caches excepted) and folders above the repository.'),
+  'basics.forcePushMain': bool(true, 'Block force-pushes to the protected branches.'),
+  'basics.discardChanges': bool(true, 'Block git reset --hard and git clean -fd that would lose work.'),
+  'basics.agentAuthor': bool(true, 'Block commits authored as Claude or Anthropic (--author, git config user.*, GIT_AUTHOR_*), so the work counts as yours.'),
+  'orphanReaper.enabled': on('orphan-reaper'),
+  'orphanReaper.onSessionEnd': bool(true, 'Also reap right after a session exits, not only when the next session starts.'),
+  'orphanReaper.extraNames': { type: 'string[]', default: [], doc: 'More program names orphan-reaper stops once the session that started them has exited.' },
+  'orphanReaper.keepNames': { type: 'string[]', default: [], doc: 'Program names orphan-reaper never stops, nor anything they started.' },
+  'log.enabled': bool(true, 'Write blocks to events.jsonl. BULKHEAD_NO_LOG=1 turns it off.'),
+  // Global file only (see src/remotes.js for why).
+  'remote.default': { type: 'string', default: null, globalOnly: true, doc: 'The remote bulkhead remote uses when several are configured and --remote is not given.' },
+  remotes: { type: 'remotes', default: {}, globalOnly: true, doc: 'Machines bulkhead remote can run jobs on: { name: { host, shell, dir, copies, maxJobs, minFreeGb, sshOptions } }.' },
+}
+
+function stateDir(env = process.env) {
+  return env.BULKHEAD_STATE_DIR || path.join(os.homedir(), '.claude', 'bulkhead')
+}
+
+function globalFile(env = process.env) {
+  return path.join(stateDir(env), 'config.json')
+}
+
+// <dir>/.claude/bulkhead.json in the project or the nearest folder above it, stopping at the
+// repository root (a .git entry) or the home directory.
+function projectFile(start, { exists = fs.existsSync, home = os.homedir() } = {}) {
+  if (!start) return null
+  let dir = path.resolve(start)
+  // the cwd and the home directory may be spelled differently (a link, C:\Users\RUNNER~1); any case, as before
+  const stop = pathKey(home, 'win32')
+  for (let i = 0; i < 40; i++) {
+    const f = path.join(dir, '.claude', 'bulkhead.json')
+    if (exists(f)) return f
+    if (exists(path.join(dir, '.git')) || pathKey(dir, 'win32') === stop) return null
+    const up = path.dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+  return null
+}
+
+function typeOk(type, v) {
+  if (type === 'boolean') return typeof v === 'boolean'
+  if (type === 'number') return typeof v === 'number' && Number.isFinite(v) && v >= 0
+  if (type === 'string') return typeof v === 'string'
+  if (type === 'string[]') return Array.isArray(v) && v.every(x => typeof x === 'string')
+  if (type === 'number[]') return Array.isArray(v) && v.every(x => Number.isInteger(x) && x > 0 && x < 65536)
+  return false
+}
+
+// Flat { 'section.key': value } from one parsed file, with a warning for every key we do not know
+// or whose value has the wrong type. Bad keys are dropped, good ones kept. `remotes` is a map
+// of its own, checked entry by entry, and kept whole under the key 'remotes'.
+function flatten(obj, file, warnings, scope = 'global') {
+  const out = {}
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    warnings.push(`${file}: expected a JSON object`)
+    return out
+  }
+  for (const [section, body] of Object.entries(obj)) {
+    if (section === '$schema' || section === '//') continue
+    if (section === 'remotes') {
+      if (scope !== 'global') {
+        warnings.push(`${file}: "remotes" can only be set in the global config file; ignored here`)
+        continue
+      }
+      const { remotes, problems } = require('./remotes').normalizeAll(body)
+      for (const p of problems) warnings.push(`${file}: ${p}`)
+      out.remotes = remotes
+      continue
+    }
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      warnings.push(`${file}: "${section}" should be an object`)
+      continue
+    }
+    for (const [k, v] of Object.entries(body)) {
+      const key = `${section}.${k}`
+      const spec = KEYS[key]
+      if (!spec) warnings.push(`${file}: unknown key "${key}"`)
+      else if (spec.globalOnly && scope !== 'global') warnings.push(`${file}: "${key}" can only be set in the global config file; ignored here`)
+      else if (!typeOk(spec.type, v)) warnings.push(`${file}: "${key}" should be ${spec.type}`)
+      else out[key] = v
+    }
+  }
+  return out
+}
+
+function readFile(file, warnings, read = f => fs.readFileSync(f, 'utf8'), scope = 'global') {
+  let text
+  try { text = read(file) } catch { return null }
+  try {
+    return flatten(JSON.parse(text.replace(/^\uFEFF/, '')), file, warnings, scope)
+  } catch (e) {
+    warnings.push(`${file} is not valid JSON (${e.message}); it is ignored until fixed`)
+    return {}
+  }
+}
+
+function envValue(spec, env) {
+  const raw = env[spec.env]
+  if (raw === undefined || raw === '') return undefined
+  if (spec.type === 'number') {
+    const n = Number(raw)
+    return Number.isFinite(n) ? n : undefined
+  }
+  return raw
+}
+
+// Defaults with both files merged over them. Read once per process.
+function fileLayer({ env = process.env, cwd = env.CLAUDE_PROJECT_DIR || process.cwd(), read } = {}) {
+  const warnings = []
+  const values = {}
+  const sources = {}
+  for (const [k, spec] of Object.entries(KEYS)) {
+    values[k] = spec.default
+    sources[k] = 'default'
+  }
+  const files = { global: globalFile(env), project: projectFile(cwd) }
+  for (const [scope, file] of [['global', files.global], ['project', files.project]]) {
+    if (!file) continue
+    const got = readFile(file, warnings, read, scope)
+    if (!got) continue
+    for (const [k, v] of Object.entries(got)) {
+      values[k] = v
+      sources[k] = file
+    }
+  }
+  return { values, sources, files, warnings }
+}
+
+// { values, sources, files, warnings }. sources[key] is 'default', a file path or 'env NAME'.
+function load(opts = {}) {
+  return withEnv(fileLayer(opts), opts.env || process.env)
+}
+
+// Environment variables win over both files. Applied on every call, since tests and the
+// slot CLI change them while running.
+function withEnv(layer, env) {
+  const values = { ...layer.values }
+  const sources = { ...layer.sources }
+  for (const [k, spec] of Object.entries(KEYS)) {
+    const v = spec.env && envValue(spec, env)
+    if (v !== undefined) {
+      values[k] = v
+      sources[k] = `env ${spec.env}`
+    }
+  }
+  if (/^(?:1|true|yes)$/i.test(String(env.BULKHEAD_NO_LOG || '').trim())) {
+    values['log.enabled'] = false
+    sources['log.enabled'] = 'env BULKHEAD_NO_LOG'
+  }
+  const off = (env.BULKHEAD_DISABLE || '').split(/[\s,]+/).filter(Boolean)
+  for (const name of off) {
+    const key = GUARDS[name] ? `${GUARDS[name]}.enabled` : RULES[name]
+    const keys = name === 'all' ? Object.values(GUARDS).map(s => `${s}.enabled`) : key ? [key] : []
+    for (const k of keys) {
+      values[k] = false
+      sources[k] = 'env BULKHEAD_DISABLE'
+    }
+  }
+  return { values, sources, files: layer.files, warnings: layer.warnings }
+}
+
+let cached = null
+function current() {
+  if (!cached) cached = fileLayer()
+  return withEnv(cached, process.env)
+}
+function reset() {
+  cached = null
+}
+
+function get(key, cfg = current()) {
+  return cfg.values[key]
+}
+
+// Whether a guard or a basics rule is on.
+function isEnabled(name, cfg = current()) {
+  const key = GUARDS[name] ? `${GUARDS[name]}.enabled` : RULES[name]
+  return key ? cfg.values[key] !== false : true
+}
+
+module.exports = { load, current, reset, get, isEnabled, projectFile, globalFile, KEYS, GUARDS, RULES, flatten }

package/src/dev-servers.js

@@ -0,0 +1,223 @@
+'use strict'
+const fs = require('fs')
+const path = require('path')
+
+// 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.
+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: ['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: ['uvicorn'], sub: null, 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: ['gatsby'], sub: ['develop'], port: 8000, flags: ['-p', '--port'] },
+  { bin: ['ng'], sub: ['serve'], port: 4200, flags: ['--port'] },
+  { bin: ['webpack'], sub: ['serve'], port: 8080, flags: ['--port'] },
+  { bin: ['webpack-dev-server'], sub: null, port: 8080, flags: ['--port'] },
+  { bin: ['hugo'], sub: ['server', 'serve'], port: 1313, flags: ['-p', '--port'] },
+  { bin: ['jekyll'], sub: ['serve', 's'], port: 4000, flags: ['-P', '--port'] },
+  { bin: ['storybook'], sub: ['dev'], port: 6006, flags: ['-p', '--port'] },
+  { bin: ['wrangler'], sub: ['dev'], port: 8787, flags: ['--port'] },
+  { bin: ['docusaurus'], sub: ['start'], port: 3000, flags: ['-p', '--port'] },
+  { bin: ['http-server'], sub: null, port: 8080, flags: ['-p', '--port'] },
+  // positional ports
+  { bin: ['http.server'], sub: null, port: 8000, positional: /^(\d+)$/ },
+  { bin: ['manage.py'], sub: ['runserver'], 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'])
+const RUNNERS = new Set(['npm', 'pnpm', 'yarn', 'bun'])
+
+// 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))
+}
+
+function segments(cmd) {
+  return cmd.replace(/\d?>&\d/g, ' ').split(/\n|;|&&|\|\||\||&/).map(s => s.trim()).filter(Boolean)
+}
+
+const binName = t => path.basename(String(t)).replace(/\.(?:cmd|exe|ps1)$/i, '').toLowerCase()
+
+// Leading NAME=value pairs, `export NAME=value`, `set NAME=value` and `$env:NAME = value`.
+function takeEnv(t, env) {
+  let i = 0
+  for (;;) {
+    if (/^(?:export|set|env)$/i.test(t[i]) && /^\w+=/.test(t[i + 1] || '')) i++
+    const ps = /^\$env:(\w+)(?:=(.*))?$/i.exec(t[i] || '')
+    if (ps) {
+      if (ps[2] !== undefined && ps[2] !== '') env[ps[1].toUpperCase()] = ps[2]
+      else if (t[i + 1] === '=') { env[ps[1].toUpperCase()] = t[i + 2]; i += 2 }
+      i++
+      continue
+    }
+    const m = /^(\w+)=(.*)$/.exec(t[i] || '')
+    if (!m) return i
+    env[m[1].toUpperCase()] = m[2]
+    i++
+  }
+}
+
+// Index of the real command after npx, nohup, python -m and similar.
+function commandStart(t) {
+  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
+    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
+  }
+  return i
+}
+
+// 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
+    }
+  }
+  return port
+}
+
+function toolPort(tool, args, env) {
+  if (tool.positional) {
+    const hit = args.map(a => tool.positional.exec(a)).find(Boolean)
+    return hit ? Number(hit[1]) : tool.port
+  }
+  const flag = flagPort(args, tool.flags)
+  if (flag !== undefined) return flag
+  for (const name of tool.env || []) {
+    if (env[name] !== undefined) return /^\d+$/.test(env[name]) ? Number(env[name]) : null
+  }
+  return tool.port
+}
+
+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) }
+  }
+  return null
+}
+
+// npm run dev, npm start, pnpm dev, yarn dev, bun run dev -> { runner, script, extra }
+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 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 }
+}
+
+function prefixDir(t, dir) {
+  const i = t.findIndex(a => /^(?:--prefix|-C|--cwd|--dir)$/.test(a))
+  return i > 0 && t[i + 1] ? resolveDir(dir, t[i + 1]) : dir
+}
+
+function resolveDir(dir, to) {
+  const win = /^\/([a-z])(?:\/|$)/i.exec(to)
+  const target = process.platform === 'win32' && win ? `${win[1]}:/${to.slice(3)}` : to
+  return path.resolve(dir || '.', target)
+}
+
+function readScripts(dir, readFile) {
+  try {
+    return JSON.parse(readFile(path.resolve(dir, 'package.json'), 'utf8')).scripts || {}
+  } catch {
+    return {}
+  }
+}
+
+// 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.
+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)
+    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))
+      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)}` }
+  }
+  return null
+}
+
+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.
+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
+  return { port, viaEnv: true, portArg: n => `PORT=${n}`, hint: n => `PORT=${n} ${t.map(quote).join(' ')}` }
+}
+
+const quote = a => (/[\s"]/.test(a) ? `'${a}'` : a)
+
+// 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
+    const flag = (tool.flags || []).find(f => a === f || a.startsWith(f + '='))
+    if (flag) { if (a === flag) i++; continue }
+    out.push(a)
+  }
+  return out
+}
+
+module.exports = { detect, tokens, segments, TOOLS }