@butlerw/vellum 0.1.0

package/src/onboarding/tutorial/lessons/basics.ts

@@ -0,0 +1,151 @@
+/**
+ * Basics Tutorial Lesson
+ *
+ * Getting started lesson that covers fundamental Vellum concepts.
+ *
+ * @module cli/onboarding/tutorial/lessons/basics
+ */
+
+import type { Lesson } from "../types.js";
+
+/**
+ * Getting Started lesson - covers basic Vellum usage
+ */
+export const basicsLesson: Lesson = {
+  id: "basics",
+  title: "Getting Started with Vellum",
+  description: "Learn the fundamentals of using Vellum AI coding assistant",
+  category: "basics",
+  difficulty: "beginner",
+  prerequisites: [],
+  estimatedMinutes: 5,
+  icon: "📚",
+  tags: ["beginner", "introduction", "fundamentals"],
+  steps: [
+    {
+      id: "basics-welcome",
+      title: "Welcome to Vellum",
+      content: `
+Welcome to Vellum! 🎉
+
+Vellum is an AI-powered coding assistant that helps you write, debug,
+and understand code faster.
+
+This tutorial will teach you the basics:
+• How to interact with the AI
+• How to use slash commands
+• How to get the most out of Vellum
+
+Press Enter to continue...
+      `.trim(),
+      action: "read",
+      estimatedDuration: 30,
+    },
+    {
+      id: "basics-chat",
+      title: "Chatting with the AI",
+      content: `
+**Talking to Vellum**
+
+Simply type your question or request in natural language:
+
+• "Explain this function"
+• "Write a unit test for this code"
+• "Fix the bug in line 42"
+• "Refactor this to use async/await"
+
+The AI understands context from your project and current file.
+
+💡 Tip: Be specific about what you want for better results!
+      `.trim(),
+      action: "read",
+      hint: "Try asking the AI to explain something simple",
+      estimatedDuration: 45,
+    },
+    {
+      id: "basics-help",
+      title: "Using the Help Command",
+      content: `
+**Slash Commands**
+
+Vellum has built-in commands that start with "/":
+
+Try typing: /help
+
+This shows all available commands and their descriptions.
+      `.trim(),
+      action: "command",
+      command: "/help",
+      expectedOutcome: "You should see a list of available commands",
+      hint: "Type /help and press Enter",
+      estimatedDuration: 30,
+    },
+    {
+      id: "basics-clear",
+      title: "Clearing the Screen",
+      content: `
+**The /clear Command**
+
+To clear the conversation history and start fresh:
+
+Try typing: /clear
+
+This clears the display but keeps your session active.
+      `.trim(),
+      action: "command",
+      command: "/clear",
+      expectedOutcome: "The screen should be cleared",
+      hint: "Type /clear and press Enter",
+      estimatedDuration: 20,
+    },
+    {
+      id: "basics-mode",
+      title: "Understanding Modes",
+      content: `
+**Coding Modes**
+
+Vellum has different modes for different tasks:
+
+• **code** - General coding assistance
+• **architect** - System design and architecture
+• **debug** - Focused debugging help
+• **explain** - Code explanations
+• **review** - Code review
+
+Use /mode to see current mode or switch modes.
+      `.trim(),
+      action: "read",
+      hint: "Try /mode to see your current mode",
+      estimatedDuration: 45,
+    },
+    {
+      id: "basics-complete",
+      title: "Basics Complete!",
+      content: `
+🎉 **Congratulations!**
+
+You've learned the basics of Vellum:
+
+✅ How to chat with the AI
+✅ How to use slash commands
+✅ How to get help
+✅ Understanding modes
+
+**Next Steps:**
+• Try the "Tools" tutorial to learn about available tools
+• Try the "Modes" tutorial for advanced mode usage
+
+Happy coding! 🚀
+      `.trim(),
+      action: "complete",
+      estimatedDuration: 15,
+    },
+  ],
+};
+
+/**
+ * Get the basics lesson
+ */
+export function getBasicsLesson(): Lesson {
+  return basicsLesson;
+}

package/src/onboarding/tutorial/lessons/index.ts

