careerclaw-js 0.11.0

package/README.md

@@ -0,0 +1,348 @@
+# careerclaw-js
+
+[![CI](https://github.com/orestes-garcia-martinez/careerclaw-js/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/orestes-garcia-martinez/careerclaw-js/actions/workflows/ci.yml)
+
+**Privacy-first job search automation for OpenClaw — Node.js / TypeScript.**
+
+CareerClaw turns your AI agent into a structured daily workflow:
+fetch listings → rank matches → draft outreach → track applications.
+
+- **Local-first:** your resume and results stay on your machine
+- **No subscription:** one-time purchase for Pro
+- **Bring your own LLM API key (optional):** use OpenAI or Anthropic to enhance drafts
+- **Works everywhere:** Node.js is natively available in every OpenClaw deployment
+
+> **Why a Node.js rewrite?** The OpenClaw gateway ships Node.js v22 and npm natively,
+> but has no Python package manager — making the original Python package's self-healing
+> installation impossible in Docker-based deployments. careerclaw-js resolves this permanently.
+
+---
+
+## How It Works
+
+1. **Fetches** job listings from RemoteOK RSS and Hacker News Who's Hiring
+2. **Ranks** them against your profile using keyword overlap, experience alignment, salary fit, and work-mode preference
+3. **Drafts** outreach for each top match (deterministic template on Free; LLM-enhanced on Pro)
+4. **Tracks** your application pipeline locally in `.careerclaw/`
+
+One command. Everything is local.
+
+---
+
+## Quickstart
+
+### 1. Install
+
+```bash
+npm install -g careerclaw-js
+```
+
+Verify:
+
+```bash
+careerclaw-js --version
+```
+
+### 2. Set up via OpenClaw (recommended)
+
+If you are running CareerClaw through OpenClaw/ClawHub, the agent guides you through
+setup automatically. Upload your resume and it will extract your profile, ask two questions
+(work mode + salary floor), and run your first briefing.
+
+### 3. Set up manually
+
+Create the runtime directory and profile:
+
+```bash
+mkdir -p ~/.careerclaw
+```
+
+Create `~/.careerclaw/profile.json`:
+
+```json
+{
+  "skills": ["typescript", "python", "react", "sql"],
+  "target_roles": ["senior engineer", "staff engineer"],
+  "experience_years": 7,
+  "work_mode": "remote",
+  "resume_summary": "Senior engineer with 7 years building distributed systems and developer tools.",
+  "location": "Austin, TX",
+  "salary_min": 150000
+}
+```
+
+### 4. Run your first briefing
+
+```bash
+# Dry run first — no files written, safe to preview
+careerclaw-js --dry-run
+
+# With your resume for better match quality (recommended)
+careerclaw-js --resume-txt ~/.careerclaw/resume.txt --dry-run
+
+# Full run when you're happy with the results
+careerclaw-js --resume-txt ~/.careerclaw/resume.txt
+
+# JSON output for agent/script consumption
+careerclaw-js --resume-txt ~/.careerclaw/resume.txt --json
+```
+
+---
+
+## Sample Output
+
+```
+=== CareerClaw Daily Briefing ===
+Fetched jobs: 289 | Sources: remoteok: 98 | hackernews: 191
+Duration: 1887ms fetch + 24ms rank
+
+Top Matches:
+
+1) Senior Full-Stack Engineer @ Instinct Science  [hackernews]
+   score: 0.2329 | fit: 8%
+   matches: react, typescript, design, aws, senior
+   gaps:    elixir, postgresql, emr
+   location: REMOTE (US)
+   url: https://news.ycombinator.com/item?id=47233919
+```
+
+---
+
+## Free vs Pro
+
+| Feature | Free | Pro ($39 lifetime) |
+|---|---|---|
+| Daily briefing | ✅ | ✅ |
+| Top 3 ranked matches | ✅ | ✅ |
+| Application tracking | ✅ | ✅ |
+| Outreach email draft (template) | ✅ | ✅ |
+| LLM-enhanced outreach email | — | ✅ |
+| Resume gap analysis | — | ✅ |
+| Cover letter (tailored, <300 words) | — | ✅ coming soon |
+
+**Pro tier: $39 one-time (lifetime license).**
+
+Purchase: https://ogm.gumroad.com/l/careerclaw-pro
+
+---
+
+## Pro: Activating
+
+Purchase a license key on Gumroad. The key is emailed immediately after payment.
+
+### Docker / self-hosted
+
+Add to your `.env`:
+
+```env
+CAREERCLAW_PRO_KEY=YOUR-KEY-HERE
+CAREERCLAW_GUMROAD_PRODUCT_ID=YOUR-PRODUCT-ID
+CAREERCLAW_OPENAI_KEY=sk-...
+```
+
+### OpenClaw managed users
+
+Tell your agent:
+
+> "Set my CAREERCLAW_PRO_KEY to YOUR-KEY-HERE"
+
+The key is validated against Gumroad on first use and cached locally as a SHA-256 hash.
+Re-validation happens every 7 days (requires internet).
+
+---
+
+## Pro: LLM-Enhanced Drafts
+
+With a valid Pro license and an LLM API key, CareerClaw writes personalised outreach emails
+using your actual resume signals mapped to each job's specific requirements. Falls back to
+the deterministic template silently on any LLM failure.
+
+Failover chain example (tries Anthropic first, falls back to OpenAI):
+
+```env
+CAREERCLAW_ANTHROPIC_KEY=sk-ant-...
+CAREERCLAW_OPENAI_KEY=sk-...
+CAREERCLAW_LLM_CHAIN=anthropic/claude-haiku-4-5-20251001,openai/gpt-4o-mini
+```
+
+Estimated cost per run: ~$0.003 at claude-haiku-4-5-20251001 pricing (3 drafts).
+
+---
+
+## All CLI Options
+
+```
+careerclaw-js [OPTIONS]
+
+Options:
+  -p, --profile PATH     Path to profile.json
+                         (default: .careerclaw/profile.json)
+      --resume-txt PATH  Plain-text resume for enhanced matching
+                         (default: .careerclaw/resume.txt if present)
+  -k, --top-k INT        Number of top matches to return (default: 3)
+  -d, --dry-run          Run without writing tracking or run log
+  -j, --json             Machine-readable JSON output (no colour, no headers)
+  -h, --help             Show this help message
+```
+
+---
+
+## Application Tracking
+
+Tracking is written automatically on each non-dry-run. Status lifecycle:
+
+`saved` → `applied` → `interviewing` → `offer` → `rejected`
+
+Runtime files — all stored under `.careerclaw/`:
+
+| File | Contents |
+|---|---|
+| `profile.json` | Career profile |
+| `resume.txt` | Plain-text resume (optional) |
+| `tracking.json` | Saved jobs keyed by stable `job_id` |
+| `runs.jsonl` | Append-only run log (one line per run) |
+| `.license_cache` | Pro license validation cache (SHA-256 hash only) |
+
+> **File format compatibility:** careerclaw-js uses the same JSON formats as the Python
+> `careerclaw` package. `profile.json`, `tracking.json`, and `runs.jsonl` are fully
+> interchangeable between both implementations.
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `CAREERCLAW_PRO_KEY` | Pro license key (Gumroad) |
+| `CAREERCLAW_GUMROAD_PRODUCT_ID` | Gumroad product ID for license validation |
+| `CAREERCLAW_ANTHROPIC_KEY` | Anthropic API key for LLM draft enhancement |
+| `CAREERCLAW_OPENAI_KEY` | OpenAI API key for LLM draft enhancement |
+| `CAREERCLAW_LLM_KEY` | Legacy single-provider key fallback |
+| `CAREERCLAW_LLM_CHAIN` | Ordered failover chain, e.g. `anthropic/claude-haiku-4-5-20251001,openai/gpt-4o-mini` |
+| `CAREERCLAW_LLM_MODEL` | Override default LLM model |
+| `CAREERCLAW_LLM_PROVIDER` | `anthropic` or `openai` (inferred from key when not set) |
+| `CAREERCLAW_DIR` | Override runtime directory (default: `.careerclaw`) |
+| `HN_WHO_IS_HIRING_ID` | Override HN thread ID (updated monthly) |
+
+Copy `.env.example` to `.env` and fill in your values.
+
+---
+
+## Roadmap
+
+| Phase | Scope | Status |
+|---|---|---|
+| 1 | Models + config | ✅ v0.1.0 |
+| 2 | RemoteOK + HN adapters | ✅ v0.2.0 |
+| 3 | Source aggregation + text processing | ✅ v0.3.0 |
+| 4 | Matching engine + scoring | ✅ v0.4.0 |
+| 5 | Requirements + resume intelligence + gap analysis | ✅ v0.5.0 |
+| 6 | Deterministic drafting | ✅ v0.6.0 |
+| 7 | Tracking + run log | ✅ v0.7.0 |
+| 8–9 | Briefing pipeline + CLI + npm publish | ✅ v0.8.0–v0.8.1 |
+| 10 | LLM draft enhancement (Pro) | ✅ v0.10.0 |
+| 11 | Gumroad license validation + offline cache | ✅ v0.11.0 |
+
+
+---
+
+## Development
+
+### Prerequisites
+
+- Node.js ≥ 20
+- npm ≥ 10
+
+### Setup
+
+```bash
+git clone https://github.com/orestes-garcia-martinez/careerclaw-js
+cd careerclaw-js
+npm install
+```
+
+### Running tests
+
+```bash
+# All tests (offline, no network)
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Type-check only
+npm run lint
+```
+
+### Smoke tests (live network — run before release)
+
+```bash
+npm run smoke:sources    # RemoteOK + HN connectivity
+npm run smoke:briefing   # Full pipeline end-to-end
+npm run smoke:llm        # LLM keys + Pro license validation
+```
+
+### Project structure
+
+```
+careerclaw-js/
+├── src/
+│   ├── adapters/       # RemoteOK RSS + HN Firebase adapters
+│   ├── core/           # Shared text processing
+│   ├── matching/       # Scoring engine
+│   ├── tests/          # Vitest test suite (270 tests, fully offline)
+│   ├── briefing.ts     # Pipeline orchestrator
+│   ├── cli.ts          # CLI entry point
+│   ├── config.ts       # Environment and source configuration
+│   ├── drafting.ts     # Deterministic draft templates (Free tier)
+│   ├── gap.ts          # Gap analysis engine
+│   ├── license.ts      # Pro license validation (Gumroad)
+│   ├── llm-enhance.ts  # LLM draft enhancement (Pro)
+│   ├── models.ts       # Canonical data schemas
+│   ├── requirements.ts # Job requirements extraction
+│   ├── resume-intel.ts # Resume intelligence
+│   ├── sources.ts      # Source aggregation
+│   └── tracking.ts     # Tracking repository
+├── scripts/            # Smoke + debug scripts (not published)
+├── SKILL.md            # OpenClaw skill definition
+├── CHANGELOG.md
+├── SECURITY.md
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## Security & Privacy
+
+careerclaw-js is built on a local-first architecture.
+
+- **No backend.** No telemetry. No analytics endpoint.
+- **API keys never stored.** Keys are read from the environment at runtime only.
+- **License cache is hash-only.** Only SHA-256 of the license key is written to disk.
+- **LLM privacy.** Only extracted keyword signals sent to the LLM — never raw resume text.
+- **External calls:** `remoteok.com`, `hacker-news.firebaseio.com`, `api.gumroad.com`,
+  and your configured LLM provider (using your own key).
+
+See [SECURITY.md](SECURITY.md) for the vulnerability disclosure policy.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the full version history.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+## Support
+
+- **GitHub Issues:** bug reports and feature requests
+- **Response SLA:** critical bugs < 48h · general questions < 72h
+- **Security disclosures:** see [SECURITY.md](SECURITY.md)
+- **Pro support:** orestes.garcia.martinez@gmail.com

package/SECURITY.md

@@ -0,0 +1,156 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in CareerClaw, please report it
+responsibly. **Do not open a public GitHub issue** for security matters.
+
+**Contact:** orestes.garcia.martinez@gmail.com
+**Subject line:** `[SECURITY] CareerClaw JS — <brief description>`
+
+Include as much detail as you can:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Affected version(s)
+
+### Response SLA
+
+| Severity                                                  | First response | Resolution target      | Release vehicle        |
+|-----------------------------------------------------------|----------------|------------------------|------------------------|
+| Critical (data exposure, key leakage)                     | < 24 hours     | < 72 hours             | Immediate patch        |
+| High (pipeline hijack, file write outside `.careerclaw/`) | < 48 hours     | < 1 week               | Patch release          |
+| Medium / Low                                              | < 1 week       | Next scheduled release | Patch or minor release |
+
+You will receive an acknowledgement within the first response window. If
+you do not hear back within 48 hours, follow up directly.
+
+We do not currently offer a bug bounty program, but we will credit
+responsible disclosures in the CHANGELOG unless you prefer to remain
+anonymous.
+
+---
+
+## Security Architecture
+
+CareerClaw is designed with a local-first, minimal-footprint security
+model. The threat surface is intentionally small.
+
+### What runs locally
+
+Everything. CareerClaw has no backend server, no cloud endpoint, and
+no telemetry pipeline. All computation — fetching, ranking, drafting,
+and persistence — runs on the user's machine.
+
+### External network calls
+
+CareerClaw makes exactly two categories of outbound network requests:
+
+| Destination                                    | Protocol | Auth               | Purpose                    |
+|------------------------------------------------|----------|--------------------|----------------------------|
+| `remoteok.com/remote-jobs.rss`                 | HTTPS    | None               | Job ingestion              |
+| `hacker-news.firebaseio.com/v0/item/{id}.json` | HTTPS    | None               | Job ingestion              |
+| User's configured LLM provider (optional)      | HTTPS    | User's own API key | Pro draft enhancement only |
+| `api.polar.sh` (optional)                      | HTTPS    | License key hash   | Pro license validation only |
+
+No other network calls are made. No analytics endpoints. No version-check
+beacons. No callback URLs.
+
+### Credential handling
+
+CareerClaw touches four credential types. None are ever written to disk raw.
+
+| Credential                    | Source      | Stored on disk?              | Logged? |
+|-------------------------------|-------------|------------------------------|---------|
+| `CAREERCLAW_PRO_KEY`          | Env var     | SHA-256 hash only            | Never   |
+| `CAREERCLAW_ANTHROPIC_KEY`    | Env var     | Never                        | Never   |
+| `CAREERCLAW_OPENAI_KEY`       | Env var     | Never                        | Never   |
+| `CAREERCLAW_LLM_KEY` (legacy) | Env var     | Never                        | Never   |
+
+Additional guarantees:
+- Keys are never written to `tracking.json`, `runs.jsonl`, or any structured output
+- Keys are never passed as CLI arguments (always environment variables)
+- Exception messages are sanitised before propagation — keys are stripped
+- `src/tests/config.test.ts` contains a dedicated test asserting that no key
+  value appears in any structured output field
+
+### License cache
+
+When `CAREERCLAW_PRO_KEY` is first validated, only a SHA-256 hash of the key
+is written to `.careerclaw/.license_cache`. The raw key is never stored.
+Subsequent runs compare against the cached hash to avoid repeated network
+validation calls.
+
+### Local data
+
+All runtime state is stored under `.careerclaw/` in the user's home directory.
+This folder is gitignored by default.
+
+| File                  | Contents                                     | Sensitive?          |
+|-----------------------|----------------------------------------------|---------------------|
+| `profile.json`        | Skills, roles, experience, salary range      | Yes — do not commit |
+| `resume.txt`          | Full resume text                             | Yes — do not commit |
+| `resume.pdf`          | Full resume (PDF)                            | Yes — do not commit |
+| `tracking.json`       | Job IDs and application statuses             | Moderate            |
+| `runs.jsonl`          | Anonymous run metrics (job counts, duration) | No                  |
+| `.license_cache`      | SHA-256 hash of Pro key only                 | No                  |
+
+**Never commit `.careerclaw/` to version control.** The `.gitignore`
+entry is present by default — verify it before pushing.
+
+### Source code transparency
+
+- No obfuscated code
+- No Base64-encoded URLs or network targets
+- No minified scripts in the repository
+- No `postinstall` hooks that execute network calls
+- All dependencies declared explicitly in `package.json`
+
+Every release is scanned with VirusTotal before publishing to ClawHub.
+
+### Permissions
+
+CareerClaw requests only the permissions it actually uses:
+
+| Permission   | Used for                                      |
+|--------------|-----------------------------------------------|
+| `read`       | `profile.json`, `tracking.json`, resume files |
+| `write`      | `tracking.json`, `runs.jsonl`                 |
+| `exec`       | Running the Node.js pipeline                  |
+| `web_search` | Fetching RemoteOK RSS and HN Firebase API     |
+
+No `notification`, `cron`, or elevated permissions are requested in
+the free tier.
+
+---
+
+## Known Limitations
+
+**HN thread ID is manually maintained.** The Hacker News "Who is Hiring?"
+thread ID in `src/config.ts` must be updated monthly. An outdated ID will
+result in stale or missing results — not a security issue, but worth noting
+for transparency.
+
+**Resume text is stored in plaintext.** `.careerclaw/resume.txt` is
+unencrypted. Users in shared environments should ensure appropriate
+filesystem permissions on the `.careerclaw/` directory.
+
+**LLM provider data handling.** When an LLM key is set and Pro is active,
+job description excerpts and resume signal keywords are sent to the configured
+provider. CareerClaw never sends the full resume text to any LLM — only the
+extracted keyword signals from `ResumeIntelligence`. Review your provider's
+data retention policy if this is a concern:
+- Anthropic: https://www.anthropic.com/legal/privacy
+- OpenAI: https://openai.com/policies/privacy-policy
+
+---
+
+## Supported Versions
+
+Security fixes are applied to the latest release only. We do not backport
+fixes to older versions.
+
+| Version              | Supported |
+|----------------------|-----------|
+| Latest (main branch) | ✅         |
+| Older releases       | ❌         |