PyPI - flanner - Versions diffs - 0.4.0__py3-none-any.whl - Mend

flanner 0.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

flanner/__init__.py +7 -0
flanner/__main__.py +8 -0
flanner/agent_hooks.py +226 -0
flanner/claude_integration.py +386 -0
flanner/cli.py +1283 -0
flanner/database.py +946 -0
flanner/exceptions.py +51 -0
flanner/frontmatter.py +213 -0
flanner/git_integration.py +321 -0
flanner/jira_utils.py +138 -0
flanner/plan_ops.py +68 -0
flanner/server.py +981 -0
flanner/storage.py +242 -0
flanner/utils.py +225 -0
flanner/web/static/css/styles.css +843 -0
flanner/web/static/js/app.js +145 -0
flanner/web/templates/_empty_glyph.html +12 -0
flanner/web/templates/base.html +66 -0
flanner/web/templates/dashboard.html +109 -0
flanner/web/templates/error.html +13 -0
flanner/web/templates/plan_edit.html +85 -0
flanner/web/templates/plan_history.html +110 -0
flanner/web/templates/plan_new.html +92 -0
flanner/web/templates/plan_view.html +88 -0
flanner/web/templates/project_detail.html +109 -0
flanner/web/templates/project_new.html +93 -0
flanner/web/templates/projects.html +72 -0
flanner/web.py +788 -0
flanner-0.4.0.dist-info/METADATA +189 -0
flanner-0.4.0.dist-info/RECORD +34 -0
flanner-0.4.0.dist-info/WHEEL +5 -0
flanner-0.4.0.dist-info/entry_points.txt +2 -0
flanner-0.4.0.dist-info/licenses/LICENSE +21 -0
flanner-0.4.0.dist-info/top_level.txt +1 -0

flanner/__init__.py ADDED Viewed

@@ -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/__main__.py ADDED Viewed

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

flanner/agent_hooks.py ADDED Viewed

@@ -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

flanner/claude_integration.py ADDED Viewed

