primitive-app 3.0.2 → 3.0.4

package/dist/lib-C53EcrFg.cjs

@@ -0,0 +1 @@
+let e=require("js-bao-wss-client");var t={debug:0,info:1,warn:2,error:3,none:4},n=`warn`,r=class e{#e;scope;constructor(e,t){this.#e=e,this.scope=t}get level(){return this.#e.level}set level(e){this.setLevel(e)}debug(...e){this.#t(`debug`,e)}log(...e){this.#t(`info`,e,`log`)}warn(...e){this.#t(`warn`,e)}error(...e){this.#t(`error`,e)}shouldLog(e){return t[e]>=t[this.level]}getLevel(){return this.level}setLevel(e){e in t&&(this.#e.level=e)}forScope(t){let n=t.trim(),r=n?[...this.scope,n]:this.scope;return new e(this.#e,r)}#t(e,t,n){if(!this.shouldLog(e))return;let r=n??(e===`info`?`log`:e),i=this.scope.length?`[${this.scope.join(`:`)}]`:void 0,a=i?[i,...t]:t;console[r](...a)}},i={level:n},a=new r(i,[]).forScope(`PrimitiveApp`);function o(e){i.level=e}var s=a.forScope(`JsBaoClientService`);function c(){if(typeof window>`u`)return!1;let e=window.location.hostname;return e===`localhost`||e===`127.0.0.1`||e===`[::1]`||e.endsWith(`.localhost`)||e.endsWith(`.local`)}var l=new class{client=null;clientInitializationPromise=null;config=null;initialize(e){s.debug(`Initializing with config:`,{appId:e.appId?`${e.appId.substring(0,10)}...`:`MISSING`,apiUrl:e.apiUrl,wsUrl:e.wsUrl,oauthRedirectUri:e.oauthRedirectUri});let t=[];(!e.appId||e.appId===`MISSING_APP_ID`)&&t.push(`appId`),(!e.apiUrl||e.apiUrl===`MISSING_API_URL`)&&t.push(`apiUrl`),(!e.wsUrl||e.wsUrl===`MISSING_WS_URL`)&&t.push(`wsUrl`),(!e.oauthRedirectUri||e.oauthRedirectUri===`MISSING_OAUTH_REDIRECT_URI`)&&t.push(`oauthRedirectUri`),t.length>0&&(s.error(`❌ Configuration validation failed!`),s.error(`Missing or invalid fields:`,t),s.error(`This will cause OAuth and API calls to fail.`),s.error(`Please check your .env file configuration.`)),this.config=e}getConfig(){return this.config}async getClientAsync(){if(s.debug(`Getting client async`),this.clientInitializationPromise)return this.clientInitializationPromise;if(!this.config)throw Error(`JsBaoClientService not initialized. Call initialize() first.`);return this.clientInitializationPromise=(async()=>{s.debug(`=== INITIALIZING CLIENT ===`),s.debug(`Configuration:`,this.config);let t=await(0,e.initializeClient)(this.config);if(t.on(`status`,e=>{s.debug(`Client status changed:`,e)}),t.on(`error`,e=>{s.error(`Client error:`,e)}),this.client=t,c()&&(window.__primitiveAppClient=t,this.config?.models&&Array.isArray(this.config.models))){let e={};for(let t of this.config.models){let n=t.schema?.name;if(n){let r=n.charAt(0).toUpperCase()+n.slice(1);e[r]=t}}window.__primitiveAppModels=e,s.debug(`Registered models on window:`,Object.keys(e))}return s.debug(`=== CLIENT INITIALIZATION COMPLETE ===`),t})(),this.clientInitializationPromise}setExternalClient(e){s.debug(`Setting external client from host app`),this.client=e,this.clientInitializationPromise=Promise.resolve(e)}async clearClient(){s.debug(`Clearing client singleton...`),this.client&&(this.client.disconnect().catch(e=>{s.warn(`Background disconnect failed (this is usually harmless):`,e)}),this.client=null,this.clientInitializationPromise=null,c()&&(window.__primitiveAppClient=void 0,window.__primitiveAppModels=void 0))}};function u(e){l.initialize(e)}var d=a.forScope(`TestHarness`),f=`===TEST===`;async function p(e={}){let{networkSync:t=!1}=e,n=await l.getClientAsync(),r=`${f} ${`${Date.now()}-${Math.random().toString(36).substring(2,11)}`}`;if(t){let{metadata:e}=await n.documents.create({title:r}),t=e.documentId,{doc:i}=await n.documents.open(t);if(!i)throw Error(`[TestHarness] Failed to open synced test document`);return n.setDefaultDocumentId(t),d.debug(`Created synced test document`,{docId:t}),m.set(t,{client:n,docId:t,networkSync:!0}),{docId:t}}let{metadata:i}=await n.documents.create({title:r,localOnly:!0}),a=i.documentId,{doc:o}=await n.documents.open(a,{waitForLoad:`local`,enableNetworkSync:!1});if(!o)throw Error(`[TestHarness] Failed to open test document`);return n.setDefaultDocumentId(a),d.debug(`Created test document`,{docId:a}),m.set(a,{client:n,docId:a,networkSync:!1}),{docId:a}}var m=new Map;async function h(e){let t=m.get(e.docId);if(!t){d.warn(`destroyTestDocument called with unknown handle`,{docId:e.docId});return}m.delete(e.docId);try{t.networkSync?await t.client.documents.delete(t.docId,{forceCloseIfOpen:!0}):(await t.client.documents.close(t.docId),await t.client.documents.evict(t.docId,{force:!0}))}catch(e){d.error(`Failed to destroy test document`,{docId:t.docId,err:e})}}async function g(){try{let e=await l.getClientAsync();d.debug(`[deleteAllTestDocuments] Starting cleanup...`),await e.syncMetadata({scope:`all`});let t=(await e.me.ownedDocuments()).filter(e=>e.title?.startsWith(f));if(t.length===0)return 0;d.debug(`[deleteAllTestDocuments] Found test documents to delete`,{count:t.length});let n=0;for(let r of t)try{e.documents.isOpen(r.documentId)&&await e.documents.close(r.documentId),await e.documents.evict(r.documentId,{force:!0}),n++}catch(e){d.error(`[deleteAllTestDocuments] Failed to delete test document`,{documentId:r.documentId,err:e})}return d.debug(`[deleteAllTestDocuments] Cleanup complete`,{evictedCount:n}),n}catch(e){return d.error(`[deleteAllTestDocuments] Top-level error during cleanup`,{err:e}),0}}function _(e){return e.flatMap(e=>e.tests.map(t=>({id:t.id,name:t.name,group:e.name,run:t.run})))}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,"c",{enumerable:!0,get:function(){return o}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return h}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return _}});

package/dist/lib-zKX4LVeH.js

@@ -0,0 +1,191 @@
+import { initializeClient as e } from "js-bao-wss-client";
+//#region src/lib/logger.ts
+var t = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+	none: 4
+}, n = "warn", r = class e {
+	#e;
+	scope;
+	constructor(e, t) {
+		this.#e = e, this.scope = t;
+	}
+	get level() {
+		return this.#e.level;
+	}
+	set level(e) {
+		this.setLevel(e);
+	}
+	debug(...e) {
+		this.#t("debug", e);
+	}
+	log(...e) {
+		this.#t("info", e, "log");
+	}
+	warn(...e) {
+		this.#t("warn", e);
+	}
+	error(...e) {
+		this.#t("error", e);
+	}
+	shouldLog(e) {
+		return t[e] >= t[this.level];
+	}
+	getLevel() {
+		return this.level;
+	}
+	setLevel(e) {
+		e in t && (this.#e.level = e);
+	}
+	forScope(t) {
+		let n = t.trim(), r = n ? [...this.scope, n] : this.scope;
+		return new e(this.#e, r);
+	}
+	#t(e, t, n) {
+		if (!this.shouldLog(e)) return;
+		let r = n ?? (e === "info" ? "log" : e), i = this.scope.length ? `[${this.scope.join(":")}]` : void 0, a = i ? [i, ...t] : t;
+		console[r](...a);
+	}
+}, i = { level: n }, a = new r(i, []).forScope("PrimitiveApp");
+function o(e) {
+	i.level = e;
+}
+//#endregion
+//#region src/services/JsBaoClientService.ts
+var s = a.forScope("JsBaoClientService");
+function c() {
+	if (typeof window > "u") return !1;
+	let e = window.location.hostname;
+	return e === "localhost" || e === "127.0.0.1" || e === "[::1]" || e.endsWith(".localhost") || e.endsWith(".local");
+}
+var l = new class {
+	client = null;
+	clientInitializationPromise = null;
+	config = null;
+	initialize(e) {
+		s.debug("Initializing with config:", {
+			appId: e.appId ? `${e.appId.substring(0, 10)}...` : "MISSING",
+			apiUrl: e.apiUrl,
+			wsUrl: e.wsUrl,
+			oauthRedirectUri: e.oauthRedirectUri
+		});
+		let t = [];
+		(!e.appId || e.appId === "MISSING_APP_ID") && t.push("appId"), (!e.apiUrl || e.apiUrl === "MISSING_API_URL") && t.push("apiUrl"), (!e.wsUrl || e.wsUrl === "MISSING_WS_URL") && t.push("wsUrl"), (!e.oauthRedirectUri || e.oauthRedirectUri === "MISSING_OAUTH_REDIRECT_URI") && t.push("oauthRedirectUri"), t.length > 0 && (s.error("❌ Configuration validation failed!"), s.error("Missing or invalid fields:", t), s.error("This will cause OAuth and API calls to fail."), s.error("Please check your .env file configuration.")), this.config = e;
+	}
+	getConfig() {
+		return this.config;
+	}
+	async getClientAsync() {
+		if (s.debug("Getting client async"), this.clientInitializationPromise) return this.clientInitializationPromise;
+		if (!this.config) throw Error("JsBaoClientService not initialized. Call initialize() first.");
+		return this.clientInitializationPromise = (async () => {
+			s.debug("=== INITIALIZING CLIENT ==="), s.debug("Configuration:", this.config);
+			let t = await e(this.config);
+			if (t.on("status", (e) => {
+				s.debug("Client status changed:", e);
+			}), t.on("error", (e) => {
+				s.error("Client error:", e);
+			}), this.client = t, c() && (window.__primitiveAppClient = t, this.config?.models && Array.isArray(this.config.models))) {
+				let e = {};
+				for (let t of this.config.models) {
+					let n = t.schema?.name;
+					if (n) {
+						let r = n.charAt(0).toUpperCase() + n.slice(1);
+						e[r] = t;
+					}
+				}
+				window.__primitiveAppModels = e, s.debug("Registered models on window:", Object.keys(e));
+			}
+			return s.debug("=== CLIENT INITIALIZATION COMPLETE ==="), t;
+		})(), this.clientInitializationPromise;
+	}
+	setExternalClient(e) {
+		s.debug("Setting external client from host app"), this.client = e, this.clientInitializationPromise = Promise.resolve(e);
+	}
+	async clearClient() {
+		s.debug("Clearing client singleton..."), this.client && (this.client.disconnect().catch((e) => {
+			s.warn("Background disconnect failed (this is usually harmless):", e);
+		}), this.client = null, this.clientInitializationPromise = null, c() && (window.__primitiveAppClient = void 0, window.__primitiveAppModels = void 0));
+	}
+}();
+function u(e) {
+	l.initialize(e);
+}
+//#endregion
+//#region src/dev-tools/test-harness/lib.ts
+var d = a.forScope("TestHarness"), f = "===TEST===";
+async function p(e = {}) {
+	let { networkSync: t = !1 } = e, n = await l.getClientAsync(), r = `${f} ${`${Date.now()}-${Math.random().toString(36).substring(2, 11)}`}`;
+	if (t) {
+		let { metadata: e } = await n.documents.create({ title: r }), t = e.documentId, { doc: i } = await n.documents.open(t);
+		if (!i) throw Error("[TestHarness] Failed to open synced test document");
+		return n.setDefaultDocumentId(t), d.debug("Created synced test document", { docId: t }), m.set(t, {
+			client: n,
+			docId: t,
+			networkSync: !0
+		}), { docId: t };
+	}
+	let { metadata: i } = await n.documents.create({
+		title: r,
+		localOnly: !0
+	}), a = i.documentId, { doc: o } = await n.documents.open(a, {
+		waitForLoad: "local",
+		enableNetworkSync: !1
+	});
+	if (!o) throw Error("[TestHarness] Failed to open test document");
+	return n.setDefaultDocumentId(a), d.debug("Created test document", { docId: a }), m.set(a, {
+		client: n,
+		docId: a,
+		networkSync: !1
+	}), { docId: a };
+}
+var m = /* @__PURE__ */ new Map();
+async function h(e) {
+	let t = m.get(e.docId);
+	if (!t) {
+		d.warn("destroyTestDocument called with unknown handle", { docId: e.docId });
+		return;
+	}
+	m.delete(e.docId);
+	try {
+		t.networkSync ? await t.client.documents.delete(t.docId, { forceCloseIfOpen: !0 }) : (await t.client.documents.close(t.docId), await t.client.documents.evict(t.docId, { force: !0 }));
+	} catch (e) {
+		d.error("Failed to destroy test document", {
+			docId: t.docId,
+			err: e
+		});
+	}
+}
+async function g() {
+	try {
+		let e = await l.getClientAsync();
+		d.debug("[deleteAllTestDocuments] Starting cleanup..."), await e.syncMetadata({ scope: "all" });
+		let t = (await e.me.ownedDocuments()).filter((e) => e.title?.startsWith(f));
+		if (t.length === 0) return 0;
+		d.debug("[deleteAllTestDocuments] Found test documents to delete", { count: t.length });
+		let n = 0;
+		for (let r of t) try {
+			e.documents.isOpen(r.documentId) && await e.documents.close(r.documentId), await e.documents.evict(r.documentId, { force: !0 }), n++;
+		} catch (e) {
+			d.error("[deleteAllTestDocuments] Failed to delete test document", {
+				documentId: r.documentId,
+				err: e
+			});
+		}
+		return d.debug("[deleteAllTestDocuments] Cleanup complete", { evictedCount: n }), n;
+	} catch (e) {
+		return d.error("[deleteAllTestDocuments] Top-level error during cleanup", { err: e }), 0;
+	}
+}
+function _(e) {
+	return e.flatMap((e) => e.tests.map((t) => ({
+		id: t.id,
+		name: t.name,
+		group: e.name,
+		run: t.run
+	})));
+}
+//#endregion
+export { u as a, o as c, h as i, p as n, l as o, g as r, a as s, _ as t };

package/dist/services/JsBaoClientService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JsBaoClientService.d.ts","sourceRoot":"","sources":["../../src/services/JsBaoClientService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,OAAO,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAK9E,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChD;CACF;AAED,KAAK,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC;AAqBhE;;;;;GAKG;AACH,cAAM,kBAAkB;IACtB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,2BAA2B,CAAqC;IACxE,OAAO,CAAC,MAAM,CAAmC;IAEjD;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAgC5C;;;OAGG;IACH,SAAS,IAAI,kBAAkB,GAAG,IAAI;IAItC;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IA8D5C;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAM5C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAsBnC;AAED,eAAO,MAAM,kBAAkB,oBAA2B,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAEhE"}
+{"version":3,"file":"JsBaoClientService.d.ts","sourceRoot":"","sources":["../../src/services/JsBaoClientService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,OAAO,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAK9E,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChD;CACF;AAED,KAAK,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC;AAqBhE;;;;;GAKG;AACH,cAAM,kBAAkB;IACtB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,2BAA2B,CAAqC;IACxE,OAAO,CAAC,MAAM,CAAmC;IAEjD;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAgC5C;;;OAGG;IACH,SAAS,IAAI,kBAAkB,GAAG,IAAI;IAItC;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAgE5C;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAM5C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAsBnC;AAED,eAAO,MAAM,kBAAkB,oBAA2B,CAAC;AAE3D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAEhE"}

package/dist/testing/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../rolldown-runtime-BNMv73og.cjs"),t=require("../lib-C53EcrFg.cjs");let n=require("js-bao-wss-client"),r=require("node:fs"),i=require("node:path");i=e.i(i,1);let a=require("vitest");var o=`000000`;function s(e,t,n){if(e)return e;throw Error(`[primitive-app/testing] Missing ${t}: pass it to registerPrimitiveTests() or set the ${n} environment variable.`)}function c(){let e=i.default.resolve(process.cwd(),`public/sql-wasm.wasm`);if(!(0,r.existsSync)(e)){console.warn(`[primitive-app/testing] ${e} not found — using the client's default database config. If client init fails to load sql-wasm.wasm, pass clientOptions.databaseConfig explicitly.`);return}return{type:`sqljs`,options:{locateFile:()=>e}}}async function l(e){let t=[],n=[];for(let[r,i]of Object.entries(e))try{let e=(await i())?.default;Array.isArray(e)?t.push(...e):e&&typeof e==`object`&&`tests`in e?t.push(e):n.push({file:r,error:Error(`Default export is not a TestGroup (expected { name, tests }).`)})}catch(e){n.push({file:r,error:e})}return{groups:t,failures:n}}async function u(e){let{models:r,testModules:i,otpCode:u=o,testTimeoutMs:d=6e4,clientOptions:f,cleanupTestDocuments:p=!0,failBelowFullScore:m=!0}=e,h=s(e.appId??process.env.VITE_APP_ID,`appId`,`VITE_APP_ID`),g=s(e.apiUrl??process.env.VITE_API_URL,`apiUrl`,`VITE_API_URL`),_=s(e.wsUrl??process.env.VITE_WS_URL,`wsUrl`,`VITE_WS_URL`),v=s(e.email??process.env.PRIMITIVE_TEST_EMAIL,`email`,`PRIMITIVE_TEST_EMAIL`),{groups:y,failures:b}=await l(i);for(let e of b)(0,a.describe)(e.file,()=>{(0,a.it)(`loads without errors`,()=>{throw e.error instanceof Error?e.error:Error(String(e.error))})});if(y.length===0){b.length===0&&console.warn(`[primitive-app/testing] No *.primitive-test.ts groups found — nothing to register.`);return}let x;(0,a.beforeAll)(async()=>{x=await(0,n.initializeClient)({apiUrl:g,wsUrl:_,appId:h,models:r,storageConfig:{type:`auto`},databaseConfig:c(),...f});try{await x.otpVerify(v,u)}catch(e){throw Error(`[primitive-app/testing] OTP sign-in failed for ${v}. The test bypass requires the app's testAccountBaseEmails whitelist to cover this address (and invite-only/domain/waitlist apps reject provisioning like any signup). Underlying error: ${e instanceof Error?e.message:String(e)}`)}t.o.initialize({apiUrl:g,wsUrl:_,appId:h,models:r,oauthRedirectUri:f?.oauthRedirectUri??process.env.VITE_OAUTH_REDIRECT_URI??`http://localhost/oauth/callback-unused-in-node-tests`,...f}),t.o.setExternalClient(x)},12e4),(0,a.afterAll)(async()=>{if(x){if(p)try{await t.r()}catch(e){console.warn(`[primitive-app/testing] Test-document cleanup failed:`,e)}await x.disconnect()}},6e4);for(let e of y)(0,a.describe)(e.name,()=>{for(let t of e.tests)(0,a.it)(t.name,async()=>{let e=await t.run(e=>console.log(`[${t.id}] ${e}`));e&&console.log(`[${t.id}] ${e}`);let n=e?.match(/^(\d+)\/(\d+)\s*\((\d+(?:\.\d+)?)%\)/);if(m&&n&&Number(n[1])!==Number(n[2]))throw Error(`Scored below full marks: ${e}`)},d)})}exports.PRIMITIVE_TEST_OTP_CODE=o,exports.registerPrimitiveTests=u;

package/dist/testing/index.d.ts

@@ -0,0 +1,62 @@
+import { type JsBaoClientOptions } from "js-bao-wss-client";
+/**
+ * The OTP code the server accepts for whitelisted test accounts
+ * (the `testAccountBaseEmails` bypass — no email delivery involved).
+ */
+export declare const PRIMITIVE_TEST_OTP_CODE = "000000";
+export interface RegisterPrimitiveTestsOptions {
+    /** The app's model classes (typically `allModels` from `@/models`). */
+    models: JsBaoClientOptions["models"];
+    /**
+     * Lazy module loaders for the registered test files, from
+     * `import.meta.glob("./**\/*.primitive-test.ts")` in the spec file.
+     * Each module's default export must be a `TestGroup` or `TestGroup[]`.
+     */
+    testModules: Record<string, () => Promise<unknown>>;
+    /** App ID. Defaults to `process.env.VITE_APP_ID`. */
+    appId?: string;
+    /** API endpoint URL. Defaults to `process.env.VITE_API_URL`. */
+    apiUrl?: string;
+    /** WebSocket endpoint URL. Defaults to `process.env.VITE_WS_URL`. */
+    wsUrl?: string;
+    /**
+     * Sign-in email for the OTP test bypass. Must resolve to the app's
+     * `testAccountBaseEmails` whitelist (e.g. `you+primitivetest-ci@domain.com`
+     * when `you@domain.com` is whitelisted). Use a stable suffix per CI project
+     * so the find-or-create provisioner reuses one test user across runs.
+     * Defaults to `process.env.PRIMITIVE_TEST_EMAIL`.
+     */
+    email?: string;
+    /** OTP code to verify with. Defaults to the "000000" test bypass. */
+    otpCode?: string;
+    /** Per-test timeout in ms. Defaults to 60_000. */
+    testTimeoutMs?: number;
+    /**
+     * Extra options merged into `initializeClient` (after the adapter's
+     * defaults), e.g. `databaseConfig` or a `storageConfig` override. The
+     * default storage is `{ type: "auto" }`: better-sqlite3 when installed,
+     * otherwise in-memory — no native deps required in CI.
+     */
+    clientOptions?: Partial<JsBaoClientOptions>;
+    /**
+     * Delete leftover `===TEST===` documents after the run (mirrors the browser
+     * panel's cleanup of interrupted runs). Defaults to true.
+     */
+    cleanupTestDocuments?: boolean;
+    /**
+     * Treat a scored result ("passed/total (pct%)" return message) below a full
+     * score as a failure so partial scores gate CI. Defaults to true; the
+     * browser panel shows the same result as "scored" without failing.
+     */
+    failBelowFullScore?: boolean;
+}
+/**
+ * Register every provided test group as vitest `describe`/`it` blocks and
+ * bootstrap an authenticated Node js-bao client for them to run against.
+ *
+ * Call with top-level await from a spec file so the groups are enumerated
+ * during vitest collection. A test file that fails to load (import error,
+ * wrong export shape) is surfaced as a failing test, never a silent skip.
+ */
+export declare function registerPrimitiveTests(options: RegisterPrimitiveTestsOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAiCA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAO3B;;;GAGG;AACH,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD,MAAM,WAAW,6BAA6B;IAC5C,uEAAuE;IACvE,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAErC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAEpD,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE5C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAkED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CA8If"}

package/dist/testing/index.js

@@ -0,0 +1,97 @@
+import { o as e, r as t } from "../lib-zKX4LVeH.js";
+import { initializeClient as n } from "js-bao-wss-client";
+import { existsSync as r } from "node:fs";
+import i from "node:path";
+import { afterAll as a, beforeAll as o, describe as s, it as c } from "vitest";
+//#region src/testing/index.ts
+var l = "000000";
+function u(e, t, n) {
+	if (e) return e;
+	throw Error(`[primitive-app/testing] Missing ${t}: pass it to registerPrimitiveTests() or set the ${n} environment variable.`);
+}
+function d() {
+	let e = i.resolve(process.cwd(), "public/sql-wasm.wasm");
+	if (!r(e)) {
+		console.warn(`[primitive-app/testing] ${e} not found — using the client's default database config. If client init fails to load sql-wasm.wasm, pass clientOptions.databaseConfig explicitly.`);
+		return;
+	}
+	return {
+		type: "sqljs",
+		options: { locateFile: () => e }
+	};
+}
+async function f(e) {
+	let t = [], n = [];
+	for (let [r, i] of Object.entries(e)) try {
+		let e = (await i())?.default;
+		Array.isArray(e) ? t.push(...e) : e && typeof e == "object" && "tests" in e ? t.push(e) : n.push({
+			file: r,
+			error: /* @__PURE__ */ Error("Default export is not a TestGroup (expected { name, tests }).")
+		});
+	} catch (e) {
+		n.push({
+			file: r,
+			error: e
+		});
+	}
+	return {
+		groups: t,
+		failures: n
+	};
+}
+async function p(r) {
+	let { models: i, testModules: p, otpCode: m = l, testTimeoutMs: h = 6e4, clientOptions: g, cleanupTestDocuments: _ = !0, failBelowFullScore: v = !0 } = r, y = u(r.appId ?? process.env.VITE_APP_ID, "appId", "VITE_APP_ID"), b = u(r.apiUrl ?? process.env.VITE_API_URL, "apiUrl", "VITE_API_URL"), x = u(r.wsUrl ?? process.env.VITE_WS_URL, "wsUrl", "VITE_WS_URL"), S = u(r.email ?? process.env.PRIMITIVE_TEST_EMAIL, "email", "PRIMITIVE_TEST_EMAIL"), { groups: C, failures: w } = await f(p);
+	for (let e of w) s(e.file, () => {
+		c("loads without errors", () => {
+			throw e.error instanceof Error ? e.error : Error(String(e.error));
+		});
+	});
+	if (C.length === 0) {
+		w.length === 0 && console.warn("[primitive-app/testing] No *.primitive-test.ts groups found — nothing to register.");
+		return;
+	}
+	let T;
+	o(async () => {
+		T = await n({
+			apiUrl: b,
+			wsUrl: x,
+			appId: y,
+			models: i,
+			storageConfig: { type: "auto" },
+			databaseConfig: d(),
+			...g
+		});
+		try {
+			await T.otpVerify(S, m);
+		} catch (e) {
+			throw Error(`[primitive-app/testing] OTP sign-in failed for ${S}. The test bypass requires the app's testAccountBaseEmails whitelist to cover this address (and invite-only/domain/waitlist apps reject provisioning like any signup). Underlying error: ${e instanceof Error ? e.message : String(e)}`);
+		}
+		e.initialize({
+			apiUrl: b,
+			wsUrl: x,
+			appId: y,
+			models: i,
+			oauthRedirectUri: g?.oauthRedirectUri ?? process.env.VITE_OAUTH_REDIRECT_URI ?? "http://localhost/oauth/callback-unused-in-node-tests",
+			...g
+		}), e.setExternalClient(T);
+	}, 12e4), a(async () => {
+		if (T) {
+			if (_) try {
+				await t();
+			} catch (e) {
+				console.warn("[primitive-app/testing] Test-document cleanup failed:", e);
+			}
+			await T.disconnect();
+		}
+	}, 6e4);
+	for (let e of C) s(e.name, () => {
+		for (let t of e.tests) c(t.name, async () => {
+			let e = await t.run((e) => console.log(`[${t.id}] ${e}`));
+			e && console.log(`[${t.id}] ${e}`);
+			let n = e?.match(/^(\d+)\/(\d+)\s*\((\d+(?:\.\d+)?)%\)/);
+			if (v && n && Number(n[1]) !== Number(n[2])) throw Error(`Scored below full marks: ${e}`);
+		}, h);
+	});
+}
+//#endregion
+export { l as PRIMITIVE_TEST_OTP_CODE, p as registerPrimitiveTests };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primitive-app",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "license": "UNLICENSED",
   "author": "Primitive LLC",
   "type": "module",
@@ -18,6 +18,11 @@
       "types": "./dist/dev-tools/vite-plugin/index.d.ts",
       "import": "./dist/dev-tools/vite-plugin/index.js",
       "default": "./dist/dev-tools/vite-plugin/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -32,21 +37,6 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
-  "scripts": {
-    "prepublishOnly": "pnpm build",
-    "dev": "vite",
-    "build": "pnpm codegen && run-p type-check \"build-only {@}\" -- && pnpm build:dts",
-    "preview": "vite preview",
-    "clean": "rm -rf dist && pnpm clean-modules",
-    "clean-modules": "rm -rf node_modules pnpm-lock.yaml",
-    "build-only": "vite build",
-    "build:dts": "vue-tsc -p tsconfig.build.json --declaration --emitDeclarationOnly",
-    "type-check": "vue-tsc --build",
-    "lint": "eslint . --fix --cache",
-    "format:check": "prettier --check src/",
-    "format": "prettier --write src/",
-    "codegen": "npx js-bao-codegen && pnpm format"
-  },
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/vue": "^1.22.0",
@@ -73,9 +63,13 @@
     "pinia": "^3.0.3",
     "vue": "^3.5.22",
     "vue-router": "^4.6.0",
+    "vitest": ">=3.0.0",
     "yjs": "*"
   },
   "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    },
     "js-bao": {
       "optional": true
     },
@@ -100,7 +94,7 @@
     "eslint-plugin-vue": "~10.9.2",
     "jiti": "^2.7.0",
     "js-bao": "^0.5.1",
-    "js-bao-wss-client": "^2.0.4",
+    "js-bao-wss-client": "1.3.0-alpha.51",
     "npm-run-all2": "^9.0.2",
     "pinia": "^3.0.4",
     "prettier": "3.9.4",
@@ -109,8 +103,23 @@
     "typescript": "~6.0.3",
     "vite": "^8.1.2",
     "vite-plugin-vue-devtools": "^8.1.5",
+    "vitest": "^4.1.10",
     "vue": "^3.5.39",
     "vue-router": "^5.1.0",
     "vue-tsc": "^3.3.6"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "pnpm codegen && run-p type-check \"build-only {@}\" -- && pnpm build:dts",
+    "preview": "vite preview",
+    "clean": "rm -rf dist && pnpm clean-modules",
+    "clean-modules": "rm -rf node_modules pnpm-lock.yaml",
+    "build-only": "vite build",
+    "build:dts": "vue-tsc -p tsconfig.build.json --declaration --emitDeclarationOnly",
+    "type-check": "vue-tsc --build",
+    "lint": "eslint . --fix --cache",
+    "format:check": "prettier --check src/",
+    "format": "prettier --write src/",
+    "codegen": "npx js-bao-codegen && pnpm format"
   }
-}
+}