framework-m-studio 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

framework_m_studio/cli/__init__.py

@@ -0,0 +1,752 @@
+"""Framework M Studio CLI Commands.
+
+This module provides CLI commands that are registered via entry points
+when framework-m-studio is installed. These extend the base `m` CLI
+with developer tools.
+
+Entry Point Registration (pyproject.toml):
+    [project.entry-points."framework_m.cli_commands"]
+    codegen = "framework_m_studio.cli:codegen_app"
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import cyclopts
+
+if TYPE_CHECKING:
+    from framework_m_studio.checklist_parser import ChecklistItem
+
+# =============================================================================
+# Codegen Sub-App
+# =============================================================================
+
+codegen_app = cyclopts.App(
+    name="codegen",
+    help="Code generation tools for Framework M",
+)
+
+
+@codegen_app.command(name="client")
+def codegen_client(
+    lang: Annotated[
+        str,
+        cyclopts.Parameter(
+            name="--lang",
+            help="Target language: ts (TypeScript) or py (Python)",
+        ),
+    ] = "ts",
+    out: Annotated[
+        str,
+        cyclopts.Parameter(
+            name="--out",
+            help="Output directory for generated code",
+        ),
+    ] = "./generated",
+    openapi_url: Annotated[
+        str,
+        cyclopts.Parameter(
+            name="--openapi-url",
+            help="URL to fetch OpenAPI schema from",
+        ),
+    ] = "http://localhost:8000/schema/openapi.json",
+) -> None:
+    """Generate API client from OpenAPI schema.
+
+    Examples:
+        m codegen client --lang ts --out ./frontend/src/api
+        m codegen client --lang py --out ./scripts/api_client
+    """
+    from pathlib import Path
+
+    from framework_m_studio.sdk_generator import (
+        fetch_openapi_schema,
+        generate_typescript_client,
+        generate_typescript_types,
+    )
+
+    print(f"Generating {lang.upper()} client...")
+    print(f"  OpenAPI URL: {openapi_url}")
+    print(f"  Output: {out}")
+
+    # Create output directory
+    output_path = Path(out)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Fetch schema and generate
+    schema = fetch_openapi_schema(openapi_url)
+    if lang.lower() == "ts":
+        types_code = generate_typescript_types(schema)
+        client_code = generate_typescript_client(schema)
+        (output_path / "types.ts").write_text(types_code)
+        (output_path / "client.ts").write_text(client_code)
+
+
+@codegen_app.command(name="doctype")
+def codegen_doctype(
+    name: Annotated[
+        str,
+        cyclopts.Parameter(help="DocType class name (PascalCase)"),
+    ],
+    app: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--app",
+            help="Target app directory",
+        ),
+    ] = None,
+) -> None:
+    """Generate DocType Python code from schema.
+
+    This is the programmatic version of the Studio UI's
+    DocType builder. Useful for CI/CD pipelines.
+
+    Examples:
+        m codegen doctype Invoice --app apps/billing
+    """
+    print(f"Generating DocType: {name}")
+    if app:
+        print(f"  Target app: {app}")
+    print()
+    print("⚠️  Not yet implemented. Coming in Phase 07.")
+    print("    Will use LibCST for code generation")
+
+
+# =============================================================================
+# Docs Sub-App (Optional - registered via separate entry point if needed)
+# =============================================================================
+
+docs_app = cyclopts.App(
+    name="docs",
+    help="Documentation generation tools",
+)
+
+
+@docs_app.command(name="generate")
+def docs_generate(
+    output: Annotated[
+        str,
+        cyclopts.Parameter(
+            name="--output",
+            help="Output directory for documentation",
+        ),
+    ] = "./docs/developer/generated",
+    openapi_url: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--openapi-url",
+            help="URL to fetch OpenAPI schema from (optional)",
+        ),
+    ] = None,
+    protocols: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name="--protocols",
+            help="Generate Protocol reference documentation",
+        ),
+    ] = False,
+    protocols_dir: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--protocols-dir",
+            help="Directory containing Protocol interfaces",
+        ),
+    ] = None,
+) -> None:
+    """Generate API documentation from DocTypes.
+
+    Examples:
+        m docs generate --output ./docs/developer/generated
+        m docs generate --protocols --protocols-dir libs/framework-m-core/src/framework_m_core/interfaces
+    """
+    from pathlib import Path
+
+    from framework_m_studio.docs_generator import run_docs_generate
+
+    # Use current working directory as project root
+    project_root = Path.cwd()
+
+    # Look in src/doctypes if it exists, otherwise use project root
+    doctypes_dir = project_root / "src" / "doctypes"
+    scan_root = project_root / "src" if doctypes_dir.exists() else project_root
+
+    run_docs_generate(
+        output=output,
+        project_root=str(scan_root),
+        openapi_url=openapi_url,
+    )
+
+    # Generate Protocol documentation if requested
+    if protocols:
+        from framework_m_studio.protocol_scanner import (
+            generate_protocol_markdown,
+            scan_protocols,
+        )
+
+        if protocols_dir:
+            interfaces_path = Path(protocols_dir)
+        else:
+            # Default to framework-m-core interfaces
+            interfaces_path = (
+                project_root
+                / "libs"
+                / "framework-m-core"
+                / "src"
+                / "framework_m_core"
+                / "interfaces"
+            )
+
+        if interfaces_path.exists():
+            print(f"\n📜 Generating Protocol documentation from {interfaces_path}...")
+            output_path = Path(output) / "protocols"
+            output_path.mkdir(parents=True, exist_ok=True)
+
+            protocol_list = scan_protocols(interfaces_path)
+            for proto in protocol_list:
+                markdown = generate_protocol_markdown(proto)
+                filename = proto["name"].lower() + ".md"
+                (output_path / filename).write_text(markdown)
+                print(f"  ✓ {proto['name']}")
+
+            print(f"  Generated {len(protocol_list)} Protocol reference docs")
+        else:
+            print(f"\n⚠️  Protocols directory not found: {interfaces_path}")
+
+
+@docs_app.command(name="export")
+def docs_export(
+    output: Annotated[
+        str,
+        cyclopts.Parameter(
+            name="--output",
+            help="Output file path for the RAG corpus (.jsonl)",
+        ),
+    ] = "./docs/machine/corpus.jsonl",
+    include_tests: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name="--include-tests",
+            help="Include tests in the corpus",
+        ),
+    ] = False,
+) -> None:
+    """Export documentation as a machine-readable JSONL corpus.
+
+    Examples:
+        m docs export --output ./docs/machine/corpus.jsonl
+    """
+    from framework_m_studio.docs_generator import run_docs_export
+
+    run_docs_export(
+        output=output,
+        include_tests=include_tests,
+    )
+
+
+@docs_app.command(name="adr")
+def docs_adr(
+    action: Annotated[
+        str,
+        cyclopts.Parameter(help="Action: create or index"),
+    ],
+    title: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Title for new ADR (required for create)"),
+    ] = None,
+) -> None:
+    """Manage Architecture Decision Records.
+
+    Examples:
+        m docs adr create "Use Redis for caching"
+        m docs adr index
+    """
+    import re
+    from datetime import date
+    from pathlib import Path
+
+    project_root = Path.cwd()
+    adr_dir = project_root / "docs" / "adr"
+    template_path = project_root / "docs" / "processes" / "adr-template.md"
+
+    if action == "create":
+        if not title:
+            print('❌ Title required: m docs adr create "Your Title"')
+            return
+
+        # Find next ADR number
+        existing_adrs = list(adr_dir.glob("*.md"))
+        numbers = []
+        for f in existing_adrs:
+            match = re.match(r"(\d+)-", f.name)
+            if match:
+                numbers.append(int(match.group(1)))
+
+        next_num = max(numbers, default=0) + 1
+        num_str = f"{next_num:04d}"
+
+        # Create slug from title
+        slug = re.sub(r"[^\w\s-]", "", title.lower())
+        slug = re.sub(r"[-\s]+", "-", slug).strip("-")
+
+        filename = f"{num_str}-{slug}.md"
+        filepath = adr_dir / filename
+
+        # Read template and fill in
+        if template_path.exists():
+            content = template_path.read_text()
+            content = content.replace("ADR-0000", f"ADR-{num_str}")
+            content = content.replace("[Short Title]", title)
+            content = content.replace("YYYY-MM-DD", date.today().isoformat())
+        else:
+            content = f"""# ADR-{num_str}: {title}
+
+- **Status**: Proposed
+- **Date**: {date.today().isoformat()}
+
+## Context
+
+[Problem description]
+
+## Decision
+
+[What we decided]
+
+## Consequences
+
+[What becomes easier or harder]
+"""
+
+        adr_dir.mkdir(parents=True, exist_ok=True)
+        filepath.write_text(content)
+        print(f"✅ Created: {filepath}")
+
+    elif action == "index":
+        _generate_adr_index(adr_dir, "ADR")
+
+    else:
+        print(f"❌ Unknown action: {action}. Use 'create' or 'index'.")
+
+
+@docs_app.command(name="rfc")
+def docs_rfc(
+    action: Annotated[
+        str,
+        cyclopts.Parameter(help="Action: create or index"),
+    ],
+    title: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Title for new RFC (required for create)"),
+    ] = None,
+) -> None:
+    """Manage Request for Comments documents.
+
+    Examples:
+        m docs rfc create "New Event System Design"
+        m docs rfc index
+    """
+    import re
+    from datetime import date
+    from pathlib import Path
+
+    project_root = Path.cwd()
+    rfc_dir = project_root / "docs" / "rfcs"
+    template_path = project_root / "docs" / "processes" / "rfc-template.md"
+
+    if action == "create":
+        if not title:
+            print('❌ Title required: m docs rfc create "Your Title"')
+            return
+
+        # Find next RFC number
+        existing_rfcs = list(rfc_dir.glob("*.md")) if rfc_dir.exists() else []
+        numbers = []
+        for f in existing_rfcs:
+            match = re.match(r"(\d+)-", f.name)
+            if match:
+                numbers.append(int(match.group(1)))
+
+        next_num = max(numbers, default=0) + 1
+        num_str = f"{next_num:04d}"
+
+        # Create slug from title
+        slug = re.sub(r"[^\w\s-]", "", title.lower())
+        slug = re.sub(r"[-\s]+", "-", slug).strip("-")
+
+        filename = f"{num_str}-{slug}.md"
+        filepath = rfc_dir / filename
+
+        # Read template and fill in
+        if template_path.exists():
+            content = template_path.read_text()
+            content = content.replace("RFC-0000", f"RFC-{num_str}")
+            content = content.replace("[Short Title]", title)
+            content = content.replace("YYYY-MM-DD", date.today().isoformat())
+        else:
+            content = f"""# RFC-{num_str}: {title}
+
+- **Status**: Draft
+- **Date**: {date.today().isoformat()}
+
+## Summary
+
+[Brief description]
+
+## Motivation
+
+[Why are we doing this?]
+
+## Detailed Design
+
+[Technical details]
+"""
+
+        rfc_dir.mkdir(parents=True, exist_ok=True)
+        filepath.write_text(content)
+        print(f"✅ Created: {filepath}")
+
+    elif action == "index":
+        _generate_adr_index(rfc_dir, "RFC")
+
+    else:
+        print(f"❌ Unknown action: {action}. Use 'create' or 'index'.")
+
+
+@docs_app.command(name="features")
+def docs_features(
+    output: Annotated[
+        str,
+        cyclopts.Parameter(
+            name="--output",
+            help="Output file path for features page",
+        ),
+    ] = "./docs/developer/features.md",
+) -> None:
+    """Generate features documentation from checklists.
+
+    Examples:
+        m docs features --output ./docs/developer/features.md
+    """
+    from pathlib import Path
+
+    from framework_m_studio.checklist_parser import (
+        generate_features_summary,
+        scan_all_checklists,
+    )
+
+    project_root = Path.cwd()
+    checklists_dir = project_root / "checklists"
+
+    if not checklists_dir.exists():
+        print(f"❌ Checklists directory not found: {checklists_dir}")
+        return
+
+    print("📊 Scanning checklists...")
+    phases = scan_all_checklists(checklists_dir)
+
+    print(f"   Found {len(phases)} phases")
+    total_items = sum(len(p.items) for p in phases)
+    completed_items = sum(len([i for i in p.items if i.completed]) for p in phases)
+    print(f"   Total: {completed_items}/{total_items} items completed")
+
+    print("\n📝 Generating features page...")
+    summary = generate_features_summary(phases)
+
+    output_path = Path(output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(summary)
+
+    print(f"✅ Features page generated: {output_path}")
+
+
+@docs_app.command(name="release-notes")
+def docs_release_notes(
+    version: Annotated[
+        str,
+        cyclopts.Parameter(help="Version string (e.g., 1.0.0)"),
+    ],
+    compare_ref: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--compare",
+            help="Git ref to compare against (e.g., v0.9.0)",
+        ),
+    ] = None,
+    output: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--output",
+            help="Output file path for release notes",
+        ),
+    ] = None,
+) -> None:
+    """Generate release notes from checklist changes.
+
+    Examples:
+        m docs release-notes 1.0.0 --compare v0.9.0
+        m docs release-notes 1.0.0 --compare HEAD~1 --output CHANGELOG.md
+    """
+    import subprocess
+    from pathlib import Path
+
+    from framework_m_studio.checklist_parser import (
+        compare_versions,
+        generate_release_notes,
+        parse_checklist_file,
+    )
+
+    project_root = Path.cwd()
+    checklists_dir = project_root / "checklists"
+
+    if not compare_ref:
+        print("❌ --compare ref required (e.g., --compare v0.9.0)")
+        return
+
+    print(f"📊 Comparing checklists: {compare_ref} vs current")
+
+    # Get list of checklist files
+    current_files = list(checklists_dir.glob("phase-*.md"))
+
+    all_changes: dict[str, list[ChecklistItem]] = {
+        "newly_completed": [],
+        "newly_added": [],
+        "removed": [],
+    }
+
+    for current_file in current_files:
+        # Get old version from git
+        relative_path = current_file.relative_to(project_root)
+        try:
+            result = subprocess.run(
+                ["git", "show", f"{compare_ref}:{relative_path}"],
+                cwd=project_root,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            old_content = result.stdout
+
+            # Parse old version
+            old_temp = project_root / ".temp_old_checklist.md"
+            old_temp.write_text(old_content)
+            old_phase = parse_checklist_file(old_temp)
+            old_temp.unlink()
+
+            # Parse current version
+            current_phase = parse_checklist_file(current_file)
+
+            # Compare
+            changes = compare_versions(old_phase.items, current_phase.items)
+
+            all_changes["newly_completed"].extend(changes["newly_completed"])
+            all_changes["newly_added"].extend(changes["newly_added"])
+            all_changes["removed"].extend(changes["removed"])
+
+        except subprocess.CalledProcessError:
+            # File didn't exist in old version
+            continue
+
+    print(f"   Newly completed: {len(all_changes['newly_completed'])}")
+    print(f"   Newly added: {len(all_changes['newly_added'])}")
+
+    print("\n📝 Generating release notes...")
+    notes = generate_release_notes(all_changes, version)
+
+    if output:
+        output_path = Path(output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Prepend to existing changelog if it exists
+        if output_path.exists():
+            existing = output_path.read_text()
+            notes = notes + "\n\n---\n\n" + existing
+
+        output_path.write_text(notes)
+        print(f"✅ Release notes written to: {output_path}")
+    else:
+        print("\n" + notes)
+
+
+def _generate_adr_index(docs_dir: Path, doc_type: str) -> None:
+    """Generate index.md and Docusaurus sidebar for ADRs or RFCs."""
+    import json
+    import re
+
+    if not docs_dir.exists():
+        print(f"❌ Directory not found: {docs_dir}")
+        return
+
+    # Collect all documents
+    docs = []
+    for f in sorted(docs_dir.glob("*.md")):
+        if f.name in ("index.md", "_category_.json"):
+            continue
+
+        match = re.match(r"(\d+)-(.+)\.md", f.name)
+        if match:
+            num = match.group(1)
+            # Extract title from file
+            content = f.read_text()
+            title_match = re.search(r"^#\s+.+:\s*(.+)$", content, re.MULTILINE)
+            title = (
+                title_match.group(1)
+                if title_match
+                else match.group(2).replace("-", " ").title()
+            )
+
+            # Extract status
+            status_match = re.search(r"\*\*Status\*\*:\s*(\w+)", content)
+            status = status_match.group(1) if status_match else "Unknown"
+
+            docs.append(
+                {
+                    "num": num,
+                    "title": title,
+                    "status": status,
+                    "filename": f.name,
+                    "slug": f.stem,  # filename without .md
+                }
+            )
+
+    # Generate index.md
+    lines = [
+        f"# {doc_type} Index",
+        "",
+        f"This index contains all {doc_type}s in chronological order.",
+        "",
+        "| # | Title | Status |",
+        "|---|-------|--------|",
+    ]
+
+    for doc in docs:
+        lines.append(
+            f"| [{doc['num']}](./{doc['filename']}) | {doc['title']} | {doc['status']} |"
+        )
+
+    lines.append("")
+    lines.append(f"_Total: {len(docs)} {doc_type}s_")
+
+    index_path = docs_dir / "index.md"
+    index_path.write_text("\n".join(lines))
+    print(f"✅ Generated: {index_path} ({len(docs)} {doc_type}s)")
+
+    # Generate Docusaurus _category_.json for sidebar with lazy-loading
+    category_config = {
+        "label": f"{doc_type}s",
+        "position": 1,
+        "collapsed": True,  # Enable lazy-loading by default collapsed
+        "collapsible": True,
+        "link": {
+            "type": "doc",
+            "id": "index",
+        },
+    }
+    category_path = docs_dir / "_category_.json"
+    category_path.write_text(json.dumps(category_config, indent=2))
+    print(f"✅ Generated: {category_path} (Docusaurus sidebar)")
+
+    # Generate sidebar items JSON for programmatic use
+    sidebar_items = {
+        "type": "category",
+        "label": f"{doc_type}s",
+        "collapsed": True,
+        "items": [
+            {
+                "type": "doc",
+                "id": f"{doc_type.lower()}/{doc['slug']}",
+                "label": f"{doc_type}-{doc['num']}: {doc['title'][:40]}{'...' if len(doc['title']) > 40 else ''}",
+            }
+            for doc in docs
+        ],
+    }
+    sidebar_path = docs_dir / "_sidebar.json"
+    sidebar_path.write_text(json.dumps(sidebar_items, indent=2))
+    print(f"✅ Generated: {sidebar_path} (sidebar items)")
+
+
+# =============================================================================
+# Studio Sub-App (Main command to start Studio server)
+# =============================================================================
+
+studio_app = cyclopts.App(
+    name="studio",
+    help="Start Framework M Studio visual editor",
+)
+
+
+@studio_app.default
+def studio_serve(
+    port: Annotated[
+        int,
+        cyclopts.Parameter(
+            name="--port",
+            help="Port to run Studio on",
+        ),
+    ] = 9000,
+    host: Annotated[
+        str,
+        cyclopts.Parameter(
+            name="--host",
+            help="Host to bind to",
+        ),
+    ] = "127.0.0.1",
+    reload: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name="--reload",
+            help="Enable auto-reload for development",
+        ),
+    ] = False,
+    cloud: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name="--cloud",
+            help="Enable cloud mode (Git-backed workspaces)",
+        ),
+    ] = False,
+) -> None:
+    """Start Framework M Studio.
+
+    Examples:
+        m studio              # Start on port 9000
+        m studio --port 8000  # Custom port
+        m studio --reload     # Development mode
+        m studio --cloud      # Enable cloud mode
+    """
+    import os
+
+    import uvicorn
+
+    # Print startup banner
+    print()
+    print("🎨 Starting Framework M Studio")
+    print(f"   ➜ Local:   http://{host}:{port}/studio/")
+    print(f"   ➜ API:     http://{host}:{port}/studio/api/")
+    print(f"  🔌 API Health:   http://{host}:{port}/studio/api/health")
+    print()
+
+    if cloud:
+        print("☁️  Cloud mode enabled - Git-backed workspaces")
+        os.environ["STUDIO_CLOUD_MODE"] = "1"
+        print()
+
+    # Start uvicorn
+    uvicorn.run(
+        "framework_m_studio.app:app",
+        host=host,
+        port=port,
+        reload=reload,
+        log_level="info",
+    )
+
+
+__all__ = [
+    "codegen_app",
+    "codegen_client",
+    "codegen_doctype",
+    "docs_app",
+    "docs_generate",
+    "studio_app",
+    "studio_serve",
+]