@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/themes/theme-usage.d.ts

@@ -0,0 +1,61 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+/** Where a theme is chosen (spec §7). */
+export interface ThemeUsage {
+    /** It is the platform default (`uiTheme.id`). */
+    platformDefault: boolean;
+    /** The live orgs whose default it is, by name. */
+    orgDefaults: {
+        orgId: string;
+        orgName: string;
+    }[];
+    /** The accounts that picked it (`accounts.theme`). */
+    pickedBy: number;
+}
+/**
+ * One theme a change takes away from some orgs, as a preview lists it (`themes?` of the scope,
+ * disable, uninstall and update previews): the orgs among those losing it whose default it is, and
+ * the number of people who picked it among those orgs' members (a preview never counts people of
+ * orgs it does not name).
+ */
+export interface ThemePreview {
+    id: string;
+    orgDefaults: {
+        orgId: string;
+        orgName: string;
+    }[];
+    pickedBy: number;
+}
+/** What a theme's availability is after a change: still `all`, narrower, or gone. */
+export type ThemeAfter = "all" | "narrower" | "gone";
+/**
+ * The platform default theme's id (null: the built-in theme, or not set), through the setting's
+ * typed reader; `lock`: the row is read FOR SHARE, so a concurrent write of the setting (which
+ * locks it FOR UPDATE first, see `SettingsService`) waits for the caller's transaction, and the
+ * reverse.
+ */
+export declare function platformDefaultThemeId(db: KernelSchemaDb, opts?: {
+    lock?: boolean;
+}): Promise<string | null>;
+/** Where theme `themeId` (a `platform_themes` id) is chosen: see {@link ThemeUsage}. */
+export declare function themeUsage(db: KernelSchemaDb, themeId: string): Promise<ThemeUsage>;
+/**
+ * The `themes` block of a preview: for each theme of `lost` (theme id -> the orgs losing it) that
+ * some org loses, the orgs among those whose default it is and how many of their members picked
+ * it, by id.
+ * Undefined when no theme is lost, so a preview without themes keeps its shape and its hash.
+ */
+export declare function themesPreview(db: KernelSchemaDb, lost: ReadonlyMap<string, ReadonlySet<string>>): Promise<ThemePreview[] | undefined>;
+/** How many members of `orgs` (each counted once) picked theme `id`. */
+export declare function pickedByIn(db: KernelSchemaDb, id: string, orgs: ReadonlySet<string>): Promise<number>;
+/** 409 `theme.platform_default`: theme `theme` is the platform default (spec §7). */
+export declare const platformDefaultError: (theme: string) => ApiError;
+/**
+ * Refuses a change that takes the platform default theme away from any org (spec §7): when one of
+ * `themeIds` is the platform default and `after` says it would no longer be `all` (narrower, or
+ * gone), 409 `theme.platform_default`. Call it in the change's transaction before anything is
+ * written, after locking the catalog item or theme rows the change touches (the one theme lock
+ * order: catalog item, theme row, then the `uiTheme` row, which this reads FOR SHARE; the setting's
+ * write takes them in the same order).
+ */
+export declare function assertNotPlatformDefault(db: KernelSchemaDb, themeIds: readonly string[], after: (id: string) => ThemeAfter): Promise<void>;

package/dist/themes/theme-usage.js

