bamboo-coding 0.1.0__tar.gz

bamboo_coding-0.1.0/PKG-INFO

@@ -0,0 +1,284 @@
+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

bamboo_coding-0.1.0/README.md

@@ -0,0 +1,270 @@
+# 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