@butlerw/vellum 0.1.0

package/src/commands/onboard.ts

@@ -0,0 +1,205 @@
+/**
+ * Onboard Command (Phase 38)
+ *
+ * CLI command to run or restart the onboarding wizard.
+ * Can be invoked as `vellum onboard` or `/onboard` slash command.
+ *
+ * @module cli/commands/onboard
+ */
+
+import { EXIT_CODES } from "./exit-codes.js";
+import type { CommandContext, CommandResult, SlashCommand } from "./types.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Onboard command options
+ */
+export interface OnboardOptions {
+  /** Force restart even if already completed */
+  force?: boolean;
+  /** Skip to specific step */
+  step?: string;
+  /** Non-interactive mode */
+  nonInteractive?: boolean;
+}
+
+/**
+ * Onboard command result
+ */
+export interface OnboardResult {
+  /** Whether onboarding completed successfully */
+  success: boolean;
+  /** Selected provider */
+  provider?: string;
+  /** Selected mode */
+  mode?: string;
+  /** Whether credentials were configured */
+  credentialsConfigured: boolean;
+  /** Error message if failed */
+  error?: string;
+  /** Exit code */
+  exitCode: number;
+}
+
+// =============================================================================
+// Slash Command Definition
+// =============================================================================
+
+/**
+ * Onboard slash command definition
+ */
+export const onboardCommand: SlashCommand = {
+  name: "onboard",
+  aliases: ["setup", "wizard"],
+  description: "Run the onboarding wizard to configure Vellum",
+  category: "session",
+  kind: "builtin",
+  positionalArgs: [
+    {
+      name: "force",
+      type: "boolean",
+      description: "Force restart even if already completed",
+      required: false,
+    },
+  ],
+  namedArgs: [
+    {
+      name: "step",
+      type: "string",
+      description:
+        "Skip to specific step (welcome, provider-select, credential-setup, mode-select)",
+      required: false,
+    },
+  ],
+  subcommands: [
+    { name: "welcome", description: "Show welcome screen" },
+    { name: "provider", description: "Configure LLM provider", aliases: ["provider-select"] },
+    { name: "credential", description: "Setup API credentials", aliases: ["credential-setup"] },
+    { name: "mode", description: "Choose default mode", aliases: ["mode-select"] },
+  ],
+  examples: [
+    "/onboard - Run onboarding wizard",
+    "/onboard --force - Restart onboarding from beginning",
+    "/onboard --step provider-select - Jump to provider selection",
+  ],
+  execute: async (context: CommandContext): Promise<CommandResult> => {
+    const { parsedArgs } = context;
+    const force = parsedArgs.positional[0] === "true" || parsedArgs.named.force === "true";
+    const stepArg = parsedArgs.named.step as string | undefined;
+
+    // Import dynamically to avoid circular dependencies
+    const { OnboardingWizard, shouldRunOnboarding, ONBOARDING_STEPS } = await import(
+      "@vellum/core"
+    );
+
+    // Check if onboarding needed
+    const needsOnboarding = await shouldRunOnboarding();
+
+    if (!needsOnboarding && !force) {
+      return {
+        kind: "success",
+        message: "✅ Onboarding already completed. Use --force to restart.",
+      };
+    }
+
+    // Create wizard with force option
+    const wizard = new OnboardingWizard({ force });
+    await wizard.loadState();
+
+    // Jump to specific step if requested
+    if (stepArg) {
+      const validSteps = ONBOARDING_STEPS as readonly string[];
+      if (!validSteps.includes(stepArg)) {
+        return {
+          kind: "error",
+          code: "INVALID_ARGUMENT",
+          message: `Invalid step: ${stepArg}. Valid steps: ${validSteps.join(", ")}`,
+        };
+      }
+      await wizard.goToStep(
+        stepArg as "welcome" | "provider-select" | "credential-setup" | "mode-select" | "complete"
+      );
+    }
+
+    // Return interactive prompt that triggers wizard
+    return {
+      kind: "interactive",
+      prompt: {
+        inputType: "text",
+        message: `🚀 Starting Vellum Setup Wizard\n\nThis will guide you through:\n• Provider selection (Anthropic, OpenAI, etc.)\n• API key configuration\n• Default mode selection\n\nPress Enter to continue or type 'skip' to exit.`,
+        placeholder: "",
+        defaultValue: "",
+        handler: async (value: string): Promise<CommandResult> => {
+          if (value.toLowerCase() === "skip") {
+            return {
+              kind: "success",
+              message: "Onboarding skipped. Run /onboard when ready.",
+            };
+          }
+
+          // Run welcome step
+          await wizard.executeWelcome();
+
+          return {
+            kind: "success",
+            message: `✅ Welcome complete!\n\nCurrent step: ${wizard.getCurrentStep()}\n\nFor the full wizard experience, use the TUI or run:\n• /provider - Select AI provider\n• /credentials - Configure API keys\n• /mode - Set default mode`,
+          };
+        },
+        onCancel: () => ({
+          kind: "success",
+          message: "Onboarding cancelled. Run /onboard when ready.",
+        }),
+      },
+    };
+  },
+};
+
+// =============================================================================
+// CLI Entry Point
+// =============================================================================
+
+/**
+ * Run onboard command from CLI (non-TUI mode)
+ */
+export async function runOnboardCommand(options: OnboardOptions = {}): Promise<OnboardResult> {
+  const { OnboardingWizard, shouldRunOnboarding } = await import("@vellum/core");
+
+  // Check if needed
+  if (!options.force && !(await shouldRunOnboarding())) {
+    return {
+      success: true,
+      credentialsConfigured: true,
+      exitCode: EXIT_CODES.SUCCESS,
+    };
+  }
+
+  // For non-interactive, just report status
+  if (options.nonInteractive) {
+    const isFirstRun = OnboardingWizard.isFirstRun();
+    return {
+      success: false,
+      credentialsConfigured: false,
+      error: isFirstRun
+        ? "First run detected. Please run 'vellum onboard' interactively."
+        : "Onboarding incomplete. Please run 'vellum onboard' interactively.",
+      exitCode: EXIT_CODES.ERROR,
+    };
+  }
+
+  // Interactive mode handled by TUI
+  const wizard = new OnboardingWizard({ force: options.force });
+  await wizard.loadState();
+
+  // Return wizard for TUI to handle
+  return {
+    success: false,
+    credentialsConfigured: false,
+    error: "Interactive mode required",
+    exitCode: EXIT_CODES.SUCCESS,
+  };
+}
+
+export default onboardCommand;

