@descryy/mcp 0.9.0 → 0.11.0

package/dist/scenarios/credential-ref.js

@@ -0,0 +1,148 @@
+/**
+ * `${credential:NAME}` — a scenario step names a stored credential by
+ * reference; the credential store holds the value. Lane A1, item 4 of
+ * `documents/plans/runtime-gap-closure.md` ("Sign-in as a first-class
+ * step"). Appended to `DEC-NEXT-scenario-format-needs-a-secret-reference.md`
+ * rather than rewriting it — see that file's own note.
+ *
+ * ## Why a second module, not a second branch inside `secret-ref.ts`
+ *
+ * `secret-ref.ts`'s own header already reserves this extension point:
+ * *"A keychain becomes a second scheme with its own prefix and its own
+ * refusal, not a fallback behind the first one. Nothing about the stored
+ * file changes when it arrives."* This module is that second scheme,
+ * `credential:` rather than `keychain:` because the store it resolves
+ * against (`descry-runtime`'s `CredentialStore`, an at-rest encrypted file
+ * store today, a real OS keychain later behind the same three-method
+ * interface) is named for what it is, not for today's backend. Kept in its
+ * own file rather than added as a branch inside `readSecretRef` so the two
+ * schemes stay independently resolvable — a caller that only has an
+ * environment map (`resolveSecretText`) and one that only has a credential
+ * store (`resolveCredentialText`, here) each fail closed on the scheme they
+ * cannot serve, rather than one function silently depending on both.
+ *
+ * ## What this does not attempt
+ *
+ * A step naming `${credential:NAME}` still types the resolved value into a
+ * field with `type`/`fill`/`select` — the same verbs, the same replay path,
+ * the same "whole field or none of it" and "empty is refused" rules as
+ * `secret-ref.ts`. It does **not** add a session-seeding step that logs a
+ * whole browser context in via a saved storage state mid-replay — that
+ * would need a driver-level primitive (`packages/mcp/src/browser/driver.ts`,
+ * `playwright-driver.ts`) to inject cookies into a session already in
+ * progress, and this lane does not own those files. `auth.ts`'s
+ * `loadStorageStateFile` already seeds a **new** session at
+ * `browser_start_session` time; wiring a credential-store-backed profile
+ * into that call is a smaller, real gap, and is recorded as a handoff in
+ * `DEC-NEXT-scenario-format-needs-a-secret-reference.md` rather than built
+ * here by touching a port this lane does not own.
+ *
+ * Rule 1: an environment variable is a fact about a process; a credential
+ * reference is a fact about a name a person chose. Neither module needs to
+ * know what kind of secret it resolves to.
+ */
+import { resolveSecretText } from "./secret-ref.js";
+/** `${credential:NAME}` — the credential name is deliberately permissive
+ *  (letters, digits, `-`, `_`, `.`) because a credential ref is a name a
+ *  person or a store assigns, not a POSIX environment variable. */
+const REFERENCE = /^\$\{credential:([A-Za-z0-9_.-]+)\}$/;
+const LOOKS_LIKE_REFERENCE = /^\$\{credential:[^}]*\}$/;
+/** Reads one stored `text` field for the `credential:` scheme alone. A `${env:...}` reference is
+ *  a literal as far as this function is concerned — `secret-ref.ts`'s `readSecretRef` is what
+ *  resolves that scheme, and a caller resolving both composes the two (see `resolveEitherRef`). */
+export function readCredentialRef(text) {
+    const matched = REFERENCE.exec(text);
+    if (matched !== null)
+        return { kind: "ref", name: matched[1] };
+    if (LOOKS_LIKE_REFERENCE.test(text)) {
+        return {
+            kind: "malformed",
+            message: `${JSON.stringify(text)} is written like a credential reference and is not one. The only form is ` +
+                '"${credential:NAME}", whole field, with the name made of letters, digits, "-", "_" or ".", no other ' +
+                "text around it. It is refused rather than stored as text on purpose, for the same reason a malformed " +
+                "${env:...} reference is: typed verbatim into a login form, it would be reported as the application's defect.",
+        };
+    }
+    return { kind: "literal", text };
+}
+export function isCredentialRef(text) {
+    return readCredentialRef(text).kind === "ref";
+}
+/** What to write into a file so `name` is resolved from the credential store at replay. */
+export function credentialRefFor(name) {
+    return `\${credential:${name}}`;
+}
+/**
+ * Turns one stored `text` into the string to type, or says why it cannot —
+ * `secret-ref.ts`'s `resolveSecretText`, restated against a credential store
+ * instead of an environment map. An unset name and an empty stored value are
+ * both refusals, for the same reason `resolveSecretText` refuses an empty
+ * environment variable: an empty password produces a failed login that
+ * reads exactly like a broken application.
+ */
+export async function resolveCredentialText(text, store) {
+    const ref = readCredentialRef(text);
+    if (ref.kind === "literal")
+        return { resolved: true, value: ref.text };
+    if (ref.kind === "malformed")
+        return { resolved: false, reason: ref.message };
+    const value = await store.retrieve(ref.name);
+    if (value === null) {
+        return {
+            resolved: false,
+            reason: `this step needs the credential "${ref.name}", and nothing is stored under that name. The scenario was ` +
+                "saved with a reference instead of the value on purpose — the value is a credential and a scenario is a " +
+                `committed file. Store it under "${ref.name}" before replaying. Nothing was typed and the replay stopped ` +
+                "here: a step that types the literal text of its own reference would fail against the application and be " +
+                "reported as the application's defect.",
+        };
+    }
+    if (value === "") {
+        return {
+            resolved: false,
+            reason: `the credential "${ref.name}" is stored and empty. An empty value is refused rather than typed: an empty ` +
+                "password produces a failed login that reads exactly like a broken application.",
+        };
+    }
+    return { resolved: true, value };
+}
+/** Every credential name a scenario's steps reference, in order, deduplicated — the `${credential:...}` counterpart to `secret-ref.ts`'s `referencedVariables`. */
+export function referencedCredentials(texts) {
+    const out = [];
+    for (const text of texts) {
+        if (text === null)
+            continue;
+        const ref = readCredentialRef(text);
+        if (ref.kind === "ref" && !out.includes(ref.name))
+            out.push(ref.name);
+    }
+    return out;
+}
+/**
+ * Resolves a step's stored text against **both** schemes: `${credential:NAME}` checked first
+ * (this module owns that shape and nothing else recognises it), `${env:VAR}` and plain literals
+ * delegated to `resolveSecretText` otherwise. One entry point so a caller (`scenario-runner.ts`)
+ * never has to decide which resolver a given step's text needs — the reference's own prefix
+ * decides. `store` is optional: a scenario naming `${credential:NAME}` with no store configured
+ * refuses by name rather than falling through to `resolveSecretText`, which would report it as a
+ * malformed `${env:...}` reference — a true statement about that resolver and a confusing one
+ * about this file's own scheme.
+ */
+export async function resolveEitherRef(text, env, store) {
+    const asCredential = readCredentialRef(text);
+    if (asCredential.kind === "ref") {
+        if (store === undefined) {
+            return {
+                resolved: false,
+                reason: `this step needs the credential "${asCredential.name}", and no credential store is configured for this ` +
+                    "replay. Sign-in-as-profile steps need a credential store wired in by the caller (browser_run_scenario's " +
+                    "own runner); nothing was typed.",
+            };
+        }
+        return resolveCredentialText(text, store);
+    }
+    if (asCredential.kind === "malformed")
+        return { resolved: false, reason: asCredential.message };
+    return resolveSecretText(text, env);
+}
+//# sourceMappingURL=credential-ref.js.map

