snapstack 1.0.0__py3-none-any.whl

pysnap/manifest.py

@@ -0,0 +1,101 @@
+"""
+Read and write .pysnap.json manifest files.
+
+The manifest is stored in the root of every pysnap-generated project and
+records the template name, version, and user choices at scaffold time.
+It is used by ``pysnap update`` to re-render infrastructure files.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from pysnap.config import MANIFEST_FILENAME, MANIFEST_SCHEMA_VERSION, PYSNAP_VERSION
+
+
+def write_manifest(
+    project_path: Path,
+    template: str,
+    template_version: str,
+    options: dict[str, Any],
+    infrastructure_files: list[str],
+) -> Path:
+    """Write a .pysnap.json manifest to the generated project root.
+
+    Parameters
+    ----------
+    project_path:
+        Root directory of the generated project.
+    template:
+        Template name (e.g. "fastapi").
+    template_version:
+        Version string from the template manifest (e.g. "1.0.0").
+    options:
+        The complete ProjectOptions dict used during generation.
+    infrastructure_files:
+        List of relative paths (from project root) that are eligible
+        for ``pysnap update`` -- i.e. infrastructure-only files.
+
+    Returns
+    -------
+    Path
+        Absolute path to the written manifest file.
+    """
+    manifest: dict[str, Any] = {
+        "schema_version": MANIFEST_SCHEMA_VERSION,
+        "pysnap_version": PYSNAP_VERSION,
+        "template": template,
+        "template_version": template_version,
+        "options": _serializable_options(options),
+        "infrastructure_files": sorted(infrastructure_files),
+        "generated_at": datetime.now(tz=timezone.utc).isoformat(),
+    }
+    dest = project_path / MANIFEST_FILENAME
+    dest.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    return dest
+
+
+def read_manifest(project_path: Path) -> dict[str, Any]:
+    """Read and parse the .pysnap.json manifest from a project directory.
+
+    Parameters
+    ----------
+    project_path:
+        Root directory of the project (where .pysnap.json lives).
+
+    Returns
+    -------
+    dict
+        Parsed manifest contents.
+
+    Raises
+    ------
+    FileNotFoundError
+        If .pysnap.json does not exist in *project_path*.
+    ValueError
+        If the file exists but contains invalid JSON.
+    """
+    manifest_path = project_path / MANIFEST_FILENAME
+    if not manifest_path.exists():
+        raise FileNotFoundError(
+            f"No {MANIFEST_FILENAME} found in {project_path}. "
+            "This does not appear to be a pysnap-generated project."
+        )
+    try:
+        return json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Corrupt {MANIFEST_FILENAME}: {exc}") from exc
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _serializable_options(options: dict[str, Any]) -> dict[str, Any]:
+    """Return a JSON-serializable copy of *options* (drop derived fields)."""
+    skip = {"project_name_slug"}
+    return {k: v for k, v in options.items() if k not in skip}

pysnap/plugins.py

@@ -0,0 +1,123 @@
+"""
+Plugin discovery for pysnap.
+
+Plugins register themselves via Python entry points.  On install, their
+templates and options automatically appear in the create/add flows.
+
+Plugin authors publish a package that declares an entry point in the
+``pysnap.plugins`` group.  The entry point must be a callable that
+takes no arguments and returns a list of PluginRegistration dicts.
+
+Example pyproject.toml for a plugin:
+
+    [project.entry-points."pysnap.plugins"]
+    my-template = "my_package.plugin:register"
+
+Example register() function:
+
+    def register():
+        return [
+            {
+                "type": "framework",
+                "name": "my-framework",
+                "display_name": "My Framework",
+                "template_path": str(Path(__file__).parent / "templates" / "my-framework"),
+                "description": "A custom framework template",
+            }
+        ]
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import warnings
+from typing import Any
+
+from pysnap.config import SUPPORTED_DATABASES, SUPPORTED_FRAMEWORKS
+
+_REQUIRED_KEYS = {"type", "name", "display_name", "template_path"}
+_VALID_TYPES = {"framework", "database", "addon"}
+
+
+def discover_plugins() -> list[dict[str, Any]]:
+    """Discover and validate all installed pysnap plugins.
+
+    Returns
+    -------
+    list of plugin registration dicts
+        Each dict has at minimum: type, name, display_name, template_path.
+    """
+    try:
+        eps = importlib.metadata.entry_points(group="pysnap.plugins")
+    except Exception:  # noqa: BLE001
+        return []
+
+    plugins: list[dict[str, Any]] = []
+    for ep in eps:
+        try:
+            register_fn = ep.load()
+            registrations = register_fn()
+            if not isinstance(registrations, list):
+                registrations = [registrations]
+            for reg in registrations:
+                validated = _validate(reg, ep.name)
+                if validated:
+                    plugins.append(validated)
+        except Exception as exc:  # noqa: BLE001
+            warnings.warn(
+                f"pysnap plugin '{ep.name}' failed to load: {exc}",
+                stacklevel=2,
+            )
+
+    return plugins
+
+
+# ---------------------------------------------------------------------------
+# Internal
+# ---------------------------------------------------------------------------
+
+
+def _validate(reg: dict[str, Any], ep_name: str) -> dict[str, Any] | None:
+    """Validate a plugin registration dict.  Returns None if invalid."""
+    if not isinstance(reg, dict):
+        warnings.warn(
+            f"Plugin '{ep_name}' returned a non-dict registration.",
+            stacklevel=3,
+        )
+        return None
+
+    missing = _REQUIRED_KEYS - reg.keys()
+    if missing:
+        warnings.warn(
+            f"Plugin '{ep_name}' registration missing required keys: {missing}",
+            stacklevel=3,
+        )
+        return None
+
+    if reg["type"] not in _VALID_TYPES:
+        warnings.warn(
+            f"Plugin '{ep_name}' has invalid type {reg['type']!r}. "
+            f"Must be one of: {_VALID_TYPES}",
+            stacklevel=3,
+        )
+        return None
+
+    # Check for name conflicts with built-in options
+    if reg["type"] == "framework" and reg["name"] in SUPPORTED_FRAMEWORKS:
+        warnings.warn(
+            f"Plugin '{ep_name}' tried to register framework {reg['name']!r} "
+            "which conflicts with a built-in framework. Ignoring.",
+            stacklevel=3,
+        )
+        return None
+
+    if reg["type"] == "database" and reg["name"] in SUPPORTED_DATABASES:
+        warnings.warn(
+            f"Plugin '{ep_name}' tried to register database {reg['name']!r} "
+            "which conflicts with a built-in database. Ignoring.",
+            stacklevel=3,
+        )
+        return None
+
+    reg["_plugin_ep"] = ep_name
+    return reg

