huntr-cli 1.0.9

package/docs/TESTING.md

@@ -0,0 +1,216 @@
+# Testing Guide
+
+Guide to testing huntr-cli following the development workflow.
+
+## Overview
+
+Tests use **Vitest** (Vite-native test framework) and document the complete huntr-cli workflow:
+- Git workflow (conventional commits, hooks)
+- Publishing workflow (automatic releases)
+- Output formatting features
+- Command structure
+
+## Running Tests
+
+### All Tests
+```bash
+npm test
+```
+
+### Specific Test Suite
+```bash
+npm test -- --testNamePattern="Publishing"
+```
+
+### Watch Mode
+```bash
+npm test -- --watch
+```
+
+### Coverage Report
+```bash
+npm test -- --coverage
+```
+
+## Test Structure
+
+### tests/example.test.ts
+
+Documents the complete workflow:
+
+| Section | Purpose |
+|---------|---------|
+| **Command Structure** | Verifies CLI commands and output formats |
+| **Build & Compilation** | TypeScript and ESLint pass in CI |
+| **Git Workflow** | Conventional commits and git hooks |
+| **Publishing Workflow** | Automatic npm publishing and versioning |
+| **Output Formatting** | Field selection and export formats |
+| **Documentation** | Guides and man pages exist |
+
+## Workflow Verification
+
+### ✅ Local Development
+```bash
+# 1. Create feature branch
+git checkout -b feat/my-feature
+
+# 2. Make changes
+npm run lint:fix
+npm run build
+
+# 3. Commit (pre-commit hook runs)
+git commit -m "feat: add feature"
+
+# 4. Push (pre-push hook runs: typecheck → lint → build)
+git push origin feat/my-feature
+```
+
+### ✅ Pull Request
+- Create PR on GitHub
+- CI runs automatically (lint, typecheck, build, test)
+- All checks must pass
+- Code review and approval
+
+### ✅ Publishing
+```bash
+# 1. Bump version
+git checkout main
+npm version minor  # Creates commit + tag
+
+# 2. Push with tags
+git push origin main --tags
+
+# 3. Release created automatically
+# - release.yml creates GitHub Release with artifacts
+# - publish.yml triggers on release
+# - npm package published automatically
+```
+
+### ✅ Version Verification
+```bash
+# Check npm registry
+npm view huntr-cli version
+
+# Install latest
+npm install -g huntr-cli@latest
+
+# Verify
+huntr --version
+```
+
+## Test Examples
+
+### Example: Command Structure
+```typescript
+it('should support boards list command', () => {
+  const commands = ['boards', 'jobs', 'activities'];
+  expect(commands).toContain('boards');
+});
+```
+
+### Example: Publishing Workflow
+```typescript
+it('should create artifacts on version bump', () => {
+  // release.yml detects version change
+  // Creates tar.gz and zip archives
+  // Creates GitHub Release with artifacts
+  expect(true).toBe(true);
+});
+```
+
+### Example: Git Workflow
+```typescript
+it('should trigger pre-push hook on git push', () => {
+  // Pre-push hook runs: typecheck → lint → build
+  expect(true).toBe(true);
+});
+```
+
+## CI Test Execution
+
+GitHub Actions runs tests automatically:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Run tests
+  run: npm test
+```
+
+Tests verify:
+- Command structure is correct
+- All output formats available
+- Publishing workflow documented
+- Git workflow enforced
+- Documentation complete
+
+## Writing New Tests
+
+When adding features, add tests to `tests/example.test.ts`:
+
+```typescript
+describe('New Feature', () => {
+  it('should do something', () => {
+    const result = newFeature();
+    expect(result).toBe(true);
+  });
+});
+```
+
+Test structure:
+- **Describe:** Feature or workflow area
+- **It:** Specific behavior or requirement
+- **Expect:** Assertion of correct behavior
+
+## Continuous Integration
+
+### On Every Push
+```
+→ Pre-commit hook (lint)
+→ Pre-push hook (typecheck, lint, build)
+→ GitHub Actions CI (lint, typecheck, build, test)
+```
+
+### On Pull Request
+```
+→ Same CI checks
+→ Code review required
+→ Tests must pass
+```
+
+### On Main Branch Push
+```
+→ All CI checks pass
+→ Version bump triggers release.yml
+→ GitHub Release created with artifacts
+→ npm publishing triggered
+```
+
+## Troubleshooting
+
+### Tests Failing
+```bash
+# Run with verbose output
+npm test -- --reporter=verbose
+
+# Check test names
+npm test -- --listTests
+```
+
+### Missing Dependencies
+```bash
+npm install
+npm run build:shared  # For workspace tests
+```
+
+### ESLint/Typecheck Failing
+```bash
+npm run lint:fix
+npm run typecheck
+```
+
+## See Also
+
+- [DEV-SETUP.md](./DEV-SETUP.md) — Development workflow
+- [CI-CD-SETUP.md](./CI-CD-SETUP.md) — Hook configuration
+- [AUTOMATIC-PUBLISHING.md](./AUTOMATIC-PUBLISHING.md) — Publishing workflow
+- [.github/workflows/ci.yml](../.github/workflows/ci.yml) — CI configuration

package/eslint.config.js

@@ -0,0 +1,68 @@
+import js from '@eslint/js';
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+
+export default [
+  {
+    ignores: ['dist/**', 'node_modules/**', '*.config.js'],
+  },
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+        project: './tsconfig.json',
+      },
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        setTimeout: 'readonly',
+        fetch: 'readonly',
+        URL: 'readonly',
+        require: 'readonly',
+        WebSocket: 'readonly',
+        MessageEvent: 'readonly',
+        Blob: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tsPlugin.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-misused-promises': 'warn',
+      'no-console': 'off',
+      'no-process-exit': 'off',
+      'curly': ['error', 'multi-line'],
+      'eol-last': ['error', 'always'],
+      'no-trailing-spaces': 'error',
+      'no-multiple-empty-lines': ['error', { max: 1 }],
+      'quotes': ['error', 'single', { avoidEscape: true }],
+      'semi': ['error', 'always'],
+      'comma-dangle': [
+        'error',
+        {
+          arrays: 'always-multiline',
+          objects: 'always-multiline',
+          imports: 'always-multiline',
+          exports: 'always-multiline',
+          functions: 'always-multiline',
+        },
+      ],
+    },
+  },
+];

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "huntr-cli",
+  "version": "1.0.9",
+  "type": "module",
+  "description": "CLI tool for managing your Huntr job search board. Track activities, search jobs, and manage your application pipeline from the terminal.",
+  "main": "dist/cli.js",
+  "bin": {
+    "huntr": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "lint": "eslint src --max-warnings 13",
+    "lint:fix": "eslint src --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "prepare": "husky install",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mattmck/huntr-cli.git"
+  },
+  "keywords": [
+    "huntr",
+    "job-search",
+    "cli",
+    "job-tracking",
+    "activities",
+    "command-line"
+  ],
+  "author": "Matt McKnight <mcknight.matthew@gmail.com>",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/mattmck/huntr-cli/issues"
+  },
+  "homepage": "https://github.com/mattmck/huntr-cli#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.2.1",
+    "axios": "^1.13.5",
+    "commander": "^14.0.3",
+    "dotenv": "^17.3.1",
+    "exceljs": "^4.4.0",
+    "keytar": "^7.9.0",
+    "pdfkit": "^0.13.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^8.56.0",
+    "@types/node": "^25.3.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.56.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.0"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,88 @@
+import axios, { AxiosInstance, AxiosError } from 'axios';
+import dotenv from 'dotenv';
+
+// Load .env file silently (debug: false suppresses info messages)
+dotenv.config({ debug: false });
+
+/** A static token string OR an async function that returns a fresh token. */
+export type TokenProvider = string | (() => Promise<string>);
+
+export class HuntrApiClient {
+  private axiosInstance: AxiosInstance;
+  private tokenProvider: () => Promise<string>;
+
+  constructor(tokenProvider: TokenProvider, baseURL: string = 'https://api.huntr.co/org') {
+    this.tokenProvider =
+      typeof tokenProvider === 'string'
+        ? async () => tokenProvider
+        : tokenProvider;
+
+    this.axiosInstance = axios.create({ baseURL });
+
+    // Inject a fresh Authorization header before every request
+    this.axiosInstance.interceptors.request.use(async (config) => {
+      const token = await this.tokenProvider();
+      if (!token) throw new Error('No API token available.');
+      config.headers = config.headers ?? {};
+      config.headers['Authorization'] = `Bearer ${token}`;
+      config.headers['Content-Type'] = 'application/json';
+      return config;
+    });
+
+    this.axiosInstance.interceptors.response.use(
+      (response) => response,
+      (error: AxiosError) => {
+        if (error.response) {
+          const status = error.response.status;
+          const apiError = error.response.data as any;
+          const message = apiError?.error?.message ?? apiError?.message ?? 'API request failed';
+          throw new Error(`HTTP ${status}: ${message}`);
+        }
+        if (error.request) {
+          throw new Error('No response from API - check your network connection');
+        }
+        throw error;
+      },
+    );
+  }
+
+  async get<T>(endpoint: string, params?: Record<string, any>): Promise<T> {
+    const response = await this.axiosInstance.get<T>(endpoint, { params });
+    return response.data;
+  }
+
+  async post<T>(endpoint: string, data?: any): Promise<T> {
+    const response = await this.axiosInstance.post<T>(endpoint, data);
+    return response.data;
+  }
+
+  async put<T>(endpoint: string, data?: any): Promise<T> {
+    const response = await this.axiosInstance.put<T>(endpoint, data);
+    return response.data;
+  }
+
+  async delete<T>(endpoint: string): Promise<T> {
+    const response = await this.axiosInstance.delete<T>(endpoint);
+    return response.data;
+  }
+
+  async *paginate<T>(
+    endpoint: string,
+    params: Record<string, any> = {},
+    limit: number = 100,
+  ): AsyncGenerator<T[], void, undefined> {
+    let next: string | undefined = undefined;
+
+    do {
+      const queryParams: Record<string, any> = { ...params, limit };
+      if (next) queryParams.next = next;
+      const response = await this.get<{ data: T[]; next?: string }>(endpoint, queryParams);
+      yield response.data;
+      next = response.next;
+    } while (next);
+  }
+}
+
+export const createClient = (tokenProvider: TokenProvider, baseURL?: string): HuntrApiClient => {
+  return new HuntrApiClient(tokenProvider, baseURL);
+};

package/src/api/personal/activities.ts

@@ -0,0 +1,66 @@
+import { HuntrApiClient } from '../client';
+import { PersonalAction, PersonalJob, PersonalJobsResponse } from '../../types/personal';
+
+export class PersonalActionsApi {
+  constructor(private client: HuntrApiClient) {}
+
+  // Returns object map { [actionId]: PersonalAction }
+  async listByBoard(boardId: string): Promise<Record<string, PersonalAction>> {
+    return this.client.get<Record<string, PersonalAction>>(`/board/${boardId}/actions`);
+  }
+
+  // Returns flattened array sorted by date desc, optionally filtered by action types
+  async listByBoardFlat(
+    boardId: string,
+    opts?: { since?: Date; types?: string[] },
+  ): Promise<PersonalAction[]> {
+    const raw = await this.listByBoard(boardId);
+    let actions = Object.values(raw);
+
+    if (opts?.since) {
+      const cutoff = opts.since.getTime();
+      actions = actions.filter(a => new Date(a.date || a.createdAt).getTime() >= cutoff);
+    }
+
+    if (opts?.types && opts.types.length > 0) {
+      actions = actions.filter(a => opts.types!.includes(a.actionType));
+    }
+
+    return actions.sort((a, b) =>
+      new Date(b.date || b.createdAt).getTime() - new Date(a.date || a.createdAt).getTime(),
+    );
+  }
+
+  // Joins actions with job data to produce enriched rows
+  async weekSummary(boardId: string): Promise<Array<{
+    date: string;
+    actionType: string;
+    company: string;
+    jobTitle: string;
+    status: string;
+    url: string;
+  }>> {
+    const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+    const [actions, jobsResponse] = await Promise.all([
+      this.listByBoardFlat(boardId, { since }),
+      this.client.get<PersonalJobsResponse>(`/board/${boardId}/jobs`),
+    ]);
+
+    const jobs = jobsResponse.jobs;
+
+    return actions
+      .filter(a => a.actionType !== 'ACTIVITY_CREATED')
+      .map(a => {
+        const jobId = a.data?._job;
+        const job: PersonalJob | undefined = jobId ? jobs[jobId] : undefined;
+        return {
+          date: new Date(a.date || a.createdAt).toISOString().substring(0, 16),
+          actionType: a.actionType,
+          company: a.data?.company?.name ?? '',
+          jobTitle: a.data?.job?.title ?? '',
+          status: a.data?.toList?.name ?? '',
+          url: job?.url ?? '',
+        };
+      });
+  }
+}

package/src/api/personal/boards.ts

@@ -0,0 +1,14 @@
+import { HuntrApiClient } from '../client';
+import { Board } from '../../types/personal';
+
+export class PersonalBoardsApi {
+  constructor(private client: HuntrApiClient) {}
+
+  async list(): Promise<Board[]> {
+    return this.client.get<Board[]>('/boards');
+  }
+
+  async get(boardId: string): Promise<Board> {
+    return this.client.get<Board>(`/boards/${boardId}`);
+  }
+}

package/src/api/personal/index.ts

@@ -0,0 +1,25 @@
+import { createClient, TokenProvider } from '../client';
+import { PersonalUserApi } from './user';
+import { PersonalBoardsApi } from './boards';
+import { PersonalJobsApi } from './jobs';
+import { PersonalActionsApi } from './activities';
+
+export class HuntrPersonalApi {
+  public user: PersonalUserApi;
+  public boards: PersonalBoardsApi;
+  public jobs: PersonalJobsApi;
+  public actions: PersonalActionsApi;
+
+  constructor(tokenProvider: TokenProvider) {
+    const client = createClient(tokenProvider, 'https://api.huntr.co/api');
+    this.user = new PersonalUserApi(client);
+    this.boards = new PersonalBoardsApi(client);
+    this.jobs = new PersonalJobsApi(client);
+    this.actions = new PersonalActionsApi(client);
+  }
+}
+
+export * from './user';
+export * from './boards';
+export * from './jobs';
+export * from './activities';

package/src/api/personal/jobs.ts

@@ -0,0 +1,33 @@
+import { HuntrApiClient } from '../client';
+import { PersonalJob, PersonalJobsResponse } from '../../types/personal';
+
+export class PersonalJobsApi {
+  constructor(private client: HuntrApiClient) {}
+
+  // API returns { jobs: { [id]: PersonalJob } } — an object map, not an array
+  async listByBoard(boardId: string): Promise<PersonalJobsResponse> {
+    return this.client.get<PersonalJobsResponse>(`/board/${boardId}/jobs`);
+  }
+
+  // Convenience: returns flat array
+  async listByBoardFlat(boardId: string): Promise<PersonalJob[]> {
+    const response = await this.listByBoard(boardId);
+    return Object.values(response.jobs);
+  }
+
+  async get(boardId: string, jobId: string): Promise<PersonalJob> {
+    return this.client.get<PersonalJob>(`/board/${boardId}/jobs/${jobId}`);
+  }
+
+  async create(boardId: string, job: Partial<PersonalJob>): Promise<PersonalJob> {
+    return this.client.post<PersonalJob>(`/board/${boardId}/jobs`, job);
+  }
+
+  async update(boardId: string, jobId: string, updates: Partial<PersonalJob>): Promise<PersonalJob> {
+    return this.client.put<PersonalJob>(`/board/${boardId}/jobs/${jobId}`, updates);
+  }
+
+  async delete(boardId: string, jobId: string): Promise<void> {
+    return this.client.delete<void>(`/board/${boardId}/jobs/${jobId}`);
+  }
+}

package/src/api/personal/user.ts

@@ -0,0 +1,10 @@
+import { HuntrApiClient } from '../client';
+import { UserProfile } from '../../types/personal';
+
+export class PersonalUserApi {
+  constructor(private client: HuntrApiClient) {}
+
+  async getProfile(): Promise<UserProfile> {
+    return this.client.get<UserProfile>('/me');
+  }
+}