diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b530928 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,125 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repository is + +Gnexus Book is a Git-backed personal infrastructure knowledge base plus the tooling that operates on it: a FastAPI backend, an MCP server for AI agents, and a Vue UI. The repository root **is** the data store — Markdown docs (numbered directories), YAML inventory in `40-inventory/`, JSON Schemas in `schemas/`, and an audit/pending-change area in `90-maintenance/pending-changes/`. + +Two consumers must keep working: + +- humans reading Markdown/YAML from Git; +- AI agents calling the MCP tools, which must not bypass validation or Git safety checks. + +## Platform handbook (mandatory) + +Rules for the whole Gnexus ecosystem live in `~/Projects/gnexus-handbook` (https://git.gnexus.space/root/gnexus-handbook), not here. Before changing authentication, MCP/keys, UI, secrets, backups, health, deployment, or documentation policy, read the handbook README and the relevant section. Link to the handbook instead of copying its rules. + +Notable for this repository: + +- Commit messages follow `10-platform/git.md`; it overrides Claude Code's default attribution (no co-authorship lines). +- This file-backed prototype predates several handbook conventions (SSO, per-user MCP keys, streamable-HTTP MCP, off-host verified backups). `50-decisions/ADR-0002-postgres-storage-and-versioning.md` tracks the gaps and the planned move to PostgreSQL. + +## Common commands + +### Server + +```bash +cd server +python3 -m venv .venv && . .venv/bin/activate # or: uv venv --python 3.11 +pip install -e ".[dev]" + +# Run all tests +.venv/bin/python -m pytest -q + +# Run a single test +.venv/bin/python -m pytest tests/test_api.py::test_health_endpoint -q + +# Dev API (README uses 8080; the Vite proxy expects 3005) +.venv/bin/python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 3005 + +# MCP server (stdio by default) +.venv/bin/python -m app.mcp_server +``` + +MCP environment: `GNEXUS_BOOK_REPO_ROOT` (defaults to the repo root derived from `server/app/config.py`) and `GNEXUS_BOOK_MCP_TRANSPORT` (`stdio` | `sse` | `streamable-http`). + +### PostgreSQL read backend (Phase 1) + +```bash +# From the repo root: local dev cluster on 127.0.0.1:5433 +./scripts/dev-db.sh start + +cd server +export GNEXUS_BOOK_DATABASE_URL="$(../scripts/dev-db.sh url)" +.venv/bin/alembic upgrade head +.venv/bin/python -m app.storage.cli import --replace +.venv/bin/python -m app.storage.cli parity # exits 1 on a file/DB difference + +GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005 +``` + +`GNEXUS_BOOK_STORAGE_BACKEND` defaults to `file`. Dumps go to the off-host NFS via +`scripts/backup-db.sh`; `scripts/restore-db.sh` requires `GNEXUS_BOOK_RESTORE_YES=1`. + +### UI + +```bash +cd ui +npm install +npm run dev # port 3006, proxies /api -> http://127.0.0.1:3005 +npm run build # outputs dist/ +``` + +`gnexus-ui-kit` is a local `file:../../gnexus-ui-kit` dependency (sibling of the repo root), built from `https://git.gnexus.space/root/gnexus-ui-kit`. `ui/vite.config.js` dedupes Vue, resolves Vue's ESM bundler build, and serves the kit's fonts from `node_modules/gnexus-ui-kit/dist/assets/fonts`. + +### Deploy (VPS) + +```bash +./scripts/install.sh # uv + Python 3.11, nvm/Node, clone/build ui-kit, venv, UI build, systemd user units +./scripts/deploy.sh # git pull, rebuild kit + UI, sync UI dist to /var/www/gnexus-book, restart backend, reload nginx +``` + +`systemd/*.service` hardcodes `/home/ubuntu/gnexus-book` paths — adjust them if the deployment user differs. Nginx (`nginx/gnexus-book.conf`) serves `ui/dist` on port 80, proxies `/api/` to the backend on 8000 and `/mcp/` to the MCP server on 8001. + +## Backend architecture + +`server/app/main.py` is the FastAPI composition root. Every route depends on a repository class constructed from `app/config.py:Settings`; `Settings()` defaults `repo_root` to `server/../..`, and tests pass `Settings(tmp_path)` to build isolated fake repositories. + +The domain layer is split by responsibility: + +- **`docs_repository.py` + `markdown.py`** — list/read/search Markdown under the repo root, skipping `.git`, `.venv`, `node_modules`, etc. The frontmatter parser is deliberately simple: only a flat `key: value` block between the first `---` fences is parsed. Nested YAML or typed values in frontmatter are not supported. +- **`inventory.py`** — reads `40-inventory/.yml`; each file is a YAML list and items are looked up by `id`. +- **`relationships.py`** — builds a graph whose node ids are `/` and whose edges come from known cross-record fields (`host`, `hypervisor_host`, `runs_services`, `points_to`, `destination`, `related_*`, etc.). References to unknown ids are returned in `unresolved_references` rather than failing the request. +- **`freshness.py`** — checks required frontmatter fields and staleness (`last_reviewed` + `review_interval`, e.g. `90d`), and reports inventory `docs:` targets that do not exist. +- **`validation.py`** — the full-repo gate used before apply/commit: schemas parse as Draft 2020-12, every inventory file validates against its schema (`SCHEMA_BY_INVENTORY`), Markdown has required frontmatter, ids are unique per inventory file, and a regex scan detects raw secret assignments/private-key blocks. The separate inventory `docs`-link validator (`_validate_inventory_doc_links`) is intentionally disabled; freshness still reports those missing targets. +- **`pending_changes.py`** — the write path. A proposal is a JSON file in `90-maintenance/pending-changes/`; `apply()` writes a Markdown doc or patches/creates an inventory item, runs whole-repo validation, and restores the previous file content if validation fails. Only `doc` and `inventory-item` kinds can be applied; full-file inventory replacement is not implemented. +- **`git_adapter.py`** — status/diff/commit. Commit requires an explicit file list, rejects absolute/traversal/denied paths, runs validation first, stages only the named files, and creates a local commit only (never pushes). +- **`storage/`** — the PostgreSQL layer introduced for the migration. `models.py` defines the schema (documents/versions/blobs, inventory items/versions, changesets, users, audit), `db_repositories.py` implements the same read interfaces as the file repositories, `importer.py` copies the current repository into the database, `parity.py` compares both backends, and `cli.py` exposes `import`, `parity`, and `counts`. `factory.py` chooses the backend from `GNEXUS_BOOK_STORAGE_BACKEND`. Alembic lives in `server/alembic/`. Reads can use either backend; in `db` mode write endpoints/tools are blocked until Phase 2, and validation/freshness still read files until Phase 3. + +### MCP server + +`server/app/mcp_server.py` exposes the same domain functions (not HTTP) as 17 MCP tools plus `gnexus-book://*` resources. The long tool descriptions and `MCP_INSTRUCTIONS`/`AGENT_USAGE_GUIDE` strings are covered by tests in `tests/test_mcp_server.py`; update the tests when changing that guidance. `GET /mcp/info` reflects the registered tools and instructions. + +The MCP guidance tells external agents never to edit repository files directly and to use propose → apply → validate → commit. That rule is for MCP clients; normal development in this checkout edits files directly, but still run validation before committing. + +## Documentation and data conventions + +- Every knowledge document needs frontmatter with `owner`, `status`, `last_reviewed`, `review_interval`, `confidence`, `source_of_truth`. Validation skips `README.md` and `server/**`; other Markdown (including `ui/README.md`) is checked. +- Inventory files are YAML sequences beginning with `---`. Item ids must be unique within a file. Adding a new inventory type requires both `40-inventory/.yml` and an entry in `validation.SCHEMA_BY_INVENTORY`. +- Never store raw passwords, tokens, private keys, recovery codes, or session cookies. Describe where a secret lives using reference values such as `unknown`, `redacted`, `password manager`, `vault`, or `ref:...`. +- Some inventory schemas require a `docs` link. When creating such an item, create the Markdown document first (the MCP inventory-creation guidance codifies this). +- Update `last_reviewed` only after the information was actually verified. +- `60-generated/inventory-index.md` is still a placeholder; no generator exists yet. + +## UI architecture + +The entire frontend is a single Vue 3 app in `ui/src/main.js` (no router). It renders tabbed, read-focused views — docs, inventory, changes, git — using components from `gnexus-ui-kit/vue`. All data goes through `/api` (`apiGet`/`apiPost`). Avoid copying UI-kit styles locally; prefer upstream changes in the kit. + +## Testing notes + +Tests run from `server/` with `pythonpath = ["."]`. Most tests read the real repository, so they assert on real inventory/docs content; fixture-based tests use `Settings(tmp_path)` and copy schemas from the real repo. + +Database tests use `GNEXUS_BOOK_TEST_DATABASE_URL` (default `postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test`) and skip when PostgreSQL is unavailable. `tests/test_migrations.py` applies the Alembic migration to a temporary database. + +`tests/test_docs_repository.py::test_freshness_report_is_clean_for_knowledge_docs` is date-dependent: it fails once documents pass their `review_interval`. When it fails, refresh `last_reviewed` only for docs whose content was actually reviewed, or treat the failure as genuine staleness. diff --git a/server/README.md b/server/README.md index 2c18f5c..cc0b97a 100644 --- a/server/README.md +++ b/server/README.md @@ -14,6 +14,35 @@ uvicorn app.main:app --reload --host 127.0.0.1 --port 8080 ``` +## PostgreSQL storage (Phase 1) + +The read path can be served from PostgreSQL instead of files: + +```bash +# From the repository root: start a local development cluster on 127.0.0.1:5433 +./scripts/dev-db.sh start + +cd server +export GNEXUS_BOOK_DATABASE_URL="$(../scripts/dev-db.sh url)" +.venv/bin/alembic upgrade head +.venv/bin/python -m app.storage.cli import --replace +.venv/bin/python -m app.storage.cli parity + +GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005 +``` + +- The default backend is `file`; set `GNEXUS_BOOK_STORAGE_BACKEND=db` to use PostgreSQL. +- `import --replace` re-imports the current repository; `parity` compares file and + database read results and exits non-zero on a difference. +- `scripts/backup-db.sh` writes a custom-format dump to the off-host NFS by default; + `scripts/restore-db.sh` requires `GNEXUS_BOOK_RESTORE_YES=1` before replacing data. +- Phase 1 scope: documents, inventory, and relationships are read from PostgreSQL. + Document writes are blocked in database mode until Phase 2; validation and freshness + still read files until Phase 3. +- Database tests use `GNEXUS_BOOK_TEST_DATABASE_URL` (default + `postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test`) and are skipped when + PostgreSQL is unavailable. + ## MCP Server The MCP server exposes the same repository, inventory, validation, pending-change, and Git commit logic through MCP tools and resources.