@vellumai/cli 0.8.3 → 0.8.5

package/src/components/DefaultMainScreen.tsx

@@ -1,4 +1,3 @@
-import { spawn } from "child_process";
 import { basename } from "path";
 import {
   useCallback,
@@ -10,8 +9,6 @@ import {
 } from "react";
 import { Box, render as inkRender, Text, useInput, useStdout } from "ink";
 
-import { removeAssistantEntry } from "../lib/assistant-config";
-
 import { SPECIES_CONFIG, type Species } from "../lib/constants";
 import { checkHealth } from "../lib/health-check";
 import { appendHistory, loadHistory } from "../lib/input-history";
@@ -43,9 +40,27 @@ export const SLASH_COMMANDS = [
   "/help",
   "/q",
   "/quit",
-  "/retire",
 ];
 
+const HELP_COMMANDS = [
+  {
+    command: "/btw <question>",
+    description: "Ask a side question while the assistant is working",
+  },
+  {
+    command: "/quit, /exit, /q",
+    description: "Disconnect and exit",
+  },
+  {
+    command: "/clear",
+    description: "Clear the screen",
+  },
+  {
+    command: "/help, ?",
+    description: "Show this help",
+  },
+] as const;
+
 const SEND_TIMEOUT_MS = 5000;
 
 // ── Layout constants ──────────────────────────────────────
@@ -100,12 +115,11 @@ const MIN_FEED_ROWS = 3;
 // Feed item height estimation
 const TOOL_CALL_CHROME_LINES = 2; // header (┌) + footer (└)
 const MESSAGE_SPACING = 1;
-const HELP_DISPLAY_HEIGHT = 7;
+const HELP_DISPLAY_HEIGHT = HELP_COMMANDS.length + 1;
 
 interface ListMessagesResponse {
   messages: RuntimeMessage[];
   nextCursor?: string;
-  interfaces?: string[];
 }
 
 interface SendMessageResponse {
@@ -742,26 +756,12 @@ function HelpDisplay(): ReactElement {
   return (
     <Box flexDirection="column">
       <Text bold>Commands:</Text>
-      <Text>
-        {"  /btw <question>   "}
-        <Text dimColor>Ask a side question while the assistant is working</Text>
-      </Text>
-      <Text>
-        {"  /retire           "}
-        <Text dimColor>Retire the remote instance and exit</Text>
-      </Text>
-      <Text>
-        {"  /quit, /exit, /q  "}
-        <Text dimColor>Disconnect and exit</Text>
-      </Text>
-      <Text>
-        {"  /clear            "}
-        <Text dimColor>Clear the screen</Text>
-      </Text>
-      <Text>
-        {"  /help, ?          "}
-        <Text dimColor>Show this help</Text>
-      </Text>
+      {HELP_COMMANDS.map((entry) => (
+        <Text key={entry.command}>
+          {`  ${entry.command.padEnd(17)} `}
+          <Text dimColor>{entry.description}</Text>
+        </Text>
+      ))}
     </Box>
   );
 }
@@ -1391,8 +1391,6 @@ interface ChatAppProps {
   /** Pre-built auth headers (e.g. { Authorization: "Bearer ..." } for local,
    *  { "X-Session-Token": "...", "Vellum-Organization-Id": "..." } for platform). */
   auth?: Record<string, string>;
-  project?: string;
-  zone?: string;
   onExit: () => void;
   handleRef: (handle: ChatAppHandle) => void;
 }
@@ -1403,8 +1401,6 @@ function ChatApp({
   assistantName,
   species,
   auth,
-  project,
-  zone,
   onExit,
   handleRef,
 }: ChatAppProps): ReactElement {
@@ -1954,86 +1950,6 @@ function ChatApp({
         return;
       }
 
-      if (trimmed === "/retire") {
-        if (!project || !zone) {
-          h.showError(
-            "No instance info available. Connect to a hatched instance first.",
-          );
-          return;
-        }
-
-        const confirmIndex = await h.showSelection(`Retire ${assistantId}?`, [
-          "Yes, retire",
-          "Cancel",
-        ]);
-        if (confirmIndex !== 0) {
-          h.addStatus("Cancelled.");
-          return;
-        }
-
-        h.showSpinner(`Retiring instance ${assistantId}...`);
-
-        try {
-          const labelChild = spawn(
-            "gcloud",
-            [
-              "compute",
-              "instances",
-              "add-labels",
-              assistantId,
-              `--project=${project}`,
-              `--zone=${zone}`,
-              "--labels=retired-by=vel",
-            ],
-            { stdio: "pipe" },
-          );
-          await new Promise<void>((resolve) => {
-            labelChild.on("close", () => resolve());
-            labelChild.on("error", () => resolve());
-          });
-        } catch {
-          // Best-effort labeling before deletion
-        }
-
-        const child = spawn(
-          "gcloud",
-          [
-            "compute",
-            "instances",
-            "delete",
-            assistantId,
-            `--project=${project}`,
-            `--zone=${zone}`,
-            "--quiet",
-          ],
-          { stdio: "pipe" },
-        );
-
-        child.on("close", (code) => {
-          handleRef_.current?.hideSpinner();
-          if (code === 0) {
-            removeAssistantEntry(assistantId);
-            handleRef_.current?.addStatus(
-              `Removed ${assistantId} from lockfile.json`,
-            );
-          } else {
-            handleRef_.current?.showError(
-              `Failed to delete instance (exit code ${code})`,
-            );
-          }
-          cleanup();
-          process.exit(code === 0 ? 0 : 1);
-        });
-
-        child.on("error", (err) => {
-          handleRef_.current?.hideSpinner();
-          handleRef_.current?.showError(
-            `Failed to retire instance: ${err.message}`,
-          );
-        });
-        return;
-      }
-
       // If a connection attempt is already in progress, don't silently drop input
       if (connectingRef.current) {
         h.addStatus(
@@ -2218,7 +2134,7 @@ function ChatApp({
       // racing with SSE events that may arrive during the sendMessage await.
       h.showSpinner("Working...");
     },
-    [runtimeUrl, assistantId, auth, project, zone, cleanup, ensureConnected],
+    [runtimeUrl, assistantId, auth, cleanup, ensureConnected],
   );
 
   const handleSubmit = useCallback(
@@ -2530,8 +2446,6 @@ export function renderChatApp(
   onExit: () => void,
   options?: {
     auth?: Record<string, string>;
-    project?: string;
-    zone?: string;
     assistantName?: string;
   },
 ): ChatAppInstance {
@@ -2544,8 +2458,6 @@ export function renderChatApp(
       assistantName={options?.assistantName}
       species={species}
       auth={options?.auth}
-      project={options?.project}
-      zone={options?.zone}
       onExit={onExit}
       handleRef={(h) => {
         chatHandle = h;

package/src/index.ts

@@ -14,6 +14,7 @@ import { message } from "./commands/message";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
 import { restore } from "./commands/restore";
+import { roadmap } from "./commands/roadmap";
 import { retire } from "./commands/retire";
 import { rollback } from "./commands/rollback";
 import { setup } from "./commands/setup";
@@ -45,6 +46,7 @@ const commands = {
   recover,
   restore,
   retire,
+  roadmap,
   rollback,
   setup,
   sleep,
@@ -83,6 +85,7 @@ function printHelp(): void {
     "  restore  Restore data (and optionally version) from a .vbundle backup",
   );
   console.log("  retire   Delete an assistant instance");
+  console.log("  roadmap  Manage roadmap items");
   console.log("  rollback  Roll back an assistant to a previous version");
   console.log("  setup    Configure API keys interactively");
   console.log("  sleep    Stop the assistant process");

package/src/lib/__tests__/port-allocator.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import { createServer, type Server } from "net";
+
+import { findOpenPort } from "../port-allocator.js";
+
+const HOST = "127.0.0.1";
+
+async function bindBlocker(port: number, host: string = HOST): Promise<Server> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.once("listening", () => resolve(server));
+    server.listen(port, host);
+  });
+}
+
+async function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+  });
+}
+
+async function getEphemeralPort(): Promise<number> {
+  const server = await new Promise<Server>((resolve, reject) => {
+    const s = createServer();
+    s.once("error", reject);
+    s.once("listening", () => resolve(s));
+    s.listen(0, HOST);
+  });
+  const addr = server.address();
+  if (!addr || typeof addr === "string" || addr.port == null) {
+    throw new Error("Could not obtain ephemeral port");
+  }
+  const port = addr.port;
+  await closeServer(server);
+  return port;
+}
+
+describe("findOpenPort", () => {
+  test("returns the preferred port when it is free", async () => {
+    const port = await getEphemeralPort();
+    const result = await findOpenPort(port, { host: HOST });
+    expect(result).toBe(port);
+  });
+
+  test("walks past an in-use port and returns the next free one", async () => {
+    const blocked = await getEphemeralPort();
+    const blocker = await bindBlocker(blocked);
+    try {
+      const result = await findOpenPort(blocked, { host: HOST });
+      expect(result).toBeGreaterThan(blocked);
+      expect(result).toBeLessThanOrEqual(blocked + 50);
+    } finally {
+      await closeServer(blocker);
+    }
+  });
+
+  test("walks past two consecutive in-use ports", async () => {
+    const first = await getEphemeralPort();
+    const blockerA = await bindBlocker(first);
+    let blockerB: Server | null = null;
+    try {
+      // Best-effort grab of the next consecutive port; if the kernel
+      // handed it to someone else just before we got here, that's still a
+      // valid "two consecutive blockers" scenario for the walk.
+      try {
+        blockerB = await bindBlocker(first + 1);
+      } catch {
+        blockerB = null;
+      }
+      const result = await findOpenPort(first, { host: HOST });
+      expect(result).toBeGreaterThan(first + (blockerB ? 1 : 0));
+    } finally {
+      await closeServer(blockerA);
+      if (blockerB) await closeServer(blockerB);
+    }
+  });
+
+  test("throws when the entire requested window is in use", async () => {
+    const blocked = await getEphemeralPort();
+    const blocker = await bindBlocker(blocked);
+    try {
+      await expect(
+        findOpenPort(blocked, { host: HOST, maxAttempts: 1 }),
+      ).rejects.toThrow(/no open port/i);
+    } finally {
+      await closeServer(blocker);
+    }
+  });
+
+  test("rejects non-integer or out-of-range preferred port", async () => {
+    await expect(findOpenPort(0, { host: HOST })).rejects.toThrow(
+      /not a valid TCP port/i,
+    );
+    await expect(findOpenPort(65536, { host: HOST })).rejects.toThrow(
+      /not a valid TCP port/i,
+    );
+    await expect(findOpenPort(1.5, { host: HOST })).rejects.toThrow(
+      /not a valid TCP port/i,
+    );
+  });
+
+  test("rejects non-positive maxAttempts", async () => {
+    await expect(
+      findOpenPort(20100, { host: HOST, maxAttempts: 0 }),
+    ).rejects.toThrow(/maxAttempts/i);
+  });
+
+  test("does not leak the probe port — port is rebindable after resolution", async () => {
+    const port = await getEphemeralPort();
+    const found = await findOpenPort(port, { host: HOST });
+    expect(found).toBe(port);
+    // If the probe leaked a listener on `port`, this would throw EADDRINUSE.
+    const reuse = await bindBlocker(found);
+    await closeServer(reuse);
+  });
+});

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

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "bun:test";
+
+import { buildExecErrorMessage, exec, execOutput } from "../step-runner";
+
+describe("buildExecErrorMessage", () => {
+  it("omits the argv from the header so secrets in args can't leak", () => {
+    // Realistic shape — docker hatch invocations pass `-e <NAME>=<val>`
+    // flags inline. If we ever regress and put argv in the header, this
+    // assertion catches it immediately.
+    const msg = buildExecErrorMessage("docker", 125, "stderr text", "");
+    expect(msg).not.toContain("ANTHROPIC_API_KEY");
+    expect(msg).not.toContain("OPENAI_API_KEY");
+    expect(msg.startsWith("docker exited with code 125")).toBe(true);
+  });
+
+  it("appends stderr below the header when present", () => {
+    const msg = buildExecErrorMessage("docker", 125, "  bind failed\n", "");
+    expect(msg).toBe("docker exited with code 125\nbind failed");
+  });
+
+  it("appends stdout when stderr is empty", () => {
+    const msg = buildExecErrorMessage("docker", 1, "", "stdout-only\n");
+    expect(msg).toBe("docker exited with code 1\nstdout-only");
+  });
+
+  it("appends both streams joined by newline when both present", () => {
+    const msg = buildExecErrorMessage("docker", 1, "stderr-line", "stdout-line");
+    expect(msg).toBe("docker exited with code 1\nstderr-line\nstdout-line");
+  });
+
+  it("collapses an empty output to just the header", () => {
+    const msg = buildExecErrorMessage("docker", 1, "  ", "\n");
+    expect(msg).toBe("docker exited with code 1");
+  });
+
+  it("handles a null exit code (signal-terminated child)", () => {
+    const msg = buildExecErrorMessage("docker", null, "killed", "");
+    expect(msg).toBe("docker exited with an unknown code\nkilled");
+  });
+});
+
+describe("exec — secret leak regression", () => {
+  it("rejects with an Error whose message contains neither the args nor any -e KEY=VALUE pair", async () => {
+    // The classic hatch failure shape: docker invoked with several
+    // -e flags, exiting non-zero. Without the fix, args.join(" ")
+    // would put `-e ANTHROPIC_API_KEY=sk-ant-…` into err.message.
+    const fakeSecret = "sk-ant-this-should-never-appear-in-logs";
+    try {
+      await exec("sh", [
+        "-c",
+        `echo "bind for 0.0.0.0:20100 failed: port is already allocated" 1>&2 && exit 125`,
+        "-e",
+        `ANTHROPIC_API_KEY=${fakeSecret}`,
+      ]);
+      throw new Error("exec 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 125");
+      expect(message).toContain("port is already allocated");
+    }
+  });
+});
+
+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";
+    try {
+      await execOutput("sh", [
+        "-c",
+        `echo "no such container" 1>&2 && exit 1`,
+        "-e",
+        `OPENAI_API_KEY=${fakeSecret}`,
+      ]);
+      throw new Error("execOutput should have rejected");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      expect(message).not.toContain(fakeSecret);
+      expect(message).not.toContain("OPENAI_API_KEY");
+      expect(message).toContain("sh exited with code 1");
+      expect(message).toContain("no such container");
+    }
+  });
+});

package/src/lib/api-key-check.ts

@@ -0,0 +1,40 @@
+import { LLM_PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
+
+export interface ApiKeyCheckResult {
+  hasKey: boolean;
+}
+
+/**
+ * Returns true when a key value is a real credential rather than a placeholder.
+ *
+ * .env.example ships values like `sk-ant-...`, `sk-...`, and `...` to show
+ * where credentials go. Any value containing `...` or that is empty is treated
+ * as a placeholder that the user has not replaced yet.
+ */
+function isPlaceholder(value: string | undefined): boolean {
+  if (!value || value.trim() === "") return true;
+  if (value.includes("...")) return true;
+  return false;
+}
+
+/**
+ * Check whether at least one LLM provider API key is configured in the
+ * current process environment.
+ *
+ * The CLI's job is to spawn the daemon and pass configuration via environment
+ * variables — it does not read from the .vellum/ directory (see AGENTS.md).
+ * Checking process.env is sufficient: the daemon forwards whatever is set
+ * in the environment, so exporting a key before running `vellum hatch` is
+ * the correct way to supply it.
+ *
+ * Uses the canonical LLM provider env-var catalog so the list stays in sync
+ * automatically as new providers are added.
+ */
+export function checkProviderApiKey(): ApiKeyCheckResult {
+  for (const envVar of Object.values(LLM_PROVIDER_ENV_VAR_NAMES)) {
+    if (!isPlaceholder(process.env[envVar])) {
+      return { hasKey: true };
+    }
+  }
+  return { hasKey: false };
+}

package/src/lib/assistant-config.ts

@@ -109,6 +109,11 @@ export interface AssistantEntry {
   [key: string]: unknown;
 }
 
+export type AssistantLookupResult =
+  | { status: "found"; entry: AssistantEntry }
+  | { status: "not_found" }
+  | { status: "ambiguous"; matches: AssistantEntry[] };
+
 interface LockfileData {
   assistants?: Record<string, unknown>[];
   activeAssistant?: string;
@@ -309,8 +314,70 @@ export function loadLatestAssistant(): AssistantEntry | null {
 }
 
 export function findAssistantByName(name: string): AssistantEntry | null {
+  return readAssistants().find((entry) => entry.assistantId === name) ?? null;
+}
+
+export function getAssistantDisplayName(entry: AssistantEntry): string {
+  const primary = entry.name?.trim();
+  if (primary) return primary;
+
+  const legacy = entry.assistantName?.trim();
+  if (legacy) return legacy;
+
+  return entry.assistantId;
+}
+
+export function formatAssistantReference(entry: AssistantEntry): string {
+  const displayName = getAssistantDisplayName(entry);
+  return displayName === entry.assistantId
+    ? entry.assistantId
+    : `${displayName} (${entry.assistantId})`;
+}
+
+function getAssistantDisplayNameCandidates(entry: AssistantEntry): string[] {
+  return Array.from(
+    new Set(
+      [entry.name?.trim(), entry.assistantName?.trim()].filter(
+        (value): value is string => typeof value === "string" && value !== "",
+      ),
+    ),
+  );
+}
+
+export function lookupAssistantByIdentifier(
+  identifier: string,
+): AssistantLookupResult {
   const entries = readAssistants();
-  return entries.find((e) => e.assistantId === name) ?? null;
+  const exactId = entries.find((entry) => entry.assistantId === identifier);
+  if (exactId) {
+    return { status: "found", entry: exactId };
+  }
+
+  const displayMatches = entries.filter((entry) =>
+    getAssistantDisplayNameCandidates(entry).includes(identifier),
+  );
+  if (displayMatches.length === 1) {
+    return { status: "found", entry: displayMatches[0] };
+  }
+  if (displayMatches.length > 1) {
+    return { status: "ambiguous", matches: displayMatches };
+  }
+
+  return { status: "not_found" };
+}
+
+export function formatAssistantLookupError(
+  identifier: string,
+  result: AssistantLookupResult = lookupAssistantByIdentifier(identifier),
+): string {
+  if (result.status === "ambiguous") {
+    const matches = result.matches
+      .map((entry) => formatAssistantReference(entry))
+      .join(", ");
+    return `Multiple assistants match '${identifier}': ${matches}. Use the assistant ID to disambiguate.`;
+  }
+
+  return `No assistant found with name or ID '${identifier}'.`;
 }
 
 export function removeAssistantEntry(assistantId: string): void {
@@ -446,13 +513,25 @@ export function resolveAssistant(nameArg?: string): AssistantEntry | null {
  * 3. Sole lockfile entry (any cloud)
  */
 export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
-  const entry = resolveAssistant(nameArg);
-  if (entry) return entry;
-
   if (nameArg) {
-    console.error(`No assistant found with name '${nameArg}'.`);
+    const result = lookupAssistantByIdentifier(nameArg);
+    if (result.status === "found") return result.entry;
+    console.error(formatAssistantLookupError(nameArg, result));
   } else {
+    const active = getActiveAssistant();
+    if (active) {
+      const result = lookupAssistantByIdentifier(active);
+      if (result.status === "found") return result.entry;
+      if (result.status === "ambiguous") {
+        console.error(formatAssistantLookupError(active, result));
+        process.exit(1);
+      }
+      // Active assistant no longer exists in lockfile — fall through.
+    }
+
     const all = readAssistants();
+    if (all.length === 1) return all[0];
+
     if (all.length === 0) {
       console.error("No assistant found. Run 'vellum hatch' first.");
     } else {

package/src/lib/assistant-target-args.ts

@@ -0,0 +1,21 @@
+export function parseAssistantTargetArg(
+  args: string[],
+  flagsWithValues: readonly string[] = [],
+): string | undefined {
+  const flagsWithValuesSet = new Set(flagsWithValues);
+  const parts: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (flagsWithValuesSet.has(arg)) {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      continue;
+    }
+    parts.push(arg);
+  }
+
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}