@@ -0,0 +1,151 @@
+/**
+ * Tutorial Lessons Index
+ *
+ * Exports all available tutorial lessons.
+ *
+ * @module cli/onboarding/tutorial/lessons
+ */
+
+import type { Lesson, LessonCategory } from "../types.js";
+import { basicsLesson } from "./basics.js";
+import { modesLesson } from "./modes.js";
+import { toolsLesson } from "./tools.js";
+
+// =============================================================================
+// Lesson Exports
+// =============================================================================
+
+export { basicsLesson, getBasicsLesson } from "./basics.js";
+export { getModesLesson, modesLesson } from "./modes.js";
+export { getToolsLesson, toolsLesson } from "./tools.js";
+
+// =============================================================================
+// Lesson Registry
+// =============================================================================
+
+/**
+ * All available lessons
+ */
+export const ALL_LESSONS: readonly Lesson[] = [basicsLesson, toolsLesson, modesLesson] as const;
+
+/**
+ * Lessons indexed by ID
+ */
+export const LESSONS_BY_ID: Readonly<Record<string, Lesson>> = Object.freeze(
+  ALL_LESSONS.reduce(
+    (acc, lesson) => {
+      acc[lesson.id] = lesson;
+      return acc;
+    },
+    {} as Record<string, Lesson>
+  )
+);
+
+/**
+ * Lessons grouped by category
+ */
+export const LESSONS_BY_CATEGORY: Readonly<Record<LessonCategory, Lesson[]>> = Object.freeze({
+  basics: ALL_LESSONS.filter((l) => l.category === "basics"),
+  tools: ALL_LESSONS.filter((l) => l.category === "tools"),
+  modes: ALL_LESSONS.filter((l) => l.category === "modes"),
+  advanced: ALL_LESSONS.filter((l) => l.category === "advanced"),
+  workflow: ALL_LESSONS.filter((l) => l.category === "workflow"),
+});
+
+// =============================================================================
+// Lesson Utilities
+// =============================================================================
+
+/**
+ * Get a lesson by ID
+ */
+export function getLessonById(lessonId: string): Lesson | undefined {
+  return LESSONS_BY_ID[lessonId];
+}
+
+/**
+ * Get lessons by category
+ */
+export function getLessonsByCategory(category: LessonCategory): Lesson[] {
+  return LESSONS_BY_CATEGORY[category] ?? [];
+}
+
+/**
+ * Get all lessons
+ */
+export function getAllLessons(): Lesson[] {
+  return [...ALL_LESSONS];
+}
+
+/**
+ * Get recommended lesson order (respecting prerequisites)
+ */
+export function getRecommendedOrder(): Lesson[] {
+  // Simple topological sort based on prerequisites
+  const visited = new Set<string>();
+  const result: Lesson[] = [];
+
+  function visit(lesson: Lesson): void {
+    if (visited.has(lesson.id)) return;
+
+    // Visit prerequisites first
+    for (const prereqId of lesson.prerequisites) {
+      const prereq = LESSONS_BY_ID[prereqId];
+      if (prereq) {
+        visit(prereq);
+      }
+    }
+
+    visited.add(lesson.id);
+    result.push(lesson);
+  }
+
+  for (const lesson of ALL_LESSONS) {
+    visit(lesson);
+  }
+
+  return result;
+}
+
+/**
+ * Check if a lesson's prerequisites are met
+ */
+export function checkPrerequisites(lessonId: string, completedLessons: string[]): boolean {
+  const lesson = LESSONS_BY_ID[lessonId];
+  if (!lesson) return false;
+
+  return lesson.prerequisites.every((prereqId: string) => completedLessons.includes(prereqId));
+}
+
+/**
+ * Get next recommended lesson based on progress
+ */
+export function getNextLesson(completedLessons: string[]): Lesson | undefined {
+  const ordered = getRecommendedOrder();
+
+  return ordered.find(
+    (lesson) =>
+      !completedLessons.includes(lesson.id) && checkPrerequisites(lesson.id, completedLessons)
+  );
+}
+
+/**
+ * Calculate total tutorial duration in minutes
+ */
+export function getTotalDuration(): number {
+  return ALL_LESSONS.reduce((sum, lesson) => sum + lesson.estimatedMinutes, 0);
+}
+
+/**
+ * Get lesson count
+ */
+export function getLessonCount(): number {
+  return ALL_LESSONS.length;
+}
+
+/**
+ * Get total step count across all lessons
+ */
+export function getTotalStepCount(): number {
+  return ALL_LESSONS.reduce((sum, lesson) => sum + lesson.steps.length, 0);
+}

package/src/onboarding/tutorial/lessons/modes.ts

