354 lines
9.4 KiB
Markdown
354 lines
9.4 KiB
Markdown
---
|
|
name: gluegun-patterns
|
|
description: Gluegun CLI toolkit patterns for TypeScript-powered command-line apps. Use when building CLI tools, creating command structures, implementing template systems, filesystem operations, HTTP utilities, prompts, or plugin architectures with Gluegun.
|
|
allowed-tools: Read, Write, Edit, Bash, Glob
|
|
---
|
|
|
|
# Gluegun CLI Toolkit Patterns
|
|
|
|
Provides comprehensive patterns and templates for building TypeScript-powered CLI applications using the Gluegun toolkit. Gluegun offers parameters, templates, filesystem operations, HTTP utilities, prompts, and extensible plugin architecture.
|
|
|
|
## Core Capabilities
|
|
|
|
Gluegun provides these essential toolbox features:
|
|
|
|
1. **Parameters** - Command-line arguments and options parsing
|
|
2. **Template** - EJS-based file generation from templates
|
|
3. **Filesystem** - File and directory operations (fs-jetpack)
|
|
4. **System** - Execute external commands and scripts
|
|
5. **HTTP** - API interactions with axios/apisauce
|
|
6. **Prompt** - Interactive user input with enquirer
|
|
7. **Print** - Colorful console output with colors/ora
|
|
8. **Patching** - Modify existing file contents
|
|
9. **Semver** - Version string manipulation
|
|
10. **Plugin System** - Extensible command architecture
|
|
|
|
## Instructions
|
|
|
|
### Building a Basic CLI
|
|
|
|
1. **Initialize Gluegun CLI structure:**
|
|
```typescript
|
|
import { build } from 'gluegun'
|
|
|
|
const cli = build()
|
|
.brand('mycli')
|
|
.src(__dirname)
|
|
.plugins('./node_modules', { matching: 'mycli-*', hidden: true })
|
|
.help()
|
|
.version()
|
|
.create()
|
|
```
|
|
|
|
2. **Create command structure:**
|
|
- Commands go in `src/commands/` directory
|
|
- Each command exports a `GluegunCommand` object
|
|
- Use templates from `templates/` directory
|
|
- Reference template: `templates/commands/basic-command.ts.ejs`
|
|
|
|
3. **Implement command with toolbox:**
|
|
```typescript
|
|
module.exports = {
|
|
name: 'generate',
|
|
run: async (toolbox) => {
|
|
const { template, print, parameters } = toolbox
|
|
const name = parameters.first
|
|
|
|
await template.generate({
|
|
template: 'model.ts.ejs',
|
|
target: `src/models/${name}.ts`,
|
|
props: { name }
|
|
})
|
|
|
|
print.success(`Generated ${name} model`)
|
|
}
|
|
}
|
|
```
|
|
|
|
### Template System
|
|
|
|
1. **Template file structure:**
|
|
- Store templates in `templates/` directory
|
|
- Use EJS syntax: `<%= variable %>`, `<%- unescaped %>`
|
|
- Reference: `templates/toolbox/template-examples.ejs`
|
|
|
|
2. **Generate files from templates:**
|
|
```typescript
|
|
await template.generate({
|
|
template: 'component.tsx.ejs',
|
|
target: `src/components/${name}.tsx`,
|
|
props: { name, style: 'functional' }
|
|
})
|
|
```
|
|
|
|
3. **Helper functions:**
|
|
- `props.camelCase` - camelCase conversion
|
|
- `props.pascalCase` - PascalCase conversion
|
|
- `props.kebabCase` - kebab-case conversion
|
|
- Reference: `scripts/template-helpers.ts`
|
|
|
|
### Filesystem Operations
|
|
|
|
1. **Common operations (fs-jetpack):**
|
|
```typescript
|
|
// Read/write files
|
|
const config = await filesystem.read('config.json', 'json')
|
|
await filesystem.write('output.txt', data)
|
|
|
|
// Directory operations
|
|
await filesystem.dir('src/components')
|
|
const files = filesystem.find('src', { matching: '*.ts' })
|
|
|
|
// Copy/move/remove
|
|
await filesystem.copy('template', 'output')
|
|
await filesystem.move('old.txt', 'new.txt')
|
|
await filesystem.remove('temp')
|
|
```
|
|
|
|
2. **Path utilities:**
|
|
```typescript
|
|
filesystem.path('src', 'commands') // Join paths
|
|
filesystem.cwd() // Current directory
|
|
filesystem.separator // OS-specific separator
|
|
```
|
|
|
|
### HTTP Utilities
|
|
|
|
1. **API interactions:**
|
|
```typescript
|
|
const api = http.create({
|
|
baseURL: 'https://api.example.com',
|
|
headers: { 'Authorization': 'Bearer token' }
|
|
})
|
|
|
|
const response = await api.get('/users')
|
|
const result = await api.post('/users', { name: 'John' })
|
|
```
|
|
|
|
2. **Error handling:**
|
|
```typescript
|
|
if (!response.ok) {
|
|
print.error(response.problem)
|
|
return
|
|
}
|
|
```
|
|
|
|
### Interactive Prompts
|
|
|
|
1. **User input patterns:**
|
|
```typescript
|
|
// Ask question
|
|
const result = await prompt.ask({
|
|
type: 'input',
|
|
name: 'name',
|
|
message: 'What is your name?'
|
|
})
|
|
|
|
// Confirm action
|
|
const proceed = await prompt.confirm('Continue?')
|
|
|
|
// Select from list
|
|
const choice = await prompt.ask({
|
|
type: 'select',
|
|
name: 'framework',
|
|
message: 'Choose framework:',
|
|
choices: ['React', 'Vue', 'Angular']
|
|
})
|
|
```
|
|
|
|
2. **Multi-select and complex forms:**
|
|
- Reference: `examples/prompts/multi-select.ts`
|
|
- See: `templates/toolbox/prompt-examples.ts.ejs`
|
|
|
|
### Plugin Architecture
|
|
|
|
1. **Create extensible plugins:**
|
|
```typescript
|
|
// Plugin structure
|
|
export default (toolbox) => {
|
|
const { filesystem, template } = toolbox
|
|
|
|
// Add custom extension
|
|
toolbox.myFeature = {
|
|
doSomething: () => { /* ... */ }
|
|
}
|
|
}
|
|
```
|
|
|
|
2. **Load plugins:**
|
|
```typescript
|
|
cli.plugins('./node_modules', { matching: 'mycli-*' })
|
|
cli.plugins('./plugins', { matching: '*.js' })
|
|
```
|
|
|
|
3. **Plugin examples:**
|
|
- Reference: `examples/plugin-system/custom-plugin.ts`
|
|
- See: `templates/plugins/plugin-template.ts.ejs`
|
|
|
|
### Print Utilities
|
|
|
|
1. **Colorful output:**
|
|
```typescript
|
|
print.info('Information message')
|
|
print.success('Success message')
|
|
print.warning('Warning message')
|
|
print.error('Error message')
|
|
print.highlight('Highlighted text')
|
|
print.muted('Muted text')
|
|
```
|
|
|
|
2. **Spinners and progress:**
|
|
```typescript
|
|
const spinner = print.spin('Loading...')
|
|
await doWork()
|
|
spinner.succeed('Done!')
|
|
|
|
// Or fail
|
|
spinner.fail('Something went wrong')
|
|
```
|
|
|
|
3. **Tables and formatting:**
|
|
```typescript
|
|
print.table([
|
|
['Name', 'Age'],
|
|
['John', '30'],
|
|
['Jane', '25']
|
|
])
|
|
```
|
|
|
|
### System Commands
|
|
|
|
1. **Execute external commands:**
|
|
```typescript
|
|
const output = await system.run('npm install')
|
|
const result = await system.exec('git status')
|
|
|
|
// Spawn with options
|
|
await system.spawn('npm run build', { stdio: 'inherit' })
|
|
```
|
|
|
|
2. **Check command availability:**
|
|
```typescript
|
|
const hasGit = await system.which('git')
|
|
```
|
|
|
|
### File Patching
|
|
|
|
1. **Modify existing files:**
|
|
```typescript
|
|
// Add line after pattern
|
|
await patching.update('package.json', (content) => {
|
|
const pkg = JSON.parse(content)
|
|
pkg.scripts.build = 'tsc'
|
|
return JSON.stringify(pkg, null, 2)
|
|
})
|
|
|
|
// Insert import statement
|
|
await patching.insert('src/index.ts', 'import { Router } from "express"')
|
|
```
|
|
|
|
## Validation Scripts
|
|
|
|
Use these scripts to validate Gluegun CLI implementations:
|
|
|
|
- `scripts/validate-cli-structure.sh` - Check directory structure
|
|
- `scripts/validate-commands.sh` - Verify command format
|
|
- `scripts/validate-templates.sh` - Check template syntax
|
|
- `scripts/test-cli-build.sh` - Run full CLI build test
|
|
|
|
## Templates
|
|
|
|
### Command Templates
|
|
- `templates/commands/basic-command.ts.ejs` - Simple command
|
|
- `templates/commands/generator-command.ts.ejs` - File generator
|
|
- `templates/commands/api-command.ts.ejs` - HTTP interaction
|
|
|
|
### Extension Templates
|
|
- `templates/extensions/custom-toolbox.ts.ejs` - Toolbox extension
|
|
- `templates/extensions/helper-functions.ts.ejs` - Utility functions
|
|
|
|
### Plugin Templates
|
|
- `templates/plugins/plugin-template.ts.ejs` - Plugin structure
|
|
- `templates/plugins/plugin-with-commands.ts.ejs` - Plugin with commands
|
|
|
|
### Toolbox Templates
|
|
- `templates/toolbox/template-examples.ejs` - Template patterns
|
|
- `templates/toolbox/prompt-examples.ts.ejs` - Prompt patterns
|
|
- `templates/toolbox/filesystem-examples.ts.ejs` - Filesystem patterns
|
|
|
|
## Examples
|
|
|
|
### Basic CLI Example
|
|
See `examples/basic-cli/` for complete working CLI:
|
|
- Simple command structure
|
|
- Template generation
|
|
- User prompts
|
|
- File operations
|
|
|
|
### Plugin System Example
|
|
See `examples/plugin-system/` for extensible architecture:
|
|
- Plugin loading
|
|
- Custom toolbox extensions
|
|
- Command composition
|
|
|
|
### Template Generator Example
|
|
See `examples/template-generator/` for advanced patterns:
|
|
- Multi-file generation
|
|
- Conditional templates
|
|
- Helper functions
|
|
|
|
## Best Practices
|
|
|
|
1. **Command Organization**
|
|
- One command per file
|
|
- Group related commands in subdirectories
|
|
- Use clear, descriptive command names
|
|
|
|
2. **Template Design**
|
|
- Keep templates simple and focused
|
|
- Use helper functions for complex logic
|
|
- Document template variables
|
|
|
|
3. **Error Handling**
|
|
- Check HTTP response status
|
|
- Validate user input from prompts
|
|
- Provide helpful error messages
|
|
|
|
4. **Plugin Architecture**
|
|
- Make plugins optional
|
|
- Document plugin interfaces
|
|
- Version plugin APIs
|
|
|
|
5. **Testing**
|
|
- Test commands in isolation
|
|
- Mock filesystem operations
|
|
- Validate template output
|
|
|
|
## Security Considerations
|
|
|
|
- Never hardcode API keys in templates
|
|
- Use environment variables for secrets
|
|
- Validate all user input from prompts
|
|
- Sanitize file paths from parameters
|
|
- Check filesystem permissions before operations
|
|
|
|
## Requirements
|
|
|
|
- Node.js 14+ or TypeScript 4+
|
|
- Gluegun package: `npm install gluegun`
|
|
- EJS for templates (included)
|
|
- fs-jetpack for filesystem (included)
|
|
- enquirer for prompts (included)
|
|
|
|
## Related Documentation
|
|
|
|
- Gluegun Official Docs: https://infinitered.github.io/gluegun/
|
|
- GitHub Repository: https://github.com/infinitered/gluegun
|
|
- EJS Templates: https://ejs.co/
|
|
- fs-jetpack: https://github.com/szwacz/fs-jetpack
|
|
|
|
---
|
|
|
|
**Purpose**: Enable rapid CLI development with Gluegun patterns and best practices
|
|
**Load when**: Building CLI tools, command structures, template systems, or plugin architectures
|