@pixelzx/genesis 2026.6.29 → 2026.7.9

package/dist/clawbot-cli-jsnS_FnN.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-CuHAMWri.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-C4rj1fY_.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-L87U4LxS.js";
+import * as daemonCliRunners2 from "../status.runtime-BNG-ykFb.js";
 export const registerDaemonCli = daemonCli.t;
 export const runDaemonInstall = daemonCliRunners0.runDaemonInstall;
 export const runDaemonRestart = daemonCliRunners1.runDaemonRestart;

package/dist/cli-BWZ_fxIG.js

@@ -0,0 +1,72 @@
+import { t as formatDocsLink } from "./links-C1-jbHJx.js";
+import { r as theme } from "./theme-DD6pQv2_.js";
+import { t as formatHelpExamples } from "./help-format-XI0mCjwz.js";
+import "./memory-core-host-runtime-cli-D5FBfgB5.js";
+import { t as DEFAULT_PROMOTION_MIN_SCORE } from "./short-term-promotion-CTgrLYqD.js";
+//#region extensions/memory-core/src/cli.ts
+let memoryCliRuntimePromise = null;
+async function loadMemoryCliRuntime() {
+	memoryCliRuntimePromise ??= import("./cli.runtime-CJ-0cVHG.js");
+	return await memoryCliRuntimePromise;
+}
+async function runMemoryStatus(opts) {
+	await (await loadMemoryCliRuntime()).runMemoryStatus(opts);
+}
+async function runMemoryIndex(opts) {
+	await (await loadMemoryCliRuntime()).runMemoryIndex(opts);
+}
+async function runMemorySearch(queryArg, opts) {
+	await (await loadMemoryCliRuntime()).runMemorySearch(queryArg, opts);
+}
+async function runMemoryPromote(opts) {
+	await (await loadMemoryCliRuntime()).runMemoryPromote(opts);
+}
+async function runMemoryPromoteExplain(selectorArg, opts) {
+	await (await loadMemoryCliRuntime()).runMemoryPromoteExplain(selectorArg, opts);
+}
+async function runMemoryRemHarness(opts) {
+	await (await loadMemoryCliRuntime()).runMemoryRemHarness(opts);
+}
+async function runMemoryRemBackfill(opts) {
+	await (await loadMemoryCliRuntime()).runMemoryRemBackfill(opts);
+}
+function registerMemoryCli(program) {
+	const memory = program.command("memory").description("Search, inspect, and reindex memory files").addHelpText("after", () => `\n${theme.heading("Examples:")}\n${formatHelpExamples([
+		["genesis memory status", "Show index and provider status."],
+		["genesis memory status --fix", "Repair stale recall locks and normalize promotion metadata."],
+		["genesis memory status --deep", "Probe embedding provider readiness."],
+		["genesis memory index --force", "Force a full reindex."],
+		["genesis memory search \"meeting notes\"", "Quick search using positional query."],
+		["genesis memory search --query \"deployment\" --max-results 20", "Limit results for focused troubleshooting."],
+		[`genesis memory promote --limit 10 --min-score ${DEFAULT_PROMOTION_MIN_SCORE}`, "Review weighted short-term candidates for long-term memory."],
+		["genesis memory promote --apply", "Append top-ranked short-term candidates into MEMORY.md."],
+		["genesis memory promote-explain \"router vlan\"", "Explain why a specific candidate would or would not promote."],
+		["genesis memory rem-harness --json", "Preview REM reflections, candidate truths, and deep promotion output."],
+		["genesis memory rem-backfill --path ./memory", "Write grounded historical REM entries into DREAMS.md for UI review."],
+		["genesis memory rem-backfill --path ./memory --stage-short-term", "Also seed durable grounded candidates into the live short-term promotion store."],
+		["genesis memory status --json", "Output machine-readable JSON (good for scripts)."]
+	])}\n\n${theme.muted("Docs:")} ${formatDocsLink("/cli/memory", "genesis.pixelzx.com/docs/cli/memory")}\n`);
+	memory.command("status").description("Show memory search index status").option("--agent <id>", "Agent id (default: default agent)").option("--json", "Print JSON").option("--deep", "Probe embedding provider availability").option("--index", "Reindex if dirty (implies --deep)").option("--fix", "Repair stale recall locks and normalize promotion metadata").option("--verbose", "Verbose logging", false).action(async (opts) => {
+		await runMemoryStatus(opts);
+	});
+	memory.command("index").description("Reindex memory files").option("--agent <id>", "Agent id (default: default agent)").option("--force", "Force full reindex", false).option("--verbose", "Verbose logging", false).action(async (opts) => {
+		await runMemoryIndex(opts);
+	});
+	memory.command("search").description("Search memory files").argument("[query]", "Search query").option("--query <text>", "Search query (alternative to positional argument)").option("--agent <id>", "Agent id (default: default agent)").option("--max-results <n>", "Max results", (value) => Number(value)).option("--min-score <n>", "Minimum score", (value) => Number(value)).option("--json", "Print JSON").action(async (queryArg, opts) => {
+		await runMemorySearch(queryArg, opts);
+	});
+	memory.command("promote").description("Rank short-term recalls and optionally append top entries to MEMORY.md").option("--agent <id>", "Agent id (default: default agent)").option("--limit <n>", "Max candidates", (value) => Number(value)).option("--min-score <n>", `Minimum weighted score (default: ${DEFAULT_PROMOTION_MIN_SCORE})`, (value) => Number(value)).option("--min-recall-count <n>", `Minimum recall count (default: 3)`, (value) => Number(value)).option("--min-unique-queries <n>", `Minimum distinct query count (default: 2)`, (value) => Number(value)).option("--apply", "Append selected candidates to MEMORY.md", false).option("--include-promoted", "Include already promoted candidates", false).option("--json", "Print JSON").action(async (opts) => {
+		await runMemoryPromote(opts);
+	});
+	memory.command("promote-explain").description("Explain a specific promotion candidate and its score breakdown").argument("<selector>", "Candidate key, path fragment, or snippet fragment").option("--agent <id>", "Agent id (default: default agent)").option("--include-promoted", "Include already promoted candidates", false).option("--json", "Print JSON").action(async (selectorArg, opts) => {
+		await runMemoryPromoteExplain(selectorArg, opts);
+	});
+	memory.command("rem-harness").description("Preview REM reflections, candidate truths, and deep promotions without writing").option("--agent <id>", "Agent id (default: default agent)").option("--path <file-or-dir>", "Seed the harness from historical daily memory file(s)").option("--grounded", "Also render a grounded day-level REM preview").option("--include-promoted", "Include already promoted deep candidates", false).option("--json", "Print JSON").action(async (opts) => {
+		await runMemoryRemHarness(opts);
+	});
+	memory.command("rem-backfill").description("Write grounded historical REM summaries into DREAMS.md for UI review").option("--agent <id>", "Agent id (default: default agent)").option("--path <file-or-dir>", "Historical daily memory file(s) or directory").option("--rollback", "Remove previously written grounded REM backfill entries", false).option("--stage-short-term", "Also seed grounded durable candidates into the short-term promotion store", false).option("--rollback-short-term", "Remove previously seeded grounded short-term candidates", false).option("--json", "Print JSON").action(async (opts) => {
+		await runMemoryRemBackfill(opts);
+	});
+}
+//#endregion
+export { runMemoryStatus as n, registerMemoryCli as t };

