@crouter/api 0.3.387 → 0.3.388

package/dist/core/command-plugins/bundle.d.ts

@@ -0,0 +1,149 @@
+import { type ValidatedCommandManifest } from '../../api/command-manifest/manifest.js';
+import type { KindConfig, MemoryExtensionDeclarations, PageComponentRegistration, PluginBundle, PluginManifest, Scope } from '../../types.js';
+/** Who may call a capability provider's tool group (contract 3). */
+export type ProviderGroupWho = 'own' | 'user' | 'allowlist' | 'any';
+/** One tool group a capability provider declares in `bundle.json`. */
+export interface ProviderGroupDeclaration {
+    group: string;
+    consent_line: string;
+    /** Price per unit, or null/absent when the group is unpriced. */
+    rate?: number | null;
+    who: ProviderGroupWho;
+    /** The app principals the group admits: `[]` unless `who` is `allowlist`
+     *  (where it may also be empty). */
+    allowlist: string[];
+}
+/** The `provider` block of a capability-provider bundle emitted by the directory. */
+export interface ProviderBlock {
+    id: string;
+    major: number;
+    groups: ProviderGroupDeclaration[];
+}
+export interface BundleIssue {
+    code: string;
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export interface ValidatedBundle {
+    bundleVersion: 1;
+    /** The plugin's integer major: `bundle.json` `version`, else `commands.json`
+     *  `version`; absent when neither declares one (treated as 1 locally). */
+    version?: number;
+    /** The transport `bundle.json` declares, when it declares one (a bundle the
+     *  directory emits for a capability provider always does). */
+    transport?: {
+        kind: 'http';
+        endpoint: string;
+        authEnv?: string;
+    };
+    /** The capability-provider block: present only on a provider bundle. */
+    provider?: ProviderBlock;
+    /** Kind-registry contributions declared in `bundle.json` (optional). The
+     *  installer copies this validated block into the synthesized plugin
+     *  manifest, where `readMergedLaunchConfig` layers it — see
+     *  `PluginManifest.kinds`. */
+    kinds?: Record<string, Partial<KindConfig>>;
+    /** Page-component contributions declared in `bundle.json` (optional). The
+     *  installer copies this validated block into the synthesized plugin
+     *  manifest, where `resolvePageComponents` reads it — see
+     *  `PluginManifest.page_components`. */
+    page_components?: PageComponentRegistration[];
+    /** Plugin-owned memory metadata declarations copied into the synthesized
+     * installed manifest alongside the archive's memory documents. */
+    memory_extensions?: MemoryExtensionDeclarations;
+    commands: ValidatedCommandManifest;
+    commandsBytes: Uint8Array;
+    directories: ReadonlyArray<{
+        path: string;
+    }>;
+    memory: ReadonlyArray<{
+        path: string;
+        bytes: Uint8Array;
+    }>;
+    hooks?: {
+        manifest: Uint8Array;
+        files: ReadonlyArray<{
+            path: string;
+            bytes: Uint8Array;
+        }>;
+    };
+}
+export interface PluginBundleValidation {
+    bundle?: ValidatedBundle;
+    issues: BundleIssue[];
+}
+/** Validate a Core-served plugin directory archive entirely in memory. */
+export declare function validatePluginBundle(archive: Uint8Array, options: {
+    reservedCoreNames: ReadonlySet<string>;
+    coreCommandPaths?: ReadonlySet<string>;
+    extensibleCoreBranches?: ReadonlySet<string>;
+}): Promise<PluginBundleValidation>;
+/** An archive install's invocation transport. */
+export type BundleInvocationTransport = {
+    kind: 'http';
+    endpoint: string;
+    authEnv?: string;
+};
+/** The hash recorded as a bundle package's `version`: the exact archive bytes
+ *  unpacked at its root. Same bytes, same version — which is what lets a
+ *  re-sent archive be recognized as the generation already installed. */
+export declare function bundleVersion(raw: Uint8Array): string;
+/** Whether `version` is the generation already unpacked at `root`. Both halves
+ *  matter: the recorded version says the config agrees, and `commands.json`
+ *  says the tree that config describes is actually on disk. A swap that died
+ *  between the rename and the config write leaves the second false, and that is
+ *  exactly the case a no-op must not claim. */
+export declare function isInstalledGeneration(name: string, scope: Scope, root: string, version: string): boolean;
+/** The ledger for a check that reached a served archive. `swapped` says whether
+ *  that archive replaced the package on disk; the validator and the check time
+ *  are recorded either way, because both describe the bytes now at the root. */
+export declare function recordCheckedGeneration(scope: Scope, name: string, etag: string | undefined, options: {
+    swapped: boolean;
+}): void;
+export interface InstallBundleArchiveOptions<M> {
+    scope: Scope;
+    /** The scope root whose `tmp/` holds staging, `.prev` and the swap lock. */
+    scopeRootPath: string;
+    /** Where the package lives once swapped in: `<plugins>/<name>`. */
+    root: string;
+    /** The archive source recorded on the manifest. */
+    bundle: PluginBundle;
+    /** Invocation transport for an ordinary archive. A provider bundle's own
+     *  `bundle.json` transport (the provider endpoint) replaces it: the archive
+     *  comes from the directory, but calls go to the provider. */
+    transport: BundleInvocationTransport;
+    /** The server's validator for `raw`, recorded once the swap lands. */
+    etag: string | undefined;
+    enable: boolean;
+    /** `bundleVersion(raw)` when the caller already computed it. */
+    version?: string;
+    validation: {
+        reservedCoreNames: ReadonlySet<string>;
+        coreCommandPaths?: ReadonlySet<string>;
+        extensibleCoreBranches?: ReadonlySet<string>;
+    };
+    /** Full candidate validation of the staged tree; throws to refuse it. */
+    validateStaged: (staging: string, manifest: PluginManifest) => Promise<M>;
+    /** Builds the error an invalid archive throws. */
+    invalid: (summary: string, issues: readonly BundleIssue[]) => Error;
+    /** Checked against the validated archive before anything is written; a
+     *  returned message refuses the archive (a provider bundle naming another id). */
+    accept?: (bundle: ValidatedBundle) => string | undefined;
+}
+export interface InstalledBundleArchive<M> {
+    manifest: PluginManifest;
+    validated: ValidatedBundle;
+    version: string;
+    root: string;
+    staged: M;
+}
+/**
+ * Validate `raw`, stage it beside the package root, swap it in, then record
+ * the config version and the state validator — in that order, never the
+ * reverse. A failure before the swap leaves the previous package untouched.
+ * The caller holds the plugin's swap lock (`bundleSwapLockPath`).
+ */
+export declare function installBundleArchive<M>(name: string, raw: Uint8Array, options: InstallBundleArchiveOptions<M>): Promise<InstalledBundleArchive<M>>;