@moifort/stack 0.0.0-stage → 0.1.0

package/templates/backend/server/utils/slug.ts

@@ -0,0 +1,21 @@
+const LEADING_ARTICLES = /^(the|a|an|le|la|les|l|un|une|des|du|de)[\s-]+/
+
+/** Folds a title, a saga name or an author into a key two spellings of the same
+ *  thing agree on. Diacritics are dropped, punctuation collapses to a separator
+ *  and a leading article is removed, so "L'Assassin royal" and "Assassin Royal"
+ *  meet.
+ *
+ *  Shared because two different things are keyed on it and they must agree: the
+ *  series catalogue's document id, which two readers have to converge on, and the
+ *  match that tells an import a book is already on the reader's shelves. */
+export const slugify = (value: string): string =>
+  value
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/['’]/g, ' ')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim()
+    .replace(LEADING_ARTICLES, '')
+    .trim()
+    .replace(/\s+/g, '-')

package/templates/backend/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./.nitro/types/tsconfig.json",
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "useUnknownInCatchVariables": true,
+    "noUnusedLocals": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["nitropack", "bun-types"],
+    "lib": ["ESNext", "DOM"]
+  }
+}

package/templates/base/.github/workflows/renovate.yml

@@ -0,0 +1,17 @@
+name: Renovate
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 20 * * *' # 22h CET / 21h UTC
+
+jobs:
+  renovate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: renovatebot/github-action@v46.3.9
+        with:
+          token: ${{ secrets.RENOVATE_TOKEN }}
+        env:
+          RENOVATE_REPOSITORIES: ${{ github.repository }}

package/templates/base/CHANGELOG.fr.md

@@ -0,0 +1,3 @@
+# Journal des modifications
+
+Traduction française de `CHANGELOG.md`, qui fait foi. Les deux fichiers avancent ensemble.

package/templates/base/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+English is the source of truth. Every served language has its own file, kept in lockstep:
+`CHANGELOG.fr.md`. Only what a user notices is logged, in their words.
+
+Each version heading carries the App Store version and its release date: `## 1.0 (2026.10.01)`.
+Entries are written when an App Store release is cut, never ahead of it.

package/templates/base/CLAUDE.md

@@ -0,0 +1,34 @@
+# {{APP_NAME}}
+
+<!-- stack:rules -->
+<!-- /stack:rules -->
+
+What the app is, in two sentences, for someone who has never opened it.
+
+The rules above are the Polyforms stack, version `{{STACK_VERSION}}` (`stack/VERSION`), and
+this file holds only what is specific to this project. The project's facts (ids, accounts,
+devices, certificates, pending work) are in [project-context.md](project-context.md).
+
+## Commands
+
+| Purpose | Command |
+|---|---|
+| Typecheck | `bun run typecheck` |
+| Tests, by family | `bun run test:unit`, `bun run test:int`, `bun run test:feat` |
+| Preflight (all of the above plus lint) | `bun run preflight` |
+| Linter | `bun run lint` / `bun run lint:fix` |
+| GraphQL schema | `bun run generate:graphql` |
+| Schema compatibility | `bun run schema:check` |
+| Deprecations | `bun run deprecations` |
+| Dev server | `bun run dev` |
+| Stack in sync | `bun run stack:check` |
+
+## Data model
+
+What is private and what is shared, the collections and their keys, the invariants a
+reviewer must know before touching a domain. Written once the first domain exists.
+
+## Traps of this project
+
+One line per trap, with the symptom and the way around it. Anything that would hold in
+another project goes into the stack instead of here.

package/templates/base/README.md

@@ -0,0 +1,12 @@
+# {{APP_NAME}}
+
+What the app does, for someone who has never opened it. Why before how, numbered steps, no
+deep architecture and no screenshot that ages.
+
+## Run it
+
+1. `bun install`
+2. Copy `.env.example` to `.env` and fill it.
+3. `bun run dev` serves the API on http://localhost:3000 (GraphQL at `POST /graphql`).
+
+Built on the Polyforms stack (`stack/VERSION`).

package/templates/base/biome.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.15/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": [
+      "**",
+      "!shared",
+      "!site",
+      "!stack",
+      "!stack.config.json",
+      "!server/system/changelog-content.ts",
+      "!ios/**/Assets.xcassets",
+      "!ios/**/*.xcstrings"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "correctness": {
+        "noUnusedImports": "error",
+        "noUnusedVariables": "error"
+      },
+      "style": {
+        "noNamespace": "error"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "asNeeded",
+      "trailingCommas": "all"
+    }
+  }
+}

