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

package/dist/catalog/appearance.service.js

@@ -0,0 +1,306 @@
+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 { parseSlotRef, UI_ARRANGEABLE_SLOTS, uiSlot, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable, Module } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { IdentityModule } from "../identity/identity.module.js";
+import { readUiArrangement, readUiTheme, SettingsService } from "../identity/settings.js";
+import { SuperAdminLock, SuperAdminLockModule } from "../identity/super-admin.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OrgLock, OrgLockModule } from "../orgs/org-lock.js";
+import { OrgsModule } from "../orgs/orgs.module.js";
+import { OrgSettingsService, readOrgSettings } from "../orgs/settings.service.js";
+import { assertPlatformDefaultEligible, eligiblePlatformDefault, themeNotAvailable, themeOnIn, } from "../themes/theme-state.js";
+import { ORG_ARRANGEABLE } from "../ui/arrangement.js";
+import { inAuthorOrder } from "./catalog-items.js";
+/** The suggestion of a plugin's catalog version, or null (none, or not an object). */
+export function suggestedAppearanceOf(manifest) {
+    const sa = manifest?.suggestedAppearance;
+    return sa !== null && typeof sa === "object" ? sa : null;
+}
+const itemNotFound = () => new ApiError("catalog.item_not_found", "No such plugin, or it suggests no appearance");
+const extensionNotFound = () => new ApiError("extension.not_found", "No such extension on in this organization, or its plugin suggests no appearance");
+const useOf = (e) => e !== undefined && "use" in e ? e.use : null;
+/**
+ * "Apply this plugin's appearance" (client extensions spec §6.5): one step that sets the plugin's
+ * suggested theme as the level's default theme and each suggested replacement as the level's `use`
+ * of its single slot. The writes go through the settings writers (`SettingsService.update` for the
+ * platform, `OrgSettingsService.update` for an org), so their validation, theme checks, lock order
+ * (the level's lock, then catalog item, theme row, `uiTheme` row) and audit apply, both settings in
+ * one call and one transaction: a theme that cannot be set (`theme.not_available`) refuses the
+ * whole call; a replacement that cannot be used where it is set is skipped, never refused (the
+ * arrangement keeps unknown keys anyway). A dry run computes the same answer and writes nothing.
+ */
+let AppearanceService = class AppearanceService {
+    db;
+    txHost;
+    settings;
+    orgSettings;
+    adminLock;
+    orgLock;
+    host;
+    constructor(db, txHost, settings, orgSettings, adminLock, orgLock, host) {
+        this.db = db;
+        this.txHost = txHost;
+        this.settings = settings;
+        this.orgSettings = orgSettings;
+        this.adminLock = adminLock;
+        this.orgLock = orgLock;
+        this.host = host;
+    }
+    /**
+     * The suggestions of the live plugins named `names`, from the version their components come from
+     * (`platform_synced_version`, else the latest); a plugin without one maps to null.
+     */
+    async suggestions(names) {
+        const out = new Map(names.map((n) => [n, null]));
+        if (names.length === 0)
+            return out;
+        const rows = await this.db
+            .selectFrom("catalog_items as i")
+            .innerJoin("catalog_item_versions as v", (j) => j
+            .onRef("v.item_id", "=", "i.id")
+            .on((eb) => eb("v.version", "=", eb.fn.coalesce("i.platform_synced_version", "i.latest_version"))))
+            .select(["i.name", "v.manifest", "v.appearance_order"])
+            .where("i.name", "in", [...names])
+            .where("i.deleted_at", "is", null)
+            .execute();
+        for (const r of rows) {
+            out.set(r.name, suggestedAppearanceOf(inAuthorOrder(r.manifest, r.appearance_order)));
+        }
+        return out;
+    }
+    /** The live catalog item `itemId` with its suggestion; else `catalog.item_not_found`. */
+    async platformItem(itemId) {
+        if (!/^[0-9a-f-]{36}$/i.test(itemId))
+            throw itemNotFound();
+        const row = await this.db
+            .selectFrom("catalog_items")
+            .select(["id", "name"])
+            .where("id", "=", itemId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        const suggestion = row && (await this.suggestions([row.name])).get(row.name);
+        if (!row || !suggestion)
+            throw itemNotFound();
+        return { id: row.id, name: row.name, suggestion };
+    }
+    /**
+     * The live plugin of extension `extension`, which must be on in the org, with its suggestion;
+     * else `extension.not_found`.
+     */
+    async orgItem(orgId, extension) {
+        if (!(await this.host.enabledPlugins(orgId)).has(extension))
+            throw extensionNotFound();
+        const row = await this.db
+            .selectFrom("catalog_items")
+            .select(["id", "name"])
+            .where("name", "=", extension)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        const suggestion = row && (await this.suggestions([row.name])).get(row.name);
+        if (!row || !suggestion)
+            throw extensionNotFound();
+        return { id: row.id, name: row.name, suggestion };
+    }
+    /**
+     * Applies (or, with `dryRun`, previews) the suggestion of `item` at `level`: for the platform,
+     * `item` is the catalog item id (`POST /api/v1/admin/catalog/items/:id/appearance`, super
+     * admin); for an org, the extension name (`POST /api/v1/orgs/:orgId/extensions/:extension/
+     * appearance`, `org.update`). The writers re-check the actor under their lock.
+     */
+    async apply(level, item, actor, dryRun) {
+        if (dryRun) {
+            const found = "orgId" in level ? await this.orgItem(level.orgId, item) : await this.platformItem(item);
+            const plan = await this.plan(level, found);
+            if (plan.theme !== undefined)
+                await this.assertThemeSettable(level, plan.theme);
+            return plan.result;
+        }
+        return "orgId" in level
+            ? this.applyOrg(level.orgId, item, actor)
+            : this.applyPlatform(item, actor);
+    }
+    /** Refuses (`theme.not_available`) a theme the level's writer would refuse; reads only. */
+    async assertThemeSettable(level, themeId) {
+        if ("orgId" in level) {
+            if (!(await themeOnIn(this.db.db, level.orgId, themeId))) {
+                throw themeNotAvailable(themeId, "in this organization");
+            }
+        }
+        else {
+            await assertPlatformDefaultEligible(this.db.db, themeId);
+        }
+    }
+    async applyPlatform(itemId, actor) {
+        // The writer's own lock first, so what the plan reads (the stored theme and arrangement) is
+        // what the write replaces; the writer takes it again (re-entrant) and then the theme rows
+        await this.adminLock.lockAndAuthorize(actor.accountId);
+        const found = await this.platformItem(itemId);
+        const plan = await this.plan({ platform: true }, found);
+        if (plan.theme === undefined && Object.keys(plan.arrangement).length === 0)
+            return plan.result;
+        await this.settings.update({
+            ...(plan.theme !== undefined && { uiTheme: { id: plan.theme } }),
+            ...(Object.keys(plan.arrangement).length > 0 && { uiArrangement: plan.arrangement }),
+        }, actor.accountId, actor.tokenId, { ...actor.auditDetail, appearance: { itemId: found.id, plugin: found.name } });
+        return plan.result;
+    }
+    async applyOrg(orgId, extension, actor) {
+        // The org lock first (as the writer takes it): `personal` and the stored arrangement are read
+        // under it, so the write keeps the lock setting it read
+        await this.orgLock.lockAndAuthorize(orgId, actor.accountId, "org.update");
+        const found = await this.orgItem(orgId, extension);
+        const plan = await this.plan({ orgId }, found);
+        if (plan.theme === undefined && Object.keys(plan.arrangement).length === 0)
+            return plan.result;
+        const stored = await readOrgSettings(this.db.db, orgId);
+        await this.orgSettings.update(orgId, {
+            ...(plan.theme !== undefined && {
+                theme: { id: plan.theme, personal: stored.theme?.personal ?? "allowed" },
+            }),
+            ...(Object.keys(plan.arrangement).length > 0 && { uiArrangement: plan.arrangement }),
+        }, actor.accountId, actor.tokenId, { ...actor.auditDetail, appearance: { itemId: found.id, plugin: found.name } });
+        return plan.result;
+    }
+    /**
+     * What applying `found` at `level` changes, from the stored settings (no writes): the level's
+     * own, and at org level the platform's it follows where it stores nothing.
+     */
+    async plan(level, found) {
+        const { suggestion } = found;
+        const [platformTheme, platformArrangement] = await Promise.all([
+            readUiTheme(this.db.db).then((t) => t.id),
+            readUiArrangement(this.db.db),
+        ]);
+        const org = "orgId" in level ? await readOrgSettings(this.db.db, level.orgId) : null;
+        // the theme in effect: an org without its own theme (id null) follows the platform default,
+        // which renders only while it is eligible (else the org sees the built-in, as ThemesService
+        // resolves it)
+        const orgTheme = org === null ? undefined : (org.theme?.id ?? null);
+        const themeFollows = orgTheme === null;
+        const followed = themeFollows && platformTheme !== null
+            ? (await eligiblePlatformDefault(this.db.db, platformTheme)) !== null
+                ? platformTheme
+                : null
+            : platformTheme;
+        const themeInEffect = orgTheme ?? followed;
+        /** The `use` in effect for a single slot, and whether an org follows the platform's. */
+        const inEffect = (slot) => {
+            if (org === null)
+                return { use: useOf(platformArrangement[slot]) };
+            const own = org.uiArrangement?.[slot];
+            return own !== undefined
+                ? { use: useOf(own), follows: false }
+                : { use: useOf(platformArrangement[slot]), follows: true };
+        };
+        const follows = (f) => (f === undefined ? {} : { followsPlatform: f });
+        const result = { theme: null, replacements: [], skipped: [] };
+        const plan = { result, arrangement: {} };
+        if (suggestion.theme !== undefined) {
+            const row = await this.db
+                .selectFrom("platform_themes")
+                .select("id")
+                .where("catalog_item_id", "=", found.id)
+                .where("name", "=", suggestion.theme)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+            if (!row) {
+                throw themeNotAvailable(suggestion.theme, "orgId" in level ? "in this organization" : "as the platform default");
+            }
+            if (row.id !== themeInEffect) {
+                plan.theme = row.id;
+                result.theme = {
+                    from: themeInEffect,
+                    to: row.id,
+                    ...follows(org === null ? undefined : themeFollows),
+                };
+            }
+        }
+        // in plugin.json order (`suggestions` restores it from `appearance_order`)
+        const entries = Object.entries(suggestion.replacements ?? {});
+        if (entries.length === 0)
+            return plan;
+        const enabled = "orgId" in level ? await this.host.enabledPlugins(level.orgId) : null;
+        const loaded = this.host
+            .uiContributions()
+            .filter((c) => c.plugin === found.name &&
+            c.contribution.aliasOf === undefined &&
+            (enabled === null || enabled.has(c.plugin)));
+        const arrangeable = "orgId" in level ? ORG_ARRANGEABLE : UI_ARRANGEABLE_SLOTS;
+        const planned = new Set();
+        for (const [ref, id] of entries) {
+            const parsed = parseSlotRef(ref);
+            const known = parsed === null ? undefined : uiSlot(parsed.id);
+            if (parsed === null || known === undefined || parsed.version > known.version) {
+                result.skipped.push({ what: ref, reason: "unknown-slot" });
+                continue;
+            }
+            const slot = known.id;
+            // a second ref to one slot (`shell.brand` and `shell.brand@1`; the SDK refuses it at parse)
+            if (known.cardinality !== "single" || !arrangeable.includes(slot) || planned.has(slot)) {
+                result.skipped.push({ what: ref, reason: "not-eligible" });
+                continue;
+            }
+            const c = loaded.find((l) => l.slot.id === slot && l.contribution.id === id);
+            if (c === undefined) {
+                result.skipped.push({ what: ref, reason: "not-available" });
+                continue;
+            }
+            if (c.contribution.kind !== "component") {
+                result.skipped.push({ what: ref, reason: "not-eligible" });
+                continue;
+            }
+            planned.add(slot);
+            const key = `${found.name}/${id}`;
+            const now = inEffect(slot);
+            if (now.use === key)
+                continue;
+            plan.arrangement[slot] = { use: key };
+            result.replacements.push({ slot, from: now.use, to: key, ...follows(now.follows) });
+        }
+        return plan;
+    }
+};
+__decorate([
+    Transactional()
+], AppearanceService.prototype, "applyPlatform", null);
+__decorate([
+    Transactional()
+], AppearanceService.prototype, "applyOrg", null);
+AppearanceService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SettingsService)),
+    __param(3, Inject(OrgSettingsService)),
+    __param(4, Inject(SuperAdminLock)),
+    __param(5, Inject(OrgLock)),
+    __param(6, Inject(ExtensionHost))
+], AppearanceService);
+export { AppearanceService };
+/**
+ * The suggested appearance action: its own module, since it writes through the org settings
+ * writer (`OrgsModule`, which imports `CatalogModule`) and the deployment settings writer.
+ */
+let AppearanceModule = class AppearanceModule {
+};
+AppearanceModule = __decorate([
+    Module({
+        imports: [IdentityModule, OrgsModule, SuperAdminLockModule, OrgLockModule, ExtensionsModule],
+        providers: [AppearanceService],
+        exports: [AppearanceService],
+    })
+], AppearanceModule);
+export { AppearanceModule };

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

