katze 0.1.1__tar.gz

katze-0.1.1/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: katze
+Version: 0.1.1
+Summary: JobKatze Auto-Apply CLI
+Author: Monnawat Tongkaw
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ModemT/jobkatze
+Project-URL: Repository, https://github.com/ModemT/jobkatze
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: prompt_toolkit>=3.0.40
+Requires-Dist: typst>=0.11.0
+
+# `katze` — JobKatze Auto-Apply CLI
+
+`katze` pulls your curated (`saved`) or matched (`match`) jobs from JobKatze, generates tailored English cover letters compiled to PDF via Typst and `agy`, opens and pre-fills ATS application forms in a persistent Chrome window, and harvests mandatory application questions across companies.
+
+---
+
+## Prerequisites
+
+1. **Python 3.11+**
+2. **Google Chrome** (or Chromium) installed locally
+3. **Typst** for compiling cover letters to PDF:
+   ```bash
+   brew install typst
+   ```
+4. **Antigravity CLI (`agy`)** on `PATH` for local agent cover letter generation
+
+---
+
+## Installation
+
+### Recommended: Global Tool via `uv`
+
+Install `katze` globally from anywhere on your machine in editable mode:
+
+```bash
+uv tool install --editable /path/to/jobkatze/cli
+```
+
+Whenever you pull changes in the repository, the global `katze` executable automatically reflects code changes. To update dependencies:
+
+```bash
+uv tool install --editable /path/to/jobkatze/cli --reinstall
+```
+
+### Local Virtual Environment
+
+Or install inside a virtual environment:
+
+```bash
+cd cli
+python3 -m venv .venv
+.venv/bin/pip install -e .
+.venv/bin/playwright install chromium
+```
+
+Or using the repository's `api` virtual environment:
+
+```bash
+api/.venv/bin/pip install -e cli
+```
+
+---
+
+## Quickstart
+
+### 1. Initialize configuration and resume
+
+```bash
+katze init /path/to/your/resume.pdf
+```
+
+This creates `~/.config/jobkatze/` (override with `JOBKATZE_CONFIG_DIR`) containing:
+- `resume.pdf` — copy of your resume uploaded to ATS file inputs
+- `profile.yaml` — candidate answers used to auto-fill application forms
+- `letter.typ` — Typst template for compiling cover letter PDFs
+
+### 2. Edit your pre-filled form answers (`katze config`) or update your resume (`katze resume`)
+
+Modify your profile interactively in the terminal UI, set individual fields directly, or open in `$EDITOR`:
+
+```bash
+# Interactive terminal UI (select field by # or name, 'a' for all, 'e' for $EDITOR)
+katze config
+
+# Set fields directly from the command line
+katze config --set city=Munich --set salary_expectation_eur=95000
+
+# Show current configuration table
+katze config --show
+```
+
+Update your resume at any time (copies into `~/.config/jobkatze/resume.pdf` and syncs to backend):
+
+```bash
+# Inspect active resume path and file status
+katze resume
+
+# Choose a PDF via native macOS Finder dialog
+katze resume --finder
+
+# Copy a specific PDF into ~/.config/jobkatze/resume.pdf and sync to backend
+katze resume /path/to/new_resume.pdf
+```
+
+### 3. Interactive Shell & Command Guides (`katze`)
+
+Launch the full interactive shell with in-place screen switching, `↑`/`↓` arrow keys, and command suggestions:
+
+```bash
+# Launch interactive shell
+katze
+
+# View quick reference guide anytime
+katze help
+
+# View dedicated guide for a specific command
+katze help resume
+katze help apply
+katze help login
+```
+
+Inside the interactive shell:
+- Type `/` to open the command suggestion menu.
+- Use `↑`/`↓` arrow keys or `Tab` to navigate options and press `Enter` to select.
+- Each command has its own screen with step-by-step guidance and actions.
+- Screens switch in place without filling up terminal scrollback. Press `Esc` or `/back` to return to the main menu, and `q` or `/quit` to exit.
+
+### 4. Log in to JobKatze
+
+Authenticate seamlessly through your web browser or command line:
+
+```bash
+# Browser login: opens JobKatze web app to authorize in 1 click
+katze login
+
+# Headless login with email and password
+katze login --email you@example.com --password secret
+
+# Local devserver (http://localhost:7071/api)
+katze login --local
+```
+
+When running `katze login`, your default browser opens the authorization page. If you are already logged in to JobKatze in your browser, click **Authorize katze** to connect immediately without retyping credentials.
+
+---
+
+## Commands
+
+### `katze apply` — Open and pre-fill application tabs in Chrome
+
+```bash
+# Apply to jobs you bookmarked ("Saved") on JobKatze Web
+katze apply --from saved --limit 5
+
+# Pull top resume-matched jobs from direct ATS boards (Greenhouse, Personio, Ashby, Lever, Recruitee, Workable)
+katze apply --from match --limit 5
+
+# Filter by specific ATS platform(s)
+katze apply --from match --source greenhouse,personio,ashby --limit 5
+
+# Apply to a single job ID
+katze apply --job <job_id>
+
+# Regenerate cover letters even if cached locally
+katze apply --job <job_id> --regen
+
+# Prompt immediately in the terminal for submission confirmation
+katze apply --from saved --prompt
+```
+
+#### How persistent Chrome tabs work
+- `katze apply` launches a detached Chrome process using `~/.config/jobkatze/chrome-profile` on `--remote-debugging-port=9222` and connects via Chrome DevTools Protocol (CDP).
+- When `katze apply` exits, **all Chrome tabs stay open**.
+- Running `katze apply` again attaches to the same Chrome window and appends new tabs next to your existing ones.
+- Each tab title is prefixed with:
+  - `[READY] Company - Role` when 0 mandatory fields remain unfilled.
+  - `[NEEDS N] Company - Role` when `N` mandatory fields need manual input (outlined in amber `2px solid #e08b00` on the page).
+
+---
+
+### `katze confirm` — Mark submitted tabs as `applied`
+
+After reviewing open tabs and clicking **Submit** in Chrome, sync your submission status back to JobKatze Web:
+
+```bash
+# Interactively confirm each pending tab [y/N]
+katze confirm
+
+# Mark all pending tabs as applied without prompting
+katze confirm --all
+
+# Mark a specific job ID as applied
+katze confirm --job <job_id>
+```
+
+---
+
+### `katze letter` — Generate a tailored cover letter PDF only
+
+```bash
+# Generate ~/.config/jobkatze/applications/<job_id>/cover_letter.{txt,pdf}
+katze letter <job_id>
+
+# Pass a custom angle or instruction to the agent
+katze letter <job_id> --hint "Emphasize distributed systems and Kubernetes experience"
+
+# Overwrite an existing letter
+katze letter <job_id> --regen
+```
+
+---
+
+### `katze questions` — Harvest & analyze mandatory ATS questions
+
+Scan application forms over plain HTTP (no browser required) to inspect what mandatory questions companies ask and verify what percentage of fields your `profile.yaml` covers:
+
+```bash
+# Scan mandatory questions across top 25 resume-matched direct-ATS jobs
+katze questions scan --from match --limit 25
+
+# Scan mandatory questions across your saved jobs
+katze questions scan --from saved --limit 25
+
+# View the cumulative frequency and profile coverage report from ~/.config/jobkatze/questions.jsonl
+katze questions report
+```
+
+---
+
+## Local Files (`~/.config/jobkatze/`)
+
+| Path | Purpose |
+| :--- | :--- |
+| `config.toml` | API base URL and authentication token (`0600` permissions) |
+| `profile.yaml` | Pre-filled candidate answers for text inputs, dropdowns, radio groups, and checkboxes |
+| `resume.pdf` | Candidate CV uploaded to file inputs |
+| `letter.typ` | Typst template compiled for each cover letter |
+| `applications/<job_id>/cover_letter.txt` | Plain-text cover letter generated by `agy` |
+| `applications/<job_id>/cover_letter.pdf` | Compiled PDF cover letter uploaded to ATS forms |
+| `questions.jsonl` | Deduplicated log of observed mandatory ATS form questions |
+| `pending_tabs.json` | Queue of open tabs awaiting `katze confirm` |
+| `chrome-profile/` | Persistent Chromium user data directory |
+
+---
+
+## Running Tests
+
+```bash
+PYTHONPATH=cli api/.venv/bin/pytest cli/tests/
+```

