[zumbrunn]

Fixes #46

Why

Found while cleaning up a machine running ~45 dune processes: dune ps listed 19 of them as "port unknown — is lsof installed?" and missed the one server that was actually serving (started through the dune shim as cli.ts dev).

dune ps (read-only)

• Matching. Besides the generated main.ts dev|serve, it now matches the dune CLI run directly (cli.ts dev|serve via the global shim or a checkout, jsr:@dune/core@x/cli serve) and deno task dev|serve wrappers. A bare cli.ts or deno task could be any project, so those are weak matches that count only when a config/site.yaml is found via --root, PWD or the live cwd.
• One instance per process tree. A server's wrapper, re-exec child and esbuild workers are grouped under the topmost matching process from a single ps -eo pid,ppid,uid,lstart,... snapshot (drops pgrep). Only the current user's processes are considered. --root is used to find the site; the command line is shown.
• "Not listening" instead of a misleading hint: listening / not-listening (lsof ran, found nothing) / unknown (lsof can't be spawned).
• Confirmed vs. unconfirmed. An instance is confirmed when its own command line points at a dune site: the directory of the main.ts it runs, its --root, or (for the dune CLI proper) its working directory, each holding a config/site.yaml. Merely running from inside a site directory confirms nothing, since any tool started from a site repo inherits that. A command line that only looks like dune (any Deno project's main.ts serve, a path containing "dune") is still listed but marked unconfirmed. (feat(cli): dune ps probes health and reads the instance registry #53 adds the instance registry as a second source of confirmation.)

dune stop (new)

Stopping used to be flags on ps; it is its own command now, so ps never prompts or signals anything.

dune stop <pid>        the instance that process belongs to (top process or any child)
dune stop --port <n>   the instance listening on that port
dune stop --idle       confirmed instances running but not listening for >= 2 minutes
dune stop --all        every confirmed instance dune ps lists
        [--force]      SIGKILL what ignores SIGTERM after 10 s
        [--yes, -y]    skip the confirmation

• A target is required. A bare dune stop prints usage and exits 2; two targets together is also a usage error.
• Only what it can verify. --all and --idle act on confirmed instances only; an unconfirmed one must be named by pid (with a warning), and the prompt shows every instance's full command line. Only your own processes are touched (our uid is read from our own row in the process table, so no --allow-sys). A signal the OS refuses is reported as "not permitted (owned by another user)"; one Deno's permissions refuse as "re-run with --allow-run"; a missing --allow-run is reported as such rather than as "no instances".
• No stale-pid kills. Each pid's start time is captured when the instance is found and re-checked right before every SIGTERM and SIGKILL, so a pid that exited and was reused while the prompt was open is never signalled (it is reported as "not signalled").
• Not servers that are still starting. --idle leaves out a not-listening instance younger than 2 minutes (indexing a big site takes a while), and says so.
• SIGTERM by default; a process that ignores it is reported with a hint, and only --force escalates to SIGKILL (which can orphan a wrapper's child). It stops the whole process tree, including any other tool a deno task wrapper started; the usage text says so.
• Asks first; with no terminal and no --yes it refuses. Never signals itself or its ancestors.
• Exit codes: 0 done (or nothing to do for --idle/--all), 1 a named pid/port matches nothing or something would not stop or was refused, 2 usage error.

Code layout

src/cli/instances.ts (discovery, shared), ps.ts (listing), stop.ts (selection, confirmation, signalling). Tests split the same way, with shared fixtures in tests/cli/ps_helpers.ts.

Verification

• deno lint src/, deno check; deno test -A --unstable-kv tests/cli: 404 passed (content_delete_test is a pre-existing flake on main, being fixed separately)
• Real processes: discovery by every launch shape; confirmed vs. unconfirmed (an unrelated main.ts started from inside a site directory is not confirmed; the site's own main.ts started from elsewhere is); dune ps under --allow-run only (no --allow-sys); a kill refused by Deno's permissions reported as needing --allow-run; start times recorded; whole tree stopped; a SIGTERM-ignoring process is left alone without --force and SIGKILLed with it; a mismatching or missing recorded start time means the process is never signalled, even with --force; a refused signal (pid 1, skipped as root) is reported as denied; never signals itself.
• Pure tables for target selection (usage errors, pid by child, --port, --idle with unconfirmed/young/unknown-state instances, --all), and the command flow against injected fakes so no flow test can stop a real instance.
• Real CLI against a live fake-dune server and idle ones: ps lists both; bare stop prints usage; stop --idle with no terminal refuses; stop by pid/port stops only that tree; stop 424242 says no such instance.

Known limits

• Windows isn't supported (needs ps/lsof).
• Version: bumps to 0.34.15 with feat(themes): template output modes — bare fragments, JSON, XML, text #36 and fix(serve): exit explicitly after a graceful shutdown #38 (whichever merges later takes the next number).
• Follow-ups (A blocked event loop takes the whole server down silently: add a watchdog, an instance registry and hang-aware dune ps #42): dune ps probes /health/live and reads the instance registry (feat(cli): dune ps probes health and reads the instance registry #53).

Docs: duneorg/dune-docs#12.

🤖 Generated with Claude Code

[zumbrunn]

Added the selective form I flagged as a follow-up: dune ps --idle (commit 3d6c156).

• dune ps --idle lists only instances that are running but not listening; dune ps --stop --idle stops just those and leaves live servers alone. Plain --stop is unchanged and still stops everything listed.
• An instance whose port state is unknown (no lsof) is never assumed idle: with nothing provably idle, --idle says so and --stop does nothing (exit 1).
• The confirmation names the idle count and process count; with nothing idle it says "No idle instances" instead of prompting.
• Tests are fakes-only (no test can stop a real instance): the listing, --stop --idle handing the stopper only idle instances (not even a live one's child pids), the refusal without --yes/TTY, the nothing-idle and lsof-unavailable cases. Disabling the filter fails 4 of them, including the safety one.
• Run for real: with a live and an idle fixture next to a live server from another session, ps --stop --idle --yes stopped only the idle fixture; the other two stayed up.
• 1900 tests pass; deno task check clean. CHANGELOG, README and the docs PR (docs(cli): dune ps finds the dune CLI and task wrappers, reports "not listening"; new dune stop dune-docs#12) are updated.

[zumbrunn]

Added the SIGKILL escalation (commit follows 3d6c156).

stopInstances() now sends SIGTERM, waits a 10 s grace period (for real servers draining in-flight requests), then SIGKILLs whatever is still alive. The result gains killed (the pids that needed it), so the escalation is never silent; survivors now means "alive even after SIGKILL" and is the only thing that makes the exit code non-zero. It still never signals itself or its ancestors.

Why: a dune serve closed its listener on the first SIGTERM and then stayed alive until sent a second one (root-caused to a ref'd plugin-admin timer, see duneorg/plugin-admin#8 and #38), so plain SIGTERM left exactly the idle processes this command exists to clear.

• A real process that swallows SIGTERM is escalated (died by SIGKILL, reported as killed); a cooperative one is not SIGKILLed; removing the escalation fails the stubborn-process test.
• Reproduced the original situation for real: a serve that got one SIGTERM sat idle, dune ps --idle listed it, and dune ps --stop --idle --yes cleared it while the live iofc server stayed up.
• 1903 tests pass; deno task check clean. CHANGELOG and the docs PR (docs(cli): dune ps finds the dune CLI and task wrappers, reports "not listening"; new dune stop dune-docs#12) are updated.