buildlog 0.9.0__tar.gz → 0.10.0__tar.gz

{buildlog-0.9.0 → buildlog-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buildlog
-Version: 0.9.0
+Version: 0.10.0
 Summary: Engineering notebook for AI-assisted development
 Project-URL: Homepage, https://github.com/Peleke/buildlog-template
 Project-URL: Repository, https://github.com/Peleke/buildlog-template
@@ -22,12 +22,12 @@ Classifier: Topic :: Software Development :: Documentation
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0.0
 Requires-Dist: copier>=9.0.0
+Requires-Dist: mcp>=1.0.0
 Requires-Dist: numpy>=1.21.0
 Requires-Dist: pymupdf>=1.26.7
 Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: all
 Requires-Dist: anthropic>=0.40.0; extra == 'all'
-Requires-Dist: mcp>=1.0.0; extra == 'all'
 Requires-Dist: ollama>=0.4.0; extra == 'all'
 Requires-Dist: openai>=1.0.0; extra == 'all'
 Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
@@ -51,7 +51,6 @@ Provides-Extra: llm
 Requires-Dist: anthropic>=0.40.0; extra == 'llm'
 Requires-Dist: ollama>=0.4.0; extra == 'llm'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
 Provides-Extra: ollama
 Requires-Dist: ollama>=0.4.0; extra == 'ollama'
 Provides-Extra: openai
@@ -164,22 +163,29 @@ The roadmap: contextual bandits (now) -> richer policy models -> longer-horizon
 
 ## Installation
 
+### Quick start
+
+```bash
+pip install buildlog          # MCP server included by default
+buildlog init --defaults      # scaffold project, register MCP, update CLAUDE.md
+```
+
+That's it. Claude Code will now have access to all 29 buildlog tools.
+
 ### Global install (recommended)
 
 ```bash
-uv tool install "buildlog[mcp]"   # or: pipx install "buildlog[mcp]"
+uv tool install buildlog   # or: pipx install buildlog
 ```
 
-This puts `buildlog` and `buildlog-mcp` on your PATH. Works from any directory. The `[mcp]` extra is required for the MCP server.
+This puts `buildlog` and `buildlog-mcp` on your PATH. Works from any directory.
 
 ### Per-project (virtual environment)
 
 ```bash
-uv pip install "buildlog[mcp]"   # or: pip install "buildlog[mcp]"
+uv pip install buildlog    # or: pip install buildlog
 ```
 
-Omit `[mcp]` if you only need the CLI.
-
 ### For JS/TS projects
 
 ```bash
@@ -188,17 +194,11 @@ npx @peleke.s/buildlog init
 
 ### MCP server for Claude Code
 
-Add to `~/.claude/claude_code_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "buildlog": {
-      "command": "buildlog-mcp",
-      "args": []
-    }
-  }
-}
+`buildlog init` auto-registers the MCP server. For existing projects:
+
+```bash
+buildlog init-mcp          # register MCP in .claude/settings.json
+buildlog mcp-test          # verify all 29 tools are registered
 ```
 
 This exposes buildlog tools (seeds, skills, experiments, gauntlet, bandit status) to any Claude Code session.
