@mnci/cli 4.51.0 → 4.53.0

package/README.md

@@ -38,7 +38,16 @@ src/
   workspace-overlay/          the config files mnci owns and rewrites
   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
+  repository-adoption/        mnci adopt — the command, which runs the step slices below
+  adoption-report/            what adopt reads from a repository and the blockers and warnings it judges
+  toolchain-adoption/         adopt --toolchain: retired tooling gone, one Nx version, an audit that passes
+  kind-adoption/              adopt --kinds: each project's mnci kind as a type tag
+  dependency-adoption/        adopt --dependencies: root runtime dependencies into the projects that import them
+  clean-working-tree/         the git precondition every step that changes files shares
+  release-tag-lineage/        release tags kept reachable across a rename; doctor, upgrade and adopt all use it
+  esm-conversion/             a generated Node app made an ES module (add --esm)
+  dev-servers/                mnci dev: several projects started together
+  workspace-presets/          mnci new --preset: a whole shape of workspace, wired
   workspace-upgrade/          mnci upgrade
   workspace-diagnostics/      mnci doctor
   project-scaffolding/        mnci add — one use case per kind, plus post-generation repairs
@@ -51,6 +60,18 @@ src/
   cli-version/                the update check
 ```
 
+**Written exception: `src/project-scaffolding/` is over the 12-file review threshold.**
+- *Rule waived:* the folder-size review point (it holds a dispatcher, one file per project kind, and
+  `post-generation.use-case.ts`).
+- *Constraint:* every kind calls `registerProjectCommands` (and uses its `ProjectCommands` type) from
+  `post-generation.use-case.ts`. A kind moved to a slice of its own would import that back from
+  `project-scaffolding` while `project-scaffolding` imports the kind: a cycle, type-only imports included.
+- *Owner:* the repository owner. *Temporary:* it ends when `registerProjectCommands`, `ProjectCommands` and the
+  helpers they use move out of `post-generation.use-case.ts` into a `project-commands/` slice; each kind
+  (`container` first) can then move into a slice of its own. Splitting a file this size is its own change and needs a
+  yes, so it is recorded here and not done as a side effect. The ESM conversion had no such dependency and is
+  already its own slice (`esm-conversion/`).
+
 The dependency graph is acyclic and flows one way: `main` → the command
 slices → the infrastructure slices → `file-system` as a leaf. That is checked,
 not assumed — and now enforced: the root `eslint.config.mjs` turns on
@@ -507,6 +528,28 @@ 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 whole shape in one step (`mnci new --preset`)
+
+Everything else in mnci is per project. `mnci new my-shop --preset web-api` also scaffolds a wired-together shape, so the
+result is a starting point that already runs rather than three projects to connect:
+
+| Preset | Adds | Wiring |
+|---|---|---|
+| `web-api` | `libs/shared` (an internal library), `apps/api` (Express) and `apps/web` (React) | the API answers `GET /api/greeting` with the shared library's `greet`; the frontend asks that route and types the answer with the shared `Greeting`; both declare `@<scope>/shared`; Vite forwards `/api` to the API in development |
+
+Each project is added through `mnci add`, so it is exactly what `add` makes, and the preset then edits them into one shape:
+the API and the frontend drop their own copy of the sample use case and contract (the library owns them now), each gets a
+spec that matches (written without a mock library, so it runs under Jest or Vitest), and one install, one `nx sync` and one
+format finish it. `mnci dev web api` starts both servers, and asking the frontend's origin for `/api/greeting` returns the
+API's answer through the proxy.
+
+A misspelt preset is refused before the workspace is generated, and the wiring edits fail with the file named, not
+silently, if a generator's output ever stops having the text they change. A preset is a starting point to edit: delete what
+you do not need. New presets are an entry in `workspace-presets/preset-catalog.config.ts` plus their wiring.
+
+The `web-api preset` e2e section generates one and checks lint, typecheck, test and build for all three projects, the
+specs under Vitest, and the proxied request while both servers run.
+
 ## Starting projects together (`mnci dev`)
 
 `<name>:start` starts one project. `mnci dev web api` starts several at once, the usual case being a frontend and the
@@ -635,6 +678,14 @@ default the newest published in the major already in use (`--nx <version>` overr
 `npm audit fix` (never `--force`) until `mnci ci audit` passes, up to four passes. Run on a copy of a real
 hand-built workspace it moved Nx 23.1.1 to 23.3.0 and the audit gate passed after one pass.
 
+When the repository has **no Nx at all** (no `nx.json`), the step sets it up first, through Nx's own commands rather
+than a template of mnci's: `nx init --plugins=skip` writes `nx.json` and installs `nx`, then `nx add @nx/js` and one
+plugin for each of ESLint, Jest and Vitest the root manifest already uses, so the projects get their targets
+inferred. Where a package has its own `lint` or `test` script Nx names the inferred target `eslint:lint` or
+`jest:test` instead, so the script keeps working under its own name. A repository that already has an `nx.json` is
+not touched by this part. The `adoption without nx` e2e section takes a plain npm workspace through it and then
+through `--overlay`.
+
 **`--kinds`** records each project's mnci kind as a `type:<kind>` tag, in its `project.json` or the `nx.tags` of
 its `package.json` (`mnci projects` shows it). The kind is read from the project itself: an `index.html` next to
 React, an `engines.vscode`, an `OutputType` of `Exe`, a `package main`, `lib/main.dart`. Where two kinds fit (a
@@ -661,8 +712,8 @@ refuses an unclean git tree, takes the same flags (`--scope`, `--registry`, `--o
 `--test-runner` from what the repository already has (its pipeline files, `jest` or `vitest` in the root
 manifest). The existing pipeline goes through the legacy migration: steps mnci does not recognise are kept in
 the three `# mnci:slot` blocks, the ones it does are replaced by `mnci ci <phase>`, and what cannot be carried
-over is listed. Scope, registry and agent have no safe guess, so they are asked for by flag. Adopt does not
-install Nx: a repository with no `nx.json` is told to run `npx nx@latest init` first.
+over is listed. Scope, registry and agent have no safe guess, so they are asked for by flag. A repository with no
+`nx.json` is told to run `mnci adopt --toolchain` first, which sets Nx up.
 
 ## `mnci upgrade`: re-applying the overlay to an existing workspace