@clubedge/create-clubedge-app 0.43.1 → 0.45.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 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):
+  - Template schema 6 adds the `mobile` role: an app with its own screens that calls an API. Like a shell, it runs no server, so it has no Dockerfile or deployment, and `deploy` leaves it out. Older CLIs refuse a schema 6 Starter and ask for an update.
+  - It needs an API, `--api hono` or `--api fastapi`: with React + Vite, or without a website. Next.js and TanStack Start have no separate API for it to call, so they refuse `--mobile expo`. It can sit next to the Capacitor app (`--shell capacitor`).
+  - A mobile stack lists the module options it implements, and the others are refused with it: Expo signs in with Better Auth, Supabase, or nothing.
+  - Interactive runs ask about it after the framework and the API.
+  - The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.28.0) cover the app's screens, sign-in, update notice, and builds.
+- **Projects without a website** (#148): `--framework none --api hono` (or `fastapi`), with or without `--mobile expo`, creates an API, and the native app that calls it directly:
+  - Schema 6 slots can be optional. The project records `framework: none`, so `add`, `remove`, and `upgrade` keep it without a web app.
+  - A slot names the files and root scripts only its apps use, left out when it is empty, such as the browser tests, and the slot whose package the root scripts use instead, so `pnpm dev` starts the API.
+  - Templates list the selections they refuse, with the reason (`rules`). Prompts and `add` offer only what the rules allow, and a refused option fails with the reason. Without a website, the Starter refuses payments, Inngest, FastAPI with Better Auth, and deploy targets other than Docker and Railway.
+  - `deploy` publishes the API itself: as the public app behind Caddy with Docker Compose, or as one public service on Railway, with Better Auth's URL and secret. Vercel, Netlify, Fly.io, and Render deploy a web app, so they refuse a project without one, and `deploy --preview` refuses it with the Railway commands for a preview by hand.
+- **Audit exceptions per stack** (#150): a stack lists the advisories `pnpm audit` skips because of its dependencies (`auditIgnores`), and projects without the stack audit them again. The Starter's Expo stack skips two in Expo's development CLI that have no usable fix.
+- The showcase waits for the billing portal's subscription before recording it, so its video no longer ends on a spinner (#146).
+
 ## 0.43.1
 
 - **`try` shows Railway's reason when Railway refuses a VM** (#144):

package/README.md

@@ -102,7 +102,7 @@ pnpm dev
 
 Or start it with npm: `npx @clubedge/create-clubedge-app my-app`. The generated project is a pnpm workspace, so dependencies are installed with pnpm either way; the CLI falls back to `corepack pnpm` when `pnpm` is not on your path. Without a destination, the CLI asks where to create the project.
 
-The generated project includes `apps/web/.env.local` (and `apps/api/.env.local` with a separate API, `apps/shell/.env.local` with a mobile app), created from the example and pointing at the local services you chose. Its `SETUP.md` describes every variable and provider. The root route is a landing page named after your project, and the dashboard is at `/dashboard`.
+The generated project includes `apps/web/.env.local` (and `apps/api/.env.local` with a separate API, `apps/shell/.env.local` with a mobile shell, `apps/mobile/.env.local` with a native app), created from the example and pointing at the local services you chose. Its `SETUP.md` describes every variable and provider. The root route is a landing page named after your project, and the dashboard is at `/dashboard`.
 
 The default Starter release ships inside the CLI package, so GitHub is only contacted when you pass `--ref`. Internet access is needed to install dependencies.
 
@@ -145,18 +145,35 @@ With the Hono API, the decoupled stacks support every module option the full-sta
 
 ### A mobile app
 
-Since CLI 0.42.0, with Starter v0.27.0, the Vite frontend can also be packaged as an Android and iOS app with [Capacitor](https://capacitorjs.com). Earlier Starters have no mobile shell, and the CLI refuses `--shell` with them.
+A project can have a mobile app in two ways, and both at once:
+
+- **A shell** packages the Vite frontend as an Android and iOS app with [Capacitor](https://capacitorjs.com), so the app shows the same pages as the website (since CLI 0.42.0, with Starter v0.27.0).
+- **A native app** has its own screens, built with [Expo](https://expo.dev) and React Native, and calls the same API (since CLI 0.44.0, with Starter v0.28.0).
+
+Earlier Starters have neither, and the CLI refuses `--shell` and `--mobile` with them.
 
 ```sh
 pnpm dlx @clubedge/create-clubedge-app my-app --framework vite --api hono --shell capacitor
+pnpm dlx @clubedge/create-clubedge-app my-app --framework vite --api hono --mobile expo
 ```
 
-| Flag                | App                                                       | Where        |
-| ------------------- | --------------------------------------------------------- | ------------ |
-| `--shell capacitor` | The Vite app, packaged for Android and iOS with Capacitor | `apps/shell` |
-| `--shell none`      | No mobile app (the default)                               |              |
+| Flag                            | App                                                          | Where         |
+| ------------------------------- | ------------------------------------------------------------ | ------------- |
+| `--shell capacitor`             | The Vite app, packaged for Android and iOS with Capacitor    | `apps/shell`  |
+| `--mobile expo`                 | A native Android and iOS app with Expo, calling the same API | `apps/mobile` |
+| `--shell none`, `--mobile none` | No mobile app (the default)                                  |               |
+
+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.
+
+#### 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).
+
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app --framework none --api hono --mobile expo
+```
 
-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`). Next.js and TanStack Start render their pages on their own server, so they cannot be packaged: the CLI refuses `--shell` with them, and interactive runs only ask about a mobile app after a frontend and its API. The shell runs no server, so `deploy` deploys the frontend and the API as above and leaves it out.
+The app then calls the API at the API's own address. A project needs a web app or an API, so `--framework none` needs `--api`. The project records `framework: none`, so `add`, `remove`, and `upgrade` keep it without a web app, and the commands that manage env files leave `apps/web/.env.local` out. `deploy` publishes the API itself on Railway or with Docker Compose (see their sections below); Fly.io, Vercel, Netlify, and Render deploy a web app, so it refuses them for a project without one.
 
 ## Choosing modules
 
@@ -194,9 +211,10 @@ Usage:
   pnpm dlx @clubedge/create-clubedge-app upgrade [--ref <tag>]   (inside a project)
 
 Options:
-  --framework <id>        App framework, such as next or tanstack-start (or vite, a frontend)
+  --framework <id>        App framework, such as next or tanstack-start (or vite, a frontend, or none)
   --api <id>              A separate API for a frontend, such as hono or fastapi
   --shell <id>            A mobile app that packages a frontend, such as capacitor
+  --mobile <id>           A native mobile app that calls the API, such as expo
   --<module> <option>     A module option, such as --auth none; the Starter lists its modules
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
                           (upgrade: the Starter to upgrade to)
@@ -223,7 +241,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.27.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.29.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -242,15 +260,16 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 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.27.1 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.29.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` or `apps/shell/.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.
+- 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`.
@@ -322,7 +341,7 @@ pnpm clubedge deploy --env-file .env.staging      # with another file of product
 pnpm clubedge deploy --dry-run                    # show the plan, create nothing
 ```
 
-With [Railway's CLI](https://docs.railway.com/cli) (the installed `railway`, or `npx @railway/cli`) and your Railway login, it creates or reuses a project named after the package and the databases selected by the modules. Full-stack projects get one public app service. A Vite project gets two services: the frontend has the public `*.up.railway.app` domain, and the API stays private; the frontend's Node server (`node server.mjs`) forwards the API routes to it over Railway's private network. API variables, including `FRONTEND_URL`, go on the API service; `VITE_*` values go on the frontend service for its build. With Better Auth, the frontend's Node server runs auth: it gets the same `DATABASE_URL` as the API, a generated `BETTER_AUTH_SECRET`, the email settings, and `BETTER_AUTH_URL`, the public frontend URL both services use. Each service's unset variables are reported from its own env example. The API's migration command runs before the API release, and the frontend and API deployments are both awaited. Database variables are references to Railway's Postgres and Redis by default. Values from `.env.production` (or `--env-file`) take precedence; external database URLs stay external, and localhost URLs are ignored. `.railway/railway.ts` describes the selected service topology and health checks; `deploy` applies it and adds Railway's TypeScript SDK (`railway`) as a dev dependency. Commit the generated file and package changes. It needs Railway CLI 5.42.1 or newer. Running `deploy` again reuses the services, so it also adds variables and ships new releases. Railway bills usage on your plan.
+With [Railway's CLI](https://docs.railway.com/cli) (the installed `railway`, or `npx @railway/cli`) and your Railway login, it creates or reuses a project named after the package and the databases selected by the modules. Full-stack projects get one public app service. A project without a website (`--framework none`) also gets one, the API, with the public `*.up.railway.app` domain its mobile app calls, its migrations before each release, and, with Better Auth, which then runs in the API, a generated `BETTER_AUTH_SECRET` and its own public URL as `BETTER_AUTH_URL`. A Vite project gets two services: the frontend has the public `*.up.railway.app` domain, and the API stays private; the frontend's Node server (`node server.mjs`) forwards the API routes to it over Railway's private network. API variables, including `FRONTEND_URL`, go on the API service; `VITE_*` values go on the frontend service for its build. With Better Auth, the frontend's Node server runs auth: it gets the same `DATABASE_URL` as the API, a generated `BETTER_AUTH_SECRET`, the email settings, and `BETTER_AUTH_URL`, the public frontend URL both services use. Each service's unset variables are reported from its own env example. The API's migration command runs before the API release, and the frontend and API deployments are both awaited. Database variables are references to Railway's Postgres and Redis by default. Values from `.env.production` (or `--env-file`) take precedence; external database URLs stay external, and localhost URLs are ignored. `.railway/railway.ts` describes the selected service topology and health checks; `deploy` applies it and adds Railway's TypeScript SDK (`railway`) as a dev dependency. Commit the generated file and package changes. It needs Railway CLI 5.42.1 or newer. Running `deploy` again reuses the services, so it also adds variables and ships new releases. Railway bills usage on your plan.
 
 ### Deploy to Fly.io (experimental)
 
@@ -344,7 +363,7 @@ In a project with `--deploy render`, `pnpm clubedge deploy` uses Render's API. R
 
 In a project with `--deploy docker` (the default), `pnpm clubedge deploy` prepares the project for a server of your own and creates nothing anywhere else. It writes three files to commit:
 
-- `compose.yaml` runs each app's image behind [Caddy](https://caddyserver.com), the only service that publishes ports (80, and 443 over TCP and UDP): it serves `DOMAIN` over HTTPS, with certificates it obtains and renews by itself. A full-stack app (Next.js or TanStack Start) is one service, `web`, built from the root `Dockerfile`; a frontend and its API are two, the frontend `web`, which Caddy serves, and `api`, which stays on the Compose network behind the frontend's `/api` proxy. Each service has an image, `${IMAGE_PREFIX:-<project>}-<service>:${TAG:-latest}`, and its build: `docker compose up -d` pulls the released images when `IMAGE_PREFIX` points at GitHub's registry, and `--build` builds them on the server. The public URL defaults to `https://$DOMAIN`: Next.js also gets it as a build argument, and Better Auth on a Vite frontend as `BETTER_AUTH_URL`.
+- `compose.yaml` runs each app's image behind [Caddy](https://caddyserver.com), the only service that publishes ports (80, and 443 over TCP and UDP): it serves `DOMAIN` over HTTPS, with certificates it obtains and renews by itself. A full-stack app (Next.js or TanStack Start) is one service, `web`, built from the root `Dockerfile`; a frontend and its API are two, the frontend `web`, which Caddy serves, and `api`, which stays on the Compose network behind the frontend's `/api` proxy; without a website, `api` is the one service, which Caddy serves, and Better Auth in it gets `BETTER_AUTH_URL`. Each service has an image, `${IMAGE_PREFIX:-<project>}-<service>:${TAG:-latest}`, and its build: `docker compose up -d` pulls the released images when `IMAGE_PREFIX` points at GitHub's registry, and `--build` builds them on the server. The public URL defaults to `https://$DOMAIN`: Next.js also gets it as a build argument, and Better Auth on a Vite frontend as `BETTER_AUTH_URL`.
 - `Caddyfile`: every request for `DOMAIN` goes to the public app.
 - `.github/workflows/release-images.yml`: each published GitHub release builds every app's image for `linux/amd64` and `linux/arm64` and pushes it to `ghcr.io/<owner>/<repository>-<service>`, tagged with its version (`1.2.3`), `1.2`, and `latest`; run by hand on the default branch, it pushes `edge`. It never runs for tag pushes, so a deleted tag leaves no images behind. The values an image compiles in come from repository variables: `NEXT_PUBLIC_APP_URL` for Next.js, the `VITE_*` values for a Vite frontend.
 
@@ -354,7 +373,7 @@ Then point the domain's DNS A and AAAA records at the server, publish a release,
 # .env.production: DOMAIN=example.com, the app's variables, and, to run the released images,
 # IMAGE_PREFIX=ghcr.io/<owner>/<repository> (TAG=1.2.3 pins a release; latest otherwise)
 docker login ghcr.io                             # while the packages are private: a token with read:packages
-docker compose --env-file .env.production run --rm web node /app/migrate.mjs   # api for a frontend and its API
+docker compose --env-file .env.production run --rm web node /app/migrate.mjs   # api when the project has one
 docker compose --env-file .env.production up -d  # --build builds the images on the server
 ```
 
@@ -372,7 +391,7 @@ In a project that deploys to Vercel or Railway, `pnpm clubedge deploy --preview`
 NEON_API_KEY=... NEON_PROJECT_ID=... pnpm clubedge deploy --preview
 ```
 
-With `NEON_API_KEY` and `NEON_PROJECT_ID` (in the shell, or in the env file), the preview gets its own [Neon branch](https://neon.com/docs/introduction/branching), `preview/<git branch>`: a copy of the production database made in seconds that shares its storage until it changes. `deploy` creates it, or reuses it on later runs, applies this branch's migrations to it, and points the preview's `DATABASE_URL` and `DATABASE_URL_DIRECT` at it. On Vercel, the preview is a preview deployment with the project's Preview variables, and the branch's URLs are set as Preview variables of your Git branch, which needs the Vercel project connected to its Git repository; without the Neon settings, it uses the Preview `DATABASE_URL`. On Railway, it is an environment named `preview-<git branch>`, copied from production with its own domain; without the Neon settings, it gets its own empty copy of Railway's Postgres, and when production's database comes from elsewhere, `deploy --preview` refuses, since the copy would use production's data. Production is not changed. It deploys a single app for now: a Vite frontend and its API are two services, so `deploy --preview` refuses them and explains how to copy production's Railway environment yourself.
+With `NEON_API_KEY` and `NEON_PROJECT_ID` (in the shell, or in the env file), the preview gets its own [Neon branch](https://neon.com/docs/introduction/branching), `preview/<git branch>`: a copy of the production database made in seconds that shares its storage until it changes. `deploy` creates it, or reuses it on later runs, applies this branch's migrations to it, and points the preview's `DATABASE_URL` and `DATABASE_URL_DIRECT` at it. On Vercel, the preview is a preview deployment with the project's Preview variables, and the branch's URLs are set as Preview variables of your Git branch, which needs the Vercel project connected to its Git repository; without the Neon settings, it uses the Preview `DATABASE_URL`. On Railway, it is an environment named `preview-<git branch>`, copied from production with its own domain; without the Neon settings, it gets its own empty copy of Railway's Postgres, and when production's database comes from elsewhere, `deploy --preview` refuses, since the copy would use production's data. Production is not changed. It deploys a single web app for now: a Vite frontend and its API are two services, and a project without a website runs only its API, so `deploy --preview` refuses them and explains how to copy production's Railway environment yourself.
 
 Projects created with `--infra neon` also have `.github/workflows/preview.yml`, which does this for every pull request in CI: a Neon branch per pull request with its migrations, the schema diff as a comment, a Vercel or Railway preview, and cleanup when the pull request closes. The Starter's SETUP.md lists the secrets it needs.
 
@@ -381,27 +400,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.43.1
+create-clubedge-app v0.45.0
         |
         v
-Clubedge Starter v0.27.1
-commit 997d71d74775352d30dc2bb25017f46ef43f4fd8
+Clubedge Starter v0.29.0
+commit 29350332db4bc44acc1e7b989c04825ff4c0f7b7
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.43.1` | `clubedge-starter@v0.27.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.45.0` | `clubedge-starter@v0.29.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.27.1` tag is expected to resolve to commit
-`997d71d74775352d30dc2bb25017f46ef43f4fd8`. The CLI verifies this before
+The `v0.29.0` tag is expected to resolve to commit
+`29350332db4bc44acc1e7b989c04825ff4c0f7b7`. 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.27.1`. 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.29.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`.
 
@@ -409,7 +428,7 @@ Every generated project records its CLI version, Starter repository, Starter ref
 
 Each CLI release bundles one Starter release. When the release is built, `scripts/bundle-template.mjs` clones the pinned Starter tag, verifies that it resolves to the pinned commit, and copies its tracked files into the package (`template/` and `template.lock.json`). Running the CLI then needs no GitHub access for the default Starter.
 
-The Starter describes itself in `clubedge.template.json`: its app directory, site config, environment files, Docker image name, and files that stay out of generated projects. Schema 2 manifests also list each framework's app directory, environment example, and Dockerfile. The CLI moves the selected framework's app to `apps/web` (renaming its package to `@clubedge/web`), moves its environment example and Dockerfile to the project root, leaves the other frameworks out, and removes their entries from `pnpm-lock.yaml` so `pnpm install --frozen-lockfile` keeps working. Schema 3 adds `modules`: for each option, the workspace packages it uses, the files it owns, the variant files that replace defaults, the root `package.json` scripts it sets, and the options it requires. Files listed under `conditional` contain `clubedge:if <condition>` / `clubedge:end` blocks (in `#`, `//`, `<!-- -->`, or JSX comments) that the CLI keeps or drops for the selection, always removing the markers; `clubedge:if starter-repository` marks sections for Starter maintainers only. Schema 4 moves each app's description into its own stack pack, placed in a slot (`--framework`, `--api`), and schema 5 adds the shell role for a mobile app (`--shell`); see [docs/stack-packs.md](docs/stack-packs.md). The CLI refuses a Starter whose manifest schema is newer than it understands and asks you to update. Starters before v0.3.0 have no manifest and use the previous layout.
+The Starter describes itself in `clubedge.template.json`: its app directory, site config, environment files, Docker image name, and files that stay out of generated projects. Schema 2 manifests also list each framework's app directory, environment example, and Dockerfile. The CLI moves the selected framework's app to `apps/web` (renaming its package to `@clubedge/web`), moves its environment example and Dockerfile to the project root, leaves the other frameworks out, and removes their entries from `pnpm-lock.yaml` so `pnpm install --frozen-lockfile` keeps working. Schema 3 adds `modules`: for each option, the workspace packages it uses, the files it owns, the variant files that replace defaults, the root `package.json` scripts it sets, and the options it requires. Files listed under `conditional` contain `clubedge:if <condition>` / `clubedge:end` blocks (in `#`, `//`, `<!-- -->`, or JSX comments) that the CLI keeps or drops for the selection, always removing the markers; `clubedge:if starter-repository` marks sections for Starter maintainers only. Schema 4 moves each app's description into its own stack pack, placed in a slot (`--framework`, `--api`), schema 5 adds the shell role for a mobile app that packages the frontend (`--shell`), and schema 6 the mobile role for a native app (`--mobile`); see [docs/stack-packs.md](docs/stack-packs.md). The CLI refuses a Starter whose manifest schema is newer than it understands and asks you to update. Starters before v0.3.0 have no manifest and use the previous layout.
 
 The CLI first builds a plan (the files to copy and the edits to make), which `--dry-run` prints, and then applies it. The source is organized the same way:
 
@@ -456,7 +475,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.27.1`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.29.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -510,6 +529,8 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.41.0 | v0.26.0 | A conflicted package.json no longer breaks later commands (`--detailed-exit-code`); doctor finds conflict markers; projects own their version and README |
 | 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 |
 
 ## Community
 

package/dist/cli/ui.js

@@ -1,4 +1,5 @@
 import process from "node:process";
+import { isOptionalSlot } from "../core/manifest.js";
 import { NO_STACK, stacksIn } from "../core/plan.js";
 import { cliUrl, cliVersion, siteUrl, starterPin } from "../package-info.js";
 // Each glyph is 6 rows tall. Rows are padded to a common width when rendered.
@@ -72,7 +73,7 @@ export function selectionHelp(manifest) {
     }
     return [
         ...Object.entries(manifest.slots).flatMap(([id, slot]) => {
-            const stacks = [...stacksIn(manifest, id), ...(slot.default === undefined ? [NO_STACK] : [])];
+            const stacks = [...stacksIn(manifest, id), ...(isOptionalSlot(slot) ? [NO_STACK] : [])];
             return stacks.length > 1 ? [line(`--${id} <id>`, `${slot.name}: ${choices(stacks, slot.default ?? NO_STACK)}`)] : [];
         }),
         ...Object.entries(manifest.modules).map(([id, module]) => line(`--${id} <id>`, `${module.name}: ${choices(Object.keys(module.options), module.default)}`)),

package/dist/core/customize.js

@@ -21,7 +21,12 @@ function recordStacks(stacks) {
         ...(Object.keys(apps).length ? { apps } : {}),
     };
 }
-export function customizeRootManifest(source, { packageName, version = "0.1.0" }, provenance, dockerImage, scripts = { set: {}, remove: [] }) {
+/** A command with one package name replaced where it stands on its own, as in `--filter=<name>`. */
+function renamePackage(command, from, to) {
+    const escaped = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return command.replace(new RegExp(`(^|[\\s='"])${escaped}(?=$|[\\s'"])`, "g"), `$1${to}`);
+}
+export function customizeRootManifest(source, { packageName, version = "0.1.0" }, provenance, dockerImage, scripts = { set: {}, remove: [] }, droppedAdvisories = []) {
     const manifest = JSON.parse(source);
     manifest.name = packageName;
     manifest.version = version;
@@ -31,6 +36,23 @@ export function customizeRootManifest(source, { packageName, version = "0.1.0" }
     }
     if (Object.keys(scripts.set).length)
         manifest.scripts = { ...manifest.scripts, ...scripts.set };
+    for (const [from, to] of Object.entries(scripts.rename ?? {})) {
+        for (const [name, command] of Object.entries(manifest.scripts ?? {})) {
+            if (typeof command === "string")
+                manifest.scripts[name] = renamePackage(command, from, to);
+        }
+    }
+    // Advisories that only left-out stacks need are audited again; settings left empty go too.
+    const auditConfig = manifest.pnpm?.auditConfig;
+    if (droppedAdvisories.length && Array.isArray(auditConfig?.ignoreGhsas)) {
+        auditConfig.ignoreGhsas = auditConfig.ignoreGhsas.filter((id) => !droppedAdvisories.includes(id));
+        if (!auditConfig.ignoreGhsas.length)
+            delete auditConfig.ignoreGhsas;
+        if (!Object.keys(auditConfig).length)
+            delete manifest.pnpm.auditConfig;
+        if (!Object.keys(manifest.pnpm).length)
+            delete manifest.pnpm;
+    }
     manifest.clubedge = {
         cliVersion: provenance.cliVersion,
         starterRepository: provenance.starterRepository,
@@ -173,20 +195,24 @@ export class ConditionalError extends Error {
 const MARKER = /^\s*(?:\/\/|#|%%|<!--|\{?\/\*)\s*clubedge:(if|end)\b\s*(.*?)\s*(?:-->|\*\/\}?)?\s*$/;
 // A single line kept only when its condition holds: "- Item <!-- clubedge:only auth=supabase -->".
 const LINE_MARKER = /\s*(?:\/\/|#|<!--|\{?\/\*)\s*clubedge:only\s+(.+?)\s*(?:-->|\*\/\}?)?\s*$/;
+/** The parts of a condition such as `framework=none && payments!=none`, as markers and rules write them. */
+export function conditionParts(expression, location) {
+    return expression.split("&&").map((part) => {
+        const match = /^\s*([a-z][a-z0-9-]*)\s*(!?=)\s*([a-z0-9|-]+)\s*$/.exec(part);
+        if (!match)
+            throw new ConditionalError(`${location}: cannot read the condition "${expression}".`);
+        return { key: match[1], equals: match[2] === "=", values: match[3].split("|") };
+    });
+}
 function evaluateCondition(expression, selection, location) {
     // Maintainer-only sections of the Starter repository never reach a generated project.
     if (expression.trim() === "starter-repository")
         return false;
-    return expression.split("&&").every((part) => {
-        const match = /^\s*([a-z][a-z0-9-]*)\s*(!?=)\s*([a-z0-9|-]+)\s*$/.exec(part);
-        if (!match)
-            throw new ConditionalError(`${location}: cannot read the condition "${expression}".`);
-        const [, key, operator, values] = match;
+    return conditionParts(expression, location).every(({ key, equals, values }) => {
         const selected = selection[key];
         if (selected === undefined)
             throw new ConditionalError(`${location}: unknown key "${key}".`);
-        const matches = values.split("|").includes(selected);
-        return operator === "=" ? matches : !matches;
+        return values.includes(selected) === equals;
     });
 }
 /**

package/dist/core/deploy.js

@@ -188,6 +188,21 @@ export function planServicePair(input) {
     const unset = frontendKeys.filter((key) => set[key] === undefined && !existing.frontend[key] && !optional.includes(key));
     return { frontend: { set, unset }, api };
 }
+/**
+ * The variables of an API deployed without a web app, as the public service its mobile app calls.
+ * It gets what planVariables provides, with the platform's client-address settings. With Better
+ * Auth, which then runs in the API, BETTER_AUTH_URL is the API's public URL, unless the env file
+ * names another public one, and the secret is generated unless the service already has one.
+ */
+export function planApiAlone(input) {
+    const plan = planVariables(input);
+    const configured = input.envFile.BETTER_AUTH_URL;
+    if (input.modules.auth === "better-auth")
+        plan.set.BETTER_AUTH_URL = configured && !isLocalUrl(configured) ? configured : input.url;
+    // The image listens on every interface: its Dockerfile sets HOST.
+    plan.unset = plan.unset.filter((key) => plan.set[key] === undefined && key !== "HOST");
+    return plan;
+}
 /**
  * DATABASE_URL_DIRECT for a database hosted elsewhere: the env file's, or for a pooled Neon URL the
  * same URL without -pooler. Never next to the platform's own database (no external URL), where it
@@ -307,7 +322,8 @@ export const railwayIacPath = ".railway/railway.ts";
  * the variables stay managed by `deploy` and the dashboard, and the region is Railway's default.
  */
 export function railwayIacSource(service, services) {
-    if (services && Object.keys(services).length > 1) {
+    // A frontend and its API, or an API without a web app: each app builds its own Dockerfile.
+    if (services && Object.values(services).some(({ role }) => role !== "fullstack")) {
         const identifier = (slot) => slot.replace(/[^a-zA-Z0-9_$]/g, "_");
         const apiEntry = Object.entries(services).find(([, item]) => item.role === "api");
         const api = apiEntry?.[1];
@@ -651,10 +667,16 @@ export const fullstackService = {
     healthPath: "/api/health",
     platforms: ["docker"],
 };
-/** The service the public reaches: a frontend, whose API stays private, else the full-stack app. */
+/**
+ * The service the public reaches: a frontend, whose API stays private, else the full-stack app,
+ * else an API without a web app, which its mobile app calls directly.
+ */
 export function publicService(services) {
     const apps = Object.values(services);
-    return apps.find(({ role }) => role === "frontend") ?? apps.find(({ role }) => role === "fullstack") ?? fullstackService;
+    return (apps.find(({ role }) => role === "frontend") ??
+        apps.find(({ role }) => role === "fullstack") ??
+        apps.find(({ role }) => role === "api") ??
+        fullstackService);
 }
 /**
  * The values an app's image compiles in, which its Dockerfile takes as build arguments, from the
@@ -671,8 +693,8 @@ export function buildArgumentKeys(service, keys) {
  * ports: it serves DOMAIN over HTTPS, with certificates it obtains and renews. `frontendKeys` are
  * the variables the public app's env example lists: the values its image compiles in become build
  * arguments, and a frontend's others runtime variables, such as Better Auth's when the frontend's
- * server runs auth. Compose reads their values from its --env-file; the public URL defaults to
- * https://DOMAIN.
+ * server runs auth. For an API without a web app, the public app, they are the API's. Compose reads
+ * their values from its --env-file; the public URL defaults to https://DOMAIN.
  */
 export function dockerComposeSource(project, services, frontendKeys = []) {
     const apps = Object.values(services);
@@ -686,22 +708,27 @@ export function dockerComposeSource(project, services, frontendKeys = []) {
     // client-address settings default to Caddy's.
     const runtimeKeys = frontendKeys.filter((key) => !key.startsWith("VITE_") && !["API_URL", "PORT", ...clientAddressKeys].includes(key));
     // Better Auth runs in the frontend's server: the API asks it for the session over the Compose network.
-    const authUrl = api && frontendKeys.includes("BETTER_AUTH_URL") ? `http://${web.id}:${web.port}` : null;
+    const authUrl = api && api !== web && frontendKeys.includes("BETTER_AUTH_URL") ? `http://${web.id}:${web.port}` : null;
     const environment = (service) => {
+        // A frontend has no env_file: CLIENT_IP_HEADER from the env file needs a line of its own.
+        const address = [
+            "      # Caddy, the one proxy in front, sets X-Forwarded-For to the client's address.",
+            ...(service.role === "frontend" ? clientAddressKeys : Object.keys(behindCaddy)).map((key) => `      ${key}: ${fromEnv(key, behindCaddy[key])}`),
+        ];
         if (service.role === "api") {
+            // The API listens on every interface, whatever HOST the env file has from development.
+            if (service === web) {
+                // Without a web app, the API is the public app, and runs Better Auth itself.
+                const auth = frontendKeys.includes("BETTER_AUTH_URL") ? [`      BETTER_AUTH_URL: ${fromEnv("BETTER_AUTH_URL", publicUrl)}`] : [];
+                return ["      HOST: 0.0.0.0", ...address, ...auth];
+            }
             return [
-                // The API listens on every interface, whatever HOST the env file has from development.
                 "      HOST: 0.0.0.0",
                 `      # Reached only through ${web.id}, which passes on the client's address as the one X-Forwarded-For entry.`,
                 ...clientAddressKeys.map((key) => `      ${key}: ${JSON.stringify(behindWeb[key] ?? "")}`),
                 ...(authUrl ? [`      BETTER_AUTH_URL: ${authUrl}`] : []),
             ];
         }
-        // A frontend has no env_file: CLIENT_IP_HEADER from the env file needs a line of its own.
-        const address = [
-            "      # Caddy, the one proxy in front, sets X-Forwarded-For to the client's address.",
-            ...(service.role === "frontend" ? clientAddressKeys : Object.keys(behindCaddy)).map((key) => `      ${key}: ${fromEnv(key, behindCaddy[key])}`),
-        ];
         if (service.role !== "frontend")
             return [...appUrlKeys.map((key) => `      ${key}: ${fromEnv(key, publicUrl)}`), ...address];
         return [

package/dist/core/manifest-fields.js

@@ -4,7 +4,11 @@ export const MANIFEST_FILE = "clubedge.template.json";
 export class ManifestError extends Error {
     name = "ManifestError";
 }
-export const stackRoles = ["fullstack", "frontend", "api", "shell"];
+export const stackRoles = ["fullstack", "frontend", "api", "shell", "mobile"];
+/** The template schema each role came with: a Starter on an older schema is read without it. */
+export const roleSchema = { fullstack: 4, frontend: 4, api: 4, shell: 5, mobile: 6 };
+/** Whether a role's apps run a server: a shell and a mobile app are installed on devices instead. */
+export const runsServer = (role) => role !== "shell" && role !== "mobile";
 /**
  * The slot for the app itself. Starters before schema 4 call it the framework, and projects
  * record their choice for it as `framework`.