spawnio 1.0.5__py3-none-any.whl

spawn/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("spawn")
+except PackageNotFoundError:
+    __version__ = "1.0.5"

spawn/cli/app.py

@@ -0,0 +1,218 @@
+import datetime
+import json
+from pathlib import Path
+
+import typer
+from rich.prompt import Confirm, Prompt
+
+from spawn import __version__
+from spawn.cli.noninteractive import build_config_from_args, build_config_from_file
+from spawn.cli.prompts import get_project_config
+from spawn.generators.project_generator import ProjectGenerator
+from spawn.github.publisher import GitHubPublisher
+from spawn.github.exceptions import GitHubPublishError
+from spawn.utils.banner import show_banner
+from spawn.utils.success import show_success
+from spawn.utils.console import console
+from spawn.core.exceptions import SpawnError
+from spawn.core.registry import instantiate_template
+
+app = typer.Typer()
+
+
+@app.callback(invoke_without_command=True)
+def main_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is not None:
+        return
+
+    show_banner()
+    console.print(f"[dim]v{__version__}[/dim]\n")
+    console.print("[bold]Commands[/bold]")
+    console.print("  [cyan]create[/cyan]    Scaffold a new project")
+    console.print("  [cyan]doctor[/cyan]    Check the health of a project directory")
+    console.print("  [cyan]version[/cyan]   Show the installed version")
+    console.print("\n[dim]Run [cyan]spawn COMMAND --help[/cyan] for details on a command.[/dim]\n")
+
+
+def _write_custom_metadata(project_path, config) -> None:
+    meta_dir = project_path / ".spawn"
+    meta_dir.mkdir(exist_ok=True)
+    (meta_dir / "meta.json").write_text(
+        json.dumps(
+            {
+                "intent": "custom",
+                "framework": None,
+                "provider": None,
+                "spawn_version": __version__,
+                "created_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+                "generator": "custom",
+                "git": config.use_git,
+                "uv": config.use_uv,
+                "source": config.custom_source_format or "tree",
+            },
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+
+
+@app.command()
+def create(
+    name: str = typer.Option(None, "--name", help="Project name (enables non-interactive mode)"),
+    template: str = typer.Option(None, "--template", help="Template slug: backend-api, cli, automation, chatbot, agent, rag, data"),
+    framework: str = typer.Option(None, "--framework", help="Framework choice for templates that support it"),
+    provider: str = typer.Option(None, "--provider", help="AI provider choice for chatbot/agent templates"),
+    cli_type: str = typer.Option(None, "--cli-type", help="CLI type for the cli template: utility or interactive"),
+    data_type: str = typer.Option(None, "--data-type", help="Project type for the data template"),
+    extras: str = typer.Option(None, "--extras", help="Comma-separated list of extras, e.g. ruff,pytest"),
+    git: bool = typer.Option(True, "--git/--no-git", help="Initialize a Git repository"),
+    uv: bool = typer.Option(True, "--uv/--no-uv", help="Initialize a uv environment and install dependencies"),
+    claude_md: bool = typer.Option(False, "--claude-md/--no-claude-md", help="Also generate CLAUDE.md alongside AGENTS.md"),
+    config_file: str = typer.Option(None, "--config", help="Path to a JSON config file (overrides other flags)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the GitHub publish prompt"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Validate and print the resolved config without creating a project"),
+) -> None:
+    try:
+        non_interactive = config_file is not None or name is not None
+
+        if non_interactive:
+            try:
+                if config_file is not None:
+                    config = build_config_from_file(Path(config_file), use_claude_md=claude_md)
+                else:
+                    if template is None:
+                        raise SpawnError("--template is required when using --name without --config.")
+                    extras_list = [e.strip() for e in extras.split(",") if e.strip()] if extras else []
+                    config = build_config_from_args(
+                        name=name,
+                        template=template,
+                        framework=framework,
+                        provider=provider,
+                        cli_type=cli_type,
+                        data_type=data_type,
+                        extras=extras_list,
+                        use_git=git,
+                        use_uv=uv,
+                        use_claude_md=claude_md,
+                    )
+            except SpawnError as e:
+                console.print(f"[red]❌ {e}[/red]")
+                raise typer.Exit(1)
+
+            if dry_run:
+                console.print("[green]✓ Config valid[/green]")
+                console.print(config)
+                return
+        else:
+            show_banner()
+            config = get_project_config()
+
+        try:
+            if config.template == "custom":
+                from spawn.generators.custom_structure import CustomStructureGenerator
+                project_path = CustomStructureGenerator().generate(
+                    project_name=config.name,
+                    entries=config.custom_entries or [],
+                    use_git=config.use_git,
+                    use_uv=config.use_uv,
+                    dependencies=config.custom_dependencies,
+                    dev_setup=config.custom_dev_setup,
+                    gitignore_extra=config.custom_gitignore_extra,
+                    generate_claude_md=config.generate_claude_md,
+                )
+                _write_custom_metadata(project_path, config)
+                next_steps = [
+                    f"cd {config.name}",
+                    "Start building your project",
+                ]
+                show_success(
+                    project_name=config.name,
+                    template_name="Custom Structure",
+                    use_git=config.use_git,
+                    next_steps=next_steps,
+                )
+            else:
+                project_path = ProjectGenerator().generate(config)
+                template_obj = instantiate_template(config)
+                if template_obj is not None:
+                    show_success(
+                        project_name=config.name,
+                        template_name=template_obj.name,
+                        use_git=config.use_git,
+                        next_steps=template_obj.next_steps,
+                    )
+
+        except SpawnError as e:
+            console.print(f"[red]❌ {e}[/red]")
+            return
+
+        if not config.use_git:
+            console.print(
+                "\n[yellow]ℹ GitHub publishing requires Git. Skipping.[/yellow]"
+            )
+            return
+
+        if non_interactive or yes:
+            return
+
+        publish_to_github = Confirm.ask(
+            "\nPublish to GitHub?",
+            default=False,
+        )
+
+        if not publish_to_github:
+            return
+
+        repo_url = Prompt.ask("Repository URL")
+
+        publisher = GitHubPublisher()
+
+        try:
+            publisher.publish(project_path, repo_url)
+            console.print("[green]🚀 Published successfully![/green]")
+
+        except GitHubPublishError as e:
+            console.print(f"[red]❌ {e}[/red]")
+    except (KeyboardInterrupt, EOFError, typer.Abort):
+        console.print("\n[yellow]Cancelled.[/yellow]")
+        raise typer.Exit(130)
+
+
+@app.command()
+def version():
+    """Show application version."""
+    typer.echo(f"Spawn v{__version__}")
+
+
+@app.command()
+def doctor(
+    path: str = typer.Argument(
+        default=".",
+        help="Path to the project directory to check. Defaults to current directory.",
+    )
+) -> None:
+    """Check the health of a project directory."""
+    from pathlib import Path
+
+    from spawn.utils.doctor import run_health_check
+
+    project_path = Path(path).resolve()
+    if not project_path.exists():
+        console.print(f"[red]❌ Path does not exist: {project_path}[/red]")
+        raise typer.Exit(1)
+    if not project_path.is_dir():
+        console.print(f"[red]❌ Path is not a directory: {project_path}[/red]")
+        raise typer.Exit(1)
+    run_health_check(project_path)
+
+
+def main():
+    try:
+        app()
+    except (KeyboardInterrupt, EOFError, typer.Abort):
+        console.print("\n[yellow]Cancelled.[/yellow]")
+        raise typer.Exit(130)
+
+
+if __name__ == "__main__":
+    main()

spawn/cli/noninteractive.py

@@ -0,0 +1,204 @@
+"""
+Non-interactive configuration builders for Spawn.
+
+Provides two public functions:
+
+- build_config_from_args: build a validated ProjectConfig from keyword arguments
+- build_config_from_file: build a validated ProjectConfig from a JSON config file
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from spawn.core.exceptions import SpawnError
+from spawn.core.models import ProjectConfig
+from spawn.core.registry import get_metadata, list_templates
+from spawn.templates.agent import get_supported_providers as get_agent_providers
+from spawn.templates.chatbot import get_supported_providers as get_chatbot_providers
+from spawn.utils.validators import validate_project_name
+
+
+def build_config_from_args(
+    name: str,
+    template: str,
+    framework: str | None = None,
+    provider: str | None = None,
+    cli_type: str | None = None,
+    data_type: str | None = None,
+    extras: list[str] | None = None,
+    use_git: bool = True,
+    use_uv: bool = True,
+    use_claude_md: bool = False,
+) -> ProjectConfig:
+    """
+    Build and return a validated ProjectConfig from explicit arguments.
+
+    Raises SpawnError for any invalid input.  Validation runs in this order:
+    project name, directory existence, template, cli_type, data_type,
+    framework, provider, extras.
+    """
+    # 1. Project name — let validate_project_name raise naturally.
+    validate_project_name(name)
+
+    # 2. Directory existence.
+    if Path(name).exists():
+        raise SpawnError(f"A directory named '{name}' already exists.")
+
+    # 3. Template.
+    metadata = get_metadata(template)
+    if metadata is None:
+        valid = ", ".join(m.slug for m in list_templates())
+        raise SpawnError(f"Unknown template: '{template}'. Valid templates: {valid}")
+
+    # 4. cli_type.
+    if metadata.available_cli_types:
+        if cli_type is None:
+            cli_type = metadata.available_cli_types[0]
+        elif cli_type not in metadata.available_cli_types:
+            valid = ", ".join(metadata.available_cli_types)
+            raise SpawnError(
+                f"Invalid cli_type: '{cli_type}'. "
+                f"Valid options for '{template}': {valid}"
+            )
+    else:
+        cli_type = None
+
+    # 5. data_type.
+    if metadata.available_data_types:
+        if data_type is None:
+            data_type = metadata.available_data_types[0]
+        elif data_type not in metadata.available_data_types:
+            valid = ", ".join(metadata.available_data_types)
+            raise SpawnError(
+                f"Invalid data_type: '{data_type}'. "
+                f"Valid options for '{template}': {valid}"
+            )
+    else:
+        data_type = None
+
+    # 6. framework.
+    if metadata.available_frameworks:
+        if framework is None:
+            framework = metadata.available_frameworks[0]
+        elif framework not in metadata.available_frameworks:
+            valid = ", ".join(metadata.available_frameworks)
+            raise SpawnError(
+                f"Invalid framework: '{framework}'. "
+                f"Valid options for '{template}': {valid}"
+            )
+    else:
+        framework = None
+
+    # 7. provider — only when the template declares providers AND a framework resolved.
+    if metadata.available_providers and framework is not None:
+        if metadata.slug == "agent":
+            valid_providers = get_agent_providers(framework)
+        elif metadata.slug == "chatbot":
+            valid_providers = get_chatbot_providers(framework)
+        else:
+            valid_providers = metadata.available_providers
+
+        if provider is None:
+            provider = valid_providers[0]
+        elif provider not in valid_providers:
+            valid = ", ".join(valid_providers)
+            raise SpawnError(
+                f"Invalid provider: '{provider}'. "
+                f"Valid options for '{template}' with framework '{framework}': {valid}"
+            )
+    else:
+        provider = None
+
+    # 8. extras — fail-fast on first invalid item, then de-duplicate preserving order.
+    input_extras: list[str] = extras if extras is not None else []
+    if not metadata.available_extras:
+        validated_extras: list[str] = []
+    else:
+        # Validate first (fail-fast on first bad item in input order).
+        for item in input_extras:
+            if item not in metadata.available_extras:
+                valid = ", ".join(metadata.available_extras)
+                raise SpawnError(
+                    f"Invalid extra: '{item}'. "
+                    f"Valid options for '{template}': {valid}"
+                )
+        # Build de-duplicated result preserving input order.
+        seen: set[str] = set()
+        validated_extras = []
+        for item in input_extras:
+            if item not in seen:
+                validated_extras.append(item)
+                seen.add(item)
+
+    return ProjectConfig(
+        name=name,
+        template=template,
+        use_git=use_git,
+        framework=framework,
+        extras=validated_extras,
+        cli_type=cli_type,
+        data_type=data_type,
+        provider=provider,
+        use_uv=use_uv,
+        generate_claude_md=use_claude_md,
+    )
+
+
+def build_config_from_file(path: Path, use_claude_md: bool = False) -> ProjectConfig:
+    """
+    Build and return a validated ProjectConfig from a JSON config file.
+
+    The file must be a JSON object with at least "name" and "template" fields.
+    All other validation is delegated to build_config_from_args.
+
+    Raises SpawnError for missing file, invalid JSON, or any field errors.
+    """
+    if not path.exists():
+        raise SpawnError(f"Config file not found: {path}")
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise SpawnError(f"Invalid JSON in config file: {e}") from e
+
+    if not isinstance(data, dict):
+        raise SpawnError("Config file must contain a JSON object.")
+
+    name = data.get("name", "")
+    if not name:
+        raise SpawnError("Config file must include a 'name' field.")
+
+    template = data.get("template", "")
+    if not template:
+        raise SpawnError("Config file must include a 'template' field.")
+
+    framework: str | None = data.get("framework", None)
+    provider: str | None = data.get("provider", None)
+    cli_type: str | None = data.get("cli_type", None)
+    data_type: str | None = data.get("data_type", None)
+
+    extras_raw = data.get("extras", [])
+    if not isinstance(extras_raw, list) or not all(
+        isinstance(e, str) for e in extras_raw
+    ):
+        raise SpawnError("'extras' in config file must be a list of strings.")
+    extras: list[str] = extras_raw
+
+    git: bool = data.get("git", True)
+    uv: bool = data.get("uv", True)
+    claude_md: bool = data.get("claude_md", use_claude_md)
+
+    return build_config_from_args(
+        name=name,
+        template=template,
+        framework=framework,
+        provider=provider,
+        cli_type=cli_type,
+        data_type=data_type,
+        extras=extras,
+        use_git=git,
+        use_uv=uv,
+        use_claude_md=claude_md,
+    )

spawn/cli/prompts.py

@@ -0,0 +1,267 @@
+import typer
+import questionary
+from pathlib import Path
+from rich.prompt import Confirm
+
+from spawn.utils.console import console
+from spawn.core.models import ProjectConfig
+from spawn.core.registry import list_templates, get_metadata
+from spawn.templates.chatbot import get_supported_providers as get_chatbot_providers
+from spawn.templates.agent import get_supported_providers as get_agent_providers
+from spawn.utils.validators import validate_project_name
+from spawn.core.exceptions import SpawnError
+
+
+# ---------------------------------------------------------------------------
+# Questionary helpers
+# ---------------------------------------------------------------------------
+
+_QSTYLE = questionary.Style([
+    ("qmark",       "fg:#2D5E8E bold"),
+    ("question",    "bold"),
+    ("pointer",     "fg:#2D5E8E bold"),
+    ("highlighted", "fg:#2D5E8E bold"),
+    ("selected",    "fg:#2D5E8E"),
+])
+
+
+def _select(message: str, choices: list[str], default: str | None = None) -> str:
+    """Arrow-key single-select. Raises KeyboardInterrupt on Ctrl+C/Esc so the
+    existing top-level abort handling in cli/app.py catches it uniformly."""
+    answer = questionary.select(
+        message, choices=choices, default=default, style=_QSTYLE
+    ).ask(kbi_msg="")
+    if answer is None:
+        raise KeyboardInterrupt
+    return answer
+
+
+def _multiselect(message: str, choices: list[str]) -> list[str]:
+    """Arrow-key + spacebar multi-select. Empty selection is valid (skip)."""
+    answer = questionary.checkbox(
+        message, choices=choices, style=_QSTYLE
+    ).ask(kbi_msg="")
+    if answer is None:
+        raise KeyboardInterrupt
+    return answer
+
+
+# ---------------------------------------------------------------------------
+# Custom Structure optional-setup multi-select
+# ---------------------------------------------------------------------------
+
+_OPTIONAL_SETUP_CHOICES = ["Ruff", "Pytest", "Pre-commit", "Dockerfile"]
+_OPTIONAL_SETUP_KEY = {
+    "Ruff":       "ruff",
+    "Pytest":     "pytest",
+    "Pre-commit": "precommit",
+    "Dockerfile": "dockerfile",
+}
+
+
+def _prompt_optional_setup() -> list[str]:
+    """Checkbox multi-select for optional dev tooling (Custom Structure flow)."""
+    chosen = _multiselect("Optional Setup (space to toggle)", _OPTIONAL_SETUP_CHOICES)
+    return [_OPTIONAL_SETUP_KEY[label] for label in chosen]
+
+
+# ---------------------------------------------------------------------------
+# Main interactive config builder
+# ---------------------------------------------------------------------------
+
+def get_project_config() -> ProjectConfig:
+    # --- Project name ---
+    while True:
+        project_name = typer.prompt(
+            typer.style("Project Name", fg=typer.colors.CYAN)
+        )
+
+        try:
+            validate_project_name(project_name)
+        except SpawnError as e:
+            typer.secho(str(e), fg=typer.colors.RED)
+            continue
+
+        if Path(project_name).exists():
+            typer.secho(
+                f"A directory named '{project_name}' already exists. "
+                "Choose a different name.",
+                fg=typer.colors.RED,
+            )
+            continue
+
+        break
+
+    # --- Template selection ---
+    templates = list_templates()
+    display_names = [meta.display_name for meta in templates] + ["Custom Structure"]
+    slug_by_display = {meta.display_name: meta.slug for meta in templates}
+    slug_by_display["Custom Structure"] = "__custom_structure__"
+
+    chosen_display = _select("Choose a template", display_names)
+    chosen_slug = slug_by_display[chosen_display]
+
+    if chosen_slug == "__custom_structure__":
+        return _get_custom_structure_config(project_name)
+
+    template = chosen_slug
+
+    # --- Sub-selections ---
+    selected_framework: str | None = None
+    selected_cli_type: str | None = None
+    selected_data_type: str | None = None
+    selected_provider: str | None = None
+    meta = get_metadata(template)
+
+    # --- CLI type ---
+    if meta and meta.available_cli_types:
+        cli_types = meta.available_cli_types
+        chosen = _select("Choose CLI Type", cli_types, default=cli_types[0])
+        selected_cli_type = chosen
+
+    # --- Data type ---
+    if meta and meta.available_data_types:
+        data_types = meta.available_data_types
+        chosen = _select("Choose Project Type", data_types, default=data_types[0])
+        selected_data_type = chosen
+
+    # --- Framework ---
+    if meta and meta.available_frameworks:
+        frameworks = meta.available_frameworks
+        chosen = _select("Choose Framework", frameworks, default=frameworks[0])
+        selected_framework = chosen
+
+    # --- Provider ---
+    if meta and meta.available_providers and selected_framework:
+        if meta.slug == "agent":
+            provider_options = get_agent_providers(selected_framework)
+        elif meta.slug == "chatbot":
+            provider_options = get_chatbot_providers(selected_framework)
+        else:
+            provider_options = meta.available_providers
+        chosen = _select("Choose Provider", provider_options, default=provider_options[0])
+        selected_provider = chosen
+
+    # --- Extras ---
+    selected_extras: list[str] = []
+    if meta and meta.available_extras:
+        selected_extras = _multiselect(
+            "Select extras (space to toggle, enter to confirm)",
+            meta.available_extras,
+        )
+
+    # --- Git ---
+    use_git = typer.confirm(
+        typer.style("Initialize Git?", fg=typer.colors.CYAN),
+        default=True,
+    )
+    generate_claude_md = Confirm.ask("Also generate CLAUDE.md for Claude Code?", default=False)
+
+    return ProjectConfig(
+        name=project_name,
+        template=template,
+        use_git=use_git,
+        generate_claude_md=generate_claude_md,
+        framework=selected_framework,
+        extras=selected_extras,
+        cli_type=selected_cli_type,
+        data_type=selected_data_type,
+        provider=selected_provider,
+    )
+
+
+def _get_custom_structure_config(project_name: str) -> ProjectConfig:
+    """
+    Interactive prompt for the Custom Structure path.
+
+    Reads a pasted structure (tree, markdown, or indented format),
+    previews detected folder/file counts, and collects Git/uv
+    preferences, optional dependencies, optional dev tooling
+    (ruff/pytest/pre-commit/dockerfile), and optional extra .gitignore
+    patterns. Returns a fully populated ProjectConfig for the "custom"
+    template.
+    """
+    import sys
+
+    from spawn.core.exceptions import StructureParseError
+    from spawn.generators.custom_structure import parse_structure, detect_format
+
+    console.print()
+    console.print(
+        "[cyan]Paste your project structure.[/cyan]\n"
+        "[dim]Supported formats: Tree (├──/└──), Markdown list (- item), "
+        "Indented hierarchy[/dim]\n"
+        "[dim]Finish with Ctrl+D (Ctrl+Z then Enter on Windows)[/dim]"
+    )
+
+    raw = sys.stdin.read()
+    detected_format = detect_format(raw)
+
+    try:
+        entries = parse_structure(raw)
+    except StructureParseError as e:
+        typer.secho(str(e), fg=typer.colors.RED)
+        raise SpawnError("Could not parse structure.") from e
+
+    folders = [e for e in entries if not e.is_file]
+    files   = [e for e in entries if e.is_file]
+
+    console.print()
+    console.print("[bold]Detected[/bold]")
+    console.print(f"Folders : {len(folders)}")
+    console.print(f"Files   : {len(files)}")
+    console.print()
+
+    use_git = typer.confirm(
+        typer.style("Initialize Git?", fg=typer.colors.CYAN), default=True
+    )
+    generate_claude_md = Confirm.ask("Also generate CLAUDE.md for Claude Code?", default=False)
+    use_uv = typer.confirm(
+        typer.style("Initialize uv?", fg=typer.colors.CYAN), default=True
+    )
+    custom_dependencies: list[str] = []
+    if use_uv:
+        deps_raw = typer.prompt(
+            typer.style(
+                "Dependencies (comma separated, optional)",
+                fg=typer.colors.CYAN,
+            ),
+            default="",
+            show_default=False,
+        )
+        if deps_raw.strip():
+            custom_dependencies = [
+                d.strip() for d in deps_raw.split(",") if d.strip()
+            ]
+    custom_dev_setup = _prompt_optional_setup() if use_uv else []
+    console.print()
+    extra_ignores_raw = typer.prompt(
+        typer.style(
+            "Additional ignore patterns (optional, comma separated)",
+            fg=typer.colors.CYAN,
+        ),
+        default="",
+        show_default=False,
+    )
+    custom_gitignore_extra = [
+        p.strip() for p in extra_ignores_raw.split(",") if p.strip()
+    ]
+    proceed = typer.confirm(
+        typer.style("Proceed?", fg=typer.colors.CYAN), default=True
+    )
+
+    if not proceed:
+        raise SpawnError("Cancelled.")
+
+    return ProjectConfig(
+        name=project_name,
+        template="custom",
+        use_git=use_git,
+        generate_claude_md=generate_claude_md,
+        use_uv=use_uv,
+        custom_entries=entries,
+        custom_dependencies=custom_dependencies,
+        custom_dev_setup=custom_dev_setup,
+        custom_gitignore_extra=custom_gitignore_extra,
+        custom_source_format=detected_format,
+    )