sillo-start 0.1.0__py3-none-any.whl

sillo_start/__init__.py

@@ -0,0 +1,35 @@
+"""Sillo Start — bootstrapper and orchestrator for Sillo applications.
+
+Sillo Start creates properly structured Sillo projects, installs and removes
+features against an existing project, and runs the development services a
+project needs. ``sillo.toml`` at the project root is the authoritative record
+of what a project is; every command reads and updates it.
+
+The package is layered so the CLI stays a thin shell over reusable logic:
+
+``config``
+    The manifest schema and its loading/writing.
+``operations``
+    Reversible units of work (write a file, edit TOML, install a package) and
+    the transaction that applies them or rolls them back.
+``packages``
+    The package-group registry, dependency resolver, and installers.
+``blueprints``
+    Named project archetypes that turn wizard answers into a manifest.
+``project``
+    Creation, inspection and validation of projects on disk.
+``generators``
+    Component scaffolding for an existing project.
+``orchestration``
+    The supervised process manager behind ``sillo-start dev``.
+``prompts``
+    The interactive wizard.
+``cli``
+    Typer commands, which do argument handling and rendering only.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

sillo_start/__main__.py

@@ -0,0 +1,19 @@
+"""``python -m sillo_start`` and the ``sillo-start`` console script."""
+
+from __future__ import annotations
+
+
+def main() -> None:
+    """Load the command tree and run the CLI."""
+    # Imported here rather than at module scope so that plugin loading and
+    # command registration happen once, at invocation, and a broken plugin
+    # cannot make `python -m sillo_start` unimportable.
+    from .cli import build_cli
+
+    # A Typer app is called, not `.main()`ed — calling it is what runs the
+    # underlying Click command with argv.
+    build_cli()()
+
+
+if __name__ == "__main__":
+    main()

sillo_start/cli/__init__.py

@@ -0,0 +1,20 @@
+"""The Typer command tree.
+
+Importing the command module registers its command on the shared ``app``, so
+:func:`build_cli` imports it and returns the app.
+"""
+
+from __future__ import annotations
+
+import typer
+
+
+def build_cli() -> typer.Typer:
+    """Assemble and return the CLI application."""
+    from . import create  # noqa: F401 — importing registers the command
+    from .app import app
+
+    return app
+
+
+__all__ = ["build_cli"]

sillo_start/cli/app.py

@@ -0,0 +1,106 @@
+"""The Typer application and its shared behaviour.
+
+The CLI layer stays thin: it parses arguments, calls into
+:mod:`sillo_start.project.template`, and renders the result. The fetching and
+personalising happen there, which is what lets them be driven from tests
+without a terminal.
+
+Errors are handled in one place. Anything deriving from
+:class:`~sillo_start.exceptions.SilloStartError` becomes a clean message plus
+its hint and a predictable exit code; the traceback appears only under
+``--verbose``.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+import typer
+
+from .. import __version__
+from ..exceptions import SilloStartError
+from ..utils.console import console
+
+app = typer.Typer(
+    name="sillo-start",
+    help="Create a Sillo application from a starter repository.",
+    add_completion=True,
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def version_callback(value: bool) -> None:
+    """Print the version and exit."""
+    if value:
+        console.print(f"sillo-start {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show the version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show debug output and tracebacks."
+    ),
+    quiet: bool = typer.Option(
+        False, "--quiet", "-q", help="Suppress non-essential output."
+    ),
+) -> None:
+    """Sillo Start — create a Sillo application from a starter repository."""
+    console.configure(verbose=verbose, quiet=quiet)
+
+
+def handle_errors(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Turn deliberate failures into clean messages and exit codes.
+
+    Applied to every command body. ``typer.Exit`` and ``typer.Abort`` pass
+    through untouched so control flow still works.
+    """
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return func(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except SilloStartError as exc:
+            console.error(exc.message, hint=exc.hint)
+            if console.verbose:
+                console.rich.print_exception()
+            raise typer.Exit(code=exc.exit_code) from exc
+        except KeyboardInterrupt:
+            console.blank()
+            console.warning("Cancelled.")
+            raise typer.Exit(code=130) from None
+        except Exception as exc:  # noqa: BLE001 — last resort, reported not swallowed
+            console.error(
+                f"Unexpected error: {exc}",
+                hint="Re-run with --verbose for the full traceback, and please report this.",
+            )
+            if console.verbose:
+                console.rich.print_exception()
+            raise typer.Exit(code=1) from exc
+
+    return wrapper
+
+
+def run() -> None:
+    """Entrypoint used by the console script."""
+    try:
+        app()
+    except SilloStartError as exc:
+        # Reached only for failures raised outside a command body.
+        console.error(exc.message, hint=exc.hint)
+        sys.exit(exc.exit_code)

sillo_start/cli/create.py

@@ -0,0 +1,114 @@
+"""``sillo-start create-app``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from ..exceptions import UsageError
+from ..utils.console import console
+from ..utils.naming import is_valid_project_name
+from .app import app, handle_errors
+
+
+@app.command("create-app")
+@handle_errors
+def create_app(
+    template: str = typer.Argument(
+        None, help="Starter repository, e.g. sillohq/starter or sillohq/starter@v1."
+    ),
+    name: str = typer.Argument(None, help="Project name. Also the directory name."),
+    directory: Path = typer.Option(
+        None,
+        "--directory",
+        "-d",
+        help="Where to create the project. Defaults to ./<name>.",
+    ),
+    ref: str = typer.Option(
+        None, "--ref", help="Branch or tag to take. Defaults to main."
+    ),
+    install: bool = typer.Option(
+        False, "--install/--no-install", help="Install dependencies after fetching."
+    ),
+    git: bool = typer.Option(
+        True, "--git/--no-git", help="Initialise a git repository."
+    ),
+    force: bool = typer.Option(False, "--force", help="Allow a non-empty directory."),
+) -> None:
+    """Create a project from a starter repository.
+
+        sillo-start create-app myapp
+        sillo-start create-app sillohq/starter myapp
+        sillo-start create-app sillohq/starter@v1.2 myapp
+
+    The starter is a real application with its own CI, so what you get has been
+    booted and exercised rather than only rendered. With one argument the
+    default starter is used and the argument is the project name.
+    """
+    from ..project.template import DEFAULT_TEMPLATE, Template, fetch, personalise
+
+    # One argument is the project name; the starter is only ever given when
+    # both are, so `create-app myapp` does the obvious thing.
+    if name is None:
+        name, template = template, DEFAULT_TEMPLATE
+    if not name:
+        raise UsageError(
+            "A project name is required.",
+            hint="sillo-start create-app myapp",
+        )
+    if not is_valid_project_name(name):
+        raise UsageError(
+            f"'{name}' is not a valid project name.",
+            hint="Use a letter followed by letters, digits, hyphens or underscores.",
+        )
+
+    parsed = Template.parse(template or DEFAULT_TEMPLATE, ref=ref)
+    root = (directory or Path.cwd() / name).resolve()
+    if root.exists() and any(root.iterdir()) and not force:
+        raise UsageError(
+            f"{root} is not empty.",
+            hint="Choose another directory, or pass --force.",
+        )
+
+    console.header(f"Creating {name}", f"from {parsed.slug}@{parsed.ref}")
+    with console.progress(f"Fetching {parsed.slug}…"):
+        fetch(parsed, root)
+
+    changed = personalise(root, name)
+    console.success(f"Fetched {parsed.slug} and renamed {len(changed)} file(s)")
+
+    if git:
+        from ..utils.subprocess import run, tool_exists
+
+        if tool_exists("git") and not (root / ".git").exists():
+            run(["git", "init", "--quiet"], cwd=root, check=False)
+
+    if install:
+        from ..utils.pkgmanagers import detect_python_manager
+        from ..utils.subprocess import run
+
+        manager = detect_python_manager()
+        console.header("Dependencies", f"installing with {manager.name}")
+        with console.progress("Resolving…"):
+            result = run(manager.sync_command(), cwd=root, check=False, timeout=900)
+        if not result.ok:
+            console.failure(f"{manager.name} exited with code {result.returncode}.")
+            if result.output:
+                console.raw(result.output)
+            raise typer.Exit(code=1)
+        console.success("Dependencies installed.")
+
+    console.blank()
+    console.print("[bold]Next steps[/bold]")
+    steps = [f"cd {root.name}"]
+    if not install:
+        steps.append("make setup")
+    else:
+        steps.append("make migrate")
+    steps.append("make dev")
+    console.commands(steps)
+    console.blank()
+    console.hint(
+        "The starter's README covers configuration, migrations and deployment."
+    )

sillo_start/exceptions.py

@@ -0,0 +1,69 @@
+"""Exception hierarchy for Sillo Start.
+
+Every error the tool raises on purpose derives from :class:`SilloStartError`.
+The CLI layer catches that base class and renders a clean message with an exit
+code, so a user never sees a traceback unless they pass ``--verbose``.
+
+Each exception carries an optional ``hint`` — a concrete next action. Error
+messages that only say what went wrong make the user guess; the hint is where
+we tell them what to type.
+"""
+
+from __future__ import annotations
+
+
+class SilloStartError(Exception):
+    """Base class for all deliberate Sillo Start failures.
+
+    Args:
+        message: What went wrong, in one sentence.
+        hint: An optional concrete remedy shown beneath the error.
+        exit_code: Process exit code the CLI should use.
+    """
+
+    exit_code: int = 1
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        exit_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+        if exit_code is not None:
+            self.exit_code = exit_code
+
+
+class UsageError(SilloStartError):
+    """The command was invoked with an invalid combination of arguments."""
+
+    exit_code = 2
+
+
+class CommandError(SilloStartError):
+    """An external command exited non-zero.
+
+    The captured output is kept on the exception so the CLI can show it — Sillo
+    Start never silently swallows subprocess output.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        command: list[str] | None = None,
+        returncode: int | None = None,
+        output: str | None = None,
+        hint: str | None = None,
+    ) -> None:
+        super().__init__(message, hint=hint)
+        self.command = command or []
+        self.returncode = returncode
+        self.output = output
+
+
+class ToolNotFoundError(SilloStartError):
+    """A required external tool is not installed or not on ``PATH``."""

sillo_start/project/__init__.py

@@ -0,0 +1,10 @@
+"""Creating a project from a starter repository."""
+
+from .template import DEFAULT_TEMPLATE, Template, fetch, personalise
+
+__all__ = [
+    "DEFAULT_TEMPLATE",
+    "Template",
+    "fetch",
+    "personalise",
+]

sillo_start/project/template.py

@@ -0,0 +1,225 @@
+"""Creating a project by fetching a starter repository.
+
+A generated project can render perfectly and still fail on its first request:
+templates are checked for rendering, not for running. A starter repository is
+a real application with its own CI, so what arrives has been booted and
+exercised before it reaches anyone.
+
+The repository is fetched as a tarball rather than cloned. That needs no git on
+the machine, brings no history someone has to delete before their first commit,
+and pins to a tag as easily as to a branch.
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import secrets
+import tarfile
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..exceptions import CommandError
+
+
+def generate_secret_key(length: int = 50) -> str:
+    """Generate a URL-safe application secret.
+
+    So a new project is never born with a placeholder secret that someone might
+    ship.
+    """
+    return secrets.token_urlsafe(length)[:length]
+
+
+#: The starter used when none is named.
+DEFAULT_TEMPLATE = "sillohq/starter"
+
+#: How long to wait for GitHub before giving up, in seconds.
+TIMEOUT = 60
+
+
+@dataclass(frozen=True)
+class Template:
+    """A starter repository and the revision to take."""
+
+    owner: str
+    repo: str
+    ref: str = "main"
+
+    @property
+    def slug(self) -> str:
+        return f"{self.owner}/{self.repo}"
+
+    @property
+    def url(self) -> str:
+        """The tarball URL. Public repositories need no authentication."""
+        return f"https://codeload.github.com/{self.owner}/{self.repo}/tar.gz/{self.ref}"
+
+    @classmethod
+    def parse(cls, value: str, *, ref: str | None = None) -> Template:
+        """Parse ``owner/repo``, ``owner/repo@ref`` or a full GitHub URL.
+
+        Raises:
+            CommandError: If *value* is not a recognisable repository.
+        """
+        text = value.strip()
+        text = re.sub(r"^(https?://)?(www\.)?github\.com/", "", text)
+        text = re.sub(r"\.git$", "", text).strip("/")
+
+        at_ref = None
+        if "@" in text:
+            text, _, at_ref = text.partition("@")
+
+        parts = [part for part in text.split("/") if part]
+        if len(parts) != 2:
+            raise CommandError(
+                f"'{value}' is not a repository.",
+                hint="Use owner/repo, for example sillohq/starter.",
+            )
+        return cls(owner=parts[0], repo=parts[1], ref=ref or at_ref or "main")
+
+
+def fetch(template: Template, destination: Path) -> None:
+    """Download *template* and unpack it into *destination*.
+
+    GitHub wraps the archive in a single top-level directory named after the
+    repository and commit, which is stripped so the project's own files land at
+    the destination root.
+
+    Raises:
+        CommandError: If the repository or ref cannot be fetched.
+    """
+    try:
+        with urllib.request.urlopen(template.url, timeout=TIMEOUT) as response:
+            payload = response.read()
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            raise CommandError(
+                f"Could not find {template.slug} at ref '{template.ref}'.",
+                hint="Check the name and the branch or tag, and that the repository is public.",
+            ) from exc
+        raise CommandError(f"GitHub returned {exc.code} for {template.slug}.") from exc
+    except urllib.error.URLError as exc:
+        raise CommandError(
+            f"Could not reach GitHub: {exc.reason}",
+            hint="Creating a project needs network access to fetch the starter.",
+        ) from exc
+
+    destination.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as archive:
+        members = archive.getmembers()
+        if not members:
+            raise CommandError(f"{template.slug} produced an empty archive.")
+
+        prefix = members[0].name.split("/")[0] + "/"
+        for member in members:
+            if not member.name.startswith(prefix):
+                continue
+            relative = member.name[len(prefix) :]
+            if not relative:
+                continue
+            # A member path that escapes the destination is how a malicious
+            # archive overwrites files elsewhere. Refuse rather than sanitise.
+            target = (destination / relative).resolve()
+            if not str(target).startswith(str(destination.resolve())):
+                raise CommandError(
+                    f"{template.slug} contains an unsafe path: {member.name}"
+                )
+
+            member.name = relative
+            archive.extract(member, destination, filter="data")
+
+
+#: Files rewritten to carry the new project's name, and what to replace in each.
+#: Targeted rather than a blanket find-and-replace, so prose that happens to say
+#: "starter" — the README, a Makefile comment — is left as written.
+#:
+#: Model files are deliberately absent. A model's docstring becomes its
+#: ``table_description``, so rewriting one puts the models out of step with the
+#: committed migration and the next `migrate` writes a spurious second one.
+RENAMES = (
+    ("pyproject.toml", ('name = "{old}"', 'name = "{new}"')),
+    (
+        "app/config.py",
+        ('"""Typed settings for {Old}."""', '"""Typed settings for {New}."""'),
+    ),
+    ("app/config.py", ('app_name: str = "{Old}"', 'app_name: str = "{New}"')),
+    ("app/config.py", ("sqlite://storage/{old}.db", "sqlite://storage/{new}.db")),
+    (".env.example", ("# {Old} environment.", "# {New} environment.")),
+    (".env.example", ("APP_NAME={Old}", "APP_NAME={New}")),
+    (".env.example", ("sqlite://storage/{old}.db", "sqlite://storage/{new}.db")),
+)
+
+
+def personalise(root: Path, name: str, *, template_name: str = "starter") -> list[str]:
+    """Rewrite the fetched project to be *name*, and create its ``.env``.
+
+    Args:
+        root: The unpacked project.
+        name: The new project name.
+        template_name: What the starter called itself.
+
+    Returns:
+        The paths that changed, relative to *root*.
+    """
+    substitutions = {
+        "old": template_name,
+        "new": name,
+        "Old": template_name.replace("_", " ").title().replace(" ", ""),
+        "New": name.replace("_", " ").title().replace(" ", ""),
+    }
+
+    changed: list[str] = []
+    for relative, (find, replace) in RENAMES:
+        path = root / relative
+        if not path.is_file():
+            continue
+        content = path.read_text(encoding="utf-8")
+        needle = find.format(**substitutions)
+        if needle not in content:
+            continue
+        path.write_text(
+            content.replace(needle, replace.format(**substitutions)), encoding="utf-8"
+        )
+        if relative not in changed:
+            changed.append(relative)
+
+    # The lock file names the project as a member of its own workspace, so it
+    # has to agree with pyproject or `uv sync` fails on a renamed project.
+    lock = root / "uv.lock"
+    if lock.is_file():
+        content = lock.read_text(encoding="utf-8")
+        renamed = content.replace(f'name = "{template_name}"', f'name = "{name}"')
+        if renamed != content:
+            lock.write_text(renamed, encoding="utf-8")
+            changed.append("uv.lock")
+
+    if _write_env(root, name):
+        changed.append(".env")
+    return changed
+
+
+def _write_env(root: Path, name: str) -> bool:
+    """Create ``.env`` from ``.env.example`` with fresh secrets.
+
+    Returns:
+        True when a file was written. An existing ``.env`` is never replaced —
+        it may hold real credentials.
+    """
+    example = root / ".env.example"
+    env = root / ".env"
+    if not example.is_file() or env.exists():
+        return False
+
+    lines = []
+    for line in example.read_text(encoding="utf-8").splitlines():
+        key, sep, _ = line.partition("=")
+        # Secrets committed to a starter are placeholders by definition. Every
+        # project gets its own, so no two deployments ever share a signing key.
+        if sep and key.strip() in {"SECRET_KEY", "JWT_SECRET", "APP_KEY"}:
+            line = f"{key}={generate_secret_key()}"
+        lines.append(line)
+    env.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return True

sillo_start/utils/__init__.py

@@ -0,0 +1,21 @@
+"""Shared low-level helpers."""
+
+from .console import Console, console, is_ci
+from .naming import is_valid_project_name, is_valid_python_identifier, package_name_for
+from .pkgmanagers import detect_python_manager
+from .subprocess import CommandResult, require_tool, run, tool_exists, which
+
+__all__ = [
+    "Console",
+    "console",
+    "is_ci",
+    "is_valid_project_name",
+    "is_valid_python_identifier",
+    "package_name_for",
+    "detect_python_manager",
+    "CommandResult",
+    "require_tool",
+    "run",
+    "tool_exists",
+    "which",
+]