magic-beans 0.1.0__tar.gz

magic_beans-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: magic-beans
+Version: 0.1.0
+Summary: Graph-based issue tracker for AI agent coordination
+Author: Henrique Bastos
+Author-email: Henrique Bastos <henrique@bastos.net>
+License-Expression: MIT
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.9
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# 🫘 Beans
+
+**Graph-based issue tracker for AI agent coordination.**
+
+Coding with AI makes developers absurdly productive. Coffee keeps them going.
+Beans keep the whole loop fed. ☕
+
+Beans is a lightweight, embedded issue tracker designed for AI agents to coordinate work
+across tasks. It models issues as nodes in a dependency graph, backed by SQLite, with a
+CLI that both humans and agents can use.
+
+```
+$ beans create "Fix auth middleware"
+bean-a3f2dd1c  2025-06-15 10:42  Fix auth middleware
+
+$ beans list
+bean-a3f2dd1c  2025-06-15 10:42  Fix auth middleware
+bean-7e2b9f01  2025-06-15 10:43  Add rate limiting
+
+$ beans --json list
+[{"id": "bean-a3f2dd1c", "title": "Fix auth middleware", "status": "open", ...}]
+```
+
+## Why Beans exists
+
+Beans was born from analyzing [beads](https://github.com/steveyegge/beads), a
+graph-based issue tracker with a similar goal: giving AI agents a structured way to
+coordinate work. The idea is excellent. The execution, however, raised serious concerns.
+
+### The problem with beads
+
+Beads is invasive software that assumes too much about the user's intentions:
+
+- **Curl-pipe-bash installer** that silently escalates to `sudo` to install a ~200MB
+  binary system-wide
+- **Strips macOS code signatures** and applies ad-hoc signatures to bypass Gatekeeper —
+  the same technique used by actual malware
+- **Installs 5 persistent git hooks** (`pre-commit`, `post-merge`, `pre-push`,
+  `post-checkout`, `prepare-commit-msg`) that run on nearly every git operation
+- **Runs a background database daemon** (Dolt SQL server) that binds to TCP ports
+  3307/3308 — a MySQL-protocol server running on your machine
+- **Silently modifies commit messages** by appending metadata trailers without asking
+- **Auto-pushes data** to remote servers every 5 minutes
+- **Fingerprints your machine** with unique UUIDs for the repo, clone, and project
+- **Injects system prompts** into AI agent configuration files (e.g.,
+  `.claude/settings.local.json`) to force agents to use the tool
+- **Includes a "stealth mode"** that hides its presence from collaborators
+- **Ships with telemetry** that records every command and all arguments, including who
+  ran them
+
+The core data model is a 50+ field struct covering everything from agent heartbeats to
+ephemeral "wisps." It's not a simple tool — it's a complex system that assumes you want
+all of it.
+
+### What beans does differently
+
+Beans keeps the good idea — a dependency graph for AI agent coordination — and throws
+away everything else:
+
+| | Beads | Beans |
+|---|---|---|
+| **Storage** | Dolt SQL server (~200MB, background daemon, TCP ports) | SQLite (zero-config, embedded, stdlib) |
+| **Installation** | `curl \| bash` + `sudo` + signature stripping | `uv add beans` or `pip install beans` |
+| **Git hooks** | 5 persistent hooks installed silently | None |
+| **Commit modification** | Silent trailer injection | Never touches your commits |
+| **Background processes** | Persistent MySQL-protocol daemon | None |
+| **Network** | Opens TCP ports, auto-pushes every 5 min | Fully offline |
+| **Telemetry** | OTel spans with actor identity + full args | None |
+| **Stealth mode** | Yes, hides from collaborators | No — transparency is a feature |
+| **AI config injection** | Writes to `.claude/settings.local.json` | Provides recipes you copy yourself |
+| **Data model** | 50+ fields | ~10 fields + dependency edges |
+| **Agent integration** | Forced via injected prompts | Opt-in via `AGENTS.md` instructions |
+
+## Design principles
+
+**Polite software.** Beans never modifies files without asking, never installs hooks,
+never runs background processes, and never phones home. It's a CLI tool that reads and
+writes to a local SQLite file. That's it.
+
+**Embedded storage.** A single `.beans/beans.db` SQLite file with WAL mode. No servers,
+no ports, no daemons. Works offline, works in CI, works anywhere Python runs.
+
+**Graph-native.** Issues (beans) are nodes. Dependencies are typed edges. "What's ready
+to work on?" is a graph query — show me all open beans with no open blockers.
+
+**Agent-friendly.** The `--json` flag on every command makes beans machine-readable.
+Agents don't need to parse human output. The CLI is a thin wrapper around a clean Python
+API — agents can also use the library directly.
+
+**Minimal by default.** A bean has an id, title, status, and timestamps. Everything else
+is optional. No 50-field structs, no agent heartbeat tracking, no ephemeral wisps.
+
+**Journal-based sync.** Changes are recorded in an append-only JSONL journal that can be
+committed to git. The SQLite database is a materialized view that can be rebuilt from the
+journal at any time. Sync through git, not through custom protocols.
+
+## Installation
+
+```bash
+uv add beans
+```
+
+Or with pip:
+
+```bash
+pip install beans
+```
+
+## Quick start
+
+```bash
+# Create some beans
+beans create "Set up database schema"
+beans create "Build API endpoints"
+beans create "Write integration tests"
+
+# List all beans
+beans list
+
+# JSON output for agent consumption
+beans --json list
+```
+
+## Architecture
+
+```
+src/beans/
+├── models.py    # Pydantic models (pure, no I/O)
+├── store.py     # SQLite storage (I/O boundary)
+└── cli.py       # Typer CLI (thin wiring layer)
+```
+
+- **models.py** — Pure data. Bean is a Pydantic model with validation. No I/O, no side
+  effects, easy to test.
+- **store.py** — The I/O boundary. BeanStore wraps a SQLite connection with
+  create/read/update/delete operations. Accepts an injected connection for testing.
+- **cli.py** — Thin wiring. Parses args, calls store methods, formats output. No
+  business logic.
+
+## For AI agents
+
+Beans is designed to be used by AI agents as a coordination mechanism. Add this to your
+project's `AGENTS.md`:
+
+```markdown
+## Task tracking
+
+This project uses `beans` for task tracking. Use `beans --json` for all commands.
+
+- Check available work: `beans --json ready`
+- Claim a task: `beans claim <id>`
+- Mark done: `beans close <id>`
+- Create subtasks: `beans create "<title>" --parent <id>`
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Beans is built with Python 3.14, managed with [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/henriquebastos/beans.git
+cd beans
+uv sync
+uv run pytest
+uv run ruff check src/ tests/
+```
+
+Tests use real SQLite `:memory:` databases — no mocks. The test suite runs in under a
+second.

magic_beans-0.1.0/README.md

@@ -0,0 +1,173 @@
+# 🫘 Beans
+
+**Graph-based issue tracker for AI agent coordination.**
+
+Coding with AI makes developers absurdly productive. Coffee keeps them going.
+Beans keep the whole loop fed. ☕
+
+Beans is a lightweight, embedded issue tracker designed for AI agents to coordinate work
+across tasks. It models issues as nodes in a dependency graph, backed by SQLite, with a
+CLI that both humans and agents can use.
+
+```
+$ beans create "Fix auth middleware"
+bean-a3f2dd1c  2025-06-15 10:42  Fix auth middleware
+
+$ beans list
+bean-a3f2dd1c  2025-06-15 10:42  Fix auth middleware
+bean-7e2b9f01  2025-06-15 10:43  Add rate limiting
+
+$ beans --json list
+[{"id": "bean-a3f2dd1c", "title": "Fix auth middleware", "status": "open", ...}]
+```
+
+## Why Beans exists
+
+Beans was born from analyzing [beads](https://github.com/steveyegge/beads), a
+graph-based issue tracker with a similar goal: giving AI agents a structured way to
+coordinate work. The idea is excellent. The execution, however, raised serious concerns.
+
+### The problem with beads
+
+Beads is invasive software that assumes too much about the user's intentions:
+
+- **Curl-pipe-bash installer** that silently escalates to `sudo` to install a ~200MB
+  binary system-wide
+- **Strips macOS code signatures** and applies ad-hoc signatures to bypass Gatekeeper —
+  the same technique used by actual malware
+- **Installs 5 persistent git hooks** (`pre-commit`, `post-merge`, `pre-push`,
+  `post-checkout`, `prepare-commit-msg`) that run on nearly every git operation
+- **Runs a background database daemon** (Dolt SQL server) that binds to TCP ports
+  3307/3308 — a MySQL-protocol server running on your machine
+- **Silently modifies commit messages** by appending metadata trailers without asking
+- **Auto-pushes data** to remote servers every 5 minutes
+- **Fingerprints your machine** with unique UUIDs for the repo, clone, and project
+- **Injects system prompts** into AI agent configuration files (e.g.,
+  `.claude/settings.local.json`) to force agents to use the tool
+- **Includes a "stealth mode"** that hides its presence from collaborators
+- **Ships with telemetry** that records every command and all arguments, including who
+  ran them
+
+The core data model is a 50+ field struct covering everything from agent heartbeats to
+ephemeral "wisps." It's not a simple tool — it's a complex system that assumes you want
+all of it.
+
+### What beans does differently
+
+Beans keeps the good idea — a dependency graph for AI agent coordination — and throws
+away everything else:
+
+| | Beads | Beans |
+|---|---|---|
+| **Storage** | Dolt SQL server (~200MB, background daemon, TCP ports) | SQLite (zero-config, embedded, stdlib) |
+| **Installation** | `curl \| bash` + `sudo` + signature stripping | `uv add beans` or `pip install beans` |
+| **Git hooks** | 5 persistent hooks installed silently | None |
+| **Commit modification** | Silent trailer injection | Never touches your commits |
+| **Background processes** | Persistent MySQL-protocol daemon | None |
+| **Network** | Opens TCP ports, auto-pushes every 5 min | Fully offline |
+| **Telemetry** | OTel spans with actor identity + full args | None |
+| **Stealth mode** | Yes, hides from collaborators | No — transparency is a feature |
+| **AI config injection** | Writes to `.claude/settings.local.json` | Provides recipes you copy yourself |
+| **Data model** | 50+ fields | ~10 fields + dependency edges |
+| **Agent integration** | Forced via injected prompts | Opt-in via `AGENTS.md` instructions |
+
+## Design principles
+
+**Polite software.** Beans never modifies files without asking, never installs hooks,
+never runs background processes, and never phones home. It's a CLI tool that reads and
+writes to a local SQLite file. That's it.
+
+**Embedded storage.** A single `.beans/beans.db` SQLite file with WAL mode. No servers,
+no ports, no daemons. Works offline, works in CI, works anywhere Python runs.
+
+**Graph-native.** Issues (beans) are nodes. Dependencies are typed edges. "What's ready
+to work on?" is a graph query — show me all open beans with no open blockers.
+
+**Agent-friendly.** The `--json` flag on every command makes beans machine-readable.
+Agents don't need to parse human output. The CLI is a thin wrapper around a clean Python
+API — agents can also use the library directly.
+
+**Minimal by default.** A bean has an id, title, status, and timestamps. Everything else
+is optional. No 50-field structs, no agent heartbeat tracking, no ephemeral wisps.
+
+**Journal-based sync.** Changes are recorded in an append-only JSONL journal that can be
+committed to git. The SQLite database is a materialized view that can be rebuilt from the
+journal at any time. Sync through git, not through custom protocols.
+
+## Installation
+
+```bash
+uv add beans
+```
+
+Or with pip:
+
+```bash
+pip install beans
+```
+
+## Quick start
+
+```bash
+# Create some beans
+beans create "Set up database schema"
+beans create "Build API endpoints"
+beans create "Write integration tests"
+
+# List all beans
+beans list
+
+# JSON output for agent consumption
+beans --json list
+```
+
+## Architecture
+
+```
+src/beans/
+├── models.py    # Pydantic models (pure, no I/O)
+├── store.py     # SQLite storage (I/O boundary)
+└── cli.py       # Typer CLI (thin wiring layer)
+```
+
+- **models.py** — Pure data. Bean is a Pydantic model with validation. No I/O, no side
+  effects, easy to test.
+- **store.py** — The I/O boundary. BeanStore wraps a SQLite connection with
+  create/read/update/delete operations. Accepts an injected connection for testing.
+- **cli.py** — Thin wiring. Parses args, calls store methods, formats output. No
+  business logic.
+
+## For AI agents
+
+Beans is designed to be used by AI agents as a coordination mechanism. Add this to your
+project's `AGENTS.md`:
+
+```markdown
+## Task tracking
+
+This project uses `beans` for task tracking. Use `beans --json` for all commands.
+
+- Check available work: `beans --json ready`
+- Claim a task: `beans claim <id>`
+- Mark done: `beans close <id>`
+- Create subtasks: `beans create "<title>" --parent <id>`
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Beans is built with Python 3.14, managed with [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/henriquebastos/beans.git
+cd beans
+uv sync
+uv run pytest
+uv run ruff check src/ tests/
+```
+
+Tests use real SQLite `:memory:` databases — no mocks. The test suite runs in under a
+second.

magic_beans-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "magic-beans"
+version = "0.1.0"
+description = "Graph-based issue tracker for AI agent coordination"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Henrique Bastos", email = "henrique@bastos.net" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "pydantic>=2.0",
+    "typer>=0.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.7,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "beans"
+
+[project.scripts]
+beans = "beans.cli:app"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=6.151.9",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.6",
+    "time-machine>=3.2.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=beans --cov-report=term-missing --no-header -q"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "RUF"]

magic_beans-0.1.0/src/beans/__init__.py

@@ -0,0 +1 @@
+

magic_beans-0.1.0/src/beans/cli.py

@@ -0,0 +1,64 @@
+# Python imports
+import json
+from datetime import datetime
+from typing import Annotated
+
+# Pip imports
+import typer
+
+# Internal imports
+from beans.models import Bean
+from beans.store import BeanStore
+
+app = typer.Typer()
+
+# Global state shared across commands
+state: dict = {}
+
+
+@app.callback()
+def main(
+    db: Annotated[str | None, typer.Option(help="Path to SQLite database")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False,
+):
+    state["db"] = db
+    state["json"] = json_output
+
+
+def local_timestamp(dt: datetime, fmt="%Y-%m-%d %H:%M") -> str:
+    return dt.astimezone().strftime(fmt)
+
+
+def format_bean(bean: Bean) -> str:
+    return f"{bean.id}  {local_timestamp(bean.created_at)}  {bean.title}"
+
+
+def get_store() -> BeanStore:
+    db_path = state.get("db") or "beans.db"  # TODO: project discovery (Phase 6.2)
+    return BeanStore.from_path(db_path)
+
+
+@app.command()
+def create(title: str):
+    """Create a new bean."""
+    bean = Bean(title=title)
+    with get_store() as store:
+        store.create_bean(bean)
+
+    if state.get("json"):
+        typer.echo(bean.model_dump_json())
+    else:
+        typer.echo(format_bean(bean))
+
+
+@app.command("list")
+def list_beans():
+    """List all beans."""
+    with get_store() as store:
+        beans = store.list_beans()
+
+    if state.get("json"):
+        typer.echo(json.dumps([b.model_dump(mode="json") for b in beans]))
+    else:
+        for bean in beans:
+            typer.echo(format_bean(bean))

magic_beans-0.1.0/src/beans/models.py

@@ -0,0 +1,29 @@
+# Python imports
+import secrets
+from datetime import UTC, datetime
+from functools import partial
+from typing import Literal
+
+# Pip imports
+from pydantic import BaseModel, Field
+
+
+ID_BYTES = 4
+
+
+def generate_id(prefix="bean-", fn=partial(secrets.token_hex, ID_BYTES)) -> str:
+    return prefix + fn()
+
+
+class Bean(BaseModel):
+    id: str = Field(default_factory=generate_id)
+    title: str
+    type: str = "task"
+    status: Literal["open", "in_progress", "closed"] = "open"
+    priority: int = Field(default=2, ge=0, le=4)
+    body: str = ""
+    parent_id: str | None = None
+    assignee: str | None = None
+    created_by: str | None = None
+    ref_id: str | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))

