@reticlehq/server 2.2.1 → 2.4.0

package/dist/honesty/verified.js

@@ -0,0 +1,86 @@
+import { Verified } from '@reticlehq/core';
+import { HonestyGrade } from './honesty.js';
+export function decideVerified(inputs) {
+    const { pass, honesty, contradictions = [], settled, outcomePending, outcomeUnread } = inputs;
+    // A failed assertion is the most actionable fact there is; it leads.
+    if (pass === false) {
+        return { verified: Verified.NO, because: 'the declared consequence did not hold' };
+    }
+    // A contradiction outranks a passing assertion, and that inversion is the whole point: the case
+    // this product exists to catch is a green assertion sitting on top of a failed write. Measured on
+    // the bench app — `ui-advanced-request-failed` arrived with verdict.pass true and every other
+    // channel agreeing. Letting `pass` win there would report exactly the false green being detected.
+    if (contradictions.length > 0) {
+        const kinds = contradictions.map((c) => c.kind).join(', ');
+        return {
+            verified: Verified.NO,
+            because: `channels disagree about this action (${kinds}) even though the assertion passed`,
+        };
+    }
+    // Dirty capture is NOT failure. The layer could not see part of the window, so any green is a
+    // statement about what it happened to observe — which is precisely the thing that must not be
+    // reported as proof.
+    if (!honesty.integrity.clean) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: `capture was not clean (${honesty.integrity.issues.join('; ')}), so a green here would only describe what was observed`,
+        };
+    }
+    // A vacuous green: nothing was actually proved. Grade NONE means no signal, no request, no state
+    // change and no element was pinned — the assertion could not have failed, which makes passing it
+    // evidence of nothing.
+    if (honesty.grade === HonestyGrade.NONE) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: 'nothing was asserted at a real grade, so passing proves nothing — assert a signal, request, or state path',
+        };
+    }
+    // A `202 Accepted` is the server saying, in the only word HTTP has for it, that the outcome does
+    // not exist yet. Treating 2xx as success makes every asynchronous workflow verifiable at exactly
+    // the moment nothing has been decided.
+    //
+    // Measured on a logistics console with server-side reconciliation: a dispatch answered 202, the row
+    // optimistically rendered "dispatched", the page settled, and the verdict came back `yes` — then
+    // the server REVERTED it to `held` 1.2s later. Every channel agreed, and every channel was early.
+    // UNKNOWN rather than NO: nothing has failed, and saying it has would be its own false report.
+    if (outcomePending === true) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: 'a write returned 202 Accepted, so the server has not finished processing it — this window cannot contain the outcome; re-check once it reconciles',
+        };
+    }
+    // A write answered 2xx and its payload went unread, so the one channel that could contradict the
+    // screen was never opened. Reporting `yes` here means "no channel disagreed" — true only because a
+    // channel was closed. Measured on a shipments console: `POST /api/bulk-hold` → 200 with three of
+    // nine items failed inside the body, banner reading "9 shipments held", verdict `yes`.
+    //
+    // UNKNOWN, not NO: nothing is known to have failed. The remedy is in the sentence, because an
+    // agent that cannot act on a caveat will learn to skip it.
+    if (outcomeUnread === true) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: 'a write returned 2xx with a response body that was never recorded, so its outcome is unread — a 200 describes the transport, not the result (a batch reports per-item failures in the body, and every GraphQL error is a 200). Enable it where your app calls connect(): `reticle.connect({ captureNetworkBodies: true })`, then re-run',
+        };
+    }
+    // Never settled: the page may still be moving, so the observation window may have closed early.
+    if (settled === false) {
+        return {
+            verified: Verified.UNKNOWN,
+            because: 'the page never settled, so the reaction window may have closed before the app finished',
+        };
+    }
+    // Partial coverage is a real caveat but not a blocker — it is reported in `honesty.coverage` and
+    // does not by itself make a graded, clean, uncontradicted pass untrustworthy.
+    //
+    // It must not be described as clean, though. This sentence said "over a clean capture" regardless,
+    // so a verdict could read `verified: yes ... over a clean capture` directly beside `coverage:
+    // partial` — the prose contradicting the evidence block next to it. Whichever a reader believes,
+    // one of them lied, and the whole point of this layer is that the sentence can be trusted on its
+    // own. Seen on a one-way IPC send: coverage said the outcome was unobservable, `because` said clean.
+    return {
+        verified: Verified.YES,
+        because: honesty.coverage?.partial === true
+            ? `assertion held at ${honesty.grade} grade with no channel disagreeing, but coverage was PARTIAL — see \`coverage\` for what went unobserved`
+            : `assertion held at ${honesty.grade} grade over a clean capture with no channel disagreeing`,
+    };
+}

