diff --git a/server/app/main.py b/server/app/main.py index 25ac2a7..c40202d 100644 --- a/server/app/main.py +++ b/server/app/main.py @@ -10,15 +10,27 @@ from .freshness import build_freshness_report from .git_adapter import CommitRequest, GitAdapter, GitAdapterError from .inventory import InventoryError -from .pending_changes import ( - PendingChangeError, - PendingChangeRepository, - ProposedChangeRequest, -) +from .pending_changes import PendingChangeError, ProposedChangeRequest from .relationships import build_relationships from .storage.db import Database -from .storage.factory import make_docs_repository, make_inventory_repository -from .storage.protocols import DocsRepositoryProtocol, InventoryRepositoryProtocol +from .storage.documents import ( + DocumentError, + diff_document_versions, + get_document_version, + list_document_versions, + restore_document_version, +) +from .storage.factory import ( + make_docs_repository, + make_inventory_repository, + make_pending_change_repository, +) +from .storage.protocols import ( + DocsRepositoryProtocol, + InventoryRepositoryProtocol, + PendingChangeRepositoryProtocol, +) +from .storage.validation import validate_database from .validation import validate_repository @@ -40,8 +52,10 @@ return make_inventory_repository(settings) -def get_pending_change_repo(settings: Settings = Depends(get_settings)) -> PendingChangeRepository: - return PendingChangeRepository(settings) +def get_pending_change_repo( + settings: Settings = Depends(get_settings), +) -> PendingChangeRepositoryProtocol: + return make_pending_change_repository(settings, via="api") def get_git_adapter(settings: Settings = Depends(get_settings)) -> GitAdapter: @@ -85,6 +99,71 @@ return repo.search(q) +@app.get("/documents/{path:path}/history") +def document_history( + path: str, settings: Settings = Depends(get_settings) +) -> list[dict[str, object]]: + if settings.storage_backend != "db": + raise HTTPException(status_code=400, detail="Document history is available in database mode") + try: + return list_document_versions(Database.from_settings(settings), path) + except DocumentError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + + +@app.get("/documents/{path:path}/versions/{version_no}") +def document_version( + path: str, version_no: int, settings: Settings = Depends(get_settings) +) -> dict[str, object]: + if settings.storage_backend != "db": + raise HTTPException(status_code=400, detail="Document versions are available in database mode") + try: + return get_document_version(Database.from_settings(settings), path, version_no) + except DocumentError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + + +@app.get("/documents/{path:path}/diff") +def document_diff( + path: str, + from_version: int | None = Query(default=None, alias="from"), + to_version: int | None = Query(default=None, alias="to"), + settings: Settings = Depends(get_settings), +) -> dict[str, object]: + if settings.storage_backend != "db": + raise HTTPException(status_code=400, detail="Document diff is available in database mode") + try: + return diff_document_versions( + Database.from_settings(settings), path, from_version, to_version + ) + except DocumentError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + + +@app.post("/documents/{path:path}/restore/{version_no}") +def document_restore( + path: str, + version_no: int, + summary: str | None = Query(default=None), + settings: Settings = Depends(get_settings), +) -> dict[str, object]: + if settings.storage_backend != "db": + raise HTTPException(status_code=400, detail="Document restore is available in database mode") + try: + return restore_document_version( + Database.from_settings(settings), + settings, + path, + version_no, + summary=summary, + via="api", + ) + except DocumentError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + except PendingChangeError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + + @app.get("/inventory") def list_inventory_types(repo: InventoryRepositoryProtocol = Depends(get_inventory_repo)) -> list[str]: return repo.list_types() @@ -139,18 +218,22 @@ @app.get("/validate") def validate(settings: Settings = Depends(get_settings)) -> dict[str, object]: + if settings.storage_backend == "db": + return validate_database(Database.from_settings(settings)) return validate_repository(settings) @app.get("/changes") -def list_changes(repo: PendingChangeRepository = Depends(get_pending_change_repo)) -> list[dict[str, object]]: +def list_changes( + repo: PendingChangeRepositoryProtocol = Depends(get_pending_change_repo), +) -> list[dict[str, object]]: return repo.list() @app.get("/changes/{change_id}") def read_change( change_id: str, - repo: PendingChangeRepository = Depends(get_pending_change_repo), + repo: PendingChangeRepositoryProtocol = Depends(get_pending_change_repo), ) -> dict[str, object]: try: return repo.get(change_id) @@ -161,7 +244,7 @@ @app.post("/changes") def propose_change( request: ProposedChangeRequest, - repo: PendingChangeRepository = Depends(get_pending_change_repo), + repo: PendingChangeRepositoryProtocol = Depends(get_pending_change_repo), ) -> dict[str, object]: return repo.create(request) @@ -169,7 +252,7 @@ @app.post("/changes/{change_id}/apply") def apply_change( change_id: str, - repo: PendingChangeRepository = Depends(get_pending_change_repo), + repo: PendingChangeRepositoryProtocol = Depends(get_pending_change_repo), ) -> dict[str, object]: try: return repo.apply(change_id) diff --git a/server/app/mcp_server.py b/server/app/mcp_server.py index 048ace0..8fc4e82 100644 --- a/server/app/mcp_server.py +++ b/server/app/mcp_server.py @@ -11,9 +11,21 @@ from .config import Settings from .freshness import build_freshness_report from .git_adapter import CommitRequest, GitAdapter -from .pending_changes import PendingChangeRepository, ProposedChangeRequest +from .pending_changes import ProposedChangeRequest from .relationships import build_relationships -from .storage.factory import make_docs_repository, make_inventory_repository +from .storage.db import Database +from .storage.documents import ( + diff_document_versions, + get_document_version, + list_document_versions, + restore_document_version as restore_document_version_service, +) +from .storage.factory import ( + make_docs_repository, + make_inventory_repository, + make_pending_change_repository, +) +from .storage.validation import validate_database from .validation import validate_repository @@ -54,6 +66,11 @@ - Only after the document exists should you propose the inventory item with the `docs` path. - Never use local filesystem tools to edit gnexus-book repository files directly — always use the MCP tools. +Storage mode: +- In database mode, apply_pending_change publishes a changeset transactionally; commit_changes is a no-op. +- Use document_history, document_version, document_diff, and restore_document_version for version work. +- Restoring a version creates a new version; it never rewrites history. + For propose_inventory_item_change, pass concrete top-level arguments, not a wrapper: inventory_type="hosts", item_id="bserv", mode="create", patch={"ip_address": "192.168.1.130", "user": "bserv"}, summary="Document bserv host". The patch object is the inventory item fields to create or update. @@ -113,6 +130,10 @@ - For create mode, patch is the new inventory item fields. - For update mode, patch is the fields to merge into the existing item. +Storage mode: +- In database mode, apply_pending_change publishes; commit_changes is a no-op. +- Use document_history, document_version, document_diff, and restore_document_version for version work. + Do document: - hostnames, usernames, IPs, domains, ports, routes, access models, credential references, versions, repository activity. @@ -139,8 +160,8 @@ return make_inventory_repository(_settings()) -def _pending() -> PendingChangeRepository: - return PendingChangeRepository(_settings()) +def _pending(): + return make_pending_change_repository(_settings(), via="mcp") def _git() -> GitAdapter: @@ -190,8 +211,11 @@ def validate_repository_tool() -> dict[str, object]: - """Validate schemas, docs, inventory links, duplicate ids, and raw secret patterns before trusting or committing changes.""" - return validate_repository(_settings()) + """Validate schemas, docs, duplicate ids, and raw secret patterns before trusting or committing changes.""" + settings = _settings() + if settings.storage_backend == "db": + return validate_database(Database.from_settings(settings)) + return validate_repository(settings) def check_freshness() -> dict[str, object]: @@ -257,6 +281,12 @@ def commit_changes(summary: str, files: list[str], details: str = "") -> dict[str, Any]: """Validate the repository and create a local Git commit for selected documentation files.""" + settings = _settings() + if settings.storage_backend == "db": + return { + "status": "noop", + "detail": "Database mode publishes changes when a changeset is applied; there is nothing to commit.", + } return _git().commit(CommitRequest(summary=summary, details=details, files=files)) @@ -264,11 +294,66 @@ """For simple full-document updates: create pending change, apply, validate, and commit in one call.""" change = propose_doc_change(path=path, content=content, summary=summary, reason=reason) applied = apply_pending_change(str(change["id"])) + if _settings().storage_backend == "db": + return { + "change": applied, + "commit": { + "status": "applied", + "detail": "Database mode publishes the changeset on apply.", + }, + } pending_path = f"90-maintenance/pending-changes/{change['id']}.json" commit = commit_changes(summary=summary, files=[path, pending_path], details=reason) return {"change": applied, "commit": commit} +def document_history(path: str) -> list[dict[str, Any]]: + """List document versions with author, actor, changeset, and summary metadata.""" + settings = _settings() + if settings.storage_backend != "db": + raise RuntimeError("Document history is available in database mode") + return list_document_versions(Database.from_settings(settings), path) + + +def document_version(path: str, version_no: int) -> dict[str, Any]: + """Read one document version by path and version number.""" + settings = _settings() + if settings.storage_backend != "db": + raise RuntimeError("Document versions are available in database mode") + return get_document_version(Database.from_settings(settings), path, version_no) + + +def document_diff( + path: str, + from_version: int | None = None, + to_version: int | None = None, +) -> dict[str, Any]: + """Show a unified diff between two document versions; defaults to the latest pair.""" + settings = _settings() + if settings.storage_backend != "db": + raise RuntimeError("Document diff is available in database mode") + return diff_document_versions( + Database.from_settings(settings), path, from_version, to_version + ) + + +def restore_document_version( + path: str, version_no: int, summary: str = "" +) -> dict[str, Any]: + """Restore a document by creating a new version with the content of an older version.""" + settings = _settings() + if settings.storage_backend != "db": + raise RuntimeError("Document restore is available in database mode") + return restore_document_version_service( + Database.from_settings(settings), + settings, + path, + version_no, + summary=summary or None, + via="mcp", + ) + + mcp = FastMCP( "gnexus-book", instructions=MCP_INSTRUCTIONS, @@ -292,6 +377,10 @@ mcp.tool(name="apply_pending_change")(apply_pending_change) mcp.tool(name="commit_changes")(commit_changes) mcp.tool(name="update_doc")(update_doc) +mcp.tool(name="document_history")(document_history) +mcp.tool(name="document_version")(document_version) +mcp.tool(name="document_diff")(document_diff) +mcp.tool(name="restore_document_version")(restore_document_version) @mcp.resource("gnexus-book://docs", mime_type="application/json") diff --git a/server/app/storage/documents.py b/server/app/storage/documents.py new file mode 100644 index 0000000..83b1b95 --- /dev/null +++ b/server/app/storage/documents.py @@ -0,0 +1,168 @@ +from __future__ import annotations + +import difflib +from datetime import datetime +from typing import Any + +from sqlalchemy import select +from sqlalchemy.orm import Session + +from ..config import Settings +from ..pending_changes import ProposedChangeRequest +from .db import Database +from .models import Changeset, DocVersion, Document +from .pending_changes_db import PostgresPendingChangeRepository + + +class DocumentError(ValueError): + pass + + +def _iso(value: datetime | None) -> str | None: + if value is None: + return None + return value.isoformat().replace("+00:00", "Z") + + +def _find_document(session: Session, path: str) -> Document: + document = session.scalars(select(Document).where(Document.slug == path)).first() + if document is None or document.deleted_at is not None: + raise DocumentError("Document not found") + return document + + +def _find_version(session: Session, document_id, version_no: int) -> DocVersion: + version = session.scalars( + select(DocVersion).where( + DocVersion.document_id == document_id, + DocVersion.version_no == version_no, + ) + ).first() + if version is None: + raise DocumentError("Document version not found") + return version + + +def list_document_versions(database: Database, path: str) -> list[dict[str, Any]]: + with database.session() as session: + document = _find_document(session, path) + versions = session.scalars( + select(DocVersion) + .where(DocVersion.document_id == document.id) + .order_by(DocVersion.version_no) + ).all() + + result: list[dict[str, Any]] = [] + for version in versions: + changeset = ( + session.get(Changeset, version.changeset_id) + if version.changeset_id + else None + ) + result.append( + { + "path": document.slug, + "version_no": version.version_no, + "content_hash": version.content_hash, + "created_at": _iso(version.created_at), + "actor_kind": version.actor_kind, + "actor_name": version.actor_name, + "via": version.via, + "changeset_id": str(version.changeset_id) if version.changeset_id else None, + "summary": changeset.summary if changeset else None, + } + ) + return result + + +def get_document_version(database: Database, path: str, version_no: int) -> dict[str, Any]: + with database.session() as session: + document = _find_document(session, path) + version = _find_version(session, document.id, version_no) + changeset = ( + session.get(Changeset, version.changeset_id) if version.changeset_id else None + ) + return { + "path": document.slug, + "version_no": version.version_no, + "raw": version.raw, + "body": version.body, + "frontmatter": dict(version.frontmatter or {}), + "content_hash": version.content_hash, + "created_at": _iso(version.created_at), + "actor_kind": version.actor_kind, + "actor_name": version.actor_name, + "via": version.via, + "changeset_id": str(version.changeset_id) if version.changeset_id else None, + "summary": changeset.summary if changeset else None, + } + + +def diff_document_versions( + database: Database, + path: str, + from_version: int | None = None, + to_version: int | None = None, +) -> dict[str, Any]: + with database.session() as session: + document = _find_document(session, path) + versions = session.scalars( + select(DocVersion) + .where(DocVersion.document_id == document.id) + .order_by(DocVersion.version_no) + ).all() + if not versions: + raise DocumentError("Document has no versions") + + latest_no = versions[-1].version_no + target_no = latest_no if to_version is None else to_version + if from_version is None: + source_no = max(1, target_no - 1) + else: + source_no = from_version + + if source_no < 1 or target_no < 1: + raise DocumentError("Version numbers must be positive") + + source = _find_version(session, document.id, source_no) + target = _find_version(session, document.id, target_no) + + diff_lines = difflib.unified_diff( + source.raw.splitlines(), + target.raw.splitlines(), + fromfile=f"{path}@v{source_no}", + tofile=f"{path}@v{target_no}", + lineterm="", + ) + return { + "path": path, + "from_version": source_no, + "to_version": target_no, + "diff": "\n".join(diff_lines), + } + + +def restore_document_version( + database: Database, + settings: Settings, + path: str, + version_no: int, + summary: str | None = None, + via: str = "api", +) -> dict[str, Any]: + with database.session() as session: + document = _find_document(session, path) + version = _find_version(session, document.id, version_no) + raw = version.raw + + repository = PostgresPendingChangeRepository(database, settings, via=via) + change = repository.create( + ProposedChangeRequest( + kind="doc", + target=path, + summary=summary or f"Restore {path} to version {version_no}", + reason=f"Restore version {version_no}", + payload={"content": raw}, + ) + ) + return repository.apply(change["id"])