package/dist/scenarios/credential-ref.js.map

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

package/dist/scenarios/index.d.ts

@@ -1,4 +1,7 @@
-export { SCENARIO_SCHEMA_VERSION, isUnverifying, type Scenario, type ScenarioStep, type ScenarioAssertion, type ScenarioAssertionKind, type ScenarioActionKind, type TargetDescriptor, } from "./scenario.ts";
+export { MIN_READABLE_SCHEMA_VERSION, SCENARIO_SCHEMA_VERSION, isUnverifying, type Scenario, type ScenarioStep, type ScenarioAssertion, type ScenarioAssertionKind, type ScenarioActionKind, type TargetDescriptor, } from "./scenario.ts";
 export { parseScenario, serializeScenario, type ScenarioParseResult } from "./parse.ts";
+export { isSecretRef, readSecretRef, referencedVariables, resolveSecretText, secretRefFor, type SecretEnvironment, type SecretRef, type SecretResolution, } from "./secret-ref.ts";
 export { scenariosDirectory, scenarioPath, listScenarios, ScenarioListError, readScenario, writeScenario, } from "./storage.ts";
+export { readCredentialRef, isCredentialRef, credentialRefFor, resolveCredentialText, resolveEitherRef, referencedCredentials, type CredentialRef, type CredentialStoreLike, type CredentialResolution, } from "./credential-ref.ts";
+export { projectScenarioToRunPlan, projectRunPlanToScenario, type ProjectedStep, type ProjectedStepKind, type ProjectedBrowserRunPlan, type ProjectionRefusal, type ScenarioProjection, type PlanProjection, type RawProjectedStep, type ScenarioMeta, } from "./browser-run-plan-projection.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/scenarios/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scenarios/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scenarios/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EACL,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,kCAAkC,CAAC"}

