bincio-wiki/CLAUDE.md

# bincio_wiki — development notes

## Project overview

A private wiki for the bincio group of friends. Built on Astro 6 using the
`brutsalvadi/astro-bloomz` fork as a git submodule at `site/`. Content lives
in `pages/` and `blog/` at the repo root; Astro loads them via glob loaders
pointing to `../pages` and `../blog` (outside the submodule). No symlinks.

## Directory layout

```
bincio_wiki/
  pages/          wiki content (*.md files the community edits)
    _docs/        documentation shown as a separate section
  blog/           blog/stories content (*.md files)
  config/         bincio-specific configuration (outside site/ submodule)
    sections.json wiki sections and subsections (imported by Astro pages + editor)
    i.bonsai.md   wikibonsai semantic tree (loaded by the index collection)
  assets/         user-uploaded images (gitignored; rsync'd to VPS separately)
  site/           Astro 6 app (git submodule → brutsalvadi/astro-bloomz)
  edit/           FastAPI edit server (Python, port 8001)
  pyproject.toml  Python dependencies (managed by uv)
  uv.lock         uv lockfile (committed)
  scripts/        dev.sh — starts both Astro and FastAPI together
  docs/           repo-level documentation (not served as wiki pages)
```

## Running locally

```bash
bash scripts/dev.sh          # Astro only (port 4321)
bash scripts/dev.sh --edit   # Astro + FastAPI edit sidecar (port 8001)
```

Python dependencies are managed by `uv`. `uv sync` is called automatically
by `dev.sh --edit` — no manual setup needed. To add a dependency:
`uv add <package>` (updates `pyproject.toml` and `uv.lock`).

## Content architecture

- Wiki pages: `pages/*.md` (IDs in Astro content store are the bare filename
  without extension, e.g. `digital-garden`)
- Docs section: `pages/_docs/*.md` (IDs start with `_docs/`)
- Blog/stories: `blog/*.md`
- Assets: `assets/` — gitignored, not part of the Astro build. FastAPI serves them
  at `/assets/{filename}` in dev (Vite proxies `/assets` → port 8001). On the VPS,
  nginx serves `/assets/` directly from the filesystem (rsync'd separately).
  Upload via `POST /api/assets` (multipart); returns `{"url": "/assets/filename"}`.
  The editor inserts `![name](/assets/filename)` into the markdown on upload.
- Bonsai index: stored in `site/src/content/index/` — the `i.bonsai.md` file
  defines the semantic tree structure
- The homepage (`site/src/pages/index.astro`) splits entries by `_docs/` prefix
  into "Pagine recenti" and "Documentazione" sections

## Astro 6 content layer notes

- Collections use glob loaders in `site/src/content.config.ts`
- `entries` collection base is `../pages` (relative to `site/`), resolving to
  `bincio_wiki/pages/`. Vite is configured with `server.fs.allow: ['..']` to
  permit serving files from outside the project root.
- `blog` collection base is `../blog` (same pattern)
- `index` collection base is `./src/content/index` (stays inside `site/`)
- Custom `generateId` on `entries` and `index` — see `content.config.ts` for
  details. `index` preserves dots so `i.bonsai` is not mangled by githubSlug.
- Use `entry.id` not `entry.slug`
- Use `import { render } from 'astro:content'; render(entry)` not `entry.render()`

## Language / i18n

Italian is the default language. All documentation in `pages/_docs/` is in
Italian. Technical terms (WikiRefs, Astro, plugin names, wikilink syntax,
code) stay in English. See `docs/lingua.md` for the full rationale.

## Authentication

### Current approach (same as bincio_activity)

**Not yet implemented in bincio_wiki** — pending.

Planned pattern:
- nginx serves the static Astro build publicly (no nginx-level auth)
- Every Astro page layout calls `GET /api/me` on load
- If the API returns 401/error, the page JS redirects to `/login/`
- FastAPI (`edit/server.py`) handles sessions: SQLite users table, bcrypt
  passwords, HTTP-only session cookie
- Login page at `/login/` — a static Astro page that POSTs credentials to
  `/api/auth/login`

### Security assessment

This is **client-side enforcement only**. The HTML is technically accessible
to anyone who:
- Uses `curl` or `wget` directly
- Disables JavaScript in the browser
- Views page source

For bincio_wiki this is an acceptable tradeoff. The content is community
memories and shared activities (not financial/medical data), members are not
adversarial, and the goal is keeping casual visitors and search engine crawlers
out — not resisting determined attackers.

### Future: making specific pages public

With this architecture, making a page public later is trivial: just use a
layout variant that skips the `/api/me` check. No nginx changes needed since
nginx already serves everything publicly at the static file level.

For stricter enforcement on genuinely sensitive pages, the alternative is
**Astro SSR** with a server middleware that checks the session cookie before
rendering any HTML. This would require migrating from static output to SSR
mode — a bigger change, not warranted for now.

### VPS deployment target

Debian 12 VPS. nginx serves the built site from `/var/www/bincio/wiki/`.
FastAPI proxied from `localhost:8001` via nginx `location /api/ { proxy_pass }`.
See `docs/vps.md` for full nginx config and deployment steps.

## Edit concurrency — future work

Current state: last-write-wins. No conflict detection.

Planned approach (not yet implemented):

1. **Git commits with attribution** — on every save, `git add <file>` +
   `git commit -m "handle: edited page-name" --author="handle <handle@bincio.wiki>"`.
   Requires an `asyncio.Lock` in `server.py` to serialize git operations.

2. **Optimistic locking via base-hash check** — when the client loads a page
   for editing, the server returns the current git commit hash alongside the
   content. On save, the client sends that hash back. If `HEAD` has moved for
   that file since then, the save is rejected with a 409 and a "pagina
   modificata, ricarica prima di salvare" message. No lock to release, no
   keepalive needed — the user can abandon the editor freely.

3. **3-way merge (ideal)** — instead of rejecting on conflict, use
   `git merge-file` with base = content at `baseHash`, ours = current HEAD,
   theirs = user's new content. Different lines → automatic merge, one commit.
   Same lines → 409 conflict error. Builds on step 2; adds it when needed.

No pessimistic locking needed. Optimistic locking with 3-way merge handles
concurrent edits gracefully without timers or "are you still there?" prompts.

## Git conventions

- No `Co-Authored-By: Claude` trailers in commits
- Commit messages in English
- Do not push without explicit user instruction