@jshookmcp/jshook 0.2.8 → 0.2.9

package/dist/maintenance-P7ePRXQC.mjs

@@ -0,0 +1,830 @@
+import { t as logger } from "./logger-Dh_xb7_2.mjs";
+import { H as EXTENSION_GIT_CHECKOUT_TIMEOUT_MS, Q as GHIDRA_BRIDGE_ENDPOINT, U as EXTENSION_GIT_CLONE_TIMEOUT_MS, mt as IDA_BRIDGE_ENDPOINT } from "./constants-B0OANIBL.mjs";
+import { n as getArtifactRetentionConfig, t as cleanupArtifacts } from "./artifactRetention-CFEprwPw.mjs";
+import { i as serializeError, n as asJsonResponse } from "./response-BQVP-xUn.mjs";
+import { c as getConfig, i as getProjectRoot } from "./outputPaths-B1uGmrWZ.mjs";
+import { t as INSTALLED_EXTENSION_METADATA_FILENAME } from "./types-Bx92KJfT.mjs";
+import { r as probeBetterSqlite3 } from "./betterSqlite3-0pqusHHH.mjs";
+import { r as ioLimit } from "./concurrency-Bt0yv1kJ.mjs";
+import { t as ToolRegistry } from "./ToolRegistry-BjaF4oNz.mjs";
+import "./definitions-ClJLzsJQ.mjs";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+//#region src/utils/environmentDoctor.ts
+const execFileAsync$1 = promisify(execFile);
+const require = createRequire(import.meta.url);
+let sharedRegistry = null;
+let sharedRegistryTimestamp = 0;
+const REGISTRY_CACHE_TTL_MS = 12e4;
+function getSharedRegistry() {
+	const now = Date.now();
+	if (!sharedRegistry || now - sharedRegistryTimestamp > REGISTRY_CACHE_TTL_MS) {
+		sharedRegistry = new ToolRegistry();
+		sharedRegistryTimestamp = now;
+	}
+	return sharedRegistry;
+}
+async function runEnvironmentDoctor(options) {
+	const includeBridgeHealth = options?.includeBridgeHealth ?? true;
+	const externalResultsPromise = getSharedRegistry().probeAll(true);
+	const gitCommandPromise = ioLimit(() => checkCommand("git", ["--version"]));
+	const pythonCommandPromise = ioLimit(() => checkCommand("python", ["--version"]));
+	const pnpmCommandPromise = ioLimit(() => checkPnpmCommand());
+	const corepackCheckPromise = ioLimit(() => checkCommand("corepack", ["--version"]));
+	const bridgesPromise = includeBridgeHealth ? Promise.all([
+		ioLimit(() => checkHttpEndpoint("ghidra-bridge", `${GHIDRA_BRIDGE_ENDPOINT.replace(/\/$/, "")}/health`)),
+		ioLimit(() => checkHttpEndpoint("ida-bridge", `${IDA_BRIDGE_ENDPOINT.replace(/\/$/, "")}/health`)),
+		ioLimit(() => checkHttpEndpoint("burp-mcp-sse", process.env.BURP_MCP_SSE_URL?.trim() || "http://127.0.0.1:9876"))
+	]) : Promise.resolve([]);
+	const [externalResults, gitCommand, pythonCommand, pnpmCommand, corepackCheck, bridges] = await Promise.all([
+		externalResultsPromise,
+		gitCommandPromise,
+		pythonCommandPromise,
+		pnpmCommandPromise,
+		corepackCheckPromise,
+		bridgesPromise
+	]);
+	const corepackCommand = normalizeCorepackCheck(corepackCheck, pnpmCommand);
+	const packages = [
+		checkPackage("@modelcontextprotocol/sdk"),
+		checkPackage("rebrowser-puppeteer-core"),
+		checkBetterSqlite3(),
+		checkPackage("camoufox-js", "Optional Firefox anti-detect driver"),
+		checkPackage("playwright-core", "Optional browser automation dependency"),
+		checkNativeMemory()
+	];
+	const commands = [
+		gitCommand,
+		pythonCommand,
+		pnpmCommand,
+		corepackCommand,
+		...Object.entries(externalResults).map(([name, result]) => ({
+			name,
+			status: result.available ? "ok" : "missing",
+			detail: result.available ? `${result.path ?? "PATH"}${result.version ? ` (${result.version})` : ""}` : result.reason ?? "Unavailable"
+		}))
+	];
+	const limitations = buildPlatformLimitations();
+	const recommendations = buildRecommendations(packages, commands, bridges, limitations);
+	return {
+		success: [
+			...packages,
+			...commands,
+			...bridges
+		].every((item) => item.status !== "error"),
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		runtime: {
+			platform: process.platform,
+			arch: process.arch,
+			node: process.version,
+			cwd: process.cwd(),
+			projectRoot: getProjectRoot()
+		},
+		packages,
+		commands,
+		bridges,
+		config: {
+			transport: (process.env.MCP_TRANSPORT ?? "stdio").toLowerCase(),
+			toolProfile: (process.env.MCP_TOOL_PROFILE ?? "search").toLowerCase(),
+			pluginRoots: process.env.MCP_PLUGIN_ROOTS ?? "<jshook-install>/plugins",
+			workflowRoots: process.env.MCP_WORKFLOW_ROOTS ?? "<jshook-install>/workflows",
+			pluginSignatureRequired: process.env.MCP_PLUGIN_SIGNATURE_REQUIRED ?? (process.env.NODE_ENV === "production" ? "true (production default)" : "false"),
+			pluginStrictLoad: process.env.MCP_PLUGIN_STRICT_LOAD ?? (process.env.NODE_ENV === "production" ? "true (production default)" : "false"),
+			artifactRetention: getArtifactRetentionConfig()
+		},
+		limitations,
+		recommendations
+	};
+}
+function checkPackage(packageName, missingHint) {
+	try {
+		const packageJson = require(require.resolve(`${packageName}/package.json`));
+		return {
+			name: packageName,
+			status: "ok",
+			detail: packageJson.version ? `installed (${packageJson.version})` : "installed"
+		};
+	} catch {
+		return {
+			name: packageName,
+			status: "missing",
+			detail: missingHint ?? "Not installed"
+		};
+	}
+}
+function checkBetterSqlite3() {
+	const result = probeBetterSqlite3();
+	return {
+		name: "better-sqlite3",
+		status: result.status,
+		detail: result.detail
+	};
+}
+function isPnpmOperational(pnpm) {
+	return pnpm.status === "ok" || pnpm.detail.includes("npx fallback works");
+}
+async function checkPnpmCommand() {
+	const direct = await checkCommand("pnpm", ["--version"]);
+	if (direct.status === "ok") return direct;
+	const npxFallback = await checkCommand("npx", ["pnpm", "--version"], 1e4);
+	if (npxFallback.status === "ok") return {
+		name: "pnpm",
+		status: "warn",
+		detail: `direct pnpm command unavailable; npx fallback works (${npxFallback.detail})`
+	};
+	return direct;
+}
+function normalizeCorepackCheck(corepack, pnpm) {
+	if (corepack.status !== "missing" || !isPnpmOperational(pnpm)) return corepack;
+	return {
+		name: corepack.name,
+		status: "warn",
+		detail: process.platform === "win32" ? pnpm.detail.includes("npx fallback works") ? "corepack not found; use `npx pnpm` directly (common with nvm4w-managed Node on Windows)" : "corepack not found; standalone pnpm is available (common with nvm4w-managed Node on Windows)" : pnpm.detail.includes("npx fallback works") ? "corepack not found; use `npx pnpm` directly" : "corepack not found; standalone pnpm is available"
+	};
+}
+/**
+* Check koffi + platform-specific native library availability for memory tools.
+* Only loads/unloads the library — does NOT call any native functions (avoids SIGBUS on SIP macOS).
+*/
+function checkNativeMemory() {
+	try {
+		const koffiVersion = require(require.resolve("koffi/package.json")).version ?? "unknown";
+		if (process.platform === "win32") return {
+			name: "native-memory",
+			status: "ok",
+			detail: `koffi ${koffiVersion} — Win32 kernel32.dll available`
+		};
+		if (process.platform === "darwin") try {
+			require("koffi").load("/usr/lib/libSystem.B.dylib").unload();
+			delete require.cache[require.resolve("koffi")];
+			return {
+				name: "native-memory",
+				status: "ok",
+				detail: `koffi ${koffiVersion} — macOS libSystem.B.dylib available (Mach APIs need root + SIP config)`
+			};
+		} catch {
+			return {
+				name: "native-memory",
+				status: "warn",
+				detail: `koffi ${koffiVersion} installed but cannot load libSystem.B.dylib`
+			};
+		}
+		return {
+			name: "native-memory",
+			status: "warn",
+			detail: `koffi ${koffiVersion} — no native FFI memory provider for ${process.platform} (proc-based ops available on Linux)`
+		};
+	} catch {
+		return {
+			name: "native-memory",
+			status: "missing",
+			detail: "koffi not installed — native memory tools unavailable. Install with: pnpm add koffi"
+		};
+	}
+}
+async function checkCommand(command, args, timeout = 4e3) {
+	try {
+		const { stdout, stderr } = await execFileAsync$1(command, args, {
+			timeout,
+			windowsHide: true
+		});
+		return {
+			name: command,
+			status: "ok",
+			detail: `${stdout || stderr}`.trim().split(/\r?\n/)[0] || "available"
+		};
+	} catch (error) {
+		if (process.platform === "win32") try {
+			const { stdout, stderr } = await execFileAsync$1("cmd", [
+				"/c",
+				command,
+				...args
+			], {
+				timeout,
+				windowsHide: true
+			});
+			return {
+				name: command,
+				status: "ok",
+				detail: `${`${stdout || stderr}`.trim().split(/\r?\n/)[0] || "available"} (via cmd)`
+			};
+		} catch (cmdError) {
+			return formatCommandError(command, cmdError);
+		}
+		return formatCommandError(command, error);
+	}
+}
+function formatCommandError(command, error) {
+	const detail = error instanceof Error ? error.message : String(error);
+	return {
+		name: command,
+		status: /ENOENT|not recognized|not found/i.test(detail) ? "missing" : "warn",
+		detail
+	};
+}
+async function checkHttpEndpoint(name, url) {
+	try {
+		const res = await fetch(url, {
+			method: "GET",
+			signal: AbortSignal.timeout(3e3)
+		});
+		return {
+			name,
+			status: res.ok ? "ok" : "warn",
+			detail: `${url} -> HTTP ${res.status}`
+		};
+	} catch (error) {
+		return {
+			name,
+			status: "warn",
+			detail: `${url} -> ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
+function buildPlatformLimitations() {
+	const limitations = [];
+	if (process.platform === "darwin") {
+		limitations.push("26 cross-platform memory tools available (scan, pointer-chain, structure-analysis, heap). 15 Windows-only tools unavailable (PE analysis, anti-cheat, code injection, speedhack, hardware breakpoints).");
+		limitations.push("Native memory operations (mach_vm_read/write) require root privileges and may require SIP configuration on ARM64.");
+	} else if (process.platform === "linux") {
+		limitations.push("Process management available via /proc. Native FFI memory provider not implemented — memory read/write uses /proc/pid/mem (requires root or CAP_SYS_PTRACE).");
+		limitations.push("Camoufox runs on Linux, but some Chrome/CDP-heavy workflows are better served by the Chrome driver.");
+	} else if (process.platform !== "win32") limitations.push(`Platform ${process.platform} is not supported for native memory operations. Use Windows or macOS.`);
+	return limitations;
+}
+function buildRecommendations(packages, commands, bridges, limitations) {
+	const recommendations = [];
+	const pnpmCommand = commands.find((item) => item.name === "pnpm");
+	const corepackCommand = commands.find((item) => item.name === "corepack");
+	if (packages.some((item) => item.name === "better-sqlite3" && item.status !== "ok")) recommendations.push("Install or rebuild the optional SQLite trace backend with `pnpm add -O better-sqlite3@12.6.2` or `npm rebuild better-sqlite3 --foreground-scripts` under the active Node version if you need trace tooling.");
+	if (packages.some((item) => item.name === "camoufox-js" && item.status !== "ok")) recommendations.push("Install optional browser dependencies with `pnpm run install:full` if you need Camoufox support.");
+	if (commands.some((item) => item.name.startsWith("wabt.") && item.status !== "ok")) recommendations.push("Install wabt if you need full WASM disassembly/decompilation; otherwise the server will stay in basic mode.");
+	if (pnpmCommand && !isPnpmOperational(pnpmCommand)) recommendations.push("Install pnpm or enable Corepack (`corepack enable`) before running package-management workflows.");
+	else if (pnpmCommand?.detail.includes("npx fallback works")) recommendations.push("Use `npx pnpm` directly on this machine or repair the local pnpm/Corepack shim if scripts expect bare `pnpm`.");
+	else if (corepackCommand?.status === "warn" && corepackCommand.detail.includes("standalone pnpm")) recommendations.push("Use `pnpm` or `npx pnpm` directly on this machine; `corepack` is optional and may be absent on nvm4w-managed Windows installs.");
+	if (bridges.some((item) => item.status !== "ok")) recommendations.push("Check local bridge endpoints (Ghidra / IDA / Burp) before relying on native-bridge workflows.");
+	if (limitations.length > 0) recommendations.push("Review platform limitations before using process/memory tooling on non-Windows hosts.");
+	return recommendations;
+}
+//#endregion
+//#region src/server/domains/maintenance/handlers.ts
+var CoreMaintenanceHandlers = class {
+	tokenBudget;
+	unifiedCache;
+	artifactCleanup;
+	environmentDoctor;
+	constructor(deps) {
+		this.tokenBudget = deps.tokenBudget;
+		this.unifiedCache = deps.unifiedCache;
+		this.artifactCleanup = deps.artifactCleanup ?? cleanupArtifacts;
+		this.environmentDoctor = deps.environmentDoctor ?? runEnvironmentDoctor;
+	}
+	async handleGetTokenBudgetStats() {
+		try {
+			const stats = this.tokenBudget.getStats();
+			return asJsonResponse({
+				success: true,
+				...stats,
+				sessionDuration: `${Math.round((Date.now() - stats.sessionStartTime) / 1e3)}s`
+			});
+		} catch (error) {
+			logger.error("Failed to read token budget stats:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleManualTokenCleanup() {
+		try {
+			const beforeStats = this.tokenBudget.getStats();
+			this.tokenBudget.manualCleanup();
+			const afterStats = this.tokenBudget.getStats();
+			const freed = beforeStats.currentUsage - afterStats.currentUsage;
+			return asJsonResponse({
+				success: true,
+				message: "Manual cleanup completed",
+				before: {
+					usage: beforeStats.currentUsage,
+					percentage: beforeStats.usagePercentage
+				},
+				after: {
+					usage: afterStats.currentUsage,
+					percentage: afterStats.usagePercentage
+				},
+				freed: {
+					tokens: freed,
+					percentage: Math.round(freed / beforeStats.maxTokens * 100)
+				}
+			});
+		} catch (error) {
+			logger.error("Failed to perform manual cleanup:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleResetTokenBudget() {
+		try {
+			this.tokenBudget.reset();
+			return asJsonResponse({
+				success: true,
+				message: "Token budget reset successfully",
+				currentUsage: 0,
+				maxTokens: 2e5,
+				usagePercentage: 0
+			});
+		} catch (error) {
+			logger.error("Failed to reset token budget:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleGetCacheStats() {
+		try {
+			return asJsonResponse({
+				success: true,
+				...await this.unifiedCache.getGlobalStats()
+			});
+		} catch (error) {
+			logger.error("Failed to get cache stats:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleSmartCacheCleanup(targetSize) {
+		try {
+			return asJsonResponse({
+				success: true,
+				...await this.unifiedCache.smartCleanup(targetSize)
+			});
+		} catch (error) {
+			logger.error("Failed to perform cache cleanup:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleClearAllCaches() {
+		try {
+			await this.unifiedCache.clearAll();
+			return asJsonResponse({
+				success: true,
+				message: "All caches cleared"
+			});
+		} catch (error) {
+			logger.error("Failed to clear caches:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleCleanupArtifacts(args) {
+		try {
+			return asJsonResponse(await this.artifactCleanup({
+				retentionDays: args.retentionDays,
+				maxTotalBytes: args.maxTotalBytes,
+				dryRun: args.dryRun
+			}));
+		} catch (error) {
+			logger.error("Failed to cleanup artifacts:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleEnvironmentDoctor(args) {
+		try {
+			return asJsonResponse(await this.environmentDoctor({ includeBridgeHealth: args.includeBridgeHealth }));
+		} catch (error) {
+			logger.error("Failed to run environment doctor:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+};
+//#endregion
+//#region src/server/domains/maintenance/handlers.extensions.ts
+const execFileAsync = promisify(execFile);
+function getJshookInstallRoot() {
+	return fileURLToPath(new URL("../../../../", import.meta.url));
+}
+function parseFirstRoot(raw) {
+	const value = raw?.trim();
+	if (!value) return void 0;
+	return value.split(",").map((item) => item.trim()).find((item) => item.length > 0);
+}
+function resolveDefaultExtensionRoot(kind) {
+	const envKey = kind === "workflow" ? "MCP_WORKFLOW_ROOTS" : "MCP_PLUGIN_ROOTS";
+	const configured = parseFirstRoot(process.env[envKey]);
+	if (configured) return resolve(configured);
+	return resolve(getJshookInstallRoot(), kind === "workflow" ? "workflows" : "plugins");
+}
+function getRegistryBaseUrl() {
+	const baseUrl = (process.env.EXTENSION_REGISTRY_BASE_URL ?? "").trim().replace(/\/+$/, "");
+	if (!baseUrl) throw new Error("EXTENSION_REGISTRY_BASE_URL is not configured. Set it in .env or environment before browsing or installing extensions.");
+	return baseUrl;
+}
+function normalizeInstallPathSegment(value, field) {
+	const normalized = value?.trim();
+	if (!normalized) {
+		if (field === "subpath") return ".";
+		throw new Error(`Registry source.${field} must be a non-empty string`);
+	}
+	return normalized;
+}
+function ensurePathStaysWithin(baseDir, targetPath, field) {
+	const rel = relative(baseDir, targetPath).replace(/\\/g, "/");
+	if (rel === ".." || rel.startsWith("../") || isAbsolute(rel)) throw new Error(`Registry source.${field} must stay within ${baseDir}: ${targetPath}`);
+}
+function resolveExtensionProjectDir(installDir, subpath) {
+	const projectDir = resolve(installDir, normalizeInstallPathSegment(subpath, "subpath"));
+	ensurePathStaysWithin(installDir, projectDir, "subpath");
+	return projectDir;
+}
+function resolveExtensionEntryFile(projectDir, entryPath) {
+	const resolvedEntryFile = resolve(projectDir, normalizeInstallPathSegment(entryPath, "entry"));
+	ensurePathStaysWithin(projectDir, resolvedEntryFile, "entry");
+	return resolvedEntryFile;
+}
+function buildRuntimeEntryCandidates(entryPath) {
+	const normalizedEntry = normalizeInstallPathSegment(entryPath, "entry").replace(/\\/g, "/");
+	const candidates = [normalizedEntry];
+	if (!normalizedEntry.endsWith(".ts")) return candidates;
+	const jsEntry = `${normalizedEntry.slice(0, -3)}.js`;
+	candidates.unshift(jsEntry);
+	if (!normalizedEntry.startsWith("dist/")) candidates.unshift(`dist/${jsEntry}`);
+	return [...new Set(candidates)];
+}
+function resolveInstalledRuntimeEntry(projectDir, entryPath) {
+	const candidates = buildRuntimeEntryCandidates(entryPath);
+	for (const candidate of candidates) if (existsSync(resolveExtensionEntryFile(projectDir, candidate))) return candidate;
+	return normalizeInstallPathSegment(entryPath, "entry");
+}
+async function writeInstalledExtensionMetadata(kind, entry, projectDir, installedEntryPath) {
+	const payload = {
+		version: 1,
+		kind,
+		slug: entry.slug,
+		id: entry.id,
+		source: {
+			type: entry.source.type,
+			repo: entry.source.repo,
+			ref: entry.source.ref,
+			commit: entry.source.commit,
+			subpath: normalizeInstallPathSegment(entry.source.subpath, "subpath"),
+			entry: normalizeInstallPathSegment(installedEntryPath, "entry")
+		}
+	};
+	const metadataPath = resolve(projectDir, INSTALLED_EXTENSION_METADATA_FILENAME);
+	await writeFile(metadataPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+	return metadataPath;
+}
+const LOCAL_EXTENSION_SDK_PACKAGE = "@jshookmcp/extension-sdk";
+const LOCAL_EXTENSION_SDK_ROOT = resolve(getJshookInstallRoot(), "packages", "extension-sdk");
+function getRegistryCacheDir() {
+	return getConfig().paths.registryCacheDir;
+}
+var RegistryFetchError = class extends Error {
+	constructor(code, url, message, cachePath, status) {
+		super(message);
+		this.code = code;
+		this.url = url;
+		this.cachePath = cachePath;
+		this.status = status;
+		this.name = "RegistryFetchError";
+	}
+};
+function resolvePackageManagerInvocation(packageManager, args) {
+	if (process.platform !== "win32")
+ /* istanbul ignore next -- OS specific fallback */
+	return {
+		command: packageManager,
+		args
+	};
+	return {
+		command: "powershell.exe",
+		args: [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			`${packageManager} ${args.join(" ")}`
+		]
+	};
+}
+async function execPackageManager(packageManager, args, options) {
+	const invocation = resolvePackageManagerInvocation(packageManager, args);
+	return execFileAsync(invocation.command, invocation.args, {
+		...options,
+		env: {
+			...process.env,
+			...options?.env,
+			CI: "true"
+		}
+	});
+}
+async function resolvePackageManager(installDir) {
+	const packageJsonPath = resolve(installDir, "package.json");
+	const pnpmLockPath = resolve(installDir, "pnpm-lock.yaml");
+	const npmLockPath = resolve(installDir, "package-lock.json");
+	if (existsSync(packageJsonPath)) try {
+		const raw = await readFile(packageJsonPath, "utf8");
+		const packageManager = JSON.parse(raw).packageManager?.trim().toLowerCase().split("@")[0];
+		if (packageManager === "pnpm") return "pnpm";
+		if (packageManager === "npm") return "npm";
+	} catch {}
+	if (existsSync(pnpmLockPath)) return "pnpm";
+	if (existsSync(npmLockPath)) return "npm";
+	return "pnpm";
+}
+function getRegistryCachePath(kind) {
+	return resolve(getRegistryCacheDir(), `registry-${kind}.json`);
+}
+async function readRegistryCache(kind) {
+	const cachePath = getRegistryCachePath(kind);
+	try {
+		const raw = await readFile(cachePath, "utf8");
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+async function writeRegistryCache(kind, payload) {
+	const cachePath = getRegistryCachePath(kind);
+	await mkdir(dirname(cachePath), { recursive: true });
+	await writeFile(cachePath, JSON.stringify(payload, null, 2), "utf8");
+}
+function classifyRegistryFetchError(url, error, cachePath) {
+	if (error instanceof RegistryFetchError) return error;
+	if (error instanceof DOMException && error.name === "AbortError") return new RegistryFetchError("timeout", url, `Registry fetch timed out after 10000ms: ${url}`, cachePath);
+	const message = error instanceof Error ? error.message : String(error);
+	if (message.includes("ENOTFOUND") || message.includes("getaddrinfo")) return new RegistryFetchError("dns_failure", url, `DNS resolution failed for registry URL: ${url}`, cachePath);
+	if (message.includes("ECONNREFUSED")) return new RegistryFetchError("connection_refused", url, `Connection refused by registry server: ${url}`, cachePath);
+	if (message.includes("CERT_") || message.includes("certificate") || message.includes("SSL")) return new RegistryFetchError("tls_error", url, `TLS/certificate error when connecting to registry: ${url}`, cachePath);
+	const httpMatch = message.match(/HTTP\s+(\d+)/i);
+	if (httpMatch) return new RegistryFetchError("http_error", url, message, cachePath, Number(httpMatch[1]));
+	return new RegistryFetchError("fetch_failed", url, message, cachePath);
+}
+function serializeRegistryFetchError(error) {
+	return {
+		success: false,
+		error: error.code,
+		message: error.message,
+		url: error.url,
+		...typeof error.status === "number" ? { status: error.status } : {}
+	};
+}
+async function fetchJson(url, options) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), 1e4);
+	const cachePath = options?.cacheKey ? getRegistryCachePath(options.cacheKey) : void 0;
+	try {
+		const res = await fetch(url, { signal: controller.signal });
+		if (!res.ok) throw new RegistryFetchError("http_error", url, `HTTP ${res.status} ${res.statusText} from ${url}`, cachePath, res.status);
+		const data = await res.json();
+		if (options?.cacheKey) try {
+			await writeRegistryCache(options.cacheKey, data);
+		} catch (cacheError) {
+			logger.warn(`[extensions] Failed to persist ${options.cacheKey} registry cache for ${url}:`, cacheError);
+		}
+		return {
+			data,
+			stale: false,
+			source: "network",
+			cachePath
+		};
+	} catch (error) {
+		const classified = classifyRegistryFetchError(url, error, cachePath);
+		if (options?.cacheKey) {
+			const cached = await readRegistryCache(options.cacheKey);
+			if (cached) {
+				logger.warn(`[extensions] Using stale ${options.cacheKey} registry cache after ${classified.code}: ${url}`);
+				return {
+					data: cached,
+					stale: true,
+					source: "cache",
+					cachePath
+				};
+			}
+		}
+		throw classified;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function rewriteLocalExtensionSdkDependency(installDir) {
+	const packageJsonPath = resolve(installDir, "package.json");
+	try {
+		const raw = await readFile(packageJsonPath, "utf8");
+		const pkg = JSON.parse(raw);
+		const sections = [
+			"dependencies",
+			"devDependencies",
+			"peerDependencies",
+			"optionalDependencies"
+		];
+		const localSdkSpec = `file:${relative(installDir, LOCAL_EXTENSION_SDK_ROOT).replace(/\\/g, "/") || "."}`;
+		let changed = false;
+		for (const sectionName of sections) {
+			const section = pkg[sectionName];
+			if (!section || typeof section !== "object") continue;
+			const dependencyMap = section;
+			const currentValue = dependencyMap[LOCAL_EXTENSION_SDK_PACKAGE];
+			if (typeof currentValue === "string" && currentValue.startsWith("workspace:")) {
+				dependencyMap[LOCAL_EXTENSION_SDK_PACKAGE] = localSdkSpec;
+				changed = true;
+			}
+		}
+		if (!changed) return false;
+		await writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+		logger.info(`[extensions] Rewrote ${LOCAL_EXTENSION_SDK_PACKAGE} dependency to local file path for ${installDir}`);
+		return true;
+	} catch (error) {
+		logger.warn(`[extensions] Failed to rewrite ${LOCAL_EXTENSION_SDK_PACKAGE} dependency for ${installDir}:`, error);
+		return false;
+	}
+}
+async function findRegistryEntryBySlug(registryBase, slug) {
+	const [workflowResult, pluginResult] = await Promise.allSettled([fetchJson(`${registryBase}/workflows.index.json`, { cacheKey: "workflows" }), fetchJson(`${registryBase}/plugins.index.json`, { cacheKey: "plugins" })]);
+	if (workflowResult.status === "fulfilled") {
+		const workflowEntry = (Array.isArray(workflowResult.value.data.workflows) ? workflowResult.value.data.workflows : []).find((item) => item.slug === slug);
+		if (workflowEntry) return {
+			entry: workflowEntry,
+			kind: "workflow"
+		};
+	}
+	if (pluginResult.status === "fulfilled") {
+		const pluginEntry = (Array.isArray(pluginResult.value.data.plugins) ? pluginResult.value.data.plugins : []).find((item) => item.slug === slug);
+		if (pluginEntry) return {
+			entry: pluginEntry,
+			kind: "plugin"
+		};
+	}
+	const workflowFetchError = workflowResult.status === "rejected" ? workflowResult.reason instanceof Error ? workflowResult.reason : new Error(String(workflowResult.reason)) : void 0;
+	const pluginFetchError = pluginResult.status === "rejected" ? pluginResult.reason instanceof Error ? pluginResult.reason : new Error(String(pluginResult.reason)) : void 0;
+	if (workflowFetchError && pluginFetchError) throw new Error(`Failed to resolve extension slug "${slug}": workflow registry error: ${workflowFetchError.message}; plugin registry error: ${pluginFetchError.message}`);
+	if (pluginFetchError) throw new Error(`Extension "${slug}" was not found in workflow registry, and plugin registry lookup failed: ${pluginFetchError.message}`);
+	if (workflowFetchError) throw new Error(`Extension "${slug}" was not found in plugin registry, and workflow registry lookup failed: ${workflowFetchError.message}`);
+	throw new Error(`Extension "${slug}" not found in workflow or plugin registry`);
+}
+var ExtensionManagementHandlers = class {
+	ctx;
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	async handleListExtensions() {
+		try {
+			return asJsonResponse({
+				success: true,
+				...this.ctx.listExtensions()
+			});
+		} catch (error) {
+			logger.error("Failed to list extensions:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleReloadExtensions() {
+		try {
+			return asJsonResponse({
+				success: true,
+				...await this.ctx.reloadExtensions()
+			});
+		} catch (error) {
+			logger.error("Failed to reload extensions:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleBrowseExtensionRegistry(kind) {
+		try {
+			const registryBase = getRegistryBaseUrl();
+			const showPlugins = kind === "all" || kind === "plugin";
+			const showWorkflows = kind === "all" || kind === "workflow";
+			const result = { success: true };
+			let stale = false;
+			const pluginPromise = showPlugins ? fetchJson(`${registryBase}/plugins.index.json`, { cacheKey: "plugins" }) : void 0;
+			const workflowPromise = showWorkflows ? fetchJson(`${registryBase}/workflows.index.json`, { cacheKey: "workflows" }) : void 0;
+			const [pluginIndex, workflowIndex] = await Promise.all([pluginPromise ?? Promise.resolve(void 0), workflowPromise ?? Promise.resolve(void 0)]);
+			if (pluginIndex) {
+				const plugins = Array.isArray(pluginIndex.data.plugins) ? pluginIndex.data.plugins : [];
+				result.plugins = plugins.map((p) => ({
+					slug: p.slug,
+					id: p.id,
+					name: p.meta.name,
+					description: p.meta.description,
+					author: p.meta.author,
+					repo: p.source.repo,
+					commit: p.source.commit,
+					entry: p.source.entry
+				}));
+				result.pluginCount = plugins.length;
+				result.pluginSource = pluginIndex.source;
+				stale = stale || pluginIndex.stale;
+			}
+			if (workflowIndex) {
+				const workflows = Array.isArray(workflowIndex.data.workflows) ? workflowIndex.data.workflows : [];
+				result.workflows = workflows.map((w) => ({
+					slug: w.slug,
+					id: w.id,
+					name: w.meta.name,
+					description: w.meta.description,
+					author: w.meta.author,
+					repo: w.source.repo,
+					commit: w.source.commit,
+					entry: w.source.entry
+				}));
+				result.workflowCount = workflows.length;
+				result.workflowSource = workflowIndex.source;
+				stale = stale || workflowIndex.stale;
+			}
+			if (stale) result.stale = true;
+			return asJsonResponse(result);
+		} catch (error) {
+			logger.error("Failed to browse extension registry:", error);
+			if (error instanceof RegistryFetchError) return asJsonResponse(serializeRegistryFetchError(error));
+			return asJsonResponse(serializeError(error));
+		}
+	}
+	async handleInstallExtension(slug, targetDir) {
+		try {
+			const { entry, kind } = await findRegistryEntryBySlug(getRegistryBaseUrl(), slug);
+			const isWorkflow = kind === "workflow";
+			const defaultRoot = resolveDefaultExtensionRoot(isWorkflow ? "workflow" : "plugin");
+			const installDir = targetDir ? resolve(targetDir) : resolve(defaultRoot, slug);
+			const projectDir = resolveExtensionProjectDir(installDir, entry.source.subpath);
+			resolveExtensionEntryFile(projectDir, entry.source.entry);
+			if (existsSync(installDir)) return asJsonResponse({
+				success: false,
+				error: `Target directory already exists: ${installDir}`,
+				hint: "Remove the existing directory first, or specify a different targetDir"
+			});
+			await mkdir(dirname(installDir), { recursive: true });
+			await execFileAsync("git", [
+				"clone",
+				entry.source.repo,
+				installDir
+			], { timeout: EXTENSION_GIT_CLONE_TIMEOUT_MS });
+			await execFileAsync("git", [
+				"-C",
+				installDir,
+				"checkout",
+				entry.source.commit
+			], { timeout: EXTENSION_GIT_CHECKOUT_TIMEOUT_MS });
+			if (existsSync(resolve(projectDir, "package.json"))) {
+				await rewriteLocalExtensionSdkDependency(projectDir);
+				const packageManager = await resolvePackageManager(projectDir);
+				await execPackageManager(packageManager, packageManager === "pnpm" ? [
+					"--ignore-workspace",
+					"install",
+					"--no-frozen-lockfile",
+					"--ignore-scripts"
+				] : ["install", "--ignore-scripts"], {
+					cwd: projectDir,
+					timeout: Math.max(EXTENSION_GIT_CLONE_TIMEOUT_MS, 12e4)
+				});
+				await execPackageManager(packageManager, packageManager === "pnpm" ? [
+					"--ignore-workspace",
+					"run",
+					"--if-present",
+					"build"
+				] : [
+					"run",
+					"build",
+					"--if-present"
+				], {
+					cwd: projectDir,
+					timeout: Math.max(EXTENSION_GIT_CLONE_TIMEOUT_MS, 12e4)
+				});
+			}
+			const installedEntry = resolveInstalledRuntimeEntry(projectDir, entry.source.entry);
+			const entryFile = resolveExtensionEntryFile(projectDir, installedEntry);
+			if (!existsSync(entryFile)) return asJsonResponse({
+				success: false,
+				error: `Installed extension entry not found: ${installedEntry}`,
+				installDir,
+				projectDir,
+				expectedEntryFile: entryFile,
+				hint: "The registry source.entry or its compiled JS output must exist after clone/build before reloadExtensions can load it."
+			});
+			const metadataPath = await writeInstalledExtensionMetadata(isWorkflow ? "workflow" : "plugin", entry, projectDir, installedEntry);
+			const reloadResult = await this.ctx.reloadExtensions();
+			return asJsonResponse({
+				success: true,
+				installed: {
+					slug: entry.slug,
+					id: entry.id,
+					name: entry.meta.name,
+					repo: entry.source.repo,
+					commit: entry.source.commit,
+					installDir,
+					projectDir,
+					entry: installedEntry,
+					entryFile,
+					metadataPath
+				},
+				reload: {
+					addedTools: reloadResult.addedTools,
+					pluginCount: reloadResult.pluginCount,
+					workflowCount: reloadResult.workflowCount,
+					errors: reloadResult.errors,
+					warnings: reloadResult.warnings
+				}
+			});
+		} catch (error) {
+			logger.error("Failed to install extension:", error);
+			return asJsonResponse(serializeError(error));
+		}
+	}
+};
+//#endregion
+export { CoreMaintenanceHandlers, ExtensionManagementHandlers };