codelocal 1.5.0-beta.1

package/dist/mcp-hub.js

@@ -0,0 +1,508 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createHash, randomUUID } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { audit } from "./audit.js";
+const REGISTRY_VERSION = 1;
+const CATALOG_VERSION = 1;
+const MAX_CATALOG_TOOLS = Number(process.env.CODELOCAL_MCP_MAX_TOOLS ?? 5000);
+const MAX_STDERR_TAIL = 16 * 1024;
+const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+function normalizeRoot(value) {
+    return path.resolve(value);
+}
+function stateRoot() {
+    return process.env.CODELOCAL_STATE_DIR ?? path.join(os.homedir(), ".codelocal");
+}
+export function mcpStatePaths() {
+    const dir = path.join(stateRoot(), "mcp");
+    return {
+        dir,
+        registry: path.join(dir, "registry.json"),
+        catalog: path.join(dir, "catalog.json"),
+    };
+}
+async function ensurePrivateDir(dir) {
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        await fs.chmod(dir, 0o700).catch(() => undefined);
+}
+async function readJson(file, fallback) {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return fallback;
+        throw new Error(`Invalid CodeLocal MCP state file ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function writeJsonAtomic(file, value) {
+    await ensurePrivateDir(path.dirname(file));
+    const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    const payload = JSON.stringify(value, null, 2) + "\n";
+    await fs.writeFile(temp, payload, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    if (process.platform !== "win32")
+        await fs.chmod(temp, 0o600).catch(() => undefined);
+    await fs.rename(temp, file);
+}
+function validateName(name) {
+    if (!NAME_RE.test(name))
+        throw new Error("MCP name must match [a-zA-Z0-9][a-zA-Z0-9._-]{0,63}.");
+    return name;
+}
+function validateEnvName(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        throw new Error(`Invalid environment variable name: ${name}`);
+    return name;
+}
+function isLoopback(hostname) {
+    const host = hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "0.0.0.0";
+}
+function validateRemoteUrl(raw) {
+    const url = new URL(raw);
+    if (!["http:", "https:"].includes(url.protocol))
+        throw new Error("Remote MCP URL must use http or https.");
+    if (url.protocol === "http:" && !isLoopback(url.hostname) && process.env.CODELOCAL_MCP_ALLOW_INSECURE_HTTP !== "1") {
+        throw new Error("Remote MCP must use HTTPS unless it is localhost. Set CODELOCAL_MCP_ALLOW_INSECURE_HTTP=1 only for trusted development endpoints.");
+    }
+    return url.toString();
+}
+function materializeEnv(refs) {
+    if (!refs)
+        return undefined;
+    const output = {};
+    for (const [target, ref] of Object.entries(refs)) {
+        validateEnvName(target);
+        validateEnvName(ref.source);
+        const value = process.env[ref.source];
+        if (value == null)
+            throw new Error(`MCP requires environment variable ${ref.source} for ${target}.`);
+        output[target] = value;
+    }
+    return output;
+}
+function materializeHeaders(refs) {
+    if (!refs)
+        return undefined;
+    const headers = {};
+    for (const [header, ref] of Object.entries(refs)) {
+        validateEnvName(ref.source);
+        const value = process.env[ref.source];
+        if (value == null)
+            throw new Error(`MCP requires environment variable ${ref.source} for HTTP header ${header}.`);
+        headers[header] = `${ref.prefix ?? ""}${value}`;
+    }
+    return headers;
+}
+function normalizeConfig(input, previous) {
+    const name = validateName(input.name.trim());
+    const now = Date.now();
+    if (input.transport === "stdio") {
+        if (!input.command?.trim())
+            throw new Error("stdio MCP requires a command.");
+        if (input.url)
+            throw new Error("stdio MCP cannot also define a URL.");
+    }
+    else {
+        if (!input.url)
+            throw new Error("remote MCP requires a URL.");
+        validateRemoteUrl(input.url);
+        if (input.command)
+            throw new Error("remote MCP cannot also define a command.");
+    }
+    return {
+        ...input,
+        name,
+        enabled: input.enabled !== false,
+        workspaceRoot: input.scope === "workspace" ? normalizeRoot(input.workspaceRoot ?? process.cwd()) : undefined,
+        command: input.command?.trim(),
+        args: input.args?.map(String),
+        url: input.url ? validateRemoteUrl(input.url) : undefined,
+        addedAt: previous?.addedAt ?? now,
+        updatedAt: now,
+    };
+}
+function configKey(server) {
+    if (server.scope === "global")
+        return `global:${server.name}`;
+    const rootHash = createHash("sha256").update(server.workspaceRoot ?? "").digest("hex").slice(0, 20);
+    return `workspace:${server.name}:${rootHash}`;
+}
+function effectiveServers(registry, workspaceRoot) {
+    const byName = new Map();
+    for (const server of registry.servers) {
+        if (server.scope === "global")
+            byName.set(server.name, server);
+    }
+    for (const server of registry.servers) {
+        if (server.scope === "workspace" && server.workspaceRoot === workspaceRoot)
+            byName.set(server.name, server);
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function tokens(value) {
+    return value.toLowerCase().split(/[^a-z0-9_./:-]+/).filter(Boolean);
+}
+function searchScore(tool, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return 1;
+    const hayName = `${tool.server}.${tool.name}`.toLowerCase();
+    const title = (tool.title ?? "").toLowerCase();
+    const description = (tool.description ?? "").toLowerCase();
+    const schema = JSON.stringify(tool.inputSchema ?? {}).toLowerCase();
+    let score = 0;
+    if (hayName === q || tool.name.toLowerCase() === q)
+        score += 100;
+    if (hayName.includes(q))
+        score += 40;
+    if (title.includes(q))
+        score += 24;
+    if (description.includes(q))
+        score += 12;
+    for (const term of tokens(q)) {
+        if (tool.name.toLowerCase() === term)
+            score += 25;
+        else if (tool.name.toLowerCase().includes(term))
+            score += 14;
+        if (tool.server.toLowerCase().includes(term))
+            score += 9;
+        if (title.includes(term))
+            score += 7;
+        if (description.includes(term))
+            score += 4;
+        if (schema.includes(term))
+            score += 1;
+    }
+    return score;
+}
+function safeConnectDetail(config) {
+    if (config.transport === "stdio")
+        return `stdio ${config.command ?? config.name}`;
+    try {
+        const url = new URL(config.url ?? "");
+        url.username = "";
+        url.password = "";
+        url.search = "";
+        url.hash = "";
+        return `http ${url.toString()}`;
+    }
+    catch {
+        return `http ${config.name}`;
+    }
+}
+function defaultRuntimeConnectGuard(workspaceRoot) {
+    if (!process.env.SERVER_URL || !process.env.PROJECT_ROOT || process.env.CODELOCAL_MCP_START_APPROVAL === "0")
+        return undefined;
+    return async (config) => {
+        await audit({
+            event: "policy.mcp_runtime_start_blocked",
+            workspaceKey: workspaceRoot,
+            riskLevel: "REVIEW",
+            status: "blocked",
+            detail: { server: config.name, transport: config.transport, rule: `mcp-runtime:${config.name}` },
+        });
+        throw new Error(`Starting installed MCP runtime requires chat-mediated approval. Use mcp_call from ChatGPT: ${config.name}`);
+    };
+}
+export class McpHub {
+    workspaceRoot;
+    beforeConnect;
+    sessions = new Map();
+    constructor(workspaceRoot = process.cwd(), beforeConnect) {
+        this.workspaceRoot = workspaceRoot;
+        this.beforeConnect = beforeConnect;
+        this.workspaceRoot = normalizeRoot(workspaceRoot);
+        this.beforeConnect ??= defaultRuntimeConnectGuard(this.workspaceRoot);
+    }
+    async registry() {
+        const value = await readJson(mcpStatePaths().registry, { version: REGISTRY_VERSION, servers: [] });
+        if (value.version !== REGISTRY_VERSION || !Array.isArray(value.servers))
+            throw new Error("Unsupported CodeLocal MCP registry format.");
+        return value;
+    }
+    async catalogFile() {
+        const value = await readJson(mcpStatePaths().catalog, { version: CATALOG_VERSION, tools: [] });
+        if (value.version !== CATALOG_VERSION || !Array.isArray(value.tools))
+            throw new Error("Unsupported CodeLocal MCP catalog format.");
+        const tools = value.tools.filter((tool) => typeof tool?.serverKey === "string" && typeof tool?.server === "string" && typeof tool?.name === "string");
+        return { version: CATALOG_VERSION, tools };
+    }
+    async addServer(input) {
+        const registry = await this.registry();
+        const previous = registry.servers.find((server) => server.name === input.name && server.scope === input.scope && (server.scope === "global" || server.workspaceRoot === normalizeRoot(input.workspaceRoot ?? this.workspaceRoot)));
+        const normalized = normalizeConfig({ ...input, workspaceRoot: input.scope === "workspace" ? (input.workspaceRoot ?? this.workspaceRoot) : undefined }, previous);
+        registry.servers = registry.servers.filter((server) => !(server.name === normalized.name && server.scope === normalized.scope && (server.scope === "global" || server.workspaceRoot === normalized.workspaceRoot)));
+        registry.servers.push(normalized);
+        registry.servers.sort((a, b) => `${a.scope}:${a.name}:${a.workspaceRoot ?? ""}`.localeCompare(`${b.scope}:${b.name}:${b.workspaceRoot ?? ""}`));
+        await writeJsonAtomic(mcpStatePaths().registry, registry);
+        const catalog = await this.catalogFile();
+        const key = configKey(normalized);
+        const filtered = catalog.tools.filter((tool) => tool.serverKey !== key);
+        if (filtered.length !== catalog.tools.length)
+            await writeJsonAtomic(mcpStatePaths().catalog, { version: CATALOG_VERSION, tools: filtered });
+        await this.disconnect(normalized.name);
+        return this.publicServer(normalized);
+    }
+    async removeServer(name, scope) {
+        validateName(name);
+        const registry = await this.registry();
+        const removedConfigs = [];
+        const kept = [];
+        for (const server of registry.servers) {
+            const matchesName = server.name === name;
+            const matchesScope = !scope || server.scope === scope;
+            const visibleWorkspaceConfig = server.scope !== "workspace" || server.workspaceRoot === this.workspaceRoot;
+            if (matchesName && matchesScope && visibleWorkspaceConfig)
+                removedConfigs.push(server);
+            else
+                kept.push(server);
+        }
+        registry.servers = kept;
+        if (removedConfigs.length)
+            await writeJsonAtomic(mcpStatePaths().registry, registry);
+        if (removedConfigs.length) {
+            const removedKeys = new Set(removedConfigs.map(configKey));
+            const catalog = await this.catalogFile();
+            const filtered = catalog.tools.filter((tool) => !removedKeys.has(tool.serverKey));
+            if (filtered.length !== catalog.tools.length)
+                await writeJsonAtomic(mcpStatePaths().catalog, { version: CATALOG_VERSION, tools: filtered });
+        }
+        await this.disconnect(name);
+        return { removed: removedConfigs.length };
+    }
+    async listServers() {
+        const registry = await this.registry();
+        const visible = effectiveServers(registry, this.workspaceRoot);
+        const catalog = await this.catalogFile();
+        return visible.map((server) => {
+            const key = configKey(server);
+            return {
+                ...this.publicServer(server),
+                toolsCached: catalog.tools.filter((tool) => tool.serverKey === key).length,
+                connected: this.sessions.has(server.name),
+            };
+        });
+    }
+    async serverInfo(name) {
+        const config = await this.resolveServer(name);
+        const key = configKey(config);
+        const catalog = await this.catalogFile();
+        return {
+            ...this.publicServer(config),
+            connected: this.sessions.has(name),
+            tools: catalog.tools.filter((tool) => tool.serverKey === key),
+        };
+    }
+    async probe(name) {
+        const config = await this.resolveServer(name);
+        const client = await this.getOrConnect(config);
+        const tools = await this.fetchAllTools(client);
+        await this.replaceCatalogForServer(config, tools);
+        return {
+            server: this.publicServer(config),
+            connected: true,
+            toolCount: tools.length,
+            tools: tools.slice(0, 100).map((tool) => ({ name: tool.name, title: tool.title, description: tool.description })),
+            truncated: tools.length > 100,
+        };
+    }
+    async searchTools(query, options = {}) {
+        const limit = Math.max(1, Math.min(options.limit ?? 8, 50));
+        if (options.refresh && options.server)
+            await this.probe(options.server);
+        const registry = await this.registry();
+        const effective = effectiveServers(registry, this.workspaceRoot).filter((server) => server.enabled);
+        const effectiveByName = new Map(effective.map((server) => [server.name, server]));
+        if (options.server) {
+            const config = await this.resolveServer(options.server);
+            const key = configKey(config);
+            const existing = await this.catalogFile();
+            if (!existing.tools.some((tool) => tool.serverKey === key))
+                await this.probe(options.server);
+        }
+        const catalog = await this.catalogFile();
+        const allowedKeys = new Set(effective.map(configKey));
+        const ranked = catalog.tools
+            .filter((tool) => allowedKeys.has(tool.serverKey) && (!options.server || tool.server === options.server))
+            .map((tool) => ({ ...tool, score: searchScore(tool, query) }))
+            .filter((tool) => !query.trim() || tool.score > 0)
+            .sort((a, b) => b.score - a.score || `${a.server}.${a.name}`.localeCompare(`${b.server}.${b.name}`))
+            .slice(0, limit);
+        return {
+            query,
+            results: ranked.map((tool) => ({
+                server: tool.server,
+                tool: tool.name,
+                title: tool.title,
+                description: tool.description,
+                score: tool.score,
+                readOnlyHint: tool.annotations?.readOnlyHint === true,
+            })),
+            catalogToolCount: catalog.tools.filter((tool) => allowedKeys.has(tool.serverKey)).length,
+            installedServerCount: effectiveByName.size,
+            recommendation: ranked.length ? "Call mcp_tool_info before mcp_call when you need the exact input schema." : "Probe a newly installed MCP with explicit local approval, then search again.",
+        };
+    }
+    async toolInfo(server, tool) {
+        const config = await this.resolveServer(server);
+        const key = configKey(config);
+        let catalog = await this.catalogFile();
+        let found = catalog.tools.find((item) => item.serverKey === key && item.name === tool);
+        if (!found) {
+            await this.probe(server);
+            catalog = await this.catalogFile();
+            found = catalog.tools.find((item) => item.serverKey === key && item.name === tool);
+        }
+        if (!found)
+            throw new Error(`MCP tool not found: ${server}.${tool}`);
+        return found;
+    }
+    async callTool(server, tool, args = {}) {
+        const config = await this.resolveServer(server);
+        const info = await this.toolInfo(server, tool);
+        const client = await this.getOrConnect(config);
+        const session = this.sessions.get(server);
+        if (session)
+            session.lastUsedAt = Date.now();
+        const result = await client.callTool({ name: info.name, arguments: args });
+        return {
+            server,
+            tool,
+            readOnlyHint: info.annotations?.readOnlyHint === true,
+            result,
+        };
+    }
+    async disconnect(name) {
+        const session = this.sessions.get(name);
+        if (!session)
+            return;
+        this.sessions.delete(name);
+        await session.client.close().catch(() => undefined);
+    }
+    async shutdown() {
+        await Promise.all([...this.sessions.keys()].map((name) => this.disconnect(name)));
+    }
+    publicServer(server) {
+        return {
+            name: server.name,
+            enabled: server.enabled,
+            scope: server.scope,
+            workspaceRoot: server.scope === "workspace" ? server.workspaceRoot : undefined,
+            transport: server.transport,
+            command: server.command,
+            args: server.args,
+            cwd: server.cwd,
+            env: server.env ? Object.fromEntries(Object.entries(server.env).map(([key, ref]) => [key, ref.source])) : undefined,
+            url: server.url,
+            headers: server.headers ? Object.fromEntries(Object.entries(server.headers).map(([key, ref]) => [key, { source: ref.source, prefix: ref.prefix ? "[configured]" : undefined }])) : undefined,
+            addedAt: server.addedAt,
+            updatedAt: server.updatedAt,
+        };
+    }
+    async resolveServer(name) {
+        validateName(name);
+        const registry = await this.registry();
+        const workspace = registry.servers.find((server) => server.name === name && server.scope === "workspace" && server.workspaceRoot === this.workspaceRoot);
+        const global = registry.servers.find((server) => server.name === name && server.scope === "global");
+        const config = workspace ?? global;
+        if (!config)
+            throw new Error(`MCP server not installed for this workspace: ${name}`);
+        if (!config.enabled)
+            throw new Error(`MCP server is disabled: ${name}`);
+        return config;
+    }
+    async getOrConnect(config) {
+        const existing = this.sessions.get(config.name);
+        if (existing)
+            return existing.client;
+        await this.beforeConnect?.(config);
+        const client = new Client({ name: "codelocal-mcp-hub", version: "1.0.0" });
+        let transport;
+        if (config.transport === "stdio") {
+            const cwd = config.cwd ? (path.isAbsolute(config.cwd) ? config.cwd : path.resolve(config.scope === "workspace" ? this.workspaceRoot : process.cwd(), config.cwd)) : (config.scope === "workspace" ? this.workspaceRoot : undefined);
+            const stdio = new StdioClientTransport({
+                command: config.command,
+                args: config.args ?? [],
+                cwd,
+                env: materializeEnv(config.env),
+                stderr: "pipe",
+            });
+            transport = stdio;
+            const session = { client, transport, connectedAt: Date.now(), lastUsedAt: Date.now(), stderrTail: "" };
+            stdio.stderr?.on("data", (chunk) => {
+                session.stderrTail = (session.stderrTail + String(chunk)).slice(-MAX_STDERR_TAIL);
+            });
+            this.sessions.set(config.name, session);
+        }
+        else {
+            const headers = materializeHeaders(config.headers);
+            transport = new StreamableHTTPClientTransport(new URL(config.url), headers ? { requestInit: { headers } } : undefined);
+            this.sessions.set(config.name, { client, transport, connectedAt: Date.now(), lastUsedAt: Date.now(), stderrTail: "" });
+        }
+        try {
+            await client.connect(transport);
+            return client;
+        }
+        catch (error) {
+            const session = this.sessions.get(config.name);
+            this.sessions.delete(config.name);
+            await client.close().catch(() => undefined);
+            const stderr = session?.stderrTail.trim();
+            throw new Error(`Failed to connect MCP ${config.name}: ${error instanceof Error ? error.message : String(error)}${stderr ? `\nMCP stderr:\n${stderr}` : ""}`);
+        }
+    }
+    async fetchAllTools(client) {
+        const tools = [];
+        let cursor;
+        do {
+            const result = await client.listTools(cursor ? { cursor } : undefined);
+            for (const tool of result.tools) {
+                tools.push({
+                    name: tool.name,
+                    title: tool.title,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                    outputSchema: tool.outputSchema,
+                    annotations: tool.annotations,
+                    discoveredAt: Date.now(),
+                });
+                if (tools.length > MAX_CATALOG_TOOLS)
+                    throw new Error(`MCP catalog exceeds CODELOCAL_MCP_MAX_TOOLS=${MAX_CATALOG_TOOLS}.`);
+            }
+            cursor = result.nextCursor;
+        } while (cursor);
+        return tools;
+    }
+    async replaceCatalogForServer(server, tools) {
+        const catalog = await this.catalogFile();
+        const key = configKey(server);
+        const others = catalog.tools.filter((tool) => tool.serverKey !== key);
+        const next = [...others, ...tools.map((tool) => ({ ...tool, serverKey: key, server: server.name }))];
+        if (next.length > MAX_CATALOG_TOOLS)
+            throw new Error(`MCP catalog exceeds CODELOCAL_MCP_MAX_TOOLS=${MAX_CATALOG_TOOLS}.`);
+        next.sort((a, b) => `${a.serverKey}.${a.name}`.localeCompare(`${b.serverKey}.${b.name}`));
+        await writeJsonAtomic(mcpStatePaths().catalog, { version: CATALOG_VERSION, tools: next });
+    }
+}
+export function parseEnvReference(value) {
+    const [targetRaw, sourceRaw] = value.includes("=") ? value.split("=", 2) : [value, value];
+    const target = validateEnvName(targetRaw.trim());
+    const source = validateEnvName(sourceRaw.trim());
+    return [target, { source }];
+}
+export function parseHeaderEnvReference(value) {
+    const index = value.indexOf("=");
+    if (index <= 0)
+        throw new Error("Header env format must be Header-Name=ENV_VAR.");
+    const header = value.slice(0, index).trim();
+    const source = validateEnvName(value.slice(index + 1).trim());
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(header))
+        throw new Error(`Invalid HTTP header name: ${header}`);
+    return [header, { source }];
+}

package/dist/native-watcher.js

@@ -0,0 +1,148 @@
+import { EventEmitter } from "node:events";
+import path from "node:path";
+const COMMON_IGNORES = [
+    ".git/**",
+    "node_modules/**",
+    ".next/**",
+    "dist/**",
+    "build/**",
+    "target/**",
+    ".venv/**",
+    "venv/**",
+    "coverage/**",
+    ".cache/**",
+    ".turbo/**",
+    ".dart_tool/**",
+    ".gradle/**",
+    "Pods/**",
+    "DerivedData/**",
+];
+function backendForPlatform() {
+    if (process.platform === "darwin")
+        return "fs-events";
+    if (process.platform === "linux")
+        return "inotify";
+    if (process.platform === "win32")
+        return "windows";
+    return undefined;
+}
+function isPlainDirectoryTarget(targets) {
+    return typeof targets === "string" && !/[*!?{}[\]]/.test(targets);
+}
+function ignoredByOption(ignored, absolutePath) {
+    if (!ignored)
+        return false;
+    if (typeof ignored === "function") {
+        try {
+            return !!ignored(absolutePath);
+        }
+        catch {
+            return false;
+        }
+    }
+    const values = Array.isArray(ignored) ? ignored : [ignored];
+    const normalized = absolutePath.replace(/\\/g, "/");
+    return values.some((value) => typeof value === "string" && normalized.includes(value.replace(/\*+/g, "")));
+}
+function mapEvent(type) {
+    if (type === "create")
+        return "add";
+    if (type === "delete")
+        return "unlink";
+    return "change";
+}
+/**
+ * Patch Chokidar's singleton `watch` entry point before client-v2 is imported.
+ * CodeLocal keeps the existing watcher consumer API, while large workspaces use
+ * @parcel/watcher native recursive backends (FSEvents/inotify/Windows) whenever
+ * the dependency is available. A shallow Chokidar fallback remains.
+ */
+export function installNativeWatcherAdapter(chokidar, options = {}) {
+    const originalWatch = chokidar.watch.bind(chokidar);
+    const fallbackDepth = Math.max(0, options.fallbackDepth ?? 2);
+    const emitLog = options.log ?? ((level, event, detail = {}) => {
+        const line = JSON.stringify({ ts: new Date().toISOString(), level, event, ...detail });
+        if (level === "error")
+            console.error(line);
+        else if (level === "warn")
+            console.warn(line);
+        else
+            console.log(line);
+    });
+    chokidar.watch = (targets, watchOptions = {}) => {
+        if (!isPlainDirectoryTarget(targets)) {
+            return originalWatch(targets, { ...watchOptions, depth: watchOptions.depth ?? fallbackDepth, followSymlinks: false });
+        }
+        const root = path.resolve(targets);
+        const emitter = new EventEmitter();
+        let subscription = null;
+        let fallback = null;
+        let closed = false;
+        const close = async () => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                await subscription?.unsubscribe();
+            }
+            catch { }
+            try {
+                await fallback?.close?.();
+            }
+            catch { }
+            emitter.removeAllListeners();
+        };
+        emitter.close = close;
+        emitter.unwatch = close;
+        emitter.add = () => emitter;
+        const startFallback = (cause) => {
+            if (closed)
+                return;
+            emitLog("warn", "workspace.watcher_fallback", {
+                backend: "chokidar-bounded",
+                depth: fallbackDepth,
+                reason: cause instanceof Error ? cause.message : String(cause),
+            });
+            fallback = originalWatch(root, {
+                ...watchOptions,
+                depth: watchOptions.depth ?? fallbackDepth,
+                followSymlinks: false,
+            });
+            fallback.on("all", (event, changed) => emitter.emit("all", event, changed));
+            fallback.on("error", (error) => emitter.emit("error", error));
+            fallback.on("ready", () => emitter.emit("ready"));
+        };
+        queueMicrotask(async () => {
+            try {
+                const dynamicImport = new Function("m", "return import(m)");
+                const parcel = await dynamicImport("@parcel/watcher");
+                if (closed)
+                    return;
+                const backend = backendForPlatform();
+                subscription = await parcel.subscribe(root, (error, events = []) => {
+                    if (closed)
+                        return;
+                    if (error) {
+                        emitter.emit("error", error);
+                        return;
+                    }
+                    for (const item of events) {
+                        const absolute = path.resolve(item.path);
+                        if (ignoredByOption(watchOptions.ignored, absolute))
+                            continue;
+                        const event = mapEvent(item.type);
+                        emitter.emit("all", event, absolute);
+                        emitter.emit(event, absolute);
+                    }
+                }, { ignore: COMMON_IGNORES, ...(backend ? { backend } : {}) });
+                emitLog("info", "workspace.watcher_ready", { backend: backend ?? "native-default", recursive: true, root });
+                emitter.emit("ready");
+            }
+            catch (error) {
+                startFallback(error);
+            }
+        });
+        return emitter;
+    };
+    return { preferredBackend: backendForPlatform() ?? "native-default", fallbackDepth };
+}