@@ -0,0 +1,98 @@
+// Who uses a theme (themes spec §6 "Losing access", §7): the platform default (`deployment_settings`
+// key `uiTheme`), the orgs whose default it is (`orgs.settings.theme.id`) and the people who picked
+// it (`accounts.theme`); the previews of changes that take a theme away list them, and the guard
+// refuses any change that takes the platform default away from an org. Plain reads in the caller's
+// context (a transaction's connection when there is one). The settings are read through the same
+// readers and schemas as their services (`readUiTheme`, `parseOrgSettings`), so the two never drift.
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { readUiTheme, UI_THEME_SETTING } from "../identity/settings.js";
+import { parseOrgSettings } from "../orgs/settings.service.js";
+/**
+ * The platform default theme's id (null: the built-in theme, or not set), through the setting's
+ * typed reader; `lock`: the row is read FOR SHARE, so a concurrent write of the setting (which
+ * locks it FOR UPDATE first, see `SettingsService`) waits for the caller's transaction, and the
+ * reverse.
+ */
+export async function platformDefaultThemeId(db, opts = {}) {
+    return (await readUiTheme(db, opts)).id;
+}
+/** Where theme `themeId` (a `platform_themes` id) is chosen: see {@link ThemeUsage}. */
+export async function themeUsage(db, themeId) {
+    const platformDefault = (await platformDefaultThemeId(db)) === themeId;
+    // the jsonb filter narrows the rows; the typed parse decides (an invalid stored value is no default)
+    const orgs = (await db
+        .selectFrom("orgs")
+        .select(["id", "name", "settings"])
+        .where("deleted_at", "is", null)
+        .where(sql `settings -> 'theme' ->> 'id'`, "=", themeId)
+        .orderBy("name")
+        .orderBy("id")
+        .execute()).filter((o) => parseOrgSettings(o.settings).theme?.id === themeId);
+    const picked = await db
+        .selectFrom("accounts")
+        .select((eb) => eb.fn.countAll().as("n"))
+        .where("theme", "=", themeId)
+        .executeTakeFirstOrThrow();
+    return {
+        platformDefault,
+        orgDefaults: orgs.map((o) => ({ orgId: o.id, orgName: o.name })),
+        pickedBy: Number(picked.n),
+    };
+}
+/**
+ * The `themes` block of a preview: for each theme of `lost` (theme id -> the orgs losing it) that
+ * some org loses, the orgs among those whose default it is and how many of their members picked
+ * it, by id.
+ * Undefined when no theme is lost, so a preview without themes keeps its shape and its hash.
+ */
+export async function themesPreview(db, lost) {
+    const out = [];
+    for (const id of [...lost.keys()].sort()) {
+        const orgs = lost.get(id);
+        if (!orgs || orgs.size === 0)
+            continue;
+        const u = await themeUsage(db, id);
+        out.push({
+            id,
+            orgDefaults: u.orgDefaults.filter((o) => orgs.has(o.orgId)),
+            pickedBy: await pickedByIn(db, id, orgs),
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+/** How many members of `orgs` (each counted once) picked theme `id`. */
+export async function pickedByIn(db, id, orgs) {
+    if (orgs.size === 0)
+        return 0;
+    const picked = await db
+        .selectFrom("accounts as a")
+        .select((eb) => eb.fn.count("a.id").distinct().as("n"))
+        .where("a.theme", "=", id)
+        .where((eb) => eb.exists(eb
+        .selectFrom("memberships as m")
+        .select("m.account_id")
+        .whereRef("m.account_id", "=", "a.id")
+        .where("m.org_id", "in", [...orgs])))
+        .executeTakeFirstOrThrow();
+    return Number(picked.n);
+}
+/** 409 `theme.platform_default`: theme `theme` is the platform default (spec §7). */
+export const platformDefaultError = (theme) => new ApiError("theme.platform_default", `Theme ${theme} is the platform default theme (setting ${UI_THEME_SETTING}): it must stay on in every organization. Choose another platform default theme first, then narrow, disable or remove this one`, [{ theme, setting: UI_THEME_SETTING }]);
+/**
+ * Refuses a change that takes the platform default theme away from any org (spec §7): when one of
+ * `themeIds` is the platform default and `after` says it would no longer be `all` (narrower, or
+ * gone), 409 `theme.platform_default`. Call it in the change's transaction before anything is
+ * written, after locking the catalog item or theme rows the change touches (the one theme lock
+ * order: catalog item, theme row, then the `uiTheme` row, which this reads FOR SHARE; the setting's
+ * write takes them in the same order).
+ */
+export async function assertNotPlatformDefault(db, themeIds, after) {
+    if (themeIds.length === 0)
+        return;
+    const id = await platformDefaultThemeId(db, { lock: true });
+    if (id === null || !themeIds.includes(id))
+        return;
+    if (after(id) !== "all")
+        throw platformDefaultError(id);
+}

package/dist/themes/themes-public.controller.d.ts

@@ -0,0 +1,28 @@
+import type { FastifyReply } from "fastify";
+import { ThemeDeliveryService } from "./theme-delivery.service.js";
+import type { ThemeRef } from "./theme-state.js";
+import { ThemesService } from "./themes.service.js";
+/**
+ * Theme delivery (themes spec §8): every theme version's stylesheet and assets, public (styles are
+ * not sensitive; the URLs reveal only that the theme exists) and immutable. The URLs are the ones
+ * `themeUrl` builds; an unknown theme, version or file is 404 `theme.not_found`.
+ */
+export declare class ThemeDeliveryController {
+    private readonly delivery;
+    constructor(delivery: ThemeDeliveryService);
+    /** The version's stylesheet: scheme overrides, `@font-face` rules and font stacks. */
+    css(id: string, version: string, reply: FastifyReply): Promise<void>;
+    /**
+     * A font (`font/woff2`) or logo (`image/svg+xml`, sanitized at import, served under a CSP
+     * sandbox; `image/png`) the version names; `file` is its plugin path as one segment
+     * (`fonts%2FMiSans.woff2`).
+     */
+    asset(id: string, version: string, file: string, reply: FastifyReply): Promise<void>;
+}
+/** The platform default theme for pages before sign-in (themes spec §8-§9), public. */
+export declare class PlatformThemeController {
+    private readonly themes;
+    constructor(themes: ThemesService);
+    /** The platform default's reference while it is eligible; null: the built-in theme. */
+    platformTheme(): Promise<ThemeRef | null>;
+}

package/dist/themes/themes-public.controller.js

@@ -0,0 +1,92 @@
+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, Header, Inject, Param, Res } from "@nestjs/common";
+import { Public } from "../identity/principal.js";
+import { ThemeDeliveryService } from "./theme-delivery.service.js";
+import { ThemesService } from "./themes.service.js";
+/** A theme version's stylesheet and assets never change (the version is in the URL). */
+const IMMUTABLE = "public, max-age=31536000, immutable";
+/**
+ * Theme delivery (themes spec §8): every theme version's stylesheet and assets, public (styles are
+ * not sensitive; the URLs reveal only that the theme exists) and immutable. The URLs are the ones
+ * `themeUrl` builds; an unknown theme, version or file is 404 `theme.not_found`.
+ */
+let ThemeDeliveryController = class ThemeDeliveryController {
+    delivery;
+    constructor(delivery) {
+        this.delivery = delivery;
+    }
+    /** The version's stylesheet: scheme overrides, `@font-face` rules and font stacks. */
+    async css(id, version, reply) {
+        const css = await this.delivery.stylesheet(id, version);
+        await reply
+            .header("content-type", "text/css; charset=utf-8")
+            .header("x-content-type-options", "nosniff")
+            .header("cache-control", IMMUTABLE)
+            .send(css);
+    }
+    /**
+     * A font (`font/woff2`) or logo (`image/svg+xml`, sanitized at import, served under a CSP
+     * sandbox; `image/png`) the version names; `file` is its plugin path as one segment
+     * (`fonts%2FMiSans.woff2`).
+     */
+    async asset(id, version, file, reply) {
+        const a = await this.delivery.asset(id, version, file);
+        reply
+            .header("content-type", a.contentType)
+            .header("x-content-type-options", "nosniff")
+            .header("cache-control", IMMUTABLE);
+        if (a.contentType === "image/svg+xml") {
+            reply.header("content-security-policy", "default-src 'none'; sandbox");
+        }
+        await reply.send(Buffer.from(a.data.buffer, a.data.byteOffset, a.data.byteLength));
+    }
+};
+__decorate([
+    Public(),
+    Get("theme.css"),
+    __param(0, Param("id")),
+    __param(1, Param("version")),
+    __param(2, Res())
+], ThemeDeliveryController.prototype, "css", null);
+__decorate([
+    Public(),
+    Get("assets/:file"),
+    __param(0, Param("id")),
+    __param(1, Param("version")),
+    __param(2, Param("file")),
+    __param(3, Res())
+], ThemeDeliveryController.prototype, "asset", null);
+ThemeDeliveryController = __decorate([
+    Controller("api/v1/themes/:id/:version"),
+    __param(0, Inject(ThemeDeliveryService))
+], ThemeDeliveryController);
+export { ThemeDeliveryController };
+/** The platform default theme for pages before sign-in (themes spec §8-§9), public. */
+let PlatformThemeController = class PlatformThemeController {
+    themes;
+    constructor(themes) {
+        this.themes = themes;
+    }
+    /** The platform default's reference while it is eligible; null: the built-in theme. */
+    platformTheme() {
+        return this.themes.platformDefault();
+    }
+};
+__decorate([
+    Public(),
+    Get(),
+    Header("cache-control", "no-store")
+], PlatformThemeController.prototype, "platformTheme", null);
+PlatformThemeController = __decorate([
+    Controller("api/v1/platform/theme"),
+    __param(0, Inject(ThemesService))
+], PlatformThemeController);
+export { PlatformThemeController };

package/dist/themes/themes.controller.d.ts

@@ -0,0 +1,13 @@
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type OrgThemes, ThemesService } from "./themes.service.js";
+/** The org's themes (`/api/v1/orgs/:orgId/themes`, themes spec §9): members only. */
+export declare class OrgThemesController {
+    private readonly themes;
+    constructor(themes: ThemesService);
+    /**
+     * `{ themes, resolved, org }`: the themes on in the org (with swatches), the viewer's resolved
+     * theme (null: the built-in one) and the org's default and personal lock.
+     */
+    list(principal: Principal, org: OrgContext): Promise<OrgThemes>;
+}

package/dist/themes/themes.controller.js

@@ -0,0 +1,38 @@
+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, Inject } from "@nestjs/common";
+import { CurrentPrincipal } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ThemesService } from "./themes.service.js";
+/** The org's themes (`/api/v1/orgs/:orgId/themes`, themes spec §9): members only. */
+let OrgThemesController = class OrgThemesController {
+    themes;
+    constructor(themes) {
+        this.themes = themes;
+    }
+    /**
+     * `{ themes, resolved, org }`: the themes on in the org (with swatches), the viewer's resolved
+     * theme (null: the built-in one) and the org's default and personal lock.
+     */
+    async list(principal, org) {
+        return this.themes.forOrg(org.orgId, principal.kind === "user" ? principal.account.id : null);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], OrgThemesController.prototype, "list", null);
+OrgThemesController = __decorate([
+    Controller("api/v1/orgs/:orgId/themes"),
+    __param(0, Inject(ThemesService))
+], OrgThemesController);
+export { OrgThemesController };

