@butlerw/vellum 0.1.0

package/src/commands/utils.ts

@@ -0,0 +1,142 @@
+/**
+ * Command System Utilities
+ *
+ * Shared utility functions for the command system.
+ *
+ * @module cli/commands/utils
+ */
+
+// =============================================================================
+// T034B: isSlashCommand
+// =============================================================================
+
+/**
+ * Check if input is a slash command
+ *
+ * Returns true if the input starts with a forward slash after trimming.
+ * Handles edge cases:
+ * - Empty string → false
+ * - Whitespace only → false
+ * - Just "/" → false (no command name)
+ * - "/command" → true
+ * - "  /command" → true (leading whitespace allowed)
+ *
+ * @param input - User input string to check
+ * @returns True if input is a slash command
+ *
+ * @example
+ * ```typescript
+ * isSlashCommand('/help')        // true
+ * isSlashCommand('  /login')     // true
+ * isSlashCommand('/a')           // true
+ * isSlashCommand('/')            // false (no command name)
+ * isSlashCommand('')             // false
+ * isSlashCommand('   ')          // false
+ * isSlashCommand('hello')        // false
+ * isSlashCommand('//comment')    // true (starts with /)
+ * ```
+ */
+export function isSlashCommand(input: string): boolean {
+  // Handle empty or whitespace-only
+  if (!input || typeof input !== "string") {
+    return false;
+  }
+
+  const trimmed = input.trim();
+
+  // Must have at least 2 chars: "/" + command char
+  if (trimmed.length < 2) {
+    return false;
+  }
+
+  // Must start with "/"
+  if (trimmed[0] !== "/") {
+    return false;
+  }
+
+  // Second character must not be whitespace (ensures command name exists)
+  const secondChar = trimmed[1];
+  if (secondChar === " " || secondChar === "\t" || secondChar === "\n") {
+    return false;
+  }
+
+  return true;
+}
+
+// =============================================================================
+// Additional Utilities
+// =============================================================================
+
+/**
+ * Extract command name from slash command input
+ *
+ * @param input - Slash command input (e.g., "/help topic")
+ * @returns Command name without slash, or null if not a valid command
+ *
+ * @example
+ * ```typescript
+ * extractCommandName('/help topic')  // 'help'
+ * extractCommandName('/login')       // 'login'
+ * extractCommandName('hello')        // null
+ * ```
+ */
+export function extractCommandName(input: string): string | null {
+  if (!isSlashCommand(input)) {
+    return null;
+  }
+
+  const trimmed = input.trim();
+  // Remove leading slash and split by whitespace
+  const parts = trimmed.slice(1).split(/\s+/);
+  return parts[0]?.toLowerCase() ?? null;
+}
+
+/**
+ * Split command input into command name and arguments
+ *
+ * @param input - Slash command input
+ * @returns Object with command name and args array, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseCommandInput('/login anthropic --store keychain')
+ * // { command: 'login', args: ['anthropic', '--store', 'keychain'] }
+ * ```
+ */
+export function parseCommandInput(input: string): { command: string; args: string[] } | null {
+  if (!isSlashCommand(input)) {
+    return null;
+  }
+
+  const trimmed = input.trim();
+  const parts = trimmed.slice(1).split(/\s+/);
+  const command = parts[0]?.toLowerCase() ?? "";
+  const args = parts.slice(1);
+
+  return { command, args };
+}
+
+/**
+ * Mask a sensitive value for display
+ *
+ * Shows first and last few characters with dots in between.
+ *
+ * @param value - Value to mask
+ * @param visibleChars - Number of visible chars at start and end (default: 4)
+ * @returns Masked string
+ *
+ * @example
+ * ```typescript
+ * maskValue('sk-1234567890abcdef')  // 'sk-1...cdef'
+ * maskValue('short')                // '****'
+ * ```
+ */
+export function maskValue(value: string, visibleChars = 4): string {
+  if (value.length <= visibleChars * 2) {
+    return "*".repeat(Math.max(4, value.length));
+  }
+
+  const start = value.slice(0, visibleChars);
+  const end = value.slice(-visibleChars);
+  return `${start}...${end}`;
+}

