@moifort/stack 0.0.0-stage → 0.1.0

package/templates/ios/ios/{{APP_NAME}}/Shared/SnapshotCache.swift

@@ -0,0 +1,78 @@
+import Foundation
+
+/// What a screen showed last time, kept on disk so a relaunch opens on it
+/// instead of on a loader. The screens it is used for change
+/// slowly: the snapshot written last time is almost always what the server
+/// is about to send, and a screen one session old is worth far more than an
+/// empty one. The snapshot draws first, the server's answer replaces it a
+/// moment later, under a spinner at the top of the screen.
+///
+/// Every snapshot lives in one folder of the caches directory, which the
+/// system may reclaim at will — that is what a cache is for, and losing it
+/// costs one loader. The screen decides what goes in: only what it *opens*
+/// on, never a filtered state the user asked for.
+struct SnapshotCache<Value: Codable & Sendable>: Sendable {
+    /// The file's name, one per screen.
+    private let name: String
+    /// Bump whenever `Value` changes shape. An older file is then ignored
+    /// instead of decoded into something that no longer means the same thing.
+    private let version: Int
+
+    init(_ name: String, version: Int) {
+        self.name = name
+        self.version = version
+    }
+
+    private var file: URL {
+        SnapshotCaches.folder.appending(path: "\(name).json")
+    }
+
+    /// The last snapshot, or `nil` when there is no usable file: a first
+    /// launch, a cache the system reclaimed, or a file written by an older shape.
+    func read() -> Value? {
+        #if DEBUG
+        // The captures draw the showcase alone, never a session left on the
+        // simulator.
+        if Showcase.isOn { return nil }
+        #endif
+        guard let data = try? Data(contentsOf: file),
+              let stored = try? JSONDecoder().decode(Stored.self, from: data),
+              stored.version == version
+        else { return nil }
+        return stored.value
+    }
+
+    /// Overwrite the snapshot with what is on screen. A failure is swallowed
+    /// on purpose: a snapshot that cannot be written costs a loader on the
+    /// next launch, nothing more.
+    func write(_ value: Value) {
+        #if DEBUG
+        if Showcase.isOn { return }
+        #endif
+        guard let data = try? JSONEncoder().encode(Stored(version: version, value: value))
+        else { return }
+        try? FileManager.default.createDirectory(
+            at: SnapshotCaches.folder, withIntermediateDirectories: true
+        )
+        try? data.write(to: file, options: .atomic)
+    }
+
+    private struct Stored: Codable {
+        let version: Int
+        let value: Value
+    }
+}
+
+/// Forget every screen's snapshot. Called when the session ends: whoever opens
+/// the app next must not read the previous account's data before the
+/// server has said a word.
+enum SnapshotCaches {
+    /// The one folder every snapshot lives in, so the session's end is a single delete.
+    static var folder: URL {
+        URL.cachesDirectory.appending(path: "snapshots", directoryHint: .isDirectory)
+    }
+
+    static func clear() {
+        try? FileManager.default.removeItem(at: folder)
+    }
+}

package/templates/ios/ios/{{APP_NAME}}/Shared/UITestEnvironment.swift

@@ -0,0 +1,70 @@
+#if DEBUG
+import FirebaseAuth
+import Foundation
+
+/// Signs the app in without Sign in with Apple, so the UI tests can reach the
+/// screens behind the login wall. Apple's sheet is a system process XCUITest
+/// cannot drive, so an end-to-end run points Firebase Auth at the local
+/// emulator instead and creates its own account there.
+///
+/// Debug-only by construction: the whole file is compiled out of the Release
+/// configuration the App Store archive is built with.
+///
+/// Driven by two launch arguments, both required for anything to happen:
+///   -uiTestAuthEmulator 127.0.0.1:9099
+///   -uiTestAccount      e2e-<uuid>@{{APP_SLUG}}.test
+///
+/// The server URL rides the plain `-serverURL` argument, which `APIClient`
+/// already reads through `UserDefaults`.
+enum UITestEnvironment {
+    /// Any password satisfies the emulator; it verifies nothing.
+    private static let password = "e2e-password"
+
+    /// Called from `App.init()` right after `FirebaseApp.configure()`,
+    /// before anything touches `Auth.auth()`.
+    static func bootstrapIfNeeded() {
+        guard
+            let emulator = value(for: "-uiTestAuthEmulator"),
+            let email = value(for: "-uiTestAccount"),
+            let (host, port) = split(emulator)
+        else { return }
+
+        Auth.auth().useEmulator(withHost: host, port: port)
+        // A previous run leaves its session in the simulator's keychain. Signing
+        // out first means the app never shows the old account's library while the
+        // new sign-in is still in flight.
+        try? Auth.auth().signOut()
+
+        Task {
+            do {
+                // The emulator starts empty on every run, so the account is
+                // created here. Falling back to a sign-in covers the app being
+                // re-launched inside one test, where the account already exists.
+                do {
+                    _ = try await Auth.auth().createUser(withEmail: email, password: password)
+                } catch {
+                    _ = try await Auth.auth().signIn(withEmail: email, password: password)
+                }
+            } catch {
+                // No XCTFail available here: the test fails on its own when the
+                // login screen never goes away, and this line says why.
+                print("[UITestEnvironment] sign-in failed for \(email): \(error)")
+            }
+        }
+    }
+
+    /// Reads the value following `name` in the launch arguments.
+    private static func value(for name: String) -> String? {
+        let arguments = ProcessInfo.processInfo.arguments
+        guard let index = arguments.firstIndex(of: name), index + 1 < arguments.count
+        else { return nil }
+        return arguments[index + 1]
+    }
+
+    private static func split(_ hostPort: String) -> (String, Int)? {
+        let parts = hostPort.split(separator: ":")
+        guard parts.count == 2, let port = Int(parts[1]) else { return nil }
+        return (String(parts[0]), port)
+    }
+}
+#endif

