@stardeck-customer-apps/testing 0.9.0 → 0.10.0

package/SKILL.md

@@ -29,6 +29,65 @@ This writes `src/generated/data-store-types.ts` and
 `src/generated/data-store-schema.sql`. The harness applies the SQL snapshot to
 PGlite at test boot. **Commit both files.**
 
+### Data store bindings
+
+Configure each app-local data store binding once in `vitest.config.ts`. The
+harness injects the same `STARDECK_DATA_STORES` manifest shape as production, so
+application code resolves the binding without test-only branches:
+
+```ts
+import { defineStardeckTestConfig } from "@stardeck-customer-apps/testing/config";
+
+export default defineStardeckTestConfig(
+  {},
+  {
+    dataStores: [{ bindingKey: "development" }],
+  }
+);
+```
+
+```ts
+import { createDataStore } from "@stardeck-customer-apps/data-store-sdk/server";
+
+const db = await createDataStore({ storeName: "development" });
+```
+
+Do not branch on `DATA_STORE_URL?.includes(".stardeck.test")` or otherwise
+sniff test hosts. Configure the binding and use `createDataStore({ storeName })`
+the same way in tests and production.
+
+For one test file that needs a different manifest, pass the same entries to the
+app instead. This overrides the config-level manifest for that file:
+
+```ts
+app = await createTestApp({
+  dataStores: [
+    { bindingKey: "development" },
+    { bindingKey: "uploads", name: "Customer Files", storeType: "storage" },
+  ],
+});
+```
+
+An app setup file may also set `STARDECK_DATA_STORES` directly. The harness
+adopts a non-empty raw env value when `createTestApp()` has no `dataStores`
+option; a per-app `dataStores` option still overrides it. An empty env value is
+treated as unset, matching the SDK manifest parser.
+
+Strictness follows adoption:
+
+- With no manifest configuration, `createTestApp()` injects a `main` database
+  entry and keeps `DATA_STORE_URL` for older bare `createDataStore()` calls.
+- Configuring `dataStores` through either channel removes `DATA_STORE_URL` by
+  default. A misspelled `storeName` then fails instead of silently connecting to
+  the default database.
+- Passing `dataStores: []` explicitly creates a strict zero-store test world:
+  the manifest is `[]`, `DATA_STORE_URL` is absent, and every
+  `createDataStore(...)` call fails until a store is configured.
+- Empty-string `bindingKey`, `slug`, or `name` values throw during test app
+  setup so typos cannot silently change manifest resolution.
+- Set `legacyDataStoreUrl: true` per file only while migrating legacy code. Set
+  it to `false` to test strict manifest-only resolution even with zero config.
+
 ## Writing tests
 
 ```ts
@@ -186,7 +245,14 @@ expect(app.edge.latestDisplay()?.action).toBe("show");
 
 - `createTestApp(options)` — boots PGlite + the control-plane simulator and
   sets all Stardeck env vars (`CONTROL_PLANE_URL`, `DEPLOYMENT_SECRET`,
-  `DATA_STORE_URL`, ids). One per test file, in `beforeAll`.
+  `STARDECK_DATA_STORES`, ids, and the legacy `DATA_STORE_URL` when enabled).
+  One per test file, in `beforeAll`.
+  - `dataStores` — per-file production-shaped data store manifest entries. The
+    first entry defaults to slug `main`; later entries need a `slug` or `name`.
+    Pass `[]` for strict zero-store mode. Empty `bindingKey`, `slug`, and `name`
+    values are rejected.
+  - `legacyDataStoreUrl` — force the legacy single-store URL on or off. When
+    omitted, it is on only for zero-config tests and off after manifest adoption.
   - `schema` — path to the DDL snapshot (default
     `./src/generated/data-store-schema.sql`); `null` for apps without a store.
   - `schemaSql` — inline DDL instead of a file.

package/dist/config.d.mts

@@ -1,5 +1,9 @@
 import { ViteUserConfig } from 'vitest/config';
+import { T as TestDataStoreInput } from './data-store-manifest-Zwgcv0DJ.mjs';
 
+interface StardeckTestConfigOptions {
+    dataStores?: TestDataStoreInput[];
+}
 /**
  * Vitest config for Stardeck customer apps. Aliases `next/headers` (and
  * `server-only`) to harness shims so server code runs outside a Next request
@@ -11,6 +15,6 @@ import { ViteUserConfig } from 'vitest/config';
  * export default defineStardeckTestConfig();
  * ```
  */
