@reticlehq/server 3.8.2 → 3.10.0

package/dist/language/flows/replay.js

@@ -1,9 +1,10 @@
 import { SECRET_FIELD_ARG, SECRET_NAME_ARG, secretKeyForFill, secretValue, } from './fields/flow-secret-field.js';
-import { EventType, FlowPredicateSchema, MUTATING_METHODS, Verified, isDevToolingUrl, pathOf, } from '@reticlehq/core';
+import { EventType, FlowPredicateSchema, MUTATING_METHODS, isDevToolingUrl, } from '@reticlehq/core';
 import { DANGEROUS_ACTION_CONFIRM_ARG, DOCUMENT_ANCHOR_ROLE, ReticleCommand, QueryBy, isGlobalPressCall, } from '@reticlehq/core';
 import { ReticleTool, invokedFlowMissing } from '@reticlehq/core';
 import { formatStepAddress } from 'open-verification';
 import { refFor } from './flow-anchor.js';
+import { navigablePath, routeOfUrl } from '@reticlehq/engine/question/predicate/predicate-route.js';
 import { asRecord, asString } from '@reticlehq/core';
 /**
  * The note attached when a testid resolves to multiple live elements (the first match is used).
@@ -21,9 +22,36 @@ function ambiguousRoleNote(role, name) {
  * replay engines (replayProgram + flow-replay's step runner) so element extraction — the core of anchor
  * resolution — can't drift between them.
  */
