flanner 0.4.0__tar.gz

flanner-0.4.0/LICENSE

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

flanner-0.4.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: flanner
+Version: 0.4.0
+Summary: Plan file management for AI assistants via MCP
+Author-email: Jayson Mulwa <jayson.mulwa@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://flanner.io
+Project-URL: Repository, https://github.com/jaysonmulwa/flanner
+Project-URL: Changelog, https://github.com/jaysonmulwa/flanner/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/jaysonmulwa/flanner/issues
+Keywords: mcp,claude,codex,ai-agents,plan-files,markdown,cli,planning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+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 :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9,>=8.1
+Requires-Dist: rich<16,>=13.0
+Requires-Dist: sqlalchemy<3,>=2.0
+Requires-Dist: python-frontmatter<2,>=1.0
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: fastapi<1,>=0.104
+Requires-Dist: uvicorn<1,>=0.24
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: python-multipart<0.1,>=0.0.6
+Requires-Dist: markdown<4,>=3.5
+Requires-Dist: pygments<3,>=2.17
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: mcp<2,>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov<9,>=6.0; extra == "dev"
+Requires-Dist: httpx<1,>=0.25; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: mypy<2,>=1.13; extra == "dev"
+Requires-Dist: pip-audit<3,>=2.7; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-Markdown; extra == "dev"
+Dynamic: license-file
+
+# Flanner
+
+[![CI](https://github.com/jaysonmulwa/flanner/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jaysonmulwa/flanner/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A plan-file manager for AI coding agents, wired into Claude Code and other assistants over MCP (Model Context Protocol).
+
+AI agents write markdown constantly: design docs, migration plans, architecture notes. It piles up fast, scattered across your repo, quietly going stale, and easy to commit by accident. Flanner gives those files one home, versions them automatically as the agent revises, and keeps them out of git until you decide otherwise, with a browsable reading view and an audit trail on top.
+
+Today Flanner is local-first; the goal is cloud-hosted plans: shared workspaces for easier collaboration, effectively unlimited storage and history, and clean links to the tools teams already work in, from product trackers and chat to second brains like Notion.
+
+<div align="center">
+<img src="docs/assets/plan-view.png" alt="flanner reading view: a versioned plan file" width="840">
+</div>
+
+## Features
+
+- **MCP integration**: exposes plan-file tools to Claude Code and Codex.
+- **Automatic headers and versioning**: every plan gets YAML frontmatter, and each revision is a new version with a full history.
+- **Git protection**: plans live in `.plans/` and are kept out of commits automatically.
+- **Agent integration**: `flanner init` wires CLAUDE.md, AGENTS.md, and a guard hook so agents save plans through flanner instead of scattering raw markdown.
+- **Reading view**: a browser dashboard to read, edit, and walk the history of plans (light and dark, fully offline).
+- **Per-project config**: customize the plan directory per repository.
+
+## Quick start
+
+```bash
+cd flanner
+pip install -e .     # provides the `flanner` command
+flanner init         # database, MCP registration, and a project for this repo
+```
+
+Then ask your agent to work with plans:
+
+> "Create an architecture plan for the auth service"
+>
+> "Show me the history of the architecture plan"
+
+And open the dashboard to browse them:
+
+```bash
+flanner web --open-browser     # http://localhost:8080
+```
+
+`flanner init` is safe to re-run. It detects your git root, creates `.plans/`, updates `.gitignore`, registers the MCP server with Claude Code, and installs the agent integration.
+
+## CLI commands
+
+```bash
+flanner init [--project-root PATH] [--plan-dir DIR]     # set up a project
+flanner status                                          # projects, plan files, db path
+flanner list [--project NAME] [--output json]           # list projects or a project's plans
+flanner sync [--project NAME] [--dry-run]               # import existing .plans/ files
+flanner config NAME [--plan-dir DIR] [...]              # change project settings
+flanner web [--port 8080] [--host 127.0.0.1] [--open-browser]
+flanner register [--force] / flanner unregister         # MCP registration with Claude Code
+flanner claude-info                                     # integration status
+```
+
+<details>
+<summary><b>Plan file format</b></summary>
+
+Every managed plan carries YAML frontmatter, generated by the tools and never hand-written:
+
+```markdown
+---
+mcp_plan_file: true
+project_id: 3d816ecd-489a-4fa0-abe2-15ec93f60d5a
+plan_file_id: 59c34f9c-8471-47fc-97f2-8dcfefa15434
+plan_name: architecture
+version: 2
+created_by: claude
+---
+
+# Architecture Plan
+
+Your plan content here...
+```
+
+</details>
+
+<details>
+<summary><b>Web interface</b></summary>
+
+![flanner dashboard](docs/assets/dashboard.png)
+
+A server-rendered dashboard, no build step, works offline:
+
+- Dashboard (`/`): projects, stats, and recent activity
+- Project detail (`/projects/{id}`): a project's plans, paginated
+- Plan viewer (`/plans/{id}`): rendered markdown, version selector, frontmatter
+- Editor (`/plans/{id}/edit`) and version history (`/plans/{id}/history`)
+
+The web UI binds `127.0.0.1` with no authentication. Do not expose it beyond localhost.
+
+</details>
+
+<details>
+<summary><b>Where data lives</b></summary>
+
+- Catalog (SQLite): `~/.flanner/data.db`, override with `FLANNER_HOME` or `FLANNER_DB_PATH`
+- Plan files: `.plans/` in your repo, git-ignored, named `name_v1.md`, `name_v2.md`, and so on
+
+</details>
+
+<details>
+<summary><b>Architecture</b></summary>
+
+Layering is enforced by `tests/test_architecture.py`:
+
+- **foundation** (`exceptions`, `utils`, `frontmatter`, `git_integration`, `jira_utils`) imports nothing else from the package
+- **data** (`database`, `storage`) sits on the foundation only
+- **composition roots** (`server` for MCP, `web`, `cli`) wire everything together and do not import each other (except `cli`, which launches both)
+
+Decisions are recorded in [docs/adr/](docs/adr/), with more guides in [docs/](docs/).
+
+</details>
+
+## How it works
+
+An agent calls `get_plan_config` to learn where plans go, then `create_plan_file_tool` or `update_plan_file_tool` to write them. Flanner places the file in the project's plan directory, adds the header, and bumps the version. Files stay in `.plans/` (git-ignored), so they never land in a commit by accident.
+
+## Roadmap
+
+Flanner is local-first today. Planned next:
+
+- Cloud-hosted plans: a PostgreSQL catalog and S3-backed storage for effectively unlimited history
+- Shared workspaces for team collaboration
+- Full-text search across plans
+- Links out to product trackers, chat, and second brains like Notion
+- Real-time updates in the web UI
+
+## Contributing
+
+Setup, the CI gates, benchmarks, and the release process are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

flanner-0.4.0/README.md

@@ -0,0 +1,139 @@
+# Flanner
+
+[![CI](https://github.com/jaysonmulwa/flanner/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jaysonmulwa/flanner/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A plan-file manager for AI coding agents, wired into Claude Code and other assistants over MCP (Model Context Protocol).
+
+AI agents write markdown constantly: design docs, migration plans, architecture notes. It piles up fast, scattered across your repo, quietly going stale, and easy to commit by accident. Flanner gives those files one home, versions them automatically as the agent revises, and keeps them out of git until you decide otherwise, with a browsable reading view and an audit trail on top.
+
+Today Flanner is local-first; the goal is cloud-hosted plans: shared workspaces for easier collaboration, effectively unlimited storage and history, and clean links to the tools teams already work in, from product trackers and chat to second brains like Notion.
+
+<div align="center">
+<img src="docs/assets/plan-view.png" alt="flanner reading view: a versioned plan file" width="840">
+</div>
+
+## Features
+
+- **MCP integration**: exposes plan-file tools to Claude Code and Codex.
+- **Automatic headers and versioning**: every plan gets YAML frontmatter, and each revision is a new version with a full history.
+- **Git protection**: plans live in `.plans/` and are kept out of commits automatically.
+- **Agent integration**: `flanner init` wires CLAUDE.md, AGENTS.md, and a guard hook so agents save plans through flanner instead of scattering raw markdown.
+- **Reading view**: a browser dashboard to read, edit, and walk the history of plans (light and dark, fully offline).
+- **Per-project config**: customize the plan directory per repository.
+
+## Quick start
+
+```bash
+cd flanner
+pip install -e .     # provides the `flanner` command
+flanner init         # database, MCP registration, and a project for this repo
+```
+
+Then ask your agent to work with plans:
+
+> "Create an architecture plan for the auth service"
+>
+> "Show me the history of the architecture plan"
+
+And open the dashboard to browse them:
+
+```bash
+flanner web --open-browser     # http://localhost:8080
+```
+
+`flanner init` is safe to re-run. It detects your git root, creates `.plans/`, updates `.gitignore`, registers the MCP server with Claude Code, and installs the agent integration.
+
+## CLI commands
+
+```bash
+flanner init [--project-root PATH] [--plan-dir DIR]     # set up a project
+flanner status                                          # projects, plan files, db path
+flanner list [--project NAME] [--output json]           # list projects or a project's plans
+flanner sync [--project NAME] [--dry-run]               # import existing .plans/ files
+flanner config NAME [--plan-dir DIR] [...]              # change project settings
+flanner web [--port 8080] [--host 127.0.0.1] [--open-browser]
+flanner register [--force] / flanner unregister         # MCP registration with Claude Code
+flanner claude-info                                     # integration status
+```
+
+<details>
+<summary><b>Plan file format</b></summary>
+
+Every managed plan carries YAML frontmatter, generated by the tools and never hand-written:
+
+```markdown
+---
+mcp_plan_file: true
+project_id: 3d816ecd-489a-4fa0-abe2-15ec93f60d5a
+plan_file_id: 59c34f9c-8471-47fc-97f2-8dcfefa15434
+plan_name: architecture
+version: 2
+created_by: claude
+---
+
+# Architecture Plan
+
+Your plan content here...
+```
+
+</details>
+
+<details>
+<summary><b>Web interface</b></summary>
+
+![flanner dashboard](docs/assets/dashboard.png)
+
+A server-rendered dashboard, no build step, works offline:
+
+- Dashboard (`/`): projects, stats, and recent activity
+- Project detail (`/projects/{id}`): a project's plans, paginated
+- Plan viewer (`/plans/{id}`): rendered markdown, version selector, frontmatter
+- Editor (`/plans/{id}/edit`) and version history (`/plans/{id}/history`)
+
+The web UI binds `127.0.0.1` with no authentication. Do not expose it beyond localhost.
+
+</details>
+
+<details>
+<summary><b>Where data lives</b></summary>
+
+- Catalog (SQLite): `~/.flanner/data.db`, override with `FLANNER_HOME` or `FLANNER_DB_PATH`
+- Plan files: `.plans/` in your repo, git-ignored, named `name_v1.md`, `name_v2.md`, and so on
+
+</details>
+
+<details>
+<summary><b>Architecture</b></summary>
+
+Layering is enforced by `tests/test_architecture.py`:
+
+- **foundation** (`exceptions`, `utils`, `frontmatter`, `git_integration`, `jira_utils`) imports nothing else from the package
+- **data** (`database`, `storage`) sits on the foundation only
+- **composition roots** (`server` for MCP, `web`, `cli`) wire everything together and do not import each other (except `cli`, which launches both)
+
+Decisions are recorded in [docs/adr/](docs/adr/), with more guides in [docs/](docs/).
+
+</details>
+
+## How it works
+
+An agent calls `get_plan_config` to learn where plans go, then `create_plan_file_tool` or `update_plan_file_tool` to write them. Flanner places the file in the project's plan directory, adds the header, and bumps the version. Files stay in `.plans/` (git-ignored), so they never land in a commit by accident.
+
+## Roadmap
+
+Flanner is local-first today. Planned next:
+
+- Cloud-hosted plans: a PostgreSQL catalog and S3-backed storage for effectively unlimited history
+- Shared workspaces for team collaboration
+- Full-text search across plans
+- Links out to product trackers, chat, and second brains like Notion
+- Real-time updates in the web UI
+
+## Contributing
+
+Setup, the CI gates, benchmarks, and the release process are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

flanner-0.4.0/flanner/__init__.py

@@ -0,0 +1,7 @@
+"""
+MCP Plan File Manager
+
+A comprehensive plan file management system for Claude Code and AI assistants.
+"""
+
+__version__ = "0.4.0"

flanner-0.4.0/flanner/__main__.py

@@ -0,0 +1,8 @@
+"""
+Main entry point for running the CLI as a module
+"""
+
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

flanner-0.4.0/flanner/agent_hooks.py

@@ -0,0 +1,226 @@
+"""Agent integration: the guard-write hook and init-time wiring.
+
+Two cooperating layers steer coding agents toward the flanner MCP tools:
+
+- a managed block in the repo's CLAUDE.md and AGENTS.md, plus a skill (soft:
+  guidance; AGENTS.md is the cross-tool convention Codex and others read)
+- a PreToolUse hook that denies raw Writes into the plan directory (hard:
+  enforcement, Claude Code only). The MCP tools write through flanner's
+  storage layer, not the agent's Write tool, so the correct path is never
+  blocked.
+
+`decide_write` is pure and takes a parsed payload + session so it can be
+tested without stdin or a live hook.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy.orm import Session
+
+from .database import ProjectModel, get_project_by_root
+from .git_integration import find_git_root
+
+AGENT_MD_START = "<!-- flanner:managed -->"
+AGENT_MD_END = "<!-- /flanner:managed -->"
+
+# The hook entry flanner merges into a repo's .claude/settings.json.
+HOOK_COMMAND = "flanner hook guard-write"
+HOOK_MATCHER = "Write|Edit|MultiEdit"
+
+
+def _resolve(file_path: str, cwd: str) -> Path:
+    """Absolute, normalized target path (file_path may be relative to cwd)."""
+    p = Path(file_path)
+    if not p.is_absolute():
+        p = Path(cwd) / p
+    return p.resolve()
+
+
+def decide_write(payload: dict[str, Any], session: Session) -> dict[str, Any] | None:
+    """Return a PreToolUse deny decision, or None to allow the write.
+
+    Allows (returns None) unless all three gates match: the repo is
+    flanner-managed, the target is a .md, and it sits inside that project's
+    plan directory. Any missing field or lookup miss allows the write.
+    """
+    tool_input = payload.get("tool_input") or {}
+    file_path = tool_input.get("file_path")
+    cwd = payload.get("cwd")
+    if not file_path or not cwd:
+        return None
+
+    target = _resolve(file_path, cwd)
+
+    root = find_git_root(str(target.parent)) or find_git_root(cwd)
+    if not root:
+        return None
+
+    project = get_project_by_root(session, root)
+    if not project or not project.project_root:
+        return None  # gate 1: not a flanner repo
+
+    plan_dir = (Path(project.project_root) / project.plan_directory).resolve()
+    if target.suffix != ".md" or not target.is_relative_to(plan_dir):
+        return None  # gate 2: not a plan file
+
+    return _deny(_steer_message(project, target))  # gate 3: wrong tool for a plan
+
+
+def _steer_message(project: ProjectModel, target: Path) -> str:
+    return (
+        f"{target.name} is a flanner-managed plan file (project '{project.name}', "
+        f"dir '{project.plan_directory}'). Don't write it directly; the plan header "
+        f"and versioning are added by the flanner MCP tools. To create it, call "
+        f"create_plan_file_tool(project_id='{project.id}', name='{target.stem}', "
+        f"content=<body without frontmatter>). To revise an existing plan, use "
+        f"update_plan_file_tool(plan_file_id=...)."
+    )
+
+
+def _deny(reason: str) -> dict[str, Any]:
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+
+
+def run_guard_write(raw_stdin: str, session: Session) -> str:
+    """Read a PreToolUse payload, return the JSON to print (empty = allow).
+
+    Fails open: any error yields an allow, so a broken guard never blocks
+    a legitimate write.
+    """
+    try:
+        payload = json.loads(raw_stdin) if raw_stdin.strip() else {}
+        decision = decide_write(payload, session)
+    except Exception:
+        return ""
+    return json.dumps(decision) if decision else ""
+
+
+# Agent-instruction files flanner writes the managed block into. CLAUDE.md is
+# read by Claude Code; AGENTS.md is the cross-tool convention read by Codex and
+# others. The block is tool-agnostic (it points at the MCP tools), so both get
+# the same guidance.
+AGENT_MD_FILES = ("CLAUDE.md", "AGENTS.md")
+
+
+def agent_md_block(project: ProjectModel) -> str:
+    """The managed section naming the plan dir and the tools to use."""
+    return (
+        f"{AGENT_MD_START}\n"
+        f"## Plan files (managed by flanner)\n\n"
+        f"Design, architecture, and planning markdown for this repo is managed by "
+        f"flanner and lives in `{project.plan_directory}/` (project: {project.name}).\n\n"
+        f"When the user asks to save a plan/design/architecture doc, confirm it is a "
+        f"plan, then use the flanner MCP tools instead of writing the file directly:\n\n"
+        f"- `get_plan_config` to confirm the location and header format\n"
+        f"- `create_plan_file_tool(project_id, name, content)` to create it "
+        f"(adds the YAML header and versions it)\n"
+        f"- `update_plan_file_tool(plan_file_id, content)` to revise it\n\n"
+        f"Never hand-write the YAML header; the tools generate it.\n"
+        f"{AGENT_MD_END}"
+    )
+
+
+def upsert_agent_md(root: str, filename: str, block: str) -> bool:
+    """Write or replace the managed block in <root>/<filename>. Returns True if changed."""
+    path = Path(root) / filename
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+
+    if AGENT_MD_START in existing and AGENT_MD_END in existing:
+        head, _, rest = existing.partition(AGENT_MD_START)
+        _, _, tail = rest.partition(AGENT_MD_END)
+        updated = f"{head.rstrip()}\n\n{block}\n{tail.lstrip()}".strip() + "\n"
+    elif existing.strip():
+        updated = existing.rstrip() + "\n\n" + block + "\n"
+    else:
+        updated = block + "\n"
+
+    if updated == existing:
+        return False
+    path.write_text(updated, encoding="utf-8")
+    return True
+
+
+def ensure_settings_hook(root: str) -> bool:
+    """Merge the guard-write PreToolUse hook into <root>/.claude/settings.json.
+
+    Idempotent; returns True if the file was changed.
+    """
+    settings_path = Path(root) / ".claude" / "settings.json"
+    settings: dict[str, Any] = {}
+    if settings_path.exists():
+        try:
+            settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            settings = {}
+
+    hooks = settings.setdefault("hooks", {})
+    pre = hooks.setdefault("PreToolUse", [])
+
+    already = any(
+        h.get("type") == "command" and h.get("command") == HOOK_COMMAND
+        for entry in pre
+        if isinstance(entry, dict)
+        for h in entry.get("hooks", [])
+    )
+    if already:
+        return False
+
+    pre.append(
+        {
+            "matcher": HOOK_MATCHER,
+            "hooks": [{"type": "command", "command": HOOK_COMMAND}],
+        }
+    )
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    return True
+
+
+SKILL_NAME = "flanner-plan"
+
+_SKILL_BODY = """---
+name: flanner-plan
+description: >
+  Save or update a plan, design, architecture, migration, or RFC document
+  through flanner so it is placed in the managed plan directory, given the
+  standard YAML header, and versioned. Use when the user asks to write or
+  revise any planning markdown that should be tracked, or when you are about
+  to create such a document yourself.
+---
+
+# Saving a plan through flanner
+
+This repo manages planning docs with flanner. Do not write them with the
+Write tool; the plan directory and header are handled by the MCP tools.
+
+1. Confirm intent. If it is ambiguous whether a markdown file is a plan
+   (versus a README, changelog, or notes), ask the user before proceeding.
+2. Resolve the target with `get_plan_config` and `list_projects`.
+3. Create with `create_plan_file_tool(project_id, name, content)`, passing the
+   markdown body WITHOUT frontmatter; the header is added for you.
+4. Revise an existing plan with `update_plan_file_tool(plan_file_id, content)`,
+   which bumps the version and re-hashes the content.
+
+Never hand-write the YAML header, and never place plan files outside the
+directory reported by `get_plan_config`.
+"""
+
+
+def install_skill(root: str) -> bool:
+    """Write the flanner-plan skill into <root>/.claude/skills. Returns True if changed."""
+    skill_path = Path(root) / ".claude" / "skills" / SKILL_NAME / "SKILL.md"
+    if skill_path.exists() and skill_path.read_text(encoding="utf-8") == _SKILL_BODY:
+        return False
+    skill_path.parent.mkdir(parents=True, exist_ok=True)
+    skill_path.write_text(_SKILL_BODY, encoding="utf-8")
+    return True