@capybara-hq/kernel 0.1.0-rc.13 → 0.1.0-rc.15

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,
+    },
+];

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

@@ -0,0 +1,144 @@
+import type { Redis } from "ioredis";
+import { ChannelConnections } from "../channels/connections.service.js";
+import type { Keyring } from "../ctx/secrets.js";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
+import { OrgExtensionConfigs } from "../extensions/org-config.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import type { OrgRole } from "../orgs/roles.js";
+import { Credentials } from "../tools/credentials.js";
+import { SetupCheckRegistry, type SetupCheckState } from "./setup-check-registry.js";
+/** Optional provider: the per-run time limit (ms) instead of `SETUP_CHECK_LIMITS.timeoutMs` (tests). */
+export declare const SETUP_CHECK_TIMEOUT: unique symbol;
+/** Who asks: the org, their role in it and their account. */
+export interface CheckCaller {
+    orgId: string;
+    role: OrgRole;
+    accountId: string;
+}
+/** The guide the checks belong to: mode, audience and target, as the guide route takes them. */
+export interface CheckSelection {
+    mode?: string | undefined;
+    audience?: "admin" | "member" | undefined;
+    connectionId?: string | undefined;
+    connectorId?: string | undefined;
+}
+/**
+ * Setup checks (spec 2026-11-09-setup-guides-v2-design.md §10): reads the cached state of a
+ * guide's checks and runs one on request. Authorization is the guide route's (catalog visibility,
+ * then the place and audience action, then the target, all through `PluginGuides.render`) before
+ * any target is loaded; the check must be in the guide rendered for that mode and audience.
+ *
+ * Multi-replica (§10.7): results, cooldowns, the single-flight lock and the org's concurrency
+ * semaphore live in Redis, every key with a TTL, none touched inside a transaction; nothing is in
+ * process memory. A run takes `capk:setup-check-run:<key>` (`LockService.lease`, 15 s, longer than
+ * the 10 s time limit) and a slot of `capk:setup-check-org:<orgId>` (8, self-expiring), and frees
+ * both on every path. Runs are limited per account (`capk:setup-check-rate:<accountId>`, 30 a
+ * minute, 429 `rate_limited`) here, so the HTTP route and the `Platform` tool share one budget.
+ * A check runs on the replica that took the lock, in the extension loaded
+ * there, raced against `AbortSignal.any([timeout, ctx.signal])` so one that ignores its signal
+ * still answers `unknown` at the limit (its late settle is dropped).
+ *
+ * Results never leak secrets (§10.8): a result is validated, redacted by every secret value the
+ * kernel knows for the target and the extension's config (the plugin's own, the connector's
+ * stored credentials it never got, the platform and the org's effective deployment config) and
+ * validated again; only that output is cached and returned. A throw, a timeout or an invalid
+ * result is `unknown` with a kernel reason; only the redacted problem or error message is logged.
+ */
+export declare class SetupChecksService {
+    private readonly db;
+    private readonly redis;
+    private readonly locks;
+    private readonly keyring;
+    private readonly guides;
+    private readonly registry;
+    private readonly extensions;
+    private readonly effective;
+    private readonly orgConfigs;
+    private readonly channels;
+    private readonly credentials;
+    private readonly log;
+    private readonly timeoutMs;
+    constructor(db: KernelDb, redis: Pick<Redis, "get" | "set" | "pttl" | "mget" | "exists" | "eval">, locks: Pick<LockService, "lease" | "releaseIf" | "takeSlot" | "releaseSlot">, keyring: Keyring, guides: Pick<PluginGuides, "render">, registry: SetupCheckRegistry, extensions: Pick<ExtensionRegistry, "current">, effective: Pick<EffectiveConfigs, "get">, orgConfigs: Pick<OrgExtensionConfigs, "get">, channels: Pick<ChannelConnections, "checkRevision" | "checkSecrets" | "runtime">, credentials: Pick<Credentials, "checkRevision" | "checkMaterial">, log: Pick<KernelLogger, "warn">, timeoutMs?: number);
+    /**
+     * The cached state of every check of the rendered guide (`GET …/checks`), by check id; nothing
+     * runs. `not_run` without a fresh result for the current input fingerprint; `running` while a
+     * run holds the lock. Redis down: every row `unknown` ("temporarily unavailable").
+     */
+    states(caller: CheckCaller, itemId: string, guideId: string, q: CheckSelection): Promise<Record<string, SetupCheckState>>;
+    /**
+     * Runs one check (`POST …/checks/:checkId/run`) unless a fresh result for the current input
+     * fingerprint is cached (or `force`, refused within 10 s of the last run: the cached state with
+     * `cooldownUntil`). Another run in progress (any replica) or the org's 8 concurrent runs taken:
+     * `running`. Kernel reasons (`unknown`) when the check cannot run here.
+     */
+    run(caller: CheckCaller, itemId: string, guideId: string, checkId: string, body: CheckSelection & {
+        force?: boolean | undefined;
+    }): Promise<SetupCheckState>;
+    /**
+     * Authorization and the guide (the guide route's rules, `PluginGuides.render`: catalog
+     * visibility, then the place and audience action, then the target), then the check's presence
+     * in the guide rendered for that mode and audience (404 `catalog.check_not_found`), then the
+     * target (400: checks need a saved connection or connector).
+     */
+    private prepare;
+    /**
+     * A plugin check runs only where its extension runs on this replica, is enabled in the org and
+     * has a valid effective config there (nothing is called otherwise): the effective config, or the
+     * kernel's answer.
+     */
+    private pluginGate;
+    /** The Redis keys of a check of the prepared target (spec §10.7). */
+    private keys;
+    /**
+     * The input revision of a prepared target (spec §10.4): the target's and its credentials'
+     * `updated_at`, the org's extension config and copy revisions; never a value.
+     */
+    private revision;
+    private channelRevision;
+    private connectorRevision;
+    /**
+     * The input fingerprint (spec §10.4): an HMAC with a key derived from the kernel's master key
+     * over revisions only (the target and credentials revision, the org config revisions, the
+     * plugin version, the loaded extension version and the mode), never a value, so it cannot be
+     * reversed to a secret.
+     */
+    private fingerprint;
+    /**
+     * After the lock is taken: the cache read again. A fresh result written since the first read
+     * (another run settled in between) is answered as is, with its cooldown when this was a forced
+     * run; null when this run must call the check.
+     */
+    private settledWhileLocking;
+    /** Counts one run of the account in its window; false at the limit (nothing counted). */
+    private allowRun;
+    /** Writes a result (TTL 5 min) and the force cooldown (10 s), outside any transaction. */
+    private store;
+    /**
+     * Loads the target (built field by field), runs the check against the time limit and turns what
+     * it answers into a validated, redacted, re-validated result. Never throws for anything the
+     * check does: a throw, a timeout or an invalid result is an `unknown` result.
+     */
+    private execute;
+    /**
+     * The target material: for a channel connection its revision and stored secret values (and, for
+     * a plugin check, the connection config decrypted exactly as `channel@1` verify gets it); for a
+     * connector its credentials' values (redaction only), the manual OAuth client id and the
+     * template id. A `result` when the material cannot be read (the check is not called).
+     */
+    private material;
+    /** The secret values of the extension's platform and effective deployment config. */
+    private configSecrets;
+    /**
+     * The secret values of the extension's org-level config (`config.org`) in the org: the check
+     * never gets them, but the extension holds them, so a result is redacted by them too. Nothing
+     * when the plugin has no org config; a read that fails throws (the check is not run: a result
+     * is never redacted by fewer secrets than the extension holds).
+     */
+    private orgConfigSecrets;
+    /** The frozen arguments of a plugin check (the target built field by field). */
+    private pluginArgs;
+}