@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/cli-development.md

@@ -0,0 +1,296 @@
+---
+name: cli-development
+description: Build CLI tools — Commander.js, Inquirer prompts, chalk output, progress bars, configuration, and packaging.
+---
+
+# CLI Development Patterns
+
+## When to Use
+
+Apply these patterns when building command-line tools in Node.js. Covers
+argument parsing with Commander, interactive prompts with Inquirer, styled
+output with chalk, progress indicators, configuration management, and
+packaging for distribution via npm or standalone binaries. Use this skill
+when creating developer tools, build scripts, or automation CLIs.
+
+## How It Works
+
+### 1. Commander.js — Argument Parsing
+
+```typescript
+import { Command, Option } from 'commander';
+
+const program = new Command();
+
+program
+  .name('mycli')
+  .version('1.0.0')
+  .description('A developer productivity tool');
+
+// Subcommand with options and arguments
+program
+  .command('deploy')
+  .description('Deploy to environment')
+  .argument('<environment>', 'Target environment (staging|production)')
+  .option('-f, --force', 'Skip confirmation prompt')
+  .option('-t, --tag <tag>', 'Deploy specific tag', 'latest')
+  .option('--dry-run', 'Show what would be deployed without deploying')
+  .addOption(
+    new Option('--strategy <strategy>', 'Deployment strategy')
+      .choices(['rolling', 'blue-green', 'canary'])
+      .default('rolling')
+  )
+  .action(async (environment, options) => {
+    if (!options.force && environment === 'production') {
+      const confirmed = await confirmProduction();
+      if (!confirmed) process.exit(0);
+    }
+    await deploy(environment, options);
+  });
+
+// Global options
+program
+  .option('--json', 'Output as JSON')
+  .option('-v, --verbose', 'Verbose logging')
+  .hook('preAction', (thisCommand) => {
+    if (thisCommand.opts().verbose) {
+      setLogLevel('debug');
+    }
+  });
+
+program.parse();
+```
+
+### 2. Inquirer — Interactive Prompts
+
+```typescript
+import { input, select, confirm, checkbox, password } from '@inquirer/prompts';
+
+async function setupProject(): Promise<ProjectConfig> {
+  const name = await input({
+    message: 'Project name:',
+    default: path.basename(process.cwd()),
+    validate: (val) => /^[a-z0-9-]+$/.test(val) || 'Use lowercase letters, numbers, and hyphens',
+  });
+
+  const framework = await select({
+    message: 'Framework:',
+    choices: [
+      { name: 'Next.js', value: 'nextjs', description: 'Full-stack React' },
+      { name: 'Express', value: 'express', description: 'Minimal API server' },
+      { name: 'Fastify', value: 'fastify', description: 'High-performance API' },
+    ],
+  });
+
+  const features = await checkbox({
+    message: 'Features:',
+    choices: [
+      { name: 'TypeScript', value: 'typescript', checked: true },
+      { name: 'ESLint', value: 'eslint', checked: true },
+      { name: 'Docker', value: 'docker' },
+      { name: 'CI/CD', value: 'ci' },
+    ],
+  });
+
+  const proceed = await confirm({ message: 'Create project?', default: true });
+  if (!proceed) process.exit(0);
+
+  return { name, framework, features };
+}
+```
+
+### 3. Chalk — Styled Output
+
+```typescript
+import chalk from 'chalk';
+
+// Status messages
+function logSuccess(msg: string) { console.log(chalk.green('OK') + ' ' + msg); }
+function logError(msg: string)   { console.error(chalk.red('ERR') + ' ' + msg); }
+function logWarn(msg: string)    { console.log(chalk.yellow('WARN') + ' ' + msg); }
+function logInfo(msg: string)    { console.log(chalk.blue('INFO') + ' ' + msg); }
+
+// Formatted output
+console.log(chalk.bold.underline('Deployment Summary'));
+console.log(`  Environment: ${chalk.cyan('production')}`);
+console.log(`  Version:     ${chalk.green('v1.2.3')}`);
+console.log(`  Status:      ${chalk.bgGreen.black(' DEPLOYED ')}`);
+
+// Tables (without dependencies)
+function printTable(headers: string[], rows: string[][]) {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map(r => r[i]?.length ?? 0))
+  );
+  const line = widths.map(w => '-'.repeat(w + 2)).join('+');
+
+  console.log(headers.map((h, i) => ` ${h.padEnd(widths[i])} `).join('|'));
+  console.log(line);
+  rows.forEach(row => {
+    console.log(row.map((c, i) => ` ${(c ?? '').padEnd(widths[i])} `).join('|'));
+  });
+}
+```
+
+### 4. Progress Indicators
+
+```typescript
+import ora from 'ora';
+import cliProgress from 'cli-progress';
+
+// Spinner for indeterminate operations
+async function withSpinner<T>(message: string, fn: () => Promise<T>): Promise<T> {
+  const spinner = ora(message).start();
+  try {
+    const result = await fn();
+    spinner.succeed();
+    return result;
+  } catch (err) {
+    spinner.fail();
+    throw err;
+  }
+}
+
+await withSpinner('Deploying...', () => deploy());
+
+// Progress bar for determinate operations
+const bar = new cliProgress.SingleBar({
+  format: 'Uploading |{bar}| {percentage}% | {value}/{total} files',
+  barCompleteChar: '\u2588',
+  barIncompleteChar: '\u2591',
+});
+
+bar.start(files.length, 0);
+for (const file of files) {
+  await upload(file);
+  bar.increment();
+}
+bar.stop();
+```
+
+### 5. Configuration Management
+
+```typescript
+import Conf from 'conf';
+
+interface Config {
+  apiKey: string;
+  defaultEnvironment: 'staging' | 'production';
+  outputFormat: 'json' | 'table' | 'text';
+}
+
+const config = new Conf<Config>({
+  projectName: 'mycli',
+  schema: {
+    apiKey: { type: 'string', default: '' },
+    defaultEnvironment: { type: 'string', enum: ['staging', 'production'], default: 'staging' },
+    outputFormat: { type: 'string', enum: ['json', 'table', 'text'], default: 'table' },
+  },
+});
+
+// Config subcommand
+program
+  .command('config')
+  .description('Manage configuration')
+  .command('set')
+  .argument('<key>', 'Configuration key')
+  .argument('<value>', 'Configuration value')
+  .action((key, value) => {
+    config.set(key, value);
+    logSuccess(`Set ${key} = ${value}`);
+  });
+
+program
+  .command('config')
+  .command('get')
+  .argument('<key>', 'Configuration key')
+  .action((key) => {
+    const value = config.get(key);
+    console.log(value ?? chalk.dim('(not set)'));
+  });
+
+program
+  .command('config')
+  .command('path')
+  .action(() => console.log(config.path));
+```
+
+### 6. Error Handling and Exit Codes
+
+```typescript
+// Wrap the top-level action to handle errors consistently
+function handleErrors(fn: (...args: any[]) => Promise<void>) {
+  return async (...args: any[]) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      if (err instanceof UserError) {
+        logError(err.message);
+        if (err.hint) logInfo(`Hint: ${err.hint}`);
+        process.exit(1);
+      }
+      if (err instanceof NetworkError) {
+        logError(`Network error: ${err.message}`);
+        logInfo('Check your connection and try again');
+        process.exit(2);
+      }
+      // Unexpected error — show stack trace
+      console.error(err);
+      process.exit(99);
+    }
+  };
+}
+
+program
+  .command('deploy')
+  .action(handleErrors(async (env, opts) => {
+    await deploy(env, opts);
+  }));
+```
+
+### 7. Packaging and Distribution
+
+```json
+{
+  "name": "mycli",
+  "version": "1.0.0",
+  "bin": { "mycli": "./dist/index.js" },
+  "type": "module",
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --target node18 --clean",
+    "prepublishOnly": "npm run build"
+  }
+}
+```
+
+For standalone binaries (no Node.js required):
+
+```bash
+# Using pkg or @vercel/ncc
+npx pkg dist/index.js --targets node18-macos-arm64,node18-linux-x64,node18-win-x64
+```
+
+## Examples
+
+| Tool | Purpose | Key Feature |
+|------|---------|-------------|
+| Commander | Argument parsing | Subcommands, options, validation |
+| Inquirer | Interactive prompts | Select, checkbox, confirm |
+| chalk | Styled terminal output | Colors, bold, underline |
+| ora | Spinners | Indeterminate progress |
+| Conf | Config persistence | JSON schema validation |
+| tsup | Bundle for distribution | Single CJS file |
+
+## Checklist
+
+- [ ] Subcommands organized by domain (`deploy`, `config`, `status`)
+- [ ] All commands support `--json` flag for scripting/piping
+- [ ] Interactive prompts have non-interactive fallbacks via flags
+- [ ] Help text is clear, with examples for complex commands
+- [ ] Exit codes are consistent (0 = success, 1 = user error, 2 = network)
+- [ ] Configuration stored with schema validation
+- [ ] Errors show actionable hints, not raw stack traces
+- [ ] Spinners/progress bars used for operations longer than 1 second
+- [ ] `bin` field in package.json points to built output
+- [ ] Shell completions generated with `program.completions()`

