inspector/.claude/skills/local-dev/SKILL.md
cliffhall 3905ceef06 chore: address Copilot review round 15
- 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>
2026-08-29 04:24:48 -04:00

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 install at the root.
  • After a pull that changes a client's dependencies: re-run npm install at 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.alias in tsup.config.ts maps @inspector/core → the repo core/ directory, with noExternal: [/^@inspector\/core/] inlining it.
  • Web — two configs, because the client is two builds: clients/web/vite.config.ts for the browser app, and clients/web/tsup.runner.config.ts for 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:

  • express is test-only, so it is a devDependency.
  • vite and @vitejs/plugin-react look like build tooling but are root dependencies, because clients/web/server/start-vite-dev-server.ts imports 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.