@dimina-kit/devtools 0.3.2-dev.20260525152421 → 0.3.2-dev.20260610082053

package/dist/main/services/mcp/index.js

@@ -13,4 +13,7 @@
  */
 export { startMcpServer } from './server.js';
 export { getMcpStatus } from './status.js';
+// Native-host: let app.ts point the `simulator` CDP target at the active
+// render-host guest as the visible page changes.
+export { setNativeHost, setActiveBridgeId, setNativeOverviewProvider, getNativeOverviewProvider, } from './target-manager.js';
 //# sourceMappingURL=index.js.map

package/dist/main/services/mcp/server.d.ts

@@ -6,6 +6,6 @@
  * Tool registration lives in `./tool-registry` and `./tools/*`; this file
  * only wires up transports and lifecycle.
  */
-import { type Disposable } from '../../utils/disposable.js';
+import { type Disposable } from '@dimina-kit/electron-deck/main';
 export declare function startMcpServer(resolvedCdpPort: number, mcpPort: number): Disposable;
 //# sourceMappingURL=server.d.ts.map

package/dist/main/services/mcp/server.js

@@ -10,7 +10,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { createServer } from 'http';
 import { createRequire } from 'node:module';
-import { toDisposable } from '../../utils/disposable.js';
+import { toDisposable } from '@dimina-kit/electron-deck/main';
 import { connectTarget, setCdpPort } from './target-manager.js';
 import { recordMcpFailed, recordMcpStarted, recordMcpStopped } from './status.js';
 import { registerCommonTargetTools } from './tool-registry.js';

package/dist/main/services/mcp/target-manager.d.ts

@@ -27,6 +27,14 @@ export interface NetworkRequestEntry {
         receiveHeadersEnd: number;
     } | null;
 }
