create-apexjs 0.6.6 → 0.6.8

package/templates/mobile/ios/Info.plist

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Info.plist for the Apex iOS shell.
+
+  Mirrors AndroidManifest.xml: a launcher app with a native launch screen and NO network
+  entitlement required (the backend runs on-device, offline). The animated pages/splash.alpine
+  route takes over after this static launch screen — the two-stage splash handoff.
+
+  Most $(…) values are Xcode build-setting placeholders; set them in the target's General tab.
+-->
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleDisplayName</key>
+  <string>Apex</string>
+  <key>CFBundleExecutable</key>
+  <string>$(EXECUTABLE_NAME)</string>
+  <key>CFBundleIdentifier</key>
+  <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>$(PRODUCT_NAME)</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>LSRequiresIPhoneOS</key>
+  <true/>
+
+  <!-- Native cold-start launch screen: a solid brand-colour screen shown before any JS runs.
+       Uses the LaunchBackground colour asset (#0b1120) in Assets.xcassets. The animated
+       pages/splash.alpine renders immediately after and dismisses to '/'. -->
+  <key>UILaunchScreen</key>
+  <dict>
+    <key>UIColorName</key>
+    <string>LaunchBackground</string>
+  </dict>
+
+  <key>UISupportedInterfaceOrientations</key>
+  <array>
+    <string>UIInterfaceOrientationPortrait</string>
+    <string>UIInterfaceOrientationLandscapeLeft</string>
+    <string>UIInterfaceOrientationLandscapeRight</string>
+  </array>
+  <key>UISupportedInterfaceOrientations~ipad</key>
+  <array>
+    <string>UIInterfaceOrientationPortrait</string>
+    <string>UIInterfaceOrientationPortraitUpsideDown</string>
+    <string>UIInterfaceOrientationLandscapeLeft</string>
+    <string>UIInterfaceOrientationLandscapeRight</string>
+  </array>
+
+  <!-- Status-bar handled by SwiftUI/WebView; no scene manifest needed for the SwiftUI App
+       lifecycle (@main struct App). -->
+</dict>
+</plist>

package/templates/mobile/ios/README.md

@@ -0,0 +1,153 @@
+# Apex iOS shell
+
+> ⚠️ **UNVERIFIED — needs a Mac + Xcode to compile and run.** These files were written on Linux,
+> mirroring the already-shipped, device-verified **Android** shell (`../android/`). No part of the
+> iOS build has been compiled or run — treat it as a well-formed starting point, not a proven app.
+> See **"For the Mac tester"** at the bottom for exactly what to check first.
+
+A native iOS app that runs your Apex backend **on the device** (offline, no server, no port) and
+renders it in a `WKWebView`. It is the 1:1 counterpart of the Android shell, using the two iOS
+platform capabilities that make it *simpler* than Android:
+
+| Concern | Android | iOS (here) |
+|---|---|---|
+| JS engine | `androidx.javascriptengine` (out-of-process, async boot, **no host callbacks**) | **JavaScriptCore `JSContext`** (in-process, sync boot, **host callbacks + exception handler**) |
+| Request interception | `WebViewClient.shouldInterceptRequest` (**cannot read POST body**) | **`WKURLSchemeHandler`** for `apex://` (**reads `httpBody` directly**) |
+| Body-bearing `fetch()`/POST | needs a **2nd path**: `@JavascriptInterface` bridge + document-start `fetch` patch | **not needed** — one scheme handler covers navigations *and* POST |
+| Cookies (HttpOnly session) | `CookieManager` | small `ApexCookieJar` inside the scheme handler (custom schemes bypass `WKHTTPCookieStore`) |
+| DB persistence | `apex-db.b64` in `filesDir`, atomic rename | `apex-db.b64` in Application Support, `FileManager.replaceItemAt` |
+
+## What's here
+
+```
+ios/
+├─ ApexApp.swift            # @main SwiftUI App: boots engine, builds WKWebView, loads apex://localhost/splash
+├─ ApexEngine.swift         # JSContext wrapper — loads server.mjs + apex-bridge.js, runs __apexHandle
+├─ ApexSchemeHandler.swift  # WKURLSchemeHandler for apex:// → engine (assets from bundle) + cookie jar
+├─ ApexDbStore.swift        # DB snapshot persistence (Application Support, atomic)
+├─ Info.plist               # launch screen + app config (no network entitlement needed — offline)
+└─ Assets.xcassets/
+   ├─ AppIcon.appiconset/   # app icon (already present)
+   └─ LaunchBackground.colorset/  # #0b1120 launch-screen colour
+```
+
+## Architecture (identical contract to Android)
+
+```
+ WKWebView  ── every request ──►  ApexSchemeHandler (apex:// scheme)
+                                     │  /assets/*, /favicon.svg → bundle files
+                                     │  everything else → engine, WITH body + injected Cookie
+                                     ▼
+                              ApexEngine.handle(requestJSON)
+                                     │  globalThis.__apexHandle(json)  (apex-bridge.js)
+                                     │    └─ APEX.run(request) → { status, headers, body }
+                                     ▼
+                              {status,headers,body}  ── served back ──►  WKWebView hydrates
+```
+
+Because interception is a **function call**, there's no listener and no port — nothing for iOS to
+suspend when the app backgrounds. That's the whole point.
+
+## Create the Xcode project & drop these files in
+
+There is no `.xcodeproj` in this folder (it's binary/machine-specific). Create one on the Mac:
+
+1. **Xcode → New → App.** Interface: **SwiftUI**, Language: **Swift**. Product name e.g. `ApexShell`.
+   Set the **Bundle Identifier** and a signing team in *Signing & Capabilities*.
+2. **Delete** the auto-generated `ContentView.swift` and the generated `…App.swift` (this repo's
+   `ApexApp.swift` provides the `@main` App).
+3. **Add these files** to the target (drag into the project navigator, *Copy items if needed* off if
+   you reference them in place): `ApexApp.swift`, `ApexEngine.swift`, `ApexSchemeHandler.swift`,
+   `ApexDbStore.swift`.
+4. **Info.plist / Assets:** either use this folder's `Info.plist` (set *Build Settings → Info.plist
+   File* to point at it) or copy its `UILaunchScreen` + keys into the generated one. Add the
+   `LaunchBackground` colour set (and your `AppIcon`) to the target's asset catalog.
+5. **Framework:** `import JavaScriptCore` — it's a **system framework**, no dependency to add
+   (link it in *Frameworks, Libraries, and Embedded Content* if the linker complains).
+
+## Copy the built bundle + client assets into the app
+
+From your **Apex app root**, build the mobile bundle:
+
+```bash
+apex build --mobile      # → dist/mobile/server.mjs
+apex build               # (or your normal build) → dist/assets/*, dist/favicon.svg
+```
+
+Then add these to the Xcode target so they land in the app bundle **Resources**:
+
+| Source | Add to bundle as | Read by |
+|---|---|---|
+| `dist/mobile/server.mjs` | `server.mjs` (bundle root) | `ApexEngine` → `Bundle.main.url(forResource:"server", withExtension:"mjs")` |
+| `native-shell/apex-bridge.js` | `apex-bridge.js` (bundle root) | `ApexEngine` → `…forResource:"apex-bridge", withExtension:"js"` |
+| `dist/assets/*` | an **`assets/` folder reference** (blue folder) | `ApexSchemeHandler` → `…forResource:base, withExtension:ext, subdirectory:"assets"` |
+| `dist/favicon.svg` | `favicon.svg` (bundle root) | `ApexSchemeHandler` |
+
+> **Important — use a *folder reference* (blue), not a *group* (yellow), for `assets/`.** A folder
+> reference preserves the `assets/` subdirectory so `subdirectory: "assets"` lookups resolve. A
+> group flattens filenames into the bundle root and the `/assets/...` path lookups will 404.
+
+Also copy `native-shell/splash.alpine` into your app's `pages/splash.alpine` (the animated intro the
+shell loads first) and rebuild — see `../NATIVE_SHELL.md`.
+
+## Run
+
+Select an iOS Simulator (or a provisioned device) and **⌘R**. You should see: the native launch
+screen (#0b1120), then the animated `splash.alpine`, then your app — all served by the Apex server
+running inside the app on JavaScriptCore. Turn the network off: it still works.
+
+## On-device drivers
+
+`apex build --mobile` reports routes needing `crypto.subtle` (sessions) or `@libsql/client/web`
+(DB) — same as Android. JavaScriptCore provides a real `crypto`? **Not by default** — JSCore has no
+WebCrypto. The bundle ships a stub so non-session routes boot; for real sessions, expose a native
+WebCrypto shim as a host object on the `JSContext` (the JSContext host-callback capability makes
+this straightforward — add it in `ApexEngine` before evaluating `server.mjs`). For DB, alias
+`@libsql/client` → `@libsql/client/web` (sql.js asm.js) before bundling, as on Android.
+
+## For the Mac tester (check these first — likeliest failure points)
+
+1. **Bundle resources present.** If you see *"Apex engine failed to start"*, `server.mjs` /
+   `apex-bridge.js` aren't in the bundle. Confirm they're in *Build Phases → Copy Bundle Resources*.
+2. **`/assets/*` 404 → white page after splash.** Almost certainly the `assets/` folder was added as
+   a *group* (yellow) not a *folder reference* (blue). Re-add as a blue folder. Verify by loading
+   `apex://localhost/assets/<one-file>.js` and watching the Xcode console.
+3. **⭐ POST body reaches the engine.** This is the one genuinely unproven iOS assumption. The task's
+   premise is that `WKURLSchemeHandler` exposes `httpBody` for custom schemes — but some iOS
+   versions have historically **dropped** the body from custom-scheme requests. **Test a POST**
+   (log in, or add a guestbook entry) and confirm the engine receives a non-empty `body`. If it's
+   empty: fall back to the Android approach — add a `WKScriptMessageHandler` (`configuration.
+   userContentController.add(...)`) plus a document-start `fetch` patch (port `FETCH_PATCH` from
+   `../android/.../MainActivity.kt`) that forwards `fetch()` bodies to the handler. The engine and
+   cookie/DB plumbing here are unchanged either way.
+4. **Promise resolution.** `ApexEngine.handle` resolves the JS promise via `.then(onFulfilled,
+   onRejected)` and assumes JavaScriptCore drains its microtask queue within the same JS turn (true
+   for our fully-synchronous in-memory pipeline). If a request ever hangs, that assumption broke —
+   pump with `JSVirtualMachine`/a run-loop tick, or wrap the handler to resolve on a `Promise`
+   settled callback.
+5. **HttpOnly session cookie** survives a full page navigation and a cold start (login, force-quit,
+   relaunch → still logged in). The jar persists to `UserDefaults`.
+6. **DB snapshot** survives a cold start (create data, force-quit, relaunch → data still there). File
+   is `apex-db.b64` in Application Support.
+
+## Testing without a Mac — CI on the iOS Simulator
+
+No Mac? The `ios-shell` GitHub Actions workflow (`.github/workflows/ios.yml`) builds this shell and
+runs `Tests/ApexEngineTests.swift` on the iOS Simulator on a **free GitHub-hosted macOS runner**.
+Trigger it from the repo's **Actions → ios-shell → Run workflow** (or it runs on pushes touching
+`ios/`). It:
+
+1. builds the packages + the showcase `--mobile` bundle,
+2. stages `server.mjs` / `apex-bridge.js` / `assets/` / `favicon.svg` into `ios/Generated/`,
+3. `xcodegen generate` (from `project.yml` — no committed `.xcodeproj`),
+4. `xcodebuild test` on an iPhone simulator.
+
+`ApexEngineTests` proves the bundle — the shim, SSR + API pipeline, **asm.js SQLite**, sealed-cookie
+auth, and the snapshot persistence seam — actually runs under **JavaScriptCore** (iOS's engine),
+which is the main iOS unknown. It does NOT exercise `WKURLSchemeHandler` (the custom-scheme POST-body
+question in the checklist above) — that still needs a device/UI test on a real Mac + iPhone.
+
+### To run on your actual iPhone
+Open the generated project on a Mac (`brew install xcodegen && cd ios && xcodegen generate && open
+ApexShell.xcodeproj`), copy the four `Generated/` items into the app's Resources, set a free Apple ID
+signing team, pick your iPhone, and Run. A free personal team gives a 7-day provisioning profile.

package/templates/mobile/ios/Tests/ApexEngineTests.swift

@@ -0,0 +1,74 @@
+// ApexEngineTests — runs on the iOS Simulator in CI (GitHub Actions macOS runner), no Mac needed
+// locally. This is the highest-value iOS check: it proves the `apex build --mobile` bundle — the
+// SHIM, the whole SSR + API pipeline, and the **asm.js SQLite** DB — actually runs under
+// **JavaScriptCore** (iOS's engine, different from Android's V8). It drives ApexEngine directly, so
+// it does NOT depend on WKURLSchemeHandler (the one remaining device-only unknown — POST bodies on
+// a custom scheme — still needs a real device/UI test).
+import JavaScriptCore
+import XCTest
+
+@testable import ApexShell
+
+final class ApexEngineTests: XCTestCase {
+  /// server.mjs + apex-bridge.js are copied into the TEST bundle by CI (see project.yml resources).
+  private func makeEngine(snapshot: String? = nil) throws -> ApexEngine {
+    try ApexEngine(snapshot: snapshot, bundle: Bundle(for: Self.self))
+  }
+
+  private func request(_ url: String, method: String = "GET", body: String? = nil) -> String {
+    let obj: [String: Any] = [
+      "url": url,
+      "method": method,
+      "headers": ["content-type": "application/json"],
+      "body": body as Any? ?? NSNull(),
+    ]
+    let data = try! JSONSerialization.data(withJSONObject: obj)
+    return String(data: data, encoding: .utf8)!
+  }
+
+  /// SSR of a DB-backed page renders the seeded rows — proves JSContext runs the bundle + asm.js DB.
+  func testGuestbookRendersSeededRowsOnJavaScriptCore() async throws {
+    let engine = try makeEngine()
+    let res = await engine.handle(request("apex://localhost/guestbook"))
+    XCTAssertTrue(res.contains("Ada Lovelace"), "seeded row missing — bundle/DB didn't run on JSCore. Got: \(res.prefix(400))")
+    XCTAssertTrue(res.contains("Alan Turing"))
+  }
+
+  /// POST inserts through the Drizzle deferred proxy on asm.js SQLite, and it persists across a
+  /// simulated cold start via the snapshot seam.
+  func testPostInsertsAndSurvivesSnapshotRestore() async throws {
+    let engine = try makeEngine()
+    _ = await engine.handle(request("apex://localhost/guestbook")) // lazy-init + seed the DB
+
+    let post = await engine.handle(
+      request(
+        "apex://localhost/api/messages",
+        method: "POST",
+        body: #"{"author":"iOS CI","body":"runs on JavaScriptCore"}"#
+      )
+    )
+    XCTAssertTrue(post.contains("iOS CI"), "POST /api/messages did not echo the created row: \(post.prefix(400))")
+
+    let after = await engine.handle(request("apex://localhost/guestbook"))
+    XCTAssertTrue(after.contains("iOS CI"), "new message not visible after POST")
+
+    // Cold-start persistence: export bytes, boot a fresh engine with them, data survives.
+    let snap = engine.snapshot()
+    XCTAssertFalse(snap.isEmpty, "snapshot export returned empty")
+    let restored = try makeEngine(snapshot: snap)
+    let restoredBody = await restored.handle(request("apex://localhost/guestbook"))
+    XCTAssertTrue(restoredBody.contains("iOS CI"), "message did not survive snapshot restore")
+  }
+
+  /// Sealed-cookie auth works on JSCore (HMAC, no WebCrypto): login sets a cookie, whoami is gated.
+  func testAuthLoginOnJavaScriptCore() async throws {
+    let engine = try makeEngine()
+    let anon = await engine.handle(request("apex://localhost/api/whoami"))
+    XCTAssertTrue(anon.contains("401"), "gated whoami should be 401 when anonymous: \(anon.prefix(200))")
+
+    let login = await engine.handle(
+      request("apex://localhost/api/login", method: "POST", body: #"{"name":"Ada"}"#)
+    )
+    XCTAssertTrue(login.contains("apex-session"), "login should set a session cookie: \(login.prefix(300))")
+  }
+}

package/templates/mobile/ios/project.yml

@@ -0,0 +1,75 @@
+# XcodeGen spec — generates ApexShell.xcodeproj from source, so the iOS project can be built on a
+# CI macOS runner (or any Mac) without hand-authoring an .xcodeproj in Xcode.
+#   brew install xcodegen && (cd ios && xcodegen generate)
+# The app + test bundle resources (server.mjs, apex-bridge.js, assets/, favicon.svg) are produced by
+# `apex build --mobile` and copied into ios/Generated/ before generating (see .github/workflows/ios.yml).
+name: ApexShell
+options:
+  bundleIdPrefix: site.apexjs
+  deploymentTarget:
+    iOS: "15.0"
+  createIntermediateGroups: true
+
+settings:
+  base:
+    SWIFT_VERSION: "5.0"
+    CODE_SIGNING_ALLOWED: "NO" # simulator builds/tests need no signing
+
+targets:
+  ApexShell:
+    type: application
+    platform: iOS
+    sources:
+      - path: ApexApp.swift
+      - path: ApexEngine.swift
+      - path: ApexSchemeHandler.swift
+      - path: ApexDbStore.swift
+      - path: Assets.xcassets
+      - path: Generated/server.mjs
+        type: file
+        buildPhase: resources
+      - path: Generated/apex-bridge.js
+        type: file
+        buildPhase: resources
+      - path: Generated/assets
+        type: folder # blue folder reference → served verbatim at /assets/*
+        buildPhase: resources
+      - path: Generated/favicon.svg
+        type: file
+        buildPhase: resources
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: site.apexjs.shell
+        INFOPLIST_FILE: Info.plist
+        GENERATE_INFOPLIST_FILE: "NO"
+        TARGETED_DEVICE_FAMILY: "1,2"
+
+  ApexShellTests:
+    type: bundle.unit-test
+    platform: iOS
+    sources:
+      - path: Tests
+      # The engine test loads the bundle from its OWN (test) bundle, so copy the JS here too.
+      - path: Generated/server.mjs
+        type: file
+        buildPhase: resources
+      - path: Generated/apex-bridge.js
+        type: file
+        buildPhase: resources
+    dependencies:
+      - target: ApexShell
+    settings:
+      base:
+        TEST_HOST: "$(BUILT_PRODUCTS_DIR)/ApexShell.app/ApexShell"
+        BUNDLE_LOADER: "$(TEST_HOST)"
+        PRODUCT_BUNDLE_IDENTIFIER: site.apexjs.shell.tests
+
+schemes:
+  ApexShell:
+    build:
+      targets:
+        ApexShell: all
+        ApexShellTests: [test]
+    test:
+      targets:
+        - ApexShellTests