@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/setup/oauth-token-probe.js

@@ -0,0 +1,108 @@
+import { NetDeniedError } from "../net/public-address.js";
+import { safeFetch } from "../net/safe-fetch.js";
+import { parseTokenRefusal, tokenRequestInit, } from "../tools/oauth/tokens.js";
+/** The authorization code the probe sends: never a code any server issued. */
+export const PROBE_CODE = "capybara-setup-probe";
+/** A fixed PKCE verifier (43 characters, RFC 7636), so a server that demands one reads the code. */
+const PROBE_VERIFIER = "capybara-setup-probe-verifier-0000000000000";
+/** The most of a token endpoint answer the probe reads (an error body is a few hundred bytes). */
+const PROBE_MAX_BYTES = 64 * 1024;
+/** Codes that say the client authenticated and only the code was bad, as intended. */
+const ACCEPTED = new Set(["invalid_grant", "invalid_code"]);
+/** Codes that say the client id or secret is wrong (RFC 6749 and Slack's). */
+const CLIENT_REFUSED = new Set([
+    "invalid_client",
+    "unauthorized_client",
+    "invalid_client_id",
+    "bad_client_secret",
+]);
+/** Codes that say the redirect URI is not registered (RFC 6749 servers and Slack's). */
+const REDIRECT_REFUSED = new Set(["redirect_uri_mismatch", "bad_redirect_uri"]);
+const text = (en, zh) => ({ en, zh });
+/** The probe's fixed texts: nothing a token endpoint sends ever reaches a result. */
+export const PROBE_TEXTS = {
+    accepted: text("The token endpoint accepted the client.", "令牌端点接受了这个客户端。"),
+    clientRefused: text("The token endpoint refused the client id or secret.", "令牌端点拒绝了客户端 ID 或密钥。"),
+    clientFix: text("Copy the Client ID and Client Secret again from the app's Basic Information page.", "从应用的 Basic Information 页面重新复制 Client ID 和 Client Secret。"),
+    redirectRefused: text("The app does not list the callback URL.", "应用的重定向地址里没有这个回调地址。"),
+    unknown: text("Could not verify the client; retry later.", "无法验证这个客户端，请稍后重试。"),
+    netDenied: text("The token endpoint's address is refused by this deployment's network rules; ask your super admin.", "这个部署的网络规则拒绝访问令牌端点的地址，请联系超级管理员。"),
+};
+/**
+ * The fix of a redirect refusal: the kernel-built callback URL (never anything the endpoint
+ * said): `http.publicUrl` + the fixed callback path. (A public URL so long that the fix passes
+ * its limit makes the result invalid, which the kernel answers as unknown.)
+ */
+export const redirectFix = (callbackUrl) => text(`Add ${callbackUrl} to the app's redirect URLs.`, `把 ${callbackUrl} 加到应用的重定向地址（Redirect URLs）里。`);
+/**
+ * The network rules of the probe: the deployment's egress proxy (`net.httpsProxy` /
+ * `net.noProxy`), its private host exemptions (`marketplaces.allowPrivateHosts`, the one list of
+ * internal hosts the kernel may reach) and loopback http only under
+ * `tools.oauthAllowInsecureLoopback` (tests), as for every other OAuth URL.
+ */
+export function probeNetPolicy(config) {
+    return {
+        allowInsecureLoopback: config.tools.oauthAllowInsecureLoopback,
+        allowPrivateHosts: config.marketplaces.allowPrivateHosts,
+        trustedOrigins: [],
+        ...(config.net.httpsProxy !== undefined && {
+            proxy: { url: config.net.httpsProxy, noProxy: config.net.noProxy },
+        }),
+    };
+}
+/**
+ * Probes the token endpoint (spec §10.6 table): `invalid_grant` / Slack `invalid_code` → ok; a
+ * refused client (or any other 401) → failing with the copy-again fix; a refused redirect URI →
+ * failing with the callback URL; anything else (429, 5xx, a network error, a redirect, a 2xx) →
+ * unknown. Never throws, never logs; the answer is read only for its refusal code and dropped.
+ */
+export async function probeTokenEndpoint(input) {
+    const { client } = input;
+    const { headers, body } = tokenRequestInit(client, {
+        grant_type: "authorization_code",
+        code: PROBE_CODE,
+        redirect_uri: input.redirectUri,
+        code_verifier: PROBE_VERIFIER,
+        resource: client.resource,
+    });
+    let status;
+    let parsed;
+    try {
+        const res = await (input.fetch ?? safeFetch)(client.tokenEndpoint, { method: "POST", headers, body: body.toString(), signal: input.signal }, input.net, { maxBytes: PROBE_MAX_BYTES });
+        status = res.status;
+        // only an answer that can carry a refusal is read (400 / 401, or a 200 error body of
+        // dialects like Slack's); other bodies are dropped unread
+        if (status === 200 || status === 400 || status === 401) {
+            try {
+                parsed = JSON.parse(await res.text());
+            }
+            catch {
+                parsed = undefined;
+            }
+        }
+        else {
+            await res.body?.cancel().catch(() => { });
+        }
+    }
+    catch (e) {
+        if (e instanceof NetDeniedError && e.code !== "net.redirect" && e.code !== "net.dns_failed") {
+            return { status: "unknown", reason: PROBE_TEXTS.netDenied };
+        }
+        return { status: "unknown", reason: PROBE_TEXTS.unknown };
+    }
+    // only the refusal code is taken from the answer; a 2xx token is never looked at or kept
+    const code = parseTokenRefusal(status, parsed);
+    if (code !== null && ACCEPTED.has(code))
+        return { status: "ok", reason: PROBE_TEXTS.accepted };
+    if (code !== null && REDIRECT_REFUSED.has(code)) {
+        return {
+            status: "failing",
+            reason: PROBE_TEXTS.redirectRefused,
+            fix: redirectFix(input.redirectUri),
+        };
+    }
+    if ((code !== null && CLIENT_REFUSED.has(code)) || status === 401) {
+        return { status: "failing", reason: PROBE_TEXTS.clientRefused, fix: PROBE_TEXTS.clientFix };
+    }
+    return { status: "unknown", reason: PROBE_TEXTS.unknown };
+}

