codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/services/topics/service.py

@@ -0,0 +1,297 @@
+from codealmanac.core.errors import ConflictError, NotFoundError, ValidationFailed
+from codealmanac.core.slug import to_kebab_case
+from codealmanac.services.index.models import TopicDetail, TopicSummary
+from codealmanac.services.index.service import IndexService
+from codealmanac.services.topics.models import (
+    TopicEdgeMutationResult,
+    TopicMutationAction,
+    TopicMutationResult,
+    TopicRewriteMutationResult,
+)
+from codealmanac.services.topics.requests import (
+    CreateTopicRequest,
+    DeleteTopicRequest,
+    DescribeTopicRequest,
+    LinkTopicRequest,
+    ListTopicsRequest,
+    RenameTopicRequest,
+    ShowTopicRequest,
+    UnlinkTopicRequest,
+)
+from codealmanac.services.wiki.frontmatter_rewrite import (
+    apply_page_topic_rewrites,
+    plan_page_topic_rewrites,
+)
+from codealmanac.services.wiki.topics import (
+    TopicDefinition,
+    load_topics_file,
+    title_for_slug,
+)
+from codealmanac.services.workspaces.requests import SelectWorkspaceRequest
+from codealmanac.services.workspaces.service import WorkspacesService
+
+
+class TopicsService:
+    def __init__(self, workspaces: WorkspacesService, index: IndexService):
+        self.workspaces = workspaces
+        self.index = index
+
+    def list(self, request: ListTopicsRequest) -> tuple[TopicSummary, ...]:
+        workspace = resolve_workspace(
+            self.workspaces,
+            request.cwd,
+            request.wiki,
+        )
+        return self.index.list_topics(workspace.workspace_id)
+
+    def show(self, request: ShowTopicRequest) -> TopicDetail:
+        workspace = resolve_workspace(
+            self.workspaces,
+            request.cwd,
+            request.wiki,
+        )
+        slug = to_kebab_case(request.slug)
+        topic = self.index.get_topic(
+            workspace.workspace_id,
+            slug,
+            request.include_descendants,
+        )
+        if topic is None:
+            raise NotFoundError("topic", request.slug)
+        return topic
+
+    def create(self, request: CreateTopicRequest) -> TopicMutationResult:
+        workspace = resolve_workspace(
+            self.workspaces,
+            request.cwd,
+            request.wiki,
+        )
+        slug = to_kebab_case(request.name)
+        if not slug:
+            raise ValidationFailed("topic name must contain slug-able characters")
+        existing = existing_topic_slugs(self.index, workspace.workspace_id)
+        topic_file = load_topics_file(workspace.almanac_path)
+        validate_parents_exist(slug, request.parents, existing)
+        for parent in request.parents:
+            topic_file.ensure_topic(parent, title_for_slug(parent))
+
+        existed_before = slug in existing or topic_file.has_entry(slug)
+        topic_file.ensure_topic(slug, request.name.strip())
+        topic_file.maybe_update_default_title(slug, request.name.strip())
+
+        for parent in request.parents:
+            if topic_file.add_parent(slug, parent):
+                reject_cycle(topic_file.definitions, slug, parent)
+
+        topic_file.write()
+        self.index.ensure_fresh(workspace.workspace_id)
+        action = (
+            TopicMutationAction.UPDATED
+            if existed_before
+            else TopicMutationAction.CREATED
+        )
+        topic = self.index.get_topic(workspace.workspace_id, slug, False)
+        return TopicMutationResult(
+            action=action,
+            slug=slug,
+            parents=topic.parents if topic is not None else request.parents,
+            description=topic.description if topic is not None else None,
+        )
+
+    def describe(self, request: DescribeTopicRequest) -> TopicMutationResult:
+        workspace = resolve_workspace(
+            self.workspaces,
+            request.cwd,
+            request.wiki,
+        )
+        existing = existing_topic_slugs(self.index, workspace.workspace_id)
+        if request.slug not in existing:
+            raise NotFoundError("topic", request.slug)
+        topic_file = load_topics_file(workspace.almanac_path)
+        topic_file.ensure_topic(request.slug, title_for_slug(request.slug))
+        description = request.description or None
+        topic_file.set_description(request.slug, description)
+        topic_file.write()
+        self.index.ensure_fresh(workspace.workspace_id)
+        topic = self.index.get_topic(workspace.workspace_id, request.slug, False)
+        return TopicMutationResult(
+            action=TopicMutationAction.DESCRIBED,
+            slug=request.slug,
+            parents=topic.parents if topic is not None else (),
+            description=description,
+        )
+
+    def link(self, request: LinkTopicRequest) -> TopicEdgeMutationResult:
+        workspace = resolve_workspace(
+            self.workspaces,
+            request.cwd,
+            request.wiki,
+        )
+        validate_not_self_parent(request.child, request.parent)
+        existing = existing_topic_slugs(self.index, workspace.workspace_id)
+        require_topics(existing, request.child, request.parent)
+        topic_file = load_topics_file(workspace.almanac_path)
+        topic_file.ensure_topic(request.child, title_for_slug(request.child))
+        topic_file.ensure_topic(request.parent, title_for_slug(request.parent))
+        if not topic_file.add_parent(request.child, request.parent):
+            return TopicEdgeMutationResult(
+                action=TopicMutationAction.ALREADY_LINKED,
+                child=request.child,
+                parent=request.parent,
+            )
+        reject_cycle(topic_file.definitions, request.child, request.parent)
+        topic_file.write()
+        self.index.ensure_fresh(workspace.workspace_id)
+        return TopicEdgeMutationResult(
+            action=TopicMutationAction.LINKED,
+            child=request.child,
+            parent=request.parent,
+        )
+
+    def unlink(self, request: UnlinkTopicRequest) -> TopicEdgeMutationResult:
+        workspace = resolve_workspace(
+            self.workspaces,
+            request.cwd,
+            request.wiki,
+        )
+        topic_file = load_topics_file(workspace.almanac_path)
+        if not topic_file.remove_parent(request.child, request.parent):
+            return TopicEdgeMutationResult(
+                action=TopicMutationAction.NO_EDGE,
+                child=request.child,
+                parent=request.parent,
+            )
+        topic_file.write()
+        self.index.ensure_fresh(workspace.workspace_id)
+        return TopicEdgeMutationResult(
+            action=TopicMutationAction.UNLINKED,
+            child=request.child,
+            parent=request.parent,
+        )
+
+    def rename(self, request: RenameTopicRequest) -> TopicRewriteMutationResult:
+        workspace = resolve_workspace(
+            self.workspaces,
+            request.cwd,
+            request.wiki,
+        )
+        if request.old_slug == request.new_slug:
+            return TopicRewriteMutationResult(
+                action=TopicMutationAction.UNCHANGED,
+                slug=request.old_slug,
+                new_slug=request.new_slug,
+            )
+        existing = existing_topic_slugs(self.index, workspace.workspace_id)
+        if request.old_slug not in existing:
+            raise NotFoundError("topic", request.old_slug)
+        if request.new_slug in existing:
+            raise ConflictError(
+                f'topic "{request.new_slug}" already exists; delete it first '
+                "if you intend to merge"
+            )
+
+        rewrites = plan_page_topic_rewrites(
+            workspace.almanac_path / "pages",
+            lambda topics: tuple(
+                request.new_slug if topic == request.old_slug else topic
+                for topic in topics
+            ),
+        )
+        topic_file = load_topics_file(workspace.almanac_path)
+        topic_file.rename_topic(request.old_slug, request.new_slug)
+        _ = topic_file.definitions
+        topic_file.write()
+        pages_updated = apply_page_topic_rewrites(rewrites)
+        self.index.ensure_fresh(workspace.workspace_id)
+        return TopicRewriteMutationResult(
+            action=TopicMutationAction.RENAMED,
+            slug=request.old_slug,
+            new_slug=request.new_slug,
+            pages_updated=pages_updated,
+        )
+
+    def delete(self, request: DeleteTopicRequest) -> TopicRewriteMutationResult:
+        workspace = resolve_workspace(
+            self.workspaces,
+            request.cwd,
+            request.wiki,
+        )
+        existing = existing_topic_slugs(self.index, workspace.workspace_id)
+        if request.slug not in existing:
+            raise NotFoundError("topic", request.slug)
+
+        rewrites = plan_page_topic_rewrites(
+            workspace.almanac_path / "pages",
+            lambda topics: tuple(topic for topic in topics if topic != request.slug),
+        )
+        topic_file = load_topics_file(workspace.almanac_path)
+        topic_file.delete_topic(request.slug)
+        _ = topic_file.definitions
+        topic_file.write()
+        pages_updated = apply_page_topic_rewrites(rewrites)
+        self.index.ensure_fresh(workspace.workspace_id)
+        return TopicRewriteMutationResult(
+            action=TopicMutationAction.DELETED,
+            slug=request.slug,
+            pages_updated=pages_updated,
+        )
+
+
+def resolve_workspace(workspaces: WorkspacesService, cwd, wiki):
+    if wiki is None:
+        return workspaces.resolve(cwd)
+    return workspaces.select(SelectWorkspaceRequest(selector=wiki, base_path=cwd))
+
+
+def existing_topic_slugs(index: IndexService, workspace_id: str) -> set[str]:
+    return {topic.slug for topic in index.list_topics(workspace_id)}
+
+
+def validate_parents_exist(
+    child: str,
+    parents: tuple[str, ...],
+    existing: set[str],
+) -> None:
+    for parent in parents:
+        validate_not_self_parent(child, parent)
+        if parent not in existing:
+            raise NotFoundError("topic", parent)
+
+
+def require_topics(existing: set[str], *slugs: str) -> None:
+    for slug in slugs:
+        if slug not in existing:
+            raise NotFoundError("topic", slug)
+
+
+def validate_not_self_parent(child: str, parent: str) -> None:
+    if child == parent:
+        raise ValidationFailed("topic cannot be its own parent")
+
+
+def reject_cycle(
+    definitions: tuple[TopicDefinition, ...],
+    child: str,
+    parent: str,
+) -> None:
+    if child in ancestors_of(definitions, parent):
+        raise ConflictError(
+            f"adding {parent} as parent of {child} would create a cycle"
+        )
+
+
+def ancestors_of(definitions: tuple[TopicDefinition, ...], slug: str) -> set[str]:
+    parents_by_child = {
+        definition.slug: set(definition.parents) for definition in definitions
+    }
+    ancestors: set[str] = set()
+    frontier = list(parents_by_child.get(slug, set()))
+    depth = 0
+    while frontier and depth < 32:
+        depth += 1
+        parent = frontier.pop()
+        if parent in ancestors:
+            continue
+        ancestors.add(parent)
+        frontier.extend(parents_by_child.get(parent, set()))
+    return ancestors

