@mnci/cli 4.15.0 → 4.17.0

package/README.md

@@ -65,7 +65,7 @@ named here because the next reader deserves to know before opening them:
 
 | Path | Rule waived | Why, and removal condition |
 |---|---|---|
-| `workspace-overlay/overlay.use-case.ts` | one responsibility per file | ~3.5k lines covering CI YAML for two providers, `.npmrc`, `nuget.config`, the VS Code workspace, release config and the CI guard scripts. Splitting it is a decomposition, not a move, so it was deliberately kept out of the change that created these slices. **Temporary** — removed when that decomposition lands. |
+| `workspace-overlay/overlay.use-case.ts` | one responsibility per file | ~5k lines covering CI YAML for two providers (including the native-app job), `.npmrc`, `nuget.config`, the VS Code workspace, release config and the CI guard scripts. Splitting it is a decomposition, not a move, so it was deliberately kept out of the change that created these slices. **Temporary** — removed when that decomposition lands. |
 | `rollup-library/repair-rollup-config.use-case.spec.ts` | a test takes its subject's basename | It also holds the `withUpgradedDeclarationSpecifierPlugin` describe, whose subject is `rollup-config.algorithm.ts`. That transform shares three fixtures with the repairs that apply it (`OLD_DTS_PLUGIN_CONFIG`, `EXTENSION_ONLY_DTS_PLUGIN_CONFIG`, `loadWriteBundle`), and duplicating them across two spec files is the worse trade. **Permanent** unless those fixtures stop being shared. |
 
 `rollup-library/` exists because of the own-the-concept rule. Its contents used
@@ -75,7 +75,7 @@ helpers — they have no interest in adding a project. The concept now sits in i
 own slice that depends on nothing above it (`file-system` alone), and all three
 consumers point at it.
 
-## Commands (deliberately just six)
+## Commands (deliberately just seven)
 
 ```sh
 mnci new my-repo            # create a monorepo (prompts scope + registry)
@@ -104,6 +104,7 @@ mnci add python-vendor shared --lib core  # wire core's module into shared's bui
 mnci add go-app api            # executable -> apps/ (binary, zipped into the drop)
 mnci add go-app cli --release  # ...released: tag + per-platform zips on the GitHub Release
 mnci add go-app tray --cgo     # needs a C toolchain: built on a runner of each OS
+mnci add go-app site --web web # embeds and serves the React app apps/web in one binary
 mnci add go-function-app fn    # serverless handler -> apps/
 mnci add go-lib core           # publishable (by git tag) -> packages/
 mnci add go-internal-lib util  # private shared package -> libs/
@@ -123,6 +124,8 @@ mnci upgrade --agent windows-latest   # ...with an explicit override
 
 mnci doctor                   # check this workspace's invariants (read-only)
 
+mnci ci verify                # the pipeline's verify phase, run here: see `mnci ci` below
+
 mnci sync                     # converge dependency ranges + nx sync (TS project refs)
 mnci sync --check             # ...report and exit non-zero, writing nothing
 
@@ -320,6 +323,35 @@ TTY, so a piped or CI run reports instead of hanging on a prompt), `-y/--yes`
 (take everything), `--ecosystem`, and `--no-install` (edit the manifests but skip
 the reinstall).
 
+## `mnci ci`: the pipeline's phases, as a command
+
+`mnci ci verify` runs the pipeline's verify phase on your machine: `nx sync:check`, then
+every project (or, when a pull request's target branch is set, only the projects affected
+since the merge-base with it) through `lint`, `typecheck`, `test` and `build`. It exits with
+the failing command's own status, so it can stand in for the pipeline's step.
+
+It is not a shortcut for those Nx targets, and the CLI still has no wrapper for `nx test`.
+It is the pipeline's own logic, which until now lived as a `node -e` one-liner inside the
+generated YAML, ported to tested code, so a laptop and a pipeline run the same thing. The
+design (one `npx mnci ci` call in the pipeline, with room for your own steps around it) is
+tracked in #269, and this is its first phase: **the generated pipelines do not call it yet**
+and are unchanged, so nothing about an existing workspace changes. Phases follow as their
+guards are ported.
+
+- **Same scoping as the guard.** No pull-request target means every project, so a push to
+  main verifies in full. A pull request verifies what is affected since the merge-base with
+  `origin/<target>`, fetching the target once if that ref is missing, and falls back to every
+  project when no merge-base can be found, since a run that verifies too little still reports
+  green. The target comes from `GITHUB_BASE_REF` or `SYSTEM_PULLREQUEST_TARGETBRANCH`, so to
+  reproduce a pull request run locally, set one: `GITHUB_BASE_REF=main mnci ci verify`.
+- **Native (cgo) apps are left out**, as in the pipeline, since one agent cannot build them.
+- **Log groups.** Under GitHub Actions and Azure Pipelines each part is a collapsible group
+  (`::group::`, `##[group]`); locally it is a plain heading.
+- **Checked against the guard it replaces.** An integration spec runs the inline guard and
+  this command against the same real git repository, with a recording stand-in for `npx`,
+  across a push, a pull request, Azure's `refs/heads/` form, a missing `origin/<target>` and
+  an unresolvable one, and requires the same Nx commands in each.
+
 ## `mnci doctor`: checking the invariants actually hold
 
 Read-only — it never edits the workspace. Every failing finding names the command
