@cavulsqa/create 2.9.2 → 2.10.0

package/templates/m3e-app/.claude/skills/module-architecture/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: module-architecture
+description: Where code goes in this app and how to add a feature end to end. Use when creating a new screen, module, route, domain, repository, composable, or when deciding whether something belongs in modules, domains or shared. Covers the dependency direction, the file layout of a module, and the checklist for wiring a feature into the shell.
+---
+
+# Module architecture
+
+```
+src/
+├── app/tabs.ts                        the navigation destinations, as data
+├── router/index.ts                    aggregates module routes, catch-all last
+├── domains/<domain>/<x>.repository.ts SQL only
+├── modules/<feature>/
+│   ├── router/routes/<feature>.routes.ts
+│   ├── views/<Name>View.vue
+│   ├── components/*.vue
+│   └── composables/use*.ts
+└── shared/                            what two modules genuinely both need
+```
+
+## The seam
+
+| Layer      | Owns                                    | Never contains                               |
+| ---------- | --------------------------------------- | -------------------------------------------- |
+| View       | Wiring a composable to components       | Business logic, SQL                          |
+| Composable | State, queries, actions for one feature | Markup                                       |
+| Repository | Plain functions over Kysely             | `ref`, lifecycle, Framework7, module imports |
+| Component  | Props in, emits out                     | Database access                              |
+
+Dependencies run **modules → domains → shared → packages**, never backwards. A repository importing
+from a module, or `shared` importing from `modules`, means something is in the wrong place.
+
+## Adding a feature
+
+1. `modules/<feature>/` with the four folders. Templates: [file-templates.md](file-templates.md).
+2. SQL in `domains/<domain>/<domain>.repository.ts`, taking the database as its first parameter.
+3. Routes in `modules/<feature>/router/routes/<feature>.routes.ts`, default-exported, registered in
+   `src/router/index.ts` **before** the global catch-all.
+4. A tab in `src/app/tabs.ts` only if it is a top-level section — with both `iconIos` and `iconMd`.
+   Otherwise it is a pushed page, and pushed pages are an `AppPage` with `back`, which hides the navigation bar.
+5. Strings in **both** `locales/en.json` and `locales/fr.json`. A missing key renders as the key.
+   Remember `@` and `|` are message syntax.
+6. A test in `tests/` for anything with SQL.
+7. `vp check`, `vp test`, `pnpm type-check`.
+
+## shared/ is not a junk drawer
+
+Something moves to `shared/` when a second module imports it **today**. The test: name the second
+caller. If you cannot, it lives in the module that uses it.
+
+## Auto-imports
+
+`ref`, `computed`, `watch`, lifecycle hooks, `useI18n`, `@vueuse/core`, `f7`, `f7ready` and
+everything under `shared/composables`, `shared/utils`, `plugins` and `modules/**/composables` are
+auto-imported — no import line. Components under `shared/components` and `modules/**/{views,components}`
+resolve the same way.
+
+Two things are **not** auto-imported and must be declared:
+
+- `f7route` / `f7router` — Framework7 passes them to a route component as props.
+- Repositories and anything under `domains/` — imported explicitly, because a domain is a boundary
+  you should see being crossed.
+
+`auto-imports.d.ts` and `components.d.ts` are generated. Never hand-edit them; if the editor
+disagrees with the build, run the dev server once to regenerate.

package/templates/m3e-app/.claude/skills/module-architecture/file-templates.md

