elsabro 2.1.0 → 2.3.0

package/skills/cli-tool.md

@@ -0,0 +1,884 @@
+---
+name: cli-tool
+description: Crear herramientas CLI profesionales con Node.js, Commander.js, publicacion en npm y testing
+tags: [cli, command-line, npm, node, terminal, automation]
+difficulty: intermediate
+estimated_time: 25min
+---
+
+# Skill: CLI Tool
+
+<when_to_use>
+Usar cuando el usuario menciona:
+- "crear CLI"
+- "herramienta de terminal"
+- "comando npm"
+- "script interactivo"
+- "utilidad de linea de comandos"
+- "tool para consola"
+- "automatizar con scripts"
+</when_to_use>
+
+<pre_requisites>
+## Pre-requisitos
+- Node.js 20+
+- Cuenta npm (para publicar)
+- Conocimiento basico de JavaScript/TypeScript
+</pre_requisites>
+
+<tech_stack>
+## Stack Tecnologico
+| Categoria | Tecnologia | Version |
+|-----------|------------|---------|
+| Runtime | Node.js | 20.x |
+| CLI Framework | Commander.js | 12.x |
+| Colors | Chalk | 5.x |
+| Prompts | Inquirer | 9.x |
+| Testing | Vitest | 2.x |
+| Build | tsup | 8.x |
+| Linting | ESLint | 9.x |
+</tech_stack>
+
+<project_structure>
+## Estructura de Proyecto
+```
+my-cli/
+├── src/
+│   ├── index.ts          # Entry point
+│   ├── commands/
+│   │   ├── index.ts      # Export all commands
+│   │   ├── init.ts       # Init command
+│   │   └── run.ts        # Run command
+│   ├── lib/
+│   │   ├── config.ts     # Configuration loader
+│   │   ├── logger.ts     # Styled console output
+│   │   └── utils.ts      # Helper functions
+│   └── types.ts          # TypeScript types
+├── tests/
+│   ├── commands.test.ts  # Command tests
+│   └── utils.test.ts     # Utility tests
+├── bin/
+│   └── cli.js            # Shebang wrapper
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+├── vitest.config.ts
+└── README.md
+```
+</project_structure>
+
+<setup_steps>
+## Pasos de Setup
+
+### 1. Inicializar Proyecto
+
+```bash
+mkdir my-cli && cd my-cli
+npm init -y
+```
+
+### 2. Instalar Dependencias
+
+```bash
+# Dependencias de produccion
+npm install commander@12 chalk@5 inquirer@9
+
+# Dependencias de desarrollo
+npm install -D typescript @types/node @types/inquirer tsup vitest
+```
+
+### 3. Configurar TypeScript
+
+**tsconfig.json:**
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+### 4. Configurar tsup
+
+**tsup.config.ts:**
+```typescript
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  target: 'node20',
+  outDir: 'dist',
+  shims: true,
+});
+```
+
+### 5. Configurar Vitest
+
+**vitest.config.ts:**
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});
+```
+
+### 6. Crear Entry Point
+
+**src/index.ts:**
+```typescript
+#!/usr/bin/env node
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { initCommand } from './commands/init.js';
+import { runCommand } from './commands/run.js';
+
+const program = new Command();
+
+program
+  .name('my-cli')
+  .description('A professional CLI tool')
+  .version('1.0.0');
+
+// Register commands
+program.addCommand(initCommand);
+program.addCommand(runCommand);
+
+// Error handling
+program.exitOverride();
+
+try {
+  await program.parseAsync(process.argv);
+} catch (error) {
+  if (error instanceof Error) {
+    console.error(chalk.red('Error:'), error.message);
+    process.exit(1);
+  }
+}
+```
+
+### 7. Crear Comandos
+
+**src/commands/init.ts:**
+```typescript
+import { Command } from 'commander';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { logger } from '../lib/logger.js';
+
+interface InitOptions {
+  name?: string;
+  template?: string;
+  force?: boolean;
+}
+
+export const initCommand = new Command('init')
+  .description('Initialize a new project')
+  .option('-n, --name <name>', 'Project name')
+  .option('-t, --template <template>', 'Template to use', 'default')
+  .option('-f, --force', 'Overwrite existing files', false)
+  .action(async (options: InitOptions) => {
+    logger.info('Initializing project...');
+
+    // Interactive prompts if name not provided
+    let projectName = options.name;
+    if (!projectName) {
+      const answers = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'name',
+          message: 'Project name:',
+          default: 'my-project',
+          validate: (input: string) => {
+            if (/^[a-z0-9-]+$/.test(input)) return true;
+            return 'Name must be lowercase with hyphens only';
+          },
+        },
+      ]);
+      projectName = answers.name;
+    }
+
+    // Template selection
+    const { confirmTemplate } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirmTemplate',
+        message: `Use template "${options.template}"?`,
+        default: true,
+      },
+    ]);
+
+    if (!confirmTemplate) {
+      const { template } = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'template',
+          message: 'Select template:',
+          choices: ['default', 'minimal', 'full'],
+        },
+      ]);
+      options.template = template;
+    }
+
+    logger.success(`Project "${projectName}" initialized with ${options.template} template`);
+  });
+```
+
+**src/commands/run.ts:**
+```typescript
+import { Command } from 'commander';
+import { logger } from '../lib/logger.js';
+
+interface RunOptions {
+  watch?: boolean;
+  verbose?: boolean;
+}
+
+export const runCommand = new Command('run')
+  .description('Run the project')
+  .argument('[script]', 'Script to run', 'start')
+  .option('-w, --watch', 'Watch mode', false)
+  .option('-v, --verbose', 'Verbose output', false)
+  .action(async (script: string, options: RunOptions) => {
+    logger.info(`Running script: ${script}`);
+
+    if (options.verbose) {
+      logger.debug('Options:', JSON.stringify(options, null, 2));
+    }
+
+    if (options.watch) {
+      logger.info('Watch mode enabled');
+    }
+
+    // Simulate running
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    logger.success('Script completed successfully');
+  });
+```
+
+**src/commands/index.ts:**
+```typescript
+export { initCommand } from './init.js';
+export { runCommand } from './run.js';
+```
+
+### 8. Crear Utilities
+
+**src/lib/logger.ts:**
+```typescript
+import chalk from 'chalk';
+
+export const logger = {
+  info: (message: string, ...args: unknown[]) => {
+    console.log(chalk.blue('info'), message, ...args);
+  },
+  success: (message: string, ...args: unknown[]) => {
+    console.log(chalk.green('success'), message, ...args);
+  },
+  warn: (message: string, ...args: unknown[]) => {
+    console.log(chalk.yellow('warn'), message, ...args);
+  },
+  error: (message: string, ...args: unknown[]) => {
+    console.error(chalk.red('error'), message, ...args);
+  },
+  debug: (message: string, ...args: unknown[]) => {
+    if (process.env.DEBUG) {
+      console.log(chalk.gray('debug'), message, ...args);
+    }
+  },
+};
+```
+
+**src/lib/config.ts:**
+```typescript
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface Config {
+  name: string;
+  version: string;
+  settings: Record<string, unknown>;
+}
+
+const CONFIG_FILE = '.myclirc.json';
+
+export function loadConfig(cwd: string = process.cwd()): Config | null {
+  const configPath = join(cwd, CONFIG_FILE);
+
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    return JSON.parse(content) as Config;
+  } catch {
+    return null;
+  }
+}
+
+export function getDefaultConfig(): Config {
+  return {
+    name: 'my-project',
+    version: '1.0.0',
+    settings: {},
+  };
+}
+```
+
+**src/lib/utils.ts:**
+```typescript
+export function isGitRepo(): boolean {
+  try {
+    const { spawnSync } = require('node:child_process');
+    const result = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'ignore' });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+export async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function formatBytes(bytes: number): string {
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let unitIndex = 0;
+  let value = bytes;
+
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex++;
+  }
+
+  return `${value.toFixed(2)} ${units[unitIndex]}`;
+}
+```
+
+**src/types.ts:**
+```typescript
+export interface CliContext {
+  cwd: string;
+  verbose: boolean;
+  config: import('./lib/config.js').Config | null;
+}
+
+export interface CommandResult {
+  success: boolean;
+  message?: string;
+  data?: unknown;
+}
+```
+
+### 9. Crear Bin Wrapper
+
+**bin/cli.js:**
+```javascript
+#!/usr/bin/env node
+import '../dist/index.js';
+```
+
+### 10. Configurar package.json
+
+**package.json:**
+```json
+{
+  "name": "my-cli",
+  "version": "1.0.0",
+  "description": "A professional CLI tool",
+  "type": "module",
+  "bin": {
+    "my-cli": "./bin/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": ["cli", "tool", "command-line"],
+  "author": "Your Name",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/username/my-cli"
+  }
+}
+```
+
+### 11. Crear Tests
+
+**tests/commands.test.ts:**
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Command } from 'commander';
+
+describe('CLI Commands', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('init command', () => {
+    it('should accept name option', async () => {
+      const program = new Command();
+      let capturedOptions: Record<string, unknown> = {};
+
+      program
+        .command('init')
+        .option('-n, --name <name>', 'Project name')
+        .action((options) => {
+          capturedOptions = options;
+        });
+
+      await program.parseAsync(['node', 'cli', 'init', '-n', 'test-project']);
+      expect(capturedOptions.name).toBe('test-project');
+    });
+
+    it('should use default template', async () => {
+      const program = new Command();
+      let capturedOptions: Record<string, unknown> = {};
+
+      program
+        .command('init')
+        .option('-t, --template <template>', 'Template', 'default')
+        .action((options) => {
+          capturedOptions = options;
+        });
+
+      await program.parseAsync(['node', 'cli', 'init']);
+      expect(capturedOptions.template).toBe('default');
+    });
+  });
+
+  describe('run command', () => {
+    it('should accept script argument', async () => {
+      const program = new Command();
+      let capturedScript = '';
+
+      program
+        .command('run')
+        .argument('[script]', 'Script to run', 'start')
+        .action((script) => {
+          capturedScript = script;
+        });
+
+      await program.parseAsync(['node', 'cli', 'run', 'build']);
+      expect(capturedScript).toBe('build');
+    });
+
+    it('should use default script when not provided', async () => {
+      const program = new Command();
+      let capturedScript = '';
+
+      program
+        .command('run')
+        .argument('[script]', 'Script to run', 'start')
+        .action((script) => {
+          capturedScript = script;
+        });
+
+      await program.parseAsync(['node', 'cli', 'run']);
+      expect(capturedScript).toBe('start');
+    });
+  });
+});
+```
+
+**tests/utils.test.ts:**
+```typescript
+import { describe, it, expect } from 'vitest';
+import { slugify, formatBytes } from '../src/lib/utils.js';
+
+describe('Utils', () => {
+  describe('slugify', () => {
+    it('should convert to lowercase', () => {
+      expect(slugify('Hello World')).toBe('hello-world');
+    });
+
+    it('should replace spaces with hyphens', () => {
+      expect(slugify('my project name')).toBe('my-project-name');
+    });
+
+    it('should remove special characters', () => {
+      expect(slugify('hello@world!')).toBe('hello-world');
+    });
+
+    it('should remove leading and trailing hyphens', () => {
+      expect(slugify('--hello--')).toBe('hello');
+    });
+  });
+
+  describe('formatBytes', () => {
+    it('should format bytes', () => {
+      expect(formatBytes(500)).toBe('500.00 B');
+    });
+
+    it('should format kilobytes', () => {
+      expect(formatBytes(1024)).toBe('1.00 KB');
+    });
+
+    it('should format megabytes', () => {
+      expect(formatBytes(1048576)).toBe('1.00 MB');
+    });
+
+    it('should format gigabytes', () => {
+      expect(formatBytes(1073741824)).toBe('1.00 GB');
+    });
+  });
+});
+```
+</setup_steps>
+
+<verification>
+## Verificacion
+
+### Probar Localmente
+
+```bash
+# Build del proyecto
+npm run build
+
+# Link global para testing
+npm link
+
+# Probar comandos
+my-cli --help
+my-cli init --help
+my-cli init -n test-project
+my-cli run build --verbose
+
+# Desinstalar link
+npm unlink -g my-cli
+```
+
+### Ejecutar Tests
+
+```bash
+# Tests una vez
+npm run test
+
+# Tests en modo watch
+npm run test:watch
+
+# Tests con coverage
+npm run test:coverage
+```
+
+### Verificar Build
+
+```bash
+# Verificar que compila
+npm run build
+
+# Verificar estructura de dist
+ls -la dist/
+
+# Verificar dry-run de publicacion
+npm publish --dry-run
+```
+</verification>
+
+<publishing>
+## Publicar en npm
+
+### Preparacion
+
+1. **Verificar nombre disponible:**
+```bash
+npm search my-cli
+# O visitar https://www.npmjs.com/package/my-cli
+```
+
+2. **Login en npm:**
+```bash
+npm login
+# Seguir prompts de autenticacion
+```
+
+3. **Verificar configuracion:**
+```bash
+npm whoami
+npm config list
+```
+
+### Publicacion
+
+```bash
+# Primera publicacion
+npm publish
+
+# Si es scoped package (@usuario/my-cli)
+npm publish --access public
+```
+
+### Versionado
+
+```bash
+# Patch: 1.0.0 -> 1.0.1 (bug fixes)
+npm version patch
+
+# Minor: 1.0.0 -> 1.1.0 (new features)
+npm version minor
+
+# Major: 1.0.0 -> 2.0.0 (breaking changes)
+npm version major
+
+# Publicar nueva version
+npm publish
+```
+
+### Tags
+
+```bash
+# Publicar como beta
+npm publish --tag beta
+
+# Publicar como next
+npm publish --tag next
+
+# Instalar version especifica
+npm install my-cli@beta
+```
+</publishing>
+
+<common_issues>
+## Problemas Comunes
+
+### Shebang no funciona
+
+**Problema:** Error "command not found" o permisos denegados.
+
+**Solucion:**
+```bash
+# Verificar shebang en bin/cli.js
+# Debe ser: #!/usr/bin/env node
+
+# Dar permisos de ejecucion
+chmod +x bin/cli.js
+```
+
+### ESM vs CommonJS
+
+**Problema:** "Cannot use import statement outside a module"
+
+**Solucion:**
+```json
+// package.json
+{
+  "type": "module"
+}
+```
+
+### Chalk no muestra colores
+
+**Problema:** Output sin colores en terminal.
+
+**Causas:**
+- Variable `NO_COLOR` activa
+- Terminal no soporta colores
+- Stdout no es TTY
+
+**Solucion:**
+```typescript
+import chalk from 'chalk';
+
+// Forzar colores (no recomendado generalmente)
+const forceChalk = new chalk.Instance({ level: 3 });
+```
+
+### Inquirer no funciona en CI
+
+**Problema:** Prompts cuelgan en CI/CD.
+
+**Solucion:**
+```typescript
+// Detectar CI y usar defaults
+const isCI = process.env.CI === 'true';
+
+if (isCI) {
+  // Usar valores por defecto sin prompts
+  return defaultOptions;
+}
+
+// Prompts interactivos
+const answers = await inquirer.prompt([...]);
+```
+
+### TypeScript paths no resuelven
+
+**Problema:** Imports con `@/` no funcionan.
+
+**Solucion:**
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  // ... otras opciones
+  esbuildOptions(options) {
+    options.alias = {
+      '@': './src',
+    };
+  },
+});
+```
+
+### Build falla con dependencias nativas
+
+**Problema:** Modulos nativos causan error en build.
+
+**Solucion:**
+```typescript
+// tsup.config.ts
+export default defineConfig({
+  // Excluir modulos nativos del bundle
+  external: ['fsevents'],
+  noExternal: [], // Incluir todo lo demas
+});
+```
+</common_issues>
+
+<best_practices>
+## Mejores Practicas
+
+### Estructura de Comandos
+
+```typescript
+// Patron recomendado para comandos complejos
+export function createCommand(): Command {
+  return new Command('name')
+    .description('...')
+    .option('...')
+    .action(async (options) => {
+      try {
+        await executeCommand(options);
+      } catch (error) {
+        handleError(error);
+        process.exit(1);
+      }
+    });
+}
+```
+
+### Manejo de Errores
+
+```typescript
+// Errores con codigos de salida apropiados
+process.exit(0); // Exito
+process.exit(1); // Error general
+process.exit(2); // Mal uso del comando
+```
+
+### Configuracion Progresiva
+
+```typescript
+// Prioridad: CLI args > env vars > config file > defaults
+function getConfig(cliOptions: Options): Config {
+  const fileConfig = loadConfigFile();
+  const envConfig = loadEnvConfig();
+
+  return {
+    ...getDefaults(),
+    ...fileConfig,
+    ...envConfig,
+    ...cliOptions,
+  };
+}
+```
+
+### Output Amigable
+
+```typescript
+// Usar spinners para operaciones largas
+import ora from 'ora';
+
+const spinner = ora('Loading...').start();
+await longOperation();
+spinner.succeed('Done!');
+```
+</best_practices>
+
+<examples>
+## Ejemplos de Uso
+
+### CLI Basico
+
+```bash
+# Crear proyecto
+my-cli init -n my-app
+
+# Ejecutar script
+my-cli run dev --watch
+
+# Ver ayuda
+my-cli --help
+```
+
+### CLI con Config
+
+```bash
+# Generar configuracion
+my-cli config init
+
+# Mostrar configuracion actual
+my-cli config show
+
+# Modificar valor
+my-cli config set key value
+```
+
+### CLI con Subcomandos
+
+```bash
+# Comandos anidados
+my-cli project create
+my-cli project list
+my-cli project delete <id>
+```
+</examples>