svcloud 0.1.0-alpha.3

package/src/lib/credentials.ts

@@ -0,0 +1,294 @@
+/**
+ * Where `svcloud login` puts the token pair, and every other command reads
+ * it from. PLANNING.md §2's storage table: OS keychain first, with a
+ * documented (never silent) file fallback.
+ *
+ *   macOS   — Keychain, via the `security` CLI (no native module, no build
+ *             step for a package that has to run via `npx`).
+ *   Linux   — Secret Service (libsecret), via `secret-tool`, when present.
+ *   Windows — Credential Manager, via a small PowerShell script that
+ *             P/Invokes advapi32's CredWrite/CredRead/CredDelete (same
+ *             reasoning: no native module).
+ *
+ * Any of the above failing for any reason (tool missing, no desktop
+ * keyring running in a container, permission denied) falls back to
+ * `~/.config/svcloud/credentials.json` at mode 0600. `save()` prints a
+ * one-time warning when it lands there, since that is the moment an
+ * unencrypted token actually touches disk — every later read/write of the
+ * same fallback file stays silent, so routine commands aren't noisy.
+ *
+ * `SVCLOUD_CREDENTIALS_FILE`, if set, bypasses the OS keychain entirely and
+ * reads/writes that exact plaintext file instead — test-only, so the
+ * `mcp` command's stdio tests (`test/mcp-bridge.test.ts`) can drive a
+ * throwaway token store without touching a developer's real macOS Keychain
+ * or their real `svcloud login` session. Never set by any shipped command.
+ */
+import { execFile } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { CREDENTIAL_ACCOUNT, CREDENTIAL_SERVICE } from "./config";
+
+const run = promisify(execFile);
+
+export interface TokenSet {
+  accessToken: string;
+  refreshToken: string;
+  /** Epoch ms. */
+  expiresAt: number;
+  scopes: string[];
+}
+
+const FALLBACK_DIR = join(homedir(), ".config", "svcloud");
+const FALLBACK_FILE = join(FALLBACK_DIR, "credentials.json");
+
+async function macosSave(json: string): Promise<void> {
+  // -U: update in place if an entry already exists, so a re-login doesn't
+  // need a delete-then-add and doesn't prompt twice.
+  await run("security", [
+    "add-generic-password",
+    "-a",
+    CREDENTIAL_ACCOUNT,
+    "-s",
+    CREDENTIAL_SERVICE,
+    "-w",
+    json,
+    "-U",
+  ]);
+}
+
+async function macosLoad(): Promise<string | undefined> {
+  try {
+    const { stdout } = await run("security", [
+      "find-generic-password",
+      "-a",
+      CREDENTIAL_ACCOUNT,
+      "-s",
+      CREDENTIAL_SERVICE,
+      "-w",
+    ]);
+    return stdout.replace(/\n$/, "");
+  } catch {
+    return undefined;
+  }
+}
+
+async function macosClear(): Promise<void> {
+  await run("security", [
+    "delete-generic-password",
+    "-a",
+    CREDENTIAL_ACCOUNT,
+    "-s",
+    CREDENTIAL_SERVICE,
+  ]).catch(() => {
+    // Nothing stored: deleting an absent item is not a failure here.
+  });
+}
+
+async function linuxSave(json: string): Promise<void> {
+  // execFile has no `input` option (that's execFileSync-only); util.promisify's
+  // execFile attaches the live ChildProcess as `.child` on the returned
+  // promise specifically so callers can write to stdin before awaiting it.
+  const pending = run("secret-tool", [
+    "store",
+    "--label=SV Cloud CLI credentials",
+    "service",
+    CREDENTIAL_SERVICE,
+    "account",
+    CREDENTIAL_ACCOUNT,
+  ]);
+  pending.child.stdin?.end(json);
+  await pending;
+}
+
+async function linuxLoad(): Promise<string | undefined> {
+  try {
+    const { stdout } = await run("secret-tool", [
+      "lookup",
+      "service",
+      CREDENTIAL_SERVICE,
+      "account",
+      CREDENTIAL_ACCOUNT,
+    ]);
+    return stdout.replace(/\n$/, "") || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function linuxClear(): Promise<void> {
+  await run("secret-tool", [
+    "clear",
+    "service",
+    CREDENTIAL_SERVICE,
+    "account",
+    CREDENTIAL_ACCOUNT,
+  ]).catch(() => {});
+}
+
+/**
+ * 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.
+ */
+const PS_TARGET = `${CREDENTIAL_SERVICE}/${CREDENTIAL_ACCOUNT}`;
+
+const PS_PROLOGUE = `
+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);
+[DllImport("advapi32.dll", SetLastError=true, CharSet=CharSet.Unicode)]
+public static extern bool CredRead(string target, uint type, uint flags, out IntPtr credentialPtr);
+[DllImport("advapi32.dll", SetLastError=true, CharSet=CharSet.Unicode)]
+public static extern bool CredDelete(string target, uint type, uint flags);
+[DllImport("advapi32.dll")]
+public static extern void CredFree(IntPtr buffer);
+[StructLayout(LayoutKind.Sequential, CharSet=CharSet.Unicode)]
+public struct CREDENTIAL {
+  public uint Flags; public uint Type; public string TargetName; public string Comment;
+  public long LastWritten; public uint CredentialBlobSize; public IntPtr CredentialBlob;
+  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> {
+  const bytes = Buffer.from(json, "utf16le");
+  const script = `${PS_PROLOGUE}
+$bytes = [Convert]::FromBase64String("${bytes.toString("base64")}")
+$blob = [Runtime.InteropServices.Marshal]::AllocHGlobal($bytes.Length)
+[Runtime.InteropServices.Marshal]::Copy($bytes, 0, $blob, $bytes.Length)
+$cred = New-Object SvCloud.Cred+CREDENTIAL
+$cred.Type = 1; $cred.TargetName = "${PS_TARGET}"; $cred.CredentialBlobSize = $bytes.Length
+$cred.CredentialBlob = $blob; $cred.Persist = 2; $cred.UserName = "${CREDENTIAL_ACCOUNT}"
+if (-not [SvCloud.Cred]::CredWrite([ref]$cred, 0)) { throw "CredWrite failed" }
+[Runtime.InteropServices.Marshal]::FreeHGlobal($blob)`;
+  await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script]);
+}
+
+async function windowsLoad(): Promise<string | undefined> {
+  const script = `${PS_PROLOGUE}
+$ptr = [IntPtr]::Zero
+if (-not [SvCloud.Cred]::CredRead("${PS_TARGET}", 1, 0, [ref]$ptr)) { exit 1 }
+$cred = [Runtime.InteropServices.Marshal]::PtrToStructure($ptr, [Type][SvCloud.Cred+CREDENTIAL])
+$bytes = New-Object byte[] $cred.CredentialBlobSize
+[Runtime.InteropServices.Marshal]::Copy($cred.CredentialBlob, $bytes, 0, $cred.CredentialBlobSize)
+[SvCloud.Cred]::CredFree($ptr)
+[Console]::Out.Write([Convert]::ToBase64String($bytes))`;
+  try {
+    const { stdout } = await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script]);
+    if (!stdout.trim()) return undefined;
+    return Buffer.from(stdout.trim(), "base64").toString("utf16le");
+  } catch {
+    return undefined;
+  }
+}
+
+async function windowsClear(): Promise<void> {
+  const script = `${PS_PROLOGUE}[SvCloud.Cred]::CredDelete("${PS_TARGET}", 1, 0) | Out-Null`;
+  await run("powershell", ["-NoProfile", "-NonInteractive", "-Command", script]).catch(() => {});
+}
+
+async function fallbackSave(json: string): Promise<void> {
+  await mkdir(FALLBACK_DIR, { recursive: true, mode: 0o700 });
+  await writeFile(FALLBACK_FILE, json, { mode: 0o600 });
+  console.error(
+    `Note: your SV Cloud sign-in is stored in plain text at ${FALLBACK_FILE} ` +
+      "because no system keychain was available. Anyone who can read that " +
+      "file can act as you until you run `svcloud logout`.",
+  );
+}
+
+async function fallbackLoad(): Promise<string | undefined> {
+  try {
+    return await readFile(FALLBACK_FILE, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+async function fallbackClear(): Promise<void> {
+  await rm(FALLBACK_FILE, { force: true });
+}
+
+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;
+  }
+}
+
+async function platformLoad(): Promise<string | undefined> {
+  try {
+    if (process.platform === "darwin") return await macosLoad();
+    if (process.platform === "linux") return await linuxLoad();
+    if (process.platform === "win32") return await windowsLoad();
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function platformClear(): Promise<void> {
+  try {
+    if (process.platform === "darwin") await macosClear();
+    else if (process.platform === "linux") await linuxClear();
+    else if (process.platform === "win32") await windowsClear();
+  } catch {
+    // Best-effort: an absent or already-cleared entry is not a failure.
+  }
+}
+
+async function testOverrideSave(path: string, json: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, json, { mode: 0o600 });
+}
+
+async function testOverrideLoad(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+export async function saveTokens(tokens: TokenSet): Promise<void> {
+  const json = JSON.stringify(tokens);
+  const override = process.env.SVCLOUD_CREDENTIALS_FILE;
+  if (override) return testOverrideSave(override, json);
+  if (await platformSave(json)) return;
+  await fallbackSave(json);
+}
+
+export async function loadTokens(): Promise<TokenSet | undefined> {
+  const override = process.env.SVCLOUD_CREDENTIALS_FILE;
+  const json = override
+    ? await testOverrideLoad(override)
+    : (await platformLoad()) ?? (await fallbackLoad());
+  if (!json) return undefined;
+  try {
+    return JSON.parse(json) as TokenSet;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function clearTokens(): Promise<void> {
+  const override = process.env.SVCLOUD_CREDENTIALS_FILE;
+  if (override) {
+    await rm(override, { force: true });
+    return;
+  }
+  await platformClear();
+  await fallbackClear();
+}

package/src/lib/deploy-poll.ts

@@ -0,0 +1,64 @@
+/**
+ * `svcloud deploy`'s poller — watches `GET /:id/deploys` for a row that
+ * isn't the pre-push baseline id, since a push produces a *new* deploy row
+ * rather than moving a known one through states the caller already has an id
+ * for (unlike `lib/run-poll.ts`'s run polling). Split out from
+ * `commands/deploy.ts` so it's unit-testable with a tiny `intervalMs`/
+ * `timeoutMs`, the same reason `run-poll.ts` lives apart from `init`/`runs`.
+ */
+import type { DeploySummary } from "@sv/cloud-contracts";
+
+const TERMINAL_DEPLOY_STATUSES: ReadonlySet<DeploySummary["status"]> = new Set([
+  "live",
+  "failed",
+  "superseded",
+  "rolled_back",
+]);
+
+export interface DeployPollResult {
+  deploy: DeploySummary | undefined;
+  /** A deploy row appeared but was still `building` when the timeout hit. */
+  timedOut: boolean;
+}
+
+export interface DeployPollOptions {
+  intervalMs?: number;
+  timeoutMs?: number;
+  quiet?: boolean;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Prints each status transition once (never per-tick), the same restraint
+ * `run-poll.ts` uses for run steps.
+ */
+export async function pollForNewDeploy(
+  fetchDeploys: () => Promise<DeploySummary[]>,
+  baselineId: string | undefined,
+  opts: DeployPollOptions = {},
+): Promise<DeployPollResult> {
+  const interval = opts.intervalMs ?? 3000;
+  const timeout = opts.timeoutMs ?? 10 * 60 * 1000;
+  const start = Date.now();
+  let lastPrinted: string | undefined;
+
+  for (;;) {
+    const deploys = await fetchDeploys();
+    const latest = deploys[0];
+    const isNew = latest !== undefined && latest.id !== baselineId;
+    if (isNew && latest.status !== lastPrinted) {
+      if (!opts.quiet) console.log(`  ${latest.status}`);
+      lastPrinted = latest.status;
+    }
+    if (isNew && TERMINAL_DEPLOY_STATUSES.has(latest.status)) {
+      return { deploy: latest, timedOut: false };
+    }
+    if (Date.now() - start > timeout) {
+      return { deploy: isNew ? latest : undefined, timedOut: true };
+    }
+    await sleep(interval);
+  }
+}

package/src/lib/discovery.ts

@@ -0,0 +1,28 @@
+/**
+ * RFC 8414 authorization-server metadata (`apps/cloud/src/routes/discovery.ts`).
+ * Read once per process and cached: PLANNING.md §2 is explicit that the CLI
+ * should read these endpoints from discovery rather than hardcode them, so a
+ * future change to cloud-api's OAuth path layout doesn't need a CLI release.
+ */
+import { apiBaseUrl } from "./config";
+
+export interface AuthServerMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  revocation_endpoint: string;
+}
+
+let cached: AuthServerMetadata | undefined;
+
+export async function getAuthServerMetadata(): Promise<AuthServerMetadata> {
+  if (cached) return cached;
+  const res = await fetch(`${apiBaseUrl()}/.well-known/oauth-authorization-server`);
+  if (!res.ok) {
+    throw new Error(
+      `Could not reach SV Cloud (${res.status}). Check your connection and try again.`,
+    );
+  }
+  cached = (await res.json()) as AuthServerMetadata;
+  return cached;
+}

package/src/lib/find-project.ts

@@ -0,0 +1,10 @@
+/** Shared by `status` and `open`: resolve a slug to its `ProjectSummary` via `GET /projects?slug=`. */
+import type { ProjectSummary } from "@sv/cloud-contracts";
+import { apiFetch } from "./api";
+
+export async function findProjectBySlug(slug: string): Promise<ProjectSummary | undefined> {
+  const { projects } = await apiFetch<{ projects: ProjectSummary[] }>(
+    `/api/v1/projects?slug=${encodeURIComponent(slug)}`,
+  );
+  return projects[0];
+}

package/src/lib/git.ts

@@ -0,0 +1,77 @@
+/**
+ * `svcloud init`'s repo inference — `git remote get-url origin` in the
+ * working directory, parsed into `<owner>/<repo>` so a first-timer never has
+ * to type `--repo` for the common case (PLANNING.md §3.1: init is "adopt an
+ * existing local project", so the working directory is the starting point).
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+export interface GitOriginRepo {
+  owner: string;
+  repo: string;
+  /** `<owner>/<repo>`, the shape `POST /projects/connect`'s `repo_full_name` expects. */
+  fullName: string;
+}
+
+function stripGitSuffix(raw: string): string {
+  return raw.replace(/\.git$/, "");
+}
+
+// git@host:owner/repo(.git)?
+const SSH_RE = /^git@[^:]+:([^/]+)\/([^/]+)$/;
+// https://host/owner/repo(.git)?(/)?
+const HTTPS_RE = /^https?:\/\/[^/]+\/([^/]+)\/([^/]+?)\/?$/;
+
+function parseOriginUrl(url: string): GitOriginRepo | undefined {
+  const ssh = SSH_RE.exec(url.trim());
+  const https = HTTPS_RE.exec(url.trim());
+  const match = ssh ?? https;
+  if (!match) return undefined;
+  const owner = match[1] as string;
+  const repo = stripGitSuffix(match[2] as string);
+  return { owner, repo, fullName: `${owner}/${repo}` };
+}
+
+/** `undefined` if there's no `origin` remote, or it isn't a recognizable owner/repo URL. */
+export async function inferRepoFromCwd(cwd: string = process.cwd()): Promise<GitOriginRepo | undefined> {
+  try {
+    const { stdout } = await run("git", ["remote", "get-url", "origin"], { cwd });
+    return parseOriginUrl(stdout);
+  } catch {
+    return undefined;
+  }
+}
+
+export interface GitWorkingState {
+  branch: string;
+  dirty: boolean;
+}
+
+/**
+ * `svcloud deploy`'s preconditions (PLANNING.md §3.3's "refuse, with a clear
+ * message, if the working tree is dirty or the branch is not the project's
+ * default_branch"). `undefined` if `cwd` isn't a readable git repo (no `git`
+ * on PATH, not a repo, or detached HEAD — there's no branch to push from any
+ * of those, and the caller should say so rather than guessing).
+ */
+export async function gitWorkingState(cwd: string = process.cwd()): Promise<GitWorkingState | undefined> {
+  try {
+    const [{ stdout: branchOut }, { stdout: statusOut }] = await Promise.all([
+      run("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd }),
+      run("git", ["status", "--porcelain"], { cwd }),
+    ]);
+    const branch = branchOut.trim();
+    if (!branch || branch === "HEAD") return undefined;
+    return { branch, dirty: statusOut.trim().length > 0 };
+  } catch {
+    return undefined;
+  }
+}
+
+/** `git push` (current branch, default remote) in `cwd`. Throws with git's own stderr on failure. */
+export async function pushCurrentBranch(cwd: string = process.cwd()): Promise<void> {
+  await run("git", ["push"], { cwd });
+}

package/src/lib/loopback-server.ts

@@ -0,0 +1,71 @@
+/**
+ * The `127.0.0.1:<random port>/callback` listener `svcloud login` opens the
+ * browser at cloud-api's `redirect_uri`. PLANNING.md §2 step 5: cloud-web's
+ * consent screen redirects the browser here with `?code=...`, this file
+ * captures it and shuts down, then step 6 exchanges the code.
+ */
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+
+export interface CallbackResult {
+  code?: string;
+  state?: string;
+  error?: string;
+}
+
+export interface LoopbackListener {
+  port: number;
+  /** Resolves with the first callback request's query params, or rejects on timeout. */
+  waitForCallback(timeoutMs: number): Promise<CallbackResult>;
+  close(): void;
+}
+
+const CALLBACK_PAGE = (ok: boolean) => `<!doctype html>
+<html><head><title>SV Cloud</title></head>
+<body style="font-family:system-ui;padding:2rem;color:#111">
+<h1>${ok ? "You're signed in." : "Sign-in didn't finish."}</h1>
+<p>You can close this tab and go back to your terminal.</p>
+</body></html>`;
+
+export function startLoopbackListener(): Promise<LoopbackListener> {
+  return new Promise((resolve, reject) => {
+    let resultResolve: ((r: CallbackResult) => void) | undefined;
+    const resultPromise = new Promise<CallbackResult>((res) => {
+      resultResolve = res;
+    });
+
+    const server = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (url.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      const code = url.searchParams.get("code") ?? undefined;
+      const state = url.searchParams.get("state") ?? undefined;
+      const error = url.searchParams.get("error") ?? undefined;
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      res.end(CALLBACK_PAGE(!error && !!code));
+      resultResolve?.({ code, state, error });
+    });
+
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address() as AddressInfo;
+      resolve({
+        port,
+        close: () => server.close(),
+        waitForCallback: (timeoutMs: number) =>
+          Promise.race([
+            resultPromise,
+            new Promise<CallbackResult>((_, rej) => {
+              const timer = setTimeout(
+                () => rej(new Error("Timed out waiting for the browser to finish sign-in.")),
+                timeoutMs,
+              );
+              timer.unref();
+            }),
+          ]),
+      });
+    });
+  });
+}

package/src/lib/output.ts

@@ -0,0 +1,47 @@
+/**
+ * `--json` on every read command (PLANNING.md §1's non-negotiable #3), plus
+ * a plain table for humans. No color/box-drawing dependency: the audience
+ * includes an agent's stdout parser as often as a terminal.
+ */
+
+export function hasFlag(argv: string[], name: string): { present: boolean; rest: string[] } {
+  const flag = `--${name}`;
+  const present = argv.includes(flag);
+  return { present, rest: argv.filter((a) => a !== flag) };
+}
+
+/** A `--name value` pair, pulled out of argv wherever it sits. Only the first occurrence counts. */
+export function takeOption(argv: string[], name: string): { value: string | undefined; rest: string[] } {
+  const flag = `--${name}`;
+  const idx = argv.indexOf(flag);
+  if (idx === -1) return { value: undefined, rest: argv };
+  const value = argv[idx + 1];
+  const rest = [...argv.slice(0, idx), ...argv.slice(idx + 2)];
+  return { value, rest };
+}
+
+export function printJson(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+/** Fixed-width columns, left-aligned, two spaces between them. */
+export function printTable(rows: Record<string, string>[], columns: string[]): void {
+  if (rows.length === 0) {
+    console.log("(none)");
+    return;
+  }
+  const widths = columns.map((col) =>
+    Math.max(col.length, ...rows.map((r) => (r[col] ?? "").length)),
+  );
+  const line = (cells: string[]) =>
+    cells.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ");
+  console.log(line(columns));
+  for (const row of rows) {
+    console.log(line(columns.map((col) => row[col] ?? "")));
+  }
+}
+
+export function die(message: string): never {
+  console.error(message);
+  process.exit(1);
+}

package/src/lib/pkce.ts

@@ -0,0 +1,17 @@
+/**
+ * PKCE (RFC 7636) for the loopback login flow. Mirrors what
+ * `apps/cloud/src/lib/pkce.ts` verifies server-side: a 43-128 character
+ * unreserved-charset verifier, and its S256 challenge. `plain` is never
+ * generated here since `cloud-api` refuses it outright.
+ */
+import { createHash, randomBytes } from "node:crypto";
+
+export function generateVerifier(): string {
+  // 32 random bytes -> 43 base64url characters, inside the 43-128 range RFC
+  // 7636 requires and cloud-api's verifyPkce enforces.
+  return randomBytes(32).toString("base64url");
+}
+
+export function challengeFromVerifier(verifier: string): string {
+  return createHash("sha256").update(verifier).digest("base64url");
+}

package/src/lib/prompt.ts

@@ -0,0 +1,43 @@
+/**
+ * Interactive prompts for a human running `svcloud init` at a real terminal.
+ * `isInteractive()` is the gate every command using this should check first —
+ * a coding agent or CI shelling out gets no prompt, only a `die()` naming the
+ * flag that would have answered it (PLANNING.md's "an agent should be going
+ * through `svcloud mcp`, not shelling out and parsing text" — the flag-driven
+ * path is for the human and CI cases that remain).
+ */
+import { createInterface } from "node:readline/promises";
+
+export function isInteractive(): boolean {
+  return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+
+export async function prompt(question: string, defaultValue?: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    const answer = (await rl.question(`${question}${suffix}: `)).trim();
+    return answer.length > 0 ? answer : (defaultValue ?? "");
+  } finally {
+    rl.close();
+  }
+}
+
+export async function confirm(question: string, defaultYes = true): Promise<boolean> {
+  const suffix = defaultYes ? "Y/n" : "y/N";
+  const answer = (await prompt(`${question} (${suffix})`)).trim().toLowerCase();
+  if (answer.length === 0) return defaultYes;
+  return answer === "y" || answer === "yes";
+}
+
+/** Numbered choice, 1-indexed on screen. Re-prompts on an out-of-range or non-numeric answer. */
+export async function choose(question: string, options: string[]): Promise<number> {
+  console.log(question);
+  options.forEach((opt, i) => console.log(`  ${i + 1}. ${opt}`));
+  for (;;) {
+    const answer = await prompt("Enter a number");
+    const n = Number.parseInt(answer, 10);
+    if (Number.isInteger(n) && n >= 1 && n <= options.length) return n - 1;
+    console.log(`Enter a number from 1 to ${options.length}.`);
+  }
+}