@buoy-gg/mcp 7.0.21 → 7.0.23

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   SyncClient,
   createMcpServer,
   runInit
-} from "./chunk-JQ5GZ4LG.mjs";
+} from "./chunk-SGRL6UKT.mjs";
 
 // src/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/index.d.mts

@@ -24,6 +24,14 @@ interface DeviceInfo {
     isConnected: boolean;
     /** Whether the connected app reported an active Buoy Pro license. */
     isPro: boolean;
+    /**
+     * The app's access tier. Apps older than the tier split report only `isPro`,
+     * which maps exactly — a key could only ever grant Pro back then.
+     *
+     * Surfaced so `list_devices` can say WHY the MCP is blocked: "signed in on
+     * the free tier" and "no account at all" are different problems.
+     */
+    tier: "anonymous" | "free" | "pro";
     tools: ToolCapability[];
 }
 /** How the client obtained its broker connection. */
@@ -57,11 +65,31 @@ declare class SyncClient {
     private pendingActions;
     /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
     private snapshotWaiters;
+    /** When each cached snapshot arrived, keyed by snapKey (staleness reporting). */
+    private snapshotAt;
+    /** Liveness per device — see {@link noteTimeout}. */
+    private health;
+    /** Dev-server origin per device — see {@link noteDevServerOrigin}. */
+    private devServerOrigins;
+    /** Devices whose origin probe already ran (a production bundle has none). */
+    private originProbed;
+    /** Last time each device appeared in the broker's device list. */
+    private lastSeen;
     constructor(opts?: SyncClientOptions);
     private readonly autoSpawn;
     /** Connect to a running broker, or spawn one in-process, then handshake. */
     start(): Promise<BrokerMode>;
     private connectSocket;
+    /**
+     * Drop everything remembered about devices that have been gone a while.
+     *
+     * Deliberately NOT on disconnect: a crashed app often drops off the broker,
+     * and its cached console snapshot is the crash evidence — throwing that away
+     * the instant it disconnects would delete the answer. But device ids change
+     * with every simulator erase and fresh dev client, and each one can hold
+     * multi-MB snapshots, so a long-lived server has to forget eventually.
+     */
+    private pruneStaleDevices;
     /** Disconnect and tear down a spawned broker, if any. */
     stop(): Promise<void>;
     /** All devices the broker knows about, merged with their advertised tools. */
@@ -91,6 +119,61 @@ declare class SyncClient {
      * is blocked.
      */
     requireProDevice(deviceId?: string): string;
+    private healthOf;
+    /** The device answered — it's alive. */
+    private noteOk;
+    /**
+     * The device didn't answer. A crashed app never answers again, so after the
+     * first miss we stop paying the full timeout on every subsequent call.
+     */
+    private noteTimeout;
+    /** True once a device has missed a call and hasn't answered since. */
+    isUnresponsive(deviceId: string): boolean;
+    /**
+     * Full timeout normally; a short one for a device already not answering.
+     *
+     * With one escape hatch: every RECOVERY_PROBE_MS a flagged device gets the
+     * full budget again. Without it the flag is self-sustaining — a device whose
+     * work legitimately takes longer than the short budget (a big snapshot, a
+     * slow simulator) can never answer, so it can never clear the flag, and every
+     * later reply is a confident "most likely CRASHED" about a healthy app.
+     */
+    private timeoutFor;
+    /**
+     * Plain-language diagnosis for a device that isn't answering, including the
+     * app's last words if the console tool got a crash flush out in time.
+     *
+     * A silent timeout is the worst possible answer here: the app is on a redbox,
+     * the reason is already captured, and without this the caller reads "timed
+     * out" and keeps retrying the same dead device.
+     */
+    unresponsiveNote(deviceId: string): string;
+    /**
+     * The newest error line the console tool synced for this device, if any.
+     * Reads the cached console snapshot rather than the device (which, by the
+     * time this matters, is not answering).
+     */
+    private lastFatalFor;
+    /** Age of the cached snapshot for a tool, in ms (null = never received). */
+    snapshotAgeMs(toolId: string, deviceId: string): number | null;
+    /**
+     * Remember where a device's bundle came from, reported by core's `app`
+     * adapter while the app is healthy. It is the only way to reload an app that
+     * has crashed: the in-app reload needs the React tree that the crash
+     * destroyed, but the dev server's reload is handled natively.
+     */
+    noteDevServerOrigin(deviceId: string, origin: unknown): void;
+    /**
+     * Ask a freshly-announced device where its bundle came from, once.
+     *
+     * Deliberately eager: this is the piece of information that can ONLY be
+     * collected while the app is healthy, and is only ever needed after it has
+     * stopped answering. One cheap round-trip per device buys the ability to
+     * recover a crashed app instead of telling the caller to go do it by hand.
+     */
+    private learnDevServerOrigin;
+    /** The dev-server origin last reported by this device, if any. */
+    devServerOrigin(deviceId: string): string | null;
     /**
      * Keep the device RECORDING this tool, without asking it to stream.
      *
@@ -135,10 +218,14 @@ declare class SyncClient {
      */
     getSnapshot(toolId: string, deviceId?: string, opts?: {
         timeoutMs?: number;
+        silent?: boolean;
     }): Promise<{
         deviceId: string;
         payload: unknown;
+        stale?: string;
     }>;
+    /** Header line for data served from cache because the device went quiet. */
+    private staleNote;
     private waitForSnapshot;
     /**
      * Invoke a remote action on a device and await its result. Pass deviceId to
@@ -146,14 +233,10 @@ declare class SyncClient {
      */
     callAction(toolId: string, action: string, params?: unknown, deviceId?: string, opts?: {
         timeoutMs?: number;
+        silent?: boolean;
     }): Promise<unknown>;
 }
 
-/**
- * Build the Buoy MCP server and register all tools against a connected
- * {@link SyncClient}. Tool packs (perf-monitor, etc.) are layered on top of the
- * generic core here.
- */
 declare function createMcpServer(sync: SyncClient): McpServer;
 
 /**
@@ -351,6 +434,12 @@ interface AutomationConfig {
     runsPerCase?: number;
     coolDownMs?: number;
     discardWarmupRuns?: number;
+    /**
+     * Run a throwaway case at the front of the batch and drop it from the
+     * results, so the batch's cold start doesn't land on real data. Default true.
+     * See the perf-monitor AutomationConfig for the reproduction.
+     */
+    discardWarmupCase?: boolean;
     shuffleCases?: boolean;
     /** Capture per-component render counts/durations each run. Default true. */
     captureRenders?: boolean;
@@ -378,13 +467,17 @@ interface IndexEntry {
     caseId?: string;
     runIndex?: number;
     isMedianRun?: boolean;
+    /** Thermal state at run start; a throttled run reads cheap AND janky. */
+    thermalState?: "nominal" | "fair" | "serious" | "critical";
     /** Render-capture mirror (absent when capture was unavailable/disabled). */
     renderCommits?: number;
     renderTotalMs?: number;
+    renderWasted?: number;
     topRenderers?: {
         name: string;
         renders: number;
         totalMs: number;
+        cause?: string;
     }[];
 }
 /** Per-metric min/max/avg/p95 channel. */
@@ -406,12 +499,40 @@ interface BenchmarkReportStats {
     uiJankFrames: number;
     deviceMaxRefreshRate: number;
 }
-
 /**
- * Pure helpers for the perf-monitor pack: build an AutomationConfig from
- * MCP-friendly input, estimate batch duration, and rank a finished batch's
- * results into a winner + comparison table. No network/sync — unit-testable.
+ * Why components rendered, counted over a run.
+ *
+ * `propsUnstable` is the actionable one: props changed by IDENTITY only —
+ * a fresh arrow or object literal handed down every render — while every
+ * value stayed equal. Reporting that as plain "props" sends you into the
+ * child, when the fix is always in the parent.
  */
+interface RenderCauseCounts {
+    mount?: number;
+    props?: number;
+    propsUnstable?: number;
+    hooks?: number;
+    parent?: number;
+}
+interface RenderCapture {
+    totalCommits: number;
+    totalRenders: number;
+    capturedDurations: boolean;
+    totalRenderMs?: number;
+    /** Parent cascades + identity-only prop churn: the removable share. */
+    wastedRenders?: number;
+    causes?: RenderCauseCounts;
+    topComponents: {
+        name: string;
+        renders: number;
+        totalMs: number;
+        maxMs: number;
+        avgMs: number;
+        causes?: RenderCauseCounts;
+        changedProps?: string[];
+        parentName?: string;
+    }[];
+}
 
 interface BuildConfigInput {
     targetRoute: string;
@@ -423,12 +544,13 @@ interface BuildConfigInput {
     coolDownMs?: number;
     navTimeoutMs?: number;
     discardWarmupRuns?: number;
+    discardWarmupCase?: boolean;
     shuffleCases?: boolean;
     reloadBetweenCases?: boolean;
     captureRenders?: boolean;
 }
 /** The settings subset a driver inherits from the device's saved config. */
-type BenchmarkSettings = Partial<Pick<AutomationConfig, "perCaseDurationMs" | "settleMs" | "navTimeoutMs" | "runsPerCase" | "coolDownMs" | "discardWarmupRuns" | "shuffleCases" | "reloadBetweenCases" | "captureRenders">>;
+type BenchmarkSettings = Partial<Pick<AutomationConfig, "perCaseDurationMs" | "settleMs" | "navTimeoutMs" | "runsPerCase" | "coolDownMs" | "discardWarmupRuns" | "discardWarmupCase" | "shuffleCases" | "reloadBetweenCases" | "captureRenders">>;
 /**
  * Build + validate the AutomationConfig the device expects. Throws on bad input.
  *
@@ -461,13 +583,17 @@ interface RankRow {
     deltaJsFps: number | null;
     /** At-risk axes for this case (e.g. "UI thread drops frames", "CPU near cap"). */
     flags: string[];
+    /** Thermal state at the median run's start, when the device reported one. */
+    thermalState?: "nominal" | "fair" | "serious" | "critical";
     /** React commits during the median run (null when capture was off/unavailable). */
     renderCommits: number | null;
     /** Top components by total render self-time during the median run. */
+    renderWasted?: number;
     topRenderers: {
         name: string;
         renders: number;
         totalMs: number;
+        cause?: string;
     }[];
 }
 interface BatchRanking {
@@ -506,14 +632,44 @@ declare function rankBatchFromIndex(index: IndexEntry[], batchId: string, casesO
 }[]): BatchRanking;
 /** Render a batch ranking as a trade-off-aware report (no single false winner). */
 declare function formatRankingMarkdown(ranking: BatchRanking): string;
-/** Side-by-side comparison of two full report stats. */
+/**
+ * Side-by-side comparison of two full reports.
+ *
+ * Renders are part of the comparison, not an afterthought: when someone runs
+ * this after a memoization fix, "did the render count actually drop" IS the
+ * question, and for a long while this function silently dropped the block
+ * that answers it.
+ */
 declare function compareReportStats(a: {
     name: string;
     stats: BenchmarkReportStats;
+    renders?: RenderCapture;
 }, b: {
     name: string;
     stats: BenchmarkReportStats;
+    renders?: RenderCapture;
 }): {
+    renders?: {
+        total: {
+            a: number;
+            b: number;
+            delta: number;
+        };
+        commits: {
+            a: number;
+            b: number;
+            delta: number;
+        };
+        wasted: {
+            a: number;
+            b: number;
+            delta: number;
+        };
+        causes: {
+            a: RenderCauseCounts;
+            b: RenderCauseCounts;
+        };
+    } | undefined;
     a: string;
     b: string;
     uiFps: {

package/dist/index.d.ts

@@ -24,6 +24,14 @@ interface DeviceInfo {
     isConnected: boolean;
     /** Whether the connected app reported an active Buoy Pro license. */
     isPro: boolean;
+    /**
+     * The app's access tier. Apps older than the tier split report only `isPro`,
+     * which maps exactly — a key could only ever grant Pro back then.
+     *
+     * Surfaced so `list_devices` can say WHY the MCP is blocked: "signed in on
+     * the free tier" and "no account at all" are different problems.
+     */
+    tier: "anonymous" | "free" | "pro";
     tools: ToolCapability[];
 }
 /** How the client obtained its broker connection. */
@@ -57,11 +65,31 @@ declare class SyncClient {
     private pendingActions;
     /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
     private snapshotWaiters;
+    /** When each cached snapshot arrived, keyed by snapKey (staleness reporting). */
+    private snapshotAt;
+    /** Liveness per device — see {@link noteTimeout}. */
+    private health;
+    /** Dev-server origin per device — see {@link noteDevServerOrigin}. */
+    private devServerOrigins;
+    /** Devices whose origin probe already ran (a production bundle has none). */
+    private originProbed;
+    /** Last time each device appeared in the broker's device list. */
+    private lastSeen;
     constructor(opts?: SyncClientOptions);
     private readonly autoSpawn;
     /** Connect to a running broker, or spawn one in-process, then handshake. */
     start(): Promise<BrokerMode>;
     private connectSocket;
+    /**
+     * Drop everything remembered about devices that have been gone a while.
+     *
+     * Deliberately NOT on disconnect: a crashed app often drops off the broker,
+     * and its cached console snapshot is the crash evidence — throwing that away
+     * the instant it disconnects would delete the answer. But device ids change
+     * with every simulator erase and fresh dev client, and each one can hold
+     * multi-MB snapshots, so a long-lived server has to forget eventually.
+     */
+    private pruneStaleDevices;
     /** Disconnect and tear down a spawned broker, if any. */
     stop(): Promise<void>;
     /** All devices the broker knows about, merged with their advertised tools. */
@@ -91,6 +119,61 @@ declare class SyncClient {
      * is blocked.
      */
     requireProDevice(deviceId?: string): string;
+    private healthOf;
+    /** The device answered — it's alive. */
+    private noteOk;
+    /**
+     * The device didn't answer. A crashed app never answers again, so after the
+     * first miss we stop paying the full timeout on every subsequent call.
+     */
+    private noteTimeout;
+    /** True once a device has missed a call and hasn't answered since. */
+    isUnresponsive(deviceId: string): boolean;
+    /**
+     * Full timeout normally; a short one for a device already not answering.
+     *
+     * With one escape hatch: every RECOVERY_PROBE_MS a flagged device gets the
+     * full budget again. Without it the flag is self-sustaining — a device whose
+     * work legitimately takes longer than the short budget (a big snapshot, a
+     * slow simulator) can never answer, so it can never clear the flag, and every
+     * later reply is a confident "most likely CRASHED" about a healthy app.
+     */
+    private timeoutFor;
+    /**
+     * Plain-language diagnosis for a device that isn't answering, including the
+     * app's last words if the console tool got a crash flush out in time.
+     *
+     * A silent timeout is the worst possible answer here: the app is on a redbox,
+     * the reason is already captured, and without this the caller reads "timed
+     * out" and keeps retrying the same dead device.
+     */
+    unresponsiveNote(deviceId: string): string;
+    /**
+     * The newest error line the console tool synced for this device, if any.
+     * Reads the cached console snapshot rather than the device (which, by the
+     * time this matters, is not answering).
+     */
+    private lastFatalFor;
+    /** Age of the cached snapshot for a tool, in ms (null = never received). */
+    snapshotAgeMs(toolId: string, deviceId: string): number | null;
+    /**
+     * Remember where a device's bundle came from, reported by core's `app`
+     * adapter while the app is healthy. It is the only way to reload an app that
+     * has crashed: the in-app reload needs the React tree that the crash
+     * destroyed, but the dev server's reload is handled natively.
+     */
+    noteDevServerOrigin(deviceId: string, origin: unknown): void;
+    /**
+     * Ask a freshly-announced device where its bundle came from, once.
+     *
+     * Deliberately eager: this is the piece of information that can ONLY be
+     * collected while the app is healthy, and is only ever needed after it has
+     * stopped answering. One cheap round-trip per device buys the ability to
+     * recover a crashed app instead of telling the caller to go do it by hand.
+     */
+    private learnDevServerOrigin;
+    /** The dev-server origin last reported by this device, if any. */
+    devServerOrigin(deviceId: string): string | null;
     /**
      * Keep the device RECORDING this tool, without asking it to stream.
      *
@@ -135,10 +218,14 @@ declare class SyncClient {
      */
     getSnapshot(toolId: string, deviceId?: string, opts?: {
         timeoutMs?: number;
+        silent?: boolean;
     }): Promise<{
         deviceId: string;
         payload: unknown;
+        stale?: string;
     }>;
+    /** Header line for data served from cache because the device went quiet. */
+    private staleNote;
     private waitForSnapshot;
     /**
      * Invoke a remote action on a device and await its result. Pass deviceId to
@@ -146,14 +233,10 @@ declare class SyncClient {
      */
     callAction(toolId: string, action: string, params?: unknown, deviceId?: string, opts?: {
         timeoutMs?: number;
+        silent?: boolean;
     }): Promise<unknown>;
 }
 
-/**
- * Build the Buoy MCP server and register all tools against a connected
- * {@link SyncClient}. Tool packs (perf-monitor, etc.) are layered on top of the
- * generic core here.
- */
 declare function createMcpServer(sync: SyncClient): McpServer;
 
 /**
@@ -351,6 +434,12 @@ interface AutomationConfig {
     runsPerCase?: number;
     coolDownMs?: number;
     discardWarmupRuns?: number;
+    /**
+     * Run a throwaway case at the front of the batch and drop it from the
+     * results, so the batch's cold start doesn't land on real data. Default true.
+     * See the perf-monitor AutomationConfig for the reproduction.
+     */
+    discardWarmupCase?: boolean;
     shuffleCases?: boolean;
     /** Capture per-component render counts/durations each run. Default true. */
     captureRenders?: boolean;
@@ -378,13 +467,17 @@ interface IndexEntry {
     caseId?: string;
     runIndex?: number;
     isMedianRun?: boolean;
+    /** Thermal state at run start; a throttled run reads cheap AND janky. */
+    thermalState?: "nominal" | "fair" | "serious" | "critical";
     /** Render-capture mirror (absent when capture was unavailable/disabled). */
     renderCommits?: number;
     renderTotalMs?: number;
+    renderWasted?: number;
     topRenderers?: {
         name: string;
         renders: number;
         totalMs: number;
+        cause?: string;
     }[];
 }
 /** Per-metric min/max/avg/p95 channel. */
@@ -406,12 +499,40 @@ interface BenchmarkReportStats {
     uiJankFrames: number;
     deviceMaxRefreshRate: number;
 }
-
 /**
- * Pure helpers for the perf-monitor pack: build an AutomationConfig from
- * MCP-friendly input, estimate batch duration, and rank a finished batch's
- * results into a winner + comparison table. No network/sync — unit-testable.
+ * Why components rendered, counted over a run.
+ *
+ * `propsUnstable` is the actionable one: props changed by IDENTITY only —
+ * a fresh arrow or object literal handed down every render — while every
+ * value stayed equal. Reporting that as plain "props" sends you into the
+ * child, when the fix is always in the parent.
  */
+interface RenderCauseCounts {
+    mount?: number;
+    props?: number;
+    propsUnstable?: number;
+    hooks?: number;
+    parent?: number;
+}
+interface RenderCapture {
+    totalCommits: number;
+    totalRenders: number;
+    capturedDurations: boolean;
+    totalRenderMs?: number;
+    /** Parent cascades + identity-only prop churn: the removable share. */
+    wastedRenders?: number;
+    causes?: RenderCauseCounts;
+    topComponents: {
+        name: string;
+        renders: number;
+        totalMs: number;
+        maxMs: number;
+        avgMs: number;
+        causes?: RenderCauseCounts;
+        changedProps?: string[];
+        parentName?: string;
+    }[];
+}
 
 interface BuildConfigInput {
     targetRoute: string;
@@ -423,12 +544,13 @@ interface BuildConfigInput {
     coolDownMs?: number;
     navTimeoutMs?: number;
     discardWarmupRuns?: number;
+    discardWarmupCase?: boolean;
     shuffleCases?: boolean;
     reloadBetweenCases?: boolean;
     captureRenders?: boolean;
 }
 /** The settings subset a driver inherits from the device's saved config. */
-type BenchmarkSettings = Partial<Pick<AutomationConfig, "perCaseDurationMs" | "settleMs" | "navTimeoutMs" | "runsPerCase" | "coolDownMs" | "discardWarmupRuns" | "shuffleCases" | "reloadBetweenCases" | "captureRenders">>;
+type BenchmarkSettings = Partial<Pick<AutomationConfig, "perCaseDurationMs" | "settleMs" | "navTimeoutMs" | "runsPerCase" | "coolDownMs" | "discardWarmupRuns" | "discardWarmupCase" | "shuffleCases" | "reloadBetweenCases" | "captureRenders">>;
 /**
  * Build + validate the AutomationConfig the device expects. Throws on bad input.
  *
@@ -461,13 +583,17 @@ interface RankRow {
     deltaJsFps: number | null;
     /** At-risk axes for this case (e.g. "UI thread drops frames", "CPU near cap"). */
     flags: string[];
+    /** Thermal state at the median run's start, when the device reported one. */
+    thermalState?: "nominal" | "fair" | "serious" | "critical";
     /** React commits during the median run (null when capture was off/unavailable). */
     renderCommits: number | null;
     /** Top components by total render self-time during the median run. */
+    renderWasted?: number;
     topRenderers: {
         name: string;
         renders: number;
         totalMs: number;
+        cause?: string;
     }[];
 }
 interface BatchRanking {
@@ -506,14 +632,44 @@ declare function rankBatchFromIndex(index: IndexEntry[], batchId: string, casesO
 }[]): BatchRanking;
 /** Render a batch ranking as a trade-off-aware report (no single false winner). */
 declare function formatRankingMarkdown(ranking: BatchRanking): string;
-/** Side-by-side comparison of two full report stats. */
+/**
+ * Side-by-side comparison of two full reports.
+ *
+ * Renders are part of the comparison, not an afterthought: when someone runs
+ * this after a memoization fix, "did the render count actually drop" IS the
+ * question, and for a long while this function silently dropped the block
+ * that answers it.
+ */
 declare function compareReportStats(a: {
     name: string;
     stats: BenchmarkReportStats;
+    renders?: RenderCapture;
 }, b: {
     name: string;
     stats: BenchmarkReportStats;
+    renders?: RenderCapture;
 }): {
+    renders?: {
+        total: {
+            a: number;
+            b: number;
+            delta: number;
+        };
+        commits: {
+            a: number;
+            b: number;
+            delta: number;
+        };
+        wasted: {
+            a: number;
+            b: number;
+            delta: number;
+        };
+        causes: {
+            a: RenderCauseCounts;
+            b: RenderCauseCounts;
+        };
+    } | undefined;
     a: string;
     b: string;
     uiFps: {