@stardeck-customer-apps/testing 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { PGlite } from '@electric-sql/pglite';
+import { ModuleSchemaOp, ModuleDataPort, IdentityClient } from '@stardeck-customer-apps/core';
 
 /**
  * The user shape returned by project-auth's `getSession()`. Mirrors the
@@ -140,6 +141,52 @@ interface TestApp {
  */
 declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
 
+/** The minimal slice of a module definition the harness needs to stand it up. */
+interface MountableModule {
+    schema: ModuleSchemaOp[];
+}
+interface ModuleSeedDeps {
+    /** Raw-SQL data port over the harness PGlite — what the module engine reads/writes through. */
+    data: ModuleDataPort;
+    /** Identity client backed by the simulated platform identity directory. */
+    identities: IdentityClient;
+}
+interface CreateModuleAppOptions {
+    /** Modules whose install schema is rendered to DDL and applied to the test DB. */
+    modules: MountableModule[];
+    /**
+     * Seed run once after the schema is applied, and again on every `reset()`.
+     * Receives the same data port + identity client the module engine uses, so a
+     * module's own `seed*` function drops straight in.
+     */
+    seed?: (deps: ModuleSeedDeps) => Promise<void>;
+    /** Allow real outbound network (default false). */
+    allowNetwork?: boolean;
+}
+interface ModuleApp extends ModuleSeedDeps {
+    /** The underlying harness app (db, identities inspector, callRoute, asUser, …). */
+    app: TestApp;
+    /** Reset to a clean slate: drop + re-apply the module schema, clear the sim, re-run the seed. */
+    reset(): Promise<void>;
+    /** Tear down (restore global fetch, close the db). */
+    close(): Promise<void>;
+}
+/**
+ * Stand a capability module up on the in-process platform simulator — the **L2**
+ * harness. It renders the module's install schema to real DDL (the SAME renderer
+ * the control plane uses, drift-tested in apps/web), applies it to PGlite, wires a
+ * raw-SQL data port over it, and a real `integrations-sdk` identity client talking
+ * to the simulated identity directory (so scoping + governance behave as in prod).
+ *
+ * That's a near-end-to-end test of a module's runtime — schema + data port +
+ * identity integration + engine — minus the HTTP/RSC shell (those belong to a
+ * real-deploy smoke). The same seams back the local dev playground.
+ *
+ * Adding a module costs one co-located test file calling this with its own
+ * definition + seed; there is no per-module harness to maintain.
+ */
+declare function createModuleApp(options: CreateModuleAppOptions): Promise<ModuleApp>;
+
 type RouteHandler<Req extends Request, P> = (request: Req, context: {
     params: Promise<P>;
 }) => Promise<Response> | Response;
@@ -183,4 +230,4 @@ declare const TEST_ENV_DEFAULTS: {
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestInbox, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };
+export { CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CreateModuleAppOptions, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type ModuleApp, type ModuleSeedDeps, type MountableModule, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestInbox, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createModuleApp, createTestApp, describeWorkflow, parseWorkflowName };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { PGlite } from '@electric-sql/pglite';
+import { ModuleSchemaOp, ModuleDataPort, IdentityClient } from '@stardeck-customer-apps/core';
 
 /**
  * The user shape returned by project-auth's `getSession()`. Mirrors the
@@ -140,6 +141,52 @@ interface TestApp {
  */
 declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
 
+/** The minimal slice of a module definition the harness needs to stand it up. */
+interface MountableModule {
+    schema: ModuleSchemaOp[];
+}
+interface ModuleSeedDeps {
+    /** Raw-SQL data port over the harness PGlite — what the module engine reads/writes through. */
+    data: ModuleDataPort;
+    /** Identity client backed by the simulated platform identity directory. */
+    identities: IdentityClient;
+}
+interface CreateModuleAppOptions {
+    /** Modules whose install schema is rendered to DDL and applied to the test DB. */
+    modules: MountableModule[];
+    /**
+     * Seed run once after the schema is applied, and again on every `reset()`.
+     * Receives the same data port + identity client the module engine uses, so a
+     * module's own `seed*` function drops straight in.
+     */
+    seed?: (deps: ModuleSeedDeps) => Promise<void>;
+    /** Allow real outbound network (default false). */
+    allowNetwork?: boolean;
+}
+interface ModuleApp extends ModuleSeedDeps {
+    /** The underlying harness app (db, identities inspector, callRoute, asUser, …). */
+    app: TestApp;
+    /** Reset to a clean slate: drop + re-apply the module schema, clear the sim, re-run the seed. */
+    reset(): Promise<void>;
+    /** Tear down (restore global fetch, close the db). */
+    close(): Promise<void>;
+}
+/**
+ * Stand a capability module up on the in-process platform simulator — the **L2**
+ * harness. It renders the module's install schema to real DDL (the SAME renderer
+ * the control plane uses, drift-tested in apps/web), applies it to PGlite, wires a
+ * raw-SQL data port over it, and a real `integrations-sdk` identity client talking
+ * to the simulated identity directory (so scoping + governance behave as in prod).
+ *
+ * That's a near-end-to-end test of a module's runtime — schema + data port +
+ * identity integration + engine — minus the HTTP/RSC shell (those belong to a
+ * real-deploy smoke). The same seams back the local dev playground.
+ *
+ * Adding a module costs one co-located test file calling this with its own
+ * definition + seed; there is no per-module harness to maintain.
+ */
+declare function createModuleApp(options: CreateModuleAppOptions): Promise<ModuleApp>;
+
 type RouteHandler<Req extends Request, P> = (request: Req, context: {
     params: Promise<P>;
 }) => Promise<Response> | Response;