package/dist/scenarios/index.js

@@ -1,4 +1,7 @@
-export { SCENARIO_SCHEMA_VERSION, isUnverifying, } from "./scenario.js";
+export { MIN_READABLE_SCHEMA_VERSION, SCENARIO_SCHEMA_VERSION, isUnverifying, } from "./scenario.js";
 export { parseScenario, serializeScenario } from "./parse.js";
+export { isSecretRef, readSecretRef, referencedVariables, resolveSecretText, secretRefFor, } from "./secret-ref.js";
 export { scenariosDirectory, scenarioPath, listScenarios, ScenarioListError, readScenario, writeScenario, } from "./storage.js";
+export { readCredentialRef, isCredentialRef, credentialRefFor, resolveCredentialText, resolveEitherRef, referencedCredentials, } from "./credential-ref.js";
+export { projectScenarioToRunPlan, projectRunPlanToScenario, } from "./browser-run-plan-projection.js";
 //# sourceMappingURL=index.js.map

package/dist/scenarios/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scenarios/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,aAAa,GAOd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAA4B,MAAM,YAAY,CAAC;AACxF,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scenarios/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,aAAa,GAOd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAA4B,MAAM,YAAY,CAAC;AACxF,OAAO,EACL,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,GAIb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,GAItB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GASzB,MAAM,kCAAkC,CAAC"}

package/dist/scenarios/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/scenarios/parse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,KAAK,QAAQ,EAMd,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAwHpE,qNAAqN;AACrN,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CAiE/D;AAED,2HAA2H;AAC3H,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE5D"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/scenarios/parse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAGL,KAAK,QAAQ,EAMd,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAgJpE,qNAAqN;AACrN,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CAwE/D;AAED,2HAA2H;AAC3H,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE5D"}

package/dist/scenarios/parse.js

@@ -3,8 +3,10 @@
  * point. Refuses rather than repairs: coercing a missing field to a default
  * would let a scenario keep loading after it stopped describing the app, silently, in CI where nobody's watching. Problems collect in one pass, not one throw at a time.
  */
