@clubedge/create-clubedge-app 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 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.9.0
         |
         v
-Clubedge Starter v0.7.0
-commit 3b8114760b8151c2538b57c06620ff2b884f2d56
+Clubedge Starter v0.8.0
+commit 0b77577a3fe77617c84e250d8b220169b72a297e
 ```
 
 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.9.0` | `clubedge-starter@v0.8.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.8.0` tag is expected to resolve to commit
+`0b77577a3fe77617c84e250d8b220169b72a297e`. 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.8.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
 
@@ -136,7 +136,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.8.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -145,9 +145,10 @@ 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
@@ -203,7 +204,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.8.0`, and publish the Starter release.
 
 ### CLI maintainers
 

package/dist/cli/args.js

@@ -86,15 +86,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

@@ -61,10 +61,13 @@ 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

package/dist/index.js

@@ -1,5 +1,6 @@
 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";
@@ -183,8 +184,13 @@ 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}`);
 }
 export async function main(argv = process.argv.slice(2)) {

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.9.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.8.0",
+    "starterCommit": "0b77577a3fe77617c84e250d8b220169b72a297e"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/README.md

@@ -169,6 +169,14 @@ Local services:
 - `pnpm infra:up`: run only the local database, for example for `pnpm check:services` or browser tests. <!-- clubedge:only infra=local -->
 - `pnpm infra:reset`: delete the local database and files in `.data/` (stop `pnpm dev` first). <!-- clubedge:only infra=local -->
 
+Change the project later:
+
+- `pnpm clubedge add <module> <option>`: add a module or switch its option, for example `pnpm clubedge add auth better-auth` or `pnpm clubedge add infra local`. Run `pnpm clubedge add` without arguments to choose from a list.
+- `pnpm clubedge remove <module>`: remove a module, for example `pnpm clubedge remove storage`.
+- `pnpm clubedge upgrade`: move the project to the newest Starter release.
+
+These commands merge the change into your code instead of overwriting it: files you never touched are updated, your edits are kept, and lines you both changed get conflict markers. Commit first, because they need a clean Git tree so that `git diff` shows the result. Add `--dry-run` to preview a change.
+
 <!-- clubedge:if starter-repository -->
 
 ## Working on this repository

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/web",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clubedge-starter-v1",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.9.0",
@@ -29,6 +29,7 @@
     "docker:build": "docker build -t clubedge-starter .",
     "docker:start": "docker run --rm -p 3000:3000 --env-file apps/web/.env.local clubedge-starter",
     "check:services": "pnpm --filter @clubedge/web check:services",
+    "clubedge": "pnpm dlx @clubedge/create-clubedge-app@latest",
     "infra:up": "docker compose -f docker-compose.dev.yml up -d --wait",
     "infra:down": "docker compose -f docker-compose.dev.yml down",
     "infra:reset": "docker compose -f docker-compose.dev.yml down --volumes",

package/template/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/auth-better-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-better-auth",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Better Auth adapter for @clubedge/auth, storing users and sessions in your own PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-supabase",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Supabase Auth adapter for @clubedge/auth.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/cache-redis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache-redis",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Redis rate limiter and cache for @clubedge/cache.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/db",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/local-db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/local-db",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "PostgreSQL for development without Docker: PGlite served over the PostgreSQL protocol.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/storage-s3/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-s3",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "S3-compatible adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-supabase",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Supabase Storage adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/ui",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template.lock.json

@@ -1,7 +1,7 @@
 {
   "repository": "Clubedge/clubedge-starter",
-  "ref": "v0.7.0",
-  "commit": "3b8114760b8151c2538b57c06620ff2b884f2d56",
+  "ref": "v0.8.0",
+  "commit": "0b77577a3fe77617c84e250d8b220169b72a297e",
   "files": [
     ".dockerignore",
     ".env.example",