@ahmed-g-gad/apothem 0.1.1

package/src/apothem/lib/contexts.py

@@ -0,0 +1,352 @@
+# SPDX-License-Identifier: MIT
+
+"""Agnostic contexts surface — injectable, enable/disable-able prompt fragments.
+
+A *context fragment* is dynamic injectable text the operator can toggle on or
+off, with optional activation metadata describing when it applies. The shape is
+neutral: it carries no tool-specific or vendor-specific identifier, so the same
+fragment applies across any installation target.
+
+This module defines the in-memory fragment value type, schema validation against
+the packaged ``context-fragment.schema.json``, and a :class:`ContextStore` that
+persists fragments deterministically under a :class:`~apothem.lib.data_home.DataHome`'s
+``contexts`` directory.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from jsonschema import Draft202012Validator
+
+from apothem.lib.atomic_io import advisory_lock, write_bytes_atomically
+from apothem.lib.data_home import DataHome
+from apothem.schemas import context_fragment_schema_path
+
+#: The deterministic on-disk filename holding the fragment array.
+_FRAGMENTS_FILENAME: Final[str] = "fragments.json"
+
+#: The advisory-lock filename guarding the fragment read-modify-write window.
+_FRAGMENTS_LOCK_FILENAME: Final[str] = ".fragments.lock"
+
+
+class ContextError(ValueError):
+    """Raised when a fragment fails validation or a store operation is invalid."""
+
+
+@dataclass(frozen=True)
+class Activation:
+    """Metadata describing when a fragment activates.
+
+    Attributes:
+        scope: Activation breadth (``global`` | ``session`` | ``task``), or
+            ``None`` when unspecified.
+        triggers: Phrases or signals that activate the fragment.
+    """
+
+    scope: str | None = None
+    triggers: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize to a schema-conforming mapping, omitting empty optionals.
+
+        Returns:
+            A mapping carrying only the populated activation fields.
+        """
+        data: dict[str, object] = {}
+        if self.scope is not None:
+            data["scope"] = self.scope
+        if self.triggers:
+            data["triggers"] = list(self.triggers)
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, object]) -> Activation:
+        """Reconstruct an :class:`Activation` from a mapping.
+
+        Args:
+            data: A mapping carrying ``scope`` and/or ``triggers``.
+
+        Returns:
+            The reconstructed activation.
+        """
+        raw_scope = data.get("scope")
+        scope = raw_scope if isinstance(raw_scope, str) else None
+        raw_triggers = data.get("triggers")
+        triggers: tuple[str, ...] = (
+            tuple(str(item) for item in raw_triggers)
+            if isinstance(raw_triggers, list)
+            else ()
+        )
+        return cls(scope=scope, triggers=triggers)
+
+
+@dataclass(frozen=True)
+class ContextFragment:
+    """One named, injectable prompt or context fragment.
+
+    Attributes:
+        id: Stable identifier, unique within a contexts store.
+        name: Human-readable fragment name.
+        body: The injectable prompt or context text.
+        enabled: Enable/disable switch; when ``False`` the fragment is retained
+            but never injected.
+        activation: Optional activation metadata, or ``None``.
+        tags: Discovery tags.
+        updated: Optional ISO 8601 timestamp of the last amendment.
+    """
+
+    id: str
+    name: str
+    body: str
+    enabled: bool
+    activation: Activation | None = None
+    tags: tuple[str, ...] = ()
+    updated: str | None = None
+
+    def to_dict(self) -> dict[str, object]:
+        """Serialize to a schema-conforming mapping, omitting empty optionals.
+
+        The required fields (``id``, ``name``, ``body``, ``enabled``) are always
+        present; optional fields are emitted only when populated so the output
+        validates under ``additionalProperties: false``.
+
+        Returns:
+            A mapping ready for JSON serialization and schema validation.
+        """
+        data: dict[str, object] = {
+            "id": self.id,
+            "name": self.name,
+            "body": self.body,
+            "enabled": self.enabled,
+        }
+        if self.activation is not None:
+            activation = self.activation.to_dict()
+            if activation:
+                data["activation"] = activation
+        if self.tags:
+            data["tags"] = list(self.tags)
+        if self.updated is not None:
+            data["updated"] = self.updated
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, object]) -> ContextFragment:
+        """Reconstruct a :class:`ContextFragment` from a mapping.
+
+        Args:
+            data: A mapping carrying the fragment fields.
+
+        Returns:
+            The reconstructed fragment.
+
+        Raises:
+            ContextError: When a required field is absent or carries the wrong
+                type.
+        """
+        try:
+            identifier = data["id"]
+            name = data["name"]
+            body = data["body"]
+            enabled = data["enabled"]
+        except KeyError as exc:
+            raise ContextError(f"fragment is missing required field: {exc}") from exc
+        if not (
+            isinstance(identifier, str)
+            and isinstance(name, str)
+            and isinstance(body, str)
+            and isinstance(enabled, bool)
+        ):
+            raise ContextError("fragment carries a field of the wrong type")
+        raw_activation = data.get("activation")
+        activation = (
+            Activation.from_dict(raw_activation)
+            if isinstance(raw_activation, Mapping)
+            else None
+        )
+        raw_tags = data.get("tags")
+        tags: tuple[str, ...] = (
+            tuple(str(item) for item in raw_tags) if isinstance(raw_tags, list) else ()
+        )
+        raw_updated = data.get("updated")
+        updated = raw_updated if isinstance(raw_updated, str) else None
+        return cls(
+            id=identifier,
+            name=name,
+            body=body,
+            enabled=enabled,
+            activation=activation,
+            tags=tags,
+            updated=updated,
+        )
+
+
+def _validator() -> Draft202012Validator:
+    """Build a validator bound to the packaged context-fragment schema.
+
+    Returns:
+        A draft-2020-12 validator for a single fragment instance.
+    """
+    schema = json.loads(context_fragment_schema_path().read_text(encoding="utf-8"))
+    return Draft202012Validator(schema)
+
+
+def validate_fragment(data: Mapping[str, object]) -> None:
+    """Validate a fragment mapping against the packaged schema.
+
+    Args:
+        data: The candidate fragment mapping.
+
+    Raises:
+        ContextError: When the mapping violates the schema; the message lists
+            every validation error.
+    """
+    errors = sorted(_validator().iter_errors(data), key=lambda error: error.path)
+    if errors:
+        joined = "; ".join(error.message for error in errors)
+        raise ContextError(f"invalid context fragment: {joined}")
+
+
+@dataclass(frozen=True)
+class ContextStore:
+    """Deterministic persistence for fragments under a data home.
+
+    The store reads and writes ``fragments.json`` within the data home's
+    ``contexts`` directory. The on-disk array is sorted by fragment id so the
+    serialization is byte-stable across runs.
+
+    Attributes:
+        data_home: The per-target data home whose ``contexts`` directory backs
+            this store.
+    """
+
+    data_home: DataHome
+
+    @property
+    def _lock_path(self) -> Path:
+        """Return the advisory-lock path guarding the fragments RMW window."""
+        return self.data_home.contexts / _FRAGMENTS_LOCK_FILENAME
+
+    def _read_raw(self) -> list[dict[str, object]]:
+        """Read the raw fragment mappings from disk.
+
+        Returns:
+            The stored mappings, or an empty list when the file is absent.
+        """
+        path = self.data_home.contexts / _FRAGMENTS_FILENAME
+        if not path.is_file():
+            return []
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(loaded, list):
+            raise ContextError(f"{path} does not hold a JSON array")
+        return [dict(entry) for entry in loaded]
+
+    def _write_raw(self, entries: list[dict[str, object]]) -> None:
+        """Persist fragment mappings deterministically.
+
+        Args:
+            entries: The fragment mappings to serialize.
+        """
+        self.data_home.contexts.mkdir(parents=True, exist_ok=True)
+        ordered = sorted(entries, key=lambda entry: str(entry["id"]))
+        path = self.data_home.contexts / _FRAGMENTS_FILENAME
+        serialized = json.dumps(ordered, indent=2, sort_keys=True, ensure_ascii=False)
+        write_bytes_atomically(path, (serialized + "\n").encode("utf-8"))
+
+    def ensure_initialized(self) -> Path:
+        """Create the canonical fragments file as an empty store when absent.
+
+        Materialization calls this so a freshly-installed target carries a
+        concrete, empty contexts artifact. The operation is idempotent and
+        non-destructive: an existing fragments file is left untouched, so
+        re-materializing a populated store never loses fragments.
+
+        Returns:
+            The path to the canonical fragments file.
+        """
+        path = self.data_home.contexts / _FRAGMENTS_FILENAME
+        # Serialize the check-then-write under the same lock add()/set_enabled()
+        # hold, so a concurrent first add() cannot create the file with a
+        # fragment between the existence check and the empty-store write.
+        with advisory_lock(self._lock_path):
+            if not path.is_file():
+                self._write_raw([])
+        return path
+
+    def fragments(self) -> list[ContextFragment]:
+        """Return every stored fragment, sorted by id.
+
+        Returns:
+            The fragments, or an empty list when the store is absent.
+        """
+        return [ContextFragment.from_dict(entry) for entry in self._read_raw()]
+
+    def enabled_fragments(self) -> list[ContextFragment]:
+        """Return only the fragments whose enable switch is on.
+
+        Returns:
+            The enabled fragments, sorted by id.
+        """
+        return [fragment for fragment in self.fragments() if fragment.enabled]
+
+    def contains(self, fragment_id: str) -> bool:
+        """Report whether a fragment with *fragment_id* is stored.
+
+        Args:
+            fragment_id: The identifier to look up.
+
+        Returns:
+            ``True`` when a fragment with that id exists.
+        """
+        return any(entry["id"] == fragment_id for entry in self._read_raw())
+
+    def add(self, fragment: ContextFragment) -> None:
+        """Validate and persist a fragment, replacing any same-id fragment.
+
+        Args:
+            fragment: The fragment to store.
+
+        Raises:
+            ContextError: When the fragment fails schema validation.
+        """
+        data = fragment.to_dict()
+        validate_fragment(data)
+        self.data_home.contexts.mkdir(parents=True, exist_ok=True)
+        # Serialize the RMW window so concurrent writers cannot lose a fragment.
+        with advisory_lock(self._lock_path):
+            entries = [e for e in self._read_raw() if e["id"] != fragment.id]
+            entries.append(data)
+            self._write_raw(entries)
+
+    def set_enabled(self, fragment_id: str, enabled: bool) -> None:
+        """Flip a stored fragment's enable switch and persist.
+
+        Args:
+            fragment_id: The identifier of the fragment to toggle.
+            enabled: The new enable state.
+
+        Raises:
+            ContextError: When no fragment with *fragment_id* is stored.
+        """
+        self.data_home.contexts.mkdir(parents=True, exist_ok=True)
+        with advisory_lock(self._lock_path):
+            entries = self._read_raw()
+            for entry in entries:
+                if entry["id"] == fragment_id:
+                    entry["enabled"] = enabled
+                    self._write_raw(entries)
+                    return
+            raise ContextError(f"no fragment with id {fragment_id!r}")
+
+
+__all__ = [
+    "Activation",
+    "ContextError",
+    "ContextFragment",
+    "ContextStore",
+    "validate_fragment",
+]

