ember.nvp 0.5.0 → 0.6.0

package/.release-plan.json

@@ -2,17 +2,13 @@
   "solution": {
     "ember.nvp": {
       "impact": "minor",
-      "oldVersion": "0.4.0",
-      "newVersion": "0.5.0",
+      "oldVersion": "0.5.0",
+      "newVersion": "0.6.0",
       "tagName": "latest",
       "constraints": [
         {
           "impact": "minor",
           "reason": "Appears in changelog section :rocket: Enhancement"
-        },
-        {
-          "impact": "patch",
-          "reason": "Appears in changelog section :house: Internal"
         }
       ],
       "pkgJSONPath": "./package.json"
@@ -21,5 +17,5 @@
       "oldVersion": "1.0.3"
     }
   },
-  "description": "## Release (2026-06-29)\n\n* ember.nvp 0.5.0 (minor)\n\n#### :rocket: Enhancement\n* `ember.nvp`\n  * [#55](https://github.com/NullVoxPopuli/ember.nvp/pull/55) Upgrade @clack/prompts ([@tcjr](https://github.com/tcjr))\n\n#### :house: Internal\n* `ember.nvp`\n  * [#53](https://github.com/NullVoxPopuli/ember.nvp/pull/53) Add typescript to root ([@tcjr](https://github.com/tcjr))\n\n#### Committers: 1\n- Tom Carter ([@tcjr](https://github.com/tcjr))\n"
+  "description": "## Release (2026-07-04)\n\n* ember.nvp 0.6.0 (minor)\n\n#### :rocket: Enhancement\n* `ember.nvp`\n  * [#56](https://github.com/NullVoxPopuli/ember.nvp/pull/56) Stage all generation in a copy-on-write overlay; confirm before writing ([@NullVoxPopuli-ai-agent](https://github.com/NullVoxPopuli-ai-agent))\n\n#### Committers: 1\n- @NullVoxPopuli's reduced-access machine account for AI usage ([@NullVoxPopuli-ai-agent](https://github.com/NullVoxPopuli-ai-agent))\n"
 }

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Release (2026-07-04)
+
+* ember.nvp 0.6.0 (minor)
+
+#### :rocket: Enhancement
+* `ember.nvp`
+  * [#56](https://github.com/NullVoxPopuli/ember.nvp/pull/56) Stage all generation in a copy-on-write overlay; confirm before writing ([@NullVoxPopuli-ai-agent](https://github.com/NullVoxPopuli-ai-agent))
+
+#### Committers: 1
+- @NullVoxPopuli's reduced-access machine account for AI usage ([@NullVoxPopuli-ai-agent](https://github.com/NullVoxPopuli-ai-agent))
+
 ## Release (2026-06-29)
 
 * ember.nvp 0.5.0 (minor)

package/README.md

@@ -30,6 +30,18 @@ pnpm dlx NullVoxPopuli/ember.nvp
 npx NullVoxPopuli/ember.nvp
 ```
 
+### Updating an existing project
+
+You can run `ember.nvp` on top of an existing project to add layers to it. Generation never writes directly to your project -- everything runs in a staging directory first, and before finishing you choose to:
+
+- **write the files** -- apply all of the staged changes
+- **review the diff** -- step through each changed file's diff, accepting or rejecting it individually (or accept/reject everything remaining)
+- **cancel** -- discard everything; your project is untouched
+
+Only files that actually changed are written. `node_modules`, `.git`, and everything else in your project are left alone, and the accepted changes land as uncommitted edits for you to review with your own git tooling.
+
+New projects skip the confirmation and are written as soon as generation succeeds. For scripting, `--write yes` / `--write no` answers the confirmation up front.
+
 ### Wrapping
 
 The provided CLI is only a wrapper around our exported `generateProject` function.
@@ -55,6 +67,23 @@ await generateProject(new Project(
 
 All parts of the generator are idempotent, so running generators on existing projects _can_ no-op.
 
+To get the same don't-write-until-confirmed behavior as the CLI, wrap generation in a `Stage`. A stage is a real directory in the OS temp dir, seeded with a copy of the target directory's current contents (sans `node_modules`/`.git`) -- so layers run against the project's existing state with plain `node:fs`, `ember-apply`, and subprocesses, and authoring a layer is exactly the same with or without one.
+
+```js
+import { generateProject, Project, Stage } from "ember.nvp";
+
+const stage = await Stage.create(directoryToGenerateIn);
+
+await generateProject(new Project(stage.directory, { name, path, type, layers, packageManager }));
+
+const changes = await stage.changes(); // [{ path, status: 'added' | 'modified' | 'deleted' }]
+console.log(await stage.diff(changes)); // unified diff against the target directory
+
+await stage.commit(); // write the changes to the target directory
+// or: await stage.commit(someOfTheChanges)  -- write only an accepted subset
+// or: await stage.discard()                 -- throw everything away, touching nothing
+```
+
 ## Reqs
 
 - node 24+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember.nvp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "ember project generator, alternative to the official blueprints, but more modern -- hopefully one day to upstream back in to ember-cli / official blueprints",
   "repository": {
     "type": "git",
@@ -22,6 +22,7 @@
     "@clack/prompts": "^1.6.0",
     "babel-remove-types": "^2.0.0",
     "content-tag": "^4.2.0",
+    "diff": "^9.0.0",
     "ember-apply": "^2.17.0",
     "execa": "^9.6.1",
     "latest-version": "^9.0.0",

package/src/cli/args.js

@@ -35,10 +35,15 @@ const { values } = parseArgs({
       type: "string",
       choices: ["replace", "update"],
     },
+
+    write: {
+      type: "string",
+      choices: ["yes", "no"],
+    },
   },
 });
 
-const { replaceOrUpdate, name, type, layers = [], packageManager, path, confirm } = values;
+const { replaceOrUpdate, name, type, layers = [], packageManager, path, confirm, write } = values;
 
 export const answers = {
   name,
@@ -48,6 +53,7 @@ export const answers = {
   path,
   confirm,
   replaceOrUpdate,
+  write,
 };
 
 /**

package/src/cli/index.js

@@ -8,8 +8,11 @@ import { askProjectType } from "./questions/project-type.js";
 import { askPackageManager } from "./questions/package-manager.js";
 import { askPath } from "./questions/path.js";
 import { askIfOK } from "./questions/ok.js";
+import { askToWrite } from "./questions/write.js";
 import { styleText } from "node:util";
+import { rm } from "node:fs/promises";
 import { Project } from "#utils/project.js";
+import { Stage } from "#utils/stage.js";
 import { askReplaceOrUpdate } from "./questions/replace-or-update.js";
 
 /**
@@ -31,7 +34,26 @@ async function main() {
   const selectedLayers = await askLayers();
   const packageManager = await askPackageManager();
 
-  let project = new Project(projectPath, {
+  await askIfOK();
+
+  /**
+   * Everything is generated in a stage: a real directory (in the OS temp
+   * dir) acting as a writable overlay of the target directory.
+   *
+   * When updating an existing project, the stage is seeded with a full
+   * copy of it (sans node_modules/.git), so the bases and layers run
+   * against the project's current state -- isSetup checks, package.json
+   * reads, file existence checks, etc. all see the existing files, and
+   * the codemods modify them in the stage exactly as if they were
+   * operating in place. "replace" starts from an empty stage instead.
+   *
+   * The target itself is not touched until stage.commit() below, which
+   * applies the difference between the stage and the target (or the
+   * subset of it the user accepts during review).
+   */
+  const stage = await Stage.create(projectPath, { seed: replaceOrUpdate !== "replace" });
+
+  let project = new Project(stage.directory, {
     name: projectName,
     type: projectType,
     path: projectPath,
@@ -39,28 +61,19 @@ async function main() {
     packageManager,
   });
 
-  await askIfOK();
-
   const s = p.spinner();
   s.start("Creating your Ember app...");
 
   try {
-    // Generate the project
-    await generateProject(project, replaceOrUpdate);
-
-    s.stop("Project created!");
+    // Generate the project (into the stage)
+    await generateProject(project);
 
-    p.note(
-      `cd ${projectName}\n` +
-        `${packageManager} install\n` +
-        `${packageManager} ${packageManager === "npm" ? "run " : ""}start`,
-      "Next steps",
-    );
-
-    p.outro(styleText("green", "✓") + " Project ready! " + styleText("dim", "Happy coding!"));
+    s.stop("Project generated");
   } catch (err) {
     s.stop("Failed to create project");
 
+    await stage.discard();
+
     if (err instanceof Error) {
       p.cancel(`Error: ${err.message}`);
       if (err.stack) {
@@ -73,6 +86,48 @@ async function main() {
     p.cancel(`Error: ${String(err)}`);
     process.exit(1);
   }
+
+  const changes = await stage.changes();
+
+  if (changes.length === 0 && replaceOrUpdate !== "replace") {
+    await stage.discard();
+
+    p.outro(styleText("green", "✓") + " Already up to date -- nothing to write.");
+    return;
+  }
+
+  /**
+   * New projects (and "replace", which was already confirmed) are written
+   * without asking. Updates to an existing project must be confirmed:
+   * write all / review each change (accept/reject) / cancel.
+   */
+  const isUpdate = !stage.isNew && replaceOrUpdate !== "replace";
+
+  const toApply = isUpdate ? await askToWrite(stage, changes) : changes;
+
+  if (!toApply || toApply.length === 0) {
+    await stage.discard();
+
+    p.cancel("Cancelled -- no files were written");
+    return process.exit(0);
+  }
+
+  if (replaceOrUpdate === "replace") {
+    await rm(projectPath, { recursive: true, force: true });
+  }
+
+  await stage.commit(toApply);
+
+  p.log.success(`Applied ${toApply.length} change${toApply.length === 1 ? "" : "s"}`);
+
+  p.note(
+    `cd ${projectName}\n` +
+      `${packageManager} install\n` +
+      `${packageManager} ${packageManager === "npm" ? "run " : ""}start`,
+    "Next steps",
+  );
+
+  p.outro(styleText("green", "✓") + " Project ready! " + styleText("dim", "Happy coding!"));
 }
 
 main().catch((err) => {

package/src/cli/questions/write.js

@@ -0,0 +1,169 @@
+import * as p from "@clack/prompts";
+import { styleText } from "node:util";
+
+import { answers, printArgInUse } from "#args";
+
+const SUPPORTED = new Set(["yes", "no"]);
+
+/**
+ *
+ * @param {string | undefined} selected
+ * @returns {selected is 'yes' | 'no'}
+ */
+function isValid(selected) {
+  if (!selected) return false;
+
+  return SUPPORTED.has(selected);
+}
+
+/**
+ * Nothing has been written to the target directory yet -- everything so
+ * far only exists in the stage. Ask whether to write the staged changes,
+ * with the option to review the diff change-by-change, accepting or
+ * rejecting each one.
+ *
+ * @param {import('#utils/stage.js').Stage} stage
+ * @param {import('#utils/stage.js').Change[]} changes
+ * @returns {Promise<import('#utils/stage.js').Change[] | null>}
+ *   the changes to write, or null to cancel without writing anything
+ */
+export async function askToWrite(stage, changes) {
+  if (isValid(answers.write)) {
+    printArgInUse("write", answers.write);
+
+    return answers.write === "yes" ? changes : null;
+  }
+
+  p.note(summarize(changes), `${changes.length} staged change${changes.length === 1 ? "" : "s"}`);
+
+  const answer = await p.select({
+    message: `Write these changes to ${stage.targetDirectory}?`,
+    options: [
+      { value: "yes", label: "write the files", hint: "apply all staged changes" },
+      {
+        value: "review",
+        label: "review the diff",
+        hint: "step through each change, accepting or rejecting it",
+      },
+      { value: "no", label: "cancel", hint: "discard the staged changes, touching nothing" },
+    ],
+  });
+
+  if (p.isCancel(answer) || answer === "no") {
+    return null;
+  }
+
+  if (answer === "yes") {
+    return changes;
+  }
+
+  return reviewEachChange(stage, changes);
+}
+
+/**
+ * Show each change's diff and ask what to do with it. "accept remaining"
+ * and "reject remaining" finish the review early, so they require an
+ * extra confirmation; declining the confirmation returns to the change
+ * being reviewed.
+ *
+ * @param {import('#utils/stage.js').Stage} stage
+ * @param {import('#utils/stage.js').Change[]} changes
+ * @returns {Promise<import('#utils/stage.js').Change[] | null>}
+ *   the accepted changes, or null to cancel the whole run
+ */
+async function reviewEachChange(stage, changes) {
+  /** @type {import('#utils/stage.js').Change[]} */
+  const accepted = [];
+  let index = 0;
+
+  while (index < changes.length) {
+    const change = changes[index];
+
+    if (!change) break;
+
+    const remaining = changes.length - index;
+
+    // Bypass clack for the diff itself: diffs are long, and clack's
+    // log decorations wrap every line.
+    console.log("\n" + (await stage.diff([change])));
+
+    const answer = await p.select({
+      message: `${change.path} (${index + 1} of ${changes.length})`,
+      options: [
+        { value: "accept", label: "accept", hint: "write this change" },
+        { value: "reject", label: "reject", hint: "skip this change" },
+        ...(remaining > 1
+          ? /** @type {const} */ ([
+              {
+                value: "accept-remaining",
+                label: "accept remaining",
+                hint: `accept this and the ${remaining - 1} unreviewed change${remaining - 1 === 1 ? "" : "s"} after it`,
+              },
+              {
+                value: "reject-remaining",
+                label: "reject remaining",
+                hint: `reject this and the ${remaining - 1} unreviewed change${remaining - 1 === 1 ? "" : "s"} after it`,
+              },
+            ])
+          : []),
+      ],
+    });
+
+    if (p.isCancel(answer)) {
+      return null;
+    }
+
+    if (answer === "accept") {
+      accepted.push(change);
+      index++;
+      continue;
+    }
+
+    if (answer === "reject") {
+      index++;
+      continue;
+    }
+
+    const bulkAccept = answer === "accept-remaining";
+    const confirmed = await p.confirm({
+      message: `${bulkAccept ? "Accept" : "Reject"} all ${remaining} remaining change${remaining === 1 ? "" : "s"} without reviewing them?`,
+    });
+
+    if (p.isCancel(confirmed) || !confirmed) {
+      // return to the change being reviewed
+      continue;
+    }
+
+    if (bulkAccept) {
+      accepted.push(...changes.slice(index));
+    }
+
+    break;
+  }
+
+  p.log.info(
+    `Accepted ${accepted.length} of ${changes.length} change${changes.length === 1 ? "" : "s"}`,
+  );
+
+  return accepted;
+}
+
+/**
+ * @param {import('#utils/stage.js').Change[]} changes
+ * @returns {string}
+ */
+function summarize(changes) {
+  const colors = /** @type {const} */ ({
+    added: "green",
+    modified: "yellow",
+    deleted: "red",
+  });
+
+  return changes
+    .map((change) => {
+      const letter = change.status[0]?.toUpperCase() ?? "?";
+
+      return `${styleText(colors[change.status], letter)} ${change.path}`;
+    })
+    .join("\n");
+}

package/src/index.js

@@ -1,2 +1,3 @@
 export { generateProject } from "./cli/generator.js";
 export { Project } from "./utils/project.js";
+export { Stage } from "./utils/stage.js";

package/src/utils/stage.js

@@ -0,0 +1,317 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { styleText } from "node:util";
+import { structuredPatch } from "diff";
+
+/**
+ * Directories that belong to the target project's environment rather than
+ * its generated contents. They are never seeded into the stage, never
+ * diffed, and never deleted on commit.
+ *
+ * (`.git` has one exception: see {@link Stage#commit})
+ */
+const ENVIRONMENT_DIRECTORIES = new Set(["node_modules", ".git"]);
+
+/**
+ * @typedef {'added' | 'modified' | 'deleted'} ChangeStatus
+ * @typedef {{ path: string, status: ChangeStatus }} Change
+ */
+
+/**
+ * A copy-on-write overlay for a project directory, in the spirit of
+ * Docker's layered file systems:
+ *
+ * - the target directory is the read-only lower layer
+ * - a real directory in the OS temp dir is the writable upper layer,
+ *   seeded ("copied up") from the target
+ *
+ * All generation (bases, layers, consolidators) runs against the upper
+ * layer via `stage.directory`. Because the upper layer is a real
+ * directory, layers keep using `node:fs`, `ember-apply`, and even
+ * subprocesses (`git`, package managers) exactly as they would against
+ * the real project -- an in-process virtual fs can't offer that, since
+ * child processes can't see it.
+ *
+ * Nothing touches the target until {@link Stage#commit}; {@link Stage#discard}
+ * throws the upper layer away.
+ */
+export class Stage {
+  /**
+   * @param {string} targetDirectory the directory the project should end up in
+   * @param {{ seed?: boolean }} [options]
+   *   seed: copy the target's current contents into the stage first
+   *   (a "copy up"). Defaults to true. Pass false to stage a from-scratch
+   *   generation (e.g. the "replace" flow).
+   * @returns {Promise<Stage>}
+   */
+  static async create(targetDirectory, options = {}) {
+    const { seed = true } = options;
+    const directory = await mkdtemp(join(tmpdir(), "ember.nvp-stage-"));
+    const exists = existsSync(targetDirectory);
+
+    if (exists && seed) {
+      await cp(targetDirectory, directory, {
+        recursive: true,
+        force: true,
+        filter: (source) => !ENVIRONMENT_DIRECTORIES.has(basename(source)),
+      });
+    }
+
+    return new Stage(targetDirectory, directory, { isNew: !exists });
+  }
+
+  #target;
+  #directory;
+  #isNew;
+
+  /**
+   * Use {@link Stage.create} instead.
+   *
+   * @param {string} target
+   * @param {string} directory
+   * @param {{ isNew: boolean }} info
+   */
+  constructor(target, directory, info) {
+    this.#target = target;
+    this.#directory = directory;
+    this.#isNew = info.isNew;
+  }
+
+  /**
+   * The writable upper layer. Generate in here,
+   * e.g. `new Project(stage.directory, desires)`.
+   *
+   * @type {string}
+   */
+  get directory() {
+    return this.#directory;
+  }
+
+  /**
+   * The directory a commit writes to.
+   *
+   * @type {string}
+   */
+  get targetDirectory() {
+    return this.#target;
+  }
+
+  /**
+   * Whether the target directory existed when the stage was created.
+   *
+   * @type {boolean}
+   */
+  get isNew() {
+    return this.#isNew;
+  }
+
+  /**
+   * Compares the upper layer to the target.
+   *
+   * @returns {Promise<Change[]>}
+   */
+  async changes() {
+    const staged = await listFiles(this.#directory);
+    const existing = existsSync(this.#target) ? await listFiles(this.#target) : new Set();
+
+    /** @type {Change[]} */
+    const changes = [];
+
+    for (const path of staged) {
+      if (!existing.has(path)) {
+        changes.push({ path, status: "added" });
+        continue;
+      }
+
+      const [before, after] = await Promise.all([
+        readFile(join(this.#target, path)),
+        readFile(join(this.#directory, path)),
+      ]);
+
+      if (!before.equals(after)) {
+        changes.push({ path, status: "modified" });
+      }
+    }
+
+    for (const path of existing) {
+      if (!staged.has(path)) {
+        changes.push({ path, status: "deleted" });
+      }
+    }
+
+    return changes.sort((a, b) => a.path.localeCompare(b.path));
+  }
+
+  /**
+   * A unified diff of the staged changes against the target,
+   * colorized when stdout supports it.
+   *
+   * @param {Change[]} [changes] pass the result of {@link Stage#changes} to avoid recomputing
+   * @returns {Promise<string>}
+   */
+  async diff(changes) {
+    changes ??= await this.changes();
+
+    const patches = [];
+
+    for (const change of changes) {
+      const before =
+        change.status === "added" ? null : await readFile(join(this.#target, change.path));
+      const after =
+        change.status === "deleted" ? null : await readFile(join(this.#directory, change.path));
+
+      patches.push(renderPatch(change, before, after));
+    }
+
+    return patches.join("\n");
+  }
+
+  /**
+   * Applies the staged changes to the target directory, then removes the
+   * stage. Only paths reported by {@link Stage#changes} are touched --
+   * everything else in the target (untracked files, node_modules, .git)
+   * is left alone.
+   *
+   * One exception: when the stage has a `.git` directory and the target
+   * does not (the git layer ran `git init` inside the stage), the `.git`
+   * directory is carried over so a freshly generated project keeps its
+   * history.
+   *
+   * @param {Change[]} [changes] the changes to apply -- pass a subset of
+   *   {@link Stage#changes} to apply only some of them (e.g. the ones a
+   *   user accepted during review). Defaults to all staged changes.
+   * @returns {Promise<Change[]>} the changes that were written
+   */
+  async commit(changes) {
+    changes ??= await this.changes();
+
+    await mkdir(this.#target, { recursive: true });
+
+    for (const change of changes) {
+      const targetPath = join(this.#target, change.path);
+
+      if (change.status === "deleted") {
+        await rm(targetPath, { force: true });
+        continue;
+      }
+
+      await mkdir(dirname(targetPath), { recursive: true });
+      await cp(join(this.#directory, change.path), targetPath, { force: true });
+    }
+
+    const stagedGit = join(this.#directory, ".git");
+    const targetGit = join(this.#target, ".git");
+
+    if (existsSync(stagedGit) && !existsSync(targetGit)) {
+      await cp(stagedGit, targetGit, { recursive: true });
+    }
+
+    await this.discard();
+
+    return changes;
+  }
+
+  /**
+   * Removes the stage without writing anything to the target.
+   */
+  async discard() {
+    await rm(this.#directory, { recursive: true, force: true });
+  }
+}
+
+/**
+ * All files (as paths relative to `directory`), excluding environment
+ * directories. Includes dotfiles (`.gitignore`, `.github/`, ...), which
+ * `fs.glob` would skip.
+ *
+ * @param {string} directory
+ * @returns {Promise<Set<string>>}
+ */
+async function listFiles(directory) {
+  /** @type {Set<string>} */
+  const files = new Set();
+
+  const entries = await readdir(directory, { withFileTypes: true, recursive: true });
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+
+    const path = relative(directory, join(entry.parentPath, entry.name));
+
+    if (path.split(sep).some((segment) => ENVIRONMENT_DIRECTORIES.has(segment))) {
+      continue;
+    }
+
+    files.add(path);
+  }
+
+  return files;
+}
+
+/**
+ * @param {Change} change
+ * @param {Buffer | null} before
+ * @param {Buffer | null} after
+ * @returns {string}
+ */
+function renderPatch(change, before, after) {
+  const header = styleText("bold", `${statusLabel(change.status)} ${change.path}`);
+
+  if (before?.includes(0) || after?.includes(0)) {
+    return `${header}\n${styleText("dim", "(binary file)")}\n`;
+  }
+
+  const patch = structuredPatch(
+    change.path,
+    change.path,
+    before?.toString() ?? "",
+    after?.toString() ?? "",
+    undefined,
+    undefined,
+    { context: 3 },
+  );
+
+  const lines = [
+    header,
+    styleText("red", `--- ${change.status === "added" ? "/dev/null" : `a/${change.path}`}`),
+    styleText("green", `+++ ${change.status === "deleted" ? "/dev/null" : `b/${change.path}`}`),
+  ];
+
+  for (const hunk of patch.hunks) {
+    lines.push(
+      styleText(
+        "cyan",
+        `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`,
+      ),
+    );
+
+    for (const line of hunk.lines) {
+      if (line.startsWith("+")) {
+        lines.push(styleText("green", line));
+      } else if (line.startsWith("-")) {
+        lines.push(styleText("red", line));
+      } else {
+        lines.push(line);
+      }
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * @param {ChangeStatus} status
+ * @returns {string}
+ */
+function statusLabel(status) {
+  switch (status) {
+    case "added":
+      return styleText("green", "A");
+    case "modified":
+      return styleText("yellow", "M");
+    case "deleted":
+      return styleText("red", "D");
+  }
+}

package/test/ember.nvp/stage.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+import { Stage } from "ember.nvp";
+import { mktemp } from "#test-helpers";
+
+async function makeTargetProject() {
+  const target = join(await mktemp("stage-target"), "my-app");
+
+  await mkdir(join(target, "app"), { recursive: true });
+  await mkdir(join(target, "node_modules/some-dep"), { recursive: true });
+  await writeFile(join(target, "package.json"), `{ "name": "my-app" }`);
+  await writeFile(join(target, "app/app.js"), `export default class App {}`);
+  await writeFile(join(target, "tsconfig.json"), `{}`);
+  await writeFile(join(target, "node_modules/some-dep/index.js"), `module.exports = 1;`);
+
+  return target;
+}
+
+describe("Stage", () => {
+  describe("a new project (target does not exist)", () => {
+    it("stages writes without touching the target, then commits them", async () => {
+      const target = join(await mktemp("stage-new"), "my-app");
+      const stage = await Stage.create(target);
+
+      expect(stage.isNew).toBe(true);
+
+      await mkdir(join(stage.directory, "app"), { recursive: true });
+      await writeFile(join(stage.directory, "package.json"), `{ "name": "my-app" }`);
+      await writeFile(join(stage.directory, "app/app.js"), `export default class App {}`);
+
+      expect(existsSync(target), "target is untouched while staged").toBe(false);
+
+      const changes = await stage.changes();
+
+      expect(changes).toEqual([
+        { path: "app/app.js", status: "added" },
+        { path: "package.json", status: "added" },
+      ]);
+
+      await stage.commit();
+
+      expect(await readFile(join(target, "package.json"), "utf-8")).toBe(`{ "name": "my-app" }`);
+      expect(existsSync(join(target, "app/app.js"))).toBe(true);
+      expect(existsSync(stage.directory), "stage is cleaned up after commit").toBe(false);
+    });
+
+    it("carries a git repo initialized in the stage over to the target", async () => {
+      const target = join(await mktemp("stage-git"), "my-app");
+      const stage = await Stage.create(target);
+
+      await writeFile(join(stage.directory, "readme.md"), `hi`);
+      execSync("git init --initial-branch=main", { cwd: stage.directory, stdio: "pipe" });
+
+      await stage.commit();
+
+      expect(existsSync(join(target, ".git"))).toBe(true);
+      expect(existsSync(join(target, "readme.md"))).toBe(true);
+    });
+  });
+
+  describe("an existing project (seeded stage)", () => {
+    it("seeds the target's files, excluding node_modules and .git", async () => {
+      const target = await makeTargetProject();
+      execSync("git init --initial-branch=main", { cwd: target, stdio: "pipe" });
+
+      const stage = await Stage.create(target);
+
+      expect(stage.isNew).toBe(false);
+      expect(existsSync(join(stage.directory, "package.json"))).toBe(true);
+      expect(existsSync(join(stage.directory, "app/app.js"))).toBe(true);
+      expect(existsSync(join(stage.directory, "node_modules"))).toBe(false);
+      expect(existsSync(join(stage.directory, ".git"))).toBe(false);
+
+      await stage.discard();
+    });
+
+    it("detects added, modified, and deleted files", async () => {
+      const target = await makeTargetProject();
+      const stage = await Stage.create(target);
+
+      await writeFile(join(stage.directory, ".prettierrc.js"), `export default {};`);
+      await writeFile(join(stage.directory, "package.json"), `{ "name": "renamed" }`);
+      await rm(join(stage.directory, "tsconfig.json"));
+
+      const changes = await stage.changes();
+
+      expect(changes).toEqual([
+        { path: ".prettierrc.js", status: "added" },
+        { path: "package.json", status: "modified" },
+        { path: "tsconfig.json", status: "deleted" },
+      ]);
+
+      await stage.discard();
+    });
+
+    it("commit only touches changed paths, preserving node_modules and unrelated files", async () => {
+      const target = await makeTargetProject();
+      const stage = await Stage.create(target);
+
+      await writeFile(join(stage.directory, "package.json"), `{ "name": "renamed" }`);
+      await rm(join(stage.directory, "tsconfig.json"));
+
+      await stage.commit();
+
+      expect(await readFile(join(target, "package.json"), "utf-8")).toBe(`{ "name": "renamed" }`);
+      expect(
+        existsSync(join(target, "tsconfig.json")),
+        "deleted in stage -> deleted in target",
+      ).toBe(false);
+      expect(existsSync(join(target, "app/app.js")), "unchanged files are untouched").toBe(true);
+      expect(
+        existsSync(join(target, "node_modules/some-dep/index.js")),
+        "node_modules survives commit",
+      ).toBe(true);
+    });
+
+    it("commit applies only the given subset of changes", async () => {
+      const target = await makeTargetProject();
+      const stage = await Stage.create(target);
+
+      await writeFile(join(stage.directory, ".prettierrc.js"), `export default {};`);
+      await writeFile(join(stage.directory, "package.json"), `{ "name": "renamed" }`);
+      await rm(join(stage.directory, "tsconfig.json"));
+
+      const changes = await stage.changes();
+      const accepted = changes.filter((change) => change.path !== "package.json");
+
+      await stage.commit(accepted);
+
+      expect(existsSync(join(target, ".prettierrc.js")), "accepted addition is written").toBe(true);
+      expect(existsSync(join(target, "tsconfig.json")), "accepted deletion is applied").toBe(false);
+      expect(
+        await readFile(join(target, "package.json"), "utf-8"),
+        "rejected change is not applied",
+      ).toBe(`{ "name": "my-app" }`);
+    });
+
+    it("discard leaves the target exactly as it was", async () => {
+      const target = await makeTargetProject();
+      const stage = await Stage.create(target);
+
+      await writeFile(join(stage.directory, "package.json"), `{ "name": "renamed" }`);
+
+      await stage.discard();
+
+      expect(await readFile(join(target, "package.json"), "utf-8")).toBe(`{ "name": "my-app" }`);
+      expect(existsSync(stage.directory)).toBe(false);
+    });
+
+    it("reports no changes when nothing was modified", async () => {
+      const target = await makeTargetProject();
+      const stage = await Stage.create(target);
+
+      expect(await stage.changes()).toEqual([]);
+
+      await stage.discard();
+    });
+  });
+
+  describe("diff", () => {
+    it("renders a unified diff for added, modified, and deleted files", async () => {
+      const target = await makeTargetProject();
+      const stage = await Stage.create(target);
+
+      await writeFile(join(stage.directory, ".prettierrc.js"), `export default {};`);
+      await writeFile(join(stage.directory, "package.json"), `{ "name": "renamed" }`);
+      await rm(join(stage.directory, "tsconfig.json"));
+
+      const diff = await stage.diff();
+
+      expect(diff).toContain(`+++ b/.prettierrc.js`);
+      expect(diff).toContain(`+export default {};`);
+
+      expect(diff).toContain(`--- a/package.json`);
+      expect(diff).toContain(`-{ "name": "my-app" }`);
+      expect(diff).toContain(`+{ "name": "renamed" }`);
+
+      expect(diff).toContain(`--- a/tsconfig.json`);
+      expect(diff).toContain(`+++ /dev/null`);
+
+      await stage.discard();
+    });
+  });
+});