@@ -0,0 +1,230 @@
+/**
+ * Modes Tutorial Lesson
+ *
+ * Lesson covering coding modes and when to use each.
+ *
+ * @module cli/onboarding/tutorial/lessons/modes
+ */
+
+import type { Lesson } from "../types.js";
+
+/**
+ * Modes lesson - understand and use coding modes
+ */
+export const modesLesson: Lesson = {
+  id: "modes",
+  title: "Mastering Coding Modes",
+  description: "Learn when and how to use different coding modes",
+  category: "modes",
+  difficulty: "intermediate",
+  prerequisites: ["basics"],
+  estimatedMinutes: 8,
+  icon: "⚡",
+  tags: ["modes", "workflow", "productivity"],
+  steps: [
+    {
+      id: "modes-intro",
+      title: "What are Modes?",
+      content: `
+**Coding Modes**
+
+Modes customize how Vellum responds to your requests:
+
+• Different system prompts
+• Different tool permissions
+• Different response styles
+
+Think of modes as "personalities" optimized for specific tasks.
+      `.trim(),
+      action: "read",
+      estimatedDuration: 30,
+    },
+    {
+      id: "modes-check",
+      title: "Check Current Mode",
+      content: `
+**The /mode Command**
+
+To see your current mode:
+
+Try typing: /mode
+
+This shows your active mode and available options.
+      `.trim(),
+      action: "command",
+      command: "/mode",
+      expectedOutcome: "Your current mode and list of available modes",
+      hint: "Type /mode and press Enter",
+      estimatedDuration: 30,
+    },
+    {
+      id: "modes-code",
+      title: "Code Mode",
+      content: `
+**Code Mode** (Default)
+
+Best for:
+• Writing new features
+• General coding tasks
+• Implementation work
+
+Balanced between speed and thoroughness.
+      `.trim(),
+      action: "read",
+      estimatedDuration: 30,
+    },
+    {
+      id: "modes-architect",
+      title: "Architect Mode",
+      content: `
+**Architect Mode**
+
+Best for:
+• System design
+• API planning
+• Architecture decisions
+• Refactoring strategies
+
+Focuses on high-level thinking before implementation.
+
+💡 Use when planning major features!
+      `.trim(),
+      action: "read",
+      hint: "Switch with: /mode architect",
+      estimatedDuration: 30,
+    },
+    {
+      id: "modes-debug",
+      title: "Debug Mode",
+      content: `
+**Debug Mode**
+
+Best for:
+• Fixing bugs
+• Error investigation
+• Understanding failures
+• Performance issues
+
+Methodical, step-by-step analysis approach.
+
+💡 Great when you're stuck on an error!
+      `.trim(),
+      action: "read",
+      hint: "Switch with: /mode debug",
+      estimatedDuration: 30,
+    },
+    {
+      id: "modes-explain",
+      title: "Explain Mode",
+      content: `
+**Explain Mode**
+
+Best for:
+• Learning new code
+• Understanding complex logic
+• Documentation
+• Code reviews
+
+Detailed explanations with examples.
+
+💡 Perfect for unfamiliar codebases!
+      `.trim(),
+      action: "read",
+      hint: "Switch with: /mode explain",
+      estimatedDuration: 30,
+    },
+    {
+      id: "modes-review",
+      title: "Review Mode",
+      content: `
+**Review Mode**
+
+Best for:
+• Code review
+• Finding issues
+• Suggesting improvements
+• Best practices check
+
+Critical analysis focused on quality.
+
+💡 Run before submitting PRs!
+      `.trim(),
+      action: "read",
+      hint: "Switch with: /mode review",
+      estimatedDuration: 30,
+    },
+    {
+      id: "modes-switch",
+      title: "Practice: Switch Modes",
+      content: `
+**Try Switching!**
+
+Switch to architect mode:
+
+/mode architect
+
+Then switch back to code mode:
+
+/mode code
+
+Notice how the context changes!
+      `.trim(),
+      action: "command",
+      command: "/mode architect",
+      expectedOutcome: "Mode should change to architect",
+      hint: "Type /mode architect and press Enter",
+      estimatedDuration: 45,
+    },
+    {
+      id: "modes-tips",
+      title: "Mode Selection Tips",
+      content: `
+**When to Use Each Mode**
+
+| Situation | Mode |
+|-----------|------|
+| Writing new code | code |
+| Planning features | architect |
+| Fixing bugs | debug |
+| Learning code | explain |
+| Before merge | review |
+
+💡 **Pro Tip**: Start in architect mode for complex tasks,
+then switch to code mode for implementation.
+      `.trim(),
+      action: "read",
+      estimatedDuration: 45,
+    },
+    {
+      id: "modes-complete",
+      title: "Modes Complete!",
+      content: `
+🎉 **Excellent Work!**
+
+You've mastered Vellum's coding modes:
+
+✅ Understanding what modes do
+✅ Available modes and their purposes
+✅ How to switch between modes
+✅ When to use each mode
+
+**Your Workflow:**
+1. Start in architect mode for planning
+2. Switch to code mode for implementation
+3. Use debug mode when things break
+4. Finish with review mode for quality
+
+You're now a Vellum power user! 🚀
+      `.trim(),
+      action: "complete",
+      estimatedDuration: 15,
+    },
+  ],
+};
+
+/**
+ * Get the modes lesson
+ */
+export function getModesLesson(): Lesson {
+  return modesLesson;
+}

