@vellumai/cli 0.7.0 → 0.7.2

package/src/lib/terminal-session.ts

@@ -6,11 +6,7 @@
  * resolver without cross-importing commands (per cli/CONTRIBUTING.md).
  */
 
-import {
-  findAssistantByName,
-  loadLatestAssistant,
-  resolveCloud,
-} from "./assistant-config.js";
+import { resolveAssistant, resolveCloud } from "./assistant-config.js";
 import { getPlatformUrl, readPlatformToken } from "./platform-client.js";
 import {
   closeTerminalSession,
@@ -42,7 +38,7 @@ export interface ResolvedManagedAssistant {
 export function resolveManagedAssistant(
   nameArg?: string,
 ): ResolvedManagedAssistant {
-  const entry = nameArg ? findAssistantByName(nameArg) : loadLatestAssistant();
+  const entry = resolveAssistant(nameArg);
 
   if (!entry) {
     if (nameArg) {
@@ -97,6 +93,7 @@ export function resolveManagedAssistant(
 export async function interactiveSession(
   assistant: ResolvedManagedAssistant,
   initialCommand?: string,
+  service?: string,
 ): Promise<void> {
   const cols = process.stdout.columns || 80;
   const rows = process.stdout.rows || 24;
@@ -109,6 +106,7 @@ export async function interactiveSession(
     cols,
     rows,
     assistant.platformUrl,
+    service,
   );
 
   // --- TTY raw mode setup ---
@@ -272,21 +270,24 @@ export function shellEscapeArgs(args: string[]): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Run a command non-interactively in a managed assistant container. Creates
+ * Run a command non-interactively in a managed assistant service. Creates
  * an ephemeral terminal session, sends the command wrapped in sentinels for
  * reliable output extraction, captures the result, and exits with the
  * remote command's exit code.
  */
 export interface NonInteractiveExecOptions {
   verbose?: boolean;
+  /** Timeout in milliseconds. 0 disables the timeout entirely. Default: 30_000. */
+  timeoutMs?: number;
 }
 
 export async function nonInteractiveExec(
   assistant: ResolvedManagedAssistant,
   command: string[],
-  options?: NonInteractiveExecOptions,
+  options?: NonInteractiveExecOptions & { service?: string },
 ): Promise<void> {
   const verbose = options?.verbose ?? false;
+  const timeoutMs = options?.timeoutMs ?? 30_000;
   const dbg = verbose
     ? (msg: string) => console.error(`\x1b[2m[exec] ${msg}\x1b[0m`)
     : (_msg: string) => {};
@@ -299,6 +300,7 @@ export async function nonInteractiveExec(
     120,
     24,
     assistant.platformUrl,
+    options?.service,
   );
 
   dbg(`session created: ${sessionId}`);
@@ -307,6 +309,7 @@ export async function nonInteractiveExec(
   const output: Buffer[] = [];
   let commandSent = false;
   let eventCount = 0;
+  let timedOut = false;
 
   // Unique sentinels to delimit command output
   const startSentinel = `__VELLUM_EXEC_START_${Date.now()}__`;
@@ -315,10 +318,14 @@ export async function nonInteractiveExec(
 
   dbg(`sentinels: start=${startSentinel} end=${endSentinel}`);
 
-  const timeout = setTimeout(() => {
-    dbg(`30s timeout reached — aborting`);
-    abortController.abort();
-  }, 30_000);
+  const timeout =
+    timeoutMs > 0
+      ? setTimeout(() => {
+          dbg(`${timeoutMs / 1000}s timeout reached — aborting`);
+          timedOut = true;
+          abortController.abort();
+        }, timeoutMs)
+      : null;
 
   try {
     for await (const event of subscribeTerminalEvents(
@@ -334,7 +341,9 @@ export async function nonInteractiveExec(
 
       if (verbose) {
         const text = bytes.toString("utf-8");
-        dbg(`SSE event #${eventCount} (seq=${event.seq}, ${bytes.length}B): ${JSON.stringify(text)}`);
+        dbg(
+          `SSE event #${eventCount} (seq=${event.seq}, ${bytes.length}B): ${JSON.stringify(text)}`,
+        );
       }
 
       // Wait for shell prompt before sending command
@@ -364,11 +373,21 @@ export async function nonInteractiveExec(
         }
       }
 
-      // Check for end sentinel in accumulated output
+      // Check for completion: require the end sentinel before looking for the
+      // exit code sentinel. The exit code string also appears in the command
+      // echo (the shell printing what was typed), so matching it alone would
+      // trigger a premature abort before the command even starts running.
       if (commandSent) {
         const accumulated = Buffer.concat(output).toString("utf-8");
-        if (accumulated.includes(exitCodeSentinel)) {
-          dbg(`exit code sentinel detected — waiting 500ms for final output`);
+        // Normalize CR so CRLF line endings from the PTY don't prevent matching
+        const normalized = accumulated.replace(/\r/g, "");
+        if (
+          normalized.includes(endSentinel + "\n") &&
+          normalized.includes(exitCodeSentinel)
+        ) {
+          dbg(
+            `end + exit code sentinels detected — waiting 500ms for final output`,
+          );
           // Give a moment for final output to arrive
           setTimeout(() => abortController.abort(), 500);
         }
@@ -377,7 +396,7 @@ export async function nonInteractiveExec(
   } catch {
     // Expected: abort on timeout or sentinel detection
   } finally {
-    clearTimeout(timeout);
+    if (timeout) clearTimeout(timeout);
     dbg(`stream ended after ${eventCount} events — closing session`);
     await closeTerminalSession(
       assistant.token,
@@ -387,7 +406,6 @@ export async function nonInteractiveExec(
     ).catch(() => {});
   }
 
-  // Parse output between sentinels
   const raw = Buffer.concat(output).toString("utf-8");
 
   if (verbose) {
@@ -396,12 +414,7 @@ export async function nonInteractiveExec(
     dbg(`--- end raw output ---`);
   }
 
-  // Strip ANSI escapes
-  const clean = raw.replace(
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: needed for ANSI stripping
-    /\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07|\x1b[()][^\n]|\r/g,
-    "",
-  );
+  const clean = stripAnsi(raw);
 
   if (verbose) {
     dbg(`--- cleaned output (${clean.length} chars) ---`);
@@ -409,40 +422,108 @@ export async function nonInteractiveExec(
     dbg(`--- end cleaned output ---`);
   }
 
-  const lines = clean.split("\n");
+  const { output: result, exitCode } = parseSentinelOutput(
+    clean,
+    startSentinel,
+    endSentinel,
+  );
+
+  dbg(`extracted result: ${result.length} chars, exit code: ${exitCode}`);
+
+  if (timedOut && !result) {
+    const secs = timeoutMs / 1000;
+    console.error(
+      `\x1b[31mError: command timed out after ${secs}s with no output.\x1b[0m`,
+    );
+    console.error(
+      `\x1b[2mTip: use --timeout <seconds> to increase the limit, or --timeout 0 to disable.\x1b[0m`,
+    );
+    process.exit(124);
+  }
+
+  if (timedOut && result) {
+    const secs = timeoutMs / 1000;
+    process.stdout.write(result + "\n");
+    console.error(
+      `\x1b[33mWarning: command timed out after ${secs}s (partial output above).\x1b[0m`,
+    );
+    process.exit(124);
+  }
+
+  if (result) {
+    process.stdout.write(result + "\n");
+  } else {
+    dbg(`no output extracted between sentinels`);
+  }
+
+  process.exit(exitCode);
+}
+
+// ---------------------------------------------------------------------------
+// Exported helpers — pure functions extracted for testability
+// ---------------------------------------------------------------------------
+
+const EXIT_CODE_SENTINEL = "__VELLUM_EXIT_";
+
+/**
+ * Strip ANSI escape sequences and carriage returns from raw PTY output.
+ */
+export function stripAnsi(raw: string): string {
+  return raw.replace(
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: needed for ANSI stripping
+    /\x1b\[[?]?[0-9;]*[a-zA-Z-~]|\x1b\][^\x07]*\x07|\x1b[()][^\n]|\r/g,
+    "",
+  );
+}
+
+export interface ParsedSentinelOutput {
+  output: string;
+  exitCode: number;
+}
 
-  // Find output between sentinels. Search backwards because each sentinel
-  // string appears twice: once in the shell command echo and once in the
-  // actual output. We want the last occurrence (the output line).
+/**
+ * Extract command output and exit code from cleaned (ANSI-stripped) terminal
+ * output using sentinel markers.
+ *
+ * Each sentinel appears twice: once in the command echo (the shell printing
+ * what was typed) and once in the actual output. We find the last start
+ * sentinel then search forward for the first end sentinel after it.
+ */
+export function parseSentinelOutput(
+  cleaned: string,
+  startSentinel: string,
+  endSentinel: string,
+): ParsedSentinelOutput {
+  const lines = cleaned.split("\n");
+
+  // Find the last start sentinel (the real output one, not the echo)
   let startIdx = -1;
-  let endIdx = -1;
   for (let i = lines.length - 1; i >= 0; i--) {
-    if (endIdx < 0 && lines[i].includes(endSentinel)) {
-      endIdx = i;
-    }
-    if (startIdx < 0 && lines[i].includes(startSentinel)) {
+    if (lines[i].includes(startSentinel)) {
       startIdx = i;
+      break;
     }
   }
 
-  dbg(`sentinel indices: startLine=${startIdx} endLine=${endIdx} (of ${lines.length} lines)`);
+  // Find the first end sentinel after the start sentinel
+  let endIdx = -1;
+  if (startIdx >= 0) {
+    for (let i = startIdx + 1; i < lines.length; i++) {
+      if (lines[i].includes(endSentinel)) {
+        endIdx = i;
+        break;
+      }
+    }
+  }
 
   const start = startIdx >= 0 ? startIdx + 1 : 0;
   const end = endIdx >= 0 ? endIdx : lines.length;
-  const result = lines.slice(start, end).join("\n").trim();
+  const output = lines.slice(start, end).join("\n").trim();
 
-  dbg(`extracted result: ${result.length} chars`);
-
-  if (result) {
-    process.stdout.write(result + "\n");
-  } else {
-    dbg(`no output extracted between sentinels`);
-  }
-
-  // Extract exit code from sentinel (also search backwards)
+  // Extract exit code — search backwards from the end
   let exitCode = 0;
   for (let i = lines.length - 1; i >= 0; i--) {
-    if (lines[i].includes(exitCodeSentinel)) {
+    if (lines[i].includes(EXIT_CODE_SENTINEL)) {
       const match = lines[i].match(/__VELLUM_EXIT_(\d+)/);
       if (match) {
         exitCode = parseInt(match[1], 10);
@@ -451,7 +532,5 @@ export async function nonInteractiveExec(
     }
   }
 
-  dbg(`exit code: ${exitCode}`);
-
-  process.exit(exitCode);
+  return { output, exitCode };
 }

package/src/lib/tui-log.ts

@@ -0,0 +1,60 @@
+/**
+ * Structured logger for the `vellum client` TUI.
+ *
+ * Writes timestamped log lines to `<xdg-log-dir>/client-cli.log`
+ * (same directory used by `vellum logs` for hatch sessions).  The file is
+ * reset on each TUI session start so it always reflects the most recent run.
+ *
+ * Usage:
+ *   import { tuiLog } from "../lib/tui-log";
+ *
+ *   tuiLog.init();                     // reset + open — call once at startup
+ *   tuiLog.info("connected", { url }); // structured write
+ *   tuiLog.close();                    // flush + close fd
+ *
+ * The log is always written — it's cheap (single file append) and invaluable
+ * for diagnosing SSE registration, client identity, and proxy issues.
+ */
+
+import {
+  closeLogFile,
+  openLogFile,
+  resetLogFile,
+  writeToLogFile,
+} from "./xdg-log.js";
+
+const LOG_FILE = "client-cli.log";
+
+let fd: number | "ignore" = "ignore";
+
+function write(level: string, msg: string, extra?: Record<string, unknown>) {
+  const ts = new Date().toISOString();
+  const suffix = extra ? ` ${JSON.stringify(extra)}` : "";
+  writeToLogFile(fd, `${ts} [client] ${level.toUpperCase()} ${msg}${suffix}\n`);
+}
+
+export const tuiLog = {
+  /** Reset and open the log file. Call once at TUI startup. */
+  init() {
+    resetLogFile(LOG_FILE);
+    fd = openLogFile(LOG_FILE);
+  },
+
+  info(msg: string, extra?: Record<string, unknown>) {
+    write("INFO", msg, extra);
+  },
+
+  warn(msg: string, extra?: Record<string, unknown>) {
+    write("WARN", msg, extra);
+  },
+
+  error(msg: string, extra?: Record<string, unknown>) {
+    write("ERROR", msg, extra);
+  },
+
+  /** Close the file descriptor. Safe to call multiple times. */
+  close() {
+    closeLogFile(fd);
+    fd = "ignore";
+  },
+};

package/src/lib/upgrade-lifecycle.ts

@@ -1,4 +1,8 @@
 import { randomBytes } from "crypto";
+import { spawnSync } from "child_process";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 
 import type { AssistantEntry } from "./assistant-config.js";
 import { saveAssistantEntry } from "./assistant-config.js";
@@ -18,6 +22,62 @@ import { resolveImageRefs } from "./platform-releases.js";
 import { exec, execOutput } from "./step-runner.js";
 import { compareVersions } from "./version-compat.js";
 
+// ---------------------------------------------------------------------------
+// Failure log capture
+// ---------------------------------------------------------------------------
+
+/** XDG-compliant directory for upgrade failure logs */
+function getUpgradeLogsDir(): string {
+  const stateHome =
+    process.env.XDG_STATE_HOME?.trim() || join(homedir(), ".local", "state");
+  return join(stateHome, "vellum", "upgrade-logs");
+}
+
+/**
+ * Capture stdout/stderr from all three containers after a readiness failure
+ * and write them to an XDG state directory. Returns the directory path so
+ * the caller can print it for the user.
+ *
+ * Runs best-effort — never throws.
+ */
+export async function captureUpgradeFailureLogs(
+  res: ReturnType<typeof dockerResourceNames>,
+  label: string,
+): Promise<string | null> {
+  const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const logDir = join(getUpgradeLogsDir(), `${label}-${isoTimestamp}`);
+  try {
+    mkdirSync(logDir, { recursive: true });
+
+    const containers: [string, string][] = [
+      [res.assistantContainer, "assistant.log"],
+      [res.gatewayContainer, "gateway.log"],
+      [res.cesContainer, "credential-executor.log"],
+    ];
+
+    for (const [container, filename] of containers) {
+      try {
+        // Capture stdout + stderr together so container logs written to either
+        // stream (docker logs writes container stdout→stdout, stderr→stderr)
+        // are preserved in a single file. spawnSync avoids the execOutput
+        // limitation of returning only stdout on success.
+        const result = spawnSync("docker", ["logs", "--tail", "500", container], {
+          encoding: "utf8",
+          maxBuffer: 10 * 1024 * 1024, // 10 MB
+        });
+        const output = [result.stdout, result.stderr].filter(Boolean).join("");
+        if (output) writeFileSync(join(logDir, filename), output);
+      } catch {
+        // Container may not exist or may have already been removed
+      }
+    }
+
+    return existsSync(logDir) ? logDir : null;
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Shared constants & builders for upgrade / rollback lifecycle events
 // ---------------------------------------------------------------------------
@@ -734,6 +794,11 @@ export async function performDockerRollback(
     // Failure path — attempt auto-rollback to original version
     console.error(`\n❌ Containers failed to become ready within the timeout.`);
 
+    const logDir = await captureUpgradeFailureLogs(res, `${instanceName}-rollback-failure`);
+    if (logDir) {
+      console.log(`📋 Container logs saved to: ${logDir}`);
+    }
+
     if (currentImageRefs) {
       await broadcastUpgradeEvent(
         entry.runtimeUrl,

package/src/lib/xdg-log.ts

@@ -9,16 +9,22 @@ import {
   writeFileSync,
   writeSync,
 } from "fs";
-import { homedir } from "os";
 import { join } from "path";
 
+import { getConfigDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
+
 /** Regex matching pino-pretty's short time prefix, e.g. `[12:07:37.467] `. */
 const PINO_TIME_RE = /^\[\d{2}:\d{2}:\d{2}\.\d{3}\]\s*/;
 
-/** Returns the XDG-compatible log directory for Vellum CLI logs. */
+/**
+ * Returns the XDG-compatible log directory for Vellum CLI logs.
+ *
+ * Environment-aware: production uses `$XDG_CONFIG_HOME/vellum/logs`,
+ * non-production environments use `$XDG_CONFIG_HOME/vellum-<env>/logs`.
+ */
 export function getLogDir(): string {
-  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-  return join(configHome, "vellum", "logs");
+  return join(getConfigDir(getCurrentEnvironment()), "logs");
 }
 
 /** Open (or create) a log file in append mode, returning the file descriptor.

package/src/commands/pair.ts

@@ -1,212 +0,0 @@
-import { createHash } from "crypto";
-import { readFileSync } from "fs";
-import jsQR from "jsqr";
-import { hostname, userInfo } from "os";
-import { PNG } from "pngjs";
-
-import { saveAssistantEntry } from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
-import type { Species } from "../lib/constants";
-import { saveGuardianToken } from "../lib/guardian-token";
-import type { GuardianTokenData } from "../lib/guardian-token";
-import { generateInstanceName } from "../lib/random-name";
-
-interface QRPairingPayload {
-  type: string;
-  v: number;
-  id?: string;
-  g: string;
-  pairingRequestId: string;
-  pairingSecret: string;
-}
-
-interface PairingResponse {
-  status: "approved" | "pending";
-  bearerToken?: string;
-  gatewayUrl?: string;
-}
-
-function decodeQRCodeFromPng(pngPath: string): string {
-  const fileData = readFileSync(pngPath);
-  const png = PNG.sync.read(fileData);
-  const code = jsQR(new Uint8ClampedArray(png.data), png.width, png.height);
-  if (!code) {
-    throw new Error("Could not decode QR code from the provided PNG image.");
-  }
-  return code.data;
-}
-
-function safeUserInfoUsername(): string {
-  try {
-    return userInfo().username;
-  } catch {
-    return "";
-  }
-}
-
-function getDeviceId(): string {
-  const raw = hostname() + safeUserInfoUsername();
-  return createHash("sha256").update(raw).digest("hex");
-}
-
-const PAIRING_POLL_INTERVAL_MS = 2000;
-const PAIRING_POLL_TIMEOUT_MS = 120_000;
-
-async function pollForApproval(
-  gatewayUrl: string,
-  pairingRequestId: string,
-  pairingSecret: string,
-): Promise<PairingResponse> {
-  const startTime = Date.now();
-
-  while (Date.now() - startTime < PAIRING_POLL_TIMEOUT_MS) {
-    const statusUrl = `${gatewayUrl}/pairing/status?id=${encodeURIComponent(pairingRequestId)}&secret=${encodeURIComponent(pairingSecret)}`;
-    const statusRes = await fetch(statusUrl);
-
-    if (!statusRes.ok) {
-      const body = await statusRes.text().catch(() => "");
-      throw new Error(
-        `Failed to check pairing status: HTTP ${statusRes.status}: ${body || statusRes.statusText}`,
-      );
-    }
-
-    const statusBody = (await statusRes.json()) as PairingResponse;
-
-    if (statusBody.status === "approved") {
-      return statusBody;
-    }
-
-    await new Promise((resolve) =>
-      setTimeout(resolve, PAIRING_POLL_INTERVAL_MS),
-    );
-  }
-
-  throw new Error("Pairing timed out waiting for approval.");
-}
-
-export async function pair(): Promise<void> {
-  const args = process.argv.slice(3);
-
-  if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum pair <path-to-qrcode.png>");
-    console.log("");
-    console.log(
-      "Pair with a remote assistant by scanning the QR code PNG generated during setup.",
-    );
-    process.exit(0);
-  }
-
-  const qrCodePath = args[0] || process.env.VELLUM_CUSTOM_QR_CODE_PATH;
-
-  if (!qrCodePath) {
-    console.error("Usage: vellum pair <path-to-qrcode.png>");
-    console.error("");
-    console.error(
-      "Pair with a remote assistant by scanning the QR code PNG generated during setup.",
-    );
-    process.exit(1);
-  }
-
-  const species: Species = "vellum";
-
-  try {
-    console.log("Reading QR code from provided image...");
-    const qrData = decodeQRCodeFromPng(qrCodePath);
-
-    let payload: QRPairingPayload;
-    try {
-      payload = JSON.parse(qrData) as QRPairingPayload;
-    } catch {
-      throw new Error("QR code does not contain valid pairing data.");
-    }
-
-    if (
-      payload.type !== "vellum-daemon" ||
-      !payload.g ||
-      !payload.pairingRequestId ||
-      !payload.pairingSecret
-    ) {
-      throw new Error("QR code does not contain valid Vellum pairing data.");
-    }
-
-    const instanceName = generateInstanceName(species);
-    const runtimeUrl = payload.g;
-    const deviceId = getDeviceId();
-    const deviceName = hostname();
-
-    console.log(`Pairing with remote assistant at ${runtimeUrl}...`);
-
-    const requestUrl = `${runtimeUrl}/pairing/request`;
-    const requestRes = await fetch(requestUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        pairingRequestId: payload.pairingRequestId,
-        pairingSecret: payload.pairingSecret,
-        deviceId,
-        deviceName,
-      }),
-    });
-
-    if (!requestRes.ok) {
-      const body = await requestRes.text().catch(() => "");
-      throw new Error(
-        `Failed to initiate pairing: HTTP ${requestRes.status}: ${body || requestRes.statusText}`,
-      );
-    }
-
-    const requestBody = (await requestRes.json()) as PairingResponse;
-
-    let bearerToken: string | undefined;
-
-    if (requestBody.status === "approved") {
-      bearerToken = requestBody.bearerToken;
-    } else if (requestBody.status === "pending") {
-      console.log("Waiting for pairing approval...");
-      const approvedResponse = await pollForApproval(
-        runtimeUrl,
-        payload.pairingRequestId,
-        payload.pairingSecret,
-      );
-      bearerToken = approvedResponse.bearerToken;
-    } else {
-      throw new Error(
-        `Unexpected pairing response status: ${requestBody.status}`,
-      );
-    }
-
-    const customEntry: AssistantEntry = {
-      assistantId: instanceName,
-      runtimeUrl,
-      cloud: "custom",
-      species,
-      hatchedAt: new Date().toISOString(),
-    };
-    saveAssistantEntry(customEntry);
-
-    if (bearerToken) {
-      const tokenData: GuardianTokenData = {
-        guardianPrincipalId: "",
-        accessToken: bearerToken,
-        accessTokenExpiresAt: "",
-        refreshToken: "",
-        refreshTokenExpiresAt: "",
-        refreshAfter: "",
-        isNew: true,
-        deviceId: getDeviceId(),
-        leasedAt: new Date().toISOString(),
-      };
-      saveGuardianToken(instanceName, tokenData);
-    }
-
-    console.log("");
-    console.log("Successfully paired with remote assistant!");
-    console.log("Instance details:");
-    console.log(`  Name: ${instanceName}`);
-    console.log(`  Runtime URL: ${runtimeUrl}`);
-    console.log("");
-  } catch (error) {
-    console.error("Error:", error instanceof Error ? error.message : error);
-    process.exit(1);
-  }
-}