@mnci/cli 4.52.0 → 4.54.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
@@ -657,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
@@ -683,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
 
@@ -1660,7 +1689,7 @@ release version --dry-run`), which wins over the workspace's default
   every Python project workspace-wide (the workspace-wide install above) —
   both skipped cleanly when the workspace has no Python projects.
 
-## Go (`@nx-go/nx-go` — one root `go.mod`, golangci-lint + `go test`)
+## Go (`@nx-go/nx-go` — a `go.mod` per project, a root `go.work`, golangci-lint + `go test`)
 
 Requires **Go 1.21+** on the machine and on the build agent; `mnci add go-*`
 fails fast with an install link when `go` is not on the `PATH`. The generated
@@ -1673,14 +1702,14 @@ pipeline installs `golangci-lint` itself (see below).
 | `go-lib`          | `packages/<name>` | publishable **by git tag** — see below; lint + test targets only                                                                                                                                              |
 | `go-internal-lib` | `libs/<name>`     | private shared code, lint + test only — a non-`main` package produces no binary                                                                                                                               |
 
-- **One root `go.mod`**, matching how TS uses one root `package.json` and
-  Python one root `requirements-dev.txt`. `project-scaffolding/go.use-case.ts` bootstraps it on the
-  first Go `add` by running the plugin's `init` then `convert-to-one-mod`
-  generators, in that order — `convert-to-one-mod` refuses once `go.work`
-  lists any module, so it has to happen before the first Go project exists.
-  Every Go project then shares that module and imports its siblings as
-  `<module>/libs/<name>/<slice>`, with no per-project manifests and no
-  `replace` directives.
+- **One `go.mod` per project, and a root `go.work` mnci owns** (#289), so a Go
+  project's dependencies are declared in that project, like every other
+  language's. `project-scaffolding/go.use-case.ts` bootstraps the workspace on
+  the first Go `add` with the plugin's `init` (no `convert-to-one-mod`); each
+  generator then writes its own `go.mod`, whose module line mnci rewrites to
+  `<host>/<org>/<repo>/<dir>` from the git origin. Siblings import each other
+  by that path, and `go.work` resolves them locally, with no `replace`
+  directives.
 - **A Go library is a capability of slice packages.** The plugin's library
   generator writes `<name>.go` at the project root, which makes the root
   package the whole library. mnci replaces it with a root `doc.go` and moves
@@ -1694,16 +1723,17 @@ pipeline installs `golangci-lint` itself (see below).
   plants a failing test and a lint finding in a nested package and asserts
   both fail the project target, so a plugin change that stopped recursing
   would surface there rather than as a silently green lib.
-- **The `go.work` multi-module layout was rejected deliberately.** Besides
-  splitting dependencies across per-project manifests, it is brittle: a
-  single stale `use` entry — a project directory removed by hand — makes
-  `go list -m -json` fail, and that breaks the **entire** Nx project graph,
-  not just the Go projects. Verified empirically.
+- **The `go.work` multi-module layout was first rejected and then adopted**
+  (#289), because per-project dependencies are the point. Its one hazard is
+  real: a single stale `use` entry — a project directory removed by hand —
+  makes `go list -m -json` fail, and that breaks the **entire** Nx project
+  graph, not just the Go projects. `mnci doctor` fails on one and names the
+  line to remove.
 - **Targets are written explicitly** rather than inferred. `@nx-go/nx-go`
-  supplies `build`/`test`/`lint` by inference, but keys that inference on a
-  per-project `go.mod` — which single-module mode does not have, so nothing
-  is inferred. mnci writes them into `project.json` instead, as it already
-  does for most kinds.
+  supplies `build`/`test`/`lint` by inference, but mnci writes them into
+  `project.json` explicitly so lint is pinned to `golangci-lint` (the plugin's
+  default is `go fmt`, which only reformats), as it already does for most
+  kinds.
 - **The project graph is still inferred, so `affected` is correct.** What the
   plugin does not infer is targets; it still derives the _graph_ from imports.
   An app that imports `libs/<name>/<slice>` depends on that lib, transitively,