@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/inbox/inbox.service.js

@@ -8,26 +8,36 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
 import { CATALOG_REQUESTS_LIST_MAX, CatalogRequestsService, } from "../catalog/requests.service.js";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { roleAtLeast } from "../orgs/roles.js";
 import { SKILL_CHANGES_LIST_MAX, SkillChangesService, } from "../skills/changes.service.js";
 import { APPROVALS_LIST_MAX, ApprovalsService, } from "../tools/approvals.service.js";
+/** The most open org notices one inbox read returns. */
+export const ORG_NOTICES_LIST_MAX = 100;
 /** 收件箱一次最多返回的事项数。 */
 export const INBOX_MAX_ITEMS = 100;
 /** 收件箱（计划取舍 C6）：按类型汇总各来源的待处理事项。无状态，每次实时读 PG。 */
 let InboxService = class InboxService {
     approvals;
     skillChanges;
+    kdb;
     catalogRequests;
-    constructor(approvals, skillChanges, catalogRequests) {
+    constructor(approvals, skillChanges, kdb, catalogRequests) {
         this.approvals = approvals;
         this.skillChanges = skillChanges;
+        this.kdb = kdb;
         this.catalogRequests = catalogRequests;
     }
     async list(orgId, accountId) {
-        const [approvals, changes, requests] = await Promise.all([
+        const [approvals, changes, requests, decided, notices] = await Promise.all([
             this.approvals.list(orgId, accountId, "pending"),
             this.skillChanges.listPending(orgId, accountId),
             this.catalogRequests.listForOrgAdmin(orgId, accountId),
+            this.catalogRequests.listDecidedForRequester(orgId, accountId),
+            this.notices(orgId, accountId),
         ]);
         const all = [
             ...approvals.map((a) => ({
@@ -48,6 +58,13 @@ let InboxService = class InboxService {
                 createdAt: r.createdAt,
                 request: r,
             })),
+            ...decided.map((r) => ({
+                type: "catalog_request_decided",
+                id: r.id,
+                createdAt: r.decidedAt ?? r.createdAt,
+                request: r,
+            })),
+            ...notices.map((n) => ({ type: n.kind, id: n.id, createdAt: n.createdAt, notice: n })),
         ];
         // 新的在前；同一时刻按 id 定序（结果稳定）
         all.sort((a, b) => a.createdAt !== b.createdAt
@@ -62,17 +79,70 @@ let InboxService = class InboxService {
         // 各来源自己也有上限：某个来源取满了也算还有更多
         const full = approvals.length >= APPROVALS_LIST_MAX ||
             changes.length >= SKILL_CHANGES_LIST_MAX ||
-            requests.length >= CATALOG_REQUESTS_LIST_MAX;
+            requests.length >= CATALOG_REQUESTS_LIST_MAX ||
+            decided.length >= CATALOG_REQUESTS_LIST_MAX ||
+            notices.length >= ORG_NOTICES_LIST_MAX;
         return {
             items: all.slice(0, INBOX_MAX_ITEMS),
             truncated: full || all.length > INBOX_MAX_ITEMS,
         };
     }
+    /** The org's open notices when the account is an org admin (else none), newest first. */
+    async notices(orgId, accountId) {
+        if (!(await this.isAdmin(orgId, accountId)))
+            return [];
+        const rows = await this.kdb.db
+            .selectFrom("org_notices")
+            .select(["id", "kind", "detail", "created_at"])
+            .where("org_id", "=", orgId)
+            .where("dismissed_at", "is", null)
+            .orderBy("created_at", "desc")
+            .orderBy("id")
+            .limit(ORG_NOTICES_LIST_MAX)
+            .execute();
+        return rows.map((r) => {
+            const base = { id: r.id, createdAt: r.created_at.toISOString() };
+            if (r.kind === "skill_renamed") {
+                return { ...base, kind: r.kind, skillRenamed: r.detail };
+            }
+            return { ...base, kind: r.kind, detail: r.detail };
+        });
+    }
+    /**
+     * An org admin dismisses an open notice (`POST /orgs/:orgId/inbox/notices/:id/dismiss`); for
+     * every admin of the org. Not an admin, or no open notice of the org with that id ->
+     * `inbox.notice_not_found`.
+     */
+    async dismissNotice(orgId, accountId, id) {
+        const notFound = new ApiError("inbox.notice_not_found", "Notice not found");
+        if (!UUID_RE.test(id) || !(await this.isAdmin(orgId, accountId)))
+            throw notFound;
+        const r = await this.kdb.db
+            .updateTable("org_notices")
+            .set({ dismissed_at: sql `now()`, dismissed_by: accountId })
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("dismissed_at", "is", null)
+            .executeTakeFirst();
+        if (r.numUpdatedRows === 0n)
+            throw notFound;
+    }
+    async isAdmin(orgId, accountId) {
+        const m = await this.kdb.db
+            .selectFrom("memberships")
+            .select("role")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        return m !== undefined && roleAtLeast(m.role, "admin");
+    }
 };
 InboxService = __decorate([
     Injectable(),
     __param(0, Inject(ApprovalsService)),
     __param(1, Inject(SkillChangesService)),
-    __param(2, Inject(CatalogRequestsService))
+    __param(2, Inject(KernelDb)),
+    __param(3, Inject(CatalogRequestsService))
 ], InboxService);
 export { InboxService };
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/dist/inbox/org-notices.d.ts

@@ -0,0 +1,63 @@
+import { type OwnedRef, type Owner } from "../catalog/ownership.js";
+import type { KernelSchemaDb, OrgNoticeKind } from "../db/kernel-schema.js";
+export type { OrgNoticeKind };
+/** The `detail` of each notice kind except `skill_renamed` (written by the platform migration). */
+export interface OrgNoticeDetails {
+    /** An org was added to the item's list, or its scope widened (`all_orgs`). */
+    /** `displayName`: a plugin's display name, which the inbox names it by (null otherwise). */
+    item_shared: {
+        ref: OwnedRef;
+        name: string;
+        displayName: LocalizedName;
+        org: {
+            id: string;
+            name: string;
+        } | "all_orgs";
+    };
+    /** A shared org-owned item changed version, for the orgs it is on in. */
+    shared_item_updated: {
+        ref: OwnedRef;
+        name: string;
+        displayName: LocalizedName;
+        from: string;
+        to: string;
+        owner: Owner;
+    };
+    /** `displayName`: the plugin's display name, which the inbox names it by (null without one). */
+    upload_confirmed: {
+        itemId: string;
+        name: string;
+        displayName: LocalizedName;
+        version: string;
+    };
+    upload_rejected: {
+        itemId: string;
+        name: string;
+        displayName: LocalizedName;
+        version: string;
+        reason: string | null;
+    };
+}
+type LocalizedName = {
+    zh: string;
+    en: string;
+} | null;
+/** A catalog item's display name for an upload notice (null without one, or for an unknown id). */
+export declare function itemDisplayName(db: KernelSchemaDb, itemId: string): Promise<LocalizedName>;
+/** Writes an org notice in the caller's transaction. */
+export declare function addOrgNotice<K extends keyof OrgNoticeDetails>(db: KernelSchemaDb, orgId: string, kind: K, detail: OrgNoticeDetails[K]): Promise<void>;
+/**
+ * Tells the owner org that its item was shared (`item_shared`): with each org of `orgs` (the owner
+ * itself is skipped), or with `all_orgs`. A platform-owned item writes nothing.
+ */
+export declare function notifyItemShared(db: KernelSchemaDb, ownerOrgId: string | null, ref: OwnedRef, name: string, orgs: readonly string[] | "all_orgs"): Promise<void>;
+/**
+ * Tells every live org the org-owned item is on in, except its owner (P3-18, {@link orgsUsing}),
+ * that it changed version (`shared_item_updated`); returns how many orgs were told. A platform-owned
+ * or missing item tells nobody.
+ */
+export declare function notifySharedUpdate(db: KernelSchemaDb, ref: OwnedRef, change: {
+    name: string;
+    from: string;
+    to: string;
+}): Promise<number>;

package/dist/inbox/org-notices.js

@@ -0,0 +1,91 @@
+// Org notices (`org_notices`, plugin scope phase 3, spec §14, ruling P3-22): what an org's admins
+// are told about shared items and uploads, until one of them dismisses it. The writers run in the
+// caller's transaction, so a notice exists exactly when its change does.
+import { randomUUID } from "node:crypto";
+import { orgsUsing, ownerOf, ownersOf } from "../catalog/ownership.js";
+/** An owned ref's display name: a plugin's (skills and agent templates have none). */
+const refDisplayName = (db, ref) => ref.kind === "plugin" ? itemDisplayName(db, ref.id) : Promise.resolve(null);
+/** A catalog item's display name for an upload notice (null without one, or for an unknown id). */
+export async function itemDisplayName(db, itemId) {
+    const row = await db
+        .selectFrom("catalog_items")
+        .select("display_name")
+        .where("id", "=", itemId)
+        .executeTakeFirst();
+    return row?.display_name ?? null;
+}
+/** Writes an org notice in the caller's transaction. */
+export async function addOrgNotice(db, orgId, kind, detail) {
+    await db
+        .insertInto("org_notices")
+        .values({ id: randomUUID(), org_id: orgId, kind, detail: JSON.stringify(detail) })
+        .execute();
+}
+const OWNER_TABLE = {
+    plugin: "catalog_items",
+    skill: "platform_skills",
+    agent_template: "platform_agent_templates",
+};
+/**
+ * Tells the owner org that its item was shared (`item_shared`): with each org of `orgs` (the owner
+ * itself is skipped), or with `all_orgs`. A platform-owned item writes nothing.
+ */
+export async function notifyItemShared(db, ownerOrgId, ref, name, orgs) {
+    if (ownerOrgId === null)
+        return;
+    const displayName = await refDisplayName(db, ref);
+    if (orgs === "all_orgs") {
+        await addOrgNotice(db, ownerOrgId, "item_shared", {
+            ref,
+            name,
+            displayName,
+            org: "all_orgs",
+        });
+        return;
+    }
+    const targets = [...new Set(orgs)].filter((o) => o !== ownerOrgId);
+    if (targets.length === 0)
+        return;
+    const rows = await db
+        .selectFrom("orgs")
+        .select(["id", "name"])
+        .where("id", "in", targets)
+        .execute();
+    const names = new Map(rows.map((r) => [r.id, r.name]));
+    for (const id of targets) {
+        await addOrgNotice(db, ownerOrgId, "item_shared", {
+            ref,
+            name,
+            displayName,
+            org: { id, name: names.get(id) ?? id },
+        });
+    }
+}
+/**
+ * Tells every live org the org-owned item is on in, except its owner (P3-18, {@link orgsUsing}),
+ * that it changed version (`shared_item_updated`); returns how many orgs were told. A platform-owned
+ * or missing item tells nobody.
+ */
+export async function notifySharedUpdate(db, ref, change) {
+    const row = await db
+        .selectFrom(OWNER_TABLE[ref.kind])
+        .select("owner_org_id")
+        .where("id", "=", ref.id)
+        .executeTakeFirst();
+    if (!row || row.owner_org_id === null)
+        return 0;
+    const owner = ownerOf(row.owner_org_id, await ownersOf(db, [row.owner_org_id]));
+    const using = await orgsUsing(db, ref, { except: row.owner_org_id });
+    const displayName = await refDisplayName(db, ref);
+    for (const o of using) {
+        await addOrgNotice(db, o.id, "shared_item_updated", {
+            ref,
+            name: change.name,
+            displayName,
+            from: change.from,
+            to: change.to,
+            owner,
+        });
+    }
+    return using.length;
+}

package/dist/inbox/platform-inbox.controller.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { PlatformInboxService, type PlatformInboxView } from "./platform-inbox.service.js";
+declare const NoticeParamsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The super admin's inbox (`GET /api/v1/admin/inbox`): the platform's requests, permission
+ * confirmations, scope sync failures and the migration run that needs a look, newest first, at
+ * most 100 (`truncated`: more, `total`: how many in all), and `GET /api/v1/admin/inbox/count`
+ * (`{ total }`, the sidebar's count). Super admins only (web session or personal token).
+ */
+export declare class PlatformInboxController {
+    private readonly inbox;
+    constructor(inbox: PlatformInboxService);
+    list(): Promise<PlatformInboxView>;
+    count(): Promise<{
+        total: number;
+    }>;
+    /** A super admin dismisses a platform notice (`ownership_transferred`) for every super admin. */
+    dismissNotice(principal: Principal, params: z.infer<typeof NoticeParamsSchema>): Promise<void>;
+}
+export {};

package/dist/inbox/platform-inbox.controller.js

@@ -0,0 +1,58 @@
+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 { z } from "zod";
+import { CurrentPrincipal, requireUser, SuperAdmin, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZParam } from "../infra/validation/zod-params.js";
+import { PlatformInboxService } from "./platform-inbox.service.js";
+const NoticeParamsSchema = z.object({ id: z.string().min(1).max(100) });
+class NoticeParams extends createZodDto(NoticeParamsSchema, "PlatformInboxNoticeParams") {
+}
+/**
+ * The super admin's inbox (`GET /api/v1/admin/inbox`): the platform's requests, permission
+ * confirmations, scope sync failures and the migration run that needs a look, newest first, at
+ * most 100 (`truncated`: more, `total`: how many in all), and `GET /api/v1/admin/inbox/count`
+ * (`{ total }`, the sidebar's count). Super admins only (web session or personal token).
+ */
+let PlatformInboxController = class PlatformInboxController {
+    inbox;
+    constructor(inbox) {
+        this.inbox = inbox;
+    }
+    list() {
+        return this.inbox.list();
+    }
+    async count() {
+        return { total: await this.inbox.count() };
+    }
+    /** A super admin dismisses a platform notice (`ownership_transferred`) for every super admin. */
+    async dismissNotice(principal, params) {
+        await this.inbox.dismissNotice(requireUser(principal).account.id, params.id);
+    }
+};
+__decorate([
+    Get()
+], PlatformInboxController.prototype, "list", null);
+__decorate([
+    Get("count")
+], PlatformInboxController.prototype, "count", null);
+__decorate([
+    Post("notices/:id/dismiss"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZParam(NoticeParams))
+], PlatformInboxController.prototype, "dismissNotice", null);
+PlatformInboxController = __decorate([
+    Controller("api/v1/admin/inbox"),
+    SuperAdmin(),
+    __param(0, Inject(PlatformInboxService))
+], PlatformInboxController);
+export { PlatformInboxController };

package/dist/inbox/platform-inbox.service.d.ts

@@ -0,0 +1,151 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import { type CatalogItemView, CatalogService } from "../catalog/catalog.service.js";
+import { CatalogRequestsService, type CatalogRequestView } from "../catalog/requests.service.js";
+import type { ScopeSyncOp } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { PlatformNoticeDetails } from "./platform-notices.js";
+/** The most items one platform inbox read returns. */
+export declare const PLATFORM_INBOX_MAX_ITEMS = 100;
+/** The most open scope sync failures one read takes. */
+export declare const SCOPE_SYNC_FAILURES_LIST_MAX = 200;
+/**
+ * A platform components migration run unfinished this long after its start is stuck (its worker
+ * stopped mid-run; a run takes seconds, and the next one starts at the next worker start or day).
+ */
+export declare const MIGRATION_RUN_STUCK_MS: number;
+/**
+ * An open failure of the plugin scope sync: its last attempt to install the plugin in the org, to
+ * uninstall it, or to install the dependencies a platform update added (`dependencies`) failed,
+ * and the org still differs from the scope in that direction.
+ */
+export interface ScopeSyncFailureView {
+    item: {
+        id: string;
+        name: string;
+        displayName: LocalizedName | null;
+    };
+    org: {
+        id: string;
+        name: string;
+    };
+    op: ScopeSyncOp;
+    /** The error code (`internal` for an unexpected error) and its message. */
+    code: string;
+    message: string;
+    failedAt: string;
+}
+/**
+ * The latest platform components migration run (`platform_migration_runs`) when it needs a look:
+ * finished with catalog items whose components could not be written (`itemsFailed`,
+ * `<name>@<version>`), or `stuck` (unfinished {@link MIGRATION_RUN_STUCK_MS} after its start).
+ */
+export interface MigrationRunView {
+    id: string;
+    startedAt: string;
+    finishedAt: string | null;
+    stuck: boolean;
+    itemsFailed: string[];
+}
+/**
+ * One item of the super admin's inbox (by `type`). Nothing is decided in the inbox: each item is
+ * acted on where it lives (the web links to it).
+ * - `catalog_request`: an org's pending request to the platform (`access`: use a plugin shown to
+ *   it; `import`: bring in a marketplace entry), as `GET /admin/catalog/requests` lists them;
+ * - `permission_confirmation`: a platform plugin whose extension permissions wait for a super
+ *   admin's confirmation (`GET /admin/catalog/items?pending=true`), `id` = the item's;
+ * - `org_upload_pending`: an org-owned plugin whose uploaded version (with an extension) waits for
+ *   the super admin in 待确认 (ruling P3-22; confirmed or rejected there), `id` = the item's;
+ * - `scope_sync_failed`: an open scope sync failure, `id` = `<itemId>/<orgId>`;
+ * - `platform_migration`: the latest migration run, failed items or stuck, `id` = the run's;
+ * - `ownership_transferred`: a deleted org's shared item now belongs to the platform, until a
+ *   super admin dismisses it (`POST admin/inbox/notices/:id/dismiss`).
+ */
+export type PlatformInboxItem = {
+    type: "catalog_request";
+    id: string;
+    createdAt: string;
+    request: CatalogRequestView;
+} | {
+    type: "permission_confirmation";
+    id: string;
+    createdAt: string;
+    item: CatalogItemView;
+} | {
+    type: "org_upload_pending";
+    id: string;
+    createdAt: string;
+    item: CatalogItemView;
+} | {
+    type: "scope_sync_failed";
+    id: string;
+    createdAt: string;
+    failure: ScopeSyncFailureView;
+} | {
+    type: "platform_migration";
+    id: string;
+    createdAt: string;
+    run: MigrationRunView;
+} | {
+    type: "ownership_transferred";
+    id: string;
+    createdAt: string;
+    notice: PlatformNoticeView;
+};
+/** An open platform notice (`platform_notices`, kind `ownership_transferred`). */
+export interface PlatformNoticeView {
+    id: string;
+    kind: "ownership_transferred";
+    createdAt: string;
+    detail: PlatformNoticeDetails["ownership_transferred"];
+}
+/**
+ * `GET /admin/inbox`: newest first, at most {@link PLATFORM_INBOX_MAX_ITEMS}; `truncated`: more;
+ * `total`: how many items wait in all (also `GET /admin/inbox/count`).
+ */
+export interface PlatformInboxView {
+    items: PlatformInboxItem[];
+    truncated: boolean;
+    total: number;
+}
+/**
+ * The super admin's inbox (plugin scope spec §5.1 rule 5, §13.5): what waits on the platform,
+ * gathered from the sources the admin pages read (the 待确认 tab's requests and permission
+ * confirmations), plus the scope sync's open failures and the platform components migration's
+ * latest run. Stateless, read live from PG.
+ */
+export declare class PlatformInboxService {
+    private readonly requests;
+    private readonly catalog;
+    private readonly kdb;
+    constructor(requests: Pick<CatalogRequestsService, "listDeployment" | "countPendingDeployment">, catalog: Pick<CatalogService, "list">, kdb: KernelDb);
+    list(): Promise<PlatformInboxView>;
+    /**
+     * How many items wait (the sidebar's count): the same sources, counted where they can be (the
+     * requests and the failures; the permission confirmations are the catalog's pending list).
+     */
+    count(): Promise<number>;
+    private countNotices;
+    /** The open platform notices, newest first, at most {@link PLATFORM_INBOX_MAX_ITEMS}. */
+    private notices;
+    /**
+     * A super admin dismisses a platform notice (for every super admin). Dismissing one already
+     * dismissed is fine; no notice with that id -> `inbox.notice_not_found`.
+     */
+    dismissNotice(accountId: string, id: string): Promise<void>;
+    /**
+     * The open failures still worth a look, joined to their item and org: of a live item and org,
+     * and the pair still differs in the failed direction (a person may have converged it meanwhile):
+     * an install failure while the org has no live install of the item; an uninstall or dependencies
+     * failure while it has one.
+     */
+    private failureRows;
+    private countScopeSyncFailures;
+    /** The open scope sync failures ({@link failureRows}), newest first. */
+    private scopeSyncFailures;
+    /**
+     * The latest migration run when it needs a look (see {@link MigrationRunView}); null when it
+     * finished without failed items, is still running, or there was none. An earlier run's failure
+     * is not shown: each run tries every unwritten item again.
+     */
+    private migrationRun;
+}