xtr-cli 4.0.2__tar.gz

xtr_cli-4.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xterr
+
+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.

xtr_cli-4.0.2/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: xtr-cli
+Version: 4.0.2
+Summary: Scaffolds a new xtr application — a console application or a web application — in one command, and serves it.
+Keywords: scaffold,new project,template,console,web,xtr-dependency-injection
+Author: Xterr
+Author-email: Xterr <me@xterr.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: xtr-console>=4.0,<5
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# xtr-cli
+
+**A new xtr application — a console application or a web application — ready to run in one command, and served in another.**
+
+<img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
+<img alt="typed" src="https://img.shields.io/badge/typed-ty%20%2B%20basedpyright-1f6feb">
+<img alt="license MIT" src="https://img.shields.io/badge/license-MIT-blue">
+
+</div>
+
+---
+
+## Why?
+
+An application on the xtr packages starts the same way every time: a project manifest, a kernel,
+an entry point that loads the environment and runs the console, a web entry point that serves
+the application from the same kernel. Then each package's *Use in an application* steps — the
+bundle list, the configuration files, the `.env` and ignore lines.
+
+The packages already describe their own steps as recipes, which
+[xtr-recipes](../xtr-recipes) applies. So this tool writes only what no recipe can — the
+manifest, the kernel and the entry points — installs the packages with `uv`, and lets each
+package's recipe configure itself. The project it leaves boots, passes its own tests, and is
+already in the state `recipes:sync --check` expects.
+
+## Install
+
+Nothing to install: run it with `uvx`.
+
+```sh
+uvx xtr-cli new shop
+```
+
+Or install it once, and call it `xtr`:
+
+```sh
+uv tool install xtr-cli
+xtr new shop
+```
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/) on the `PATH`, and `git` unless
+`--no-git` is given.
+
+## Quick start
+
+```console
+$ uvx xtr-cli new shop
+ • cli — A console application: a kernel, its commands, the layered .env files and logging.
+ • webapp — A web application: FastAPI served from the kernel, with the console beside it.
+ Template [cli/webapp] (cli): webapp
+ • orm — Database engines, sessions per unit of work and versioned migrations.
+ • messenger — A message bus: handlers, middleware, transports and consumers.
+ …
+ Add-ons, comma-separated (empty for none): orm, messenger
+ Database drivers for orm — sqlite, postgres, mysql, joined with + (sqlite): sqlite+postgres
+ Transports and serializers for messenger — amqp, taskiq, pydantic, joined with +:
+
+shop — the webapp template
+--------------------------
+
+ • directory: /home/ada/shop
+ • add-ons:   orm (sqlite, postgres), messenger
+ • python:    3.13
+The same, with no question asked:
+  uvx xtr-cli new shop --template=webapp --with=orm:sqlite+postgres,messenger --python=3.13 -n
+
+ Create it? [y/n] (y):
+write pyproject.toml
+…
+run   uv add -- 'xtr-dependency-injection[fastapi]>=4.0,<5' …
+run   uv add --dev -- 'xtr-recipes>=4.0,<5' pytest httpx ruff basedpyright ty
+run   uv run xtr-recipes recipes:sync
+run   git init --quiet
+
+ [OK] shop is ready in /home/ada/shop
+```
+
+```sh
+cd shop
+uv run shop-web             # serve it
+uv run shop debug:bundles   # what is active
+uv run pytest
+```
+
+## Commands
+
+```sh
+xtr project:new [<directory>] [options]   # alias: new — into a new or empty directory
+xtr project:init [options]                # alias: init — into the current directory
+xtr server:start [options]                # alias: serve — run the project's web application
+```
+
+| Option | Default | |
+|---|---|---|
+| `--template` | asked; `cli` with `-n` | `cli`, `webapp`, or a directory holding a `template.toml` |
+| `--name` | the directory's name | the distribution and console script; dashes become underscores for the import package |
+| `--with` | asked; none with `-n` | add-ons, comma-separated: `orm:sqlite+postgres,messenger` |
+| `--python` | the Python running this tool | the `3.<minor>` the project is pinned to; 3.11 or later |
+| `--no-git` | | do not run `git init`; `init` never re-initialises an existing repository |
+| `--dry-run` | | print every file and command, and write nothing |
+| `--local-packages` | | install the xtr packages, editable, from a directory of their sources |
+| `-n` | | ask nothing: every question takes its default |
+
+**Questions fill in only what the command line left out**, and an option given is never asked.
+With `-n` — or wherever nothing can answer, such as CI — nothing is asked at all. Before anything
+is written the run prints the command that makes the same project with no question asked, so an
+answered run can be repeated in a script.
+
+The directory must be missing, or hold nothing but `.git` and editor metadata: nothing is ever
+written over. A name that would not import — a keyword, a module of the standard library — is
+refused before anything is written.
+
+### What it runs
+
+1. Writes the template's files.
+2. `uv add` the template's packages and the add-ons; every unversioned xtr requirement is pinned
+   to this tool's major version, so the files and the packages are from the same release.
+3. `uv add --dev` the tools: `xtr-recipes`, `pytest`, `ruff`, `basedpyright`, `ty`.
+4. `uv run xtr-recipes recipes:sync` — each package's recipe writes `<app>/bundles.py`, its
+   configuration files, its `.env` and `.gitignore` blocks, and `xtr.lock`; the steps it cannot
+   make are printed.
+5. `git init`; nothing is committed.
+
+A step that fails stops the run; what was made so far is left in place, and the error names the
+command to run by hand.
+
+### Serving
+
+```sh
+cd shop
+uvx xtr-cli serve                       # or `xtr serve` once installed
+uvx xtr-cli serve --port 9000 --no-reload
+```
+
+`serve` finds the project — the nearest `pyproject.toml` at or above the current directory, or
+`--project-dir` — and its web entry point, then runs it in the project's own environment with
+`uv run`. The server restarts on every source change; `--no-reload` turns that off.
+
+| Option | Default | |
+|---|---|---|
+| `--project-dir` | the nearest project | the project to serve |
+| `--entrypoint` | found in the project | a console script, or an ASGI application as `module:attribute` |
+| `--host` | the entry point's own | where to listen |
+| `--port` | the entry point's own | the port to listen on |
+| `--reload` / `--no-reload` | `--reload` | restart on every source change |
+| `--dry-run` | | print the command, and run nothing |
+
+The web entry point is found by reading the project's files, never by importing them:
+
+1. **A web console script** — a `[project.scripts]` entry whose module imports `uvicorn`,
+   `hypercorn` or `granian`, or whose name ends in `-web` or `-server`. It is run as it is, so
+   whatever it does before serving — loading the `.env` files, for one — still happens. The host,
+   the port and reloading reach it as `WEB_HOST`, `WEB_PORT` and `WEB_RELOAD=1`, which the
+   `webapp` template's `<name>-web` reads.
+2. **An ASGI application** — only when there is no such script: a module-level
+   `FastAPI()`, `Starlette()` or `Litestar()`, handed to `uv run uvicorn module:attribute`, on
+   `127.0.0.1:8000` unless told otherwise. `uvicorn` must be installed in the project, and
+   nothing the application does at startup outside that module runs.
+
+Several candidates are offered to choose from; with `-n` the command fails and lists them for
+`--entrypoint`. Ctrl-C stops the server and waits for it to finish shutting down, so the
+application's shutdown hooks run.
+
+## Templates
+
+| Template | Packages | Scripts |
+|---|---|---|
+| `cli` | `xtr-dependency-injection`, `xtr-console[di]`, `xtr-dotenv[di,console]`, `xtr-logging[di]` | `<name>` |
+| `webapp` | the same, `xtr-dependency-injection[fastapi]`, `xtr-http-kernel[logging,console]`, `fastapi`, `uvicorn` | `<name>`, `<name>-web` |
+
+Both write `pyproject.toml` (with ruff, basedpyright, ty and pytest configured), `.python-version`,
+`.gitignore`, `README.md`, `src/<app>/kernel.py`, `src/<app>/__main__.py`, an example
+`app:hello` command and a test that builds the kernel. `webapp` adds `src/<app>/web/` — the
+FastAPI application served with `setup(app, kernel)`, its routes and a uvicorn entry point — and
+a test that requests the home page.
+
+### A template of your own
+
+`--template=<directory>` takes any directory holding a `template.toml`:
+
+```toml
+summary = "What it makes, in one line."
+
+[dependencies]
+packages = ["xtr-console[di]"]     # uv add
+dev = ["xtr-recipes", "pytest"]    # uv add --dev; with xtr-recipes, the recipes are applied
+
+[files]
+# destination in the project = file under the template directory
+"pyproject.toml" = "files/pyproject.toml.tmpl"
+"src/${app}/__main__.py" = "files/main.py.tmpl"
+
+[notes]
+next = ["uv run ${name} list"]     # printed once the project is made
+```
+
+Destinations, files and notes substitute `${name}` (the distribution), `${app}` (the import
+name), `${python}` (`3.13`) and `${minor}` (`13`); a literal `$` is written `$$`. An unknown
+placeholder, table or key is an `InvalidTemplateError` before anything is written. Write only
+what no recipe writes: the bundle list, `.env` and the ignore lines are the recipes'.
+
+## Add-ons
+
+Choosing an add-on only adds its requirement; the recipe the package ships configures it, the
+way it would for a package added later with `xtr-recipes recipes:add`.
+
+| Add-on | Installs | Variants |
+|---|---|---|
+| `orm` | `xtr-orm[di,console]` | `sqlite` (default), `postgres`, `mysql` |
+| `messenger` | `xtr-messenger[di,console]` | `amqp`, `taskiq`, `pydantic` |
+| `scheduler` | `xtr-scheduler[di,console,cron]` | |
+| `event-dispatcher` | `xtr-event-dispatcher[di,console]` | |
+| `cache` | `xtr-cache[di,console]` | `redis` |
+| `lock` | `xtr-lock[di]` | `redis` |
+| `rate-limiter` | `xtr-rate-limiter[di,cache,lock]` | `redis` |
+| `storage` | `xtr-storage[di]` | `s3`, `gcs` |
+| `security` | `xtr-security[console]` — `webapp` only | |
+| `jwt` | `xtr-security-jwt[console]` — `webapp` only; brings `security` | |
+
+`jwt` boots without a key and signs nothing until one is there: run
+`uv run <name> jwt:generate-keypair --kid jwt --output-dir secrets` for development, and mount
+the deployment's own key in production. No key is ever minted for you.
+
+Variants follow the name after `:`, joined with `+`: `orm:sqlite+postgres`. A name alone takes
+the defaults; `messenger:` picks none. Asked interactively, an add-on with variants is followed by
+a question for them.
+
+## Errors
+
+Everything this library raises derives from `CliError`, and carries what went wrong as typed
+attributes. A command reports it and exits `1`.
+
+| Error | Raised when |
+|---|---|
+| `DirectoryNotEmptyError` | the directory is a file, or holds anything but version-control and editor metadata |
+| `AmbiguousWebEntryPointError` | `serve` found several web entry points, and no question may be asked |
+| `InvalidProjectNameError` | the name normalises to nothing, or to a keyword, a non-identifier or a standard-library module |
+| `InvalidTemplateError` | a `template.toml` does not parse, holds an unknown key, names a missing file, or a placeholder is unknown |
+| `ProjectNotFoundError` | `serve` was run outside a project |
+| `StepFailedError` | `uv` or `git` exited with a failure; the later steps were not run |
+| `UnknownAddOnError` | `--with` names an unknown add-on, one the template cannot take, one twice, or an unknown variant |
+| `UnknownTemplateError` | `--template` is neither a shipped template nor a directory holding one |
+| `UnsupportedPythonError` | `--python` is not `3.<minor>` with a minor of 11 or more |
+| `WebEntryPointNotFoundError` | the project has nothing to serve, or `--entrypoint` names nothing it has |
+
+## Layout
+
+```
+xtr_cli/
+├── command/                 project:new, project:init and server:start
+├── command_support.py       what both commands share: questions, plan, apply, report
+├── project_questions.py     what the command line left out, asked
+├── project_name.py          the distribution and import names
+├── project_settings.py      everything decided, and the command line repeating it
+├── template.py              a template.toml and its files
+├── template_catalog.py      the shipped templates, or a directory
+├── add_on.py                one add-on: a name standing for a requirement
+├── add_on_catalog.py        the add-ons, and how --with names them
+├── scaffolder.py            settings into a plan, a plan into a project
+├── scaffold_plan.py         the files and commands, before anything is made
+├── web_entry_point.py       what serves an application, and the command starting it
+├── web_entry_point_finder.py the project around a directory, and its web entry point
+├── subprocess_runner.py     uv, git and the server, run as real processes
+├── templates/               cli/ and webapp/
+└── exception/               CliError, the root of everything this library raises
+```
+
+## Development
+
+Developed in the [python-xtr](https://github.com/xterr/python-xtr) monorepo, under
+`packages/xtr-cli`; run the commands below from there.
+
+```sh
+uv sync --all-extras
+uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
+```
+
+`tests/integration/test_scaffold.py` makes each template for real, from the working tree's
+packages, and runs the project's own checks and commands. It needs `uv` and the network for the
+third-party packages, and is skipped unless `XTR_CLI_SCAFFOLD=1` is set.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

xtr_cli-4.0.2/README.md

@@ -0,0 +1,286 @@
+<div align="center">
+
+# xtr-cli
+
+**A new xtr application — a console application or a web application — ready to run in one command, and served in another.**
+
+<img alt="python 3.11+" src="https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB?logo=python&logoColor=white">
+<img alt="typed" src="https://img.shields.io/badge/typed-ty%20%2B%20basedpyright-1f6feb">
+<img alt="license MIT" src="https://img.shields.io/badge/license-MIT-blue">
+
+</div>
+
+---
+
+## Why?
+
+An application on the xtr packages starts the same way every time: a project manifest, a kernel,
+an entry point that loads the environment and runs the console, a web entry point that serves
+the application from the same kernel. Then each package's *Use in an application* steps — the
+bundle list, the configuration files, the `.env` and ignore lines.
+
+The packages already describe their own steps as recipes, which
+[xtr-recipes](../xtr-recipes) applies. So this tool writes only what no recipe can — the
+manifest, the kernel and the entry points — installs the packages with `uv`, and lets each
+package's recipe configure itself. The project it leaves boots, passes its own tests, and is
+already in the state `recipes:sync --check` expects.
+
+## Install
+
+Nothing to install: run it with `uvx`.
+
+```sh
+uvx xtr-cli new shop
+```
+
+Or install it once, and call it `xtr`:
+
+```sh
+uv tool install xtr-cli
+xtr new shop
+```
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/) on the `PATH`, and `git` unless
+`--no-git` is given.
+
+## Quick start
+
+```console
+$ uvx xtr-cli new shop
+ • cli — A console application: a kernel, its commands, the layered .env files and logging.
+ • webapp — A web application: FastAPI served from the kernel, with the console beside it.
+ Template [cli/webapp] (cli): webapp
+ • orm — Database engines, sessions per unit of work and versioned migrations.
+ • messenger — A message bus: handlers, middleware, transports and consumers.
+ …
+ Add-ons, comma-separated (empty for none): orm, messenger
+ Database drivers for orm — sqlite, postgres, mysql, joined with + (sqlite): sqlite+postgres
+ Transports and serializers for messenger — amqp, taskiq, pydantic, joined with +:
+
+shop — the webapp template
+--------------------------
+
+ • directory: /home/ada/shop
+ • add-ons:   orm (sqlite, postgres), messenger
+ • python:    3.13
+The same, with no question asked:
+  uvx xtr-cli new shop --template=webapp --with=orm:sqlite+postgres,messenger --python=3.13 -n
+
+ Create it? [y/n] (y):
+write pyproject.toml
+…
+run   uv add -- 'xtr-dependency-injection[fastapi]>=4.0,<5' …
+run   uv add --dev -- 'xtr-recipes>=4.0,<5' pytest httpx ruff basedpyright ty
+run   uv run xtr-recipes recipes:sync
+run   git init --quiet
+
+ [OK] shop is ready in /home/ada/shop
+```
+
+```sh
+cd shop
+uv run shop-web             # serve it
+uv run shop debug:bundles   # what is active
+uv run pytest
+```
+
+## Commands
+
+```sh
+xtr project:new [<directory>] [options]   # alias: new — into a new or empty directory
+xtr project:init [options]                # alias: init — into the current directory
+xtr server:start [options]                # alias: serve — run the project's web application
+```
+
+| Option | Default | |
+|---|---|---|
+| `--template` | asked; `cli` with `-n` | `cli`, `webapp`, or a directory holding a `template.toml` |
+| `--name` | the directory's name | the distribution and console script; dashes become underscores for the import package |
+| `--with` | asked; none with `-n` | add-ons, comma-separated: `orm:sqlite+postgres,messenger` |
+| `--python` | the Python running this tool | the `3.<minor>` the project is pinned to; 3.11 or later |
+| `--no-git` | | do not run `git init`; `init` never re-initialises an existing repository |
+| `--dry-run` | | print every file and command, and write nothing |
+| `--local-packages` | | install the xtr packages, editable, from a directory of their sources |
+| `-n` | | ask nothing: every question takes its default |
+
+**Questions fill in only what the command line left out**, and an option given is never asked.
+With `-n` — or wherever nothing can answer, such as CI — nothing is asked at all. Before anything
+is written the run prints the command that makes the same project with no question asked, so an
+answered run can be repeated in a script.
+
+The directory must be missing, or hold nothing but `.git` and editor metadata: nothing is ever
+written over. A name that would not import — a keyword, a module of the standard library — is
+refused before anything is written.
+
+### What it runs
+
+1. Writes the template's files.
+2. `uv add` the template's packages and the add-ons; every unversioned xtr requirement is pinned
+   to this tool's major version, so the files and the packages are from the same release.
+3. `uv add --dev` the tools: `xtr-recipes`, `pytest`, `ruff`, `basedpyright`, `ty`.
+4. `uv run xtr-recipes recipes:sync` — each package's recipe writes `<app>/bundles.py`, its
+   configuration files, its `.env` and `.gitignore` blocks, and `xtr.lock`; the steps it cannot
+   make are printed.
+5. `git init`; nothing is committed.
+
+A step that fails stops the run; what was made so far is left in place, and the error names the
+command to run by hand.
+
+### Serving
+
+```sh
+cd shop
+uvx xtr-cli serve                       # or `xtr serve` once installed
+uvx xtr-cli serve --port 9000 --no-reload
+```
+
+`serve` finds the project — the nearest `pyproject.toml` at or above the current directory, or
+`--project-dir` — and its web entry point, then runs it in the project's own environment with
+`uv run`. The server restarts on every source change; `--no-reload` turns that off.
+
+| Option | Default | |
+|---|---|---|
+| `--project-dir` | the nearest project | the project to serve |
+| `--entrypoint` | found in the project | a console script, or an ASGI application as `module:attribute` |
+| `--host` | the entry point's own | where to listen |
+| `--port` | the entry point's own | the port to listen on |
+| `--reload` / `--no-reload` | `--reload` | restart on every source change |
+| `--dry-run` | | print the command, and run nothing |
+
+The web entry point is found by reading the project's files, never by importing them:
+
+1. **A web console script** — a `[project.scripts]` entry whose module imports `uvicorn`,
+   `hypercorn` or `granian`, or whose name ends in `-web` or `-server`. It is run as it is, so
+   whatever it does before serving — loading the `.env` files, for one — still happens. The host,
+   the port and reloading reach it as `WEB_HOST`, `WEB_PORT` and `WEB_RELOAD=1`, which the
+   `webapp` template's `<name>-web` reads.
+2. **An ASGI application** — only when there is no such script: a module-level
+   `FastAPI()`, `Starlette()` or `Litestar()`, handed to `uv run uvicorn module:attribute`, on
+   `127.0.0.1:8000` unless told otherwise. `uvicorn` must be installed in the project, and
+   nothing the application does at startup outside that module runs.
+
+Several candidates are offered to choose from; with `-n` the command fails and lists them for
+`--entrypoint`. Ctrl-C stops the server and waits for it to finish shutting down, so the
+application's shutdown hooks run.
+
+## Templates
+
+| Template | Packages | Scripts |
+|---|---|---|
+| `cli` | `xtr-dependency-injection`, `xtr-console[di]`, `xtr-dotenv[di,console]`, `xtr-logging[di]` | `<name>` |
+| `webapp` | the same, `xtr-dependency-injection[fastapi]`, `xtr-http-kernel[logging,console]`, `fastapi`, `uvicorn` | `<name>`, `<name>-web` |
+
+Both write `pyproject.toml` (with ruff, basedpyright, ty and pytest configured), `.python-version`,
+`.gitignore`, `README.md`, `src/<app>/kernel.py`, `src/<app>/__main__.py`, an example
+`app:hello` command and a test that builds the kernel. `webapp` adds `src/<app>/web/` — the
+FastAPI application served with `setup(app, kernel)`, its routes and a uvicorn entry point — and
+a test that requests the home page.
+
+### A template of your own
+
+`--template=<directory>` takes any directory holding a `template.toml`:
+
+```toml
+summary = "What it makes, in one line."
+
+[dependencies]
+packages = ["xtr-console[di]"]     # uv add
+dev = ["xtr-recipes", "pytest"]    # uv add --dev; with xtr-recipes, the recipes are applied
+
+[files]
+# destination in the project = file under the template directory
+"pyproject.toml" = "files/pyproject.toml.tmpl"
+"src/${app}/__main__.py" = "files/main.py.tmpl"
+
+[notes]
+next = ["uv run ${name} list"]     # printed once the project is made
+```
+
+Destinations, files and notes substitute `${name}` (the distribution), `${app}` (the import
+name), `${python}` (`3.13`) and `${minor}` (`13`); a literal `$` is written `$$`. An unknown
+placeholder, table or key is an `InvalidTemplateError` before anything is written. Write only
+what no recipe writes: the bundle list, `.env` and the ignore lines are the recipes'.
+
+## Add-ons
+
+Choosing an add-on only adds its requirement; the recipe the package ships configures it, the
+way it would for a package added later with `xtr-recipes recipes:add`.
+
+| Add-on | Installs | Variants |
+|---|---|---|
+| `orm` | `xtr-orm[di,console]` | `sqlite` (default), `postgres`, `mysql` |
+| `messenger` | `xtr-messenger[di,console]` | `amqp`, `taskiq`, `pydantic` |
+| `scheduler` | `xtr-scheduler[di,console,cron]` | |
+| `event-dispatcher` | `xtr-event-dispatcher[di,console]` | |
+| `cache` | `xtr-cache[di,console]` | `redis` |
+| `lock` | `xtr-lock[di]` | `redis` |
+| `rate-limiter` | `xtr-rate-limiter[di,cache,lock]` | `redis` |
+| `storage` | `xtr-storage[di]` | `s3`, `gcs` |
+| `security` | `xtr-security[console]` — `webapp` only | |
+| `jwt` | `xtr-security-jwt[console]` — `webapp` only; brings `security` | |
+
+`jwt` boots without a key and signs nothing until one is there: run
+`uv run <name> jwt:generate-keypair --kid jwt --output-dir secrets` for development, and mount
+the deployment's own key in production. No key is ever minted for you.
+
+Variants follow the name after `:`, joined with `+`: `orm:sqlite+postgres`. A name alone takes
+the defaults; `messenger:` picks none. Asked interactively, an add-on with variants is followed by
+a question for them.
+
+## Errors
+
+Everything this library raises derives from `CliError`, and carries what went wrong as typed
+attributes. A command reports it and exits `1`.
+
+| Error | Raised when |
+|---|---|
+| `DirectoryNotEmptyError` | the directory is a file, or holds anything but version-control and editor metadata |
+| `AmbiguousWebEntryPointError` | `serve` found several web entry points, and no question may be asked |
+| `InvalidProjectNameError` | the name normalises to nothing, or to a keyword, a non-identifier or a standard-library module |
+| `InvalidTemplateError` | a `template.toml` does not parse, holds an unknown key, names a missing file, or a placeholder is unknown |
+| `ProjectNotFoundError` | `serve` was run outside a project |
+| `StepFailedError` | `uv` or `git` exited with a failure; the later steps were not run |
+| `UnknownAddOnError` | `--with` names an unknown add-on, one the template cannot take, one twice, or an unknown variant |
+| `UnknownTemplateError` | `--template` is neither a shipped template nor a directory holding one |
+| `UnsupportedPythonError` | `--python` is not `3.<minor>` with a minor of 11 or more |
+| `WebEntryPointNotFoundError` | the project has nothing to serve, or `--entrypoint` names nothing it has |
+
+## Layout
+
+```
+xtr_cli/
+├── command/                 project:new, project:init and server:start
+├── command_support.py       what both commands share: questions, plan, apply, report
+├── project_questions.py     what the command line left out, asked
+├── project_name.py          the distribution and import names
+├── project_settings.py      everything decided, and the command line repeating it
+├── template.py              a template.toml and its files
+├── template_catalog.py      the shipped templates, or a directory
+├── add_on.py                one add-on: a name standing for a requirement
+├── add_on_catalog.py        the add-ons, and how --with names them
+├── scaffolder.py            settings into a plan, a plan into a project
+├── scaffold_plan.py         the files and commands, before anything is made
+├── web_entry_point.py       what serves an application, and the command starting it
+├── web_entry_point_finder.py the project around a directory, and its web entry point
+├── subprocess_runner.py     uv, git and the server, run as real processes
+├── templates/               cli/ and webapp/
+└── exception/               CliError, the root of everything this library raises
+```
+
+## Development
+
+Developed in the [python-xtr](https://github.com/xterr/python-xtr) monorepo, under
+`packages/xtr-cli`; run the commands below from there.
+
+```sh
+uv sync --all-extras
+uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
+```
+
+`tests/integration/test_scaffold.py` makes each template for real, from the working tree's
+packages, and runs the project's own checks and commands. It needs `uv` and the network for the
+third-party packages, and is skipped unless `XTR_CLI_SCAFFOLD=1` is set.
+
+## License
+
+MIT — see [LICENSE](LICENSE).