@akira-tl/forgerelay 0.8.8 → 0.8.10

package/dist/cli.js

@@ -8,23 +8,21 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as prompts from "@clack/prompts";
-import { getShellConfig } from "@earendil-works/pi-coding-agent";
-import { satisfies } from "semver";
-import { loadConfig } from "./config.js";
-import { runHooksCommand } from "./hook-cli.js";
+import { loadConfig } from "./runtime/config/config.js";
+import { runInit } from "./cli/init.js";
+import { runHooksCommand } from "./mcp/hooks/hook-cli.js";
 import { executeSubagentSession } from "./subagents/sessions/execution.js";
 import { SubagentDeliveryMailbox } from "./subagents/sessions/delivery-mailbox.js";
 import { SubagentSessionManager } from "./subagents/sessions/manager.js";
 import { formatSubagentProviderAvailabilitySummary } from "./subagents/providers/availability.js";
 import { parseSubagentRunArgs } from "./subagents/cli-target.js";
-import { ensureForgeRelayInstanceId, generateInstanceId, generateOwnerToken, loadForgeRelayFiles, removeForgeRelayRemote, renameForgeRelayRemote, resolveSubagentsFlag, writeForgeRelayAuth, writeForgeRelayConfig, writeForgeRelayRemote, } from "./user-config.js";
-import { expandHomePath } from "./roots.js";
-import { shutdownHttpServer } from "./server-shutdown.js";
-import { publicEndpointUrl } from "./oauth/public-url.js";
-import { authenticateRemote, defaultRemoteAlias, isRemoteMcpUnauthorized, normalizeRemoteServiceTarget, refreshRemoteAuthentication, verifyRemoteMcp, } from "./remote-auth.js";
-import { defaultSshRouteAlias, parseSshRoute, readRemoteOwnerToken, withRemoteServiceEndpoint, } from "./remote-transport.js";
+import { ensureForgeRelayInstanceId, loadForgeRelayFiles, removeForgeRelayRemote, renameForgeRelayRemote, writeForgeRelayConfig, writeForgeRelayRemote, } from "./runtime/config/user-config.js";
+import { shutdownHttpServer } from "./mcp/server/transport/server-shutdown.js";
+import { publicEndpointUrl } from "./mcp/oauth/public-url.js";
+import { authenticateRemote, defaultRemoteAlias, isRemoteMcpUnauthorized, normalizeRemoteServiceTarget, refreshRemoteAuthentication, verifyRemoteMcp, } from "./workspaces/relay/auth/remote-auth.js";
+import { defaultSshRouteAlias, parseSshRoute, readRemoteOwnerToken, withRemoteServiceEndpoint, } from "./workspaces/relay/transport/remote-transport.js";
+import { assertSupportedNode, checkBashShell, checkGitAvailable, checkSqliteNative, nodeVersionStatus, normalizeOptionalPublicBaseUrl, } from "./cli/setup-support.js";
 const require = createRequire(import.meta.url);