package/dist/cli-BnjgRW4w.js

@@ -0,0 +1,154 @@
+import { c as normalizeOptionalString, d as normalizeStringifiedOptionalString } from "./string-coerce-DPP_aYVc.js";
+import "./text-runtime-DVUvIDNC.js";
+import { t as COGNITIVE_SERVICES_RESOURCE } from "./shared-G254rWzJ.js";
+import { execFile, execFileSync, spawn } from "node:child_process";
+//#region extensions/microsoft-foundry/cli.ts
+function summarizeAzErrorMessage(raw) {
+	const trimmed = raw.trim();
+	if (!trimmed) return "";
+	const normalized = trimmed.replace(/\s+/g, " ");
+	if (/not recognized|enoent|spawn .* az/i.test(normalized)) return "Azure CLI (az) is not installed or not on PATH.";
+	if (/az login/i.test(normalized) || /please run 'az login'/i.test(normalized)) return "Azure CLI is not logged in. Run `az login --use-device-code`.";
+	if (/subscription/i.test(normalized) && /could not be found|does not exist|no subscriptions/i.test(normalized)) return "Azure CLI could not find an accessible subscription. Check the selected subscription or tenant access.";
+	if (/tenant/i.test(normalized) && /not found|invalid|doesn't exist|does not exist/i.test(normalized)) return "Azure CLI could not use that tenant. Verify the tenant ID or tenant domain and try `az login --tenant <tenant>`.";
+	if (/aadsts\d+/i.test(normalized)) return "Azure login failed for the selected tenant. Re-run `az login --use-device-code` and confirm the tenant is correct.";
+	return normalized.slice(0, 300);
+}
+function buildAzCommandError(error, stderr, stdout) {
+	const details = summarizeAzErrorMessage(`${stderr ?? ""} ${stdout ?? ""}`);
+	return new Error(details ? `${error.message}: ${details}` : error.message);
+}
+function execAz(args) {
+	return normalizeOptionalString(execFileSync("az", args, {
+		encoding: "utf-8",
+		timeout: 3e4,
+		shell: process.platform === "win32"
+	})) ?? "";
+}
+async function execAzAsync(args) {
+	return await new Promise((resolve, reject) => {
+		execFile("az", args, {
+			encoding: "utf-8",
+			timeout: 3e4,
+			shell: process.platform === "win32"
+		}, (error, stdout, stderr) => {
+			if (error) {
+				reject(buildAzCommandError(error, stderr ?? "", stdout ?? ""));
+				return;
+			}
+			resolve(normalizeStringifiedOptionalString(stdout) ?? "");
+		});
+	});
+}
+function isAzCliInstalled() {
+	try {
+		execAz([
+			"version",
+			"--output",
+			"none"
+		]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function getLoggedInAccount() {
+	try {
+		return JSON.parse(execAz([
+			"account",
+			"show",
+			"--output",
+			"json"
+		]));
+	} catch {
+		return null;
+	}
+}
+function listSubscriptions() {
+	try {
+		return JSON.parse(execAz([
+			"account",
+			"list",
+			"--output",
+			"json",
+			"--all"
+		])).filter((sub) => sub.state === "Enabled");
+	} catch {
+		return [];
+	}
+}
+function buildAccessTokenArgs(params) {
+	const args = [
+		"account",
+		"get-access-token",
+		"--resource",
+		COGNITIVE_SERVICES_RESOURCE,
+		"--output",
+		"json"
+	];
+	if (params?.subscriptionId) args.push("--subscription", params.subscriptionId);
+	else if (params?.tenantId) args.push("--tenant", params.tenantId);
+	return args;
+}
+function getAccessTokenResult(params) {
+	return JSON.parse(execAz(buildAccessTokenArgs(params)));
+}
+async function getAccessTokenResultAsync(params) {
+	return JSON.parse(await execAzAsync(buildAccessTokenArgs(params)));
+}
+async function azLoginDeviceCode() {
+	return azLoginDeviceCodeWithOptions({});
+}
+async function azLoginDeviceCodeWithOptions(params) {
+	return new Promise((resolve, reject) => {
+		const maxCapturedLoginOutputChars = 8e3;
+		const child = spawn("az", [
+			"login",
+			"--use-device-code",
+			...params.tenantId ? ["--tenant", params.tenantId] : [],
+			...params.allowNoSubscriptions ? ["--allow-no-subscriptions"] : []
+		], {
+			stdio: [
+				"inherit",
+				"pipe",
+				"pipe"
+			],
+			shell: process.platform === "win32"
+		});
+		const stdoutChunks = [];
+		const stderrChunks = [];
+		let stdoutLen = 0;
+		let stderrLen = 0;
+		const appendBoundedChunk = (chunks, text, len) => {
+			if (!text) return len;
+			chunks.push(text);
+			let total = len + text.length;
+			while (total > maxCapturedLoginOutputChars && chunks.length > 0) {
+				const removed = chunks.shift();
+				total -= removed?.length ?? 0;
+			}
+			return total;
+		};
+		child.stdout?.on("data", (chunk) => {
+			const text = String(chunk);
+			stdoutLen = appendBoundedChunk(stdoutChunks, text, stdoutLen);
+			process.stdout.write(text);
+		});
+		child.stderr?.on("data", (chunk) => {
+			const text = String(chunk);
+			stderrLen = appendBoundedChunk(stderrChunks, text, stderrLen);
+			process.stderr.write(text);
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			const output = normalizeOptionalString([...stderrChunks, ...stdoutChunks].join("")) ?? "";
+			reject(/* @__PURE__ */ new Error(output ? `az login exited with code ${code}: ${output}` : `az login exited with code ${code}`));
+		});
+		child.on("error", reject);
+	});
+}
+//#endregion
+export { getAccessTokenResult as a, isAzCliInstalled as c, execAzAsync as i, listSubscriptions as l, azLoginDeviceCodeWithOptions as n, getAccessTokenResultAsync as o, execAz as r, getLoggedInAccount as s, azLoginDeviceCode as t };