quickscale-cli 0.76.0__tar.gz → 0.83.0__tar.gz

{quickscale_cli-0.76.0 → quickscale_cli-0.83.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: quickscale-cli
-Version: 0.76.0
+Version: 0.83.0
 Summary: Command-line interface for QuickScale Django project generator
 License-Expression: Apache-2.0
 Keywords: django,cli,project-generator,saas
 Author: Experto AI
 Author-email: victor@experto.ai
-Requires-Python: >=3.14,<4.0
+Requires-Python: >=3.12,<3.14
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 6.0
 Requires-Dist: click (>=8.3.1,<9.0.0)
-Requires-Dist: quickscale-core (>=0.76.0,<0.77.0)
+Requires-Dist: quickscale-core (>=0.83.0,<0.84.0)
 Project-URL: Documentation, https://github.com/Experto-AI/quickscale/tree/main/docs
 Project-URL: Homepage, https://github.com/Experto-AI/quickscale
 Project-URL: Repository, https://github.com/Experto-AI/quickscale
@@ -24,11 +24,12 @@ Description-Content-Type: text/markdown
 
 Command-line interface package for QuickScale.
 
-This package exposes the `quickscale` command used to plan, apply, inspect, and operate generated projects.
+This package exposes the `quickscale` command used to plan, apply, inspect, recover, and operate generated projects.
 
 ## Command groups
 
 - Project lifecycle: `plan`, `apply`, `status`, `remove`
+- Disaster recovery & promotion: `dr capture`, `dr plan`, `dr execute`, `dr report`
 - Local development: `up`, `down`, `ps`, `logs`, `shell`, `manage`
 - Deployment: `deploy`
 - Module workflows: `update`, `push`

{quickscale_cli-0.76.0 → quickscale_cli-0.83.0}/README.md

@@ -2,11 +2,12 @@
 
 Command-line interface package for QuickScale.
 
-This package exposes the `quickscale` command used to plan, apply, inspect, and operate generated projects.
+This package exposes the `quickscale` command used to plan, apply, inspect, recover, and operate generated projects.
 
 ## Command groups
 
 - Project lifecycle: `plan`, `apply`, `status`, `remove`
+- Disaster recovery & promotion: `dr capture`, `dr plan`, `dr execute`, `dr report`
 - Local development: `up`, `down`, `ps`, `logs`, `shell`, `manage`
 - Deployment: `deploy`
 - Module workflows: `update`, `push`

{quickscale_cli-0.76.0 → quickscale_cli-0.83.0}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "quickscale-cli"
-version = "0.76.0"
+version = "0.83.0"
 description = "Command-line interface for QuickScale Django project generator"
-requires-python = ">=3.14,<4.0"
+requires-python = ">=3.12,<3.14"
 readme = "README.md"
 license = "Apache-2.0"
 authors = [{name = "Experto AI", email = "victor@experto.ai"}]
@@ -29,9 +29,9 @@ quickscale = "quickscale_cli.main:cli"
 packages = [{include = "quickscale_cli", from = "src"}]
 
 [tool.poetry.dependencies]
-python = "^3.14"
+python = ">=3.12,<3.14"
 click = "^8.3.1"
-quickscale-core = "^0.76.0"
+quickscale-core = "^0.83.0"
 
 [tool.poetry.group.dev.dependencies]
 # Dev dependencies centralized in root pyproject.toml
@@ -43,6 +43,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]

{quickscale_cli-0.76.0 → quickscale_cli-0.83.0}/src/quickscale_cli/__init__.py

@@ -7,15 +7,22 @@ stays in sync with other packages when the release is bumped in one place.
 
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 
 __author__ = "Experto AI"
 __email__ = "victor@experto.ai"
 
+logger = logging.getLogger(__name__)
+
 # Prefer an embedded package-level `_version.py` if it exists (build step).
 try:
     from ._version import __version__
-except Exception:
+except Exception as exc:
+    logger.warning(
+        "Failed to import embedded CLI version; falling back to VERSION file or 0.0.0: %s",
+        exc,
+    )
     _root = Path(__file__).resolve().parents[3]
     _version_file = _root / "VERSION"
     if _version_file.exists():