@@ -206,10 +206,10 @@ This exposes buildlog tools (seeds, skills, experiments, gauntlet, bandit status
 ## Quick Start
 
 ```bash
-buildlog init              # scaffold a project (run in any repo)
-buildlog new my-feature    # start a session
+buildlog init --defaults      # scaffold + MCP + CLAUDE.md
+buildlog new my-feature       # start a session
 # ... work ...
-buildlog distill && buildlog skills
+buildlog commit -m "feat: add auth"
 buildlog experiment start
 # ... work across sessions ...
 buildlog experiment end

{buildlog-0.9.0 → buildlog-0.10.0}/README.md

@@ -104,22 +104,29 @@ The roadmap: contextual bandits (now) -> richer policy models -> longer-horizon
 
 ## Installation
 
+### Quick start
+
+```bash
+pip install buildlog          # MCP server included by default
+buildlog init --defaults      # scaffold project, register MCP, update CLAUDE.md
+```
+
+That's it. Claude Code will now have access to all 29 buildlog tools.
+
 ### Global install (recommended)
 
 ```bash
-uv tool install "buildlog[mcp]"   # or: pipx install "buildlog[mcp]"
+uv tool install buildlog   # or: pipx install buildlog
 ```
 
-This puts `buildlog` and `buildlog-mcp` on your PATH. Works from any directory. The `[mcp]` extra is required for the MCP server.
+This puts `buildlog` and `buildlog-mcp` on your PATH. Works from any directory.
 
 ### Per-project (virtual environment)
 
 ```bash
-uv pip install "buildlog[mcp]"   # or: pip install "buildlog[mcp]"
+uv pip install buildlog    # or: pip install buildlog
 ```
 
-Omit `[mcp]` if you only need the CLI.
-
 ### For JS/TS projects
 
 ```bash
@@ -128,17 +135,11 @@ npx @peleke.s/buildlog init
 
 ### MCP server for Claude Code
 
-Add to `~/.claude/claude_code_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "buildlog": {
-      "command": "buildlog-mcp",
-      "args": []
-    }
-  }
-}
+`buildlog init` auto-registers the MCP server. For existing projects:
+
+```bash
+buildlog init-mcp          # register MCP in .claude/settings.json
+buildlog mcp-test          # verify all 29 tools are registered
 ```
 
 This exposes buildlog tools (seeds, skills, experiments, gauntlet, bandit status) to any Claude Code session.
@@ -146,10 +147,10 @@ This exposes buildlog tools (seeds, skills, experiments, gauntlet, bandit status
 ## Quick Start
 
 ```bash
-buildlog init              # scaffold a project (run in any repo)
-buildlog new my-feature    # start a session
+buildlog init --defaults      # scaffold + MCP + CLAUDE.md
+buildlog new my-feature       # start a session
 # ... work ...
-buildlog distill && buildlog skills
+buildlog commit -m "feat: add auth"
 buildlog experiment start
 # ... work across sessions ...
 buildlog experiment end

{buildlog-0.9.0 → buildlog-0.10.0}/post_gen.py

@@ -3,7 +3,11 @@
 
 from pathlib import Path
 
-CLAUDE_MD_SECTION = """
+try:
+    from buildlog.constants import CLAUDE_MD_BUILDLOG_SECTION
+except ImportError:
+    # Fallback for when buildlog isn't installed (e.g., copier from GitHub)
+    CLAUDE_MD_BUILDLOG_SECTION = """
 ## Build Journal
 
 After completing significant work (features, debugging sessions, deployments,
@@ -40,15 +44,16 @@ def main():
 
     content = claude_md.read_text()
 
-    if "## Build Journal" in content:
-        print("Build Journal section already exists in CLAUDE.md")
+    # Check for either old or new section marker
+    if "## buildlog Integration" in content or "## Build Journal" in content:
+        print("buildlog section already exists in CLAUDE.md")
         return
 
     # Append to end of file
     with open(claude_md, "a") as f:
-        f.write("\n" + CLAUDE_MD_SECTION)
+        f.write("\n" + CLAUDE_MD_BUILDLOG_SECTION)
 
-    print("Added Build Journal section to CLAUDE.md")
+    print("Added buildlog Integration section to CLAUDE.md")
 
 
 if __name__ == "__main__":

{buildlog-0.9.0 → buildlog-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "buildlog"
-version = "0.9.0"
+version = "0.10.0"
 description = "Engineering notebook for AI-assisted development"
 readme = "README.md"
 license = "MIT"
@@ -32,6 +32,7 @@ dependencies = [
     "pyyaml>=6.0.0",
     "numpy>=1.21.0",
     "pymupdf>=1.26.7",
+    "mcp>=1.0.0",
 ]
 
 [project.optional-dependencies]
@@ -60,15 +61,12 @@ llm = [
     "ollama>=0.4.0",
     "anthropic>=0.40.0",
 ]
-# MCP server for Claude Code integration
-mcp = [
-    "mcp>=1.0.0",
-]
+# MCP server for Claude Code integration (now a default dependency, kept for backwards compat)
+mcp = []
 # All optional features
 all = [
     "sentence-transformers>=2.2.0",
     "openai>=1.0.0",
-    "mcp>=1.0.0",
     "ollama>=0.4.0",
     "anthropic>=0.40.0",
 ]

{buildlog-0.9.0 → buildlog-0.10.0}/src/buildlog/cli.py

@@ -50,12 +50,13 @@ def main():
 
 @main.command()
 @click.option("--no-claude-md", is_flag=True, help="Don't update CLAUDE.md")
+@click.option("--no-mcp", is_flag=True, help="Don't register MCP server")
 @click.option(
     "--defaults",
     is_flag=True,
     help="Use default values for all prompts (non-interactive)",
 )
-def init(no_claude_md: bool, defaults: bool):
+def init(no_claude_md: bool, no_mcp: bool, defaults: bool):
     """Initialize buildlog in the current directory.
 
     Sets up the buildlog/ directory with templates and optionally
@@ -109,23 +110,40 @@ def init(no_claude_md: bool, defaults: bool):
         click.echo("Failed to initialize buildlog.", err=True)
         raise SystemExit(1)
 
+    # Ensure .buildlog/ directory exists (copier skips dot-prefixed paths)
+    dot_buildlog = buildlog_dir / ".buildlog"
+    dot_buildlog.mkdir(exist_ok=True)
+    (dot_buildlog / "seeds").mkdir(exist_ok=True)
+
     # Update CLAUDE.md if it exists and user didn't opt out
     if not no_claude_md:
         claude_md = Path("CLAUDE.md")
         if claude_md.exists():
             content = claude_md.read_text()
-            if "## Build Journal" not in content:
-                section = (
-                    "\n## Build Journal\n\n"
-                    "After completing significant work (features, debugging sessions, "
-                    "deployments,\n"
-                    "2+ hour focused sessions), write a build journal entry.\n\n"
-                    "**Location:** `buildlog/YYYY-MM-DD-{slug}.md`\n"
-                    "**Template:** `buildlog/_TEMPLATE.md`\n"
-                )
+            if (
+                "## buildlog Integration" not in content
+                and "## Build Journal" not in content
+            ):
+                try:
+                    from buildlog.constants import CLAUDE_MD_BUILDLOG_SECTION
+
+                    section = CLAUDE_MD_BUILDLOG_SECTION
+                except ImportError:
+                    section = (
+                        "\n## Build Journal\n\n"
+                        "After completing significant work (features, debugging "
+                        "sessions, deployments,\n"
+                        "2+ hour focused sessions), write a build journal entry.\n\n"
+                        "**Location:** `buildlog/YYYY-MM-DD-{slug}.md`\n"
+                        "**Template:** `buildlog/_TEMPLATE.md`\n"
+                    )
                 with open(claude_md, "a") as f:
                     f.write(section)
-                click.echo("Added Build Journal section to CLAUDE.md")
+                click.echo("Added buildlog Integration section to CLAUDE.md")
+
+    # Register MCP server unless opted out
+    if not no_mcp:
+        _init_mcp()
 
     click.echo("\n✓ buildlog initialized!")
     click.echo()
@@ -142,12 +160,125 @@ def init(no_claude_md: bool, defaults: bool):
     click.echo("Start now: buildlog new my-first-task --quick")
 
 
+def _init_mcp(settings_path: Path | None = None, global_mode: bool = False) -> None:
+    """Register buildlog as an MCP server in settings.json.
+
+    Args:
+        settings_path: Path to settings.json. Defaults to .claude/settings.json
+        global_mode: If True, display global-specific messaging
+    """
+    import json as json_module
+
+    if settings_path is None:
+        settings_path = Path(".claude") / "settings.json"
+
+    location = "~/.claude/settings.json" if global_mode else ".claude/settings.json"
+
+    try:
+        if settings_path.exists():
+            try:
+                data = json_module.loads(settings_path.read_text())
+            except json_module.JSONDecodeError:
+                click.echo(
+                    f"Warning: {location} is malformed, skipping MCP registration",
+                    err=True,
+                )
+                return
+        else:
+            data = {}
+
+        if "mcpServers" not in data:
+            data["mcpServers"] = {}
+
+        if "buildlog" in data["mcpServers"]:
+            click.echo(f"buildlog MCP server already registered in {location}")
+            return
+
+        data["mcpServers"]["buildlog"] = {"command": "buildlog-mcp", "args": []}
+
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+        settings_path.write_text(json_module.dumps(data, indent=2) + "\n")
+        click.echo(f"Registered buildlog MCP server in {location}")
+        if global_mode:
+            click.echo("Claude Code now has access to buildlog tools in all projects.")
+    except Exception as e:
+        click.echo(f"Warning: could not register MCP server: {e}", err=True)
+
+
+@main.command("init-mcp")
+@click.option(
+    "--global",
+    "global_",
+    is_flag=True,
+    help="Register globally in ~/.claude/settings.json (works in any project)",
+)
+def init_mcp(global_: bool):
+    """Register buildlog as an MCP server for Claude Code.
+
+    Creates or updates .claude/settings.json with the buildlog MCP
+    server configuration. Idempotent — safe to run multiple times.
+
+    Use --global to register in ~/.claude/settings.json so buildlog
+    tools are available in every project without per-project init.
+
+    Examples:
+
+        buildlog init-mcp              # local (current project)
+        buildlog init-mcp --global     # global (all projects)
+    """
+    if global_:
+        settings_path = Path.home() / ".claude" / "settings.json"
+        _init_mcp(settings_path=settings_path, global_mode=True)
+    else:
+        _init_mcp()
+
+
+@main.command("mcp-test")
+def mcp_test():
+    """Verify the MCP server starts and all tools are registered.
+
+    Checks that the buildlog-mcp server can be imported and lists
+    all registered tools. Exits 0 if all 29 tools are found, 1 otherwise.
+
+    Examples:
+
+        buildlog mcp-test
+    """
+    try:
+        from buildlog.mcp.server import mcp as mcp_server
+    except ImportError:
+        click.echo("MCP not installed. Run: pip install buildlog", err=True)
+        raise SystemExit(1)
+
+    try:
+        # FastMCP stores tools internally
+        tools = mcp_server._tool_manager._tools
+        tool_names = sorted(tools.keys())
+    except AttributeError:
+        # Fallback: try to count via the public API pattern
+        click.echo("Warning: could not inspect tools via internal API", err=True)
+        tool_names = []
+
+    expected = 29
+    click.echo(f"buildlog MCP server: {len(tool_names)} tools registered")
+    for name in tool_names:
+        click.echo(f"  {name}")
+
+    if len(tool_names) >= expected:
+        click.echo(f"\nAll {expected} tools registered.")
+        raise SystemExit(0)
+    else:
+        click.echo(f"\nExpected {expected} tools, found {len(tool_names)}.", err=True)
+        raise SystemExit(1)
+
+
 @main.command()
 @click.option("--json", "output_json", is_flag=True, help="Output as JSON")
 def overview(output_json: bool):
     """Show the full state of your buildlog at a glance.
 
     Entries, skills, promoted rules, experiments — everything in one view.
+    Works even without buildlog init (shows uninitialized state).
 
     Examples:
 
@@ -158,9 +289,38 @@ def overview(output_json: bool):
 
     buildlog_dir = Path("buildlog")
 
+    # Handle uninitialized state gracefully
     if not buildlog_dir.exists():
-        click.echo("No buildlog/ directory found. Run 'buildlog init' first.", err=True)
-        raise SystemExit(1)
+        result = {
+            "initialized": False,
+            "entries": 0,
+            "skills": {
+                "total": 0,
+                "by_confidence": {},
+                "promoted": 0,
+                "rejected": 0,
+                "pending": 0,
+            },
+            "active_session": None,
+            "render_targets": [],
+            "message": "buildlog not initialized. Run 'buildlog init' to enable full features.",
+        }
+        if output_json:
+            click.echo(json_module.dumps(result, indent=2))
+        else:
+            click.echo("buildlog overview")
+            click.echo("=" * 40)
+            click.echo("  Status:      Not initialized")
+            click.echo()
+            click.echo("Get started:")
+            click.echo("  buildlog init --defaults    # Initialize buildlog")
+            click.echo()
+            click.echo("Or use globally without init:")
+            click.echo("  buildlog init-mcp --global  # Register MCP server globally")
+            click.echo(
+                "  buildlog gauntlet list      # Review personas work without init"
+            )
+        return
 
     # Count entries
     entries = sorted(buildlog_dir.glob("20??-??-??-*.md"))
@@ -208,6 +368,7 @@ def overview(output_json: bool):
     from buildlog.render import RENDERERS
 
     result = {
+        "initialized": True,
         "entries": len(entries),
         "skills": {
             "total": total_skills,
@@ -586,7 +747,7 @@ def distill(
     """Extract patterns from all buildlog entries.
 
     Parses the Improvements section of each buildlog entry and aggregates
-    insights into structured output (JSON or YAML).
+    insights into structured output (JSON or YAML). Returns empty result if not initialized.
 
     Examples:
 
@@ -596,11 +757,25 @@ def distill(
         buildlog distill --since 2026-01-01    # Filter by date
         buildlog distill --category workflow   # Filter by category
     """
+    import json as json_module
+
     buildlog_dir = Path("buildlog")
 
+    # Handle uninitialized state gracefully
     if not buildlog_dir.exists():
-        click.echo("No buildlog/ directory found. Run 'buildlog init' first.", err=True)
-        raise SystemExit(1)
+        empty_result = {
+            "initialized": False,
+            "patterns": [],
+            "statistics": {"total_patterns": 0, "total_entries": 0},
+            "message": "buildlog not initialized",
+        }
+        if fmt == "json":
+            click.echo(json_module.dumps(empty_result, indent=2))
+        else:
+            click.echo(
+                "# buildlog not initialized - run 'buildlog init' first\npatterns: []"
+            )
+        return
 
     # Convert datetime to date if provided
     since_date = since.date() if since else None
@@ -651,6 +826,7 @@ def stats(output_json: bool, detailed: bool, since_date: str | None):
     """Show buildlog statistics and analytics.
 
     Provides insights on buildlog usage, coverage, and quality.
+    Returns empty stats if not initialized.
 
     Examples:
 
@@ -659,11 +835,27 @@ def stats(output_json: bool, detailed: bool, since_date: str | None):
         buildlog stats --detailed   # Include top sources
         buildlog stats --since 2026-01-01
     """
+    import json as json_module
+
     buildlog_dir = Path("buildlog")
 
+    # Handle uninitialized state gracefully
     if not buildlog_dir.exists():
-        click.echo("No buildlog/ directory found. Run 'buildlog init' first.", err=True)
-        raise SystemExit(1)
+        empty_stats = {
+            "initialized": False,
+            "total_entries": 0,
+            "total_patterns": 0,
+            "categories": {},
+            "date_range": None,
+            "message": "buildlog not initialized",
+        }
+        if output_json:
+            click.echo(json_module.dumps(empty_stats, indent=2))
+        else:
+            click.echo("buildlog stats")
+            click.echo("=" * 40)
+            click.echo("  Not initialized. Run 'buildlog init' first.")
+        return
 
     # Parse since date if provided
     parsed_since = None
@@ -726,7 +918,7 @@ def skills(
     """Generate agent-consumable skills from buildlog patterns.
 
     Transforms distilled patterns into actionable rules with deduplication,
-    confidence scoring, and stable IDs.
+    confidence scoring, and stable IDs. Returns empty set if not initialized.
 
     Examples:
 
@@ -743,9 +935,31 @@ def skills(
     """
     buildlog_dir = Path("buildlog")
 
+    # Handle uninitialized state gracefully - return empty skill set
     if not buildlog_dir.exists():
-        click.echo("No buildlog/ directory found. Run 'buildlog init' first.", err=True)
-        raise SystemExit(1)
+        if fmt == "json":
+            import json as json_module
+
+            click.echo(
+                json_module.dumps(
+                    {
+                        "initialized": False,
+                        "skills": {},
+                        "total_skills": 0,
+                        "message": "buildlog not initialized",
+                    },
+                    indent=2,
+                )
+            )
+        elif fmt == "yaml":
+            click.echo(
+                "# buildlog not initialized - run 'buildlog init' first\nskills: {}\ntotal_skills: 0"
+            )
+        else:
+            click.echo(
+                "No buildlog/ directory found. Run 'buildlog init' to extract skills."
+            )
+        return
 
     # Convert datetime to date if provided
     since_date = since.date() if since else None
@@ -935,7 +1149,7 @@ def status_cmd(min_confidence: str, output_json: bool):
     """Show extracted skills by category and confidence.
 
     Displays all skills extracted from buildlog entries, grouped by category,
-    with confidence levels and promotion status.
+    with confidence levels and promotion status. Returns empty state if not initialized.
 
     Examples:
 
@@ -948,9 +1162,23 @@ def status_cmd(min_confidence: str, output_json: bool):
 
     buildlog_dir = Path("buildlog")
 
+    # Handle uninitialized state gracefully
     if not buildlog_dir.exists():
-        click.echo("No buildlog/ directory found. Run 'buildlog init' first.", err=True)
-        raise SystemExit(1)
+        empty_result = {
+            "initialized": False,
+            "total_skills": 0,
+            "total_entries": 0,
+            "skills": {},
+            "by_confidence": {"high": 0, "medium": 0, "low": 0},
+            "promotable_ids": [],
+            "error": None,
+        }
+        if output_json:
+            click.echo(json_module.dumps(empty_result, indent=2))
+        else:
+            click.echo("Skills: 0 total from 0 entries")
+            click.echo("  buildlog not initialized. Run 'buildlog init' first.")
+        return
 
     result = status(buildlog_dir, min_confidence=min_confidence)  # type: ignore[arg-type]
 
@@ -1092,6 +1320,7 @@ def diff_cmd(output_json: bool):
     """Show skills pending review (not yet promoted or rejected).
 
     Useful for seeing what's new since the last time you reviewed skills.
+    Returns empty diff if not initialized.
 
     Examples:
 
@@ -1103,9 +1332,22 @@ def diff_cmd(output_json: bool):
 
     buildlog_dir = Path("buildlog")
 
+    # Handle uninitialized state gracefully
     if not buildlog_dir.exists():
-        click.echo("No buildlog/ directory found. Run 'buildlog init' first.", err=True)
-        raise SystemExit(1)
+        empty_result = {
+            "initialized": False,
+            "pending": {},
+            "total_pending": 0,
+            "already_promoted": 0,
+            "already_rejected": 0,
+            "error": None,
+        }
+        if output_json:
+            click.echo(json_module.dumps(empty_result, indent=2))
+        else:
+            click.echo("Pending: 0 | Promoted: 0 | Rejected: 0")
+            click.echo("  buildlog not initialized. Run 'buildlog init' first.")
+        return
 
     result = core_diff(buildlog_dir)