feat(cli): auto-update RDE dashboard via npx re-exec on stack dev

[BilalG1]

What & why

Re-running stack dev / hexclave dev now picks up the latest published dashboard without reinstalling the CLI.

In the RDE, the dashboard is a Next.js standalone build bundled into the @hexclave/cli npm tarball — so a dashboard change only reaches a user when they get a newer CLI version. This PR closes that gap for the recommended stack dev flow.

How it works

1. npx self-re-exec — at the top of the dev action, the CLI checks npm for a newer @hexclave/cli. If found, it re-execs npx --yes -p @hexclave/cli@<latest> stack dev <your args> (with a loop guard) and exits with the child's code. The running code — and the dashboard bundled in that tarball — is now the latest; the user's installed devDependency is untouched. npx caches per version, so steady-state runs are fast.

2. Dashboard version handshake (the necessary second half) — stack dev keeps a detached background dashboard alive across runs and reuses it by default, which would otherwise silently defeat the update. The now-latest process compares the running dashboard's version (persisted in dev-env state) against its own and kills + restarts the stale one (SIGTERM → wait → SIGKILL) so the new dashboard actually binds :26700. Equal/older/unknown versions are reused exactly as before.

Safety / opt-outs

• Skipped for the re-exec'd child (STACK_CLI_SKIP_AUTO_UPDATE, loop guard), when the user opts out (STACK_CLI_NO_AUTO_UPDATE / --no-auto-update), and in CI (CI).
• Registry lookup is TTL-cached in dev-env state with a short timeout and is offline-safe — any failure (no network, no npx) falls through to the installed CLI.
• isVersionNewer never downgrades and returns false for unparseable versions.

Changes

• packages/stack-cli/src/lib/self-update.ts (new) — maybeReexecToLatest(), resolveLatestVersion(), isVersionNewer(), buildNpxInvocation().
• packages/stack-cli/src/commands/dev.ts — re-exec wiring, killLocalDashboard(), version handshake, --no-auto-update flag, version stamp on the recorded dashboard process.
• packages/stack-cli/src/lib/dev-env-state.ts — localDashboard.version + cliUpdateCheck cache helpers.
• Tests: new self-update.test.ts + additions to dev-env-state.test.ts.

Verification

• pnpm --filter @hexclave/cli run lint ✅
• pnpm --filter @hexclave/cli run typecheck ✅
• pnpm --filter @hexclave/cli run test ✅ (132 passed)

Prerequisite

Relies on @hexclave/cli being published to npm with the latest dist-tag tracking releases — otherwise the check is a no-op (which is safe).

---

Summary by cubic

stack dev now re-execs via npx to use the latest published @hexclave/cli, keeping the bundled RDE dashboard up to date without reinstalling. It also restarts a stale background dashboard so the new version binds port 26700.

• New Features

  • Auto-update: checks npm for a newer @hexclave/cli and re-runs npx --yes --min-release-age=0 -p <pkg>@<latest> stack dev .... Cached lookup, short timeout, offline-safe. Skips in CI and when --no-auto-update or STACK_CLI_NO_AUTO_UPDATE=1 is set.
  • Dashboard version handshake: records the CLI version that started the dashboard and restarts it if the running one is older; otherwise reuses it. Graceful SIGTERM with a timeout, then SIGKILL if needed.

• Bug Fixes

  • Cooldown handling: npx re-exec now passes npm’s real --min-release-age=0 so just-published versions install reliably, avoiding ETARGET.
  • Safer dashboard restarts: after SIGTERM, wait for the port to free instead of gating on the pid to avoid recycled-pid false positives; bail early on ESRCH/EPERM; only SIGKILL when the port is still held.
  • Robust cache: validate cliUpdateCheck shape on read; drop malformed entries to avoid version-parse errors.
  • Fail-open: wrap the auto-update path so corrupt/unreadable state files don’t crash stack dev; continue with the installed CLI.

^{Written for commit d3f0581. Summary will update on new commits.}

[greptile-apps]

Greptile Summary

This PR adds an auto-update mechanism to stack dev that re-execs via npx @hexclave/cli@<latest> when a newer version is published, and adds a dashboard version handshake that kills and restarts a stale background dashboard process so users always get the latest bundled dashboard without reinstalling the CLI.

