@clubedge/create-clubedge-app 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.41.0
+
+- **A `package.json` with conflict markers no longer breaks the next commands** (#122, by @NishilRathod; issue #111):
+  - After `add`, `remove`, or `upgrade` leaves markers in a `package.json`, `pnpm install` is skipped with the reason: pnpm cannot read the file, so resolve it, then run `pnpm install`. The conflict report always prints, even when the install fails.
+  - pnpm is found from outside the project, so a broken `package.json` is no longer reported as "pnpm was not found", and an installed pnpm that fails says why.
+  - `status`, `doctor`, `add`, `remove`, `upgrade`, `deploy`, `neon`, and `try` name the unreadable `package.json` instead of printing a JSON parse error, and point to `git diff --no-index` against the Starter's version in `.clubedge/incoming`.
+  - `--detailed-exit-code` for `add`, `remove`, and `upgrade`: exit 2 when the change left conflicts to resolve, 0 when it was clean. Without it, conflicts still exit 0, as existing projects' upgrade workflow expects. The next Starter release's workflow uses it to open the upgrade pull request even when `package.json` conflicts.
+- **`doctor` fails on unresolved conflict markers** in the project's files, listing them with their block counts (#123, by @ahmed-husssain; issue #109).
+- **Projects own their version and README** (#125, by @ahmed-husssain; issue #124):
+  - New projects start at version `0.1.0`, and `add`, `remove`, and `upgrade` keep the project's own version, so the root `package.json` no longer conflicts on it with every Starter release.
+  - A README the project replaced (without the generated `## Generated from` section) is kept as it is; the Starter's new README goes to `.clubedge/incoming/README.md` to compare.
+- CI covers these cases end to end on Linux and Windows (#128).
+- Still on Starter `v0.26.0`.
+
+## 0.40.0
+
+- **Every module on React + Vite with FastAPI**: default to Starter `v0.26.0` (#126). `--framework vite --api fastapi` now offers the module options Hono got in 0.39.0, each written in Python:
+  - `--storage s3` (or a local folder with `--infra local`) and `--storage supabase`.
+  - `--cache redis`, for the rate limits and cache.
+  - `--email smtp` and `--email resend`.
+  - `--observability otel` and `--observability sentry`, with browser error reporting.
+  - `--payments stripe`, on the same tables as the Hono API.
+  - `--jobs bullmq` and `--jobs inngest`. `--jobs pg-boss` is still refused for FastAPI: pg-boss has no Python version.
+  - The account settings page in full: display name, password change, and account deletion.
+  - New Vite + FastAPI projects get the same defaults as the other stacks: S3 storage, Redis cache, and SMTP email.
+  - Each module has its own uv dependency group: every project keeps the same `uv.lock`, and its production image installs only the selected modules' libraries.
+- Rendered Python files keep the two blank lines PEP 8 and `ruff format` want between top-level definitions when a conditional block is removed (#121). Generating FastAPI projects from Starter `v0.26.0` needs this release.
+- The README says the decoupled stacks with Hono support every module (#120).
+
 ## 0.39.0
 
 - **Every module on React + Vite with Hono**: default to Starter `v0.25.0` (#118). `--framework vite --api hono` now offers every module option the full-stack apps have, each running in the API with the matching UI in the frontend:

package/README.md

@@ -141,7 +141,7 @@ They meet at one HTTP contract, `packages/contract/openapi.yaml`: the frontend c
 
 With `--auth supabase`, the Vite app owns the browser session and attaches its access token to contract requests. Hono or FastAPI verifies that token with Supabase Auth and returns the contract's shared user shape. Configure `VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_URL`, and `SUPABASE_PUBLISHABLE_KEY` in the generated env examples; no Supabase service-role key goes to the browser.
 
-The decoupled stacks support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache, any local infrastructure (the API's `apps/api/.env.local` holds `DATABASE_URL`, since the API owns the database), and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that builds the frontend and API as separate services; copy the variables of `.env.example` and `apps/api/.env.example` to `.env.production`, fill in their values, and run `docker compose --env-file .env.production up --build -d`. The frontend's `VITE_*` values are build arguments, compiled into its bundle; with Better Auth, its Node server also gets the auth variables (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and the email settings). With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
+With the Hono API, the decoupled stacks support every module option the full-stack frameworks do (since Starter v0.26.0), each running in the API with the matching UI in the frontend; with FastAPI, they support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache. Both work with any local infrastructure (the API's `apps/api/.env.local` holds `DATABASE_URL`, since the API owns the database), and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that builds the frontend and API as separate services; copy the variables of `.env.example` and `apps/api/.env.example` to `.env.production`, fill in their values, and run `docker compose --env-file .env.production up --build -d`. The frontend's `VITE_*` values are build arguments, compiled into its bundle; with Better Auth, its Node server also gets the auth variables (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and the email settings). With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
 
 ## Choosing modules
 
@@ -207,7 +207,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.25.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.26.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -226,7 +226,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 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.25.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.26.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.
@@ -241,6 +241,10 @@ Several modules in one command are applied as one change, and their requirements
 
 The project must be a Git repository without uncommitted changes, so you can review the result with `git diff` and undo it. Pass `--force` to skip this check. Add `--no-install` to skip `pnpm install`. Afterward, run `pnpm db:migrate` and `pnpm check:services` if the change added tables or services.
 
+pnpm cannot read a `package.json` with conflict markers, so a change that leaves conflicts in one skips `pnpm install` and says so: resolve them, then run `pnpm install`. Until then, `pnpm clubedge` does not start either, and the CLI's own commands (`pnpm dlx @clubedge/create-clubedge-app status`, for example) stop with a message that names the file and the command that compares it with the Starter's version in `.clubedge/incoming/`. When the install fails for another reason, the CLI still lists what is left to resolve, then exits with an error.
+
+A change that leaves conflicts exits with 0, like a clean one. For scripts that need to tell them apart, add `--detailed-exit-code`: the CLI then exits with 2 when the change was written with conflicts to resolve, 0 when it was clean or there was nothing to change, and 1 when it failed.
+
 ## A hosted database with Neon
 
 `--infra neon` gives the project a [Neon](https://neon.com) PostgreSQL database with nothing to install and no account:
@@ -337,27 +341,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.39.0
+create-clubedge-app v0.41.0
         |
         v
-Clubedge Starter v0.25.0
-commit 17f4e82dca42884e7bfc3c66991110d00c7428a8
+Clubedge Starter v0.26.0
+commit 7c01a0295bea53adc72bda5b843a478ddd04f892
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.39.0` | `clubedge-starter@v0.25.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.41.0` | `clubedge-starter@v0.26.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.25.0` tag is expected to resolve to commit
-`17f4e82dca42884e7bfc3c66991110d00c7428a8`. The CLI verifies this before
+The `v0.26.0` tag is expected to resolve to commit
+`7c01a0295bea53adc72bda5b843a478ddd04f892`. 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.25.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.26.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`.
 
@@ -412,7 +416,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.25.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.26.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -462,6 +466,8 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.37.0 | v0.24.1 | An MCP server (capabilities, validate, plan, create) and an agent skill for coding agents |
 | 0.38.0 | v0.24.2 | Starter v0.24.2: Next.js security update (critical RCE advisories); database URLs, Neon, and deploy variables for a frontend and its API |
 | 0.39.0 | v0.25.0 | Starter v0.25.0: every module on React + Vite with Hono, and account settings on React + Vite |
+| 0.40.0 | v0.26.0 | Starter v0.26.0: every module on React + Vite with FastAPI (pg-boss excepted) |
+| 0.41.0 | v0.26.0 | A conflicted package.json no longer breaks later commands (`--detailed-exit-code`); doctor finds conflict markers; projects own their version and README |
 
 ## 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 },
+    "detailed-exit-code": { type: "boolean", default: false },
     services: { type: "boolean", default: true },
     open: { type: "boolean", default: true },
     claim: { type: "boolean", default: false },
@@ -98,6 +99,9 @@ export function parseCliArgs(argv) {
     if (command.name !== "try" && (values.claim || values.status)) {
         throw new UsageError("--claim and --status only apply to try.");
     }
+    if (command.name !== "add" && command.name !== "remove" && command.name !== "upgrade" && values["detailed-exit-code"]) {
+        throw new UsageError("--detailed-exit-code only applies to add, remove, and upgrade.");
+    }
     if (command.name === "try" && values["template-dir"] !== undefined) {
         throw new UsageError("--template-dir does not apply to try: the VM downloads the Starter itself.");
     }
@@ -122,6 +126,7 @@ export function parseCliArgs(argv) {
         yes: values.yes,
         dryRun: values["dry-run"],
         force: values.force,
+        detailedExitCode: values["detailed-exit-code"],
         services: values.services,
         open: values.open,
         claim: values.claim,

package/dist/cli/ui.js

@@ -130,6 +130,8 @@ ${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
+  --detailed-exit-code    add/remove/upgrade: exit with 2 when the change leaves conflicts to
+                          resolve (0: changed cleanly or nothing to change, 1: failed)
   --no-services           doctor: skip pnpm check:services
   --no-open               try, deploy (Vercel, Netlify, Render): do not open the URL in the browser
   --claim                 try: open the page that claims the VM, to share the preview

package/dist/core/customize.js

@@ -21,9 +21,10 @@ function recordStacks(stacks) {
         ...(Object.keys(apps).length ? { apps } : {}),
     };
 }
-export function customizeRootManifest(source, { packageName }, provenance, dockerImage, scripts = { set: {}, remove: [] }) {
+export function customizeRootManifest(source, { packageName, version = "0.1.0" }, provenance, dockerImage, scripts = { set: {}, remove: [] }) {
     const manifest = JSON.parse(source);
     manifest.name = packageName;
+    manifest.version = version;
     if (manifest.scripts && typeof manifest.scripts === "object") {
         for (const name of scripts.remove)
             delete manifest.scripts[name];
@@ -229,8 +230,12 @@ export function applyConditionals(source, selection, path = "file") {
     if (!removed)
         return text;
     // A removed block can leave two blank lines in a row, or blank lines at the start or end of
-    // the file; formatted sources never have them.
-    const collapsed = text.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+    // the file; formatted sources never have them. Python is the exception: two blank lines come
+    // before a top-level definition (PEP 8, which ruff format enforces), one inside indented code.
+    const squeezed = path.endsWith(".py")
+        ? text.replace(/\n{4,}/g, "\n\n\n").replace(/\n{3,}(?=[ \t])/g, "\n\n")
+        : text.replace(/\n{3,}/g, "\n\n");
+    const collapsed = squeezed.replace(/^\n+/, "");
     return source.endsWith("\n") ? collapsed.replace(/\n+$/, "\n") : collapsed;
 }
 /** Removes dependencies on workspace packages that were left out of the project. */

package/dist/core/health.js

@@ -210,3 +210,20 @@ export function checkDatabaseUrls(input) {
     }
     return { name, status: "ok", detail: "Neon, pooled for the app and direct for migrations and the jobs worker" };
 }
+export function checkConflicts(conflicts) {
+    const name = "Conflicts";
+    if (!conflicts.length)
+        return { name, status: "ok", detail: "no unresolved conflict markers" };
+    const total = conflicts.reduce((sum, c) => sum + c.blocks, 0);
+    const sample = conflicts
+        .slice(0, 5)
+        .map((c) => `\n  • ${c.path} (${c.blocks} ${c.blocks === 1 ? "block" : "blocks"})`)
+        .join("");
+    const more = conflicts.length > 5 ? `\n  ... and ${conflicts.length - 5} more files` : "";
+    return {
+        name,
+        status: "fail",
+        detail: `${conflicts.length} ${conflicts.length === 1 ? "file has" : "files have"} unresolved conflict markers (${total} total):${sample}${more}`,
+        fix: 'Resolve the "<<<<<<< yours" markers in these files, then delete .clubedge/incoming.',
+    };
+}

package/dist/core/merge.js

@@ -3,6 +3,11 @@
 // 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" };
+/**
+ * Where the Starter's versions of files left to resolve are saved, next to the project's own,
+ * for comparing by hand. The folder ignores itself, so it never shows in git status or a commit.
+ */
+export const INCOMING_DIR = ".clubedge/incoming";
 /** How many conflict blocks a merged file has. */
 export function countConflicts(content) {
     const marker = `<<<<<<< ${CONFLICT_LABELS.yours}`;

package/dist/core/project.js

@@ -1,21 +1,59 @@
 // Reads an existing generated project and renders projects in memory, so commands that change
 // a project (add, remove, upgrade) can compare what the CLI generated with what it would now.
 import { readFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { pathExists } from "../utils/fs.js";
 import { displayNameFromPackageName } from "../utils/names.js";
 import { recordedStacks } from "./customize.js";
+import { countConflicts, INCOMING_DIR } from "./merge.js";
 import { createPlan } from "./plan.js";
 export class ProjectError extends Error {
     name = "ProjectError";
 }
+/** The Starter's version of a file, saved by the last change in the `.clubedge` of a folder above it. */
+async function findIncoming(file) {
+    let folder = dirname(file);
+    while (true) {
+        const incoming = join(folder, INCOMING_DIR, relative(folder, file));
+        if (await pathExists(incoming))
+            return incoming;
+        const parent = dirname(folder);
+        if (parent === folder)
+            return null;
+        folder = parent;
+    }
+}
+/**
+ * Why a package.json does not parse, naming it as seen from `directory`. Most often it is a
+ * conflict left by add, remove, or upgrade, which pnpm cannot read either.
+ */
+async function unreadableManifest(path, content, directory, error) {
+    const shown = (file) => relative(directory, file).split(sep).join("/");
+    const conflicts = countConflicts(content);
+    if (!conflicts) {
+        return new ProjectError(`${shown(path)} is not valid JSON: ${error instanceof Error ? error.message : String(error)}. Fix it, then run this again.`);
+    }
+    const incoming = await findIncoming(path);
+    return new ProjectError(`${shown(path)} has ${conflicts} unresolved ${conflicts === 1 ? "conflict" : "conflicts"} from an earlier add, remove, or upgrade, ` +
+        "marked <<<<<<< yours ... ======= ... >>>>>>> clubedge. While it has the markers, pnpm cannot read it either, so `pnpm install` and `pnpm clubedge` fail too. " +
+        "Keep your lines, the Starter's, or a mix, delete the markers, then run this again." +
+        (incoming ? `\nThe Starter's version, to compare with yours:\n  git diff --no-index ${shown(path)} ${shown(incoming)}` : ""));
+}
 /** Finds the generated project that contains `directory` and reads its provenance. */
 export async function readProject(directory) {
-    let current = resolve(directory);
+    const start = resolve(directory);
+    let current = start;
     while (true) {
         const manifestPath = join(current, "package.json");
         if (await pathExists(manifestPath)) {
-            const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+            const content = await readFile(manifestPath);
+            let manifest;
+            try {
+                manifest = JSON.parse(content.toString("utf8"));
+            }
+            catch (error) {
+                throw await unreadableManifest(manifestPath, content, start, error);
+            }
             const origin = manifest.clubedge;
             if (origin?.starterRef) {
                 // Projects record the framework only when the Starter offered a choice, but always their modules.
@@ -24,7 +62,11 @@ export async function readProject(directory) {
                 }
                 return {
                     root: current,
-                    identity: { packageName: manifest.name, displayName: displayNameFromPackageName(manifest.name) },
+                    identity: {
+                        packageName: manifest.name,
+                        displayName: displayNameFromPackageName(manifest.name),
+                        version: typeof manifest.version === "string" ? manifest.version : "0.1.0",
+                    },
                     cliVersion: origin.cliVersion,
                     starterRepository: origin.starterRepository,
                     starterRef: origin.starterRef,

package/dist/core/update.js

@@ -4,14 +4,10 @@
 import { mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { updateEnvFile } from "./env.js";
-import { planMerge, sameContent } from "./merge.js";
+import { INCOMING_DIR, planMerge, sameContent } from "./merge.js";
 import { readProjectFiles, renderProject } from "./project.js";
+export { INCOMING_DIR };
 const LOCKFILE = "pnpm-lock.yaml";
-/**
- * Where the Starter's versions of files left to resolve are saved, next to the project's own,
- * for comparing by hand. The folder ignores itself, so it never shows in git status or a commit.
- */
-export const INCOMING_DIR = ".clubedge/incoming";
 export async function planUpdate(project, base, target) {
     const render = (side) => renderProject({
         source: side.source,
@@ -32,7 +28,23 @@ export async function planUpdate(project, base, target) {
     const current = await readProjectFiles(project.root, [
         ...new Set([...baseFiles.keys(), ...targetFiles.keys(), ...special]),
     ]);
+    const currentReadme = current.get("README.md");
+    const customReadme = Boolean(currentReadme && !currentReadme.toString("utf8").includes("## Generated from"));
+    const targetReadme = targetFiles.get("README.md");
+    if (customReadme) {
+        baseFiles.delete("README.md");
+        targetFiles.delete("README.md");
+    }
     const actions = planMerge(baseFiles, targetFiles, current);
+    if (customReadme && targetReadme && !sameContent(currentReadme, targetReadme)) {
+        actions.push({
+            path: "README.md",
+            kind: "keep",
+            reason: "You replaced the generated README with your own.",
+            incoming: targetReadme,
+        });
+        actions.sort((a, b) => a.path.localeCompare(b.path));
+    }
     let lockfile = { kind: "unchanged" };
     const baseLock = before.files.get(LOCKFILE);
     const targetLock = after.files.get(LOCKFILE);

package/dist/index.js

@@ -15,7 +15,7 @@ import { deployProject } from "./deploy.js";
 import { tryOnRailway } from "./try.js";
 import { describeNewDatabase, neonCommand, provisionNeonDatabase } from "./neon.js";
 import { initializeGit } from "./steps/git.js";
-import { detectLauncher, installDependencies, resolvePnpm } from "./steps/install.js";
+import { detectLauncher, detectPnpm, installDependencies } from "./steps/install.js";
 import { commandSucceeds, run } from "./utils/process.js";
 import { displayNameFromPackageName, packageNameFromDirectory } from "./utils/names.js";
 const minimumNode = [22, 12];
@@ -148,7 +148,7 @@ async function createProject(args) {
     const targetDirectory = resolve(process.cwd(), requested);
     await assertTargetIsUsable(targetDirectory);
     const packageName = packageNameFromDirectory(targetDirectory);
-    const identity = { packageName, displayName: displayNameFromPackageName(packageName) };
+    const identity = { packageName, displayName: displayNameFromPackageName(packageName), version: "0.1.0" };
     const progress = spinner();
     progress.start("Preparing the Starter");
     const source = await resolveTemplateSource({ ref: args.ref, templateDir: args.templateDir }).catch((error) => {
@@ -237,9 +237,11 @@ async function createProject(args) {
         if (launcher && launcher !== "pnpm") {
             log.info(`This project is a pnpm workspace, so dependencies are installed with pnpm (not ${launcher}).`);
         }
-        const pnpm = await resolvePnpm();
+        const { pnpm, problem } = await detectPnpm();
         if (!pnpm) {
-            log.warn("pnpm was not found. Enable it with `corepack enable`, then run `pnpm install` in the project.");
+            log.warn(problem
+                ? `pnpm is installed but did not run, so dependencies were not installed. ${problem} Run \`pnpm install\` in the project once it works.`
+                : "pnpm was not found. Enable it with `corepack enable`, then run `pnpm install` in the project.");
         }
         else {
             pnpmCommand = pnpm.join(" ");
@@ -321,7 +323,10 @@ export async function main(argv = process.argv.slice(2)) {
                 upgrade: "Upgrade this project to a newer Starter",
             };
             intro(intros[args.command.name]);
-            await changeProject(args);
+            // Conflicts exit with 0 unless asked: the Starter's upgrade workflow in existing projects
+            // runs the newest CLI under `set -o pipefail`, and would stop before opening its pull request.
+            if ((await changeProject(args)) === "conflicts" && args.detailedExitCode)
+                process.exitCode = 2;
         }
     }
     catch (error) {

package/dist/inspect.js

@@ -5,14 +5,15 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import process from "node:process";
 import { dim } from "./cli/ui.js";
-import { checkDatabaseUrls, checkEnvFile, checkLockfile, checkNode, checkPnpm, fetchLatestRelease, nextStep, updateState, } from "./core/health.js";
+import { checkConflicts, checkDatabaseUrls, checkEnvFile, checkLockfile, checkNode, checkPnpm, fetchLatestRelease, nextStep, updateState, } from "./core/health.js";
+import { countConflicts } from "./core/merge.js";
 import { parseEnvFile } from "./core/deploy.js";
 import { neonDatabaseState } from "./core/neon.js";
 import { databaseEnvFile, projectEnvFiles, readProject } from "./core/project.js";
 import { savedDatabaseForUrl } from "./neon.js";
 import { cliCommand } from "./modify.js";
 import { resolvePnpm } from "./steps/install.js";
-import { pathExists } from "./utils/fs.js";
+import { listTemplateFiles, pathExists } from "./utils/fs.js";
 import { commandSucceeds, run, runCapture } from "./utils/process.js";
 async function readText(path) {
     try {
@@ -78,6 +79,19 @@ function print(result) {
     else
         log.error(line);
 }
+export async function findConflictedFiles(root) {
+    const files = await listTemplateFiles(root);
+    const conflicts = [];
+    for (const file of files) {
+        const content = await readFile(join(root, file)).catch(() => null);
+        if (!content)
+            continue;
+        const blocks = countConflicts(content);
+        if (blocks > 0)
+            conflicts.push({ path: file, blocks });
+    }
+    return conflicts;
+}
 export async function runDoctor(args) {
     const project = await readProject(process.cwd());
     const root = project.root;
@@ -91,6 +105,7 @@ export async function runDoctor(args) {
     const pnpm = await resolvePnpm();
     const pnpmVersion = pnpm ? await runCapture(pnpm[0], [...pnpm.slice(1), "--version"]).catch(() => null) : null;
     check(checkPnpm(pnpmVersion, manifest.packageManager));
+    check(checkConflicts(await findConflictedFiles(root)));
     const installed = await pathExists(join(root, "node_modules", ".modules.yaml"));
     check(installed
         ? { name: "Dependencies", status: "ok", detail: "installed" }

package/dist/mcp-server.js

@@ -11,7 +11,7 @@ import { createPlan, describePlan } from "./core/plan.js";
 import { resolveTemplateSource } from "./core/source.js";
 import { cliVersion, cliUrl, siteUrl } from "./package-info.js";
 import { initializeGit } from "./steps/git.js";
-import { installDependencies, resolvePnpm } from "./steps/install.js";
+import { detectPnpm, installDependencies } from "./steps/install.js";
 import { commandSucceeds, run } from "./utils/process.js";
 import { displayNameFromPackageName, packageNameFromDirectory } from "./utils/names.js";
 // Keep subprocess output off the MCP JSON-RPC stdout stream, and don't let children read MCP input.
@@ -217,9 +217,11 @@ function createServer() {
             }
         }
         if (install_dependencies) {
-            const pnpm = await resolvePnpm();
+            const { pnpm, problem } = await detectPnpm();
             if (!pnpm) {
-                warnings.push("Project created, but pnpm was not found. Install pnpm and run it in the project directory.");
+                warnings.push(problem
+                    ? `Project created, but pnpm is installed and did not run. ${problem}`
+                    : "Project created, but pnpm was not found. Install pnpm and run it in the project directory.");
             }
             else {
                 try {

package/dist/modify.js

@@ -18,7 +18,8 @@ import { applyUpdate, INCOMING_DIR, planUpdate } from "./core/update.js";
 import { cliVersion, starterPin } from "./package-info.js";
 import { parseEnvFile } from "./core/deploy.js";
 import { describeNewDatabase, projectDatabaseEnv, provisionNeonDatabase } from "./neon.js";
-import { installDependencies, resolvePnpm } from "./steps/install.js";
+import { detectPnpm, installDependencies } from "./steps/install.js";
+import { listTemplateFiles } from "./utils/fs.js";
 import { commandSucceeds, runCapture } from "./utils/process.js";
 /** How to run the CLI in this project: its `clubedge` script when it has one. */
 export async function cliCommand(project) {
@@ -230,8 +231,27 @@ function describe(plan) {
     }
     return lines.join("\n");
 }
+const conflictsOf = (plan) => plan.actions.filter((action) => action.kind === "conflict");
+/**
+ * The project's package.json files with conflict markers: this change's, and any an earlier change
+ * left that this one does not touch, which its plan does not list.
+ */
+async function conflictedManifests(root) {
+    const manifests = (await listTemplateFiles(root)).filter((path) => /(^|\/)package\.json$/.test(path));
+    const conflicted = await Promise.all(manifests.map(async (path) => (countConflicts(await readFile(join(root, path))) ? path : null)));
+    return conflicted.filter((path) => path !== null);
+}
+/**
+ * Why pnpm cannot run yet: it reads every package.json in the workspace and stops at one with
+ * conflict markers, so `pnpm install` and `pnpm clubedge` fail until they are resolved.
+ */
+function conflictedManifestWarning(paths, install) {
+    const one = paths.length === 1;
+    return (`${install ? "Skipped `pnpm install`: " : ""}${paths.join(", ")} ${one ? "has" : "have"} conflict markers, which pnpm cannot read, ` +
+        `so pnpm commands, \`pnpm clubedge\` among them, fail until ${one ? "it is" : "they are"} resolved. Then run \`pnpm install\`.`);
+}
 function report(plan) {
-    const conflicts = plan.actions.filter((action) => action.kind === "conflict");
+    const conflicts = conflictsOf(plan);
     const kept = plan.actions.filter((action) => action.kind === "keep");
     const incoming = (path) => `${INCOMING_DIR}/${path}`;
     if (conflicts.length) {
@@ -366,12 +386,12 @@ export async function changeProject(args) {
         const complete = command.name === "upgrade" ? command : await completeCommand(baseManifest, project, command, interactive);
         if (!complete) {
             outro("Cancelled; nothing was changed.");
-            return;
+            return "unchanged";
         }
         const change = await planChange(project, complete, base, baseManifest, target, cli);
         if (!change) {
             outro(upgrading ? `The project is already on Starter ${project.starterRef}.` : "The project already uses that selection; nothing to change.");
-            return;
+            return "unchanged";
         }
         const plan = await planUpdate(project, change.base, change.target);
         if (change.releases)
@@ -381,17 +401,32 @@ export async function changeProject(args) {
             for (const note of change.notes)
                 log.info(note);
             outro("Dry run: nothing was changed. Run again without --dry-run to apply.");
-            return;
+            return "unchanged";
         }
         await applyUpdate(plan);
         log.success(`Updated ${plan.actions.filter((action) => action.kind !== "keep").length} files`);
-        if (args.install) {
-            const pnpm = await resolvePnpm();
-            if (!pnpm)
-                log.warn("pnpm was not found. Run `pnpm install` to update dependencies.");
+        // The files are written now, so what is left to resolve is reported even when the install fails.
+        let installError;
+        const manifests = await conflictedManifests(project.root);
+        if (manifests.length) {
+            log.warn(conflictedManifestWarning(manifests, args.install));
+        }
+        else if (args.install) {
+            const { pnpm, problem } = await detectPnpm();
+            if (pnpm) {
+                try {
+                    await installDependencies(project.root, pnpm, plan.lockfile.kind === "install" ? ["--no-frozen-lockfile"] : []);
+                    log.success("Dependencies updated");
+                }
+                catch (error) {
+                    installError = error;
+                }
+            }
+            else if (problem) {
+                log.warn(`pnpm is installed but did not run, so dependencies were not updated. ${problem} Run \`pnpm install\` once it works.`);
+            }
             else {
-                await installDependencies(project.root, pnpm, plan.lockfile.kind === "install" ? ["--no-frozen-lockfile"] : []);
-                log.success("Dependencies updated");
+                log.warn("pnpm was not found. Run `pnpm install` to update dependencies.");
             }
         }
         else if (plan.lockfile.kind !== "unchanged") {
@@ -400,11 +435,16 @@ export async function changeProject(args) {
         report(plan);
         for (const note of change.notes)
             log.info(note);
+        if (installError) {
+            const reason = installError instanceof Error ? installError.message : String(installError);
+            throw new Error(`The files were updated, but \`pnpm install\` did not complete: ${reason}${reason.endsWith(".") ? "" : "."} Fix that, then run \`pnpm install\`.`);
+        }
         if (change.target.modules.infra === "neon" && project.modules.infra !== "neon")
             await addNeonDatabase(project, args, cli);
         outro(upgrading
             ? "Review the changes with `git diff`, then run `pnpm db:migrate` for new migrations and your tests."
             : "Review the changes with `git diff`, then run `pnpm check:services` and `pnpm db:migrate` if the change added services or tables.");
+        return conflictsOf(plan).length ? "conflicts" : "changed";
     }
     catch (error) {
         if (spinning)

package/dist/steps/install.js

@@ -1,12 +1,35 @@
+import { tmpdir } from "node:os";
 import process from "node:process";
-import { commandSucceeds, run } from "../utils/process.js";
-/** The generated workspace relies on pnpm features (workspace:* and pnpm-workspace.yaml). */
+import { onPath, run, runCapture, withAbsolutePath } from "../utils/process.js";
+/**
+ * Finds pnpm, which the generated workspace relies on (workspace:* and pnpm-workspace.yaml), or
+ * corepack, which runs the pnpm version the project pins. Both are checked outside the project:
+ * they read the package.json of the folder they start in and fail when it does not parse, such as
+ * while it has conflict markers, and that is not pnpm missing.
+ */
+export async function detectPnpm() {
+    let problem;
+    for (const pnpm of [["pnpm"], ["corepack", "pnpm"]]) {
+        const command = pnpm[0];
+        try {
+            // `corepack --version`, not `corepack pnpm --version`: outside a project, corepack would
+            // download its own default pnpm just to answer. PATH's relative folders still mean the
+            // folder the CLI runs in, where onPath and the install look.
+            await runCapture(command, ["--version"], tmpdir(), withAbsolutePath());
+            return { pnpm };
+        }
+        catch (error) {
+            if (!problem && (await onPath(command))) {
+                const reason = error instanceof Error ? error.message : String(error);
+                problem = `\`${command} --version\` failed: ${reason}${reason.endsWith(".") ? "" : "."}`;
+            }
+        }
+    }
+    return { pnpm: null, problem };
+}
+/** The command that runs pnpm, or null; detectPnpm also says why an installed one did not run. */
 export async function resolvePnpm() {
-    if (await commandSucceeds("pnpm", ["--version"]))
-        return ["pnpm"];
-    if (await commandSucceeds("corepack", ["pnpm", "--version"]))
-        return ["corepack", "pnpm"];
-    return null;
+    return (await detectPnpm()).pnpm;
 }
 /** The package manager that launched the CLI, from npm_config_user_agent (e.g. "npm/10.8.2 ..."). */
 export function detectLauncher(userAgent = process.env.npm_config_user_agent) {