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

package/dist/catalog/plugin-import.js

@@ -8,11 +8,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { createHash, randomUUID } from "node:crypto";
-import { PLUGIN_MANIFEST_FILE, parseSkillMd, pluginDescription, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
+import { appearanceIssues, PLUGIN_MANIFEST_FILE, parseSkillMd, pluginDescription, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
+import { ClientBuilds } from "../client/client-builds.service.js";
+import { checkClientFiles } from "../client/client-files.js";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
 import { ExtensionAdmin } from "../extensions/admin-view.js";
@@ -112,14 +114,17 @@ const reviewStale = (review) => new ApiError("plugin.review_stale", `The review
 const mismatch = (what) => new ApiError("marketplace.package_mismatch", `The downloaded package does not match the marketplace entry: ${what}`);
 /**
  * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
- * `catalog.legacy_format`; a failing theme (themes spec §5) -> `theme.invalid` (details
- * `[{ theme, errors }]`) or `theme.unreadable` (details `[{ theme, issues }]`, the failing pairs);
- * anything else -> `catalog.invalid_manifest` (issues as details).
+ * `catalog.legacy_format`; undeclared client code -> `client.undeclared`; a failing theme (themes
+ * spec §5) -> `theme.invalid` (details `[{ theme, errors }]`) or `theme.unreadable` (details
+ * `[{ theme, issues }]`, the failing pairs); anything else -> `catalog.invalid_manifest` (issues as
+ * details).
  */
 export function catalogPackageError(e) {
     const legacy = e.code === "catalog.legacy_format" || e.code === "extension.legacy_format";
     if (legacy)
         return new ApiError("catalog.legacy_format", e.message, e.issues);
+    if (e.code === "client.undeclared")
+        return new ApiError("client.undeclared", e.message);
     if (e.code === "theme.invalid" || e.code === "theme.unreadable") {
         return themeApiError(e);
     }
@@ -160,6 +165,7 @@ let PluginImport = class PluginImport {
     txHost;
     platform;
     maintenance;
+    clientBuilds;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     files;
     /**
@@ -180,7 +186,9 @@ let PluginImport = class PluginImport {
     /** The platform rows of a new item's components, written after the confirm's commit. */
     platform, 
     /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
-    maintenance) {
+    maintenance, 
+    /** The client build of a dropped org upload's package is deleted with it. */
+    clientBuilds) {
         this.kdb = kdb;
         this.adminLock = adminLock;
         this.orgLock = orgLock;
@@ -197,6 +205,7 @@ let PluginImport = class PluginImport {
         this.txHost = txHost;
         this.platform = platform;
         this.maintenance = maintenance;
+        this.clientBuilds = clientBuilds;
         this.files = storage;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -341,6 +350,22 @@ let PluginImport = class PluginImport {
             ? await readingPackage(() => readExtensionPackage(bytes, { maxBytes, hostSdkVersion: SDK_VERSION }))
             : undefined;
         const content = this.checkContent(pkg, format);
+        // suggestedAppearance.theme against the themes the scan found (the manifest may not list them)
+        const appearance = appearanceIssues(m, pkg.themes.map((t) => t.id));
+        if (appearance.length > 0)
+            throw invalid(appearance);
+        // Client code (client extensions spec §9.1): the section re-checked and every file against it
+        // (keys, listed = present, sizes, sha384 recomputed, the CSS layer wrap); delivered from object
+        // storage, so refused without one. The store checks the bytes it writes again. A bootstrap
+        // plugin never carries it: a bootstrap run may have no object store (it may be a bootstrap
+        // plugin itself), and a required entry failing on that would stop the start.
+        if (ext?.section.client !== undefined) {
+            if (source.kind === "bootstrap") {
+                throw new ApiError("client.invalid", `Bootstrap plugin ${m.name} ships client code (extension.client), which a bootstrap plugin may not carry: its files are kept in object storage, which a bootstrap run may not have (the object store may be a bootstrap plugin itself); take ${m.name} out of bootstrap.json and import it into the catalog instead`);
+            }
+            checkClientFiles(ext.section.client, pkg.files);
+            this.files.assertAvailable();
+        }
         // A name live for another owner (an org's for the super admin; the platform's or another
         // org's for an org) -> 409 plugin.name_taken naming it (P3-14); the same owner adds a version
         await assertNameFree(this.db, m.name, owner?.orgId ?? null);
@@ -475,13 +500,16 @@ let PluginImport = class PluginImport {
                 .sort()
             : [];
         const mismatch = permissionsMismatch(opts.expect?.marketplace?.permissions, ext ? keys : undefined);
+        const manifest = normalizedManifest(pkg);
+        const replacements = manifest.suggestedAppearance?.replacements;
         const staged = {
             itemId,
             packageName,
             version,
             contentDigest: pkg.contentDigest,
             size: tgz.size,
-            manifest: normalizedManifest(pkg),
+            manifest,
+            ...(replacements !== undefined && { appearanceOrder: Object.keys(replacements) }),
             files: content.files.map(({ path, size, sha256 }) => ({ path, size, sha256 })),
             ...(mismatch !== null && { permissionsMismatch: mismatch }),
             sourceFormat: format,
@@ -785,6 +813,22 @@ let PluginImport = class PluginImport {
         // Checked again before this upload claims anything (ruling P3-51)
         if (owner !== undefined)
             await assertPackageFree(t, staged.packageName, owner.orgId);
+        // The item's name lock and its live row before the extension's install lock: the global lock
+        // order is the item, then the install lock (ruling P3-50; ExtensionAdminOps.install locks the
+        // source item row before the install lock, an org deletion its items before it). Taken after
+        // the install lock instead, a confirmation of an org upload racing a replacement upload
+        // deadlocks (40P01).
+        const m = manifest;
+        await this.itemLock.lock(m.name);
+        // The scope the audit records: the review's for a new item, the item's own for a new version
+        // of a live item (which keeps its scope)
+        const existing = await t
+            .selectFrom("catalog_items")
+            .select(["id", "scope", "awaiting_confirmation", "package_name"])
+            .where("name", "=", m.name)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
         let now;
         let previous;
         if (reviewed) {
@@ -817,8 +861,6 @@ let PluginImport = class PluginImport {
                 previous = await this.approve(actor, review, staged, now, stored, opts);
             }
         }
-        const m = manifest;
-        await this.itemLock.lock(m.name);
         // Under the name's lock: the first confirm of a name wins, a later one of another owner is
         // refused naming it, before anything of it is written (P3-14)
         await assertNameFree(t, m.name, owner?.orgId ?? null);
@@ -826,15 +868,6 @@ let PluginImport = class PluginImport {
             await assertNameNotReserved(t, m.name);
             await this.resolveDependencies(m, owner);
         }
-        // The scope the audit records: the review's for a new item, the item's own for a new version
-        // of a live item (which keeps its scope)
-        const existing = await t
-            .selectFrom("catalog_items")
-            .select(["id", "scope", "awaiting_confirmation", "package_name"])
-            .where("name", "=", m.name)
-            .where("deleted_at", "is", null)
-            .forUpdate()
-            .executeTakeFirst();
         const actual = existing === undefined
             ? scope
             : {
@@ -879,6 +912,7 @@ let PluginImport = class PluginImport {
             version: staged.version,
             contentDigest: staged.contentDigest,
             manifest: m,
+            appearanceOrder: staged.appearanceOrder ?? null,
             listing: {
                 publisher: m.publisher,
                 description: pluginDescription(m.description).en,
@@ -1307,8 +1341,27 @@ let PluginImport = class PluginImport {
                 .executeTakeFirst());
         if (used !== undefined)
             return;
-        // extension_blobs (a PG-stored package) goes with the row (ON DELETE CASCADE)
+        const build = await t
+            .selectFrom("extension_client_builds")
+            .select("object_prefix")
+            .where("package_sha256", "=", sha)
+            .executeTakeFirst();
+        // extension_blobs (a PG-stored package) and extension_client_builds go with the row (ON
+        // DELETE CASCADE)
         await t.deleteFrom("extension_packages").where("sha256", "=", sha).execute();
+        if (build !== undefined) {
+            afterCommit(async () => {
+                try {
+                    await this.clientBuilds.deleteFiles(sha, build.object_prefix);
+                }
+                catch (err) {
+                    this.log.warn("cannot delete an expired org upload's client build objects", {
+                        sha256: sha,
+                        err,
+                    });
+                }
+            });
+        }
         // The object only once the row is gone for good: a failure leaves an unreferenced object
         // (harmless; a later upload of the same bytes rewrites it), never a row without its bytes
         if (pkg.blob_store === "object") {
@@ -1588,6 +1641,7 @@ let PluginImport = class PluginImport {
             warnings,
             reviewHash: extensionReviewHash(set, warnings),
             sensitive: permissions.some((g) => g.sensitive) || warnings.length > 0,
+            ...(pkg.section.client !== undefined && { client: reviewClient(pkg) }),
         };
     }
     async readStored(sha256) {
@@ -1654,7 +1708,8 @@ PluginImport = __decorate([
     __param(13, Inject(KERNEL_LOGGER)),
     __param(14, Inject(TransactionHost)),
     __param(15, Inject(PlatformComponents)),
-    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(17, Inject(ClientBuilds))
 ], PluginImport);
 export { PluginImport };
 /**
@@ -1751,6 +1806,27 @@ export function pluginReviewHash(r, files) {
     ]);
     return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
 }
+/** The client code of a read extension package for its review (sizes from the package's files). */
+function reviewClient(pkg) {
+    const c = pkg.section.client;
+    const sizes = new Map(pkg.files.map((f) => [f.path, f.size]));
+    const files = [
+        ...(c.entry !== undefined ? [c.entry] : []),
+        ...(c.styles ?? []),
+        ...(c.assets ?? []),
+    ].map((path) => {
+        // checkClientFiles ran first: every listed file is in the package
+        const size = sizes.get(path.slice(2));
+        if (size === undefined)
+            throw new Error(`client file ${path} is not in the package`);
+        return { path, size };
+    });
+    return {
+        files,
+        totalBytes: files.reduce((n, f) => n + f.size, 0),
+        apiVersion: c.apiVersion,
+    };
+}
 /**
  * A version change that is a downgrade (the imported version below the installed one) whose
  * version has migrations not run on this deployment -> `extension.downgrade_unsupported` (the same

package/dist/catalog/plugin-package.d.ts

@@ -16,9 +16,11 @@ export { LEGACY_FORMAT_MESSAGE, packagePath };
  */
 /**
  * Codes of {@link PluginPackageError}: `theme.invalid` / `theme.unreadable` when the package's only
- * problems are in its themes (themes spec §5: a failing theme refuses the whole plugin).
+ * problems are in its themes (themes spec §5: a failing theme refuses the whole plugin);
+ * `client.undeclared` for an `extension.client` section whose manifest lacks
+ * `permissions.client: true` (client extensions spec §5.4: client code is always reviewed).
  */
-export type PluginPackageErrorCode = "catalog.invalid_manifest" | "catalog.legacy_format" | "theme.invalid" | "theme.unreadable";
+export type PluginPackageErrorCode = "catalog.invalid_manifest" | "catalog.legacy_format" | "theme.invalid" | "theme.unreadable" | "client.undeclared";
 /** The problems of one theme of a refused plugin (English; `unreadable:` lines for readability). */
 export interface PluginThemeProblem {
     /** The theme id (the file's base name). */

package/dist/catalog/plugin-package.js

@@ -12,9 +12,11 @@ export class PluginPackageError extends Error {
     constructor(code, issues, themes) {
         super(code === "catalog.legacy_format"
             ? (issues[0] ?? LEGACY_FORMAT_MESSAGE)
-            : code === "theme.invalid" || code === "theme.unreadable"
-                ? `Theme ${themes?.[0]?.theme ?? "?"} ${code === "theme.invalid" ? "is invalid" : "is not readable"}: ${issues[0] ?? "unknown problem"}`
-                : `Invalid plugin package: ${issues[0] ?? "unknown problem"}`);
+            : code === "client.undeclared"
+                ? (issues[0] ?? code)
+                : code === "theme.invalid" || code === "theme.unreadable"
+                    ? `Theme ${themes?.[0]?.theme ?? "?"} ${code === "theme.invalid" ? "is invalid" : "is not readable"}: ${issues[0] ?? "unknown problem"}`
+                    : `Invalid plugin package: ${issues[0] ?? "unknown problem"}`);
         this.name = "PluginPackageError";
         this.code = code;
         this.issues = issues;
@@ -78,6 +80,27 @@ export function iconProblem(path, data) {
     return /<svg[\s>/]/i.test(text) ? undefined : `${path} is not an SVG document`;
 }
 /** package.json parsed, or undefined when it is not valid (only used to name a legacy package). */
+/**
+ * Client code the extension manifest does not declare (an `extension.client` section without
+ * `permissions.client: true`), read from the raw plugin.json before it is parsed, so the refusal
+ * names it (`client.undeclared`) instead of being one parse problem among others.
+ */
+function clientUndeclared(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const ext = isObj(raw) ? raw.extension : undefined;
+    if (!isObj(ext) || ext.client === undefined)
+        return undefined;
+    const perms = isObj(ext.manifest) ? ext.manifest.permissions : undefined;
+    if (isObj(perms) && perms.client === true)
+        return undefined;
+    return `${PLUGIN_MANIFEST_FILE}: extension.client ships client code, but the extension manifest does not declare permissions.client: true; client code must be declared so it is reviewed (capybara-plugin pack writes both)`;
+}
 const parsedOrUndefined = (data) => {
     try {
         return parsePackageJsonFile({ data });
@@ -201,6 +224,9 @@ export function readPluginFiles(files, opts) {
         const text = decode(manifestBytes);
         if (text === undefined)
             return invalid([`${PLUGIN_MANIFEST_FILE} is not valid UTF-8 text`]);
+        const undeclared = clientUndeclared(text);
+        if (undeclared !== undefined)
+            throw new PluginPackageError("client.undeclared", [undeclared]);
         const parsed = parsePluginManifest(text);
         if ("errors" in parsed) {
             return invalid(parsed.errors.map((e) => `${PLUGIN_MANIFEST_FILE}: ${e}`));

package/dist/client/client-access.service.d.ts

@@ -0,0 +1,101 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import type { OrgRole } from "../orgs/roles.js";
+import { StorageService } from "../storage/storage.service.js";
+import type { ClientExtensionsResponse } from "./client.schemas.js";
+/** A client build the caller may fetch files of (the row the delivery route serves from). */
+export interface FetchableBuild {
+    plugin: string;
+    build: string;
+    /** Every manifest key of the build: the entry, the styles and the assets. */
+    keys: ReadonlySet<string>;
+    /** The ids of the build's `component` contributions (whatever their slot's role gate). */
+    components: ReadonlySet<string>;
+    /** Relative to `deployment/`: `platform/client/<plugin>/<sha256>/`. */
+    objectPrefix: string;
+}
+/** `/api/v1/client/<plugin>/<build>/<path inside dist/client/>` of a manifest key. */
+export declare const clientFileUrl: (plugin: string, build: string, key: string) => string;
+/** A served client file: its bytes and the headers that depend on it. */
+export interface ClientFile {
+    contentType: string;
+    data: Uint8Array;
+}
+/**
+ * The client file a delivery URL path names, as `{ plugin, build, key }`, or null. `path` is the
+ * raw request path after `/api/v1/client/`, never decoded: every segment must already be made of
+ * `[A-Za-z0-9._-]` and not be `.` or `..`, so an encoded separator (`%2F`, `%5C`), an encoded dot
+ * (`%2e`), a backslash, an empty segment (`//`, a trailing `/`) or a dot segment names nothing.
+ * The key is then `./dist/client/<segments>`: the exact manifest spelling, nothing joined or
+ * normalised.
+ */
+export declare function parseClientPath(path: string): {
+    plugin: string;
+    build: string;
+    key: string;
+} | null;
+/**
+ * Who may load which client code (client extensions spec §9.2, §9.3, §10.2), decided from PG on
+ * every request: no process state, nothing cached, so every replica answers the same and a change
+ * (an org switch, an upgrade, the kill switch) applies at once.
+ *
+ * Client code follows the server code that actually runs. A build is **served** when its package
+ * is what a live replica serves for an enabled install (`extension_replica_status.serving_sha256`,
+ * heartbeat within `STALE_RECONCILE_PERIODS` reconcile intervals: the row's own package when
+ * loaded, the older package still running beside a version pending approval or failed) and the
+ * approved permission snapshot covers its client keys (`permissions.client` and every
+ * `ui.component:<id>` of its manifest). So during an upgrade awaiting approval, or after the new
+ * version's migration / setup / import failed, the old build stays served and listed and the new
+ * one is not, until a replica serves it; with no live replica nothing is (fails closed). An org
+ * upload awaiting the super admin has no install, so nothing of it is served. The kill switch
+ * (`clientExtensions`) then stops all builds or those of the listed plugins.
+ */
+export declare class ClientAccess {
+    private readonly db;
+    private readonly config;
+    private readonly storage;
+    private readonly log;
+    constructor(db: KernelDb, config: Pick<KernelConfigService, "get">, storage: StorageService, log: Pick<KernelLogger, "warn">);
+    /**
+     * The client file a delivery request names (`path`: the raw path after `/api/v1/client/`, see
+     * {@link parseClientPath}) when the account may fetch it ({@link fetchable}) and the build lists
+     * it by that exact key; else 404 `client.not_found` (one answer for every reason, and never the
+     * requested path in the message). The bytes come from object storage under the build's prefix;
+     * the integrity a browser checks them against came from the `extension_client_builds` row.
+     */
+    file(accountId: string, superAdmin: boolean, path: string): Promise<ClientFile>;
+    /**
+     * The served client builds (see the class header) as a query to narrow: one row per (extension,
+     * served build); during a rollout two replicas may serve two builds of one extension.
+     */
+    private served;
+    /**
+     * One served build per extension, for the shell reads: the install's current package when a
+     * replica serves it, else the newest build a replica still serves (the old one while the new
+     * version waits for approval or failed).
+     */
+    private listed;
+    /**
+     * The build `build` of `plugin` when the account may fetch its files, else null; one query, not
+     * cached. It must be served (class header), not stopped by the kill switch, and the account a
+     * member (any role) of a live org where the extension is enabled, or a super admin when the
+     * build's manifest has a `platform.page` component (the admin console loads only those). A
+     * build of a client API version the kernel does not support is never fetchable, as it is never
+     * listed in a shell read.
+     */
+    fetchable(accountId: string, superAdmin: boolean, plugin: string, build: string): Promise<FetchableBuild | null>;
+    /**
+     * The org's shell read: every extension enabled in the org (`enabled.ts`) with a served client
+     * build ({@link listed}: one per extension), in name order, minus the stopped ones; `components`
+     * are those whose slot the role may use (`canUseSlot`: its `minRole`, never `platform.page`). An
+     * extension with no component left is still listed (its stylesheets and entry still load).
+     */
+    orgSet(orgId: string, role: OrgRole): Promise<ClientExtensionsResponse>;
+    /**
+     * The admin console's set (spec §9.6): the extensions with a served build (whatever their org
+     * enablement) with at least one `platform.page` component and an entry, only those components
+     * and no stylesheets (the admin console runs no org client code); with `plugin`, at most that one.
+     */
+    platformSet(plugin?: string): Promise<ClientExtensionsResponse>;
+}