@hexclave/shared 1.0.23 → 1.0.25

package/src/config-authoring.ts

@@ -27,11 +27,11 @@ type StrictStackConfig<T extends StackConfig> =
     : T;
 
 /** @deprecated Use `defineHexclaveConfig` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */
-export function defineStackConfig<const T extends StackConfig>(config: StrictStackConfig<T>): T {
+export function defineStackConfig(config: StrictStackConfig<StackConfig>): StackConfig {
   return config;
 }
 
 // Hexclave alias — separate function so it does not inherit the deprecation tag.
-export function defineHexclaveConfig<const T extends HexclaveConfig>(config: StrictStackConfig<T>): T {
+export function defineHexclaveConfig(config: StrictStackConfig<HexclaveConfig>): HexclaveConfig {
   return config;
 }

package/src/interface/crud/projects.ts

@@ -32,6 +32,14 @@ const enabledOAuthProviderSchema = yupObject({
   id: schemaFields.oauthIdSchema.defined(),
 });
 
+const pushedConfigErrorSchema = yupObject({
+  message: yupString().defined(),
+}).defined();
+
+const configWarningSchema = yupObject({
+  message: yupString().defined(),
+}).defined();
+
 const onboardingConfigChoiceValues = ["create-new", "link-existing"] as const;
 const onboardingSignInMethodValues = ["credential", "magicLink", "passkey", "google", "github", "microsoft"] as const;
 const onboardingPaymentsCountryValues = ["US", "OTHER"] as const;
@@ -89,6 +97,8 @@ export const projectsCrudAdminReadSchema = yupObject({
   owner_team_id: schemaFields.yupString().nullable().defined(),
   onboarding_status: schemaFields.projectOnboardingStatusSchema.defined(),
   onboarding_state: projectOnboardingStateSchema.nullable().optional(),
+  pushed_config_error: pushedConfigErrorSchema.nullable().defined(),
+  config_warnings: yupArray(configWarningSchema).defined(),
   /** @deprecated */
   config: yupObject({
     allow_localhost: schemaFields.projectAllowLocalhostSchema.defined(),
@@ -117,6 +127,8 @@ export const projectsCrudAdminReadSchema = yupObject({
 export const projectsCrudClientReadSchema = yupObject({
   id: schemaFields.projectIdSchema.defined(),
   display_name: schemaFields.projectDisplayNameSchema.defined(),
+  pushed_config_error: pushedConfigErrorSchema.nullable().defined(),
+  config_warnings: yupArray(configWarningSchema).defined(),
   config: yupObject({
     sign_up_enabled: schemaFields.projectSignUpEnabledSchema.defined(),
     credential_enabled: schemaFields.projectCredentialEnabledSchema.defined(),

package/src/utils/env.test.tsx

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getEnvVariable, getProcessEnv, resolveHexclaveStackEnvVarValue } from "./env";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("Hexclave/Stack env var dual-read", () => {
+  it("falls back to the legacy Stack name when the Hexclave value is empty", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_API_URL", "");
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://stack.example.test");
+
+    expect(getEnvVariable("NEXT_PUBLIC_STACK_API_URL")).toBe("https://stack.example.test");
+    expect(getProcessEnv("NEXT_PUBLIC_STACK_API_URL")).toBe("https://stack.example.test");
+  });
+
+  it("allows both names when they have the same non-empty value", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_API_URL", "https://api.example.test");
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://api.example.test");
+
+    expect(getEnvVariable("NEXT_PUBLIC_STACK_API_URL")).toBe("https://api.example.test");
+    expect(getProcessEnv("NEXT_PUBLIC_STACK_API_URL")).toBe("https://api.example.test");
+  });
+
+  it("throws when both names are non-empty and different", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_API_URL", "https://hexclave.example.test");
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://stack.example.test");
+
+    expect(() => getEnvVariable("NEXT_PUBLIC_STACK_API_URL")).toThrow(/NEXT_PUBLIC_HEXCLAVE_API_URL.*NEXT_PUBLIC_STACK_API_URL.*different values/);
+    expect(() => getProcessEnv("NEXT_PUBLIC_STACK_API_URL")).toThrow(/NEXT_PUBLIC_HEXCLAVE_API_URL.*NEXT_PUBLIC_STACK_API_URL.*different values/);
+  });
+
+  it("checks renamed legacy aliases when falling back", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_URL", "https://hexclave-url.example.test");
+    vi.stubEnv("NEXT_PUBLIC_STACK_URL", "https://stack-url.example.test");
+
+    expect(() => getEnvVariable("NEXT_PUBLIC_STACK_API_URL")).toThrow(/NEXT_PUBLIC_HEXCLAVE_URL.*NEXT_PUBLIC_STACK_URL.*different values/);
+  });
+
+  it("returns undefined when both names are empty", () => {
+    expect(resolveHexclaveStackEnvVarValue("HEXCLAVE_FOO", "STACK_FOO", "", "")).toBeUndefined();
+  });
+
+  it("falls back to the legacy Stack name when a canonical Hexclave name is looked up", () => {
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://stack.example.test");
+
+    // Caller passes the canonical HEXCLAVE_ name but only the legacy value is set.
+    expect(getEnvVariable("NEXT_PUBLIC_HEXCLAVE_API_URL")).toBe("https://stack.example.test");
+    expect(getProcessEnv("NEXT_PUBLIC_HEXCLAVE_API_URL")).toBe("https://stack.example.test");
+  });
+
+  it("throws on a conflict when a canonical Hexclave name is looked up", () => {
+    vi.stubEnv("NEXT_PUBLIC_HEXCLAVE_API_URL", "https://hexclave.example.test");
+    vi.stubEnv("NEXT_PUBLIC_STACK_API_URL", "https://stack.example.test");
+
+    expect(() => getEnvVariable("NEXT_PUBLIC_HEXCLAVE_API_URL")).toThrow(/NEXT_PUBLIC_HEXCLAVE_API_URL.*NEXT_PUBLIC_STACK_API_URL.*different values/);
+  });
+});

package/src/utils/env.tsx

@@ -6,22 +6,37 @@ export function isBrowserLike() {
 }
 
 // newName: oldName
-const ENV_VAR_RENAME: Record<string, string[]> = {
+const ENV_VAR_RENAME: Record<string, string[] | undefined> = {
   NEXT_PUBLIC_STACK_API_URL: ['STACK_BASE_URL', 'NEXT_PUBLIC_STACK_URL'],
 };
 
+export function resolveHexclaveStackEnvVarValue(hexclaveName: string, stackName: string, hexclaveValue: string | undefined, stackValue: string | undefined): string | undefined {
+  if (hexclaveValue && stackValue && hexclaveValue !== stackValue) {
+    throw new Error(`Environment variables ${hexclaveName} and ${stackName} are both set to different values. Remove one of them or set them to the same value.`);
+  }
+  return hexclaveValue || stackValue || undefined;
+}
+
 /**
- * Hexclave rebrand: compute the `HEXCLAVE_*`-prefixed equivalent of a `STACK_*`
- * env var name by replacing the first `STACK_` occurrence with `HEXCLAVE_`.
- * Covers `STACK_FOO`, `NEXT_PUBLIC_STACK_FOO`, `NEXT_PUBLIC_BROWSER_STACK_FOO`,
- * `NEXT_PUBLIC_SERVER_STACK_FOO`, `VITE_STACK_FOO`. Returns `undefined` when the
- * name has no `STACK_` segment (caller should behave exactly as before).
+ * Hexclave rebrand: resolve an env var by reading both the `HEXCLAVE_*` and
+ * `STACK_*` spellings, preferring the canonical Hexclave value and falling back
+ * to the legacy Stack value (empty counts as unset). Works in BOTH directions —
+ * whether the caller passes the legacy `STACK_FOO` name or the canonical
+ * `HEXCLAVE_FOO` name, the other spelling is still honored. Covers `STACK_FOO`,
+ * `NEXT_PUBLIC_STACK_FOO`, `NEXT_PUBLIC_BROWSER_STACK_FOO`,
+ * `NEXT_PUBLIC_SERVER_STACK_FOO`, `VITE_STACK_FOO` and their HEXCLAVE_ twins.
+ * Names with neither segment behave exactly as before.
  */
-function getHexclaveEnvVarName(name: string): string | undefined {
-  if (!name.includes("STACK_")) {
-    return undefined;
+function getEnvVarWithHexclaveFallback(name: string): string | undefined {
+  if (name.includes("STACK_")) {
+    const hexclaveName = name.replace("STACK_", "HEXCLAVE_");
+    return resolveHexclaveStackEnvVarValue(hexclaveName, name, process.env[hexclaveName], process.env[name]);
+  }
+  if (name.includes("HEXCLAVE_")) {
+    const stackName = name.replace("HEXCLAVE_", "STACK_");
+    return resolveHexclaveStackEnvVarValue(name, stackName, process.env[name], process.env[stackName]);
   }
-  return name.replace("STACK_", "HEXCLAVE_");
+  return process.env[name];
 }
 
 /**
@@ -45,21 +60,21 @@ export function getEnvVariable(name: string, defaultValue?: string | undefined):
 
   // throw error if the old name is used as the retrieve key
   for (const [newName, oldNames] of Object.entries(ENV_VAR_RENAME)) {
-    if (oldNames.includes(name)) {
+    if (oldNames?.includes(name)) {
       throwErr(`Environment variable ${name} has been renamed to ${newName}. Please update your configuration to use the new name.`);
     }
   }
 
   // Hexclave rebrand: prefer the HEXCLAVE_*-prefixed equivalent, fall back to the STACK_* name.
-  const hexclaveName = getHexclaveEnvVarName(name);
-  let value = (hexclaveName ? process.env[hexclaveName] : undefined) ?? process.env[name];
+  // Treat the empty string as unset — the checked-in .env templates define empty
+  // HEXCLAVE_* placeholders, which must not shadow a real value under the legacy name.
+  let value = getEnvVarWithHexclaveFallback(name);
 
   // check the key under the old name if the new name is not found
-  if (!value && ENV_VAR_RENAME[name] as any) {
-    for (const oldName of ENV_VAR_RENAME[name]) {
-      // Hexclave rebrand: also accept the HEXCLAVE_*-prefixed equivalent of each old alias.
-      const hexclaveOldName = getHexclaveEnvVarName(oldName);
-      value = (hexclaveOldName ? process.env[hexclaveOldName] : undefined) ?? process.env[oldName];
+  const renamedNames = ENV_VAR_RENAME[name];
+  if (!value && renamedNames != null) {
+    for (const oldName of renamedNames) {
+      value = getEnvVarWithHexclaveFallback(oldName);
       if (value) break;
     }
   }
@@ -112,6 +127,7 @@ export function getProcessEnv(name: string): string | undefined {
     return undefined;
   }
   // Hexclave rebrand: prefer the HEXCLAVE_*-prefixed equivalent, fall back to the STACK_* name.
-  const hexclaveName = getHexclaveEnvVarName(name);
-  return (hexclaveName ? process.env[hexclaveName] : undefined) ?? process.env[name];
+  // Empty counts as unset — the checked-in .env templates define empty HEXCLAVE_* placeholders,
+  // which must not shadow a real value under the legacy name.
+  return getEnvVarWithHexclaveFallback(name);
 }

package/src/utils/errors.tsx

@@ -80,7 +80,12 @@ export class HexclaveAssertionError extends Error {
 
     // Use literal dot-form (guarded with `typeof process`) so Next.js / webpack
     // DefinePlugin can inline the value at build time. See getProcessEnv in ./env.
-    if ((typeof process !== "undefined" ? process.env.NEXT_PUBLIC_STACK_DEBUGGER_ON_ASSERTION_ERROR : undefined) === "true") {
+    const hexclaveDebuggerValue = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_HEXCLAVE_DEBUGGER_ON_ASSERTION_ERROR : undefined;
+    const stackDebuggerValue = typeof process !== "undefined" ? process.env.NEXT_PUBLIC_STACK_DEBUGGER_ON_ASSERTION_ERROR : undefined;
+    if (hexclaveDebuggerValue && stackDebuggerValue && hexclaveDebuggerValue !== stackDebuggerValue) {
+      throw new Error("Environment variables NEXT_PUBLIC_HEXCLAVE_DEBUGGER_ON_ASSERTION_ERROR and NEXT_PUBLIC_STACK_DEBUGGER_ON_ASSERTION_ERROR are both set to different values. Remove one of them or set them to the same value.");
+    }
+    if ((hexclaveDebuggerValue || stackDebuggerValue) === "true") {
       debugger;
     }
   }