package/dist/setup/redact-check.d.ts

@@ -0,0 +1,18 @@
+import type { SetupCheckResult } from "@capybara-hq/plugin-sdk";
+/** The shortest secret value redacted from a check result (shorter values would hit plain words). */
+export declare const CHECK_SECRET_MIN_CHARS = 8;
+/** A redactor over the given secret values (only strings of at least 8 characters count). */
+export declare function checkRedactor(secrets: readonly unknown[]): (s: string) => string;
+/**
+ * A fresh plain object of a validated result with its texts redacted (validate it again: the
+ * redacted copy may be too long now). Only `status`, `reason` and `fix` are carried over.
+ */
+export declare function redactCheckResult(result: SetupCheckResult, redact: (s: string) => string): SetupCheckResult;
+/**
+ * What a log line may say about an error a check threw: its name and its redacted, shortened
+ * message, never the error object (a stack or a `cause` can carry what the message does not).
+ */
+export declare function describeCheckError(err: unknown, redact: (s: string) => string): {
+    name: string;
+    message: string;
+};

package/dist/setup/redact-check.js

@@ -0,0 +1,46 @@
+import { createRedactor } from "../log.js";
+/** The shortest secret value redacted from a check result (shorter values would hit plain words). */
+export const CHECK_SECRET_MIN_CHARS = 8;
+/** A redactor over the given secret values (only strings of at least 8 characters count). */
+export function checkRedactor(secrets) {
+    return createRedactor(secrets.filter((v) => typeof v === "string"), CHECK_SECRET_MIN_CHARS);
+}
+const redactText = (t, redact) => ({
+    en: redact(t.en),
+    ...(t.zh !== undefined && { zh: redact(t.zh) }),
+});
+/**
+ * A fresh plain object of a validated result with its texts redacted (validate it again: the
+ * redacted copy may be too long now). Only `status`, `reason` and `fix` are carried over.
+ */
+export function redactCheckResult(result, redact) {
+    return {
+        status: result.status,
+        ...(result.reason !== undefined && { reason: redactText(result.reason, redact) }),
+        ...(result.fix !== undefined && { fix: redactText(result.fix, redact) }),
+    };
+}
+/** The most of an extension's error message that reaches a log line (after redaction). */
+const ERROR_LOG_CHARS = 500;
+/**
+ * What a log line may say about an error a check threw: its name and its redacted, shortened
+ * message, never the error object (a stack or a `cause` can carry what the message does not).
+ */
+export function describeCheckError(err, redact) {
+    let name = "Error";
+    let message = "";
+    try {
+        if (err instanceof Error) {
+            name = typeof err.name === "string" ? err.name.slice(0, 64) : "Error";
+            message = typeof err.message === "string" ? err.message : "";
+        }
+        else {
+            name = typeof err;
+            message = typeof err === "string" ? err : "";
+        }
+    }
+    catch {
+        // a hostile error object (a throwing getter): nothing more to say about it
+    }
+    return { name: redact(name), message: redact(message).slice(0, ERROR_LOG_CHARS) };
+}

