@cavulsqa/create 2.4.0 → 2.7.0

package/README.md

@@ -44,7 +44,7 @@ The `f7-app` template: a tabbed shell, a `domains` / `modules` / `shared` layout
 sales demo over a six-table schema — dashboard aggregates, search, an order sheet, swipe actions,
 a detail screen — with tests against real SQLite.
 
-Underneath it, the data layer this repository publishes: `@cavulsqa/mobile-db` for Capacitor SQLite
+Underneath it, the data layer this repository publishes: `@cavulsqa/mobile-db` for OPFS SQLite
 under Kysely, `@cavulsqa/reactive-db` for the change bus, and `@cavulsqa/reactive-vue` for
 `useReactiveQuery`. A write announces the tables it touched and every query watching them refetches;
 nothing in a screen asks for a refresh.

package/lib/catalog.mjs

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The workspace catalog, as a flat map of `name` to range.
+ *
+ * A deliberately small reader: the catalog is a block of `name: range` and nothing else.
+ */
+export function catalog(repoRoot) {
+  const entries = new Map();
+  let inside = false;
+  for (const line of readFileSync(join(repoRoot, "pnpm-workspace.yaml"), "utf8").split(/\r?\n/)) {
+    if (/^catalog:\s*$/.test(line)) {
+      inside = true;
+      continue;
+    }
+    if (inside && /^\S/.test(line)) break;
+    if (!inside) continue;
+    const match = /^\s+"?([^":]+)"?:\s*(.+?)\s*$/.exec(line);
+    if (match) entries.set(match[1], match[2].replace(/^["']|["']$/g, ""));
+  }
+  return entries;
+}

package/lib/pruneEngines.mjs

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Removes every storage engine the generated app did not ask for.
+ *
+ * Without this the choice is cosmetic: one template means one `package.json`, so picking OPFS still
+ * installed `@capacitor-community/sqlite` and put the native plugin in the APK for code that never
+ * runs - which is the whole reason the engine sits behind its own entry point in `mobile-db`.
+ *
+ * The template describes its own engines in `cavulsqa.engineModules`, so nothing here has a list of
+ * engine names in it. Each module is one candidate file, and every place that references it does so
+ * on a line of its own - a `STORAGE_IDS` entry, an `export` in the candidates barrel, an import
+ * specifier and an entry in `DEFAULT_ORDER`. Dropping whole lines is why this stays a few rules
+ * rather than a parser.
+ */
+export function pruneEngines(out, manifest, engine) {
+  const modules = manifest?.cavulsqa?.engineModules;
+  if (!modules || !engine) return { kept: null, dropped: [] };
+
+  const kept = Object.entries(modules).find(([, module]) => module.engines.includes(engine));
+  if (!kept) return { kept: null, dropped: [] };
+
+  const dropped = Object.entries(modules).filter(([name]) => name !== kept[0]);
+  if (dropped.length === 0) return { kept: kept[0], dropped: [] };
+
+  // A dependency two engines share is not removable, and neither is an engine id that survives.
+  const keptDeps = new Set(kept[1].dependencies ?? []);
+  const deadDeps = new Set();
+  const deadEngines = new Set();
+  const deadExports = new Set();
+  for (const [, module] of dropped) {
+    for (const dep of module.dependencies ?? []) if (!keptDeps.has(dep)) deadDeps.add(dep);
+    for (const id of module.engines) deadEngines.add(id);
+    for (const symbol of module.exports ?? []) deadExports.add(symbol);
+    const file = join(out, module.file);
+    if (existsSync(file)) rmSync(file);
+  }
+
+  dropLines(join(out, "src/shared/database/candidates/types.ts"), (line) =>
+    [...deadEngines].some((id) => line.trim() === `"${id}",`),
+  );
+  dropLines(join(out, "src/shared/database/candidates/index.ts"), (line) =>
+    dropped.some(([, module]) => line.includes(`"./${basenameOf(module.file)}"`)),
+  );
+  dropLines(join(out, "src/app/storage.config.ts"), (line) =>
+    [...deadExports].some((symbol) => line.trim() === `${symbol},`),
+  );
+
+  // `.env.example` documents every engine, one line each. An app that keeps the line for an engine
+  // it no longer has is documentation that lies, and `VITE_STORAGE_ENGINE` would name a candidate
+  // the chain cannot offer.
+  dropLines(join(out, ".env.example"), (line) =>
+    [...deadEngines].some((id) => line.startsWith(`#   ${id} `)),
+  );
+  rewriteLine(join(out, ".env.example"), /^VITE_STORAGE_ENGINE=/, `VITE_STORAGE_ENGINE=${engine}`);
+
+  pruneDependencies(join(out, "package.json"), deadDeps);
+  return { kept: kept[0], dropped: dropped.map(([name]) => name) };
+}
+
+function basenameOf(file) {
+  return file.split("/").pop().replace(/\.ts$/, "");
+}
+
+function dropLines(path, matches) {
+  if (!existsSync(path)) return;
+  const kept = readFileSync(path, "utf8")
+    .split("\n")
+    .filter((line) => !matches(line));
+  writeFileSync(path, kept.join("\n"));
+}
+
+function rewriteLine(path, matches, replacement) {
+  if (!existsSync(path)) return;
+  const lines = readFileSync(path, "utf8")
+    .split("\n")
+    .map((line) => (matches.test(line) ? replacement : line));
+  writeFileSync(path, lines.join("\n"));
+}
+
+function pruneDependencies(path, dead) {
+  if (!existsSync(path) || dead.size === 0) return;
+  const pkg = JSON.parse(readFileSync(path, "utf8"));
+  for (const group of ["dependencies", "devDependencies"]) {
+    if (!pkg[group]) continue;
+    for (const dep of dead) delete pkg[group][dep];
+  }
+  writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`);
+}

package/lib/publishedVersions.mjs

@@ -0,0 +1,40 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Every publishable package under `packages/`, mapped to the version it currently declares. */
+export function publishedVersions(repoRoot) {
+  const versions = new Map();
+  for (const dir of readdirSync(join(repoRoot, "packages")).sort()) {
+    const manifest = join(repoRoot, "packages", dir, "package.json");
+    if (!existsSync(manifest)) continue;
+    const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+    if (!pkg.private) versions.set(pkg.name, pkg.version);
+  }
+  return versions;
+}
+
+/**
+ * The sibling packages the templates declare as `workspace:` deps, in the order they are named.
+ *
+ * These are the ones the bundler rewrites to a concrete `^` range, so they are the ones whose
+ * versions change what a published creator scaffolds.
+ */
+export function workspaceDependencies(repoRoot) {
+  const names = new Set();
+  const templates = join(repoRoot, "templates");
+  if (!existsSync(templates)) return [];
+
+  for (const name of readdirSync(templates).sort()) {
+    const manifest = join(templates, name, "package.json");
+    if (!existsSync(manifest)) continue;
+    const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+    for (const group of [pkg.dependencies, pkg.devDependencies]) {
+      for (const [dep, range] of Object.entries(group ?? {})) {
+        if (typeof range === "string" && range.startsWith("workspace:")) names.add(dep);
+      }
+    }
+  }
+  // Codepoint order, not locale order: this list is hashed, and the hash has to match on every
+  // machine that computes it.
+  return [...names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}

package/lib/scaffold.mjs

@@ -1,3 +1,4 @@
+import { pruneEngines } from "./pruneEngines.mjs";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 
@@ -90,6 +91,13 @@ export function scaffold({ templateDir, out, name, appId, appName, engine, pragm
    * and change, while the choice of engine for one deployment is configuration. `.env.example` is
    * copied in by the template and documents every value.
    */
+  // Before the .env: picking an engine also removes the ones you did not pick, so the app installs
+  // only the plugin or wasm it actually reaches.
+  if (engine) {
+    const templateManifest = JSON.parse(readFileSync(join(templateDir, "package.json"), "utf8"));
+    pruneEngines(out, templateManifest, engine);
+  }
+
   if (engine || pragmas) {
     const lines = ["# Written by @cavulsqa/create. See .env.example for what these mean.", ""];
     if (engine) lines.push(`VITE_STORAGE_ENGINE=${engine}`);

package/lib/templateFingerprint.mjs

@@ -1,19 +1,28 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import { publishedVersions, workspaceDependencies } from "./publishedVersions.mjs";
 
 /**
- * A content hash of every tracked file under `templates/`, used to prove that `@cavulsqa/create`
- * was republished after the templates changed.
+ * A content hash of everything a published creator would bundle, used to prove that
+ * `@cavulsqa/create` was republished after any of it changed.
  *
  * The creator bundles the templates at pack time, so a template fix reaches nobody until a new
  * version of the creator goes out. Nothing about that is visible in a diff, which is exactly the
  * kind of coupling that gets forgotten - so it is checked rather than remembered.
  *
- * It asks git rather than walking the directory. Walking gave two different answers on a Windows
- * working copy and on a CI checkout, because the disk holds whatever each machine happens to have:
- * ignored files, build leftovers, and CRLF where the runner has LF. `git ls-files -s` reports the
- * blob hash recorded in the index, which is normalised, platform-independent, and - the point -
- * describes exactly what a `git clone` of this repository would produce.
+ * Two inputs, because the bundle has two:
+ *
+ *   - The tracked files under `templates/`. It asks git rather than walking the directory. Walking
+ *     gave two different answers on a Windows working copy and on a CI checkout, because the disk
+ *     holds whatever each machine happens to have: ignored files, build leftovers, and CRLF where
+ *     the runner has LF. `git ls-files -s` reports the blob hash recorded in the index, which is
+ *     normalised, platform-independent, and - the point - describes exactly what a `git clone` of
+ *     this repository would produce.
+ *   - The sibling versions the bundler pins those templates to. A template declares
+ *     `workspace:*` and the bundler rewrites it to `^<current version>`, so bumping a library
+ *     changes what the creator scaffolds while leaving every tracked file byte-identical. Hashing
+ *     the files alone said "unchanged" and let the creator keep shipping ranges that no longer
+ *     admitted the packages it was meant to install.
  */
 export function fingerprintTemplates(repoRoot) {
   const listing = execFileSync("git", ["ls-files", "-s", "--", "templates"], {
@@ -25,5 +34,10 @@ export function fingerprintTemplates(repoRoot) {
   const lines = listing.split("\n").filter(Boolean).sort();
   if (!lines.length) throw new Error("git reports no tracked files under templates/");
 
-  return `sha256-${createHash("sha256").update(lines.join("\n")).digest("base64")}`;
+  const versions = publishedVersions(repoRoot);
+  const pins = workspaceDependencies(repoRoot).map((name) => `${name}@${versions.get(name)}`);
+
+  return `sha256-${createHash("sha256")
+    .update([...lines, ...pins].join("\n"))
+    .digest("base64")}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavulsqa/create",
-  "version": "2.4.0",
+  "version": "2.7.0",
   "description": "Create a Vue + Framework7 + Capacitor + SQLite app from the cavulsqa templates.",
   "keywords": [
     "capacitor",
@@ -52,7 +52,7 @@
       }
     ]
   },
