codealmanac 0.1.0.dev0__py3-none-any.whl

codealmanac/services/automation/ports.py

@@ -0,0 +1,14 @@
+from typing import Protocol
+
+from codealmanac.services.automation.models import ScheduledJob, ScheduledJobStatus
+
+
+class SchedulerAdapter(Protocol):
+    def install(self, job: ScheduledJob) -> ScheduledJobStatus:
+        """Install and activate one scheduled job."""
+
+    def uninstall(self, job: ScheduledJob) -> bool:
+        """Remove one scheduled job. Return true when a plist was removed."""
+
+    def status(self, job: ScheduledJob) -> ScheduledJobStatus:
+        """Read persisted scheduler state for one job."""

codealmanac/services/automation/requests.py

@@ -0,0 +1,40 @@
+from datetime import timedelta
+from pathlib import Path
+
+from pydantic import field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.automation.models import AutomationTask
+
+
+class AutomationSelectionRequest(CodeAlmanacModel):
+    tasks: tuple[AutomationTask, ...] = ()
+    home: Path | None = None
+
+
+class InstallAutomationRequest(AutomationSelectionRequest):
+    cwd: Path
+    every: timedelta | None = None
+    quiet: timedelta | None = None
+    garden_every: timedelta | None = None
+    garden_off: bool = False
+    env_path: str | None = None
+    python_executable: Path | None = None
+
+    @field_validator("every", "quiet", "garden_every")
+    @classmethod
+    def non_negative_duration(
+        cls,
+        value: timedelta | None,
+    ) -> timedelta | None:
+        if value is not None and value.total_seconds() < 0:
+            raise ValueError("automation duration must be non-negative")
+        return value
+
+
+class UninstallAutomationRequest(AutomationSelectionRequest):
+    pass
+
+
+class AutomationStatusRequest(AutomationSelectionRequest):
+    pass

codealmanac/services/automation/service.py

