snotes/AGENTS.md

# snotes — Agent Guide

## Project Overview

A multi-user hosted markdown notes app. Notes are plain `.md` files on a mounted
filesystem (NAS at `/mnt/aura/snotes`), while metadata, tags, history, and a
full-text search index live in SQLite. Built with FastAPI + a vanilla-JS SPA that
embeds TipTap (ProseMirror) for the editor.

## Essential Commands

| Action | Command |
|---|---|
| Dev server | `./run-local` (or `uv run uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000`) |
| Run tests | `uv run pytest` |
| Lint | `uv run ruff check .` |
| Format | `uv run ruff format .` |
| Install deps | `uv sync` |
| Build Docker | `docker compose build` |

## Project Structure

```
snotes/
├── backend/
│   ├── main.py       # FastAPI app, routes, lifespan, auth dependency
│   ├── config.py     # pydantic-settings, reads .env
│   ├── database.py   # aiosqlite: schema, seed users, list_users
│   ├── notes.py      # note CRUD, tag extraction, FTS index, history
│   ├── auth.py       # LAN vs remote gate + signed session cookie
│   └── models.py     # Pydantic request models
├── static/
│   ├── index.html    # SPA shell; loads marked, turndown, app.js (ESM)
│   ├── app.js        # SPA client + TipTap editor (esm.sh CDN)
│   ├── app.css       # Hyper-inspired stylesheet
│   └── snotes-main.png  # logo + favicon (copied from assets/)
├── tests/
│   ├── conftest.py   # LAN + remote ASGI client fixtures (temp DB + data dir)
│   └── test_main.py
├── Dockerfile
├── docker-compose.yml   # port 8019, mounts /mnt/aura/snotes
├── pyproject.toml
└── .env.example
```

## API Routes

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/me` | Current user + auth mode |
| `GET` | `/api/users` | List users |
| `POST` | `/api/users/select` | Set user cookie |
| `POST` | `/api/auth/login` | Remote password → auth cookie |
| `GET/POST` | `/api/notes` | List (current user) / create |
| `GET` | `/api/notes/recent` | Recent notes across all users |
| `GET/PUT/DELETE` | `/api/notes/{id}` | Read / update / soft-delete |
| `GET` | `/api/notes/{id}/history` | Version history |
| `GET` | `/api/tags` | Tag frequency |
| `GET` | `/api/search?q=` | FTS5 search |

## Non-obvious Behaviors

1. **Auth model**: the LAN gate (in `auth.is_lan`) matches the client IP against
   `LAN_CIDRS`. When remote, a signed `snotes_auth` cookie (itsdangerous) is
   required. User selection is a separate plain `snotes_user` cookie.
2. **Client IP**: read from `X-Forwarded-For` first, else `request.client.host` —
   set the latter in tests via `ASGITransport(..., client=(ip, port))`.
3. **Markdown round-trip**: the editor works on HTML. On load, `marked` converts
   markdown → HTML into TipTap; on save, `turndown` converts TipTap HTML →
   markdown. The stored `.md` file is the source of truth for search/tags.
4. **Storage split**: note *content* lives in `DATA_DIR/<user>/<uuid>.md`; all
   metadata (title, tags, timestamps, history) lives in SQLite. The filename is a
   random uuid hex, never the title (titles change freely).
5. **Soft delete**: deletes set `notes.deleted_at`, remove the `.md` file, and
   write a `delete` history row.
6. **FTS sync**: every save deletes + re-inserts the note's FTS row (title+body);
   tags are normalized into `tags`/`note_tags` join tables.

## Gotchas

- The frontend loads TipTap via `esm.sh` and marked/turndown via jsDelivr — the
  app needs internet access on first editor load (or vendor these locally later).
- `notes.py` opens a new `aiosqlite` connection per operation (same pattern as
  `tasky`); fine for a small personal corpus, not for hot paths.

## Browser extension (browser-extension/)

A Firefox MV3 "quick capture" extension — mirrors the pve-max extension pattern.
No backend changes: it reuses `GET /api/users` and `POST/PUT /api/notes`.

```
browser-extension/
  manifest.json        # MV3, gecko id snotes-capture@schmeeve.com
  background.js        # Relays fetch() to snotes API (credentials:'include')
  content.js           # postMessage ping/pong + settings handshake; get_context msg
  popup.html/js/css    # Capture form: textarea, user select, Save, Page button
  options.html/js      # Server URL config (auto-filled via ping/pong)
  release-firefox.sh   # Package + --sign; copies .xpi to static/
  icons/               # 48px + 96px PNGs (from assets/snotes-favicon.png)
```

### How it works

1. **Content script** runs on all pages. It answers `snotes-ping` → `snotes-pong`
   and `snotes-settings` → writes `serverUrl` to `browser.storage.sync`, plus a
   `get_context` message returning the page's selected text, title, and URL.
2. **Popup** prefills the note from the active tab's selection, lists users via
   `list_users`, and Save creates (`POST`) then updates (`PUT`) via `save_note`.
   A **Page** button inserts `[title](url)`; the note **autosaves 8s** after the
   last keystroke.
3. **Helper page** — the SPA's "Capture" view (`showTools()` in `static/app.js`)
   pings the extension, offers one-click install from
   `/static/snotes-capture-firefox.xpi`, and sends `snotes-settings` with
   `location.origin` to auto-configure.

### Install / release

```bash
# Manual dev install: about:debugging → Load Temporary Add-on → manifest.json
bash browser-extension/release-firefox.sh            # package .zip only
bash browser-extension/release-firefox.sh --sign     # sign via AMO (auto-bumps version)
```

The signed `.xpi` is copied to `static/snotes-capture-firefox.xpi` (git-tracked)
so the helper page serves it. Signing needs `AMO_JWT_ISSUER` / `AMO_JWT_SECRET`
and `npm install -g web-ext`.

### Gotchas

- The extension's `fetch` uses `credentials:'include'`, so on remote hosts it
  only works if the user has already logged into snotes in that browser (the
  `snotes_auth` cookie is reused). On LAN no auth is needed.
- `dist/` is gitignored; committed artifact lives in `static/` instead.