fix: review comments

Author: bradjin8

.github/dependabot.yml

@@ -10,11 +10,12 @@ updates:
     labels:
       - "dependencies"
 
-  # Keep Python runtime dependencies up-to-date within the bounded ranges
-  # declared in requirements.txt / pyproject.toml.
-  # Dependabot opens a PR for each package that has a new version available.
-  # After merging, regenerate requirements-lock.txt by running the
-  # "Update dependency lock file" workflow (or locally with pip-compile).
+  # Keep Python runtime dependencies up-to-date within the bounded ranges in
+  # pyproject.toml [project.dependencies] (requirements.txt must stay in sync).
+  # Dependabot opens a PR when a newer version fits those bounds — it does NOT
+  # refresh requirements-lock.txt. CI installs from the lock, so after merging a
+  # Dependabot pip PR you must regenerate the lock: run the "Update dependency
+  # lock file" workflow (Actions tab) or pip-compile locally (see README).
   - package-ecosystem: "pip"
     directory: "/"
     schedule:

.github/workflows/tests.yml

@@ -16,6 +16,58 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # ── Lock file + requirements sync (closes #47) ───────────────────────────
+  lockfile:
+    name: Lock file freshness
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify requirements.txt matches pyproject.toml
+        run: |
+          python <<'PY'
+          import sys
+          import tomllib
+          from pathlib import Path
+
+          with open("pyproject.toml", "rb") as f:
+              py_deps = tomllib.load(f)["project"]["dependencies"]
+          req_deps = [
+              line.strip()
+              for line in Path("requirements.txt").read_text().splitlines()
+              if line.strip() and not line.strip().startswith("#")
+          ]
+          if sorted(py_deps) != sorted(req_deps):
+              print(
+                  "requirements.txt [project.dependencies] drift from pyproject.toml",
+                  file=sys.stderr,
+              )
+              print("pyproject.toml:", sorted(py_deps), file=sys.stderr)
+              print("requirements.txt:", sorted(req_deps), file=sys.stderr)
+              sys.exit(1)
+          PY
+
+      - name: Install pip-tools
+        run: python -m pip install pip-tools
+
+      - name: Verify requirements-lock.txt is up to date
+        # Same pip-compile flags as update-lock.yml, without --upgrade.
+        run: |
+          pip-compile requirements.txt \
+            --output-file /tmp/requirements-lock.txt \
+            --no-header \
+            --annotation-style=line \
+            --allow-unsafe \
+            --quiet
+          diff -u \
+            <(grep -E '^[A-Za-z0-9_.-]+==' requirements-lock.txt | sort) \
+            <(grep -E '^[A-Za-z0-9_.-]+==' /tmp/requirements-lock.txt | sort)
+
   # ── Unit tests: matrix across OS and Python version ───────────────────────
   # Closes #13. The unittest suite is the merge gate. Multi-OS catches the
   # rare path / line-ending issue that a single-OS run hides; multi-Python

.github/workflows/update-lock.yml

@@ -36,15 +36,19 @@ jobs:
             --allow-unsafe \
             --upgrade
 
-      - name: Restore header comment
-        # pip-compile --no-header omits the auto-generated header line but
-        # we maintain our own documentation header; restore it if missing.
+      - name: Prepend lock file header
+        # pip-compile --no-header strips our docs header every run; restore via
+        # heredoc (single-quoted HEADER=... would leave literal \n characters).
         run: |
