applika-cli 0.1.0__tar.gz

applika_cli-0.1.0/.gitignore

@@ -0,0 +1,170 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# vscode
+settings.json
+.vscode/
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+/documents
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.claude/settings.local.json
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+*.db
+
+fake_ledger_db.json
+*.pem
+logs/

applika_cli-0.1.0/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

applika_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this CLI.
+
+## Keeping This File Up to Date
+
+**CLAUDE.md is a living document. Update it when the CLI changes in ways that affect how you work here.**
+
+Update when:
+- A new command or sub-app is added
+- The package structure changes
+- A new development command is added or removed
+- Packaging or install behavior changes
+- A new required environment variable is introduced
+- Validation, formatting, or test workflow changes
+
+Do NOT add:
+- Implementation details already visible in the code
+- Ephemeral task notes or in-progress work
+- Anything already obvious from the command help or tests
+
+---
+
+## Commands
+
+```bash
+# Install the CLI globally from the local checkout
+uv tool install --force .
+
+# Install dev dependencies
+uv sync
+
+# Show CLI help
+uv run python -m applika.main --help
+
+# Run linter with auto-fix
+make lint
+
+# Run formatter
+make format
+
+# Run tests
+make test
+
+# Build wheel for PyPI
+uv build
+```
+
+---
+
+## End-of-Task Validation
+
+**Always finish a CLI task by running formatting, linting, and tests.**
+
+Run these at the end of any CLI code change:
+
+```bash
+make format
+make lint
+make test
+```
+
+Do not skip this unless the user explicitly asks you not to run validation or the environment prevents it.
+
+---
+
+## Package Structure
+
+All source code lives under `src/applika/` (importable as `applika`).
+
+```
+src/applika/
+├── main.py              # Entry point: def main() -> None
+├── app.py               # Root Typer app + --api-base-url callback → AppConfig
+├── config.py            # AppConfig dataclass + resolve_api_base_url
+├── skills/
+│   └── applika-cli/     # Bundled SKILL.md (included in wheel, symlinked/copied by skill install)
+├── schemas/
+│   ├── enums.py         # StrEnum types: Currency, SalaryPeriod, ExperienceLevel,
+│   │                    #   WorkMode, ApplicationMode, ModeFilter, StatusFilter, OutputFormat
+│   └── application.py  # Pydantic models: ApplicationCreate, ApplicationUpdate,
+│                        #   ApplicationCompanyInput (vendored from backend DTOs)
+├── lib/
+│   ├── api.py           # ApiClient (httpx + cookie auth), ApiError, AuthError,
+│   │                    #   require_session, create_session_from_exchange
+│   ├── session.py       # SessionData, SessionStore (~/.config/applika/session.json)
+│   └── loopback.py      # LoopbackLoginServer for OAuth callback
+├── utils/
+│   ├── dates.py         # parse_date, ensure_date_string
+│   └── output.py        # render_application_table, print_application_summary
+└── commands/
+    ├── auth.py          # login + logout + whoami Typer commands
+    ├── skill.py         # skill install Typer sub-app
+    └── applications/
+        ├── __init__.py  # applications_app Typer sub-app with default-to-list callback
+        ├── commands.py  # list_applications, new_application, edit_application
+        ├── filter.py    # filter_applications, resolve_platform_id
+        └── payloads.py  # ApplicationArgs dataclass + build_application_payload
+```
+
+## Key Patterns
+
+- **Global state**: `AppConfig` (dataclass with `api_base_url` + `store`) lives on `ctx.obj`, set by the root `@app.callback()` in `app.py`.
+- **Auth required**: Commands call `require_session(config.store)` → raises `AuthError` if no session.
+- **Payload validation**: `ApplicationCreate`/`ApplicationUpdate` Pydantic models validate inputs before API calls in `new_application` and `edit_application`.
+- **ApplicationArgs**: Thin dataclass passed to `build_application_payload()` — decouples Typer command signatures from payload construction logic.
+- **Schemas are vendored**: `schemas/enums.py` and `schemas/application.py` are standalone copies (no backend import). Keep in sync with `backend/app/core/enums.py` and `backend/app/application/dto/application.py` when the backend changes.
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `applika login` | GitHub OAuth login (opens browser) |
+| `applika logout` | Log out and clear session |
+| `applika whoami` | Show the currently authenticated user |
+| `applika applications list` | List applications (filterable) |
+| `applika applications new` | Create a new application |
+| `applika applications edit <id>` | Edit an existing application |
+| `applika skill install` | Install the AI skill (symlink/copy) for Claude, Gemini, or Codex |
+
+## Environment Variables
+
+- `APPLIKA_API_BASE_URL`: Override the default API URL (`https://applika.dev/api`)