package/src/commands/vim.ts

@@ -0,0 +1,152 @@
+/**
+ * Vim Mode Slash Command (T041)
+ *
+ * Provides the /vim command for toggling Vim editing mode.
+ *
+ * @module cli/commands/vim
+ */
+
+import type { CommandContext, CommandResult, SlashCommand } from "./types.js";
+import { success } from "./types.js";
+
+// =============================================================================
+// Module State
+// =============================================================================
+
+/**
+ * Callback to toggle vim mode.
+ * Set by the App component when initialized.
+ */
+let vimToggleCallback: (() => void) | null = null;
+
+/**
+ * Callback to check if vim mode is enabled.
+ * Set by the App component when initialized.
+ */
+let vimEnabledCallback: (() => boolean) | null = null;
+
+/**
+ * Set the vim mode callbacks for the /vim command.
+ * Called by the App component during initialization.
+ *
+ * @param toggle - Callback to toggle vim mode on/off
+ * @param isEnabled - Callback to check if vim mode is currently enabled
+ */
+export function setVimCallbacks(toggle: () => void, isEnabled: () => boolean): void {
+  vimToggleCallback = toggle;
+  vimEnabledCallback = isEnabled;
+}
+
+/**
+ * Clear vim mode callbacks.
+ * Called during cleanup.
+ */
+export function clearVimCallbacks(): void {
+  vimToggleCallback = null;
+  vimEnabledCallback = null;
+}
+
+// =============================================================================
+// /vim Command
+// =============================================================================
+
+/**
+ * /vim command - Toggle Vim editing mode.
+ *
+ * When enabled:
+ * - Input field uses Vim-style modal editing
+ * - NORMAL mode: navigation and commands
+ * - INSERT mode: text entry (i, a, I, A, o, O)
+ * - VISUAL mode: text selection (v, V)
+ * - COMMAND mode: command line (:)
+ * - Press Escape to return to NORMAL mode
+ * - Press Ctrl+V to toggle vim mode on/off
+ *
+ * @example
+ * ```
+ * /vim         - Toggle vim mode on/off
+ * /vim on      - Enable vim mode
+ * /vim off     - Disable vim mode
+ * ```
+ */
+export const vimCommand: SlashCommand = {
+  name: "vim",
+  description: "Toggle Vim editing mode for input",
+  kind: "builtin",
+  category: "config",
+  aliases: ["vi"],
+  positionalArgs: [
+    {
+      name: "state",
+      type: "string",
+      description: "Explicitly set state: 'on' or 'off'",
+      required: false,
+    },
+  ],
+  examples: [
+    "/vim      - Toggle vim mode on/off",
+    "/vim on   - Enable vim mode",
+    "/vim off  - Disable vim mode",
+  ],
+
+  execute: async (ctx: CommandContext): Promise<CommandResult> => {
+    const state = ctx.parsedArgs.positional[0] as string | undefined;
+
+    // Check if callbacks are available
+    if (!vimToggleCallback || !vimEnabledCallback) {
+      return success("Vim mode system not initialized.");
+    }
+
+    const currentlyEnabled = vimEnabledCallback();
+
+    // Handle explicit on/off
+    if (state === "on") {
+      if (currentlyEnabled) {
+        return success(
+          "Vim mode is already enabled.\n\nUse 'i' to enter INSERT mode, Escape to return to NORMAL mode."
+        );
+      }
+      vimToggleCallback();
+      return success(
+        "🟢 Vim mode enabled.\n\nYou are now in NORMAL mode. Press 'i' to enter INSERT mode for typing."
+      );
+    }
+
+    if (state === "off") {
+      if (!currentlyEnabled) {
+        return success("Vim mode is already disabled.");
+      }
+      vimToggleCallback();
+      return success("⚫ Vim mode disabled.\n\nReturned to standard input mode.");
+    }
+
+    // Toggle
+    vimToggleCallback();
+    const newState = vimEnabledCallback();
+
+    if (newState) {
+      return success(
+        "🟢 Vim mode enabled.\n\n" +
+          "You are now in NORMAL mode. Key bindings:\n" +
+          "  • i, a, I, A, o, O - Enter INSERT mode\n" +
+          "  • v, V - Enter VISUAL mode\n" +
+          "  • : - Enter COMMAND mode\n" +
+          "  • h, j, k, l - Navigation\n" +
+          "  • Escape - Return to NORMAL mode\n" +
+          "  • Ctrl+V - Toggle vim mode off\n\n" +
+          "Press 'i' to start typing."
+      );
+    }
+
+    return success("⚫ Vim mode disabled.\n\nReturned to standard input mode.");
+  },
+};
+
+// =============================================================================
+// Export
+// =============================================================================
+
+/**
+ * All vim-related slash commands for registration.
+ */
+export const vimSlashCommands: SlashCommand[] = [vimCommand];

