@butlerw/vellum 0.1.0

package/src/commands/update.ts

@@ -0,0 +1,274 @@
+/**
+ * Update Command (Phase 39)
+ *
+ * CLI command for checking and performing updates to the Vellum CLI.
+ *
+ * Usage:
+ * - `vellum update` - Check and update if available
+ * - `vellum update --check` - Only check, don't update
+ * - `vellum update --force` - Skip confirmation prompts
+ *
+ * @module cli/commands/update
+ */
+
+import { confirm } from "@inquirer/prompts";
+import {
+  checkForUpdates,
+  detectPackageManager,
+  type PackageManager,
+  performUpdate,
+  type UpdateOptions,
+  type VersionCheckResult,
+} from "@vellum/core";
+import chalk from "chalk";
+
+import { ICONS } from "../utils/icons.js";
+import { EXIT_CODES } from "./exit-codes.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Update command options
+ */
+export interface UpdateCommandOptions {
+  /** Only check for updates, don't install */
+  check?: boolean;
+  /** Skip confirmation prompts */
+  force?: boolean;
+  /** Target version to update to */
+  version?: string;
+  /** Package manager to use */
+  packageManager?: PackageManager;
+  /** Dry-run mode (no actual update) */
+  dryRun?: boolean;
+}
+
+/**
+ * Update command result
+ */
+export interface UpdateCommandResult {
+  /** Whether the command succeeded */
+  success: boolean;
+  /** Exit code */
+  exitCode: number;
+  /** Message to display */
+  message: string;
+  /** Whether an update was available */
+  updateAvailable?: boolean;
+  /** Whether an update was performed */
+  updatePerformed?: boolean;
+  /** New version installed */
+  newVersion?: string;
+}
+
+// =============================================================================
+// Output Helpers
+// =============================================================================
+
+/**
+ * Format version check result for display
+ */
+function formatCheckResult(result: VersionCheckResult): string {
+  if (!result.success || !result.updateInfo) {
+    return chalk.red(`✗ Failed to check for updates: ${result.error ?? "Unknown error"}`);
+  }
+
+  const info = result.updateInfo;
+
+  if (!info.hasUpdate) {
+    return chalk.green(`✓ You're up to date! (v${info.currentVersion})`);
+  }
+
+  const lines = [
+    chalk.yellow(`⬆ Update available: v${info.currentVersion} → v${info.latestVersion}`),
+    "",
+    chalk.dim(`  Channel: ${info.channel}`),
+  ];
+
+  if (info.releaseDate) {
+    lines.push(chalk.dim(`  Released: ${new Date(info.releaseDate).toLocaleDateString()}`));
+  }
+
+  if (info.releaseNotesUrl) {
+    lines.push(chalk.dim(`  Release notes: ${info.releaseNotesUrl}`));
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Display update progress spinner
+ */
+function displayProgress(pm: PackageManager, version: string): void {
+  console.log(chalk.blue(`\n⟳ Updating to v${version} using ${pm}...\n`));
+}
+
+// =============================================================================
+// Command Implementation
+// =============================================================================
+
+/**
+ * Execute the update command
+ *
+ * @param currentVersion - Current installed version
+ * @param options - Command options
+ * @returns Command result
+ */
+export async function executeUpdateCommand(
+  currentVersion: string,
+  options: UpdateCommandOptions = {}
+): Promise<UpdateCommandResult> {
+  // Step 1: Check for updates
+  console.log(chalk.blue("⟳ Checking for updates...\n"));
+
+  const checkResult = await checkForUpdates(currentVersion);
+
+  // Display check result
+  console.log(formatCheckResult(checkResult));
+  console.log("");
+
+  // If check failed, exit with error
+  if (!checkResult.success) {
+    return {
+      success: false,
+      exitCode: EXIT_CODES.ERROR,
+      message: checkResult.error ?? "Failed to check for updates",
+      updateAvailable: false,
+    };
+  }
+
+  // updateInfo is guaranteed to exist because we checked success above
+  const info = checkResult.updateInfo;
+  if (!info) {
+    return {
+      success: false,
+      exitCode: EXIT_CODES.ERROR,
+      message: "Failed to get update info",
+      updateAvailable: false,
+    };
+  }
+
+  // If no update available, we're done
+  if (!info.hasUpdate) {
+    return {
+      success: true,
+      exitCode: EXIT_CODES.SUCCESS,
+      message: "Already up to date",
+      updateAvailable: false,
+    };
+  }
+
+  // If --check flag, just report and exit
+  if (options.check) {
+    return {
+      success: true,
+      exitCode: EXIT_CODES.SUCCESS,
+      message: `Update available: v${info.latestVersion}`,
+      updateAvailable: true,
+      updatePerformed: false,
+    };
+  }
+
+  // Confirm update unless --force
+  if (!options.force && !options.dryRun) {
+    const shouldUpdate = await confirm({
+      message: `Update to v${options.version ?? info.latestVersion}?`,
+      default: true,
+    });
+
+    if (!shouldUpdate) {
+      console.log(chalk.dim("\nUpdate cancelled."));
+      return {
+        success: true,
+        exitCode: EXIT_CODES.SUCCESS,
+        message: "Update cancelled by user",
+        updateAvailable: true,
+        updatePerformed: false,
+      };
+    }
+  }
+
+  // Step 2: Perform update
+  const pm = options.packageManager ?? detectPackageManager();
+  const targetVersion = options.version ?? info.latestVersion;
+
+  displayProgress(pm, targetVersion);
+
+  const updateOptions: UpdateOptions = {
+    targetVersion,
+    packageManager: pm,
+    global: true,
+    dryRun: options.dryRun,
+  };
+
+  const updateResult = await performUpdate(currentVersion, updateOptions);
+
+  if (!updateResult.success) {
+    console.log(chalk.red(`\n✗ Update failed: ${updateResult.error}`));
+    console.log(chalk.dim("\nYou can try updating manually:"));
+    console.log(chalk.dim(`  ${pm} install -g @vellum/cli@${targetVersion}`));
+
+    return {
+      success: false,
+      exitCode: EXIT_CODES.ERROR,
+      message: updateResult.error ?? "Update failed",
+      updateAvailable: true,
+      updatePerformed: false,
+    };
+  }
+
+  // Success
+  if (options.dryRun) {
+    console.log(chalk.green(`✓ [Dry run] Would update to v${targetVersion}`));
+  } else {
+    console.log(chalk.green(`✓ Successfully updated to v${targetVersion}`));
+
+    if (updateResult.requiresRestart) {
+      console.log(
+        chalk.yellow(`\n${ICONS.warning} Please restart your terminal to use the new version.`)
+      );
+    }
+  }
+
+  return {
+    success: true,
+    exitCode: EXIT_CODES.SUCCESS,
+    message: `Updated to v${targetVersion}`,
+    updateAvailable: true,
+    updatePerformed: !options.dryRun,
+    newVersion: targetVersion,
+  };
+}
+
+// =============================================================================
+// Startup Check
+// =============================================================================
+
+/**
+ * Check for updates on startup (silent, non-blocking)
+ * Returns update info if available, null otherwise
+ *
+ * @param currentVersion - Current installed version
+ * @returns Update info if update available
+ */
+export async function checkUpdateOnStartup(
+  currentVersion: string
+): Promise<{ latestVersion: string; releaseNotesUrl?: string } | null> {
+  try {
+    const result = await checkForUpdates(currentVersion);
+
+    if (result.success && result.updateInfo?.hasUpdate) {
+      return {
+        latestVersion: result.updateInfo.latestVersion,
+        releaseNotesUrl: result.updateInfo.releaseNotesUrl,
+      };
+    }
+
+    return null;
+  } catch {
+    // Silently fail on startup check
+    return null;
+  }
+}

package/src/commands/usage.ts

@@ -0,0 +1,213 @@
+/**
+ * Usage Command
+ *
+ * Display detailed token usage and cost breakdown for the current session.
+ * Inspired by Aider's /tokens command.
+ *
+ * Usage:
+ * - /usage - Show session token breakdown and costs
+ * - /usage json - Output as JSON
+ *
+ * @module cli/commands/usage
+ */
+
+import { formatCost, formatTokenCount } from "@vellum/core";
+import { getCostCommandsService } from "./cost.js";
+import type { CommandContext, CommandResult, SlashCommand } from "./types.js";
+import { error, success } from "./types.js";
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Calculate estimated cost for tokens.
+ */
+function estimateCost(tokens: number, pricePerMillion: number): number {
+  return (tokens / 1_000_000) * pricePerMillion;
+}
+
+/**
+ * Format a visual bar for percentage.
+ */
+function formatBar(percentage: number, width = 20): string {
+  const filled = Math.round((percentage / 100) * width);
+  const empty = width - filled;
+  return "▓".repeat(filled) + "░".repeat(empty);
+}
+
+// =============================================================================
+// Command Definition
+// =============================================================================
+
+/**
+ * /usage command - Display token usage and cost breakdown.
+ *
+ * Shows detailed breakdown of:
+ * - System prompt tokens
+ * - Conversation history tokens
+ * - File context tokens
+ * - Current turn tokens
+ * - Estimated costs
+ */
+export const usageCommand: SlashCommand = {
+  name: "usage",
+  description: "Show detailed token usage and cost breakdown",
+  kind: "builtin",
+  category: "system",
+  aliases: ["tokens", "u"],
+  positionalArgs: [
+    {
+      name: "format",
+      type: "string",
+      description: "Output format: default, json",
+      required: false,
+    },
+  ],
+  examples: [
+    "/usage       - Show token breakdown",
+    "/tokens      - Alias for /usage",
+    "/usage json  - Output as JSON",
+  ],
+
+  execute: async (ctx: CommandContext): Promise<CommandResult> => {
+    const format = (ctx.parsedArgs.positional[0] as string | undefined) ?? "default";
+    const costService = getCostCommandsService();
+
+    if (!costService) {
+      return error(
+        "RESOURCE_NOT_FOUND",
+        "Usage tracking not available. Start a conversation first.",
+        ["/cost - Alternative command for basic cost info"]
+      );
+    }
+
+    const summary = costService.getSessionSummary();
+    const sessionCost = costService.getSessionCost();
+
+    // JSON format
+    if (format === "json") {
+      const data = {
+        session: {
+          requests: summary.totalRequests,
+          inputTokens: summary.totalInputTokens,
+          outputTokens: summary.totalOutputTokens,
+          cacheReadTokens: summary.totalCacheReadTokens,
+          cacheWriteTokens: summary.totalCacheWriteTokens,
+          reasoningTokens: summary.totalReasoningTokens,
+          totalTokens: summary.totalInputTokens + summary.totalOutputTokens,
+        },
+        cost: {
+          input: sessionCost.input,
+          output: sessionCost.output,
+          cacheRead: sessionCost.cacheRead,
+          cacheWrite: sessionCost.cacheWrite,
+          reasoning: sessionCost.reasoning,
+          total: sessionCost.total,
+        },
+        byProvider: summary.byProvider,
+        byModel: summary.byModel,
+      };
+      return success(JSON.stringify(data, null, 2));
+    }
+
+    // Default formatted output
+    const totalTokens = summary.totalInputTokens + summary.totalOutputTokens;
+    const lines: string[] = [];
+
+    lines.push("📊 Token Usage Breakdown");
+    lines.push("");
+
+    // Token counts with visual bars
+    lines.push("─── Tokens ───");
+    const maxTokens = Math.max(summary.totalInputTokens, summary.totalOutputTokens, 1);
+
+    const inputPct = Math.round((summary.totalInputTokens / maxTokens) * 100);
+    const outputPct = Math.round((summary.totalOutputTokens / maxTokens) * 100);
+
+    lines.push(
+      `  Input:    ${formatBar(inputPct, 15)} ${formatTokenCount(summary.totalInputTokens)}`
+    );
+    lines.push(
+      `  Output:   ${formatBar(outputPct, 15)} ${formatTokenCount(summary.totalOutputTokens)}`
+    );
+
+    if (summary.totalCacheReadTokens > 0) {
+      const cachePct = Math.round((summary.totalCacheReadTokens / maxTokens) * 100);
+      lines.push(
+        `  Cache(R): ${formatBar(cachePct, 15)} ${formatTokenCount(summary.totalCacheReadTokens)}`
+      );
+    }
+    if (summary.totalCacheWriteTokens > 0) {
+      const cachePct = Math.round((summary.totalCacheWriteTokens / maxTokens) * 100);
+      lines.push(
+        `  Cache(W): ${formatBar(cachePct, 15)} ${formatTokenCount(summary.totalCacheWriteTokens)}`
+      );
+    }
+    if (summary.totalReasoningTokens > 0) {
+      const reasonPct = Math.round((summary.totalReasoningTokens / maxTokens) * 100);
+      lines.push(
+        `  Reason:   ${formatBar(reasonPct, 15)} ${formatTokenCount(summary.totalReasoningTokens)}`
+      );
+    }
+
+    lines.push(`  ─────────────────────────────────`);
+    lines.push(`  Total:    ${" ".repeat(15)} ${formatTokenCount(totalTokens)}`);
+    lines.push("");
+
+    // Cost breakdown
+    lines.push("─── Cost Breakdown ───");
+    if (sessionCost.input > 0) {
+      lines.push(`  Input:    ${formatCost(sessionCost.input)}`);
+    }
+    if (sessionCost.output > 0) {
+      lines.push(`  Output:   ${formatCost(sessionCost.output)}`);
+    }
+    if (sessionCost.cacheRead > 0) {
+      lines.push(`  Cache(R): ${formatCost(sessionCost.cacheRead)} (90% savings)`);
+    }
+    if (sessionCost.cacheWrite > 0) {
+      lines.push(`  Cache(W): ${formatCost(sessionCost.cacheWrite)}`);
+    }
+    if (sessionCost.reasoning > 0) {
+      lines.push(`  Reason:   ${formatCost(sessionCost.reasoning)}`);
+    }
+    lines.push(`  ─────────────────────────────────`);
+    lines.push(`  Total:    ${formatCost(sessionCost.total)}`);
+    lines.push("");
+
+    // By model (if multiple)
+    const models = Object.entries(summary.byModel);
+    if (models.length > 1) {
+      lines.push("─── By Model ───");
+      for (const [model, usage] of models) {
+        const modelTokens = usage.inputTokens + usage.outputTokens;
+        lines.push(
+          `  ${model}: ${formatTokenCount(modelTokens)} (${formatCost(usage.cost)}) - ${usage.requests} req`
+        );
+      }
+      lines.push("");
+    }
+
+    // Session stats
+    lines.push("─── Session Stats ───");
+    lines.push(`  Requests: ${summary.totalRequests}`);
+
+    // Cost efficiency tip
+    if (summary.totalCacheReadTokens > 0) {
+      const savedCost = estimateCost(summary.totalCacheReadTokens, 2.7); // ~90% savings
+      lines.push(`  Cache savings: ~${formatCost(savedCost)}`);
+    }
+
+    lines.push("");
+    lines.push("💡 Tip: Use /cost for a quick summary, /usage for detailed breakdown");
+
+    return success(lines.join("\n"), {
+      totalTokens,
+      cost: sessionCost.total,
+      requests: summary.totalRequests,
+    });
+  },
+};
+
+export default usageCommand;