huntr-cli 1.0.9

package/docs/DEV-SETUP.md

@@ -0,0 +1,512 @@
+# Development Setup Guide
+
+Complete guide for setting up huntr-cli for local development with all tools configured.
+
+## Installation
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.com/mattmck/huntr-cli.git
+cd huntr-cli
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install
+# Automatically:
+# - Installs all npm packages
+# - Runs "prepare" script to setup git hooks with husky
+# - Configures pre-commit and pre-push hooks
+```
+
+### 3. Verify Setup
+
+```bash
+npm run build      # Should compile with no errors
+npm run lint       # Should pass (warnings ok)
+npm run typecheck  # Should pass
+```
+
+---
+
+## Available Commands
+
+### Development
+
+```bash
+npm run dev -- me                    # Run CLI in dev mode
+npm run dev -- boards list           # List boards
+npm run dev -- activities list <id>  # List activities
+```
+
+### Building & Testing
+
+```bash
+npm run build      # Compile TypeScript to dist/
+npm run typecheck  # Check TypeScript types (no emit)
+npm run lint       # Check code style (errors only)
+npm run lint:fix   # Auto-fix style issues
+npm test           # Run tests (currently none)
+```
+
+### Git Hooks
+
+```bash
+# These run automatically
+npm run prepare    # Install git hooks manually
+```
+
+---
+
+## Git Workflow
+
+### Create Feature Branch
+
+```bash
+git checkout -b feat/new-feature
+# or
+git checkout -b fix/bug-fix
+git checkout -b docs/update-readme
+```
+
+### Make Changes
+
+```bash
+# Edit files
+nano src/cli.ts
+
+# Check style (pre-commit will do this too)
+npm run lint:fix
+
+# Test locally
+npm run dev -- boards list
+
+# Build and typecheck
+npm run build
+npm run typecheck
+```
+
+### Commit Changes
+
+```bash
+# Stage files
+git add src/
+
+# Commit with conventional message
+git commit -m "feat: add new feature"
+
+# ⚠️ Pre-commit hook runs here:
+# - Lints staged files
+# - Blocks commit if errors found
+# - Auto-fixes some issues
+
+# If hook fails, fix errors and retry
+git add .
+git commit -m "feat: add new feature"
+```
+
+### Push to Remote
+
+```bash
+git push origin feat/new-feature
+
+# ⚠️ Pre-push hook runs here:
+# - Typecheck
+# - Lint all files
+# - Build
+# - Blocks push if any fail
+```
+
+### Create Pull Request
+
+1. Go to GitHub repository
+2. Click "Create Pull Request"
+3. Fill in title and description
+4. Create PR
+
+### Wait for CI
+
+- GitHub Actions runs automatically
+- Check `Actions` tab for status
+- All jobs must pass (green checkmarks)
+- Cannot merge if CI fails
+
+### Merge to Main
+
+```bash
+# Via GitHub UI (Squash merge recommended)
+# OR locally:
+git checkout main
+git pull origin main
+git merge feat/new-feature
+git push origin main
+```
+
+---
+
+## Pre-commit Hook Details
+
+**What it does:** Lints only the files you're committing
+
+**When:** Before `git commit` succeeds
+
+**Behavior:**
+- ✅ Runs ESLint on staged `.ts` files
+- ✅ Auto-fixes fixable issues
+- ✅ Stages fixed files
+- ❌ Blocks commit if non-fixable errors found
+
+**Example:**
+
+```bash
+$ git commit -m "feat: add feature"
+
+🔍 Running pre-commit checks...
+  ✓ src/cli.ts (fixed 2 issues)
+✓ Pre-commit checks passed
+
+[feat/new-feature abc1234] feat: add feature
+```
+
+**If it fails:**
+
+```bash
+$ git commit -m "feat: add feature"
+
+🔍 Running pre-commit checks...
+  ✗ src/lib/list-options.ts
+    error: Missing trailing comma (comma-dangle)
+    error: Unexpected any type (no-explicit-any)
+❌ Linting failed. Please fix errors and try again.
+
+# Fix errors
+vim src/lib/list-options.ts
+
+# Re-stage and retry
+git add .
+git commit -m "feat: add feature"
+```
+
+**Manual linting:**
+
+```bash
+npm run lint       # Check all files
+npm run lint:fix   # Auto-fix issues
+```
+
+---
+
+## Pre-push Hook Details
+
+**What it does:** Comprehensive checks before pushing
+
+**When:** Before `git push` succeeds
+
+**Checks (in order):**
+1. TypeScript compilation (`npm run typecheck`)
+2. ESLint all files (`npm run lint`)
+3. Build to dist/ (`npm run build`)
+
+**Example:**
+
+```bash
+$ git push origin feat/new-feature
+
+🧪 Running pre-push checks...
+📋 Typechecking...
+  ✓ No TypeScript errors
+🔍 Linting all source files...
+  ✓ Lint passed
+🔨 Building...
+  ✓ Build successful
+✓ All pre-push checks passed
+
+Counting objects: 3, done.
+Writing objects: 100% (3/3), 287 bytes | 287.00 KiB/s, done.
+Total 3 (delta 0), reused 0 (delta 0)
+To github.com:mattmck/huntr-cli.git
+   abc1234..def5678  feat/new-feature -> feat/new-feature
+```
+
+**If it fails:**
+
+```bash
+$ git push origin feat/new-feature
+
+🧪 Running pre-push checks...
+📋 Typechecking...
+  ❌ TypeScript errors found
+
+# Fix issues locally
+npm run typecheck  # See what's wrong
+# Edit files to fix
+npm run build
+npm run lint
+
+# Retry push
+git push origin feat/new-feature
+```
+
+---
+
+## ESLint Configuration
+
+**File:** `eslint.config.js` (modern flat config)
+
+**What's checked:**
+- TypeScript type safety
+- Code style (quotes, semicolons, trailing commas)
+- Unused variables
+- Unneeded assignments
+- No console.log in production (warning)
+
+**Fix style issues:**
+
+```bash
+npm run lint:fix
+```
+
+**Common issues:**
+- Missing trailing commas in objects/arrays
+- Wrong quote style (should be single quotes)
+- Missing semicolons
+
+All can be auto-fixed with `npm run lint:fix`.
+
+---
+
+## Debugging
+
+### Run CLI with Debug Output
+
+```bash
+DEBUG=* npm run dev -- boards list
+```
+
+### Check Node Version
+
+```bash
+node --version
+# Should be 18+
+```
+
+### Clear Cache & Reinstall
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Bypass Hooks (Emergency Only)
+
+```bash
+# Skip pre-commit
+git commit --no-verify
+
+# Skip pre-push
+git push --no-verify
+```
+
+**⚠️ Not recommended:** These should only be used in emergencies. Better to fix the issue!
+
+---
+
+## Project Structure
+
+```
+huntr-cli/
+├── src/
+│   ├── cli.ts              # Main CLI entry point
+│   ├── types/              # Type definitions
+│   ├── api/                # API clients
+│   ├── config/             # Configuration management
+│   ├── commands/           # CLI commands
+│   └── lib/                # Shared utilities
+├── dist/                   # Compiled output (git ignored)
+├── .github/
+│   └── workflows/          # GitHub Actions
+├── .husky/                 # Git hooks
+├── completions/            # Shell completions
+├── docs/                   # Documentation
+├── eslint.config.js        # ESLint configuration
+├── tsconfig.json           # TypeScript configuration
+├── package.json            # Dependencies & scripts
+└── README.md               # Project README
+```
+
+---
+
+## Conventional Commits
+
+Follow this format for commit messages:
+
+```
+type: subject
+
+body (optional)
+```
+
+**Types:**
+- `feat:` — New feature
+- `fix:` — Bug fix
+- `docs:` — Documentation only
+- `chore:` — Build tools, dependencies
+- `refactor:` — Code restructuring
+- `test:` — Test-related changes
+- `perf:` — Performance improvements
+
+**Examples:**
+
+```bash
+git commit -m "feat: add field selection to list commands"
+git commit -m "fix: handle missing company in activities"
+git commit -m "docs: add CI/CD setup guide"
+git commit -m "chore: update dependencies"
+```
+
+---
+
+## Tips & Tricks
+
+### Quick Lint & Build
+
+```bash
+npm run lint:fix && npm run build && npm run typecheck
+```
+
+### Test Changes Before Commit
+
+```bash
+npm run dev -- <your-command>
+npm run build
+npm run typecheck
+npm run lint
+```
+
+### View What Will Be Committed
+
+```bash
+git diff --cached
+git status
+```
+
+### Undo Last Commit (Keep Changes)
+
+```bash
+git reset --soft HEAD~1
+```
+
+### Check Git Hooks Status
+
+```bash
+ls -la .husky/
+# Should show pre-commit and pre-push
+```
+
+### Reinstall Hooks
+
+```bash
+npm run prepare
+```
+
+---
+
+## Troubleshooting
+
+### "Hooks not running"
+
+**Solution:**
+```bash
+npm run prepare
+chmod +x .husky/pre-commit .husky/pre-push
+```
+
+### "Module not found" errors
+
+**Solution:**
+```bash
+npm install
+npm run build
+```
+
+### "TypeScript errors"
+
+**Solution:**
+```bash
+npm run typecheck
+# Read errors and fix
+```
+
+### "ESLint errors"
+
+**Solution:**
+```bash
+npm run lint        # See issues
+npm run lint:fix    # Auto-fix
+git add .
+git commit -m "..."
+```
+
+### "Build fails"
+
+**Solution:**
+```bash
+npm run build 2>&1 | head -20
+# Read error, fix issue
+npm run build
+```
+
+---
+
+## Next Steps
+
+1. **Clone & install:** `git clone ... && npm install`
+2. **Verify setup:** `npm run build && npm run lint && npm run typecheck`
+3. **Try a change:** Edit `src/cli.ts`, run `npm run dev`, commit, push
+4. **Check hooks:** Notice pre-commit and pre-push running
+5. **Read docs:** See `docs/` for detailed information
+
+---
+
+## Documentation Index
+
+- **CI/CD Setup:** `docs/CI-CD-SETUP.md`
+- **GitHub Actions:** `docs/GITHUB-ACTIONS-GUIDE.md`
+- **Output Formats:** `docs/OUTPUT-FORMATS.md`
+- **Output Examples:** `docs/OUTPUT-EXAMPLES.md`
+- **npm Publishing:** `docs/NPM-PUBLISHING.md`
+- **Enhancement Plan:** `docs/ENHANCEMENT-PLAN.md`
+
+---
+
+## Quick Commands Reference
+
+```bash
+# Development
+npm run dev -- <command>        # Run CLI in dev mode
+npm run dev -- --help           # See all commands
+
+# Quality
+npm run lint                     # Check code style
+npm run lint:fix                 # Fix style issues
+npm run typecheck                # Check TypeScript
+npm run build                    # Build project
+npm test                         # Run tests
+
+# Git (automatic with hooks)
+git add .                        # Stage changes
+git commit -m "type: message"    # Triggers pre-commit hook
+git push origin branch           # Triggers pre-push hook
+```
+
+---
+
+## Support
+
+- **Lint issues?** Run `npm run lint:fix`
+- **Type errors?** Run `npm run typecheck` to see details
+- **Build failing?** Run `npm run build` for error details
+- **Git hooks?** See `docs/CI-CD-SETUP.md`
+- **Publishing?** See `docs/NPM-PUBLISHING.md`

package/docs/ENHANCEMENT-PLAN.md

@@ -0,0 +1,204 @@
+# Output Format Enhancements — Implementation Plan
+
+## Overview
+
+This document outlines the implementation plan for:
+1. `--fields` parameter for field selection
+2. PDF output format
+3. Excel output format
+4. Enhanced output validation
+
+## Changes to list-options.ts
+
+### Type Updates
+
+```typescript
+export interface ListOptions {
+  format: OutputFormat;
+  days?: number;
+  types?: string[];
+  fields?: string[];  // NEW: selected fields
+}
+
+export type OutputFormat = 'table' | 'json' | 'csv' | 'pdf' | 'excel';  // UPDATED
+```
+
+### New Functions
+
+1. **`validateFields(availableFields: string[], requestedFields?: string[]): string[]`**
+   - Validates that requested fields exist in available set
+   - Returns requested fields if valid, or all available fields if none specified
+   - Throws error with helpful message if invalid
+
+2. **`formatPdf<T>(rows: T[], headers: string[], title?: string): Buffer`**
+   - Generates PDF with professional formatting
+   - Includes headers, borders, auto-sized columns
+   - Uses `pdfkit` library
+
+3. **`formatExcel<T>(rows: T[], headers: string[], title?: string): Buffer`**
+   - Generates Excel workbook
+   - Includes headers with formatting
+   - Auto-adjusted column widths
+   - Uses `exceljs` library
+
+### Parser Update
+
+Update `parseListOptions()` to:
+- Accept and validate `fields` parameter
+- Provide it in returned `ListOptions` object
+
+---
+
+## CLI Updates
+
+### Package Dependencies
+
+Add to `package.json`:
+```json
+{
+  "pdfkit": "^0.13.0",
+  "exceljs": "^4.4.0"
+}
+```
+
+### Command Updates
+
+Each list command (`boards list`, `jobs list`, `activities list`):
+
+1. Add option:
+   ```typescript
+   .option('--fields <fields>', 'Comma-separated list of fields to include')
+   ```
+
+2. Define `AVAILABLE_FIELDS` for each entity:
+   ```typescript
+   const AVAILABLE_FIELDS = ['ID', 'Name', 'Created'];
+   ```
+
+3. Call helper to validate:
+   ```typescript
+   const validFields = validateFields(AVAILABLE_FIELDS, listOpts.fields);
+   ```
+
+4. Handle PDF/Excel formats:
+   ```typescript
+   if (listOpts.format === 'pdf') {
+     const buffer = formatPdf(rows, validFields, 'Boards List');
+     process.stdout.write(buffer);
+   } else if (listOpts.format === 'excel') {
+     const buffer = formatExcel(rows, validFields, 'Boards List');
+     process.stdout.write(buffer);
+   }
+   ```
+
+---
+
+## Field Definitions by Command
+
+### `boards list`
+- Available: ID, Name, Created
+- Default (no `--fields`): ID, Name, Created
+
+### `jobs list`
+- Available: ID, Title, URL, Created, Company (if available), Location (if available)
+- Default: ID, Title, URL, Created
+
+### `activities list`
+- Available: Date, Type, Company, Job, Status, JobID, CompanyID (raw IDs)
+- Default: Date, Type, Company, Job, Status
+
+### `me`
+- Not applicable (no format parameter)
+
+### `boards get`, `jobs get`
+- Not applicable (no format parameter, singular entity)
+
+---
+
+## Error Handling
+
+Invalid field example:
+```bash
+$ huntr boards list --fields ID,InvalidField
+Error: Unknown field 'InvalidField'
+Available fields: ID, Name, Created
+```
+
+Invalid format example:
+```bash
+$ huntr boards list --format doc
+Error: Invalid format: doc. Must be table, json, csv, pdf, or excel.
+```
+
+---
+
+## Testing Strategy
+
+1. **Field Validation**
+   - Valid field selection
+   - Invalid field selection (error)
+   - No `--fields` parameter (all fields)
+
+2. **Format Output**
+   - PDF generation and binary integrity
+   - Excel generation and spreadsheet validity
+   - CSV escaping still works
+   - Table formatting preserved
+
+3. **Round-trip Testing**
+   - CSV → Excel conversion
+   - CSV → PDF conversion
+   - Field selection works across all formats
+
+---
+
+## Rollout Plan
+
+### Phase 1: Foundation
+- [ ] Update `list-options.ts` with types and validation
+- [ ] Add `validateFields()` utility
+- [ ] Install dependencies: pdfkit, exceljs
+
+### Phase 2: Field Selection
+- [ ] Update all commands to support `--fields` parameter
+- [ ] Test field validation across all commands
+
+### Phase 3: PDF Format
+- [ ] Implement `formatPdf()` in list-options.ts
+- [ ] Test PDF output for each command
+- [ ] Update completions for `--format pdf`
+
+### Phase 4: Excel Format
+- [ ] Implement `formatExcel()` in list-options.ts
+- [ ] Test Excel output for each command
+- [ ] Update completions for `--format excel`
+
+### Phase 5: Documentation
+- [ ] Update OUTPUT-FORMATS.md with examples
+- [ ] Update README.md with new options
+- [ ] Update bash/zsh completions
+- [ ] Add examples to help text
+
+---
+
+## Library Selection Rationale
+
+### pdfkit vs alternatives
+- **pdfkit**: Pure Node.js, no native dependencies, good for CLI
+- **puppeteer**: Overkill, requires headless browser
+- **pdf-lib**: Good but pdfkit more feature-complete for tables
+
+### exceljs vs alternatives
+- **exceljs**: Pure JavaScript, supports streaming, professional features
+- **xlsx**: Simpler but less control over formatting
+- **node-xlsx**: Minimal, but exceljs more actively maintained
+
+---
+
+## Backward Compatibility
+
+All changes are backward compatible:
+- Existing commands work without `--fields` parameter
+- Existing formats (table, json, csv) unchanged
+- Default behavior unchanged
+- No breaking changes to API