boardwatch 0.1.0__py3-none-any.whl

boardwatch/cli/app.py

@@ -0,0 +1,56 @@
+"""boardwatch CLI entry point."""
+
+from importlib.metadata import version as package_version
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from boardwatch.cli.companies_cmd import companies_app
+from boardwatch.cli.config_cmd import config_app
+from boardwatch.cli.digest_cmd import digest as _digest
+from boardwatch.cli.doctor_cmd import doctor as _doctor
+from boardwatch.cli.eligibility_cmd import eligibility_app
+from boardwatch.cli.export_cmd import export as _export
+from boardwatch.cli.init_cmd import init as _init
+from boardwatch.cli.profile_cmd import profile_app
+from boardwatch.cli.scan_cmd import scan as _scan
+from boardwatch.cli.show_cmd import show as _show
+from boardwatch.cli.top_cmd import top as _top
+from boardwatch.cli.track_cmd import track_app
+
+app = typer.Typer(no_args_is_help=True, add_completion=False)
+console = Console()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    data_dir: Path | None = typer.Option(  # noqa: B008
+        None, "--data-dir", help="Override the data directory (default: platform data dir)."
+    ),
+) -> None:
+    """boardwatch — self-hosted job radar over official ATS APIs."""
+    ctx.obj = data_dir
+
+
+@app.command()
+def version() -> None:
+    """Print the boardwatch version and schema revision."""
+    from boardwatch.store.db import schema_revision
+
+    console.print(f"boardwatch {package_version('boardwatch')} · schema {schema_revision()}")
+
+
+app.add_typer(companies_app, name="companies")
+app.command("scan")(_scan)
+app.command("init")(_init)
+app.add_typer(profile_app, name="profile")
+app.command("top")(_top)
+app.command("show")(_show)
+app.add_typer(config_app, name="config")
+app.command("doctor")(_doctor)
+app.command("digest")(_digest)
+app.add_typer(eligibility_app, name="eligibility")
+app.add_typer(track_app, name="track")
+app.command("export")(_export)

boardwatch/cli/companies_cmd.py

