terminalhire 0.1.0

package/README.md

@@ -0,0 +1,294 @@
+# terminalhire — local-first job matching for developers
+
+Pull curated job matches from a broad public pool. Matching runs entirely on your device. Your profile never leaves your machine.
+
+**Domain:** [terminalhire.com](https://terminalhire.com)
+
+## Install
+
+```sh
+# one-off — no global install needed
+npx terminalhire help
+
+# global install
+npm i -g terminalhire
+
+# wire up the Claude Code statusLine nudge (optional, recommended)
+node $(npm root -g)/terminalhire/install.js
+```
+
+The installer prints a full v3.1 disclosure, asks for explicit "yes", then offers GitHub sign-in (recommended), and finally writes one key to `~/.claude/settings.json`. Install is NOT consent to share your profile — that is a separate, per-role decision.
+
+## Uninstall
+
+```sh
+node install.js --uninstall
+terminalhire logout             # clear GitHub token (if connected)
+terminalhire profile --delete   # also wipe local profile
+rm -rf ~/.jpi               # wipe everything
+```
+
+## Commands
+
+```sh
+terminalhire login              # sign in with GitHub — enriches profile instantly (recommended)
+terminalhire logout             # clear stored GitHub token from ~/.jpi/github-token.enc
+
+terminalhire jobs               # fetch index, match locally, browse ranked roles
+terminalhire jobs --limit 20    # show top 20 results (default: 10)
+terminalhire jobs --remote-only # filter to remote roles only
+terminalhire jobs --all         # show all matches above zero score
+
+terminalhire profile --show     # inspect your encrypted local profile (incl. GitHub fields)
+terminalhire profile --edit     # set displayName, contactEmail, prefs
+terminalhire profile --delete   # wipe profile and encryption key from disk
+```
+
+## GitHub sign-in (recommended)
+
+GitHub is the **primary enrichment signal** for Terminalhire. Signing in solves the cold-start problem — you get accurate matches on the very first run instead of waiting for tag accumulation.
+
+```sh
+terminalhire login
+```
+
+This runs the **GitHub OAuth Device Flow**:
+
+1. A code like `XXXX-XXXX` and a URL (`https://github.com/login/device`) are displayed.
+2. You open the URL, enter the code, and click "Authorize".
+3. Terminalhire polls until you authorize, then stores the token encrypted at `~/.jpi/github-token.enc`.
+4. Your public GitHub profile is fetched, processed, and merged into your local profile.
+
+### What GitHub enriches
+
+| Signal | Source |
+|---|---|
+| Skill tags | Repo languages + repo topics, filtered through `vocabulary.normalize()` |
+| Seniority estimate | Account age × (repos + followers) per [documented thresholds](#seniority-thresholds) |
+| Display name | `user.name` if not already set in profile |
+| Contact email | `user.email` if public and not already set in profile |
+
+### Public scope guarantee
+
+Scope requested: **`read:user`** — public profile + public repos only.
+
+**Private-repo scopes are NEVER requested.** This means:
+- No employer-IP risk from private repos.
+- No code, secrets, or private file access.
+- Only what is already publicly visible on your GitHub profile.
+
+### Data residency
+
+- Token: encrypted at `~/.jpi/github-token.enc` (AES-256-GCM, same scheme as local profile).
+- GitHub data stays **on your machine** — it enriches your local profile.
+- GitHub fields cross the wire **only** in a consented `LeadPayload` when you type "yes".
+- GitHub data is **never sent silently**.
+
+### Seniority thresholds
+
+```
+junior : age < 2 yr  OR  (repos < 5 AND followers < 10)
+mid    : age 2–5 yr  AND repos >= 5
+senior : age 5–9 yr  AND (repos >= 20 OR followers >= 100)
+staff  : age >= 9 yr AND (repos >= 40 OR followers >= 500)
+```
+
+When signals conflict → conservative (lower) estimate. Unresolvable → undefined.
+
+### Mock mode (dev / CI)
+
+No GitHub OAuth App registered yet? Set `TERMINALHIRE_GITHUB_MOCK=1`:
+
+```sh
+TERMINALHIRE_GITHUB_MOCK=1 terminalhire login
+```
+
+Uses the fixture at `fixtures/github-sample.json` instead of a live OAuth flow. No client ID needed. Safe for local development and CI.
+
+### Registering a GitHub OAuth App
+
+1. Go to github.com → Settings → Developer settings → OAuth Apps → **New OAuth App**
+2. Set "Authorization callback URL" to `http://localhost` (not used by device flow)
+3. Enable **Device Authorization** in the OAuth App settings
+4. Copy "Client ID" → set as `GITHUB_CLIENT_ID` in your environment
+5. For public (CLI-only) OAuth Apps, the client secret is optional. If you set one, add it as `GITHUB_CLIENT_SECRET`.
+
+```sh
+export GITHUB_CLIENT_ID=Iv1.your_app_client_id
+# optional:
+export GITHUB_CLIENT_SECRET=your_client_secret
+```
+
+## Status bar nudge
+
+After `terminalhire jobs` runs and finds matches, the Claude Code status bar shows a once-per-session discovery nudge:
+
+```
+✦ N roles match your current work — run: terminalhire jobs
+```
+
+The nudge is printed at most once per Claude Code session. It reads only `~/.jpi/index-cache.json` (a matchCount written by the last `terminalhire jobs` run). It makes zero network calls.
+
+## Architecture (v3.1 hybrid)
+
+```
+Server                              Client (your machine)
+──────────────────────────────      ─────────────────────────────────────────
+Broad public pool:                  ~/.jpi/profile.enc  (AES-256-GCM encrypted)
+  Greenhouse + Ashby (ATS)          ~/.jpi/github-token.enc  (AES-256-GCM)
+  Himalayas + WWR + HN         GET  Fingerprint built from profile
+  Coastal buyer-lead roles    ←─── /api/index (anonymous, no dev data)
+                                    Local match() from @jpi/core
+                                    Ranked list printed to terminal
+                                    ↓
+                               POST /api/lead  ←── ONLY on explicit "yes"
+                                    Named-entity consent per role
+                                    (GitHub fields included only if present AND consented)
+
+GitHub (optional enrichment):
+  github.com/login/device/code ←── Device flow (read:user scope only)
+  api.github.com/users/<login>      Token + data stay on machine
+  (public repos, topics, langs)
+```
+
+**Zero dev-side egress during matching.** The index download is anonymous. GitHub enrichment stays local. The only outbound payload with developer data is a consented `LeadPayload`, for buyer-lead roles only.
+
+## Privacy
+
+| What happens locally | What crosses the wire |
+|---|---|
+| Profile accumulated from personal project sessions | GET /api/index — anonymous, no dev data |
+| Closed-vocab skill tags + seniority (encrypted at rest) | POST /api/lead — ONLY after explicit per-role "yes" consent |
+| GitHub token + public profile data (encrypted at rest) | GitHub fields in lead — ONLY after consent AND GitHub is connected |
+| Employer-repo sessions: language tags only | Nothing else |
+| git email domain + remote host (employer detection only) | |
+
+**Employer-repo exclusion (default on):** if `git config user.email` is a corporate domain or `git remote` points to a non-personal host, only language-level tags (`typescript`, `python`, …) accumulate. Fine-grained framework/infra tags are excluded. The flag `hasEmployerSessions` is recorded locally but never emitted.
+
+## Local profile encryption
+
+- Algorithm: **AES-256-GCM** via Node built-in `crypto` (no external deps).
+- Key: stored at `~/.jpi/key` with `0600` permissions. If `keytar` is installed, the OS keychain is preferred and the key file is not written.
+- Profile file: `~/.jpi/profile.enc` — JSON blob `{ iv, tag, ciphertext }` (all hex-encoded).
+- GitHub token file: `~/.jpi/github-token.enc` — same format, same key.
+
+## Lead payload shape
+
+The exact object sent to `/api/lead` when you consent (nothing else is sent):
+
+```json
+{
+  "opportunityId": "coastal:senior-fullstack-001",
+  "buyerId": "coastal",
+  "buyerLegalName": "Coastal Recruiting LLC",
+  "approvedFields": {
+    "skillTags": ["typescript", "react", "postgresql"],
+    "seniorityBand": "senior",
+    "displayName": "Your Name",
+    "contactEmail": "you@example.com",
+    "note": "Optional note typed at consent time",
+    "github": {
+      "login": "yourlogin",
+      "profileUrl": "https://github.com/yourlogin",
+      "topLanguages": ["typescript", "python", "go"],
+      "publicRepos": 42
+    }
+  },
+  "consentText": "You are about to share the following information with Coastal Recruiting LLC\n...",
+  "createdAt": "2026-06-14T00:00:00.000Z"
+}
+```
+
+- `displayName`, `contactEmail`, and `note` are included only if set.
+- `github` is included **only** when: (a) you have run `terminalhire login` AND (b) you typed "yes" at the consent prompt.
+- `skillTags` is always the full list from your profile.
+
+## Consent prompt text
+
+The exact text shown before any lead is sent (GitHub profile connected):
+
+```
+You are about to share the following information with Coastal Recruiting LLC
+for opportunity: <title> at <company> (<jobId>)
+
+Fields that will be sent:
+  • skillTags: ["typescript","react","postgresql"]
+  • seniorityBand: "senior"
+  • displayName: "Your Name"        ← only if set in profile
+  • contactEmail: "you@example.com" ← only if set in profile
+  • github.login: "yourlogin"
+  • github.profileUrl: "https://github.com/yourlogin"
+  • github.topLanguages: ["typescript","python","go"]
+  • github.publicRepos: 42
+
+GitHub fields above are public data only (scope: read:user). No private repos.
+
+Nothing else leaves your machine. This action is specific to this role.
+Coastal Recruiting LLC will use this to evaluate you for the role.
+You can delete your profile at any time with: terminalhire profile --delete
+
+Share your profile with Coastal Recruiting LLC for this role? [y/N]
+```
+
+Without GitHub: the `github.*` fields and the note about public scope are omitted.
+
+Typing anything other than `y` or `yes` aborts with no network call.
+
+## Apply modes
+
+| `applyMode` | What happens when you select a role |
+|---|---|
+| `direct` | Opens the employer's public URL in your terminal. No data sent. |
+| `buyer-lead` | Triggers the named-entity consent flow above. Nothing sent without "yes". |
+
+The two modes are never silently conflated.
+
+## Zero-egress test (M-5)
+
+```sh
+node test/zero-egress.test.js
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `TERMINALHIRE_API_URL` | `https://terminalhire.com` | Base URL for `/api/index` and `/api/lead` (also accepts legacy `JPI_API_URL`) |
+| `GITHUB_CLIENT_ID` | _(required for real OAuth)_ | GitHub OAuth App client ID (device flow) |
+| `GITHUB_CLIENT_SECRET` | _(optional)_ | GitHub OAuth App client secret (public apps omit this) |
+| `GITHUB_DEVICE_CLIENT_ID` | _(falls back to `GITHUB_CLIENT_ID`)_ | Device-flow specific client ID if different |
+| `TERMINALHIRE_GITHUB_MOCK` | `0` | Set to `1` to skip real OAuth and use the fixture (dev/CI); also accepts legacy `JPI_GITHUB_MOCK` |
+
+## File layout
+
+```
+apps/cli/
+  bin/
+    jpi.js          — statusLine nudge (once-per-session, zero egress)
+    jpi-dispatch.js — 'terminalhire' bin entrypoint, routes subcommands
+    jpi-jobs.js     — 'terminalhire jobs': fetch index, local match, consent flow
+    jpi-login.js    — 'terminalhire login' / 'terminalhire logout': GitHub device flow + enrichment
+    jpi-profile.js  — 'terminalhire profile': show/edit/delete encrypted profile
+    refresh.js      — TOMBSTONE (v1 removed; exits non-zero)
+  src/
+    signal.ts       — local fingerprint extractor (reads dep files + extensions)
+    profile.ts      — encrypted profile: read/write/accumulate/delete
+    github-auth.ts  — GitHub device flow: token I/O + encrypted storage
+  test/
+    zero-egress.test.js  — M-5 zero-egress assertion suite
+  install.js        — v3.1 installer with GitHub onboarding
+  package.json
+```
+
+## How data is used: local default vs consented lead
+
+| Data | Default (local-enrichment) | Opt-in (consented lead) |
+|---|---|---|
+| Skill tags | Stored encrypted locally, used for local matching only | Included in `approvedFields.skillTags` on "yes" |
+| Seniority | Stored encrypted locally | Included in `approvedFields.seniorityBand` on "yes" |
+| Display name | Stored encrypted locally (pre-filled from GitHub if public) | Included if set and "yes" |
+| Contact email | Stored encrypted locally (pre-filled from GitHub public email) | Included if set and "yes" |
+| GitHub login / profileUrl | Stored in `profile.github` on `terminalhire login` | Included in `approvedFields.github` ONLY on "yes" |
+| GitHub topLanguages | Used locally for tag inference (closed vocab) | Included in `approvedFields.github` ONLY on "yes" |
+| GitHub token | Encrypted at `~/.jpi/github-token.enc` | Never sent |
+| Private repos | Never accessed (scope: read:user) | N/A |