ember.nvp 1.8.0 → 1.9.0

package/.release-plan.json

@@ -2,8 +2,8 @@
   "solution": {
     "ember.nvp": {
       "impact": "minor",
-      "oldVersion": "1.7.1",
-      "newVersion": "1.8.0",
+      "oldVersion": "1.8.0",
+      "newVersion": "1.9.0",
       "tagName": "latest",
       "constraints": [
         {
@@ -14,52 +14,14 @@
       "pkgJSONPath": "./package.json"
     },
     "@nullvoxpopuli/ember-build-tooling-utils": {
-      "impact": "minor",
-      "oldVersion": "1.1.1",
-      "newVersion": "1.2.0",
-      "tagName": "latest",
-      "constraints": [
-        {
-          "impact": "minor",
-          "reason": "Appears in changelog section :rocket: Enhancement"
-        }
-      ],
-      "pkgJSONPath": "./packages/build-tooling-utils/package.json"
+      "oldVersion": "1.2.0"
     },
     "@nullvoxpopuli/ember-rolldown": {
-      "impact": "minor",
-      "oldVersion": "2.8.1",
-      "newVersion": "2.9.0",
-      "tagName": "latest",
-      "constraints": [
-        {
-          "impact": "patch",
-          "reason": "Has dependency `workspace:*` on @nullvoxpopuli/ember-build-tooling-utils"
-        },
-        {
-          "impact": "minor",
-          "reason": "Appears in changelog section :rocket: Enhancement"
-        }
-      ],
-      "pkgJSONPath": "./packages/rolldown/package.json"
+      "oldVersion": "2.9.0"
     },
     "@nullvoxpopuli/ember-vite": {
-      "impact": "minor",
-      "oldVersion": "1.1.1",
-      "newVersion": "1.2.0",
-      "tagName": "latest",
-      "constraints": [
-        {
-          "impact": "patch",
-          "reason": "Has dependency `workspace:*` on @nullvoxpopuli/ember-build-tooling-utils"
-        },
-        {
-          "impact": "minor",
-          "reason": "Appears in changelog section :rocket: Enhancement"
-        }
-      ],
-      "pkgJSONPath": "./packages/vite/package.json"
+      "oldVersion": "1.2.0"
     }
   },
-  "description": "## Release (2026-09-21)\n\n* ember.nvp 1.8.0 (minor)\n* @nullvoxpopuli/ember-build-tooling-utils 1.2.0 (minor)\n* @nullvoxpopuli/ember-rolldown 2.9.0 (minor)\n* @nullvoxpopuli/ember-vite 1.2.0 (minor)\n\n#### :rocket: Enhancement\n* `ember.nvp`, `@nullvoxpopuli/ember-build-tooling-utils`, `@nullvoxpopuli/ember-rolldown`, `@nullvoxpopuli/ember-vite`\n  * [#135](https://github.com/NullVoxPopuli/ember.nvp/pull/135) Accept @babel/core 8 in the plugin packages ([@NullVoxPopuli](https://github.com/NullVoxPopuli))\n\n#### Committers: 1\n- [@NullVoxPopuli](https://github.com/NullVoxPopuli)\n"
+  "description": "## Release (2026-09-28)\n\n* ember.nvp 1.9.0 (minor)\n\n#### :rocket: Enhancement\n* `ember.nvp`\n  * [#139](https://github.com/NullVoxPopuli/ember.nvp/pull/139) CLI help ([@tcjr](https://github.com/tcjr))\n  * [#137](https://github.com/NullVoxPopuli/ember.nvp/pull/137) Add an expect-type layer for type tests ([@NullVoxPopuli-ai-agent](https://github.com/NullVoxPopuli-ai-agent))\n\n#### Committers: 2\n- @NullVoxPopuli's reduced-access machine account for AI usage ([@NullVoxPopuli-ai-agent](https://github.com/NullVoxPopuli-ai-agent))\n- Tom Carter ([@tcjr](https://github.com/tcjr))\n"
 }

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Release (2026-09-28)
+
+* ember.nvp 1.9.0 (minor)
+
+#### :rocket: Enhancement
+* `ember.nvp`
+  * [#139](https://github.com/NullVoxPopuli/ember.nvp/pull/139) CLI help ([@tcjr](https://github.com/tcjr))
+  * [#137](https://github.com/NullVoxPopuli/ember.nvp/pull/137) Add an expect-type layer for type tests ([@NullVoxPopuli-ai-agent](https://github.com/NullVoxPopuli-ai-agent))
+
+#### Committers: 2
+- @NullVoxPopuli's reduced-access machine account for AI usage ([@NullVoxPopuli-ai-agent](https://github.com/NullVoxPopuli-ai-agent))
+- Tom Carter ([@tcjr](https://github.com/tcjr))
+
 ## Release (2026-09-21)
 
 * ember.nvp 1.8.0 (minor)

package/README.md

@@ -172,6 +172,14 @@ Code formatting with:
 
 Super experimental vitest setup using [ember-vitest](https://github.com/NullVoxPopuli/ember-vitest)
 
+### expect-type (optional)
+
+Type tests for TypeScript libraries with [expect-type](https://github.com/mmkal/expect-type).
+
+- Tests live in `type-tests/`, with their own tsconfig.
+- `lint:type-tests` typechecks them, and `lint` runs it too.
+- JavaScript projects and apps get nothing.
+
 ## Architecture
 
 ### How Layers Work

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember.nvp",
-  "version": "1.8.0",
+  "version": "1.9.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",

package/src/cli/args.js

@@ -1,48 +1,81 @@
 import * as p from "@clack/prompts";
 import { styleText, parseArgs } from "node:util";
+import { printHelp } from "./help.js";
 
-const { values } = parseArgs({
-  options: {
-    name: {
-      type: "string",
-    },
+export const coreOptions = /** @type {const} */ ({
+  help: {
+    type: "boolean",
+    short: "h",
+    description: "Show CLI help and option details",
+  },
 
-    path: {
-      type: "string",
-    },
+  name: {
+    type: "string",
+    description: "Name of the project",
+  },
+
+  path: {
+    type: "string",
+    description: "Target directory path for the project",
+  },
 
-    type: {
-      type: "string",
-      choices: ["app", "addon", "library", "extension", "custom-element"],
-    },
+  type: {
+    type: "string",
+    choices: ["app", "addon", "library", "extension", "custom-element"],
+    description: "Type of project to generate",
+  },
 
-    confirm: {
-      type: "string",
-      choices: ["yes", "no"],
-    },
+  confirm: {
+    type: "string",
+    choices: ["yes", "no"],
+    description: "Bypass target confirmation step",
+  },
 
-    layers: {
-      type: "string",
-      multiple: true,
-    },
+  layers: {
+    type: "string",
+    multiple: true,
+    description: "Layers to apply to the project (repeat for multiple layers)",
+  },
 
-    packageManager: {
-      type: "string",
-      choices: ["npm", "pnpm"],
-    },
+  packageManager: {
+    type: "string",
+    choices: ["npm", "pnpm"],
+    description: "Package manager to configure for the project",
+  },
 
-    replaceOrUpdate: {
-      type: "string",
-      choices: ["replace", "update"],
-    },
+  replaceOrUpdate: {
+    type: "string",
+    choices: ["replace", "update"],
+    description: "Strategy to use if target directory exists",
+  },
 
-    write: {
-      type: "string",
-      choices: ["yes", "no"],
-    },
+  write: {
+    type: "string",
+    choices: ["yes", "no"],
+    description: "Confirm writing changes to disk",
   },
 });
 
+/**
+ * This lightweight check is here because Node's `parseArgs` is in strict mode.
+ * If a user runs `npx ember.nvp --help` alongside invalid or unknown flags,
+ * standard strict parsing would throw a `TypeError (ERR_PARSE_ARGS_UNKNOWN_OPTION)`
+ * before reaching any help handler. Pre-checking raw arguments ensures `--help`
+ * always prints successfully regardless of invalid flags.
+ */
+const isHelpRequested = process.argv.slice(2).some((arg) => arg === "--help" || arg === "-h");
+if (isHelpRequested) {
+  printHelp(coreOptions);
+  process.exit(0);
+}
+
+/**
+ * The CLI options are parsed using Node's `parseArgs` in default strict mode.
+ */
+const { values } = parseArgs({
+  options: coreOptions,
+});
+
 const { replaceOrUpdate, name, type, layers = [], packageManager, path, confirm, write } = values;
 
 export const answers = {

package/src/cli/help.js

@@ -0,0 +1,32 @@
+import { styleText } from "node:util";
+
+/**
+ * Print help text to stdout.
+ *
+ * @param {Record<string, any>} coreOptions
+ */
+export function printHelp(coreOptions) {
+  const title = styleText(["bgCyan", "black"], " ember.nvp ");
+  console.log(`${title}\n`);
+  console.log(`${styleText("bold", "Usage:")} npx ember.nvp [options]\n`);
+
+  console.log(styleText("bold", "Core Options:"));
+  for (const [name, config] of Object.entries(coreOptions)) {
+    const flag = `--${name}`;
+    const alias = config.short ? `-${config.short}, ` : "    ";
+    const typeStr = config.type ? styleText("dim", `<${config.type}>`) : "";
+    const desc = config.description || "";
+    const choices = config.choices
+      ? styleText(
+          "yellow",
+          ` [choices: ${config.choices.map((/** @type {string} */ c) => `"${c}"`).join(", ")}]`,
+        )
+      : "";
+
+    console.log(`  ${styleText("cyan", alias)}${styleText("cyan", flag)} ${typeStr}`);
+    if (desc || choices) {
+      console.log(`      ${desc}${choices}`);
+    }
+    console.log("");
+  }
+}

package/src/layers/expect-type/files/type-tests/index.test.ts

@@ -0,0 +1,4 @@
+import { expectTypeOf } from "expect-type";
+
+// Replace this with type tests for your library's exports
+expectTypeOf(1).toEqualTypeOf<number>();

package/src/layers/expect-type/files/type-tests/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["."],
+  "compilerOptions": {
+    "rootDir": "..",
+    "noEmit": true
+  }
+}

package/src/layers/expect-type/index.js

@@ -0,0 +1,104 @@
+import { packageJson } from "ember-apply";
+import { join } from "node:path";
+import { applyFolderTo } from "#utils/fs.js";
+import { getLatest } from "#utils/npm.js";
+
+const deps = {
+  "expect-type": "^1.3.0",
+};
+
+/**
+ * The library tsconfig only includes `src` (it drives declaration output),
+ * so type tests get their own project.
+ */
+const scripts = {
+  "lint:type-tests": "ember-tsc --noEmit --project type-tests",
+};
+
+/**
+ * @type {import('#types').Layer}
+ */
+export default {
+  label: "expect-type",
+  hint: "type tests for the published API",
+
+  async run(project) {
+    // Apps aren't published, so they have no public API to pin
+    if (!project.isLibrary) return;
+
+    if (!(await project.hasOrWantsLayer("typescript"))) return;
+
+    await applyFolderTo(join(import.meta.dirname, "files"), project);
+    await packageJson.addDevDependencies(await getLatest(deps), project.directory);
+    await packageJson.addScripts(scripts, project.directory);
+  },
+
+  /**
+   * @overload
+   * @param {import('#utils/project.js').Project} project
+   * @param {true} explain
+   * @returns {Promise<{ isSetup: boolean; reasons: string[] }>}
+   */
+  /**
+   * @overload
+   * @param {import('#utils/project.js').Project} project
+   * @param {boolean | undefined} [explain]
+   * @returns {Promise<boolean>}
+   */
+  async isSetup(project, explain) {
+    /** @type {string[]} */
+    const reasons = [];
+
+    // Nothing to set up outside TypeScript libraries,
+    // so nothing can be missing
+    if (!project.isLibrary || !(await project.hasOrWantsLayer("typescript"))) {
+      return explain ? { isSetup: true, reasons } : true;
+    }
+
+    if (!project.hasFile("type-tests/tsconfig.json")) {
+      if (!explain) return false;
+
+      reasons.push("type-tests/tsconfig.json is missing");
+    }
+
+    let manifest = await packageJson.read(project.directory);
+
+    for (let script of Object.keys(scripts)) {
+      if (!manifest.scripts?.[script]) {
+        if (!explain) return false;
+
+        reasons.push(`package.json is missing the "${script}" script`);
+      }
+    }
+
+    for (let dep of Object.keys(deps)) {
+      if (!manifest.devDependencies?.[dep]) {
+        if (!explain) return false;
+
+        reasons.push(`package.json is missing ${dep} in devDependencies`);
+      }
+    }
+
+    if (explain) {
+      return {
+        isSetup: reasons.length === 0,
+        reasons,
+      };
+    }
+
+    return reasons.length === 0;
+  },
+
+  /**
+   * @param {import('#utils/project.js').Project} project
+   */
+  async readme(project) {
+    if (!project.isLibrary || !(await project.hasOrWantsLayer("typescript"))) return;
+
+    return `### Type tests
+
+Type tests in \`type-tests/\` use [expect-type](https://github.com/mmkal/expect-type) to pin the types of the public API.
+
+- \`${project.runPrefix} lint:type-tests\` - Typecheck the type tests`;
+  },
+};

package/test/ember.nvp/cli.test.ts

@@ -1,5 +1,6 @@
 import { test, expect as hardExpect } from "vitest";
 import { cli } from "#test-helpers";
+import { stripVTControlCharacters } from "node:util";
 
 const expect = hardExpect.soft;
 
@@ -10,3 +11,58 @@ test.skip("cli works", async () => {
 
   expect(execaPromise.exitCode).toBe(0);
 });
+
+const BASIC_HELP_OUTPUT = `
+    " ember.nvp 
+
+    Usage: npx ember.nvp [options]
+
+    Core Options:
+      -h, --help <boolean>
+          Show CLI help and option details
+
+          --name <string>
+          Name of the project
+
+          --path <string>
+          Target directory path for the project
+
+          --type <string>
+          Type of project to generate [choices: "app", "addon", "library", "extension", "custom-element"]
+
+          --confirm <string>
+          Bypass target confirmation step [choices: "yes", "no"]
+
+          --layers <string>
+          Layers to apply to the project (repeat for multiple layers)
+
+          --packageManager <string>
+          Package manager to configure for the project [choices: "npm", "pnpm"]
+
+          --replaceOrUpdate <string>
+          Strategy to use if target directory exists [choices: "replace", "update"]
+
+          --write <string>
+          Confirm writing changes to disk [choices: "yes", "no"]
+    "
+  `;
+
+test("cli --help outputs usage and core options", async () => {
+  let { execaPromise } = cli(["--help"]);
+
+  const res = await execaPromise;
+
+  expect(res.exitCode).toBe(0);
+  const outStr = stripVTControlCharacters(res.stdout);
+  expect(outStr).toMatchInlineSnapshot(BASIC_HELP_OUTPUT);
+});
+
+test("cli -h alias works", async () => {
+  let { execaPromise } = cli(["-h"]);
+
+  const res = await execaPromise;
+
+  expect(res.exitCode).toBe(0);
+  const outStr = stripVTControlCharacters(res.stdout);
+  expect(outStr).toMatchInlineSnapshot(BASIC_HELP_OUTPUT);
+});

package/test/ember.nvp/layer-expect-type.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, beforeAll, afterAll, expect } from "vitest";
+import { generate, expectIsSetup, layers } from "#test-helpers";
+import { writeLibrarySource } from "./library-src-fixtures.ts";
+import { execa } from "execa";
+import { existsSync } from "node:fs";
+import { rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { Project } from "ember.nvp";
+
+const expectType = layers.find((layer) => layer.name === "expect-type")!;
+
+async function typecheck(project: Project) {
+  return execa("pnpm lint:type-tests", {
+    cwd: project.directory,
+    shell: true,
+    all: true,
+    reject: false,
+  });
+}
+
+describe("layer: expect-type", () => {
+  const dirs: string[] = [];
+
+  afterAll(async () => {
+    if (process.env.CI) return;
+
+    for (const dir of dirs) {
+      await rm(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    }
+  });
+
+  describe("TypeScript library", () => {
+    let project: Project;
+
+    beforeAll(async () => {
+      project = await generate({
+        type: "library",
+        name: "my-lib",
+        layers: ["typescript", "expect-type"],
+      });
+      dirs.push(project.directory);
+
+      await writeLibrarySource(project, "typescript");
+
+      let install = await execa("pnpm install", { cwd: project.directory, shell: true });
+      expect(install.exitCode).toBe(0);
+    });
+
+    it("is setup", async () => {
+      await expectIsSetup(project, expectType);
+    });
+
+    it("the generated type tests pass", async () => {
+      let result = await typecheck(project);
+
+      expect(result.exitCode, result.all).toBe(0);
+    });
+
+    it("checks the library's real exports", async () => {
+      await writeFile(
+        join(project.directory, "type-tests/math.test.ts"),
+        `import { expectTypeOf } from "expect-type";
+import { add } from "../src/index.ts";
+
+expectTypeOf(add).parameters.toEqualTypeOf<[number, number]>();
+expectTypeOf(add).returns.toEqualTypeOf<number>();
+`,
+      );
+
+      let result = await typecheck(project);
+
+      expect(result.exitCode, result.all).toBe(0);
+    });
+
+    it("fails on a wrong type assertion", async () => {
+      await writeFile(
+        join(project.directory, "type-tests/wrong.test.ts"),
+        `import { expectTypeOf } from "expect-type";
+import { add } from "../src/index.ts";
+
+expectTypeOf(add).returns.toEqualTypeOf<string>();
+`,
+      );
+
+      let result = await typecheck(project);
+
+      expect(result.exitCode).not.toBe(0);
+      expect(result.all).toContain("wrong.test.ts");
+    });
+
+    it("keeps type tests out of the build", async () => {
+      await rm(join(project.directory, "type-tests/wrong.test.ts"));
+
+      let build = await execa("pnpm build", { cwd: project.directory, shell: true });
+      expect(build.exitCode).toBe(0);
+
+      expect(existsSync(join(project.directory, "dist/type-tests"))).toBe(false);
+    });
+  });
+
+  describe("JavaScript library", () => {
+    it("adds nothing (no declarations to test)", async () => {
+      let project = await generate({ type: "library", name: "my-lib", layers: ["expect-type"] });
+      dirs.push(project.directory);
+
+      await expectIsSetup(project, expectType);
+
+      expect(existsSync(join(project.directory, "type-tests"))).toBe(false);
+      expect(await project.read("package.json")).not.toContain("expect-type");
+    });
+  });
+});

package/test/ember.nvp/layers.test.ts

@@ -13,6 +13,7 @@ describe("discoverLayers", () => {
         "are-the-types-wrong",
         "eslint-bundled-ember",
         "eslint-bundled-nvp",
+        "expect-type",
         "git",
         "github-actions",
         "inspector-support",

package/test/ember.nvp/permutations/shared.ts

@@ -28,11 +28,11 @@ const INITIAL_ONLY = new Set<string>([
  */
 const NOT_YET_SUPPORTED: Record<ProjectType, Set<string>> = {
   // publish checks: apps aren't published
-  app: new Set(["publint", "are-the-types-wrong"]),
+  app: new Set(["publint", "are-the-types-wrong", "expect-type"]),
   // libraries have no Application to wire inspector support into
   library: new Set(["inspector-support"]),
   // publish checks: extensions aren't published (to npm)
-  extension: new Set(["publint", "are-the-types-wrong"]),
+  extension: new Set(["publint", "are-the-types-wrong", "expect-type"]),
   // same toolchain as libraries: no Application either
   "custom-element": new Set(["inspector-support"]),
 };
@@ -61,6 +61,7 @@ const CHECK_LAYERS = new Set<string>([
   "prettier",
   "publint",
   "are-the-types-wrong",
+  "expect-type",
 ]);
 
 type PermutationGroup = "main" | "checks";

package/test/test-helpers.ts

@@ -120,7 +120,10 @@ export function cli(args: string[] = []) {
   let output = new MockWritable();
   let input = new MockReadable();
 
-  let execaPromise = execa("node", args, { shell: true, stdout: output, stdin: input });
+  let execaPromise = execa("node", [cliPath, ...args]);
+  if (execaPromise.stdout) {
+    execaPromise.stdout.pipe(output);
+  }
 
   return {
     execaPromise,

package/vitest.config.js

@@ -1,9 +1,15 @@
-import { defineConfig } from "vitest/config";
+import { configDefaults, defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
     testTimeout: 60_000,
     hookTimeout: 60_000,
     include: ["test/**/*.test.ts", "src/**/*.test.ts", "packages/*/src/**/*.test.ts"],
+    // Templates copied into generated projects, which run their own tests
+    exclude: configDefaults.exclude.concat([
+      "src/**/layers/*/files/**",
+      "src/**/layers/*/library-files/**",
+      "src/**/bases/*/files/**",
+    ]),
   },
 });