buildlog 0.8.0__py3-none-any.whl → 0.10.0__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,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,
@@ -298,11 +459,11 @@ def new(slug: str, entry_date: str | None, quick: bool):
     # Determine date
     if entry_date:
         try:
-            # Validate date format
-            year, month, day = entry_date.split("-")
-            date_str = f"{int(year):04d}-{int(month):02d}-{int(day):02d}"
+            # Validate date format AND range (month 1-12, day 1-31)
+            parsed = datetime.strptime(entry_date, "%Y-%m-%d").date()
+            date_str = parsed.isoformat()
         except ValueError:
-            click.echo("Invalid date format. Use YYYY-MM-DD.", err=True)
+            click.echo("Invalid date. Use YYYY-MM-DD with valid values.", err=True)
             raise SystemExit(1)
     else:
         date_str = date.today().isoformat()
@@ -331,6 +492,161 @@ def new(slug: str, entry_date: str | None, quick: bool):
     click.echo(f"\nOpen it: $EDITOR {entry_path}")
 
 
+@main.command(
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True}
+)
+@click.option(
+    "--slug",
+    "-s",
+    default=None,
+    help="Entry slug (default: derived from branch name)",
+)
+@click.option(
+    "--entry",
+    "-e",
+    type=click.Path(),
+    default=None,
+    help="Explicit entry file to append to",
+)
+@click.option(
+    "--no-entry",
+    is_flag=True,
+    help="Skip buildlog entry update (just run git commit)",
+)
+@click.pass_context
+def commit(ctx, slug: str | None, entry: str | None, no_entry: bool):
+    """Commit code and update the buildlog entry in one step.
+
+    Wraps `git commit` and appends commit context to today's buildlog
+    entry. If no entry exists for today, creates one automatically.
+
+    All unknown options/arguments are passed through to git commit.
+
+    Examples:
+
+        buildlog commit -m "feat: add LLM extractor"
+        buildlog commit --slug llm-extractor -m "feat: add LLM extractor"
+        buildlog commit --no-entry -m "chore: formatting"
+    """
+    buildlog_dir = Path("buildlog")
+
+    # Build git commit command — extra args are passed through from Click context
+    git_cmd = ["git", "commit", *ctx.args]
+
+    # Run git commit first
+    result = subprocess.run(git_cmd, capture_output=True, text=True)
+    sys.stdout.write(result.stdout)
+    sys.stderr.write(result.stderr)
+
+    if result.returncode != 0:
+        raise SystemExit(result.returncode)
+
+    if no_entry or not buildlog_dir.exists():
+        return
+
+    # Get commit info from what we just committed
+    try:
+        commit_hash = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        commit_msg = subprocess.run(
+            ["git", "log", "-1", "--format=%s"],
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        # diff-tree needs special handling for root commit
+        diff_result = subprocess.run(
+            ["git", "diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD"],
+            capture_output=True,
+            text=True,
+        )
+        if diff_result.returncode == 0 and diff_result.stdout.strip():
+            files_changed = diff_result.stdout.strip()
+        else:
+            # Root commit fallback
+            files_changed = subprocess.run(
+                ["git", "diff", "--name-only", "--cached", "HEAD~1"],
+                capture_output=True,
+                text=True,
+            ).stdout.strip()
+            if not files_changed:
+                # Truly initial commit — list all tracked files
+                files_changed = subprocess.run(
+                    ["git", "ls-tree", "--name-only", "-r", "HEAD"],
+                    capture_output=True,
+                    text=True,
+                ).stdout.strip()
+    except subprocess.CalledProcessError:
+        click.echo("Warning: could not read commit info", err=True)
+        return
+
+    # Resolve entry file
+    today = date.today().isoformat()
+    entry_path = _resolve_entry_path(buildlog_dir, today, slug, entry)
+
+    # Append commit block
+    commit_block = f"\n### `{commit_hash}` — {commit_msg}\n\n"
+    if files_changed:
+        file_list = files_changed.split("\n")
+        commit_block += "Files:\n"
+        for f in file_list[:20]:  # cap at 20 to avoid noise
+            commit_block += f"- `{f}`\n"
+        if len(file_list) > 20:
+            commit_block += f"- ...and {len(file_list) - 20} more\n"
+    commit_block += "\n"
+
+    # Ensure commits section exists, append to it
+    if entry_path.exists():
+        content = entry_path.read_text()
+        if "## Commits" not in content:
+            content = content.rstrip() + "\n\n## Commits\n"
+        content += commit_block
+    else:
+        # Auto-create minimal entry
+        content = f"# {today}\n\n## Commits\n{commit_block}"
+
+    entry_path.write_text(content)
+    click.echo(f"buildlog: updated {entry_path}")
+
+
+def _resolve_entry_path(
+    buildlog_dir: Path, today: str, slug: str | None, explicit: str | None
+) -> Path:
+    """Find or create the entry path for today."""
+    if explicit:
+        return Path(explicit)
+
+    # Check for existing entry with today's date
+    existing = list(buildlog_dir.glob(f"{today}-*.md"))
+    if existing:
+        return existing[0]
+
+    # Derive slug from branch name if not provided
+    if slug is None:
+        try:
+            branch = subprocess.run(
+                ["git", "branch", "--show-current"],
+                capture_output=True,
+                text=True,
+                check=True,
+            ).stdout.strip()
+            # Clean branch name into slug
+            slug = branch.split("/")[-1]  # strip prefix like feat/
+            slug = slug.lower().replace("_", "-")
+            slug = "".join(c for c in slug if c.isalnum() or c == "-")
+        except subprocess.CalledProcessError:
+            slug = "session"
+
+    if not slug:
+        slug = "session"
+
+    return buildlog_dir / f"{today}-{slug}.md"
+
+
 @main.command("list")
 def list_entries():
     """List all buildlog entries."""
@@ -431,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:
 
@@ -441,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
@@ -496,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:
 
@@ -504,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
@@ -571,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:
 
@@ -588,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
@@ -780,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:
 
@@ -793,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]
 
