avalon-cli 0.2.0__py3-none-any.whl

avalon_cli/__init__.py

@@ -0,0 +1,37 @@
+"""avalon-cli: command-line companion for the Avalon real-time web framework.
+
+The package is self-contained (standard library only) and does not import
+``avalon`` itself. The public API mirrors the CLI commands:
+
+* :func:`create_project` - ``avalon new``
+* :class:`DevServer` / :func:`build_command` - ``avalon dev``
+* :func:`load_config` - reads ``avalon.toml``
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from .config import ConfigError, DevConfig, ProjectConfig, find_project_root, load_config  # noqa: E402
+from .reloader import DevServer, build_command, diff_snapshots, take_snapshot  # noqa: E402
+from .scaffold import ScaffoldError, ScaffoldResult, create_project  # noqa: E402
+from .templates import TEMPLATES, ProjectTemplate, get_template  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "ConfigError",
+    "DevConfig",
+    "DevServer",
+    "ProjectConfig",
+    "ProjectTemplate",
+    "ScaffoldError",
+    "ScaffoldResult",
+    "TEMPLATES",
+    "build_command",
+    "create_project",
+    "diff_snapshots",
+    "find_project_root",
+    "get_template",
+    "load_config",
+    "take_snapshot",
+]

avalon_cli/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m avalon_cli``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

avalon_cli/cli.py

@@ -0,0 +1,163 @@
+"""The ``avalon`` command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import shlex
+import signal
+import sys
+import threading
+from collections.abc import Sequence
+from typing import TextIO
+
+from . import __version__
+from .config import ConfigError, load_config
+from .reloader import DevServer, build_command
+from .scaffold import ScaffoldError, create_project
+from .templates import DEFAULT_TEMPLATE, TEMPLATES
+
+__all__ = ["build_parser", "main"]
+
+
+class CLIError(Exception):
+    """An error reported to the user as ``error: <message>`` with exit code 1."""
+
+
+def _cmd_new(args: argparse.Namespace, out: TextIO) -> int:
+    result = create_project(args.name, args.template, args.directory, force=args.force)
+    out.write(f"Created {result.template!r} project in {result.root}\n")
+    for path in result.files:
+        out.write(f"  {path.relative_to(result.root).as_posix()}\n")
+    out.write(f"\nNext steps:\n  cd {shlex.quote(str(result.root))}\n  avalon dev\n")
+    return 0
+
+
+def _cmd_templates(args: argparse.Namespace, out: TextIO) -> int:
+    width = max(len(name) for name in TEMPLATES)
+    for name in sorted(TEMPLATES):
+        marker = " (default)" if name == DEFAULT_TEMPLATE else ""
+        out.write(f"{name:<{width}}  {TEMPLATES[name].description}{marker}\n")
+    return 0
+
+
+def _cmd_info(args: argparse.Namespace, out: TextIO) -> int:
+    out.write(f"avalon-cli  {__version__}\n")
+    out.write(f"python      {platform.python_version()} ({sys.executable})\n")
+    try:
+        config = load_config(args.project)
+    except ConfigError as exc:
+        out.write(f"project     (none: {exc})\n")
+        return 0
+    dev = config.dev
+    argv = build_command(dev.command, host=dev.host, port=dev.port)
+    out.write(f"project     {config.name}\n")
+    out.write(f"root        {config.root}\n")
+    out.write(f"command     {shlex.join(argv)}\n")
+    out.write(f"address     http://{dev.host}:{dev.port}/\n")
+    out.write(f"watch       {', '.join(dev.watch)}\n")
+    out.write(f"extensions  {', '.join(dev.extensions) or '(all files)'}\n")
+    return 0
+
+
+def _cmd_dev(args: argparse.Namespace, out: TextIO) -> int:
+    config = load_config(args.project)
+    dev = config.dev
+    host = dev.host if args.host is None else args.host
+    port = dev.port if args.port is None else args.port
+    interval = dev.interval if args.interval is None else args.interval
+    if not 0 < port < 65536:
+        raise CLIError(f"port must be between 1 and 65535 (got {port})")
+    if interval <= 0:
+        raise CLIError("interval must be positive")
+    argv = build_command(dev.command, host=host, port=port)
+
+    env = dict(os.environ)
+    env.update(AVALON_HOST=host, AVALON_PORT=str(port), AVALON_ENV="development")
+    server = DevServer(
+        argv,
+        cwd=config.root,
+        env=env,
+        watch=dev.watch,
+        extensions=dev.extensions,
+        ignore=dev.ignore,
+        interval=interval,
+        reload=not args.no_reload,
+    )
+    out.write(f"Serving {config.name} at http://{host}:{port}/ (Ctrl-C to stop)\n")
+    out.flush()
+
+    # Treat SIGTERM like a clean shutdown so the child is never orphaned.
+    stop_event = threading.Event()
+    previous = None
+    if threading.current_thread() is threading.main_thread():
+        previous = signal.signal(signal.SIGTERM, lambda signum, frame: stop_event.set())
+    try:
+        return server.run(stop_event)
+    except KeyboardInterrupt:
+        out.write("\nStopped.\n")
+        return 130
+    finally:
+        if previous is not None:
+            signal.signal(signal.SIGTERM, previous)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the argument parser for the ``avalon`` command."""
+    parser = argparse.ArgumentParser(
+        prog="avalon",
+        description="Command-line companion for the Avalon real-time web framework.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND", required=True)
+
+    new = sub.add_parser("new", help="create a new project from a template")
+    new.add_argument("name", help="project name (also the directory name)")
+    new.add_argument(
+        "-t", "--template", default=DEFAULT_TEMPLATE, choices=sorted(TEMPLATES),
+        help=f"template to use (default: {DEFAULT_TEMPLATE})",
+    )
+    new.add_argument(
+        "-d", "--directory", default=".",
+        help="parent directory to create the project in (default: current directory)",
+    )
+    new.add_argument("--force", action="store_true", help="write into a non-empty directory")
+    new.set_defaults(handler=_cmd_new)
+
+    dev = sub.add_parser("dev", help="run the dev command with auto-reload")
+    dev.add_argument("-C", "--project", default=".", help="project directory (default: current directory)")
+    dev.add_argument("--host", help="host to bind (overrides avalon.toml)")
+    dev.add_argument("-p", "--port", type=int, help="port to bind (overrides avalon.toml)")
+    dev.add_argument("--interval", type=float, help="seconds between file-change polls")
+    dev.add_argument("--no-reload", action="store_true", help="run once without watching files")
+    dev.set_defaults(handler=_cmd_dev)
+
+    templates = sub.add_parser("templates", help="list available project templates")
+    templates.set_defaults(handler=_cmd_templates)
+
+    info = sub.add_parser("info", help="show environment and resolved project settings")
+    info.add_argument("-C", "--project", default=".", help="project directory (default: current directory)")
+    info.set_defaults(handler=_cmd_info)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None, out: TextIO | None = None) -> int:
+    """Entry point for the ``avalon`` console script.
+
+    :param argv: arguments excluding the program name (defaults to ``sys.argv[1:]``).
+    :param out: stream for normal output (defaults to ``sys.stdout``).
+    :returns: process exit code. Errors print ``error: ...`` to stderr and return 1.
+    """
+    out = out or sys.stdout
+    args = build_parser().parse_args(argv)
+    try:
+        return args.handler(args, out)
+    except (CLIError, ConfigError, ScaffoldError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

avalon_cli/config.py

@@ -0,0 +1,128 @@
+"""Load and validate ``avalon.toml`` project configuration."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "CONFIG_FILENAME",
+    "ConfigError",
+    "DevConfig",
+    "ProjectConfig",
+    "find_project_root",
+    "load_config",
+]
+
+CONFIG_FILENAME = "avalon.toml"
+
+
+class ConfigError(Exception):
+    """Raised when ``avalon.toml`` is missing, unreadable or invalid."""
+
+
+@dataclass(frozen=True)
+class DevConfig:
+    """Settings for ``avalon dev`` (the ``[dev]`` table)."""
+
+    command: str = "{python} app.py"
+    host: str = "127.0.0.1"
+    port: int = 8000
+    watch: tuple[str, ...] = (".",)
+    extensions: tuple[str, ...] = (".py", ".html", ".css", ".js", ".toml")
+    ignore: tuple[str, ...] = (".venv", ".git", "__pycache__", "node_modules")
+    interval: float = 0.5
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    """The fully-resolved contents of an ``avalon.toml`` file."""
+
+    root: Path
+    name: str
+    dev: DevConfig = field(default_factory=DevConfig)
+
+
+def find_project_root(start: str | Path = ".") -> Path:
+    """Walk upward from *start* and return the first directory with ``avalon.toml``.
+
+    Raises :class:`ConfigError` if no such directory exists.
+    """
+    current = Path(start).expanduser().resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / CONFIG_FILENAME).is_file():
+            return candidate
+    raise ConfigError(f"no {CONFIG_FILENAME} found in {current} or any parent directory")
+
+
+def _expect(value: Any, kind: type | tuple[type, ...], key: str) -> Any:
+    # bool is a subclass of int; reject it where a number is expected.
+    if isinstance(value, bool) and bool not in (kind if isinstance(kind, tuple) else (kind,)):
+        raise ConfigError(f"[dev].{key} has the wrong type (got bool)")
+    if not isinstance(value, kind):
+        raise ConfigError(f"[dev].{key} has the wrong type (got {type(value).__name__})")
+    return value
+
+
+def _str_list(value: Any, key: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise ConfigError(f"[dev].{key} must be a list of strings")
+    return tuple(value)
+
+
+def _parse_dev(table: Any) -> DevConfig:
+    if not isinstance(table, dict):
+        raise ConfigError("[dev] must be a table")
+    defaults = DevConfig()
+    known = {"command", "host", "port", "watch", "extensions", "ignore", "interval"}
+    unknown = sorted(set(table) - known)
+    if unknown:
+        raise ConfigError(f"unknown key(s) in [dev]: {', '.join(unknown)}")
+
+    port = _expect(table.get("port", defaults.port), int, "port")
+    if not 0 < port < 65536:
+        raise ConfigError(f"[dev].port must be between 1 and 65535 (got {port})")
+    interval = float(_expect(table.get("interval", defaults.interval), (int, float), "interval"))
+    if interval <= 0:
+        raise ConfigError("[dev].interval must be positive")
+    command = _expect(table.get("command", defaults.command), str, "command")
+    if not command.strip():
+        raise ConfigError("[dev].command must not be empty")
+
+    extensions = _str_list(table.get("extensions", list(defaults.extensions)), "extensions")
+    return DevConfig(
+        command=command,
+        host=_expect(table.get("host", defaults.host), str, "host"),
+        port=port,
+        watch=_str_list(table.get("watch", list(defaults.watch)), "watch"),
+        extensions=tuple(e if e.startswith(".") else f".{e}" for e in extensions),
+        ignore=_str_list(table.get("ignore", list(defaults.ignore)), "ignore"),
+        interval=interval,
+    )
+
+
+def load_config(start: str | Path = ".") -> ProjectConfig:
+    """Find and parse the ``avalon.toml`` governing *start*.
+
+    Missing keys fall back to :class:`DevConfig` defaults; the project name
+    defaults to the directory name. Raises :class:`ConfigError` on any problem.
+    """
+    root = find_project_root(start)
+    path = root / CONFIG_FILENAME
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path}: invalid TOML: {exc}") from None
+    except OSError as exc:
+        raise ConfigError(f"{path}: {exc.strerror}") from None
+
+    project = data.get("project", {})
+    if not isinstance(project, dict):
+        raise ConfigError("[project] must be a table")
+    name = project.get("name", root.name)
+    if not isinstance(name, str) or not name:
+        raise ConfigError("[project].name must be a non-empty string")
+
+    return ProjectConfig(root=root, name=name, dev=_parse_dev(data.get("dev", {})))