@@ -0,0 +1,178 @@
+# File templates
+
+Copy these shapes. They encode decisions that are easy to get wrong once and then repeat everywhere.
+
+## Route file
+
+`modules/<feature>/router/routes/<feature>.routes.ts`
+
+```ts
+import type { Router } from "framework7/types";
+
+const featureRoutes: Router.RouteParameters[] = [
+  {
+    name: "feature",
+    path: "/feature/",
+    // `async` is Framework7's route hook, not an async function - resolve from the promise.
+    async({ resolve }) {
+      void import("@/modules/feature/views/FeatureView.vue").then((view) => {
+        resolve({ component: view.default });
+      });
+    },
+  },
+  {
+    name: "feature-detail",
+    path: "/feature/:id/",
+    async({ resolve }) {
+      void import("@/modules/feature/views/FeatureDetailView.vue").then((view) => {
+        resolve({ component: view.default });
+      });
+    },
+  },
+];
+
+export default featureRoutes;
+```
+
+`await` inside that hook does not compile — the property is literally named `async`.
+
+## Repository
+
+`domains/<domain>/<domain>.repository.ts`
+
+```ts
+import type { Kysely } from "kysely";
+import { nowISO } from "@cavulsqa/mobile-db";
+import type { Database } from "@/shared/database/schema";
+
+export interface ThingRow {
+  id: number;
+  name: string;
+  totalCents: number;
+}
+
+/** Reads take the database as a parameter - that is what makes them testable. */
+export function listThings(db: Kysely<Database>, term: string): Promise<ThingRow[]> {
+  let query = db.selectFrom("thing").select(["id", "name", "total_cents as totalCents"]);
+  if (term.trim()) query = query.where("name", "like", `%${term.trim()}%`);
+  return query.orderBy("id", "desc").limit(40).execute();
+}
+
+/** All-or-nothing work goes in one transaction. */
+export async function saveThing(
+  db: Kysely<Database>,
+  input: { name: string; lines: Array<{ productId: number; quantity: number }> },
+): Promise<void> {
+  await db.transaction().execute(async (trx) => {
+    const thing = await trx
+      .insertInto("thing")
+      .values({ created_at: nowISO(), name: input.name })
+      .returning("id")
+      .executeTakeFirstOrThrow();
+
+    for (const line of input.lines) {
+      await trx
+        .insertInto("thing_line")
+        .values({ thing_id: thing.id, ...line })
+        .execute();
+    }
+  });
+}
+```
+
+No `ref`, no lifecycle, no Framework7, no imports from `modules/`.
+
+## Composable
+
+`modules/<feature>/composables/useFeature.ts`
+
+```ts
+import { listThings, saveThing, type ThingRow } from "@/domains/thing/thing.repository";
+import { getDatabase, rdb } from "@/shared/database/database";
+import { useReactiveQuery } from "@/shared/database/queries";
+
+export function useFeature() {
+  const term = ref("");
+  const busy = ref(false);
+
+  const query = useReactiveQuery(() => listThings(getDatabase().db, term.value), {
+    // Every table the SQL touches. A join means each joined table.
+    tables: ["thing"],
+    // The term is part of the identity, so the query re-runs (debounced) as it moves.
+    queryKey: ["feature:things", term],
+    debounce: 250,
+  });
+
+  const things = computed<ThingRow[]>(() => query.data.value ?? []);
+
+  // Writes go through `rdb`, which announces the tables they touched.
+  async function save(input: Parameters<typeof saveThing>[1]) {
+    busy.value = true;
+    try {
+      await saveThing(rdb, input);
+    } finally {
+      busy.value = false;
+    }
+  }
+
+  return { term, things, loading: query.loading, busy, save };
+}
+```
+
+`ref`, `computed` and the composable itself are auto-imported. Repositories are not.
+
+## View
+
+`modules/<feature>/views/FeatureView.vue`
+
+```vue
+<template>
+  <AppPage :title="t('feature.title')" name="feature">
+    <SectionHeader :title="t('feature.section')" />
+    <M3List v-if="things.length" variant="segmented" inset>
+      <M3ListItem
+        v-for="thing in things"
+        :key="thing.id"
+        clickable
+        :headline="thing.name"
+        :supporting="formatMoney(thing.totalCents)"
+        @click="f7router.navigate(`/feature/${String(thing.id)}/`)"
+      >
+        <template #leading><i-ms-inventory-2-outline-rounded /></template>
+      </M3ListItem>
+    </M3List>
+    <EmptyState v-else :headline="t('feature.emptyTitle')" :text="t('feature.empty')" />
+  </AppPage>
+</template>
+
+<script setup lang="ts">
+import type { Router } from "framework7/types";
+import { useFeature } from "@/modules/feature/composables/useFeature";
+
+defineProps<{ f7router: Router.Router }>();
+const { t } = useI18n();
+const { things } = useFeature();
+</script>
+```
+
+Components, icons and composables resolve themselves; colours and type come from tokens. The
+`m3-expressive` skill decides which component and which role.
+
+## Pushed detail view
+
+```vue
+<AppPage :title="thing?.name ?? t('feature.title')" back>…</AppPage>
+```
+
+```ts
+const props = defineProps<{ f7route: Router.Route; f7router: Router.Router }>();
+const id = Number(props.f7route.params.id ?? 0);
+```
+
+`back` gives the small app bar with a back button and hides the navigation bar. A detail screen's
+state changes go in an `M3DockedToolbar` in `AppPage`'s `#fixed` slot.
+
+## Test
+
+`tests/<domain>.repository.test.ts` — see the reactive-data skill's testing guide for the harness.
+Assert the arithmetic, the empty state and the idempotence, not just that rows come back.

