chore: make runs working

Author: moneebullah25

.claude/rules/backend-frontend.md

@@ -0,0 +1,51 @@
+---
+description: Backend (FastAPI) and Frontend (React) rules for app_starter
+globs: backend/**,frontend/**
+alwaysApply: false
+---
+
+# Backend and Frontend Rules
+
+## FastAPI App Structure
+
+- The `backend/` package lives at the repo root (not under `src/`).
+- Always run the backend with `PYTHONPATH=.:src` so both `backend` and `app` are importable.
+- The FastAPI application object is `app` in `backend/main.py`.
+- The items router is mounted at prefix `/api`.
+- CORS is configured to allow `http://localhost:5173` (the Vite dev server). Do not add wildcard origins.
+- Use `make serve` to start the backend on port 8000 with hot-reload.
+
+## API Endpoints
+
+- `GET /health` returns `{"status": "ok"}` with status 200. No authentication required.
+- `GET /api/items` returns a list of `Item` objects.
+- `POST /api/items` accepts an `ItemCreate` JSON body and returns an `Item`.
+
+## Schemas
+
+- Defined in `backend/schemas.py` as Pydantic `BaseModel` subclasses.
+- `Item`: `id: int`, `name: str`
+- `ItemCreate`: `name: str`
+
+## Testing
+
+- Tests live in `backend/tests/test_api.py`.
+- Use `fastapi.testclient.TestClient` with the `app` from `backend.main`.
+- Three tests required:
+  1. `test_health` -- GET `/health` returns 200 and `{"status": "ok"}`.
+  2. `test_get_items` -- GET `/api/items` returns 200 and a list.
+  3. `test_create_item` -- POST `/api/items` with `{"name": "Test Item"}` returns 200.
+
+## Frontend
+
+- The frontend is a Vite + React + TypeScript app in `frontend/`.
+- Use `make frontend` to start the dev server on port 5173.
+- `VITE_API_URL` env var controls the backend URL; defaults to `http://localhost:8000`. Set it in `frontend/.env` (copy from `.env.example`).
+- TypeScript interfaces in `App.tsx` must mirror the Pydantic schemas in `backend/schemas.py`. Keep them in sync when either side changes.
+
+## Running the Full Stack
+
+- Backend: `make serve` (port 8000, `PYTHONPATH=.:src`).
+- Frontend: `make frontend` (port 5173).
+- The frontend calls the backend directly via `VITE_API_URL`. CORS on the backend allows the frontend origin.
+- Run `make setup` once to install both Python and Node dependencies.

.claude/rules/infrastructure.md

@@ -0,0 +1,93 @@
+---
+description: Infrastructure rules for Docker, CI, gitignore, pre-commit, and Claude hooks
+globs: docker/**,Dockerfile,.dockerignore,.github/workflows/**,.gitignore,.pre-commit-config.yaml,.claude/**
+alwaysApply: false
+---
+
+# Infrastructure Rules
+
+## Docker Build
+
+- Always build from the repo root: `docker build -f docker/Dockerfile .`
+- The Dockerfile must install `git` via `apt-get install -y --no-install-recommends git` because `uv-dynamic-versioning` calls git to resolve the package version at install time.
+- Install production deps with `uv sync --no-dev --no-editable`. The `--no-editable` flag is required so the package is installed into `.venv` as a regular package, not a symlink.
+- The full repo context is copied into the image so git history is available for versioning.
+
+## Docker Compose Services
+
+Two services defined in `docker/docker-compose.yml`:
+
+| Service    | Image / Build                     | Port  |
+|------------|-----------------------------------|-------|
+| `backend`  | Built locally from `docker/Dockerfile` (context: `..`) | 8000  |
+| `frontend` | `node:22-alpine`                  | 5173  |
+
+Startup order enforced via `depends_on` with `condition: service_healthy`:
+`backend` (healthy) -> `frontend`.
+
+## Healthchecks
+
+- **backend**: HTTP check on port 8000 (`/health`). Interval 10s, start period 15s.
+- **frontend**: `wget` check on port 5173. Interval 15s, start period 30s.
+
+## Env Vars in Docker
+
+- `PYTHONPATH=.:src` -- Set so both `backend` and `app` packages are importable.
+- `VITE_API_URL=http://localhost:8000` -- Frontend env var for the browser to reach the backend. Uses `localhost` because the browser runs on the host.
+
+## Running Docker
+
+```shell
+docker compose -f docker/docker-compose.yml up --build -d
+```
+
+## CI Pipeline
+
+Two parallel jobs in `.github/workflows/ci.yml`:
+
+### `build` job
+- Matrix: Python 3.11, 3.12, 3.13 on `ubuntu-latest`.
+- Checks out with `fetch-depth: 0` (full history needed for version resolution).
+- Runs `uv run python devtools/lint.py` for linting.
+- Runs `uv run pytest` with `PYTHONPATH=.:src`.
+
+### `docker-build` job
+- Runs in parallel with `build`.
+- Builds the backend image: `docker build -f docker/Dockerfile -t app-starter-backend:ci .`
+- Does not push; build-only verification.
+
+## Gitignore
+
+Key project-specific entries in `.gitignore`:
+- **Frontend build**: `frontend/node_modules/`, `frontend/dist/`, `frontend/.env`
+
+## Pre-commit Hooks
+
+Hooks defined in `.pre-commit-config.yaml`:
+
+1. `trailing-whitespace`, `end-of-file-fixer`, `check-yaml`, `check-merge-conflict`
+2. `check-added-large-files` with 5 MB limit (`--maxkb=5000`)
+3. `ruff` (with `--fix`) and `ruff-format`
+
+If `core.hooksPath` is set in global git config (e.g., by another tool), pre-commit
+hooks installed via `pre-commit install` may be silently ignored. To work around this,
+run hooks manually:
+```shell
+uv run pre-commit run --all-files
+```
+
+## Post-edit Claude Hook
+
+Configured in `.claude/settings.json` as a `PostToolUse` hook on `Edit|Write|NotebookEdit`.
+
+- `asyncRewake: true` -- Runs in the background; exit code 2 wakes Claude on failure.
+- Timeout: 300 seconds.
+- Script: `.claude/validate.sh`.
+
+Behavior of `validate.sh`:
+- Skips validation entirely for config/doc files (`.md`, `.json`, `.yaml`, `.yml`, `.toml`, `.txt`, `.sh`, `.env`, `.gitignore`, `.dockerignore`).
+- Always runs `make lint` and `make test`.
+- Exits 2 on any failure to trigger Claude rewake.
+
+Do not modify `validate.sh` or `.claude/settings.json` without understanding the
+rewake behavior. A non-zero exit other than 2 will not wake the model.

.claude/rules/tooling.md

@@ -0,0 +1,85 @@
+---
+description: Tooling, build system, and CI rules for python_nbdev_starter
+globs: "*"
+alwaysApply: true
+---
+
+# Tooling Rules
+
+## Package Management
+
+- Always use `uv` for all package and environment operations. Never use `pip`, `pip install`, or bare `python` directly.
+- Install dependencies: `uv sync --all-extras`
+- Add a new dependency: `uv add <package>`
+- Run any command in the project venv: `uv run <command>`
+- Upgrade all deps: `uv sync --upgrade --all-extras --dev`
+
+## nbdev Commands
+
+- Export notebooks to Python: `uv run nbdev_export`
+- Test notebooks: `uv run nbdev_test`
+- Build docs: `uv run nbdev_docs`
+- Clean notebook outputs: `uv run nbdev_clean`
+- Always run `nbdev_export` after editing notebooks before running lint or tests.
+
+## Make Targets
+
+| Target | What it does |
+|---|---|
+| `make` (default) | Runs `agent-rules`, `install`, `lint`, `test` in order |
+| `make install` | `uv sync --all-extras` |
+| `make lint` | `uv run python devtools/lint.py` (codespell, ruff check --fix, ruff format, basedpyright) |
+| `make test` | `uv run pytest` |
+| `make nbdev-export` | Export notebooks to `python_nbdev_starter/` |
+| `make nbdev-test` | Run tests inside notebooks |
+| `make nbdev-docs` | Build documentation |
+| `make nbdev-clean` | Strip notebook outputs |
+| `make upgrade` | `uv sync --upgrade --all-extras --dev` |
+| `make build` | `nbdev_export` + `uv build` |
+| `make clean` | Removes dist, caches, .venv |
+| `make agent-rules` | Regenerates `CLAUDE.md` and `AGENTS.md` from `.cursor/rules/*.mdc` |
+
+## Testing
+
+- Test paths: `python_nbdev_starter`. Configured via `testpaths` in `pyproject.toml`.
+- `pythonpath = ["."]` is set in pytest config so imports resolve.
+- `python_files = ["*.py"]` — pytest discovers tests in any `.py` file.
+- Run all tests: `make test`
+- Run notebook tests: `make nbdev-test`
+- Run a single test with output: `uv run pytest -s path/to/file.py`
+
+## Linting
+
+- `make lint` runs `devtools/lint.py`, which executes in order:
+  1. `codespell --write-changes` on `python_nbdev_starter devtools README.md`
+  2. `ruff check --fix` on `python_nbdev_starter devtools`
+  3. `ruff format` on `python_nbdev_starter devtools`
+  4. `basedpyright --stats` on `python_nbdev_starter devtools`
+- Always run `make lint` after changes and fix all errors before considering work complete.
+
+## Versioning
+
+- Uses `uv-dynamic-versioning` which reads version from git tags at build time.
+- The `git` binary must be available for versioning to work.
+- `fetch-depth: 0` is required in CI checkout for full tag history.
+- Do not hardcode version strings; the version is always derived from git.
+
+## CI Pipeline
+
+- `test.yaml` uses `fastai/workflows/nbdev-ci@master` — the standard nbdev CI workflow.
+- Runs on push/PR/workflow_dispatch.
+
+## Post-Edit Validation Hook
+
+- `.claude/settings.json` registers a `PostToolUse` hook on `Edit|Write|NotebookEdit`.
+- The hook runs `.claude/validate.sh` with a 300-second timeout and `asyncRewake: true`.
+- Conditional logic in `validate.sh`:
+  - **Skips entirely** for non-source files (`.md`, `.json`, `.yaml`, `.yml`, `.toml`, `.txt`, `.sh`, `.env`, `.gitignore`, `.dockerignore`).
+  - **For `.ipynb` files**: runs `nbdev_export` first, then `make lint` and `make test`.
+  - **For `.py` files**: always runs `make lint` and `make test`.
+- Exit code 2 on failure wakes the model to address the issue.
+
+## Pre-commit Hooks
+
+- To run hooks manually: `uv run pre-commit run --all-files`
+- Never skip pre-commit checks. If a hook fails, fix the underlying issue.

.claude/settings.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync:*)",
+      "Bash(uv run:*)",
+      "Bash(make:*)",
+      "Bash(nbdev_export:*)",
+      "Bash(nbdev_test:*)",
+      "Bash(nbdev_clean:*)",
+      "Bash(nbdev_docs:*)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash /Users/mrmacbook/Desktop/muneeb/python_nbdev_starter/.claude/validate.sh",
+            "timeout": 300,
+            "statusMessage": "Validating (lint + test)...",
+            "asyncRewake": true
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/validate.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Post-edit validation hook. Reads the changed file path from stdin JSON,
+# then runs make targets appropriate for what changed.
+# Exit 2 on failure so asyncRewake wakes the model.
+
+set -uo pipefail
+
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$PROJECT_DIR"
+
+# Extract changed file path from hook JSON payload
+CHANGED_FILE=$(python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+inp = data.get('tool_input', {})
+print(inp.get('file_path', '') or inp.get('notebook_path', ''))
+" 2>/dev/null || echo "")
+
+# Regenerate CLAUDE.md when rule files change
+if echo "$CHANGED_FILE" | grep -qE "(\.cursor/rules/.*\.mdc$|\.claude/rules/.*\.md$)"; then
+    echo "--- make agent-rules ---"
+    if ! make agent-rules; then
+        echo "FAILED: make agent-rules"
+        exit 2
+    fi
+    exit 0
+fi
+
+# Skip validation for non-source files
+if echo "$CHANGED_FILE" | grep -qE "\.(mdc|md|json|yaml|yml|toml|txt|sh|env|gitignore|dockerignore)$"; then
+    exit 0
+fi
+
+FAILED=0
+
+run() {
+    echo "--- $* ---"
+    if ! "$@"; then
+        echo "FAILED: $*"
+        FAILED=1
+    fi
+}
+
+# For notebook changes, export first
+if echo "$CHANGED_FILE" | grep -qE "\.ipynb$"; then
+    echo "--- nbdev_export ---"
+    if ! uv run nbdev-export; then
+        echo "FAILED: nbdev_export"
+        FAILED=1
+    fi
+fi
+
+# Always run lint and notebook tests
+run make lint
+run make nbdev-test
+
+if [ "$FAILED" -ne 0 ]; then
+    exit 2
+fi

.cursor/rules/general.mdc

@@ -0,0 +1,72 @@
+---
+description: General Guidelines
+globs: 
+alwaysApply: true
+---
+# Assistant Rules
+
+**Your fundamental responsibility:** Remember you are a senior engineer and have a
+serious responsibility to be clear, factual, think step by step and be systematic,
+express expert opinion, and make use of the user’s attention wisely.
+
+**Rules must be followed:** It is your responsibility to carefully read these rules as
+well as Python or other language-specific rules included here.
+
+Therefore:
+
+- Be concise. State answers or responses directly, without extra commentary.
+  Or (if it is clear) directly do what is asked.
+
+- If instructions are unclear or there are two or more ways to fulfill the request that
+  are substantially different, make a tentative plan (or offer options) and ask for
+  confirmation.
+
+- If you can think of a much better approach that the user requests, be sure to mention
+  it. It’s your responsibility to suggest approaches that lead to better, simpler
+  solutions.
+
+- Give thoughtful opinions on better/worse approaches, but NEVER say “great idea!”
+  or “good job” or other compliments, encouragement, or non-essential banter.
+  Your job is to give expert opinions and to solve problems, not to motivate the user.
+
+- Avoid gratuitous enthusiasm or generalizations.
+  Use thoughtful comparisons like saying which code is “cleaner” but don’t congratulate
+  yourself. Avoid subjective descriptions.
+  For example, don’t say “I’ve meticulously improved the code and it is in great shape!”
+  That is useless generalization.
+  Instead, specifically say what you’ve done, e.g., "I’ve added types, including
+  generics, to all the methods in `Foo` and fixed all linter errors."
+
+# General Coding Guidelines
+
+## Using Comments
+
+- Keep all comments concise and clear and suitable for inclusion in final production.
+
+- DO use comments whenever the intent of a given piece of code is subtle or confusing or
+  avoids a bug or is not obvious from the code itself.
+
+- DO NOT repeat in comments what is obvious from the names of functions or variables or
+  types.
+
+- DO NOT include comments that reflect what you did, such as “Added this function” as
+  this is meaningless to anyone reading the code later.
+  (Instead, describe in your message to the user any other contextual information.)
+
+- DO NOT use fancy or needlessly decorated headings like “===== MIGRATION TOOLS =====”
+  in comments
+
+- DO NOT number steps in comments.
+  These are hard to maintain if the code changes.
+  NEVER DO THIS: “// Step 3: Fetch the data from the cache”\
+  This is fine: “// Now fetch the data from the cache”
+
+- DO NOT use emojis or special unicode characters like ① or • or – or — in comments.
+
+- Use emojis in output if it enhances the clarity and can be done consistently.
+  You may use ✔︎ and ✘ to indicate success and failure, and ∆ and ‼︎ for user-facing
+  warnings and errors, for example, but be sure to do it consistently.
+  DO NOT use emojis gratuitously in comments or output.
+  You may use then ONLY when they have clear meanings (like success or failure).
+  Unless the user says otherwise, avoid emojis and Unicode in comments as clutters the
+  output with little benefit.