@cavulsqa/create 2.9.3 → 2.10.0

package/templates/m3e-app/tests/storage.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, expect, test } from "vite-plus/test";
+import { DEFAULT_ORDER, storageChain } from "../src/app/storage.config.js";
+import {
+  describeOpenFailure,
+  MINIMUM_CHROMIUM_FOR_OPFS,
+  probeOpfsCapable,
+  webviewLikelyTooOld,
+  webviewVersion,
+} from "../src/shared/database/storage.js";
+
+const original = globalThis.navigator;
+
+afterEach(() => {
+  if (original)
+    Object.defineProperty(globalThis, "navigator", { value: original, configurable: true });
+});
+
+function withNavigator(value: unknown): void {
+  Object.defineProperty(globalThis, "navigator", { value, configurable: true });
+}
+
+/**
+ * The regression this exists for: the probe used to require `createSyncAccessHandle` on
+ * `FileSystemFileHandle.prototype`. That method is Worker-only in Chromium, so it is absent on the
+ * main thread of every device - and the check rejected a phone on WebView 150 that had been running
+ * OPFS for hours. A main-thread probe may only look at what the main thread can see.
+ */
+test("a WebView that supports OPFS passes even without the worker-only method", () => {
+  withNavigator({ storage: { getDirectory: () => Promise.resolve({}) } });
+  expect("createSyncAccessHandle" in (globalThis.FileSystemFileHandle?.prototype ?? {})).toBe(
+    false,
+  );
+  expect(probeOpfsCapable().supported).toBe(true);
+});
+
+test("a WebView with no OPFS at all is refused, and told what to do", () => {
+  withNavigator({ storage: {} });
+  const probe = probeOpfsCapable();
+  expect(probe.supported).toBe(false);
+  expect(probe.reason).toMatch(/Android System WebView/);
+});
+
+test("an open failure is translated into something actionable", () => {
+  const sah = describeOpenFailure(new Error("createSyncAccessHandle is not a function"));
+  expect(sah).toMatch(/Android System WebView/);
+  // The other cause of the same failure, and the one a person can actually fix themselves.
+  expect(sah).toMatch(/still holds the database open/);
+  // The engine's own words are kept, so a bug report has something to go on.
+  expect(sah).toContain("createSyncAccessHandle is not a function");
+
+  expect(describeOpenFailure(new Error("disk I/O error"))).toBe(
+    "The database could not be opened: disk I/O error",
+  );
+});
+
+/**
+ * The chain is a claim about ordering, so it is checked like one: fastest first, durable before
+ * volatile, and nothing in it without a stated cost.
+ */
+test("the storage chain is ordered and honest about what each entry costs", () => {
+  expect(storageChain.length).toBeGreaterThan(0);
+
+  // The ranking is asserted against the default order, not the live chain: VITE_STORAGE_ENGINE
+  // reorders the chain on purpose, and a generated app that chose another engine is not broken.
+  expect(DEFAULT_ORDER[0]?.id).toBe("sqlite-wasm-opfs-sahpool");
+  expect(DEFAULT_ORDER[0]?.evidence).toBe("measured");
+
+  // Whatever the environment asked for, the chain must still be every candidate exactly once -
+  // promoting one may not drop the others, or the fallback silently disappears.
+  expect([...storageChain].sort((a, b) => (a.id < b.id ? -1 : 1))).toEqual(
+    [...DEFAULT_ORDER].sort((a, b) => (a.id < b.id ? -1 : 1)),
+  );
+
+  for (const candidate of DEFAULT_ORDER) {
+    expect(candidate.tradeoff.length, candidate.id).toBeGreaterThan(20);
+    expect(candidate.label.length, candidate.id).toBeGreaterThan(5);
+  }
+
+  // Nothing in the chain may be volatile: a silent stop somewhere data is not kept is worse than
+  // an error that names every attempt.
+  expect(storageChain.filter((candidate) => !candidate.durable)).toEqual([]);
+
+  // Every engine gets a probe of its own; sharing one would hide that IndexedDB needs no OPFS.
+  expect(storageChain.every((candidate) => typeof candidate.probe === "function")).toBe(true);
+
+  // Ids are unique, or results keyed by id would overwrite each other.
+  expect(new Set(storageChain.map((c) => c.id)).size).toBe(storageChain.length);
+});
+
+/** The floor is reported, never enforced: a vendor build can differ, so it informs and nothing else. */
+test("the WebView version is read from the user agent and judged against the floor", () => {
+  withNavigator({
+    storage: { getDirectory: () => Promise.resolve({}) },
+    userAgent: "Mozilla/5.0 (Linux; Android 16) AppleWebKit/537.36 Chrome/150.0.7871.183 Mobile",
+  });
+  expect(webviewVersion()).toBe(150);
+  expect(webviewLikelyTooOld()).toBe(false);
+  // Support is still asserted, because the floor must not become a second gate on a working device.
+  expect(probeOpfsCapable().supported).toBe(true);
+
+  withNavigator({
+    storage: { getDirectory: () => Promise.resolve({}) },
+    userAgent: "Mozilla/5.0 (Linux; Android 7.0) AppleWebKit/537.36 Chrome/51.0.2704.90 Mobile",
+  });
+  expect(webviewVersion()).toBe(51);
+  expect(webviewLikelyTooOld()).toBe(true);
+
+  withNavigator({
+    storage: { getDirectory: () => Promise.resolve({}) },
+    userAgent: "something else",
+  });
+  expect(webviewVersion()).toBe(null);
+  // Unknown is not old: an unparseable agent must not lock anybody out.
+  expect(webviewLikelyTooOld()).toBe(false);
+
+  expect(MINIMUM_CHROMIUM_FOR_OPFS).toBe(109);
+});