{quickscale_cli-0.76.0 → quickscale_cli-0.83.0}/src/quickscale_cli/_version.py

@@ -1,2 +1,2 @@
 # Auto-generated by scripts/version_tool.sh
-__version__ = "0.76.0"
+__version__ = "0.83.0"

quickscale_cli-0.83.0/src/quickscale_cli/analytics_contract.py

@@ -0,0 +1,177 @@
+"""Shared analytics-module configuration helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+ANALYTICS_PROVIDER_POSTHOG = "posthog"
+ANALYTICS_PROVIDERS = (ANALYTICS_PROVIDER_POSTHOG,)
+
+DEFAULT_ANALYTICS_POSTHOG_API_KEY_ENV_VAR = "POSTHOG_API_KEY"
+DEFAULT_ANALYTICS_POSTHOG_HOST_ENV_VAR = "POSTHOG_HOST"
+
+ANALYTICS_POSTHOG_DEFAULT_HOST = "https://us.i.posthog.com"
+ANALYTICS_POSTHOG_EU_HOST = "https://eu.i.posthog.com"
+
+ANALYTICS_EVENT_PAGEVIEW = "$pageview"
+ANALYTICS_EVENT_FORM_SUBMIT = "form_submit"
+ANALYTICS_EVENT_SOCIAL_LINK_CLICK = "social_link_click"
+
+_ANALYTICS_ENV_VAR_NAME_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+
+def default_analytics_module_options() -> dict[str, Any]:
+    """Return the default planner/apply contract for analytics."""
+    return {
+        "enabled": True,
+        "provider": ANALYTICS_PROVIDER_POSTHOG,
+        "posthog_api_key_env_var": DEFAULT_ANALYTICS_POSTHOG_API_KEY_ENV_VAR,
+        "posthog_host_env_var": DEFAULT_ANALYTICS_POSTHOG_HOST_ENV_VAR,
+        "posthog_host": ANALYTICS_POSTHOG_DEFAULT_HOST,
+        "exclude_debug": True,
+        "exclude_staff": False,
+        "anonymous_by_default": True,
+    }
+
+
+def _normalize_provider(value: Any) -> str:
+    return str(value).strip().lower()
+
+
+def _normalize_posthog_host(value: Any) -> str:
+    candidate = str(value).strip()
+    if not candidate:
+        return ""
+    if not candidate.startswith(("http://", "https://")):
+        candidate = "https://" + candidate.lstrip("/")
+    return candidate.rstrip("/")
+
+
+def normalize_analytics_module_options(
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Return analytics options with normalized provider and host fields."""
+    normalized = dict(options or {})
+
+    if "provider" in normalized:
+        normalized["provider"] = _normalize_provider(normalized["provider"])
+
+    for option_name in ("posthog_api_key_env_var", "posthog_host_env_var"):
+        if option_name in normalized:
+            normalized[option_name] = str(normalized[option_name]).strip()
+
+    if "posthog_host" in normalized:
+        normalized["posthog_host"] = _normalize_posthog_host(normalized["posthog_host"])
+
+    return normalized
+
+
+def resolve_analytics_module_options(
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Merge analytics options with defaults and normalized overrides."""
+    resolved = default_analytics_module_options()
+    resolved.update(normalize_analytics_module_options(options))
+    resolved["provider"] = _normalize_provider(resolved["provider"])
+    resolved["posthog_api_key_env_var"] = str(
+        resolved["posthog_api_key_env_var"]
+    ).strip()
+    resolved["posthog_host_env_var"] = str(resolved["posthog_host_env_var"]).strip()
+    resolved["posthog_host"] = _normalize_posthog_host(resolved["posthog_host"])
+    return resolved
+
+
+def validate_analytics_env_var_reference(option_name: str, value: Any) -> str | None:
+    """Validate an analytics env-var reference field."""
+    candidate = str(value).strip()
+    if not candidate:
+        return None
+
+    qualified_option = f"modules.analytics.{option_name}"
+    if not _ANALYTICS_ENV_VAR_NAME_PATTERN.fullmatch(candidate):
+        return (
+            f"{qualified_option} must be an environment variable name matching "
+            "^[A-Z][A-Z0-9_]*$"
+        )
+    return None
+
+
+def _is_valid_posthog_host(value: str) -> bool:
+    candidate = value.strip()
+    if not candidate:
+        return False
+
+    parsed = urlsplit(candidate)
+    return parsed.scheme in {"http", "https"} and bool(parsed.netloc)
+
+
+def validate_analytics_module_options(options: Mapping[str, Any] | None) -> list[str]:
+    """Return validation issues for analytics module options."""
+    resolved = resolve_analytics_module_options(options)
+    issues: list[str] = []
+
+    provider = str(resolved.get("provider", "")).strip().lower()
+    if provider not in ANALYTICS_PROVIDERS:
+        issues.append(
+            "modules.analytics.provider must be one of: "
+            + ", ".join(ANALYTICS_PROVIDERS)
+        )
+
+    for option_name in ("posthog_api_key_env_var", "posthog_host_env_var"):
+        issue = validate_analytics_env_var_reference(
+            option_name,
+            resolved.get(option_name, ""),
+        )
+        if issue:
+            issues.append(issue)
+
+    if not _is_valid_posthog_host(str(resolved.get("posthog_host", ""))):
+        issues.append("modules.analytics.posthog_host must be an absolute http(s) URL")
+
+    for option_name in (
+        "enabled",
+        "exclude_debug",
+        "exclude_staff",
+        "anonymous_by_default",
+    ):
+        if not isinstance(resolved.get(option_name), bool):
+            issues.append(f"modules.analytics.{option_name} must be a boolean")
+
+    return issues
+
+
+def analytics_production_targeted(options: Mapping[str, Any] | None) -> bool:
+    """Return whether analytics is configured for live runtime capture."""
+    resolved = resolve_analytics_module_options(options)
+    if not bool(resolved.get("enabled", True)):
+        return False
+
+    api_key_env_var = str(resolved.get("posthog_api_key_env_var", "")).strip()
+    return not bool(
+        validate_analytics_env_var_reference(
+            "posthog_api_key_env_var",
+            api_key_env_var,
+        )
+    )
+
+
+__all__ = [
+    "ANALYTICS_EVENT_FORM_SUBMIT",
+    "ANALYTICS_EVENT_PAGEVIEW",
+    "ANALYTICS_EVENT_SOCIAL_LINK_CLICK",
+    "ANALYTICS_POSTHOG_DEFAULT_HOST",
+    "ANALYTICS_POSTHOG_EU_HOST",
+    "ANALYTICS_PROVIDER_POSTHOG",
+    "ANALYTICS_PROVIDERS",
+    "DEFAULT_ANALYTICS_POSTHOG_API_KEY_ENV_VAR",
+    "DEFAULT_ANALYTICS_POSTHOG_HOST_ENV_VAR",
+    "analytics_production_targeted",
+    "default_analytics_module_options",
+    "normalize_analytics_module_options",
+    "resolve_analytics_module_options",
+    "validate_analytics_env_var_reference",
+    "validate_analytics_module_options",
+]

quickscale_cli-0.83.0/src/quickscale_cli/auth_contract.py

@@ -0,0 +1,97 @@
+"""Shared auth-module configuration helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+AUTH_REGISTRATION_ENABLED_OPTION = "registration_enabled"
+AUTH_EMAIL_VERIFICATION_OPTION = "email_verification"
+AUTH_AUTHENTICATION_METHOD_OPTION = "authentication_method"
+AUTH_SESSION_COOKIE_AGE_OPTION = "session_cookie_age"
+
+AUTH_EMAIL_VERIFICATION_VALUES = ("none", "optional", "mandatory")
+AUTH_AUTHENTICATION_METHOD_VALUES = ("email", "username", "both")
+CANONICAL_AUTH_MODULE_OPTION_KEYS = frozenset(
+    {
+        AUTH_REGISTRATION_ENABLED_OPTION,
+        AUTH_EMAIL_VERIFICATION_OPTION,
+        AUTH_AUTHENTICATION_METHOD_OPTION,
+        AUTH_SESSION_COOKIE_AGE_OPTION,
+    }
+)
+
+LEGACY_AUTH_ALLOW_REGISTRATION_OPTION = "allow_registration"
+LEGACY_AUTH_SOCIAL_PROVIDERS_OPTION = "social_providers"
+
+
+def default_auth_module_options() -> dict[str, Any]:
+    """Return the default planner/apply contract for auth."""
+    return {
+        AUTH_REGISTRATION_ENABLED_OPTION: True,
+        AUTH_EMAIL_VERIFICATION_OPTION: "none",
+        AUTH_AUTHENTICATION_METHOD_OPTION: "email",
+        AUTH_SESSION_COOKIE_AGE_OPTION: 1209600,
+    }
+
+
+def format_auth_desired_config_contract() -> str:
+    """Return concise remediation text for canonical auth desired config."""
+    return "\n".join(
+        [
+            "Canonical auth keys/value shapes:",
+            "modules.auth.registration_enabled: true|false",
+            "modules.auth.email_verification: none|optional|mandatory",
+            "modules.auth.authentication_method: email|username|both",
+            "modules.auth.session_cookie_age: <positive integer seconds>  # optional",
+            (
+                "Remove legacy keys like modules.auth.allow_registration and "
+                "modules.auth.social_providers."
+            ),
+        ]
+    )
+
+
+def normalize_auth_module_options(
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Return auth options with legacy keys normalized or removed."""
+    normalized = dict(options or {})
+
+    if (
+        AUTH_REGISTRATION_ENABLED_OPTION not in normalized
+        and LEGACY_AUTH_ALLOW_REGISTRATION_OPTION in normalized
+    ):
+        normalized[AUTH_REGISTRATION_ENABLED_OPTION] = normalized[
+            LEGACY_AUTH_ALLOW_REGISTRATION_OPTION
+        ]
+
+    normalized.pop(LEGACY_AUTH_ALLOW_REGISTRATION_OPTION, None)
+    normalized.pop(LEGACY_AUTH_SOCIAL_PROVIDERS_OPTION, None)
+    return normalized
+
+
+def resolve_auth_module_options(
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Merge auth options with defaults and normalized overrides."""
+    resolved = default_auth_module_options()
+    resolved.update(normalize_auth_module_options(options))
+    return resolved
+
+
+__all__ = [
+    "AUTH_AUTHENTICATION_METHOD_OPTION",
+    "AUTH_AUTHENTICATION_METHOD_VALUES",
+    "AUTH_EMAIL_VERIFICATION_OPTION",
+    "AUTH_EMAIL_VERIFICATION_VALUES",
+    "AUTH_REGISTRATION_ENABLED_OPTION",
+    "AUTH_SESSION_COOKIE_AGE_OPTION",
+    "CANONICAL_AUTH_MODULE_OPTION_KEYS",
+    "LEGACY_AUTH_ALLOW_REGISTRATION_OPTION",
+    "LEGACY_AUTH_SOCIAL_PROVIDERS_OPTION",
+    "default_auth_module_options",
+    "format_auth_desired_config_contract",
+    "normalize_auth_module_options",
+    "resolve_auth_module_options",
+]

quickscale_cli-0.83.0/src/quickscale_cli/backups_contract.py

@@ -0,0 +1,137 @@
+"""Shared module configuration helpers.
+
+This module centralizes the non-secret configuration contract used by the
+planner, apply flow, and state persistence for module compatibility helpers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import re
+from typing import Any
+
+from quickscale_cli.analytics_contract import normalize_analytics_module_options
+from quickscale_cli.auth_contract import normalize_auth_module_options
+from quickscale_cli.crm_contract import normalize_crm_module_options
+from quickscale_cli.notifications_contract import normalize_notifications_module_options
+from quickscale_cli.social_contract import normalize_social_module_options
+
+DEFAULT_BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR = "QUICKSCALE_BACKUPS_REMOTE_ACCESS_KEY_ID"
+DEFAULT_BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR = (
+    "QUICKSCALE_BACKUPS_REMOTE_SECRET_ACCESS_KEY"
+)
+
+BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR_OPTION = "remote_access_key_id_env_var"
+BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR_OPTION = "remote_secret_access_key_env_var"
+
+_LEGACY_BACKUPS_SECRET_OPTIONS = {
+    "remote_access_key_id": DEFAULT_BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR,
+    "remote_secret_access_key": DEFAULT_BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR,
+}
+
+_BACKUPS_ENV_VAR_NAME_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
+_LIKELY_AWS_ACCESS_KEY_ID_PATTERN = re.compile(r"^(?:AKIA|ASIA)[A-Z0-9]{16}$")
+
+
+def normalize_backups_module_options(
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Return backups options with legacy raw-secret keys removed.
+
+    Legacy raw credential values are converted into conventional environment-variable
+    references so downstream persistence layers never re-store the secret values.
+    """
+    normalized = dict(options or {})
+
+    legacy_access_key_id = str(normalized.pop("remote_access_key_id", "")).strip()
+    legacy_secret_access_key = str(
+        normalized.pop("remote_secret_access_key", "")
+    ).strip()
+
+    access_key_env_var = str(
+        normalized.get(BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR_OPTION, "")
+    ).strip()
+    secret_access_key_env_var = str(
+        normalized.get(BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR_OPTION, "")
+    ).strip()
+
+    if legacy_access_key_id and not access_key_env_var:
+        normalized[BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR_OPTION] = (
+            DEFAULT_BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR
+        )
+    if legacy_secret_access_key and not secret_access_key_env_var:
+        normalized[BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR_OPTION] = (
+            DEFAULT_BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR
+        )
+
+    return normalized
+
+
+def has_legacy_backups_secret_values(options: Mapping[str, Any] | None) -> bool:
+    """Return whether backups options still include legacy raw-secret keys."""
+    if not options:
+        return False
+
+    for option_name in _LEGACY_BACKUPS_SECRET_OPTIONS:
+        if str(options.get(option_name, "")).strip():
+            return True
+    return False
+
+
+def validate_backups_env_var_reference(option_name: str, value: Any) -> str | None:
+    """Validate a backups env-var reference field.
+
+    Returns an actionable error string when the value is not a safe environment
+    variable name or appears to be a literal credential value.
+    """
+    candidate = str(value).strip()
+    if not candidate:
+        return None
+
+    qualified_option = f"modules.backups.{option_name}"
+    if not _BACKUPS_ENV_VAR_NAME_PATTERN.fullmatch(candidate):
+        return (
+            f"{qualified_option} must be an environment variable name matching "
+            "^[A-Z][A-Z0-9_]*$"
+        )
+
+    if option_name == BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR_OPTION:
+        if _LIKELY_AWS_ACCESS_KEY_ID_PATTERN.fullmatch(candidate):
+            return (
+                f"{qualified_option} must reference an environment variable name, "
+                "not a literal AWS access key id"
+            )
+
+    return None
+
+
+def sanitize_module_options(
+    module_name: str,
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Return module options safe for config/state persistence."""
+    if module_name == "analytics":
+        return normalize_analytics_module_options(options)
+    if module_name == "auth":
+        return normalize_auth_module_options(options)
+    if module_name == "backups":
+        return normalize_backups_module_options(options)
+    if module_name == "crm":
+        return normalize_crm_module_options(options)
+    if module_name == "notifications":
+        return normalize_notifications_module_options(options)
+    if module_name == "social":
+        return normalize_social_module_options(dict(options or {}))
+    return dict(options or {})
+
+
+__all__ = [
+    "BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR_OPTION",
+    "BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR_OPTION",
+    "DEFAULT_BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR",
+    "DEFAULT_BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR",
+    "has_legacy_backups_secret_values",
+    "normalize_backups_module_options",
+    "sanitize_module_options",
+    "validate_backups_env_var_reference",
+]