-import { SCENARIO_SCHEMA_VERSION, } from "./scenario.js";
-const ACTIONS = ["navigate", "click", "type", "fill"];
+import { readSecretRef } from "./secret-ref.js";
+import { readCredentialRef } from "./credential-ref.js";
+import { MIN_READABLE_SCHEMA_VERSION, SCENARIO_SCHEMA_VERSION, } from "./scenario.js";
+const ACTIONS = ["navigate", "click", "type", "fill", "select", "submit"];
 const ASSERTION_KINDS = [
     "elementVisible",
     "textEquals",
@@ -13,9 +15,11 @@ const ASSERTION_KINDS = [
     "noFailedRequests",
 ];
 /** Actions that act on an element, and therefore require a target. `navigate` acts on the page. */
-const ELEMENT_ACTIONS = ["click", "type", "fill"];
-/** Actions that enter text, and therefore require it. */
-const TEXT_ACTIONS = ["type", "fill"];
+const ELEMENT_ACTIONS = ["click", "type", "fill", "select", "submit"];
+/** Actions that carry a value in `text`, and therefore require one. `select` is here because the
+ *  option it chooses is the same kind of stored string as typed text — see `ScenarioStep.text`.
+ *  `submit` is not: it acts on a form through the form's own submit control and names nothing. */
+const TEXT_ACTIONS = ["type", "fill", "select"];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -69,10 +73,32 @@ function readStep(raw, index, problems) {
     }
     const text = raw["text"] ?? null;
     if (TEXT_ACTIONS.includes(kind) && typeof text !== "string") {
-        problems.push(`${where}: ${kind} enters text and needs it stored`);
+        problems.push(kind === "select"
+            ? `${where}: select chooses an option and needs its value stored in text`
+            : `${where}: ${kind} enters text and needs it stored`);
     }
     if (!TEXT_ACTIONS.includes(kind) && text !== null) {
-        problems.push(`${where}: only type and fill carry text`);
+        problems.push(`${where}: only ${TEXT_ACTIONS.join(", ")} carry text`);
+    }
+    // A secret or credential reference with a typo in it is refused here rather than at replay.
+    // Stored text is typed verbatim, so `${ENV:PASSWORD}` or `${credential:NAME }` would reach the
+    // login form as those characters and the page's rejection of them would be reported as the
+    // application's defect. `credential:` is checked first — a well-formed credential reference
+    // (`credential-ref.ts`, RG-1(4) / lane "delivery") must never be flagged malformed by a
+    // validator that only knew the `env:` scheme when it was written; `readSecretRef`'s own
+    // `LOOKS_LIKE_REFERENCE` matches any `${...}` shape generically, so without this check first,
+    // every valid `${credential:NAME}` step failed here before a scenario could ever be read.
+    if (typeof text === "string") {
+        const credentialRef = readCredentialRef(text);
+        if (credentialRef.kind === "malformed") {
+            problems.push(`${where}: ${credentialRef.message}`);
+        }
+        else if (credentialRef.kind === "literal") {
+            const ref = readSecretRef(text);
+            if (ref.kind === "malformed")
+                problems.push(`${where}: ${ref.message}`);
+        }
+        // credentialRef.kind === "ref": a well-formed ${credential:NAME}, nothing to flag.
     }
     return {
         action: kind,
@@ -127,12 +153,19 @@ export function parseScenario(raw) {
             ],
         };
     }
