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

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

@@ -0,0 +1,436 @@
+import { type AgentTemplate, type AgentTemplateTier, type Connector, type LocalizedName, type Logger } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+import type { ExtensionAdminOps } from "../extensions/admin-ops.js";
+import type { ExtensionInstalls } from "../extensions/installs.js";
+import { ExtensionPackageError } from "../extensions/package.js";
+import { type PackageWarning, type PermissionGroup, type PermissionItem } from "../extensions/permission-view.js";
+import type { ExtensionSource } from "../extensions/sources.js";
+import type { ProvenanceResult } from "../packages/provenance.js";
+import type { StorageService } from "../storage/storage.service.js";
+import { type ActorOpts, type CatalogItemView, type PermissionsMismatch, type SourceDetail } from "./catalog.service.js";
+import { type ClaudeEntryOverlay } from "./claude/manifest.js";
+import { type TranslationReport } from "./claude/report.js";
+import { PluginPackageError } from "./plugin-package.js";
+/**
+ * Enterprise import of a plugin (package ecosystem spec §4.3): one review for every plugin, whatever
+ * it contains (an extension, skills, connector templates, dependencies), confirmed once.
+ *
+ * prepare: the tgz is always hostile input, and **nothing is written until every check passes**
+ * (F-AD): `readPluginPackage` (plugin.json, package.json, listed / scanned skills and templates,
+ * icons; a pre-0.1.0 tgz is `catalog.legacy_format`), the extension's module graph and migrations
+ * (`readExtensionPackage`), the extension's deployment state (config-declared names are
+ * refused; name ownership; a downgrade to a version with unrun migrations is refused), each skill by
+ * the skill package rules, each connector template against the connector loaded on this replica (or
+ * statically when the connector is provided by the plugin's own extension or by a dependency), the
+ * catalog name / version conflicts and the actor still an enterprise admin. Dependencies are only
+ * resolved against the imported catalog versions for the review (an unresolved one does not block
+ * the import, spec §4.1); they are never fetched. Only then is the extension handed to
+ * `ExtensionInstalls.ingest` (source `catalog`), the skill / template / icon files written to object
+ * storage, a staging row written (24 hours) and `catalog.plugin_staged` audited.
+ *
+ * confirm: `reviewHash` must match the staging; in one transaction it deletes the staging row
+ * (confirm works once), locks the extension name and recomputes its deployment state (installed /
+ * upgraded / swapped after the review -> `plugin.review_stale`), writes the extension's permission
+ * snapshot when it is installed by this import (or upgraded with `deployExtension`; source web, audit
+ * `extension.permissions_approved` carrying the plugin), and creates the item or adds the version
+ * (`manifest` = the normalized plugin.json, `extension_sha256`, the files under the staging prefix).
+ * After the commit, with `deployExtension`, the plugin's own extension is installed on the
+ * deployment and enabled (`ExtensionAdminOps.install` + `enable`; each replica reconciles, no
+ * restart); a failure is returned, not thrown, and an upgrade that was not installed gets its old
+ * snapshot back.
+ *
+ * Expired staging is cleaned by the maintenance job `app-staging-cleanup`
+ * ({@link PluginImport.cleanupExpired}): it deletes the staging row and its object prefix; a stored
+ * extension package stays in the content-addressed `extension_packages` (the same as importing the
+ * same tgz again; without an install record referencing it it is never loaded).
+ */
+/** How long a staged import is kept. */
+export declare const PLUGIN_STAGING_TTL_MS: number;
+/** The deployment state of the plugin's extension and what confirming with `deployExtension` does. */
+export type ExtensionReviewAction = "install" | "upgrade" | "keep";
+/** The plugin's extension in a review. */
+export interface PluginReviewExtension {
+    name: string;
+    version: string;
+    /** sha256 of the plugin tgz (the package store key). */
+    sha256: string;
+    /**
+     * install: not on the deployment; upgrade: installed from another package (another version), the
+     * import's package replaces it when deployed; keep: this exact package is installed.
+     */
+    action: ExtensionReviewAction;
+    /** Installed on the deployment (any version). */
+    deployed: boolean;
+    /** The installed version (null when not installed). */
+    currentVersion: string | null;
+    /** The installed package (null when not installed). */
+    currentSha256: string | null;
+    /** Permissions from the static manifest and migration SQL (no extension code runs). */
+    permissions: PermissionGroup[];
+    /** Permission keys added / removed against the current snapshot (all added without one). */
+    added: string[];
+    addedItems: PermissionItem[];
+    removed: string[];
+    /** Review warnings of the migration SQL (sensitive). */
+    warnings: PackageWarning[];
+    /** The extension's own review digest (as when its package is uploaded alone). */
+    reviewHash: string;
+    /** Sensitive permissions or migration warnings. */
+    sensitive: boolean;
+}
+/** One connector template in a review. */
+export interface PluginReviewTemplate {
+    id: string;
+    displayName: LocalizedName;
+    description: string;
+    plugin: string;
+    connector: string;
+    endpoint: Record<string, unknown>;
+    auth: Record<string, unknown>;
+    editableEndpoint: string[];
+    /** The connector is loaded on this replica and the endpoint was checked against its schema. */
+    endpointChecked: boolean;
+}
+/** One agent template in a review (sub-agents spec §16.2: its tool narrowing and model tier). */
+export interface PluginReviewAgentTemplate {
+    name: string;
+    /** Relative to the plugin root. */
+    path: string;
+    description: string;
+    /** The instructions (the body). */
+    instructions: string;
+    /** Default `inherit`. */
+    model: AgentTemplateTier;
+    tools?: string[];
+    disallowedTools?: string[];
+    toolPolicies?: Record<string, "ask" | "deny">;
+    effort?: AgentTemplate["effort"];
+    maxSteps?: number;
+    skills?: string[];
+}
+/** The source of a staged import. */
+export interface PluginImportSource {
+    /**
+     * `git`: read from a git commit (a git marketplace's entry, or a direct git import);
+     * `bootstrap`: a package baked into the image, imported by the bootstrap step (its extension
+     * package is kept in PG, since the object store may be one of the bootstrap plugins; the
+     * permission snapshot is written with source `bootstrap`).
+     */
+    kind: "file" | "npm" | "marketplace" | "git" | "bootstrap";
+    ref: string;
+    integrity?: string;
+    marketplaceId?: string;
+    /** Where it came from (stored on the catalog version as `source_detail`). */
+    detail?: SourceDetail;
+}
+/** The format a plugin was read from: a Capybara plugin, or a translated Claude Code plugin. */
+export type PluginSourceFormat = "capybara" | "claude-code";
+/** The largest license text stored (bytes); a longer one is omitted (`licenseTruncated`). */
+export declare const LICENSE_TEXT_MAX_BYTES = 65536;
+/** The one review of a plugin (the enterprise admin sees every component before confirming). */
+export interface PluginReview {
+    name: string;
+    /** `claude-code`: translated from a Claude Code plugin (no extension; see `translation`). */
+    format: PluginSourceFormat;
+    /** The translation report of a Claude Code plugin (spec §8.4). */
+    translation?: TranslationReport;
+    /** The tree has both manifests: `.capybara-plugin/plugin.json` was read, the Claude one ignored. */
+    claudeManifestIgnored?: true;
+    /**
+     * `repository` of a Claude Code plugin's manifest (spec §8.2): display only, never checked or
+     * fetched, not stored with the version.
+     */
+    repository?: string;
+    /** The root LICENSE text (UTF-8, at most {@link LICENSE_TEXT_MAX_BYTES} bytes). */
+    licenseText?: string;
+    /** The root LICENSE is longer than {@link LICENSE_TEXT_MAX_BYTES} bytes (or not UTF-8) and is not stored. */
+    licenseTruncated?: true;
+    /**
+     * The version recorded: the plugin's own (plugin.json, else the entry's, else the fallback of
+     * spec §5.3), with `+git.<sha12>` / `+sha256.<12>` appended when that release is already imported
+     * with other content (Decision 6).
+     */
+    version: string;
+    /** The plugin's own version when `version` got build metadata appended. */
+    pluginVersion?: string;
+    /** The content digest of the plugin's files (Decision 5). */
+    contentDigest: string;
+    /** package.json `name`; null for a git plugin without package.json. */
+    packageName: string | null;
+    publisher: string;
+    description: string;
+    displayName?: LocalizedName;
+    license?: string;
+    homepage?: string;
+    extension?: PluginReviewExtension;
+    skills: {
+        name: string;
+        description: string;
+        body: string;
+        path: string;
+        files: number;
+        /** The plugin suggests pinning the skill (plugin.json `pinned`; changed at confirm). */
+        suggestPinned: boolean;
+    }[];
+    connectorTemplates: PluginReviewTemplate[];
+    /**
+     * Agent templates (phase C). Absent in reviews staged before phase C (read as none); left out of
+     * {@link pluginReviewHash} when empty, so their digests are unchanged.
+     */
+    agentTemplates?: PluginReviewAgentTemplate[];
+    /**
+     * Each dependency with the highest imported catalog version satisfying its range (null when
+     * nothing does yet: the import still completes, an org install is refused until it is imported).
+     */
+    dependencies: {
+        name: string;
+        range: string;
+        resolved: string | null;
+    }[];
+    source: PluginImportSource;
+    /**
+     * npm provenance (spec §5.5, display only): "built from `repository`@`commit` by `workflow`" for
+     * npm and npm-backed marketplace imports when the registry has it; otherwise not checked, with
+     * the reason ("not an npm package" for every other source).
+     */
+    provenance: ProvenanceResult;
+    /** A git marketplace's repository differs from the attested one (a warning, never a refusal). */
+    provenanceWarning?: "repository_mismatch";
+    /** The extension is sensitive. */
+    sensitive: boolean;
+    /** Digest of everything above that confirm depends on; sent back on confirm. */
+    reviewHash: string;
+}
+/** The deploy result of the plugin's extension with `deployExtension`. */
+export interface ExtensionDeployResult {
+    name: string;
+    action: "install" | "upgrade";
+    version: string;
+    /** The package to install (retry through the extension admin with it after a failure). */
+    sha256: string;
+    /**
+     * enabled: installed and enabled; installed: installed, desired state left as it was (confirm
+     * with `enable: false`, the bootstrap step's upgrades); failed: see code / message.
+     */
+    result: "enabled" | "installed" | "failed";
+    code?: string;
+    message?: string;
+    /** e.g. `snapshot_not_restored: …` when an upgrade failed and the snapshot had changed since. */
+    note?: string;
+}
+/** The result of {@link PluginImport.confirm}. */
+export interface PluginConfirmResult {
+    item: CatalogItemView;
+    /** null without `deployExtension` or when there is nothing to deploy (no extension, keep). */
+    deploy: ExtensionDeployResult | null;
+}
+/** What prepare checks besides the package itself (npm and marketplace imports). */
+export interface PluginPrepareExpect {
+    /** The npm package that was requested (package.json `name` must equal it). */
+    packageName?: string;
+    /**
+     * Marketplace import: the entry the package must match (`marketplace.package_mismatch`) and its
+     * permission summary (`permissions`, compared with the package's keys: a warning only).
+     */
+    marketplace?: {
+        name: string;
+        version: string | null;
+        packageName?: string;
+        permissions?: string[];
+    };
+}
+/** The provenance shown with a review (fetched by the npm paths before prepare). */
+export interface ReviewProvenance {
+    provenance: ProvenanceResult;
+    warning?: "repository_mismatch";
+}
+export interface PluginImportDeps {
+    db: KernelDb;
+    config: () => KernelConfig;
+    storage: StorageService;
+    installs: Pick<ExtensionInstalls, "ingest" | "fetchNpm" | "fetchProvenance">;
+    ops: Pick<ExtensionAdminOps, "install" | "enable">;
+    /** Reads a package from the package store (confirm recomputes the permission set). */
+    blobs: {
+        get(sha256: string): Promise<Uint8Array>;
+    };
+    /** Config-declared extension names -> source. */
+    declared: () => ReadonlyMap<string, ExtensionSource>;
+    /** The connector `kind` provided by extension `plugin` loaded on this replica. */
+    findConnector: (plugin: string, kind: string) => Connector | undefined;
+    /** The version of an extension loaded on this replica (templates' `pluginVersion` is checked). */
+    pluginVersion?: (plugin: string) => string | undefined;
+    /**
+     * false: this process loads no connectors (the CLI), so a template of an unknown connector gets
+     * only the static endpoint checks and `endpointChecked: false`; the org install re-checks it
+     * against the loaded connector. Default true (the HTTP path).
+     */
+    connectorsLoaded?: boolean;
+    log: Pick<Logger, "info" | "warn" | "error">;
+}
+/**
+ * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
+ * `catalog.legacy_format`, anything else -> `catalog.invalid_manifest` (issues as details).
+ */
+export declare function catalogPackageError(e: PluginPackageError | ExtensionPackageError): ApiError;
+export declare class PluginImport {
+    private readonly d;
+    constructor(d: PluginImportDeps);
+    /**
+     * Reads, checks and stages a plugin (see the file header). Returns the staging id and review.
+     * `fallback` (a marketplace archive): a tgz without plugin.json may be skills only, named,
+     * versioned and published by it (the version defaulting to `0.0.0-sha256.h<12>`, spec §5.3).
+     */
+    prepare(actor: string | null, bytes: Uint8Array, source: PluginImportSource, opts?: ActorOpts & {
+        expect?: PluginPrepareExpect;
+        fallback?: {
+            name: string;
+            version?: string;
+            publisher: string;
+        };
+        provenance?: ReviewProvenance;
+        claudeManifestIgnored?: true;
+    }): Promise<{
+        stagingId: string;
+        review: PluginReview;
+        permissionKeys: string[];
+        permissionsMismatch: PermissionsMismatch;
+    }>;
+    /**
+     * Checks and stages a plugin read from a git commit (`files` relative to the plugin root; see
+     * `git-source.ts`): the same checks as a tgz ({@link readPluginFiles}), with package.json
+     * optional (spec §4.1) and a skills-only tree without plugin.json named by `fallback` (Decision
+     * 3). A plugin with an extension needs package.json (its peerDependencies ranges are checked as
+     * for a tgz) and its build output; its files are packed into a deterministic tgz, which is what
+     * the package store keeps and the deployment installs. Returns what {@link prepare} returns.
+     */
+    prepareGit(actor: string | null, files: Map<string, Uint8Array>, source: PluginImportSource, opts: ActorOpts & {
+        expect?: PluginPrepareExpect;
+        /**
+         * `version` is the entry's version, else derived from the commit (spec §5.3); `entryVersion`
+         * is the entry's own (a Claude Code plugin reports where its version came from).
+         */
+        fallback: {
+            name: string;
+            version: string;
+            publisher: string;
+            entryVersion?: string;
+        };
+        provenance?: ReviewProvenance;
+        /** The Claude Code marketplace entry's overlay (the entry's components and `strict`). */
+        claude?: ClaudeEntryOverlay;
+    }): Promise<{
+        stagingId: string;
+        review: PluginReview;
+        permissionKeys: string[];
+        permissionsMismatch: PermissionsMismatch;
+    }>;
+    /**
+     * The checks and writes of prepare after the package was read. `tgz.bytes` is the package tgz
+     * (required with an extension: it is stored in the package store); `size` is recorded.
+     */
+    private prepareContents;
+    /** Fetches a plugin from the configured npm registry (verified by `dist.integrity`), then prepares it. */
+    prepareNpm(actor: string | null, input: {
+        package: string;
+        version?: string;
+    }, opts?: ActorOpts): Promise<{
+        stagingId: string;
+        review: PluginReview;
+    }>;
+    /**
+     * A staged import's review, as prepare returned it, with a marketplace import's permission
+     * mismatch when there is one (the import page loads `?staging=<id>` with it). Unknown, expired or
+     * already confirmed -> 404 `plugin.staging_not_found`.
+     */
+    staged(stagingId: string): Promise<{
+        stagingId: string;
+        review: PluginReview;
+        permissionsMismatch?: PermissionsMismatch;
+    }>;
+    /**
+     * Confirms a staged import (see the file header). Returns the committed catalog item and, with
+     * `deployExtension`, the extension's deploy result (a failed deploy is returned, not thrown).
+     */
+    confirm(actor: string | null, stagingId: string, input: {
+        reviewHash: string;
+        deployExtension: boolean;
+        /**
+         * With `deployExtension`: enable the extension after installing it (default true). false
+         * keeps the install record's desired state (a new install stays disabled), for the bootstrap
+         * step's upgrades of a plugin an enterprise admin may have disabled.
+         */
+        enable?: boolean;
+        /**
+         * The skills (by name, each in the review) suggested as pinned when an agent selects them
+         * (spec §9.1); replaces the plugin's `pinned` flags in the stored manifest. Omitted keeps
+         * them. An admin decision like `deployExtension`, so not part of `reviewHash`.
+         */
+        pinnedSuggestions?: string[];
+    }, opts?: ActorOpts): Promise<PluginConfirmResult>;
+    /**
+     * Writes the extension's permission snapshot for the version being imported (source web; cli
+     * without an actor; bootstrap for the bootstrap step), after
+     * registering the name owner like ExtensionAdminOps.install (Ruling P3). Returns the snapshot it
+     * overwrote (null when there was none).
+     */
+    private approve;
+    /**
+     * Deploys the plugin's extension after the commit: `install` (a new install is disabled, a version
+     * change keeps the desired state) then `enable`. Nothing is thrown; the result says what happened.
+     * When an upgrade was not installed, the snapshot overwritten at confirm is restored (the old
+     * version keeps running, F-O; audit `extension.permissions_restored`). Retry through the extension
+     * admin (the package is already in the package store) with the sha256 from the result.
+     */
+    private deploy;
+    /**
+     * Restores the snapshot overwritten at confirm (deletes it when there was none before), audits
+     * `extension.permissions_restored`. Compare-and-write (row locked): restores only while the
+     * snapshot is still the one written at confirm (this version, approved by this actor); if someone
+     * approved or changed it meanwhile it is left alone and false is returned.
+     */
+    private restoreSnapshot;
+    /**
+     * Deletes expired staging rows and their object prefixes (maintenance job `app-staging-cleanup`).
+     * Row by row: objects first, then the row (a failed object delete keeps the row for the next
+     * round); concurrent replicas skip each other's rows (`SKIP LOCKED`). Returns the rows deleted.
+     */
+    cleanupExpired(): Promise<number>;
+    /** npm / marketplace imports: the package must be the one that was asked for. */
+    private checkExpected;
+    /** A config-declared extension's name cannot be taken by an imported plugin. */
+    private assertNotDeclared;
+    /**
+     * Skills (by the skill package rules), connector templates (against the loaded connector) and
+     * icons; returns the files to store and the review's skills and templates.
+     */
+    private checkContent;
+    /**
+     * The highest imported, non-deleted catalog version satisfying each dependency's range (null when
+     * none does).
+     */
+    private resolveDependencies;
+    /**
+     * The extension's state on the deployment; installed from another npm package ->
+     * `extension.name_conflict`.
+     */
+    private extensionState;
+    /** The review of the extension: permissions, the change against the snapshot, warnings, action. */
+    private reviewExtension;
+    private readStored;
+    private itemView;
+}
+/**
+ * The review digest (first 32 hex of a sha256): name, version and content digest, the extension (sha256, action,
+ * current version / package, its own review digest), every template field, each skill's name / path
+ * / file count, the dependency resolution, the sha256 of every stored file, the format, the
+ * translation report's items, the sha256 of the license text and the two review flags
+ * (`claudeManifestIgnored`, `licenseTruncated`), and the agent templates when there are any.
+ * Exported for tests. `repository` is display only.
+ */
+export declare function pluginReviewHash(r: Pick<PluginReview, "name" | "version" | "contentDigest" | "extension" | "connectorTemplates" | "agentTemplates" | "skills" | "dependencies" | "format" | "translation" | "licenseText" | "claudeManifestIgnored" | "licenseTruncated">, files: {
+    path: string;
+    sha256: string;
+}[]): string;