@butlerw/vellum 0.1.0

package/src/tui/utils/ui-sizing.ts

@@ -0,0 +1,192 @@
+/**
+ * Terminal UI Sizing Utilities
+ *
+ * Centralized utilities for calculating terminal dimensions and responsive layouts.
+ * Ported from Gemini CLI patterns for consistent responsive behavior.
+ *
+ * @module tui/utils/ui-sizing
+ */
+
+/** Default terminal width when stdout is not a TTY */
+const DEFAULT_TERMINAL_WIDTH = 80;
+
+/** Default terminal height when stdout is not a TTY */
+const DEFAULT_TERMINAL_HEIGHT = 24;
+
+/** Minimum width for narrow terminal detection */
+const NARROW_WIDTH_BREAKPOINT = 80;
+
+/** Maximum width for responsive scaling (beyond this, use fixed percentage) */
+const WIDE_WIDTH_BREAKPOINT = 132;
+
+/** Content width percentage at narrow width (98%) */
+const NARROW_CONTENT_RATIO = 0.98;
+
+/** Content width percentage at wide width (90%) */
+const WIDE_CONTENT_RATIO = 0.9;
+
+/**
+ * Linear interpolation between two values.
+ *
+ * @param min - Minimum value (at t=0)
+ * @param max - Maximum value (at t=1)
+ * @param t - Interpolation factor (0-1)
+ * @returns Interpolated value
+ *
+ * @example
+ * ```ts
+ * lerp(0, 100, 0.5) // 50
+ * lerp(10, 20, 0.25) // 12.5
+ * ```
+ */
+export function lerp(min: number, max: number, t: number): number {
+  return min + (max - min) * t;
+}
+
+/**
+ * Clamp a value to a specified range.
+ *
+ * @param value - Value to clamp
+ * @param min - Minimum allowed value
+ * @param max - Maximum allowed value
+ * @returns Clamped value
+ *
+ * @example
+ * ```ts
+ * clamp(150, 0, 100) // 100
+ * clamp(-10, 0, 100) // 0
+ * clamp(50, 0, 100) // 50
+ * ```
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Get the current terminal width.
+ *
+ * @param fallback - Fallback width if terminal size cannot be determined
+ * @returns Terminal width in columns
+ *
+ * @example
+ * ```ts
+ * const width = getTerminalWidth();
+ * console.log(`Terminal is ${width} columns wide`);
+ * ```
+ */
+export function getTerminalWidth(fallback = DEFAULT_TERMINAL_WIDTH): number {
+  return process.stdout.columns ?? fallback;
+}
+
+/**
+ * Get the current terminal height.
+ *
+ * @param fallback - Fallback height if terminal size cannot be determined
+ * @returns Terminal height in rows
+ *
+ * @example
+ * ```ts
+ * const height = getTerminalHeight();
+ * console.log(`Terminal is ${height} rows tall`);
+ * ```
+ */
+export function getTerminalHeight(fallback = DEFAULT_TERMINAL_HEIGHT): number {
+  return process.stdout.rows ?? fallback;
+}
+
+/**
+ * Calculate the maximum content width for responsive layouts.
+ *
+ * Uses linear interpolation between narrow and wide breakpoints:
+ * - At 80 columns: 98% width (maximize space in small terminals)
+ * - At 132 columns: 90% width (comfortable reading width)
+ * - Below 80: Use full available width minus minimal padding
+ * - Above 132: Cap at 90% of terminal width
+ *
+ * @param terminalWidth - Terminal width (defaults to current terminal)
+ * @returns Maximum content width in columns
+ *
+ * @example
+ * ```ts
+ * // In a 100-column terminal
+ * const maxWidth = getMaxContentWidth(100);
+ * // Returns ~94 columns (interpolated between 98% and 90%)
+ * ```
+ */
+export function getMaxContentWidth(terminalWidth?: number): number {
+  const width = terminalWidth ?? getTerminalWidth();
+
+  // Below narrow breakpoint: use almost full width
+  if (width <= NARROW_WIDTH_BREAKPOINT) {
+    return Math.floor(width * NARROW_CONTENT_RATIO);
+  }
+
+  // Above wide breakpoint: cap at wide ratio
+  if (width >= WIDE_WIDTH_BREAKPOINT) {
+    return Math.floor(width * WIDE_CONTENT_RATIO);
+  }
+
+  // Interpolate between breakpoints
+  const t = (width - NARROW_WIDTH_BREAKPOINT) / (WIDE_WIDTH_BREAKPOINT - NARROW_WIDTH_BREAKPOINT);
+  const ratio = lerp(NARROW_CONTENT_RATIO, WIDE_CONTENT_RATIO, t);
+
+  return Math.floor(width * ratio);
+}
+
+/**
+ * Calculate content padding for centered layouts.
+ *
+ * @param terminalWidth - Terminal width (defaults to current terminal)
+ * @returns Object with left and right padding values
+ *
+ * @example
+ * ```ts
+ * const { left, right } = getContentPadding(100);
+ * // For centered content at 94 cols in 100 col terminal:
+ * // left = 3, right = 3
+ * ```
+ */
+export function getContentPadding(terminalWidth?: number): {
+  left: number;
+  right: number;
+} {
+  const width = terminalWidth ?? getTerminalWidth();
+  const contentWidth = getMaxContentWidth(width);
+  const totalPadding = width - contentWidth;
+
+  // Distribute padding evenly, with any remainder going to the right
+  const leftPadding = Math.floor(totalPadding / 2);
+  const rightPadding = totalPadding - leftPadding;
+
+  return {
+    left: leftPadding,
+    right: rightPadding,
+  };
+}
+
+/**
+ * Get terminal dimensions as an object.
+ *
+ * @returns Object with width and height
+ *
+ * @example
+ * ```ts
+ * const { width, height } = getTerminalSize();
+ * ```
+ */
+export function getTerminalSize(): { width: number; height: number } {
+  return {
+    width: getTerminalWidth(),
+    height: getTerminalHeight(),
+  };
+}
+
+// Re-export constants for external use
+export {
+  DEFAULT_TERMINAL_HEIGHT,
+  DEFAULT_TERMINAL_WIDTH,
+  NARROW_CONTENT_RATIO,
+  NARROW_WIDTH_BREAKPOINT,
+  WIDE_CONTENT_RATIO,
+  WIDE_WIDTH_BREAKPOINT,
+};