package/templates/m3e-app/.claude/skills/reactive-data/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: reactive-data
+description: Reading and writing the local SQLite database in this app. Use whenever the task involves a query, a mutation, a repository, a migration, the schema, useReactiveQuery, the change bus, stale data, a screen not refreshing, query metrics, or testing data access. Covers the tables invalidation contract, why every write goes through rdb, and how to test SQL without a device.
+---
+
+# Reactive data workflow
+
+SQLite is the source of truth. A screen reads it through a reactive query; a write announces the
+tables it touched and every query watching one of them refetches. Nothing calls refetch by hand.
+
+## Adding a read
+
+```ts
+const query = useReactiveQuery(() => searchOrders(getDatabase().db, term.value), {
+  tables: ["sales_order", "order_line", "customer"],
+  queryKey: ["demo:orders", term],
+  debounce: 250,
+});
+```
+
+1. Put the SQL in a repository: `src/domains/<domain>/<domain>.repository.ts`, taking the database
+   as its first parameter. Never reach for the singleton inside a repository — that is what makes it
+   testable.
+2. **List every table the SQL touches in `tables`.** Count them in the query, not from memory: a
+   join means each joined table. Under-list and the screen goes stale with no error; over-list and
+   an unrelated write re-runs an expensive query.
+3. `queryKey` is an array of the values the query reads. Two mounted queries whose keys match
+   share one request, so anything that distinguishes them belongs in the key — a route param, a
+   filter ref. Refs are unwrapped and tracked: when one moves the query re-runs through its own
+   `debounce`, so never pair a key with a manual `refetch()`.
+4. `debounce` so a burst of writes causes one refetch.
+
+## Adding a write
+
+```ts
+await saveOrder(rdb, payload);        // announces its tables
+await saveOrder(getDatabase().db, …); // writes, and no screen notices
+```
+
+`rdb` is the reactive wrapper. A raw write lands in SQLite silently and the UI keeps showing old
+rows until something unrelated refetches — no error, nothing to see in review.
+
+All-or-nothing work goes in one transaction. A helper anyone can press twice must survive being
+pressed twice: insert-where-missing, or `onConflict(...).doNothing()`.
+
+## Schema changes
+
+`schema.ts` and `migrations.ts` are edited together — a field in one and not the other is a runtime
+error the compiler cannot see. Migrations are numbered, never renamed, never edited after shipping.
+Money is integer cents. Index what you filter and join by.
+
+## Testing
+
+Always. [testing.md](testing.md) has the harness: a Kysely on `createSqlJsDialect()`, migrate, then
+assert against real rows — including the arithmetic. A total that type-checks can still be computed
+wrong, and a device is not needed to catch that.
+
+## Diagnosing "the screen did not update"
+
+In order:
+
+1. Did the write go through `rdb`?
+2. Does the query's `tables` include the table that changed?
+3. Is the query's `queryKey` shared with a different query? Check the console for the conflict
+   warning.
+4. Is the page off-screen? `usePageVisibility` suppresses refetches for hidden pages by design.
+5. Only then look at the packages.
+
+## Proof obligations
+
+Name the tables the SQL touches and confirm `tables` matches. Say whether a test covers it. Never
+claim a data path works on the strength of a type-check.
+
+## Inserting a parent and its children
+
+The parent and its children go in one transaction, and the parent's id comes from `insertId`:
+
+```ts
+await db.transaction().execute(async (trx) => {
+  const inserted = await trx.insertInto("sales_order").values({ ... }).executeTakeFirstOrThrow();
+  const orderId = Number(inserted.insertId ?? 0);
+  if (!orderId) throw new Error("the order was written but the database reported no id for it");
+  ...
+});
+```
+
+`.returning("id")` looks like the obvious way and is the wrong one: inside an open transaction the
+plugin runs the statement through `query()` and discards its RETURNING rows, so kysely throws
+`no result` from a write that succeeded. `insertId` comes from `last_insert_rowid()` and works on
+both sides of the boundary. Full note in [database.md](../../rules/database.md).

