blackboard-cli 0.1.0__tar.gz

blackboard_cli-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides project-specific guidance for Claude Code when working in this repository.
+
+## Project Identity
+
+`bb-cli` is a terminal-first Blackboard client for students. The current repository already implements the Day 1–9 foundation: CLI commands, SQLite persistence, iCal + Blackboard sync, course content caching, downloads, and an AI-facing query layer. The immediate delivery priority is Day 10: `bb chat`.
+
+## Current Delivery Phase
+
+- Treat the repository state as implemented truth.
+- Treat `PLAN.md` as delivery-priority truth.
+- The current sprint is complete through Day 9.
+- Prioritize Day 10–14 deliverables before v0.2 ideas.
+- If a requested change is outside the current plan, note it as future work instead of silently expanding scope.
+
+## Non-Negotiable Rules
+
+- Use `uv` for running, testing, and packaging workflows. Do not replace repo workflows with direct `pip` usage.
+- Keep Blackboard data answers grounded in local data or tool results. Do not invent Blackboard facts.
+- Keep selectors externalized in `selectors/blackboard_ultra.toml`. Do not hardcode fragile selectors into random call sites unless there is a strong reason.
+- Prefer minimal-impact changes that fit the current architecture.
+- When project brief, roadmap, and source diverge, trust the current repository state first.
+
+## Repo Navigation by Path
+
+- `pyproject.toml` — package metadata, entrypoint, build config, dev tooling
+- `bb/cli.py` — Typer command surface and user-facing orchestration
+- `bb/db.py` — SQLite schema, migrations, persistence helpers, sync log, downloads
+- `bb/sync.py` — iCal retry flow, activity-stream sync, grade sync, snapshot save
+- `bb/adapters/blackboard_ultra.py` — Blackboard auth, session restore, scraping, selector-driven parsing, content-tree traversal
+- `selectors/blackboard_ultra.toml` — runtime selector source for Blackboard scraping
+- `bb/tools/queries.py` — AI-facing query surface returning JSON-friendly results
+- `bb/models/content.py` — content tree dataclasses and serialization helpers
+
+## Change Rules by Lane
+
+### CLI and command behavior
+Start in `bb/cli.py`. Check whether the change also affects persistence in `bb/db.py`, sync behavior in `bb/sync.py`, or cached content behavior.
+
+### Database, schema, or persistence
+Start in `bb/db.py`. Review migrations, query helpers, and all callers in `bb/cli.py` and `bb/tools/queries.py`.
+
+### Blackboard scraping or selector breakage
+Inspect `bb/adapters/blackboard_ultra.py` and `selectors/blackboard_ultra.toml` together. Prefer selector fixes before broad parser rewrites. Check `bb/sync.py` snapshot behavior when stream scraping returns zero items.
+
+### AI-facing data access and future chat behavior
+Start in `bb/tools/queries.py`. Ensure outputs stay JSON-serializable, missing DB/cache states are handled gracefully, and response logic stays grounded in actual data.
+
+### Course content, cache, and downloads
+Inspect `bb/models/content.py`, the course/download commands in `bb/cli.py`, and the Blackboard content scraping logic in `bb/adapters/blackboard_ultra.py`.
+
+## Verification Rules
+
+- CLI changes: verify the affected command flow and any impacted tables or cache behavior.
+- DB changes: verify schema compatibility, caller expectations, and regression risk.
+- Scraping changes: verify the selector path, fallback behavior, and minimum viable fix.
+- Tool-layer changes: verify JSON shape, empty-state behavior, and alignment with the underlying database or cached files.
+- Sprint-facing AI/chat changes: prefer extending the tool surface before compensating with prompt-only behavior.
+
+## Skills and Subagents
+
+Use `.claude/context/` for project memory, `.claude/skills/` for repeatable workflows, and `.claude/agents/` for specialized review or investigation once those are added. Keep this file constitutional and path-aware; move long checklists and playbooks into skills or context files.
+
+## Git Rules
+
+- **NEVER commit `docs/` or `tasks/`** — internal planning files (specs, plans, brainstorming). They are in `.gitignore`. If `git add` warns "ignored file", stop immediately — never force-add.
+- **`git filter-repo` removes remote** — after running it, always re-add: `git remote add origin git@github.com:Bruce1508/bb-cli.git`
+- **Force push only after intentional history rewrite** — use `git push --force origin main` only after `git filter-repo`. Normal pushes use `--force-with-lease`.
+
+## Python / Testing Gotchas (learned Day 8–9)
+
+- **`pdfplumber` pages outside `with` block** — `pdf.pages` raises after context exits. Always capture `page_count = len(pdf.pages)` INSIDE `with pdfplumber.open() as pdf:`.
+- **`iterdir()` on missing dir** — `Path.iterdir()` raises `FileNotFoundError` if dir doesn't exist. Guard: `if not path.exists(): return ...` before iterating.
+- **`httpx.stream()` needs method arg** — `client.stream("GET", url)`, not `client.stream(url)`. Also: `Content-Length` is a string — cast: `int(response.headers.get("content-length", 0))`.
+- **`patch()` needs module-level import** — `patch("bb.tools.queries.pdfplumber.open")` requires `import pdfplumber` at module level. Lazy imports inside functions don't exist as attributes at patch time.
+- **`or` vs `is not None`** — `x or default` treats empty list/string/0 as falsy. Use `x if x is not None else default` when "provided but empty" is a valid value.
+- **Library classes must not have UI deps** — never put `typer.confirm` / `input()` inside library classes (`Downloader`, etc.). That's the CLI layer's responsibility; mixing them breaks non-TTY usage and testing.
+- **Partial file cleanup on failure** — on download error, always `dest_path.unlink(missing_ok=True)` in except clauses so corrupt partial files don't accumulate silently.
+- **`uv pip install -e .` .pth bug** — hatchling generates `_bb_cli.pth` without trailing newline; Python skips it. Fix: `printf '/path/to/bb-cli\n' > .venv/lib/python3.13/site-packages/_bb_cli.pth`.
+- **`webbrowser.open(None)`** — silently opens `"None"` as a URL. Always guard: `if item.url is None: raise typer.Exit(1)` before calling.