katze-0.1.1/README.md

@@ -0,0 +1,240 @@
+# `katze` — JobKatze Auto-Apply CLI
+
+`katze` pulls your curated (`saved`) or matched (`match`) jobs from JobKatze, generates tailored English cover letters compiled to PDF via Typst and `agy`, opens and pre-fills ATS application forms in a persistent Chrome window, and harvests mandatory application questions across companies.
+
+---
+
+## Prerequisites
+
+1. **Python 3.11+**
+2. **Google Chrome** (or Chromium) installed locally
+3. **Typst** for compiling cover letters to PDF:
+   ```bash
+   brew install typst
+   ```
+4. **Antigravity CLI (`agy`)** on `PATH` for local agent cover letter generation
+
+---
+
+## Installation
+
+### Recommended: Global Tool via `uv`
+
+Install `katze` globally from anywhere on your machine in editable mode:
+
+```bash
+uv tool install --editable /path/to/jobkatze/cli
+```
+
+Whenever you pull changes in the repository, the global `katze` executable automatically reflects code changes. To update dependencies:
+
+```bash
+uv tool install --editable /path/to/jobkatze/cli --reinstall
+```
+
+### Local Virtual Environment
+
+Or install inside a virtual environment:
+
+```bash
+cd cli
+python3 -m venv .venv
+.venv/bin/pip install -e .
+.venv/bin/playwright install chromium
+```
+
+Or using the repository's `api` virtual environment:
+
+```bash
+api/.venv/bin/pip install -e cli
+```
+
+---
+
+## Quickstart
+
+### 1. Initialize configuration and resume
+
+```bash
+katze init /path/to/your/resume.pdf
+```
+
+This creates `~/.config/jobkatze/` (override with `JOBKATZE_CONFIG_DIR`) containing:
+- `resume.pdf` — copy of your resume uploaded to ATS file inputs
+- `profile.yaml` — candidate answers used to auto-fill application forms
+- `letter.typ` — Typst template for compiling cover letter PDFs
+
+### 2. Edit your pre-filled form answers (`katze config`) or update your resume (`katze resume`)
+
+Modify your profile interactively in the terminal UI, set individual fields directly, or open in `$EDITOR`:
+
+```bash
+# Interactive terminal UI (select field by # or name, 'a' for all, 'e' for $EDITOR)
+katze config
+
+# Set fields directly from the command line
+katze config --set city=Munich --set salary_expectation_eur=95000
+
+# Show current configuration table
+katze config --show
+```
+
+Update your resume at any time (copies into `~/.config/jobkatze/resume.pdf` and syncs to backend):
+
+```bash
+# Inspect active resume path and file status
+katze resume
+
+# Choose a PDF via native macOS Finder dialog
+katze resume --finder
+
+# Copy a specific PDF into ~/.config/jobkatze/resume.pdf and sync to backend
+katze resume /path/to/new_resume.pdf
+```
+
+### 3. Interactive Shell & Command Guides (`katze`)
+
+Launch the full interactive shell with in-place screen switching, `↑`/`↓` arrow keys, and command suggestions:
+
+```bash
+# Launch interactive shell
+katze
+
+# View quick reference guide anytime
+katze help
+
+# View dedicated guide for a specific command
+katze help resume
+katze help apply
+katze help login
+```
+
+Inside the interactive shell:
+- Type `/` to open the command suggestion menu.
+- Use `↑`/`↓` arrow keys or `Tab` to navigate options and press `Enter` to select.
+- Each command has its own screen with step-by-step guidance and actions.
+- Screens switch in place without filling up terminal scrollback. Press `Esc` or `/back` to return to the main menu, and `q` or `/quit` to exit.
+
+### 4. Log in to JobKatze
+
+Authenticate seamlessly through your web browser or command line:
+
+```bash
+# Browser login: opens JobKatze web app to authorize in 1 click
+katze login
+
+# Headless login with email and password
+katze login --email you@example.com --password secret
+
+# Local devserver (http://localhost:7071/api)
+katze login --local
+```
+
+When running `katze login`, your default browser opens the authorization page. If you are already logged in to JobKatze in your browser, click **Authorize katze** to connect immediately without retyping credentials.
+
+---
+
+## Commands
+
+### `katze apply` — Open and pre-fill application tabs in Chrome
+
+```bash
+# Apply to jobs you bookmarked ("Saved") on JobKatze Web
+katze apply --from saved --limit 5
+
+# Pull top resume-matched jobs from direct ATS boards (Greenhouse, Personio, Ashby, Lever, Recruitee, Workable)
+katze apply --from match --limit 5
+
+# Filter by specific ATS platform(s)
+katze apply --from match --source greenhouse,personio,ashby --limit 5
+
+# Apply to a single job ID
+katze apply --job <job_id>
+
+# Regenerate cover letters even if cached locally
+katze apply --job <job_id> --regen
+
+# Prompt immediately in the terminal for submission confirmation
+katze apply --from saved --prompt
+```
+
+#### How persistent Chrome tabs work
+- `katze apply` launches a detached Chrome process using `~/.config/jobkatze/chrome-profile` on `--remote-debugging-port=9222` and connects via Chrome DevTools Protocol (CDP).
+- When `katze apply` exits, **all Chrome tabs stay open**.
+- Running `katze apply` again attaches to the same Chrome window and appends new tabs next to your existing ones.
+- Each tab title is prefixed with:
+  - `[READY] Company - Role` when 0 mandatory fields remain unfilled.
+  - `[NEEDS N] Company - Role` when `N` mandatory fields need manual input (outlined in amber `2px solid #e08b00` on the page).
+
+---
+
+### `katze confirm` — Mark submitted tabs as `applied`
+
+After reviewing open tabs and clicking **Submit** in Chrome, sync your submission status back to JobKatze Web:
+
+```bash
+# Interactively confirm each pending tab [y/N]
+katze confirm
+
+# Mark all pending tabs as applied without prompting
+katze confirm --all
+
+# Mark a specific job ID as applied
+katze confirm --job <job_id>
+```
+
+---
+
+### `katze letter` — Generate a tailored cover letter PDF only
+
+```bash
+# Generate ~/.config/jobkatze/applications/<job_id>/cover_letter.{txt,pdf}
+katze letter <job_id>
+
+# Pass a custom angle or instruction to the agent
+katze letter <job_id> --hint "Emphasize distributed systems and Kubernetes experience"
+
+# Overwrite an existing letter
+katze letter <job_id> --regen
+```
+
+---
+
+### `katze questions` — Harvest & analyze mandatory ATS questions
+
+Scan application forms over plain HTTP (no browser required) to inspect what mandatory questions companies ask and verify what percentage of fields your `profile.yaml` covers:
+
+```bash
+# Scan mandatory questions across top 25 resume-matched direct-ATS jobs
+katze questions scan --from match --limit 25
+
+# Scan mandatory questions across your saved jobs
+katze questions scan --from saved --limit 25
+
+# View the cumulative frequency and profile coverage report from ~/.config/jobkatze/questions.jsonl
+katze questions report
+```
+
+---
+
+## Local Files (`~/.config/jobkatze/`)
+
+| Path | Purpose |
+| :--- | :--- |
+| `config.toml` | API base URL and authentication token (`0600` permissions) |
+| `profile.yaml` | Pre-filled candidate answers for text inputs, dropdowns, radio groups, and checkboxes |
+| `resume.pdf` | Candidate CV uploaded to file inputs |
+| `letter.typ` | Typst template compiled for each cover letter |
+| `applications/<job_id>/cover_letter.txt` | Plain-text cover letter generated by `agy` |
+| `applications/<job_id>/cover_letter.pdf` | Compiled PDF cover letter uploaded to ATS forms |
+| `questions.jsonl` | Deduplicated log of observed mandatory ATS form questions |
+| `pending_tabs.json` | Queue of open tabs awaiting `katze confirm` |
+| `chrome-profile/` | Persistent Chromium user data directory |
+
+---
+
+## Running Tests
+
+```bash
+PYTHONPATH=cli api/.venv/bin/pytest cli/tests/
+```

katze-0.1.1/katze/__init__.py

@@ -0,0 +1,4 @@
+"""JobKatze CLI package."""
+
+__version__ = "0.1.0"
+