@@ -0,0 +1,294 @@
+import os
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import timedelta
+from pathlib import Path
+
+from codealmanac.core.errors import ValidationFailed
+from codealmanac.core.paths import home_dir, normalize_path, state_dir_for
+from codealmanac.services.automation.models import (
+    AutomationInstallResult,
+    AutomationStatusReport,
+    AutomationTask,
+    AutomationUninstallResult,
+    AutomationWorkingDirectory,
+    EnvironmentVariable,
+    ScheduledJob,
+    ScheduledJobStatus,
+)
+from codealmanac.services.automation.ports import SchedulerAdapter
+from codealmanac.services.automation.requests import (
+    AutomationSelectionRequest,
+    AutomationStatusRequest,
+    InstallAutomationRequest,
+    UninstallAutomationRequest,
+)
+from codealmanac.services.config.models import DEFAULT_SYNC_QUIET
+from codealmanac.services.workspaces.service import WorkspacesService
+
+DEFAULT_SYNC_INTERVAL = timedelta(hours=5)
+DEFAULT_GARDEN_INTERVAL = timedelta(hours=4)
+AUTOMATION_SYNC_CLAIM_OWNER = "codealmanac.automation.sync"
+AUTOMATION_SYNC_PENDING_TIMEOUT = timedelta(hours=24)
+AUTOMATION_SYNC_MAX_FAILED_ATTEMPTS = 3
+
+SYNC_LABEL = "com.codealmanac.sync"
+GARDEN_LABEL = "com.codealmanac.garden"
+
+LAUNCHD_FALLBACK_PATHS = (
+    "/usr/local/bin",
+    "/opt/homebrew/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+)
+
+
+@dataclass(frozen=True)
+class AutomationTaskDefinition:
+    task: AutomationTask
+    label: str
+    default_interval: timedelta
+    stdout_log_name: str
+    stderr_log_name: str
+    working_directory: AutomationWorkingDirectory
+
+
+DEFAULT_INSTALL_TASKS = (AutomationTask.SYNC, AutomationTask.GARDEN)
+DEFAULT_STATUS_TASKS = (AutomationTask.SYNC, AutomationTask.GARDEN)
+
+
+class AutomationService:
+    def __init__(
+        self,
+        workspaces: WorkspacesService,
+        scheduler: SchedulerAdapter,
+    ):
+        self.workspaces = workspaces
+        self.scheduler = scheduler
+
+    def install(self, request: InstallAutomationRequest) -> AutomationInstallResult:
+        explicit_tasks = len(request.tasks) > 0
+        tasks = selected_tasks(request.tasks, DEFAULT_INSTALL_TASKS)
+        if explicit_tasks and request.garden_off:
+            raise ValidationFailed(
+                "--garden-off can only be used with the default automation install"
+            )
+        if explicit_tasks and len(tasks) > 1 and request.every is not None:
+            raise ValidationFailed(
+                "--every can only target one explicit automation task at a time"
+            )
+        if request.quiet is not None and request.quiet.total_seconds() < 0:
+            raise ValidationFailed("quiet window must be zero or greater")
+
+        selected = tuple(
+            task
+            for task in tasks
+            if not (task == AutomationTask.GARDEN and request.garden_off)
+        )
+        jobs = tuple(
+            self._job_for_task(
+                task,
+                request,
+                explicit_tasks,
+                resolve_working_directory=True,
+            )
+            for task in selected
+        )
+        for job in jobs:
+            self.scheduler.install(job)
+
+        disabled: tuple[ScheduledJob, ...] = ()
+        if not explicit_tasks and request.garden_off:
+            garden = self._job_for_task(
+                AutomationTask.GARDEN,
+                request,
+                explicit_tasks,
+                resolve_working_directory=False,
+            )
+            self.scheduler.uninstall(garden)
+            disabled = (garden,)
+
+        return AutomationInstallResult(jobs=jobs, disabled=disabled)
+
+    def uninstall(
+        self,
+        request: UninstallAutomationRequest,
+    ) -> AutomationUninstallResult:
+        tasks = selected_tasks(request.tasks, DEFAULT_STATUS_TASKS)
+        removed: list[Path] = []
+        for task in tasks:
+            job = self._job_for_task(
+                task,
+                base_request(request),
+                explicit_tasks=True,
+                resolve_working_directory=False,
+            )
+            if self.scheduler.uninstall(job):
+                removed.append(job.plist_path)
+        return AutomationUninstallResult(tasks=tasks, removed=tuple(removed))
+
+    def status(self, request: AutomationStatusRequest) -> AutomationStatusReport:
+        tasks = selected_tasks(request.tasks, DEFAULT_STATUS_TASKS)
+        statuses: list[ScheduledJobStatus] = []
+        for task in tasks:
+            job = self._job_for_task(
+                task,
+                base_request(request),
+                explicit_tasks=True,
+                resolve_working_directory=False,
+            )
+            statuses.append(self.scheduler.status(job))
+        return AutomationStatusReport(statuses=tuple(statuses))
+
+    def _job_for_task(
+        self,
+        task: AutomationTask,
+        request: InstallAutomationRequest,
+        explicit_tasks: bool,
+        resolve_working_directory: bool,
+    ) -> ScheduledJob:
+        definition = task_definition(task)
+        home = normalize_path(request.home or home_dir())
+        logs_dir = state_dir_for(home) / "logs"
+        return ScheduledJob(
+            task=task,
+            label=definition.label,
+            plist_path=plist_path_for(task, home),
+            program_arguments=program_arguments_for(task, request),
+            interval=interval_for(task, request, explicit_tasks),
+            environment=(
+                EnvironmentVariable(
+                    name="PATH",
+                    value=launch_path(home, request.env_path),
+                ),
+            ),
+            stdout_path=logs_dir / definition.stdout_log_name,
+            stderr_path=logs_dir / definition.stderr_log_name,
+            working_directory=self._working_directory(definition, request.cwd)
+            if resolve_working_directory
+            else None,
+        )
+
+    def _working_directory(
+        self,
+        definition: AutomationTaskDefinition,
+        cwd: Path,
+    ) -> Path | None:
+        if definition.working_directory == AutomationWorkingDirectory.NONE:
+            return None
+        return self.workspaces.resolve(cwd).root_path
+
+
+def base_request(
+    request: AutomationSelectionRequest,
+) -> InstallAutomationRequest:
+    return InstallAutomationRequest(
+        cwd=Path.cwd(),
+        tasks=request.tasks,
+        home=request.home,
+    )
+
+
+def task_definition(task: AutomationTask) -> AutomationTaskDefinition:
+    if task == AutomationTask.SYNC:
+        return AutomationTaskDefinition(
+            task=AutomationTask.SYNC,
+            label=SYNC_LABEL,
+            default_interval=DEFAULT_SYNC_INTERVAL,
+            stdout_log_name="sync.out.log",
+            stderr_log_name="sync.err.log",
+            working_directory=AutomationWorkingDirectory.NONE,
+        )
+    return AutomationTaskDefinition(
+        task=AutomationTask.GARDEN,
+        label=GARDEN_LABEL,
+        default_interval=DEFAULT_GARDEN_INTERVAL,
+        stdout_log_name="garden.out.log",
+        stderr_log_name="garden.err.log",
+        working_directory=AutomationWorkingDirectory.CURRENT_WIKI,
+    )
+
+
+def selected_tasks(
+    requested: Sequence[AutomationTask],
+    defaults: tuple[AutomationTask, ...],
+) -> tuple[AutomationTask, ...]:
+    tasks = tuple(requested) if len(requested) > 0 else defaults
+    selected: list[AutomationTask] = []
+    for task in tasks:
+        if task not in selected:
+            selected.append(task)
+    return tuple(selected)
+
+
+def interval_for(
+    task: AutomationTask,
+    request: InstallAutomationRequest,
+    explicit_tasks: bool,
+) -> timedelta:
+    if task == AutomationTask.SYNC:
+        return request.every or DEFAULT_SYNC_INTERVAL
+    if request.garden_every is not None:
+        return request.garden_every
+    if explicit_tasks and request.every is not None:
+        return request.every
+    return DEFAULT_GARDEN_INTERVAL
+
+
+def program_arguments_for(
+    task: AutomationTask,
+    request: InstallAutomationRequest,
+) -> tuple[str, ...]:
+    executable = request.python_executable or Path(sys.executable)
+    base = (str(executable), "-m", "codealmanac.cli.main")
+    if task == AutomationTask.SYNC:
+        quiet = request.quiet or DEFAULT_SYNC_QUIET
+        return (
+            *base,
+            "sync",
+            "--quiet",
+            duration_text(quiet),
+            "--claim-owner",
+            AUTOMATION_SYNC_CLAIM_OWNER,
+            "--pending-timeout",
+            duration_text(AUTOMATION_SYNC_PENDING_TIMEOUT),
+            "--max-failed-attempts",
+            str(AUTOMATION_SYNC_MAX_FAILED_ATTEMPTS),
+        )
+    return (*base, "garden")
+
+
+def plist_path_for(task: AutomationTask, home: Path) -> Path:
+    definition = task_definition(task)
+    return home / "Library/LaunchAgents" / f"{definition.label}.plist"
+
+
+def launch_path(home: Path, env_path: str | None) -> str:
+    values = [
+        item.strip()
+        for item in (env_path or os.environ.get("PATH", "")).split(":")
+        if item.strip()
+    ]
+    values.extend([str(home / ".local/bin"), str(home / ".bun/bin")])
+    values.extend(LAUNCHD_FALLBACK_PATHS)
+    return ":".join(unique(values))
+
+
+def unique(values: Sequence[str]) -> tuple[str, ...]:
+    seen: list[str] = []
+    for value in values:
+        if value not in seen:
+            seen.append(value)
+    return tuple(seen)
+
+
+def duration_text(value: timedelta) -> str:
+    seconds = int(value.total_seconds())
+    if seconds % 3600 == 0:
+        return f"{seconds // 3600}h"
+    if seconds % 60 == 0:
+        return f"{seconds // 60}m"
+    return f"{seconds}s"

codealmanac/services/config/__init__.py

@@ -0,0 +1,17 @@
+from codealmanac.services.config.models import (
+    CodeAlmanacConfig,
+    HarnessConfig,
+    SyncConfig,
+)
+from codealmanac.services.config.requests import LoadConfigRequest
+from codealmanac.services.config.service import ConfigService
+from codealmanac.services.config.store import ConfigStore
+
+__all__ = [
+    "CodeAlmanacConfig",
+    "ConfigService",
+    "ConfigStore",
+    "HarnessConfig",
+    "LoadConfigRequest",
+    "SyncConfig",
+]

codealmanac/services/config/models.py

@@ -0,0 +1,61 @@
+from datetime import timedelta
+from typing import Any
+
+from humanfriendly import InvalidTimespan, parse_timespan
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.services.harnesses.models import HarnessKind
+
+DEFAULT_HARNESS = HarnessKind.CLAUDE
+DEFAULT_SYNC_QUIET = timedelta(minutes=45)
+
+
+class HarnessConfig(CodeAlmanacModel):
+    default: HarnessKind = DEFAULT_HARNESS
+
+
+class SyncConfig(CodeAlmanacModel):
+    quiet: timedelta = DEFAULT_SYNC_QUIET
+
+    @field_validator("quiet", mode="before")
+    @classmethod
+    def parse_quiet(cls, value: Any) -> Any:
+        return parse_duration(value, "sync.quiet")
+
+    @field_validator("quiet")
+    @classmethod
+    def require_non_negative_quiet(cls, value: timedelta) -> timedelta:
+        if value.total_seconds() < 0:
+            raise ValueError("sync.quiet must be zero or greater")
+        return value
+
+
+class CodeAlmanacConfig(BaseSettings):
+    model_config = SettingsConfigDict(frozen=True, extra="forbid")
+
+    harness: HarnessConfig = Field(default_factory=HarnessConfig)
+    sync: SyncConfig = Field(default_factory=SyncConfig)
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls,
+        init_settings,
+        env_settings,
+        dotenv_settings,
+        file_secret_settings,
+    ):
+        return (init_settings,)
+
+
+def parse_duration(value: Any, label: str) -> Any:
+    if value is None or isinstance(value, timedelta):
+        return value
+    if not isinstance(value, str):
+        return value
+    try:
+        return timedelta(seconds=parse_timespan(value))
+    except InvalidTimespan as error:
+        raise ValueError(f"{label} must be a duration") from error