codealmanac/services/updates/__init__.py

@@ -0,0 +1,4 @@
+from codealmanac.services.updates.service import UpdatesService
+
+__all__ = ["UpdatesService"]
+

codealmanac/services/updates/models.py

@@ -0,0 +1,83 @@
+import sys
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+
+PACKAGE_NAME = "codealmanac"
+
+
+class UpdateInstallMethod(StrEnum):
+    UV_TOOL = "uv-tool"
+    PIP = "pip"
+    EDITABLE = "editable"
+    UNKNOWN = "unknown"
+
+
+class UpdateStatus(StrEnum):
+    READY = "ready"
+    COMPLETED = "completed"
+    UNSUPPORTED = "unsupported"
+    FAILED = "failed"
+
+
+class PackageInstallMetadata(CodeAlmanacModel):
+    package: str = PACKAGE_NAME
+    version: str
+    installer: str | None = None
+    editable: bool = False
+    source_url: str | None = None
+    python_executable: Path = Path(sys.executable)
+
+    @field_validator("package", "version")
+    @classmethod
+    def require_text_fields(cls, value: str) -> str:
+        return required_text(value, "package install metadata")
+
+    @field_validator("installer", "source_url")
+    @classmethod
+    def normalize_optional_text(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "package install metadata")
+
+
+class PackageCommandResult(CodeAlmanacModel):
+    exit_code: int
+    stdout: str = ""
+    stderr: str = ""
+
+
+class UpdatePlan(CodeAlmanacModel):
+    status: UpdateStatus
+    method: UpdateInstallMethod
+    installed_version: str
+    command: tuple[str, ...] = ()
+    message: str
+    fix: str | None = None
+    installer: str | None = None
+    editable: bool = False
+    source_url: str | None = None
+
+    @field_validator("installed_version", "message")
+    @classmethod
+    def require_text_fields(cls, value: str) -> str:
+        return required_text(value, "update plan")
+
+    @field_validator("fix", "installer", "source_url")
+    @classmethod
+    def normalize_optional_text(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "update plan")
+
+
+class UpdateResult(CodeAlmanacModel):
+    status: UpdateStatus
+    plan: UpdatePlan
+    exit_code: int | None = None
+    stdout: str = ""
+    stderr: str = ""