-declare function defineStardeckTestConfig(overrides?: ViteUserConfig): ViteUserConfig;
+declare function defineStardeckTestConfig(overrides?: ViteUserConfig, stardeck?: StardeckTestConfigOptions): ViteUserConfig;
 
-export { defineStardeckTestConfig };
+export { type StardeckTestConfigOptions, defineStardeckTestConfig };

package/dist/config.d.ts

@@ -1,5 +1,9 @@
 import { ViteUserConfig } from 'vitest/config';
+import { T as TestDataStoreInput } from './data-store-manifest-Zwgcv0DJ.js';
 
+interface StardeckTestConfigOptions {
+    dataStores?: TestDataStoreInput[];
+}
 /**
  * Vitest config for Stardeck customer apps. Aliases `next/headers` (and
  * `server-only`) to harness shims so server code runs outside a Next request
@@ -11,6 +15,6 @@ import { ViteUserConfig } from 'vitest/config';
  * export default defineStardeckTestConfig();
  * ```
  */
-declare function defineStardeckTestConfig(overrides?: ViteUserConfig): ViteUserConfig;
+declare function defineStardeckTestConfig(overrides?: ViteUserConfig, stardeck?: StardeckTestConfigOptions): ViteUserConfig;
 
-export { defineStardeckTestConfig };
+export { type StardeckTestConfigOptions, defineStardeckTestConfig };

package/dist/config.js

@@ -23,7 +23,77 @@ __export(config_exports, {
   defineStardeckTestConfig: () => defineStardeckTestConfig
 });
 module.exports = __toCommonJS(config_exports);