package/dist/http-server.d.ts

@@ -32,4 +32,3 @@ export interface SharedServer {
 export declare function createSharedServer(options?: {
     token?: string;
 }): SharedServer;
-//# sourceMappingURL=http-server.d.ts.map

package/dist/http-server.js

@@ -2,6 +2,7 @@ import * as http from 'node:http';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { MCP_SSE_PATH, MCP_MESSAGE_PATH, STATUS_PATH } from '@reticlehq/core';
 import { log } from './log.js';
+import { reportMcpConnected } from './telemetry/mcp-connection.js';
 import { isLoopbackHost, isLocalWebOrigin, isLoopbackPeer, requestToken, tokensMatch, } from './token-auth.js';
 /**
  * Creates a shared HTTP server that handles both the WebSocket bridge (browser SDK) and the
@@ -84,6 +85,10 @@ export function createSharedServer(options = {}) {
                 .connect(transport)
                 .then(() => {
                 log('mcp_client_connected', { sessionId: sid });
+                // The one signal that separates "Reticle is running" from "somebody is USING it": a daemon
+                // can sit up for days with nothing attached. It also exposes reconnect churn, which is
+                // indistinguishable from healthy usage in every other metric.
+                reportMcpConnected();
             })
                 .catch((err) => {
                 const message = err instanceof Error ? err.message : String(err);
@@ -138,4 +143,3 @@ export function createSharedServer(options = {}) {
     }
     return { httpServer, attachMcp, attachStatus, attachAgentPresence, close };
 }
-//# sourceMappingURL=http-server.js.map

package/dist/hunt/hunt-report.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Aggregate many crawl runs into the one number the core claim needs.
+ *
+ * Detection already exists: `reticle_crawl` drives every reachable control and reports contradictions
+ * — two channels disagreeing about the same click. It found `swallowed-500-login` and, separately,
+ * `ui-advanced-request-failed` on a control whose assertion was green, neither of them planted.
+ *
+ * What was missing is the arithmetic that turns those into evidence. The claim worth making is not
+ * "Reticle can find bugs"; it is:
+ *
+ *   "Run over N already-merged, already-green changes, it found X real bugs their own tests
+ *    certified as passing."
+ *
+ * That needs no control arm, which is why it is the cheapest credible proof available: the
+ * counterfactual is already established, because those changes SHIPPED. An A/B is the second study,
+ * and this tells you where to point it.
+ *
+ * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
+ * it across a commit range is a shell loop. This is only the part that must not be done by eye.
+ */
+/** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
+export declare const CONTRADICTION_KINDS: readonly string[];
+export interface HuntAnomaly {
+    kind: string;
+    ref?: string;
+    desc?: string;
+    detail?: string;
+}
+/** One crawl over one checkout. `label` is whatever identifies it — a commit sha, a PR number. */
+export interface HuntRun {
+    label: string;
+    anomalies: readonly HuntAnomaly[];
+    /** Controls actually driven. A run that drove nothing proves nothing and is reported separately. */
+    stepsRun?: number;
+}
+export interface HuntSummary {
+    runs: number;
+    /** Runs that actually drove at least one control. The denominator that can honestly be quoted. */
+    runsWithCoverage: number;
+    /** Runs where at least one CONTRADICTION was found — the headline numerator. */
+    runsWithContradictions: number;
+    contradictions: number;
+    /** Single-channel faults (console errors, failed requests, dead controls). Context, not the claim. */
+    singleChannelFaults: number;
+    byKind: Record<string, number>;
+    /** Labels with contradictions, so each one can be confirmed by hand before it is counted. */
+    flagged: string[];
+    headline: string;
+}
+export declare function summarizeHunt(runs: readonly HuntRun[]): HuntSummary;

package/dist/hunt/hunt-report.js

@@ -0,0 +1,84 @@
+/**
+ * Aggregate many crawl runs into the one number the core claim needs.
+ *
+ * Detection already exists: `reticle_crawl` drives every reachable control and reports contradictions
+ * — two channels disagreeing about the same click. It found `swallowed-500-login` and, separately,
+ * `ui-advanced-request-failed` on a control whose assertion was green, neither of them planted.
+ *
+ * What was missing is the arithmetic that turns those into evidence. The claim worth making is not
+ * "Reticle can find bugs"; it is:
+ *
+ *   "Run over N already-merged, already-green changes, it found X real bugs their own tests
+ *    certified as passing."
+ *
+ * That needs no control arm, which is why it is the cheapest credible proof available: the
+ * counterfactual is already established, because those changes SHIPPED. An A/B is the second study,
+ * and this tells you where to point it.
+ *
+ * Pure functions over already-collected reports — the driving is `reticle_crawl`'s job, and running
+ * it across a commit range is a shell loop. This is only the part that must not be done by eye.
+ */
+/** The contradiction kinds — cross-channel disagreement, as opposed to a single-channel fault. */
+export const CONTRADICTION_KINDS = [
+    'ui-advanced-request-failed',
+    'signal-contradicted',
+    'response-ignored',
+    'duplicate-request',
+    'request-never-settled',
+    'failure-misattributed',
+];
+const isContradiction = (kind) => CONTRADICTION_KINDS.includes(kind);
+export function summarizeHunt(runs) {
+    const byKind = {};
+    const flagged = [];
+    let contradictions = 0;
+    let singleChannelFaults = 0;
+    let runsWithCoverage = 0;
+    for (const run of runs) {
+        // A run that drove nothing is not evidence of cleanliness. Counting it in the denominator would
+        // dilute the rate with checkouts where the app never even came up — the arithmetic equivalent of
+        // reporting a green because no test ran.
+        if ((run.stepsRun ?? 0) > 0)
+            runsWithCoverage += 1;
+        let flaggedThisRun = false;
+        for (const anomaly of run.anomalies) {
+            byKind[anomaly.kind] = (byKind[anomaly.kind] ?? 0) + 1;
+            if (isContradiction(anomaly.kind)) {
+                contradictions += 1;
+                flaggedThisRun = true;
+            }
+            else {
+                singleChannelFaults += 1;
+            }
+        }
+        if (flaggedThisRun)
+            flagged.push(run.label);
+    }
+    return {
+        runs: runs.length,
+        runsWithCoverage,
+        runsWithContradictions: flagged.length,
+        contradictions,
+        singleChannelFaults,
+        byKind,
+        flagged,
+        headline: buildHeadline(runsWithCoverage, flagged.length, contradictions),
+    };
+}
+/**
+ * The sentence that goes in front of someone, phrased so it cannot overstate itself.
+ *
+ * It counts CHECKOUTS with a finding rather than raw findings, because one broken control clicked
+ * five times is one bug and five anomalies. It also says "candidate": every flag still has to be
+ * confirmed by hand before it is a bug, and a number that skips that step is the kind of evidence
+ * this project exists to distrust.
+ */
+function buildHeadline(withCoverage, flaggedRuns, contradictions) {
+    if (withCoverage === 0) {
+        return 'no run drove a single control — nothing was measured, which is not the same as nothing being wrong';
+    }
+    if (flaggedRuns === 0) {
+        return `${String(withCoverage)} merged changes crawled, no cross-channel contradictions found — confirm coverage was real before reading this as clean`;
+    }
+    return `${String(flaggedRuns)} of ${String(withCoverage)} merged, already-green changes carried a candidate false green (${String(contradictions)} contradictions) — each needs manual confirmation before it is counted`;
+}

package/dist/idle-shutdown.d.ts

@@ -31,4 +31,3 @@ export declare class IdleShutdown {
  * `0` to disable. Anything missing/invalid falls back to the default. Pure.
  */
 export declare function resolveIdleShutdownMs(raw: string | undefined): number;
-//# sourceMappingURL=idle-shutdown.d.ts.map

package/dist/idle-shutdown.js

@@ -65,4 +65,3 @@ export function resolveIdleShutdownMs(raw) {
         return SESSION_LIFECYCLE.DAEMON_IDLE_SHUTDOWN_MS;
     return Math.floor(n);
 }
-//# sourceMappingURL=idle-shutdown.js.map

package/dist/index.d.ts

@@ -132,4 +132,3 @@ export declare function start(options?: StartOptions): Promise<RunningServer>;
  * browser sessions persist in the daemon.
  */
 export declare function startDaemon(options?: StartOptions): Promise<RunningServer>;
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -426,4 +426,3 @@ export async function startDaemon(options = {}) {
         },
     };
 }