@@ -183,4 +230,4 @@ declare const TEST_ENV_DEFAULTS: {
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestInbox, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };
+export { CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CreateModuleAppOptions, DATA_STORE_TEST_HOST, DEFAULT_SCHEMA_PATH, type ModuleApp, type ModuleSeedDeps, type MountableModule, type SessionTokens, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, type TestDirectory, type TestInbox, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createModuleApp, createTestApp, describeWorkflow, parseWorkflowName };

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   TEST_ENV_DEFAULTS: () => TEST_ENV_DEFAULTS,
   WORKFLOW_NAME_PREFIX: () => WORKFLOW_NAME_PREFIX,
   callRoute: () => callRoute,
+  createModuleApp: () => createModuleApp,
   createTestApp: () => createTestApp,
   describeWorkflow: () => describeWorkflow,
   parseWorkflowName: () => parseWorkflowName
@@ -980,6 +981,39 @@ async function createTestApp(options = {}) {
   return app;
 }
 
+// src/module-app.ts
+var import_core = require("@stardeck-customer-apps/core");
+async function createModuleApp(options) {
+  const schemaSql = options.modules.map((m) => (0, import_core.renderSchemaOpsToSql)(m.schema)).join("\n\n");
+  const app = await createTestApp({ schemaSql, allowNetwork: options.allowNetwork });
+  const sql = { query: (text, params) => app.db.query(text, params ?? []) };
+  const data = (0, import_core.makeSqlPort)(sql);
+  const { createIntegrationsClient } = await import("@stardeck-customer-apps/integrations-sdk");
+  const identities = createIntegrationsClient({
+    controlPlaneUrl: TEST_ENV_DEFAULTS.CONTROL_PLANE_URL,
+    organizationId: TEST_ENV_DEFAULTS.ORGANIZATION_ID,
+    projectId: TEST_ENV_DEFAULTS.PROJECT_ID,
+    deploymentId: TEST_ENV_DEFAULTS.DEPLOYMENT_ID,
+    deploymentSecret: TEST_ENV_DEFAULTS.DEPLOYMENT_SECRET
+  }).identities;
+  const runSeed = async () => {
+    if (options.seed) await options.seed({ data, identities });
+  };
+  await runSeed();
+  return {
+    app,
+    data,
+    identities,
+    async reset() {
+      await app.reset();
+      await runSeed();
+    },
+    async close() {
+      await app.close();
+    }
+  };
+}
+
 // src/next/headers-shim.ts
 var import_node_async_hooks = require("async_hooks");
 var requestScopeStorage = globalSingleton(
@@ -1077,6 +1111,7 @@ function parseWorkflowName(describeTitle) {
   TEST_ENV_DEFAULTS,
   WORKFLOW_NAME_PREFIX,
   callRoute,
+  createModuleApp,
   createTestApp,
   describeWorkflow,
   parseWorkflowName

package/dist/index.mjs

@@ -936,6 +936,42 @@ async function createTestApp(options = {}) {
   return app;
 }
 
+// src/module-app.ts
+import {
+  makeSqlPort,
+  renderSchemaOpsToSql
+} from "@stardeck-customer-apps/core";
+async function createModuleApp(options) {
+  const schemaSql = options.modules.map((m) => renderSchemaOpsToSql(m.schema)).join("\n\n");
+  const app = await createTestApp({ schemaSql, allowNetwork: options.allowNetwork });
+  const sql = { query: (text, params) => app.db.query(text, params ?? []) };
+  const data = makeSqlPort(sql);
+  const { createIntegrationsClient } = await import("@stardeck-customer-apps/integrations-sdk");
+  const identities = createIntegrationsClient({
+    controlPlaneUrl: TEST_ENV_DEFAULTS.CONTROL_PLANE_URL,
+    organizationId: TEST_ENV_DEFAULTS.ORGANIZATION_ID,
+    projectId: TEST_ENV_DEFAULTS.PROJECT_ID,
+    deploymentId: TEST_ENV_DEFAULTS.DEPLOYMENT_ID,
+    deploymentSecret: TEST_ENV_DEFAULTS.DEPLOYMENT_SECRET
+  }).identities;
+  const runSeed = async () => {
+    if (options.seed) await options.seed({ data, identities });
+  };
+  await runSeed();
+  return {
+    app,
+    data,
+    identities,
+    async reset() {
+      await app.reset();
+      await runSeed();
+    },
+    async close() {
+      await app.close();
+    }
+  };
+}
+
 // src/next/headers-shim.ts
 import { AsyncLocalStorage } from "async_hooks";
 var requestScopeStorage = globalSingleton(
@@ -1032,6 +1068,7 @@ export {
   TEST_ENV_DEFAULTS,
   WORKFLOW_NAME_PREFIX,
   callRoute,
+  createModuleApp,
   createTestApp,
   describeWorkflow,
   parseWorkflowName

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/testing",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -62,13 +62,18 @@
   "author": "Stardeck",
   "license": "MIT",
   "dependencies": {
-    "@electric-sql/pglite": "^0.3.0"
+    "@electric-sql/pglite": "^0.3.0",
+    "@stardeck-customer-apps/core": "*"
   },
   "peerDependencies": {
+    "@stardeck-customer-apps/integrations-sdk": ">=1.6.0",
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "vitest": ">=2.0.0"
   },
   "peerDependenciesMeta": {
+    "@stardeck-customer-apps/integrations-sdk": {
+      "optional": true
+    },
     "next": {
       "optional": true
     }