@clubedge/create-clubedge-app 0.44.0 → 0.46.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.46.0
+
+- **Add and remove the apps installed on devices** (#161), so a project created without them can take them later, and drop them again, without starting over: `pnpm clubedge add mobile expo` for the native app, `pnpm clubedge add shell capacitor` for the shell that packages the website, and `pnpm clubedge remove mobile` or `pnpm clubedge remove shell`. The shell needs Starter v0.27.0 or later, and the native app v0.28.0.
+  - Adding an app brings its folder, its CI job and the Starter's other sections for it, its dependencies, and its local env file. `package.json` records it, so later changes and upgrades keep it.
+  - The app must fit the project, and the CLI says which project can have it when this one can't. When the project's option for a module is one the app lacks, such as a sign-in the native app doesn't have yet, switch it in the same command: `pnpm clubedge add mobile expo auth better-auth`.
+  - Removing an app deletes the Starter's files and lists what was never the Starter's, such as the shell's `android/` and `ios/` projects, to delete once you no longer need them.
+  - The framework and the API stay as the project was created.
+  - When a change keeps a variable in a local env file, the comments above it that you never edited now follow the example's, so a later change that removes the variable removes them too.
+- **Module options can name the registry packages only they need** (#162), in a new `dependencies` field. A project without the option leaves them out, such as the notification plugins in projects without push. Stack packs can use it too ([stack packs](https://github.com/Clubedge/create-clubedge-app/blob/main/docs/stack-packs.md)).
+- **Starter v0.30.0** by default (#163). Its template schema is still 6. The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.30.0) cover:
+  - store releases for both mobile apps, signed, from your computer or a workflow, with build numbers made from each app's version;
+  - push notifications for both apps (`--push expo` or `--push native`);
+  - over-the-air updates for the native app (`--ota eas`).
+
+## 0.45.0
+
+- **Starter v0.29.0** by default (#159). Its template schema is still 6. The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.29.0) cover:
+  - an update policy for apps installed on phones: a minimum announced for a date, values per platform, and APIs that answer apps below the minimum `426 update_required`;
+  - a new design for the native app (`--mobile expo`);
+  - splash screens that are never cropped or stretched.
+- **`package.json` merges by key** (#158) when `add`, `remove`, or `upgrade` merges the Starter's changes into your project:
+  - A key only one side changed takes that side's value, and objects merge key by key, so your dependencies and the Starter's no longer collide line by line.
+  - A key both sides changed differently is a conflict, with the usual markers around that key's lines only.
+  - Your key order and indentation are kept. A file that doesn't parse, such as one with markers left from an earlier merge, merges by line as before.
+- **The Starter pin** keeps the release a change came with in notes such as "since CLI 0.44.0, with Starter v0.28.0", which moving the pin to v0.29.0 had changed.
+- CI uses astral-sh/setup-uv 10.3.2 (#154).
+
 ## 0.44.0
 
 - **The native app with Expo**: default to Starter `v0.28.0` (#151). `--mobile expo` adds `apps/mobile`, an Android and iOS app with its own native screens, which calls the project's API (#147):

package/README.md

@@ -165,6 +165,8 @@ pnpm dlx @clubedge/create-clubedge-app my-app --framework vite --api hono --mobi
 
 A shell packages the frontend's static files, so it needs `--framework vite`, and the frontend still needs its API (`--api hono` or `--api fastapi`). A native app calls the API through the website, as the shell does, so it needs one too. Next.js and TanStack Start render their pages on their own server and have no separate API for an app to call: the CLI refuses `--shell` and `--mobile` with them, and interactive runs only ask about a mobile app after a frontend and its API. A shell and a native app run no server, so `deploy` deploys the frontend and the API as above and leaves them out. The native app's Starter lists the sign-in options it supports, so the CLI refuses an `--auth` option the app does not have yet.
 
+A project created without them can add them later, and drop them again: `pnpm clubedge add mobile expo`, `pnpm clubedge add shell capacitor`, or `pnpm clubedge remove mobile` (since CLI 0.46.0, see [Change an existing project](#change-an-existing-project)).
+
 #### Without a website
 
 A project can also be only an API and its native app: `--framework none` leaves the web app out (since CLI 0.44.0, with Starter v0.28.0).
@@ -241,7 +243,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.28.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.30.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -250,7 +252,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter
 
 ## Change an existing project
 
-Inside a project created by the CLI, `add` and `remove` change modules, and `upgrade` moves the project to a newer Starter release. Projects from Starter v0.8.0 on have a `clubedge` script, so `pnpm clubedge add cache redis` works too. Without a module or option, `add` and `remove` ask for them, with a list where you can pick several modules at once:
+Inside a project created by the CLI, `add` and `remove` change modules and the apps installed on devices, and `upgrade` moves the project to a newer Starter release. Projects from Starter v0.8.0 on have a `clubedge` script, so `pnpm clubedge add cache redis` works too. Without a module or option, `add` and `remove` ask for them, with a list where you can pick several modules and apps at once:
 
 ```sh
 pnpm clubedge add                                            # choose a module and option from a list
@@ -258,21 +260,33 @@ pnpm dlx @clubedge/create-clubedge-app add cache redis      # or switch: add aut
 pnpm dlx @clubedge/create-clubedge-app remove storage
 pnpm clubedge add email resend payments stripe              # several modules as one change
 pnpm clubedge remove storage payments
+pnpm clubedge add mobile expo                               # the native app; add shell capacitor packages the website
+pnpm clubedge remove mobile
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.28.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.30.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
 
 - Files you never changed are updated, added, or deleted.
 - Files you changed keep your edits. Where the module change touches the same lines, the file gets conflict markers (`<<<<<<< yours` ... `>>>>>>> clubedge`) for you to resolve. The Starter's whole new version of each such file is saved in `.clubedge/incoming/` to compare with yours (`git diff --no-index <file> .clubedge/incoming/<file>`); Git ignores that folder, so delete it when you are done.
+- `package.json` files merge by key, not by line: a script, dependency, or override you added next to the Starter's keeps both, and markers wrap only a key you both changed to different values, such as the same dependency's range. The file keeps your key order, indentation, and line endings.
 - Your own files are never touched.
 - Each app's local env file (`apps/web/.env.local`, and `apps/api/.env.local`, `apps/shell/.env.local`, or `apps/mobile/.env.local` when the project has them) keeps your values. Values still at their generated defaults follow the new selection, and new variables are added.
 - `pnpm-lock.yaml` is replaced if you never changed your dependencies; otherwise `pnpm install` reconciles it.
 
 Several modules in one command are applied as one change, and their requirements are checked together, so `add auth supabase storage supabase` works even though Supabase Storage needs Supabase Auth. When lines conflict, the CLI lists each file with its number of conflict blocks. Before an upgrade, it lists the Starter releases it crosses with the sections of their release notes, such as `v0.13.0  Observability, Tests, Also`.
 
+### Apps installed on devices
+
+Since CLI 0.46.0, `add` and `remove` also take the apps that run on phones rather than on a server: the native app (`add mobile expo`) and the shell that packages the website (`add shell capacitor`), with Starter v0.27.0 or later for the shell and v0.28.0 for the native app. The project's framework and API stay as they were created, since its deployment and data are built around them.
+
+- Adding an app brings its folder, its CI job and the rest of the Starter's sections for it, its dependencies in `pnpm-lock.yaml`, and its local env file, made from its example as a new project's is. `package.json` records it, so later changes and upgrades keep it.
+- The app must fit the project: the native app calls an API, so it needs `--framework vite` or `none` with an API, and the shell packages the Vite frontend. The CLI says which project can have the app when this one cannot.
+- An app implements the modules it uses, such as the native app's sign-in. When the project's option is one it lacks, switch it in the same command: `add mobile expo auth better-auth`.
+- Removing an app deletes the Starter's files and leaves what was never the Starter's, such as its env file, its `node_modules`, and the shell's `android/` and `ios/` projects. The CLI lists them, to delete once you no longer need them.
+
 The project must be a Git repository without uncommitted changes, so you can review the result with `git diff` and undo it. Pass `--force` to skip this check. Add `--no-install` to skip `pnpm install`. Afterward, run `pnpm db:migrate` and `pnpm check:services` if the change added tables or services.
 
 pnpm cannot read a `package.json` with conflict markers, so a change that leaves conflicts in one skips `pnpm install` and says so: resolve them, then run `pnpm install`. Until then, `pnpm clubedge` does not start either, and the CLI's own commands (`pnpm dlx @clubedge/create-clubedge-app status`, for example) stop with a message that names the file and the command that compares it with the Starter's version in `.clubedge/incoming/`. When the install fails for another reason, the CLI still lists what is left to resolve, then exits with an error.
@@ -399,27 +413,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.44.0
+create-clubedge-app v0.46.0
         |
         v
-Clubedge Starter v0.28.0
-commit 090b05a9561f6eb7bb3bc0ab0b15ada7702aef8c
+Clubedge Starter v0.30.0
+commit 4d341955bd13cb170c7385acb745c3d374259897
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.44.0` | `clubedge-starter@v0.28.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.46.0` | `clubedge-starter@v0.30.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.28.0` tag is expected to resolve to commit
-`090b05a9561f6eb7bb3bc0ab0b15ada7702aef8c`. The CLI verifies this before
+The `v0.30.0` tag is expected to resolve to commit
+`4d341955bd13cb170c7385acb745c3d374259897`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.28.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.30.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -474,7 +488,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.28.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.30.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -529,6 +543,8 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.42.0 | v0.27.0 | Starter v0.27.0: mobile apps with Capacitor (`--shell capacitor`, template schema 5); client addresses per platform; Docker Compose behind Caddy, with images on GHCR |
 | 0.43.0 | v0.27.1 | Upgrades keep each app's own version; add, remove, and upgrade that change nothing skip the Starter download |
 | 0.44.0 | v0.28.0 | Starter v0.28.0: the native app with Expo (`--mobile expo`, template schema 6); projects without a website (`--framework none`), with template rules; audit exceptions per stack |
+| 0.45.0 | v0.29.0 | Starter v0.29.0: an update policy for installed apps, a new design for the native app, and clean splash screens; `package.json` merged by key |
+| 0.46.0 | v0.30.0 | Add and remove the mobile apps in an existing project; Starter v0.30.0: store releases, push notifications, and over-the-air updates; module options' `dependencies` |
 
 ## Community
 

package/dist/cli/args.js

@@ -153,7 +153,7 @@ function parseCommand(positionals) {
     const module = rest[0];
     if (name === "add") {
         if (rest.length > 1 && rest.length % 2 === 1) {
-            throw new UsageError("Usage: add [module option]..., for example: add cache redis, or add email resend payments stripe");
+            throw new UsageError("Usage: add [module option]..., for example: add cache redis, add email resend payments stripe, or add mobile expo");
         }
         const changes = rest.length === 1
             ? [{ module: rest[0] }]

package/dist/cli/ui.js

@@ -101,8 +101,9 @@ Usage:
   upgrade, status, doctor, try, deploy, or neon. Without a module or option, add and remove ask
   for them.
 
-  add and remove change modules of an existing project, several at once as one
-  change, and upgrade moves it to a newer Starter (this CLI's release unless --ref
+  add and remove change modules of an existing project, and its apps installed on
+  devices (add mobile expo, add shell capacitor, remove mobile), several at once as
+  one change, and upgrade moves it to a newer Starter (this CLI's release unless --ref
   is given) and lists the Starter releases it crosses. The change is merged into
   your code; lines you changed that it also changes get conflict markers. Commit
   first so you can review the result with git diff.

package/dist/core/env.js

@@ -49,12 +49,28 @@ export function updateEnvFile(local, baseExample, targetExample) {
         const start = generated ? at - comments.length : at;
         lines.splice(start, at - start + 1, ...(generated ? replacement : replacement.slice(-1)));
     }
+    /**
+     * Gives a variable whose value stays the target's comments, if the developer kept the base's:
+     * another change of the selection then still finds them as generated, and removes them with it.
+     */
+    function refreshComments(key) {
+        const at = find(lines, key);
+        const comments = commentsAbove(lines, at);
+        const baseComments = commentsAbove(base, find(base, key));
+        const targetComments = commentsAbove(target, find(target, key));
+        if (sameLines(comments, baseComments) && !sameLines(baseComments, targetComments)) {
+            lines.splice(at - comments.length, comments.length, ...targetComments);
+        }
+    }
     for (const [key, before] of baseValues) {
         if (!mine.has(key))
             continue;
         const after = targetValues.get(key);
-        if (after === before || mine.get(key) === after)
+        if (after === before || mine.get(key) === after) {
+            if (after !== undefined)
+                refreshComments(key);
             continue;
+        }
         const generated = mine.get(key) === before;
         if (after === undefined) {
             (generated ? result.removed : result.unused).push(key);

package/dist/core/manifest-fields.js

@@ -89,6 +89,17 @@ export function parseRequires(file, value, prefix) {
     }
     return requires;
 }
+/** An npm package name, scoped or not, such as expo-notifications or @capacitor/push-notifications. */
+const PACKAGE_NAME = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+/** `dependencies`: packages from the registry, by name. */
+function parseDependencies(file, value, prefix) {
+    if (value === undefined)
+        return [];
+    if (!isStringArray(value) || !value.every((name) => PACKAGE_NAME.test(name))) {
+        throw new ManifestError(`${file}: ${prefix}dependencies must be an array of package names.`);
+    }
+    return value;
+}
 /** A module's name, default, and options; `prefix` locates it in its file. */
 export function parseModule(file, entry, prefix) {
     const { fail, requireString } = fields(file, prefix);
@@ -111,6 +122,7 @@ export function parseModule(file, entry, prefix) {
         options[optionId] = {
             name: read.requireString(values, "name"),
             packages: read.optionalStringRecord(values, "packages"),
+            dependencies: parseDependencies(file, values.dependencies, optionPrefix),
             files: read.optionalStringArray(values, "files"),
             replace: read.optionalStringRecord(values, "replace"),
             requires: parseRequires(file, values.requires, optionPrefix),

package/dist/core/merge.js

@@ -1,7 +1,8 @@
 // Three-way merge between what the CLI generated (base), what it would generate now (target),
 // and the project as it is (current). Changes from base to target are applied to the project
 // without losing the project's own edits. Pure: callers read and write the files.
-import { diff3Merge } from "node-diff3";
+import { diff3Merge, diffComm } from "node-diff3";
+import { mergePackageJson } from "./package-json-merge.js";
 export const CONFLICT_LABELS = { yours: "yours", theirs: "clubedge" };
 /**
  * Where the Starter's versions of files left to resolve are saved, next to the project's own,
@@ -35,28 +36,41 @@ export function sameContent(a, b) {
         return a.equals(b);
     return normalize(a) === normalize(b);
 }
-/** Merges base -> target into current. Resolves null for binary files, which cannot be merged. */
-export function mergeText(current, base, target) {
-    if (isBinary(current) || isBinary(base) || isBinary(target))
-        return null;
-    const split = (content) => normalize(content).split("\n");
-    const regions = diff3Merge(split(current), split(base), split(target), { excludeFalseConflicts: true });
+/** The merged text, with conflict markers around each region where the two sides differ. */
+function withMarkers(regions) {
     const lines = [];
     let conflict = false;
     for (const region of regions) {
-        if (region.ok) {
+        if ("ok" in region) {
             lines.push(...region.ok);
             continue;
         }
-        if (!region.conflict)
-            continue;
         conflict = true;
-        lines.push(`<<<<<<< ${CONFLICT_LABELS.yours}`, ...region.conflict.a, "=======", ...region.conflict.b, `>>>>>>> ${CONFLICT_LABELS.theirs}`);
+        lines.push(`<<<<<<< ${CONFLICT_LABELS.yours}`, ...region.yours, "=======", ...region.theirs, `>>>>>>> ${CONFLICT_LABELS.theirs}`);
     }
     return { text: lines.join("\n"), conflict };
 }
+/** Merges base -> target into current. Resolves null for binary files, which cannot be merged. */
+export function mergeText(current, base, target) {
+    if (isBinary(current) || isBinary(base) || isBinary(target))
+        return null;
+    const split = (content) => normalize(content).split("\n");
+    const regions = diff3Merge(split(current), split(base), split(target), { excludeFalseConflicts: true });
+    return withMarkers(regions.flatMap((region) => region.ok ? [{ ok: region.ok }] : region.conflict ? [{ yours: region.conflict.a, theirs: region.conflict.b }] : []));
+}
+/**
+ * Merges a package.json by key (see package-json-merge.ts), so edits to different keys never
+ * conflict, and markers wrap only the lines of a key both sides changed differently. Resolves
+ * null when a side does not parse, for mergeText to merge it by line.
+ */
+export function mergePackageJsonText(current, base, target) {
+    const merged = mergePackageJson(normalize(current), normalize(base), normalize(target));
+    if (!merged)
+        return null;
+    return withMarkers(diffComm(merged.yours.split("\n"), merged.theirs.split("\n")).map((region) => region.common !== undefined ? { ok: region.common } : { yours: region.buffer1, theirs: region.buffer2 }));
+}
 function merged(path, current, base, target, binaryReason) {
-    const result = mergeText(current, base, target);
+    const result = (/(^|\/)package\.json$/.test(path) ? mergePackageJsonText(current, base, target) : null) ?? mergeText(current, base, target);
     if (!result)
         return { path, kind: "keep", reason: binaryReason, incoming: target };
     const content = withLineEndings(result.text, current);

package/dist/core/package-json-merge.js

@@ -0,0 +1,106 @@
+// package.json files merge by key instead of by line (#142), so edits to different keys never
+// conflict: a script the project adds after the Starter's, or an override next to one the
+// Starter adds. A key both sides changed to different values is a conflict. The merged file is
+// written twice, with your value for each such key and with the Starter's, and merge.ts puts
+// conflict markers around the lines where the two differ, which are that key's.
+/** A key both sides changed to different values; undefined is a side that removed it. */
+class Conflict {
+    yours;
+    theirs;
+    constructor(yours, theirs) {
+        this.yours = yours;
+        this.theirs = theirs;
+    }
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Conflict);
+const own = (object, key) => (Object.hasOwn(object, key) ? object[key] : undefined);
+/** Sets a key as data, so a key named __proto__ cannot change the object's prototype. */
+function set(object, key, value) {
+    Object.defineProperty(object, key, { value, enumerable: true, writable: true, configurable: true });
+}
+/** Equal JSON values; objects regardless of their key order. */
+function same(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((item, i) => same(item, b[i]));
+    if (isObject(a) && isObject(b)) {
+        const keys = Object.keys(a);
+        return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && same(a[key], b[key]));
+    }
+    return false;
+}
+/**
+ * One key's value: whoever changed it, or a conflict when both did, differently. Objects both
+ * changed merge key by key; arrays and scalars are single values. Undefined is a removed key.
+ */
+function merge(base, yours, theirs) {
+    if (same(yours, theirs) || same(base, theirs))
+        return yours;
+    if (same(base, yours))
+        return theirs;
+    if (isObject(yours) && isObject(theirs))
+        return mergeObjects(isObject(base) ? base : {}, yours, theirs);
+    return new Conflict(yours, theirs);
+}
+/**
+ * Your keys in your order; a key only the Starter has goes after the key it follows in the
+ * Starter's file, or first. At the root, `clubedge` (the provenance) is always the Starter's.
+ */
+function mergeObjects(base, yours, theirs, root = false) {
+    const order = Object.keys(yours);
+    let previous;
+    for (const key of Object.keys(theirs)) {
+        if (!order.includes(key))
+            order.splice(previous === undefined ? 0 : order.indexOf(previous) + 1, 0, key);
+        previous = key;
+    }
+    const result = {};
+    for (const key of order) {
+        const value = root && key === "clubedge" ? own(theirs, key) : merge(own(base, key), own(yours, key), own(theirs, key));
+        if (value !== undefined)
+            set(result, key, value);
+    }
+    return result;
+}
+/** The merged value with one side's value for each conflict. */
+function resolve(value, side) {
+    if (value instanceof Conflict)
+        return value[side];
+    if (!isObject(value))
+        return value;
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        const resolved = resolve(item, side);
+        if (resolved !== undefined)
+            set(result, key, resolved);
+    }
+    return result;
+}
+/**
+ * The file's indentation, as npm reads it: the whitespace before the first key, after the
+ * opening brace's line. A file on one line has none, and stays on one line.
+ */
+function indentation(text) {
+    return /^\s*\{\n([ \t]*)"/.exec(text)?.[1] ?? "";
+}
+/**
+ * Merges base -> target into current, all LF text. Resolves the result written with your value
+ * for each conflict and with the Starter's (equal when there are none), in your file's
+ * indentation and final newline; null when a side is not a JSON object, to merge by line.
+ */
+export function mergePackageJson(current, base, target) {
+    let parsed;
+    try {
+        parsed = [JSON.parse(current), JSON.parse(base), JSON.parse(target)];
+    }
+    catch {
+        return null;
+    }
+    const [yours, before, theirs] = parsed;
+    if (!isObject(yours) || !isObject(before) || !isObject(theirs))
+        return null;
+    const merged = mergeObjects(before, yours, theirs, true);
+    const write = (side) => JSON.stringify(resolve(merged, side), null, indentation(current)) + (current.endsWith("\n") ? "\n" : "");
+    return { yours: write("yours"), theirs: write("theirs") };
+}

package/dist/core/plan.js

@@ -238,6 +238,8 @@ function resolveModuleFiles(manifest, selection, stacks) {
     const keptPaths = new Set();
     const usedPackages = new Map();
     const offeredPackages = new Map();
+    const usedDependencies = new Set();
+    const offeredDependencies = new Set();
     const variantSources = new Set();
     /** Variant source path to the default file it replaces. */
     const replacements = new Map();
@@ -254,6 +256,11 @@ function resolveModuleFiles(manifest, selection, stacks) {
                 if (selected)
                     usedPackages.set(name, directory);
             }
+            for (const name of option.dependencies) {
+                offeredDependencies.add(name);
+                if (selected)
+                    usedDependencies.add(name);
+            }
             for (const [target, variant] of Object.entries(option.replace)) {
                 variantSources.add(variant);
                 if (selected)
@@ -303,9 +310,12 @@ function resolveModuleFiles(manifest, selection, stacks) {
     if (Object.keys(rename).length)
         scripts.rename = rename;
     const removedPackages = [...offeredPackages].filter(([name]) => !usedPackages.has(name));
+    // Registry packages only left-out options list go the way of left-out workspace packages:
+    // out of each app's package.json and the lockfile's importers.
+    const removedDependencies = [...offeredDependencies].filter((name) => !usedDependencies.has(name));
     return {
         scripts,
-        removedPackageNames: removedPackages.map(([name]) => name),
+        removedPackageNames: [...removedPackages.map(([name]) => name), ...removedDependencies],
         removedPackageDirectories: removedPackages.map(([, directory]) => directory),
         replacedTargets: new Set(replacements.values()),
         replacements,

package/dist/core/update.js

@@ -1,6 +1,6 @@
 // Changes an existing project from one generated state (base) to another (target): different
-// modules for add and remove, or a newer Starter for upgrade. The project's own edits survive
-// through a three-way merge, see merge.ts.
+// modules or apps for add and remove, or a newer Starter for upgrade. The project's own edits
+// survive through a three-way merge, see merge.ts.
 import { mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { customizeAppManifest } from "./customize.js";
@@ -14,15 +14,17 @@ export async function planUpdate(project, base, target) {
         source: side.source,
         manifest: side.manifest,
         identity: project.identity,
-        stacks: project.stacks,
+        stacks: side.stacks ?? project.stacks,
         modules: side.modules,
         cliVersion: side.cliVersion,
     });
     const before = await render(base);
     const after = await render(target);
-    // The lockfile and the local env files are handled on their own below.
-    const envFiles = [...after.envFiles, ...before.envFiles.filter(({ to }) => !after.envFiles.some((file) => file.to === to))];
-    const special = [LOCKFILE, ...envFiles.map(({ to }) => to)];
+    // The lockfile and the local env files are handled on their own below. The env file of an app
+    // the change removes is left as it is: it is the developer's, and Git ignores it.
+    const envFiles = after.envFiles;
+    const removedEnvFiles = before.envFiles.filter(({ to }) => !after.envFiles.some((file) => file.to === to));
+    const special = [LOCKFILE, ...[...envFiles, ...removedEnvFiles].map(({ to }) => to)];
     const strip = (files) => new Map([...files].filter(([path]) => !special.includes(path)));
     const baseFiles = strip(before.files);
     const targetFiles = strip(after.files);
@@ -80,7 +82,14 @@ export async function planUpdate(project, base, target) {
         const text = (files) => files.get(envFile.from)?.toString("utf8") ?? "";
         const local = current.get(envFile.to)?.toString("utf8");
         const update = local === undefined ? null : updateEnvFile(local, text(before.files), text(after.files));
-        return { path: envFile.to, update, changed: update !== null && update.text !== local };
+        const added = !before.envFiles.some(({ to }) => to === envFile.to);
+        const example = after.files.get(envFile.from);
+        return {
+            path: envFile.to,
+            update,
+            changed: update !== null && update.text !== local,
+            ...(local === undefined && added && example ? { create: example } : {}),
+        };
     });
     return { project, actions, lockfile, envs };
 }
@@ -137,5 +146,13 @@ export async function applyUpdate(plan) {
     for (const env of plan.envs) {
         if (env.update && env.changed)
             await writeFile(join(root, env.path), env.update.text);
+        if (env.create) {
+            await mkdir(dirname(join(root, env.path)), { recursive: true });
+            // An env file written since the plan was made is never replaced.
+            await writeFile(join(root, env.path), env.create, { flag: "wx" }).catch((error) => {
+                if (error.code !== "EEXIST")
+                    throw error;
+            });
+        }
     }
 }

package/dist/index.js

@@ -77,13 +77,12 @@ async function chooseStacks(manifest, requested, interactive) {
  * offered. Returns null when a prompt is cancelled.
  */
 async function chooseModules(manifest, stacks, requested, interactive) {
-    const unasked = Object.keys(manifest.modules).filter((id) => requested[id] === undefined);
+    // Modules with a choice for these apps: a module only a mobile app uses has one for a website.
+    const unasked = Object.keys(manifest.modules).filter((id) => requested[id] === undefined && moduleChoices(manifest, stacks, id, requested).length > 1);
     if (!interactive || unasked.length === 0)
         return requested;
     const customize = await confirm({
-        message: `Customize the included services (${Object.values(manifest.modules)
-            .map((module) => module.name.toLowerCase())
-            .join(", ")})?`,
+        message: `Customize the included services (${unasked.map((id) => manifest.modules[id].name.toLowerCase()).join(", ")})?`,
         initialValue: false,
     });
     if (isCancel(customize))
@@ -101,8 +100,13 @@ async function chooseModules(manifest, stacks, requested, interactive) {
                 // Modules answered later are checked when the plan is created.
                 return value === undefined || allowed.includes(value);
             }));
-        if (available.length === 0)
+        // With one option left, there is nothing to ask. It is still the answer: later modules'
+        // requirements check it, and the plan takes it rather than the default.
+        if (available.length < 2) {
+            if (available[0] !== undefined)
+                chosen[id] = available[0][0];
             continue;
+        }
         const value = await select({
             message: module.name,
             initialValue: available.some(([optionId]) => optionId === module.default)
@@ -259,7 +263,7 @@ async function createProject(args) {
     const directory = relative(process.cwd(), targetDirectory) || ".";
     const scripts = JSON.parse(await readFile(join(targetDirectory, "package.json"), "utf8")).scripts ?? {};
     const later = scripts.clubedge
-        ? `Change modules later with \`pnpm clubedge add\` or \`pnpm clubedge remove\`, and get Starter updates with \`pnpm clubedge upgrade\`.\n\n`
+        ? `Change modules and mobile apps later with \`pnpm clubedge add\` or \`pnpm clubedge remove\`, and get Starter updates with \`pnpm clubedge upgrade\`.\n\n`
         : "";
     outro(`Next steps:\n  cd ${directory}\n${migrate ? `  ${pnpmCommand} ${migrate}\n` : ""}  ${pnpmCommand} dev\n\n` +
         `See SETUP.md for database and provider configuration.\n\n` +
@@ -318,8 +322,8 @@ export async function main(argv = process.argv.slice(2)) {
         }
         else {
             const intros = {
-                add: "Add a module to this project",
-                remove: "Remove a module from this project",
+                add: "Add a module or an app to this project",
+                remove: "Remove a module or an app from this project",
                 upgrade: "Upgrade this project to a newer Starter",
             };
             intro(intros[args.command.name]);