@beryl-so/cli 0.24.0 → 0.25.0

package/dist/commands/accounts.js

@@ -172,9 +172,10 @@ export const testAccountCommands = [
             "--probe is the liveness check: a two-step plan (goto a gated page, then a POSITIVE " +
             "assertion that only holds when signed in — the account menu, a 'Sign out' control). " +
             "It is replayed in a fresh browser carrying only the captured session. It is " +
-            "REQUIRED, and not a formality: assertions like `hidden` and `count 0` all pass " +
-            "against a logged-out page, so without a positive signal a dead session would run " +
-            "every test logged-out and still report the run green.\n\n" +
+            "REQUIRED, and not a formality: assertions like `hidden`, `count 0`, and a URL " +
+            "match on a redirect all pass against a logged-out page, so without a positive " +
+            "signal a dead session would run every test logged-out and still report the run " +
+            "green.\n\n" +
             "Storing only stores. Run `beryl accounts check` to prove it against the live app.",
         scope: "project",
         args: [
@@ -264,8 +265,10 @@ export const testAccountCommands = [
             "itself did not complete (fix the plan); SESSION_PROOF_FAILED means the sign-in " +
             "worked but the session did not survive the move to a fresh browser, so this app " +
             "keeps its credential somewhere that cannot be carried (a service worker, a " +
-            "WebAuthn binding). In that case the account is marked unsupported and its tests " +
-            "keep signing in inline — degraded, not broken.\n\n" +
+            "WebAuthn binding). In that case the account is marked unsupported: its " +
+            "session-mode tests fail at setup with SESSION_UNSUPPORTED on every run until " +
+            "re-authored with auth_mode \"inline\" and their own sign-in steps; inline tests " +
+            "are unaffected.\n\n" +
             "Blocks for two browser replays.",
         scope: "project",
         args: [{ name: "account-id", description: "Account id", required: true }],

package/dist/commands/config-vars.js

@@ -57,6 +57,9 @@ export const configCommands = [
     {
         name: "config vars get",
         summary: "Show one config variable",
+        description: "Returns the variable row with its value in plaintext (variables are not secret) — " +
+            "a sensitive value lives in `config secrets`, readable only via `config secrets " +
+            "get --reveal`.",
         scope: "project",
         args: [{ name: "key", description: "Variable key or id", required: true }],
         async run(ctx, input) {
@@ -113,6 +116,8 @@ export const configCommands = [
     {
         name: "config secrets get",
         summary: "Show one secret's metadata, or reveal its value with --reveal",
+        description: "Returns metadata only by default; --reveal is a logged, member-gated decrypt — " +
+            "unlike `config vars get`, which returns its value in plaintext.",
         scope: "project",
         args: [{ name: "key", description: "Secret key or id", required: true }],
         flags: [

package/dist/commands/init.js

@@ -285,8 +285,8 @@ export const initCommands = [
         description: "The full guide to authoring durable, healable tests: the ActionPlan shape, outcome " +
             "assertions, natural-language intent, test accounts and the project mailbox " +
             "({{login_email}}, {{mailbox_address}}, {{inbox_address}} + await_email), and the " +
-            "local run-fix loop. The same content `beryl init` installs as the beryl-test " +
-            "skill — call this before authoring your first plan when no skill is installed " +
+            "local run-fix loop. Same content as the beryl-test skill `beryl init` installs — " +
+            `skip if a loaded beryl-test skill states v${cliVersion()}; else call this first ` +
             "(works without logging in).",
         examples: ["beryl guide"],
         async run() {

package/dist/commands/mailboxes.js

@@ -1,4 +1,4 @@
-import { extractCode } from "../email-extract.js";
+import { ApiError } from "../http.js";
 import { dim, green, table } from "../output.js";
 import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
 const mailboxPath = (ws) => `/workspaces/${ws}/mailboxes`;
@@ -89,9 +89,12 @@ export const mailboxCommands = [
         summary: "Read the latest email in a mailbox (waits for one to arrive)",
         description: "Waits up to --timeout-s for a matching email and returns it (one blocking request; " +
             "the server caps the wait at 50s — re-run to keep waiting). With --extract-code, " +
-            "also pulls the one-time code (4-8 digits) out of the body/subject. Use " +
+            "also asks the server to pull the one-time code out of the email (AI-assisted when " +
+            "the email is ambiguous; `code` is null if none was found). Use " +
             "--recipient-contains to read only one `+tag` alias's mail when several identities " +
-            "share the mailbox. Exits non-zero if nothing arrives before the timeout.",
+            "share the mailbox. Exits non-zero if nothing arrives before the timeout. Waits for " +
+            "and returns ONE latest matching email — `mailbox emails` lists what has already " +
+            "arrived, without waiting.",
         scope: "project",
         args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
         flags: [
@@ -124,7 +127,8 @@ export const mailboxCommands = [
         ],
         async run(ctx, input) {
             const { workspaceId } = await ctx.requireProject(input);
-            const email = (await ctx.client.get(`${mailboxPath(workspaceId)}/${arg(input, "mailbox-id")}/emails/latest`, {
+            const mailboxId = arg(input, "mailbox-id");
+            const email = (await ctx.client.get(`${mailboxPath(workspaceId)}/${mailboxId}/emails/latest`, {
                 timeout_s: flagNum(input, "timeout-s"),
                 since: flagStr(input, "since"),
                 from_contains: flagStr(input, "from-contains"),
@@ -133,12 +137,25 @@ export const mailboxCommands = [
             }));
             if (!flagBool(input, "extract-code"))
                 return { data: email };
-            return { data: { ...email, code: extractCode(email) } };
+            // Extraction is the server's job (the same brain runs use, AI included); a 422
+            // means the email genuinely carries no code.
+            try {
+                const extracted = (await ctx.client.post(`${mailboxPath(workspaceId)}/${mailboxId}/emails/${email.id}/extract`, { extract: "code" }));
+                return { data: { ...email, code: extracted.value } };
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 422) {
+                    return { data: { ...email, code: null } };
+                }
+                throw err;
+            }
         },
     },
     {
         name: "mailbox emails",
         summary: "List the emails a mailbox has received",
+        description: "Returns the already-received emails without waiting — `mailbox read` blocks for " +
+            "a matching one and returns just it.",
         scope: "project",
         args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
         flags: [

package/dist/commands/runs.js

@@ -102,17 +102,19 @@ export const runCommands = [
             "says so once instead of failing every test (on a terminal the CLI offers to install " +
             "whichever half is missing; over MCP it prints the exact install commands). " +
             "Signup/OTP flows work: the CLI answers the spec's await_email steps over the API " +
-            "against the same mailbox the cloud runner uses. Authenticated tests work too: a plan " +
-            "that signs itself in with {{login_email}}/{{login_password}} has its password fetched " +
+            "against the same mailbox the cloud runner uses. Authenticated tests work too: for a plan " +
+            "that signs itself in with {{login_email}}/{{login_password}}, the email is baked into " +
+            "the fetched spec and the password is fetched " +
             "once over the logged secret-reveal route, handed to the spec the way the cloud runner " +
-            "does, and scrubbed from any error text or DOM snapshot before results upload. When the " +
+            "does, and scrubbed from any error text or DOM snapshot before results upload; a test " +
+            "whose account has no stored password is skipped with the exact fix-it command. When the " +
             "run finishes, the results and replay artifacts are imported into Beryl as a normal run " +
             "(trigger source `local`) — history, replay, and reports all work; pass --no-sync to " +
             "keep a run entirely off the record while iterating. Session-mode tests behave as " +
             "in the cloud: their account signs in once per invocation and every session-mode " +
             "test rides that session; a failed sign-in fails those tests with the same " +
             "SESSION_* reason a cloud run reports. Only a test that depends on a session Beryl " +
-            "captured server-side is skipped, with a note. Point " +
+            "captured server-side is skipped, with a note — run those with `runs trigger`. Point " +
             "--url-override at a local dev server or preview, and --dir to keep specs, artifacts, " +
             "and reports on disk. Exits 0 only if every executed test passed.",
         scope: "project",
@@ -134,7 +136,12 @@ export const runCommands = [
                 type: "string",
                 description: "Run against this base URL instead of the environment's (e.g. http://localhost:3000)",
             },
-            { name: "env", type: "string", description: "Environment id to attach the imported run to" },
+            {
+                name: "env",
+                type: "string",
+                description: "Environment id to run against and attach the imported run to — use for a " +
+                    "standing environment; --url-override is for a throwaway host",
+            },
             {
                 name: "sync",
                 type: "boolean",
@@ -464,7 +471,9 @@ export const runCommands = [
         summary: "Show one run with its per-test results",
         description: "Over MCP the failure screenshots come back as viewable image content, so an agent can " +
             "look at the page that broke instead of guessing from the error string. Set screenshots " +
-            "to false to skip fetching them. Ignored outside MCP — the terminal cannot show an image.",
+            "to false to skip fetching them. Ignored outside MCP — the terminal cannot show an image. " +
+            "Returns the run row with its per-test results — `runs report` returns the generated " +
+            "report document, `runs explain` an AI explanation of one failed result.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
         flags: [
@@ -516,6 +525,8 @@ export const runCommands = [
     {
         name: "runs report",
         summary: "Show the generated report for a run",
+        description: "Returns the run's stored generated report (404 until it has been generated) — " +
+            "`runs get` returns the raw run row with per-test results.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
         async run(ctx, input) {
@@ -595,6 +606,8 @@ export const runCommands = [
     {
         name: "runs explain",
         summary: "Explain, with AI, why a test result failed",
+        description: "Takes a single test-RESULT id (not a run id) and returns an AI failure " +
+            "explanation for that result — `runs get` lists a run's results and their ids.",
         scope: "project",
         args: [{ name: "result-id", description: "Test result id (from `beryl runs get`)", required: true }],
         async run(ctx, input) {

package/dist/commands/tests.js

@@ -128,6 +128,9 @@ export const testCommands = [
     {
         name: "tests get",
         summary: "Show one test",
+        description: "Returns the test's metadata row (status, flags, per-environment last result), not " +
+            "the plan — `tests plan` prints the stored JSON plan, `tests script` the rendered " +
+            "Playwright spec.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -138,6 +141,8 @@ export const testCommands = [
     {
         name: "tests plan",
         summary: "Print a test's current step plan (JSON)",
+        description: "Returns the stored json_plan of the test's current version — `tests get` returns " +
+            "the metadata row, `tests script` the rendered Playwright spec.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -164,11 +169,16 @@ export const testCommands = [
             "image content), you fix the plan file and re-run. The proving run is imported as the " +
             "test's first run (--no-sync to skip). A plan that signs in with a session Beryl captured " +
             "server-side cannot replay locally (that session never leaves Beryl's cloud) — it falls " +
-            "back to server-side verification automatically. A session-mode plan replays locally " +
+            "back to server-side verification automatically, and says so. A session-mode plan replays locally " +
             "fine: the server renders it with its account's stored sign-in steps in front, so " +
             "the same identity is exercised on your machine. Optional `before` and `after` arrays hold setup and teardown " +
             "steps: `after` runs even when a main step fails, which is how a create/update/delete test " +
-            "cleans up the record it made on the runs that go red.",
+            "cleans up the record it made on the runs that go red. " +
+            "Recovery: a 409 `duplicate_title` carries existing_test_id + existing_plan_hash — " +
+            "reconcile with that test (`tests get` / `tests set-plan`), don't rename-and-retry; a " +
+            "409 `plan_hash_mismatch` means the submitted plan is not the bytes that were replayed " +
+            "— re-run `tests create`; a 429 with Retry-After 30 means the verify slots are " +
+            "saturated — wait and retry.",
         scope: "project",
         flags: [
             { name: "title", type: "string", required: true, description: "Title for the new test" },
@@ -421,7 +431,9 @@ export const testCommands = [
         description: "Accepts the same plan shape as `tests create`, including the optional `before` and " +
             "`after` sections — `after` runs on pass and on fail, so cleanup happens even when the " +
             "test goes red. Pass `--description` when the re-authored plan changes what the test " +
-            "proves; omit it to keep the test's existing intent.",
+            "proves; omit it to keep the test's existing intent. Saves the edit with NO replay — " +
+            "it rides into the next run unproven; `tests recompile` is the verify-first " +
+            "alternative.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
@@ -464,9 +476,12 @@ export const testCommands = [
         name: "tests quarantine",
         summary: "Mute a flaky test: it keeps running, but its failures stop failing the run",
         description: "A quarantined test still executes and its result is still recorded and visible — its " +
-            "red just doesn't count towards the run's verdict, so it can't red-light a deploy. Use " +
+            "red lands in the run's quarantined_count and gates neither the run's verdict nor exit " +
+            "codes, so it can't red-light a deploy. Use " +
             "it on a persistently flaky test instead of deleting it (which destroys the history) or " +
-            "asking support to deactivate it (which stops it running at all). `off` un-quarantines.",
+            "asking support to deactivate it (which stops it running at all). After 5 consecutive " +
+            "clean passes the test reports rehab_ready — advisory only, nothing un-quarantines " +
+            "itself. `off` un-quarantines.",
         scope: "project",
         args: [
             { name: "test-id", description: "Test id", required: true },
@@ -501,6 +516,13 @@ export const testCommands = [
     {
         name: "tests recompile",
         summary: "Validate + verify an edited plan against the live site before persisting",
+        description: "Unlike `tests set-plan` (which saves the edit and lets it ride into the next run), " +
+            "this replays the edited plan against the live site before anything persists. A " +
+            "deterministic replay failure (verdict `drop`) REJECTS the edit — persisted:false, " +
+            "the prior plan stays live — and returns the failure evidence (over MCP the " +
+            "screenshot is image content). Verdict `flag` (the runner errored, no verdict on " +
+            "the flow) persists the plan but reports it unverified. Returns 429 with " +
+            "Retry-After 30 when the 2 inline-verify slots are saturated — wait and retry.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
@@ -569,6 +591,9 @@ export const testCommands = [
     {
         name: "tests restore",
         summary: "Restore a test to an earlier version",
+        description: "Copies the named older version's plan forward as a NEW head version — unlike " +
+            "`tests reset`, which flips authored_by back to `system` and leaves the plan " +
+            "untouched.",
         scope: "project",
         args: [
             { name: "test-id", description: "Test id", required: true },
@@ -584,6 +609,9 @@ export const testCommands = [
     {
         name: "tests reset",
         summary: "Discard user edits and return the test to its latest system-authored version",
+        description: "Flips authored_by back to `system` WITHOUT changing the plan (the next " +
+            "regeneration overwrites it) — unlike `tests restore`, which copies an older " +
+            "version's plan forward as a new version.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -632,7 +660,9 @@ export const testCommands = [
         summary: "Print the rendered Playwright spec for a test (or an unbanked plan file)",
         description: "With a test id, fetches the banked test's rendered .spec.ts. With --file, compiles a " +
             "plan JSON that has NOT been banked yet — the same render `tests create` proves locally — " +
-            "so you can inspect exactly what would run before creating anything.",
+            "so you can inspect exactly what would run before creating anything. This returns the " +
+            "executable spec — `tests plan` returns the stored JSON plan it is rendered from, " +
+            "`tests get` the metadata row.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id (omit when passing --file)" }],
         flags: [

package/dist/email-pump.js

@@ -1,10 +1,10 @@
 import fs from "node:fs";
-import { extractValue } from "./email-extract.js";
 import { ApiError } from "./http.js";
 const SIDECAR_POLL_MS = 500;
 // The server caps one blocking wait at 50s; stay under it and loop.
 const SERVER_WAIT_MAX_S = 45;
 const DEFAULT_WAIT_S = 30;
+const EXTRACT_RETRY_MS = 1000;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export function startEmailPump(opts) {
     let stopped = false;
@@ -29,11 +29,36 @@ export function startEmailPump(opts) {
             throw err;
         }
     };
+    // A 422 is a real verdict — "this email carries no artifact" — and sends the wait on
+    // to the next email; anything else is transport trouble, retried until the step's own
+    // deadline does the failing.
+    const extractOnServer = async (emailId, req, deadline) => {
+        while (!stopped && Date.now() < deadline) {
+            try {
+                const res = (await opts.client.post(`/workspaces/${opts.workspaceId}/mailboxes/${opts.inboxId}/emails/${emailId}/extract`, { extract: req.extract ?? "code", extract_pattern: req.pattern }));
+                if (res.source === "ai")
+                    opts.onEvent?.("await_email: the AI extractor answered");
+                return { ok: true, value: res.value };
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 422) {
+                    const detail = typeof err.detail === "string" ? err.detail : err.message;
+                    return {
+                        ok: false,
+                        error: detail.replace(/^EMAIL_EXTRACTION_FAILED:\s*/, ""),
+                    };
+                }
+                await sleep(EXTRACT_RETRY_MS);
+            }
+        }
+        return { ok: false, error: "extraction did not complete before the wait deadline" };
+    };
     const resolveRequest = async (req) => {
         // Wait exactly wait_s, like the cloud resolver — the spec's own grace window
         // covers this side's poll tick + round trip.
         const waitS = Math.max(1, Number(req.wait_s) || DEFAULT_WAIT_S);
         const deadline = Date.now() + waitS * 1000;
+        let lastExtractError;
         while (!stopped && Date.now() < deadline) {
             const remainingS = Math.ceil((deadline - Date.now()) / 1000);
             const email = await fetchLatest(req, Math.min(SERVER_WAIT_MAX_S, remainingS));
@@ -48,9 +73,15 @@ export function startEmailPump(opts) {
             consumed.add(email.id);
             since = email.received_at;
             opts.onEvent?.(`await_email: matched "${email.subject ?? "(no subject)"}"`);
-            return extractValue(email, String(req.extract ?? "code"), req.pattern);
+            const extracted = await extractOnServer(email.id, req, deadline);
+            if (extracted.ok)
+                return extracted.value;
+            // Same move as the cloud resolver: an email without the artifact (a welcome mail
+            // racing the code mail) is consumed and the wait continues for the next one.
+            lastExtractError = extracted.error;
+            opts.onEvent?.(`await_email: ${extracted.error} — waiting for the next email`);
         }
-        throw new Error(`no matching email arrived in the run inbox within ${waitS}s`);
+        throw new Error(lastExtractError ?? `no matching email arrived in the run inbox within ${waitS}s`);
     };
     const writeResponse = (response) => {
         let box = {};

package/dist/skill-tables.js

@@ -0,0 +1,74 @@
+// Table rows derive from the schema snapshot at module load, so the skill can never
+// drift from the plan language; only the one-liners are hand-written, and parity
+// tests fail when a schema enum gains or loses a member the docs don't cover.
+import { ACTION_PLAN_SCHEMA } from "./schema.generated.js";
+const defs = ACTION_PLAN_SCHEMA.$defs;
+export const ACTION_TYPES = defs.ActionType.enum;
+export const EXPECT_KINDS = defs.ExpectKind.enum;
+export const EMAIL_EXTRACTS = defs.EmailExtract.enum;
+function actionRequires(action) {
+    const rule = defs.PlanStep.allOf.find((r) => r.if.properties.action?.const === action && !r.if.properties.extract);
+    return rule?.then.required ?? [];
+}
+function expectRequires(kind) {
+    const rule = defs.PlanStep.allOf.find((r) => r.if.properties.expect_kind?.const === kind);
+    return rule?.then.required ?? [];
+}
+export const ACTION_DOCS = {
+    goto: "Navigate to `url` — a path on your app, absolute only for another origin",
+    fill: "Type `value` into the `selector` element",
+    click: "Click the `selector` element",
+    press: "Press keyboard `key` (e.g. `Enter`) on the `selector` element",
+    check: "Check the `selector` checkbox",
+    uncheck: "Uncheck the `selector` checkbox",
+    select: "Choose `option` in the `selector` dropdown",
+    hover: "Hover the `selector` element",
+    scroll: "Scroll the page (no selector) or bring `selector` into view — see below",
+    wait_for: "Wait for the `selector` element to appear",
+    expect: "Assert — kinds in the expect table below",
+    capture_count: "Bank the live count of `selector` matches under `capture_as` for a later `count_delta`",
+    await_email: "Await mail in the run inbox, bank the extracted value under `capture_as` (§5)",
+    upload: "Set a file input: `value` names a project config file — see below",
+    dialog: "Arm a one-shot accept/dismiss handler for the NEXT step's dialog — see below",
+    switch_tab: "Make another open tab the active page; `value` picks it — see below",
+    close_tab: "Close the active tab (optional `value` picks one) and fall back to the previous",
+    drag: "Drag the `selector` element onto the `value` TARGET selector",
+};
+export const EXPECT_DOCS = {
+    visible: "The element is visible",
+    attached: "In the DOM, maybe not shown — for carousel/slider content where `visible` is timing-flaky",
+    hidden: "The element is not visible",
+    checked: "The checkbox/radio is checked",
+    enabled: "The element is enabled",
+    disabled: "The element is disabled",
+    have_text: "The element's text EXACTLY equals `expect_text`",
+    have_value: "The input's value equals `expect_text`",
+    have_url: "The page URL contains `expect_text` (page-level, no selector)",
+    have_title: "The page title contains `expect_text` (page-level, no selector)",
+    have_count: "Exactly `expect_count` elements match `selector`",
+    persisted: "The record just created is present — a visible match for the `{{unique}}`-named row",
+    gone: "Zero matches — absent from the DOM, stronger than `hidden`",
+    count_delta: "The match count moved by signed `expect_delta` vs the `capture_ref` baseline",
+};
+export const EXTRACT_DOCS = {
+    code: "the one-time code",
+    link: "the sign-in/verify URL",
+    pattern: "your own regex in `extract_pattern`, exactly one capture group",
+};
+function table(header, rows) {
+    return [
+        `| ${header} | required fields | meaning |`,
+        "|---|---|---|",
+        ...rows.map(([name, req, doc]) => `| \`${name}\` | ${req} | ${doc} |`),
+    ].join("\n");
+}
+const fields = (names) => names.map((f) => `\`${f}\``).join(", ") || "—";
+export function actionTable() {
+    return table("action", ACTION_TYPES.map((a) => [a, fields(actionRequires(a)), ACTION_DOCS[a] ?? ""]));
+}
+export function expectTable() {
+    return table("expect_kind", EXPECT_KINDS.map((k) => [k, fields(expectRequires(k)), EXPECT_DOCS[k] ?? ""]));
+}
+export function extractLine() {
+    return EMAIL_EXTRACTS.map((e) => `\`${e}\` (${EXTRACT_DOCS[e] ?? ""})`).join(", ");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",

package/dist/email-extract.js

@@ -1,99 +0,0 @@
-import vm from "node:vm";
-// A labelled digit run ("your code is 654321") beats the bare fenced pattern, because a
-// real sign-in mail is full of innocent 4-8 digit runs — "© 2026", a support number —
-// and the bare fence would happily return the first of them.
-const CODE_PATTERN = /(?<!\d)(\d{4,8})(?!\d)/;
-const LABELLED_CODE_PATTERN = /(?:verification|security|one[\s-]?time|login|sign[\s-]?in|access|confirmation)?\s*(?:code|otp|passcode|pin)\b[^0-9]{0,20}(?<!\d)(\d{4,8})(?!\d)/i;
-const LINK_PATTERN = /https:\/\/[^\s"'<>)\]]+/;
-// An anchor's href is the click target in an HTML mail; a bare URL scan over raw markup
-// would return a CSS background or tracking pixel instead.
-const HREF_PATTERN = /<a\b[^>]*\bhref\s*=\s*["']?(https:\/\/[^\s"'>]+)/gi;
-// Footer furniture a sign-in mail carries but nobody means.
-const LINK_NOISE = [
-    "unsubscribe",
-    "/privacy",
-    "/terms",
-    "list-manage",
-    "mailchimp",
-    "sendgrid.net",
-    "/track/",
-    "/wf/open",
-    "twitter.com",
-    "facebook.com",
-    "linkedin.com",
-];
-// Matches the server's EMAIL_PATTERN_MAX_BODY_CHARS bound: backtracking cost scales with
-// haystack length, and no real sign-in code lives past the first few KB of an email.
-const PATTERN_MAX_BODY_CHARS = 20_000;
-const PATTERN_TIMEOUT_MS = 2_000;
-// An author-supplied regex against a sender-supplied body is the textbook ReDoS setup,
-// and native RegExp cannot be interrupted once it starts. Running the match inside a vm
-// context gives it a real wall-clock deadline — V8 services the timeout interrupt while
-// backtracking — matching the server's regex-engine timeout, whatever the pattern is.
-function matchWithDeadline(haystack, pattern) {
-    try {
-        return vm.runInNewContext("haystack.match(new RegExp(pattern))", { haystack, pattern }, { timeout: PATTERN_TIMEOUT_MS });
-    }
-    catch (err) {
-        const code = err?.code;
-        if (code === "ERR_SCRIPT_EXECUTION_TIMEOUT" || /timed out/i.test(String(err))) {
-            throw new Error("the extract_pattern took too long to match this email — it backtracks " +
-                "explosively (an ambiguous quantifier like (a+)+ or (a|a)+ does this). " +
-                "Rewrite it to match unambiguously.");
-        }
-        throw err;
-    }
-}
-export function visibleText(html) {
-    return html
-        .replace(/<(style|script|head)\b[\s\S]*?<\/\1>/gi, " ")
-        .replace(/<[^>]+>/g, " ");
-}
-function bodyOf(email) {
-    if (email.body_text)
-        return email.body_text;
-    if (email.body_html)
-        return visibleText(email.body_html);
-    return "";
-}
-export function extractCode(email) {
-    for (const pattern of [LABELLED_CODE_PATTERN, CODE_PATTERN]) {
-        for (const text of [bodyOf(email), email.subject ?? ""]) {
-            const match = text.match(pattern);
-            if (match)
-                return match[1];
-        }
-    }
-    return null;
-}
-export function extractLink(email) {
-    const html = email.body_html ?? "";
-    const hrefs = [...html.matchAll(HREF_PATTERN)].map((m) => m[1]);
-    const candidates = hrefs.length > 0 ? hrefs : (bodyOf(email).match(LINK_PATTERN) ?? []);
-    for (const url of candidates) {
-        if (!LINK_NOISE.some((noise) => url.toLowerCase().includes(noise)))
-            return url;
-    }
-    if (candidates.length > 0) {
-        throw new Error("the email's only links look like footer/unsubscribe links, not a sign-in link");
-    }
-    throw new Error("the email arrived but carried no https link to follow");
-}
-export function extractValue(email, extract, pattern) {
-    if (extract === "link")
-        return extractLink(email);
-    const body = bodyOf(email);
-    if (extract === "pattern") {
-        if (!pattern)
-            throw new Error("extract=pattern needs an extract_pattern");
-        const match = matchWithDeadline(body.slice(0, PATTERN_MAX_BODY_CHARS), pattern);
-        if (!match) {
-            throw new Error("the email arrived but nothing in it matched the extract_pattern");
-        }
-        return match[1] ?? match[0];
-    }
-    const code = extractCode(email);
-    if (!code)
-        throw new Error("the email arrived but carried no 4-8 digit sign-in code");
-    return code;
-}