buildlog 0.5.0__py3-none-any.whl → 0.6.1__py3-none-any.whl

buildlog/cli.py

@@ -172,8 +172,8 @@ def new(slug: str, entry_date: str | None):
     click.echo(f"\nOpen it: $EDITOR {entry_path}")
 
 
-@main.command()
-def list():
+@main.command("list")
+def list_entries():
     """List all buildlog entries."""
     buildlog_dir = Path("buildlog")
 
@@ -182,7 +182,8 @@ def list():
         raise SystemExit(1)
 
     entries = sorted(
-        buildlog_dir.glob("20??-??-??-*.md"), reverse=True  # Most recent first
+        buildlog_dir.glob("20??-??-??-*.md"),
+        reverse=True,  # Most recent first
     )
 
     if not entries:
@@ -876,5 +877,392 @@ def experiment_report(output_json: bool):
                 )
 
 
+# -----------------------------------------------------------------------------
+# Gauntlet Commands (Review Personas)
+# -----------------------------------------------------------------------------
+
+PERSONAS = {
+    "security_karen": "OWASP Top 10 security review",
+    "test_terrorist": "Comprehensive testing coverage audit",
+    "ruthless_reviewer": "Code quality and functional principles",
+}
+
+
+@main.group()
+def gauntlet():
+    """Run the review gauntlet with curated personas.
+
+    The gauntlet runs your code through multiple ruthless reviewers,
+    each with domain-specific rules loaded from seed files.
+
+    Personas:
+      - security_karen: OWASP security review (12 rules)
+      - test_terrorist: Testing coverage audit (21 rules)
+      - ruthless_reviewer: Code quality review (coming soon)
+
+    Example workflow:
+
+        buildlog gauntlet list                    # See available personas
+        buildlog gauntlet rules --persona all    # Show all rules
+        buildlog gauntlet prompt src/            # Generate review prompt
+    """
+    pass
+
+
+@gauntlet.command("list")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+def gauntlet_list(output_json: bool):
+    """List available reviewer personas and their rule counts.
+
+    Examples:
+
+        buildlog gauntlet list
+        buildlog gauntlet list --json
+    """
+    import json as json_module
+
+    from buildlog.seeds import get_default_seeds_dir, load_all_seeds
+
+    # Find seeds directory (local overrides > buildlog template > package bundled)
+    seeds_dir = get_default_seeds_dir()
+
+    if seeds_dir is None:
+        if output_json:
+            click.echo('{"personas": {}, "total_rules": 0, "error": "No seeds found"}')
+        else:
+            click.echo("No seed files found.")
+            click.echo("Seeds are bundled with buildlog - check your installation.")
+        return
+
+    seeds = load_all_seeds(seeds_dir)
+
+    if output_json:
+        data = {
+            "personas": {
+                name: {
+                    "description": PERSONAS.get(name, "Custom persona"),
+                    "rules_count": len(sf.rules),
+                    "version": sf.version,
+                }
+                for name, sf in seeds.items()
+            },
+            "total_rules": sum(len(sf.rules) for sf in seeds.values()),
+        }
+        click.echo(json_module.dumps(data, indent=2))
+    else:
+        click.echo("Review Gauntlet Personas")
+        click.echo("=" * 50)
+
+        if not seeds:
+            click.echo("\nNo seed files found.")
+            click.echo("Initialize with: buildlog init")
+            click.echo("Or create seeds in: .buildlog/seeds/")
+            return
+
+        total = 0
+        for name, sf in sorted(seeds.items()):
+            desc = PERSONAS.get(name, "Custom persona")
+            click.echo(f"\n  {name}")
+            click.echo(f"    {desc}")
+            click.echo(f"    Rules: {len(sf.rules)} (v{sf.version})")
+            total += len(sf.rules)
+
+        click.echo(f"\nTotal: {len(seeds)} personas, {total} rules")
+
+
+@gauntlet.command("rules")
+@click.option(
+    "--persona",
+    "-p",
+    default="all",
+    help="Persona to show rules for (or 'all')",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["yaml", "json", "markdown"]),
+    default="yaml",
+    help="Output format",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output file")
+def gauntlet_rules(persona: str, fmt: str, output: str | None):
+    """Show rules for reviewer personas.
+
+    Use this to see what rules are loaded for each persona,
+    or export them for use in prompts.
+
+    Examples:
+
+        buildlog gauntlet rules                         # All rules (YAML)
+        buildlog gauntlet rules -p security_karen       # Single persona
+        buildlog gauntlet rules --format json -o rules.json
+        buildlog gauntlet rules --format markdown       # For docs
+    """
+    import json as json_module
+
+    from buildlog.seeds import get_default_seeds_dir, load_all_seeds
+
+    # Find seeds directory (local overrides > buildlog template > package bundled)
+    seeds_dir = get_default_seeds_dir()
+
+    if seeds_dir is None:
+        click.echo("No seed files found.", err=True)
+        click.echo(
+            "Seeds are bundled with buildlog - check your installation.", err=True
+        )
+        raise SystemExit(1)
+
+    seeds = load_all_seeds(seeds_dir)
+
+    if not seeds:
+        click.echo("No seed files found in directory.", err=True)
+        raise SystemExit(1)
+
+    # Filter personas
+    if persona != "all":
+        if persona not in seeds:
+            available = ", ".join(seeds.keys())
+            click.echo(f"Unknown persona: {persona}", err=True)
+            click.echo(f"Available: {available}", err=True)
+            raise SystemExit(1)
+        seeds = {persona: seeds[persona]}
+
+    # Build output data
+    if fmt == "json":
+        data = {}
+        for name, sf in seeds.items():
+            data[name] = {
+                "version": sf.version,
+                "rules": [
+                    {
+                        "rule": r.rule,
+                        "category": r.category,
+                        "context": r.context,
+                        "antipattern": r.antipattern,
+                        "rationale": r.rationale,
+                        "tags": r.tags,
+                        "references": [
+                            {"url": ref.url, "title": ref.title} for ref in r.references
+                        ],
+                    }
+                    for r in sf.rules
+                ],
+            }
+        formatted = json_module.dumps(data, indent=2)
+
+    elif fmt == "markdown":
+        lines = ["# Review Gauntlet Rules\n"]
+        for name, sf in seeds.items():
+            lines.append(f"## {name.replace('_', ' ').title()}\n")
+            lines.append(f"*{len(sf.rules)} rules, v{sf.version}*\n")
+            for i, r in enumerate(sf.rules, 1):
+                lines.append(f"### {i}. {r.rule}\n")
+                lines.append(f"**Category**: {r.category}  ")
+                lines.append(f"**Tags**: {', '.join(r.tags)}\n")
+                if r.context:
+                    lines.append(f"**When**: {r.context}\n")
+                if r.antipattern:
+                    lines.append(f"**Antipattern**: {r.antipattern}\n")
+                if r.rationale:
+                    lines.append(f"**Why**: {r.rationale}\n")
+                if r.references:
+                    lines.append("**References**:")
+                    for ref in r.references:
+                        lines.append(f"- [{ref.title}]({ref.url})")
+                lines.append("")
+        formatted = "\n".join(lines)
+
+    else:  # yaml
+        import yaml as yaml_module
+
+        data = {}
+        for name, sf in seeds.items():
+            data[name] = {
+                "version": sf.version,
+                "rules": [
+                    {
+                        "rule": r.rule,
+                        "category": r.category,
+                        "context": r.context,
+                        "antipattern": r.antipattern,
+                        "rationale": r.rationale,
+                        "tags": r.tags,
+                    }
+                    for r in sf.rules
+                ],
+            }
+        formatted = yaml_module.dump(data, default_flow_style=False, sort_keys=False)
+
+    # Output
+    if output:
+        output_path = Path(output)
+        output_path.write_text(formatted, encoding="utf-8")
+        total = sum(len(sf.rules) for sf in seeds.values())
+        click.echo(f"Wrote {total} rules to {output_path}")
+    else:
+        click.echo(formatted)
+
+
+@gauntlet.command("prompt")
+@click.argument("target", type=click.Path(exists=True))
+@click.option(
+    "--persona",
+    "-p",
+    multiple=True,
+    help="Personas to include (default: all)",
+)
+@click.option("--output", "-o", type=click.Path(), help="Output file")
+def gauntlet_prompt(target: str, persona: tuple[str, ...], output: str | None):
+    """Generate a review prompt for the gauntlet.
+
+    Creates a prompt with rules and target code that can be
+    used with Claude or another LLM to run a review.
+
+    Examples:
+
+        buildlog gauntlet prompt src/
+        buildlog gauntlet prompt src/api.py -p security_karen
+        buildlog gauntlet prompt . -o review_prompt.md
+    """
+    from buildlog.seeds import get_default_seeds_dir, load_all_seeds
+
+    # Find seeds directory (local overrides > buildlog template > package bundled)
+    seeds_dir = get_default_seeds_dir()
+
+    if seeds_dir is None:
+        click.echo("No seed files found.", err=True)
+        click.echo(
+            "Seeds are bundled with buildlog - check your installation.", err=True
+        )
+        raise SystemExit(1)
+
+    seeds = load_all_seeds(seeds_dir)
+
+    if not seeds:
+        click.echo("No seed files found in directory.", err=True)
+        raise SystemExit(1)
+
+    # Filter personas
+    if persona:
+        seeds = {k: v for k, v in seeds.items() if k in persona}
+        if not seeds:
+            click.echo(f"No matching personas: {', '.join(persona)}", err=True)
+            raise SystemExit(1)
+
+    # Build the prompt
+    target_path = Path(target)
+    lines = [
+        "# Review Gauntlet Prompt\n",
+        "You are running the Review Gauntlet. Apply these rules ruthlessly.\n",
+        "## Target\n",
+        f"Review: `{target_path}`\n",
+        "## Reviewers and Rules\n",
+    ]
+
+    for name, sf in seeds.items():
+        persona_name = name.replace("_", " ").title()
+        lines.append(f"### {persona_name}\n")
+        for r in sf.rules:
+            lines.append(f"- **{r.rule}**")
+            if r.antipattern:
+                lines.append(f"  - Antipattern: {r.antipattern}")
+        lines.append("")
+
+    lines.extend(
+        [
+            "## Output Format\n",
+            "For each issue found, output:\n",
+            "```json",
+            "{",
+            '  "reviewer": "<persona>",',
+            '  "severity": "critical|major|minor|nitpick",',
+            '  "category": "<category>",',
+            '  "location": "<file:line>",',
+            '  "description": "<what is wrong>",',
+            '  "rule_learned": "<generalizable rule>"',
+            "}",
+            "```\n",
+            "## Instructions\n",
+            "1. Read the target code thoroughly",
+            "2. Apply each rule from each reviewer",
+            "3. Report ALL violations found",
+            "4. Be ruthless - this is the gauntlet",
+            "",
+        ]
+    )
+
+    formatted = "\n".join(lines)
+
+    if output:
+        output_path = Path(output)
+        output_path.write_text(formatted, encoding="utf-8")
+        click.echo(f"Wrote prompt to {output_path}")
+    else:
+        click.echo(formatted)
+
+
+@gauntlet.command("learn")
+@click.argument("issues_file", type=click.Path(exists=True))
+@click.option("--source", "-s", help="Source identifier (e.g., 'gauntlet:PR#42')")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+def gauntlet_learn(issues_file: str, source: str | None, output_json: bool):
+    """Persist learnings from a gauntlet review.
+
+    Takes a JSON file of issues (in the gauntlet output format)
+    and calls learn_from_review to persist them.
+
+    Examples:
+
+        buildlog gauntlet learn review_issues.json
+        buildlog gauntlet learn issues.json --source "gauntlet:2026-01-22"
+    """
+    import json as json_module
+    from dataclasses import asdict
+
+    from buildlog.core import learn_from_review
+
+    buildlog_dir = Path("buildlog")
+
+    if not buildlog_dir.exists():
+        click.echo("No buildlog/ directory found. Run 'buildlog init' first.", err=True)
+        raise SystemExit(1)
+
+    # Load issues
+    try:
+        with open(issues_file) as f:
+            data = json_module.load(f)
+    except json_module.JSONDecodeError as e:
+        click.echo(f"Invalid JSON: {e}", err=True)
+        raise SystemExit(1)
+
+    # Handle different formats
+    if isinstance(data, list):
+        issues = data
+    elif isinstance(data, dict) and "all_issues" in data:
+        issues = data["all_issues"]
+    elif isinstance(data, dict) and "issues" in data:
+        issues = data["issues"]
+    else:
+        click.echo(
+            "Expected list of issues or dict with 'issues'/'all_issues'", err=True
+        )
+        raise SystemExit(1)
+
+    if not issues:
+        click.echo("No issues found in file.", err=True)
+        raise SystemExit(1)
+
+    # Learn from review
+    result = learn_from_review(buildlog_dir, issues, source=source or "gauntlet")
+
+    if output_json:
+        click.echo(json_module.dumps(asdict(result), indent=2))
+    else:
+        click.echo(f"✓ {result.message}")
+        click.echo(f"  New learnings: {result.new_learnings}")
+        click.echo(f"  Reinforced: {result.reinforced_learnings}")
+        click.echo(f"  Total processed: {result.total_issues_processed}")
+
+
 if __name__ == "__main__":
     main()

