huntr-cli 1.0.9

package/docs/GITHUB-ACTIONS-GUIDE.md

@@ -0,0 +1,367 @@
+# GitHub Actions Workflows Guide
+
+Quick reference for all GitHub Actions workflows in this project.
+
+## Summary
+
+| Workflow | Trigger | Purpose | Status |
+|----------|---------|---------|--------|
+| **CI** | Push, PR | Lint, typecheck, build, test | Always runs |
+| **Publish** | Release created | Auto-publish to npm | Production |
+| **Manual Publish** | Manual dispatch | On-demand publish with version | Optional |
+| **Security Audit** | Daily, push, manual | Check dependencies | Monitoring |
+
+---
+
+## Workflow Details
+
+### CI Workflow (`.github/workflows/ci.yml`)
+
+**Runs on:** Every push to `main`/`develop`, every PR
+
+**Jobs:**
+- `lint` — ESLint all TypeScript files
+- `typecheck` — TypeScript compilation check
+- `build` — Build to dist/
+- `test` — Run tests
+
+**Status:** ✅ Passing all checks
+
+**View logs:** `Actions` → workflow run → job → step
+
+**What to do if it fails:**
+1. Click the failed job in Actions tab
+2. Read error message
+3. Fix locally: `npm run lint:fix`, `npm run typecheck`, `npm run build`
+4. Commit and push fix
+
+---
+
+### Publish Workflow (`.github/workflows/publish.yml`)
+
+**Runs on:** GitHub Release published
+
+**How to trigger:**
+```bash
+# 1. Tag and push
+git tag v1.1.0
+git push origin v1.1.0
+
+# 2. Create release (GitHub CLI)
+gh release create v1.1.0 --generate-notes
+
+# OR create in GitHub UI:
+# Releases → Create new release → select tag → Publish
+```
+
+**What it does:**
+1. Checks out code
+2. Installs dependencies
+3. Runs lint, typecheck, build
+4. **Publishes to npm** with NPM_TOKEN
+5. Comments on release with result
+
+**Requirements:**
+- `NPM_TOKEN` secret configured
+
+**View logs:** `Actions` → `Publish to npm` → run
+
+---
+
+### Manual Publish Workflow (`.github/workflows/manual-publish.yml`)
+
+**Runs on:** Manual trigger via GitHub UI
+
+**How to trigger:**
+1. Go to GitHub repo
+2. `Actions` tab
+3. `Manual Publish` workflow (left sidebar)
+4. Click `Run workflow`
+5. Enter version (e.g., `1.1.0-beta.1`)
+6. Select npm tag (`latest`, `beta`, `rc`)
+7. Click `Run workflow`
+
+**What it does:**
+1. Validates version format
+2. Updates package.json
+3. Runs full CI pipeline
+4. Publishes to npm
+5. Creates git tag and GitHub Release
+6. (Optional) Posts to Slack
+
+**Use cases:**
+- Publishing pre-releases (beta, RC)
+- Emergency patches
+- Skipping GitHub Release step
+
+**Requirements:**
+- `NPM_TOKEN` secret
+- `SLACK_WEBHOOK_URL` (optional)
+
+---
+
+### Security Audit Workflow (`.github/workflows/security-audit.yml`)
+
+**Runs on:**
+- Daily at midnight UTC
+- Every push to main/develop
+- Manual via Actions tab
+
+**What it does:**
+- Installs dependencies
+- Runs `npm audit` (moderate+ severity)
+- Uploads report as artifact
+
+**View report:**
+1. `Actions` → `Security Audit` → latest run
+2. Download artifacts
+3. Review audit-report.json
+
+**What to do if vulnerabilities found:**
+```bash
+npm audit
+npm audit fix
+git add package-lock.json
+git commit -m "chore: fix security vulnerabilities"
+git push
+```
+
+---
+
+## Setup Checklist
+
+### First Time Setup
+
+- [ ] Clone repo: `git clone https://github.com/mattmck/huntr-cli.git`
+- [ ] Install dependencies: `npm install` (hooks auto-setup)
+- [ ] Configure `NPM_TOKEN` secret in GitHub
+- [ ] (Optional) Configure `SLACK_WEBHOOK_URL` secret
+
+### NPM Token Setup
+
+1. Go to [npmjs.com](https://npmjs.com)
+2. Profile → Access Tokens
+3. Generate new token (Automation level)
+4. Copy token (starts with `npm_`)
+5. GitHub repo → Settings → Secrets and variables → Actions
+6. New secret: name `NPM_TOKEN`, value = paste token
+
+### Slack Setup (Optional)
+
+1. Go to your Slack workspace settings
+2. Create incoming webhook
+3. Copy webhook URL
+4. GitHub repo → Settings → Secrets → Actions
+5. New secret: name `SLACK_WEBHOOK_URL`, value = webhook URL
+
+---
+
+## Publishing Workflow
+
+### 1. Make Changes & Commit
+
+```bash
+# Create feature branch
+git checkout -b feat/new-feature
+
+# Make changes
+npm run lint:fix  # Format code
+npm run build     # Verify build works
+
+# Commit
+git add src/
+git commit -m "feat: add new feature"
+```
+
+### 2. Create Pull Request
+
+```bash
+git push origin feat/new-feature
+# Go to GitHub, create PR
+# Wait for CI to pass (all green checks)
+```
+
+### 3. Merge to Main
+
+```bash
+# Via GitHub UI or:
+git checkout main
+git pull origin main
+git merge feat/new-feature
+git push origin main
+```
+
+### 4. Publish to npm
+
+**Option A: Automatic (Recommended)**
+```bash
+# Create tag from main
+git tag v1.1.0
+git push origin v1.1.0
+
+# Create release in GitHub (auto-publishes)
+gh release create v1.1.0 --generate-notes
+```
+
+**Option B: Manual**
+1. Go to GitHub Actions
+2. `Manual Publish` workflow
+3. Enter version `1.1.0`
+4. Select npm tag `latest`
+5. Run
+
+---
+
+## Troubleshooting
+
+### CI Fails on PR
+
+**Check:** Which job failed?
+- `lint` → Run `npm run lint:fix`
+- `typecheck` → Fix TypeScript errors
+- `build` → Run `npm run build` locally
+- `test` → Check test output
+
+**Fix locally, then:**
+```bash
+git add .
+git commit -m "fix: resolve CI errors"
+git push origin feature-branch
+```
+
+### Publish Fails
+
+**Check logs:**
+1. `Actions` → `Publish to npm` (or `Manual Publish`)
+2. Click failed run
+3. Click failed job
+4. Read error message
+
+**Common issues:**
+- NPM_TOKEN missing/invalid → Check Settings → Secrets
+- Version already published → Use new version
+- TypeScript errors → Fix with `npm run typecheck`
+- Lint errors → Fix with `npm run lint:fix`
+
+### How to Re-run Failed Workflow
+
+1. Go to `Actions` tab
+2. Click workflow
+3. Click the failed run
+4. Click `Re-run failed jobs` (or `Re-run all jobs`)
+
+---
+
+## Workflow Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `.github/workflows/ci.yml` | CI pipeline |
+| `.github/workflows/publish.yml` | Auto-publish on release |
+| `.github/workflows/manual-publish.yml` | On-demand publish |
+| `.github/workflows/security-audit.yml` | Daily security checks |
+
+---
+
+## Local Development Commands
+
+```bash
+# Lint
+npm run lint              # Check style
+npm run lint:fix          # Auto-fix style
+
+# Typecheck
+npm run typecheck         # Check TS compilation
+
+# Build
+npm run build             # Build to dist/
+
+# Combined (what pre-push hook does)
+npm run lint && npm run typecheck && npm run build
+```
+
+---
+
+## Branch Protection Rules (Recommended)
+
+Set up in GitHub Settings → Branches → Branch protection rules for `main`:
+
+- ✅ Require status checks to pass before merging
+- ✅ Require branches to be up to date before merging
+- ✅ Require code reviews before merging
+- ✅ Dismiss stale pull request approvals
+- ✅ Require linear history
+
+---
+
+## Monitoring Dashboard
+
+**View all workflows:** GitHub repo → `Actions` tab
+
+**Recent runs:**
+```bash
+# Using GitHub CLI
+gh run list --workflow=ci.yml -L 5
+gh run list --workflow=publish.yml -L 5
+gh run list --workflow=security-audit.yml -L 5
+```
+
+**Trigger manual workflows:**
+```bash
+gh workflow run security-audit.yml
+gh workflow run manual-publish.yml -f version=1.1.0-beta.1 -f npm_tag=beta
+```
+
+---
+
+## CI/CD Status Badge
+
+Add to README.md:
+
+```markdown
+[![CI](https://github.com/mattmck/huntr-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mattmck/huntr-cli/actions)
+```
+
+Result: [![CI](https://img.shields.io/github/actions/workflow/status/mattmck/huntr-cli/ci.yml?branch=main)](https://github.com/mattmck/huntr-cli/actions)
+
+---
+
+## Best Practices
+
+1. **Always wait for CI to pass** before merging PRs
+2. **Use conventional commits** in messages (feat:, fix:, etc.)
+3. **Keep commits atomic** (one logical change per commit)
+4. **Push to feature branch, create PR** (don't commit to main)
+5. **Create release from main branch** only
+6. **Review workflow logs** if something fails
+
+---
+
+## Summary Diagram
+
+```
+Development
+    ↓
+Feature Branch
+    ↓
+Create PR
+    ↓
+[CI: lint, typecheck, build, test]
+    ↓
+Merge to main
+    ↓
+Create Release/Tag
+    ↓
+[Publish: build + publish to npm]
+    ↓
+✅ Live on npmjs.com
+```
+
+---
+
+## Need Help?
+
+- **Workflow failed?** Check `Actions` tab logs
+- **Want to publish?** Use Manual Publish workflow
+- **CI errors?** Run locally with `npm run lint:fix && npm run typecheck && npm run build`
+- **Secrets issues?** Check Settings → Secrets → Actions

package/docs/NPM-PUBLISHING.md

@@ -0,0 +1,324 @@
+# NPM Publishing Guide
+
+When you publish huntr-cli to npm, here's where it lives and how users install it.
+
+## Where Your Package Lives
+
+### npm Registry (npmjs.com)
+
+When you run `npm publish`, your package is uploaded to the **npm registry** at:
+
+```
+https://www.npmjs.com/package/huntr-cli
+```
+
+This is the **official public npm registry** operated by GitHub (acquired by GitHub in 2020). Every time you publish a new version, it's stored here and immediately available to the world.
+
+### Local npm Cache
+
+When a user installs your package with `npm install -g huntr-cli`:
+1. npm checks their local cache first (`~/.npm`)
+2. If not cached, downloads from npmjs.com
+3. Stores a local copy in their cache
+
+### Global Installation Location
+
+When installed globally (`-g` flag), the executable is placed in the user's global node_modules:
+
+**macOS/Linux:**
+```bash
+~/.nvm/versions/node/v18.x.x/bin/huntr
+# OR
+/usr/local/bin/huntr
+# OR
+~/.npm/_npx/huntr-cli/bin/huntr
+```
+
+**Windows:**
+```
+C:\Users\username\AppData\Roaming\npm\huntr.cmd
+C:\Users\username\AppData\Roaming\npm\huntr
+```
+
+The `bin` field in your `package.json` tells npm where to create this symlink:
+
+```json
+{
+  "name": "huntr-cli",
+  "bin": {
+    "huntr": "./dist/cli.js"
+  }
+}
+```
+
+## How to Publish
+
+### 1. Create npm Account
+
+If you don't have one:
+```bash
+npm adduser
+# Enter username, password, email
+```
+
+Verify you're logged in:
+```bash
+npm whoami
+```
+
+### 2. Update Version in package.json
+
+Update the version following semver (major.minor.patch):
+
+```bash
+# Manual update
+"version": "1.0.0" → "1.0.1"
+
+# OR use npm version command
+npm version patch    # 1.0.0 → 1.0.1
+npm version minor    # 1.0.0 → 1.1.0
+npm version major    # 1.0.0 → 2.0.0
+```
+
+### 3. Build the Project
+
+The `prepublishOnly` script runs automatically before publishing:
+
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  }
+}
+```
+
+So just publish:
+```bash
+npm publish
+```
+
+It automatically builds to `dist/` before uploading.
+
+### 4. Verify Publishing
+
+Check that your package is live:
+
+```bash
+# View on npm
+npm view huntr-cli
+
+# Check latest version
+npm view huntr-cli version
+
+# View all versions
+npm view huntr-cli versions
+
+# Open in browser
+npm view huntr-cli repository.url
+```
+
+Or visit: https://www.npmjs.com/package/huntr-cli
+
+## After Publishing
+
+### Users Can Install Globally
+
+```bash
+npm install -g huntr-cli
+huntr --version
+huntr boards list
+```
+
+### Users Can Use with npx (No Installation)
+
+```bash
+npx huntr-cli me
+npx huntr-cli boards list
+npx huntr-cli jobs list <board-id>
+```
+
+This runs the latest version without installing it globally.
+
+### Distribute Shell Completions
+
+For users who want bash/zsh completions, they can download from your GitHub repo:
+
+```bash
+# User's setup:
+cd huntr-cli
+cp completions/huntr.bash ~/.bash_completion.d/huntr
+# or
+cp completions/_huntr ~/.zsh/completions/_huntr
+```
+
+Or you could add a `postinstall` script to automatically copy completions (optional):
+
+```json
+{
+  "scripts": {
+    "postinstall": "node scripts/install-completions.js"
+  }
+}
+```
+
+## About GitHub Artifacts
+
+You mentioned GitHub artifacts. These are **different from npm publishing**:
+
+### GitHub Artifacts
+- **Where:** GitHub Actions artifact storage (temporary)
+- **What:** Build outputs (dist/, coverage/, etc.)
+- **Lifetime:** Default 90 days, configurable
+- **Access:** Only in the workflow or via GitHub API
+- **Use case:** CI/CD testing, not distribution
+
+### npm Registry
+- **Where:** npmjs.com (permanent)
+- **What:** Your published package
+- **Lifetime:** Forever (unless you unpublish)
+- **Access:** `npm install`, searchable on npmjs.com
+- **Use case:** Public distribution
+
+**GitHub Artifacts are NOT for distributing CLI tools to users.** npm is the standard for Node.js packages.
+
+## Distribution Flow
+
+```
+GitHub Repo
+    ↓
+    └─→ [npm publish] → npmjs.com ← [npm install -g] ← Users
+    └─→ GitHub Actions → GitHub Artifacts (temporary, CI only)
+```
+
+## Optional: GitHub Releases
+
+You can also create **GitHub Releases** with prebuilt binaries:
+
+```bash
+# Create a release
+gh release create v1.0.0 --title "Version 1.0.0"
+
+# Upload artifacts to release
+gh release upload v1.0.0 ./dist/huntr-cli.tar.gz
+```
+
+Users could then download from: https://github.com/mattmck/huntr-cli/releases
+
+But for Node.js CLIs, npm is the standard distribution method.
+
+## Version Management
+
+### Semantic Versioning
+
+- **1.0.0** = major.minor.patch
+- **1.0.1** = patch release (bug fix)
+- **1.1.0** = minor release (new feature, backward compatible)
+- **2.0.0** = major release (breaking change)
+
+### Current Version
+
+Your current version is `1.0.0` in package.json.
+
+Next versions:
+- Adding --fields, PDF, Excel = **1.1.0** (new features, backward compatible)
+- Bug fixes = **1.0.1**
+- Breaking change (e.g., rename command) = **2.0.0**
+
+### Prerelease Versions
+
+You can also publish prerelease versions:
+```bash
+npm version prerelease  # 1.0.0 → 1.0.1-0
+npm publish --tag beta
+```
+
+Users can then install:
+```bash
+npm install -g huntr-cli@beta
+```
+
+## Checklist Before Publishing
+
+- [ ] Update version in package.json
+- [ ] Update CHANGELOG.md (if you have one)
+- [ ] Run `npm run build` — ensure it compiles
+- [ ] Run `npm run lint` — no linting errors
+- [ ] Run `npm test` (if you have tests)
+- [ ] Update README.md if needed
+- [ ] Commit changes: `git commit -m "chore: v1.0.1"`
+- [ ] Tag release: `git tag v1.0.1`
+- [ ] Push to GitHub: `git push origin main --tags`
+- [ ] Publish to npm: `npm publish`
+- [ ] Verify on npmjs.com
+
+## Unpublishing (if needed)
+
+If you accidentally publish something broken, you can unpublish:
+
+```bash
+# Unpublish a specific version
+npm unpublish huntr-cli@1.0.0
+
+# Unpublish entire package (only works within 24 hours)
+npm unpublish huntr-cli --force
+```
+
+This is a last resort and not recommended. Better to publish a patch fix.
+
+## Keeping npm Secure
+
+- **Never commit `.npmrc`** — add to `.gitignore`
+- **Use automation tokens** if publishing from CI/CD
+- **Scope your package** if you want `npm install @mattmcknight/huntr-cli` (requires pro account)
+- **Enable 2FA** on your npm account: `npm profile set-2fa auth-and-writes`
+
+## Troubleshooting
+
+### "You must be logged in to publish"
+
+```bash
+npm login
+npm whoami  # verify
+```
+
+### "Package name already taken"
+
+Your package.json name is used as-is. If `huntr-cli` is taken, you could use:
+```json
+{
+  "name": "@mattmcknight/huntr-cli",
+  "name": "huntr-cli-mcknight"
+}
+```
+
+### "build script not running"
+
+Make sure `prepublishOnly` is in package.json scripts:
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  }
+}
+```
+
+### "dist/ not uploading"
+
+Check that `dist/` is NOT in `.npmignore`:
+```bash
+cat .npmignore  # should NOT list dist/
+```
+
+If `.npmignore` exists and lists dist/, remove that line.
+
+## Summary
+
+**After publishing to npm:**
+- Users run: `npm install -g huntr-cli`
+- Package lives at: https://npmjs.com/package/huntr-cli
+- Can be used globally: `huntr boards list`
+- Can be used with npx: `npx huntr-cli boards list`
+- GitHub Artifacts are for CI/CD, not distribution
+- npm Registry is the official distribution channel