snapstack 1.0.0__py3-none-any.whl

pysnap/commands/update.py

@@ -0,0 +1,133 @@
+"""
+``pysnap update`` command -- update infrastructure files in a pysnap project.
+"""
+
+from __future__ import annotations
+
+import difflib
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.syntax import Syntax
+
+from pysnap.manifest import read_manifest
+
+console = Console()
+
+
+def update_command(
+    accept_all: Annotated[
+        bool,
+        typer.Option("--accept-all", help="Accept all updates without confirmation"),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Show diffs without writing changes"),
+    ] = False,
+) -> None:
+    """Update infrastructure files in a pysnap-generated project."""
+    project_path = Path.cwd()
+
+    try:
+        manifest = read_manifest(project_path)
+    except FileNotFoundError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    template_name = manifest.get("template", "")
+    original_options = manifest.get("options", {})
+    infrastructure_files: list[str] = manifest.get("infrastructure_files", [])
+
+    if not infrastructure_files:
+        console.print("[green]No infrastructure files to update.[/green]")
+        return
+
+    # Re-render infrastructure files from current template
+    from jinja2 import Environment, FileSystemLoader, select_autoescape
+    from pysnap.generator import load_template_manifest
+
+    try:
+        manifest_data = load_template_manifest(template_name)
+    except FileNotFoundError as exc:
+        console.print(f"[red]Template not found:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    template_dir = Path(__file__).parent.parent / "templates" / template_name
+    shared_dir = Path(__file__).parent.parent / "_shared"
+    search_paths = [str(template_dir)]
+    if shared_dir.is_dir():
+        search_paths.append(str(shared_dir))
+
+    env = Environment(
+        loader=FileSystemLoader(search_paths),
+        autoescape=select_autoescape([]),
+        keep_trailing_newline=True,
+    )
+
+    context = {**original_options}
+    context["project_name_slug"] = original_options.get("project_name", "").replace("-", "_")
+
+    # Build reverse map: output_path -> template_name
+    all_files = manifest_data.get("files", {})
+    output_to_template: dict[str, str] = {}
+    for group_files in all_files.values():
+        for tmpl, out in group_files.items():
+            output_to_template[out] = tmpl
+
+    changed = 0
+    no_change = 0
+
+    for out_rel in infrastructure_files:
+        tmpl_name = output_to_template.get(out_rel)
+        if not tmpl_name:
+            continue
+
+        try:
+            rendered = env.get_template(tmpl_name).render(**context)
+        except Exception as exc:
+            console.print(f"[yellow]Warning:[/yellow] Could not render {out_rel}: {exc}")
+            continue
+
+        current_path = project_path / out_rel
+        if current_path.exists():
+            current = current_path.read_text(encoding="utf-8")
+        else:
+            current = ""
+
+        if current == rendered:
+            no_change += 1
+            continue
+
+        # Show diff
+        diff = list(difflib.unified_diff(
+            current.splitlines(keepends=True),
+            rendered.splitlines(keepends=True),
+            fromfile=f"current/{out_rel}",
+            tofile=f"updated/{out_rel}",
+        ))
+
+        console.print(f"\n[bold cyan]{out_rel}[/bold cyan]")
+        console.print(Syntax("".join(diff), "diff", theme="monokai", line_numbers=False))
+
+        if dry_run:
+            changed += 1
+            continue
+
+        should_write = accept_all
+        if not should_write:
+            import questionary
+            answer = questionary.confirm(f"Apply update to {out_rel}?", default=True).ask()
+            should_write = bool(answer)
+
+        if should_write:
+            current_path.parent.mkdir(parents=True, exist_ok=True)
+            current_path.write_text(rendered, encoding="utf-8")
+            console.print(f"[green]  Updated[/green] {out_rel}")
+            changed += 1
+
+    if dry_run:
+        console.print(f"\n[dim]Dry run: {changed} file(s) would change, {no_change} unchanged.[/dim]")
+    else:
+        console.print(f"\n[green]Done.[/green] {changed} file(s) updated, {no_change} unchanged.")

pysnap/community.py

@@ -0,0 +1,113 @@
+"""
+Community template cloning and validation.
+
+Handles ``pysnap use <url> <project_name>``:
+  1. Clone the repository (shallow) to a temp directory.
+  2. Validate that it contains a template.json manifest.
+  3. Delegate generation to the standard generator pipeline.
+  4. Clean up the clone.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def clone_template(url: str, dest: Path) -> None:
+    """Shallow-clone *url* into *dest*.
+
+    Parameters
+    ----------
+    url:
+        Git repository URL.
+    dest:
+        Target directory (must not already exist).
+
+    Raises
+    ------
+    RuntimeError
+        If git is not installed or the clone command fails.
+    """
+    result = subprocess.run(
+        ["git", "clone", "--depth", "1", url, str(dest)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"git clone failed for {url!r}:\n{result.stderr}"
+        )
+
+
+def validate_template(path: Path) -> bool:
+    """Return True if *path* is a valid pysnap template directory.
+
+    A valid template must contain a ``template.json`` with at least the
+    ``name`` and ``files`` fields.
+    """
+    manifest_path = path / "template.json"
+    if not manifest_path.exists():
+        return False
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        return "name" in data and "files" in data
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def cleanup_clone(path: Path) -> None:
+    """Remove the cloned template directory."""
+    if path.exists():
+        shutil.rmtree(path, ignore_errors=True)
+
+
+def use_community_template(
+    template_url: str,
+    project_name: str,
+    options: dict,
+    output_dir: str,
+    console,
+) -> Path | None:
+    """Clone a community template and generate a project from it.
+
+    Returns the generated project path or None on failure.
+    """
+    tmp_dir = Path(tempfile.mkdtemp(prefix="pysnap-clone-"))
+    clone_path = tmp_dir / "template"
+
+    try:
+        console.print(f"[dim]Cloning {template_url}...[/dim]")
+        clone_template(template_url, clone_path)
+
+        if not validate_template(clone_path):
+            console.print(
+                "[red]Invalid template:[/red] The repository must contain a valid template.json."
+            )
+            return None
+
+        # Temporarily patch generator to use the cloned template directory
+        from pysnap import generator as gen_module
+
+        original_resolve = gen_module._resolve_template_dir
+
+        def _patched_resolve(framework: str) -> Path:
+            return clone_path
+
+        gen_module._resolve_template_dir = _patched_resolve  # type: ignore[assignment]
+        try:
+            result = gen_module.generate_project(project_name, options, output_dir, console)
+        finally:
+            gen_module._resolve_template_dir = original_resolve  # type: ignore[assignment]
+
+        return result
+
+    except RuntimeError as exc:
+        console.print(f"[red]Clone failed:[/red] {exc}")
+        return None
+    finally:
+        cleanup_clone(tmp_dir)

pysnap/config.py

@@ -0,0 +1,76 @@
+"""
+pysnap internal configuration constants.
+
+This module is the single source of truth for all pysnap-wide defaults,
+supported option sets, and external service URLs. Never import user-facing
+constants from here -- use it only for internal logic.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "PYSNAP_VERSION",
+    "REGISTRY_URL",
+    "REGISTRY_CACHE_TTL_SECONDS",
+    "REGISTRY_CACHE_PATH",
+    "PLUGIN_ENTRY_POINT_GROUP",
+    "SUPPORTED_FRAMEWORKS",
+    "SUPPORTED_DATABASES",
+    "SUPPORTED_PACKAGE_MANAGERS",
+    "DEFAULT_OPTIONS",
+    "MANIFEST_SCHEMA_VERSION",
+    "MANIFEST_FILENAME",
+    "INFRASTRUCTURE_FILE_GROUPS",
+]
+
+from pathlib import Path
+
+PYSNAP_VERSION: str = "1.0.0"
+
+# Community template registry
+REGISTRY_URL: str = (
+    "https://raw.githubusercontent.com/pysnap-dev/pysnap/main/registry/templates.json"
+)
+REGISTRY_CACHE_TTL_SECONDS: int = 3600  # 1 hour
+REGISTRY_CACHE_PATH: Path = Path.home() / ".cache" / "pysnap" / "registry.json"
+
+# Plugin discovery
+PLUGIN_ENTRY_POINT_GROUP: str = "pysnap.plugins"
+
+# Built-in framework names and display names
+SUPPORTED_FRAMEWORKS: dict[str, str] = {
+    "fastapi": "FastAPI",
+    "django": "Django",
+    "flask": "Flask",
+}
+
+# Built-in database names and display names
+SUPPORTED_DATABASES: dict[str, str] = {
+    "sqlite": "SQLite",
+    "postgresql": "PostgreSQL",
+    "none": "None",
+}
+
+# Supported package managers
+SUPPORTED_PACKAGE_MANAGERS: list[str] = ["uv", "pip", "poetry"]
+
+# Default option values (used for non-interactive mode when flag is omitted)
+DEFAULT_OPTIONS: dict = {
+    "framework": "fastapi",
+    "database": "sqlite",
+    "include_auth": False,
+    "include_docker": True,
+    "include_ci": True,
+    "package_manager": "uv",
+    "include_tests": True,
+}
+
+# .pysnap.json manifest
+MANIFEST_SCHEMA_VERSION: str = "1.0"
+MANIFEST_FILENAME: str = ".pysnap.json"
+
+# Template condition groups that map to infrastructure files eligible for `pysnap update`
+INFRASTRUCTURE_FILE_GROUPS: list[str] = [
+    "when_docker",
+    "when_ci",
+]

