loki-mode 6.79.0 → 6.80.0

package/magic/core/registry.py

@@ -0,0 +1,340 @@
+"""Component registry for Magic Modules.
+
+Tracks every generated component with: name, version (semver), spec hash,
+file paths, tags, creation/update timestamps, debate results, deprecation.
+
+Storage: JSON at .loki/magic/registry.json (atomic writes via tmp + rename).
+Standard library only.
+"""
+
+import json
+import re
+import time
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+from typing import Optional
+
+SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+NAME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]*$")
+
+
+def _utcnow() -> str:
+    """Return current UTC timestamp in ISO 8601 format."""
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+@dataclass
+class ComponentEntry:
+    name: str
+    version: str = "1.0.0"
+    spec_path: str = ""
+    react_path: str = ""
+    webcomponent_path: str = ""
+    test_path: str = ""
+    spec_hash: str = ""
+    created_at: str = ""
+    updated_at: str = ""
+    tags: list = field(default_factory=list)
+    description: str = ""
+    targets: list = field(default_factory=lambda: ["react"])
+    debate_passed: bool = False
+    debate_result: dict = field(default_factory=dict)
+    deprecated: bool = False
+    replaces: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ComponentEntry":
+        """Construct from a dict, ignoring unknown keys."""
+        known = {f for f in cls.__dataclass_fields__}
+        filtered = {k: v for k, v in data.items() if k in known}
+        return cls(**filtered)
+
+
+class ComponentRegistry:
+    def __init__(self, project_dir: str = "."):
+        self.project_dir = Path(project_dir)
+        self.registry_path = self.project_dir / ".loki" / "magic" / "registry.json"
+        self.registry_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+    def load(self) -> dict:
+        """Load registry from disk, return empty structure if missing."""
+        if not self.registry_path.exists():
+            return {"version": "1", "updated_at": "", "components": []}
+        try:
+            data = json.loads(self.registry_path.read_text())
+        except (json.JSONDecodeError, OSError):
+            # Back up corrupted registry and start fresh
+            try:
+                backup = self.registry_path.with_suffix(".json.corrupt")
+                self.registry_path.rename(backup)
+            except OSError:
+                pass
+            return {"version": "1", "updated_at": "", "components": []}
+
+        # Ensure required fields exist
+        if not isinstance(data, dict):
+            return {"version": "1", "updated_at": "", "components": []}
+        data.setdefault("version", "1")
+        data.setdefault("updated_at", "")
+        data.setdefault("components", [])
+        if not isinstance(data["components"], list):
+            data["components"] = []
+        return data
+
+    def save(self, data: dict) -> None:
+        """Atomic write via temp + rename."""
+        data["updated_at"] = _utcnow()
+        tmp = self.registry_path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(data, indent=2, sort_keys=False))
+        tmp.replace(self.registry_path)
+
+    # ------------------------------------------------------------------
+    # CRUD
+    # ------------------------------------------------------------------
+    def register(self, entry: ComponentEntry) -> ComponentEntry:
+        """Add or update a component entry.
+
+        If name exists, bump version (patch) when version matches existing.
+        Validates name format and semver.
+        """
+        if not NAME_RE.match(entry.name):
+            raise ValueError(f"Invalid component name: {entry.name}")
+        if not SEMVER_RE.match(entry.version):
+            raise ValueError(f"Invalid semver: {entry.version}")
+
+        now = _utcnow()
+        data = self.load()
+        existing_idx = next(
+            (i for i, c in enumerate(data["components"]) if c.get("name") == entry.name),
+            None,
+        )
+
+        if existing_idx is not None:
+            existing = data["components"][existing_idx]
+            entry.created_at = existing.get("created_at") or now
+            entry.updated_at = now
+            # Auto-bump patch if same version as existing
+            if entry.version == existing.get("version"):
+                entry.version = self._bump_patch(existing.get("version", "1.0.0"))
+            data["components"][existing_idx] = asdict(entry)
+        else:
+            entry.created_at = entry.created_at or now
+            entry.updated_at = now
+            data["components"].append(asdict(entry))
+
+        self.save(data)
+        return entry
+
+    def get(self, name: str) -> Optional[ComponentEntry]:
+        """Fetch component by name. Returns None if not found."""
+        data = self.load()
+        for c in data["components"]:
+            if c.get("name") == name:
+                return ComponentEntry.from_dict(c)
+        return None
+
+    def remove(self, name: str) -> bool:
+        """Remove component entry (does not delete files). Returns True if removed."""
+        data = self.load()
+        original_count = len(data["components"])
+        data["components"] = [c for c in data["components"] if c.get("name") != name]
+        if len(data["components"]) == original_count:
+            return False
+        self.save(data)
+        return True
+
+    def search(
+        self,
+        query: str = "",
+        tags: list = None,
+        target: str = None,
+    ) -> list:
+        """Search by name/description substring, tags, or target framework.
+
+        - query: case-insensitive substring against name and description.
+        - tags: all tags must be present on the component.
+        - target: match when target appears in component's targets list (or
+          component targets includes "both").
+        """
+        data = self.load()
+        results = []
+        q = (query or "").lower().strip()
+        tag_set = set(tags or [])
+
+        for c in data["components"]:
+            name = c.get("name", "")
+            description = c.get("description", "")
+            ctags = set(c.get("tags") or [])
+            ctargets = c.get("targets") or []
+
+            if q and q not in name.lower() and q not in description.lower():
+                continue
+            if tag_set and not tag_set.issubset(ctags):
+                continue
+            if target:
+                if target not in ctargets and "both" not in ctargets:
+                    continue
+            results.append(ComponentEntry.from_dict(c))
+        return results
+
+    def list_all(self, include_deprecated: bool = False) -> list:
+        """List all components. Excludes deprecated by default."""
+        data = self.load()
+        results = []
+        for c in data["components"]:
+            if not include_deprecated and c.get("deprecated"):
+                continue
+            results.append(ComponentEntry.from_dict(c))
+        return results
+
+    def deprecate(self, name: str, replaces: str = "") -> bool:
+        """Mark component as deprecated. `replaces` points to newer component."""
+        data = self.load()
+        for c in data["components"]:
+            if c.get("name") == name:
+                c["deprecated"] = True
+                if replaces:
+                    c["replaces"] = replaces
+                c["updated_at"] = _utcnow()
+                self.save(data)
+                return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Stats & maintenance
+    # ------------------------------------------------------------------
+    def stats(self) -> dict:
+        """Return registry stats: count, per-target counts, avg debate score, etc."""
+        data = self.load()
+        components = data["components"]
+        total = len(components)
+        deprecated = sum(1 for c in components if c.get("deprecated"))
+        active = total - deprecated
+
+        target_counts = {"react": 0, "webcomponent": 0, "both": 0}
+        for c in components:
+            for t in c.get("targets") or []:
+                if t in target_counts:
+                    target_counts[t] += 1
+
+        debate_passed = sum(1 for c in components if c.get("debate_passed"))
+        scores = []
+        for c in components:
+            res = c.get("debate_result") or {}
+            score = res.get("score")
+            if isinstance(score, (int, float)):
+                scores.append(float(score))
+        avg_debate_score = sum(scores) / len(scores) if scores else 0.0
+
+        tag_counts: dict = {}
+        for c in components:
+            for t in c.get("tags") or []:
+                tag_counts[t] = tag_counts.get(t, 0) + 1
+
+        return {
+            "total": total,
+            "active": active,
+            "deprecated": deprecated,
+            "targets": target_counts,
+            "debate_passed": debate_passed,
+            "avg_debate_score": avg_debate_score,
+            "tags": tag_counts,
+            "updated_at": data.get("updated_at", ""),
+        }
+
+    def prune(self, days_unused: int = 90) -> int:
+        """Remove deprecated entries whose updated_at is older than N days.
+
+        Returns the number of entries removed.
+        """
+        if days_unused < 0:
+            return 0
+        data = self.load()
+        cutoff = time.time() - (days_unused * 86400)
+        kept = []
+        removed = 0
+        for c in data["components"]:
+            if c.get("deprecated"):
+                ts = self._parse_ts(c.get("updated_at", ""))
+                if ts is not None and ts < cutoff:
+                    removed += 1
+                    continue
+            kept.append(c)
+        if removed:
+            data["components"] = kept
+            self.save(data)
+        return removed
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _bump_patch(version: str) -> str:
+        """1.2.3 -> 1.2.4"""
+        m = SEMVER_RE.match(version or "")
+        if not m:
+            return "1.0.0"
+        major, minor, patch = m.groups()
+        return f"{major}.{minor}.{int(patch) + 1}"
+
+    @staticmethod
+    def _parse_ts(value: str) -> Optional[float]:
+        """Parse an ISO 8601 UTC timestamp (YYYY-MM-DDTHH:MM:SSZ) to epoch seconds."""
+        if not value:
+            return None
+        try:
+            t = time.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
+            return time.mktime(t) - time.timezone
+        except (ValueError, TypeError):
+            return None
+
+
+# ---------------------------------------------------------------------------
+# Module-level convenience API (called by autonomy/loki cmd_magic)
+# ---------------------------------------------------------------------------
+
+def register_component(
+    registry_path: str = ".loki/magic/registry.json",
+    name: str = "",
+    spec_path: str = "",
+    target: str = "react",
+    react_path: str = "",
+    webcomponent_path: str = "",
+    test_path: str = "",
+    spec_hash: str = "",
+    description: str = "",
+    tags=None,
+    placement=None,
+    **extra,
+) -> dict:
+    """Register or update a component entry. Returns the stored entry as dict."""
+    tags = list(tags) if tags else []
+    if placement:
+        tags.append(f"placement:{placement}")
+    from pathlib import Path as _P
+    project_dir = str(_P(registry_path).parent.parent.parent)
+    reg = ComponentRegistry(project_dir)
+    entry = ComponentEntry(
+        name=name,
+        spec_path=spec_path,
+        react_path=react_path,
+        webcomponent_path=webcomponent_path,
+        test_path=test_path,
+        spec_hash=spec_hash,
+        description=description,
+        tags=tags,
+        targets=[target] if target != "both" else ["react", "webcomponent"],
+    )
+    stored = reg.register(entry)
+    from dataclasses import asdict as _asdict
+    return _asdict(stored)
+
+
+def prune_registry(registry_path: str = ".loki/magic/registry.json", days_unused: int = 90) -> int:
+    """Remove deprecated entries older than N days. Returns count removed."""
+    from pathlib import Path as _P
+    project_dir = str(_P(registry_path).parent.parent.parent)
+    return ComponentRegistry(project_dir).prune(days_unused)