blackboard_cli-0.1.0/.claude/hooks/README.md

@@ -0,0 +1,47 @@
+# Hooks
+
+This directory contains project-specific hook scripts for `bb-cli`.
+
+## Scope
+
+These scripts are wired through the project settings file:
+
+- `.claude/settings.json`
+
+This follows Claude Code's project-level hook model, where hooks declared in `.claude/settings.json` apply to the current repository.
+
+## Hook scripts
+
+### `scripts/guard-uv.sh`
+
+Runs before Bash tool calls and checks for commands that drift from repository conventions.
+
+Current behavior:
+- flags direct `pip` usage
+- flags `python -m pip`
+- flags bare `pytest` when it is not invoked through `uv run`
+
+The hook does not silently block the command. Instead, it returns a `PreToolUse` decision of `ask`, which surfaces the repository convention and lets the user confirm intentionally.
+
+### `scripts/suggest-targeted-tests.sh`
+
+Runs after successful `Edit` or `Write` tool calls and suggests small, relevant checks based on which paths were changed.
+
+Current path groups:
+- DB and tool layer: `bb/db.py`, `bb/tools/queries.py`, `bb/models/content.py`
+- scraping lane: `bb/adapters/blackboard_ultra.py`, `selectors/blackboard_ultra.toml`, `bb/sync.py`
+- CLI surface: `bb/cli.py`
+- packaging: `pyproject.toml`
+
+The hook adds repo-specific follow-up context rather than trying to run tests automatically.
+
+## Design intent
+
+These hooks are deliberately lightweight guardrails.
+
+They are meant to:
+- reinforce repo conventions
+- reduce avoidable workflow drift
+- suggest the smallest relevant verification step
+
+They are not meant to become a heavy automation layer that interrupts normal work unnecessarily.