@@ -0,0 +1,386 @@
+"""
+Claude Code Integration for Flanner
+Handles automatic registration of MCP server with Claude Code.
+"""
+import json
+import logging
+import platform
+from pathlib import Path
+from typing import Any
+logger = logging.getLogger(__name__)
+def get_claude_config_path() -> Path | None:
+    """
+    Get the path to Claude Desktop configuration file.
+    Returns:
+        Path to claude_desktop_config.json or None if not found
+    """
+    system = platform.system()
+    home = Path.home()
+    # Possible Claude Desktop config locations
+    possible_paths = []
+    if system == "Windows":
+        # Windows paths
+        possible_paths = [
+            home / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json",
+            home / ".claude" / "claude_desktop_config.json",
+        ]
+    elif system == "Darwin":  # macOS
+        possible_paths = [
+            home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+            home / ".claude" / "claude_desktop_config.json",
+        ]
+    else:  # Linux
+        possible_paths = [
+            home / ".config" / "claude" / "claude_desktop_config.json",
+            home / ".claude" / "claude_desktop_config.json",
+        ]
+    # Return first existing path
+    for path in possible_paths:
+        if path.exists():
+            return path
+    # Return default path (even if it doesn't exist yet)
+    return possible_paths[0] if possible_paths else None
+def read_claude_config() -> dict[str, Any]:
+    """
+    Read Claude Code MCP settings.
+    Returns:
+        Dictionary of MCP settings, or empty dict with mcpServers key
+    """
+    config_path = get_claude_config_path()
+    if not config_path or not config_path.exists():
+        return {"mcpServers": {}}
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            config: dict[str, Any] = json.load(f)
+        # Ensure mcpServers key exists
+        if "mcpServers" not in config:
+            config["mcpServers"] = {}
+        return config
+    except Exception as e:
+        logger.warning("Could not read Claude config: %s", e)
+        return {"mcpServers": {}}
+def write_claude_config(config: dict[str, Any]) -> bool:
+    """
+    Write Claude Code MCP settings.
+    Args:
+        config: Configuration dictionary
+    Returns:
+        True if successful, False otherwise
+    """
+    config_path = get_claude_config_path()
+    if not config_path:
+        return False
+    try:
+        # Ensure directory exists
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        # Write config with pretty formatting
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2)
+        return True
+    except Exception as e:
+        logger.error("Could not write Claude config: %s", e)
+        return False
+def get_local_server_config() -> dict[str, Any]:
+    """
+    Get the configuration for local MCP server.
+    Returns:
+        Server configuration dictionary
+    """
+    # Get absolute path to the project directory
+    project_dir = Path(__file__).resolve().parent.parent
+    return {
+        "command": "python",
+        "args": ["-m", "flanner.server"],
+        "cwd": str(project_dir),
+        "env": {
+            # Add any environment variables if needed
+        },
+    }
+def get_cloud_server_config(server_url: str, api_key: str | None = None) -> dict[str, Any]:
+    """
+    Get the configuration for cloud-based MCP server (future use).
+    Args:
+        server_url: URL of the cloud MCP server
+        api_key: Optional API key for authentication
+    Returns:
+        Server configuration dictionary
+    """
+    config = {
+        "type": "cloud",
+        "url": server_url,
+    }
+    if api_key:
+        config["apiKey"] = api_key
+    return config
+def is_server_registered(server_name: str = "flanner") -> bool:
+    """
+    Check if MCP server is registered in Claude Code.
+    Args:
+        server_name: Name of the server to check
+    Returns:
+        True if server is registered, False otherwise
+    """
+    config = read_claude_config()
+    return server_name in config.get("mcpServers", {})
+def get_server_config_from_claude(server_name: str = "flanner") -> dict[str, Any] | None:
+    """
+    Get the current server configuration from Claude Code.
+    Args:
+        server_name: Name of the server
+    Returns:
+        Server configuration or None if not found
+    """
+    config = read_claude_config()
+    server_config: dict[str, Any] | None = config.get("mcpServers", {}).get(server_name)
+    return server_config
+def register_mcp_server(
+    server_name: str = "flanner",
+    server_type: str = "local",
+    server_url: str | None = None,
+    api_key: str | None = None,
+    force: bool = False,
+) -> tuple[bool, str]:
+    """
+    Register MCP server with Claude Code.
+    Args:
+        server_name: Name to register the server under
+        server_type: "local" or "cloud"
+        server_url: URL for cloud servers
+        api_key: API key for cloud servers
+        force: If True, overwrite existing configuration
+    Returns:
+        Tuple of (success: bool, message: str)
+    """
+    # Get current config
+    config = read_claude_config()
+    # Check if already registered
+    if server_name in config["mcpServers"] and not force:
+        return True, f"Server '{server_name}' is already registered in Claude Code"
+    # Get server configuration based on type
+    if server_type == "local":
+        server_config = get_local_server_config()
+    elif server_type == "cloud":
+        if not server_url:
+            return False, "Cloud server requires a URL"
+        server_config = get_cloud_server_config(server_url, api_key)
+    else:
+        return False, f"Invalid server type: {server_type}"
+    # Add server to config
+    config["mcpServers"][server_name] = server_config
+    # Write config
+    if write_claude_config(config):
+        action = "Updated" if force else "Registered"
+        return True, f"{action} MCP server '{server_name}' in Claude Code"
+    else:
+        return False, "Failed to write Claude Code configuration"
+def unregister_mcp_server(server_name: str = "flanner") -> tuple[bool, str]:
+    """
+    Unregister MCP server from Claude Code.
+    Args:
+        server_name: Name of the server to unregister
+    Returns:
+        Tuple of (success: bool, message: str)
+    """
+    config = read_claude_config()
+    if server_name not in config.get("mcpServers", {}):
+        return False, f"Server '{server_name}' is not registered in Claude Code"
+    # Remove server
+    del config["mcpServers"][server_name]
+    # Write config
+    if write_claude_config(config):
+        return True, f"Unregistered MCP server '{server_name}' from Claude Code"
+    else:
+        return False, "Failed to write Claude Code configuration"
+def verify_server_config() -> tuple[bool, str, dict[str, Any] | None]:
+    """
+    Verify that the registered MCP server configuration is correct.
+    Returns:
+        Tuple of (is_valid: bool, message: str, current_config: Optional[Dict])
+    """
+    server_name = "flanner"
+    # Check if registered
+    if not is_server_registered(server_name):
+        return False, "MCP server is not registered in Claude Code", None
+    # Get current config
+    current_config = get_server_config_from_claude(server_name)
+    expected_config = get_local_server_config()
+    # Compare configurations
+    if current_config == expected_config:
+        return True, "MCP server configuration is correct", current_config
+    else:
+        return False, "MCP server configuration has changed", current_config
+def get_claude_config_info() -> dict[str, Any]:
+    """
+    Get information about Claude Code configuration.
+    Returns:
+        Dictionary with configuration information
+    """
+    config_path = get_claude_config_path()
+    info = {
+        "config_path": str(config_path) if config_path else "Not found",
+        "config_exists": config_path.exists() if config_path else False,
+        "server_registered": is_server_registered(),
+        "total_servers": 0,
+        "our_server_config": None,
+    }
+    if config_path and config_path.exists():
+        config = read_claude_config()
+        info["total_servers"] = len(config.get("mcpServers", {}))
+        info["our_server_config"] = config.get("mcpServers", {}).get("flanner")
+    return info
+def auto_register_on_init() -> tuple[bool, str]:
+    """
+    Automatically register MCP server on first init.
+    This is called during 'mcp-plan init' command.
+    Returns:
+        Tuple of (success: bool, message: str)
+    """
+    # Check if already registered
+    if is_server_registered():
+        # Verify configuration is correct
+        is_valid, msg, current_config = verify_server_config()
+        if is_valid:
+            return True, "MCP server already registered and up-to-date"
+        else:
+            # Configuration changed, update it
+            success, update_msg = register_mcp_server(force=True)
+            if success:
+                return True, "MCP server configuration updated"
+            else:
+                return False, f"Failed to update configuration: {update_msg}"
+    else:
+        # Not registered, register it
+        return register_mcp_server()
+def check_server_status() -> dict[str, Any]:
+    """
+    Check the status of MCP server registration.
+    This is called during 'mcp-plan status' command.
+    Returns:
+        Dictionary with status information
+    """
+    status = {
+        "registered": False,
+        "config_valid": False,
+        "config_path": None,
+        "message": "",
+        "action_needed": None,
+    }
+    config_path = get_claude_config_path()
+    status["config_path"] = str(config_path) if config_path else "Not found"
+    if not config_path:
+        status["message"] = "Claude Code configuration path not found"
+        status["action_needed"] = "Please ensure Claude Code is installed"
+        return status
+    if not is_server_registered():
+        status["message"] = "MCP server is not registered in Claude Code"
+        status["action_needed"] = "Run: flanner init (or manually register)"
+        return status
+    status["registered"] = True
+    # Verify configuration
+    is_valid, msg, current_config = verify_server_config()
+    status["config_valid"] = is_valid
+    status["message"] = msg
+    if not is_valid:
+        status["action_needed"] = "Run: flanner init (to update configuration)"
+    return status
+def print_registration_instructions() -> None:
+    """
+    Print manual registration instructions for Claude Code.
+    """
+    server_config = get_local_server_config()
+    print("\n" + "=" * 60)
+    print("CLAUDE CODE MCP SERVER CONFIGURATION")
+    print("=" * 60)
+    print("\nTo manually add the MCP server to Claude Code:")
+    print("\n1. Open Claude Code settings")
+    print("2. Add the following to your MCP settings:\n")
+    print(json.dumps({"mcpServers": {"flanner": server_config}}, indent=2))
+    print("\n3. Restart Claude Code")
+    print("=" * 60 + "\n")