• self-update.ts (new): registry lookup with TTL caching, isVersionNewer comparison, decideReexec I/O-free decision layer, and maybeReexecToLatest entry point — all with thorough unit test coverage.
• dev.ts: wires in the re-exec call, adds killLocalDashboard (SIGTERM → wait → SIGKILL) and a version handshake in startDashboardIfNeeded to restart a stale background dashboard before launching a fresh one.
• Shared helpers (own-package.ts, child-process.ts): extract repeated package.json reading and signal-forwarding boilerplate, consumed by both dev.ts and emulator.ts.

Confidence Score: 3/5

The auto-update and registry-cache paths are safe and well-tested, but killLocalDashboard can send SIGKILL to an unrelated process if the original dashboard's pid is recycled to a user-owned process before the 10-second timeout expires.

After SIGTERM succeeds, a recycled pid owned by the same user keeps processExists returning true for the full polling window, causing SIGKILL to be sent unconditionally to whatever process now holds that pid.

packages/stack-cli/src/commands/dev.ts — specifically the killLocalDashboard wait loop and SIGKILL escalation logic

Important Files Changed

Filename	Overview
packages/stack-cli/src/commands/dev.ts	Adds version handshake to restart stale background dashboard; killLocalDashboard has a correctness hole where a recycled pid owned by the same user can receive SIGKILL unintentionally.
packages/stack-cli/src/lib/self-update.ts	New module implementing npx re-exec logic with version comparison, registry caching, and loop guard; well-structured with a clear I/O-free decision layer and comprehensive tests.
packages/stack-cli/src/lib/dev-env-state.ts	Adds localDashboard.version and cliUpdateCheck to the persisted state; cliUpdateCheck is passed through without a structural type guard, though the downstream behaviour degrades gracefully.
packages/stack-cli/src/lib/own-package.ts	Clean extraction of package.json reading into a tested, I/O-isolated helper; resolveBinName correctly prefers the stack alias for cross-version compatibility.
packages/stack-cli/src/lib/child-process.ts	New shared forwardSignals helper deduplicates identical signal-forwarding boilerplate from both dev.ts and emulator.ts; correct and safe.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as stack dev (installed)
    participant Registry as npm registry
    participant npx as npx @latest
    participant Dashboard as bg dashboard

    User->>CLI: stack dev --config-file
    CLI->>Registry: GET /latest (TTL-cached, 1.5s timeout)
    Registry-->>CLI: version 2.8.110
    CLI->>CLI: isVersionNewer check
    CLI->>npx: "spawn npx -p @hexclave/cli@2.8.110 stack dev"
    npx-->>CLI: exits with child code
    npx->>Dashboard: isDashboardReachable port 26700?
    alt stale dashboard running
        npx->>Dashboard: shouldRestartDashboard check
        npx->>Dashboard: SIGTERM then wait then SIGKILL
        npx->>Dashboard: spawn new dashboard detached
    else up-to-date or no dashboard
        npx->>Dashboard: reuse or start normally
    end
    Dashboard-->>User: http://127.0.0.1:26700

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
packages/stack-cli/src/commands/dev.ts:286-301
**SIGKILL can reach a recycled pid owned by the same user**

After a successful `SIGTERM`, the wait loop calls `processExists(pid)`, which probes with `kill(pid, 0)`. If the dashboard exits quickly and the pid is immediately reused by a process also owned by the current user, `kill(pid, 0)` succeeds (no exception), `processExists` returns `true`, the loop spins for the full 10-second timeout, and the subsequent `process.kill(pid, "SIGKILL")` kills an unrelated process. The EPERM short-circuit in the SIGTERM block only defends against recycling onto *another user's* process; it has no effect once SIGTERM is already sent and we're in the polling loop.

The port availability check is the property that actually matters for letting the new dashboard bind — gate the early-return on that alone, or additionally accept `!processExists(pid)` only when the result also matches the EPERM/ESRCH path.

### Issue 2 of 2
packages/stack-cli/src/lib/dev-env-state.ts:59
**`cliUpdateCheck` is passed through without type validation**

`parsed.cliUpdateCheck` is assigned as-is without verifying that it has the expected shape (`{ packageName: string, latestVersion: string, checkedAtMillis: number }`). If the state file is hand-edited or written by a different version, `readCliUpdateCheckCache` returns a structurally wrong object and `resolveLatestVersion` could see `NaN` from `now - cache.checkedAtMillis` or skip the cache packageName check unexpectedly. Adding a type guard matching `CliUpdateCheckCache` would keep the existing safe-fallback behaviour explicit rather than accidental.

_{Reviews (1): Last reviewed commit: "fix(cli): drop redundant --minimum-relea..." | Re-trigger Greptile}

[cubic-dev-ai]

1 issue found across 12 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>