package/templates/ios/ios/{{APP_NAME}}/{{APP_NAME}}.entitlements

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.developer.applesignin</key>
+	<array>
+		<string>Default</string>
+	</array>
+</dict>
+</plist>

package/templates/ios/ios/{{APP_NAME}}Tests/Onboarding/OnboardingGateTests.swift

@@ -0,0 +1,38 @@
+import Foundation
+import Testing
+@testable import {{APP_NAME}}
+
+@MainActor
+struct OnboardingGateTests {
+    @Test func aFreshAccountIsSentToOnboarding() async {
+        var client = OnboardingClient.preview
+        client.launch = { LaunchState(firstName: nil, onboardingCompleted: false) }
+        let gate = OnboardingGate(client: client)
+
+        await gate.refresh()
+
+        #expect(gate.state == .required)
+    }
+
+    @Test func anOnboardedAccountOpensTheAppWithItsName() async {
+        let gate = OnboardingGate(client: .preview)
+
+        await gate.refresh()
+
+        #expect(gate.state == .ready)
+        #expect(gate.firstName == "Ada")
+    }
+
+    @Test func aFailedLaunchIsSaidAndCanBeRetried() async {
+        var client = OnboardingClient.preview
+        client.launch = { throw Boom() }
+        let gate = OnboardingGate(client: client)
+
+        await gate.refresh()
+
+        guard case .failed = gate.state else {
+            Issue.record("expected a failure, got \(gate.state)")
+            return
+        }
+    }
+}

package/templates/ios/ios/{{APP_NAME}}Tests/Settings/SettingsViewModelTests.swift

@@ -0,0 +1,63 @@
+import Foundation
+import Testing
+@testable import {{APP_NAME}}
+
+@MainActor
+struct ProfileSettingsViewModelTests {
+    @Test func deletionEndsTheSession() async {
+        let ended = Flag()
+        let viewModel = ProfileSettingsViewModel(client: .preview)
+
+        await viewModel.deleteAccount { ended.isOn = true }
+
+        #expect(ended.isOn)
+        #expect(viewModel.errorMessage == nil)
+    }
+
+    @Test func lostAnswerOverAGoneAccountSaysNothing() async {
+        var client = SettingsClient.preview
+        client.deleteAccount = { throw Boom() }
+        client.accountIsGone = { true }
+        let viewModel = ProfileSettingsViewModel(client: client)
+
+        await viewModel.deleteAccount {}
+
+        #expect(viewModel.errorMessage == nil)
+    }
+
+    @Test func refusedDeletionSaysSoAndStops() async {
+        let ended = Flag()
+        var client = SettingsClient.preview
+        client.deleteAccount = { throw Boom() }
+        let viewModel = ProfileSettingsViewModel(client: client)
+
+        await viewModel.deleteAccount { ended.isOn = true }
+
+        #expect(ended.isOn == false)
+        #expect(viewModel.errorMessage != nil)
+        #expect(viewModel.isDeletingAccount == false)
+    }
+}
+
+@MainActor
+struct ChangelogViewModelTests {
+    @Test func loadShowsTheEntries() async {
+        let viewModel = ChangelogViewModel(client: .preview)
+
+        await viewModel.load()
+
+        #expect(viewModel.entries.map(\.version) == ["1.1", "1.0"])
+        #expect(viewModel.isLoading == false)
+    }
+
+    @Test func failureIsSaid() async {
+        var client = SettingsClient.preview
+        client.changelog = { throw Boom() }
+        let viewModel = ChangelogViewModel(client: client)
+
+        await viewModel.load()
+
+        #expect(viewModel.entries.isEmpty)
+        #expect(viewModel.errorMessage != nil)
+    }
+}

