@clubedge/create-clubedge-app 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.16.0
+
+- Default to Starter `v0.14.0`, which adds:
+  - An account settings page at `/settings` when an auth provider is selected: display name, password change (signing out other sessions), and account deletion. Supabase projects set `SUPABASE_SECRET_KEY` to allow deletion.
+  - Browser error reporting with observability on: uncaught errors, unhandled rejections, and render errors caught by the new error pages, through `/api/client-errors` (`otel`) or Sentry's browser SDK (`sentry`). Sentry builds with `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` upload source maps and then delete them.
+  - Auth emails sent through the background-jobs queue, with retries, when both email and jobs are selected.
+- None of this needs CLI code: it all comes from the Starter's manifest.
+
+## 0.15.0
+
+- Add `status`: a project's Starter release, framework, modules, and Git state, whether a newer Starter release exists (from npm, still working offline), and the command to run next.
+- Add `doctor`: checks Node.js and pnpm against the project's versions, installed dependencies, the lockfile, and the env file against the example, then runs `pnpm check:services` (`--no-services` skips it). It exits with an error when a check fails.
+- `add` and `remove` take several modules (`add email resend payments stripe`, `remove storage payments`) and apply them as one change, checking requirements after every change.
+- After a change with conflicts, list each file with its number of conflict blocks.
+- `upgrade` lists the Starter releases it crosses, with the sections of their release notes.
+- Fix a finished command exiting with an error when Windows briefly locked the downloaded Starter's temporary folder.
+- CI: test generated projects on macOS too; the release workflow waits up to 15 minutes for npm.
+
 ## 0.14.1
 
 - Default to Starter `v0.13.1`. In projects with background jobs or observability, a configuration error such as a missing `DATABASE_URL` no longer stops the server at startup; pages that need no database keep working, and the error is reported once.

package/README.md

@@ -95,8 +95,8 @@ Interactive runs ask whether to customize these after the framework question.
 ```text
 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)
 
 Options:
@@ -127,7 +127,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.13.1
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.14.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -136,15 +136,17 @@ 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. 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:
+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:
 
 ```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 clubedge add email resend payments stripe              # several modules as one change
+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.13.1 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.14.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.
@@ -155,34 +157,47 @@ The CLI renders the project twice, from the Starter commit and modules recorded
 - `apps/web/.env.local` 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`.
+
 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.
 
+## Check a project
+
+Two read-only commands help you keep a project healthy:
+
+```sh
+pnpm clubedge status    # Starter release, modules, Git state, and whether a newer Starter exists
+pnpm clubedge doctor    # Node.js, pnpm, dependencies, lockfile, env file, and pnpm check:services
+```
+
+`status` ends with the command to run next, such as `pnpm clubedge upgrade` when a newer Starter release is available; it asks npm for the newest CLI and still works offline. `doctor` checks that Node.js and pnpm meet the project's versions, that dependencies are installed, that `pnpm-lock.yaml` matches every `package.json`, and that `apps/web/.env.local` has every variable in `.env.example`, then runs `pnpm check:services` (skip it with `--no-services`). It exits with an error when a check fails, so it also works in CI.
+
 ## Version relationship
 
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.14.1
+create-clubedge-app v0.16.0
         |
         v
-Clubedge Starter v0.13.1
-commit 28bfbf98c85ae500ace6a062dd10d67746e1a330
+Clubedge Starter v0.14.0
+commit 2219a21c2eb237b7d8ee004ea8bbeb098b70106e
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.14.1` | `clubedge-starter@v0.13.1` | The CLI's required, tested default |
+| `create-clubedge-app@0.16.0` | `clubedge-starter@v0.14.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.13.1` tag is expected to resolve to commit
-`28bfbf98c85ae500ace6a062dd10d67746e1a330`. The CLI verifies this before
+The `v0.14.0` tag is expected to resolve to commit
+`2219a21c2eb237b7d8ee004ea8bbeb098b70106e`. 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.13.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.14.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`.
 
@@ -208,6 +223,7 @@ src/
 | --- | --- |
 | Configure a generated project | Its `SETUP.md`, also in the [Starter repository](https://github.com/Clubedge/clubedge-starter/blob/main/SETUP.md) |
 | Change modules or upgrade a project | [Change an existing project](#change-an-existing-project) |
+| See where a project stands, or why it does not run | [Check a project](#check-a-project) |
 | Reproduce an exact Starter version | [Version relationship](#version-relationship) |
 | See what changed in each release | [CHANGELOG.md](CHANGELOG.md) |
 | See what is planned next | [ROADMAP.md](ROADMAP.md) |
@@ -236,7 +252,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.13.1`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.14.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -260,7 +276,9 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.12.0 | v0.11.0 | Payments |
 | 0.13.0 | v0.12.0 | Background jobs |
 | 0.14.0 | v0.13.0 | Observability |
