teabag 0.1.0__tar.gz

teabag-0.1.0/PKG-INFO

@@ -0,0 +1,423 @@
+Metadata-Version: 2.1
+Name: teabag
+Version: 0.1.0
+Summary: AI-native version control CLI for safe AI-assisted development.
+Author-email: teaBag <devnull@example.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# teaBag — How to Use
+
+teaBag is a CLI for **AI-native version control**: it keeps your main codebase safe while AI tools edit code in isolated workspaces, and it records every run (prompt, intent, and diff) so you can review, compare, and merge changes in a structured way.
+
+The CLI command is **`tb`**.
+
+---
+
+## Installation
+
+From the teaBag project root:
+
+```bash
+pip install -e .
+```
+
+This installs the `tb` command. Requires **Python 3.10+** and a **git** repository (recommended) for diff capture.
+
+---
+
+## Quick Start
+
+```bash
+cd /path/to/your/project
+
+# 1. Initialize teaBag (creates .teabag/, workspaces/, .ai_history/, env_store/)
+tb init
+
+# 2. Create a workspace for an AI agent
+tb spawn agent_1
+
+# 3. Human fills prompt.json (tb spawn creates a default with _teabag section)
+#    AI reads prompt.json and writes intent.json (only intent.json first)
+# 4. Point your AI at workspaces/agent_1 to edit code, then record the run
+tb run agent_1
+
+# 5. List runs
+tb list-runs
+
+# 6. When done, remove the workspace
+tb delete-workspace agent_1
+```
+
+Your main project files stay untouched; all AI edits live under `workspaces/agent_1/`. Each `tb run` creates a snapshot under `.ai_history/run_001/`, `run_002/`, and so on.
+
+---
+
+## Directory Layout
+
+After `tb init`, your repo looks like this:
+
+```
+your_project/
+├── .teabag/           # Config and metadata
+│   ├── config.json
+│   ├── experiments.json
+│   └── snapshots/     # Workspace snapshots (see below)
+├── .ai_history/       # Recorded runs (immutable: intent.json and all artifacts are read-only after creation)
+│   └── run_001/
+│       ├── prompt.json   # or prompt.md (human prompt; _teabag section in .json)
+│       ├── intent.json
+│       ├── diff.patch
+│       ├── metadata.json
+│       ├── environment.json   # Python version, packages
+│       ├── tests.json        # If teabag.json test_command is set
+│       └── metrics.json      # If teabag.json metrics_script is set
+├── workspaces/        # One directory per agent
+│   └── agent_1/
+│       ├── venv       # Symlink to shared env (or ENV_PATH file)
+│       ├── prompt.json  # default from tb spawn; human fills "prompt"; AI reads and writes intent.json
+│       └── intent.json  # written by AI from prompt.json
+├── env_store/         # Shared virtualenvs (keyed by Python + requirements.txt)
+└── src/               # Your real code (unchanged until you accept a run)
+```
+
+---
+
+## Workspaces and Shared Environments
+
+### Creating a workspace
+
+```bash
+tb spawn agent_1
+tb spawn agent_2
+```
+
+Each workspace gets a directory under `workspaces/` and a **shared Python virtualenv** (same Python version and repo-root `requirements.txt` share one env). The env is created under `env_store/<hash>/` and linked as `workspaces/<name>/venv`.
+
+### Installing or changing packages
+
+Use the workspace’s venv so all agents sharing that env see the same packages:
+
+```bash
+# From project root — no need to activate
+workspaces/agent_1/venv/bin/pip install requests
+workspaces/agent_1/venv/bin/pip install -r requirements.txt
+workspaces/agent_1/venv/bin/pip uninstall -y some-package
+```
+
+Or activate first (Linux/macOS):
+
+```bash
+source workspaces/agent_1/venv/bin/activate
+pip install requests
+deactivate
+```
+
+If you change `requirements.txt` at the repo root, existing workspaces keep their current env until you delete and re-spawn them; new workspaces will use a new env hash.
+
+### Listing and pruning environments
+
+```bash
+tb env list      # List registered shared envs
+tb env prune     # Remove missing envs from the registry
+```
+
+---
+
+## Recording a Run
+
+Flow: **prompt.json → AI writes intent.json → apply only those changes → then run the rest.**
+
+1. **`tb spawn`** creates a default **`prompt.json`** in the workspace with a **`_teabag`** section so the AI always knows to produce **`intent.json`**.
+2. **Human** fills the **`prompt`** field in `prompt.json` (the task for the model).
+3. **AI** reads `prompt.json`, writes **`intent.json`** (with at least `intent.goal`; optionally `intent.files_to_modify`, `parent_experiment`). The `_teabag` section ensures the AI generates intent.json before editing other files.
+4. Then run **`tb run agent_1`** to record the run (and optionally run tests/metrics).
+
+Default **`prompt.json`** (created by `tb spawn`; human fills `"prompt"`):
+
+```json
+{
+  "_teabag": {
+    "version": 1,
+    "instructions": "Read this prompt and write intent.json in this workspace. intent.json must have: \"intent\" object with \"goal\" (string, required), and optionally \"files_to_modify\" (array of file paths), \"parent_experiment\" (string). Do not modify any other files until intent.json is written.",
+    "required_intent_fields": ["intent.goal"],
+    "optional_intent_fields": ["intent.files_to_modify", "parent_experiment", "prompt"]
+  },
+  "prompt": "Optimize the database queries in db/query.py to reduce the N+1 problem."
+}
+```
+
+Example **`intent.json`** (AI-written from that prompt):
+
+```json
+{
+  "parent_experiment": "exp_001",
+  "prompt": "optimize database queries",
+  "intent": {
+    "files_to_modify": ["db/query.py"],
+    "goal": "reduce N+1 query problem"
+  }
+}
+```
+
+You can use **`prompt.md`** instead of `prompt.json` (no default template); the AI must still write `intent.json`.
+
+```bash
+tb run agent_1
+```
+
+This creates a new run (e.g. `.ai_history/run_002/`) with copies of the prompt file, `intent.json`, `diff.patch`, `metadata.json`, and `environment.json` (and optionally `tests.json` / `metrics.json` from `teabag.json`). **intent.json and all run artifacts are made read-only** so the record cannot be modified after creation.
+
+---
+
+## Inspecting and Comparing Runs
+
+List all runs:
+
+```bash
+tb list-runs
+```
+
+Show full details for one run (metadata, intent, environment, tests/metrics summary):
+
+```bash
+tb runs show run_002
+```
+
+Compare two runs (diff size, test exit code, metrics):
+
+```bash
+tb runs compare run_001 run_002
+```
+
+Rank runs by test result, time, or diff size:
+
+```bash
+tb runs rank                  # Prefer passing tests, then newest
+tb runs rank --by time        # Newest first
+tb runs rank --by diff        # Smallest diff first
+```
+
+---
+
+## Applying Changes to the Main Repo
+
+### Accept a single run
+
+Apply a run’s diff to the repo and mark its experiment as accepted:
+
+```bash
+tb runs accept run_002
+```
+
+Check first without modifying files:
+
+```bash
+tb runs accept run_002 --dry-run
+```
+
+Requires the `patch` command (e.g. `brew install patch` on macOS).
+
+### Merge the best runs automatically
+
+Apply the top runs (ranked by tests, then time) that do not touch the same files as already-accepted runs:
+
+```bash
+tb merge best                 # Apply the single best non-conflicting run
+tb merge best --limit 3       # Apply up to 3
+tb merge best --limit 2 --dry-run   # Only print what would be applied
+```
+
+### See a merge plan for one run
+
+```bash
+tb merge plan run_002
+```
+
+Shows the run’s goal, touched files, test result, and whether it conflicts (overlapping files) with any already-accepted run.
+
+---
+
+## Automation: Tests and Metrics
+
+Put a **`teabag.json`** file in the **repository root** to run tests and an optional metrics script every time you run `tb run <agent_name>`.
+
+Example:
+
+```json
+{
+  "test_command": "pytest -q",
+  "test_timeout": 120,
+  "metrics_script": "scripts/collect_metrics.sh"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `test_command` | Shell command run from the **workspace** directory. Exit code and output are stored in `tests.json`. |
+| `test_timeout` | Timeout in seconds (default: 300). |
+| `metrics_script` | Path (relative to repo root) to a script run from the workspace. Output is stored in `metrics.json`. |
+
+If `test_command` is omitted, no tests run and `tests.json` is not created. If `metrics_script` is omitted or the file is missing, no metrics run. `environment.json` is always written for every run.
+
+---
+
+## Snapshots and Multi-Agent Workflows
+
+### Workspace snapshot
+
+Save a copy of a workspace (excluding venv) for later use or as a template:
+
+```bash
+tb workspace snapshot agent_1
+```
+
+This creates `.teabag/snapshots/agent_1_<ISO8601>/`.
+
+### Spawn many agents at once
+
+```bash
+# Create 5 workspaces: agent_1 .. agent_5
+tb agents spawn 5
+
+# Create 5 workspaces from a snapshot (use the snapshot directory name)
+tb agents spawn 5 --template agent_1_20250116T120000Z
+```
+
+### Task: create a task and spawn agents
+
+Create a task and spawn N workspaces in one step:
+
+```bash
+tb task run "optimize database layer" --agents 3
+```
+
+This creates a task, spawns `agent_1`, `agent_2`, `agent_3`, and associates them with the task. Then run your AI in each workspace and record with `tb run agent_1`, etc.
+
+List tasks:
+
+```bash
+tb task list
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|--------|-------------|
+| `tb init` | Initialize teaBag in the current repo. |
+| `tb spawn <agent_name>` | Create a workspace and link shared venv. |
+| `tb run <agent_name>` | Record a run (prompt.json with _teabag + human prompt; AI must have written intent.json). |
+| `tb list-runs` | List all recorded runs. |
+| `tb runs show <run_id>` | Show full run details. |
+| `tb runs compare <run_a> <run_b>` | Compare two runs. |
+| `tb runs rank [--by tests\|time\|diff]` | Rank runs. |
+| `tb runs accept <run_id> [--dry-run]` | Apply run’s diff to the repo. |
+| `tb merge best [--limit K] [--dry-run]` | Apply best K non-conflicting runs. |
+| `tb merge plan <run_id>` | Show merge plan and conflicts. |
+| `tb workspace snapshot <agent_name>` | Snapshot workspace to .teabag/snapshots/. |
+| `tb agents spawn <n> [--template NAME]` | Spawn n workspaces (agent_1 .. agent_n). |
+| `tb task run "desc" [--agents N] [--template NAME]` | Create task and spawn N agents. |
+| `tb task list` | List tasks. |
+| `tb delete-workspace <agent_name>` | Remove a workspace. |
+| `tb env list` | List shared environments. |
+| `tb env prune` | Prune missing envs from registry. |
+
+You can pass `--repo-root /path/to/repo` to any command (except `init`) to run from another directory.
+
+---
+
+## Examples
+
+### Example 1: Single agent, then accept
+
+```bash
+tb init
+tb spawn agent_1
+# ... You fill prompt.json, AI writes intent.json and edits workspaces/agent_1/ ...
+tb run agent_1
+tb list-runs
+tb runs show run_001
+tb runs accept run_001 --dry-run
+tb runs accept run_001
+tb delete-workspace agent_1
+```
+
+### Example 2: Multiple runs, compare and pick one
+
+```bash
+tb init
+tb spawn agent_1
+# First experiment
+# Human fills "prompt" in workspaces/agent_1/prompt.json; AI writes intent.json (here, manual for demo)
+echo '{"intent":{"goal":"add caching"}}' > workspaces/agent_1/intent.json
+tb run agent_1
+# Second experiment (new prompt in prompt.json, AI writes new intent.json)
+echo '{"intent":{"goal":"use Redis"}}' > workspaces/agent_1/intent.json
+tb run agent_1
+
+tb runs compare run_001 run_002
+tb runs rank
+tb merge plan run_002
+tb runs accept run_002
+tb delete-workspace agent_1
+```
+
+### Example 3: Parallel agents and merge best
+
+```bash
+tb init
+tb task run "refactor auth module" --agents 3
+# ... run AI in workspaces/agent_1, agent_2, agent_3; add intent + prompt in each ...
+tb run agent_1
+tb run agent_2
+tb run agent_3
+
+tb runs rank
+tb merge best --limit 1 --dry-run
+tb merge best --limit 1
+tb delete-workspace agent_1
+tb delete-workspace agent_2
+tb delete-workspace agent_3
+```
+
+### Example 4: Snapshot as template for more agents
+
+```bash
+tb init
+tb spawn agent_1
+# ... set up workspace with baseline code, intent, prompt ...
+tb workspace snapshot agent_1
+# Snapshot created: .teabag/snapshots/agent_1_20250116T120000Z
+
+tb agents spawn 4 --template agent_1_20250116T120000Z
+# Now agent_1, agent_2, agent_3, agent_4 all start from that snapshot
+```
+
+---
+
+## Troubleshooting
+
+- **"intent.json not found"**  
+  AI must read `prompt.json` (or `prompt.md`) and write `intent.json` with `intent.goal` before `tb run`.
+- **"Neither prompt.json nor prompt.md found"**  
+  Run `tb spawn` to get a default `prompt.json`, or add `prompt.json` / `prompt.md` and fill the human prompt.
+
+- **"Workspace for agent X does not exist"**  
+  Run `tb spawn <agent_name>` first.
+
+- **"patch failed" / "patch: command not found"**  
+  Install `patch` (e.g. `brew install patch`). Required for `tb runs accept` and `tb merge best`.
+
+- **Symlinks not supported (e.g. some Windows setups)**  
+  teaBag writes `workspaces/<agent_name>/ENV_PATH` with the absolute path to the env. Use that path to call pip or activate.
+
+- **merge best applies nothing**  
+  All runs may already be accepted, or every candidate conflicts (touches the same files as an accepted run). Use `tb runs rank` and `tb merge plan <run_id>` to inspect.
+
+- **Template snapshot not found**  
+  Use the snapshot directory name under `.teabag/snapshots/` (e.g. `agent_1_20250116T120000Z`), not a full path.
+
+- **Diff is empty**  
+  Diff uses `git diff` when the repo has a `.git` directory. For non-git projects, runs are still recorded but `diff.patch` may be a placeholder.