@@ -0,0 +1,104 @@
+"""boardwatch companies — search / add / remove / list / import / export (§2.3).
+`export` is the registry-format contribution funnel; data-portability export
+(--format jsonl|csv) is P2 and intentionally absent."""
+
+from __future__ import annotations
+
+import typer
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+from boardwatch.cli.context import build_context
+from boardwatch.core.board_urls import UnknownBoardURL, parse_board_target
+from boardwatch.registry.loader import load_catalog
+from boardwatch.registry.validate import CatalogError, CompanyEntry
+from boardwatch.store.queries import list_watches, unwatch, upsert_watch
+
+companies_app = typer.Typer(no_args_is_help=True, help="Manage watched company boards.")
+console = Console()
+
+
+def _catalog_index() -> dict[tuple[str, str], CompanyEntry]:
+    return {(e.provider, e.slug): e for e in load_catalog()}
+
+
+@companies_app.command("add")
+def add(ctx: typer.Context, target: str) -> None:
+    """Watch a board by provider:slug or board URL."""
+    try:
+        provider, slug = parse_board_target(target)
+    except UnknownBoardURL as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1) from exc  # no DB write on the failed-validation path
+    entry = _catalog_index().get((provider, slug))
+    source = "registry" if entry else "user"
+    name = entry.name if entry else slug
+    app_ctx = build_context(ctx.obj)
+    with app_ctx.engine.begin() as conn:
+        upsert_watch(conn, provider=provider, slug=slug, name=name, source=source)
+    console.print(f"Watching {provider}:{slug} (source={source}).")
+
+
+@companies_app.command("remove")
+def remove(ctx: typer.Context, target: str) -> None:
+    provider, slug = parse_board_target(target)
+    app_ctx = build_context(ctx.obj)
+    with app_ctx.engine.begin() as conn:
+        changed = unwatch(conn, provider=provider, slug=slug)
+    console.print(f"Unwatched {provider}:{slug}." if changed else "No such watch.")
+
+
+@companies_app.command("search")
+def search(ctx: typer.Context, query: str) -> None:
+    """Case-insensitive substring search over the bundled catalog (offline)."""
+    q = query.casefold()
+    hits = [e for e in load_catalog() if q in e.name.casefold() or q in e.slug.casefold()]
+    table = Table("name", "provider", "slug", "starter")
+    for e in hits:
+        table.add_row(e.name, e.provider, e.slug, "★" if "starter" in e.tags else "")
+    console.print(table)
+
+
+@companies_app.command("list")
+def list_(ctx: typer.Context) -> None:
+    app_ctx = build_context(ctx.obj)
+    with app_ctx.engine.connect() as conn:
+        rows = list_watches(conn)
+    table = Table("provider", "slug", "source", "watched", "last_health", "last_ok_at")
+    for r in rows:
+        table.add_row(
+            r.provider, r.slug, r.source, "yes" if r.watched else "no",
+            r.last_health or "—", str(r.last_ok_at or "—"),
+        )
+    console.print(table)
+
+
+@companies_app.command("export")
+def export(ctx: typer.Context) -> None:
+    """Emit the user's watches as registry-format YAML (the §3.2 contribution funnel)."""
+    app_ctx = build_context(ctx.obj)
+    with app_ctx.engine.connect() as conn:
+        rows = list_watches(conn)
+    payload = {"companies": [
+        {"name": r.slug, "provider": r.provider, "slug": r.slug, "tags": []} for r in rows
+    ]}
+    console.print(yaml.safe_dump(payload, sort_keys=False))
+
+
+@companies_app.command("import")
+def import_(ctx: typer.Context, path: typer.FileText) -> None:
+    """Validate registry-format YAML, then watch each entry."""
+    try:
+        raw = yaml.safe_load(path.read()) or {}
+        entries = [CompanyEntry.model_validate(row) for row in (raw.get("companies") or [])]
+    except (CatalogError, ValueError) as exc:
+        console.print(f"[red]invalid import file: {exc}[/red]")
+        raise typer.Exit(code=1) from exc
+    app_ctx = build_context(ctx.obj)
+    with app_ctx.engine.begin() as conn:
+        for e in entries:
+            in_catalog = (e.provider, e.slug) in _catalog_index()
+            upsert_watch(conn, provider=e.provider, slug=e.slug, name=e.name,
+                         source="registry" if in_catalog else "user")
+    console.print(f"Imported {len(entries)} watches.")

boardwatch/cli/config_cmd.py