package/src/onboarding/tutorial/lessons/tools.ts

@@ -0,0 +1,172 @@
+/**
+ * Tools Tutorial Lesson
+ *
+ * Lesson covering tool usage and capabilities.
+ *
+ * @module cli/onboarding/tutorial/lessons/tools
+ */
+
+import type { Lesson } from "../types.js";
+
+/**
+ * Tools lesson - learn about available tools
+ */
+export const toolsLesson: Lesson = {
+  id: "tools",
+  title: "Working with Tools",
+  description: "Learn how to use and manage Vellum's powerful tools",
+  category: "tools",
+  difficulty: "beginner",
+  prerequisites: ["basics"],
+  estimatedMinutes: 7,
+  icon: "🔧",
+  tags: ["tools", "commands", "capabilities"],
+  steps: [
+    {
+      id: "tools-intro",
+      title: "Introduction to Tools",
+      content: `
+**What are Tools?**
+
+Tools are powerful capabilities that Vellum can use to help you:
+
+• **Read files** - Access and understand your code
+• **Edit files** - Make changes to your codebase
+• **Run commands** - Execute shell commands
+• **Search** - Find code across your project
+• **And more!**
+
+Tools work automatically when you ask the AI to do something.
+      `.trim(),
+      action: "read",
+      estimatedDuration: 30,
+    },
+    {
+      id: "tools-list",
+      title: "Listing Available Tools",
+      content: `
+**The /tools Command**
+
+To see all available tools:
+
+Try typing: /tools
+
+This shows every tool Vellum can use and its description.
+      `.trim(),
+      action: "command",
+      command: "/tools",
+      expectedOutcome: "A list of available tools with descriptions",
+      hint: "Type /tools and press Enter",
+      estimatedDuration: 30,
+    },
+    {
+      id: "tools-categories",
+      title: "Tool Categories",
+      content: `
+**Tool Categories**
+
+Tools are organized into categories:
+
+📁 **Filesystem** - read, write, list files
+🔍 **Search** - grep, semantic search
+💻 **Shell** - run terminal commands
+🌐 **Web** - fetch URLs, API calls
+🔒 **Security** - permission management
+
+Each category serves different needs.
+      `.trim(),
+      action: "read",
+      hint: "Tools automatically activate based on your request",
+      estimatedDuration: 45,
+    },
+    {
+      id: "tools-permissions",
+      title: "Tool Permissions",
+      content: `
+**Security & Permissions**
+
+Some tools require approval before running:
+
+• **File edits** - Confirm before modifying files
+• **Shell commands** - Approve potentially dangerous commands
+• **Network** - Authorize external requests
+
+You control what Vellum can do!
+
+💡 Use /permission to manage approvals.
+      `.trim(),
+      action: "read",
+      hint: "You can always deny a tool action",
+      estimatedDuration: 45,
+    },
+    {
+      id: "tools-natural",
+      title: "Natural Language Usage",
+      content: `
+**Just Ask!**
+
+You don't need to know tool names. Just describe what you want:
+
+✅ "Show me the contents of package.json"
+✅ "Find all TypeScript files with TODO comments"
+✅ "Run the tests"
+✅ "Create a new component called Button"
+
+Vellum picks the right tools automatically.
+      `.trim(),
+      action: "read",
+      hint: "Be specific about what you want to achieve",
+      estimatedDuration: 30,
+    },
+    {
+      id: "tools-practice",
+      title: "Practice: List Files",
+      content: `
+**Let's Try It!**
+
+Ask Vellum to list files in the current directory:
+
+Example prompts:
+• "What files are in this directory?"
+• "List the contents of this folder"
+• "Show me the project structure"
+
+Try one of these or write your own!
+      `.trim(),
+      action: "interact",
+      expectedOutcome: "Vellum should use the file listing tool",
+      hint: "Just type a natural language request",
+      estimatedDuration: 60,
+    },
+    {
+      id: "tools-complete",
+      title: "Tools Complete!",
+      content: `
+🎉 **Great Job!**
+
+You now understand Vellum's tool system:
+
+✅ What tools are and how they work
+✅ How to list available tools
+✅ Tool categories and permissions
+✅ Natural language tool usage
+
+**Pro Tips:**
+• Let Vellum choose tools automatically
+• Review tool actions before approving
+• Use /tools to explore capabilities
+
+Next: Try the "Modes" tutorial! 🎯
+      `.trim(),
+      action: "complete",
+      estimatedDuration: 15,
+    },
+  ],
+};
+
+/**
+ * Get the tools lesson
+ */
+export function getToolsLesson(): Lesson {
+  return toolsLesson;
+}