@butlerw/vellum 0.1.0

package/src/commands/init/prompts.ts

@@ -0,0 +1,366 @@
+/**
+ * Init Prompts Command
+ *
+ * Scaffolds the .vellum/ directory structure for customizing prompts,
+ * rules, skills, commands, and workflows.
+ *
+ * Usage:
+ * - `vellum init prompts` - Interactive scaffolding
+ * - `vellum init prompts --force` - Overwrite existing .vellum/
+ *
+ * @module cli/commands/init/prompts
+ * @see REQ-015
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { confirm } from "@inquirer/prompts";
+import chalk from "chalk";
+
+import { EXIT_CODES } from "../exit-codes.js";
+import type { CommandContext, CommandResult, SlashCommand } from "../types.js";
+import { error, pending, success } from "../types.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Directory structure to scaffold
+ */
+const SCAFFOLD_DIRECTORIES = [
+  "prompts",
+  "prompts/roles",
+  "prompts/providers",
+  "prompts/spec",
+  "prompts/workers",
+  "prompts/custom",
+  "rules",
+  "skills",
+  "commands",
+  "workflows",
+] as const;
+
+/**
+ * README files to copy from templates
+ */
+const README_MAPPINGS: Record<string, string> = {
+  prompts: "prompts-readme.md",
+  rules: "rules-readme.md",
+  skills: "skills-readme.md",
+  commands: "commands-readme.md",
+  workflows: "workflows-readme.md",
+};
+
+/**
+ * Example files to copy from templates
+ */
+const EXAMPLE_MAPPINGS: Record<string, string> = {
+  "commands/summarize.example.md": "example-command.md",
+  "workflows/bugfix.example.md": "example-workflow.md",
+  "skills/react-patterns/SKILL.md": "example-skill.md",
+};
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for init prompts command
+ */
+export interface InitPromptsOptions {
+  /** Overwrite existing .vellum/ without prompting */
+  force?: boolean;
+  /** Non-interactive mode (for CI) */
+  nonInteractive?: boolean;
+  /** Working directory (defaults to process.cwd()) */
+  cwd?: string;
+}
+
+/**
+ * Result of init prompts command
+ */
+export interface InitPromptsResult {
+  /** Whether initialization succeeded */
+  success: boolean;
+  /** Path to created .vellum/ directory */
+  vellumPath?: string;
+  /** Directories created */
+  directoriesCreated?: string[];
+  /** Files created */
+  filesCreated?: string[];
+  /** Error message if failed */
+  error?: string;
+  /** Exit code */
+  exitCode: number;
+}
+
+// =============================================================================
+// Template Loading
+// =============================================================================
+
+/**
+ * Get the templates directory path
+ */
+function getTemplatesDir(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  return join(dirname(currentFile), "templates");
+}
+
+/**
+ * Read a template file
+ */
+function readTemplate(templateName: string): string | null {
+  try {
+    const templatePath = join(getTemplatesDir(), templateName);
+    return readFileSync(templatePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// Scaffolding Logic
+// =============================================================================
+
+/**
+ * Create the .vellum/ directory structure
+ *
+ * @param rootDir - Project root directory
+ * @returns Created directories and files
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Multiple directory/file creation paths required
+function scaffoldVellumDirectory(rootDir: string): {
+  directories: string[];
+  files: string[];
+} {
+  const vellumPath = join(rootDir, ".vellum");
+  const directories: string[] = [];
+  const files: string[] = [];
+
+  // Create main .vellum directory
+  if (!existsSync(vellumPath)) {
+    mkdirSync(vellumPath, { recursive: true });
+    directories.push(".vellum");
+  }
+
+  // Create subdirectories
+  for (const subdir of SCAFFOLD_DIRECTORIES) {
+    const fullPath = join(vellumPath, subdir);
+    if (!existsSync(fullPath)) {
+      mkdirSync(fullPath, { recursive: true });
+      directories.push(`.vellum/${subdir}`);
+    }
+  }
+
+  // Copy README files
+  for (const [targetDir, templateFile] of Object.entries(README_MAPPINGS)) {
+    const targetPath = join(vellumPath, targetDir, "README.md");
+    if (!existsSync(targetPath)) {
+      const content = readTemplate(templateFile);
+      if (content) {
+        writeFileSync(targetPath, content, "utf-8");
+        files.push(`.vellum/${targetDir}/README.md`);
+      }
+    }
+  }
+
+  // Copy example files
+  for (const [targetFile, templateFile] of Object.entries(EXAMPLE_MAPPINGS)) {
+    const targetPath = join(vellumPath, targetFile);
+    const targetDirPath = dirname(targetPath);
+
+    // Ensure parent directory exists (for nested paths like skills/react-patterns/)
+    if (!existsSync(targetDirPath)) {
+      mkdirSync(targetDirPath, { recursive: true });
+      const relativePath = targetDirPath
+        .replace(`${vellumPath}/`, "")
+        .replace(`${vellumPath}\\`, "");
+      if (!directories.includes(`.vellum/${relativePath}`)) {
+        directories.push(`.vellum/${relativePath}`);
+      }
+    }
+
+    if (!existsSync(targetPath)) {
+      const content = readTemplate(templateFile);
+      if (content) {
+        writeFileSync(targetPath, content, "utf-8");
+        files.push(`.vellum/${targetFile}`);
+      }
+    }
+  }
+
+  return { directories, files };
+}
+
+// =============================================================================
+// Command Execution
+// =============================================================================
+
+/**
+ * Execute init prompts command
+ *
+ * @param options - Command options
+ * @returns Init result
+ */
+export async function executeInitPrompts(
+  options: InitPromptsOptions = {}
+): Promise<InitPromptsResult> {
+  const rootDir = options.cwd ?? process.cwd();
+  const vellumPath = join(rootDir, ".vellum");
+
+  try {
+    // Check for existing .vellum directory
+    const exists = existsSync(vellumPath);
+
+    if (exists && !options.force) {
+      // In non-interactive mode, fail if directory exists
+      if (options.nonInteractive) {
+        console.log(chalk.yellow(".vellum/ already exists. Use --force to overwrite."));
+        return {
+          success: false,
+          error: "Directory already exists",
+          exitCode: EXIT_CODES.ERROR,
+        };
+      }
+
+      // Interactive confirmation
+      const shouldOverwrite = await confirm({
+        message: ".vellum/ already exists. Overwrite?",
+        default: false,
+      });
+
+      if (!shouldOverwrite) {
+        console.log(chalk.gray("Aborted."));
+        return {
+          success: false,
+          error: "Aborted by user",
+          exitCode: EXIT_CODES.SUCCESS, // User choice, not an error
+        };
+      }
+    }
+
+    // Scaffold the directory structure
+    console.log(chalk.blue("\n🔧 Scaffolding .vellum/ directory...\n"));
+
+    const { directories, files } = scaffoldVellumDirectory(rootDir);
+
+    // Display created items
+    if (directories.length > 0) {
+      console.log(chalk.gray("Created directories:"));
+      for (const dir of directories) {
+        console.log(chalk.gray(`  📁 ${dir}`));
+      }
+    }
+
+    if (files.length > 0) {
+      console.log(chalk.gray("\nCreated files:"));
+      for (const file of files) {
+        console.log(chalk.gray(`  📄 ${file}`));
+      }
+    }
+
+    console.log(chalk.green("\n✅ .vellum/ directory scaffolded successfully!"));
+    console.log(chalk.gray("\nNext steps:"));
+    console.log(chalk.gray("  • Add custom prompts to .vellum/prompts/"));
+    console.log(chalk.gray("  • Add global rules to .vellum/rules/"));
+    console.log(chalk.gray("  • Create skills in .vellum/skills/"));
+    console.log(chalk.gray("  • Add custom commands in .vellum/commands/"));
+    console.log(chalk.gray("  • Define workflows in .vellum/workflows/"));
+    console.log(chalk.gray("  • Run `vellum prompt validate` to check syntax\n"));
+
+    return {
+      success: true,
+      vellumPath,
+      directoriesCreated: directories,
+      filesCreated: files,
+      exitCode: EXIT_CODES.SUCCESS,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(chalk.red(`\n❌ Failed to scaffold .vellum/: ${message}`));
+    return {
+      success: false,
+      error: message,
+      exitCode: EXIT_CODES.ERROR,
+    };
+  }
+}
+
+// =============================================================================
+// Slash Command Definition
+// =============================================================================
+
+/**
+ * Init prompts slash command for TUI
+ *
+ * Scaffolds the .vellum/ directory structure.
+ */
+export const initPromptsCommand: SlashCommand = {
+  name: "init-prompts",
+  description: "Scaffold .vellum/ directory for custom prompts and configuration",
+  kind: "builtin",
+  category: "config",
+  aliases: ["scaffold"],
+  namedArgs: [
+    {
+      name: "force",
+      shorthand: "f",
+      type: "boolean",
+      description: "Overwrite existing .vellum/ without prompting",
+      required: false,
+      default: false,
+    },
+  ],
+  examples: [
+    "/init-prompts           - Interactive scaffolding",
+    "/init-prompts --force   - Overwrite existing .vellum/",
+  ],
+
+  execute: async (ctx: CommandContext): Promise<CommandResult> => {
+    const force = ctx.parsedArgs.named.force as boolean | undefined;
+
+    return pending({
+      message: "Scaffolding .vellum/ directory...",
+      showProgress: true,
+      promise: (async (): Promise<CommandResult> => {
+        const result = await executeInitPrompts({
+          force: force ?? false,
+          nonInteractive: false,
+        });
+
+        if (result.success) {
+          const createdCount =
+            (result.directoriesCreated?.length ?? 0) + (result.filesCreated?.length ?? 0);
+          return success(`Scaffolded ${createdCount} items in .vellum/`, {
+            vellumPath: result.vellumPath,
+            directoriesCreated: result.directoriesCreated,
+            filesCreated: result.filesCreated,
+          });
+        }
+
+        return error("INTERNAL_ERROR", result.error ?? "Failed to scaffold .vellum/");
+      })(),
+    });
+  },
+};
+
+// =============================================================================
+// CLI Entry Point
+// =============================================================================
+
+/**
+ * Run init prompts command from CLI
+ *
+ * @param options - CLI options
+ */
+export async function runInitPromptsCli(options: { force?: boolean }): Promise<void> {
+  const result = await executeInitPrompts({
+    force: options.force ?? false,
+    nonInteractive: false,
+  });
+
+  process.exit(result.exitCode);
+}

package/src/commands/init/templates/commands-readme.md

@@ -0,0 +1,80 @@
+# Commands Directory
+
+Custom slash commands that extend Vellum's functionality.
+
+## Structure
+
+```text
+commands/
+├── {command-name}.md    # Command definition
+└── README.md
+```
+
+## File Format
+
+```markdown
+---
+name: review
+description: Request code review for current changes
+category: tools
+aliases:
+  - cr
+  - codereview
+---
+
+# /review Command
+
+Review the current changes and provide feedback.
+
+## Instructions
+
+When this command is invoked:
+
+1. Examine the current git diff
+2. Look for potential issues:
+   - Code style violations
+   - Performance concerns
+   - Security vulnerabilities
+   - Missing error handling
+3. Provide structured feedback
+
+## Output Format
+
+Format your review as:
+
+### Summary
+Brief overview of changes
+
+### Issues Found
+- [ ] Issue 1
+- [ ] Issue 2
+
+### Suggestions
+Improvement recommendations
+```markdown
+
+## Frontmatter Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Command name without slash (required) |
+| `description` | string | Help text (required) |
+| `category` | string | Grouping: system, auth, session, navigation, tools, config, debug |
+| `aliases` | string[] | Alternative command names |
+| `enabled` | boolean | Whether command is active |
+
+## Usage
+
+After creating a command file:
+
+```bash
+# Use the command
+/review
+
+# Or use an alias
+/cr
+```
+
+## Documentation
+
+See [Vellum Commands Documentation](https://vellum.dev/docs/commands) for more details.

package/src/commands/init/templates/example-command.md

@@ -0,0 +1,79 @@
+---
+name: summarize
+description: Summarize the current file or selection
+category: tools
+aliases:
+  - sum
+  - tldr
+enabled: true
+---
+
+# /summarize Command
+
+Provide a concise summary of the current context.
+
+## Instructions
+
+When this command is invoked:
+
+1. Identify the current context:
+   - If text is selected, summarize the selection
+   - If a file is open, summarize the file
+   - If in a conversation, summarize recent messages
+
+2. Generate a summary that includes:
+   - **Purpose**: What does this code/text do?
+   - **Key Points**: Main concepts or functionality
+   - **Structure**: How is it organized?
+
+3. Keep the summary:
+   - Concise (3-5 sentences for small content)
+   - Structured (use bullet points for complex content)
+   - Actionable (highlight important details)
+
+## Output Format
+
+```markdown
+## Summary
+
+**Purpose**: [One-sentence description]
+
+**Key Points**:
+- Point 1
+- Point 2
+- Point 3
+
+**Notable**: [Any important observations]
+```
+
+## Examples
+
+### For Code Files
+
+```markdown
+## Summary
+
+**Purpose**: HTTP request handler for user authentication
+
+**Key Points**:
+- Validates JWT tokens from Authorization header
+- Supports both cookie and header-based auth
+- Returns 401 for invalid/expired tokens
+
+**Notable**: Rate limiting applied via middleware
+```
+
+### For Documentation
+
+```markdown
+## Summary
+
+**Purpose**: API reference for the authentication module
+
+**Key Points**:
+- 5 endpoints documented (login, logout, refresh, verify, revoke)
+- OAuth2 flow supported
+- Includes code examples in TypeScript
+
+**Notable**: Breaking changes from v1 noted in migration section
+```

package/src/commands/init/templates/example-skill.md

@@ -0,0 +1,168 @@
+---
+name: react-patterns
+description: Best practices and patterns for React development
+version: "1.0.0"
+triggers:
+  - react
+  - component
+  - hook
+  - jsx
+  - tsx
+tags:
+  - react
+  - frontend
+  - typescript
+priority: 100
+---
+
+# React Patterns Skill
+
+Expert knowledge for building React applications with TypeScript.
+
+## Core Principles
+
+1. **Composition over inheritance**: Build small, reusable components
+2. **Unidirectional data flow**: Props down, events up
+3. **Explicit over implicit**: Prefer explicit prop passing
+4. **Type safety**: Leverage TypeScript for all components
+
+## Component Patterns
+
+### Functional Components (Preferred)
+
+```tsx
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  variant?: 'primary' | 'secondary';
+  disabled?: boolean;
+}
+
+export function Button({ 
+  label, 
+  onClick, 
+  variant = 'primary',
+  disabled = false 
+}: ButtonProps) {
+  return (
+    <button
+      className={`btn btn-${variant}`}
+      onClick={onClick}
+      disabled={disabled}
+    >
+      {label}
+    </button>
+  );
+}
+```markdown
+
+### Compound Components
+
+```tsx
+interface TabsContextValue {
+  activeTab: string;
+  setActiveTab: (tab: string) => void;
+}
+
+const TabsContext = createContext<TabsContextValue | null>(null);
+
+function Tabs({ children, defaultTab }: TabsProps) {
+  const [activeTab, setActiveTab] = useState(defaultTab);
+  
+  return (
+    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
+      <div className="tabs">{children}</div>
+    </TabsContext.Provider>
+  );
+}
+
+Tabs.Tab = function Tab({ id, children }: TabProps) {
+  const ctx = useContext(TabsContext);
+  if (!ctx) throw new Error('Tab must be used within Tabs');
+  
+  return (
+    <button
+      className={ctx.activeTab === id ? 'active' : ''}
+      onClick={() => ctx.setActiveTab(id)}
+    >
+      {children}
+    </button>
+  );
+};
+```markdown
+
+## Hook Patterns
+
+### Custom Hooks
+
+```tsx
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+
+  useEffect(() => {
+    localStorage.setItem(key, JSON.stringify(value));
+  }, [key, value]);
+
+  return [value, setValue] as const;
+}
+```markdown
+
+### Cleanup Pattern
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  
+  fetchData(controller.signal)
+    .then(setData)
+    .catch(err => {
+      if (!controller.signal.aborted) {
+        setError(err);
+      }
+    });
+  
+  return () => controller.abort();
+}, []);
+```markdown
+
+## Anti-Patterns to Avoid
+
+1. **Don't mutate state directly**
+   ```tsx
+   // ❌ Bad
+   state.items.push(newItem);
+   
+   // ✅ Good
+   setItems([...items, newItem]);
+   ```text
+
+2. **Don't use index as key for dynamic lists**
+   ```tsx
+   // ❌ Bad
+   items.map((item, i) => <Item key={i} {...item} />);
+   
+   // ✅ Good
+   items.map(item => <Item key={item.id} {...item} />);
+   ```text
+
+3. **Don't overuse useEffect**
+   ```tsx
+   // ❌ Bad - derived state
+   const [fullName, setFullName] = useState('');
+   useEffect(() => {
+     setFullName(`${firstName} ${lastName}`);
+   }, [firstName, lastName]);
+   
+   // ✅ Good - compute directly
+   const fullName = `${firstName} ${lastName}`;
+   ```
+
+## Testing Recommendations
+
+- Use `@testing-library/react` for component tests
+- Test behavior, not implementation
+- Use `userEvent` over `fireEvent`
+- Mock API calls at the network level with MSW