pysnap/generator.py

@@ -0,0 +1,262 @@
+"""
+Project generation engine.
+
+Renders Jinja2 templates into the target project directory using a
+manifest-driven file mapping.  The mapping comes from each framework
+template's ``template.json`` rather than being hard-coded, so new
+frameworks can be added without touching this module.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from pysnap.config import (
+    INFRASTRUCTURE_FILE_GROUPS,
+    PYSNAP_VERSION,
+)
+from pysnap.manifest import write_manifest
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def generate_project(
+    project_name: str,
+    options: dict[str, Any],
+    output_dir: str,
+    console: Console,
+) -> Path | None:
+    """Scaffold a new project from a template into *output_dir/project_name*.
+
+    Returns the generated project path on success, or ``None`` if the
+    directory already exists.
+    """
+    project_path = Path(output_dir) / project_name
+
+    if project_path.exists():
+        console.print(
+            f"[red]Error:[/red] Directory [bold]{project_path}[/bold] already exists."
+        )
+        return None
+
+    # Register cleanup so Ctrl-C leaves no partial project behind.
+    _register_cleanup(project_path)
+
+    template_dir = _resolve_template_dir(options["framework"])
+    manifest_data = _load_manifest(template_dir)
+    template_map = _build_template_map(manifest_data, options)
+    infrastructure_files = _collect_infrastructure_files(manifest_data, options)
+
+    shared_dir = Path(__file__).parent / "_shared"
+    search_paths = [str(template_dir)]
+    if shared_dir.is_dir():
+        search_paths.append(str(shared_dir))
+
+    env = Environment(
+        loader=FileSystemLoader(search_paths),
+        autoescape=select_autoescape([]),
+        keep_trailing_newline=True,
+    )
+
+    context = {
+        **options,
+        "project_name_slug": project_name.replace("-", "_").replace(" ", "_"),
+    }
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+            transient=True,
+        ) as progress:
+            task = progress.add_task("[green]Generating project...", total=len(template_map))
+            for tmpl_name, out_path in template_map.items():
+                full_out = project_path / out_path
+                full_out.parent.mkdir(parents=True, exist_ok=True)
+                try:
+                    content = env.get_template(tmpl_name).render(**context)
+                    full_out.write_text(content, encoding="utf-8")
+                except Exception as exc:
+                    console.print(
+                        f"[yellow]Warning:[/yellow] Could not generate {out_path}: {exc}"
+                    )
+                progress.advance(task)
+
+        _write_project_manifest(
+            project_path=project_path,
+            manifest_data=manifest_data,
+            options=options,
+            infrastructure_files=infrastructure_files,
+        )
+
+        _print_success(console, project_name, options)
+
+        # Cleanup no longer needed -- generation succeeded.
+        _cancel_cleanup()
+
+    except KeyboardInterrupt:
+        # Cleanup fires via atexit; we just exit cleanly.
+        console.print("\n[yellow]Cancelled -- cleaning up partial project...[/yellow]")
+        sys.exit(130)
+
+    return project_path
+
+
+def load_template_manifest(framework: str) -> dict[str, Any]:
+    """Load the template.json manifest for *framework*."""
+    return _load_manifest(_resolve_template_dir(framework))
+
+
+def build_template_map(manifest_data: dict[str, Any], options: dict[str, Any]) -> dict[str, str]:
+    """Public wrapper around the internal template-map builder."""
+    return _build_template_map(manifest_data, options)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+_cleanup_path: Path | None = None
+
+
+def _register_cleanup(project_path: Path) -> None:
+    global _cleanup_path
+    _cleanup_path = project_path
+    atexit.register(_atexit_cleanup)
+
+
+def _cancel_cleanup() -> None:
+    global _cleanup_path
+    _cleanup_path = None
+
+
+def _atexit_cleanup() -> None:
+    global _cleanup_path
+    if _cleanup_path is not None and _cleanup_path.exists():
+        shutil.rmtree(_cleanup_path, ignore_errors=True)
+
+
+def _resolve_template_dir(framework: str) -> Path:
+    """Return the absolute path to the Jinja2 template directory for *framework*."""
+    here = Path(__file__).parent
+    template_dir = here / "templates" / framework
+    if not template_dir.is_dir():
+        raise FileNotFoundError(
+            f"No template directory found for framework '{framework}' "
+            f"(expected {template_dir})."
+        )
+    return template_dir
+
+
+def _load_manifest(template_dir: Path) -> dict[str, Any]:
+    """Parse template.json from *template_dir*."""
+    manifest_path = template_dir / "template.json"
+    if not manifest_path.exists():
+        raise FileNotFoundError(
+            f"Template manifest not found: {manifest_path}. "
+            "Check that the template directory contains a template.json."
+        )
+    return json.loads(manifest_path.read_text(encoding="utf-8"))
+
+
+def _build_template_map(
+    manifest_data: dict[str, Any],
+    options: dict[str, Any],
+) -> dict[str, str]:
+    """Evaluate the manifest's condition groups and return the active file mapping."""
+    files = manifest_data.get("files", {})
+    mapping: dict[str, str] = {}
+
+    for group, group_files in files.items():
+        if _group_active(group, options):
+            mapping.update(group_files)
+
+    return mapping
+
+
+def _group_active(group: str, options: dict[str, Any]) -> bool:
+    """Return True if a condition group should be included given *options*."""
+    db_selected = options.get("database", "none") != "none"
+    auth_selected = bool(options.get("include_auth"))
+
+    conditions: dict[str, bool] = {
+        "always": True,
+        "when_database": db_selected,
+        "when_auth": auth_selected,
+        "when_auth_and_database": auth_selected and db_selected,
+        "when_docker": bool(options.get("include_docker")),
+        "when_tests": bool(options.get("include_tests")),
+        "when_ci": bool(options.get("include_ci")),
+    }
+    return conditions.get(group, False)
+
+
+def _collect_infrastructure_files(
+    manifest_data: dict[str, Any],
+    options: dict[str, Any],
+) -> list[str]:
+    """Return relative output paths of infrastructure-only template files."""
+    files = manifest_data.get("files", {})
+    infra: list[str] = []
+    for group in INFRASTRUCTURE_FILE_GROUPS:
+        if _group_active(group, options):
+            infra.extend(files.get(group, {}).values())
+    return infra
+
+
+def _write_project_manifest(
+    project_path: Path,
+    manifest_data: dict[str, Any],
+    options: dict[str, Any],
+    infrastructure_files: list[str],
+) -> None:
+    write_manifest(
+        project_path=project_path,
+        template=manifest_data["name"],
+        template_version=manifest_data.get("version", "unknown"),
+        options=options,
+        infrastructure_files=infrastructure_files,
+    )
+
+
+def _print_success(console: Console, project_name: str, options: dict[str, Any]) -> None:
+    pm = options["package_manager"]
+    install_cmd = {
+        "uv": "uv sync",
+        "pip": 'pip install -e ".[dev]"',
+        "poetry": "poetry install",
+    }.get(pm, 'pip install -e ".[dev]"')
+
+    framework = options["framework"]
+    run_cmd = {
+        "fastapi": "uvicorn app.main:app --reload",
+        "django": "python manage.py runserver",
+        "flask": "flask --app app run --debug",
+    }.get(framework, "python -m app")
+
+    console.print()
+    console.print(
+        Panel(
+            f"[bold green]Project [cyan]{project_name}[/cyan] created successfully![/bold green]\n\n"
+            f"[bold]Next steps:[/bold]\n"
+            f"  [cyan]cd {project_name}[/cyan]\n"
+            f"  [cyan]{install_cmd}[/cyan]\n"
+            f"  [cyan]{run_cmd}[/cyan]\n\n"
+            f"[dim]Run [white]pysnap update[/white] later to pull in template improvements.[/dim]",
+            border_style="green",
+        )
+    )

pysnap/main.py

@@ -0,0 +1,65 @@
+"""
+snapstack -- scaffold Python backend projects in seconds.
+
+Entry point for the Typer CLI application.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from pysnap import __version__
+
+app = typer.Typer(
+    name="snapstack",
+    help="The create-next-app experience for Python backend projects.",
+    add_completion=False,
+    pretty_exceptions_enable=False,
+)
+
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"snapstack {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Show snapstack version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """snapstack -- scaffold Python backend projects in seconds."""
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+from pysnap.commands.create import create_command  # noqa: E402
+
+app.command(name="create", help="Scaffold a new Python project.")(create_command)
+
+
+# ---------------------------------------------------------------------------
+# Subcommand groups (registered in their own modules)
+# ---------------------------------------------------------------------------
+
+from pysnap.commands.templates_cmd import templates_app  # noqa: E402
+from pysnap.commands.add import add_command  # noqa: E402
+from pysnap.commands.update import update_command  # noqa: E402
+
+app.add_typer(templates_app, name="templates")
+app.command(name="add", help="Add boilerplate to an existing project.")(add_command)
+app.command(name="update", help="Update infrastructure files in a pysnap project.")(update_command)