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

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

@@ -1,15 +1,19 @@
-import { type AgentTemplate, type Connector, type ConnectorTemplateFile, type ConnectorTemplateSpec, type Logger, type PluginManifest } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { KernelDatabase, KernelDb, SourceFormat } from "../db/kernel-schema.js";
-import type { ExtensionHost } from "../extensions/host.js";
-import type { OrgExtensionConfigs } from "../extensions/org-config.js";
+import { type AgentTemplate, type ConnectorTemplateFile, type ConnectorTemplateSpec, type PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb, SourceFormat } from "../db/kernel-schema.js";
+import { OrgExtensionConfigs, type OrgExtensionInput, type OrgExtensionPutOptions } from "../extensions/org-config.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import type { OrgAction } from "../orgs/roles.js";
-import { type SkillConflict, type SkillsService } from "../skills/skills.service.js";
-import type { StorageService } from "../storage/storage.service.js";
-import type { ConnectorsService, CreateConnectorInput } from "../tools/connectors.service.js";
-import { type CatalogVersionFiles, type TemplateDeps } from "./org-catalog.service.js";
-import { type CatalogRequestsService } from "./requests.service.js";
-type Trx = Transaction<KernelDatabase>;
+import { type SkillConflict, SkillsService } from "../skills/skills.service.js";
+import { StorageService } from "../storage/storage.service.js";
+import type { CreateConnectorInput } from "../tools/connectors.service.js";
+import { ConnectorsService } from "../tools/connectors.service.js";
+import { type CatalogVersionFiles, type TemplateDeps } from "./catalog-content.js";
+import { CatalogRequestsService } from "./requests.service.js";
 /** What an org fills in for one connector template at install (C30). */
 export interface ConnectorInstallInput {
     name?: string;
@@ -82,19 +86,6 @@ export interface PluginInstallView {
      */
     deploymentPending: boolean;
 }
-export interface PluginInstallerDeps {
-    db: KernelDb;
-    storage: StorageService;
-    host: Pick<ExtensionHost, "manifests" | "list">;
-    findConnector: (plugin: string, kind: string) => Connector | undefined;
-    connectors: Pick<ConnectorsService, "create" | "removeIn" | "checkCreateInput" | "prepareTemplateUpdate" | "applyTemplateIn">;
-    skills: Pick<SkillsService, "createVersionFromFiles" | "softDeleteIn" | "revertVersionIn">;
-    orgConfigs: Pick<OrgExtensionConfigs, "put" | "disableIn" | "afterDisable" | "enabledDependents">;
-    requests: Pick<CatalogRequestsService, "resolveByInstall">;
-    /** `catalog.staleInstallMinutes`: an install `installing` for longer can be cleaned up by uninstalling it. */
-    staleInstallMinutes: () => number;
-    log?: Pick<Logger, "warn">;
-}
 /** A dependency resolved against the catalog. */
 export interface ResolvedDependency {
     name: string;
@@ -178,7 +169,7 @@ export interface UninstallCtx {
  * `catalog.dependency_disabled`; a cycle (`a` -> `b` -> `a`, by name) or nesting deeper than
  * {@link DEPENDENCY_DEPTH_LIMIT} -> `catalog.dependency_cycle`. Returns the direct dependencies.
  */
-export declare function resolveDependencies(db: KernelDb | Trx, manifest: PluginManifest): Promise<ResolvedDependency[]>;
+export declare function resolveDependencies(db: KernelSchemaDb, manifest: PluginManifest): Promise<ResolvedDependency[]>;
 /**
  * The input a template needs that the org did not give: a static credential (the org's for an
  * org-owned template; for a personal one the installer's own, stored as their personal credential,
@@ -218,10 +209,31 @@ export declare function under(e: unknown, at: string): unknown;
  * `private` are internal to the catalog, not an API).
  */
 export declare class PluginInstaller {
-    private readonly d;
-    constructor(d: PluginInstallerDeps);
-    /** The installer's dependencies (shared with `PluginUpgrader`). */
-    get deps(): PluginInstallerDeps;
+    private readonly kdb;
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    private readonly orgLock;
+    private readonly storage;
+    /** The loaded extensions and connectors of this replica (the extension registry). */
+    private readonly registry;
+    private readonly skills;
+    private readonly orgConfigs;
+    private readonly requests;
+    private readonly config;
+    /** Org connectors: installs create, upgrade and remove them. */
+    private readonly connectors;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, 
+    /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
+    orgLock: OrgLock, storage: StorageService, 
+    /** The loaded extensions and connectors of this replica (the extension registry). */
+    registry: ExtensionRegistry, skills: SkillsService, orgConfigs: OrgExtensionConfigs, requests: CatalogRequestsService, config: KernelConfigService, 
+    /** Org connectors: installs create, upgrade and remove them. */
+    connectors: ConnectorsService, log: KernelLogger, txHost: TransactionHost);
+    /** The kernel-schema handle of the current context (the transaction, else the pool). */
+    private get db();
+    /** `catalog.staleInstallMinutes`: an install `installing` for longer can be cleaned up by uninstalling it. */
+    staleInstallMinutes(): number;
     /**
      * The checks an install runs before it creates anything, without the org's input (for the org
      * catalog to run before a request is created): dependency resolution, the extensions deployed and
@@ -267,7 +279,7 @@ export declare class PluginInstaller {
      * version outside the dependency's range -> `catalog.dependency_unresolved` (org upgrades arrive in
      * phase A).
      */
-    liveDependency(db: KernelDb | Trx, orgId: string, dep: ResolvedDependency): Promise<string | undefined>;
+    liveDependency(db: KernelSchemaDb, orgId: string, dep: ResolvedDependency): Promise<string | undefined>;
     /**
      * The org's live (not failed) install of a dependency's item; `lock` takes it FOR SHARE (the
      * caller holds the org row lock).
@@ -279,9 +291,10 @@ export declare class PluginInstaller {
      * cannot leave the component pointing at a removed install. `created` false: the org's existing
      * install, if any (returns its id, undefined when there is none); it must be `installed`
      * (`installing` -> 409 `plugin.install_in_progress`, retry later) and in range. `created` true:
-     * `child`, the dependency install this install just created, must still exist.
+     * `child`, the dependency install this install just created, must still exist. A step of an
+     * install or upgrade: it commits on its own (`requires_new`), the undo on failure relies on it.
      */
-    recordDependency(orgId: string, dep: ResolvedDependency, record: (c: Component, t: Trx) => Promise<void>, child?: string): Promise<string | undefined>;
+    recordDependency(orgId: string, dep: ResolvedDependency, record: (c: Component) => Promise<void>, child?: string): Promise<string | undefined>;
     /**
      * Runs a plan: the install row, then the steps (see the class comment). Throws
      * {@link InstallFailure} once the row exists (after rolling back); errors before it propagate
@@ -294,6 +307,28 @@ export declare class PluginInstaller {
         approvedBy?: string;
         parent?: string;
     }): Promise<string>;
+    /**
+     * The install row (role and item policy re-checked under the lock; one live install per org and
+     * item). A step of the install: committed on its own.
+     */
+    /**
+     * Enables a plugin's extension for the org and records it as a component of the install, in one
+     * transaction (`put` joins it): "enabled before" is decided under the org row lock (already
+     * enabled: `put` writes nothing, the config is untouched, the component is recorded as not
+     * created), and the ledger row is written before the COMMIT, so no concurrent uninstall fits
+     * between enabling and recording. Used by the install and the upgrade.
+     */
+    enableExtension(orgId: string, name: string, input: OrgExtensionInput, actor: string, actorTokenId: string | undefined, opts: Pick<OrgExtensionPutOptions, "viaItem" | "approvedBy">, record: (c: Component) => Promise<void>): Promise<void>;
+    private createInstallRow;
+    /**
+     * An agent template step: created (or a new version of the org's live template of this plugin and
+     * name) and recorded in one transaction of its own, under the org row lock.
+     */
+    private installAgentTemplate;
+    /** The install `installed` and its `plugin.org_installed` audit, under the org row lock (its own transaction). */
+    private markInstalled;
+    /** The install `failed` with `{ step, code }` and its `plugin.org_install_failed` audit (its own transaction). */
+    private markFailed;
     /**
      * The extension to enable: the plugin's own, when it has one. Not loaded on this replica ->
      * `catalog.not_deployed`; not yet enabled in this org while its own catalog item is disabled ->
@@ -311,8 +346,14 @@ export declare class PluginInstaller {
      * an org admin re-enabled by hand or a skill version a user uploaded since.
      */
     private rollback;
+    /**
+     * Undoes one component of a failed install and deletes its component row, under the org row lock,
+     * in a transaction of its own (committed when it returns); returns the extensions it disabled
+     * (the caller notifies them).
+     */
+    private rollbackOne;
     /** Removes one component (one already gone is no error); returns whether anything changed. */
-    removeComponent(t: Trx, orgId: string, actor: string, c: Component, reason: string): Promise<boolean>;
+    removeComponent(orgId: string, actor: string, c: Component, reason: string): Promise<boolean>;
     /**
      * Uninstall (the plugin's component actions, see `requiredActions`, re-checked under the org row
      * lock, one transaction). Removes only components with created=true:
@@ -338,20 +379,22 @@ export declare class PluginInstaller {
     uninstall(orgId: string, actor: string, installId: string, opts?: {
         actorTokenId?: string;
     }): Promise<UninstallReport>;
+    /** The uninstall's one transaction; the extensions it disabled are notified once it commits. */
+    private writeUninstall;
     /**
      * The oldest other live install (not in `removing`) that has component `kind` / `ref`, or
      * undefined.
      */
-    heir(t: Trx, orgId: string, removing: Set<string>, kind: ComponentKind, ref: string): Promise<string | undefined>;
+    heir(orgId: string, removing: Set<string>, kind: ComponentKind, ref: string): Promise<string | undefined>;
     /** Passes ownership of a component to `heir` (its component row becomes created=true). */
-    handOver(t: Trx, heir: string, kind: ComponentKind, ref: string): Promise<void>;
+    handOver(heir: string, kind: ComponentKind, ref: string): Promise<void>;
     /**
      * Uninstalls one install in the caller's transaction (see {@link uninstall}); dependency installs
      * it created recurse. Its own components' outcomes go into `ctx.report` (and its audit); the
      * outcome of the install itself is returned for the caller to report: `missing`, `kept` (another
      * install outside this uninstall depends on it) or `removed`.
      */
-    uninstallIn(t: Trx, orgId: string, actor: string, installId: string, ctx: UninstallCtx): Promise<"missing" | "kept" | "removed">;
+    uninstallIn(orgId: string, actor: string, installId: string, ctx: UninstallCtx): Promise<"missing" | "kept" | "removed">;
     /**
      * The uninstall rules for one component an install created (a skill, connector or extension;
      * dependency installs recurse through {@link uninstallIn}), in the caller's transaction: kept
@@ -362,7 +405,7 @@ export declare class PluginInstaller {
      * (`used_by_plugins`); otherwise removed (`removed`, or `gone` when it no longer existed). Used
      * by uninstall and by an upgrade's removals.
      */
-    decideRemovalIn(t: Trx, orgId: string, actor: string, c: Component, removing: Set<string>, agentRefs: {
+    decideRemovalIn(orgId: string, actor: string, c: Component, removing: Set<string>, agentRefs: {
         connectors: Set<string>;
         skills: Set<string>;
         templates: Set<string>;
@@ -380,7 +423,7 @@ export declare class PluginInstaller {
      * extension among them needs `afterDisable` once committed). Used when an upgrade fails and when
      * an interrupted one is cleaned up.
      */
-    undoUpgradeIn(t: Trx, orgId: string, actor: string, installId: string, steps: readonly UpgradeStep[], reason: string): Promise<{
+    undoUpgradeIn(orgId: string, actor: string, installId: string, steps: readonly UpgradeStep[], reason: string): Promise<{
         kind: ComponentKind;
         ref: string;
     }[]>;
@@ -390,7 +433,7 @@ export declare class PluginInstaller {
      * The connectors, org skills and agent templates (`subagents.templates`) referenced by the
      * current definitions of the org's live agents.
      */
-    agentRefs(t: Trx, orgId: string): Promise<{
+    agentRefs(orgId: string): Promise<{
         connectors: Set<string>;
         skills: Set<string>;
         templates: Set<string>;
@@ -415,7 +458,7 @@ export interface SkillPlan {
  * The skill conflicts of a plan, depth first in install order (dependencies before the plugin).
  * Exported for the upgrade preview.
  */
-export declare function planSkillConflicts(db: KernelDb | Trx, orgId: string, plan: SkillPlan): Promise<SkillConflict[]>;
+export declare function planSkillConflicts(db: KernelSchemaDb, orgId: string, plan: SkillPlan): Promise<SkillConflict[]>;
 /**
  * One step a running upgrade took, journaled in `plugin_installs.upgrade.done` (migration 0049) so
  * a failed or interrupted upgrade can be undone: `created` a component the upgrade created (its
@@ -444,4 +487,3 @@ export type UpgradeStep = {
 export declare function journalEntries(upgrade: unknown): UpgradeStep[];
 /** The org actions a plan needs: the union over the plugins it installs (spec §10). */
 export declare function planActions(plan: InstallPlan): OrgAction[];
-export {};