@cavulsqa/create 2.10.0 → 2.11.0

package/bin/create.mjs

@@ -7,11 +7,13 @@
  * silent default, because a generated app named "my-app" in the wrong directory is worse than a
  * failed command.
  */
+import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { scaffold } from "../lib/scaffold.mjs";
+import { knownUpdateServer, linkCommands, normaliseUpdateUrl } from "../lib/updates.mjs";
 import {
   defaultTemplate,
   listTemplates,
@@ -50,6 +52,9 @@ Options:
   --app-id ID          android application id (default: com.ayb.<name>)
   --engine ID          which storage engine the app prefers, written to .env
   --pragmas PROFILE    safe (default) or fast
+  --updates            wire Capuchoo over-the-air updates (asked when interactive)
+  --update-url URL     the update server; implies --updates
+  --no-link            with updates, write the files but do not install or run capuchoo init
   --from PATH          use a template directory on disk instead of the bundled ones
   --yes                take the defaults, ask nothing
   --help               this
@@ -73,6 +78,62 @@ function listEngines(templateDir) {
   }
 }
 
+/**
+ * The update server, or undefined for an app without over-the-air updates - the default, because an
+ * updater with nowhere to check is dead weight in every build. Interactive answers are asked again
+ * until they parse; a flag that does not parse is an error.
+ */
+async function chooseUpdates(flags, ask, interactive) {
+  const given = flags.get("update-url");
+  if (typeof given === "string") return normaliseUpdateUrl(given);
+
+  const wanted =
+    flags.has("updates") ||
+    (await ask("Capuchoo over-the-air updates? [y/N]", "n")).toLowerCase().startsWith("y");
+  if (!wanted) return undefined;
+
+  const known = knownUpdateServer();
+  if (!interactive) {
+    if (!known) throw new Error("--updates needs --update-url, or a signed-in capuchoo CLI");
+    return normaliseUpdateUrl(known);
+  }
+  for (;;) {
+    const answer = await ask("Update server URL", known);
+    try {
+      return normaliseUpdateUrl(answer ?? "");
+    } catch (error) {
+      console.log(`  ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+
+/** Runs the server-side half; stops at the first failure and says which step it was. */
+function link(out, appId) {
+  for (const args of linkCommands(appId)) {
+    console.log(`\n> pnpm ${args.join(" ")}`);
+    const result = spawnSync("pnpm", args, {
+      cwd: out,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    if (result.status !== 0) {
+      const why = result.error
+        ? `could not start: ${result.error.message}`
+        : `exited ${result.status}`;
+      console.error(`\nStopped at "pnpm ${args.join(" ")}" (${why}). The rest is below.`);
+      return false;
+    }
+  }
+  return true;
+}
+
+function commandLines(appId) {
+  return linkCommands(appId)
+    .filter(([first]) => first !== "install")
+    .map((args) => `  pnpm ${args.join(" ")}`)
+    .join("\n");
+}
+
 /** npm package names: lowercase, no spaces, no leading dot or underscore. */
 function validName(value) {
   return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(value);
@@ -143,6 +204,8 @@ async function main() {
       throw new Error(`--pragmas must be "safe" or "fast", not "${pragmas}"`);
     }
 
+    const updateUrl = await chooseUpdates(flags, ask, Boolean(rl));
+
     const dir = flags.get("dir") ?? (await ask("Directory", `./${name}`));
     const out = isAbsolute(dir) ? dir : resolve(process.cwd(), dir);
 
@@ -154,17 +217,26 @@ async function main() {
       appName: String(appName),
       engine: typeof engine === "string" ? engine : undefined,
       pragmas: typeof pragmas === "string" ? pragmas : undefined,
+      updateUrl,
     });
 
     console.log(`
 ${appName} created in ${out}
   template  ${template}
-  appId     ${appId}
+  appId     ${appId}${updateUrl ? `\n  updates   ${updateUrl}` : ""}`);
 
-  cd ${basename(out)}
-  pnpm install
-  pnpm dev
+    const wantsLink =
+      Boolean(updateUrl && rl && !flags.has("no-link")) &&
+      (await ask("Install dependencies and link to Capuchoo now? [Y/n]", "y")).toLowerCase() !==
+        "n";
+    // capuchoo init asks its own questions; two readers on one stdin would split the keystrokes.
+    rl?.close();
+    const linked = wantsLink && link(out, appId);
 
+    console.log(`
+  cd ${basename(out)}${linked ? "" : "\n  pnpm install"}
+  pnpm dev
+${updateUrl && !linked ? `\nThen link it to Capuchoo (needs your account):\n${commandLines(appId)}\n` : ""}
 Android needs JDK 21: npx cap add android, then pnpm build && npx cap sync android`);
   } finally {
     rl?.close();

package/lib/scaffold.mjs

@@ -2,13 +2,19 @@ import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node
 import { basename, dirname, join } from "node:path";
 import { listTemplateFiles } from "./templateFiles.mjs";
 import { pruneEngines } from "./pruneEngines.mjs";
+import { addUpdates, linkCommands } from "./updates.mjs";
 
 /** Files whose contents carry the app's identity and have to be rewritten, not copied. */
 function personalise(entry, text, { name, appName }) {
   if (entry === "capacitor.config.ts") {
     return text
-      .replace(/appId: "[^"]*"/, `appId: "${name.appId}"`)
-      .replace(/appName: "[^"]*"/, `appName: "${appName}"`);
+      .replace(/(appId: [^\n"]*")[^"\n]*(")/, `$1${name.appId}$2`)
+      .replace(/(appName: [^\n"]*")[^"\n]*(")/, `$1${appName}$2`);
+  }
+  if (entry === ".env.example") {
+    return text
+      .replace(/^VITE_APP_ID=.*$/m, `VITE_APP_ID=${name.appId}`)
+      .replace(/^VITE_APP_NAME=.*$/m, `VITE_APP_NAME=${appName}`);
   }
   if (entry === "vite.config.ts") {
     return text.replace(
@@ -22,6 +28,26 @@ function personalise(entry, text, { name, appName }) {
   return null;
 }
 
+function updatesReadme(appId) {
+  const commands = linkCommands(appId)
+    .map((args) => `pnpm ${args.join(" ")}`)
+    .join("\n");
+  return `
+## Over-the-air updates
+
+Wired for [Capuchoo](https://www.npmjs.com/package/@capuchoo/cli): the updater packages,
+\`capacitor.config.ts\`, \`notifyAppReady()\` in \`src/main.ts\`, and one flavour per environment in
+\`build/<env>/.env.<env>\`. Linking the app to the server, its channels and the dev and staging ids
+need an account, so they run once:
+
+\`\`\`bash
+${commands}
+\`\`\`
+
+The app ships no update screen: drive it with \`useUpdater()\` from \`@capuchoo/updater/vue\`.
+`;
+}
+
 function manifest(source, { name, appName, templateName }) {
   const pkg = JSON.parse(source);
   const { private: _private, cavulsqa: _cavulsqa, ...rest } = pkg;
@@ -56,7 +82,7 @@ function copyTree(from, to, transform) {
  * The template's dependencies are already concrete - `bundleTemplates.mjs` resolved them when the
  * creator was packed - so nothing here has to know about workspaces or catalogs.
  */
-export function scaffold({ templateDir, out, name, appId, appName, engine, pragmas }) {
+export function scaffold({ templateDir, out, name, appId, appName, engine, pragmas, updateUrl }) {
   if (!existsSync(templateDir)) throw new Error(`no template at ${templateDir}`);
   if (existsSync(out)) throw new Error(`${out} already exists`);
 
@@ -92,6 +118,8 @@ export function scaffold({ templateDir, out, name, appId, appName, engine, pragm
     writeFileSync(join(out, ".env"), `${lines.join("\n")}\n`);
   }
 
+  if (updateUrl) addUpdates(out, { appId, appName, updateUrl });
+
   // pnpm will not finish an install while a dependency's build script is neither allowed nor
   // denied, and vite-plus pulls esbuild in. Without this every generated app fails its first
   // `pnpm install` with ERR_PNPM_IGNORED_BUILDS.
@@ -117,6 +145,9 @@ export function scaffold({ templateDir, out, name, appId, appName, engine, pragm
       "",
       existing,
       "",
+      "# Flavour files are configuration to commit. Last, because the last matching rule wins.",
+      "!build/*/.env.*",
+      "",
     ].join("\n"),
   );
 
@@ -136,7 +167,7 @@ pnpm build && npx cap sync android && npx cap run android
 Android builds need **JDK 21**; an older one fails with \`invalid source release: 21\`.
 
 \`CLAUDE.md\` and \`.claude/\` carry the architecture an agent needs before editing anything here.
-`,
+${updateUrl ? updatesReadme(appId) : ""}`,
   );
 
   return { templateName };

package/lib/updates.mjs

@@ -0,0 +1,209 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * What a Capuchoo-updated app installs, matching what `capuchoo init` would add so its `packages`
+ * step finds everything present. `@capacitor/app` is already a template dependency.
+ */
+export const UPDATE_PACKAGES = {
+  dependencies: {
+    "@capacitor/device": "^8.0.0",
+    "@capgo/capacitor-updater": "^8.0.0",
+    "@capuchoo/updater": "^0.14.1",
+  },
+  devDependencies: {
+    "@capuchoo/cli": "^0.16.4",
+  },
+};
+
+export const FLAVOURS = [
+  { env: "dev", idSuffix: ".dev", nameSuffix: " Dev" },
+  { env: "staging", idSuffix: ".staging", nameSuffix: " Staging" },
+  { env: "prod", idSuffix: "", nameSuffix: "" },
+];
+
+/**
+ * The update server's base URL, normalised: no trailing slash, and no `/api`, because the runtime
+ * appends `/api/update` itself and a doubled segment is a 404 that reads as "no update".
+ */
+export function normaliseUpdateUrl(value) {
+  const trimmed = String(value).trim().replace(/\/+$/, "");
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new Error(
+      `"${value}" is not a URL; give the update server's base, e.g. https://updates.example.com`,
+    );
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error(`the update server must be http(s), not ${url.protocol}`);
+  }
+  if (url.pathname.endsWith("/api")) {
+    throw new Error(
+      `give the server's base URL without /api - the updater appends /api/update itself`,
+    );
+  }
+  return trimmed;
+}
+
+/**
+ * The server the Capuchoo CLI is already signed in to, as the default answer. Only the endpoint is
+ * read; the API key next to it is never touched.
+ */
+export function knownUpdateServer() {
+  if (process.env.CAPUCHOO_ENDPOINT) return process.env.CAPUCHOO_ENDPOINT;
+  try {
+    const config = JSON.parse(readFileSync(join(homedir(), ".capuchoo", "config.json"), "utf8"));
+    return typeof config.endpoint === "string" ? config.endpoint : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function sortedMerge(base = {}, extra) {
+  return Object.fromEntries(
+    Object.entries({ ...base, ...extra }).sort(([a], [b]) => a.localeCompare(b)),
+  );
+}
+
+export function withUpdatePackages(pkg) {
+  return {
+    ...pkg,
+    dependencies: sortedMerge(pkg.dependencies, UPDATE_PACKAGES.dependencies),
+    devDependencies: sortedMerge(pkg.devDependencies, UPDATE_PACKAGES.devDependencies),
+  };
+}
+
+function insertAfter(text, anchor, insertion, file) {
+  const index = text.indexOf(anchor);
+  if (index === -1) throw new Error(`${file} has no "${anchor.trim()}" to wire the updater into`);
+  const at = index + anchor.length;
+  return text.slice(0, at) + insertion + text.slice(at);
+}
+
+/**
+ * The shape `capuchoo init` writes and its doctor checks for. The helper refuses an empty server
+ * URL - an empty one silently disables updates - which is why every flavour file carries one.
+ */
+export function wireCapacitorConfig(text) {
+  const withImport = insertAfter(
+    text,
+    'import type { CapacitorConfig } from "@capacitor/cli";\n',
+    'import { capuchooUpdaterConfig } from "@capuchoo/updater/capacitor";\n',
+    "capacitor.config.ts",
+  );
+  return insertAfter(
+    withImport,
+    "  plugins: {\n",
+    [
+      "    CapacitorUpdater: capuchooUpdaterConfig({",
+      "      apiUrl: process.env.VITE_UPDATE_API_URL,",
+      "      channel: process.env.VITE_UPDATE_CHANNEL,",
+      "    }),",
+      "",
+    ].join("\n"),
+    "capacitor.config.ts",
+  );
+}
+
+/**
+ * `notifyAppReady()` right after the imports and before anything that can throw: a bundle that has
+ * not confirmed it booted within ten seconds is rolled back, working or not.
+ */
+export function wireEntry(text) {
+  const lines = text.split("\n");
+  let last = -1;
+  for (let index = 0; index < lines.length; index++) {
+    if (!/^import\b/.test(lines[index])) continue;
+    last = index;
+    while (last < lines.length - 1 && !/;\s*$/.test(lines[last])) last++;
+    index = last;
+  }
+  if (last === -1) throw new Error("src/main.ts has no imports to place notifyAppReady after");
+  lines.splice(
+    last + 1,
+    0,
+    'import { notifyAppReady } from "@capuchoo/updater";',
+    "",
+    "/** First, unconditionally: an update that does not confirm it booted is rolled back. */",
+    "void notifyAppReady();",
+  );
+  return lines.join("\n");
+}
+
+export function flavourFile({ env, idSuffix, nameSuffix }, { appId, appName, updateUrl }) {
+  return [
+    `# The ${env} flavour. The Capuchoo CLI exports these values when it builds ${env}; see .env.example.`,
+    `VITE_APP_ID=${appId}${idSuffix}`,
+    `VITE_APP_NAME=${appName}${nameSuffix}`,
+    `VITE_ENVIRONMENT=${env}`,
+    `VITE_UPDATE_API_URL=${updateUrl}`,
+    `VITE_UPDATE_CHANNEL=${env}`,
+    "",
+  ].join("\n");
+}
+
+const ENV_EXAMPLE_UPDATES = `
+# Capuchoo over-the-air updates. Each flavour sets these in build/<env>/.env.<env>; capacitor.config.ts
+# loads the one VITE_ENVIRONMENT names (dev by default) so a local \`npx cap sync\` works too.
+#   VITE_UPDATE_API_URL     the update server's base URL, without /api
+#   VITE_UPDATE_CHANNEL     the channel this build follows: dev, staging or prod
+# VITE_UPDATE_PUBLIC_KEY=   release signing; \`capuchoo keys init\` prints it. Once set, unsigned updates are refused.
+`;
+
+/**
+ * Turns a scaffolded app into a Capuchoo-updated one, offline. What needs the server - linking the
+ * app, its channels, registering the flavour ids - is left to `capuchoo init`, which reports
+ * everything written here as already satisfied.
+ */
+export function addUpdates(out, { appId, appName, updateUrl }) {
+  const packagePath = join(out, "package.json");
+  const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+  writeFileSync(packagePath, `${JSON.stringify(withUpdatePackages(pkg), null, 2)}\n`);
+
+  const configPath = join(out, "capacitor.config.ts");
+  writeFileSync(configPath, wireCapacitorConfig(readFileSync(configPath, "utf8")));
+
+  const entryPath = join(out, "src", "main.ts");
+  writeFileSync(entryPath, wireEntry(readFileSync(entryPath, "utf8")));
+
+  for (const flavour of FLAVOURS) {
+    const dir = join(out, "build", flavour.env);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, `.env.${flavour.env}`),
+      flavourFile(flavour, { appId, appName, updateUrl }),
+    );
+  }
+
+  const examplePath = join(out, ".env.example");
+  if (existsSync(examplePath)) {
+    writeFileSync(
+      examplePath,
+      `${readFileSync(examplePath, "utf8").trimEnd()}\n${ENV_EXAMPLE_UPDATES}`,
+    );
+  }
+}
+
+/** The commands that finish the job against the server, in order, for the README and the CLI. */
+export function linkCommands(appId) {
+  return [
+    ["install"],
+    ["exec", "capuchoo", "init", "--app-id", appId],
+    ...FLAVOURS.filter((flavour) => flavour.idSuffix).map((flavour) => [
+      "exec",
+      "capuchoo",
+      "app",
+      "identifiers",
+      "add",
+      `${appId}${flavour.idSuffix}`,
+      "--flavour",
+      flavour.env,
+      "--platform",
+      "all",
+      "--yes",
+    ]),
+  ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavulsqa/create",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Create a Vue + Capacitor + SQLite app from the cavulsqa templates: Framework7 (iOS and Material) or Material 3 Expressive.",
   "keywords": [
     "capacitor",
@@ -60,7 +60,7 @@
       }
     ]
   },
-  "templatesFingerprint": "sha256-3YSsClBPuShazZVtnS9LabHQ330E0wPZiedhN6vIadU=",
+  "templatesFingerprint": "sha256-eIGH2ix9joNhpsfimiVjXn35142qMIzl59n4E69AcYg=",
   "scripts": {
     "build": "node scripts/bundleTemplates.mjs",
     "check": "vp check",

package/templates/f7-app/.claude/rules/native.md

@@ -41,6 +41,23 @@ The tab bar lives in the shell, outside every page, inside `.views.tabs`. So:
   twice.
 - FAB buttons open upward (`position="top"`), or they land behind it.
 
+## Identity, environments and updates come from env
+
+`capacitor.config.ts` reads `VITE_APP_ID` and `VITE_APP_NAME`, falling back to the literals
+`create` wrote. It loads env with Node's own `process.loadEnvFile` - there is no dotenv, and adding
+one is a second loader that disagrees with this one about precedence. Nothing overwrites a value
+already set, so the order is: the shell, `.env.local`, `.env`, then `build/<env>/.env.<env>` for
+`VITE_ENVIRONMENT` (dev by default).
+
+- Change the id or name in the env, never as a second literal in the config.
+- Every variable the app reads is documented in `.env.example`; a new one goes there too.
+- Live reload is `VITE_LIVE_RELOAD=true` in `.env.local`; staging and prod ignore it.
+- An app generated with Capuchoo updates has `build/{dev,staging,prod}/.env.*` (committed - they
+  are configuration, not secrets), `capuchooUpdaterConfig` in the config and `notifyAppReady()`
+  first in `src/main.ts`. Keep that call unconditional and before anything that can throw: a bundle
+  that has not confirmed it booted within ten seconds is rolled back. `pnpm exec capuchoo doctor`
+  checks the whole setup.
+
 ## Proof obligations
 
 Say which platform you tested on. "Type-checks" is not a claim about a device, and neither is a

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

@@ -17,3 +17,24 @@ VITE_STORAGE_ENGINE=sqlite-wasm-opfs-sahpool
 # 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
+
+# App identity, read by capacitor.config.ts, which falls back to the values `create` wrote there. A
+# Capuchoo flavour build exports build/<env>/.env.<env>, and those values win over this file.
+VITE_APP_ID=com.example.app
+VITE_APP_NAME=App
+
+# dev, staging or prod. staging and prod never live-reload, whatever VITE_LIVE_RELOAD says.
+# VITE_ENVIRONMENT=dev
+
+# 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/f7-app/capacitor.config.ts

@@ -1,9 +1,48 @@
 import type { CapacitorConfig } from "@capacitor/cli";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Node's own env loader, so no dotenv. It never overwrites a variable already set, which gives the
+ * precedence: the shell (a Capuchoo flavour build exports its flavour's values) over `.env.local`
+ * over `.env` over the flavour file in `build/`, when the app has one.
+ */
+function loadEnv(file: string): void {
+  const path = join(__dirname, file);
+  if (existsSync(path)) process.loadEnvFile(path);
+}
+
+loadEnv(".env.local");
+loadEnv(".env");
+const ENVIRONMENT = process.env.VITE_ENVIRONMENT || "dev";
+loadEnv(`build/${ENVIRONMENT}/.env.${ENVIRONMENT}`);
+
+/** A flavour built for distribution never points at a laptop, whatever `.env.local` says. */
+const DISTRIBUTED = new Set(["staging", "prod"]);
+
+const liveReload = process.env.VITE_LIVE_RELOAD === "true" && !DISTRIBUTED.has(ENVIRONMENT);
+
+/**
+ * Live reload: the installed debug app loads the dev server instead of its bundled files, so an
+ * edit shows on the device without a rebuild. With `adb reverse tcp:5173 tcp:5173` the device's
+ * localhost is this machine's, so the default host needs no IP and no shared network.
+ */
+function liveReloadUrl(): string | undefined {
+  if (!liveReload) return undefined;
+  const scheme = process.env.VITE_LIVE_RELOAD_SCHEME || "http";
+  const host = process.env.VITE_LIVE_RELOAD_HOST || "localhost";
+  const port = process.env.VITE_LIVE_RELOAD_PORT || "5173";
+  return `${scheme}://${host}:${port}`;
+}
 
 const config: CapacitorConfig = {
-  appId: "com.example.app",
-  appName: "App",
+  appId: process.env.VITE_APP_ID || "com.example.app",
+  appName: process.env.VITE_APP_NAME || "App",
   webDir: "dist",
+  server: {
+    url: liveReloadUrl(),
+    cleartext: liveReload,
+  },
   plugins: {
     SplashScreen: { launchAutoHide: false },
     Keyboard: { resizeOnFullScreen: true },

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

@@ -7,13 +7,23 @@ 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 } from "vite-plus";
+import { defineConfig, loadEnv } from "vite-plus";
 import {
   Framework7VueResolver,
   getFramework7AutoImports,
 } from "./src/shared/utils/resolvers/resolvers.js";
 
 const SRC = fileURLToPath(new URL("./src", import.meta.url));
+const ROOT = fileURLToPath(new URL(".", import.meta.url));
+
+/**
+ * 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;
+}
 
 // Read once so Settings can show the real name and version without importing the manifest
 // into the bundle.
@@ -21,7 +31,7 @@ const pkg = JSON.parse(
   readFileSync(fileURLToPath(new URL("./package.json", import.meta.url)), "utf-8"),
 ) as { name: string; version: string };
 
-export default defineConfig({
+export default defineConfig(({ mode }) => ({
   define: {
     __APP_NAME__: JSON.stringify("App"),
     __APP_VERSION__: JSON.stringify(pkg.version),
@@ -89,7 +99,7 @@ export default defineConfig({
   ],
 
   resolve: { alias: { "@": SRC } },
-  server: { port: 5173 },
+  server: { port: devPort(mode), strictPort: true },
   build: { target: "esnext" },
   lint: { options: { typeAware: false } },
   /**
@@ -101,4 +111,4 @@ export default defineConfig({
   fmt: {
     ignorePatterns: ["**/auto-imports.d.ts", "**/components.d.ts"],
   },
-});
+}));

package/templates/m3e-app/.claude/rules/native.md

@@ -54,6 +54,23 @@ carried by the template. Add it to `android/app/src/main/AndroidManifest.xml` af
   asks the person at runtime only for a permission the manifest declares, so without these the
   lookup fails as `denied` and the chat offers the depot instead.
 
+## Identity, environments and updates come from env
+
+`capacitor.config.ts` reads `VITE_APP_ID` and `VITE_APP_NAME`, falling back to the literals
+`create` wrote. It loads env with Node's own `process.loadEnvFile` - there is no dotenv, and adding
+one is a second loader that disagrees with this one about precedence. Nothing overwrites a value
+already set, so the order is: the shell, `.env.local`, `.env`, then `build/<env>/.env.<env>` for
+`VITE_ENVIRONMENT` (dev by default).
+
+- Change the id or name in the env, never as a second literal in the config.
+- Every variable the app reads is documented in `.env.example`; a new one goes there too.
+- Live reload is `VITE_LIVE_RELOAD=true` in `.env.local`; staging and prod ignore it.
+- An app generated with Capuchoo updates has `build/{dev,staging,prod}/.env.*` (committed - they
+  are configuration, not secrets), `capuchooUpdaterConfig` in the config and `notifyAppReady()`
+  first in `src/main.ts`. Keep that call unconditional and before anything that can throw: a bundle
+  that has not confirmed it booted within ten seconds is rolled back. `pnpm exec capuchoo doctor`
+  checks the whole setup.
+
 ## Proof obligations
 
 Say which platform you tested on. "Type-checks" is not a claim about a device, and neither is a

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

@@ -30,3 +30,11 @@ VITE_PRAGMA_PROFILE=safe
 # VITE_LIVE_RELOAD_PORT=5173
 # VITE_LIVE_RELOAD_HOST=localhost
 # VITE_LIVE_RELOAD_SCHEME=http
+
+# App identity, read by capacitor.config.ts, which falls back to the values `create` wrote there. A
+# Capuchoo flavour build exports build/<env>/.env.<env>, and those values win over this file.
+VITE_APP_ID=com.example.m3e
+VITE_APP_NAME=M3E
+
+# dev, staging or prod. staging and prod never live-reload, whatever VITE_LIVE_RELOAD says.
+# VITE_ENVIRONMENT=dev

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

@@ -2,16 +2,25 @@ import type { CapacitorConfig } from "@capacitor/cli";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
-for (const file of [".env.local", ".env"]) {
+/**
+ * Node's own env loader, so no dotenv. It never overwrites a variable already set, which gives the
+ * precedence: the shell (a Capuchoo flavour build exports its flavour's values) over `.env.local`
+ * over `.env` over the flavour file in `build/`, when the app has one.
+ */
+function loadEnv(file: string): void {
   const path = join(__dirname, file);
   if (existsSync(path)) process.loadEnvFile(path);
 }
 
+loadEnv(".env.local");
+loadEnv(".env");
+const ENVIRONMENT = process.env.VITE_ENVIRONMENT || "dev";
+loadEnv(`build/${ENVIRONMENT}/.env.${ENVIRONMENT}`);
+
 /** A flavour built for distribution never points at a laptop, whatever `.env.local` says. */
 const DISTRIBUTED = new Set(["staging", "prod"]);
 
-const liveReload =
-  process.env.VITE_LIVE_RELOAD === "true" && !DISTRIBUTED.has(process.env.VITE_ENVIRONMENT ?? "");
+const liveReload = process.env.VITE_LIVE_RELOAD === "true" && !DISTRIBUTED.has(ENVIRONMENT);
 
 /**
  * Live reload: the installed debug app loads the dev server instead of its bundled files, so an
@@ -20,15 +29,15 @@ const liveReload =
  */
 function liveReloadUrl(): string | undefined {
   if (!liveReload) return undefined;
-  const scheme = process.env.VITE_LIVE_RELOAD_SCHEME ?? "http";
-  const host = process.env.VITE_LIVE_RELOAD_HOST ?? "localhost";
-  const port = process.env.VITE_LIVE_RELOAD_PORT ?? "5173";
+  const scheme = process.env.VITE_LIVE_RELOAD_SCHEME || "http";
+  const host = process.env.VITE_LIVE_RELOAD_HOST || "localhost";
+  const port = process.env.VITE_LIVE_RELOAD_PORT || "5173";
   return `${scheme}://${host}:${port}`;
 }
 
 const config: CapacitorConfig = {
-  appId: "com.example.m3e",
-  appName: "M3E",
+  appId: process.env.VITE_APP_ID || "com.example.m3e",
+  appName: process.env.VITE_APP_NAME || "M3E",
   webDir: "dist",
   server: {
     url: liveReloadUrl(),

package/templates/m3e-app/package.json

@@ -44,6 +44,7 @@
     "@intlify/unplugin-vue-i18n": "^11.2.5",
     "@types/node": "^24.12.2",
     "@vitejs/plugin-vue": "^6.0.3",
+    "happy-dom": "^20.11.6",
     "sql.js": "1.13.0",
     "typescript": "^5.9.3",
     "unplugin-auto-import": "^21.1.0",