blackboard_cli-0.1.0/.claude/hooks/scripts/guard-uv.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -gt 0 && -n "${1:-}" ]]; then
+  INPUT="$1"
+elif [[ -n "${CLAUDE_HOOK_INPUT:-}" ]]; then
+  INPUT="$CLAUDE_HOOK_INPUT"
+else
+  INPUT="$(cat)"
+fi
+
+if [[ -z "$INPUT" ]]; then
+  exit 0
+fi
+
+MESSAGE=""
+ADDITIONAL=""
+
+if echo "$INPUT" | grep -Eiq '"command"[[:space:]]*:[[:space:]]*"[^"]*python[[:space:]]+-m[[:space:]]+pip'; then
+  MESSAGE="Prefer uv-based workflows over python -m pip."
+  ADDITIONAL="This repository uses uv-based install and execution flows. Prefer commands like 'uv pip install -e .' or 'uv run ...' instead of python -m pip."
+elif echo "$INPUT" | grep -Eiq '"command"[[:space:]]*:[[:space:]]*"[^"]*(^|[^[:alnum:]_])pip([[:space:]]|$)'; then
+  MESSAGE="Prefer uv-based workflows over direct pip usage."
+  ADDITIONAL="This repository uses uv-based install and execution flows. Prefer commands like 'uv pip install -e .' or 'uv run ...' instead of direct pip usage."
+elif echo "$INPUT" | grep -Eiq '"command"[[:space:]]*:[[:space:]]*"[^"]*(^|[^[:alnum:]_])pytest([[:space:]]|$)' && ! echo "$INPUT" | grep -Eiq 'uv[[:space:]]+run[[:space:]]+pytest'; then
+  MESSAGE="Prefer running tests through uv."
+  ADDITIONAL="Repository convention is to run tests through uv, for example 'uv run pytest tests/ -v'."
+fi
+
+if [[ -z "$MESSAGE" ]]; then
+  exit 0
+fi
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "ask",
+    "permissionDecisionReason": "$MESSAGE",
+    "additionalContext": "$ADDITIONAL"
+  }
+}
+EOF
+
+exit 0

blackboard_cli-0.1.0/.claude/hooks/scripts/suggest-targeted-tests.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -gt 0 && -n "${1:-}" ]]; then
+  INPUT="$1"
+elif [[ -n "${CLAUDE_HOOK_INPUT:-}" ]]; then
+  INPUT="$CLAUDE_HOOK_INPUT"
+else
+  INPUT="$(cat)"
+fi
+
+if [[ -z "$INPUT" ]]; then
+  exit 0
+fi
+
+suggestions=()
+
+if echo "$INPUT" | grep -Eiq 'bb/db\.py|bb/tools/queries\.py|bb/models/content\.py'; then
+  suggestions+=("uv run pytest tests/ -v")
+fi
+
+if echo "$INPUT" | grep -Eiq 'bb/adapters/blackboard_ultra\.py|selectors/blackboard_ultra\.toml|bb/sync\.py'; then
+  suggestions+=("Check scraping-related tests or add a narrow regression test around the changed adapter or selector lane.")
+fi
+
+if echo "$INPUT" | grep -Eiq 'bb/cli\.py'; then
+  suggestions+=("Sanity-check the affected command flow with uv run bb <command>.")
+fi
+
+if echo "$INPUT" | grep -Eiq 'pyproject\.toml'; then
+  suggestions+=("Verify package and CLI sanity with uv build and a quick uv run bb <command> check.")
+fi
+
+if [[ ${#suggestions[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+json_array=""
+for s in "${suggestions[@]}"; do
+  escaped=$(printf '%s' "$s" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  if [[ -n "$json_array" ]]; then
+    json_array+="\\n- ${escaped}"
+  else
+    json_array+="- ${escaped}"
+  fi
+done
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Suggested targeted verification:\n${json_array}"
+  },
+  "suppressOutput": true
+}
+EOF
+
+exit 0

blackboard_cli-0.1.0/.claude/settings.json

@@ -0,0 +1,30 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scripts/guard-uv.sh",
+            "timeout": 10,
+            "statusMessage": "Checking bb-cli shell workflow conventions"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/scripts/suggest-targeted-tests.sh",
+            "timeout": 10,
+            "statusMessage": "Suggesting targeted verification for bb-cli"
+          }
+        ]
+      }
+    ]
+  }
+}

