snapstack 1.0.0__py3-none-any.whl

pysnap/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

pysnap/_shared/Dockerfile.j2

@@ -0,0 +1,34 @@
+{% set python_ver = "3.11" %}
+# syntax=docker/dockerfile:1
+FROM python:{{ python_ver }}-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Python dependencies
+COPY pyproject.toml .
+{% if package_manager == "uv" %}
+RUN pip install --no-cache-dir uv && uv sync --no-dev
+{% elif package_manager == "poetry" %}
+RUN pip install --no-cache-dir poetry && poetry install --only=main
+{% else %}
+RUN pip install --no-cache-dir -e .
+{% endif %}
+
+COPY . .
+
+{% if framework == "fastapi" %}
+EXPOSE 8000
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+{% elif framework == "django" %}
+EXPOSE 8000
+CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]
+{% elif framework == "flask" %}
+EXPOSE 5000
+ENV FLASK_APP=app
+CMD ["flask", "run", "--host=0.0.0.0"]
+{% endif %}

pysnap/_shared/ci.yml.j2

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+{% if package_manager == "uv" %}
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest
+{% elif package_manager == "poetry" %}
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Install dependencies
+        run: poetry install
+
+      - name: Lint
+        run: poetry run ruff check .
+
+      - name: Test
+        run: poetry run pytest
+{% else %}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest
+{% endif %}

pysnap/_shared/docker-compose.yml.j2

@@ -0,0 +1,46 @@
+services:
+  app:
+    build: .
+{% if framework == "fastapi" %}
+    ports:
+      - "8000:8000"
+{% elif framework == "django" %}
+    ports:
+      - "8000:8000"
+{% elif framework == "flask" %}
+    ports:
+      - "5000:5000"
+{% endif %}
+    env_file:
+      - .env
+    depends_on:
+{% if database == "postgresql" %}
+      db:
+        condition: service_healthy
+{% endif %}
+    develop:
+      watch:
+        - action: sync
+          path: .
+          target: /app
+{% if database == "postgresql" %}
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-user}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-password}
+      POSTGRES_DB: ${POSTGRES_DB:-{{ project_name_slug }}}
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER:-user}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:
+{% endif %}

pysnap/_shared/dockerignore.j2

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+*.log
+.DS_Store
+Thumbs.db

pysnap/_shared/env_example.j2

@@ -0,0 +1,24 @@
+# {{ project_name }} environment variables
+# Copy this file to .env and fill in your values
+
+# Application
+PROJECT_NAME="{{ project_name }}"
+VERSION="0.1.0"
+DESCRIPTION="Generated by pysnap"
+API_PREFIX="/api"
+DEBUG=false
+ALLOWED_ORIGINS='["http://localhost:3000","http://localhost:8000"]'
+
+{% if include_auth %}
+# Security
+SECRET_KEY="change-me-generate-a-long-random-string"
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+ALGORITHM="HS256"
+{% endif %}
+{% if database == "postgresql" %}
+# Database
+DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/{{ project_name_slug }}"
+{% elif database == "sqlite" %}
+# Database
+DATABASE_URL="sqlite+aiosqlite:///./{{ project_name_slug }}.db"
+{% endif %}

pysnap/_shared/gitignore.j2

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+*.log
+.DS_Store
+Thumbs.db

pysnap/commands/__init__.py

@@ -0,0 +1 @@
+"""Commands subpackage for pysnap."""

pysnap/commands/add.py

