@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/dist/domain/plugin/archive.js

@@ -0,0 +1,50 @@
+import { comparePaths, isContainedPath } from "@stigmer/plugin-package";
+import { InflateError, inflateEntry } from "../../archive/inflate.js";
+import { MAX_ZIP_SIZE, PLATFORM_ARCHIVE_LIMITS } from "../../archive/limits.js";
+import { openArchive, validateArchiveStructure } from "../../archive/open.js";
+/**
+ * Gates the archive and builds the lazy reader. Directory entries and
+ * entries whose sanitised name the library would refuse as uncontained are
+ * dropped here rather than surfaced: the prefilter already made every name
+ * unrooted and `..`-free, so what remains is the rare empty-segment name,
+ * which no plugin author writes and no manifest can declare.
+ */
+export function openPluginArchive(bytes) {
+    const { hash, entries } = openArchive(bytes, MAX_ZIP_SIZE);
+    validateArchiveStructure(entries, PLATFORM_ARCHIVE_LIMITS);
+    const byPath = new Map();
+    for (const prefiltered of entries) {
+        const { name } = prefiltered;
+        if (name.endsWith("/") || !isContainedPath(name)) {
+            continue;
+        }
+        // Two entries sanitising to one name (`a/../b.md` beside `b.md`): the
+        // first wins, as the skill gate's "first root-named entry" rule reads.
+        if (!byPath.has(name)) {
+            byPath.set(name, prefiltered);
+        }
+    }
+    const fileEntries = [...byPath.values()]
+        .map(({ name, entry }) => ({ path: name, size: entry.uncompressedSize }))
+        .sort((a, b) => comparePaths(a.path, b.path));
+    const files = {
+        entries: fileEntries,
+        read(path) {
+            const prefiltered = byPath.get(path);
+            if (prefiltered === undefined) {
+                throw new Error(`plugin file '${path}' is not listed`);
+            }
+            try {
+                return inflateEntry(prefiltered.entry, prefiltered.entry.uncompressedSize);
+            }
+            catch (error) {
+                if (error instanceof InflateError) {
+                    throw new Error(`failed to read '${path}' from the plugin archive: ${error.detail}`);
+                }
+                throw error;
+            }
+        },
+    };
+    return { digest: hash, files };
+}
+//# sourceMappingURL=archive.js.map

package/dist/domain/plugin/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../../src/domain/plugin/archive.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAExE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAU9E;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAC3D,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAAC;IAE3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAC;IACnD,KAAK,MAAM,WAAW,IAAI,OAAO,EAAE,CAAC;QAClC,MAAM,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC;QAC7B,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;YACjD,SAAS;QACX,CAAC;QACD,sEAAsE;QACtE,uEAAuE;QACvE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAsB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;SACxD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC;SACxE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEhD,MAAM,KAAK,GAAgB;QACzB,OAAO,EAAE,WAAW;QACpB,IAAI,CAAC,IAAY;YACf,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,iBAAiB,CAAC,CAAC;YACzD,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,YAAY,CACjB,WAAW,CAAC,KAAK,EACjB,WAAW,CAAC,KAAK,CAAC,gBAAgB,CACnC,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;oBAClC,MAAM,IAAI,KAAK,CACb,mBAAmB,IAAI,8BAA8B,KAAK,CAAC,MAAM,EAAE,CACpE,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACjC,CAAC"}