-    if (schemaVersion < SCENARIO_SCHEMA_VERSION) {
+    if (schemaVersion < MIN_READABLE_SCHEMA_VERSION) {
         return {
             valid: false,
-            problems: [`schemaVersion ${schemaVersion} is older than ${SCENARIO_SCHEMA_VERSION} and no migration exists yet — re-save the scenario.`],
+            problems: [
+                `schemaVersion ${schemaVersion} is older than ${MIN_READABLE_SCHEMA_VERSION}, the oldest this reader still accepts, and no migration exists — re-save the scenario.`,
+            ],
         };
     }
+    // Between MIN_READABLE and current: read as-is. Version 1 is a strict subset of 2 — every
+    // field means what it meant — so the migration is the identity and a scenario saved before the
+    // `select`/`submit` verbs and the secret reference existed keeps replaying untouched. The
+    // stored number is kept rather than rewritten to the current one: it is provenance for which
+    // reader wrote the file, and a re-save is what updates it.
     for (const field of ["name", "targetUrl", "savedAt", "savedAtCommit"]) {
         if (typeof raw[field] !== "string")
             problems.push(`${field} is required`);

package/dist/scenarios/parse.js.map

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

package/dist/scenarios/scenario.d.ts

@@ -3,8 +3,21 @@
  * is the runner's separate question. A step stores a `TargetDescriptor`, never a `ref`
  * (refs are snapshot-scoped, stale by replay). All 3 descriptor fields are required
  * together — a fallback chain would quietly substitute a match instead of disagreeing. */
-/** Bumped when a stored scenario's shape changes. An integer, never semver: one repository, one reader, nothing to argue about. */
-export declare const SCENARIO_SCHEMA_VERSION = 1;
+/** Bumped when a stored scenario's shape changes. An integer, never semver: one repository, one reader, nothing to argue about.
+ *
+ *  2 adds the `select` and `submit` verbs and the `${env:VAR}` secret reference. The bump is
+ *  about the *reference*, not the verbs: an older reader meeting an unknown verb already refuses
+ *  it by name, but an older reader meeting `${env:PASSWORD}` in a `text` field would type that
+ *  literal string into a login form and report the resulting failure as the application's. Rule
+ *  7 forbids that, so the version gate is what stops it — a version 2 file is refused whole by a
+ *  version 1 reader, with a message that says to upgrade. */
+export declare const SCENARIO_SCHEMA_VERSION = 2;
+/** The oldest stored version this reader still accepts. Version 1 is a strict subset of 2 —
+ *  every field means what it meant, so the migration is the identity and a scenario saved before
+ *  this change keeps replaying untouched. Read in the other direction from
+ *  `SCENARIO_SCHEMA_VERSION`: that one stops a new file being misread by an old reader, this one
+ *  stops an old file being refused by a new one for no reason. */
+export declare const MIN_READABLE_SCHEMA_VERSION = 1;
 /** How a step names its element. Re-resolved at replay against a fresh snapshot,
  *  must match exactly one — zero/ambiguous/partial each refuse, naming what disagreed. */
 export interface TargetDescriptor {
@@ -12,15 +25,36 @@ export interface TargetDescriptor {
     readonly name: string;
     readonly selector: string;
 }
-/** Mirrors the port's `BrowserActionKind`, restated rather than imported: the format must be readable without a browser in the process. */
-export type ScenarioActionKind = "navigate" | "click" | "type" | "fill";
+/** Mirrors the port's `BrowserActionKind`, restated rather than imported: the format must be
+ *  readable without a browser in the process. `waitFor` is absent from both for the same reason —
+ *  it performs nothing. */
+export type ScenarioActionKind = "navigate" | "click" | "type" | "fill" | "select" | "submit";
 export interface ScenarioStep {
     readonly action: ScenarioActionKind;
     /** The element to act on. Null for `navigate`, which acts on the page — and required for everything else, because a step with nothing to resolve cannot be replayed. */
     readonly target: TargetDescriptor | null;
     /** Where to go. Present for `navigate` alone. */
     readonly url: string | null;
-    /** What to enter. Present for `type` and `fill` alone. `type` appends, `fill` replaces — the runtime's two text verbs, kept distinct here because the stored artifact must say which one a replay should perform. */
+    /** What to enter, or for `select` which option to choose. Present for `type`, `fill` and
+     *  `select` alone — `submit` acts on a form through its own submit control and carries nothing,
+     *  and `navigate` acts on the page.
+     *
+     *  `type` appends, `fill` replaces — the runtime's two text verbs, kept distinct here because
+     *  the stored artifact must say which one a replay should perform.
+     *
+     *  For `select` this is the option's **stored value**, not the label a person reads. Three
+     *  reasons, in order of weight. (1) The driver already records `matched.value` in
+     *  `PerformedStep`, so a scenario storing the label could never match its own session's
+     *  provenance record and every saved `select` would fall back to a later snapshot check.
+     *  (2) A label changes when copy changes — a rewording, a translation — and a scenario that
+     *  breaks on a rewording is a scenario a team turns off. A value changes when the backend's
+     *  option set changes, and a scenario breaking *then* is the scenario doing its job. (3) The
+     *  replay verb matches by value first and label second, exactly as the live verb does, so a
+     *  stored value that has since become a label still resolves rather than refusing. That
+     *  fallback is inside the option matcher and is not the descriptor fallback rule 2 forbids: it
+     *  never substitutes a *different* element, only recognises the same option named the other way.
+     *
+     *  May carry a secret reference — `${env:VAR}` — instead of a literal. See `secret-ref.ts`. */
     readonly text: string | null;
 }
 /** What the scenario claims. Kept small, derived only from what a snapshot/run

package/dist/scenarios/scenario.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../../src/scenarios/scenario.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAE1F,mIAAmI;AACnI,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;0FAC0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,2IAA2I;AAC3I,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAExE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,wKAAwK;IACxK,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qNAAqN;IACrN,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;iGAEiG;AACjG,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,gLAAgL;IAChL,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;0FAEsF;IACtF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC;;qFAEiF;IACjF,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACnD;AAED;;oBAEoB;AACpB,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAEzD"}
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../../src/scenarios/scenario.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAE1F;;;;;;;6DAO6D;AAC7D,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;kEAIkE;AAClE,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C;0FAC0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;2BAE2B;AAC3B,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,wKAAwK;IACxK,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;mGAmB+F;IAC/F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;iGAEiG;AACjG,MAAM,MAAM,qBAAqB,GAC7B,gBAAgB,GAChB,YAAY,GACZ,WAAW,GACX,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,gLAAgL;IAChL,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;0FAEsF;IACtF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC;;qFAEiF;IACjF,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACnD;AAED;;oBAEoB;AACpB,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAEzD"}

package/dist/scenarios/scenario.js

@@ -3,8 +3,21 @@
  * is the runner's separate question. A step stores a `TargetDescriptor`, never a `ref`
  * (refs are snapshot-scoped, stale by replay). All 3 descriptor fields are required
  * together — a fallback chain would quietly substitute a match instead of disagreeing. */
-/** Bumped when a stored scenario's shape changes. An integer, never semver: one repository, one reader, nothing to argue about. */
-export const SCENARIO_SCHEMA_VERSION = 1;
+/** Bumped when a stored scenario's shape changes. An integer, never semver: one repository, one reader, nothing to argue about.
+ *
+ *  2 adds the `select` and `submit` verbs and the `${env:VAR}` secret reference. The bump is
+ *  about the *reference*, not the verbs: an older reader meeting an unknown verb already refuses
+ *  it by name, but an older reader meeting `${env:PASSWORD}` in a `text` field would type that
+ *  literal string into a login form and report the resulting failure as the application's. Rule
+ *  7 forbids that, so the version gate is what stops it — a version 2 file is refused whole by a
+ *  version 1 reader, with a message that says to upgrade. */
+export const SCENARIO_SCHEMA_VERSION = 2;
+/** The oldest stored version this reader still accepts. Version 1 is a strict subset of 2 —
+ *  every field means what it meant, so the migration is the identity and a scenario saved before
+ *  this change keeps replaying untouched. Read in the other direction from
+ *  `SCENARIO_SCHEMA_VERSION`: that one stops a new file being misread by an old reader, this one
+ *  stops an old file being refused by a new one for no reason. */
+export const MIN_READABLE_SCHEMA_VERSION = 1;
 /** True when a scenario claims nothing, so verifies nothing. A clean replay still
  *  proves the steps resolve — real info, not "the app is behaving". Reported as
  *  `unverified`. */

package/dist/scenarios/scenario.js.map

@@ -1 +1 @@
-{"version":3,"file":"scenario.js","sourceRoot":"","sources":["../../src/scenarios/scenario.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAE1F,mIAAmI;AACnI,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AA4DzC;;oBAEoB;AACpB,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC9C,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"scenario.js","sourceRoot":"","sources":["../../src/scenarios/scenario.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAE1F;;;;;;;6DAO6D;AAC7D,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC;;;;kEAIkE;AAClE,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAiF7C;;oBAEoB;AACpB,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC9C,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC;AAC1C,CAAC"}

package/dist/scenarios/secret-ref.d.ts

@@ -0,0 +1,86 @@
+/**
+ * A step's text without the secret in it — `${env:VAR}` in place of a literal, resolved from
+ * the environment at replay.
+ *
+ * ## Why the format needs this at all
+ *
+ * A saved scenario is a committed file. `ScenarioStep.text` stores what was typed. Logging in
+ * by hand once and saving the session is the documented way to reach a gated screen, and the
+ * act of logging in is the act of typing a password — so the format's ordinary, intended use
+ * writes a credential into git. The guard that existed before this catches only a value the
+ * session was *also* seeded with, because that is the only value a session can prove is a
+ * credential; a password the agent simply typed was still written.
+ *
+ * ## Why there is no detector
+ *
+ * Nothing at the moment of typing distinguishes a password from a fixture value. `type="password"`
+ * is a hint: plenty of credential fields are not typed that way, and plenty of password fields
+ * hold throwaway values that are *useful* committed. A heuristic wrong in one direction commits a
+ * credential; wrong in the other it silently breaks a scenario somebody wrote on purpose. So a
+ * value is a secret because it is written as a reference, and for no other reason.
+ *
+ * ## Whole field, never embedded
+ *
+ * A reference is the entire `text` or none of it. `"Bearer ${env:TOKEN}"` is refused rather than
+ * interpolated. A partially-resolved string is the failure this module exists to prevent wearing
+ * a different hat: half of it came from the environment and half of it is in the file, and
+ * nothing in the artifact says which half. If a page needs a prefix, put the prefix in the
+ * variable.
+ *
+ * ## Escaping
+ *
+ * `$${env:X}` is the literal text `${env:X}`. A form that legitimately takes that string — a
+ * template editor, a config field — must stay writable, and an escape is cheaper than a special
+ * case later.
+ *
+ * Rule 1: an environment variable is a fact about a process, not about a language.
+ */
+export type SecretRef = 
+/** Store and type this exactly. `text` is already unescaped. */
+{
+    readonly kind: "literal";
+    readonly text: string;
+}
+/** Resolve `variable` from the environment at replay; never store its value. */
+ | {
+    readonly kind: "ref";
+    readonly variable: string;
+}
+/** Meant as a reference and is not one. Refused at parse, save and replay alike. */
+ | {
+    readonly kind: "malformed";
+    readonly message: string;
+};
+/**
+ * Reads one stored `text` field. Never throws and never resolves — resolution is a separate
+ * call, so the format module stays readable with no environment in the process.
+ */
+export declare function readSecretRef(text: string): SecretRef;
+/** True when this stored text would be resolved rather than typed. Cheap enough to call anywhere. */
+export declare function isSecretRef(text: string): boolean;
+/** What to write into a file so `variable` is resolved at replay. The one place the syntax is built. */
+export declare function secretRefFor(variable: string): string;
+export type SecretResolution = {
+    readonly resolved: true;
+    readonly value: string;
+}
+/** `reason` is already a whole sentence for a person, and never carries a value. */
+ | {
+    readonly resolved: false;
+    readonly reason: string;
+};
+/** Where a reference resolves from. A map, not `process.env` directly, so a replay can be given
+ *  one — and so this file names no process global that a test would then have to mutate. */
+export type SecretEnvironment = Readonly<Record<string, string | undefined>>;
+/**
+ * Turns one stored `text` into the string to type, or says why it cannot.
+ *
+ * An unset variable and an empty one are both refusals. An empty variable is the shape a
+ * mistyped export takes — `PASSWORD=` in a `.env` that was never filled in — and typing an empty
+ * string into a login form produces a failed login that reads exactly like a broken application.
+ */
+export declare function resolveSecretText(text: string, env: SecretEnvironment): SecretResolution;
+/** Every variable a scenario's steps reference, in order, deduplicated. What a preflight names
+ *  to a developer, and what a runner checks before it opens a browser it will not be able to use. */
+export declare function referencedVariables(texts: readonly (string | null)[]): readonly string[];
+//# sourceMappingURL=secret-ref.d.ts.map

package/dist/scenarios/secret-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-ref.d.ts","sourceRoot":"","sources":["../../src/scenarios/secret-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAaH,MAAM,MAAM,SAAS;AACnB,gEAAgE;AAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACrD,gFAAgF;GAC9E;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AACrD,oFAAoF;GAClF;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAsBrD;AAED,qGAAqG;AACrG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,wGAAwG;AACxG,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACrD,oFAAoF;GAClF;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;4FAC4F;AAC5F,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAE7E;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,CA2BxF;AAED;qGACqG;AACrG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,MAAM,EAAE,CAQxF"}