package/dist/setup/setup-check-registry.d.ts

@@ -0,0 +1,86 @@
+import type { SetupCheckResult, SetupCheckStatus, SetupCheckText, SetupGuidePlace } from "@capybara-hq/plugin-sdk";
+import type { RegisteredSetupCheck } from "../ctx/create-ctx.js";
+import type { InflightTracker } from "../extensions/inflight.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+/**
+ * The state of one check row (spec §10.3): a result, `running` (another request runs it, or the
+ * org's concurrency cap is reached) or `not_run`. The fields are fixed: nothing else ever leaves
+ * the kernel, in particular no extension error text.
+ */
+export interface SetupCheckState {
+    status: SetupCheckStatus | "running" | "not_run";
+    reason?: SetupCheckText;
+    fix?: SetupCheckText;
+    /** ISO time of the result. */
+    checkedAt?: string;
+    /** A forced rerun is refused until then. */
+    cooldownUntil?: string;
+}
+/** The object a kernel check is about: ids and the plugin, never a config or a credential. */
+export type KernelCheckTarget = {
+    kind: "channel-connection";
+    connectionId: string;
+    plugin: string;
+} | {
+    kind: "connector";
+    connectorId: string;
+    templateId: string;
+    plugin: string;
+};
+/** What a kernel check (`capybara:*`) receives. */
+export interface KernelCheckArgs {
+    orgId: string;
+    /** The caller (person or the agent's trigger account). */
+    accountId: string;
+    mode: string | null;
+    target: KernelCheckTarget;
+    /** Aborted at the kernel's timeout. */
+    signal: AbortSignal;
+    /**
+     * Every secret value the kernel redacts the result by: the target's (a connection's secret
+     * fields, a connector's stored credentials) and the plugin's deployment and org config secrets.
+     */
+    secrets: string[];
+}
+/** A kernel check's implementation. */
+export type KernelCheckRun = (args: KernelCheckArgs) => Promise<SetupCheckResult>;
+/** A check found for a guide's `::check` line. */
+export type ResolvedSetupCheck = {
+    source: "kernel";
+    id: string;
+    place: SetupGuidePlace | "any";
+    run: KernelCheckRun;
+} | {
+    source: "plugin";
+    id: string;
+    place: SetupGuidePlace;
+    run: RegisteredSetupCheck["run"];
+    inflight: InflightTracker;
+    /** The instance's `ctx.signal` (aborted when the instance is revoked). */
+    signal: AbortSignal;
+    version: string;
+    generation: number;
+};
+/**
+ * Where setup checks come from (spec §10.2, §10.6): the kernel's own `capybara:*` checks, in a
+ * map of their own registered once at module init (static code, the same on every replica, like
+ * the builtin tools), and an extension's checks, read from its active instance on this replica
+ * (registered in its `setup` through `ctx.setup.check`, revoked with the instance). An extension
+ * can never register a `capybara:` id (`SETUP_CHECK_ID_RE` has no colon), so it cannot shadow a
+ * kernel check.
+ */
+export declare class SetupCheckRegistry {
+    private readonly extensions;
+    private readonly kernel;
+    constructor(extensions: Pick<ExtensionRegistry, "current">);
+    /** Registers a kernel check; an id twice, a malformed id or an unknown place throws. */
+    registerKernel(id: `capybara:${string}`, place: SetupGuidePlace | "any", run: KernelCheckRun): void;
+    /**
+     * The check behind a guide's `::check <id>` line of `plugin`'s guide: a kernel check for
+     * `capybara:*`, else the plugin's own (null when this replica does not run the extension or the
+     * extension did not register the id).
+     */
+    resolve(plugin: string, id: string): ResolvedSetupCheck | null;
+    /** Whether `plugin` runs on this replica. */
+    running(plugin: string): boolean;
+}

package/dist/setup/setup-check-registry.js

@@ -0,0 +1,75 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { SETUP_CHECK_ID_RE, SETUP_GUIDE_PLACES } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { ExtensionRegistry } from "../extensions/registry.js";
+const KERNEL_ID_RE = new RegExp(`^capybara:${SETUP_CHECK_ID_RE.source.slice(1)}`);
+/**
+ * Where setup checks come from (spec §10.2, §10.6): the kernel's own `capybara:*` checks, in a
+ * map of their own registered once at module init (static code, the same on every replica, like
+ * the builtin tools), and an extension's checks, read from its active instance on this replica
+ * (registered in its `setup` through `ctx.setup.check`, revoked with the instance). An extension
+ * can never register a `capybara:` id (`SETUP_CHECK_ID_RE` has no colon), so it cannot shadow a
+ * kernel check.
+ */
+let SetupCheckRegistry = class SetupCheckRegistry {
+    extensions;
+    kernel = new Map();
+    constructor(extensions) {
+        this.extensions = extensions;
+    }
+    /** Registers a kernel check; an id twice, a malformed id or an unknown place throws. */
+    registerKernel(id, place, run) {
+        if (!KERNEL_ID_RE.test(id))
+            throw new Error(`setup check id "${id}" is not capybara:<id>`);
+        if (place !== "any" && !SETUP_GUIDE_PLACES.includes(place)) {
+            throw new Error(`setup check "${id}": unknown place "${place}"`);
+        }
+        if (typeof run !== "function")
+            throw new Error(`setup check "${id}": run must be a function`);
+        if (this.kernel.has(id))
+            throw new Error(`duplicate kernel setup check "${id}"`);
+        this.kernel.set(id, Object.freeze({ place, run }));
+    }
+    /**
+     * The check behind a guide's `::check <id>` line of `plugin`'s guide: a kernel check for
+     * `capybara:*`, else the plugin's own (null when this replica does not run the extension or the
+     * extension did not register the id).
+     */
+    resolve(plugin, id) {
+        if (id.startsWith("capybara:")) {
+            const k = this.kernel.get(id);
+            return k ? { source: "kernel", id, place: k.place, run: k.run } : null;
+        }
+        const inst = this.extensions.current(plugin);
+        const c = inst?.setupChecks.get(id);
+        if (!inst || !c)
+            return null;
+        return {
+            source: "plugin",
+            id,
+            place: c.place,
+            run: c.run,
+            inflight: inst.inflight,
+            signal: inst.signal,
+            version: inst.version,
+            generation: inst.generation,
+        };
+    }
+    /** Whether `plugin` runs on this replica. */
+    running(plugin) {
+        return this.extensions.current(plugin) !== undefined;
+    }
+};
+SetupCheckRegistry = __decorate([
+    Injectable(),
+    __param(0, Inject(ExtensionRegistry))
+], SetupCheckRegistry);
+export { SetupCheckRegistry };

package/dist/setup/setup-checks.controller.d.ts

@@ -0,0 +1,28 @@
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { SetupCheckState } from "./setup-check-registry.js";
+import { SetupCheckPathParams, SetupCheckRunBody, SetupChecksQuery, SetupGuidePathParams } from "./setup-checks.schemas.js";
+import { SetupChecksService } from "./setup-checks.service.js";
+/**
+ * The live rows of a setup guide (spec 2026-11-09-setup-guides-v2-design.md §10.3). Authorization
+ * is the guide route's (`catalog.read` here; catalog visibility, the place and audience action
+ * and the target are checked by the service before anything is loaded). A response carries only
+ * the fixed fields of {@link SetupCheckState}.
+ */
+export declare class SetupChecksController {
+    private readonly checks;
+    constructor(checks: SetupChecksService);
+    /** The cached state of each check of the rendered guide; never runs anything. */
+    states(principal: Principal, org: OrgContext, params: z.infer<typeof SetupGuidePathParams>, q: z.infer<typeof SetupChecksQuery>): Promise<{
+        results: Record<string, SetupCheckState>;
+    }>;
+    /**
+     * Runs one check unless a fresh result is cached (`force`: rerun, once per 10 s per check and
+     * target). 30 runs a minute per account (429 `rate_limited`): counted by the service, shared
+     * with the `Platform` tool's `setup.check`; the throttler also guards the route (`retry-after`).
+     */
+    run(principal: Principal, org: OrgContext, params: z.infer<typeof SetupCheckPathParams>, body: z.infer<typeof SetupCheckRunBody>): Promise<{
+        result: SetupCheckState;
+    }>;
+}

package/dist/setup/setup-checks.controller.js

@@ -0,0 +1,78 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, HttpCode, Inject, Post } from "@nestjs/common";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { Throttled } from "../infra/throttler/throttler.guard.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { SetupCheckPathParams, SetupCheckRunBody, SetupChecksQuery, SetupGuidePathParams, } from "./setup-checks.schemas.js";
+import { SetupChecksService } from "./setup-checks.service.js";
+class SetupGuideParamsDto extends createZodDto(SetupGuidePathParams, "SetupGuidePathParams") {
+}
+class SetupCheckParamsDto extends createZodDto(SetupCheckPathParams, "SetupCheckPathParams") {
+}
+class SetupChecksQueryDto extends createZodDto(SetupChecksQuery, "SetupChecksQuery") {
+}
+class SetupCheckRunBodyDto extends createZodDto(SetupCheckRunBody, "SetupCheckRunBody") {
+}
+/**
+ * The live rows of a setup guide (spec 2026-11-09-setup-guides-v2-design.md §10.3). Authorization
+ * is the guide route's (`catalog.read` here; catalog visibility, the place and audience action
+ * and the target are checked by the service before anything is loaded). A response carries only
+ * the fixed fields of {@link SetupCheckState}.
+ */
+let SetupChecksController = class SetupChecksController {
+    checks;
+    constructor(checks) {
+        this.checks = checks;
+    }
+    /** The cached state of each check of the rendered guide; never runs anything. */
+    async states(principal, org, params, q) {
+        const p = requireUser(principal);
+        return {
+            results: await this.checks.states({ orgId: org.orgId, role: org.role, accountId: p.account.id }, params.itemId, params.guideId, q),
+        };
+    }
+    /**
+     * Runs one check unless a fresh result is cached (`force`: rerun, once per 10 s per check and
+     * target). 30 runs a minute per account (429 `rate_limited`): counted by the service, shared
+     * with the `Platform` tool's `setup.check`; the throttler also guards the route (`retry-after`).
+     */
+    async run(principal, org, params, body) {
+        const p = requireUser(principal);
+        return {
+            result: await this.checks.run({ orgId: org.orgId, role: org.role, accountId: p.account.id }, params.itemId, params.guideId, params.checkId, body),
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(SetupGuideParamsDto)),
+    __param(3, ZQuery(SetupChecksQueryDto))
+], SetupChecksController.prototype, "states", null);
+__decorate([
+    Post(":checkId/run"),
+    HttpCode(200),
+    OrgAction("catalog.read"),
+    Throttled("setup-check"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(SetupCheckParamsDto)),
+    __param(3, ZBody(SetupCheckRunBodyDto))
+], SetupChecksController.prototype, "run", null);
+SetupChecksController = __decorate([
+    Controller("api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks"),
+    __param(0, Inject(SetupChecksService))
+], SetupChecksController);
+export { SetupChecksController };