-          HEADER='# Pinned lock file — generated by pip-compile (pip-tools).\n# Install: pip install -r requirements-lock.txt\n# Update:  pip-compile requirements.txt --output-file requirements-lock.txt --no-header --annotation-style=line --allow-unsafe\n# Run periodically (e.g. via the "Update dependency lock file" CI workflow) to pick up\n# upstream patch / security releases within the bounded ranges in requirements.txt.'
-          if ! head -1 requirements-lock.txt | grep -q "^#"; then
-            printf '%s\n' "$HEADER" | cat - requirements-lock.txt > /tmp/lock.tmp
-            mv /tmp/lock.tmp requirements-lock.txt
-          fi
+          cat > /tmp/lock-header <<'EOF'
+          # Pinned lock file — generated by pip-compile (pip-tools).
+          # Install: pip install -r requirements-lock.txt
+          # Update:  pip-compile requirements.txt --output-file requirements-lock.txt --no-header --annotation-style=line --allow-unsafe
+          # Run periodically (e.g. via the "Update dependency lock file" CI workflow) to pick up
+          # upstream patch / security releases within the bounded ranges in requirements.txt.
+          EOF
+          cat /tmp/lock-header requirements-lock.txt > /tmp/lock.tmp
+          mv /tmp/lock.tmp requirements-lock.txt
 
       - name: Open PR if lock file changed
         uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676  # v7
@@ -57,6 +61,11 @@ jobs:
             Automated weekly refresh of `requirements-lock.txt`.
 
             Generated by `pip-compile --upgrade` from the bounded specifiers
-            in `requirements.txt`. Review the diff to confirm no unexpected
-            major-version jumps before merging.
+            in `requirements.txt` (must match `pyproject.toml` `[project.dependencies]`).
+
+            **Dependabot pip PRs** may bump bounds in `requirements.txt` / `pyproject.toml`
+            but do not regenerate this lock file — merge those first, then merge this PR
+            (or run **Actions → Update dependency lock file → Run workflow**).
+
+            Review the diff to confirm no unexpected major-version jumps before merging.
           labels: dependencies

README.md

@@ -61,6 +61,34 @@ source venv/bin/activate
 pip install -r requirements.txt
 ```
 
+For reproducible installs (same versions as CI), use the pinned lock file:
+
+```bash
+pip install -r requirements-lock.txt
+```
+
+### Dependency bounds and lock file
+
+Runtime version **bounds** live in `pyproject.toml` under `[project.dependencies]` (`flask`, `fpdf2`, `pillow`, etc.). `requirements.txt` mirrors those specifiers for backward compatibility — keep them identical when you change deps.
+
+**CI** installs from `requirements-lock.txt`, which pins exact versions (including transitive packages). Regenerate the lock after editing bounds:
+
+```bash
+pip install pip-tools
+pip-compile requirements.txt \
+  --output-file requirements-lock.txt \
+  --no-header \
+  --annotation-style=line \
+  --allow-unsafe
+```
+
+Then restore the comment header at the top of `requirements-lock.txt` (see the existing file) and commit both `requirements.txt` / `pyproject.toml` and `requirements-lock.txt`.
+
+**Automated updates:**
+
+- **Dependabot** (`.github/dependabot.yml`) — weekly PRs for `pip` and `github-actions` when newer versions fit the declared bounds. Merging a Dependabot **pip** PR does **not** refresh the lock file; run the lock workflow or `pip-compile` locally afterward.
+- **Update dependency lock file** (`.github/workflows/update-lock.yml`) — scheduled Mondays 08:00 UTC (and manual **Actions → Run workflow**) runs `pip-compile --upgrade` and opens a PR with an updated `requirements-lock.txt`.
+
 ## Quick Start (Web UI)
 
 ```bash
@@ -73,7 +101,7 @@ The Werkzeug debugger is **off by default** and must be opted in explicitly via
 
 ## Tests
 
-Run the full suite from the repository root (install `requirements.txt` first):
+Run the full suite from the repository root (install `requirements-lock.txt` or `requirements.txt` first):
 
 ```bash
 python -m unittest discover tests -v
@@ -147,7 +175,9 @@ Cursor CLI agent sessions are read from `~/.cursor/chats/` (the default path use
 ```
 cursor-chat-browser-python/
 ├── app.py                  # Flask application entry point
-├── requirements.txt        # Python dependencies
+├── requirements.txt        # Runtime bounds (mirrors pyproject.toml)
+├── requirements-lock.txt   # Pinned lock file used by CI
+├── pyproject.toml          # Package metadata and canonical dependency bounds
 ├── api/                    # API route blueprints
 │   ├── workspaces.py       # /api/workspaces endpoints
 │   ├── composers.py        # /api/composers endpoints