package/templates/ios/ios/{{APP_NAME}}Tests/Support/TestDoubles.swift

@@ -0,0 +1,35 @@
+import Foundation
+
+/// An error no client really throws, for a call that fails.
+struct Boom: Error {}
+
+/// A switch a test flips between two calls of the same client.
+final class Flag: @unchecked Sendable {
+    private let lock = NSLock()
+    private var value = false
+
+    var isOn: Bool {
+        get { lock.withLock { value } }
+        set { lock.withLock { value = newValue } }
+    }
+}
+
+/// What a client was asked, in order.
+final class Calls: @unchecked Sendable {
+    private let lock = NSLock()
+    private var items: [String] = []
+
+    func record(_ call: String) { lock.withLock { items.append(call) } }
+    var all: [String] { lock.withLock { items } }
+}
+
+/// Waits until `condition` holds, or `timeout` runs out: a state a timer or a
+/// debounce brings about is checked once it is there, not after a fixed sleep a
+/// slow CI machine overshoots.
+@MainActor
+func eventually(within timeout: Duration = .seconds(5), _ condition: () -> Bool) async {
+    let deadline = ContinuousClock.now + timeout
+    while !condition(), ContinuousClock.now < deadline {
+        try? await Task.sleep(for: .milliseconds(10))
+    }
+}

package/templates/ios/package.merge.json

@@ -0,0 +1,10 @@
+{
+  "scripts": {
+    "ios:project": "cd ios && xcodegen generate",
+    "ios:codegen": "bun scripts/apollo-codegen.ts",
+    "ios:build": "bun run ios:project && bun run ios:codegen && DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -project ios/{{APP_NAME}}.xcodeproj -scheme {{APP_NAME}} -destination 'generic/platform=iOS Simulator' -derivedDataPath build/derived SWIFT_ENABLE_EXPLICIT_MODULES=NO build",
+    "ios:test": "DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -project ios/{{APP_NAME}}.xcodeproj -scheme {{APP_NAME}} -destination \"platform=iOS Simulator,name=${IOS_SIMULATOR:-iPhone 17}\" -derivedDataPath build/derived SWIFT_ENABLE_EXPLICIT_MODULES=NO test",
+    "ios:strings": "DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer bun scripts/check-strings.ts build/derived",
+    "ios:components": "bun scripts/check-ios-components.ts"
+  }
+}