package/dist/themes/themes.module.d.ts

@@ -0,0 +1,3 @@
+/** Themes (themes spec §7-§9): resolution, the org's theme listing and delivery. */
+export declare class ThemesModule {
+}

package/dist/themes/themes.module.js

@@ -0,0 +1,21 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { StorageModule } from "../storage/storage.module.js";
+import { ThemeDeliveryService } from "./theme-delivery.service.js";
+import { ThemesService } from "./themes.service.js";
+/** Themes (themes spec §7-§9): resolution, the org's theme listing and delivery. */
+let ThemesModule = class ThemesModule {
+};
+ThemesModule = __decorate([
+    Module({
+        imports: [StorageModule],
+        providers: [ThemesService, ThemeDeliveryService],
+        exports: [ThemesService, ThemeDeliveryService],
+    })
+], ThemesModule);
+export { ThemesModule };

package/dist/themes/themes.schemas.d.ts

@@ -0,0 +1,3 @@
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** The theme routes the Platform operations mirror (`check:platform-ops` keys). */
+export declare const THEME_ROUTES: readonly RouteSchemas[];

package/dist/themes/themes.schemas.js

@@ -0,0 +1,2 @@
+/** The theme routes the Platform operations mirror (`check:platform-ops` keys). */
+export const THEME_ROUTES = [{ route: "GET /api/v1/orgs/:orgId/themes" }];

