create-nx-archweave 0.2.1 → 0.3.0

package/README.md

@@ -2,10 +2,11 @@
 
 One command takes you from an empty directory to a configured Nx workspace with:
 
-- FSD Lite structure
+- an FSD Lite lint rule for the frontend app's layers (`warn` or `error` by preset), plus slice generators
+- frontend/backend boundaries as lint errors between the projects it tags, when you pick a backend
 - AI agent rules
 - GitHub templates
-- optional AI PR review (Claude, Gemini, GPT, Cursor)
+- optional AI PR review with the provider you choose (Claude supported; Gemini, GPT and Cursor in beta)
 
 ```bash
 # npm
@@ -27,15 +28,12 @@ Anything you don't pass as a flag, the CLI asks you interactively. The `quick-st
 
 - Node >= 22.18
 - npm, pnpm >= 10, yarn (classic or berry) or bun
-- network access to github.com (Nx's react template is downloaded from there)
-
-**react-vite and older package managers.** You can't create react-vite with npm 10 or yarn 1. Both of those fail inside `create-nx-workspace`'s own install of Nx's react template. So the CLI never offers npm 10 or yarn 1 for react-vite. If a flag names one of them, the CLI stops before creating anything.
 
 ## Choosing a package manager
 
 The CLI asks for the package manager too:
 
-- It only offers package managers that are installed and can create the workspace.
+- It only offers package managers that are installed.
 - It preselects the one that launched the CLI: `npx` → npm, `pnpm dlx` → pnpm, `yarn dlx` → yarn, `bunx` → bun.
 - Without a terminal, it uses the launching package manager, else npm.
 
@@ -47,29 +45,35 @@ A few things to know for specific package managers:
 
 ## What it runs
 
-The CLI prints its plan up front. Then it runs three steps with the package manager you chose.
+The CLI prints its plan up front. Then it runs the steps below with the package manager you chose.
 
-- It never re-implements `create-nx-workspace`.
+- It never re-implements `create-nx-workspace` or Nx's generators.
 - It never commits for you.
-- `--preset=next` replaces the template for `--frontend=next`.
-- pnpm adds a fourth step that records the build scripts pnpm skipped. bun adds one that lists the install scripts bun blocked (`bun pm untrusted`).
+- `--frontend=next` creates the workspace with `--preset=next --appName=web --e2eTestRunner=none` instead, which already holds the app.
+- No path creates an e2e project. See the [getting-started guide](https://github.com/clearlydev/nx-archweave/blob/main/docs/getting-started.md#adding-e2e-tests) to add one with Nx's own generator.
+- pnpm adds a last step that records the build scripts pnpm skipped. bun adds one that lists the install scripts bun blocked (`bun pm untrusted`).
 
-Here are the three steps for npm and pnpm.
+Here are the steps for npm and pnpm.
 
-**Step 1: create the workspace**
+**Step 1: create the workspace, then the React app**
 
 ```bash
 # npm
-npx -y create-nx-workspace@23.3.0 <name> \
-  --template=nrwl/react-template \
-  --pm=npm --nxCloud=skip --interactive=false
+npx -y create-nx-workspace@24.0.1 <name> \
+  --preset=empty --pm=npm --nxCloud=skip --interactive=false
+npm exec nx -- add @nx/react
+npm exec nx -- g @nx/react:app apps/web --bundler=vite --linter=eslint \
+  --style=css --unitTestRunner=vitest --e2eTestRunner=none --routing=false
 
 # pnpm
-pnpm dlx create-nx-workspace@23.3.0 <name> \
-  --template=nrwl/react-template \
-  --pm=pnpm --nxCloud=skip --interactive=false
+pnpm dlx create-nx-workspace@24.0.1 <name> \
+  --preset=empty --pm=pnpm --nxCloud=skip --interactive=false
+pnpm nx add @nx/react
+pnpm nx g @nx/react:app apps/web …   (same flags)
 ```
 
+`--preset=empty` downloads nothing and keeps the workspace on that create-nx-workspace's Nx version. `nx add` installs `@nx/react` at the same version.
+
 **Step 2: install the plugin**
 
 ```bash
@@ -94,13 +98,13 @@ pnpm nx g @clearlydev/nx-archweave:init …
 With `--backend=express|nest`, the CLI inserts two official steps before init:
 
 1. `@nx/<backend>`, pinned to the workspace's exact nx version
-2. `nx g @nx/<backend>:application apps/api --frontendProject=<detected app>`
+2. `nx g @nx/<backend>:application apps/api --frontendProject=<detected app> --unitTestRunner=vitest --e2eTestRunner=none` (vitest like the frontend; the generator would otherwise ask)
 
 init then wires `shared-types` and `scope:` tags, and writes the boundary constraints (`--applyEslint=true` on this path).
 
 When something goes wrong:
 
-- If a step fails, the CLI stops right away. It leaves the created directory in place (it never auto-deletes) and tells you how to recover.
+- If a step fails, the CLI stops right away. It leaves the created directory in place (it never auto-deletes), tells you how to recover, and prints the failed step and every step after it as commands you can run yourself. It never re-runs them for you.
 - When stdin isn't a TTY and a required input is missing, the CLI fails fast instead of hanging.
 
 ## Options

package/dist/bin.js

@@ -22,9 +22,9 @@ var AI_HOST_CHOICES = [
 ];
 var REVIEW_PROVIDER_CHOICES = [
   { id: "claude", label: "Claude" },
-  { id: "gemini", label: "Gemini" },
-  { id: "gpt", label: "GPT" },
-  { id: "cursor", label: "Cursor" }
+  { id: "gemini", label: "Gemini (beta)" },
+  { id: "gpt", label: "GPT (beta)" },
+  { id: "cursor", label: "Cursor (beta)" }
 ];
 var REVIEW_PROVIDER_VALUES = REVIEW_PROVIDER_CHOICES.map((provider) => provider.id);
 var AI_HOST_VALUES = AI_HOST_CHOICES.map((host) => host.id);
@@ -46,12 +46,6 @@ var PLUGIN_CHOICES = [
 ];
 var PLUGIN_VALUES = PLUGIN_CHOICES.map((plugin) => plugin.id);
 
-// src/cli/preflight.ts
-function parseMajor(version) {
-  const match = /^\s*v?(\d+)\./.exec(version ?? "");
-  return match ? Number(match[1]) : void 0;
-}
-
 // src/cli/package-manager.ts
 var SUPPORTED = ["npm", "pnpm", "yarn", "bun"];
 function isCliPackageManager(name) {
@@ -71,24 +65,11 @@ function listInstalledManagers(launcher, probe) {
   }
   return installed;
 }
-function managerIncompatibility(manager, frontend) {
-  const major = parseMajor(manager.version);
-  if (frontend !== "react-vite" || major === void 0) return void 0;
-  if (manager.name === "npm" && major < 11) return "react-vite needs npm 11 \u2014 npm 10 crashes in Nx's react template";
-  if (manager.name === "yarn" && major < 2) return "react-vite needs yarn 2+ \u2014 yarn 1 cannot resolve the template's workspace:* packages";
-  return void 0;
-}
 var NOTHING_CREATED = "Nothing was created.";
 async function choosePackageManager(input, ask, tell) {
   const launcher = parseUserAgent(input.userAgent);
   const resolveNamed = (name, source) => {
     const version = launcher?.name === name && launcher.version ? launcher.version : input.probe(name)?.trim() || void 0;
-    const reason = managerIncompatibility({ name, version }, input.frontend);
-    if (reason) {
-      return {
-        error: `create-nx-archweave stopped before creating anything: ${name} ${version} cannot create this workspace \u2014 ${reason}. ${INSTALL_ADVICE} ${NOTHING_CREATED}`
-      };
-    }
     return { packageManager: name, source, version };
   };
   if (input.flag) return resolveNamed(input.flag, "flag");
@@ -105,50 +86,30 @@ async function choosePackageManager(input, ask, tell) {
     tell(`${launcher.name} is not supported (${SUPPORTED_TEXT} are) \u2014 choosing from the supported ones instead.`);
   }
   const installed = listInstalledManagers(launcher, input.probe);
-  const reasons = installed.map((manager) => managerIncompatibility(manager, input.frontend));
-  const selectable = installed.filter((_, index) => reasons[index] === void 0);
-  const unavailable = installed.filter((_, index) => reasons[index] !== void 0);
-  const unavailableLines = unavailable.map(
-    (manager) => `     ${manager.name.padEnd(6)}${manager.version ?? ""}  \u2014 not available: ${reasons[installed.indexOf(manager)]}`
-  );
-  if (selectable.length === 0) {
-    return {
-      error: ["create-nx-archweave stopped before creating anything: no installed package manager can create this workspace.", ...unavailableLines, `${INSTALL_ADVICE} ${NOTHING_CREATED}`].join("\n")
-    };
-  }
-  if (selectable.length === 1) {
-    if (unavailable.length > 0) tell(["Package manager:", ...unavailableLines].join("\n"));
-    return { packageManager: selectable[0].name, source: unavailable.length > 0 ? "only-compatible" : "only-installed", version: selectable[0].version };
-  }
-  const defaultIndex = Math.max(0, selectable.findIndex((manager) => manager.name === launcher?.name));
+  if (installed.length === 1) return { packageManager: installed[0].name, source: "only-installed", version: installed[0].version };
+  const defaultIndex = Math.max(0, installed.findIndex((manager) => manager.name === launcher?.name));
   tell("? Package manager");
-  selectable.forEach((manager, index) => {
+  installed.forEach((manager, index) => {
     const head = `  ${index + 1}) ${manager.name.padEnd(6)}${manager.version ?? ""}`.trimEnd();
     tell(index === defaultIndex ? `${head}  (default)` : head);
   });
-  unavailableLines.forEach((line) => tell(line));
   for (; ; ) {
-    const answer = (await ask(`Choose 1-${selectable.length} [${defaultIndex + 1}]: `)).trim().toLowerCase();
+    const answer = (await ask(`Choose 1-${installed.length} [${defaultIndex + 1}]: `)).trim().toLowerCase();
     const byNumber = /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
-    const index = answer === "" ? defaultIndex : byNumber >= 0 ? byNumber : selectable.findIndex((manager) => manager.name === answer);
-    if (index >= 0 && index < selectable.length) {
-      return { packageManager: selectable[index].name, source: "asked", version: selectable[index].version };
+    const index = answer === "" ? defaultIndex : byNumber >= 0 ? byNumber : installed.findIndex((manager) => manager.name === answer);
+    if (index >= 0 && index < installed.length) {
+      return { packageManager: installed[index].name, source: "asked", version: installed[index].version };
     }
-    const blocked = unavailable.find((manager) => manager.name === answer);
-    tell(
-      blocked ? `${blocked.name} is not available here: ${reasons[installed.indexOf(blocked)]}.` : `Choose a number from 1 to ${selectable.length} (or a name: ${selectable.map((manager) => manager.name).join(", ")}).`
-    );
+    tell(`Choose a number from 1 to ${installed.length} (or a name: ${installed.map((manager) => manager.name).join(", ")}).`);
   }
 }
 var SUPPORTED_TEXT = "npm, pnpm, yarn and bun";
-var INSTALL_ADVICE = "Use npm 11+, pnpm, yarn 2+ (Corepack: corepack enable) or bun, or pass --package-manager= with one of them.";
 var SOURCE_TEXT = {
   flag: "--package-manager",
   launcher: "the package manager that ran this command",
   default: "default \u2014 no launching package manager detected",
   asked: "chosen",
-  "only-installed": "the only one installed",
-  "only-compatible": "the only installed one that can create this workspace"
+  "only-installed": "the only one installed"
 };
 function describeResolution(resolution) {
   const name = resolution.version ? `${resolution.packageManager} ${resolution.version}` : resolution.packageManager;
@@ -509,9 +470,7 @@ function renderVersion() {
 
 // src/cli/plan.ts
 var DEFAULT_PLUGIN_SOURCE = `@clearlydev/nx-archweave@^${CLI_VERSION}`;
-var VALIDATED_CREATE_NX_WORKSPACE_VERSION = "23.3.0";
-var NPM_10_CREATE_WORKSPACE_HINT = `If the npm error above is "Cannot read properties of null (reading 'edgesOut')", that is a known npm 10 bug with the current Nx workspace dependencies \u2014 upgrade npm (npm install -g npm@11), or, if pnpm is installed, re-run with --package-manager=pnpm.`;
-var YARN_1_CREATE_WORKSPACE_HINT = `If the yarn error above is "Couldn't find package \u2026@workspace:*", that is yarn 1 (classic), which cannot resolve the workspace:* packages in Nx's react template \u2014 use yarn 2+ (corepack enable, then yarn set version stable) or re-run with another package manager.`;
+var VALIDATED_CREATE_NX_WORKSPACE_VERSION = "24.0.1";
 function nxArgs(pm) {
   return pm === "npm" ? ["exec", "nx", "--"] : ["nx"];
 }
@@ -528,10 +487,11 @@ function isYarnBerry(ctx) {
   return ctx.readFile(".yarnrc.yml") !== void 0 || /^__metadata:/m.test(ctx.readFile("yarn.lock") ?? "");
 }
 var YARN_PLAN_ENV = { YARN_ENABLE_IMMUTABLE_INSTALLS: "false" };
+var NO_E2E = ["--e2eTestRunner=none"];
 function createWorkspaceSourceArgs(frontend, backend) {
-  if (frontend === "react-vite") return ["--template=nrwl/react-template"];
-  if (frontend === "next") return ["--preset=next"];
-  return [`--preset=${backend}`, "--appName=api"];
+  if (frontend === "react-vite") return ["--preset=empty"];
+  if (frontend === "next") return ["--preset=next", "--appName=web", ...NO_E2E];
+  return [`--preset=${backend}`, "--appName=api", ...NO_E2E, "--unitTestRunner=vitest"];
 }
 function buildNextSteps(input) {
   const lines = [
@@ -556,7 +516,7 @@ function buildNextSteps(input) {
 function buildPlan(input) {
   const pluginSource = input.pluginSource ?? DEFAULT_PLUGIN_SOURCE;
   const workspaceSource = createWorkspaceSourceArgs(input.frontend, input.backend);
-  const aiAgentArgs = input.aiHosts.map((host) => `--aiAgents=${AI_HOST_CHOICES.find((choice) => choice.id === host)?.nxAgent ?? host}`);
+  const aiAgentArgs = input.aiHosts.length === 0 ? ["--aiAgents=none"] : input.aiHosts.map((host) => `--aiAgents=${AI_HOST_CHOICES.find((choice) => choice.id === host)?.nxAgent ?? host}`);
   const pm = input.packageManager;
   const nxPrefix = nxArgs(pm);
   const initArgs = [
@@ -572,8 +532,10 @@ function buildPlan(input) {
     // Step 2 (the plugin install) always dirties the fresh workspace's tree
     // (package.json + lockfile), so init's clean-tree refusal would otherwise
     // always fire here. This is orchestration knowledge, not policy: the CLI
-    // knows what its own previous step did.
-    "--allowDirty=true"
+    // knows what its own previous step did. For the same reason the report's note about
+    // reverting earlier user changes doesn't apply: the only changes are that install's.
+    "--allowDirty=true",
+    "--dirtyFromCaller=true"
   ];
   if (input.review !== void 0) {
     initArgs.push(`--review=${input.review}`);
@@ -608,10 +570,9 @@ function buildPlan(input) {
         "--nxCloud=skip",
         "--interactive=false"
       ],
-      cwd: null,
-      ...input.frontend === "react-vite" && pm === "npm" ? { failureHint: NPM_10_CREATE_WORKSPACE_HINT } : {},
-      ...input.frontend === "react-vite" && pm === "yarn" ? { failureHint: YARN_1_CREATE_WORKSPACE_HINT } : {}
+      cwd: null
     },
+    ...input.frontend === "react-vite" ? reactAppSteps(input.name, pm) : [],
     {
       id: "install-plugin",
       description: `Install ${pluginSource}`,
@@ -728,11 +689,31 @@ function listBlockedScriptsStep(workspaceName) {
     failureHint: `The workspace itself is complete \u2014 every earlier step finished; only listing the blocked install scripts failed. Inside "${workspaceName}", run bun pm untrusted to see them.`
   };
 }
+function reactAppSteps(workspaceName, pm) {
+  return [
+    {
+      id: "add-react-plugin",
+      description: "Add @nx/react with nx add (at the workspace nx version)",
+      command: pm,
+      args: [...nxArgs(pm), "add", "@nx/react"],
+      cwd: workspaceName
+    },
+    {
+      id: "create-web-app",
+      description: "Create the React + Vite app in apps/web with the official @nx/react generator",
+      command: pm,
+      args: [...nxArgs(pm), "g", "@nx/react:app", "apps/web", ...REACT_APP_OPTIONS],
+      cwd: workspaceName
+    }
+  ];
+}
+var REACT_APP_OPTIONS = ["--bundler=vite", "--linter=eslint", "--style=css", "--unitTestRunner=vitest", ...NO_E2E, "--routing=false"];
+var API_APP_OPTIONS = ["--unitTestRunner=vitest", ...NO_E2E];
 function backendSteps(backend, workspaceName, pm, initCommand) {
   const nxG = nxGenerateCommand(pm);
-  const templateApi = (ctx) => ctx.listDir("apps").includes("api");
+  const apiExists = (ctx) => ctx.listDir("apps").includes("api");
   const standaloneError = `this workspace has no apps/ directory \u2014 CLI backend wiring needs the frontend under apps/. Create the api app with the official @nx generator, then run \`${nxG} @clearlydev/nx-archweave:add-backend\` yourself. Finish setup inside "${workspaceName}" with: ${initCommand}`;
-  const nestConflictError = `the workspace template already ships an Express apps/api \u2014 re-run with --backend=express to wire it, or remove apps/api and scaffold Nest yourself, then run add-backend. Either way, finish setup inside "${workspaceName}" with: ${initCommand}`;
+  const apiExistsError = `the workspace already has an apps/api \u2014 wire it with \`${nxG} @clearlydev/nx-archweave:add-backend --backend=${backend}\`, or remove it and run the official generator yourself. Either way, finish setup inside "${workspaceName}" with: ${initCommand}`;
   return [
     {
       id: "install-backend-plugin",
@@ -742,9 +723,7 @@ function backendSteps(backend, workspaceName, pm, initCommand) {
       cwd: workspaceName,
       finalizeArgs: (ctx) => {
         if (ctx.listDir("apps").length === 0) return { error: standaloneError };
-        if (templateApi(ctx)) {
-          return backend === "express" ? { skip: "the workspace template already ships the Express api" } : { error: nestConflictError };
-        }
+        if (apiExists(ctx)) return { error: apiExistsError };
         const raw = ctx.readFile("package.json");
         if (raw === void 0) return { error: "could not read the created workspace's package.json to pin the @nx version" };
         try {
@@ -763,14 +742,12 @@ function backendSteps(backend, workspaceName, pm, initCommand) {
       command: pm,
       // Since Nx 20 the positional is a directory relative to the workspace root —
       // a bare `api` would land at the root instead of beside the frontend.
-      args: [...nxArgs(pm), "g", `@nx/${backend}:application`, "apps/api"],
+      args: [...nxArgs(pm), "g", `@nx/${backend}:application`, "apps/api", ...API_APP_OPTIONS],
       cwd: workspaceName,
       finalizeArgs: (ctx) => {
         const all = ctx.listDir("apps");
         if (all.length === 0) return { error: standaloneError };
-        if (all.includes("api")) {
-          return backend === "express" ? { skip: "the workspace template already ships the Express api" } : { error: nestConflictError };
-        }
+        if (all.includes("api")) return { error: apiExistsError };
         const apps = all.filter((name) => name !== "api" && name !== "e2e" && !name.endsWith("-e2e"));
         if (apps.length === 0) return { error: "no frontend app directory found under apps/ in the created workspace" };
         if (apps.length > 1) return { error: `multiple app directories found under apps/ (${apps.join(", ")}) \u2014 cannot pick --frontendProject` };
@@ -786,7 +763,7 @@ function backendSteps(backend, workspaceName, pm, initCommand) {
           }
           return apps[0];
         })();
-        return [...nxArgs(pm), "g", `@nx/${backend}:application`, "apps/api", `--frontendProject=${frontendProject}`];
+        return [...nxArgs(pm), "g", `@nx/${backend}:application`, "apps/api", `--frontendProject=${frontendProject}`, ...API_APP_OPTIONS];
       }
     }
   ];
@@ -998,7 +975,7 @@ function executePlan(plan, exec, invokedFromDir, ctxFactory = createStepContext)
         completed.push({ step, result, args, optionalFailure });
         continue;
       }
-      return { ok: false, completed, failedStep: step, failedResult: result };
+      return { ok: false, completed, failedStep: step, failedResult: result, failedArgs: args };
     }
     completed.push({ step, result, args });
   }
@@ -1036,9 +1013,32 @@ function renderExecuteReport(report, plan, workspaceName) {
     ...!report.finalizeError && failedStep.failureHint ? [`  ${failedStep.failureHint}`] : [],
     "",
     `The "${workspaceName}" directory (if it was created) was left in place \u2014 create-nx-archweave never deletes it automatically.`,
-    `Inspect the error above, fix the issue, then either re-run the failed command yourself inside "${workspaceName}" or remove the directory and start over.`
+    `Inspect the error above and fix the issue. Then either run the remaining steps below yourself, or remove the directory and start over.`,
+    "",
+    ...renderRemainingSteps(report, plan, workspaceName)
   ].join("\n");
 }
+function renderRemainingSteps(report, plan, workspaceName) {
+  const start = plan.steps.indexOf(report.failedStep);
+  const remaining = start === -1 ? [report.failedStep] : plan.steps.slice(start);
+  const lines = [`Remaining steps, in order (printed only \u2014 create-nx-archweave does not run them again):`];
+  const env = Object.entries(plan.env ?? {});
+  if (env.length > 0) lines.push(`  Run them with ${env.map(([key, value]) => `${key}=${value}`).join(" ")} set, as the CLI does.`);
+  remaining.forEach((step, index) => {
+    const ranArgs = step === report.failedStep ? report.failedArgs : void 0;
+    const args = ranArgs ?? step.args;
+    const where = step.cwd === null ? "in the directory you ran create-nx-archweave from" : `inside "${workspaceName}"`;
+    lines.push(`  ${index + 1}. ${step.description}${step.optional ? " (optional)" : ""} \u2014 ${where}:`);
+    lines.push(`       ${[step.command, ...args].map(shellQuote).join(" ")}`);
+    if (step.finalizeArgs && ranArgs === void 0) {
+      lines.push("       (the CLI works out this step's exact arguments when it runs \u2014 check them against the workspace first)");
+    }
+  });
+  return lines;
+}
+function shellQuote(word) {
+  return /^[\w@%+=:,./^~-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+}
 
 // src/bin.ts
 var NonInteractiveInputError = class extends Error {
@@ -1126,7 +1126,6 @@ async function main(argv) {
       {
         flag: args.packageManager,
         userAgent: process.env["npm_config_user_agent"],
-        frontend: inputs.frontend,
         interactive,
         probe: readVersion
       },

package/dist/cli/execute.d.ts

@@ -35,6 +35,8 @@ export type ExecuteReport = {
     completed: CompletedStep[];
     failedStep: PlanStep;
     failedResult: ExecResult;
+    /** The args the failed step ran with (after finalizeArgs); absent when it never executed. */
+    failedArgs?: string[];
     /** Set when finalizeArgs refused — the step never executed. */
     finalizeError?: string;
 };

package/dist/cli/package-manager.d.ts

@@ -1,5 +1,4 @@
 import type { Ask } from './prompts.ts';
-import type { CliFrontend } from './types.ts';
 /** The managers this CLI builds workspaces with. */
 export type CliPackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
 export declare function isCliPackageManager(name: string): name is CliPackageManager;
@@ -24,14 +23,7 @@ export type Probe = (name: CliPackageManager) => string | undefined;
  * launched this command. The launcher's own version is used instead of probing it again.
  */
 export declare function listInstalledManagers(launcher: Launcher | undefined, probe: Probe): InstalledManager[];
-/**
- * Why this manager cannot create the chosen workspace, or undefined when it can.
- * Both known cases fail inside create-nx-workspace's own install of
- * Nx's react template, so a pick is never allowed — an unknown version is not held
- * against the manager.
- */
-export declare function managerIncompatibility(manager: InstalledManager, frontend: CliFrontend): string | undefined;
-export type PackageManagerSource = 'flag' | 'launcher' | 'default' | 'asked' | 'only-installed' | 'only-compatible';
+export type PackageManagerSource = 'flag' | 'launcher' | 'default' | 'asked' | 'only-installed';
 export interface PackageManagerResolution {
     packageManager: CliPackageManager;
     source: PackageManagerSource;
@@ -42,17 +34,15 @@ export interface ChooseInput {
     /** `--package-manager`, already validated by parse-args. */
     flag: CliPackageManager | undefined;
     userAgent: string | undefined;
-    frontend: CliFrontend;
     /** stdin is a TTY — only then is a question asked. */
     interactive: boolean;
     probe: Probe;
 }
 /**
- * Flag > (interactive) the question > launcher > npm. One rule everywhere: a manager
- * that cannot create the chosen workspace is never used — the question shows it with its
- * reason but does not offer it, and a flag or launcher naming it stops the run before
- * anything is created. Non-interactive runs launched by an unsupported manager are
- * refused the same way.
+ * Flag > (interactive) the question > launcher > npm. Every supported manager can create
+ * every workspace (npm 10 and yarn 1 included, measured 2026-10-25 on the empty-preset
+ * react-vite path and on next). Non-interactive runs launched by an unsupported manager are
+ * refused before anything is created.
  */
 export declare function choosePackageManager(input: ChooseInput, ask: Ask, tell: (line: string) => void): Promise<PackageManagerResolution | {
     error: string;

package/dist/cli/plan.d.ts

@@ -35,7 +35,7 @@ export interface StepContext {
     listDir(relativePath: string): string[];
 }
 export interface PlanStep {
-    id: 'create-workspace' | 'install-plugin' | 'install-backend-plugin' | 'create-api-app' | 'run-init' | 'settle-build-approvals' | 'list-blocked-scripts' | 'install-ai-plugin';
+    id: 'create-workspace' | 'add-react-plugin' | 'create-web-app' | 'install-plugin' | 'install-backend-plugin' | 'create-api-app' | 'run-init' | 'settle-build-approvals' | 'list-blocked-scripts' | 'install-ai-plugin';
     description: string;
     command: string;
     args: string[];
@@ -47,7 +47,7 @@ export interface PlanStep {
      * @nx/<backend> version pin and --frontendProject are only knowable after
      * step 1 ran). Returning { error } stops the plan before executing the
      * step; { skip } records the step as satisfied without executing it
-     * (measured reality: the react template already ships apps/api). */
+     * (express already declared, so there is nothing to align). */
     finalizeArgs?: (ctx: StepContext) => string[] | {
         error: string;
     } | {
@@ -72,17 +72,6 @@ export interface CreatePlan {
      * automatic commit — that stays outside what this CLI does). */
     nextSteps: string[];
 }
-/** npm 10 (bundled with Node 22) crashes inside create-nx-workspace's own install
- * of the react template's dependency tree — an arborist bug in its peer-set
- * resolution, reproduced on every npm 10 release up to 10.9.9 and absent in npm 11
- * (E2E CI finding, 2026-10-13). The next preset installs fine on npm 10
- * (2026-10-14), so only react-vite + npm is affected: package-manager.ts never lets a
- * known npm 10 pick it, and the create step keeps this hint for the case the version
- * could not be read. */
-export declare const NPM_10_CREATE_WORKSPACE_HINT: string;
-/** yarn 1 cannot resolve the `workspace:*` packages Nx's react template declares
- * (measured 2026-10-15); the same guard and fallback as npm 10 above. */
-export declare const YARN_1_CREATE_WORKSPACE_HINT: string;
 /** `pnpm nx g` / `npm exec nx -- g` — how the user runs a generator in the new workspace. */
 export declare function nxGenerateCommand(pm: CliPackageManager): string;
 export declare function isYarnBerry(ctx: Pick<StepContext, 'readFile'>): boolean;

package/dist/index.js

@@ -11,9 +11,9 @@ var AI_HOST_CHOICES = [
 ];
 var REVIEW_PROVIDER_CHOICES = [
   { id: "claude", label: "Claude" },
-  { id: "gemini", label: "Gemini" },
-  { id: "gpt", label: "GPT" },
-  { id: "cursor", label: "Cursor" }
+  { id: "gemini", label: "Gemini (beta)" },
+  { id: "gpt", label: "GPT (beta)" },
+  { id: "cursor", label: "Cursor (beta)" }
 ];
 var REVIEW_PROVIDER_VALUES = REVIEW_PROVIDER_CHOICES.map((provider) => provider.id);
 var AI_HOST_VALUES = AI_HOST_CHOICES.map((host) => host.id);
@@ -38,12 +38,6 @@ var PLUGIN_VALUES = PLUGIN_CHOICES.map((plugin) => plugin.id);
 // src/cli/parse-args.ts
 import { parseArgs as parseNodeArgs } from "node:util";
 
-// src/cli/preflight.ts
-function parseMajor(version) {
-  const match = /^\s*v?(\d+)\./.exec(version ?? "");
-  return match ? Number(match[1]) : void 0;
-}
-
 // src/cli/package-manager.ts
 var SUPPORTED = ["npm", "pnpm", "yarn", "bun"];
 function isCliPackageManager(name) {
@@ -385,9 +379,7 @@ function renderVersion() {
 
 // src/cli/plan.ts
 var DEFAULT_PLUGIN_SOURCE = `@clearlydev/nx-archweave@^${CLI_VERSION}`;
-var VALIDATED_CREATE_NX_WORKSPACE_VERSION = "23.3.0";
-var NPM_10_CREATE_WORKSPACE_HINT = `If the npm error above is "Cannot read properties of null (reading 'edgesOut')", that is a known npm 10 bug with the current Nx workspace dependencies \u2014 upgrade npm (npm install -g npm@11), or, if pnpm is installed, re-run with --package-manager=pnpm.`;
-var YARN_1_CREATE_WORKSPACE_HINT = `If the yarn error above is "Couldn't find package \u2026@workspace:*", that is yarn 1 (classic), which cannot resolve the workspace:* packages in Nx's react template \u2014 use yarn 2+ (corepack enable, then yarn set version stable) or re-run with another package manager.`;
+var VALIDATED_CREATE_NX_WORKSPACE_VERSION = "24.0.1";
 function nxArgs(pm) {
   return pm === "npm" ? ["exec", "nx", "--"] : ["nx"];
 }
@@ -404,10 +396,11 @@ function isYarnBerry(ctx) {
   return ctx.readFile(".yarnrc.yml") !== void 0 || /^__metadata:/m.test(ctx.readFile("yarn.lock") ?? "");
 }
 var YARN_PLAN_ENV = { YARN_ENABLE_IMMUTABLE_INSTALLS: "false" };
+var NO_E2E = ["--e2eTestRunner=none"];
 function createWorkspaceSourceArgs(frontend, backend) {
-  if (frontend === "react-vite") return ["--template=nrwl/react-template"];
-  if (frontend === "next") return ["--preset=next"];
-  return [`--preset=${backend}`, "--appName=api"];
+  if (frontend === "react-vite") return ["--preset=empty"];
+  if (frontend === "next") return ["--preset=next", "--appName=web", ...NO_E2E];
+  return [`--preset=${backend}`, "--appName=api", ...NO_E2E, "--unitTestRunner=vitest"];
 }
 function buildNextSteps(input) {
   const lines = [
@@ -432,7 +425,7 @@ function buildNextSteps(input) {
 function buildPlan(input) {
   const pluginSource = input.pluginSource ?? DEFAULT_PLUGIN_SOURCE;
   const workspaceSource = createWorkspaceSourceArgs(input.frontend, input.backend);
-  const aiAgentArgs = input.aiHosts.map((host) => `--aiAgents=${AI_HOST_CHOICES.find((choice) => choice.id === host)?.nxAgent ?? host}`);
+  const aiAgentArgs = input.aiHosts.length === 0 ? ["--aiAgents=none"] : input.aiHosts.map((host) => `--aiAgents=${AI_HOST_CHOICES.find((choice) => choice.id === host)?.nxAgent ?? host}`);
   const pm = input.packageManager;
   const nxPrefix = nxArgs(pm);
   const initArgs = [
@@ -448,8 +441,10 @@ function buildPlan(input) {
     // Step 2 (the plugin install) always dirties the fresh workspace's tree
     // (package.json + lockfile), so init's clean-tree refusal would otherwise
     // always fire here. This is orchestration knowledge, not policy: the CLI
-    // knows what its own previous step did.
-    "--allowDirty=true"
+    // knows what its own previous step did. For the same reason the report's note about
+    // reverting earlier user changes doesn't apply: the only changes are that install's.
+    "--allowDirty=true",
+    "--dirtyFromCaller=true"
   ];
   if (input.review !== void 0) {
     initArgs.push(`--review=${input.review}`);
@@ -484,10 +479,9 @@ function buildPlan(input) {
         "--nxCloud=skip",
         "--interactive=false"
       ],
-      cwd: null,
-      ...input.frontend === "react-vite" && pm === "npm" ? { failureHint: NPM_10_CREATE_WORKSPACE_HINT } : {},
-      ...input.frontend === "react-vite" && pm === "yarn" ? { failureHint: YARN_1_CREATE_WORKSPACE_HINT } : {}
+      cwd: null
     },
+    ...input.frontend === "react-vite" ? reactAppSteps(input.name, pm) : [],
     {
       id: "install-plugin",
       description: `Install ${pluginSource}`,
@@ -604,11 +598,31 @@ function listBlockedScriptsStep(workspaceName) {
     failureHint: `The workspace itself is complete \u2014 every earlier step finished; only listing the blocked install scripts failed. Inside "${workspaceName}", run bun pm untrusted to see them.`
   };
 }
+function reactAppSteps(workspaceName, pm) {
+  return [
+    {
+      id: "add-react-plugin",
+      description: "Add @nx/react with nx add (at the workspace nx version)",
+      command: pm,
+      args: [...nxArgs(pm), "add", "@nx/react"],
+      cwd: workspaceName
+    },
+    {
+      id: "create-web-app",
+      description: "Create the React + Vite app in apps/web with the official @nx/react generator",
+      command: pm,
+      args: [...nxArgs(pm), "g", "@nx/react:app", "apps/web", ...REACT_APP_OPTIONS],
+      cwd: workspaceName
+    }
+  ];
+}
+var REACT_APP_OPTIONS = ["--bundler=vite", "--linter=eslint", "--style=css", "--unitTestRunner=vitest", ...NO_E2E, "--routing=false"];
+var API_APP_OPTIONS = ["--unitTestRunner=vitest", ...NO_E2E];
 function backendSteps(backend, workspaceName, pm, initCommand) {
   const nxG = nxGenerateCommand(pm);
-  const templateApi = (ctx) => ctx.listDir("apps").includes("api");
+  const apiExists = (ctx) => ctx.listDir("apps").includes("api");
   const standaloneError = `this workspace has no apps/ directory \u2014 CLI backend wiring needs the frontend under apps/. Create the api app with the official @nx generator, then run \`${nxG} @clearlydev/nx-archweave:add-backend\` yourself. Finish setup inside "${workspaceName}" with: ${initCommand}`;
-  const nestConflictError = `the workspace template already ships an Express apps/api \u2014 re-run with --backend=express to wire it, or remove apps/api and scaffold Nest yourself, then run add-backend. Either way, finish setup inside "${workspaceName}" with: ${initCommand}`;
+  const apiExistsError = `the workspace already has an apps/api \u2014 wire it with \`${nxG} @clearlydev/nx-archweave:add-backend --backend=${backend}\`, or remove it and run the official generator yourself. Either way, finish setup inside "${workspaceName}" with: ${initCommand}`;
   return [
     {
       id: "install-backend-plugin",
@@ -618,9 +632,7 @@ function backendSteps(backend, workspaceName, pm, initCommand) {
       cwd: workspaceName,
       finalizeArgs: (ctx) => {
         if (ctx.listDir("apps").length === 0) return { error: standaloneError };
-        if (templateApi(ctx)) {
-          return backend === "express" ? { skip: "the workspace template already ships the Express api" } : { error: nestConflictError };
-        }
+        if (apiExists(ctx)) return { error: apiExistsError };
         const raw = ctx.readFile("package.json");
         if (raw === void 0) return { error: "could not read the created workspace's package.json to pin the @nx version" };
         try {
@@ -639,14 +651,12 @@ function backendSteps(backend, workspaceName, pm, initCommand) {
       command: pm,
       // Since Nx 20 the positional is a directory relative to the workspace root —
       // a bare `api` would land at the root instead of beside the frontend.
-      args: [...nxArgs(pm), "g", `@nx/${backend}:application`, "apps/api"],
+      args: [...nxArgs(pm), "g", `@nx/${backend}:application`, "apps/api", ...API_APP_OPTIONS],
       cwd: workspaceName,
       finalizeArgs: (ctx) => {
         const all = ctx.listDir("apps");
         if (all.length === 0) return { error: standaloneError };
-        if (all.includes("api")) {
-          return backend === "express" ? { skip: "the workspace template already ships the Express api" } : { error: nestConflictError };
-        }
+        if (all.includes("api")) return { error: apiExistsError };
         const apps = all.filter((name) => name !== "api" && name !== "e2e" && !name.endsWith("-e2e"));
         if (apps.length === 0) return { error: "no frontend app directory found under apps/ in the created workspace" };
         if (apps.length > 1) return { error: `multiple app directories found under apps/ (${apps.join(", ")}) \u2014 cannot pick --frontendProject` };
@@ -662,7 +672,7 @@ function backendSteps(backend, workspaceName, pm, initCommand) {
           }
           return apps[0];
         })();
-        return [...nxArgs(pm), "g", `@nx/${backend}:application`, "apps/api", `--frontendProject=${frontendProject}`];
+        return [...nxArgs(pm), "g", `@nx/${backend}:application`, "apps/api", `--frontendProject=${frontendProject}`, ...API_APP_OPTIONS];
       }
     }
   ];
@@ -795,7 +805,7 @@ function executePlan(plan, exec, invokedFromDir, ctxFactory = createStepContext)
         completed.push({ step, result, args, optionalFailure });
         continue;
       }
-      return { ok: false, completed, failedStep: step, failedResult: result };
+      return { ok: false, completed, failedStep: step, failedResult: result, failedArgs: args };
     }
     completed.push({ step, result, args });
   }
@@ -833,9 +843,38 @@ function renderExecuteReport(report, plan, workspaceName) {
     ...!report.finalizeError && failedStep.failureHint ? [`  ${failedStep.failureHint}`] : [],
     "",
     `The "${workspaceName}" directory (if it was created) was left in place \u2014 create-nx-archweave never deletes it automatically.`,
-    `Inspect the error above, fix the issue, then either re-run the failed command yourself inside "${workspaceName}" or remove the directory and start over.`
+    `Inspect the error above and fix the issue. Then either run the remaining steps below yourself, or remove the directory and start over.`,
+    "",
+    ...renderRemainingSteps(report, plan, workspaceName)
   ].join("\n");
 }
+function renderRemainingSteps(report, plan, workspaceName) {
+  const start = plan.steps.indexOf(report.failedStep);
+  const remaining = start === -1 ? [report.failedStep] : plan.steps.slice(start);
+  const lines = [`Remaining steps, in order (printed only \u2014 create-nx-archweave does not run them again):`];
+  const env = Object.entries(plan.env ?? {});
+  if (env.length > 0) lines.push(`  Run them with ${env.map(([key, value]) => `${key}=${value}`).join(" ")} set, as the CLI does.`);
+  remaining.forEach((step, index) => {
+    const ranArgs = step === report.failedStep ? report.failedArgs : void 0;
+    const args = ranArgs ?? step.args;
+    const where = step.cwd === null ? "in the directory you ran create-nx-archweave from" : `inside "${workspaceName}"`;
+    lines.push(`  ${index + 1}. ${step.description}${step.optional ? " (optional)" : ""} \u2014 ${where}:`);
+    lines.push(`       ${[step.command, ...args].map(shellQuote).join(" ")}`);
+    if (step.finalizeArgs && ranArgs === void 0) {
+      lines.push("       (the CLI works out this step's exact arguments when it runs \u2014 check them against the workspace first)");
+    }
+  });
+  return lines;
+}
+function shellQuote(word) {
+  return /^[\w@%+=:,./^~-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`;
+}
+
+// src/cli/preflight.ts
+function parseMajor(version) {
+  const match = /^\s*v?(\d+)\./.exec(version ?? "");
+  return match ? Number(match[1]) : void 0;
+}
 export {
   AI_HOST_CHOICES,
   AI_HOST_PROBES,
@@ -845,14 +884,12 @@ export {
   DEFAULT_AI_HOSTS,
   FRONTEND_VALUES,
   LOCALE_VALUES,
-  NPM_10_CREATE_WORKSPACE_HINT,
   PLUGIN_CHOICES,
   PLUGIN_VALUES,
   PNPM_PENDING_BUILD_PLACEHOLDER,
   PRESET_VALUES,
   REVIEW_PROVIDER_CHOICES,
   REVIEW_PROVIDER_VALUES,
-  YARN_1_CREATE_WORKSPACE_HINT,
   aiHostsQuestion,
   buildPlan,
   childEnv,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-nx-archweave",
-  "version": "0.2.1",
-  "description": "One command from an empty directory to a configured Nx workspace: FSD Lite structure, AI agent rules, GitHub templates, and optional AI PR review (Claude, Gemini, GPT, Cursor)",
+  "version": "0.3.0",
+  "description": "One command from an empty directory to a configured Nx workspace: an FSD Lite lint rule, frontend/backend boundaries, AI agent rules, GitHub templates, and optional AI PR review with the provider you choose (Claude supported; Gemini, GPT and Cursor in beta)",
   "license": "MIT",
   "author": "clearlydev (https://github.com/clearlydev)",
   "engines": {