quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/dev_panel.py

@@ -0,0 +1,178 @@
+"""The /_dev panel (M12, DEV-1): what the last requests did, while developing.
+
+With `server.debug: true`, the server records each request — the component,
+the action it ran, the queries (SQL, parameters, time, rows), the variables of
+each scope, the redirect and the flash — and `/_dev` shows the last ones. With
+`debug: false` nothing is recorded and `/_dev` does not exist.
+
+Recording goes through a context variable, so a query executed deep in the
+runtime finds the request it belongs to without anything being passed down,
+and two requests in two threads never mix.
+"""
+
+import contextvars
+import html
+import threading
+import time
+from collections import deque
+from typing import Any, Dict, List, Optional
+
+_ATUAL: contextvars.ContextVar = contextvars.ContextVar('quantum_dev_request', default=None)
+
+# A value longer than this is cut in the panel (a query of 10k rows, a blob).
+_MAX_TEXTO = 300
+
+
+def _curto(valor: Any) -> str:
+    texto = repr(valor) if not isinstance(valor, str) else valor
+    return texto if len(texto) <= _MAX_TEXTO else texto[:_MAX_TEXTO] + f'… ({len(texto)} chars)'
+
+
+def _escopo(variaveis: Dict[str, Any]) -> Dict[str, str]:
+    return {nome: _curto(valor) for nome, valor in sorted((variaveis or {}).items())
+            if not str(nome).startswith('_')}
+
+
+# -- what the runtime reports ------------------------------------------------
+
+def note(**campos) -> None:
+    """Add facts to the request being recorded (no-op when nothing records)."""
+    registro = _ATUAL.get()
+    if registro is not None:
+        registro.update(campos)
+
+
+def note_query(datasource: str, sql: str, params: Optional[Dict[str, Any]], ms: float,
+               rows: Optional[int], error: Optional[str] = None) -> None:
+    registro = _ATUAL.get()
+    if registro is not None:
+        registro['queries'].append({
+            'datasource': datasource, 'sql': ' '.join(sql.split()),
+            'params': {k: _curto(v) for k, v in (params or {}).items()},
+            'ms': round(ms, 2), 'rows': rows, 'error': error,
+        })
+
+
+def note_scopes(execution_context, label: str = 'page') -> None:
+    """The variables the page — or the action (`label='action'`) — ended with,
+    and the session and application scopes as they were then."""
+    registro = _ATUAL.get()
+    if registro is None or execution_context is None:
+        return
+    proprias = dict(getattr(execution_context, 'component_vars', {}) or {})
+    proprias.update(getattr(execution_context, 'local_vars', {}) or {})
+    escopos = registro['scopes'] or {}
+    escopos[label] = _escopo({k: v for k, v in proprias.items() if '.' not in str(k)})
+    escopos['session'] = _escopo(getattr(execution_context, 'session_vars', {}))
+    escopos['application'] = _escopo(getattr(execution_context, 'application_vars', {}))
+    # action, then page, then the scopes that outlive them
+    ordem = ['action', 'page', 'session', 'application']
+    registro['scopes'] = {k: escopos[k] for k in ordem if k in escopos}
+
+
+# -- the recorder ------------------------------------------------------------
+
+class DevPanel:
+    """The last requests of this server process, newest first."""
+
+    def __init__(self, keep: int = 30):
+        self.requests: deque = deque(maxlen=keep)
+        self._numero = 0
+        self._trava = threading.Lock()
+
+    def start(self, method: str, path: str):
+        with self._trava:
+            self._numero += 1
+            numero = self._numero
+        registro = {'n': numero, 'method': method, 'path': path, 'component': None,
+                    'action': None, 'queries': [], 'scopes': None, 'status': None,
+                    'redirect': None, 'flash': None, 'error': None, 't0': time.perf_counter()}
+        return _ATUAL.set(registro)
+
+    def finish(self, token, status: int, location: Optional[str], flash: Optional[dict]) -> None:
+        registro = _ATUAL.get()
+        _ATUAL.reset(token)
+        if registro is None:
+            return
+        registro['status'] = status
+        registro['redirect'] = location
+        registro['flash'] = flash
+        registro['ms'] = round((time.perf_counter() - registro.pop('t0')) * 1000, 1)
+        with self._trava:
+            self.requests.appendleft(registro)
+
+    def get(self, numero: int) -> Optional[dict]:
+        return next((r for r in list(self.requests) if r['n'] == numero), None)
+
+    # -- the page ------------------------------------------------------------
+
+    def render(self, numero: Optional[int] = None) -> str:
+        requisicoes = list(self.requests)
+        escolhida = self.get(numero) if numero is not None else (requisicoes[0] if requisicoes else None)
+        e = html.escape
+        linhas = []
+        for r in requisicoes:
+            atual = escolhida is not None and r['n'] == escolhida['n']
+            linhas.append(
+                f'<tr class="{"atual" if atual else ""}"><td><a href="/_dev/{r["n"]}">#{r["n"]}</a></td>'
+                f'<td>{e(r["method"])}</td><td>{e(r["path"])}</td><td>{r["status"]}</td>'
+                f'<td>{e(r["action"] or "")}</td><td>{len(r["queries"])}</td><td>{r["ms"]} ms</td></tr>')
+        detalhe = self._detalhe(escolhida) if escolhida else '<p>No requests yet. Open a page of the app.</p>'
+        return f'''<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8"><title>Quantum /_dev</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+body {{ font: 14px/1.45 system-ui, sans-serif; margin: 0; padding: 16px; color: #1f2328; background: #f6f8fa; }}
+h1 {{ font-size: 18px; margin: 0 0 4px; }} h2 {{ font-size: 15px; margin: 20px 0 6px; }}
+.nota {{ color: #57606a; margin: 0 0 12px; }}
+table {{ border-collapse: collapse; width: 100%; background: #fff; }}
+td, th {{ border: 1px solid #d0d7de; padding: 4px 8px; text-align: left; vertical-align: top; }}
+tr.atual td {{ background: #ddf4ff; }}
+code, pre {{ font: 12px/1.4 ui-monospace, monospace; white-space: pre-wrap; word-break: break-word; margin: 0; }}
+th code {{ white-space: nowrap; word-break: normal; }}
+.erro {{ color: #cf222e; }}
+.caixa {{ overflow-x: auto; }}
+</style></head><body>
+<h1>Quantum /_dev</h1>
+<p class="nota">The last {len(requisicoes)} requests of this server process. Shown because
+<code>server.debug</code> is true; with <code>debug: false</code> this page does not exist.</p>
+<div class="caixa"><table><tr><th>#</th><th>Method</th><th>Path</th><th>Status</th><th>Action</th>
+<th>Queries</th><th>Time</th></tr>{"".join(linhas)}</table></div>
+{detalhe}
+</body></html>'''
+
+    def _detalhe(self, r: dict) -> str:
+        e = html.escape
+        partes = [f'<h2>#{r["n"]} {e(r["method"])} {e(r["path"])} → {r["status"]} ({r["ms"]} ms)</h2>',
+                  '<div class="caixa"><table>',
+                  f'<tr><th>Component</th><td><code>{e(r["component"] or "—")}</code></td></tr>',
+                  f'<tr><th>Action</th><td>{e(r["action"] or "—")}</td></tr>',
+                  f'<tr><th>Redirect</th><td>{e(r["redirect"] or "—")}</td></tr>']
+        flash = r.get('flash')
+        partes.append('<tr><th>Flash</th><td>' + (
+            f'{e(str(flash.get("message", "")))} <em>({e(str(flash.get("type", "")))})</em>' if flash else '—')
+            + '</td></tr>')
+        if r.get('error'):
+            partes.append(f'<tr><th>Error</th><td class="erro"><pre>{e(r["error"])}</pre></td></tr>')
+        partes.append('</table></div>')
+        partes.append(f'<h2>Queries ({len(r["queries"])})</h2>')
+        if r['queries']:
+            partes.append('<div class="caixa"><table><tr><th>Datasource</th><th>SQL</th><th>Params</th>'
+                          '<th>Rows</th><th>Time</th></tr>')
+            for q in r['queries']:
+                params = ', '.join(f'{e(k)}={e(v)}' for k, v in q['params'].items())
+                resultado = f'<span class="erro">{e(q["error"])}</span>' if q['error'] else (q['rows'] if q['rows'] is not None else '—')
+                partes.append(f'<tr><td>{e(q["datasource"])}</td><td><pre>{e(q["sql"])}</pre></td>'
+                              f'<td><code>{params}</code></td><td>{resultado}</td><td>{q["ms"]} ms</td></tr>')
+            partes.append('</table></div>')
+        else:
+            partes.append('<p>None.</p>')
+        for escopo, variaveis in (r.get('scopes') or {}).items():
+            partes.append(f'<h2>{e(escopo)} ({len(variaveis)})</h2>')
+            if variaveis:
+                partes.append('<div class="caixa"><table>' + ''.join(
+                    f'<tr><th><code>{e(k)}</code></th><td><code>{e(v)}</code></td></tr>'
+                    for k, v in variaveis.items()) + '</table></div>')
+            else:
+                partes.append('<p>None.</p>')
+        return '\n'.join(partes)

