julee-hcd 0.1.0__py3-none-any.whl

julee_hcd/__init__.py

@@ -0,0 +1,28 @@
+"""Human-centred design models.
+
+A julee kit. It holds the people a solution is for and what they are
+trying to do — personas, journeys, epics and stories — together with the
+applications and integrations that serve them, and the contributions and
+accelerators a solution draws on.
+
+It describes who a system is for rather than how it is built, so it
+carries no technical domain of its own. julee-viewpoints renders what a
+solution declares here into its documentation, and julee-c4 describes the
+same solution's structure.
+
+Install it, then adopt it::
+
+    [tool.julee]
+    kits = ["hcd"]
+"""
+
+from julee.core.entities.kit import Kit
+
+kit = Kit(
+    slug="hcd",
+    name="Human-centred design models",
+    package="julee_hcd",
+    viewpoint=True,
+)
+
+__all__ = ["kit"]

julee_hcd/domain/__init__.py

@@ -0,0 +1 @@
+"""The HCD domain: its entities and the repository protocols over them."""

julee_hcd/domain/models/__init__.py

@@ -0,0 +1,32 @@
+"""Human-centred design entities.
+
+The people a solution is for, what they are trying to do, and what serves
+them. Code structure is described by julee.core's own entities, which this
+kit reads rather than redefines.
+"""
+
+from .app import App, AppInterface, AppType
+from .base import Authored
+from .contrib import ContribModule
+from .epic import Epic
+from .integration import Direction, ExternalDependency, Integration
+from .journey import Journey, JourneyStep, StepType
+from .persona import Persona
+from .story import Story
+
+__all__ = [
+    "App",
+    "AppInterface",
+    "AppType",
+    "Authored",
+    "ContribModule",
+    "Direction",
+    "Epic",
+    "ExternalDependency",
+    "Integration",
+    "Journey",
+    "JourneyStep",
+    "Persona",
+    "StepType",
+    "Story",
+]

julee_hcd/domain/models/app.py

