@beryl-so/cli 0.54.1 → 0.61.0

package/dist/commands/tests.js

@@ -1,14 +1,37 @@
 import fs from "node:fs";
 import { CliError, UsageError } from "../errors.js";
 import { ApiError } from "../http.js";
-import { lintPlan } from "../lint.js";
-import { establishAccountSession, executeLocalSpec, } from "../local-exec.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 { 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 = {
+    QUARANTINED: "quarantined",
+    UNQUARANTINED: "released from quarantine",
+    GROUPS_ADDED: "added to",
+    GROUPS_REMOVED: "removed from",
+    RENAMED: "renamed",
+};
+function eventLine(e) {
+    const when = e.created_at.slice(0, 19).replace("T", " ");
+    const verb = EVENT_VERBS[e.action] ?? e.action.toLowerCase();
+    const who = e.actor_name ? `by ${e.actor_name}` : "automatically";
+    const d = e.detail ?? {};
+    const groups = Array.isArray(d.groups) ? ` ${d.groups.join(", ")}` : "";
+    // The reason is the point: an automatic mute has to say what triggered it.
+    const why = d.failures !== undefined
+        ? ` (${d.failures} failures in ${d.days} days, run ${d.run_id})`
+        : d.passes !== undefined
+            ? ` (${d.passes} clean passes)`
+            : d.from !== undefined
+                ? ` ("${d.from}" to "${d.to}")`
+                : "";
+    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.
@@ -165,7 +188,8 @@ export const testCommands = [
             {
                 name: "status",
                 type: "string",
-                description: "With --page, show only this bucket: passed, failed, or quarantined",
+                description: "With --page, show only this bucket: passed, failed, errored, cancelled, " +
+                    "quarantined, or unstable (failed no longer includes errored)",
             },
             {
                 name: "ungrouped",
@@ -257,7 +281,8 @@ export const testCommands = [
             "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. A session-mode plan replays locally " +
+            "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 " +
@@ -346,6 +371,23 @@ export const testCommands = [
                 environment_id: env,
             });
             let compiled = await compile();
+            const verifyInCloud = async (reason) => {
+                ctx.err(yellow(`! ${reason}, so this plan is verified server-side instead.`));
+                try {
+                    return { data: await bank({ verify: true, plan_hash: compiled.plan_hash }) };
+                }
+                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.
@@ -367,20 +409,7 @@ export const testCommands = [
             // 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) {
-                ctx.err(yellow("! This plan signs in with a captured session, so it can only be verified " +
-                    "in Beryl's cloud — verifying server-side instead."));
-                try {
-                    return { data: await bank({ verify: true, plan_hash: compiled.plan_hash }) };
-                }
-                catch (err) {
-                    const failure = verifyFailureResult(err);
-                    if (failure)
-                        return failure;
-                    const conflict = createConflictResult(err, compiled.plan_hash);
-                    if (conflict)
-                        return conflict;
-                    throw err;
-                }
+                return verifyInCloud("A captured session never leaves Beryl's cloud");
             }
             if (compiled.login_config_error)
                 throw new CliError(compiled.login_config_error);
@@ -637,7 +666,7 @@ export const testCommands = [
     },
     {
         name: "tests quarantine",
-        summary: "Mute a flaky test: it keeps running, but its failures stop failing the run",
+        summary: "Mute flaky tests: they keep running, but their failures stop failing the run",
         description: "A quarantined test still executes and its result is still recorded and visible. Its " +
             "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 " +
@@ -645,24 +674,63 @@ export const testCommands = [
             "asking support to deactivate it (which stops it running at all). After the project's " +
             "release threshold of consecutive clean passes (default 5) the test reports " +
             "rehab_ready: a suggestion while auto quarantine is off, the actual release once " +
-            "`projects quarantine on` has turned it on. `off` un-quarantines.",
+            "`projects quarantine on` has turned it on. `off` un-quarantines. Several ids are one " +
+            "call; tests already in the requested state are left alone rather than rejected. Who " +
+            "quarantined what is recorded, readable with `beryl tests events`.",
         scope: "project",
         args: [
-            { name: "test-id", description: "Test id", required: true },
             { name: "state", description: "on | off", required: true },
+            { name: "test-ids", description: "One or more test ids", required: true, variadic: true },
         ],
-        examples: ["beryl tests quarantine 4f… on", "beryl tests quarantine 4f… off"],
+        examples: ["beryl tests quarantine on 4f…", "beryl tests quarantine on 4f… 9a… 1c…", "beryl tests quarantine off 4f…"],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const state = arg(input, "state").toLowerCase();
+            let state = arg(input, "state").toLowerCase();
+            let ids = argList(input, "test-ids");
+            // Older scripts wrote `tests quarantine <id> on`; keep them working.
             if (state !== "on" && state !== "off") {
-                throw new UsageError(`Expected "on" or "off", got "${arg(input, "state")}"`);
+                const trailing = ids[ids.length - 1]?.toLowerCase();
+                if (trailing === "on" || trailing === "off") {
+                    ids = [arg(input, "state"), ...ids.slice(0, -1)];
+                    state = trailing;
+                }
+                else {
+                    throw new UsageError(`Expected "on" or "off", got "${arg(input, "state")}"`);
+                }
             }
+            const quarantined = state === "on";
+            const only = ids.length === 1 ? ids[0] : undefined;
+            if (only !== undefined) {
+                return {
+                    data: await ctx.client.patch(`${testPath(workspaceId, projectId, only)}/quarantine`, { quarantined }),
+                };
+            }
+            const data = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests/bulk-quarantine`, { test_case_ids: ids, quarantined }));
             return {
-                data: await ctx.client.patch(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/quarantine`, { quarantined: state === "on" }),
+                data,
+                human: `${quarantined ? "Quarantined" : "Released"} ${data.updated} of ${ids.length} tests (the rest were already ${quarantined ? "quarantined" : "not"}).`,
             };
         },
     },
+    {
+        name: "tests events",
+        summary: "Who quarantined, grouped or renamed a test, and why",
+        description: "Lifecycle history for one test, newest first: quarantine and release (by a person or " +
+            "by auto-quarantine, with the run and failure streak behind it), group changes, and " +
+            "renames. Plan edits are NOT here: those are versions, and `beryl tests versions` can " +
+            "restore them.",
+        scope: "project",
+        args: [{ name: "test-id", description: "Test id", required: true }],
+        flags: [{ name: "limit", type: "number", description: "How many events (default 100, max 500)" }],
+        examples: ["beryl tests events 4f…", "beryl tests events 4f… --limit 20"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const limit = flagNum(input, "limit");
+            const path = `${testPath(workspaceId, projectId, arg(input, "test-id"))}/events`;
+            const data = (await ctx.client.get(limit === undefined ? path : `${path}?limit=${limit}`));
+            return { data, human: data.length ? data.map(eventLine).join("\n") : "No changes recorded." };
+        },
+    },
     {
         name: "tests delete",
         summary: "Delete tests, their version history, and their results",

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

@@ -0,0 +1,59 @@
+import { UsageError } from "../errors.js";
+import { dim, table } from "../output.js";
+import { flagStr, projectPath } from "./util.js";
+const integrationsPath = (ws, p) => `${projectPath(ws, p)}/third-party-integrations`;
+export const thirdPartyIntegrationCommands = [
+    {
+        name: "third-party-integrations list",
+        summary: "The third party providers this project's tests can connect to",
+        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; " +
+            "anything else is refused at save time.",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const { providers } = (await ctx.client.get(integrationsPath(workspaceId, projectId)));
+            return {
+                data: providers,
+                human: providers.length
+                    ? table(providers.map((p) => ({ key: p.key, label: p.label })))
+                    : dim("No third party providers are set up on this deployment."),
+            };
+        },
+    },
+    {
+        name: "third-party-integrations target",
+        summary: "The channel this project's tests pick when the app asks where to post",
+        description: "Returns the project's own destination on Beryl's provider account (for Slack, a " +
+            "channel), creating it on first ask. When a test connects the app, it picks this " +
+            "channel in the app's settings; `await_third_party` then waits for the app's message " +
+            "there. `recorded_app_id` is the app whose first message was seen, null until then. " +
+            "A 409 means the provider is not set up on this deployment (see " +
+            "`third-party-integrations list`).",
+        scope: "project",
+        flags: [
+            {
+                name: "provider",
+                type: "string",
+                required: true,
+                description: "Provider key from `third-party-integrations list`, e.g. slack",
+            },
+        ],
+        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 { workspaceId, projectId } = await ctx.requireProject(input);
+            const target = (await ctx.client.post(`${integrationsPath(workspaceId, projectId)}/${encodeURIComponent(provider)}/target`));
+            return {
+                data: target,
+                human: `#${target.external_name}\n\n` +
+                    dim(`Pick this channel in the app when the test connects ${target.provider}.` +
+                        (target.recorded_app_id ? ` Recorded app: ${target.recorded_app_id}` : "")),
+            };
+        },
+    },
+];

package/dist/commands/tracker.js

@@ -0,0 +1,295 @@
+import { UsageError } from "../errors.js";
+import { flagNum, flagStr, flagStrings, projectPath } from "./util.js";
+const PROVIDERS = ["linear"];
+const SEVERITIES = ["high", "medium", "low"];
+const PRIORITIES = ["urgent", "high", "medium", "low", "none"];
+const ON_OFF = ["on", "off"];
+const ENV_FLAG = {
+    name: "env",
+    type: "string",
+    description: "Environment id (defaults to the project's default environment)",
+};
+const PROVIDER_FLAG = {
+    name: "tracker",
+    type: "string",
+    enum: PROVIDERS,
+    description: "Issue tracker (default linear)",
+};
+/** `envs update` flags for the Site Health issue tracker settings. */
+export const TRACKER_SETTING_FLAGS = [
+    {
+        name: "tracker",
+        type: "string",
+        enum: [...PROVIDERS, "off"],
+        description: "Tracker Site Health files tickets in; `off` stops filing for this environment " +
+            "(connect it first with `health tracker connect`)",
+    },
+    { name: "tracker-team", type: "string", description: "Tracker team id (see `health tracker teams`)" },
+    {
+        name: "tracker-project",
+        type: "string",
+        description: "Tracker project id inside the team (see `health tracker projects`); `none` clears it",
+    },
+    {
+        name: "tracker-label",
+        type: "strings",
+        description: "Label put on every ticket, repeatable; replaces the set (default beryl)",
+    },
+    {
+        name: "tracker-priority",
+        type: "strings",
+        description: "Severity to tracker priority, repeatable, e.g. high=urgent. Priorities: " +
+            PRIORITIES.join(", ") +
+            " (default high=high, medium=medium, low=low)",
+    },
+    {
+        name: "tracker-threshold",
+        type: "string",
+        enum: SEVERITIES,
+        description: "Lowest severity filed automatically; the rest go to the digest (default high)",
+    },
+    {
+        name: "tracker-digest",
+        type: "string",
+        enum: ["off", "daily", "weekly"],
+        description: "Digest of findings that were not filed (default weekly)",
+    },
+    {
+        name: "tracker-digest-to",
+        type: "string",
+        enum: ["ticket", "slack"],
+        description: "Where the digest goes: one digest ticket, or the Slack alert channel (default ticket)",
+    },
+    {
+        name: "tracker-auto-close",
+        type: "string",
+        enum: ON_OFF,
+        description: "Close a ticket once a run no longer sees its finding (default on)",
+    },
+    {
+        name: "tracker-reopen",
+        type: "string",
+        enum: ON_OFF,
+        description: "Reopen the same ticket when a fixed finding comes back; off files a new one (default on)",
+    },
+    {
+        name: "tracker-reopen-closed",
+        type: "string",
+        enum: ON_OFF,
+        description: "Reopen a ticket closed in the tracker while the check still fails (default on)",
+    },
+    {
+        name: "tracker-max-tickets",
+        type: "number",
+        description: "New tickets one run may file, 0-100; the rest go to the digest (default 10)",
+    },
+    {
+        name: "tracker-assignee",
+        type: "string",
+        description: "Tracker user id (a person or an agent user) new tickets go to; `none` clears it",
+    },
+    {
+        name: "tracker-min-runs",
+        type: "number",
+        description: "Runs in a row a finding must show in before a manual run files it (default 1)",
+    },
+    {
+        name: "tracker-min-runs-scheduled",
+        type: "number",
+        description: "Same, for scheduled and CI runs (default 2)",
+    },
+    {
+        name: "tracker-pause",
+        type: "string",
+        enum: ON_OFF,
+        description: "Pause all ticket creation and updates without disconnecting",
+    },
+];
+function onOff(input, name) {
+    const v = flagStr(input, name);
+    if (v === undefined)
+        return undefined;
+    if (!ON_OFF.includes(v))
+        throw new UsageError(`--${name} must be on or off`);
+    return v === "on";
+}
+function orNull(value) {
+    return value === "none" ? null : value;
+}
+function priorityMap(entries) {
+    const map = {};
+    for (const entry of entries) {
+        const [severity, priority] = entry.split("=").map((s) => s.trim().toLowerCase());
+        if (!severity || !priority || !SEVERITIES.includes(severity) || !PRIORITIES.includes(priority)) {
+            throw new UsageError(`--tracker-priority takes severity=priority, e.g. high=urgent (severities: ${SEVERITIES.join(", ")}; priorities: ${PRIORITIES.join(", ")})`);
+        }
+        map[severity] = priority;
+    }
+    return map;
+}
+/** The `site_health_tracker` PATCH body from `envs update` flags; undefined when none were given. */
+export function trackerSettingsFromFlags(input) {
+    const body = {};
+    const provider = flagStr(input, "tracker");
+    if (provider !== undefined)
+        body.provider = provider === "off" ? null : provider;
+    const team = flagStr(input, "tracker-team");
+    if (team !== undefined) {
+        body.team_id = team;
+        if (provider === undefined)
+            body.provider = "linear";
+    }
+    const project = orNull(flagStr(input, "tracker-project"));
+    if (project !== undefined)
+        body.project_id = project;
+    const labels = flagStrings(input, "tracker-label");
+    if (labels)
+        body.labels = labels;
+    const priorities = flagStrings(input, "tracker-priority");
+    if (priorities)
+        body.priority_map = priorityMap(priorities);
+    const threshold = flagStr(input, "tracker-threshold");
+    if (threshold !== undefined)
+        body.auto_file_threshold = threshold;
+    const digest = flagStr(input, "tracker-digest");
+    if (digest !== undefined)
+        body.digest = digest;
+    const digestTo = flagStr(input, "tracker-digest-to");
+    if (digestTo !== undefined)
+        body.digest_target = digestTo;
+    const toggles = [
+        ["tracker-auto-close", "auto_close"],
+        ["tracker-reopen", "reopen_on_regression"],
+        ["tracker-reopen-closed", "reopen_if_closed_while_failing"],
+        ["tracker-pause", "paused"],
+    ];
+    for (const [flag, field] of toggles) {
+        const v = onOff(input, flag);
+        if (v !== undefined)
+            body[field] = v;
+    }
+    const numbers = [
+        ["tracker-max-tickets", "max_tickets_per_run"],
+        ["tracker-min-runs", "min_consecutive_runs_manual"],
+        ["tracker-min-runs-scheduled", "min_consecutive_runs_scheduled"],
+    ];
+    for (const [flag, field] of numbers) {
+        const v = flagNum(input, flag);
+        if (v !== undefined)
+            body[field] = v;
+    }
+    const assignee = orNull(flagStr(input, "tracker-assignee"));
+    if (assignee !== undefined)
+        body.assignee_id = assignee;
+    return Object.keys(body).length ? body : undefined;
+}
+function provider(input) {
+    return flagStr(input, "tracker") ?? "linear";
+}
+export const trackerCommands = [
+    {
+        name: "health tracker status",
+        summary: "Show how Site Health files findings as issue tracker tickets for an environment",
+        description: "Returns the environment's tracker settings with every default filled in, the " +
+            "workspace's connection (`status: disconnected` means the token expired or was " +
+            "revoked; ticket changes queue until you reconnect), the number of queued changes, " +
+            "open tickets (filed in the tracker), `unfiled_tickets` the tracker hasn't accepted " +
+            "yet with its `last_sync_error`, digest findings, and `last_sync`: what the latest run filed, " +
+            "updated, closed or skipped. Change settings with `envs update --tracker-*`.",
+        scope: "project",
+        flags: [ENV_FLAG],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/site-health/tracker`, {
+                    environment_id: flagStr(input, "env"),
+                }),
+            };
+        },
+    },
+    {
+        name: "health tracker tickets",
+        summary: "List the findings Site Health tracks in the issue tracker, with their tickets",
+        description: "One row per finding: `status` watching (seen, waiting for enough runs in a row), " +
+            "digest (not filed), open, closed (with `close_reason` fixed, intended or tracker) " +
+            "or stale (its page is gone), plus the ticket key and URL once filed and `queued` " +
+            "when a change is waiting to reach the tracker.",
+        scope: "project",
+        flags: [
+            ENV_FLAG,
+            {
+                name: "status",
+                type: "string",
+                enum: ["watching", "digest", "open", "closed", "stale"],
+                description: "Only rows in this status",
+            },
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/site-health/tickets`, {
+                    environment_id: flagStr(input, "env"),
+                    status: flagStr(input, "status"),
+                }),
+            };
+        },
+    },
+    {
+        name: "health tracker connect",
+        summary: "Get the link that connects an issue tracker to the workspace",
+        description: "Returns an authorize URL for a workspace admin to open in a browser. Once approved, " +
+            "Beryl files tickets as its own app user, and any changes queued while disconnected " +
+            "are applied. Then pick a team with `envs update --tracker-team`.",
+        scope: "workspace",
+        flags: [PROVIDER_FLAG],
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            const res = (await ctx.client.get(`/workspaces/${ws}/trackers/${provider(input)}/connect`));
+            return { data: res, human: `Open this link to connect:\n${res.url}` };
+        },
+    },
+    {
+        name: "health tracker disconnect",
+        summary: "Remove the workspace's issue tracker connection",
+        description: "Deletes the stored tokens. Tickets already filed stay in the tracker; to stop " +
+            "filing for one environment only, use `envs update --tracker off` or `--tracker-pause on`.",
+        scope: "workspace",
+        flags: [PROVIDER_FLAG, { name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            await ctx.confirm(`Disconnect ${provider(input)}?`, input.flags.force === true);
+            await ctx.client.del(`/workspaces/${ws}/trackers/${provider(input)}`);
+            return { human: "Disconnected." };
+        },
+    },
+    {
+        name: "health tracker teams",
+        summary: "List the teams of the connected issue tracker",
+        scope: "workspace",
+        flags: [PROVIDER_FLAG],
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            return { data: await ctx.client.get(`/workspaces/${ws}/trackers/${provider(input)}/teams`) };
+        },
+    },
+    {
+        name: "health tracker projects",
+        summary: "List a tracker team's projects",
+        scope: "workspace",
+        flags: [
+            PROVIDER_FLAG,
+            { name: "team", type: "string", description: "Team id (see `health tracker teams`)", required: true },
+        ],
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            const team = flagStr(input, "team");
+            if (!team)
+                throw new UsageError("--team is required");
+            return {
+                data: await ctx.client.get(`/workspaces/${ws}/trackers/${provider(input)}/projects`, {
+                    team_id: team,
+                }),
+            };
+        },
+    },
+];

