gh-vanman2024-cli-builder-plugins-cli-builder/skills/gluegun-patterns/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
gluegun-patterns	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.	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:

   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:

   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:

   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):

   // 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:

   filesystem.path('src', 'commands') // Join paths
   filesystem.cwd() // Current directory
   filesystem.separator // OS-specific separator
   

HTTP Utilities

1. API interactions:

   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:

   if (!response.ok) {
     print.error(response.problem)
     return
   }
   

Interactive Prompts

1. User input patterns:

   // 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:

   // Plugin structure
   export default (toolbox) => {
     const { filesystem, template } = toolbox
   
     // Add custom extension
     toolbox.myFeature = {
       doSomething: () => { /* ... */ }
     }
   }
   

2. Load plugins:

   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:

   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:

   const spinner = print.spin('Loading...')
   await doWork()
   spinner.succeed('Done!')
   
   // Or fail
   spinner.fail('Something went wrong')
   

3. Tables and formatting:

   print.table([
     ['Name', 'Age'],
     ['John', '30'],
     ['Jane', '25']
   ])
   

System Commands

1. Execute external commands:

   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:

   const hasGit = await system.which('git')
   

File Patching

1. Modify existing files:

   // 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