cmp-standards 2.6.0 → 2.8.0-alpha

package/standards/tools/tool-design.md

@@ -1,297 +1,297 @@
-# Diseño de Tools Internas
-
-## Qué es una Tool
-
-Una **Tool** es una utilidad reutilizable que automatiza tareas comunes. Diferente de MCP tools, estas son funciones/scripts internos del proyecto.
-
-## Categorías
-
-### 1. CLI Tools
-
-Scripts ejecutables desde terminal:
-
-```
-scripts/
-├── checks/           # Validaciones
-│   ├── typecheck.mjs
-│   └── lint.mjs
-├── migration/        # Migraciones
-│   └── run-migration.mjs
-└── ai/               # AI-related
-    └── generate.mjs
-```
-
-### 2. Build Tools
-
-Parte del proceso de build:
-
-```typescript
-// tools/build/
-├── compile.ts
-├── bundle.ts
-└── optimize.ts
-```
-
-### 3. Dev Tools
-
-Para desarrollo local:
-
-```typescript
-// tools/dev/
-├── mock-server.ts
-├── seed-db.ts
-└── test-utils.ts
-```
-
-## Estructura de una CLI Tool
-
-```typescript
-#!/usr/bin/env node
-// scripts/my-tool.mjs
-
-import { parseArgs } from 'node:util'
-
-// 1. Parse arguments
-const { values, positionals } = parseArgs({
-  options: {
-    verbose: { type: 'boolean', short: 'v', default: false },
-    output: { type: 'string', short: 'o' }
-  },
-  allowPositionals: true
-})
-
-// 2. Validate input
-if (positionals.length === 0) {
-  console.error('Usage: my-tool <input> [--verbose] [--output path]')
-  process.exit(1)
-}
-
-// 3. Execute
-async function main() {
-  try {
-    const result = await doWork(positionals[0], values)
-    console.log('Done:', result)
-    process.exit(0)
-  } catch (error) {
-    console.error('Error:', error.message)
-    process.exit(1)
-  }
-}
-
-main()
-```
-
-## Patrones Recomendados
-
-### Patrón: Reporter
-
-Para tools que analizan y reportan:
-
-```typescript
-interface ReportResult {
-  passed: boolean
-  items: ReportItem[]
-  summary: string
-}
-
-async function analyze(path: string): Promise<ReportResult> {
-  const items = await scanFiles(path)
-  const issues = items.filter(i => !i.valid)
-
-  return {
-    passed: issues.length === 0,
-    items: issues,
-    summary: `Found ${issues.length} issues in ${items.length} files`
-  }
-}
-```
-
-### Patrón: Transformer
-
-Para tools que transforman archivos:
-
-```typescript
-interface TransformOptions {
-  input: string
-  output: string
-  dryRun?: boolean
-}
-
-async function transform(options: TransformOptions): Promise<void> {
-  const content = await readFile(options.input, 'utf-8')
-  const transformed = applyTransformations(content)
-
-  if (options.dryRun) {
-    console.log('Would write to:', options.output)
-    console.log(transformed)
-    return
-  }
-
-  await writeFile(options.output, transformed)
-}
-```
-
-### Patrón: Batch Processor
-
-Para operaciones sobre múltiples archivos:
-
-```typescript
-async function processBatch(
-  files: string[],
-  processor: (file: string) => Promise<void>
-): Promise<BatchResult> {
-  const results = await Promise.allSettled(
-    files.map(processor)
-  )
-
-  return {
-    total: files.length,
-    succeeded: results.filter(r => r.status === 'fulfilled').length,
-    failed: results.filter(r => r.status === 'rejected').length
-  }
-}
-```
-
-## Configuración
-
-### En package.json
-
-```json
-{
-  "scripts": {
-    "tool:analyze": "node scripts/analyze.mjs",
-    "tool:migrate": "node scripts/migrate.mjs",
-    "tool:generate": "node scripts/generate.mjs"
-  }
-}
-```
-
-### Con argumentos
-
-```json
-{
-  "scripts": {
-    "lint:all": "npm run lint -- --fix",
-    "check:verbose": "npm run check -- --verbose"
-  }
-}
-```
-
-## Logging
-
-```typescript
-// Usar chalk para colores
-import chalk from 'chalk'
-
-function log(level: 'info' | 'warn' | 'error', msg: string) {
-  const prefix = {
-    info: chalk.blue('ℹ'),
-    warn: chalk.yellow('⚠'),
-    error: chalk.red('✖')
-  }
-  console.error(`${prefix[level]} ${msg}`)
-}
-
-// Usar stderr para logs, stdout para output
-console.error('[INFO] Processing...')  // logs
-console.log(JSON.stringify(result))    // output (puede ser piped)
-```
-
-## Testing Tools
-
-```typescript
-import { describe, it, expect } from 'vitest'
-import { execSync } from 'child_process'
-
-describe('my-tool', () => {
-  it('should process valid input', () => {
-    const result = execSync('node scripts/my-tool.mjs input.txt')
-    expect(result.toString()).toContain('Done')
-  })
-
-  it('should fail on invalid input', () => {
-    expect(() => {
-      execSync('node scripts/my-tool.mjs')
-    }).toThrow()
-  })
-})
-```
-
-## Anti-Patterns
-
-### NO: Hardcoded paths
-
-```typescript
-// MAL
-const config = await readFile('/Users/carlos/project/config.json')
-
-// BIEN
-const config = await readFile(path.join(process.cwd(), 'config.json'))
-```
-
-### NO: Silent failures
-
-```typescript
-// MAL
-try {
-  await doWork()
-} catch {
-  // silencio
-}
-
-// BIEN
-try {
-  await doWork()
-} catch (error) {
-  console.error('Failed:', error.message)
-  process.exit(1)
-}
-```
-
-### NO: Sin validación de input
-
-```typescript
-// MAL
-async function main() {
-  await processFile(process.argv[2])
-}
-
-// BIEN
-async function main() {
-  const file = process.argv[2]
-  if (!file) {
-    console.error('Usage: tool <file>')
-    process.exit(1)
-  }
-  if (!existsSync(file)) {
-    console.error(`File not found: ${file}`)
-    process.exit(1)
-  }
-  await processFile(file)
-}
-```
-
-## Documentación
-
-Cada tool debe tener:
-
-1. **JSDoc header** con descripción y ejemplos
-2. **--help** flag que explica uso
-3. **README** si es compleja
-
-```typescript
-/**
- * @file Analyze TypeScript files for common issues
- * @example
- * ```bash
- * # Analyze single file
- * npm run tool:analyze src/index.ts
- *
- * # Analyze directory
- * npm run tool:analyze src/ --recursive
- *
- * # Output JSON
- * npm run tool:analyze src/ --format json > report.json
- * ```
- */
-```
+# Diseño de Tools Internas
+
+## Qué es una Tool
+
+Una **Tool** es una utilidad reutilizable que automatiza tareas comunes. Diferente de MCP tools, estas son funciones/scripts internos del proyecto.
+
+## Categorías
+
+### 1. CLI Tools
+
+Scripts ejecutables desde terminal:
+
+```
+scripts/
+├── checks/           # Validaciones
+│   ├── typecheck.mjs
+│   └── lint.mjs
+├── migration/        # Migraciones
+│   └── run-migration.mjs
+└── ai/               # AI-related
+    └── generate.mjs
+```
+
+### 2. Build Tools
+
+Parte del proceso de build:
+
+```typescript
+// tools/build/
+├── compile.ts
+├── bundle.ts
+└── optimize.ts
+```
+
+### 3. Dev Tools
+
+Para desarrollo local:
+
+```typescript
+// tools/dev/
+├── mock-server.ts
+├── seed-db.ts
+└── test-utils.ts
+```
+
+## Estructura de una CLI Tool
+
+```typescript
+#!/usr/bin/env node
+// scripts/my-tool.mjs
+
+import { parseArgs } from 'node:util'
+
+// 1. Parse arguments
+const { values, positionals } = parseArgs({
+  options: {
+    verbose: { type: 'boolean', short: 'v', default: false },
+    output: { type: 'string', short: 'o' }
+  },
+  allowPositionals: true
+})
+
+// 2. Validate input
+if (positionals.length === 0) {
+  console.error('Usage: my-tool <input> [--verbose] [--output path]')
+  process.exit(1)
+}
+
+// 3. Execute
+async function main() {
+  try {
+    const result = await doWork(positionals[0], values)
+    console.log('Done:', result)
+    process.exit(0)
+  } catch (error) {
+    console.error('Error:', error.message)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+## Patrones Recomendados
+
+### Patrón: Reporter
+
+Para tools que analizan y reportan:
+
+```typescript
+interface ReportResult {
+  passed: boolean
+  items: ReportItem[]
+  summary: string
+}
+
+async function analyze(path: string): Promise<ReportResult> {
+  const items = await scanFiles(path)
+  const issues = items.filter(i => !i.valid)
+
+  return {
+    passed: issues.length === 0,
+    items: issues,
+    summary: `Found ${issues.length} issues in ${items.length} files`
+  }
+}
+```
+
+### Patrón: Transformer
+
+Para tools que transforman archivos:
+
+```typescript
+interface TransformOptions {
+  input: string
+  output: string
+  dryRun?: boolean
+}
+
+async function transform(options: TransformOptions): Promise<void> {
+  const content = await readFile(options.input, 'utf-8')
+  const transformed = applyTransformations(content)
+
+  if (options.dryRun) {
+    console.log('Would write to:', options.output)
+    console.log(transformed)
+    return
+  }
+
+  await writeFile(options.output, transformed)
+}
+```
+
+### Patrón: Batch Processor
+
+Para operaciones sobre múltiples archivos:
+
+```typescript
+async function processBatch(
+  files: string[],
+  processor: (file: string) => Promise<void>
+): Promise<BatchResult> {
+  const results = await Promise.allSettled(
+    files.map(processor)
+  )
+
+  return {
+    total: files.length,
+    succeeded: results.filter(r => r.status === 'fulfilled').length,
+    failed: results.filter(r => r.status === 'rejected').length
+  }
+}
+```
+
+## Configuración
+
+### En package.json
+
+```json
+{
+  "scripts": {
+    "tool:analyze": "node scripts/analyze.mjs",
+    "tool:migrate": "node scripts/migrate.mjs",
+    "tool:generate": "node scripts/generate.mjs"
+  }
+}
+```
+
+### Con argumentos
+
+```json
+{
+  "scripts": {
+    "lint:all": "npm run lint -- --fix",
+    "check:verbose": "npm run check -- --verbose"
+  }
+}
+```
+
+## Logging
+
+```typescript
+// Usar chalk para colores
+import chalk from 'chalk'
+
+function log(level: 'info' | 'warn' | 'error', msg: string) {
+  const prefix = {
+    info: chalk.blue('ℹ'),
+    warn: chalk.yellow('⚠'),
+    error: chalk.red('✖')
+  }
+  console.error(`${prefix[level]} ${msg}`)
+}
+
+// Usar stderr para logs, stdout para output
+console.error('[INFO] Processing...')  // logs
+console.log(JSON.stringify(result))    // output (puede ser piped)
+```
+
+## Testing Tools
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { execSync } from 'child_process'
+
+describe('my-tool', () => {
+  it('should process valid input', () => {
+    const result = execSync('node scripts/my-tool.mjs input.txt')
+    expect(result.toString()).toContain('Done')
+  })
+
+  it('should fail on invalid input', () => {
+    expect(() => {
+      execSync('node scripts/my-tool.mjs')
+    }).toThrow()
+  })
+})
+```
+
+## Anti-Patterns
+
+### NO: Hardcoded paths
+
+```typescript
+// MAL
+const config = await readFile('/Users/carlos/project/config.json')
+
+// BIEN
+const config = await readFile(path.join(process.cwd(), 'config.json'))
+```
+
+### NO: Silent failures
+
+```typescript
+// MAL
+try {
+  await doWork()
+} catch {
+  // silencio
+}
+
+// BIEN
+try {
+  await doWork()
+} catch (error) {
+  console.error('Failed:', error.message)
+  process.exit(1)
+}
+```
+
+### NO: Sin validación de input
+
+```typescript
+// MAL
+async function main() {
+  await processFile(process.argv[2])
+}
+
+// BIEN
+async function main() {
+  const file = process.argv[2]
+  if (!file) {
+    console.error('Usage: tool <file>')
+    process.exit(1)
+  }
+  if (!existsSync(file)) {
+    console.error(`File not found: ${file}`)
+    process.exit(1)
+  }
+  await processFile(file)
+}
+```
+
+## Documentación
+
+Cada tool debe tener:
+
+1. **JSDoc header** con descripción y ejemplos
+2. **--help** flag que explica uso
+3. **README** si es compleja
+
+```typescript
+/**
+ * @file Analyze TypeScript files for common issues
+ * @example
+ * ```bash
+ * # Analyze single file
+ * npm run tool:analyze src/index.ts
+ *
+ * # Analyze directory
+ * npm run tool:analyze src/ --recursive
+ *
+ * # Output JSON
+ * npm run tool:analyze src/ --format json > report.json
+ * ```
+ */
+```