@mnci/cli 4.48.0 → 4.50.0

package/README.md

@@ -507,6 +507,69 @@ from File`), and the curated root scripts.
 4. Installs the chosen **stack** (see below), `husky` + `@commitlint/*` for
    real, so versions resolve at generation time.
 
+## Container images (`mnci add container <name> --app <app>`)
+
+`container` is a kind that wraps an app you already have, so the app keeps its own kind and the image is a project
+of its own beside it: `mnci add container api-image --app api --port 3000`. It writes `apps/<name>/` with a
+`Dockerfile`, a `Dockerfile.dockerignore`, a `files/` directory for anything the image copies from beside the build
+context, and a manifest tagged `type:container` with two targets. `image` builds `<name>:<VERSION>` and
+`<name>:latest` after the app's own output target (`VERSION` is `dev` when unset, as in the Go builds), and `start`
+runs the image, publishing the port. The project declares the app as an implicit dependency, so `nx affected`
+knows a change to the app affects its image. `npm run <name>:image` and `<name>:start` are registered; `:qa` builds
+the image.
+
+One recipe per app kind, each a plain image of what the app already produces:
+
+| App | Build context | Image |
+|---|---|---|
+| `node-app` | the app's pruned output (`prune` target) | `node:24-alpine`, production dependencies installed, runs as `node`, `HOST=0.0.0.0` so a published port is reachable |
+| `react-app` | its production `dist` | `nginx` with a server block that falls back to `index.html` for client-side routes |
+| `go-app` | the static `linux-amd64` binary from `build-all` | `distroless/static`, non-root |
+
+An Azure Functions app is refused, because its image is the Functions host's own and needs its own entry point.
+
+The target is called `image`, not `build`, **on purpose**: CI runs every project's `build`, and building an image needs a
+Docker engine that an agent may not have (a Windows agent cannot run Linux images at all). Adding a container project
+therefore does not change what CI verifies; building and publishing images is a step you add in a pipeline slot where
+the agent has Docker. `mnci upgrade` rewrites `tools/container-image.cjs`, the small helper both targets run.
+
+The `container images` e2e section builds a Node, a React and a Go image and talks to the running containers. It needs
+a Docker engine, so it skips where there is none and runs in CI's Linux `e2e-containers` job (nightly and on demand).
+
+## 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