## 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 <n2d4xc@gmail.com>
Skip the AI agent for plain static config files (no imports, no helpers).
tryParseHexclaveConfigFileContent detects these and applies the update
deterministically via override + renderConfigObjectToFile.
Also updates tests to use import-bearing configs for agent boundary
tests, and adds a dedicated fast-path test.
Co-Authored-By: mantra <mantra@stack-auth.com>
## Stack Auth → Hexclave rename — PR 5 (internal symbols, paths,
packages, brand strings)
PR 5 finishes the **internal / non-wire** half of the Stack→Hexclave
rename. It only touches things where nothing outside the repo depends on
the exact name: internal symbols, file/dir names, the
`@stackframe/template` package, and residual brand strings. Plan +
progress are in `HEXCLAVE-RENAME-PR5-PLAN.md`.
Every step was verified green (`pnpm typecheck` + `pnpm lint`, 28/28)
and committed as its own checkpoint, then a fan-out of review agents
audited all commits and the findings were fixed.
### What changed
- **Internal symbols** (`@hexclave/shared`, `packages/template`, apps):
`stack*`/`Stack*` → `hexclave*`/`Hexclave*` — incl.
`stackGlobalsSymbol`, the `_Stack*AppImpl` classes,
`stackAppInternalsSymbol`, `StackContext`, `getStackStripe`, etc. The
`stack*App` local-variable convention
(`stackServerApp`/`stackClientApp`/…) was renamed across 175
source/example/doc files.
- **File renames**: `hexclave-handler/provider/context.tsx`,
`backend/hexclave.tsx`, `internal-tool/hexclave.ts`,
`hexclave-app-internals.ts`.
- **Directory renames**: `lib/hexclave-app`, `hexclave-companion`,
`[...hexclave]` route segment, `skills/hexclave`,
`dashboard/src/hexclave`, and the package dirs
**`packages/{next,shared,ui,sc,cli}`** (dropping the `stack-` prefix to
match the `@hexclave/*` npm names).
- **Packages**: `@stackframe/template` → `@hexclave/template`; **deleted
`packages/init-stack`** (onboarding lives in `@hexclave/cli init`; the
published npm package is untouched).
- **Brand strings**: reworded `Stack Auth`/`Stack dashboard` prose in
code + docs-mintlify, renamed `hexclave-app.mdx`/`use-hexclave-app.mdx`
with redirects, regenerated OpenAPI, updated coupled e2e assertions;
`doctor`/`init` now prefer `hexclave.config.ts`.
### Intentionally kept (verified, not oversights)
Wire/compat identifiers (`x-stack-*` headers, `stack-*` cookies,
`STACK_*` env names, `*.stack-auth.com`, `stackauth_`, `ask_stack_auth`,
query params), public `Stack*` SDK aliases, crypto/JWT/vault
domain-separation tags, `*-brand-sentinel`s, the
`Symbol.for("StackAuth--…")` string, `_stack_sync_metadata`, Postgres
`stackframe` / docker image names, the `stack-auth-logo*.svg` (used by
the rebrand modal), and `migration.mdx` / "formerly known as Stack Auth"
notes. False positives (Phosphor `StackIcon`/`StackSimple`, `TanStack`,
`OrbStack`, `stackable`/`Stacked` charts) left alone.
### Review pass
Six review agents audited all commits. Found + fixed one real bug — a
build script (`bundle-type-definitions.ts`) hardcoded the old
`lib/stack-app` glob path (not an import, so typecheck/lint were blind),
silently emptying the dashboard AI type bundle — plus stale comments, a
dead CI env var, and stale `.gitignore`/`.dockerignore` entries.
Cross-cutting audit confirmed **zero wire-compat identifiers were
accidentally renamed**.
### ⚠️ Verification note
`typecheck` + `lint` are fully green locally. The **e2e suite was not
run** (needs a live backend+DB), so the brand-string assertion +
OpenAPI-regen changes are verified by grep/codegen only — please let CI
exercise e2e to confirm.
### Base-branch note
This branch was forked from the local-only `cl/friendly-lewin-72293f`
(not on origin, no separate PR), so this PR against `dev` also carries
that branch's ~11 preceding Hexclave-rename commits (config-file rename,
env-var dual-read, AI setup-prompt rebrand). If those should land
separately, re-parent before merge.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Finishes the internal Stack Auth → Hexclave rename and cleans up
remaining stragglers, including dev-tool and prompt copy. All changes
are internal-only; public/wire APIs remain unchanged. Re-merged `dev`
and resolved the payments create-purchase-url conflict.
- **Refactors**
- Internal symbols: stack*/Stack* → hexclave*/Hexclave* (e.g.,
`getHexclaveServerApp` via `@/hexclave`, `getHexclaveStripe`,
`hexclaveAppInternalsSymbol`, `hexclaveSchemaInfo`, Prisma
`__hexclave_*`, `data-hexclave-handler-page`, Stripe mock
`hexclavePortPrefix`).
- Files/dirs: moved to `lib/hexclave-app`; handler route
`[...hexclave]`; backend entry `src/hexclave.tsx`; dashboard internals
`hexclave-app-internals`; companion `hexclave-companion`; dropped
`stack-` prefix across package dirs
(`packages/{shared,ui,sc,cli,next}`); workflows/emulator paths now
`packages/cli`; Quetzal codegen env at `packages/next/.env.local`.
- Packages/docs: `@stackframe/template` → `@hexclave/template`; removed
`packages/init-stack`; regenerated OpenAPI and updated docs
slugs/redirects for hexclave-app/use-hexclave-app.
- Brand strings/prompts: reworded remaining “Stack” dashboard strings to
Hexclave; updated dev-tool copy and prompts; `doctor/init` now prefer
`hexclave.config.ts`. Kept all wire-compat identifiers and public
aliases (`x-stack-*`, `stack-*` cookies, `STACK_*` env,
`*.stack-auth.com`, `Stack*` SDK names).
- Rebased/merged onto latest `dev`: retained `@hexclave/template`, kept
`src` in published files, refreshed setup-prompt imports and docs JSON,
adopted 1.0.5 version bumps, and re-merged `dev` again (resolved
`create-purchase-url` with `getHexclaveStripe`).
- **Bug Fixes**
- Restored dashboard AI type bundle by pointing the glob to
`packages/template/src/lib/hexclave-app`.
- Addressed rename leftovers: updated lingering `@/stack` imports and
CSS selector, fixed schema/meta and port-prefix expansions, and aligned
emulator commands to `packages/cli`.
- CI/build: removed a dead env var and stale ignore entries; fixed
Docker by renaming `STACK_SKIP_TEMPLATE_GENERATION` →
`HEXCLAVE_SKIP_TEMPLATE_GENERATION`.
<sup>Written for commit 3c1af3bff3.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1547?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. -->
- Updated error message in `runHeadlessClaudeAgent` to be more concise.
- Removed unnecessary comments in `config-file.test.ts` and `hexclave-config-file.ts` to enhance readability.
- Refactored `runHeadlessClaudeAgent` to streamline the handling of the `onPreToolUse` option.
- Adjusted import statements in `index.ts` for better clarity.
These changes improve the maintainability and clarity of the codebase, particularly in the configuration management components.
- Updated `next.config.mjs` to include dynamic path resolution for the `@anthropic-ai/claude-agent-sdk`, improving output file tracing.
- Refactored tests in `config-file.test.ts` to clarify the shared agent updater's functionality and ensure it can handle updates to both config and imported files in a single run.
- Modified `manager.ts` to utilize `updateConfigObject` for applying configuration updates, enhancing the reliability of remote environment updates.
- Improved the `updateConfigObject` function in `local-config-updater` to include baseline configuration in the update prompt, ensuring expected outcomes are clearly defined.
These changes enhance the configuration management and testing capabilities within the Hexclave ecosystem.
- Removed "allowImportingTsExtensions" from tsconfig.json in dashboard, local-config-updater, and stack-cli to streamline TypeScript configurations.
- Updated import statement in local-config-updater to use a more explicit path for better clarity.
These changes simplify TypeScript settings and improve code maintainability across the project.
- Added "allowImportingTsExtensions" to tsconfig.json files in dashboard, local-config-updater, and stack-cli for enhanced TypeScript module handling.
- Refactored the AppDetailsPageClient component to simplify the enable/disable functionality by removing asynchronous alert wrappers.
- Updated the configuration update function to enable waiting for sync, improving the reliability of remote environment updates.
These changes enhance TypeScript support and improve the user experience in the dashboard application.
- Added outputFileTracingIncludes to next.config.mjs for better handling of the @anthropic-ai/claude-agent-sdk files.
- Updated import statements in local-config-updater to use TypeScript type imports for improved clarity and maintainability.
These changes improve the configuration management and build process within the Hexclave ecosystem.
## What
Continues the **Stack Auth → Hexclave** rename for a set of safe,
internal-only surfaces. This intentionally avoids public-contract names.
### Changes
- **Examples** — renamed the user-facing config module
`stack.ts`/`stack.tsx` (and the `convex` / `lovable` `stack/`
directories) to `hexclave`, and updated every importer across
`.ts`/`.tsx`/`.jsx`. The public `app/handler/[...stack]/` route segment
is left unchanged.
- **apps/{dashboard,backend,internal-tool}** — renamed app-local
SDK-init symbols `stackClientApp → hexclaveClientApp` and
`getStackServerApp → getHexclaveServerApp`, and the dashboard
`StackCompanion` component → `HexclaveCompanion` (incl.
`useStackCompanion`, context types). The public
`StackClientApp`/`StackServerApp` SDK classes are **unchanged**.
- **packages/stack-shared** — added comments to the crypto / JWT / vault
`stack-*` literals documenting that they must **not** be renamed (key
derivation / JWKS / KMS-alias stability). The literals are
byte-identical.
### Deliberately excluded
- **`STACK_*` → `HEXCLAVE_*` env-var rename** — `HEXCLAVE_*` already
resolves via the dual-read layers (SDK env, dashboard `_inlineEnvVars`,
`getEnvVariable`). The remaining holdout is the docker post-build
sentinel path, which the codebase authors explicitly deferred and which
is tightly coupled to `entrypoint.sh` + untestable here. A blind rename
there risks silently breaking self-host/emulator bootstrap for ~zero
functional gain.
- **All public-contract names** — SDK class names, env vars, HTTP
headers (`x-stack-*`), and the `/handler` route convention.
## Verification
- `pnpm lint` — **29/29 passing**.
- `pnpm typecheck` — **28/29 passing**; the only failure is
`@hexclave/docs` (pre-existing missing fumadocs `.source` codegen,
untouched by this PR).
- Two rounds of adversarial multi-agent review; findings fixed:
string-literal collateral from the symbol sweep (CLI test fixtures + an
AI-prompt template) reverted, and a missed `.jsx` importer in
`examples/cjs-test` corrected.
## Notes
- Based on a `dev` snapshot from when the branch was cut (a couple
commits behind tip); the diff contains only the changes above.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Complete the internal “Stack” → “Hexclave” rename across examples,
app-local code, config tooling, and setup docs, and standardize env
output to HEXCLAVE_* with correct default API URL handling. Public SDK
classes, handler routes, and legacy env names keep working.
- **Refactors**
- Examples/config: `stack.*` files and `stack/` dirs →
`hexclave.*`/`hexclave/`; imports updated; keep `app/handler/[...stack]`
route.
- Apps: backend/dashboard/internal-tool now use `getHexclaveServerApp`
and `hexclaveClientApp`; dashboard `StackCompanion` →
`HexclaveCompanion`. Public `StackClientApp`/`StackServerApp` unchanged.
- Env/setup: Next.js and CLI generators write HEXCLAVE_* and omit API
URL when using https://api.stack-auth.com; CLI `doctor` and auth
resolution prefer HEXCLAVE_* (e.g. `HEXCLAVE_SECRET_SERVER_KEY`,
`HEXCLAVE_PROJECT_ID`) with `STACK_*` fallback.
- Config tooling: `stack-config-file` → `hexclave-config-file`, emitting
`HexclaveConfig`; imports updated across backend/dashboard/tooling.
- Shared/docs: added “do not rename” notes for crypto/JWT/vault
`stack-*` literals; regenerated setup prompt/docs to use
`hexclave.config.ts`, `hexclave dev`, and `src/hexclave/`.
- Tests: updated snapshots/assertions to expect `HexclaveConfig` and
HEXCLAVE_* env names.
- **Migration**
- No action required. SDK and CLI read both HEXCLAVE_* and STACK_*.
<sup>Written for commit 8a891b4f6c.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1534?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
* **Refactor**
* Renamed internal app/client/server instances and companion/provider
components to the new product name across backend, dashboard, examples,
and tooling; imports updated accordingly.
* Updated generated environment variable names and CLI init/doctor
outputs to prefer the new product prefix.
* **Documentation**
* Added clarifying notes about vault/encryption and JWT/key labels to
avoid breaking existing encrypted data.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
- Added a new package `@hexclave/local-config-updater` to manage configuration updates.
- Implemented core functionality for reading and updating configuration files using a headless agent.
- Integrated with the `@anthropic-ai/claude-agent-sdk` for AI-assisted updates.
- Updated the pnpm-lock file to reflect new dependencies and removed the deprecated `@anthropic-ai/claude-agent-sdk` from the dashboard app.
- Added tests to ensure the correct behavior of the local config updater.
This change enhances the configuration management capabilities within the Hexclave ecosystem.
Uses the previously-unused filePath param as Babel's sourceFilename so parse
diagnostics reference the real file. Addresses Copilot review note.
Co-Authored-By: mantra <mantra@stack-auth.com>
- Roll back the config file and its referenced files if the agent fails or
its result doesn't validate, so no half-applied update is left behind
- Validate the rendered fast-path config in memory before writing to disk
- Only schedule a background sync after a successful update (manager.ts)
- Treat empty-object update values as leaves and skip undefined values so the
agent prompt matches override() semantics
- Detect agent completion via "result" in message (matches the CLI)
- Accept the export { config } specifier form in the structural check
- Add importAttributes to parseStackConfigFileContent for parser consistency
- Drop the unsafe Record<string,string> cast in stripClaudeCodeEnv
- Add a bounded, configurable timeout to the agent run
Co-Authored-By: mantra <mantra@stack-auth.com>
Apply RDE config updates in place instead of overwriting the whole file.
Plain static configs keep the deterministic render (fast path, no AI). Configs
with custom structure (imports, helper wrappers, external text refs) are edited
by a headless Claude agent so user-authored structure is preserved and
externally-referenced files are updated rather than inlined. Every edit is
validated (semantic when the config is evaluable, structural fallback
otherwise) and hard-fails on mismatch.
Co-Authored-By: mantra <mantra@stack-auth.com>
