codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/prompts/operations/garden.md

@@ -0,0 +1,26 @@
+# Garden Operation
+
+Garden improves the existing configured Almanac wiki as a whole graph.
+
+Before editing, read `manual/README.md`, `manual/pages.md`,
+`manual/evidence.md`, `manual/style.md`, `manual/sources.md`, and
+`manual/garden.md` under the configured Almanac root.
+
+Garden is cultivation. The goal is not to add activity; the goal is to make the
+project memory more coherent, navigable, current, and trustworthy.
+
+Inspect pages, topics, links, referenced files, and health issues where useful.
+Look for duplicate pages, stale claims, missing anchors, missing links, bloated
+pages, confusing topics, unsupported claims, disconnected temporal notes, and
+clusters that need hubs.
+
+Prefer synthesis over logs. Fold fragments into evolving pages when chronology
+is not part of the meaning. Split pages that contain independent concepts.
+Merge overlapping pages when one page is the better home. Archive or supersede
+stale pages only when preserving history helps future agents.
+
+Improve topic neighborhoods, leads, links, source notes, and page boundaries.
+Create or revise hub pages when a dense cluster needs reading order.
+
+No-op is valid when the wiki is already coherent enough for the current pass.
+Do not churn unrelated pages to show activity.

codealmanac/prompts/operations/ingest.md

@@ -0,0 +1,18 @@
+# Ingest Operation
+
+Ingest starts from bounded selected material and distills reusable project
+understanding into the existing configured Almanac graph.
+
+Before editing, read `manual/README.md`, `manual/pages.md`,
+`manual/evidence.md`, `manual/style.md`, `manual/sources.md`, and
+`manual/ingest.md` under the configured Almanac root.
+
+Use the source briefs and source runtime snapshots in the runtime context as
+operation input. The brief identifies the selected source and its provenance
+hint. The runtime snapshot is readable source material gathered before the
+agent run. Update existing synthesis pages when they are the right home. Create
+new pages only when the material names a durable concept, decision, flow,
+invariant, incident, gotcha, or project-world fact that deserves its own page.
+
+Preserve the source-selection boundary. The selected material is raw material,
+not the source of truth for every claim.

codealmanac/prompts/renderer.py

@@ -0,0 +1,24 @@
+from importlib.resources import files
+
+from codealmanac.prompts.models import PromptName
+from codealmanac.prompts.requests import RenderPromptRequest
+
+PROMPTS_PACKAGE = "codealmanac.prompts"
+
+
+class PromptRenderer:
+    def render(self, request: RenderPromptRequest) -> str:
+        sections = [prompt_text(section) for section in request.sections]
+        sections.extend(request.context)
+        return join_prompt_sections(tuple(sections))
+
+
+def prompt_text(name: PromptName) -> str:
+    resource = files(PROMPTS_PACKAGE).joinpath(*name.value.split("/"))
+    return resource.read_text(encoding="utf-8").strip()
+
+
+def join_prompt_sections(sections: tuple[str, ...]) -> str:
+    return "\n\n---\n\n".join(
+        section.strip() for section in sections if section.strip()
+    )

codealmanac/prompts/requests.py