package/src/tui-blessed/app.ts

@@ -0,0 +1,160 @@
+import blessed from "neo-blessed";
+import type { AppComponents } from "./types.js";
+
+export function createApp(): AppComponents {
+  const screen = blessed.screen({
+    smartCSR: true,
+    fullUnicode: true,
+    title: "Vellum CLI (blessed POC)",
+  });
+
+  // Layout constants
+  const HEADER_HEIGHT = 1;
+  const STATUS_HEIGHT = 2;
+  const INPUT_HEIGHT = 3;
+
+  const header = blessed.box({
+    parent: screen,
+    top: 0,
+    left: 0,
+    width: "100%",
+    height: HEADER_HEIGHT,
+    content: " 🐍 Vellum CLI | Model: claude-3.5-sonnet ",
+    style: { fg: "white", bg: "blue" },
+  });
+
+  const messageLog = blessed.log({
+    parent: screen,
+    top: HEADER_HEIGHT,
+    left: 0,
+    width: "100%",
+    height: `100%-${HEADER_HEIGHT + STATUS_HEIGHT + INPUT_HEIGHT}`,
+    tags: true, // Enable {color-fg} tags
+    keys: true,
+    vi: true,
+    mouse: true,
+    scrollable: true,
+    alwaysScroll: true,
+    scrollbar: {
+      ch: "│",
+      track: { bg: "black" },
+      style: { bg: "gray" },
+    },
+    scrollback: 3000,
+    border: { type: "line" },
+    style: { border: { fg: "gray" } },
+  });
+
+  const statusBar = blessed.box({
+    parent: screen,
+    bottom: INPUT_HEIGHT,
+    left: 0,
+    width: "100%",
+    height: STATUS_HEIGHT,
+    content: " Status: Ready | Tokens: 0/0 ",
+    style: { fg: "gray" },
+    border: { type: "line" },
+  });
+
+  const input = blessed.textbox({
+    parent: screen,
+    bottom: 0,
+    left: 0,
+    width: "100%",
+    height: INPUT_HEIGHT,
+    inputOnFocus: true,
+    border: { type: "line" },
+    style: {
+      fg: "white",
+      border: { fg: "cyan" },
+    },
+    label: " Input ",
+  });
+
+  // Global keybindings
+  screen.key(["C-c", "C-q"], () => {
+    screen.destroy();
+    process.exit(0);
+  });
+
+  screen.key(["pageup"], () => {
+    messageLog.scroll(-Math.floor((messageLog.height as number) / 2));
+    screen.render();
+  });
+
+  screen.key(["pagedown"], () => {
+    messageLog.scroll(Math.floor((messageLog.height as number) / 2));
+    screen.render();
+  });
+
+  screen.key(["home"], () => {
+    messageLog.setScrollPerc(0);
+    screen.render();
+  });
+
+  screen.key(["end"], () => {
+    messageLog.setScrollPerc(100);
+    screen.render();
+  });
+
+  // Escape returns to input
+  screen.key(["escape"], () => {
+    input.focus();
+    screen.render();
+  });
+
+  // Input handling
+  input.on("submit", (value: string) => {
+    const text = String(value ?? "").trim();
+    if (text) {
+      addMessage(messageLog, { role: "user", content: text });
+      // Simulate assistant response
+      setTimeout(() => {
+        addMessage(messageLog, {
+          role: "assistant",
+          content: "This is a simulated response. 中文测试 🎉 Emoji test!",
+        });
+        screen.render();
+      }, 500);
+    }
+    input.clearValue();
+    screen.render();
+    input.focus();
+  });
+
+  input.focus();
+  screen.render();
+
+  return { screen, header, messageLog, input, statusBar };
+}
+
+function addMessage(
+  log: ReturnType<typeof blessed.log>,
+  message: { role: string; content: string }
+) {
+  const roleColors: Record<string, string> = {
+    user: "cyan",
+    assistant: "green",
+    system: "yellow",
+    tool: "magenta",
+  };
+  const color = roleColors[message.role] || "white";
+  const prefix = message.role === "user" ? "You" : "Assistant";
+  log.add(`{${color}-fg}${prefix}:{/${color}-fg} ${message.content}`);
+}
+
+export function addMessageToLog(
+  log: ReturnType<typeof blessed.log>,
+  role: "user" | "assistant" | "system" | "tool",
+  content: string
+) {
+  const roleColors: Record<string, string> = {
+    user: "cyan",
+    assistant: "green",
+    system: "yellow",
+    tool: "magenta",
+  };
+  const color = roleColors[role];
+  const prefix = role === "user" ? "You" : role.charAt(0).toUpperCase() + role.slice(1);
+  log.add(`{${color}-fg}${prefix}:{/${color}-fg} ${content}`);
+}

