Metadata-Version: 2.4
Name: bamboo-coding
Version: 0.1.0
Summary: Bamboo Coding controller and client
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi==0.115.0
Requires-Dist: uvicorn==0.30.6
Requires-Dist: gitpython==3.1.40
Requires-Dist: python-dotenv==1.0.0
Requires-Dist: websockets==13.1
Requires-Dist: httpx==0.27.2
Requires-Dist: bamboo-ssh

# Bamboo Coding

Bamboo Coding is a FastAPI-based workspace and Git review system with an outbound Python client and a browser UI.

## Architecture

- `bamboo_coding/server/`: packaged server entrypoint and public app surface
- `bamboo_coding/client/`: packaged outbound client runtime
- `controller/app/`: controller internals used by the packaged server entrypoint
- `shared/`: legacy shared protocol implementation backing the new namespace
- `static/`: browser UI assets

The controller never reads arbitrary local paths itself. Clients connect outward, advertise allowed roots, wait for approval, and then handle tasks for paths inside those roots.

## Features

- Web approval for pending clients
- Client-first workspace selection in the UI
- Direct folder browsing, including non-Git folders
- Automatic Git mode when the selected path is inside a repository
- Changed-files-first tree, diff viewer, commit history, branches, stage/unstage, and commit
- Durable client token storage and task journal
- Multi-terminal browser dialogs bound to the selected client and path

## Requirements

- Python 3.12+
- Git 2.x+

## Install

```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
```

## Client Config

The client reads `~/.bamboo-coding/bamboo-coding.toml` by default.

Quick start:

```bash
bamboo-coding setup
bamboo-coding run
```

`setup` creates the config file if it is missing. By default it uses the current working directory as the first allowed root. You can override the generated values:

```bash
bamboo-coding setup --root /work/project-a --root /work/project-b --client-id worker-1 --hostname devbox
```

Example generated config:

```toml
[client]
controller_url = "ws://127.0.0.1:8100/ws/agents"
client_id = "worker-1"
hostname = "devbox"
allowed_roots = ["/work/project-a", "/work/project-b"]
max_concurrent_tasks = 1

[storage]
token_path = "~/.bamboo-coding/token.json"
journal_path = "~/.bamboo-coding/journal.db"
```

Environment variables still override TOML values. Existing `AGENT_*` overrides remain supported during the transition.

## Makefile Commands

The repository now includes a root `Makefile` as the quick command hub.

Common targets:

```bash
make help              # list available commands
make dev               # run the server locally
make start             # start the server with docker compose
make stop              # stop the docker compose stack
make restart           # restart the docker compose stack
make logs              # follow server logs
make ps                # show compose service state
make test              # run the full pytest suite
make client-install    # install editable package plus build/upload tooling
make client-clean      # remove build artifacts and Python cache files
make client-build      # build wheel and sdist into dist/
make client-reinstall  # clean and reinstall the editable package
make client-deploy     # publish dist/* to real PyPI
```

`client-deploy` publishes to the real PyPI index. It prompts for a PyPI deploy
token when one is missing:

```bash
make client-deploy
```

You can also provide the token through the environment for non-interactive runs:

```bash
export PYPI_TOKEN=<pypi-token>
make client-deploy
```

The Makefile maps `PYPI_TOKEN` to Twine's token auth internally by setting
`TWINE_USERNAME=__token__` and `TWINE_PASSWORD=<pypi-token>`.

## Docker Folder

The server Docker assets live under `docker/`:

```text
docker/
  compose.server.yml
  server.Dockerfile
```

## Run Locally

### 1. Start the server

```bash
bamboo-coding-server --dev --host 127.0.0.1 --port 8100
```

The legacy launcher also still works:

```bash
.venv/bin/python app.py --dev --host 127.0.0.1 --port 8100
```

### 2. Setup and run a client

First write the default config:

```bash
bamboo-coding setup
```

Then start the long-running client:

```bash
bamboo-coding run
```

Bare `bamboo-coding` is an alias for `bamboo-coding run`.

For one-off value overrides you can still use environment variables, but `run` still expects a config file to exist:

