@clubedge/create-clubedge-app 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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.
+- Remove optional peer links to packages that only left-out modules installed, so generated projects no longer install them. For example, a project without `--infra local` no longer installs PGlite through drizzle-orm, and a project without Better Auth no longer installs its optional peers.
+
 ## 0.6.0
 
 - Default to Starter `v0.6.0`, which adds the local infrastructure module and `pnpm check:services`.

package/README.md

@@ -12,27 +12,27 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.6.0
+create-clubedge-app v0.8.0
         |
         v
-Clubedge Starter v0.6.0
-commit bf5a5e801254816455cbb837902283b788ab7595
+Clubedge Starter v0.7.0
+commit 3b8114760b8151c2538b57c06620ff2b884f2d56
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.6.0` | `clubedge-starter@v0.6.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`.
 
-The `v0.6.0` tag is expected to resolve to commit
-`bf5a5e801254816455cbb837902283b788ab7595`. The CLI verifies this before
+The `v0.7.0` tag is expected to resolve to commit
+`3b8114760b8151c2538b57c06620ff2b884f2d56`. 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.6.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.7.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 ## Requirements
 
@@ -92,7 +92,7 @@ Authentication, file storage, and caching are modules. Each has a default, and a
 | `--auth`    | `supabase`, `better-auth`, `none`          | `supabase` |
 | `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
 | `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
-| `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `none` | `docker` |
+| `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `none` | `docker` |
 
 ```sh
 # Only the monorepo, UI, database, and tooling
@@ -110,7 +110,7 @@ Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 --auth <id>             Authentication: supabase (default), better-auth, or none
 --storage <id>          File storage: s3 (default), supabase, or none
 --cache <id>            Cache and rate limits: redis (default) or memory
---infra <id>            Local services: docker (default), supabase, or none
+--infra <id>            Local services: docker (default), supabase, local, or none
 --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
 --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
 --dry-run               Show what would be created without writing anything
@@ -136,13 +136,35 @@ 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.6.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.7.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
 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.
