ember.nvp 1.14.0 → 1.15.0

package/.release-plan.json

@@ -2,8 +2,8 @@
   "solution": {
     "ember.nvp": {
       "impact": "minor",
-      "oldVersion": "1.13.0",
-      "newVersion": "1.14.0",
+      "oldVersion": "1.14.0",
+      "newVersion": "1.15.0",
       "tagName": "latest",
       "constraints": [
         {
@@ -23,5 +23,5 @@
       "oldVersion": "1.2.0"
     }
   },
-  "description": "## Release (2026-09-30)\n\n* ember.nvp 1.14.0 (minor)\n\n#### :rocket: Enhancement\n* `ember.nvp`\n  * [#156](https://github.com/NullVoxPopuli/ember.nvp/pull/156) Give TypeScript libraries with tests a publish tsconfig ([@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"
+  "description": "## Release (2026-10-02)\n\n* ember.nvp 1.15.0 (minor)\n\n#### :rocket: Enhancement\n* `ember.nvp`\n  * [#158](https://github.com/NullVoxPopuli/ember.nvp/pull/158) Migrate projects from the older blueprints ([@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-10-02)
+
+* ember.nvp 1.15.0 (minor)
+
+#### :rocket: Enhancement
+* `ember.nvp`
+  * [#158](https://github.com/NullVoxPopuli/ember.nvp/pull/158) Migrate projects from the older blueprints ([@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-09-30)
 
 * ember.nvp 1.14.0 (minor)

package/README.md

@@ -59,6 +59,29 @@ The accepted changes land as uncommitted edits, for you to review with your own
 New projects skip the confirmation, and are written as soon as generation succeeds.
 For scripting, `--write yes` / `--write no` answers the confirmation up front.
 
+### Migrating from an older blueprint
+
+Run ember.nvp in a project from one of these blueprints, and choose update:
+
+| Blueprint                                                                       | Becomes   |
+| ------------------------------------------------------------------------------- | --------- |
+| `@ember/addon-blueprint`, and the addon package of `@embroider/addon-blueprint` | a library |
+| `@ember-tooling/classic-build-addon-blueprint` (classic addons)                 | a library |
+| `@ember/app-blueprint` (Vite with `@embroider/compat`)                          | an app    |
+| `@ember-tooling/classic-build-app-blueprint` (classic apps)                     | an app    |
+
+ember.nvp checks the project before it asks about layers.
+When the project uses something that ember.nvp does not support, such as v1 addons or `.hbs` templates, ember.nvp lists each item with what to do, and writes nothing.
+Most of these items also work in the old setup, so you can fix them there first.
+
+Otherwise, the migration keeps your code, and replaces the old build:
+
+- libraries build with tsdown, and keep `addon-main.cjs`, so that apps with ember-cli can still use them
+- apps build with Vite, without `@embroider/compat`
+
+The layers that replace the old tooling, such as qunit for the tests, start selected.
+After writing, ember.nvp lists what is left for you, such as settings to copy by hand.
+
 ### Wrapping
 
 The provided CLI is only a wrapper around the exported `generateProject` function.
@@ -84,6 +107,11 @@ await generateProject(new Project(
 
 All parts of the generator are idempotent, so running generators on existing projects _can_ no-op.
 
+A project from an older blueprint is migrated first.
+`generateProject` returns `{ todo }`, the list of what is left for the user.
+When the project needs changes before it can migrate, `generateProject` throws a `MigrationError` with a `findings` list, and changes nothing.
+`checkMigration(project)` gives the same lists without changing anything, and `formatFindings(findings)` prints them the way the CLI does.
+
 To get the same don't-write-until-confirmed behavior as the CLI, wrap generation in a `Stage`.
 A stage is a scratch copy of the target directory (without `node_modules` and `.git`).
 Layers run against that copy, and the target directory is untouched until you commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember.nvp",
-  "version": "1.14.0",
+  "version": "1.15.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",
@@ -13,6 +13,7 @@
     "#bases/*": "./src/bases/*/index.js",
     "#consolidators/*": "./src/consolidators/*",
     "#layers": "./src/layers/index.js",
+    "#migration-from": "./src/migration-from/index.js",
     "#types": "./src/utils/types.ts",
     "#utils/*": "./src/utils/*",
     "#test-helpers": "./test/test-helpers.ts"

package/src/cli/generator.js

@@ -1,13 +1,19 @@
 import { mkdir, rm } from "node:fs/promises";
 
 import { bases } from "#bases";
+import { migrate } from "#migration-from";
 import { consolidateLintingScripts } from "../consolidators/linting.js";
 import { hasGit } from "#utils/git.js";
 /**
  * Generate project files by running layer functions
  *
+ * A project from an older blueprint is migrated first.
+ * When it uses features that ember.nvp does not support,
+ * this throws a `MigrationError` that lists them, before anything changes.
+ *
  * @param {import('#utils/project.js').Project} project
  * @param {string} [replaceOrUpdate]
+ * @returns {Promise<{ todo: import('#types').Finding[] }>} work left for the user after a migration
  */
 export async function generateProject(project, replaceOrUpdate) {
   if (replaceOrUpdate === "replace") {
@@ -16,6 +22,8 @@ export async function generateProject(project, replaceOrUpdate) {
 
   await mkdir(project.directory, { recursive: true });
 
+  let migration = await migrate(project);
+
   await bases[project.desires.type].run(project);
 
   /**
@@ -51,6 +59,8 @@ export async function generateProject(project, replaceOrUpdate) {
       `[ember.nvp] Consolidation commit -- Please report issues to https://github.com/NullVoxPopuli/ember.nvp/`,
     );
   }
+
+  return { todo: migration?.report.todo ?? [] };
 }
 
 /**

package/src/cli/index.js

@@ -17,6 +17,8 @@ import { cwd } from "#utils/cwd.js";
 import { Project } from "#utils/project.js";
 import { Stage } from "#utils/stage.js";
 import { askAboutProjectHere, askReplaceOrUpdate } from "./questions/replace-or-update.js";
+import { checkForMigration, showTodo } from "./questions/migration.js";
+import { MigrationError } from "#migration-from";
 
 /**
  * This whole file's primary purpose is to be an interactive CLI
@@ -35,7 +37,11 @@ async function main() {
   const projectPath = here ? cwd : await askPath(projectName);
   const replaceOrUpdate = here ?? (await askReplaceOrUpdate(projectPath));
   const projectType = await askProjectType(replaceOrUpdate === "update" ? projectPath : undefined);
-  const selectedLayers = await askLayers(projectType);
+  const migrationLayers =
+    replaceOrUpdate === "update"
+      ? await checkForMigration(projectPath, projectName, projectType)
+      : [];
+  const selectedLayers = await askLayers(projectType, migrationLayers);
   const packageManager = await askPackageManager();
 
   // Layer options start from what the project already uses
@@ -82,9 +88,12 @@ async function main() {
   const s = p.spinner();
   s.start("Creating your Ember app...");
 
+  /** @type {import('#types').Finding[]} */
+  let todo = [];
+
   try {
     // Generate the project (into the stage)
-    await generateProject(project);
+    ({ todo } = await generateProject(project));
 
     s.stop("Project generated");
   } catch (err) {
@@ -92,6 +101,12 @@ async function main() {
 
     await stage.discard();
 
+    // the message is the list for the user, and a stack trace adds nothing to it
+    if (err instanceof MigrationError) {
+      p.cancel(err.message);
+      process.exit(1);
+    }
+
     if (err instanceof Error) {
       p.cancel(`Error: ${err.message}`);
       if (err.stack) {
@@ -141,6 +156,8 @@ async function main() {
 
   p.log.success(`Applied ${toApply.length} change${toApply.length === 1 ? "" : "s"}`);
 
+  showTodo(todo);
+
   /**
    * Converted / generated files are written expecting the project's own
    * formatting and lint pass to run right away.

package/src/cli/questions/layers.js

@@ -5,8 +5,9 @@ import * as p from "@clack/prompts";
 
 /**
  * @param {import('#types').ProjectType} projectType
+ * @param {string[]} [suggested] layers to select by default, beyond each layer's own default
  */
-export async function askLayers(projectType) {
+export async function askLayers(projectType, suggested = []) {
   const optionalLayers = (await discoverLayers()).filter(
     (layer) => typeof layer.run === "function",
   );
@@ -37,7 +38,7 @@ export async function askLayers(projectType) {
   const defaultValues = (
     await Promise.all(
       optionalLayers.map(async (layer) => {
-        let result = await layer.defaultValue?.(projectType);
+        let result = suggested.includes(layer.name) || (await layer.defaultValue?.(projectType));
 
         return result && layer.name;
       }),

package/src/cli/questions/migration.js

@@ -0,0 +1,69 @@
+import * as p from "@clack/prompts";
+import { styleText } from "node:util";
+import { checkMigration, formatFindings } from "#migration-from";
+import { Project } from "#utils/project.js";
+
+/**
+ * A project from an older blueprint is migrated during the update.
+ *
+ * The check runs before the layer questions,
+ * so that a project that ember.nvp cannot migrate stops here,
+ * with the list of what to change first.
+ *
+ * @param {string} projectPath
+ * @param {string} name
+ * @param {import('#types').ProjectType} type
+ * @returns {Promise<string[]>} layers that replace the old blueprint's tooling
+ */
+export async function checkForMigration(projectPath, name, type) {
+  let project = new Project(projectPath, {
+    name,
+    type,
+    path: projectPath,
+    layers: [],
+    packageManager: "pnpm",
+  });
+
+  let spinner = p.spinner();
+
+  spinner.start("Checking for an older blueprint");
+
+  let result = await checkMigration(project);
+
+  if (!result) {
+    spinner.stop("No older blueprint found");
+    return [];
+  }
+
+  let { migration, report } = result;
+
+  if (report.unsupported.length > 0) {
+    spinner.stop(`This project is from ${migration.label}`);
+    p.log.error(
+      `ember.nvp cannot migrate this project yet. Change these first:\n\n` +
+        formatFindings(report.unsupported),
+    );
+
+    if (report.todo.length > 0) {
+      p.log.info(
+        `After that, the migration leaves these for you:\n\n${formatFindings(report.todo)}`,
+      );
+    }
+
+    p.cancel("Nothing was written");
+    return process.exit(1);
+  }
+
+  spinner.stop(`Migrating from ${styleText("cyan", migration.label)}`);
+
+  return report.layers;
+}
+
+/**
+ * @param {import('#types').Finding[]} todo
+ */
+export function showTodo(todo) {
+  if (todo.length === 0) return;
+
+  p.note(formatFindings(todo), "Left to do after the migration");
+}

package/src/index.js

@@ -1,3 +1,4 @@
 export { generateProject } from "./cli/generator.js";
 export { Project } from "./utils/project.js";
 export { Stage } from "./utils/stage.js";
+export { checkMigration, formatFindings, MigrationError } from "./migration-from/index.js";

package/src/migration-from/addons.js

@@ -0,0 +1,154 @@
+import { existsSync, globSync } from "node:fs";
+import { join, sep } from "node:path";
+import { readJSON } from "#utils/fs.js";
+
+/**
+ * @typedef {object} Dependency
+ * @property {string} name
+ * @property {Record<string, any>} manifest
+ */
+
+/**
+ * Packages with the shape of a v1 addon that work without ember-cli
+ */
+const WORKS_WITHOUT_EMBER_CLI = new Set(["@embroider/macros"]);
+
+/**
+ * ember-cli runs v1 addons as part of its build.
+ * ember.nvp builds without ember-cli, so a v1 addon never loads.
+ *
+ * @param {Record<string, any>} manifest
+ */
+export function isV1Addon(manifest) {
+  return (
+    Boolean(manifest.keywords?.includes("ember-addon")) &&
+    manifest["ember-addon"]?.version !== 2 &&
+    !WORKS_WITHOUT_EMBER_CLI.has(manifest.name)
+  );
+}
+
+/**
+ * The manifests of the dependencies that are installed in the project.
+ *
+ * A migration decides from the project's own files.
+ * An install is extra: when there is one, it tells which dependencies are v1 addons,
+ * and which modules the addons add to an app.
+ *
+ * Only the top level of node_modules is read.
+ * Every package manager puts a project's direct dependencies there.
+ *
+ * @param {string} directory the project
+ * @param {Record<string, string>} dependencies the dependencies to look for, by name
+ * @returns {Dependency[]} empty when the project has no node_modules
+ */
+export function installedDependencies(directory, dependencies) {
+  let modules = join(directory, "node_modules");
+
+  if (!existsSync(modules)) return [];
+
+  /** @type {Dependency[]} */
+  let found = [];
+
+  for (let folder of globSync(["*", "@*/*"], { cwd: modules })) {
+    let name = folder.split(sep).join("/");
+
+    if (!(name in dependencies)) continue;
+
+    let manifest = readJSON(join(modules, folder, "package.json"));
+
+    if (manifest) found.push({ name, manifest });
+  }
+
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * @param {Dependency[]} dependencies
+ * @returns {string[]} such as `ember-power-select@6.0.1`
+ */
+export function v1AddonsIn(dependencies) {
+  /** @type {string[]} */
+  let v1 = [];
+
+  for (let { name, manifest } of dependencies) {
+    if (isV1Addon(manifest)) v1.push(`${name}@${manifest.version}`);
+  }
+
+  return v1;
+}
+
+/**
+ * @typedef {object} AppModule
+ * @property {string} addon the package that provides it
+ * @property {string} path such as `services/session`
+ * @property {string | undefined} specifier the module to import it from
+ */
+
+/**
+ * Modules that v2 addons merge into an app through `ember-addon.app-js`.
+ *
+ * `@embroider/compat` merges them.
+ * An ember.nvp app does not, so the app must register the ones it looks up by name.
+ *
+ * @param {Dependency[]} dependencies
+ * @returns {AppModule[]}
+ */
+export function appModulesIn(dependencies) {
+  /** @type {AppModule[]} */
+  let modules = [];
+
+  for (let { name, manifest } of dependencies) {
+    let appJs = manifest["ember-addon"]?.["app-js"] ?? {};
+
+    for (let [appPath, file] of Object.entries(appJs)) {
+      modules.push({
+        addon: name,
+        path: appPath.replace(/^\.\//, "").replace(/\.\w+$/, ""),
+        specifier: exportedAs(name, manifest, String(file)),
+      });
+    }
+  }
+
+  return modules;
+}
+
+/**
+ * The specifier that reaches `target` through the package's `exports`.
+ *
+ *   exports: { "./*": "./dist/*.js" }, target: ./dist/_app_/services/x.js
+ *     → pkg/_app_/services/x
+ *
+ * @param {string} name
+ * @param {Record<string, any>} manifest
+ * @param {string} target a file in the package, such as `./dist/_app_/services/x.js`
+ * @returns {string | undefined}
+ */
+function exportedAs(name, manifest, target) {
+  let exports = manifest.exports;
+
+  if (!exports) return `${name}/${target.replace(/^\.\//, "")}`;
+  if (typeof exports !== "object") return;
+
+  for (let [key, value] of Object.entries(exports)) {
+    let path = typeof value === "string" ? value : (value?.import ?? value?.default);
+
+    if (typeof path !== "string" || typeof key !== "string") continue;
+
+    if (!path.includes("*")) {
+      if (path === target) return `${name}/${key.replace(/^\.\//, "")}`;
+      continue;
+    }
+
+    let [before = "", after = ""] = path.split("*");
+
+    if (
+      target.startsWith(before) &&
+      target.endsWith(after) &&
+      target.length >= before.length + after.length
+    ) {
+      let matched = target.slice(before.length, target.length - after.length);
+
+      return `${name}/${key.replace(/^\.\//, "").replace("*", matched)}`;
+    }
+  }
+}