Speeds up project onboarding by consolidating API calls and adding
prefetching:
- Single PATCH endpoint for saving onboarding status + state together
- Background config save on welcome step (with proper retry/error
handling)
- Prefetch email themes and Stripe info for upcoming steps
- Suspense-based skeleton loaders instead of full-page spinners
- Extracted shared types and lightweight step components
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Unified onboarding progress saving for the new project flow,
persisting status plus optional onboarding state in a single update
path.
* **Improvements**
* Onboarding wizard now derives status/state from owned project data and
removes extra internal fetching/loading gates.
* Added skeleton/Suspense loading for email theme and payments steps,
with more reliable “final config”/completion sequencing.
* Admin project data now includes onboarding state; Stripe account info
uses cached retrieval.
* Backend avoids source-of-truth override changes during metadata-only
updates.
* **Tests**
* Updated onboarding wizard tests and added end-to-end coverage for
updating onboarding status/state together.
* **Documentation**
* Added the “clickmaps” app icon to docs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: armaan <armaan@stack-auth.com>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
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
Completes the env-var side of the Hexclave rebrand: every
`STACK_*`-prefixed variable (including `NEXT_PUBLIC_STACK_*` and
`VITE_STACK_*`) is renamed to `HEXCLAVE_*` across all checked-in `.env`,
`.env.development`, and `.env.example` files (30 files, ~135 keys).
Legacy `STACK_*` names keep working everywhere via dual-read, so
**existing deployments, `.env.local` files, and self-hosted setups need
no immediate migration**.
## How legacy names keep working
- **Server code** already resolves `HEXCLAVE_*` first with `STACK_*`
fallback via `getEnvVariable`. Direct `process.env.STACK_X` readers fed
by the renamed files (prisma seed, e2e tests/helpers, internal-tool
scripts, examples, `prisma.config.ts`) now read `HEXCLAVE_X || STACK_X`.
- **Client code** (Next.js build-time inlining) uses literal dual-read
expressions; the dashboard's `_inlineEnvVars` already had them.
- **Docker/self-hosting**: `docker/server/entrypoint.sh` (shared by the
server and local-emulator images) gets a generic two-way
`HEXCLAVE_`↔`STACK_` env mirror — runs at startup and again before
sentinel replacement — replacing the previous URL-trio-only mirror.
Operators can use either prefix.
## The empty-placeholder trap (`||` vs `??`)
The checked-in templates define empty placeholders (`HEXCLAVE_X=#
comment` parses to `""` via dotenv). With `?? `-based fallbacks, that
empty string would silently shadow a real value under the legacy name —
including legacy vars set in Vercel/CI env at build time, since the
tracked `.env` is present during builds. All fallback chains therefore
treat empty-as-unset (`||`):
- `getEnvVariable` and `getProcessEnv` in `packages/shared`
- the dashboard/docs/example literal dual-reads
- the generated SDK env getters (via
`packages/template/scripts/generate-env.ts`; the generated
`src/generated/env.ts` files are gitignored and regenerate at build)
## Other notable changes
- Tests that override env now set the canonical `HEXCLAVE_*` name (it
wins over `STACK_*`): e2e `cross-domain-auth`, backend
`internal-feedback-emails` in-source test.
- e2e `helpers.ts` port-prefix expansion loop also matches the
`HEXCLAVE_` prefixes.
- `docker/local-emulator/generate-env-development.mjs` reads source keys
canonically (legacy fallback) and emits canonical keys; regenerated
output matches.
- `rotate-secrets.sh` falls back to
`HEXCLAVE_DATABASE_CONNECTION_STRING`.
- Docs code snippets (`docs/code-examples`) renamed outright to
canonical names, consistent with #1571.
- OAuth callback `console.warn` in `packages/template/src/lib/auth.ts`
now says Hexclave.
## Migration note for the team
Local `.env.local` files with legacy `STACK_*` overrides keep working
**unless** the override targets a var that `.env.development` now sets
to a real (non-empty) `HEXCLAVE_*` value — the canonical name wins over
file precedence. Rename those keys in your `.env.local` once.
## Verification
- `typecheck` + `lint` pass on every touched package (shared, backend,
dashboard, e2e, internal-tool, cli, docs, template). Pre-existing
failures on dev (`admin-app-impl.ts` typecheck, dashboard metrics-page
errors) are unchanged (identical error counts with/without this change).
- `getEnvVariable`/`getProcessEnv` fallback semantics smoke-tested
directly (empty-HEXCLAVE → legacy fallback, HEXCLAVE wins when set,
defaults intact).
- `internal-feedback-emails` in-source vitest passes; emulator env
generator `--check` passes; `bash -n` on touched shell scripts.
- Two independent review agents audited the diff for correctness bugs
and coverage gaps; all confirmed findings are fixed in the third commit.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Renamed all `STACK_*` env vars (including
`NEXT_PUBLIC_STACK_*`/`VITE_STACK_*`) to `HEXCLAVE_*` across env
templates and code, with dual‑read that treats empty as unset, detects
conflicts, ignores post‑build sentinels, and falls back to legacy names.
All GitHub Actions now use `HEXCLAVE_*`; local‑emulator e2e is fixed by
setting `NEXT_PUBLIC_HEXCLAVE_IS_LOCAL_EMULATOR` in CI.
- **Refactors**
- Added conflict‑aware dual‑read helpers (prefer `HEXCLAVE_*`,
empty‑as‑unset, ignore post‑build sentinels, preserve empty passthrough)
and used them across `packages/shared` (resolver + tests),
`apps/dashboard` inline/public envs (with tests), `apps/backend` Prisma
config/seed and vitest (accept both prefixes), `packages/cli`
(API/Dashboard URLs, project ID, `HEXCLAVE_EMULATOR_HOME`; tests),
Docker (`entrypoint.sh` mirroring + `rotate-secrets.sh` DB URL),
docs/components (`docs/src/lib/env.ts`), and examples; hosted/Vite apps
now error if both spellings differ.
- Port‑prefix expansion includes `HEXCLAVE_*`; backend tests use a new
helper to resolve DB connection strings; Prisma prefers
`HEXCLAVE_DATABASE_CONNECTION_STRING` with legacy fallback.
- Generated SDK env getters use plain `HEXCLAVE_*` || `STACK_*` (no
conflict throw); dashboard inline resolver preserves empty/sentinel
passthrough to avoid build failures; docs/examples include dual‑read
utilities.
- Tests now stub canonical `HEXCLAVE_*` flags (e.g., plan limits, bot
challenge, OAuth tokens, hosted handler) to avoid shadowing/conflict
with committed defaults.
- **Migration**
- No immediate action; legacy `STACK_*` names still work.
- If both names are set with different values, builds/scripts error. Set
only `HEXCLAVE_*` or make both equal.
- SDK consumers won’t see conflict throws; update env names to
`HEXCLAVE_*` over time.
<sup>Written for commit 7539fb9fbf.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1588?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.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
* **Chores**
* Migrated environment variable names from the legacy `STACK_*` prefix
to the new `HEXCLAVE_*` prefix across backend, dashboard, tooling,
Docker, and examples.
* Updated environment/config resolution to prefer `HEXCLAVE_*`, treat
empty strings as unset, and detect conflicts when both `STACK_*` and
`HEXCLAVE_*` are set to different values.
* Updated local emulator, server startup, and env-generation workflows
to use the new names (with legacy fallback where applicable).
* **Documentation**
* Updated docs and code examples to reference `HEXCLAVE_*` variables.
* **Tests**
* Refreshed unit and e2e coverage to validate dual-read behavior,
conflict detection, and empty-value handling.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
`hexclave dev` re-execs itself through `npx <pkg>@latest`
(`maybeReexecToLatest`) so users always get the latest dashboard without
reinstalling. But when that npx run **fails**, it exits nonzero and we
did `process.exit(result.code)` — killing `hexclave dev` even though a
perfectly good CLI was already installed locally.
This surfaced on **Replit**, where a user running `hexclave dev` got:
```
npm notice Access denied: Your download has been blocked by the Socket Security Policy.
Reason: AI-detected potential malware.
npm error code ECOMPROMISED
npm error Lock compromised
```
Diagnosis: the user's `pnpm` is aliased to `sfw pnpm` (**Socket
Firewall**), and Replit enforces an org-level Socket Security Policy.
Socket **blocks the `@hexclave/cli@latest` download** (false-positive
"AI-detected malware", almost certainly the bundled minified dashboard).
The interrupted download breaks npx's reify while it holds its cache
lock, which npm reports as `Lock compromised`. The lock message is a
*downstream symptom*; the real failure is the blocked download.
The same class of failure (blocked download, npm error, lock contention,
offline) all share one shape: **npx exits nonzero before our CLI ever
runs**, and today that takes down `hexclave dev`.
## Fix
Use a **startup-marker handshake** to distinguish the two cases:
- The parent passes a temp marker path to the npx child via
`STACK_CLI_REEXEC_MARKER`.
- The re-exec'd child touches the marker the instant it starts
(`signalReexecStartedIfChild`).
- After the child exits (`decidePostReexec`):
- exited 0, or nonzero **with** the marker present → our CLI ran;
**propagate** the exit code (real command result).
- nonzero **without** the marker, or npx not spawnable → our CLI never
ran; **fall back** to the installed CLI instead of failing `hexclave
dev`.
The marker only needs file create/exists (robust on sandboxed/networked
filesystems). If the marker can't be created, we preserve the old
always-propagate behavior, so there's no spurious-fallback risk.
`decidePostReexec` and `signalReexecStartedIfChild` are pure and
unit-tested.
## Verification
- `pnpm test run src/lib/self-update.test.ts` → 23 passing (added cases
for the fallback decision and the marker handshake).
- `pnpm typecheck` / `pnpm lint` → clean.
- End-to-end: forced a real npx failure (unreachable registry → npx
exits nonzero before our CLI runs) and confirmed `hexclave dev` now logs
`Auto-update skipped: …; continuing with the installed CLI.` and
proceeds into the installed dev path instead of dying.
## Notes / follow-ups (not in this PR)
- Workaround for affected users today: `STACK_CLI_NO_AUTO_UPDATE=1` (or
`--no-auto-update`) skips the npx download entirely.
- Worth reporting the Socket false-positive to socket.dev to allowlist
`@hexclave/cli`, and reconsidering shipping a ~165 MB minified dashboard
inside the npm tarball (it's what trips AI-malware heuristics and slows
cold installs).
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Prevent `hexclave dev` from exiting when `npx @latest` auto-update fails
by falling back to the installed CLI. Signal-based aborts now propagate
as a nonzero exit (never NaN), so Ctrl-C doesn’t relaunch dev.
- **Bug Fixes**
- Fall back to the installed CLI when `npx <pkg>@latest` fails before
the CLI starts (firewalls, offline, npm lock errors). Do not fall back
when the child is killed by a signal; propagate 128+signum with a safe
nonzero fallback if the signum is unknown.
- Startup-marker handshake: parent sets `REEXEC_MARKER_ENV`
(`HEXCLAVE_CLI_REEXEC_MARKER`); child touches it on start;
`decidePostReexec` chooses propagate vs fallback. If the marker can’t be
created, keep the old always-propagate behavior.
- Scrub the marker env from user commands using the exported constant,
covering both Windows and POSIX spawn paths.
<sup>Written for commit cb2635f2ae.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1612?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.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
## Release Notes
* **Bug Fixes**
* Updated the `dev` command to prevent internal re-exec environment
details from being inherited by user commands.
* Improved self-update re-exec fallback logic to better detect whether
the CLI actually started, with more reliable exit-code and signal
handling.
* **Tests**
* Added deterministic test coverage for the post-re-exec decision path
and signal/exit propagation scenarios, including early `npx` failures.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
`envVarsForProject` in the dev-environment manager only emits the legacy
`STACK_*` env var names. The rest of the CLI was migrated to the
`HEXCLAVE_*` brand as canonical, keeping `STACK_*` only as a fallback:
- `init` scaffolds `.env` with `NEXT_PUBLIC_HEXCLAVE_PROJECT_ID`,
`NEXT_PUBLIC_HEXCLAVE_PUBLISHABLE_CLIENT_KEY`,
`HEXCLAVE_SECRET_SERVER_KEY`
- `resolveProjectId` reads `HEXCLAVE_PROJECT_ID` first, then
`STACK_PROJECT_ID` (commented as "legacy")
- `doctor` lists the `HEXCLAVE_*` names first
So `hexclave dev` injects a different set of names than the CLI
otherwise expects/generates.
## Change
`envVarsForProject` now emits both brands (`HEXCLAVE_*` and `STACK_*`)
across the public framework prefixes (`NEXT_PUBLIC_`, `VITE_`,
`EXPO_PUBLIC_`), built from a single source list.
- All previously-emitted `STACK_*` keys are unchanged (no regression).
- The secret server key is still only emitted as
`HEXCLAVE_SECRET_SERVER_KEY` / `STACK_SECRET_SERVER_KEY` — never under a
public, client-readable prefix.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Updated the dev environment to emit both `HEXCLAVE_*` and legacy
`STACK_*` env vars so `hexclave dev` matches the rest of the CLI and
avoids name mismatches. Secret keys remain non-public.
- **Bug Fixes**
- Emit both brands for `PROJECT_ID`, `PUBLISHABLE_CLIENT_KEY`, and
`API_URL` under ``, `NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`.
- Only emit `HEXCLAVE_SECRET_SERVER_KEY` / `STACK_SECRET_SERVER_KEY`
(never with public prefixes).
- Keep existing `STACK_*` outputs unchanged for backward compatibility.
<sup>Written for commit 2aef5d4b1a.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1627?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.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**
* Improved internal environment variable generation architecture for
enhanced maintainability and multi-framework support.
---
**Note:** This release contains internal code improvements with no
changes to user-facing functionality.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What
Adds a **Things to Know About Microsoft OAuth** section to the Microsoft
auth provider docs covering provider-specific behavior:
- **Emails are not marked as verified** — Microsoft doesn't attest
control of the returned email, so Hexclave treats Microsoft emails as
unverified. Links to Microsoft's [claims validation
guidance](https://learn.microsoft.com/en-us/entra/identity-platform/claims-validation#validate-the-subject).
- **Supported account types** (custom OAuth keys only) — explains how
the tenant type set in the dashboard/config maps to Microsoft's
`{tenant}` endpoint segment (`common` / `organizations` / `consumers` /
tenant ID), with the default being `consumers`. Links to Microsoft's
[endpoint
reference](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols#endpoints).
Also fixes a leftover branding issue: the dev shared-keys `<Info>`
callout said "Stack" instead of "Hexclave".
## Why
The unverified-email behavior is surprising (sign-in succeeds but the
email isn't verified) and previously undocumented. The account-types
note helps developers using their own OAuth app pick the right tenant
setting.
<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds a “Things to Know About Microsoft OAuth” section explaining that
Microsoft emails are treated as unverified and how account types map to
Microsoft tenant endpoints (custom keys only, default is `consumers`).
Also fixes the dev shared-keys callout to correctly use Hexclave
branding and behavior.
<sup>Written for commit 7ae78d6e52.
Summary will update on new commits.</sup>
<a
href="https://cubic.dev/pr/hexclave/hexclave/pull/1623?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.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
* **Documentation**
* Updated Microsoft authentication provider guide to clarify that
Hexclave automatically creates shared development keys and displays its
logo on the OAuth sign-in page.
* Added section explaining Microsoft OAuth email verification behavior
and how account types map to Microsoft tenant settings.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
