@clubedge/create-clubedge-app 0.45.0 → 0.46.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.46.1
+
+- **Starter v0.30.1** by default (#167). Its template schema is still 6. The [Starter's release notes](https://github.com/Clubedge/clubedge-starter/releases/tag/v0.30.1) cover:
+  - the native app (`--mobile expo`) reaching its API again: since v0.29.0, each of its calls to the API threw after the API had answered, so the account never loaded, and saving a name or deleting the account failed;
+  - getting the fix to installed apps: a new build in the stores, then `APP_MINIMUM_VERSION` on the API, which sends older installs to the update screen, or an over-the-air update with `--ota eas`;
+  - end-to-end tests of both mobile apps on an Android emulator;
+  - Expo SDK 58's latest patch versions.
+
+## 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:

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.29.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.30.1
 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,9 +260,11 @@ 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.29.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.30.1 # 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.
@@ -274,6 +278,15 @@ The CLI renders the project twice, from the Starter commit and modules recorded
 
 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.
@@ -400,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.45.0
+create-clubedge-app v0.46.1
         |
         v
-Clubedge Starter v0.29.0
-commit 29350332db4bc44acc1e7b989c04825ff4c0f7b7
+Clubedge Starter v0.30.1
+commit 6d04531ffb2cd9f0e76b6e2b3b542f733b66aed6
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.45.0` | `clubedge-starter@v0.29.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.46.1` | `clubedge-starter@v0.30.1` | 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.29.0` tag is expected to resolve to commit
-`29350332db4bc44acc1e7b989c04825ff4c0f7b7`. The CLI verifies this before
+The `v0.30.1` tag is expected to resolve to commit
+`6d04531ffb2cd9f0e76b6e2b3b542f733b66aed6`. 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.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.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.30.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.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -475,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.29.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.30.1`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -531,6 +544,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 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/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]);