package/templates/m3e-app/tests/textDirection.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "vite-plus/test";
+import { textDirection } from "../src/shared/utils/textDirection.js";
+
+test("a language reads the way its script is written", () => {
+  expect(textDirection("ar")).toBe("rtl");
+  expect(textDirection("ar-DZ")).toBe("rtl");
+  expect(textDirection("he")).toBe("rtl");
+  expect(textDirection("fr")).toBe("ltr");
+  expect(textDirection("en-US")).toBe("ltr");
+  expect(textDirection("not a locale")).toBe("ltr");
+});

package/templates/m3e-app/tooling/linkedPackages.ts

@@ -0,0 +1,112 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import type { Plugin, ViteDevServer } from "vite-plus";
+
+/** Quiet time after the last write before a rebuild counts as finished. */
+const SETTLE_MS = 300;
+
+const pathKey = (path: string) => {
+  const absolute = resolve(path);
+  return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+};
+
+/**
+ * `@cavulsqa` packages linked from the workspace, as opposed to installed from the registry - the
+ * ones whose `dist` changes under a running dev server while their watchers rebuild them.
+ */
+export function linkedPackages(root: string, names: readonly string[]): string[] {
+  return names.filter((name) => {
+    const path = join(root, "node_modules", name);
+    return existsSync(path) && !realpathSync(path).split(sep).includes("node_modules");
+  });
+}
+
+function exportedFiles(packageDir: string): string[] {
+  const manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8")) as {
+    exports?: unknown;
+    main?: string;
+    module?: string;
+  };
+  const files = new Set<string>();
+  const collect = (value: unknown) => {
+    if (typeof value === "string" && !value.includes("*")) files.add(join(packageDir, value));
+    else if (value && typeof value === "object") Object.values(value).forEach(collect);
+  };
+  collect(manifest.exports);
+  collect(manifest.main);
+  collect(manifest.module);
+  return [...files];
+}
+
+/**
+ * One clean reload per rebuild of a linked package. Left to itself the dev server reloads on the
+ * first file the build touches - often while `dist` has just been emptied, so the page asks for an
+ * entry that is not there yet and boots blank. It also never notices the stylesheet `app.css`
+ * imports, so a rebuild paired new JavaScript with old scoped styles. Here every change or
+ * deletion under a linked `dist` - through both of Vite's HMR hooks - is held back until writing
+ * stops and every exported file exists again with the same size on two checks in a row (a file that
+ * exists can still be half written); then the dev server restarts, and the page reloads when it
+ * reconnects.
+ *
+ * A restart rather than a module invalidation, because the native resolver caches what it saw
+ * while `dist` was empty: an app file transformed in that window keeps failing with "Failed to
+ * resolve import" after the rebuild, since the resolver's cache is keyed by the real path and the
+ * app reaches the package through its `node_modules` link. A restart starts every cache fresh.
+ */
+export function linkedRebuilds(root: string, names: readonly string[]): Plugin {
+  const packages = names.map((name) => realpathSync(join(root, "node_modules", name)));
+  const dists = packages.map((dir) => pathKey(join(dir, "dist")) + sep);
+  const required = packages.flatMap(exportedFiles);
+  const inDist = (file: string) => dists.some((dist) => pathKey(file).startsWith(dist));
+
+  let server: ViteDevServer | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let sizes = "";
+
+  const snapshot = () =>
+    required.map((file) => (existsSync(file) ? statSync(file).size : -1)).join(",");
+
+  const reload = () => {
+    if (!server) return;
+    const now = snapshot();
+    const settled = now === sizes && !now.split(",").includes("-1");
+    sizes = now;
+    if (!settled) {
+      timer = setTimeout(reload, SETTLE_MS);
+      return;
+    }
+    const restarting = server;
+    server = undefined;
+    restarting.config.logger.info("linked package rebuilt - restarting", { timestamp: true });
+    restarting.restart().catch((error: unknown) => {
+      restarting.config.logger.error(`restart after a linked rebuild failed: ${String(error)}`);
+    });
+  };
+
+  const schedule = () => {
+    clearTimeout(timer);
+    sizes = "";
+    timer = setTimeout(reload, SETTLE_MS);
+  };
+
+  return {
+    name: "cavulsqa:linked-rebuilds",
+    apply: "serve",
+    configureServer(devServer) {
+      if (packages.length === 0) return;
+      server = devServer;
+      devServer.watcher.add(packages.map((dir) => join(dir, "dist")));
+      for (const event of ["add", "change", "unlink"] as const) {
+        devServer.watcher.on(event, (file) => {
+          if (inDist(file)) schedule();
+        });
+      }
+    },
+    hotUpdate({ file }) {
+      if (inDist(file)) return [];
+    },
+    handleHotUpdate({ file }) {
+      if (inDist(file)) return [];
+    },
+  };
+}