blackboard_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,92 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(/opt/homebrew/bin/uv run:*)",
+      "Bash(uv run:*)",
+      "Bash(echo \"EXIT: $?\")",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(uv pip:*)",
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "Bash(git remote:*)",
+      "Bash(pip show:*)",
+      "Bash(pip3 install:*)",
+      "Bash(git push:*)",
+      "Bash(grep:*)",
+      "Bash(sed -i '' 's/patch\\(\"\"bb\\\\.cli\\\\.notify\"\"\\)/patch\\(\"\"bb.cli.dispatch_notify\"\"\\)/g' /Users/brucevo/Desktop/bb-cli/tests/test_cli_import_ical.py)",
+      "Bash(sed -i '' 's/Mock bb\\\\.cli\\\\.notify/Mock bb.cli.dispatch_notify/' /Users/brucevo/Desktop/bb-cli/tests/test_cli_import_ical.py)",
+      "Bash(sw_vers -productVersion)",
+      "Read(//Users/brucevo/Library/LaunchAgents/**)",
+      "mcp__plugin_context7_context7__query-docs",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -c \"import bb; print\\(bb.__file__\\)\" 2>&1)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 /Users/brucevo/Desktop/bb-cli/.venv/bin/bb auto-setup --help 2>&1)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -c \"import sys; print\\(sys.path\\)\")",
+      "Bash(git:*)",
+      "Bash(grep -v \"^$\")",
+      "Bash(ls /Users/brucevo/Desktop/bb-cli/.venv/lib/python*/site-packages/)",
+      "Bash(python3 -m site --user-site)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -c \":*)",
+      "Bash(.venv/bin/python -c \"import site; print\\(site.getusersitepackages\\(\\)\\); print\\(site.getsitepackages\\(\\)\\)\")",
+      "Bash(xxd)",
+      "Bash(printf /Users/brucevo/Desktop/bb-clin cat /Users/brucevo/Desktop/bb-cli/.venv/lib/python3.13/site-packages/_bb_cli.pth)",
+      "Bash(uv sync:*)",
+      "Bash(printf '/Users/brucevo/Desktop/bb-cli\\\\n')",
+      "Bash(git-filter-repo --version)",
+      "Skill(code-review:code-review)",
+      "Bash(.venv/bin/bb status:*)",
+      "Bash(cat .venv/lib/python*/site-packages/bb*.pth)",
+      "Bash(ls .venv/lib/python*/site-packages/)",
+      "Bash(.venv/bin/bb download:*)",
+      "Bash(.venv/bin/bb open:*)",
+      "Bash(PYTHONPATH=/Users/brucevo/Desktop/bb-cli .venv/bin/bb status 2>&1)",
+      "Bash(PYTHONPATH=/Users/brucevo/Desktop/bb-cli .venv/bin/bb --help)",
+      "Bash(.venv/bin/python -c \"import site; site.addsitedir\\('.venv/lib/python3.13/site-packages'\\); import bb; print\\(bb.__file__\\)\" 2>&1)",
+      "Bash(.venv/bin/python -c \"import sys; print\\(sys.path\\)\")",
+      "Bash(.venv/bin/python -c \"import bb; print\\(bb.__file__\\)\" 2>&1)",
+      "Read(//opt/homebrew/Cellar/python@3.13/3.13.7/Frameworks/Python.framework/Versions/3.13/bin/**)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 /Users/brucevo/Desktop/bb-cli/.venv/bin/bb status 2>&1)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -c \"\nimport site\nimport sys\nprint\\('site-packages:', site.getsitepackages\\(\\)\\)\nprint\\('/Users/brucevo/Desktop/bb-cli' in sys.path\\)\n\")",
+      "Bash(uv venv:*)",
+      "Bash(printf n:*)",
+      "Bash(printf '%s\\\\n' '/Users/brucevo/Desktop/bb-cli')",
+      "Bash(python3:*)",
+      "Bash(.venv/bin/python -c \"from bb.cli import app; print\\('ok'\\)\" 2>&1)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -c \"import sys; print\\([p for p in sys.path if 'bb' in p.lower\\(\\)]\\)\")",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -c \"import site; print\\(site.getusersitepackages\\(\\)\\); print\\(site.getsitepackages\\(\\)\\)\")",
+      "Bash(sqlite3 ~/.bb/bb.db \"DELETE FROM deadlines; DELETE FROM sync_log;\")",
+      "Bash(sqlite3:*)",
+      "Bash(find /Users/brucevo/Desktop/bb-cli/bb/adapters/__pycache__ -name \"*.pyc\" -delete)",
+      "Bash(printf /Users/brucevo/Desktop/bb-clin)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -c \"import sys; print\\([p for p in sys.path if 'bb-cli' in p]\\)\")",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -c \"import site; site.addsitedir\\('/Users/brucevo/Desktop/bb-cli/.venv/lib/python3.13/site-packages'\\); import sys; print\\([p for p in sys.path if 'bb-cli' in p or 'Desktop' in p]\\)\")",
+      "Bash(ls:*)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.venv/bin/python3 -S -c \"import sys; print\\(sys.path\\)\")",
+      "Bash(find /Users/brucevo/Desktop/bb-cli/bb -name \"*.pyc\" -delete)",
+      "Bash(find /Users/brucevo/Desktop/bb-cli/bb -name \"__pycache__\" -type d -exec rm -rf {} +)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.worktrees/day10-bb-chat/.venv/bin/python -c \"import bb; print\\(bb.__file__\\)\")",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.worktrees/day10-bb-chat/.venv/bin/python -c \"from bb.cli import app; cmds = [c.name for c in app.registered_commands]; print\\(cmds\\)\")",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.worktrees/day10-bb-chat/.venv/bin/bb chat:*)",
+      "Bash(xxd:*)",
+      "Bash(/Users/brucevo/Desktop/bb-cli/.worktrees/day10-bb-chat/.venv/bin/python3 -c \"import sys; print\\([p for p in sys.path if 'bb' in p or 'day10' in p]\\)\")",
+      "Bash(/Users/brucevo/Desktop/bb-cli/inspect_courses_page.py:*)",
+      "Bash(echo \"/clear:*)",
+      "Bash(uv add:*)",
+      "Bash(pip index:*)",
+      "Bash(pip install:*)",
+      "Bash(curl -s \"https://pypi.org/pypi/mcp/json\")",
+      "Bash(curl -s https://pypi.org/pypi/mcp/json)",
+      "Bash(gtimeout 2 uv run bb mcp-server)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(wc -l tests/*.py)",
+      "Bash(uv build:*)",
+      "Bash(source /tmp/bb-test/bin/activate)",
+      "Bash(bb version:*)",
+      "Bash(bb --help)",
+      "Bash(deactivate)",
+      "Bash(rm -rf /tmp/bb-test)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" https://pypi.org/pypi/blackboard-cli/json)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" https://pypi.org/pypi/bbcli/json)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" https://pypi.org/pypi/bb-student/json)"
+    ]
+  }
+}

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

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Lint
+        run: uv run ruff check bb/
+
+      - name: Test
+        run: uv run pytest tests/ -q
+
+      - name: Build
+        run: uv build