package/templates/m3e-app/.claude/skills/reactive-data/testing.md

@@ -0,0 +1,55 @@
+# Testing data access
+
+The queries run against real SQLite — sql.js, the same dialect `@cavulsqa/mobile-db` uses for its
+own tests. No device, no emulator, about a second for the suite.
+
+## The harness
+
+```ts
+import { beforeEach, expect, test } from "vite-plus/test";
+import { Kysely } from "kysely";
+import { Migrator } from "kysely/migration";
+import { createSqlJsDialect } from "@cavulsqa/mobile-db/testing";
+import { migrations } from "../src/shared/database/migrations.js";
+import type { Database } from "../src/shared/database/schema.js";
+
+let db: Kysely<Database>;
+
+beforeEach(async () => {
+  db = new Kysely<Database>({ dialect: await createSqlJsDialect() });
+  await new Migrator({
+    db,
+    provider: { getMigrations: () => Promise.resolve(migrations) },
+  }).migrateToLatest();
+});
+```
+
+A fresh in-memory database per test, with the app's real migrations applied. `Migrator` comes from
+`kysely/migration` — the root export is a compile-time error in kysely 0.29.
+
+## What to assert
+
+Type-checking proves the query compiles. These are the things it cannot prove:
+
+- **Arithmetic.** Two lines at quantity 1 and 2 × 1000 cents must total 3000. Write the number.
+- **Empty state.** An aggregate over no rows returns `0`, not `null`. `coalesce` is easy to forget
+  and the screen shows a blank tile.
+- **Joins.** Every joined row actually resolves — product names present, customer attached.
+- **Filters.** A search matches on each field it claims to, and returns `[]` for no match.
+- **State machines.** A status cycle lands where you expect at each step.
+- **Idempotence.** Anything a person can press twice, pressed twice. `seedSampleData` threw
+  `UNIQUE constraint failed: tag.label` on the second press and only a test caught it.
+- **Missing rows.** A lookup for an id that does not exist returns `null`, and an update against one
+  is a no-op rather than a throw.
+
+## The icon test
+
+`tests/icons.test.ts` guards a different silent failure: it reads the framework7-icons ttf and
+asserts every name used in `src/` is a real ligature, plus that the five names this app has already
+got wrong stay unresolvable. Extend the second list whenever a wrong name gets through.
+
+## Running
+
+```bash
+vp test        # from templates/m3e-app
+```

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

@@ -0,0 +1,32 @@
+# Which SQLite engine the app opens, and what it falls back to.
+#
+# Copy this file to `.env` and edit. Everything here is baked in at build time - Vite substitutes
+# `import.meta.env` when it bundles - so changing it means rebuilding, not restarting.
+
+# 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 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 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
+# the flush decision to the OS, which is right for a benchmark and wrong for data a person would
+# miss. Batched writes cost almost the same either way.
+VITE_PRAGMA_PROFILE=safe
+
+# Live reload, for development only. Put these in `.env.local` (git-ignored), run the dev server,
+# forward its port to the device, then `npx cap sync android` and install the debug build once:
+#
+#   adb reverse tcp:5173 tcp:5173
+#
+# From then on every edit reloads on the device. The dev server listens on VITE_LIVE_RELOAD_PORT
+# too, so if another project already holds 5173, change it here and reverse that port instead.
+# A build with VITE_ENVIRONMENT=staging or prod ignores these and always loads its bundled files.
+# VITE_LIVE_RELOAD=true
+# VITE_LIVE_RELOAD_PORT=5173
+# VITE_LIVE_RELOAD_HOST=localhost
+# VITE_LIVE_RELOAD_SCHEME=http

package/templates/m3e-app/CLAUDE.md

