@vellumai/cli 0.4.10 → 0.4.12

package/README.md

@@ -14,6 +14,29 @@ bun run ./src/index.ts <command> [options]
 
 ## Commands
 
+### Lifecycle: `ps`, `sleep`, `wake`
+
+Day-to-day process management for the daemon and gateway.
+
+| Command | Description |
+|---------|-------------|
+| `vellum ps` | List assistants and per-assistant process status (daemon, gateway PIDs and health). |
+| `vellum sleep` | Stop daemon and gateway processes. Directory-agnostic — works from anywhere. |
+| `vellum wake` | Start the daemon and gateway from the current checkout. |
+
+```bash
+# Start everything
+vellum wake
+
+# Check what's running
+vellum ps
+
+# Stop everything
+vellum sleep
+```
+
+> **Note:** `vellum wake` requires a hatched assistant. Run `vellum hatch` first, or launch the macOS app which handles hatching automatically.
+
 ### `hatch`
 
 Provision a new assistant instance and bootstrap the Vellum runtime on it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/coverage.test.ts

@@ -0,0 +1,41 @@
+// Bun's coverage reporter only tracks files that are actually loaded during
+// test execution. There is no config option to include all source files.
+// See: https://github.com/oven-sh/bun/issues/5928
+import { resolve } from "node:path";
+import { expect, test } from "bun:test";
+
+const EXCLUDE_PATTERNS = [".test.ts", ".d.ts"];
+const EXCLUDE_FILES = [
+  // index.ts calls main() at module level, causing side effects on import
+  "index.ts",
+];
+
+async function importAllModules(dir: string): Promise<string[]> {
+  const glob = new Bun.Glob("**/*.{ts,tsx}");
+  const files = [...glob.scanSync(dir)].filter(
+    (f) =>
+      !EXCLUDE_PATTERNS.some((pattern) => f.endsWith(pattern)) &&
+      !EXCLUDE_FILES.some((excluded) => f === excluded) &&
+      !f.includes("__tests__"),
+  );
+
+  await Promise.all(files.map((relPath) => import(resolve(dir, relPath))));
+
+  return files;
+}
+
+test("imports all source modules for coverage tracking", async () => {
+  /**
+   * Ensures all source files are loaded so Bun's coverage reporter
+   * includes them in the report, not just files touched by other tests.
+   */
+
+  // GIVEN the src directory containing all source modules
+  const srcDir = resolve(import.meta.dir, "..");
+
+  // WHEN we dynamically import every source module
+  const files = await importAllModules(srcDir);
+
+  // THEN at least one file should have been imported
+  expect(files.length).toBeGreaterThan(0);
+});

package/src/commands/config.ts

@@ -1,8 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 
 import { syncConfigToLockfile } from "../lib/assistant-config";
