Skip to content

Commit fb092d3

Browse files
authored
refactor(mcp): split devframe.ts into per-area modules (#496)
Fixes #373
1 parent d157699 commit fb092d3

21 files changed

Lines changed: 3714 additions & 2775 deletions

‎.claude/skills/devtools-docs/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ Rules:
130130
| Page | Source of truth |
131131
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
132132
| inspectors/\* | `app/src/pages/*.ts` (the tab) and `packages/devtools/src/*` (collectors, actions) |
133-
| agents/\* | `packages/devtools/src/devframe.ts`, `rpc/*.ts`, `rpc/analog-register.ts`, Devframe built-ins |
133+
| agents/\* | `packages/devtools/src/devframe.ts`, `devframe-*.ts`, `rpc/*.ts`, `rpc/analog-register.ts`, Devframe built-ins |
134134
| getting-started/\* | `packages/devtools/package.json` exports, `hub.ts`, `vite.ts`, `config.ts`, `overlay.ts`, `popup.ts`, demos |
135135
| security | `hub.ts`, `vite.ts`, `forms-privacy.ts`, `forms-actions.ts`, router and Analog redaction |
136136
| contributing/\* | root `package.json`, `nx.json`, `project.json` files, `.github/workflows`, `extension/` |

‎.claude/skills/devtools-inspector/SKILL.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Every inspector follows the same path:
1010
```
1111
app page (overlay.ts + <area>-collector.ts)
1212
-> rpc.call('push-<area>', { pageId, ... })
13-
-> devframe.ts: per-page Map, shared state '<area>', expiry, forget-<area>-page
13+
-> devframe.ts and devframe-<area>.ts: per-page Map, shared state '<area>', expiry, forget-<area>-page
1414
-> panel page (app/src/pages/<area>.ts) via rpc.sharedState('<area>')
1515
-> agent tools (ctx.agent.registerTool) and MCP resources
1616
```
@@ -32,7 +32,7 @@ Read `docs/contributing/coding-standards.md` ("Reading data from the page") befo
3232

3333
## Server side (`devframe.ts`, `rpc/`)
3434

35-
- `devframe.ts` wires the setup. A new inspector goes in its own `rpc/<area>-register.ts` (see `rpc/errors-register.ts`), and agent tools of an existing area live in `devframe-<area>-tools.ts`, which take the setup values they read as an `env` object typed through `devframe-env.ts`. Keep `devframe.ts` under the line ratchet of `pnpm lint`.
35+
- `devframe.ts` wires the setup. A new inspector goes in its own `rpc/<area>-register.ts` (see `rpc/errors-register.ts`). Existing inspectors follow one of two layouts: the ones registered from `devframe-inspectors.ts` (errors, perf, build and the like) keep their state, RPC functions and tools in their `rpc/<area>-register.ts`; the older areas keep their state and RPC functions in `devframe-<area>.ts`. Change an inspector in the module it already lives in. An older area's agent tools are in that module or in a separate `devframe-*-tools.ts` module. These modules take the setup values they read as an `env` object typed through `devframe-env.ts`. The page registry (owners, heartbeats, lease) is `devframe-pages.ts` and the registrars are `devframe-registrars.ts`. Keep `devframe.ts` under the line ratchet of `pnpm lint`.
3636

3737
- Keep a `Map<pageId, report>` with `reportedAt`, drop pages older than `ttl(pageId)` (from `visibility.ttl()`, so a page with a current heartbeat never expires) in the shared expiry interval, and write the combined value into the shared state.
3838
- Page actions that the panel triggers (restore, highlight, run) go panel -> `request-<area>-action` -> broadcast `<area>-action` to the page -> `<area>-action-result`, keyed by `requestId`, with a timeout.
@@ -48,7 +48,7 @@ Read `docs/contributing/coding-standards.md` ("Reading data from the page") befo
4848

4949
- Describe what the tool returns, where the data comes from and what an empty answer means. Answer in markdown.
5050
- Give each new tool or resource one entry in `AGENT_ENTRIES` (`packages/devtools/src/config.ts`): its inspector, safety tier, the `actions` it writes for and whether it needs a page. `AGENT_INSPECTOR`, `AGENT_SAFETY`, `ACTION_TOOLS`, `PAGE_AGENT_ENTRIES` and the tags derive from it. `packages/devtools/src/__tests__/agent-metadata.test.ts` fails on a registered tool without an entry; update `packages/devtools/src/__tests__/fixtures/agent-metadata-derived.json` with it.
51-
- Update tool descriptions (in `devframe.ts`, `devframe-<area>-tools.ts` or the inspector's register module) when data shapes change, and the tool list on the docs site (apps/docs/src/content/agents/tools.md). Use the `devtools-docs` skill for that edit.
51+
- Update tool descriptions (in `devframe.ts`, `devframe-<area>.ts`, `devframe-<area>-tools.ts` or the inspector's register module) when data shapes change, and the tool list on the docs site (apps/docs/src/content/agents/tools.md). Use the `devtools-docs` skill for that edit.
5252

5353
## Tests
5454

‎apps/docs/src/content/contributing/development.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ app/ # Devtools UI SPA (Angular + Vite)
6464
packages/
6565
devtools/ # Publishable npm package
6666
src/devframe.ts # defineDevframe(): the tool definition
67+
src/devframe-*.ts # Its parts: shared types, registrars, the page registry, and the state, RPC functions and agent tools of the areas kept here (other inspectors live in `src/rpc/<area>-register.ts`)
6768
src/overlay.ts # Client script running in the user's page (the overlay-manual entry)
6869
src/overlay-auto.ts # The overlay entry: starts the overlay and the floating button on import
6970
src/rpc/ # Node-side RPC functions and agent tools
@@ -269,7 +270,7 @@ If a code change needs no docs change, add the `no-docs` label to the pull reque
269270
### Add an RPC function
270271

271272
1. Create the function in `packages/devtools/src/rpc/`.
272-
2. Register it in `packages/devtools/src/devframe.ts`.
273+
2. Register it in `packages/devtools/src/devframe.ts`, or in the `devframe-<area>.ts` module of its inspector.
273274
3. Map it to its inspector in `RPC_INSPECTOR` in `packages/devtools/src/config.ts`, so turning the inspector off removes it.
274275
4. Call it from the UI in `app/src/pages/`.
275276

‎apps/docs/src/content/contributing/writing-docs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -224,7 +224,7 @@ The docs describe what the code does today. Before you write a claim, find it in
224224
| Page | Source of truth |
225225
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
226226
| Inspector pages | The tab in `app/src/pages/` and its collector in `packages/devtools/src/` |
227-
| Agent tools and resources | `packages/devtools/src/devframe.ts`, `rpc/*.ts` and `rpc/analog-register.ts` |
227+
| Agent tools and resources | `packages/devtools/src/devframe.ts`, `devframe-*.ts`, `rpc/*.ts` and `rpc/analog-register.ts` |
228228
| Setup pages | `packages/devtools/package.json` exports, `hub.ts`, `vite.ts`, `config.ts`, `overlay.ts`, `popup.ts` and the demos |
229229
| Security | `hub.ts`, `vite.ts` and the redaction code, such as `forms-privacy.ts` |
230230
| Contributing | Root `package.json` scripts, `nx.json`, `project.json` files and `.github/workflows` |

‎docs/CONTEXT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ A library's own view in the panel and its own agent tools, through the public pl
5353
_Avoid_: extension (the Chrome extension), add-on, inspector
5454

5555
**Devframe**:
56-
The framework the devtools are built on (`devframe`). One definition, `packages/devtools/src/devframe.ts` (with the `devframe-*-tools.ts` and `rpc/*-register.ts` modules it calls), declares the RPC functions, shared state and agent tools, and Devframe serves it as the embedded panel, the standalone CLI, the static report and the MCP server.
56+
The framework the devtools are built on (`devframe`). One definition, `packages/devtools/src/devframe.ts` (with the `devframe-*.ts` and `rpc/*-register.ts` modules it calls), declares the RPC functions, shared state and agent tools, and Devframe serves it as the embedded panel, the standalone CLI, the static report and the MCP server.
5757
_Avoid_: framework, runtime, backend
5858

5959
**Hub**:

‎lint-baseline.json‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -231,8 +231,7 @@
231231
"packages/devtools/src/console-tap.ts": {
232232
"unicorn(no-useless-spread)": 1
233233
},
234-
"packages/devtools/src/devframe.ts": {
235-
"pangular(max-lines)": 3236,
234+
"packages/devtools/src/devframe-components.ts": {
236235
"unicorn(no-useless-spread)": 1
237236
},
238237
"packages/devtools/src/dom-diff.ts": {
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// The Capacitor inspector on the devframe server (`devframe.ts`): the
2+
// `capacitor` shared state with patches, and its push and forget.
3+
4+
import { createSharedState } from 'devframe/utils/shared-state';
5+
import type { ResolvedPangularConfig } from './config.ts';
6+
import {
7+
mergeCapacitorReport,
8+
patchCapacitorState,
9+
syncCapacitorState,
10+
toCapacitorReport,
11+
type CapacitorPage,
12+
type CapacitorState,
13+
} from './rpc/capacitor-tools.ts';
14+
import { trackPageSessions } from './rpc/page-sessions.ts';
15+
import type { DevframeNodeContext, Owns, PangularScope, Register } from './devframe-env.ts';
16+
17+
export async function registerCapacitor(env: {
18+
ctx: DevframeNodeContext;
19+
my: PangularScope;
20+
config: ResolvedPangularConfig;
21+
register: Register;
22+
owns: Owns;
23+
mayForget: Owns;
24+
}) {
25+
const { ctx, my, config, register, owns, mayForget } = env;
26+
const limits = config.limits;
27+
const capacitorPages = new Map<string, CapacitorPage>();
28+
// With patches on, a push sends the panel what changed, not every page:
29+
// devframe's own shared states send the whole value on each change.
30+
const capacitorShared = await my.rpc.sharedState('capacitor', {
31+
sharedState: createSharedState<CapacitorState>({
32+
initialValue: { pages: {} },
33+
enablePatches: true,
34+
}),
35+
});
36+
const applyCapacitor = () =>
37+
capacitorShared.mutate((draft) => syncCapacitorState(draft, capacitorPages));
38+
const capacitorSessions = trackPageSessions(ctx.rpc, (pageIds) => {
39+
let removed = false;
40+
for (const pageId of pageIds) removed = capacitorPages.delete(pageId) || removed;
41+
if (removed) applyCapacitor();
42+
});
43+
44+
register({
45+
name: 'push-capacitor',
46+
type: 'action',
47+
jsonSerializable: true,
48+
handler: (message: unknown) => {
49+
const report = toCapacitorReport(message);
50+
if (!report || !owns(report.pageId)) return { known: true };
51+
capacitorSessions.bind(report.pageId);
52+
const answer = mergeCapacitorReport(capacitorPages, report, limits.capacitorCalls);
53+
if (answer.known) {
54+
capacitorShared.mutate((draft) => patchCapacitorState(draft, capacitorPages, report));
55+
}
56+
return answer;
57+
},
58+
});
59+
60+
register({
61+
name: 'forget-capacitor-page',
62+
type: 'action',
63+
jsonSerializable: true,
64+
handler: (pageId: string) => {
65+
if (!mayForget(pageId)) return;
66+
capacitorSessions.unbind(pageId);
67+
if (capacitorPages.delete(pageId)) applyCapacitor();
68+
},
69+
});
70+
71+
return { capacitorPages, capacitorShared, applyCapacitor };
72+
}

0 commit comments

Comments
 (0)