Initial commit

skills/oclif-patterns/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: oclif-patterns
+description: Enterprise CLI patterns using oclif framework with TypeScript. Use when building oclif CLIs, creating plugins, implementing commands with flags/args, adding auto-documentation, testing CLI commands, or when user mentions oclif, enterprise CLI, TypeScript CLI, plugin system, or CLI testing.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# oclif Enterprise CLI Patterns
+
+Provides comprehensive patterns for building production-grade CLIs with oclif framework.
+
+## Core Capabilities
+
+### 1. Command Structure
+- Single and multi-command CLIs
+- Flag definitions (string, boolean, integer, custom)
+- Argument parsing with validation
+- Command inheritance and base classes
+- Async command execution
+
+### 2. Plugin System
+- Installable plugins
+- Plugin discovery and loading
+- Hook system for extensibility
+- Plugin commands and lifecycle
+
+### 3. Auto-Documentation
+- Auto-generated help text
+- README generation
+- Command reference docs
+- Flag and argument documentation
+
+### 4. Testing Patterns
+- Command unit tests
+- Integration testing
+- Mock stdin/stdout
+- Fixture management
+- Test helpers
+
+## Implementation Guide
+
+### Command Creation
+
+**Use templates**:
+- `templates/command-basic.ts` - Simple command with flags
+- `templates/command-advanced.ts` - Complex command with validation
+- `templates/command-async.ts` - Async operations
+- `templates/base-command.ts` - Custom base class
+
+**Key patterns**:
+1. Import Command from '@oclif/core'
+2. Define flags using `Flags` object
+3. Define args using `Args` object
+4. Implement async run() method
+5. Use this.log() for output
+6. Use this.error() for errors
+
+### Flag Patterns
+
+**Common flags**:
+- String: `Flags.string({ description, required, default })`
+- Boolean: `Flags.boolean({ description, allowNo })`
+- Integer: `Flags.integer({ description, min, max })`
+- Custom: `Flags.custom<T>({ parse: async (input) => T })`
+- Multiple: `Flags.string({ multiple: true })`
+
+**Best practices**:
+- Always provide clear descriptions
+- Use char for common short flags
+- Set required vs optional explicitly
+- Provide sensible defaults
+- Validate in parse function for custom flags
+
+### Argument Patterns
+
+**Definition**:
+```typescript
+static args = {
+  name: Args.string({ description: 'Name', required: true }),
+  file: Args.file({ description: 'File path', exists: true })
+}
+```
+
+**Access in run()**:
+```typescript
+const { args } = await this.parse(MyCommand)
+```
+
+### Plugin Development
+
+**Use templates**:
+- `templates/plugin-package.json` - Plugin package.json
+- `templates/plugin-command.ts` - Plugin command structure
+- `templates/plugin-hooks.ts` - Hook implementations
+
+**Plugin structure**:
+```
+my-plugin/
+├── package.json (oclif configuration)
+├── src/
+│   ├── commands/ (plugin commands)
+│   └── hooks/ (lifecycle hooks)
+├── test/ (plugin tests)
+└── README.md
+```
+
+### Testing Setup
+
+**Use templates**:
+- `templates/test-command.ts` - Command test template
+- `templates/test-helpers.ts` - Test utilities
+- `templates/test-setup.ts` - Test configuration
+
+**Testing approach**:
+1. Use @oclif/test for test helpers
+2. Mock stdin/stdout with fancy-test
+3. Test flag parsing separately
+4. Test command execution
+5. Test error handling
+6. Use fixtures for file operations
+
+### Auto-Documentation
+
+**Generated automatically**:
+- Command help via `--help` flag
+- README.md with command reference
+- Usage examples
+- Flag and argument tables
+
+**Use scripts**:
+- `scripts/generate-docs.sh` - Generate all documentation
+- `scripts/update-readme.sh` - Update README with commands
+
+## Quick Start Examples
+
+### Create Basic Command
+```bash
+# Use template
+./scripts/create-command.sh my-command basic
+
+# Results in: src/commands/my-command.ts
+```
+
+### Create Plugin
+```bash
+# Use template
+./scripts/create-plugin.sh my-plugin
+
+# Results in: plugin directory structure
+```
+
+### Run Tests
+```bash
+# Use test helpers
+npm test
+# or with coverage
+npm run test:coverage
+```
+
+## Validation Scripts
+
+**Available validators**:
+- `scripts/validate-command.sh` - Check command structure
+- `scripts/validate-plugin.sh` - Verify plugin structure
+- `scripts/validate-tests.sh` - Ensure test coverage
+
+## Templates Reference
+
+### TypeScript Commands
+1. `command-basic.ts` - Simple command pattern
+2. `command-advanced.ts` - Full-featured command
+3. `command-async.ts` - Async/await patterns
+4. `base-command.ts` - Custom base class
+5. `command-with-config.ts` - Configuration management
+
+### Plugin System
+6. `plugin-package.json` - Plugin package.json
+7. `plugin-command.ts` - Plugin command
+8. `plugin-hooks.ts` - Hook implementations
+9. `plugin-manifest.json` - Plugin manifest
+
+### Testing
+10. `test-command.ts` - Command unit test
+11. `test-helpers.ts` - Test utilities
+12. `test-setup.ts` - Test configuration
+13. `test-integration.ts` - Integration test
+
+### Configuration
+14. `tsconfig.json` - TypeScript config
+15. `package.json` - oclif package.json
+16. `.eslintrc.json` - ESLint config
+
+## Examples Directory
+
+See `examples/` for complete working examples:
+- `examples/basic-cli/` - Simple CLI with commands
+- `examples/plugin-cli/` - CLI with plugin support
+- `examples/enterprise-cli/` - Full enterprise setup
+
+## Common Patterns
+
+### Error Handling
+```typescript
+if (!valid) {
+  this.error('Invalid input', { exit: 1 })
+}
+```
+
+### Spinner/Progress
+```typescript
+const spinner = ux.action.start('Processing')
+// ... work
+ux.action.stop()
+```
+
+### Prompts
+```typescript
+const answer = await ux.prompt('Continue?')
+```
+
+### Table Output
+```typescript
+ux.table(data, { columns: [...] })
+```
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5+
+- @oclif/core ^3.0.0
+- @oclif/test for testing
+- Knowledge of TypeScript decorators (optional but helpful)
+
+## Best Practices
+
+1. **Command Design**: Keep commands focused, single responsibility
+2. **Flags**: Use descriptive names, provide help text
+3. **Testing**: Test command parsing and execution separately
+4. **Documentation**: Let oclif generate docs, keep them updated
+5. **Plugins**: Design for extensibility from the start
+6. **Error Messages**: Provide actionable error messages
+7. **TypeScript**: Use strict mode, define proper types
+8. **Async**: Use async/await, handle promises properly
+
+## Advanced Features
+
+### Custom Flag Types
+Create reusable custom flag parsers for complex validation.
+
+### Hook System
+Implement hooks for: init, prerun, postrun, command_not_found.
+
+### Topic Commands
+Organize commands into topics (e.g., `mycli topic:command`).
+
+### Auto-Update
+Use @oclif/plugin-update for automatic CLI updates.
+
+### Analytics
+Integrate analytics to track command usage.