@@ -689,6 +721,64 @@ the generated tree, so it runs afterwards, but still before the first write:
 a refusal leaves the target byte-identical to how it was found, and the staging
 copy is discarded.
 
+### Adopting a flat Go module
+
+A repository with its own `go.mod`, a root `main.go` and `internal/` packages is the
+other common starting point, and `--into` takes it as it is. Measured on a clone of a
+real one (twelve `internal/` packages, its own `release.yml`):
+
+- **`go.mod` and `go.sum` are never touched.** `add go-*` skips the module bootstrap
+  when a `go.mod` exists, so the module path, the `require` lines and the Go version
+  survive byte for byte, and no `go.work` is created.
+- **The Go plugin is registered anyway.** The bootstrap that registers it in `nx.json`
+  is the one that is skipped, which used to leave the plugin installed and unlisted:
+  every target worked, and Nx had **no Go project graph**, so `nx affected` skipped an
+  app that imports a changed library, silently. `add go-*` now registers it, `mnci
+  upgrade` repairs a workspace that adopted before, and `mnci doctor` fails while Go
+  projects exist and it is missing.
+- **Your own workflow coexists.** A release workflow that fires on `v*` tags and the
+  generated `ci.yml`, which fires on pushes and pull requests to `main`, do not overlap.
+  mnci tags a released app `<name>@<version>`, so once `--release` and its GitHub
+  Release assets do what yours did, delete the old workflow.
+- **The format step can fail on a file you already had**, and says so without failing
+  the run: a UTF-16 `.json` at the root made `eslint .` report a parse error. The root
+  lint covers root-level files, so a repository's existing JSON, Markdown and YAML are
+  now inside it; fix or delete what it names.
+
+Landing the code is mechanical, so it is a recipe, not a command (`git mv` and one
+import rewrite are the whole job, and a command would have to guess your layout). With
+`youtube-downloader` as the module path, `mvd-cli` as the app and `mvd-core` as the
+library:
+
+```sh
+mnci add go-app mvd-cli
+mnci add go-internal-lib mvd-core
+
+# The generated starters are placeholders: drop them.
+rm apps/mvd-cli/main.go apps/mvd-cli/main_test.go
+rm -r libs/mvd-core/mvdcore
+
+# git mv, not mv, so `git log --follow` reaches the history before the move.
+git mv main.go apps/mvd-cli/main.go
+for slice in internal/*/; do git mv "$slice" "libs/mvd-core/$(basename "$slice")"; done
+
+# Rewrite the import paths (macOS: sed -i '').
+grep -rl 'youtube-downloader/internal/' --include=*.go apps libs \
+  | xargs sed -i 's#youtube-downloader/internal/#youtube-downloader/libs/mvd-core/#g'
+
+npx nx run-many -t test,build --projects=mvd-cli,mvd-core
+```
+
+Use `nx` and not a bare `go test ./...` from the root: `./...` also walks
+`node_modules`, where npm packages that contain Go code sit (one did here). On the
+repository measured, this left `go build` clean, every test passing, 62 renames
+detected by git, and the app depending on the library in the project graph. The e2e
+(`go adoption`) runs this recipe on a fixture and asserts each of those.
+
+Not measured here: whether `golangci-lint`, which is what each Go project's `lint`
+runs, passes on a codebase that has never been linted. Run `nx run <lib>:lint` before
+relying on it, and expect to fix or silence what it reports.
+
 ## Layout convention = release scoping
 
 | Directory          | Contents                                                       | Released?                              |
