@inglorious/capacitor 0.2.0 → 0.4.0

package/README.md

@@ -5,6 +5,7 @@
 Native project setup for [Capacitor](https://capacitorjs.com) apps, written once in `package.json` instead of clicked through Xcode and Android Studio. `@inglorious/create-app --mobile` sets it up for you.
 
 - `inglorious-capacitor configure` writes the app's native settings into `android/` and `ios/` after every `cap sync`: App Links and Universal Links, the signing team, push, Analytics off until consent and without the advertising ID, permissions and Info.plist entries, and the Firebase files.
+- `inglorious-capacitor dev <ios|android>` runs the app on a device or emulator with live reload from the Vite dev server.
 - `inglorious-capacitor assets` makes every icon and splash screen, light and dark, from one logo.
 - `inglorious-capacitor listing-assets` captures store screenshots of the running app in every size and language, and makes the promotional images (Google Play's feature graphic, a header and a search results card) and Google Play's 512px icon.
 
@@ -22,6 +23,8 @@ Run `configure` as Capacitor's `sync` hook, so `cap add` and `cap sync` both app
     "capacitor:sync:after": "inglorious-capacitor configure",
     "mobile:init:ios": "cap add ios && inglorious-capacitor assets --ios",
     "mobile:init:android": "cap add android && inglorious-capacitor assets --android",
+    "mobile:dev:ios": "inglorious-capacitor dev ios",
+    "mobile:dev:android": "inglorious-capacitor dev android",
     "mobile:assets": "inglorious-capacitor assets",
     "mobile:listing-assets": "inglorious-capacitor listing-assets"
   }
@@ -65,20 +68,37 @@ The `native` key of `package.json` holds them all. Every key is optional; the ap
 
 ### What `configure` does
 
-| Setting                                   | iOS                                                                                                        | Android                                                        |
-| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `appLinks`                                | Associated Domains entitlement                                                                             | Verified intent filter for `paths`                             |
-| `appLinks` + `teamId`                     | `public/.well-known/apple-app-site-association`                                                            |                                                                |
-| `appLinks` + `sha256`                     |                                                                                                            | `public/.well-known/assetlinks.json`                           |
-| `ios.teamId`                              | `DEVELOPMENT_TEAM`, so Xcode signs without asking                                                          |                                                                |
-| `ios.swipeBack`                           | A swipe from the left edge goes back: WebKit's back gesture, turned on in a generated `MainViewController` |                                                                |
-| `ios.infoPlist`                           | Info.plist entries                                                                                         |                                                                |
-| `android.permissions`                     |                                                                                                            | `<uses-permission>` entries                                    |
-| `@capacitor-firebase/messaging` installed | Push entitlement, background mode, AppDelegate methods                                                     |                                                                |
-| `@capacitor-firebase/analytics` installed | Collection off until consent                                                                               | Collection off until consent, and no advertising ID permission |
-| `GoogleService-Info.plist` in the root    | Copied into the app target                                                                                 |                                                                |
-| `google-services.json` in the root        |                                                                                                            | Copied to `android/app/`                                       |
-| always                                    |                                                                                                            | Keystores kept out of git                                      |
+| Setting                                       | iOS                                                                                                        | Android                                                        |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `appLinks`                                    | Associated Domains entitlement                                                                             | Verified intent filter for `paths`                             |
+| `appLinks` + `teamId`                         | `public/.well-known/apple-app-site-association`                                                            |                                                                |
+| `appLinks` + `sha256`                         |                                                                                                            | `public/.well-known/assetlinks.json`                           |
+| `ios.teamId`                                  | `DEVELOPMENT_TEAM`, so Xcode signs without asking                                                          |                                                                |
+| `ios.swipeBack`                               | A swipe from the left edge goes back: WebKit's back gesture, turned on in a generated `MainViewController` |                                                                |
+| `ios.infoPlist`                               | Info.plist entries                                                                                         |                                                                |
+| `ios.privacyManifest`                         | `PrivacyInfo.xcprivacy` entries, with Apple's keys                                                         |                                                                |
+| `@capawesome/capacitor-live-update` installed | `PrivacyInfo.xcprivacy` declaring its use of `UserDefaults`, which it doesn't declare itself               |                                                                |
+| `android.permissions`                         |                                                                                                            | `<uses-permission>` entries                                    |
+| `@capacitor-firebase/messaging` installed     | Push entitlement, background mode, AppDelegate methods                                                     |                                                                |
+| `@capacitor-firebase/analytics` installed     | Collection off until consent                                                                               | Collection off until consent, and no advertising ID permission |
+| `GoogleService-Info.plist` in the root        | Copied into the app target                                                                                 |                                                                |
+| `google-services.json` in the root            |                                                                                                            | Copied to `android/app/`                                       |
+| always                                        |                                                                                                            | Keystores kept out of git                                      |
+
+The privacy manifest is merged with the one already in the project, so entries added by hand stay. Apple refuses a build that calls a required-reason API without a declared reason; `configure` declares the ones of known plugins that ship no manifest of their own, and `ios.privacyManifest` adds the app's:
+
+```json
+"privacyManifest": {
+  "NSPrivacyAccessedAPITypes": [
+    {
+      "NSPrivacyAccessedAPIType": "NSPrivacyAccessedAPICategoryUserDefaults",
+      "NSPrivacyAccessedAPITypeReasons": ["CA92.1"]
+    }
+  ]
+}
+```
+
+A file input that takes images (a `Button` with `accept="image/*"`) offers the camera on iOS, which closes the app unless `ios.infoPlist` has an `NSCameraUsageDescription`.
 
 Path patterns end in `*` to match a prefix: `/jobs*` is every path that starts with `/jobs`. `exclude` takes paths and, starting with `#`, fragments; only iOS can exclude, so on Android list in `paths` only what opens the app. Serve both `.well-known` files as `application/json`.
 
@@ -88,6 +108,10 @@ It runs for the platform Capacitor is syncing, and changes nothing when the sett
 
 It centres the logo (`public/logo.svg` or `public/logo.png` by default) on `background` for the icons and the splash screen, and on `backgroundDark` for the dark splash screen, then hands the result to [`@capacitor/assets`](https://github.com/ionic-team/capacitor-assets) for every size and density. `iconScale` and `splashScale` are the logo's width as a share of the icon and of the splash screen. Pass `--ios` or `--android` for one platform.
 
+## Live reload on a device
+
+`inglorious-capacitor dev ios` (or `android`) starts Vite on the local network (`vite --host`) and runs `cap run ios --live-reload`, which points the installed app at it: every saved file reloads on the phone. The phone must be on the same network as the computer. It builds the web app first if `webDir` has none, since `cap run` syncs it. Further options go to `cap run`, such as `--target <id>`; `--port=<port>` changes Vite's port (5173 by default). Ctrl+C stops both, and Capacitor puts the native config back.
+
 ## Store listing images
 
 `listing-assets` opens the running app in your installed Chrome (through `playwright-core`, so no browser download) and captures the screens listed in `listing.config.js`, once per device and language:

package/bin/inglorious-capacitor.js

@@ -5,6 +5,9 @@ const USAGE = `Usage: inglorious-capacitor <command>
 
   configure            Apply the "native" settings in package.json to the
                        native projects (runs after every cap sync)
+  dev <ios|android> [--port=5173] [cap run options]
+                       Run the app on a device or emulator with live reload
+                       from the Vite dev server
   assets [--ios] [--android]
                        Make the app icons and splash screens from the logo
   listing-assets       Capture store screenshots of the running app, and make
@@ -21,6 +24,15 @@ try {
     const { configure } = await import("../src/configure/index.js")
     const platforms = await configure()
     if (platforms.length) console.log(`Configured ${platforms.join(" and ")}`)
+  } else if (command === "dev") {
+    const { dev } = await import("../src/dev/index.js")
+    const [platform, ...rest] = flags
+    const portFlag = rest.find((flag) => flag.startsWith("--port="))
+    process.exitCode = await dev({
+      platform,
+      port: portFlag ? Number(portFlag.slice("--port=".length)) : undefined,
+      args: rest.filter((flag) => flag !== portFlag),
+    })
   } else if (command === "assets") {
     const { assets } = await import("../src/assets/index.js")
     await assets({ platforms: flags.map((flag) => flag.replace(/^--/, "")) })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/capacitor",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Configures Capacitor's native projects from package.json, makes their icons and splash screens from one logo, and the screenshots and graphics the stores ask for.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",

package/src/config.js

@@ -10,6 +10,15 @@ const CAPACITOR_CONFIG_FILES = [
 ]
 const PUSH_PLUGIN = "@capacitor-firebase/messaging"
 const ANALYTICS_PLUGIN = "@capacitor-firebase/analytics"
+const USER_DEFAULTS = {
+  NSPrivacyAccessedAPIType: "NSPrivacyAccessedAPICategoryUserDefaults",
+  NSPrivacyAccessedAPITypeReasons: ["CA92.1"],
+}
+// Plugins that call Apple's required-reason APIs without a privacy manifest of
+// their own, so the app has to declare them.
+const PLUGIN_API_TYPES = {
+  "@capawesome/capacitor-live-update": [USER_DEFAULTS],
+}
 
 /**
  * Everything `configure` and `assets` act on: the app's id and name from the
@@ -32,14 +41,18 @@ export async function readSettings(root, env = process.env) {
     root,
     appId: capacitor.appId,
     appName: capacitor.appName,
+    webDir: capacitor.webDir ?? "www",
     appLinks: native.appLinks?.domain
       ? normalizeAppLinks(native.appLinks)
       : null,
-    ios: { teamId: null, infoPlist: {}, ...native.ios },
+    ios: { teamId: null, infoPlist: {}, privacyManifest: null, ...native.ios },
     android: { sha256: [], permissions: [], ...native.android },
     assets: native.assets ?? {},
     hasPush: PUSH_PLUGIN in dependencies,
     hasAnalytics: ANALYTICS_PLUGIN in dependencies,
+    accessedApiTypes: Object.entries(PLUGIN_API_TYPES)
+      .filter(([plugin]) => plugin in dependencies)
+      .flatMap(([, types]) => types),
   }
 }
 

package/src/configure/configure.test.js

@@ -10,6 +10,7 @@ import { tmpdir } from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 
+import plist from "plist"
 import { afterEach, beforeEach, describe, expect, it } from "vitest"
 
 import { configure } from "./index.js"
@@ -43,6 +44,7 @@ describe("configure", () => {
     expect(after.manifest).not.toContain("autoVerify")
     expect(after.plist).not.toContain("UIBackgroundModes")
     expect(after.appDelegate).toBe(before.appDelegate)
+    expect(after.privacyManifest).toBeNull()
     expect(after.gitignore).toMatch(/^\*\.jks$/m)
     expect(existsSync(path.join(root, "public"))).toBe(false)
   })
@@ -186,6 +188,90 @@ function writePackage(root, pkg) {
   writeFileSync(path.join(root, "package.json"), JSON.stringify(pkg))
 }
 
+describe("configure, privacy manifest", () => {
+  let root
+
+  beforeEach(() => {
+    root = mkdtempSync(path.join(tmpdir(), "inglorious-capacitor-"))
+    cpSync(FIXTURES, root, { recursive: true })
+  })
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  it("declares what plugins use without saying so, once, as a resource", async () => {
+    writePackage(root, {
+      dependencies: { "@capawesome/capacitor-live-update": "^8.0.0" },
+    })
+
+    await configure({ root, env: { CAPACITOR_CONFIG } })
+    const first = snapshot(root)
+    await configure({ root, env: { CAPACITOR_CONFIG } })
+
+    expect(snapshot(root)).toEqual(first)
+    expect(plist.parse(first.privacyManifest)).toEqual({
+      NSPrivacyTracking: false,
+      NSPrivacyTrackingDomains: [],
+      NSPrivacyCollectedDataTypes: [],
+      NSPrivacyAccessedAPITypes: [
+        {
+          NSPrivacyAccessedAPIType: "NSPrivacyAccessedAPICategoryUserDefaults",
+          NSPrivacyAccessedAPITypeReasons: ["CA92.1"],
+        },
+      ],
+    })
+    expect(first.pbxproj).toContain("PrivacyInfo.xcprivacy in Resources")
+    expect(first.pbxproj).not.toContain("PrivacyInfo.xcprivacy in Sources")
+  })
+
+  it("merges the declared entries with the manifest already there", async () => {
+    writeFileSync(
+      path.join(root, "ios", "App", "App", "PrivacyInfo.xcprivacy"),
+      plist.build({
+        NSPrivacyAccessedAPITypes: [
+          {
+            NSPrivacyAccessedAPIType:
+              "NSPrivacyAccessedAPICategoryUserDefaults",
+            NSPrivacyAccessedAPITypeReasons: ["1C8F.1"],
+          },
+        ],
+      }),
+    )
+    writePackage(root, {
+      dependencies: { "@capawesome/capacitor-live-update": "^8.0.0" },
+      native: {
+        ios: {
+          privacyManifest: {
+            NSPrivacyAccessedAPITypes: [
+              {
+                NSPrivacyAccessedAPIType:
+                  "NSPrivacyAccessedAPICategoryFileTimestamp",
+                NSPrivacyAccessedAPITypeReasons: ["C617.1"],
+              },
+            ],
+          },
+        },
+      },
+    })
+
+    await configure({ root, env: { CAPACITOR_CONFIG } })
+
+    expect(
+      plist.parse(snapshot(root).privacyManifest).NSPrivacyAccessedAPITypes,
+    ).toEqual([
+      {
+        NSPrivacyAccessedAPIType: "NSPrivacyAccessedAPICategoryUserDefaults",
+        NSPrivacyAccessedAPITypeReasons: ["1C8F.1", "CA92.1"],
+      },
+      {
+        NSPrivacyAccessedAPIType: "NSPrivacyAccessedAPICategoryFileTimestamp",
+        NSPrivacyAccessedAPITypeReasons: ["C617.1"],
+      },
+    ])
+  })
+})
+
 function snapshot(root) {
   const read = (...segments) => {
     const file = path.join(root, ...segments)
@@ -201,6 +287,7 @@ function snapshot(root) {
     entitlements: read("ios", "App", "App", "App.entitlements"),
     appDelegate: read("ios", "App", "App", "AppDelegate.swift"),
     viewController: read("ios", "App", "App", "MainViewController.swift"),
+    privacyManifest: read("ios", "App", "App", "PrivacyInfo.xcprivacy"),
     storyboard: read("ios", "App", "App", "Base.lproj", "Main.storyboard"),
     association: read("public", ".well-known", "apple-app-site-association"),
     assetLinks: read("public", ".well-known", "assetlinks.json"),

package/src/configure/ios.js

@@ -14,6 +14,8 @@ const ANALYTICS_OFF = {
   GOOGLE_ANALYTICS_IDFV_COLLECTION_ENABLED: false,
 }
 const GOOGLE_SERVICE_INFO = "GoogleService-Info.plist"
+const PRIVACY_MANIFEST = "PrivacyInfo.xcprivacy"
+const APP_GROUP = "App"
 const APP_DELEGATE = "AppDelegate.swift"
 const MAIN_VIEW_CONTROLLER = "MainViewController.swift"
 const MAIN_STORYBOARD = path.join("Base.lproj", "Main.storyboard")
@@ -113,11 +115,96 @@ export async function configureIos(project, settings) {
     addPushMethods(path.join(appRoot, APP_DELEGATE))
   }
 
+  if (settings.ios.privacyManifest || settings.accessedApiTypes.length) {
+    writePrivacyManifest(path.join(appRoot, PRIVACY_MANIFEST), settings)
+    if (
+      !readFileSync(pbxprojPath(settings.root), "utf8").includes(
+        PRIVACY_MANIFEST,
+      )
+    ) {
+      addResource(ios, PRIVACY_MANIFEST)
+    }
+  }
+
   if (settings.ios.swipeBack) {
     await enableSwipeBack(ios, settings.root, appRoot)
   }
 }
 
+/**
+ * Writes the app's privacy manifest: what is already in it, what the app
+ * declares in `ios.privacyManifest`, and the required-reason APIs its plugins
+ * use without declaring them.
+ */
+function writePrivacyManifest(file, settings) {
+  const current = existsSync(file)
+    ? plist.parse(readFileSync(file, "utf8"))
+    : {}
+  const declared = settings.ios.privacyManifest ?? {}
+  const next = {
+    ...current,
+    ...declared,
+    NSPrivacyTracking:
+      declared.NSPrivacyTracking ?? current.NSPrivacyTracking ?? false,
+    NSPrivacyTrackingDomains: union(
+      current.NSPrivacyTrackingDomains,
+      declared.NSPrivacyTrackingDomains,
+    ),
+    NSPrivacyCollectedDataTypes:
+      declared.NSPrivacyCollectedDataTypes ??
+      current.NSPrivacyCollectedDataTypes ??
+      [],
+    NSPrivacyAccessedAPITypes: mergeApiTypes([
+      ...(current.NSPrivacyAccessedAPITypes ?? []),
+      ...(declared.NSPrivacyAccessedAPITypes ?? []),
+      ...settings.accessedApiTypes,
+    ]),
+  }
+  if (JSON.stringify(next) === JSON.stringify(current)) return
+  writeFileSync(file, plist.build(next))
+}
+
+function mergeApiTypes(types) {
+  const byType = new Map()
+  for (const type of types) {
+    const name = type.NSPrivacyAccessedAPIType
+    byType.set(name, {
+      NSPrivacyAccessedAPIType: name,
+      NSPrivacyAccessedAPITypeReasons: union(
+        byType.get(name)?.NSPrivacyAccessedAPITypeReasons,
+        type.NSPrivacyAccessedAPITypeReasons,
+      ),
+    })
+  }
+  return [...byType.values()]
+}
+
+function union(first = [], second = []) {
+  return [...new Set([...first, ...second])]
+}
+
+// Trapeze's addFile compiles any file that is not a .plist or .strings, and a
+// privacy manifest has to be copied into the bundle instead.
+function addResource(ios, fileName) {
+  const groups = ios.pbxProject?.hash.project.objects.PBXGroup ?? {}
+  const appGroup = Object.entries(groups).find(
+    ([, group]) =>
+      group.isa === "PBXGroup" &&
+      (group.name === APP_GROUP || group.path === APP_GROUP),
+  )
+  const [appGroupId] = appGroup ?? []
+  ios.addResourceFile(fileName, appGroupId)
+  const references = ios.pbxProject?.hash.project.objects.PBXFileReference ?? {}
+  for (const reference of Object.values(references)) {
+    if (reference?.path !== `"${fileName}"`) continue
+    reference.lastKnownFileType = "text.xml"
+    for (const [key, value] of Object.entries(reference)) {
+      if (value === undefined) delete reference[key]
+    }
+  }
+  ios.markPbxModified()
+}
+
 async function enableSwipeBack(ios, root, appRoot) {
   const controller = path.join(appRoot, MAIN_VIEW_CONTROLLER)
   if (!existsSync(controller)) {

package/src/dev/dev.test.js

@@ -0,0 +1,103 @@
+import { EventEmitter } from "node:events"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import { dev } from "./index.js"
+
+const CAPACITOR_CONFIG = {
+  appId: "com.example.app",
+  appName: "Example",
+  webDir: "dist",
+}
+
+describe("dev", () => {
+  let root
+
+  beforeEach(() => {
+    root = mkdtempSync(path.join(tmpdir(), "inglorious-capacitor-dev-"))
+    writeFileSync(path.join(root, "package.json"), "{}")
+    writeFileSync(
+      path.join(root, "capacitor.config.json"),
+      JSON.stringify(CAPACITOR_CONFIG),
+    )
+  })
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  it("serves Vite on the network and runs the app against it", async () => {
+    buildWebDir(root)
+    const spawn = fakeSpawn()
+
+    const code = await dev({
+      root,
+      platform: "ios",
+      args: ["--target", "ABC"],
+      spawn,
+      isReady: async () => true,
+    })
+
+    expect(code).toBe(0)
+    expect(spawn.calls).toEqual([
+      ["vite", ["--host", "--port", "5173", "--strictPort"]],
+      [
+        "cap",
+        ["run", "ios", "--live-reload", "--port", "5173", "--target", "ABC"],
+      ],
+    ])
+    expect(spawn.children[0].kill).toHaveBeenCalled()
+  })
+
+  it("builds the web app first when it was never built", async () => {
+    const spawn = fakeSpawn()
+
+    await dev({
+      root,
+      platform: "android",
+      port: 3000,
+      spawn,
+      isReady: async () => true,
+    })
+
+    expect(
+      spawn.calls.map(([command, args]) => `${command} ${args[0]}`),
+    ).toEqual(["vite build", "vite --host", "cap run"])
+  })
+
+  it("stops the dev server when the app fails", async () => {
+    buildWebDir(root)
+    const spawn = fakeSpawn({ cap: 1 })
+
+    await expect(
+      dev({ root, platform: "android", spawn, isReady: async () => true }),
+    ).rejects.toThrow("exited with 1")
+    expect(spawn.children[0].kill).toHaveBeenCalled()
+  })
+
+  it("refuses an unknown platform", async () => {
+    await expect(dev({ root, platform: "web" })).rejects.toThrow("Usage")
+  })
+})
+
+function buildWebDir(root) {
+  mkdirSync(path.join(root, "dist"))
+  writeFileSync(path.join(root, "dist", "index.html"), "")
+}
+
+function fakeSpawn(exitCodes = {}) {
+  const spawn = (command, args) => {
+    spawn.calls.push([command, args])
+    const child = Object.assign(new EventEmitter(), { kill: vi.fn() })
+    spawn.children.push(child)
+    const isServer = command === "vite" && args[0] === "--host"
+    if (!isServer) setTimeout(() => child.emit("exit", exitCodes[command] ?? 0))
+    return child
+  }
+  spawn.calls = []
+  spawn.children = []
+  return spawn
+}

package/src/dev/index.js

@@ -0,0 +1,101 @@
+import { spawn as nodeSpawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import process from "node:process"
+
+import { readSettings } from "../config.js"
+
+export const DEV_PORT = 5173
+const PLATFORMS = ["ios", "android"]
+const SUCCESS = 0
+const READY_POLL_MS = 250
+const READY_TIMEOUT_MS = 30_000
+
+/**
+ * Runs the app on a phone or emulator against the Vite dev server on this
+ * computer, so every saved file reloads on the device. Vite listens on the
+ * local network and `cap run --live-reload` points the native app at it;
+ * stopping either stops both, and Capacitor restores the native config.
+ *
+ * @param {{ root?: string, platform: string, port?: number, args?: string[], spawn?: typeof nodeSpawn, isReady?: (url: string) => Promise<boolean> }} options
+ *   `args` go to `cap run`, such as `--target <id>`.
+ * @returns {Promise<number>} The exit code of `cap run`.
+ */
+export async function dev({
+  root = process.cwd(),
+  platform,
+  port = DEV_PORT,
+  args = [],
+  spawn = nodeSpawn,
+  isReady = respondsAt,
+}) {
+  if (!PLATFORMS.includes(platform)) {
+    throw new Error(`Usage: inglorious-capacitor dev <ios|android>`)
+  }
+
+  const { webDir } = await readSettings(root, {})
+  if (!existsSync(path.join(root, webDir, "index.html"))) {
+    await run(spawn, "vite", ["build"], root)
+  }
+
+  const commands = devCommands({ platform, port, args })
+  const server = spawn(...commands.server, { cwd: root, stdio: "inherit" })
+  try {
+    await waitFor(() => isReady(`http://localhost:${port}`))
+    const ignoreInterrupt = () => {}
+    process.on("SIGINT", ignoreInterrupt)
+    try {
+      return await run(spawn, ...commands.app, root)
+    } finally {
+      process.off("SIGINT", ignoreInterrupt)
+    }
+  } finally {
+    server.kill()
+  }
+}
+
+/**
+ * The two processes `dev` starts.
+ *
+ * @param {{ platform: string, port: number, args: string[] }} options
+ */
+export function devCommands({ platform, port, args }) {
+  return {
+    server: ["vite", ["--host", "--port", String(port), "--strictPort"]],
+    app: [
+      "cap",
+      ["run", platform, "--live-reload", "--port", String(port), ...args],
+    ],
+  }
+}
+
+function run(spawn, command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: "inherit" })
+    child.on("error", reject)
+    child.on("exit", (code) => {
+      if (code)
+        reject(new Error(`${command} ${args.join(" ")} exited with ${code}`))
+      else resolve(SUCCESS)
+    })
+  })
+}
+
+async function waitFor(check) {
+  const deadline = Date.now() + READY_TIMEOUT_MS
+  while (!(await check())) {
+    if (Date.now() > deadline) {
+      throw new Error("The dev server didn't start in time")
+    }
+    await new Promise((resolve) => setTimeout(resolve, READY_POLL_MS))
+  }
+}
+
+async function respondsAt(url) {
+  try {
+    await fetch(url)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/index.js

@@ -1,4 +1,5 @@
 export { assets } from "./assets/index.js"
 export { readSettings } from "./config.js"
 export { configure } from "./configure/index.js"
+export { dev } from "./dev/index.js"
 export { listingAssets } from "./listing-assets/index.js"

package/types/index.d.ts

@@ -24,6 +24,12 @@ export interface NativeConfig {
      * WebKit's back gesture in a generated `MainViewController`.
      */
     swipeBack?: boolean
+    /**
+     * Entries of the app's `PrivacyInfo.xcprivacy`, with Apple's keys. Merged
+     * with the manifest already there and with the required-reason APIs of
+     * known plugins that do not declare their own.
+     */
+    privacyManifest?: PrivacyManifest
   }
   android?: {
     /** SHA-256 fingerprints of the keys that sign the app, for App Links. */
@@ -45,20 +51,39 @@ export interface NativeConfig {
   }
 }
 
+/** An app's privacy manifest, with Apple's keys. */
+export interface PrivacyManifest {
+  NSPrivacyTracking?: boolean
+  NSPrivacyTrackingDomains?: string[]
+  NSPrivacyCollectedDataTypes?: Record<string, unknown>[]
+  NSPrivacyAccessedAPITypes?: AccessedApiType[]
+}
+
+/** A required-reason API and why the app calls it. */
+export interface AccessedApiType {
+  NSPrivacyAccessedAPIType: string
+  NSPrivacyAccessedAPITypeReasons: string[]
+}
+
 export interface ProjectSettings {
   root: string
   appId: string
   appName: string
+  /** The built web app, from the Capacitor config. */
+  webDir: string
   appLinks: Required<NonNullable<NativeConfig["appLinks"]>> | null
   ios: {
     teamId: string | null
     infoPlist: Record<string, unknown>
     swipeBack?: boolean
+    privacyManifest: PrivacyManifest | null
   }
   android: { sha256: string[]; permissions: string[] }
   assets: NonNullable<NativeConfig["assets"]>
   hasPush: boolean
   hasAnalytics: boolean
+  /** Required-reason APIs the app's plugins use without declaring them. */
+  accessedApiTypes: AccessedApiType[]
 }
 
 /**
@@ -162,3 +187,18 @@ export declare function assets(options?: {
   root?: string
   platforms?: ("ios" | "android")[]
 }): Promise<void>
+
+/**
+ * Runs the app on a device or emulator with live reload: Vite listens on the
+ * local network and `cap run --live-reload` points the app at it. Builds the
+ * web app first if it was never built.
+ * @returns The exit code of `cap run`.
+ */
+export declare function dev(options: {
+  root?: string
+  platform: "ios" | "android"
+  /** Defaults to 5173. */
+  port?: number
+  /** More options for `cap run`, such as `["--target", "<id>"]`. */
+  args?: string[]
+}): Promise<number>