package/assets/skills/code-review.md

@@ -0,0 +1,185 @@
+---
+name: code-review
+description: Code review patterns with review checklist, PR sizing, automated checks, constructive feedback, and security review.
+---
+
+# Code Review
+
+## When to Use
+Apply to every pull request before merge. Use the structured checklist to catch bugs, security holes, and maintainability issues that automated tools miss. Also useful for self-review before opening a PR, and for training junior developers on what to look for.
+
+## How It Works
+
+### Start with the Big Picture
+
+Before reading line-by-line, understand what the PR is doing:
+
+```
+1. Read the PR title and description -- what problem does this solve?
+2. Check the file list -- does the scope match the described change?
+3. Look for unexpected files (config changes, new dependencies, migrations)
+4. Verify the change has tests proportional to its risk
+5. Check if the PR can be split into smaller, focused changes
+```
+
+If a PR touches 20+ files across unrelated domains, ask to split it. Large PRs get rubber-stamped; small PRs get real review.
+
+### Security Review Checklist
+
+Check every PR for these patterns, especially in routes and data handling:
+
+```typescript
+// SQL injection -- use parameterized queries
+// BAD:  db.query(`SELECT * FROM users WHERE id = '${userId}'`)
+// GOOD:
+const user = await db.query("SELECT * FROM users WHERE id = $1", [userId]);
+
+// XSS -- sanitize user content before rendering
+// BAD:  <div dangerouslySetInnerHTML={{ __html: userComment }} />
+// GOOD:
+import DOMPurify from "dompurify";
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userComment) }} />
+
+// Auth bypass -- verify ownership, not just authentication
+// BAD:  const order = await db.orders.findById(req.params.id);
+// GOOD:
+const order = await db.orders.findOne({
+  id: req.params.id,
+  userId: req.user.id,
+});
+
+// Mass assignment -- whitelist allowed fields
+// BAD:  await db.users.update(req.params.id, req.body);
+// GOOD:
+const { name, email } = req.body;
+await db.users.update(req.params.id, { name, email });
+```
+
+### Performance Review
+
+Look for patterns that will cause problems at scale:
+
+```typescript
+// N+1 queries -- fetch related data in one query
+// BAD:
+for (const order of orders) {
+  order.user = await db.users.findById(order.userId);
+}
+// GOOD:
+const userIds = [...new Set(orders.map((o) => o.userId))];
+const users = await db.users.findByIds(userIds);
+const userMap = new Map(users.map((u) => [u.id, u]));
+orders.forEach((o) => (o.user = userMap.get(o.userId)));
+
+// Unbounded queries -- always paginate
+// BAD:  const allUsers = await db.users.findAll();
+// GOOD: const users = await db.users.findAll({ limit: 50, cursor });
+
+// Memory leaks -- event listeners without cleanup
+// BAD:  useEffect(() => { window.addEventListener("resize", handler); }, []);
+// GOOD:
+useEffect(() => {
+  window.addEventListener("resize", handler);
+  return () => window.removeEventListener("resize", handler);
+}, []);
+```
+
+### Readability Review
+
+```
+- Functions: does the name describe what it does, not how?
+  BAD:  loopAndFilter()    GOOD: getActiveUsers()
+
+- Variables: would a new team member understand this?
+  BAD:  const d = new Date()    GOOD: const createdAt = new Date()
+
+- Comments: explain WHY, not WHAT
+  BAD:  // increment counter
+  GOOD: // Retry up to 3 times -- the payment gateway has transient failures
+
+- Magic numbers: named constants, not inline literals
+  BAD:  if (retries > 3)    GOOD: if (retries > MAX_RETRIES)
+```
+
+### Automated Checks as First Pass
+
+Set up CI to catch mechanical issues before human review:
+
+```yaml
+# .github/workflows/pr-checks.yml
+name: PR Checks
+on: [pull_request]
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm test -- --coverage
+      - run: npx audit-ci --moderate
+      - uses: danger/danger-js@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+```typescript
+// dangerfile.ts -- automated PR feedback
+import { danger, warn, fail } from "danger";
+
+if (danger.github.pr.body.length < 10) {
+  fail("PR description is too short. Explain what and why.");
+}
+if (danger.github.pr.additions > 500) {
+  warn("Large PR. Consider splitting into smaller changes.");
+}
+const hasTests = danger.git.created_files.some((f) => f.includes(".test."));
+if (!hasTests && danger.github.pr.additions > 50) {
+  warn("No test files added. Is this change covered by existing tests?");
+}
+```
+
+### Constructive Feedback Patterns
+
+```markdown
+## Ask, don't demand
+BAD:  "This is wrong. Use a Map instead."
+GOOD: "Have you considered using a Map here? It would give O(1)
+       lookup instead of the O(n) filter on line 42."
+
+## Distinguish blocking from non-blocking
+- "nit: rename `d` to `createdAt`"            -> nice to have
+- "issue: this query is missing LIMIT"         -> must fix
+- "question: what happens if `user` is null?"  -> need clarification
+
+## Offer alternatives with code
+"This works, but a reduce() might be clearer:
+```ts
+const byId = items.reduce<Record<string, Item>>(
+  (acc, item) => ({ ...acc, [item.id]: item }),
+  {}
+);
+```"
+```
+
+## Examples
+
+| What You Catch | How to Spot It | Impact |
+|---------------|---------------|--------|
+| SQL injection | String interpolation in queries | Data breach |
+| N+1 query | Loop with await inside | 200ms -> 5s page load |
+| Missing error handling | No try/catch on external calls | Unhandled crash |
+| Auth bypass | findById without userId check | Users access others' data |
+| Memory leak | Event listener without cleanup | App degrades over time |
+| Large PR | 20+ files across domains | Missed bugs, rubber-stamped |
+
+## Checklist
+- [ ] PR description explains WHAT and WHY (not just HOW)
+- [ ] Scope is focused -- one concern per PR, under 400 lines changed
+- [ ] No hardcoded secrets, API keys, or credentials
+- [ ] SQL queries use parameterized inputs
+- [ ] User input is validated and sanitized
+- [ ] Database queries have LIMIT and appropriate indexes
+- [ ] Error cases handled, not swallowed silently
+- [ ] No N+1 query patterns