@@ -0,0 +1,171 @@
+"""
+``pysnap add`` command -- add boilerplate to an existing project.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+from pysnap.generator import build_template_map, load_template_manifest
+
+console = Console()
+
+SUPPORTED_COMPONENTS = ["docker", "ci", "auth", "tests"]
+
+COMPONENT_TO_GROUP = {
+    "docker": "when_docker",
+    "ci": "when_ci",
+    "auth": "when_auth",
+    "tests": "when_tests",
+}
+
+
+def add_command(
+    component: Annotated[
+        str,
+        typer.Argument(help=f"Component to add: {', '.join(SUPPORTED_COMPONENTS)}"),
+    ],
+    framework: Annotated[
+        Optional[str],
+        typer.Option("--framework", "-f", help="Framework (auto-detected from pyproject.toml)"),
+    ] = None,
+    db: Annotated[
+        Optional[str],
+        typer.Option("--db", "-d", help="Database (auto-detected from pyproject.toml)"),
+    ] = None,
+    pm: Annotated[
+        Optional[str],
+        typer.Option("--pm", help="Package manager"),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite existing files without asking"),
+    ] = False,
+) -> None:
+    """Add boilerplate to an existing Python project."""
+    if component not in SUPPORTED_COMPONENTS:
+        console.print(
+            f"[red]Unknown component:[/red] {component!r}. "
+            f"Choose from: {', '.join(SUPPORTED_COMPONENTS)}"
+        )
+        raise typer.Exit(code=1)
+
+    project_path = Path.cwd()
+
+    # Auto-detect framework from pyproject.toml if not provided
+    detected_framework = framework or _detect_framework(project_path)
+    if not detected_framework:
+        console.print(
+            "[red]Cannot detect framework.[/red] "
+            "Run from your project root or specify --framework."
+        )
+        raise typer.Exit(code=1)
+
+    detected_db = db or _detect_database(project_path)
+    detected_pm = pm or _detect_package_manager(project_path)
+
+    options = {
+        "framework": detected_framework,
+        "database": detected_db or "none",
+        "include_auth": component == "auth",
+        "include_docker": component == "docker",
+        "include_ci": component == "ci",
+        "include_tests": component == "tests",
+        "package_manager": detected_pm or "pip",
+        "project_name": project_path.name,
+        "project_name_slug": project_path.name.replace("-", "_"),
+    }
+
+    from jinja2 import Environment, FileSystemLoader, select_autoescape
+    from pysnap.config import SUPPORTED_FRAMEWORKS
+
+    template_dir = _find_template_dir(detected_framework)
+    if not template_dir:
+        console.print(f"[red]No template found for framework:[/red] {detected_framework!r}")
+        raise typer.Exit(code=1)
+
+    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,
+    )
+    manifest_data = load_template_manifest(detected_framework)
+
+    group = COMPONENT_TO_GROUP[component]
+    group_files: dict[str, str] = manifest_data.get("files", {}).get(group, {})
+
+    if not group_files:
+        console.print(f"[yellow]No files to add for component:[/yellow] {component!r}")
+        return
+
+    wrote_any = False
+    for tmpl_name, out_rel in group_files.items():
+        out_path = project_path / out_rel
+        if out_path.exists() and not force:
+            console.print(
+                f"[yellow]Skipping[/yellow] {out_rel} (already exists -- use --force to overwrite)"
+            )
+            continue
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        content = env.get_template(tmpl_name).render(**options)
+        out_path.write_text(content, encoding="utf-8")
+        console.print(f"[green]  +[/green] {out_rel}")
+        wrote_any = True
+
+    if wrote_any:
+        console.print(f"\n[bold green]{component}[/bold green] added successfully.")
+    else:
+        console.print(f"[dim]Nothing to do for {component!r}.[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# Auto-detection helpers
+# ---------------------------------------------------------------------------
+
+
+def _detect_framework(project_path: Path) -> str | None:
+    pyproject = project_path / "pyproject.toml"
+    if not pyproject.exists():
+        return None
+    text = pyproject.read_text(encoding="utf-8")
+    if "fastapi" in text.lower():
+        return "fastapi"
+    if "django" in text.lower():
+        return "django"
+    if "flask" in text.lower():
+        return "flask"
+    return None
+
+
+def _detect_database(project_path: Path) -> str | None:
+    pyproject = project_path / "pyproject.toml"
+    if not pyproject.exists():
+        return None
+    text = pyproject.read_text(encoding="utf-8")
+    if "asyncpg" in text or "psycopg" in text:
+        return "postgresql"
+    if "aiosqlite" in text or "sqlite" in text.lower():
+        return "sqlite"
+    return "none"
+
+
+def _detect_package_manager(project_path: Path) -> str | None:
+    if (project_path / "uv.lock").exists():
+        return "uv"
+    if (project_path / "poetry.lock").exists():
+        return "poetry"
+    return "pip"
+
+
+def _find_template_dir(framework: str) -> Path | None:
+    base = Path(__file__).parent.parent / "templates" / framework
+    return base if base.is_dir() else None

pysnap/commands/create.py

@@ -0,0 +1,136 @@
+"""
+``pysnap create`` command implementation.
+
+Handles both interactive (TTY) and non-interactive (flags-only) modes.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+from pysnap.config import DEFAULT_OPTIONS, SUPPORTED_FRAMEWORKS
+from pysnap.generator import generate_project
+
+console = Console()
+
+
+def create_command(
+    project_name: Annotated[str, typer.Argument(help="Name of the project directory to create")],
+    framework: Annotated[
+        Optional[str],
+        typer.Option("--framework", "-f", help="Web framework (fastapi, django, flask)"),
+    ] = None,
+    db: Annotated[
+        Optional[str],
+        typer.Option("--db", "-d", help="Database (sqlite, postgresql, none)"),
+    ] = None,
+    auth: Annotated[
+        Optional[bool],
+        typer.Option("--auth/--no-auth", help="Include JWT authentication"),
+    ] = None,
+    docker: Annotated[
+        Optional[bool],
+        typer.Option("--docker/--no-docker", help="Include Dockerfile and docker-compose"),
+    ] = None,
+    ci: Annotated[
+        Optional[bool],
+        typer.Option("--ci/--no-ci", help="Include GitHub Actions CI/CD"),
+    ] = None,
+    pm: Annotated[
+        Optional[str],
+        typer.Option("--pm", help="Package manager (uv, pip, poetry)"),
+    ] = None,
+    tests: Annotated[
+        Optional[bool],
+        typer.Option("--tests/--no-tests", help="Include pytest test suite"),
+    ] = None,
+    output: Annotated[
+        str,
+        typer.Option("--output", "-o", help="Output directory"),
+    ] = ".",
+    no_preview: Annotated[
+        bool,
+        typer.Option("--no-preview", help="Skip the file tree preview"),
+    ] = False,
+    no_validate: Annotated[
+        bool,
+        typer.Option("--no-validate", help="Skip post-generation validation"),
+    ] = False,
+) -> None:
+    """Scaffold a new Python project."""
+    # Build initial options dict from flags (None = not specified by user)
+    flag_options: dict = {
+        "framework": framework,
+        "database": db,
+        "include_auth": auth,
+        "include_docker": docker,
+        "include_ci": ci,
+        "package_manager": pm,
+        "include_tests": tests,
+    }
+
+    all_provided = all(v is not None for v in flag_options.values())
+    interactive = sys.stdin.isatty() and not all_provided
+
+    if interactive:
+        # Import here to avoid hard dependency when running non-interactively
+        from pysnap.prompts import ask_project_options
+
+        filled = ask_project_options(flag_options)
+        if filled is None:
+            raise typer.Abort()
+        options = filled
+    else:
+        # Fill any None values with defaults
+        options = {
+            k: (v if v is not None else DEFAULT_OPTIONS.get(k))
+            for k, v in flag_options.items()
+        }
+
+    options["project_name"] = project_name
+    options["project_name_slug"] = project_name.replace("-", "_").replace(" ", "_")
+
+    # Validate framework
+    known = set(SUPPORTED_FRAMEWORKS) | {"django", "flask"}  # Always include built-ins
+    if options["framework"] not in known:
+        console.print(f"[red]Unknown framework:[/red] {options['framework']!r}")
+        raise typer.Exit(code=1)
+
+    # Show preview (unless skipped)
+    if not no_preview and sys.stdout.isatty():
+        from pysnap.generator import build_template_map, load_template_manifest
+        from pysnap.preview import show_preview
+
+        manifest_data = load_template_manifest(options["framework"])
+        template_map = build_template_map(manifest_data, options)
+        action = show_preview(template_map, options, console)
+        if action == "cancel":
+            raise typer.Abort()
+        if action == "back":
+            # Re-run interactively if possible
+            if sys.stdin.isatty():
+                from pysnap.prompts import ask_project_options
+
+                refilled = ask_project_options({})
+                if refilled is None:
+                    raise typer.Abort()
+                options.update(refilled)
+            # else just proceed
+
+    project_path = generate_project(project_name, options, output, console)
+    if project_path is None:
+        raise typer.Exit(code=1)
+
+    # Post-generation validation (unless skipped)
+    if not no_validate:
+        from pysnap.validator import report_validation, validate_syntax
+
+        failures = validate_syntax(project_path)
+        report_validation(failures, console)
+        if failures:
+            raise typer.Exit(code=2)

