raise-cli 2.2.1__py3-none-any.whl

raise_cli/onboarding/manifest.py

@@ -0,0 +1,201 @@
+"""Project manifest schema and persistence.
+
+The manifest file (.raise/manifest.yaml) stores project metadata detected
+during initialization, including project type and code file count.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError, model_validator
+
+from raise_cli.config.ide import IdeType
+from raise_cli.config.paths import MANIFEST_FILE, get_raise_dir
+from raise_cli.onboarding.detection import ProjectType
+
+logger = logging.getLogger(__name__)
+
+
+class ProjectInfo(BaseModel):
+    """Information about the project detected during init.
+
+    Attributes:
+        name: Project name (usually directory name).
+        project_type: Whether greenfield or brownfield.
+        language: Dominant programming language (auto-detected or user-specified).
+        test_command: Command to run tests (configuration over convention).
+        lint_command: Command to run linter (configuration over convention).
+        type_check_command: Command to run type checker (configuration over convention).
+        code_file_count: Number of code files detected.
+        detected_at: When the project was initialized.
+    """
+
+    name: str
+    project_type: ProjectType
+    language: str | None = None
+    test_command: str | None = None
+    lint_command: str | None = None
+    type_check_command: str | None = None
+    code_file_count: int = 0
+    detected_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class BranchConfig(BaseModel):
+    """Branch naming configuration for the project.
+
+    Attributes:
+        development: The development/integration branch name.
+        main: The stable/production branch name.
+    """
+
+    development: str = "main"
+    main: str = "main"
+
+
+class IdeManifest(BaseModel):
+    """IDE configuration persisted in manifest (legacy single-IDE format).
+
+    Attributes:
+        type: Which IDE this project uses.
+    """
+
+    type: IdeType = "claude"
+
+
+class AgentsManifest(BaseModel):
+    """Multi-agent configuration persisted in manifest.
+
+    Replaces IdeManifest with a list to support multiple simultaneous agents.
+
+    Attributes:
+        types: List of active agent types (e.g. ["claude", "cursor", "windsurf"]).
+    """
+
+    types: list[str] = Field(default_factory=lambda: ["claude"])
+
+
+class BacklogConfig(BaseModel):
+    """Backlog configuration from manifest (optional section).
+
+    Attributes:
+        adapter_default: Default PM adapter name (e.g., 'jira', 'filesystem').
+    """
+
+    adapter_default: str | None = None
+
+
+class TierConfig(BaseModel):
+    """Tier configuration from manifest (optional section).
+
+    Attributes:
+        level: Tier level string (community, pro, enterprise).
+        backend_url: Backend URL for PRO/Enterprise tiers.
+        capabilities: List of capability strings enabled for this tier.
+    """
+
+    level: str = "community"
+    backend_url: str | None = None
+    capabilities: list[str] = Field(default_factory=list)
+
+
+class ProjectManifest(BaseModel):
+    """Project manifest stored in .raise/manifest.yaml.
+
+    Attributes:
+        version: Manifest schema version.
+        project: Project information.
+        branches: Branch naming configuration.
+        ide: Legacy single-IDE configuration (backward compat — read/write).
+        agents: Multi-agent configuration (new format).
+        tier: Optional tier configuration (S211.5).
+    """
+
+    version: str = "1.0"
+    project: ProjectInfo
+    branches: BranchConfig = Field(default_factory=BranchConfig)
+    ide: IdeManifest = Field(default_factory=IdeManifest)
+    agents: AgentsManifest = Field(default_factory=AgentsManifest)
+    tier: TierConfig | None = None
+    backlog: BacklogConfig | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _migrate_ide_to_agents(cls, data: Any) -> dict[str, Any]:
+        """Migrate old ide.type format to agents.types on load.
+
+        If 'agents' key is absent but 'ide' key is present, derive
+        agents.types from ide.type for backward compat.
+        """
+        if not isinstance(data, dict):
+            return cast(dict[str, Any], data)
+        typed: dict[str, Any] = cast(dict[str, Any], data)
+        if "agents" not in typed and "ide" in typed:
+            raw_ide: object = typed["ide"]
+            if isinstance(raw_ide, dict):
+                raw_type: object = cast(dict[str, object], raw_ide).get(
+                    "type", "claude"
+                )
+                ide_type: str = str(raw_type) if raw_type is not None else "claude"
+            else:
+                ide_type = "claude"
+            typed["agents"] = {"types": [ide_type]}
+        return typed
+
+
+def save_manifest(manifest: ProjectManifest, project_root: Path) -> None:
+    """Save project manifest to .raise/manifest.yaml.
+
+    Creates .raise/ directory if it doesn't exist.
+
+    Args:
+        manifest: The manifest to save.
+        project_root: Root directory of the project.
+    """
+    raise_dir = get_raise_dir(project_root)
+    raise_dir.mkdir(parents=True, exist_ok=True)
+
+    manifest_path = raise_dir / MANIFEST_FILE
+
+    # Convert to dict with proper serialization
+    data = manifest.model_dump(mode="json")
+
+    content = yaml.dump(
+        data, default_flow_style=False, allow_unicode=True, sort_keys=False
+    )
+    manifest_path.write_text(content, encoding="utf-8")
+    logger.debug("Saved manifest: %s", manifest_path)
+
+
+def load_manifest(project_root: Path) -> ProjectManifest | None:
+    """Load project manifest from .raise/manifest.yaml.
+
+    Args:
+        project_root: Root directory of the project.
+
+    Returns:
+        ProjectManifest if file exists and is valid, None otherwise.
+    """
+    manifest_path = get_raise_dir(project_root) / MANIFEST_FILE
+
+    if not manifest_path.exists():
+        logger.debug("Manifest not found: %s", manifest_path)
+        return None
+
+    try:
+        content = manifest_path.read_text(encoding="utf-8")
+        data = yaml.safe_load(content)
+        if data is None:
+            logger.warning("Empty manifest: %s", manifest_path)
+            return None
+        return ProjectManifest.model_validate(data)
+    except yaml.YAMLError as e:
+        logger.warning("Invalid YAML in manifest: %s", e)
+        return None
+    except ValidationError as e:
+        logger.warning("Invalid manifest schema: %s", e)
+        return None

raise_cli/onboarding/memory_md.py

@@ -0,0 +1,399 @@
+"""MEMORY.md generation for Claude Code and other AI editors.
+
+Agent-agnostic generator: produces markdown string from methodology.yaml
+and patterns.jsonl. Knows nothing about file paths or write destinations.
+
+The generator is IDE-independent — placement functions (in CLI commands)
+decide where to write the output.
+
+Example:
+    from raise_cli.onboarding.memory_md import MemoryMdGenerator
+
+    gen = MemoryMdGenerator()
+    content = gen.generate(
+        methodology_path=Path(".raise/rai/framework/methodology.yaml"),
+        patterns_path=Path(".raise/rai/memory/patterns.jsonl"),
+        project_name="my-project",
+    )
+    Path("MEMORY.md").write_text(content)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryMdGenerator:
+    """Generates MEMORY.md content from methodology and patterns.
+
+    Part 1 (static): Lifecycle, skills, gates, principles, branches
+    from methodology.yaml.
+
+    Part 2 (dynamic): Key patterns from patterns.jsonl.
+
+    The generator returns a string — it never writes to disk.
+    This separation enables multi-IDE support: generate once,
+    write to Claude Code, Cursor, Windsurf, etc.
+    """
+
+    def generate(
+        self,
+        methodology_path: Path | None = None,
+        patterns_path: Path | None = None,
+        project_name: str = "project",
+        max_patterns: int = 10,
+        development_branch: str = "main",
+    ) -> str:
+        """Generate MEMORY.md content.
+
+        Args:
+            methodology_path: Path to methodology.yaml (Part 1 source).
+            patterns_path: Path to patterns.jsonl (Part 2 source).
+            project_name: Project name for the header.
+            max_patterns: Maximum patterns to include in Part 2.
+            development_branch: Development branch name for placeholder
+                substitution in branch model (default: "main").
+
+        Returns:
+            Markdown content for MEMORY.md.
+        """
+        lines: list[str] = []
+
+        self._add_header(lines, project_name)
+
+        # Part 1: Static methodology
+        methodology = self._load_methodology(methodology_path)
+        if methodology:
+            self._add_lifecycle_section(lines, methodology)
+            self._add_skills_section(lines, methodology)
+            self._add_gates_section(lines, methodology)
+            self._add_principles_section(lines, methodology)
+            self._add_branches_section(lines, methodology, development_branch)
+
+        # Part 2: Dynamic patterns
+        patterns = self._load_patterns(patterns_path)
+        self._add_patterns_section(lines, patterns, max_patterns)
+
+        self._add_footer(lines)
+
+        return "\n".join(lines)
+
+    # =========================================================================
+    # Header & Footer
+    # =========================================================================
+
+    def _add_header(self, lines: list[str], project_name: str) -> None:
+        """Add document header."""
+        lines.append(f"# Rai Memory — {project_name}")
+        lines.append("")
+        lines.append(
+            "> Permanent knowledge for this project. Loaded into system prompt."
+        )
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+
+    def _add_footer(self, lines: list[str]) -> None:
+        """Add document footer with timestamp."""
+        lines.append(f"*Last updated: {date.today().isoformat()}*")
+        lines.append("*Generated by `rai graph build`*")
+        lines.append("")
+
+    # =========================================================================
+    # Part 1: Methodology sections
+    # =========================================================================
+
+    def _add_lifecycle_section(
+        self, lines: list[str], methodology: dict[str, Any]
+    ) -> None:
+        """Add lifecycle flows section."""
+        lifecycle = methodology.get("lifecycle", {})
+        if not lifecycle:
+            return
+
+        lines.append("## RaiSE Framework Process")
+        lines.append("")
+        lines.append("### Work Lifecycle (Always Follow)")
+        lines.append("")
+        lines.append("```")
+
+        for level_name, level_data in lifecycle.items():
+            label = level_name.upper() + " LEVEL"
+            if level_name == "session":
+                label = "SESSION LEVEL"
+            elif level_name == "story":
+                label = "STORY LEVEL (per story)"
+            elif level_name == "epic":
+                label = "EPIC LEVEL"
+
+            lines.append(f"{label}:")
+            lines.append(f"  {level_data['flow']}")
+            lines.append("")
+
+            # Add note if present
+            if "note" in level_data:
+                lines.append(f"* {level_data['note']}")
+                lines.append("")
+
+        # Remove trailing blank line inside code block
+        if lines and lines[-1] == "":
+            lines.pop()
+        lines.append("```")
+        lines.append("")
+
+    def _add_skills_section(
+        self, lines: list[str], methodology: dict[str, Any]
+    ) -> None:
+        """Add skills by category."""
+        skills = methodology.get("skills", {})
+        if not skills:
+            return
+
+        # Count total skills
+        total = sum(len(category_skills) for category_skills in skills.values())
+
+        lines.append(f"## Available Skills ({total} total)")
+        lines.append("")
+
+        # Category display names
+        category_names = {
+            "session": "Session Skills",
+            "epic": "Epic Skills",
+            "story": "Story Skills",
+            "discovery": "Discovery Skills",
+            "meta": "Meta Skills",
+            "other": "Other Skills",
+        }
+
+        for category, category_skills in skills.items():
+            display_name = category_names.get(category, f"{category.title()} Skills")
+            lines.append(f"### {display_name}")
+
+            for skill in category_skills:
+                name = skill["name"]
+                purpose = skill["purpose"]
+                lines.append(f"- `{name}` — {purpose}")
+
+            lines.append("")
+
+        lines.append("---")
+        lines.append("")
+
+    def _add_gates_section(self, lines: list[str], methodology: dict[str, Any]) -> None:
+        """Add gate requirements as table."""
+        gates = methodology.get("gates", {})
+        blocking = gates.get("blocking", [])
+        if not blocking:
+            return
+
+        lines.append("### Gate Requirements")
+        lines.append("")
+        lines.append("| Gate | Required Before |")
+        lines.append("|------|-----------------|")
+
+        for gate in blocking:
+            require = gate["require"]
+            before = gate["before"]
+            enforced_by = gate.get("enforced_by", "")
+            enforced_str = f" ({enforced_by})" if enforced_by else ""
+            lines.append(f"| **{require}** | **{before}**{enforced_str} |")
+
+        # Add quality gates as simple rows
+        quality = gates.get("quality", [])
+        for gate in quality:
+            gate_name = gate["gate"]
+            when = gate["when"]
+            lines.append(f"| {gate_name} | {when} |")
+
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+
+    def _add_principles_section(
+        self, lines: list[str], methodology: dict[str, Any]
+    ) -> None:
+        """Add principles as numbered rules."""
+        principles = methodology.get("principles", {})
+        if not principles:
+            return
+
+        lines.append("## Critical Process Rules")
+        lines.append("")
+
+        rule_num = 1
+        for _category, category_principles in principles.items():
+            for principle in category_principles:
+                name = principle["name"]
+                rule = principle["rule"]
+                lines.append(f"{rule_num}. **{name}** — {rule}")
+                rule_num += 1
+
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+
+    def _add_branches_section(
+        self,
+        lines: list[str],
+        methodology: dict[str, Any],
+        development_branch: str = "main",
+    ) -> None:
+        """Add branch model section."""
+        branches = methodology.get("branches", {})
+        if not branches:
+            return
+
+        lines.append("## Branch Model")
+        lines.append("")
+
+        structure = branches.get("structure", "")
+        if structure:
+            structure = structure.replace("{development_branch}", development_branch)
+            lines.append("```")
+            # structure may have trailing newline from YAML block scalar
+            for line in structure.rstrip().split("\n"):
+                lines.append(line)
+            lines.append("```")
+            lines.append("")
+
+        flow = branches.get("flow", [])
+        for item in flow:
+            item = item.replace("{development_branch}", development_branch)
+            lines.append(f"- {item}")
+
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+
+    # =========================================================================
+    # Part 2: Patterns
+    # =========================================================================
+
+    def _add_patterns_section(
+        self,
+        lines: list[str],
+        patterns: list[dict[str, Any]],
+        max_patterns: int,
+    ) -> None:
+        """Add key patterns from patterns.jsonl."""
+        lines.append("## Key Patterns (from memory)")
+        lines.append("")
+
+        if not patterns:
+            lines.append("*No patterns yet. Patterns are learned during work.*")
+            lines.append("")
+            lines.append("---")
+            lines.append("")
+            return
+
+        # Take most recent patterns (already sorted by load order = chronological)
+        selected = patterns[-max_patterns:]
+
+        for pattern in selected:
+            pat_id = pattern.get("id", "?")
+            content = pattern.get("content") or pattern.get("pattern", "")
+            lines.append(f"- **{pat_id}:** {content}")
+
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+
+    # =========================================================================
+    # Loaders
+    # =========================================================================
+
+    def _load_methodology(self, path: Path | None) -> dict[str, Any] | None:
+        """Load and parse methodology.yaml.
+
+        Args:
+            path: Path to methodology.yaml.
+
+        Returns:
+            Parsed YAML dictionary, or None if unavailable.
+        """
+        if path is None or not path.exists():
+            logger.debug("methodology.yaml not found at %s", path)
+            return None
+
+        try:
+            content = path.read_text(encoding="utf-8")
+            data: dict[str, Any] = yaml.safe_load(content)
+            return data
+        except (yaml.YAMLError, OSError) as e:
+            logger.warning("Failed to parse methodology.yaml: %s", e)
+            return None
+
+    def _load_patterns(self, path: Path | None) -> list[dict[str, Any]]:
+        """Load patterns from JSONL file.
+
+        Args:
+            path: Path to patterns.jsonl.
+
+        Returns:
+            List of pattern dictionaries. Empty list if unavailable.
+        """
+        if path is None or not path.exists():
+            return []
+
+        patterns: list[dict[str, Any]] = []
+        try:
+            with path.open("r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        data = json.loads(line)
+                        patterns.append(data)
+                    except json.JSONDecodeError:
+                        continue
+        except OSError as e:
+            logger.warning("Failed to read patterns.jsonl: %s", e)
+
+        return patterns
+
+
+def generate_memory_md(
+    methodology_path: Path | None = None,
+    patterns_path: Path | None = None,
+    project_name: str = "project",
+    max_patterns: int = 10,
+    development_branch: str = "main",
+) -> str:
+    """Convenience function to generate MEMORY.md content.
+
+    Args:
+        methodology_path: Path to methodology.yaml.
+        patterns_path: Path to patterns.jsonl.
+        project_name: Project name for header.
+        max_patterns: Maximum patterns to include.
+        development_branch: Development branch name for placeholder
+            substitution in branch model (default: "main").
+
+    Returns:
+        Markdown content for MEMORY.md.
+
+    Example:
+        >>> content = generate_memory_md(
+        ...     methodology_path=Path(".raise/rai/framework/methodology.yaml"),
+        ...     patterns_path=Path(".raise/rai/memory/patterns.jsonl"),
+        ...     project_name="my-api",
+        ... )
+        >>> Path("MEMORY.md").write_text(content)
+    """
+    generator = MemoryMdGenerator()
+    return generator.generate(
+        methodology_path=methodology_path,
+        patterns_path=patterns_path,
+        project_name=project_name,
+        max_patterns=max_patterns,
+        development_branch=development_branch,
+    )