stack/HEXCLAVE-RENAME-PR5-PLAN.md

Hexclave Rename — PR 5 Plan (internal symbol & path cleanup)

Branch: cl/hexclave-rename-pr5

PR 5 finishes the internal, non-wire half of the Stack→Hexclave rename. PRs 1–3 + follow-ups already shipped the compatibility layer (wire dual-accept, env dual-read, @hexclave/* packages, public Hexclave* aliases, dual cookies, dual domains). PR 5 renames things that are safe because nobody outside the repo depends on the exact name: internal symbols, directory/file names, internal variables, and residual brand strings. It must NOT touch wire/compat identifiers or external-facing names.

Generated SDK packages (packages/js, packages/react, packages/stack, packages/tanstack-start) are copied from packages/template by scripts/generate-sdks.ts — only edit packages/template, then run pnpm -w run generate-sdks.

---

Scope decisions (maps the 12-section review feedback)

#	Area	Decision
1	Package directory names (packages/stack*)	Rename all dirs → hexclave-based names
2	@stackframe/template, @stackframe/init-stack	Rename @stackframe/template → @hexclave/template; delete packages/init-stack/ entirely (deprecated)
3	Source dirs (lib/stack-app, stack-companion, apps/.../stack/); skills/stack-auth	Rename all; skills/stack-auth → skills/hexclave directly
4	Source files with stack basename; logo assets	Rename all code files. KEEP stack-auth-logo*.svg (verified: used intentionally by the rebrand modal as the old logo)
5	Public SDK Stack* aliases	No action (kept as deprecated aliases)
6	Internal-only Stack* symbols + camelCase/infix internal vars	Rename all (incl. newly-discovered stackGlobalsSymbol-class identifiers)
7	x-stack-* HTTP headers	No action (dual-accept forever)
8	Cookies / storage / DOM / postMessage	Rename what's safe-to-reset (UI-only local state); keep compat for anything persisted/cross-version
9	STACK_PORT_PREFIX	Env var already renamed (0 refs left). Rename the internal stackPortPrefix / expandStackPortPrefix / replaceStackPortPrefix vars/fns
10	doctor.ts, init prompt	Update stale stack.config.ts-only references to prefer hexclave.config.ts
11	*.stack-auth.com domains	No action (compat)
12	Brand strings	Update "Stack Auth"/"Stack dashboard" prose in code (incl. newly-found known-errors.tsx, backend messages)

---

A. Directories to rename (§1, §3)

Current	New
packages/stack (npm @hexclave/next)	packages/next
packages/stack-shared (@hexclave/shared)	packages/shared
packages/stack-ui (@hexclave/ui)	packages/ui
packages/stack-sc (@hexclave/sc)	packages/sc
packages/stack-cli (@hexclave/cli)	packages/cli
packages/template (→ @hexclave/template)	packages/template (dir name fine; npm name changes)
**/src/lib/stack-app/ (template + generated)	**/src/lib/hexclave-app/
apps/dashboard/src/stack/	apps/dashboard/src/hexclave/
apps/dashboard/src/components/stack-companion/ (+ stack-companion.tsx)	…/hexclave-companion/
skills/stack-auth/	skills/hexclave/
app/handler/[...stack]/ (dashboard, internal-tool, all examples/*)	app/handler/[...hexclave]/ — DECIDED: rename

Decided (review): directory names drop the stack- prefix to match the npm names — packages/{next,shared,ui,sc,cli}.

[...stack] → [...hexclave] is internal/cosmetic: it changes the Next.js catch-all param key (params.stack → params.hexclave), NOT the public /handler/* URL. Update the param read site in the handler (packages/template/src/components-page/*handler*.tsx) and every examples/*/.../handler/[...stack]/page.tsx in lockstep. Public URLs are unchanged, so no wire/compat risk.

Do NOT rename: sdks/implementations/swift/Sources/StackAuth/ (frozen Swift package).

Each dir rename ripples into: tsconfig.json path aliases, pnpm-workspace.yaml, turbo.json, import specifiers (mostly already @hexclave/* so unaffected), scripts/generate-sdks.ts source/dest paths, and any relative imports. Use git mv; then sweep references.

---

B. Package renames / deletions (§2)

1. @stackframe/template → @hexclave/template: update packages/template/package.json name; update the ~3 dependents that reference @stackframe/template (find: rg '@stackframe/template'), scripts/generate-sdks.ts, any tsconfig path. It's never published, so no npm impact.
2. Delete packages/init-stack/: remove the directory and de-wire all references —
   • pnpm-workspace.yaml, root package.json scripts (init-stack:local etc.), turbo.json
   • any CI workflow referencing it
   • dashboard onboarding / docs that point at npx @stackframe/init-stack (onboarding already moved to @hexclave/cli init)
   • The already-published @stackframe/init-stack npm package stays on npm (can't/shouldn't unpublish) — that's fine; we just stop building it.
   • Migrate-or-confirm: a few helper names live here (getStackPackageName, StackAppFile* types, MCP_SERVER_NAME, EVENT_PREFIX="stack-init-"). Confirm nothing still-shipping imports from init-stack before deletion (rg 'init-stack').

---

C. Files to rename (§4)

Edit in packages/template (regenerated to SDKs):

• components-page/stack-handler.tsx → hexclave-handler.tsx; stack-handler-client.tsx → hexclave-handler-client.tsx
• providers/stack-context.tsx → hexclave-context.tsx; stack-provider.tsx → hexclave-provider.tsx; stack-provider-client.tsx → hexclave-provider-client.tsx

Apps:

• apps/backend/src/stack.tsx → hexclave.tsx
• apps/internal-tool/src/stack.ts → hexclave.ts
• apps/dashboard/src/lib/stack-app-internals.ts → hexclave-app-internals.ts
• apps/dashboard/src/components/stack-companion.tsx → hexclave-companion.tsx (with dir rename in §A)

KEEP (do not rename/delete):

• apps/dashboard/public/stack-auth-logo.svg, stack-auth-logo-bright.svg — old logo shown on purpose in hexclave-rebrand-modal.tsx.
• .github/assets/stack-webhooks.png — only if it still depicts current product; low priority, leave unless re-capturing.

---

D. Internal symbols & variables to rename (§6, §9)

All internal-only (not exported from any customer entrypoint). Stack* → Hexclave*, stack* → hexclave*.

packages/stack-shared (→ packages/shared):

• stackGlobalsSymbol (utils/globals.tsx) — the Symbol.for("__stack-globals") string is already __hexclave-globals; rename just the JS const.
• stackCapturedErrors (utils/errors.tsx), stackFs (utils/fs.tsx), stackPortPrefix (utils/redirect-urls.tsx), stackDevEnvStatePath (utils/dev-env-state-path.ts)
• stackAuthHost (loop var) + stackAuth (return-object key) in utils/cloud-hosts.tsx — internal shape, paired with a hexclave key; safe.
• stackAuthUser / stackAuthUserId (utils/featurebase.tsx), StackAuthUser type
• yup .meta() keys: stackSchemaInfo, stackConfigCanNoLongerBeOverridden, stackAllowUserIdMe, StackAdaptSentinel (schema-fields.ts, config/schema.ts) — internal metadata, renameable in lockstep
• stackApp / stackServerApp local vars in interface/page-component-versions.ts
• ⚠️ showOnboardingStackConfigValue — rename the identifier, but VERIFY its string value isn't persisted in DB config rows before changing the value (rename name only if value is persisted).

packages/template (regenerate after):

• stackAppInternalsSymbol const (lib/stack-app/common.ts) — rename the const; keep the dual Symbol.for("StackAuth--…") + Symbol.for("Hexclave--app-internals") strings (customer-visible, dual-attach).
• _StackClientAppImplIncomplete, _StackServerAppImplIncomplete, _StackAdminAppImplIncomplete, _StackClientAppImpl/Server/Admin, LazyStackAdminAppImpl (impl classes/index)
• StackContext (providers/stack-context.tsx), StackContextValue, StackProviderClient, StackHandlerClient, StackHandlerProps, StackSDK, StackAppInternals, StackAppTokenInternals, StackAppRequestInternals, StackDevTool, StackSimple, StackRouter, StackConfigValue/StackConfigObject/StackConfigFileContent, StackOAuthCallback, StackIcon, StackAuthHeaders, StackAppImport
• replaceStackPortPrefix (lib/stack-app/apps/implementations/common.ts)
• .stack-devtool CSS class (dev-tool-styles.ts + core) — rename className + selectors atomically. (Dev-tool storage/DOM keys STORAGE_KEY/ROOT_ID/etc. are already __hexclave-dev-tool-*.)

apps/backend:

• getStackStripe (lib/stripe.tsx), stackPortPrefix, expandStackPortPrefix (polyfills.tsx), stackAuthBaseUrl (oauth/index.tsx), stackAuthHost (loop var)
• getStackAuthApiBaseUrl (imported from shared — rename at source)
• in-process global cache keys __stack_actual_global_connection_string, __stack_actual_replica_connection_string, __stack_prisma_sigterm_registered (prisma-client.tsx) — process-local, safe
• ⚠️ __stackComponent (email-rendering.tsx) — VERIFY it's a runtime-only marker, not serialized into stored/rendered templates, before renaming.

apps/dashboard:

• stackAppInternalsSymbol (lib/stack-app-internals.ts + external-db-sync/page-client.tsx) — const rename, dual Symbol strings kept
• stackServerApp/stackAdminApp local vars, StackAdminAppContext, expandStackPortPrefix (polyfills.tsx), isStackAppTokenInternals/getStackAppTokenInternals
• data-stack-handler-page DOM attribute (internal)
• ⚠️ stack-scope CSS class (47×) — VERIFY it isn't referenced by the published @hexclave/dashboard-ui-components / saved create-dashboard outputs. If purely dashboard-internal, rename className + globals.css selector atomically; else keep.

Other apps: createStackMcpHandler (apps/mcp), and e2e helper names (expandStackPortPrefix, stackTestTenancyId, localRedirectUrl test consts) — rename freely (internal test harness).

---

E. Safe-to-reset cookies/storage/DOM (§8)

Rename outright (UI-only local state, a one-time reset is harmless):

• stack-devtool-trigger-position → already hexclave-devtool-trigger-position ✅ (confirm propagated)
• __stack-dev-tool-state/-root/-instance → already __hexclave-* ✅
• _STACK_AUTH.lastUsed (OAuth last-provider hint) → _HEXCLAVE.lastUsed
• dev-tool DOM ids/attrs, data-stack-handler-page

Keep backwards-compatible (persisted / cross-version / saved-state): main auth + OAuth cookies (stack-access, stack-refresh-*, stack-oauth-* — dual-write already), stack:session-replay:v1:* (LEGACY prefix, dual-read), iframe postMessage types + window.Stack* globals + STACK_EDITABLE_*/STACK_EXPR_* email-HTML markers (saved dashboards/templates), stack-init-id query param.

---

F. Brand strings to reword (§12)

Update "Stack Auth" / "Stack dashboard" / "Stack" product prose in code (docs handled separately):

• packages/stack-shared/src/known-errors.tsx — "…not a valid OAuth scope for Stack.", "…on the Stack dashboard…" (×2)
• apps/backend — check-version message, send-test-webhook body, init-script-callback telegram text, purchase-session "Stack Auth price ID", code comments
• apps/dashboard — OAuth confirm card alt text, domain-settings label, setup-page snippet labels
• The ~25 "Stack Auth" literals across 12 files from the first pass
• Init/CLI prompts: packages/stack-cli/src/commands/init.ts user-facing "Set up Stack Auth"/"Stack" strings

Keep brand strings that are intentional: the rebrand modal copy ("Stack Auth is now Hexclave"), compat comments documenting stack_response_mode / dual-emit, migration.mdx prose (the rebrand-explanation page must keep "Stack Auth").

docs-mintlify (DECIDED: in scope)

• Reword "Stack Auth" / "Stack" product prose throughout docs-mintlify/ (keep migration.mdx's intentional mentions + any explicit compat notes).
• Rename stack-named doc files: docs-mintlify/guides/going-further/stack-app.mdx, docs-mintlify/sdk/objects/stack-app.mdx, docs-mintlify/sdk/hooks/use-stack-app.mdx → hexclave-app.mdx / use-hexclave-app.mdx. Update docs.json nav entries and every internal cross-link (rg the old slugs). Add redirects if Mintlify supports them so old URLs don't 404.
• Leave tanstack-start doc dir/files alone (framework name).

---

G. doctor.ts & init prompt (§10)

• packages/stack-cli/src/commands/doctor.ts — config check looks only for stack.config.{ts,js}; make it prefer hexclave.config.ts and accept stack.config.ts as fallback (mirror config-file.ts discovery).
• packages/stack-cli/src/commands/init.ts prompt text ("Path to your existing stack.config.ts") — mention hexclave.config.ts (preferred) + stack.config.ts (legacy).

---

DO NOT TOUCH — verified compat-critical & false positives

Compat-critical (renaming breaks data/wire/cross-version):

• Crypto/vault/JWT domain-separation purpose tags — crypto.tsx, jwt.tsx, helpers/vault/* carry explicit do NOT rename notes (break decryption/verification of existing data).
• Brand sentinels stack-known-error-brand-sentinel, stack-status-error-brand-sentinel (known-errors.tsx, errors.tsx) — cross-version isKnownError/isStatusError checks across coexisting SDK copies.
• OTel telemetry attribute keys stack.external-db-sync.*, stack.db-replication.*, stack.prisma.transaction.* (observability dashboards; plan scopes observability out).
• DB table _stack_sync_metadata; webhook event type stack.test; IdP ids stack-preconfigured-idp:*.
• Bearer stackauth_ value; x-stack-* headers; stack-* cookies' legacy names; stack.config.ts fallback; *.stack-auth.com domains.
• Infra (plan-locked): Postgres DB stackframe, ClickHouse user stackframe, Docker image/container names (stack-backend, stack-local-emulator, stackframe-server), hostnames, STACK_AUTH_* GitHub secrets, stack-auth-config-sync.yml.
• Swift StackAuth package + StackClientApp/StackServerApp/StackAuthError symbols (frozen).
• MCP ask_stack_auth / server name stack-auth (kept; ask_hexclave already added).
• stack-auth-logo*.svg (old logo, used by rebrand modal).

False positives — contain "stack" but are NOT our brand:

• stackable / Stackable / StackableQuantityField / handleStackableChange / isStackableSelfMatch / "Stackable products…" — payments product feature ("can be purchased multiple times").
• Stacked* charts — StackedTooltip, StackedBarChartDisplay, StackedDataPoint, filterStackedDatapointsByTimeRange, emailStackedChartConfig — "stacked bar chart" charting term.
• TanStack / TanStackStart* / StackStart* (the 66 StackStartServerContext hits are the tail of TanStackStartServerContext), tanstackStartOnlyTemplateFiles — TanStack Start framework.
• OrbStack (resolveConnectionStringWithOrbStack) — third-party Docker tool; localstack.
• JS call-stack concepts (error.stack, stackTrace, stack-trace length) — not brand.

---

Execution order

1. Branch is ready (cl/hexclave-rename-pr5). Work in slices; lint/typecheck between slices.
2. Symbols/vars first (§D, §F, §G) inside packages/template + packages/stack-shared (mechanical, grep-driven), then apps/*. Verify the ⚠️ items (showOnboardingStackConfigValue value, __stackComponent, stack-scope) before touching them.
3. pnpm -w run generate-sdks to propagate template renames to js/react/stack/tanstack-start.
4. File renames (§C) via git mv, fix imports.
5. Directory renames (§A) via git mv; update tsconfig/turbo.json/pnpm-workspace.yaml/generate-sdks.ts; then a clean install (rm -rf node_modules && pnpm install --frozen-lockfile) — large workspace renames leave the .pnpm symlink layout half-stitched otherwise.
6. Package rename + init-stack deletion (§B); de-wire workspace/CI.
7. skills/stack-auth → skills/hexclave; [...stack] → [...hexclave] across dashboard/internal-tool/examples (§A).
8. docs-mintlify (§F): reword prose + rename stack-app.mdx/use-stack-app.mdx, fix docs.json nav + cross-links.
9. Force-rebuild (turbo run build --filter=./packages/* --force), then pnpm typecheck + pnpm lint.
10. Targeted tests: SDK build/import, CLI doctor/init, dashboard boot, e2e auth wire (must still pass with stack-named cookies/headers untouched).

Resolved decisions (review)

• Dir naming: drop the stack- prefix → packages/{next,shared,ui,sc,cli}.
• docs-mintlify: in scope — reword brand prose + rename stack-*.mdx files.
• [...stack]: rename to [...hexclave] (internal param key only; URL unchanged).

Still to verify during implementation (rename only if safe)

• showOnboardingStackConfigValue — is the string value persisted in DB config rows?
• __stackComponent — serialized into stored/rendered email templates?
• stack-scope CSS — referenced by published @hexclave/dashboard-ui-components or saved create-dashboard outputs?