pysnap/preview.py

@@ -0,0 +1,131 @@
+"""
+Pre-generation file tree preview using Rich.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import questionary
+from rich.console import Console
+from rich.tree import Tree
+
+
+def build_preview_tree(template_map: dict[str, str], options: dict[str, Any]) -> Tree:
+    """Build a Rich Tree from the template map with optional file annotations.
+
+    Parameters
+    ----------
+    template_map:
+        Mapping of template filename -> output path (relative to project root).
+    options:
+        The current ProjectOptions dict (used to annotate optional files).
+
+    Returns
+    -------
+    rich.tree.Tree
+        A Rich Tree ready to render.
+    """
+    project_name = options.get("project_name", "project")
+    tree = Tree(f"[bold cyan]{project_name}/[/bold cyan]")
+
+    # Group output paths by top-level directory
+    dirs: dict[str, list[tuple[str, str | None]]] = {}
+    root_files: list[tuple[str, str | None]] = []
+
+    for tmpl_name, out_rel in template_map.items():
+        annotation = _annotation(out_rel, options)
+        parts = out_rel.split("/")
+        if len(parts) == 1:
+            root_files.append((out_rel, annotation))
+        else:
+            top = parts[0]
+            dirs.setdefault(top, []).append((out_rel, annotation))
+
+    # Root files first
+    for path, ann in sorted(root_files):
+        _add_leaf(tree, path, ann)
+
+    # Subdirectories
+    for dir_name, entries in sorted(dirs.items()):
+        subtree = tree.add(f"[bold]{dir_name}/[/bold]")
+        for full_path, ann in sorted(entries):
+            relative = "/".join(full_path.split("/")[1:])
+            _add_leaf(subtree, relative, ann)
+
+    return tree
+
+
+def show_preview(
+    template_map: dict[str, str],
+    options: dict[str, Any],
+    console: Console,
+) -> str:
+    """Render the preview tree and prompt the developer.
+
+    Returns
+    -------
+    str
+        One of: "confirm", "back", "cancel".
+    """
+    tree = build_preview_tree(template_map, options)
+    console.print()
+    console.print("[bold]Project preview:[/bold]")
+    console.print(tree)
+    console.print(
+        f"\n[dim]{len(template_map)} file(s) will be generated[/dim]\n"
+    )
+
+    answer = questionary.select(
+        "Proceed?",
+        choices=[
+            questionary.Choice("Looks good, generate!", value="confirm"),
+            questionary.Choice("Go back and change options", value="back"),
+            questionary.Choice("Cancel", value="cancel"),
+        ],
+    ).ask()
+
+    return answer or "cancel"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+_OPTIONAL_ANNOTATIONS = {
+    "Dockerfile": "Docker: Yes",
+    "docker-compose.yml": "Docker: Yes",
+    ".dockerignore": "Docker: Yes",
+    ".github/workflows/ci.yml": "CI: Yes",
+}
+
+_CONDITION_ANNOTATIONS = {
+    "when_docker": "Docker: Yes",
+    "when_ci": "CI: Yes",
+    "when_auth": "Auth: Yes",
+    "when_tests": "Tests: Yes",
+}
+
+
+def _annotation(out_path: str, options: dict[str, Any]) -> str | None:
+    # Known fixed-name infrastructure files
+    if out_path in _OPTIONAL_ANNOTATIONS:
+        return _OPTIONAL_ANNOTATIONS[out_path]
+    # Test files
+    if out_path.startswith("tests/"):
+        return "Tests: Yes"
+    # Auth files
+    if "auth" in out_path.lower() or "security" in out_path.lower():
+        return "Auth: Yes" if options.get("include_auth") else None
+    # db files
+    if "db" in out_path.lower() or "session" in out_path.lower():
+        return f"DB: {options.get('database', 'none')}"
+    return None
+
+
+def _add_leaf(parent: Tree, name: str, annotation: str | None) -> None:
+    if annotation:
+        parent.add(f"[green]{name}[/green]  [dim]({annotation})[/dim]")
+    else:
+        parent.add(name)

pysnap/prompts.py

@@ -0,0 +1,217 @@
+"""
+Interactive prompt logic for pysnap.
+
+Accepts a partial options dict (pre-filled from CLI flags) and only prompts
+for keys whose value is None.  Plugin-provided choices are merged into the
+framework and database selection lists.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import questionary
+
+from pysnap.config import (
+    DEFAULT_OPTIONS,
+    SUPPORTED_DATABASES,
+    SUPPORTED_FRAMEWORKS,
+    SUPPORTED_PACKAGE_MANAGERS,
+)
+
+# ---------------------------------------------------------------------------
+# Custom questionary theme matching pysnap branding
+# ---------------------------------------------------------------------------
+
+pysnap_style = questionary.Style(
+    [
+        ("qmark", "fg:#ff6b6b bold"),
+        ("question", "bold"),
+        ("answer", "fg:#6bffd4 bold"),
+        ("pointer", "fg:#ff6b6b bold"),
+        ("highlighted", "fg:#6bffd4 bold"),
+        ("selected", "fg:#6bffd4"),
+        ("separator", "fg:#6c5ce7"),
+        ("instruction", "fg:#aaaaaa"),
+        ("text", ""),
+        ("disabled", "fg:#858585 italic"),
+    ]
+)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def ask_project_options(partial: dict[str, Any | None]) -> dict[str, Any] | None:
+    """Prompt for any options that are None in *partial*.
+
+    Parameters
+    ----------
+    partial:
+        A dict with the same keys as DEFAULT_OPTIONS.  Keys with a non-None
+        value will skip their corresponding prompt.
+
+    Returns
+    -------
+    dict
+        Completed options dict, or None if the user cancelled.
+    """
+    try:
+        return _collect(partial)
+    except KeyboardInterrupt:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _collect(partial: dict[str, Any | None]) -> dict[str, Any] | None:
+    """Run only the prompts for options that are still None."""
+    options: dict[str, Any] = dict(partial)
+
+    # Merge plugin-provided choices (no-op if no plugins installed)
+    framework_choices = _framework_choices()
+    database_choices = _database_choices()
+
+    # --- Framework ---
+    if options.get("framework") is None:
+        answer = questionary.select(
+            "Which framework?",
+            choices=framework_choices,
+            default=_choice_by_value(framework_choices, DEFAULT_OPTIONS["framework"]),
+            style=pysnap_style,
+        ).ask()
+        if answer is None:
+            return None
+        options["framework"] = answer
+
+    # --- Database ---
+    if options.get("database") is None:
+        answer = questionary.select(
+            "Which database?",
+            choices=database_choices,
+            default=_choice_by_value(database_choices, DEFAULT_OPTIONS["database"]),
+            style=pysnap_style,
+        ).ask()
+        if answer is None:
+            return None
+        options["database"] = answer
+
+    # --- Auth ---
+    if options.get("include_auth") is None:
+        answer = questionary.confirm(
+            "Include JWT authentication?",
+            default=DEFAULT_OPTIONS["include_auth"],
+            style=pysnap_style,
+        ).ask()
+        if answer is None:
+            return None
+        options["include_auth"] = answer
+
+    # --- Docker ---
+    if options.get("include_docker") is None:
+        answer = questionary.confirm(
+            "Include Docker (Dockerfile + docker-compose)?",
+            default=DEFAULT_OPTIONS["include_docker"],
+            style=pysnap_style,
+        ).ask()
+        if answer is None:
+            return None
+        options["include_docker"] = answer
+
+    # --- CI ---
+    if options.get("include_ci") is None:
+        answer = questionary.confirm(
+            "Include GitHub Actions CI?",
+            default=DEFAULT_OPTIONS["include_ci"],
+            style=pysnap_style,
+        ).ask()
+        if answer is None:
+            return None
+        options["include_ci"] = answer
+
+    # --- Package manager ---
+    if options.get("package_manager") is None:
+        pm_choices = [
+            questionary.Choice("uv  (recommended)", value="uv"),
+            questionary.Choice("pip", value="pip"),
+            questionary.Choice("poetry", value="poetry"),
+        ]
+        answer = questionary.select(
+            "Which package manager?",
+            choices=pm_choices,
+            default=pm_choices[0],
+            style=pysnap_style,
+        ).ask()
+        if answer is None:
+            return None
+        options["package_manager"] = answer
+
+    # --- Tests ---
+    if options.get("include_tests") is None:
+        answer = questionary.confirm(
+            "Include pytest test suite?",
+            default=DEFAULT_OPTIONS["include_tests"],
+            style=pysnap_style,
+        ).ask()
+        if answer is None:
+            return None
+        options["include_tests"] = answer
+
+    return options
+
+
+def _framework_choices() -> list[questionary.Choice]:
+    choices = [
+        questionary.Choice(f"{display}  (built-in)", value=key)
+        for key, display in SUPPORTED_FRAMEWORKS.items()
+    ]
+    # Merge plugin-provided framework choices
+    try:
+        from pysnap.plugins import discover_plugins
+
+        for plugin in discover_plugins():
+            if plugin.get("type") == "framework":
+                choices.append(
+                    questionary.Choice(
+                        f"{plugin['display_name']}  (plugin)",
+                        value=plugin["name"],
+                    )
+                )
+    except Exception:  # noqa: BLE001
+        pass
+    return choices
+
+
+def _database_choices() -> list[questionary.Choice]:
+    choices = [
+        questionary.Choice(display, value=key)
+        for key, display in SUPPORTED_DATABASES.items()
+    ]
+    # Merge plugin-provided database choices
+    try:
+        from pysnap.plugins import discover_plugins
+
+        for plugin in discover_plugins():
+            if plugin.get("type") == "database":
+                choices.append(
+                    questionary.Choice(
+                        f"{plugin['display_name']}  (plugin)",
+                        value=plugin["name"],
+                    )
+                )
+    except Exception:  # noqa: BLE001
+        pass
+    return choices
+
+
+def _choice_by_value(choices: list[questionary.Choice], value: str) -> questionary.Choice:
+    """Return the Choice whose value matches *value*, or the first choice."""
+    for c in choices:
+        if c.value == value:
+            return c
+    return choices[0]

