mfbt-cli 0.1.0__tar.gz

mfbt_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Create venv and install dependencies
+        run: |
+          uv venv
+          uv pip install -e . -r requirements-dev.txt
+
+      - name: Lint with ruff
+        run: uv run ruff check src/ tests/
+
+      - name: Type check with mypy
+        run: uv run mypy src/mfbt/
+
+      - name: Run tests with coverage
+        run: >
+          uv run pytest tests/
+          --cov=mfbt
+          --cov-report=term-missing
+          --cov-fail-under=75
+          -q
+
+  installation-test:
+    runs-on: ubuntu-latest
+    needs: quality
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Create venv and install dev dependencies
+        run: |
+          uv venv
+          uv pip install -e . -r requirements-dev.txt
+
+      - name: Run installation tests
+        run: uv run pytest tests/integration/test_installation.py -v
+
+      - name: Upload test logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: installation-test-logs-py${{ matrix.python-version }}
+          path: |
+            tests/integration/test_installation.py
+          retention-days: 14

mfbt_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,100 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution packages
+    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 sdist and wheel
+        run: python -m build
+
+      - name: Verify distributions
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test-installation:
+    name: Test installation from wheel
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install from wheel
+        run: pip install dist/*.whl
+
+      - name: Verify entry point
+        run: mfbt --version
+
+      - name: Verify help
+        run: mfbt --help
+
+      - name: Verify module import
+        run: python -c "import mfbt; print('ok')"
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: [build, test-installation]
+    runs-on: ubuntu-latest
+    if: github.event.release.prerelease
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, test-installation]
+    runs-on: ubuntu-latest
+    if: "!github.event.release.prerelease"
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mfbt_cli-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# mfbt config
+.mfbt/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build/dist
+dist/
+build/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+
+# PyPI config (tokens)
+.pypirc
+
+# OS
+.DS_Store

mfbt_cli-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: "24.4.2"
+    hooks:
+      - id: black
+        language_version: python3
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.4.4"
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: "v1.10.0"
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: ["--config-file=pyproject.toml"]

mfbt_cli-0.1.0/.pypirc.template

@@ -0,0 +1,20 @@
+# Copy this file to ~/.pypirc (or ./.pypirc) and fill in your API tokens.
+# NEVER commit real tokens to version control.
+#
+# Generate tokens at:
+#   - TestPyPI: https://test.pypi.org/manage/account/token/
+#   - PyPI:     https://pypi.org/manage/account/token/
+
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-XXXX
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-XXXX

mfbt_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md - mfbt CLI
+
+## Project Overview
+
+**mfbt CLI** is a Python-based CLI tool for the mfbt platform, targeting publication to PyPI. It provides both an interactive TUI mode (K9S-style) and traditional subcommands for managing mfbt projects.
+
+- **Language:** Python 3.10+ (uses modern features: pattern matching, improved type hints)
+- **Backend:** Integrates with mfbt REST API (`{BASE_URL}/api/v1/`)
+- **Auth:** OAuth 2.1 with PKCE (1hr access tokens, 30-day refresh tokens), plus API key management (`mfbtsk-{uuid}`, passed as `Authorization: Bearer {key}`)
+- **Config:** `.mfbt` directory stores auth tokens and project configuration
+
+## API Specification
+
+The file `openapi.json` in the project root contains the full OpenAPI spec for the mfbt backend. **Do NOT read this file in full** — it is very large. Instead, use Grep or search tools to find specific endpoints, schemas, or parameters as needed.
+
+## Architecture
+
+### Core Systems
+
+1. **Authentication & Configuration** — Browser-based OAuth flow, token refresh/session management, API key support, project selection post-auth
+2. **Interactive TUI Mode** — Launched when CLI runs without subcommands; K9S-style keyboard-driven navigation with real-time status updates
+3. **Subcommands** — `status`, `next`, `modules`, `features`, plus commands for brainstorming phases, implementations, and jobs. Consistent output formatting (table, JSON, etc.)
+4. **API Integration Layer** — REST client for all mfbt endpoints, paginated responses (`{items, total, page, page_size, total_pages}`), error handling (404 for unauthorized, 402 for token limits), job polling for async operations, WebSocket support for real-time job status
+5. **API Key Management** — CRUD via `/api/v1/users/me/api-keys`
+
+### Key API Endpoints
+
+- Projects CRUD
+- Brainstorming phases
+- Modules, features, and implementations
+- Job monitoring: `GET /api/v1/jobs/{job_id}`
+- Thread comments
+- MCP config retrieval: `GET /api/v1/projects/{id}/mcp-config`
+- API key management: `/api/v1/users/me/api-keys`
+
+### Constraints
+
+- Must work with existing mfbt FastAPI backend
+- Support both UUIDs and short URL identifiers
+- Handle ISO 8601 UTC timestamps
+- Graceful degradation when token limits reached (HTTP 402)
+
+## MFBT MCP Server (Virtual Filesystem)
+
+This project uses the **mfbt MCP server**, which exposes a virtual filesystem (VFS) for navigating mfbt project data. **Always call `readMeFirst`** at the start of a session to get the full VFS guide, available tools, and recommended workflow.
+
+### Key MCP Concepts
+
+- The VFS exposes project phases, modules, features, and implementations as a navigable filesystem
+- Use UNIX-like commands: `ls`, `cat`, `tree`, `find`, `grep`, `head`, `tail`
+- Smart metadata on directories guides what to work on next (progress %, next feature, completion status)
+- Two feature sources: `system-generated/` (AI-created from brainstorming) and `user-defined/` (manually created or imported)
+
+### MCP VFS Structure
+
+```
+/
+├── phases/
+│   ├── system-generated/{phase}/
+│   │   ├── phase-spec/          # full.md, summary.md, by-section/
+│   │   ├── phase-prompt-plan/   # full.md, by-section/
+│   │   └── features/{module}/{feature}/
+│   │       ├── implementations/{impl}/
+│   │       │   ├── spec.md          # WHAT to build
+│   │       │   ├── prompt_plan.md   # HOW to build
+│   │       │   └── notes.md         # Writable learnings
+│   │       └── conversations/conversations.md
+│   └── user-defined/features/{module}/{feature}/
+│       └── (same structure as above)
+├── project-info/team-info.json
+├── system-info/users/available-users-list.csv
+└── for-coding-agents/
+    ├── agents.md              # Grounding context (read at session start)
+    └── mfbt-usage-guide/      # Workflow guides
+```
+
+### MCP Recommended Workflow
+
+1. `cat /for-coding-agents/agents.md --branch_name='your-branch'` — grounding context
+2. `ls /` → `ls /phases/` → drill into phases, modules, features
+3. Read `spec.md` (what to build) and `prompt_plan.md` (how to build)
+4. `setMetadataValueForKey .../features/{module}/{feature}/ in_progress true` — mark as started
+5. Implement the feature
+6. `write .../implementations/{impl}/notes.md '<learnings>'` — document what you learned
+7. `setMetadataValueForKey .../implementations/{impl}/ is_complete true` — mark done (auto-syncs feature status)
+
+### MCP Tips
+
+- Include `coding_agent_name: "claude_code"` and `branch_name` in tool calls
+- Use `summary.md` for quick spec overviews; `by-section/` for large specs
+- Focus on `must_have` features first, then `important`, then `optional`
+- `notes.md` auto-feeds into `agents.md` grounding — document architectural decisions and gotchas
+- Use `grep` to search across specs and prompt plans
+- For team communication (posting comments), see `/for-coding-agents/mfbt-usage-guide/`
+- To update status: `in_progress` on features when starting, `is_complete` on implementations when done
+
+## Development
+
+- **Venv:** `.venv/bin/python`, `.venv/bin/pytest`
+- **Run tests:** `.venv/bin/pytest tests/unit/ralph/ -v`
+- **API response formats:** List endpoints (`/features`, `/implementations`) return **paginated** `{"items": [...], "total": N, ...}` — always extract via `body["items"]`. Some endpoints (`/brainstorming-phases`) return plain lists. See `src/mfbt/tui/data_provider.py` for the canonical parsing pattern.
+- **Ralph subcommand:** `src/mfbt/commands/ralph/` — orchestrator, display (console), tui_display (Textual), agent runner, progress (API), prompt builder, types
+- **Ralph TUI:** Standalone Textual app (`tui_app.py`), separate from main mfbt TUI. Uses `RalphTUIDisplay` adapter (same 8-method interface as `RalphDisplay`) with `call_from_thread()` to marshal UI updates from the orchestrator's worker thread.
+- **Display duck typing:** `RalphOrchestrator.display` is typed as `Any` — both `RalphDisplay` and `RalphTUIDisplay` are structurally compatible (same 8 methods).

mfbt_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zipstack
+
+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.

mfbt_cli-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: mfbt-cli
+Version: 0.1.0
+Summary: CLI tool for the mfbt platform — interactive TUI and subcommands for managing mfbt projects
+Project-URL: Homepage, https://github.com/Zipstack/mfbt-cli
+Project-URL: Repository, https://github.com/Zipstack/mfbt-cli
+Project-URL: Issues, https://github.com/Zipstack/mfbt-cli/issues
+Author-email: Zipstack <engineering@zipstack.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: platformdirs>=3.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.86.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+# mfbt CLI
+
+Command-line tool for the [mfbt](https://mfbt.ai) platform. Provides both an interactive TUI mode and traditional subcommands for managing mfbt projects.
+
+## Features
+
+- **Interactive TUI** -- K9S-style keyboard-driven interface for navigating projects, phases, modules, and features
+- **Subcommands** -- Traditional CLI commands for scripting and automation (`auth`, `projects`, `ralph`, and more)
+- **OAuth 2.1 Authentication** -- Secure browser-based login with PKCE and API key support
+- **Real-time Updates** -- WebSocket-powered job monitoring and status tracking
+- **Agent Orchestration** -- Auto-invoke coding agents to implement pending features with `mfbt ralph`
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install mfbt-cli
+```
+
+## Quick Start
+
+```bash
+# Authenticate with the mfbt platform
+mfbt auth login
+
+# List your projects
+mfbt projects list
+
+# Launch the interactive TUI
+mfbt
+
+# Show version
+mfbt --version
+```
+
+## Usage
+
+```bash
+# Run with verbose output
+mfbt -v
+mfbt -vv    # debug
+mfbt -vvv   # trace
+
+# Authentication commands
+mfbt auth login
+mfbt auth status
+mfbt auth logout
+
+# Project management
+mfbt projects list
+mfbt projects show
+mfbt projects switch
+
+# Auto-invoke coding agents
+mfbt ralph
+```
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Zipstack/mfbt-cli.git
+cd mfbt-cli
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Unix
+# .venv\Scripts\activate   # Windows
+
+# Install in editable mode with dev dependencies
+pip install -e .
+pip install -r requirements-dev.txt
+
+# Run tests
+pytest tests/ -v
+
+# Code quality
+black --check src/ tests/
+ruff check src/ tests/
+mypy src/
+```
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.

mfbt_cli-0.1.0/README.md

@@ -0,0 +1,88 @@
+# mfbt CLI
+
+Command-line tool for the [mfbt](https://mfbt.ai) platform. Provides both an interactive TUI mode and traditional subcommands for managing mfbt projects.
+
+## Features
+
+- **Interactive TUI** -- K9S-style keyboard-driven interface for navigating projects, phases, modules, and features
+- **Subcommands** -- Traditional CLI commands for scripting and automation (`auth`, `projects`, `ralph`, and more)
+- **OAuth 2.1 Authentication** -- Secure browser-based login with PKCE and API key support
+- **Real-time Updates** -- WebSocket-powered job monitoring and status tracking
+- **Agent Orchestration** -- Auto-invoke coding agents to implement pending features with `mfbt ralph`
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install mfbt-cli
+```
+
+## Quick Start
+
+```bash
+# Authenticate with the mfbt platform
+mfbt auth login
+
+# List your projects
+mfbt projects list
+
+# Launch the interactive TUI
+mfbt
+
+# Show version
+mfbt --version
+```
+
+## Usage
+
+```bash
+# Run with verbose output
+mfbt -v
+mfbt -vv    # debug
+mfbt -vvv   # trace
+
+# Authentication commands
+mfbt auth login
+mfbt auth status
+mfbt auth logout
+
+# Project management
+mfbt projects list
+mfbt projects show
+mfbt projects switch
+
+# Auto-invoke coding agents
+mfbt ralph
+```
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Zipstack/mfbt-cli.git
+cd mfbt-cli
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Unix
+# .venv\Scripts\activate   # Windows
+
+# Install in editable mode with dev dependencies
+pip install -e .
+pip install -r requirements-dev.txt
+
+# Run tests
+pytest tests/ -v
+
+# Code quality
+black --check src/ tests/
+ruff check src/ tests/
+mypy src/
+```
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.

mfbt_cli-0.1.0/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do not** open a public issue.
+2. Email security details to the project maintainers.
+3. Include steps to reproduce, impact assessment, and any suggested fixes.
+
+We will acknowledge receipt within 48 hours and aim to provide a fix within 7 days for critical issues.
+
+## Scope
+
+- Authentication token storage and handling
+- API key management
+- File permission management for `.mfbt/` directory
+- Any data transmission to/from the mfbt API