@jsonresume/jobs 0.7.0

package/README.md

@@ -0,0 +1,270 @@
+# @jsonresume/job-search
+
+[![npm version](https://img.shields.io/npm/v/@jsonresume/job-search)](https://www.npmjs.com/package/@jsonresume/job-search)
+[![license](https://img.shields.io/npm/l/@jsonresume/job-search)](./LICENSE)
+[![node](https://img.shields.io/node/v/@jsonresume/job-search)](https://nodejs.org)
+
+Search Hacker News "Who is Hiring" jobs matched against your [JSON Resume](https://jsonresume.org). Jobs are semantically ranked using AI embeddings — your resume is compared against hundreds of monthly job postings to surface the best fits.
+
+## Quick Start
+
+```bash
+npx @jsonresume/jobs
+```
+
+That's it. The CLI walks you through login on first run — all you need is a resume hosted at [registry.jsonresume.org](https://registry.jsonresume.org).
+
+## Prerequisites
+
+- **Node.js** >= 18
+- A JSON Resume on the [JSON Resume Registry](https://registry.jsonresume.org) (free, backed by your GitHub Gist)
+- *(Optional)* `OPENAI_API_KEY` — enables AI summaries and batch ranking in the TUI
+
+## Installation
+
+Run directly with npx (no install needed):
+
+```bash
+npx @jsonresume/jobs
+```
+
+Or install globally:
+
+```bash
+npm install -g @jsonresume/job-search
+jsonresume-jobs
+```
+
+## Authentication
+
+On first run, the CLI prompts for your GitHub username, verifies your resume exists on the registry, generates an API key, and saves it to `~/.jsonresume/config.json`. Future runs skip straight to the TUI.
+
+You can also authenticate manually:
+
+```bash
+# Via environment variable
+export JSONRESUME_API_KEY=jr_yourname_xxxxx
+
+# Generate a key via curl
+curl -s -X POST https://registry.jsonresume.org/api/v1/keys \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"YOUR_GITHUB_USERNAME"}'
+```
+
+To clear saved credentials:
+
+```bash
+npx @jsonresume/jobs logout
+```
+
+## Interactive TUI
+
+The default command launches a full terminal interface for browsing and managing jobs.
+
+```bash
+npx @jsonresume/jobs
+```
+
+### Features
+
+- **Split-pane detail view** — press Enter to see a compact job list on the left and full details on the right, navigate jobs without leaving the detail panel
+- **Tab-based views** — All / Interested / Applied / Maybe / Passed with live counts
+- **Persistent filters** — remote, salary, keyword, days — saved to disk per search profile
+- **Custom search profiles** — targeted searches like "remote React jobs in climate tech" with AI-powered reranking
+- **Two-pass loading** — results appear instantly from vector search, then reshuffle when LLM reranking completes in the background
+- **Batch operations** — select multiple jobs with `v`, then bulk-mark them all at once
+- **Inline search** — press `n` to quickly filter visible jobs by keyword
+- **Export** — press `e` to export your shortlist to a markdown file
+- **Toast notifications** — instant feedback on every action
+- **Help modal** — press `?` for a full keyboard reference
+- **AI summaries** — per-job summaries and batch ranking (requires `OPENAI_API_KEY`)
+- **Vim-style navigation** — `j`/`k`, `g`/`G`, `Ctrl+U`/`Ctrl+D`, `/` for search profiles, `f` for filters
+
+### Keyboard Shortcuts
+
+#### List View
+
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Move down |
+| `k` / `↑` | Move up |
+| `g` / `G` | Jump to first / last job |
+| `Ctrl+U` / `Ctrl+D` | Page up / page down |
+| `Enter` | Open split-pane detail view |
+| `i` | Mark interested |
+| `x` | Mark applied |
+| `m` | Mark maybe |
+| `p` | Mark passed |
+| `v` | Toggle batch selection |
+| `Tab` / `Shift+Tab` | Next / previous tab |
+| `n` | Inline keyword search |
+| `f` | Manage filters |
+| `/` | Search profiles |
+| `Space` | AI summary |
+| `S` | AI batch review |
+| `e` | Export shortlist to markdown |
+| `R` | Force refresh |
+| `?` | Help modal |
+| `q` | Quit |
+
+#### Detail View (Split Pane)
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate jobs (updates detail pane) |
+| `J` / `K` | Scroll detail content |
+| `o` | Open HN post in browser |
+| `i` / `x` / `m` / `p` | Mark job state |
+| `Space` | AI summary |
+| `Esc` / `q` | Back to full list |
+
+#### Filters & Search Profiles
+
+| Key | Action |
+|-----|--------|
+| `a` | Add filter |
+| `d` | Delete filter / search profile |
+| `n` | New search profile |
+| `Enter` | Select / edit |
+| `Esc` | Close |
+
+## CLI Commands
+
+For scripting and pipelines, the CLI also supports direct commands:
+
+```bash
+npx @jsonresume/jobs search                              # Find matching jobs
+npx @jsonresume/jobs search --remote --min-salary 150    # Remote, $150k+ salary
+npx @jsonresume/jobs search --search "rust"              # Keyword filter
+npx @jsonresume/jobs detail 181420                       # Full job details
+npx @jsonresume/jobs mark 181420 interested              # Mark a job
+npx @jsonresume/jobs me                                  # Your resume summary
+npx @jsonresume/jobs update ./resume.json                # Update your resume
+npx @jsonresume/jobs help                                # All options
+```
+
+### Command Reference
+
+| Command | Description |
+|---------|-------------|
+| *(default)* | Launch interactive TUI |
+| `search` | Find matching jobs (table output) |
+| `detail <id>` | Show full details for a job |
+| `mark <id> <state>` | Set job state: `interested`, `not_interested`, `applied`, `maybe`, `dismissed` |
+| `me` | Show your resume summary |
+| `update <file>` | Upload a new version of your resume |
+| `logout` | Remove saved API key |
+| `help` | Show help |
+
+### Search Options
+
+| Flag | Description |
+|------|-------------|
+| `--top N` | Number of results (default: 20, max: 100) |
+| `--days N` | How far back to look (default: 30) |
+| `--remote` | Remote jobs only |
+| `--min-salary N` | Minimum salary in thousands (e.g. `150` = $150k) |
+| `--search TERM` | Keyword filter (title, company, skills) |
+| `--interested` | Show only jobs marked interested |
+| `--applied` | Show only jobs marked applied |
+| `--json` | Output raw JSON for piping |
+
+### Mark States
+
+| State | Icon | Meaning |
+|-------|------|---------|
+| `interested` | ⭐ | You want this job |
+| `applied` | 📨 | You've applied |
+| `maybe` | ? | Considering it |
+| `not_interested` | ✗ | Not for you |
+| `dismissed` | 👁 | Hide from results |
+
+## How Ranking Works
+
+The system uses a five-stage pipeline to match and rank jobs against your resume.
+
+### Stage 1: Embedding Generation
+
+Your JSON Resume is fetched from [registry.jsonresume.org](https://registry.jsonresume.org) and converted to text (label, summary, skills, work history). This text is embedded using OpenAI's `text-embedding-3-large` model into a 3072-dimensional vector.
+
+Job postings from HN's monthly "Who is Hiring?" threads are parsed by GPT into structured data (title, company, skills, salary, remote, location) and embedded into the same vector space.
+
+### Stage 2: Vector Similarity Search
+
+Your resume embedding is compared against all job embeddings using cosine similarity via [pgvector](https://github.com/pgvector/pgvector). The top ~500 candidates are retrieved in ~200ms. This is purely semantic — it finds jobs that "sound like" your resume. Jobs you've already passed on are excluded server-side so you always get fresh results.
+
+### Stage 3: Custom Search Profiles
+
+When you create a search profile (e.g. "remote React roles at climate tech startups"), two techniques boost the prompt's influence:
+
+**HyDE (Hypothetical Document Embedding):** Instead of naively blending your prompt into resume text, the system generates a hypothetical ideal job posting matching your preferences. This creates a document-to-document comparison, which is far more effective than query-to-document matching.
+
+**Embedding Interpolation:** The resume and HyDE vectors are combined: `0.65 × hyde + 0.35 × resume`. This gives your search intent 65% influence on ranking, versus plain resume matching where the resume dominates ~80% of the signal.
+
+### Stage 4: LLM Reranking
+
+For custom searches, the top 30 vector results are re-scored by `gpt-4.1-mini`. Each job receives a 1–10 relevance score considering skill alignment, experience level, location fit, and your stated preferences.
+
+The final score blends both signals: `0.4 × vector_score + 0.6 × llm_score`. This lets the LLM override semantic similarity — a job that's a great vector match but contradicts your preferences gets pushed down.
+
+In the TUI, this runs as a two-pass load: jobs appear instantly from vector search, then reshuffle when reranking finishes in the background.
+
+### Stage 5: Client-side Filtering
+
+After server-side ranking, the TUI applies local filters (remote only, minimum salary, keyword, days). Filters are persisted per search profile, so switching profiles restores each one's filters.
+
+## Claude Code Skill
+
+This package includes a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) that turns job searching into a guided, AI-assisted experience.
+
+### Install
+
+```bash
+mkdir -p ~/.claude/skills/jsonresume-hunt
+cp node_modules/@jsonresume/job-search/skills/jsonresume-hunt/SKILL.md \
+   ~/.claude/skills/jsonresume-hunt/SKILL.md
+```
+
+### Use
+
+In Claude Code, type:
+
+```
+/jsonresume-hunt
+/jsonresume-hunt remote React jobs over $150k
+```
+
+The skill interviews you about what you're looking for, runs multiple searches, researches top companies, does skill gap analysis, collects your decisions, and generates a markdown tracker with your shortlist and outreach drafts.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `JSONRESUME_API_KEY` | No | API key (auto-generated on first run if not set) |
+| `OPENAI_API_KEY` | No | Enables AI summaries and batch ranking in TUI |
+| `JSONRESUME_BASE_URL` | No | API base URL override (default: `https://registry.jsonresume.org`) |
+
+## Data Storage
+
+| Path | Contents |
+|------|----------|
+| `~/.jsonresume/config.json` | API key and username |
+| `~/.jsonresume/filters.json` | Saved filter presets per search profile |
+| `~/.jsonresume/cache/` | Cached job results (auto-expires) |
+
+## Contributing
+
+This package is part of the [jsonresume.org](https://github.com/jsonresume/jsonresume.org) monorepo.
+
+```bash
+git clone https://github.com/jsonresume/jsonresume.org.git
+cd jsonresume.org
+pnpm install
+node packages/job-search/bin/cli.js help
+```
+
+See the repo root [CLAUDE.md](../../CLAUDE.md) for code standards and contribution guidelines.
+
+## License
+
+[MIT](./LICENSE)

package/bin/cli.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+
+/**
+ * @jsonresume/job-search — Search HN jobs matched to your JSON Resume
+ *
+ * Just run:  npx @jsonresume/jobs
+ */
+
+const VERSION = '0.7.0';
+
+const BASE_URL =
+  getArg('--base-url') ||
+  process.env.JSONRESUME_BASE_URL ||
+  'https://registry.jsonresume.org';
+
+// ── Arg parsing ────────────────────────────────────────────
+
+function getArg(name) {
+  const idx = process.argv.indexOf(name);
+  if (idx === -1) return null;
+  return process.argv[idx + 1];
+}
+
+function hasFlag(name) {
+  return process.argv.includes(name);
+}
+
+// ── API client ─────────────────────────────────────────────
+
+let _apiKey;
+
+async function getApiKey() {
+  if (_apiKey) return _apiKey;
+  const { ensureApiKey } = await import('../src/auth.js');
+  _apiKey = await ensureApiKey(BASE_URL);
+  return _apiKey;
+}
+
+async function api(path, options = {}) {
+  const apiKey = await getApiKey();
+  const url = `${BASE_URL}/api/v1${path}`;
+  const res = await fetch(url, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+      ...options.headers,
+    },
+  });
+
+  const data = await res.json();
+  if (!res.ok) {
+    console.error(`Error: ${data.error || res.statusText}`);
+    process.exit(1);
+  }
+  return data;
+}
+
+// ── Formatters ─────────────────────────────────────────────
+
+function formatSalary(salary, salaryUsd) {
+  if (salaryUsd) return `$${Math.round(salaryUsd / 1000)}k`;
+  if (salary) return salary;
+  return '—';
+}
+
+function formatLocation(loc, remote) {
+  const parts = [];
+  if (loc?.city) parts.push(loc.city);
+  if (loc?.countryCode) parts.push(loc.countryCode);
+  if (remote) parts.push(`(${remote})`);
+  return parts.join(', ') || '—';
+}
+
+function stateIcon(state) {
+  const icons = {
+    interested: '⭐',
+    applied: '📨',
+    not_interested: '✗',
+    dismissed: '👁',
+    maybe: '?',
+  };
+  return icons[state] || ' ';
+}
+
+// ── Commands ───────────────────────────────────────────────
+
+async function cmdSearch() {
+  const params = new URLSearchParams();
+  params.set('top', getArg('--top') || '20');
+  params.set('days', getArg('--days') || '30');
+  if (hasFlag('--remote')) params.set('remote', 'true');
+  if (getArg('--min-salary')) params.set('min_salary', getArg('--min-salary'));
+  if (getArg('--search')) params.set('search', getArg('--search'));
+
+  const { jobs } = await api(`/jobs?${params}`);
+
+  let filtered = jobs;
+  if (hasFlag('--interested'))
+    filtered = jobs.filter((j) => j.state === 'interested');
+  if (hasFlag('--applied'))
+    filtered = jobs.filter((j) => j.state === 'applied');
+
+  if (hasFlag('--json')) {
+    console.log(JSON.stringify(filtered, null, 2));
+    return;
+  }
+
+  if (filtered.length === 0) {
+    console.log('No matching jobs found.');
+    return;
+  }
+
+  console.log(
+    `\n Found ${filtered.length} matching jobs (last ${params.get(
+      'days'
+    )} days)\n`
+  );
+  console.log(
+    ' ' +
+      'St'.padEnd(3) +
+      'Score'.padEnd(7) +
+      'ID'.padEnd(8) +
+      'Title'.padEnd(35) +
+      'Company'.padEnd(25) +
+      'Location'.padEnd(25) +
+      'Salary'.padEnd(10)
+  );
+  console.log(' ' + '─'.repeat(112));
+
+  for (const j of filtered) {
+    const line =
+      ' ' +
+      stateIcon(j.state).padEnd(3) +
+      String(j.similarity).padEnd(7) +
+      String(j.id).padEnd(8) +
+      (j.title || '').slice(0, 33).padEnd(35) +
+      (j.company || '').slice(0, 23).padEnd(25) +
+      formatLocation(j.location, j.remote).slice(0, 23).padEnd(25) +
+      formatSalary(j.salary, j.salary_usd).padEnd(10);
+    console.log(line);
+  }
+  console.log('');
+}
+
+async function cmdDetail() {
+  const id = process.argv[3];
+  if (!id) {
+    console.error('Usage: jsonresume-jobs detail <job_id>');
+    process.exit(1);
+  }
+
+  const job = await api(`/jobs/${id}`);
+
+  if (hasFlag('--json')) {
+    console.log(JSON.stringify(job, null, 2));
+    return;
+  }
+
+  console.log(`\n${'═'.repeat(70)}`);
+  console.log(`  ${job.title || 'Unknown'} at ${job.company || 'Unknown'}`);
+  console.log(`${'═'.repeat(70)}`);
+  console.log(`  ID:         ${job.id}`);
+  console.log(`  Location:   ${formatLocation(job.location, job.remote)}`);
+  console.log(`  Salary:     ${formatSalary(job.salary, job.salary_usd)}`);
+  console.log(`  Type:       ${job.type || '—'}`);
+  console.log(`  Experience: ${job.experience || '—'}`);
+  console.log(`  Posted:     ${job.posted_at || '—'}`);
+  console.log(
+    `  State:      ${
+      job.state ? `${stateIcon(job.state)} ${job.state}` : 'none'
+    }`
+  );
+  console.log(`  HN URL:     ${job.url || '—'}`);
+
+  if (job.description) {
+    console.log(`\n  Description:\n  ${job.description}`);
+  }
+
+  if (job.skills?.length) {
+    console.log(`\n  Skills: ${job.skills.map((s) => s.name).join(', ')}`);
+  }
+
+  if (job.responsibilities?.length) {
+    console.log(`\n  Responsibilities:`);
+    job.responsibilities.forEach((r) => console.log(`    • ${r}`));
+  }
+
+  if (job.qualifications?.length) {
+    console.log(`\n  Qualifications:`);
+    job.qualifications.forEach((q) => console.log(`    • ${q}`));
+  }
+  console.log('');
+}
+
+async function cmdMark() {
+  const id = process.argv[3];
+  const state = process.argv[4];
+  const feedback = getArg('--feedback');
+
+  if (!id || !state) {
+    console.error(
+      'Usage: jsonresume-jobs mark <job_id> <interested|not_interested|applied|dismissed|maybe> [--feedback "reason"]'
+    );
+    process.exit(1);
+  }
+
+  const body = { state };
+  if (feedback) body.feedback = feedback;
+
+  const result = await api(`/jobs/${id}`, {
+    method: 'PUT',
+    body: JSON.stringify(body),
+  });
+
+  const desc = result.job_title
+    ? `${result.job_title} at ${result.job_company}`
+    : `#${result.id}`;
+  console.log(`${stateIcon(result.state)} Marked ${desc} as ${result.state}`);
+}
+
+async function cmdMe() {
+  const data = await api('/me');
+
+  if (hasFlag('--json')) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  const r = data.resume;
+  console.log(`\n  ${r.basics?.name} (${data.username})`);
+  console.log(`  ${r.basics?.label || ''}`);
+  console.log(
+    `  ${r.basics?.location?.city || ''}, ${
+      r.basics?.location?.countryCode || ''
+    }`
+  );
+  console.log(`\n  Skills: ${(r.skills || []).map((s) => s.name).join(', ')}`);
+  console.log(`  Work: ${(r.work || []).length} entries`);
+  console.log(`  Projects: ${(r.projects || []).length} entries`);
+  console.log('');
+}
+
+async function cmdUpdate() {
+  const filePath = process.argv[3];
+  if (!filePath) {
+    console.error('Usage: jsonresume-jobs update <path-to-resume.json>');
+    process.exit(1);
+  }
+
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const resolved = path.resolve(filePath);
+
+  let resume;
+  try {
+    const raw = fs.readFileSync(resolved, 'utf-8');
+    resume = JSON.parse(raw);
+  } catch (err) {
+    console.error(`Error reading ${resolved}: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!resume.basics) {
+    console.error('Invalid resume — must have a "basics" section.');
+    process.exit(1);
+  }
+
+  const result = await api('/resume', {
+    method: 'PUT',
+    body: JSON.stringify(resume),
+  });
+
+  console.log(`Resume updated for ${result.username}.`);
+}
+
+async function cmdLogout() {
+  const { loadConfig, saveConfig } = await import('../src/auth.js');
+  const config = loadConfig();
+  const username = config.username || 'unknown';
+  saveConfig({});
+  console.log(`Logged out (removed saved key for ${username}).`);
+}
+
+function cmdHelp() {
+  console.log(`
+jsonresume-jobs v${VERSION} — Search HN "Who is Hiring" jobs matched to your JSON Resume
+
+QUICK START
+  npx @jsonresume/jobs              Launch the interactive TUI (logs in automatically)
+
+COMMANDS
+  (default)                         Interactive TUI with AI features
+  search                            Find matching jobs (table output)
+  detail <id>                       Show full details for a job
+  mark <id> <state>                 Mark a job's state
+  me                                Show your resume summary
+  update <file>                     Update your resume on the registry
+  logout                            Remove saved API key
+  help                              Show this help message
+
+SEARCH OPTIONS
+  --top N                           Number of results (default: 20, max: 100)
+  --days N                          How far back to look (default: 30)
+  --remote                          Remote jobs only
+  --min-salary N                    Minimum salary in thousands (e.g. 150)
+  --search TERM                     Keyword filter (searches title, company, skills)
+  --interested                      Show only jobs you marked interested
+  --applied                         Show only jobs you marked applied
+
+MARK STATES
+  interested                        You want this job
+  not_interested                    Not for you
+  applied                           You've applied
+  maybe                             Considering it
+  dismissed                         Hide from results
+
+GLOBAL OPTIONS
+  --json                            Output raw JSON (for piping / Claude Code)
+  --base-url URL                    API base URL (default: https://registry.jsonresume.org)
+  --feedback "reason"               Add a reason when marking (with mark command)
+
+ENVIRONMENT
+  JSONRESUME_API_KEY                Your API key (optional — auto-login if not set)
+  OPENAI_API_KEY                    Enable AI features (summaries, reranking)
+  JSONRESUME_BASE_URL               API base URL override
+
+EXAMPLES
+  npx @jsonresume/jobs                                              # TUI
+  npx @jsonresume/jobs search --remote --min-salary 150             # CLI search
+  npx @jsonresume/jobs detail 181420                                # Job details
+  npx @jsonresume/jobs mark 181420 interested --feedback "great"    # Mark job
+`);
+}
+
+// ── Main ───────────────────────────────────────────────────
+
+async function main() {
+  const cmd = process.argv[2] || '';
+
+  if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    return cmdHelp();
+  }
+
+  if (cmd === '--version' || cmd === '-v') {
+    console.log(VERSION);
+    return;
+  }
+
+  if (cmd === 'logout') {
+    return cmdLogout();
+  }
+
+  switch (cmd) {
+    case 'search':
+      return cmdSearch();
+    case 'detail':
+      return cmdDetail();
+    case 'mark':
+      return cmdMark();
+    case 'me':
+      return cmdMe();
+    case 'update':
+      return cmdUpdate();
+    case 'browse':
+    case 'tui':
+    case '':
+    default: {
+      // Default: launch TUI
+      const apiKey = await getApiKey();
+      const { default: runTUI } = await import('../src/tui/App.js');
+      return runTUI({ baseUrl: BASE_URL, apiKey });
+    }
+  }
+}
+
+main().catch((e) => {
+  console.error(`Fatal: ${e.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@jsonresume/jobs",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Search Hacker News jobs matched against your JSON Resume",
+  "bin": {
+    "jsonresume-jobs": "./bin/cli.js",
+    "jobs": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "keywords": [
+    "jsonresume",
+    "jobs",
+    "hacker-news",
+    "job-search",
+    "cli",
+    "tui",
+    "ink"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsonresume/jsonresume.org",
+    "directory": "packages/job-search"
+  },
+  "license": "MIT",
+  "author": "Thomas Davis <thomasalwyndavis@gmail.com>",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.58",
+    "@ai-sdk/openai": "^3.0.41",
+    "ai": "^6.0.116",
+    "ink": "^6.8.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^19.2.4"
+  }
+}