quantum-framework 0.11.0__tar.gz → 0.13.0__tar.gz

{quantum_framework-0.11.0/quantum_framework.egg-info → quantum_framework-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantum-framework
-Version: 0.11.0
+Version: 0.13.0
 Summary: Full-stack declarative framework for building web, desktop, and mobile applications
 Author-email: Daniel Gregorio <danielgregorio2611@gmail.com>
 License: MIT
@@ -37,6 +37,10 @@ Provides-Extra: rag
 Requires-Dist: chromadb>=0.5.0; extra == "rag"
 Provides-Extra: jobs
 Requires-Dist: apscheduler>=3.10.0; extra == "jobs"
+Provides-Extra: admin
+Requires-Dist: sqlalchemy>=2.0; extra == "admin"
+Requires-Dist: PyJWT>=2.8; extra == "admin"
+Requires-Dist: cryptography>=42.0; extra == "admin"
 Provides-Extra: websocket
 Requires-Dist: websockets>=12.0; extra == "websocket"
 Dynamic: license-file

{quantum_framework-0.11.0 → quantum_framework-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantum-framework"
-version = "0.11.0"
+version = "0.13.0"
 description = "Full-stack declarative framework for building web, desktop, and mobile applications"
 readme = "README.md"
 license = {text = "MIT"}
@@ -50,6 +50,13 @@ jobs = [
     # q:schedule failed on any clean install.
     "apscheduler>=3.10.0",
 ]
+admin = [
+    # `quantum admin`: the admin database (SQLAlchemy), its login tokens
+    # (PyJWT) and encrypted connector secrets (cryptography).
+    "sqlalchemy>=2.0",
+    "PyJWT>=2.8",
+    "cryptography>=42.0",
+]
 websocket = [
     # The transport behind q:websocket. Without it the tag registers a
     # connection and opens nothing — and says so, rather than pretending.
@@ -71,7 +78,14 @@ Repository = "https://github.com/danielgregorio/quantum"
 # do core), e as pastas `quantum-as4`/`quantum-lsp` (projetos irmaos,
 # hifenados e nem importaveis) — 91 arquivos de peso morto no wheel. O ponto
 # em `quantum.*` casa subpacotes; sem ele, `quantum_admin` nao entra.
-include = ["quantum", "quantum.*"]
+include = ["quantum", "quantum.*",
+           # The admin (`quantum admin`, extra [admin]): its screens, its
+           # services and the backend library they use. The backend's
+           # FastAPI modules ship with it, unused by the screens.
+           "quantum_admin", "quantum_admin.services", "quantum_admin.backend"]
+
+[tool.setuptools.package-data]
+quantum_admin = ["components/**/*.q", "assets/*"]
 
 
 [tool.black]

quantum_framework-0.13.0/quantum/cli/admin.py

@@ -0,0 +1,131 @@
+"""`quantum admin` — serve the Quantum Admin (quantum_admin/components/admin).
+
+The admin is a Quantum app: .q screens over declared services. This command
+writes its configuration into a data folder and starts the same server as
+`quantum start`, so nothing has to be set up by hand.
+
+    quantum admin                      # data in ./.quantum-admin, projects under ./
+    quantum admin --data quantum_admin # the repository's own admin data
+
+The data folder holds the admin database, its settings (connectors, global
+settings, process PIDs) and the generated config. Paths of projects are
+relative to the folder the command runs in (--root to change it).
+"""
+
+import os
+import secrets
+from pathlib import Path
+
+MODULES = [
+    "quantum_admin.services.auth",
+    "quantum_admin.services.projects",
+    "quantum_admin.services.yaml_import",
+    "quantum_admin.services.connectors",
+    "quantum_admin.services.settings",
+    "quantum_admin.services.components",
+    "quantum_admin.services.apps",
+    "quantum_admin.services.repository",
+]
+
+INSTALL_HINT = 'pip install "quantum-framework[admin]"'
+
+
+def create_admin_parser(subparsers):
+    parser = subparsers.add_parser('admin', help='Start the Quantum Admin')
+    parser.add_argument('--port', type=int, default=8090, help='Port (default 8090)')
+    parser.add_argument('--data', default='.quantum-admin',
+                        help='Folder for the admin database and settings (default ./.quantum-admin)')
+    parser.add_argument('--root', default='.',
+                        help='Folder the project paths are relative to (default: current folder)')
+    return parser
+
+
+def missing_dependencies():
+    """Names of the [admin] extra's packages that do not import."""
+    faltando = []
+    for modulo, pacote in (("sqlalchemy", "SQLAlchemy"), ("jwt", "PyJWT"),
+                           ("cryptography", "cryptography")):
+        try:
+            __import__(modulo)
+        except ImportError:
+            faltando.append(pacote)
+    return faltando
+
+
+def _package() -> Path:
+    import quantum_admin
+    return Path(quantum_admin.__file__).resolve().parent
+
+
+def screens_folder() -> Path:
+    return _package() / "components"
+
+
+def assets_folder() -> Path:
+    """The screens' CSS and JS, served under /static/."""
+    return _package() / "assets"
+
+
+def _secret(arquivo: Path) -> str:
+    """A key kept in the data folder, so sessions survive a restart."""
+    if arquivo.exists():
+        return arquivo.read_text(encoding="utf-8").strip()
+    chave = secrets.token_hex(32)
+    arquivo.write_text(chave, encoding="utf-8")
+    try:
+        arquivo.chmod(0o600)
+    except OSError:
+        pass
+    return chave
+
+
+def prepare(data: str, root: str, port: int) -> Path:
+    """Create the data folder, point the admin at it, write the config. Returns its path."""
+    import yaml
+
+    pasta = Path(data).resolve()
+    (pasta / "settings").mkdir(parents=True, exist_ok=True)
+
+    # Read by quantum_admin.backend at import time, so set before any import.
+    os.environ["QUANTUM_ADMIN_DATABASE_URL"] = f"sqlite:///{(pasta / 'quantum_admin.db').as_posix()}"
+    os.environ["QUANTUM_ADMIN_SETTINGS_DIR"] = str(pasta / "settings")
+    os.environ["QUANTUM_ADMIN_ROOT"] = str(Path(root).resolve())
+    os.environ.setdefault("JWT_SECRET_KEY", _secret(pasta / "jwt_secret"))
+
+    config = pasta / "quantum.config.yaml"
+    config.write_text(
+        "# Generated by `quantum admin` on every start; edits are overwritten.\n" +
+        yaml.safe_dump({
+            "server": {"host": "127.0.0.1", "port": port, "reload": False, "debug": False},
+            "paths": {"components": screens_folder().as_posix(),
+                      "static": assets_folder().as_posix(),
+                      "uploads": (pasta / "uploads").as_posix(),
+                      "logs": (pasta / "logs").as_posix()},
+            "security": {"login_url": "/admin/login", "secret_key": _secret(pasta / "session_secret")},
+            "logging": {"level": "WARNING", "console": True, "file": False},
+            "services": MODULES,
+        }, sort_keys=False),
+        encoding="utf-8")
+    return config
+
+
+def handle_admin(args) -> int:
+    faltando = missing_dependencies()
+    if faltando:
+        print(f"[ERROR] The admin needs {', '.join(faltando)}. Install with:\n  {INSTALL_HINT}")
+        return 1
+
+    config = prepare(args.data, args.root, args.port)
+
+    from quantum.runtime.web_server import QuantumWebServer
+    from quantum_admin.backend.auth_service import get_auth_service
+
+    # Created now, not at the first login, so a generated password is printed
+    # before the URL instead of in the middle of the request log.
+    get_auth_service()
+    print(f"\n  Quantum Admin: http://127.0.0.1:{args.port}/admin"
+          f"\n  data: {config.parent}\n")
+
+    server = QuantumWebServer(str(config))
+    server.PID_FILE = str(config.parent / "admin.pid")
+    return server.start() or 0

{quantum_framework-0.11.0 → quantum_framework-0.13.0}/quantum/cli/commands/migrate.py

@@ -70,7 +70,9 @@ class DatabaseConnection:
             if not caminho.is_absolute():
                 caminho = self.project_path / caminho
             caminho.parent.mkdir(parents=True, exist_ok=True)
-            self._conn = sqlite3.connect(str(caminho))
+            # isolation_level=None: execute_script opens the transaction
+            # itself, so a CREATE TABLE is inside it too (DB-8).
+            self._conn = sqlite3.connect(str(caminho), isolation_level=None)
             self._db_type = 'sqlite'
             logger.info("Migrating datasource %s (SQLite at %s)", nome, caminho)
             return self._conn
@@ -128,6 +130,32 @@ class DatabaseConnection:
             cursor.execute(sql)
         return cursor
 
+    def execute_script(self, sql: str):
+        """Run a whole migration file, in one transaction (DB-8).
+
+        sqlite3's execute() takes ONE statement, so every migration with more
+        than one — a table and its index — failed with "You can only execute
+        one statement at a time". The statements are split here and run
+        inside an explicit BEGIN, which commit()/rollback() close: a failure
+        halfway leaves no table behind.
+        """
+        if self._db_type != 'sqlite':
+            return self.execute(sql)
+        import sqlite3
+        cursor = self._conn.cursor()
+        if not self._conn.in_transaction:
+            cursor.execute('BEGIN')
+        pedaco = ''
+        for linha in sql.splitlines(keepends=True):
+            pedaco += linha
+            if sqlite3.complete_statement(pedaco):
+                if pedaco.strip():
+                    cursor.execute(pedaco)
+                pedaco = ''
+        if pedaco.strip() and not all(l.strip().startswith('--') or not l.strip() for l in pedaco.splitlines()):
+            raise MigrationError(f"incomplete SQL statement at the end: {pedaco.strip()[:80]!r}")
+        return cursor
+
     def commit(self):
         self._conn.commit()
 
@@ -275,7 +303,7 @@ class MigrationRunner:
                 click.echo(f"Applying {migration.version}: {migration.name}...")
 
                 # Execute migration SQL
-                self.db.execute(migration.content)
+                self.db.execute_script(migration.content)
 
                 # Record migration
                 self._record_migration(migration)
@@ -338,7 +366,7 @@ class MigrationRunner:
                 click.echo(f"Rolling back {version}: {migration_info['name']}...")
 
                 # Execute rollback SQL
-                self.db.execute(down_file.read_text())
+                self.db.execute_script(down_file.read_text())
 
                 # Remove migration record
                 self._remove_migration_record(version)

{quantum_framework-0.11.0 → quantum_framework-0.13.0}/quantum/cli/runner.py

@@ -24,6 +24,7 @@ if os.name == 'nt':  # Windows
 from quantum.core.parser import QuantumParser, QuantumParseError
 from quantum.core.ast_nodes import ComponentNode, ApplicationNode, JobNode
 from quantum.runtime.component import ComponentRuntime, ComponentExecutionError
+from quantum.runtime.executors.control_flow.redirect_executor import PageRedirect
 from quantum.runtime.web_server import QuantumWebServer
 
 # Import deploy commands (lazy load to avoid import errors if requests not installed)
@@ -166,6 +167,9 @@ class QuantumRunner:
         except ComponentExecutionError as e:
             print(f"[ERROR] Execution error: {e}")
             return 1
+        except PageRedirect as r:
+            print(f"[REDIRECT] {r.status} {r.url}")
+            return 0
     
     def _execute_application(self, app: ApplicationNode, debug: bool = False) -> int:
         """Execute q:application"""
@@ -280,6 +284,7 @@ def main():
 Examples:
   quantum start                    # Start web server (magic!)
   quantum run hello.q              # Execute component
+  quantum admin                    # Start the Quantum Admin
   quantum run game.q --engine godot # Build Godot 4 project
   quantum run backup-job.q         # Execute job
   quantum deploy ./my-app          # Deploy application
@@ -330,6 +335,10 @@ Examples:
     # Stop command
     subparsers.add_parser('stop', help='Stop running web server')
 
+    # Admin command (the screens need the [admin] extra; checked when run)
+    from quantum.cli.admin import create_admin_parser
+    create_admin_parser(subparsers)
+
     # Deploy commands (if available)
     deploy_available, create_deploy_parser, create_apps_parser, handle_deploy, handle_apps = _get_deploy_module()
 
@@ -392,6 +401,10 @@ Examples:
                 traceback.print_exc()
             sys.exit(1)
 
+    elif args.command == 'admin':
+        from quantum.cli.admin import handle_admin
+        sys.exit(handle_admin(args))
+
     # Handle 'stop' command
     elif args.command == 'stop':
         from quantum.cli.server_process import stop_server

{quantum_framework-0.11.0 → quantum_framework-0.13.0}/quantum/core/ast_nodes.py

@@ -112,6 +112,7 @@ class ComponentNode(QuantumNode):
         # Phase G: Authentication & Security
         self.require_auth = False  # Require authentication to access component
         self.require_role = None   # Required role(s) to access (comma-separated: "admin,editor")
+        self.login_url = None      # AUTH-4: overrides security.login_url for this component
         self.require_permission = None  # Required permission(s)
 
         # HTML rendering & interactivity (Phase 1 & future Phase 3)

{quantum_framework-0.11.0 → quantum_framework-0.13.0}/quantum/core/expression_stdlib.py

@@ -15,6 +15,9 @@ Functions are looked up by name from expressions, so anything added here
 becomes language surface. That is the reason to keep it short.
 """
 
+import math
+import re
+from decimal import Decimal, ROUND_HALF_UP
 from datetime import datetime, timedelta
 from typing import Any, Iterable, Optional
 
@@ -84,6 +87,13 @@ def _split(v: Any, sep: str = ",") -> list: return str(v).split(sep)
 def _contains(v: Any, needle: Any) -> bool: return str(needle) in str(v)
 
 
+def _slugify(v: Any) -> str:
+    """'Olá, Mundo!' -> 'ola-mundo': for URLs made from a title (EXPR-9)."""
+    import unicodedata
+    texto = unicodedata.normalize('NFKD', str(v)).encode('ascii', 'ignore').decode('ascii')
+    return re.sub(r'[^a-z0-9]+', '-', texto.lower()).strip('-')
+
+
 # -- collections -----------------------------------------------------------
 
 def _len(v: Any) -> int:
@@ -114,8 +124,21 @@ def _sort(v: Iterable, reverse: bool = False) -> list:
 # -- numbers ---------------------------------------------------------------
 
 def _round(v: Any, digits: int = 0) -> Any:
-    result = round(float(v), int(digits))
-    return int(result) if digits == 0 else result
+    # EXPR-9: half away from zero, as in ColdFusion and spreadsheets. Python's
+    # round() is banker's rounding over binary floats: round(2.5) was 2 and
+    # round(0.125, 2) was 0.12. Decimal over the number's text avoids both.
+    casas = int(digits)
+    passo = Decimal(1).scaleb(-casas)
+    result = Decimal(str(v)).quantize(passo, rounding=ROUND_HALF_UP)
+    return int(result) if casas <= 0 else float(result)
+
+
+def _ceil(v: Any) -> int:
+    return math.ceil(float(v))
+
+
+def _floor(v: Any) -> int:
+    return math.floor(float(v))
 
 
 # -- passwords ---------------------------------------------------------------
@@ -165,6 +188,7 @@ STDLIB = {
     'replace': _replace,
     'split': _split,
     'contains': _contains,
+    'slugify': _slugify,
     # collections
     'len': _len,
     'first': _first,
@@ -173,6 +197,8 @@ STDLIB = {
     'sort': _sort,
     # numbers
     'round': _round,
+    'ceil': _ceil,
+    'floor': _floor,
     'abs': abs,
     'min': min,
     'max': max,

{quantum_framework-0.11.0 → quantum_framework-0.13.0}/quantum/core/expressions.py

@@ -23,6 +23,7 @@ access, and the whole arithmetic/comparison/call surface is about 15%.
 """
 
 import ast
+import contextvars
 import math
 import operator
 import re
@@ -30,6 +31,11 @@ from typing import Any, Callable, Dict, Optional
 
 from quantum.core.expression_stdlib import STDLIB
 
+# EXPR-8: in a condition, a key a scope does not have (`session.userId`
+# before login) is absent, not a failure — see ExpressionEvaluator.evaluate.
+_SCOPES = ('session', 'application', 'request', 'cookie', 'form', 'query')
+_ABSENT_SCOPE_KEY_IS_NONE = contextvars.ContextVar('absent_scope_key_is_none', default=False)
+
 
 class ExpressionError(Exception):
     """Raised when an expression cannot be evaluated."""
@@ -249,6 +255,43 @@ def _normalise_js_operators(source: str) -> str:
     return ''.join(out)
 
 
+# EXPR-10: what a JavaScript habit is called here. `Math.ceil(x)` and
+# `text.split(' ')` are the first things people write; the bare "only named
+# function calls are allowed" did not say what to write instead.
+_JS_EQUIVALENTS = {
+    'Math.ceil': 'ceil(x)', 'Math.floor': 'floor(x)', 'Math.round': 'round(x)',
+    'Math.max': 'max(a, b)', 'Math.min': 'min(a, b)', 'Math.abs': 'abs(x)',
+    'Date.now': 'now()', 'parseInt': 'int(x)', 'parseFloat': 'float(x)',
+    'split': "split(text, ' ')", 'join': "join(items, ', ')", 'toUpperCase': 'upper(text)',
+    'toLowerCase': 'lower(text)', 'trim': 'trim(text)', 'replace': 'replace(text, old, new)',
+    'includes': 'contains(text, part)', 'indexOf': 'contains(text, part)',
+}
+
+
+def _method_hint(func: ast.AST) -> str:
+    if not isinstance(func, ast.Attribute):
+        return ""
+    base = func.value.id if isinstance(func.value, ast.Name) else None
+    chave = f"{base}.{func.attr}" if base in ('Math', 'Date') else func.attr
+    if chave in _JS_EQUIVALENTS:
+        escrito = chave if '.' in chave else f"x.{func.attr}"
+        return f"; write {_JS_EQUIVALENTS[chave]} instead of {escrito}(...)"
+    return f"; call functions by name, e.g. {func.attr}(x), not x.{func.attr}()"
+
+
+def names_read(expression: str) -> set:
+    """The root names an expression reads — `user` in `user.name > 1` — not the
+    functions it calls. An expression that does not parse reads nothing here;
+    evaluating it reports the error."""
+    try:
+        tree = ast.parse(_normalise_js_operators(expression.strip()), mode='eval')
+    except SyntaxError:
+        return set()
+    chamadas = {id(n.func) for n in ast.walk(tree) if isinstance(n, ast.Call)}
+    return {n.id for n in ast.walk(tree)
+            if isinstance(n, ast.Name) and id(n) not in chamadas}
+
+
 class ExpressionEvaluator:
     """Evaluates Quantum `{...}` expressions against a variable context."""
 
@@ -274,8 +317,24 @@ class ExpressionEvaluator:
 
     # -- public API --------------------------------------------------------
 
-    def evaluate(self, expression: str, context: Dict[str, Any]) -> Any:
-        """Evaluate an expression, raising ExpressionError on any failure."""
+    def evaluate(self, expression: str, context: Dict[str, Any],
+                 absent_scope_key_is_none: bool = False) -> Any:
+        """Evaluate an expression, raising ExpressionError on any failure.
+
+        absent_scope_key_is_none (conditions, EXPR-8): `session.x` where the
+        scope has no `x` reads as None instead of raising. A condition is a
+        presence test, and a scope key that is not there yet is the ordinary
+        case (a page runs before login) — raising made the WHOLE condition
+        false, so `not session.authenticated` was false for a visitor with no
+        session and a guard written that way never fired.
+        """
+        marca = _ABSENT_SCOPE_KEY_IS_NONE.set(absent_scope_key_is_none)
+        try:
+            return self._evaluate(expression, context)
+        finally:
+            _ABSENT_SCOPE_KEY_IS_NONE.reset(marca)
+
+    def _evaluate(self, expression: str, context: Dict[str, Any]) -> Any:
         if expression is None:
             raise ExpressionError("expression is None")
 
@@ -423,18 +482,18 @@ class ExpressionEvaluator:
             return op(operand)
 
         if isinstance(node, ast.BoolOp):
-            values = [self._eval(v, ctx) for v in node.values]
-            if isinstance(node.op, ast.And):
-                result = True
-                for v in values:
-                    if not v:
-                        return v
-                    result = v
-                return result
-            for v in values:
-                if v:
-                    return v
-            return values[-1] if values else False
+            # EXPR-6: short-circuit, as in Python. Every operand used to be
+            # evaluated first, so `user and user.name` failed with "variable
+            # 'user' is not defined"-style errors exactly when the left side
+            # was there to guard the right.
+            valor = False
+            for operando in node.values:
+                valor = self._eval(operando, ctx)
+                if isinstance(node.op, ast.And) and not valor:
+                    return valor
+                if isinstance(node.op, ast.Or) and valor:
+                    return valor
+            return valor
 
         if isinstance(node, ast.Compare):
             left = self._eval(node.left, ctx)
@@ -473,6 +532,11 @@ class ExpressionEvaluator:
             plano = self._dotted_name(node)
             if plano is not None and plano in ctx:
                 return ctx[plano]
+            if (_ABSENT_SCOPE_KEY_IS_NONE.get() and isinstance(node.value, ast.Name)
+                    and node.value.id in _SCOPES):
+                escopo = ctx.get(node.value.id)
+                if escopo is None or (isinstance(escopo, dict) and node.attr not in escopo):
+                    return None
             return self._attribute(self._eval(node.value, ctx), node.attr)
 
         if isinstance(node, ast.Subscript):
@@ -588,7 +652,7 @@ class ExpressionEvaluator:
 
     def _call(self, node: ast.Call, ctx: Dict[str, Any]) -> Any:
         if not isinstance(node.func, ast.Name):
-            raise ExpressionError("only named function calls are allowed")
+            raise ExpressionError("only named function calls are allowed" + _method_hint(node.func))
         fn = self.functions.get(node.func.id)
         if fn is None and self.function_resolver is not None:
             # A q:function declared by the component being executed.
@@ -600,7 +664,8 @@ class ExpressionEvaluator:
         if fn is None:
             raise ExpressionError(
                 f"function {node.func.id!r} is not defined"
-                f"{_suggest(node.func.id, self.functions)}"
+                + (f"; write {_JS_EQUIVALENTS[node.func.id]}" if node.func.id in _JS_EQUIVALENTS
+                   else _suggest(node.func.id, self.functions))
             )
         args = [self._eval(a, ctx) for a in node.args]
         kwargs = {kw.arg: self._eval(kw.value, ctx) for kw in node.keywords}

quantum_framework-0.13.0/quantum/core/guards.py

@@ -0,0 +1,53 @@
+"""Page guards (AUTH-6): a q:if at the top of a page whose branch has a q:redirect.
+
+    <q:if condition="not session.authenticated">
+      <q:redirect url="/login" />
+    </q:if>
+
+A q:action does not run the page's statements, so a guard written like this
+used to protect only the GET — the POST ran the action without a session.
+Guards now run before each action of the page as well as before the render.
+"""
+
+from typing import List
+
+from quantum.core.ast_nodes import RedirectNode
+from quantum.core.features.conditionals.src.ast_node import IfNode
+
+
+def _branches(node: IfNode) -> List:
+    corpo = list(node.if_body)
+    for bloco in node.elseif_blocks:
+        corpo += list(bloco.get('body', []))
+    return corpo + list(node.else_body)
+
+
+def _has_redirect(nodes) -> bool:
+    return any(isinstance(n, RedirectNode) or (isinstance(n, IfNode) and _has_redirect(_branches(n)))
+               for n in nodes)
+
+
+def page_guards(component) -> List[IfNode]:
+    """The top-level q:if statements that can redirect, in document order."""
+    return [s for s in getattr(component, 'statements', [])
+            if isinstance(s, IfNode) and _has_redirect(_branches(s))]
+
+
+def guard_conditions(node: IfNode) -> List[str]:
+    """Every condition a guard evaluates, nested q:if included."""
+    condicoes = [node.condition] + [b.get('condition', '') for b in node.elseif_blocks]
+    for filho in _branches(node):
+        if isinstance(filho, IfNode):
+            condicoes += guard_conditions(filho)
+    return [c for c in condicoes if c]
+
+
+def mark_guards(component) -> None:
+    """Flag each guard, nested q:if included, so its condition fails closed (AUTH-6)."""
+    def marcar(node):
+        node.is_guard = True
+        for filho in _branches(node):
+            if isinstance(filho, IfNode):
+                marcar(filho)
+    for guarda in page_guards(component):
+        marcar(guarda)