- The CI wiring guard matched a substring, and last round's justification for that was wrong: it accepts a longer script name (`npm run verify:skills:cli:disabled`) and a mere mention (`echo npm run verify:skills:cli`), either of which lets the real validator be removed while the guard stays green. `runsCommand` now splits the script on the separators that begin a new command and requires a segment to equal the invocation exactly, with both counterexamples as regression cases. - `local-dev`'s own description and its AGENTS.md index row both still promised "where a new dependency must be declared" — the rules round 13 moved out of it entirely. Both now describe what the skill actually carries: the reasoning behind those rules. Recorded listing share updated to 1,199/4,000. Signed-off-by: cliffhall <cliff@futurescale.com>
8.9 KiB
| name | description | disable-model-invocation |
|---|---|---|
| local-dev | Getting the Inspector running locally, and the reasoning behind its dependency rules. Which install to run and which script starts each client (web, cli, tui, launcher); why v2 is not an npm workspace; how the @inspector/core alias works; and why the placement rules in AGENTS.md are what they are — what each one is defending against, what it looked like when it was violated, and how to tell you have hit one. | false |
Local development
The rules a reviewer cites (TypeScript, Mantine/React, testing, the gate)
stay in AGENTS.md. This skill is how to get the thing
running and where a package goes.
Install
Requires Node >=22.19.0.
npm install # at the REPO ROOT
v2 is not an npm workspace — each client under clients/* keeps its own
package.json and node_modules. A single root npm install is still all you
need: the root postinstall (scripts/install-clients.mjs) cascades
npm install into clients/web, clients/cli, clients/tui, and
clients/launcher.
- Fresh clone:
npm installat the root. - After a pull that changes a client's dependencies: re-run
npm installat the root to re-sync every client.
The cascade is dev-only — it exits early when the package is installed under
node_modules, and a consumer never needs it because the tarball ships
prebuilt artifacts (each client's build/, plus clients/web/dist and
clients/web/static) rather than sources to compile. Set
INSPECTOR_SKIP_CLIENT_INSTALL=1 to skip it. The files allowlist itself is
docs/publishing.md.
⚠️ In a git worktree, do a real npm install. A symlinked node_modules
passes lint, tests and coverage, then fails every Storybook story file on Vite's
fs.allow.
Running
For day-to-day web iteration, run Vite directly — fast HMR, no launcher build needed:
cd clients/web && npm run dev
The launcher-driven scripts run the built launcher, so npm run build
first:
npm run build # web → cli → tui → launcher
npm run web # prod web launcher against clients/web/dist
npm run web:dev # web launcher in --dev mode (Vite)
Individual builds: build:web, build:cli, build:tui, build:launcher. The
web build produces both the browser SPA (clients/web/dist, Vite) and the Node
prod-server runner (clients/web/build, tsup).
To run the CLI or TUI: node clients/launcher/build/index.js --cli … /
--tui ….
The @inspector/core alias
core/ holds the logic shared by all three clients and intentionally has no
package.json — it is not published on its own. Each client bundles it via a
build-time alias:
- CLI / TUI —
esbuildOptions.aliasintsup.config.tsmaps@inspector/core→ the repocore/directory, withnoExternal: [/^@inspector\/core/]inlining it. - Web — two configs, because the client is two builds:
clients/web/vite.config.tsfor the browser app, andclients/web/tsup.runner.config.tsfor the Node backend runner, which defines the alias itself. Dependency or debugging work on the runner belongs in the tsup config, not the Vite one (Copilot).
Where a dependency goes
The rules are in AGENTS.md → Dependency placement, and
they are not restated here. Read them there and come back for the why — what
each rule is defending against, what it looked like when it was violated, and how
to tell you have hit one.
Work the rules in order: which manifest declares it, then dependencies vs
devDependencies, then whether the bundlers must also externalise it.
Why the SDK packages are root-only
A per-client declaration installs a second copy that drifts from the root's.
Not theoretical: it put two versions of ext-apps (1.7.4 / 1.7.5) and of the
transitive v1 @modelcontextprotocol/sdk (1.29.0 / 1.30.0) in the tree at once
(#1970). A second copy of client/core is exactly the failure the dedupe +
server.deps.inline workaround in vitest.shared.mts exists for.
The same reasoning extends to anything reached only through root-owned code that
has no manifest of its own (test-servers/src, core/) — hence the repo-root
alias for those in vitest.shared.mts. express and yaml are the two today.
Why runtime consumption decides dependencies
The client builds externalise npm packages, so a published install resolves them from the root manifest — and devDependencies are not installed for consumers. A runtime import parked there therefore breaks the published package while passing every local check, which is the worst shape a mistake can take here.
Two live examples worth knowing:
expressis test-only, so it is a devDependency.viteand@vitejs/plugin-reactlook like build tooling but are rootdependencies, becauseclients/web/server/start-vite-dev-server.tsimports them at runtime for--web --dev. Moving them would break that for consumers while every local check stayed green.
Why a root dependency must also be externalised
tsup and Vite externalise what the client's package.json declares, and a
root-only dependency is in none of them — so it is bundled, silently. For a
CJS package inlined into an ESM bundle that is fatal: esbuild leaves a
Dynamic require of "path" is not supported shim that throws at import time,
so the binary dies before it parses a flag (proper-lockfile, #2082).
undici (#2067) is the worse variant, because it is import()ed lazily: the
binary boots fine and only the proxied path dies — with esbuild's rewritten
specifier (import("./undici-HXPKCIY3.js")) meaning no user-side install can
ever satisfy it. It was declared in clients/cli/package.json, so the CLI
looked correct while web and TUI silently inlined 1.05 MB of it.
How to tell. The ordinary tiers cannot: unit and integration tests run
against source, where the real package is on the resolution path, and the smokes
never take the lazy path. npm run verify:bundle-externals reads the built
output for exactly this reason — the config and the output disagreed for four
releases.
⚠️ Probing by hand with node -e falsely succeeds. node -e exposes a
global require that satisfies esbuild's typeof require !== "undefined"
guard, so the chunk looks loadable when it is not. Reproduce from a real .mjs
file.
Why React-rendering packages are the exception
An externalised package resolves its own react from wherever npm placed
it — beside a React satisfying that package's peer range, which is looser
than ours in every case here. ink-form and ink-scroll-view declare ">=18",
so a consumer's React 18 satisfies them and hoists them while our React 19 nests
underneath: the bundle renders through one React, those packages call hooks on
another, and the TUI crashes on the first hook (#1952).
ink is exempt on cost (~1.4 MB of react-reconciler + yoga-layout, plus
a createRequire banner). ⚠️ Never justify that exemption by a peer range —
it briefly read "its ">=19" peer keeps npm honest", which is false: a consumer
pinning React 19.0 satisfies ">=19" while a narrower range of ours nests
underneath. What makes it safe is the root react range staying open to the
whole major, so npm can dedupe. clients/tui/__tests__/tsupConfig.test.ts
enforces the whole split, the exemption included.
Why a version skew is worth aligning rather than working around
Because v2 is not a workspace, the same package can appear twice in one tsc
program — a client's own install plus the root's, reached through core/ or
test-servers/src. At the same version that is harmless; on a skew TypeScript
must relate two structurally-distinct declarations, which for a
recursive-generic surface is exponential. A zod 4.3.6 / 4.4.3 skew exhausted
the 4 GB tsc heap outright with TS2589 (#1896).
⚠️ Raising the heap hides the class rather than fixing it. Align the
versions; npm run verify:dep-lockstep is the guard, and it derives its
candidate set from what actually enters each tsc program, so a package whose
declarations arrive only through another package's .d.ts is still seen.
Why overrides beats npm audit fix
tsup@8.5.1 declares esbuild: ^0.27.0, and the advisory covers
0.27.3 - 0.28.0 with 0.27.7 the last 0.27.x — so there is no upward escape
inside that range, and npm audit fix "resolves" it by silently downgrading
to 0.27.2 across three installs (~700 lines of lockfile churn for a low-severity
dev-only advisory; tried and reverted in #2058). The override forces one deduped
copy above the range instead.
Two costs: it puts tsup on an esbuild major it does not declare, so
npm run build — not npm audit — is the real gate on such a pin; and it is
invisible to the audit once clean, so drop it when tsup widens its range
rather than carrying it forever.