svcloud 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svcloud",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "The SV Cloud CLI. Alpha: login, logout, status, open, projects list, mcp, init, and runs are built; see PLANNING.md for what's still missing.",
   "type": "module",
   "license": "UNLICENSED",

package/src/commands/promote.ts

@@ -0,0 +1,85 @@
+/**
+ * `svcloud promote <app>` — put the commit staging is running onto the live app.
+ *
+ * All this does is create a `prod-*` tag and push it. The promotion itself is
+ * GitHub Actions calling SV Cloud, exactly as it would if somebody tagged by
+ * hand — this is a convenience over `git tag`, not a second way in, for the
+ * same reason `svcloud deploy` pushes a branch rather than uploading a build.
+ *
+ * A NEW TAG EVERY TIME, never a moving `prod`. A moving tag needs a force-push
+ * and makes "which commit is live" a question nobody can answer; the server
+ * refuses to point one at a second commit. The date-plus-counter name is picked
+ * here so nobody has to think about it.
+ */
+import type { ProjectSummary } from "@sv/cloud-contracts";
+import { findProjectBySlug } from "../lib/find-project";
+import { existingPromotionTags, gitWorkingState, headSha, pushTag } from "../lib/git";
+import { die, printJson } from "../lib/output";
+
+const USAGE = `Usage: svcloud promote <app> [--commit <sha>] [--tag <name>]
+
+Tags a commit and pushes it, which promotes it to your live app.
+With no --commit, promotes the commit currently checked out.`;
+
+export async function promoteCommand(argv: string[], json: boolean): Promise<void> {
+  const slug = argv.find((a) => !a.startsWith("--"));
+  if (!slug) die(USAGE);
+
+  const project = await findProjectBySlug(slug as string);
+  if (!project) die(`No app named "${slug}".`);
+  assertStaged(project);
+
+  const explicitSha = flagValue(argv, "--commit");
+  const sha = explicitSha ?? (await headSha());
+  if (!sha) {
+    die("Could not work out which commit to promote. Run this inside the app's git repository, or pass --commit <sha>.");
+  }
+
+  // A dirty tree is not fatal here the way it is for `deploy` — the tag names a
+  // commit, and uncommitted work simply is not in it — but somebody who thinks
+  // their latest edit is going live should hear otherwise before it does not.
+  const state = await gitWorkingState();
+  if (state?.dirty && !explicitSha) {
+    console.warn("You have uncommitted changes. They are NOT part of this promotion.");
+  }
+
+  const tag = flagValue(argv, "--tag") ?? (await nextTagName());
+
+  await pushTag(tag, sha as string);
+
+  if (json) {
+    return printJson({ tag, commit_sha: sha, project: project.slug });
+  }
+  console.log(`Tagged ${(sha as string).slice(0, 7)} as ${tag} and pushed it.`);
+  console.log("");
+  console.log("GitHub Actions is promoting it now. Watch it in your repository's Actions tab;");
+  console.log(`your live app is at ${project.web_address ?? "its web address"}.`);
+}
+
+function assertStaged(project: ProjectSummary): void {
+  if (project.deploy_mode === "staged") return;
+  die(
+    `"${project.slug}" does not use a staging environment, so there is nothing to promote — ` +
+      "pushing to its default branch already updates it.\n" +
+      "To start using staging: svcloud staging create <app>",
+  );
+}
+
+/**
+ * `prod-<today>.<n>`, where n is the next free counter for today. Reads the
+ * repo's existing tags rather than assuming, so re-promoting twice in one day
+ * does not collide with a tag the server would refuse to reuse.
+ */
+async function nextTagName(): Promise<string> {
+  const today = new Date().toISOString().slice(0, 10);
+  const prefix = `prod-${today}.`;
+  const used = new Set(await existingPromotionTags());
+  let n = 1;
+  while (used.has(`${prefix}${n}`)) n++;
+  return `${prefix}${n}`;
+}
+
+function flagValue(argv: string[], flag: string): string | undefined {
+  const i = argv.indexOf(flag);
+  return i === -1 ? undefined : argv[i + 1];
+}

package/src/commands/staging.ts