package/dist/themes/themes.service.d.ts

@@ -0,0 +1,50 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type ListedTheme, type ThemeRef } from "./theme-state.js";
+/** `GET /api/v1/orgs/:orgId/themes` (themes spec §9). */
+export interface OrgThemes {
+    /** The themes on in the org, by English name. */
+    themes: ListedTheme[];
+    /** The viewer's theme ({@link ThemesService.resolve}); null: the built-in theme. */
+    resolved: ThemeRef | null;
+    /**
+     * The org's setting as stored: its default (null: follow the platform) and the personal lock.
+     * The stored id may name a theme absent from `themes` (it went off in the org after it was
+     * chosen; resolution skips it): the UI shows it as unavailable, not as selected.
+     */
+    org: {
+        id: string | null;
+        personal: "allowed" | "locked";
+    };
+}
+/**
+ * Which theme applies (themes spec §7) and the org's theme listing. Read-only; the levels are
+ * written by their settings services (deployment, org, person), which check availability with the
+ * same predicates (`theme-state.ts`).
+ */
+export declare class ThemesService {
+    private readonly db;
+    constructor(db: KernelDb);
+    /** The themes on in the org with their references and swatches, by English name then id. */
+    listForOrg(orgId: string): Promise<ListedTheme[]>;
+    /**
+     * The theme of a signed-in page in the org (spec §7): the person's pick if it is on in the org
+     * and the org does not lock; else the org's default if on; else the platform default if on in
+     * the org; else null (the built-in theme). An unavailable choice is skipped, never an error.
+     * `accountId` null (a service token): no personal pick.
+     */
+    resolve(orgId: string, accountId: string | null): Promise<ThemeRef | null>;
+    /** The platform default for pages before sign-in, when it is still eligible (spec §7); else null. */
+    platformDefault(): Promise<ThemeRef | null>;
+    /**
+     * The listing, the viewer's resolved theme and the org's setting. Separate reads, not one
+     * snapshot: a change committed between them shows at the next read.
+     */
+    forOrg(orgId: string, accountId: string | null): Promise<OrgThemes>;
+    /** A live theme's name (the super admin's summaries); null when there is no such theme. */
+    nameOf(id: string): Promise<LocalizedName | null>;
+    /** Theme `id`'s name if it is on in the org, else null (a summary never names another org's theme). */
+    nameIn(orgId: string, id: string): Promise<LocalizedName | null>;
+    /** Theme `id`'s name if it is on in one of the person's orgs, else null (same reason). */
+    nameForAccount(accountId: string, id: string): Promise<LocalizedName | null>;
+}

