@vellumai/cli 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/lib/__tests__/lifecycle-reporter.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+
+import { consoleLifecycleReporter } from "../lifecycle-reporter.js";
+
+describe("consoleLifecycleReporter", () => {
+  const originalDesktopApp = process.env.VELLUM_DESKTOP_APP;
+  let stdoutWriteSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    stdoutWriteSpy = spyOn(process.stdout, "write").mockImplementation(
+      () => true,
+    );
+  });
+
+  afterEach(() => {
+    stdoutWriteSpy.mockRestore();
+    if (originalDesktopApp === undefined) {
+      delete process.env.VELLUM_DESKTOP_APP;
+    } else {
+      process.env.VELLUM_DESKTOP_APP = originalDesktopApp;
+    }
+  });
+
+  test("routes log/warn/error to the matching console methods", () => {
+    const logSpy = spyOn(console, "log").mockImplementation(() => {});
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    consoleLifecycleReporter.log("hello");
+    consoleLifecycleReporter.warn("careful");
+    consoleLifecycleReporter.error("boom");
+
+    expect(logSpy).toHaveBeenCalledWith("hello");
+    expect(warnSpy).toHaveBeenCalledWith("careful");
+    expect(errorSpy).toHaveBeenCalledWith("boom");
+
+    logSpy.mockRestore();
+    warnSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("emits the HATCH_PROGRESS stdout contract under VELLUM_DESKTOP_APP", () => {
+    process.env.VELLUM_DESKTOP_APP = "1";
+
+    consoleLifecycleReporter.progress(3, 6, "Starting assistant...");
+
+    expect(stdoutWriteSpy).toHaveBeenCalledWith(
+      `HATCH_PROGRESS:${JSON.stringify({ step: 3, total: 6, label: "Starting assistant..." })}\n`,
+    );
+  });
+
+  test("suppresses progress output when not running under the desktop app", () => {
+    delete process.env.VELLUM_DESKTOP_APP;
+
+    consoleLifecycleReporter.progress(1, 6, "Allocating resources...");
+
+    expect(stdoutWriteSpy).not.toHaveBeenCalled();
+  });
+});

package/src/lib/__tests__/step-runner.test.ts

