# PRD prd-new: Quick install script

- **Status:** Draft
- **Author:** claude
- **Created:** 2026-07-25
- **Issue:** #197

## Summary

Add a proper Python package distribution (`pyproject.toml` with a
`bot-bottle` entry point) plus a thin `install.sh` bootstrapper, so users
can install bot-bottle with a single command instead of cloning the repo
and invoking `cli.py` directly. A new `bot-bottle doctor` subcommand
verifies host prerequisites after install.

## 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`. This blocks any
public demo: readers want `curl | sh` or `pipx install`, not a manual
clone-and-configure flow. There is also no single command that tells a
user whether their host is actually ready to run a bottle.

## Goals / Success Criteria

- `curl -fsSL <raw-url>/install.sh | sh` leaves a working `bot-bottle`
  command on PATH.
- Python-native users can install with `pipx install bot-bottle` or
  `uv tool install bot-bottle` (once published) — or from a local
  checkout today.
- `install.sh` validates prerequisites (Python ≥ 3.11), creates the
  `~/.bot-bottle/` config tree, installs the package, and runs
  `bot-bottle doctor`. It never installs Docker or a VM backend silently
  and never uses `sudo`.
- `install.sh` is idempotent — safe to re-run.
- `bot-bottle doctor` reports Python version, backend availability, and
  config-dir presence, exiting non-zero when a hard prerequisite is unmet.
- The package keeps **zero runtime pip dependencies** (stdlib-only,
  matching the existing constraint in `AGENTS.md`).

## Non-goals

- Bundling a Python runtime or producing a standalone binary.
- Automatic Docker / VM-backend installation.
- Plugin-architecture changes (issue #197 floats a containerized-plugin
  direction; that's a separate feature).
- Publishing to a package index in this PR — the package *structure* is
  the deliverable; publishing is a follow-up step.

## Design

### Package structure (`pyproject.toml`)

Fill out the previously-stub `pyproject.toml` with project metadata, a
console-script entry point, and package-data for the non-Python assets the
runtime reads from inside the package:

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

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

`bot_bottle.cli:main` already exists (the `cli.py` shim calls it), so no
refactor of the entry point is needed. `package-data` ships the container
Dockerfiles, `egress_entrypoint.sh`, the firecracker netpool defaults, and
the macos-container init script so an installed wheel can still build its
sidecar/agent images.

### `install.sh`

A POSIX `sh` bootstrapper that:

1. Checks `python3` is present and ≥ 3.11; exits with a clear message
   otherwise.
2. Creates `~/.bot-bottle/{agents,bottles,contrib}`.
3. Installs via `pipx` if available, else `python3 -m pip install --user`.
   The spec defaults to the git URL and is overridable via
   `BOT_BOTTLE_INSTALL_SPEC` (used by tests / local installs).
4. Locates the `bot-bottle` entry point (PATH or `~/.local/bin`).
5. Runs `bot-bottle doctor` and reports the result.

It is idempotent and never calls `sudo`.

### `bot-bottle doctor`

A new store-free subcommand (no DB migration required) that checks and
reports:

- **python** — interpreter version (hard requirement: ≥ 3.11).
- **backend** — at least one backend available on this host
  (macos-container / firecracker / docker), reusing
  `is_backend_available()` rather than hardcoding Docker, since the
  default backend is now a VM backend. Hard requirement.
- **config** — whether `~/.bot-bottle/` exists (advisory only; `start`
  provisions on first run).

Exits 0 when both hard requirements pass, non-zero otherwise.

## Testing strategy

- Unit test `bot-bottle doctor` success/failure paths with backend
  availability and Python version mocked.
- Unit test that `pyproject.toml` parses, declares the entry point and an
  empty `dependencies` list, and that every `package-data` glob resolves
  to a file that exists on disk (guards against drift).
- Unit test that `install.sh` is executable, POSIX-ish (`set -eu`), never
  calls `sudo`, and runs `doctor` after install.

## Open questions

- Should `version` be derived from a git tag at build time (e.g.
  `hatch-vcs`) or kept static? Static (`0.1.0`) is simpler for now.
- Publishing target (PyPI vs. a self-hosted index) is deferred.