stage-cli 1.0.0__tar.gz

stage_cli-1.0.0/.gitattributes

@@ -0,0 +1,51 @@
+* text=auto
+
+*.py      text diff=python
+*.pyi     text diff=python
+*.sql     text
+*.yaml    text
+*.yml     text
+*.json    text
+*.toml    text
+*.md      text diff=markdown
+*.cfg     text
+*.ini     text
+*.txt     text
+*.tcss    text
+*.rb      text
+*.svg     text
+.python-version text
+.gitignore      text
+.gitattributes  text
+
+*.sh      text eol=lf
+*.bash    text eol=lf
+*.bat     text eol=crlf
+*.cmd     text eol=crlf
+
+*.db      binary
+*.db-wal  binary
+*.db-shm  binary
+*.sqlite  binary
+*.sqlite3 binary
+*.ttf     binary
+*.otf     binary
+*.woff    binary
+*.woff2   binary
+*.png     binary
+*.jpg     binary
+*.jpeg    binary
+*.gif     binary
+*.ico     binary
+*.pdf     binary
+*.zip     binary
+*.gz      binary
+*.whl     binary
+
+uv.lock text linguist-generated=true
+
+tests/fixtures/**  linguist-vendored=true
+tests/golden/**    linguist-generated=true
+
+src/stage/data/companies/**  text
+src/stage/data/lexicon/**    text

stage_cli-1.0.0/.gitignore

@@ -0,0 +1,92 @@
+docs/
+
+.venv/
+venv/
+env/
+ENV/
+.python-version.local
+
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+pip-wheel-metadata/
+
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.tox/
+.nox/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.benchmarks/
+
+*.db
+*.db-wal
+*.db-shm
+*.db.bak-*
+*.sqlite
+*.sqlite3
+
+.*.lock
+
+tests/captured/
+captured/
+*.log
+*.log.[0-9]
+*.jsonl
+logs/
+
+stage-export-*.csv
+stage-export-*.json
+stage-export-*.md
+stage-export-*.pdf
+stage-*.csv
+stage-*.pdf
+last-listing.json
+
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+secrets.yaml
+secrets.yml
+
+node_modules/
+.direnv/
+*.tmp
+
+.idea/
+.vscode/*
+!.vscode/extensions.json
+*.swp
+*.swo
+*~
+*.bak
+*.orig
+*.rej
+
+.DS_Store
+.AppleDouble
+.LSOverride
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+Desktop.ini
+desktop.ini
+$RECYCLE.BIN/
+*.lnk
+
+# Local-only release runbook
+packaging/RELEASING.md

stage_cli-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

stage_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-01
+
+First release. Stage collects CS internship postings from company job boards
+and community feeds, keeps the ones a CS undergraduate can apply to, and stores
+them in a SQLite database on your own machine.
+
+### What it does
+
+- **Reads 1,487 employers** across 15 ATS platforms — Greenhouse, Lever, Ashby,
+  Workday, SmartRecruiters, Workable and more — through 13 adapters, plus 11
+  community feeds.
+- **Filters hard.** It has kept 4,165 postings and rejected 134,368. Senior
+  roles, graduate-only research posts and work outside Canada and the United
+  States are all rejected. A posting whose location cannot be read is kept,
+  since a board that publishes no place is missing data rather than advertising
+  a foreign one. Every rejection records the rule that caught it, so
+  `stage quarantine` shows what was skipped and why.
+- **Classifies each posting** by role, internship scope, degree eligibility,
+  location and language, in English and French. Filter with `--role`,
+  `--location`, `--term`, `--lang`, `--source` and `--company`, and narrow by
+  date with `--last`.
+- **Browses from the terminal.** `stage list`, `stage search`, and a full-screen
+  `stage tui`. Rows are numbered, so `stage show 3` and `stage open 3 5 9` act
+  on what you just saw. The TUI keeps its filters in one panel, marks rows with
+  `space` to open them together, and switches theme with `ctrl+t`.
+- **Exports** to CSV, JSON, Markdown or PDF.
+- **Runs on a schedule** through launchd, systemd or Task Scheduler, and can
+  post new postings to a Discord channel through a webhook.
+- **Stays polite.** Requests are rate limited per host, cached with validators,
+  and backed off when a board pushes back. A cooldown longer than the retry
+  ceiling stops the run for that host rather than hammering it.
+- **Stays local.** No account, no server, no telemetry. The only network traffic
+  is Stage reading public job boards.
+
+### Requirements
+
+Python 3.12, 3.13 or 3.14 on macOS, Linux or Windows.
+
+[1.0.0]: https://github.com/NicholasXydis/Stage/releases/tag/v1.0.0

stage_cli-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas Xydis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stage_cli-1.0.0/PKG-INFO

@@ -0,0 +1,379 @@
+Metadata-Version: 2.5
+Name: stage-cli
+Version: 1.0.0
+Summary: Aggregates CS internship postings (Canada/US, EN + FR) into a local SQLite database
+Project-URL: Homepage, https://github.com/NicholasXydis/Stage
+Project-URL: Repository, https://github.com/NicholasXydis/Stage
+Project-URL: Issues, https://github.com/NicholasXydis/Stage/issues
+Project-URL: Changelog, https://github.com/NicholasXydis/Stage/blob/main/CHANGELOG.md
+Author-email: Nicholas Xydis <NicholasXydis@outlook.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,co-op,internship,python,stage,student,tui
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: beautifulsoup4>=4.15.0
+Requires-Dist: fpdf2>=2.8.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: platformdirs>=4.3.6
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.4
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: textual>=8.2.8
+Requires-Dist: typer<0.28,>=0.27.1
+Description-Content-Type: text/markdown
+
+<div align="center">
+<table><tr><td>
+<pre>
+  ____  _
+ / ___|| |_   __ _   __ _   ___
+ &#92;___ &#92;| __| / _&#96; | / _&#96; | / _ &#92;
+  ___) | |_ | (_| || (_| ||  __/
+ |____/ &#92;__| &#92;__,_| &#92;__, | &#92;___|
+                    |___/
+</pre>
+</td></tr></table>
+
+### One command. Thousands of internships.
+
+**Every CS internship you can actually apply to, in one place.**
+
+Free and open source. No account, no server, no telemetry.
+
+<br>
+
+![python](https://img.shields.io/static/v1?label=python&message=3.12%20%7C%203.13%20%7C%203.14&color=4a9eff&logo=python&logoColor=white)
+
+![tests](https://img.shields.io/static/v1?label=tests&message=2%2C375&color=44bb00) ![coverage](https://img.shields.io/static/v1?label=coverage&message=89%25&color=44bb00) [![ci](https://img.shields.io/github/actions/workflow/status/NicholasXydis/Stage/ci.yml?branch=main&label=ci&logo=githubactions&logoColor=white)](https://github.com/NicholasXydis/Stage/actions/workflows/ci.yml)
+
+<br>
+
+<p align="center"><sub><b>Made with</b></sub></p>
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/python/python-original.svg" alt="Python" width="46" height="46">
+  &nbsp;&nbsp;&nbsp;
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/sqlite/sqlite-original.svg" alt="SQLite" width="46" height="46">
+  &nbsp;&nbsp;&nbsp;
+  <img src="https://avatars.githubusercontent.com/u/93378883?s=200" alt="Textual" width="46" height="46">
+</p>
+
+<p align="center"><sub><b>Works on</b></sub></p>
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/windows8/windows8-original.svg" alt="Windows" width="46" height="46">
+  &nbsp;&nbsp;&nbsp;
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/linux/linux-original.svg" alt="Linux" width="46" height="46">
+  &nbsp;&nbsp;&nbsp;
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/apple/apple-original.svg" alt="macOS" width="46" height="46">
+</p>
+
+</div>
+
+## Why
+Internships disappear fast. By the time you find the right posting, hundreds of students may already be ahead of you. Most job boards make it worse by burying relevant roles under senior positions, research jobs, and listings nowhere near you.
+
+Stage scans 1,450+ employer career boards and finds internships CS undergrads in Canada and the U.S. can actually apply to. Every rejected posting is logged with the exact reason it was filtered out.
+
+It has kept **4,165** postings out of **138,533** screened so far.
+
+## A look at it
+
+<div align="center">
+  <img src="assets/tui.png" alt="The Stage TUI listing internship postings, with columns for age, company, title and location, a search bar, and the full description of the highlighted posting below" width="100%">
+  <br><sub><b>stage tui</b> — browse everything, filter with <b>f</b>, open with <b>o</b></sub>
+</div>
+
+<br>
+
+<div align="center">
+  <img src="assets/cli.png" alt="The stage command line help, showing commands grouped into Everyday, Keeping current, Registry and maintenance, and Health" width="100%">
+  <br><sub><b>stage --help</b> — commands grouped by what you are doing</sub>
+</div>
+
+## Install
+
+```bash
+uv tool install stage-cli
+```
+
+<details>
+<summary><b>Don't have uv?</b> Install it first, then reopen your terminal.</summary>
+
+<br>
+
+If you already have Python, this works everywhere:
+
+```bash
+pip install uv
+```
+
+Or use your usual package manager — `brew install uv` on macOS, `winget install
+astral-sh.uv` on Windows. More options at
+[docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).
+
+</details>
+
+<details>
+<summary><b>Other ways to install</b></summary>
+
+<br>
+
+```bash
+pipx install stage-cli                  # isolates the tool, like uv
+pip install stage-cli                   # installs into the active environment
+```
+
+`uv tool install` and `pipx` both keep Stage away from your system Python, which
+is what you want for a command line tool.
+
+</details>
+
+Needs Python 3.12, 3.13, or 3.14. Nothing else to set up — no database to
+configure, no API key, no config file.
+
+### First run
+
+```bash
+stage sync                    # fetch every board once (grab a coffee)
+stage tui                     # browse what came back
+```
+
+The first sync visits every board and takes a few minutes. Later ones are much
+quicker, since Stage remembers what it already has and only asks each board for
+what changed.
+
+```bash
+stage --install-completion    # tab-complete commands and filters
+```
+
+Completion needs a fresh terminal. After that, `stage <TAB>` lists commands and
+`stage list --<TAB>` lists filters.
+
+## The basics
+
+```bash
+stage sync                            # fetch the latest postings
+stage list                            # what is new, newest first
+stage search "machine learning"       # search titles, employers, descriptions
+stage tui                             # browse it all in a full screen
+```
+
+Rows are numbered, so you can act on what you just saw:
+
+```bash
+stage list --role swe --location montreal
+stage show 3                          # read the third row in full
+stage open 3 5 9                      # open those three in your browser
+```
+
+Filters work the same on `list`, `search`, and `export`:
+
+| Filter | What it takes |
+| --- | --- |
+| `--role` | swe, security, data, ml-ai, quant, infra, embedded, general-cs |
+| `--location` | montreal, canada, usa, unknown |
+| `--term` | summer-2027, fall-2026, winter-2027, and so on |
+| `--lang` | en, fr, bilingual |
+| `--source` | greenhouse, lever, ashby, workday, and more |
+| `--company` | one exact employer |
+| `--all` | every match, not just the first page |
+| `--last N` | look back N days instead of the default 14; `--last 0` removes the limit. On `search`, which already covers every row, it narrows instead |
+
+Mistype one and Stage tells you what it accepts, rather than showing you an
+empty list.
+
+## The full-screen browser
+
+```bash
+stage tui
+```
+
+Press `/` to search and `f` for filters — arrows move, enter picks, escape
+closes. Role, location, language, how far back to look, new-since-last-sync and
+the employer you are sitting on all live in that one panel.
+`space` marks rows and `o` opens every one you marked. `w` expands the full
+description, `e` exports what you are looking at, and `ctrl+t` changes the theme.
+Press `?` for the full key list.
+
+Same database as the CLI. The panel covers role, location, language, the date
+window and new-since-last-sync; `--term` and `--source` stay CLI-only. Row
+numbers are a CLI idea — in the TUI you move a cursor instead.
+
+## Keeping it fresh
+
+```bash
+stage schedule enable     # sync quietly in the background
+stage schedule status     # check on it
+```
+
+Opt-in, and it uses whatever scheduler your system already has: launchd,
+systemd, or Task Scheduler. Nothing runs until you turn it on.
+
+Want to hear about new postings without checking? Point Stage at a Discord
+channel you manage:
+
+```bash
+stage schedule notify https://discord.com/api/webhooks/...
+stage schedule test-notify        # make sure it works
+```
+
+Create a Discord webhook in the channel you want Stage to post to. It is just a URL Stage uses to send new internships.
+
+Notifications only follow scheduled syncs, not stage sync. Your machine also needs to be awake. If it misses runs, Stage catches up once when it can run again.
+
+<details>
+<summary><b>Want notifications around the clock?</b></summary>
+
+<br>
+
+Put Stage on something that stays on — a VPS, a Raspberry Pi, an old laptop:
+
+```bash
+uv tool install stage-cli
+stage sync                         # first sync, a few minutes
+stage schedule notify <webhook>
+stage schedule enable              # systemd, launchd, or Task Scheduler
+```
+
+That machine keeps its own database and posts to Discord on its own schedule.
+Yours stays free for browsing.
+
+</details>
+
+## Architecture
+
+```text
+Stage/
+├─ src/stage/
+│  ├─ cli/                  Typer commands, Rich rendering, scheduling, notify
+│  ├─ tui/                  Textual screens over the same services; safe.py escapes output
+│  ├─ domain/               the types every layer speaks: jobs, filters, enums, events
+│  ├─ sources/              13 ATS adapters + 11 curated feeds
+│  ├─ services/             sync, discover, query, export, quarantine, health
+│  ├─ classify/             role, internship scope, degree eligibility, location
+│  ├─ normalize/            location, term, language, apply-url canonicalisation
+│  ├─ dedup/                cross-source duplicate resolution
+│  ├─ http/                 rate posture, circuit breaker, validator cache
+│  ├─ storage/              SQLite repository, migrations, FTS
+│  └─ data/                 packaged registry (a directory) and lexicons
+├─ tests/                   2,375 tests, 89% branch coverage
+└─ .github/workflows/       CI, CodeQL, scheduled canary, release
+```
+
+<div align="center">
+<pre>
+┌──────────────────────────────────────────────────────────────┐
+│                    1,450+ employer boards                    │
+│    Greenhouse · Lever · Ashby · Workday · SmartRecruiters    │
+│                + 11 curated internship feeds                 │
+└───────────────────────────┬──────────────────────────────────┘
+                            │  rate-limited, cached, backed off
+                            ▼
+┌──────────────────────────────────────────────────────────────┐
+│                          normalize                           │
+│       location · term · language · canonical apply URL       │
+└───────────────────────────┬──────────────────────────────────┘
+                            ▼
+┌──────────────────────────────────────────────────────────────┐
+│                            screen                            │
+│    internship? · CS role? · degree scope? · Canada or US?    │
+│        every rejection keeps the rule that caught it         │
+└──────────────┬───────────────────────────────┬───────────────┘
+               │ kept                          │ rejected
+               ▼                               ▼
+        ┌─────────────┐                 ┌─────────────┐
+        │    jobs     │                 │ quarantine  │
+        │    4,165    │                 │   134,368   │
+        └──────┬──────┘                 └─────────────┘
+               │  dedup collapses the same posting across sources
+               ▼
+     ┌───────────────────────┐
+     │     SQLite + FTS5     │
+     │    on your machine    │
+     └──────┬────────┬───────┘
+            ▼        ▼
+      stage list   stage tui
+      search       full-screen browser
+      export       Discord on a schedule
+</pre>
+</div>
+
+## CI
+
+| Workflow | File | Purpose |
+| --- | --- | --- |
+| CI | `.github/workflows/ci.yml` | Ruff, format, mypy strict, 2,375 tests, coverage floor, badge drift |
+| Supported Pythons | `.github/workflows/ci.yml` | The full suite again on 3.13 and 3.14 |
+| Wheel | `.github/workflows/ci.yml` | Builds and smoke-tests the wheel on Ubuntu, Windows and macOS |
+| CodeQL | `.github/workflows/codeql.yml` | Static analysis for Python and the workflows themselves |
+| Canary | `.github/workflows/canary.yml` | Probes one live board per platform and opens an issue on drift |
+| Release | `.github/workflows/release.yml` | Re-runs every gate plus pip-audit, then publishes from a `v*` tag |
+
+<div align="center">
+  <img src="assets/ci-flow.svg" alt="Quality checks on Python 3.12, then the full suite on 3.13 and 3.14, a wheel smoke test on three operating systems, and CodeQL. All gates must pass for CI to pass" width="100%">
+</div>
+
+Any failing gate blocks the merge. The canary runs weekly and opens an issue
+when a board changes shape, so parser drift surfaces before a sync does.
+
+Every run also builds the wheel and installs it into a clean environment outside
+the checkout on Ubuntu, Windows and macOS, checks the registry, lexicons and font
+resolve from inside the installed package, then runs `help`, `list`, `search`,
+`doctor`, `coverage`, `stats`, a dry-run sync and all four export formats against
+it. What ships is what gets tested.
+
+## Good to know
+
+- Everything sits in one SQLite file you own. Open it with any SQLite client,
+  back it up, or delete it.
+- The only network traffic is Stage reading public job boards. No account, no
+  telemetry.
+- Requests are rate limited per host, cached, and retried with backoff, so it
+  does not hammer anyone's site.
+- Four in five postings arrive with no description at all. Stage marks those
+  fields `unknown` instead of guessing.
+- Missing something you expected? `stage quarantine` shows which rule caught it.
+
+## Learn more
+
+`stage help` walks through the common workflows with real examples.
+`stage help COMMAND` explains one command; `stage --help` lists them all.
+
+[CHANGELOG.md](CHANGELOG.md) lists what changed in each release.
+
+## Found a bug?
+
+Open an issue, especially if a job board stopped working, since those break
+without warning and I cannot watch all of them myself. I read everything.
+
+## Security
+
+Stage reads public job boards and writes to a local file. It never asks for
+credentials. Found a security issue? Open a
+[security advisory](https://github.com/NicholasXydis/Stage/security/advisories/new)
+instead of a public issue.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+<div align="center">
+<br>
+<sub>Built for students who would rather be studying than refreshing career pages.</sub>
+</div>