package/templates/base/bunfig.toml

@@ -0,0 +1,2 @@
+[install]
+exact = true

package/templates/base/docs/adr/0001-built-on-the-polyforms-stack.md

@@ -0,0 +1,21 @@
+# 0001. Built on the Polyforms stack
+
+Date: {{TODAY}}
+
+## Context
+
+Every Polyforms app shares one way of being built: a Bun and Nitro backend on Firebase,
+GraphQL through Pothos, Terraform, one CI workflow per concern, Sentry, scheduled routines,
+and for apps with a phone client, SwiftUI with the stack's conventions.
+
+## Decision
+
+This project consumes the `@moifort/stack` package. Its rules are rendered into `stack/`
+and imported by `CLAUDE.md`; its templates seeded the repository; a version bump arrives as
+a Renovate pull request and is applied by the upgrade routine.
+
+## Consequences
+
+A rule is never changed here: a correction that holds for every project goes into the
+package and comes back as a version. What is specific to this project is written in
+`CLAUDE.md`, `project-context.md` and the ADRs that follow this one.

package/templates/base/docs/data-recovery.md

@@ -0,0 +1,116 @@
+# Data recovery — Firestore protections and runbook
+
+What protects production data, and what to do when it is lost. Read this before touching
+anything: a hurried restore over live writes does more damage than the incident.
+
+## What is in place
+
+Both settings live on `google_firestore_database.default` in `infra/firebase.tf`, applied by
+the Deploy workflow (since 2026-10-19, commit 5dc4f24).
+
+| Protection | Covers | Retention |
+|---|---|---|
+| Delete protection (`DELETE_PROTECTION_ENABLED`) | Deleting the `(default)` database from the console, `gcloud` or a script | — |
+| Point-in-time recovery (`POINT_IN_TIME_RECOVERY_ENABLED`) | Documents deleted or overwritten by a bug, a migration, a bad command | 7 days, to the minute |
+| Terraform `deletion_policy = ABANDON` (provider default) | `terraform destroy` leaves the database alone | — |
+| GCP project soft delete (platform default) | Deleting the whole project | 30 days |
+
+**Not in place, on purpose:** scheduled Firestore backups, an export to a bucket in another
+project, a lien on the project. So there is **no copy of the data outside the database
+itself**: a deleted database or a project gone past 30 days is unrecoverable.
+
+Check the live state (read-only, works with the observer account):
+
+```bash
+CLOUDSDK_CONFIG=$HOME/.config/{{APP_SLUG}}-observer/gcloud gcloud firestore databases describe --database='(default)' --project={{APP_SLUG}}-polyforms --format='value(deleteProtectionState,pointInTimeRecoveryEnablement,earliestVersionTime,versionRetentionPeriod)'
+```
+
+`earliestVersionTime` is the oldest instant that can still be recovered.
+
+## Before any recovery
+
+1. **Stop the bleeding first.** If a bug or a migration is still writing, revert and deploy
+   the fix (or pause the scheduler job) before restoring, or the restore is overwritten.
+2. **Pin the instant.** Find the last whole minute *before* the damage, from Cloud Logging,
+   the `migration-meta` collection or the deploy time. PITR snapshot times must be a whole
+   minute (`…:05:00Z`) and later than `earliestVersionTime`. The clock runs: past seven days
+   the version is gone, so do this the day the damage is seen.
+3. **Scope the damage.** Which collections, which `userId`s, which documents. Collections are
+   flat with a `userId` field, so a reader's library is one query.
+4. Recovery writes production: it needs the user's own `gcloud` login (the observer account is
+   read-only) and **the user's go-ahead**. It is never done silently.
+
+## Case 1 — documents deleted or overwritten, less than 7 days ago
+
+Never restore the whole database over `(default)`: it would erase every legitimate write made
+since. Recover only what was damaged.
+
+**A handful of documents** — read the old version straight from `(default)` with a read-only
+transaction at a past `readTime`, then write it back:
+
+```ts
+import { Timestamp } from 'firebase-admin/firestore'
+
+const readTime = Timestamp.fromDate(new Date('2026-10-19T14:05:00Z'))
+const before = await db.runTransaction((tx) => tx.get(db.collection('books').doc(bookId)), {
+  readOnly: true,
+  readTime,
+})
+if (before.exists) await db.collection('books').doc(bookId).set(before.data()!)
+```
+
+A query works the same way (`tx.get(db.collection('books').where('userId', '==', userId))`).
+
+**Many documents or whole collections** — clone the database at that instant into a
+separate database, copy back what was damaged, then delete the clone:
+
+```bash
+gcloud firestore databases clone --project={{APP_SLUG}}-polyforms --source-database='projects/{{APP_SLUG}}-polyforms/databases/(default)' --snapshot-time=2026-10-19T14:05:00Z --destination-database=recovered
+```
+
+Then a one-off script (in `scripts/`, run locally with the user's credentials) opens both
+databases — `getFirestore(app)` and `getFirestore(app, 'recovered')` — and copies back the
+damaged documents, in batches of at most 500 writes. A document deleted by the incident
+exists in `recovered` and not in `(default)`; one created since the incident exists only in
+`(default)` and must be left alone.
+
+Delete the clone when done, it bills storage while it exists:
+
+```bash
+gcloud firestore databases delete --database=recovered --project={{APP_SLUG}}-polyforms
+```
+
+If `clone` is refused (flag names change; check `gcloud firestore databases clone --help`),
+the fallback is an export at the same instant into a bucket, then an import into a new
+database: `gcloud firestore export gs://<bucket>/recovery --snapshot-time=… --database='(default)'`,
+create `recovered`, `gcloud firestore import gs://<bucket>/recovery --database=recovered`.
+
+## Case 2 — the `(default)` database deleted
+
+Delete protection refuses this; someone has to turn it off first
+(`gcloud firestore databases update --database='(default)' --no-delete-protection`, or the
+console). If it happened anyway, the PITR history went with the database and **there is no
+backup to restore from**. What is left is to recreate the database by applying Terraform
+(the Deploy workflow) and to tell readers. Shared series catalogues rebuild themselves from
+new scans; private books do not.
+
+## Case 3 — the whole GCP project deleted
+
+A deleted project stays in "pending deletion" for 30 days: everything is shut down, nothing is
+erased. Restore it, with the user's own login (owner):
+
+```bash
+gcloud projects undelete {{APP_SLUG}}-polyforms
+```
+
+Then check billing is still linked (the prepaid Gemini key and Cloud Run need it), that Cloud
+Run serves again, and that Firestore answers. APIs and services come back with the project;
+re-run the Deploy workflow if anything is missing. Past 30 days the project, its data and its
+ID are gone for good.
+
+## If more protection is ever wanted
+
+From cheapest to strongest: a lien on the project (free, blocks project deletion until
+removed); a `google_firestore_backup_schedule` (daily kept 7 days, weekly kept 14 weeks,
+billed as backup storage, restore into a new database); a scheduled export to a bucket in
+another project with a retention lock — the only copy that survives losing the project.

package/templates/base/docs/ideas.md

@@ -0,0 +1,4 @@
+# Ideas
+
+One line per idea, dated, newest first. Nothing here is decided; an idea that becomes a
+feature leaves this list for a design or an ADR.

package/templates/base/project-context.md

@@ -0,0 +1,43 @@
+# Project context
+
+The facts of this project. Nothing here is a rule (rules live in the stack) and nothing
+here should be copied into another project.
+
+## Environments
+
+| Environment | GCP project | Notes |
+|---|---|---|
+| Production | `{{APP_SLUG}}-polyforms` | |
+| Staging | `{{APP_SLUG}}-staging-polyforms` | Deployed from pull requests labelled `staging` |
+
+## Accounts and consoles
+
+Which account opens which console, and the access trick if there is one.
+
+## Analytics and monitoring
+
+Sentry projects `{{APP_SLUG}}-node` and `{{APP_SLUG}}-ios` (org `polyforms`). GA4 property, dashboards.
+
+## Test devices
+
+Name, identifier, signing team, trust state.
+
+## Certificates and keys
+
+| Item | Role | Created | Expires |
+|---|---|---|---|
+| | Signing | | |
+| | App Store Connect API | | |
+
+## Where each secret lives
+
+Every token and the places it is replicated, with the example file beside each ignored one.
+
+## Decisions specific to this project
+
+Structuring choices and their reason, when neither the code nor the history says it. An
+architecture choice gets an ADR in `docs/adr/`.
+
+## Pending work
+
+What is started, what remains to be done by hand, what waits on someone else.

package/templates/base/renovate.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "pinDigests": false,
+  "gitAuthor": "Renovate Bot <{{GITHUB_OWNER}}@users.noreply.github.com>",
+  "labels": ["dependencies"],
+  "packageRules": [
+    {
+      "description": "Automerge non-major updates in a single grouped PR",
+      "matchUpdateTypes": ["minor", "patch", "digest"],
+      "groupName": "non-major dependencies",
+      "commitMessageTopic": "dependencies",
+      "automerge": true,
+      "automergeType": "pr",
+      "automergeStrategy": "squash"
+    },
+    {
+      "description": "Major updates: one pull request each, never automerged; the upgrade routine reads the changelog, applies the code changes, deploys to staging and merges",
+      "matchUpdateTypes": ["major"],
+      "labels": ["dependencies", "major"],
+      "automerge": false
+    },
+    {
+      "description": "The stack package: never automerged; the upgrade routine applies its migrations and merges",
+      "matchPackageNames": ["@moifort/stack"],
+      "labels": ["dependencies", "stack"],
+      "automerge": false
+    }
+  ],
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": ["before 5am on monday"],
+    "automerge": true,
+    "automergeType": "pr",
+    "automergeStrategy": "squash"
+  }
+}