avalon_cli/reloader.py

@@ -0,0 +1,218 @@
+"""A dependency-free, polling auto-reloader used by ``avalon dev``.
+
+The reloader runs the project's dev command as a child process, takes
+periodic snapshots of file modification times under the watched
+directories, and restarts the child whenever something changes.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import shlex
+import subprocess
+import sys
+import threading
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from pathlib import Path
+
+__all__ = ["DevServer", "Snapshot", "build_command", "diff_snapshots", "take_snapshot"]
+
+Snapshot = dict[Path, int]
+"""Mapping of file path to ``st_mtime_ns``."""
+
+
+def build_command(template: str, *, host: str, port: int, python: str | None = None) -> list[str]:
+    """Split a dev command template into argv and fill in its placeholders.
+
+    Supported placeholders are ``{host}``, ``{port}`` and ``{python}`` (the
+    current interpreter). Splitting happens *before* substitution so values
+    containing spaces stay a single argument.
+
+    >>> build_command("{python} -m http.server {port}", host="h", port=1, python="py")
+    ['py', '-m', 'http.server', '1']
+
+    Raises :class:`ValueError` for an empty command or an unknown placeholder.
+    """
+    values = {"host": host, "port": port, "python": python or sys.executable}
+    tokens = shlex.split(template)
+    if not tokens:
+        raise ValueError("dev command is empty")
+    try:
+        return [token.format(**values) for token in tokens]
+    except (KeyError, IndexError) as exc:
+        raise ValueError(
+            f"unknown placeholder {exc} in dev command {template!r} "
+            "(supported: {host}, {port}, {python})"
+        ) from None
+
+
+def _is_ignored(name: str, patterns: Iterable[str]) -> bool:
+    return any(fnmatch.fnmatch(name, pattern) for pattern in patterns)
+
+
+def take_snapshot(
+    roots: Iterable[str | Path],
+    extensions: Iterable[str] = (),
+    ignore: Iterable[str] = (),
+) -> Snapshot:
+    """Record the mtime of every watched file under *roots*.
+
+    :param roots: files or directories to watch (missing paths are skipped).
+    :param extensions: file suffixes to include, e.g. ``(".py", ".html")``;
+        empty means every file.
+    :param ignore: glob patterns matched against each file or directory
+        *name*; matching directories are not descended into.
+    """
+    exts = tuple(extensions)
+    patterns = tuple(ignore)
+    snapshot: Snapshot = {}
+
+    def record(path: Path) -> None:
+        if exts and path.suffix not in exts:
+            return
+        try:
+            snapshot[path] = path.stat().st_mtime_ns
+        except OSError:  # deleted between listing and stat
+            pass
+
+    for root in roots:
+        root_path = Path(root).resolve()
+        if root_path.is_file():
+            if not _is_ignored(root_path.name, patterns):
+                record(root_path)
+            continue
+        for dirpath, dirnames, filenames in os.walk(root_path):
+            dirnames[:] = sorted(d for d in dirnames if not _is_ignored(d, patterns))
+            for filename in filenames:
+                if not _is_ignored(filename, patterns):
+                    record(Path(dirpath, filename))
+    return snapshot
+
+
+def diff_snapshots(old: Snapshot, new: Snapshot) -> set[Path]:
+    """Return paths that were added, removed or modified between two snapshots."""
+    changed = set(old.keys() ^ new.keys())
+    changed.update(path for path in old.keys() & new.keys() if old[path] != new[path])
+    return changed
+
+
+def _default_log(message: str) -> None:
+    print(f"[avalon] {message}", file=sys.stderr, flush=True)
+
+
+class DevServer:
+    """Run a command and restart it whenever watched files change.
+
+    Example::
+
+        server = DevServer(["python", "app.py"], cwd="myproj", watch=["."])
+        server.run()  # blocks; Ctrl-C to stop
+    """
+
+    def __init__(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: str | Path = ".",
+        env: Mapping[str, str] | None = None,
+        watch: Iterable[str | Path] = (".",),
+        extensions: Iterable[str] = (),
+        ignore: Iterable[str] = (),
+        interval: float = 0.5,
+        reload: bool = True,
+        log: Callable[[str], None] = _default_log,
+    ) -> None:
+        if not argv:
+            raise ValueError("argv must not be empty")
+        if interval <= 0:
+            raise ValueError("interval must be positive")
+        self.argv = list(argv)
+        self.cwd = Path(cwd).resolve()
+        self.env = dict(os.environ if env is None else env)
+        self.watch = [p if Path(p).is_absolute() else self.cwd / p for p in watch]
+        self.extensions = tuple(extensions)
+        self.ignore = tuple(ignore)
+        self.interval = interval
+        self.reload = reload
+        self.log = log
+        self.process: subprocess.Popen[bytes] | None = None
+        self.restarts = 0
+        self._snapshot: Snapshot = {}
+
+    # -- process control -------------------------------------------------
+    def start(self) -> None:
+        """Start the child process (no-op if it is already running)."""
+        if self.process is not None and self.process.poll() is None:
+            return
+        self.log(f"starting: {shlex.join(self.argv)}")
+        self.process = subprocess.Popen(self.argv, cwd=self.cwd, env=self.env)
+
+    def stop(self, timeout: float = 5.0) -> int | None:
+        """Terminate the child (killing it after *timeout* seconds) and return its exit code."""
+        proc = self.process
+        if proc is None:
+            return None
+        if proc.poll() is None:
+            proc.terminate()
+            try:
+                proc.wait(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait()
+        return proc.returncode
+
+    def restart(self) -> None:
+        """Stop the child if needed and start a fresh one."""
+        self.stop()
+        self.restarts += 1
+        self.start()
+
+    # -- file watching ---------------------------------------------------
+    def poll_changes(self) -> set[Path]:
+        """Take a new snapshot and return the paths that changed since the last one."""
+        new = take_snapshot(self.watch, self.extensions, self.ignore)
+        changed = diff_snapshots(self._snapshot, new)
+        self._snapshot = new
+        return changed
+
+    def run(self, stop_event: threading.Event | None = None) -> int:
+        """Run until the child exits (without reload) or *stop_event* is set.
+
+        With reloading enabled, a child that exits on its own is restarted on
+        the next file change, so a crash can be fixed without restarting
+        ``avalon dev``. Returns the last exit code of the child (0 if it was
+        stopped by us). The child is always terminated before returning.
+        """
+        stop_event = stop_event or threading.Event()
+        self._snapshot = take_snapshot(self.watch, self.extensions, self.ignore)
+        self.start()
+        assert self.process is not None
+        reported_exit = False
+        try:
+            while not stop_event.wait(self.interval):
+                code = self.process.poll()
+                if code is not None and not self.reload:
+                    return code
+                if code is not None and not reported_exit:
+                    self.log(f"process exited with code {code}; waiting for changes...")
+                    reported_exit = True
+                if not self.reload:
+                    continue
+                changed = self.poll_changes()
+                if changed:
+                    names = ", ".join(sorted(_display(p, self.cwd) for p in changed)[:3])
+                    more = f" (+{len(changed) - 3} more)" if len(changed) > 3 else ""
+                    self.log(f"change detected: {names}{more}; restarting")
+                    self.restart()
+                    reported_exit = False
+            return 0
+        finally:
+            self.stop()
+
+
+def _display(path: Path, base: Path) -> str:
+    try:
+        return str(path.relative_to(base))
+    except ValueError:
+        return str(path)

avalon_cli/scaffold.py

@@ -0,0 +1,89 @@
+"""Create new project directories from built-in templates (``avalon new``)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import __version__
+from .templates import DEFAULT_TEMPLATE, get_template
+
+__all__ = ["ScaffoldError", "ScaffoldResult", "create_project", "package_name_for", "validate_project_name"]
+
+_NAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_-]*$")
+
+
+class ScaffoldError(Exception):
+    """Raised when a project cannot be created (bad name, existing directory...)."""
+
+
+@dataclass(frozen=True)
+class ScaffoldResult:
+    """Outcome of :func:`create_project`."""
+
+    root: Path
+    template: str
+    files: tuple[Path, ...]
+
+
+def validate_project_name(name: str) -> str:
+    """Return *name* unchanged if it is a valid project name.
+
+    A valid name starts with a letter and contains only letters, digits,
+    ``-`` and ``_``. Raises :class:`ScaffoldError` otherwise.
+    """
+    if not _NAME_RE.match(name):
+        raise ScaffoldError(
+            f"invalid project name {name!r}: use letters, digits, '-' or '_', starting with a letter"
+        )
+    return name
+
+
+def package_name_for(name: str) -> str:
+    """Convert a project name into a Python identifier (``My-App`` -> ``my_app``)."""
+    return validate_project_name(name).replace("-", "_").lower()
+
+
+def create_project(
+    name: str,
+    template: str = DEFAULT_TEMPLATE,
+    parent: str | Path = ".",
+    *,
+    force: bool = False,
+) -> ScaffoldResult:
+    """Generate a new project called *name* inside *parent*.
+
+    :param name: project name; also the directory name.
+    :param template: name of a built-in template (see ``avalon templates``).
+    :param parent: directory in which the project directory is created.
+    :param force: allow writing into an existing non-empty directory,
+        overwriting files that the template provides.
+    :raises ScaffoldError: for an invalid name, unknown template, or a
+        non-empty target directory without *force*.
+    """
+    validate_project_name(name)
+    try:
+        tmpl = get_template(template)
+    except KeyError as exc:
+        raise ScaffoldError(exc.args[0]) from None
+
+    root = Path(parent).expanduser().resolve() / name
+    if root.exists():
+        if not root.is_dir():
+            raise ScaffoldError(f"{root} exists and is not a directory")
+        if any(root.iterdir()) and not force:
+            raise ScaffoldError(f"{root} is not empty (use --force to write into it)")
+
+    context = {
+        "project_name": name,
+        "package_name": package_name_for(name),
+        "cli_version": __version__,
+    }
+    written: list[Path] = []
+    for rel_path, content in sorted(tmpl.render(context).items()):
+        target = root / rel_path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+        written.append(target)
+    return ScaffoldResult(root=root, template=tmpl.name, files=tuple(written))

