@reticlehq/test 2.0.0

package/dist/input-mode.js

@@ -0,0 +1,64 @@
+import { ReticleTool } from '@reticlehq/server';
+import { InputMode } from '@reticlehq/core';
+import { ReticleSkip } from './skip.js';
+import { SKIP_REASON_REAL_INPUT } from './constants.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** The act envelope's inputMode field, narrowed from the raw tool result. */
+export function readInputMode(actResult) {
+    if (typeof actResult !== 'object' || actResult === null)
+        return undefined;
+    const mode = actResult['inputMode'];
+    if (mode === InputMode.REAL || mode === InputMode.SYNTHETIC)
+        return mode;
+    return undefined;
+}
+/**
+ * Tracks the most recent act's inputMode across a spec so `expectInputModeReal()` can read it
+ * without re-touching the page. The context records every act through `record`.
+ */
+export class InputModeTracker {
+    last;
+    record(actResult) {
+        const mode = readInputMode(actResult);
+        if (mode !== undefined)
+            this.last = mode;
+    }
+    get() {
+        return this.last;
+    }
+}
+/**
+ * Assert real native input is active. Prefers the last act's reported mode (zero extra page
+ * mutation); if no act has run, issues a non-mutating SCROLL_INTO_VIEW probe and reads its mode.
+ * On 'synthetic' throws ReticleSkip(SKIP_REASON_REAL_INPUT) — the runner turns this into status:'skip'.
+ * It NEVER silently passes on synthetic.
+ */
+export async function expectInputModeReal(invoke, tracker, sessionId) {
+    let mode = tracker.get();
+    if (mode === undefined) {
+        mode = await probeInputMode(invoke, sessionId);
+    }
+    if (mode !== InputMode.REAL) {
+        throw new ReticleSkip(SKIP_REASON_REAL_INPUT);
+    }
+}
+/**
+ * Read whether native real input is active for the session WITHOUT touching the page: reticle_sessions
+ * reports `realInputAvailable` per session (true when a CDP/launched provider matches the tab url).
+ * App-agnostic — no assumed testid.
+ */
+async function probeInputMode(invoke, sessionId) {
+    const result = await invoke(ReticleTool.SESSIONS, {});
+    const sessions = isRecord(result) && Array.isArray(result['sessions']) ? result['sessions'] : [];
+    for (const session of sessions) {
+        if (!isRecord(session))
+            continue;
+        if (sessionId === undefined || session['sessionId'] === sessionId) {
+            return session['realInputAvailable'] === true ? InputMode.REAL : InputMode.SYNTHETIC;
+        }
+    }
+    return InputMode.SYNTHETIC;
+}
+//# sourceMappingURL=input-mode.js.map

package/dist/input-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-mode.js","sourceRoot":"","sources":["../src/input-mode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,SAAkB;IAC9C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC1E,MAAM,IAAI,GAAI,SAAqC,CAAC,WAAW,CAAC,CAAC;IACjE,IAAI,IAAI,KAAK,SAAS,CAAC,IAAI,IAAI,IAAI,KAAK,SAAS,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACzE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACnB,IAAI,CAAwB;IAEpC,MAAM,CAAC,SAAkB;QACvB,MAAM,IAAI,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAC3C,CAAC;IAED,GAAG;QACD,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAmB,EACnB,OAAyB,EACzB,SAAkB;IAElB,IAAI,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IACzB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,WAAW,CAAC,sBAAsB,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,cAAc,CAAC,MAAmB,EAAE,SAAkB;IACnE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjG,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACjC,IAAI,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,CAAC,KAAK,SAAS,EAAE,CAAC;YAClE,OAAO,OAAO,CAAC,oBAAoB,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC;QACvF,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC,SAAS,CAAC;AAC7B,CAAC"}

package/dist/junit.d.ts

