framework-m-studio 0.2.2__py3-none-any.whl

framework_m_studio/docs_generator.py

@@ -0,0 +1,318 @@
+"""Documentation Generator for Framework M.
+
+Generates API documentation from DocTypes and Controllers.
+Supports markdown output and MkDocs integration.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+from urllib.request import Request, urlopen
+
+
+def format_field_table(fields: list[dict[str, Any]]) -> str:
+    """Format fields as a markdown table.
+
+    Args:
+        fields: List of field dictionaries.
+
+    Returns:
+        Markdown table string.
+    """
+    if not fields:
+        return "_No fields defined._\n"
+
+    lines = [
+        "| Field | Type | Required | Description | Validators |",
+        "|-------|------|----------|-------------|------------|",
+    ]
+
+    for field in fields:
+        name = field.get("name", "")
+        field_type = field.get("type", "str")
+        required = "✓" if field.get("required", True) else ""
+        description = field.get("description", "") or "-"
+
+        # Format validators
+        validators = field.get("validators", {})
+        if validators:
+            validator_strs = []
+            if validators.get("min_value") is not None:
+                validator_strs.append(f"min: {validators['min_value']}")
+            if validators.get("max_value") is not None:
+                validator_strs.append(f"max: {validators['max_value']}")
+            if validators.get("min_length") is not None:
+                validator_strs.append(f"minLen: {validators['min_length']}")
+            if validators.get("max_length") is not None:
+                validator_strs.append(f"maxLen: {validators['max_length']}")
+            if validators.get("pattern"):
+                validator_strs.append(f"pattern: `{validators['pattern']}`")
+            validators_str = ", ".join(validator_strs) if validator_strs else "-"
+        else:
+            validators_str = "-"
+
+        lines.append(
+            f"| {name} | {field_type} | {required} | {description} | {validators_str} |"
+        )
+
+    return "\n".join(lines) + "\n"
+
+
+def format_meta_section(meta: dict[str, Any]) -> str:
+    """Format Meta configuration as markdown.
+
+    Args:
+        meta: Meta configuration dictionary.
+
+    Returns:
+        Markdown string.
+    """
+    if not meta:
+        return ""
+
+    lines = ["## Configuration", "", "| Setting | Value |", "|---------|-------|"]
+
+    settings = [
+        ("Table Name", meta.get("tablename")),
+        ("Naming Pattern", meta.get("name_pattern")),
+        ("Submittable", meta.get("is_submittable")),
+        ("Track Changes", meta.get("track_changes")),
+    ]
+
+    for setting, value in settings:
+        if value is not None:
+            lines.append(f"| {setting} | `{value}` |")
+
+    if len(lines) > 4:  # Has at least one setting
+        lines.append("")
+        return "\n".join(lines)
+    return ""
+
+
+def generate_doctype_markdown(doctype_info: dict[str, Any]) -> str:
+    """Generate markdown documentation for a DocType.
+
+    Args:
+        doctype_info: DocType information dictionary.
+
+    Returns:
+        Markdown string.
+    """
+    name = doctype_info.get("name", "Unknown")
+    docstring = doctype_info.get("docstring", "")
+    fields = doctype_info.get("fields", [])
+    meta = doctype_info.get("meta", {})
+
+    lines = [
+        f"# {name}",
+        "",
+    ]
+
+    if docstring:
+        lines.extend([docstring, ""])
+
+    # Fields section
+    lines.extend(
+        [
+            "## Fields",
+            "",
+            format_field_table(fields),
+        ]
+    )
+
+    # Meta configuration section
+    meta_section = format_meta_section(meta)
+    if meta_section:
+        lines.append(meta_section)
+
+    # Controller info placeholder
+    lines.extend(
+        [
+            "## Controller",
+            "",
+            "Controller hooks are implemented in `*_controller.py` files.",
+            "Available lifecycle hooks:",
+            "",
+            "- `validate()` - Called before save, raise exceptions for validation errors",
+            "- `before_insert()` - Called before inserting a new document",
+            "- `after_insert()` - Called after successfully inserting",
+            "- `before_save()` - Called before saving (insert or update)",
+            "- `after_save()` - Called after saving",
+            "- `before_delete()` - Called before deleting",
+            "- `after_delete()` - Called after deleting",
+            "",
+        ]
+    )
+
+    return "\n".join(lines)
+
+
+def generate_index(doctypes: list[str]) -> str:
+    """Generate index.md with links to all DocTypes.
+
+    Args:
+        doctypes: List of DocType names.
+
+    Returns:
+        Index markdown string.
+    """
+    lines = [
+        "# API Reference",
+        "",
+        "## DocTypes",
+        "",
+    ]
+
+    for name in sorted(doctypes):
+        filename = name.lower() + ".md"
+        lines.append(f"- [{name}]({filename})")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def generate_api_reference(
+    doctypes: list[dict[str, Any]],
+    output_dir: Path,
+) -> None:
+    """Generate API reference documentation for all DocTypes.
+
+    Args:
+        doctypes: List of DocType info dictionaries.
+        output_dir: Output directory for markdown files.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    doctype_names = []
+
+    for doctype in doctypes:
+        name = doctype.get("name", "Unknown")
+        doctype_names.append(name)
+
+        markdown = generate_doctype_markdown(doctype)
+        filename = name.lower() + ".md"
+        (output_dir / filename).write_text(markdown)
+
+    # Generate index
+    index_md = generate_index(doctype_names)
+    (output_dir / "index.md").write_text(index_md)
+
+
+def export_openapi_json(
+    openapi_url: str,
+    output_file: Path,
+    *,
+    timeout: int = 30,
+) -> None:
+    """Export OpenAPI JSON from a running app.
+
+    Args:
+        openapi_url: URL to fetch OpenAPI schema from.
+        output_file: Output file path for JSON.
+        timeout: Request timeout in seconds.
+    """
+    request = Request(openapi_url)
+    request.add_header("Accept", "application/json")
+
+    with urlopen(request, timeout=timeout) as response:
+        schema = json.loads(response.read().decode("utf-8"))
+
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    output_file.write_text(json.dumps(schema, indent=2))
+
+
+def run_docs_generate(
+    output: str = "./docs/api",
+    project_root: str | None = None,
+    openapi_url: str | None = None,
+    build_site: bool = False,
+) -> None:
+    """Run the documentation generator.
+
+    Args:
+        output: Output directory for documentation.
+        project_root: Project root directory (for DocType discovery).
+        openapi_url: Optional OpenAPI URL to export.
+        build_site: If True, run mkdocs build if available.
+    """
+    from framework_m_studio.discovery import doctype_to_dict, scan_doctypes
+
+    output_dir = Path(output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Determine project root
+    root = Path(project_root) if project_root else Path.cwd()
+
+    # Scan for DocTypes
+    doctypes = scan_doctypes(root)
+    doctype_infos = [doctype_to_dict(dt) for dt in doctypes]
+
+    # Generate API reference
+    generate_api_reference(doctype_infos, output_dir)
+
+    print(f"📚 Generated documentation for {len(doctypes)} DocTypes")
+    print(f"   Output: {output_dir}")
+
+    # Export OpenAPI if URL provided
+    if openapi_url:
+        openapi_file = output_dir / "openapi.json"
+        try:
+            export_openapi_json(openapi_url, openapi_file)
+            print(f"   OpenAPI: {openapi_file}")
+        except Exception as e:
+            print(f"   ⚠️  Failed to export OpenAPI: {e}")
+
+    # Run mkdocs build if requested
+    if build_site:
+        run_mkdocs_build(root)
+
+
+def run_mkdocs_build(project_root: Path) -> bool:
+    """Run mkdocs build if mkdocs is installed.
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        True if build succeeded, False otherwise.
+    """
+    import shutil
+    import subprocess
+
+    # Check if mkdocs is available
+    mkdocs_path = shutil.which("mkdocs")
+    if not mkdocs_path:
+        print("   [i] mkdocs not found, skipping site build")
+        print("      Install with: pip install mkdocs-material")
+        return False
+
+    # Check if mkdocs.yml exists
+    mkdocs_config = project_root / "mkdocs.yml"
+    if not mkdocs_config.exists():
+        print("   [i] No mkdocs.yml found, skipping site build")
+        return False
+
+    # Run mkdocs build
+    print("   🔨 Building documentation site...")
+    try:
+        result = subprocess.run(
+            [mkdocs_path, "build"],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        if result.returncode == 0:
+            print("   ✅ Site built successfully")
+            return True
+        else:
+            print(f"   ❌ mkdocs build failed: {result.stderr}")
+            return False
+    except subprocess.TimeoutExpired:
+        print("   ❌ mkdocs build timed out")
+        return False
+    except Exception as e:
+        print(f"   ❌ mkdocs build error: {e}")
+        return False

framework_m_studio/git/__init__.py

@@ -0,0 +1 @@
+# Git module for Studio Cloud Mode

framework_m_studio/git/adapter.py

@@ -0,0 +1,309 @@
+"""Git Adapter Implementation.
+
+Uses the `git` CLI via asyncio subprocess for all Git operations.
+No external Python dependencies (gitpython, dulwich) required.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from urllib.parse import urlparse, urlunparse
+
+from .protocol import (
+    CommitResult,
+    GitAdapterProtocol,
+    GitAuthError,
+    GitConflictError,
+    GitError,
+    GitNetworkError,
+    GitStatus,
+)
+
+
+class GitAdapter:
+    """Git adapter using the git CLI.
+
+    Implements GitAdapterProtocol using asyncio subprocess to call git commands.
+    This approach has no Python dependencies and works with any git version.
+    """
+
+    def __init__(self, git_binary: str = "git"):
+        """Initialize GitAdapter.
+
+        Args:
+            git_binary: Path to git binary (default: "git" from PATH).
+        """
+        self.git_binary = git_binary
+
+    async def _run_git(
+        self,
+        args: list[str],
+        cwd: Path | None = None,
+        *,
+        check: bool = True,
+        env: dict[str, str] | None = None,
+    ) -> tuple[str, str]:
+        """Run a git command asynchronously.
+
+        Args:
+            args: Git command arguments (without 'git' prefix).
+            cwd: Working directory for the command.
+            check: If True, raise GitError on non-zero exit.
+            env: Additional environment variables.
+
+        Returns:
+            Tuple of (stdout, stderr).
+
+        Raises:
+            GitError: If command fails and check=True.
+        """
+        import os
+
+        full_env = os.environ.copy()
+        if env:
+            full_env.update(env)
+
+        # Disable interactive prompts
+        full_env["GIT_TERMINAL_PROMPT"] = "0"
+
+        proc = await asyncio.create_subprocess_exec(
+            self.git_binary,
+            *args,
+            cwd=cwd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=full_env,
+        )
+
+        stdout, stderr = await proc.communicate()
+        stdout_str = stdout.decode("utf-8", errors="replace").strip()
+        stderr_str = stderr.decode("utf-8", errors="replace").strip()
+
+        if check and proc.returncode != 0:
+            error_msg = stderr_str or stdout_str or "Unknown git error"
+            raise self._classify_error(error_msg, proc.returncode or 0)
+
+        return stdout_str, stderr_str
+
+    def _classify_error(self, message: str, returncode: int) -> GitError:
+        """Classify a git error into a specific exception type."""
+        lower_msg = message.lower()
+
+        if "authentication" in lower_msg or "permission denied" in lower_msg:
+            return GitAuthError(message, returncode)
+        if "conflict" in lower_msg or "merge conflict" in lower_msg:
+            return GitConflictError(message, returncode)
+        if (
+            "could not resolve host" in lower_msg
+            or "connection refused" in lower_msg
+            or "network" in lower_msg
+        ):
+            return GitNetworkError(message, returncode)
+
+        return GitError(message, returncode)
+
+    def _embed_token_in_url(self, url: str, token: str) -> str:
+        """Embed auth token in HTTPS URL.
+
+        Converts: https://github.com/user/repo.git
+        To:       https://token@github.com/user/repo.git
+        """
+        parsed = urlparse(url)
+        if parsed.scheme not in ("http", "https"):
+            return url  # SSH URLs don't use token embedding
+
+        # Replace or add username with token
+        netloc = f"{token}@{parsed.hostname}"
+        if parsed.port:
+            netloc += f":{parsed.port}"
+
+        return urlunparse(parsed._replace(netloc=netloc))
+
+    async def clone(
+        self,
+        repo_url: str,
+        target_dir: Path,
+        *,
+        auth_token: str | None = None,
+        branch: str | None = None,
+    ) -> None:
+        """Clone a repository to the target directory."""
+        url = repo_url
+        if auth_token:
+            url = self._embed_token_in_url(repo_url, auth_token)
+
+        args = ["clone", "--depth", "1"]  # Shallow clone for speed
+        if branch:
+            args.extend(["--branch", branch])
+        args.extend([url, str(target_dir)])
+
+        await self._run_git(args)
+
+    async def commit(
+        self,
+        workspace: Path,
+        message: str,
+        *,
+        author: str | None = None,
+    ) -> CommitResult:
+        """Stage all changes and create a commit."""
+        # Stage all changes
+        await self._run_git(["add", "-A"], cwd=workspace)
+
+        # Check if there's anything to commit
+        status_out, _ = await self._run_git(
+            ["status", "--porcelain"], cwd=workspace, check=False
+        )
+        if not status_out:
+            raise GitError("No changes to commit", 0)
+
+        # Count files
+        files_changed = len(status_out.strip().split("\n"))
+
+        # Build commit command
+        args = ["commit", "-m", message]
+        if author:
+            args.extend(["--author", author])
+
+        await self._run_git(args, cwd=workspace)
+
+        # Get commit SHA
+        sha, _ = await self._run_git(["rev-parse", "HEAD"], cwd=workspace)
+
+        return CommitResult(sha=sha, message=message, files_changed=files_changed)
+
+    async def push(
+        self,
+        workspace: Path,
+        branch: str | None = None,
+        *,
+        force: bool = False,
+    ) -> None:
+        """Push commits to remote."""
+        args = ["push"]
+        if force:
+            args.append("--force-with-lease")
+        if branch:
+            args.extend(["origin", branch])
+
+        await self._run_git(args, cwd=workspace)
+
+    async def pull(
+        self,
+        workspace: Path,
+        *,
+        rebase: bool = True,
+    ) -> None:
+        """Pull latest changes from remote."""
+        args = ["pull"]
+        if rebase:
+            args.append("--rebase")
+
+        await self._run_git(args, cwd=workspace)
+
+    async def create_branch(
+        self,
+        workspace: Path,
+        name: str,
+        *,
+        checkout: bool = True,
+    ) -> None:
+        """Create a new branch."""
+        if checkout:
+            await self._run_git(["checkout", "-b", name], cwd=workspace)
+        else:
+            await self._run_git(["branch", name], cwd=workspace)
+
+    async def checkout(
+        self,
+        workspace: Path,
+        ref: str,
+    ) -> None:
+        """Checkout a branch or commit."""
+        await self._run_git(["checkout", ref], cwd=workspace)
+
+    async def get_status(
+        self,
+        workspace: Path,
+    ) -> GitStatus:
+        """Get the current status of the workspace."""
+        # Get current branch
+        branch = await self.get_current_branch(workspace)
+
+        # Get status
+        status_out, _ = await self._run_git(
+            ["status", "--porcelain"], cwd=workspace, check=False
+        )
+
+        modified: list[str] = []
+        staged: list[str] = []
+        untracked: list[str] = []
+
+        for line in status_out.split("\n"):
+            if not line:
+                continue
+            status_code = line[:2]
+            filepath = line[3:]
+
+            if status_code[0] == "?":
+                untracked.append(filepath)
+            elif status_code[0] != " ":
+                staged.append(filepath)
+
+            if status_code[1] == "M":
+                modified.append(filepath)
+
+        is_clean = not (modified or staged or untracked)
+
+        # Get ahead/behind counts
+        ahead, behind = await self._get_ahead_behind(workspace, branch)
+
+        return GitStatus(
+            branch=branch,
+            is_clean=is_clean,
+            modified_files=modified,
+            staged_files=staged,
+            untracked_files=untracked,
+            ahead=ahead,
+            behind=behind,
+        )
+
+    async def get_current_branch(
+        self,
+        workspace: Path,
+    ) -> str:
+        """Get the name of the current branch."""
+        branch, _ = await self._run_git(
+            ["rev-parse", "--abbrev-ref", "HEAD"], cwd=workspace
+        )
+        return branch
+
+    async def _get_ahead_behind(self, workspace: Path, branch: str) -> tuple[int, int]:
+        """Get number of commits ahead/behind remote."""
+        try:
+            out, _ = await self._run_git(
+                ["rev-list", "--left-right", "--count", f"origin/{branch}...HEAD"],
+                cwd=workspace,
+                check=False,
+            )
+            if out:
+                parts = out.split()
+                if len(parts) == 2:
+                    behind = int(parts[0])
+                    ahead = int(parts[1])
+                    return ahead, behind
+        except (ValueError, GitError):
+            pass
+        return 0, 0
+
+    async def fetch(
+        self,
+        workspace: Path,
+    ) -> None:
+        """Fetch updates from remote without merging."""
+        await self._run_git(["fetch", "--quiet"], cwd=workspace)
+
+
+# Type assertion to verify protocol compliance
+_: GitAdapterProtocol = GitAdapter()