codealmanac/services/updates/ports.py

@@ -0,0 +1,17 @@
+from typing import Protocol
+
+from codealmanac.services.updates.models import (
+    PackageCommandResult,
+    PackageInstallMetadata,
+)
+
+
+class PackageInstallMetadataProvider(Protocol):
+    def read(self) -> PackageInstallMetadata:
+        """Return metadata for the currently running package installation."""
+
+
+class PackageCommandRunner(Protocol):
+    def run(self, command: tuple[str, ...]) -> PackageCommandResult:
+        """Run a foreground package-manager command."""
+

codealmanac/services/updates/requests.py

@@ -0,0 +1,10 @@
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class CheckUpdateRequest(CodeAlmanacModel):
+    pass
+
+
+class RunUpdateRequest(CodeAlmanacModel):
+    pass
+

codealmanac/services/updates/service.py

@@ -0,0 +1,113 @@
+from codealmanac.services.updates.models import (
+    PACKAGE_NAME,
+    PackageInstallMetadata,
+    UpdateInstallMethod,
+    UpdatePlan,
+    UpdateResult,
+    UpdateStatus,
+)
+from codealmanac.services.updates.ports import (
+    PackageCommandRunner,
+    PackageInstallMetadataProvider,
+)
+from codealmanac.services.updates.requests import CheckUpdateRequest, RunUpdateRequest
+
+
+class UpdatesService:
+    def __init__(
+        self,
+        metadata: PackageInstallMetadataProvider,
+        runner: PackageCommandRunner,
+    ):
+        self.metadata = metadata
+        self.runner = runner
+
+    def check(self, request: CheckUpdateRequest) -> UpdatePlan:
+        return plan_update(self.metadata.read())
+
+    def run(self, request: RunUpdateRequest) -> UpdateResult:
+        plan = self.check(CheckUpdateRequest())
+        if plan.status != UpdateStatus.READY:
+            return UpdateResult(status=plan.status, plan=plan)
+        output = self.runner.run(plan.command)
+        status = (
+            UpdateStatus.COMPLETED
+            if output.exit_code == 0
+            else UpdateStatus.FAILED
+        )
+        return UpdateResult(
+            status=status,
+            plan=plan,
+            exit_code=output.exit_code,
+            stdout=output.stdout,
+            stderr=output.stderr,
+        )
+
+
+def plan_update(metadata: PackageInstallMetadata) -> UpdatePlan:
+    method = update_method(metadata)
+    if method == UpdateInstallMethod.EDITABLE:
+        return UpdatePlan(
+            status=UpdateStatus.UNSUPPORTED,
+            method=method,
+            installed_version=metadata.version,
+            message="editable source install cannot be self-updated",
+            fix="run: git pull && uv sync",
+            installer=metadata.installer,
+            editable=metadata.editable,
+            source_url=metadata.source_url,
+        )
+    if method == UpdateInstallMethod.UV_TOOL:
+        command = ("uv", "tool", "upgrade", PACKAGE_NAME)
+        return runnable_plan(metadata, method, command)
+    if method == UpdateInstallMethod.PIP:
+        command = (
+            str(metadata.python_executable),
+            "-m",
+            "pip",
+            "install",
+            "--upgrade",
+            PACKAGE_NAME,
+        )
+        return runnable_plan(metadata, method, command)
+    return UpdatePlan(
+        status=UpdateStatus.UNSUPPORTED,
+        method=method,
+        installed_version=metadata.version,
+        message="unknown package installer; refusing automatic update",
+        fix=(
+            f"run: uv tool upgrade {PACKAGE_NAME} "
+            f"or {metadata.python_executable} -m pip install --upgrade {PACKAGE_NAME}"
+        ),
+        installer=metadata.installer,
+        editable=metadata.editable,
+        source_url=metadata.source_url,
+    )
+
+
+def runnable_plan(
+    metadata: PackageInstallMetadata,
+    method: UpdateInstallMethod,
+    command: tuple[str, ...],
+) -> UpdatePlan:
+    return UpdatePlan(
+        status=UpdateStatus.READY,
+        method=method,
+        installed_version=metadata.version,
+        command=command,
+        message="ready to run foreground package update",
+        installer=metadata.installer,
+        editable=metadata.editable,
+        source_url=metadata.source_url,
+    )
+
+
+def update_method(metadata: PackageInstallMetadata) -> UpdateInstallMethod:
+    if metadata.editable:
+        return UpdateInstallMethod.EDITABLE
+    installer = (metadata.installer or "").strip().casefold()
+    if installer == "uv":
+        return UpdateInstallMethod.UV_TOOL
+    if installer == "pip":
+        return UpdateInstallMethod.PIP
+    return UpdateInstallMethod.UNKNOWN