package/src/commands/open.ts

@@ -0,0 +1,169 @@
+/**
+ * Open Slash Command
+ *
+ * Opens files and URLs using system defaults:
+ * - /open <url> - Open URL in browser
+ * - /open <file> - Open file with default app
+ * - /open -e <file> - Open file in editor (supports :line)
+ *
+ * @module cli/commands/open
+ */
+
+import * as path from "node:path";
+import { isValidUrl, openFile, openInEditor, openUrl } from "../tui/services/open-external.js";
+import type { CommandContext, CommandResult, SlashCommand } from "./types.js";
+import { error, success } from "./types.js";
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Parse file path with optional line number
+ *
+ * Supports formats:
+ * - /path/to/file.ts
+ * - /path/to/file.ts:42
+ * - C:\path\to\file.ts:42 (Windows)
+ *
+ * @param input - Path string potentially containing :line suffix
+ * @returns Parsed path and optional line number
+ */
+function parsePathWithLine(input: string): { filePath: string; line?: number } {
+  // Windows absolute path check (C:\, D:\, etc.)
+  const isWindowsAbsolute = /^[a-zA-Z]:[/\\]/.test(input);
+
+  // Find the last colon that's followed by a number (line indicator)
+  // For Windows paths, skip the drive letter colon
+  const searchStart = isWindowsAbsolute ? 2 : 0;
+  const colonIndex = input.lastIndexOf(":");
+
+  if (colonIndex > searchStart) {
+    const potentialLine = input.slice(colonIndex + 1);
+    const lineNum = parseInt(potentialLine, 10);
+
+    if (!Number.isNaN(lineNum) && lineNum > 0) {
+      return {
+        filePath: input.slice(0, colonIndex),
+        line: lineNum,
+      };
+    }
+  }
+
+  return { filePath: input };
+}
+
+/**
+ * Resolve path relative to current working directory
+ */
+function resolvePath(inputPath: string, cwd: string): string {
+  if (path.isAbsolute(inputPath)) {
+    return inputPath;
+  }
+  return path.resolve(cwd, inputPath);
+}
+
+// =============================================================================
+// Command Implementation
+// =============================================================================
+
+/**
+ * Open command handler
+ */
+async function executeOpen(ctx: CommandContext): Promise<CommandResult> {
+  const target = ctx.parsedArgs.positional[0] as string | undefined;
+  const inEditor = ctx.parsedArgs.named.editor === true || ctx.parsedArgs.named.e === true;
+
+  if (!target) {
+    return error(
+      "MISSING_ARGUMENT",
+      "Missing target. Usage: /open <url|file> or /open -e <file>[:line]",
+      ["/open https://example.com", "/open ./README.md", "/open -e src/index.ts:42"]
+    );
+  }
+
+  // URL handling
+  if (isValidUrl(target)) {
+    if (inEditor) {
+      return error(
+        "INVALID_ARGUMENT",
+        "Cannot open URL in editor. Use /open <url> without -e flag."
+      );
+    }
+
+    const result = await openUrl(target);
+    if (result.success) {
+      return success(`Opened ${target} in browser`);
+    }
+    return error("INTERNAL_ERROR", result.error);
+  }
+
+  // File handling
+  const cwd = ctx.session.cwd ?? process.cwd();
+  const { filePath, line } = parsePathWithLine(target);
+  const resolvedPath = resolvePath(filePath, cwd);
+
+  if (inEditor) {
+    const result = await openInEditor(resolvedPath, { line });
+    if (result.success) {
+      const location = line ? `${resolvedPath}:${line}` : resolvedPath;
+      return success(`Opened ${location} in editor`);
+    }
+    return error("INTERNAL_ERROR", result.error);
+  }
+
+  // Default: open with system default application
+  const result = await openFile(resolvedPath);
+  if (result.success) {
+    return success(`Opened ${resolvedPath}`);
+  }
+  return error("INTERNAL_ERROR", result.error);
+}
+
+// =============================================================================
+// Command Definition
+// =============================================================================
+
+/**
+ * /open command - Open files and URLs externally
+ *
+ * @example
+ * ```
+ * /open https://github.com      # Open URL in browser
+ * /open ./README.md             # Open file with default app
+ * /open -e src/index.ts         # Open in editor (VS Code)
+ * /open -e src/index.ts:42      # Open in editor at line 42
+ * ```
+ */
+export const openCommand: SlashCommand = {
+  name: "open",
+  description: "Open a file or URL with system default or editor",
+  kind: "builtin",
+  category: "navigation",
+  aliases: ["o"],
+  positionalArgs: [
+    {
+      name: "target",
+      type: "string",
+      description: "URL or file path to open (supports :line for editor)",
+      required: true,
+    },
+  ],
+  namedArgs: [
+    {
+      name: "editor",
+      shorthand: "e",
+      type: "boolean",
+      description: "Open in text editor (VS Code) instead of default app",
+      required: false,
+      default: false,
+    },
+  ],
+  examples: [
+    "/open https://github.com",
+    "/open ./README.md",
+    "/open -e src/index.ts",
+    "/open -e src/index.ts:42",
+  ],
+  execute: executeOpen,
+};