```bash
CONTROLLER_URL=ws://127.0.0.1:8100/ws/agents AGENT_CLIENT_ID=worker-1 AGENT_ALLOWED_ROOTS=/work/project-a:/work/project-b bamboo-coding run
```

The module entrypoint is also available:

```bash
.venv/bin/python -m bamboo_coding.client.main run
```

### 3. Approve the client in the web UI

Open:

```text
http://127.0.0.1:8100/
```

The start page shows:

- approved clients first, with live root counts
- pending clients with an `Approve` button
- roots and immediate children only after you pick a specific client

Once approved, the client stores its token under `~/.bamboo-coding/` by default and reconnects automatically on the next start.

### 4. Open terminals from the web UI

After you pick a client and workspace, use the `Terminal` button in the header.

Terminal behavior:

- each terminal attaches to the currently selected client
- the initial shell directory uses the current selected path
- you can open multiple terminals in the same page
- windows can be dragged, resized, and maximized inside the page
- `Hide` moves a terminal into the bottom-right dock; click the dock item to restore it
- the header `Layout` control supports `Hidden`, `1`, `1|2`, `1|2|3`, and `2x2` presets
- applying `Hidden` docks every open terminal without closing the sessions
- applying a layout restores all open terminals, fills the preset slots by open order, and docks overflow terminals
- with an active layout, new terminals join the preset only while free slots remain; after that they open as floating windows
- the main page `Shortcuts` button opens browser-local terminal shortcut settings
- default terminal shortcuts are `Ctrl+Down` for `Hidden` and `Ctrl+Up` for `2x2`
- leaving or refreshing the page while any terminal windows remain open triggers the browser unload warning

There is also a standalone terminal page that reuses the same component:

```text
http://127.0.0.1:8100/terminal?agent_id=<agent-id>&path=/absolute/path
```

### 5. Open a specific workspace directly

When multiple clients may advertise the same path, include both the client and the path:

```text
http://127.0.0.1:8100/?agent_id=<agent-id>&path=/absolute/path/inside/an/approved/root
```

Path-only links still work when the owner is unambiguous:

```text
http://127.0.0.1:8100/?path=/absolute/path/inside/an/approved/root
```

If the path is inside a Git repository, Git actions are enabled. If it is only a normal folder, the UI still shows the file tree and editor.

## Public API

### Discovery and approval

- `GET /api/health`
- `GET /api/agents` (includes live `roots` for connected approved clients)
- `POST /api/agents/{agent_id}/approve`
- `GET /api/roots`

### Filesystem

- `GET /api/fs/tree?path=...&agent_id=...`
- `GET /api/fs/browse?path=...&agent_id=...`
- `GET /api/fs/file?path=...&agent_id=...`
- `PUT /api/fs/file?path=...&agent_id=...`

### Git

- `GET /api/git/status?path=...&agent_id=...`
- `GET /api/git/diff?path=...&file=...&agent_id=...`
- `GET /api/git/commits?path=...&agent_id=...`
- `GET /api/git/commit/{commit_hash}?path=...&agent_id=...`
- `POST /api/git/stage?path=...&agent_id=...`
- `POST /api/git/unstage?path=...&agent_id=...`
- `GET /api/git/branches?path=...&agent_id=...`
- `POST /api/git/branches?path=...&agent_id=...`
- `PUT /api/git/branches/checkout?path=...&agent_id=...`
- `DELETE /api/git/branches/{name}?path=...&agent_id=...`
- `POST /api/git/branches/merge?path=...&agent_id=...`
- `POST /api/git/commit?path=...&agent_id=...`

### Client transport

- `WS /ws/agents`
- `WS /ws/terminal?agent_id=...&path=...&terminal_id=...&cols=...&rows=...`

## Testing

```bash
.venv/bin/python -m pytest -q
```

## Repository Layout

- `app.py`: legacy server launcher pointing at `bamboo_coding.server.main`
- `bamboo_coding/server/`: packaged server entrypoint
- `bamboo_coding/client/`: packaged client runtime
- `controller/app/`: controller internals
- `static/`: SPA assets
- `docker/`: server Docker Compose and Dockerfile assets
- `tests/`: controller, client, protocol, and Git utility tests