package/dist/setup/setup-checks.schemas.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `:itemId` / `:guideId` of the check routes. */
+export declare const SetupGuidePathParams: z.ZodObject<{
+    itemId: z.ZodString;
+    guideId: z.ZodString;
+}, z.core.$strip>;
+/** `:itemId` / `:guideId` / `:checkId` of the run route (`capybara:<id>` for a kernel check). */
+export declare const SetupCheckPathParams: z.ZodObject<{
+    itemId: z.ZodString;
+    guideId: z.ZodString;
+    checkId: z.ZodString;
+}, z.core.$strip>;
+/** `GET …/guides/:guideId/checks`: the cached states, nothing runs. */
+export declare const SetupChecksQuery: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodString>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        admin: "admin";
+        member: "member";
+    }>>;
+    connectionId: z.ZodOptional<z.ZodString>;
+    connectorId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * `POST …/guides/:guideId/checks/:checkId/run`: runs the check unless a fresh cached result exists;
+ * `force` reruns it (at most once per 10 seconds per check and target).
+ */
+export declare const SetupCheckRunBody: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodString>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        admin: "admin";
+        member: "member";
+    }>>;
+    connectionId: z.ZodOptional<z.ZodString>;
+    connectorId: z.ZodOptional<z.ZodString>;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const SETUP_CHECK_ROUTES: readonly RouteSchemas[];

