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

framework_m_studio/cli/new.py

@@ -0,0 +1,754 @@
+"""Scaffolding CLI Commands - Create new apps and doctypes.
+
+This module provides CLI commands for scaffolding new Framework M
+components using templates.
+
+Usage:
+    m new:doctype Invoice              # Create new doctype
+    m new:doctype Invoice --app myapp  # Explicit app target
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+
+# =============================================================================
+# Template Content (Embedded for simplicity)
+# =============================================================================
+
+DOCTYPE_TEMPLATE = '''\
+"""{{ class_name }} DocType.
+
+Auto-generated by `m new:doctype {{ name }}`.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from framework_m import DocType, Field
+
+
+class {{ class_name }}(DocType):
+    """{{ class_name }} DocType definition.
+
+    Attributes:
+        name: Unique identifier for this {{ name }}.
+    """
+
+    __doctype_name__: ClassVar[str] = "{{ class_name }}"
+
+    name: str = Field(description="Unique identifier")
+
+    class Meta:
+        """DocType metadata."""
+
+        naming_rule: ClassVar[str] = "autoincrement"
+        is_submittable: ClassVar[bool] = False
+        api_resource: ClassVar[bool] = True  # Expose via REST API
+        show_in_desk: ClassVar[bool] = True  # Show in Desk UI
+'''
+
+CONTROLLER_TEMPLATE = '''\
+"""{{ class_name }} Controller.
+
+Auto-generated by `m new:doctype {{ name }}`.
+"""
+
+from __future__ import annotations
+
+from framework_m import Controller
+from .doctype import {{ class_name }}
+
+
+class {{ class_name }}Controller(Controller[{{ class_name }}]):
+    """Controller for {{ class_name }} DocType.
+
+    Implement custom business logic here.
+    """
+
+    doctype = {{ class_name }}
+
+    async def before_save(self, doc: {{ class_name }}) -> None:
+        """Called before saving a document."""
+        pass
+
+    async def after_save(self, doc: {{ class_name }}) -> None:
+        """Called after saving a document."""
+        pass
+'''
+
+TEST_TEMPLATE = '''\
+"""Tests for {{ class_name }} DocType.
+
+Auto-generated by `m new:doctype {{ name }}`.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from .doctype import {{ class_name }}
+
+
+class Test{{ class_name }}:
+    """Tests for {{ class_name }}."""
+
+    def test_create_{{ snake_name }}(self) -> None:
+        """{{ class_name }} should be creatable."""
+        doc = {{ class_name }}(name="test-001")
+        assert doc.name == "test-001"
+
+    def test_{{ snake_name }}_doctype_name(self) -> None:
+        """{{ class_name }} should have correct doctype name."""
+        assert {{ class_name }}.__doctype_name__ == "{{ class_name }}"
+'''
+
+INIT_TEMPLATE = '''\
+"""{{ class_name }} DocType package.
+
+Auto-generated by `m new:doctype {{ name }}`.
+"""
+
+from .controller import {{ class_name }}Controller
+from .doctype import {{ class_name }}
+
+__all__ = ["{{ class_name }}", "{{ class_name }}Controller"]
+'''
+
+
+# =============================================================================
+# Name Utilities
+# =============================================================================
+
+
+def to_pascal_case(name: str) -> str:
+    """Convert name to PascalCase.
+
+    Examples:
+        >>> to_pascal_case("sales_order")
+        'SalesOrder'
+        >>> to_pascal_case("user")
+        'User'
+        >>> to_pascal_case("ItemSupplier")
+        'ItemSupplier'
+        >>> to_pascal_case("Sales Order")
+        'SalesOrder'
+        >>> to_pascal_case("my-app")
+        'MyApp'
+    """
+    # Normalize separators: replace spaces and hyphens with underscores
+    normalized = name.replace(" ", "_").replace("-", "_")
+
+    # Handle snake_case - capitalize first letter of each part, preserve rest
+    if "_" in normalized:
+        return "".join(
+            (word[0].upper() + word[1:]) if word else ""
+            for word in normalized.split("_")
+        )
+
+    # Already PascalCase or single word - just ensure first letter is uppercase
+    return name[0].upper() + name[1:] if name else name
+
+
+def to_snake_case(name: str) -> str:
+    """Convert name to snake_case.
+
+    Examples:
+        >>> to_snake_case("SalesOrder")
+        'sales_order'
+        >>> to_snake_case("user")
+        'user'
+        >>> to_snake_case("my-app")
+        'my_app'
+        >>> to_snake_case("Sales Order")
+        'sales_order'
+    """
+    # First, replace spaces and hyphens with underscores
+    name = name.replace(" ", "_").replace("-", "_")
+    # Insert underscore before uppercase letters
+    s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
+    result = re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+    # Collapse multiple underscores
+    return re.sub("_+", "_", result)
+
+
+def normalize_app_name(name: str) -> str:
+    """Normalize app name to Python package format.
+
+    Examples:
+        >>> normalize_app_name("my-app")
+        'my_app'
+    """
+    return name.replace("-", "_")
+
+
+# =============================================================================
+# App Detection Strategy
+# =============================================================================
+
+# Entry point group for discovering installed apps
+APPS_ENTRY_POINT_GROUP = "framework_m.apps"
+
+
+def detect_app_from_cwd() -> str | None:
+    """Detect app name from pyproject.toml in cwd or parents.
+
+    Returns:
+        App name if found, None otherwise.
+    """
+    result = find_app_root()
+    return result[0] if result else None
+
+
+def find_app_root() -> tuple[str, Path] | None:
+    """Find app name and root directory from pyproject.toml.
+
+    Searches current directory and parents for pyproject.toml.
+
+    Returns:
+        Tuple of (app_name, root_path) if found, None otherwise.
+    """
+    for path in [Path.cwd(), *Path.cwd().parents]:
+        pyproject = path / "pyproject.toml"
+        if pyproject.exists():
+            app_name = parse_project_name(pyproject)
+            if app_name:
+                return (app_name, path)
+    return None
+
+
+def parse_project_name(pyproject_path: Path) -> str | None:
+    """Parse project name from pyproject.toml.
+
+    Args:
+        pyproject_path: Path to pyproject.toml
+
+    Returns:
+        Normalized project name or None
+    """
+    try:
+        content = pyproject_path.read_text()
+        # Simple regex to find name = "..."
+        match = re.search(r'name\s*=\s*["\']([^"\']+)["\']', content)
+        if match:
+            return normalize_app_name(match.group(1))
+    except Exception:
+        pass
+    return None
+
+
+def is_interactive() -> bool:
+    """Check if running in interactive terminal."""
+    return sys.stdin.isatty()
+
+
+def list_installed_apps() -> list[str]:
+    """List installed apps from entry points.
+
+    Scans the framework_m.apps entry point group for registered apps.
+
+    Returns:
+        List of app names
+    """
+    from importlib.metadata import entry_points
+
+    eps = entry_points(group=APPS_ENTRY_POINT_GROUP)
+    return [ep.name for ep in eps]
+
+
+def prompt_select(prompt: str, options: list[str]) -> str | None:
+    """Prompt user to select from a list of options.
+
+    Args:
+        prompt: The prompt message
+        options: List of options to choose from
+
+    Returns:
+        Selected option or None if cancelled
+    """
+    if not options:
+        return None
+
+    print(f"\n{prompt}")
+    for i, opt in enumerate(options, 1):
+        print(f"  {i}. {opt}")
+
+    try:
+        choice = input("\nEnter number (or 'q' to quit): ").strip()
+        if choice.lower() == "q":
+            return None
+
+        idx = int(choice) - 1
+        if 0 <= idx < len(options):
+            return options[idx]
+    except (ValueError, EOFError, KeyboardInterrupt):
+        pass
+
+    return None
+
+
+def detect_app(explicit_app: str | None = None) -> str | None:
+    """Detect app using the detection strategy.
+
+    Strategy:
+    1. Explicit --app parameter wins (unless it's '.' which means current dir)
+    2. Auto-detect from pyproject.toml in CWD or parents
+    3. None if not found (caller handles interactive/error)
+
+    Args:
+        explicit_app: Explicitly provided app name, or '.' for current dir
+
+    Returns:
+        App name or None
+    """
+    # Treat '.' as "use current directory's app"
+    if explicit_app and explicit_app != ".":
+        return normalize_app_name(explicit_app)
+
+    return detect_app_from_cwd()
+
+
+def require_app(explicit_app: str | None = None) -> str:
+    """Require an app, prompting if necessary.
+
+    Full implementation of App Detection Strategy:
+    1. Explicit --app parameter wins
+    2. Auto-detect from pyproject.toml
+    3. Interactive prompt if TTY
+    4. Fail with error if non-interactive
+
+    Args:
+        explicit_app: Explicitly provided app name
+
+    Returns:
+        App name (guaranteed)
+
+    Raises:
+        SystemExit: If app cannot be determined
+    """
+    # 1. Explicit --app wins
+    if explicit_app:
+        return normalize_app_name(explicit_app)
+
+    # 2. Auto-detect from CWD
+    detected = detect_app_from_cwd()
+    if detected:
+        return detected
+
+    # 3. Interactive prompt if TTY
+    if is_interactive():
+        apps = list_installed_apps()
+        if apps:
+            print("Could not detect app from current directory.")
+            selected = prompt_select("Which app?", apps)
+            if selected:
+                return selected
+            print("\nNo app selected.")
+        else:
+            print("Could not detect app from current directory.")
+            print("No apps registered in entry points.")
+
+    # 4. Fail with clear error
+    print(
+        "Error: Cannot detect app. Use --app <name>.",
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+
+
+# =============================================================================
+# Scaffold Functions
+# =============================================================================
+
+
+def render_template(template: str, context: dict[str, str]) -> str:
+    """Simple template rendering (no Jinja2 dependency).
+
+    Args:
+        template: Template string with {{ var }} placeholders
+        context: Dict of variable names to values
+
+    Returns:
+        Rendered template
+    """
+    result = template
+    for key, value in context.items():
+        result = result.replace("{{ " + key + " }}", value)
+    return result
+
+
+def scaffold_doctype(
+    doctype_name: str,
+    output_dir: Path,
+    test_output_dir: Path | None = None,
+) -> dict[str, Path]:
+    """Create doctype scaffold files.
+
+    Args:
+        doctype_name: Name of the doctype (e.g., "Invoice" or "sales_order")
+        output_dir: Directory to create files in
+        test_output_dir: Optional separate directory for test files (keeps them out of src/)
+
+    Returns:
+        Dict mapping file type to created path
+    """
+    class_name = to_pascal_case(doctype_name)
+    snake_name = to_snake_case(doctype_name)
+
+    context = {
+        "name": doctype_name,
+        "class_name": class_name,
+        "snake_name": snake_name,
+    }
+
+    # Ensure output directory exists
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    created_files: dict[str, Path] = {}
+
+    # Create doctype files (go in src/)
+    doctype_files = [
+        ("__init__.py", INIT_TEMPLATE),
+        ("doctype.py", DOCTYPE_TEMPLATE),
+        ("controller.py", CONTROLLER_TEMPLATE),
+    ]
+
+    for filename, template in doctype_files:
+        filepath = output_dir / filename
+        content = render_template(template, context)
+        filepath.write_text(content)
+        created_files[filename] = filepath
+
+    # Create test file (goes in tests/ directory if specified)
+    test_dir = test_output_dir if test_output_dir else output_dir
+    test_dir.mkdir(parents=True, exist_ok=True)
+    test_filename = f"test_{snake_name}.py"
+    test_filepath = test_dir / test_filename
+    test_content = render_template(TEST_TEMPLATE, context)
+    test_filepath.write_text(test_content)
+    created_files[test_filename] = test_filepath
+
+    return created_files
+
+
+# =============================================================================
+# CLI Commands
+# =============================================================================
+
+
+def new_doctype_command(
+    name: Annotated[str, cyclopts.Parameter(help="Name of the new DocType")],
+    app: Annotated[
+        str | None,
+        cyclopts.Parameter(name="--app", help="Target app name"),
+    ] = None,
+    output: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            name="--output", help="Output directory (default: doctypes/<name>)"
+        ),
+    ] = None,
+) -> None:
+    """Create a new DocType with scaffolded files.
+
+    Creates a new DocType package with:
+    - doctype.py (schema definition)
+    - controller.py (business logic)
+    - test_*.py (pytest tests)
+
+    Examples:
+        m new:doctype Invoice
+        m new:doctype Invoice --app myapp
+        m new:doctype SalesOrder --output ./my_doctypes/sales_order
+    """
+    # Detect app if not provided
+    detected_app = detect_app(app)
+
+    # Find app root directory (where pyproject.toml is)
+    app_info = find_app_root()
+    app_root = app_info[1] if app_info else Path.cwd()
+
+    if detected_app is None and output is None:
+        if is_interactive():
+            print("Warning: Could not detect app. Creating in current directory.")
+        else:
+            print(
+                "Error: Cannot detect app. Use --app <name> or --output <path>.",
+                file=sys.stderr,
+            )
+            raise SystemExit(1)
+
+    # Determine output directory
+    snake_name = to_snake_case(name)
+    test_output_dir: Path | None = None
+
+    if output:
+        output_dir = output
+        # If explicit output, put tests in parallel tests/ structure
+        if "src" in output.parts:
+            parts = list(output.parts)
+            src_idx = parts.index("src")
+            parts[src_idx] = "tests"
+            test_output_dir = Path(*parts)
+    elif detected_app:
+        # Use app_root (not CWD) to construct paths
+        # This ensures correct paths even when running from subdirectory
+        app_namespace_doctypes = app_root / "src" / detected_app / "doctypes"
+        src_doctypes = app_root / "src" / "doctypes"
+
+        if app_namespace_doctypes.exists():
+            # Namespaced structure: src/<app>/doctypes/<doctype>/
+            output_dir = app_namespace_doctypes / snake_name
+            test_output_dir = app_root / "tests" / "doctypes" / snake_name
+        elif src_doctypes.exists():
+            # Legacy flat structure: src/doctypes/<doctype>/
+            output_dir = src_doctypes / snake_name
+            test_output_dir = app_root / "tests" / "doctypes" / snake_name
+        else:
+            # Default: create in namespaced location
+            output_dir = app_namespace_doctypes / snake_name
+            test_output_dir = app_root / "tests" / "doctypes" / snake_name
+    else:
+        output_dir = Path.cwd() / snake_name
+        test_output_dir = Path.cwd() / "tests" / snake_name
+
+    # Check if directory already exists
+    if output_dir.exists():
+        print(f"Error: Directory already exists: {output_dir}", file=sys.stderr)
+        raise SystemExit(1)
+
+    # Scaffold
+    print(f"Creating DocType: {to_pascal_case(name)}")
+    print(f"  Location: {output_dir}")
+    if test_output_dir:
+        print(f"  Tests:    {test_output_dir}")
+
+    created = scaffold_doctype(name, output_dir, test_output_dir)
+
+    print()
+    print("✓ Created files:")
+    for _filename, filepath in created.items():
+        print(f"  - {filepath}")
+
+
+# =============================================================================
+# New App Command
+# =============================================================================
+
+# App template files (embedded for simplicity)
+APP_PYPROJECT_TEMPLATE = """\
+[project]
+name = "{{ app_name }}"
+version = "0.1.0"
+description = "A Framework M application"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "framework-m>=0.1.0",
+]
+
+[project.entry-points."framework_m.apps"]
+{{ app_name }} = "{{ app_name }}:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ app_name }}"]
+"""
+
+APP_README_TEMPLATE = """\
+# {{ class_name }}
+
+A Framework M application.
+
+## Getting Started
+
+```bash
+cd {{ app_name }}
+uv sync
+m dev
+```
+
+## Structure
+
+```
+{{ app_name }}/
+├── src/
+│   └── {{ app_name }}/       # App namespace
+│       ├── __init__.py       # App config
+│       ├── doctypes/         # Your DocTypes go here
+│       ├── services/         # Business logic (optional)
+│       └── utils/            # Utilities (optional)
+├── tests/                    # Test files
+├── pyproject.toml
+└── README.md
+```
+
+## Adding DocTypes
+
+```bash
+m new:doctype Invoice
+```
+
+This creates:
+- `src/{{ app_name }}/doctypes/invoice/` - DocType files
+- `tests/doctypes/invoice/` - Test files
+"""
+
+
+def scaffold_app(
+    app_name: str,
+    output_dir: Path,
+) -> dict[str, Path]:
+    """Create app scaffold files.
+
+    Args:
+        app_name: Name of the app (e.g., "myapp")
+        output_dir: Directory to create app in
+
+    Returns:
+        Dict mapping file type to created path
+    """
+    class_name = to_pascal_case(app_name)
+    snake_name = to_snake_case(app_name)
+
+    context = {
+        "app_name": snake_name,
+        "class_name": class_name,
+    }
+
+    # Create directory structure
+    app_dir = output_dir / snake_name
+    app_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create namespaced package: src/<app_name>/
+    namespace_dir = app_dir / "src" / snake_name
+    namespace_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create doctypes subdirectory
+    doctypes_dir = namespace_dir / "doctypes"
+    doctypes_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create tests directory
+    tests_dir = app_dir / "tests"
+    tests_dir.mkdir(parents=True, exist_ok=True)
+
+    created_files: dict[str, Path] = {}
+
+    # Create <app_name>/__init__.py with app configuration
+    app_init_content = f'''"""{class_name} App.
+
+A Framework M application with namespaced package structure.
+"""
+
+# App configuration - discovered via entry points
+app = {{
+    "name": "{snake_name}",
+    "title": "{class_name}",
+    "description": "A Framework M application",
+}}
+'''
+    app_init_path = namespace_dir / "__init__.py"
+    app_init_path.write_text(app_init_content)
+    created_files[f"src/{snake_name}/__init__.py"] = app_init_path
+
+    # Create <app_name>/doctypes/__init__.py
+    doctypes_init_content = f'''"""{class_name} DocTypes Package."""
+
+# DocTypes are auto-discovered from this package
+'''
+    doctypes_init_path = doctypes_dir / "__init__.py"
+    doctypes_init_path.write_text(doctypes_init_content)
+    created_files[f"src/{snake_name}/doctypes/__init__.py"] = doctypes_init_path
+
+    # Create tests/__init__.py
+    tests_init_path = tests_dir / "__init__.py"
+    tests_init_path.write_text('"""Tests for the app."""\n')
+    created_files["tests/__init__.py"] = tests_init_path
+
+    # Create pyproject.toml
+    pyproject_content = render_template(APP_PYPROJECT_TEMPLATE, context)
+    pyproject_path = app_dir / "pyproject.toml"
+    pyproject_path.write_text(pyproject_content)
+    created_files["pyproject.toml"] = pyproject_path
+
+    # Create README.md
+    readme_content = render_template(APP_README_TEMPLATE, context)
+    readme_path = app_dir / "README.md"
+    readme_path.write_text(readme_content)
+    created_files["README.md"] = readme_path
+
+    return created_files
+
+
+def new_app_command(
+    name: Annotated[str, cyclopts.Parameter(help="Name of the new app")],
+    output_dir: Annotated[
+        Path,
+        cyclopts.Parameter(
+            name="--output-dir", help="Parent directory for the new app"
+        ),
+    ] = Path(),
+) -> None:
+    """Create a new Framework M app.
+
+    Creates a minimal app structure with:
+    - pyproject.toml (with Framework M dependency)
+    - README.md
+    - src/<app>/doctypes/ (namespaced structure for DocTypes)
+
+    Examples:
+        m new:app myapp
+        m new:app myapp --output-dir ./apps
+    """
+    snake_name = to_snake_case(name)
+    app_path = output_dir / snake_name
+
+    # Check if directory already exists
+    if app_path.exists():
+        print(f"Error: Directory already exists: {app_path}", file=sys.stderr)
+        raise SystemExit(1)
+
+    print(f"Creating new app: {name}")
+    print(f"  Location: {app_path}")
+    print()
+
+    created = scaffold_app(name, output_dir)
+
+    print("✓ Created files:")
+    for filepath in created.values():
+        print(f"  - {filepath}")
+
+    print()
+    print("✓ Created directory structure:")
+    print(f"  - {app_path}/src/{snake_name}/doctypes/")
+    print(f"  - {app_path}/tests/")
+    print()
+    print("Next steps:")
+    print(f"  cd {snake_name}")
+    print("  m dev")
+
+
+__all__ = [
+    "APPS_ENTRY_POINT_GROUP",
+    "detect_app",
+    "detect_app_from_cwd",
+    "is_interactive",
+    "list_installed_apps",
+    "new_app_command",
+    "new_doctype_command",
+    "prompt_select",
+    "require_app",
+    "scaffold_app",
+    "scaffold_doctype",
+    "to_pascal_case",
+    "to_snake_case",
+]