@mnci/cli 1.9.1 → 1.11.0

package/README.md

@@ -75,6 +75,43 @@ each a single cross-platform command:
 | `npm run python:install`  | fixed Python toolchain (ruff/pytest/build/twine) + editable-install every Python project — the same two guards CI runs, for local dev |
 | `prepare`                 | `husky` (commit-msg lint hook)                                                                                                        |
 
+## Every `add` also wires local-dev commands
+
+Every `mnci add` (and the inline `internal-lib` case) finishes by calling
+`registerProjectCommands` (`commands/add/shared.ts`), which writes up to three
+root `package.json` scripts for the project just added:
+
+| Script         | Runs                                       | When it's added                                                                                                                                    |
+| -------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<name>:build` | `nx run <name>:build`                      | the kind has a `build` target (not every kind does — a private lib with nothing to publish, or a Python function app deployed as source, has none) |
+| `<name>:qa`    | `nx run <name>:lint && nx run <name>:test` | always — every kind has both                                                                                                                       |
+| `<name>:start` | the kind's real local-dev command          | only kinds with a genuine dev-server story — never a library                                                                                       |
+
+The same three (when present) are appended as VS Code Tasks into the
+workspace's `<workspace-name>.code-workspace` file, so they also show up
+under **Terminal → Run Task** / the Command Palette — `build`/`qa` grouped
+accordingly, `start` marked `isBackground` since it runs a process that
+doesn't exit on its own. Re-running `add` for the same project name
+overwrites its own scripts/tasks rather than duplicating them.
+
+`:start` resolves differently per kind — an existing generator target where
+one already exists, a small `nx:run-commands` target mnci writes where none
+did:
+
+| Kind(s)                                    | `:start` runs                                                                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `react-app`, `node-app`                    | `nx run <name>:serve` — the generator's own inferred dev-server target                                                                |
+| `node-function-app`, `python-function-app` | `nx run <name>:start` → `func start` (Azure Functions Core Tools, install separately — never a prerequisite for `add` itself)         |
+| `python-app`                               | `nx run <name>:start` → `python3 main.py` — mnci writes a runnable `main.py`, since the plugin's own sample module has no entry point |
+| `go-app`                                   | `nx run <name>:start` → `go run .`                                                                                                    |
+| `flutter-app`                              | `nx run <name>:start` → `flutter run -d chrome` (web is the only platform this plugin builds for)                                     |
+| every library, `go-function-app`           | no `:start` at all — see below                                                                                                        |
+
+**`go-function-app` is a known gap, not an oversight**: unlike the Node and
+Python function-app kinds, it writes no `host.json`/custom-handler config, so
+there is nothing for `func start` to attach to. Shipping a `:start` script
+that would just fail felt worse than being upfront that it doesn't exist yet.
+
 ## What `new` actually does
 
 1. `npx create-nx-workspace@latest <name> --preset=ts` — npm workspaces +
@@ -84,15 +121,18 @@ each a single cross-platform command:
    default for): independent versioning from **conventional commits**,
    `{projectName}@{version}` tags, **tag-only git** (`commit: false`) — nothing
    is ever pushed to `main`; future runs resolve versions from tag names.
-3. Writes `.npmrc` (Azure Artifacts feed or public npm — scope routing makes
-   accidental public publishes impossible), `commitlint.config.mjs`, a husky
-   `commit-msg` hook, the chosen CI provider's pipeline file(s)
+3. Writes `eslint.config.mjs` (three lines importing `@mnci/eslint-config` —
+   the whole linting opinion, in one root config), `.prettierrc.json` +
+   `.prettierignore`, `.npmrc` (comment-only — see **Known gaps** below),
+   `commitlint.config.mjs`, a husky `commit-msg` hook, the chosen CI provider's
+   pipeline file(s)
    (`azure-pipelines.yml` and/or `.github/workflows/ci.yml`, `--ci`, default
    `azure`; `github`/`both` also gets `.github/dependabot.yml` — weekly
    dependency-update PRs), a `<workspace-name>.code-workspace` file (VS Code
-   workspace configuration with folder structure, ESLint/Prettier settings, and
-   recommended extensions — open it in VS Code via `File > Open Workspace from
-File`), and the curated root scripts.
+   workspace configuration with folder structure, ESLint/Prettier settings,
+   recommended extensions, and an empty `tasks` array that `mnci add` fills in
+   per project — see below — open it in VS Code via `File > Open Workspace
+from File`), and the curated root scripts.
 4. Installs the chosen **stack** (see below), `husky` + `@commitlint/*` for
    real, so versions resolve at generation time.
 
@@ -105,9 +145,23 @@ this existed; nothing let an already-generated workspace pick one up.
 same options `new` would have and calls the exact same `applyOverlay` `new`
 itself calls — the one function that does every bit of `mnci`-owned file
 writing (`nx.json`'s `release`/`sync`/`generators`/`mnci` blocks, `.npmrc`,
-`commitlint.config.mjs`, `.husky/commit-msg`, the CI pipeline file(s), and the
-curated root `package.json` scripts). Nothing else in the workspace — app/lib
-source, `project.json` targets from `mnci add` — is ever touched.
+`eslint.config.mjs`, `.prettierrc.json`, `commitlint.config.mjs`,
+`.husky/commit-msg`, the CI pipeline file(s), and the curated root
+`package.json` scripts). Nothing else in the workspace — app/lib source,
+`project.json` targets from `mnci add` — is ever touched.
+
+`upgrade` also **deletes** things, which is stronger than the overwriting it
+has always done — one more reason to run `git diff` first, as the command's own
+output tells you to:
+
+- `create-nx-workspace`'s `.prettierrc` and `.vscode/`, both superseded (by
+  `.prettierrc.json`, which Prettier would otherwise never reach, and by the
+  `.code-workspace` file).
+- **every per-project `eslint.config.*` under `apps/`, `libs/` and
+  `packages/`.** This is the migration path for a workspace generated before
+  mnci owned linting: without it an upgrade would install the root config while
+  each project kept linting against its own stale copy. The root config is never
+  touched, and neither is a config anywhere outside those three directories.
 
 ```sh
 mnci upgrade                          # re-apply from persisted config alone
@@ -144,13 +198,33 @@ stack:
 | --------------- | ------------------ | ------- | ---------------------------------------------------------------------------------------- |
 | `--test-runner` | `jest` \| `vitest` | `jest`  | `nx.json` generator `unitTestRunner` default; the hand-built function app follows it too |
 
-**Linting and formatting are unified across the workspace**: every project uses
-**ESLint + Prettier** with the JavaScript Standard Style configuration (no
-semicolons, single quotes, 2-space indents). ESLint is a per-project Nx target
-handling code quality (correctness only), while Prettier handles all formatting.
-Both are automatically configured; `npm run lint` checks code quality, `npm run
-format` (write) and `npm run format:check` (CI-safe) handle formatting. The CI
-runs lint/test/build only — formatting is left as a local/pre-commit step.
+**Linting and formatting are unified across the workspace, from exactly one
+config file each.** The root `eslint.config.mjs` is three lines importing
+[`@mnci/eslint-config`](../eslint-config/README.md); every `@nx/*` generator
+drops a config into the project it creates, and `mnci add` deletes it. Projects
+still get their `lint` target: `@nx/eslint/plugin` infers it by mapping config
+_directories_ onto the project roots beneath them, so the root config covers
+them all. (Verified, not assumed — and the e2e enforces both "every project has
+a `lint` target" and "the root config genuinely reports violations in a project
+with no config of its own", because a future Nx change there would silently
+switch linting off workspace-wide.)
+
+ESLint handles code quality only; **Prettier owns all formatting**, configured
+for JavaScript Standard Style (no semicolons, single quotes, 2-space indents, no
+trailing commas). `mnci` runs Prettier itself at the end of `new` and every
+`add`, so a generated workspace passes its own `format:check` immediately — Nx's
+generators emit semicolons and double quotes, and without that pass the first
+commit buries every real change under generator noise.
+
+One caveat worth knowing: `space-before-function-paren`, Standard's signature
+rule, is **not** enforced. Prettier rewrites `function f (a)` to `function f(a)`
+on every run and has closed the corresponding option permanently, so enabling it
+would make `npm run lint` and `npm run format:check` mutually unsatisfiable.
+Choosing Prettier means accepting its call there.
+
+`npm run lint` checks code quality; `npm run format` (write) and
+`npm run format:check` (CI-safe) handle formatting. The CI runs lint/test/build
+only — formatting is left as a local/pre-commit step.
 
 TypeScript is not a question — every workspace runs the **dual compiler** from
 [Nx's TS 7 guide](https://nx.dev/docs/technologies/typescript/guides/typescript-7):
@@ -428,6 +502,13 @@ than a surprise:
 
 ## Known gaps (accepted for the experiment)
 
+- **The generated `.npmrc` is empty (comments only), so `npm publish` will not
+  authenticate.** This is a deliberate deferral, not an oversight: the previous
+  file claimed here that scope routing made accidental public publishes
+  impossible, when in fact no `@scope:registry` line was ever emitted. Rather
+  than ship half-wired auth, the CI token export (`NODE_AUTH_TOKEN`/`PAT`) is
+  left in place so wiring it later is one line, and the generated `.npmrc`
+  carries a comment saying so. Publish-path e2e assertions are relaxed to match.
 - No `doctor`/`resurrect`/`spell` — out of scope until the model is proven.
 - **Flutter apps build for web only.** Android would require the Android SDK and
   NDK on every build agent; iOS is impossible on a Linux agent regardless. Add