package/src/tui-blessed/index.ts

@@ -0,0 +1,2 @@
+export { addMessageToLog, createApp } from "./app.js";
+export type { AppComponents, MessageOptions } from "./types.js";

package/src/tui-blessed/neo-blessed.d.ts

@@ -0,0 +1,6 @@
+// Type declarations for neo-blessed
+// neo-blessed is a fork of blessed and uses the same API
+declare module "neo-blessed" {
+  import * as blessed from "blessed";
+  export = blessed;
+}

package/src/tui-blessed/test.ts

@@ -0,0 +1,21 @@
+import { createApp } from "./app.js";
+
+const { messageLog, screen } = createApp();
+
+// Add some test messages
+messageLog.add("{cyan-fg}You:{/cyan-fg} Hello!");
+messageLog.add("{green-fg}Assistant:{/green-fg} Hi! How can I help you today?");
+messageLog.add("{magenta-fg}Tool:{/magenta-fg} search_files completed");
+messageLog.add("{yellow-fg}System:{/yellow-fg} Connected to model");
+
+// Test CJK and emoji
+messageLog.add("{cyan-fg}You:{/cyan-fg} 请用中文回答 🎉");
+messageLog.add("{green-fg}Assistant:{/green-fg} 当然可以！我会用中文回答你的问题。😊");
+
+// Test long content
+messageLog.add(
+  "{green-fg}Assistant:{/green-fg} " +
+    "This is a very long message that should wrap properly in the terminal. ".repeat(5)
+);
+
+screen.render();

package/src/tui-blessed/types.ts

