driggsby 0.1.41 → 0.2.0

package/dist/login/claim-client.js

@@ -0,0 +1,151 @@
+// The app-token claim flow's HTTP client, against Driggsby's public
+// app-token claim API: create a pending claim, send the user to claim_url,
+// poll with the claim id + poll secret until the user approves. The app
+// token is returned by exactly one poll; callers must never poll again after
+// an approval.
+import { CliError } from "../cli-error.js";
+import { sanitizeForTerminal } from "../terminal-text.js";
+const CLAIM_SCOPE = "driggsby.app_deploy";
+const CLAIM_APP_NAME = "Driggsby CLI";
+const REQUEST_TIMEOUT_MS = 15_000;
+// The server names its own claim lifetime; this cap keeps a buggy or hostile
+// expires_in from making the CLI wait (and poll) effectively forever.
+const MAX_EXPIRES_IN_SECONDS = 1_800;
+// Both endpoints answer with small JSON objects; anything enormous is not a
+// real Driggsby response. The cap bounds what gets parsed and surfaced, not
+// what the network buffers — the request timeout bounds that.
+const MAX_RESPONSE_BODY_CHARS = 1_000_000;
+// Server error_description fields are one or two sentences; a bound keeps a
+// misbehaving origin from flooding the terminal through an error message.
+const MAX_ERROR_DESCRIPTION_CHARS = 300;
+export const SIGN_IN_START_FAILURE = "We weren't able to start a Driggsby sign-in just now. Please try again in\na minute.";
+// Poll failures happen after the user may already have approved, so "start a
+// sign-in" would be the wrong stage to describe.
+const SIGN_IN_FINISH_FAILURE = "We weren't able to finish your Driggsby sign-in just now. Please try again\nin a minute.";
+export async function createClaimRequest(baseUrl) {
+    const response = await fetch(`${baseUrl}/app-tokens/claim-requests`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ app_name: CLAIM_APP_NAME, scope: CLAIM_SCOPE }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        // Never follow a redirect: a 307/308 would replay this claim flow —
+        // and, on the poll below, the poll secret — to whatever origin a
+        // Location header names. These endpoints never legitimately redirect.
+        redirect: "error",
+    });
+    const body = await readJsonBody(response);
+    if (response.status !== 201) {
+        // The server's error_description fields are written to be user-facing;
+        // errorDescription surfaces them sanitized and length-bounded.
+        throw new CliError(errorDescription(body) ?? SIGN_IN_START_FAILURE, 1);
+    }
+    const record = asRecord(body);
+    const claimRequestId = stringField(record, "claim_request_id");
+    const claimUrl = stringField(record, "claim_url");
+    const pollSecret = stringField(record, "poll_secret");
+    const expiresIn = record?.expires_in;
+    if (claimRequestId === null ||
+        claimUrl === null ||
+        pollSecret === null ||
+        typeof expiresIn !== "number" ||
+        !Number.isFinite(expiresIn) ||
+        expiresIn <= 0) {
+        throw new CliError(SIGN_IN_START_FAILURE, 1);
+    }
+    return {
+        claimRequestId,
+        claimUrl,
+        pollSecret,
+        expiresInSeconds: Math.min(expiresIn, MAX_EXPIRES_IN_SECONDS),
+    };
+}
+export async function pollClaimRequest(baseUrl, credentials) {
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/app-tokens/claim-requests/poll`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                claim_request_id: credentials.claimRequestId,
+                poll_secret: credentials.pollSecret,
+            }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            // Same as the create call: a redirect must never carry the poll secret
+            // (or accept a token from) another origin.
+            redirect: "error",
+        });
+    }
+    catch {
+        return { kind: "transient" };
+    }
+    const body = await readJsonBody(response);
+    const record = asRecord(body);
+    if (response.status === 404 || response.status === 410) {
+        // The claim no longer exists server-side — the same end state as an
+        // explicit "gone" answer; retrying the same claim can never succeed.
+        return { kind: "gone" };
+    }
+    if (response.status === 429) {
+        // Rate limiting from an edge layer is momentary; the poll loop's own
+        // interval is the backoff.
+        return { kind: "transient" };
+    }
+    if (response.status >= 400 && response.status < 500) {
+        // A 4xx (invalid_poll_request and friends) means our request is wrong —
+        // a bug, not something a retry can fix — so fail now instead of polling
+        // uselessly until the claim expires.
+        throw new CliError(errorDescription(body) ?? SIGN_IN_FINISH_FAILURE, 1);
+    }
+    if (response.status !== 200) {
+        return { kind: "transient" };
+    }
+    switch (record?.status) {
+        case "pending":
+            return { kind: "pending" };
+        case "approved": {
+            const appToken = stringField(record, "app_token");
+            if (appToken === null) {
+                throw new CliError(SIGN_IN_FINISH_FAILURE, 1);
+            }
+            return { kind: "approved", appToken };
+        }
+        case "gone":
+            return { kind: "gone" };
+        default:
+            return { kind: "transient" };
+    }
+}
+async function readJsonBody(response) {
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch {
+        return null;
+    }
+    if (text.length > MAX_RESPONSE_BODY_CHARS) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}
+function stringField(record, field) {
+    const value = record?.[field];
+    return typeof value === "string" && value !== "" ? value : null;
+}
+// The server's user-facing error text, stripped of terminal control bytes
+// like every other string this CLI did not author, and length-bounded.
+function errorDescription(body) {
+    const raw = stringField(asRecord(body), "error_description");
+    if (raw === null) {
+        return null;
+    }
+    return sanitizeForTerminal(raw.slice(0, MAX_ERROR_DESCRIPTION_CHARS));
+}

package/dist/login/login.js

@@ -0,0 +1,146 @@
+// driggsby login: create an app-token claim, send the user to the approval
+// page, poll until they approve, and store the token. The token is shown to
+// no one — it goes straight from the poll response into the credential
+// store.
+import { apiBaseUrl, apiHost } from "../api/base-url.js";
+import { blockedNetworkError } from "../api/network-error.js";
+import { CliError } from "../cli-error.js";
+import { defaultCredentialEnvironment, describeStorageLocation, environmentToken, saveToken, } from "../credentials/store.js";
+import { sanitizeForTerminal, wrapProse } from "../terminal-text.js";
+import { createClaimRequest, pollClaimRequest, SIGN_IN_START_FAILURE, } from "./claim-client.js";
+import { tryOpenUrl } from "./open-url.js";
+const LOGIN_RETRY_COMMAND = "npx driggsby@latest login";
+const DEFAULT_POLL_INTERVAL_MS = 4_000;
+function defaultLoginIo() {
+    return {
+        out: (text) => {
+            process.stdout.write(text);
+        },
+        openUrl: tryOpenUrl,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
+        pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+    };
+}
+export async function runLogin(environment = defaultCredentialEnvironment(), io = defaultLoginIo()) {
+    const baseUrl = apiBaseUrl(environment.env);
+    io.out("Sign in to Driggsby\n\n");
+    const claim = await createClaim(baseUrl);
+    const claimUrl = approvedClaimUrl(claim.claimUrl, baseUrl);
+    const browserOpened = await io.openUrl(claimUrl);
+    io.out(browserOpened
+        ? "Your browser should open a Driggsby approval page. If it doesn't, open\nthis link:\n\n"
+        : "Open this link in your browser to approve access for this machine:\n\n");
+    io.out(`  ${claimUrl}\n\n`);
+    const minutes = approximateMinutes(claim.expiresInSeconds);
+    const minutesWord = minutes === 1 ? "minute" : "minutes";
+    io.out(`Waiting for your approval (the link is good for about ${minutes} ${minutesWord})...\n`);
+    const appToken = await pollUntilApproved(baseUrl, claim, io);
+    // Warnings are held back and printed after the "Approved." line — and when
+    // one fires, it replaces the all-clear closer: the last thing the user
+    // reads must never contradict a warning they were just shown.
+    const warnings = [];
+    const storedIn = await storeApprovedToken(appToken, environment, (text) => warnings.push(text));
+    const envTokenWarning = shadowingEnvTokenWarning(environment);
+    if (envTokenWarning !== null) {
+        warnings.push(envTokenWarning);
+    }
+    io.out(`\n${wrapProse(`Approved. Your Driggsby app token is now saved in ${describeStorageLocation(storedIn)}.`)}\n`);
+    if (warnings.length > 0) {
+        io.out(`\n${warnings.join("\n")}`);
+        return;
+    }
+    io.out("\nNext:\n  You're all set — driggsby commands will use this saved token\n  automatically. Deploy an app with npx driggsby@latest deploy.\n");
+}
+// The one-time token is already consumed by the time saving starts, so a
+// storage failure must say clearly that a fresh sign-in is needed — never
+// the generic "something went wrong".
+async function storeApprovedToken(appToken, environment, warn) {
+    try {
+        return await saveToken(appToken, environment, warn);
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw error;
+        }
+        throw new CliError("Your sign-in was approved, but we couldn't save the Driggsby app token\n" +
+            `on this machine. Please sign in again:\n  ${LOGIN_RETRY_COMMAND}`, 1);
+    }
+}
+async function createClaim(baseUrl) {
+    try {
+        return await createClaimRequest(baseUrl);
+    }
+    catch (error) {
+        const blocked = blockedNetworkError(error, {
+            host: apiHost(baseUrl),
+            retryCommand: LOGIN_RETRY_COMMAND,
+        });
+        if (blocked !== null) {
+            throw blocked;
+        }
+        if (error instanceof CliError) {
+            throw error;
+        }
+        throw new CliError(SIGN_IN_START_FAILURE, 1);
+    }
+}
+// The approval page must live on the origin the CLI is talking to. Anything
+// else means a broken or untrustworthy response, and the CLI refuses to
+// print or open it. What comes back is the PARSER'S normalized href with
+// terminal control bytes stripped — the raw server string is never printed
+// or handed to the browser opener.
+function approvedClaimUrl(rawClaimUrl, baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawClaimUrl);
+    }
+    catch {
+        throw new CliError(SIGN_IN_START_FAILURE, 1);
+    }
+    if (parsed.origin !== new URL(baseUrl).origin) {
+        throw new CliError(SIGN_IN_START_FAILURE, 1);
+    }
+    // URL.origin ignores userinfo, so user:pass@ would pass the origin check
+    // while confusing the printed link. Claim URLs never carry credentials.
+    if (parsed.username !== "" || parsed.password !== "") {
+        throw new CliError(SIGN_IN_START_FAILURE, 1);
+    }
+    return sanitizeForTerminal(parsed.href);
+}
+async function pollUntilApproved(baseUrl, claim, io) {
+    const deadline = io.now() + claim.expiresInSeconds * 1_000;
+    const credentials = { claimRequestId: claim.claimRequestId, pollSecret: claim.pollSecret };
+    while (io.now() < deadline) {
+        await io.sleep(io.pollIntervalMs);
+        const result = await pollClaimRequest(baseUrl, credentials);
+        switch (result.kind) {
+            case "approved":
+                // The token is delivered exactly once; from here on, never poll again.
+                return result.appToken;
+            case "gone":
+                throw new CliError("This sign-in link is no longer active — it may have been declined or timed out.\n\n" +
+                    `Start a fresh sign-in:\n  ${LOGIN_RETRY_COMMAND}`, 1);
+            case "pending":
+            case "transient":
+                break;
+        }
+    }
+    throw new CliError("The sign-in link expired before it was approved.\n\n" +
+        `Start a fresh sign-in:\n  ${LOGIN_RETRY_COMMAND}`, 1);
+}
+// DRIGGSBY_TOKEN outranks every saved token, so a login that saved one has
+// not actually changed which token commands use. The warning joins the same
+// held-back channel as storage warnings: after the "Approved." line, in
+// place of the all-clear closer.
+function shadowingEnvTokenWarning(environment) {
+    if (environmentToken(environment) === null) {
+        return null;
+    }
+    return ("Note: DRIGGSBY_TOKEN is set in this environment, and driggsby commands\n" +
+        "use it instead of the token saved just now. Unset DRIGGSBY_TOKEN to\n" +
+        "switch to the saved token.\n");
+}
+function approximateMinutes(seconds) {
+    return Math.max(1, Math.round(seconds / 60));
+}

package/dist/login/logout.js

@@ -0,0 +1,37 @@
+// driggsby logout: remove the app token that login saved, everywhere it
+// could live on this machine. A removal that fails is reported as a failure,
+// never as "nothing to remove" — the token may still work, and the user must
+// know that.
+import { clearStoredToken, defaultCredentialEnvironment, describeStorageLocation, } from "../credentials/store.js";
+import { wrapProse } from "../terminal-text.js";
+function writeToStdout(text) {
+    process.stdout.write(text);
+}
+export async function runLogout(environment = defaultCredentialEnvironment(), out = writeToStdout) {
+    const result = await clearStoredToken(environment);
+    const cleared = result.clearedSources.map(describeStorageLocation).join(" and ");
+    const failed = result.failedSources.map(describeStorageLocation).join(" and ");
+    if (result.failedSources.length > 0) {
+        if (result.clearedSources.length > 0) {
+            out(`${wrapProse(`Your Driggsby app token was removed from ${cleared}.`)}\n\n`);
+        }
+        const keychainHint = result.failedSources.includes("keychain")
+            ? " If your macOS keychain is locked, unlock it first."
+            : result.failedSources.includes("keyring")
+                ? " If your system keyring is locked or unreachable, unlock it first."
+                : "";
+        const failure = `We weren't able to remove your Driggsby app token from ${failed}, ` +
+            `so it may still be saved there.${keychainHint}`;
+        out(`${wrapProse(failure)}\n\nPlease try again:\n  npx driggsby@latest logout\n`);
+    }
+    else if (result.clearedSources.length === 0) {
+        out("No saved Driggsby app token was found on this machine, so there was\nnothing to remove.\n");
+    }
+    else {
+        out(`${wrapProse(`Signed out. Your Driggsby app token was removed from ${cleared}.`)}\n`);
+    }
+    if (result.envTokenStillSet) {
+        out("\nNote: DRIGGSBY_TOKEN is set in this environment and still works. Unset it\nto finish signing out here.\n");
+    }
+    return result.failedSources.length > 0 ? 1 : 0;
+}