package/src/apothem/lib/data_home.py

@@ -0,0 +1,255 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared data-home resolution for the memory, contexts, and plans surfaces.
+
+Every base directory receives ONE Apothem-owned working directory shared across
+every installation target. The operator's durable memory records, injectable
+context fragments, and captured learning signals live in that single home — a
+write under one harness is visible to every other harness sharing the base. This
+module derives the home deterministically from a base directory and the
+working-directory name, so two harnesses installing into the same base resolve
+to the same home rather than per-harness silos.
+
+The data home is an Apothem-owned subtree (``<base>/.apothem/``) beneath the
+base directory. Memory, contexts, learning, and plans each get a dedicated
+child directory so the surfaces never collide.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from apothem.lib.profile import WorkspaceConfig
+
+#: The Apothem-owned subtree name placed under the base directory.
+_APOTHEM_SUBTREE: str = ".apothem"
+
+#: The plans child directory name beneath the shared working directory.
+_PLANS_CHILD: str = "plans"
+
+
+class DataHomeError(ValueError):
+    """Raised when a data home cannot be resolved from the given inputs."""
+
+
+@dataclass(frozen=True)
+class DataHome:
+    """The shared on-disk home for an Apothem base directory's data surfaces.
+
+    One home is shared across every installation target rooted at the same
+    base; the surfaces are never per-harness.
+
+    Attributes:
+        root: The Apothem-owned root directory for the shared data.
+        plans: The directory holding plan suites.
+        memory: The directory holding durable memory records.
+        contexts: The directory holding injectable context fragments.
+        learning: The directory holding captured learning signals.
+    """
+
+    root: Path
+    plans: Path
+    memory: Path
+    contexts: Path
+    learning: Path
+
+    def ensure(self) -> DataHome:
+        """Create the data-home directory tree if absent and return self.
+
+        Creating an existing tree is a no-op, so the call is idempotent and
+        never disturbs records already written under any of the surfaces. The
+        ``plans`` child is included so the shared working directory carries its
+        plan-suite home alongside the data stores.
+
+        Returns:
+            This :class:`DataHome`, for call chaining.
+        """
+        for directory in (
+            self.root,
+            self.plans,
+            self.memory,
+            self.contexts,
+            self.learning,
+        ):
+            directory.mkdir(parents=True, exist_ok=True)
+        return self
+
+
+def resolve_shared_data_home(
+    *, base: Path, directory_name: str = ".apothem"
+) -> DataHome:
+    """Resolve the SHARED Apothem working directory beneath *base*.
+
+    All harnesses installing into the same *base* resolve to the SAME home:
+    memory, contexts, learning, and plans are shared, never per-harness. The
+    home is ``<base>/<directory_name>/`` with ``plans/``, ``memory/``,
+    ``contexts/``, and ``learning/`` children.
+
+    Args:
+        base: The base directory the working directory sits beneath — the
+            project root or the user home, as :func:`resolve_workspace_base`
+            selects from the profile's ``workspace.scope``.
+        directory_name: The shared working-directory name. Defaults to
+            ``".apothem"`` and is overridable from the profile's
+            ``workspace.directory_name``. Must be a single path component.
+
+    Returns:
+        A :class:`DataHome` with absolute child paths. The directories are
+        not created; call :meth:`DataHome.ensure` to materialize the tree.
+
+    Raises:
+        DataHomeError: When *directory_name* is empty, carries a path separator
+            or a drive specifier (``:``), or is a ``.`` / ``..`` component.
+    """
+    name = _validate_directory_name(directory_name)
+    root = base / name
+    return DataHome(
+        root=root,
+        plans=root / _PLANS_CHILD,
+        memory=root / "memory",
+        contexts=root / "contexts",
+        learning=root / "learning",
+    )
+
+
+def _validate_directory_name(directory_name: str) -> str:
+    """Return *directory_name* stripped, or raise if it is not one component.
+
+    The working-directory name must be exactly one path component so that
+    joining it onto a base never escapes the base. The guard rejects path
+    separators, a Windows drive specifier (``:``, which would reset pathlib to
+    the drive root), and the ``.`` / ``..`` traversal components.
+
+    Args:
+        directory_name: The candidate working-directory name.
+
+    Returns:
+        The stripped, validated single-component name.
+
+    Raises:
+        DataHomeError: When *directory_name* is empty, carries a separator or a
+            drive specifier (``:``), or is a ``.`` / ``..`` component.
+    """
+    name = directory_name.strip()
+    if not name:
+        raise DataHomeError("directory_name must be a non-empty string")
+    if "/" in name or "\\" in name or ":" in name or name in {".", ".."}:
+        raise DataHomeError(
+            f"directory_name must be a single path component, got {directory_name!r}"
+        )
+    return name
+
+
+def resolve_workspace_base(
+    *, workspace: WorkspaceConfig, project_root: Path, home: Path
+) -> Path:
+    """Resolve the base directory the shared working directory sits beneath.
+
+    The *workspace* scope selects which root the working directory is anchored
+    to: ``"project-local"`` (the default) roots it at *project_root*, while
+    ``"user-home"`` roots it at *home*. The mapping is pure and deterministic;
+    no filesystem access occurs.
+
+    The default scope reproduces today's behavior (base equals the project
+    root), so a profile that omits ``workspace`` resolves the shared home under
+    the install root exactly as the pre-relocation layout did.
+
+    Args:
+        workspace: The profile's workspace configuration carrying ``scope``.
+        project_root: The project root used when ``scope`` is project-local.
+        home: The user home directory used when ``scope`` is user-home.
+
+    Returns:
+        *project_root* for the project-local scope, *home* for the user-home
+        scope.
+
+    Raises:
+        DataHomeError: When ``workspace.scope`` is neither ``"project-local"``
+            nor ``"user-home"``.
+    """
+    scope = workspace.scope
+    if scope == "project-local":
+        return project_root
+    if scope == "user-home":
+        return home
+    raise DataHomeError(
+        f"workspace.scope must be 'project-local' or 'user-home', got {scope!r}"
+    )
+
+
+def resolve_install_data_home(
+    root: Path, *, profile: dict[str, object] | None
+) -> DataHome:
+    """Resolve the shared data home an install pass into *root* materializes.
+
+    The base is derived from the install *profile*'s ``workspace`` block:
+    project-local scope (the default) roots the shared home at *root*; user-home
+    scope roots it at the user home. The directory name (default ``.apothem``)
+    is the working-directory name. When *profile* is ``None`` (the
+    non-interactive path) or omits ``workspace``, the base is *root* and the name
+    is ``.apothem`` — behavior-preserving for the base while the harness segment
+    is collapsed.
+
+    Args:
+        root: The install root (harness root or project root) the shared working
+            directory is anchored to under project-local scope.
+        profile: The install profile dict carrying the ``workspace`` block, or
+            ``None`` for the non-interactive path.
+
+    Returns:
+        The shared :class:`DataHome` for the install pass. The directories are
+        not created; call :meth:`DataHome.ensure` to materialize the tree.
+    """
+    # Local import avoids a module-load cycle: profile.py is heavier and is only
+    # needed to coerce the workspace block here.
+    from apothem.lib.profile import WorkspaceConfig, coerce_profile
+
+    workspace = (
+        WorkspaceConfig() if profile is None else coerce_profile(profile).workspace
+    )
+    base = resolve_workspace_base(
+        workspace=workspace, project_root=root, home=Path.home()
+    )
+    return resolve_shared_data_home(base=base, directory_name=workspace.directory_name)
+
+
+def plans_root(*, base: Path, directory_name: str = ".apothem") -> Path:
+    """Return the future shared plans home ``<base>/<directory_name>/plans``.
+
+    This is the target plans location once Apothem consolidates its working
+    state into a single shared working directory. The path is computed purely;
+    no filesystem access occurs and the directory is not created.
+
+    This helper is currently unconsumed — additive plumbing for a later
+    relocation of plans from ``<project-root>/.plans`` to the shared working
+    directory.
+
+    Args:
+        base: The base directory the working directory sits beneath — the
+            project root or the user home, as :func:`resolve_workspace_base`
+            selects from the profile's ``workspace.scope``.
+        directory_name: The shared working-directory name. Defaults to
+            ``".apothem"`` and is overridable from the profile's
+            ``workspace.directory_name``. Must be a single path component.
+
+    Returns:
+        The path ``<base>/<directory_name>/plans``.
+
+    Raises:
+        DataHomeError: When *directory_name* is not a single path component.
+    """
+    name = _validate_directory_name(directory_name)
+    return base / name / _PLANS_CHILD
+
+
+__all__ = [
+    "DataHome",
+    "DataHomeError",
+    "plans_root",
+    "resolve_install_data_home",
+    "resolve_shared_data_home",
+    "resolve_workspace_base",
+]