@ai-agent-forge/agent-forge 0.85.0

package/dist/plugins/ecosystem/node-url-package-source.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { detectPluginPackageMediaTypeV1 } from "./node-package-media.js";
+/**
+ * Custom-URL plugin package download (design §4.6 "自定义 URL" row). The URL
+ * is the package file itself (zip/tgz); integrity is layered: a `#sha256:<hex>`
+ * ref fragment becomes a strong digest check, otherwise TLS plus the double
+ * manifest validation performed by the install host.
+ */
+const DEFAULT_TIMEOUT_MS_V1 = 30_000;
+const MAX_TIMEOUT_MS_V1 = 120_000;
+const DEFAULT_MAX_PACKAGE_BYTES_V1 = 128 * 1024 * 1024;
+const MAX_PACKAGE_BYTES_V1 = 512 * 1024 * 1024;
+const DEFAULT_REDIRECTS_V1 = 3;
+const MAX_REDIRECTS_V1 = 5;
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+export class NodeUrlPackageSourceErrorV1 extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "NodeUrlPackageSourceErrorV1";
+        this.code = code;
+    }
+}
+function boundedPositive(value, fallback, maximum, label) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result <= 0 || result > maximum)
+        throw new NodeUrlPackageSourceErrorV1("invalid_configuration", `${label} must be a positive integer at most ${maximum}`);
+    return result;
+}
+function packageUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new NodeUrlPackageSourceErrorV1("invalid_url", "plugin package URL is invalid");
+    }
+    if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+        parsed.username !== "" ||
+        parsed.password !== "")
+        throw new NodeUrlPackageSourceErrorV1("invalid_url", "plugin package URL must use http(s) without credentials");
+    if (parsed.hash !== "")
+        throw new NodeUrlPackageSourceErrorV1("invalid_url", "plugin package URL must not include a fragment");
+    return parsed;
+}
+function isAbortLike(error) {
+    return error instanceof Error && (error.name === "AbortError" || error.name === "AbortSignalError");
+}
+/**
+ * Download one package file over http(s). Redirects are followed manually and
+ * every hop must again be a valid http(s) URL without credentials. When
+ * `expectedDigestHex` is present the sha256 of the bytes must match exactly.
+ */
+export async function downloadNodeUrlPackageV1(options, input) {
+    const transport = options.fetch ?? globalThis.fetch;
+    if (typeof transport !== "function")
+        throw new NodeUrlPackageSourceErrorV1("invalid_configuration", "Node fetch is unavailable");
+    const timeoutMs = boundedPositive(options.requestTimeoutMs, DEFAULT_TIMEOUT_MS_V1, MAX_TIMEOUT_MS_V1, "requestTimeoutMs");
+    const maxPackageBytes = boundedPositive(options.maxPackageBytes, DEFAULT_MAX_PACKAGE_BYTES_V1, MAX_PACKAGE_BYTES_V1, "maxPackageBytes");
+    const maxRedirects = options.maxRedirects ?? DEFAULT_REDIRECTS_V1;
+    if (!Number.isSafeInteger(maxRedirects) || maxRedirects < 0 || maxRedirects > MAX_REDIRECTS_V1)
+        throw new NodeUrlPackageSourceErrorV1("invalid_configuration", `maxRedirects must be an integer between 0 and ${MAX_REDIRECTS_V1}`);
+    const userAgent = options.userAgent ?? "agent-forge-plugin-url/1";
+    if (userAgent.length === 0 || userAgent.length > 256 || /[\r\n]/u.test(userAgent))
+        throw new NodeUrlPackageSourceErrorV1("invalid_configuration", "userAgent is invalid");
+    if (input.expectedDigestHex !== undefined && !/^[0-9a-f]{64}$/u.test(input.expectedDigestHex))
+        throw new NodeUrlPackageSourceErrorV1("invalid_url", "expected sha256 digest is invalid");
+    let current = packageUrl(input.url);
+    let response;
+    const controller = new AbortController();
+    let timedOut = false;
+    const abort = () => controller.abort(input.signal?.reason);
+    if (input.signal?.aborted === true)
+        abort();
+    else
+        input.signal?.addEventListener("abort", abort, { once: true });
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    try {
+        for (let redirect = 0;; redirect += 1) {
+            if (controller.signal.aborted)
+                throw new NodeUrlPackageSourceErrorV1("cancelled", "plugin package download was cancelled");
+            let hop;
+            try {
+                hop = await transport(current.toString(), {
+                    method: "GET",
+                    headers: { accept: "*/*", "user-agent": userAgent },
+                    redirect: "manual",
+                    signal: controller.signal,
+                });
+            }
+            catch (error) {
+                if (timedOut)
+                    throw new NodeUrlPackageSourceErrorV1("request_timed_out", "plugin package download timed out");
+                if (isAbortLike(error) || input.signal?.aborted === true)
+                    throw new NodeUrlPackageSourceErrorV1("cancelled", "plugin package download was cancelled");
+                throw new NodeUrlPackageSourceErrorV1("request_failed", "plugin package download failed");
+            }
+            if (!REDIRECT_STATUS.has(hop.status)) {
+                response = hop;
+                break;
+            }
+            const location = hop.headers.get("location");
+            await hop.body?.cancel().catch(() => undefined);
+            if (location === null || redirect >= maxRedirects)
+                throw new NodeUrlPackageSourceErrorV1("request_failed", "plugin package redirect limit exceeded");
+            current = packageUrl(new URL(location, current).toString());
+        }
+        if (response === undefined)
+            throw new NodeUrlPackageSourceErrorV1("request_failed", "plugin package download failed");
+        if (response.status < 200 || response.status >= 300)
+            throw new NodeUrlPackageSourceErrorV1("request_failed", "plugin package download did not succeed");
+        if (response.body === null)
+            throw new NodeUrlPackageSourceErrorV1("request_failed", "plugin package response has no body");
+        const reader = response.body.getReader();
+        const chunks = [];
+        const hash = createHash("sha256");
+        let total = 0;
+        try {
+            for (;;) {
+                if (controller.signal.aborted)
+                    throw new NodeUrlPackageSourceErrorV1("cancelled", "plugin package download was cancelled");
+                const item = await reader.read();
+                if (item.done)
+                    break;
+                total += item.value.byteLength;
+                if (total > maxPackageBytes)
+                    throw new NodeUrlPackageSourceErrorV1("response_too_large", "plugin package exceeds the configured size limit");
+                hash.update(item.value);
+                chunks.push(item.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        if (controller.signal.aborted)
+            throw new NodeUrlPackageSourceErrorV1("cancelled", "plugin package download was cancelled");
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        const digestHex = hash.digest("hex");
+        if (input.expectedDigestHex !== undefined && digestHex !== input.expectedDigestHex)
+            throw new NodeUrlPackageSourceErrorV1("digest_mismatch", "plugin package bytes do not match the expected sha256 digest");
+        const fileName = current.pathname.split("/").pop();
+        const mediaType = detectPluginPackageMediaTypeV1(bytes, fileName === undefined || fileName.length === 0 ? undefined : fileName);
+        return { bytes, mediaType, digestHex };
+    }
+    finally {
+        clearTimeout(timeout);
+        input.signal?.removeEventListener("abort", abort);
+        await response?.body?.cancel().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=node-url-package-source.js.map

package/dist/plugins/ecosystem/node-url-package-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-url-package-source.js","sourceRoot":"","sources":["../../../src/plugins/ecosystem/node-url-package-source.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { detectPluginPackageMediaTypeV1, type PluginPackageMediaTypeV1 } from \"./node-package-media.ts\";\n\n/**\n * Custom-URL plugin package download (design §4.6 \"自定义 URL\" row). The URL\n * is the package file itself (zip/tgz); integrity is layered: a `#sha256:<hex>`\n * ref fragment becomes a strong digest check, otherwise TLS plus the double\n * manifest validation performed by the install host.\n */\n\nconst DEFAULT_TIMEOUT_MS_V1 = 30_000;\nconst MAX_TIMEOUT_MS_V1 = 120_000;\nconst DEFAULT_MAX_PACKAGE_BYTES_V1 = 128 * 1024 * 1024;\nconst MAX_PACKAGE_BYTES_V1 = 512 * 1024 * 1024;\nconst DEFAULT_REDIRECTS_V1 = 3;\nconst MAX_REDIRECTS_V1 = 5;\nconst REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);\n\nexport type NodeUrlPackageSourceErrorCodeV1 =\n\t| \"cancelled\"\n\t| \"invalid_configuration\"\n\t| \"invalid_url\"\n\t| \"request_failed\"\n\t| \"request_timed_out\"\n\t| \"response_too_large\"\n\t| \"digest_mismatch\";\n\nexport class NodeUrlPackageSourceErrorV1 extends Error {\n\treadonly code: NodeUrlPackageSourceErrorCodeV1;\n\n\tconstructor(code: NodeUrlPackageSourceErrorCodeV1, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"NodeUrlPackageSourceErrorV1\";\n\t\tthis.code = code;\n\t}\n}\n\nexport interface NodeUrlPackageSourceOptionsV1 {\n\t/** Real fetch or a deterministic test replacement. */\n\treadonly fetch?: typeof globalThis.fetch;\n\treadonly requestTimeoutMs?: number;\n\treadonly maxPackageBytes?: number;\n\treadonly maxRedirects?: number;\n\treadonly userAgent?: string;\n}\n\nexport interface NodeUrlPackageDownloadV1 {\n\treadonly bytes: Uint8Array;\n\treadonly mediaType: PluginPackageMediaTypeV1;\n\t/** sha256 hex of the downloaded bytes; always computed, verified when expected. */\n\treadonly digestHex: string;\n}\n\nfunction boundedPositive(value: number | undefined, fallback: number, maximum: number, label: string): number {\n\tconst result = value ?? fallback;\n\tif (!Number.isSafeInteger(result) || result <= 0 || result > maximum)\n\t\tthrow new NodeUrlPackageSourceErrorV1(\n\t\t\t\"invalid_configuration\",\n\t\t\t`${label} must be a positive integer at most ${maximum}`,\n\t\t);\n\treturn result;\n}\n\nfunction packageUrl(value: string): URL {\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(value);\n\t} catch {\n\t\tthrow new NodeUrlPackageSourceErrorV1(\"invalid_url\", \"plugin package URL is invalid\");\n\t}\n\tif (\n\t\t(parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") ||\n\t\tparsed.username !== \"\" ||\n\t\tparsed.password !== \"\"\n\t)\n\t\tthrow new NodeUrlPackageSourceErrorV1(\"invalid_url\", \"plugin package URL must use http(s) without credentials\");\n\tif (parsed.hash !== \"\")\n\t\tthrow new NodeUrlPackageSourceErrorV1(\"invalid_url\", \"plugin package URL must not include a fragment\");\n\treturn parsed;\n}\n\nfunction isAbortLike(error: unknown): boolean {\n\treturn error instanceof Error && (error.name === \"AbortError\" || error.name === \"AbortSignalError\");\n}\n\n/**\n * Download one package file over http(s). Redirects are followed manually and\n * every hop must again be a valid http(s) URL without credentials. When\n * `expectedDigestHex` is present the sha256 of the bytes must match exactly.\n */\nexport async function downloadNodeUrlPackageV1(\n\toptions: NodeUrlPackageSourceOptionsV1,\n\tinput: {\n\t\treadonly url: string;\n\t\treadonly expectedDigestHex?: string;\n\t\treadonly signal?: AbortSignal;\n\t},\n): Promise<NodeUrlPackageDownloadV1> {\n\tconst transport = options.fetch ?? globalThis.fetch;\n\tif (typeof transport !== \"function\")\n\t\tthrow new NodeUrlPackageSourceErrorV1(\"invalid_configuration\", \"Node fetch is unavailable\");\n\tconst timeoutMs = boundedPositive(\n\t\toptions.requestTimeoutMs,\n\t\tDEFAULT_TIMEOUT_MS_V1,\n\t\tMAX_TIMEOUT_MS_V1,\n\t\t\"requestTimeoutMs\",\n\t);\n\tconst maxPackageBytes = boundedPositive(\n\t\toptions.maxPackageBytes,\n\t\tDEFAULT_MAX_PACKAGE_BYTES_V1,\n\t\tMAX_PACKAGE_BYTES_V1,\n\t\t\"maxPackageBytes\",\n\t);\n\tconst maxRedirects = options.maxRedirects ?? DEFAULT_REDIRECTS_V1;\n\tif (!Number.isSafeInteger(maxRedirects) || maxRedirects < 0 || maxRedirects > MAX_REDIRECTS_V1)\n\t\tthrow new NodeUrlPackageSourceErrorV1(\n\t\t\t\"invalid_configuration\",\n\t\t\t`maxRedirects must be an integer between 0 and ${MAX_REDIRECTS_V1}`,\n\t\t);\n\tconst userAgent = options.userAgent ?? \"agent-forge-plugin-url/1\";\n\tif (userAgent.length === 0 || userAgent.length > 256 || /[\\r\\n]/u.test(userAgent))\n\t\tthrow new NodeUrlPackageSourceErrorV1(\"invalid_configuration\", \"userAgent is invalid\");\n\tif (input.expectedDigestHex !== undefined && !/^[0-9a-f]{64}$/u.test(input.expectedDigestHex))\n\t\tthrow new NodeUrlPackageSourceErrorV1(\"invalid_url\", \"expected sha256 digest is invalid\");\n\n\tlet current = packageUrl(input.url);\n\tlet response: Response | undefined;\n\tconst controller = new AbortController();\n\tlet timedOut = false;\n\tconst abort = () => controller.abort(input.signal?.reason);\n\tif (input.signal?.aborted === true) abort();\n\telse input.signal?.addEventListener(\"abort\", abort, { once: true });\n\tconst timeout = setTimeout(() => {\n\t\ttimedOut = true;\n\t\tcontroller.abort();\n\t}, timeoutMs);\n\ttry {\n\t\tfor (let redirect = 0; ; redirect += 1) {\n\t\t\tif (controller.signal.aborted)\n\t\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"cancelled\", \"plugin package download was cancelled\");\n\t\t\tlet hop: Response;\n\t\t\ttry {\n\t\t\t\thop = await transport(current.toString(), {\n\t\t\t\t\tmethod: \"GET\",\n\t\t\t\t\theaders: { accept: \"*/*\", \"user-agent\": userAgent },\n\t\t\t\t\tredirect: \"manual\",\n\t\t\t\t\tsignal: controller.signal,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tif (timedOut)\n\t\t\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"request_timed_out\", \"plugin package download timed out\");\n\t\t\t\tif (isAbortLike(error) || input.signal?.aborted === true)\n\t\t\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"cancelled\", \"plugin package download was cancelled\");\n\t\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"request_failed\", \"plugin package download failed\");\n\t\t\t}\n\t\t\tif (!REDIRECT_STATUS.has(hop.status)) {\n\t\t\t\tresponse = hop;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tconst location = hop.headers.get(\"location\");\n\t\t\tawait hop.body?.cancel().catch(() => undefined);\n\t\t\tif (location === null || redirect >= maxRedirects)\n\t\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"request_failed\", \"plugin package redirect limit exceeded\");\n\t\t\tcurrent = packageUrl(new URL(location, current).toString());\n\t\t}\n\t\tif (response === undefined)\n\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"request_failed\", \"plugin package download failed\");\n\t\tif (response.status < 200 || response.status >= 300)\n\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"request_failed\", \"plugin package download did not succeed\");\n\t\tif (response.body === null)\n\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"request_failed\", \"plugin package response has no body\");\n\t\tconst reader = response.body.getReader();\n\t\tconst chunks: Uint8Array[] = [];\n\t\tconst hash = createHash(\"sha256\");\n\t\tlet total = 0;\n\t\ttry {\n\t\t\tfor (;;) {\n\t\t\t\tif (controller.signal.aborted)\n\t\t\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"cancelled\", \"plugin package download was cancelled\");\n\t\t\t\tconst item = await reader.read();\n\t\t\t\tif (item.done) break;\n\t\t\t\ttotal += item.value.byteLength;\n\t\t\t\tif (total > maxPackageBytes)\n\t\t\t\t\tthrow new NodeUrlPackageSourceErrorV1(\n\t\t\t\t\t\t\"response_too_large\",\n\t\t\t\t\t\t\"plugin package exceeds the configured size limit\",\n\t\t\t\t\t);\n\t\t\t\thash.update(item.value);\n\t\t\t\tchunks.push(item.value);\n\t\t\t}\n\t\t} finally {\n\t\t\treader.releaseLock();\n\t\t}\n\t\tif (controller.signal.aborted)\n\t\t\tthrow new NodeUrlPackageSourceErrorV1(\"cancelled\", \"plugin package download was cancelled\");\n\t\tconst bytes = new Uint8Array(total);\n\t\tlet offset = 0;\n\t\tfor (const chunk of chunks) {\n\t\t\tbytes.set(chunk, offset);\n\t\t\toffset += chunk.byteLength;\n\t\t}\n\t\tconst digestHex = hash.digest(\"hex\");\n\t\tif (input.expectedDigestHex !== undefined && digestHex !== input.expectedDigestHex)\n\t\t\tthrow new NodeUrlPackageSourceErrorV1(\n\t\t\t\t\"digest_mismatch\",\n\t\t\t\t\"plugin package bytes do not match the expected sha256 digest\",\n\t\t\t);\n\t\tconst fileName = current.pathname.split(\"/\").pop();\n\t\tconst mediaType = detectPluginPackageMediaTypeV1(\n\t\t\tbytes,\n\t\t\tfileName === undefined || fileName.length === 0 ? undefined : fileName,\n\t\t);\n\t\treturn { bytes, mediaType, digestHex };\n\t} finally {\n\t\tclearTimeout(timeout);\n\t\tinput.signal?.removeEventListener(\"abort\", abort);\n\t\tawait response?.body?.cancel().catch(() => undefined);\n\t}\n}\n"]}

package/dist/plugins/ecosystem/plugin-acquisition.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Pure ref parsing for multi-source plugin package acquisition
+ * (`plugin install <ref>`, design `插件独立分发与启动装配设计.md` §4.6).
+ *
+ * Ref grammar and resolution priority:
+ * 1. local path (existing directory or `.zip`/`.tgz` file); a ref that exists
+ *    locally but is neither of those is an explicit `unsupported_local_ref`
+ *    error and never falls through to later priorities;
+ * 2. `github:<owner>/<repo>[@<tag>]` / `gitee:...` — resolved against the
+ *    matching release API by the acquisition host;
+ * 3. `http://`/`https://` URL, optionally with a `#sha256:<hex>` fragment that
+ *    is stripped before resolution and becomes a strong digest check;
+ * 4. anything else is an npm package ref (`@scope/name[@range]` or
+ *    `name[@range]`) with the minimal range subset `x.y.z`, `^x.y.z`,
+ *    `~x.y.z`, `latest`.
+ *
+ * Reserved scheme prefixes (`github:`, `gitee:`, and any other URL scheme) are
+ * never probed as local paths; every other ref is probed locally before npm
+ * name parsing. The CLI additionally routes only refs that cannot be legacy
+ * plugin IDs to this parser (see {@link isPluginAcquisitionRefTargetV1}).
+ */
+import type { PluginDistributionArtifactV1 } from "./distribution.ts";
+import type { PluginManifestV1 } from "./types.ts";
+export declare const MAX_PLUGIN_ACQUISITION_REF_CHARS_V1 = 2048;
+export declare const MAX_PLUGIN_ACQUISITION_NPM_NAME_CHARS_V1 = 214;
+/**
+ * Resolved acquisition package handed to an install transaction. The manifest
+ * identity is discovered from the package itself (`agent-forge.json`); the
+ * artifact is an opaque host-owned handle bound to the acquired bytes.
+ */
+export interface PluginAcquisitionPackageV1 {
+    readonly manifest: PluginManifestV1;
+    readonly manifestDigest: string;
+    /** Opaque source label persisted in the plugin state record (`npm:<host>`, `url:<host>`, `local:dir`, `local:file`). */
+    readonly source: string;
+    readonly artifact: PluginDistributionArtifactV1;
+    /** Release the artifact bytes; resolves `true` when nothing remains held. */
+    readonly release: () => Promise<boolean>;
+}
+export type PluginAcquisitionErrorCodeV1 = "invalid_ref" | "unsupported_local_ref" | "unsupported_scheme" | "invalid_digest_fragment" | "invalid_npm_ref" | "cancelled" | "download_failed" | "package_not_found" | "version_not_found" | "digest_mismatch" | "unsupported_media_type" | "package_invalid" | "budget_exceeded" | "release_not_found" | "release_asset_not_found" | "release_asset_ambiguous" | "rate_limited";
+export declare class PluginAcquisitionErrorV1 extends Error {
+    readonly code: PluginAcquisitionErrorCodeV1;
+    /** Optional factual suffix (asset candidates, rate-limit reset) appended to the static message. */
+    constructor(code: PluginAcquisitionErrorCodeV1, detail?: string);
+}
+/** A parsed acquisition ref. Digests are lowercase hex without an algorithm prefix. */
+export type PluginAcquisitionRefV1 = {
+    readonly kind: "local-path";
+    readonly path: string;
+} | {
+    readonly kind: "local-file";
+    readonly path: string;
+} | {
+    readonly kind: "url";
+    readonly url: string;
+    readonly expectedDigestHex?: string;
+} | {
+    readonly kind: "npm";
+    readonly name: string;
+    readonly range?: string;
+} | {
+    readonly kind: "github" | "gitee";
+    readonly owner: string;
+    readonly repo: string;
+    readonly tag?: string;
+    readonly expectedDigestHex?: string;
+};
+/** Host-injected local filesystem classification; it must not follow symlinks. */
+export interface PluginAcquisitionLocalProbeV1 {
+    readonly statLocalRef: (path: string) => "directory" | "file" | "other" | "missing";
+}
+/**
+ * Parse one acquisition ref. Priority: local (probe-injected) → github/gitee
+ * (recognized only) → http(s) URL → npm name. Throws
+ * {@link PluginAcquisitionErrorV1} for every unsupported or malformed ref.
+ */
+export declare function parsePluginAcquisitionRefV1(ref: string, probe: PluginAcquisitionLocalProbeV1): PluginAcquisitionRefV1;
+/**
+ * CLI routing predicate: legacy registry plugin IDs never contain `/`, `\`,
+ * `:`, `#`, a leading `@`, or an npm range suffix (`@^…`, `@~…`, `@latest`).
+ * Only targets with one of those markers enter acquisition ref parsing, so the
+ * existing `plugin install <pluginId>[@<exact version>]` registry path keeps
+ * its exact behavior. Note `name@1.2.3` (exact version) stays a registry
+ * identity; an unscoped npm package must be installed through a range suffix
+ * (`name@^1.2.3`, `name@latest`) or a scoped `@scope/name…` ref.
+ */
+export declare function isPluginAcquisitionRefTargetV1(target: string): boolean;
+//# sourceMappingURL=plugin-acquisition.d.ts.map

package/dist/plugins/ecosystem/plugin-acquisition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-acquisition.d.ts","sourceRoot":"","sources":["../../../src/plugins/ecosystem/plugin-acquisition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,eAAO,MAAM,mCAAmC,OAAO,CAAC;AACxD,eAAO,MAAM,wCAAwC,MAAM,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,wHAAwH;IACxH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;IAChD,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,MAAM,4BAA4B,GACrC,aAAa,GACb,uBAAuB,GACvB,oBAAoB,GACpB,yBAAyB,GACzB,iBAAiB,GACjB,WAAW,GACX,iBAAiB,GACjB,mBAAmB,GACnB,mBAAmB,GACnB,iBAAiB,GACjB,wBAAwB,GACxB,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,yBAAyB,GACzB,yBAAyB,GACzB,cAAc,CAAC;AAsBlB,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAE5C,mGAAmG;IACnG,YAAY,IAAI,EAAE,4BAA4B,EAAE,MAAM,CAAC,EAAE,MAAM,EAQ9D;CACD;AAED,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxE;IACA,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACnC,CAAC;AAEL,kFAAkF;AAClF,MAAM,WAAW,6BAA6B;IAC7C,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACpF;AAoFD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,6BAA6B,GAAG,sBAAsB,CAcrH;AAaD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAetE","sourcesContent":["/**\n * Pure ref parsing for multi-source plugin package acquisition\n * (`plugin install <ref>`, design `插件独立分发与启动装配设计.md` §4.6).\n *\n * Ref grammar and resolution priority:\n * 1. local path (existing directory or `.zip`/`.tgz` file); a ref that exists\n *    locally but is neither of those is an explicit `unsupported_local_ref`\n *    error and never falls through to later priorities;\n * 2. `github:<owner>/<repo>[@<tag>]` / `gitee:...` — resolved against the\n *    matching release API by the acquisition host;\n * 3. `http://`/`https://` URL, optionally with a `#sha256:<hex>` fragment that\n *    is stripped before resolution and becomes a strong digest check;\n * 4. anything else is an npm package ref (`@scope/name[@range]` or\n *    `name[@range]`) with the minimal range subset `x.y.z`, `^x.y.z`,\n *    `~x.y.z`, `latest`.\n *\n * Reserved scheme prefixes (`github:`, `gitee:`, and any other URL scheme) are\n * never probed as local paths; every other ref is probed locally before npm\n * name parsing. The CLI additionally routes only refs that cannot be legacy\n * plugin IDs to this parser (see {@link isPluginAcquisitionRefTargetV1}).\n */\n\nimport type { PluginDistributionArtifactV1 } from \"./distribution.ts\";\nimport type { PluginManifestV1 } from \"./types.ts\";\n\nexport const MAX_PLUGIN_ACQUISITION_REF_CHARS_V1 = 2048;\nexport const MAX_PLUGIN_ACQUISITION_NPM_NAME_CHARS_V1 = 214;\n\n/**\n * Resolved acquisition package handed to an install transaction. The manifest\n * identity is discovered from the package itself (`agent-forge.json`); the\n * artifact is an opaque host-owned handle bound to the acquired bytes.\n */\nexport interface PluginAcquisitionPackageV1 {\n\treadonly manifest: PluginManifestV1;\n\treadonly manifestDigest: string;\n\t/** Opaque source label persisted in the plugin state record (`npm:<host>`, `url:<host>`, `local:dir`, `local:file`). */\n\treadonly source: string;\n\treadonly artifact: PluginDistributionArtifactV1;\n\t/** Release the artifact bytes; resolves `true` when nothing remains held. */\n\treadonly release: () => Promise<boolean>;\n}\n\nexport type PluginAcquisitionErrorCodeV1 =\n\t| \"invalid_ref\"\n\t| \"unsupported_local_ref\"\n\t| \"unsupported_scheme\"\n\t| \"invalid_digest_fragment\"\n\t| \"invalid_npm_ref\"\n\t| \"cancelled\"\n\t| \"download_failed\"\n\t| \"package_not_found\"\n\t| \"version_not_found\"\n\t| \"digest_mismatch\"\n\t| \"unsupported_media_type\"\n\t| \"package_invalid\"\n\t| \"budget_exceeded\"\n\t| \"release_not_found\"\n\t| \"release_asset_not_found\"\n\t| \"release_asset_ambiguous\"\n\t| \"rate_limited\";\n\nconst ACQUISITION_ERROR_MESSAGES_V1: Readonly<Record<PluginAcquisitionErrorCodeV1, string>> = {\n\tinvalid_ref: \"Plugin ref is invalid\",\n\tunsupported_local_ref: \"Local plugin ref exists but is neither a directory nor a .zip/.tgz file\",\n\tunsupported_scheme: \"Plugin ref URL scheme is not supported\",\n\tinvalid_digest_fragment: \"Plugin ref #sha256 digest fragment is invalid\",\n\tinvalid_npm_ref: \"Plugin npm package ref is invalid\",\n\tcancelled: \"Plugin package acquisition was cancelled\",\n\tdownload_failed: \"Plugin package download failed\",\n\tpackage_not_found: \"Plugin npm package was not found on the registry\",\n\tversion_not_found: \"No npm package version matches the requested range\",\n\tdigest_mismatch: \"Plugin package bytes do not match the expected digest\",\n\tunsupported_media_type: \"Plugin package bytes are neither a zip nor a tgz\",\n\tpackage_invalid: \"Plugin package contents are invalid\",\n\tbudget_exceeded: \"Plugin package exceeds the configured size budget\",\n\trelease_not_found: \"Plugin release was not found\",\n\trelease_asset_not_found: \"Plugin release has no .zip/.tgz asset\",\n\trelease_asset_ambiguous: \"Plugin release has multiple .zip/.tgz assets\",\n\trate_limited: \"Plugin release API rate limit was exceeded\",\n};\n\nexport class PluginAcquisitionErrorV1 extends Error {\n\treadonly code: PluginAcquisitionErrorCodeV1;\n\n\t/** Optional factual suffix (asset candidates, rate-limit reset) appended to the static message. */\n\tconstructor(code: PluginAcquisitionErrorCodeV1, detail?: string) {\n\t\tsuper(\n\t\t\tdetail === undefined || detail.length === 0\n\t\t\t\t? ACQUISITION_ERROR_MESSAGES_V1[code]\n\t\t\t\t: `${ACQUISITION_ERROR_MESSAGES_V1[code]}: ${detail}`,\n\t\t);\n\t\tthis.name = \"PluginAcquisitionErrorV1\";\n\t\tthis.code = code;\n\t}\n}\n\n/** A parsed acquisition ref. Digests are lowercase hex without an algorithm prefix. */\nexport type PluginAcquisitionRefV1 =\n\t| { readonly kind: \"local-path\"; readonly path: string }\n\t| { readonly kind: \"local-file\"; readonly path: string }\n\t| { readonly kind: \"url\"; readonly url: string; readonly expectedDigestHex?: string }\n\t| { readonly kind: \"npm\"; readonly name: string; readonly range?: string }\n\t| {\n\t\t\treadonly kind: \"github\" | \"gitee\";\n\t\t\treadonly owner: string;\n\t\t\treadonly repo: string;\n\t\t\treadonly tag?: string;\n\t\t\treadonly expectedDigestHex?: string;\n\t  };\n\n/** Host-injected local filesystem classification; it must not follow symlinks. */\nexport interface PluginAcquisitionLocalProbeV1 {\n\treadonly statLocalRef: (path: string) => \"directory\" | \"file\" | \"other\" | \"missing\";\n}\n\nconst DIGEST_FRAGMENT_SUFFIX_V1 = /^#sha256:([0-9a-fA-F]{64})$/u;\n\nfunction boundedRef(ref: string): string {\n\tif (\n\t\ttypeof ref !== \"string\" ||\n\t\tref.length === 0 ||\n\t\tref.length > MAX_PLUGIN_ACQUISITION_REF_CHARS_V1 ||\n\t\t/[\\u0000-\\u001f\\s]/u.test(ref)\n\t)\n\t\tthrow new PluginAcquisitionErrorV1(\"invalid_ref\");\n\treturn ref;\n}\n\n/** Split and validate a trailing `#sha256:<64 hex>` fragment from a scheme ref. */\nfunction splitDigestFragment(ref: string): { readonly value: string; readonly digestHex?: string } {\n\tconst hash = ref.lastIndexOf(\"#\");\n\tif (hash < 0) return { value: ref };\n\tconst fragment = ref.slice(hash);\n\tconst match = DIGEST_FRAGMENT_SUFFIX_V1.exec(fragment);\n\tif (match === null) throw new PluginAcquisitionErrorV1(\"invalid_digest_fragment\");\n\treturn { value: ref.slice(0, hash), digestHex: match[1]!.toLowerCase() };\n}\n\nfunction ownerRepoTag(kind: \"github\" | \"gitee\", value: string, digestHex?: string): PluginAcquisitionRefV1 {\n\tconst match =\n\t\t/^([A-Za-z0-9][A-Za-z0-9._-]{0,99})\\/([A-Za-z0-9][A-Za-z0-9._-]{0,99})(?:@([A-Za-z0-9][A-Za-z0-9._+-]{0,127}))?$/u.exec(\n\t\t\tvalue,\n\t\t);\n\tif (match === null) throw new PluginAcquisitionErrorV1(\"invalid_ref\");\n\treturn {\n\t\tkind,\n\t\towner: match[1]!,\n\t\trepo: match[2]!,\n\t\t...(match[3] === undefined ? {} : { tag: match[3] }),\n\t\t...(digestHex === undefined ? {} : { expectedDigestHex: digestHex }),\n\t};\n}\n\nfunction parseUrlRef(value: string, digestHex?: string): PluginAcquisitionRefV1 {\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(value);\n\t} catch {\n\t\tthrow new PluginAcquisitionErrorV1(\"invalid_ref\");\n\t}\n\tif (parsed.username !== \"\" || parsed.password !== \"\") throw new PluginAcquisitionErrorV1(\"invalid_ref\");\n\tif (parsed.hash !== \"\") throw new PluginAcquisitionErrorV1(\"invalid_digest_fragment\");\n\treturn {\n\t\tkind: \"url\",\n\t\turl: parsed.toString(),\n\t\t...(digestHex === undefined ? {} : { expectedDigestHex: digestHex }),\n\t};\n}\n\nconst NPM_RANGE_V1 = /^(?:latest|[~^]?\\d+\\.\\d+\\.\\d+(?:[-+][0-9A-Za-z.-]+)?)$/u;\nconst NPM_NAME_V1 = /^@?[a-z0-9][a-z0-9-._]*(?:\\/[a-z0-9][a-z0-9-._]*)?$/u;\n\nfunction parseNpmRef(ref: string): PluginAcquisitionRefV1 {\n\tconst at = ref.lastIndexOf(\"@\");\n\tconst name = at > 0 ? ref.slice(0, at) : ref;\n\tconst range = at > 0 ? ref.slice(at + 1) : undefined;\n\tif (\n\t\tname.length === 0 ||\n\t\tname.length > MAX_PLUGIN_ACQUISITION_NPM_NAME_CHARS_V1 ||\n\t\t!NPM_NAME_V1.test(name) ||\n\t\t(name.startsWith(\"@\") && !name.includes(\"/\")) ||\n\t\t(!name.startsWith(\"@\") && name.includes(\"/\"))\n\t)\n\t\tthrow new PluginAcquisitionErrorV1(\"invalid_npm_ref\");\n\tif (range !== undefined && !NPM_RANGE_V1.test(range)) throw new PluginAcquisitionErrorV1(\"invalid_npm_ref\");\n\treturn {\n\t\tkind: \"npm\",\n\t\tname,\n\t\t...(range === undefined ? {} : { range }),\n\t};\n}\n\nfunction isLocalPackageFile(path: string): boolean {\n\tconst value = path.toLowerCase();\n\treturn value.endsWith(\".zip\") || value.endsWith(\".tgz\") || value.endsWith(\".tar.gz\");\n}\n\n/**\n * Parse one acquisition ref. Priority: local (probe-injected) → github/gitee\n * (recognized only) → http(s) URL → npm name. Throws\n * {@link PluginAcquisitionErrorV1} for every unsupported or malformed ref.\n */\nexport function parsePluginAcquisitionRefV1(ref: string, probe: PluginAcquisitionLocalProbeV1): PluginAcquisitionRefV1 {\n\tconst value = boundedRef(ref);\n\t// Windows drive-letter paths must not be mistaken for URL schemes.\n\tif (/^[a-zA-Z]:[\\\\/]/u.test(value)) return localRef(value, probe);\n\tconst scheme = /^([a-zA-Z][a-zA-Z\\d+.-]*):/u.exec(value);\n\tif (scheme !== null) {\n\t\tconst prefix = scheme[1]!.toLowerCase();\n\t\tconst stripped = splitDigestFragment(value);\n\t\tif (prefix === \"github\" || prefix === \"gitee\")\n\t\t\treturn ownerRepoTag(prefix, stripped.value.slice(prefix.length + 1), stripped.digestHex);\n\t\tif (prefix === \"http\" || prefix === \"https\") return parseUrlRef(stripped.value, stripped.digestHex);\n\t\tthrow new PluginAcquisitionErrorV1(\"unsupported_scheme\");\n\t}\n\treturn localRef(value, probe);\n}\n\nfunction localRef(value: string, probe: PluginAcquisitionLocalProbeV1): PluginAcquisitionRefV1 {\n\tconst stat = probe.statLocalRef(value);\n\tif (stat === \"directory\") return { kind: \"local-path\", path: value };\n\tif (stat === \"file\") {\n\t\tif (!isLocalPackageFile(value)) throw new PluginAcquisitionErrorV1(\"unsupported_local_ref\");\n\t\treturn { kind: \"local-file\", path: value };\n\t}\n\tif (stat === \"other\") throw new PluginAcquisitionErrorV1(\"unsupported_local_ref\");\n\treturn parseNpmRef(value);\n}\n\n/**\n * CLI routing predicate: legacy registry plugin IDs never contain `/`, `\\`,\n * `:`, `#`, a leading `@`, or an npm range suffix (`@^…`, `@~…`, `@latest`).\n * Only targets with one of those markers enter acquisition ref parsing, so the\n * existing `plugin install <pluginId>[@<exact version>]` registry path keeps\n * its exact behavior. Note `name@1.2.3` (exact version) stays a registry\n * identity; an unscoped npm package must be installed through a range suffix\n * (`name@^1.2.3`, `name@latest`) or a scoped `@scope/name…` ref.\n */\nexport function isPluginAcquisitionRefTargetV1(target: string): boolean {\n\tif (typeof target !== \"string\" || target.length === 0) return false;\n\tif (target.startsWith(\"@\")) return true;\n\tif (/^[a-zA-Z]:[\\\\/]/u.test(target)) return true;\n\tif (target.startsWith(\"/\") || target.startsWith(\"\\\\\")) return true;\n\tif (target.startsWith(\"./\") || target.startsWith(\".\\\\\")) return true;\n\tif (target.startsWith(\"../\") || target.startsWith(\"..\\\\\")) return true;\n\tif (/[:#]/u.test(target)) return true;\n\tif (/[\\\\/]/u.test(target)) return true;\n\tconst at = target.lastIndexOf(\"@\");\n\tif (at > 0) {\n\t\tconst suffix = target.slice(at + 1);\n\t\tif (suffix === \"latest\" || suffix.startsWith(\"^\") || suffix.startsWith(\"~\")) return true;\n\t}\n\treturn false;\n}\n"]}