package/dist/commands/workspaces.js

@@ -1,3 +1,4 @@
+import { autoFormat } from "../output.js";
 import { arg, flagBool, flagStr } from "./util.js";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export const workspaceCommands = [
@@ -145,11 +146,16 @@ export const workspaceCommands = [
         ],
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
+            const email = arg(input, "email");
+            const invitation = (await ctx.client.post(`/workspaces/${ws}/invitations`, {
+                email,
+                role: (flagStr(input, "role") ?? "USER").toUpperCase(),
+            }));
+            if (!invitation.email_delivery_failed)
+                return { data: invitation };
             return {
-                data: await ctx.client.post(`/workspaces/${ws}/invitations`, {
-                    email: arg(input, "email"),
-                    role: (flagStr(input, "role") ?? "USER").toUpperCase(),
-                }),
+                data: invitation,
+                human: `${autoFormat(invitation)}\nWarning: the invitation email to ${email} was not delivered. Check the address, or revoke and re-invite later.`,
             };
         },
     },

package/dist/http.js

@@ -97,8 +97,8 @@ export class ApiClient {
     patch(path, body) {
         return this.request("PATCH", path, { body });
     }
-    put(path, body) {
-        return this.request("PUT", path, { body });
+    put(path, body, query) {
+        return this.request("PUT", path, { body, query });
     }
     del(path, body) {
         return this.request("DELETE", path, { body });

package/dist/lint.js

@@ -16,6 +16,9 @@ export const WRITE_NEEDS_CLOSING_TEARDOWN = (detail) => "A 'write' test must end
 export const OPTIONAL_TEARDOWN_ACTION_MUST_BE_LAST = (label, action) => `${label} (${action}) is optional but not the last step of 'after'. An optional step ` +
     "that misses ends the teardown, so the steps after it would silently not run. Guard " +
     "them with an optional 'wait_for' or 'expect' instead, or move this step to the end.";
+export const THIRD_PARTY_UNDECLARED = (p) => `third_party_authorize approves the install on ${p}'s consent page, which needs ` +
+    `Beryl's ${p} login: add "${p}" to third_party_integrations`;
+export const THIRD_PARTY_UNUSED = (p) => `third_party_integrations declares "${p}" but no third_party_authorize step uses it; remove it`;
 const typeOf = (value) => {
     if (value === null)
         return "null";
@@ -174,6 +177,37 @@ function identityIssues(plan, provisioning) {
         ? [{ path: "(root)", message: MINTED_IDENTITY_NEEDS_TEARDOWN }]
         : [];
 }
+export const THIRD_PARTY_AUTHORIZE = "third_party_authorize";
+export const AWAIT_THIRD_PARTY = "await_third_party";
+const executed = (plan) => [
+    ...steps(plan.before),
+    ...steps(plan.steps),
+    ...steps(plan.after),
+];
+export function planUsesThirdParty(plan) {
+    if (typeof plan !== "object" || plan === null)
+        return false;
+    return executed(plan).some((s) => s.action === THIRD_PARTY_AUTHORIZE || s.action === AWAIT_THIRD_PARTY);
+}
+// Mirrors the server's ActionPlan validator, which raises the first sorted mismatch only.
+function thirdPartyIssues(plan) {
+    if (typeof plan !== "object" || plan === null)
+        return [];
+    const record = plan;
+    const declared = new Set(Array.isArray(record.third_party_integrations)
+        ? record.third_party_integrations.map(String)
+        : []);
+    const authorized = new Set(executed(record)
+        .filter((s) => s.action === THIRD_PARTY_AUTHORIZE && typeof s.provider === "string")
+        .map((s) => s.provider));
+    const [undeclared] = [...authorized].filter((p) => !declared.has(p)).sort();
+    if (undeclared)
+        return [{ path: "(root)", message: THIRD_PARTY_UNDECLARED(undeclared) }];
+    const [unused] = [...declared].filter((p) => !authorized.has(p)).sort();
+    if (unused)
+        return [{ path: "third_party_integrations", message: THIRD_PARTY_UNUSED(unused) }];
+    return [];
+}
 const TEARDOWN_PROOF_KINDS = new Set([
     "gone",
     "hidden",
@@ -212,6 +246,7 @@ export function lintPlan(plan, opts = {}) {
     if (issues.length > 0)
         return issues;
     return [
+        ...thirdPartyIssues(plan),
         ...identityIssues(plan, opts.provisioning === true),
         ...(opts.access === undefined ? [] : accessIssues(plan, opts.access)),
     ];

package/dist/local-exec.js

@@ -8,6 +8,11 @@ export const IMPORT_MAX_ERROR_LEN = 5000;
 export const IMPORT_MAX_FILE_BYTES = 14 * 1024 * 1024;
 export const IMPORT_MAX_TOTAL_BYTES = 180 * 1024 * 1024;
 export const IMPORT_MAX_FILES = 3600;
+export const THIRD_PARTY_CLOUD_ONLY = "third party integration steps run only in Beryl's cloud";
+export const THIRD_PARTY_USE_TRIGGER = `${THIRD_PARTY_CLOUD_ONLY}; use \`beryl runs trigger\``;
+// The rendered await_third_party helper, and the authorize step's wait to leave the provider's host.
+const THIRD_PARTY_SPEC_MARKER = /__vmThirdParty\(|\.test\(u\.hostname\)/;
+export const specUsesThirdParty = (content) => THIRD_PARTY_SPEC_MARKER.test(content);
 export function toRunEntry(spec, outcome, runError, startedAt, ordinal, redact) {
     // Mirrors the cloud runner's redact_result: the spec types secrets into the page
     // and an injected session authenticates its requests, so error text and the DOM

package/dist/registry/index.js

@@ -12,6 +12,8 @@ import { mcpCommands } from "../commands/mcp.js";
 import { projectCommands } from "../commands/projects.js";
 import { runCommands } from "../commands/runs.js";
 import { testCommands } from "../commands/tests.js";
+import { thirdPartyIntegrationCommands } from "../commands/third-party-integrations.js";
+import { trackerCommands } from "../commands/tracker.js";
 import { workspaceCommands } from "../commands/workspaces.js";
 export const WORKSPACE_FLAG = {
     name: "workspace",
@@ -65,9 +67,11 @@ export const commands = [
     ...groupCommands,
     ...runCommands,
     ...healthCommands,
+    ...trackerCommands,
     ...explorationCommands,
     ...configCommands,
     ...mailboxCommands,
+    ...thirdPartyIntegrationCommands,
     ...testAccountCommands,
     ...accountCommands,
     ...mcpCommands,