@@ -0,0 +1,229 @@
+"""App domain model.
+
+Represents an application in the HCD documentation system.
+Apps are defined via YAML manifests in apps/*/app.yaml.
+"""
+
+from enum import StrEnum
+
+from julee.core.utils import normalize_name
+from pydantic import Field, field_validator
+
+from .base import Authored
+
+
+class AppInterface(StrEnum):
+    """How people reach an app, which decides how it is drawn in C4."""
+
+    SPHINX = "sphinx"
+    API = "api"
+    MCP = "mcp"
+    WEB = "web"
+    CLI = "cli"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_string(cls, value: str) -> "AppInterface":
+        """The interface this names, or UNKNOWN if it names none of them."""
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.UNKNOWN
+
+    @property
+    def user_relationship(self) -> str:
+        """What a person does to the app, for the arrow into it."""
+        return {
+            AppInterface.SPHINX: "Writes RST",
+            AppInterface.API: "HTTP",
+            AppInterface.MCP: "MCP",
+            AppInterface.WEB: "Uses",
+            AppInterface.CLI: "Runs",
+        }.get(self, "Uses")
+
+    @property
+    def accelerator_relationship(self) -> str:
+        """What the app does to an accelerator, for the arrow out of it."""
+        return {
+            AppInterface.SPHINX: "Documents",
+            AppInterface.API: "Exposes",
+            AppInterface.MCP: "Provides tools for",
+            AppInterface.WEB: "Presents",
+            AppInterface.CLI: "Executes",
+        }.get(self, "Uses")
+
+
+class AppType(StrEnum):
+    """Application type classification."""
+
+    STAFF = "staff"
+    EXTERNAL = "external"
+    MEMBER_TOOL = "member-tool"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def from_string(cls, value: str) -> "AppType":
+        """Convert string to AppType, defaulting to UNKNOWN."""
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.UNKNOWN
+
+
+class App(Authored):
+    """Application entity.
+
+    Apps represent distinct applications in the system, defined via YAML
+    manifests. They serve as containers for stories and provide organization
+    for the documentation.
+    """
+
+    slug: str = Field(description='URL-safe identifier (e.g., "staff-portal")')
+    name: str = Field(description='Display name (e.g., "Staff Portal")')
+    app_type: AppType = Field(
+        default=AppType.UNKNOWN,
+        description="Classification (staff, external, member-tool)",
+    )
+    status: str | None = Field(
+        default=None,
+        description='Optional status indicator (e.g., "in-development", "live")',
+    )
+    description: str = Field(default="", description="Human-readable description")
+    interface: AppInterface = Field(
+        default=AppInterface.UNKNOWN,
+        description="How people reach this app, which decides how C4 draws it",
+    )
+    technology: str = Field(
+        default="",
+        description="What the app is built with; inferred from interface if blank",
+    )
+    accelerators: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="List of accelerator slugs associated with this app",
+    )
+    manifest_path: str = Field(default="", description="Path to the app.yaml file")
+    name_normalized: str = Field(default="", description="Lowercase name for matching")
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Validate slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return v.strip()
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @field_validator("name_normalized", mode="before")
+    @classmethod
+    def compute_name_normalized(cls, v: str, info) -> str:
+        """Compute normalized name from name if not provided."""
+        if v:
+            return v
+        name = info.data.get("name", "")
+        return normalize_name(name) if name else ""
+
+    def model_post_init(self, __context) -> None:
+        """Ensure normalized fields are computed after init."""
+        if not self.name_normalized and self.name:
+            object.__setattr__(self, "name_normalized", normalize_name(self.name))
+
+    @classmethod
+    def from_manifest(
+        cls,
+        slug: str,
+        manifest: dict,
+        manifest_path: str,
+    ) -> "App":
+        """Create an App from a parsed YAML manifest.
+
+        Args:
+            slug: App slug (usually directory name)
+            manifest: Parsed YAML content
+            manifest_path: Path to the manifest file
+
+        Returns:
+            App instance
+        """
+        name = manifest.get("name", slug.replace("-", " ").title())
+        app_type = AppType.from_string(manifest.get("type", "unknown"))
+
+        return cls(
+            slug=slug,
+            name=name,
+            app_type=app_type,
+            status=manifest.get("status"),
+            description=manifest.get("description", "").strip(),
+            accelerators=manifest.get("accelerators", []),
+            manifest_path=manifest_path,
+        )
+
+    def matches_type(self, app_type: AppType | str) -> bool:
+        """Check if this app matches the given type.
+
+        Args:
+            app_type: AppType enum or string to match
+
+        Returns:
+            True if app matches the type
+        """
+        if isinstance(app_type, str):
+            app_type = AppType.from_string(app_type)
+        return self.app_type == app_type
+
+    def matches_name(self, name: str) -> bool:
+        """Check if this app matches the given name (case-insensitive).
+
+        Args:
+            name: Name to match against
+
+        Returns:
+            True if normalized names match
+        """
+        return self.name_normalized == normalize_name(name)
+
+    @property
+    def type_label(self) -> str:
+        """Get human-readable type label."""
+        labels = {
+            AppType.STAFF: "Staff Application",
+            AppType.EXTERNAL: "External Application",
+            AppType.MEMBER_TOOL: "Member Tool",
+            AppType.UNKNOWN: "Unknown",
+        }
+        return labels.get(self.app_type, str(self.app_type))
+
+    @property
+    def interface_label(self) -> str:
+        """What to call this app's interface in a diagram."""
+        return {
+            AppInterface.SPHINX: "Sphinx Extension",
+            AppInterface.API: "REST API",
+            AppInterface.MCP: "MCP Server",
+            AppInterface.WEB: "Web Application",
+            AppInterface.CLI: "CLI Tool",
+            AppInterface.UNKNOWN: "Application",
+        }.get(self.interface, str(self.interface))
+
+    @property
+    def c4_technology(self) -> str:
+        """What to label this app's technology, guessing from its interface.
+
+        An app that says what it is built with is believed; one that does
+        not gets the usual answer for how it is reached.
+        """
+        if self.technology:
+            return self.technology
+        return {
+            AppInterface.SPHINX: "Python/Sphinx",
+            AppInterface.API: "FastAPI",
+            AppInterface.MCP: "FastMCP",
+            AppInterface.WEB: "Python",
+            AppInterface.CLI: "Python/Click",
+        }.get(self.interface, "Python")

