@butlerw/vellum 0.1.0

package/src/commands/core/help.ts

@@ -0,0 +1,354 @@
+/**
+ * Help Command
+ *
+ * Displays help information for commands and categories.
+ *
+ * @module cli/commands/core/help
+ */
+
+import type { CommandRegistry } from "../registry.js";
+import type { CommandCategory, CommandContext, CommandResult, SlashCommand } from "../types.js";
+import { error, success } from "../types.js";
+
+// =============================================================================
+// Category Display Names
+// =============================================================================
+
+/**
+ * Human-readable names for command categories
+ */
+const CATEGORY_NAMES: Record<CommandCategory, string> = {
+  system: "System",
+  workflow: "Workflow",
+  auth: "Authentication",
+  session: "Session",
+  navigation: "Navigation",
+  tools: "Tools",
+  config: "Configuration",
+  debug: "Debug",
+};
+
+/**
+ * Category display order
+ */
+const CATEGORY_ORDER: CommandCategory[] = [
+  "system",
+  "workflow",
+  "session",
+  "config",
+  "auth",
+  "tools",
+  "debug",
+];
+
+// =============================================================================
+// Help Formatter
+// =============================================================================
+
+/**
+ * Format command list grouped by category
+ */
+function formatCommandList(registry: CommandRegistry): string {
+  const lines: string[] = [];
+  lines.push("📚 Available Commands\n");
+
+  for (const category of CATEGORY_ORDER) {
+    const commands = registry.getByCategory(category);
+    if (commands.size === 0) continue;
+
+    lines.push(`\n${CATEGORY_NAMES[category]}:`);
+
+    // Sort commands alphabetically
+    const sortedCmds = Array.from(commands).sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const cmd of sortedCmds) {
+      const aliases = cmd.aliases?.length ? ` (${cmd.aliases.join(", ")})` : "";
+      lines.push(`  /${cmd.name}${aliases} - ${cmd.description}`);
+    }
+  }
+
+  // Add shell mode hint
+  lines.push("\n\n💡 Quick Tips:");
+  lines.push("  • Type !<command> to execute shell commands directly (e.g., !ls, !git status)");
+  lines.push("  • Use @file to mention files in your prompt");
+  lines.push("  • Press Tab for autocomplete");
+
+  lines.push("\nUse /help <command> for detailed help on a specific command.");
+  return lines.join("\n");
+}
+
+/**
+ * Format positional arguments section
+ */
+function formatPositionalArgs(args: readonly import("../types.js").PositionalArg[]): string[] {
+  const lines: string[] = ["Arguments:"];
+  for (const arg of args) {
+    const required = arg.required ? "(required)" : "(optional)";
+    const defaultVal = arg.default !== undefined ? ` [default: ${arg.default}]` : "";
+    lines.push(`  <${arg.name}> ${required}${defaultVal}`);
+    lines.push(`    ${arg.description}`);
+  }
+  lines.push("");
+  return lines;
+}
+
+/**
+ * Format named arguments (flags) section
+ */
+function formatNamedArgs(args: readonly import("../types.js").NamedArg[]): string[] {
+  const lines: string[] = ["Options:"];
+  for (const arg of args) {
+    const short = arg.shorthand ? `-${arg.shorthand}, ` : "    ";
+    const required = arg.required ? "(required)" : "";
+    const defaultVal = arg.default !== undefined ? ` [default: ${arg.default}]` : "";
+    lines.push(`  ${short}--${arg.name} ${required}${defaultVal}`);
+    lines.push(`    ${arg.description}`);
+  }
+  lines.push("");
+  return lines;
+}
+
+/**
+ * Format detailed help for a single command
+ */
+function formatCommandHelp(cmd: SlashCommand): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`📖 /${cmd.name}`);
+  lines.push(`   ${cmd.description}\n`);
+
+  // Aliases
+  if (cmd.aliases?.length) {
+    lines.push(`Aliases: ${cmd.aliases.map((a) => `/${a}`).join(", ")}`);
+  }
+
+  // Category and Kind
+  lines.push(`Category: ${CATEGORY_NAMES[cmd.category]}`);
+  lines.push(`Kind: ${cmd.kind}\n`);
+
+  // Usage
+  const usage = buildUsage(cmd);
+  lines.push(`Usage: ${usage}\n`);
+
+  // Positional arguments
+  if (cmd.positionalArgs?.length) {
+    lines.push(...formatPositionalArgs(cmd.positionalArgs));
+  }
+
+  // Named arguments (flags)
+  if (cmd.namedArgs?.length) {
+    lines.push(...formatNamedArgs(cmd.namedArgs));
+  }
+
+  // Examples
+  if (cmd.examples?.length) {
+    lines.push("Examples:");
+    for (const example of cmd.examples) {
+      lines.push(`  ${example}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format help for a category
+ */
+function formatCategoryHelp(category: CommandCategory, registry: CommandRegistry): string {
+  const commands = registry.getByCategory(category);
+  const lines: string[] = [];
+
+  lines.push(`📂 ${CATEGORY_NAMES[category]} Commands\n`);
+
+  if (commands.size === 0) {
+    lines.push("  No commands in this category.");
+    return lines.join("\n");
+  }
+
+  const sortedCmds = Array.from(commands).sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const cmd of sortedCmds) {
+    const aliases = cmd.aliases?.length ? ` (${cmd.aliases.join(", ")})` : "";
+    lines.push(`  /${cmd.name}${aliases}`);
+    lines.push(`    ${cmd.description}`);
+  }
+
+  lines.push("\n\nUse /help <command> for detailed help on a specific command.");
+  return lines.join("\n");
+}
+
+/**
+ * Build usage string for a command
+ */
+function buildUsage(cmd: SlashCommand): string {
+  const parts: string[] = [`/${cmd.name}`];
+
+  // Add positional args
+  if (cmd.positionalArgs) {
+    for (const arg of cmd.positionalArgs) {
+      if (arg.required) {
+        parts.push(`<${arg.name}>`);
+      } else {
+        parts.push(`[${arg.name}]`);
+      }
+    }
+  }
+
+  // Add named args hint
+  if (cmd.namedArgs?.length) {
+    parts.push("[options]");
+  }
+
+  return parts.join(" ");
+}
+
+/**
+ * Check if a string is a valid category
+ */
+function isCategory(topic: string): topic is CommandCategory {
+  return CATEGORY_ORDER.includes(topic as CommandCategory);
+}
+
+// =============================================================================
+// T027: Help Command Definition
+// =============================================================================
+
+/**
+ * Provides access to command registry for help command
+ *
+ * This must be set before using the help command.
+ * Typically set during application initialization.
+ */
+let registryRef: CommandRegistry | null = null;
+
+/**
+ * Set the command registry reference for help command
+ */
+export function setHelpRegistry(registry: CommandRegistry): void {
+  registryRef = registry;
+}
+
+/**
+ * Get the command registry reference
+ */
+export function getHelpRegistry(): CommandRegistry | null {
+  return registryRef;
+}
+
+/**
+ * Get dynamic subcommands for help based on registered commands.
+ * Returns subcommands for all registered commands plus category names.
+ */
+export function getHelpSubcommands(): import("../types.js").SubcommandDef[] {
+  const subcommands: import("../types.js").SubcommandDef[] = [];
+
+  // Add category names as subcommands
+  for (const category of CATEGORY_ORDER) {
+    subcommands.push({
+      name: category,
+      description: `Show ${CATEGORY_NAMES[category]} commands`,
+    });
+  }
+
+  // Add registered commands as subcommands (if registry is available)
+  if (registryRef) {
+    const allCommands = registryRef.list();
+    for (const cmd of allCommands) {
+      // Skip if already added (category name conflict)
+      if (!subcommands.some((s) => s.name === cmd.name)) {
+        subcommands.push({
+          name: cmd.name,
+          description: cmd.description,
+          aliases: cmd.aliases ? [...cmd.aliases] : undefined,
+        });
+      }
+    }
+  }
+
+  return subcommands;
+}
+
+/**
+ * Help command - displays help information
+ *
+ * Usage:
+ * - /help - Display all commands grouped by category
+ * - /help <command> - Display detailed help for a command
+ * - /help <category> - Display commands in a category
+ */
+export const helpCommand: SlashCommand = {
+  name: "help",
+  description: "Display help information for commands and categories",
+  kind: "builtin",
+  category: "system",
+  aliases: ["h", "?"],
+  positionalArgs: [
+    {
+      name: "topic",
+      type: "string",
+      description: "Command name or category to get help for",
+      required: false,
+    },
+  ],
+  examples: [
+    "/help              - Show all commands",
+    "/help auth         - Help for auth command",
+    "/help system       - Show system category commands",
+  ],
+  // Subcommands are generated dynamically via getHelpSubcommands()
+  // The autocomplete system should call getHelpSubcommands() for fresh data
+  subcommands: CATEGORY_ORDER.map((category) => ({
+    name: category,
+    description: `Show ${CATEGORY_NAMES[category]} commands`,
+  })),
+
+  execute: async (ctx: CommandContext): Promise<CommandResult> => {
+    const topic = ctx.parsedArgs.positional[0] as string | undefined;
+
+    // Get registry from the reference
+    const registry = registryRef;
+    if (!registry) {
+      return error(
+        "INTERNAL_ERROR",
+        "Command registry not initialized. This is a configuration error."
+      );
+    }
+
+    // No topic: show all commands
+    if (!topic) {
+      const message = formatCommandList(registry);
+      return success(message, { type: "help-list", categories: CATEGORY_ORDER });
+    }
+
+    // Check if topic is a category
+    if (isCategory(topic)) {
+      const message = formatCategoryHelp(topic, registry);
+      return success(message, { type: "help-category", category: topic });
+    }
+
+    // Try to find command by name or alias
+    const cmd = registry.get(topic);
+    if (cmd) {
+      const message = formatCommandHelp(cmd);
+      return success(message, { type: "help-command", command: cmd.name });
+    }
+
+    // Command not found - try fuzzy search for suggestions
+    const allCommands = registry.list();
+    const suggestions = allCommands
+      .filter(
+        (c) =>
+          c.name.toLowerCase().includes(topic.toLowerCase()) ||
+          c.aliases?.some((a) => a.toLowerCase().includes(topic.toLowerCase()))
+      )
+      .map((c) => `/${c.name}`)
+      .slice(0, 3);
+
+    return error(
+      "COMMAND_NOT_FOUND",
+      `Unknown command or category: "${topic}"`,
+      suggestions.length > 0 ? suggestions : undefined
+    );
+  },
+};

package/src/commands/core/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Core Commands Barrel Export
+ *
+ * Exports all core builtin commands for the command system.
+ *
+ * @module cli/commands/core
+ */
+
+// =============================================================================
+// T030: Core Commands Exports
+// =============================================================================
+
+export { clearCommand } from "./clear.js";
+export { exitCommand } from "./exit.js";
+export { getHelpRegistry, getHelpSubcommands, helpCommand, setHelpRegistry } from "./help.js";

package/src/commands/cost.ts

@@ -0,0 +1,179 @@
+/**
+ * Cost Slash Command (Phase 35)
+ *
+ * Provides the /cost command for displaying session cost information.
+ *
+ * @module cli/commands/cost
+ */
+
+import type { CostService, ModelUsage, ProviderUsage } from "@vellum/core";
+import { formatCost, formatCostBreakdown, formatTokenCount } from "@vellum/core";
+import type { CommandContext, CommandResult, SlashCommand } from "./types.js";
+import { error, success } from "./types.js";
+
+// =============================================================================
+// Module State
+// =============================================================================
+
+/**
+ * Reference to the active CostService instance.
+ * Set by the App component when initialized.
+ */
+let costService: CostService | null = null;
+
+/**
+ * Set the CostService instance for cost commands.
+ * Called by the App component during initialization.
+ *
+ * @param service - The CostService instance to use
+ */
+export function setCostCommandsService(service: CostService | null): void {
+  costService = service;
+}
+
+/**
+ * Get the current CostService instance.
+ * Returns null if not yet initialized.
+ */
+export function getCostCommandsService(): CostService | null {
+  return costService;
+}
+
+// =============================================================================
+// /cost Command
+// =============================================================================
+
+/**
+ * /cost command - Display session cost information.
+ *
+ * Shows current session's token usage and cost breakdown.
+ * Without a CostService, shows a placeholder indicating
+ * cost tracking is not initialized.
+ */
+export const costCommand: SlashCommand = {
+  name: "cost",
+  description: "Show session cost breakdown",
+  kind: "builtin",
+  category: "system",
+  aliases: ["costs", "usage"],
+  positionalArgs: [
+    {
+      name: "format",
+      type: "string",
+      description: "Output format: brief, full, json",
+      required: false,
+    },
+  ],
+  examples: [
+    "/cost         - Show brief cost summary",
+    "/cost full    - Show detailed breakdown",
+    "/cost json    - Output as JSON",
+  ],
+
+  execute: async (ctx: CommandContext): Promise<CommandResult> => {
+    const format = (ctx.parsedArgs.positional[0] as string | undefined) ?? "brief";
+
+    if (!costService) {
+      return error("RESOURCE_NOT_FOUND", "Cost tracking not initialized. Start a session first.");
+    }
+
+    const sessionCost = costService.getSessionCost();
+    const inputTokens = costService.totalInputTokens;
+    const outputTokens = costService.totalOutputTokens;
+    const requestCount = costService.requestCount;
+
+    // JSON output
+    if (format === "json") {
+      const summary = costService.getSessionSummary();
+      return success(JSON.stringify(summary, null, 2));
+    }
+
+    // Brief output (default)
+    if (format === "brief" || format !== "full") {
+      const totalTokens = inputTokens + outputTokens;
+      const lines = [
+        "💰 Session Cost",
+        "",
+        `  Requests: ${requestCount}`,
+        `  Tokens:   ${formatTokenCount(totalTokens)} (${formatTokenCount(inputTokens)} in / ${formatTokenCount(outputTokens)} out)`,
+        `  Cost:     ${formatCost(sessionCost.total)}`,
+        "",
+        "Use /cost full for detailed breakdown.",
+      ];
+      return success(lines.join("\n"));
+    }
+
+    // Full output
+    const summary = costService.getSessionSummary();
+    const lines = [
+      "💰 Session Cost Details",
+      "",
+      "─── Token Usage ───",
+      `  Input:     ${formatTokenCount(inputTokens)}`,
+      `  Output:    ${formatTokenCount(outputTokens)}`,
+    ];
+
+    if (summary.totalCacheReadTokens > 0) {
+      lines.push(`  Cache (R): ${formatTokenCount(summary.totalCacheReadTokens)}`);
+    }
+    if (summary.totalCacheWriteTokens > 0) {
+      lines.push(`  Cache (W): ${formatTokenCount(summary.totalCacheWriteTokens)}`);
+    }
+    if (summary.totalReasoningTokens > 0) {
+      lines.push(`  Reasoning: ${formatTokenCount(summary.totalReasoningTokens)}`);
+    }
+
+    lines.push("");
+    lines.push("─── Cost Breakdown ───");
+    lines.push(formatCostBreakdown(sessionCost));
+
+    // By provider
+    const providers = Object.entries(summary.byProvider) as [string, ProviderUsage][];
+    if (providers.length > 0) {
+      lines.push("");
+      lines.push("─── By Provider ───");
+      for (const [provider, usage] of providers) {
+        lines.push(`  ${provider}: ${formatCost(usage.cost)} (${usage.requests} requests)`);
+      }
+    }
+
+    // By model
+    const models = Object.entries(summary.byModel) as [string, ModelUsage][];
+    if (models.length > 0) {
+      lines.push("");
+      lines.push("─── By Model ───");
+      for (const [model, usage] of models) {
+        lines.push(`  ${model}: ${formatCost(usage.cost)} (${usage.requests} requests)`);
+      }
+    }
+
+    return success(lines.join("\n"));
+  },
+};
+
+/**
+ * /cost reset command - Reset session cost tracking.
+ */
+export const costResetCommand: SlashCommand = {
+  name: "cost-reset",
+  description: "Reset session cost tracking",
+  kind: "builtin",
+  category: "system",
+  aliases: ["reset-cost"],
+  examples: ["/cost-reset  - Clear session cost data"],
+
+  execute: async (_ctx: CommandContext): Promise<CommandResult> => {
+    if (!costService) {
+      return error("RESOURCE_NOT_FOUND", "Cost tracking not initialized.");
+    }
+
+    costService.reset();
+    return success("✅ Session cost tracking reset.");
+  },
+};
+
+// =============================================================================
+// Export
+// =============================================================================
+
+export default costCommand;