package/dist/themes/themes.service.js

@@ -0,0 +1,99 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { readUiTheme } from "../identity/settings.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { DEFAULT_ORG_THEME, readOrgSettings } from "../orgs/settings.service.js";
+import { eligiblePlatformDefault, themeDefinitions, themeOnForAccount, themeOnIn, themeRefOf, themeSwatches, themesOnIn, } from "./theme-state.js";
+/**
+ * Which theme applies (themes spec §7) and the org's theme listing. Read-only; the levels are
+ * written by their settings services (deployment, org, person), which check availability with the
+ * same predicates (`theme-state.ts`).
+ */
+let ThemesService = class ThemesService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** The themes on in the org with their references and swatches, by English name then id. */
+    async listForOrg(orgId) {
+        const on = await themesOnIn(this.db.db, orgId);
+        const defs = await themeDefinitions(this.db.db, on.map((c) => c.id));
+        const out = [];
+        for (const c of on) {
+            const d = defs.get(c.id);
+            if (!d)
+                continue;
+            out.push({
+                ...themeRefOf(c.id, d.version, d.definition),
+                swatches: themeSwatches(d.definition),
+            });
+        }
+        return out.sort((a, b) => a.name.en < b.name.en ? -1 : a.name.en > b.name.en ? 1 : a.id < b.id ? -1 : 1);
+    }
+    /**
+     * The theme of a signed-in page in the org (spec §7): the person's pick if it is on in the org
+     * and the org does not lock; else the org's default if on; else the platform default if on in
+     * the org; else null (the built-in theme). An unavailable choice is skipped, never an error.
+     * `accountId` null (a service token): no personal pick.
+     */
+    async resolve(orgId, accountId) {
+        return (await this.forOrg(orgId, accountId)).resolved;
+    }
+    /** The platform default for pages before sign-in, when it is still eligible (spec §7); else null. */
+    async platformDefault() {
+        const { id } = await readUiTheme(this.db.db);
+        if (id === null || (await eligiblePlatformDefault(this.db.db, id)) === null)
+            return null;
+        const d = (await themeDefinitions(this.db.db, [id])).get(id);
+        return d ? themeRefOf(id, d.version, d.definition) : null;
+    }
+    /**
+     * The listing, the viewer's resolved theme and the org's setting. Separate reads, not one
+     * snapshot: a change committed between them shows at the next read.
+     */
+    async forOrg(orgId, accountId) {
+        const themes = await this.listForOrg(orgId);
+        const org = (await readOrgSettings(this.db.db, orgId)).theme ?? DEFAULT_ORG_THEME;
+        const pick = accountId === null || org.personal === "locked"
+            ? null
+            : ((await this.db
+                .selectFrom("accounts")
+                .select("theme")
+                .where("id", "=", accountId)
+                .executeTakeFirst())?.theme ?? null);
+        const platform = (await readUiTheme(this.db.db)).id;
+        const on = (id) => (id === null ? undefined : themes.find((t) => t.id === id));
+        const hit = on(pick) ?? on(org.id) ?? on(platform);
+        let resolved = null;
+        if (hit) {
+            const { swatches: _swatches, ...ref } = hit;
+            resolved = ref;
+        }
+        return { themes, resolved, org: { id: org.id, personal: org.personal } };
+    }
+    /** A live theme's name (the super admin's summaries); null when there is no such theme. */
+    async nameOf(id) {
+        return (await themeDefinitions(this.db.db, [id])).get(id)?.definition.name ?? null;
+    }
+    /** Theme `id`'s name if it is on in the org, else null (a summary never names another org's theme). */
+    async nameIn(orgId, id) {
+        return (await themeOnIn(this.db.db, orgId, id)) ? this.nameOf(id) : null;
+    }
+    /** Theme `id`'s name if it is on in one of the person's orgs, else null (same reason). */
+    async nameForAccount(accountId, id) {
+        return (await themeOnForAccount(this.db.db, accountId, id)) ? this.nameOf(id) : null;
+    }
+};
+ThemesService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], ThemesService);
+export { ThemesService };