julee_hcd/domain/models/base.py

@@ -0,0 +1,47 @@
+"""What every authored HCD entity carries besides its own content.
+
+A persona, an epic, a journey and the rest are written in RST and read
+back out of it, so each one remembers which document it came from and
+the prose that surrounded it. That is the same five fields every time,
+which is why they live here rather than being restated seven times.
+
+An entity derived from code rather than authored — a story read out of a
+feature file — still has them, because it may later be written back into
+a document alongside the ones that were authored.
+"""
+
+from julee.core.entities.entity import Entity
+from pydantic import Field
+
+
+class Authored(Entity):
+    """An entity a person wrote into a document, and can be written back.
+
+    The RST fields exist so a round-trip is lossless: reading a document
+    into entities and writing it out again should give back the document,
+    including the parts this kit does not model.
+    """
+
+    solution_slug: str = Field(
+        default="",
+        description=(
+            "Slug of the solution this belongs to, for a site documenting "
+            "more than one"
+        ),
+    )
+    docname: str = Field(
+        default="",
+        description="RST document this was read from, for incremental builds",
+    )
+    page_title: str = Field(
+        default="",
+        description="Title of the document, when it differs from the entity's own",
+    )
+    preamble_rst: str = Field(
+        default="",
+        description="Verbatim RST that preceded the directive, kept for round-trip",
+    )
+    epilogue_rst: str = Field(
+        default="",
+        description="Verbatim RST that followed the directive, kept for round-trip",
+    )

julee_hcd/domain/models/contrib.py

@@ -0,0 +1,45 @@
+"""Contrib module domain model.
+
+A contrib module is a reusable utility a solution picks up — a polling
+workflow, an authentication helper — as against an accelerator, which is
+a way of thinking about a problem. The difference is that a solution runs
+a contrib module and reasons with an accelerator.
+"""
+
+from pydantic import Field, field_validator
+
+from .base import Authored
+
+
+class ContribModule(Authored):
+    """A reusable utility a solution uses."""
+
+    slug: str = Field(description="Identifier for the contrib module")
+    name: str = Field(
+        default="", description="Display name; derived from slug if blank"
+    )
+    description: str = Field(default="", description="What the module does")
+    technology: str = Field(
+        default="Python", description="What the module is built with"
+    )
+    code_path: str = Field(
+        default="", description="Where the module's code lives in the repository"
+    )
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """A contrib module without a slug cannot be referred to."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return v.strip()
+
+    @property
+    def display_title(self) -> str:
+        """What to call the module, falling back to a readable slug."""
+        return self.name if self.name else self.slug.replace("-", " ").title()
+
+    @property
+    def c4_description(self) -> str:
+        """What to write on the module's box in a diagram."""
+        return self.description if self.description else f"{self.display_title} utility"

julee_hcd/domain/models/epic.py

