@pixelzx/genesis 2026.6.29 → 2026.7.8

package/dist/clawbot-cli-CcTWZznd.js

@@ -0,0 +1,9 @@
+import { t as formatDocsLink } from "./links-C1-jbHJx.js";
+import { r as theme } from "./theme-DD6pQv2_.js";
+import { t as registerQrCli } from "./qr-cli-hTiyQbbK.js";
+//#region src/cli/clawbot-cli.ts
+function registerClawbotCli(program) {
+	registerQrCli(program.command("clawbot").description("Legacy clawbot command aliases").addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/clawbot", "genesis.pixelzx.com/docs/cli/clawbot")}\n`));
+}
+//#endregion
+export { registerClawbotCli };

package/dist/clawhub-Dg91MiOl.js

@@ -0,0 +1,400 @@
+import { i as formatErrorMessage } from "./errors-CufR9eHH.js";
+import { c as normalizeOptionalString } from "./string-coerce-DPP_aYVc.js";
+import { o as resolveCompatibilityHostVersion } from "./version-qod78efn.js";
+import { n as installPluginFromArchive } from "./install-CYvCH-s3.js";
+import { i as DEFAULT_MAX_EXTRACTED_BYTES, r as DEFAULT_MAX_ENTRY_BYTES } from "./archive-CKUwqCyM.js";
+import { a as fetchClawHubPackageVersion, c as normalizeClawHubSha256Integrity, d as satisfiesGatewayMinimum, f as satisfiesPluginApiRange, h as parseClawHubPluginSpec, i as fetchClawHubPackageDetail, n as downloadClawHubPackageArchive, s as normalizeClawHubSha256Hex, t as ClawHubRequestError, u as resolveLatestVersionFromPackage } from "./clawhub-CFJ2HwYe.js";
+import fs from "node:fs/promises";
+import { createHash } from "node:crypto";
+import JSZip from "jszip";
+//#region src/plugins/clawhub.ts
+const CLAWHUB_INSTALL_ERROR_CODE = {
+	INVALID_SPEC: "invalid_spec",
+	PACKAGE_NOT_FOUND: "package_not_found",
+	VERSION_NOT_FOUND: "version_not_found",
+	NO_INSTALLABLE_VERSION: "no_installable_version",
+	SKILL_PACKAGE: "skill_package",
+	UNSUPPORTED_FAMILY: "unsupported_family",
+	PRIVATE_PACKAGE: "private_package",
+	INCOMPATIBLE_PLUGIN_API: "incompatible_plugin_api",
+	INCOMPATIBLE_GATEWAY: "incompatible_gateway",
+	MISSING_ARCHIVE_INTEGRITY: "missing_archive_integrity",
+	ARCHIVE_INTEGRITY_MISMATCH: "archive_integrity_mismatch"
+};
+const CLAWHUB_GENERATED_ARCHIVE_METADATA_FILE = "_meta.json";
+function formatClawHubSpecifier(params) {
+	return `clawhub:${params.name}${params.version ? `@${params.version}` : ""}`;
+}
+function buildClawHubInstallFailure(error, code) {
+	return {
+		ok: false,
+		error,
+		code
+	};
+}
+function isClawHubInstallFailure(value) {
+	return Boolean(value && typeof value === "object" && "ok" in value && value.ok === false && "error" in value);
+}
+function mapClawHubRequestError(error, context) {
+	if (error instanceof ClawHubRequestError && error.status === 404) {
+		if (context.stage === "package") return buildClawHubInstallFailure("Package not found on ClawHub.", CLAWHUB_INSTALL_ERROR_CODE.PACKAGE_NOT_FOUND);
+		return buildClawHubInstallFailure(`Version not found on ClawHub: ${context.name}@${context.version ?? "unknown"}.`, CLAWHUB_INSTALL_ERROR_CODE.VERSION_NOT_FOUND);
+	}
+	return buildClawHubInstallFailure(formatErrorMessage(error));
+}
+function resolveRequestedVersion(params) {
+	if (params.requestedVersion) return params.requestedVersion;
+	return resolveLatestVersionFromPackage(params.detail);
+}
+function readTrimmedString(value) {
+	return normalizeOptionalString(value) ?? null;
+}
+function normalizeClawHubRelativePath(value) {
+	if (typeof value !== "string" || value.length === 0) return null;
+	if (value.trim() !== value || value.includes("\\")) return null;
+	if (value.startsWith("/")) return null;
+	if (value.split("/").some((segment) => segment.length === 0 || segment === "." || segment === "..")) return null;
+	return value;
+}
+function describeInvalidClawHubRelativePath(value) {
+	if (typeof value !== "string") return `non-string value of type ${typeof value}`;
+	if (value.length === 0) return "empty string";
+	if (value.trim() !== value) return `path "${value}" has leading or trailing whitespace`;
+	if (value.includes("\\")) return `path "${value}" contains backslashes`;
+	if (value.startsWith("/")) return `path "${value}" is absolute`;
+	const segments = value.split("/");
+	if (segments.some((segment) => segment.length === 0)) return `path "${value}" contains an empty segment`;
+	if (segments.some((segment) => segment === "." || segment === "..")) return `path "${value}" contains dot segments`;
+	return `path "${value}" failed validation for an unknown reason`;
+}
+function describeInvalidClawHubSha256(value) {
+	if (typeof value !== "string") return `non-string value of type ${typeof value}`;
+	if (value.length === 0) return "empty string";
+	if (value.trim().length === 0) return "whitespace-only string";
+	return `value "${value}" is not a 64-character hexadecimal SHA-256 digest`;
+}
+function resolveClawHubArchiveVerification(versionDetail, packageName, version) {
+	const sha256hashValue = versionDetail.version?.sha256hash;
+	const sha256hash = readTrimmedString(sha256hashValue);
+	const integrity = sha256hash ? normalizeClawHubSha256Integrity(sha256hash) : null;
+	if (integrity) return {
+		ok: true,
+		verification: {
+			kind: "archive-integrity",
+			integrity
+		}
+	};
+	if (sha256hashValue !== void 0 && sha256hashValue !== null) return buildClawHubInstallFailure(`ClawHub version metadata for "${packageName}@${version}" has an invalid sha256hash (${typeof sha256hashValue === "string" && sha256hashValue.trim().length === 0 ? "empty string" : typeof sha256hashValue === "string" ? `unrecognized value "${sha256hashValue.trim()}"` : `non-string value of type ${typeof sha256hashValue}`}).`, CLAWHUB_INSTALL_ERROR_CODE.MISSING_ARCHIVE_INTEGRITY);
+	const files = versionDetail.version?.files;
+	if (!Array.isArray(files) || files.length === 0) return {
+		ok: true,
+		verification: null
+	};
+	const normalizedFiles = [];
+	const seenPaths = /* @__PURE__ */ new Set();
+	for (const [index, file] of files.entries()) {
+		if (!file || typeof file !== "object") return buildClawHubInstallFailure(`ClawHub version metadata for "${packageName}@${version}" has an invalid files[${index}] entry (expected an object, got ${file === null ? "null" : typeof file}).`, CLAWHUB_INSTALL_ERROR_CODE.MISSING_ARCHIVE_INTEGRITY);
+		const fileRecord = file;
+		const filePath = normalizeClawHubRelativePath(fileRecord.path);
+		const sha256Value = readTrimmedString(fileRecord.sha256);
+		const sha256 = sha256Value ? normalizeClawHubSha256Hex(sha256Value) : null;
+		if (!filePath) return buildClawHubInstallFailure(`ClawHub version metadata for "${packageName}@${version}" has an invalid files[${index}].path (${describeInvalidClawHubRelativePath(fileRecord.path)}).`, CLAWHUB_INSTALL_ERROR_CODE.MISSING_ARCHIVE_INTEGRITY);
+		if (filePath === CLAWHUB_GENERATED_ARCHIVE_METADATA_FILE) return buildClawHubInstallFailure(`ClawHub version metadata for "${packageName}@${version}" must not include generated file "${filePath}" in files[].`, CLAWHUB_INSTALL_ERROR_CODE.MISSING_ARCHIVE_INTEGRITY);
+		if (!sha256) return buildClawHubInstallFailure(`ClawHub version metadata for "${packageName}@${version}" has an invalid files[${index}].sha256 (${describeInvalidClawHubSha256(fileRecord.sha256)}).`, CLAWHUB_INSTALL_ERROR_CODE.MISSING_ARCHIVE_INTEGRITY);
+		if (seenPaths.has(filePath)) return buildClawHubInstallFailure(`ClawHub version metadata for "${packageName}@${version}" has duplicate files[] path "${filePath}".`, CLAWHUB_INSTALL_ERROR_CODE.MISSING_ARCHIVE_INTEGRITY);
+		seenPaths.add(filePath);
+		normalizedFiles.push({
+			path: filePath,
+			sha256
+		});
+	}
+	return {
+		ok: true,
+		verification: {
+			kind: "file-list",
+			files: normalizedFiles
+		}
+	};
+}
+async function readLimitedClawHubArchiveEntry(entry, limits, handlers) {
+	const hintedSize = entry._data?.uncompressedSize;
+	if (typeof hintedSize === "number" && Number.isFinite(hintedSize) && hintedSize > limits.maxEntryBytes) return buildClawHubInstallFailure(`ClawHub archive fallback verification rejected "${entry.name}" because it exceeds the per-file size limit.`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+	let entryBytes = 0;
+	return await new Promise((resolve) => {
+		let settled = false;
+		const stream = entry.nodeStream("nodebuffer");
+		stream.on("data", (chunk) => {
+			if (settled) return;
+			const buffer = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+			entryBytes += buffer.byteLength;
+			if (entryBytes > limits.maxEntryBytes) {
+				settled = true;
+				stream.destroy?.();
+				resolve(buildClawHubInstallFailure(`ClawHub archive fallback verification rejected "${entry.name}" because it exceeds the per-file size limit.`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH));
+				return;
+			}
+			if (!limits.addArchiveBytes(buffer.byteLength)) {
+				settled = true;
+				stream.destroy?.();
+				resolve(buildClawHubInstallFailure("ClawHub archive fallback verification exceeded the total extracted-size limit.", CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH));
+				return;
+			}
+			handlers.onChunk(buffer);
+		});
+		stream.once("end", () => {
+			if (settled) return;
+			settled = true;
+			resolve(handlers.onEnd());
+		});
+		stream.once("error", (error) => {
+			if (settled) return;
+			settled = true;
+			resolve(buildClawHubInstallFailure(error instanceof Error ? error.message : String(error), CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH));
+		});
+	});
+}
+async function readClawHubArchiveEntryBuffer(entry, limits) {
+	const chunks = [];
+	return await readLimitedClawHubArchiveEntry(entry, limits, {
+		onChunk(buffer) {
+			chunks.push(buffer);
+		},
+		onEnd() {
+			return Buffer.concat(chunks);
+		}
+	});
+}
+async function hashClawHubArchiveEntry(entry, limits) {
+	const digest = createHash("sha256");
+	return await readLimitedClawHubArchiveEntry(entry, limits, {
+		onChunk(buffer) {
+			digest.update(buffer);
+		},
+		onEnd() {
+			return digest.digest("hex");
+		}
+	});
+}
+function validateClawHubArchiveMetaJson(params) {
+	let parsed;
+	try {
+		parsed = JSON.parse(params.bytes.toString("utf8"));
+	} catch {
+		return buildClawHubInstallFailure(`ClawHub archive contents do not match files[] metadata for "${params.packageName}@${params.version}": _meta.json is not valid JSON.`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+	}
+	if (!parsed || typeof parsed !== "object") return buildClawHubInstallFailure(`ClawHub archive contents do not match files[] metadata for "${params.packageName}@${params.version}": _meta.json is not a JSON object.`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+	const record = parsed;
+	if (record.slug !== params.packageName) return buildClawHubInstallFailure(`ClawHub archive contents do not match files[] metadata for "${params.packageName}@${params.version}": _meta.json slug does not match the package name.`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+	if (record.version !== params.version) return buildClawHubInstallFailure(`ClawHub archive contents do not match files[] metadata for "${params.packageName}@${params.version}": _meta.json version does not match the package version.`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+	return null;
+}
+async function verifyClawHubArchiveFiles(params) {
+	try {
+		if ((await fs.stat(params.archivePath)).size > 268435456) return buildClawHubInstallFailure("ClawHub archive fallback verification rejected the downloaded archive because it exceeds the ZIP archive size limit.", CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+		const archiveBytes = await fs.readFile(params.archivePath);
+		const zip = await JSZip.loadAsync(archiveBytes);
+		const actualFiles = /* @__PURE__ */ new Map();
+		const validatedGeneratedPaths = /* @__PURE__ */ new Set();
+		let entryCount = 0;
+		let extractedBytes = 0;
+		const addArchiveBytes = (bytes) => {
+			extractedBytes += bytes;
+			return extractedBytes <= DEFAULT_MAX_EXTRACTED_BYTES;
+		};
+		for (const entry of Object.values(zip.files)) {
+			entryCount += 1;
+			if (entryCount > 5e4) return buildClawHubInstallFailure("ClawHub archive fallback verification exceeded the archive entry limit.", CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+			if (entry.dir) continue;
+			const relativePath = normalizeClawHubRelativePath(entry.name);
+			if (!relativePath) return buildClawHubInstallFailure(`ClawHub archive contents do not match files[] metadata for "${params.packageName}@${params.packageVersion}": invalid package file path "${entry.name}" (${describeInvalidClawHubRelativePath(entry.name)}).`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+			if (relativePath === CLAWHUB_GENERATED_ARCHIVE_METADATA_FILE) {
+				const metaResult = await readClawHubArchiveEntryBuffer(entry, {
+					maxEntryBytes: DEFAULT_MAX_ENTRY_BYTES,
+					addArchiveBytes
+				});
+				if (isClawHubInstallFailure(metaResult)) return metaResult;
+				const metaFailure = validateClawHubArchiveMetaJson({
+					packageName: params.packageName,
+					version: params.packageVersion,
+					bytes: metaResult
+				});
+				if (metaFailure) return metaFailure;
+				validatedGeneratedPaths.add(relativePath);
+				continue;
+			}
+			const sha256 = await hashClawHubArchiveEntry(entry, {
+				maxEntryBytes: DEFAULT_MAX_ENTRY_BYTES,
+				addArchiveBytes
+			});
+			if (typeof sha256 !== "string") return sha256;
+			actualFiles.set(relativePath, sha256);
+		}
+		for (const file of params.files) {
+			const actualSha256 = actualFiles.get(file.path);
+			if (!actualSha256) return buildClawHubInstallFailure(`ClawHub archive contents do not match files[] metadata for "${params.packageName}@${params.packageVersion}": missing "${file.path}".`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+			if (actualSha256 !== file.sha256) return buildClawHubInstallFailure(`ClawHub archive contents do not match files[] metadata for "${params.packageName}@${params.packageVersion}": expected ${file.path} to hash to ${file.sha256}, got ${actualSha256}.`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+			actualFiles.delete(file.path);
+		}
+		const unexpectedFile = [...actualFiles.keys()].toSorted()[0];
+		if (unexpectedFile) return buildClawHubInstallFailure(`ClawHub archive contents do not match files[] metadata for "${params.packageName}@${params.packageVersion}": unexpected file "${unexpectedFile}".`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+		return {
+			ok: true,
+			validatedGeneratedPaths: [...validatedGeneratedPaths].toSorted()
+		};
+	} catch {
+		return buildClawHubInstallFailure("ClawHub archive fallback verification failed while reading the downloaded archive.", CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+	}
+}
+async function resolveCompatiblePackageVersion(params) {
+	const requestedVersion = resolveRequestedVersion(params);
+	if (!requestedVersion) return buildClawHubInstallFailure(`ClawHub package "${params.detail.package?.name ?? "unknown"}" has no installable version.`, CLAWHUB_INSTALL_ERROR_CODE.NO_INSTALLABLE_VERSION);
+	let versionDetail;
+	try {
+		versionDetail = await fetchClawHubPackageVersion({
+			name: params.detail.package?.name ?? "",
+			version: requestedVersion,
+			baseUrl: params.baseUrl,
+			token: params.token
+		});
+	} catch (error) {
+		return mapClawHubRequestError(error, {
+			stage: "version",
+			name: params.detail.package?.name ?? "unknown",
+			version: requestedVersion
+		});
+	}
+	const resolvedVersion = versionDetail.version?.version ?? requestedVersion;
+	if (params.detail.package?.family === "skill") return {
+		ok: true,
+		version: resolvedVersion,
+		compatibility: versionDetail.version?.compatibility ?? params.detail.package?.compatibility ?? null,
+		verification: null
+	};
+	const verificationState = resolveClawHubArchiveVerification(versionDetail, params.detail.package?.name ?? "unknown", resolvedVersion);
+	if (!verificationState.ok) return verificationState;
+	return {
+		ok: true,
+		version: resolvedVersion,
+		compatibility: versionDetail.version?.compatibility ?? params.detail.package?.compatibility ?? null,
+		verification: verificationState.verification
+	};
+}
+function validateClawHubPluginPackage(params) {
+	const pkg = params.detail.package;
+	if (!pkg) return buildClawHubInstallFailure("Package not found on ClawHub.", CLAWHUB_INSTALL_ERROR_CODE.PACKAGE_NOT_FOUND);
+	if (pkg.family === "skill") return buildClawHubInstallFailure(`"${pkg.name}" is a skill. Use "genesis skills install ${pkg.name}" instead.`, CLAWHUB_INSTALL_ERROR_CODE.SKILL_PACKAGE);
+	if (pkg.family !== "code-plugin" && pkg.family !== "bundle-plugin") return buildClawHubInstallFailure(`Unsupported ClawHub package family: ${String(pkg.family)}`, CLAWHUB_INSTALL_ERROR_CODE.UNSUPPORTED_FAMILY);
+	if (pkg.channel === "private") return buildClawHubInstallFailure(`"${pkg.name}" is private on ClawHub and cannot be installed anonymously.`, CLAWHUB_INSTALL_ERROR_CODE.PRIVATE_PACKAGE);
+	const compatibility = params.compatibility;
+	const runtimeVersion = params.runtimeVersion;
+	if (compatibility?.pluginApiRange && !satisfiesPluginApiRange(runtimeVersion, compatibility.pluginApiRange)) return buildClawHubInstallFailure(`Plugin "${pkg.name}" requires plugin API ${compatibility.pluginApiRange}, but this Genesis runtime exposes ${runtimeVersion}.`, CLAWHUB_INSTALL_ERROR_CODE.INCOMPATIBLE_PLUGIN_API);
+	if (compatibility?.minGatewayVersion && !satisfiesGatewayMinimum(runtimeVersion, compatibility.minGatewayVersion)) return buildClawHubInstallFailure(`Plugin "${pkg.name}" requires Genesis >=${compatibility.minGatewayVersion}, but this host is ${runtimeVersion}.`, CLAWHUB_INSTALL_ERROR_CODE.INCOMPATIBLE_GATEWAY);
+	return null;
+}
+function logClawHubPackageSummary(params) {
+	const pkg = params.detail.package;
+	if (!pkg) return;
+	const verification = pkg.verification?.tier ? ` verification=${pkg.verification.tier}` : "";
+	params.logger?.info?.(`ClawHub ${pkg.family} ${pkg.name}@${params.version} channel=${pkg.channel}${verification}`);
+	const compatibilityParts = [params.compatibility?.pluginApiRange ? `pluginApi=${params.compatibility.pluginApiRange}` : null, params.compatibility?.minGatewayVersion ? `minGateway=${params.compatibility.minGatewayVersion}` : null].filter(Boolean);
+	if (compatibilityParts.length > 0) params.logger?.info?.(`Compatibility: ${compatibilityParts.join(" ")}`);
+	if (pkg.channel !== "official") params.logger?.warn?.(`ClawHub package "${pkg.name}" is ${pkg.channel}; review source and verification before enabling.`);
+}
+async function installPluginFromClawHub(params) {
+	const parsed = parseClawHubPluginSpec(params.spec);
+	if (!parsed?.name) return buildClawHubInstallFailure(`invalid ClawHub plugin spec: ${params.spec}`, CLAWHUB_INSTALL_ERROR_CODE.INVALID_SPEC);
+	params.logger?.info?.(`Resolving ${formatClawHubSpecifier(parsed)}…`);
+	let detail;
+	try {
+		detail = await fetchClawHubPackageDetail({
+			name: parsed.name,
+			baseUrl: params.baseUrl,
+			token: params.token
+		});
+	} catch (error) {
+		return mapClawHubRequestError(error, {
+			stage: "package",
+			name: parsed.name
+		});
+	}
+	const versionState = await resolveCompatiblePackageVersion({
+		detail,
+		requestedVersion: parsed.version,
+		baseUrl: params.baseUrl,
+		token: params.token
+	});
+	if (!versionState.ok) return versionState;
+	const runtimeVersion = resolveCompatibilityHostVersion();
+	const validationFailure = validateClawHubPluginPackage({
+		detail,
+		compatibility: versionState.compatibility,
+		runtimeVersion
+	});
+	if (validationFailure) return validationFailure;
+	if (!versionState.verification) return buildClawHubInstallFailure(`ClawHub version metadata for "${parsed.name}@${versionState.version}" is missing sha256hash and usable files[] metadata for fallback archive verification.`, CLAWHUB_INSTALL_ERROR_CODE.MISSING_ARCHIVE_INTEGRITY);
+	const canonicalPackageName = detail.package?.name ?? parsed.name;
+	logClawHubPackageSummary({
+		detail,
+		version: versionState.version,
+		compatibility: versionState.compatibility,
+		logger: params.logger
+	});
+	let archive;
+	try {
+		archive = await downloadClawHubPackageArchive({
+			name: parsed.name,
+			version: versionState.version,
+			baseUrl: params.baseUrl,
+			token: params.token
+		});
+	} catch (error) {
+		return buildClawHubInstallFailure(formatErrorMessage(error));
+	}
+	try {
+		if (versionState.verification.kind === "archive-integrity") {
+			if (archive.integrity !== versionState.verification.integrity) return buildClawHubInstallFailure(`ClawHub archive integrity mismatch for "${parsed.name}@${versionState.version}": expected ${versionState.verification.integrity}, got ${archive.integrity}.`, CLAWHUB_INSTALL_ERROR_CODE.ARCHIVE_INTEGRITY_MISMATCH);
+		} else {
+			const validatedPaths = versionState.verification.files.map((file) => file.path).toSorted().join(", ");
+			const fallbackVerification = await verifyClawHubArchiveFiles({
+				archivePath: archive.archivePath,
+				packageName: canonicalPackageName,
+				packageVersion: versionState.version,
+				files: versionState.verification.files
+			});
+			if (!fallbackVerification.ok) return fallbackVerification;
+			const validatedGeneratedPaths = fallbackVerification.validatedGeneratedPaths.length > 0 ? ` Validated generated metadata files present in archive: ${fallbackVerification.validatedGeneratedPaths.join(", ")} (JSON parse plus slug/version match only).` : "";
+			params.logger?.warn?.(`ClawHub package "${canonicalPackageName}@${versionState.version}" is missing sha256hash; falling back to files[] verification. Validated files: ${validatedPaths}.${validatedGeneratedPaths}`);
+		}
+		params.logger?.info?.(`Downloading ${detail.package?.family === "bundle-plugin" ? "bundle" : "plugin"} ${parsed.name}@${versionState.version} from ClawHub…`);
+		const installResult = await installPluginFromArchive({
+			archivePath: archive.archivePath,
+			dangerouslyForceUnsafeInstall: params.dangerouslyForceUnsafeInstall,
+			logger: params.logger,
+			mode: params.mode,
+			dryRun: params.dryRun,
+			expectedPluginId: params.expectedPluginId
+		});
+		if (!installResult.ok) return installResult;
+		const pkg = detail.package;
+		const clawhubFamily = pkg.family === "code-plugin" || pkg.family === "bundle-plugin" ? pkg.family : null;
+		if (!clawhubFamily) return buildClawHubInstallFailure(`Unsupported ClawHub package family: ${pkg.family}`, CLAWHUB_INSTALL_ERROR_CODE.UNSUPPORTED_FAMILY);
+		return {
+			...installResult,
+			packageName: parsed.name,
+			clawhub: {
+				source: "clawhub",
+				clawhubUrl: normalizeOptionalString(params.baseUrl) || normalizeOptionalString(process.env.GENESIS_CLAWHUB_URL) || "https://clawhub.ai",
+				clawhubPackage: parsed.name,
+				clawhubFamily,
+				clawhubChannel: pkg.channel,
+				version: installResult.version ?? versionState.version,
+				integrity: archive.integrity,
+				resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+			}
+		};
+	} finally {
+		await archive.cleanup().catch(() => void 0);
+	}
+}
+//#endregion
+export { formatClawHubSpecifier as n, installPluginFromClawHub as r, CLAWHUB_INSTALL_ERROR_CODE as t };

package/dist/cli/daemon-cli.js

@@ -1,8 +1,8 @@
 // Legacy shim for pre-tsdown update-cli imports.
-import * as daemonCli from "../daemon-cli-DT5GXTxV.js";
+import * as daemonCli from "../daemon-cli-CCC_5IkN.js";
 import * as daemonCliRunners0 from "../install.runtime-BmPESpWr.js";
-import * as daemonCliRunners1 from "../lifecycle.runtime-1wfzPGwQ.js";
-import * as daemonCliRunners2 from "../status.runtime-DYi_nOHT.js";
+import * as daemonCliRunners1 from "../lifecycle.runtime-3bkEDR0o.js";
+import * as daemonCliRunners2 from "../status.runtime-DdcRs0mC.js";
 export const registerDaemonCli = daemonCli.t;
 export const runDaemonInstall = daemonCliRunners0.runDaemonInstall;
 export const runDaemonRestart = daemonCliRunners1.runDaemonRestart;

package/dist/cli-B9pz-wec.js

@@ -0,0 +1,2 @@
+import { i as registerPluginCliCommandsFromValidatedConfig, n as loadValidatedConfigForPluginRegistration, t as getPluginCliCommandDescriptors } from "./cli-BDqmMCNa.js";
+export { getPluginCliCommandDescriptors, loadValidatedConfigForPluginRegistration, registerPluginCliCommandsFromValidatedConfig };

package/dist/cli-BDqmMCNa.js

@@ -0,0 +1,219 @@
+import { a as loadConfig, u as readConfigFileSnapshot } from "./io-Cy5vajWd.js";
+import "./config-DYHZ3jG1.js";
+import { i as GATEWAY_CLIENT_NAMES, r as GATEWAY_CLIENT_MODES } from "./client-info-CjxzJxIU.js";
+import { t as resolveManifestActivationPluginIds } from "./activation-planner-CL9cBJNP.js";
+import { n as loadGenesisPluginCliRegistry, r as loadGenesisPlugins } from "./loader-C6YNVFIJ.js";
+import { n as collectUniqueCommandDescriptors } from "./command-descriptor-utils-AegwfgPx.js";
+import { i as resolvePluginRuntimeLoadContext, r as createPluginRuntimeLoaderLogger, t as buildPluginRuntimeLoadOptions } from "./load-context-CSuoyE4e.js";
+import { r as callGateway } from "./call-DgFhP0IB.js";
+import { a as registerLazyCommandGroup, n as getCommandGroupNames, o as removeCommandGroupNames, t as findCommandGroupEntry } from "./register-command-groups-BjShh-Db.js";
+import { randomUUID } from "node:crypto";
+//#region src/plugins/cli-gateway-nodes-runtime.ts
+function createPluginCliGatewayNodesRuntime() {
+	return {
+		async list(params) {
+			const payload = await callGateway({
+				method: "node.list",
+				params: {},
+				clientName: GATEWAY_CLIENT_NAMES.CLI,
+				mode: GATEWAY_CLIENT_MODES.CLI
+			});
+			const nodes = Array.isArray(payload?.nodes) ? payload.nodes : [];
+			return { nodes: params?.connected === true ? nodes.filter((node) => node !== null && typeof node === "object" && node.connected === true) : nodes };
+		},
+		async invoke(params) {
+			return await callGateway({
+				method: "node.invoke",
+				params: {
+					nodeId: params.nodeId,
+					command: params.command,
+					...params.params !== void 0 && { params: params.params },
+					timeoutMs: params.timeoutMs,
+					idempotencyKey: params.idempotencyKey || randomUUID()
+				},
+				timeoutMs: params.timeoutMs ? params.timeoutMs + 5e3 : void 0,
+				clientName: GATEWAY_CLIENT_NAMES.CLI,
+				mode: GATEWAY_CLIENT_MODES.CLI
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/cli-registry-loader.ts
+function createPluginCliLogger() {
+	return createPluginRuntimeLoaderLogger();
+}
+function resolvePluginCliLogger(logger) {
+	return logger ?? createPluginCliLogger();
+}
+function buildPluginCliLoaderParams(context, params, loaderOptions) {
+	const onlyPluginIds = resolvePrimaryCommandPluginIds(context, params?.primaryCommand);
+	return buildPluginRuntimeLoadOptions(context, {
+		...loaderOptions,
+		...onlyPluginIds.length > 0 ? { onlyPluginIds } : {}
+	});
+}
+function resolvePrimaryCommandPluginIds(context, primaryCommand) {
+	const normalizedPrimary = primaryCommand?.trim();
+	if (!normalizedPrimary) return [];
+	return resolveManifestActivationPluginIds({
+		trigger: {
+			kind: "command",
+			command: normalizedPrimary
+		},
+		config: context.activationSourceConfig,
+		workspaceDir: context.workspaceDir,
+		env: context.env
+	});
+}
+function resolvePluginCliLoadContext(params) {
+	return resolvePluginRuntimeLoadContext({
+		config: params.cfg,
+		env: params.env,
+		logger: params.logger
+	});
+}
+async function loadPluginCliMetadataRegistryWithContext(context, params, loaderOptions) {
+	return {
+		...context,
+		registry: await loadGenesisPluginCliRegistry(buildPluginCliLoaderParams(context, params, loaderOptions))
+	};
+}
+async function loadPluginCliCommandRegistryWithContext(params) {
+	const onlyPluginIds = resolvePrimaryCommandPluginIds(params.context, params.primaryCommand);
+	return {
+		...params.context,
+		registry: loadGenesisPlugins(buildPluginRuntimeLoadOptions(params.context, {
+			...params.loaderOptions,
+			...onlyPluginIds.length > 0 ? { onlyPluginIds } : {},
+			activate: false,
+			cache: false,
+			runtimeOptions: { nodes: createPluginCliGatewayNodesRuntime() }
+		}))
+	};
+}
+function buildPluginCliCommandGroupEntries(params) {
+	return params.registry.cliRegistrars.map((entry) => ({
+		pluginId: entry.pluginId,
+		placeholders: entry.descriptors,
+		names: entry.commands,
+		register: async (program) => {
+			await entry.register({
+				program,
+				config: params.config,
+				workspaceDir: params.workspaceDir,
+				logger: params.logger
+			});
+		}
+	}));
+}
+async function loadPluginCliDescriptors(params) {
+	try {
+		const logger = resolvePluginCliLogger(params.logger);
+		const { registry } = await loadPluginCliMetadataRegistryWithContext(resolvePluginCliLoadContext({
+			cfg: params.cfg,
+			env: params.env,
+			logger
+		}), { primaryCommand: params.primaryCommand }, params.loaderOptions);
+		return collectUniqueCommandDescriptors(registry.cliRegistrars.map((entry) => entry.descriptors));
+	} catch {
+		return [];
+	}
+}
+async function loadPluginCliRegistrationEntries(params) {
+	const resolvedLogger = resolvePluginCliLogger(params.logger);
+	const { config, workspaceDir, logger, registry } = await loadPluginCliCommandRegistryWithContext({
+		context: resolvePluginCliLoadContext({
+			cfg: params.cfg,
+			env: params.env,
+			logger: resolvedLogger
+		}),
+		primaryCommand: params.primaryCommand,
+		loaderOptions: params.loaderOptions
+	});
+	return buildPluginCliCommandGroupEntries({
+		registry,
+		config,
+		workspaceDir,
+		logger
+	});
+}
+async function loadPluginCliRegistrationEntriesWithDefaults(params) {
+	const logger = resolvePluginCliLogger(params.logger);
+	return loadPluginCliRegistrationEntries({
+		...params,
+		logger
+	});
+}
+//#endregion
+//#region src/plugins/register-plugin-cli-command-groups.ts
+function canRegisterPluginCliLazily(entry) {
+	if (entry.placeholders.length === 0) return false;
+	const descriptorNames = new Set(entry.placeholders.map((descriptor) => descriptor.name));
+	return getCommandGroupNames(entry).every((command) => descriptorNames.has(command));
+}
+async function registerPluginCliCommandGroups(program, entries, params) {
+	for (const entry of entries) {
+		const registerEntry = async () => {
+			await entry.register(program);
+			for (const command of getCommandGroupNames(entry)) params.existingCommands.add(command);
+		};
+		if (params.primary && findCommandGroupEntry([entry], params.primary)) {
+			removeCommandGroupNames(program, entry);
+			await registerEntry();
+			continue;
+		}
+		const overlaps = getCommandGroupNames(entry).filter((command) => params.existingCommands.has(command));
+		if (overlaps.length > 0) {
+			params.logger.debug?.(`plugin CLI register skipped (${entry.pluginId}): command already registered (${overlaps.join(", ")})`);
+			continue;
+		}
+		try {
+			if (params.mode === "lazy" && canRegisterPluginCliLazily(entry)) {
+				for (const placeholder of entry.placeholders) registerLazyCommandGroup(program, entry, placeholder);
+				continue;
+			}
+			if (params.mode === "lazy" && entry.placeholders.length > 0) params.logger.debug?.(`plugin CLI lazy register fallback to eager (${entry.pluginId}): descriptors do not cover all command roots`);
+			await registerEntry();
+		} catch (error) {
+			params.logger.warn(`plugin CLI register failed (${entry.pluginId}): ${String(error)}`);
+		}
+	}
+}
+//#endregion
+//#region src/plugins/cli.ts
+const logger = createPluginCliLogger();
+const loadValidatedConfigForPluginRegistration = async () => {
+	if (!(await readConfigFileSnapshot()).valid) return null;
+	return loadConfig();
+};
+async function getPluginCliCommandDescriptors(cfg, env, loaderOptions) {
+	return loadPluginCliDescriptors({
+		cfg,
+		env,
+		loaderOptions
+	});
+}
+async function registerPluginCliCommands(program, cfg, env, loaderOptions, options) {
+	const mode = options?.mode ?? "eager";
+	const primary = options?.primary ?? void 0;
+	await registerPluginCliCommandGroups(program, await loadPluginCliRegistrationEntriesWithDefaults({
+		cfg,
+		env,
+		loaderOptions,
+		primaryCommand: primary
+	}), {
+		mode,
+		primary,
+		existingCommands: new Set(program.commands.map((cmd) => cmd.name())),
+		logger
+	});
+}
+async function registerPluginCliCommandsFromValidatedConfig(program, env, loaderOptions, options) {
+	const config = await loadValidatedConfigForPluginRegistration();
+	if (!config) return null;
+	await registerPluginCliCommands(program, config, env, loaderOptions, options);
+	return config;
+}
+//#endregion
+export { registerPluginCliCommandsFromValidatedConfig as i, loadValidatedConfigForPluginRegistration as n, registerPluginCliCommands as r, getPluginCliCommandDescriptors as t };