@vellumai/cli 0.1.1

package/src/components/DefaultMainScreen.tsx

@@ -0,0 +1,217 @@
+import { type ReactElement } from "react";
+import { Box, render as inkRender, Text } from "ink";
+import { basename } from "path";
+
+import { SPECIES_CONFIG, type Species } from "../lib/constants";
+import { checkHealth } from "../lib/health-check";
+import { withStatusEmoji } from "../lib/status-emoji";
+
+export const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  magenta: "\x1b[35m",
+  gray: "\x1b[90m",
+} as const;
+
+export const SLASH_COMMANDS = ["/clear", "/doctor", "/exit", "/help", "/q", "/quit", "/retire"];
+
+export const TYPING_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface RuntimeMessage {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+  timestamp: string;
+  toolCalls?: unknown[];
+}
+
+export function formatTimestamp(ts: string): string {
+  try {
+    const date = new Date(ts);
+    return date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  } catch {
+    return "";
+  }
+}
+
+export function renderMessage(msg: RuntimeMessage): void {
+  const time = formatTimestamp(msg.timestamp);
+  const timeStr = time ? `${ANSI.gray}${time}${ANSI.reset} ` : "";
+
+  if (msg.role === "user") {
+    console.log(`${timeStr}${ANSI.green}${ANSI.bold}You:${ANSI.reset} ${msg.content}`);
+  } else {
+    console.log(`${timeStr}${ANSI.cyan}${ANSI.bold}Assistant:${ANSI.reset} ${msg.content}`);
+    if (msg.toolCalls && Array.isArray(msg.toolCalls) && msg.toolCalls.length > 0) {
+      for (const tc of msg.toolCalls) {
+        const call = tc as Record<string, unknown>;
+        const name = typeof call.name === "string" ? call.name : "unknown";
+        console.log(`  ${ANSI.dim}[tool: ${name}]${ANSI.reset}`);
+      }
+    }
+  }
+}
+
+export function renderHelp(): void {
+  console.log(`${ANSI.bold}Commands:${ANSI.reset}`);
+  console.log(
+    `  /doctor [question] ${ANSI.dim}Run diagnostics on the remote instance via SSH${ANSI.reset}`,
+  );
+  console.log(`  /retire           ${ANSI.dim}Retire the remote instance and exit${ANSI.reset}`);
+  console.log(`  /quit, /exit, /q  ${ANSI.dim}Disconnect and exit${ANSI.reset}`);
+  console.log(`  /clear            ${ANSI.dim}Clear the screen${ANSI.reset}`);
+  console.log(`  /help, ?          ${ANSI.dim}Show this help${ANSI.reset}`);
+}
+
+export function renderErrorMainScreen(error: unknown): number {
+  const msg = error instanceof Error ? error.message : String(error);
+  console.log(`${ANSI.red}${ANSI.bold}Failed to render MainWindow${ANSI.reset}`);
+  console.log(`${ANSI.dim}${msg}${ANSI.reset}`);
+  console.log(`${ANSI.dim}Run /clear to retry${ANSI.reset}`);
+  return 3;
+}
+
+function stripAnsi(str: string): string {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+interface DefaultMainScreenProps {
+  runtimeUrl: string;
+  assistantId: string;
+  species: Species;
+}
+
+function DefaultMainScreen({
+  runtimeUrl,
+  assistantId,
+  species,
+}: DefaultMainScreenProps): ReactElement {
+  const cwd = process.cwd();
+  const dirName = basename(cwd);
+  const config = SPECIES_CONFIG[species];
+  const art = config.art;
+  const accentColor = species === "openclaw" ? "red" : "magenta";
+
+  const tips = ["Send a message to start chatting", "Use /help to see available commands"];
+
+  const leftLines = [
+    " ",
+    "    Meet your Assistant!",
+    " ",
+    ...art.map((l) => `  ${stripAnsi(l)}`),
+    " ",
+    `  ${runtimeUrl}`,
+    `  ~/${dirName}`,
+  ];
+
+  const rightLines = [
+    " ",
+    "Tips for getting started",
+    ...tips,
+    " ",
+    "Assistant",
+    assistantId,
+    "Species",
+    `${config.hatchedEmoji} ${species}`,
+    "Status",
+    withStatusEmoji("checking..."),
+  ];
+
+  const maxLines = Math.max(leftLines.length, rightLines.length);
+
+  return (
+    <Box flexDirection="column" width={72}>
+      <Text dimColor>{"── Vellum " + "─".repeat(62)}</Text>
+      <Box flexDirection="row">
+        <Box flexDirection="column" width={LEFT_PANEL_WIDTH}>
+          {Array.from({ length: maxLines }, (_, i) => {
+            const line = leftLines[i] ?? " ";
+            if (i === 1) {
+              return (
+                <Text key={i} bold>
+                  {line}
+                </Text>
+              );
+            }
+            if (i > 2 && i <= 2 + art.length) {
+              return (
+                <Text key={i} color={accentColor}>
+                  {line}
+                </Text>
+              );
+            }
+            if (i > 2 + art.length) {
+              return (
+                <Text key={i} dimColor>
+                  {line}
+                </Text>
+              );
+            }
+            return <Text key={i}>{line}</Text>;
+          })}
+        </Box>
+        <Box flexDirection="column">
+          {Array.from({ length: maxLines }, (_, i) => {
+            const line = rightLines[i] ?? " ";
+            const isHeading = i === 1 || i === 6;
+            const isDim = i === 5 || i === 7 || i === 9;
+            if (isHeading) {
+              return (
+                <Text key={i} color={accentColor}>
+                  {line}
+                </Text>
+              );
+            }
+            if (isDim) {
+              return (
+                <Text key={i} dimColor>
+                  {line}
+                </Text>
+              );
+            }
+            return <Text key={i}>{line}</Text>;
+          })}
+        </Box>
+      </Box>
+      <Text dimColor>{"─".repeat(72)}</Text>
+      <Text> </Text>
+      <Text dimColor> ? for shortcuts</Text>
+      <Text> </Text>
+    </Box>
+  );
+}
+
+const LEFT_PANEL_WIDTH = 36;
+
+export function render(runtimeUrl: string, assistantId: string, species: Species): number {
+  const config = SPECIES_CONFIG[species];
+  const art = config.art;
+
+  const leftLineCount = 3 + art.length + 3;
+  const rightLineCount = 11;
+  const maxLines = Math.max(leftLineCount, rightLineCount);
+
+  const { unmount } = inkRender(
+    <DefaultMainScreen runtimeUrl={runtimeUrl} assistantId={assistantId} species={species} />,
+    { exitOnCtrlC: false },
+  );
+  unmount();
+
+  const statusCanvasLine = rightLineCount + 1;
+  const statusCol = LEFT_PANEL_WIDTH + 1;
+  checkHealth(runtimeUrl)
+    .then((health) => {
+      const statusText = health.detail
+        ? `${withStatusEmoji(health.status)} (${health.detail})`
+        : withStatusEmoji(health.status);
+      process.stdout.write(`\x1b7\x1b[${statusCanvasLine};${statusCol}H\x1b[K${statusText}\x1b8`);
+    })
+    .catch(() => {});
+
+  return 1 + maxLines + 4;
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env bun
+
+import { hatch } from "./commands/hatch";
+
+const commands = {
+  hatch,
+} as const;
+
+type CommandName = keyof typeof commands;
+
+async function main() {
+  const args = process.argv.slice(2);
+  const commandName = args[0];
+
+  if (!commandName || commandName === "--help" || commandName === "-h") {
+    console.log("Usage: vellum-cli <command> [options]");
+    console.log("");
+    console.log("Commands:");
+    console.log("  hatch   Create a new assistant instance");
+    process.exit(0);
+  }
+
+  const command = commands[commandName as CommandName];
+
+  if (!command) {
+    console.error(`Error: Unknown command '${commandName}'`);
+    console.error("Run 'vellum-cli --help' for usage information.");
+    process.exit(1);
+  }
+
+  try {
+    await command();
+  } catch (error) {
+    console.error("Error:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/lib/constants.ts

@@ -0,0 +1,75 @@
+export const FIREWALL_TAG = "vellum-assistant";
+export const GATEWAY_PORT = 7830;
+export const VALID_REMOTE_HOSTS = ["local", "gcp", "aws", "custom"] as const;
+export type RemoteHost = (typeof VALID_REMOTE_HOSTS)[number];
+export const VALID_SPECIES = ["openclaw", "vellum"] as const;
+export type Species = (typeof VALID_SPECIES)[number];
+
+const ANSI = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  red: "\x1b[31m",
+  magenta: "\x1b[35m",
+} as const;
+
+interface SpeciesConfig {
+  color: string;
+  art: string[];
+  hatchedEmoji: string;
+  waitingMessages: string[];
+  runningMessages: string[];
+}
+
+export const SPECIES_CONFIG: Record<Species, SpeciesConfig> = {
+  openclaw: {
+    color: ANSI.red,
+    art: [
+      `${ANSI.red}     ___${ANSI.reset}`,
+      `${ANSI.red}    / ${ANSI.reset}${ANSI.bold}o${ANSI.reset}${ANSI.red} \\${ANSI.reset}`,
+      `${ANSI.red}   |  ${ANSI.reset}${ANSI.bold}>${ANSI.reset}${ANSI.red}  |${ANSI.reset}`,
+      `${ANSI.red}   /|   |\\${ANSI.reset}`,
+      `${ANSI.red}  / |___| \\${ANSI.reset}`,
+      `${ANSI.red} |  /   \\  |${ANSI.reset}`,
+      `${ANSI.red} |_/     \\_|${ANSI.reset}`,
+      `${ANSI.red}  V       V${ANSI.reset}`,
+      `${ANSI.red}  |_|   |_|${ANSI.reset}`,
+    ],
+    hatchedEmoji: "🦞",
+    waitingMessages: [
+      "Warming up the egg...",
+      "Getting cozy in there...",
+      "Preparing the nest...",
+      "Gathering shell fragments...",
+    ],
+    runningMessages: [
+      "Running startup script...",
+      "Teaching the hatchling to code...",
+      "Growing stronger...",
+      "Almost ready to peek out...",
+    ],
+  },
+  vellum: {
+    color: ANSI.magenta,
+    art: [
+      `${ANSI.magenta}    ,___,${ANSI.reset}`,
+      `${ANSI.magenta}   (${ANSI.reset}${ANSI.bold} O O ${ANSI.reset}${ANSI.magenta})${ANSI.reset}`,
+      `${ANSI.magenta}    /)${ANSI.reset}${ANSI.bold}V${ANSI.reset}${ANSI.magenta}(\\${ANSI.reset}`,
+      `${ANSI.magenta}   //   \\\\${ANSI.reset}`,
+      `${ANSI.magenta}  /"     "\\${ANSI.reset}`,
+      `${ANSI.magenta}  ^       ^${ANSI.reset}`,
+    ],
+    hatchedEmoji: "🦉",
+    waitingMessages: [
+      "Warming up the nest...",
+      "Getting cozy in there...",
+      "Fluffing the feathers...",
+      "Preening in the moonlight...",
+    ],
+    runningMessages: [
+      "Running startup script...",
+      "Teaching the owlet to code...",
+      "Spreading wings...",
+      "Almost ready to take flight...",
+    ],
+  },
+};

package/src/lib/gcp.ts

@@ -0,0 +1,261 @@
+import { exec, execOutput } from "./step-runner";
+
+export async function getActiveProject(): Promise<string> {
+  const output = await execOutput("gcloud", [
+    "config",
+    "get-value",
+    "project",
+  ]);
+  const project = output.trim();
+  if (!project || project === "(unset)") {
+    throw new Error(
+      "No active GCP project. Run `gcloud config set project <project>` first.",
+    );
+  }
+  return project;
+}
+
+export interface FirewallRuleSpec {
+  name: string;
+  direction: "INGRESS" | "EGRESS";
+  action: "ALLOW" | "DENY";
+  rules: string;
+  sourceRanges?: string;
+  destinationRanges?: string;
+  targetTags: string;
+  description: string;
+}
+
+interface FirewallRuleState {
+  name: string;
+  direction: string;
+  allowed: string;
+  sourceRanges: string;
+  destinationRanges: string;
+  targetTags: string;
+  description: string;
+}
+
+async function describeFirewallRule(
+  ruleName: string,
+  project: string,
+): Promise<FirewallRuleState | null> {
+  try {
+    const output = await execOutput("gcloud", [
+      "compute",
+      "firewall-rules",
+      "describe",
+      ruleName,
+      `--project=${project}`,
+      "--format=json(name,direction,allowed,sourceRanges,destinationRanges,targetTags,description)",
+    ]);
+    const parsed = JSON.parse(output);
+    const allowed = (parsed.allowed ?? [])
+      .map((a: { IPProtocol: string; ports?: string[] }) => {
+        const ports = a.ports ?? [];
+        if (ports.length === 0) {
+          return a.IPProtocol;
+        }
+        return ports.map((p: string) => `${a.IPProtocol}:${p}`).join(",");
+      })
+      .filter(Boolean)
+      .join(",");
+    return {
+      name: parsed.name ?? "",
+      direction: parsed.direction ?? "",
+      allowed,
+      sourceRanges: (parsed.sourceRanges ?? []).join(","),
+      destinationRanges: (parsed.destinationRanges ?? []).join(","),
+      targetTags: (parsed.targetTags ?? []).join(","),
+      description: parsed.description ?? "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+function ruleNeedsUpdate(spec: FirewallRuleSpec, state: FirewallRuleState): boolean {
+  return (
+    spec.direction !== state.direction ||
+    spec.rules !== state.allowed ||
+    (spec.sourceRanges ?? "") !== state.sourceRanges ||
+    (spec.destinationRanges ?? "") !== state.destinationRanges ||
+    spec.targetTags !== state.targetTags ||
+    spec.description !== state.description
+  );
+}
+
+async function createFirewallRule(spec: FirewallRuleSpec, project: string): Promise<void> {
+  const args = [
+    "compute",
+    "firewall-rules",
+    "create",
+    spec.name,
+    `--project=${project}`,
+    `--direction=${spec.direction}`,
+    `--action=${spec.action}`,
+    `--rules=${spec.rules}`,
+    `--target-tags=${spec.targetTags}`,
+    `--description=${spec.description}`,
+  ];
+  if (spec.sourceRanges) {
+    args.push(`--source-ranges=${spec.sourceRanges}`);
+  }
+  if (spec.destinationRanges) {
+    args.push(`--destination-ranges=${spec.destinationRanges}`);
+  }
+  await exec("gcloud", args);
+}
+
+async function deleteFirewallRule(ruleName: string, project: string): Promise<void> {
+  await exec("gcloud", [
+    "compute",
+    "firewall-rules",
+    "delete",
+    ruleName,
+    `--project=${project}`,
+    "--quiet",
+  ]);
+}
+
+export async function syncFirewallRules(
+  desiredRules: FirewallRuleSpec[],
+  project: string,
+  tag: string,
+): Promise<void> {
+  let existingNames: string[];
+  try {
+    const output = await execOutput("gcloud", [
+      "compute",
+      "firewall-rules",
+      "list",
+      `--project=${project}`,
+      `--filter=targetTags:${tag}`,
+      "--format=value(name)",
+    ]);
+    existingNames = output
+      .split("\n")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  } catch {
+    existingNames = [];
+  }
+
+  const desiredNames = new Set(desiredRules.map((r) => r.name));
+
+  for (const existingName of existingNames) {
+    if (!desiredNames.has(existingName)) {
+      console.log(`   🗑️  Deleting stale firewall rule: ${existingName}`);
+      await deleteFirewallRule(existingName, project);
+    }
+  }
+
+  for (const spec of desiredRules) {
+    const state = await describeFirewallRule(spec.name, project);
+
+    if (!state) {
+      console.log(`   ➕ Creating firewall rule: ${spec.name}`);
+      await createFirewallRule(spec, project);
+      continue;
+    }
+
+    if (ruleNeedsUpdate(spec, state)) {
+      console.log(`   🔄 Updating firewall rule: ${spec.name}`);
+      await deleteFirewallRule(spec.name, project);
+      await createFirewallRule(spec, project);
+      continue;
+    }
+
+    console.log(`   ✅ Firewall rule up to date: ${spec.name}`);
+  }
+}
+
+export async function fetchFirewallRules(
+  project: string,
+  tag: string,
+): Promise<string> {
+  const output = await execOutput("gcloud", [
+    "compute",
+    "firewall-rules",
+    "list",
+    `--project=${project}`,
+    `--filter=targetTags:${tag}`,
+    "--format=json",
+  ]);
+  return output;
+}
+
+export interface GcpInstance {
+  name: string;
+  zone: string;
+  externalIp: string | null;
+  species: string | null;
+}
+
+export async function listAssistantInstances(project: string): Promise<GcpInstance[]> {
+  const output = await execOutput("gcloud", [
+    "compute",
+    "instances",
+    "list",
+    `--project=${project}`,
+    "--filter=labels.vellum-assistant=true",
+    "--format=json(name,zone,networkInterfaces[0].accessConfigs[0].natIP,labels)",
+  ]);
+  const parsed = JSON.parse(output) as Array<{
+    name: string;
+    zone: string;
+    networkInterfaces?: Array<{ accessConfigs?: Array<{ natIP?: string }> }>;
+    labels?: Record<string, string>;
+  }>;
+  return parsed.map((inst) => {
+    const zoneParts = (inst.zone ?? "").split("/");
+    return {
+      name: inst.name,
+      zone: zoneParts[zoneParts.length - 1] || "",
+      externalIp: inst.networkInterfaces?.[0]?.accessConfigs?.[0]?.natIP ?? null,
+      species: inst.labels?.species ?? null,
+    };
+  });
+}
+
+export async function instanceExists(
+  instanceName: string,
+  project: string,
+  zone: string,
+): Promise<boolean> {
+  try {
+    await execOutput("gcloud", [
+      "compute",
+      "instances",
+      "describe",
+      instanceName,
+      `--project=${project}`,
+      `--zone=${zone}`,
+      "--format=get(name)",
+    ]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function sshCommand(
+  instanceName: string,
+  project: string,
+  zone: string,
+  command: string,
+): Promise<string> {
+  return execOutput("gcloud", [
+    "compute",
+    "ssh",
+    instanceName,
+    `--project=${project}`,
+    `--zone=${zone}`,
+    "--quiet",
+    "--ssh-flag=-o StrictHostKeyChecking=no",
+    "--ssh-flag=-o UserKnownHostsFile=/dev/null",
+    "--ssh-flag=-o ConnectTimeout=5",
+    "--ssh-flag=-o LogLevel=ERROR",
+    `--command=${command}`,
+  ]);
+}

package/src/lib/health-check.ts

@@ -0,0 +1,38 @@
+export const HEALTH_CHECK_TIMEOUT_MS = 1500;
+
+interface HealthResponse {
+  status: string;
+  message?: string;
+}
+
+export interface HealthCheckResult {
+  status: string;
+  detail: string | null;
+}
+
+export async function checkHealth(runtimeUrl: string): Promise<HealthCheckResult> {
+  try {
+    const url = `${runtimeUrl}/healthz`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), HEALTH_CHECK_TIMEOUT_MS);
+
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { "Content-Type": "application/json" },
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      return { status: `error (${response.status})`, detail: null };
+    }
+
+    const data = (await response.json()) as HealthResponse;
+    const status = data.status || "unknown";
+    return { status, detail: status !== "healthy" ? (data.message ?? null) : null };
+  } catch (error) {
+    const status =
+      error instanceof Error && error.name === "AbortError" ? "timeout" : "unreachable";
+    return { status, detail: null };
+  }
+}

package/src/lib/interfaces-seed.ts

@@ -0,0 +1,25 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const COMPONENTS_DIR = join(import.meta.dir, "..", "components");
+const CONSTANTS_PATH = join(import.meta.dir, "constants.ts");
+
+function inlineLocalImports(source: string): string {
+  const constantsSource = readFileSync(CONSTANTS_PATH, "utf-8");
+
+  return source
+    .replace(/import\s*\{[^}]*\}\s*from\s*["'][^"']*\/constants["'];?\s*\n/, constantsSource + "\n")
+    .replace(/import\s*\{[^}]*\}\s*from\s*["']path["'];?\s*\n/, "");
+}
+
+export function buildInterfacesSeed(): string {
+  const rawSource = readFileSync(join(COMPONENTS_DIR, "DefaultMainScreen.tsx"), "utf-8");
+  const mainWindowSource = inlineLocalImports(rawSource);
+
+  return `
+INTERFACES_SEED_DIR="/tmp/interfaces-seed"
+mkdir -p "\$INTERFACES_SEED_DIR/tui"
+cat > "\$INTERFACES_SEED_DIR/tui/main-window.tsx" << 'INTERFACES_SEED_EOF'
+${mainWindowSource}INTERFACES_SEED_EOF
+`;
+}

package/src/lib/openclaw-runtime-server.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const ADAPTER_PATH = join(import.meta.dir, "..", "adapters", "openclaw-http-server.ts");
+
+export function buildOpenclawRuntimeServer(): string {
+  const serverSource = readFileSync(ADAPTER_PATH, "utf-8");
+
+  return `
+cat > /opt/openclaw-runtime-server.ts << 'RUNTIME_SERVER_EOF'
+${serverSource}
+RUNTIME_SERVER_EOF
+
+mkdir -p "\$HOME/.vellum"
+nohup bun run /opt/openclaw-runtime-server.ts >> "\$HOME/.vellum/http-gateway.log" 2>&1 &
+echo "OpenClaw runtime server started (PID: \$!)"
+`;
+}