sillo-start 0.1.0__tar.gz

sillo_start-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Editors
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv.lock is committed deliberately: sillo-start is an application-style CLI,
+# so a reproducible resolution is worth more than floating dependencies.

sillo_start-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: sillo-start
+Version: 0.1.0
+Summary: Create a Sillo application from a starter repository.
+Project-URL: Homepage, https://github.com/sillohq/start
+Project-URL: Repository, https://github.com/sillohq/start
+Project-URL: Documentation, https://docs.sillo.build
+Author-email: Chidebele Dunamis <techwithdunamix@gmail.com>
+License-Expression: BSD-3-Clause
+Keywords: asgi,cli,scaffolding,sillo,starter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.15.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.5; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sillo Start
+
+Creates a Sillo application from a starter repository.
+
+```bash
+uvx sillo-start create-app myapp
+cd myapp
+make setup
+make dev
+```
+
+That is the whole tool. It fetches a real, working application, renames it to
+yours, gives it its own secrets, and gets out of the way.
+
+## Why a starter repository, not a generator
+
+A generator renders templates. Templates are checked for *rendering*, which is
+not the same as working — a project can produce valid Python, import cleanly,
+render every page, and still fail on its first real request. Middleware
+registered in the wrong order, an auth backend reading the wrong claim, a
+missing static mount: all of them render perfectly.
+
+[`sillohq/starter`](https://github.com/sillohq/starter) is a real application
+with its own CI. Every push boots it and exercises every route, on three
+Python versions. What you get has been run, not just written.
+
+It also means the starter can be read, forked and improved on its own, and
+that `sillo-start` never has to be released to fix a bug in what it produces.
+
+## Install
+
+```bash
+# Run it without installing
+uvx sillo-start create-app myapp
+
+# Or install it
+uv tool install sillo-start
+pipx install sillo-start
+```
+
+Python 3.11 or newer. The only dependencies are `typer` and `rich`.
+
+## Usage
+
+```bash
+sillo-start create-app myapp                       # the default starter
+sillo-start create-app sillohq/starter myapp       # named explicitly
+sillo-start create-app sillohq/starter@v1.2 myapp  # pinned to a tag
+sillo-start create-app acme/our-template myapp     # your own starter
+```
+
+Any public GitHub repository works. A full URL is accepted too, so pasting what
+is in your address bar does what you expect.
+
+| Option | |
+| --- | --- |
+| `--ref <branch\|tag>` | Which revision to take. Defaults to `main` |
+| `-d`, `--directory <path>` | Where to create it. Defaults to `./<name>` |
+| `--install` | Install dependencies straight away |
+| `--no-git` | Do not initialise a git repository |
+| `--force` | Allow a directory that is not empty |
+| `-v`, `--verbose` | Show tracebacks |
+
+Dependencies are **not** installed by default, so creating a project takes a
+second rather than a minute. `make setup` in the new project does it, along
+with everything else a first run needs.
+
+## What it does to the project
+
+The starter arrives as a tarball rather than a clone. That needs no `git` on
+the machine, brings no history for you to delete before your first commit, and
+pins to a tag as easily as to a branch.
+
+Then three things happen:
+
+**It takes your name.** The package name, the application title, the SQLite
+path. Rewriting is targeted rather than a blanket find-and-replace, so prose
+that happens to say "starter" — a README sentence, a comment — is left as
+written.
+
+**It gets its own secrets.** `.env` is created from `.env.example` with a fresh
+key for `SECRET_KEY`, `JWT_SECRET` and `APP_KEY`. A secret committed to a
+starter is a placeholder by definition; no two projects should ever share a
+signing key. An existing `.env` is never touched — it may hold real credentials.
+
+**It becomes a git repository**, unless you pass `--no-git`.
+
+## What it deliberately does not do
+
+Migrations, creating users, running the queue worker, starting the server —
+none of that is here.
+
+Those belong to the project, in its own `console.py`:
+
+```bash
+python console.py db migrate
+python console.py user admin ada@example.com ada
+python console.py worker
+python console.py serve --reload
+```
+
+The framework provides the operations as plain functions —
+`sillo.record.commands`, `sillo.users.commands`, `sillo.work.commands` — and
+the project decides how to expose them. Nothing in a created project depends on
+`sillo-start`, so it cannot rot when this tool changes, and you can delete this
+tool the moment your project exists.
+
+## Safety
+
+An archive member whose path escapes the destination is refused rather than
+sanitised — that is how a malicious archive overwrites files elsewhere on your
+machine.
+
+A directory that is not empty is refused unless you pass `--force`, and even
+then existing files are left in place.
+
+A project name that is not a usable Python identifier is refused *before*
+anything is fetched, since it becomes both a package name and a directory.
+
+## Development
+
+See [docs/contributing.md](docs/contributing.md).
+
+## Licence
+
+BSD-3-Clause.

sillo_start-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Sillo Start
+
+Creates a Sillo application from a starter repository.
+
+```bash
+uvx sillo-start create-app myapp
+cd myapp
+make setup
+make dev
+```
+
+That is the whole tool. It fetches a real, working application, renames it to
+yours, gives it its own secrets, and gets out of the way.
+
+## Why a starter repository, not a generator
+
+A generator renders templates. Templates are checked for *rendering*, which is
+not the same as working — a project can produce valid Python, import cleanly,
+render every page, and still fail on its first real request. Middleware
+registered in the wrong order, an auth backend reading the wrong claim, a
+missing static mount: all of them render perfectly.
+
+[`sillohq/starter`](https://github.com/sillohq/starter) is a real application
+with its own CI. Every push boots it and exercises every route, on three
+Python versions. What you get has been run, not just written.
+
+It also means the starter can be read, forked and improved on its own, and
+that `sillo-start` never has to be released to fix a bug in what it produces.
+
+## Install
+
+```bash
+# Run it without installing
+uvx sillo-start create-app myapp
+
+# Or install it
+uv tool install sillo-start
+pipx install sillo-start
+```
+
+Python 3.11 or newer. The only dependencies are `typer` and `rich`.
+
+## Usage
+
+```bash
+sillo-start create-app myapp                       # the default starter
+sillo-start create-app sillohq/starter myapp       # named explicitly
+sillo-start create-app sillohq/starter@v1.2 myapp  # pinned to a tag
+sillo-start create-app acme/our-template myapp     # your own starter
+```
+
+Any public GitHub repository works. A full URL is accepted too, so pasting what
+is in your address bar does what you expect.
+
+| Option | |
+| --- | --- |
+| `--ref <branch\|tag>` | Which revision to take. Defaults to `main` |
+| `-d`, `--directory <path>` | Where to create it. Defaults to `./<name>` |
+| `--install` | Install dependencies straight away |
+| `--no-git` | Do not initialise a git repository |
+| `--force` | Allow a directory that is not empty |
+| `-v`, `--verbose` | Show tracebacks |
+
+Dependencies are **not** installed by default, so creating a project takes a
+second rather than a minute. `make setup` in the new project does it, along
+with everything else a first run needs.
+
+## What it does to the project
+
+The starter arrives as a tarball rather than a clone. That needs no `git` on
+the machine, brings no history for you to delete before your first commit, and
+pins to a tag as easily as to a branch.
+
+Then three things happen:
+
+**It takes your name.** The package name, the application title, the SQLite
+path. Rewriting is targeted rather than a blanket find-and-replace, so prose
+that happens to say "starter" — a README sentence, a comment — is left as
+written.
+
+**It gets its own secrets.** `.env` is created from `.env.example` with a fresh
+key for `SECRET_KEY`, `JWT_SECRET` and `APP_KEY`. A secret committed to a
+starter is a placeholder by definition; no two projects should ever share a
+signing key. An existing `.env` is never touched — it may hold real credentials.
+
+**It becomes a git repository**, unless you pass `--no-git`.
+
+## What it deliberately does not do
+
+Migrations, creating users, running the queue worker, starting the server —
+none of that is here.
+
+Those belong to the project, in its own `console.py`:
+
+```bash
+python console.py db migrate
+python console.py user admin ada@example.com ada
+python console.py worker
+python console.py serve --reload
+```
+
+The framework provides the operations as plain functions —
+`sillo.record.commands`, `sillo.users.commands`, `sillo.work.commands` — and
+the project decides how to expose them. Nothing in a created project depends on
+`sillo-start`, so it cannot rot when this tool changes, and you can delete this
+tool the moment your project exists.
+
+## Safety
+
+An archive member whose path escapes the destination is refused rather than
+sanitised — that is how a malicious archive overwrites files elsewhere on your
+machine.
+
+A directory that is not empty is refused unless you pass `--force`, and even
+then existing files are left in place.
+
+A project name that is not a usable Python identifier is refused *before*
+anything is fetched, since it becomes both a package name and a directory.
+
+## Development
+
+See [docs/contributing.md](docs/contributing.md).
+
+## Licence
+
+BSD-3-Clause.

sillo_start-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sillo-start"
+version = "0.1.0"
+description = "Create a Sillo application from a starter repository."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+authors = [
+    { name = "Chidebele Dunamis", email = "techwithdunamix@gmail.com" },
+]
+keywords = ["sillo", "scaffolding", "cli", "starter", "asgi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Code Generators",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-cov>=5.0.0",
+    "mypy>=1.15.0",
+    "ruff>=0.6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/sillohq/start"
+Repository = "https://github.com/sillohq/start"
+Documentation = "https://docs.sillo.build"
+
+[project.scripts]
+sillo-start = "sillo_start.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sillo_start"]
+
+[tool.hatch.build.targets.sdist]
+include = ["sillo_start", "tests", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = [
+    "E501",
+    # Typer expresses defaults as function calls in the signature.
+    "B008",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+warn_unused_ignores = true
+disallow_untyped_defs = false
+files = ["sillo_start"]

sillo_start-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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."
+    )