@@ -0,0 +1,14 @@
+import type { Widgets } from "blessed";
+
+export interface AppComponents {
+  screen: Widgets.Screen;
+  header: Widgets.BoxElement;
+  messageLog: Widgets.Log;
+  input: Widgets.TextboxElement;
+  statusBar: Widgets.BoxElement;
+}
+
+export interface MessageOptions {
+  role: "user" | "assistant" | "system" | "tool";
+  content: string;
+}

package/src/utils/icons.ts

@@ -0,0 +1,130 @@
+/**
+ * Text-based icons to replace emojis throughout the CLI.
+ * Using bracketed text for better terminal compatibility.
+ *
+ * @module cli/utils/icons
+ */
+
+/**
+ * Unified icon system for CLI output.
+ * All values are text-based for maximum terminal compatibility.
+ */
+export const ICONS = {
+  // Status indicators
+  success: "[OK]",
+  error: "[ERR]",
+  warning: "[WARN]",
+  info: "[INFO]",
+
+  // Actions/hints
+  hint: "Hint:",
+  tip: "Tip:",
+  note: "Note:",
+  tools: "Tools:",
+
+  // Progress indicators
+  skip: "[SKIP]",
+  running: "[...]",
+  done: "[DONE]",
+  interrupted: "[INT]",
+  pending: "[...]",
+
+  // File types (for mentions)
+  file: {
+    code: "[Code]",
+    docs: "[Doc]",
+    config: "[Cfg]",
+    web: "[Web]",
+    style: "[Style]",
+    default: "[File]",
+    folder: "[Dir]",
+  },
+
+  // Providers (bracketed names)
+  provider: {
+    anthropic: "[Anthropic]",
+    openai: "[OpenAI]",
+    google: "[Google]",
+    copilot: "[Copilot]",
+    deepseek: "[DeepSeek]",
+    groq: "[Groq]",
+    xai: "[xAI]",
+    qwen: "[Qwen]",
+    ollama: "[Ollama]",
+    lmstudio: "[LMStudio]",
+    default: "[Provider]",
+  },
+
+  // Modes
+  mode: {
+    vibe: "[Vibe]",
+    plan: "[Plan]",
+    spec: "[Spec]",
+  },
+
+  // Spec phases
+  phase: {
+    research: "[Research]",
+    requirements: "[Reqs]",
+    design: "[Design]",
+    tasks: "[Tasks]",
+    implementation: "[Impl]",
+    validation: "[Valid]",
+  },
+
+  // Tips/onboarding icons
+  tips: {
+    hint: "Hint:",
+    vibe: "[Vibe]",
+    edit: "[Edit]",
+    tools: "Tools:",
+    target: "[Goal]",
+    plan: "[Plan]",
+    search: "[Search]",
+    rocket: "[Start]",
+  },
+
+  // Misc
+  current: "*", // Mark current item
+  bullet: "-",
+  workflow: "[Flow]",
+  migrate: "[Migrate]",
+  package: "[Pkg]",
+  git: "[Git]",
+  cwd: "[CWD]",
+  checkpoint: "[Ckpt]",
+  celebration: "[Done!]",
+  reset: "[Reset]",
+} as const;
+
+/**
+ * Get provider icon text
+ */
+export function getProviderIcon(provider: string): string {
+  const key = provider.toLowerCase() as keyof typeof ICONS.provider;
+  return ICONS.provider[key] ?? ICONS.provider.default;
+}
+
+/**
+ * Get mode icon text
+ */
+export function getModeIcon(mode: string): string {
+  const key = mode.toLowerCase() as keyof typeof ICONS.mode;
+  return ICONS.mode[key] ?? `[${mode}]`;
+}
+
+/**
+ * Get phase icon text
+ */
+export function getPhaseIcon(phase: string): string {
+  const key = phase.toLowerCase() as keyof typeof ICONS.phase;
+  return ICONS.phase[key] ?? `[${phase}]`;
+}
+
+/**
+ * Get file type icon text
+ */
+export function getFileIcon(type: string): string {
+  const key = type.toLowerCase() as keyof typeof ICONS.file;
+  return ICONS.file[key] ?? ICONS.file.default;
+}

package/src/utils/index.ts