package/dist/setup/setup-checks.schemas.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+/** `:itemId` / `:guideId` of the check routes. */
+export const SetupGuidePathParams = z.object({
+    itemId: z.string().min(1).max(100),
+    guideId: z.string().min(1).max(64),
+});
+/** `:itemId` / `:guideId` / `:checkId` of the run route (`capybara:<id>` for a kernel check). */
+export const SetupCheckPathParams = SetupGuidePathParams.extend({
+    checkId: z.string().min(1).max(64),
+});
+/**
+ * The guide the checks belong to, as the guide route renders it (spec
+ * 2026-11-09-setup-guides-v2-design.md §10.3): its mode and audience (checked against the place by
+ * the service) and the target (`connectionId` for a channel connection, `connectorId` for a
+ * connector made from the template). Checks need a target.
+ */
+const GuideSelection = {
+    mode: z.string().min(1).max(64).optional(),
+    audience: z.enum(["admin", "member"]).optional(),
+    connectionId: z.string().min(1).max(100).optional(),
+    connectorId: z.string().min(1).max(100).optional(),
+};
+/** `GET …/guides/:guideId/checks`: the cached states, nothing runs. */
+export const SetupChecksQuery = z.object(GuideSelection).strict();
+/**
+ * `POST …/guides/:guideId/checks/:checkId/run`: runs the check unless a fresh cached result exists;
+ * `force` reruns it (at most once per 10 seconds per check and target).
+ */
+export const SetupCheckRunBody = z
+    .object({ ...GuideSelection, force: z.boolean().optional() })
+    .strict();
+export const SETUP_CHECK_ROUTES = [
+    {
+        route: "GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks",
+        params: SetupGuidePathParams,
+        query: SetupChecksQuery,
+    },
+    {
+        route: "POST /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks/:checkId/run",
+        params: SetupCheckPathParams,
+        body: SetupCheckRunBody,
+    },
+];