@clubedge/create-clubedge-app 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 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:
@@ -136,12 +136,14 @@ 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
@@ -155,14 +157,27 @@ 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.15.0
         |
         v
 Clubedge Starter v0.13.1
@@ -173,7 +188,7 @@ 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.15.0` | `clubedge-starter@v0.13.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`.
 
@@ -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) |
@@ -260,7 +276,8 @@ 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 |
+| 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",

package/dist/inspect.js

@@ -0,0 +1,125 @@
+// `status` and `doctor` look at an existing project without changing it: status reports where
+// it stands and what to run next, and doctor checks that it can run.
+import { log, outro } from "@clack/prompts";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import process from "node:process";
+import { dim } from "./cli/ui.js";
+import { checkEnvFile, checkLockfile, checkNode, checkPnpm, fetchLatestRelease, nextStep, updateState, } from "./core/health.js";
+import { readProject } from "./core/project.js";
+import { cliCommand } from "./modify.js";
+import { resolvePnpm } from "./steps/install.js";
+import { pathExists } from "./utils/fs.js";
+import { commandSucceeds, run, runCapture } from "./utils/process.js";
+/** Where generated projects keep their env files. */
+const ENV_PATHS = { example: ".env.example", local: "apps/web/.env.local" };
+async function readText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export async function gitState(root) {
+    if (!(await commandSucceeds("git", ["-C", root, "rev-parse", "--is-inside-work-tree"])))
+        return { kind: "none" };
+    const status = await runCapture("git", ["-C", root, "status", "--porcelain"]);
+    const files = status.split("\n").filter(Boolean).length;
+    return files ? { kind: "dirty", files } : { kind: "clean" };
+}
+const describeGit = (git) => git.kind === "none"
+    ? "not a Git repository"
+    : git.kind === "clean"
+        ? "clean"
+        : `${git.files} uncommitted ${git.files === 1 ? "change" : "changes"}`;
+export async function showStatus(_args) {
+    const project = await readProject(process.cwd());
+    const [git, latest, cli] = await Promise.all([gitState(project.root), fetchLatestRelease(), cliCommand(project)]);
+    const update = updateState(project.starterRef, latest);
+    const commit = project.starterCommit ? ` ${dim(`(commit ${project.starterCommit.slice(0, 7)})`)}` : "";
+    const modules = Object.entries(project.modules)
+        .map(([id, option]) => `${id}: ${option}`)
+        .join(", ");
+    const updates = update.kind === "available"
+        ? `Starter ${update.starterRef} is available (create-clubedge-app ${update.cliVersion})`
+        : update.kind === "current"
+            ? "on the newest Starter release"
+            : "could not check";
+    const rows = [
+        ["Project", project.identity.packageName],
+        ["Starter", `${project.starterRef}${commit}, created with create-clubedge-app ${project.cliVersion}`],
+        ["Framework", project.framework],
+        ["Modules", modules],
+        ["Git", describeGit(git)],
+        ["Updates", updates],
+    ];
+    log.message(rows.map(([label, value]) => `${label.padEnd(10)} ${value}`).join("\n"));
+    outro(nextStep(git, update, cli));
+}
+/** Runs `pnpm install --frozen-lockfile --lockfile-only` offline; resolves its error or null. */
+async function lockfileError(root, pnpm) {
+    const [command, ...prefix] = pnpm;
+    try {
+        await runCapture(command, [...prefix, "install", "--frozen-lockfile", "--lockfile-only", "--offline"], root);
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function print(result) {
+    const line = `${result.name}: ${result.detail}${result.fix ? `\n${dim(result.fix)}` : ""}`;
+    if (result.status === "ok")
+        log.success(line);
+    else if (result.status === "warn")
+        log.warn(line);
+    else
+        log.error(line);
+}
+export async function runDoctor(args) {
+    const project = await readProject(process.cwd());
+    const root = project.root;
+    const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    const results = [];
+    const check = (result) => {
+        results.push(result);
+        print(result);
+    };
+    check(checkNode(process.versions.node, manifest.engines?.node));
+    const pnpm = await resolvePnpm();
+    const pnpmVersion = pnpm ? await runCapture(pnpm[0], [...pnpm.slice(1), "--version"]).catch(() => null) : null;
+    check(checkPnpm(pnpmVersion, manifest.packageManager));
+    const installed = await pathExists(join(root, "node_modules", ".modules.yaml"));
+    check(installed
+        ? { name: "Dependencies", status: "ok", detail: "installed" }
+        : { name: "Dependencies", status: "fail", detail: "not installed", fix: "Run `pnpm install`." });
+    if (pnpm)
+        check(checkLockfile(await lockfileError(root, pnpm)));
+    check(checkEnvFile(await readText(join(root, ENV_PATHS.example)), await readText(join(root, ENV_PATHS.local)), ENV_PATHS));
+    // Service checks need the dependencies, and print their own results.
+    if (args.services && manifest.scripts?.["check:services"] && pnpm && installed) {
+        log.step("Checking the configured services with `pnpm check:services`");
+        try {
+            await run(pnpm[0], [...pnpm.slice(1), "check:services"], root);
+            results.push({ name: "Services", status: "ok", detail: "every configured service answered" });
+        }
+        catch {
+            check({
+                name: "Services",
+                status: "fail",
+                detail: "a configured service did not answer",
+                fix: "See the output above; SETUP.md explains each service.",
+            });
+        }
+    }
+    const failed = results.filter((result) => result.status === "fail").length;
+    const warned = results.filter((result) => result.status === "warn").length;
+    if (failed)
+        process.exitCode = 1;
+    outro(failed
+        ? `${failed} ${failed === 1 ? "check" : "checks"} failed${warned ? ` and ${warned} need attention` : ""}.`
+        : warned
+            ? `No failures; ${warned} ${warned === 1 ? "check needs" : "checks need"} attention.`
+            : "Every check passed.");
+}

package/dist/modify.js

@@ -8,6 +8,9 @@ import process from "node:process";
 import { UsageError } from "./cli/args.js";
 import { dim } from "./cli/ui.js";
 import { readTemplateManifest } from "./core/manifest.js";
+import { compareVersions } from "./core/health.js";
+import { countConflicts } from "./core/merge.js";
+import { describeReleases, fetchReleases, releasesBetween } from "./core/releases.js";
 import { selectModules } from "./core/plan.js";
 import { readProject } from "./core/project.js";
 import { downloadGitHubTemplate, readDirectoryTemplate, resolveTemplateSource, } from "./core/source.js";
@@ -16,7 +19,7 @@ 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) {
+export async function cliCommand(project) {
     try {
         const manifest = JSON.parse(await readFile(join(project.root, "package.json"), "utf8"));
         if (manifest.scripts?.clubedge)
@@ -86,17 +89,17 @@ function available(manifest, project, moduleId, optionId) {
  * 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 === "add" && command.changes.length && command.changes.every((change) => change.option)) {
+        return { name: "add", changes: command.changes.map(({ module, option }) => ({ module, option: option })) };
     }
-    if (command.name === "remove" && command.module)
-        return { name: "remove", module: command.module };
+    if (command.name === "remove" && command.modules.length)
+        return { name: "remove", modules: command.modules };
     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;
+    let moduleId = command.name === "add" ? command.changes[0]?.module : undefined;
     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)
@@ -114,7 +117,7 @@ export async function completeCommand(manifest, project, command, interactive) {
         moduleId = value;
     }
     if (command.name === "remove")
-        return { name: "remove", module: moduleId };
+        return { name: "remove", modules: [moduleId] };
     const module = manifest.modules[moduleId];
     if (!module) {
         throw new UsageError(`Unknown module "${moduleId}". Choose one of: ${Object.keys(manifest.modules).join(", ")}.`);
@@ -132,30 +135,32 @@ export async function completeCommand(manifest, project, command, interactive) {
     });
     if (isCancel(option))
         return null;
-    return { name: "add", module: moduleId, option };
+    return { name: "add", changes: [{ module: moduleId, option }] };
 }
-/** The selection after add or remove, validated against the Starter's manifest. */
-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(", ")}.`);
-    }
-    let option;
-    if (command.name === "add") {
-        option = command.option;
-        if (!module.options[option]) {
-            throw new UsageError(`Unknown ${command.module} option "${option}". Choose one of: ${Object.keys(module.options).join(", ")}.`);
+/**
+ * The selection after add or remove, validated against the Starter's manifest. Every change
+ * applies before requirements are checked, so changes that only work together, such as Supabase
+ * Auth with Supabase Storage, can be made in one command.
+ */
+export function changedModules(manifest, project, command, cli) {
+    const changes = command.name === "add" ? command.changes : command.modules.map((module) => ({ module, option: "none" }));
+    const requested = { ...project.modules };
+    for (const { module: id, option } of changes) {
+        const module = manifest.modules[id];
+        if (!module) {
+            throw new UsageError(`Unknown module "${id}". Choose one of: ${Object.keys(manifest.modules).join(", ")}.`);
         }
-    }
-    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: ${cli} add ${command.module} ${others[0] ?? module.default}`);
+        if (command.name === "remove" && !module.options.none) {
+            const others = Object.keys(module.options).filter((other) => other !== project.modules[id]);
+            throw new UsageError(`${module.name} cannot be removed. Switch it instead, for example: ${cli} add ${id} ${others[0] ?? module.default}`);
+        }
+        if (!module.options[option]) {
+            throw new UsageError(`Unknown ${id} option "${option}". Choose one of: ${Object.keys(module.options).join(", ")}.`);
         }
-        option = "none";
+        requested[id] = option;
     }
     // Validates requirements between modules, such as Supabase Storage needing Supabase Auth.
-    return selectModules(manifest, { ...project.modules, [command.module]: option });
+    return selectModules(manifest, requested);
 }
 /**
  * The project's selection in a newer Starter. Modules the project predates get their "none"
@@ -209,7 +214,13 @@ function report(plan) {
     const conflicts = plan.actions.filter((action) => action.kind === "conflict");
     const kept = plan.actions.filter((action) => action.kind === "keep");
     if (conflicts.length) {
-        log.warn(`Resolve the conflict markers (<<<<<<< yours / >>>>>>> clubedge) in:\n${conflicts.map((action) => `  ${action.path}`).join("\n")}`);
+        const blocks = conflicts.map((action) => countConflicts(action.content));
+        const total = blocks.reduce((sum, count) => sum + count, 0);
+        log.warn(`Resolve ${total} ${total === 1 ? "conflict" : "conflicts"} in ${conflicts.length} ${conflicts.length === 1 ? "file" : "files"}. ` +
+            "Each is marked <<<<<<< yours ... ======= ... >>>>>>> clubedge: keep your lines, the Starter's, or a mix, then delete the markers.\n" +
+            conflicts
+                .map((action, i) => `  ${action.path} ${dim(`(${blocks[i]} ${blocks[i] === 1 ? "block" : "blocks"})`)}`)
+                .join("\n"));
     }
     if (kept.length) {
         log.info(`Check these files by hand:\n${kept.map((action) => `  ${action.path}: ${action.reason}`).join("\n")}`);
@@ -259,16 +270,24 @@ async function planChange(project, command, base, baseManifest, target, cli) {
     if (/^v\d/.test(target.ref)) {
         notes.push(`Release notes: https://github.com/${target.repository}/releases/tag/${target.ref}`);
     }
+    let releases;
+    if (compareVersions(project.starterRef, target.ref) !== null) {
+        const published = await fetchReleases(target.repository);
+        const crossed = published ? releasesBetween(published, project.starterRef, target.ref) : [];
+        if (crossed.length)
+            releases = describeReleases(crossed);
+    }
     return {
         base: baseSide,
         target: { source: target, manifest: targetManifest, modules, cliVersion },
         summary: `Starter ${project.starterRef} -> ${target.ref}`,
         notes,
+        releases,
     };
 }
 export async function changeProject(args) {
     const command = args.command;
-    if (command.name === "create")
+    if (command.name !== "add" && command.name !== "remove" && command.name !== "upgrade")
         throw new Error("Not a project change.");
     const interactive = Boolean(process.stdin.isTTY) && !args.yes;
     const project = await readProject(process.cwd());
@@ -300,6 +319,8 @@ export async function changeProject(args) {
             return;
         }
         const plan = await planUpdate(project, change.base, change.target);
+        if (change.releases)
+            log.info(`Starter releases in this upgrade:\n${change.releases}`);
         log.message(`${change.summary}\n\n${describe(plan) || "No file changes."}`);
         if (args.dryRun) {
             for (const note of change.notes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",