codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/cli/render/root.py

@@ -0,0 +1,290 @@
+import argparse
+import json
+import sys
+
+from codealmanac.services.index.models import (
+    HealthReport,
+    IndexRefreshResult,
+    PageView,
+    SearchPageResult,
+    TopicDetail,
+    TopicSummary,
+)
+from codealmanac.services.tagging.models import TaggingResult
+from codealmanac.services.topics.models import (
+    TopicEdgeMutationResult,
+    TopicMutationAction,
+    TopicMutationResult,
+    TopicRewriteMutationResult,
+)
+from codealmanac.services.workspaces.models import (
+    DropWorkspaceResult,
+    WorkspaceListResult,
+)
+from codealmanac.workflows.garden.models import GardenResult
+from codealmanac.workflows.ingest.models import IngestResult
+from codealmanac.workflows.sync.models import SyncMode, SyncSummary
+
+
+def render_search(rows: tuple[SearchPageResult, ...], json_output: bool) -> None:
+    if json_output:
+        data = [row.model_dump(mode="json") for row in rows]
+        print(json.dumps(data, indent=2))
+        return
+    if len(rows) == 0:
+        print("# 0 results", file=sys.stderr)
+        return
+    for row in rows:
+        print(row.slug)
+
+
+def render_workspace_list(result: WorkspaceListResult, json_output: bool) -> None:
+    if json_output:
+        data = [item.model_dump(mode="json") for item in result.items]
+        print(json.dumps(data, indent=2))
+        return
+    for item in result.items:
+        workspace = item.workspace
+        print(
+            f"{workspace.name}\t{workspace.root_path}\t"
+            f"{workspace.almanac_root.as_posix()}"
+        )
+
+
+def render_workspace_drop(result: DropWorkspaceResult, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(result.model_dump(mode="json"), indent=2))
+        return
+    if len(result.dropped) == 0:
+        print("# 0 wikis dropped", file=sys.stderr)
+        return
+    for workspace in result.dropped:
+        print(
+            f"dropped {workspace.name}\t{workspace.root_path}\t"
+            f"{workspace.almanac_root.as_posix()}"
+        )
+
+
+def render_build(workspace_name: str, result: IndexRefreshResult) -> None:
+    print(f"built {workspace_name}: {index_summary(result)}")
+
+def render_ingest(result: IngestResult) -> None:
+    print(f"ingested {result.run.run_id}: {result.run.status.value}")
+    print(f"sources: {len(result.sources)}")
+    print(f"wiki_changes: {len(result.safety.changed_files)}")
+    if result.run.summary is not None:
+        print(f"summary: {result.run.summary}")
+
+def render_garden(result: GardenResult) -> None:
+    print(f"gardened {result.run.run_id}: {result.run.status.value}")
+    print(f"wiki_changes: {len(result.safety.changed_files)}")
+    print(f"health_before: {health_issue_count(result.health_before)}")
+    if result.run.summary is not None:
+        print(f"summary: {result.run.summary}")
+
+def render_sync_status(summary: SyncSummary, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(summary.model_dump(mode="json"), indent=2))
+        return
+    status_mode = summary.mode == SyncMode.STATUS
+    print("sync status:" if status_mode else "sync:")
+    print(f"  scanned: {summary.scanned}")
+    print(f"  eligible: {summary.eligible}")
+    if status_mode:
+        print(f"  ready: {len(summary.ready)}")
+    else:
+        print(f"  started: {len(summary.started)}")
+    print(f"  skipped: {len(summary.skipped)}")
+    print(f"  needs_attention: {len(summary.needs_attention)}")
+    for ready in summary.ready:
+        print(
+            f"  - ready {ready.app.value} {ready.session_id}: "
+            f"lines {ready.from_line}-{ready.to_line}"
+        )
+    for started in summary.started:
+        print(
+            f"  - started {started.app.value} {started.session_id}: "
+            f"{started.run_id} (lines {started.from_line}-{started.to_line})"
+        )
+    for item in summary.needs_attention:
+        print(f"  - needs attention {item.transcript_path}: {item.reason}")
+
+def health_issue_count(report: HealthReport) -> int:
+    return sum(
+        len(items)
+        for items in (
+            report.orphans,
+            report.dead_refs,
+            report.broken_links,
+            report.broken_xwiki,
+            report.empty_topics,
+            report.empty_pages,
+        )
+    )
+
+def render_reindex(result: IndexRefreshResult, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(result.model_dump(mode="json"), indent=2))
+        return
+    print(f"reindexed: {index_summary(result)}")
+
+def index_summary(result: IndexRefreshResult) -> str:
+    skip_suffix = (
+        f"; {result.files_skipped} skipped" if result.files_skipped > 0 else ""
+    )
+    return (
+        f"{result.pages_indexed} {page_word(result.pages_indexed)} "
+        f"({result.changed} updated, {result.removed} removed{skip_suffix})"
+    )
+
+def render_page(page: PageView, args: argparse.Namespace) -> None:
+    if args.json:
+        print(json.dumps(page.model_dump(mode="json"), indent=2))
+        return
+    if args.body:
+        print(body_with_trailing_newline(page.body), end="")
+        return
+    if args.links:
+        print_lines(page.wikilinks_out)
+        return
+    if args.backlinks:
+        print_lines(page.wikilinks_in)
+        return
+    if args.files:
+        print_lines(tuple(ref.path for ref in page.file_refs))
+        return
+    if args.topics:
+        print_lines(page.topics)
+        return
+    if args.meta:
+        print(metadata_header(page))
+        return
+    if args.lead:
+        print(first_paragraph(page.body))
+        return
+    print(body_with_trailing_newline(page.body), end="")
+
+def print_lines(values: tuple[str, ...]) -> None:
+    for value in values:
+        print(value)
+
+def metadata_header(page: PageView) -> str:
+    lines = [
+        f"slug: {page.slug}",
+        f"title: {page.title or ''}",
+        f"path: {page.file_path}",
+    ]
+    if page.summary:
+        lines.append(f"summary: {page.summary}")
+    if page.topics:
+        lines.append(f"topics: {', '.join(page.topics)}")
+    return "\n".join(lines)
+
+def first_paragraph(body: str) -> str:
+    paragraphs = [part.strip() for part in body.split("\n\n") if part.strip()]
+    return paragraphs[0] if paragraphs else ""
+
+def body_with_trailing_newline(body: str) -> str:
+    if body == "" or body.endswith("\n"):
+        return body
+    return f"{body}\n"
+
+def render_topics(rows: tuple[TopicSummary, ...]) -> None:
+    for row in rows:
+        title = row.title or row.slug
+        print(f"{row.slug}\t{row.page_count}\t{title}")
+
+def render_topic(topic: TopicDetail) -> None:
+    print(f"slug: {topic.slug}")
+    print(f"title: {topic.title or ''}")
+    if topic.description:
+        print(f"description: {topic.description}")
+    if topic.parents:
+        print(f"parents: {', '.join(topic.parents)}")
+    if topic.children:
+        print(f"children: {', '.join(topic.children)}")
+    if topic.pages:
+        print("pages:")
+        for slug in topic.pages:
+            print(f"  {slug}")
+    else:
+        print("pages: none")
+
+def render_topic_mutation(result: TopicMutationResult) -> None:
+    print(f"{result.slug}: {result.action.value}")
+
+def render_topic_edge_mutation(result: TopicEdgeMutationResult) -> None:
+    if result.action == TopicMutationAction.NO_EDGE:
+        print(f"no edge {result.child} -> {result.parent}")
+        return
+    if result.action == TopicMutationAction.ALREADY_LINKED:
+        print(f"edge {result.child} -> {result.parent} already exists")
+        return
+    print(f"{result.action.value} {result.child} -> {result.parent}")
+
+def render_topic_rewrite_mutation(result: TopicRewriteMutationResult) -> None:
+    if result.action == TopicMutationAction.UNCHANGED:
+        print(f"topic {result.slug} unchanged")
+        return
+    if result.action == TopicMutationAction.RENAMED:
+        print(
+            f"renamed {result.slug} -> {result.new_slug} "
+            f"({result.pages_updated} {page_word(result.pages_updated)} updated)"
+        )
+        return
+    if result.action == TopicMutationAction.DELETED:
+        print(
+            f"deleted {result.slug} "
+            f"({result.pages_updated} {page_word(result.pages_updated)} untagged)"
+        )
+        return
+    print(f"{result.slug}: {result.action.value}")
+
+def page_word(count: int) -> str:
+    return "page" if count == 1 else "pages"
+
+def render_health(report: HealthReport, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(report.model_dump(mode="json"), indent=2))
+        return
+    render_health_section("orphans", tuple(item.slug for item in report.orphans))
+    render_health_section(
+        "dead_refs",
+        tuple(f"{item.slug}\t{item.path}" for item in report.dead_refs),
+    )
+    render_health_section(
+        "broken_links",
+        tuple(
+            f"{item.source_slug}\t{item.target_slug}" for item in report.broken_links
+        ),
+    )
+    render_health_section(
+        "broken_xwiki",
+        tuple(
+            f"{item.source_slug}\t{item.target_wiki}:{item.target_slug}"
+            for item in report.broken_xwiki
+        ),
+    )
+    render_health_section(
+        "empty_topics",
+        tuple(item.slug for item in report.empty_topics),
+    )
+    render_health_section(
+        "empty_pages",
+        tuple(item.slug for item in report.empty_pages),
+    )
+
+def render_health_section(name: str, rows: tuple[str, ...]) -> None:
+    if not rows:
+        print(f"{name} (0): ok")
+        return
+    print(f"{name} ({len(rows)}):")
+    for row in rows:
+        print(f"  {row}")
+
+def render_tagging(changed_label: str, unchanged_label: str, result: TaggingResult):
+    if result.changed_topics:
+        print(f"{result.slug}: {changed_label} {', '.join(result.changed_topics)}")
+        return
+    unchanged = ", ".join(result.requested_topics)
+    print(f"{result.slug}: {unchanged_label} {unchanged}")