package/templates/m3e-app/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
+}

package/templates/m3e-app/vite.config.ts

@@ -0,0 +1,144 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath, URL } from "node:url";
+import { M3eResolver } from "@cavulsqa/m3e-vue/resolver";
+import VueI18nPlugin from "@intlify/unplugin-vue-i18n/vite";
+import tailwindcss from "@tailwindcss/vite";
+import vue from "@vitejs/plugin-vue";
+import AutoImport from "unplugin-auto-import/vite";
+import Icons from "unplugin-icons/vite";
+import IconsResolver from "unplugin-icons/resolver";
+import Components from "unplugin-vue-components/vite";
+import { defineConfig, loadEnv } from "vite-plus";
+import { linkedPackages, linkedRebuilds } from "./tooling/linkedPackages.js";
+import {
+  Framework7VueResolver,
+  getFramework7AutoImports,
+} from "./src/shared/utils/resolvers/resolvers.js";
+
+const SRC = fileURLToPath(new URL("./src", import.meta.url));
+
+const pkg = JSON.parse(
+  readFileSync(fileURLToPath(new URL("./package.json", import.meta.url)), "utf-8"),
+) as { name: string; version: string };
+
+/**
+ * One port for the dev server and the live-reload URL `capacitor.config.ts` builds, both read from
+ * `VITE_LIVE_RELOAD_PORT` - change it when another dev server already holds 5173.
+ */
+function devPort(mode: string): number {
+  const port = Number(loadEnv(mode, ROOT, "VITE_").VITE_LIVE_RELOAD_PORT);
+  return Number.isInteger(port) && port > 0 ? port : 5173;
+}
+
+const ROOT = fileURLToPath(new URL(".", import.meta.url));
+/**
+ * Linked workspace packages skip pre-bundling: Vite keeps a pre-bundle until the lockfile changes,
+ * so a package rebuilt by its watcher would keep serving its old JavaScript.
+ */
+const LINKED = linkedPackages(ROOT, ["@cavulsqa/m3e", "@cavulsqa/m3e-vue"]);
+
+export default defineConfig(({ mode }) => ({
+  define: {
+    __APP_NAME__: JSON.stringify("App"),
+    __APP_VERSION__: JSON.stringify(pkg.version),
+  },
+
+  plugins: [
+    linkedRebuilds(ROOT, LINKED),
+    vue({
+      template: {
+        compilerOptions: {
+          isCustomElement: (tag) => tag === "jeep-sqlite",
+        },
+      },
+    }),
+
+    tailwindcss(),
+
+    /**
+     * Material Symbols as tree-shaken SVG components from the installed collection, never a font
+     * and never fetched: `autoInstall` off means a misspelt name fails the build instead of
+     * downloading something at dev time or rendering an empty box on a device.
+     */
+    Icons({ autoInstall: false, compiler: "vue3", scale: 1 }),
+
+    VueI18nPlugin({
+      include: [fileURLToPath(new URL("./src/locales/**", import.meta.url))],
+    }),
+
+    AutoImport({
+      include: [/\.[tj]sx?$/, /\.vue$/, /\.vue\?vue/],
+      exclude: [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/, /[\\/]dist[\\/]/],
+      imports: [
+        "vue",
+        "vue-i18n",
+        "@vueuse/core",
+        getFramework7AutoImports(),
+        {
+          "@cavulsqa/m3e-vue": [
+            "useSnackbar",
+            "useNotification",
+            "useDialog",
+            "useActionSheet",
+            "useHaptics",
+            "useReducedMotion",
+          ],
+        },
+      ],
+      dirs: [
+        "src/shared/composables/**",
+        "src/shared/utils/**",
+        "src/plugins/**",
+        "src/modules/**/composables/**",
+      ],
+      dts: "auto-imports.d.ts",
+      vueTemplate: true,
+      viteOptimizeDeps: true,
+      injectAtEnd: true,
+      dirsScanOptions: { types: true },
+    }),
+
+    /**
+     * Three resolvers, one per source: `M3*` from @cavulsqa/m3e-vue (everything visible), the five
+     * Framework7 engine components (app, views, view, page, page content - nothing visual), and
+     * `i-ms-*` icons from Material Symbols. No screen imports any of them by hand.
+     */
+    Components({
+      dts: "components.d.ts",
+      dirs: ["src/shared/components/**", "src/modules/**/views/**", "src/modules/**/components/**"],
+      extensions: ["vue"],
+      deep: true,
+      resolvers: [
+        M3eResolver(),
+        Framework7VueResolver(),
+        IconsResolver({
+          prefix: "i",
+          alias: { ms: "material-symbols" },
+          enabledCollections: ["material-symbols"],
+        }),
+      ],
+    }),
+  ],
+
+  resolve: { alias: { "@": SRC } },
+  server: { port: devPort(mode), strictPort: true },
+  optimizeDeps: {
+    exclude: LINKED,
+    include: LINKED.includes("@cavulsqa/m3e")
+      ? ["@cavulsqa/m3e > @material/material-color-utilities"]
+      : [],
+  },
+  build: { target: "esnext" },
+  test: {
+    server: {
+      deps: {
+        /** material-color-utilities 0.4.0 has an extensionless import Node's ESM loader rejects. */
+        inline: ["@material/material-color-utilities"],
+      },
+    },
+  },
+  lint: { options: { typeAware: false } },
+  fmt: {
+    ignorePatterns: ["**/auto-imports.d.ts", "**/components.d.ts"],
+  },
+}));