@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,222 @@
+import type { AgentTemplate, ConnectorTemplateFile, PluginManifest } from "@capybara-hq/plugin-sdk";
+import type { SourceFormat } from "../db/kernel-schema.js";
+import type { OrgAction } from "../orgs/roles.js";
+import type { CreateConnectorInput, TemplateUpdateInput } from "../tools/connectors.service.js";
+import type { ConnectorAuth } from "../tools/credentials.js";
+import { type CatalogVersionFiles, type OrgCatalogTemplate } from "./org-catalog.service.js";
+import { type ComponentKind, type InstallPlan, type PluginInstaller, type PluginInstallInput, type PluginInstallView, type ResolvedDependency } from "./plugin-install.js";
+/** How a component differs between the installed and the target version. */
+export type UpgradeChange = "added" | "changed" | "removed" | "unchanged";
+/**
+ * One component of an upgrade preview: `ref` is the extension name, the dependency's plugin name,
+ * the skill name, the connector template id or the agent template name.
+ */
+export interface UpgradeComponent {
+    kind: ComponentKind;
+    ref: string;
+    change: UpgradeChange;
+    detail?: string;
+}
+/** `POST …/plugin-installs/:installId/upgrade/preview` (spec §10, step 1). */
+export interface UpgradePreview {
+    from: string;
+    to: string;
+    /** Confirm with it; it changes when the target, the install's components or the inputs change. */
+    diffHash: string;
+    components: UpgradeComponent[];
+    inputs: {
+        /** Added templates: their connectors are created with the org's input (as at install). */
+        connectors: string[];
+        /** Changed templates whose auth method or required credentials changed: re-entry needed. */
+        credentialsChanged: string[];
+        /** The extension is added and not yet enabled in the org: its org config may be given. */
+        extensionConfig: boolean;
+    };
+    /**
+     * The target version's connector templates named in `inputs.connectors` and
+     * `inputs.credentialsChanged` (presets and auth, no credentials), for the input form: the target
+     * is not always the latest version (an extension's plugin moves to the deployed version).
+     */
+    templates: OrgCatalogTemplate[];
+}
+/** The body of `POST …/plugin-installs/:installId/upgrade`. */
+export interface PluginUpgradeInput extends PluginInstallInput {
+    version: string;
+    diffHash: string;
+}
+interface LedgerRow {
+    kind: ComponentKind;
+    ref: string;
+    created: boolean;
+    skill_version: number | null;
+    template_id: string | null;
+    dropped: boolean;
+}
+interface VersionRow extends CatalogVersionFiles {
+    version: string;
+    manifest: PluginManifest;
+    source_format: SourceFormat;
+}
+interface SkillDiff {
+    name: string;
+    change: UpgradeChange;
+    /** The skill directory in the target version (added / changed / unchanged). */
+    dir?: string;
+    /** The target version suggests pinning the skill (spec §9.1). */
+    suggestPinned?: boolean;
+    /** The ledger row of the org skill (by skill id), when the install has one that is live. */
+    ledger?: LedgerRow;
+}
+interface AgentTemplateDiff {
+    name: string;
+    change: UpgradeChange;
+    /** The target version's template (added / changed / unchanged). */
+    template?: AgentTemplate;
+    /** The ledger row of the org template, when the install has one that is live. */
+    ledger?: LedgerRow;
+}
+interface TemplateDiff {
+    id: string;
+    change: UpgradeChange;
+    target?: ConnectorTemplateFile;
+    /** The org connector created from the template (live), when the install has one. */
+    connector?: {
+        id: string;
+        connector: string;
+        endpoint: unknown;
+        auth: ConnectorAuth;
+    };
+    ledger?: LedgerRow;
+    credentialsChanged: boolean;
+}
+interface DependencyDiff {
+    name: string;
+    change: UpgradeChange;
+    range?: string;
+    fromRange?: string;
+    resolved?: ResolvedDependency;
+    /** The dependency install recorded in the ledger. */
+    child?: {
+        installId: string;
+        version: string;
+        ledger: LedgerRow;
+    };
+    /** Added: null when already installed in the org (recorded created=false). */
+    plan?: InstallPlan | null;
+}
+/**
+ * Everything an upgrade will do, computed before anything is written (opaque outside this module:
+ * {@link PluginUpgrader.check} hands it to {@link PluginUpgrader.upgrade}).
+ */
+export interface UpgradeDiff {
+    installId: string;
+    itemId: string;
+    name: string;
+    from: VersionRow;
+    to: VersionRow;
+    ledger: LedgerRow[];
+    extension: {
+        change: UpgradeChange;
+        name: string;
+    } | null;
+    skills: SkillDiff[];
+    agentTemplates: AgentTemplateDiff[];
+    templates: TemplateDiff[];
+    dependencies: DependencyDiff[];
+    components: UpgradeComponent[];
+    inputs: UpgradePreview["inputs"];
+    diffHash: string;
+    ledgerHash: string;
+    actions: OrgAction[];
+    /** With input: the connectors to create and the template updates to prepare. */
+    creates: Map<string, CreateConnectorInput>;
+    updates: Map<string, TemplateUpdateInput>;
+}
+/**
+ * Org in-place upgrade (and, for declarative plugins, rollback) of an installed plugin (package
+ * ecosystem spec §10, Decisions 9–11):
+ * - **preview** diffs the installed and the target version per component (extension, dependency
+ *   plugins, skills by name, connector templates by id) and returns the inputs needed and a
+ *   `diffHash`; the same checks as an install run first (dependencies resolve, extension and
+ *   template connectors deployed, skill conflicts -> `plugin.skill_conflict`), plus the target
+ *   rules (`plugin.upgrade_target_invalid`): an extension-bearing plugin can move only to the
+ *   catalog version carrying the deployment's extension, and installs depending on this plugin must
+ *   still accept the target;
+ * - **upgrade** re-checks the `diffHash` (`plugin.upgrade_stale`), sets the install `upgrading`
+ *   under the org lock (another upgrade or an uninstall -> `plugin.install_in_progress`), then:
+ *   added dependencies (installed by the install flow), the added extension (enabled), added and
+ *   changed skills (a new version of the same skill; agents keep selecting it by id), added
+ *   connectors (created from the template), and in one final transaction the changed connectors
+ *   (template-owned fields only, `applyTemplateIn`), the removals by the uninstall rules, the new
+ *   version and the audit `plugin.org_upgraded`. Each step is journaled in
+ *   `plugin_installs.upgrade`; on failure the journal is undone (created components removed, skill
+ *   versions reverted; changed connectors were never committed), the install stays `installed` at
+ *   the old version with `error = { step, code }`, audit `plugin.org_upgrade_failed`, 502
+ *   `plugin.upgrade_failed`. An upgrade interrupted for longer than `catalog.staleInstallMinutes`
+ *   is undone by the next preview, upgrade or uninstall.
+ * Approval follows the item's policy (the org catalog service creates the request). No in-process
+ * state.
+ */
+export declare class PluginUpgrader {
+    private readonly installer;
+    private readonly d;
+    constructor(installer: PluginInstaller);
+    /** The upgrade preview (see the class comment). */
+    preview(orgId: string, actor: string, installId: string, version: string): Promise<UpgradePreview>;
+    /**
+     * The checks of {@link upgrade} before an approval request (the org catalog service creates one
+     * for a needs_approval item without a grant): the diff with the input, the `diffHash`. Returns
+     * the item and the org actions the upgrade needs.
+     */
+    check(orgId: string, actor: string, installId: string, input: PluginUpgradeInput): Promise<{
+        itemId: string;
+        name: string;
+        actions: OrgAction[];
+        diff: UpgradeDiff;
+    }>;
+    /**
+     * Runs an upgrade (see the class comment); returns the install view. `checked` is the diff
+     * {@link check} computed for the same input (re-verified under the org lock: the install's
+     * version and ledger must be unchanged), otherwise it is computed here.
+     */
+    upgrade(orgId: string, actor: string, installId: string, input: PluginUpgradeInput, opts?: {
+        actorTokenId?: string;
+    }, checked?: UpgradeDiff): Promise<PluginInstallView>;
+    /**
+     * Undoes a failed upgrade (its journal, in one transaction): the install back `installed` at the
+     * old version with `error = { step, code }`, audit `plugin.org_upgrade_failed`. When the journal
+     * is no longer this upgrade's (another request cleaned it up as interrupted and undid what it
+     * journaled), only the step whose journal write failed is undone and the install row is left as
+     * the cleanup set it. Returns the error to throw: 502 `plugin.upgrade_failed` (a dependency
+     * another install is still installing: its 409 as it is).
+     */
+    private failed;
+    /**
+     * An upgrade interrupted for longer than `catalog.staleInstallMinutes` (a replica crashed
+     * midway): its journal is undone, the install back `installed` at the old version (error step
+     * `interrupted`), audit `plugin.org_upgrade_failed`. Nothing to do otherwise.
+     */
+    private recoverInterrupted;
+    /**
+     * The removals of an upgrade, in the final transaction, by the uninstall rules
+     * (`decideRemovalIn`): only components this install created are removed, and only when nothing
+     * else uses them; one still used (by an agent, a connector or another extension) stays in the
+     * ledger marked `dropped` ("no longer in the plugin", still this install's), every other removed
+     * component leaves the ledger; a dropped component the target brings back is un-dropped. A dependency
+     * install is uninstalled by the same rules (another install using it takes it over). Skills ->
+     * connectors -> extension -> dependencies.
+     */
+    private removeIn;
+    /**
+     * Computes an upgrade (see the class comment). `input` null: the preview (no input checks);
+     * otherwise the connector inputs are built and checked as at install.
+     */
+    private diff;
+    /**
+     * The update of a changed template's connector: the new endpoint preset with the org's values at
+     * the editable paths, the new auth preset and policies; credentials only when the auth method or
+     * the credentials it needs changed (then the input must give what the template needs).
+     */
+    private templateUpdate;
+}
+export {};