@@ -0,0 +1,93 @@
+# App instructions
+
+An offline-first mobile app in **Material 3 Expressive**: Vue 3 + Capacitor over a local SQLite
+database that screens read reactively. Framework7 runs underneath as the navigation engine only.
+Generated from `@cavulsqa/template-m3e-app`.
+
+**SQLite is the source of truth.** There is no server in this template. A screen reads the local
+database and a write to the local database refreshes it. If you add a backend, it syncs _into_
+SQLite — it does not become the thing screens read.
+
+## Stack
+
+Vue 3.5 `<script setup lang="ts">` · `@cavulsqa/m3e-vue` components on `@cavulsqa/m3e` tokens ·
+Framework7 9 core (router, views, pages - nothing visual) · Capacitor 8 (Android first) · Kysely over
+SQLite in an OPFS worker · vue-i18n · Tailwind 4 mapped to M3 tokens · Google Sans Flex · Material
+Symbols · Vite+ (`vp`).
+
+| Package                  | What it gives you                                                    |
+| ------------------------ | -------------------------------------------------------------------- |
+| `@cavulsqa/m3e`          | 2025-spec colour, the 35 shapes, springs, wavy progress, every token |
+| `@cavulsqa/m3e-vue`      | The `M3*` components, overlay services, theme application            |
+| `@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.
+
+## Layout
+
+```
+src/
+├── app/            tabs.ts (destinations as data), theme.config.ts (seed, presets, extras)
+├── router/         index.ts aggregates module routes; global/ holds the catch-all
+├── domains/        <domain>/<domain>.repository.ts — SQL, no Vue
+├── modules/        home, demo, gallery, settings — each {router/routes,views,components,composables}
+├── shared/         components (AppPage, SectionHeader, EmptyState), composables (navigation, theme),
+│                   database/, utils/
+├── plugins/        framework7 (engine), m3e (services + haptics), capacitor/, i18n, sqlite
+├── assets/css/     app.css (layers), theme/, layout/ (shell, transitions), base.css
+└── locales/        en.json, fr.json
+```
+
+A module owns its routes, views, components and composables. A `domain` owns SQL and nothing else.
+`shared` is for what two modules both use today.
+
+## Skills and rules
+
+| Skill                 | Reach for it when                                                      |
+| --------------------- | ---------------------------------------------------------------------- |
+| `m3-expressive`       | Any screen, component, layout, motion, colour or icon work             |
+| `reactive-data`       | Any query, mutation, repository, migration, or a screen not refreshing |
+| `module-architecture` | Adding a feature, or deciding where a file belongs                     |
+
+Rules in `.claude/rules/`. The short version, each earned by a real bug:
+
+- **Everything visible is an `M3*` component; Framework7 is the engine.** Five `F7*` components
+  resolve (app, views, view, page, page content). See `.claude/rules/m3e-ui.md`.
+- **Every routed screen is an `AppPage`.** Pushed pages pass `back`; that also hides the bar.
+- **Tokens only.** Roles, the shape scale, `type-*` styles; Tailwind's own palette does not exist
+  here. Hex values live in `src/app/theme.config.ts`.
+- **Overlays go through the M3 services** (`useSnackbar`, `useDialog`, `useActionSheet`,
+  `M3BottomSheet`, `M3Menu`) so Android back closes the top one first.
+- **Icons are `<i-ms-*-rounded />` SVGs**; a wrong name fails the build, which is the point.
+- **A reactive query's `tables` must list exactly what its function reads.** Under-list and the
+  screen goes stale with no error. See `.claude/rules/data-fetching.md`.
+- **Every write goes through `rdb`**, never `getDatabase().db`.
+- **`queryKey` is an identity built from arguments**, not a label: `["demo:order", orderId]`.
+- **An inserted id comes from `insertId`, never `.returning(...)`.** See `.claude/rules/database.md`.
+- **Money is integer cents.**
+- **`f7route` and `f7router` are props**, not imports.
+- **A route loads its component through `lazyRoute`**, never a bare `import().then(resolve)`.
+- **In locale files, `@` and `|` are message syntax.** A literal `@` must be `{'@'}`.
+- **No comments that narrate.** A comment explains a non-obvious _why_.
+
+## Verification
+
+```bash
+vp check          # format, lint, type-check
+vp test           # repository, migration and navigation tests
+pnpm type-check   # vue-tsc, the gate for anything touching .vue
+```
+
+`components.d.ts` and `auto-imports.d.ts` are generated by the dev server and the build; they are
+committed so `vue-tsc` works on a fresh clone.
+
+**Type-checking is not verification for UI.** If you changed something visual, check light and dark,
+a 360dp width and reduced motion, and say plainly whether you have seen it run on a device.
+
+## What not to do
+
+- Do not add a state library or a data-fetching library; see the notes in `@cavulsqa/reactive-vue`.
+- Do not assume the toolchain. Capacitor 8 compiles against **JDK 21**.
+- Do not build for the web. `vp dev` in a browser is for inspection; the target is a device.