brainfile 0.1.0__tar.gz

brainfile-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

brainfile-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

brainfile-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Brainfile Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brainfile-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: brainfile
+Version: 0.1.0
+Summary: Python library for the Brainfile task management protocol
+Project-URL: Homepage, https://brainfile.md
+Project-URL: Repository, https://github.com/brainfile/py
+Project-URL: Issues, https://github.com/brainfile/py/issues
+Project-URL: Documentation, https://github.com/brainfile/protocol
+Author: Brainfile Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,brainfile,kanban,markdown,mcp,task-management,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: watchdog>=3.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/brainfile/core/main/logo.png" alt="Brainfile Logo" width="128" height="128">
+</p>
+
+# brainfile
+
+**The Python engine behind [Brainfile](https://brainfile.md).**
+
+This library provides the core logic for managing Brainfile v2 projects: reading/writing task files, managing contracts, validating boards, and querying task state. It is the Python equivalent of [@brainfile/core](https://github.com/brainfile/core) with full API parity.
+
+Used by [Cecli](https://github.com/dwash96/cecli) and other tools that need programmatic access to Brainfile workspaces.
+
+## Installation
+
+```bash
+pip install brainfile
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add brainfile
+```
+
+## v2 Architecture
+
+Brainfile v2 uses a directory-based structure. Each task is its own markdown file.
+
+```
+.brainfile/
+├── brainfile.md          # Board config (columns, types, rules)
+├── board/                # Active tasks
+│   ├── task-1.md
+│   └── task-2.md
+└── logs/                 # Completed tasks (history)
+    └── task-0.md
+```
+
+## Quick Start
+
+```python
+from brainfile import ensureV2Dirs, addTaskFile, readTasksDir, completeTaskFile
+
+# Initialize workspace
+dirs = ensureV2Dirs(".brainfile/brainfile.md")
+
+# Add a task
+result = addTaskFile(
+    dirs.boardDir,
+    {"title": "Implement auth", "column": "in-progress", "priority": "high"},
+    body="## Description\nAdd JWT authentication to the API.\n",
+)
+print(result["task"].id)  # "task-1"
+
+# List all active tasks
+for doc in readTasksDir(dirs.boardDir):
+    t = doc.task
+    print(f"{t.id}: {t.title} [{t.column}]")
+
+# Complete a task (moves to logs/)
+completeTaskFile(result["filePath"], dirs.logsDir)
+```
+
+## Task File Operations
+
+Read and write individual task files.
+
+```python
+from brainfile import readTaskFile, writeTaskFile, findV2Task, getV2Dirs
+
+# Read a single task
+doc = readTaskFile(".brainfile/board/task-1.md")
+print(doc.task.title)
+print(doc.body)  # Markdown content below frontmatter
+
+# Find a task across board and logs
+dirs = getV2Dirs(".brainfile/brainfile.md")
+result = findV2Task(dirs, "task-1", searchLogs=True)
+if result:
+    print(result["doc"].task.title, "in", "logs" if result["isLog"] else "board")
+```
+
+## Contracts
+
+Tasks can carry formal contracts for AI agent coordination: deliverables, validation commands, constraints, and feedback for rework.
+
+```python
+from brainfile import readTaskFile, writeTaskFile, Contract, Deliverable
+
+doc = readTaskFile(".brainfile/board/task-1.md")
+task = doc.task
+
+# Attach a contract
+task.contract = Contract(
+    status="ready",
+    deliverables=[
+        Deliverable(path="src/auth.py", description="JWT auth module"),
+        Deliverable(path="tests/test_auth.py", description="Unit tests"),
+    ],
+    validation={"commands": ["pytest tests/test_auth.py"]},
+    constraints=["Use PyJWT library", "Token expiry must be configurable"],
+)
+
+writeTaskFile(".brainfile/board/task-1.md", task, doc.body)
+```
+
+### Contract Lifecycle
+
+```
+ready  →  in_progress  →  delivered  →  done
+                │                         │
+                └─────────→  failed  ←────┘
+                             (add feedback, reset to ready)
+```
+
+```python
+from brainfile import setTaskContractStatus
+
+# Agent picks up work
+setTaskContractStatus(board, "task-1", "in_progress")
+
+# Agent delivers
+setTaskContractStatus(board, "task-1", "delivered")
+
+# PM validates
+setTaskContractStatus(board, "task-1", "done")
+```
+
+## Board Operations (V1)
+
+Immutable operations on in-memory board objects. Useful for single-file workflows or building custom tools.
+
+```python
+from brainfile import Brainfile, add_task, move_task, patch_task, TaskInput, TaskPatch
+
+# Parse a brainfile
+result = Brainfile.parse(markdown_content)
+board = result.board
+
+# Add a task
+result = add_task(board, "todo", TaskInput(title="New task", priority="high"))
+board = result.board
+
+# Move between columns
+result = move_task(board, "task-1", "todo", "in-progress")
+
+# Patch fields
+result = patch_task(board, "task-1", TaskPatch(tags=["urgent"], assignee="codex"))
+
+# Serialize back
+output = Brainfile.serialize(board)
+```
+
+## Queries
+
+```python
+from brainfile import (
+    find_task_by_id,
+    get_all_tasks,
+    get_tasks_by_tag,
+    get_tasks_by_assignee,
+    search_tasks,
+)
+
+task_info = find_task_by_id(board, "task-1")
+urgent = get_tasks_by_tag(board, "urgent")
+results = search_tasks(board, "auth")
+```
+
+## Validation and Linting
+
+```python
+from brainfile import BrainfileValidator, BrainfileLinter, LintOptions
+
+# Validate board structure
+result = BrainfileValidator.validate(board)
+for error in result.errors:
+    print(f"{error.path}: {error.message}")
+
+# Lint with auto-fix
+result = BrainfileLinter.lint(content, LintOptions(auto_fix=True))
+```
+
+## File Discovery
+
+```python
+from brainfile import discover, find_nearest_brainfile, isV2
+
+# Find brainfiles in a project
+result = discover("/path/to/project")
+for f in result.files:
+    print(f"{f.name}: {f.item_count} tasks")
+
+# Walk up to find nearest brainfile
+path = find_nearest_brainfile()
+
+# Check if a workspace is v2
+if isV2(".brainfile/brainfile.md"):
+    print("V2 workspace detected")
+```
+
+## Ecosystem
+
+| Package | Description |
+|---------|-------------|
+| [brainfile (Python)](https://github.com/brainfile/py) | This library |
+| [@brainfile/core](https://github.com/brainfile/core) | TypeScript core library |
+| [@brainfile/cli](https://github.com/brainfile/cli) | CLI with TUI and MCP server |
+| [Protocol](https://github.com/brainfile/protocol) | Specification and JSON Schema |
+
+## Development
+
+```bash
+git clone https://github.com/brainfile/py.git
+cd py
+uv sync --dev
+uv run pytest
+```
+
+## License
+
+MIT

brainfile-0.1.0/README.md

@@ -0,0 +1,222 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/brainfile/core/main/logo.png" alt="Brainfile Logo" width="128" height="128">
+</p>
+
+# brainfile
+
+**The Python engine behind [Brainfile](https://brainfile.md).**
+
+This library provides the core logic for managing Brainfile v2 projects: reading/writing task files, managing contracts, validating boards, and querying task state. It is the Python equivalent of [@brainfile/core](https://github.com/brainfile/core) with full API parity.
+
+Used by [Cecli](https://github.com/dwash96/cecli) and other tools that need programmatic access to Brainfile workspaces.
+
+## Installation
+
+```bash
+pip install brainfile
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add brainfile
+```
+
+## v2 Architecture
+
+Brainfile v2 uses a directory-based structure. Each task is its own markdown file.
+
+```
+.brainfile/
+├── brainfile.md          # Board config (columns, types, rules)
+├── board/                # Active tasks
+│   ├── task-1.md
+│   └── task-2.md
+└── logs/                 # Completed tasks (history)
+    └── task-0.md
+```
+
+## Quick Start
+
+```python
+from brainfile import ensureV2Dirs, addTaskFile, readTasksDir, completeTaskFile
+
+# Initialize workspace
+dirs = ensureV2Dirs(".brainfile/brainfile.md")
+
+# Add a task
+result = addTaskFile(
+    dirs.boardDir,
+    {"title": "Implement auth", "column": "in-progress", "priority": "high"},
+    body="## Description\nAdd JWT authentication to the API.\n",
+)
+print(result["task"].id)  # "task-1"
+
+# List all active tasks
+for doc in readTasksDir(dirs.boardDir):
+    t = doc.task
+    print(f"{t.id}: {t.title} [{t.column}]")
+
+# Complete a task (moves to logs/)
+completeTaskFile(result["filePath"], dirs.logsDir)
+```
+
+## Task File Operations
+
+Read and write individual task files.
+
+```python
+from brainfile import readTaskFile, writeTaskFile, findV2Task, getV2Dirs
+
+# Read a single task
+doc = readTaskFile(".brainfile/board/task-1.md")
+print(doc.task.title)
+print(doc.body)  # Markdown content below frontmatter
+
+# Find a task across board and logs
+dirs = getV2Dirs(".brainfile/brainfile.md")
+result = findV2Task(dirs, "task-1", searchLogs=True)
+if result:
+    print(result["doc"].task.title, "in", "logs" if result["isLog"] else "board")
+```
+
+## Contracts
+
+Tasks can carry formal contracts for AI agent coordination: deliverables, validation commands, constraints, and feedback for rework.
+
+```python
+from brainfile import readTaskFile, writeTaskFile, Contract, Deliverable
+
+doc = readTaskFile(".brainfile/board/task-1.md")
+task = doc.task
+
+# Attach a contract
+task.contract = Contract(
+    status="ready",
+    deliverables=[
+        Deliverable(path="src/auth.py", description="JWT auth module"),
+        Deliverable(path="tests/test_auth.py", description="Unit tests"),
+    ],
+    validation={"commands": ["pytest tests/test_auth.py"]},
+    constraints=["Use PyJWT library", "Token expiry must be configurable"],
+)
+
+writeTaskFile(".brainfile/board/task-1.md", task, doc.body)
+```
+
+### Contract Lifecycle
+
+```
+ready  →  in_progress  →  delivered  →  done
+                │                         │
+                └─────────→  failed  ←────┘
+                             (add feedback, reset to ready)
+```
+
+```python
+from brainfile import setTaskContractStatus
+
+# Agent picks up work
+setTaskContractStatus(board, "task-1", "in_progress")
+
+# Agent delivers
+setTaskContractStatus(board, "task-1", "delivered")
+
+# PM validates
+setTaskContractStatus(board, "task-1", "done")
+```
+
+## Board Operations (V1)
+
+Immutable operations on in-memory board objects. Useful for single-file workflows or building custom tools.
+
+```python
+from brainfile import Brainfile, add_task, move_task, patch_task, TaskInput, TaskPatch
+
+# Parse a brainfile
+result = Brainfile.parse(markdown_content)
+board = result.board
+
+# Add a task
+result = add_task(board, "todo", TaskInput(title="New task", priority="high"))
+board = result.board
+
+# Move between columns
+result = move_task(board, "task-1", "todo", "in-progress")
+
+# Patch fields
+result = patch_task(board, "task-1", TaskPatch(tags=["urgent"], assignee="codex"))
+
+# Serialize back
+output = Brainfile.serialize(board)
+```
+
+## Queries
+
+```python
+from brainfile import (
+    find_task_by_id,
+    get_all_tasks,
+    get_tasks_by_tag,
+    get_tasks_by_assignee,
+    search_tasks,
+)
+
+task_info = find_task_by_id(board, "task-1")
+urgent = get_tasks_by_tag(board, "urgent")
+results = search_tasks(board, "auth")
+```
+
+## Validation and Linting
+
+```python
+from brainfile import BrainfileValidator, BrainfileLinter, LintOptions
+
+# Validate board structure
+result = BrainfileValidator.validate(board)
+for error in result.errors:
+    print(f"{error.path}: {error.message}")
+
+# Lint with auto-fix
+result = BrainfileLinter.lint(content, LintOptions(auto_fix=True))
+```
+
+## File Discovery
+
+```python
+from brainfile import discover, find_nearest_brainfile, isV2
+
+# Find brainfiles in a project
+result = discover("/path/to/project")
+for f in result.files:
+    print(f"{f.name}: {f.item_count} tasks")
+
+# Walk up to find nearest brainfile
+path = find_nearest_brainfile()
+
+# Check if a workspace is v2
+if isV2(".brainfile/brainfile.md"):
+    print("V2 workspace detected")
+```
+
+## Ecosystem
+
+| Package | Description |
+|---------|-------------|
+| [brainfile (Python)](https://github.com/brainfile/py) | This library |
+| [@brainfile/core](https://github.com/brainfile/core) | TypeScript core library |
+| [@brainfile/cli](https://github.com/brainfile/cli) | CLI with TUI and MCP server |
+| [Protocol](https://github.com/brainfile/protocol) | Specification and JSON Schema |
+
+## Development
+
+```bash
+git clone https://github.com/brainfile/py.git
+cd py
+uv sync --dev
+uv run pytest
+```
+
+## License
+
+MIT