buildlog/data/seeds/security_karen.yaml

@@ -0,0 +1,162 @@
+# Security Karen - Curated Security Rules
+# Source: OWASP Top 10 (2021), CWE, security best practices
+# These rules are defensible - each links to authoritative sources
+
+persona: security_karen
+version: 1
+
+rules:
+  # A01:2021 - Broken Access Control
+  - rule: "Verify authorization on every privileged operation"
+    category: security
+    context: "Any endpoint or function that modifies data or accesses sensitive resources"
+    antipattern: "Checking authentication but not authorization; assuming authenticated = authorized"
+    rationale: "Broken access control is OWASP #1. Users can act outside intended permissions."
+    tags: [access-control, authorization, owasp-a01]
+    references:
+      - url: "https://owasp.org/Top10/A01_2021-Broken_Access_Control/"
+        title: "OWASP A01:2021 Broken Access Control"
+      - url: "https://cwe.mitre.org/data/definitions/862.html"
+        title: "CWE-862: Missing Authorization"
+
+  - rule: "Deny by default for access control decisions"
+    category: security
+    context: "Access control logic, permission checks, authorization middleware"
+    antipattern: "Allowing access unless explicitly denied; missing else clause in auth checks"
+    rationale: "Fail-open access control leads to unauthorized access. Fail-closed is safer."
+    tags: [access-control, authorization, defense-in-depth]
+    references:
+      - url: "https://owasp.org/Top10/A01_2021-Broken_Access_Control/"
+        title: "OWASP A01:2021 Broken Access Control"
+
+  # A02:2021 - Cryptographic Failures
+  - rule: "Never store passwords in plaintext or reversible encryption"
+    category: security
+    context: "User registration, password storage, credential management"
+    antipattern: "Storing raw passwords; using MD5/SHA1 without salt; using encryption instead of hashing"
+    rationale: "Password leaks expose users. Use bcrypt/argon2 with proper work factors."
+    tags: [cryptography, passwords, owasp-a02]
+    references:
+      - url: "https://owasp.org/Top10/A02_2021-Cryptographic_Failures/"
+        title: "OWASP A02:2021 Cryptographic Failures"
+      - url: "https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html"
+        title: "OWASP Password Storage Cheat Sheet"
+
+  - rule: "Use TLS 1.2+ for all data in transit"
+    category: security
+    context: "API calls, database connections, service-to-service communication"
+    antipattern: "HTTP endpoints; TLS 1.0/1.1; self-signed certs in production without pinning"
+    rationale: "Data in transit can be intercepted. TLS provides confidentiality and integrity."
+    tags: [cryptography, tls, owasp-a02]
+    references:
+      - url: "https://owasp.org/Top10/A02_2021-Cryptographic_Failures/"
+        title: "OWASP A02:2021 Cryptographic Failures"
+
+  # A03:2021 - Injection
+  - rule: "Parameterize all database queries"
+    category: security
+    context: "Any code constructing SQL, NoSQL, LDAP, or OS commands from input"
+    antipattern: "String concatenation with user input; f-strings in queries; raw SQL with variables"
+    rationale: "SQL injection allows data theft, modification, or deletion. Parameterization prevents it."
+    tags: [injection, sql, owasp-a03]
+    references:
+      - url: "https://owasp.org/Top10/A03_2021-Injection/"
+        title: "OWASP A03:2021 Injection"
+      - url: "https://cwe.mitre.org/data/definitions/89.html"
+        title: "CWE-89: SQL Injection"
+
+  - rule: "Escape or sanitize all output to prevent XSS"
+    category: security
+    context: "Rendering user-provided content in HTML, JavaScript, or other executable contexts"
+    antipattern: "innerHTML with user data; dangerouslySetInnerHTML; template literals without escaping"
+    rationale: "XSS allows attackers to execute code in users' browsers. Always escape output."
+    tags: [injection, xss, owasp-a03]
+    references:
+      - url: "https://owasp.org/Top10/A03_2021-Injection/"
+        title: "OWASP A03:2021 Injection"
+      - url: "https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html"
+        title: "OWASP XSS Prevention Cheat Sheet"
+
+  # A04:2021 - Insecure Design
+  - rule: "Implement rate limiting on authentication endpoints"
+    category: security
+    context: "Login, registration, password reset, API authentication"
+    antipattern: "Unlimited login attempts; no lockout; no CAPTCHA on repeated failures"
+    rationale: "Credential stuffing and brute force attacks are common. Rate limiting mitigates them."
+    tags: [authentication, rate-limiting, owasp-a04]
+    references:
+      - url: "https://owasp.org/Top10/A04_2021-Insecure_Design/"
+        title: "OWASP A04:2021 Insecure Design"
+      - url: "https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html"
+        title: "OWASP Authentication Cheat Sheet"
+
+  # A05:2021 - Security Misconfiguration
+  - rule: "Never commit secrets to version control"
+    category: security
+    context: "Any code or configuration file that might contain API keys, passwords, tokens"
+    antipattern: "Hardcoded credentials; .env files in git; secrets in docker-compose.yml"
+    rationale: "Git history is forever. Leaked secrets lead to account compromise."
+    tags: [secrets, configuration, owasp-a05]
+    references:
+      - url: "https://owasp.org/Top10/A05_2021-Security_Misconfiguration/"
+        title: "OWASP A05:2021 Security Misconfiguration"
+
+  - rule: "Disable debug mode and verbose errors in production"
+    category: security
+    context: "Production deployments, error handling, logging configuration"
+    antipattern: "DEBUG=True in production; stack traces in API responses; verbose SQL errors"
+    rationale: "Debug info reveals implementation details useful for attackers."
+    tags: [configuration, errors, owasp-a05]
+    references:
+      - url: "https://owasp.org/Top10/A05_2021-Security_Misconfiguration/"
+        title: "OWASP A05:2021 Security Misconfiguration"
+
+  # A07:2021 - Identification and Authentication Failures
+  - rule: "Use secure session management with httpOnly and secure flags"
+    category: security
+    context: "Session cookies, JWT storage, authentication tokens"
+    antipattern: "Tokens in localStorage; cookies without httpOnly; missing secure flag"
+    rationale: "Insecure session storage enables session hijacking via XSS."
+    tags: [authentication, sessions, owasp-a07]
+    references:
+      - url: "https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/"
+        title: "OWASP A07:2021 Identification and Authentication Failures"
+      - url: "https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html"
+        title: "OWASP Session Management Cheat Sheet"
+
+  # A08:2021 - Software and Data Integrity Failures
+  - rule: "Verify integrity of external dependencies"
+    category: security
+    context: "Package installation, CI/CD pipelines, dependency updates"
+    antipattern: "No lockfile; no hash verification; installing from arbitrary URLs"
+    rationale: "Supply chain attacks inject malicious code via dependencies."
+    tags: [dependencies, supply-chain, owasp-a08]
+    references:
+      - url: "https://owasp.org/Top10/A08_2021-Software_and_Data_Integrity_Failures/"
+        title: "OWASP A08:2021 Software and Data Integrity Failures"
+
+  # A09:2021 - Security Logging and Monitoring Failures
+  - rule: "Log security-relevant events with sufficient context"
+    category: security
+    context: "Authentication, authorization failures, input validation failures"
+    antipattern: "No logging; logging without timestamps; no user/IP context; PII in logs"
+    rationale: "Without logs, breaches go undetected. Logs enable incident response."
+    tags: [logging, monitoring, owasp-a09]
+    references:
+      - url: "https://owasp.org/Top10/A09_2021-Security_Logging_and_Monitoring_Failures/"
+        title: "OWASP A09:2021 Security Logging and Monitoring Failures"
+      - url: "https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html"
+        title: "OWASP Logging Cheat Sheet"
+
+  # A10:2021 - Server-Side Request Forgery (SSRF)
+  - rule: "Validate and allowlist URLs for server-side requests"
+    category: security
+    context: "Fetching external URLs, webhooks, image proxies, URL shorteners"
+    antipattern: "Fetching arbitrary user-provided URLs; no protocol/host validation"
+    rationale: "SSRF allows attackers to access internal services or cloud metadata."
+    tags: [ssrf, input-validation, owasp-a10]
+    references:
+      - url: "https://owasp.org/Top10/A10_2021-Server-Side_Request_Forgery_%28SSRF%29/"
+        title: "OWASP A10:2021 SSRF"
+      - url: "https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html"
+        title: "OWASP SSRF Prevention Cheat Sheet"