package/dist/login/open-url.js

@@ -0,0 +1,79 @@
+// Best-effort browser opening for the consent URL. Failure is always fine —
+// the caller prints the URL either way — so nothing here throws to the user.
+// Only https URLs (plus http on loopback, for the local-server dev override)
+// are ever handed to a platform opener, and the URL is the sole,
+// pre-validated argument: no shell interprets it on POSIX, and the Windows
+// cmd.exe path quotes it with the same rules as the MCP setup spawns.
+import { spawn } from "node:child_process";
+import { win32 } from "node:path";
+import { quoteForCmd } from "../mcp-setup/spawn-plan.js";
+export function openUrlSpawnPlan(url, platform = process.platform, systemRoot = process.env.SystemRoot ?? "C:\\Windows") {
+    if (!isOpenableUrl(url)) {
+        return null;
+    }
+    if (platform === "darwin") {
+        // Absolute path, like /usr/bin/security in the keychain backend: `open`
+        // is a fixed system binary and must not be resolvable off a hijacked
+        // PATH. xdg-open below stays PATH-resolved — its location legitimately
+        // varies across Linux distributions.
+        return { program: "/usr/bin/open", args: [url], windowsVerbatimArguments: false };
+    }
+    if (platform === "win32") {
+        // `start` is a cmd.exe builtin; its first quoted argument is the window
+        // title, so an empty "" keeps the URL from being eaten as the title.
+        const commandLine = ["start", '""', quoteForCmd(url)].join(" ");
+        return {
+            program: win32.join(systemRoot, "System32", "cmd.exe"),
+            args: ["/d", "/s", "/c", `"${commandLine}"`],
+            windowsVerbatimArguments: true,
+        };
+    }
+    return { program: "xdg-open", args: [url], windowsVerbatimArguments: false };
+}
+// The plain RFC 3986 character set, with `%` and `!` deliberately excluded:
+// cmd.exe expands %VAR% even inside quoted arguments, and expands !VAR! the
+// same way on machines with delayed expansion enabled, so a URL carrying
+// either could pull environment values into the URL the Windows opener
+// launches. Claim URLs never contain them; a URL that does is simply not
+// opened (the caller prints the link instead), on every platform for
+// consistency.
+const OPENABLE_URL_CHARACTERS = /^[A-Za-z0-9\-._~:/?#[\]@$&'()*+,;=]*$/;
+function isOpenableUrl(url) {
+    if (!OPENABLE_URL_CHARACTERS.test(url)) {
+        return false;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol === "https:") {
+        return true;
+    }
+    return (parsed.protocol === "http:" &&
+        (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1"));
+}
+// Resolves true once the opener process starts; the page itself may still
+// fail to open, which is why callers always print the URL too.
+export function tryOpenUrl(url, platform = process.platform) {
+    const plan = openUrlSpawnPlan(url, platform);
+    if (plan === null) {
+        return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+        const child = spawn(plan.program, plan.args, {
+            stdio: "ignore",
+            detached: platform !== "win32",
+            windowsVerbatimArguments: plan.windowsVerbatimArguments,
+        });
+        child.on("error", () => {
+            resolve(false);
+        });
+        child.on("spawn", () => {
+            child.unref();
+            resolve(true);
+        });
+    });
+}

package/dist/main.js

@@ -0,0 +1,57 @@
+// CLI entry point. The bin stub (bin/driggsby.js) imports this module; it is
+// never imported as a library.
+import { parseArgv } from "./args.js";
+import { CliError } from "./cli-error.js";
+import { runDeploy } from "./deploy/deploy-command.js";
+import { runDev } from "./dev/dev-command.js";
+import { runInit } from "./init/init-command.js";
+import { runRollback } from "./deploy/rollback-command.js";
+import { runVersions } from "./deploy/versions-command.js";
+import { runLogin } from "./login/login.js";
+import { runLogout } from "./login/logout.js";
+import { runMcpSetup } from "./mcp-setup/setup.js";
+import { VERSION } from "./version.js";
+async function run(argv) {
+    const command = parseArgv(argv);
+    switch (command.kind) {
+        case "print-help": {
+            const stream = command.stream === "stdout" ? process.stdout : process.stderr;
+            stream.write(command.text);
+            return command.exitCode;
+        }
+        case "print-version":
+            process.stdout.write(`driggsby ${VERSION}\n`);
+            return 0;
+        case "mcp-setup":
+            await runMcpSetup({ client: command.client, print: command.print, scope: command.scope });
+            return 0;
+        case "login":
+            await runLogin();
+            return 0;
+        case "logout":
+            return await runLogout();
+        case "init":
+            return await runInit({ slug: command.slug });
+        case "dev":
+            return await runDev();
+        case "deploy":
+            return await runDeploy({ preview: command.preview });
+        case "rollback":
+            return await runRollback({ toVersion: command.toVersion });
+        case "versions":
+            return await runVersions({});
+    }
+}
+try {
+    process.exitCode = await run(process.argv.slice(2));
+}
+catch (error) {
+    if (error instanceof CliError) {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = error.exitCode;
+    }
+    else {
+        process.stderr.write("Something went wrong running driggsby. Please try again.\n");
+        process.exitCode = 1;
+    }
+}

package/dist/mcp-setup/classify.js

@@ -0,0 +1,37 @@
+import { DRIGGSBY_MCP_URL } from "./commands.js";
+import {} from "./known-client.js";
+// Classifies what `claude mcp get driggsby` / `codex mcp get driggsby --json`
+// reported so setup can be idempotent: an entry that already matches is left
+// alone, a different entry gets remove+add remediation, and anything
+// unreadable is treated as unknown so setup just proceeds.
+export function classifyExistingMcpConfig(client, scope, output) {
+    const text = `${output.stdout}\n${output.stderr}`;
+    if (!output.succeeded) {
+        return reportsMissingConfig(text) ? "missing" : "unknown";
+    }
+    return matchesExpectedConfig(client, scope, text) ? "matches" : "differs";
+}
+function reportsMissingConfig(text) {
+    return (text.includes("No MCP server found") ||
+        text.includes("No MCP server named 'driggsby' found") ||
+        text.includes("No MCP server found with name"));
+}
+function matchesExpectedConfig(client, scope, text) {
+    switch (client) {
+        case "claude-code":
+            return (hasLine(text, "Type: http") &&
+                hasLine(text, `URL: ${DRIGGSBY_MCP_URL}`) &&
+                hasClaudeScope(text, scope ?? "user"));
+        case "codex":
+            return (text.includes('"enabled": true') &&
+                text.includes('"type": "streamable_http"') &&
+                text.includes(`"url": "${DRIGGSBY_MCP_URL}"`));
+    }
+}
+function hasClaudeScope(text, scope) {
+    const expected = scope === "local" ? "Scope: Local config" : "Scope: User config";
+    return text.split("\n").some((line) => line.trim().startsWith(expected));
+}
+function hasLine(text, expected) {
+    return text.split("\n").some((line) => line.trim() === expected);
+}

package/dist/mcp-setup/client-command.js

@@ -0,0 +1,133 @@
+import { spawn } from "node:child_process";
+import {} from "./classify.js";
+import {} from "./commands.js";
+import { planSpawn } from "./spawn-plan.js";
+const CLIENT_CONFIG_COMMAND_TIMEOUT_MS = 30_000;
+// After the child exits, wait at most this long for its output pipes to
+// close: a backgrounded grandchild that inherited the pipes must not be able
+// to hang the CLI.
+const OUTPUT_DRAIN_GRACE_MS = 250;
+const LOOPBACK_REDIRECT_NEEDLE = "redirect_uri=http%3A%2F%2F127.0.0.1%3A";
+const BROWSER_LAUNCH_FAILED_NEEDLE = "Browser launch failed";
+const REMOTE_SIGN_IN_HINT_RECENT_CHARS = 512;
+export const REMOTE_SIGN_IN_HINT = `
+Remote sign-in note:
+  The URL above redirects to 127.0.0.1 on this machine.
+  If you opened this terminal over SSH, use SSH local port forwarding before
+  opening the URL in your local browser.
+
+If sign-in times out, run:
+  codex mcp login driggsby
+`;
+// Watches streamed Codex output for the signature of a headless/SSH session
+// (loopback OAuth redirect plus a failed browser launch) and fires exactly
+// once, over a rolling window so the needles can span chunk boundaries.
+export class RemoteSignInHintState {
+    #recentOutput = "";
+    #sawLoopbackRedirect = false;
+    #sawBrowserLaunchFailed = false;
+    #printed = false;
+    observe(text) {
+        this.#recentOutput += text;
+        if (this.#recentOutput.includes(LOOPBACK_REDIRECT_NEEDLE)) {
+            this.#sawLoopbackRedirect = true;
+        }
+        if (this.#recentOutput.includes(BROWSER_LAUNCH_FAILED_NEEDLE)) {
+            this.#sawBrowserLaunchFailed = true;
+        }
+        if (this.#recentOutput.length > REMOTE_SIGN_IN_HINT_RECENT_CHARS) {
+            this.#recentOutput = this.#recentOutput.slice(-REMOTE_SIGN_IN_HINT_RECENT_CHARS);
+        }
+        if (this.#printed || !this.#sawLoopbackRedirect || !this.#sawBrowserLaunchFailed) {
+            return false;
+        }
+        this.#printed = true;
+        return true;
+    }
+}
+// Runs a client CLI command (claude/codex) with a hard timeout. When
+// `streamOutput` is set (Codex, whose OAuth happens in-band) the child's
+// output is echoed live to our own stdout/stderr while still being captured.
+export function runClientCommand(command, streamOutput, timeoutMs = CLIENT_CONFIG_COMMAND_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        // No shell anywhere: spawn-plan.ts resolves Windows .cmd shims through an
+        // explicit cmd.exe invocation and reports a missing program itself
+        // (PATH-only lookup — the current directory is never searched).
+        const plan = planSpawn(command);
+        if (plan === null) {
+            resolve({ kind: "not-found" });
+            return;
+        }
+        const child = spawn(plan.program, plan.args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsVerbatimArguments: plan.windowsVerbatimArguments,
+        });
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            // Tear down our ends of the pipes and drop the child from the event
+            // loop: a backgrounded grandchild that inherited the pipes must not be
+            // able to keep this process alive after the result is decided.
+            child.stdout.destroy();
+            child.stderr.destroy();
+            child.unref();
+            resolve(result);
+        };
+        const hint = streamOutput ? new RemoteSignInHintState() : null;
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const stdoutDone = collectStream(child.stdout, stdoutChunks, streamOutput ? "stdout" : null, hint);
+        const stderrDone = collectStream(child.stderr, stderrChunks, streamOutput ? "stderr" : null, hint);
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            settle({ kind: "timed-out" });
+        }, timeoutMs);
+        timer.unref();
+        child.once("error", (error) => {
+            settle(error.code === "ENOENT" ? { kind: "not-found" } : { kind: "spawn-error" });
+        });
+        child.once("exit", (code) => {
+            void (async () => {
+                // Race the pipes closing against the drain grace, and cancel the
+                // grace timer as soon as the race settles so it can't hold the
+                // process (or add dead wait) after a fast, clean exit.
+                let drainTimer;
+                const drainGrace = new Promise((resolveGrace) => {
+                    drainTimer = setTimeout(resolveGrace, OUTPUT_DRAIN_GRACE_MS);
+                });
+                await Promise.race([Promise.all([stdoutDone, stderrDone]), drainGrace]);
+                clearTimeout(drainTimer);
+                const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+                const stderr = Buffer.concat(stderrChunks).toString("utf8");
+                settle({ kind: "output", output: { succeeded: code === 0, stdout, stderr } });
+            })();
+        });
+    });
+}
+function collectStream(stream, chunks, echoTo, hint) {
+    if (stream === null) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        stream.on("data", (chunk) => {
+            chunks.push(chunk);
+            if (echoTo !== null) {
+                (echoTo === "stdout" ? process.stdout : process.stderr).write(chunk);
+            }
+            if (hint?.observe(chunk.toString("utf8")) === true) {
+                process.stdout.write(REMOTE_SIGN_IN_HINT);
+            }
+        });
+        stream.once("close", () => {
+            resolve();
+        });
+        // A torn-down pipe (e.g. the SIGKILL timeout path on Windows) must end
+        // the collection quietly, never surface as an uncaught stream error.
+        stream.on("error", () => {
+            resolve();
+        });
+    });
+}