package/templates/ios/.github/workflows/build-ios.yml

@@ -0,0 +1,168 @@
+name: Build
+
+# Runs only for what the app is built from: its sources, the committed schema the
+# Apollo code is regenerated from (so a backend change that breaks an iOS operation
+# still lands here), the two checks the job ends with, and this file. A server-only
+# push no longer pays twenty minutes of macOS runner, nor cancels a running build.
+# No branch protection requires this check, so a run that never starts blocks nothing.
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'ios/**'
+      - 'shared/schema.graphql'
+      - 'scripts/check-strings.ts'
+      - 'scripts/check-ios-components.ts'
+      - '.github/workflows/build-ios.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'ios/**'
+      - 'shared/schema.graphql'
+      - 'scripts/check-strings.ts'
+      - 'scripts/check-ios-components.ts'
+      - '.github/workflows/build-ios.yml'
+  workflow_dispatch:
+
+# A newer push to the same branch, or to the same pull request, makes this run
+# pointless: it is cancelled rather than left to use a runner for nothing. Keyed on
+# the workflow file and the ref, since the three test workflows share one name.
+concurrency:
+  group: ${{ github.workflow_ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Guards the one thing the other three workflows cannot see: whether the app
+  # still compiles. The generated Apollo code is regenerated here from the
+  # committed schema, so a backend change that the iOS operations no longer match
+  # fails here rather than at release time. Builds without signing or uploading.
+  # macos-26 is a standard runner, so this costs nothing on a public repository.
+  ios:
+    name: 📱 iOS
+    runs-on: macos-26
+    # The simulator's first boot on a fresh runner takes ten minutes and more,
+    # on top of a cold build: 30 cut a run short on 2026-10-16.
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Select the latest final Xcode
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+
+      # Booted first, so its ten-minute first start runs alongside the Apollo
+      # generation and the build rather than after them, where it sat as eleven
+      # silent minutes before the tests on 2026-10-16.
+      #
+      # The iPhone 17 precisely: the scheme's test pre-action boots "iPhone 17" to
+      # add the UI tests' photo. On any other device that pre-action cold-booted a
+      # second simulator inside the test step, six to fifteen silent minutes before
+      # the first test on 2026-10-18–20. simctl resolves the name to the device
+      # already booted, so here it finds this one ready and does nothing.
+      - name: Boot the simulator the tests run on
+        run: |
+          set -euo pipefail
+          devices=$(xcrun simctl list devices available)
+          line=$(grep -m1 -E '^ +iPhone 17 \(' <<< "$devices" \
+            || grep -m1 -E '^ +iPhone' <<< "$devices")
+          udid=$(grep -oE '[0-9A-F]{8}(-[0-9A-F]{4}){3}-[0-9A-F]{12}' <<< "$line")
+          echo "Testing on $line"
+          echo "SIMULATOR_UDID=$udid" >> "$GITHUB_ENV"
+          xcrun simctl boot "$udid"
+
+      - name: Generate the Xcode project
+        run: |
+          brew install xcodegen
+          (cd ios && xcodegen generate)
+
+      - name: Materialize gitignored build files
+        run: |
+          set -euo pipefail
+          printf '%s' "${{ secrets.IOS_GOOGLE_SERVICE_INFO_PLIST }}" \
+            | openssl base64 -d -A > ios/{{APP_NAME}}/GoogleService-Info.plist
+          cp ios/{{APP_NAME}}/Shared/Secrets.swift.example ios/{{APP_NAME}}/Shared/Secrets.swift
+
+      # Fetching the packages took four of the Apollo step's minutes on 2026-10-20.
+      # Package.resolved is not committed, so the cache cannot be keyed on it before
+      # resolving: the latest cache is restored, resolution then fetches only what
+      # moved, and a new cache is saved only when the resolved versions changed.
+      - name: Restore the Swift packages
+        id: spm-restore
+        uses: actions/cache/restore@v6
+        with:
+          path: ${{ runner.temp }}/SourcePackages
+          key: spm-${{ runner.os }}-${{ github.sha }}
+          restore-keys: spm-${{ runner.os }}-
+
+      - name: Generate Apollo GraphQL code (gitignored, regenerated per build)
+        run: |
+          set -euo pipefail
+          # Resolve SPM so the apollo-ios checkout (and its bundled CLI) exists.
+          xcodebuild -resolvePackageDependencies \
+            -project ios/{{APP_NAME}}.xcodeproj -scheme {{APP_NAME}} \
+            -derivedDataPath "$RUNNER_TEMP/DerivedData" \
+            -clonedSourcePackagesDirPath "$RUNNER_TEMP/SourcePackages"
+          resolved=ios/{{APP_NAME}}.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
+          if [ -f "$resolved" ]; then
+            echo "SPM_CACHE_KEY=spm-${RUNNER_OS}-$(shasum -a 256 "$resolved" | cut -c1-16)" \
+              >> "$GITHUB_ENV"
+          fi
+          # Apollo 2.x ships the CLI as a tarball inside the checkout — extract it.
+          CLI_DIR="$RUNNER_TEMP/SourcePackages/checkouts/apollo-ios/CLI"
+          tar -xzf "$CLI_DIR/apollo-ios-cli.tar.gz" -C "$CLI_DIR"
+          chmod +x "$CLI_DIR/apollo-ios-cli"
+          (cd ios && "$CLI_DIR/apollo-ios-cli" generate)
+
+      - name: Save the Swift packages
+        if: env.SPM_CACHE_KEY != '' && steps.spm-restore.outputs.cache-matched-key != env.SPM_CACHE_KEY
+        uses: actions/cache/save@v6
+        with:
+          path: ${{ runner.temp }}/SourcePackages
+          key: ${{ env.SPM_CACHE_KEY }}
+
+      - name: Build the app and its tests
+        # Compiled once, for the simulator the tests then run on: no signing
+        # identity needed (release-ios.yml owns those).
+        run: |
+          set -euo pipefail
+          xcodebuild -project ios/{{APP_NAME}}.xcodeproj -scheme {{APP_NAME}} \
+            -destination "id=$SIMULATOR_UDID" \
+            -derivedDataPath "$RUNNER_TEMP/DerivedData" \
+            -clonedSourcePackagesDirPath "$RUNNER_TEMP/SourcePackages" \
+            CODE_SIGNING_ALLOWED=NO \
+            build-for-testing
+
+      - name: Unit tests
+        # The ViewModels driven over inline clients ({{APP_NAME}}Tests): no network, no
+        # Firebase, only a simulator to host the bundle. Runs what the step above
+        # built, without compiling anything again.
+        run: |
+          set -euo pipefail
+          # Says how long the boot still had to go, so a slow one shows here.
+          start=$SECONDS
+          xcrun simctl bootstatus "$SIMULATOR_UDID" -b
+          echo "Simulator ready after a further $((SECONDS - start)) s"
+          xcodebuild -project ios/{{APP_NAME}}.xcodeproj -scheme {{APP_NAME}} \
+            -destination "id=$SIMULATOR_UDID" \
+            -derivedDataPath "$RUNNER_TEMP/DerivedData" \
+            -clonedSourcePackagesDirPath "$RUNNER_TEMP/SourcePackages" \
+            -only-testing:{{APP_NAME}}Tests \
+            CODE_SIGNING_ALLOWED=NO \
+            test-without-building
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Every string has its French and its English
+        # Reads the strings the build just extracted: one added to the code and
+        # left out of the catalogue fails here, as does one with no English.
+        run: bun scripts/check-strings.ts "$RUNNER_TEMP/DerivedData"
+
+      - name: Components stay pure and previewed
+        # Stack rule 10-ios.md: nothing under components/ or Shared/Components
+        # calls the server, reads a singleton or holds a ViewModel,
+        # and every view there has a #Preview.
+        run: bun scripts/check-ios-components.ts