package/src/commands/workflow.ts

@@ -0,0 +1,257 @@
+/**
+ * Workflow Slash Commands (T035)
+ *
+ * Provides slash commands for workflow management:
+ * - /workflow - List available workflows
+ * - /workflow {name} - Inject workflow instructions
+ *
+ * Workflows are loaded from .vellum/workflows/*.md files.
+ *
+ * @module cli/commands/workflow
+ * @see REQ-011
+ */
+
+import { createWorkflowLoader, type Workflow, type WorkflowLoader } from "@vellum/core";
+import { ICONS } from "../utils/icons.js";
+import type { CommandContext, CommandResult, SlashCommand } from "./types.js";
+import { error, pending, success } from "./types.js";
+
+// =============================================================================
+// Module State
+// =============================================================================
+
+/**
+ * Cached WorkflowLoader instance.
+ * Initialized lazily on first use.
+ */
+let cachedLoader: WorkflowLoader | null = null;
+
+/**
+ * Last workspace path used to create the loader.
+ */
+let lastWorkspacePath: string | null = null;
+
+/**
+ * Get or create WorkflowLoader for the given workspace.
+ *
+ * @param cwd - Current working directory (workspace root)
+ * @returns WorkflowLoader instance
+ */
+function getLoader(cwd: string): WorkflowLoader {
+  // Create new loader if workspace changed
+  if (cachedLoader === null || lastWorkspacePath !== cwd) {
+    cachedLoader = createWorkflowLoader({ cwd });
+    lastWorkspacePath = cwd;
+  }
+  return cachedLoader;
+}
+
+/**
+ * Clear the cached loader (for testing).
+ */
+export function clearWorkflowLoaderCache(): void {
+  cachedLoader = null;
+  lastWorkspacePath = null;
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Format workflow list for display.
+ *
+ * @param workflows - Array of loaded workflows
+ * @returns Formatted string for TUI display
+ */
+function formatWorkflowList(workflows: Workflow[]): string {
+  if (workflows.length === 0) {
+    return `📂 No workflows found.
+
+Create workflows in .vellum/workflows/*.md with YAML frontmatter:
+
+\`\`\`yaml
+---
+id: deploy
+name: Deploy to Production
+description: Step-by-step deployment workflow
+steps:
+  - id: build
+    prompt: "Build the project for production"
+  - id: test
+    prompt: "Run all tests"
+  - id: deploy
+    prompt: "Deploy to production server"
+---
+\`\`\`
+
+Then run: /workflow deploy`;
+  }
+
+  const lines = [`${ICONS.workflow} Available Workflows:\n`];
+
+  for (const wf of workflows) {
+    const stepCount = wf.steps.length;
+    const source = wf.source === "project" ? "[project]" : "[user]";
+    lines.push(`  ${ICONS.bullet} ${wf.id} - ${wf.name || wf.description || "No description"}`);
+    lines.push(`    ${stepCount} step${stepCount !== 1 ? "s" : ""} ${source}\n`);
+  }
+
+  lines.push("\nUsage: /workflow <name> [--var=value ...]");
+
+  return lines.join("\n");
+}
+
+/**
+ * Format workflow instructions for injection.
+ *
+ * @param workflow - The workflow to format
+ * @param variables - Variable values for interpolation
+ * @returns Formatted workflow instructions
+ */
+function formatWorkflowInstructions(workflow: Workflow, variables: Record<string, string>): string {
+  const loader = getLoader(lastWorkspacePath ?? process.cwd());
+  return loader.getWorkflowInstructions(workflow, variables);
+}
+
+/**
+ * Parse variable arguments from command args.
+ * Format: --var=value or --var value
+ *
+ * @param args - Raw argument string
+ * @returns Parsed variables object
+ */
+function parseVariables(args: string): { name: string; variables: Record<string, string> } {
+  const parts = args.trim().split(/\s+/);
+  const name = parts[0] ?? "";
+  const variables: Record<string, string> = {};
+
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    if (part?.startsWith("--")) {
+      const eqIndex = part.indexOf("=");
+      if (eqIndex > 2) {
+        // --key=value format
+        const key = part.slice(2, eqIndex);
+        const value = part.slice(eqIndex + 1);
+        variables[key] = value;
+      } else {
+        const nextPart = parts[i + 1];
+        if (nextPart && !nextPart.startsWith("--")) {
+          // --key value format
+          const key = part.slice(2);
+          variables[key] = nextPart;
+          i++;
+        }
+      }
+    }
+  }
+
+  return { name, variables };
+}
+
+// =============================================================================
+// /workflow Command - List and Execute Workflows
+// =============================================================================
+
+/**
+ * /workflow command handler.
+ *
+ * Without arguments: Lists all available workflows
+ * With workflow name: Loads and injects workflow instructions
+ *
+ * @example
+ * ```
+ * /workflow          # List all workflows
+ * /workflow deploy   # Inject deploy workflow
+ * /workflow deploy --env=prod --branch=main
+ * ```
+ */
+async function executeWorkflow(ctx: CommandContext): Promise<CommandResult> {
+  const args = ctx.parsedArgs.raw.trim();
+  const loader = getLoader(ctx.session.cwd);
+
+  // No arguments - list workflows
+  if (!args) {
+    try {
+      const workflows = await loader.loadAll();
+      return success(formatWorkflowList(workflows));
+    } catch (err) {
+      return error(
+        "INTERNAL_ERROR",
+        `Failed to load workflows: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  // Parse workflow name and variables
+  const { name, variables } = parseVariables(args);
+
+  if (!name) {
+    return error(
+      "INVALID_ARGUMENT",
+      "Please specify a workflow name. Use /workflow to list available workflows."
+    );
+  }
+
+  try {
+    // Try to load the specific workflow
+    const workflow = await loader.load(name);
+
+    if (!workflow) {
+      // Workflow not found - show helpful message
+      const workflows = await loader.loadAll();
+      const names = workflows.map((w: Workflow) => w.id);
+      const suggestion =
+        names.length > 0
+          ? `\n\nAvailable workflows: ${names.join(", ")}`
+          : "\n\nNo workflows found. Create one in .vellum/workflows/";
+
+      return error("RESOURCE_NOT_FOUND", `Workflow "${name}" not found.${suggestion}`);
+    }
+
+    // Format workflow instructions for injection
+    const instructions = formatWorkflowInstructions(workflow, variables);
+
+    // Return pending result to inject instructions into context
+    return pending({
+      message: `${ICONS.workflow} Loading workflow: ${workflow.name || workflow.id}`,
+      promise: Promise.resolve(success(instructions)),
+    });
+  } catch (err) {
+    return error(
+      "INTERNAL_ERROR",
+      `Failed to load workflow "${name}": ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+/**
+ * /workflow slash command definition.
+ */
+export const workflowCommand: SlashCommand = {
+  name: "workflow",
+  description: "List or execute workflows from .vellum/workflows/",
+  kind: "builtin",
+  category: "workflow",
+  aliases: ["wf"],
+  positionalArgs: [
+    {
+      name: "name",
+      type: "string",
+      description: "Workflow name to execute (optional)",
+      required: false,
+    },
+  ],
+  subcommands: [
+    { name: "list", description: "List available workflows", aliases: ["ls"] },
+    { name: "run", description: "Run a workflow by name" },
+    { name: "validate", description: "Validate workflow file syntax" },
+  ],
+  execute: executeWorkflow,
+};
+
+/**
+ * All workflow-related slash commands.
+ */
+export const workflowCommands: SlashCommand[] = [workflowCommand];

package/src/components/header.tsx

@@ -0,0 +1,25 @@
+/**
+ * Header Component
+ * @module cli/components/header
+ */
+
+import { Box, Text } from "ink";
+import type { FC } from "react";
+
+export interface HeaderProps {
+  title?: string;
+  model?: string;
+  provider?: string;
+}
+
+export const Header: FC<HeaderProps> = ({ title = "Vellum", model, provider }) => {
+  return (
+    <Box borderStyle="single" paddingX={1}>
+      <Text bold color="blue">
+        {title}
+      </Text>
+      {model && <Text> | Model: {model}</Text>}
+      {provider && <Text> | Provider: {provider}</Text>}
+    </Box>
+  );
+};

package/src/components/input.tsx

@@ -0,0 +1,25 @@
+/**
+ * Input Component
+ * @module cli/components/input
+ */
+
+import { Box, Text } from "ink";
+import type { FC } from "react";
+
+export interface InputProps {
+  value?: string;
+  onChange?: (value: string) => void;
+  onSubmit?: (value: string) => void;
+  placeholder?: string;
+  disabled?: boolean;
+}
+
+export const Input: FC<InputProps> = ({ value = "", placeholder = ">" }) => {
+  return (
+    <Box>
+      <Text>
+        {placeholder} {value}
+      </Text>
+    </Box>
+  );
+};

package/src/components/message-list.tsx

@@ -0,0 +1,32 @@
+/**
+ * Message List Component
+ * @module cli/components/message-list
+ */
+
+import { Box, Text } from "ink";
+import type { FC } from "react";
+
+export interface Message {
+  role: "user" | "assistant";
+  content: string;
+}
+
+export interface MessageListProps {
+  messages?: Message[];
+}
+
+export const MessageList: FC<MessageListProps> = ({ messages = [] }) => {
+  return (
+    <Box flexDirection="column">
+      {messages.map((msg, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: Messages don't have stable IDs
+        <Box key={i} marginBottom={1}>
+          <Text color={msg.role === "user" ? "green" : "blue"}>
+            {msg.role === "user" ? "You: " : "Assistant: "}
+          </Text>
+          <Text>{msg.content}</Text>
+        </Box>
+      ))}
+    </Box>
+  );
+};

package/src/components/status-bar.tsx

@@ -0,0 +1,23 @@
+/**
+ * Status Bar Component
+ * @module cli/components/status-bar
+ */
+
+import { Box, Text } from "ink";
+import type { FC } from "react";
+
+export interface StatusBarProps {
+  status?: string;
+  model?: string;
+  tokens?: number;
+}
+
+export const StatusBar: FC<StatusBarProps> = ({ status = "Ready", model, tokens }) => {
+  return (
+    <Box borderStyle="single" paddingX={1}>
+      <Text color="gray">{status}</Text>
+      {model && <Text> | {model}</Text>}
+      {tokens !== undefined && <Text> | Tokens: {tokens}</Text>}
+    </Box>
+  );
+};