@mnci/cli 4.47.0 → 4.49.0

package/README.md

@@ -36,7 +36,9 @@ plays (`.use-case`, `.client`, `.repository`, `.algorithm`, `.validator`,
 src/
   main.ts                     the CLI transport — decodes argv, calls one use case
   workspace-overlay/          the config files mnci owns and rewrites
-  workspace-creation/         mnci new, and the interactive wizard
+  workspace-creation/         mnci new
+  interactive-wizard/         bare mnci: every command and option, asked from the command's own description
+  repository-adoption/        mnci adopt — bringing an existing repository under mnci, step by step
   workspace-upgrade/          mnci upgrade
   workspace-diagnostics/      mnci doctor
   project-scaffolding/        mnci add — one use case per kind, plus post-generation repairs
@@ -505,6 +507,52 @@ from File`), and the curated root scripts.
 4. Installs the chosen **stack** (see below), `husky` + `@commitlint/*` for
    real, so versions resolve at generation time.
 
+## A paired Playwright project (`mnci add react-app web --e2e`)
+
+`--e2e` scaffolds `apps/<name>-e2e` beside a React app with `@nx/react:app --e2eTestRunner=playwright`. It is
+opt-in, and for React apps only: it adds Playwright to the workspace, and a Node API has no page to drive.
+
+- **The test.** Nx's sample looks for an `h1` containing "Welcome", which mnci's greeting app does not render, so it
+  is replaced by `src/greeting.e2e.spec.ts`: open `/` and expect the app's own greeting.
+- **What CI verifies.** The project has `lint` and `typecheck` (both pass, and CI's `lint,typecheck,test,build` run
+  picks them up); it has no `test` or `build`. Its `e2e` target is **not** part of CI's verify, because it needs a
+  browser, and installing one on every agent would cost every run. Run it where a browser exists:
+  `npx playwright install chromium`, then `npx nx run <name>-e2e:e2e -- --project=chromium` (the `--` hands the
+  flag to Playwright, not to Nx).
+- **Commands.** `npm run <name>-e2e:qa` is lint and typecheck. There is no `:build` or `:start`.
+- **No per-project ESLint config.** None is generated (`--linter=none`), and the usual sweep covers the directory.
+
+The `react e2e project` e2e section generates one, checks CI's targets, installs Chromium and runs the test against
+the built app.
+
+## ES module Node apps (`mnci add node-app|node-function-app --esm`)
+
+Generated Node apps are CommonJS by default, and `npm-lib` packages are ESM-only. `--esm` makes an app an ES module
+too: its `package.json` gets `"type": "module"` and its esbuild target builds `esm`; every relative import in its
+sources names its file the way `nodenext` resolution needs (`./hello` becomes `./hello/index.js`, which TypeScript
+reports as TS2835 otherwise); and its `jest.config.cts` gets a `moduleNameMapper` that resolves `./x.js` back to the
+`./x.ts` Jest transforms. It applies to `node-app` (Express, Koa or no framework) and `node-function-app`; Fastify
+and Nest keep the layout their framework mandates (autoloaded routes, decorators), so `--esm` is refused with them,
+and on any other kind.
+
+Measured on generated apps rather than assumed (the `node esm apps` e2e section): lint, typecheck, test and build are
+green; the built bundle is ES module syntax and runs; `prune` keeps `"type": "module"` in the pruned manifest, so
+`dist` still runs afterwards; and a **CommonJS** app that depends on an ESM-only library typechecks, builds and runs,
+including from `dist` after `prune` and an install there, because Node loads the ES module through `require`
+(unflagged from Node 22.12; the e2e says so and skips on older Node).
+
+## The interactive wizard (`mnci` with no arguments)
+
+Bare `mnci` lists **every command** (inside a workspace the Projects and Dependencies sections come first, outside
+one the Workspace section does), asks the command's arguments and then the options that apply, prints the command
+line it is about to run, and runs it through the same program the flags go through. It reads the commands from the
+program itself, so a command or option added to `main.ts` is offered without a wizard change. Two groupings are
+kept by hand and checked by a spec: `add` offers the flags of the kind just chosen, and `adopt` asks which step
+first (report, baseline tags, toolchain, project kinds, dependencies, overlay) and offers that step's own flags.
+`wizard-coverage.integration.spec.ts` fails when a command is missing from the menu, an `adopt` flag belongs to no
+step, an `add` flag is reachable for no kind, or the line the wizard builds for an option is not one the program
+accepts.
+
 ## `mnci adopt`: reading an existing repository before changing it
 
 `mnci adopt` is the start of bringing a repository that already has history, tooling and published