quantum-framework 0.9.0__py3-none-any.whl

quantum/runtime/file_upload_service.py

@@ -0,0 +1,326 @@
+"""
+Phase H: File Upload Service
+
+Handles file uploads with validation, storage, and naming strategies.
+"""
+
+import os
+import uuid
+import mimetypes
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+from werkzeug.utils import secure_filename
+from werkzeug.datastructures import FileStorage
+
+
+class FileUploadError(Exception):
+    """Raised when file upload fails"""
+    pass
+
+
+class FileUploadService:
+    """Service for handling file uploads with validation"""
+
+    # File size constants
+    KB = 1024
+    MB = 1024 * KB
+    GB = 1024 * MB
+
+    def __init__(self, root: str = None):
+        """Initialize file upload service.
+
+        `root` confines every path this service touches. Defaults to
+        ./uploads under the current working directory.
+        """
+        self.max_file_size = 10 * self.MB  # Default 10MB
+        self.allowed_extensions = None  # None = allow all
+        self.root = Path(root or 'uploads').resolve()
+
+    def resolve_within_root(self, filepath: str) -> Path:
+        """Resolve `filepath` and refuse anything outside the root.
+
+        q:file's path can come straight from databinding — a form field, a
+        query parameter. delete_file used to do `Path(filepath).unlink()` with
+        no containment at all, so
+
+            <q:file action="delete" file="{nomeArquivo}" />
+
+        with nomeArquivo = "uploads/../banco-importante.db" deleted a file
+        outside the upload directory and reported
+        {'success': True, 'message': 'File deleted successfully'}.
+        Reproduced before fixing.
+
+        Same rule as the component router's _is_within_components: reject the
+        traversal token outright, then resolve and confirm containment.
+        """
+        raw = str(filepath or '')
+        if not raw:
+            raise FileUploadError("empty file path")
+        if '..' in raw.replace('\\', '/').split('/'):
+            raise FileUploadError(
+                f"path {raw!r} escapes the upload directory"
+            )
+        candidate = Path(raw)
+        target = (candidate if candidate.is_absolute()
+                  else self.root / candidate).resolve()
+        if target != self.root and self.root not in target.parents:
+            raise FileUploadError(
+                f"path {raw!r} resolves outside the upload directory "
+                f"({self.root})"
+            )
+        return target
+
+    @staticmethod
+    def parse_size(size_str: str) -> int:
+        """
+        Parse file size string like '5MB', '100KB', '1GB' to bytes
+
+        Args:
+            size_str: Size string (e.g., '5MB', '100KB')
+
+        Returns:
+            Size in bytes
+        """
+        size_str = size_str.strip().upper()
+
+        if size_str.endswith('GB'):
+            return int(float(size_str[:-2]) * FileUploadService.GB)
+        elif size_str.endswith('MB'):
+            return int(float(size_str[:-2]) * FileUploadService.MB)
+        elif size_str.endswith('KB'):
+            return int(float(size_str[:-2]) * FileUploadService.KB)
+        elif size_str.endswith('B'):
+            return int(size_str[:-1])
+        else:
+            # Assume bytes if no unit
+            return int(size_str)
+
+    @staticmethod
+    def get_file_extension(filename: str) -> str:
+        """Get file extension from filename"""
+        return Path(filename).suffix.lower()
+
+    @staticmethod
+    def is_allowed_extension(filename: str, allowed: List[str]) -> bool:
+        """
+        Check if file extension is allowed
+
+        Args:
+            filename: Filename to check
+            allowed: List of allowed extensions (e.g., ['.jpg', '.png', '.pdf'])
+
+        Returns:
+            True if allowed, False otherwise
+        """
+        if not allowed:
+            return True  # No restrictions
+
+        ext = FileUploadService.get_file_extension(filename)
+        return ext in [a.lower() for a in allowed]
+
+    @staticmethod
+    def is_allowed_mimetype(file: FileStorage, allowed_patterns: List[str]) -> bool:
+        """
+        Check if file MIME type matches allowed patterns
+
+        Args:
+            file: FileStorage object
+            allowed_patterns: List of MIME patterns (e.g., ['image/*', 'application/pdf'])
+
+        Returns:
+            True if allowed, False otherwise
+        """
+        if not allowed_patterns:
+            return True  # No restrictions
+
+        file_mimetype = file.content_type or mimetypes.guess_type(file.filename)[0]
+
+        if not file_mimetype:
+            return False
+
+        for pattern in allowed_patterns:
+            if pattern == '*/*':
+                return True
+
+            if '*' in pattern:
+                # Handle wildcards like 'image/*'
+                main_type = pattern.split('/')[0]
+                if file_mimetype.startswith(main_type + '/'):
+                    return True
+            elif file_mimetype == pattern:
+                return True
+
+        return False
+
+    def validate_file(
+        self,
+        file: FileStorage,
+        max_size: Optional[str] = None,
+        allowed_extensions: Optional[List[str]] = None,
+        allowed_mimetypes: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Validate uploaded file
+
+        Args:
+            file: FileStorage object from Flask
+            max_size: Maximum file size (e.g., '5MB', '100KB')
+            allowed_extensions: List of allowed extensions
+            allowed_mimetypes: List of allowed MIME types
+
+        Returns:
+            Dict with validation result
+
+        Raises:
+            FileUploadError: If validation fails
+        """
+        if not file or not file.filename:
+            raise FileUploadError("No file provided")
+
+        # Check file size
+        file.seek(0, os.SEEK_END)
+        file_size = file.tell()
+        file.seek(0)  # Reset to beginning
+
+        if max_size:
+            max_bytes = self.parse_size(max_size)
+            if file_size > max_bytes:
+                raise FileUploadError(
+                    f"File size ({file_size / self.MB:.2f}MB) exceeds maximum ({max_size})"
+                )
+
+        # Check extension
+        if allowed_extensions and not self.is_allowed_extension(file.filename, allowed_extensions):
+            raise FileUploadError(
+                f"File type not allowed. Allowed: {', '.join(allowed_extensions)}"
+            )
+
+        # Check MIME type
+        if allowed_mimetypes and not self.is_allowed_mimetype(file, allowed_mimetypes):
+            raise FileUploadError(
+                f"File MIME type not allowed. Allowed: {', '.join(allowed_mimetypes)}"
+            )
+
+        return {
+            'valid': True,
+            'filename': file.filename,
+            'size': file_size,
+            'mimetype': file.content_type
+        }
+
+    def upload_file(
+        self,
+        file: FileStorage,
+        destination: str,
+        name_conflict: str = "error",
+        custom_filename: Optional[str] = None,
+        max_size: Optional[str] = None,
+        allowed_extensions: Optional[List[str]] = None,
+        allowed_mimetypes: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Upload file to destination
+
+        Args:
+            file: FileStorage object from Flask
+            destination: Destination directory
+            name_conflict: Strategy for naming conflicts (error, overwrite, skip, makeUnique)
+            custom_filename: Optional custom filename
+            max_size: Maximum file size
+            allowed_extensions: Allowed file extensions
+            allowed_mimetypes: Allowed MIME types
+
+        Returns:
+            Dict with upload result
+
+        Raises:
+            FileUploadError: If upload fails
+        """
+        # Validate file
+        validation = self.validate_file(file, max_size, allowed_extensions, allowed_mimetypes)
+
+        # Secure the filename
+        original_filename = custom_filename or file.filename
+        secure_name = secure_filename(original_filename)
+
+        # Create destination directory if it doesn't exist.
+        #
+        # `destination` is databound, so it can carry a form value. It used to
+        # be Path(destination).mkdir(parents=True) with no containment, which
+        # let an upload create and write directories anywhere on disk. Every
+        # destination= in this repo already lives under ./uploads/, so
+        # confining to the root breaks no real usage.
+        dest_path = self.resolve_within_root(destination)
+        dest_path.mkdir(parents=True, exist_ok=True)
+
+        # Handle name conflicts
+        final_filename = secure_name
+        file_path = dest_path / final_filename
+
+        if file_path.exists():
+            if name_conflict == "error":
+                raise FileUploadError(f"File '{final_filename}' already exists")
+            elif name_conflict == "skip":
+                return {
+                    'success': False,
+                    'skipped': True,
+                    'filename': final_filename,
+                    'message': 'File already exists and was skipped'
+                }
+            elif name_conflict == "makeUnique":
+                # Generate unique filename
+                name_part = file_path.stem
+                ext_part = file_path.suffix
+                unique_id = uuid.uuid4().hex[:8]
+                final_filename = f"{name_part}_{unique_id}{ext_part}"
+                file_path = dest_path / final_filename
+            # elif name_conflict == "overwrite": just use the same filename
+
+        # Save file
+        try:
+            file.save(str(file_path))
+        except Exception as e:
+            raise FileUploadError(f"Failed to save file: {e}")
+
+        return {
+            'success': True,
+            'filename': final_filename,
+            'filepath': str(file_path),
+            'original_filename': original_filename,
+            'size': validation['size'],
+            'mimetype': validation['mimetype'],
+            'url': f"/uploads/{final_filename}"  # Relative URL
+        }
+
+    def delete_file(self, filepath: str) -> Dict[str, Any]:
+        """
+        Delete a file
+
+        Args:
+            filepath: Path to file to delete
+
+        Returns:
+            Dict with deletion result
+        """
+        try:
+            file_path = self.resolve_within_root(filepath)
+        except FileUploadError as e:
+            return {'success': False, 'error': str(e)}
+
+        if not file_path.exists():
+            return {
+                'success': False,
+                'error': 'File not found'
+            }
+
+        try:
+            file_path.unlink()
+            return {
+                'success': True,
+                'message': 'File deleted successfully'
+            }
+        except Exception as e:
+            return {
+                'success': False,
+                'error': str(e)
+            }

quantum/runtime/function_registry.py

@@ -0,0 +1,118 @@
+"""
+Quantum Function Registry - Manages function definitions across scopes
+"""
+
+from typing import Dict, Optional, List
+import sys
+from pathlib import Path
+
+# Fix imports
+
+from quantum.core.ast_nodes import ComponentNode
+from quantum.core.features.functions.src.ast_node import FunctionNode
+
+
+class FunctionRegistry:
+    """Global registry for all functions across scopes"""
+
+    def __init__(self):
+        # Escopo por container
+        self.components: Dict[str, Dict[str, FunctionNode]] = {}  # component_name -> {func_name: func}
+
+        # Index global (para funções scope="global")
+        self.global_functions: Dict[str, FunctionNode] = {}
+
+        # Imported modules (para q:import)
+        self.imported_modules: List[str] = []
+
+    def register_component(self, component: ComponentNode):
+        """Register all functions from a component"""
+        component_name = getattr(component, 'name', None) or getattr(component, 'id', 'unknown')
+        if component_name not in self.components:
+            self.components[component_name] = {}
+
+        for func in getattr(component, 'functions', []):
+            self.register_function(func, component)
+
+    def register_function(self, func: FunctionNode, container: ComponentNode):
+        """Register function in appropriate scope"""
+        container_name = getattr(container, 'name', None) or getattr(container, 'id', 'unknown')
+        if container_name not in self.components:
+            self.components[container_name] = {}
+
+        self.components[container.name][func.name] = func
+
+        # Functions with scope="global" go to global index
+        if func.scope == "global":
+            qualified_name = f"{container.name}.{func.name}"
+            self.global_functions[qualified_name] = func
+
+    def resolve_function(self, name: str, current_component: Optional[ComponentNode] = None) -> Optional[FunctionNode]:
+        """
+        Resolve function name to FunctionNode - respects scope rules
+
+        Resolution order:
+        1. Local component functions
+        2. Global functions (qualified name: Component.function)
+        3. Imported module functions
+        """
+
+        # 1. Check local component first
+        if current_component and current_component.name in self.components:
+            component_funcs = self.components[current_component.name]
+            if name in component_funcs:
+                return component_funcs[name]
+
+        # 2. Check global functions (qualified name: Component.function)
+        if name in self.global_functions:
+            return self.global_functions[name]
+
+        # 3. Check if it's a qualified call (Component.function)
+        if '.' in name:
+            component_name, func_name = name.split('.', 1)
+            if component_name in self.components:
+                return self.components[component_name].get(func_name)
+
+        return None
+
+    def get_rest_endpoints(self) -> List[FunctionNode]:
+        """Get all functions that are REST endpoints"""
+        endpoints = []
+
+        # Functions in components with endpoint attribute
+        for component_funcs in self.components.values():
+            for func in component_funcs.values():
+                if func.is_rest_enabled() and not func.is_private():
+                    endpoints.append(func)
+
+        return endpoints
+
+    def get_event_handlers(self, component: ComponentNode) -> List:
+        """Get all event handlers for a component"""
+        return component.event_handlers
+
+    def import_module(self, module_name: str):
+        """Mark module as imported (for q:import)"""
+        if module_name not in self.imported_modules:
+            self.imported_modules.append(module_name)
+
+    def is_module_imported(self, module_name: str) -> bool:
+        """Check if module is imported"""
+        return module_name in self.imported_modules
+
+    def list_functions(self, component_name: Optional[str] = None) -> List[FunctionNode]:
+        """List all functions (optionally filtered by component)"""
+        if component_name:
+            return list(self.components.get(component_name, {}).values())
+
+        # List all functions
+        all_functions = []
+        for component_funcs in self.components.values():
+            all_functions.extend(component_funcs.values())
+        return all_functions
+
+    def clear(self):
+        """Clear all registered functions"""
+        self.components.clear()
+        self.global_functions.clear()
+        self.imported_modules.clear()

quantum/runtime/game_builder.py

@@ -0,0 +1,166 @@
+"""
+Game Engine 2D - Builder/Orchestrator
+
+Orchestrates the compilation pipeline:
+  ApplicationNode (type="game") → extract scenes/behaviors/prefabs → CodeGenerator → output
+
+Supports two backends:
+  - pixi (default): PIXI.js + Matter.js → standalone HTML file
+  - godot: Godot 4 → project directory with .tscn + .gd files
+
+Usage:
+    builder = GameBuilder()                    # Default: pixi backend
+    builder = GameBuilder(engine='godot')      # Godot 4 backend
+    builder.build_to_file(app_node)
+"""
+
+import os
+from pathlib import Path
+from typing import Optional
+
+from quantum.core.ast_nodes import ApplicationNode
+from quantum.core.features.game_engine_2d.src.ast_nodes import (
+    SceneNode, BehaviorNode, PrefabNode, EnemyNode,
+)
+
+
+class GameBuildError(Exception):
+    """Error during game build."""
+    pass
+
+
+class GameBuilder:
+    """Builds a game from a Quantum game ApplicationNode.
+
+    Args:
+        engine: Backend engine to use. 'pixi' (default) or 'godot'.
+    """
+
+    VALID_ENGINES = ('pixi', 'godot')
+
+    def __init__(self, engine: str = 'pixi', source_dir: str = None):
+        if engine not in self.VALID_ENGINES:
+            raise GameBuildError(
+                f"Unknown engine '{engine}'. Valid engines: {', '.join(self.VALID_ENGINES)}"
+            )
+        self.engine = engine
+        self.source_dir = source_dir
+
+    def build(self, app: ApplicationNode, output_dir: Optional[str] = None) -> str:
+        """Build game from an ApplicationNode with type='game'.
+
+        For pixi engine: returns HTML string.
+        For godot engine: returns output directory path.
+        """
+        scenes = getattr(app, 'scenes', [])
+        behaviors = getattr(app, 'behaviors', [])
+        prefabs = getattr(app, 'prefabs', [])
+        enemies = getattr(app, 'enemies', [])
+
+        if not scenes:
+            raise GameBuildError("No scenes found in game application")
+
+        valid_behaviors = [b for b in behaviors if isinstance(b, BehaviorNode)]
+        valid_prefabs = [p for p in prefabs if isinstance(p, PrefabNode)]
+        valid_enemies = [e for e in enemies if isinstance(e, EnemyNode)]
+
+        if self.engine == 'godot':
+            return self._build_godot(app, scenes, valid_behaviors, valid_prefabs, output_dir, valid_enemies)
+        else:
+            return self._build_pixi(app, scenes, valid_behaviors, valid_prefabs)
+
+    def _build_pixi(self, app: ApplicationNode, scenes, behaviors, prefabs) -> str:
+        """Build with PIXI.js + Matter.js backend (returns HTML string)."""
+        from quantum.runtime.game_code_generator import GameCodeGenerator
+
+        if len(scenes) > 1:
+            initial_name = scenes[0].name
+            for scene in scenes:
+                if isinstance(scene, SceneNode) and scene.active:
+                    initial_name = scene.name
+                    break
+
+            generator = GameCodeGenerator()
+            return generator.generate_multi(
+                scenes=[s for s in scenes if isinstance(s, SceneNode)],
+                initial=initial_name,
+                behaviors=behaviors,
+                prefabs=prefabs,
+                title=app.app_id,
+            )
+
+        active_scene = scenes[0]
+        for scene in scenes:
+            if isinstance(scene, SceneNode) and scene.active:
+                active_scene = scene
+                break
+
+        generator = GameCodeGenerator()
+        return generator.generate(
+            scene=active_scene,
+            behaviors=behaviors,
+            prefabs=prefabs,
+            title=app.app_id,
+        )
+
+    def _build_godot(self, app: ApplicationNode, scenes, behaviors, prefabs,
+                     output_dir: Optional[str] = None,
+                     enemies: list = None) -> str:
+        """Build with Godot 4 backend (returns output directory path)."""
+        from quantum.runtime.godot_code_generator import GodotCodeGenerator
+
+        if output_dir is None:
+            output_dir = f"projects/{app.app_id}/godot"
+
+        generator = GodotCodeGenerator(source_dir=self.source_dir)
+        persistent = getattr(app, 'persistent', [])
+
+        if len(scenes) > 1:
+            initial_name = scenes[0].name
+            for scene in scenes:
+                if isinstance(scene, SceneNode) and (getattr(scene, 'initial', False) or scene.active):
+                    initial_name = scene.name
+                    break
+
+            return generator.generate_multi(
+                scenes=[s for s in scenes if isinstance(s, SceneNode)],
+                initial=initial_name,
+                behaviors=behaviors,
+                prefabs=prefabs,
+                enemies=enemies or [],
+                persistent=persistent,
+                output_dir=output_dir,
+                project_name=app.app_id,
+            )
+
+        active_scene = scenes[0]
+        for scene in scenes:
+            if isinstance(scene, SceneNode) and scene.active:
+                active_scene = scene
+                break
+
+        return generator.generate(
+            scene=active_scene,
+            behaviors=behaviors,
+            prefabs=prefabs,
+            enemies=enemies or [],
+            output_dir=output_dir,
+            project_name=app.app_id,
+        )
+
+    def build_to_file(self, app: ApplicationNode, output_path: Optional[str] = None) -> str:
+        """Build and write output. Returns the output file/directory path."""
+        if self.engine == 'godot':
+            return self.build(app, output_dir=output_path)
+
+        # PIXI: write HTML file
+        html = self.build(app)
+
+        if output_path is None:
+            output_path = f"{app.app_id}.html"
+
+        path = Path(output_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(html, encoding='utf-8')
+
+        return str(path.resolve())