-const SUPPORTED_NODE_RANGE = ">=20.12 <27";
 async function main(argv) {
     assertSupportedNode();
     const [rawCommand, ...args] = argv;
@@ -74,11 +72,11 @@ function normalizeCommand(command) {
 async function ensureConfigured() {
     const files = loadForgeRelayFiles();
     if (files.configExists && files.authExists) {
-        ensureForgeRelayInstanceId();
+        await ensureForgeRelayInstanceId();
         return;
     }
     if (process.env.FORGERELAY_OAUTH_OWNER_TOKEN) {
-        ensureForgeRelayInstanceId();
+        await ensureForgeRelayInstanceId();
         return;
     }
     if (!input.isTTY || !output.isTTY) {
@@ -93,92 +91,6 @@ async function ensureConfigured() {
     }
     await runInit({ force: false });
 }
-async function runInit({ force }) {
-    const files = loadForgeRelayFiles();
-    if (!force && files.configExists && files.authExists) {
-        prompts.log.info(`ForgeRelay is already configured at ${files.dir}`);
-        prompts.log.info("Run `forgerelay init --force` to update it.");
-        return;
-    }
-    try {
-        prompts.intro("ForgeRelay setup");
-        const defaultRoots = files.config.allowedRoots?.join(", ") || process.cwd();
-        const rootsAnswer = await textPrompt({
-            message: `Where are your projects located? Press Enter to use ${defaultRoots}`,
-            placeholder: defaultRoots,
-            defaultValue: defaultRoots,
-            validate: (value) => value?.trim() ? undefined : "Enter at least one project root.",
-        });
-        const allowedRoots = rootsAnswer
-            .split(",")
-            .map((root) => resolve(expandHomePath(root.trim())))
-            .filter(Boolean);
-        const defaultPort = String(files.config.port ?? 7676);
-        const portAnswer = await textPrompt({
-            message: `Which local port should ForgeRelay use? Press Enter to use ${defaultPort}`,
-            placeholder: defaultPort,
-            defaultValue: defaultPort,
-            validate: validatePort,
-        });
-        const port = Number(portAnswer);
-        prompts.note([
-            "ForgeRelay needs one or more public base URLs so ChatGPT or Claude can reach this MCP server.",
-            "Create a tunnel or reverse proxy with Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel, or your own HTTPS proxy.",
-            "Each URL may include its own route prefix. Separate multiple URLs with commas; the first is canonical.",
-            "",
-            "Example: https://forge.example.com/forgerelay/main, https://alias.example.com/relay",
-        ].join("\n"), "Public URL required");
-        const defaultPublicBaseUrls = Array.isArray(files.config.publicBaseUrl)
-            ? files.config.publicBaseUrl.join(", ")
-            : files.config.publicBaseUrl ?? "";
-        const publicBaseUrls = normalizePublicBaseUrlsInput(await textPrompt({
-            message: defaultPublicBaseUrls
-                ? `What are the public base URLs? Press Enter to keep ${defaultPublicBaseUrls}`
-                : "What are the public base URLs?",
-            placeholder: defaultPublicBaseUrls || "https://your-tunnel-host.example.com",
-            defaultValue: defaultPublicBaseUrls,
-            validate: validateRequiredPublicBaseUrls,
-        }));
-        const publicBaseUrl = compactPublicBaseUrlConfig(publicBaseUrls);
-        const config = {
-            host: files.config.host ?? "127.0.0.1",
-            port,
-            allowedRoots,
-            publicBaseUrl,
-            allowedHosts: files.config.allowedHosts,
-            workflowInstructions: files.config.workflowInstructions,
-            appendInstructions: files.config.appendInstructions,
-            subagents: resolveSubagentsFlag(files.config),
-        };
-        const auth = {
-            ...files.auth,
-            ownerToken: files.auth.ownerToken ?? generateOwnerToken(),
-            instanceId: files.auth.instanceId ?? generateInstanceId(),
-        };
-        const configPath = writeForgeRelayConfig(config);
-        const authPath = writeForgeRelayAuth(auth);
-        const lines = [
-            `Config: ${configPath}`,
-            `Auth: ${authPath}`,
-            `Local MCP URL: http://${config.host}:${config.port}/mcp`,
-            ...publicBaseUrls.map((baseUrl, index) => `${index === 0 ? "Public MCP URL" : "Public MCP alias"}: ${publicEndpointUrl(baseUrl, "mcp").toString()}`),
-        ];
-        prompts.note(lines.join("\n"), "ForgeRelay configured");
-        prompts.note([
-            `Owner password: ${auth.ownerToken}`,
-            "Use this when ChatGPT or Claude asks you to approve ForgeRelay access.",
-            `Stored at: ${authPath}`,
-        ].join("\n"), "Owner password");
-        prompts.outro("Run `forgerelay serve` to start the MCP server.");
-    }
-    catch (error) {
-        if (error instanceof SetupCancelledError) {
-            prompts.cancel("Setup cancelled");
-            return;
-        }
-        throw error;
-    }
-}
 async function serve() {
     const sqliteStatus = checkSqliteNative();
     if (sqliteStatus !== "ok") {
@@ -195,7 +107,7 @@ async function serve() {
     const { app, close, subagentProviders } = createServer(config);
     const httpServer = app.listen(config.port, config.host, () => {
         console.log(`forgerelay listening on http://${config.host}:${config.port}/mcp`);
-        console.log(`public base url: ${config.publicBaseUrl}`);
+        console.log(`client-facing base url: ${config.publicBaseUrl}`);
         console.log(`allowed roots: ${config.allowedRoots.join(", ")}`);
         console.log(`allowed hosts: ${config.allowedHosts.join(", ")}`);
         if (config.allowedHosts.includes("*")) {
@@ -316,7 +228,7 @@ async function runAuthCommand(args) {
         if (!fromAlias || !toAlias || extra.length > 0) {
             throw new Error("Usage: forgerelay auth rename <old-alias> <new-alias>");
         }
-        renameForgeRelayRemote(fromAlias, toAlias);
+        await renameForgeRelayRemote(fromAlias, toAlias);
         console.log(`Renamed remote ${fromAlias} to ${toAlias}.`);
         return;
     }
@@ -324,7 +236,7 @@ async function runAuthCommand(args) {
         const [alias, ...extra] = rest;
         if (!alias || extra.length > 0)
             throw new Error("Usage: forgerelay auth remove <alias>");
-        removeForgeRelayRemote(alias);
+        await removeForgeRelayRemote(alias);
         console.log(`Removed remote ${alias}.`);
         return;
     }
@@ -341,7 +253,7 @@ async function runAuthCommand(args) {
             let refreshed = false;
             if (remote.accessTokenExpiresAt <= Math.floor(Date.now() / 1000)) {
                 remote = await refreshRemoteAuthentication(remote, endpoint);
-                writeForgeRelayRemote(alias, remote);
+                await writeForgeRelayRemote(alias, remote);
                 refreshed = true;
             }
             try {
@@ -351,7 +263,7 @@ async function runAuthCommand(args) {
                 if (refreshed || !isRemoteMcpUnauthorized(error))
                     throw error;
                 remote = await refreshRemoteAuthentication(remote, endpoint);
-                writeForgeRelayRemote(alias, remote);
+                await writeForgeRelayRemote(alias, remote);
                 await verifyRemoteMcp(remote, endpoint);
             }
         });
@@ -378,9 +290,9 @@ async function runAuthCommand(args) {
         : defaultRemoteAlias(remote.target);
     const alias = parsed.alias?.trim() || existingAlias || defaultAlias;
     if (!files.auth.instanceId) {
-        ensureForgeRelayInstanceId();
+        await ensureForgeRelayInstanceId();
     }
-    writeForgeRelayRemote(alias, remote);
+    await writeForgeRelayRemote(alias, remote);
     console.log(`Authenticated remote ${alias} (${remote.instanceId}).`);
 }
 async function runDoctor() {
@@ -396,16 +308,17 @@ async function runDoctor() {
     console.log(`SQLite native dependency: ${checkSqliteNative()}`);
     try {
         const config = loadConfig();
-        console.log(`Local MCP URL: http://${config.host}:${config.port}/mcp`);
-        console.log(`Public base URLs: ${config.publicBaseUrls.join(", ")}`);
-        console.log(`Public base URL: ${config.publicBaseUrl}`);
-        console.log(`Public MCP URL: ${publicEndpointUrl(config.publicBaseUrl, "mcp").toString()}`);
+        console.log(`Bind MCP URL: http://${config.host}:${config.port}/mcp`);
+        console.log(`Client-facing base URLs: ${config.publicBaseUrls.join(", ")}`);
+        console.log(`Client-facing base URL: ${config.publicBaseUrl}`);
+        console.log(`Client-facing MCP URL: ${publicEndpointUrl(config.publicBaseUrl, "mcp").toString()}`);
         console.log(`Tool mode: ${config.toolMode}`);
         console.log(`Widgets: ${config.widgets}`);
         console.log(`Trust proxy: ${config.logging.trustProxy ? "one hop" : "off"}`);
         console.log(`Artifacts: ${config.artifactsEnabled ? "enabled" : "disabled"}`);
         console.log(`Subagents: ${config.subagents ? "enabled" : "disabled"}`);
         console.log(`Skills: ${config.skillsEnabled ? "enabled" : "disabled"}`);
+        console.log(`Agent-managed Language Server install: ${config.allowAgentLanguageServerInstall ? "enabled" : "disabled"}`);
         console.log(`Allowed roots: ${config.allowedRoots.join(", ")}`);
         console.log(`Allowed hosts: ${config.allowedHosts.join(", ")}`);
     }
@@ -641,112 +554,6 @@ function printVersion() {
     }
     console.log(packageJson.version);
 }
-function isNullConfigValue(value) {
-    const normalized = value.trim().toLowerCase();
-    return !normalized || normalized === "null" || normalized === "none";
-}
-function normalizeOptionalPublicBaseUrl(value) {
-    const trimmed = value.trim();
-    if (isNullConfigValue(trimmed))
-        return null;
-    return compactPublicBaseUrlConfig(normalizePublicBaseUrlsInput(trimmed));
-}
-function normalizePublicBaseUrlsInput(value) {
-    const entries = value
-        .split(",")
-        .map((entry) => entry.trim())
-        .filter(Boolean);
-    if (entries.length === 0)
-        throw new Error("Enter at least one public base URL.");
-    return Array.from(new Set(entries.map((entry) => normalizePublicBaseUrl(entry))));
-}
-function compactPublicBaseUrlConfig(baseUrls) {
-    return baseUrls.length === 1 ? baseUrls[0] : baseUrls;
-}
-function normalizePublicBaseUrl(value) {
-    const trimmed = value.trim();
-    const parsed = new URL(trimmed);
-    parsed.hash = "";
-    parsed.search = "";
-    parsed.pathname = parsed.pathname.replace(/\/+$/, "");
-    return parsed.toString().replace(/\/$/, "");
-}
-async function textPrompt(options) {
-    const result = await prompts.text({
-        ...options,
-        validate: (value) => options.validate?.(value?.trim() ? value : options.defaultValue),
-    });
-    if (prompts.isCancel(result))
-        throw new SetupCancelledError();
-    const value = String(result).trim();
-    return value || options.defaultValue;
-}
-function validatePort(value) {
-    const port = Number(value);
-    return Number.isInteger(port) && port >= 1 && port <= 65535
-        ? undefined
-        : "Enter a port between 1 and 65535.";
-}
-function validateRequiredPublicBaseUrls(value) {
-    const trimmed = value?.trim() ?? "";
-    if (!trimmed)
-        return "Enter at least one public base URL from your tunnel or reverse proxy.";
-    try {
-        normalizePublicBaseUrlsInput(trimmed);
-        return undefined;
-    }
-    catch (error) {
-        return error instanceof Error ? error.message : String(error);
-    }
-}
-function assertSupportedNode() {
-    if (satisfies(process.versions.node, SUPPORTED_NODE_RANGE))
-        return;
-    throw new Error([
-        `ForgeRelay requires Node ${SUPPORTED_NODE_RANGE}.`,
-        `Current Node: ${process.version}`,
-        "",
-        "Install Node 22 LTS or use a version manager such as nvm, fnm, or mise.",
-    ].join("\n"));
-}
-function nodeVersionStatus() {
-    return satisfies(process.versions.node, SUPPORTED_NODE_RANGE)
-        ? `supported ${SUPPORTED_NODE_RANGE}`
-        : `unsupported, requires ${SUPPORTED_NODE_RANGE}`;
-}
-class SetupCancelledError extends Error {
-}
-function checkSqliteNative() {
-    try {
-        const Database = require("better-sqlite3");
-        const db = new Database(":memory:");
-        db.close();
-        return "ok";
-    }
-    catch (error) {
-        return error instanceof Error ? error.message : String(error);
-    }
-}
-function checkGitAvailable() {
-    try {
-        const { execFileSync } = require("node:child_process");
-        return execFileSync("git", ["--version"], { encoding: "utf8" }).trim();
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return `unavailable (${message})`;
-    }
-}
-function checkBashShell() {
-    try {
-        const { shell, args } = getShellConfig();
-        return `${shell} ${args.join(" ")}`;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return `unavailable (${message})`;
-    }
-}
 main(process.argv.slice(2)).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;

package/dist/lsp/code-intelligence.js

@@ -3,9 +3,9 @@ import { readFile, realpath } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createMessageConnection } from "vscode-jsonrpc/node";
-import { DefinitionRequest, DocumentDiagnosticReportKind, DocumentDiagnosticRequest, DocumentSymbolRequest, ExitNotification, HoverRequest, InitializeRequest, ReferencesRequest, InitializedNotification, MarkupKind, PositionEncodingKind, PublishDiagnosticsNotification, ShutdownRequest, WorkspaceSymbolRequest, } from "vscode-languageserver-protocol";
+import { DefinitionRequest, DiagnosticTag, DocumentDiagnosticReportKind, DocumentDiagnosticRequest, DocumentSymbolRequest, ExitNotification, HoverRequest, InitializeRequest, ReferencesRequest, InitializedNotification, MarkupKind, PositionEncodingKind, PublishDiagnosticsNotification, ShutdownRequest, WorkspaceSymbolRequest, } from "vscode-languageserver-protocol";
 import { LanguageServerConfigurationError, } from "./language-server-config.js";
-import { terminateProcessTree } from "../process-platform.js";
+import { terminateProcessTree } from "../mcp/process/process-platform.js";
 import { CodeIntelligenceError } from "./code-intelligence-error.js";
 import { DEFAULT_CODE_INTELLIGENCE_RESULT_LIMIT } from "./code-intelligence-types.js";
 import { normalizeHoverContents } from "./normalization/hover.js";
@@ -14,9 +14,11 @@ import { isWithin, locationEntries, normalizeLocations, workspaceDisplayPath, }
 import { lspPositionFromUser, rangeFromLsp } from "./position-encoding.js";
 import { DiagnosticSnapshotStore } from "./runtime/diagnostic-snapshots.js";
 import { DocumentSynchronizer } from "./runtime/document-synchronizer.js";
+import { languageServerCommandRequiresShell } from "./runtime/process-launch.js";
 import { SemanticRequestCoordinator } from "./runtime/semantic-requests.js";
 export { CodeIntelligenceError } from "./code-intelligence-error.js";
 const STDERR_TAIL_BYTES = 64 * 1024;
+const PUSH_DIAGNOSTIC_WAIT_MS = 1_000;
 export class LanguageService {
     workspaceRoot;
     project;
@@ -258,7 +260,10 @@ export class LanguageService {
                     ...this.diagnosticSnapshots.readPull(document, limit),
                 };
             }
-            const snapshot = this.diagnosticSnapshots.readPush(document, limit);
+            const snapshot = await this.diagnosticSnapshots.waitForFreshPush(document, limit, Math.min(PUSH_DIAGNOSTIC_WAIT_MS, this.policy.requestTimeoutMs), signal);
+            if (signal?.aborted) {
+                throw new CodeIntelligenceError("code.request_cancelled", `Diagnostic request for ${input.path} was cancelled by the Host.`);
+            }
             if (snapshot.freshness.state === "missing" && !this.diagnosticSnapshots.hasObservedPushDiagnostics()) {
                 throw new CodeIntelligenceError("code.operation_unsupported", `Language server ${this.project.definition.id} does not provide pull diagnostics and has not published push diagnostics.`);
             }
@@ -336,7 +341,7 @@ export class LanguageService {
                 stdio: "pipe",
                 windowsHide: true,
                 detached,
-                shell: false,
+                shell: languageServerCommandRequiresShell(definition.command),
             });
         }
         catch (error) {
@@ -370,6 +375,9 @@ export class LanguageService {
             clientInfo: { name: "forgerelay" },
             rootUri,
             workspaceFolders: [{ uri: rootUri, name: basename(this.project.projectRoot) }],
+            ...(definition.initializationOptions === undefined
+                ? {}
+                : { initializationOptions: definition.initializationOptions }),
             capabilities: {
                 general: {
                     positionEncodings: [
@@ -405,6 +413,12 @@ export class LanguageService {
                         dynamicRegistration: false,
                         hierarchicalDocumentSymbolSupport: true,
                     },
+                    publishDiagnostics: {
+                        relatedInformation: true,
+                        tagSupport: {
+                            valueSet: [DiagnosticTag.Unnecessary, DiagnosticTag.Deprecated],
+                        },
+                    },
                     diagnostic: {
                         dynamicRegistration: false,
                         relatedDocumentSupport: false,

package/dist/lsp/runtime/diagnostic-snapshots.js

@@ -4,6 +4,7 @@ export class DiagnosticSnapshotStore {
     maxDiagnosticsPerDocument;
     pushSnapshots = new Map();
     pullSnapshots = new Map();
+    pushWaiters = new Map();
     pushObserved = false;
     constructor(maxDocuments, maxDiagnosticsPerDocument) {
         this.maxDocuments = maxDocuments;
@@ -11,10 +12,13 @@ export class DiagnosticSnapshotStore {
     }
     capturePush(params, document, encoding) {
         this.pushObserved = true;
-        if (!document)
+        if (!document) {
+            this.notifyPushWaiters(params.uri, true);
             return;
+        }
         const snapshot = this.normalizeSnapshot(params.diagnostics, document, encoding, params.version === undefined ? {} : { publishedVersion: params.version });
         this.setBounded(this.pushSnapshots, params.uri, snapshot);
+        this.notifyPushWaiters(params.uri, true);
     }
     capturePull(diagnostics, document, encoding, resultId) {
         const snapshot = this.normalizeSnapshot(diagnostics, document, encoding, resultId === undefined ? {} : { resultId });
@@ -41,12 +45,52 @@ export class DiagnosticSnapshotStore {
     readPull(document, limit) {
         return this.read(this.pullSnapshots, document, limit, false);
     }
+    async waitForFreshPush(document, limit, timeoutMs, signal) {
+        let snapshot = this.readPush(document, limit);
+        const deadline = Date.now() + timeoutMs;
+        while (snapshot.freshness.state === "missing" || snapshot.freshness.state === "stale") {
+            if (signal?.aborted)
+                break;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0 || !await this.waitForPush(document.uri, remaining, signal))
+                break;
+            snapshot = this.readPush(document, limit);
+        }
+        return snapshot;
+    }
     hasObservedPushDiagnostics() {
         return this.pushObserved;
     }
+    waitForPush(uri, timeoutMs, signal) {
+        if (signal?.aborted)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            let settled = false;
+            const waiters = this.pushWaiters.get(uri) ?? new Set();
+            const finish = (observed) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                waiters.delete(finish);
+                if (waiters.size === 0)
+                    this.pushWaiters.delete(uri);
+                resolve(observed);
+            };
+            const onAbort = () => finish(false);
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            timer.unref();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            waiters.add(finish);
+            this.pushWaiters.set(uri, waiters);
+        });
+    }
     clear() {
         this.pushSnapshots.clear();
         this.pullSnapshots.clear();
+        for (const uri of [...this.pushWaiters.keys()])
+            this.notifyPushWaiters(uri, false);
         this.pushObserved = false;
     }
     get size() {
@@ -70,6 +114,13 @@ export class DiagnosticSnapshotStore {
             ...metadata,
         };
     }
+    notifyPushWaiters(uri, observed) {
+        const waiters = this.pushWaiters.get(uri);
+        if (!waiters)
+            return;
+        for (const waiter of [...waiters])
+            waiter(observed);
+    }
     setBounded(snapshots, uri, snapshot) {
         snapshots.delete(uri);
         snapshots.set(uri, snapshot);

package/dist/lsp/runtime/managed-language-servers.js

@@ -0,0 +1,172 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, join, resolve } from "node:path";
+const MANAGED_LANGUAGE_SERVERS = {
+    typescript: {
+        id: "typescript",
+        label: "TypeScript / JavaScript",
+        executable: "typescript-language-server",
+        packages: ["typescript-language-server@6", "typescript@6"],
+    },
+    pyright: {
+        id: "pyright",
+        label: "Python (Pyright)",
+        executable: "pyright-langserver",
+        packages: ["pyright@1"],
+    },
+};
+export function managedLanguageServerRoot(configDir) {
+    return join(configDir, "language-servers");
+}
+export function managedLanguageServerBinDir(configDir) {
+    return join(managedLanguageServerRoot(configDir), "node_modules", ".bin");
+}
+export function managedLanguageServerExecutablePath(configDir, id, platform = process.platform) {
+    const bin = managedLanguageServerBinDir(configDir);
+    const executable = MANAGED_LANGUAGE_SERVERS[id].executable;
+    const extensions = platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+    return extensions
+        .map((extension) => join(bin, `${executable}${extension}`))
+        .find((path) => existsSync(path));
+}
+export function managedLanguageServerIdForCommand(configDir, command, platform = process.platform) {
+    return supportedManagedLanguageServers().find((id) => {
+        const executable = managedLanguageServerExecutablePath(configDir, id, platform);
+        if (executable === undefined)
+            return false;
+        const executablePath = resolve(executable);
+        const commandPath = resolve(command);
+        return platform === "win32"
+            ? executablePath.toLowerCase() === commandPath.toLowerCase()
+            : executablePath === commandPath;
+    });
+}
+export function managedTypeScriptTsserverPath(configDir) {
+    const path = join(managedLanguageServerRoot(configDir), "node_modules", "typescript", "lib", "tsserver.js");
+    return existsSync(path) ? path : undefined;
+}
+export function managedLanguageServerRuntimeIdentity(configDir, id) {
+    const packageNames = id === "typescript"
+        ? ["typescript-language-server", "typescript"]
+        : ["pyright"];
+    try {
+        const versions = packageNames.map((name) => {
+            const packageJson = JSON.parse(readFileSync(join(managedLanguageServerRoot(configDir), "node_modules", name, "package.json"), "utf8"));
+            if (!packageJson.version)
+                throw new Error(`Missing version for ${name}`);
+            return [name, packageJson.version];
+        });
+        return JSON.stringify(versions);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function withManagedLanguageServerPath(env, configDir) {
+    if (!configDir)
+        return { ...env };
+    const bin = managedLanguageServerBinDir(configDir);
+    return {
+        ...env,
+        PATH: [bin, env.PATH].filter((value) => Boolean(value)).join(delimiter),
+    };
+}
+export function managedLanguageServerOptions() {
+    return [
+        {
+            value: "typescript",
+            label: MANAGED_LANGUAGE_SERVERS.typescript.label,
+            hint: "Installs typescript-language-server and TypeScript into ForgeRelay's private config directory.",
+        },
+        {
+            value: "pyright",
+            label: MANAGED_LANGUAGE_SERVERS.pyright.label,
+            hint: "Installs Pyright into ForgeRelay's private config directory.",
+        },
+    ];
+}
+export function supportedManagedLanguageServers() {
+    return Object.keys(MANAGED_LANGUAGE_SERVERS);
+}
+export function installedManagedLanguageServers(configDir) {
+    return supportedManagedLanguageServers()
+        .filter((id) => managedExecutableExists(configDir, MANAGED_LANGUAGE_SERVERS[id].executable));
+}
+export function managedLanguageServerPackages(ids) {
+    const packages = new Set();
+    for (const id of ids) {
+        for (const packageSpec of MANAGED_LANGUAGE_SERVERS[id].packages)
+            packages.add(packageSpec);
+    }
+    return [...packages];
+}
+export async function installManagedLanguageServers(ids, configDir, runNpm = defaultNpmRunner) {
+    const selected = Array.from(new Set(ids));
+    const root = managedLanguageServerRoot(configDir);
+    const packages = managedLanguageServerPackages(selected);
+    if (packages.length === 0)
+        return { installed: [], packages: [], root };
+    mkdirSync(root, { recursive: true });
+    const packageJsonPath = join(root, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        writeFileSync(packageJsonPath, JSON.stringify({
+            name: "forgerelay-managed-language-servers",
+            private: true,
+            description: "ForgeRelay-managed optional Language Servers. Do not publish.",
+        }, null, 2) + "\n");
+    }
+    await runNpm([
+        "install",
+        "--prefix",
+        root,
+        "--save-exact",
+        "--no-audit",
+        "--no-fund",
+        ...packages,
+    ]);
+    for (const id of selected)
+        assertManagedLanguageServerInstall(configDir, id);
+    return { installed: selected, packages, root };
+}
+function assertManagedLanguageServerInstall(configDir, id) {
+    if (!managedLanguageServerExecutablePath(configDir, id)) {
+        throw new Error(`Managed Language Server ${id} installed without its expected executable.`);
+    }
+    if (id === "typescript" && !managedTypeScriptTsserverPath(configDir)) {
+        throw new Error("Managed TypeScript Language Server installed without a compatible TypeScript tsserver.js. " +
+            "ForgeRelay requires a tsserver-based TypeScript package for typescript-language-server.");
+    }
+}
+function managedExecutableExists(configDir, executable) {
+    const bin = managedLanguageServerBinDir(configDir);
+    if (process.platform === "win32") {
+        return [".cmd", ".exe", ".bat", ""].some((extension) => existsSync(join(bin, `${executable}${extension}`)));
+    }
+    return existsSync(join(bin, executable));
+}
+function defaultNpmRunner(args) {
+    const command = process.platform === "win32" ? "npm.cmd" : "npm";
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            shell: process.platform === "win32",
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => { stdout += chunk; });
+        child.stderr?.on("data", (chunk) => { stderr += chunk; });
+        child.once("error", reject);
+        child.once("close", (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            const detail = (stderr || stdout).trim();
+            reject(new Error(`npm install for managed Language Servers failed with exit ${code ?? "unknown"}${detail ? `: ${detail}` : ""}`));
+        });
+    });
+}