-  "templatesFingerprint": "sha256-tG0kS6m1X1FkrDBDpzezvdSxTxaLazPunAi3a0xab7o=",
+  "templatesFingerprint": "sha256-FbgQOdRBk/8d4JoHOGyxK9/r8aLGGRY9ipzvKvfADNk=",
   "scripts": {
     "build": "node scripts/bundleTemplates.mjs",
     "check": "vp check",

package/templates/f7-app/.env.example

@@ -6,15 +6,11 @@
 # The engine tried first. The rest of the chain in src/app/storage.config.ts still follows it as
 # fallback, so this reorders rather than restricts.
 #
-#   sqlite-wasm-opfs-sahpool     official @sqlite.org/sqlite-wasm, OPFS pool. Faster at writes and
-#                                transactions, seeds ~1.8x quicker, and it is the SQLite team's own
-#                                build. The default for those reasons.
-#   wa-sqlite-access-handle-pool wa-sqlite, OPFS pool. Faster at joins and scans on measured
-#                                hardware; a single-maintainer project.
+#   sqlite-wasm-opfs-sahpool     official @sqlite.org/sqlite-wasm on an OPFS pool. Fastest measured, the SQLite team's own build, and the default.
+#   wa-sqlite-access-handle-pool wa-sqlite on an OPFS pool. Faster at joins and scans on measured hardware; a single-maintainer project.
 #   wa-sqlite-opfs-async         wa-sqlite over OPFS without the pool, on the Asyncify build.
-#   wa-sqlite-idb-batch-atomic   SQLite pages in IndexedDB. The slowest, and the only one that works
-#                                without synchronous access handles - the option for a WebView
-#                                between Chromium 86 and 108.
+#   wa-sqlite-idb-batch-atomic   SQLite pages in IndexedDB. The slowest, and the only durable route on a WebView below Chromium 109.
+#   capacitor-sqlite             the native plugin. Slower on every measured axis and it ships in the APK, but a read is not blocked by an in-flight write.
 VITE_STORAGE_ENGINE=sqlite-wasm-opfs-sahpool
 
 # PRAGMA profile. `safe` keeps SQLite's durability guarantee; `fast` trades it for speed by handing

package/templates/f7-app/CLAUDE.md

@@ -10,15 +10,15 @@ SQLite — it does not become the thing screens read.
 ## Stack
 
 Vue 3.5 `<script setup lang="ts">` · Framework7 9 (+ framework7-vue 8) · Capacitor 8 (Android
-first) · Kysely over `@capacitor-community/sqlite` · vue-i18n · Tailwind 4 · Vite+ (`vp`).
+first) · Kysely over SQLite in an OPFS worker · vue-i18n · Tailwind 4 · Vite+ (`vp`).
 
 Data layer comes from three published packages, not from this repo:
 
