@beryl-so/cli 0.67.0 → 0.77.1

package/dist/commands/tests.js

@@ -1,12 +1,6 @@
 import fs from "node:fs";
-import { CliError, UsageError } from "../errors.js";
-import { ApiError } from "../http.js";
-import { lintPlan, planUsesThirdParty } from "../lint.js";
-import { establishAccountSession, executeLocalSpec, THIRD_PARTY_CLOUD_ONLY, } from "../local-exec.js";
-import { PlaywrightMissingError } from "../local-run.js";
-import { dim, green, red, table, yellow } from "../output.js";
-import { confirmInstall, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
-import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
+import { UsageError } from "../errors.js";
+import { table } from "../output.js";
 import { arg, argList, flagBool, flagNum, flagStr, flagStrings, inGroup, projectPath, readJsonFlag, } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
 const EVENT_VERBS = {
@@ -32,27 +26,6 @@ function eventLine(e) {
                 : "";
     return `${when}  ${verb}${groups} ${who}${why}`;
 }
-// A duplicate-title 409 after a green replay is idempotent when the existing row
-// holds the same plan (a retry after a lost response) — success, not an error.
-// A different plan under the same title is a real conflict.
-function createConflictResult(err, planHash) {
-    if (!(err instanceof ApiError) || err.status !== 409)
-        return undefined;
-    const detail = err.detail;
-    if (typeof detail !== "object" || detail === null || detail.code !== "duplicate_title")
-        return undefined;
-    if (detail.existing_plan_hash && detail.existing_plan_hash === planHash) {
-        return {
-            data: { id: detail.existing_test_id, already_existed: true },
-            human: green(`✓ Already banked as ${detail.existing_test_id} (same plan) — nothing to do.`),
-        };
-    }
-    return {
-        human: (detail.message ?? "A test with this title already exists.") +
-            "\nIts plan differs from yours — use `tests set-plan` to update it, or pick a new title.",
-        exitCode: 1,
-    };
-}
 // The server transcodes a failure screenshot to WebP to fit it under the payload cap,
 // so the format is not knowable up front — sniff it off the decoded magic bytes rather
 // than asserting PNG.
@@ -65,27 +38,6 @@ export function sniffImageMime(b64) {
         return "image/jpeg";
     return "image/png";
 }
-// A verify-failure 422 carries evidence (a11y page state + failure screenshot).
-// Returned as a CommandResult rather than thrown: a thrown error is text-only in
-// the MCP adapter, and the screenshot only reaches the agent as image content.
-function verifyFailureResult(err) {
-    if (!(err instanceof ApiError) || err.status !== 422)
-        return undefined;
-    const detail = err.detail;
-    if (typeof detail !== "object" || detail === null || !detail.message)
-        return undefined;
-    const parts = [detail.message];
-    if (detail.error_context) {
-        parts.push("", "----- Page state at failure (accessibility snapshot) -----", detail.error_context);
-    }
-    return {
-        human: parts.join("\n"),
-        images: detail.screenshot_b64
-            ? [{ data: detail.screenshot_b64, mimeType: sniffImageMime(detail.screenshot_b64) }]
-            : undefined,
-        exitCode: 1,
-    };
-}
 // The concise human table for `tests list` — the full TestResponse is a 24-column
 // firehose of internal ids that wraps unreadably in a normal terminal. `--wide`
 // (and `--json`) still expose every field.
@@ -110,54 +62,6 @@ function conciseTestRow(row) {
     };
 }
 export const testCommands = [
-    {
-        name: "tests lint",
-        summary: "Validate a plan JSON file offline, before sending it to the server",
-        description: "Checks a plan against the published ActionPlan JSON Schema: every action's required " +
-            "fields, plus the two structural rules (the first EXECUTED step must be a goto, and at " +
-            "least one step across before + steps must be an expect). Also the identity rules: a " +
-            "plan that signs up with {{inbox_address}} and reads the mail must delete the account " +
-            "in `after`, and no test plan may type {{mailbox_address}} (errors; the server refuses " +
-            "both too). Pass --provisioning for an account's signup or sign-in plan, which may fill " +
-            "{{mailbox_address}}. Runs entirely locally, so a malformed plan fails here instead of " +
-            "costing a server round-trip. " +
-            `Schema: ${ACTION_PLAN_SCHEMA.$id}`,
-        scope: "none",
-        flags: [
-            { name: "file", type: "string", required: true, description: "Plan JSON file, or - for stdin" },
-            {
-                name: "provisioning",
-                type: "boolean",
-                description: "The file is an account's signup or sign-in plan (for `accounts signup` / " +
-                    "`accounts set-login`), so it may fill {{mailbox_address}}",
-            },
-            {
-                name: "access",
-                type: "string",
-                description: "The label the plan will be banked with: read (default) or write. It is yours to " +
-                    "set; Beryl does not infer it. Only a write is checked (its closing teardown proof and {{unique}} names)",
-            },
-        ],
-        examples: [
-            "beryl tests lint --file plan.json",
-            "beryl tests lint --file plan.json --access write",
-            "beryl tests lint --file signup-plan.json --provisioning",
-        ],
-        async run(_ctx, input) {
-            const issues = lintPlan(readJsonFlag(input, "file"), {
-                provisioning: flagBool(input, "provisioning"),
-                access: accessFlag(input, "read"),
-            });
-            const lines = issues.map((i) => `${i.severity === "warning" ? "warning" : "error"} ${i.path}: ${i.message}`);
-            if (issues.every((i) => i.severity === "warning")) {
-                return {
-                    data: { valid: true, issues },
-                    human: ["Plan is valid.", ...lines].join("\n"),
-                };
-            }
-            return { data: { valid: false, issues }, human: lines.join("\n"), exitCode: 1 };
-        },
-    },
     {
         name: "tests list",
         summary: "List the project's tests with their latest result",
@@ -190,7 +94,7 @@ export const testCommands = [
                 name: "status",
                 type: "string",
                 description: "With --page, show only this bucket: passed, failing (failed or errored), " +
-                    "failed, errored, cancelled, quarantined, or unstable",
+                    "failed, errored, cancelled, or quarantined",
             },
             {
                 name: "ungrouped",
@@ -264,290 +168,10 @@ export const testCommands = [
             return { data: version.json_plan, human: JSON.stringify(version.json_plan, null, 2) };
         },
     },
-    {
-        name: "tests create",
-        summary: "Create a test case from a JSON action plan (for tests authored locally, e.g. by your coding agent)",
-        description: "The plan is a JSON object whose steps are {action, selector, url, value, ...}: the first " +
-            "EXECUTED step must be a goto, and at least one step must be an expect. Before anything is " +
-            "banked, the plan is proven by replaying it in a browser ON YOUR MACHINE with the " +
-            "Playwright runner bundled in the CLI (your repo's own @playwright/test wins when " +
-            "present): the server renders the spec (`tests/compile`), the CLI runs it (minting " +
-            "a run inbox for await_email steps and resolving the saved login exactly as a cloud run " +
-            "would), and only a green replay creates the test (bound to the replayed plan by its hash). " +
-            "This holds over MCP too: the replay runs on the machine hosting the MCP server, never on " +
-            "Beryl's; if the Chromium browser is missing there the tool returns the install command " +
-            "(`beryl init` installs it; on a terminal the CLI offers to). " +
-            "A red replay banks NOTHING: the failure evidence comes back (over MCP the screenshot is " +
-            "image content), you fix the plan file and re-run. No run is recorded: once a batch of " +
-            "tests is banked, run their ids together once (`runs local`, or `runs trigger` for the " +
-            "cloud) so they land as ONE run with real first results. 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, and says so; so does a plan with third party " +
-            "integration steps, which run only in Beryl's cloud. 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. " +
-            "Recovery: a 409 `duplicate_title` carries existing_test_id + existing_plan_hash, so " +
-            "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). A server-side verify that could not run (verdict `flag`) " +
-            "still banks the test but returns verified:false and exits 1; prove it with `tests recompile`.",
-        scope: "project",
-        flags: [
-            { name: "title", type: "string", required: true, description: "Title for the new test" },
-            { name: "file", type: "string", required: true, description: "Plan JSON file, or - for stdin" },
-            {
-                name: "description",
-                type: "string",
-                description: "One to three sentences stating what this test proves: the immutable outcome Beryl's healing " +
-                    "checks against. State the purpose, not the steps; the one observable signal that's true " +
-                    "only if the flow worked.",
-            },
-            {
-                name: "no-verify",
-                type: "boolean",
-                description: "Skip verification entirely: bank the authored plan as-is, unproven",
-            },
-            {
-                name: "url-override",
-                type: "string",
-                description: "Replay against this base URL instead of the environment's (e.g. http://localhost:3000). " +
-                    "The banked test is then unproven against its real environment, and the CLI says so.",
-            },
-            {
-                name: "group",
-                type: "strings",
-                description: "Put the test in an existing project group (by name), repeatable. An unknown " +
-                    "name is an error (create groups with `beryl groups create`). Omit for no group.",
-            },
-            { name: "env", type: "string", description: "Environment id to compile and prove against" },
-            {
-                name: "access",
-                type: "string",
-                description: "read (default): the test only reads the app. write: any step creates, edits, " +
-                    "renames, deletes or toggles something; a writer must clean up in `after`",
-            },
-            {
-                name: "dir",
-                type: "string",
-                description: "Keep the rendered spec, artifacts, and JSON report under this directory",
-            },
-        ],
-        examples: [
-            'beryl tests create --title "Checkout happy path" --file plan.json',
-            'beryl tests create --title "Checkout happy path" --file plan.json --description "Proves a shopper can buy a product: after paying, an order-confirmation page with an order number appears."',
-            'beryl tests create --title "Checkout happy path" --file plan.json --url-override http://localhost:3000',
-        ],
-        async run(ctx, input) {
-            const title = flagStr(input, "title");
-            if (!title)
-                throw new UsageError("--title is required");
-            const { workspaceId, projectId } = await ctx.requireProject(input);
-            const plan = readJsonFlag(input, "file");
-            const description = flagStr(input, "description");
-            const urlOverride = flagStr(input, "url-override");
-            const env = flagStr(input, "env");
-            const groups = flagStrings(input, "group");
-            const access = accessFlag(input, "read");
-            const bank = (extra) => ctx.client.post(`${projectPath(workspaceId, projectId)}/tests`, {
-                title,
-                plan,
-                description,
-                groups,
-                access,
-                ...extra,
-            });
-            if (flagBool(input, "no-verify")) {
-                const created = await bank({ verify: false });
-                return {
-                    data: created,
-                    human: yellow(`Banked UNPROVEN (--no-verify): ${created.id}`),
-                };
-            }
-            const compile = () => ctx.client.post(`${projectPath(workspaceId, projectId)}/tests/compile`, {
-                plan,
-                title,
-                base_url: urlOverride,
-                environment_id: env,
-            });
-            let compiled = await compile();
-            const verifyInCloud = async (reason) => {
-                ctx.err(yellow(`! ${reason}, so this plan is verified server-side instead.`));
-                try {
-                    const created = await bank({ verify: true, plan_hash: compiled.plan_hash });
-                    if (created.verified === false) {
-                        // The replay could not run (verdict "flag"): saved, but nothing was proven.
-                        return {
-                            data: created,
-                            human: yellow(`Banked UNVERIFIED: ${created.id}. The server-side replay could not run` +
-                                (created.verify_message ? ` (${String(created.verify_message)})` : "") +
-                                "; the test is saved but unproven. Prove it with `tests recompile`."),
-                            exitCode: 1,
-                        };
-                    }
-                    return { data: created };
-                }
-                catch (err) {
-                    const failure = verifyFailureResult(err);
-                    if (failure)
-                        return failure;
-                    const conflict = createConflictResult(err, compiled.plan_hash);
-                    if (conflict)
-                        return conflict;
-                    throw err;
-                }
-            };
-            if (planUsesThirdParty(plan))
-                return verifyInCloud(THIRD_PARTY_CLOUD_ONLY);
-            // Session-mode plan: establish the account's session once (server-side, reused
-            // from the stored one when it still proves live) and replay against it — the
-            // cloud shape. An unsupported account is re-compiled to sign itself in.
-            let session;
-            if (compiled.session_mode && compiled.account_id) {
-                ctx.err(dim("Establishing the test account's session…"));
-                const established = await establishAccountSession(ctx.client, projectPath(workspaceId, projectId), compiled.account_id);
-                if (established.session) {
-                    session = established.session;
-                }
-                else if (established.unsupported) {
-                    ctx.err(yellow(`! ${established.error} — the replay signs in itself.`));
-                    compiled = await compile();
-                }
-                else {
-                    throw new CliError(established.error ?? "SESSION_UNAVAILABLE");
-                }
-            }
-            // A captured session lives encrypted in Beryl's cloud and is never handed to
-            // this machine — the cloud is the only place this plan can be proven.
-            if (compiled.requires_auth && !session) {
-                return verifyInCloud("A captured session never leaves Beryl's cloud");
-            }
-            if (compiled.login_config_error)
-                throw new CliError(compiled.login_config_error);
-            let loginPassword;
-            if (compiled.uses_login_password) {
-                try {
-                    const secret = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/config/secrets/LOGIN_PASSWORD/value`, { environment_id: env }));
-                    loginPassword = secret.value;
-                }
-                catch (err) {
-                    throw new CliError("Could not reveal the LOGIN_PASSWORD secret for the saved login: " +
-                        (err instanceof Error ? err.message : String(err)));
-                }
-            }
-            const specOf = (content) => ({
-                id: "local-verify",
-                title,
-                content,
-                requiresAuth: false,
-                usesEmail: /__vmInbox\(|__vmAwaitEmail\(/.test(content),
-                usesLoginPassword: compiled.uses_login_password,
-                inlinedLoginSteps: compiled.inlined_login_steps ?? 0,
-                email: compiled.email ?? undefined,
-            });
-            const attempts = 1 + Math.max(0, compiled.policy.error_retries);
-            let outcome;
-            let runError;
-            let installOffered = false;
-            for (let attempt = 1; attempt <= attempts; attempt++) {
-                if (attempt > 1) {
-                    // Fresh render per attempt: the errored attempt may already have consumed
-                    // the {{unique}}/inbox handles its spec minted — replaying the same spec
-                    // would collide on exactly the uniqueness those handles exist to dodge.
-                    ctx.err(dim(`Replay errored — recompiling and retrying (${attempt}/${attempts})…`));
-                    compiled = await compile();
-                }
-                ctx.err(dim(`Replaying "${title}" locally before banking…`));
-                try {
-                    ({ outcome, runError } = await executeLocalSpec({ client: ctx.client, workspaceId, projectId }, {
-                        spec: specOf(compiled.content),
-                        dir: flagStr(input, "dir"),
-                        harvest: true,
-                        loginPassword,
-                        session,
-                        onEvent: (line) => ctx.err(dim(line)),
-                    }));
-                }
-                catch (err) {
-                    if (err instanceof PlaywrightMissingError) {
-                        // On a TTY offer the install once and redo this attempt; over MCP or a
-                        // pipe the hint is the answer.
-                        if (ctx.interactive && !installOffered) {
-                            installOffered = true;
-                            const cwd = process.cwd();
-                            const commands = installCommandsFor(playwrightGaps(cwd), cwd);
-                            if (await confirmInstall(ctx.prompt, commands)) {
-                                await installPlaywright(cwd, (line) => ctx.err(dim(line)));
-                                attempt -= 1;
-                                continue;
-                            }
-                        }
-                        throw new CliError(err.message);
-                    }
-                    throw err;
-                }
-                // A completed replay — green or red — is a verdict; only an errored one
-                // (the spec never ran) earns a retry.
-                if (outcome)
-                    break;
-            }
-            if (!outcome) {
-                return {
-                    data: { banked: false, verified: false, error: runError },
-                    human: red(`Replay errored after ${attempts} attempt(s) — nothing was banked.`) +
-                        `\n${runError ?? "the spec did not run"}` +
-                        `\nFix the environment (or retry), then re-run \`beryl tests create\`.`,
-                    exitCode: 1,
-                };
-            }
-            const result = outcome.results[0];
-            if (outcome.failed > 0 || outcome.passed === 0) {
-                const shot = outcome.harvested?.screenshot;
-                const parts = [
-                    `Plan failed its local replay — nothing was banked.`,
-                    ...(result?.error ? ["", result.error] : []),
-                    "",
-                    "Fix the plan file and re-run `beryl tests create`. The replay artifacts " +
-                        (flagStr(input, "dir")
-                            ? `are under ${outcome.directory}.`
-                            : "can be kept with --dir."),
-                ];
-                return {
-                    data: { banked: false, verified: false, error: result?.error },
-                    human: parts.join("\n"),
-                    images: shot
-                        ? [{ data: shot.toString("base64"), mimeType: "image/png" }]
-                        : undefined,
-                    exitCode: 1,
-                };
-            }
-            let created;
-            try {
-                created = await bank({ verify: false, plan_hash: compiled.plan_hash });
-            }
-            catch (err) {
-                const conflict = createConflictResult(err, compiled.plan_hash);
-                if (conflict)
-                    return conflict;
-                throw err;
-            }
-            if (urlOverride) {
-                ctx.err(yellow(`! The proof ran against ${urlOverride}, not the environment's root URL — ` +
-                    "the banked test is unproven against its real target until a run there passes."));
-            }
-            // The server saw verify:false; the proof is the local replay, unless it ran off-target.
-            return {
-                data: { ...created, verified: !urlOverride, verdict: "keep", verified_by: "local" },
-                human: green(`✓ Replay passed locally — banked as ${created.id}`),
-            };
-        },
-    },
     {
         name: "tests set-plan",
         summary: "Replace a test's step plan from a JSON file (creates a new version)",
-        description: "Accepts the same plan shape as `tests create`, including the optional `before` and " +
+        description: "Accepts an ActionPlan (the shape `tests plan` returns), 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. Saves the edit with NO replay: " +
@@ -591,6 +215,31 @@ export const testCommands = [
             };
         },
     },
+    {
+        name: "tests set-intent",
+        summary: "Edit what a test proves, the target heal judges against",
+        description: "The intent is the plain-language statement of what the test proves; heal judges every " +
+            "repair against it. It belongs to the test, so every surface of the test gets a new " +
+            "version carrying the new text (same plan, recorded as your edit; see `tests versions`). " +
+            "The plan is NOT regenerated: change the steps with `tests set-plan`. Re-explore keeps " +
+            "matching the same test after an edit.",
+        scope: "project",
+        args: [
+            { name: "test-id", description: "Test id", required: true },
+            { name: "intent", description: "New intent text", required: true },
+        ],
+        examples: [
+            'beryl tests set-intent 4f… "Proves a shopper can check out and sees an order number."',
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.patch(testPath(workspaceId, projectId, arg(input, "test-id")), {
+                    intent: arg(input, "intent"),
+                }),
+            };
+        },
+    },
     {
         name: "tests set-groups",
         summary: "Replace the groups a test belongs to",
@@ -917,38 +566,14 @@ export const testCommands = [
     },
     {
         name: "tests script",
-        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. This returns the " +
-            "executable spec. `tests plan` returns the stored JSON plan it is rendered from, " +
-            "`tests get` the metadata row.",
+        summary: "Print the rendered Playwright spec for a test",
+        description: "Fetches the banked test's rendered .spec.ts: 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: [
-            { name: "file", type: "string", description: "Compile this plan JSON file instead of a banked test" },
-            {
-                name: "url-override",
-                type: "string",
-                description: "With --file: resolve relative gotos against this base URL",
-            },
-            { name: "env", type: "string", description: "With --file: environment id to render against" },
-        ],
-        examples: ["beryl tests script 4f…", "beryl tests script --file plan.json"],
+        args: [{ name: "test-id", description: "Test id", required: true }],
+        examples: ["beryl tests script 4f…"],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const id = input.args["test-id"];
-            const file = flagStr(input, "file");
-            if (Boolean(id) === Boolean(file))
-                throw new UsageError("Pass exactly one of <test-id> or --file");
-            if (file) {
-                const data = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests/compile`, {
-                    plan: readJsonFlag(input, "file"),
-                    base_url: flagStr(input, "url-override"),
-                    environment_id: flagStr(input, "env"),
-                }));
-                return { data: data, human: data.content };
-            }
             const data = (await ctx.client.get(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/script`));
             const script = typeof data === "string" ? data : (data.script ?? data.content ?? data);
             return { data, human: typeof script === "string" ? script : JSON.stringify(data, null, 2) };

package/dist/commands/third-party-integrations.js

@@ -9,7 +9,8 @@ export const thirdPartyIntegrationCommands = [
         groupDefault: true,
         groupSummary: "Test a site's own integrations (Connect Slack) against Beryl's accounts on those providers.",
         description: "Lists the providers set up on this Beryl deployment. A test may use " +
-            "`third_party_authorize` / `await_third_party` only for a provider listed here; " +
+            "`third_party_authorize` / `await_third_party` / `send_third_party` only for a " +
+            "provider listed here; " +
             "anything else is refused at save time.",
         scope: "project",
         async run(ctx, input) {
@@ -31,6 +32,8 @@ export const thirdPartyIntegrationCommands = [
             "channel in the app's settings; `await_third_party` then waits for the app's message " +
             "there. `recorded_app_ids` maps each environment id to the app whose first message " +
             "was seen there; an environment accepts only its own app once recorded. " +
+            "Pass `env` and `app` to record that app yourself (a Slack app id, `A...`), which " +
+            "`send_third_party` needs to know whose bot to mention. " +
             "A 409 means the provider is not set up on this deployment (see " +
             "`third-party-integrations list`).",
         scope: "project",
@@ -41,14 +44,34 @@ export const thirdPartyIntegrationCommands = [
                 required: true,
                 description: "Provider key from `third-party-integrations list`, e.g. slack",
             },
+            {
+                name: "env",
+                type: "string",
+                description: "Environment id to record `app` for (with `app`)",
+            },
+            {
+                name: "app",
+                type: "string",
+                description: "The connected app's id on the provider, e.g. a Slack app id (with `env`)",
+            },
+        ],
+        examples: [
+            "beryl third-party-integrations target --provider slack",
+            "beryl third-party-integrations target --provider slack --env <env-id> --app A0123ABCD",
         ],
-        examples: ["beryl third-party-integrations target --provider slack"],
         async run(ctx, input) {
             const provider = flagStr(input, "provider");
             if (!provider)
                 throw new UsageError("--provider is required");
+            const env = flagStr(input, "env");
+            const app = flagStr(input, "app");
+            if (Boolean(env) !== Boolean(app))
+                throw new UsageError("--env and --app go together");
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const target = (await ctx.client.post(`${integrationsPath(workspaceId, projectId)}/${encodeURIComponent(provider)}/target`));
+            const base = `${integrationsPath(workspaceId, projectId)}/${encodeURIComponent(provider)}/target`;
+            const target = (env && app
+                ? await ctx.client.put(`${base}/apps/${encodeURIComponent(env)}`, { app_id: app })
+                : await ctx.client.post(base));
             return {
                 data: target,
                 human: `#${target.external_name}\n\n` +

package/dist/commands/watch.js

@@ -16,6 +16,7 @@ const FAILING = new Set(["failed", "errored"]);
 const TERMINAL_RUN = new Set(["completed", "failed", "cancelled"]);
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const CI_ERROR_MAX_LEN = 4_000;
+const SUMMARY_WAIT_TRIES = 10;
 function runPageUrl(apiUrl, projectId, runId) {
     if (!apiUrl)
         return null;
@@ -35,6 +36,16 @@ function runPageUrl(apiUrl, projectId, runId) {
 }
 const escapeAnnotationData = (s) => s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
 const escapeAnnotationProp = (s) => escapeAnnotationData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+// Reported on its own line, never folded into the verdict summary or the exit code.
+export function findingsGateLine(gate) {
+    if (gate.status === "passed")
+        return "findings gate passed: no new Site Health findings since the last green run";
+    if (gate.status === "failed") {
+        const n = gate.new_count ?? 0;
+        return `findings gate failed: ${n} new Site Health finding${n === 1 ? "" : "s"} since the last green run`;
+    }
+    return `findings gate unknown: ${gate.reason ?? "not evaluated"}`;
+}
 // Auth, client and wrong-host errors fail identically on every retry; only a network
 // blip, a timeout, throttling or a 5xx is worth waiting out.
 function isRetryable(e) {
@@ -91,6 +102,8 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
             ctx.err(red(detail.replace(/^/gm, "    ")));
             process.stdout.write(`::error title=${escapeAnnotationProp(r.title || r.id)}::${escapeAnnotationData(detail)}\n`);
         }
+        if (!ok && r.heal_skip_reason)
+            ctx.err(dim(`    ${r.heal_skip_reason}`));
     };
     if (!ctx.json)
         ctx.err(dim(`watching run ${runId}`));
@@ -187,6 +200,19 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
         }
     }
     clearStatusLine();
+    // A finalized run turns terminal a moment before its summary (and findings gate) is
+    // written; a run that ended failed is never finalized, so there is nothing to wait for.
+    const awaitingSummary = (r) => Boolean(r && TERMINAL_RUN.has(r.status) && r.status !== "failed" && !r.summary);
+    for (let i = 0; i < SUMMARY_WAIT_TRIES && awaitingSummary(run); i++) {
+        await sleep(1_000);
+        try {
+            run = (await ctx.client.get(`${path}/runs/${runId}`));
+        }
+        catch (e) {
+            if (!isRetryable(e))
+                throw e;
+        }
+    }
     const counters = {
         passed: run?.passed_count ?? 0,
         failed: run?.failed_count ?? 0,
@@ -214,6 +240,13 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
         : green(`${passed} passed`) + extra;
     if (!ctx.json)
         ctx.err(`\n${statusColor(finalStatus)}: ${summary}`);
+    const gate = run?.findings_gate ?? null;
+    if (gate && !ctx.json) {
+        const line = findingsGateLine(gate);
+        ctx.err(gate.status === "passed" ? green(line) : gate.status === "failed" ? red(line) : yellow(line));
+        for (const f of gate.new_findings ?? [])
+            ctx.err(dim(`  ${f.severity} ${f.page_path} ${f.title}`));
+    }
     const link = runPageUrl(ctx.client.baseUrl, project, runId);
     if (ci && link)
         ctx.err(dim(link));
@@ -225,6 +258,7 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
             "| passed | failed | errored | cancelled | quarantined | total |",
             "| --- | --- | --- | --- | --- | --- |",
             `| ${counters.passed} | ${counters.failed} | ${counters.errored} | ${counters.cancelled} | ${counters.quarantined} | ${counters.total} |`,
+            ...(gate ? ["", findingsGateLine(gate)] : []),
             ...(link ? ["", `[Open the run in Beryl](${link})`] : []),
             ...failures.flatMap((r) => [
                 "",
@@ -232,6 +266,7 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
                 "```",
                 String(r.error_message ?? "").slice(0, CI_ERROR_MAX_LEN),
                 "```",
+                ...(r.heal_skip_reason ? ["", r.heal_skip_reason] : []),
             ]),
             "",
         ];
@@ -249,6 +284,7 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
             status: finalStatus,
             ...(failFastStop ? { fail_fast: true } : {}),
             ...counters,
+            ...(gate ? { findings_gate: gate } : {}),
         },
         exitCode,
     };