@hublo/sentinel 1.3.0 → 1.4.0-alpha.10

package/docs/build-adoption.md

@@ -0,0 +1,521 @@
+# Build adoption cheat sheet
+
+Sentinel owns the Vite toolchain so a module can be built, moved and reasoned about on its own.
+
+There are two families, and they get two different answers, from one rule: **sentinel provides
+the FORM where the form is shared, and the PIECES where it is not.**
+
+|                        | React apps                            | Nest services                                  |
+| ---------------------- | ------------------------------------- | ---------------------------------------------- |
+| what sentinel gives    | the packages, re-exported             | the whole config, as `nestService()`           |
+| what your config keeps | everything below the imports          | four lines                                     |
+| why                    | 4 apps, 4 genuinely different configs | 38 services, one shared 25-line webpack config |
+
+Read [React](#react-apps) or [Nest](#nest-services). A SvelteKit module is declined with the
+versions that would change that, not with a flat refusal: see
+[below](#svelte-modules-and-what-they-need-first).
+
+# React apps
+
+Today `vite`, `@vitejs/plugin-react`, `@tailwindcss/vite`, `vite-plugin-svgr` and `nitro` sit in
+the monorepo's **root** `package.json`, which is what makes a self-contained front app
+impossible.
+
+## Adopt a module
+
+```console
+$ pnpm add -D @hublo/sentinel
+$ sentinel --init --build
+$ pnpm install
+```
+
+`--init` does the whole thing: the `build` script, the `serve` script, the nx target, the
+removal of the build packages sentinel now owns, and **it points your `vite.config.ts` at
+sentinel**.
+
+## What changes in your config: the imports, and nothing else
+
+```diff
+- import tailwindcss from '@tailwindcss/vite'
+- import react from '@vitejs/plugin-react'
+- import { nitro } from 'nitro/vite'
+- import { defineConfig, loadEnv } from 'vite'
+- import svgr from 'vite-plugin-svgr'
++ import { defineConfig, loadEnv, nitro, react, svgr, tailwindcss } from '@hublo/sentinel/build/react'
+```
+
+That is the entire diff. Every attribute, every alias table, every path, every comment stays
+exactly where it was, so your build produces what it produced before **by construction**: only
+where the tools come from changed. Measured on `console`, `career` and `host-admin`, the file
+is byte-identical below the import block.
+
+Your own imports are untouched: TanStack, `@rolldown/plugin-babel`, `@front/theme/node`,
+`node:path`. Sentinel takes only the five packages that sit in the workspace root, which is
+what stops your app being buildable on its own.
+
+If any import is in a shape sentinel cannot map — `import * as vite from 'vite'`, a
+side-effect import, a file that does not parse — **nothing is written at all** and it tells you
+why. A half-adopted build config is the one outcome worse than no adoption.
+
+**Your module needs `"type": "module"`.** Sentinel is ESM only, and Vite decides how to load a
+`.ts` config from the nearest `package.json`: without it, Vite loads the config as CommonJS,
+`require`s sentinel, and fails with a message naming neither your module nor the fix. Sentinel
+checks this before writing anything and tells you to add the field or rename the config to
+`.mts`. Every front app in this repo already declares it, so this is about the next one.
+
+## What sentinel owns, and what stays yours
+
+Sentinel owns the five packages that sit in the workspace root today: `vite`,
+`@vitejs/plugin-react`, `@tailwindcss/vite`, `vite-plugin-svgr` and `nitro`. It re-exports
+them, so your imports resolve from it instead of from the root.
+
+**Everything else stays yours**, and that is the whole design: your plugin order, your ports,
+your `base`, your sourcemap decision, your alias tables, your `optimizeDeps`, your conditional
+plugins. Sentinel never reads them, so nothing in them can be lost.
+
+Your own packages are untouched too. Verified: `@rolldown/plugin-babel`, `@locator/babel-jsx`,
+`@tanstack/react-start` and `@tanstack/router-plugin` are declared by the apps themselves and
+not at the root, so none of them is sentinel's to take.
+`src/roles/build/presets/toolchain.json` records what is taken and what deliberately is not,
+each with its reason.
+
+A shared base of common VALUES was designed and dropped. The measurement is why: parsing the
+three React apps leaf by leaf, what they truly share is six values, and the things that LOOK
+shared are not (`root: __dirname` is the same text with a different value in each,
+`build.sourcemap` is the same variable name computed three ways, `optimizeDeps` is not even
+the same key). Every hard case in those configs is precisely what is not common, so a shared
+shape absorbing them would stop being shared. It may come back as an opt-in later; it is not
+part of adopting.
+
+## Commands
+
+```console
+$ sentinel --run --build              # build this module
+$ sentinel --run --build --ci         # non-zero on failure
+$ sentinel --run --dev                # start the dev server
+$ sentinel --inspect --build          # what it resolves to, and where it departs
+$ sentinel --init --build --dry-run   # show what would change, write nothing
+```
+
+## The `--` your `build` script ends with
+
+`--init` writes `"build": "sentinel --run --build --"`, and that trailing `--` is doing work
+rather than being a typo.
+
+`pnpm run build --mode production` appends the option to the script, so the separator is what
+decides who reads it:
+
+```console
+# with it     -> sentinel --run --build -- --mode production   -> Vite gets --mode
+# without it  -> sentinel --run --build --mode production      -> error: unknown option '--mode'
+```
+
+Sentinel refuses flags it does not know rather than passing them on, which is what turns
+`--dryrun` into an error instead of an option Vite silently ignores. The separator is how you say
+"the rest is for the tool", and sentinel prints `NOT the standard check` when you use it, because
+a build with extra flags is not the one CI runs.
+
+`--inspect --build` reads the manifest and the config's TEXT. It never loads the config, so it
+cannot fail on an app's own terms (career throws without `VITE_BRAND_ID`) and it stays cheap
+across a sweep:
+
+```console
+$ sentinel --inspect --build
+  ✓ console (react) build — runner=vite configFile=vite.config.ts vite=sentinel
+    overrides=0 prerequisite=pnpm run prepare:brand-runtime-artifacts adopted=true
+```
+
+`vite=sentinel` is the field nothing else reports and the one worth reading: an adopted config
+takes its plugins from sentinel, so a module answering `module` here is one build away from
+running two copies of Vite against each other.
+
+## The dev server, and why `--init` migrates it too
+
+Your app calls the toolchain **twice**: `build` and `serve`. `--init` migrates both, because
+migrating one leaves the workspace root unable to drop the packages.
+
+That is not a sentinel limitation, it is how pnpm links binaries. Measured with sentinel's exact
+shape — `vite` as a dependency of a package your app depends on:
+
+```console
+$ pnpm exec vite --version
+Command "vite" not found
+```
+
+pnpm links a **direct** dependency's binaries, not a transitive one's. Sentinel resolves its own
+Vite and always did; it is your `serve` script calling `vite` directly that stops resolving.
+
+`--init` rewrites only the tool call and keeps whatever wraps it:
+
+```
+before: … --touch-file …/App.tsx -- pnpm --dir apps/front/console exec vite --host 0.0.0.0
+after : … --touch-file …/App.tsx -- sentinel --run --dev -- --host 0.0.0.0
+```
+
+Your own options travel through `--`. Vite's `dev` / `serve` subcommand is dropped, since the
+verb already says which one this is. It rewrites `serve`, not `dev`, because that is where the
+call lives in all three apps — `dev` is a one-line alias to it.
+
+**The rewritten `serve` names its module** (`sentinel --run --dev --module console`). It has
+to: the script does not call sentinel from your app, it hands the call to the `@front/theme`
+watcher, which spawns from the WORKSPACE ROOT. From there sentinel sees every module, and a
+dev server is a one-module command, so it refuses rather than starting several. Measured:
+without the flag, `pnpm run serve` answers "this resolved to 439 [all]" and exits 1.
+
+**`--dev` is never swept**, and it is refused across more than one module whoever asks. An
+unqualified `sentinel --run` skips it entirely, so a sweep across the workspace answers a
+question rather than launching a server per module.
+
+**The read verbs refuse it too.** `--inspect --dev`, `--report --dev` and `--status --dev` exit
+1 and point at `--build`. A server is started, not read: it has no state of its own, since its
+config, its resolution and its plugins are the build's, since one `--init` plan writes `build` and
+`serve` together. An answer here could only repeat `--build`'s, and a second surface saying the
+same thing is one more to keep true. The refusal names the way out in your own verb, and says
+that `--init --dev` is how the target is adopted.
+
+Unlike `--run --build`, it does **not** run `prebuild`: the artefact is produced by the watcher
+that wraps this command, and running it again would race the watcher about to own the file.
+
+**And it retires the `serve` target in your `project.json`**, when that target does nothing but
+call the script. A dev server needs nothing from nx: it never terminates so it is never cached, it
+writes no output to restore, and no caller hands it a flag the bundler would refuse. So the script
+alone declares it and nx infers the target, which is not a theory — `host-admin` has no `serve`
+target at all and its dev server runs.
+
+This arrived late, and the reason is worth stating: `--init` rewrote the script and stopped there,
+so an adopted module kept one dev server with two declarations, and `--inspect` called it
+conformant. It is a drift check now.
+
+A target that does **more** than delegate — a `dependsOn`, its own options, a different command —
+is left exactly where it is, and named in `--inspect` instead. Removing it would drop behaviour
+this role never declared, and that is a decision for whoever wrote it.
+
+## Your `vitest.config` moves too
+
+An app calls the toolchain from more than one file, and `--init` follows it everywhere.
+Measured here: `career` and `host-admin` import `loadEnv` from `vite` in their
+`vitest.config.ts`, and `libs/front/ui` imports `mergeConfig`. Left behind, those imports stop
+resolving the day the root drops the packages, and they fail your TESTS rather than your build,
+long after the adoption that caused it.
+
+Note that `vitest/config` exports a `mergeConfig` of its own. That one is vitest's and stays
+where it is: the rewrite matches on the import specifier, never on the name.
+
+## Why the imports, and only the imports
+
+An earlier design read your config and rebuilt it around `reactApp`. It was dropped, for a
+reason worth stating: a Vite config is **code**, not configuration. `career`'s alias table
+opens with `...frontThemeAliases`, a constant declared 130 lines earlier; `host-admin` has
+three conditional plugin groups; one nitro block carries a comment explaining a rolldown SSR
+interop bug. Moving expressions and hoping nothing referenced them fails as a build that
+_succeeds_ and ships the wrong bundle, which is the one failure a migration tool must not have.
+
+Leaving that edit to you was worse. It is real work on a file nobody enjoys touching, so it
+would not get done, and the root would stay unblocked forever.
+
+Changing only the imports removes the dilemma: sentinel **reads nothing**, so there is nothing
+it can lose. The parsing is done with `oxc-parser` rather than by matching lines, because an
+import can be renamed, wrapped, or sitting next to a commented-out import of the same package
+(`host-admin` has one) — and a regex that gets any of those wrong edits a file nobody
+re-reads.
+
+## `resolve.alias` is passed through, never read
+
+Sentinel does not read, rewrite or resolve your alias table. It goes in as an option and comes
+out unchanged, so nothing in it can be lost by adopting.
+
+Your config file stays in your app, so `__dirname` is still your app's directory. Verified on
+`console`: the 17 resolved `replacement` paths are identical before and after, pointing at the
+app's real files rather than anything under sentinel.
+
+Deriving the table from `tsconfig.base.json` — which already holds all 401 path mappings — is
+its own ticket, with a build-output comparison as its acceptance criterion.
+
+## TanStack stays yours
+
+`@tanstack/react-start` and `@tanstack/router-plugin` do **not** move to sentinel. 48 app source
+files import the first directly: it is a framework your app codes against, not a tool that
+builds it, and the router plugin generates your app's own route tree.
+
+That is why you pass the factories in. Sentinel decides _when_ to call them — the router plugin
+alone under test, `tanstackStart` and `nitro` otherwise — while the packages stay where they
+belong. The day the bundler changes, `--migrate` removes that line.
+
+## Sentinel's Vite runs, not yours
+
+The binary is resolved from **sentinel's** install first, which is the opposite of every other
+role. An adopted config imports its plugins from `@hublo/sentinel/build/react`, so they are
+bound to sentinel's Vite; a binary from your module — or, in this monorepo, from the workspace
+root — hands the plugins a different Vite than the one running them. Nothing reports a version
+conflict: a hook simply never fires.
+
+`--run --build` says so out loud if it happens, and `--inspect --build` reports which install
+answered.
+
+## `prebuild` runs, even in CI
+
+If your module declares a `prebuild` script, `--run --build` runs it first.
+
+npm's lifecycle fires `prebuild` before `build`, so `pnpm run build` was always safe — but
+`sentinel --run --build` is what CI calls, and it is not. All three front apps here generate a
+gitignored branding artefact in `prebuild`; skipping it produces an error naming a tool that is
+not at fault.
+
+It runs **once**: `npm_lifecycle_event` says whether the script runner already fired it.
+
+## Checking an adoption is COMPLETE, not merely started
+
+`sentinel --inspect --build` reports a module as conformant only when everything adoption writes
+is there. Seven things, and each of them shipped missing at least once:
+
+| What it checks                                                  | What its absence cost                                                                                                                                  |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| the `build` npm script                                          | `pnpm run build` did nothing; only nx could build the module                                                                                           |
+| the script invokes sentinel                                     | the config pointed at sentinel while the command ran something else                                                                                    |
+| `nx.targets.build` exists                                       | the build ran on nx's DEFAULT inputs while every sibling target declared its own                                                                       |
+| `outputs`, when `cache: true`                                   | nx cached the build and restored **0 of 464 files**, with the target green                                                                             |
+| `^default` among `inputs`                                       | declaring `inputs` REPLACES nx's default, so the build stopped hashing its dependencies                                                                |
+| `forwardAllArgs: false`                                         | the image's `--generatePackageJson` reached Vite, which refuses it                                                                                     |
+| no `build` target left in `project.json`                        | two declarations, and which one nx runs depends on the caller                                                                                          |
+| no `serve` target left there either, once its script is adopted | the same fault on the dev server, and this check missed it for the whole role: `console` read `conformant=true drift=[]` with the target still on disk |
+
+None of these was found by a check. Each was found by a person reading a diff, which is why they
+are checks now: `--status` counts them across every module, so the next one is visible everywhere
+rather than on the two files somebody happens to open.
+
+**What it cannot check:** whether the translation LOST something. Once a service is adopted its
+webpack target is gone, so an `assets` list that was dropped and one that never existed look
+identical. That property belongs to the moment of translation, and is held by the refusals (a
+target sentinel cannot translate faithfully is refused, not approximated) and by the tests that
+pin what the translation reads.
+
+## Your config is CODE, and it runs before the build does
+
+A Vite config is executed, not parsed. Whatever it reads from the environment, it reads at that
+moment — before a single file is bundled, and before sentinel has done anything.
+
+So a shell or a container missing one of those variables fails at config load, with an error from
+your config rather than from the build. Measured here: `host-admin` and `career` both stop with
+
+```
+Error: Missing branding environment variable "VITE_BRAND_ID". Expected one of: hublo, hublo-nova
+```
+
+That variable is not sentinel's, and adoption neither adds nor removes the requirement: the same
+config asked for it before. It is worth knowing because the message names your config and the
+moment is early enough to look like the build role is broken.
+
+The one thing to check when you move a build somewhere new — a fresh clone, another CI job, an
+image — is that it carries the variables your config reads. `sentinel --init --build` says so at
+the end of a React adoption, for the same reason.
+
+# Nest services
+
+## Why this is happening now
+
+Not a preference. Nx v24 removes the `@nx/webpack:webpack` executor and the `composePlugins` /
+`withNx` helpers `tools/webpack-configs/` is built on, and nx's own migration generator refuses
+all 38 services because they use `@nx/js:node` ([nrwl/nx#36389]). There is no version of "stay on
+webpack" available, so the way out runs through here.
+
+[nrwl/nx#36389]: https://github.com/nrwl/nx/issues/36389
+
+## Your build stops checking types, and gets faster
+
+The webpack target ran `"compiler": "tsc"`, so it type-checked every file it compiled, as a side
+effect of compiling them. The new build bundles and does not. That is deliberate: a build builds,
+and `typecheck` is its own target, which CI already runs on every pull request.
+
+You gain time, and it was measured on `main` rather than promised: median compile went from 36s to
+21s on `contract` (20 webpack builds against 10 Vite ones) and from 33s to 24s on `network`
+(8 Vite builds).
+
+You lose nothing on a pull request, and you gain coverage. Webpack compiled `tsconfig.app.json`,
+which excludes `*.spec.ts`, `*.mock.ts`, `*.fixture.ts`, `*.steps.ts` and `*.integration-spec.ts`.
+The `typecheck` target builds the projects your `tsconfig.json` REFERENCES, so the app and the
+specs. Your test files are type-checked for the first time.
+
+What genuinely changes is the deploy path: `build-and-publish-orchestrator` runs on a push to
+`main` and type-checks nothing, where the old build would have failed there. The residual risk is
+a type error that passes its own pull request and only appears once two of them meet on `main`.
+Measured over the 12 weeks before adoption on those two services, the build's type check stopped
+zero real errors, so nothing was added to the deploy workflow to cover it. A service that wants
+the check back at build time adds it to its own `build` script, which stays its decision.
+
+## Adopt a service
+
+```console
+$ pnpm add -D @hublo/sentinel
+$ sentinel --init --build
+$ pnpm install
+```
+
+That writes both files below and needs no manual step. It is a TRANSLATION, not a scaffold:
+every value the config needs is already declared in the webpack target your service builds with
+today, and those are exactly the values a human miscounts. It is also safe to re-run, which is
+how you verify your own adoption.
+
+It **refuses** rather than guessing when your target is not one it reproduces: a service with
+its own webpack config (one exists here, loading `.sql` files as raw text), or a `production`
+configuration whose `fileReplacements` point at files that exist. It says which, and writes
+nothing.
+
+What it writes, so you can review it. The config, which must be **`vite.config.mts`**:
+
+```ts
+import path from 'node:path'
+
+import { nestService } from '@hublo/sentinel/build/nest'
+
+export default nestService({
+  project: 'poe',
+  root: __dirname,
+  workspaceRoot: path.resolve(__dirname, '../../../..'),
+  outDir: 'dist/apps/nest/microservices/poe',
+})
+```
+
+`.mts` and not `.ts`: a Nest service is CommonJS, sentinel is ESM only, and Vite decides how to
+load a `.ts` config from the nearest `package.json`. Without the extension it loads the config as
+CommonJS, `require`s sentinel, and fails with a message naming neither your module nor the fix.
+
+Then the npm script and the nx target, both in `package.json`, exactly as `--init` writes them on
+`poe`:
+
+```json
+"scripts": { "build": "sentinel --run --build --" },
+"nx": {
+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "pnpm --filter poe run build",
+        "forwardAllArgs": false
+      },
+      "cache": true,
+      "inputs": ["default", "^default", "{projectRoot}/vite.config.mts"],
+      "outputs": ["{workspaceRoot}/dist/apps/nest/microservices/poe"]
+    }
+  }
+}
+```
+
+**Why an explicit target here**, where lint, format and typescript let nx infer one from the script:
+the image runs `nx run <project>:build --generatePackageJson`, and an inferred npm-script target
+forwards unknown arguments, which sentinel and Vite would both refuse. `forwardAllArgs: false`
+makes nx swallow the flag, which is what lets the Dockerfile stay identical for a migrated and a
+non-migrated service alike. That is also why the two roles' blocks do not look alike: those three
+declare `cache` and `inputs` and nothing more, because nothing else is needed for them.
+
+**Why the command runs the SCRIPT and not sentinel.** It used to be `pnpm exec sentinel --run
+--build` with a `cwd`, and that skipped the module's own `prebuild`: `console` prepares its brand
+artefacts there, and npm fires `pre<script>` only when the script is what was invoked. Going
+through `pnpm --filter <name> run build` keeps that hook, and it costs nothing on a service that
+has none.
+
+A Nest service has no dev server to migrate; that half is
+[a React concern](#the-dev-server-and-why---init-migrates-it-too).
+
+## The check that decides whether you are done
+
+Not "it builds", and not "it starts". Every service already has a `generate-swagger-file` target
+that **runs the built bundle** and writes its OpenAPI contract into a committed file:
+
+```console
+$ nx run <service>:build --generatePackageJson
+$ nx run <service>:generate-swagger-file
+$ git diff --exit-code libs/api-types/service-<service>/
+```
+
+That proves the service boots **and** that its public API did not move, in one step. It is not
+optional advice: the first version of this preset built and started, and moved the contract of
+the second service it was tried on.
+
+## What the preset does for you, and why each part exists
+
+**Decorator metadata, emitted by TypeScript.** esbuild cannot emit `emitDecoratorMetadata` and
+Nest cannot live without it. The transform reads your module's own tsconfig, so the emit is
+preserved rather than re-chosen. It is deliberately not swc, which is ten times faster and wrong:
+swc drops the `=== "function"` guard tsc puts around a serialized type, so an enum imported into
+a DTO reaches `@nestjs/swagger` instead of `Object` and the service throws
+`A circular dependency has been detected` at boot.
+
+**One output file per module.** Hoisting everything into one scope forces the bundler to rename
+duplicate class names, and `@nestjs/swagger` keys its schemas on `class.name`, so a renamed class
+silently becomes a renamed schema in your published API.
+
+**The pruned `package.json` and lockfile** the image installs from, built from the nx project
+graph exactly as `--generatePackageJson` did.
+
+**A refusal to ship a manifest that would not install.** The build compares what the bundler left
+external against what the manifest declares. This is the check that would have caught `tslib`
+arriving through `importHelpers` without any module declaring it, which killed a pod while every
+build was green.
+
+## If you need something the shape does not give you
+
+Pass `overrides`, merged with Vite's own `mergeConfig`:
+
+```ts
+export default nestService({
+  /* … */
+  overrides: { build: { sourcemap: false } },
+})
+```
+
+Or drop to the pieces, which the same entry point exports individually: `decoratorMetadata`,
+`nodeManifest`, `tsconfigAliases`, plus Vite's `defineConfig`, `loadEnv` and `mergeConfig`.
+
+# Both families
+
+## Svelte modules, and what they need first
+
+Sentinel ships **Vite 8**. `@sveltejs/vite-plugin-svelte` caps at Vite 6 until its major 7, and
+that major requires `svelte ^5.46.4`. So the build role cannot apply to a SvelteKit module still
+on Svelte 5.19 or 5.25, and it says exactly that rather than "this is not a React app":
+
+```console
+$ sentinel --init --build
+  build: the build role does not apply to this module yet:
+  @sveltejs/vite-plugin-svelte is at 5.0.3, needs >= 7.0.0; svelte is at 5.25.6,
+  needs >= 5.46.4. sentinel ships Vite 8, and @sveltejs/vite-plugin-svelte caps at
+  Vite 6 until its major 7. Nothing was written. Raise those versions, check the
+  module still builds and its tests still pass, then re-run `sentinel --init --build`.
+```
+
+**Sentinel does not raise them for you**, and that is deliberate. Removing a tool it replaces and
+raising the framework your source is written against are different acts: a reviewer sees the line
+`5.19.9 -> 5.46.4`, nobody sees a behaviour change at runtime, and a green build does not prove
+there is none. The decision belongs to whoever owns the module.
+
+It is a **skip**, not a failure. `sentinel --init` on such a module still adopts lint, format and
+typescript, and exits 0.
+
+Adding sentinel for those roles does **not** disturb your Vite 6, verified under pnpm's isolated
+layout: your plugin keeps resolving your own Vite, and sentinel resolves its own.
+
+The requirements live in `presets/requirements.json`, one entry per preset, each carrying the
+reason it exists.
+
+## Troubleshooting
+
+**`--init --build` says there is no Vite config.** Then this module has not been given one yet.
+Sentinel does not scaffold it, on either side: a config it invented would give the module a
+second build path nobody reviewed. On the Nest side, write the four lines above yourself, which
+is also how the diff stays readable to whoever approves it.
+
+**`--init --build` says the preset does not handle this module.** Detection answers `node` for
+a front app, because the build toolchain is declared at the workspace root and your app declares
+none of it. Sentinel reads your Vite config instead: `@vitejs/plugin-react` or
+`@tanstack/react-start` makes it React, and `@hublo/sentinel/build/nest` makes it Nest. If your
+config imports neither, it genuinely is not one of the two.
+
+**`--inspect --build` reports a `configError`.** Your config threw while loading. `career` does
+this without `VITE_BRAND_ID`: the config is loaded for real, so it needs the same environment a
+build needs. The message names what is missing.
+
+**`--init --build` wrote nothing and named an import.** Sentinel refuses rather than guesses:
+a namespace import (`import * as vite from 'vite'`), a side-effect import, or a config that
+does not parse cannot be mapped onto named exports. Nothing is written, including the
+`package.json` side, because a `build` script running sentinel's Vite against a config whose
+plugins still come from the root is the two-copies failure this role exists to prevent.