quantum/runtime/email_service.py

@@ -0,0 +1,162 @@
+"""
+Phase I: Email Service
+
+ColdFusion cfmail-inspired email sending with SMTP support.
+"""
+
+import smtplib
+import os
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from email.mime.base import MIMEBase
+from email import encoders
+from typing import List, Dict, Any, Optional
+from pathlib import Path
+
+
+class EmailError(Exception):
+    """Raised when email sending fails"""
+    pass
+
+
+class EmailService:
+    """Service for sending emails via SMTP"""
+
+    def __init__(self):
+        """Initialize email service with config from environment"""
+        self.smtp_host = os.getenv('SMTP_HOST', 'localhost')
+        self.smtp_port = int(os.getenv('SMTP_PORT', '587'))
+        self.smtp_user = os.getenv('SMTP_USER', '')
+        self.smtp_password = os.getenv('SMTP_PASSWORD', '')
+        self.smtp_use_tls = os.getenv('SMTP_USE_TLS', 'true').lower() == 'true'
+        self.default_from = os.getenv('SMTP_FROM', 'noreply@quantum.dev')
+
+    def send_email(
+        self,
+        to: str,
+        subject: str,
+        body: str,
+        from_addr: Optional[str] = None,
+        cc: Optional[str] = None,
+        bcc: Optional[str] = None,
+        reply_to: Optional[str] = None,
+        email_type: str = "html",
+        attachments: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Send email via SMTP
+
+        Args:
+            to: Recipient email(s) (comma-separated)
+            subject: Email subject
+            body: Email body content
+            from_addr: Sender email (uses default if not provided)
+            cc: CC recipients (comma-separated)
+            bcc: BCC recipients (comma-separated)
+            reply_to: Reply-To address
+            email_type: 'html' or 'text'
+            attachments: List of file paths to attach
+
+        Returns:
+            Dict with send result
+
+        Raises:
+            EmailError: If sending fails
+        """
+        try:
+            # Create message
+            msg = MIMEMultipart()
+            msg['From'] = from_addr or self.default_from
+            msg['To'] = to
+            msg['Subject'] = subject
+
+            if cc:
+                msg['Cc'] = cc
+            if reply_to:
+                msg['Reply-To'] = reply_to
+
+            # Attach body
+            mime_type = 'html' if email_type == 'html' else 'plain'
+            msg.attach(MIMEText(body, mime_type, 'utf-8'))
+
+            # Attach files if provided
+            if attachments:
+                for file_path in attachments:
+                    self._attach_file(msg, file_path)
+
+            # Prepare recipients
+            recipients = self._parse_recipients(to, cc, bcc)
+
+            # Send email
+            if os.getenv('EMAIL_MOCK', 'true').lower() == 'true':
+                # Mock mode for development (don't actually send)
+                print(f"[MOCK] Email sent to {to}")
+                print(f"   Subject: {subject}")
+                print(f"   From: {msg['From']}")
+                print(f"   Type: {email_type}")
+                return {
+                    'success': True,
+                    'mock': True,
+                    'to': to,
+                    'subject': subject,
+                    'message': 'Email mock-sent successfully'
+                }
+            else:
+                # Real SMTP sending
+                with smtplib.SMTP(self.smtp_host, self.smtp_port) as server:
+                    if self.smtp_use_tls:
+                        server.starttls()
+
+                    if self.smtp_user and self.smtp_password:
+                        server.login(self.smtp_user, self.smtp_password)
+
+                    server.sendmail(msg['From'], recipients, msg.as_string())
+
+                return {
+                    'success': True,
+                    'to': to,
+                    'subject': subject,
+                    'message': 'Email sent successfully'
+                }
+
+        except Exception as e:
+            raise EmailError(f"Failed to send email: {e}")
+
+    def _attach_file(self, msg: MIMEMultipart, file_path: str):
+        """Attach a file to email message"""
+        try:
+            path = Path(file_path)
+            if not path.exists():
+                raise EmailError(f"Attachment file not found: {file_path}")
+
+            with open(file_path, 'rb') as f:
+                part = MIMEBase('application', 'octet-stream')
+                part.set_payload(f.read())
+
+            encoders.encode_base64(part)
+            part.add_header(
+                'Content-Disposition',
+                f'attachment; filename= {path.name}'
+            )
+
+            msg.attach(part)
+        except Exception as e:
+            raise EmailError(f"Failed to attach file {file_path}: {e}")
+
+    def _parse_recipients(
+        self,
+        to: str,
+        cc: Optional[str] = None,
+        bcc: Optional[str] = None
+    ) -> List[str]:
+        """Parse comma-separated email addresses into list"""
+        recipients = []
+
+        if to:
+            recipients.extend([email.strip() for email in to.split(',')])
+        if cc:
+            recipients.extend([email.strip() for email in cc.split(',')])
+        if bcc:
+            recipients.extend([email.strip() for email in bcc.split(',')])
+
+        return recipients

quantum/runtime/error_handler.py

@@ -0,0 +1,295 @@
+"""
+Enhanced Error Handler - Phase C: Developer Experience
+
+Provides better error messages with:
+- Context (line numbers, code snippets)
+- Suggestions (did you mean...?)
+- Helpful hints
+- Color-coded output
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional, List
+import difflib
+
+class QuantumError(Exception):
+    """Base class for Quantum errors with enhanced context"""
+
+    def __init__(self, message: str, file_path: Optional[str] = None,
+                 line: Optional[int] = None, column: Optional[int] = None,
+                 suggestion: Optional[str] = None, hint: Optional[str] = None):
+        self.message = message
+        self.file_path = file_path
+        self.line = line
+        self.column = column
+        self.suggestion = suggestion
+        self.hint = hint
+        super().__init__(self.format_error())
+
+    def format_error(self) -> str:
+        """Format error message with context"""
+        parts = []
+
+        # Header
+        parts.append("=" * 60)
+        parts.append("❌ QUANTUM ERROR")
+        parts.append("=" * 60)
+
+        # Location
+        if self.file_path:
+            location = f"📂 File: {self.file_path}"
+            if self.line:
+                location += f":{self.line}"
+                if self.column:
+                    location += f":{self.column}"
+            parts.append(location)
+
+        # Error message
+        parts.append(f"\n💥 {self.message}")
+
+        # Code context
+        if self.file_path and self.line:
+            context = self._get_code_context()
+            if context:
+                parts.append("\n📝 Code:")
+                parts.append(context)
+
+        # Suggestion
+        if self.suggestion:
+            parts.append(f"\n💡 Suggestion: {self.suggestion}")
+
+        # Hint
+        if self.hint:
+            parts.append(f"\n🔍 Hint: {self.hint}")
+
+        parts.append("=" * 60)
+
+        return "\n".join(parts)
+
+    def _get_code_context(self, context_lines: int = 3) -> Optional[str]:
+        """Get code context around error line"""
+        try:
+            file_path = Path(self.file_path)
+            if not file_path.exists():
+                return None
+
+            lines = file_path.read_text(encoding='utf-8').splitlines()
+
+            start = max(0, self.line - context_lines - 1)
+            end = min(len(lines), self.line + context_lines)
+
+            context_parts = []
+            for i in range(start, end):
+                line_num = i + 1
+                line_content = lines[i]
+
+                # Mark error line with arrow
+                if line_num == self.line:
+                    context_parts.append(f"  → {line_num:4d} | {line_content}")
+                    # Add column pointer if available
+                    if self.column:
+                        pointer = " " * (self.column + 10) + "^"
+                        context_parts.append(pointer)
+                else:
+                    context_parts.append(f"    {line_num:4d} | {line_content}")
+
+            return "\n".join(context_parts)
+
+        except Exception:
+            return None
+
+
+class ComponentNotFoundError(QuantumError):
+    """Component import not found"""
+
+    def __init__(self, component_name: str, file_path: str, line: int,
+                 available_components: List[str] = None):
+        # Find similar component names
+        suggestion = None
+        if available_components:
+            matches = difflib.get_close_matches(component_name, available_components, n=3, cutoff=0.6)
+            if matches:
+                if len(matches) == 1:
+                    suggestion = f"Did you mean '{matches[0]}'?"
+                else:
+                    suggestion = f"Did you mean one of: {', '.join(matches)}?"
+
+        hint = f"Add: <q:import component=\"{component_name}\" />"
+
+        super().__init__(
+            f"Component '{component_name}' not found",
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion,
+            hint=hint
+        )
+
+
+class ValidationErrorWithContext(QuantumError):
+    """Validation error with context"""
+
+    def __init__(self, field_name: str, validation_type: str,
+                 value: any, file_path: str = None, line: int = None):
+        message = f"Validation failed for field '{field_name}' ({validation_type})"
+
+        if validation_type == "required":
+            suggestion = f"Field '{field_name}' is required but was not provided"
+        elif validation_type == "type":
+            suggestion = f"Expected type differs from provided value: {value}"
+        elif validation_type == "minlength":
+            suggestion = f"Value '{value}' is too short"
+        elif validation_type == "maxlength":
+            suggestion = f"Value '{value}' is too long"
+        elif validation_type == "pattern":
+            suggestion = f"Value '{value}' doesn't match required pattern"
+        else:
+            suggestion = f"Validation '{validation_type}' failed for value: {value}"
+
+        super().__init__(
+            message,
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion
+        )
+
+
+class QueryErrorWithContext(QuantumError):
+    """Query error with SQL context"""
+
+    def __init__(self, query_name: str, sql: str, error: str,
+                 file_path: str = None, line: int = None):
+        message = f"Query '{query_name}' failed"
+
+        # Provide SQL-specific suggestions
+        suggestion = None
+        if "syntax error" in error.lower():
+            suggestion = "Check your SQL syntax"
+        elif "table" in error.lower() and "doesn't exist" in error.lower():
+            suggestion = "Table doesn't exist - check your database schema"
+        elif "column" in error.lower():
+            suggestion = "Column doesn't exist - check your table structure"
+        elif "duplicate" in error.lower():
+            suggestion = "Duplicate entry - check for unique constraints"
+
+        hint = f"SQL: {sql[:100]}..." if len(sql) > 100 else f"SQL: {sql}"
+
+        super().__init__(
+            f"{message}: {error}",
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion,
+            hint=hint
+        )
+
+
+class TransactionErrorWithContext(QuantumError):
+    """Transaction error with rollback info"""
+
+    def __init__(self, error: str, statements_executed: int,
+                 file_path: str = None, line: int = None):
+        message = "Transaction failed and was rolled back"
+
+        suggestion = f"{statements_executed} statement(s) were executed before failure"
+        hint = "All changes have been rolled back. Check the error above and fix the issue."
+
+        super().__init__(
+            f"{message}: {error}",
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion,
+            hint=hint
+        )
+
+
+class FileUploadErrorWithContext(QuantumError):
+    """File upload error with details"""
+
+    def __init__(self, error: str, filename: str = None,
+                 file_size: int = None, max_size: int = None,
+                 file_path: str = None, line: int = None):
+        message = f"File upload failed"
+
+        suggestion = None
+        if "too large" in error.lower():
+            if file_size and max_size:
+                suggestion = f"File is {file_size} bytes but maximum is {max_size} bytes"
+        elif "type" in error.lower() or "extension" in error.lower():
+            suggestion = "File type not allowed - check allowed extensions"
+
+        hint = None
+        if filename:
+            hint = f"Filename: {filename}"
+
+        super().__init__(
+            f"{message}: {error}",
+            file_path=file_path,
+            line=line,
+            suggestion=suggestion,
+            hint=hint
+        )
+
+
+class ErrorHandler:
+    """Central error handler for better error reporting"""
+
+    _logger = None
+
+    @classmethod
+    def _get_logger(cls):
+        if cls._logger is None:
+            import logging
+            cls._logger = logging.getLogger('quantum.errors')
+        return cls._logger
+
+    @staticmethod
+    def handle_parse_error(error: Exception, file_path: str) -> QuantumError:
+        """Convert parse errors to enhanced errors"""
+        error_msg = str(error)
+
+        # Extract line and column from XML parse errors
+        line = None
+        column = None
+        if "line" in error_msg:
+            import re
+            match = re.search(r'line (\d+)', error_msg)
+            if match:
+                line = int(match.group(1))
+            match = re.search(r'column (\d+)', error_msg)
+            if match:
+                column = int(match.group(1))
+
+        return QuantumError(
+            f"Parse error: {error_msg}",
+            file_path=file_path,
+            line=line,
+            column=column,
+            suggestion="Check your XML syntax",
+            hint="Make sure all tags are properly closed and attributes are quoted"
+        )
+
+    @staticmethod
+    def handle_runtime_error(error: Exception, component_name: str,
+                            file_path: str = None) -> QuantumError:
+        """Convert runtime errors to enhanced errors"""
+        return QuantumError(
+            f"Runtime error in component '{component_name}': {error}",
+            file_path=file_path,
+            suggestion="Check your component logic and variable names",
+            hint="Run the component with `quantum run <file>.q` to see the error without the server"
+        )
+
+    @classmethod
+    def print_warning(cls, message: str):
+        """Log formatted warning"""
+        cls._get_logger().warning(message)
+
+    @classmethod
+    def print_info(cls, message: str):
+        """Log formatted info"""
+        cls._get_logger().info(message)
+
+    @classmethod
+    def print_success(cls, message: str):
+        """Log formatted success"""
+        cls._get_logger().info(message)