pysnap/registry.py

@@ -0,0 +1,123 @@
+"""
+Community template registry client.
+
+Fetches the curated template list from the pysnap GitHub repository and
+supports filtering by keyword and framework.  Results are cached locally
+for REGISTRY_CACHE_TTL_SECONDS seconds.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from pysnap.config import REGISTRY_CACHE_PATH, REGISTRY_CACHE_TTL_SECONDS, REGISTRY_URL
+
+
+def fetch_registry(url: str = REGISTRY_URL) -> list[dict[str, Any]]:
+    """Fetch the community registry, using a local cache when fresh.
+
+    Parameters
+    ----------
+    url:
+        Override the registry URL (used in tests to inject mock data).
+
+    Returns
+    -------
+    list of RegistryEntry dicts.
+
+    Raises
+    ------
+    OSError / urllib.error.URLError
+        When the registry cannot be reached and there is no cached copy.
+    """
+    # Try cache first
+    cached = _load_cache()
+    if cached is not None:
+        return cached
+
+    # Fetch from network
+    entries = _download(url)
+    _save_cache(entries)
+    return entries
+
+
+def search_registry(
+    entries: list[dict[str, Any]],
+    keyword: str,
+    *,
+    framework: str | None = None,
+) -> list[dict[str, Any]]:
+    """Filter registry entries by *keyword* and optional *framework*.
+
+    Parameters
+    ----------
+    entries:
+        Full list of RegistryEntry dicts.
+    keyword:
+        Case-insensitive search term matched against name, description, tags.
+    framework:
+        Optional framework filter (exact match on the ``framework`` field).
+
+    Returns
+    -------
+    Filtered list, sorted by stars descending.
+    """
+    kw = keyword.lower()
+    results: list[dict[str, Any]] = []
+
+    for entry in entries:
+        # Framework filter
+        if framework and entry.get("framework", "").lower() != framework.lower():
+            continue
+
+        # Keyword match
+        searchable = " ".join([
+            entry.get("name", ""),
+            entry.get("description", ""),
+            " ".join(entry.get("tags", [])),
+        ]).lower()
+
+        if kw in searchable:
+            results.append(entry)
+
+    # Sort by stars descending
+    results.sort(key=lambda e: e.get("stars", 0), reverse=True)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Cache helpers
+# ---------------------------------------------------------------------------
+
+
+def _load_cache() -> list[dict] | None:
+    if not REGISTRY_CACHE_PATH.exists():
+        return None
+    try:
+        data = json.loads(REGISTRY_CACHE_PATH.read_text(encoding="utf-8"))
+        fetched_at = data.get("_fetched_at", 0)
+        if time.time() - fetched_at < REGISTRY_CACHE_TTL_SECONDS:
+            return data.get("entries", [])
+    except Exception:  # noqa: BLE001
+        pass
+    return None
+
+
+def _save_cache(entries: list[dict]) -> None:
+    REGISTRY_CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"_fetched_at": time.time(), "entries": entries}
+    REGISTRY_CACHE_PATH.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+
+def _download(url: str) -> list[dict]:
+    req = urllib.request.Request(url, headers={"User-Agent": "pysnap-cli"})
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        raise OSError(f"Cannot reach registry at {url}: {exc}") from exc