-| next | | `status` and `doctor` commands, several modules in one change, macOS CI |
+| 0.15.0 | v0.13.1 | `status` and `doctor`, several modules in one change, conflict and upgrade summaries, macOS CI |
+| 0.16.0 | v0.14.0 | Account settings page, browser error reporting and Sentry source maps, auth emails through the jobs queue |
+| next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community
 

package/dist/cli/args.js

@@ -12,6 +12,7 @@ const OPTIONS = {
     yes: { type: "boolean", short: "y", default: false },
     "dry-run": { type: "boolean", default: false },
     force: { type: "boolean", default: false },
+    services: { type: "boolean", default: true },
     help: { type: "boolean", short: "h", default: false },
     version: { type: "boolean", short: "v", default: false },
 };
@@ -78,9 +79,9 @@ export function parseCliArgs(argv) {
         throw new UsageError("Only one project directory can be provided.");
     }
     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.");
+        throw new UsageError("--framework and module flags only apply when creating a project; use add or remove to change modules.");
     }
-    if ((command.name === "add" || command.name === "remove") && values.ref !== undefined) {
+    if (command.name !== "create" && command.name !== "upgrade" && values.ref !== undefined) {
         throw new UsageError("--ref only applies when creating or upgrading a project.");
     }
     if (values.framework !== undefined && !values.framework.trim()) {
@@ -104,25 +105,42 @@ export function parseCliArgs(argv) {
         yes: values.yes,
         dryRun: values["dry-run"],
         force: values.force,
+        services: values.services,
         help: values.help,
         version: values.version,
     };
 }
+function assertDistinct(modules) {
+    const repeated = modules.find((module, index) => modules.indexOf(module) !== index);
+    if (repeated)
+        throw new UsageError(`The module "${repeated}" is named more than once.`);
+}
 /**
- * `add <module> <option>`, `remove <module>`, and `upgrade` change an existing project; anything
- * else is the directory of a new project. Create a project literally named "add" with `./add`.
+ * `add <module> <option>...`, `remove <module>...`, and `upgrade` change an existing project, and `status`
+ * and `doctor` inspect one; anything else is the directory of a new project. Create a project
+ * literally named "add" with `./add`.
  */
 function parseCommand(positionals) {
-    const [name, module, option, ...extra] = positionals;
+    const [name, ...rest] = positionals;
+    const module = rest[0];
     if (name === "add") {
-        if (extra.length)
-            throw new UsageError("Usage: add [module] [option], for example: add cache redis");
-        return { name, module, option };
+        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");
+        }
+        const changes = rest.length === 1
+            ? [{ module: rest[0] }]
+            : Array.from({ length: rest.length / 2 }, (_, i) => ({ module: rest[2 * i], option: rest[2 * i + 1] }));
+        assertDistinct(changes.map((change) => change.module));
+        return { name, changes };
     }
     if (name === "remove") {
-        if (option !== undefined)
-            throw new UsageError("Usage: remove [module], for example: remove storage");
-        return { name, module };
+        assertDistinct(rest);
+        return { name, modules: rest };
+    }
+    if (name === "status" || name === "doctor") {
+        if (module !== undefined)
+            throw new UsageError(`Usage: ${name}, run inside a project.`);
+        return { name };
     }
     if (name === "upgrade") {
         if (module !== undefined)

package/dist/cli/ui.js

@@ -86,17 +86,24 @@ 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)
+  pnpm dlx @clubedge/create-clubedge-app status                  (inside a project)
+  pnpm dlx @clubedge/create-clubedge-app doctor                  (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.
+  Inside a project with the clubedge script, use pnpm clubedge add, remove,
+  upgrade, status, or doctor. 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.
+  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
+  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.
+
+  status shows the project's Starter release, modules, and Git state, and whether a
+  newer Starter is available. doctor checks Node.js, pnpm, the dependencies, the
+  lockfile, and the env file, then runs pnpm check:services; it changes nothing.
 
 Options:
 ${selectionHelp(manifest)}
@@ -105,6 +112,7 @@ ${selectionHelp(manifest)}
   --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
   --dry-run               Show what would be created or changed without writing anything
   --force                 add/remove: change a project with uncommitted changes or without Git
+  --no-services           doctor: skip pnpm check:services
   -y, --yes               Accept defaults and never prompt (default directory: my-app)
   --no-install            Skip dependency installation
   --no-git                Skip Git repository initialization
@@ -119,8 +127,11 @@ Examples:
   pnpm dlx @clubedge/create-clubedge-app my-app --ref main
   pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter
   pnpm dlx @clubedge/create-clubedge-app add auth better-auth
+  pnpm dlx @clubedge/create-clubedge-app add email resend payments stripe
   pnpm dlx @clubedge/create-clubedge-app remove storage --dry-run
   pnpm dlx @clubedge/create-clubedge-app@latest upgrade
+  pnpm clubedge status
+  pnpm clubedge doctor --no-services
 
 Learn more:
   CLI      ${cliUrl}

package/dist/core/env.js

@@ -4,6 +4,10 @@
 const LINE = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
 const COMMENT = /^\s*#/;
 const keyOf = (line) => LINE.exec(line)?.[1];
+/** The variable names an env file sets, in order. */
+export function envKeys(text) {
+    return text.split(/\r?\n/).flatMap((line) => keyOf(line) ?? []);
+}
 const valueOf = (line) => LINE.exec(line)[2].replace(/\s+#.*$/, "").trim();
 const find = (lines, key) => lines.findIndex((line) => keyOf(line) === key);
 function values(lines) {

package/dist/core/health.js

@@ -0,0 +1,161 @@
+// Pure checks behind `status` and `doctor`: they take what the commands read from the project,
+// the system, and npm, and return what to show, so each can be tested without a real project.
+import { envKeys } from "./env.js";
+/** Compares dotted versions such as "v0.13.1" and "0.12.0"; null when either is not one. */
+export function compareVersions(a, b) {
+    const parse = (value) => {
+        const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(value.trim());
+        return match ? match.slice(1).map(Number) : null;
+    };
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (left[i] !== right[i])
+            return left[i] - right[i];
+    }
+    return 0;
+}
+const REGISTRY_URL = "https://registry.npmjs.org/@clubedge%2fcreate-clubedge-app/latest";
+/**
+ * The newest published CLI and the Starter release it is pinned to, from npm. Resolves null when
+ * npm cannot be reached in time, so status still works offline.
+ */
+export async function fetchLatestRelease(fetcher = fetch, timeoutMs = 4_000) {
+    try {
+        const response = await fetcher(REGISTRY_URL, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return null;
+        const latest = (await response.json());
+        if (typeof latest.version !== "string" || typeof latest.clubedge?.starterRef !== "string")
+            return null;
+        return { cliVersion: latest.version, starterRef: latest.clubedge.starterRef };
+    }
+    catch {
+        return null;
+    }
+}
+export function updateState(projectRef, latest) {
+    if (!latest)
+        return { kind: "unknown" };
+    const difference = compareVersions(latest.starterRef, projectRef);
+    if (difference === null)
+        return { kind: "unknown" };
+    return difference > 0 ? { kind: "available", ...latest } : { kind: "current" };
+}
+/** The command that runs the newest CLI in this project. */
+export function latestCliCommand(cli) {
+    return cli === "pnpm clubedge" ? cli : "pnpm dlx @clubedge/create-clubedge-app@latest";
+}
+/** What to do next, given the working tree and whether a newer Starter exists. */
+export function nextStep(git, update, cli) {
+    if (update.kind === "available") {
+        const upgrade = `${latestCliCommand(cli)} upgrade`;
+        return git.kind === "dirty"
+            ? `Commit or stash your changes, then run \`${upgrade}\` to move to Starter ${update.starterRef}.`
+            : `Run \`${upgrade}\` to move to Starter ${update.starterRef}.`;
+    }
+    if (update.kind === "current") {
+        return `The project is on the newest Starter release. Run \`${cli} doctor\` to check its setup.`;
+    }
+    return `Could not check for a newer Starter release. Run \`${cli} doctor\` to check the project's setup.`;
+}
+/** The lowest version a range such as ">=22.12.0" or "^22.12.0" accepts. */
+function minimumOf(range) {
+    const match = /(\d+\.\d+\.\d+)/.exec(range ?? "");
+    return match ? match[1] : null;
+}
+export function checkNode(actual, engines) {
+    const minimum = minimumOf(engines) ?? "22.12.0";
+    const difference = compareVersions(actual, minimum);
+    return difference !== null && difference >= 0
+        ? { name: "Node.js", status: "ok", detail: `${actual} (needs ${minimum} or newer)` }
+        : {
+            name: "Node.js",
+            status: "fail",
+            detail: `${actual}, but the project needs ${minimum} or newer`,
+            fix: `Install Node.js ${minimum} or newer, such as the current LTS release.`,
+        };
+}
+/** Compares pnpm with the version in package.json's packageManager, such as "pnpm@10.9.0". */
+export function checkPnpm(actual, packageManager) {
+    const pinned = /^pnpm@(\d+\.\d+\.\d+)/.exec(packageManager ?? "")?.[1];
+    if (!actual) {
+        return {
+            name: "pnpm",
+            status: "fail",
+            detail: "not found",
+            fix: "Run `corepack enable`, which installs the pnpm version the project pins.",
+        };
+    }
+    if (!pinned)
+        return { name: "pnpm", status: "ok", detail: actual };
+    const difference = compareVersions(actual, pinned);
+    return difference !== null && difference >= 0
+        ? { name: "pnpm", status: "ok", detail: `${actual} (project pins ${pinned})` }
+        : {
+            name: "pnpm",
+            status: "warn",
+            detail: `${actual}, older than the ${pinned} the project pins`,
+            fix: "Run `corepack enable` so pnpm follows the project's packageManager field.",
+        };
+}
+/**
+ * Compares the local env file with the example: variables the example has and the local file
+ * lacks, and variables only the local file sets.
+ */
+export function checkEnvFile(example, local, paths) {
+    const name = "Environment file";
+    if (local === null) {
+        return {
+            name,
+            status: "fail",
+            detail: `${paths.local} does not exist`,
+            fix: `Copy ${paths.example} to ${paths.local} and fill in the values.`,
+        };
+    }
+    if (example === null)
+        return { name, status: "ok", detail: `${paths.local} exists (no ${paths.example} to compare)` };
+    const exampleKeys = new Set(envKeys(example));
+    const localKeys = new Set(envKeys(local));
+    const missing = [...exampleKeys].filter((key) => !localKeys.has(key));
+    const unused = [...localKeys].filter((key) => !exampleKeys.has(key));
+    if (!missing.length && !unused.length) {
+        return { name, status: "ok", detail: `${paths.local} has every variable in ${paths.example}` };
+    }
+    const parts = [
+        missing.length ? `missing ${missing.join(", ")}` : "",
+        unused.length ? `not in ${paths.example}: ${unused.join(", ")}` : "",
+    ].filter(Boolean);
+    return {
+        name,
+        status: "warn",
+        detail: `${paths.local}: ${parts.join("; ")}`,
+        fix: missing.length
+            ? `Add the missing variables from ${paths.example}; empty values are fine for services you do not use yet.`
+            : "Remove variables the project no longer uses, unless your own code reads them.",
+    };
+}
+/** Reads the result of `pnpm install --frozen-lockfile --lockfile-only`. */
+export function checkLockfile(error) {
+    const name = "Lockfile";
+    if (error === null)
+        return { name, status: "ok", detail: "pnpm-lock.yaml matches every package.json" };
+    if (error.includes("ERR_PNPM_OUTDATED_LOCKFILE")) {
+        return {
+            name,
+            status: "fail",
+            detail: "pnpm-lock.yaml is out of date with a package.json",
+            fix: "Run `pnpm install` to update it, then commit pnpm-lock.yaml.",
+        };
+    }
+    return {
+        name,
+        status: "warn",
+        detail: `could not check: ${error.split("\n").find((line) => line.trim()) ?? error}`,
+    };
+}

package/dist/core/merge.js

@@ -3,6 +3,14 @@
 // without losing the project's own edits. Pure: callers read and write the files.
 import { diff3Merge } from "node-diff3";
 export const CONFLICT_LABELS = { yours: "yours", theirs: "clubedge" };
+/** How many conflict blocks a merged file has. */
+export function countConflicts(content) {
+    const marker = `<<<<<<< ${CONFLICT_LABELS.yours}`;
+    return content
+        .toString("utf8")
+        .split(/\r?\n/)
+        .filter((line) => line === marker).length;
+}
 function isBinary(content) {
     return content.subarray(0, 8000).includes(0);
 }

package/dist/core/releases.js

@@ -0,0 +1,59 @@
+// The Starter releases an upgrade crosses, from GitHub, so `upgrade` can say what changed before
+// the developer reviews `git diff`.
+import { compareVersions } from "./health.js";
+/**
+ * The repository's published releases, newest first. Resolves null when GitHub cannot be reached
+ * in time or refuses, so an upgrade never depends on it. GITHUB_TOKEN raises the rate limit.
+ */
+export async function fetchReleases(repository, fetcher = fetch, timeoutMs = 5_000) {
+    try {
+        const token = process.env.GITHUB_TOKEN;
+        const response = await fetcher(`https://api.github.com/repos/${repository}/releases?per_page=100`, {
+            headers: {
+                accept: "application/vnd.github+json",
+                ...(token ? { authorization: `Bearer ${token}` } : {}),
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            return null;
+        const releases = (await response.json());
+        if (!Array.isArray(releases))
+            return null;
+        return releases
+            .filter((release) => typeof release.tag_name === "string" && !release.draft && !release.prerelease)
+            .map((release) => ({
+            tag: release.tag_name,
+            name: typeof release.name === "string" && release.name ? release.name : release.tag_name,
+            body: typeof release.body === "string" ? release.body : "",
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+/** Releases after `from`, up to and including `to`, oldest first. */
+export function releasesBetween(releases, from, to) {
+    return releases
+        .filter((release) => {
+        const afterFrom = compareVersions(release.tag, from);
+        const upToTo = compareVersions(release.tag, to);
+        return afterFrom !== null && upToTo !== null && afterFrom > 0 && upToTo <= 0;
+    })
+        .sort((a, b) => compareVersions(a.tag, b.tag));
+}
+/** The second-level headings of release notes, such as "Background jobs" and "Tests". */
+export function releaseHeadings(body) {
+    return body
+        .split(/\r?\n/)
+        .flatMap((line) => /^##\s+(.+?)\s*#*\s*$/.exec(line)?.[1] ?? []);
+}
+/** One line per release: its tag and what its notes cover. */
+export function describeReleases(releases) {
+    return releases
+        .map((release) => {
+        const headings = releaseHeadings(release.body);
+        return `${release.tag}  ${headings.length ? headings.join(", ") : release.name}`;
+    })
+        .join("\n");
+}

package/dist/core/source.js

@@ -83,7 +83,9 @@ export async function downloadGitHubTemplate(ref, { repository = starterPin.star
         }
     }
     const temporary = await mkdtemp(join(tmpdir(), "create-clubedge-app-"));
-    const cleanup = () => rm(temporary, { recursive: true, force: true });
+    // Windows can briefly lock a folder that was just read (antivirus, indexing). Retry, and never
+    // fail a command that already did its work over a leftover folder in the system temp directory.
+    const cleanup = () => rm(temporary, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }).catch(() => undefined);
     try {
         const root = join(temporary, "starter");
         await downloadTemplate(`gh:${repository}#${ref}`, { dir: root, force: true });

package/dist/index.js

@@ -9,6 +9,7 @@ import { readTemplateManifest } from "./core/manifest.js";
 import { createPlan, describePlan, selectFramework } from "./core/plan.js";
 import { readBundledTemplate, resolveTemplateSource } from "./core/source.js";
 import { cliUrl, cliVersion, siteUrl, starterPin } from "./package-info.js";
+import { runDoctor, showStatus } from "./inspect.js";
 import { changeProject } from "./modify.js";
 import { initializeGit } from "./steps/git.js";
 import { detectLauncher, installDependencies, resolvePnpm } from "./steps/install.js";
@@ -225,6 +226,14 @@ export async function main(argv = process.argv.slice(2)) {
             intro("Create a project with Clubedge Starter");
             await createProject(args);
         }
+        else if (args.command.name === "status") {
+            intro("Project status");
+            await showStatus(args);
+        }
+        else if (args.command.name === "doctor") {
+            intro("Check this project's setup");
+            await runDoctor(args);
+        }
         else {
             const intros = {
                 add: "Add a module to this project",