+import {
+  getAllowlistPath,
+  getNestedValue,
+  loadRawConfig,
+  saveRawConfig,
+  setNestedValue,
+} from "../lib/config";
 
 interface AllowlistConfig {
   values?: string[];
@@ -16,76 +21,6 @@ interface AllowlistValidationError {
   message: string;
 }
 
-function getRootDir(): string {
-  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-}
-
-function getConfigPath(): string {
-  return join(getRootDir(), "workspace", "config.json");
-}
-
-function getAllowlistPath(): string {
-  return join(getRootDir(), "protected", "secret-allowlist.json");
-}
-
-function loadRawConfig(): Record<string, unknown> {
-  const configPath = getConfigPath();
-  if (!existsSync(configPath)) {
-    return {};
-  }
-  const raw = readFileSync(configPath, "utf-8");
-  return JSON.parse(raw) as Record<string, unknown>;
-}
-
-function saveRawConfig(config: Record<string, unknown>): void {
-  const configPath = getConfigPath();
-  const dir = dirname(configPath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-
-function getNestedValue(
-  obj: Record<string, unknown>,
-  path: string,
-): unknown {
-  const keys = path.split(".");
-  let current: unknown = obj;
-  for (const key of keys) {
-    if (
-      current === null ||
-      current === undefined ||
-      typeof current !== "object"
-    ) {
-      return undefined;
-    }
-    current = (current as Record<string, unknown>)[key];
-  }
-  return current;
-}
-
-function setNestedValue(
-  obj: Record<string, unknown>,
-  path: string,
-  value: unknown,
-): void {
-  const keys = path.split(".");
-  let current = obj;
-  for (let i = 0; i < keys.length - 1; i++) {
-    const key = keys[i];
-    if (
-      current[key] === undefined ||
-      current[key] === null ||
-      typeof current[key] !== "object"
-    ) {
-      current[key] = {};
-    }
-    current = current[key] as Record<string, unknown>;
-  }
-  current[keys[keys.length - 1]] = value;
-}
-
 function validateAllowlist(
   allowlistConfig: AllowlistConfig,
 ): AllowlistValidationError[] {

package/src/commands/retire.ts

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { rmSync, writeFileSync } from "fs";
+import { renameSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { basename, dirname, join } from "path";
 
@@ -63,20 +63,37 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
     } catch {}
   }
 
-  // Archive ~/.vellum before deleting
+  // Move ~/.vellum out of the way so the path is immediately available for the
+  // next hatch, then kick off the tar archive in the background.
+  const archivePath = getArchivePath(name);
+  const metadataPath = getMetadataPath(name);
+  const stagingDir = `${archivePath}.staging`;
+
   try {
-    const archivePath = getArchivePath(name);
-    const metadataPath = getMetadataPath(name);
-    await exec("tar", ["czf", archivePath, "-C", dirname(vellumDir), basename(vellumDir)]);
-    writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
-    console.log(`📦 Archived to ${archivePath}`);
+    renameSync(vellumDir, stagingDir);
   } catch (err) {
-    console.warn(`⚠️  Failed to archive: ${err instanceof Error ? err.message : err}`);
-    console.warn("Proceeding with permanent deletion.");
+    console.warn(`⚠️  Failed to move ${vellumDir}: ${err instanceof Error ? err.message : err}`);
+    console.warn("Skipping archive.");
+    console.log("\u2705 Local instance retired.");
+    return;
   }
 
-  rmSync(vellumDir, { recursive: true, force: true });
+  writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
+
+  // Spawn tar + cleanup in the background and detach so the CLI can exit
+  // immediately. The staging directory is removed once the archive is written.
+  const tarCmd = [
+    `tar czf ${JSON.stringify(archivePath)} -C ${JSON.stringify(dirname(stagingDir))} ${JSON.stringify(basename(stagingDir))}`,
+    `rm -rf ${JSON.stringify(stagingDir)}`,
+  ].join(" && ");
+
+  const child = spawn("sh", ["-c", tarCmd], {
+    stdio: "ignore",
+    detached: true,
+  });
+  child.unref();
 
+  console.log(`📦 Archiving to ${archivePath} in the background.`);
   console.log("\u2705 Local instance retired.");
 }
 

package/src/commands/sleep.ts

@@ -1,7 +1,6 @@
 import { homedir } from "os";
 import { join } from "path";
 
-import { loadAllAssistants } from "../lib/assistant-config";
 import { stopProcessByPidFile } from "../lib/process";
 
 export async function sleep(): Promise<void> {
@@ -13,20 +12,15 @@ export async function sleep(): Promise<void> {
     process.exit(0);
   }
 
-  const assistants = loadAllAssistants();
-  const hasLocal = assistants.some((a) => a.cloud === "local");
-  if (!hasLocal) {
-    console.error("Error: No local assistant found in lock file. Run 'vellum hatch local' first.");
-    process.exit(1);
-  }
-
   const vellumDir = join(homedir(), ".vellum");
   const daemonPidFile = join(vellumDir, "vellum.pid");
   const socketFile = join(vellumDir, "vellum.sock");
   const gatewayPidFile = join(vellumDir, "gateway.pid");
 
   // Stop daemon
-  const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon", [socketFile]);
+  const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon", [
+    socketFile,
+  ]);
   if (!daemonStopped) {
     console.log("Daemon is not running.");
   } else {

package/src/commands/tunnel.ts

@@ -0,0 +1,88 @@
+import { findAssistantByName, loadLatestAssistant } from "../lib/assistant-config";
+import { runNgrokTunnel } from "../lib/ngrok";
+
+const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
+type TunnelProvider = (typeof VALID_PROVIDERS)[number];
+
+const DEFAULT_PROVIDER: TunnelProvider = "vellum";
+
+interface TunnelArgs {
+  assistantName: string | null;
+  provider: TunnelProvider;
+}
+
+function parseArgs(): TunnelArgs {
+  const args = process.argv.slice(3);
+  let assistantName: string | null = null;
+  let provider: TunnelProvider = DEFAULT_PROVIDER;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log("Usage: vellum tunnel [<name>] [options]");
+      console.log("");
+      console.log("Create a tunnel for a locally hosted assistant.");
+      console.log("");
+      console.log("Arguments:");
+      console.log(
+        "  <name>                        Name of the assistant (defaults to latest)",
+      );
+      console.log("");
+      console.log("Options:");
+      console.log(
+        `  --provider <provider>         Tunnel provider: ${VALID_PROVIDERS.join(", ")} (default: ${DEFAULT_PROVIDER})`,
+      );
+      process.exit(0);
+    } else if (arg === "--provider") {
+      const next = args[i + 1];
+      if (!next || !VALID_PROVIDERS.includes(next as TunnelProvider)) {
+        console.error(
+          `Error: --provider requires one of: ${VALID_PROVIDERS.join(", ")}`,
+        );
+        process.exit(1);
+      }
+      provider = next as TunnelProvider;
+      i++;
+    } else if (arg.startsWith("-")) {
+      console.error(`Error: Unknown option '${arg}'.`);
+      process.exit(1);
+    } else if (!assistantName) {
+      assistantName = arg;
+    } else {
+      console.error(`Error: Unexpected argument '${arg}'.`);
+      process.exit(1);
+    }
+  }
+
+  return { assistantName, provider };
+}
+
+export async function tunnel(): Promise<void> {
+  const { assistantName, provider } = parseArgs();
+
+  const entry = assistantName
+    ? findAssistantByName(assistantName)
+    : loadLatestAssistant();
+
+  if (!entry) {
+    if (assistantName) {
+      console.error(
+        `No assistant instance found with name '${assistantName}'.`,
+      );
+    } else {
+      console.error(
+        "No assistant instance found. Run `vellum hatch` first.",
+      );
+    }
+    process.exit(1);
+  }
+
+  if (provider === "ngrok") {
+    await runNgrokTunnel();
+    return;
+  }
+
+  throw new Error(
+    `Tunnel provider '${provider}' is not yet implemented.`,
+  );
+}