package/templates/ios/scripts/apollo-codegen.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+/**
+ * Generates the app's GraphQL types from the committed schema, with the CLI the
+ * resolved apollo-ios package ships (never a global install: its version must
+ * match the library's). Resolves the packages first when they are not there.
+ *
+ *   bun scripts/apollo-codegen.ts
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { $ } from 'bun'
+
+const root = join(import.meta.dir, '..')
+const derived = join(root, 'build/derived')
+const cliDir = join(derived, 'SourcePackages/checkouts/apollo-ios/CLI')
+const env = { ...process.env, DEVELOPER_DIR: '/Applications/Xcode.app/Contents/Developer' }
+
+if (!existsSync(join(cliDir, 'apollo-ios-cli.tar.gz'))) {
+  await $`xcodebuild -resolvePackageDependencies -project ios/{{APP_NAME}}.xcodeproj -scheme {{APP_NAME}} -derivedDataPath ${derived}`
+    .cwd(root)
+    .env(env)
+    .quiet()
+}
+if (!existsSync(join(cliDir, 'apollo-ios-cli'))) {
+  await $`tar -xzf apollo-ios-cli.tar.gz`.cwd(cliDir)
+}
+await $`${join(cliDir, 'apollo-ios-cli')} generate`.cwd(join(root, 'ios')).env(env)
+// A fresh checkout sometimes skips the namespace file on the first run.
+const namespace = join(root, 'ios/{{APP_NAME}}/Generated/GraphQL/{{APP_NAME}}GraphQL.graphql.swift')
+if (!existsSync(namespace)) await $`${join(cliDir, 'apollo-ios-cli')} generate`.cwd(join(root, 'ios')).env(env)
+console.log('GraphQL types generated in ios/{{APP_NAME}}/Generated/GraphQL')

package/templates/ios/scripts/check-ios-components.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+/**
+ * Keeps the iOS components pure, as the stack rule 10-ios.md asks: everything under a
+ * `components/` folder, and under `Shared/Components`, draws
+ * what it is given and asks nothing of the server.
+ *
+ * A component fails the run when it
+ * - calls an API enum (`ItemAPI.add`…) or a client's `.live`;
+ * - reads a singleton (`Something.shared`…), the system's own
+ *   (`UIApplication.shared`, `UIPasteboard.general`) aside;
+ * - listens to `NotificationCenter`;
+ * - holds a ViewModel;
+ * - declares a view and no `#Preview`.
+ *
+ * Connected code — Screens, ViewModels, clients — lives beside the
+ * `components/` folder and is not checked.
+ *
+ *   bun scripts/check-ios-components.ts
+ */
+import { readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { Glob } from 'bun'
+
+const root = join(import.meta.dir, '../ios/{{APP_NAME}}')
+
+const RULES: { pattern: RegExp; says: string }[] = [
+  {
+    pattern: /\b[A-Z][A-Za-z]*API\.[a-z]/,
+    says: 'calls an API: hand it the value or an action instead',
+  },
+  { pattern: /\b[A-Z][A-Za-z]*Client\.live\b/, says: 'reaches a live client: the Screen owns it' },
+  {
+    pattern: /\b(?!UIApplication\b|UIPasteboard\b)[A-Z][A-Za-z]*\.shared\b/,
+    says: 'reads a singleton: pass the value down, or inject it through @Environment',
+  },
+  { pattern: /\bNotificationCenter\b/, says: 'listens to change notices: only Screens do' },
+  {
+    pattern: /\b[A-Z][A-Za-z]*ViewModel\b/,
+    says: 'holds a ViewModel: take its values and actions',
+  },
+]
+
+const files = [
+  ...new Glob('Features/*/components/**/*.swift').scanSync(root),
+  ...new Glob('Shared/Components/**/*.swift').scanSync(root),
+].sort()
+
+const failures: string[] = []
+for (const file of files) {
+  const source = await readFile(join(root, file), 'utf8')
+  // Comments say what the code once did; only the code is checked.
+  const code = source
+    .split('\n')
+    .map((line) => line.replace(/\/\/.*$/, ''))
+    .join('\n')
+  code.split('\n').forEach((line, index) => {
+    for (const rule of RULES) {
+      if (rule.pattern.test(line)) failures.push(`${file}:${index + 1}: ${rule.says}`)
+    }
+  })
+  const declaresView = /\bstruct\s+\w+(<[^>]*>)?\s*:\s*[^{]*\bView\b/.test(code)
+  if (declaresView && !code.includes('#Preview')) {
+    failures.push(`${file}: declares a view and no #Preview`)
+  }
+}
+
+if (failures.length > 0) {
+  console.error(`${failures.length} component rule(s) broken (the stack rule 10-ios.md):`)
+  for (const failure of failures) console.error(`  ${relative(process.cwd(), join(root, failure))}`)
+  process.exit(1)
+}
+console.log(`${files.length} components, all pure and previewed.`)

package/templates/ios/scripts/check-strings.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env bun
+/**
+ * Keeps the iOS string catalogues whole: every string the app shows has its
+ * French and its English.
+ *
+ * The strings are written in French in the Swift code, and the catalogues say
+ * so (`sourceLanguage: fr`). English is the app's development language all the
+ * same, so that a user whose iPhone speaks neither gets English, as the
+ * server answers them. The price of that: a string missing from the French
+ * table falls back to the English one. So each string carries an explicit
+ * French entry, copied from its key, which this script writes; a string with
+ * no English is reported, and fails the run.
+ *
+ * Reads what the compiler extracted from the last build (`.stringsdata`, under
+ * the derived data given), so a string added to the code and absent from the
+ * catalogue is caught too.
+ *
+ *   bun scripts/check-strings.ts <derived-data>           # check, as CI does
+ *   bun scripts/check-strings.ts <derived-data> --write   # sync the catalogues in place
+ */
+import { copyFile, mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { $, Glob } from 'bun'
+
+const ios = join(import.meta.dir, '../ios')
+
+/** Each catalogue, and the build products its strings come from. */
+const CATALOGUES = [
+  { path: join(ios, '{{APP_NAME}}/Localizable.xcstrings'), product: '{{APP_NAME}}.build' },
+]
+
+type Unit = { stringUnit?: { state: string; value: string }; variations?: unknown }
+type Entry = {
+  extractionState?: string
+  shouldTranslate?: boolean
+  localizations?: Record<string, Unit>
+}
+type Catalogue = { sourceLanguage: string; strings: Record<string, Entry>; version: string }
+
+const [derivedData, ...flags] = process.argv.slice(2)
+if (!derivedData) throw new Error('Usage: bun scripts/check-strings.ts <derived-data> [--write]')
+const write = flags.includes('--write')
+
+/** Xcode's own layout: two spaces, ` : ` between a key and its value. */
+const serialize = (catalogue: Catalogue) =>
+  `${JSON.stringify(catalogue, Object.keys(flatten(catalogue)).sort(), 2).replaceAll('": ', '" : ')}\n`
+
+/** Every key at any depth, for `JSON.stringify` to write them sorted. */
+function flatten(value: unknown, keys: Record<string, true> = {}): Record<string, true> {
+  if (value && typeof value === 'object')
+    for (const [key, inner] of Object.entries(value)) {
+      keys[key] = true
+      flatten(inner, keys)
+    }
+  return keys
+}
+
+const work = await mkdtemp(join(tmpdir(), '{{APP_SLUG}}-strings-'))
+const missing: string[] = []
+
+for (const { path, product } of CATALOGUES) {
+  // Under the configuration's folder: the project's own folder is named
+  // {{APP_NAME}}.build too, and holds the extension's strings.
+  const extracted = await Array.fromAsync(
+    new Glob(`**/*-iphone*/${product}/**/*.stringsdata`).scan({ cwd: derivedData, absolute: true }),
+  )
+  if (extracted.length === 0)
+    throw new Error(`No ${product} strings under ${derivedData}: build the app first`)
+
+  // The sync runs on a copy: a check must not touch the working tree. The copy
+  // keeps the catalogue's name, which is the table its strings are filed under.
+  const synced = join(work, basename(product, '.build'), basename(path))
+  await mkdir(dirname(synced), { recursive: true })
+  await copyFile(path, synced)
+  await $`xcrun xcstringstool sync ${synced} --stringsdata ${extracted}`.quiet()
+
+  const catalogue: Catalogue = JSON.parse(await readFile(synced, 'utf8'))
+  for (const [key, entry] of Object.entries(catalogue.strings)) {
+    if (entry.extractionState === 'stale') {
+      delete catalogue.strings[key]
+      continue
+    }
+    entry.localizations ??= {}
+    const localizations = entry.localizations
+    localizations.fr ??= { stringUnit: { state: 'translated', value: key } }
+    if (!localizations.en) missing.push(`${basename(product, '.build')}: ${JSON.stringify(key)}`)
+  }
+
+  const before = await readFile(path, 'utf8')
+  const after = serialize(catalogue)
+  if (before === after) continue
+  if (write) {
+    await writeFile(path, after)
+    console.log(`${basename(product, '.build')}: catalogue synced`)
+  } else missing.push(`${basename(product, '.build')}: catalogue out of date, run with --write`)
+}
+
+if (missing.length > 0) {
+  console.error(`Strings without their English:\n${missing.map((line) => `  ${line}`).join('\n')}`)
+  process.exit(1)
+}
+console.log('Every string has its French and its English.')

package/templates/ios/scripts/install-device.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+#
+# Build, install and launch the app on the physical iPhone named in
+# project-context.md, whose CoreDevice id is IOS_DEVICE_ID (in .env or the shell).
+# On request only: see the stack rule 10-ios.md, "Physical device".
+set -euo pipefail
+cd "$(dirname "$0")/.."
+[ -f .env ] && set -a && . ./.env && set +a
+: "${IOS_DEVICE_ID:?IOS_DEVICE_ID is unset: the CoreDevice id from xcrun devicectl list devices}"
+export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
+
+bun run ios:project >/dev/null
+bun run ios:codegen
+
+echo "==> Building for device ${IOS_DEVICE_ID}"
+# -allowProvisioningUpdates lets automatic signing register the device and mint the
+# profile on first run.
+xcodebuild -project ios/{{APP_NAME}}.xcodeproj -scheme {{APP_NAME}} \
+  -destination "platform=iOS,id=${IOS_DEVICE_ID}" \
+  -derivedDataPath build/device \
+  -allowProvisioningUpdates \
+  build
+
+APP="build/device/Build/Products/Debug-iphoneos/{{APP_NAME}}.app"
+echo "==> Installing ${APP}"
+xcrun devicectl device install app "$APP" --device "$IOS_DEVICE_ID"
+BUNDLE_ID=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$APP/Info.plist")
+echo "==> Launching ${BUNDLE_ID}"
+xcrun devicectl device process launch --device "$IOS_DEVICE_ID" "$BUNDLE_ID"