switchroom 0.7.15 → 0.10.0

package/telegram-plugin/uat/harness.ts

@@ -3,11 +3,20 @@
  *
  * Issue: https://github.com/switchroom/switchroom/issues/866
  *
- * `spinUp({ agent, topic })` is the single entry point a scenario
- * uses. Phase 1 ships the type shape + the lifecycle skeleton; the
- * actual `child_process.spawn` of the agent under test is stubbed
- * with TODO markers so the reviewer can see exactly where Phase 2
- * lands.
+ * `spinUp({ agent })` connects the mtcute driver and resolves the test
+ * bot's user_id, returning a Scenario the test can interact with.
+ *
+ * **Runtime model — Phase 2a (DM focus):** the test-harness agent is
+ * a standard switchroom agent the operator created once via
+ * `switchroom agent add test-harness ...` (see uat/SETUP.md). The
+ * harness does NOT spin the agent up per-scenario — it relies on the
+ * agent being already running. Per-scenario state isolation rolls in
+ * with Phase 2b once we move beyond DM smoke tests.
+ *
+ * Forum-topic routing, ephemeral STATE_DIR, child-process agents, and
+ * the progress-card observers are deferred to Phase 2b (#866 v2) — the
+ * epic's original plan was written before the Docker runtime landed
+ * and would substantially re-invent the agent lifecycle.
  */
 
 import { Driver } from "./driver.js";
@@ -19,32 +28,65 @@ import {
   type PollOptions,
   type PinnedCardSnapshot,
 } from "./assertions.js";
-import { allocatePort } from "./port-allocator.js";
+import type { ObservedMessage } from "./driver.js";
+import { loadUatEnv } from "./load-env.js";
+
+loadUatEnv();
 
 export interface SpinUpOptions {
-  /** Agent name to install + run, e.g. `"clerk"`, `"test-harness"`. */
+  /**
+   * Agent name to run scenarios against, e.g. `"test-harness"`. The
+   * agent must already be configured + running (Phase 2a: standard
+   * runtime + persistent agent).
+   */
   agent: string;
   /**
-   * Forum topic slug for isolation. The harness creates the topic in
-   * the test supergroup and tears it down after the scenario.
+   * Bot username (with or without `@`) the harness should resolve to
+   * a user_id. Defaults to `process.env.TELEGRAM_TEST_BOT_USERNAME`.
+   */
+  botUsername?: string;
+  /**
+   * Settle delay (ms) after the driver connects, before the scenario's
+   * first send. Gives the previous scenario's turn time to finish its
+   * outbound stream on the agent side. Without this the next inbound
+   * lands while the gateway is still pinning/editing the prior turn's
+   * card, the gateway reuses the existing pin via edit (instead of
+   * pinning a new message), and observePins-based assertions miss the
+   * event entirely. Default {@link DEFAULT_SETTLE_MS}; set to 0 for
+   * single-scenario runs where the cooldown is dead time. Scenarios
+   * that account for this in their outer `it()` budget should add the
+   * settle on top of inner poll deadlines.
    */
-  topic: string;
+  settleMs?: number;
 }
 
+export const DEFAULT_SETTLE_MS = 8_000;
+
 export interface Scenario {
   /** mtcute driver, already connected. */
   driver: Driver;
-  /** Negative supergroup chat id; from `$SWITCHROOM_UAT_CHAT_ID`. */
-  chatId: number;
-  /** Topic id created for this scenario. */
-  threadId: number;
+  /** Test bot's Telegram user_id; doubles as the chat_id for DMs. */
+  botUserId: number;
+  /** Driver user account's Telegram user_id. */
+  driverUserId: number;
 
-  // Sugar over the assertion helpers, pre-bound to this scenario's
-  // chat + thread. Phase 1 returns a thin pass-through.
+  /** Sugar for `driver.sendText(botUserId, text)`. */
+  sendDM: (text: string) => Promise<{ messageId: number }>;
+
+  /**
+   * Wait for the next message in the bot DM chat matching `match`.
+   * `opts.from` filters by sender side: `"bot"` for replies from the
+   * test bot, `"driver"` for the driver's own echoes (rare in
+   * scenarios but useful for assertions on the outbound side).
+   */
   expectMessage: (
-    match: Parameters<typeof expectMessage>[2],
-    opts: PollOptions & { from?: "bot" | "user" },
-  ) => ReturnType<typeof expectMessage>;
+    match: string | RegExp | ((m: ObservedMessage) => boolean),
+    opts: PollOptions & { from?: "bot" | "driver" },
+  ) => Promise<ObservedMessage>;
+
+  // Phase 2b stubs — type-only so existing scenarios that reference
+  // these helpers still typecheck after this PR. Implementations land
+  // alongside `observeReactions` / `observePins` in #866 v2.
   expectReaction: (
     messageId: number,
     sequence: string[],
@@ -57,105 +99,109 @@ export interface Scenario {
     opts: PollOptions,
   ) => ReturnType<typeof waitForCardPhase>;
 
-  /** Stop the agent process, delete the topic, disconnect the driver. */
+  /** Disconnect the driver. The persistent test-harness agent keeps running. */
   tearDown: () => Promise<void>;
 }
 
-/**
- * Spin up an isolated agent + scenario context.
- *
- * Phase 1: returns a stub Scenario whose tools throw helpful "not
- * implemented" errors. The shape is correct so scenarios written
- * against it will typecheck today and run for real once Phase 2
- * lands.
- */
-export async function spinUp(opts: SpinUpOptions): Promise<Scenario> {
-  // TODO(#866): resolve secrets from vault.
-  //   - `telegram-test-bot-token` for the agent under test
-  //   - `telegram-uat-driver-session` for the mtcute driver
-  //   - `TELEGRAM_API_ID` / `TELEGRAM_API_HASH` from env
-  // For now we throw early with a clear message so accidental runs
-  // before Phase 2 don't crash with confusing stack traces.
-  if (!process.env.SWITCHROOM_UAT_CHAT_ID) {
-    throw new Error(
-      "[uat/harness] SWITCHROOM_UAT_CHAT_ID is not set — see uat/SETUP.md §2",
+interface ResolvedConfig {
+  apiId: number;
+  apiHash: string;
+  session: string;
+  botUsername: string;
+}
+
+function resolveConfig(opts: SpinUpOptions): ResolvedConfig {
+  const apiId = Number.parseInt(process.env.TELEGRAM_API_ID ?? "", 10);
+  if (!Number.isFinite(apiId)) {
+    fail("TELEGRAM_API_ID is missing or not an integer — see uat/SETUP.md §3");
+  }
+  const apiHash = process.env.TELEGRAM_API_HASH ?? "";
+  if (apiHash.length === 0) {
+    fail("TELEGRAM_API_HASH is empty — see uat/SETUP.md §3");
+  }
+  const session = process.env.TELEGRAM_UAT_DRIVER_SESSION ?? "";
+  if (session.length === 0) {
+    fail(
+      "TELEGRAM_UAT_DRIVER_SESSION is empty — run `bun run uat:login` first " +
+        "(see uat/SETUP.md §4)",
     );
   }
-  const chatId = Number.parseInt(process.env.SWITCHROOM_UAT_CHAT_ID, 10);
-  if (!Number.isFinite(chatId) || chatId >= 0) {
-    throw new Error(
-      `[uat/harness] SWITCHROOM_UAT_CHAT_ID must be a negative supergroup id (got ${process.env.SWITCHROOM_UAT_CHAT_ID})`,
+  const botUsername =
+    opts.botUsername ?? process.env.TELEGRAM_TEST_BOT_USERNAME ?? "";
+  if (botUsername.length === 0) {
+    fail(
+      "Bot username not provided — pass `botUsername` to spinUp() or set " +
+        "TELEGRAM_TEST_BOT_USERNAME",
     );
   }
+  return { apiId, apiHash, session, botUsername };
+}
+
+export async function spinUp(opts: SpinUpOptions): Promise<Scenario> {
+  const cfg = resolveConfig(opts);
+  void opts.agent; // currently informational; #866 v2 will use it for state-dir scoping
 
-  // TODO(#866): allocate gateway port + ephemeral STATE_DIR.
-  //   const port = await allocatePort();
-  //   const stateDir = await mkdtemp(join(tmpdir(), `uat-${opts.agent}-`));
-  //   process.env.STATE_DIR is per-process — we instead pass STATE_DIR
-  //   in the spawned child's env, never mutate ours.
-  const port = await allocatePort();
-  void port; // Phase 2: feed into agent child env
-
-  // TODO(#866): create the forum topic via Bot API
-  // (`createForumTopic`) using the test bot token; capture the
-  // returned `message_thread_id` and stash for tearDown's
-  // `deleteForumTopic`.
-  const threadId = -1; // sentinel; Phase 2 fills in
-
-  // TODO(#866): spawn the agent under test as a child process.
-  //   const child = spawn(process.execPath, [agentEntry], {
-  //     env: {
-  //       ...process.env,
-  //       STATE_DIR: stateDir,
-  //       TELEGRAM_GATEWAY_PORT: String(port),
-  //       SWITCHROOM_AGENT_NAME: opts.agent,
-  //       BOT_TOKEN: <vault: telegram-test-bot-token>,
-  //     },
-  //     stdio: ["ignore", "pipe", "pipe"],
-  //   });
-  //   await waitForGatewayReady(port, { timeout: 30_000 });
-
-  // TODO(#866): connect mtcute driver.
-  //   const driver = new Driver({ apiId, apiHash, session });
-  //   await driver.connect();
   const driver = new Driver({
-    apiId: 0,
-    apiHash: "",
-    session: "<resolved-from-vault>",
+    apiId: cfg.apiId,
+    apiHash: cfg.apiHash,
+    session: cfg.session,
   });
 
+  await driver.connect();
+
+  // Resolve both IDs eagerly so scenarios can rely on them being
+  // populated by the time `spinUp` returns. Run in parallel — the
+  // two calls don't interact.
+  const [botUserId, driverUserId] = await Promise.all([
+    driver.resolveBotUserId(cfg.botUsername),
+    driver.getMyUserId(),
+  ]);
+
+  // Unpin FIRST, then settle. Order matters: the gateway is a logical
+  // singleton for the chat's pinned card — on every turn it tries to
+  // edit the existing pin rather than pin a fresh one, so observePins
+  // (a transition listener) sees nothing on the next turn. Unpinning
+  // forces the agent to issue a fresh `pin` event we can observe.
+  // The settle delay then absorbs (a) the unpin's own propagation
+  // round-trip and (b) any tail-end edits from the prior scenario's
+  // turn still in flight. Doing unpin before settle keeps the gap a
+  // single window of dead time rather than two stacked waits.
+  await driver.unpinAllMessages(botUserId);
+  const settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
+  if (settleMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, settleMs));
+  }
+
   const scenario: Scenario = {
     driver,
-    chatId,
-    threadId,
+    botUserId,
+    driverUserId,
+    sendDM: (text) => driver.sendText(botUserId, text),
     expectMessage: (match, pollOpts) =>
-      expectMessage(driver, chatId, match, {
+      expectMessage(driver, botUserId, match, {
         ...pollOpts,
-        threadId,
+        senderFilter:
+          pollOpts.from === "bot"
+            ? { notUserId: driverUserId }
+            : pollOpts.from === "driver"
+              ? { userId: driverUserId }
+              : undefined,
       }),
     expectReaction: (messageId, sequence, pollOpts) =>
-      expectReaction(driver, chatId, messageId, sequence, pollOpts),
-    expectPinnedCard: (pollOpts) =>
-      expectPinnedCard(driver, chatId, { ...pollOpts, threadId }),
+      expectReaction(driver, botUserId, messageId, sequence, pollOpts),
+    expectPinnedCard: (pollOpts) => expectPinnedCard(driver, botUserId, pollOpts),
     waitForCardPhase: (card, phase, pollOpts) =>
       waitForCardPhase(driver, card, phase, pollOpts),
     tearDown: async () => {
-      // TODO(#866): SIGTERM child, await exit (or SIGKILL after 5s),
-      // delete forum topic, rm -rf state dir, disconnect driver.
       await driver.disconnect().catch(() => {
-        /* idempotent */
+        /* idempotent — log-and-move-on; the persistent agent is unaffected */
       });
     },
   };
 
-  // Phase 1 marker so accidental runs fail loudly instead of silently
-  // sending nothing.
-  void opts;
-  throw new Error(
-    "[uat/harness] spinUp is scaffolded but not wired (Phase 1 stub) — see TODO markers in uat/harness.ts",
-  );
-
-  // unreachable in Phase 1; left for shape:
-  // eslint-disable-next-line no-unreachable
   return scenario;
 }
+
+function fail(msg: string): never {
+  throw new Error(`[uat/harness] ${msg}`);
+}

package/telegram-plugin/uat/load-env.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadUatEnv } from "./load-env.js";
+
+describe("loadUatEnv", () => {
+  let tmpDir: string;
+  let envFile: string;
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "uat-load-env-"));
+    envFile = join(tmpDir, ".env");
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    for (const key of Object.keys(process.env)) {
+      if (!(key in originalEnv)) delete process.env[key];
+    }
+    for (const [key, value] of Object.entries(originalEnv)) {
+      process.env[key] = value;
+    }
+  });
+
+  it("populates env vars from KEY=value lines", () => {
+    writeFileSync(envFile, "UAT_TEST_FOO=bar\nUAT_TEST_BAZ=qux\n");
+    loadUatEnv(envFile);
+    expect(process.env.UAT_TEST_FOO).toBe("bar");
+    expect(process.env.UAT_TEST_BAZ).toBe("qux");
+  });
+
+  it("does not overwrite values already set in process.env", () => {
+    process.env.UAT_TEST_FOO = "from-shell";
+    writeFileSync(envFile, "UAT_TEST_FOO=from-file\n");
+    loadUatEnv(envFile);
+    expect(process.env.UAT_TEST_FOO).toBe("from-shell");
+  });
+
+  it("strips surrounding single or double quotes", () => {
+    writeFileSync(envFile, `UAT_TEST_DQ="quoted"\nUAT_TEST_SQ='quoted'\n`);
+    loadUatEnv(envFile);
+    expect(process.env.UAT_TEST_DQ).toBe("quoted");
+    expect(process.env.UAT_TEST_SQ).toBe("quoted");
+  });
+
+  it("ignores blank lines and # comments", () => {
+    writeFileSync(envFile, "# top comment\n\nUAT_TEST_FOO=bar\n# trailing\n");
+    loadUatEnv(envFile);
+    expect(process.env.UAT_TEST_FOO).toBe("bar");
+  });
+
+  it("is a no-op when the file does not exist", () => {
+    const before = process.env.UAT_TEST_NONEXISTENT;
+    loadUatEnv(join(tmpDir, "missing.env"));
+    expect(process.env.UAT_TEST_NONEXISTENT).toBe(before);
+  });
+
+  it("handles values containing = signs (session strings)", () => {
+    writeFileSync(envFile, "UAT_TEST_SESSION=abc=def=ghi\n");
+    loadUatEnv(envFile);
+    expect(process.env.UAT_TEST_SESSION).toBe("abc=def=ghi");
+  });
+
+  it("skips empty values so unpopulated .env.example copies stay unset", () => {
+    writeFileSync(envFile, "UAT_TEST_EMPTY=\nUAT_TEST_QUOTED_EMPTY=\"\"\n");
+    loadUatEnv(envFile);
+    expect(process.env.UAT_TEST_EMPTY).toBeUndefined();
+    expect(process.env.UAT_TEST_QUOTED_EMPTY).toBeUndefined();
+  });
+});

package/telegram-plugin/uat/load-env.ts

@@ -0,0 +1,48 @@
+/**
+ * Load the repo-root `.env` into process.env at harness startup.
+ *
+ * The UAT harness needs four env vars (TELEGRAM_API_ID, TELEGRAM_API_HASH,
+ * TELEGRAM_UAT_DRIVER_SESSION, TELEGRAM_TEST_BOT_USERNAME) that originate
+ * in the operator's vault. Re-exporting them every shell session is fiddly,
+ * so we let the operator stash them in a gitignored repo-root `.env`.
+ * Consolidated at the repo root (previously lived at
+ * `telegram-plugin/uat/.env`) so a single file handles UAT secrets +
+ * any future repo-wide dev env knobs. See `SETUP.md` §6 for the
+ * refresh workflow.
+ *
+ * Existing process.env values win — a CI run that supplies vars via the
+ * job environment doesn't get clobbered by a stale local `.env`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+// HERE is `<repo>/telegram-plugin/uat` (or the dist-mirror); two
+// dirname() hops up gets us the repo root regardless of where the
+// bundled output lives.
+export const UAT_ENV_FILE = path.resolve(HERE, "..", "..", ".env");
+
+export function loadUatEnv(envPath: string = UAT_ENV_FILE): void {
+  if (!existsSync(envPath)) return;
+  const content = readFileSync(envPath, "utf-8");
+  for (const rawLine of content.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (value === "") continue;
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}

package/telegram-plugin/uat/login.ts

@@ -3,9 +3,9 @@
  *
  * Issue: https://github.com/switchroom/switchroom/issues/865
  *
- * Run via `bun run uat:login` from telegram-plugin/. Prompts for
- * phone, login code, and (optionally) 2FA password on stdin. Captures
- * the session string in memory and writes it to vault under
+ * Run via `bun run uat:login` from `telegram-plugin/`. Prompts for
+ * phone, login code, and 2FA password on stdin. Captures the session
+ * string in memory and writes it to vault under
  * `telegram-uat-driver-session`. The session string is **never
  * printed** — not to stdout, not to stderr, not to logs. If you see
  * one in scrollback, file an incident.
@@ -13,14 +13,29 @@
  * Required env:
  *   TELEGRAM_API_ID    — from https://my.telegram.org/apps
  *   TELEGRAM_API_HASH  — from https://my.telegram.org/apps
+ *
+ * Vault write: the script writes the session into a 0600 tmpfile and
+ * spawns `switchroom vault set --file <tmpf> --allow test-harness`
+ * with inherited stdio. The operator is prompted once for the vault
+ * passphrase (the broker-mediated stdin path doesn't support `--allow`
+ * scope flags; see `src/cli/vault.ts:331-356` for the rationale). The
+ * tmpfile is `shred -u`'d after the spawn returns.
  */
 
 import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { TelegramClient } from "@mtcute/node";
+import { fileURLToPath } from "node:url";
+import { MemoryStorage, TelegramClient } from "@mtcute/node";
+import { loadUatEnv } from "./load-env.js";
+
+loadUatEnv();
 
-const VAULT_KEY = "telegram-uat-driver-session";
+export const VAULT_KEY = "telegram-uat-driver-session";
+export const VAULT_SCOPE = "test-harness";
 
 async function main(): Promise<void> {
   const apiId = Number.parseInt(process.env.TELEGRAM_API_ID ?? "", 10);
@@ -33,8 +48,6 @@ async function main(): Promise<void> {
 
   const rl = createInterface({ input, output, terminal: true });
 
-  // Confirm the operator understands the security posture before we
-  // mint a bearer-equivalent credential.
   const ack = await rl.question(
     [
       "",
@@ -52,12 +65,15 @@ async function main(): Promise<void> {
   const phone = (await rl.question("Phone number (E.164, e.g. +14155551234): ")).trim();
   if (!phone.startsWith("+")) fail("Phone must start with '+'.");
 
-  const client = new TelegramClient({ apiId, apiHash });
+  // MemoryStorage so nothing lands on disk in this process. The
+  // exported session string is the only durable output; everything
+  // else is ephemeral.
+  const client = new TelegramClient({
+    apiId,
+    apiHash,
+    storage: new MemoryStorage(),
+  });
 
-  // mtcute exposes a `start()` flow that takes async callbacks for
-  // each interactive step. Exact callback names may shift across
-  // versions — verify against the pinned mtcute version before first
-  // run.
   await client.start({
     phone: async () => phone,
     code: async () =>
@@ -66,54 +82,73 @@ async function main(): Promise<void> {
       (await rl.question("2FA password (leave blank if none): ")),
   });
 
-  // TODO(#865): mtcute v0.27 exports sessions via the
-  // `@mtcute/core/utils.js` `StringSessionStorage` adapter; the
-  // exact call is `await client.exportSession()` only when that
-  // storage is configured, otherwise sessions live in the SQLite
-  // file at `client.session`. Phase 2 wires the string-session
-  // storage so this script can mint a string. For now we throw
-  // before producing a value so the operator never gets a half-
-  // baked session in vault.
-  const session: string = await Promise.reject(
-    new Error(
-      "uat:login: Phase 1 stub — Phase 2 wires StringSessionStorage. See uat/SETUP.md §3.",
-    ),
-  );
-
+  const session = await client.exportSession();
   await client.destroy();
   rl.close();
 
-  // Write to vault via the switchroom CLI's stdin path so the
-  // session never appears in argv (which would land in `ps` output).
   await writeToVault(VAULT_KEY, session);
 
-  // Belt-and-suspenders: zero out the local copy.
-  scrub(session);
-
   process.stdout.write(
-    `\nDone. Session stored in vault as \`${VAULT_KEY}\`.\n` +
+    `\nDone. Session stored in vault as \`${VAULT_KEY}\` (scope: allow=${VAULT_SCOPE}).\n` +
       "If you ever see the actual session string in your terminal, file an incident.\n",
   );
 }
 
-function writeToVault(key: string, value: string): Promise<void> {
+/**
+ * Spawns `switchroom vault set --file <tmpf> --allow test-harness` so
+ * the operator passphrase prompt works (broker-mediated stdin writes
+ * reject `--allow`/`--deny`). The tmpfile is created 0700-mode dir,
+ * 0600 file, and `shred -u`'d after the set returns regardless of
+ * outcome.
+ *
+ * Exported so `tests/uat-login.test.ts` can pin the security-critical
+ * invariants (mode 0600, `--allow test-harness`, cleanup on failure)
+ * against the real implementation.
+ */
+export async function writeToVault(key: string, value: string): Promise<void> {
+  const dir = await mkdtemp(join(tmpdir(), "uat-session-"));
+  const path = join(dir, "session");
+  try {
+    await writeFile(path, value, { mode: 0o600 });
+    await runInherit("switchroom", [
+      "vault",
+      "set",
+      key,
+      "--file",
+      path,
+      "--format",
+      "string",
+      "--allow",
+      VAULT_SCOPE,
+    ]);
+  } finally {
+    // Best-effort secure delete. `shred -u` first (overwrites then
+    // unlinks); fall back to plain rm if shred is missing.
+    await runQuiet("shred", ["-u", path]).catch(() => undefined);
+    await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+function runInherit(cmd: string, args: string[]): Promise<void> {
   return new Promise((resolve, reject) => {
-    const proc = spawn("switchroom", ["vault", "set", key], {
-      stdio: ["pipe", "inherit", "inherit"],
-    });
+    const proc = spawn(cmd, args, { stdio: "inherit" });
     proc.on("error", reject);
     proc.on("exit", (code) => {
       if (code === 0) resolve();
-      else reject(new Error(`switchroom vault set exited ${code}`));
+      else reject(new Error(`${cmd} ${args[0] ?? ""} exited ${code}`));
     });
-    proc.stdin.end(value + "\n");
   });
 }
 
-function scrub(_s: string): void {
-  // JS strings are immutable — best we can do is drop the reference
-  // and trust the GC. Documented here so a future hardening pass
-  // (e.g. SecureBuffer) has a hook.
+function runQuiet(cmd: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: "ignore" });
+    proc.on("error", reject);
+    proc.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} exited ${code}`));
+    });
+  });
 }
 
 function fail(msg: string): never {
@@ -121,14 +156,22 @@ function fail(msg: string): never {
   process.exit(1);
 }
 
-main().catch((err) => {
-  // Defensive: if mtcute throws, the error MAY contain the session
-  // string in some adapters. Strip anything that looks like a base64
-  // blob > 64 chars before printing.
-  const sanitized = String(err?.message ?? err).replace(
-    /[A-Za-z0-9+/=_-]{64,}/g,
-    "<redacted>",
-  );
-  process.stderr.write(`uat:login failed: ${sanitized}\n`);
-  process.exit(1);
-});
+// Only run the interactive flow when invoked directly (`bun run
+// uat:login`). Tests that `import` this module for `writeToVault`
+// otherwise trigger the prompt-for-phone-number flow on every load.
+const invokedDirectly =
+  process.argv[1] !== undefined &&
+  fileURLToPath(import.meta.url) === process.argv[1];
+if (invokedDirectly) {
+  main().catch((err) => {
+    // Defensive: if mtcute throws, the error MAY contain the session
+    // string in some adapters. Strip anything that looks like a long
+    // base64 blob before printing.
+    const sanitized = String(err?.message ?? err).replace(
+      /[A-Za-z0-9+/=_-]{64,}/g,
+      "<redacted>",
+    );
+    process.stderr.write(`uat:login failed: ${sanitized}\n`);
+    process.exit(1);
+  });
+}