kritya 0.8.2-beta

package/dist/mcp/login.js

@@ -0,0 +1,117 @@
+import { openBrowser, startCallbackServer } from "./callback.js";
+import { buildAuthorizeUrl, createPkce, discoverAuthServer, discoverProtectedResource, exchangeCode, randomState, registerClient, revokeToken, } from "./oauth.js";
+import { deleteAuth, loadAuth, saveAuth } from "./tokens.js";
+const pending = new Map();
+export function pendingLogin(serverName) {
+    return pending.get(serverName);
+}
+/** Pull the `code` out of a pasted redirect URL, or accept a bare code. */
+export function extractCode(input) {
+    const trimmed = input.trim();
+    try {
+        const url = new URL(trimmed);
+        const code = url.searchParams.get("code");
+        if (code)
+            return code;
+    }
+    catch {
+        // Not a URL — treat the whole thing as the code.
+    }
+    return trimmed;
+}
+export async function beginLogin(opts) {
+    const existing = pending.get(opts.serverName);
+    if (existing)
+        existing.cancel();
+    const resource = await discoverProtectedResource(opts.serverUrl, opts.resourceMetadataUrl);
+    const issuer = resource.authorizationServers[0];
+    const meta = await discoverAuthServer(issuer);
+    const state = randomState();
+    const pkce = createPkce();
+    // The listener has to exist before registration: DCR pins the exact
+    // redirect_uri, so the port can't be chosen afterwards.
+    const callback = await startCallbackServer(state);
+    const scope = resource.scopesSupported?.join(" ") ?? meta.scopesSupported?.join(" ");
+    const registration = await reuseOrRegister(opts.serverUrl, meta, callback.redirectUri, scope);
+    const authorizeUrl = buildAuthorizeUrl({
+        meta,
+        clientId: registration.clientId,
+        redirectUri: callback.redirectUri,
+        challenge: pkce.challenge,
+        state,
+        resource: resource.resource,
+        scope,
+    });
+    let submitManual = () => { };
+    let cancelManual = () => { };
+    const manual = new Promise((resolve, reject) => {
+        submitManual = resolve;
+        cancelManual = reject;
+    });
+    // Nothing may ever consume this branch (the loopback usually wins); without
+    // this an unhandled rejection would surface when we cancel it.
+    manual.catch(() => { });
+    const browserOpened = openBrowser(authorizeUrl);
+    const completed = Promise.race([callback.waitForCode(), manual]).then(async (code) => {
+        callback.close();
+        const auth = await exchangeCode({
+            meta,
+            clientId: registration.clientId,
+            clientSecret: registration.clientSecret,
+            code,
+            verifier: pkce.verifier,
+            redirectUri: callback.redirectUri,
+            resource: resource.resource,
+        });
+        auth.serverName = opts.serverName;
+        saveAuth(opts.serverUrl, auth);
+        pending.delete(opts.serverName);
+        return auth;
+    });
+    completed.catch(() => pending.delete(opts.serverName));
+    const entry = {
+        serverName: opts.serverName,
+        serverUrl: opts.serverUrl,
+        authorizeUrl,
+        redirectUri: callback.redirectUri,
+        browserOpened,
+        completed,
+        submitCode: (codeOrUrl) => submitManual(extractCode(codeOrUrl)),
+        cancel: () => {
+            callback.close();
+            cancelManual(new Error("login cancelled"));
+            pending.delete(opts.serverName);
+        },
+    };
+    pending.set(opts.serverName, entry);
+    return entry;
+}
+/**
+ * Reuse a client_id already registered with this authorization server when the
+ * redirect URI still matches. Re-registering on every login would leave a trail
+ * of dead client records on the provider's side, and some rate-limit it.
+ */
+async function reuseOrRegister(serverUrl, meta, redirectUri, scope) {
+    const prior = loadAuth(serverUrl);
+    // The loopback port changes every run, so a stored client_id is only reusable
+    // if the AS registered a wildcard-ish URI or the port happened to repeat.
+    // Registration is cheap and always correct, so only reuse on an exact match.
+    if (prior?.clientId && prior.issuer === meta.issuer && prior.redirectUri === redirectUri) {
+        return { clientId: prior.clientId, clientSecret: prior.clientSecret };
+    }
+    return registerClient(meta, redirectUri, scope);
+}
+/**
+ * Log out of a server: try to revoke server-side, then always delete locally.
+ * The two are reported separately on purpose — telling someone they are "logged
+ * out" when the token is merely forgotten, and still live on the provider's
+ * side, would be a lie they can't act on.
+ */
+export async function logout(serverUrl) {
+    const auth = loadAuth(serverUrl);
+    if (!auth)
+        return { revoked: false, hadToken: false };
+    const revoked = await revokeToken(auth);
+    deleteAuth(serverUrl);
+    return { revoked, hadToken: true };
+}

