boardwatch 0.1.0__tar.gz

boardwatch-0.1.0/.dockerignore

@@ -0,0 +1,21 @@
+.git
+.github
+.venv
+.agent
+.superpowers
+.reasonix-runs
+reasonix.toml
+tools
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.coverage
+coverage.xml
+dist
+tests
+docs
+*.db
+_alembic_dev.db
+__pycache__
+*.pyc
+.DS_Store

boardwatch-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# Pin line endings repo-wide so the content hashes in the generalization inventory (R7)
+# are stable on every platform. Without this, Git for Windows checks out CRLF by default
+# and every sha256 pin mismatches at once. text=auto still leaves detected binaries alone.
+* text=auto eol=lf

boardwatch-0.1.0/.github/ISSUE_TEMPLATE/board_or_provider.yml

@@ -0,0 +1,33 @@
+name: Board / provider request
+description: Ask for a company in the registry, or support for a new ATS
+labels: ["registry"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        You can already watch **any** Greenhouse / Lever / Ashby board today with
+        `boardwatch companies add <url>` — no issue needed. Use this for adding a
+        company to the **bundled registry** or requesting a **new ATS provider**.
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Request type
+      options:
+        - Add a company to the bundled registry
+        - Support a new ATS provider
+    validations:
+      required: true
+  - type: input
+    id: board-url
+    attributes:
+      label: Public board URL (if adding a company)
+      placeholder: https://boards.greenhouse.io/acme
+  - type: input
+    id: provider
+    attributes:
+      label: ATS provider (if requesting new support)
+      placeholder: e.g. Workday, SmartRecruiters
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else?

boardwatch-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,52 @@
+name: Bug report
+description: Something isn't working as documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for filing a bug. Please search existing issues first.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. boardwatch init ...
+        2. boardwatch scan ...
+        3. boardwatch top ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: boardwatch version
+      description: Output of `boardwatch version`.
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: e.g. 3.12.3
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant output / traceback
+      render: shell

boardwatch-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/mit112/boardwatch/security/advisories/new
+    about: Report security issues privately via GitHub Security Advisories, not public issues.

boardwatch-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,19 @@
+name: Feature request
+description: Suggest an improvement or new capability
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe the job-search pain point, not the implementation.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you've considered

boardwatch-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What & why
+
+<!-- What does this change, and what problem does it solve? Link the issue, e.g. Closes #NN -->
+
+## Checklist
+
+- [ ] `make check` passes locally (generalization + ruff + mypy --strict + pytest)
+- [ ] Tests added/updated for the change
+- [ ] README/docs updated if behavior or config changed
+- [ ] One logical change per PR
+
+<!-- Registry additions: confirm the board is publicly reachable (HTTP 200, valid JSON)
+     and include the rationale. See src/boardwatch/registry/README.md -->

boardwatch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  test:
+    name: test (${{ matrix.python }}, ${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        # Full 3-OS matrix only on push to main (the pre-permanent safety net).
+        # PRs run ubuntu-only to conserve Free-tier minutes (macOS bills 10x,
+        # Windows 2x). OS-specific risk is re-verified at the main merge.
+        os: ${{ github.event_name == 'push' && fromJSON('["ubuntu-latest", "macos-latest", "windows-latest"]') || fromJSON('["ubuntu-latest"]') }}
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run mypy --strict src tools
+      - run: uv run pytest
+
+  gitleaks:
+    name: gitleaks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  perf:
+    name: perf
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --frozen
+      - run: uv run pytest tests/perf -m perf --no-cov -s
+
+  generalization:
+    name: generalization
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --frozen
+      - run: uv run python -m tools.generalization

boardwatch-0.1.0/.github/workflows/registry-health.yml

@@ -0,0 +1,16 @@
+name: registry-health
+on:
+  schedule:
+    - cron: "0 7 * * 1"   # Mondays 07:00 UTC
+  workflow_dispatch: {}
+jobs:
+  health:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install uv && uv sync
+      # exits non-zero iff DEAD/ERROR/UNREACHABLE → drift is visible; EMPTY passes (§3.2-valid)
+      - run: uv run python -m boardwatch.registry.health_report

boardwatch-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: release
+
+# Cut a release by pushing a tag: `git tag v0.1.0 && git push origin v0.1.0`.
+# One-time setup on PyPI: add a Trusted Publisher for this repo + the `release`
+# workflow + the `pypi` environment (https://docs.pypi.org/trusted-publishers/).
+# No API token is stored anywhere.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build + smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --frozen
+      # The strongest gate belongs on the most irreversible action. `make check` is the same
+      # generalization + ruff + mypy --strict + pytest gate main runs; `pytest -q` alone let a
+      # tag publish code that main CI would have rejected.
+      - run: make check
+      - run: uv build                    # sdist + wheel into dist/
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write                    # Trusted Publishing (OIDC) — tokenless
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: github release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      # Notes are intentionally NOT auto-generated: GitHub credits commit
+      # co-authors, and release notes must stay attribution-free. Write them
+      # by hand on the release, or via a curated CHANGELOG.
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: false
+          body: |
+            Install: `pipx install boardwatch` · `docker run ghcr.io/mit112/boardwatch:latest`
+            See the README for the quickstart.
+
+  docker:
+    name: build + push image (GHCR)
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

boardwatch-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+.coverage
+coverage.xml
+dist/
+_alembic_dev.db
+.agent/*
+.superpowers/*
+reasonix.toml
+.reasonix-runs/
+.DS_Store

boardwatch-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks

boardwatch-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# 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 adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-01
+
+First public release.
+
+### Added
+
+- **Job radar over official ATS APIs.** Watch company boards on Greenhouse, Lever, and
+  Ashby. No scraping, no credentials, no accounts.
+- **Change detection.** `digest` reports what is new, reopened, updated, or closed since
+  your last run, and `top --new` limits ranking to postings you have not seen.
+- **Deterministic eligibility engine.** Work authorization, experience, clearance, and
+  degree requirements are extracted with auditable rules, and every requirement it surfaces
+  cites the exact job description span it came from. No model is involved in the default path.
+- **Persisted eligibility audit trail.** `show` renders a per-posting verdict with its
+  supporting evidence, so a decision can be re-checked later rather than taken on trust.
+- **Ranking against your profile.** `top` scores open postings, with a live component
+  breakdown available in `show`.
+- **Application tracking.** `track` records your own funnel state per job.
+- **Data portability.** `export` writes every open or tracked posting with its verdict and
+  funnel state as JSONL or CSV. `top --json` emits machine-readable rankings.
+- **Opt-in LLM eligibility extraction.** Disabled by default. When enabled, the model acts
+  only as a span locator: it returns verbatim job description quotes, every one of which is
+  validated as a literal substring of the source before use. Fabricated citations are
+  dropped. LLM findings are advisory and can never produce an "ineligible" verdict.
+- **Local-first storage.** Its primary store is one SQLite database in your platform
+  data directory; the opt-in LLM tier also caches raw responses there as plain files on
+  disk. Overridable with `--data-dir`. No server, no cloud, no telemetry.
+- **`doctor`** for connectivity, per-board health and freshness, and database integrity.
+
+[0.1.0]: https://github.com/mit112/boardwatch/releases/tag/v0.1.0

boardwatch-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of Conduct
+
+This project follows the spirit of the
+[Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Be respectful and constructive. Harassment, personal attacks, and
+discriminatory language are not tolerated in any of this project's spaces
+(issues, PRs, discussions, commits). Report unacceptable behavior privately to
+the maintainer via GitHub; reports are handled confidentially. Maintainers may
+edit or remove comments, commits, issues, and PRs that violate this standard,
+and may ban repeat offenders.

boardwatch-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Dev setup: install [uv](https://docs.astral.sh/uv/), then `uv sync` and
+`uv run pre-commit install`. `make check` (generalization + ruff + mypy --strict + pytest) must
+be green before every PR; CI runs the same commands: pull requests run the test suite on ubuntu with
+Python 3.11-3.13, plus gitleaks and a dedicated generalization job; pushes to `main` additionally
+run that test matrix on macOS and Windows.
+
+## What must never enter this repo
+
+This project is a general-purpose tool. Some of it grew out of a private, single-user
+job-search setup, so there is a standing rule about what does not come along.
+
+Never commit:
+
+- **Personal career data.** Resume or CV text, work history, cover letters, EEO or
+  work-authorization answers.
+- **Personal targeting lists.** A private list of companies, recruiters or contacts.
+- **Personal preference defaults.** One person's job titles, locations, salary floor or
+  filters, shipped as the default for everybody.
+- **Personal identifiers.** Home-directory paths, email addresses, phone numbers,
+  profile URLs.
+
+Curated generic content is welcome. The tech taxonomy and the public starter registry are
+both good examples. The question that separates them:
+
+> Does this content describe **the world**, or **one user's situation and preferences**?
+
+A list of public company job boards describes the world. A list of the companies you
+personally want to work at describes you.
+
+These checks catch identifier shapes, new data files and changed defaults, so those cannot
+land unnoticed. They do not and cannot catch personal values written into Python source or
+prose; code review is the control there. For a legitimate block, add a reviewed entry to
+`tools/generalization/allowlists.py` for the shape and inventory rules, or a reviewed update
+to `tools/generalization/snapshots.py` for the pinned defaults. The collection-defaults rule
+has no opt-out by design, so the remedy there is to restructure the value. Weakening or
+removing a check is a security-sensitive change and will be reviewed as one.
+
+All changes land via PR — `main` is branch-protected. One issue per PR.
+
+The bundled registry catalog (company boards) has its own bar — see
+[`src/boardwatch/registry/README.md`](src/boardwatch/registry/README.md).

boardwatch-0.1.0/Dockerfile

@@ -0,0 +1,25 @@
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim
+
+# Dependencies come from uv.lock, never from a fresh resolve: two builds of the same tag
+# must yield the same dependency tree. `uv export` renders the locked graph as a
+# hash-pinned requirements file, and --require-hashes makes pip refuse anything that does
+# not match. The package itself is then installed with --no-deps so pip cannot re-resolve
+# behind the lock's back.
+COPY --from=ghcr.io/astral-sh/uv:0.10.5 /uv /usr/local/bin/uv
+COPY . /tmp/boardwatch
+RUN uv export --directory /tmp/boardwatch --frozen --no-dev --no-emit-project \
+        -o /tmp/requirements.txt \
+    && pip install --no-cache-dir --require-hashes -r /tmp/requirements.txt \
+    && pip install --no-cache-dir --no-deps /tmp/boardwatch \
+    && rm -rf /tmp/boardwatch /tmp/requirements.txt /usr/local/bin/uv
+
+# Run as a non-root user; persist the local SQLite DB under /data (mount a volume
+# here and pass `--data-dir /data`).
+RUN useradd --create-home --uid 10001 boardwatch \
+    && mkdir -p /data && chown boardwatch:boardwatch /data
+USER boardwatch
+WORKDIR /data
+VOLUME ["/data"]
+
+ENTRYPOINT ["boardwatch"]

boardwatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mit sheth
+
+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.

boardwatch-0.1.0/Makefile

@@ -0,0 +1,10 @@
+.PHONY: check lint type test generalization
+check: generalization lint type test
+lint:
+	uv run ruff check .
+type:
+	uv run mypy --strict src tools
+test:
+	uv run pytest
+generalization:
+	uv run python -m tools.generalization