+/**
+ * The refs of a role query's matches that have NO accessible name, in page order.
+ *
+ * A role query without a name returns every control of the role, named ones included. A nameless
+ * anchor's recorded position (`nth` of `of`) counts only the nameless ones — an icon-only edit
+ * button is the 2nd nameless button of its row, not the 5th button — so the named ones are dropped
+ * before the position is read.
+ */
+export function namelessRefs(result) {
+    if (!result.ok) {
+        return [];
+    }
+    const elements = asRecord(result.result)['elements'];
+    if (!Array.isArray(elements)) {
+        return [];
+    }
+    const refs = [];
+    for (const element of elements) {
+        const e = asRecord(element);
+        const ref = asString(e['ref']);
+        if (0 === (asString(e['name']) ?? '').trim().length && ref !== undefined) {
+            refs.push(ref);
+        }
+    }
+    return refs;
+}
 export function queryRefs(result) {
-    if (!result.ok)
+    if (!result.ok) {
         return [];
+    }
     const payload = asRecord(result.result);
     const elements = Array.isArray(payload['elements']) ? payload['elements'] : [];
     return elements.map((e) => asString(asRecord(e)['ref']) ?? '').filter((r) => r.length > 0);
@@ -47,12 +75,14 @@ export function replayActionArgs(value, confirmDangerous = false, field) {
     const key = field === undefined ? undefined : secretKeyForFill(args, field);
     delete args[SECRET_NAME_ARG];
     delete args[SECRET_FIELD_ARG];
-    if (confirmDangerous)
+    if (confirmDangerous) {
         args[DANGEROUS_ACTION_CONFIRM_ARG] = true;
+    }
     if (key !== undefined) {
         const supplied = secretValue(key, process.env);
-        if (supplied !== undefined && supplied.length > 0)
+        if (supplied !== undefined && supplied.length > 0) {
             args['value'] = supplied;
+        }
     }
     return args;
 }
@@ -62,37 +92,52 @@ export function replayActionArgs(value, confirmDangerous = false, field) {
  */
 function recordedFieldName(step) {
     const by = asString(step['by']);
-    if (QueryBy.TESTID === by)
+    if (QueryBy.TESTID === by) {
         return asString(step['value']);
-    if (QueryBy.ROLE === by)
+    }
+    if (QueryBy.ROLE === by) {
         return asString(step['name']);
+    }
     return undefined;
 }
 /** The element's source location from an action result, when the framework stamped one. */
 function sourceFromResult(res) {
     const source = asRecord(res['source']);
-    if (typeof source['file'] !== 'string' || typeof source['line'] !== 'number')
+    if (typeof source['file'] !== 'string' || typeof source['line'] !== 'number') {
         return undefined;
+    }
     const out = { file: source['file'], line: source['line'] };
-    if ('number' === typeof source['column'])
+    if ('number' === typeof source['column']) {
         out['column'] = source['column'];
+    }
     return out;
 }
 /**
- * The pathname of a session's live url, or undefined when it has none yet.
+ * The page a session's live url is on, as a NAVIGABLE path: pathname + query + hash, with
+ * Reticle's own params dropped. Undefined when the session has no url yet.
  *
- * Pathname rather than the whole url, because that is what `startPath` is compared against and what
- * a hash-routed app makes meaningless in the document location — see routeOfEvent.
+ * Every recorded page comes from here: a step's page, the route a tape is cut on, and the
+ * `startPath` and route `requires` of a saved flow. The pathname alone dropped the query, so a
+ * journey leased on `/?showModal=login` saved `startPath: "/"`, and its replay asserted "the modal
+ * is absent" on a page where the modal never opens. Under a hash router it dropped the hash too,
+ * which made every page `/` (#1411).
  */
-export { pathOf };
+export function pageOf(url) {
+    if (url === undefined) {
+        return undefined;
+    }
+    const parts = routeOfUrl(url);
+    return parts === undefined ? undefined : navigablePath(parts);
+}
 /**
  * Did the app send a write request in this window? A step that did is saved `writes: true`, so a
  * replay does not repeat it unasked. The dev server's own traffic is not the app's.
  */
 export function wroteIn(events) {
     return events.some((event) => {
-        if (EventType.NET_REQUEST !== event.type)
+        if (EventType.NET_REQUEST !== event.type) {
             return false;
+        }
         const method = asString(event.data['method'])?.toUpperCase() ?? '';
         return MUTATING_METHODS.includes(method) && !isDevToolingUrl(asString(event.data['url']));
     });
@@ -122,7 +167,9 @@ route,
 /** The session that acted: only recordings it started take the step. */
 session, 
 /** The act's window sent a write request; see `wroteIn`. */
-wrote = false) {
+wrote = false, 
+/** The act as the ambient tape keeps it, when that differs. See RecordingStore.capture. */
+ambientArgs) {
     // NO `active()` gate. `RecordingStore.capture` opens the AMBIENT tape on its first step, and that
     // branch was unreachable from here: this returned early whenever nothing was open, and the only
     // thing that opened anything was `reticle_record { action: "start" }`. So the comment on `capture`
@@ -134,8 +181,15 @@ wrote = false) {
     // recorded cannot contribute to either.
     // A click on Reticle's own panel (the HUD exposed) is not a step of the app's journey: saved, the
     // app's flow pressed Run Harness on replay, a paid drive, under an intent that never named it.
-    if (true === asRecord(res)['reticleUi'])
+    if (true === asRecord(res)['reticleUi']) {
         return;
+    }
+    const step = capturedStep(args, res, route, wrote);
+    const ambient = ambientArgs === undefined ? undefined : capturedStep(ambientArgs, res, route, wrote);
+    recordings.capture(step, route, session, ambient);
+}
+/** One act as a recorded step, with the claim the agent declared on it. */
+function capturedStep(args, res, route, wrote) {
     const step = compileActStep(args, res);
     // Keep the assertion the agent actually made. `act_and_wait { until }` IS the agent saying what
     // success means — the large majority of calls carry one — and dropping it produced a flow graded
@@ -143,36 +197,50 @@ wrote = false) {
     // story failing at its last step. See enforceableExpect below.
     const declared = args['until'] ?? args['predicate'];
     const expect = enforceableExpect(declared);
-    if (expect !== undefined)
+    if (expect !== undefined) {
         step.expect = expect;
-    else if (declared !== undefined)
+    }
+    else if (declared !== undefined) {
         step.unkeptExpect = UNKEPT_EXPECT;
-    if (route !== undefined)
+    }
+    if (route !== undefined) {
         step.page = route;
+    }
     const intent = asString(args['intent'])?.trim();
-    if (intent !== undefined && intent.length > 0)
+    if (intent !== undefined && intent.length > 0) {
         step.intent = intent;
-    if (wrote)
+    }
+    if (wrote) {
         step.writes = true;
-    recordings.capture(step, route, session);
+    }
+    return step;
 }
 /**
- * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
- * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
- * a regression test asserting something never once observed to hold because of the action. The
- * action itself is always recorded: it happened, and replay needs it to reach the next step.
+ * Capture an act_and_wait once its verdict is known.
+ *
+ * The rule act_sequence keeps (#988). A recording somebody opened keeps every claim the agent
+ * declared, held or not: dropping a refuted one saved a flow that replayed green on the defect it
+ * had caught. The ambient tape keeps a claim only if the action made it hold (`held`), so a flow cut
+ * from it never replays a claim that was never once true because of the action. The action is
+ * always recorded: replay needs it to reach the next step.
+ *
+ * Keyed on `held`, not on `verified: yes`. A claim the action made hold under an `unknown` or a
+ * contradicted verdict is still what the agent proved about the page, and dropping it left the
+ * replay with no check at all. One function decides both tapes: a second rule that took the claim off the tape
+ * after the fact ran before this capture, so it took the PREVIOUS step's claim, which had passed.
  */
-export function captureVerdictedAct(recordings, args, res, route, verified, session, 
+export function captureVerdictedAct(recordings, args, res, route, held, session, 
 /** The act's window sent a write request; see `wroteIn`. */
 wrote = false) {
     const { until: _until, predicate: _predicate, ...unproved } = args;
-    captureAct(recordings, Verified.YES === verified ? args : unproved, res, route, session, wrote);
+    captureAct(recordings, args, res, route, session, wrote, held ? undefined : unproved);
 }
 /** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
 export function captureAssertion(recordings, raw, session) {
     const expect = enforceableExpect(raw);
-    if (expect !== undefined)
+    if (expect !== undefined) {
         recordings.attachExpect(expect, session);
+    }
 }
 /**
  * A declared predicate, as a recorded expectation — or nothing.
@@ -186,8 +254,9 @@ export function captureAssertion(recordings, raw, session) {
  * Every one of those was a claim the agent made and the file did not keep.
  */
 function enforceableExpect(raw) {
-    if (raw === undefined)
+    if (raw === undefined) {
         return undefined;
+    }
     // The flow file's own schema, so capture keeps exactly what a load would accept — a predicate
     // holding a session ref is refused by both, rather than recorded here and rejected on read.
     const parsed = FlowPredicateSchema.safeParse(raw);
@@ -232,8 +301,9 @@ function compileAnchorArgs(r, ref, action, actArgs) {
     const compiled = anchorArgs(r, ref, action, actArgs);
     // The SDK says the target holds a secret (a password input, whatever its label). Carried beside
     // the anchor so the saved flow redacts the fill by what the field IS, not by what it is called.
-    if (true === r['secret'])
+    if (true === r['secret']) {
         compiled.args[SECRET_FIELD_ARG] = true;
+    }
     return compiled;
 }
 function anchorArgs(r, ref, action, actArgs) {
@@ -262,10 +332,15 @@ function anchorArgs(r, ref, action, actArgs) {
             action,
             args: actArgs,
         };
-        if (source !== undefined)
+        if (source !== undefined) {
             testidArgs['source'] = source;
-        if (testidOf !== undefined)
+        }
+        if (testidOf !== undefined) {
             testidArgs['of'] = testidOf;
+            if ('number' === typeof r['testidNth'] && 0 <= r['testidNth']) {
+                testidArgs['nth'] = r['testidNth'];
+            }
+        }
         return { args: testidArgs, stable: true };
     }
     // Role + NAME before component: a component/source anchor names the JSX site, so every row's copy
@@ -282,21 +357,64 @@ function anchorArgs(r, ref, action, actArgs) {
             action,
             args: actArgs,
         };
-        if (source !== undefined)
+        if (source !== undefined) {
             roleArgs['source'] = source;
+        }
         if ('number' === typeof r['nth'] && 'number' === typeof r['of']) {
             roleArgs['nth'] = r['nth'];
             roleArgs['of'] = r['of'];
         }
+        if (Array.isArray(r['within'])) {
+            roleArgs['within'] = r['within'];
+        }
         return { args: roleArgs, stable: true };
     }
+    // A role and NO accessible name (an icon-only button): the role plus the control's position among
+    // the nameless controls of that role. Without this branch the step fell to a component anchor or
+    // to the stale ref, and a replay on a fresh page could not find the control again.
+    if (role !== undefined &&
+        role !== 'generic' &&
+        name === undefined &&
+        asString(r['component']) === undefined) {
+        const namelessArgs = {
+            by: QueryBy.ROLE,
+            value: role,
+            action,
+            args: actArgs,
+        };
+        if (source !== undefined) {
+            namelessArgs['source'] = source;
+        }
+        if ('number' === typeof r['nth'] && 'number' === typeof r['of']) {
+            namelessArgs['nth'] = r['nth'];
+            namelessArgs['of'] = r['of'];
+        }
+        return { args: namelessArgs, stable: true };
+    }
     const component = asString(r['component']);
     if (component !== undefined || source !== undefined) {
         const componentArgs = { by: QueryBy.COMPONENT, action, args: actArgs };
-        if (component !== undefined)
+        if (component !== undefined) {
             componentArgs['component'] = component;
-        if (source !== undefined)
+        }
+        if (source !== undefined) {
             componentArgs['source'] = source;
+        }
+        // Which of the elements this anchor matches was acted on: a list renders every item from one site.
+        // The element's own words, when it has no accessible name: they survive a change of layout.
+        const ownText = asString(r['ownText']);
+        if (ownText !== undefined && ownText.length > 0) {
+            componentArgs['text'] = ownText;
+        }
+        // The role, too: a nameless control with no own words has no other identity a layout keeps.
+        const role = asString(r['role']);
+        if (role !== undefined && role.length > 0) {
+            componentArgs['role'] = role;
+        }
+        if ('number' === typeof r['componentNth'] && 'number' === typeof r['componentOf']) {
+            componentArgs['nth'] = r['componentNth'];
+            componentArgs['of'] = r['componentOf'];
+        }
         return { args: componentArgs, stable: true };
     }
     return { args: { ref, action, args: actArgs }, stable: false };
@@ -312,26 +430,38 @@ export function compileSequenceStep(args, res) {
         ? asRecord(res)['steps']
         : [];
     let stable = inputSteps.length > 0;
+    // A declared `expect` that a flow cannot keep (a session ref), said on save as for a single act (#2188).
+    let unkept = false;
     const subSteps = inputSteps.flatMap((raw, i) => {
         // A step on Reticle's own panel is not a step of the app's journey, as for a single act.
-        if (true === asRecord(resolved[i])['reticleUi'])
+        if (true === asRecord(resolved[i])['reticleUi']) {
             return [];
+        }
         const step = asRecord(raw);
         const compiled = compileAnchorArgs(asRecord(resolved[i]), asString(step['ref']) ?? '', asString(step['action']) ?? '', replayActionArgs(step['args']));
-        if (!compiled.stable)
+        if (!compiled.stable) {
             stable = false;
+        }
         // Each sub-step keeps its OWN declared consequence. A sequence records one step and replays as
         // one batch, but what each step CLAIMED is per step -- folding them together would let one
         // signal answer for every click in the journey.
         const expect = enforceableExpect(step['expect']);
+        if (expect === undefined && step['expect'] !== undefined) {
+            unkept = true;
+        }
         return [expect === undefined ? compiled.args : { ...compiled.args, expect }];
     });
     const timeoutMs = explicitTimeoutMs(args);
+    // The pace is part of what the sequence did: replay at the default settle answered differently (#2130).
+    const burst = args['burst'];
+    const burstMs = 'number' === typeof burst && Number.isFinite(burst) && 0 <= burst ? burst : undefined;
     return {
         tool: ReticleTool.ACT_SEQUENCE,
         stable,
         args: { steps: subSteps },
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(burstMs === undefined ? {} : { burstMs }),
+        ...(unkept ? { unkeptExpect: UNKEPT_EXPECT } : {}),
     };
 }
 /**
@@ -346,18 +476,21 @@ export function compileSequenceStep(args, res) {
  */
 async function resolveRef(session, step) {
     // Dispatched the way it ran live: at the document, with no ref. See compileAnchorArgs.
-    if (isDocumentPress(step))
+    if (isDocumentPress(step)) {
         return { ref: '' };
+    }
     const by = asString(step.by);
     const value = asString(step.value);
     if (by === QueryBy.TESTID && value !== undefined) {
         const result = await session.command(ReticleCommand.QUERY, { by, value });
-        if (!result.ok)
+        if (!result.ok) {
             throw new Error(result.error ?? 'query failed');
+        }
         const refs = queryRefs(result);
         const ref = refs[0];
-        if (ref === undefined)
+        if (ref === undefined) {
             throw new Error(`testid '${value}' did not resolve in current page`);
+        }
         return refs.length > 1 ? { ref, note: ambiguousTestidNote(value) } : { ref };
     }
     // Role + accessible NAME: the anchor that distinguishes one row's control from another's, which
@@ -366,13 +499,16 @@ async function resolveRef(session, step) {
         const name = asString(step.name);
         const query = { by, value, ...(name === undefined ? {} : { name }) };
         const result = await session.command(ReticleCommand.QUERY, query);
-        if (!result.ok)
+        if (!result.ok) {
             throw new Error(result.error ?? 'query failed');
-        const refs = queryRefs(result);
+        }
+        const refs = name === undefined ? namelessRefs(result) : queryRefs(result);
         const meant = refFor(step, refs);
         const ref = meant ?? refs[0];
         if (ref === undefined) {
-            throw new Error(`${value} named '${String(name)}' did not resolve in current page`);
+            throw new Error(name === undefined
+                ? `no ${value} with no accessible name resolved in current page`
+                : `${value} named '${String(name)}' did not resolve in current page`);
         }
         return meant === undefined ? { ref, note: ambiguousRoleNote(value, String(name)) } : { ref };
     }
@@ -385,8 +521,9 @@ async function resolveRef(session, step) {
             ...(source === undefined ? {} : { source }),
         };
         const result = await session.command(ReticleCommand.QUERY, query);
-        if (!result.ok)
+        if (!result.ok) {
             throw new Error(result.error ?? 'query failed');
+        }
         const refs = queryRefs(result);
         const ref = refs[0];
         if (ref === undefined) {
@@ -468,8 +605,9 @@ via = []) {
                 ...via,
             ]);
             results.push(...nested);
-            if (nested.some((r) => !r.ok))
+            if (nested.some((r) => !r.ok)) {
                 break;
+            }
             continue;
         }
         try {
@@ -480,8 +618,9 @@ via = []) {
                 for (const raw of subs) {
                     const sub = asRecord(raw);
                     const { ref, note } = await resolveRef(session, sub);
-                    if (note !== undefined)
+                    if (note !== undefined) {
                         notes.push(note);
+                    }
                     liveSteps.push({
                         ref,
                         action: asString(sub['action']) ?? '',
@@ -502,8 +641,9 @@ via = []) {
                     session.finishAction();
                 }
                 results.push(buildResult(step.tool, r.ok, r.error, notes));
-                if (!r.ok)
+                if (!r.ok) {
                     break;
+                }
             }
             else {
                 const { ref, note } = await resolveRef(session, step.args);
@@ -520,8 +660,9 @@ via = []) {
                     session.finishAction();
                 }
                 results.push(buildResult(step.tool, r.ok, r.error, note !== undefined ? [note] : []));
-                if (!r.ok)
+                if (!r.ok) {
                     break;
+                }
             }
         }
         catch (e) {
@@ -537,9 +678,11 @@ via = []) {
 }
 function buildResult(tool, ok, error, notes) {
     const base = { tool, ok };
-    if (!ok)
+    if (!ok) {
         base.error = error ?? 'command failed';
-    if (notes.length > 0)
+    }
+    if (notes.length > 0) {
         base.note = notes.join('; ');
+    }
     return base;
 }

package/dist/language/flows/steps/page-steps.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Steps that reach past the page the journey is on: one opens another page (`navigate`), one sends a
+ * request to the app (`request`). Neither acts on an element, and both depend on a caller that owns
+ * what the replay cannot reach by itself: the sessions, the origin, the cookies.
+ */
+import { type Drift, type FlowRequest, type FlowStep, type FlowStepResult } from '@reticlehq/core';
+/**
+ * Opens the page a `navigate` step names and returns the session of the page that loaded, or why no
+ * page of the app answered. A full page load ends the session that asked for it, so only the caller
+ * that owns the sessions can do this.
+ */
+export type OpenPage<S> = (url: string) => Promise<{
+    session: S;
+} | {
+    error: string;
+}>;
+/**
+ * Sends the request a `request` step names and returns the answer, or why nothing could be sent.
+ * Supplied by the caller that knows the app's origin and the page's cookies.
+ */
+export type SendRequest = (request: FlowRequest) => Promise<{
+    status: number;
+    body: string;
+} | {
+    error: string;
+}>;
+/** Where the page's cookies come from: the driven browser's storage state. */
+interface CookieSource {
+    storageState?(sessionUrl: string): Promise<unknown>;
+}
+/** The step's result before its `expect` is judged, and the session to go on with. */
+export declare function openStepPage<S>(step: FlowStep, index: number, open: OpenPage<S> | undefined): Promise<{
+    result: FlowStepResult;
+    session?: S;
+}>;
+export declare function runRequestStep(step: FlowStep, index: number, send: SendRequest | undefined, judged: boolean, 
+/**
+ * The run's own yes to steps that change data, never the flow file's: flow files are shared, and a
+ * saved `DELETE` would otherwise run with the user's cookies on any app the flow is pointed at.
+ */
+confirmDangerous: boolean): Promise<FlowStepResult>;
+/** True for a step that reaches past the page: `navigate` or `request`. */
+export declare function isPageStep(step: FlowStep): boolean;
+/**
+ * Run a `navigate` or `request` step. `judge` evaluates an `expect` on a page; it comes from the
+ * replay so this file does not import the replay back. `checked` is false for a setup step, whose
+ * consequence is not checked. A navigate step returns the session to go on with.
+ */
+export declare function runPageStep<S>(step: FlowStep, index: number, ctx: {
+    open?: OpenPage<S> | undefined;
+    send?: SendRequest | undefined;
+    checked: boolean;
+    confirmDangerous: boolean;
+    judge: (session: S, expect: NonNullable<FlowStep['expect']>) => Promise<Drift | undefined>;
+    route: (session: S) => string | undefined;
+}): Promise<{
+    result: FlowStepResult;
+    session?: S;
+}>;
+/**
+ * The sender a `request` step uses: same origin as the page only, the page's cookies unless the step
+ * is anonymous, no redirects followed (a 302 is the answer to judge). `pageUrl` is read at send time,
+ * because a `navigate` step changes the page.
+ */
+export declare function requestSender(pageUrl: () => string | undefined, provider: CookieSource | undefined, 
+/** The `Cookie` header of the account a step names in `as`, or undefined when not supplied. */
+accountCookie?: (name: string) => string | undefined): SendRequest;
+export {};