@@ -0,0 +1,33 @@
+/**
+ * CLI Utilities
+ *
+ * Shared utility functions for the Vellum CLI.
+ *
+ * @module cli/utils
+ */
+
+// For backward compatibility, also export ModelMetadata as an alias
+export type { ModelInfo as ModelMetadata } from "@vellum/provider";
+
+// Re-export model utilities from @vellum/provider (Single Source of Truth)
+export {
+  calculateCost,
+  getContextWindow,
+  getModelInfo,
+  getProviderModels,
+  getSupportedProviders,
+  type ModelInfo,
+} from "@vellum/provider";
+export {
+  getFileIcon,
+  getModeIcon,
+  getPhaseIcon,
+  getProviderIcon,
+  ICONS,
+} from "./icons.js";
+export {
+  formatResumeHint,
+  getShortId,
+  SHORT_ID_LENGTH,
+  shouldShowResumeHint,
+} from "./resume-hint.js";

package/src/utils/resume-hint.ts

@@ -0,0 +1,86 @@
+/**
+ * Resume Hint Utilities (T034)
+ *
+ * Provides exit resume hint formatting for the CLI.
+ * Displays a cyan-colored message with short session ID
+ * to help users resume their sessions.
+ *
+ * @module cli/utils/resume-hint
+ */
+
+import chalk from "chalk";
+
+import { ICONS } from "./icons.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Number of characters in a short session ID.
+ */
+export const SHORT_ID_LENGTH = 8;
+
+/**
+ * Horizontal separator line for the hint box.
+ */
+const SEPARATOR = "━".repeat(39);
+
+// =============================================================================
+// Functions
+// =============================================================================
+
+/**
+ * Extract short ID from a full session UUID.
+ *
+ * Takes the first 8 characters of the UUID for easy typing.
+ *
+ * @param sessionId - Full session UUID
+ * @returns First 8 characters of the UUID
+ *
+ * @example
+ * ```typescript
+ * getShortId('a1b2c3d4-e5f6-7890-abcd-ef1234567890')
+ * // Returns: 'a1b2c3d4'
+ * ```
+ */
+export function getShortId(sessionId: string): string {
+  return sessionId.slice(0, SHORT_ID_LENGTH);
+}
+
+/**
+ * Format a resume hint message for display on exit.
+ *
+ * Creates a cyan-colored box with instructions for resuming
+ * the session using the short ID.
+ *
+ * @param sessionId - Full session UUID
+ * @returns Formatted cyan-colored hint message
+ *
+ * @example
+ * ```typescript
+ * formatResumeHint('a1b2c3d4-e5f6-7890-abcd-ef1234567890')
+ * // Returns:
+ * // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * // Hint: To resume this session, run: vellum resume a1b2c3d4
+ * // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ```
+ */
+export function formatResumeHint(sessionId: string): string {
+  const shortId = getShortId(sessionId);
+  const message = `${ICONS.hint} To resume this session, run: vellum resume ${shortId}`;
+
+  return chalk.cyan(`${SEPARATOR}\n${message}\n${SEPARATOR}`);
+}
+
+/**
+ * Check if a session should show resume hint on exit.
+ *
+ * Resume hint should only be shown for sessions with messages.
+ *
+ * @param messageCount - Number of messages in the session
+ * @returns True if resume hint should be shown
+ */
+export function shouldShowResumeHint(messageCount: number): boolean {
+  return messageCount > 0;
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const version = "0.1.0";

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,35 @@
+/**
+ * Vitest Configuration for CLI Package
+ *
+ * CLI-specific test settings for command system tests.
+ * Tests for commands are located in src/commands/__tests__/
+ */
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: [
+      "src/**/*.test.{ts,tsx}",
+      // Explicitly include command tests
+      "src/commands/**/*.test.{ts,tsx}",
+      "src/commands/__tests__/**/*.test.{ts,tsx}",
+      // Include fixture tests
+      "src/test/fixtures/__tests__/**/*.test.{ts,tsx}",
+    ],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+    },
+    env: {
+      VELLUM_FAKE_RESPONSES: "true",
+      VELLUM_ICONS: "unicode", // Force Unicode icons in tests for consistent assertions
+    },
+    // Increase timeout for MCP-related tests that involve dynamic imports with vi.mock
+    testTimeout: 10000,
+    // Ensure tests with vi.mock for @vellum/mcp run in sequence to avoid mock conflicts
+    sequence: {
+      shuffle: false,
+    },
+  },
+});