diff --git a/nexus-dev/.claude-plugin/plugin.json b/nexus-dev/.claude-plugin/plugin.json index 154e28a..9a285ff 100644 --- a/nexus-dev/.claude-plugin/plugin.json +++ b/nexus-dev/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "nexus-dev", - "version": "0.1.0", - "description": "Projekt-Plugin für nexus (Family Knowledge Hub): SDD-Karten-Workflow, Security/Privacy-Invarianten (SICHT/PRIV/fail-closed), Karten-Command. Für Claude Code Sessions im Repo l.kirchner/nexus-hub.", + "version": "0.2.0", + "description": "Projekt-Plugin für nexus (Family Knowledge Hub): SDD-Karten-Workflow, Security/Privacy-Invarianten (SICHT/PRIV/fail-closed), Stack-Konventionen, Karten-Command. Für Claude Code Sessions im Repo l.kirchner/nexus-hub.", "author": { "name": "l.kirchner", "url": "https://gitea.luki-net.org/l.kirchner" diff --git a/nexus-dev/skills/nexus-stack/SKILL.md b/nexus-dev/skills/nexus-stack/SKILL.md new file mode 100644 index 0000000..3c568df --- /dev/null +++ b/nexus-dev/skills/nexus-stack/SKILL.md @@ -0,0 +1,45 @@ +--- +name: nexus-stack +description: Stack-Konventionen fuer nexus (Family Knowledge Hub) seit K-101. Verwenden bei jeder Implementierungs-Karte im Repo l.kirchner/nexus-hub - deckt ab uv-Projektlayout, FastAPI-Patterns, Settings, structlog-Redaction-Pflicht, Alembic, Web-Build, Deploy-Artefakt und Projekt-Kommandos. +--- + +# nexus Stack-Konventionen (ADR-0002, eingeführt mit K-101) + +## Layout & Werkzeuge + +- **Backend:** uv-Projekt, Python 3.12, src-Layout `src/nexus/`. Console-Scripts: `nexus-api`, `nexus-worker`. +- **Web:** `web/` — Vite + React + TypeScript + Tailwind v4 (`@tailwindcss/vite`). Build-Artefakt `web/dist` wird von FastAPI unter `/` ausgeliefert (API-Routen gewinnen; SPA via `StaticFiles(html=True)`). +- **Kommandos** (verbindliche Liste: `docs/05_AGENT_RULES.md` → Projekt-Kommandos): `uv sync`, `uv run pytest`, `uv run ruff check`, `uv run mypy`, `uv run alembic upgrade head`, `npm run build` in `web/`. +- Vor jedem Merge lokal grün: ruff + mypy (strict) + pytest; CI (`.gitea/workflows/ci.yml`) führt dieselben Gates aus. + +## Settings & Konfiguration + +- Eine `Settings`-Klasse (`src/nexus/config.py`, pydantic-settings, Prefix `NEXUS_`), Zugriff via `get_settings()` (lru_cache). Tests leeren den Cache (siehe `tests/conftest.py`-Fixture). +- Produktion liest `/etc/nexus/env` (systemd `EnvironmentFile`). Neue Settings dort dokumentieren (proxmox-scripts `install/nexus-install.sh` legt die Datei an). +- `Settings.__repr__` redacted Secrets (`database_url=***`) — bei neuen Secret-Feldern beibehalten. +- Version = Git-SHA: `NEXUS_GIT_SHA` env → `GIT_SHA`-Datei im Artefakt (schreibt deploy.yml) → `"dev"`. + +## Logging (PRIV-5 — nicht verhandelbar) + +- IMMER `nexus.logging_setup.configure_logging()` — nie eigenes logging-Setup, nie `print`. +- Content-Keys (`body`, `content`, `text`, `ocr_text`, `title`, `filename`, …) werden vom Redaction-Processor auf `***` gesetzt. Neue content-tragende Felder in `CONTENT_KEYS` ergänzen — niemals umbenennen, um Redaction zu umgehen. +- Log-Zeilen tragen IDs + Metadaten, nie Inhalte. Secrets (DB-Passwörter, Tokens) zusätzlich als `secrets=[...]` an `configure_logging` geben. +- Jede Karte mit neuen Log-Pfaden ergänzt einen Redaction-Test nach dem Muster `tests/test_logging_redaction.py`. + +## Datenbank & Migrationen + +- SQLAlchemy 2 + Alembic; DSN ausschließlich über `NEXUS_DATABASE_URL` (sqlalchemy-Format `postgresql+psycopg://…`), nie in Dateien. +- Migrationen: `alembic/versions/`, Template ist typisiert (`script.py.mako`). Erste Fach-Migration kommt mit K-103 (setzt auch `target_metadata`). +- `/healthz` meldet `db: unconfigured | ok | unreachable` — Karten, die die DB anschließen, halten dieses Feld korrekt. + +## Deploy (deploy.yml, seit K-101 scharf) + +- Push auf `main` → Test-Gate (`needs:`) → Artefakt (`src/`, `pyproject.toml`, `uv.lock`, `alembic*`, `start*.sh`, `GIT_SHA`, `web/dist`) → rsync nach `/opt/nexus/current` → `uv sync --frozen --no-dev` → Service-Restart → Healthcheck. +- Rollback: voriger Stand liegt in `/opt/nexus/previous` (Prozedur im deploy.yml-Header). +- systemd: `nexus.service` → `start.sh` (uvicorn), `nexus-worker.service` → `start-worker.sh`. Runtime-Provisionierung des LXC: proxmox-scripts `install/nexus-runtime.sh` (idempotent). + +## Rote Linien + +- Kein `requirements.txt`, kein pip — uv ist die einzige Quelle der Wahrheit (`uv.lock` committed). +- Keine neuen Top-Level-Prozesse außer API + Worker ohne ADR. +- API-first: jeder User-Workflow hat API-Tests, bevor/während die UI ihn bekommt.