llmsbrieftxt 1.4.0__tar.gz → 1.11.0__tar.gz

llmsbrieftxt-1.11.0/.github/workflows/claude-cli-qa.yml

@@ -0,0 +1,296 @@
+name: Claude CLI QA Tests
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: [main]
+    paths:
+      - 'llmsbrieftxt/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/claude-cli-qa.yml'
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch to test (leave empty for current branch)'
+        required: false
+        type: string
+      test_scope:
+        description: 'Test scope (quick, standard, thorough)'
+        required: false
+        default: 'standard'
+        type: choice
+        options:
+          - quick
+          - standard
+          - thorough
+      single_test_case:
+        description: 'Run single test case (e.g., TS-001). Leave empty to run full test scope.'
+        required: false
+        type: choice
+        options:
+          - ''
+          - TS-001
+          - TS-002
+          - TS-003
+          - TS-004A
+          - TS-004B
+          - TS-005
+          - TS-006
+          - TS-007
+          - TS-008
+          - TS-009
+          - TS-010
+          - TS-011
+          - TS-012
+
+jobs:
+  cli-qa-tests:
+    name: Agent-Based CLI QA
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: read
+      id-token: write
+    env:
+      OLLAMA_MODEL: gemma3:270m
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.branch || github.head_ref || github.ref }}
+          fetch-depth: 1
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Install package with dependencies
+        run: |
+          uv sync --all-groups
+
+      - name: Install Ollama
+        run: |
+          echo "Installing Ollama for local LLM testing..."
+          curl -fsSL https://ollama.com/install.sh | sh
+
+          # Verify installation
+          ollama --version
+
+      - name: Start Ollama service
+        run: |
+          echo "Starting Ollama service..."
+          ollama serve > ollama.log 2>&1 &
+          echo $! > ollama.pid
+
+          # Wait for Ollama to be ready
+          echo "Waiting for Ollama to be ready..."
+          timeout 60 bash -c 'until curl -s http://localhost:11434/api/tags > /dev/null; do sleep 2; done'
+
+          echo "✓ Ollama service is running"
+
+      - name: Pull Ollama model
+        run: |
+          echo "Pulling ${{ env.OLLAMA_MODEL }} model for testing..."
+          ollama pull ${{ env.OLLAMA_MODEL }}
+
+          echo "✓ Model pulled successfully"
+
+      - name: Verify Ollama setup
+        run: |
+          echo "Verifying Ollama models..."
+          ollama list
+
+          echo "✓ Model ready"
+
+      - name: Verify CLI installation
+        run: |
+          # Ensure CLI is accessible
+          uv run llmtxt --help
+
+          echo "✓ CLI installed and accessible"
+
+      - name: Determine test scope
+        id: test-scope
+        run: |
+          SCOPE="${{ github.event.inputs.test_scope || 'standard' }}"
+          echo "scope=$SCOPE" >> $GITHUB_OUTPUT
+
+          case "$SCOPE" in
+            quick)
+              echo "max_urls=2" >> $GITHUB_OUTPUT
+              echo "depth=1" >> $GITHUB_OUTPUT
+              ;;
+            thorough)
+              echo "max_urls=5" >> $GITHUB_OUTPUT
+              echo "depth=1" >> $GITHUB_OUTPUT
+              ;;
+            *)
+              echo "max_urls=3" >> $GITHUB_OUTPUT
+              echo "depth=1" >> $GITHUB_OUTPUT
+              ;;
+          esac
+
+      - name: Determine test argument
+        id: test-arg
+        run: |
+          # If single test case is specified, use that; otherwise use test scope
+          if [ -n "${{ github.event.inputs.single_test_case }}" ]; then
+            echo "arg=${{ github.event.inputs.single_test_case }}" >> $GITHUB_OUTPUT
+          else
+            # Default to 'standard' for PR events, or use the specified scope
+            SCOPE="${{ github.event.inputs.test_scope || 'standard' }}"
+            echo "arg=$SCOPE" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run Claude CLI QA Agent
+        id: claude-cli-qa
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Allow Claude bot to trigger this workflow
+          allowed_bots: '*'
+
+          # Use Haiku model for faster/cheaper testing
+          claude_args: |
+            --model claude-haiku-4-5-20251001
+            --allowedTools "Bash,Read,Write,Glob,Grep,TodoWrite,Task,SlashCommand"
+
+          # Enable progress tracking for PR events only
+          track_progress: ${{ github.event_name == 'pull_request' }}
+
+          # Show full output in workflow logs for debugging
+          show_full_output: true
+
+          prompt: |
+            Run the QA test suite using the slash command: /qa-test ${{ steps.test-arg.outputs.arg }}
+
+      - name: Validate test execution
+        id: validate-tests
+        if: always()
+        run: |
+          echo "=== Validating CLI QA Test Results ==="
+
+          # Check if CLI is accessible via uv run
+          if ! uv run llmtxt --help &> /dev/null; then
+            echo "❌ ERROR: llmtxt CLI not accessible via 'uv run'"
+            exit 1
+          fi
+
+          echo "✅ CLI validation passed (accessible via 'uv run llmtxt')"
+
+      - name: Evaluate test results
+        id: evaluate-results
+        if: always()
+        run: |
+          echo "=== Evaluating Test Results ==="
+
+          # Check Claude agent execution status
+          if [ "${{ steps.claude-cli-qa.outcome }}" = "failure" ]; then
+            echo "❌ Claude QA agent failed to complete"
+            echo "status=failure" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          # Parse output for test failures (these patterns match the prompt output)
+          CLAUDE_OUTPUT="${{ steps.claude-cli-qa.outputs.text }}"
+
+          # Check for critical failures in output
+          if echo "$CLAUDE_OUTPUT" | grep -q "NO-GO\|❌ FAIL\|CRITICAL"; then
+            echo "❌ Test failures detected in QA results"
+            echo "status=failure" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          # Check for test summary with failures
+          if echo "$CLAUDE_OUTPUT" | grep -q "FAIL.*\|Failed:.*[1-9]"; then
+            echo "⚠️  Some tests failed but not critical - checking severity"
+            if echo "$CLAUDE_OUTPUT" | grep -q "Exit Code Bug\|returns exit code 0\|CRITICAL"; then
+              echo "❌ Critical test failures detected"
+              echo "status=failure" >> $GITHUB_OUTPUT
+              exit 1
+            fi
+          fi
+
+          echo "✅ All critical tests passed"
+          echo "status=success" >> $GITHUB_OUTPUT
+
+      - name: Generate test summary
+        if: always()
+        env:
+          CLAUDE_STATUS: ${{ steps.claude-cli-qa.outcome }}
+          EVALUATION_STATUS: ${{ steps.evaluate-results.outputs.status }}
+          GITHUB_SERVER_URL: ${{ github.server_url }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_RUN_ID: ${{ github.run_id }}
+        run: |
+          cat <<'EOF' >> $GITHUB_STEP_SUMMARY
+          ## llmtxt CLI QA Test Summary
+
+          **Test Mode**: ${{ github.event.inputs.single_test_case != '' && format('🔍 Single Test (Troubleshooting) - {0}', github.event.inputs.single_test_case) || format('📦 Full Test Suite - {0}', steps.test-arg.outputs.arg) }}
+          **Status**: ${{ steps.evaluate-results.outputs.status == 'success' && '✅ All Tests Passed' || '❌ Tests Failed' }}
+
+          ### Environment
+          - Python: 3.11
+          - Package Manager: uv
+          - LLM Provider: Ollama (${{ env.OLLAMA_MODEL }})
+          - Max URLs: ${{ steps.test-scope.outputs.max_urls }}
+          - Crawl Depth: ${{ steps.test-scope.outputs.depth }}
+
+          ### Test Categories
+          - Basic Functionality Tests
+          - CLI Flags and Options Tests
+          - Cache Behavior Tests
+          - Error Handling Tests
+          - Output Format Validation
+
+          ### Results
+          ${{ github.event.inputs.single_test_case != '' && format('The CLI QA agent executed test case **{0}** for troubleshooting.', github.event.inputs.single_test_case) || 'The CLI QA agent executed comprehensive tests using the `cli-qa-tester` agent.' }}
+          Detailed test report and findings are available in the workflow logs.
+
+          **View full logs**: [${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+
+          ---
+
+          🤖 **Agent-Based Testing**: This workflow uses Claude Code agents to perform intelligent,
+          adaptive CLI testing without traditional E2E test frameworks.
+          EOF
+
+      - name: Upload test artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: cli-qa-artifacts
+          path: |
+            ~/.claude/docs/
+            .llmsbrieftxt_cache/
+            ollama.log
+            **/test-*.txt
+            **/test-*.log
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Fail workflow if tests failed
+        if: always() && steps.evaluate-results.outputs.status == 'failure'
+        run: |
+          echo "❌ CLI QA tests have critical failures - blocking PR"
+          exit 1
+
+      - name: Cleanup
+        if: always()
+        run: |
+          if [ -f ollama.pid ]; then
+            kill $(cat ollama.pid) || true
+          fi
+          echo "✓ Cleanup complete"

llmsbrieftxt-1.11.0/.github/workflows/claude-doc-review.yml

@@ -0,0 +1,296 @@
+name: Documentation Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    branches: [main]
+
+jobs:
+  doc-review:
+    name: Agent-Based Documentation Review
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Need full history to compare changes
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            llmsbrieftxt/**/*.py
+            tests/**/*.py
+            pyproject.toml
+          files_ignore: |
+            **/__pycache__/**
+            **/*.pyc
+            .git/**
+
+      - name: Get documentation files
+        id: doc-files
+        uses: tj-actions/changed-files@v44
+        with:
+          files: |
+            README.md
+            CLAUDE.md
+            docs/**/*.md
+            **/*.md
+
+      - name: Check if documentation review needed
+        id: check-review
+        run: |
+          CODE_CHANGED="${{ steps.changed-files.outputs.any_changed }}"
+          DOCS_CHANGED="${{ steps.doc-files.outputs.any_changed }}"
+
+          echo "code_changed=$CODE_CHANGED" >> $GITHUB_OUTPUT
+          echo "docs_changed=$DOCS_CHANGED" >> $GITHUB_OUTPUT
+
+          if [ "$CODE_CHANGED" == "true" ]; then
+            echo "review_needed=true" >> $GITHUB_OUTPUT
+            if [ "$DOCS_CHANGED" == "true" ]; then
+              echo "review_type=validate" >> $GITHUB_OUTPUT
+              echo "📝 Code and documentation changed - will validate accuracy"
+            else
+              echo "review_type=check_missing" >> $GITHUB_OUTPUT
+              echo "⚠️  Code changed but no documentation updates - will check if updates needed"
+            fi
+          else
+            echo "review_needed=false" >> $GITHUB_OUTPUT
+            echo "ℹ️  No code changes detected - skipping documentation review"
+          fi
+
+      - name: Run Documentation Review Agent
+        if: steps.check-review.outputs.review_needed == 'true'
+        id: doc-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Allow Claude bot to trigger this workflow
+          allowed_bots: '*'
+
+          # Use Haiku model for faster/cheaper reviews
+          claude_args: |
+            --model claude-haiku-4-5-20251001
+            --allowedTools "Glob,Grep,Read,Bash(git:*),Bash(gh:*),Task,TodoWrite"
+
+          # Enable progress tracking
+          track_progress: true
+
+          # Optional: Show full output in workflow logs for debugging
+          # Rerun in debug mode or enable `show_full_output: true` in your workflow file for full output.
+          # show_full_output: false
+
+          prompt: |
+            You are reviewing documentation accuracy for a pull request.
+
+            **PR Information**:
+            - Repository: ${{ github.repository }}
+            - PR Number: ${{ github.event.pull_request.number }}
+            - Base Branch: ${{ github.event.pull_request.base.ref }}
+            - Head Branch: ${{ github.event.pull_request.head.ref }}
+
+            **Change Summary**:
+            - Code files changed: ${{ steps.changed-files.outputs.all_changed_files }}
+            - Documentation files changed: ${{ steps.doc-files.outputs.all_changed_files }}
+            - Review Type: ${{ steps.check-review.outputs.review_type }}
+
+            **Task**:
+            Launch the `documentation-accuracy-reviewer` agent to analyze documentation:
+
+            ```
+            Use the Task tool to launch the documentation-accuracy-reviewer agent with this task:
+
+            "Review documentation accuracy for PR #${{ github.event.pull_request.number }}
+
+            Review Type: ${{ steps.check-review.outputs.review_type }}
+
+            Step 1: Analyze Code Changes
+            - Use git diff to see what code changed between base and head branches
+            - Identify files: ${{ steps.changed-files.outputs.all_changed_files }}
+            - Determine what functionality was added, modified, or removed
+            - Note any new CLI flags, options, or behavior changes
+            - Identify any API or function signature changes
+
+            Step 2: Review Documentation Files
+            - Read current README.md
+            - Read current CLAUDE.md
+            - Read any other relevant documentation files
+            - Check if documentation reflects the code changes
+
+            Step 3: Documentation Accuracy Analysis
+
+            ${{ steps.check-review.outputs.review_type == 'validate' && 'Documentation WAS updated - verify accuracy:
+            - Do the documentation updates accurately describe the code changes?
+            - Are new features/flags properly documented?
+            - Are examples correct and working?
+            - Is the documentation complete (no missing features)?
+            - Are there any outdated sections that need updating?
+            - Is the documentation clear and helpful to users?' || '' }}
+
+            ${{ steps.check-review.outputs.review_type == 'check_missing' && 'Documentation WAS NOT updated - check if needed:
+            - Do the code changes require documentation updates?
+            - Are new user-facing features undocumented?
+            - Are CLI changes reflected in usage examples?
+            - Would users be confused by the changes without documentation?
+            - Are internal changes that do not need documentation?' || '' }}
+
+            Step 4: Specific Checks
+            - README.md: Usage examples, CLI flags, installation instructions
+            - CLAUDE.md: Development commands, test instructions, architecture notes
+            - Code comments: Public function docstrings, parameter descriptions
+            - CLI help text: Ensure --help output matches documentation
+
+            Step 5: Report Findings
+
+            Create a detailed review report with:
+
+            **Documentation Review Report**
+
+            **Summary**: [One-line assessment of documentation quality]
+
+            **Code Changes Analyzed**:
+            - [List key changes that might need documentation]
+
+            **Documentation Status**: ✅ Adequate | ⚠️  Needs Updates | ❌ Missing Critical Docs
+
+            **Findings**:
+
+            1. **Issue Title** (Critical/Major/Minor)
+               - Location: [file:line or section]
+               - Problem: [What's wrong or missing]
+               - Impact: [Why it matters to users]
+               - Recommendation: [Specific fix]
+
+            2. [Additional findings...]
+
+            **Positive Findings**:
+            - [What was done well]
+
+            **Recommendations**:
+            1. [High priority]
+            2. [Medium priority]
+            3. [Nice to have]
+
+            **Approval Status**:
+            - ✅ APPROVE: Documentation is accurate and complete
+            - ⚠️  APPROVE WITH SUGGESTIONS: Minor improvements recommended
+            - ❌ REQUEST CHANGES: Critical documentation issues must be addressed
+
+            Provide your report in markdown format suitable for PR comments."
+            ```
+
+            After the agent completes:
+            1. Review the documentation review report
+            2. Post findings as PR comment using gh CLI
+            3. If critical issues found, note that changes are recommended
+            4. If documentation is adequate, approve the documentation aspect
+
+      - name: Post review summary
+        if: always() && steps.check-review.outputs.review_needed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REVIEW_STATUS: ${{ steps.doc-review.outcome }}
+        run: |
+          if [ "$REVIEW_STATUS" == "success" ]; then
+            echo "✅ Documentation review completed successfully"
+
+            # Post a summary comment (the agent already posted detailed findings)
+            gh pr comment ${{ github.event.pull_request.number }} --body "
+            ## 📚 Documentation Review Complete
+
+            The documentation-accuracy-reviewer agent has completed its analysis.
+            Please review the detailed findings in the comments above.
+
+            **Status**: ✅ Review completed
+            **Reviewed by**: Claude Code (documentation-accuracy-reviewer agent)
+            "
+          else
+            echo "❌ Documentation review encountered issues"
+
+            gh pr comment ${{ github.event.pull_request.number }} --body "
+            ## 📚 Documentation Review
+
+            ⚠️  The documentation review encountered issues. Please check the workflow logs for details.
+
+            [View workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+            "
+          fi
+
+      - name: Generate summary
+        if: always()
+        env:
+          REVIEW_NEEDED: ${{ steps.check-review.outputs.review_needed }}
+          CODE_CHANGED: ${{ steps.check-review.outputs.code_changed }}
+          DOCS_CHANGED: ${{ steps.check-review.outputs.docs_changed }}
+          REVIEW_TYPE: ${{ steps.check-review.outputs.review_type }}
+          REVIEW_STATUS: ${{ steps.doc-review.outcome }}
+        run: |
+          cat <<'EOF' >> $GITHUB_STEP_SUMMARY
+          ## 📚 Documentation Review Summary
+
+          ### Change Analysis
+          - Code files changed: ${{ env.CODE_CHANGED == 'true' && '✅ Yes' || '❌ No' }}
+          - Documentation files changed: ${{ env.DOCS_CHANGED == 'true' && '✅ Yes' || '❌ No' }}
+
+          ### Review Status
+          EOF
+
+          if [ "$REVIEW_NEEDED" == "true" ]; then
+            cat <<'EOF' >> $GITHUB_STEP_SUMMARY
+          **Review Type**: ${{ env.REVIEW_TYPE }}
+          **Status**: ${{ env.REVIEW_STATUS == 'success' && '✅ Completed' || '❌ Failed' }}
+
+          The `documentation-accuracy-reviewer` agent analyzed:
+          - Code changes to identify what needs documentation
+          - Existing documentation for accuracy and completeness
+          - README.md, CLAUDE.md, and other documentation files
+          - Code comments and docstrings
+
+          **Detailed findings** have been posted as PR comments.
+          EOF
+          else
+            cat <<'EOF' >> $GITHUB_STEP_SUMMARY
+          **Review**: ⏭️  Skipped (no code changes)
+
+          No code changes detected in this PR, so documentation review was not necessary.
+          EOF
+          fi
+
+          cat <<'EOF' >> $GITHUB_STEP_SUMMARY
+
+          ---
+
+          🤖 **Automated Review**: This workflow uses the Claude Code `documentation-accuracy-reviewer`
+          agent to ensure documentation stays in sync with code changes.
+          EOF
+
+      - name: Check documentation adequacy
+        if: steps.check-review.outputs.review_needed == 'true'
+        run: |
+          # This step will fail the workflow if critical documentation issues were found
+          # The agent should have posted details in PR comments
+
+          if [ "${{ steps.doc-review.outcome }}" != "success" ]; then
+            echo "❌ Documentation review did not complete successfully"
+            echo "Please check the agent's findings and address any critical issues"
+            exit 1
+          fi
+
+          # If code changed but no docs changed, at least warn
+          if [ "${{ steps.check-review.outputs.code_changed }}" == "true" ] && \
+             [ "${{ steps.check-review.outputs.docs_changed }}" == "false" ]; then
+            echo "⚠️  Code changed but no documentation updates detected"
+            echo "Please verify that documentation updates are not needed"
+            # Don't fail - let the agent's analysis determine if this is acceptable
+          fi
+
+          echo "✅ Documentation review passed"

llmsbrieftxt-1.11.0/.github/workflows/claude.yml

@@ -0,0 +1,54 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+
+          # Optional: Show full output in workflow logs for debugging
+          # Rerun in debug mode or enable `show_full_output: true` in your workflow file for full output.
+          # show_full_output: false
+