buildlog 0.9.0__py3-none-any.whl → 0.10.1__py3-none-any.whl

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,161 @@ 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, also writes usage instructions to ~/.claude/CLAUDE.md
+    """
+    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"] = {}
+
+        mcp_already_registered = "buildlog" in data["mcpServers"]
+
+        if not mcp_already_registered:
+            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}")
+        else:
+            click.echo(f"buildlog MCP server already registered in {location}")
+
+        # In global mode, also write/update ~/.claude/CLAUDE.md with usage instructions
+        if global_mode:
+            _init_global_claude_md(settings_path.parent)
+            click.echo(
+                "Claude Code now has buildlog tools + instructions in all projects."
+            )
+
+    except Exception as e:
+        click.echo(f"Warning: could not register MCP server: {e}", err=True)
+
+
+def _init_global_claude_md(claude_dir: Path) -> None:
+    """Write buildlog usage instructions to ~/.claude/CLAUDE.md.
+
+    Creates or appends to the global CLAUDE.md so Claude knows how to use
+    buildlog tools automatically in any project.
+    """
+    from buildlog.constants import CLAUDE_MD_GLOBAL_SECTION
+
+    claude_md_path = claude_dir / "CLAUDE.md"
+
+    try:
+        if claude_md_path.exists():
+            content = claude_md_path.read_text()
+            # Check if buildlog section already exists
+            if "## buildlog" in content:
+                click.echo("buildlog instructions already in ~/.claude/CLAUDE.md")
+                return
+            # Append to existing file
+            with open(claude_md_path, "a") as f:
+                f.write(CLAUDE_MD_GLOBAL_SECTION)
+            click.echo("Added buildlog instructions to ~/.claude/CLAUDE.md")
+        else:
+            # Create new file with header
+            header = "# Global Claude Instructions\n\nThese instructions apply to all projects.\n"
+            claude_md_path.write_text(header + CLAUDE_MD_GLOBAL_SECTION)
+            click.echo("Created ~/.claude/CLAUDE.md with buildlog instructions")
+    except Exception as e:
+        click.echo(f"Warning: could not write CLAUDE.md: {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 +325,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 +404,7 @@ def overview(output_json: bool):
     from buildlog.render import RENDERERS
 
     result = {
+        "initialized": True,
         "entries": len(entries),
         "skills": {
             "total": total_skills,
@@ -586,7 +783,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 +793,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 +862,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 +871,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 +954,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 +971,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 +1185,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 +1198,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 +1356,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 +1368,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)
 

buildlog/constants.py

@@ -0,0 +1,160 @@
+"""Shared constants for buildlog, including the CLAUDE.md integration section."""
+
+# Shorter version for global ~/.claude/CLAUDE.md - focused on "always on" usage
+CLAUDE_MD_GLOBAL_SECTION = """
+## buildlog (Always On)
+
+buildlog is your ambient data capture layer. It runs in ALL projects via MCP.
+Use these tools to track work, extract learnings, and feed downstream systems.
+
+### Core Loop (use after every significant commit)
+
+1. `buildlog_overview()` — check project state
+2. `buildlog_commit(message="...")` — git commit with auto entry logging
+3. `buildlog_gauntlet_rules()` + review + `buildlog_gauntlet_issues([...])` — run gauntlet
+4. `buildlog_log_reward(outcome="accepted")` — close the feedback loop
+
+### Key Tools
+
+| Tool | When to Use |
+|------|-------------|
+| `buildlog_overview()` | Start of session, check state |
+| `buildlog_commit(message)` | Wrap git commits with logging |
+| `buildlog_entry_new(slug)` | Create journal entry |
+| `buildlog_gauntlet_rules()` | Load reviewer personas |
+| `buildlog_gauntlet_issues(issues)` | Process review findings |
+| `buildlog_log_reward(outcome)` | Feedback after approval |
+| `buildlog_skills()` | Extract patterns from entries |
+| `buildlog_status()` | See extracted skills |
+| `buildlog_promote(skill_ids)` | Surface to agent rules |
+
+### Outputs (ambient capture for downstream)
+
+- Journal entries: `buildlog/*.md`
+- Reward signals: `buildlog/.buildlog/reward_events.jsonl`
+- Extracted skills: `buildlog/.buildlog/promoted.json`
+- Review learnings: `buildlog/.buildlog/review_learnings.json`
+
+This data feeds automated content generation, engineering logs, and learning systems.
+"""
+
+# Full version for per-project CLAUDE.md - comprehensive reference
+CLAUDE_MD_BUILDLOG_SECTION = """
+## buildlog Integration
+
+buildlog is configured as an MCP server. Use the tools below to maintain
+a learning loop: write entries, extract skills, run gauntlet reviews, and
+track experiments.
+
+### Always On: Commit -> Gauntlet -> Learn Loop
+
+After every significant commit or feature completion:
+
+1. **Create/update entry**: `buildlog_entry_new(slug="what-you-built")`
+2. **Run gauntlet review**: `buildlog_gauntlet_rules()` to load rules, then review code against them
+3. **Process findings**: `buildlog_gauntlet_issues(issues=[...])` to categorize and persist learnings
+4. **Fix criticals/majors**, re-run until clean or accept risk: `buildlog_gauntlet_accept_risk(remaining_issues=[...])`
+5. **Log reward**: `buildlog_log_reward(outcome="accepted")` when work is approved
+
+### Skill Extraction & Promotion Workflow
+
+1. `buildlog_status()` — see extracted skills by category
+2. `buildlog_diff()` — see skills pending review
+3. `buildlog_promote(skill_ids=[...], target="claude_md")` — surface to agent rules
+4. `buildlog_reject(skill_ids=[...])` — mark false positives
+
+### Gauntlet Review Loop Workflow
+
+1. `buildlog_gauntlet_rules()` — load reviewer persona rules
+2. Review code against rules, collect issues
+3. `buildlog_gauntlet_issues(issues=[...])` — categorize, persist learnings, get next action
+4. If action="fix_criticals": fix and re-run
+5. If action="checkpoint_majors"/"checkpoint_minors": ask user
+6. `buildlog_gauntlet_accept_risk(remaining_issues=[...])` — accept remaining
+7. `buildlog_learn_from_review(issues=[...])` — persist learnings
+
+### Reward Signal / Thompson Sampling Workflow
+
+1. `buildlog_log_reward(outcome="accepted"|"revision"|"rejected")` — explicit feedback
+2. `buildlog_rewards()` — view reward history and statistics
+3. `buildlog_bandit_status()` — see which rules the bandit favors
+
+### Session Tracking & Experiment Workflow
+
+1. `buildlog_experiment_start(error_class="missing_test")` — begin tracked session
+2. `buildlog_log_mistake(error_class="...", description="...")` — log mistakes
+3. `buildlog_experiment_end()` — end session, calculate metrics
+4. `buildlog_experiment_metrics()` — per-session or aggregate stats
+5. `buildlog_experiment_report()` — comprehensive report
+
+### Tool Reference (29 tools)
+
+**Commit & Entries:**
+- `buildlog_commit(message, git_args, slug, no_entry)` — git commit with auto buildlog entry
+- `buildlog_entry_new(slug, entry_date, quick)` — create entry
+- `buildlog_entry_list()` — list all entries
+- `buildlog_overview()` — project state at a glance
+
+**Skill Management:**
+- `buildlog_status(min_confidence="low")` — extracted skills
+- `buildlog_promote(skill_ids, target="claude_md")` — promote to agent rules
+- `buildlog_reject(skill_ids)` — reject false positives
+- `buildlog_diff()` — pending skills
+- `buildlog_distill(since, category)` — extract patterns from entries
+- `buildlog_skills(since, min_frequency)` — generate skill set from entries
+- `buildlog_stats(since, detailed)` — buildlog statistics and insights
+
+**Gauntlet Review:**
+- `buildlog_gauntlet_prompt(target, personas)` — generate review prompt with rules
+- `buildlog_gauntlet_loop(target, personas, max_iterations, stop_at, auto_gh_issues)` — full loop config
+- `buildlog_gauntlet_rules(persona, format)` — load reviewer rules
+- `buildlog_gauntlet_issues(issues, iteration)` — process findings
+- `buildlog_gauntlet_accept_risk(remaining_issues)` — accept risk
+- `buildlog_gauntlet_list_personas()` — list available reviewer personas
+- `buildlog_gauntlet_generate(source_text, persona, dry_run)` — generate rules from source text
+
+**Review Learning:**
+- `buildlog_learn_from_review(issues, source)` — persist review learnings
+
+**Reward & Bandit:**
+- `buildlog_log_reward(outcome, rules_active)` — log feedback
+- `buildlog_rewards(limit)` — reward history
+- `buildlog_bandit_status(context)` — bandit state
+
+**Experiments:**
+- `buildlog_experiment_start(error_class)` — start session
+- `buildlog_experiment_end()` — end session
+- `buildlog_log_mistake(error_class, description)` — log mistake
+- `buildlog_experiment_metrics(session_id)` — metrics
+- `buildlog_experiment_report()` — full report
+
+**Project Setup:**
+- `buildlog_init(no_mcp, no_claude_md)` — initialize buildlog in project
+- `buildlog_update()` — update buildlog template to latest
+
+### When to Use Each Tool
+
+- **At session start**: `buildlog_overview()` for context
+- **During active dev**: `buildlog_entry_new()` to document work
+- **After commits**: `buildlog_commit()` or `buildlog_gauntlet_prompt()` + review + `buildlog_gauntlet_issues()`
+- **After review approval**: `buildlog_log_reward(outcome="accepted")`
+- **For learning**: `buildlog_distill()`, `buildlog_skills()`, `buildlog_stats()`
+- **For skill promotion**: `buildlog_status()` -> `buildlog_diff()` -> `buildlog_promote()`
+- **To accept risk**: `buildlog_gauntlet_accept_risk()`
+- **For experiments**: `buildlog_experiment_start()` -> work -> `buildlog_experiment_end()`
+
+### Integration with Commits
+
+`buildlog commit -m "message"` wraps git commit and auto-logs to today's entry.
+
+### Reference Files
+
+- `buildlog/.buildlog/promoted.json` — promoted skill IDs
+- `buildlog/.buildlog/rejected.json` — rejected skill IDs
+- `buildlog/.buildlog/review_learnings.json` — review-based learnings
+- `buildlog/.buildlog/reward_events.jsonl` — reward signals
+- `buildlog/.buildlog/sessions.jsonl` — session tracking
+- `buildlog/.buildlog/mistakes.jsonl` — mistake tracking
+- `buildlog/.buildlog/active_session.json` — current session
+- `buildlog/bandit_state.jsonl` — Thompson Sampling state
+"""