@@ -0,0 +1,126 @@
+/**
+ * `svcloud staging create|status|on|off <app>` — an app's staging environment.
+ *
+ * The rules all live on the server (apps/cloud's services/staging.ts), for the
+ * same reason `bundle` keeps its merge rules there and the MCP bridge holds no
+ * tool registry: a rule enforced in whatever CLI version somebody happens to
+ * have installed is a rule that drifts.
+ *
+ * What this file owes the person running it is the consequence, said plainly.
+ * `on` is the moment pushes to their default branch stop reaching their live
+ * app, and somebody who does not realise that discovers it when a customer asks
+ * where the fix went.
+ */
+import type { ProjectDetail } from "@sv/cloud-contracts";
+import { apiFetch } from "../lib/api";
+import { findProjectBySlug } from "../lib/find-project";
+import { die, printJson } from "../lib/output";
+
+const USAGE = `Usage:
+  svcloud staging create <app>   Give an app a staging environment
+  svcloud staging status <app>   Show whether it is ready to switch over
+  svcloud staging on <app>       Deploy the default branch to staging from now on
+  svcloud staging off <app>      Go back to deploying the live app from the default branch`;
+
+interface Preflight {
+  staging_ready: boolean;
+  workflow_ok: boolean;
+  workflow_problem: string | null;
+  missing_secret_names: string[];
+  deploy_mode: "direct" | "staged";
+}
+
+export async function stagingCommand(argv: string[], json: boolean): Promise<void> {
+  const [subcommand, slug] = argv;
+  if (!subcommand || !slug) die(USAGE);
+
+  const project = await findProjectBySlug(slug as string);
+  if (!project) die(`No app named "${slug}".`);
+
+  switch (subcommand) {
+    case "create":
+      return create(project.id, json);
+    case "status":
+      return status(project.id, json);
+    case "on":
+      return on(project.id, argv.includes("--force"), json);
+    case "off":
+      return off(project.id, json);
+    default:
+      die(`Unknown subcommand: ${subcommand}\n\n${USAGE}`);
+  }
+}
+
+async function create(projectId: string, json: boolean): Promise<void> {
+  const result = await apiFetch<{
+    staging?: ProjectDetail;
+    already_exists?: boolean;
+    run_id?: string;
+  }>(`/api/v1/projects/${projectId}/staging`, { method: "POST" });
+
+  if (json) return printJson(result);
+
+  if (result.already_exists) {
+    console.log("This app already has a staging environment.");
+    console.log(`  ${result.staging?.web_address ?? ""}`);
+    return;
+  }
+  console.log("Setting up a staging environment.");
+  console.log(`  ${result.staging?.web_address ?? ""}`);
+  console.log("");
+  // Said before they ask: creating it costs money and changes nothing yet.
+  console.log("This is a second copy of your app, with its own database and files.");
+  console.log("Its usage comes out of the same plan allowance as your live app.");
+  console.log("");
+  console.log("Nothing has changed about where your pushes go yet.");
+  console.log("Run `svcloud staging status <app>` to see what is left before switching over.");
+}
+
+async function status(projectId: string, json: boolean): Promise<void> {
+  const result = await apiFetch<Preflight>(`/api/v1/projects/${projectId}/staging/preflight`);
+  if (json) return printJson(result);
+
+  if (result.deploy_mode === "staged") {
+    console.log("Pushes to your default branch deploy staging.");
+    console.log("Your live app changes when you push a prod-* tag.");
+    return;
+  }
+
+  console.log("Pushes to your default branch deploy your live app.");
+  console.log("");
+  console.log(`  staging environment   ${result.staging_ready ? "ready" : "not created yet"}`);
+  console.log(
+    `  deploy workflow       ${result.workflow_ok ? "ready" : (result.workflow_problem ?? "not ready")}`,
+  );
+  if (result.missing_secret_names.length > 0) {
+    console.log(`  settings              ${result.missing_secret_names.length} missing on staging:`);
+    for (const name of result.missing_secret_names) console.log(`      ${name}`);
+    console.log("");
+    // The likeliest reason a first staging build fails, and nothing can copy
+    // them across: SV Cloud never sees a setting's value after it is set.
+    console.log("Add these with `svcloud secrets set` before switching over, or the");
+    console.log("first staging build is likely to fail.");
+  } else {
+    console.log("  settings              ready");
+  }
+}
+
+async function on(projectId: string, force: boolean, json: boolean): Promise<void> {
+  const result = await apiFetch<{ project: ProjectDetail; note: string }>(
+    `/api/v1/projects/${projectId}/staging/enable${force ? "?force=1" : ""}`,
+    { method: "POST" },
+  );
+  if (json) return printJson(result);
+  console.log(result.note);
+  console.log("");
+  console.log("To go back at any time: svcloud staging off <app>");
+}
+
+async function off(projectId: string, json: boolean): Promise<void> {
+  const result = await apiFetch<{ project: ProjectDetail; note: string }>(
+    `/api/v1/projects/${projectId}/staging/disable`,
+    { method: "POST" },
+  );
+  if (json) return printJson(result);
+  console.log(result.note);
+}