@@ -1,6 +1,15 @@
+import { mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
 import { describe, expect, it } from "bun:test";
 
-import { buildExecErrorMessage, exec, execOutput } from "../step-runner";
+import {
+  buildExecErrorMessage,
+  exec,
+  execOutput,
+  execWithStdin,
+} from "../step-runner";
 
 describe("buildExecErrorMessage", () => {
   it("omits the argv from the header so secrets in args can't leak", () => {
@@ -63,6 +72,45 @@ describe("exec — secret leak regression", () => {
   });
 });
 
+describe("execWithStdin — pipes input + no secret leak in errors", () => {
+  it("writes the supplied input to the child's stdin", async () => {
+    // Use sh `cat > path` to capture stdin to a real file we can inspect.
+    // Mirrors the Docker-hatch overlay-staging call site shape.
+    const workDir = mkdtempSync(join(tmpdir(), "step-runner-stdin-"));
+    const dest = join(workDir, "captured.txt");
+    try {
+      const payload = '{"hello":"world"}\n';
+      await execWithStdin("sh", ["-c", `cat > ${dest}`], payload);
+      expect(readFileSync(dest, "utf-8")).toBe(payload);
+    } finally {
+      rmSync(workDir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects with an Error whose message contains neither the args nor any -e KEY=VALUE pair", async () => {
+    const fakeSecret = "sk-anthropic-stdin-canary";
+    try {
+      await execWithStdin(
+        "sh",
+        [
+          "-c",
+          'echo "permission denied while trying to connect to docker daemon" 1>&2 && exit 1',
+          "-e",
+          `ANTHROPIC_API_KEY=${fakeSecret}`,
+        ],
+        "",
+      );
+      throw new Error("execWithStdin should have rejected");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      expect(message).not.toContain(fakeSecret);
+      expect(message).not.toContain("ANTHROPIC_API_KEY");
+      expect(message).toContain("sh exited with code 1");
+      expect(message).toContain("permission denied");
+    }
+  });
+});
+
 describe("execOutput — secret leak regression", () => {
   it("rejects with an Error whose message contains neither the args nor any -e KEY=VALUE pair", async () => {
     const fakeSecret = "sk-openai-leak-canary";

package/src/lib/assistant-client.ts

@@ -12,11 +12,9 @@
  * ```
  */
 
-import {
-  resolveAssistant,
-} from "./assistant-config.js";
+import { resolveAssistant } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
-import { loadGuardianToken } from "./guardian-token.js";
+import { loadGuardianToken, refreshGuardianToken } from "./guardian-token.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
@@ -45,7 +43,8 @@ export class AssistantClient {
   readonly runtimeUrl: string;
 
   private readonly _assistantId: string;
-  private readonly token: string | undefined;
+  /** Mutable: a 401 on the guardian path refreshes this in place (see request). */
+  private token: string | undefined;
   /** True when token is a platform session token (X-Session-Token), false for guardian JWT (Authorization: Bearer). */
   private readonly isSessionAuth: boolean;
   private readonly orgId: string | undefined;
@@ -176,45 +175,67 @@ export class AssistantClient {
       ? `?${new URLSearchParams(opts.query).toString()}`
       : "";
     const url = `${this.runtimeUrl}/v1/assistants/${this._assistantId}${urlPath}${qs}`;
-
-    const headers: Record<string, string> = { ...opts?.headers };
-    if (this.token) {
-      if (this.isSessionAuth) {
-        headers["X-Session-Token"] ??= this.token;
-      } else {
-        headers["Authorization"] ??= `Bearer ${this.token}`;
-      }
-    }
-    if (this.orgId) {
-      headers["Vellum-Organization-Id"] ??= this.orgId;
-    }
-    if (body !== undefined) {
-      headers["Content-Type"] = "application/json";
-    }
-
     const jsonBody = body !== undefined ? JSON.stringify(body) : undefined;
 
-    if (opts?.signal) {
+    // Headers are built per-attempt so a refreshed token is picked up on retry.
+    const buildHeaders = (): Record<string, string> => {
+      const headers: Record<string, string> = { ...opts?.headers };
+      if (this.token) {
+        if (this.isSessionAuth) {
+          headers["X-Session-Token"] ??= this.token;
+        } else {
+          headers["Authorization"] ??= `Bearer ${this.token}`;
+        }
+      }
+      if (this.orgId) {
+        headers["Vellum-Organization-Id"] ??= this.orgId;
+      }
+      if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+      }
+      return headers;
+    };
+
+    const doFetch = (): Promise<Response> => {
+      const headers = buildHeaders();
+      if (opts?.signal) {
+        return fetch(url, {
+          method,
+          headers,
+          body: jsonBody,
+          signal: opts.signal,
+        });
+      }
+      const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
       return fetch(url, {
-        method,
-        headers,
-        body: jsonBody,
-        signal: opts.signal,
-      });
-    }
-
-    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
-    try {
-      return await fetch(url, {
         method,
         headers,
         body: jsonBody,
         signal: controller.signal,
-      });
-    } finally {
-      clearTimeout(timeoutId);
+      }).finally(() => clearTimeout(timeoutId));
+    };
+
+    const response = await doFetch();
+
+    // Reactive auto-refresh: a paired/local guardian access token that has
+    // expired comes back 401. Refresh it once via the stored refresh credential
+    // and retry. Self-gating — refreshGuardianToken returns null unless a usable
+    // refresh token is stored, so ephemeral (`--token`) and access-only sessions
+    // just see the original 401. The platform session-auth path is never
+    // refreshed here (its token is managed by the Vellum platform).
+    if (response.status === 401 && !this.isSessionAuth) {
+      const refreshed = await refreshGuardianToken(
+        this.runtimeUrl,
+        this._assistantId,
+      );
+      if (refreshed?.accessToken) {
+        this.token = refreshed.accessToken;
+        return doFetch();
+      }
     }
+
+    return response;
   }
 }

package/src/lib/assistant-config.ts

@@ -10,6 +10,8 @@ import {
 import { homedir } from "os";
 import { dirname, join } from "path";
 
+import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./constants.js";
 import {
   getDefaultPorts,
@@ -18,8 +20,6 @@ import {
   getMultiInstanceDir,
 } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
-import { SEEDS } from "./environments/seeds.js";
-import type { EnvironmentDefinition } from "./environments/types.js";
 import { probePort } from "./port-probe.js";
 
 /**
@@ -76,7 +76,19 @@ export interface AssistantEntry {
    *  Avoids mDNS resolution issues when the machine checks its own gateway. */
   localUrl?: string;
   bearerToken?: string;
+  /** Deployment topology / how the assistant is reached. Known values:
+   *  `"local"` (on-machine daemon), `"docker"` (local container),
+   *  `"apple-container"` (macOS-app-managed container), `"vellum"`
+   *  (platform-managed, uses the X-Session-Token auth path), `"gcp"` / `"aws"`
+   *  / `"custom"` (remote, SSH-managed), and `"paired"` (a remote assistant
+   *  paired from another machine — reached via a bearer guardian token at
+   *  `runtimeUrl`; has no local process, container, or `resources`).
+   *  Kept as a free `string` (not a union) for forward-compatibility. */
   cloud: string;
+  /** True when this entry was registered via `vellum connect import` (a remote
+   *  pairing). Set alongside `cloud: "paired"`; also backs the re-import /
+   *  overwrite guard in connect import. */
+  paired?: boolean;
   instanceId?: string;
   namespace?: string;
   project?: string;
@@ -559,6 +571,19 @@ export function resolveCloud(entry: AssistantEntry): string {
   return "local";
 }
 
+/**
+ * Extract the hostname from a URL string. Falls back to stripping the scheme
+ * and taking the hostname portion if URL parsing fails.
+ */
+export function extractHostFromUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname;
+  } catch {
+    return url.replace(/^https?:\/\//, "").split(":")[0];
+  }
+}
+
 export function saveAssistantEntry(entry: AssistantEntry): void {
   const entries = readAssistants().filter(
     (e) => e.assistantId !== entry.assistantId,
@@ -618,7 +643,7 @@ export async function allocateLocalResources(
 
   // Env-aware bases: non-prod envs sit in their own 1000-port window so
   // running prod and staging assistants side-by-side doesn't collide. See
-  // `environments/seeds.ts:portBlock` for the layout.
+  // the `@vellumai/environments` `portBlock` layout.
   const basePorts = getDefaultPorts(env);
   const daemonPort = await findAvailablePort(basePorts.daemon, reservedPorts);
   const gatewayPort = await findAvailablePort(basePorts.gateway, [

package/src/lib/cloudflare-tunnel.ts

@@ -0,0 +1,276 @@
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { GATEWAY_PORT } from "./constants.js";
+
+// ── Workspace config helpers (mirrors the pattern in ngrok.ts) ───────────────
+
+function getDefaultWorkspaceDir(): string {
+  return (
+    process.env.VELLUM_WORKSPACE_DIR?.trim() ||
+    join(homedir(), ".vellum", "workspace")
+  );
+}
+
+function getConfigPath(workspaceDir: string): string {
+  return join(workspaceDir, "config.json");
+}
+
+function loadRawConfig(workspaceDir: string): Record<string, unknown> {
+  const configPath = getConfigPath(workspaceDir);
+  if (!existsSync(configPath)) return {};
+  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+}
+
+function saveRawConfig(
+  workspaceDir: string,
+  config: Record<string, unknown>,
+): void {
+  const configPath = getConfigPath(workspaceDir);
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+function saveIngressUrl(workspaceDir: string, publicUrl: string): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  ingress.publicBaseUrl = publicUrl;
+  ingress.enabled = true;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+function clearIngressUrl(workspaceDir: string): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  delete ingress.publicBaseUrl;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+// ── Cloudflare Tunnel ─────────────────────────────────────────────────────────
+
+const CLOUDFLARED_TIMEOUT_MS = 30_000;
+
+// Quick-tunnel hostnames follow the pattern <word>-<word>-<word>.trycloudflare.com
+const QUICK_TUNNEL_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+/**
+ * Check whether cloudflared is installed and on PATH.
+ * Returns the version string if found, null otherwise.
+ */
+export function getCloudflareTunnelVersion(): string | null {
+  try {
+    const output = execFileSync("cloudflared", ["version"], {
+      encoding: "utf-8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spawn a cloudflared quick-tunnel process forwarding HTTP traffic to
+ * `targetPort`.  The child process writes its public URL to stderr during
+ * startup — use {@link waitForCloudflareTunnelUrl} to extract it.
+ */
+export function startCloudflareTunnelProcess(targetPort: number): ChildProcess {
+  return spawn(
+    "cloudflared",
+    ["tunnel", "--url", `http://localhost:${targetPort}`, "--no-autoupdate"],
+    // Keep stdio as pipes so we can parse the URL from output.
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+}
+
+/**
+ * Listen to a running cloudflared process's stdout/stderr and resolve with
+ * the public quick-tunnel URL once cloudflared prints it.
+ *
+ * cloudflared emits a line containing the trycloudflare.com URL during
+ * startup — typically within 5–15 seconds on a normal internet connection.
+ *
+ * Rejects when:
+ * - The URL does not appear within `timeoutMs`.
+ * - The child process exits before the URL is found.
+ */
+export function waitForCloudflareTunnelUrl(
+  child: ChildProcess,
+  timeoutMs: number = CLOUDFLARED_TIMEOUT_MS,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `cloudflared tunnel URL did not appear within ${timeoutMs / 1000}s. ` +
+            `Ensure cloudflared is working: try running 'cloudflared tunnel --url http://localhost:8080' manually.`,
+        ),
+      );
+    }, timeoutMs);
+
+    let resolved = false;
+
+    function scanLine(line: string): void {
+      if (resolved) return;
+      const match = QUICK_TUNNEL_URL_RE.exec(line);
+      if (match) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve(match[0]);
+      }
+    }
+
+    // Buffer incomplete lines across chunks
+    let stdoutBuf = "";
+    let stderrBuf = "";
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdoutBuf += chunk.toString();
+      const lines = stdoutBuf.split("\n");
+      stdoutBuf = lines.pop() ?? "";
+      for (const line of lines) scanLine(line);
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrBuf += chunk.toString();
+      const lines = stderrBuf.split("\n");
+      stderrBuf = lines.pop() ?? "";
+      for (const line of lines) scanLine(line);
+    });
+
+    child.on("exit", (code) => {
+      if (resolved) return;
+      clearTimeout(timer);
+      reject(
+        new Error(
+          `cloudflared exited with code ${code ?? "unknown"} before the tunnel URL appeared.`,
+        ),
+      );
+    });
+  });
+}
+
+/**
+ * Run the cloudflared quick-tunnel workflow:
+ * 1. Verify cloudflared is installed.
+ * 2. Start a quick tunnel pointing at the gateway port.
+ * 3. Parse the public URL from cloudflared output.
+ * 4. Persist the URL to the workspace config as the ingress base URL.
+ * 5. Block until the process exits or the user presses Ctrl+C.
+ * 6. Clear the ingress URL from config on exit.
+ *
+ * No Cloudflare account is required — quick tunnels are free and ephemeral.
+ */
+export interface RunCloudflareTunnelOptions {
+  /** Gateway port to forward. Defaults to the global GATEWAY_PORT. */
+  port?: number;
+  /** Workspace directory for config read/write. Defaults to ~/.vellum/workspace. */
+  workspaceDir?: string;
+}
+
+export async function runCloudflareTunnel(
+  opts: RunCloudflareTunnelOptions = {},
+): Promise<void> {
+  const version = getCloudflareTunnelVersion();
+  if (!version) {
+    console.error("Error: cloudflared is not installed.");
+    console.error("");
+    console.error("Install cloudflared:");
+    console.error("  macOS:   brew install cloudflare/cloudflare/cloudflared");
+    console.error("  Linux:   https://pkg.cloudflare.com/index.html");
+    console.error(
+      "  Windows: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
+    );
+    console.error("");
+    console.error("No Cloudflare account is required for quick tunnels.");
+    process.exit(1);
+  }
+
+  console.log(`Using ${version}`);
+
+  const port = opts.port ?? GATEWAY_PORT;
+  const workspaceDir = opts.workspaceDir ?? getDefaultWorkspaceDir();
+
+  console.log(`Starting cloudflared quick tunnel to localhost:${port}...`);
+  console.log("No Cloudflare account required — quick tunnels are free.");
+  console.log("");
+
+  let publicUrl: string | undefined;
+  const child = startCloudflareTunnelProcess(port);
+
+  const cleanup = (): void => {
+    if (!child.killed) child.kill("SIGTERM");
+    if (publicUrl) {
+      console.log("\nClearing ingress URL from config...");
+      clearIngressUrl(workspaceDir);
+    }
+  };
+
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  child.on("error", (err: Error) => {
+    console.error(`cloudflared process error: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    // Always clear the saved ingress URL when the tunnel process ends so
+    // webhook integrations don't keep hitting a dead endpoint.
+    if (publicUrl !== undefined) {
+      clearIngressUrl(workspaceDir);
+    }
+    if (code !== null && code !== 0) {
+      console.error(`\ncloudflared exited with code ${code}.`);
+      process.exit(1);
+    }
+  });
+
+  // Forward cloudflared output to the console so the user can see startup
+  // progress and any authentication errors.
+  child.stdout?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[cloudflared] ${line}`);
+  });
+  child.stderr?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[cloudflared] ${line}`);
+  });
+
+  try {
+    publicUrl = await waitForCloudflareTunnelUrl(child);
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  console.log("");
+  console.log(`Tunnel established: ${publicUrl}`);
+  console.log(`Forwarding to:     localhost:${port}`);
+  console.log("");
+
+  saveIngressUrl(workspaceDir, publicUrl);
+  console.log("Ingress URL saved to config.");
+  console.log("");
+  console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
+
+  // Keep running until cloudflared exits (e.g., network error or user Ctrl+C)
+  await new Promise<void>((resolve) => {
+    child.on("exit", () => resolve());
+  });
+}

package/src/lib/config-utils.ts

@@ -35,6 +35,21 @@ export function buildNestedConfig(
 /**
  * Ensure hatch always provides enough initial LLM config for the assistant to
  * detect a fresh off-platform hatch and seed BYOK profiles.
+ *
+ * @deprecated Part of the workspace-config overlay path — a CLI→Assistant
+ * side channel that bypasses the Assistant's public APIs and has no
+ * equivalent in web/desktop. Two replacement paths are on the table:
+ *
+ *   1. Post-hatch API calls — the CLI calls public Assistant routes after
+ *      boot (`POST /v1/secrets`, plus a small read-only endpoint that
+ *      returns the canonical inference-profile templates so the CLI can
+ *      PATCH them in). See the closed alternatives in PR #32061 and
+ *      PR #32131 for the shape this would take.
+ *   2. Move inference-profile seeds out of workspace config and into
+ *      Assistant code, so there is nothing for the CLI to inject in the
+ *      first place.
+ *
+ * Either path removes the need for this helper.
  */
 export function buildHatchConfigValues(
   configValues: Record<string, string>,
@@ -52,15 +67,21 @@ export function buildHatchConfigValues(
 
 /**
  * Write arbitrary key-value pairs to a temporary JSON file and return its
- * path. The caller passes this path to the daemon via the
- * VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH env var so the daemon can merge the
- * values into its workspace config on first boot.
+ * path. The caller is responsible for getting the file to the daemon — for
+ * the local hatch flow that means setting `VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH`
+ * on the daemon process; for the Docker hatch flow the caller stages the
+ * file into the workspace volume so the rename-after-consume step in
+ * `mergeDefaultWorkspaceConfig` is a same-filesystem rename.
  *
  * Keys use dot-notation to address nested fields. For example:
  *   "llm.default.provider" → {llm: {default: {provider: ...}}}
  *   "llm.default.model"    → {llm: {default: {model: ...}}}
  *
  * Returns undefined when configValues is empty (nothing to write).
+ *
+ * @deprecated See {@link buildHatchConfigValues} for the replacement
+ * direction. This overlay path is a CLI→Assistant side channel and will be
+ * removed once one of the documented replacements lands.
  */
 export function writeInitialConfig(
   configValues: Record<string, string>,

package/src/lib/confirm-action.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared interactive confirmation for destructive CLI commands (retire, unpair,
+ * …). Per cli/AGENTS.md, a command that removes assistant state must print the
+ * resolved identity and require confirmation, with a `--yes` bypass for
+ * automation.
+ */
+
+/** True only when we can run an interactive raw-mode confirmation prompt. */
+export function canPromptForConfirmation(): boolean {
+  return (
+    process.stdin.isTTY === true &&
+    process.stdout.isTTY === true &&
+    typeof process.stdin.setRawMode === "function"
+  );
+}
+
+/**
+ * Show `prompt` and resolve true on Enter, false on Esc/q/Ctrl-C. Restores the
+ * prior stdin raw/paused state on exit. Caller must gate on
+ * {@link canPromptForConfirmation} first.
+ */
+export async function confirmAction(prompt: string): Promise<boolean> {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  const wasRaw = stdin.isRaw === true;
+  const wasPaused = stdin.isPaused();
+
+  stdout.write(prompt);
+  stdin.setRawMode(true);
+  stdin.resume();
+
+  return await new Promise<boolean>((resolve) => {
+    const cleanup = () => {
+      stdin.off("data", onData);
+      stdin.setRawMode(wasRaw);
+      if (wasPaused) {
+        stdin.pause();
+      }
+      stdout.write("\n");
+    };
+
+    const onData = (chunk: Buffer) => {
+      const byte = chunk[0];
+      if (byte === 13 || byte === 10) {
+        cleanup();
+        resolve(true);
+        return;
+      }
+      if (byte === 27 || byte === 3 || byte === 113 || byte === 81) {
+        cleanup();
+        resolve(false);
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}