loki-mode 6.75.3 → 6.76.0

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.75.3
+**Version:** v6.76.0
 
 ---
 

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '6.75.3'
+__version__ = '6.76.0'

package/mcp/magic_tools.py

@@ -0,0 +1,471 @@
+"""MCP tools for Magic Modules.
+
+Exposes loki magic functionality to AI coding assistants via the MCP
+protocol. Tools delegate to the magic/ package where possible and fall
+back to the `loki magic` CLI when direct imports are unavailable.
+
+Registration pattern:
+    from mcp.magic_tools import register_magic_tools
+    register_magic_tools(mcp_server)   # Called from mcp/server.py
+
+All tools are resilient: they catch exceptions and return structured
+error dicts rather than raising, so an MCP client always receives a
+well-formed JSON response.
+"""
+
+import json
+import re
+import subprocess
+from typing import Any, Dict, List, Optional
+
+
+# Regex used to validate component names. Mirrors the rule stated in the
+# tool docstrings so callers get a consistent, early error.
+_NAME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]*$")
+
+# Default timeout (seconds) for CLI subprocess calls. Generation involves
+# an LLM round-trip so it can legitimately take a while; we still cap it
+# to avoid hanging the MCP server indefinitely.
+_CLI_TIMEOUT = 600
+
+
+def _error(message: str, **extra: Any) -> Dict[str, Any]:
+    """Return a structured error dict."""
+    result: Dict[str, Any] = {"ok": False, "error": message}
+    result.update(extra)
+    return result
+
+
+def _ok(**fields: Any) -> Dict[str, Any]:
+    """Return a structured success dict."""
+    result: Dict[str, Any] = {"ok": True}
+    result.update(fields)
+    return result
+
+
+def _validate_name(name: str) -> Optional[str]:
+    """Return an error message if name is invalid, else None."""
+    if not isinstance(name, str) or not name:
+        return "name must be a non-empty string"
+    if not _NAME_RE.match(name):
+        return (
+            "name must match ^[a-zA-Z][a-zA-Z0-9_-]*$ "
+            "(letters, digits, underscore, hyphen; must start with a letter)"
+        )
+    return None
+
+
+def _run_loki(args: List[str], timeout: int = _CLI_TIMEOUT) -> Dict[str, Any]:
+    """Invoke the `loki` CLI and return a structured result.
+
+    The CLI is expected to emit JSON on stdout for machine consumers. If
+    stdout is not valid JSON we surface both stdout and stderr in the
+    error response so callers can diagnose.
+    """
+    cmd = ["loki", *args]
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError:
+        return _error("loki CLI not found on PATH", command=cmd)
+    except subprocess.TimeoutExpired:
+        return _error(
+            "loki CLI timed out", command=cmd, timeout_seconds=timeout
+        )
+    except Exception as exc:  # pragma: no cover - defensive
+        return _error(f"failed to invoke loki CLI: {exc}", command=cmd)
+
+    stdout = (proc.stdout or "").strip()
+    stderr = (proc.stderr or "").strip()
+
+    if proc.returncode != 0:
+        return _error(
+            f"loki CLI exited with code {proc.returncode}",
+            command=cmd,
+            stdout=stdout,
+            stderr=stderr,
+            returncode=proc.returncode,
+        )
+
+    # Try to decode JSON first; fall back to raw stdout if not JSON.
+    if stdout:
+        try:
+            parsed = json.loads(stdout)
+            if isinstance(parsed, dict):
+                parsed.setdefault("ok", True)
+                return parsed
+            return _ok(result=parsed)
+        except json.JSONDecodeError:
+            return _ok(stdout=stdout, stderr=stderr)
+
+    return _ok(stdout=stdout, stderr=stderr)
+
+
+# ---------------------------------------------------------------------------
+# Tool implementations
+# ---------------------------------------------------------------------------
+
+
+def loki_magic_generate(
+    name: str,
+    description: str = "",
+    target: str = "react",
+    placement: str = "",
+    tags: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Generate a new component from a description.
+
+    Args:
+        name: Component name (must match ^[a-zA-Z][a-zA-Z0-9_-]*$).
+        description: Natural-language description of what the component does.
+        target: 'react' | 'webcomponent' | 'both'.
+        placement: Optional file path where the component should be placed.
+        tags: List of tags for registry search.
+
+    Returns:
+        A dict with keys:
+          ok (bool), name (str), spec_path (str),
+          react_path (str, if target includes react),
+          webcomponent_path (str, if target includes webcomponent),
+          version (str), debate_passed (bool)
+        On failure: {"ok": False, "error": "..."}.
+    """
+    err = _validate_name(name)
+    if err:
+        return _error(err, name=name)
+
+    allowed_targets = {"react", "webcomponent", "both"}
+    if target not in allowed_targets:
+        return _error(
+            f"target must be one of {sorted(allowed_targets)}",
+            target=target,
+        )
+
+    if tags is not None and not isinstance(tags, list):
+        return _error("tags must be a list of strings", tags=tags)
+
+    args: List[str] = ["magic", "generate", name, "--target", target]
+    if description:
+        args.extend(["--description", description])
+    if placement:
+        args.extend(["--placement", placement])
+    if tags:
+        args.extend(["--tags", ",".join(str(t) for t in tags)])
+
+    return _run_loki(args)
+
+
+def loki_magic_list(
+    query: str = "",
+    tags: Optional[List[str]] = None,
+    target: Optional[str] = None,
+) -> Dict[str, Any]:
+    """List / search registered components.
+
+    Args:
+        query: Substring match against component names.
+        tags: Filter by tags (AND logic).
+        target: Filter by target framework.
+
+    Returns:
+        {"ok": True, "count": int, "components": [...]} on success,
+        or a structured error dict on failure.
+    """
+    if tags is not None and not isinstance(tags, list):
+        return _error("tags must be a list of strings", tags=tags)
+
+    try:
+        # Prefer direct Python API when available.
+        from magic.core.registry import ComponentRegistry  # type: ignore
+    except ImportError:
+        # Fall back to CLI if the magic package is not importable.
+        args: List[str] = ["magic", "list", "--json"]
+        if query:
+            args.extend(["--query", query])
+        if tags:
+            args.extend(["--tags", ",".join(str(t) for t in tags)])
+        if target:
+            args.extend(["--target", target])
+        return _run_loki(args)
+    except Exception as exc:
+        return _error(f"failed to import magic registry: {exc}")
+
+    try:
+        reg = ComponentRegistry(".")
+        results = reg.search(query=query, tags=tags, target=target)
+    except Exception as exc:
+        return _error(f"registry search failed: {exc}")
+
+    components = list(results) if results is not None else []
+    return _ok(count=len(components), components=components)
+
+
+def loki_magic_get(name: str) -> Dict[str, Any]:
+    """Fetch details for a specific component.
+
+    Args:
+        name: Component name (must match ^[a-zA-Z][a-zA-Z0-9_-]*$).
+
+    Returns:
+        {"ok": True, "component": {...}} on success,
+        or a structured error dict on failure.
+    """
+    err = _validate_name(name)
+    if err:
+        return _error(err, name=name)
+
+    try:
+        from magic.core.registry import ComponentRegistry  # type: ignore
+    except ImportError:
+        return _run_loki(["magic", "get", name, "--json"])
+    except Exception as exc:
+        return _error(f"failed to import magic registry: {exc}")
+
+    try:
+        reg = ComponentRegistry(".")
+        # Prefer a .get() method if the registry exposes one; otherwise
+        # fall back to searching by exact name.
+        component: Any = None
+        if hasattr(reg, "get"):
+            component = reg.get(name)
+        elif hasattr(reg, "find"):
+            component = reg.find(name)
+        else:
+            results = reg.search(query=name)
+            for item in (results or []):
+                if isinstance(item, dict) and item.get("name") == name:
+                    component = item
+                    break
+    except Exception as exc:
+        return _error(f"registry lookup failed: {exc}", name=name)
+
+    if component is None:
+        return _error(f"component not found: {name}", name=name)
+    return _ok(component=component)
+
+
+def loki_magic_update(
+    name: str,
+    spec_update: str = "",
+    force: bool = False,
+) -> Dict[str, Any]:
+    """Update a component when its spec has changed.
+
+    Args:
+        name: Component name.
+        spec_update: Optional updated description / spec text to apply
+            before regeneration.
+        force: If False (default), only regenerates when the spec hash
+            has diverged. If True, always regenerates.
+
+    Returns:
+        A dict describing the update result on success, or a structured
+        error dict on failure.
+    """
+    err = _validate_name(name)
+    if err:
+        return _error(err, name=name)
+
+    args: List[str] = ["magic", "update", name]
+    if spec_update:
+        args.extend(["--spec-update", spec_update])
+    if force:
+        args.append("--force")
+    args.append("--json")
+
+    return _run_loki(args)
+
+
+def loki_magic_debate(
+    name: str,
+    rounds: int = 3,
+    personas: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Run multi-persona debate on an existing component.
+
+    Args:
+        name: Component name.
+        rounds: Number of debate rounds (default 3).
+        personas: Optional list of persona identifiers. When omitted,
+            the debate runner uses its default persona set.
+
+    Returns:
+        Debate result including critiques and (if applicable) refined
+        code, or a structured error dict on failure.
+    """
+    err = _validate_name(name)
+    if err:
+        return _error(err, name=name)
+
+    if not isinstance(rounds, int) or rounds < 1:
+        return _error("rounds must be a positive integer", rounds=rounds)
+
+    if personas is not None and not isinstance(personas, list):
+        return _error("personas must be a list of strings", personas=personas)
+
+    try:
+        from magic.core.debate import DebateRunner  # type: ignore
+    except ImportError:
+        args: List[str] = ["magic", "debate", name, "--rounds", str(rounds)]
+        if personas:
+            args.extend(["--personas", ",".join(str(p) for p in personas)])
+        args.append("--json")
+        return _run_loki(args)
+    except Exception as exc:
+        return _error(f"failed to import debate runner: {exc}")
+
+    try:
+        runner_kwargs: Dict[str, Any] = {"rounds": rounds}
+        if personas:
+            runner_kwargs["personas"] = personas
+        # DebateRunner's exact constructor signature is defined by the
+        # magic package. We pass the workspace root positionally and
+        # forward debate params as kwargs, staying tolerant of minor
+        # signature differences.
+        try:
+            runner = DebateRunner(".", **runner_kwargs)
+        except TypeError:
+            runner = DebateRunner(".")
+            for attr, value in runner_kwargs.items():
+                try:
+                    setattr(runner, attr, value)
+                except Exception:
+                    pass
+
+        if hasattr(runner, "run"):
+            result = runner.run(name)
+        elif hasattr(runner, "debate"):
+            result = runner.debate(name)
+        else:
+            return _error(
+                "DebateRunner exposes neither run() nor debate()",
+                name=name,
+            )
+    except Exception as exc:
+        return _error(f"debate failed: {exc}", name=name)
+
+    if isinstance(result, dict):
+        result.setdefault("ok", True)
+        return result
+    return _ok(result=result)
+
+
+def loki_magic_tokens_extract() -> Dict[str, Any]:
+    """Extract design tokens from the current codebase.
+
+    Returns observed colors, spacing, typography, etc. Observation is
+    non-destructive: the registry is not modified (save=False).
+    """
+    try:
+        from magic.core.design_tokens import DesignTokens  # type: ignore
+    except ImportError:
+        return _run_loki(["magic", "tokens", "extract", "--json"])
+    except Exception as exc:
+        return _error(f"failed to import design tokens module: {exc}")
+
+    try:
+        dt = DesignTokens(".")
+        observed = dt.extract_from_codebase(save=False)
+    except Exception as exc:
+        return _error(f"token extraction failed: {exc}")
+
+    if isinstance(observed, dict):
+        observed.setdefault("ok", True)
+        return observed
+    return _ok(tokens=observed)
+
+
+def loki_magic_stats() -> Dict[str, Any]:
+    """Registry stats: total components, per-target counts, debate pass rate.
+
+    Returns:
+        A dict of statistics on success, or a structured error dict on
+        failure.
+    """
+    try:
+        from magic.core.registry import ComponentRegistry  # type: ignore
+    except ImportError:
+        return _run_loki(["magic", "stats", "--json"])
+    except Exception as exc:
+        return _error(f"failed to import magic registry: {exc}")
+
+    try:
+        stats = ComponentRegistry(".").stats()
+    except Exception as exc:
+        return _error(f"failed to compute stats: {exc}")
+
+    if isinstance(stats, dict):
+        stats.setdefault("ok", True)
+        return stats
+    return _ok(stats=stats)
+
+
+# ---------------------------------------------------------------------------
+# Public registration entry point
+# ---------------------------------------------------------------------------
+
+
+# Tuple of (callable, public-tool-name). Tool names are stable and match
+# the CLI verbs so MCP clients can predict them.
+_TOOLS = (
+    (loki_magic_generate, "loki_magic_generate"),
+    (loki_magic_list, "loki_magic_list"),
+    (loki_magic_get, "loki_magic_get"),
+    (loki_magic_update, "loki_magic_update"),
+    (loki_magic_debate, "loki_magic_debate"),
+    (loki_magic_tokens_extract, "loki_magic_tokens_extract"),
+    (loki_magic_stats, "loki_magic_stats"),
+)
+
+
+def register_magic_tools(mcp_server: Any) -> List[str]:
+    """Wire the module's functions into a FastMCP server instance.
+
+    Usage from mcp/server.py:
+        from mcp.magic_tools import register_magic_tools
+        register_magic_tools(mcp)
+
+    Args:
+        mcp_server: A FastMCP-compatible server instance exposing a
+            `.tool()` decorator factory.
+
+    Returns:
+        The list of tool names that were successfully registered.
+    """
+    if mcp_server is None:
+        raise ValueError("mcp_server must not be None")
+
+    if not hasattr(mcp_server, "tool"):
+        raise TypeError(
+            "mcp_server does not expose a .tool() method; "
+            "expected a FastMCP-compatible instance"
+        )
+
+    registered: List[str] = []
+    for func, tool_name in _TOOLS:
+        try:
+            mcp_server.tool()(func)
+            registered.append(tool_name)
+        except Exception:
+            # Don't let a single bad registration break the rest. The
+            # integration pass can inspect the returned list to confirm
+            # which tools made it through.
+            continue
+    return registered
+
+
+__all__ = [
+    "loki_magic_generate",
+    "loki_magic_list",
+    "loki_magic_get",
+    "loki_magic_update",
+    "loki_magic_debate",
+    "loki_magic_tokens_extract",
+    "loki_magic_stats",
+    "register_magic_tools",
+]

package/mcp/server.py

@@ -1954,6 +1954,19 @@ async def loki_phase_report() -> str:
 Use loki_state_get and loki_task_queue_list to gather data."""
 
 
+# ============================================================
+# MAGIC MODULES TOOLS (spec-driven component generation)
+# ============================================================
+
+try:
+    from mcp.magic_tools import register_magic_tools
+    register_magic_tools(mcp)
+except Exception as _magic_err:
+    # Magic Modules is optional; log and continue if unavailable
+    import sys as _sys
+    print(f"[warn] magic_tools registration skipped: {_magic_err}", file=_sys.stderr)
+
+
 # ============================================================
 # MAIN
 # ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "6.75.3",
+  "version": "6.76.0",
   "description": "Loki Mode by Autonomi - Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "agent",