package/dist/mcp/oauth.js

@@ -0,0 +1,345 @@
+import crypto from "node:crypto";
+import { VERSION } from "../version.js";
+import { debugLog } from "../config/debug.js";
+import { isExpired, loadAuth, saveAuth } from "./tokens.js";
+/**
+ * OAuth 2.1 for remote (Streamable HTTP) MCP servers.
+ *
+ * Every major hosted MCP server — Linear, Notion, Sentry, GitHub, Atlassian —
+ * gates on OAuth rather than a static bearer token, so `headers` in config only
+ * ever reached unauthenticated servers and ones handing out long-lived PATs.
+ * The flow implemented here is the one the MCP spec pins down:
+ *
+ *   401 + WWW-Authenticate  → protected-resource metadata (RFC 9728)
+ *                           → authorization-server metadata (RFC 8414)
+ *                           → dynamic client registration (RFC 7591)
+ *                           → authorization code + PKCE (RFC 7636) in a browser
+ *                           → loopback redirect (RFC 8252) captures the code
+ *                           → token exchange, scoped with `resource` (RFC 8707)
+ *
+ * Two deliberate choices:
+ *
+ *  - No client secret is required or expected. kritya is a public client on the
+ *    user's own machine; there is nowhere to keep a secret that the user
+ *    couldn't already read. PKCE is what makes the code exchange safe. A secret
+ *    is stored only if an AS insists on issuing one.
+ *  - Discovery degrades to spec defaults rather than failing. Real deployments
+ *    are inconsistent about which .well-known documents they publish, and a
+ *    missing metadata file is not a good enough reason to refuse to log in.
+ */
+const DISCOVERY_TIMEOUT_MS = 10_000;
+const TOKEN_TIMEOUT_MS = 15_000;
+/** Thrown when a server needs a login kritya doesn't have yet. Carries enough to start one. */
+export class McpAuthRequiredError extends Error {
+    serverUrl;
+    resourceMetadataUrl;
+    constructor(serverUrl, resourceMetadataUrl) {
+        super("authentication required (run /mcp login)");
+        this.serverUrl = serverUrl;
+        this.resourceMetadataUrl = resourceMetadataUrl;
+        this.name = "McpAuthRequiredError";
+    }
+}
+function ua() {
+    return { "user-agent": `kritya/${VERSION}`, accept: "application/json" };
+}
+async function getJson(url, timeoutMs = DISCOVERY_TIMEOUT_MS) {
+    const res = await fetch(url, { headers: ua(), signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status} from ${url}`);
+    return res.json();
+}
+/**
+ * Pull `resource_metadata="…"` out of a 401's WWW-Authenticate challenge.
+ * Returns undefined when the header is missing or doesn't name one — common
+ * enough that callers fall back to well-known probing rather than giving up.
+ */
+export function parseWwwAuthenticate(header) {
+    if (!header)
+        return undefined;
+    const match = /resource_metadata\s*=\s*"([^"]+)"/i.exec(header);
+    return match?.[1];
+}
+/** Candidate .well-known URLs for a resource, per RFC 9728's path-aware rules. */
+export function resourceMetadataUrls(serverUrl) {
+    const u = new URL(serverUrl);
+    const origin = u.origin;
+    const p = u.pathname.replace(/\/$/, "");
+    const urls = [`${origin}/.well-known/oauth-protected-resource`];
+    // Path-scoped variant first when the endpoint isn't at the root: a host can
+    // serve several distinct MCP resources under one origin.
+    if (p && p !== "")
+        urls.unshift(`${origin}/.well-known/oauth-protected-resource${p}`);
+    return urls;
+}
+export async function discoverProtectedResource(serverUrl, metadataUrl) {
+    const candidates = metadataUrl
+        ? [metadataUrl, ...resourceMetadataUrls(serverUrl)]
+        : resourceMetadataUrls(serverUrl);
+    for (const url of candidates) {
+        try {
+            const doc = (await getJson(url));
+            if (doc?.authorization_servers?.length) {
+                return {
+                    resource: doc.resource ?? serverUrl,
+                    authorizationServers: doc.authorization_servers,
+                    scopesSupported: doc.scopes_supported,
+                };
+            }
+        }
+        catch (err) {
+            debugLog(`mcp oauth protected-resource ${url}`, err);
+        }
+    }
+    // No document: assume the resource server is also its own authorization
+    // server, which is how most single-tenant MCP deployments are set up.
+    return { resource: serverUrl, authorizationServers: [new URL(serverUrl).origin] };
+}
+/** Candidate .well-known URLs for an authorization server, RFC 8414 + OIDC. */
+export function authServerMetadataUrls(issuer) {
+    const u = new URL(issuer);
+    const origin = u.origin;
+    const p = u.pathname.replace(/\/$/, "");
+    const urls = [];
+    if (p) {
+        urls.push(`${origin}/.well-known/oauth-authorization-server${p}`);
+        urls.push(`${origin}/.well-known/openid-configuration${p}`);
+        urls.push(`${origin}${p}/.well-known/openid-configuration`);
+    }
+    urls.push(`${origin}/.well-known/oauth-authorization-server`);
+    urls.push(`${origin}/.well-known/openid-configuration`);
+    return urls;
+}
+export async function discoverAuthServer(issuer) {
+    for (const url of authServerMetadataUrls(issuer)) {
+        try {
+            const doc = (await getJson(url));
+            if (doc?.authorization_endpoint && doc?.token_endpoint) {
+                return {
+                    issuer: doc.issuer ?? issuer,
+                    authorizationEndpoint: doc.authorization_endpoint,
+                    tokenEndpoint: doc.token_endpoint,
+                    registrationEndpoint: doc.registration_endpoint,
+                    revocationEndpoint: doc.revocation_endpoint,
+                    scopesSupported: doc.scopes_supported,
+                };
+            }
+        }
+        catch (err) {
+            debugLog(`mcp oauth as-metadata ${url}`, err);
+        }
+    }
+    // RFC 8414 default endpoint layout — enough for servers that publish nothing.
+    const base = issuer.replace(/\/$/, "");
+    return {
+        issuer,
+        authorizationEndpoint: `${base}/authorize`,
+        tokenEndpoint: `${base}/token`,
+        registrationEndpoint: `${base}/register`,
+    };
+}
+export function createPkce() {
+    const verifier = crypto.randomBytes(32).toString("base64url");
+    const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}
+export function randomState() {
+    return crypto.randomBytes(16).toString("base64url");
+}
+/**
+ * Register kritya with the authorization server. Public client, no secret
+ * requested: `token_endpoint_auth_method: "none"` plus PKCE is the OAuth 2.1
+ * shape for a native app.
+ */
+export async function registerClient(meta, redirectUri, scope) {
+    if (!meta.registrationEndpoint) {
+        throw new Error(`authorization server ${meta.issuer} does not support dynamic client registration; ` +
+            `register kritya manually and put the client_id in mcp-auth.json`);
+    }
+    const res = await fetch(meta.registrationEndpoint, {
+        method: "POST",
+        headers: { ...ua(), "content-type": "application/json" },
+        body: JSON.stringify({
+            client_name: "kritya",
+            client_uri: "https://github.com/GenAICloudDevOps/kritya",
+            redirect_uris: [redirectUri],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            ...(scope ? { scope } : {}),
+        }),
+        signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`client registration failed: HTTP ${res.status}${body ? ` — ${body.slice(0, 200)}` : ""}`);
+    }
+    const doc = (await res.json());
+    if (!doc.client_id)
+        throw new Error("client registration returned no client_id");
+    return { clientId: doc.client_id, clientSecret: doc.client_secret };
+}
+export function buildAuthorizeUrl(opts) {
+    const url = new URL(opts.meta.authorizationEndpoint);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", opts.clientId);
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    url.searchParams.set("code_challenge", opts.challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("state", opts.state);
+    // RFC 8707: binds the issued token to this MCP server, so a token minted for
+    // one resource can't be replayed against another on the same AS.
+    url.searchParams.set("resource", opts.resource);
+    if (opts.scope)
+        url.searchParams.set("scope", opts.scope);
+    return url.toString();
+}
+async function postToken(tokenEndpoint, params, clientSecret) {
+    const headers = {
+        ...ua(),
+        "content-type": "application/x-www-form-urlencoded",
+    };
+    // Confidential-client fallback: only when the AS insisted on issuing a secret.
+    if (clientSecret) {
+        const basic = Buffer.from(`${params.client_id}:${clientSecret}`).toString("base64");
+        headers.authorization = `Basic ${basic}`;
+    }
+    const res = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers,
+        body: new URLSearchParams(params).toString(),
+        signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+    });
+    const doc = (await res.json().catch(() => ({})));
+    if (!res.ok || doc.error || !doc.access_token) {
+        const detail = doc.error_description ?? doc.error ?? `HTTP ${res.status}`;
+        throw new Error(`token request failed: ${detail}`);
+    }
+    return doc;
+}
+export async function exchangeCode(opts) {
+    const doc = await postToken(opts.meta.tokenEndpoint, {
+        grant_type: "authorization_code",
+        code: opts.code,
+        redirect_uri: opts.redirectUri,
+        client_id: opts.clientId,
+        code_verifier: opts.verifier,
+        resource: opts.resource,
+    }, opts.clientSecret);
+    return {
+        resource: opts.resource,
+        issuer: opts.meta.issuer,
+        tokenEndpoint: opts.meta.tokenEndpoint,
+        revocationEndpoint: opts.meta.revocationEndpoint,
+        clientId: opts.clientId,
+        clientSecret: opts.clientSecret,
+        redirectUri: opts.redirectUri,
+        accessToken: doc.access_token,
+        refreshToken: doc.refresh_token,
+        expiresAt: doc.expires_in ? Date.now() + doc.expires_in * 1000 : undefined,
+        scope: doc.scope,
+    };
+}
+export async function refreshToken(auth) {
+    if (!auth.refreshToken)
+        throw new Error("no refresh token — a new login is required");
+    const doc = await postToken(auth.tokenEndpoint, {
+        grant_type: "refresh_token",
+        refresh_token: auth.refreshToken,
+        client_id: auth.clientId,
+        resource: auth.resource,
+    }, auth.clientSecret);
+    return {
+        ...auth,
+        accessToken: doc.access_token,
+        // An AS may rotate the refresh token; keep the old one when it doesn't.
+        refreshToken: doc.refresh_token ?? auth.refreshToken,
+        expiresAt: doc.expires_in ? Date.now() + doc.expires_in * 1000 : undefined,
+        scope: doc.scope ?? auth.scope,
+    };
+}
+/**
+ * Ask the AS to invalidate a token (RFC 7009). Returns false when the server
+ * doesn't advertise a revocation endpoint or rejects the call — the caller
+ * still deletes locally, but must say which of the two happened rather than
+ * claiming the token is dead when it is merely forgotten.
+ */
+export async function revokeToken(auth) {
+    if (!auth.revocationEndpoint)
+        return false;
+    const token = auth.refreshToken ?? auth.accessToken;
+    const hint = auth.refreshToken ? "refresh_token" : "access_token";
+    try {
+        const res = await fetch(auth.revocationEndpoint, {
+            method: "POST",
+            headers: { ...ua(), "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                token,
+                token_type_hint: hint,
+                client_id: auth.clientId,
+            }).toString(),
+            signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+        });
+        return res.ok;
+    }
+    catch (err) {
+        debugLog(`mcp oauth revoke ${auth.revocationEndpoint}`, err);
+        return false;
+    }
+}
+/**
+ * The token side of one server's session, shared by every request on that
+ * transport. Refreshes are serialized through a single in-flight promise:
+ * kritya connects to all servers in parallel and a transport can have several
+ * requests outstanding, so without this a batch of simultaneous 401s would
+ * fire a burst of refreshes and — against an AS that rotates refresh tokens —
+ * invalidate each other's grant.
+ */
+export class OAuthSession {
+    serverUrl;
+    auth;
+    refreshing;
+    constructor(serverUrl, auth) {
+        this.serverUrl = serverUrl;
+        this.auth = auth ?? loadAuth(serverUrl);
+    }
+    get hasAuth() {
+        return this.auth !== undefined;
+    }
+    /** Current access token, refreshing first if it is known to be expiring. */
+    async accessToken() {
+        if (!this.auth)
+            return undefined;
+        if (isExpired(this.auth) && this.auth.refreshToken) {
+            const next = await this.doRefresh(this.auth);
+            return next?.accessToken;
+        }
+        return this.auth.accessToken;
+    }
+    /**
+     * Called after a 401. Returns true when a refreshed token is now in place and
+     * the request is worth retrying; false when the user must log in again.
+     */
+    async handleUnauthorized() {
+        if (!this.auth?.refreshToken)
+            return false;
+        const next = await this.doRefresh(this.auth);
+        return next !== undefined;
+    }
+    doRefresh(current) {
+        const inFlight = this.refreshing ??
+            (this.refreshing = refreshToken(current)
+                .then((next) => {
+                this.auth = next;
+                saveAuth(this.serverUrl, next);
+                return next;
+            })
+                .finally(() => {
+                this.refreshing = undefined;
+            }));
+        return inFlight.catch((err) => {
+            debugLog(`mcp oauth refresh ${this.serverUrl}`, err);
+            return undefined;
+        });
+    }
+}

package/dist/mcp/servers.js

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Where MCP server definitions come from and how they combine:
+ *
+ *  - Global: `mcpServers` in ~/.kritya/config.json — the user's own machines.
+ *  - Project: `.mcp.json` at the workspace root (the cross-tool convention
+ *    also read by Claude Code, Cursor, and VS Code), shape
+ *    `{ "mcpServers": { name: { command|url, ... } } }`. A repo can ship this
+ *    file, and it launches processes / sends requests with the user's
+ *    credentials — so it is part of the workspace trust gate and must only be
+ *    loaded for trusted workspaces (the caller enforces this).
+ *
+ * `${VAR}` in any string value is expanded from the environment at load time,
+ * so a checked-in .mcp.json never needs to contain a literal secret
+ * (e.g. "Authorization": "Bearer ${LINEAR_API_KEY}").
+ */
+const VAR_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** Expand ${VAR} from process.env; unknown variables are left as-is so typos stay visible. */
+export function expandVars(value) {
+    return value.replace(VAR_RE, (whole, name) => {
+        const v = process.env[name];
+        return v !== undefined ? v : whole;
+    });
+}
+/**
+ * Names of ${VAR}s still unexpanded in an already-expanded config.
+ *
+ * Leaving them literal keeps typos visible, but only if something actually
+ * looks: otherwise a missing LINEAR_API_KEY means we POST the literal string
+ * `Bearer ${LINEAR_API_KEY}` to a third party, get an opaque 401 back, and —
+ * because 401 is also how OAuth asks for a login — report it as "needs login".
+ * Callers use this to fail the server with the real reason instead.
+ */
+export function missingVars(cfg) {
+    const found = new Set();
+    const scan = (s) => {
+        if (!s)
+            return;
+        for (const m of s.matchAll(VAR_RE))
+            found.add(m[1]);
+    };
+    scan(cfg.command);
+    cfg.args?.forEach(scan);
+    scan(cfg.cwd);
+    scan(cfg.url);
+    for (const v of Object.values(cfg.env ?? {}))
+        scan(v);
+    for (const v of Object.values(cfg.headers ?? {}))
+        scan(v);
+    return [...found].sort();
+}
+function expandRecord(rec) {
+    if (!rec)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(rec))
+        out[k] = expandVars(v);
+    return out;
+}
+export function expandServerConfig(cfg) {
+    return {
+        command: cfg.command !== undefined ? expandVars(cfg.command) : undefined,
+        args: cfg.args?.map(expandVars),
+        env: expandRecord(cfg.env),
+        cwd: cfg.cwd !== undefined ? expandVars(cfg.cwd) : undefined,
+        url: cfg.url !== undefined ? expandVars(cfg.url) : undefined,
+        headers: expandRecord(cfg.headers),
+        // Carried through verbatim: these are tool-name patterns, not values, and
+        // dropping them here would silently expose a server's whole tool list.
+        tools: cfg.tools,
+    };
+}
+function isServerConfig(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const cfg = v;
+    return typeof cfg.command === "string" || typeof cfg.url === "string";
+}
+/**
+ * Read the workspace's `.mcp.json`. Malformed files and entries with neither
+ * `command` nor `url` are skipped silently — a broken project file should
+ * degrade to "no project servers", not break startup.
+ */
+export function loadProjectMcpServers(workspace) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(path.join(workspace, ".mcp.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed?.mcpServers || typeof parsed.mcpServers !== "object")
+        return undefined;
+    const servers = {};
+    for (const [name, cfg] of Object.entries(parsed.mcpServers)) {
+        if (isServerConfig(cfg))
+            servers[name] = cfg;
+    }
+    return Object.keys(servers).length ? servers : undefined;
+}
+/**
+ * Combine plugin, project, and global server definitions, expanding ${VAR} in
+ * each. Precedence on a name clash: global wins over project, which wins over
+ * a plugin -- a plugin is third-party-contributed, so anything the user or
+ * the workspace declares explicitly takes priority.
+ */
+export function mergeMcpServers(global, project, plugin) {
+    const merged = { ...plugin, ...project, ...global };
+    const out = {};
+    for (const [name, cfg] of Object.entries(merged))
+        out[name] = expandServerConfig(cfg);
+    return out;
+}

package/dist/mcp/spawnWin.js

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+function pathExtensions() {
+    return (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+        .split(";")
+        .map((e) => e.trim())
+        .filter(Boolean);
+}
+function isFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find the concrete file a bare command name refers to, applying PATHEXT the
+ * way a shell would. Returns undefined when nothing matches, so the caller can
+ * fall through to a plain spawn and let the OS produce the usual ENOENT rather
+ * than a substitute error that points at the wrong thing.
+ */
+export function resolveWindowsCommand(command) {
+    const exts = pathExtensions();
+    const hasExt = exts.some((e) => command.toLowerCase().endsWith(e.toLowerCase()));
+    const isPath = command.includes("/") || command.includes("\\") || path.isAbsolute(command);
+    // An explicit path with an explicit extension is already unambiguous.
+    if (hasExt && isPath)
+        return isFile(command) ? command : undefined;
+    const bases = isPath
+        ? [command]
+        : (process.env.PATH ?? "")
+            .split(path.delimiter)
+            .filter(Boolean)
+            .map((dir) => path.join(dir, command));
+    for (const base of bases) {
+        if (hasExt) {
+            if (isFile(base))
+                return base;
+            continue;
+        }
+        for (const ext of exts) {
+            if (isFile(base + ext))
+                return base + ext;
+        }
+    }
+    return undefined;
+}
+/**
+ * Quote one argument so cmd.exe passes it through unchanged.
+ *
+ * Two layers: the standard Windows double-quote rules (so the child's own
+ * argv parsing sees the original string), then a caret escape of every
+ * character cmd.exe would still act on before the child ever runs.
+ */
+function escapeForCmd(arg) {
+    // Escape backslashes that precede a quote, and any trailing run of them,
+    // then wrap in quotes — the CommandLineToArgvW rules.
+    const quoted = `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1")}"`;
+    return quoted.replace(/[()[\]{}^=;!'+,`~%!&|<>"]/g, "^$&");
+}
+/**
+ * Decide how to spawn `command` with `args` on this platform. On non-Windows,
+ * and for ordinary .exe files on Windows, this is a passthrough; only batch
+ * files need the cmd.exe detour.
+ */
+export function planSpawn(command, args) {
+    if (os.platform() !== "win32")
+        return { command, args };
+    const resolved = resolveWindowsCommand(command);
+    if (!resolved)
+        return { command, args };
+    const ext = path.extname(resolved).toLowerCase();
+    if (ext !== ".cmd" && ext !== ".bat")
+        return { command: resolved, args };
+    const comSpec = process.env.ComSpec ?? process.env.COMSPEC ?? "cmd.exe";
+    const line = [resolved, ...args].map(escapeForCmd).join(" ");
+    return {
+        // /d skips AutoRun commands from the registry, /s keeps our outer quotes
+        // intact, /c runs and exits.
+        command: comSpec,
+        args: ["/d", "/s", "/c", `"${line}"`],
+        windowsVerbatimArguments: true,
+    };
+}