@reticlehq/server 3.9.0 → 3.10.0

package/dist/command/update/updater.js

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import { NodePlatform } from '../../machine/platform.js';
+import { PLUGIN_SERVER_DIR } from '../../telemetry/agent-client.js';
 import { existsSync } from 'node:fs';
 import { platform } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -63,6 +64,11 @@ function detectExecutionKind() {
 export function classifyExecutionKind(script) {
     if (script.includes('/_npx/') || script.includes('\\_npx\\'))
         return ExecutionKind.NPX;
+    // The Claude Code plugin's copy sits in a `node_modules`, but it is not the project's. It is pinned
+    // to the plugin version, so treat it as npx: a restart picks the version, and nothing is installed.
+    if (script.includes(`/${PLUGIN_SERVER_DIR}/`) || script.includes(`\\${PLUGIN_SERVER_DIR}\\`)) {
+        return ExecutionKind.NPX;
+    }
     const globalSignals = [
         '/lib/node_modules/',
         '\\npm\\node_modules\\',

package/dist/command/version/version-skew.js

@@ -61,7 +61,7 @@ function namesWeDoNotKnow(peer, self) {
 export const SKEW_CONVERGE = "To put every piece on one version, update the CLI and the app SDK (`reticle update` in the app's " +
     'folder does both), then restart the MCP host.';
 /** The fix for two builds of one version. */
-const SAME_VERSION_FIX = 'Both say the same version, so one of them is an older build of it: run `reticle restart`, then ' +
+const SAME_VERSION_FIX = 'Both say the same version, so one of them is an older build of it: run `reticle serve --restart`, then ' +
     'reload the page so it loads the SDK the dev server serves now.';
 function versionPhrase(peer, self) {
     return peer.version === undefined

package/dist/features/compare/action-plan.d.ts

@@ -0,0 +1,260 @@
+/**
+ * The action plan `reticle compare` drives on each build. Pure: it reads trees and returns steps.
+ *
+ * The plan is made on the reference, breadth first, with no model and no settings:
+ * - the start page, and a wait on the start page;
+ * - the start page with each value of each url parameter the app's scripts read
+ *   (`?scenario=deferred`), up to `MAX_URL_ROOTS`. Each is a start page of its own, with its own
+ *   wait, and opening it does not count toward the depth;
+ * - every single action on every control: click each button, tab, checkbox and option; fill each
+ *   text field with two values chosen by the shape of its value, one edge value of that shape, and
+ *   the values the app's scripts compare the field's name with (`value-dictionary.ts`); select each
+ *   option of a combobox;
+ * - a click on each distinct visible text that has no control role (`- text`, `- generic`), up to
+ *   `MAX_TEXT_PROBES`. A text probe stays in the plan only when it changes the screen on the
+ *   reference: much of the web is a clickable element with no role;
+ * - a press of each common key (`DEFAULT_KEYS`) and of each key the app's scripts compare a key
+ *   event with or name in a shortcut, up to `MAX_KEYS`, each on the start page. A key goes to the
+ *   first element of the page and bubbles to the document. Escape again after each sequence that
+ *   made controls appear: what opened must close;
+ * - each request the app makes fails (`FaultKind`), up to `MAX_FAULT_REQUESTS` requests. A request
+ *   the start page makes on load fails three ways before the page loads. A request an action made
+ *   fails two ways (server, network), and the action's sequence is done again under the fault.
+ *   Files the page is built from are not requests the app makes;
+ * - each click again, followed by a wait, so behaviour on a timer can show. Also each path of two or
+ *   more steps that reached a new screen, followed by a wait. The wait stays in the plan only when
+ *   the reference showed delayed activity there: a call still pending, a page that kept changing
+ *   while it settled, or a change during the wait;
+ * - each single action again under each option of each combobox (a mode, a variant);
+ * - after each sequence, one level deeper into the controls its last action made appear (a menu, a
+ *   dialog): controls that were not on the page before that action;
+ * - on a page with two or more fields: fill every field with its own value, then press each button,
+ *   also a button that is disabled until the fields are filled. When such a press brings new
+ *   fields (the next step of a form, a dialog), fill those and press again, past the depth limit
+ *   up to `MAX_CHAIN` steps. A form step and its own buttons (new with its fields, or disabled
+ *   until they are filled) are planned first, so the cap does not starve them.
+ *   Only this shows a build that takes the start time for the end time.
+ *
+ * The plan explores screens, not paths. Many paths reach one screen, and each path costs a load on
+ * every build. A path of two or more steps that ends on a screen already reached is kept for at most
+ * `MAX_PATHS_PER_SCREEN` paths, and nothing is planned after it. A single action is always kept.
+ *
+ * A control is targeted by its test id when it has one, else by its role and name. Controls with the
+ * same target are numbered in page order, so "fill every field" fills eight fields, not one field
+ * eight times. Every sequence starts from a fresh load of the start page.
+ */
+import { type ValueDictionary } from './outside/value-dictionary.js';
+/** A control on the page, by identity. `nth` counts the controls with the same identity before it. */
+export interface Target {
+    testid?: string;
+    role?: string;
+    name?: string;
+    /** Visible text with no control role: a text probe, clicked by its text. */
+    text?: string;
+    nth: number;
+}
+export type PlanStep = {
+    action: 'click';
+    target: Target;
+} | {
+    action: 'fill';
+    target: Target;
+    value: string;
+} | {
+    action: 'select';
+    target: Target;
+    value: string;
+} | {
+    action: 'wait';
+    ms: number;
+}
+/** Open the start page with this query, such as `?scenario=deferred`: a start page of its own. */
+ | {
+    action: 'goto';
+    query: string;
+}
+/** Press a key on the first element of the page. It bubbles to the document's key listeners. */
+ | {
+    action: 'press';
+    key: string;
+}
+/** Make one request fail, then load the start page again. The steps after it see the fault. */
+ | {
+    action: 'fault';
+    method: string;
+    path: string;
+    fault: FaultKind;
+} | {
+    action: 'fillall';
+    fields: readonly {
+        target: Target;
+        value: string;
+    }[];
+};
+export type Sequence = readonly PlanStep[];
+/**
+ * How a request fails. A failed answer is an input too: the error state, the retry button and the
+ * empty list exist only when a request fails.
+ */
+export declare const FaultKind: {
+    /** The server failed. */
+    readonly SERVER: "500";
+    /** The network failed. */
+    readonly ABORT: "abort";
+    /** The server answered with nothing. */
+    readonly EMPTY: "empty";
+};
+export type FaultKind = (typeof FaultKind)[keyof typeof FaultKind];
+export declare const ControlKind: {
+    readonly CLICK: "click";
+    readonly FILL: "fill";
+    readonly SELECT: "select";
+};
+export type ControlKind = (typeof ControlKind)[keyof typeof ControlKind];
+export interface PlanControl {
+    kind: ControlKind;
+    target: Target;
+    ref?: string;
+    /** The field's value now. Empty for a control that is not a field. */
+    value: string;
+    /** The option labels of a combobox. */
+    options: string[];
+    disabled: boolean;
+}
+/** The most sequences in one plan. Each costs one fresh load on every build. */
+export declare const MAX_SEQUENCES = 220;
+/**
+ * A form chain goes on past `MAX_DEPTH` up to this many steps: fill every field, press a button, and
+ * when the press brought new fields, fill those and press again. A wizard's later steps and a
+ * dialog's submit sit there.
+ */
+export declare const MAX_CHAIN = 8;
+/**
+ * The most text probes in one plan. Much of the web is a clickable element with no role (an
+ * accordion header, a table row), so visible text is clicked too.
+ */
+export declare const MAX_TEXT_PROBES = 40;
+/** The most start pages opened by a url parameter value, in one plan. */
+export declare const MAX_URL_ROOTS = 12;
+/** The most values of one url parameter opened as start pages. */
+export declare const MAX_VALUES_PER_PARAM = 8;
+/**
+ * The most paths of two or more steps kept to one screen. A path to a screen already reached is not
+ * explored further. A single action is always kept: it is a check on the candidate even when it
+ * changes nothing on the reference.
+ */
+export declare const MAX_PATHS_PER_SCREEN = 2;
+/**
+ * The keys a person presses on any page: close, confirm, move focus, move in a list. Each is a check
+ * also where it changes nothing on the reference: a build that answers to the wrong key shows it.
+ */
+export declare const DEFAULT_KEYS: readonly ["Escape", "Enter", "Tab", "ArrowDown", "ArrowUp", "ArrowLeft", "ArrowRight", "Home", "End"];
+/** The most keys pressed on the start page, common keys first. */
+export declare const MAX_KEYS = 24;
+/** The most requests made to fail, in the order the plan first sees them. */
+export declare const MAX_FAULT_REQUESTS = 8;
+/** The wait after a click: a slideshow advances, a countdown ends, a delivery settles. */
+export declare const WAIT_AFTER_CLICK_MS = 4000;
+/** Long text with markup characters and a non-ASCII mark: a build that breaks only on such input. */
+export declare const EDGE_TEXT: string;
+/** The identity of a target, with its number. */
+export declare const targetKey: (t: Target) => string;
+/** The target as a person reads it: `button "Save"`, `[testid=save]`, `button "Open" #2`. */
+export declare const targetLabel: (t: Target) => string;
+/** The controls of a tree, numbered by page order. Options are kept on their combobox. */
+export declare function planControls(tree: string): PlanControl[];
+/**
+ * A click on each distinct visible text that has no control role, in page order, up to
+ * `MAX_TEXT_PROBES`. `dropped` counts the texts past the cap.
+ */
+export declare function textProbes(tree: string): {
+    steps: PlanStep[];
+    dropped: number;
+};
+/** The ref of the first element of the page, where a key press goes. */
+export declare const firstRef: (tree: string) => string | undefined;
+/** The ref of `target` on this tree, or undefined when the tree has no such control. */
+export declare function refFor(tree: string, target: Target): string | undefined;
+/**
+ * Values for a field, by the shape of its value: two that differ from it and from each other, so a
+ * build that mixes up two fields shows a difference, and one edge value of that shape.
+ */
+export declare function valuesFor(value: string): readonly string[];
+/** The single actions on one control. None on a disabled control. */
+export declare function actionsOf(control: PlanControl, dictionary?: ValueDictionary): PlanStep[];
+export declare function stepLabel(step: PlanStep): string;
+/** One key for one sequence, the same on every build. */
+export declare const sequenceKey: (seq: Sequence) => string;
+/** What a probe of one sequence saw. */
+export interface Probe {
+    /** The settled tree after the last step. */
+    tree: string;
+    /** For a sequence that ends in a wait: whether the reference showed delayed activity there. */
+    active: boolean;
+    /** What the app did since the first action, as effect lines: the requests the plan can fail. */
+    effects?: readonly string[];
+}
+/**
+ * What the plan left out because of a cap, so a caller can see that the plan is not every action.
+ * Each count is zero when nothing was left out.
+ */
+export type PlanDropped = {
+    /** Sequences not tried, because the plan reached `MAX_SEQUENCES`. */
+    sequences: number;
+    /** Visible texts not clicked, past `MAX_TEXT_PROBES`. */
+    textProbes: number;
+    /** Url parameter values not opened, past `MAX_VALUES_PER_PARAM` or `MAX_URL_ROOTS`. */
+    urlRoots: number;
+    /** Paths of two or more steps to a screen that `MAX_PATHS_PER_SCREEN` paths already reached. */
+    sameScreenPaths: number;
+    /** Keys not pressed, past `MAX_KEYS`. */
+    keys: number;
+    /** Requests not made to fail, past `MAX_FAULT_REQUESTS`. */
+    faultRequests: number;
+};
+export declare const NOTHING_DROPPED: PlanDropped;
+export interface Plan {
+    sequences: Sequence[];
+    dropped: PlanDropped;
+}
+/** What the app's scripts tell the plan (`value-dictionary.ts`). Each part can be left out. */
+export interface PlanHints {
+    dictionary?: ValueDictionary;
+    /** The values each url parameter is compared with. */
+    urlParams?: ReadonlyMap<string, readonly string[]>;
+    /** The keys the app listens for. */
+    keys?: readonly string[];
+    /** The effect lines of the start page's load: the requests it makes on load. */
+    loadEffects?: readonly string[];
+}
+/** The requests the app made, from effect lines, without the files the page is built from. */
+export declare function requestsIn(lines: readonly string[]): {
+    method: string;
+    path: string;
+}[];
+/**
+ * A start page for each value of each url parameter, up to `MAX_VALUES_PER_PARAM` for one
+ * parameter and `MAX_URL_ROOTS` in all. `dropped` counts the values past the caps.
+ */
+export declare function urlRoots(params: ReadonlyMap<string, readonly string[]>): {
+    steps: PlanStep[];
+    dropped: number;
+};
+/**
+ * A press of each common key, then of each key the app listens for, up to `MAX_KEYS`. `dropped`
+ * counts the keys past the cap.
+ */
+export declare function keyPresses(appKeys: readonly string[]): {
+    steps: PlanStep[];
+    dropped: number;
+};
+/**
+ * Make the plan on the reference. `probe` drives one sequence from a fresh load, or answers
+ * undefined when a step could not be done.
+ */
+export declare function buildPlan(startTree: string, probe: (seq: Sequence) => Promise<Probe | undefined>, hints?: PlanHints): Promise<Plan>;
+/**
+ * The sequences to drive: those that are not the start of another planned sequence. The page is
+ * read after every step of a run, so a run also reads each planned sequence it starts with.
+ */
+export declare function longestRuns(plan: readonly Sequence[]): Sequence[];