-| Package                  | What it gives you                                                  |
-| ------------------------ | ------------------------------------------------------------------ |
-| `@cavulsqa/mobile-db`    | The Capacitor SQLite dialect, migrations, transaction-aware writes |
-| `@cavulsqa/reactive-db`  | Change bus, result cache, visibility gate, query metrics           |
-| `@cavulsqa/reactive-vue` | `useReactiveQuery` and the Framework7 page-visibility adapter      |
+| Package                  | What it gives you                                             |
+| ------------------------ | ------------------------------------------------------------- |
+| `@cavulsqa/mobile-db`    | The OPFS worker dialect, migrations, transaction-aware writes |
+| `@cavulsqa/reactive-db`  | Change bus, result cache, visibility gate, query metrics      |
+| `@cavulsqa/reactive-vue` | `useReactiveQuery` and the Framework7 page-visibility adapter |
 
 Do not vendor or fork them. If one is wrong, fix it there and bump the version.
 

package/templates/f7-app/package.json

@@ -12,6 +12,7 @@
     "check": "vp check"
   },
   "dependencies": {
+    "@capacitor-community/sqlite": "^8.1.1",
     "@capacitor/android": "^8.5.0",
     "@capacitor/app": "^8.0.0",
     "@capacitor/core": "^8.0.0",
@@ -19,9 +20,9 @@
     "@capacitor/preferences": "^8.0.0",
     "@capacitor/splash-screen": "^8.0.0",
     "@capacitor/status-bar": "^8.0.0",
-    "@cavulsqa/mobile-db": "^0.6.0",
-    "@cavulsqa/reactive-db": "^0.3.0",
-    "@cavulsqa/reactive-vue": "^0.3.0",
+    "@cavulsqa/mobile-db": "^1.1.0",
+    "@cavulsqa/reactive-db": "^1.1.0",
+    "@cavulsqa/reactive-vue": "^1.1.0",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@tailwindcss/vite": "^4.3.3",
     "@vueuse/core": "^14.4.0",
@@ -53,7 +54,50 @@
       "sqlite-wasm-opfs-sahpool",
       "wa-sqlite-access-handle-pool",
       "wa-sqlite-opfs-async",
-      "wa-sqlite-idb-batch-atomic"
-    ]
+      "wa-sqlite-idb-batch-atomic",
+      "capacitor-sqlite"
+    ],
+    "engineModules": {
+      "opfsSahPool": {
+        "file": "src/shared/database/candidates/opfsSahPool.ts",
+        "engines": [
+          "sqlite-wasm-opfs-sahpool"
+        ],
+        "exports": [
+          "opfsSahPool"
+        ],
+        "dependencies": [
+          "@sqlite.org/sqlite-wasm"
+        ]
+      },
+      "waSqlite": {
+        "file": "src/shared/database/candidates/waSqlite.ts",
+        "engines": [
+          "wa-sqlite-access-handle-pool",
+          "wa-sqlite-opfs-async",
+          "wa-sqlite-idb-batch-atomic"
+        ],
+        "exports": [
+          "waAccessHandlePool",
+          "waOriginPrivateFileSystem",
+          "waIdbBatchAtomic"
+        ],
+        "dependencies": [
+          "wa-sqlite"
+        ]
+      },
+      "capacitorSqlite": {
+        "file": "src/shared/database/candidates/capacitorSqlite.ts",
+        "engines": [
+          "capacitor-sqlite"
+        ],
+        "exports": [
+          "capacitorSqlite"
+        ],
+        "dependencies": [
+          "@capacitor-community/sqlite"
+        ]
+      }
+    }
   }
 }