applika_cli-0.1.0/Makefile

@@ -0,0 +1,29 @@
+install:
+	uv tool install --force .
+
+install-dev:
+	uv sync
+
+install-linux:
+	$(MAKE) install
+
+install-macos:
+	$(MAKE) install
+
+install-windows:
+	$(MAKE) install
+
+test:
+	uv run --no-sync pytest tests -q
+
+lint:
+	uv run --no-sync ruff check . --fix
+
+format:
+	uv run --no-sync ruff format .
+
+help:
+	uv run --no-sync applika --help
+
+uninstall:
+	uv tool uninstall applika-cli

applika_cli-0.1.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: applika-cli
+Version: 0.1.0
+Summary: Job application tracker CLI for Applika.dev
+Project-URL: Homepage, https://applika.dev
+Project-URL: Repository, https://github.com/ApplikaDev/applika
+Author-email: Luis Eduardo Soares <luisedu.soares@outlook.com.br>, David Alecrim <dsalecrim@outlook.com>
+License: MIT
+Keywords: applika,cli,job-tracker
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# applika-cli
+
+Command-line interface for [Applika.dev](https://applika.dev) — a structured job application tracker designed for active job seekers who want full control over their data without relying on a browser.
+
+Track every application you send, filter and review your pipeline from the terminal, and keep your AI coding assistant (Claude Code, Gemini, Codex) aware of the CLI through a bundled skill file.
+
+## Requirements
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+## Installation
+
+```bash
+uv tool install applika-cli
+```
+
+This installs the `applika` binary globally via uv's tool environment. Verify:
+
+```bash
+applika --help
+```
+
+To install from a local source checkout (useful during development):
+
+```bash
+uv tool install --force .
+```
+
+---
+
+## Authentication
+
+The CLI authenticates via GitHub OAuth. On `applika login`, your browser opens to GitHub's authorization page. Once you authorize, the callback is captured locally on a loopback port and the session (access + refresh tokens) is saved to `~/.config/applika/session.json`. The session refreshes automatically on expiry — you only need to log in once per device.
+
+```bash
+# Open browser and complete GitHub OAuth
+applika login
+
+# Verify the active session without making any other API call
+applika whoami
+# → Logged in as: username=luissoares  name=Luis Soares  email=luis@example.com
+
+# Revoke the session server-side and clear local storage
+applika logout
+```
+
+> `applika whoami` is the recommended pre-flight check. Run it before any other command, especially in scripts or AI-assisted workflows, to confirm a valid session exists before hitting the API.
+
+---
+
+## Commands
+
+### `applika applications list`
+
+Lists all job applications in the current cycle, sorted by date descending. Supports rich filtering and both human-readable table output and machine-readable JSON.
+
+```bash
+# Default: all applications as a table
+applika applications list
+
+# Narrow down by any combination of filters
+applika applications list \
+  --search "stripe" \
+  --mode active \
+  --status active \
+  --platform LinkedIn \
+  --from 2026-01-01 \
+  --to 2026-06-30
+
+# JSON output — useful for piping into jq or scripts
+applika applications list --output-format json
+
+# Scope to a specific job-search cycle by UUID
+applika applications list --cycle-id <uuid>
+```
+
+**Filter reference:**
+
+| Flag | Values | Default | Description |
+|---|---|---|---|
+| `--search TEXT` | any string | — | Case-insensitive substring match on company name or role title |
+| `--mode` | `active` · `passive` · `all` | `all` | `active` = you applied; `passive` = recruiter reached out |
+| `--status` | `active` · `finalized` · `all` | `all` | `finalized` applications have a recorded outcome |
+| `--platform TEXT` | e.g. `LinkedIn` | — | Exact match on platform name |
+| `--from YYYY-MM-DD` | date | — | Include applications from this date (inclusive) |
+| `--to YYYY-MM-DD` | date | — | Include applications up to this date (inclusive) |
+| `--output-format` | `table` · `json` | `table` | `json` returns the raw API response as a formatted array |
+| `--cycle-id TEXT` | UUID | — | Filter to a specific job-search cycle |
+
+---
+
+### `applika applications new`
+
+Records a new job application. The CLI validates the payload locally with Pydantic before calling the API, so you get clear field-level error messages without a round-trip.
+
+```bash
+# Minimal — required fields only
+applika applications new \
+  --company "Stripe" \
+  --role "Backend Engineer" \
+  --platform "LinkedIn" \
+  --mode active \
+  --date 2026-05-10
+
+# With salary info (currency and period are always required together with any salary field)
+applika applications new \
+  --company "Cloudflare" \
+  --role "Systems Engineer" \
+  --platform "Email" \
+  --mode passive \
+  --date 2026-05-10 \
+  --observation "Recruiter cold-messaged. Interesting stack." \
+  --country "Brazil" \
+  --work-mode remote \
+  --salary-min 18000 \
+  --salary-max 24000 \
+  --currency BRL \
+  --salary-period monthly
+```
+
+**Required flags:**
+
+| Flag | Description |
+|---|---|
+| `--company TEXT` | Company name. Matched against known companies; a new record is created if not found. |
+| `--role TEXT` | Job title or role description |
+| `--platform TEXT` | Platform where you found or were contacted about the role (e.g. `LinkedIn`, `Indeed`, `Email`) |
+| `--mode` | `active` — you applied proactively · `passive` — inbound from a recruiter |
+| `--date YYYY-MM-DD` | Date the application was submitted or the first contact occurred |
+
+**Optional flags:**
+
+| Flag | Description |
+|---|---|
+| `--company-url URL` | Company website |
+| `--job-url URL` | Direct link to the job posting |
+| `--observation TEXT` | Free-form notes about the role, process, or company |
+| `--country TEXT` | Country where the role is based |
+| `--work-mode` | `remote` · `hybrid` · `on_site` |
+| `--experience-level` | `intern` · `junior` · `mid_level` · `senior` · `staff` · `lead` · `principal` · `specialist` |
+| `--expected-salary FLOAT` | The salary you expect or asked for |
+| `--salary-min FLOAT` | Lower bound of a posted salary range |
+| `--salary-max FLOAT` | Upper bound of a posted salary range |
+| `--currency` | `USD` · `BRL` · `EUR` · `GBP` · `CAD` · `AUD` · `JPY` · `CHF` · `INR` |
+| `--salary-period` | `hourly` · `monthly` · `annual` |
+
+> **Salary rule:** if any salary amount is provided (`--expected-salary`, `--salary-min`, or `--salary-max`), both `--currency` and `--salary-period` become required. The CLI enforces this before making any API call.
+
+---
+
+### `applika applications edit <id>`
+
+Updates an existing application. Only the flags you pass are changed — everything else keeps its current value. This makes partial updates safe: you can update just the role name or add salary info without touching anything else.
+
+```bash
+# Update the role title
+applika applications edit 42 --role "Staff Engineer"
+
+# Add salary info that wasn't captured at application time
+applika applications edit 42 \
+  --expected-salary 180000 \
+  --currency USD \
+  --salary-period annual
+
+# Clear fields you no longer want to track
+applika applications edit 42 \
+  --clear-job-url \
+  --clear-observation \
+  --clear-country \
+  --clear-salary
+```
+
+Find the application `id` with:
+
+```bash
+applika applications list --search "company name" --output-format json
+```
+
+**Clear flags** — set a field back to null without affecting others:
+
+| Flag | Clears |
+|---|---|
+| `--clear-job-url` | Job posting URL |
+| `--clear-observation` | Notes |
+| `--clear-country` | Country |
+| `--clear-salary` | All salary fields (`expected_salary`, `salary_min`, `salary_max`, `currency`, `salary_period`) |
+
+> Finalized applications (those with a recorded outcome) are read-only and cannot be edited. The CLI checks this before sending the request.
+
+---
+
+### `applika skill`
+
+Installs the bundled AI skill into your assistant's skills directory. The skill teaches Claude Code, Gemini, or Codex how to use this CLI — what commands exist, how authentication works, required vs optional flags, and common workflows.
+
+The skill file is shipped inside the installed package (`applika/skills/applika-cli/SKILL.md`) so it stays in sync with the CLI version you have installed. By default the command creates a symlink so updates are reflected automatically; it falls back to a file copy if symlink creation fails (e.g. Windows without Developer Mode enabled).
+
+```bash
+# Interactive — choose which tool(s) to install for
+applika skill
+# →  1. Claude   (~/.claude/skills/applika-cli)
+# →  2. Gemini   (~/.gemini/skills/applika-cli)
+# →  3. Codex    (~/.codex/skills/applika-cli)
+# →  4. All of the above
+
+# Install to the current project's .claude/skills/ (file copy, no prompt)
+# Useful when you want the skill scoped to a single repo
+applika skill --local
+
+# Install to any arbitrary directory (file copy, no prompt)
+applika skill --dir /path/to/skills
+
+# Preview what would be installed without touching the filesystem
+applika skill --dry-run
+
+# Overwrite an existing installation
+applika skill --force
+```
+
+Once installed, the AI assistant automatically loads the skill context in every session and knows how to:
+- check authentication with `applika whoami` before running commands
+- construct valid `new` and `edit` payloads
+- apply the correct filters on `list`
+- recover from auth errors by prompting for `applika login`
+
+---
+
+## Global options
+
+These flags apply to every command and are passed before the subcommand name:
+
+```bash
+applika --api-base-url https://staging.applika.dev/api applications list
+```
+
+| Flag | Default | Env variable |
+|---|---|---|
+| `--api-base-url TEXT` | `https://applika.dev/api` | `APPLIKA_API_BASE_URL` |
+
+---
+
+## Package structure
+
+```
+cli/
+├── pyproject.toml               # Build config, dependencies, entry point
+├── Makefile                     # Shortcuts: test, lint, format
+├── README.md
+├── CLAUDE.md                    # Guidance for AI assistants working in this repo
+└── src/
+    └── applika/                 # Importable package (entry: applika.main:main)
+        ├── main.py              # Entry point — calls app()
+        ├── app.py               # Root Typer app, --api-base-url callback, AppConfig wiring
+        ├── config.py            # AppConfig dataclass + resolve_api_base_url()
+        │
+        ├── skills/
+        │   └── applika-cli/
+        │       └── SKILL.md     # Bundled AI skill — installed via `applika skill`
+        │
+        ├── schemas/             # Vendored Pydantic models (no backend import)
+        │   ├── enums.py         # StrEnum types: Currency, SalaryPeriod, WorkMode, etc.
+        │   └── application.py   # ApplicationCreate, ApplicationUpdate with validators
+        │
+        ├── lib/                 # Infrastructure — no Typer dependency
+        │   ├── api.py           # ApiClient (httpx + cookie auth), ApiError, AuthError
+        │   ├── session.py       # SessionData, SessionStore (~/.config/applika/session.json)
+        │   └── loopback.py      # LoopbackLoginServer for OAuth browser callback
+        │
+        ├── utils/               # Pure helpers — no httpx, no Typer
+        │   ├── dates.py         # parse_date, ensure_date_string
+        │   └── output.py        # render_application_table, print_application_summary
+        │
+        └── commands/
+            ├── auth.py          # login, logout, whoami commands
+            ├── skill.py         # skill command — installs the AI skill
+            └── applications/
+                ├── __init__.py  # applications_app Typer sub-app, default-to-list callback
+                ├── commands.py  # list_applications, new_application, edit_application
+                ├── filter.py    # filter_applications, resolve_platform_id
+                └── payloads.py  # ApplicationArgs dataclass, build_application_payload()
+```
+
+**Layer rules:**
+- `lib/` — HTTP and session logic only. No Typer, no output formatting.
+- `utils/` — Pure functions. No side effects, no I/O beyond what the function signature implies.
+- `schemas/` — Vendored copies of backend DTOs. Keep in sync manually with `backend/app/application/dto/application.py` and `backend/app/core/enums.py` when the backend changes.
+- `commands/` — Typer command functions only. Delegates to `lib/` and `utils/`.
+
+---
+
+## Development
+
+```bash
+# Install project + dev dependencies into a local virtualenv
+uv sync
+
+# Run the test suite
+make test
+
+# Auto-fix lint issues
+make lint
+
+# Apply code formatter
+make format
+
+# Build a wheel for distribution
+uv build
+
+# Install the locally built CLI globally for manual testing
+uv tool install --force .
+```
+
+Tests live in `tests/` and use `typer.testing.CliRunner` with fake `ApiClient` and `SessionStore` implementations defined in `tests/conftest.py`. No real network calls are made.
+
+---
+
+## License
+
+MIT