@@ -0,0 +1,138 @@
+"""boardwatch config show|set (§2.3, D17). Validates against the supported-key table;
+writes config.toml via tomli-w (stdlib has no writer), round-tripping the raw dict so a
+user's unknown-but-harmless keys survive a set."""
+
+from __future__ import annotations
+
+import tomllib
+from typing import Any
+
+import tomli_w
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+
+from boardwatch.cli.context import build_context
+from boardwatch.core.secrets import LLM_API_KEY_ENV, resolve_secret
+from boardwatch.core.settings import Settings, load_settings
+
+config_app = typer.Typer(no_args_is_help=True, help="Show or change settings.")
+console = Console()
+
+# key → (caster, "takes effect", units note). weights.* are nested under [weights].
+_SCALAR_KEYS = {
+    "per_host_delay_seconds": (float, "next scan", "seconds, floor 0.25"),
+    "retry_attempts": (int, "next scan", "total attempts 1–10 (1 = no retry)"),
+    "scan_workers": (int, "next scan", "1–8"),
+}
+_WEIGHT_KEYS = {"skill_coverage", "title_match", "recency", "location_fit"}
+
+_SECRET_LEAF_NAMES = frozenset({"api_key", "token", "secret", "password"})
+
+
+def _is_secret_key(name: str) -> bool:
+    return name in _SECRET_LEAF_NAMES or name.endswith("_api_key")
+
+
+def _find_secret_key(raw: dict[str, Any], prefix: str = "") -> str | None:
+    """Dotted path of the first reserved secret key at any depth in raw, or None.
+    Recurses through nested tables (dict) and arrays-of-tables (list). Returns a PATH
+    only, never a value (secrets contract, P0-3 D-P0-3-5)."""
+    for key, value in raw.items():
+        path = f"{prefix}{key}"
+        if _is_secret_key(key):
+            return path
+        found = _find_secret_in_value(value, path)
+        if found is not None:
+            return found
+    return None
+
+
+def _find_secret_in_value(value: Any, path: str) -> str | None:
+    """Walk a config value for a reserved secret key; returns a PATH or None, never a value."""
+    if isinstance(value, dict):
+        return _find_secret_key(value, f"{path}.")
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            found = _find_secret_in_value(item, f"{path}[{index}]")
+            if found is not None:
+                return found
+    return None
+
+
+@config_app.command("show")
+def show(ctx: typer.Context) -> None:
+    settings = load_settings(data_dir=ctx.obj)
+    defaults = Settings(data_dir=settings.data_dir, config_dir=settings.config_dir)
+    for key, (_caster, effect, units) in _SCALAR_KEYS.items():
+        cur, dflt = getattr(settings, key), getattr(defaults, key)
+        console.print(f"{key} = {cur} (default {dflt}; {units}; {effect})")
+    for key in sorted(_WEIGHT_KEYS):
+        cur, dflt = getattr(settings.weights, key), getattr(defaults.weights, key)
+        console.print(f"weights.{key} = {cur} (default {dflt}; [0,1]; next top)")
+    llm = settings.llm
+    console.print(
+        f"llm: reserved (opt-in; ships v1.1); "
+        f"enabled={llm.enabled}, provider={llm.provider}, model={llm.model}"
+    )
+    present = "set" if resolve_secret(LLM_API_KEY_ENV) is not None else "unset"
+    console.print(f"llm.api_key: {present} (via {LLM_API_KEY_ENV})")
+
+
+@config_app.command("set")
+def set_(ctx: typer.Context, key: str, value: str) -> None:
+    settings = load_settings(data_dir=ctx.obj)
+    config_file = settings.config_dir / "config.toml"
+    raw = tomllib.loads(config_file.read_text(encoding="utf-8")) if config_file.is_file() else {}
+
+    existing_secret = _find_secret_key(raw)
+    if existing_secret is not None:
+        console.print(
+            f"[red]refusing to write: config.toml must not contain secrets; found "
+            f"reserved key {existing_secret!r}. Remove it and put credentials in the "
+            f"environment ({LLM_API_KEY_ENV}).[/red]"
+        )
+        raise typer.Exit(code=1)
+    if _is_secret_key(key.rsplit(".", 1)[-1]):
+        console.print(
+            f"[red]secrets do not belong in config.toml; set {LLM_API_KEY_ENV} in the "
+            f"environment instead of {key!r}.[/red]"
+        )
+        raise typer.Exit(code=1)
+    if key == "llm" or key.startswith("llm."):
+        console.print(
+            f"[red]{key!r} is reserved for the v1.1 LLM tier and is not settable yet.[/red]"
+        )
+        raise typer.Exit(code=1)
+
+    if key in _SCALAR_KEYS:
+        caster, _e, _u = _SCALAR_KEYS[key]
+        old = getattr(settings, key)
+        try:
+            new = caster(value)
+            # construct Settings with the new value → the Field(ge/le) range check fires
+            Settings(data_dir=settings.data_dir, config_dir=settings.config_dir, **{key: new})
+        except (ValueError, ValidationError) as exc:
+            console.print(f"[red]invalid value for {key}: {exc}[/red]")
+            raise typer.Exit(code=1) from exc
+        raw[key] = new
+    elif key.startswith("weights.") and key.split(".", 1)[1] in _WEIGHT_KEYS:
+        from boardwatch.core.settings import RankWeights
+
+        leaf = key.split(".", 1)[1]
+        old = getattr(settings.weights, leaf)
+        try:
+            new = float(value)
+            RankWeights(**{**settings.weights.model_dump(), leaf: new})  # [0,1] range check
+        except (ValueError, ValidationError) as exc:
+            console.print(f"[red]invalid value for {key}: {exc}[/red]")
+            raise typer.Exit(code=1) from exc
+        raw.setdefault("weights", {})[leaf] = new
+    else:
+        console.print(f"[red]unknown key {key!r}[/red]")
+        raise typer.Exit(code=1)
+
+    config_file.parent.mkdir(parents=True, exist_ok=True)
+    config_file.write_bytes(tomli_w.dumps(raw).encode("utf-8"))  # round-trips unknown keys
+    console.print(f"{key}: {old} → {new}")
+    build_context(ctx.obj)  # ensure the data dir/schema exist (parity with other commands)

