@clubedge/create-clubedge-app 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.10.0
+
+- Default to Starter `v0.9.0`, which adds the email module (`--email smtp|resend|none`), password reset for both auth providers, and email verification for Better Auth. `--email` needs no CLI code: it comes from the Starter's manifest.
+- Fix a doubled blank line in `.env.local` when `add` or `remove` swaps one section of variables for another, such as switching `--email smtp` to `resend`.
+- Take module flags from the Starter's manifest: any `--<module> <option>` flag is accepted and validated against the modules the Starter describes, so new Starter modules need no CLI release. A mistyped module lists the Starter's modules; an unknown flag without a value is still an error.
+- Build the help text's framework and module lines, and the "customize the included services" prompt, from the Starter's manifest.
+
+## 0.9.0
+
+- Default to Starter `v0.8.0`, whose projects have a `clubedge` script: `pnpm clubedge add`, `remove`, and `upgrade`.
+- `add` and `remove` ask for the module and option when they are not given, offering only options the project can use. Without a terminal, missing arguments remain an error.
+- Messages suggest `pnpm clubedge ...` in projects with the `clubedge` script, and the outro after creating a project mentions it.
+- Test the CLI on Windows in CI: its checks and tests, and generated projects with a module change.
+
 ## 0.8.0
 
 - Add `add <module> <option>` and `remove <module>` to change the modules of an existing project. The CLI renders the project's recorded Starter commit with the current and the new selection and merges the difference into the project. Files you never changed are updated, your edits are kept, and lines both sides changed get conflict markers. The local env file keeps your values: only generated values follow the new selection, and new variables are added. A Git repository without uncommitted changes is required unless `--force` is passed, so the result can be reviewed and undone.

package/README.md

@@ -12,27 +12,27 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.8.0
+create-clubedge-app v0.10.0
         |
         v
-Clubedge Starter v0.7.0
-commit 3b8114760b8151c2538b57c06620ff2b884f2d56
+Clubedge Starter v0.9.0
+commit e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.8.0` | `clubedge-starter@v0.7.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.10.0` | `clubedge-starter@v0.9.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.7.0` tag is expected to resolve to commit
-`3b8114760b8151c2538b57c06620ff2b884f2d56`. The CLI verifies this before
+The `v0.9.0` tag is expected to resolve to commit
+`e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5`. 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.7.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.9.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.
 
 ## Requirements
 
@@ -85,13 +85,14 @@ Either way, the app lives in `apps/web` and uses the same shared packages, so th
 
 ### Choosing services
 
-Authentication, file storage, and caching are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries.
+Authentication, file storage, caching, email, and local infrastructure are modules. Each has a default, and anything you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The Starter's `clubedge.template.json` defines the modules, so a module a newer Starter adds gets its `--<module>` flag without a CLI change; `--help` lists the modules of the Starter this CLI release creates.
 
 | Flag        | Options                                    | Default    |
 | ----------- | ------------------------------------------ | ---------- |
 | `--auth`    | `supabase`, `better-auth`, `none`          | `supabase` |
 | `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
 | `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
+| `--email`   | `smtp` (any provider, or a local inbox), `resend`, `none` | `smtp` |
 | `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `none` | `docker` |
 
 ```sh
@@ -136,7 +137,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.7.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.9.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -145,14 +146,15 @@ 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 one module at a time, and `upgrade` moves the project to a newer Starter release:
+Inside a project created by the CLI, `add` and `remove` change one module at a time, 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:
 
 ```sh
+pnpm clubedge add                                            # choose a module and option from a list
 pnpm dlx @clubedge/create-clubedge-app add cache redis      # or switch: add auth better-auth
 pnpm dlx @clubedge/create-clubedge-app remove storage
 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.8.0  # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.9.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.
@@ -203,7 +205,7 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 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.7.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.9.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -217,7 +219,7 @@ The required CI job always tests the pinned default. The scheduled compatibility
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull request guidance. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and pull request guidance, and [ROADMAP.md](ROADMAP.md) for the planned phases. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
 
 ## License
 