package/templates/f7-app/src/app/storage.config.ts

@@ -1,4 +1,5 @@
 import {
+  capacitorSqlite,
   isStorageId,
   opfsSahPool,
   waAccessHandlePool,
@@ -10,11 +11,12 @@ import {
 
 /**
  * The knob. Walked in order, first candidate that opens wins, and the rest are never imported - so a
- * chain that stops at the first entry never downloads wa-sqlite's wasm.
+ * chain that stops at the first entry never downloads the others' wasm.
  *
- * Reorder freely to trade speed for reach: `waIdbBatchAtomic` first is the compatibility choice,
- * since IndexedDB is the only durable route on a WebView between Chromium 86 and 108. Only
- * `sqlite-wasm-opfs-sahpool` has been measured on a phone; the rest carry `evidence: "expected"`.
+ * Reorder freely to trade speed for reach: the entries lower down reach older WebViews, and each
+ * one states its own `tradeoff` and whether its `evidence` came from a device or a vendor's README.
+ * Read the list rather than this comment - `@cavulsqa/create` removes the engines an app did not
+ * ask for, so what is below is what this app actually has.
  *
  * No in-memory entry on purpose: a chain that ends somewhere data is not kept is worse than one that
  * fails and names every attempt.
@@ -24,6 +26,7 @@ export const DEFAULT_ORDER: StorageCandidate[] = [
   waAccessHandlePool,
   waOriginPrivateFileSystem,
   waIdbBatchAtomic,
+  capacitorSqlite,
 ];
 
 /**

package/templates/f7-app/src/shared/database/candidates/capacitorSqlite.ts

@@ -0,0 +1,47 @@
+import { Capacitor } from "@capacitor/core";
+import type { StorageCandidate, StorageProbe } from "./types";
+
+/**
+ * `@capacitor-community/sqlite`: a real file behind a native bridge.
+ *
+ * Slower than the OPFS engine on every axis measured on a device - batched writes about 2.4x, the
+ * app's own screen queries about 1.3x - and it needs the plugin in the APK. It is here for the one
+ * thing the worker cannot do: the worker is serial, so a read waits behind an in-flight write,
+ * where this dialect keeps reads outside the write lock. Choose it for an app that writes
+ * continuously while the UI reads, or that needs SQLCipher or native access to the file.
+ */
+function probeNativePlatform(): StorageProbe {
+  if (!Capacitor.isNativePlatform()) {
+    return {
+      supported: false,
+      reason: "the SQLite plugin is native-only; on web it needs jeep-sqlite and a separate store",
+    };
+  }
+  return { supported: true };
+}
+
+export const capacitorSqlite: StorageCandidate = {
+  id: "capacitor-sqlite",
+  label: "Capacitor SQLite · native plugin",
+  tradeoff:
+    "Needs the native plugin in the APK, and every statement crosses the bridge. Slower than the " +
+    "worker engines, but reads are not blocked by an in-flight write.",
+  durable: true,
+  evidence: "measured",
+  probe: probeNativePlatform,
+  createDialect: async () => {
+    const [{ CapacitorSQLite, SQLiteConnection }, { SharedConnectionSQLiteDialect }] =
+      await Promise.all([
+        import("@capacitor-community/sqlite"),
+        import("@cavulsqa/mobile-db/capacitor"),
+      ]);
+
+    const sqlite = new SQLiteConnection(CapacitorSQLite);
+    const name = "app.sqlite3";
+    await sqlite.createConnection(name, false, "no-encryption", 1, false);
+    const database = await sqlite.retrieveConnection(name, false);
+    await database.open();
+
+    return new SharedConnectionSQLiteDialect({ database, sqlite, name, serializeAccess: true });
+  },
+};

package/templates/f7-app/src/shared/database/candidates/index.ts

@@ -1,3 +1,4 @@
 export * from "./types";
 export { opfsSahPool } from "./opfsSahPool";
 export { waAccessHandlePool, waIdbBatchAtomic, waOriginPrivateFileSystem } from "./waSqlite";
+export { capacitorSqlite } from "./capacitorSqlite";

package/templates/f7-app/src/shared/database/candidates/types.ts

@@ -12,6 +12,7 @@ export const STORAGE_IDS = [
   "wa-sqlite-access-handle-pool",
   "wa-sqlite-opfs-async",
   "wa-sqlite-idb-batch-atomic",
+  "capacitor-sqlite",
 ] as const;
 
 export type StorageId = (typeof STORAGE_IDS)[number];