@@ -72,6 +72,14 @@ export interface OrgCatalogTemplate {
     editableEndpoint: string[];
     auth: Record<string, unknown>;
     ownership: "org" | "personal" | null;
+    /**
+     * The template's setup guide in the item's latest version (`GET …/catalog/:itemId/guides/
+     * :guideId`), null without one (spec 2026-11-09-setup-guides-v2-design.md §9.3).
+     */
+    guide: {
+        itemId: string;
+        guideId: string;
+    } | null;
 }
 /** `GET /orgs/:orgId/catalog/:itemId`: the item and what the install wizard needs (latest version). */
 export interface OrgCatalogDetail {
@@ -105,7 +113,7 @@ export interface OrgCatalogDetail {
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export declare function orgTemplateView(id: string, file: ConnectorTemplateFile): OrgCatalogTemplate;
+export declare function orgTemplateView(id: string, file: ConnectorTemplateFile, guide?: OrgCatalogTemplate["guide"]): OrgCatalogTemplate;
 /** An item's icon (the latest version's plugin icon). */
 export interface CatalogIcon {
     data: Uint8Array;

package/dist/catalog/catalog-content.js

@@ -16,7 +16,7 @@ import { satisfiesRange } from "./versions.js";
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export function orgTemplateView(id, file) {
+export function orgTemplateView(id, file, guide = null) {
     const t = file.template;
     return {
         id,
@@ -29,6 +29,7 @@ export function orgTemplateView(id, file) {
         auth: t.auth,
         ownership: t.ownership ??
             (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
+        guide,
     };
 }
 const iconNotFound = () => new ApiError("catalog.icon_not_found", "This catalog item has no icon");

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

@@ -1,4 +1,4 @@
-import type { PluginManifest } from "@capybara-hq/plugin-sdk";
+import { type PluginManifest } from "@capybara-hq/plugin-sdk";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 type Db = Pick<KernelSchemaDb, "selectFrom" | "insertInto" | "deleteFrom">;
 /** A stored file as a version row lists it. */
@@ -9,7 +9,8 @@ interface FileMeta {
 }
 /**
  * The display file paths of a plugin (package paths): the plugin icon, the connector templates'
- * icons (given by the caller, which parsed the templates) and the setup guide files.
+ * icons (given by the caller, which parsed the templates) and the setup guide documents (both
+ * languages; the caller keeps the ones the package has).
  */
 export declare function displayFilePaths(m: PluginManifest, templateIcons?: string[]): Set<string>;
 /**

package/dist/catalog/catalog-files.js

@@ -1,16 +1,18 @@
 // Catalog display files in PG (`catalog_files`, migration 0100): a plugin's icon, its connector
-// templates' icons and its setup guide files. They are small (64 KiB each at most, by the plugin
+// templates' icons and its setup guide documents. They are small (64 KiB each at most, by the plugin
 // format) and must be readable without object storage: a bootstrap plugin is imported before any
 // object-store extension runs, and the object-store plugin's own icon can never wait for itself.
 // Skills, connector templates and agent templates stay in object storage under the version's
 // `object_prefix` (they are copied into platform components there).
 import { createHash } from "node:crypto";
+import { setupGuideDocPath } from "@capybara-hq/plugin-sdk";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
 import { packagePath } from "../packages/tgz.js";
 /**
  * The display file paths of a plugin (package paths): the plugin icon, the connector templates'
- * icons (given by the caller, which parsed the templates) and the setup guide files.
+ * icons (given by the caller, which parsed the templates) and the setup guide documents (both
+ * languages; the caller keeps the ones the package has).
  */
 export function displayFilePaths(m, templateIcons = []) {
     const out = new Set();
@@ -18,9 +20,10 @@ export function displayFilePaths(m, templateIcons = []) {
         out.add(packagePath(m.icon));
     for (const icon of templateIcons)
         out.add(packagePath(icon));
-    for (const g of m.setupGuides ?? [])
-        for (const f of g.files ?? [])
-            out.add(packagePath(f.path));
+    for (const g of m.setupGuides ?? []) {
+        out.add(setupGuideDocPath(g.id, "en"));
+        out.add(setupGuideDocPath(g.id, "zh"));
+    }
     return out;
 }
 /**

package/dist/catalog/catalog-import.module.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { ClientModule } from "../client/client.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { SuperAdminLockModule } from "../identity/super-admin.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
@@ -34,6 +35,8 @@ CatalogImportModule = __decorate([
             // an org upload re-checks the owner org's admin (`PluginImport`, ruling P3-7)
             OrgLockModule,
             StorageModule,
+            // the client build prefix goes with an expired org upload's package (`PluginImport`)
+            ClientModule,
             // a failed post-import platform sync enqueues the migration job (`PluginImport.syncPlatform`)
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],

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

@@ -37,6 +37,12 @@ export interface CatalogListing {
     description: string;
     displayName: LocalizedName | null;
 }
+/**
+ * A stored manifest with `suggestedAppearance.replacements` back in plugin.json order: `order` is
+ * the version's `appearance_order` (the jsonb column does not keep key order); keys it does not
+ * name follow in stored order. Anything else is returned as is.
+ */
+export declare function inAuthorOrder(manifest: unknown, order: readonly string[] | null): unknown;
 /** Input of {@link writeCatalogVersion}. */
 export interface CatalogVersionWrite {
     /**
@@ -60,6 +66,11 @@ export interface CatalogVersionWrite {
     contentDigest: string;
     /** The normalized plugin.json. */
     manifest: PluginManifest;
+    /**
+     * The keys of `manifest.suggestedAppearance.replacements` in plugin.json order (the manifest may
+     * have passed through jsonb, which does not keep key order); null without replacements.
+     */
+    appearanceOrder: string[] | null;
     listing: CatalogListing;
     /** The id of the item to create when there is none yet (the one the storage prefix used). */
     newItemId: string;

package/dist/catalog/catalog-items.js

@@ -69,6 +69,26 @@ export function permissionsMismatch(declared, actual) {
     const extra = [...want].filter((k) => !have.has(k)).sort();
     return missing.length > 0 || extra.length > 0 ? { missing, extra } : null;
 }
+/**
+ * A stored manifest with `suggestedAppearance.replacements` back in plugin.json order: `order` is
+ * the version's `appearance_order` (the jsonb column does not keep key order); keys it does not
+ * name follow in stored order. Anything else is returned as is.
+ */
+export function inAuthorOrder(manifest, order) {
+    const m = manifest;
+    const r = m?.suggestedAppearance?.replacements;
+    if (order === null || r === null || typeof r !== "object" || Array.isArray(r))
+        return manifest;
+    const map = r;
+    const keys = new Set([...order.filter((k) => Object.hasOwn(map, k)), ...Object.keys(map)]);
+    return {
+        ...m,
+        suggestedAppearance: {
+            ...m?.suggestedAppearance,
+            replacements: Object.fromEntries([...keys].map((k) => [k, map[k]])),
+        },
+    };
+}
 /**
  * The live item of a name, with the source identity of its latest version
  * ({@link sourceIdentity}; null when there is none).
@@ -274,6 +294,7 @@ export async function writeCatalogVersion(db, w) {
         item_id: id,
         version,
         manifest: JSON.stringify(w.manifest),
+        appearance_order: w.appearanceOrder,
         source: w.source.source,
         source_ref: w.source.ref,
         integrity: w.source.integrity ?? null,

package/dist/catalog/catalog-scope.service.d.ts

@@ -166,6 +166,13 @@ export declare class CatalogScopeService {
     private confirmLocked;
     /** The item is live and its first version confirmed (no longer awaiting). */
     private confirmed;
+    /**
+     * The error a failed confirmation step answers with: 409 `catalog.item_removed` when the item is
+     * gone or soft-deleted by now, whichever step failed (the removal's cleanup job may take the
+     * extension out under the confirmation, so a step answers `extension.not_found`), the original
+     * error logged; else (or when the item cannot be read) the original error.
+     */
+    private removalOr;
     /** Clears the pending state of a version an earlier confirmation applied already. */
     private clearPending;
     /**

package/dist/catalog/catalog-scope.service.js

@@ -335,26 +335,23 @@ let CatalogScopeService = class CatalogScopeService {
             // A new version: applied (unless an earlier confirmation applied it and stopped before the
             // approval), then its permissions approved; an approval that fails puts the pending state
             // back, so the version shows in 待确认 again (ruling P3-37)
-            if (item.platform_synced_version !== version) {
-                try {
+            try {
+                if (item.platform_synced_version !== version) {
                     await this.updater.updateToPendingLocked(actor, itemId, version, opts);
                 }
+                else {
+                    await this.clearPending(itemId, version);
+                }
+                try {
+                    await this.approvePackage(actor, name, sha, reviewHash, opts);
+                }
                 catch (e) {
-                    if (e instanceof ApiError && e.code === "catalog.item_not_found") {
-                        throw itemRemovedError(name);
-                    }
+                    await this.restorePending(itemId, pending);
                     throw e;
                 }
             }
-            else {
-                await this.clearPending(itemId, version);
-            }
-            try {
-                await this.approvePackage(actor, name, sha, reviewHash, opts);
-            }
             catch (e) {
-                await this.restorePending(itemId, pending);
-                throw e;
+                throw await this.removalOr(e, itemId, name);
             }
             return null;
         }
@@ -362,7 +359,10 @@ let CatalogScopeService = class CatalogScopeService {
         let installedHere = false;
         try {
             if (install?.sha256 !== sha) {
-                await this.ops.install(name, sha, actor, opts.actorTokenId, { catalogItemId: itemId });
+                await this.ops.install(name, sha, actor, opts.actorTokenId, {
+                    catalogItemId: itemId,
+                    liveItem: true,
+                });
                 installedHere = install === undefined;
             }
             await this.stillPending(itemId, name, version);
@@ -377,7 +377,7 @@ let CatalogScopeService = class CatalogScopeService {
             if (installedHere && !(await this.confirmed(itemId))) {
                 await this.takeOut(itemId, name, actor, opts);
             }
-            throw e;
+            throw await this.removalOr(e, itemId, name);
         }
         return version;
     }
@@ -390,6 +390,46 @@ let CatalogScopeService = class CatalogScopeService {
             .executeTakeFirst();
         return row !== undefined && row.deleted_at === null && !row.awaiting_confirmation;
     }
+    /**
+     * The error a failed confirmation step answers with: 409 `catalog.item_removed` when the item is
+     * gone or soft-deleted by now, whichever step failed (the removal's cleanup job may take the
+     * extension out under the confirmation, so a step answers `extension.not_found`), the original
+     * error logged; else (or when the item cannot be read) the original error.
+     */
+    async removalOr(e, itemId, name) {
+        if (e instanceof ApiError && e.code === "catalog.item_removed")
+            return e;
+        let removed;
+        try {
+            const row = await this.db
+                .selectFrom("catalog_items")
+                .select("deleted_at")
+                .where("id", "=", itemId)
+                .executeTakeFirst();
+            removed = row === undefined || row.deleted_at !== null;
+        }
+        catch (err) {
+            this.log.warn("cannot read the item of a failed confirmation", { itemId, err });
+            return e;
+        }
+        if (!removed)
+            return e;
+        if (e instanceof ApiError) {
+            this.log.info("a confirmation step failed after its item was removed", {
+                itemId,
+                name,
+                code: e.code,
+            });
+        }
+        else {
+            this.log.warn("a confirmation step failed after its item was removed", {
+                itemId,
+                name,
+                err: e,
+            });
+        }
+        return itemRemovedError(name);
+    }
     /** Clears the pending state of a version an earlier confirmation applied already. */
     async clearPending(itemId, version) {
         await this.db

package/dist/catalog/catalog.service.js

@@ -22,7 +22,7 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { sameRepository } from "../packages/provenance.js";
 import { assertNotPlatformDefault } from "../themes/theme-usage.js";
-import { countInstalls, itemConfirmations, itemScopeFacts, itemView, marketplaceLatest, versionUsable, } from "./catalog-items.js";
+import { countInstalls, inAuthorOrder, itemConfirmations, itemScopeFacts, itemView, marketplaceLatest, versionUsable, } from "./catalog-items.js";
 import { expandGitUrl, GitSourceError, gitErrorDetails, normalGitPath, readGitTreeAndOids, resolveGitCommit, } from "./git-source.js";
 import { fetchMarketplaceArchive, marketplaceNetPolicy, marketplaceUrlProblem, } from "./marketplace-fetch.js";
 import { assertEntryNotDeprecated, entryCompatible, entrySourceHost, HOST_VERSIONS, hostAllowed, loadMarketplaceEntry, MarketplacesService, pluginNameFrom, } from "./marketplaces.service.js";
@@ -448,7 +448,7 @@ let CatalogService = class CatalogService {
                 integrity: v.integrity,
                 contentDigest: v.content_digest,
                 sourceDetail: v.source_detail ?? null,
-                manifest: v.manifest,
+                manifest: inAuthorOrder(v.manifest, v.appearance_order),
                 files: v.files,
                 size: Number(v.size),
                 extensionSha256: v.extension_sha256,
@@ -487,6 +487,14 @@ let CatalogService = class CatalogService {
     }
     async writeRemove(actor, itemId, opts) {
         await this.adminLock.lockAndAuthorize(actor);
+        // The item row before the install lock the check below takes (the global lock order: the
+        // item, then the install lock, ruling P3-50; also the item before its theme rows in removeIn)
+        await this.db
+            .selectFrom("catalog_items")
+            .select("id")
+            .where("id", "=", itemId)
+            .forUpdate()
+            .execute();
         await this.assertExtensionDisabled(this.db, itemId, true);
         if ((await this.removeIn(actor, itemId, opts)) === null)
             throw notFound();

package/dist/catalog/cli.js

@@ -2,6 +2,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { OBJECT_STORE_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { ClientBuilds } from "../client/client-builds.service.js";
 import { ApiError } from "../errors.js";
 import { planApprovals, snapshotCovers } from "../extensions/approvals.js";
 import { openExtensionCli } from "../extensions/cli.js";
@@ -178,6 +179,8 @@ export async function openCatalogCli(config, log, opts = {}) {
         // inspection (the registry), marketplace imports are not offered by the CLI.
         const imports = cli.app.get(PluginImport);
         imports.useCliStorage(storage);
+        // and so do the client files of a package with client code (stored with the package)
+        cli.app.get(ClientBuilds).useCliStorage(storage);
         const catalog = cli.app.get(CatalogService);
         const db = cli.app.get(KernelDb);
         const redis = cli.app.get(REDIS);