magic_beans-0.1.0/src/beans/store.py

@@ -0,0 +1,82 @@
+# Python imports
+import sqlite3
+
+# Internal imports
+from beans.models import Bean
+
+def columns(cursor: sqlite3.Cursor) -> list[str]:
+    return [desc[0] for desc in cursor.description]
+
+
+def row(cols: list[str], values: tuple) -> dict:
+    return dict(zip(cols, values))
+
+
+SCHEMA = """
+PRAGMA journal_mode=WAL;
+PRAGMA foreign_keys=ON;
+
+CREATE TABLE IF NOT EXISTS beans (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    type TEXT NOT NULL DEFAULT 'task',
+    status TEXT NOT NULL DEFAULT 'open',
+    priority INTEGER NOT NULL DEFAULT 2,
+    body TEXT NOT NULL DEFAULT '',
+    parent_id TEXT,
+    assignee TEXT,
+    created_by TEXT,
+    ref_id TEXT,
+    created_at TEXT NOT NULL
+);
+"""
+
+
+class BeanStore:
+    def __init__(self, conn: sqlite3.Connection):
+        self.conn = conn
+        self.init_db(conn)
+
+    @staticmethod
+    def init_db(conn: sqlite3.Connection, schema: str = SCHEMA):
+        conn.executescript(schema)
+
+    @classmethod
+    def from_path(cls, db_path: str) -> BeanStore:
+        return cls(sqlite3.connect(db_path))
+
+    def close(self):
+        self.conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def create_bean(self, bean: Bean) -> Bean:
+        self.conn.execute(
+            """INSERT INTO beans
+            (id, title, type, status, priority, body, parent_id, assignee, created_by, ref_id, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                bean.id,
+                bean.title,
+                bean.type,
+                bean.status,
+                bean.priority,
+                bean.body,
+                bean.parent_id,
+                bean.assignee,
+                bean.created_by,
+                bean.ref_id,
+                bean.created_at.isoformat(),
+            ),
+        )
+        self.conn.commit()
+        return bean
+
+    def list_beans(self) -> list[Bean]:
+        cursor = self.conn.execute("SELECT * FROM beans")
+        cols = columns(cursor)
+        return [Bean(**row(cols, values)) for values in cursor.fetchall()]