@reticlehq/server 2.14.0 → 3.2.0

package/dist/crawl/crawl.js

@@ -1,441 +0,0 @@
-import { span } from '../trace.js';
-import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
-import { crawlEmptyNote } from './crawl-empty.js';
-import { parseInteractive, asRecord, asNumber, asString, sourceOf, } from '../tools/tools-helpers.js';
-import { isSessionReplacedError } from '../session/session-replaced.js';
-import { ReticleTool } from '../tools/tool-names.js';
-import { findContradictions } from '../events/contradictions.js';
-/** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
-export const CAPPED_SNAPSHOT_NOTE = 'the page exceeded one snapshot, so controls past the cap were never seen — interactiveFound is a floor, not a total; re-run with a narrower `scope` to cover the rest';
-/**
- * Said out loud when the crawl's OWN clicks put controls on the page that it then never visited.
- *
- * The enumeration happens once, before the first click, so a control that only exists after a login,
- * a modal or a tab switch is invisible to this run. Measured on the bench app: a crawl of the login
- * screen visited three controls, its click on "Sign in" produced seven more, and it returned
- * `truncated: false` with an empty anomaly list and nine of twelve steps unused. Read as a sweep,
- * that is a clean bill of health for an app the crawl never entered.
- *
- * The same words as the capped-snapshot case on purpose — it is the same idea (interactiveFound is a
- * floor) reached by a different route, and a second vocabulary for it would just be more to learn.
- */
-function revealedControlsNote(count) {
-    return (`the page changed as you clicked: ${String(count)} control(s) that did not exist when this crawl ` +
-        'started were never visited — interactiveFound is a floor, not a total; re-run the crawl from ' +
-        'the state you are now in to cover them');
-}
-/** Any buffer event that proves the app reacted to a click (vs a dead/no-op control). */
-function isActivity(e) {
-    return (e.type === EventType.NET_REQUEST ||
-        e.type === EventType.DOM_ADDED ||
-        e.type === EventType.DOM_REMOVED ||
-        e.type === EventType.DOM_ATTR ||
-        e.type === EventType.DOM_TEXT ||
-        e.type === EventType.ROUTE_CHANGE ||
-        e.type === EventType.SIGNAL ||
-        e.type === EventType.ANIM_START ||
-        e.type === EventType.ANIM_END);
-}
-function isConsoleError(e) {
-    return e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT;
-}
-const SOURCE_FRAME = /^(.*):(\d+):(\d+)$/;
-const COMPONENT_STACK_FIELDS = ['componentStack', 'message'];
-const URL_SOURCE_PROTOCOLS = new Set([
-    'http:',
-    'https:',
-    'file:',
-    'webpack:',
-    'webpack-internal:',
-]);
-/** Turn a browser/dev-server frame URL into the file-shaped pointer the rest of Reticle emits. */
-function sourceFile(raw) {
-    let file = raw.trim();
-    if (0 === file.length)
-        return undefined;
-    try {
-        const parsed = new URL(file);
-        if (URL_SOURCE_PROTOCOLS.has(parsed.protocol))
-            file = decodeURIComponent(parsed.pathname);
-    }
-    catch {
-        // A repo-relative or Windows path is already the more useful form; keep it as-is.
-    }
-    file = file.replace(/[?#].*$/, '').replace(/\\/g, '/');
-    const bundledPrefix = file.lastIndexOf('/./');
-    if (-1 !== bundledPrefix)
-        file = file.slice(bundledPrefix + 3);
-    if (file.startsWith('/@fs/'))
-        file = file.slice('/@fs/'.length);
-    if (/^\/[A-Za-z]:\//.test(file))
-        file = file.slice(1);
-    else
-        file = file.replace(/^\/+/, '');
-    if (file.startsWith('./'))
-        file = file.slice(2);
-    return 0 === file.length ? undefined : file;
-}
-/** The location part of a Chrome/React or Firefox stack frame. */
-function frameLocation(line) {
-    let frame = line.trim();
-    if (frame.startsWith('at '))
-        frame = frame.slice(3).trim();
-    else {
-        const firefoxSeparator = frame.lastIndexOf('@');
-        if (-1 === firefoxSeparator)
-            return undefined;
-        frame = frame.slice(firefoxSeparator + 1);
-    }
-    const opening = frame.lastIndexOf('(');
-    if (-1 !== opening && frame.endsWith(')'))
-        return frame.slice(opening + 1, -1);
-    return frame;
-}
-function isFrameworkSource(file) {
-    const normalized = `/${file.toLowerCase().replace(/^\/+/, '')}`;
-    return normalized.includes('/node_modules/') || normalized.startsWith('/node:');
-}
-/** First editable app frame in a component/error stack, excluding framework internals. */
-function sourceFromStack(stack) {
-    for (const line of stack.split('\n')) {
-        const location = frameLocation(line);
-        if (location === undefined)
-            continue;
-        const match = SOURCE_FRAME.exec(location);
-        if (null === match)
-            continue;
-        const [, rawFile, rawLine] = match;
-        if (rawFile === undefined || rawLine === undefined)
-            continue;
-        const file = sourceFile(rawFile);
-        const lineNumber = Number(rawLine);
-        if (file === undefined ||
-            isFrameworkSource(file) ||
-            !Number.isSafeInteger(lineNumber) ||
-            lineNumber <= 0) {
-            continue;
-        }
-        return `${file}:${String(lineNumber)}`;
-    }
-    return undefined;
-}
-/** Prefer where a console fault occurred over the control whose click merely exposed it. */
-function sourceFromConsoleError(event) {
-    // React currently passes its component stack as a console.error string argument, so the browser
-    // observer carries it inside `message`; richer producers can send `componentStack` directly.
-    for (const field of COMPONENT_STACK_FIELDS) {
-        const componentStack = asString(event.data[field]);
-        if (componentStack === undefined)
-            continue;
-        const componentSource = sourceFromStack(componentStack);
-        if (componentSource !== undefined)
-            return componentSource;
-    }
-    // The ordinary error stack can also identify a component better than ErrorEvent.filename (for
-    // example, a bundle or click-handler frame), so try app frames before the structured fallback.
-    const stack = asString(event.data['stack']);
-    if (stack !== undefined) {
-        const stackSource = sourceFromStack(stack);
-        if (stackSource !== undefined)
-            return stackSource;
-    }
-    const directFile = asString(event.data['source']);
-    const directLine = asNumber(event.data['line']);
-    if (directFile === undefined || directLine === undefined || directLine <= 0)
-        return undefined;
-    const file = sourceFile(directFile);
-    return file === undefined || isFrameworkSource(file)
-        ? undefined
-        : `${file}:${String(directLine)}`;
-}
-function failedRequests(events, floor) {
-    return events.filter((e) => {
-        if (e.type !== EventType.NET_REQUEST)
-            return false;
-        const status = asNumber(e.data['status']);
-        return status !== undefined && status >= floor;
-    });
-}
-/**
- * The autonomous "smart monkey". Discovers every reachable interactive control once,
- * then clicks each (bounded by maxSteps) and classifies the reaction into anomalies — console
- * errors, failed requests, and DEAD controls (dispatched but the app did nothing). Pure
- * orchestration over a CrawlSession: no browser/Node imports, fully unit-testable with a fake.
- * Single-pass by design (no re-discovery) so it always terminates and never explodes on navigation.
- */
-/**
- * Controls whose correct behaviour IS to do nothing when clicked.
- *
- * Read off the same descriptor the crawler already has, so no extra round trip: `[disabled]` is inert
- * by definition, an already `[checked]` radio/checkbox is idempotent, and clicking a text field
- * focuses it rather than changing anything.
- */
-export function legitimatelyInert(desc) {
-    if (desc.includes('[disabled]'))
-        return true;
-    if (desc.includes('[checked]'))
-        return true;
-    // Inputs, and the ARIA LIVE-REGION roles.
-    //
-    // `alert`, `status`, `log`, `timer` and `marquee` exist to be READ — a screen reader announces
-    // them and nothing is meant to happen when one is clicked. Clicking twice and seeing nothing is
-    // therefore correct behaviour, and reporting it as `dead-control` accuses a working app.
-    //
-    // Found by driving a real app: the demo reported `dead-control — alert "Invalid email or
-    // password"`, which is a login form correctly telling somebody their password was wrong. That is
-    // the most expensive kind of false positive there is — the strongest claim the crawler makes,
-    // about an app that was working, and on the path a new user meets first.
-    //
-    // `alertdialog` is deliberately NOT here: it is interactive, and a word boundary keeps it out.
-    return /\b(textbox|searchbox|combobox|spinbutton|alert|status|log|timer|marquee)\b/.test(desc);
-}
-/**
- * How many interactive controls exist now that did not exist when the crawl enumerated.
- *
- * Keyed on ref, which is the element's identity: a control that re-rendered keeps its ref and is not
- * new, and one that vanished simply does not appear. Returns 0 rather than throwing if the snapshot
- * fails — this is a disclosure, and failing the whole crawl to report on coverage would be worse
- * than the silence it is fixing.
- */
-async function countRevealed(session, opts, before) {
-    const snap = await session.command(ReticleCommand.SNAPSHOT, {
-        mode: 'interactive',
-        ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
-    });
-    if (!snap.ok)
-        return 0;
-    const tree = (snap.result ?? {}).tree ?? '';
-    const known = new Set(before.map((i) => (i.ref !== '' ? i.ref : i.desc)));
-    return parseInteractive(tree).filter((i) => !known.has(i.ref !== '' ? i.ref : i.desc)).length;
-}
-/**
- * The confirmation half of the dead-control rule. Kept separate so the rule above reads as one
- * question, and so the second click gets its own window: reusing the first would let the first
- * click's own (absent) activity decide the second, which is not a second sample at all.
- *
- * `true` means "silent both times" — the only state the anomaly is reported in. Anything that goes
- * wrong here returns `false`: a confirmation that cannot run is not evidence, and the direction that
- * costs a missed finding is better than the one that invents one.
- */
-async function stillSilent(session, item, settleMs, opts, sleep) {
-    const since = session.elapsed();
-    session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
-    try {
-        const again = await session.command(ReticleCommand.ACT, {
-            ref: item.ref,
-            action: ActionType.CLICK,
-            args: true === opts.confirmDangerous ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
-        });
-        await sleep(settleMs);
-        // A control that has GONE (the first click removed it) is not a dead control — it did something.
-        if (!again.ok || false === asRecord(again.result)['dispatched'])
-            return false;
-        return !session.eventsSince(since).some(isActivity);
-    }
-    catch {
-        return false;
-    }
-    finally {
-        session.finishAction?.();
-    }
-}
-export async function crawl(session, opts, sleep) {
-    const maxSteps = opts.maxSteps ?? CRAWL_DEFAULTS.MAX_STEPS;
-    const settleMs = opts.settleMs ?? CRAWL_DEFAULTS.SETTLE_MS;
-    const snap = await session.command(ReticleCommand.SNAPSHOT, {
-        mode: 'interactive',
-        ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
-    });
-    const snapshot = snap.ok ? (snap.result ?? {}) : {};
-    const tree = snapshot.tree ?? '';
-    const items = parseInteractive(tree);
-    // The snapshot walk stops at its node cap and returns a DOCUMENT-ORDER PREFIX, so on a large page
-    // the controls it never reached are not merely unclicked — they were never seen. Reporting
-    // `interactiveFound` without this would state a control count that is really a cap, and
-    // `truncated:false` would positively assert that nothing was cut.
-    const coverageCapped = true === snapshot.truncated;
-    const anomalies = [];
-    const visited = [];
-    const counts = { consoleErrors: 0, failedRequests: 0, deadControls: 0, contradictions: 0 };
-    const seen = new Set();
-    let stepsRun = 0;
-    for (const item of items) {
-        if (stepsRun >= maxSteps)
-            break;
-        // Dedupe by ref (the unique element), not by label — two "Delete"/"Edit" controls share a desc
-        // but are different controls; collapsing them by label under-covers list/table UIs.
-        const dedupeKey = item.ref !== '' ? item.ref : item.desc;
-        if (seen.has(dedupeKey))
-            continue; // don't re-click the same control
-        seen.add(dedupeKey);
-        stepsRun += 1;
-        visited.push(item.desc);
-        const since = session.elapsed();
-        session.beginAction?.(ReticleTool.CRAWL, { ref: item.ref, action: ActionType.CLICK });
-        let act;
-        /*
-         * A full page load reconnects the SDK, which rejects whatever command was in flight.
-         *
-         * On a server-rendered app that is what following a link DOES — every navigation replaces the
-         * session — so the rejection is evidence the click worked, not that it failed. Crawl used to let
-         * it propagate and died on link one of every Django, Rails or plain-HTML app.
-         *
-         * Recorded as a navigation rather than swallowed: a control that took the page somewhere is the
-         * opposite of a dead one, and reporting it as dead would be the false negative crawl exists to
-         * find.
-         */
-        let navigatedAway = false;
-        try {
-            // One span per control clicked, so a slow crawl names the control rather than reporting a
-            // single multi-second total. The settle sleep below is INSIDE it deliberately: it is part of
-            // what a step costs, and hiding it would make the fixed budget look free.
-            act = await span('crawl.step', { ref: item.ref, desc: item.desc }, async () => {
-                const clicked = await session.command(ReticleCommand.ACT, {
-                    ref: item.ref,
-                    action: ActionType.CLICK,
-                    args: true === opts.confirmDangerous ? { [DANGEROUS_ACTION_CONFIRM_ARG]: true } : {},
-                });
-                await sleep(settleMs);
-                return clicked;
-            });
-        }
-        catch (err) {
-            if (!isSessionReplacedError(err))
-                throw err;
-            navigatedAway = true;
-        }
-        finally {
-            // Close on every exit so a throw cannot leak the window onto the next control's events.
-            session.finishAction?.();
-        }
-        const events = session.eventsSince(since);
-        // Captured at act time, so it survives a click that unmounts its own control.
-        const src = sourceOf(asRecord(act?.result)['source']);
-        const controlSource = src === undefined ? undefined : `${src.file}:${String(src.line)}`;
-        const source = controlSource === undefined ? {} : { source: controlSource };
-        const errs = events.filter(isConsoleError);
-        for (const e of errs) {
-            counts.consoleErrors += 1;
-            const errorSource = sourceFromConsoleError(e) ?? controlSource;
-            anomalies.push({
-                kind: CrawlAnomalyKind.CONSOLE_ERROR,
-                ref: item.ref,
-                desc: item.desc,
-                detail: asString(e.data['message']) ?? e.type,
-                ...(errorSource === undefined ? {} : { source: errorSource }),
-            });
-        }
-        for (const e of failedRequests(events, CRAWL_DEFAULTS.FAILED_STATUS)) {
-            counts.failedRequests += 1;
-            const method = asString(e.data['method']) ?? '';
-            const url = asString(e.data['url']) ?? '';
-            const status = asNumber(e.data['status']);
-            anomalies.push({
-                kind: CrawlAnomalyKind.FAILED_REQUEST,
-                ref: item.ref,
-                desc: item.desc,
-                detail: `${method} ${url} → ${status ?? ''}`.trim(),
-                ...source,
-            });
-        }
-        // CONTRADICTIONS: the channels disagree about what this click did. Reported per control, so a
-        // crawl of an unknown app surfaces its false greens without anyone knowing where to look.
-        // A crawl clicks controls that navigate, so its windows are the ones most likely to straddle a
-        // document boundary — and a finding here is reported against a specific control by name.
-        for (const c of findContradictions(events, {
-            currentDocumentId: session.currentDocumentId,
-            currentEditEpoch: session.currentEditEpoch,
-            appOrigin: session.url,
-            // The crawl's window IS one control's click, so it can name the floor the consequence rules
-            // need — without it a crawl would report nothing about the UI moving, which is most of what a
-            // crawl is for.
-            actionSince: since,
-        })) {
-            counts.contradictions += 1;
-            anomalies.push({
-                kind: c.kind,
-                ref: item.ref,
-                desc: item.desc,
-                detail: `${c.claim}, but ${c.counter} — ${c.detail}`,
-                ...source,
-            });
-        }
-        // DEAD: the click dispatched but the app produced no activity and no error to explain it.
-        //
-        // Unless the control is SUPPOSED to be inert. Measured on a shipments console: every one of the
-        // crawler's three anomalies was a control behaving correctly — a `[disabled]` button, an already
-        // `[checked]` radio, and a text input (a click focuses it; mutating would be the surprise). An
-        // anomaly list that is 100% false on a real app is worse than no anomaly list, because the agent
-        // spends its budget disproving it and learns to skip the field.
-        //
-        // Deliberately NOT fixed by counting focus as activity: focus moving is not the app reacting, and
-        // treating it as such would make a genuinely dead button that takes focus look alive — trading
-        // noise for the false negative this check exists to catch.
-        const dispatched = asRecord(act?.result)['dispatched'] !== false && true === act?.ok;
-        if (
-        // A control that took the page somewhere is the OPPOSITE of a dead one. Without this, every
-        // link on a server-rendered app would be reported as an anomaly by the check that exists to
-        // find controls which do nothing.
-        !navigatedAway &&
-            dispatched &&
-            0 === errs.length &&
-            !events.some(isActivity) &&
-            !legitimatelyInert(item.desc)) {
-            // CONFIRM IT. One silent sample is a sample, not a fact, and this is the strongest claim the
-            // crawler makes — "your button does nothing" is the finding a reader acts on immediately.
-            //
-            // Measured on a fixture whose FIXED twin has a working primary CTA: the crawl reported it dead
-            // on 2 of 3 runs, always a control the drive had already clicked successfully moments earlier.
-            // A false positive in this tier is the most expensive kind there is — it is the tier a verdict
-            // is built from, and the twin column is the whole claim this product makes.
-            //
-            // A second click costs one round trip on the rare control that looked dead, and nothing at all
-            // on every control that did not. A genuinely dead control is silent twice; the flake is not.
-            if (await stillSilent(session, item, settleMs, opts, sleep)) {
-                counts.deadControls += 1;
-                anomalies.push({
-                    kind: CrawlAnomalyKind.DEAD_CONTROL,
-                    ref: item.ref,
-                    desc: item.desc,
-                    detail: 'clicked TWICE and the app did nothing either time (no DOM/network/route/signal change)',
-                    ...source,
-                });
-            }
-        }
-    }
-    // One more look, AFTER the clicks. The enumeration above happened before any of them, so anything
-    // the crawl itself unlocked — a dashboard behind a login, a modal's contents, a tab's panel — was
-    // never in `items` and never had a chance to be visited. Counted by ref against what was
-    // enumerated, so a control that merely moved or re-rendered under the same ref is not miscounted
-    // as new, and a surface that SHRANK (a modal closed) reports nothing, because nothing went
-    // unvisited. Skipped when the snapshot was already capped: that case has its own note and a second
-    // one would only muddy it.
-    const revealed = coverageCapped ? 0 : await countRevealed(session, opts, items);
-    return {
-        interactiveFound: items.length,
-        stepsRun,
-        anomalies,
-        counts,
-        visited,
-        // True when coverage was bounded for EITHER reason: the step budget ran out, or the page was
-        // bigger than one snapshot. Conflating "I stopped early" with "I saw everything" is what turns a
-        // partial sweep into "all controls healthy".
-        truncated: items.length > stepsRun || coverageCapped || revealed > 0,
-        ...(coverageCapped
-            ? { coverageNote: CAPPED_SNAPSHOT_NOTE }
-            : revealed > 0
-                ? { coverageNote: revealedControlsNote(revealed) }
-                : {}),
-        // A bare `stepsRun: 0` made "the page had no controls" and "it had 34 and none were clicked" the
-        // same answer. See crawl-empty.
-        ...(() => {
-            const note = crawlEmptyNote({
-                interactiveFound: items.length,
-                stepsRun,
-                maxSteps,
-                truncated: coverageCapped,
-            });
-            return note === undefined ? {} : { note };
-        })(),
-    };
-}

package/dist/daemon/daemon-resilience.d.ts

@@ -1,74 +0,0 @@
-/**
- * Process-level resilience for the long-running daemon. The daemon serves many agents at once, so a
- * single stray error must not take the whole fleet down:
- *
- * - unhandledRejection (a fire-and-forget promise nobody awaited — the common case in async WS/pool
- * code) → LOG and keep running. One agent's async slip-up can't crash the daemon for everyone.
- * - uncaughtException (a synchronous throw escaped all try/catch) → the process state is undefined
- * per Node's guidance, so LOG a clear reason and exit cleanly; the next `reticle mcp` respawns a fresh
- * daemon, which beats crashing silently or limping along corrupt.
- */
-export interface ProcessLike {
-    on(event: string, listener: (arg: unknown) => void): unknown;
-}
-type LogFn = (event: string, data: Record<string, unknown>) => void;
-/** The two ways a failure reaches the top of the process. Named so the analytics can tell them apart. */
-export declare const CrashKind: {
-    readonly UNHANDLED_REJECTION: "unhandled_rejection";
-    readonly UNCAUGHT_EXCEPTION: "uncaught_exception";
-};
-export type CrashKind = (typeof CrashKind)[keyof typeof CrashKind];
-/**
- * Log EVERY way this process can leave, so a death always leaves a line.
- *
- * Reported from the field: a 115-line daemon log containing zero of `reticle_daemon_idle_exit`,
- * `reticle_daemon_close_error`, `daemon_stopped`, `uncaught` or `unhandled` — the daemon simply
- * stopped existing mid-wait. Both crash handlers below already log before exiting, so their silence
- * ruled themselves out and left nothing else to read: no shutdown path had run at all.
- *
- * `exit` fires for every in-process exit including an explicit `process.exit`, and carries the code.
- * The signals cover an external kill. What neither can catch is SIGKILL or an OOM abort — and that
- * is the point: after this, silence in the log is itself the finding, because every other door is
- * now instrumented.
- */
-/**
- * Why the daemon is going away — carried ON the exit line, not left to be inferred.
- *
- * From the field (#123): a real gate log read `reticle_daemon_signalled SIGTERM` then
- * `reticle_daemon_exiting code:0`, then 21 seconds with nothing listening. `code: 0` is the last
- * line before the port goes dark and it cannot distinguish "shut down tidily" from "the bridge every
- * app on this machine needs is now gone". A correct install was written up as a failure naming the
- * fixture because of it.
- *
- * `UNKNOWN` is the load-bearing member, not a fallback: it means the process left through Node
- * WITHOUT passing a shutdown path — an uncaught throw, a stray `process.exit`. That is a different
- * fact from an idle exit, and the one worth noticing.
- */
-export declare const DaemonExitReason: {
-    /** A shutdown signal arrived (SIGTERM/SIGINT). */
-    readonly SIGNAL: "signal";
-    /** The idle timer fired and the daemon retired itself. */
-    readonly IDLE: "idle";
-    /** Left through Node, but not via any shutdown path we own. */
-    readonly UNKNOWN: "unknown";
-};
-export type DaemonExitReason = (typeof DaemonExitReason)[keyof typeof DaemonExitReason];
-/** Record why the daemon is shutting down. Called by a shutdown path before it exits. */
-export declare function recordExitReason(reason: DaemonExitReason): void;
-export declare function installExitTrace(proc: ProcessLike, log: LogFn): void;
-export declare function installDaemonResilience(proc: ProcessLike, log: LogFn, onFatal: () => void): void;
-/**
- * Process-level resilience for the MCP PROXY, whose rule is the opposite of the daemon's.
- *
- * The daemon exits on an uncaught throw because the next `reticle mcp` respawns it. Nothing respawns
- * the proxy — it is the stdio server the editor launched, and its exit is what the user experiences
- * as "the MCP server disconnected, open /mcp and reconnect". So it logs and keeps serving: its whole
- * state is a socket and a queue, and it already knows how to rebuild both (see the reconnect and
- * dormant paths). A crashed-but-serving proxy answers the handshake and `tools/list` from cache; a
- * dead one answers nothing and needs a human.
- *
- * `onCrash` is for reporting only — it must not end the process. `onGone` is the ONE exception, and
- * it is the subject of DISCONNECT_STORM below.
- */
-export declare function installProxyResilience(proc: ProcessLike, log: LogFn, onCrash?: (kind: CrashKind, cause: unknown) => void, onGone?: () => void): void;
-export {};