@@ -0,0 +1,22 @@
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+from codealmanac.prompts.models import PromptName
+
+
+class RenderPromptRequest(CodeAlmanacModel):
+    sections: tuple[PromptName, ...]
+    context: tuple[str, ...] = ()
+
+    @field_validator("sections")
+    @classmethod
+    def require_sections(cls, value: tuple[PromptName, ...]) -> tuple[PromptName, ...]:
+        if len(value) == 0:
+            raise ValueError("at least one prompt section is required")
+        return value
+
+    @field_validator("context")
+    @classmethod
+    def require_context_text(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return tuple(required_text(item, "prompt context") for item in value)

codealmanac/server/__init__.py

@@ -0,0 +1 @@
+"""Local read-only web server adapter."""

codealmanac/server/app.py

@@ -0,0 +1,202 @@
+from enum import StrEnum
+from importlib import resources
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse, Response
+from pydantic import BaseModel, ConfigDict, ValidationError, field_validator
+
+from codealmanac.app import CodeAlmanac
+from codealmanac.core.errors import CodeAlmanacError, ConflictError, NotFoundError
+from codealmanac.services.viewer.models import (
+    ViewerFile,
+    ViewerOverview,
+    ViewerPage,
+    ViewerSearch,
+    ViewerTopic,
+)
+from codealmanac.services.viewer.requests import (
+    ViewerFileRequest,
+    ViewerOverviewRequest,
+    ViewerPageRequest,
+    ViewerSearchRequest,
+    ViewerTopicRequest,
+)
+
+
+class ServerAssetSuffix(StrEnum):
+    HTML = ".html"
+    CSS = ".css"
+    JAVASCRIPT = ".js"
+
+
+ASSET_MEDIA_TYPES: dict[ServerAssetSuffix, str] = {
+    ServerAssetSuffix.HTML: "text/html",
+    ServerAssetSuffix.CSS: "text/css",
+    ServerAssetSuffix.JAVASCRIPT: "text/javascript",
+}
+
+
+class ServerAssetRequest(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    path: str
+
+    @field_validator("path")
+    @classmethod
+    def validate_path(cls, value: str) -> str:
+        if value != value.strip():
+            raise ValueError("asset path must not contain surrounding whitespace")
+        if not value:
+            raise ValueError("asset path is required")
+        if value.startswith("/") or "\\" in value:
+            raise ValueError("asset path must be relative")
+        parts = value.split("/")
+        if any(part in {"", ".", ".."} for part in parts):
+            raise ValueError("asset path contains an invalid segment")
+        suffix = Path(value).suffix
+        if suffix not in {item.value for item in ServerAssetSuffix}:
+            raise ValueError("asset path has an unsupported extension")
+        return value
+
+    @property
+    def media_type(self) -> str:
+        return ASSET_MEDIA_TYPES[ServerAssetSuffix(Path(self.path).suffix)]
+
+    @property
+    def parts(self) -> list[str]:
+        return self.path.split("/")
+
+
+def create_server_app(
+    codealmanac: CodeAlmanac,
+    cwd: Path,
+    wiki: str | None = None,
+) -> FastAPI:
+    server = FastAPI(title="CodeAlmanac Local Viewer")
+
+    @server.get("/api/overview", response_model=ViewerOverview)
+    def overview() -> ViewerOverview:
+        try:
+            return codealmanac.viewer.overview(
+                ViewerOverviewRequest(cwd=cwd, wiki=wiki)
+            )
+        except ValidationError as error:
+            raise validation_error(error) from error
+        except CodeAlmanacError as error:
+            raise http_error(error) from error
+
+    @server.get("/api/page/{slug}", response_model=ViewerPage)
+    def page(slug: str) -> ViewerPage:
+        try:
+            return codealmanac.viewer.page(
+                ViewerPageRequest(cwd=cwd, wiki=wiki, slug=slug)
+            )
+        except ValidationError as error:
+            raise validation_error(error) from error
+        except CodeAlmanacError as error:
+            raise http_error(error) from error
+
+    @server.get("/api/search", response_model=ViewerSearch)
+    def search(q: str | None = None, limit: int = 50) -> ViewerSearch:
+        try:
+            return codealmanac.viewer.search(
+                ViewerSearchRequest(cwd=cwd, wiki=wiki, query=q, limit=limit)
+            )
+        except ValidationError as error:
+            raise validation_error(error) from error
+        except CodeAlmanacError as error:
+            raise http_error(error) from error
+
+    @server.get("/api/file", response_model=ViewerFile)
+    def file(path: str, limit: int = 50) -> ViewerFile:
+        try:
+            return codealmanac.viewer.file(
+                ViewerFileRequest(cwd=cwd, wiki=wiki, path=path, limit=limit)
+            )
+        except ValidationError as error:
+            raise validation_error(error) from error
+        except CodeAlmanacError as error:
+            raise http_error(error) from error
+
+    @server.get("/api/topic/{slug}", response_model=ViewerTopic)
+    def topic(slug: str, descendants: bool = False) -> ViewerTopic:
+        try:
+            return codealmanac.viewer.topic(
+                ViewerTopicRequest(
+                    cwd=cwd,
+                    wiki=wiki,
+                    slug=slug,
+                    include_descendants=descendants,
+                )
+            )
+        except ValidationError as error:
+            raise validation_error(error) from error
+        except CodeAlmanacError as error:
+            raise http_error(error) from error
+
+    @server.get("/", include_in_schema=False)
+    def index() -> HTMLResponse:
+        return HTMLResponse(read_asset_text(ServerAssetRequest(path="index.html")))
+
+    @server.get("/app.js", include_in_schema=False)
+    def app_js() -> Response:
+        return asset_response("app.js")
+
+    @server.get("/app.css", include_in_schema=False)
+    def app_css() -> Response:
+        return asset_response("app.css")
+
+    @server.get("/assets/{asset_path:path}", include_in_schema=False)
+    def static_asset(asset_path: str) -> Response:
+        return asset_response(asset_path)
+
+    @server.get("/{path:path}", include_in_schema=False)
+    def fallback(path: str) -> HTMLResponse:
+        if path.startswith("api/"):
+            raise HTTPException(status_code=404, detail="not found")
+        return HTMLResponse(read_asset_text(ServerAssetRequest(path="index.html")))
+
+    return server
+
+
+def asset_response(asset_path: str) -> Response:
+    try:
+        request = ServerAssetRequest(path=asset_path)
+        return Response(
+            read_asset_text(request),
+            media_type=request.media_type,
+        )
+    except ValidationError as error:
+        raise validation_error(error) from error
+    except FileNotFoundError as error:
+        raise HTTPException(
+            status_code=404,
+            detail={"code": "not_found", "message": f"asset not found: {asset_path}"},
+        ) from error
+
+
+def read_asset_text(request: ServerAssetRequest) -> str:
+    asset = resources.files("codealmanac.server.assets").joinpath(*request.parts)
+    if not asset.is_file():
+        raise FileNotFoundError(request.path)
+    return asset.read_text(encoding="utf-8")
+
+
+def http_error(error: CodeAlmanacError) -> HTTPException:
+    status_code = 400
+    if isinstance(error, NotFoundError):
+        status_code = 404
+    elif isinstance(error, ConflictError):
+        status_code = 409
+    return HTTPException(
+        status_code=status_code,
+        detail={"code": error.code, "message": str(error)},
+    )
+
+
+def validation_error(error: ValidationError) -> HTTPException:
+    return HTTPException(
+        status_code=422,
+        detail={"code": "validation_failed", "message": str(error)},
+    )

codealmanac/server/assets/__init__.py

@@ -0,0 +1 @@
+"""Static assets bundled with the local viewer."""