codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/integrations/updates/package.py

@@ -0,0 +1,85 @@
+import json
+import subprocess
+from importlib.metadata import PackageNotFoundError, distribution
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.updates.models import (
+    PACKAGE_NAME,
+    PackageCommandResult,
+    PackageInstallMetadata,
+)
+
+
+class InstalledPackageMetadataProvider:
+    def read(self) -> PackageInstallMetadata:
+        try:
+            package = distribution(PACKAGE_NAME)
+        except PackageNotFoundError:
+            return PackageInstallMetadata(
+                version="unknown",
+                installer=None,
+                editable=False,
+                source_url=None,
+            )
+        direct_url = read_direct_url(package.read_text("direct_url.json"))
+        return PackageInstallMetadata(
+            version=package.version,
+            installer=clean_optional_text(package.read_text("INSTALLER")),
+            editable=direct_url.editable,
+            source_url=direct_url.source_url,
+        )
+
+
+class SubprocessPackageCommandRunner:
+    def run(self, command: tuple[str, ...]) -> PackageCommandResult:
+        try:
+            result = subprocess.run(
+                command,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+        except OSError as error:
+            return PackageCommandResult(
+                exit_code=1,
+                stderr=f"{error.__class__.__name__}: {error}",
+            )
+        return PackageCommandResult(
+            exit_code=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+        )
+
+
+class DirectUrlMetadata(CodeAlmanacModel):
+    editable: bool = False
+    source_url: str | None = None
+
+
+def read_direct_url(raw: str | None) -> DirectUrlMetadata:
+    if raw is None:
+        return DirectUrlMetadata()
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return DirectUrlMetadata()
+    if not isinstance(payload, dict):
+        return DirectUrlMetadata()
+    dir_info = payload.get("dir_info")
+    editable = False
+    if isinstance(dir_info, dict):
+        editable = dir_info.get("editable") is True
+    url = payload.get("url")
+    return DirectUrlMetadata(
+        editable=editable,
+        source_url=url if isinstance(url, str) and url.strip() else None,
+    )
+
+
+def clean_optional_text(value: str | None) -> str | None:
+    if value is None:
+        return None
+    cleaned = value.strip()
+    if cleaned == "":
+        return None
+    return cleaned

codealmanac/integrations/workspaces/__init__.py

@@ -0,0 +1 @@
+"""Concrete workspace-state integrations."""

codealmanac/integrations/workspaces/git/__init__.py

@@ -0,0 +1,3 @@
+from codealmanac.integrations.workspaces.git.probe import GitWorkspaceChangeProbe
+
+__all__ = ["GitWorkspaceChangeProbe"]

codealmanac/integrations/workspaces/git/probe.py

@@ -0,0 +1,128 @@
+import hashlib
+import subprocess
+from pathlib import Path
+
+from codealmanac.services.workspaces.models import (
+    WorkspaceChangeSnapshot,
+    WorkspacePathChange,
+    WorkspacePathState,
+)
+
+GIT_STATUS_TIMEOUT_SECONDS = 10
+
+
+class GitWorkspaceChangeProbe:
+    def snapshot(self, root_path: Path) -> WorkspaceChangeSnapshot:
+        try:
+            completed = subprocess.run(
+                (
+                    "git",
+                    "-C",
+                    str(root_path),
+                    "status",
+                    "--porcelain=v1",
+                    "-z",
+                    "--untracked-files=all",
+                ),
+                text=True,
+                capture_output=True,
+                timeout=GIT_STATUS_TIMEOUT_SECONDS,
+                check=False,
+            )
+        except FileNotFoundError:
+            return unavailable_snapshot(root_path, "git not found on PATH")
+        except subprocess.TimeoutExpired:
+            return unavailable_snapshot(root_path, "git status timed out")
+        if completed.returncode != 0:
+            return unavailable_snapshot(
+                root_path,
+                first_line(completed.stderr, completed.stdout)
+                or f"git status exited {completed.returncode}",
+            )
+        return WorkspaceChangeSnapshot(
+            root_path=root_path,
+            available=True,
+            changes=tuple(
+                change_with_fingerprint(root_path, change)
+                for change in parse_git_status(completed.stdout)
+            ),
+        )
+
+
+def unavailable_snapshot(root_path: Path, reason: str) -> WorkspaceChangeSnapshot:
+    return WorkspaceChangeSnapshot(
+        root_path=root_path,
+        available=False,
+        unavailable_reason=reason,
+    )
+
+
+def parse_git_status(value: str) -> tuple[WorkspacePathChange, ...]:
+    changes: list[WorkspacePathChange] = []
+    fields = [field for field in value.split("\0") if field]
+    skip_next = False
+    for field in fields:
+        if skip_next:
+            skip_next = False
+            continue
+        if len(field) < 4:
+            continue
+        status = field[:2]
+        path = Path(field[3:])
+        changes.append(
+            WorkspacePathChange(
+                path=path,
+                state=state_from_status(status),
+                status=status,
+            )
+        )
+        if "R" in status or "C" in status:
+            skip_next = True
+    return tuple(changes)
+
+
+def state_from_status(status: str) -> WorkspacePathState:
+    if "?" in status:
+        return WorkspacePathState.UNTRACKED
+    if "U" in status:
+        return WorkspacePathState.UNMERGED
+    if "R" in status:
+        return WorkspacePathState.RENAMED
+    if "C" in status:
+        return WorkspacePathState.COPIED
+    if "D" in status:
+        return WorkspacePathState.DELETED
+    if "A" in status:
+        return WorkspacePathState.ADDED
+    if "M" in status:
+        return WorkspacePathState.MODIFIED
+    if "T" in status:
+        return WorkspacePathState.TYPE_CHANGED
+    return WorkspacePathState.UNKNOWN
+
+
+def change_with_fingerprint(
+    root_path: Path,
+    change: WorkspacePathChange,
+) -> WorkspacePathChange:
+    return change.model_copy(
+        update={"fingerprint": file_fingerprint(root_path / change.path)}
+    )
+
+
+def file_fingerprint(path: Path) -> str | None:
+    if not path.is_file():
+        return None
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def first_line(*values: str) -> str:
+    for value in values:
+        lines = [line.strip() for line in value.splitlines() if line.strip()]
+        if lines:
+            return lines[0]
+    return ""

codealmanac/manual/README.md

@@ -0,0 +1,24 @@
+---
+title: Manual Overview
+topics: []
+---
+
+# Manual Overview
+
+This manual defines how agents maintain a CodeAlmanac repo-owned wiki.
+
+Prompts name the job. The manual defines the writing rules, evidence bar, page
+shape, and operation-specific workflow.
+
+Read the relevant page before editing:
+
+- `pages.md`: what deserves a page and how pages connect.
+- `evidence.md`: how claims stay grounded and how conflicts are handled.
+- `style.md`: how CodeAlmanac prose should read.
+- `sources.md`: how raw material relates to wiki synthesis.
+- `build.md`: how to create the first useful wiki.
+- `ingest.md`: how to fold new material into an existing wiki.
+- `garden.md`: how to improve an existing wiki graph.
+
+Repo-specific conventions live in `README.md` and `topics.yaml` under the
+configured Almanac root.

codealmanac/manual/__init__.py

@@ -0,0 +1,19 @@
+from codealmanac.manual.library import ManualLibrary
+from codealmanac.manual.models import (
+    ManualDocument,
+    ManualDocumentName,
+    ManualInstallResult,
+    ManualInventory,
+    ManualWorkspaceStatus,
+)
+from codealmanac.manual.requests import ManualReadRequest
+
+__all__ = [
+    "ManualDocument",
+    "ManualDocumentName",
+    "ManualInstallResult",
+    "ManualInventory",
+    "ManualLibrary",
+    "ManualReadRequest",
+    "ManualWorkspaceStatus",
+]

codealmanac/manual/build.md

@@ -0,0 +1,20 @@
+---
+title: Build
+topics: [manual]
+---
+
+# Build
+
+Build creates or refreshes the initial scaffold under the configured Almanac
+root for a repo.
+
+The goal is a usable local wiki, not a file-tree summary. A thin starter page is
+acceptable at initialization, but the first real build should create a reading
+path through durable subjects.
+
+Before writing substantive pages, read `manual/README.md`, `manual/pages.md`,
+`manual/evidence.md`, `manual/style.md`, and the repo-specific `README.md`
+under the configured Almanac root.
+
+A build is useful when a future agent can understand the repo faster from the
+wiki than by rediscovering context from raw files and old conversations.

codealmanac/manual/evidence.md

@@ -0,0 +1,23 @@
+---
+title: Evidence
+topics: [manual]
+---
+
+# Evidence
+
+Every durable claim needs grounding in code, docs, transcripts, PRs, local
+commands, or another named source.
+
+Authority depends on the claim:
+
+- Code is authoritative for runtime behavior.
+- Transcripts are authoritative for what was discussed.
+- PRs are authoritative for review and merge context.
+- The wiki is the maintained synthesis.
+
+When evidence conflicts, state the conflict plainly or defer the claim. Do not
+turn a transcript, diff, or note into source of truth for behavior the code
+contradicts.
+
+Use frontmatter `sources:` entries for material that supports the page. Use
+precise file references when source code is relevant to retrieval.

codealmanac/manual/garden.md

@@ -0,0 +1,20 @@
+---
+title: Garden
+topics: [manual]
+---
+
+# Garden
+
+Garden improves the existing wiki graph.
+
+Look for stale claims, duplicate pages, weak leads, missing links, broken file
+references, confusing topics, unsupported claims, disconnected temporal notes,
+and clusters that need hubs.
+
+Broken page links should be resolved by linking to the right existing page,
+creating a justified page, or changing the mention back to plain text.
+
+Prefer synthesis over activity logs. Fold fragments into durable pages when
+chronology is not part of the meaning.
+
+No-op is valid when the wiki is coherent enough for the current pass.

codealmanac/manual/ingest.md

@@ -0,0 +1,17 @@
+---
+title: Ingest
+topics: [manual]
+---
+
+# Ingest
+
+Ingest folds selected local material into an existing configured Almanac wiki.
+
+Read the new material, then read nearby pages, backlinks, topics, and local
+wiki conventions. Decide what the material changes.
+
+Update existing pages when the subject already has a home. Create a page only
+when the material reveals a durable subject that needs one.
+
+No-op is valid when the input adds no durable wiki knowledge. If the input
+exposes a graph problem, treat part of the run like Garden.

codealmanac/manual/library.py

@@ -0,0 +1,84 @@
+from importlib.resources import files
+from pathlib import Path
+
+from codealmanac.core.errors import ValidationFailed
+from codealmanac.manual.models import (
+    MANUAL_DOCUMENTS,
+    ManualDocument,
+    ManualInstallResult,
+    ManualInventory,
+    ManualWorkspaceStatus,
+)
+from codealmanac.manual.requests import ManualReadRequest
+
+MANUAL_PACKAGE = "codealmanac.manual"
+
+
+class ManualLibrary:
+    def inventory(self) -> ManualInventory:
+        return ManualInventory(
+            documents=tuple(
+                self.read(ManualReadRequest(document=document))
+                for document in MANUAL_DOCUMENTS
+            )
+        )
+
+    def read(self, request: ManualReadRequest) -> ManualDocument:
+        resource = files(MANUAL_PACKAGE).joinpath(request.document.value)
+        try:
+            body = resource.read_text(encoding="utf-8")
+        except (FileNotFoundError, OSError) as error:
+            raise ValidationFailed(
+                f"cannot read bundled manual document {request.document.value}: {error}"
+            ) from error
+        return ManualDocument(
+            name=request.document,
+            relative_path=request.document.value,
+            body=body,
+        )
+
+    def install_missing(self, target_path: Path) -> ManualInstallResult:
+        try:
+            target_path.mkdir(parents=True, exist_ok=True)
+            copied: list[str] = []
+            existing: list[str] = []
+            for document in MANUAL_DOCUMENTS:
+                destination = target_path / document.value
+                if destination.exists():
+                    existing.append(document.value)
+                    continue
+                source = files(MANUAL_PACKAGE).joinpath(document.value)
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                destination.write_bytes(source.read_bytes())
+                copied.append(document.value)
+        except OSError as error:
+            raise ValidationFailed(f"cannot install manual files: {error}") from error
+        return ManualInstallResult(
+            target_path=target_path,
+            copied=tuple(copied),
+            existing=tuple(existing),
+        )
+
+    def workspace_status(self, target_path: Path) -> ManualWorkspaceStatus:
+        expected = tuple(document.value for document in MANUAL_DOCUMENTS)
+        present: list[str] = []
+        changed: list[str] = []
+        try:
+            for document in MANUAL_DOCUMENTS:
+                workspace_file = target_path / document.value
+                if not workspace_file.is_file():
+                    continue
+                present.append(document.value)
+                bundled = files(MANUAL_PACKAGE).joinpath(document.value).read_bytes()
+                if workspace_file.read_bytes() != bundled:
+                    changed.append(document.value)
+        except OSError as error:
+            raise ValidationFailed(f"cannot inspect manual files: {error}") from error
+        missing = tuple(document for document in expected if document not in present)
+        return ManualWorkspaceStatus(
+            target_path=target_path,
+            expected=expected,
+            present=tuple(present),
+            missing=missing,
+            changed=tuple(changed),
+        )

codealmanac/manual/models.py

@@ -0,0 +1,83 @@
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import Field, field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+
+
+class ManualDocumentName(StrEnum):
+    README = "README.md"
+    PAGES = "pages.md"
+    EVIDENCE = "evidence.md"
+    STYLE = "style.md"
+    SOURCES = "sources.md"
+    BUILD = "build.md"
+    INGEST = "ingest.md"
+    GARDEN = "garden.md"
+
+
+MANUAL_DOCUMENTS: tuple[ManualDocumentName, ...] = (
+    ManualDocumentName.README,
+    ManualDocumentName.PAGES,
+    ManualDocumentName.EVIDENCE,
+    ManualDocumentName.STYLE,
+    ManualDocumentName.SOURCES,
+    ManualDocumentName.BUILD,
+    ManualDocumentName.INGEST,
+    ManualDocumentName.GARDEN,
+)
+
+
+class ManualDocument(CodeAlmanacModel):
+    name: ManualDocumentName
+    relative_path: str
+    body: str
+
+    @field_validator("relative_path")
+    @classmethod
+    def require_relative_path(cls, value: str) -> str:
+        text = required_text(value, "manual path")
+        if text.startswith("/") or "/../" in f"/{text}/":
+            raise ValueError("manual path must be relative")
+        return text
+
+    @field_validator("body")
+    @classmethod
+    def require_body(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("manual body must not be empty")
+        return value
+
+
+class ManualInventory(CodeAlmanacModel):
+    documents: tuple[ManualDocument, ...] = Field(min_length=1)
+
+
+class ManualInstallResult(CodeAlmanacModel):
+    target_path: Path
+    copied: tuple[str, ...]
+    existing: tuple[str, ...]
+
+    @field_validator("copied", "existing")
+    @classmethod
+    def require_paths(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return tuple(required_text(path, "manual path") for path in value)
+
+
+class ManualWorkspaceStatus(CodeAlmanacModel):
+    target_path: Path
+    expected: tuple[str, ...] = Field(min_length=1)
+    present: tuple[str, ...]
+    missing: tuple[str, ...]
+    changed: tuple[str, ...] = ()
+
+    @property
+    def complete(self) -> bool:
+        return len(self.missing) == 0
+
+    @field_validator("expected", "present", "missing", "changed")
+    @classmethod
+    def require_paths(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return tuple(required_text(path, "manual path") for path in value)

codealmanac/manual/pages.md

@@ -0,0 +1,28 @@
+---
+title: Pages
+topics: [manual]
+---
+
+# Pages
+
+A page is the stable home for what the wiki knows about one durable subject.
+
+Good subjects include decisions, subsystems, external services, workflows,
+incidents, invariants, failure modes, project strategy, and repeated concepts
+that future agents will need again.
+
+Do not create pages that only summarize one file, one transcript, one diff, or
+one task log. Those are material used to justify a change. They are not usually
+the subject of the wiki.
+
+Prefer updating an existing page when the subject already has a home. Create a
+new page when the material reveals a durable subject that would otherwise stay
+buried.
+
+Use `[[page-slug]]` links for subjects a reader may follow. Use
+`[[src/path.py]]` and `[[src/path/]]` references when a page should be found by
+file-aware search.
+
+Page links are for real wiki nodes, not automatic entity markup. Link only to
+an existing page or a page created in the same run. If the subject is useful
+but does not yet deserve a page, mention it as plain text.

codealmanac/manual/requests.py

@@ -0,0 +1,6 @@
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.manual.models import ManualDocumentName
+
+
+class ManualReadRequest(CodeAlmanacModel):
+    document: ManualDocumentName

codealmanac/manual/sources.md

@@ -0,0 +1,18 @@
+---
+title: Sources
+topics: [manual]
+---
+
+# Sources
+
+Sources are raw material CodeAlmanac can learn from. They are not automatically
+source of truth for every claim.
+
+Selected material may include files, directories, diffs, commit ranges, PRs,
+issues, web pages, notes, and local agent transcripts. The source runtime
+normalizes that material before a lifecycle run.
+
+Adding or discovering material does not imply a wiki update. The lifecycle run
+decides whether the material changes durable wiki knowledge.
+
+Keep page shape organized by subject, not by how material arrived.

codealmanac/manual/style.md

@@ -0,0 +1,19 @@
+---
+title: Style
+topics: [manual]
+---
+
+# Style
+
+Write for a future coding agent that needs useful context quickly.
+
+Use plain factual sentences. Prefer "is" over vague phrasing such as "serves
+as." Avoid promotional language, speculation, and generic architecture prose
+that could describe any repository.
+
+Start with the subject and why it matters in this repo. Keep details that would
+otherwise require rediscovery: names, files, commands, dates, constraints,
+failure modes, and rejected alternatives.
+
+Use prose first. Use bullets for real lists and tables for structured
+comparison.

codealmanac/prompts/__init__.py

@@ -0,0 +1,5 @@
+from codealmanac.prompts.models import PromptName
+from codealmanac.prompts.renderer import PromptRenderer
+from codealmanac.prompts.requests import RenderPromptRequest
+
+__all__ = ["PromptName", "PromptRenderer", "RenderPromptRequest"]

codealmanac/prompts/base/notability.md

@@ -0,0 +1,14 @@
+# Notability
+
+Write or edit wiki pages only when the change preserves non-obvious durable
+knowledge that helps future work.
+
+Good wiki changes capture decisions, multi-file flows, invariants, incidents,
+gotchas, operational constraints, team conventions, external dependencies as
+this repo uses them, or product context that shapes implementation choices.
+
+Do not use the wiki as a scratchpad. Do not preserve unresolved intake work,
+temporary question lists, raw field inventories, or routine activity logs.
+
+No-op is valid when the available material does not justify a durable wiki
+change.

codealmanac/prompts/base/purpose.md

@@ -0,0 +1,23 @@
+# CodeAlmanac Purpose
+
+CodeAlmanac maintains a repo-owned wiki for a codebase and the project world
+around that codebase. New installs default to `almanac/`; the repo may choose a
+different configured Almanac root.
+
+The wiki is durable project memory for future coding agents. It records why the
+system is shaped this way, what must not be violated, what was tried and failed,
+how workflows move end to end, and what gotchas were discovered through real
+work.
+
+The code is authoritative for runtime behavior. The wiki is maintained
+synthesis. Transcripts, PRs, notes, diffs, and docs are raw material that can
+justify wiki changes.
+
+The public command and product name is `codealmanac`. Do not introduce public
+`almanac`, `alm`, `absorb`, or hosted CLI language.
+
+The public CLI name is codealmanac.
+
+Detailed wiki doctrine lives in `manual/` under the configured Almanac root.
+The prompt names the job; the manual defines the page, evidence, style, source,
+and operation rules.

codealmanac/prompts/base/syntax.md

@@ -0,0 +1,19 @@
+# Wiki Syntax
+
+Pages are Markdown files under `pages/` inside the configured Almanac root,
+with YAML frontmatter. Use kebab-case slugs and stable page titles.
+
+Use `topics:` for topic slugs. Use structured `sources:` entries for evidence
+that supports non-obvious claims. Use `[[...]]` wikilinks for pages, files,
+folders, and cross-wiki references.
+
+Page wikilinks must resolve. Link only to existing page slugs or pages you
+create or update in this run. If no page exists and you are not creating it,
+write the name as plain text instead of leaving a broken `[[...]]` link.
+
+Every sentence should contain a specific fact. Prefer neutral prose. Do not
+speculate. Do not add promotional language.
+
+Update only files inside the configured Almanac root unless the operation
+explicitly says otherwise. Do not edit application code during lifecycle wiki
+operations.

codealmanac/prompts/models.py

@@ -0,0 +1,9 @@
+from enum import StrEnum
+
+
+class PromptName(StrEnum):
+    BASE_PURPOSE = "base/purpose.md"
+    BASE_NOTABILITY = "base/notability.md"
+    BASE_SYNTAX = "base/syntax.md"
+    OPERATION_INGEST = "operations/ingest.md"
+    OPERATION_GARDEN = "operations/garden.md"