spawnio 1.0.5__py3-none-any.whl

spawn/core/exceptions.py

@@ -0,0 +1,7 @@
+class SpawnError(Exception):
+    """Base exception for Spawn."""
+    pass
+
+
+class StructureParseError(SpawnError):
+    """Raised when pasted structure text cannot be parsed."""

spawn/core/models.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ProjectConfig:
+    name: str
+    template: str
+    use_git: bool
+    framework: str | None = None
+    extras: list[str] = field(default_factory=list)
+    cli_type: str | None = None
+    data_type: str | None = None
+    provider: str | None = None
+    use_uv: bool = True
+    generate_claude_md: bool = False
+    custom_entries: list | None = None   # list[ParsedEntry] when template == "custom"
+    custom_dependencies: list[str] = field(default_factory=list)
+    custom_dev_setup: list[str] = field(default_factory=list)
+    # subset of ["ruff", "pytest", "precommit", "dockerfile"]
+    custom_gitignore_extra: list[str] = field(default_factory=list)
+    custom_source_format: str | None = None  # "tree" | "markdown" | "indented"

spawn/core/registry.py

@@ -0,0 +1,152 @@
+import inspect
+from dataclasses import dataclass, field
+
+from spawn.core.models import ProjectConfig
+from spawn.templates.backend_api import BackendAPITemplate
+from spawn.templates.cli_application import CLITemplate
+from spawn.templates.automation import AutomationTemplate
+from spawn.templates.chatbot import ChatbotTemplate
+from spawn.templates.agent import AgentTemplate
+from spawn.templates.rag import RAGTemplate
+from spawn.templates.data_project import DataProjectTemplate
+from spawn.templates.mcp_server import MCPServerTemplate
+from spawn.templates.base import BaseTemplate
+
+
+@dataclass
+class TemplateMetadata:
+    slug: str
+    display_name: str
+    description: str
+    template_class: type
+    available_frameworks: list[str] = field(default_factory=list)
+    available_extras: list[str] = field(default_factory=list)
+    available_cli_types: list[str] = field(default_factory=list)
+    available_providers: list[str] = field(default_factory=list)
+    available_data_types: list[str] = field(default_factory=list)
+
+
+# Slugs that existed in previous versions but have been superseded.
+# get_template() returns None for these, which surfaces as a clear
+# SpawnError("Unknown template: fastapi") in the generator.
+_REMOVED_SLUGS = {"fastapi", "python"}
+
+TEMPLATES: dict[str, TemplateMetadata] = {
+    "backend-api": TemplateMetadata(
+        slug="backend-api",
+        display_name="Backend API",
+        description="Production-ready backend with FastAPI, Flask, or Django",
+        template_class=BackendAPITemplate,
+        available_frameworks=["fastapi", "flask", "django"],
+        available_extras=["ruff", "pytest", "docker", "github-actions"],
+    ),
+    "cli": TemplateMetadata(
+        slug="cli",
+        display_name="CLI Application",
+        description="Command-line application with Typer, Click, or Argparse",
+        template_class=CLITemplate,
+        available_frameworks=["typer", "click", "argparse"],
+        available_extras=["ruff", "pytest", "github-actions"],
+        available_cli_types=["utility", "interactive"],
+    ),
+    "automation": TemplateMetadata(
+        slug="automation",
+        display_name="Automation Tool",
+        description="Workflow-based automation with logging, tasks, and integrations",
+        template_class=AutomationTemplate,
+        available_extras=["ruff", "pytest", "github-actions"],
+    ),
+    "chatbot": TemplateMetadata(
+        slug="chatbot",
+        display_name="AI Chatbot",
+        description="Conversational AI with PydanticAI, OpenAI SDK, or LiteLLM",
+        template_class=ChatbotTemplate,
+        available_frameworks=["pydantic-ai", "openai-sdk", "litellm"],
+        available_providers=["openai", "anthropic", "gemini", "openrouter", "ollama", "groq"],
+        available_extras=["ruff", "pytest", "rich", "github-actions"],
+    ),
+    "agent": TemplateMetadata(
+        slug="agent",
+        display_name="AI Agent",
+        description="Tool-calling agent with PydanticAI or OpenAI Agents SDK",
+        template_class=AgentTemplate,
+        available_frameworks=["pydantic-ai", "openai-agents"],
+        available_providers=["openai", "anthropic", "gemini", "openrouter", "ollama", "groq"],
+        available_extras=["ruff", "pytest", "github-actions"],
+    ),
+    "rag": TemplateMetadata(
+        slug="rag",
+        display_name="RAG System",
+        description="Retrieval-Augmented Generation with LlamaIndex and ChromaDB",
+        template_class=RAGTemplate,
+        available_extras=["ruff", "pytest", "github-actions"],
+    ),
+    "data": TemplateMetadata(
+        slug="data",
+        display_name="Data Project",
+        description="Data Analysis, Dashboard, ETL Pipeline, or Machine Learning project",
+        template_class=DataProjectTemplate,
+        available_extras=["ruff", "pytest", "github-actions"],
+        available_data_types=["Data Analysis", "Dashboard", "ETL Pipeline", "Machine Learning"],
+    ),
+    "mcp": TemplateMetadata(
+        slug="mcp",
+        display_name="MCP Server",
+        description="Model Context Protocol server with the official Python SDK",
+        template_class=MCPServerTemplate,
+        available_extras=["ruff", "pytest", "github-actions"],
+    ),
+}
+
+
+def get_template(template_name: str) -> BaseTemplate | None:
+    """Return a no-argument template instance. Used by tests and CLI helpers."""
+    metadata = TEMPLATES.get(template_name)
+
+    if metadata is None:
+        return None
+
+    return metadata.template_class()
+
+
+def instantiate_template(config: ProjectConfig) -> BaseTemplate | None:
+    """
+    Instantiate a template from a fully-populated ProjectConfig.
+
+    For templates that accept framework/extras (e.g. BackendAPITemplate),
+    those values are forwarded from config. For all other templates the
+    no-argument constructor is used, so existing behaviour is unchanged.
+    """
+    metadata = TEMPLATES.get(config.template)
+
+    if metadata is None:
+        return None
+
+    cls = metadata.template_class
+
+    # Forward framework and extras only when the constructor accepts them.
+    # Introspecting the signature avoids coupling the registry to each
+    # template class individually.
+    params = set(inspect.signature(cls.__init__).parameters)
+
+    kwargs: dict = {}
+    if "framework" in params:
+        kwargs["framework"] = config.framework
+    if "extras" in params:
+        kwargs["extras"] = config.extras
+    if "cli_type" in params:
+        kwargs["cli_type"] = config.cli_type
+    if "provider" in params:
+        kwargs["provider"] = config.provider
+    if "data_type" in params:
+        kwargs["data_type"] = config.data_type
+
+    return cls(**kwargs)
+
+
+def get_metadata(template_name: str) -> TemplateMetadata | None:
+    return TEMPLATES.get(template_name)
+
+
+def list_templates() -> list[TemplateMetadata]:
+    return list(TEMPLATES.values())

