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

framework_m_studio/cli/quality.py

@@ -0,0 +1,157 @@
+"""Quality assurance commands for Framework M."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+
+
+def get_pythonpath() -> str:
+    """Construct PYTHONPATH including current directory and src."""
+    cwd = Path.cwd()
+    paths = [str(cwd)]
+
+    src = cwd / "src"
+    if src.exists():
+        paths.append(str(src))
+
+    return ":".join(paths)
+
+
+def build_pytest_command(
+    verbose: bool = False,
+    coverage: bool = False,
+    filter_expr: str | None = None,
+    extra_args: tuple[str, ...] = (),
+) -> list[str]:
+    """Build pytest command."""
+    cmd = [sys.executable, "-m", "pytest"]
+    if verbose:
+        cmd.append("-v")
+    if coverage:
+        cmd.append("--cov")
+    if filter_expr:
+        cmd.extend(["-k", filter_expr])
+    if extra_args:
+        cmd.extend(extra_args)
+    else:
+        cmd.append(".")
+    return cmd
+
+
+def build_ruff_check_command(
+    fix: bool = False,
+    extra_args: tuple[str, ...] = (),
+) -> list[str]:
+    """Build ruff check command."""
+    cmd = [sys.executable, "-m", "ruff", "check"]
+    if fix:
+        cmd.append("--fix")
+    if extra_args:
+        cmd.extend(extra_args)
+    return cmd
+
+
+def build_ruff_format_command(
+    check: bool = False,
+    extra_args: tuple[str, ...] = (),
+) -> list[str]:
+    """Build ruff format command."""
+    cmd = [sys.executable, "-m", "ruff", "format"]
+    if check:
+        cmd.append("--check")
+    if extra_args:
+        cmd.extend(extra_args)
+    return cmd
+
+
+def build_mypy_command(
+    strict: bool = False,
+    extra_args: tuple[str, ...] = (),
+) -> list[str]:
+    """Build mypy command."""
+    cmd = [sys.executable, "-m", "mypy"]
+    if strict:
+        cmd.append("--strict")
+    if extra_args:
+        cmd.extend(extra_args)
+    return cmd
+
+
+def _run_command(cmd: list[str]) -> None:
+    """Run a command and exit with its return code."""
+    try:
+        subprocess.run(cmd, check=True)
+        sys.exit(0)
+    except subprocess.CalledProcessError as e:
+        sys.exit(e.returncode)
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        sys.exit(130)
+
+
+def test_command(
+    path: Annotated[
+        str | None, cyclopts.Parameter(name="--path", help="Test path")
+    ] = None,
+    verbose: Annotated[
+        bool, cyclopts.Parameter(name="--verbose", help="Verbose output")
+    ] = False,
+    coverage: Annotated[
+        bool, cyclopts.Parameter(name="--coverage", help="Enable coverage")
+    ] = False,
+    filter: Annotated[
+        str | None, cyclopts.Parameter(name="--filter", help="Filter tests")
+    ] = None,
+) -> None:
+    """Run tests using pytest."""
+    extra = (path,) if path else ()
+    cmd = build_pytest_command(
+        verbose=verbose, coverage=coverage, filter_expr=filter, extra_args=extra
+    )
+    _run_command(cmd)
+
+
+def lint_command(
+    fix: Annotated[bool, cyclopts.Parameter(name="--fix", help="Fix issues")] = False,
+) -> None:
+    """Lint code using ruff."""
+    cmd = build_ruff_check_command(fix=fix)
+    _run_command(cmd)
+
+
+def format_command(
+    check: Annotated[
+        bool, cyclopts.Parameter(name="--check", help="Check only")
+    ] = False,
+) -> None:
+    """Format code using ruff."""
+    cmd = build_ruff_format_command(check=check)
+    _run_command(cmd)
+
+
+def typecheck_command(
+    strict: Annotated[
+        bool, cyclopts.Parameter(name="--strict", help="Strict mode")
+    ] = False,
+) -> None:
+    """Type check code using mypy."""
+    cmd = build_mypy_command(strict=strict)
+    _run_command(cmd)
+
+
+__all__ = [
+    "build_mypy_command",
+    "build_pytest_command",
+    "build_ruff_check_command",
+    "build_ruff_format_command",
+    "format_command",
+    "get_pythonpath",
+    "lint_command",
+    "test_command",
+    "typecheck_command",
+]

framework_m_studio/cli/studio.py

@@ -0,0 +1,159 @@
+"""Studio CLI Command - Admin Interface Server.
+
+This module provides the `m studio` CLI command for running
+Framework M Studio - the admin and development interface.
+
+Usage:
+    m studio                # Start Studio on default port (9000)
+    m studio --port 9001    # Custom port
+    m studio --reload       # Enable auto-reload
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+
+# Default Studio configuration
+DEFAULT_STUDIO_PORT = 9000
+DEFAULT_STUDIO_APP = "framework_m_studio.app:app"
+
+
+def get_studio_app() -> str:
+    """Get the Studio app path.
+
+    Returns:
+        Studio app path in module:attribute format
+    """
+    return DEFAULT_STUDIO_APP
+
+
+def get_pythonpath() -> str:
+    """Get PYTHONPATH with src/ directory included.
+
+    Returns:
+        PYTHONPATH string with src/ prepended
+    """
+    cwd = Path.cwd()
+    src_path = cwd / "src"
+
+    paths = []
+
+    # Add src/ if it exists
+    if src_path.exists():
+        paths.append(str(src_path))
+
+    # Add current directory
+    paths.append(str(cwd))
+
+    # Preserve existing PYTHONPATH
+    existing = os.environ.get("PYTHONPATH", "")
+    if existing:
+        paths.append(existing)
+
+    return os.pathsep.join(paths)
+
+
+def build_studio_command(
+    host: str = "127.0.0.1",
+    port: int = DEFAULT_STUDIO_PORT,
+    reload: bool = False,
+    log_level: str | None = None,
+) -> list[str]:
+    """Build the uvicorn command line for Studio.
+
+    Args:
+        host: Host to bind to
+        port: Port to bind to
+        reload: Enable auto-reload
+        log_level: Log level (debug, info, warning, error)
+
+    Returns:
+        Complete command as list of strings
+    """
+    app_path = get_studio_app()
+    cmd = [sys.executable, "-m", "uvicorn", app_path]
+
+    cmd.extend(["--host", host])
+    cmd.extend(["--port", str(port)])
+
+    if reload:
+        cmd.append("--reload")
+
+    if log_level:
+        cmd.extend(["--log-level", log_level])
+
+    return cmd
+
+
+def studio_command(
+    host: Annotated[
+        str,
+        cyclopts.Parameter(name="--host", help="Host to bind to"),
+    ] = "127.0.0.1",
+    port: Annotated[
+        int,
+        cyclopts.Parameter(name="--port", help="Port to bind to"),
+    ] = DEFAULT_STUDIO_PORT,
+    reload: Annotated[
+        bool,
+        cyclopts.Parameter(name="--reload", help="Enable auto-reload for development"),
+    ] = False,
+    log_level: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name="--log-level", help="Log level (debug, info, warning, error)"
+        ),
+    ] = None,
+) -> None:
+    """Start Framework M Studio - the admin interface.
+
+    Studio provides a web-based admin UI for:
+    - Browsing and editing DocTypes
+    - Monitoring jobs and events
+    - Running queries and reports
+
+    Examples:
+        m studio                    # Default port 9000
+        m studio --port 9001        # Custom port
+        m studio --reload           # Dev mode with auto-reload
+    """
+    # Set up environment
+    env = os.environ.copy()
+    env["PYTHONPATH"] = get_pythonpath()
+
+    # Build command
+    cmd = build_studio_command(
+        host=host,
+        port=port,
+        reload=reload,
+        log_level=log_level,
+    )
+
+    print("Starting Framework M Studio")
+    print("=" * 40)
+    print(f"  URL: http://{host}:{port}")
+    print(f"  Reload: {reload}")
+    print()
+
+    # Execute uvicorn
+    try:
+        subprocess.run(cmd, env=env, check=True)
+    except subprocess.CalledProcessError as e:
+        raise SystemExit(e.returncode) from e
+    except KeyboardInterrupt:
+        print("\nStudio stopped.")
+
+
+__all__ = [
+    "DEFAULT_STUDIO_APP",
+    "DEFAULT_STUDIO_PORT",
+    "build_studio_command",
+    "get_studio_app",
+    "studio_command",
+]