@@ -0,0 +1,11 @@
+import type { FileSystemPort } from '@reticlehq/server';
+import type { SpecResult } from './types.js';
+/** Render results as a single JUnit `<testsuite>` document (CI consumable). */
+export declare function toJUnitXml(results: readonly SpecResult[], opts?: {
+    suite?: string;
+}): string;
+/** Write the JUnit report through the injected filesystem seam (tests pass a fake adapter). */
+export declare function writeJUnit(fs: FileSystemPort, path: string, results: readonly SpecResult[], opts?: {
+    suite?: string;
+}): Promise<void>;
+//# sourceMappingURL=junit.d.ts.map

package/dist/junit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"junit.d.ts","sourceRoot":"","sources":["../src/junit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA+B7C,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAU5F;AAED,+FAA+F;AAC/F,wBAAsB,UAAU,CAC9B,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxB,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/junit.js

@@ -0,0 +1,43 @@
+import { DEFAULT_JUNIT_SUITE_NAME, JUnit, TestStatus } from './constants.js';
+import { summarize } from './summary.js';
+/** Escape the five XML-significant characters in attribute values + text. */
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function seconds(ms) {
+    return (ms / 1000).toFixed(3);
+}
+function caseXml(r) {
+    const open = `  <${JUnit.CASE} ${JUnit.ATTR_NAME}="${escapeXml(r.name)}" ` +
+        `${JUnit.ATTR_TIME}="${seconds(r.durationMs)}">`;
+    if (r.status === TestStatus.FAIL) {
+        const msg = escapeXml(r.error ?? '');
+        return `${open}\n    <${JUnit.FAILURE} ${JUnit.ATTR_MESSAGE}="${msg}"></${JUnit.FAILURE}>\n  </${JUnit.CASE}>`;
+    }
+    if (r.status === TestStatus.SKIP) {
+        const msg = escapeXml(r.skipReason ?? '');
+        return `${open}\n    <${JUnit.SKIPPED} ${JUnit.ATTR_MESSAGE}="${msg}"></${JUnit.SKIPPED}>\n  </${JUnit.CASE}>`;
+    }
+    return `${open}</${JUnit.CASE}>`;
+}
+/** Render results as a single JUnit `<testsuite>` document (CI consumable). */
+export function toJUnitXml(results, opts) {
+    const suite = escapeXml(opts?.suite ?? DEFAULT_JUNIT_SUITE_NAME);
+    const s = summarize(results);
+    const header = `<${JUnit.SUITE} ${JUnit.ATTR_NAME}="${suite}" ` +
+        `${JUnit.ATTR_TESTS}="${String(s.total)}" ` +
+        `${JUnit.ATTR_FAILURES}="${String(s.failed)}" ` +
+        `${JUnit.ATTR_SKIPPED}="${String(s.skipped)}">`;
+    const body = results.map(caseXml).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>\n${header}\n${body}\n</${JUnit.SUITE}>\n`;
+}
+/** Write the JUnit report through the injected filesystem seam (tests pass a fake adapter). */
+export async function writeJUnit(fs, path, results, opts) {
+    await fs.writeFile(path, toJUnitXml(results, opts));
+}
+//# sourceMappingURL=junit.js.map

package/dist/junit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"junit.js","sourceRoot":"","sources":["../src/junit.ts"],"names":[],"mappings":"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"}

package/dist/matchers.d.ts

@@ -0,0 +1,26 @@
+import { type ToolInvoker } from '@reticlehq/server';
+import type { ElementQuery, ElementState } from '@reticlehq/core';
+/** The verdict envelope returned by reticle_assert / the `verdict` field of reticle_act_and_wait. */
+export interface Verdict {
+    pass: boolean;
+    evidence?: unknown;
+    failureReason?: string;
+}
+/**
+ * Throw an ReticleAssertionError carrying the verdict's own evidence + failureReason. Used by every
+ * `expect*` matcher and by actAndWait, so the runner's single catch boundary marks fail with the
+ * predicate engine's structured diagnosis intact. `extraEvidence` lets actAndWait attach its trace.
+ */
+export declare function failFromVerdict(verdict: Verdict, extraEvidence?: Record<string, unknown>): never;
+export interface MatcherDeps {
+    invoke: ToolInvoker;
+    timeoutMs?: number;
+    sessionId?: string;
+}
+export declare function expectSignal(deps: MatcherDeps, name: string, dataMatches?: Record<string, unknown>): Promise<void>;
+export declare function expectNet(deps: MatcherDeps, method: string, urlContains: string, status?: number): Promise<void>;
+export declare function expectElement(deps: MatcherDeps, query: ElementQuery, state?: ElementState): Promise<void>;
+export declare function expectText(deps: MatcherDeps, contains: string): Promise<void>;
+export declare function expectAbsent(deps: MatcherDeps, query: ElementQuery): Promise<void>;
+export declare function expectNoConsoleErrors(deps: MatcherDeps): Promise<void>;
+//# sourceMappingURL=matchers.d.ts.map

package/dist/matchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.d.ts","sourceRoot":"","sources":["../src/matchers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIlE,qGAAqG;AACrG,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAiBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAchG;AAkBD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAgB,SAAS,CACvB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,YAAY,EACnB,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG7E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtE"}

package/dist/matchers.js

@@ -0,0 +1,95 @@
+import { ReticleTool } from '@reticlehq/server';
+import { ReticleAssertionError } from './skip.js';
+import { CONSOLE_LEVEL_ERROR, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind } from './constants.js';
+function asVerdict(value) {
+    if (typeof value !== 'object' || value === null) {
+        return { pass: false, failureReason: 'assert returned a non-object result' };
+    }
+    const record = value;
+    const pass = record['pass'] === true;
+    const failureReason = typeof record['failureReason'] === 'string' ? record['failureReason'] : undefined;
+    return {
+        pass,
+        evidence: record['evidence'],
+        ...(failureReason !== undefined ? { failureReason } : {}),
+    };
+}
+/**
+ * Throw an ReticleAssertionError carrying the verdict's own evidence + failureReason. Used by every
+ * `expect*` matcher and by actAndWait, so the runner's single catch boundary marks fail with the
+ * predicate engine's structured diagnosis intact. `extraEvidence` lets actAndWait attach its trace.
+ */
+export function failFromVerdict(verdict, extraEvidence) {
+    const message = verdict.failureReason ?? 'assertion failed';
+    // actAndWait passes extra context (the reaction trace); merge it alongside the verdict evidence.
+    const evidence = extraEvidence !== undefined
+        ? {
+            ...extraEvidence,
+            ...(verdict.evidence !== undefined ? { evidence: verdict.evidence } : {}),
+        }
+        : verdict.evidence;
+    throw new ReticleAssertionError(message, {
+        ...(evidence !== undefined ? { evidence } : {}),
+        ...(verdict.failureReason !== undefined ? { failureReason: verdict.failureReason } : {}),
+    });
+}
+/** Run reticle_assert for a predicate; resolve on pass, throw the structured failure otherwise. */
+async function assertPredicate(invoke, predicate, timeoutMs, sessionId) {
+    const args = {
+        predicate,
+        timeout_ms: timeoutMs,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+    };
+    const verdict = asVerdict(await invoke(ReticleTool.ASSERT, args));
+    if (!verdict.pass)
+        failFromVerdict(verdict);
+}
+function timeout(deps) {
+    return deps.timeoutMs ?? DEFAULT_ASSERT_TIMEOUT_MS;
+}
+export function expectSignal(deps, name, dataMatches) {
+    const predicate = {
+        kind: PredicateKind.SIGNAL,
+        name,
+        ...(dataMatches !== undefined ? { dataMatches } : {}),
+    };
+    return assertPredicate(deps.invoke, predicate, timeout(deps), deps.sessionId);
+}
+export function expectNet(deps, method, urlContains, status) {
+    const predicate = {
+        kind: PredicateKind.NET,
+        method,
+        urlContains,
+        ...(status !== undefined ? { status } : {}),
+    };
+    return assertPredicate(deps.invoke, predicate, timeout(deps), deps.sessionId);
+}
+export function expectElement(deps, query, state) {
+    const predicate = {
+        kind: PredicateKind.ELEMENT,
+        query,
+        ...(state !== undefined ? { state } : {}),
+    };
+    return assertPredicate(deps.invoke, predicate, timeout(deps), deps.sessionId);
+}
+export function expectText(deps, contains) {
+    const predicate = { kind: PredicateKind.TEXT, contains };
+    return assertPredicate(deps.invoke, predicate, timeout(deps), deps.sessionId);
+}
+export function expectAbsent(deps, query) {
+    const predicate = {
+        kind: PredicateKind.ELEMENT,
+        query,
+        absent: true,
+    };
+    return assertPredicate(deps.invoke, predicate, timeout(deps), deps.sessionId);
+}
+export function expectNoConsoleErrors(deps) {
+    const predicate = {
+        kind: PredicateKind.CONSOLE,
+        level: CONSOLE_LEVEL_ERROR,
+        absent: true,
+    };
+    return assertPredicate(deps.invoke, predicate, timeout(deps), deps.sessionId);
+}
+//# sourceMappingURL=matchers.js.map

package/dist/matchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.js","sourceRoot":"","sources":["../src/matchers.ts"],"names":[],"mappings":"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"}

package/dist/register.d.ts

@@ -0,0 +1,31 @@
+import type { FlowErrorCode } from '@reticlehq/core';
+import type { FlowReplaySession } from '@reticlehq/server';
+import { flowsAsSpecs } from './flow-spec.js';
+import type { FlowsAsSpecsOptions, SpecRunResult } from './flow-spec.js';
+/** A loaded flow file was missing/malformed/badly-named — its spec throws this when run. */
+export declare class FlowMalformedError extends Error {
+    readonly code: FlowErrorCode;
+    constructor(name: string, code: FlowErrorCode);
+}
+/** A RUNNABLE flow spec ran but failed — carries the verbatim replay + success evidence. */
+export declare class SpecFailure extends Error {
+    readonly result: SpecRunResult;
+    constructor(name: string, result: SpecRunResult);
+}
+/** The injectable test-registrar — vitest's `it` in CI, a collector stub in unit tests. */
+export type RegisterFn = (name: string, fn: () => Promise<void> | void) => void;
+export interface RegisterFlowSpecsOptions extends FlowsAsSpecsOptions {
+    /** Defaults to vitest's `it`. Injected so registration can be unit-tested without nested vitest. */
+    register?: RegisterFn;
+}
+/**
+ * FLOW2SPEC — register one vitest test per flow under `source`. The agent-readable map (.reticle/flows)
+ * becomes the executable suite: a passing flow registers a green `it`, a malformed file registers a
+ * loudly-failing ERROR `it`, an empty dir registers nothing. `getSession` is the seam — the
+ * `reticle drive` launched session in CI, a fake in unit tests. MUST be awaited at module top level so
+ * vitest collects the registered cases.
+ */
+export declare function registerFlowSpecs(source: Parameters<typeof flowsAsSpecs>[0], getSession: () => Promise<FlowReplaySession> | FlowReplaySession, opts?: RegisterFlowSpecsOptions): Promise<void>;
+/** Public alias matching the design's stated entrypoint name. */
+export declare const reticleFlowsAsSpecs: typeof registerFlowSpecs;
+//# sourceMappingURL=register.d.ts.map

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAY,mBAAmB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEnF,4FAA4F;AAC5F,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBACjB,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa;CAK9C;AAED,4FAA4F;AAC5F,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;gBACnB,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa;CAKhD;AAkBD,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;AAEhF,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,oGAAoG;IACpG,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AA6BD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EAC1C,UAAU,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,EAChE,IAAI,CAAC,EAAE,wBAAwB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,0BAAoB,CAAC"}

package/dist/register.js

@@ -0,0 +1,73 @@
+import { FLOW_LOAD_ERROR_PREFIX, SpecKind, SpecOutcome } from './constants.js';
+import { flowsAsSpecs } from './flow-spec.js';
+/** A loaded flow file was missing/malformed/badly-named — its spec throws this when run. */
+export class FlowMalformedError extends Error {
+    code;
+    constructor(name, code) {
+        super(`${FLOW_LOAD_ERROR_PREFIX}: '${name}' (${code})`);
+        this.name = 'FlowMalformedError';
+        this.code = code;
+    }
+}
+/** A RUNNABLE flow spec ran but failed — carries the verbatim replay + success evidence. */
+export class SpecFailure extends Error {
+    result;
+    constructor(name, result) {
+        super(`${result.message ?? 'flow spec failed'}: ${name}\n${renderEvidence(result)}`);
+        this.name = 'SpecFailure';
+        this.result = result;
+    }
+}
+/** Render the structured drift/near-miss evidence into the Error message so a CI log self-explains. */
+function renderEvidence(result) {
+    const driftLines = result.steps
+        .filter((s) => s.drift !== undefined)
+        .map((s) => {
+        const nearest = s.drift?.nearest;
+        const fix = nearest === null || nearest === undefined ? '' : ` (nearest: ${nearest})`;
+        return `  step ${String(s.step)}: ${s.drift?.reason ?? 'drift'}${fix}`;
+    });
+    const successLine = result.successResult.pass || result.successResult.failureReason === undefined
+        ? []
+        : [`  success: ${result.successResult.failureReason}`];
+    return [...driftLines, ...successLine].join('\n');
+}
+/**
+ * Resolve the default registrar (vitest's `it`) lazily. vitest is an OPTIONAL peer dependency, so the
+ * public barrel (`@reticlehq/test`) must stay importable when vitest is absent — only callers that actually
+ * register flow specs without injecting their own `register` fn need it. A static top-level import
+ * would pull vitest into the eager module graph of every `import { reticleTest } from '@reticlehq/test'`.
+ */
+async function defaultRegister() {
+    const vitest = await import('vitest');
+    return vitest.it;
+}
+/** Turn one FlowSpec into a (name, fn) registration. The fn throws structured evidence on failure. */
+function specToCase(spec, getSession) {
+    return async () => {
+        if (spec.kind === SpecKind.ERROR && spec.loadError !== undefined) {
+            throw new FlowMalformedError(spec.name, spec.loadError.code);
+        }
+        const result = await spec.run(await getSession());
+        if (result.outcome === SpecOutcome.FAIL) {
+            throw new SpecFailure(spec.name, result);
+        }
+    };
+}
+/**
+ * FLOW2SPEC — register one vitest test per flow under `source`. The agent-readable map (.reticle/flows)
+ * becomes the executable suite: a passing flow registers a green `it`, a malformed file registers a
+ * loudly-failing ERROR `it`, an empty dir registers nothing. `getSession` is the seam — the
+ * `reticle drive` launched session in CI, a fake in unit tests. MUST be awaited at module top level so
+ * vitest collects the registered cases.
+ */
+export async function registerFlowSpecs(source, getSession, opts) {
+    const register = opts?.register ?? (await defaultRegister());
+    const specs = await flowsAsSpecs(source, opts);
+    for (const spec of specs) {
+        register(spec.name, specToCase(spec, getSession));
+    }
+}
+/** Public alias matching the design's stated entrypoint name. */
+export const reticleFlowsAsSpecs = registerFlowSpecs;
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,6 @@
+import type { ReticleSpec } from './types.js';
+export declare function register(spec: ReticleSpec): void;
+/** A frozen snapshot copy so a run that started can ignore later (re-entrant) registrations. */
+export declare function getRegistered(): readonly ReticleSpec[];
+export declare function clearRegistry(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAK9C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAEhD;AAED,gGAAgG;AAChG,wBAAgB,aAAa,IAAI,SAAS,WAAW,EAAE,CAEtD;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}

package/dist/registry.js

@@ -0,0 +1,13 @@
+/** Module-level registration list. A list (not a map) so duplicate names are kept, not collapsed. */
+const specs = [];
+export function register(spec) {
+    specs.push(spec);
+}
+/** A frozen snapshot copy so a run that started can ignore later (re-entrant) registrations. */
+export function getRegistered() {
+    return [...specs];
+}
+export function clearRegistry() {
+    specs.length = 0;
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAEA,qGAAqG;AACrG,MAAM,KAAK,GAAkB,EAAE,CAAC;AAEhC,MAAM,UAAU,QAAQ,CAAC,IAAiB;IACxC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACnB,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,8 @@
+import { type ToolInvoker } from '@reticlehq/server';
+/**
+ * The single testid -> ref chokepoint. Queries by testid; returns the first ref. On zero matches
+ * throws ReticleQueryEmptyError naming the testid, carrying the query's presentTestids as evidence so
+ * the runner surfaces "you meant one of these" instead of a blank failure.
+ */
+export declare function resolveTestid(invoke: ToolInvoker, testid: string, sessionId?: string): Promise<string>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA2BlE;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAajB"}

package/dist/resolve.js

@@ -0,0 +1,39 @@
+import { ReticleTool } from '@reticlehq/server';
+import { QueryBy } from '@reticlehq/core';
+import { ReticleQueryEmptyError } from './skip.js';
+import { NO_ELEMENT_FOR_TESTID } from './constants.js';
+function asQueryEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return {};
+    const record = value;
+    const elements = Array.isArray(record['elements'])
+        ? record['elements']
+        : undefined;
+    const hint = typeof record['hint'] === 'object' && record['hint'] !== null
+        ? record['hint']
+        : undefined;
+    return {
+        ...(elements !== undefined ? { elements } : {}),
+        ...(hint !== undefined ? { hint } : {}),
+    };
+}
+/**
+ * The single testid -> ref chokepoint. Queries by testid; returns the first ref. On zero matches
+ * throws ReticleQueryEmptyError naming the testid, carrying the query's presentTestids as evidence so
+ * the runner surfaces "you meant one of these" instead of a blank failure.
+ */
+export async function resolveTestid(invoke, testid, sessionId) {
+    const args = {
+        by: QueryBy.TESTID,
+        value: testid,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+    };
+    const result = asQueryEnvelope(await invoke(ReticleTool.QUERY, args));
+    const first = result.elements?.[0]?.ref;
+    if (typeof first === 'string' && first.length > 0)
+        return first;
+    const present = result.hint?.presentTestids;
+    const detail = present !== undefined ? { evidence: { presentTestids: present } } : undefined;
+    throw new ReticleQueryEmptyError(`${NO_ELEMENT_FOR_TESTID} ${testid}`, detail);
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAQvD,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC3D,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAChD,CAAC,CAAE,MAAM,CAAC,UAAU,CAAyB;QAC7C,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,IAAI,GACR,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI;QAC3D,CAAC,CAAE,MAAM,CAAC,MAAM,CAAkC;QAClD,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO;QACL,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAmB,EACnB,MAAc,EACd,SAAkB;IAElB,MAAM,IAAI,GAA4B;QACpC,EAAE,EAAE,OAAO,CAAC,MAAM;QAClB,KAAK,EAAE,MAAM;QACb,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAC;IACF,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACtE,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAEhE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC;IAC5C,MAAM,MAAM,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7F,MAAM,IAAI,sBAAsB,CAAC,GAAG,qBAAqB,IAAI,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC;AACjF,CAAC"}

package/dist/runner.d.ts

@@ -0,0 +1,13 @@
+import type { ReticleSpec, RunSummary, RunnerOptions, SpecResult } from './types.js';
+/** Run one spec to a result. Never throws — a spec failure is captured, not propagated. */
+export declare function runOne(spec: ReticleSpec, opts: RunnerOptions): Promise<SpecResult>;
+/**
+ * Run all specs sequentially, in registration order, isolating each through runOne so one
+ * failure never aborts the rest. Snapshots the spec list at call time (re-entrant registration
+ * during a run is ignored for that run). Returns the JSON result + summary; prints if a sink is set.
+ */
+export declare function runSpecs(opts: RunnerOptions): Promise<{
+    results: SpecResult[];
+    summary: RunSummary;
+}>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAWrF,2FAA2F;AAC3F,wBAAsB,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBxF;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC;IAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC,CAWzD"}

package/dist/runner.js

@@ -0,0 +1,52 @@
+import { TestStatus } from './constants.js';
+import { isSkip } from './skip.js';
+import { getRegistered } from './registry.js';
+import { summarize, printSummary } from './summary.js';
+/** Classify a thrown value: skip (sentinel) vs fail (everything else). */
+function classify(error) {
+    if (isSkip(error)) {
+        return { status: TestStatus.SKIP, skipReason: error.reason };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { status: TestStatus.FAIL, error: message };
+}
+/** Run one spec to a result. Never throws — a spec failure is captured, not propagated. */
+export async function runOne(spec, opts) {
+    const start = opts.now();
+    let outcome;
+    try {
+        const t = opts.buildContext(opts.invoke);
+        await spec.fn(t);
+        outcome = { status: TestStatus.PASS };
+    }
+    catch (error) {
+        outcome = classify(error);
+    }
+    const durationMs = opts.now() - start;
+    // exactOptionalPropertyTypes: only spread an optional field when it is actually present.
+    return {
+        name: spec.name,
+        status: outcome.status,
+        durationMs,
+        ...(outcome.error !== undefined ? { error: outcome.error } : {}),
+        ...(outcome.skipReason !== undefined ? { skipReason: outcome.skipReason } : {}),
+    };
+}
+/**
+ * Run all specs sequentially, in registration order, isolating each through runOne so one
+ * failure never aborts the rest. Snapshots the spec list at call time (re-entrant registration
+ * during a run is ignored for that run). Returns the JSON result + summary; prints if a sink is set.
+ */
+export async function runSpecs(opts) {
+    const specs = opts.specs ?? getRegistered();
+    const results = [];
+    for (const spec of specs) {
+        results.push(await runOne(spec, opts));
+    }
+    const summary = summarize(results);
+    if (opts.print !== undefined) {
+        printSummary(summary, results, opts.print);
+    }
+    return { results, summary };
+}
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGvD,0EAA0E;AAC1E,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAClB,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAC/D,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACrD,CAAC;AAED,2FAA2F;AAC3F,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAiB,EAAE,IAAmB;IACjE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IAAI,OAA4D,CAAC;IACjE,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACjB,OAAO,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;IACtC,yFAAyF;IACzF,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU;QACV,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,EAAE,CAAC;IAC5C,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC7B,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/skip.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The skip sentinel. MATCHERS' `t.expectInputModeReal()` throws this when the active input mode
+ * is not 'real', so the runner reports `status:'skip'` (with the reason) instead of a silent pass.
+ */
+export declare class ReticleSkip extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** Structured diagnosis attached to a matcher failure so the runner surfaces the tool's own evidence. */
+export interface AssertionDetail {
+    /** The predicate engine's near-miss / matched-element / found-entries evidence. */
+    evidence?: unknown;
+    /** The tool's own failureReason, preserved verbatim (the Error message may add framing). */
+    failureReason?: string;
+}
+/**
+ * A failed matcher (e.g. an `reticle_assert` returning `{ pass:false, failureReason }`). Carries the
+ * reason as its message plus the tool's structured `evidence`/`failureReason`; the runner treats it
+ * as an ordinary fail (the message becomes SpecResult.error).
+ */
+export declare class ReticleAssertionError extends Error {
+    readonly evidence?: unknown;
+    readonly failureReason?: string;
+    constructor(message: string, detail?: AssertionDetail);
+}
+/**
+ * Raised when a testid resolves to zero elements (the act/fill chokepoint). A subclass so a runner
+ * can special-case "unknown testid" if it wants, but it is still an ordinary fail.
+ */
+export declare class ReticleQueryEmptyError extends ReticleAssertionError {
+    constructor(message: string, detail?: AssertionDetail);
+}
+export declare function isSkip(error: unknown): error is ReticleSkip;
+//# sourceMappingURL=skip.d.ts.map

package/dist/skip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip.d.ts","sourceRoot":"","sources":["../src/skip.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED,yGAAyG;AACzG,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe;CAOtD;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,qBAAqB;gBACnD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe;CAItD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAE3D"}