spawn/generators/custom_structure.py

@@ -0,0 +1,508 @@
+"""
+Parse pasted folder-structure text into a flat list of (path, is_file) entries,
+and generate the filesystem structure from parsed entries.
+
+Supported input formats:
+  tree      — uses ├──, └──, │ connectors (standard Unix tree output)
+  markdown  — lines starting with optional whitespace + "- " or "* "
+  indented  — plain indentation (tabs or spaces), no bullets or tree chars
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from spawn.core.exceptions import SpawnError, StructureParseError
+from spawn.utils.console import console
+from spawn.utils.git import initialize_git
+from spawn.utils.uv import initialize_uv, install_packages
+
+# Tree connector characters
+_TREE_CHARS = {"├", "└", "│"}
+_TREE_CONNECTOR_RE = re.compile(r"^[\s│]*[├└]──\s*")
+_MARKDOWN_LINE_RE = re.compile(r"^(\s*)[-*]\s+")
+
+
+@dataclass
+class ParsedEntry:
+    path: str       # relative path, forward-slash separated
+    is_file: bool   # True if entry has a file extension or no trailing "/"
+
+
+# ─── Helpers ──────────────────────────────────────────────────────────────
+
+
+_KNOWN_EXTENSIONLESS_FILES = {
+    "license",
+    "licence",
+    "dockerfile",
+    "makefile",
+    "procfile",
+    "changelog",
+    "authors",
+    "contributing",
+    "codeowners",
+    "readme",  # bare "README" with no extension, distinct from README.md
+}
+
+
+def _is_file_entry(name: str) -> bool:
+    """
+    Decide whether a name represents a file or a folder.
+
+    Rules (in priority order):
+    1. Trailing "/" → always folder.
+    2. Starts with "." (dotfile like .env, .gitignore) → file.
+    3. Contains a "." after the last "/" segment → file.
+    4. Name is a known extension-less filename (LICENSE, Dockerfile, etc.) → file.
+    5. Anything else → folder.
+    """
+    if name.endswith("/"):
+        return False
+    segment = name.rsplit("/", 1)[-1]
+    if segment.startswith("."):
+        return True
+    if "." in segment:
+        return True
+    if segment.lower() in _KNOWN_EXTENSIONLESS_FILES:
+        return True
+    return False
+
+
+def _strip_name(name: str) -> str:
+    """Remove trailing slash and inline comments."""
+    name = re.sub(r"\s*#.*$", "", name).strip()
+    return name.rstrip("/")
+
+
+# ─── Format detection ─────────────────────────────────────────────────────
+
+
+def detect_format(raw: str) -> str:
+    """Return 'tree', 'markdown', or 'indented'."""
+    for line in raw.splitlines():
+        if any(c in line for c in _TREE_CHARS):
+            return "tree"
+    for line in raw.splitlines():
+        if _MARKDOWN_LINE_RE.match(line):
+            return "markdown"
+    return "indented"
+
+
+# ─── Per-format depth extraction ──────────────────────────────────────────
+
+
+def _tree_depth_and_name(line: str) -> tuple[int, str] | None:
+    stripped = line.rstrip()
+    if not stripped:
+        return None
+
+    # Root line: no tree characters
+    if not any(c in stripped for c in _TREE_CHARS):
+        name = _strip_name(stripped.lstrip())
+        if not name:
+            return None
+        return (0, name)
+
+    match = re.match(r"^([\s│]*)[├└]──\s*(.+)$", stripped)
+    if not match:
+        return None
+    prefix, name = match.group(1), match.group(2).rstrip()
+    name = _strip_name(name)
+    if not name:
+        return None
+    depth = len(prefix) // 4 + 1
+    return (depth, name)
+
+
+def _markdown_depth_and_name(line: str, indent_unit: int) -> tuple[int, str] | None:
+    match = _MARKDOWN_LINE_RE.match(line)
+    if not match:
+        stripped = line.strip()
+        if not stripped:
+            return None
+        return (0, _strip_name(stripped))
+    spaces = len(match.group(1))
+    name = _strip_name(line[match.end():].strip())
+    if not name:
+        return None
+    depth = (spaces // indent_unit + 1) if indent_unit > 0 else 1
+    return (depth, name)
+
+
+def _indented_depth_and_name(
+    line: str, indent_unit: int | None
+) -> tuple[int, str, int | None]:
+    stripped = line.rstrip()
+    if not stripped or not stripped.strip():
+        return (-1, "", indent_unit)
+
+    leading = len(stripped) - len(stripped.lstrip())
+    name = _strip_name(stripped.strip())
+    if not name:
+        return (-1, "", indent_unit)
+
+    if leading == 0:
+        return (0, name, indent_unit)
+
+    if indent_unit is None:
+        indent_unit = leading
+
+    depth = leading // indent_unit
+    return (depth, name, indent_unit)
+
+
+# ─── Main parser ──────────────────────────────────────────────────────────
+
+
+def parse_structure(raw: str) -> list[ParsedEntry]:
+    """
+    Parse raw pasted text into a flat list of ParsedEntry with full
+    relative paths.
+
+    Raises StructureParseError for empty input, malformed indentation,
+    or duplicate paths.
+    """
+    lines = [ln for ln in raw.splitlines() if ln.strip()]
+    if not lines:
+        raise StructureParseError("Input is empty — no structure to parse.")
+
+    fmt = detect_format(raw)
+
+    if fmt == "tree":
+        depth_name_pairs = _parse_tree_lines(lines)
+    elif fmt == "markdown":
+        depth_name_pairs = _parse_markdown_lines(lines)
+    else:
+        depth_name_pairs = _parse_indented_lines(lines)
+
+    return _build_entries(depth_name_pairs)
+
+
+def _parse_tree_lines(lines: list[str]) -> list[tuple[int, str]]:
+    result = []
+    for line in lines:
+        parsed = _tree_depth_and_name(line)
+        if parsed is None:
+            continue
+        result.append(parsed)
+    return result
+
+
+def _parse_markdown_lines(lines: list[str]) -> list[tuple[int, str]]:
+    indent_unit = 2
+    space_counts = []
+    for line in lines:
+        m = _MARKDOWN_LINE_RE.match(line)
+        if m:
+            spaces = len(m.group(1))
+            if spaces > 0:
+                space_counts.append(spaces)
+    if space_counts:
+        indent_unit = min(space_counts)
+
+    result = []
+    for line in lines:
+        parsed = _markdown_depth_and_name(line, indent_unit)
+        if parsed is None:
+            continue
+        result.append(parsed)
+    return result
+
+
+def _parse_indented_lines(lines: list[str]) -> list[tuple[int, str]]:
+    indent_unit: int | None = None
+    result = []
+    for line in lines:
+        depth, name, indent_unit = _indented_depth_and_name(line, indent_unit)
+        if depth < 0 or not name:
+            continue
+        result.append((depth, name))
+    return result
+
+
+def _build_entries(
+    depth_name_pairs: list[tuple[int, str]],
+) -> list[ParsedEntry]:
+    if not depth_name_pairs:
+        raise StructureParseError("No parseable entries found in input.")
+
+    # Normalise so the shallowest entry is always at depth 0
+    min_depth = min(d for d, _ in depth_name_pairs)
+    if min_depth != 0:
+        depth_name_pairs = [(d - min_depth, n) for d, n in depth_name_pairs]
+
+    entries: list[ParsedEntry] = []
+    seen: set[str] = set()
+    stack: list[str] = [""]
+    prev_depth = -1
+
+    for depth, name in depth_name_pairs:
+        if depth > prev_depth + 1:
+            raise StructureParseError(
+                f"Entry '{name}' is indented {depth} level(s) deep but the "
+                f"previous depth was {prev_depth} — missing intermediate parent."
+            )
+
+        del stack[depth + 1:]
+
+        parent = stack[depth] if depth < len(stack) else stack[-1]
+        full_path = f"{parent}/{name}".lstrip("/") if parent else name
+
+        is_file = _is_file_entry(name)
+
+        if full_path in seen:
+            raise StructureParseError(
+                f"Duplicate path '{full_path}' declared more than once."
+            )
+        seen.add(full_path)
+
+        entries.append(ParsedEntry(path=full_path, is_file=is_file))
+
+        if not is_file:
+            if depth + 1 >= len(stack):
+                stack.append(full_path)
+            else:
+                stack[depth + 1] = full_path
+
+        prev_depth = depth
+
+    return entries
+
+
+# ─── README helpers ───────────────────────────────────────────────────────
+
+
+# ─── .gitignore helper ────────────────────────────────────────────────────
+
+
+def _build_gitignore_content(extra_patterns: list[str]) -> str:
+    """Return .gitignore content: Python defaults + deduplicated extra patterns."""
+    from spawn.templates.shared_content import GITIGNORE_CONTENT
+
+    existing_lines = {
+        ln.strip() for ln in GITIGNORE_CONTENT.splitlines() if ln.strip()
+    }
+    new_lines = [p for p in extra_patterns if p not in existing_lines]
+    if not new_lines:
+        return GITIGNORE_CONTENT
+    return (
+        GITIGNORE_CONTENT.rstrip()
+        + "\n\n# Custom\n"
+        + "\n".join(new_lines)
+        + "\n"
+    )
+
+
+
+def _render_tree(entries: list[ParsedEntry]) -> str:
+    """Render parsed entries as a normalised indented tree string."""
+    lines = []
+    for entry in entries:
+        depth = entry.path.count("/")
+        indent = "  " * depth
+        name = entry.path.rsplit("/", 1)[-1]
+        suffix = "" if entry.is_file else "/"
+        lines.append(f"{indent}{name}{suffix}")
+    return "\n".join(lines)
+
+
+def _build_readme_content(
+    project_name: str, entries: list[ParsedEntry], use_uv: bool
+) -> str:
+    """Return generated README.md content for a custom-structure project."""
+    tree_lines = _render_tree(entries)
+    setup_line = "uv sync" if use_uv else "# Set up your environment"
+    return (
+        f"# {project_name}\n\n"
+        "Generated by Spawn\n\n"
+        "## Project Structure\n\n"
+        "```\n"
+        f"{tree_lines}\n"
+        "```\n\n"
+        "## Setup\n\n"
+        "```bash\n"
+        f"{setup_line}\n"
+        "```\n\n"
+        "## Run\n\n"
+        "Add project run instructions here.\n"
+    )
+
+
+def _build_agents_md_content(project_name: str, entries: list[ParsedEntry]) -> str:
+    """Return generated AGENTS.md content for a custom-structure project."""
+    tree_lines = _render_tree(entries)
+    return (
+        f"# Agent Context: {project_name}\n\n"
+        "This file orients coding agents working in this repository.\n\n"
+        "## Project Structure\n\n"
+        "```\n"
+        f"{tree_lines}\n"
+        "```\n\n"
+        "## Setup\n\n"
+        "See README.md for setup instructions.\n"
+    )
+
+
+# ─── Filesystem generator ─────────────────────────────────────────────────
+
+
+class CustomStructureGenerator:
+    def generate(
+        self,
+        project_name: str,
+        entries: list[ParsedEntry],
+        use_git: bool = False,
+        use_uv: bool = True,
+        dependencies: list[str] | None = None,
+        dev_setup: list[str] | None = None,
+        gitignore_extra: list[str] | None = None,
+        generate_claude_md: bool = False,
+    ) -> Path:
+        """
+        Create the folder/file structure described by *entries* under a new
+        directory named *project_name* in the current working directory.
+
+        Raises SpawnError if the directory already exists or an OS error
+        occurs.  Rolls back on any failure.
+        """
+        project_path = Path(project_name)
+
+        if project_path.exists():
+            raise SpawnError(f"Directory '{project_name}' already exists.")
+
+        try:
+            project_path.mkdir()
+
+            for entry in entries:
+                if entry.path == "pyproject.toml" and use_uv:
+                    continue  # uv init --bare will create this
+                if entry.path == ".git" or entry.path.startswith(".git/"):
+                    continue  # git init will create/manage this
+                full_path = project_path / entry.path
+                if entry.is_file:
+                    full_path.parent.mkdir(parents=True, exist_ok=True)
+                    full_path.touch()
+                else:
+                    full_path.mkdir(parents=True, exist_ok=True)
+
+            readme_entry = next(
+                (
+                    e for e in entries
+                    if e.path == "README.md" or e.path.endswith("/README.md")
+                ),
+                None,
+            )
+            if readme_entry is not None:
+                readme_path = project_path / readme_entry.path
+                readme_path.write_text(
+                    _build_readme_content(project_name, entries, use_uv),
+                    encoding="utf-8",
+                )
+
+            agents_md_entry = next(
+                (
+                    e for e in entries
+                    if e.path == "AGENTS.md" or e.path.endswith("/AGENTS.md")
+                ),
+                None,
+            )
+            if agents_md_entry is not None:
+                agents_md_path = project_path / agents_md_entry.path
+                agents_md_path.write_text(
+                    _build_agents_md_content(project_name, entries),
+                    encoding="utf-8",
+                )
+
+            if generate_claude_md and agents_md_entry is not None:
+                claude_md_path = project_path / agents_md_entry.path.replace("AGENTS.md", "CLAUDE.md")
+                claude_md_path.write_text(
+                    _build_agents_md_content(project_name, entries),
+                    encoding="utf-8",
+                )
+
+            gitignore_entry = next(
+                (
+                    e for e in entries
+                    if e.path == ".gitignore" or e.path.endswith("/.gitignore")
+                ),
+                None,
+            )
+            if gitignore_entry is not None:
+                gitignore_path = project_path / gitignore_entry.path
+                gitignore_path.write_text(
+                    _build_gitignore_content(gitignore_extra or []),
+                    encoding="utf-8",
+                )
+
+            if use_git:
+                console.print("[yellow]Initializing Git...[/yellow]")
+                initialize_git(project_path)
+
+            if use_uv:
+                initialize_uv(project_path)
+
+            if use_uv and dependencies:
+                console.print("[yellow]Installing dependencies...[/yellow]")
+                install_packages(project_path, dependencies)
+
+            if use_uv and dev_setup:
+                self._apply_dev_setup(project_path, dev_setup)
+
+        except OSError as e:
+            shutil.rmtree(project_path, ignore_errors=True)
+            raise SpawnError(str(e)) from e
+
+        except BaseException:
+            shutil.rmtree(project_path, ignore_errors=True)
+            raise
+
+        return project_path
+
+    def _apply_dev_setup(self, project_path: Path, dev_setup: list[str]) -> None:
+        """Install dev tools and generate their config files."""
+        dev_deps: list[str] = []
+        if "ruff" in dev_setup:
+            dev_deps.append("ruff")
+        if "pytest" in dev_setup:
+            dev_deps.append("pytest")
+        if "precommit" in dev_setup:
+            dev_deps.append("pre-commit")
+
+        if dev_deps:
+            console.print("[yellow]Installing dev tools...[/yellow]")
+            install_packages(project_path, dev_deps, dev=True)
+
+        if "ruff" in dev_setup:
+            (project_path / "ruff.toml").write_text(
+                'line-length = 88\ntarget-version = "py312"\n',
+                encoding="utf-8",
+            )
+
+        if "pytest" in dev_setup:
+            tests_dir = project_path / "tests"
+            tests_dir.mkdir(exist_ok=True)
+            (tests_dir / "__init__.py").touch()
+
+        if "precommit" in dev_setup:
+            (project_path / ".pre-commit-config.yaml").write_text(
+                "repos:\n"
+                "  - repo: https://github.com/astral-sh/ruff-pre-commit\n"
+                "    rev: v0.15.16\n"
+                "    hooks:\n"
+                "      - id: ruff\n",
+                encoding="utf-8",
+            )
+
+        if "dockerfile" in dev_setup:
+            (project_path / "Dockerfile").write_text(
+                "FROM python:3.12-slim\n"
+                "WORKDIR /app\n"
+                "COPY . .\n"
+                "RUN pip install uv && uv sync\n"
+                'CMD ["python", "-m", "src.main"]\n',
+                encoding="utf-8",
+            )