quickscale-cli 0.84.0__tar.gz → 0.86.0__tar.gz

quickscale_cli-0.86.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: quickscale-cli
+Version: 0.86.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.13,<3.15
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+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.86.0,<0.87.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
+Description-Content-Type: text/markdown
+
+# quickscale-cli
+
+Command-line interface for the [QuickScale](https://github.com/Experto-AI/quickscale) Django project generator.
+
+## Installation
+
+```bash
+pip install quickscale-cli
+```
+
+Or install the full bundle:
+
+```bash
+pip install quickscale
+```
+
+## Documentation
+
+See the [main repository README](../README.md) and [docs/](../docs/) for full documentation.
+

quickscale_cli-0.86.0/README.md

@@ -0,0 +1,19 @@
+# quickscale-cli
+
+Command-line interface for the [QuickScale](https://github.com/Experto-AI/quickscale) Django project generator.
+
+## Installation
+
+```bash
+pip install quickscale-cli
+```
+
+Or install the full bundle:
+
+```bash
+pip install quickscale
+```
+
+## Documentation
+
+See the [main repository README](../README.md) and [docs/](../docs/) for full documentation.

{quickscale_cli-0.84.0 → quickscale_cli-0.86.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quickscale-cli"
-version = "0.84.0"
+version = "0.86.0"
 description = "Command-line interface for QuickScale Django project generator"
 requires-python = ">=3.13,<3.15"
 readme = "README.md"
@@ -32,7 +32,7 @@ packages = [{include = "quickscale_cli", from = "src"}]
 [tool.poetry.dependencies]
 python = ">=3.13,<3.15"
 click = "^8.3.1"
-quickscale-core = "^0.84.0"
+quickscale-core = "^0.86.0"
 
 [tool.poetry.group.dev.dependencies]
 # Dev dependencies centralized in root pyproject.toml

{quickscale_cli-0.84.0 → quickscale_cli-0.86.0}/src/quickscale_cli/_version.py

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

{quickscale_cli-0.84.0 → quickscale_cli-0.86.0}/src/quickscale_cli/backups_contract.py

@@ -10,6 +10,7 @@ from collections.abc import Mapping
 import re
 from typing import Any
 
+from quickscale_cli.billing_contract import normalize_billing_module_options
 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
@@ -116,6 +117,8 @@ def sanitize_module_options(
         return normalize_auth_module_options(options)
     if module_name == "backups":
         return normalize_backups_module_options(options)
+    if module_name == "billing":
+        return normalize_billing_module_options(options)
     if module_name == "crm":
         return normalize_crm_module_options(options)
     if module_name == "notifications":

quickscale_cli-0.86.0/src/quickscale_cli/billing_contract.py

@@ -0,0 +1,183 @@
+"""Shared billing-module configuration helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import re
+from typing import Any
+
+DEFAULT_BILLING_PUBLISHABLE_KEY_ENV_VAR = "STRIPE_PUBLISHABLE_KEY"
+DEFAULT_BILLING_SECRET_KEY_ENV_VAR = "STRIPE_SECRET_KEY"
+DEFAULT_BILLING_WEBHOOK_SECRET_ENV_VAR = "QUICKSCALE_BILLING_WEBHOOK_SECRET"
+DEFAULT_BILLING_CURRENCY = "usd"
+
+BILLING_ENV_VAR_OPTION_NAMES = (
+    "publishable_key_env_var",
+    "secret_key_env_var",
+    "webhook_secret_env_var",
+)
+BILLING_MODULE_OPTION_KEYS = frozenset(
+    {
+        "enabled",
+        *BILLING_ENV_VAR_OPTION_NAMES,
+        "billing_currency",
+    }
+)
+BILLING_SUPPORTED_CURRENCIES = (
+    "aud",
+    "brl",
+    "cad",
+    "chf",
+    "czk",
+    "dkk",
+    "eur",
+    "gbp",
+    "hkd",
+    "huf",
+    "inr",
+    "jpy",
+    "mxn",
+    "myr",
+    "nok",
+    "nzd",
+    "php",
+    "pln",
+    "ron",
+    "sek",
+    "sgd",
+    "thb",
+    "try",
+    "usd",
+    "zar",
+)
+
+_BILLING_ENV_VAR_NAME_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+
+def default_billing_module_options() -> dict[str, Any]:
+    """Return the default planner/apply contract for billing."""
+    return {
+        "enabled": True,
+        "publishable_key_env_var": DEFAULT_BILLING_PUBLISHABLE_KEY_ENV_VAR,
+        "secret_key_env_var": DEFAULT_BILLING_SECRET_KEY_ENV_VAR,
+        "webhook_secret_env_var": DEFAULT_BILLING_WEBHOOK_SECRET_ENV_VAR,
+        "billing_currency": DEFAULT_BILLING_CURRENCY,
+    }
+
+
+def normalize_billing_module_options(
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Return billing options with normalized env-var and currency values."""
+    normalized = dict(options or {})
+
+    for option_name in BILLING_ENV_VAR_OPTION_NAMES:
+        if option_name in normalized:
+            normalized[option_name] = str(normalized[option_name]).strip()
+
+    if "billing_currency" in normalized:
+        normalized["billing_currency"] = (
+            str(normalized["billing_currency"]).strip().lower()
+        )
+
+    return normalized
+
+
+def resolve_billing_module_options(
+    options: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Merge billing options with defaults and normalized overrides."""
+    resolved = default_billing_module_options()
+    resolved.update(normalize_billing_module_options(options))
+    for option_name in BILLING_ENV_VAR_OPTION_NAMES:
+        resolved[option_name] = str(resolved[option_name]).strip()
+    resolved["billing_currency"] = str(resolved["billing_currency"]).strip().lower()
+    return resolved
+
+
+def validate_billing_env_var_reference(option_name: str, value: Any) -> str | None:
+    """Validate a billing env-var reference field."""
+    candidate = str(value).strip()
+    if not candidate:
+        return None
+
+    qualified_option = f"modules.billing.{option_name}"
+    if not _BILLING_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 validate_billing_currency(value: Any) -> str | None:
+    """Validate the configured billing currency code."""
+    candidate = str(value).strip().lower()
+    if not candidate:
+        return "modules.billing.billing_currency cannot be blank"
+
+    if candidate not in BILLING_SUPPORTED_CURRENCIES:
+        return (
+            "modules.billing.billing_currency must be one of the supported "
+            "QuickScale billing currency codes: "
+            + ", ".join(BILLING_SUPPORTED_CURRENCIES)
+        )
+    return None
+
+
+def validate_billing_module_options(options: Mapping[str, Any] | None) -> list[str]:
+    """Return validation issues for billing module options."""
+    resolved = resolve_billing_module_options(options)
+    issues: list[str] = []
+
+    if not isinstance(resolved.get("enabled", True), bool):
+        issues.append("modules.billing.enabled must be a boolean")
+
+    for option_name in BILLING_ENV_VAR_OPTION_NAMES:
+        issue = validate_billing_env_var_reference(
+            option_name,
+            resolved.get(option_name, ""),
+        )
+        if issue:
+            issues.append(issue)
+
+    currency_issue = validate_billing_currency(resolved.get("billing_currency", ""))
+    if currency_issue:
+        issues.append(currency_issue)
+
+    return issues
+
+
+def billing_production_targeted(options: Mapping[str, Any] | None) -> bool:
+    """Return whether billing is configured for live runtime ownership."""
+    resolved = resolve_billing_module_options(options)
+    if not bool(resolved.get("enabled", True)):
+        return False
+
+    if validate_billing_currency(resolved.get("billing_currency", "")):
+        return False
+
+    for option_name in BILLING_ENV_VAR_OPTION_NAMES:
+        candidate = str(resolved.get(option_name, "")).strip()
+        if not candidate or validate_billing_env_var_reference(option_name, candidate):
+            return False
+
+    return True
+
+
+__all__ = [
+    "BILLING_ENV_VAR_OPTION_NAMES",
+    "BILLING_MODULE_OPTION_KEYS",
+    "BILLING_SUPPORTED_CURRENCIES",
+    "DEFAULT_BILLING_CURRENCY",
+    "DEFAULT_BILLING_PUBLISHABLE_KEY_ENV_VAR",
+    "DEFAULT_BILLING_SECRET_KEY_ENV_VAR",
+    "DEFAULT_BILLING_WEBHOOK_SECRET_ENV_VAR",
+    "billing_production_targeted",
+    "default_billing_module_options",
+    "normalize_billing_module_options",
+    "resolve_billing_module_options",
+    "validate_billing_currency",
+    "validate_billing_env_var_reference",
+    "validate_billing_module_options",
+]

{quickscale_cli-0.84.0 → quickscale_cli-0.86.0}/src/quickscale_cli/commands/apply_command.py

@@ -21,6 +21,14 @@ from quickscale_cli.analytics_contract import (
     resolve_analytics_module_options,
     validate_analytics_module_options,
 )
+from quickscale_cli.billing_contract import (
+    DEFAULT_BILLING_CURRENCY,
+    DEFAULT_BILLING_PUBLISHABLE_KEY_ENV_VAR,
+    DEFAULT_BILLING_SECRET_KEY_ENV_VAR,
+    DEFAULT_BILLING_WEBHOOK_SECRET_ENV_VAR,
+    resolve_billing_module_options,
+    validate_billing_module_options,
+)
 from quickscale_cli.backups_contract import (
     BACKUPS_REMOTE_ACCESS_KEY_ID_ENV_VAR_OPTION,
     BACKUPS_REMOTE_SECRET_ACCESS_KEY_ENV_VAR_OPTION,
@@ -39,6 +47,9 @@ from quickscale_cli.notifications_contract import (
     resolve_notifications_module_options,
     validate_notifications_module_options,
 )
+from quickscale_cli.commands.implied_module_defaults import (
+    get_implied_module_default_configs,
+)
 from quickscale_cli.module_catalog import (
     find_not_ready_modules,
     get_module_readiness_reason,
@@ -63,6 +74,7 @@ from quickscale_cli.utils.module_dependency_sync import (
 from quickscale_cli.utils.module_wiring_manager import regenerate_managed_wiring
 from quickscale_cli.schema.config_schema import (
     ConfigValidationError,
+    ModuleConfig,
     QuickScaleConfig,
     generate_yaml,
     validate_config,
@@ -470,13 +482,13 @@ def _start_docker(
 
 
 def _abort_for_not_ready_modules(module_names: list[str], *, source: str) -> None:
-    """Abort apply when placeholder modules appear in config or applied state."""
+    """Abort apply when non-public-ready modules appear in config or applied state."""
     not_ready = find_not_ready_modules(module_names)
     if not not_ready:
         return
 
     click.secho(
-        f"\n❌ {source} references placeholder modules that are not ready:",
+        f"\n❌ {source} references modules that are not public-ready:",
         fg="red",
         err=True,
         bold=True,
@@ -680,6 +692,21 @@ def _sanitize_loaded_module_configs(qs_config: QuickScaleConfig) -> list[str]:
     return sanitized_modules
 
 
+def _materialize_implied_module_configs(qs_config: QuickScaleConfig) -> list[str]:
+    """Add explicit module config blocks required by selected modules."""
+    implied_configs = get_implied_module_default_configs(qs_config.modules.keys())
+    if not implied_configs:
+        return []
+
+    for module_name, options in implied_configs.items():
+        qs_config.modules[module_name] = ModuleConfig(
+            name=module_name,
+            options=sanitize_module_options(module_name, options),
+        )
+
+    return list(implied_configs.keys())
+
+
 def _load_and_validate_config(config_path: Path) -> QuickScaleConfig:
     """Load and validate configuration from file."""
     if not config_path.exists():
@@ -698,16 +725,24 @@ def _load_and_validate_config(config_path: Path) -> QuickScaleConfig:
         qs_config = validate_config(yaml_content)
         original_data = yaml.safe_load(yaml_content) or {}
         original_modules = original_data.get("modules") or {}
-        _sanitize_loaded_module_configs(qs_config)
+        sanitized_modules = _sanitize_loaded_module_configs(qs_config)
+        implied_modules = _materialize_implied_module_configs(qs_config)
         normalized_yaml = generate_yaml(qs_config)
         normalized_data = yaml.safe_load(normalized_yaml) or {}
         normalized_modules = normalized_data.get("modules") or {}
         if normalized_modules != original_modules:
             config_path.write_text(normalized_yaml)
-            click.secho(
-                "✅ Sanitized legacy module config keys in quickscale.yml",
-                fg="green",
-            )
+            if sanitized_modules:
+                click.secho(
+                    "✅ Sanitized legacy module config keys in quickscale.yml",
+                    fg="green",
+                )
+            if implied_modules:
+                click.secho(
+                    "✅ Added implied module config to quickscale.yml: "
+                    + ", ".join(implied_modules),
+                    fg="green",
+                )
         _validate_module_prerequisites(qs_config)
         return qs_config
     except ConfigValidationError as e:
@@ -720,6 +755,64 @@ def _load_and_validate_config(config_path: Path) -> QuickScaleConfig:
 
 def _validate_module_prerequisites(qs_config: QuickScaleConfig) -> None:
     """Validate actionable module-specific prerequisites before apply proceeds."""
+    if "orgs" in qs_config.modules and "auth" not in qs_config.modules:
+        click.secho(
+            "\n❌ Organizations requires the auth module before apply can continue:",
+            fg="red",
+            err=True,
+        )
+        click.echo(
+            "  • Add 'auth' under modules in quickscale.yml before applying orgs.",
+            err=True,
+        )
+        click.echo(
+            "\n💡 Organizations relies on the QuickScale auth login flow and "
+            "django-allauth account adapter hooks. Re-run 'quickscale plan "
+            "--reconfigure --configure-modules' or edit quickscale.yml to add "
+            "auth, then re-run 'quickscale apply'.",
+            err=True,
+        )
+        raise click.Abort()
+
+    billing_config = qs_config.modules.get("billing")
+    if billing_config is not None:
+        billing_issues = validate_billing_module_options(billing_config.options or {})
+        if billing_issues:
+            click.secho(
+                "\n❌ Billing module configuration is incomplete for apply:",
+                fg="red",
+                err=True,
+            )
+            for issue in billing_issues:
+                click.echo(f"  • {issue}", err=True)
+            click.echo(
+                "\n💡 Re-run 'quickscale plan --reconfigure --configure-modules' or "
+                "edit quickscale.yml to correct the billing option values. "
+                "Billing apply requires valid env-var references and a supported "
+                "currency code.",
+                err=True,
+            )
+            raise click.Abort()
+
+        if "auth" not in qs_config.modules:
+            click.secho(
+                "\n❌ Billing requires the auth module before apply can continue:",
+                fg="red",
+                err=True,
+            )
+            click.echo(
+                "  • Add 'auth' under modules in quickscale.yml before applying billing.",
+                err=True,
+            )
+            click.echo(
+                "\n💡 Billing relies on the QuickScale auth login flow and "
+                "AUTH_USER_MODEL. Re-run 'quickscale plan --reconfigure "
+                "--configure-modules' or edit quickscale.yml to add auth, then "
+                "re-run 'quickscale apply'.",
+                err=True,
+            )
+            raise click.Abort()
+
     _abort_for_not_ready_modules(
         list(qs_config.modules.keys()), source="quickscale.yml"
     )
@@ -1004,6 +1097,95 @@ def _sync_analytics_env_example(
     return True
 
 
+def _render_billing_env_example_block(
+    options: Mapping[str, Any] | None,
+) -> str:
+    """Render the managed billing section for `.env.example`."""
+    resolved = resolve_billing_module_options(options)
+    publishable_key_env_var = str(
+        resolved.get(
+            "publishable_key_env_var",
+            DEFAULT_BILLING_PUBLISHABLE_KEY_ENV_VAR,
+        )
+        or DEFAULT_BILLING_PUBLISHABLE_KEY_ENV_VAR
+    ).strip()
+    secret_key_env_var = str(
+        resolved.get(
+            "secret_key_env_var",
+            DEFAULT_BILLING_SECRET_KEY_ENV_VAR,
+        )
+        or DEFAULT_BILLING_SECRET_KEY_ENV_VAR
+    ).strip()
+    webhook_secret_env_var = str(
+        resolved.get(
+            "webhook_secret_env_var",
+            DEFAULT_BILLING_WEBHOOK_SECRET_ENV_VAR,
+        )
+        or DEFAULT_BILLING_WEBHOOK_SECRET_ENV_VAR
+    ).strip()
+    billing_currency = str(
+        resolved.get("billing_currency", DEFAULT_BILLING_CURRENCY)
+        or DEFAULT_BILLING_CURRENCY
+    ).strip()
+
+    return "\n".join(
+        [
+            "# QuickScale Billing (managed)",
+            "# Runtime Stripe variables for the backend billing module.",
+            f"# Billing currency from quickscale.yml: {billing_currency}",
+            f"{publishable_key_env_var}=",
+            f"{secret_key_env_var}=",
+            f"{webhook_secret_env_var}=",
+            "# End QuickScale Billing",
+        ]
+    )
+
+
+def _sync_billing_env_example(
+    output_path: Path,
+    qs_config: QuickScaleConfig,
+) -> bool:
+    """Keep `.env.example` aligned with the billing env-var names."""
+    billing_config = qs_config.modules.get("billing")
+    env_example_path = output_path / ".env.example"
+    if billing_config is None or not env_example_path.exists():
+        return True
+
+    start_marker = "# QuickScale Billing (managed)"
+    end_marker = "# End QuickScale Billing"
+    rendered_block = _render_billing_env_example_block(billing_config.options or {})
+
+    try:
+        content = env_example_path.read_text()
+    except OSError as e:
+        click.secho(
+            f"⚠️  Failed to read .env.example for billing wiring: {e}",
+            fg="yellow",
+        )
+        return False
+
+    if start_marker in content and end_marker in content:
+        before, remainder = content.split(start_marker, maxsplit=1)
+        _, after = remainder.split(end_marker, maxsplit=1)
+        replacement = rendered_block + after
+        updated_content = before + replacement
+    else:
+        suffix = "" if content.endswith("\n") else "\n"
+        updated_content = content + suffix + "\n" + rendered_block + "\n"
+
+    try:
+        env_example_path.write_text(updated_content)
+    except OSError as e:
+        click.secho(
+            f"⚠️  Failed to update .env.example for billing wiring: {e}",
+            fg="yellow",
+        )
+        return False
+
+    click.secho("✅ Updated .env.example with billing env vars", fg="green")
+    return True
+
+
 def _normalize_backups_gitignore_entry(local_directory: str) -> str | None:
     """Return a safe repo-relative ignore entry for backup artifacts."""
     if any(
@@ -2179,6 +2361,14 @@ def _execute_apply_steps(
             reason="Unable to update .env.example with the configured analytics env-var names.",
         )
 
+    if not _sync_billing_env_example(ctx.output_path, ctx.qs_config):
+        _abort_after_post_embed_failure(
+            ctx,
+            embedded_modules,
+            failed_step="billing env example sync",
+            reason="Unable to update .env.example with the configured billing env-var names.",
+        )
+
     if not _sync_project_module_dependencies_for_apply(
         ctx.output_path,
         ctx.qs_config,

quickscale_cli-0.86.0/src/quickscale_cli/commands/implied_module_defaults.py

@@ -0,0 +1,23 @@
+"""Helpers for materializing implicit module configs in CLI flows."""
+
+from collections.abc import Collection
+from typing import Any
+
+from quickscale_cli.commands.module_config import get_default_notifications_config
+
+
+def get_implied_module_default_configs(
+    module_names: Collection[str],
+) -> dict[str, dict[str, Any]]:
+    """Return module config blocks that should be made explicit automatically."""
+    names = set(module_names)
+    implied_configs: dict[str, dict[str, Any]] = {}
+
+    if "billing" in names and "orgs" not in names:
+        implied_configs["orgs"] = {}
+        names.add("orgs")
+
+    if "orgs" in names and "notifications" not in names:
+        implied_configs["notifications"] = get_default_notifications_config()
+
+    return implied_configs

{quickscale_cli-0.84.0 → quickscale_cli-0.86.0}/src/quickscale_cli/commands/module_commands.py

@@ -208,8 +208,12 @@ def _sync_state_module_version(project_path: Path, module: str, version: str) ->
     state_manager.save(state)
 
 
-def _validate_module_readiness(module: str) -> bool:
-    """Reject placeholder modules from embed/apply flows."""
+def _validate_module_readiness(
+    module: str,
+    *,
+    execution_mode: ModuleExecutionMode = STANDALONE_MODULE_EXECUTION_MODE,
+) -> bool:
+    """Reject non-public modules from standalone embed/update flows."""
     readiness_reason = get_module_readiness_reason(module)
     if readiness_reason is None:
         return True
@@ -416,7 +420,10 @@ def embed_module(
         if not _validate_module_not_exists(project_path, module):
             return False
 
-        if not _validate_module_readiness(module):
+        if not _validate_module_readiness(
+            module,
+            execution_mode=execution_mode,
+        ):
             return False
 
         branch = f"splits/{module}-module"