@@ -0,0 +1,82 @@
+"""Epic domain model.
+
+Represents an epic in the HCD documentation system.
+Epics are defined via RST directives and group related stories together.
+"""
+
+from julee.core.utils import normalize_name
+from pydantic import Field, field_validator
+
+from .base import Authored
+
+
+class Epic(Authored):
+    """Epic entity.
+
+    An epic represents a collection of related stories that together
+    deliver a larger piece of functionality or business value.
+    """
+
+    slug: str = Field(description='URL-safe identifier (e.g., "credential-creation")')
+    description: str = Field(
+        default="", description="Human-readable description of the epic"
+    )
+    story_refs: tuple[str, ...] = Field(
+        default_factory=tuple, description="List of story feature titles in this epic"
+    )
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Validate slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return v.strip()
+
+    def with_story(self, story_title: str) -> "Epic":
+        """The epic with a story reference added.
+
+        An entity is immutable, so this returns a new epic rather than
+        changing this one. A title already present is not added twice.
+
+        Args:
+            story_title: Feature title of the story to add
+        """
+        if story_title in self.story_refs:
+            return self
+        return self.model_copy(update={"story_refs": (*self.story_refs, story_title)})
+
+    def has_story(self, story_title: str) -> bool:
+        """Check if this epic contains a specific story.
+
+        Args:
+            story_title: Feature title to check (case-insensitive)
+
+        Returns:
+            True if the story is in this epic
+        """
+        story_normalized = normalize_name(story_title)
+        return any(normalize_name(ref) == story_normalized for ref in self.story_refs)
+
+    def get_story_refs_normalized(self) -> list[str]:
+        """Get normalized story references.
+
+        Returns:
+            List of normalized story titles
+        """
+        return [normalize_name(ref) for ref in self.story_refs]
+
+    @property
+    def display_title(self) -> str:
+        """Get formatted title for display."""
+        return self.slug.replace("-", " ").title()
+
+    @property
+    def story_count(self) -> int:
+        """Get number of stories in this epic."""
+        return len(self.story_refs)
+
+    @property
+    def has_stories(self) -> bool:
+        """Check if epic has any stories."""
+        return len(self.story_refs) > 0

julee_hcd/domain/models/integration.py