pysnap/commands/templates_cmd.py

@@ -0,0 +1,134 @@
+"""
+``pysnap templates`` subcommand group.
+
+Provides ``pysnap templates list`` and ``pysnap templates search``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+templates_app = typer.Typer(
+    name="templates",
+    help="Browse available project templates.",
+    add_completion=False,
+)
+
+console = Console()
+
+
+@templates_app.command(name="list")
+def templates_list() -> None:
+    """List all available templates (built-in + plugins)."""
+    rows = _collect_builtin_templates()
+
+    # Merge plugin templates
+    try:
+        from pysnap.plugins import discover_plugins
+        for plugin in discover_plugins():
+            if plugin.get("type") == "framework":
+                rows.append({
+                    "name": plugin["name"],
+                    "display_name": plugin.get("display_name", plugin["name"]),
+                    "description": plugin.get("description", ""),
+                    "source": plugin.get("_plugin_name", "Plugin"),
+                })
+    except Exception:  # noqa: BLE001
+        pass
+
+    table = Table(title="Available Templates", show_header=True, header_style="bold cyan")
+    table.add_column("Name", style="bold")
+    table.add_column("Framework")
+    table.add_column("Description")
+    table.add_column("Source", style="dim")
+
+    for row in rows:
+        table.add_row(
+            row["name"],
+            row.get("display_name", row["name"]),
+            row.get("description", ""),
+            row.get("source", "Built-in"),
+        )
+
+    console.print(table)
+
+
+@templates_app.command(name="search")
+def templates_search(
+    keyword: Annotated[str, typer.Argument(help="Search keyword")],
+    framework: Annotated[
+        Optional[str],
+        typer.Option("--framework", "-f", help="Filter by framework"),
+    ] = None,
+) -> None:
+    """Search the community template registry."""
+    from pysnap.registry import fetch_registry, search_registry
+
+    console.print(f"[dim]Searching community registry for [bold]{keyword!r}[/bold]...[/dim]")
+
+    try:
+        entries = fetch_registry()
+    except Exception as exc:
+        console.print(f"[red]Error fetching registry:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    results = search_registry(entries, keyword, framework=framework)
+
+    if not results:
+        console.print("[yellow]No templates found matching your search.[/yellow]")
+        return
+
+    table = Table(
+        title=f"Community Templates -- '{keyword}'",
+        show_header=True,
+        header_style="bold cyan",
+    )
+    table.add_column("Name", style="bold")
+    table.add_column("Description")
+    table.add_column("Framework")
+    table.add_column("Stars", justify="right")
+    table.add_column("Author", style="dim")
+
+    for entry in results:
+        table.add_row(
+            entry.get("name", ""),
+            entry.get("description", ""),
+            entry.get("framework", ""),
+            str(entry.get("stars", 0)),
+            entry.get("author", ""),
+        )
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _collect_builtin_templates() -> list[dict]:
+    """Scan built-in template directories for template.json manifests."""
+    templates_dir = Path(__file__).parent.parent / "templates"
+    rows: list[dict] = []
+    if not templates_dir.is_dir():
+        return rows
+    for framework_dir in sorted(templates_dir.iterdir()):
+        manifest_path = framework_dir / "template.json"
+        if manifest_path.exists():
+            try:
+                data = json.loads(manifest_path.read_text(encoding="utf-8"))
+                rows.append({
+                    "name": data.get("name", framework_dir.name),
+                    "display_name": data.get("display_name", framework_dir.name),
+                    "description": data.get("description", ""),
+                    "source": "Built-in",
+                })
+            except Exception:  # noqa: BLE001
+                pass
+    return rows