@@ -1266,6 +1356,11 @@ get `react-app-<name>-dev` / `-uat` / `-prod`, and the classic release pipeline
 deploys each environment from its own artifact + tag. Need different
 environments? Edit `REACT_ENVIRONMENTS` in the generator.
 
+**A React app can also ship inside a Go binary**, for an app that serves its own UI
+(`mnci add go-app <name> --web <react-app>`): the default `build` is what gets
+embedded, not the per-environment ones, so the app should call its API on the same
+origin (`/api/...`). See _Serving a React app from a Go app_ in the Go section.
+
 ## Python (`@mnci/nx-python-pip` — pip + Ruff + pytest + PyPA `build`/`twine`, no uv)
 
 Python is the first non-JS language, and follows the same philosophy as every
@@ -1485,6 +1580,41 @@ pipeline installs `golangci-lint` itself (see below).
     OS's zip to the same GitHub Release, so one release collects a zip from every
     runner. Azure Pipelines has no GitHub Release to attach to and stops at the
     artifact.
+- **Serving a React app from a Go app (`mnci add go-app <name> --web <react-app>`).**
+  For an app that runs a local server and is used in a browser, shipped as one
+  self-contained binary. `//go:embed` cannot reach outside its package directory,
+  and a React app builds into its own `apps/<react-app>/dist`, so the Go app needs
+  wiring mnci writes for you (the React app has to exist first):
+  - **`stage-web`** copies that `dist` into `apps/<name>/web/`, after the React
+    app's `build`, and the directory is git-ignored (an `apps/<name>/.gitignore`).
+    Its output is declared and its inputs are the React build's outputs, so Nx
+    caches it and a change to the React code reaches the binary.
+  - **Every target that compiles Go depends on it**: `build`, `test`, `lint`,
+    `start`, `build-all` and `build-native` (`package*` reach it through those).
+    `//go:embed` fails at compile time without its files, so on a fresh checkout
+    `go vet`, `go test` and `golangci-lint` fail as well as `go build`. A committed
+    placeholder was rejected: staging replaces the directory, so git would show it
+    modified for ever. The cost is that a Go-only change waits for a React build
+    on a cold cache, and your editor shows the embed error until the first
+    `nx run <name>:stage-web`.
+  - **The project graph knows**: `implicitDependencies` makes the React app a
+    dependency, so changing it marks the Go app affected, while changing the Go
+    app does not rebuild the React app.
+  - **The sources**: `main.go` becomes a small server (`ADDR`, default
+    `127.0.0.1:8080`) that logs the stamped `version`, `web.go` embeds the staged
+    files and serves them (an unknown path falls back to `index.html`, so a
+    client-side route survives a reload), and `main_test.go` checks the embed holds
+    a page. They replace the generated hello world.
+  - **`nx run <name>:dev`** starts the Vite dev server and the Go server together.
+    `add` adds `server.proxy: { '/api': 'http://127.0.0.1:8080' }` to the React
+    app's Vite config (and tells you what to add if it cannot find a `server`
+    block), so the browser talks to Vite and `/api` reaches Go.
+  - **Releasing one.** `package-all` stages once and builds six binaries from the
+    same copy. A native (`--cgo`) app is built on a runner per OS, and **each leg
+    rebuilds the React app**: sharing one frontend build between runners is not
+    done yet.
+  - Types shared between Go and TypeScript (OpenAPI, generated types) are out of
+    scope.
 - **Releasing a Go app is an opt-in: `mnci add go-app <name> --release`.** The
   app is tagged `release:go`, which `release.projects` selects by tag (as it
   does for a VS Code extension, so `mnci upgrade` keeps it). Without the flag