@@ -181,7 +203,7 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.6.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.7.0`, and publish the Starter release.
 
 ### CLI maintainers
 

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,16 +61,26 @@ 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
   --auth <id>             Authentication: supabase (default), better-auth, or none
   --storage <id>          File storage: s3 (default), supabase, or none
   --cache <id>            Cache and rate limits: redis (default) or memory
-  --infra <id>            Local services: docker (default), supabase, or none
+  --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/customize.js

@@ -1,5 +1,6 @@
 // Pure text transforms applied to template files. Keeping them free of I/O makes each one easy
 // to test and lets --dry-run describe them without touching the disk.
+import { pruneOptionalPeers } from "./lockfile-peers.js";
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
 export function customizeRootManifest(source, { packageName }, provenance, dockerImage, scripts = { set: {}, remove: [] }) {
     const manifest = JSON.parse(source);
@@ -75,7 +76,9 @@ export function customizeAppManifest(source, appPackage) {
 /**
  * Keeps pnpm-lock.yaml in step with the selected framework so `pnpm install --frozen-lockfile`
  * works. Importers are keyed by workspace path at two-space indentation; package entries that
- * are no longer used are harmless, and pnpm prunes them on the next lockfile update.
+ * are no longer used are harmless, and pnpm prunes them on the next lockfile update. Optional
+ * peer links to packages that only left-out importers installed are removed, so those packages
+ * are not installed either.
  */
 export function customizeLockfile(source, { remove, rename, removeDependencies = [] }) {
     const output = [];
@@ -135,7 +138,7 @@ export function customizeLockfile(source, { remove, rename, removeDependencies =
         skippingDependency = false;
         output.push(line);
     }
-    return output.join("\n");
+    return pruneOptionalPeers(output.join("\n"));
 }
 export class ConditionalError extends Error {
     name = "ConditionalError";

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/lockfile-peers.js

@@ -0,0 +1,174 @@
+// pnpm links a package's optional peer dependency whenever that peer is installed anywhere in the
+// workspace, and records the link in lockfile keys: drizzle-orm@0.45.4(@electric-sql/pglite@0.5.8).
+// When a left-out workspace package was the only reason the peer was installed, the link would
+// keep installing it, so these helpers remove such links from the lockfile.
+function unquote(text) {
+    return text.replace(/^(['"])(.*)\1$/, "$2");
+}
+/** "drizzle-orm@0.45.4(pglite@0.5.8)" -> "drizzle-orm@0.45.4"; "0.45.4(x@1)" -> "0.45.4". */
+function withoutSuffix(text) {
+    const start = text.indexOf("(");
+    return start === -1 ? text : text.slice(0, start);
+}
+function parse(source) {
+    const roots = [];
+    const optionalPeers = new Map();
+    const snapshots = new Map();
+    let section = "";
+    let key = "";
+    let group = "";
+    let entry = "";
+    for (const line of source.split("\n")) {
+        if (/^\S/.test(line)) {
+            section = line.replace(/:.*$/, "");
+            continue;
+        }
+        const keyMatch = /^ {2}(\S.*?):(?: \{\})?$/.exec(line);
+        if (keyMatch) {
+            key = unquote(keyMatch[1]);
+            group = entry = "";
+            if (section === "snapshots")
+                snapshots.set(key, snapshots.get(key) ?? []);
+            continue;
+        }
+        const groupMatch = /^ {4}(\S+):$/.exec(line);
+        if (groupMatch) {
+            group = groupMatch[1];
+            entry = "";
+            continue;
+        }
+        const entryMatch = /^ {6}(\S.*?):(?: (.*))?$/.exec(line);
+        if (entryMatch) {
+            entry = unquote(entryMatch[1]);
+            const value = entryMatch[2] ? unquote(entryMatch[2]) : "";
+            if (section === "snapshots" && (group === "dependencies" || group === "optionalDependencies")) {
+                snapshots.get(key).push({ name: entry, ref: value });
+            }
+            continue;
+        }
+        const fieldMatch = /^ {8}(\S+): (.*)$/.exec(line);
+        if (!fieldMatch)
+            continue;
+        const [, field, value] = fieldMatch;
+        if (section === "importers" && field === "version")
+            roots.push(`${entry}@${unquote(value)}`);
+        if (section === "packages" && group === "peerDependenciesMeta" && field === "optional" && value === "true") {
+            const peers = optionalPeers.get(key) ?? new Set();
+            peers.add(entry);
+            optionalPeers.set(key, peers);
+        }
+    }
+    return { roots, optionalPeers, snapshots };
+}
+/**
+ * Finds optional peers that only optional-peer links keep installed: packages that no importer
+ * reaches through regular or required dependencies. Returns them as "name@version".
+ */
+export function findUnneededOptionalPeers(source) {
+    const { roots, optionalPeers, snapshots } = parse(source);
+    const reached = new Set();
+    const peerLinks = new Set();
+    const queue = roots.filter((key) => snapshots.has(key));
+    while (queue.length) {
+        const key = queue.pop();
+        if (reached.has(key))
+            continue;
+        reached.add(key);
+        const peers = optionalPeers.get(withoutSuffix(key));
+        for (const { name, ref } of snapshots.get(key) ?? []) {
+            if (peers?.has(name)) {
+                peerLinks.add(`${name}@${withoutSuffix(ref)}`);
+                continue;
+            }
+            const target = `${name}@${ref}`;
+            if (snapshots.has(target))
+                queue.push(target);
+        }
+    }
+    const reachedPackages = new Set([...reached].map(withoutSuffix));
+    return [...peerLinks].filter((peer) => !reachedPackages.has(peer)).sort();
+}
+/** Removes every "(peer)" or "(peer(...))" segment from lockfile keys and versions. */
+function removeSuffixSegments(text, peer) {
+    const marker = `(${peer}`;
+    let result = "";
+    let index = 0;
+    for (let found = text.indexOf(marker); found !== -1; found = text.indexOf(marker, index)) {
+        const next = text[found + marker.length];
+        if (next !== ")" && next !== "(") {
+            // A different package whose name merely starts with this one.
+            result += text.slice(index, found + marker.length);
+            index = found + marker.length;
+            continue;
+        }
+        let depth = 0;
+        let end = found;
+        for (; end < text.length; end++) {
+            if (text[end] === "(")
+                depth++;
+            else if (text[end] === ")" && --depth === 0)
+                break;
+        }
+        result += text.slice(index, found);
+        index = end + 1;
+    }
+    return result + text.slice(index);
+}
+/**
+ * Drops optional-peer links to packages nothing else installs (see findUnneededOptionalPeers),
+ * so `pnpm install --frozen-lockfile` no longer installs them. Snapshot entries that become
+ * identical are merged.
+ */
+export function pruneOptionalPeers(source) {
+    const peers = findUnneededOptionalPeers(source);
+    if (!peers.length)
+        return source;
+    let text = source;
+    for (const peer of peers)
+        text = removeSuffixSegments(text, peer);
+    const output = [];
+    const seenKeys = new Set();
+    let section = "";
+    let skippingEntry = false;
+    let pendingGroup = null;
+    for (const line of text.split("\n")) {
+        if (/^\S/.test(line)) {
+            section = line.replace(/:.*$/, "");
+            skippingEntry = false;
+            pendingGroup = null;
+            output.push(line);
+            continue;
+        }
+        if (section !== "snapshots") {
+            output.push(line);
+            continue;
+        }
+        const keyMatch = /^ {2}(\S.*?):(?: \{\})?$/.exec(line);
+        if (keyMatch) {
+            pendingGroup = null;
+            // Removing a link can make two snapshot keys identical; keep the first entry.
+            skippingEntry = seenKeys.has(keyMatch[1]);
+            seenKeys.add(keyMatch[1]);
+            if (!skippingEntry)
+                output.push(line);
+            continue;
+        }
+        if (skippingEntry)
+            continue;
+        if (/^ {4}\S+:$/.test(line)) {
+            // Held until the group gets an entry, so a group whose only entry was removed disappears.
+            pendingGroup = line;
+            continue;
+        }
+        const dependency = /^ {6}(\S.*?): (.*)$/.exec(line);
+        if (dependency && peers.includes(`${unquote(dependency[1])}@${withoutSuffix(unquote(dependency[2]))}`)) {
+            continue;
+        }
+        if (pendingGroup !== null && line.trim() !== "") {
+            output.push(pendingGroup);
+            pendingGroup = null;
+        }
+        output.push(line);
+    }
+    return output.join("\n");
+}

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;
+}