codealmanac/core/__init__.py

@@ -0,0 +1 @@
+

codealmanac/core/errors.py

@@ -0,0 +1,45 @@
+from typing import Literal
+
+ErrorCode = Literal[
+    "codealmanac_error",
+    "not_found",
+    "conflict",
+    "validation_failed",
+    "execution_failed",
+]
+
+
+class CodeAlmanacError(Exception):
+    """Base class for product errors that cross CLI and future server edges."""
+
+    code: ErrorCode = "codealmanac_error"
+
+
+class NotFoundError(CodeAlmanacError):
+    code: ErrorCode = "not_found"
+
+    def __init__(self, resource: str, identifier: str):
+        super().__init__(f"{resource} not found: {identifier}")
+        self.resource = resource
+        self.identifier = identifier
+
+
+class ConflictError(CodeAlmanacError):
+    code: ErrorCode = "conflict"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class ValidationFailed(CodeAlmanacError):
+    code: ErrorCode = "validation_failed"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class ExecutionFailed(CodeAlmanacError):
+    code: ErrorCode = "execution_failed"
+
+    def __init__(self, message: str):
+        super().__init__(message)

codealmanac/core/models.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from codealmanac.core.paths import default_config_path, default_registry_path
+
+
+class CodeAlmanacModel(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class AppConfig(CodeAlmanacModel):
+    registry_path: Path = Field(default_factory=default_registry_path)
+    config_path: Path = Field(default_factory=default_config_path)

codealmanac/core/paths.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+
+def home_dir() -> Path:
+    return Path.home()
+
+
+def state_dir_for(home: Path) -> Path:
+    return home / ".codealmanac"
+
+
+def global_state_dir() -> Path:
+    return state_dir_for(home_dir())
+
+
+def default_registry_path() -> Path:
+    return global_state_dir() / "registry.json"
+
+
+def default_config_path() -> Path:
+    return global_state_dir() / "config.toml"
+
+
+def normalize_path(path: Path) -> Path:
+    return path.expanduser().resolve(strict=False)

codealmanac/core/slug.py

@@ -0,0 +1,7 @@
+import re
+
+
+def to_kebab_case(value: str) -> str:
+    text = value.strip().lower()
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    return text.strip("-")

codealmanac/core/text.py

@@ -0,0 +1,5 @@
+def required_text(value: str, field_name: str) -> str:
+    text = value.strip()
+    if not text:
+        raise ValueError(f"{field_name} must not be empty")
+    return text

codealmanac/database/__init__.py

@@ -0,0 +1,15 @@
+from codealmanac.database.sqlite import (
+    SQLiteConnection,
+    SQLiteMigration,
+    SQLiteRow,
+    apply_migrations,
+    connect_sqlite,
+)
+
+__all__ = (
+    "SQLiteConnection",
+    "SQLiteMigration",
+    "SQLiteRow",
+    "apply_migrations",
+    "connect_sqlite",
+)

codealmanac/database/sqlite.py

@@ -0,0 +1,54 @@
+import sqlite3
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+
+type SQLiteConnection = sqlite3.Connection
+type SQLiteRow = sqlite3.Row
+
+
+class SQLiteMigration(CodeAlmanacModel):
+    version: int
+    sql: str
+
+    @field_validator("version")
+    @classmethod
+    def positive_version(cls, value: int) -> int:
+        if value <= 0:
+            raise ValueError("SQLite migration version must be positive")
+        return value
+
+    @field_validator("sql")
+    @classmethod
+    def require_sql(cls, value: str) -> str:
+        return required_text(value, "SQLite migration SQL")
+
+
+def connect_sqlite(path: Path) -> SQLiteConnection:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    connection = sqlite3.connect(path)
+    connection.row_factory = sqlite3.Row
+    connection.execute("PRAGMA foreign_keys = ON")
+    connection.execute("PRAGMA journal_mode = WAL")
+    return connection
+
+
+def apply_migrations(
+    connection: SQLiteConnection,
+    migrations: tuple[SQLiteMigration, ...],
+) -> None:
+    current = user_version(connection)
+    for migration in sorted(migrations, key=lambda item: item.version):
+        if migration.version <= current:
+            continue
+        connection.executescript(migration.sql)
+        connection.execute(f"PRAGMA user_version = {migration.version}")
+        current = migration.version
+    connection.commit()
+
+
+def user_version(connection: SQLiteConnection) -> int:
+    return int(connection.execute("PRAGMA user_version").fetchone()[0])

codealmanac/integrations/__init__.py

@@ -0,0 +1 @@
+"""Concrete outside-world adapters."""

codealmanac/integrations/automation/__init__.py

@@ -0,0 +1,3 @@
+from codealmanac.integrations.automation.scheduler import LaunchdSchedulerAdapter
+
+__all__ = ["LaunchdSchedulerAdapter"]

codealmanac/integrations/automation/scheduler/__init__.py

@@ -0,0 +1,5 @@
+from codealmanac.integrations.automation.scheduler.launchd import (
+    LaunchdSchedulerAdapter,
+)
+
+__all__ = ["LaunchdSchedulerAdapter"]

codealmanac/integrations/automation/scheduler/launchd.py

@@ -0,0 +1,163 @@
+import os
+import plistlib
+import subprocess
+from datetime import timedelta
+from pathlib import Path
+
+from codealmanac.core.errors import ExecutionFailed
+from codealmanac.services.automation.models import (
+    EnvironmentVariable,
+    ScheduledJob,
+    ScheduledJobStatus,
+)
+
+
+class LaunchdSchedulerAdapter:
+    def install(self, job: ScheduledJob) -> ScheduledJobStatus:
+        job.plist_path.parent.mkdir(parents=True, exist_ok=True)
+        job.stdout_path.parent.mkdir(parents=True, exist_ok=True)
+        job.stderr_path.parent.mkdir(parents=True, exist_ok=True)
+        with job.plist_path.open("wb") as handle:
+            plistlib.dump(launchd_plist(job), handle, sort_keys=False)
+        self._bootout(job)
+        self._bootstrap(job)
+        return self.status(job)
+
+    def uninstall(self, job: ScheduledJob) -> bool:
+        if not job.plist_path.exists():
+            return False
+        self._bootout(job)
+        job.plist_path.unlink(missing_ok=True)
+        return True
+
+    def status(self, job: ScheduledJob) -> ScheduledJobStatus:
+        if not job.plist_path.exists():
+            return ScheduledJobStatus(
+                task=job.task,
+                label=job.label,
+                plist_path=job.plist_path,
+                installed=False,
+                loaded=self._is_loaded(job),
+            )
+        data = read_plist(job.plist_path)
+        return ScheduledJobStatus(
+            task=job.task,
+            label=job.label,
+            plist_path=job.plist_path,
+            installed=True,
+            loaded=self._is_loaded(job),
+            interval=read_interval(data),
+            quiet=read_quiet(data),
+        )
+
+    def _bootstrap(self, job: ScheduledJob) -> None:
+        result = self._run_launchctl(
+            ("bootstrap", launchd_target(), str(job.plist_path))
+        )
+        if result.returncode != 0:
+            raise ExecutionFailed(
+                "launchctl bootstrap failed for "
+                f"{job.label}: {surface_process_error(result)}"
+            )
+
+    def _bootout(self, job: ScheduledJob) -> None:
+        self._run_launchctl(("bootout", launchd_target(), str(job.plist_path)))
+
+    def _is_loaded(self, job: ScheduledJob) -> bool:
+        result = self._run_launchctl(("print", f"{launchd_target()}/{job.label}"))
+        return result.returncode == 0
+
+    def _run_launchctl(self, args: tuple[str, ...]) -> subprocess.CompletedProcess[str]:
+        try:
+            return subprocess.run(
+                ("launchctl", *args),
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+        except OSError as error:
+            return subprocess.CompletedProcess(
+                args=("launchctl", *args),
+                returncode=1,
+                stdout="",
+                stderr=str(error),
+            )
+
+
+def launchd_plist(job: ScheduledJob) -> dict[str, object]:
+    data: dict[str, object] = {
+        "Label": job.label,
+        "ProgramArguments": list(job.program_arguments),
+        "StartInterval": int(job.interval.total_seconds()),
+        "EnvironmentVariables": environment_dict(job.environment),
+        "RunAtLoad": True,
+        "StandardOutPath": str(job.stdout_path),
+        "StandardErrorPath": str(job.stderr_path),
+    }
+    if job.working_directory is not None:
+        data["WorkingDirectory"] = str(job.working_directory)
+    return data
+
+
+def read_plist(path: Path) -> dict[str, object]:
+    with path.open("rb") as handle:
+        data = plistlib.load(handle)
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+def read_interval(data: dict[str, object]) -> timedelta | None:
+    value = data.get("StartInterval")
+    if not isinstance(value, int):
+        return None
+    return timedelta(seconds=value)
+
+
+def read_quiet(data: dict[str, object]) -> timedelta | None:
+    args = data.get("ProgramArguments")
+    if not isinstance(args, list):
+        return None
+    values = [item for item in args if isinstance(item, str)]
+    try:
+        index = values.index("--quiet")
+    except ValueError:
+        return None
+    if index + 1 >= len(values):
+        return None
+    return parse_compact_duration(values[index + 1])
+
+
+def parse_compact_duration(value: str) -> timedelta | None:
+    if value.endswith("h"):
+        parsed = parse_int(value[:-1])
+        return None if parsed is None else timedelta(hours=parsed)
+    if value.endswith("m"):
+        parsed = parse_int(value[:-1])
+        return None if parsed is None else timedelta(minutes=parsed)
+    if value.endswith("s"):
+        parsed = parse_int(value[:-1])
+        return None if parsed is None else timedelta(seconds=parsed)
+    return None
+
+
+def parse_int(value: str) -> int | None:
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def environment_dict(values: tuple[EnvironmentVariable, ...]) -> dict[str, str]:
+    return {item.name: item.value for item in values}
+
+
+def launchd_target() -> str:
+    return f"gui/{os.getuid()}"
+
+
+def surface_process_error(result: subprocess.CompletedProcess[str]) -> str:
+    text = result.stderr.strip() or result.stdout.strip()
+    if len(text) > 500:
+        return f"{text[:500]}..."
+    return text or f"exit {result.returncode}"