avalon_cli/templates.py

@@ -0,0 +1,235 @@
+"""Built-in project templates used by ``avalon new``.
+
+Each template is a mapping of relative file paths to file contents. Contents
+are rendered with :class:`string.Template`, so placeholders look like
+``$project_name`` / ``${package_name}`` and a literal dollar sign is written
+as ``$$``. Using ``string.Template`` (rather than ``str.format``) keeps the
+curly braces in generated Python, HTML, CSS and JavaScript untouched.
+
+Available placeholders:
+
+``project_name``
+    The name given on the command line, e.g. ``my-app``.
+``package_name``
+    A Python-identifier-safe version of the name, e.g. ``my_app``.
+``cli_version``
+    The version of ``avalon-cli`` that generated the project.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from string import Template as _StringTemplate
+
+__all__ = ["ProjectTemplate", "TEMPLATES", "DEFAULT_TEMPLATE", "get_template"]
+
+
+@dataclass(frozen=True)
+class ProjectTemplate:
+    """A named set of files that makes up a new project skeleton."""
+
+    name: str
+    description: str
+    files: dict[str, str] = field(default_factory=dict)
+
+    def render(self, context: dict[str, str]) -> dict[str, str]:
+        """Return ``{relative_path: rendered_content}`` for every file.
+
+        Raises :class:`KeyError` if a template references a placeholder that
+        is missing from *context* (a bug in the template, not user error).
+        """
+        return {
+            path: _StringTemplate(body).substitute(context)
+            for path, body in self.files.items()
+        }
+
+
+_GITIGNORE = """\
+__pycache__/
+*.py[cod]
+.venv/
+.env
+dist/
+build/
+*.egg-info/
+"""
+
+_MINIMAL_TOML = """\
+# Project settings read by avalon-cli (generated by avalon-cli $cli_version).
+
+[project]
+name = "$project_name"
+
+[dev]
+# Command started (and restarted on change) by `avalon dev`.
+# Placeholders: {host}, {port}, {python}. AVALON_HOST / AVALON_PORT are
+# also exported into the child's environment.
+command = "{python} app.py"
+host = "127.0.0.1"
+port = 8000
+watch = ["."]
+extensions = [".py", ".html", ".css", ".js", ".toml"]
+ignore = [".venv", ".git", "__pycache__", "node_modules"]
+"""
+
+_MINIMAL_APP = '''\
+"""Entry point for $project_name, an Avalon real-time application.
+
+Run it with `avalon dev`, which restarts this process whenever a watched
+file changes and passes the address in AVALON_HOST / AVALON_PORT.
+"""
+
+import os
+from pathlib import Path
+
+from avalon import Avalon, HTMLResponse
+
+app = Avalon()
+
+INDEX_HTML = Path(__file__).with_name("templates") / "index.html"
+
+
+@app.get("/")
+def index(request):
+    """Serve the landing page."""
+    return HTMLResponse(INDEX_HTML.read_text(encoding="utf-8"))
+
+
+@app.websocket("/ws/echo")
+async def echo(ws):
+    """Echo every message back to the connected client in real time."""
+    async for message in ws:
+        await ws.send(message)
+
+
+if __name__ == "__main__":
+    app.run(
+        host=os.environ.get("AVALON_HOST", "127.0.0.1"),
+        port=int(os.environ.get("AVALON_PORT", "8000")),
+    )
+'''
+
+_MINIMAL_INDEX = """\
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>$project_name</title>
+</head>
+<body>
+  <h1>$project_name</h1>
+  <p>Edit <code>app.py</code> and save: <code>avalon dev</code> reloads automatically.</p>
+  <script>
+    const ws = new WebSocket(`ws://$${location.host}/ws/echo`);
+    ws.onmessage = (event) => console.log("echo:", event.data);
+    ws.onopen = () => ws.send("hello from $project_name");
+  </script>
+</body>
+</html>
+"""
+
+_MINIMAL_README = """\
+# $project_name
+
+An [Avalon](https://pypi.org/project/avalon/) real-time web application.
+
+```bash
+avalon dev            # start the auto-reloading development server
+avalon info           # show the resolved project configuration
+```
+"""
+
+_STATIC_TOML = """\
+# Project settings read by avalon-cli (generated by avalon-cli $cli_version).
+# This template needs nothing beyond the Python standard library.
+
+[project]
+name = "$project_name"
+
+[dev]
+command = "{python} -m http.server {port} --bind {host} --directory public"
+host = "127.0.0.1"
+port = 8000
+watch = ["public"]
+extensions = [".html", ".css", ".js"]
+ignore = [".git"]
+"""
+
+_STATIC_INDEX = """\
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>$project_name</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <h1>$project_name</h1>
+  <p>A static prototype. Swap to the <code>minimal</code> template when you need real-time features.</p>
+  <script src="app.js"></script>
+</body>
+</html>
+"""
+
+_STATIC_CSS = """\
+body {
+  font-family: system-ui, sans-serif;
+  max-width: 40rem;
+  margin: 3rem auto;
+  padding: 0 1rem;
+}
+"""
+
+_STATIC_JS = """\
+console.log("$project_name loaded");
+"""
+
+_STATIC_README = """\
+# $project_name
+
+A static site served by Python's built-in `http.server`, managed with avalon-cli.
+
+```bash
+avalon dev    # serve ./public and restart when files change
+```
+"""
+
+TEMPLATES: dict[str, ProjectTemplate] = {
+    "minimal": ProjectTemplate(
+        name="minimal",
+        description="Avalon app with one page and a WebSocket echo endpoint.",
+        files={
+            "avalon.toml": _MINIMAL_TOML,
+            "app.py": _MINIMAL_APP,
+            "templates/index.html": _MINIMAL_INDEX,
+            "README.md": _MINIMAL_README,
+            ".gitignore": _GITIGNORE,
+        },
+    ),
+    "static": ProjectTemplate(
+        name="static",
+        description="Plain HTML/CSS/JS served by the standard library (no Avalon needed).",
+        files={
+            "avalon.toml": _STATIC_TOML,
+            "public/index.html": _STATIC_INDEX,
+            "public/style.css": _STATIC_CSS,
+            "public/app.js": _STATIC_JS,
+            "README.md": _STATIC_README,
+            ".gitignore": _GITIGNORE,
+        },
+    ),
+}
+
+DEFAULT_TEMPLATE = "minimal"
+
+
+def get_template(name: str) -> ProjectTemplate:
+    """Look up a built-in template by name.
+
+    Raises :class:`KeyError` with a helpful message listing valid names.
+    """
+    try:
+        return TEMPLATES[name]
+    except KeyError:
+        valid = ", ".join(sorted(TEMPLATES))
+        raise KeyError(f"unknown template {name!r} (choose from: {valid})") from None

avalon_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: avalon-cli
+Version: 0.2.0
+Summary: Command-line companion for the Avalon real-time web framework: scaffold projects and run an auto-reloading dev server.
+Author: nehz
+License-Expression: MIT
+Keywords: avalon,cli,scaffold,dev-server,real-time,web
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# avalon-cli
+
+**The command-line companion for the [Avalon](https://pypi.org/project/avalon/) real-time web framework.**
+
+`avalon-cli` gets you from zero to a running, auto-reloading app in two commands:
+`avalon new` scaffolds a project and `avalon dev` runs it, restarting the server
+every time you save a file. It uses only the Python standard library and does not
+import `avalon` itself, so it installs in seconds and works with any Avalon version
+(or with no framework at all, via the `static` template).
+
+## Features
+
+- **Project scaffolding**: `avalon new` generates a ready-to-run project from a built-in template.
+- **Auto-reloading dev server**: `avalon dev` runs your dev command, watches files by polling
+  (no native dependencies), and restarts the process on change. If the process crashes it waits
+  for your fix and starts again on the next save, so you never have to restart `avalon dev`.
+- **One config file**: `avalon.toml` holds the dev command, host, port and watch rules, found by
+  walking upward from the current directory.
+- **Clean shutdown**: Ctrl-C or SIGTERM always terminates the child process; nothing is orphaned.
+- **Zero dependencies**: standard library only, Python 3.11+.
+
+## Install
+
+```bash
+pip install avalon-cli
+```
+
+This installs the `avalon` command. `python -m avalon_cli` works too.
+
+## Quickstart
+
+```bash
+avalon new chat-demo            # Avalon app (default "minimal" template)
+cd chat-demo
+pip install avalon              # the framework the generated app.py uses
+avalon dev                      # http://127.0.0.1:8000/, reloads on save
+```
+
+No framework yet? The `static` template needs nothing but Python:
+
+```bash
+avalon new mysite --template static
+avalon dev -C mysite --port 9000
+```
+
+## Commands
+
+All commands print errors as `error: <message>` on stderr and exit with status 1;
+usage errors exit with status 2.
+
+### `avalon new NAME [-t TEMPLATE] [-d DIRECTORY] [--force]`
+
+Create the directory `DIRECTORY/NAME` and fill it from a template.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `NAME` | (required) | Project name and directory name. Must start with a letter and contain only letters, digits, `-` and `_`. |
+| `-t`, `--template` | `minimal` | One of the templates listed by `avalon templates`. |
+| `-d`, `--directory` | `.` | Parent directory to create the project in. |
+| `--force` | off | Write into an existing non-empty directory, overwriting files the template provides (other files are left alone). |
+
+An existing *empty* directory is always accepted.
+
+### `avalon templates`
+
+List the built-in templates:
+
+| Template | Files | Notes |
+| --- | --- | --- |
+| `minimal` (default) | `avalon.toml`, `app.py`, `templates/index.html`, `README.md`, `.gitignore` | An Avalon app with one page and a WebSocket echo endpoint. Requires `avalon`. |
+| `static` | `avalon.toml`, `public/index.html`, `public/style.css`, `public/app.js`, `README.md`, `.gitignore` | Served by `python -m http.server`; no dependencies. |
+
+### `avalon dev [-C PROJECT] [--host HOST] [-p PORT] [--interval SECONDS] [--no-reload]`
+
+Find `avalon.toml` (in `PROJECT` or any parent directory), start the configured dev
+command from the project root, and restart it whenever a watched file is added,
+modified or removed.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `-C`, `--project` | `.` | Directory to start looking for `avalon.toml`. |
+| `--host` | `[dev].host` | Overrides the host. |
+| `-p`, `--port` | `[dev].port` | Overrides the port (1-65535). |
+| `--interval` | `[dev].interval` | Seconds between file-change polls. |
+| `--no-reload` | off | Run the command once, without watching; `avalon dev` exits with the command's exit code. |
+
+The child process receives `AVALON_HOST`, `AVALON_PORT` and `AVALON_ENV=development`
+in its environment. With reloading on, `avalon dev` exits with status 0 on SIGTERM
+and 130 on Ctrl-C.
+
+### `avalon info [-C PROJECT]`
+
+Print the `avalon-cli` and Python versions and, if a project is found, its name,
+root, fully-resolved dev command, address, watch paths and extensions.
+
+### `avalon --version`
+
+Print `avalon 0.2.0`.
+
+## Configuration: `avalon.toml`
+
+```toml
+[project]
+name = "chat-demo"          # default: the directory name
+
+[dev]
+command = "{python} app.py" # placeholders: {host}, {port}, {python}
+host = "127.0.0.1"
+port = 8000
+watch = ["."]               # files or directories, relative to the project root
+extensions = [".py", ".html", ".css", ".js", ".toml"]  # [] watches every file
+ignore = [".venv", ".git", "__pycache__", "node_modules"]  # glob patterns matched against names
+interval = 0.5              # seconds between polls
+```
+
+Every key is optional; the values above are the defaults. Extensions without a
+leading dot get one (`"py"` becomes `".py"`). Unknown keys in `[dev]` are rejected
+so typos are caught early. The command is split shell-style *before* placeholders
+are substituted, so a `{python}` path containing spaces stays a single argument.
+`{python}` is the interpreter running `avalon-cli`.
+
+## Python API
+
+Everything the CLI does is available from `avalon_cli`:
+
+```python
+from avalon_cli import DevServer, build_command, create_project, load_config
+
+result = create_project("chat-demo", template="minimal", parent=".", force=False)
+print(result.root, result.template, result.files)   # ScaffoldResult
+
+config = load_config(result.root)                   # ProjectConfig(root, name, dev=DevConfig(...))
+argv = build_command(config.dev.command, host=config.dev.host, port=config.dev.port)
+
+server = DevServer(
+    argv,
+    cwd=config.root,
+    watch=config.dev.watch,
+    extensions=config.dev.extensions,
+    ignore=config.dev.ignore,
+    interval=config.dev.interval,
+)
+server.run()   # blocks; pass a threading.Event to stop it from another thread
+```
+
+| Name | Description |
+| --- | --- |
+| `create_project(name, template="minimal", parent=".", *, force=False) -> ScaffoldResult` | Scaffold a project; raises `ScaffoldError`. |
+| `load_config(start=".") -> ProjectConfig` | Locate and validate `avalon.toml`; raises `ConfigError`. |
+| `find_project_root(start=".") -> Path` | Directory containing the nearest `avalon.toml`; raises `ConfigError`. |
+| `build_command(template, *, host, port, python=None) -> list[str]` | Turn a dev command template into argv; raises `ValueError`. |
+| `DevServer(argv, *, cwd=".", env=None, watch=(".",), extensions=(), ignore=(), interval=0.5, reload=True, log=...)` | Reloading process runner with `start()`, `stop(timeout=5.0)`, `restart()`, `poll_changes()`, `run(stop_event=None) -> int`, and a `restarts` counter. |
+| `take_snapshot(roots, extensions=(), ignore=()) -> dict[Path, int]` | File-to-mtime map of watched files. |
+| `diff_snapshots(old, new) -> set[Path]` | Paths added, removed or modified between two snapshots. |
+| `TEMPLATES`, `get_template(name)`, `ProjectTemplate` | The built-in template registry. |
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e .
+python -m unittest discover -s tests -t .
+```
+
+## License
+
+MIT

avalon_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+avalon_cli/__init__.py,sha256=vuxKHExQw02ogJcf2GvC-FdnELkGUrTwImDR-wLvqTY,1125
+avalon_cli/__main__.py,sha256=WG0hXQDOYngR5yRZsWmhMyzax-2R9KqRqT32ENhUikg,91
+avalon_cli/cli.py,sha256=EVAlA8_gZNBrLcYQE5ikuSpafpwrmYhGwldQUV8ZhyM,6358
+avalon_cli/config.py,sha256=15TVv4eU9nMOc5BqKzUJ_zRxHwNVjxFoGtgdC1zldxM,4664
+avalon_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+avalon_cli/reloader.py,sha256=yVmslWaCToM0RYP2QI5K77pcXkbvBXaAGPjm60nw7Q8,8085
+avalon_cli/scaffold.py,sha256=lzUyL1HMs2oo6JKnuGvxqg6l7FMLKf68eB-hZGyQKjI,2975
+avalon_cli/templates.py,sha256=rOIdth653NW5jbLJF4DFgDrppzb8y_YYFgkWj1cRGas,6152
+avalon_cli-0.2.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+avalon_cli-0.2.0.dist-info/METADATA,sha256=JavRCO6LZAUtoQnYWayoBgDVGQag-h7t0cb40Rn32r4,8043
+avalon_cli-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+avalon_cli-0.2.0.dist-info/entry_points.txt,sha256=5M-BHK_zp4gUzapusuoHdRDVjaDVoa-soZ-8v08PAdQ,47
+avalon_cli-0.2.0.dist-info/top_level.txt,sha256=nROcDniKc61f2q-lh4Kxwobojbp34slyaqPiz-JPyIA,11
+avalon_cli-0.2.0.dist-info/RECORD,,

avalon_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

avalon_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+avalon = avalon_cli.cli:main

avalon_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

avalon_cli-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+avalon_cli