package/magic/core/spec.py

@@ -0,0 +1,337 @@
+"""Spec management for Magic Modules.
+
+Specs are markdown files describing desired component behavior. They are
+the source of truth -- implementations regenerate when specs change.
+"""
+
+import re
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+SPEC_TEMPLATE = """# {name}
+
+## Description
+{description}
+
+## Props
+- `prop1` (string, required): Description
+- `prop2` (boolean, optional, default=false): Description
+
+## Behavior
+Describe how the component behaves, state transitions, user interactions.
+
+## Visual / Styling
+Describe the visual design: colors, spacing, typography, responsive behavior.
+
+## Accessibility
+- Keyboard navigation: [describe]
+- Screen reader: [describe]
+- Focus management: [describe]
+
+## Examples
+```tsx
+<{name} prop1="value" />
+```
+"""
+
+
+@dataclass
+class ComponentSpec:
+    """Structured representation of a component spec."""
+
+    name: str
+    description: str
+    markdown: str
+    props: dict = field(default_factory=dict)
+    behavior: str = ""
+    visual: str = ""
+    a11y: list = field(default_factory=list)
+    examples: list = field(default_factory=list)
+
+
+class SpecManager:
+    """Manage component specs stored as markdown under .loki/magic/specs/."""
+
+    # Matches a bullet prop line like:
+    #   - `name` (type, required): description
+    #   - `name` (type, optional, default=false): description
+    _PROP_LINE = re.compile(
+        r"^\s*[-*]\s*`(?P<name>[^`]+)`\s*"
+        r"(?:\((?P<meta>[^)]*)\))?"
+        r"\s*:\s*(?P<desc>.*)$"
+    )
+
+    # Code fences used to extract examples.
+    _CODE_FENCE = re.compile(
+        r"```(?P<lang>[a-zA-Z0-9_+-]*)\n(?P<code>.*?)```",
+        re.DOTALL,
+    )
+
+    def __init__(self, project_dir: str = "."):
+        self.specs_dir = Path(project_dir) / ".loki" / "magic" / "specs"
+        self.specs_dir.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def create_spec(self, name: str, description: str) -> ComponentSpec:
+        """Create a new spec file from a description.
+
+        This creates a scaffolded spec using SPEC_TEMPLATE. A caller can
+        later enrich the markdown via AI assistance and re-save.
+        """
+        safe_name = self._sanitize_name(name)
+        markdown = SPEC_TEMPLATE.format(name=safe_name, description=description)
+        spec = self.parse_markdown(markdown)
+        # parse_markdown may extract a slightly different name; honor the
+        # requested one for filesystem purposes.
+        spec.name = safe_name
+        self.save_spec(spec)
+        return spec
+
+    def load_spec(self, name: str) -> Optional[ComponentSpec]:
+        """Load existing spec by name."""
+        path = self._spec_path(name)
+        if not path.exists():
+            return None
+        markdown = path.read_text(encoding="utf-8")
+        spec = self.parse_markdown(markdown)
+        # Filesystem name is authoritative.
+        spec.name = self._sanitize_name(name)
+        return spec
+
+    def save_spec(self, spec: ComponentSpec) -> Path:
+        """Write spec to disk as .loki/magic/specs/<name>.md."""
+        path = self._spec_path(spec.name)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(spec.markdown, encoding="utf-8")
+        return path
+
+    def parse_markdown(self, md_text: str) -> ComponentSpec:
+        """Parse markdown into a structured ComponentSpec.
+
+        Recognized sections (case-insensitive header match):
+            # <Component Name>
+            ## Description
+            ## Props
+            ## Behavior
+            ## Visual / Styling   (also: Visual, Styling)
+            ## Accessibility      (also: A11y)
+            ## Examples
+        """
+        sections = self._split_sections(md_text)
+
+        name = sections.get("__title__", "").strip() or "Component"
+        description = sections.get("description", "").strip()
+        behavior = sections.get("behavior", "").strip()
+        visual = (
+            sections.get("visual / styling")
+            or sections.get("visual")
+            or sections.get("styling")
+            or ""
+        ).strip()
+
+        props_text = sections.get("props", "")
+        props = self._parse_props(props_text)
+
+        a11y_text = (
+            sections.get("accessibility")
+            or sections.get("a11y")
+            or ""
+        )
+        a11y = self._parse_bullets(a11y_text)
+
+        examples_text = sections.get("examples", "")
+        examples = self._parse_examples(examples_text)
+
+        return ComponentSpec(
+            name=name,
+            description=description,
+            markdown=md_text,
+            props=props,
+            behavior=behavior,
+            visual=visual,
+            a11y=a11y,
+            examples=examples,
+        )
+
+    def list_specs(self) -> list:
+        """List all spec names (without the .md extension)."""
+        if not self.specs_dir.exists():
+            return []
+        return sorted(p.stem for p in self.specs_dir.glob("*.md"))
+
+    def delete_spec(self, name: str) -> bool:
+        """Delete spec file. Returns True if removed, False if not found."""
+        path = self._spec_path(name)
+        if not path.exists():
+            return False
+        path.unlink()
+        return True
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _spec_path(self, name: str) -> Path:
+        return self.specs_dir / f"{self._sanitize_name(name)}.md"
+
+    @staticmethod
+    def _sanitize_name(name: str) -> str:
+        """Strip whitespace and any path separators from a spec name."""
+        cleaned = name.strip()
+        # Disallow path traversal characters.
+        cleaned = cleaned.replace("/", "_").replace("\\", "_")
+        return cleaned
+
+    @staticmethod
+    def _split_sections(md_text: str) -> dict:
+        """Split markdown into sections keyed by lowercased heading text.
+
+        The first H1 is stored under the special key '__title__'.
+        """
+        sections: dict = {}
+        current_key: Optional[str] = None
+        buffer: list = []
+        title_captured = False
+
+        def flush():
+            if current_key is not None:
+                sections[current_key] = "\n".join(buffer).strip("\n")
+
+        for line in md_text.splitlines():
+            h1 = re.match(r"^#\s+(.*?)\s*$", line)
+            h2 = re.match(r"^##\s+(.*?)\s*$", line)
+            if h1 and not title_captured:
+                sections["__title__"] = h1.group(1).strip()
+                title_captured = True
+                # Reset buffer so title body does not leak into next section.
+                if current_key is not None:
+                    flush()
+                    buffer = []
+                    current_key = None
+                continue
+            if h2:
+                # Close previous section.
+                flush()
+                current_key = h2.group(1).strip().lower()
+                buffer = []
+                continue
+            buffer.append(line)
+
+        flush()
+        return sections
+
+    @classmethod
+    def _parse_props(cls, props_text: str) -> dict:
+        """Parse a bullet list of prop definitions into a dict.
+
+        Each entry looks like:
+            - `name` (type, required): description
+            - `name` (type, optional, default=false): description
+        """
+        props: dict = {}
+        for raw in props_text.splitlines():
+            line = raw.rstrip()
+            if not line.strip():
+                continue
+            match = cls._PROP_LINE.match(line)
+            if not match:
+                continue
+            name = match.group("name").strip()
+            meta_raw = (match.group("meta") or "").strip()
+            desc = match.group("desc").strip()
+
+            prop_type = ""
+            required = False
+            default = None
+            extras: list = []
+
+            if meta_raw:
+                parts = [p.strip() for p in meta_raw.split(",") if p.strip()]
+                for idx, part in enumerate(parts):
+                    lowered = part.lower()
+                    if idx == 0 and "=" not in part and lowered not in (
+                        "required",
+                        "optional",
+                    ):
+                        prop_type = part
+                        continue
+                    if lowered == "required":
+                        required = True
+                    elif lowered == "optional":
+                        required = False
+                    elif "=" in part:
+                        key, _, value = part.partition("=")
+                        key = key.strip().lower()
+                        value = value.strip()
+                        if key == "default":
+                            default = value
+                        else:
+                            extras.append(part)
+                    else:
+                        extras.append(part)
+
+            props[name] = {
+                "type": prop_type,
+                "required": required,
+                "default": default,
+                "description": desc,
+                "extras": extras,
+            }
+        return props
+
+    @staticmethod
+    def _parse_bullets(text: str) -> list:
+        """Extract bullet list items as plain strings."""
+        items: list = []
+        for raw in text.splitlines():
+            line = raw.strip()
+            if not line:
+                continue
+            if line.startswith(("-", "*")):
+                items.append(line[1:].strip())
+        return items
+
+    @classmethod
+    def _parse_examples(cls, text: str) -> list:
+        """Extract fenced code blocks as example dicts."""
+        examples: list = []
+        for match in cls._CODE_FENCE.finditer(text):
+            lang = (match.group("lang") or "").strip()
+            code = match.group("code")
+            examples.append({"language": lang, "code": code})
+        return examples
+
+
+# ---------------------------------------------------------------------------
+# Module-level convenience API (called by autonomy/loki cmd_magic)
+# ---------------------------------------------------------------------------
+
+def generate_spec(name: str, out_path: str, from_spec=None, from_screenshot=None, description: str = "") -> str:
+    """Generate or copy a component spec to out_path.
+
+    If from_spec is given, copy its contents. If from_screenshot, delegate to
+    the generator's vision path. Otherwise create a template from SPEC_TEMPLATE.
+    Returns the path written.
+    """
+    from pathlib import Path as _P
+    out = _P(out_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    if from_spec:
+        out.write_text(_P(from_spec).read_text())
+        return str(out)
+    if from_screenshot:
+        try:
+            from magic.core.generator import ComponentGenerator
+            md = ComponentGenerator().generate_from_screenshot(from_screenshot, name)
+            out.write_text(md)
+            return str(out)
+        except Exception:
+            pass
+    desc = description or f"Loki Magic component {name}."
+    out.write_text(SPEC_TEMPLATE.format(name=name, description=desc))
+    return str(out)