quantum-framework 0.10.0__tar.gz → 0.12.0__tar.gz

{quantum_framework-0.10.0/quantum_framework.egg-info → quantum_framework-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantum-framework
-Version: 0.10.0
+Version: 0.12.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
@@ -216,7 +220,7 @@ Full docs at **[danielgregorio.github.io/quantum](https://danielgregorio.github.
 
 - [Getting Started](https://danielgregorio.github.io/quantum/guide/getting-started) · [Installation](https://danielgregorio.github.io/quantum/guide/installation) · [Quick Start](https://danielgregorio.github.io/quantum/guide/quick-start)
 - [Components](https://danielgregorio.github.io/quantum/guide/components) · [State](https://danielgregorio.github.io/quantum/guide/state-management) · [Loops](https://danielgregorio.github.io/quantum/guide/loops) · [Conditionals](https://danielgregorio.github.io/quantum/guide/conditionals)
-- [Queries](https://danielgregorio.github.io/quantum/guide/query) · [Functions](https://danielgregorio.github.io/quantum/guide/functions) · [Data fetching](https://danielgregorio.github.io/quantum/guide/data-fetching)
+- [Queries](https://danielgregorio.github.io/quantum/guide/query) · [Functions](https://danielgregorio.github.io/quantum/guide/functions)
 
 Releases and their notes are on the [GitHub Releases](https://github.com/danielgregorio/quantum/releases) page.
 

{quantum_framework-0.10.0 → quantum_framework-0.12.0}/README.md

@@ -173,7 +173,7 @@ Full docs at **[danielgregorio.github.io/quantum](https://danielgregorio.github.
 
 - [Getting Started](https://danielgregorio.github.io/quantum/guide/getting-started) · [Installation](https://danielgregorio.github.io/quantum/guide/installation) · [Quick Start](https://danielgregorio.github.io/quantum/guide/quick-start)
 - [Components](https://danielgregorio.github.io/quantum/guide/components) · [State](https://danielgregorio.github.io/quantum/guide/state-management) · [Loops](https://danielgregorio.github.io/quantum/guide/loops) · [Conditionals](https://danielgregorio.github.io/quantum/guide/conditionals)
-- [Queries](https://danielgregorio.github.io/quantum/guide/query) · [Functions](https://danielgregorio.github.io/quantum/guide/functions) · [Data fetching](https://danielgregorio.github.io/quantum/guide/data-fetching)
+- [Queries](https://danielgregorio.github.io/quantum/guide/query) · [Functions](https://danielgregorio.github.io/quantum/guide/functions)
 
 Releases and their notes are on the [GitHub Releases](https://github.com/danielgregorio/quantum/releases) page.
 

{quantum_framework-0.10.0 → quantum_framework-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantum-framework"
-version = "0.10.0"
+version = "0.12.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.12.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.10.0 → quantum_framework-0.12.0}/quantum/cli/commands/migrate.py

@@ -1,6 +1,6 @@
 """
 Quantum CLI - Database Migration Commands
-Handles database migrations with automatic PostgreSQL/SQLite failover
+Applies migrations to a datasource declared in quantum.config.yaml (DB-6)
 """
 import os
 import sys
@@ -44,95 +44,76 @@ class Migration:
 
 
 class DatabaseConnection:
-    """Database connection with automatic failover"""
+    """Connection to the datasource the migrations are for (DB-6).
 
-    def __init__(self, project_path: Path = None):
+    It used to read a separate `database:` section that nothing else uses and,
+    without one, try a PostgreSQL at localhost/quantum with user postgres before
+    falling back to ./data/quantum.db. A project whose pages query
+    datasources.db (./data/app.db) had its migrations applied to a different
+    file — or to whatever local PostgreSQL answered.
+    """
+
+    def __init__(self, project_path: Path = None, datasource: str = None):
         self.project_path = project_path or Path.cwd()
+        self.datasource = datasource
         self._conn = None
         self._db_type = None
 
     def connect(self) -> Any:
-        """
-        Connect to database with automatic failover.
-        Tries PostgreSQL first, falls back to SQLite.
-        """
-        # Try to load database config from quantum.config.yaml
-        config = self._load_config()
-
-        # Try PostgreSQL
-        if self._try_postgres(config):
+        nome, config = self._datasource_config()
+        driver = str(config.get('driver', '')).lower()
+        if driver == 'sqlite':
+            import sqlite3
+            caminho = Path(config.get('database') or '')
+            if not config.get('database'):
+                raise MigrationError(f"datasource '{nome}' (sqlite) has no database: path")
+            if not caminho.is_absolute():
+                caminho = self.project_path / caminho
+            caminho.parent.mkdir(parents=True, exist_ok=True)
+            self._conn = sqlite3.connect(str(caminho))
+            self._db_type = 'sqlite'
+            logger.info("Migrating datasource %s (SQLite at %s)", nome, caminho)
             return self._conn
-
-        # Fallback to SQLite
-        logger.warning("PostgreSQL unavailable, falling back to SQLite")
-        if self._try_sqlite(config):
+        if driver in ('postgres', 'postgresql'):
+            try:
+                import psycopg2
+            except ImportError as exc:
+                raise MigrationError("datasource '%s' is PostgreSQL: pip install psycopg2-binary" % nome) from exc
+            self._conn = psycopg2.connect(
+                host=config.get('host', 'localhost'), port=int(config.get('port', 5432)),
+                dbname=config.get('database'), user=config.get('username') or config.get('user'),
+                password=config.get('password', ''), connect_timeout=5)
+            self._db_type = 'postgres'
+            logger.info("Migrating datasource %s (PostgreSQL %s)", nome, config.get('database'))
             return self._conn
+        raise MigrationError(f"datasource '{nome}': driver {driver!r} is not supported by quantum migrate "
+                             f"(use sqlite or postgres)")
 
-        raise MigrationError("Could not connect to any database")
-
-    def _load_config(self) -> Dict:
-        """Load database configuration from quantum.config.yaml"""
+    def _datasource_config(self):
         config_path = self.project_path / "quantum.config.yaml"
-        if not config_path.exists():
-            return {}
-
-        try:
+        datasources = {}
+        if config_path.exists():
             import yaml
-            with open(config_path) as f:
-                config = yaml.safe_load(f) or {}
-            return config.get('database', {})
-        except Exception as e:
-            logger.warning(f"Could not load config: {e}")
-            return {}
-
-    def _try_postgres(self, config: Dict) -> bool:
-        """Try to connect to PostgreSQL"""
-        try:
-            import psycopg2
-
-            # Get connection params from config or environment
-            host = config.get('host') or os.environ.get('QUANTUM_DB_HOST', 'localhost')
-            port = config.get('port') or os.environ.get('QUANTUM_DB_PORT', '5432')
-            database = config.get('database') or os.environ.get('QUANTUM_DB_NAME', 'quantum')
-            user = config.get('user') or os.environ.get('QUANTUM_DB_USER', 'postgres')
-            password = config.get('password') or os.environ.get('QUANTUM_DB_PASSWORD', '')
-
-            self._conn = psycopg2.connect(
-                host=host,
-                port=int(port),
-                database=database,
-                user=user,
-                password=password,
-                connect_timeout=5
-            )
-            self._db_type = 'postgres'
-            logger.info(f"Connected to PostgreSQL at {host}:{port}/{database}")
-            return True
-
-        except ImportError:
-            logger.debug("psycopg2 not installed")
-            return False
-        except Exception as e:
-            logger.debug(f"PostgreSQL connection failed: {e}")
-            return False
-
-    def _try_sqlite(self, config: Dict) -> bool:
-        """Try to connect to SQLite"""
-        try:
-            import sqlite3
-
-            db_path = config.get('sqlite_path') or self.project_path / "data" / "quantum.db"
-            db_path = Path(db_path)
-            db_path.parent.mkdir(parents=True, exist_ok=True)
-
-            self._conn = sqlite3.connect(str(db_path))
-            self._db_type = 'sqlite'
-            logger.info(f"Connected to SQLite at {db_path}")
-            return True
-
-        except Exception as e:
-            logger.error(f"SQLite connection failed: {e}")
-            return False
+            from quantum.core.config_env import expand_env
+            with open(config_path, encoding='utf-8') as f:
+                datasources = (expand_env(yaml.safe_load(f) or {}).get('datasources') or {})
+        if not datasources:
+            raise MigrationError(
+                "quantum.config.yaml declares no datasources. Add one, for example:\n"
+                "  datasources:\n    db:\n      driver: sqlite\n      database: ./data/app.db")
+        if self.datasource:
+            if self.datasource not in datasources:
+                raise MigrationError(f"no datasource '{self.datasource}'; declared: {', '.join(datasources)}")
+            return self.datasource, datasources[self.datasource]
+        if len(datasources) > 1:
+            raise MigrationError(f"several datasources are declared ({', '.join(datasources)}); "
+                                 f"choose one with --datasource")
+        nome = next(iter(datasources))
+        return nome, datasources[nome]
+
+    def _ensure_connected(self):
+        if self._conn is None:
+            self.connect()
 
     @property
     def db_type(self) -> str:
@@ -163,10 +144,10 @@ class MigrationRunner:
 
     MIGRATIONS_TABLE = "_migrations"
 
-    def __init__(self, project_path: Path = None):
+    def __init__(self, project_path: Path = None, datasource: str = None):
         self.project_path = project_path or Path.cwd()
         self.migrations_dir = self.project_path / "migrations"
-        self.db = DatabaseConnection(self.project_path)
+        self.db = DatabaseConnection(self.project_path, datasource)
 
     def _ensure_migrations_table(self):
         """Create migrations tracking table if it doesn't exist"""

{quantum_framework-0.10.0 → quantum_framework-0.12.0}/quantum/cli/runner.py

@@ -25,7 +25,6 @@ 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.web_server import QuantumWebServer
-from quantum.runtime.api_server import QuantumAPIServer
 
 # Import deploy commands (lazy load to avoid import errors if requests not installed)
 def _get_deploy_module():
@@ -77,12 +76,15 @@ def load_config(config_path: str = 'quantum.config.yaml') -> dict:
     so `datasources:` declared in quantum.config.yaml were never seen and
     every q:query fell through to the optional Quantum Admin API.
     """
+    from quantum.core.config_env import ConfigEnvError, expand_env
     try:
         import yaml
         path = Path(config_path)
         if path.exists():
             with open(path, 'r', encoding='utf-8') as fh:
-                return yaml.safe_load(fh) or {}
+                return expand_env(yaml.safe_load(fh) or {})
+    except ConfigEnvError:
+        raise                   # CFG-1: never run with a half-read config
     except Exception as exc:
         print(f"[WARN] Could not read {config_path}: {exc}")
     return {}
@@ -187,10 +189,6 @@ class QuantumRunner:
         elif app.app_type == 'ui':
             target = getattr(self, '_ui_target', 'html')
             return self._build_ui(app, target, debug)
-        elif app.app_type == 'html':
-            return self._start_web_server(app)
-        elif app.app_type in ('microservices', 'api'):
-            return self._start_api_server(app)
         else:
             print(f"[ERROR] Application type '{app.app_type}' not supported")
             return 1
@@ -271,32 +269,6 @@ class QuantumRunner:
         # TODO: Implement real job execution
         print("[SUCCESS] Job executed successfully")
         return 0
-    
-    def _start_web_server(self, app: ApplicationNode) -> int:
-        """Start web server"""
-        try:
-            server = QuantumWebServer(port=8080)
-            server.configure_from_ast(app)
-            # Propagate the server's exit code: it returns non-zero when the
-            # port is taken or the bind fails, and swallowing that made
-            # `quantum run` report success with nothing listening.
-            return server.start() or 0
-        except Exception as e:
-            print(f"[ERROR] Web server error: {e}")
-            return 1
-    
-    def _start_api_server(self, app: ApplicationNode) -> int:
-        """Start API server"""
-        try:
-            server = QuantumAPIServer(port=8080)
-            server.configure_from_ast(app)
-            # Propagate the server's exit code: it returns non-zero when the
-            # port is taken or the bind fails, and swallowing that made
-            # `quantum run` report success with nothing listening.
-            return server.start() or 0
-        except Exception as e:
-            print(f"[ERROR] API server error: {e}")
-            return 1
 
 
 def main():
@@ -308,8 +280,7 @@ def main():
 Examples:
   quantum start                    # Start web server (magic!)
   quantum run hello.q              # Execute component
-  quantum run webapp.q             # Start web server from .q file
-  quantum run api.q                # Start API server
+  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
@@ -360,6 +331,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()
 
@@ -387,6 +362,7 @@ Examples:
 
     # Migration commands
     migrate_parser = subparsers.add_parser('migrate', help='Database migration commands')
+    migrate_parser.add_argument('--datasource', help='Datasource from quantum.config.yaml (default: the only one declared)')
     migrate_subparsers = migrate_parser.add_subparsers(dest='migrate_command')
 
     migrate_subparsers.add_parser('status', help='Show migration status')
@@ -421,6 +397,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
@@ -491,7 +471,7 @@ Examples:
         MigrationRunner = result
 
         try:
-            runner = MigrationRunner()
+            runner = MigrationRunner(datasource=getattr(args, 'datasource', None))
 
             if args.migrate_command == 'status':
                 import json

{quantum_framework-0.10.0 → quantum_framework-0.12.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)
@@ -1919,6 +1920,7 @@ class DataNode(QuantumNode):
 
         # Result metadata
         self.result: Optional[str] = None
+        self.on_error: str = 'fail'   # DATA-4: 'fail' or 'continue'
 
         # Child elements
         self.columns: List[ColumnNode] = []

quantum_framework-0.12.0/quantum/core/config_env.py

@@ -0,0 +1,54 @@
+"""
+`${VAR}` in quantum.config.yaml (CFG-1).
+
+    datasources:
+      db:
+        password: ${DB_PASSWORD}
+        host: ${DB_HOST:-localhost}
+        port: ${DB_PORT:5432}      # ':' works as well as ':-'
+
+A config file is the place people put secrets by reference, and every loader
+used to read `${DB_PASSWORD}` as the literal password. There were four loaders
+(the CLI, the web server, the service container, migrations); they all go
+through expand_env now.
+"""
+
+import os
+import re
+from typing import Any
+
+_REFERENCE = re.compile(r'\$\$|\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-?([^}]*))?\}')
+
+
+class ConfigEnvError(ValueError):
+    """A `${VAR}` with no value and no default."""
+
+
+def expand_env(value: Any, path: str = '') -> Any:
+    """Replace `${NAME}` and `${NAME:-default}` in every string of a loaded config.
+
+    `$$` is a literal `$`. A variable that is not set and has no default is an
+    error naming the variable and where it was used — an empty password or
+    database path would otherwise fail much later, somewhere else.
+    """
+    if isinstance(value, dict):
+        return {k: expand_env(v, f'{path}.{k}' if path else str(k)) for k, v in value.items()}
+    if isinstance(value, list):
+        return [expand_env(v, f'{path}[{i}]') for i, v in enumerate(value)]
+    if not isinstance(value, str) or '$' not in value:
+        return value
+
+    def substitute(match):
+        if match.group(0) == '$$':
+            return '$'
+        name, default = match.group(1), match.group(2)
+        if name in os.environ:
+            return os.environ[name]
+        if default is not None:
+            return default
+        raise ConfigEnvError(
+            f"quantum.config.yaml: {path or 'value'} uses ${{{name}}}, but the "
+            f"environment variable {name} is not set. Set it, or give a default: "
+            f"${{{name}:-value}}")
+
+    return _REFERENCE.sub(substitute, value)