Metadata-Version: 2.4
Name: backlog-md-py
Version: 0.3.0
Summary: Standalone Python compatibility implementation of Backlog.md
Author: Robert Musser
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/rmusser01/backlog-md-py
Project-URL: Repository, https://github.com/rmusser01/backlog-md-py
Project-URL: Issues, https://github.com/rmusser01/backlog-md-py/issues
Project-URL: Changelog, https://github.com/rmusser01/backlog-md-py/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/rmusser01/backlog-md-py/tree/main/docs
Keywords: backlog.md,backlog,markdown,mcp,task-management
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: PyYAML>=6.0.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: tui
Requires-Dist: textual>=0.86.0; extra == "tui"
Dynamic: license-file

# backlog-md-py

`backlog-md-py` is a standalone Python implementation of the local-file
[Backlog.md](https://github.com/MrLesk/Backlog.md) task workflow. It keeps
Backlog.md projects as Markdown files on disk, while providing a Python CLI,
Python helper functions, SDK-free MCP server, singleton daemon for multi-agent
setups, browser board, and optional Textual TUI.

Use it when you want Backlog.md-compatible project tracking from Python tooling
or local agents without requiring a Node or Bun runtime.

## Status And Safety

This project is in beta. The audited compatibility inventory reports the
documented local-file CLI, Python helper, MCP, daemon, browser-board, and TUI
surfaces as implemented for the current baseline. Beta means the supported
contract is ready for real project integration after validation, but it is not
yet a 1.0 API freeze.

The source of truth remains the `backlog/` Markdown directory in each project.
Before live mutation in a consuming project, run copied-repository smoke tests
and review the resulting diff. See the [stability policy](docs/stability-policy.md)
for the supported contract and release gate.

Do not alias `backlog-py` to `backlog` unless the target project has made an
explicit project cutover decision.

## Quick Start

For released versions, install from PyPI:

```bash
python -m pip install backlog-md-py
```

For unreleased commits, install from GitHub:

```bash
python -m pip install "git+https://github.com/rmusser01/backlog-md-py.git"
```

Run the CLI against a Backlog.md project:

```bash
backlog-py --help
backlog-py --cwd /path/to/project task list --plain
backlog-py --cwd /path/to/project board
backlog-py --cwd /path/to/project browser --port 6420 --no-open
backlog-py compat status
```

For a safe first run, start with a scratch project:

```bash
mkdir -p /tmp/backlog-md-py-demo
backlog-py --cwd /tmp/backlog-md-py-demo init --defaults --no-git
backlog-py --cwd /tmp/backlog-md-py-demo task create "Try backlog-md-py" --plain
backlog-py --cwd /tmp/backlog-md-py-demo board
```

## Interfaces At A Glance

- CLI: `backlog-py --cwd /path/to/project ...`
- Python module entry point: `python -m backlog_py ...`
- Python helpers: import from `backlog_py.mcp` and `backlog_py.storage.project`
- MCP stdio: `backlog-py-mcp`
- Multi-agent singleton daemon: `backlog-py daemon ensure`
- Browser board: `backlog-py --cwd /path/to/project browser --port 6420`
- Optional TUI: install `backlog-md-py[tui]`, then run
  `backlog-py --cwd /path/to/project tui`

The plain CLI and MCP tools are the recommended automation surfaces. The
browser board and TUI are human-facing project navigation surfaces.

## Agent And MCP Use

`backlog-py-mcp` is included by default and provides SDK-free MCP stdio mode:

```bash
backlog-py-mcp
```

For multi-agent environments, prefer one local singleton daemon and let MCP
clients connect through it:

```bash
backlog-py daemon ensure
backlog-py daemon status --json
```

See [integration.md](docs/integration.md) for CLI, Python helper, and MCP
configuration, and [singleton-daemon.md](docs/singleton-daemon.md) for daemon
setup and rollback guidance.

## How It Fits Together

All interfaces resolve a Backlog.md project, parse Markdown-backed records, and
delegate mutations to shared core services that preserve unowned Markdown
sections and serialize writes with local filesystem locks. The daemon is a
process-reuse and coordination layer, not a separate database. The optional
SQLite index is disposable read acceleration; Markdown remains authoritative.

See [architecture.md](docs/architecture.md) for a contributor-oriented system
map.

## Documentation

Start with the [documentation index](docs/README.md). The most commonly used
references are:

- [Getting started](docs/getting-started.md)
- [Integration guide](docs/integration.md)
- [Architecture guide](docs/architecture.md)
- [Stability policy](docs/stability-policy.md)
- [Singleton daemon guide](docs/singleton-daemon.md)
- [Cutover validation checklist](docs/cutover-validation.md)
- [Browser release validation](docs/browser-release-validation.md)
- [Changelog](CHANGELOG.md)
- [Contributing guide](CONTRIBUTING.md)
- [Release checklist](docs/release-checklist.md)

## Development

Use Python 3.11, 3.12, or 3.13. Create a local virtual environment with `uv`
and install editable development dependencies:

```bash
uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
```

Run the focused agent-critical gate or the full test suite:

```bash
uv run --extra dev python -m pytest tests/test_agent_critical_matrix.py -v
uv run --extra dev python -m pytest tests -v
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow and
[architecture.md](docs/architecture.md) for the source layout.