@@ -0,0 +1,226 @@
+"""Integration domain model.
+
+Represents an integration module in the HCD documentation system.
+Integrations are defined via YAML manifests in integrations/*/integration.yaml.
+"""
+
+from enum import StrEnum
+
+from julee.core.entities.entity import Entity
+from julee.core.utils import normalize_name
+from pydantic import Field, field_validator
+
+from .base import Authored
+
+
+class Direction(StrEnum):
+    """Integration data flow direction."""
+
+    INBOUND = "inbound"
+    OUTBOUND = "outbound"
+    BIDIRECTIONAL = "bidirectional"
+
+    @classmethod
+    def from_string(cls, value: str) -> "Direction":
+        """Convert string to Direction, defaulting to BIDIRECTIONAL."""
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.BIDIRECTIONAL
+
+    @property
+    def label(self) -> str:
+        """Get human-readable label."""
+        labels = {
+            Direction.INBOUND: "Inbound (data source)",
+            Direction.OUTBOUND: "Outbound (data sink)",
+            Direction.BIDIRECTIONAL: "Bidirectional",
+        }
+        return labels.get(self, str(self.value))
+
+
+class ExternalDependency(Entity):
+    """External system that an integration depends on."""
+
+    name: str = Field(description="Display name of the external system")
+    url: str | None = Field(
+        default=None, description="Optional URL for documentation or reference"
+    )
+    description: str = Field(default="", description="Optional brief description")
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ExternalDependency":
+        """Create from dictionary (YAML parsed data).
+
+        Args:
+            data: Dictionary with name, url, description keys
+
+        Returns:
+            ExternalDependency instance
+        """
+        return cls(
+            name=data.get("name", ""),
+            url=data.get("url"),
+            description=data.get("description", ""),
+        )
+
+
+class Integration(Authored):
+    """Integration module entity.
+
+    Integrations represent connections to external systems, defining
+    data flow direction and external dependencies.
+    """
+
+    slug: str = Field(description='URL-safe identifier (e.g., "pilot-data-collection")')
+    module: str = Field(
+        description='Python module name (e.g., "pilot_data_collection")'
+    )
+    name: str = Field(description="Display name")
+    description: str = Field(default="", description="Human-readable description")
+    direction: Direction = Field(
+        default=Direction.BIDIRECTIONAL, description="Data flow direction"
+    )
+    depends_on: tuple[ExternalDependency, ...] = Field(
+        default_factory=tuple, description="List of external dependencies"
+    )
+    manifest_path: str = Field(
+        default="", description="Path to the integration.yaml file"
+    )
+    name_normalized: str = Field(default="", description="Lowercase name for matching")
+
+    @field_validator("slug", mode="before")
+    @classmethod
+    def validate_slug(cls, v: str) -> str:
+        """Validate slug is not empty."""
+        if not v or not v.strip():
+            raise ValueError("slug cannot be empty")
+        return v.strip()
+
+    @field_validator("module", mode="before")
+    @classmethod
+    def validate_module(cls, v: str) -> str:
+        """Validate module is not empty."""
+        if not v or not v.strip():
+            raise ValueError("module cannot be empty")
+        return v.strip()
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @field_validator("name_normalized", mode="before")
+    @classmethod
+    def compute_name_normalized(cls, v: str, info) -> str:
+        """Compute normalized name from name if not provided."""
+        if v:
+            return v
+        name = info.data.get("name", "")
+        return normalize_name(name) if name else ""
+
+    def model_post_init(self, __context) -> None:
+        """Ensure normalized fields are computed after init."""
+        if not self.name_normalized and self.name:
+            object.__setattr__(self, "name_normalized", normalize_name(self.name))
+
+    @classmethod
+    def from_manifest(
+        cls,
+        module_name: str,
+        manifest: dict,
+        manifest_path: str,
+    ) -> "Integration":
+        """Create an Integration from a parsed YAML manifest.
+
+        Args:
+            module_name: Module directory name
+            manifest: Parsed YAML content
+            manifest_path: Path to the manifest file
+
+        Returns:
+            Integration instance
+        """
+        slug = manifest.get("slug", module_name.replace("_", "-"))
+        name = manifest.get("name", slug.replace("-", " ").title())
+        direction = Direction.from_string(manifest.get("direction", "bidirectional"))
+
+        # Parse depends_on list
+        depends_on_raw = manifest.get("depends_on", [])
+        depends_on = [
+            (
+                ExternalDependency.from_dict(dep)
+                if isinstance(dep, dict)
+                else ExternalDependency(name=str(dep))
+            )
+            for dep in depends_on_raw
+        ]
+
+        return cls(
+            slug=slug,
+            module=module_name,
+            name=name,
+            description=manifest.get("description", "").strip(),
+            direction=direction,
+            depends_on=tuple(depends_on),
+            manifest_path=manifest_path,
+        )
+
+    def matches_direction(self, direction: Direction | str) -> bool:
+        """Check if this integration matches the given direction.
+
+        Args:
+            direction: Direction enum or string to match
+
+        Returns:
+            True if integration matches the direction
+        """
+        if isinstance(direction, str):
+            direction = Direction.from_string(direction)
+        return self.direction == direction
+
+    def matches_name(self, name: str) -> bool:
+        """Check if this integration matches the given name (case-insensitive).
+
+        Args:
+            name: Name to match against
+
+        Returns:
+            True if normalized names match
+        """
+        return self.name_normalized == normalize_name(name)
+
+    def has_dependency(self, dep_name: str) -> bool:
+        """Check if this integration has a specific dependency.
+
+        Args:
+            dep_name: Dependency name to check (case-insensitive)
+
+        Returns:
+            True if dependency exists
+        """
+        dep_normalized = normalize_name(dep_name)
+        return any(
+            normalize_name(dep.name) == dep_normalized for dep in self.depends_on
+        )
+
+    @property
+    def direction_label(self) -> str:
+        """Get human-readable direction label."""
+        return self.direction.label
+
+    @property
+    def module_path(self) -> str:
+        """Get full module path for display."""
+        return f"integrations.{self.module}"