@beryl-so/cli 0.54.1 → 0.60.0

package/README.md

@@ -191,7 +191,7 @@ Manage a project's environments: the URLs and auth Beryl runs tests against.
 | `beryl envs list` | List a project's environments | `envs_list` |
 | `beryl envs get <env-id>` | Show one environment | `envs_get` |
 | `beryl envs create <name> <url>` | Add an environment (e.g. staging) to a project | `envs_create` |
-| `beryl envs update <env-id>` | Update an environment's name, URL, or auth settings | `envs_update` |
+| `beryl envs update <env-id>` | Update an environment's name, URL, auth settings, Site Health screen sizes, schedule, CI and pages, or issue tracker settings | `envs_update` |
 | `beryl envs delete <env-id>` | Delete an environment | `envs_delete` |
 
 ### schedule
@@ -223,7 +223,8 @@ Author, inspect, version, and heal a project's tests: the checks Beryl runs on e
 | `beryl tests set-groups <test-id>` | Replace the groups a test belongs to | `tests_set_groups` |
 | `beryl tests set-access <test-id> <access>` | Mark a test read or write | `tests_set_access` |
 | `beryl tests add-groups <test-ids...>` | Add groups to one or more tests, keeping the groups they already have | `tests_add_groups` |
-| `beryl tests quarantine <test-id> <state>` | Mute a flaky test: it keeps running, but its failures stop failing the run | `tests_quarantine` |
+| `beryl tests quarantine <state> <test-ids...>` | Mute flaky tests: they keep running, but their failures stop failing the run | `tests_quarantine` |
+| `beryl tests events <test-id>` | Who quarantined, grouped or renamed a test, and why | `tests_events` |
 | `beryl tests delete <test-ids...>` | Delete tests, their version history, and their results | `tests_delete` |
 | `beryl tests recompile <test-id>` | Validate + verify an edited plan against the live site before persisting | `tests_recompile` |
 | `beryl tests versions <test-id>` | List a test's version history | `tests_versions` |
@@ -269,14 +270,21 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 
 ### health
 