codealmanac/services/config/requests.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+from pydantic import Field, field_validator
+
+from codealmanac.core.models import CodeAlmanacModel
+from codealmanac.core.text import required_text
+
+
+class LoadConfigRequest(CodeAlmanacModel):
+    cwd: Path
+    wiki: str | None = Field(
+        default=None,
+        description="None means use the nearest project config.",
+    )
+
+    @field_validator("wiki")
+    @classmethod
+    def require_wiki(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return required_text(value, "wiki selector")

codealmanac/services/config/service.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+from codealmanac.core.errors import NotFoundError
+from codealmanac.core.paths import normalize_path
+from codealmanac.services.config.models import CodeAlmanacConfig
+from codealmanac.services.config.requests import LoadConfigRequest
+from codealmanac.services.config.store import ConfigStore
+from codealmanac.services.workspaces.requests import SelectWorkspaceRequest
+from codealmanac.services.workspaces.service import WorkspacesService
+
+PROJECT_CONFIG_NAME = "config.toml"
+
+
+class ConfigService:
+    def __init__(
+        self,
+        workspaces: WorkspacesService,
+        store: ConfigStore,
+        user_config_path: Path,
+    ):
+        self.workspaces = workspaces
+        self.store = store
+        self.user_config_path = user_config_path
+
+    def load(self, request: LoadConfigRequest) -> CodeAlmanacConfig:
+        project_config_path = self._project_config_path(request)
+        paths = config_source_paths(
+            user_config_path=normalize_path(self.user_config_path),
+            project_config_path=project_config_path,
+        )
+        return self.store.load(paths)
+
+    def _project_config_path(self, request: LoadConfigRequest) -> Path | None:
+        if request.wiki is not None:
+            workspace = self.workspaces.select(
+                SelectWorkspaceRequest(
+                    selector=request.wiki,
+                    base_path=request.cwd,
+                )
+            )
+            return workspace.almanac_path / PROJECT_CONFIG_NAME
+        try:
+            workspace = self.workspaces.resolve(request.cwd)
+        except (NotFoundError, OSError):
+            return None
+        return workspace.almanac_path / PROJECT_CONFIG_NAME
+
+
+def config_source_paths(
+    user_config_path: Path,
+    project_config_path: Path | None,
+) -> tuple[Path, ...]:
+    if project_config_path is None:
+        return (user_config_path,)
+    return (project_config_path, user_config_path)

codealmanac/services/config/store.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+from tomllib import TOMLDecodeError
+
+from pydantic import ValidationError
+from pydantic_settings import TomlConfigSettingsSource
+
+from codealmanac.core.errors import ValidationFailed
+from codealmanac.services.config.models import CodeAlmanacConfig
+
+
+class ConfigStore:
+    def load(self, paths: tuple[Path, ...]) -> CodeAlmanacConfig:
+        try:
+            sources = tuple(
+                TomlConfigSettingsSource(
+                    CodeAlmanacConfig,
+                    toml_file=path,
+                    deep_merge=True,
+                )
+                for path in paths
+            )
+            return CodeAlmanacConfig(_build_sources=(sources, {}))
+        except TOMLDecodeError as error:
+            raise ValidationFailed(f"invalid config TOML: {error}") from error
+        except ValidationError as error:
+            raise ValidationFailed(f"invalid config: {error}") from error

codealmanac/services/diagnostics/__init__.py

@@ -0,0 +1 @@
+"""Local diagnostics service."""

codealmanac/services/diagnostics/models.py

@@ -0,0 +1,22 @@
+from enum import StrEnum
+
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class DoctorStatus(StrEnum):
+    OK = "ok"
+    INFO = "info"
+    PROBLEM = "problem"
+
+
+class DoctorCheck(CodeAlmanacModel):
+    key: str
+    status: DoctorStatus
+    message: str
+    fix: str | None = None
+
+
+class DoctorReport(CodeAlmanacModel):
+    version: str
+    install: tuple[DoctorCheck, ...]
+    wiki: tuple[DoctorCheck, ...]

codealmanac/services/diagnostics/requests.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from codealmanac.core.models import CodeAlmanacModel
+
+
+class DoctorRequest(CodeAlmanacModel):
+    cwd: Path
+    wiki: str | None = None