boardwatch/cli/context.py

@@ -0,0 +1,25 @@
+"""Per-invocation app context: settings + engine, built lazily by DB-touching commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlalchemy import Engine
+
+from boardwatch.core.settings import Settings, load_settings
+from boardwatch.store.db import ensure_schema, get_engine
+
+
+@dataclass
+class AppContext:
+    settings: Settings
+    engine: Engine
+
+
+def build_context(data_dir: Path | None, *, ensure: bool = True) -> AppContext:
+    settings = load_settings(data_dir=data_dir)
+    engine = get_engine(settings.data_dir, busy_timeout_ms=settings.busy_timeout_ms)
+    if ensure:
+        ensure_schema(engine)
+    return AppContext(settings=settings, engine=engine)

boardwatch/cli/digest_cmd.py

@@ -0,0 +1,76 @@
+"""digest: what changed since you last looked (D18).
+
+Reads the event window past the stored cursor, renders it, and advances the cursor.
+Issues BEGIN IMMEDIATE before the first cursor read so two concurrent digests cannot
+both read the same window (A1). --peek renders without advancing.
+
+A crash after terminal output can still re-render a window. Exactly-once terminal
+rendering is not achievable transactionally, and claiming it would be false.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from sqlalchemy import text
+
+from boardwatch.cli.context import build_context
+from boardwatch.reports.digest import DigestEntry, DigestSummary, summarize_events
+from boardwatch.store.app_state import get_digest_cursor, set_digest_cursor
+
+console = Console()
+
+# Explicit accessors rather than getattr: mypy --strict cannot type a getattr lookup, and
+# a typo in a section name would then only surface at runtime.
+_SECTIONS: tuple[tuple[str, Callable[[DigestSummary], tuple[DigestEntry, ...]]], ...] = (
+    ("New", lambda s: s.new),
+    ("Reopened", lambda s: s.reopened),
+    ("Updated", lambda s: s.revised),
+)
+
+
+def render(summary: DigestSummary) -> None:
+    for heading, accessor in _SECTIONS:
+        entries = accessor(summary)
+        if not entries:
+            continue
+        table = Table(title=heading, show_header=True, header_style="bold", title_justify="left")
+        table.add_column("#", style="dim")
+        table.add_column("Title")
+        table.add_column("Company")
+        for entry in entries:
+            table.add_row(str(entry.posting_id), entry.title, entry.company)
+        console.print(table)
+    if summary.closed_count:
+        console.print(f"{summary.closed_count} closed since your last digest.")
+
+
+def digest(
+    ctx: typer.Context,
+    peek: bool = typer.Option(
+        False, "--peek", help="Show the same digest without advancing the cursor."
+    ),
+) -> None:
+    """New, reopened, updated and closed postings since your last digest."""
+    app_ctx = build_context(ctx.obj)
+    with app_ctx.engine.connect() as conn:
+        # A1: BEGIN IMMEDIATE serializes before the first cursor read so two
+        # overlapping digests cannot read the same window.
+        conn.execute(text("BEGIN IMMEDIATE"))
+        try:
+            summary = summarize_events(conn, get_digest_cursor(conn))
+            if summary.is_empty:
+                console.print("nothing new since your last digest")
+                return
+            render(summary)
+            if not peek:
+                set_digest_cursor(conn, summary.max_event_id)
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+    if peek:
+        console.print("peeked, so the cursor did not move")

boardwatch/cli/doctor_cmd.py