package/dist/time-zone.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+/** Whether `tz` is an IANA time zone this runtime knows (run context spec §3.3, §3.4). */
+export declare function isTimeZone(tz: string): boolean;
+/** An IANA time zone name, checked with `Intl.DateTimeFormat`. */
+export declare const IanaTimeZone: z.ZodString;

package/dist/time-zone.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/** Whether `tz` is an IANA time zone this runtime knows (run context spec §3.3, §3.4). */
+export function isTimeZone(tz) {
+    if (tz === "" || tz.length > 64)
+        return false;
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** An IANA time zone name, checked with `Intl.DateTimeFormat`. */
+export const IanaTimeZone = z
+    .string()
+    .min(1)
+    .max(64)
+    .refine(isTimeZone, "must be an IANA time zone name, such as Asia/Shanghai");

package/dist/tools/approvals.controller.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import { type ApprovalRecord, type ApprovalsService, type ApprovalView, type ToolGrantView } from "./approvals.service.js";
+import { type ApprovalRecord, ApprovalsService, type ApprovalView, type ToolGrantView } from "./approvals.service.js";
 declare const ListQuery: z.ZodObject<{
     status: z.ZodOptional<z.ZodEnum<{
         approved: "approved";

package/dist/tools/approvals.controller.js

@@ -7,17 +7,16 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post, Query, } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
 import { z } from "zod";
-import { APPROVALS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { CONTROL_OR_HIDDEN_RE } from "../text.js";
-import { APPROVAL_DENY_REASON_MAX_CHARS, } from "./approvals.service.js";
-const ListQuery = z
-    .object({ status: z.enum(["pending", "approved", "denied", "expired", "cancelled"]).optional() })
-    .strict();
+import { ApprovalsListQuerySchema } from "./approvals.schemas.js";
+import { APPROVAL_DENY_REASON_MAX_CHARS, ApprovalsService, } from "./approvals.service.js";
+const ListQuery = ApprovalsListQuerySchema;
 const DecisionBody = z
     .object({
     decision: z.enum(["approve", "deny"]),
@@ -39,6 +38,10 @@ const DecisionBody = z
     path: ["reason"],
     message: "A reason can only be given with deny",
 });
+class ApprovalsListQuery extends createZodDto(ListQuery, "ApprovalsListQuery") {
+}
+class ApprovalDecisionBody extends createZodDto(DecisionBody, "ApprovalDecisionBody") {
+}
 /**
  * 工具调用审批（`/api/v1/orgs/:orgId/approvals`，`approvals.decide`：访客起、仅限用户主体——agent 不能审批，R2）。
  * 能否看到 / 处理某条审批由 `requested_for` / `approver_role` 判定（见 `ApprovalsService`），看不到的一律 404。
@@ -68,7 +71,7 @@ __decorate([
     OrgAction("approvals.decide"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Query(new ZodPipe(ListQuery)))
+    __param(2, ZQuery(ApprovalsListQuery))
 ], ApprovalsController.prototype, "list", null);
 __decorate([
     Get(":id"),
@@ -84,11 +87,11 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, Body(new ZodPipe(DecisionBody)))
+    __param(3, ZBody(ApprovalDecisionBody))
 ], ApprovalsController.prototype, "decide", null);
 ApprovalsController = __decorate([
     Controller("api/v1/orgs/:orgId/approvals"),
-    __param(0, Inject(APPROVALS))
+    __param(0, Inject(ApprovalsService))
 ], ApprovalsController);
 export { ApprovalsController };
 /** 本人的「以后都允许」授权（`/api/v1/orgs/:orgId/me/tool-grants`）：查看与撤销，只动自己的。 */
@@ -123,6 +126,6 @@ __decorate([
 ], ToolGrantsController.prototype, "revoke", null);
 ToolGrantsController = __decorate([
     Controller("api/v1/orgs/:orgId/me/tool-grants"),
-    __param(0, Inject(APPROVALS))
+    __param(0, Inject(ApprovalsService))
 ], ToolGrantsController);
 export { ToolGrantsController };

package/dist/tools/approvals.schemas.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `GET /approvals?status=`: absent lists every status. */
+export declare const ApprovalsListQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        approved: "approved";
+        cancelled: "cancelled";
+        denied: "denied";
+        expired: "expired";
+        pending: "pending";
+    }>>;
+}, z.core.$strict>;
+/** `:id` of `GET /approvals/:id`, as the route takes it (`@Param`). */
+export declare const ApprovalPathParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The approval reads a Platform operation mirrors. Deciding (`POST /approvals/:id/decision`) is a
+ * person's act and stays excluded (spec §6.4, §14.1 item 2), so it has no entry here.
+ */
+export declare const APPROVAL_ROUTES: readonly RouteSchemas[];