-function defineStardeckTestConfig(overrides = {}) {
+
+// src/constants.ts
+var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
+
+// src/data-store-manifest.ts
+var STARDECK_DATA_STORES_ENV = "STARDECK_DATA_STORES";
+function dataStoreSlug(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return slug || "store";
+}
+function buildTestDataStoreManifest(inputs = [{}]) {
+  const takenSlugs = /* @__PURE__ */ new Set();
+  const takenBindingKeys = /* @__PURE__ */ new Set();
+  const takenIds = /* @__PURE__ */ new Set();
+  return inputs.map((input, index) => {
+    for (const field of ["bindingKey", "slug", "name"]) {
+      if (input[field] === "") {
+        throw new Error(`[stardeck-testing] dataStores[${index}].${field} cannot be empty.`);
+      }
+    }
+    let slug;
+    if (input.slug !== void 0) {
+      slug = input.slug;
+      if (takenSlugs.has(slug)) {
+        throw new Error(`[stardeck-testing] dataStores[${index}].slug must be unique.`);
+      }
+    } else {
+      const base = input.name !== void 0 ? dataStoreSlug(input.name) : index === 0 ? "main" : null;
+      if (base === null) {
+        throw new Error(
+          `[stardeck-testing] dataStores[${index}] requires a slug or name. Only the first entry defaults to the "main" slug.`
+        );
+      }
+      slug = base;
+      let suffix = 2;
+      while (takenSlugs.has(slug)) {
+        slug = `${base}_${suffix}`;
+        suffix++;
+      }
+    }
+    const id = input.id ?? `00000000-0000-4000-8000-${String(index + 1).padStart(12, "0")}`;
+    if (takenIds.has(id)) {
+      throw new Error(`[stardeck-testing] dataStores[${index}].id must be unique.`);
+    }
+    if (input.bindingKey !== void 0 && takenBindingKeys.has(input.bindingKey)) {
+      throw new Error(`[stardeck-testing] dataStores[${index}].bindingKey must be unique.`);
+    }
+    takenSlugs.add(slug);
+    takenIds.add(id);
+    if (input.bindingKey !== void 0) takenBindingKeys.add(input.bindingKey);
+    const storeType = input.storeType ?? "database";
+    return {
+      id,
+      name: input.name ?? slug,
+      slug,
+      storeType,
+      accessLevel: input.accessLevel ?? "admin",
+      ...storeType === "database" ? { url: input.url ?? DATA_STORE_TEST_URL } : {},
+      ...input.bindingKey ? { bindingKey: input.bindingKey } : {}
+    };
+  });
+}
+
+// src/config.ts
+function defineStardeckTestConfig(overrides = {}, stardeck = {}) {
+  const dataStoreEnv = stardeck.dataStores !== void 0 ? {
+    [STARDECK_DATA_STORES_ENV]: JSON.stringify(
+      buildTestDataStoreManifest(stardeck.dataStores)
+    )
+  } : {};
   return {
     ...overrides,
     resolve: {
@@ -44,6 +114,10 @@ function defineStardeckTestConfig(overrides = {}) {
       pool: "forks",
       isolate: true,
       ...overrides.test,
+      env: {
+        ...dataStoreEnv,
+        ...overrides.test?.env
+      },
       setupFiles: [
         "@stardeck-customer-apps/testing/setup",
         ...overrides.test?.setupFiles ? Array.isArray(overrides.test.setupFiles) ? overrides.test.setupFiles : [overrides.test.setupFiles] : []

package/dist/config.mjs

@@ -1,5 +1,73 @@
+// src/constants.ts
+var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
+
+// src/data-store-manifest.ts
+var STARDECK_DATA_STORES_ENV = "STARDECK_DATA_STORES";
+function dataStoreSlug(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return slug || "store";
+}
+function buildTestDataStoreManifest(inputs = [{}]) {
+  const takenSlugs = /* @__PURE__ */ new Set();
+  const takenBindingKeys = /* @__PURE__ */ new Set();
+  const takenIds = /* @__PURE__ */ new Set();
+  return inputs.map((input, index) => {
+    for (const field of ["bindingKey", "slug", "name"]) {
+      if (input[field] === "") {
+        throw new Error(`[stardeck-testing] dataStores[${index}].${field} cannot be empty.`);
+      }
+    }
+    let slug;
+    if (input.slug !== void 0) {
+      slug = input.slug;
+      if (takenSlugs.has(slug)) {
+        throw new Error(`[stardeck-testing] dataStores[${index}].slug must be unique.`);
+      }
+    } else {
+      const base = input.name !== void 0 ? dataStoreSlug(input.name) : index === 0 ? "main" : null;
+      if (base === null) {
+        throw new Error(
+          `[stardeck-testing] dataStores[${index}] requires a slug or name. Only the first entry defaults to the "main" slug.`
+        );
+      }
+      slug = base;
+      let suffix = 2;
+      while (takenSlugs.has(slug)) {
+        slug = `${base}_${suffix}`;
+        suffix++;
+      }
+    }
+    const id = input.id ?? `00000000-0000-4000-8000-${String(index + 1).padStart(12, "0")}`;
+    if (takenIds.has(id)) {
+      throw new Error(`[stardeck-testing] dataStores[${index}].id must be unique.`);
+    }
+    if (input.bindingKey !== void 0 && takenBindingKeys.has(input.bindingKey)) {
+      throw new Error(`[stardeck-testing] dataStores[${index}].bindingKey must be unique.`);
+    }
+    takenSlugs.add(slug);
+    takenIds.add(id);
+    if (input.bindingKey !== void 0) takenBindingKeys.add(input.bindingKey);
+    const storeType = input.storeType ?? "database";
+    return {
+      id,
+      name: input.name ?? slug,
+      slug,
+      storeType,
+      accessLevel: input.accessLevel ?? "admin",
+      ...storeType === "database" ? { url: input.url ?? DATA_STORE_TEST_URL } : {},
+      ...input.bindingKey ? { bindingKey: input.bindingKey } : {}
+    };
+  });
+}
+
 // src/config.ts
-function defineStardeckTestConfig(overrides = {}) {
+function defineStardeckTestConfig(overrides = {}, stardeck = {}) {
+  const dataStoreEnv = stardeck.dataStores !== void 0 ? {
+    [STARDECK_DATA_STORES_ENV]: JSON.stringify(
+      buildTestDataStoreManifest(stardeck.dataStores)
+    )
+  } : {};
   return {
     ...overrides,
     resolve: {
@@ -20,6 +88,10 @@ function defineStardeckTestConfig(overrides = {}) {
       pool: "forks",
       isolate: true,
       ...overrides.test,
+      env: {
+        ...dataStoreEnv,
+        ...overrides.test?.env
+      },
       setupFiles: [
         "@stardeck-customer-apps/testing/setup",
         ...overrides.test?.setupFiles ? Array.isArray(overrides.test.setupFiles) ? overrides.test.setupFiles : [overrides.test.setupFiles] : []

package/dist/data-store-manifest-Zwgcv0DJ.d.mts

@@ -0,0 +1,25 @@
+declare const STARDECK_DATA_STORES_ENV = "STARDECK_DATA_STORES";
+interface TestDataStoreInput {
+    bindingKey?: string;
+    /** Stable snake_case handle for the store. */
+    slug?: string;
+    name?: string;
+    id?: string;
+    accessLevel?: "read" | "write" | "admin";
+    storeType?: "database" | "storage";
+    /** Defaults to the PGlite simulator URL for database stores. */
+    url?: string;
+}
+interface TestDataStoreManifestEntry {
+    id: string;
+    name: string;
+    slug: string;
+    storeType: "database" | "storage";
+    accessLevel: "read" | "write" | "admin";
+    url?: string;
+    bindingKey?: string;
+}
+/** Builds the production-shaped manifest injected into a test app. */
+declare function buildTestDataStoreManifest(inputs?: TestDataStoreInput[]): TestDataStoreManifestEntry[];
+
+export { STARDECK_DATA_STORES_ENV as S, type TestDataStoreInput as T, type TestDataStoreManifestEntry as a, buildTestDataStoreManifest as b };

package/dist/data-store-manifest-Zwgcv0DJ.d.ts

@@ -0,0 +1,25 @@
+declare const STARDECK_DATA_STORES_ENV = "STARDECK_DATA_STORES";
+interface TestDataStoreInput {
+    bindingKey?: string;
+    /** Stable snake_case handle for the store. */
+    slug?: string;
+    name?: string;
+    id?: string;
+    accessLevel?: "read" | "write" | "admin";
+    storeType?: "database" | "storage";
+    /** Defaults to the PGlite simulator URL for database stores. */
+    url?: string;
+}
+interface TestDataStoreManifestEntry {
+    id: string;
+    name: string;
+    slug: string;
+    storeType: "database" | "storage";
+    accessLevel: "read" | "write" | "admin";
+    url?: string;
+    bindingKey?: string;
+}
+/** Builds the production-shaped manifest injected into a test app. */
+declare function buildTestDataStoreManifest(inputs?: TestDataStoreInput[]): TestDataStoreManifestEntry[];
+
+export { STARDECK_DATA_STORES_ENV as S, type TestDataStoreInput as T, type TestDataStoreManifestEntry as a, buildTestDataStoreManifest as b };

package/dist/index.d.mts

@@ -1,6 +1,8 @@
 import * as _stardeck_customer_apps_payments_sdk from '@stardeck-customer-apps/payments-sdk';
 import * as next_server from 'next/server';
 import { PGlite } from '@electric-sql/pglite';
+import { T as TestDataStoreInput } from './data-store-manifest-Zwgcv0DJ.mjs';
+export { S as STARDECK_DATA_STORES_ENV, a as TestDataStoreManifestEntry, b as buildTestDataStoreManifest } from './data-store-manifest-Zwgcv0DJ.mjs';
 
 type RouteHandler<Req extends Request = Request, P = Record<string, string | string[]>> = (request: Req, context: {
     params: Promise<P>;
@@ -437,6 +439,13 @@ interface TestEdge {
     get count(): number;
 }
 interface TestAppOptions {
+    /** Data stores exposed through the production-shaped STARDECK_DATA_STORES manifest. */
+    dataStores?: TestDataStoreInput[];
+    /**
+     * Force the legacy single-store DATA_STORE_URL on or off. By default it is
+     * present only for the zero-config manifest, and omitted once a manifest is configured.
+     */
+    legacyDataStoreUrl?: boolean;
     /**
      * Path to the schema.sql snapshot generated by
      * `npx stardeck-data-store generate-types` (relative to the project root).
@@ -517,6 +526,7 @@ declare function parseWorkflowName(describeTitle: string): string | null;
 
 declare const CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
 declare const DATA_STORE_TEST_HOST = "db.stardeck.test";
+declare const DATA_STORE_TEST_URL = "postgresql://test:test@db.stardeck.test/main";
 declare const STORAGE_TEST_URL = "https://storage.stardeck.test";
 declare const STORAGE_TEST_HOST = "storage.stardeck.test";
 declare const TEST_ENV_DEFAULTS: {
@@ -525,10 +535,9 @@ declare const TEST_ENV_DEFAULTS: {
     readonly ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a";
     readonly PROJECT_ID: "00000000-0000-4000-8000-00000000000b";
     readonly DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c";
-    readonly DATA_STORE_URL: "postgresql://test:test@db.stardeck.test/main";
     readonly STORAGE_URL: "https://storage.stardeck.test";
 };
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };
+export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DATA_STORE_TEST_URL, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, TestDataStoreInput, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import * as _stardeck_customer_apps_payments_sdk from '@stardeck-customer-apps/payments-sdk';
 import * as next_server from 'next/server';
 import { PGlite } from '@electric-sql/pglite';
+import { T as TestDataStoreInput } from './data-store-manifest-Zwgcv0DJ.js';
+export { S as STARDECK_DATA_STORES_ENV, a as TestDataStoreManifestEntry, b as buildTestDataStoreManifest } from './data-store-manifest-Zwgcv0DJ.js';
 
 type RouteHandler<Req extends Request = Request, P = Record<string, string | string[]>> = (request: Req, context: {
     params: Promise<P>;
@@ -437,6 +439,13 @@ interface TestEdge {
     get count(): number;
 }
 interface TestAppOptions {
+    /** Data stores exposed through the production-shaped STARDECK_DATA_STORES manifest. */
+    dataStores?: TestDataStoreInput[];
+    /**
+     * Force the legacy single-store DATA_STORE_URL on or off. By default it is
+     * present only for the zero-config manifest, and omitted once a manifest is configured.
+     */
+    legacyDataStoreUrl?: boolean;
     /**
      * Path to the schema.sql snapshot generated by
      * `npx stardeck-data-store generate-types` (relative to the project root).
@@ -517,6 +526,7 @@ declare function parseWorkflowName(describeTitle: string): string | null;
 
 declare const CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
 declare const DATA_STORE_TEST_HOST = "db.stardeck.test";
+declare const DATA_STORE_TEST_URL = "postgresql://test:test@db.stardeck.test/main";
 declare const STORAGE_TEST_URL = "https://storage.stardeck.test";
 declare const STORAGE_TEST_HOST = "storage.stardeck.test";
 declare const TEST_ENV_DEFAULTS: {
@@ -525,10 +535,9 @@ declare const TEST_ENV_DEFAULTS: {
     readonly ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a";
     readonly PROJECT_ID: "00000000-0000-4000-8000-00000000000b";
     readonly DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c";
-    readonly DATA_STORE_URL: "postgresql://test:test@db.stardeck.test/main";
     readonly STORAGE_URL: "https://storage.stardeck.test";
 };
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };
+export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DATA_STORE_TEST_URL, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, TestDataStoreInput, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };

package/dist/index.js

@@ -32,11 +32,14 @@ var index_exports = {};
 __export(index_exports, {
   CONTROL_PLANE_TEST_URL: () => CONTROL_PLANE_TEST_URL,
   DATA_STORE_TEST_HOST: () => DATA_STORE_TEST_HOST,
+  DATA_STORE_TEST_URL: () => DATA_STORE_TEST_URL,
   DEFAULT_SCHEMA_PATH: () => DEFAULT_SCHEMA_PATH,
+  STARDECK_DATA_STORES_ENV: () => STARDECK_DATA_STORES_ENV,
   STORAGE_TEST_HOST: () => STORAGE_TEST_HOST,
   STORAGE_TEST_URL: () => STORAGE_TEST_URL,
   TEST_ENV_DEFAULTS: () => TEST_ENV_DEFAULTS,
   WORKFLOW_NAME_PREFIX: () => WORKFLOW_NAME_PREFIX,
+  buildTestDataStoreManifest: () => buildTestDataStoreManifest,
   callRoute: () => callRoute,
   createTestApp: () => createTestApp,
   describeWorkflow: () => describeWorkflow,
@@ -93,6 +96,7 @@ function globalSingleton(key, create) {
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
+  lastHarnessDataStoreManifest: null,
   currentUser: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
@@ -141,6 +145,7 @@ function requireDb() {
 var TEST_DOMAIN_SUFFIX = ".stardeck.test";
 var CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
 var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
 var STORAGE_TEST_URL = "https://storage.stardeck.test";
 var STORAGE_TEST_HOST = "storage.stardeck.test";
 var TEST_ENV_DEFAULTS = {
@@ -149,7 +154,6 @@ var TEST_ENV_DEFAULTS = {
   ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a",
   PROJECT_ID: "00000000-0000-4000-8000-00000000000b",
   DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c",
-  DATA_STORE_URL: `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`,
   STORAGE_URL: STORAGE_TEST_URL
 };
 var DEFAULT_TEST_USER = {
@@ -2603,11 +2607,89 @@ function uninstallFetchRouter() {
   }
 }
 
+// src/data-store-manifest.ts
+var STARDECK_DATA_STORES_ENV = "STARDECK_DATA_STORES";
+function dataStoreSlug(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return slug || "store";
+}
+function buildTestDataStoreManifest(inputs = [{}]) {
+  const takenSlugs = /* @__PURE__ */ new Set();
+  const takenBindingKeys = /* @__PURE__ */ new Set();
+  const takenIds = /* @__PURE__ */ new Set();
+  return inputs.map((input, index) => {
+    for (const field of ["bindingKey", "slug", "name"]) {
+      if (input[field] === "") {
+        throw new Error(`[stardeck-testing] dataStores[${index}].${field} cannot be empty.`);
+      }
+    }
+    let slug;
+    if (input.slug !== void 0) {
+      slug = input.slug;
+      if (takenSlugs.has(slug)) {
+        throw new Error(`[stardeck-testing] dataStores[${index}].slug must be unique.`);
+      }
+    } else {
+      const base = input.name !== void 0 ? dataStoreSlug(input.name) : index === 0 ? "main" : null;
+      if (base === null) {
+        throw new Error(
+          `[stardeck-testing] dataStores[${index}] requires a slug or name. Only the first entry defaults to the "main" slug.`
+        );
+      }
+      slug = base;
+      let suffix = 2;
+      while (takenSlugs.has(slug)) {
+        slug = `${base}_${suffix}`;
+        suffix++;
+      }
+    }
+    const id = input.id ?? `00000000-0000-4000-8000-${String(index + 1).padStart(12, "0")}`;
+    if (takenIds.has(id)) {
+      throw new Error(`[stardeck-testing] dataStores[${index}].id must be unique.`);
+    }
+    if (input.bindingKey !== void 0 && takenBindingKeys.has(input.bindingKey)) {
+      throw new Error(`[stardeck-testing] dataStores[${index}].bindingKey must be unique.`);
+    }
+    takenSlugs.add(slug);
+    takenIds.add(id);
+    if (input.bindingKey !== void 0) takenBindingKeys.add(input.bindingKey);
+    const storeType = input.storeType ?? "database";
+    return {
+      id,
+      name: input.name ?? slug,
+      slug,
+      storeType,
+      accessLevel: input.accessLevel ?? "admin",
+      ...storeType === "database" ? { url: input.url ?? DATA_STORE_TEST_URL } : {},
+      ...input.bindingKey ? { bindingKey: input.bindingKey } : {}
+    };
+  });
+}
+
 // src/test-app.ts
-function applyTestEnv() {
+function applyTestEnv(options) {
   for (const [key, value] of Object.entries(TEST_ENV_DEFAULTS)) {
     process.env[key] = value;
   }
+  let manifestAdopted = true;
+  if (options.dataStores !== void 0) {
+    const manifest = JSON.stringify(buildTestDataStoreManifest(options.dataStores));
+    process.env[STARDECK_DATA_STORES_ENV] = manifest;
+    state.lastHarnessDataStoreManifest = manifest;
+  } else {
+    const currentManifest = process.env[STARDECK_DATA_STORES_ENV];
+    if (!currentManifest || currentManifest === state.lastHarnessDataStoreManifest) {
+      const manifest = JSON.stringify(buildTestDataStoreManifest());
+      process.env[STARDECK_DATA_STORES_ENV] = manifest;
+      state.lastHarnessDataStoreManifest = manifest;
+      manifestAdopted = false;
+    }
+  }
+  if (options.legacyDataStoreUrl === true || !manifestAdopted && options.legacyDataStoreUrl === void 0) {
+    process.env.DATA_STORE_URL = DATA_STORE_TEST_URL;
+  } else {
+    delete process.env.DATA_STORE_URL;
+  }
   delete process.env.DISABLE_AUTH;
   delete process.env.NEXT_PUBLIC_DISABLE_AUTH;
   delete process.env.SANDBOX_MODE;
@@ -2640,7 +2722,7 @@ async function createTestApp(options = {}) {
       "[stardeck-testing] A test app is already active in this test file. Call `app.close()` first, or share one app per file."
     );
   }
-  applyTestEnv();
+  applyTestEnv(options);
   state.allowNetwork = options.allowNetwork ?? false;
   installFetchRouter();
   const db = await createPgliteDatabase();
@@ -2742,11 +2824,14 @@ function parseWorkflowName(describeTitle) {
 0 && (module.exports = {
   CONTROL_PLANE_TEST_URL,
   DATA_STORE_TEST_HOST,
+  DATA_STORE_TEST_URL,
   DEFAULT_SCHEMA_PATH,
+  STARDECK_DATA_STORES_ENV,
   STORAGE_TEST_HOST,
   STORAGE_TEST_URL,
   TEST_ENV_DEFAULTS,
   WORKFLOW_NAME_PREFIX,
+  buildTestDataStoreManifest,
   callRoute,
   createTestApp,
   describeWorkflow,

package/dist/index.mjs

@@ -47,6 +47,7 @@ function globalSingleton(key, create) {
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
+  lastHarnessDataStoreManifest: null,
   currentUser: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
@@ -95,6 +96,7 @@ function requireDb() {
 var TEST_DOMAIN_SUFFIX = ".stardeck.test";
 var CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
 var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
 var STORAGE_TEST_URL = "https://storage.stardeck.test";
 var STORAGE_TEST_HOST = "storage.stardeck.test";
 var TEST_ENV_DEFAULTS = {
@@ -103,7 +105,6 @@ var TEST_ENV_DEFAULTS = {
   ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a",
   PROJECT_ID: "00000000-0000-4000-8000-00000000000b",
   DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c",
-  DATA_STORE_URL: `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`,
   STORAGE_URL: STORAGE_TEST_URL
 };
 var DEFAULT_TEST_USER = {
@@ -2557,11 +2558,89 @@ function uninstallFetchRouter() {
   }
 }
 
+// src/data-store-manifest.ts
+var STARDECK_DATA_STORES_ENV = "STARDECK_DATA_STORES";
+function dataStoreSlug(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return slug || "store";
+}
+function buildTestDataStoreManifest(inputs = [{}]) {
+  const takenSlugs = /* @__PURE__ */ new Set();
+  const takenBindingKeys = /* @__PURE__ */ new Set();
+  const takenIds = /* @__PURE__ */ new Set();
+  return inputs.map((input, index) => {
+    for (const field of ["bindingKey", "slug", "name"]) {
+      if (input[field] === "") {
+        throw new Error(`[stardeck-testing] dataStores[${index}].${field} cannot be empty.`);
+      }
+    }
+    let slug;
+    if (input.slug !== void 0) {
+      slug = input.slug;
+      if (takenSlugs.has(slug)) {
+        throw new Error(`[stardeck-testing] dataStores[${index}].slug must be unique.`);
+      }
+    } else {
+      const base = input.name !== void 0 ? dataStoreSlug(input.name) : index === 0 ? "main" : null;
+      if (base === null) {
+        throw new Error(
+          `[stardeck-testing] dataStores[${index}] requires a slug or name. Only the first entry defaults to the "main" slug.`
+        );
+      }
+      slug = base;
+      let suffix = 2;
+      while (takenSlugs.has(slug)) {
+        slug = `${base}_${suffix}`;
+        suffix++;
+      }
+    }
+    const id = input.id ?? `00000000-0000-4000-8000-${String(index + 1).padStart(12, "0")}`;
+    if (takenIds.has(id)) {
+      throw new Error(`[stardeck-testing] dataStores[${index}].id must be unique.`);
+    }
+    if (input.bindingKey !== void 0 && takenBindingKeys.has(input.bindingKey)) {
+      throw new Error(`[stardeck-testing] dataStores[${index}].bindingKey must be unique.`);
+    }
+    takenSlugs.add(slug);
+    takenIds.add(id);
+    if (input.bindingKey !== void 0) takenBindingKeys.add(input.bindingKey);
+    const storeType = input.storeType ?? "database";
+    return {
+      id,
+      name: input.name ?? slug,
+      slug,
+      storeType,
+      accessLevel: input.accessLevel ?? "admin",
+      ...storeType === "database" ? { url: input.url ?? DATA_STORE_TEST_URL } : {},
+      ...input.bindingKey ? { bindingKey: input.bindingKey } : {}
+    };
+  });
+}
+
 // src/test-app.ts
-function applyTestEnv() {
+function applyTestEnv(options) {
   for (const [key, value] of Object.entries(TEST_ENV_DEFAULTS)) {
     process.env[key] = value;
   }
+  let manifestAdopted = true;
+  if (options.dataStores !== void 0) {
+    const manifest = JSON.stringify(buildTestDataStoreManifest(options.dataStores));
+    process.env[STARDECK_DATA_STORES_ENV] = manifest;
+    state.lastHarnessDataStoreManifest = manifest;
+  } else {
+    const currentManifest = process.env[STARDECK_DATA_STORES_ENV];
+    if (!currentManifest || currentManifest === state.lastHarnessDataStoreManifest) {
+      const manifest = JSON.stringify(buildTestDataStoreManifest());
+      process.env[STARDECK_DATA_STORES_ENV] = manifest;
+      state.lastHarnessDataStoreManifest = manifest;
+      manifestAdopted = false;
+    }
+  }
+  if (options.legacyDataStoreUrl === true || !manifestAdopted && options.legacyDataStoreUrl === void 0) {
+    process.env.DATA_STORE_URL = DATA_STORE_TEST_URL;
+  } else {
+    delete process.env.DATA_STORE_URL;
+  }
   delete process.env.DISABLE_AUTH;
   delete process.env.NEXT_PUBLIC_DISABLE_AUTH;
   delete process.env.SANDBOX_MODE;
@@ -2594,7 +2673,7 @@ async function createTestApp(options = {}) {
       "[stardeck-testing] A test app is already active in this test file. Call `app.close()` first, or share one app per file."
     );
   }
-  applyTestEnv();
+  applyTestEnv(options);
   state.allowNetwork = options.allowNetwork ?? false;
   installFetchRouter();
   const db = await createPgliteDatabase();
@@ -2695,11 +2774,14 @@ function parseWorkflowName(describeTitle) {
 export {
   CONTROL_PLANE_TEST_URL,
   DATA_STORE_TEST_HOST,
+  DATA_STORE_TEST_URL,
   DEFAULT_SCHEMA_PATH,
+  STARDECK_DATA_STORES_ENV,
   STORAGE_TEST_HOST,
   STORAGE_TEST_URL,
   TEST_ENV_DEFAULTS,
   WORKFLOW_NAME_PREFIX,
+  buildTestDataStoreManifest,
   callRoute,
   createTestApp,
   describeWorkflow,

package/dist/next/headers-shim.js

@@ -39,6 +39,7 @@ function globalSingleton(key, create) {
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
+  lastHarnessDataStoreManifest: null,
   currentUser: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),

package/dist/next/headers-shim.mjs

@@ -12,6 +12,7 @@ function globalSingleton(key, create) {
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
+  lastHarnessDataStoreManifest: null,
   currentUser: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),

package/dist/setup.js

@@ -33,6 +33,7 @@ function globalSingleton(key, create) {
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
+  lastHarnessDataStoreManifest: null,
   currentUser: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
@@ -81,6 +82,7 @@ function requireDb() {
 var TEST_DOMAIN_SUFFIX = ".stardeck.test";
 var CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
 var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
 var STORAGE_TEST_URL = "https://storage.stardeck.test";
 var STORAGE_TEST_HOST = "storage.stardeck.test";
 var TEST_ENV_DEFAULTS = {
@@ -89,7 +91,6 @@ var TEST_ENV_DEFAULTS = {
   ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a",
   PROJECT_ID: "00000000-0000-4000-8000-00000000000b",
   DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c",
-  DATA_STORE_URL: `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`,
   STORAGE_URL: STORAGE_TEST_URL
 };
 

package/dist/setup.mjs

@@ -9,6 +9,7 @@ function globalSingleton(key, create) {
 // src/state.ts
 var state = globalSingleton("state", () => ({
   db: null,
+  lastHarnessDataStoreManifest: null,
   currentUser: null,
   sessions: /* @__PURE__ */ new Map(),
   refreshSessions: /* @__PURE__ */ new Map(),
@@ -57,6 +58,7 @@ function requireDb() {
 var TEST_DOMAIN_SUFFIX = ".stardeck.test";
 var CONTROL_PLANE_TEST_URL = "https://control-plane.stardeck.test";
 var DATA_STORE_TEST_HOST = "db.stardeck.test";
+var DATA_STORE_TEST_URL = `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`;
 var STORAGE_TEST_URL = "https://storage.stardeck.test";
 var STORAGE_TEST_HOST = "storage.stardeck.test";
 var TEST_ENV_DEFAULTS = {
@@ -65,7 +67,6 @@ var TEST_ENV_DEFAULTS = {
   ORGANIZATION_ID: "00000000-0000-4000-8000-00000000000a",
   PROJECT_ID: "00000000-0000-4000-8000-00000000000b",
   DEPLOYMENT_ID: "00000000-0000-4000-8000-00000000000c",
-  DATA_STORE_URL: `postgresql://test:test@${DATA_STORE_TEST_HOST}/main`,
   STORAGE_URL: STORAGE_TEST_URL
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/testing",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Vitest test harness for Stardeck customer apps — in-process Postgres (PGlite) plus a control-plane simulator so the real Stardeck SDKs run unmodified in tests",
   "main": "dist/index.js",
   "module": "dist/index.mjs",