blackboard_cli-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.coverage
+htmlcov/
+# uv.lock intentionally tracked for reproducible CI installs
+**/.DS_Store
+# Note: ~/.bb/ is outside the repo — no gitignore entry needed
+
+# Keep internal docs/plans private — only CLAUDE.md and README.md are public
+*.md
+!CLAUDE.md
+!README.md
+
+# NEVER commit internal planning docs — specs, plans, brainstorming notes
+docs/
+tasks/

blackboard_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,212 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`bb-cli` is "Claude Code for Blackboard" — a terminal-first tool that lets college students manage their entire school life without opening a browser. Core features: sync deadlines/grades/announcements from Blackboard Ultra, browse/download course content, and **`bb chat` — an interactive AI assistant** that answers questions using real Blackboard data. Think of it as giving students a personal AI that actually knows their courses, deadlines, and grades.
+
+Target distribution: PyPI package `bb-cli`. Blackboard Ultra first, plugin architecture for Canvas/Moodle/Brightspace later.
+
+## Package Manager & Commands
+
+This project uses `uv` exclusively — do not use `pip` directly.
+
+```bash
+# Run CLI commands
+uv run bb <command>
+
+# Run tests
+uv run pytest tests/ -v
+uv run pytest tests/test_db.py -v          # single test file
+uv run pytest --cov=bb --cov-report=term-missing  # with coverage
+
+# Watch mode during development
+uv run ptw
+
+# Linting and formatting
+uv run ruff check bb/
+uv run ruff format bb/
+
+# Build package
+uv build
+
+# Install from local source
+uv pip install -e .
+
+# Start MCP server (for Claude Desktop integration)
+uv run bb mcp-server
+```
+
+## Architecture
+
+### Core Data Flow
+
+```
+bb sync
+  → Phase 1: iCal feed (no auth) via httpx
+  → Phase 2: Activity Stream scraping via Playwright (headed Chromium)
+  → Parse → upsert to SQLite (~/.bb/bb.db)
+  → Notify via configured provider(s)
+
+bb chat
+  → User types natural language query
+  → LLM decides which tool functions to call
+  → Tool functions query local DB / read cached files / trigger sync
+  → LLM formats response with real data
+  → Never hallucinate — always ground answers in tool results
+
+bb mcp-server
+  → Exposes tool functions as MCP protocol tools
+  → Claude Desktop / Cursor / any MCP client can connect
+  → Student asks Claude "what are my deadlines?" → Claude calls bb-cli tools → real data
+```
+
+### Project Structure
+
+```
+bb/
+  cli.py            # Typer app — all command definitions
+  config.py         # TOML config at ~/.bb/config.toml (Pydantic validation)
+  db.py             # SQLite (WAL mode) — CRUD + version-based migrations
+  sync.py           # Orchestrates both sync phases
+  hash.py           # Content hashing utilities for dedup
+  logger.py         # Structured logging with Rich handler
+  adapters/
+    base.py         # LMSAdapter ABC — defines interface all adapters must implement
+    registry.py     # Decorator-based adapter registration + discovery
+    blackboard_ultra.py  # Playwright scraping: auth, activity stream, grades, content
+  parsers/
+    ical.py         # .ics → list[Deadline], UTC storage / Toronto display
+    html_llm.py     # LLM-based HTML parser — fallback when CSS selectors fail
+  security/
+    session.py      # Fernet-encrypted session files; keyring for key storage
+  notify/
+    base.py         # Notifier ABC
+    terminal.py     # OS-native notifications (osascript / notify-send)
+    ntfy.py         # ntfy.sh push (zero account required)
+    telegram.py     # Telegram Bot API
+    discord.py      # Discord webhook
+  tools/
+    __init__.py     # TOOL_REGISTRY — central dict of all callable tool functions
+    queries.py      # DB query tools: deadlines, grades, announcements, courses
+    ai_tools.py     # AI-powered tools: summarize, study plan, key concepts
+  ai/
+    chat.py         # Chat engine: REPL loop, tool calling orchestration, streaming
+    prompts.py      # System prompt for student assistant context
+    providers/
+      ollama.py     # Ollama local LLM integration (free, private, offline)
+      api.py        # Claude API / OpenAI API fallback
+  mcp/
+    server.py       # MCP server exposing tool functions for Claude Desktop
+  models/
+    content.py      # ContentItem, ContentTree dataclasses for course browser
+  cache.py          # TTL-based content cache management
+selectors/
+  blackboard_ultra.toml   # CSS selectors loaded at runtime — NOT hardcoded
+tests/
+  fixtures/
+    sample.ics
+    activity_stream.html  # Saved real HTML for offline testing
+```
+
+### Key Design Decisions
+
+**`bb chat` is the killer feature.** Everything else (sync, due, grades) is foundation that chat builds on. The tool function layer (`bb/tools/`) is the bridge: CLI commands and chat both call the same functions, just with different interfaces.
+
+**Tool function architecture.** Every data query is a tool function in `bb/tools/queries.py` with: clear docstring (LLM reads this), Pydantic input/output models, and direct SQLite queries. The LLM calls these tools — it never makes up data. Tool functions are shared between `bb chat` (Ollama/API calls them) and `bb mcp-server` (Claude Desktop calls them via MCP protocol).
+
+**AI provider priority.** `bb chat` auto-detects: Ollama running locally → use it (free, private, offline). No Ollama → check config for Claude/OpenAI API key → use that. No AI at all → graceful message suggesting install Ollama. Config: `[ai] provider = "ollama" | "claude" | "openai"` in `~/.bb/config.toml`.
+
+**MCP server as Claude Desktop bridge.** `bb mcp-server` starts a stdio MCP server that exposes all tool functions. Students add it to Claude Desktop config → can ask Claude about their Blackboard data in natural language. This means bb-cli works both standalone (via `bb chat` with Ollama) and as a plugin for Claude Desktop.
+
+**Selector externalization.** All Playwright CSS selectors live in `selectors/blackboard_ultra.toml`. The adapter reads them at runtime. This allows selector updates without code changes when Blackboard modifies its UI.
+
+**Selector resilience.** Primary selector → fallback selector → LLM extraction (`bb/parsers/html_llm.py` using Ollama locally). Circuit breaker: max 20 pages per sync.
+
+**Session encryption.** Playwright `storage_state()` is encrypted with Fernet symmetric encryption. Key stored in OS keyring; falls back to password-based derivation when keyring is unavailable.
+
+**Session 3-tier check.** fresh (< threshold, skip verify) / uncertain (verify with headless browser) / expired (assume dead) — ported from SkipClass Pro's `smart_session_manager.py`.
+
+**Cache layer.** Course content trees cached at `~/.bb/cache/<COURSE>/tree.json` with 2h TTL. Downloads at `~/.bb/files/<COURSE>/`. Study packs at `~/.bb/study/<COURSE>/`.
+
+### Data Models
+
+Defined in `bb/adapters/base.py`:
+- `Deadline` — course, title, due_at (UTC), source (ical/stream/api)
+- `Announcement` — course, title, body_preview, posted_at, is_read
+- `GradeItem` — course, item, score, out_of, status (pending/submitted/graded)
+
+Content models in `bb/models/content.py`:
+- `ContentItem` — type (module/file/folder/discussion/link), title, url, download_url, children, size_bytes, mime_type
+- `ContentTree` — course, scraped_at, items list
+
+Tool output models in `bb/tools/`:
+- All tool functions return plain dicts or Pydantic models serializable to JSON
+- LLM receives tool results as JSON → formats human-readable response
+
+### Notification Rules
+
+Configured in `~/.bb/config.toml`. Default: new deadline → normal priority; deadline <24h → high; new grade → high; session expired → high. Dedup via `notified_at` field in DB.
+
+### Automation
+
+`bb auto-setup` installs OS-native scheduler:
+- macOS: launchd plist at `~/Library/LaunchAgents/com.bb-cli.sync.plist`
+- Linux: crontab entry
+- Default interval: every 4 hours, runs `bb sync` silently
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `bb init` | Interactive wizard — LMS URL, notification method, AI provider, saves `~/.bb/config.toml` |
+| `bb auth` | Opens headed Chromium for login + MFA, saves encrypted session |
+| `bb sync` | Full sync (iCal + Activity Stream); `--ical-only`, `--dry-run` flags |
+| `bb due` | Upcoming deadlines table; `--days N`, `--course`, `--all`, `--json` |
+| `bb ann` | Recent announcements; `--unread` filter |
+| `bb grades` | Grade table; `--course` filter |
+| `bb status` | Session health, last sync time, DB stats |
+| `bb chat` | **Interactive AI assistant** — ask anything about your courses in natural language |
+| `bb chat "query"` | Single-shot mode — ask one question, get answer, exit |
+| `bb <COURSE>` | Interactive course content browser (e.g., `bb BTP200`); `--tree`, `--refresh` |
+| `bb download <COURSE>` | File downloader; `--all`, `--type pdf` flags |
+| `bb open <COURSE> <item>` | Open non-downloadable items in browser |
+| `bb mcp-server` | Start MCP server for Claude Desktop / Cursor integration |
+| `bb auto-setup` | Install OS scheduler for automatic syncing; `--disable` to stop |
+| `bb cache clear` | Clear content cache |
+| `bb setup-browsers` | Run `playwright install chromium` |
+
+### `bb chat` Special Commands
+
+Inside the chat REPL, these slash commands are available:
+- `/exit` or `/quit` — exit chat
+- `/clear` — clear conversation history
+- `/sync` — trigger `bb sync` without leaving chat
+- `/courses` — list all courses
+- `/help` — show available commands
+
+## Testing Approach
+
+- Use real in-memory SQLite (not mocks) for DB tests
+- Save real Blackboard HTML as fixtures for offline adapter testing
+- Mock Playwright for integration tests
+- Mock Ollama for chat tests — test tool routing + response format
+- Test tool functions independently with fixture data in SQLite
+- Test MCP server for protocol compliance
+- Target: >70% coverage before PyPI release
+- Typer app must have 2+ commands — single-command apps collapse into standalone mode, breaking `runner.invoke(app, ["subcommand"])` in tests
+- Patch `BB_DIR` in tests via `unittest.mock.patch("bb.config.BB_DIR", tmp_path)` and `patch("bb.db.BB_DIR", tmp_path)` — `Database.__init__` uses `path=None` pattern so `BB_DIR` is resolved at call time, not import time
+- WAL pragma does nothing on `:memory:` — test WAL mode with a real `tempfile.NamedTemporaryFile`
+
+## Gotchas & Environment Notes
+
+- **Hatchling package discovery**: `pyproject.toml` requires `[tool.hatch.build.targets.wheel] packages = ["bb"]` — hatchling cannot auto-discover `bb` from the hyphenated project name `bb-cli`
+- **uv dev deps syntax**: Use `[dependency-groups] dev = [...]` (PEP 735), NOT `[tool.uv] dev-dependencies` — the latter is deprecated and will break in future uv versions
+- **SQLite migrations**: Use `connection.executescript()` (not `execute()`) for multi-statement SQL migration strings — handles multiple statements and auto-commits
+- **CLI not found after uv sync**: If `uv run bb` gives `ModuleNotFoundError`, run `uv pip install -e .` to force editable install registration
+- **`git filter-repo` removes remote**: After running `git filter-repo`, remote is deleted — re-add with `git remote add origin <url>` before force pushing
+- **Ollama tool calling**: `qwen2.5:7b` has better tool calling accuracy than `llama3.2:3b`. Always validate tool call arguments with Pydantic before executing. If tool calling fails, fall back to keyword-based routing.
+- **MCP server stdio**: MCP server communicates via stdin/stdout (stdio transport). Do NOT print anything to stdout in server mode — use stderr for logging. Use `from mcp.server.fastmcp import FastMCP` — `FastMCP` lives inside the official `mcp` package (`mcp>=1.12`), not the third-party `fastmcp` package. Pass `log_level="WARNING"` to suppress INFO noise to stderr.
+- **Chat streaming**: When streaming Ollama responses, use `rich.live.Live` context for smooth token-by-token display. Don't mix `print()` with Rich Live — it causes display glitches.
+- **Tool function docstrings matter**: Ollama/Claude read tool docstrings to decide when to call them. Write docstrings as if explaining to a smart intern what the function does and when to use it.

blackboard_cli-0.1.0/LICENSE

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