bot-bottle/docs/prds/prd-new-install-script.md

PRD prd-new: 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:

[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.