-//# sourceMappingURL=index.js.map

package/dist/init/agent-rules.d.ts

@@ -35,4 +35,3 @@ export declare function markedBlock(): string;
 export declare function mergeMarkedInstruction(existing: string | null | undefined): AgentRuleResult;
 /** The Cursor rule file (.mdc): `alwaysApply` keeps the rule in every turn's context. */
 export declare function cursorRuleFile(): string;
-//# sourceMappingURL=agent-rules.d.ts.map

package/dist/init/agent-rules.js

@@ -27,7 +27,10 @@ This app is instrumented by **Reticle** — an in-app verification layer exposed
 - **How:** drive the actual flow (\`reticle_act\` / \`reticle_act_and_wait\`), then read the observable effect (\`reticle_assert\`, \`reticle_snapshot\`, \`reticle_state\`, \`reticle_network\`). Confirm the change produced the effect it was meant to, with no new console errors or failed requests.
 - **Covered flows:** run \`reticle gate\` — it reports which recorded flows the changed files affect and whether they still pass.
 - **Never weaken a check to make it green.** Downgrading, skipping, or deleting an assertion is a finding, not a fix.
-- **If Reticle can't run** (no daemon, or this is not a running web app), say so — do not skip verification silently.`;
+- **If Reticle can't run** (no daemon, or this is not a running web app), say so — do not skip verification silently.
+- **If a tool result carries \`update_available\`, say so.** Reticle checked npm and a newer version exists. Tell the human the version numbers and offer to run \`reticle update\` — between tasks, never mid-verification, because it restarts the daemon and drops the session. Finish what you are doing first.
+- **Wish Reticle could do something? Ask for it with \`reticle_feedback\`.** Reticle is built for agents, so what you find awkward or missing is what decides the roadmap — and you are the only one who can report it, because that thought disappears when your context does. File \`feature_request\` for something that does not exist, \`improvement\` for something that works but costs too many calls. Say what you are actually trying to achieve (\`need\`) and how you work around it today (\`currentApproach\`), and set \`model\` to the model you are running. File it the moment you notice, then carry on — nothing is too minor.
+- **If Reticle itself fails you, tell its maintainers with \`reticle_feedback\`.** A tool that returned something wrong, a thing Reticle could not observe at all, or a verdict you could not act on — file it with a root-cause analysis and the call trace, then carry on with the task. Working around a broken tool in silence is how the same defect survives. This is about defects in *Reticle*; a bug you find in *this app* is Reticle working, and belongs in your report to the user instead.`;
 export const AgentRuleStatus = {
     APPLY: 'apply',
     ALREADY: 'already',
@@ -62,4 +65,3 @@ alwaysApply: true
 ${RULE_BODY}
 `;
 }
-//# sourceMappingURL=agent-rules.js.map

package/dist/init/capabilities.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What the app can be driven by: its `data-testid` values, and which state library holds its truth.
+ *
+ * `init` wired none of this, so every app came up with `hasCapabilities: false`, empty capabilities,
+ * and a `reticle_state` holding nothing but `__reticle_renders` — the state-truth read that SKILL.md
+ * calls the highest-value line was unavailable on every app out of the box. Measured across six.
+ *
+ * Testids are scanned rather than asked for. Stores are NAMED but not wired: detecting that an app
+ * depends on zustand is easy, knowing which module exports the store instance is not, and generating
+ * a wrong import would break the dev module that everything else now hangs off.
+ */
+/** Cap the generated list. A capabilities block is a hint for an agent, not an inventory. */
+export declare const MAX_TESTIDS = 60;
+/** Every distinct `data-testid` literal in the given sources, in first-seen order. */
+export declare function scanTestids(sources: readonly string[]): string[];
+/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+export declare function storeHints(deps: ReadonlySet<string>): string[];

package/dist/init/capabilities.js

@@ -0,0 +1,51 @@
+/**
+ * What the app can be driven by: its `data-testid` values, and which state library holds its truth.
+ *
+ * `init` wired none of this, so every app came up with `hasCapabilities: false`, empty capabilities,
+ * and a `reticle_state` holding nothing but `__reticle_renders` — the state-truth read that SKILL.md
+ * calls the highest-value line was unavailable on every app out of the box. Measured across six.
+ *
+ * Testids are scanned rather than asked for. Stores are NAMED but not wired: detecting that an app
+ * depends on zustand is easy, knowing which module exports the store instance is not, and generating
+ * a wrong import would break the dev module that everything else now hangs off.
+ */
+/** `data-testid="foo"` / `data-testid='foo'` / `data-testid={"foo"}` — the forms people actually write. */
+const TESTID_ATTR = /data-testid\s*=\s*[{]?\s*["'`]([^"'`]+)["'`]/g;
+/** Cap the generated list. A capabilities block is a hint for an agent, not an inventory. */
+export const MAX_TESTIDS = 60;
+/** Every distinct `data-testid` literal in the given sources, in first-seen order. */
+export function scanTestids(sources) {
+    const found = new Set();
+    for (const src of sources) {
+        for (const m of src.matchAll(TESTID_ATTR)) {
+            const id = m[1];
+            if (id !== undefined && id.length > 0)
+                found.add(id);
+            if (found.size >= MAX_TESTIDS)
+                return [...found];
+        }
+    }
+    return [...found];
+}
+/**
+ * State libraries the browser SDK has an adapter for, in the order we would recommend registering
+ * them. TanStack Query is first on purpose: a stale cache served as fresh fires NO network request,
+ * so the network log shows silence and the DOM shows a plausible number — the cache is the only
+ * witness, which makes it the highest-value store in the list and the least obvious one to add.
+ */
+const STORE_LIBRARIES = [
+    ['@tanstack/react-query', "registerStore('queries', tanstackQueryStore(queryClient))"],
+    ['zustand', "registerStore('app', useStore) // pass the store itself, not () => store.getState()"],
+    ['@reduxjs/toolkit', "registerStore('app', store)"],
+    ['redux', "registerStore('app', store)"],
+    ['jotai', "registerStore('app', jotaiStore(getDefaultStore(), { cart, user }))"],
+    ['valtio', "registerStore('app', valtioStore(state))"],
+    ['mobx', "registerStore('app', mobxStore(state))"],
+    ['xstate', "registerStore('machine', xstateStore(actor))"],
+    ['pinia', "registerStore('cart', piniaStore(useCartStore()))"],
+    ['svelte', "registerStore('cart', svelteStore(cartStore))"],
+];
+/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+export function storeHints(deps) {
+    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep)).map(([, hint]) => hint);
+}

package/dist/init/cursor.d.ts

@@ -22,4 +22,3 @@ interface CursorMergeResult {
 export declare function cursorServerEntry(): Record<string, unknown>;
 export declare function mergeCursorConfig(existing: string | null): CursorMergeResult;
 export {};
-//# sourceMappingURL=cursor.d.ts.map

package/dist/init/cursor.js

@@ -46,4 +46,3 @@ export function mergeCursorConfig(existing) {
     };
     return { status: CursorMergeStatus.APPLY, content: `${JSON.stringify(merged, null, 2)}\n` };
 }
-//# sourceMappingURL=cursor.js.map

package/dist/init/desktop-doctor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Setup RCA for desktop apps.
+ *
+ * Every failure this catches is SILENT. A Tauri app with the default CSP runs perfectly and simply
+ * never appears in `reticle status` — the WebSocket is blocked before it opens, and nothing in the
+ * app's own console says so. An Electron app missing the preload line works fine and reports zero
+ * network activity forever, which reads as "the app makes no backend calls" rather than "you are
+ * blind to all of them".
+ *
+ * Silent misconfiguration is the same disease as a false green: the tool answers confidently and the
+ * answer is wrong. So the diagnosis names the file, the reason, and the exact line to add.
+ *
+ * Pure: a `read` function in, findings out. No fs, no cwd, no process.
+ */
+export declare const DesktopFinding: {
+    /** Tauri's CSP will block the bridge WebSocket — the app will never connect, with no error. */
+    readonly TAURI_CSP_BLOCKS_BRIDGE: "tauri-csp-blocks-bridge";
+    /** A custom CSP dropped the `ipc:` source Tauri needs for `invoke` itself. */
+    readonly TAURI_CSP_BLOCKS_IPC: "tauri-csp-blocks-ipc";
+    /** The preload never requires the shim, so every IPC call is invisible. */
+    readonly ELECTRON_PRELOAD_MISSING: "electron-preload-missing";
+    /** The main process never installs the capture helper, so screenshots are unavailable. */
+    readonly ELECTRON_CAPTURE_MISSING: "electron-capture-missing";
+};
+export type DesktopFinding = (typeof DesktopFinding)[keyof typeof DesktopFinding];
+export interface DesktopDiagnosis {
+    code: DesktopFinding;
+    /** Which file to look at. */
+    file: string;
+    /** What is wrong, in one line. */
+    problem: string;
+    /** Exactly what to add — copy-pasteable, with the port actually in use. */
+    fix: string;
+}
+/** Reads a project-relative path. Undefined means the file does not exist. */
+export type ReadFile = (path: string) => string | undefined;
+/** Is this project a desktop shell at all? Used to print a positive result instead of silence. */
+export declare function isDesktopProject(read: ReadFile): boolean;
+/** Which desktop shell (if any) this project is, and what is missing from its Reticle wiring. */
+export declare function diagnoseDesktop(read: ReadFile, port: number): DesktopDiagnosis[];

package/dist/init/desktop-doctor.js

@@ -0,0 +1,198 @@
+import { RETICLE_IPC_GLOBAL } from '@reticlehq/core';
+/**
+ * Setup RCA for desktop apps.
+ *
+ * Every failure this catches is SILENT. A Tauri app with the default CSP runs perfectly and simply
+ * never appears in `reticle status` — the WebSocket is blocked before it opens, and nothing in the
+ * app's own console says so. An Electron app missing the preload line works fine and reports zero
+ * network activity forever, which reads as "the app makes no backend calls" rather than "you are
+ * blind to all of them".
+ *
+ * Silent misconfiguration is the same disease as a false green: the tool answers confidently and the
+ * answer is wrong. So the diagnosis names the file, the reason, and the exact line to add.
+ *
+ * Pure: a `read` function in, findings out. No fs, no cwd, no process.
+ */
+export const DesktopFinding = {
+    /** Tauri's CSP will block the bridge WebSocket — the app will never connect, with no error. */
+    TAURI_CSP_BLOCKS_BRIDGE: 'tauri-csp-blocks-bridge',
+    /** A custom CSP dropped the `ipc:` source Tauri needs for `invoke` itself. */
+    TAURI_CSP_BLOCKS_IPC: 'tauri-csp-blocks-ipc',
+    /** The preload never requires the shim, so every IPC call is invisible. */
+    ELECTRON_PRELOAD_MISSING: 'electron-preload-missing',
+    /** The main process never installs the capture helper, so screenshots are unavailable. */
+    ELECTRON_CAPTURE_MISSING: 'electron-capture-missing',
+};
+const TAURI_CONF = 'src-tauri/tauri.conf.json';
+const PRELOAD_REQUIRE = '@reticlehq/electron/preload';
+const CAPTURE_REQUIRE = '@reticlehq/electron/main';
+function parseJson(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined; // a malformed config is the app's problem, not something to crash the doctor on
+    }
+}
+function record(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+/**
+ * Does this CSP permit the bridge WebSocket on `port`?
+ *
+ * A MISSING csp key is treated as blocking, not permissive: Tauri applies a restrictive default, so
+ * reporting "no CSP, therefore fine" would be precisely the false green this tool exists to prevent.
+ */
+function cspAllowsBridge(csp, port) {
+    if (csp === undefined)
+        return false;
+    const exact = `ws://localhost:${String(port)}`;
+    const loopback = `ws://127.0.0.1:${String(port)}`;
+    // A BARE `ws:` scheme source allows any ws origin. It must be matched as a whole source, not as a
+    // substring: `includes('ws:')` also matches `ws://localhost:4400`, which would make every port
+    // look allowed and silently defeat the port check this function exists to perform.
+    const bareScheme = /(^|[\s;])ws:(?!\/\/)/.test(csp);
+    return (csp.includes(exact) ||
+        csp.includes(loopback) ||
+        csp.includes('ws://localhost:*') ||
+        csp.includes('ws://127.0.0.1:*') ||
+        bareScheme);
+}
+/** Tauri v2 needs `ipc:`/`http://ipc.localhost` in connect-src for `invoke` to work at all. */
+function cspAllowsIpc(csp) {
+    return csp.includes('ipc:') || csp.includes('ipc.localhost');
+}
+function diagnoseTauri(read, port) {
+    const conf = parseJson(read(TAURI_CONF));
+    if (conf === undefined)
+        return [];
+    const security = record(record(conf['app'])['security']);
+    const csp = typeof security['csp'] === 'string' ? security['csp'] : undefined;
+    const findings = [];
+    if (!cspAllowsBridge(csp, port)) {
+        findings.push({
+            code: DesktopFinding.TAURI_CSP_BLOCKS_BRIDGE,
+            file: TAURI_CONF,
+            problem: csp === undefined
+                ? "no `app.security.csp` set, so Tauri's restrictive default applies and blocks the Reticle bridge — the app will run normally and never connect"
+                : 'the CSP `connect-src` does not allow the Reticle bridge WebSocket — the app will run normally and never connect',
+            fix: `add to app.security.csp connect-src:  ws://localhost:${String(port)}`,
+        });
+    }
+    if (csp !== undefined && !cspAllowsIpc(csp)) {
+        findings.push({
+            code: DesktopFinding.TAURI_CSP_BLOCKS_IPC,
+            file: TAURI_CONF,
+            problem: 'the CSP dropped the `ipc:` source Tauri needs — `invoke` itself will fail',
+            fix: 'add to app.security.csp connect-src:  ipc: http://ipc.localhost',
+        });
+    }
+    return findings;
+}
+/** The directory portion of a path, without pulling in node:path (this module stays pure). */
+function dirOf(path) {
+    const cut = path.lastIndexOf('/');
+    return cut < 0 ? '' : path.slice(0, cut + 1);
+}
+/**
+ * Where a preload SOURCE might live, in the order worth trying.
+ *
+ * Beside `main` first (the unbundled layout), then the usual source directories — a bundled setup
+ * points `main` at `out/` or `dist/` while the real preload stays in `src/` or `electron/`.
+ */
+function preloadCandidates(mainDir) {
+    const names = ['preload.cjs', 'preload.js', 'preload.mjs', 'preload.ts', 'preload.mts'];
+    const dirs = [mainDir, 'electron/', 'src/', 'src/preload/', 'src/main/', ''];
+    return dirs.flatMap((dir) => names.map((name) => `${dir}${name}`));
+}
+/**
+ * Where a BUNDLED preload's output lands. electron-vite's default layout mirrors `out/main` with
+ * `out/preload`; Forge and hand-rolled setups favour `dist`/`build`.
+ */
+function bundledPreloadCandidates(mainDir) {
+    const roots = [mainDir.replace(/main\/?$/, ''), 'out/', 'dist/', 'build/', '.vite/build/'];
+    const names = [
+        'preload/index.js',
+        'preload/index.mjs',
+        'preload/index.cjs',
+        'preload.js',
+        'preload.mjs',
+        'preload.cjs',
+    ];
+    return roots.flatMap((root) => names.map((name) => `${root}${name}`));
+}
+/**
+ * Is the preload wired, judged from whatever evidence exists?
+ *
+ * Source first (the require is right there). Failing that, the BUILD OUTPUT: bundling inlines the
+ * shim, and the shim carries the contract's own window global — finding that string in the artifact
+ * proves the preload is wired even though the require has been compiled away. Undefined means no
+ * evidence either way, and an unknown must never be reported as a fault.
+ */
+function preloadWired(read, mainDir) {
+    for (const candidate of preloadCandidates(mainDir)) {
+        const source = read(candidate);
+        if (source !== undefined)
+            return { wired: source.includes(PRELOAD_REQUIRE), file: candidate };
+    }
+    for (const candidate of bundledPreloadCandidates(mainDir)) {
+        const built = read(candidate);
+        if (built !== undefined) {
+            return { wired: built.includes(RETICLE_IPC_GLOBAL), file: candidate };
+        }
+    }
+    return undefined;
+}
+function diagnoseElectron(read, main) {
+    const findings = [];
+    const dir = dirOf(main);
+    // Undefined = no source AND no build output to judge from. An unknown is not a fault.
+    const preload = preloadWired(read, dir);
+    if (preload !== undefined && !preload.wired) {
+        findings.push({
+            code: DesktopFinding.ELECTRON_PRELOAD_MISSING,
+            file: preload.file,
+            problem: 'the preload never installs the Reticle IPC shim, so every ipcRenderer.invoke is invisible — reticle_network will report nothing and read as "this app makes no backend calls"',
+            fix: `add as the FIRST line:  require('${PRELOAD_REQUIRE}')`,
+        });
+    }
+    const mainSource = read(main);
+    if (mainSource !== undefined && !mainSource.includes(CAPTURE_REQUIRE)) {
+        findings.push({
+            code: DesktopFinding.ELECTRON_CAPTURE_MISSING,
+            file: main,
+            problem: 'the main process never installs the capture helper, so screenshots are unavailable',
+            fix: `add:  const { installReticleCapture } = require('${CAPTURE_REQUIRE}')  then installReticleCapture(win)`,
+        });
+    }
+    return findings;
+}
+/** Is this project a desktop shell at all? Used to print a positive result instead of silence. */
+export function isDesktopProject(read) {
+    if (read(TAURI_CONF) !== undefined)
+        return true;
+    const pkg = parseJson(read('package.json'));
+    if (pkg === undefined)
+        return false;
+    const deps = { ...record(pkg['dependencies']), ...record(pkg['devDependencies']) };
+    return deps['electron'] !== undefined;
+}
+/** Which desktop shell (if any) this project is, and what is missing from its Reticle wiring. */
+export function diagnoseDesktop(read, port) {
+    const tauri = diagnoseTauri(read, port);
+    if (tauri.length > 0 || read(TAURI_CONF) !== undefined)
+        return tauri;
+    const pkg = parseJson(read('package.json'));
+    if (pkg === undefined)
+        return [];
+    const deps = { ...record(pkg['dependencies']), ...record(pkg['devDependencies']) };
+    if (deps['electron'] === undefined)
+        return [];
+    const main = typeof pkg['main'] === 'string' ? pkg['main'] : undefined;
+    return main === undefined ? [] : diagnoseElectron(read, main);
+}