package/dist/domain/plugin/constants.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Plugin domain constants — every wire-visible string and pinned value in
+ * one place (guidelines: errors are API surface; the CLI, console and SDK
+ * show these verbatim). The archive budgets are the platform's
+ * (src/archive/limits.ts); what is a plugin's is here.
+ */
+/** Storage key prefix for plugin archives: "plugins/<digest>.zip". */
+export declare const PLUGIN_ARTIFACT_KEY_PREFIX = "plugins/";
+/**
+ * A manifest version becomes the plugin's audit tag only when it fits the
+ * tag pattern every versioned kind shares (`spec.tag` on skills). Semantic
+ * Versioning build metadata (`1.0.0+build.1`) does not fit; such a version
+ * installs untagged with a warning rather than refusing the plugin.
+ */
+export declare const VERSION_TAG_PATTERN: RegExp;
+/**
+ * The runner's built-in sub-agents. A plugin sub-agent bearing one of these
+ * names shadows a built-in at run time; the runner only warns, so the
+ * install warns too rather than refusing (an M1 finding kept as data here).
+ */
+export declare const BUILT_IN_SUB_AGENT_NAMES: ReadonlySet<string>;
+/**
+ * The materialisation order and the kinds a plugin may own, in the order
+ * references resolve: an agent names skills and servers, a workflow may
+ * name the agent. Cascade deletes in reverse.
+ */
+export declare const MATERIALIZATION_ORDER: readonly ["skill", "mcp_server", "agent", "workflow"];
+export type MaterializedKindName = (typeof MATERIALIZATION_ORDER)[number];
+/** FailedPrecondition copy when the upload lane was not configured. */
+export declare const TRANSFER_LANE_NOT_CONFIGURED = "plugin artifact transfer lane is not configured on this server";
+/** Warning kinds the SERVER adds to the library's; the wire carries them as strings. */
+export declare const SERVER_WARNING_KINDS: {
+    readonly componentIgnored: "component-ignored";
+    readonly modelHintUnresolved: "model-hint-unresolved";
+    readonly subAgentNameBuiltin: "sub-agent-name-builtin";
+    readonly versionNotTaggable: "version-not-taggable";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/domain/plugin/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/domain/plugin/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sEAAsE;AACtE,eAAO,MAAM,0BAA0B,aAAa,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAsB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAIvD,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,uDAKxB,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,uEAAuE;AACvE,eAAO,MAAM,4BAA4B,mEACyB,CAAC;AAEnE,wFAAwF;AACxF,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC"}

package/dist/domain/plugin/constants.js

@@ -0,0 +1,46 @@
+/**
+ * Plugin domain constants — every wire-visible string and pinned value in
+ * one place (guidelines: errors are API surface; the CLI, console and SDK
+ * show these verbatim). The archive budgets are the platform's
+ * (src/archive/limits.ts); what is a plugin's is here.
+ */
+/** Storage key prefix for plugin archives: "plugins/<digest>.zip". */
+export const PLUGIN_ARTIFACT_KEY_PREFIX = "plugins/";
+/**
+ * A manifest version becomes the plugin's audit tag only when it fits the
+ * tag pattern every versioned kind shares (`spec.tag` on skills). Semantic
+ * Versioning build metadata (`1.0.0+build.1`) does not fit; such a version
+ * installs untagged with a warning rather than refusing the plugin.
+ */
+export const VERSION_TAG_PATTERN = /^[a-zA-Z0-9._-]+$/;
+/**
+ * The runner's built-in sub-agents. A plugin sub-agent bearing one of these
+ * names shadows a built-in at run time; the runner only warns, so the
+ * install warns too rather than refusing (an M1 finding kept as data here).
+ */
+export const BUILT_IN_SUB_AGENT_NAMES = new Set([
+    "explore",
+    "shell",
+    "general-purpose",
+]);
+/**
+ * The materialisation order and the kinds a plugin may own, in the order
+ * references resolve: an agent names skills and servers, a workflow may
+ * name the agent. Cascade deletes in reverse.
+ */
+export const MATERIALIZATION_ORDER = [
+    "skill",
+    "mcp_server",
+    "agent",
+    "workflow",
+];
+/** FailedPrecondition copy when the upload lane was not configured. */
+export const TRANSFER_LANE_NOT_CONFIGURED = "plugin artifact transfer lane is not configured on this server";
+/** Warning kinds the SERVER adds to the library's; the wire carries them as strings. */
+export const SERVER_WARNING_KINDS = {
+    componentIgnored: "component-ignored",
+    modelHintUnresolved: "model-hint-unresolved",
+    subAgentNameBuiltin: "sub-agent-name-builtin",
+    versionNotTaggable: "version-not-taggable",
+};
+//# sourceMappingURL=constants.js.map

package/dist/domain/plugin/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/domain/plugin/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,0BAA0B,GAAG,UAAU,CAAC;AAErD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAwB,IAAI,GAAG,CAAC;IACnE,SAAS;IACT,OAAO;IACP,iBAAiB;CAClB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,OAAO;IACP,YAAY;IACZ,OAAO;IACP,UAAU;CACF,CAAC;AAGX,uEAAuE;AACvE,MAAM,CAAC,MAAM,4BAA4B,GACvC,gEAAgE,CAAC;AAEnE,wFAAwF;AACxF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,gBAAgB,EAAE,mBAAmB;IACrC,mBAAmB,EAAE,uBAAuB;IAC5C,mBAAmB,EAAE,wBAAwB;IAC7C,kBAAkB,EAAE,sBAAsB;CAClC,CAAC"}

package/dist/domain/plugin/controller.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import type { ContentAddressedArchiveStore } from "../../archive/content-store.js";
+import type { Logger } from "../../boot/logger.js";
+import type { Authorizer } from "../../extensions/authorizer.js";
+import type { ResourceAuthorizationLifecycle } from "../../extensions/resource-authorization.js";
+import type { Store } from "../../store/interface.js";
+import type { UploadSlots } from "../skill/transfer/slots.js";
+import type { PluginMaterializerProvider } from "./materialize/ports.js";
+/** The transfer lane's controller-side pair; the slots are the skill lane's (one upload surface). */
+export interface PluginTransferLaneDeps {
+    readonly slots: UploadSlots;
+    readonly baseUrl: string;
+}
+export interface PluginControllerDeps {
+    readonly store: Store;
+    readonly logger: Logger;
+    readonly authorizer: Authorizer;
+    readonly authorizationLifecycle: ResourceAuthorizationLifecycle | undefined;
+    readonly artifactStorage: ContentAddressedArchiveStore;
+    readonly materializerProvider: PluginMaterializerProvider;
+    readonly transferLane?: PluginTransferLaneDeps;
+}
+/** Registers both plugin services on the router (routes stage). */
+export declare function registerPluginServices(router: ConnectRouter, deps: PluginControllerDeps): void;
+//# sourceMappingURL=controller.d.ts.map

package/dist/domain/plugin/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../src/domain/plugin/controller.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,qBAAqB,CAAC;AAiCzE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAEnF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4CAA4C,CAAC;AAgDjG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAEtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AA+BzE,qGAAqG;AACrG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,sBAAsB,EAAE,8BAA8B,GAAG,SAAS,CAAC;IAC5E,QAAQ,CAAC,eAAe,EAAE,4BAA4B,CAAC;IACvD,QAAQ,CAAC,oBAAoB,EAAE,0BAA0B,CAAC;IAC1D,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC;CAChD;AAED,mEAAmE;AACnE,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,oBAAoB,GACzB,IAAI,CAcN"}