codealmanac/services/viewer/__init__.py

@@ -0,0 +1 @@
+"""Read-only browser viewer service."""

codealmanac/services/viewer/models.py

@@ -0,0 +1,80 @@
+from enum import StrEnum
+from pathlib import Path
+
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class ViewerFileKind(StrEnum):
+    FILE = "file"
+    DIRECTORY = "directory"
+
+
+class ViewerWorkspace(CodeAlmanacModel):
+    name: str
+    root_path: Path
+
+
+class ViewerPageSummary(CodeAlmanacModel):
+    slug: str
+    title: str | None
+    summary: str | None
+    topics: tuple[str, ...]
+    archived: bool
+
+
+class ViewerTopicSummary(CodeAlmanacModel):
+    slug: str
+    title: str | None
+    description: str | None
+    page_count: int
+
+
+class ViewerFileReference(CodeAlmanacModel):
+    path: str
+    is_dir: bool
+
+
+class ViewerOverview(CodeAlmanacModel):
+    workspace: ViewerWorkspace
+    page_count: int
+    topic_count: int
+    pages: tuple[ViewerPageSummary, ...]
+    topics: tuple[ViewerTopicSummary, ...]
+    featured_page: ViewerPageSummary | None
+
+
+class ViewerPage(CodeAlmanacModel):
+    workspace: ViewerWorkspace
+    slug: str
+    title: str | None
+    summary: str | None
+    topics: tuple[str, ...]
+    body: str
+    html: str
+    backlinks: tuple[str, ...]
+    outgoing_links: tuple[str, ...]
+    file_refs: tuple[ViewerFileReference, ...]
+    related_pages: tuple[ViewerPageSummary, ...]
+
+
+class ViewerSearch(CodeAlmanacModel):
+    workspace: ViewerWorkspace
+    query: str | None
+    pages: tuple[ViewerPageSummary, ...]
+
+
+class ViewerFile(CodeAlmanacModel):
+    workspace: ViewerWorkspace
+    path: str
+    kind: ViewerFileKind
+    pages: tuple[ViewerPageSummary, ...]
+
+
+class ViewerTopic(CodeAlmanacModel):
+    workspace: ViewerWorkspace
+    slug: str
+    title: str | None
+    description: str | None
+    parents: tuple[str, ...]
+    children: tuple[str, ...]
+    pages: tuple[ViewerPageSummary, ...]