package/dist/cli/args.js

@@ -1,32 +1,70 @@
 import { parseArgs } from "node:util";
-/** Module flags the CLI accepts. Which options exist is up to the Starter's manifest. */
-export const MODULE_FLAGS = ["auth", "storage", "cache", "infra"];
 export class UsageError extends Error {
     name = "UsageError";
 }
+/** The CLI's own long options; every other --name value flag selects a module option. */
+const OPTIONS = {
+    framework: { type: "string" },
+    ref: { type: "string" },
+    "template-dir": { type: "string" },
+    install: { type: "boolean", default: true },
+    git: { type: "boolean", default: true },
+    yes: { type: "boolean", short: "y", default: false },
+    "dry-run": { type: "boolean", default: false },
+    force: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+    version: { type: "boolean", short: "v", default: false },
+};
+const isOwnOption = (name) => name in OPTIONS || (name.startsWith("no-") && OPTIONS[name.slice(3)]?.type === "boolean");
+/**
+ * Takes module flags (`--email smtp` or `--email=smtp`) out of the arguments, leaving the CLI's
+ * own options for the strict parser. A flag that is neither needs a value, so a stray unknown
+ * flag such as --verbose is still reported.
+ */
+function extractModuleFlags(argv) {
+    const rest = [];
+    const modules = {};
+    for (let i = 0; i < argv.length; i++) {
+        const argument = argv[i];
+        if (argument === "--") {
+            rest.push(...argv.slice(i));
+            break;
+        }
+        const match = /^--([^=]+)(?:=(.*))?$/.exec(argument);
+        if (!match || isOwnOption(match[1])) {
+            rest.push(argument);
+            // A string option's value is never a flag of its own.
+            if (match && match[2] === undefined && OPTIONS[match[1]]?.type === "string") {
+                if (argv[i + 1] !== undefined)
+                    rest.push(argv[++i]);
+            }
+            continue;
+        }
+        const [, name, inline] = match;
+        if (!/^[a-z][a-z0-9-]*$/.test(name))
+            throw new UsageError(`Unknown option --${name}. Run with --help to see available options.`);
+        const next = argv[i + 1];
+        const value = inline ?? (next !== undefined && !next.startsWith("-") ? argv[++i] : undefined);
+        if (value === undefined) {
+            throw new UsageError(`Unknown option --${name}. Module flags take an option, such as --${name} none. Run with --help to see available options.`);
+        }
+        if (!value.trim())
+            throw new UsageError(`--${name} requires an option, such as none.`);
+        modules[name] = value.trim();
+    }
+    return { rest, modules };
+}
 export function parseCliArgs(argv) {
+    const { rest, modules } = extractModuleFlags(argv);
     let parsed;
     try {
         parsed = parseArgs({
-            args: argv,
+            args: rest,
             allowPositionals: true,
             allowNegative: true,
             strict: true,
             options: {
-                framework: { type: "string" },
-                auth: { type: "string" },
-                storage: { type: "string" },
-                cache: { type: "string" },
-                infra: { type: "string" },
-                ref: { type: "string" },
-                "template-dir": { type: "string" },
-                install: { type: "boolean", default: true },
-                git: { type: "boolean", default: true },
-                yes: { type: "boolean", short: "y", default: false },
-                "dry-run": { type: "boolean", default: false },
-                force: { type: "boolean", default: false },
-                help: { type: "boolean", short: "h", default: false },
-                version: { type: "boolean", short: "v", default: false },
+                ...OPTIONS,
             },
         });
     }
@@ -39,7 +77,7 @@ export function parseCliArgs(argv) {
     if (command.name === "create" && positionals.length > 1) {
         throw new UsageError("Only one project directory can be provided.");
     }
-    if (command.name !== "create" && (values.framework !== undefined || MODULE_FLAGS.some((id) => values[id]))) {
+    if (command.name !== "create" && (values.framework !== undefined || Object.keys(modules).length)) {
         throw new UsageError("--framework and module flags only apply when creating a project; use add or remove to change one module.");
     }
     if ((command.name === "add" || command.name === "remove") && values.ref !== undefined) {
@@ -48,15 +86,6 @@ export function parseCliArgs(argv) {
     if (values.framework !== undefined && !values.framework.trim()) {
         throw new UsageError("--framework requires a framework id, such as next or tanstack-start.");
     }
-    const modules = {};
-    for (const module of MODULE_FLAGS) {
-        const value = values[module];
-        if (value === undefined)
-            continue;
-        if (!value.trim())
-            throw new UsageError(`--${module} requires an option, such as none.`);
-        modules[module] = value.trim();
-    }
     if (values.ref !== undefined && !values.ref.trim()) {
         throw new UsageError("--ref requires a tag, branch, or commit.");
     }
@@ -86,15 +115,13 @@ export function parseCliArgs(argv) {
 function parseCommand(positionals) {
     const [name, module, option, ...extra] = positionals;
     if (name === "add") {
-        if (!module || !option || extra.length) {
-            throw new UsageError("Usage: add <module> <option>, for example: add cache redis");
-        }
+        if (extra.length)
+            throw new UsageError("Usage: add [module] [option], for example: add cache redis");
         return { name, module, option };
     }
     if (name === "remove") {
-        if (!module || option !== undefined) {
-            throw new UsageError("Usage: remove <module>, for example: remove storage");
-        }
+        if (option !== undefined)
+            throw new UsageError("Usage: remove [module], for example: remove storage");
         return { name, module };
     }
     if (name === "upgrade") {

package/dist/cli/ui.js

@@ -52,7 +52,32 @@ export function showBanner() {
     console.log(`  ${dim("By Clubedge")}  ${dim("·")}  ${paint(gradientFrom, siteUrl)}`);
     console.log("");
 }
-export function helpText() {
+/** "a (default), b, or c" */
+function choices(ids, defaultId) {
+    const labels = ids.map((id) => (id === defaultId ? `${id} (default)` : id));
+    return labels.length > 1 ? `${labels.slice(0, -1).join(", ")}${labels.length > 2 ? "," : ""} or ${labels.at(-1)}` : labels[0] ?? "";
+}
+/**
+ * The framework and module flags of a Starter, from its manifest, so new modules appear in the
+ * help without CLI changes. Without a manifest, a generic line explains module flags.
+ */
+export function selectionHelp(manifest) {
+    const line = (flag, text) => `  ${flag.padEnd(24)}${text}`;
+    if (!manifest) {
+        return [
+            line("--framework <id>", "App framework, such as next or tanstack-start"),
+            line("--<module> <option>", "A module option, such as --auth none; the Starter lists its modules"),
+        ].join("\n");
+    }
+    const frameworks = Object.keys(manifest.frameworks);
+    return [
+        ...(frameworks.length > 1
+            ? [line("--framework <id>", `App framework: ${choices(frameworks, manifest.defaultFramework)}`)]
+            : []),
+        ...Object.entries(manifest.modules).map(([id, module]) => line(`--${id} <id>`, `${module.name}: ${choices(Object.keys(module.options), module.default)}`)),
+    ].join("\n");
+}
+export function helpText(manifest = null) {
     return `
 create-clubedge-app ${cliVersion}
 
@@ -61,21 +86,20 @@ This CLI release scaffolds Starter ${starterPin.starterRef} (commit ${starterPin
 
 Usage:
   pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
-  pnpm dlx @clubedge/create-clubedge-app add <module> <option>   (inside a project)
-  pnpm dlx @clubedge/create-clubedge-app remove <module>         (inside a project)
+  pnpm dlx @clubedge/create-clubedge-app add [module] [option]   (inside a project)
+  pnpm dlx @clubedge/create-clubedge-app remove [module]         (inside a project)
   pnpm dlx @clubedge/create-clubedge-app upgrade [--ref <tag>]   (inside a project)
 
+  Inside a project with the clubedge script, use pnpm clubedge add, remove, or
+  upgrade. Without a module or option, add and remove ask for them.
+
   add and remove change one module of an existing project, and upgrade moves it
   to a newer Starter (this CLI's release unless --ref is given). 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.
 
 Options:
-  --framework <id>        App framework: next (default) or tanstack-start
-  --auth <id>             Authentication: supabase (default), better-auth, or none
-  --storage <id>          File storage: s3 (default), supabase, or none
-  --cache <id>            Cache and rate limits: redis (default) or memory
-  --infra <id>            Local services: docker (default), supabase, local, or none
+${selectionHelp(manifest)}
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
                           (upgrade: the Starter to upgrade to)
   --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)

package/dist/core/env.js

@@ -76,10 +76,17 @@ export function updateEnvFile(local, baseExample, targetExample) {
         while (anchor >= 0 && !keyOf(target[anchor]))
             anchor--;
         const position = anchor >= 0 ? find(lines, keyOf(target[anchor])) : -1;
-        if (position === -1)
+        if (position === -1) {
             appended.push(...commentsAbove(target, at), line);
-        else
-            lines.splice(position + 1, 0, ...target.slice(anchor + 1, at + 1));
+            return;
+        }
+        const between = target.slice(anchor + 1, at + 1);
+        // A removed section can leave its blank separator after the anchor; reuse it rather than
+        // adding a second one.
+        // The last element is the end of the file after its final newline, not a blank line.
+        const followedByBlank = position + 1 < lines.length - 1 && lines[position + 1].trim() === "";
+        const reuseBlank = between[0]?.trim() === "" && followedByBlank;
+        lines.splice(position + (reuseBlank ? 2 : 1), 0, ...(reuseBlank ? between.slice(1) : between));
     });
     let text = lines.join(eol);
     // Removed variables can leave blank lines in a row, as removed template blocks do.

package/dist/index.js

@@ -1,13 +1,14 @@
 import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
-import { relative, resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
 import process from "node:process";
 import { parseCliArgs, UsageError } from "./cli/args.js";
 import { dim, helpText, showBanner } from "./cli/ui.js";
 import { assertTargetIsUsable, executePlan } from "./core/execute.js";
 import { readTemplateManifest } from "./core/manifest.js";
 import { createPlan, describePlan, selectFramework } from "./core/plan.js";
-import { resolveTemplateSource } from "./core/source.js";
-import { cliUrl, cliVersion, siteUrl } from "./package-info.js";
+import { readBundledTemplate, resolveTemplateSource } from "./core/source.js";
+import { cliUrl, cliVersion, siteUrl, starterPin } from "./package-info.js";
 import { changeProject } from "./modify.js";
 import { initializeGit } from "./steps/git.js";
 import { detectLauncher, installDependencies, resolvePnpm } from "./steps/install.js";
@@ -62,7 +63,9 @@ async function chooseModules(manifest, requested, interactive) {
     if (!interactive || unasked.length === 0)
         return requested;
     const customize = await confirm({
-        message: "Customize the included services (auth, storage, cache, local infrastructure)?",
+        message: `Customize the included services (${Object.values(manifest.modules)
+            .map((module) => module.name.toLowerCase())
+            .join(", ")})?`,
         initialValue: false,
     });
     if (isCancel(customize))
@@ -183,10 +186,28 @@ 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`
+        : "";
     outro(`Next steps:\n  cd ${directory}\n  ${pnpmCommand} dev\n\n` +
         `See SETUP.md for database and provider configuration.\n\n` +
+        later +
         `${dim("Docs")}     ${cliUrl}\n${dim("Clubedge")} ${siteUrl}`);
 }
+/** The bundled Starter's manifest, for the help text; null in a checkout without a bundle. */
+async function bundledManifest() {
+    try {
+        const bundled = await readBundledTemplate();
+        // A checkout can hold an older bundle; only the pinned release describes what this CLI creates.
+        if (!bundled || bundled.commit !== starterPin.starterCommit)
+            return null;
+        return await readTemplateManifest(bundled.root);
+    }
+    catch {
+        return null;
+    }
+}
 export async function main(argv = process.argv.slice(2)) {
     try {
         const args = parseCliArgs(argv);
@@ -196,7 +217,7 @@ export async function main(argv = process.argv.slice(2)) {
         }
         showBanner();
         if (args.help) {
-            console.log(helpText());
+            console.log(helpText(await bundledManifest()));
             return;
         }
         assertSupportedNode();

package/dist/modify.js

@@ -1,7 +1,9 @@
 // `add`, `remove`, and `upgrade` change an existing project. The project's recorded Starter
 // commit and modules (base) and the new state (target: other modules, or a newer Starter) are
 // rendered in memory, and the difference is merged into the project (see core/update.ts).
-import { confirm, isCancel, log, outro, spinner } from "@clack/prompts";
+import { confirm, isCancel, log, outro, select, spinner } from "@clack/prompts";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
 import process from "node:process";
 import { UsageError } from "./cli/args.js";
 import { dim } from "./cli/ui.js";
@@ -13,6 +15,18 @@ import { applyUpdate, planUpdate } from "./core/update.js";
 import { cliVersion, starterPin } from "./package-info.js";
 import { installDependencies, resolvePnpm } from "./steps/install.js";
 import { commandSucceeds, runCapture } from "./utils/process.js";
+/** How to run the CLI in this project: its `clubedge` script when it has one. */
+async function cliCommand(project) {
+    try {
+        const manifest = JSON.parse(await readFile(join(project.root, "package.json"), "utf8"));
+        if (manifest.scripts?.clubedge)
+            return "pnpm clubedge";
+    }
+    catch {
+        // Fall back to the full command below.
+    }
+    return "pnpm dlx @clubedge/create-clubedge-app";
+}
 /** The Starter revision the project was generated from. */
 async function projectSource(project, templateDir) {
     if (templateDir)
@@ -62,8 +76,66 @@ async function assertSafeToChange(project, args, interactive) {
     if (isCancel(proceed) || !proceed)
         throw new UsageError("Cancelled; nothing was changed.");
 }
+/** Whether an option's requirements hold for the project's other modules. */
+function available(manifest, project, moduleId, optionId) {
+    const option = manifest.modules[moduleId].options[optionId];
+    return Object.entries(option.requires).every(([other, allowed]) => allowed.includes(project.modules[other] ?? ""));
+}
+/**
+ * Asks for whatever add or remove was not given: the module, then the option. Without a
+ * terminal, the missing arguments are an error. Resolves null when a prompt is cancelled.
+ */
+export async function completeCommand(manifest, project, command, interactive) {
+    if (command.name === "add" && command.module && command.option) {
+        return { name: "add", module: command.module, option: command.option };
+    }
+    if (command.name === "remove" && command.module)
+        return { name: "remove", module: command.module };
+    if (!interactive) {
+        throw new UsageError(command.name === "add"
+            ? "Usage: add <module> <option>, for example: add cache redis. Run it in a terminal to choose from a list."
+            : "Usage: remove <module>, for example: remove storage. Run it in a terminal to choose from a list.");
+    }
+    let moduleId = command.module;
+    if (!moduleId) {
+        const choices = Object.entries(manifest.modules).filter(([id, module]) => command.name === "add" ? true : Boolean(module.options.none) && project.modules[id] !== "none");
+        if (!choices.length)
+            throw new UsageError("No module can be removed: every removable module is already none.");
+        const value = await select({
+            message: command.name === "add" ? "Which module do you want to add or switch?" : "Which module do you want to remove?",
+            options: choices.map(([id, module]) => ({
+                value: id,
+                label: module.name,
+                hint: `now: ${module.options[project.modules[id] ?? ""]?.name ?? project.modules[id] ?? "not set"}`,
+            })),
+        });
+        if (isCancel(value))
+            return null;
+        moduleId = value;
+    }
+    if (command.name === "remove")
+        return { name: "remove", module: moduleId };
+    const module = manifest.modules[moduleId];
+    if (!module) {
+        throw new UsageError(`Unknown module "${moduleId}". Choose one of: ${Object.keys(manifest.modules).join(", ")}.`);
+    }
+    const options = Object.keys(module.options).filter((id) => id !== project.modules[moduleId] && available(manifest, project, moduleId, id));
+    if (!options.length)
+        throw new UsageError(`${module.name} has no other option this project can use.`);
+    const option = await select({
+        message: `${module.name}: which option?`,
+        options: options.map((id) => ({
+            value: id,
+            label: module.options[id].name,
+            ...(id === module.default ? { hint: "default" } : {}),
+        })),
+    });
+    if (isCancel(option))
+        return null;
+    return { name: "add", module: moduleId, option };
+}
 /** The selection after add or remove, validated against the Starter's manifest. */
-function changedModules(manifest, project, command) {
+function changedModules(manifest, project, command, cli) {
     const module = manifest.modules[command.module];
     if (!module) {
         throw new UsageError(`Unknown module "${command.module}". Choose one of: ${Object.keys(manifest.modules).join(", ")}.`);
@@ -78,7 +150,7 @@ function changedModules(manifest, project, command) {
     else {
         if (!module.options.none) {
             const others = Object.keys(module.options).filter((id) => id !== project.modules[command.module]);
-            throw new UsageError(`${module.name} cannot be removed. Switch it instead, for example: add ${command.module} ${others[0] ?? module.default}`);
+            throw new UsageError(`${module.name} cannot be removed. Switch it instead, for example: ${cli} add ${command.module} ${others[0] ?? module.default}`);
         }
         option = "none";
     }
@@ -89,7 +161,7 @@ function changedModules(manifest, project, command) {
  * The project's selection in a newer Starter. Modules the project predates get their "none"
  * option where there is one, so an upgrade never adds a service on its own.
  */
-export function upgradedModules(manifest, project) {
+export function upgradedModules(manifest, project, cli = "pnpm clubedge") {
     const requested = {};
     const introduced = [];
     for (const [id, module] of Object.entries(manifest.modules)) {
@@ -99,7 +171,7 @@ export function upgradedModules(manifest, project) {
             introduced.push(id);
         }
         else if (!module.options[recorded]) {
-            throw new UsageError(`The new Starter no longer offers ${module.name} "${recorded}". Choose one of: ${Object.keys(module.options).join(", ")}, with add ${id} <option>, before upgrading.`);
+            throw new UsageError(`The new Starter no longer offers ${module.name} "${recorded}". Switch to one of ${Object.keys(module.options).join(", ")} with ${cli} add ${id} <option> before upgrading.`);
         }
         else {
             requested[id] = recorded;
@@ -154,11 +226,10 @@ function report(plan) {
     }
 }
 /** Works out what the command changes; resolves null when the project is already there. */
-async function planChange(project, command, base, target) {
-    const baseManifest = await readTemplateManifest(base.root);
+async function planChange(project, command, base, baseManifest, target, cli) {
     const baseSide = { source: asRecorded(base, project), manifest: baseManifest, modules: project.modules, cliVersion: project.cliVersion };
     if (command.name !== "upgrade") {
-        const modules = changedModules(baseManifest, project, command);
+        const modules = changedModules(baseManifest, project, command, cli);
         const changed = Object.keys(modules).filter((id) => modules[id] !== project.modules[id]);
         if (!changed.length)
             return null;
@@ -177,11 +248,11 @@ async function planChange(project, command, base, target) {
     if (target.commit && target.commit === project.starterCommit)
         return null;
     const targetManifest = await readTemplateManifest(target.root);
-    const { modules, introduced, dropped } = upgradedModules(targetManifest, project);
+    const { modules, introduced, dropped } = upgradedModules(targetManifest, project, cli);
     const notes = [
         ...introduced.map((id) => {
             const module = targetManifest.modules[id];
-            return `Starter ${target.ref} adds ${module.name}; the project uses "${modules[id]}". Choose another option with: add ${id} <option>`;
+            return `Starter ${target.ref} adds ${module.name}; the project uses "${modules[id]}". Choose another option with: ${cli} add ${id} <option>`;
         }),
         ...dropped.map((id) => `Starter ${target.ref} no longer has the ${id} module; its files are merged away like any other change.`),
     ];
@@ -214,14 +285,20 @@ export async function changeProject(args) {
         const target = upgrading ? await upgradeSource(args) : null;
         if (target)
             sources.push(target);
-        const change = await planChange(project, command, base, target);
+        const baseManifest = await readTemplateManifest(base.root);
+        progress.stop("Starter ready");
         spinning = false;
+        const cli = await cliCommand(project);
+        const complete = command.name === "upgrade" ? command : await completeCommand(baseManifest, project, command, interactive);
+        if (!complete) {
+            outro("Cancelled; nothing was changed.");
+            return;
+        }
+        const change = await planChange(project, complete, base, baseManifest, target, cli);
         if (!change) {
-            progress.stop("Starter ready");
             outro(upgrading ? `The project is already on Starter ${project.starterRef}.` : "The project already uses that selection; nothing to change.");
             return;
         }
-        progress.stop("Starter ready");
         const plan = await planUpdate(project, change.base, change.target);
         log.message(`${change.summary}\n\n${describe(plan) || "No file changes."}`);
         if (args.dryRun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.7.0",
-    "starterCommit": "3b8114760b8151c2538b57c06620ff2b884f2d56"
+    "starterRef": "v0.9.0",
+    "starterCommit": "e858d0b5b60bbb05f1b6aed3f4d9e841ea2df2a5"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -22,6 +22,8 @@ NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
 # Better Auth keeps users and sessions in DATABASE_URL (run pnpm db:migrate first).
 # Generate a secret with: openssl rand -base64 32
 BETTER_AUTH_SECRET=
+# true refuses sign-in until the email address is confirmed through the emailed link. # clubedge:only email!=none
+BETTER_AUTH_REQUIRE_EMAIL_VERIFICATION=false # clubedge:only email!=none
 # clubedge:end
 
 # clubedge:if cache=redis
@@ -31,6 +33,24 @@ REDIS_URL= # clubedge:only infra!=docker
 REDIS_URL=redis://localhost:6379 # clubedge:only infra=docker
 # clubedge:end
 
+# clubedge:if email=smtp
+# Email over SMTP: any provider's SMTP endpoint (smtps:// for TLS). Without it, development
+# prints emails to the server log and production refuses to send.
+SMTP_URL= # clubedge:only infra!=docker|supabase
+# Mailpit from docker-compose.dev.yml; read the emails at http://localhost:8025. # clubedge:only infra=docker
+SMTP_URL=smtp://localhost:1025 # clubedge:only infra=docker
+# The local Supabase inbox; read the emails at http://127.0.0.1:54324. # clubedge:only infra=supabase
+SMTP_URL=smtp://127.0.0.1:54325 # clubedge:only infra=supabase
+EMAIL_FROM=App <no-reply@example.com>
+# clubedge:end
+
+# clubedge:if email=resend
+# Resend (https://resend.com). EMAIL_FROM must use a domain verified in Resend. Without the
+# key, development prints emails to the server log and production refuses to send.
+RESEND_API_KEY=
+EMAIL_FROM=App <no-reply@example.com>
+# clubedge:end
+
 # clubedge:if storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
 STORAGE_BUCKET= # clubedge:only infra!=docker