@@ -0,0 +1,106 @@
+"""boardwatch doctor — connectivity, per-board health + freshness, DB integrity (§2.3).
+
+Runtime is healthy-path-only: ~15 boards ≈ seconds when healthy; DEAD/ERROR/
+UNREACHABLE paths can take minutes (tenacity retries + timeouts)."""
+
+from __future__ import annotations
+
+from importlib.metadata import version as package_version
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from sqlalchemy import Connection, select, text
+from sqlalchemy.exc import OperationalError
+
+from boardwatch.cli.context import build_context
+from boardwatch.core.clock import utcnow
+from boardwatch.scan.coordinator import default_providers
+from boardwatch.scan.health import probe_health
+from boardwatch.store import tables
+from boardwatch.store.db import schema_revision
+from boardwatch.store.queries import last_complete_scan_ages
+
+console = Console()
+
+
+def _db_revision(conn: Connection) -> str | None:
+    """The DB's applied Alembic revision, or None if the DB is unversioned/uninitialized."""
+    try:
+        result = conn.execute(text("SELECT version_num FROM alembic_version")).scalar_one_or_none()
+    except OperationalError:  # alembic_version table absent → schema never applied
+        return None
+    return str(result) if result is not None else None
+
+
+def _integrity_check(conn: Connection) -> str:
+    """PRAGMA integrity_check result ('ok' on a healthy DB). A module-level seam so tests
+    can force a corruption result without writing bad SQLite pages."""
+    return str(conn.execute(text("PRAGMA integrity_check")).scalar_one())
+
+
+def doctor(ctx: typer.Context, offline: bool = typer.Option(False, "--offline")) -> None:
+    """Connectivity, board health and freshness, and database integrity checks."""
+    # ensure=False (context.py supports it): doctor must INSPECT the schema, never migrate it —
+    # otherwise a corrupted/absent revision would be silently upgraded before we could report it
+    app_ctx = build_context(ctx.obj, ensure=False)
+
+    with app_ctx.engine.connect() as conn:
+        db_revision = _db_revision(conn)
+    schema_ok = db_revision == schema_revision()
+    if db_revision is None:  # absent/unversioned schema — report and stop before probing
+        console.print(f"boardwatch {package_version('boardwatch')}")
+        console.print("schema: ABSENT (run a boardwatch command that initializes the database)")
+        raise typer.Exit(code=1)
+
+    report = probe_health(app_ctx.engine, app_ctx.settings, offline=offline)
+
+    with app_ctx.engine.connect() as conn:
+        ages = last_complete_scan_ages(conn)
+        watches = conn.execute(
+            select(tables.companies).where(tables.companies.c.watched.is_(True))
+        ).all()
+        running = conn.execute(
+            select(tables.runs.c.id).where(tables.runs.c.finished_at.is_(None))
+        ).first()
+        integrity = _integrity_check(conn)
+
+    # connectivity: offline renders "not checked" for EVERY registered provider (not just those
+    # with watches — the offline contract); online renders the probed result
+    conn_table = Table("provider", "reachable")
+    if offline:
+        for provider in sorted(default_providers()):
+            conn_table.add_row(provider, "not checked")
+    else:
+        for c in report.connectivity:
+            label = "yes" if c.reachable else "NO"
+            conn_table.add_row(c.provider, label + (" (fallback)" if c.from_fallback else ""))
+    console.print(conn_table)
+
+    # per-board health + freshness; freshness renders an AGE (duration), not a raw timestamp;
+    # offline renders the STORED columns (last_health + last_ok_at)
+    now = utcnow()
+    health_table = Table("board", "last_health", "last_ok_at", "last_complete_scan_age")
+    for w in watches:
+        stored = " (stored)" if offline else ""
+        ts = ages.get(w.id)
+        age = "never" if ts is None else f"{(now - ts).days}d ago"
+        health_table.add_row(
+            f"{w.provider}:{w.slug}", (w.last_health or "—") + stored,
+            str(w.last_ok_at or "—"), age,
+        )
+    console.print(health_table)
+    if running:
+        console.print(f"[yellow]a scan is in progress (run {running.id})[/yellow]")
+
+    # schema check compares the DB's applied revision against the code's expected script head
+    schema_ok = db_revision == schema_revision()
+    integrity_ok = integrity == "ok"
+    console.print(f"boardwatch {package_version('boardwatch')}")
+    console.print(
+        f"integrity: {integrity} · schema: "
+        f"{'ok' if schema_ok else f'MISMATCH (db={db_revision}, code={schema_revision()})'}"
+    )
+
+    failed = report.actionable or not integrity_ok or not schema_ok
+    raise typer.Exit(code=1 if failed else 0)