## Summary
The RDE dashboard was bundled into the `@hexclave/cli` npm tarball
(~165MB). That made the `npx @latest` auto-update re-exec pull a huge
tarball, which tripped download firewalls (Socket Firewall
false-positives on Replit → `Lock compromised`).
This decouples the dashboard from the CLI: it's published as a **GitHub
Release artifact** (a zip + `manifest.json` on a floating
`dashboard-latest` release) and fetched at runtime, cached on disk. The
dashboard now rolls forward **independently of the CLI version**
(assuming newest dashboards stay compatible with older CLIs — no compat
gate yet, by design for now).
## How it works
- **Runtime** (`packages/cli/src/lib/dashboard-release.ts`): on
`hexclave dev`, fetch `manifest.json` (`{version, sha256, url}`) from a
stable, no-API GitHub URL → cache under
`<dirname(devEnvStatePath())>/dashboards/<version>/` → streamed
download, **sha256 verify**, extract via the existing `extract-zip` dep,
atomic publish. Offline → fall back to the newest cached build.
- **Wiring** (`dev.ts`): `startDashboardIfNeeded` resolves/launches the
cached release; the restart decision now compares the **dashboard
release** version (not the CLI version). `HEXCLAVE_DASHBOARD_DIR` runs a
local build with zero network; a custom dev dashboard command bypasses
releases entirely.
- **No more npx self-update**: the `npx @latest` re-exec in `hexclave
dev` is removed entirely (along with `self-update.ts`, the
`--no-auto-update` flag, and the binName plumbing that only built the
npx call). It existed to keep the bundled dashboard fresh; now the
dashboard self-updates from GitHub, so the re-exec only added an npx
download on every run — the firewall surface. Users update the CLI via
npm/npx themselves.
- **Publishing** (`scripts/package-dashboard-release.mjs` +
`.github/workflows/dashboard-release.yaml`): build standalone → zip →
write manifest → publish immutable `dashboard-v<version>` release +
clobber the `dashboard-latest` manifest. **Fails loudly** if an existing
tag's asset sha differs from a fresh build (dashboard changed without a
version bump → would otherwise advertise a hash the served zip doesn't
match).
- **Build**: CLI build is now `tsdown`-only (no bundled dashboard);
`turbo.json` drops the dashboard standalone build from the CLI build
graph.
## Testing
- **Unit**: 135 CLI tests pass (manifest parsing incl. path-safe version
validation, URL resolution, version picking, dir override).
- **End-to-end (no GitHub)**: a localhost HTTP server + fixture zip
exercised the full fetch path — download, sha256 verify, cache-hit,
roll-forward, **corrupt-sha rejection**, offline→cache fallback (9/9).
- **Real dashboard, no GitHub**: built the standalone, served the real
76MB zip over `python -m http.server`, and confirmed `hexclave dev`
downloads → verifies → extracts → **boots** the dashboard and registers
an RDE session against the hosted backend. Also validated
`HEXCLAVE_DASHBOARD_DIR` boot.
## Review
Three review agents (runtime correctness, packaging/workflow, code
quality) ran; valid findings fixed: path-traversal hardening on
`version`, a concurrent cache rm/rename race, the workflow
sha-mismatch/atomicity gap, plus `errorMessage` dedup and added tests.
## Notes / follow-ups
- No CLI↔dashboard compatibility gate yet (assumes always-compatible);
easy to add later via a min-CLI field in the manifest. This matters more
now that the CLI no longer auto-updates.
- The publish workflow has not run yet, so the first push to `main` will
create the `dashboard-latest` release.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added automated, immutable versioned releases for the standalone
dashboard plus a continuously updated “latest” manifest.
* CLI now fetches, verifies, caches, and supports offline fallback for
the dashboard runtime.
* **Bug Fixes**
* Improved dashboard restart behavior to update only when a strictly
newer published version is available.
* **Chores**
* Removed the CLI’s automatic update/re-launch behavior for more
predictable startup.
* **Tests**
* Added unit tests for dashboard manifest validation and latest-version
selection.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
## Summary
Replaces `writeConfigObject` (destructive overwrite) with
`updateConfigObject` — an async, AI-aware updater that preserves
user-authored config structure (imports, external file references,
helpers).
**Dual-path approach:**
- **Fast path** (deterministic, no AI): plain static literal configs →
`override()` + in-memory validation + atomic write
- **Agent path** (custom structure): configs with `import x from
"./file.txt" with { type: "text" }` etc. → Claude agent edits the
external files in place, then validates
**Safety guarantees:**
- Snapshot/restore: config + all relative imports are captured before
the agent runs; rolled back on any failure
- In-memory validation on fast path (never write unvalidated bytes)
- Semantic check when config is evaluable; no-op detection + structural
check when it isn't
- Path traversal guard on imports (rejects `../` escapes)
- Agent isolation: `settingSources: []`, `strictMcpConfig: true`,
`CLAUDE_CODE_DISABLE_AUTO_MEMORY`, no Bash tool
- `scheduleSync` only fires after a successful update
- Bounded 120s timeout on agent runs (configurable via env var)
CI failures are preexisting on `dev`
(`ERR_PNPM_LOCKFILE_CONFIG_MISMATCH` from overrides move without
lockfile regen); this branch has zero lockfile changes vs dev.
Link to Devin session:
https://app.devin.ai/sessions/cc7409a357bc472ea19fbed065f1229f
Requested by: @mantrakp04
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Introduced partial configuration update functionality with validation
and automatic rollback on failures.
* Enhanced configuration management with support for more complex file
structures and external references.
* **Chores**
* Added Claude Agent SDK dependency for configuration update operations.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Documentation
Docs for this feature were added in this branch:
- **New page**
`docs-mintlify/guides/going-further/local-development.mdx` — covers
`stack dev`, the development-environment flow, and how dashboard edits
are written back to the local config file (structure-preserving fast
path vs. assistant path, external `import … with { type: "text" }`
templates, validation + rollback). Added to `docs.json` nav; also fixes
the previously-broken `/guides/going-further/local-development` links
from `index.mdx` and `self-host.mdx`.
- **`docs-mintlify/guides/going-further/cli.mdx`** — added a `stack dev`
("Run a development environment") section.
- **Skill-site AI prompts** — filled in the `config-docs` and
`dashboard-instructions` placeholders under
`packages/stack-shared/src/ai/unified-prompts/skill-site-prompt-parts/`,
and added a structure-preserving note to the setup prompt.
- **`CHANGELOG.md`** — user-facing entry.
---------
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: mantra <[email protected]>
## 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).
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
`hexclave dev` now re-execs via `npx` to run the latest `@hexclave/cli`,
so the bundled RDE dashboard stays current without reinstalling. It
reuses the running dashboard and only restarts it when the current CLI
is strictly newer.
- **New Features**
- Auto-update: always re-execs `npx --yes --min-release-age=0 -p
@hexclave/cli@latest hexclave dev ...`; runs in CI; opt out with
`--no-auto-update` or `STACK_CLI_NO_AUTO_UPDATE=1`.
- Per-port dashboard version handshake: records the CLI version per port
and restarts only when strictly newer; otherwise reuses it (respects
`NEXT_PUBLIC_HEXCLAVE_LOCAL_DASHBOARD_PORT`).
- **Bug Fixes**
- Safer restarts: after SIGTERM, wait for the port to free instead of
pid probes; bail on ESRCH/EPERM; only SIGKILL if the port still answers.
- Robust execution: ship a single `hexclave` bin (fixes `pnpx`/`pnpm
dlx`), forward SIGINT/SIGTERM to children, validate per-port dashboard
state, update help/messages to `hexclave`, and make Windows re-exec
reliable (`npx.cmd` with shell and argv quoting).
<sup>Written for commit 80c9b30a5c.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1521?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* CLI can auto-check and re-exec to a pinned newer release (opt-out:
--no-auto-update).
* Local dashboard startup is version-aware and only restarts when the
CLI is strictly newer.
* Improved child-process signal forwarding for cleaner shutdowns.
* **Tests**
* Expanded unit tests covering dev workflow, self-update, package
metadata, persistence, and dashboard lifecycle.
* **Bug Fixes**
* Updated user-facing CLI messaging to use "hexclave" command names.
* **Chores**
* Removed legacy docs workspace entry.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konstantin Wohlwend <[email protected]>
github-actions[bot]
BilalG1andGitHub
Konsti WohlwendandGitHub