package/src/index.ts

@@ -18,9 +18,9 @@ import { pair } from "./commands/pair";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
 import { retire } from "./commands/retire";
-import { skills } from "./commands/skills";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
+import { tunnel } from "./commands/tunnel";
 import { wake } from "./commands/wake";
 
 const commands = {
@@ -36,9 +36,9 @@ const commands = {
   ps,
   recover,
   retire,
-  skills,
   sleep,
   ssh,
+  tunnel,
   wake,
   whoami,
 } as const;
@@ -49,9 +49,8 @@ function resolveAssistantEntry(): string | undefined {
   // When installed globally, resolve from node_modules
   try {
     const require = createRequire(import.meta.url);
-    const assistantPkgPath = require.resolve(
-      "@vellumai/assistant/package.json"
-    );
+    const assistantPkgPath =
+      require.resolve("@vellumai/assistant/package.json");
     return join(dirname(assistantPkgPath), "src", "index.ts");
   } catch {
     // For local development, resolve from sibling directory
@@ -62,7 +61,7 @@ function resolveAssistantEntry(): string | undefined {
       "..",
       "assistant",
       "src",
-      "index.ts"
+      "index.ts",
     );
     if (existsSync(localPath)) {
       return localPath;
@@ -93,12 +92,14 @@ async function main() {
     console.log("  login    Log in to the Vellum platform");
     console.log("  logout   Log out of the Vellum platform");
     console.log("  pair     Pair with a remote assistant via QR code");
-    console.log("  ps       List assistants (or processes for a specific assistant)");
+    console.log(
+      "  ps       List assistants (or processes for a specific assistant)",
+    );
     console.log("  recover  Restore a previously retired local assistant");
     console.log("  retire   Delete an assistant instance");
-    console.log("  skills   Browse and install skills from the Vellum catalog");
     console.log("  sleep    Stop the daemon process");
     console.log("  ssh      SSH into a remote assistant instance");
+    console.log("  tunnel   Create a tunnel for a locally hosted assistant");
     console.log("  wake     Start the daemon and gateway");
     console.log("  whoami   Show current logged-in user");
     process.exit(0);
@@ -117,9 +118,7 @@ async function main() {
       });
     } else {
       console.error(`Unknown command: ${commandName}`);
-      console.error(
-        "Install the full stack with: bun install -g vellum"
-      );
+      console.error("Install the full stack with: bun install -g vellum");
       process.exit(1);
     }
     return;

package/src/lib/config.ts

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+function getRootDir(): string {
+  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
+}
+
+export function getConfigPath(): string {
+  return join(getRootDir(), "workspace", "config.json");
+}
+
+export function getAllowlistPath(): string {
+  return join(getRootDir(), "protected", "secret-allowlist.json");
+}
+
+export function loadRawConfig(): Record<string, unknown> {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  const raw = readFileSync(configPath, "utf-8");
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+export function saveRawConfig(config: Record<string, unknown>): void {
+  const configPath = getConfigPath();
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+export function getNestedValue(
+  obj: Record<string, unknown>,
+  path: string,
+): unknown {
+  const keys = path.split(".");
+  let current: unknown = obj;
+  for (const key of keys) {
+    if (
+      current === null ||
+      current === undefined ||
+      typeof current !== "object"
+    ) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+export function setNestedValue(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const keys = path.split(".");
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (
+      current[key] === undefined ||
+      current[key] === null ||
+      typeof current[key] !== "object"
+    ) {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+  current[keys[keys.length - 1]] = value;
+}

package/src/lib/local.ts

@@ -2,7 +2,7 @@ import { execFileSync, spawn } from "child_process";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { createRequire } from "module";
 import { createConnection } from "net";
-import { homedir } from "os";
+import { homedir, hostname, networkInterfaces, platform } from "os";
 import { dirname, join } from "path";
 
 import { loadLatestAssistant } from "./assistant-config.js";
@@ -254,8 +254,8 @@ async function discoverPublicUrl(): Promise<string | undefined> {
 
   let externalIp: string | undefined;
 
-  // Try cloud-specific metadata services first for GCP and AWS.
-  if (cloud && cloud !== "local") {
+  // Try cloud-specific metadata services for GCP and AWS.
+  if (cloud === "gcp" || cloud === "aws") {
     try {
       if (cloud === "gcp") {
         const resp = await fetch(
@@ -281,46 +281,85 @@ async function discoverPublicUrl(): Promise<string | undefined> {
     } catch {
       // metadata service not reachable
     }
+
+    if (externalIp) {
+      console.log(`   Discovered external IP: ${externalIp}`);
+      return `http://${externalIp}:${GATEWAY_PORT}`;
+    }
   }
 
-  // Fall back to a public IP discovery service for all environments
-  // (local, custom, or when cloud-specific metadata didn't resolve).
-  if (!externalIp) {
-    externalIp = await discoverPublicIpFallback();
+  // For local and custom environments, use the local LAN address.
+  // On macOS, prefer the .local hostname (Bonjour/mDNS) so other devices on
+  // the same network can reach the gateway by name.
+  if (platform() === "darwin") {
+    const localHostname = getMacLocalHostname();
+    if (localHostname) {
+      console.log(`   Discovered macOS local hostname: ${localHostname}`);
+      return `http://${localHostname}:${GATEWAY_PORT}`;
+    }
   }
 
-  if (externalIp) {
-    console.log(`   Discovered external IP: ${externalIp}`);
-    return `http://${externalIp}:${GATEWAY_PORT}`;
+  const lanIp = getLocalLanIPv4();
+  if (lanIp) {
+    console.log(`   Discovered LAN IP: ${lanIp}`);
+    return `http://${lanIp}:${GATEWAY_PORT}`;
   }
 
-  // Final fallback to localhost when no public IP could be discovered.
+  // Final fallback to localhost when no LAN address could be discovered.
   return `http://localhost:${GATEWAY_PORT}`;
 }
 
-/** Try to discover the machine's public IP using external services.
- *  Attempts multiple providers for resilience. */
-async function discoverPublicIpFallback(): Promise<string | undefined> {
-  const services = [
-    "https://api.ipify.org",
-    "https://ifconfig.me/ip",
-    "https://icanhazip.com",
-  ];
+/**
+ * Returns the macOS Bonjour/mDNS `.local` hostname (e.g. "Vargass-Mac-Mini.local"),
+ * or undefined if not running on macOS or the hostname cannot be determined.
+ */
+function getMacLocalHostname(): string | undefined {
+  const host = hostname();
+  if (!host) return undefined;
+  // macOS hostnames already end with .local when Bonjour is active
+  if (host.endsWith(".local")) return host;
+  // Otherwise, append .local — macOS resolves <ComputerName>.local via mDNS
+  return `${host}.local`;
+}
 
-  for (const url of services) {
-    try {
-      const resp = await fetch(url, { signal: AbortSignal.timeout(3000) });
-      if (resp.ok) {
-        const ip = (await resp.text()).trim();
-        // Basic validation: must look like an IPv4 or IPv6 address
-        if (ip && /^[\d.:a-fA-F]+$/.test(ip)) {
-          return ip;
-        }
+/**
+ * Returns the local IPv4 address most likely to be reachable from other
+ * devices on the same LAN.
+ *
+ * Priority order:
+ *   1. en0 (Wi-Fi on macOS)
+ *   2. en1 (secondary network on macOS)
+ *   3. First non-loopback IPv4 on any interface
+ *
+ * Skips link-local addresses (169.254.x.x) and IPv6.
+ * Returns undefined if no suitable address is found.
+ */
+function getLocalLanIPv4(): string | undefined {
+  const ifaces = networkInterfaces();
+
+  // Priority interfaces in order
+  const priorityInterfaces = ["en0", "en1"];
+
+  for (const ifName of priorityInterfaces) {
+    const addrs = ifaces[ifName];
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal && !addr.address.startsWith("169.254.")) {
+        return addr.address;
+      }
+    }
+  }
+
+  // Fallback: first non-loopback, non-link-local IPv4 on any interface
+  for (const [, addrs] of Object.entries(ifaces)) {
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal && !addr.address.startsWith("169.254.")) {
+        return addr.address;
       }
-    } catch {
-      // Service unreachable, try the next one
     }
   }
+
   return undefined;
 }
 

package/src/lib/ngrok.ts

@@ -0,0 +1,263 @@
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+
+import { loadRawConfig, saveRawConfig } from "./config";
+import { GATEWAY_PORT } from "./constants";
+
+const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
+const NGROK_POLL_INTERVAL_MS = 500;
+const NGROK_POLL_TIMEOUT_MS = 15_000;
+
+interface NgrokTunnel {
+  public_url: string;
+  config?: { addr?: string };
+}
+
+interface NgrokTunnelsResponse {
+  tunnels: NgrokTunnel[];
+}
+
+/**
+ * Check whether ngrok is installed and accessible on the PATH.
+ * Returns the version string if installed, null otherwise.
+ */
+export function getNgrokVersion(): string | null {
+  try {
+    const output = execFileSync("ngrok", ["version"], {
+      encoding: "utf-8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Query the ngrok local API for running tunnels.
+ * Returns the list of tunnels, or null if the API is unreachable.
+ */
+async function queryNgrokTunnels(): Promise<NgrokTunnel[] | null> {
+  try {
+    const res = await fetch(NGROK_API_URL, {
+      signal: AbortSignal.timeout(2_000),
+    });
+    if (!res.ok) return null;
+    const data = (await res.json()) as NgrokTunnelsResponse;
+    return data.tunnels ?? [];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find an existing ngrok tunnel that targets the given local address.
+ * Returns the HTTPS public URL if found, null otherwise.
+ */
+export async function findExistingTunnel(
+  targetPort: number,
+): Promise<string | null> {
+  const tunnels = await queryNgrokTunnels();
+  if (!tunnels || tunnels.length === 0) return null;
+
+  const targetAddrs = [
+    `localhost:${targetPort}`,
+    `127.0.0.1:${targetPort}`,
+    `http://localhost:${targetPort}`,
+    `http://127.0.0.1:${targetPort}`,
+  ];
+
+  // Prefer HTTPS tunnel
+  for (const t of tunnels) {
+    const addr = t.config?.addr ?? "";
+    if (targetAddrs.includes(addr) && t.public_url.startsWith("https://")) {
+      return t.public_url;
+    }
+  }
+
+  // Fall back to any tunnel pointing at the target
+  for (const t of tunnels) {
+    const addr = t.config?.addr ?? "";
+    if (targetAddrs.includes(addr) && t.public_url) {
+      return t.public_url;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Start an ngrok process tunneling HTTP traffic to the given local port.
+ * Returns the spawned child process.
+ */
+export function startNgrokProcess(targetPort: number): ChildProcess {
+  const child = spawn("ngrok", ["http", String(targetPort), "--log=stdout"], {
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return child;
+}
+
+/**
+ * Poll the ngrok local API until an HTTPS tunnel URL appears.
+ * Returns the public URL, or throws if the timeout is exceeded.
+ */
+export async function waitForNgrokUrl(
+  timeoutMs: number = NGROK_POLL_TIMEOUT_MS,
+): Promise<string> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const tunnels = await queryNgrokTunnels();
+    if (tunnels && tunnels.length > 0) {
+      // Prefer HTTPS
+      const httpsTunnel = tunnels.find((t) =>
+        t.public_url.startsWith("https://"),
+      );
+      if (httpsTunnel) return httpsTunnel.public_url;
+      if (tunnels[0]?.public_url) return tunnels[0].public_url;
+    }
+    await new Promise((r) => setTimeout(r, NGROK_POLL_INTERVAL_MS));
+  }
+  throw new Error(
+    `ngrok tunnel did not become available within ${timeoutMs / 1000}s. Check ngrok logs for errors.`,
+  );
+}
+
+/**
+ * Persist a public ingress URL to the workspace config and enable ingress.
+ */
+function saveIngressUrl(publicUrl: string): void {
+  const config = loadRawConfig();
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  ingress.publicBaseUrl = publicUrl;
+  ingress.enabled = true;
+  config.ingress = ingress;
+  saveRawConfig(config);
+}
+
+/**
+ * Clear the ingress public base URL from the workspace config.
+ */
+function clearIngressUrl(): void {
+  const config = loadRawConfig();
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  delete ingress.publicBaseUrl;
+  config.ingress = ingress;
+  saveRawConfig(config);
+}
+
+/**
+ * Run the ngrok tunnel workflow: check installation, find or start a tunnel,
+ * save the public URL to config, and block until exit or signal.
+ */
+export async function runNgrokTunnel(): Promise<void> {
+  const version = getNgrokVersion();
+  if (!version) {
+    console.error("Error: ngrok is not installed.");
+    console.error("");
+    console.error("Install ngrok:");
+    console.error("  macOS:  brew install ngrok/ngrok/ngrok");
+    console.error("  Linux:  sudo snap install ngrok");
+    console.error("");
+    console.error(
+      "Then authenticate: ngrok config add-authtoken <your-token>",
+    );
+    console.error(
+      "  Get your token at: https://dashboard.ngrok.com/get-started/your-authtoken",
+    );
+    process.exit(1);
+  }
+
+  console.log(`Using ${version}`);
+
+  const port = GATEWAY_PORT;
+
+  // Check for an existing ngrok tunnel pointing at the gateway
+  const existingUrl = await findExistingTunnel(port);
+  if (existingUrl) {
+    console.log(`Found existing ngrok tunnel: ${existingUrl}`);
+    saveIngressUrl(existingUrl);
+    console.log("Ingress URL saved to config.");
+    console.log("");
+    console.log(
+      "Tunnel is already running. Press Ctrl+C to detach (tunnel stays active).",
+    );
+
+    // Block until SIGINT/SIGTERM
+    await new Promise<void>((resolve) => {
+      process.on("SIGINT", () => resolve());
+      process.on("SIGTERM", () => resolve());
+    });
+    return;
+  }
+
+  console.log(`Starting ngrok tunnel to localhost:${port}...`);
+
+  let publicUrl: string | undefined;
+
+  const ngrokProcess = startNgrokProcess(port);
+
+  const cleanup = () => {
+    if (!ngrokProcess.killed) {
+      ngrokProcess.kill("SIGTERM");
+    }
+    if (publicUrl) {
+      console.log("\nClearing ingress URL from config...");
+      clearIngressUrl();
+    }
+  };
+
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  ngrokProcess.on("error", (err: Error) => {
+    console.error(`ngrok process error: ${err.message}`);
+    process.exit(1);
+  });
+
+  ngrokProcess.on("exit", (code: number | null) => {
+    if (code !== null && code !== 0) {
+      console.error(`ngrok exited with code ${code}.`);
+      console.error(
+        "Check that ngrok is authenticated: ngrok config add-authtoken <token>",
+      );
+      process.exit(1);
+    }
+  });
+
+  // Pipe ngrok stdout/stderr to console for visibility
+  ngrokProcess.stdout?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[ngrok] ${line}`);
+  });
+  ngrokProcess.stderr?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.error(`[ngrok] ${line}`);
+  });
+
+  try {
+    publicUrl = await waitForNgrokUrl();
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  console.log("");
+  console.log(`Tunnel established: ${publicUrl}`);
+  console.log(`Forwarding to:     localhost:${port}`);
+
+  saveIngressUrl(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 the ngrok process exits or we receive a signal
+  await new Promise<void>((resolve) => {
+    ngrokProcess.on("exit", () => resolve());
+  });
+}

package/src/commands/skills.ts

@@ -1,355 +0,0 @@
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  writeFileSync,
-} from "node:fs";
-import { homedir } from "node:os";
-import { join, dirname } from "node:path";
-import { gunzipSync } from "node:zlib";
-import { randomUUID } from "node:crypto";
-
-// ---------------------------------------------------------------------------
-// Path helpers
-// ---------------------------------------------------------------------------
-
-function getRootDir(): string {
-  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-}
-
-function getSkillsDir(): string {
-  return join(getRootDir(), "workspace", "skills");
-}
-
-function getSkillsIndexPath(): string {
-  return join(getSkillsDir(), "SKILLS.md");
-}
-
-// ---------------------------------------------------------------------------
-// Platform API client
-// ---------------------------------------------------------------------------
-
-function getConfigPlatformUrl(): string | undefined {
-  try {
-    const configPath = join(getRootDir(), "workspace", "config.json");
-    if (!existsSync(configPath)) return undefined;
-    const raw = JSON.parse(readFileSync(configPath, "utf-8")) as Record<
-      string,
-      unknown
-    >;
-    const platform = raw.platform as Record<string, unknown> | undefined;
-    const baseUrl = platform?.baseUrl;
-    if (typeof baseUrl === "string" && baseUrl.trim()) return baseUrl.trim();
-  } catch {
-    // ignore
-  }
-  return undefined;
-}
-
-function getPlatformUrl(): string {
-  return (
-    process.env.VELLUM_ASSISTANT_PLATFORM_URL ??
-    getConfigPlatformUrl() ??
-    "https://platform.vellum.ai"
-  );
-}
-
-function getPlatformToken(): string | null {
-  try {
-    return readFileSync(join(getRootDir(), "platform-token"), "utf-8").trim();
-  } catch {
-    return null;
-  }
-}
-
-function buildHeaders(): Record<string, string> {
-  const headers: Record<string, string> = {};
-  const token = getPlatformToken();
-  if (token) {
-    headers["X-Session-Token"] = token;
-  }
-  return headers;
-}
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface CatalogSkill {
-  id: string;
-  name: string;
-  description: string;
-  emoji?: string;
-  includes?: string[];
-  version?: string;
-}
-
-interface CatalogManifest {
-  version: number;
-  skills: CatalogSkill[];
-}
-
-// ---------------------------------------------------------------------------
-// Catalog operations
-// ---------------------------------------------------------------------------
-
-async function fetchCatalog(): Promise<CatalogSkill[]> {
-  const url = `${getPlatformUrl()}/v1/skills/`;
-  const response = await fetch(url, {
-    headers: buildHeaders(),
-    signal: AbortSignal.timeout(10000),
-  });
-
-  if (!response.ok) {
-    throw new Error(`Platform API error ${response.status}: ${response.statusText}`);
-  }
-
-  const manifest = (await response.json()) as CatalogManifest;
-  if (!Array.isArray(manifest.skills)) {
-    throw new Error("Platform catalog has invalid skills array");
-  }
-  return manifest.skills;
-}
-
-/**
- * Extract SKILL.md content from a tar archive (uncompressed).
- */
-function extractSkillMdFromTar(tarBuffer: Buffer): string | null {
-  let offset = 0;
-  while (offset + 512 <= tarBuffer.length) {
-    const header = tarBuffer.subarray(offset, offset + 512);
-
-    // End-of-archive (two consecutive zero blocks)
-    if (header.every((b) => b === 0)) break;
-
-    // Filename (bytes 0-99, null-terminated)
-    const nameEnd = header.indexOf(0, 0);
-    const name = header
-      .subarray(0, Math.min(nameEnd >= 0 ? nameEnd : 100, 100))
-      .toString("utf-8");
-
-    // File size (bytes 124-135, octal)
-    const sizeStr = header.subarray(124, 136).toString("utf-8").trim();
-    const size = parseInt(sizeStr, 8) || 0;
-
-    offset += 512; // past header
-
-    if (name.endsWith("SKILL.md") || name === "SKILL.md") {
-      return tarBuffer.subarray(offset, offset + size).toString("utf-8");
-    }
-
-    // Skip to next header (data padded to 512 bytes)
-    offset += Math.ceil(size / 512) * 512;
-  }
-  return null;
-}
-
-async function fetchSkillContent(skillId: string): Promise<string> {
-  const url = `${getPlatformUrl()}/v1/skills/${encodeURIComponent(skillId)}/`;
-  const response = await fetch(url, {
-    headers: buildHeaders(),
-    signal: AbortSignal.timeout(15000),
-  });
-
-  if (!response.ok) {
-    throw new Error(
-      `Failed to fetch skill "${skillId}": HTTP ${response.status}`,
-    );
-  }
-
-  const gzipBuffer = Buffer.from(await response.arrayBuffer());
-  const tarBuffer = gunzipSync(gzipBuffer);
-  const skillMd = extractSkillMdFromTar(tarBuffer);
-
-  if (!skillMd) {
-    throw new Error(`SKILL.md not found in archive for "${skillId}"`);
-  }
-
-  return skillMd;
-}
-
-// ---------------------------------------------------------------------------
-// Managed skill installation
-// ---------------------------------------------------------------------------
-
-function atomicWriteFile(filePath: string, content: string): void {
-  const dir = dirname(filePath);
-  mkdirSync(dir, { recursive: true });
-  const tmpPath = join(dir, `.tmp-${randomUUID()}`);
-  writeFileSync(tmpPath, content, "utf-8");
-  renameSync(tmpPath, filePath);
-}
-
-function upsertSkillsIndex(id: string): void {
-  const indexPath = getSkillsIndexPath();
-  let lines: string[] = [];
-  if (existsSync(indexPath)) {
-    lines = readFileSync(indexPath, "utf-8").split("\n");
-  }
-
-  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const pattern = new RegExp(`^[-*]\\s+(?:\`)?${escaped}(?:\`)?\\s*$`);
-  if (lines.some((line) => pattern.test(line))) return;
-
-  const nonEmpty = lines.filter((l) => l.trim());
-  nonEmpty.push(`- ${id}`);
-  const content = nonEmpty.join("\n");
-  atomicWriteFile(indexPath, content.endsWith("\n") ? content : content + "\n");
-}
-
-function installSkillLocally(
-  skillId: string,
-  skillMdContent: string,
-  catalogEntry: CatalogSkill,
-  overwrite: boolean,
-): void {
-  const skillDir = join(getSkillsDir(), skillId);
-  const skillFilePath = join(skillDir, "SKILL.md");
-
-  if (existsSync(skillFilePath) && !overwrite) {
-    throw new Error(
-      `Skill "${skillId}" is already installed. Use --overwrite to replace it.`,
-    );
-  }
-
-  mkdirSync(skillDir, { recursive: true });
-  atomicWriteFile(skillFilePath, skillMdContent);
-
-  // Write version metadata
-  if (catalogEntry.version) {
-    const meta = {
-      version: catalogEntry.version,
-      installedAt: new Date().toISOString(),
-    };
-    atomicWriteFile(
-      join(skillDir, "version.json"),
-      JSON.stringify(meta, null, 2) + "\n",
-    );
-  }
-
-  upsertSkillsIndex(skillId);
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function hasFlag(args: string[], flag: string): boolean {
-  return args.includes(flag);
-}
-
-// ---------------------------------------------------------------------------
-// Usage
-// ---------------------------------------------------------------------------
-
-function printUsage(): void {
-  console.log("Usage: vellum skills <subcommand> [options]");
-  console.log("");
-  console.log("Subcommands:");
-  console.log("  list                             List available catalog skills");
-  console.log(
-    "  install <skill-id> [--overwrite]  Install a skill from the catalog",
-  );
-  console.log("");
-  console.log("Options:");
-  console.log("  --json    Machine-readable JSON output");
-}
-
-// ---------------------------------------------------------------------------
-// Command entry point
-// ---------------------------------------------------------------------------
-
-export async function skills(): Promise<void> {
-  const args = process.argv.slice(3);
-  const subcommand = args[0];
-  const json = hasFlag(args, "--json");
-
-  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
-    printUsage();
-    return;
-  }
-
-  switch (subcommand) {
-    case "list": {
-      try {
-        const catalog = await fetchCatalog();
-
-        if (json) {
-          console.log(JSON.stringify({ ok: true, skills: catalog }));
-          return;
-        }
-
-        if (catalog.length === 0) {
-          console.log("No skills available in the catalog.");
-          return;
-        }
-
-        console.log(`Available skills (${catalog.length}):\n`);
-        for (const s of catalog) {
-          const emoji = s.emoji ? `${s.emoji} ` : "";
-          const deps = s.includes?.length
-            ? ` (requires: ${s.includes.join(", ")})`
-            : "";
-          console.log(`  ${emoji}${s.id}`);
-          console.log(`    ${s.name} — ${s.description}${deps}`);
-        }
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (json) {
-          console.log(JSON.stringify({ ok: false, error: msg }));
-        } else {
-          console.error(`Error: ${msg}`);
-        }
-        process.exitCode = 1;
-      }
-      break;
-    }
-
-    case "install": {
-      const skillId = args.find((a) => !a.startsWith("--") && a !== "install");
-      if (!skillId) {
-        console.error("Usage: vellum skills install <skill-id>");
-        process.exit(1);
-      }
-
-      const overwrite = hasFlag(args, "--overwrite");
-
-      try {
-        // Verify skill exists in catalog
-        const catalog = await fetchCatalog();
-        const entry = catalog.find((s) => s.id === skillId);
-        if (!entry) {
-          throw new Error(`Skill "${skillId}" not found in the Vellum catalog`);
-        }
-
-        // Fetch SKILL.md from platform
-        const content = await fetchSkillContent(skillId);
-
-        // Install locally
-        installSkillLocally(skillId, content, entry, overwrite);
-
-        if (json) {
-          console.log(JSON.stringify({ ok: true, skillId }));
-        } else {
-          console.log(`Installed skill "${skillId}".`);
-        }
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (json) {
-          console.log(JSON.stringify({ ok: false, error: msg }));
-        } else {
-          console.error(`Error: ${msg}`);
-        }
-        process.exitCode = 1;
-      }
-      break;
-    }
-
-    default: {
-      console.error(`Unknown skills subcommand: ${subcommand}`);
-      printUsage();
-      process.exit(1);
-    }
-  }
-}