package/dist/plugins/ecosystem/plugin-acquisition.js

@@ -0,0 +1,197 @@
+/**
+ * Pure ref parsing for multi-source plugin package acquisition
+ * (`plugin install <ref>`, design `插件独立分发与启动装配设计.md` §4.6).
+ *
+ * Ref grammar and resolution priority:
+ * 1. local path (existing directory or `.zip`/`.tgz` file); a ref that exists
+ *    locally but is neither of those is an explicit `unsupported_local_ref`
+ *    error and never falls through to later priorities;
+ * 2. `github:<owner>/<repo>[@<tag>]` / `gitee:...` — resolved against the
+ *    matching release API by the acquisition host;
+ * 3. `http://`/`https://` URL, optionally with a `#sha256:<hex>` fragment that
+ *    is stripped before resolution and becomes a strong digest check;
+ * 4. anything else is an npm package ref (`@scope/name[@range]` or
+ *    `name[@range]`) with the minimal range subset `x.y.z`, `^x.y.z`,
+ *    `~x.y.z`, `latest`.
+ *
+ * Reserved scheme prefixes (`github:`, `gitee:`, and any other URL scheme) are
+ * never probed as local paths; every other ref is probed locally before npm
+ * name parsing. The CLI additionally routes only refs that cannot be legacy
+ * plugin IDs to this parser (see {@link isPluginAcquisitionRefTargetV1}).
+ */
+export const MAX_PLUGIN_ACQUISITION_REF_CHARS_V1 = 2048;
+export const MAX_PLUGIN_ACQUISITION_NPM_NAME_CHARS_V1 = 214;
+const ACQUISITION_ERROR_MESSAGES_V1 = {
+    invalid_ref: "Plugin ref is invalid",
+    unsupported_local_ref: "Local plugin ref exists but is neither a directory nor a .zip/.tgz file",
+    unsupported_scheme: "Plugin ref URL scheme is not supported",
+    invalid_digest_fragment: "Plugin ref #sha256 digest fragment is invalid",
+    invalid_npm_ref: "Plugin npm package ref is invalid",
+    cancelled: "Plugin package acquisition was cancelled",
+    download_failed: "Plugin package download failed",
+    package_not_found: "Plugin npm package was not found on the registry",
+    version_not_found: "No npm package version matches the requested range",
+    digest_mismatch: "Plugin package bytes do not match the expected digest",
+    unsupported_media_type: "Plugin package bytes are neither a zip nor a tgz",
+    package_invalid: "Plugin package contents are invalid",
+    budget_exceeded: "Plugin package exceeds the configured size budget",
+    release_not_found: "Plugin release was not found",
+    release_asset_not_found: "Plugin release has no .zip/.tgz asset",
+    release_asset_ambiguous: "Plugin release has multiple .zip/.tgz assets",
+    rate_limited: "Plugin release API rate limit was exceeded",
+};
+export class PluginAcquisitionErrorV1 extends Error {
+    code;
+    /** Optional factual suffix (asset candidates, rate-limit reset) appended to the static message. */
+    constructor(code, detail) {
+        super(detail === undefined || detail.length === 0
+            ? ACQUISITION_ERROR_MESSAGES_V1[code]
+            : `${ACQUISITION_ERROR_MESSAGES_V1[code]}: ${detail}`);
+        this.name = "PluginAcquisitionErrorV1";
+        this.code = code;
+    }
+}
+const DIGEST_FRAGMENT_SUFFIX_V1 = /^#sha256:([0-9a-fA-F]{64})$/u;
+function boundedRef(ref) {
+    if (typeof ref !== "string" ||
+        ref.length === 0 ||
+        ref.length > MAX_PLUGIN_ACQUISITION_REF_CHARS_V1 ||
+        /[\u0000-\u001f\s]/u.test(ref))
+        throw new PluginAcquisitionErrorV1("invalid_ref");
+    return ref;
+}
+/** Split and validate a trailing `#sha256:<64 hex>` fragment from a scheme ref. */
+function splitDigestFragment(ref) {
+    const hash = ref.lastIndexOf("#");
+    if (hash < 0)
+        return { value: ref };
+    const fragment = ref.slice(hash);
+    const match = DIGEST_FRAGMENT_SUFFIX_V1.exec(fragment);
+    if (match === null)
+        throw new PluginAcquisitionErrorV1("invalid_digest_fragment");
+    return { value: ref.slice(0, hash), digestHex: match[1].toLowerCase() };
+}
+function ownerRepoTag(kind, value, digestHex) {
+    const match = /^([A-Za-z0-9][A-Za-z0-9._-]{0,99})\/([A-Za-z0-9][A-Za-z0-9._-]{0,99})(?:@([A-Za-z0-9][A-Za-z0-9._+-]{0,127}))?$/u.exec(value);
+    if (match === null)
+        throw new PluginAcquisitionErrorV1("invalid_ref");
+    return {
+        kind,
+        owner: match[1],
+        repo: match[2],
+        ...(match[3] === undefined ? {} : { tag: match[3] }),
+        ...(digestHex === undefined ? {} : { expectedDigestHex: digestHex }),
+    };
+}
+function parseUrlRef(value, digestHex) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new PluginAcquisitionErrorV1("invalid_ref");
+    }
+    if (parsed.username !== "" || parsed.password !== "")
+        throw new PluginAcquisitionErrorV1("invalid_ref");
+    if (parsed.hash !== "")
+        throw new PluginAcquisitionErrorV1("invalid_digest_fragment");
+    return {
+        kind: "url",
+        url: parsed.toString(),
+        ...(digestHex === undefined ? {} : { expectedDigestHex: digestHex }),
+    };
+}
+const NPM_RANGE_V1 = /^(?:latest|[~^]?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/u;
+const NPM_NAME_V1 = /^@?[a-z0-9][a-z0-9-._]*(?:\/[a-z0-9][a-z0-9-._]*)?$/u;
+function parseNpmRef(ref) {
+    const at = ref.lastIndexOf("@");
+    const name = at > 0 ? ref.slice(0, at) : ref;
+    const range = at > 0 ? ref.slice(at + 1) : undefined;
+    if (name.length === 0 ||
+        name.length > MAX_PLUGIN_ACQUISITION_NPM_NAME_CHARS_V1 ||
+        !NPM_NAME_V1.test(name) ||
+        (name.startsWith("@") && !name.includes("/")) ||
+        (!name.startsWith("@") && name.includes("/")))
+        throw new PluginAcquisitionErrorV1("invalid_npm_ref");
+    if (range !== undefined && !NPM_RANGE_V1.test(range))
+        throw new PluginAcquisitionErrorV1("invalid_npm_ref");
+    return {
+        kind: "npm",
+        name,
+        ...(range === undefined ? {} : { range }),
+    };
+}
+function isLocalPackageFile(path) {
+    const value = path.toLowerCase();
+    return value.endsWith(".zip") || value.endsWith(".tgz") || value.endsWith(".tar.gz");
+}
+/**
+ * Parse one acquisition ref. Priority: local (probe-injected) → github/gitee
+ * (recognized only) → http(s) URL → npm name. Throws
+ * {@link PluginAcquisitionErrorV1} for every unsupported or malformed ref.
+ */
+export function parsePluginAcquisitionRefV1(ref, probe) {
+    const value = boundedRef(ref);
+    // Windows drive-letter paths must not be mistaken for URL schemes.
+    if (/^[a-zA-Z]:[\\/]/u.test(value))
+        return localRef(value, probe);
+    const scheme = /^([a-zA-Z][a-zA-Z\d+.-]*):/u.exec(value);
+    if (scheme !== null) {
+        const prefix = scheme[1].toLowerCase();
+        const stripped = splitDigestFragment(value);
+        if (prefix === "github" || prefix === "gitee")
+            return ownerRepoTag(prefix, stripped.value.slice(prefix.length + 1), stripped.digestHex);
+        if (prefix === "http" || prefix === "https")
+            return parseUrlRef(stripped.value, stripped.digestHex);
+        throw new PluginAcquisitionErrorV1("unsupported_scheme");
+    }
+    return localRef(value, probe);
+}
+function localRef(value, probe) {
+    const stat = probe.statLocalRef(value);
+    if (stat === "directory")
+        return { kind: "local-path", path: value };
+    if (stat === "file") {
+        if (!isLocalPackageFile(value))
+            throw new PluginAcquisitionErrorV1("unsupported_local_ref");
+        return { kind: "local-file", path: value };
+    }
+    if (stat === "other")
+        throw new PluginAcquisitionErrorV1("unsupported_local_ref");
+    return parseNpmRef(value);
+}
+/**
+ * CLI routing predicate: legacy registry plugin IDs never contain `/`, `\`,
+ * `:`, `#`, a leading `@`, or an npm range suffix (`@^…`, `@~…`, `@latest`).
+ * Only targets with one of those markers enter acquisition ref parsing, so the
+ * existing `plugin install <pluginId>[@<exact version>]` registry path keeps
+ * its exact behavior. Note `name@1.2.3` (exact version) stays a registry
+ * identity; an unscoped npm package must be installed through a range suffix
+ * (`name@^1.2.3`, `name@latest`) or a scoped `@scope/name…` ref.
+ */
+export function isPluginAcquisitionRefTargetV1(target) {
+    if (typeof target !== "string" || target.length === 0)
+        return false;
+    if (target.startsWith("@"))
+        return true;
+    if (/^[a-zA-Z]:[\\/]/u.test(target))
+        return true;
+    if (target.startsWith("/") || target.startsWith("\\"))
+        return true;
+    if (target.startsWith("./") || target.startsWith(".\\"))
+        return true;
+    if (target.startsWith("../") || target.startsWith("..\\"))
+        return true;
+    if (/[:#]/u.test(target))
+        return true;
+    if (/[\\/]/u.test(target))
+        return true;
+    const at = target.lastIndexOf("@");
+    if (at > 0) {
+        const suffix = target.slice(at + 1);
+        if (suffix === "latest" || suffix.startsWith("^") || suffix.startsWith("~"))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=plugin-acquisition.js.map

package/dist/plugins/ecosystem/plugin-acquisition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-acquisition.js","sourceRoot":"","sources":["../../../src/plugins/ecosystem/plugin-acquisition.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure ref parsing for multi-source plugin package acquisition\n * (`plugin install <ref>`, design `插件独立分发与启动装配设计.md` §4.6).\n *\n * Ref grammar and resolution priority:\n * 1. local path (existing directory or `.zip`/`.tgz` file); a ref that exists\n *    locally but is neither of those is an explicit `unsupported_local_ref`\n *    error and never falls through to later priorities;\n * 2. `github:<owner>/<repo>[@<tag>]` / `gitee:...` — resolved against the\n *    matching release API by the acquisition host;\n * 3. `http://`/`https://` URL, optionally with a `#sha256:<hex>` fragment that\n *    is stripped before resolution and becomes a strong digest check;\n * 4. anything else is an npm package ref (`@scope/name[@range]` or\n *    `name[@range]`) with the minimal range subset `x.y.z`, `^x.y.z`,\n *    `~x.y.z`, `latest`.\n *\n * Reserved scheme prefixes (`github:`, `gitee:`, and any other URL scheme) are\n * never probed as local paths; every other ref is probed locally before npm\n * name parsing. The CLI additionally routes only refs that cannot be legacy\n * plugin IDs to this parser (see {@link isPluginAcquisitionRefTargetV1}).\n */\n\nimport type { PluginDistributionArtifactV1 } from \"./distribution.ts\";\nimport type { PluginManifestV1 } from \"./types.ts\";\n\nexport const MAX_PLUGIN_ACQUISITION_REF_CHARS_V1 = 2048;\nexport const MAX_PLUGIN_ACQUISITION_NPM_NAME_CHARS_V1 = 214;\n\n/**\n * Resolved acquisition package handed to an install transaction. The manifest\n * identity is discovered from the package itself (`agent-forge.json`); the\n * artifact is an opaque host-owned handle bound to the acquired bytes.\n */\nexport interface PluginAcquisitionPackageV1 {\n\treadonly manifest: PluginManifestV1;\n\treadonly manifestDigest: string;\n\t/** Opaque source label persisted in the plugin state record (`npm:<host>`, `url:<host>`, `local:dir`, `local:file`). */\n\treadonly source: string;\n\treadonly artifact: PluginDistributionArtifactV1;\n\t/** Release the artifact bytes; resolves `true` when nothing remains held. */\n\treadonly release: () => Promise<boolean>;\n}\n\nexport type PluginAcquisitionErrorCodeV1 =\n\t| \"invalid_ref\"\n\t| \"unsupported_local_ref\"\n\t| \"unsupported_scheme\"\n\t| \"invalid_digest_fragment\"\n\t| \"invalid_npm_ref\"\n\t| \"cancelled\"\n\t| \"download_failed\"\n\t| \"package_not_found\"\n\t| \"version_not_found\"\n\t| \"digest_mismatch\"\n\t| \"unsupported_media_type\"\n\t| \"package_invalid\"\n\t| \"budget_exceeded\"\n\t| \"release_not_found\"\n\t| \"release_asset_not_found\"\n\t| \"release_asset_ambiguous\"\n\t| \"rate_limited\";\n\nconst ACQUISITION_ERROR_MESSAGES_V1: Readonly<Record<PluginAcquisitionErrorCodeV1, string>> = {\n\tinvalid_ref: \"Plugin ref is invalid\",\n\tunsupported_local_ref: \"Local plugin ref exists but is neither a directory nor a .zip/.tgz file\",\n\tunsupported_scheme: \"Plugin ref URL scheme is not supported\",\n\tinvalid_digest_fragment: \"Plugin ref #sha256 digest fragment is invalid\",\n\tinvalid_npm_ref: \"Plugin npm package ref is invalid\",\n\tcancelled: \"Plugin package acquisition was cancelled\",\n\tdownload_failed: \"Plugin package download failed\",\n\tpackage_not_found: \"Plugin npm package was not found on the registry\",\n\tversion_not_found: \"No npm package version matches the requested range\",\n\tdigest_mismatch: \"Plugin package bytes do not match the expected digest\",\n\tunsupported_media_type: \"Plugin package bytes are neither a zip nor a tgz\",\n\tpackage_invalid: \"Plugin package contents are invalid\",\n\tbudget_exceeded: \"Plugin package exceeds the configured size budget\",\n\trelease_not_found: \"Plugin release was not found\",\n\trelease_asset_not_found: \"Plugin release has no .zip/.tgz asset\",\n\trelease_asset_ambiguous: \"Plugin release has multiple .zip/.tgz assets\",\n\trate_limited: \"Plugin release API rate limit was exceeded\",\n};\n\nexport class PluginAcquisitionErrorV1 extends Error {\n\treadonly code: PluginAcquisitionErrorCodeV1;\n\n\t/** Optional factual suffix (asset candidates, rate-limit reset) appended to the static message. */\n\tconstructor(code: PluginAcquisitionErrorCodeV1, detail?: string) {\n\t\tsuper(\n\t\t\tdetail === undefined || detail.length === 0\n\t\t\t\t? ACQUISITION_ERROR_MESSAGES_V1[code]\n\t\t\t\t: `${ACQUISITION_ERROR_MESSAGES_V1[code]}: ${detail}`,\n\t\t);\n\t\tthis.name = \"PluginAcquisitionErrorV1\";\n\t\tthis.code = code;\n\t}\n}\n\n/** A parsed acquisition ref. Digests are lowercase hex without an algorithm prefix. */\nexport type PluginAcquisitionRefV1 =\n\t| { readonly kind: \"local-path\"; readonly path: string }\n\t| { readonly kind: \"local-file\"; readonly path: string }\n\t| { readonly kind: \"url\"; readonly url: string; readonly expectedDigestHex?: string }\n\t| { readonly kind: \"npm\"; readonly name: string; readonly range?: string }\n\t| {\n\t\t\treadonly kind: \"github\" | \"gitee\";\n\t\t\treadonly owner: string;\n\t\t\treadonly repo: string;\n\t\t\treadonly tag?: string;\n\t\t\treadonly expectedDigestHex?: string;\n\t  };\n\n/** Host-injected local filesystem classification; it must not follow symlinks. */\nexport interface PluginAcquisitionLocalProbeV1 {\n\treadonly statLocalRef: (path: string) => \"directory\" | \"file\" | \"other\" | \"missing\";\n}\n\nconst DIGEST_FRAGMENT_SUFFIX_V1 = /^#sha256:([0-9a-fA-F]{64})$/u;\n\nfunction boundedRef(ref: string): string {\n\tif (\n\t\ttypeof ref !== \"string\" ||\n\t\tref.length === 0 ||\n\t\tref.length > MAX_PLUGIN_ACQUISITION_REF_CHARS_V1 ||\n\t\t/[\\u0000-\\u001f\\s]/u.test(ref)\n\t)\n\t\tthrow new PluginAcquisitionErrorV1(\"invalid_ref\");\n\treturn ref;\n}\n\n/** Split and validate a trailing `#sha256:<64 hex>` fragment from a scheme ref. */\nfunction splitDigestFragment(ref: string): { readonly value: string; readonly digestHex?: string } {\n\tconst hash = ref.lastIndexOf(\"#\");\n\tif (hash < 0) return { value: ref };\n\tconst fragment = ref.slice(hash);\n\tconst match = DIGEST_FRAGMENT_SUFFIX_V1.exec(fragment);\n\tif (match === null) throw new PluginAcquisitionErrorV1(\"invalid_digest_fragment\");\n\treturn { value: ref.slice(0, hash), digestHex: match[1]!.toLowerCase() };\n}\n\nfunction ownerRepoTag(kind: \"github\" | \"gitee\", value: string, digestHex?: string): PluginAcquisitionRefV1 {\n\tconst match =\n\t\t/^([A-Za-z0-9][A-Za-z0-9._-]{0,99})\\/([A-Za-z0-9][A-Za-z0-9._-]{0,99})(?:@([A-Za-z0-9][A-Za-z0-9._+-]{0,127}))?$/u.exec(\n\t\t\tvalue,\n\t\t);\n\tif (match === null) throw new PluginAcquisitionErrorV1(\"invalid_ref\");\n\treturn {\n\t\tkind,\n\t\towner: match[1]!,\n\t\trepo: match[2]!,\n\t\t...(match[3] === undefined ? {} : { tag: match[3] }),\n\t\t...(digestHex === undefined ? {} : { expectedDigestHex: digestHex }),\n\t};\n}\n\nfunction parseUrlRef(value: string, digestHex?: string): PluginAcquisitionRefV1 {\n\tlet parsed: URL;\n\ttry {\n\t\tparsed = new URL(value);\n\t} catch {\n\t\tthrow new PluginAcquisitionErrorV1(\"invalid_ref\");\n\t}\n\tif (parsed.username !== \"\" || parsed.password !== \"\") throw new PluginAcquisitionErrorV1(\"invalid_ref\");\n\tif (parsed.hash !== \"\") throw new PluginAcquisitionErrorV1(\"invalid_digest_fragment\");\n\treturn {\n\t\tkind: \"url\",\n\t\turl: parsed.toString(),\n\t\t...(digestHex === undefined ? {} : { expectedDigestHex: digestHex }),\n\t};\n}\n\nconst NPM_RANGE_V1 = /^(?:latest|[~^]?\\d+\\.\\d+\\.\\d+(?:[-+][0-9A-Za-z.-]+)?)$/u;\nconst NPM_NAME_V1 = /^@?[a-z0-9][a-z0-9-._]*(?:\\/[a-z0-9][a-z0-9-._]*)?$/u;\n\nfunction parseNpmRef(ref: string): PluginAcquisitionRefV1 {\n\tconst at = ref.lastIndexOf(\"@\");\n\tconst name = at > 0 ? ref.slice(0, at) : ref;\n\tconst range = at > 0 ? ref.slice(at + 1) : undefined;\n\tif (\n\t\tname.length === 0 ||\n\t\tname.length > MAX_PLUGIN_ACQUISITION_NPM_NAME_CHARS_V1 ||\n\t\t!NPM_NAME_V1.test(name) ||\n\t\t(name.startsWith(\"@\") && !name.includes(\"/\")) ||\n\t\t(!name.startsWith(\"@\") && name.includes(\"/\"))\n\t)\n\t\tthrow new PluginAcquisitionErrorV1(\"invalid_npm_ref\");\n\tif (range !== undefined && !NPM_RANGE_V1.test(range)) throw new PluginAcquisitionErrorV1(\"invalid_npm_ref\");\n\treturn {\n\t\tkind: \"npm\",\n\t\tname,\n\t\t...(range === undefined ? {} : { range }),\n\t};\n}\n\nfunction isLocalPackageFile(path: string): boolean {\n\tconst value = path.toLowerCase();\n\treturn value.endsWith(\".zip\") || value.endsWith(\".tgz\") || value.endsWith(\".tar.gz\");\n}\n\n/**\n * Parse one acquisition ref. Priority: local (probe-injected) → github/gitee\n * (recognized only) → http(s) URL → npm name. Throws\n * {@link PluginAcquisitionErrorV1} for every unsupported or malformed ref.\n */\nexport function parsePluginAcquisitionRefV1(ref: string, probe: PluginAcquisitionLocalProbeV1): PluginAcquisitionRefV1 {\n\tconst value = boundedRef(ref);\n\t// Windows drive-letter paths must not be mistaken for URL schemes.\n\tif (/^[a-zA-Z]:[\\\\/]/u.test(value)) return localRef(value, probe);\n\tconst scheme = /^([a-zA-Z][a-zA-Z\\d+.-]*):/u.exec(value);\n\tif (scheme !== null) {\n\t\tconst prefix = scheme[1]!.toLowerCase();\n\t\tconst stripped = splitDigestFragment(value);\n\t\tif (prefix === \"github\" || prefix === \"gitee\")\n\t\t\treturn ownerRepoTag(prefix, stripped.value.slice(prefix.length + 1), stripped.digestHex);\n\t\tif (prefix === \"http\" || prefix === \"https\") return parseUrlRef(stripped.value, stripped.digestHex);\n\t\tthrow new PluginAcquisitionErrorV1(\"unsupported_scheme\");\n\t}\n\treturn localRef(value, probe);\n}\n\nfunction localRef(value: string, probe: PluginAcquisitionLocalProbeV1): PluginAcquisitionRefV1 {\n\tconst stat = probe.statLocalRef(value);\n\tif (stat === \"directory\") return { kind: \"local-path\", path: value };\n\tif (stat === \"file\") {\n\t\tif (!isLocalPackageFile(value)) throw new PluginAcquisitionErrorV1(\"unsupported_local_ref\");\n\t\treturn { kind: \"local-file\", path: value };\n\t}\n\tif (stat === \"other\") throw new PluginAcquisitionErrorV1(\"unsupported_local_ref\");\n\treturn parseNpmRef(value);\n}\n\n/**\n * CLI routing predicate: legacy registry plugin IDs never contain `/`, `\\`,\n * `:`, `#`, a leading `@`, or an npm range suffix (`@^…`, `@~…`, `@latest`).\n * Only targets with one of those markers enter acquisition ref parsing, so the\n * existing `plugin install <pluginId>[@<exact version>]` registry path keeps\n * its exact behavior. Note `name@1.2.3` (exact version) stays a registry\n * identity; an unscoped npm package must be installed through a range suffix\n * (`name@^1.2.3`, `name@latest`) or a scoped `@scope/name…` ref.\n */\nexport function isPluginAcquisitionRefTargetV1(target: string): boolean {\n\tif (typeof target !== \"string\" || target.length === 0) return false;\n\tif (target.startsWith(\"@\")) return true;\n\tif (/^[a-zA-Z]:[\\\\/]/u.test(target)) return true;\n\tif (target.startsWith(\"/\") || target.startsWith(\"\\\\\")) return true;\n\tif (target.startsWith(\"./\") || target.startsWith(\".\\\\\")) return true;\n\tif (target.startsWith(\"../\") || target.startsWith(\"..\\\\\")) return true;\n\tif (/[:#]/u.test(target)) return true;\n\tif (/[\\\\/]/u.test(target)) return true;\n\tconst at = target.lastIndexOf(\"@\");\n\tif (at > 0) {\n\t\tconst suffix = target.slice(at + 1);\n\t\tif (suffix === \"latest\" || suffix.startsWith(\"^\") || suffix.startsWith(\"~\")) return true;\n\t}\n\treturn false;\n}\n"]}

package/dist/plugins/ecosystem/plugin-bootstrap.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Startup plugin bootstrap orchestrator (design
+ * `插件独立分发与启动装配设计.md` §4.4, §0.7). Pure injectable decision loop
+ * over the frozen factory manifest: every entry is compared against the
+ * locally resolved active installations and only missing plugins are handed
+ * to the npm install dependency — bootstrap never acquires through any other
+ * source.
+ *
+ * Coverage rules (G5): an existing active installation is never replaced. A
+ * satisfied range is skipped silently (zero acquisition calls, G3); an
+ * unsatisfied one produces a diagnostic with a manual install command and no
+ * automatic replacement. Failure semantics (G4): one plugin's install
+ * failure is recorded and the loop continues; the run itself never throws.
+ * All effects live behind the injected dependencies, so the loop is fully
+ * deterministic under mocks.
+ */
+import type { PluginBootstrapFactoryEntryV1 } from "./bootstrap-factory-manifest.ts";
+export declare const PLUGIN_BOOTSTRAP_VERSION_V1: 1;
+/** Read-only local lookup of active installation versions (never networked). */
+export type PluginBootstrapListActiveV1 = (input: {
+    readonly signal?: AbortSignal;
+}) => Promise<ReadonlyMap<string, string>>;
+/** npm-only install action; resolves with the installed version and source label. */
+export type PluginBootstrapInstallFromNpmV1 = (input: {
+    readonly npmName: string;
+    readonly range?: string;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly pluginVersion: string;
+    readonly source: string;
+}>;
+export interface PluginBootstrapDepsV1 {
+    readonly listActive: PluginBootstrapListActiveV1;
+    readonly installFromNpm: PluginBootstrapInstallFromNpmV1;
+    /** Deterministic clock for the observed duration; defaults to Date.now. */
+    readonly now?: () => number;
+    /** Cooperative cancellation; checked before each manifest entry. */
+    readonly signal?: AbortSignal;
+}
+export type PluginBootstrapActionStatusV1 = "skipped" | "diagnosed" | "installed" | "failed";
+export type PluginBootstrapActionReasonV1 = "satisfies_range" | "range_not_satisfied" | "installed" | "install_failed";
+/** One per-entry outcome; the version fields carry what each status observed. */
+export interface PluginBootstrapActionV1 {
+    readonly pluginId: string;
+    readonly status: PluginBootstrapActionStatusV1;
+    readonly reason: PluginBootstrapActionReasonV1;
+    readonly npmName: string;
+    readonly range?: string;
+    /** Active version that decided a skipped/diagnosed outcome. */
+    readonly activeVersion?: string;
+    /** Version reported by the install action. */
+    readonly installedVersion?: string;
+    /** npm source label reported by the install action. */
+    readonly source?: string;
+    /** Acquisition or install failure code for failed actions. */
+    readonly errorCode?: string;
+}
+export type PluginBootstrapDiagnosticCodeV1 = "range_not_satisfied" | "install_failed" | "list_active_failed" | "cancelled" | "bootstrap_failed";
+export interface PluginBootstrapDiagnosticV1 {
+    readonly code: PluginBootstrapDiagnosticCodeV1;
+    readonly message: string;
+    readonly pluginId?: string;
+}
+export type PluginBootstrapStatusV1 = "succeeded" | "degraded" | "failed";
+export interface PluginBootstrapResultV1 {
+    readonly version: typeof PLUGIN_BOOTSTRAP_VERSION_V1;
+    /** Aggregated outcome: failed > degraded (diagnosed entries) > succeeded. */
+    readonly status: PluginBootstrapStatusV1;
+    readonly actions: readonly PluginBootstrapActionV1[];
+    readonly diagnostics: readonly PluginBootstrapDiagnosticV1[];
+    readonly durationMs: number;
+}
+/** Executable repair command for diagnostics (G4/G5 remediation hint). */
+export declare function pluginBootstrapInstallCommandV1(entry: {
+    readonly npmName: string;
+    readonly range?: string;
+}): string;
+/**
+ * Run the bootstrap decision loop. An empty manifest short-circuits before
+ * any dependency is touched, so the factory-empty S1-c2 state performs zero
+ * reads on real startups.
+ */
+export declare function runPluginBootstrapV1(input: {
+    readonly manifest: readonly PluginBootstrapFactoryEntryV1[];
+    readonly deps: PluginBootstrapDepsV1;
+}): Promise<PluginBootstrapResultV1>;
+//# sourceMappingURL=plugin-bootstrap.d.ts.map