package/src/index.ts

@@ -17,6 +17,8 @@ import { projectsCommand } from "./commands/projects";
 import { runsCommand } from "./commands/runs";
 import { secretsCommand } from "./commands/secrets";
 import { storageCommand } from "./commands/storage";
+import { promoteCommand } from "./commands/promote";
+import { stagingCommand } from "./commands/staging";
 import { statusCommand } from "./commands/status";
 import { whoamiCommand } from "./commands/whoami";
 import { AuthRequiredError, ApiError } from "./lib/api";
@@ -38,6 +40,8 @@ Usage:
   svcloud storage presign       Get a direct URL for one file in an app's storage
   svcloud db <cmd>              Browse and edit an app's database (see 'svcloud db' for subcommands)
   svcloud deploy <app>          Push the current branch and watch the build (must be the app's default branch)
+  svcloud staging <cmd>         An app's staging environment (create/status/on/off)
+  svcloud promote <app>         Tag the current commit and put it on the live app
   svcloud bundle <cmd>          Keep an app's starter current (status/update/done)
   svcloud mcp                   Run the local MCP bridge (for a coding agent's harness config)
   svcloud mcp setup <harness>   Write a coding agent harness's MCP config for svcloud
@@ -109,6 +113,12 @@ async function main(): Promise<void> {
     case "deploy":
       await deployCommand(rest, json);
       return;
+    case "staging":
+      await stagingCommand(rest, json);
+      return;
+    case "promote":
+      await promoteCommand(rest, json);
+      return;
     case "version":
     case "-v":
     case "--version":

package/src/lib/browser.ts

@@ -7,15 +7,49 @@
  */
 import { spawn } from "node:child_process";
 
+export interface LaunchPlan {
+  command: string;
+  args: string[];
+  /** Windows only: pass the args through to cmd.exe exactly as written. */
+  verbatim: boolean;
+}
+
+/**
+ * Split out from `openBrowser` so the Windows quoting can be tested without
+ * spawning anything. The Windows branch is the whole reason this exists:
+ * cmd.exe parses the command line before `start` ever sees it, and `&` is a
+ * command separator there, so an unquoted OAuth URL is truncated at its first
+ * parameter boundary. The browser then opens `...?response_type=code` with
+ * nothing after it and `GET /oauth/authorize` answers `Query parameter
+ * "client_id" is required.` Quoting the URL stops the split, and
+ * `windowsVerbatimArguments` stops Node from re-quoting the quotes we just
+ * added (its own escaping targets the MSVCRT argument parser, which runs
+ * after cmd's, and so never escapes cmd metacharacters). The bare `""` is
+ * `start`'s optional window-title argument: without it, `start` takes the
+ * quoted URL for the title and opens nothing.
+ */
+export function planBrowserLaunch(platform: NodeJS.Platform, url: string): LaunchPlan {
+  if (platform === "darwin") {
+    return { command: "open", args: [url], verbatim: false };
+  }
+  if (platform === "win32") {
+    return {
+      command: "cmd.exe",
+      args: ["/c", "start", '""', `"${url}"`],
+      verbatim: true,
+    };
+  }
+  return { command: "xdg-open", args: [url], verbatim: false };
+}
+
 export function openBrowser(url: string): void {
   try {
-    if (process.platform === "darwin") {
-      spawn("open", [url], { stdio: "ignore", detached: true }).unref();
-    } else if (process.platform === "win32") {
-      spawn("cmd", ["/c", "start", '""', url], { stdio: "ignore", detached: true }).unref();
-    } else {
-      spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
-    }
+    const plan = planBrowserLaunch(process.platform, url);
+    spawn(plan.command, plan.args, {
+      stdio: "ignore",
+      detached: true,
+      windowsVerbatimArguments: plan.verbatim,
+    }).unref();
   } catch {
     // The printed URL is the fallback; nothing else to do here.
   }

package/src/lib/credentials.ts

@@ -145,15 +145,44 @@ async function linuxClear(): Promise<void> {
  * Windows Credential Manager has no CLI that can both write and read a
  * secret back out (`cmdkey` is write-only), so this goes through
  * PowerShell's P/Invoke of advapi32's CredWrite/CredRead/CredDelete
- * directly — untested on Windows (this CLI was built and verified on
- * macOS); any failure here falls back to the plaintext file below rather
- * than surfacing a build-only error to a novice.
+ * directly. Verified on Windows 11 / PowerShell 5.1 on 2026-09-18, after
+ * it had never once worked: two defects, and the second is why the first
+ * was invisible for so long.
+ *
+ * 1. The prologue passed `-UsingNamespace System.Runtime.InteropServices`.
+ *    `Add-Type -MemberDefinition` ALREADY emits that using directive, so
+ *    this produced a second one — CS0105 — and Add-Type compiles
+ *    warnings-as-errors, so the type never came into existence and every
+ *    `[SvCloud.Cred]::...` call below failed with "Unable to find type".
+ *    Do not re-add it; the directive is implicit.
+ *
+ * 2. Neither failure set a non-zero exit code. Add-Type's compile error and
+ *    the subsequent "type not found" are both NON-TERMINATING errors, and
+ *    `powershell -Command` exits 0 after them, so `execFile` saw success:
+ *    `platformSave` returned true, the plaintext fallback never fired, and
+ *    the token went nowhere. `svcloud login` printed no error and every
+ *    later command said "Not signed in" — which reads as a server bug.
+ *    Hence `$ErrorActionPreference` plus the `trap`: any terminating error
+ *    now exits 1, which is the only thing `run()` can actually detect.
+ *
+ * `platformSave` additionally reads back what it wrote (see there), so a
+ * store that accepts a write it cannot return is treated as no store at
+ * all, on every platform rather than just this one.
  */
 function psTarget(): string {
   return `${CREDENTIAL_SERVICE}/${credentialAccount()}`;
 }
 
-const PS_PROLOGUE = `
+/**
+ * Exported only so `test/windows-credentials.test.ts` can pin the two
+ * defects above from any platform — the same reason `planBrowserLaunch` is
+ * split out of `openBrowser`. Neither is reproducible on the machines this
+ * CLI is developed on, and both failed silently, so the shape is worth
+ * asserting directly rather than trusting a reviewer to notice.
+ */
+export const PS_PROLOGUE = `
+$ErrorActionPreference = "Stop"
+trap { [Console]::Error.WriteLine($_.Exception.Message); exit 1 }
 Add-Type -Namespace SvCloud -Name Cred -MemberDefinition @'
 [DllImport("advapi32.dll", SetLastError=true, CharSet=CharSet.Unicode)]
 public static extern bool CredWrite(ref CREDENTIAL credential, uint flags);
@@ -170,7 +199,7 @@ public struct CREDENTIAL {
   public uint Persist; public uint AttributeCount; public IntPtr Attributes;
   public string TargetAlias; public string UserName;
 }
-'@ -UsingNamespace System.Runtime.InteropServices
+'@
 `;
 
 async function windowsSave(json: string): Promise<void> {
@@ -232,16 +261,30 @@ async function fallbackClear(): Promise<void> {
   await rm(fallbackFile(), { force: true });
 }
 
+/**
+ * Returns true only if the keychain both accepted the write AND hands the
+ * same bytes back. The read-back is the point: a store that swallows a write
+ * and then returns nothing is WORSE than an absent one, because `saveTokens`
+ * treats it as done and the plaintext fallback never runs — so `svcloud
+ * login` reports success, stores nothing anywhere, and every later command
+ * says "Not signed in" with no error to explain it. That is exactly how the
+ * Windows path failed from its introduction until 2026-09-18 (see the
+ * Windows section's header). Verifying here rather than in `windowsSave`
+ * covers all three platforms, since nothing about the trap is specific to
+ * this one: a locked macOS Keychain or a container with no Secret Service
+ * would land the same way. A mismatch degrades to the documented plaintext
+ * file with its warning, which is a working sign-in.
+ */
 async function platformSave(json: string): Promise<boolean> {
   try {
     if (process.platform === "darwin") await macosSave(json);
     else if (process.platform === "linux") await linuxSave(json);
     else if (process.platform === "win32") await windowsSave(json);
     else return false;
-    return true;
   } catch {
     return false;
   }
+  return (await platformLoad()) === json;
 }
 
 async function platformLoad(): Promise<string | undefined> {

package/src/lib/git.ts

@@ -75,3 +75,36 @@ export async function gitWorkingState(cwd: string = process.cwd()): Promise<GitW
 export async function pushCurrentBranch(cwd: string = process.cwd()): Promise<void> {
   await run("git", ["push"], { cwd });
 }
+
+/** The commit the current branch points at, for naming and confirming a promotion. */
+export async function headSha(cwd: string = process.cwd()): Promise<string | undefined> {
+  try {
+    const { stdout } = await run("git", ["rev-parse", "HEAD"], { cwd });
+    return stdout.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Create an annotated tag and push it. Throws with git's own stderr on failure. */
+export async function pushTag(
+  tag: string,
+  sha: string,
+  cwd: string = process.cwd(),
+): Promise<void> {
+  await run("git", ["tag", tag, sha], { cwd });
+  await run("git", ["push", "origin", tag], { cwd });
+}
+
+/** The promotion tags already on this repo, newest first, so a new one can avoid colliding. */
+export async function existingPromotionTags(cwd: string = process.cwd()): Promise<string[]> {
+  try {
+    const { stdout } = await run("git", ["tag", "--list", "prod-*"], { cwd });
+    return stdout
+      .split("\n")
+      .map((t) => t.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/src/lib/self.ts

@@ -18,6 +18,12 @@
  * used rather than the npm shim: the shim's exec bit and its `.cmd`
  * wrapper on Windows are two more things that can be wrong, and
  * `process.execPath` is neither.
+ *
+ * ON WINDOWS THE BARE NAME IS NEVER WRITTEN, whatever PATH says — see
+ * `planBridgeCommand`. That is a separate question from whether the
+ * OWNER's shell can reach `svcloud`, which is what `isOnPath` answers and
+ * what `mcp check` reports; the two were previously the same code path and
+ * are now deliberately not.
  */
 import { accessSync, constants } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
@@ -29,23 +35,76 @@ export function ownBinPath(): string {
   return join(here, "..", "..", "bin", "svcloud.js");
 }
 
+/** Windows' documented default when PATHEXT is unset. */
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
 /**
- * Whether a bare `svcloud` resolves to an executable on this PATH.
+ * The suffixes a bare name may resolve through on this platform.
+ *
+ * Windows has no execute BIT. `accessSync(..., X_OK)` is documented as
+ * having no effect there and degrades to a plain existence check, and
+ * `chmodSync` only toggles the read-only flag — so on Windows the suffix
+ * list is the ONLY thing carrying the meaning of "executable", and it has
+ * to come from PATHEXT rather than a hardcoded guess. (A real machine's
+ * PATHEXT is longer than the four anyone hardcodes: the one this was
+ * verified on carries twelve, `.JS` among them.)
+ *
+ * The extensionless file is deliberately NOT accepted on Windows, and that
+ * is the decision worth knowing here. `npm install -g svcloud` writes
+ * THREE shims — `svcloud`, `svcloud.cmd` and `svcloud.ps1` — and only the
+ * bare one is unrunnable by cmd.exe, PowerShell and CreateProcess alike.
+ * Git Bash would run it, which is the argument for keeping it, but every
+ * real global install has the `.cmd` beside it, so accepting the bare file
+ * changes the answer only when the `.cmd` is ABSENT — precisely the case
+ * where claiming "on PATH" would be wrong for two of the three shells a
+ * Windows owner might be in. Being wrong in that direction is the
+ * expensive one: a false yes leaves an owner believing a broken install is
+ * fine, while a false no costs a `pathHint` nobody is harmed by.
+ */
+export function executableSuffixes(
+  platform: NodeJS.Platform,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  if (platform !== "win32") return [""];
+  const raw = env.PATHEXT ?? DEFAULT_PATHEXT;
+  const parsed = raw
+    .split(";")
+    .map((ext) => ext.trim())
+    .filter(Boolean);
+  // An empty or whitespace-only PATHEXT is a broken environment, not an
+  // instruction to accept every extensionless file on PATH.
+  return parsed.length > 0 ? parsed : DEFAULT_PATHEXT.split(";");
+}
+
+/**
+ * Whether a bare `svcloud` resolves to something the OWNER'S SHELL would
+ * run, on this PATH.
  *
  * Deliberately not `which`/`where`: spawning a shell to answer a question
  * about the environment we are already in is slower and less predictable
- * than reading PATH ourselves. On Windows a bare name is resolved against
- * PATHEXT, so the shim's real filename there is `svcloud.cmd`.
+ * than reading PATH ourselves.
+ *
+ * This answers a question about a shell, NOT about what a harness can
+ * spawn — those differ on Windows, and conflating them is what
+ * `planBridgeCommand` now keeps apart. `mcp check` reports this one to the
+ * owner; the config written to disk does not depend on it there.
+ *
+ * `name` is assumed to carry no extension of its own (its only caller
+ * passes the default): on Windows every candidate is `name` + a PATHEXT
+ * suffix, so passing `"svcloud.cmd"` would look for `svcloud.cmd.exe`.
  */
 export function isOnPath(name = "svcloud", env: NodeJS.ProcessEnv = process.env): boolean {
   const raw = env.PATH ?? env.Path ?? "";
   if (!raw) return false;
-  const suffixes = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
+  // X_OK means something only where an execute bit exists; see
+  // `executableSuffixes` for why Windows checks mere existence instead.
+  const mode = process.platform === "win32" ? constants.F_OK : constants.X_OK;
+  const suffixes = executableSuffixes(process.platform, env);
   for (const dir of raw.split(delimiter)) {
     if (!dir) continue;
     for (const suffix of suffixes) {
       try {
-        accessSync(join(dir, `${name}${suffix}`), constants.X_OK);
+        accessSync(join(dir, `${name}${suffix}`), mode);
         return true;
       } catch {
         /* Not here; keep looking. */
@@ -62,10 +121,48 @@ export interface BridgeCommand {
   onPath: boolean;
 }
 
+/**
+ * Split out of `bridgeCommand` so the Windows rule is testable from the
+ * platforms this CLI is actually developed on — the same reason
+ * `planBrowserLaunch` exists in `lib/browser.ts`.
+ *
+ * ON WINDOWS THE BARE NAME IS REFUSED EVEN WHEN IT IS ON PATH. A harness
+ * starts an MCP server by spawning a child process, and Node's default is
+ * `shell: false`. Measured on Windows 11 / Node 24.19 against the shims
+ * `npm install -g svcloud` really writes:
+ *
+ *   spawn("svcloud",     …)  no shell → ENOENT  — CreateProcess appends
+ *                                        only `.exe`, and npm writes no
+ *                                        `svcloud.exe`; PATHEXT is a
+ *                                        SHELL's rule, not CreateProcess's
+ *   spawn("svcloud.cmd", …)  no shell → EINVAL  — Node refuses to spawn
+ *                                        .cmd/.bat without a shell at all
+ *                                        (the CVE-2024-27980 mitigation)
+ *   spawn(execPath, [binPath])  no shell → works
+ *
+ * So on Windows `isOnPath` being true says the owner's shell can reach
+ * `svcloud`, and says nothing about whether a harness can — writing the
+ * bare name there produces exactly the failure this file exists to
+ * prevent: a server that never starts, with no error the owner ever sees.
+ * The absolute form works with or without a shell, so Windows always gets
+ * it. `onPath` reports the form that was CHOSEN, not what PATH holds;
+ * `mcp check` calls `isOnPath` directly for the latter.
+ */
+export function planBridgeCommand(
+  platform: NodeJS.Platform,
+  onPath: boolean,
+  execPath: string,
+  binPath: string,
+): BridgeCommand {
+  if (platform !== "win32" && onPath) {
+    return { command: "svcloud", args: ["mcp"], onPath: true };
+  }
+  return { command: execPath, args: [binPath, "mcp"], onPath: false };
+}
+
 /** The `command` + `args` a harness config should use to run `svcloud mcp`. */
 export function bridgeCommand(): BridgeCommand {
-  if (isOnPath()) return { command: "svcloud", args: ["mcp"], onPath: true };
-  return { command: process.execPath, args: [ownBinPath(), "mcp"], onPath: false };
+  return planBridgeCommand(process.platform, isOnPath(), process.execPath, ownBinPath());
 }
 
 /**