framework_m_studio/cli/utility.py

@@ -0,0 +1,50 @@
+"""Utility CLI commands for Framework M Studio."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import cyclopts
+from rich.console import Console
+
+console = Console()
+
+
+def check_ipython_installed() -> bool:
+    """Check if IPython is installed."""
+    try:
+        import IPython  # type: ignore # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def console_command() -> None:
+    """Start an interactive console."""
+    if check_ipython_installed():
+        import IPython
+
+        IPython.embed(header="Framework M Console")
+    else:
+        import code
+
+        code.interact(banner="Framework M Console (IPython not installed)")
+
+
+def routes_command(
+    app_path: Annotated[
+        str | None,
+        cyclopts.Parameter(name="--app", help="App path to inspect"),
+    ] = None,
+) -> None:
+    """List API routes."""
+    console.print("Routes: /api/v1 (Mock)")
+    if app_path:
+        console.print(f"Inspecting app: {app_path}")
+
+
+__all__ = [
+    "console_command",
+    "routes_command",
+]

framework_m_studio/codegen/generator.py

@@ -44,9 +44,13 @@ def _get_jinja_env() -> Environment:
 
 
 def _to_snake_case(name: str) -> str:
-    """Convert PascalCase to snake_case."""
+    """Convert PascalCase or 'Spaced Words' to snake_case."""
+    # First, replace spaces and hyphens with underscores
+    name = name.replace(" ", "_").replace("-", "_")
     s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
-    return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+    result = re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+    # Collapse multiple underscores
+    return re.sub("_+", "_", result)
 
 
 def _get_test_value(field_type: str) -> str:

framework_m_studio/codegen/parser.py

@@ -41,6 +41,8 @@ class FieldSchema:
     required: bool = True
     description: str | None = None
     label: str | None = None
+    link_doctype: str | None = None  # For Link fields - which DocType to link to
+    table_doctype: str | None = None  # For Table fields - which DocType for child table
     validators: dict[str, Any] = field(default_factory=dict)
 
 
@@ -54,6 +56,7 @@ class ConfigSchema:
     is_submittable: bool = False
     is_tree: bool = False
     track_changes: bool = True
+    permissions: dict[str, list[str]] | None = None
     extra: dict[str, Any] = field(default_factory=dict)
 
 
@@ -199,8 +202,58 @@ class DocTypeParserVisitor(cst.CSTVisitor):
         validators: dict[str, Any] = {}
         description: str | None = None
         label: str | None = None
+        link_doctype: str | None = None
+        table_doctype: str | None = None
+
+        # Helper to check Annotated type recursively (handles Union/BinaryOp)
+        def extract_annotated_metadata(
+            type_node: cst.BaseExpression,
+        ) -> tuple[str | None, str | None]:
+            """Extract link_doctype/table_doctype from Annotated, even in unions."""
+            nonlocal field_type
+
+            # Handle BinaryOp (e.g., Type | None)
+            if isinstance(type_node, cst.BinaryOperation):
+                # Check left side (usually the main type)
+                left_link, left_table = extract_annotated_metadata(type_node.left)
+                if left_link or left_table:
+                    return left_link, left_table
+                # Check right side
+                return extract_annotated_metadata(type_node.right)
+
+            # Handle Subscript (Annotated, Optional, etc.)
+            if isinstance(type_node, cst.Subscript):
+                subscript_value = _node_to_source(type_node.value)
+
+                if subscript_value == "Annotated":
+                    slice_elements = type_node.slice
+                    if isinstance(slice_elements, tuple) and len(slice_elements) >= 1:
+                        # Extract base type
+                        first_elem = slice_elements[0]
+                        if isinstance(first_elem.slice, cst.Index):
+                            field_type = _node_to_source(first_elem.slice.value)
+                        else:
+                            field_type = _node_to_source(first_elem.slice)
+
+                        # Look for Link() in metadata
+                        for elem in slice_elements[1:]:
+                            if isinstance(elem.slice, cst.Index):
+                                value = elem.slice.value
+                            else:
+                                value = elem.slice
+
+                            if isinstance(value, cst.Call):
+                                func_name = _node_to_source(value.func)
+                                if func_name == "Link" and value.args:
+                                    arg_value = _node_to_source(value.args[0].value)
+                                    return arg_value.strip("\"'"), None
+
+            return None, None
+
+        # Extract Link/Table metadata from type annotation
+        link_doctype, table_doctype = extract_annotated_metadata(field_type_raw)
 
-        # Check for Annotated[type, Field(...)] pattern
+        # Also check for Annotated at top level (non-union case)
         if isinstance(field_type_raw, cst.Subscript):
             subscript_value = _node_to_source(field_type_raw.value)
             if subscript_value == "Annotated":
@@ -214,7 +267,7 @@ class DocTypeParserVisitor(cst.CSTVisitor):
                     else:
                         field_type = _node_to_source(first_elem.slice)
 
-                    # Look for Field() in remaining elements
+                    # Look for Link() or Field() in remaining elements
                     for elem in slice_elements[1:]:
                         if isinstance(elem.slice, cst.Index):
                             value = elem.slice.value
@@ -223,7 +276,12 @@ class DocTypeParserVisitor(cst.CSTVisitor):
 
                         if isinstance(value, cst.Call):
                             func_name = _node_to_source(value.func)
-                            if func_name == "Field":
+                            if func_name == "Link":
+                                # Extract linked DocType: Link("Supplier")
+                                if value.args:
+                                    arg_value = _node_to_source(value.args[0].value)
+                                    link_doctype = arg_value.strip("\"'")
+                            elif func_name == "Field":
                                 default_value, validators, description, label = (
                                     _parse_field_call(value)
                                 )
@@ -232,7 +290,6 @@ class DocTypeParserVisitor(cst.CSTVisitor):
                                     default_value = None
                                 elif default_value is not None:
                                     required = False
-                                break
 
         # Check for Optional type
         if "Optional" in field_type or "None" in field_type:
@@ -258,6 +315,12 @@ class DocTypeParserVisitor(cst.CSTVisitor):
         elif node.value:
             default_value = _node_to_source(node.value)
 
+        # Override type for special field types
+        if link_doctype:
+            field_type = "Link"  # Frontend expects "Link" as the type
+        elif table_doctype:
+            field_type = "Table"  # Frontend expects "Table" as the type
+
         field_schema = FieldSchema(
             name=field_name,
             type=field_type,
@@ -265,6 +328,8 @@ class DocTypeParserVisitor(cst.CSTVisitor):
             required=required,
             description=description,
             label=label,
+            link_doctype=link_doctype,
+            table_doctype=table_doctype,
             validators=validators,
         )
         self._current_fields.append(field_schema)
@@ -309,6 +374,9 @@ class DocTypeParserVisitor(cst.CSTVisitor):
             self._current_config.is_tree = value.lower() == "true"
         elif name == "track_changes":
             self._current_config.track_changes = value.lower() != "false"
+        elif name == "permissions":
+            # Parse permissions dict from source code string
+            self._current_config.permissions = _parse_permissions_dict(value)
         else:
             self._current_config.extra[name] = value
 
@@ -318,6 +386,32 @@ class DocTypeParserVisitor(cst.CSTVisitor):
 # =============================================================================
 
 
+def _parse_permissions_dict(value: str) -> dict[str, list[str]] | None:
+    """Parse permissions dict from source code string.
+
+    Converts source code like:
+        {"read": ["Employee"], "write": ["Manager"]}
+    to an actual Python dict.
+
+    Args:
+        value: Source code string representing the dict
+
+    Returns:
+        Parsed permissions dict or None if parsing fails
+    """
+    import ast
+
+    try:
+        # Use ast.literal_eval to safely parse the dict
+        parsed = ast.literal_eval(value)
+        if isinstance(parsed, dict):
+            # Ensure all values are lists of strings
+            return {k: v if isinstance(v, list) else [v] for k, v in parsed.items()}
+    except (ValueError, SyntaxError):
+        pass
+    return None
+
+
 def _get_attribute_name(node: cst.Attribute) -> str:
     """Get full attribute name from Attribute node."""
     parts: list[str] = []
@@ -517,6 +611,8 @@ def doctype_to_dict(doctype: DocTypeSchema) -> dict[str, Any]:
                 "required": f.required,
                 "label": f.label,
                 "description": f.description,
+                "link_doctype": f.link_doctype,  # Include Link field metadata
+                "table_doctype": f.table_doctype,  # Include Table field metadata
                 "validators": f.validators,
             }
             for f in doctype.fields
@@ -528,6 +624,7 @@ def doctype_to_dict(doctype: DocTypeSchema) -> dict[str, Any]:
             "is_submittable": doctype.config.is_submittable,
             "is_tree": doctype.config.is_tree,
             "track_changes": doctype.config.track_changes,
+            "permissions": doctype.config.permissions,
             **doctype.config.extra,
         },
         "docstring": doctype.docstring,

framework_m_studio/codegen/templates/doctype.py.jinja2

@@ -5,7 +5,7 @@ Generated by Framework M Studio.
 
 from __future__ import annotations
 
-from typing import ClassVar
+from typing import ClassVar{% if fields|selectattr('link_doctype')|list or fields|selectattr('table_doctype')|list %}, Annotated{% endif %}
 
 {% if imports %}
 {% for imp in imports %}
@@ -13,7 +13,10 @@ from typing import ClassVar
 {% endfor %}
 {% endif %}
 from pydantic import Field
-from framework_m.core.base import BaseDocType
+from framework_m_core.domain.base_doctype import BaseDocType
+{% if fields|selectattr('link_doctype')|list %}
+from framework_m_core.domain.mixins import Link
+{% endif %}
 
 
 class {{ name }}(BaseDocType):
@@ -24,8 +27,14 @@ class {{ name }}(BaseDocType):
 {% if fields %}
 {% for field in fields %}
 {%- set has_field_args = field.description or field.label or field.validators %}
+{%- set field_type = field.type %}
+{%- if field.type == 'Link' or field.link_doctype %}
+{%- set field_type = 'Annotated[str, Link("' + field.link_doctype + '")]' %}
+{%- elif field.type == 'Table' or field.table_doctype %}
+{%- set field_type = 'list[' + field.table_doctype + ']' %}
+{%- endif %}
 {% if has_field_args %}
-    {{ field.name }}: {{ field.type }}{{ ' | None' if not field.required else '' }} = Field(
+    {{ field.name }}: {{ field_type }}{{ ' | None' if not field.required and 'None' not in field_type else '' }} = Field(
 {%- if field.required and (not field.default or field.default == 'None') %}...{% elif field.default and field.default != 'None' %}{{ field.default }}{% else %}None{% endif %}
 {%- if field.description %}, description="{{ field.description }}"{% endif %}
 {%- if field.label %}, label="{{ field.label }}"{% endif %}
@@ -33,16 +42,16 @@ class {{ name }}(BaseDocType):
 {%- if field.validators.min_length %}, min_length={{ field.validators.min_length }}{% endif %}
 {%- if field.validators.max_length %}, max_length={{ field.validators.max_length }}{% endif %}
 {%- if field.validators.pattern %}, pattern=r"{{ field.validators.pattern }}"{% endif %}
-{%- if field.validators.min_value is defined %}, ge={{ field.validators.min_value }}{% endif %}
-{%- if field.validators.max_value is defined %}, le={{ field.validators.max_value }}{% endif %}
-{%- endif %}
-    )
+{%- if field.validators.get('min_value') is not none %}, ge={{ field.validators.min_value }}{% endif %}
+{%- if field.validators.get('max_value') is not none %}, le={{ field.validators.max_value }}{% endif %}
+{%- endif -%}
+)
 {% elif field.required and not field.default %}
-    {{ field.name }}: {{ field.type }}
+    {{ field.name }}: {{ field_type }}
 {% elif field.default %}
-    {{ field.name }}: {{ field.type }} = {{ field.default }}
+    {{ field.name }}: {{ field_type }} = {{ field.default }}
 {% else %}
-    {{ field.name }}: {{ field.type }} | None = None
+    {{ field.name }}: {{ field_type }}{{ ' | None' if 'None' not in field_type else '' }} = None
 {% endif %}
 {% endfor %}
 {% else %}

framework_m_studio/codegen/test_generator.py

@@ -39,9 +39,13 @@ def _get_jinja_env() -> Environment:
 
 
 def _to_snake_case(name: str) -> str:
-    """Convert PascalCase to snake_case."""
+    """Convert PascalCase or 'Spaced Words' to snake_case."""
+    # First, replace spaces and hyphens with underscores
+    name = name.replace(" ", "_").replace("-", "_")
     s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
-    return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+    result = re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+    # Collapse multiple underscores
+    return re.sub("_+", "_", result)
 
 
 def _get_test_value(field_type: str, field_name: str = "") -> str: