Newer
Older
gnexus-book / CLAUDE.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 9 hours ago 12 KB docs: document data ownership rollout

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

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). Production agents use streamable HTTP at /mcp-protocol/ with a personal mcp_* key:

cd server
GNEXUS_BOOK_MCP_HOST=0.0.0.0 GNEXUS_BOOK_MCP_PORT=8001 .venv/bin/python -m app.mcp_http

Keys are managed through /mcp-keys (session) and /internal/keys (service secret, blocked by nginx); mcp_tokens stores only a SHA-256 hash and a tail hint, never plaintext. Behind nginx, set GNEXUS_BOOK_MCP_ALLOWED_HOSTS/_ORIGINS to the public hostname and origin or FastMCP returns 421.

PostgreSQL read backend (Phase 1)

# 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
.venv/bin/python -m app.storage.cli migrate --replace --manifest /tmp/report.json
.venv/bin/python -m app.storage.cli assign-owner --user-json /tmp/owner.json
.venv/bin/python -m app.storage.cli ownership

# Rehearsed/real cutover and rollback verification
../scripts/cutover-db.sh --replace
../scripts/rollback-cutover.sh

GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005

# Local stack with database storage and gnexus-auth (loads server/.env)
../scripts/dev-server.sh
../scripts/dev-mcp.sh

# Operations
../scripts/backup-db.sh
../scripts/restore-drill.sh
GNEXUS_BOOK_HEALTH_URL=http://127.0.0.1:3005/health ../scripts/healthcheck.sh

gnexus-book-backup.timer runs the off-host dump daily; the restore-drill timer is installed but disabled until a manual drill passes. Synapse alerts use SYNAPSE_URL/SYNAPSE_API_KEY. See 30-runbooks/postgres-operations.md.

server/.env is gitignored and holds the local database URL, OAuth client, webhook secret and internal key secret; systemd loads it through EnvironmentFile. Local SSO details are in 30-runbooks/local-auth-testing.md.

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

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)

./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/<type>.yml; each file is a YAML list and items are looked up by id.
  • relationships.py — builds a graph whose node ids are <inventory-type>/<id> 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).
  • auth/ — gnexus-auth integration: OAuth 2.0 PKCE login/callback, hashed browser sessions, user mirror, HMAC webhook handling, a pure-ASGI session guard, personal MCP key management (mcp_keys.py, mcp_routes.py), the MCP bearer guard (mcp_guard.py), and the actor context used by writes. Authentication is disabled unless GNEXUS_BOOK_AUTH_CLIENT_ID, ..._CLIENT_SECRET, ..._BASE_URL, and ..._REDIRECT_URI are set; disabled mode is intentional for local development. The guard exempts /health, /me, /auth/*, and /webhooks/gnexus-auth*. The gnexus-gauth client library is a pinned git dependency.
  • 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 read interfaces, pending_changes_db.py implements draft/apply changesets transactionally, documents.py provides history/version/diff/restore, validation.py validates the database, importer.py copies the repository into PostgreSQL, parity.py compares both backends, and cli.py exposes import, parity, and counts. factory.py selects docs/inventory/pending repositories from GNEXUS_BOOK_STORAGE_BACKEND. Alembic lives in server/alembic/. In db mode all knowledge writes go through changesets; commit_changes is a no-op. Validation, freshness, and relationships use the selected backend.

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/<type>.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 frontend is a single Vue 3 app in ui/src/main.js (no router). It uses a drawer shell with pages: docs (search, history, diff, proposals), inventory (JSON/raw), changes (apply), status, MCP keys, and settings. ui/src/i18n/ holds flat en/uk/ru dictionaries; navigation labels must be computed because t() reads the reactive locale. The auth gate calls /api/me; sign-in redirects through /api/auth/login, and gnexus-auth returns to /auth/callback (Vite proxies /auth and /webhooks, nginx proxies them in production). All data goes through /api. 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_db_storage.py covers read parity, tests/test_db_changesets.py covers versioning/changesets/history/diff/restore, tests/test_auth.py covers login, sessions, /me, the route guard and signed webhooks with mocked gnexus-auth HTTP calls, tests/test_mcp_keys.py covers internal provisioning, the user key API, the MCP bearer guard, rate limits, actor selection and key revocation on user block, and 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.