@@ -937,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:
 
@@ -948,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)
 
@@ -1277,6 +1674,7 @@ PERSONAS = {
     "security_karen": "OWASP Top 10 security review",
     "test_terrorist": "Comprehensive testing coverage audit",
     "ruthless_reviewer": "Code quality and functional principles",
+    "bragi": "Detect and flag LLM-ish prose patterns in markdown",
 }
 
 
@@ -1656,6 +2054,69 @@ def gauntlet_learn(issues_file: str, source: str | None, output_json: bool):
         click.echo(f"  Total processed: {result.total_issues_processed}")
 
 
+@gauntlet.command("generate")
+@click.argument("source_text", type=click.Path(exists=True))
+@click.option("--persona", "-p", required=True, help="Persona name for the seed file")
+@click.option(
+    "--output-dir",
+    "-o",
+    type=click.Path(),
+    default=".buildlog/seeds",
+    help="Output directory for seed YAML",
+)
+@click.option("--dry-run", is_flag=True, help="Preview without writing")
+def gauntlet_generate(source_text: str, persona: str, output_dir: str, dry_run: bool):
+    """Generate seed rules from source text using LLM extraction.
+
+    Runs the seed engine pipeline with LLMExtractor to produce
+    a YAML seed file from arbitrary source content.
+
+    Examples:
+
+        buildlog gauntlet generate docs/security.md --persona security_karen
+        buildlog gauntlet generate notes.txt -p test_terrorist --dry-run
+    """
+    import json as json_module
+
+    from buildlog.llm import get_llm_backend
+    from buildlog.seed_engine import Pipeline, Source, SourceType
+
+    backend = get_llm_backend()
+    if backend is None:
+        click.echo(
+            "No LLM backend available. Install ollama or set ANTHROPIC_API_KEY.",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    content = Path(source_text).read_text()
+    source = Source(
+        name=Path(source_text).stem,
+        url=f"file://{Path(source_text).resolve()}",
+        source_type=SourceType.REFERENCE_DOC,
+        domain=persona.split("_")[0] if "_" in persona else "general",
+        description=content,
+    )
+
+    pipeline = Pipeline.with_llm(
+        persona=persona,
+        backend=backend,
+        source_content={source.url: content},
+    )
+
+    if dry_run:
+        preview = pipeline.dry_run([source])
+        click.echo(json_module.dumps(preview, indent=2))
+        return
+
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    result = pipeline.run([source], output_dir=out)
+    click.echo(f"Generated {result.rule_count} rules for {persona}")
+    if result.output_path:
+        click.echo(f"Seed file: {result.output_path}")
+
+
 @gauntlet.command("loop")
 @click.argument("target", type=click.Path(exists=True))
 @click.option(