-Site Health, or how your site reads to search engines and visitors: content, speed, mobile, links and security, graded from a real check of your live pages.
+Site Health, or how your site reads to search engines and visitors: content, speed, links, security, and a visual check of layout at phone, tablet and desktop sizes, graded from a real check of your live pages.
 
 `beryl health` with no subcommand runs `health get`.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl health get` | Show the latest Site Health report for a project environment | `health_get` |
-| `beryl health run` | Run a fresh Site Health check for a project environment | `health_run` |
+| `beryl health get` | Show the latest Site Health report, or one report by id | `health_get` |
+| `beryl health run` | Run a fresh Site Health check, or a visual check of one page | `health_run` |
+| `beryl health intended <key>` | Mark a visual finding as intended, so it stops counting against the grade | `health_intended` |
+| `beryl health tracker status` | Show how Site Health files findings as issue tracker tickets for an environment | `health_tracker_status` |
+| `beryl health tracker tickets` | List the findings Site Health tracks in the issue tracker, with their tickets | `health_tracker_tickets` |
+| `beryl health tracker connect` | Get the link that connects an issue tracker to the workspace | `health_tracker_connect` |
+| `beryl health tracker disconnect` | Remove the workspace's issue tracker connection | `health_tracker_disconnect` |
+| `beryl health tracker teams` | List the teams of the connected issue tracker | `health_tracker_teams` |
+| `beryl health tracker projects` | List a tracker team's projects | `health_tracker_projects` |
 
 ### explorations
 

package/dist/commands/environments.js

@@ -1,5 +1,7 @@
 import { UsageError } from "../errors.js";
-import { arg, findGroup, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { HEALTH_RUN_SETTING_FLAGS, VIEWPORTS, runSettingsFromFlags } from "./health.js";
+import { TRACKER_SETTING_FLAGS, trackerSettingsFromFlags } from "./tracker.js";
+import { arg, findGroup, flagBool, flagNum, flagStr, flagStrings, projectPath } from "./util.js";
 const SCHEDULE_GROUPS_FLAG = "Comma-separated group names or ids the schedule targets (the run covers the union of their active tests at fire time); omit to run every active test";
 const SCHEDULE_CADENCE_FLAGS = [
     {
@@ -65,13 +67,30 @@ export const environmentCommands = [
     },
     {
         name: "envs update",
-        summary: "Update an environment's name, URL, or auth settings",
+        summary: "Update an environment's name, URL, auth settings, Site Health screen sizes, schedule, CI and pages, or issue tracker settings",
         scope: "project",
         args: [{ name: "env-id", description: "Environment id", required: true }],
         flags: [
             { name: "name", type: "string", description: "New name" },
             { name: "url", type: "string", description: "New root URL" },
             { name: "auth", type: "string", enum: ["public", "gated"], description: "New auth choice" },
+            {
+                name: "viewport",
+                type: "strings",
+                enum: ["all", ...VIEWPORTS],
+                description: "Screen size the Site Health visual checks run at, repeatable; replaces the set. " +
+                    "Pass `--viewport all` to reset to all five.",
+            },
+            ...HEALTH_RUN_SETTING_FLAGS,
+            ...TRACKER_SETTING_FLAGS,
+        ],
+        examples: [
+            "beryl envs update <env-id> --tracker linear --tracker-team <team-id>",
+            "beryl envs update <env-id> --tracker-threshold medium --tracker-max-tickets 5",
+            "beryl envs update <env-id> --tracker-priority high=urgent --tracker-pause on",
+            "beryl envs update <env-id> --health-schedule daily --health-time 06:00 --health-timezone Europe/Berlin",
+            "beryl envs update <env-id> --health-pages crawl --health-max-pages 25 --health-exclude '/blog/*'",
+            "beryl envs update <env-id> --health-ci main_only --health-ci-fail-on medium",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -82,6 +101,20 @@ export const environmentCommands = [
                 body.root_url = flagStr(input, "url");
             if (flagStr(input, "auth"))
                 body.requires_auth_choice = flagStr(input, "auth");
+            const viewports = flagStrings(input, "viewport");
+            if (viewports) {
+                const bad = viewports.find((v) => v !== "all" && !VIEWPORTS.includes(v));
+                if (bad) {
+                    throw new UsageError(`--viewport must be one of: all, ${VIEWPORTS.join(", ")}`);
+                }
+                body.site_health_viewports = viewports.includes("all") ? [] : viewports;
+            }
+            const tracker = trackerSettingsFromFlags(input);
+            if (tracker)
+                body.site_health_tracker = tracker;
+            const runs = runSettingsFromFlags(input);
+            if (runs)
+                body.site_health_runs = runs;
             if (Object.keys(body).length === 0)
                 throw new UsageError("Nothing to update");
             return {

package/dist/commands/health.js

@@ -1,43 +1,404 @@
-import { flagStr, projectPath } from "./util.js";
+import { UsageError } from "../errors.js";
+import { arg, flagBool, flagNum, flagStr, flagStrings, projectPath } from "./util.js";
 const ENV_FLAG = {
     name: "env",
     type: "string",
     description: "Environment id (defaults to the project's default environment)",
 };
+export const VIEWPORTS = [
+    "phone",
+    "tablet_portrait",
+    "tablet_landscape",
+    "desktop",
+    "desktop_wide",
+];
+const SCREENSHOTS_FLAG = {
+    name: "screenshots",
+    type: "boolean",
+    description: "Include the annotated screenshots (as images over MCP, data URIs in --json)",
+};
+// Annotated evidence is spent from the agent's context window; the top few carry it.
+const MAX_MCP_IMAGES = 3;
+const WAIT_POLL_MS = 5000;
+const WAIT_LIMIT_MS = 6 * 60 * 1000;
+function toImage(dataUri) {
+    const [, mimeType, data] = /^data:([^;]+);base64,(.*)$/.exec(dataUri) ?? [];
+    return mimeType && data ? { data, mimeType } : undefined;
+}
+// Over MCP the screenshots go out as image blocks and never as inline base64 text.
+function present(ctx, report, withShots) {
+    if (!withShots || !ctx.mcp)
+        return { data: report };
+    const images = [];
+    for (const cat of report.categories ?? []) {
+        for (const f of cat.findings ?? []) {
+            if (f.screenshot && !f.intended && f.status !== "pass" && images.length < MAX_MCP_IMAGES) {
+                const img = toImage(f.screenshot);
+                if (img)
+                    images.push(img);
+            }
+            delete f.screenshot;
+        }
+    }
+    const stripped = { ...report, screenshots: null };
+    return { data: stripped, images: images.length ? images : undefined };
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// A run fans out to up to 100 pages, each on its own worker.
+const CI_WAIT_LIMIT_MS = 30 * 60 * 1000;
+const DAYS = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+const ON_OFF = ["on", "off"];
+/** `envs update` flags for when Site Health runs and which pages it checks. */
+export const HEALTH_RUN_SETTING_FLAGS = [
+    {
+        name: "health-schedule",
+        type: "string",
+        enum: ["off", "daily", "weekly"],
+        description: "Run Site Health on a schedule (default off)",
+    },
+    {
+        name: "health-time",
+        type: "string",
+        placeholder: "HH:MM",
+        description: "Time of day scheduled runs start, 24h, in --health-timezone (default 09:00)",
+    },
+    {
+        name: "health-day",
+        type: "string",
+        enum: DAYS,
+        description: "Day weekly runs start (default mon)",
+    },
+    {
+        name: "health-timezone",
+        type: "string",
+        description: "IANA timezone for the schedule, e.g. Europe/Berlin (default UTC)",
+    },
+    {
+        name: "health-ci",
+        type: "string",
+        enum: ["off", "every_build", "main_only", "deploy_only"],
+        description: "Which CI builds `health run --ci` checks; other builds skip and pass (default off)",
+    },
+    {
+        name: "health-ci-fail-on",
+        type: "string",
+        enum: ["high", "medium", "never"],
+        description: "Lowest finding severity that fails the CI build; never reports only (default high)",
+    },
+    {
+        name: "health-ci-tickets",
+        type: "string",
+        enum: ON_OFF,
+        description: "CI runs file tracker tickets; off leaves the findings to the PR (default off)",
+    },
+    {
+        name: "health-pages",
+        type: "string",
+        enum: ["homepage", "paths", "sitemap", "crawl"],
+        description: "Pages a run checks: the homepage, --health-path list, sitemap.xml, or a crawl from " +
+            "the homepage (default homepage)",
+    },
+    {
+        name: "health-path",
+        type: "strings",
+        description: "Page path for the paths mode, repeatable; replaces the list. `none` clears it",
+    },
+    {
+        name: "health-crawl-depth",
+        type: "number",
+        description: "Link hops from the homepage in crawl mode, 1-5 (default 2)",
+    },
+    {
+        name: "health-max-pages",
+        type: "number",
+        description: "Most pages one run checks, homepage included, 1-100 (default 25)",
+    },
+    {
+        name: "health-include",
+        type: "strings",
+        description: "Path pattern a page must match, e.g. '/blog/*', repeatable; replaces the list. `none` clears it",
+    },
+    {
+        name: "health-exclude",
+        type: "strings",
+        description: "Path pattern to skip, repeatable; replaces the list. `none` clears it",
+    },
+    {
+        name: "health-logged-in",
+        type: "strings",
+        description: "Path pattern checked signed in with the environment's saved test sign-in, repeatable; " +
+            "the rest run logged out. `none` clears it",
+    },
+    {
+        name: "health-retries",
+        type: "number",
+        description: "Extra attempts when a page check fails or times out, 0-3 (default 1)",
+    },
+];
+function list(input, name) {
+    const values = flagStrings(input, name);
+    if (!values)
+        return undefined;
+    return values.includes("none") ? [] : values;
+}
+/** The `site_health_runs` PATCH body from `envs update` flags; undefined when none were given. */
+export function runSettingsFromFlags(input) {
+    const body = {};
+    const strings = [
+        ["health-schedule", "schedule"],
+        ["health-timezone", "schedule_timezone"],
+        ["health-ci", "ci_mode"],
+        ["health-ci-fail-on", "ci_fail_on"],
+        ["health-pages", "pages"],
+    ];
+    for (const [flag, field] of strings) {
+        const v = flagStr(input, flag);
+        if (v !== undefined)
+            body[field] = v;
+    }
+    const time = flagStr(input, "health-time");
+    if (time !== undefined) {
+        const m = /^(\d{1,2}):(\d{2})$/.exec(time);
+        if (!m || Number(m[1]) > 23 || Number(m[2]) > 59) {
+            throw new UsageError("--health-time must be HH:MM, 24h, e.g. 09:30");
+        }
+        body.schedule_hour = Number(m[1]);
+        body.schedule_minute = Number(m[2]);
+    }
+    const day = flagStr(input, "health-day");
+    if (day !== undefined) {
+        const idx = DAYS.indexOf(day.toLowerCase());
+        if (idx < 0)
+            throw new UsageError(`--health-day must be one of: ${DAYS.join(", ")}`);
+        body.schedule_day_of_week = idx;
+    }
+    const tickets = flagStr(input, "health-ci-tickets");
+    if (tickets !== undefined) {
+        if (!ON_OFF.includes(tickets))
+            throw new UsageError("--health-ci-tickets must be on or off");
+        body.ci_files_tickets = tickets === "on";
+    }
+    const lists = [
+        ["health-path", "paths"],
+        ["health-include", "include"],
+        ["health-exclude", "exclude"],
+        ["health-logged-in", "logged_in"],
+    ];
+    for (const [flag, field] of lists) {
+        const v = list(input, flag);
+        if (v !== undefined)
+            body[field] = v;
+    }
+    const numbers = [
+        ["health-crawl-depth", "crawl_depth"],
+        ["health-max-pages", "max_pages"],
+        ["health-retries", "retries"],
+    ];
+    for (const [flag, field] of numbers) {
+        const v = flagNum(input, flag);
+        if (v !== undefined)
+            body[field] = v;
+    }
+    return Object.keys(body).length ? body : undefined;
+}
+function ciBranch() {
+    const env = process.env;
+    return (env.GITHUB_HEAD_REF ||
+        env.GITHUB_REF_NAME ||
+        env.CI_COMMIT_REF_NAME ||
+        env.CIRCLE_BRANCH ||
+        env.BITBUCKET_BRANCH ||
+        env.BRANCH_NAME ||
+        undefined);
+}
+// Markdown, so a CI step can post it as the PR comment as is.
+export function ciMarkdown(run) {
+    if (run.skipped)
+        return `Beryl Site Health: skipped (${run.reason ?? "CI mode"}).`;
+    const f = run.findings ?? {};
+    const verdict = run.status === "failed"
+        ? "failed to complete"
+        : run.gate?.passed
+            ? "passed"
+            : `failed (findings at or above ${run.gate?.fail_on})`;
+    const lines = [
+        `**Beryl Site Health ${verdict}**`,
+        "",
+        `${run.pages?.length ?? 0} page(s) checked. Open findings: ${f.high ?? 0} high, ` +
+            `${f.medium ?? 0} medium, ${f.low ?? 0} low.`,
+    ];
+    if (run.failing?.length) {
+        lines.push("", "| Page | Severity | Finding |", "| --- | --- | --- |");
+        for (const x of run.failing)
+            lines.push(`| ${x.page_path} | ${x.severity} | ${x.title} |`);
+    }
+    const broken = (run.pages ?? []).filter((p) => p.status === "failed" || p.problem);
+    if (broken.length) {
+        lines.push("", "Pages that could not be checked:");
+        for (const p of broken) {
+            lines.push(`- ${p.page_path}: ${p.problem ?? p.error ?? "check failed"}`);
+        }
+    }
+    return lines.join("\n");
+}
+async function runCi(ctx, input, base) {
+    let run = (await ctx.client.post(`${base}/runs`, {
+        trigger: "ci",
+        branch: flagStr(input, "branch") ?? ciBranch(),
+        deploy: flagBool(input, "deploy"),
+    }, { environment_id: flagStr(input, "env") }));
+    if (run.skipped)
+        return { data: run, human: ciMarkdown(run) };
+    const deadline = Date.now() + CI_WAIT_LIMIT_MS;
+    while (run.status === "queued" || run.status === "running") {
+        if (Date.now() > deadline) {
+            return { data: run, human: "Beryl Site Health: timed out waiting for the run.", exitCode: 1 };
+        }
+        await sleep(WAIT_POLL_MS);
+        run = (await ctx.client.get(`${base}/runs/${run.run_id}`));
+    }
+    return { data: run, human: ciMarkdown(run), exitCode: run.gate?.passed ? 0 : 1 };
+}
 export const healthCommands = [
     {
         name: "health get",
         groupDefault: true,
         groupSummary: "Site Health, or how your site reads to search engines and visitors: content, " +
-            "speed, mobile, links and security, graded from a real check of your live pages.",
-        summary: "Show the latest Site Health report for a project environment",
+            "speed, links, security, and a visual check of layout at phone, tablet and desktop " +
+            "sizes, graded from a real check of your live pages.",
+        summary: "Show the latest Site Health report, or one report by id",
         description: "A check runs automatically when a project or environment gets its URL. While one " +
-            "is in flight the report comes back with status queued/running and no grades yet; " +
-            "call again to pick up the finished result.",
+            "is in flight the report comes back with status queued/running and no grades yet, " +
+            "plus the `stage` a running check is on; call again to pick up the finished result. Visual findings sit in the `layout` " +
+            "category, which also grades them per screen size (`screens`: phone, tablet, " +
+            "desktop) and as `mobile` (phone and tablet only). Each carries a `key`, the " +
+            "`selector`, measured values, the `viewports` it shows at and a fix hint in " +
+            "`recommendation`. The `performance` category grades Google PageSpeed on mobile " +
+            "and on desktop separately (`speeds`, each with its own Core Web Vitals) and takes " +
+            "the worse of the two; one that couldn't be measured is left out. Pass --report for a single-page check started with " +
+            "`health run --path`.",
         scope: "project",
-        flags: [ENV_FLAG],
+        flags: [
+            ENV_FLAG,
+            { name: "report", type: "string", description: "Report id (from `health run`)" },
+            {
+                name: "run",
+                type: "string",
+                description: "Run id: every page of one run, finding counts and the CI gate verdict",
+            },
+            SCREENSHOTS_FLAG,
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return {
-                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/seo-report`, {
-                    environment_id: flagStr(input, "env"),
-                }),
-            };
+            const runId = flagStr(input, "run");
+            if (runId) {
+                return {
+                    data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/seo-report/runs/${runId}`),
+                };
+            }
+            const withShots = flagBool(input, "screenshots");
+            const reportId = flagStr(input, "report");
+            const base = `${projectPath(workspaceId, projectId)}/seo-report`;
+            const report = (await ctx.client.get(reportId ? `${base}/${reportId}` : base, {
+                environment_id: reportId ? undefined : flagStr(input, "env"),
+                screenshots: withShots ? "true" : "false",
+            }));
+            return present(ctx, report, withShots);
         },
     },
     {
         name: "health run",
-        summary: "Run a fresh Site Health check for a project environment",
-        description: "Queues a new check and returns immediately. Returns the in-flight report instead " +
-            "of stacking a second one when a check is already running.",
+        summary: "Run a fresh Site Health check, or a visual check of one page",
+        description: "Queues a check and returns immediately (or, with --wait, once it finishes; a check " +
+            "takes one to three minutes). Without --path it is the full Site Health run of the " +
+            "environment URL. With --path it runs only the visual checks (clipping, overlap, tap " +
+            "targets, scroll traps, content stability, scroll-through) on that page, logged out " +
+            "unless it matches the environment's --health-logged-in patterns, " +
+            "at the chosen --viewport sizes (default: the environment's configured set). Returns " +
+            "the in-flight report instead of stacking a second one of the same scope. A full run " +
+            "also checks the environment's configured pages (see `envs update --health-pages`); " +
+            "each page gets its own report, grouped under the homepage report's `run_id`.\n\n" +
+            "With --ci it starts a CI run, waits for every page, prints a Markdown summary you can " +
+            "post as the PR comment, and exits 1 when findings at or above the environment's " +
+            "fail-on severity exist, a page couldn't be checked, or the run failed. Builds that the " +
+            "environment's CI mode doesn't cover skip and exit 0. CI runs file tracker tickets only when --health-ci-tickets is on.",
+        scope: "project",
+        flags: [
+            ENV_FLAG,
+            { name: "path", type: "string", description: "Page path to check, e.g. /pricing" },
+            {
+                name: "viewport",
+                type: "strings",
+                enum: VIEWPORTS,
+                description: "Screen size, repeatable: phone (390x844), tablet_portrait (768x1024), " +
+                    "tablet_landscape (1024x768), desktop (1440x900), desktop_wide (1920x1080)",
+            },
+            { name: "wait", type: "boolean", description: "Wait for the check to finish" },
+            SCREENSHOTS_FLAG,
+            {
+                name: "ci",
+                type: "boolean",
+                description: "CI run: wait, print a PR-ready summary, exit 1 at or above the fail-on severity",
+            },
+            {
+                name: "branch",
+                type: "string",
+                description: "Branch of the CI build (default: read from the CI environment)",
+            },
+            { name: "deploy", type: "boolean", description: "The CI build is a deploy (for --health-ci deploy_only)" },
+        ],
+        examples: [
+            "beryl health run",
+            "beryl health run --path /pricing --viewport phone --wait",
+            "beryl health run --ci",
+            "beryl health run --ci --deploy --env <env-id>",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const base = `${projectPath(workspaceId, projectId)}/seo-report`;
+            const path = flagStr(input, "path");
+            const viewports = flagStrings(input, "viewport");
+            if (flagBool(input, "ci")) {
+                if (path || viewports)
+                    throw new UsageError("--ci runs the configured pages; drop --path and --viewport");
+                return runCi(ctx, input, base);
+            }
+            const bad = viewports?.find((v) => !VIEWPORTS.includes(v));
+            if (bad)
+                throw new UsageError(`--viewport must be one of: ${VIEWPORTS.join(", ")}`);
+            const body = path || viewports ? { path, viewports } : undefined;
+            let report = (await ctx.client.post(base, body, {
+                environment_id: flagStr(input, "env"),
+            }));
+            const withShots = flagBool(input, "screenshots");
+            if (!flagBool(input, "wait"))
+                return { data: report };
+            const deadline = Date.now() + WAIT_LIMIT_MS;
+            while (report.status === "queued" || report.status === "running") {
+                if (Date.now() > deadline)
+                    return { data: report, exitCode: 1 };
+                await sleep(WAIT_POLL_MS);
+                report = (await ctx.client.get(`${base}/${report.id}`, {
+                    screenshots: withShots ? "true" : "false",
+                }));
+            }
+            const result = present(ctx, report, withShots);
+            return report.status === "failed" ? { ...result, exitCode: 1 } : result;
+        },
+    },
+    {
+        name: "health intended",
+        summary: "Mark a visual finding as intended, so it stops counting against the grade",
+        description: "Takes the finding's `key` from `health get`. The finding stays in the report, flagged " +
+            "intended, and is left out of the grade on this report and every later run of the " +
+            "environment. --clear removes the mark.",
         scope: "project",
-        flags: [ENV_FLAG],
-        examples: ["beryl health run", "beryl health run --env 4f…"],
+        args: [{ name: "key", description: "Finding key", required: true }],
+        flags: [ENV_FLAG, { name: "clear", type: "boolean", description: "Remove the mark" }],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return {
-                data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/seo-report`, undefined, { environment_id: flagStr(input, "env") }),
-            };
+            const report = (await ctx.client.put(`${projectPath(workspaceId, projectId)}/seo-report/intended`, { key: arg(input, "key"), intended: !flagBool(input, "clear") }, { environment_id: flagStr(input, "env") }));
+            return present(ctx, report, false);
         },
     },
 ];

package/dist/commands/runs.js

@@ -585,8 +585,8 @@ export const runCommands = [
             {
                 name: "status",
                 type: "string",
-                description: "With --page, show only this bucket: passed, failed, errored, cancelled, or " +
-                    "quarantined",
+                description: "With --page, show only this bucket: passed, failed, errored, cancelled, " +
+                    "quarantined, or unstable (currently unstable in the run's environment)",
             },
             {
                 name: "group",

package/dist/commands/tests.js

@@ -9,6 +9,29 @@ import { confirmInstall, installCommandsFor, installPlaywright, playwrightGaps,
 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",
@@ -637,7 +661,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 +669,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/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/registry/index.js

@@ -12,6 +12,7 @@ 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 { trackerCommands } from "../commands/tracker.js";
 import { workspaceCommands } from "../commands/workspaces.js";
 export const WORKSPACE_FLAG = {
     name: "workspace",
@@ -65,6 +66,7 @@ export const commands = [
     ...groupCommands,
     ...runCommands,
     ...healthCommands,
+    ...trackerCommands,
     ...explorationCommands,
     ...configCommands,
     ...mailboxCommands,

package/package.json

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