grimoire-kit 3.0.0__py3-none-any.whl

grimoire/cli/cmd_upgrade.py

@@ -0,0 +1,175 @@
+"""``grimoire upgrade`` — migrate a v2 project to v3 structure.
+
+Detects a v2 project by the presence of ``project-context.yaml`` without
+v3 markers. Generates the v3 config from the v2 config,
+ensures the v3 directory layout, and preserves all memory files.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from grimoire.tools._common import load_yaml, save_yaml
+
+# ── Data Models ───────────────────────────────────────────────────────────────
+
+@dataclass(slots=True)
+class UpgradeAction:
+    """A single planned migration action."""
+
+    kind: str  # "create-dir", "generate-file", "move-dir", "skip"
+    description: str
+    target: str
+
+
+@dataclass(slots=True)
+class UpgradePlan:
+    """All planned actions for the v2 → v3 migration."""
+
+    source_version: str = "v2"
+    target_version: str = "v3"
+    actions: list[UpgradeAction] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    already_v3: bool = False
+
+
+# ── Detection ─────────────────────────────────────────────────────────────────
+
+def detect_version(project_root: Path) -> str:
+    """Return ``"v3"`` if ``project-context.yaml`` contains v3 markers,
+    ``"v2"`` if it exists but is v2-style, or ``"unknown"``."""
+    pctx = project_root / "project-context.yaml"
+    if not pctx.exists():
+        return "unknown"
+
+    try:
+        data = load_yaml(pctx)
+    except OSError:
+        return "unknown"
+
+    if not isinstance(data, dict):
+        return "unknown"
+
+    # v3 has top-level 'grimoire' key with 'version'
+    if "grimoire" in data and isinstance(data["grimoire"], dict):
+        return "v3"
+
+    # v2 has top-level keys like 'project', 'communication_language', etc.
+    if "project" in data or "communication_language" in data:
+        return "v2"
+
+    return "unknown"
+
+
+# ── Planning ──────────────────────────────────────────────────────────────────
+
+def _extract_v2_config(project_root: Path) -> dict[str, Any]:
+    """Extract usable fields from a v2 project-context.yaml."""
+    data = load_yaml(project_root / "project-context.yaml")
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+def plan_upgrade(project_root: Path) -> UpgradePlan:
+    """Analyze the project and plan the migration."""
+    plan = UpgradePlan()
+    version = detect_version(project_root)
+
+    if version == "v3":
+        plan.already_v3 = True
+        return plan
+
+    if version == "unknown":
+        plan.warnings.append(
+            "No project-context.yaml found or unrecognizable format."
+        )
+        return plan
+
+    # v2 → v3 migration plan
+    _extract_v2_config(project_root)  # validate readable
+
+    # 1. Generate bmad section in project-context.yaml
+    plan.actions.append(UpgradeAction(
+        kind="generate-file",
+        description="Add 'grimoire' section to project-context.yaml (v3 config)",
+        target="project-context.yaml",
+    ))
+
+    # 2. Ensure v3 directories
+    for d in ("_grimoire", "_grimoire/_memory", "_grimoire-output",
+              "_grimoire/_config", "_grimoire/_config/agents"):
+        dp = project_root / d
+        if not dp.is_dir():
+            plan.actions.append(UpgradeAction(
+                kind="create-dir",
+                description=f"Create directory: {d}/",
+                target=d,
+            ))
+
+    # 3. Warn about orphan files
+    old_dirs = ["agents", "tasks", "workflows"]
+    for od in old_dirs:
+        odp = project_root / od
+        if odp.is_dir():
+            plan.warnings.append(
+                f"Top-level '{od}/' directory exists — may need manual review."
+            )
+
+    return plan
+
+
+# ── Execution ─────────────────────────────────────────────────────────────────
+
+def _generate_v3_section(v2_data: dict[str, Any]) -> dict[str, Any]:
+    """Build the 'grimoire' section from v2 config data."""
+    project_name = v2_data.get("project", "unnamed")
+    if isinstance(project_name, dict):
+        project_name = project_name.get("name", "unnamed")
+
+    return {
+        "grimoire": {
+            "version": "3.0",
+            "migrated_from": "v2",
+        },
+        "project": {
+            "name": project_name,
+        },
+        "agents": {
+            "archetype": "minimal",
+        },
+        "memory": {
+            "backend": "auto",
+        },
+    }
+
+
+def execute_upgrade(project_root: Path, plan: UpgradePlan,
+                    dry_run: bool = False) -> list[str]:
+    """Execute the upgrade plan. Returns list of completed action descriptions."""
+    completed: list[str] = []
+
+    for action in plan.actions:
+        if action.kind == "create-dir":
+            dp = project_root / action.target
+            if not dry_run:
+                dp.mkdir(parents=True, exist_ok=True)
+            completed.append(action.description)
+
+        elif action.kind == "generate-file" and action.target == "project-context.yaml":
+            pctx = project_root / "project-context.yaml"
+            v2_data = _extract_v2_config(project_root)
+            v3_section = _generate_v3_section(v2_data)
+
+            if not dry_run:
+                # Merge v3 section into existing file
+                existing = load_yaml(pctx) if pctx.exists() else {}
+                if not isinstance(existing, dict):
+                    existing = {}
+                existing.update(v3_section)
+                save_yaml(existing, pctx)
+            completed.append(action.description)
+
+    return completed

grimoire/core/__init__.py

@@ -0,0 +1,16 @@
+"""Grimoire core — business logic and domain models."""
+
+from grimoire.core.config import GrimoireConfig
+from grimoire.core.exceptions import GrimoireError
+from grimoire.core.project import GrimoireProject
+from grimoire.core.resolver import PathResolver
+from grimoire.core.scanner import StackScanner
+
+__all__ = [
+    "GrimoireConfig",
+    "GrimoireError",
+    "GrimoireProject",
+    "PathResolver",
+    "StackScanner",
+]
+

grimoire/core/config.py

@@ -0,0 +1,237 @@
+"""Typed configuration for Grimoire projects.
+
+Loads and validates ``project-context.yaml`` into typed dataclasses.
+Unknown sections are preserved in ``extra`` so downstream tools can
+access them without requiring schema changes here.
+
+Usage::
+
+    from grimoire.core.config import GrimoireConfig
+
+    cfg = GrimoireConfig.from_yaml(Path("project-context.yaml"))
+    print(cfg.project.name)
+    print(cfg.user.language)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from grimoire.core.exceptions import GrimoireConfigError
+
+# ── Sub-sections ──────────────────────────────────────────────────────────────
+
+@dataclass(frozen=True, slots=True)
+class RepoConfig:
+    """A single repository entry."""
+
+    name: str
+    path: str = "."
+    default_branch: str = "main"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RepoConfig:
+        return cls(
+            name=str(data.get("name", "")),
+            path=str(data.get("path", ".")),
+            default_branch=str(data.get("default_branch", "main")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectConfig:
+    """The ``project:`` section."""
+
+    name: str
+    description: str = ""
+    type: str = "webapp"
+    metaphor: str = ""
+    stack: tuple[str, ...] = ()
+    repos: tuple[RepoConfig, ...] = ()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ProjectConfig:
+        raw_stack = data.get("stack") or []
+        raw_repos = data.get("repos") or []
+        return cls(
+            name=str(data.get("name", "")),
+            description=str(data.get("description", "")),
+            type=str(data.get("type", "webapp")),
+            metaphor=str(data.get("metaphor", "")),
+            stack=tuple(str(s) for s in raw_stack),
+            repos=tuple(RepoConfig.from_dict(r) for r in raw_repos),
+        )
+
+
+_VALID_SKILL_LEVELS = frozenset({"beginner", "intermediate", "expert"})
+
+
+@dataclass(frozen=True, slots=True)
+class UserConfig:
+    """The ``user:`` section."""
+
+    name: str = ""
+    language: str = "Français"
+    document_language: str = "Français"
+    skill_level: str = "intermediate"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> UserConfig:
+        skill = str(data.get("skill_level", "intermediate"))
+        if skill not in _VALID_SKILL_LEVELS:
+            raise GrimoireConfigError(
+                f"Invalid skill_level '{skill}', expected one of: {sorted(_VALID_SKILL_LEVELS)}"
+            )
+        return cls(
+            name=str(data.get("name", "")),
+            language=str(data.get("language", "Français")),
+            document_language=str(data.get("document_language", "Français")),
+            skill_level=skill,
+        )
+
+
+_VALID_BACKENDS = frozenset({
+    "auto", "local", "qdrant-local", "qdrant-server", "ollama",
+})
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryConfig:
+    """The ``memory:`` section."""
+
+    backend: str = "auto"
+    collection_prefix: str = "grimoire"
+    embedding_model: str = ""
+    qdrant_url: str = ""
+    ollama_url: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> MemoryConfig:
+        backend = str(data.get("backend", "auto"))
+        if backend not in _VALID_BACKENDS:
+            raise GrimoireConfigError(
+                f"Invalid memory backend '{backend}', expected one of: {sorted(_VALID_BACKENDS)}"
+            )
+        return cls(
+            backend=backend,
+            collection_prefix=str(data.get("collection_prefix", "grimoire")),
+            embedding_model=str(data.get("embedding_model", "")),
+            qdrant_url=str(data.get("qdrant_url", "")),
+            ollama_url=str(data.get("ollama_url", "")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class AgentsConfig:
+    """The ``agents:`` section."""
+
+    archetype: str = "minimal"
+    custom_agents: tuple[str, ...] = ()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AgentsConfig:
+        raw = data.get("custom_agents") or []
+        return cls(
+            archetype=str(data.get("archetype", "minimal")),
+            custom_agents=tuple(str(a) for a in raw),
+        )
+
+
+# ── Root Config ───────────────────────────────────────────────────────────────
+
+_KNOWN_TOP_KEYS = frozenset({
+    "project", "user", "memory", "agents", "installed_archetypes",
+})
+
+
+@dataclass(frozen=True, slots=True)
+class GrimoireConfig:
+    """Root Grimoire project configuration.
+
+    Immutable after construction.  Unrecognised top-level keys are stored
+    in ``extra`` so tools can access them without schema changes.
+    """
+
+    project: ProjectConfig
+    user: UserConfig = field(default_factory=UserConfig)
+    memory: MemoryConfig = field(default_factory=MemoryConfig)
+    agents: AgentsConfig = field(default_factory=AgentsConfig)
+    installed_archetypes: tuple[str, ...] = ()
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    # ── Factory methods ───────────────────────────────────────────────
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> GrimoireConfig:
+        """Build a :class:`GrimoireConfig` from a parsed YAML dict.
+
+        Raises :class:`GrimoireConfigError` on validation failures.
+        """
+        if not isinstance(data, dict):
+            raise GrimoireConfigError("Config root must be a YAML mapping")
+
+        raw_project = data.get("project")
+        if not isinstance(raw_project, dict) or not raw_project.get("name"):
+            raise GrimoireConfigError("Config must contain a 'project' section with a 'name' field")
+
+        raw_archetypes = data.get("installed_archetypes") or []
+        extra = {k: v for k, v in data.items() if k not in _KNOWN_TOP_KEYS}
+
+        return cls(
+            project=ProjectConfig.from_dict(raw_project),
+            user=UserConfig.from_dict(data.get("user") or {}),
+            memory=MemoryConfig.from_dict(data.get("memory") or {}),
+            agents=AgentsConfig.from_dict(data.get("agents") or {}),
+            installed_archetypes=tuple(str(a) for a in raw_archetypes),
+            extra=extra,
+        )
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> GrimoireConfig:
+        """Load config from a YAML file.
+
+        Raises :class:`GrimoireConfigError` if the file is missing, unreadable,
+        or contains invalid YAML.
+        """
+        if not path.is_file():
+            raise GrimoireConfigError(f"Config file not found: {path}")
+
+        try:
+            from ruamel.yaml import YAML
+
+            yaml = YAML(typ="safe")
+            raw = yaml.load(path)
+        except ImportError:
+            # Fallback to PyYAML if ruamel not available
+            try:
+                import yaml as pyyaml  # type: ignore[import-untyped]
+
+                with open(path) as fh:
+                    raw = pyyaml.safe_load(fh)
+            except Exception as exc:
+                raise GrimoireConfigError(f"Cannot parse '{path}': {exc}") from exc
+        except Exception as exc:
+            raise GrimoireConfigError(f"Cannot parse '{path}': {exc}") from exc
+
+        if raw is None:
+            raise GrimoireConfigError(f"Config file is empty: {path}")
+
+        return cls.from_dict(raw)
+
+    @classmethod
+    def find_and_load(cls, start: Path | None = None) -> GrimoireConfig:
+        """Walk up the directory tree to find ``project-context.yaml``.
+
+        Starts from *start* (default: cwd) and searches upward.
+        Raises :class:`GrimoireConfigError` if no config file is found.
+        """
+        current = (start or Path.cwd()).resolve()
+        for parent in [current, *current.parents]:
+            candidate = parent / "project-context.yaml"
+            if candidate.is_file():
+                return cls.from_yaml(candidate)
+        raise GrimoireConfigError(
+            f"No 'project-context.yaml' found in {current} or any parent directory"
+        )

grimoire/core/exceptions.py

@@ -0,0 +1,87 @@
+"""Typed exception hierarchy for Grimoire Kit.
+
+Every exception inherits from :class:`GrimoireError` so callers can
+``except GrimoireError`` to catch all Grimoire-specific failures.
+"""
+
+from __future__ import annotations
+
+
+class GrimoireError(Exception):
+    """Base exception for all Grimoire Kit errors."""
+
+
+class GrimoireConfigError(GrimoireError):
+    """Invalid or missing ``bmad.yaml`` configuration.
+
+    Raised when the config file cannot be parsed, contains unknown keys,
+    or fails schema validation.
+    """
+
+
+class GrimoireProjectError(GrimoireError):
+    """Project not initialised or has an invalid structure.
+
+    Raised when ``grimoire up`` or other project-scoped commands are run
+    outside of a properly initialised Grimoire project.
+    """
+
+
+class GrimoireAgentError(GrimoireError):
+    """Agent not found, persona invalid, or activation failure.
+
+    Raised when an agent referenced in ``bmad.yaml`` cannot be loaded
+    from built-in archetypes, the registry, or custom paths.
+    """
+
+
+class GrimoireToolError(GrimoireError):
+    """A Grimoire tool failed during execution.
+
+    Raised when a tool (context-router, harmony-check, etc.) encounters
+    a runtime error that prevents it from producing a result.
+    """
+
+
+class GrimoireMergeError(GrimoireError):
+    """General merge failure.
+
+    Raised when ``grimoire merge`` or ``grimoire init`` on an existing project
+    encounters an unrecoverable error during file merging.
+    """
+
+
+class GrimoireMergeConflict(GrimoireMergeError):  # noqa: N818 — semantic: it's a conflict, not an error
+    """Unresolved merge conflict that requires user intervention.
+
+    Carries the list of conflicting paths so the caller can present
+    them to the user.
+    """
+
+    def __init__(self, message: str, conflicts: list[str] | None = None) -> None:
+        super().__init__(message)
+        self.conflicts: list[str] = conflicts or []
+
+
+class GrimoireRegistryError(GrimoireError):
+    """Registry operation failure (network, auth, package not found).
+
+    Raised by the registry client when a search, install, or publish
+    operation fails.
+    """
+
+
+class GrimoireMemoryError(GrimoireError):
+    """Memory backend error (connection, serialisation, query failure).
+
+    Raised when the memory system cannot read, write, or consolidate
+    memories due to a backend issue.
+    """
+
+
+class GrimoireValidationError(GrimoireError):
+    """Schema or data validation failure.
+
+    Raised when DNA files, agent definitions, or other structured data
+    fail validation against their expected schema.
+    """