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

quickscale_cli-0.76.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: quickscale-cli
+Version: 0.76.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
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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)
+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 package for QuickScale.
+
+This package exposes the `quickscale` command used to plan, apply, inspect, and operate generated projects.
+
+## Command groups
+
+- Project lifecycle: `plan`, `apply`, `status`, `remove`
+- Local development: `up`, `down`, `ps`, `logs`, `shell`, `manage`
+- Deployment: `deploy`
+- Module workflows: `update`, `push`
+
+## Relationship to other packages
+
+- `quickscale-cli` is the command surface
+- `quickscale-core` contains the underlying scaffolding and template logic
+- `quickscale` installs both together for convenience
+
+## Install
+
+Usually installed via the meta-package:
+
+```bash
+pip install quickscale
+```
+
+Standalone package installs can use this package's published metadata and dependency constraints.
+
+## Documentation
+
+- Repository overview: [QuickScale README](https://github.com/Experto-AI/quickscale/blob/main/README.md)
+- Start guide: [START_HERE.md](https://github.com/Experto-AI/quickscale/blob/main/START_HERE.md)
+- Technical decisions: [docs/technical/decisions.md](https://github.com/Experto-AI/quickscale/blob/main/docs/technical/decisions.md)
+- CLI source entrypoint: [src/quickscale_cli/main.py](https://github.com/Experto-AI/quickscale/blob/main/quickscale_cli/src/quickscale_cli/main.py)
+
+This README is package-local context only. Root documentation remains authoritative for repo-wide policy and scope.
+

quickscale_cli-0.76.0/README.md

@@ -0,0 +1,37 @@
+# quickscale-cli
+
+Command-line interface package for QuickScale.
+
+This package exposes the `quickscale` command used to plan, apply, inspect, and operate generated projects.
+
+## Command groups
+
+- Project lifecycle: `plan`, `apply`, `status`, `remove`
+- Local development: `up`, `down`, `ps`, `logs`, `shell`, `manage`
+- Deployment: `deploy`
+- Module workflows: `update`, `push`
+
+## Relationship to other packages
+
+- `quickscale-cli` is the command surface
+- `quickscale-core` contains the underlying scaffolding and template logic
+- `quickscale` installs both together for convenience
+
+## Install
+
+Usually installed via the meta-package:
+
+```bash
+pip install quickscale
+```
+
+Standalone package installs can use this package's published metadata and dependency constraints.
+
+## Documentation
+
+- Repository overview: [QuickScale README](https://github.com/Experto-AI/quickscale/blob/main/README.md)
+- Start guide: [START_HERE.md](https://github.com/Experto-AI/quickscale/blob/main/START_HERE.md)
+- Technical decisions: [docs/technical/decisions.md](https://github.com/Experto-AI/quickscale/blob/main/docs/technical/decisions.md)
+- CLI source entrypoint: [src/quickscale_cli/main.py](https://github.com/Experto-AI/quickscale/blob/main/quickscale_cli/src/quickscale_cli/main.py)
+
+This README is package-local context only. Root documentation remains authoritative for repo-wide policy and scope.

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

@@ -1,39 +1,42 @@
-[tool.poetry]
+[project]
 name = "quickscale-cli"
-version = "0.74.2"
+version = "0.76.0"
 description = "Command-line interface for QuickScale Django project generator"
-authors = ["Experto AI <victor@experto.ai>"]
+requires-python = ">=3.14,<4.0"
+readme = "README.md"
 license = "Apache-2.0"
+authors = [{name = "Experto AI", email = "victor@experto.ai"}]
 keywords = ["django", "cli", "project-generator", "saas"]
-homepage = "https://github.com/Experto-AI/quickscale"
-repository = "https://github.com/Experto-AI/quickscale"
-documentation = "https://github.com/Experto-AI/quickscale/tree/main/docs"
-readme = "README.md"
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
     "Framework :: Django",
     "Framework :: Django :: 6.0",
 ]
+dynamic = ["dependencies"]
+
+[project.urls]
+Homepage = "https://github.com/Experto-AI/quickscale"
+Repository = "https://github.com/Experto-AI/quickscale"
+Documentation = "https://github.com/Experto-AI/quickscale/tree/main/docs"
+
+[project.scripts]
+quickscale = "quickscale_cli.main:cli"
+
+[tool.poetry]
 packages = [{include = "quickscale_cli", from = "src"}]
 
 [tool.poetry.dependencies]
-python = "^3.12"
+python = "^3.14"
 click = "^8.3.1"
-quickscale-core = "^0.74.2"
+quickscale-core = "^0.76.0"
 
 [tool.poetry.group.dev.dependencies]
 # Dev dependencies centralized in root pyproject.toml
 # Use: poetry install from repository root
 
-[tool.poetry.scripts]
-quickscale = "quickscale_cli.main:cli"
-
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
@@ -46,10 +49,6 @@ python_functions = ["test_*"]
 addopts = [
     "--strict-markers",
     "--strict-config",
-    "--cov=quickscale_cli",
-    "--cov-report=term-missing",
-    "--cov-report=html",
-    "--cov-fail-under=90",
     "-m", "not e2e",  # Skip E2E tests by default (run with: pytest -m e2e)
 ]
 markers = [

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

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

{quickscale_cli-0.74.2 → quickscale_cli-0.76.0}/src/quickscale_cli/commands/apply_command.py

@@ -7,10 +7,12 @@ import subprocess
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
+from typing import Any, cast
 
 import click
 
 from quickscale_cli.commands.module_commands import embed_module
+from quickscale_cli.utils.module_wiring_manager import regenerate_managed_wiring
 from quickscale_cli.schema.config_schema import (
     ConfigValidationError,
     QuickScaleConfig,
@@ -43,6 +45,15 @@ class ApplyContext:
     delta: ConfigDelta
 
 
+@dataclass
+class EmbedModulesResult:
+    """Result for module embedding step."""
+
+    success: bool
+    embedded_modules: list[str]
+    failed_module: str | None = None
+
+
 def _run_command(
     cmd: list[str],
     cwd: Path,
@@ -89,28 +100,19 @@ def _run_command(
 def _generate_project(config: QuickScaleConfig, output_path: Path) -> bool:
     """Generate project using ProjectGenerator"""
     try:
-        click.echo(f"⏳ Generating project: {config.project.name}...")
-
-        # Validate theme availability
-        if config.project.theme == "showcase_htmx":
-            click.secho(
-                f"❌ Error: Theme '{config.project.theme}' is not yet implemented",
-                fg="red",
-                err=True,
-            )
-            click.echo(
-                "\n💡 The 'showcase_htmx' theme is planned for a future release:",
-                err=True,
-            )
-            click.echo("   - showcase_htmx: Coming in v0.78.0", err=True)
-            click.echo(
-                "   - Use 'showcase_react' (default) or 'showcase_html' instead",
-                err=True,
-            )
-            return False
+        click.echo(
+            f"⏳ Generating project: {config.project.slug} "
+            f"(package: {config.project.package})..."
+        )
 
         generator = ProjectGenerator(theme=config.project.theme)
-        generator.generate(config.project.name, output_path)
+        # mypy can resolve an older installed quickscale-core signature here.
+        generate_project = cast(Any, generator.generate)
+        generate_project(
+            config.project.slug,
+            output_path,
+            package_name=config.project.package,
+        )
 
         click.secho(f"✅ Project generated: {output_path}", fg="green")
         return True
@@ -160,7 +162,11 @@ def _git_commit(project_path: Path, message: str) -> bool:
     return success
 
 
-def _embed_module(project_path: Path, module_name: str) -> bool:
+def _embed_module(
+    project_path: Path,
+    module_name: str,
+    skip_auth_migration_check: bool = False,
+) -> bool:
     """Embed a module using the embed_module function with non-interactive mode"""
     click.echo(f"⏳ Embedding module: {module_name}...")
 
@@ -169,6 +175,8 @@ def _embed_module(project_path: Path, module_name: str) -> bool:
             module=module_name,
             project_path=project_path,
             non_interactive=True,
+            allow_unverifiable_auth_state=True,
+            skip_auth_migration_check=skip_auth_migration_check,
         )
 
         if success:
@@ -200,6 +208,15 @@ def _run_migrations(project_path: Path) -> bool:
     )[0]
 
 
+def _run_migrations_in_docker(project_path: Path) -> bool:
+    """Run Django migrations inside the backend Docker container."""
+    return _run_command(
+        ["quickscale", "manage", "migrate"],
+        project_path,
+        "Running migrations (Docker)",
+    )[0]
+
+
 def _start_docker(
     project_path: Path, build: bool = True, verbose: bool = False
 ) -> bool:
@@ -246,6 +263,7 @@ def _start_docker(
             cmd,
             project_path,
             "Starting Docker services",
+            capture=False,
         )
         return success
 
@@ -352,7 +370,10 @@ def _load_and_validate_config(config_path: Path) -> QuickScaleConfig:
         click.secho(
             f"❌ Configuration file not found: {config_path}", fg="red", err=True
         )
-        click.echo("\n💡 Create a configuration with: quickscale plan <name>", err=True)
+        click.echo(
+            "\n💡 Create a configuration with: quickscale plan <project-slug>",
+            err=True,
+        )
         raise click.Abort()
 
     click.echo(f"\n📋 Reading configuration: {config_path}")
@@ -367,18 +388,19 @@ def _load_and_validate_config(config_path: Path) -> QuickScaleConfig:
         raise click.Abort()
 
 
-def _determine_output_path(config_path: Path, project_name: str) -> Path:
+def _determine_output_path(config_path: Path, project_slug: str) -> Path:
     """Determine output directory for project."""
     config_path = config_path.resolve()
-    if config_path.parent.name == project_name:
+    if config_path.parent.name == project_slug:
         return config_path.parent
-    return Path.cwd() / project_name
+    return Path.cwd() / project_slug
 
 
 def _display_config_summary(qs_config: QuickScaleConfig) -> None:
     """Display configuration summary."""
     click.echo("\n🚀 Applying configuration:")
-    click.echo(f"   Project: {qs_config.project.name}")
+    click.echo(f"   Project slug: {qs_config.project.slug}")
+    click.echo(f"   Python package: {qs_config.project.package}")
     click.echo(f"   Theme: {qs_config.project.theme}")
     if qs_config.modules:
         click.echo(f"   Modules: {', '.join(qs_config.modules.keys())}")
@@ -495,7 +517,7 @@ def _generate_with_existing_config(
                     item.unlink()
 
     temp_dir = Path(tempfile.mkdtemp())
-    temp_project = temp_dir / qs_config.project.name
+    temp_project = temp_dir / qs_config.project.slug
 
     if not _generate_project(qs_config, temp_project):
         shutil.rmtree(temp_dir)
@@ -536,42 +558,92 @@ def _init_git_with_config(output_path: Path) -> None:
         click.secho("⚠️  Initial commit failed, continuing...", fg="yellow")
 
 
+def _commit_pending_config_changes(output_path: Path) -> None:
+    """Commit pending QuickScale config changes before module embedding
+
+    Stages and commits quickscale.yml and .quickscale/ directory changes so
+    git subtree operations have a clean working directory.  Called before
+    embedding modules in existing projects.
+
+    Args:
+        output_path: Path to the project directory
+
+    """
+    if is_working_directory_clean(output_path):
+        return
+
+    # Stage only QuickScale-managed config files
+    subprocess.run(
+        ["git", "add", "quickscale.yml", ".quickscale/"],
+        cwd=output_path,
+        capture_output=True,
+        check=False,
+    )
+
+    # Check if anything was staged
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--name-only"],
+        cwd=output_path,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    if result.stdout.strip():
+        _run_command(
+            ["git", "commit", "-m", "Update QuickScale configuration"],
+            output_path,
+            "Committing pending QuickScale configuration changes",
+        )
+
+
 def _embed_modules_step(
     output_path: Path,
     modules_to_embed: list[str],
     no_modules: bool,
     existing_state: QuickScaleState | None,
-) -> list[str]:
-    """Embed modules and return list of successfully embedded modules."""
+) -> EmbedModulesResult:
+    """Embed modules with fail-fast semantics."""
     embedded_modules: list[str] = []
 
     if no_modules or not modules_to_embed:
         if existing_state and not modules_to_embed:
             click.echo("⏭️  No new modules to embed")
-        return embedded_modules
+        return EmbedModulesResult(success=True, embedded_modules=embedded_modules)
+
+    skip_auth_migration_check = existing_state is None
 
     for module_name in modules_to_embed:
-        if not _embed_module(output_path, module_name):
-            click.secho(
-                f"⚠️  Module embedding failed for {module_name}, continuing...",
-                fg="yellow",
-            )
-            # Commit any partial changes to allow subsequent modules to be embedded
+        if not _embed_module(
+            output_path,
+            module_name,
+            skip_auth_migration_check=skip_auth_migration_check,
+        ):
             if not is_working_directory_clean(output_path):
                 _git_commit(output_path, f"Partial module: {module_name} (incomplete)")
+            click.secho(
+                f"❌ Module embedding failed for required module: {module_name}",
+                fg="red",
+                err=True,
+            )
+            return EmbedModulesResult(
+                success=False,
+                embedded_modules=embedded_modules,
+                failed_module=module_name,
+            )
         else:
             embedded_modules.append(module_name)
             _git_commit(output_path, f"Add module: {module_name}")
 
-    return embedded_modules
+    return EmbedModulesResult(success=True, embedded_modules=embedded_modules)
 
 
-def _run_post_generation_steps(output_path: Path) -> None:
-    """Run poetry install and migrations."""
+def _run_post_generation_steps(output_path: Path, run_migrations: bool = True) -> None:
+    """Run poetry install and optionally migrations."""
     if not _run_poetry_install(output_path):
         click.secho("⚠️  Poetry install failed, continuing...", fg="yellow")
 
-    if not _run_migrations(output_path):
+    if run_migrations and not _run_migrations(output_path):
         click.secho("⚠️  Migrations failed, continuing...", fg="yellow")
 
 
@@ -590,7 +662,8 @@ def _save_project_state(
             new_state = QuickScaleState(
                 version="1",
                 project=ProjectState(
-                    name=qs_config.project.name,
+                    slug=qs_config.project.slug,
+                    package=qs_config.project.package,
                     theme=qs_config.project.theme,
                     created_at=datetime.now().isoformat(),
                     last_applied=datetime.now().isoformat(),
@@ -624,7 +697,10 @@ def _save_project_state(
 
 
 def _display_next_steps(
-    output_path: Path, qs_config: QuickScaleConfig, no_docker: bool
+    output_path: Path,
+    qs_config: QuickScaleConfig,
+    no_docker: bool,
+    docker_started: bool | None = None,
 ) -> None:
     """Display success message and next steps."""
     click.echo("\n" + "=" * 50)
@@ -633,12 +709,17 @@ def _display_next_steps(
 
     click.echo("\n📋 Next steps:")
     if output_path != Path.cwd():
-        click.echo(f"  cd {qs_config.project.name}")
+        click.echo(f"  cd {qs_config.project.slug}")
 
     if qs_config.docker.start and not no_docker:
-        click.echo("  # Docker services should be running")
-        click.echo("  quickscale logs web  # View logs")
-        click.echo("  quickscale ps        # Check status")
+        if docker_started is False:
+            click.echo("  # Docker auto-start failed during apply")
+            click.echo("  quickscale up --build  # Retry Docker startup")
+            click.echo("  quickscale logs        # View failure details")
+        else:
+            click.echo("  # Docker services should be running")
+            click.echo("  quickscale logs backend  # View logs")
+            click.echo("  quickscale ps        # Check status")
     else:
         click.echo("  quickscale up        # Start Docker services")
         click.echo("  # Or run without Docker:")
@@ -657,7 +738,7 @@ def _prepare_apply_context(config_path: Path) -> ApplyContext:
     qs_config = _load_and_validate_config(config_path)
 
     # Determine output path
-    output_path = _determine_output_path(config_path, qs_config.project.name)
+    output_path = _determine_output_path(config_path, qs_config.project.slug)
 
     # Load existing state if project exists
     state_manager = StateManager(output_path)
@@ -684,6 +765,57 @@ def _prepare_apply_context(config_path: Path) -> ApplyContext:
     )
 
 
+def _regenerate_managed_wiring_for_apply(
+    ctx: ApplyContext,
+    embedded_modules: list[str],
+) -> bool:
+    """Regenerate managed module wiring files after embed/config changes."""
+    desired_module_names = sorted(ctx.qs_config.modules.keys())
+    if ctx.existing_state is None:
+        selected_modules = embedded_modules
+    else:
+        # Existing state may include unchanged modules that should remain wired.
+        selected_modules = sorted(
+            set(ctx.delta.modules_unchanged) | set(embedded_modules)
+        )
+
+    # If no desired modules are configured, explicitly render empty managed files.
+    if not desired_module_names:
+        selected_modules = []
+
+    options = {
+        module_name: module_config.options
+        for module_name, module_config in ctx.qs_config.modules.items()
+    }
+
+    success, message = regenerate_managed_wiring(
+        ctx.output_path,
+        module_names=selected_modules,
+        option_overrides=options,
+        project_package=ctx.qs_config.project.package,
+    )
+    if success:
+        click.secho("✅ Managed module wiring regenerated", fg="green")
+        return True
+
+    click.secho(f"❌ Managed wiring regeneration failed: {message}", fg="red", err=True)
+    return False
+
+
+def _print_apply_failure_summary(failed_step: str, reason: str) -> None:
+    """Print explicit failure summary and skipped steps."""
+    click.echo("\n" + "=" * 50)
+    click.secho("❌ Apply failed", fg="red", bold=True)
+    click.echo("=" * 50)
+    click.echo(f"\nFailed step: {failed_step}")
+    click.echo(f"Reason: {reason}")
+    click.echo("\nSkipped downstream steps:")
+    click.echo("  • poetry install")
+    click.echo("  • migrations")
+    click.echo("  • docker start")
+    click.echo("  • success completion output")
+
+
 def _execute_apply_steps(
     ctx: ApplyContext,
     force: bool,
@@ -714,24 +846,101 @@ def _execute_apply_steps(
         if ctx.existing_state
         else list(ctx.qs_config.modules.keys())
     )
-    embedded_modules = _embed_modules_step(
+
+    # For existing projects, commit any pending QuickScale config changes
+    # (e.g. quickscale.yml updated by `quickscale plan`) before embedding
+    # modules, so git subtree has a clean working directory to operate on.
+    if ctx.existing_state is not None and modules_to_embed:
+        _commit_pending_config_changes(ctx.output_path)
+
+    embed_result = _embed_modules_step(
         ctx.output_path, modules_to_embed, no_modules, ctx.existing_state
     )
+    embedded_modules = embed_result.embedded_modules
+
+    if not embed_result.success:
+        # Persist successful partial embeds (explicit no-rollback contract).
+        _save_project_state(
+            ctx.output_path,
+            ctx.qs_config,
+            ctx.existing_state,
+            embedded_modules,
+            ctx.delta,
+        )
+        _print_apply_failure_summary(
+            failed_step="module embedding",
+            reason=f"required module '{embed_result.failed_module}' failed to embed",
+        )
+        raise click.Abort()
+
+    # Deterministic managed wiring generation for selected modules.
+    if not _regenerate_managed_wiring_for_apply(ctx, embedded_modules):
+        _save_project_state(
+            ctx.output_path,
+            ctx.qs_config,
+            ctx.existing_state,
+            embedded_modules,
+            ctx.delta,
+        )
+        _print_apply_failure_summary(
+            failed_step="managed module wiring generation",
+            reason="unable to render settings/modules.py and urls_modules.py",
+        )
+        raise click.Abort()
 
-    # Run post-generation steps
-    _run_post_generation_steps(ctx.output_path)
+    should_auto_start_docker = not no_docker and ctx.qs_config.docker.start
+
+    # Run post-generation steps. Defer migrations until after Docker startup
+    # when auto-start is enabled, so PostgreSQL is reachable.
+    _run_post_generation_steps(
+        ctx.output_path,
+        run_migrations=not should_auto_start_docker,
+    )
 
     # Apply mutable configuration changes
     if ctx.existing_state and ctx.delta.has_mutable_config_changes:
-        if not _apply_mutable_config(ctx.output_path, ctx.delta, ctx.manifests):
-            click.secho("⚠️  Some config changes failed to apply", fg="yellow")
+        click.secho(
+            "✅ Mutable configuration changes applied via managed wiring",
+            fg="green",
+        )
 
     # Start Docker
-    if not no_docker and ctx.qs_config.docker.start:
-        if not _start_docker(
+    docker_started: bool | None = None
+    if should_auto_start_docker:
+        docker_started = _start_docker(
             ctx.output_path, ctx.qs_config.docker.build, verbose_docker
-        ):
-            click.secho("⚠️  Docker start failed, continuing...", fg="yellow")
+        )
+        if not docker_started:
+            _save_project_state(
+                ctx.output_path,
+                ctx.qs_config,
+                ctx.existing_state,
+                embedded_modules,
+                ctx.delta,
+            )
+            _print_apply_failure_summary(
+                failed_step="docker startup",
+                reason="Docker auto-start failed. Run 'quickscale logs' to inspect the failing service.",
+            )
+            raise click.Abort()
+
+    # For Docker auto-start projects, run migrations in the backend container
+    # so database connectivity uses the internal Docker network.
+    if should_auto_start_docker:
+        if docker_started:
+            if not _run_migrations_in_docker(ctx.output_path):
+                _save_project_state(
+                    ctx.output_path,
+                    ctx.qs_config,
+                    ctx.existing_state,
+                    embedded_modules,
+                    ctx.delta,
+                )
+                _print_apply_failure_summary(
+                    failed_step="database migrations",
+                    reason="Migrations failed inside Docker backend container. Run 'quickscale logs backend' for details.",
+                )
+                raise click.Abort()
 
     # Save state
     _save_project_state(
@@ -743,7 +952,7 @@ def _execute_apply_steps(
     )
 
     # Display next steps
-    _display_next_steps(ctx.output_path, ctx.qs_config, no_docker)
+    _display_next_steps(ctx.output_path, ctx.qs_config, no_docker, docker_started)
 
 
 @click.command()
@@ -796,10 +1005,11 @@ def apply(
       1. Validate configuration
       2. Generate project
       3. Initialize git + initial commit
-      4. Embed modules (if configured)
-      5. Run poetry install
-      6. Run migrations
+      4. Embed modules (if configured, fail-fast on required module failure)
+      5. Regenerate managed module wiring files
+      6. Run poetry install
       7. Start Docker (if configured)
+      8. Run migrations (after Docker auto-start when enabled)
     """
     # Prepare context
     ctx = _prepare_apply_context(Path(config))