@inglorious/create-app 1.11.0 → 1.12.0

package/README.md

@@ -31,7 +31,7 @@ For the JavaScript and TypeScript Vite templates, the CLI then asks about the ap
 | Add push notifications?   | `--push` / `--no-push`                                                   | Firebase Cloud Messaging, a permission prompt and the Supabase side of sending; turns on PWA support       |
 | Enable PWA support?       | `--pwa` / `--no-pwa`                                                     | `vite-plugin-pwa`, a manifest, icons, and a service worker that keeps installed apps on the latest version |
 
-Every template except `minimal` then asks whether to add agent skills (`--skills` / `--no-skills`). Saying yes runs the [skills CLI](https://skills.sh) in the new project. It asks which coding agents to install for, and installs the [Inglorious Forge skills](https://github.com/IngloriousCoderz/forge-skills) that match your choices: `forge`, `forge-best-practices`, `store`, `web` and `web-best-practices` always, plus `ssx`, `vite-plugin-jsx` or `vite-plugin-vue`, `ui` and `ui-best-practices`, `i18n`, `firebase` and `supabase` when the project uses them. If the install fails, the CLI prints the command to retry it.
+Every template except `minimal` then asks whether to add agent skills (`--skills` / `--no-skills`). Saying yes runs the [skills CLI](https://skills.sh) in the new project. It asks which coding agents to install for, and installs the [Inglorious Forge skills](https://github.com/IngloriousCoderz/forge-skills) that match your choices: `forge`, `forge-best-practices`, `app-recipe`, `store`, `web` and `web-best-practices` always, plus `ssx`, `vite-plugin-jsx` or `vite-plugin-vue`, `ui` and `ui-best-practices`, `i18n`, `firebase` and `supabase` when the project uses them. If the install fails, the CLI prints the command to retry it.
 
 The app is generated in the syntax you chose: lit-html, JSX or Vue. Every question answered on the command line is skipped, so a project can be created without any prompt:
 
@@ -99,7 +99,7 @@ For Android and iOS builds, install Android Studio with the Android SDK and a Ja
 
 Every Vite app is versioned with [Changesets](https://github.com/changesets/changesets): describe each change with `pnpm changeset`, and `pnpm release:version` raises the version in `package.json` and writes `CHANGELOG.md`. The app reads that version as `import.meta.env.VITE_APP_VERSION`.
 
-Mobile apps also get `pnpm mobile:release`, which copies the version into the iOS and Android projects, raises the build number they share (every store upload needs a new one), builds with the values in `.env` rather than `.env.local`, and syncs. The generated README describes the whole release, upload included.
+Mobile apps also get `pnpm mobile:release`, which copies the version into the iOS and Android projects, raises the build number they share (every store upload needs a new one), builds with the values in `.env` rather than `.env.local`, and syncs. The generated README describes the whole release, upload included. With `--push` too, an `app_versions` table in Supabase holds each platform's minimum build: an older install shows nothing but an update page, so raising it makes a release mandatory.
 
 ## License
 

package/bin/index.js

@@ -20,6 +20,7 @@ import { SYNTAXES, TEMPLATES } from "./lib/features.js"
 import { copyDir } from "./lib/file.js"
 import { addFirebaseSupport } from "./lib/firebase.js"
 import { addMobileSupport } from "./lib/mobile.js"
+import { addNativeUpdateSupport } from "./lib/native-update.js"
 import { addPwaSupport } from "./lib/pwa.js"
 import { askAppFeatures } from "./lib/questions.js"
 import { addReleaseSupport } from "./lib/release.js"
@@ -207,6 +208,10 @@ async function main() {
       addFirebaseSupport(targetDir, pkg, { ...features, templatesRoot })
     }
 
+    if (features.mobile && features.push) {
+      addNativeUpdateSupport(targetDir, templatesRoot)
+    }
+
     for (const depType of ["dependencies", "devDependencies"]) {
       if (pkg[depType]) {
         for (const [name, version] of Object.entries(pkg[depType])) {

package/bin/lib/app.js

@@ -6,14 +6,21 @@ import * as jsxComponents from "./app-jsx.js"
 import * as litComponents from "./app-lit.js"
 import * as vueComponents from "./app-vue.js"
 import {
+  CAPACITOR_APP_VERSION,
   CAPACITOR_FIREBASE_VERSION,
   CAPACITOR_VERSION,
   FIREBASE_VERSION,
   INDENTATION,
   SUPABASE_VERSION,
 } from "./constants.js"
-import { ICON_PACKS, LANGUAGES, PROMPT_TEXTS } from "./features.js"
+import {
+  ICON_PACKS,
+  LANGUAGES,
+  NATIVE_UPDATE_TEXTS,
+  PROMPT_TEXTS,
+} from "./features.js"
 import { importBlock } from "./imports.js"
+import { nativeUpdateFiles } from "./native-update.js"
 import { envExample, promptFiles } from "./prompts.js"
 import {
   appModel,
@@ -33,7 +40,8 @@ const COMPONENTS = {
 /**
  * Writes the source of an app with the features chosen: Inglorious UI,
  * routing, page transitions, icon packs, internationalization, a mobile
- * layout, analytics and push prompts, in lit-html, JSX or Vue. It replaces the template's hello world,
+ * layout, analytics and push prompts, and the page that blocks outdated native
+ * builds, in lit-html, JSX or Vue. It replaces the template's hello world,
  * keeping its message type as the example on the home page. The files come
  * out as Prettier and the template's ESLint config would leave them.
  *
@@ -60,6 +68,7 @@ export function addAppFeatures(targetDir, pkg, options) {
   app.links = app.routing && !app.tabs
   app.isVue = app.renderer === "vue"
   app.hasPrompts = app.analytics || app.push
+  app.nativeUpdate = app.mobile && app.push
   app.layout = layout(app)
 
   const components = COMPONENTS[app.renderer]
@@ -93,6 +102,7 @@ export function addAppFeatures(targetDir, pkg, options) {
     Object.assign(files, promptFiles(app))
     files[".env.example"] = envExample(app)
   }
+  if (app.nativeUpdate) Object.assign(files, nativeUpdateFiles(app))
   if (app.isTypeScript) {
     files["types/index.d.ts"] = typesSource(app)
   }
@@ -140,6 +150,10 @@ function addDependencies(pkg, app) {
       CAPACITOR_FIREBASE_VERSION
     pkg.dependencies["@supabase/supabase-js"] = SUPABASE_VERSION
   }
+  if (app.nativeUpdate) {
+    pkg.dependencies["@capacitor/app"] = CAPACITOR_APP_VERSION
+    pkg.dependencies["@inglorious/supabase"] = "workspace:*"
+  }
 }
 
 function catalogue(app, language) {
@@ -148,6 +162,7 @@ function catalogue(app, language) {
     ...LANGUAGES[language].texts,
     ...(app.analytics && { analytics }),
     ...(app.push && { push }),
+    ...(app.nativeUpdate && { nativeUpdate: NATIVE_UPDATE_TEXTS[language] }),
   }
 }
 
@@ -195,12 +210,22 @@ function mainSource(app) {
   if (app.hasPrompts) {
     imports.push('import { renderPrompts } from "./common/prompt"')
   }
+  if (app.nativeUpdate) {
+    imports.push(
+      'import { App as NativeApp } from "@capacitor/app"',
+      'import { when } from "@inglorious/web/directives/when"',
+      'import { watchNativeUpdate } from "@inglorious/web/native-update"',
+    )
+    if (app.isTypeScript) imports.push('import type { AppApi } from "../types"')
+  }
 
   const args = [
     "store",
-    app.hasPrompts
-      ? "(api) => html`${App.render(null, api)} ${renderPrompts(api)}`"
-      : "(api) => App.render(null, api)",
+    app.nativeUpdate
+      ? "renderApp"
+      : app.hasPrompts
+        ? "(api) => html`${App.render(null, api)} ${renderPrompts(api)}`"
+        : "(api) => App.render(null, api)",
     app.isTypeScript
       ? 'document.getElementById("root")!'
       : 'document.getElementById("root")',
@@ -209,9 +234,7 @@ function mainSource(app) {
   const body = app.i18n
     ? `// Mounts once the starting language has loaded, so the first render is
 // already translated.
-ready.then(() =>
-${call("mount", args, "  ", ",")}
-)`
+${afterReady(args)}`
     : call("mount", args, "", "")
 
   const session = app.push
@@ -222,12 +245,35 @@ supabase.auth.onAuthStateChange((_event, session) => {
 })`
     : ""
 
+  const nativeUpdate = app.nativeUpdate
+    ? `
+
+watchNativeUpdate(NativeApp, store)
+
+// An outdated native build shows nothing but the update page.
+function renderApp(api${app.isTypeScript ? ": AppApi" : ""}) {
+  return html\`\${when(
+    api.getEntity("nativeUpdate")${app.isTypeScript ? "!" : ""}.isUpdateRequired,
+    () => api.render("nativeUpdate"),
+    () => html\`\${App.render(null, api)} \${renderPrompts(api)}\`,
+  )}\`
+}`
+    : ""
+
   return `${importBlock(imports)}
 
-${body}${session}
+${body}${session}${nativeUpdate}
 `
 }
 
+function afterReady(args) {
+  const oneLine = `ready.then(() => ${call("mount", args, "", "")})`
+  if (!oneLine.includes("\n") && oneLine.length <= LINE_WIDTH) return oneLine
+  return `ready.then(() =>
+${call("mount", args, "  ", ",")}
+)`
+}
+
 function uiComponents(app) {
   const names = ["app-bar", "container"]
   if (app.links) names.push("link")
@@ -244,6 +290,18 @@ body {
 }
 `
 
+const UPDATE_PAGE = `
+.app-update {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+  padding: 1.5rem;
+  text-align: center;
+}
+`
+
 const PLAIN_PROMPT = `
 .app-prompt {
   position: fixed;
@@ -287,7 +345,7 @@ main {
   align-items: center;
   gap: 1rem;
 }
-${app.tabs && app.hasPrompts ? PROMPT_ABOVE_TABS : ""}`
+${app.tabs && app.hasPrompts ? PROMPT_ABOVE_TABS : ""}${app.nativeUpdate ? UPDATE_PAGE : ""}`
   if (app.ui) {
     return app.isVue
       ? `${layout}
@@ -348,12 +406,18 @@ function storeSource(app) {
       `import { PushPrompt } from "${relative("src/store", app.layout.pushPrompt)}"`,
     )
   }
+  if (app.nativeUpdate) {
+    imports.push(
+      `import { NativeUpdate } from "${relative("src/store", app.layout.nativeUpdate)}"`,
+    )
+  }
 
   const types = ["Message", "Home"]
   if (app.routing) types.push("About", "Router")
   if (app.i18n) types.push("I18n")
   if (app.analytics) types.push("Analytics")
   if (app.push) types.push("PushPrompt")
+  if (app.nativeUpdate) types.push("NativeUpdate")
   const oneLine = `  types: { ${types.join(", ")} },`
   const typesValue =
     oneLine.length <= LINE_WIDTH
@@ -381,6 +445,7 @@ function singletons(app) {
   if (app.i18n) ids.push("i18n")
   if (app.analytics) ids.push("analytics")
   if (app.push) ids.push("pushPrompt")
+  if (app.nativeUpdate) ids.push("nativeUpdate")
   return ids
 }
 
@@ -527,6 +592,22 @@ function typesSource(app) {
     )
     state.push("  pushPrompt: AppPushPromptEntity")
   }
+  if (app.nativeUpdate) {
+    imports.push(
+      `import type {
+  NativeUpdateEntity,
+  NativeUpdateType,
+} from "@inglorious/web/native-update"`,
+    )
+    eventTypes.push("NativeUpdateType")
+    entities.push("AppNativeUpdateEntity")
+    declarations.push(
+      `export interface AppNativeUpdateEntity extends NativeUpdateEntity {
+  type: "NativeUpdate"
+}`,
+    )
+    state.push("  nativeUpdate: AppNativeUpdateEntity")
+  }
 
   return `${importBlock(imports)}
 

package/bin/lib/constants.js

@@ -1,3 +1,4 @@
+export const CAPACITOR_APP_VERSION = "^8.1.2"
 export const CAPACITOR_VERSION = "^8.5.3"
 export const CHANGESETS_VERSION = "^3.0.3"
 export const CAPACITOR_FIREBASE_VERSION = "^8.5.2"

package/bin/lib/features.js

@@ -272,3 +272,62 @@ function from(name, source) {
 function language(title, texts) {
   return { title, texts }
 }
+
+export const NATIVE_UPDATE_TEXTS = {
+  en: {
+    title: "Time to update",
+    body: "This version of the app is no longer supported. Update it to keep going.",
+    bodyNoLink:
+      "This version of the app is no longer supported. Update it from your app store to keep going.",
+    update: "Update",
+  },
+  it: {
+    title: "È ora di aggiornare",
+    body: "Questa versione dell'app non è più supportata. Aggiornala per continuare.",
+    bodyNoLink:
+      "Questa versione dell'app non è più supportata. Aggiornala dal tuo store per continuare.",
+    update: "Aggiorna",
+  },
+  fr: {
+    title: "Mise à jour nécessaire",
+    body: "Cette version de l'app n'est plus prise en charge. Mettez-la à jour pour continuer.",
+    bodyNoLink:
+      "Cette version de l'app n'est plus prise en charge. Mettez-la à jour depuis votre store pour continuer.",
+    update: "Mettre à jour",
+  },
+  de: {
+    title: "Zeit für ein Update",
+    body: "Diese Version der App wird nicht mehr unterstützt. Aktualisiere sie, um weiterzumachen.",
+    bodyNoLink:
+      "Diese Version der App wird nicht mehr unterstützt. Aktualisiere sie in deinem App Store, um weiterzumachen.",
+    update: "Aktualisieren",
+  },
+  es: {
+    title: "Hora de actualizar",
+    body: "Esta versión de la app ya no es compatible. Actualízala para continuar.",
+    bodyNoLink:
+      "Esta versión de la app ya no es compatible. Actualízala desde tu tienda de apps para continuar.",
+    update: "Actualizar",
+  },
+  pt: {
+    title: "Hora de atualizar",
+    body: "Esta versão da app já não é suportada. Atualiza-a para continuar.",
+    bodyNoLink:
+      "Esta versão da app já não é suportada. Atualiza-a na tua loja de apps para continuar.",
+    update: "Atualizar",
+  },
+  ja: {
+    title: "アップデートが必要です",
+    body: "このバージョンのアプリはサポートが終了しました。引き続き使うにはアップデートしてください。",
+    bodyNoLink:
+      "このバージョンのアプリはサポートが終了しました。引き続き使うにはアプリストアからアップデートしてください。",
+    update: "アップデート",
+  },
+  ar: {
+    title: "حان وقت التحديث",
+    body: "لم يعد هذا الإصدار من التطبيق مدعومًا. حدّثه للمتابعة.",
+    bodyNoLink:
+      "لم يعد هذا الإصدار من التطبيق مدعومًا. حدّثه من متجر التطبيقات للمتابعة.",
+    update: "تحديث",
+  },
+}

package/bin/lib/file.js

@@ -8,6 +8,9 @@ import {
   FIRST_ITEM_INDEX,
 } from "./constants.js"
 
+const MIGRATION_STAMP_LENGTH = 14
+const ONE_SECOND = 1
+
 export function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true })
 
@@ -64,6 +67,28 @@ export function injectAfterImport(source, importSource, newImport) {
   )
 }
 
+/**
+ * Prefixes a migration with the current time, as `supabase migration new`
+ * does, a second later than any migration already there.
+ *
+ * @param {string} targetDir
+ * @param {string} name - The file in supabase/migrations.
+ */
+export function stampMigration(targetDir, name) {
+  const migrations = path.join(targetDir, "supabase/migrations")
+  const taken = new Set(
+    fs.readdirSync(migrations).map((file) => file.split("_")[FIRST_ITEM_INDEX]),
+  )
+  const time = new Date()
+  while (taken.has(migrationStamp(time))) {
+    time.setSeconds(time.getSeconds() + ONE_SECOND)
+  }
+  fs.renameSync(
+    path.join(migrations, name),
+    path.join(migrations, `${migrationStamp(time)}_${name}`),
+  )
+}
+
 export function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 }
@@ -86,3 +111,10 @@ export function toJavaIdentifier(value) {
 
   return identifier || "app"
 }
+
+function migrationStamp(time) {
+  return time
+    .toISOString()
+    .replace(/\D/g, "")
+    .slice(FIRST_ITEM_INDEX, MIGRATION_STAMP_LENGTH)
+}

package/bin/lib/firebase.js

@@ -2,10 +2,8 @@ import fs from "fs"
 import { EOL } from "os"
 import path from "path"
 
-import { FIRST_ITEM_INDEX } from "./constants.js"
-import { copyDir } from "./file.js"
+import { copyDir, stampMigration } from "./file.js"
 
-const MIGRATION_STAMP_LENGTH = 14
 const FIRST_NUMBER = 1
 
 /**
@@ -27,7 +25,7 @@ export function addFirebaseSupport(targetDir, pkg, options) {
 
   if (push) {
     copyDir(path.join(templatesRoot, "features/push"), targetDir)
-    stampMigration(targetDir)
+    stampMigration(targetDir, "push.sql")
     pkg.scripts["vault:push"] = "node scripts/push-vault-secrets.mjs"
     keepSupabaseOutOfTypeScript(targetDir)
   }
@@ -63,18 +61,6 @@ function replaceInFile(file, search, replacement) {
   )
 }
 
-function stampMigration(targetDir) {
-  const migrations = path.join(targetDir, "supabase/migrations")
-  const stamp = new Date()
-    .toISOString()
-    .replace(/\D/g, "")
-    .slice(FIRST_ITEM_INDEX, MIGRATION_STAMP_LENGTH)
-  fs.renameSync(
-    path.join(migrations, "push.sql"),
-    path.join(migrations, `${stamp}_push.sql`),
-  )
-}
-
 function appendSetupToReadme(targetDir, { analytics, push, mobile }) {
   const readmePath = path.join(targetDir, "README.md")
   if (!fs.existsSync(readmePath)) return

package/bin/lib/native-update.js

@@ -0,0 +1,119 @@
+import fs from "fs"
+import { EOL } from "os"
+import path from "path"
+
+import { copyDir, stampMigration } from "./file.js"
+import { importBlock } from "./imports.js"
+import { relative } from "./source.js"
+
+const README_SECTION = `## Mandatory Native Updates
+
+The native apps carry their web code inside the binary, so only the stores update them. Each platform's row in the \`app_versions\` table holds the oldest build allowed to run: an older one shows nothing but an update page, at launch and whenever it comes back to the foreground.
+
+Once a new build is live in a store, raise that platform's minimum to its build number:
+
+\`\`\`sql
+update public.app_versions set min_build = 7 where platform = 'android';
+\`\`\`
+
+Never before: users would be blocked with nothing to download. Set \`store_url\` to the store page, or the update page shows no button. A failed check keeps the last answer, so nobody is blocked for being offline.
+
+Older builds keep talking to the backend until they are blocked, so a change that breaks them ships in two releases: a build that works with both backends, made mandatory, then the breaking change.`
+
+/**
+ * The source of the NativeUpdate type: the page that blocks a native build
+ * older than the minimum in Supabase. Lit-html in every syntax, like the
+ * prompts: src/main renders it in place of the app.
+ *
+ * @param {{ ui: boolean, i18n: boolean, ext: string, isTypeScript: boolean, layout: Record<string, string> }} app
+ * @returns {Record<string, string>} Sources by file path.
+ */
+export function nativeUpdateFiles(app) {
+  return {
+    [`${app.layout.nativeUpdate}/index.${app.ext}`]: nativeUpdateSource(app),
+  }
+}
+
+/**
+ * Adds what mandatory native updates need outside src/: the app_versions
+ * table and how to raise its minimum in the README.
+ *
+ * @param {string} targetDir
+ * @param {string} templatesRoot
+ */
+export function addNativeUpdateSupport(targetDir, templatesRoot) {
+  copyDir(path.join(templatesRoot, "features/native-update"), targetDir)
+  stampMigration(targetDir, "native_update.sql")
+  appendToReadme(targetDir)
+}
+
+function nativeUpdateSource(app) {
+  const at = app.layout.nativeUpdate
+  const imports = [
+    'import { supabaseNativeUpdate } from "@inglorious/supabase"',
+    'import { html } from "@inglorious/web"',
+    'import { when } from "@inglorious/web/directives/when"',
+    'import { createNativeUpdate } from "@inglorious/web/native-update"',
+    `import { supabase } from "${relative(at, "src/api/supabase")}"`,
+  ]
+  if (app.ui) imports.push('import { Button } from "@inglorious/ui/button"')
+  if (app.i18n) imports.push(`import { t } from "${relative(at, "src/i18n")}"`)
+  if (app.isTypeScript) {
+    imports.push(
+      `import type { AppApi, AppNativeUpdateEntity } from "${relative(at, "types")}"`,
+    )
+  }
+  const label = (key, text) =>
+    app.i18n ? `t("nativeUpdate.${key}")` : JSON.stringify(text)
+  const text = (key, plain) =>
+    app.i18n ? `\${t("nativeUpdate.${key}")}` : plain
+  const params = app.isTypeScript
+    ? "entity: AppNativeUpdateEntity, api: AppApi"
+    : "entity, api"
+  const button = app.ui
+    ? `\${when(entity.storeUrl, () =>
+        Button.render({
+          children: ${label("update", "Update")},
+          color: "primary",
+          onClick: () => api.notify(\`#\${entity.id}:nativeUpdateApply\`),
+        }),
+      )}`
+    : `\${when(
+        entity.storeUrl,
+        () =>
+          html\`<button
+            @click=\${() => api.notify(\`#\${entity.id}:nativeUpdateApply\`)}
+          >
+            ${text("update", "Update")}
+          </button>\`,
+      )}`
+
+  return `${importBlock(imports)}
+
+export const NativeUpdate = {
+  ...createNativeUpdate({ adapter: supabaseNativeUpdate(supabase) }),
+
+  render(${params}) {
+    const body = entity.storeUrl
+      ? ${label("body", "This version of the app is no longer supported. Update it to keep going.")}
+      : ${label("bodyNoLink", "This version of the app is no longer supported. Update it from your app store to keep going.")}
+
+    return html\`<main class="app-update">
+      <h1>${text("title", "Time to update")}</h1>
+      <p>\${body}</p>
+      ${button}
+    </main>\`
+  },
+}
+`
+}
+
+function appendToReadme(targetDir) {
+  const readmePath = path.join(targetDir, "README.md")
+  if (!fs.existsSync(readmePath)) return
+  const readme = fs.readFileSync(readmePath, "utf-8")
+  fs.writeFileSync(
+    readmePath,
+    `${readme.trimEnd()}${EOL}${EOL}${README_SECTION}${EOL}`,
+  )
+}

package/bin/lib/skills.js

@@ -18,6 +18,7 @@ export function skillsFor({
   const skills = [
     "forge",
     "forge-best-practices",
+    "app-recipe",
     "store",
     "web",
     "web-best-practices",

package/bin/lib/source.js

@@ -42,6 +42,7 @@ export function layout(app) {
     message: `${screens}/home/message`,
     analytics: "src/app/analytics",
     pushPrompt: "src/app/push-prompt",
+    nativeUpdate: "src/app/native-update",
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/create-app",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "A scaffolding tool to quickly create a new app with Inglorious Web.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",

package/templates/features/native-update/supabase/migrations/native_update.sql

@@ -0,0 +1,17 @@
+-- The oldest native build allowed to run on each platform. Readable before
+-- sign-in, so an outdated app is stopped on its login screen too.
+create table public.app_versions (
+  platform text primary key check (platform in ('ios', 'android')),
+  min_build integer not null check (min_build >= 1),
+  store_url text
+);
+
+alter table public.app_versions enable row level security;
+
+create policy "Anyone reads the minimum app versions"
+  on public.app_versions for select to anon, authenticated
+  using (true);
+
+insert into public.app_versions (platform, min_build) values
+  ('ios', 1),
+  ('android', 1);