codealmanac/services/viewer/renderer.py

@@ -0,0 +1,89 @@
+import re
+from urllib.parse import quote
+
+from markdown_it import MarkdownIt
+from markdown_it.token import Token
+
+from codealmanac.services.wiki.models import (
+    CrossWikiLink,
+    FileLink,
+    FolderLink,
+    PageLink,
+)
+from codealmanac.services.wiki.wikilinks import classify_wikilink
+
+WIKILINK_RE = re.compile(r"\[\[([^\]\n]+)\]\]")
+
+
+class MarkdownRenderer:
+    def __init__(self):
+        self.markdown = MarkdownIt("commonmark", {"html": False, "linkify": False})
+
+    def render(self, body: str) -> str:
+        env: dict[str, object] = {}
+        tokens = self.markdown.parse(body, env)
+        for token in tokens:
+            if token.type == "inline" and token.children is not None:
+                token.children = rewrite_wikilinks(token.children)
+        return self.markdown.renderer.render(tokens, self.markdown.options, env)
+
+
+def rewrite_wikilinks(tokens: list[Token]) -> list[Token]:
+    rewritten: list[Token] = []
+    for token in tokens:
+        if token.type != "text":
+            rewritten.append(token)
+            continue
+        rewritten.extend(rewrite_text_token(token.content))
+    return rewritten
+
+
+def rewrite_text_token(value: str) -> list[Token]:
+    rewritten: list[Token] = []
+    position = 0
+    for match in WIKILINK_RE.finditer(value):
+        if match.start() > position:
+            rewritten.append(text_token(value[position : match.start()]))
+        rewritten.extend(tokens_for_wikilink_match(match))
+        position = match.end()
+    if position < len(value):
+        rewritten.append(text_token(value[position:]))
+    return rewritten or [text_token(value)]
+
+
+def tokens_for_wikilink_match(match: re.Match[str]) -> list[Token]:
+    raw = match.group(1)
+    link = classify_wikilink(raw)
+    if link is None:
+        return [text_token(match.group(0))]
+    label = wikilink_label(raw)
+    if isinstance(link, PageLink):
+        slug = quote(link.target, safe="")
+        return link_tokens(label, f"#/page/{slug}")
+    if isinstance(link, FileLink | FolderLink):
+        return [code_token(label)]
+    if isinstance(link, CrossWikiLink):
+        return [code_token(label)]
+    return [text_token(match.group(0))]
+
+
+def text_token(value: str) -> Token:
+    return Token("text", "", 0, content=value)
+
+
+def code_token(value: str) -> Token:
+    return Token("code_inline", "code", 0, content=value)
+
+
+def link_tokens(label: str, href: str) -> list[Token]:
+    opening = Token("link_open", "a", 1, attrs={"href": href})
+    closing = Token("link_close", "a", -1)
+    return [opening, text_token(label), closing]
+
+
+def wikilink_label(raw: str) -> str:
+    target, separator, label = raw.partition("|")
+    if separator:
+        return label.strip() or target.strip()
+    return target.strip()
+