@clubedge/create-clubedge-app 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.8.0
+
+- Add `add <module> <option>` and `remove <module>` to change the modules of an existing project. The CLI renders the project's recorded Starter commit with the current and the new selection and merges the difference into the project. Files you never changed are updated, your edits are kept, and lines both sides changed get conflict markers. The local env file keeps your values: only generated values follow the new selection, and new variables are added. A Git repository without uncommitted changes is required unless `--force` is passed, so the result can be reviewed and undone.
+- Add `upgrade [--ref <ref>]`, which moves an existing project to a newer Starter (this CLI's release by default) with the same merge as `add` and `remove`, and records the new revision. Modules the project predates start as `none` where the Starter offers it, and options the new Starter no longer offers are refused before anything changes.
+- Record the commit of a Starter fetched with `--ref`, so projects created from a branch or tag can later be changed and upgraded.
+- Fix creating a project directly under a Windows drive root, such as `D:\my-app`, which failed with EPERM.
+
 ## 0.7.0
 
 - Default to Starter `v0.7.0`, which adds `--infra local`: PostgreSQL through PGlite and a local folder for files, so `pnpm dev` runs with nothing installed.

package/README.md

@@ -12,7 +12,7 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.7.0
+create-clubedge-app v0.8.0
         |
         v
 Clubedge Starter v0.7.0
@@ -23,7 +23,7 @@ The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.7.0` | `clubedge-starter@v0.7.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.8.0` | `clubedge-starter@v0.7.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`.
 
@@ -143,6 +143,28 @@ pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 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:
+
+```sh
+pnpm dlx @clubedge/create-clubedge-app add cache redis      # or switch: add auth better-auth
+pnpm dlx @clubedge/create-clubedge-app remove storage
+pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
+pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.8.0  # or a specific tag, branch, or commit
+```
+
+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.
+
+- Files you never changed are updated, added, or deleted.
+- Files you changed keep your edits. Where the module change touches the same lines, the file gets conflict markers (`<<<<<<< yours` ... `>>>>>>> clubedge`) for you to resolve.
+- Your own files are never touched.
+- `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.
+
+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.
+
 ## How it works
 
 Each CLI release bundles one Starter release. When the release is built, `scripts/bundle-template.mjs` clones the pinned Starter tag, verifies that it resolves to the pinned commit, and copies its tracked files into the package (`template/` and `template.lock.json`). Running the CLI then needs no GitHub access for the default Starter.

package/dist/cli/args.js

@@ -24,6 +24,7 @@ export function parseCliArgs(argv) {
                 git: { type: "boolean", default: true },
                 yes: { type: "boolean", short: "y", default: false },
                 "dry-run": { type: "boolean", default: false },
+                force: { type: "boolean", default: false },
                 help: { type: "boolean", short: "h", default: false },
                 version: { type: "boolean", short: "v", default: false },
             },
@@ -34,8 +35,16 @@ export function parseCliArgs(argv) {
         throw new UsageError(`${message.split("\n")[0]} Run with --help to see available options.`);
     }
     const { values, positionals } = parsed;
-    if (positionals.length > 1)
+    const command = parseCommand(positionals);
+    if (command.name === "create" && positionals.length > 1) {
         throw new UsageError("Only one project directory can be provided.");
+    }
+    if (command.name !== "create" && (values.framework !== undefined || MODULE_FLAGS.some((id) => values[id]))) {
+        throw new UsageError("--framework and module flags only apply when creating a project; use add or remove to change one module.");
+    }
+    if ((command.name === "add" || command.name === "remove") && values.ref !== undefined) {
+        throw new UsageError("--ref only applies when creating or upgrading a project.");
+    }
     if (values.framework !== undefined && !values.framework.trim()) {
         throw new UsageError("--framework requires a framework id, such as next or tanstack-start.");
     }
@@ -55,7 +64,8 @@ export function parseCliArgs(argv) {
         throw new UsageError("Use either --ref or --template-dir, not both.");
     }
     return {
-        projectDirectory: positionals[0],
+        command,
+        projectDirectory: command.name === "create" ? positionals[0] : undefined,
         framework: values.framework?.trim(),
         modules,
         ref: values.ref,
@@ -64,7 +74,33 @@ export function parseCliArgs(argv) {
         git: values.git,
         yes: values.yes,
         dryRun: values["dry-run"],
+        force: values.force,
         help: values.help,
         version: values.version,
     };
 }
+/**
+ * `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`.
+ */
+function parseCommand(positionals) {
+    const [name, module, option, ...extra] = positionals;
+    if (name === "add") {
+        if (!module || !option || extra.length) {
+            throw new UsageError("Usage: add <module> <option>, for example: add cache redis");
+        }
+        return { name, module, option };
+    }
+    if (name === "remove") {
+        if (!module || option !== undefined) {
+            throw new UsageError("Usage: remove <module>, for example: remove storage");
+        }
+        return { name, module };
+    }
+    if (name === "upgrade") {
+        if (module !== undefined)
+            throw new UsageError("Usage: upgrade [--ref <tag>], for example: upgrade --ref v0.8.0");
+        return { name };
+    }
+    return { name: "create" };
+}

package/dist/cli/ui.js

@@ -61,6 +61,14 @@ 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 upgrade [--ref <tag>]   (inside a project)
+
+  add and remove change one module of an existing project, and upgrade moves it
+  to a newer Starter (this CLI's release unless --ref is given). The change is
+  merged into your code; lines you changed that it also changes get conflict
+  markers. Commit first so you can review the result with git diff.
 
 Options:
   --framework <id>        App framework: next (default) or tanstack-start
@@ -69,8 +77,10 @@ Options:
   --cache <id>            Cache and rate limits: redis (default) or memory
   --infra <id>            Local services: docker (default), supabase, local, or none
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
+                          (upgrade: the Starter to upgrade to)
   --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
-  --dry-run               Show what would be created without writing anything
+  --dry-run               Show what would be created or changed without writing anything
+  --force                 add/remove: change a project with uncommitted changes or without Git
   -y, --yes               Accept defaults and never prompt (default directory: my-app)
   --no-install            Skip dependency installation
   --no-git                Skip Git repository initialization
@@ -84,6 +94,9 @@ Examples:
   pnpm dlx @clubedge/create-clubedge-app my-app --dry-run
   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 remove storage --dry-run
+  pnpm dlx @clubedge/create-clubedge-app@latest upgrade
 
 Learn more:
   CLI      ${cliUrl}

package/dist/core/env.js

@@ -0,0 +1,97 @@
+// The local env file holds the developer's secrets, so commands treat it line by line, the way
+// the three-way merge treats files: values still at their generated defaults follow the new
+// selection, and values the developer set are never changed or removed.
+const LINE = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
+const COMMENT = /^\s*#/;
+const keyOf = (line) => LINE.exec(line)?.[1];
+const valueOf = (line) => LINE.exec(line)[2].replace(/\s+#.*$/, "").trim();
+const find = (lines, key) => lines.findIndex((line) => keyOf(line) === key);
+function values(lines) {
+    const map = new Map();
+    for (const line of lines) {
+        const key = keyOf(line);
+        if (key)
+            map.set(key, valueOf(line));
+    }
+    return map;
+}
+/** The comment lines directly above line `at`. */
+function commentsAbove(lines, at) {
+    let start = at;
+    while (start > 0 && COMMENT.test(lines[start - 1]))
+        start--;
+    return lines.slice(start, at);
+}
+const sameLines = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
+/**
+ * Updates the local env file from the base example to the target example. Each variable's
+ * comment lines move with it unless the developer edited them, and a new variable is added after
+ * the variable it follows in the target's example, or at the end.
+ */
+export function updateEnvFile(local, baseExample, targetExample) {
+    const base = baseExample.split(/\r?\n/);
+    const target = targetExample.split(/\r?\n/);
+    const baseValues = values(base);
+    const targetValues = values(target);
+    const lines = local.split(/\r?\n/);
+    const mine = values(lines);
+    const eol = local.includes("\r\n") ? "\r\n" : "\n";
+    const result = { text: local, added: [], updated: [], removed: [], customized: [], unused: [] };
+    /** Replaces the variable's line, and its comments if the developer kept the base's. */
+    function replace(key, replacement) {
+        const at = find(lines, key);
+        const comments = commentsAbove(lines, at);
+        const generated = sameLines(comments, commentsAbove(base, find(base, key)));
+        const start = generated ? at - comments.length : at;
+        lines.splice(start, at - start + 1, ...(generated ? replacement : replacement.slice(-1)));
+    }
+    for (const [key, before] of baseValues) {
+        if (!mine.has(key))
+            continue;
+        const after = targetValues.get(key);
+        if (after === before || mine.get(key) === after)
+            continue;
+        const generated = mine.get(key) === before;
+        if (after === undefined) {
+            (generated ? result.removed : result.unused).push(key);
+            if (generated)
+                replace(key, []);
+        }
+        else {
+            (generated ? result.updated : result.customized).push(key);
+            if (generated) {
+                const at = find(target, key);
+                replace(key, [...commentsAbove(target, at), target[at]]);
+            }
+        }
+    }
+    const appended = [];
+    target.forEach((line, at) => {
+        const key = keyOf(line);
+        if (!key || baseValues.has(key) || mine.has(key) || result.added.includes(key))
+            return;
+        result.added.push(key);
+        // The nearest variable above it in the target, and the blank or comment lines in between.
+        let anchor = at - 1;
+        while (anchor >= 0 && !keyOf(target[anchor]))
+            anchor--;
+        const position = anchor >= 0 ? find(lines, keyOf(target[anchor])) : -1;
+        if (position === -1)
+            appended.push(...commentsAbove(target, at), line);
+        else
+            lines.splice(position + 1, 0, ...target.slice(anchor + 1, at + 1));
+    });
+    let text = lines.join(eol);
+    // Removed variables can leave blank lines in a row, as removed template blocks do.
+    if (result.removed.length) {
+        text = text.replace(new RegExp(`(?:${eol}){3,}`, "g"), eol + eol);
+        if (local.endsWith(eol))
+            text = text.replace(new RegExp(`(?:${eol})+$`), eol);
+    }
+    if (appended.length) {
+        const separator = text === "" || text.endsWith(eol) ? "" : eol;
+        text += `${separator}${eol}${appended.join(eol)}${eol}`;
+    }
+    result.text = text;
+    return result;
+}

package/dist/core/execute.js

@@ -1,7 +1,7 @@
 import { constants } from "node:fs";
 import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, parse } from "node:path";
-import { copyTemplateFiles, emptyDirectory } from "../utils/fs.js";
+import { copyTemplateFiles, emptyDirectory, pathExists } from "../utils/fs.js";
 export class TargetError extends Error {
     name = "TargetError";
 }
@@ -30,7 +30,9 @@ export async function assertTargetIsUsable(directory) {
 export async function executePlan(plan, source) {
     const target = plan.targetDirectory;
     await assertTargetIsUsable(target);
-    await mkdir(dirname(target), { recursive: true });
+    // Only create a missing parent: on Windows, mkdir on an existing drive root (D:\) fails.
+    if (!(await pathExists(dirname(target))))
+        await mkdir(dirname(target), { recursive: true });
     let created = false;
     try {
         await mkdir(target);

package/dist/core/merge.js

@@ -0,0 +1,96 @@
+// Three-way merge between what the CLI generated (base), what it would generate now (target),
+// and the project as it is (current). Changes from base to target are applied to the project
+// 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" };
+function isBinary(content) {
+    return content.subarray(0, 8000).includes(0);
+}
+function normalize(content) {
+    return content.toString("utf8").replace(/\r\n/g, "\n");
+}
+function usesCrlf(content) {
+    return content.includes("\r\n");
+}
+/** The text in the project's line endings: a project checked out with CRLF keeps CRLF. */
+function withLineEndings(text, like) {
+    return Buffer.from(like && usesCrlf(like) ? text.replace(/\n/g, "\r\n") : text);
+}
+/** Equal content, ignoring CRLF versus LF line endings in text files. */
+export function sameContent(a, b) {
+    if (isBinary(a) || isBinary(b))
+        return a.equals(b);
+    return normalize(a) === normalize(b);
+}
+/** Merges base -> target into current. Resolves null for binary files, which cannot be merged. */
+export function mergeText(current, base, target) {
+    if (isBinary(current) || isBinary(base) || isBinary(target))
+        return null;
+    const split = (content) => normalize(content).split("\n");
+    const regions = diff3Merge(split(current), split(base), split(target), { excludeFalseConflicts: true });
+    const lines = [];
+    let conflict = false;
+    for (const region of regions) {
+        if (region.ok) {
+            lines.push(...region.ok);
+            continue;
+        }
+        if (!region.conflict)
+            continue;
+        conflict = true;
+        lines.push(`<<<<<<< ${CONFLICT_LABELS.yours}`, ...region.conflict.a, "=======", ...region.conflict.b, `>>>>>>> ${CONFLICT_LABELS.theirs}`);
+    }
+    return { text: lines.join("\n"), conflict };
+}
+function merged(path, current, base, target, binaryReason) {
+    const result = mergeText(current, base, target);
+    if (!result)
+        return { path, kind: "keep", reason: binaryReason };
+    const content = withLineEndings(result.text, current);
+    return { path, kind: result.conflict ? "conflict" : "merge", content };
+}
+/**
+ * Decides what happens to every file the base or the target contains. Files only the project
+ * has are never touched. Actions come back sorted by path.
+ */
+export function planMerge(base, target, current) {
+    const paths = [...new Set([...base.keys(), ...target.keys()])].sort();
+    const actions = [];
+    for (const path of paths) {
+        const before = base.get(path);
+        const after = target.get(path);
+        const mine = current.get(path);
+        if (before && after && sameContent(before, after))
+            continue;
+        if (!before && after) {
+            if (!mine)
+                actions.push({ path, kind: "create", content: after });
+            else if (!sameContent(mine, after)) {
+                actions.push(merged(path, mine, Buffer.alloc(0), after, "Your file differs from the one the new selection adds."));
+            }
+            continue;
+        }
+        if (before && !after) {
+            if (!mine)
+                continue;
+            if (sameContent(mine, before))
+                actions.push({ path, kind: "delete" });
+            else
+                actions.push({ path, kind: "keep", reason: "You changed this file, and the new selection no longer includes it. Delete it if nothing uses it." });
+            continue;
+        }
+        if (before && after) {
+            if (!mine) {
+                actions.push({ path, kind: "keep", reason: "You deleted this file, and the new selection changes it. Restore it if you need the change." });
+            }
+            else if (sameContent(mine, before)) {
+                const content = isBinary(after) ? after : withLineEndings(normalize(after), mine);
+                actions.push({ path, kind: "update", content });
+            }
+            else if (!sameContent(mine, after)) {
+                actions.push(merged(path, mine, before, after, "You changed this file, and the new selection changes it too."));
+            }
+        }
+    }
+    return actions;
+}

package/dist/core/project.js

@@ -0,0 +1,68 @@
+// 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 { pathExists } from "../utils/fs.js";
+import { displayNameFromPackageName } from "../utils/names.js";
+import { createPlan } from "./plan.js";
+export class ProjectError extends Error {
+    name = "ProjectError";
+}
+/** Finds the generated project that contains `directory` and reads its provenance. */
+export async function readProject(directory) {
+    let current = resolve(directory);
+    while (true) {
+        const manifestPath = join(current, "package.json");
+        if (await pathExists(manifestPath)) {
+            const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+            const origin = manifest.clubedge;
+            if (origin?.starterRef) {
+                if (!origin.framework || !origin.modules) {
+                    throw new ProjectError("This project was created before create-clubedge-app 0.5.0 and does not record its modules, so it cannot be changed automatically.");
+                }
+                return {
+                    root: current,
+                    identity: { packageName: manifest.name, displayName: displayNameFromPackageName(manifest.name) },
+                    cliVersion: origin.cliVersion,
+                    starterRepository: origin.starterRepository,
+                    starterRef: origin.starterRef,
+                    starterCommit: origin.starterCommit,
+                    framework: origin.framework,
+                    modules: origin.modules,
+                };
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new ProjectError("No Clubedge project found here. Run this command inside a project created by create-clubedge-app.");
+        }
+        current = parent;
+    }
+}
+/** The files the CLI generates for this selection, without writing anything. */
+export async function renderProject(input) {
+    const plan = createPlan({ ...input, targetDirectory: "", git: false, install: false });
+    const files = new Map();
+    for (const { from, to } of plan.files)
+        files.set(to, await readFile(join(input.source.root, from)));
+    for (const edit of plan.edits) {
+        const content = files.get(edit.path);
+        if (content)
+            files.set(edit.path, Buffer.from(edit.apply(content.toString("utf8"))));
+    }
+    return { files, envFile: plan.envFile };
+}
+/** Reads the project's copies of the given paths; missing files are left out. */
+export async function readProjectFiles(root, paths) {
+    const files = new Map();
+    for (const path of paths) {
+        try {
+            files.set(path, await readFile(join(root, path)));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return files;
+}

package/dist/core/source.js

@@ -63,6 +63,18 @@ export function pickTagCommit(output, tag) {
         .map(([id, ref]) => [ref, id]));
     return refs.get(`refs/tags/${tag}^{}`) ?? refs.get(`refs/tags/${tag}`);
 }
+/** Resolves a tag, branch, or full commit SHA to a commit with `git ls-remote`. */
+export async function resolveRefCommit(repository, ref) {
+    if (/^[0-9a-f]{40}$/i.test(ref))
+        return ref.toLowerCase();
+    const output = await runCapture("git", ["ls-remote", `https://github.com/${repository}.git`]);
+    return pickTagCommit(output, ref) ?? pickBranchCommit(output, ref);
+}
+/** Picks a branch's commit from `git ls-remote` output. */
+export function pickBranchCommit(output, branch) {
+    const line = output.split("\n").find((entry) => entry.trim().split(/\s+/)[1] === `refs/heads/${branch}`);
+    return line?.trim().split(/\s+/)[0];
+}
 export async function downloadGitHubTemplate(ref, { repository = starterPin.starterRepository, expectedCommit } = {}) {
     if (expectedCommit) {
         const commit = await resolveTagCommit(repository, ref);
@@ -82,7 +94,8 @@ export async function downloadGitHubTemplate(ref, { repository = starterPin.star
             files: files.map((file) => ({ from: file, to: file })),
             repository,
             ref,
-            commit: expectedCommit,
+            // Recorded in the project's provenance so later add, remove, and upgrade find this revision.
+            commit: expectedCommit ?? (await resolveRefCommit(repository, ref).catch(() => undefined)),
             cleanup,
         };
     }

package/dist/core/update.js

@@ -0,0 +1,84 @@
+// Changes an existing project from one generated state (base) to another (target): different
+// modules for add and remove, or a newer Starter for upgrade. The project's own edits survive
+// through a three-way merge, see merge.ts.
+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 { readProjectFiles, renderProject } from "./project.js";
+const LOCKFILE = "pnpm-lock.yaml";
+export async function planUpdate(project, base, target) {
+    const render = (side) => renderProject({
+        source: side.source,
+        manifest: side.manifest,
+        identity: project.identity,
+        framework: project.framework,
+        modules: side.modules,
+        cliVersion: side.cliVersion,
+    });
+    const before = await render(base);
+    const after = await render(target);
+    // The lockfile and the local env file are handled on their own below.
+    const envFile = after.envFile ?? before.envFile;
+    const special = [LOCKFILE, ...(envFile ? [envFile.to] : [])];
+    const strip = (files) => new Map([...files].filter(([path]) => !special.includes(path)));
+    const baseFiles = strip(before.files);
+    const targetFiles = strip(after.files);
+    const current = await readProjectFiles(project.root, [
+        ...new Set([...baseFiles.keys(), ...targetFiles.keys(), ...special]),
+    ]);
+    const actions = planMerge(baseFiles, targetFiles, current);
+    let lockfile = { kind: "unchanged" };
+    const baseLock = before.files.get(LOCKFILE);
+    const targetLock = after.files.get(LOCKFILE);
+    const currentLock = current.get(LOCKFILE);
+    if (targetLock && !(baseLock && sameContent(baseLock, targetLock))) {
+        lockfile =
+            baseLock && currentLock && sameContent(currentLock, baseLock)
+                ? { kind: "replace", content: targetLock }
+                : { kind: "install" };
+    }
+    let env = null;
+    if (envFile) {
+        const text = (files) => files.get(envFile.from)?.toString("utf8") ?? "";
+        const baseExample = text(before.files);
+        const targetExample = text(after.files);
+        const local = current.get(envFile.to)?.toString("utf8");
+        const update = local === undefined ? null : updateEnvFile(local, baseExample, targetExample);
+        env = { path: envFile.to, update, changed: update !== null && update.text !== local };
+    }
+    return { project, actions, lockfile, env };
+}
+/** Removes empty folders left behind by deleted files, up to the project root. */
+async function removeEmptyFolders(root, path) {
+    let folder = dirname(join(root, path));
+    while (folder.length > root.length) {
+        try {
+            if ((await readdir(folder)).length > 0)
+                return;
+            await rmdir(folder);
+        }
+        catch {
+            return;
+        }
+        folder = dirname(folder);
+    }
+}
+export async function applyUpdate(plan) {
+    const { root } = plan.project;
+    for (const action of plan.actions) {
+        const path = join(root, action.path);
+        if (action.kind === "delete") {
+            await rm(path, { force: true });
+            await removeEmptyFolders(root, action.path);
+        }
+        else if (action.kind !== "keep") {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, action.content);
+        }
+    }
+    if (plan.lockfile.kind === "replace")
+        await writeFile(join(root, LOCKFILE), plan.lockfile.content);
+    if (plan.env?.update && plan.env.changed)
+        await writeFile(join(root, plan.env.path), plan.env.update.text);
+}

package/dist/index.js

@@ -8,6 +8,7 @@ import { readTemplateManifest } from "./core/manifest.js";
 import { createPlan, describePlan, selectFramework } from "./core/plan.js";
 import { resolveTemplateSource } from "./core/source.js";
 import { cliUrl, cliVersion, siteUrl } from "./package-info.js";
+import { changeProject } from "./modify.js";
 import { initializeGit } from "./steps/git.js";
 import { detectLauncher, installDependencies, resolvePnpm } from "./steps/install.js";
 import { displayNameFromPackageName, packageNameFromDirectory } from "./utils/names.js";
@@ -199,8 +200,19 @@ export async function main(argv = process.argv.slice(2)) {
             return;
         }
         assertSupportedNode();
-        intro("Create a project with Clubedge Starter");
-        await createProject(args);
+        if (args.command.name === "create") {
+            intro("Create a project with Clubedge Starter");
+            await createProject(args);
+        }
+        else {
+            const intros = {
+                add: "Add a module to this project",
+                remove: "Remove a module from this project",
+                upgrade: "Upgrade this project to a newer Starter",
+            };
+            intro(intros[args.command.name]);
+            await changeProject(args);
+        }
     }
     catch (error) {
         console.error(`\n${error instanceof Error ? error.message : String(error)}`);

package/dist/modify.js

@@ -0,0 +1,263 @@
+// `add`, `remove`, and `upgrade` change an existing project. The project's recorded Starter
+// commit and modules (base) and the new state (target: other modules, or a newer Starter) are
+// rendered in memory, and the difference is merged into the project (see core/update.ts).
+import { confirm, isCancel, log, outro, spinner } from "@clack/prompts";
+import process from "node:process";
+import { UsageError } from "./cli/args.js";
+import { dim } from "./cli/ui.js";
+import { readTemplateManifest } from "./core/manifest.js";
+import { selectModules } from "./core/plan.js";
+import { readProject } from "./core/project.js";
+import { downloadGitHubTemplate, readDirectoryTemplate, resolveTemplateSource, } from "./core/source.js";
+import { applyUpdate, planUpdate } from "./core/update.js";
+import { cliVersion, starterPin } from "./package-info.js";
+import { installDependencies, resolvePnpm } from "./steps/install.js";
+import { commandSucceeds, runCapture } from "./utils/process.js";
+/** The Starter revision the project was generated from. */
+async function projectSource(project, templateDir) {
+    if (templateDir)
+        return readDirectoryTemplate(templateDir);
+    if (!project.starterCommit) {
+        throw new UsageError(`This project records no Starter commit (Starter "${project.starterRef}"), so the CLI cannot fetch the revision it came from. Pass --template-dir with that Starter checkout.`);
+    }
+    if (project.starterCommit === starterPin.starterCommit)
+        return resolveTemplateSource({});
+    return downloadGitHubTemplate(project.starterCommit, { repository: project.starterRepository });
+}
+/** The Starter to upgrade to: --template-dir, --ref, or the release this CLI is pinned to. */
+async function upgradeSource(args) {
+    if (args.templateDir)
+        return readDirectoryTemplate(args.templateDir);
+    return resolveTemplateSource({ ref: args.ref });
+}
+/**
+ * Renders the project's own revision with the provenance it recorded, so the generated
+ * package.json and README match the project even when the revision was fetched by commit.
+ */
+function asRecorded(source, project) {
+    return { ...source, ref: project.starterRef, commit: project.starterCommit };
+}
+/**
+ * Refuses to change a project whose changes Git cannot show and undo, unless --force: a Git
+ * repository must have no uncommitted changes, and a folder without Git needs confirmation.
+ */
+async function assertSafeToChange(project, args, interactive) {
+    if (args.force)
+        return;
+    const isRepository = await commandSucceeds("git", ["-C", project.root, "rev-parse", "--is-inside-work-tree"]);
+    if (isRepository) {
+        const status = await runCapture("git", ["-C", project.root, "status", "--porcelain"]);
+        if (status) {
+            throw new UsageError("The project has uncommitted changes. Commit or stash them first, so you can review this change with `git diff` and undo it if needed, or pass --force.");
+        }
+        return;
+    }
+    if (!interactive) {
+        throw new UsageError("The project is not a Git repository, so this change could not be undone. Pass --force to change it anyway.");
+    }
+    const proceed = await confirm({
+        message: "The project is not a Git repository, so this change cannot be undone. Continue?",
+        initialValue: false,
+    });
+    if (isCancel(proceed) || !proceed)
+        throw new UsageError("Cancelled; nothing was changed.");
+}
+/** The selection after add or remove, validated against the Starter's manifest. */
+function changedModules(manifest, project, command) {
+    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(", ")}.`);
+        }
+    }
+    else {
+        if (!module.options.none) {
+            const others = Object.keys(module.options).filter((id) => id !== project.modules[command.module]);
+            throw new UsageError(`${module.name} cannot be removed. Switch it instead, for example: add ${command.module} ${others[0] ?? module.default}`);
+        }
+        option = "none";
+    }
+    // Validates requirements between modules, such as Supabase Storage needing Supabase Auth.
+    return selectModules(manifest, { ...project.modules, [command.module]: option });
+}
+/**
+ * The project's selection in a newer Starter. Modules the project predates get their "none"
+ * option where there is one, so an upgrade never adds a service on its own.
+ */
+export function upgradedModules(manifest, project) {
+    const requested = {};
+    const introduced = [];
+    for (const [id, module] of Object.entries(manifest.modules)) {
+        const recorded = project.modules[id];
+        if (recorded === undefined) {
+            requested[id] = module.options.none ? "none" : module.default;
+            introduced.push(id);
+        }
+        else if (!module.options[recorded]) {
+            throw new UsageError(`The new Starter no longer offers ${module.name} "${recorded}". Choose one of: ${Object.keys(module.options).join(", ")}, with add ${id} <option>, before upgrading.`);
+        }
+        else {
+            requested[id] = recorded;
+        }
+    }
+    const dropped = Object.keys(project.modules).filter((id) => !manifest.modules[id]);
+    return { modules: selectModules(manifest, requested), introduced, dropped };
+}
+const verbs = {
+    create: "add",
+    update: "update",
+    merge: "merge",
+    conflict: "conflict",
+    delete: "delete",
+    keep: "keep",
+};
+function describe(plan) {
+    const lines = plan.actions.map((action) => `${verbs[action.kind].padEnd(8)} ${action.path}`);
+    if (plan.lockfile.kind === "replace")
+        lines.push(`${"update".padEnd(8)} pnpm-lock.yaml`);
+    if (plan.lockfile.kind === "install")
+        lines.push(`${"install".padEnd(8)} pnpm-lock.yaml ${dim("(pnpm install reconciles your dependency changes)")}`);
+    const env = plan.env?.update;
+    if (plan.env && env && plan.env.changed) {
+        const parts = [
+            env.added.length ? `adds ${env.added.join(", ")}` : "",
+            env.updated.length ? `updates ${env.updated.join(", ")}` : "",
+            env.removed.length ? `removes ${env.removed.join(", ")}` : "",
+        ].filter(Boolean);
+        lines.push(`${"update".padEnd(8)} ${plan.env.path} ${dim(`(${parts.join("; ")})`)}`);
+    }
+    return lines.join("\n");
+}
+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")}`);
+    }
+    if (kept.length) {
+        log.info(`Check these files by hand:\n${kept.map((action) => `  ${action.path}: ${action.reason}`).join("\n")}`);
+    }
+    if (plan.env && !plan.env.update) {
+        log.info(`${plan.env.path} does not exist yet; create it from the example file.`);
+    }
+    const env = plan.env?.update;
+    if (plan.env && env?.customized.length) {
+        log.info(`You set your own ${env.customized.join(", ")} in ${plan.env.path}; the example's value changed, so check whether yours still fits.`);
+    }
+    if (plan.env && env?.unused.length) {
+        log.info(`The project no longer uses ${env.unused.join(", ")}, which you set in ${plan.env.path}. Remove them when you no longer need them.`);
+    }
+}
+/** Works out what the command changes; resolves null when the project is already there. */
+async function planChange(project, command, base, target) {
+    const baseManifest = await readTemplateManifest(base.root);
+    const baseSide = { source: asRecorded(base, project), manifest: baseManifest, modules: project.modules, cliVersion: project.cliVersion };
+    if (command.name !== "upgrade") {
+        const modules = changedModules(baseManifest, project, command);
+        const changed = Object.keys(modules).filter((id) => modules[id] !== project.modules[id]);
+        if (!changed.length)
+            return null;
+        return {
+            base: baseSide,
+            target: { ...baseSide, modules, cliVersion },
+            summary: changed.map((id) => `${baseManifest.modules[id].name}: ${project.modules[id]} -> ${modules[id]}`).join(", "),
+            notes: [],
+        };
+    }
+    if (!target)
+        throw new Error("upgrade needs a target Starter.");
+    if (!target.commit && target.kind === "github") {
+        throw new UsageError(`Could not resolve Starter "${target.ref}" to a commit. Use a tag, a branch, or a full commit SHA.`);
+    }
+    if (target.commit && target.commit === project.starterCommit)
+        return null;
+    const targetManifest = await readTemplateManifest(target.root);
+    const { modules, introduced, dropped } = upgradedModules(targetManifest, project);
+    const notes = [
+        ...introduced.map((id) => {
+            const module = targetManifest.modules[id];
+            return `Starter ${target.ref} adds ${module.name}; the project uses "${modules[id]}". Choose another option with: add ${id} <option>`;
+        }),
+        ...dropped.map((id) => `Starter ${target.ref} no longer has the ${id} module; its files are merged away like any other change.`),
+    ];
+    if (/^v\d/.test(target.ref)) {
+        notes.push(`Release notes: https://github.com/${target.repository}/releases/tag/${target.ref}`);
+    }
+    return {
+        base: baseSide,
+        target: { source: target, manifest: targetManifest, modules, cliVersion },
+        summary: `Starter ${project.starterRef} -> ${target.ref}`,
+        notes,
+    };
+}
+export async function changeProject(args) {
+    const command = args.command;
+    if (command.name === "create")
+        throw new Error("Not a project change.");
+    const interactive = Boolean(process.stdin.isTTY) && !args.yes;
+    const project = await readProject(process.cwd());
+    await assertSafeToChange(project, args, interactive);
+    const upgrading = command.name === "upgrade";
+    const progress = spinner();
+    progress.start(upgrading ? "Preparing both Starter revisions" : `Preparing Starter ${project.starterRef}`);
+    const sources = [];
+    let spinning = true;
+    try {
+        // For upgrade, --template-dir names the new Starter; the project's own comes from GitHub.
+        const base = await projectSource(project, upgrading ? undefined : args.templateDir);
+        sources.push(base);
+        const target = upgrading ? await upgradeSource(args) : null;
+        if (target)
+            sources.push(target);
+        const change = await planChange(project, command, base, target);
+        spinning = false;
+        if (!change) {
+            progress.stop("Starter ready");
+            outro(upgrading ? `The project is already on Starter ${project.starterRef}.` : "The project already uses that selection; nothing to change.");
+            return;
+        }
+        progress.stop("Starter ready");
+        const plan = await planUpdate(project, change.base, change.target);
+        log.message(`${change.summary}\n\n${describe(plan) || "No file changes."}`);
+        if (args.dryRun) {
+            for (const note of change.notes)
+                log.info(note);
+            outro("Dry run: nothing was changed. Run again without --dry-run to apply.");
+            return;
+        }
+        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.");
+            else {
+                await installDependencies(project.root, pnpm, plan.lockfile.kind === "install" ? ["--no-frozen-lockfile"] : []);
+                log.success("Dependencies updated");
+            }
+        }
+        else if (plan.lockfile.kind !== "unchanged") {
+            log.info("Run `pnpm install` to update dependencies.");
+        }
+        report(plan);
+        for (const note of change.notes)
+            log.info(note);
+        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.");
+    }
+    catch (error) {
+        if (spinning)
+            progress.stop("Could not prepare the Starter");
+        throw error;
+    }
+    finally {
+        for (const source of sources)
+            await source.cleanup();
+    }
+}

package/dist/steps/install.js

@@ -13,7 +13,7 @@ export function detectLauncher(userAgent = process.env.npm_config_user_agent) {
     const name = userAgent?.split("/")[0];
     return name && ["npm", "pnpm", "yarn", "bun"].includes(name) ? name : null;
 }
-export async function installDependencies(directory, pnpm) {
+export async function installDependencies(directory, pnpm, args = []) {
     const [command, ...prefix] = pnpm;
-    await run(command, [...prefix, "install"], directory);
+    await run(command, [...prefix, "install", ...args], directory);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -52,7 +52,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "giget": "^2.0.0"
+    "giget": "^2.0.0",
+    "node-diff3": "^3.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",