+export interface NativeOverview {
+    currentRoute: string | null;
+    pageStackDepth: number;
+    storageKeys: string[];
+    storageCount: number;
+    appDataKeys: string[];
+}
+export type NativeOverviewProvider = () => Promise<NativeOverview>;
 interface TargetState {
     client: any;
     connected: boolean;
@@ -35,6 +43,33 @@ interface TargetState {
     networkRequests: NetworkRequestEntry[];
 }
 export declare function setCdpPort(port: number): void;
+export declare function setNativeHost(enabled: boolean): void;
+/**
+ * Update the active-page bridgeId so the `simulator` target follows the
+ * currently visible render guest. No-op when unchanged. When native-host is
+ * on and the simulator target is already connected, fire-and-forget a
+ * reconnect so MCP re-points at the new active page.
+ */
+export declare function setActiveBridgeId(id: string | null): void;
+export declare function setNativeOverviewProvider(provider: NativeOverviewProvider | null): void;
+export declare function getNativeOverviewProvider(): NativeOverviewProvider | null;
+/**
+ * Resolve which CDP target the `simulator` MCP tools should drive.
+ *
+ * Default (non-native) path: the localhost:7788 simulator shell — identical
+ * to the original behavior; `activeBridgeId` is ignored.
+ *
+ * Native-host path: the active render-host <webview> guest
+ * (pageFrame.html?...bridgeId=<id>), preferring the guest matching
+ * `activeBridgeId`, then any pageFrame guest, then degrading to the shell.
+ */
+export declare function selectSimulatorTarget<T extends {
+    url?: string;
+    type?: string;
+}>(targets: T[], opts: {
+    nativeHost: boolean;
+    activeBridgeId: string | null;
+}): T | undefined;
 export declare function getTargetState(kind: TargetKind): TargetState;
 declare function listCdpTargets(): Promise<CDP.Target[]>;
 export { listCdpTargets as listTargets };

package/dist/main/services/mcp/target-manager.js

@@ -12,9 +12,20 @@
 import CDP from 'chrome-remote-interface';
 import { DEFAULT_CDP_PORT } from '../../../shared/constants.js';
 const SIMULATOR_URL_PATTERN = 'localhost:7788';
+// Native-host: the real mini-app page runs in a nested render-host <webview>
+// guest whose CDP target URL carries the render frame + the page's bridgeId.
+const RENDER_GUEST_PATTERN = 'pageFrame.html';
 const MAX_BUFFER = 500;
 const RECONNECT_INTERVAL_MS = 3000;
 let cdpPort = DEFAULT_CDP_PORT;
+// Native-host mode: the simulator target is the active render-host <webview>
+// guest (pageFrame.html?...bridgeId=<id>) rather than the localhost:7788 shell.
+let nativeHostMode = false;
+// The visible page's bridgeId, pushed from the bridge-router render events.
+// `selectSimulatorTarget` prefers the guest matching this id so MCP follows
+// the active page across navigation/tab switches.
+let activeBridgeId = null;
+let nativeOverviewProvider = null;
 const targets = {
     simulator: { client: null, connected: false, timer: null, consoleLogs: [], networkRequests: [] },
     workbench: { client: null, connected: false, timer: null, consoleLogs: [], networkRequests: [] },
@@ -22,6 +33,57 @@ const targets = {
 export function setCdpPort(port) {
     cdpPort = port;
 }
+export function setNativeHost(enabled) {
+    nativeHostMode = enabled;
+}
+/**
+ * Update the active-page bridgeId so the `simulator` target follows the
+ * currently visible render guest. No-op when unchanged. When native-host is
+ * on and the simulator target is already connected, fire-and-forget a
+ * reconnect so MCP re-points at the new active page.
+ */
+export function setActiveBridgeId(id) {
+    if (id === activeBridgeId)
+        return;
+    activeBridgeId = id;
+    if (nativeHostMode && targets.simulator.connected) {
+        void connectTarget('simulator');
+    }
+}
+export function setNativeOverviewProvider(provider) {
+    nativeOverviewProvider = provider;
+}
+export function getNativeOverviewProvider() {
+    return nativeOverviewProvider;
+}
+/**
+ * Resolve which CDP target the `simulator` MCP tools should drive.
+ *
+ * Default (non-native) path: the localhost:7788 simulator shell — identical
+ * to the original behavior; `activeBridgeId` is ignored.
+ *
+ * Native-host path: the active render-host <webview> guest
+ * (pageFrame.html?...bridgeId=<id>), preferring the guest matching
+ * `activeBridgeId`, then any pageFrame guest, then degrading to the shell.
+ */
+export function selectSimulatorTarget(targets, opts) {
+    if (!opts.nativeHost) {
+        return targets.find((t) => t.url?.includes(SIMULATOR_URL_PATTERN));
+    }
+    // 1) Active-bridge guest takes priority over list order.
+    if (opts.activeBridgeId !== null) {
+        const bridgeMatch = `bridgeId=${opts.activeBridgeId}`;
+        const active = targets.find((t) => t.url?.includes(RENDER_GUEST_PATTERN) && t.url.includes(bridgeMatch));
+        if (active)
+            return active;
+    }
+    // 2) Any render guest (no active match / no active bridge).
+    const anyGuest = targets.find((t) => t.url?.includes(RENDER_GUEST_PATTERN));
+    if (anyGuest)
+        return anyGuest;
+    // 3) Degrade to the localhost:7788 shell when no render guest exists yet.
+    return targets.find((t) => t.url?.includes(SIMULATOR_URL_PATTERN));
+}
 export function getTargetState(kind) {
     return targets[kind];
 }
@@ -36,7 +98,7 @@ async function listCdpTargets() {
 export { listCdpTargets as listTargets };
 function findTarget(allTargets, kind) {
     if (kind === 'simulator') {
-        return allTargets.find((t) => t.url?.includes(SIMULATOR_URL_PATTERN));
+        return selectSimulatorTarget(allTargets, { nativeHost: nativeHostMode, activeBridgeId });
     }
     // workbench main window: page target whose URL contains index.html (renderer)
     return allTargets.find((t) => t.type === 'page' && t.url?.includes('entries/main/index.html') && !t.url?.includes(SIMULATOR_URL_PATTERN));

package/dist/main/services/mcp/tools/context-tools.js

@@ -10,7 +10,7 @@
  * reliably than they read resources, and this keeps the surface consistent
  * with sibling `*_get_page_info` / `*_connection_status` tools.
  */
-import { getClient, getTargetState } from '../target-manager.js';
+import { getClient, getNativeOverviewProvider, getTargetState, } from '../target-manager.js';
 // Truncation thresholds: keep the overview compact — orientation, not data dump.
 const MAX_KEYS = 50;
 const MAX_HINT_TEXT = 200;
@@ -160,6 +160,20 @@ export function registerContextTools(server) {
                 isError: true,
             };
         }
+        const nativeOverviewProvider = getNativeOverviewProvider();
+        if (nativeOverviewProvider) {
+            try {
+                const nativeOverview = await nativeOverviewProvider();
+                probe.pageStackDepth = nativeOverview.pageStackDepth;
+                probe.currentRoute = nativeOverview.currentRoute;
+                probe.storageKeys = nativeOverview.storageKeys;
+                probe.storageCount = nativeOverview.storageCount;
+                probe.appDataKeys = nativeOverview.appDataKeys;
+            }
+            catch {
+                // Best effort: keep the CDP probe values if the native provider fails.
+            }
+        }
         if (!probe.simulatorDataPresent)
             hints.push('simulator bridge not ready (window.__simulatorData missing)');
         else if (!probe.bridgeReady)

package/dist/main/services/module.d.ts

@@ -1,4 +1,4 @@
-import type { Disposable } from '../utils/disposable.js';
+import type { Disposable } from '@dimina-kit/electron-deck/main';
 import type { WorkbenchContext } from './workbench-context.js';
 /**
  * A composable unit of workbench functionality.

package/dist/main/services/network-forward/index.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Native-host network forwarder.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ * The right-panel "Network" view is the embedded Chrome DevTools front-end. In
+ * native-host that front-end is attached to the SERVICE HOST webContents (see
+ * view-manager `pointNativeDevtoolsAtServiceWc`), so its Network tab only ever
+ * shows the service host's own network activity.
+ *
+ * But the mini-app's `wx.request` / `dd.request` / `downloadFile` / `uploadFile`
+ * do NOT run in the service host. bridge-router forwards every `invokeAPI` that
+ * isn't registered host-side to the SIMULATOR WebContentsView via `E.API_CALL`,
+ * and DeviceShell runs the handler there (`device-shell.tsx` → `runApiAsync` →
+ * `direct-request.ts`/`simulator-api-network.ts`, which call `fetch()` /
+ * `XMLHttpRequest`). Those requests therefore go through the simulator WCV's
+ * network stack — a DIFFERENT webContents than the one the DevTools front-end
+ * inspects — so they were invisible in the Network panel after the native-host
+ * refactor. THAT is the regression this service closes.
+ *
+ * ── How it surfaces them (primary sink: native Network tab) ─────────────────
+ * We attach the CDP `webContents.debugger` to the simulator WCV, `Network.enable`,
+ * and listen for the Network.* lifecycle events. Rather than reformat them, we
+ * forward the RAW CDP messages straight into the WebContents that HOSTS the
+ * DevTools front-end (the right-panel `simulatorView.webContents`), via
+ * `window.DevToolsAPI.dispatchMessage(json)`. The bundled Chrome DevTools then
+ * renders them natively in its own Network tab — same protocol path it would
+ * use for its own inspected target.
+ *
+ * Because the front-end is inspecting the service host (a DIFFERENT target than
+ * the simulator the events came from), the simulator's `requestId`s could
+ * collide with the service host's own. We therefore rewrite every requestId
+ * into a namespaced virtual id (`dimina:sim:<epoch>:<rawId>`) before dispatch,
+ * keeping a raw→virtual map so redirects / extra-info / completion events on the
+ * same request stay correlated. We inject on the MAIN session (no `sessionId`),
+ * i.e. the events appear as activity on the currently-inspected target. This is
+ * the one-shot approach the Codex review settled on; child-target routing
+ * (`Target.attachedToTarget` + hooking outbound CDP) is explicitly deferred.
+ *
+ * ── Fallback sink (console line) ────────────────────────────────────────────
+ * If the DevTools host wc is unavailable, or `window.DevToolsAPI.dispatchMessage`
+ * never appears (front-end not bootstrapped), or a dispatch throws, we degrade
+ * to the legacy behaviour: re-emit each COMPLETED request as one `[网络]`-prefixed
+ * line into the SERVICE HOST's own console (where the DevTools is attached). That
+ * keeps the requests visible in the panel the user already watches even when the
+ * protocol path can't be used. The fallback never duplicates the native path —
+ * it is chosen per completed-request, only when the native dispatch is known
+ * unusable.
+ *
+ * ── Coverage (one-shot scope) ───────────────────────────────────────────────
+ *  ✅ Forwarded to the native Network tab: requestWillBeSent, responseReceived,
+ *     loadingFinished, loadingFailed (+ requestWillBeSentExtraInfo /
+ *     responseReceivedExtraInfo when present, for accurate headers/status).
+ *  ⏳ TODO (二期): `dataReceived` per-chunk forwarding (skipped to avoid an
+ *     executeJavaScript per chunk), and response body / preview (needs hooking
+ *     `InspectorFrontendHost.sendMessageToBackend` + a prefetched body cache so
+ *     the front-end's `Network.getResponseBody` round-trip resolves).
+ *  ⚠️ NOT captured here: requests issued from inside a render-host `<webview>`
+ *     guest (page-level resource loads / page `fetch`). The safe-area service
+ *     already owns each guest's `wc.debugger`, and `debugger.attach` is
+ *     single-owner — bringing those in needs a shared CDP broker. `source:'render'`
+ *     is reserved for when that's added (later).
+ *  ⚠️ NOT observable by any `webContents.debugger`: a request a host module issues
+ *     directly from the MAIN process. Those need an explicit `report()` call
+ *     (exposed below; it uses the console fallback path).
+ */
+import type { WebContents } from 'electron';
+import { type ConnectionRegistry, type Disposable } from '@dimina-kit/electron-deck/main';
+/** Which layer a captured request came from (tags the fallback log line). */
+export type NetworkSource = 'service' | 'render';
+/** A normalized completed network request, used only by the console fallback. */
+export interface NetworkRequestRecord {
+    source: NetworkSource;
+    url: string;
+    method: string;
+    /** HTTP status, or 0 when the request failed before a response. */
+    status: number;
+    /** Failure text for `loadingFailed`, else undefined. */
+    errorText?: string;
+}
+/**
+ * Resolvers the forwarder consults each time it needs a target wc. Both are
+ * re-read on every use so a pre-warm-pool swap (service) or a DevTools-host
+ * re-create (devtools) is tolerated without re-wiring.
+ */
+export interface NetworkForwarderBridge {
+    /** The SERVICE HOST wc — fallback console sink target. */
+    getServiceWc(appId?: string): WebContents | null;
+    /**
+     * The wc hosting the right-panel Chrome DevTools FRONT-END (the one we inject
+     * `window.DevToolsAPI.dispatchMessage` into). Set by the ViewManager via
+     * `setDevtoolsHost`. Null until the DevTools host view exists.
+     */
+    getDevtoolsWc?(): WebContents | null;
+    /**
+     * Optional connection-layer registry (`@dimina-kit/electron-deck/main`). When
+     * present, per-webContents teardowns route through `acquire(wc).own(d)` so the
+     * Connection disposes them deterministically on wc destroy / reset (replacing
+     * the bespoke `wc.once('destroyed', cleanup)`). Omitted → the legacy
+     * `once('destroyed')` fallback is used, so existing callers compile unchanged.
+     */
+    connections?: ConnectionRegistry;
+}
+export interface NetworkForwarder extends Disposable {
+    /**
+     * Attach the CDP debugger to the simulator WCV and start forwarding its
+     * Network events. Idempotent for the same wc; re-pointing to a new wc (a
+     * relaunch / pool swap) detaches the previous one first. No-op if the wc is
+     * destroyed or its debugger is already claimed (DevTools / another client).
+     */
+    attachSimulator(wc: WebContents): void;
+    /** Detach from the current simulator WCV (without disposing the forwarder). */
+    detachSimulator(): void;
+    /**
+     * Point the forwarder at the WebContents hosting the DevTools FRONT-END (the
+     * primary, native-Network-tab sink). Pass null when that view is torn down so
+     * we fall back to the console line. Re-callable across DevTools re-creates.
+     */
+    setDevtoolsHost(wc: WebContents | null): void;
+    /**
+     * Manually surface a request that no `webContents.debugger` can observe
+     * (e.g. a main-process direct send). Uses the console fallback sink.
+     */
+    report(record: NetworkRequestRecord): void;
+}
+/**
+ * CDP events whose `params.requestId` we rewrite into the virtual namespace.
+ * Anything carrying a requestId must be namespaced consistently — even methods
+ * we don't (yet) forward — so the raw→virtual map stays coherent if forwarding
+ * is widened later. `requestServedFromCache` and `resourceChangedPriority` are
+ * included for that reason (MINOR: rewrite-only today, not forwarded).
+ */
+export declare const REWRITE_REQUEST_ID_METHODS: ReadonlySet<string>;
+/** The Network.* methods this one-shot pass forwards to the front-end. */
+export declare const FORWARDED_METHODS: ReadonlySet<string>;
+/**
+ * Bounded, TTL'd raw→virtual requestId map with an active/retired split.
+ *
+ * An ACTIVE request (seen `requestWillBeSent`/ExtraInfo, not yet terminal) must
+ * NEVER lose its mapping — otherwise a later `responseReceived`/`loadingFinished`
+ * would mint a fresh virtual id and the front-end would see an orphaned event.
+ * So active entries are exempt from both TTL and the LRU cap.
+ *
+ * Only once a request goes terminal (`loadingFinished`/`loadingFailed`) is it
+ * RETIRED: its mapping is kept a while longer so genuinely-late events (an
+ * extra-info after completion) still correlate, but it now ages out by TTL and
+ * by an LRU cap so a long session never grows unbounded. Eviction only ever
+ * touches the retired pool.
+ */
+export declare class RequestIdNamespace {
+    private readonly epoch;
+    private readonly ttlMs;
+    private readonly max;
+    private readonly now;
+    private readonly map;
+    private seq;
+    constructor(epoch: string, ttlMs?: number, max?: number, now?: () => number);
+    /**
+     * Resolve (lazily creating) the virtual id for a raw id. Lazy creation lets an
+     * ExtraInfo event that arrives BEFORE its `requestWillBeSent` still get a
+     * stable id that the later events reuse — a redirect chain reuses the same raw
+     * id and therefore the same virtual id (we never mint a new one per redirect).
+     *
+     * A freshly-resolved (or any non-retired) entry is ACTIVE and thus immune to
+     * eviction. We only TTL-expire entries that have already been retired; an
+     * active entry never "expires" no matter how long it stays in flight.
+     */
+    resolve(rawId: string): string;
+    /**
+     * Mark a request terminal: it leaves the active set and enters the retired
+     * pool with a fresh TTL, where it becomes eligible for TTL/LRU eviction.
+     */
+    retire(rawId: string): void;
+    private evict;
+    /** Total entries (active + retired). */
+    get size(): number;
+    /** Entries still in flight (resolved, not yet retired). */
+    get activeSize(): number;
+}
+/**
+ * Rewrite a single CDP message's `requestId` into the namespace, returning a new
+ * `{ method, params }` (never mutating the input). Returns the message unchanged
+ * when the method carries no requestId we track or params is malformed. Pure
+ * aside from the namespace map it threads through.
+ */
+export declare function rewriteRequestId(method: string, params: unknown, ns: RequestIdNamespace): {
+    method: string;
+    params: unknown;
+};
+export declare function createNetworkForwarder(bridge: NetworkForwarderBridge): NetworkForwarder;
+//# sourceMappingURL=index.d.ts.map