Skip to content

Commit 86fbdfc

Browse files
cliffhallclaude
andcommitted
refactor(web): address review — fix stale paths, move customHeaders, one-way arrows (#1776)
Responds to the @claude review on PR #1784: 1. Stale path references (fixed): update the four in-repo pointers left at pre-move paths — specification/v2_auth_mid_session.md (oauthResume, browserTabVisibility → lib/), and the two load-bearing sandbox security comments (sandbox_proxy.html, sandbox-controller.ts → src/utils/sandbox-csp). 2. lib/types/customHeaders (moved): it's pure (types + pure transforms), the rule's clearest counterexample. Moved lib/types/customHeaders.{ts,test.ts} → utils/ (no external importers; only its own test) and removed the undocumented lib/types/ subdir. Documented that utils/ is the home for pure shared domain types + their constructors — no separate types/ bucket. 3. One-way arrows (item 3): declare OAuthResumeAuthKind in utils/pendingReauth and re-export it from lib/oauthResume, so the only cross-directory arrow now points lib → utils. Codified that invariant in AGENTS.md. Wording nit: AGENTS.md + README now state diagnostic logging (console.warn/error) doesn't count as a side effect for the utils rule. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
1 parent 7323715 commit 86fbdfc

9 files changed

Lines changed: 18 additions & 8 deletions

File tree

‎AGENTS.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,9 +245,11 @@ gh project item-edit --project-id PVT_kwDOCt2Azc4BJVxt --id "$ITEM_ID" --field-i
245245

246246
The web client keeps two grab-bag directories under `clients/web/src`, split by a real (now codified) rule — **`utils` = functions that compute; `lib` = things that instantiate, adapt, or touch the environment.** If it does I/O or wraps a subsystem, it's `lib`; if it's a pure transform, it's `utils`.
247247

248-
- **`src/utils/`** — pure, side-effect-free functions. Input → output, no DOM/browser/storage I/O, no subsystem ownership. Trivially unit-testable with no mocks. (Anchors: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `sandbox-csp`.) A module that only imports **types** from `@inspector/core` (or elsewhere) is still pure and belongs here — a type-only import is not a subsystem dependency (e.g. `pendingReauth` is pure type declarations, `oauthUx`/`oauthFlow` re-export core copy/predicates).
248+
- **`src/utils/`** — pure, side-effect-free functions. Input → output, no DOM/browser/storage I/O, no subsystem ownership. Trivially unit-testable with no mocks. (Anchors: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `sandbox-csp`, `customHeaders`.) This includes modules that are pure **shared domain types plus their pure constructors/transforms** (`customHeaders` — `CustomHeader` + `headersToRecord`/`migrateFromLegacyAuth`); there is no separate `types/` bucket. **Diagnostic logging (`console.warn`/`console.error`) does not count as a side effect** for this rule — a validator that warns on bad input is still "pure" here (`sandbox-csp`, `jsonUtils`, `schemaUtils` all warn). A module that only imports **types** from `@inspector/core` (or elsewhere) is likewise pure and belongs here — a type-only import is not a subsystem dependency (e.g. `pendingReauth` is pure type declarations, `oauthUx`/`oauthFlow` re-export core copy/predicates).
249249
- **`src/lib/`** — infrastructure / integration / stateful adapters. Modules that instantiate or compose subsystems, wrap the `@inspector/core` **runtime** (not just its types), touch the DOM / `window` / `sessionStorage`, or otherwise produce side effects. (Anchors: `environmentFactory` composes `InspectorClientEnvironment`; `remoteOAuthStorage` is an adapter class over `core/auth`; `oauthResume` reads/writes `sessionStorage`; `browserTabVisibility` registers `visibilitychange` listeners; `clearServerOAuthState` drives the live `InspectorClient` / `OAuthStorage`; `downloadFile` triggers browser downloads.)
250250

251+
Cross-directory imports point **one way, `lib → utils`** (infra depends on pure helpers, never the reverse). Keep it that way: if a `utils/` module needs a type currently exported from a `lib/` module, declare the type in `utils/` and re-export it from `lib/` (as `pendingReauth` owns `OAuthResumeAuthKind` and `oauthResume` re-exports it), rather than importing "up" from `utils` into `lib`.
252+
251253
Nothing keys off the boundary (no path alias, no build/coverage glob) — it's a human-legible signal at import time, valuable in a codebase this test-heavy (the ≥90% per-file gate). When adding a module, place it by the rule; when it genuinely mixes both (e.g. `downloadFile` bundles DOM-side-effect helpers with a couple of pure ones), keep it whole on its dominant side (`lib`) rather than splitting hairs.
252254

253255
## React instructions

‎clients/web/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ Every screen and element has a `*.stories.tsx` (see [Storybook](#storybook)). St
5959

6060
Two grab-bag directories, split by one rule: **`utils` = functions that compute; `lib` = things that instantiate, adapt, or touch the environment.** If it does I/O or wraps a subsystem, it's `lib`; if it's a pure transform, it's `utils`.
6161

62-
- **`src/utils/`** — pure, side-effect-free functions (no DOM/`window`/`sessionStorage` I/O, no subsystem ownership), trivially unit-testable with no mocks. A type-only import from `@inspector/core` doesn't count as a subsystem dependency. Examples: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `deepLink`, `sandbox-csp`.
62+
- **`src/utils/`** — pure, side-effect-free functions (no DOM/`window`/`sessionStorage` I/O, no subsystem ownership), trivially unit-testable with no mocks. Diagnostic `console.warn`/`console.error` doesn't count as a side effect, and a type-only import from `@inspector/core` doesn't count as a subsystem dependency. Also home to pure shared domain types + their constructors (`customHeaders`) — no separate `types/` bucket. Examples: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `deepLink`, `sandbox-csp`, `customHeaders`.
6363
- **`src/lib/`** — infrastructure / stateful adapters: modules that compose subsystems, wrap the `@inspector/core` **runtime**, or produce side effects. Examples: `environmentFactory`, `remoteOAuthStorage`, `oauthResume` (sessionStorage), `browserTabVisibility` (DOM listeners), `clearServerOAuthState`, `downloadFile`.
6464

6565
Nothing keys off the boundary — it's a human-legible import-time signal. See [`AGENTS.md`](../../AGENTS.md) for the full rule.

‎clients/web/server/sandbox-controller.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ export function createSandboxController(
5353
// policy container: any fetch directive on this header would be inherited by
5454
// the inner app document and, since multiple CSPs intersect, would override
5555
// the per-app `connect-src`/`img-src` allowlists the host bakes into the
56-
// wrapped HTML (see src/lib/sandbox-csp.ts). The opaque-origin sandbox on
56+
// wrapped HTML (see src/utils/sandbox-csp.ts). The opaque-origin sandbox on
5757
// the inner frame is the structural boundary; `frame-ancestors` ensures the
5858
// proxy can only be embedded by the local inspector itself.
5959
const SANDBOX_PROXY_CSP =

‎clients/web/src/lib/oauthResume.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,13 @@ import {
3434
type OAuthRecoverySource,
3535
} from "@inspector/core/auth/oauthUx.js";
3636
import { OAUTH_PENDING_SERVER_KEY } from "../utils/oauthFlow.js";
37+
import type { OAuthResumeAuthKind } from "../utils/pendingReauth.js";
3738

3839
export const OAUTH_RESUME_KEY = "mcp-inspector:oauth-resume";
3940

4041
export { OAUTH_PENDING_SERVER_KEY };
4142

42-
export type OAuthResumeAuthKind = "step_up" | "reauth";
43+
export type { OAuthResumeAuthKind };
4344

4445
export interface OAuthResumeSnapshot {
4546
version: 1;
File renamed without changes.
File renamed without changes.

‎clients/web/src/utils/pendingReauth.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
import type { AuthChallenge } from "@inspector/core/auth/challenge.js";
22
import type { OAuthRecoverySource } from "@inspector/core/auth/oauthUx.js";
3-
import type { OAuthResumeAuthKind } from "../lib/oauthResume.js";
3+
4+
/**
5+
* Which interactive auth flow a resume/recovery represents. Declared here in the
6+
* pure `utils/` layer (rather than in `lib/oauthResume`) so the only arrow
7+
* between the two directories points `lib → utils`; `lib/oauthResume`
8+
* re-exports it for its existing consumers.
9+
*/
10+
export type OAuthResumeAuthKind = "step_up" | "reauth";
411

512
/** Origin of a deferred or resumed auth recovery flow (matches web `StepUpSource`). */
613
export type PendingReauthSource = OAuthRecoverySource;

‎clients/web/static/sandbox_proxy.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
Network/resource egress from the inner document is constrained by a
1919
Content-Security-Policy that the HOST builds and bakes into the
2020
delivered HTML before it reaches this proxy (see
21-
src/lib/sandbox-csp.ts). The proxy assigns that pre-wrapped document
21+
src/utils/sandbox-csp.ts). The proxy assigns that pre-wrapped document
2222
to `srcdoc` verbatim — it never parses or injects into the untrusted
2323
bytes — so the CSP `<meta>` is guaranteed to be the first `<head>`
2424
child of the inner document. -->

‎specification/v2_auth_mid_session.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ RemoteClientTransport StreamableHTTPClientTransport
139139
| EMA | `core/auth/ema/emaFlow.ts`, `core/auth/ema/resourceContext.ts` — see [v2_auth_ema.md](v2_auth_ema.md) |
140140
| Web remote backend | `core/mcp/remote/node/server.ts`, `remote-session.ts`, `core/mcp/node/authChallengeFetch.ts` |
141141
| Web remote client | `core/mcp/remote/remoteClientTransport.ts`, `core/mcp/inspectorClient.ts` |
142-
| Web app | `clients/web/src/App.tsx`, `utils/oauthResume.ts`, `utils/pendingReauth.ts`, `utils/browserTabVisibility.ts`, `components/groups/StepUpAuthModal/` |
142+
| Web app | `clients/web/src/App.tsx`, `lib/oauthResume.ts`, `utils/pendingReauth.ts`, `lib/browserTabVisibility.ts`, `components/groups/StepUpAuthModal/` |
143143
| TUI | `clients/tui/src/App.tsx`, `utils/tuiOAuth.ts` |
144144
| CLI | `clients/cli/src/cliOAuth.ts` |
145145
| Runner OAuth (TUI/CLI) | `core/auth/node/runner-interactive-oauth.ts`, `oauth-callback-server.ts` |
@@ -323,7 +323,7 @@ interface OAuthResumeSnapshot {
323323
}
324324
```
325325

326-
Key: `mcp-inspector:oauth-resume` in `sessionStorage` (`clients/web/src/utils/oauthResume.ts`).
326+
Key: `mcp-inspector:oauth-resume` in `sessionStorage` (`clients/web/src/lib/oauthResume.ts`).
327327

328328
**Callback flow** (`InspectorClient.resumeAfterOAuth()`):
329329

0 commit comments

Comments
 (0)