# PRD 0054: Install script

- **Status:** Draft
- **Author:** didericis
- **Created:** 2026-06-06
- **Issue:** #197

## Summary

Add a proper Python package distribution and a thin `install.sh` bootstrapper so users can install bot-bottle with a single command without cloning the repo.

## Problem

There is currently no install path for new users. The only way to run bot-bottle is to clone the repo and invoke `cli.py` directly. This blocks any HN-style public demo: readers want `curl | sh` or `pipx install`, not a manual clone-and-configure flow.

## Goals / Success Criteria

- `curl -fsSL <url>/install.sh | sh` (or equivalent) leaves a working `bot-bottle` command on PATH.
- Python-native users can install with `pipx install bot-bottle` or `uv tool install bot-bottle`.
- `install.sh` validates prerequisites (Python ≥ 3.11, Docker) and exits with a clear message if they are missing. It does not silently install Docker.
- `install.sh` runs `bot-bottle doctor` (or equivalent diagnostic) after install to confirm the environment is ready.
- The package has no runtime pip dependencies (stdlib-only, matching the existing constraint).

## Non-goals

- Bundling a Python runtime or producing a standalone binary.
- Automatic Docker installation.
- Plugin architecture changes (out of scope; see issue #197 for future direction).
- Publishing to PyPI in this PR — the package structure is the deliverable; publishing is a separate step.

## Design

### Package structure

Add a minimal `pyproject.toml` at the repo root:

```toml
[project]
name = "bot-bottle"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
bot-bottle = "bot_bottle.cli:main"
```

The existing `bot_bottle/` package and `cli.py` entry point already contain the logic; this just wires up the standard entry point. `cli.py` may need a small refactor to expose a `main()` callable if it uses `if __name__ == "__main__"` only.

### `install.sh`

A thin bootstrapper that:

1. Checks `python3 --version` ≥ 3.11; exits with instructions if not met.
2. Checks `docker info` exits 0; exits with instructions if Docker is not running.
3. Installs via `pipx` if available, otherwise falls back to `pip install --user`.
4. Runs `bot-bottle doctor` to verify the install.

The script must be idempotent (safe to re-run) and must not require `sudo`.

### `bot-bottle doctor`

A new subcommand that checks and reports:

- Python version.
- Docker daemon reachability.
- Whether `~/.bot-bottle/` config directory exists.

Exits 0 if all checks pass, non-zero otherwise.

## Open questions

- Where should `install.sh` be hosted for the `curl | sh` path? (Options: raw Gitea, a separate static host, GitHub releases if/when the repo is mirrored.) Resolve before shipping.
- Should `version` in `pyproject.toml` be driven by a git tag at build time (e.g. via `hatch-vcs`) or kept as a static string? Static is simpler for now.