From 9d408a446c8022900d9fddd6cde5362e4b8ca784 Mon Sep 17 00:00:00 2001 From: Lifei Zhou Date: Thu, 22 Oct 2026 22:18:29 +0000 Subject: [PATCH] chore: remove unused GitHub workflow (#13071) --- .github/recipes/code-review.yaml | 44 -- .github/workflows/build-cli.yml | 67 --- .github/workflows/code-review.yml | 210 ---------- .github/workflows/docs-update-cli-ref.yml | 304 -------------- .github/workflows/goose-issue-solver.yml | 242 ----------- .github/workflows/goose-pr-reviewer.yml | 323 --------------- documentation/automation/README.md | 57 --- .../cli-command-tracking/.gitignore | 28 -- .../automation/cli-command-tracking/README.md | 336 --------------- .../cli-command-tracking/TESTING.md | 382 ------------------ .../config/skip-commands.json | 9 - .../recipes/synthesize-cli-changes.yaml | 208 ---------- .../recipes/update-cli-commands.yaml | 222 ---------- .../scripts/diff-cli-structures.py | 355 ---------------- .../scripts/extract-cli-structure.py | 363 ----------------- .../scripts/extract-cli-structure.sh | 115 ------ .../scripts/run-pipeline.sh | 194 --------- .../2025-12-28-goose-maintains-goose/index.md | 8 +- 18 files changed, 4 insertions(+), 3463 deletions(-) delete mode 100644 .github/recipes/code-review.yaml delete mode 100644 .github/workflows/build-cli.yml delete mode 100644 .github/workflows/code-review.yml delete mode 100644 .github/workflows/docs-update-cli-ref.yml delete mode 100644 .github/workflows/goose-issue-solver.yml delete mode 100644 .github/workflows/goose-pr-reviewer.yml delete mode 100644 documentation/automation/README.md delete mode 100644 documentation/automation/cli-command-tracking/.gitignore delete mode 100644 documentation/automation/cli-command-tracking/README.md delete mode 100644 documentation/automation/cli-command-tracking/TESTING.md delete mode 100644 documentation/automation/cli-command-tracking/config/skip-commands.json delete mode 100644 documentation/automation/cli-command-tracking/recipes/synthesize-cli-changes.yaml delete mode 100644 documentation/automation/cli-command-tracking/recipes/update-cli-commands.yaml delete mode 100755 documentation/automation/cli-command-tracking/scripts/diff-cli-structures.py delete mode 100755 documentation/automation/cli-command-tracking/scripts/extract-cli-structure.py delete mode 100755 documentation/automation/cli-command-tracking/scripts/extract-cli-structure.sh delete mode 100755 documentation/automation/cli-command-tracking/scripts/run-pipeline.sh diff --git a/.github/recipes/code-review.yaml b/.github/recipes/code-review.yaml deleted file mode 100644 index f0c8f3537..000000000 --- a/.github/recipes/code-review.yaml +++ /dev/null @@ -1,44 +0,0 @@ -version: "1.0.0" -title: GitHub PR Code Review -description: Perform a code review of a GitHub pull request. - -parameters: - - key: pr_directory - input_type: string - requirement: required - description: Path to the directory with pr.md and pr.diff - - key: instructions - input_type: string - requirement: required - description: Specific instructions for the code review. - -extensions: - - type: builtin - name: developer - - type: stdio - name: code_review - cmd: uv - args: - - run - - '{{ recipe_dir }}/../scripts/pr-review-mcp.py' - -prompt: | - Review the code changes downloaded from a GitHub pull request. - The PR metadata is located at {{ pr_directory }}/pr.md. - The proposed diff you are to review is located at {{ pr_directory }}/pr.diff. - The base branch is checked out in the working directory. - Use the tools you have to review the diff and examine the code changes and context. - Use the code review tools to add feedback on specific parts of the diff. - There is no need to call the finish_review tool unless absolutely necessary to add - summary content not covered by inline comments. - - Be concise with your comments. Just a few sentences per comment at most, with no - extra formatting. Just the gist of the problem is enough. - - ** Important ** - Don't add nit-pick comments and avoid matters of opinion. - Adhere closely to the code review instructions below. - Don't add add feedback outside the scope of the instructions below. - - # Code review instructions - {{ instructions }} diff --git a/.github/workflows/build-cli.yml b/.github/workflows/build-cli.yml deleted file mode 100644 index e2f6930cc..000000000 --- a/.github/workflows/build-cli.yml +++ /dev/null @@ -1,67 +0,0 @@ -# This is a reusable workflow that builds the CLI for multiple platforms. -# -# Platform Build Strategy: -# - Linux standard (x86_64 + aarch64): Builds inside manylinux_2_28 container for glibc 2.28+ compat -# - Linux Vulkan: Uses native Ubuntu 24.04 runners for newer Vulkan headers/tooling -# - Linux musl: Uses native Ubuntu 22.04 runners with reduced features for musl compatibility -# - macOS: Uses bundle-macos.yml to package CLI artifacts without Desktop -# - Windows: Uses bundle-windows.yml to package CLI artifacts without Desktop -on: - workflow_call: - inputs: - version: - required: false - default: "" - type: string - ref: - type: string - required: false - default: "" - -name: "Reusable workflow to build CLI" - -jobs: - build-cli-macos: - strategy: - fail-fast: false - matrix: - target: - - x86_64-apple-darwin - - aarch64-apple-darwin - uses: ./.github/workflows/bundle-macos.yml - permissions: - contents: read - with: - version: ${{ inputs.version }} - ref: ${{ inputs.ref }} - target: ${{ matrix.target }} - signing: false - package_cli: true - package_desktop: false - - build-cli-windows: - strategy: - fail-fast: false - matrix: - windows_variant: - - standard - - cuda - uses: ./.github/workflows/bundle-windows.yml - permissions: - contents: read - with: - version: ${{ inputs.version }} - ref: ${{ inputs.ref }} - signing: false - package_cli: true - package_desktop: false - windows_variant: ${{ matrix.windows_variant }} - - build-cli-linux: - uses: ./.github/workflows/build-cli-linux.yml - permissions: - contents: read - with: - version: ${{ inputs.version }} - ref: ${{ inputs.ref }} - package_desktop: false diff --git a/.github/workflows/code-review.yml b/.github/workflows/code-review.yml deleted file mode 100644 index 3ad1bae70..000000000 --- a/.github/workflows/code-review.yml +++ /dev/null @@ -1,210 +0,0 @@ -name: Code Review - -on: - workflow_dispatch: - inputs: - pr_number: - description: 'PR number to review' - required: true - type: number - oidc_proxy_url: - description: 'OIDC proxy URL (overrides repo variable)' - required: false - type: string - review_instructions: - description: 'Instructions for the code review' - required: false - default: 'Review the changes for correctness' - type: string - # pull_request_target: - # types: [opened, synchronize, reopened] - -concurrency: - group: code-review-${{ github.event.pull_request.number || github.event.inputs.pr_number }} - cancel-in-progress: true - -jobs: - prepare: - runs-on: ubuntu-latest - permissions: - id-token: write - contents: read - pull-requests: read - steps: - - name: Mint OIDC token - id: oidc - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 - env: - TOKEN_AUDIENCE: goose-oidc-proxy - with: - script: | - const token = await core.getIDToken(process.env.TOKEN_AUDIENCE); - core.setOutput('token', token); - core.setSecret(token); - - - name: Gather PR metadata and diff - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - PR_NUMBER=${{ github.event.pull_request.number || github.event.inputs.pr_number }} - mkdir -p /tmp/code-review - - gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json title --jq '.title' > /tmp/code-review/title.txt - gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json body --jq '.body // "(no description)"' > /tmp/code-review/body.txt - gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefOid --jq '.headRefOid' > /tmp/code-review/commit_id.txt - gh pr diff "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" > /tmp/code-review/pr.diff - - TITLE=$(cat /tmp/code-review/title.txt) - BODY=$(cat /tmp/code-review/body.txt) - printf '# %s\n\n## Description\n\n%s\n' "$TITLE" "$BODY" > /tmp/code-review/pr.md - - - name: Write OIDC token to file - run: echo "$OIDC_TOKEN" > /tmp/code-review/oidc-token.txt - env: - OIDC_TOKEN: ${{ steps.oidc.outputs.token }} - - - name: Upload review inputs - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: code-review-inputs - path: /tmp/code-review/ - retention-days: 1 - - review: - needs: prepare - runs-on: ubuntu-latest - permissions: {} - timeout-minutes: 15 - - container: - image: ghcr.io/aaif-goose/goose:latest - options: --user root - env: - HOME: /tmp/goose-home - - steps: - - name: Checkout base branch - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - - name: Install tools - run: | - apt-get update - apt-get install -y ripgrep jq - - - name: Download review inputs - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 - with: - name: code-review-inputs - path: /tmp/code-review - - - name: Install custom provider and run goose review - env: - GOOSE_PROVIDER: anthropic-oidc-proxy - GOOSE_MODEL: ${{ vars.GOOSE_CODE_REVIEW_MODEL || 'claude-opus-4-6' }} - OIDC_PROXY_URL: ${{ github.event.inputs.oidc_proxy_url || vars.OIDC_PROXY_URL }} - REVIEW_INSTRUCTIONS: ${{ github.event.inputs.review_instructions || 'Review the changes for correctness' }} - run: | - ANTHROPIC_OIDC_PROXY_API_KEY=$(cat /tmp/code-review/oidc-token.txt) - export ANTHROPIC_OIDC_PROXY_API_KEY - rm /tmp/code-review/oidc-token.txt - - mkdir -p "$HOME/.local/share/goose/sessions" - mkdir -p "$HOME/.config/goose/custom_providers" - cp oidc-proxy/anthropic-oidc-proxy.json "$HOME/.config/goose/custom_providers/" - - goose run \ - --recipe .github/recipes/code-review.yaml \ - --params pr_directory=/tmp/code-review \ - --params instructions="$REVIEW_INSTRUCTIONS" - - - name: Upload review output - if: always() - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: code-review-output - path: | - /tmp/conclusion.json - /tmp/comments.json - if-no-files-found: ignore - retention-days: 30 - - submit: - needs: [prepare, review] - runs-on: ubuntu-latest - permissions: - pull-requests: write - if: always() && needs.review.result == 'success' - - steps: - - name: Download review inputs - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 - with: - name: code-review-inputs - path: /tmp/inputs - - - name: Download review output - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 - with: - name: code-review-output - path: /tmp/output - - - name: Submit review - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PR_NUMBER: ${{ github.event.pull_request.number || github.event.inputs.pr_number }} - run: | - CONCLUSION="/tmp/output/conclusion.json" - COMMENTS="/tmp/output/comments.json" - COMMIT_ID=$(cat /tmp/inputs/commit_id.txt) - - if [ ! -f "$COMMENTS" ]; then - echo "No comments produced, skipping review submission." - exit 0 - fi - - if [ ! -f "$CONCLUSION" ]; then - echo '{"body":"","event":"COMMENT"}' > "$CONCLUSION" - fi - - jq -n \ - --arg commit_id "$COMMIT_ID" \ - --slurpfile conclusion "$CONCLUSION" \ - --slurpfile comments "$COMMENTS" \ - '{ - commit_id: $commit_id, - event: $conclusion[0].event, - comments: $comments[0] - } - | if $conclusion[0].body != "" then .body = $conclusion[0].body else . end - ' > /tmp/review-payload.json - - if gh api \ - --method POST \ - -H "Accept: application/vnd.github+json" \ - "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \ - --input /tmp/review-payload.json; then - echo "Review submitted with inline comments." - exit 0 - fi - - echo "Inline comments failed, folding into review body." - - jq -n \ - --arg commit_id "$COMMIT_ID" \ - --slurpfile conclusion "$CONCLUSION" \ - --slurpfile comments "$COMMENTS" \ - '{ - commit_id: $commit_id, - body: ( - $conclusion[0].body + "\n\n---\n\n## Inline Comments\n\n" + - ([$comments[0][] | - "### `" + .path + "` (line " + (.line | tostring) + ")\n\n" + .body - ] | join("\n\n---\n\n")) - ), - event: $conclusion[0].event - }' \ - | gh api \ - --method POST \ - -H "Accept: application/vnd.github+json" \ - "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/reviews" \ - --input - diff --git a/.github/workflows/docs-update-cli-ref.yml b/.github/workflows/docs-update-cli-ref.yml deleted file mode 100644 index 8adf26ae8..000000000 --- a/.github/workflows/docs-update-cli-ref.yml +++ /dev/null @@ -1,304 +0,0 @@ -# Automatically updates the CLI Commands Guide when CLI commands or options -# change between releases. -# -# Triggers: Manual (for testing) or on release (production) -# Testing: Use dry_run mode to review outputs without creating PRs -# See: documentation/automation/cli-command-tracking/TESTING.md - -name: Update CLI Documentation - -on: - workflow_dispatch: # Manual trigger for testing - inputs: - old_version: - description: 'Previous version (e.g., v1.14.0). Leave empty to auto-detect.' - required: false - type: string - new_version: - description: 'New version (e.g., v1.15.0). Leave empty to use HEAD.' - required: false - type: string - dry_run: - description: 'Dry run mode - generate files but do not create PR' - required: false - type: boolean - default: true - - # Automatic triggering on releases - # Uses edited to catch when release-action updates the release with artifacts - release: - types: [edited] - -permissions: - contents: write # Create branches and commit files - pull-requests: write # Create PRs - -jobs: - update-docs: - name: Update CLI Documentation - runs-on: ubuntu-latest - - env: - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - - steps: - - name: Checkout repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 # Fetch all history for version comparison - fetch-tags: true # Fetch all tags so we can checkout version tags - - - name: Fetch upstream tags (for forks) - if: github.repository != 'aaif-goose/goose' - run: | - # Add upstream remote and fetch tags (only needed when testing in forks) - git remote add upstream https://github.com/aaif-goose/goose.git || git remote set-url upstream https://github.com/aaif-goose/goose.git - git fetch upstream --tags --force - echo "✅ Fetched tags from upstream (fork mode)" - echo "Total tags available: $(git tag | wc -l)" - - - name: Install system dependencies - run: | - sudo apt-get update - sudo apt-get install -y jq ripgrep - - - name: Set up Rust - uses: actions-rust-lang/setup-rust-toolchain@ecabd13d1c56bd1345c230e542e9144811ad706f # v2.0.0 - with: - toolchain: stable - - - name: Set up Python - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 - with: - python-version: '3.11' - - - name: Set up Node.js - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 - with: - node-version: '20' - - - name: Install goose CLI - run: | - mkdir -p /home/runner/.local/bin - curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh \ - | CONFIGURE=false GOOSE_BIN_DIR=/home/runner/.local/bin bash - echo "/home/runner/.local/bin" >> $GITHUB_PATH - goose --version - - - name: Configure goose for CI - env: - GOOSE_PROVIDER: ${{ vars.GOOSE_PROVIDER || 'anthropic' }} - GOOSE_MODEL: ${{ vars.GOOSE_MODEL || 'claude-opus-4-5' }} - run: | - mkdir -p ~/.config/goose - cat < ~/.config/goose/config.yaml - GOOSE_PROVIDER: $GOOSE_PROVIDER - GOOSE_MODEL: $GOOSE_MODEL - keyring: false - EOF - - # Also export into the job environment so later steps can log the values - echo "GOOSE_PROVIDER=$GOOSE_PROVIDER" >> "$GITHUB_ENV" - echo "GOOSE_MODEL=$GOOSE_MODEL" >> "$GITHUB_ENV" - - echo "✅ Created goose config:" - cat ~/.config/goose/config.yaml - - - name: Determine versions to compare - id: versions - env: - GH_TOKEN: ${{ github.token }} - INPUT_OLD_VERSION: ${{ github.event.inputs.old_version }} - INPUT_NEW_VERSION: ${{ github.event.inputs.new_version }} - EVENT_NAME: ${{ github.event_name }} - RELEASE_TAG: ${{ github.event.release.tag_name }} - run: | - get_previous_release() { - gh release list --limit 2 --json tagName --jq '.[].tagName' | sed -n '2p' - } - - if [ -n "$INPUT_OLD_VERSION" ]; then - OLD_VERSION="$INPUT_OLD_VERSION" - else - OLD_VERSION=$(get_previous_release) - fi - - if [ -n "$INPUT_NEW_VERSION" ]; then - NEW_VERSION="$INPUT_NEW_VERSION" - elif [ "$EVENT_NAME" = "release" ]; then - NEW_VERSION="$RELEASE_TAG" - else - NEW_VERSION="HEAD" # For testing unreleased changes - fi - - if [ -z "$OLD_VERSION" ] || [ -z "$NEW_VERSION" ]; then - echo "Error: Could not determine versions to compare" - exit 1 - fi - - echo "old_version=$OLD_VERSION" >> $GITHUB_OUTPUT - echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT - echo "OLD_VERSION=$OLD_VERSION" >> $GITHUB_ENV - echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV - - echo "✅ Comparing $OLD_VERSION → $NEW_VERSION" - - - name: Extract and compare CLI structures - id: extract - timeout-minutes: 30 # Building goose takes time - working-directory: documentation/automation/cli-command-tracking - env: - GOOSE_REPO: ${{ github.workspace }} - run: | - set -o pipefail # Ensure pipeline failures are caught - - mkdir -p output - ./scripts/run-pipeline.sh "$OLD_VERSION" "$NEW_VERSION" 2>&1 | tee output/pipeline.log - - HAS_CHANGES=$(jq -r '.has_changes' output/cli-changes.json) - echo "has_changes=$HAS_CHANGES" >> $GITHUB_OUTPUT - - if [ "$HAS_CHANGES" = "false" ]; then - echo "✅ No changes detected" - else - echo "✅ Changes detected" - fi - - - name: Update goose-cli-commands.md (AI synthesis) - if: steps.extract.outputs.has_changes == 'true' - timeout-minutes: 10 - working-directory: documentation/automation/cli-command-tracking/output - env: - CLI_COMMANDS_PATH: ${{ github.workspace }}/documentation/docs/guides/goose-cli-commands.md - run: | - echo "🔍 Environment diagnostics:" - echo " GOOSE_PROVIDER: $GOOSE_PROVIDER" - echo " GOOSE_MODEL: $GOOSE_MODEL" - echo " ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:0:8}..." # Show first 8 chars only - echo " CLI_COMMANDS_PATH: $CLI_COMMANDS_PATH" - echo " HOME: $HOME" - echo " PATH: $PATH" - echo "" - echo "📁 Goose config file:" - cat ~/.config/goose/config.yaml || echo "Config file not found!" - echo "" - echo "📁 Current directory:" - pwd - ls -la - echo "" - echo "🤖 Applying changes to goose-cli-commands.md..." - goose run --recipe ../recipes/update-cli-commands.yaml - - - name: Upload automation outputs - if: always() - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: cli-docs-update-${{ steps.versions.outputs.old_version }}-to-${{ steps.versions.outputs.new_version }} - path: | - documentation/automation/cli-command-tracking/output/*.json - documentation/automation/cli-command-tracking/output/*.md - documentation/automation/cli-command-tracking/output/*.log - retention-days: 30 - - - name: Create Pull Request - if: | - steps.extract.outputs.has_changes == 'true' && - (github.event.inputs.dry_run != 'true' || github.event_name == 'release') - uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 - with: - branch: docs/auto-cli-commands-${{ steps.versions.outputs.new_version }} - delete-branch: true - - commit-message: | - docs: Update CLI commands for ${{ steps.versions.outputs.new_version }} - - Automated update based on CLI changes between ${{ steps.versions.outputs.old_version }} and ${{ steps.versions.outputs.new_version }}. - - title: "docs: Update CLI Commands Guide for ${{ steps.versions.outputs.new_version }}" - body: | - ## Summary - - This PR updates the CLI Commands Guide based on command and option changes detected between **${{ steps.versions.outputs.old_version }}** and **${{ steps.versions.outputs.new_version }}**. - - ### Type of Change - - [x] Documentation - - ### AI Assistance - - [x] This PR was created or reviewed with AI assistance - - #### 🤖 Automation Details - - - **Workflow**: docs-update-cli-ref.yml - - **Triggered by**: ${{ github.event_name }} - - **Previous version**: ${{ steps.versions.outputs.old_version }} - - **New version**: ${{ steps.versions.outputs.new_version }} - - #### 📋 Changes Detected - - Review the workflow artifacts for detailed change analysis: - - cli-changes.json - Structured diff of changes - - cli-changes.md - Human-readable change documentation - - update-summary.md - Summary of documentation updates applied - - Download artifacts from the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}). - - ### ✅ Review Checklist - - - [ ] Verify all CLI changes are accurately documented - - [ ] Check that examples are updated correctly - - [ ] Ensure new commands are in the correct sections - - [ ] Confirm no unintended changes were made - - ### 🔗 Related - - - Release: ${{ github.event.release.html_url || 'N/A' }} - - --- - - *This PR was automatically generated by the CLI Documentation Automation workflow.* - - labels: | - documentation - automated - cli-commands - - - name: Workflow summary - if: always() - env: - OLD_VERSION: ${{ steps.versions.outputs.old_version }} - NEW_VERSION: ${{ steps.versions.outputs.new_version }} - HAS_CHANGES: ${{ steps.extract.outputs.has_changes }} - DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }} - run: | - echo "## 📊 CLI Documentation Update Summary" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "**Version Comparison**: $OLD_VERSION → $NEW_VERSION" >> $GITHUB_STEP_SUMMARY - echo "**Changes Detected**: $HAS_CHANGES" >> $GITHUB_STEP_SUMMARY - echo "**Dry Run Mode**: $DRY_RUN" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - - if [ "$HAS_CHANGES" = "true" ]; then - echo "### ✅ Documentation Updated" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "The CLI Commands Guide has been updated to reflect changes in $NEW_VERSION." >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - - if [ "$DRY_RUN" = "true" ]; then - echo "**Note**: Running in dry-run mode - no PR was created. Review the artifacts to see the generated changes." >> $GITHUB_STEP_SUMMARY - else - echo "A pull request has been created with the documentation updates." >> $GITHUB_STEP_SUMMARY - fi - else - echo "### ℹ️ No Changes Needed" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "No CLI command changes were detected between $OLD_VERSION and $NEW_VERSION." >> $GITHUB_STEP_SUMMARY - fi - - echo "" >> $GITHUB_STEP_SUMMARY - echo "### 📦 Artifacts" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "Download the workflow artifacts to review:" >> $GITHUB_STEP_SUMMARY - echo "- Extracted CLI structures" >> $GITHUB_STEP_SUMMARY - echo "- Change detection results" >> $GITHUB_STEP_SUMMARY - echo "- Human-readable change documentation" >> $GITHUB_STEP_SUMMARY - echo "- Documentation update summary" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/goose-issue-solver.yml b/.github/workflows/goose-issue-solver.yml deleted file mode 100644 index 067e6dfeb..000000000 --- a/.github/workflows/goose-issue-solver.yml +++ /dev/null @@ -1,242 +0,0 @@ -name: goose Issue Solver - -on: - issue_comment: - types: [created] - workflow_dispatch: - inputs: - issue_number: - description: 'Issue number to solve' - required: true - type: string - -env: - GOOSE_RECIPE: | - version: "1.0.0" - title: "Solve GitHub Issue" - description: "Solve GitHub issue #${ISSUE_NUMBER}" - - extensions: - - type: builtin - name: developer - - type: platform - name: todo - - instructions: | - Write code like a senior goose contributor. - - Principles: - - Search first: `rg "keyword" -l` to find existing patterns. Copy them exactly. - - Deletion is a feature: ask "can I delete code instead of adding?" - - Complete changes: update ALL usages when changing a type. No exceptions. - - When changing message types, update ALL provider format functions. - - When changing ACP request/response types, run `just generate-acp-types`. - - Your context degrades. The TODO is your memory. Update it after each step. - - Types: - - `PathBuf` for paths, never `String` - - Enums for finite sets, never string comparisons - - `Vec` not `Option>` - empty vec is the "none" case - - Don't return `Result` if failure is meaningless - - `#[serde(default)]` on new struct fields - - Patterns: - - Early returns, not nested if-else - - Extract to utility if code appears 3+ times - - Scope locks tightly: extract data, release lock, then I/O - - Log and continue for non-critical failures - - Error messages must say HOW to fix, not just what's wrong - - Use `#[cfg(target_os = "...")]` for platform-specific code - - Testing: - - Bug fix: write failing test FIRST, then fix - - Delete tests when deleting features - - No tests for trivial code - - Don't: - - Create abstractions unless required - - Add backward compat shims - update callers - - Write WHAT comments (keep WHY comments) - - Add checks the OS will do anyway - - prompt: | - Solve GitHub issue #${ISSUE_NUMBER}: ${ISSUE_TITLE} - - The issue is saved at /tmp/issue.json - - Trigger comment: - ${TRIGGER_COMMENT} - - Write this to your TODO immediately and update as you progress: - - ## Phase 1: Understand - - [ ] Read /tmp/issue.json - - [ ] Write all requirements (explicit + implicit) to /tmp/requirements.md - - [ ] Read AGENTS.md if it exists - - ## Phase 2: Research - - [ ] `rg "keyword" -l` to find relevant files and similar patterns - - [ ] `analyze path="crates/" focus="SymbolName"` to trace type/function usage - - [ ] Read 2-3 similar implementations to copy their patterns - - [ ] List all files that need changes in TODO - - ## Phase 3: Plan - - [ ] Decide on implementation approach - - [ ] If changing >5 files or public APIs, write plan to /tmp/plan.md first - - [ ] Update TODO with specific changes to make - - ## Phase 4: Implement - - [ ] Implement minimal fix per /tmp/requirements.md - - [ ] Before adding anything, check: is it in the requirements? If not, don't. - - [ ] No .github/, no lock files, no secrets - - ## Phase 5: Verify - - [ ] source bin/activate-hermit - - [ ] cargo check - - [ ] cargo test (affected crates) - - [ ] cargo fmt - - [ ] cargo clippy --all-targets -- -D warnings - - [ ] Fix failures, retry up to 3 times - - ## Phase 6: Confirm (MANDATORY) - - [ ] Reread /tmp/issue.json - - [ ] Reread /tmp/requirements.md - - [ ] Confirm all requirements met, nothing extra added - - [ ] Write a summary of changes to /tmp/issue_summary.txt - - The Phase 6 "Reread" steps MUST appear in your updated TODO. Skipping them is failure. - - Only write /tmp/issue_summary.txt if the fix is complete and verified. - Run `git add` for any new files required for the fix. - Do NOT commit. Leave changes in the working directory for the workflow to handle. - -permissions: - contents: write - pull-requests: write - issues: write - -concurrency: - group: goose-issue-${{ github.event.issue.number || github.event.inputs.issue_number }} - cancel-in-progress: false - -jobs: - solve-issue: - if: | - github.event_name == 'workflow_dispatch' || - (!github.event.issue.pull_request && - startsWith(github.event.comment.body, '/goose') && - contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) - - runs-on: ubuntu-latest - timeout-minutes: 30 - - container: - image: ghcr.io/aaif-goose/goose:latest - options: --user root - env: - GOOSE_PROVIDER: ${{ vars.GOOSE_PROVIDER || 'anthropic' }} - GOOSE_MODEL: ${{ vars.GOOSE_MODEL || 'claude-opus-4-5' }} - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - HOME: /tmp/goose-home - - steps: - - name: Acknowledge trigger - if: github.event_name == 'issue_comment' - run: | - curl -sL -X POST \ - -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \ - "https://api.github.com/repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions" \ - -d '{"content":"eyes"}' - - - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: main - fetch-depth: 1 - - - name: Install tools - run: | - apt-get update - apt-get install -y jq gettext curl build-essential pkg-config libssl-dev - curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg - echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null - apt-get update - apt-get install -y gh - - - name: Get issue details (issue_comment) - if: github.event_name == 'issue_comment' - env: - ISSUE_JSON: ${{ toJSON(github.event.issue) }} - run: printenv ISSUE_JSON > /tmp/issue.json - - - name: Get issue details (workflow_dispatch) - if: github.event_name == 'workflow_dispatch' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: gh api /repos/${{ github.repository }}/issues/${{ github.event.inputs.issue_number }} > /tmp/issue.json - - - name: Set issue outputs - id: issue - run: | - echo "number=$(jq -r '.number' /tmp/issue.json)" >> $GITHUB_OUTPUT - - # SECURITY: Use random delimiter to prevent injection if title contains our delimiter - DELIMITER="EOF_$(openssl rand -hex 8)" - echo "title<<$DELIMITER" >> $GITHUB_OUTPUT - jq -r '.title' /tmp/issue.json >> $GITHUB_OUTPUT - echo "$DELIMITER" >> $GITHUB_OUTPUT - - - name: Run goose - id: goose - env: - ISSUE_NUMBER: ${{ steps.issue.outputs.number }} - ISSUE_TITLE: ${{ steps.issue.outputs.title }} - TRIGGER_COMMENT: ${{ github.event.comment.body || 'Triggered via workflow_dispatch' }} - run: | - mkdir -p $HOME/.local/share/goose/sessions - mkdir -p $HOME/.config/goose - git config --global --add safe.directory "$GITHUB_WORKSPACE" - - echo "$GOOSE_RECIPE" | envsubst '$ISSUE_NUMBER $ISSUE_TITLE $TRIGGER_COMMENT' > /tmp/recipe.yaml - - goose run --recipe /tmp/recipe.yaml - - if [ -n "$(git status --porcelain)" ] && [ -f /tmp/issue_summary.txt ]; then - echo "has_changes=true" >> $GITHUB_OUTPUT - # SECURITY: Use random delimiter to prevent injection if summary contains our delimiter - SUMMARY_DELIMITER="EOF_$(openssl rand -hex 8)" - echo "summary<<$SUMMARY_DELIMITER" >> $GITHUB_OUTPUT - cat /tmp/issue_summary.txt >> $GITHUB_OUTPUT - echo "$SUMMARY_DELIMITER" >> $GITHUB_OUTPUT - else - echo "has_changes=false" >> $GITHUB_OUTPUT - fi - - - name: Verify no workflow changes - if: steps.goose.outputs.has_changes == 'true' - run: | - if git diff --name-only | grep -q "^\.github/"; then - echo "::error::Changes to .github/ are not allowed" - git checkout -- .github/ - fi - - - name: Create Pull Request - if: steps.goose.outputs.has_changes == 'true' - uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 - with: - token: ${{ secrets.GITHUB_TOKEN }} - commit-message: "fix: ${{ steps.issue.outputs.title }}" - title: "fix: ${{ steps.issue.outputs.title }}" - branch: goose/issue-${{ steps.issue.outputs.number }} - delete-branch: true - draft: true - labels: goose-generated - body: | - Closes #${{ steps.issue.outputs.number }} - - ## Summary - ${{ steps.goose.outputs.summary || 'See commits for details.' }} - - --- - *Generated by goose Issue Solver* diff --git a/.github/workflows/goose-pr-reviewer.yml b/.github/workflows/goose-pr-reviewer.yml deleted file mode 100644 index c21a85f94..000000000 --- a/.github/workflows/goose-pr-reviewer.yml +++ /dev/null @@ -1,323 +0,0 @@ -# goose PR Reviewer -# -# Automated PR review using goose AI agent. -# -# Trigger: Comment "/goose [optional instructions]" on a PR (OWNER/MEMBER only) -# -# Examples: -# /goose -# /goose focus on security implications -# /goose check error handling in src/auth/ -# -# Required Secrets: -# - ANTHROPIC_API_KEY: API key for Anthropic -# -# Optional Variables: -# - GOOSE_PROVIDER: LLM provider (default: anthropic) -# - GOOSE_MODEL: Model name (default: claude-opus-4-5) -# -# Security: -# - PR content could prompt-inject the agent; only trigger on PRs you trust. -# - Do not add workflow_dispatch: API calls fetch mutable data, enabling TOCTOU attacks. - -name: goose PR Reviewer - -on: - issue_comment: - types: [created] - -env: - GOOSE_RECIPE: | - version: "1.0.0" - title: "Review Pull Request" - description: "Review PR #${PR_NUMBER}" - - extensions: - - type: builtin - name: developer - - type: platform - name: todo - - instructions: | - You are a code reviewer. Evaluate code, don't implement changes. Be constructive, specific, and verify claims with evidence. - - ## Issue Categories - - 🔴 BLOCKING: Must fix. Requires HIGH confidence + code evidence. - - 🟡 WARNING: Should fix. MEDIUM+ confidence. - - 🟢 SUGGESTION: Nice to have. Can be speculative if labeled. - - ✅ HIGHLIGHT: Good practices to acknowledge. - - ## Core Review Lens: "Succeed Fast" Detection - LLM code often compiles quickly while avoiding proper design. Ask these questions: - - **Necessity**: Do we need this? - - New function? Could an existing one take an extra parameter? - - New struct? Search `rg "struct Similar"` - does one exist? - - New dependency? Many tools (gh, python) are pre-installed. - - **Types & Options**: Is the type system being used correctly? - - Option: Why optional? If .unwrap() is nearby, it should be required. - - Option: Rarely needed. Consider if None vs Some(false) distinction matters. - - Manual JSON parsing: Use typed structs, not field extraction. - - Many casts/assertions: The types are probably wrong. - - Use builders: Prefer `Foo::builder()` over manual struct construction when available. - - Generated types: Use API/SDK-provided types. Don't redefine what's already generated. - - Path types: Use PathBuf for paths, not String. Use centralized path utilities. - - **Duplication & State**: Is there one source of truth? - - Similar code nearby? Factor it out. - - Shadow state (settings in multiple places)? Consolidate. - - Singleton caching config? What if config changes? - - **Error Handling**: Are errors handled or hidden? - - .ok(), .unwrap_or_default(), catch-and-log: Should this propagate? - - ## Code Hygiene - - AI-generated artifacts: Verbose comments like "// Helper function to..." may be LLM leftovers. Delete if obvious. - - Comments restating code: Delete. "Code speaks for itself." - - Comments that lie: Dangerous. Fix or delete. - - TODOs without owners: Create issue or delete. - - Tests setting env vars: `rg "env::set_var" -g "*test*"` = flaky tests. - - Tests not testing behavior: "What bug would this catch?" - Ref: https://engineering.block.xyz/blog/the-high-cost-of-free-testing - - ## Security (especially workflows) - - TOCTOU: Use event payload, not API calls. - - Heredoc injection: User content may contain delimiter. - - Feature auto-enable: Must respect user toggles. - - ## Architectural Smell (be specific about why) - - Brittle: Too many special cases, hardcoded assumptions. - - Wrong layer: Routes should be thin. Clients shouldn't know implementation details. - - Not independent: Multiple booleans → should be enum. - - Cumbersome: Simpler approach exists? Extend existing APIs. - - Naming confusion: Similar functions should return similarly-named types (not FooResult vs ResultFoo). - - Scope creep: Changes unrelated to PR's stated purpose. - - ## Anti-hallucination - - Search with rg before claiming something is "missing" - - Before claiming UI/frontend changes are needed, trace the actual data flow - - Say "I couldn't verify" not "this is wrong" - - 2 verified issues are better than 10 speculative ones - - ## Language Note - These guidelines are primarily Rust-focused. For TypeScript/frontend changes (ui/desktop/), - apply the same rigor with language-appropriate patterns (e.g., discriminated unions, - optional chaining, React key uniqueness). Review all code equally thoroughly. - - If the approach is fundamentally wrong, reject it. Don't polish bad code. - - prompt: | - Review PR #${PR_NUMBER}: ${PR_TITLE} - - The PR metadata is saved at /tmp/pr.json - The PR diff is saved at /tmp/pr.diff - - The PR branch is already checked out. You are in the repository directory. - Use the codebase to understand context - explore with analyze, rg, and file reads. - - Reviewer instructions from trigger: - ${REVIEW_INSTRUCTIONS} - - FIRST ACTION: Call todo_write with this entire checklist. Your memory degrades - the TODO is your only reliable memory. Update it frequently. - - ## Budget Guidance - You have 15 minutes. Allocate effort wisely: - - Phase 1 (Understand): ~20% - Don't over-explore, get the gist - - Phase 2 (Evaluate): ~30% - This is where design issues surface - - Phase 3 (Verify): ~30% - Only if approach is sound, skip if fundamentally flawed - - Phase 4 (Report): ~20% - Prioritize and write concisely - For large diffs (>500 lines): Focus on architecture over line-by-line review. - Aim for 3-7 high-quality findings, not exhaustive coverage. - - ## PR Understanding - - Intent: [fill after Phase 1] - - Approach: [fill after Phase 1] - - Evaluation: [fill after Phase 2 - is this the right approach?] - - ## Phase 1: Understand - - [ ] Read /tmp/pr.json for PR description and context - - [ ] Read /tmp/pr.diff for the actual changes - - [ ] Read AGENTS.md if it exists - - [ ] Note reviewer instructions: ${REVIEW_INSTRUCTIONS} - - [ ] Summarize: What is this PR trying to accomplish? - - ## Phase 2: Evaluate (Empathize, then Challenge) - First, empathize with the author's choices: - - [ ] Trace the data/control flow through the changes - - [ ] Why did the author choose this approach? - - [ ] What constraints were they working under? - - Then, challenge the approach: - - [ ] Architectural fit: Does this fit naturally, or is there awkward "pretending"? - - [ ] Alternatives: Could existing APIs/patterns be extended instead of adding new code? - - [ ] Consistency: Do names/types match similar code? Search with: rg "similar_name" --type rust - - [ ] Necessity: Is all this code needed? Could parameters/fields be removed? - - [ ] State and intent: If this enables/disables features, does it respect user preferences? - - [ ] Simpler path: Is there a way to achieve this with less code? - - If fundamental design issues are found, note them and consider skipping detailed verification. - - ## Phase 3: Verify (only if approach is sound) - - [ ] Review for correctness and logic errors - - [ ] Check for security vulnerabilities - - [ ] Assess error handling - - [ ] Look for performance issues - - [ ] Verify edge cases are handled - - [ ] For each issue, add to Issues Found below with confidence level - - Note: Do NOT run cargo check, cargo test, cargo fmt, or other build commands. - CI pipelines already validate those automatically. Focus on code review only. - - ## Phase 4: Report - - [ ] Prioritize findings: 🔴 Blocking > 🟡 Warning > 🟢 Suggestion - - [ ] Verify all 🔴 BLOCKING issues have HIGH confidence + code evidence - - [ ] Write review to /tmp/pr_review.md - - [ ] Be concise - quality over quantity - - ## Issues Found - [Add issues here as you find them, format: [HIGH/MED/LOW] [file:line] description - evidence] - - --- - - Format your review in /tmp/pr_review.md as: - - **Summary**: [1-2 sentence overview of what this PR does and your assessment] - - Only include sections below if they have content. Omit empty sections entirely. - - **🔴 Blocking Issues** - [Issues that must be fixed before merge. Each must have file:line and evidence.] - - **🟡 Warnings** - [Issues that should be addressed] - - **🟢 Suggestions** - [Optional improvements] - - **✅ Highlights** - [Good practices observed in this PR] - - --- - *Review generated by goose* - - Only write /tmp/pr_review.md when the review is complete. - Do NOT make any changes to the codebase. - -permissions: - contents: read - pull-requests: write - -concurrency: - group: goose-pr-review-${{ github.event.issue.number }} - cancel-in-progress: true - -jobs: - review-pr: - if: | - github.event.issue.pull_request && - startsWith(github.event.comment.body, '/goose') && - contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association) - - runs-on: ubuntu-latest - timeout-minutes: 15 - - container: - image: ghcr.io/aaif-goose/goose:latest - options: --user root - env: - GOOSE_PROVIDER: ${{ vars.GOOSE_PROVIDER || 'anthropic' }} - GOOSE_MODEL: ${{ vars.GOOSE_MODEL || 'claude-opus-4-5' }} - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - HOME: /tmp/goose-home - - steps: - - name: Acknowledge trigger - run: | - curl -sL -X POST \ - -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \ - "https://api.github.com/repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions" \ - -d '{"content":"eyes"}' - - - name: Checkout PR - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: refs/pull/${{ github.event.issue.number }}/head - fetch-depth: 1 - - - name: Install tools - run: | - apt-get update - apt-get install -y gettext curl ripgrep - curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg - echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null - apt-get update - apt-get install -y gh - - - name: Get PR diff - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh pr diff ${{ github.event.issue.number }} --repo ${{ github.repository }} > /tmp/pr.diff - - - name: Extract review instructions - id: instructions - env: - COMMENT_BODY: ${{ github.event.comment.body }} - run: | - if [ -n "$COMMENT_BODY" ]; then - INSTRUCTIONS=$(echo "$COMMENT_BODY" | sed 's|^/goose||' | sed 's|^[[:space:]]*||' | sed 's|[[:space:]]*$||') - fi - - if [ -z "$INSTRUCTIONS" ]; then - INSTRUCTIONS="No specific instructions - perform a general code review." - fi - - # SECURITY: Use random delimiter to prevent injection if comment contains our delimiter - DELIMITER="EOF_$(openssl rand -hex 8)" - echo "instructions<<$DELIMITER" >> $GITHUB_OUTPUT - echo "$INSTRUCTIONS" >> $GITHUB_OUTPUT - echo "$DELIMITER" >> $GITHUB_OUTPUT - - - name: Run goose review - id: goose - env: - PR_NUMBER: ${{ github.event.issue.number }} - PR_TITLE: ${{ github.event.issue.title }} - PR_BODY: ${{ github.event.issue.body }} - REVIEW_INSTRUCTIONS: ${{ steps.instructions.outputs.instructions }} - # SECURITY: Pass issue JSON via environment variable to avoid heredoc injection - # (GHSA-mm8p-57gq-3xj6) - user-controlled content could terminate heredoc early - ISSUE_JSON: ${{ toJson(github.event.issue) }} - run: | - mkdir -p $HOME/.local/share/goose/sessions - mkdir -p $HOME/.config/goose - git config --global --add safe.directory "$GITHUB_WORKSPACE" - - # SECURITY: Use printf with env var instead of heredoc to prevent injection - printf '%s' "$ISSUE_JSON" > /tmp/pr.json - - echo "$GOOSE_RECIPE" | envsubst '$PR_NUMBER $PR_TITLE $PR_BODY $REVIEW_INSTRUCTIONS' > /tmp/recipe.yaml - - goose run --recipe /tmp/recipe.yaml - - if [ -f /tmp/pr_review.md ]; then - echo "has_review=true" >> $GITHUB_OUTPUT - else - echo "has_review=false" >> $GITHUB_OUTPUT - fi - - - name: Post review comment - if: steps.goose.outputs.has_review == 'true' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh pr comment ${{ github.event.issue.number }} --repo ${{ github.repository }} --body-file /tmp/pr_review.md - - - name: Post failure comment - if: failure() || steps.goose.outputs.has_review != 'true' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh pr comment ${{ github.event.issue.number }} --repo ${{ github.repository }} --body "⚠️ goose PR review could not be completed. Check the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details." diff --git a/documentation/automation/README.md b/documentation/automation/README.md deleted file mode 100644 index 54c9e1d0d..000000000 --- a/documentation/automation/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# Documentation Automation - -This directory contains automated pipelines for keeping goose documentation synchronized with code changes. - -## Overview - -Each automation project tracks specific types of changes and updates corresponding documentation: - -| Project | Status | Tracks | Updates | -|---------|--------|--------|---------| -| cli-command-tracking | 🔮 Planned | CLI commands & options | CLI documentation | -| provider-tracking | 🔮 Planned | Supported AI providers | Provider documentation | -| extension-tracking | 🔮 Planned | Built-in extensions | Extension documentation | - -## Architecture - -Each automation project follows a consistent pattern: - -``` -project-name/ -├── README.md # Project-specific documentation -├── TESTING.md # How to test this automation -├── config/ # Configuration files -├── scripts/ # Deterministic extraction/diff scripts -└── recipes/ # AI-powered synthesis/update recipes -``` - -### Design Principles - -1. **Modular**: Each project is self-contained -2. **Testable**: Clear inputs/outputs at each stage -3. **Transparent**: Intermediate files can be inspected -4. **Reusable**: Common patterns across projects - -### Hybrid Approach - -- **Shell scripts**: Deterministic extraction and comparison -- **AI recipes**: Synthesis and documentation updates - -## GitHub Actions Integration - -Automation projects can be triggered via GitHub Actions workflows in `.github/workflows/`. - -See individual project TESTING.md files for workflow usage. - -## Adding New Automations - -When creating a new automation project: - -1. Create a subdirectory: `documentation/automation/your-project/` -2. Follow the standard structure (README, TESTING, config, scripts, recipes) -3. Create corresponding GitHub Actions workflow (if needed) -4. Update this README with the new project - -## Questions? - -For project-specific questions, see the README in each project directory. diff --git a/documentation/automation/cli-command-tracking/.gitignore b/documentation/automation/cli-command-tracking/.gitignore deleted file mode 100644 index a04131864..000000000 --- a/documentation/automation/cli-command-tracking/.gitignore +++ /dev/null @@ -1,28 +0,0 @@ -# Output directory - generated files -output/ - -# Python cache -__pycache__/ -*.pyc -*.pyo -*.pyd -.Python - -# Virtual environments -venv/ -env/ -ENV/ - -# IDE -.vscode/ -.idea/ -*.swp -*.swo -*~ - -# OS -.DS_Store -Thumbs.db - -# Logs -*.log diff --git a/documentation/automation/cli-command-tracking/README.md b/documentation/automation/cli-command-tracking/README.md deleted file mode 100644 index f7b8327f7..000000000 --- a/documentation/automation/cli-command-tracking/README.md +++ /dev/null @@ -1,336 +0,0 @@ -# CLI Command Tracking - -Automated pipeline for detecting and documenting CLI command changes between goose releases. - -## Overview - -This automation keeps the [CLI Commands Guide](https://goose-docs.ai/docs/guides/goose-cli-commands) synchronized with code changes by: - -1. **Extracting** CLI structure from goose binary using `--help` output (deterministic) -2. **Detecting** changes between versions (deterministic diff) -3. **Synthesizing** human-readable change documentation (AI-powered) -4. **Updating** the CLI Commands Guide (AI-powered) - -The automation runs automatically on new releases via GitHub Actions, or can be run manually for testing. - -## Quick Start - -### Automated (GitHub Actions) - -The automation runs automatically when a new release is published. See [TESTING.md](./TESTING.md) for testing instructions. - -### Manual (Local Testing) - -```bash -# Set the goose repository path -export GOOSE_REPO=/path/to/goose - -# Run the complete pipeline with auto-detected versions -./scripts/run-pipeline.sh - -# Or specify versions explicitly -./scripts/run-pipeline.sh v1.17.0 v1.19.0 - -# Or run individual steps: -# 1. Extract CLI structures -./scripts/extract-cli-structure.sh v1.17.0 > output/old-cli-structure.json -./scripts/extract-cli-structure.sh v1.19.0 > output/new-cli-structure.json - -# 2. Detect changes -python3 scripts/diff-cli-structures.py output/old-cli-structure.json \ - output/new-cli-structure.json \ - > output/cli-changes.json - -# 3. Generate human-readable change documentation -cd output && goose run --recipe ../recipes/synthesize-cli-changes.yaml - -# 4. Update goose-cli-commands.md -cd output && goose run --recipe ../recipes/update-cli-commands.yaml -``` - -### Version Detection - -The pipeline automatically detects versions when not specified: -- **Old version**: Second-most-recent release tag (via `gh release list`) -- **New version**: Most recent release tag, or `RELEASE_TAG` env var (for CI) -- **Fallback**: Uses git tags if `gh` CLI not available - -To test unreleased changes, explicitly pass `HEAD`: -```bash -./scripts/run-pipeline.sh v1.19.0 HEAD -``` - -## Architecture - -### Modular Pipeline Design - -The automation uses a **hybrid approach**: deterministic scripts for data extraction/diffing, AI recipes for analysis and documentation updates. - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ EXTRACTION (Deterministic) │ -├─────────────────────────────────────────────────────────────────┤ -│ extract-cli-structure.sh → extract-cli-structure.py │ -│ ↓ │ -│ cli-structure.json (commands, options, subcommands, aliases) │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ DIFFING (Deterministic) │ -├─────────────────────────────────────────────────────────────────┤ -│ diff-cli-structures.py │ -│ ↓ │ -│ cli-changes.json (added, removed, modified commands/options) │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ SYNTHESIS (AI-Powered) │ -├─────────────────────────────────────────────────────────────────┤ -│ synthesize-cli-changes.yaml │ -│ ↓ │ -│ cli-changes.md (human-readable) │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ UPDATE (AI-Powered) │ -├─────────────────────────────────────────────────────────────────┤ -│ update-cli-commands.yaml │ -│ ↓ │ -│ goose-cli-commands.md (updated) + update-summary.md │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### Why This Design? - -**Scripts handle deterministic tasks:** -- Building goose from specific git tags -- Running `--help` commands and parsing output -- JSON structure comparison -- No interpretation or inference - direct extraction - -**AI recipes handle synthesis and updates:** -- Analyzing changes and explaining implications -- Generating migration guidance and examples -- Updating documentation with proper formatting and context - -**Benefits:** -- **Reliability**: Extraction is deterministic and reproducible -- **Testability**: Each stage has clear inputs/outputs -- **Maintainability**: Easy to update individual components -- **Transparency**: Intermediate files can be inspected - -### Data Flow - -All stages communicate via JSON/Markdown files in the `output/` directory: - -| File | Producer | Consumer | Purpose | -|------|----------|----------|---------| -| `old-cli-structure.json` | `extract-cli-structure.sh` | `diff-cli-structures.py` | Previous version CLI structure | -| `new-cli-structure.json` | `extract-cli-structure.sh` | `diff-cli-structures.py` | Current version CLI structure | -| `cli-changes.json` | `diff-cli-structures.py` | `synthesize-cli-changes.yaml` | Detected changes (structured) | -| `cli-changes.md` | `synthesize-cli-changes.yaml` | `update-cli-commands.yaml` | Human-readable change documentation | -| `update-summary.md` | `update-cli-commands.yaml` | Human review | Summary of documentation updates | - -## Configuration - -### Environment Variables - -| Variable | Required | Default | Description | -|----------|----------|---------|-------------| -| `GOOSE_REPO` | Yes (local) | - | Path to goose repository root | -| `CLI_COMMANDS_PATH` | No | `$GOOSE_REPO/documentation/docs/guides/goose-cli-commands.md` | Full path to target doc file | -| `RELEASE_TAG` | No | - | Used by GitHub Actions to specify the new version | - -**Example:** -```bash -export GOOSE_REPO=/Users/you/goose -# CLI_COMMANDS_PATH is auto-constructed from GOOSE_REPO -``` - -### Skipped Commands - -Some commands are intentionally excluded from extraction and documentation tracking. These are configured in `config/skip-commands.json`: - -```json -{ - "description": "Commands to skip during extraction (not documented intentionally)", - "skip_commands": [ - { - "name": "term", - "reason": "Terminal integration documented via @goose/@g aliases" - } - ] -} -``` - -To add or remove skipped commands, edit the config file - no code changes required. - -## Scripts - -### `extract-cli-structure.sh` - -Builds goose from a specific git tag and extracts CLI structure using `--help` output. - -**Usage:** -```bash -./scripts/extract-cli-structure.sh [version] > output/cli-structure.json -``` - -**Arguments:** -- `version` (optional): Git tag or commit to extract from (default: HEAD) - -**Output:** JSON with complete command tree including options, subcommands, aliases - -**Example:** -```bash -# Extract from current code -./scripts/extract-cli-structure.sh HEAD > output/new-cli-structure.json - -# Extract from specific version -./scripts/extract-cli-structure.sh v1.15.0 > output/old-cli-structure.json -``` - -### `diff-cli-structures.py` - -Compares two CLI structure files and outputs detected changes. - -**Usage:** -```bash -python3 scripts/diff-cli-structures.py > output/cli-changes.json -``` - -**Arguments:** -- `old-file`: Path to old CLI structure JSON -- `new-file`: Path to new CLI structure JSON - -**Output:** JSON with categorized changes: -- `commands.added`: New commands -- `commands.removed`: Deleted commands -- `commands.modified`: Changed commands (options, description, aliases) -- `breaking_changes`: Categorized breaking changes - -**Example:** -```bash -python3 scripts/diff-cli-structures.py \ - output/old-cli-structure.json \ - output/new-cli-structure.json \ - > output/cli-changes.json -``` - -## Recipes - -### `synthesize-cli-changes.yaml` - -Analyzes detected changes and generates human-readable documentation. - -**Inputs:** -- `output/cli-changes.json` - Detected changes from diff script -- `output/old-cli-structure.json` - Previous version structure -- `output/new-cli-structure.json` - Current version structure - -**Output:** -- `output/cli-changes.md` - Human-readable change documentation with: - - Breaking changes with migration guidance - - New commands with usage examples - - Modified commands with details - - Non-breaking changes summary - -**Usage:** -```bash -cd output -goose run --recipe ../recipes/synthesize-cli-changes.yaml -``` - -### `update-cli-commands.yaml` - -Updates the CLI Commands Guide based on synthesized changes. - -**Inputs:** -- `output/cli-changes.md` - Change documentation from synthesis recipe -- `goose-cli-commands.md` - Target documentation file (path from `CLI_COMMANDS_PATH` or `GOOSE_REPO` env var) - -**Outputs:** -- Updated `goose-cli-commands.md` with changes applied -- `output/update-summary.md` - Summary of changes for review - -**Usage:** -```bash -export CLI_COMMANDS_PATH=/path/to/goose-cli-commands.md -cd output -goose run --recipe ../recipes/update-cli-commands.yaml -``` - -## Directory Structure - -``` -cli-command-tracking/ -├── README.md # This file -├── TESTING.md # Testing guide for GitHub Actions workflow -├── .gitignore # Excludes output/ directory -├── config/ # Configuration files -│ └── skip-commands.json # Commands to exclude from tracking -├── scripts/ # Extraction and diff scripts -│ ├── extract-cli-structure.sh # Wrapper that builds goose and runs Python -│ ├── extract-cli-structure.py # Python script to parse --help output -│ ├── diff-cli-structures.py # Compare structures and detect changes -│ └── run-pipeline.sh # End-to-end pipeline runner -├── recipes/ # AI recipes -│ ├── synthesize-cli-changes.yaml # Generate change docs -│ └── update-cli-commands.yaml # Update documentation -├── .github/workflows/ # GitHub Actions workflow -│ └── docs-update-cli-ref.yml # Workflow definition -└── output/ # Generated files (gitignored) - ├── old-cli-structure.json # Previous version structure - ├── new-cli-structure.json # Current version structure - ├── cli-changes.json # Detected changes (structured) - ├── cli-changes.md # Change documentation (human-readable) - ├── update-summary.md # Documentation update summary - └── pipeline.log # Pipeline execution log -``` - -## GitHub Actions Workflow - -The automation runs via `.github/workflows/docs-update-cli-ref.yml`: - -- **Trigger**: Automatically on new releases, or manually for testing -- **Process**: Builds goose for both versions, extracts CLI structures, detects changes, updates documentation -- **Output**: Creates a PR with updated `goose-cli-commands.md` if changes detected -- **Testing**: See [TESTING.md](./TESTING.md) for detailed testing instructions - -## What Gets Tracked - -### Commands -- ✅ Commands added/removed -- ✅ Command descriptions changed -- ✅ Command aliases added/removed -- ✅ Subcommands added/removed - -### Options -- ✅ Options added/removed -- ✅ Option help text changed -- ✅ Default values changed -- ✅ Possible values changed (enums) -- ✅ Short/long flags changed - -### Breaking Changes (Auto-Categorized) -- Command removed (high severity) -- Option removed (high severity) -- Option renamed (high severity) -- Default value changed (medium severity) -- Enum values removed (high severity) -- Alias removed (medium severity) - -## Maintenance - -When modifying the automation: - -1. **Test locally first**: Run `./scripts/run-pipeline.sh` with test versions -2. **Verify outputs**: Check generated files against actual CLI changes -3. **Test in fork**: Use GitHub Actions workflow with dry-run mode -4. **Document changes**: Update this README with design decisions - -## Related Documentation - -- [TESTING.md](./TESTING.md) - How to test the GitHub Actions workflow -- [Automation Overview](../README.md) - All automation projects -- [CLI Commands Guide](../../docs/guides/goose-cli-commands.md) - Target documentation diff --git a/documentation/automation/cli-command-tracking/TESTING.md b/documentation/automation/cli-command-tracking/TESTING.md deleted file mode 100644 index d3df81957..000000000 --- a/documentation/automation/cli-command-tracking/TESTING.md +++ /dev/null @@ -1,382 +0,0 @@ -# Testing Guide - -This guide explains how to test the CLI command tracking automation locally and in GitHub Actions. - -## Prerequisites - -- Python 3.7+ -- Rust toolchain (for building goose) -- jq (for JSON processing) -- goose CLI installed (for running recipes) -- Git with access to goose repository - -## Local Testing - -### Step 1: Set Up Environment - -```bash -cd /path/to/cli-command-tracking - -# Set the goose repository path -export GOOSE_REPO=/path/to/goose - -# Create output directory -mkdir -p output -``` - -### Step 2: Test Extraction Script - -Test the extraction with a specific version: - -```bash -# Test with a release version -./scripts/extract-cli-structure.sh v1.19.0 > output/test-extraction.json - -# Verify output -jq '.version, .commands | length' output/test-extraction.json - -# Inspect a specific command -jq '.commands[] | select(.name == "session")' output/test-extraction.json - -# Verify skipped commands are excluded -jq '.commands[].name' output/test-extraction.json | grep -v term -``` - -**Expected output:** -- Valid JSON structure -- Version number extracted correctly -- All commands captured (14+ commands, excluding skipped ones like `term`) -- Subcommands nested properly -- Options parsed with all fields - -**Common issues:** -- Rust not installed: Install via rustup -- Build fails: Check Cargo.toml dependencies -- Timeout errors: Increase timeout in script if needed -- Keychain prompt: See "Keychain Access" section below - -### Step 3: Test Diff Script - -Compare two CLI structures: - -```bash -# Extract from two versions -./scripts/extract-cli-structure.sh v1.14.0 > output/old-cli-structure.json -./scripts/extract-cli-structure.sh v1.15.0 > output/new-cli-structure.json - -# Run diff -python3 scripts/diff-cli-structures.py \ - output/old-cli-structure.json \ - output/new-cli-structure.json \ - > output/cli-changes.json - -# Check results -jq '.has_changes, .summary' output/cli-changes.json - -# View specific changes -jq '.changes.commands.added' output/cli-changes.json -jq '.changes.commands.modified[0]' output/cli-changes.json -jq '.breaking_changes' output/cli-changes.json -``` - -**Expected output:** -- `has_changes: true` if versions differ -- Summary with counts of changes -- Detailed changes in structured format -- Breaking changes categorized - -### Step 4: Test AI Synthesis Recipe - -Generate human-readable documentation: - -```bash -cd output - -# Run synthesis recipe -goose run --recipe ../recipes/synthesize-cli-changes.yaml - -# Check output -ls -lh cli-changes.md -head -50 cli-changes.md -``` - -**Expected output:** -- `cli-changes.md` file created -- Markdown formatted properly -- Breaking changes listed first -- Examples provided for complex changes -- When testing AI workflows, ensure any content sent via the `store_comment` tool does not contain triple-backtick code fences (```), even though regular backticks in markdown files like `cli-changes.md` are allowed. - -### Step 5: Test Documentation Update Recipe - -Update the actual documentation: - -```bash -cd output - -# Set path to documentation file -export CLI_COMMANDS_PATH=/path/to/goose/documentation/docs/guides/goose-cli-commands.md - -# Run update recipe -goose run --recipe ../recipes/update-cli-commands.yaml - -# Check outputs -ls -lh update-summary.md -cat update-summary.md - -# Verify documentation was updated -git diff $CLI_COMMANDS_PATH -``` - -### Step 6: Test Full Pipeline - -Run the complete end-to-end pipeline: - -```bash -cd /path/to/cli-command-tracking - -# Set documentation path (optional - only needed for update step) -export CLI_COMMANDS_PATH=/path/to/goose/documentation/docs/guides/goose-cli-commands.md - -# Run pipeline -./scripts/run-pipeline.sh v1.14.0 v1.15.0 - -# Check all outputs -ls -lh output/ -``` - -**Expected output:** -- All intermediate files created -- Pipeline completes without errors -- Summary shows changes detected -- `cli-changes.md` generated - -## GitHub Actions Testing - -### Test in Fork - -1. **Fork the repository** (if not already done) - -2. **Copy automation files** to your fork: - ```bash - cp -r /path/to/cli-command-tracking \ - /path/to/forked-goose/documentation/automation/ - - cp /path/to/goose/.github/workflows/docs-update-cli-ref.yml \ - /path/to/forked-goose/.github/workflows/ - ``` - -3. **Set up secrets** in your fork: - - Go to Settings → Secrets and variables → Actions - - Add `ANTHROPIC_API_KEY` secret - -4. **Set up variables** (optional): - - Add `GOOSE_PROVIDER` variable (default: anthropic) - - Add `GOOSE_MODEL` variable (default: claude-opus-4-5) - -5. **Trigger workflow manually**: - - Go to Actions → "Update CLI Documentation" - - Click "Run workflow" - - Set `dry_run: true` for testing - - Optionally specify versions to compare - -### Dry Run Mode - -Test without creating PR: - -1. Trigger workflow with `dry_run: true` -2. Review outputs in workflow logs -3. Download artifacts to inspect generated files -4. Validate changes are correct - -### Workflow Inputs - -| Input | Description | Default | -|-------|-------------|---------| -| `old_version` | Previous version tag | Auto-detect from releases | -| `new_version` | New version tag | HEAD | -| `dry_run` | Generate files but don't create PR | true | - -### Reviewing Artifacts - -After workflow runs: - -1. Go to the workflow run page -2. Download the artifacts ZIP -3. Extract and review: - - `old-cli-structure.json` - Previous CLI structure - - `new-cli-structure.json` - New CLI structure - - `cli-changes.json` - Detected changes - - `cli-changes.md` - Human-readable documentation - - `pipeline.log` - Execution log - -## Testing with Known Changes - -To validate the automation works correctly, test with versions that have known CLI changes. - -### Finding Test Versions - -```bash -cd /path/to/goose - -# Check git history for CLI changes -git log --oneline --all -- crates/goose-cli/src/cli.rs | head -20 - -# Look for commits that added/removed/modified commands -git show :crates/goose-cli/src/cli.rs | grep "enum Command" -A 30 -``` - -### Test Case: New Command Added - -If you know a version added a new command: - -```bash -./scripts/run-pipeline.sh v1.13.0 v1.14.0 -jq '.changes.commands.added' output/cli-changes.json -``` - -### Test Case: Option Modified - -If you know a version modified options: - -```bash -./scripts/run-pipeline.sh v1.14.0 v1.15.0 -jq '.changes.commands.modified' output/cli-changes.json -``` - -### Test Case: No Changes - -Test with same version (should show no changes): - -```bash -./scripts/run-pipeline.sh v1.14.0 v1.14.0 -jq '.has_changes' output/cli-changes.json -# Should output: false -``` - -## Validation Checklist - -Before considering the automation complete: - -### Extraction Script -- [ ] Handles all command types (simple, with subcommands, with aliases) -- [ ] Parses all option types (short, long, with values, flags) -- [ ] Captures defaults and possible values -- [ ] Works with commands that have no description -- [ ] Handles nested subcommands (2+ levels) -- [ ] Builds goose from git tags correctly - -### Diff Script -- [ ] Detects added commands -- [ ] Detects removed commands -- [ ] Detects modified options -- [ ] Detects changed help text -- [ ] Detects changed defaults -- [ ] Detects changed possible values -- [ ] Categorizes breaking changes correctly - -### AI Recipes -- [ ] Generates readable documentation -- [ ] Provides migration guidance -- [ ] Uses correct markdown formatting -- [ ] Avoids backticks (security constraint) -- [ ] Includes relevant examples -- [ ] Uses text_editor tool to write files - -### Pipeline -- [ ] Runs end-to-end without errors -- [ ] Handles "no changes" case -- [ ] Creates all expected output files -- [ ] Filters goose session output correctly - -### GitHub Actions -- [ ] Workflow triggers correctly -- [ ] Builds goose for both versions -- [ ] Uploads artifacts -- [ ] Creates PR when changes detected -- [ ] Respects dry_run mode -- [ ] Works in forks (fetches upstream tags) - -## Troubleshooting - -### Keychain Access (macOS) - -On macOS, running `goose --help` or `goose --version` may prompt for keychain access. This happens because goose tries to access stored credentials on startup. - -**Local workaround:** Allow the keychain access when prompted. - -**CI consideration:** GitHub Actions runners don't have a keychain, so this may need to be handled. Check existing goose workflows for patterns - there may be a `keyring: false` config option or environment variable to disable credential loading. - -**TODO:** Investigate if this blocks CI execution and document the solution. - -### Build fails for old version - -Some old versions may have different dependencies: - -```bash -# Check if version exists -git tag | grep v1.14.0 - -# Try building manually -git worktree add /tmp/goose-test v1.14.0 -cd /tmp/goose-test -cargo build --release -``` - -### Extraction timeout - -Increase timeout in `extract-cli-structure.py`: - -```python -result = subprocess.run(cmd, capture_output=True, text=True, timeout=30) # Increase from 10 -``` - -### Diff shows unexpected changes - -Check if help text formatting changed: - -```bash -# Compare raw help output -./old-goose session --help > old-help.txt -./new-goose session --help > new-help.txt -diff old-help.txt new-help.txt -``` - -### AI recipe fails - -Check input files exist and are valid: - -```bash -ls -lh output/cli-changes.json output/old-cli-structure.json output/new-cli-structure.json -jq empty output/cli-changes.json # Validates JSON -``` - -### Workflow fails in fork - -Ensure: -- `ANTHROPIC_API_KEY` secret is set -- Upstream tags are fetched (workflow does this automatically) -- Rust toolchain is available - -## Manual Verification - -After automation runs, manually verify: - -1. **Accuracy**: Do detected changes match actual CLI changes? -2. **Completeness**: Are all changes captured? -3. **Documentation**: Is the updated documentation accurate and clear? -4. **Examples**: Do all examples still work? -5. **Style**: Is formatting consistent with existing docs? - -## Test Data - -Keep test data for regression testing: - -```bash -# Save known-good outputs -mkdir -p test-data -cp output/cli-changes.json test-data/v1.14.0-to-v1.15.0-changes.json -cp output/cli-changes.md test-data/v1.14.0-to-v1.15.0-changes.md -``` - -Use these to verify future changes don't break existing functionality. diff --git a/documentation/automation/cli-command-tracking/config/skip-commands.json b/documentation/automation/cli-command-tracking/config/skip-commands.json deleted file mode 100644 index 6b8581b8c..000000000 --- a/documentation/automation/cli-command-tracking/config/skip-commands.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "description": "Commands to skip during extraction (not documented intentionally)", - "skip_commands": [ - { - "name": "term", - "reason": "Terminal integration documented via @goose/@g aliases" - } - ] -} diff --git a/documentation/automation/cli-command-tracking/recipes/synthesize-cli-changes.yaml b/documentation/automation/cli-command-tracking/recipes/synthesize-cli-changes.yaml deleted file mode 100644 index 41e8c7736..000000000 --- a/documentation/automation/cli-command-tracking/recipes/synthesize-cli-changes.yaml +++ /dev/null @@ -1,208 +0,0 @@ -version: "2" -title: "Synthesize CLI Changes" -description: "Generate human-readable documentation for CLI command changes between two versions" - -extensions: - - type: builtin - name: developer - -instructions: | - You are a technical documentation specialist creating release notes for CLI command changes. - - ## Your Task - - Analyze the CLI changes between two goose versions and generate clear, user-focused - documentation explaining what changed and why it matters. - - ## Input Files - - You have access to THREE data sources: - - 1. **cli-changes.json** - The diff (what changed): - - commands: added, removed, modified - - breaking_changes: categorized breaking changes - - summary: high-level statistics - - 2. **old-cli-structure.json** - Before state (for context): - - Complete command structure from old version - - 3. **new-cli-structure.json** - After state (for context): - - Complete command structure from new version - - ## Output Format - - Create a Markdown file (cli-changes.md) with this structure: - - # CLI Command Changes - - **From**: {old_version} - **To**: {new_version} - **Analyzed**: {timestamp} - - ## Summary - - Brief overview of changes (2-3 sentences). - - - Commands added: X - - Commands removed: X - - Commands modified: X - - Breaking changes: X - - ## Breaking Changes - - ⚠️ **Important**: These changes may break existing scripts or workflows. - - List all breaking changes with migration guidance: - - ### Command Removed: **command-name** - - - **Impact**: Users can no longer use this command - - **Migration**: Use **alternative-command** instead - - **Example**: - - # Old way - goose old-command --option value - - # New way - goose new-command --option value - - ### Option Removed: **--option-name** from **command** - - - **Impact**: Scripts using this option will fail - - **Migration**: Use **--new-option** instead or adjust workflow - - ### Default Value Changed: **--option** in **command** - - - **Old default**: value1 - - **New default**: value2 - - **Impact**: Behavior changes when option is omitted - - **Migration**: Explicitly specify the value if you need the old behavior - - ## New Commands - - Commands added in this release: - - ### **command-name** - - - **Description**: What this command does - - **Usage**: goose command-name [OPTIONS] - - **Purpose**: Why this command was added - - **Key Options**: - - **--option1**: Description - - **--option2**: Description - - **Example**: - - goose command-name --option1 value - - ## Removed Commands - - Commands removed in this release: - - ### **command-name** - - - **Reason**: Why it was removed (infer from context) - - **Alternative**: What to use instead - - **Migration**: How to update existing usage - - ## Modified Commands - - Commands with changes in this release: - - ### **command-name** - - **Changes**: - - #### Description Updated - - - **Old**: Previous description - - **New**: New description - - **Impact**: Clarifies command purpose - - #### New Options - - - **--new-option** VALUE: Description and purpose - - #### Removed Options - - - **--old-option**: Was used for X, now use **--new-option** instead - - #### Modified Options - - - **--option-name**: - - Help text updated for clarity - - Default changed from X to Y - - Possible values expanded: added Z - - #### Aliases Changed - - - Added alias: **x** - - Removed alias: **y** - - ## Non-Breaking Changes - - Changes that don't break existing usage: - - - New optional options added - - Help text clarifications - - New aliases added - - Expanded enum values (new possible values) - - ## Analysis Guidelines - - 1. **Focus on User Impact**: Explain changes from user perspective, not implementation details - - 2. **Prioritize Breaking Changes**: These go first and need clear migration guidance - - 3. **Provide Examples**: Show before/after for breaking changes - - 4. **Infer Intent**: Use command names, descriptions, and option names to understand why changes were made - - 5. **Be Specific**: Include concrete details about what changed - - 6. **Group Related Changes**: If multiple options changed in one command, group them together - - 7. **Explain Implications**: Don't just list changes, explain what they mean for users - - 8. **Suggest Alternatives**: For removed features, suggest what to use instead - - 9. **Skip Trivial Changes**: Don't document minor help text formatting changes - - 10. **Use Context**: Reference old and new structures to understand relationships - - ## Special Cases - - - **Empty changes arrays**: If a category has no changes, skip that section entirely - - - **Commands with no description**: Some commands (like **diagnostics**) have empty about fields - this is normal - - - **Alias changes**: Removing aliases might break user muscle memory, note this in breaking changes - - - **Default value changes**: These can be subtle breaking changes if users rely on defaults - - - **Enum expansions**: Adding new possible values is non-breaking, but removing them is breaking - - ## File Locations - - - Input 1: ./cli-changes.json (the diff) - - Input 2: ./old-cli-structure.json (before state) - - Input 3: ./new-cli-structure.json (after state) - - Output: ./cli-changes.md - - Start by reading all THREE input files, then generate the CLI changes documentation. - -prompt: | - Please analyze the CLI changes and generate comprehensive release notes. - - Steps: - 1. Read all THREE input files (cli-changes.json, old-cli-structure.json, new-cli-structure.json) - 2. Analyze the changes - 3. Write the documentation to ./cli-changes.md using the text_editor tool - - Focus on: - - User impact (how does this affect CLI users and scripts?) - - Breaking vs non-breaking changes - - Migration guidance for breaking changes - - Clear, actionable documentation - - Examples for complex changes - - IMPORTANT: You MUST use the text_editor tool to write the output to ./cli-changes.md diff --git a/documentation/automation/cli-command-tracking/recipes/update-cli-commands.yaml b/documentation/automation/cli-command-tracking/recipes/update-cli-commands.yaml deleted file mode 100644 index d3bd0f613..000000000 --- a/documentation/automation/cli-command-tracking/recipes/update-cli-commands.yaml +++ /dev/null @@ -1,222 +0,0 @@ -version: "2" -title: "Update CLI Commands Documentation" -description: "Apply CLI changes to goose-cli-commands.md based on cli-changes.md" - -extensions: - - type: builtin - name: developer - -instructions: | - You are a technical documentation specialist making targeted updates to the CLI Commands Guide to reflect the CURRENT state of the CLI. - - ## ⚠️ GOAL: Document Current State, NOT Change History - - Update docs to show what the CLI looks like NOW. Do NOT document what changed, was removed, or is deprecated. - - Examples: - - Option removed? Delete it from the docs (don't mention it was removed) - - Option added? Add it to the docs (don't mention it's new) - - Option modified? Update to current state (don't mention what it used to be) - - ## 🚨 ABSOLUTE PROHIBITIONS - - 1. **ONLY delete entire command sections** (like `#### bench`, `#### run`) when cli-changes.md explicitly states "Command X was removed" - 2. **NEVER change section headings** (like `### Task Execution`, `### Session Management`) - 3. **NEVER rename options** unless cli-changes.md explicitly documents the rename (e.g., don't change `--with-streamable-http-extension` to something else) - 4. **NEVER duplicate sections** - if a section exists, update it in place - 5. **NEVER remove horizontal rules** (`---`) between sections - 6. **NEVER rewrite examples** - only update the specific flag/option that changed - - ## ⚠️ CRITICAL RULES - - 1. **Only change what's in cli-changes.md** - If not mentioned, don't touch it - 2. **Preserve structure and content** - Keep all existing headings, section organization, formatting, and content intact - 3. **Make surgical edits** - Smallest possible change to achieve the goal - 4. **Use str_replace with old_str/new_str** (NOT diff format) - Include enough context for unique matching, verify old_str matches EXACTLY - 5. Do not copy or reference "Breaking changes" or "Migration guidance" headings from cli-changes.md. Use them only to determine current-state edits - - ## Your Task - - You will update the CLI Commands documentation based on changes in cli-changes.md: - 1. **Command sections** - Add/remove/update command documentation - 2. **Option lists** - Add/remove/update options within commands - 3. **Examples** - Update examples if behavior changed - 4. **Maintain Consistency** - Match existing documentation style - - ## Input Files - - 1. **cli-changes.md** - The change documentation from the pipeline: - - Located at: ./cli-changes.md - - Contains: Command changes, option changes, breaking changes, migration guidance - - 2. **goose-cli-commands.md** - The target documentation file: - - Located at: ${CLI_COMMANDS_PATH} (environment variable) - - Default: ${GOOSE_REPO}/documentation/docs/guides/goose-cli-commands.md - - Contains: Complete CLI reference documentation - - 3. **update-summary.md** - Output file for change summary: - - Located at: ./update-summary.md - - You will create this file to document what was updated - - ## Target Sections in goose-cli-commands.md - - The CLI Commands Guide has this structure: - - Flag Naming Conventions - - Core Commands (configure, info, version, update) - - Session Management (session and subcommands) - - Task Execution (run, bench, recipe, schedule, mcp, acp) - - Interface (web) - - Interactive Session Features (slash commands, themes, etc.) - - **Keep this structure intact** - only update content within sections. - - ## Update Strategy - - ### 1. Read and Analyze - - Read cli-changes.md completely and identify ALL changes documented. - - **CRITICAL**: Only make changes that are explicitly documented in cli-changes.md. - - ### 2. Apply Updates - - For each change documented in cli-changes.md: - - | Change Type | How to Update | - |-------------|---------------| - | **Command added** | Add new command section in appropriate category. Follow existing format with description, options, usage, examples. | - | **Command removed** | Remove entire command section. Check for references elsewhere. | - | **Command description changed** | Update the description text under the command header. | - | **Option added** | Add to the Options list for that command. Include short flag, long flag, description. | - | **Option removed** | Remove from the Options list. | - | **Option modified** | Update the option description, default value, or possible values. | - | **Alias added** | Update command header to show alias (e.g., "**Alias**: x"). | - | **Alias removed** | Remove alias from command header. | - | **Default changed** | Update the default value in the option description. | - | **Possible values changed** | Update the list of valid values. | - - ### 3. Documentation Style - - Follow the existing style in goose-cli-commands.md: - - - **Command headers**: Use #### for command names - - **Options**: Use bullet lists with bold option names - - **Usage blocks**: Use fenced code blocks with language identifier - - **Examples**: Use fenced code blocks with comments - - **Notes**: Use :::info, :::warning, :::tip, :::caution admonitions - - Example format: - - #### command-name - - Brief description of what the command does. - - **Options:** - - **-f, --format FORMAT**: Output format (text, json). Default: text - - **--verbose**: Enable verbose output - - **Usage:** - - # Basic usage - goose command-name - - # With options - goose command-name --format json --verbose - - ### 4. Verification - - After making updates: - - Verify all changes from cli-changes.md are reflected - - Check that no unintended changes were made - - Ensure examples are still valid - - Confirm formatting is consistent - - ## Output Requirements - - ### 1. Updated goose-cli-commands.md - - Apply all changes from cli-changes.md: - - Add new commands in appropriate sections - - Remove deleted commands - - Update modified commands/options - - Preserve all other content - - ### 2. Create update-summary.md - - Generate a summary document: - - # CLI Documentation Update Summary - - **Date**: {current_date} - **Source**: cli-changes.md ({old_version} → {new_version}) - **Target**: goose-cli-commands.md - - ## Changes Applied - - ### Commands Added - - **command-name**: Added to Section Name - - ### Commands Removed - - **command-name**: Removed from Section Name - - ### Commands Modified - - **command-name**: Updated description, added options X and Y - - ## Sections Updated - - - Core Commands: Added X - - Session Management: Updated options for Y - - Task Execution: Modified examples for Z - - ## Verification Checklist - - - [ ] All new commands documented - - [ ] All removed commands deleted - - [ ] All option changes reflected - - [ ] Examples updated and valid - - [ ] No broken references - - [ ] Style consistency maintained - - [ ] No changes outside of cli-changes.md - - ## Notes - - Any special considerations or decisions made during the update. - - ## File Locations Summary - - - Input 1: ./cli-changes.md (change documentation) - - Input 2: ${CLI_COMMANDS_PATH} or ${GOOSE_REPO}/documentation/docs/guides/goose-cli-commands.md - - Output 1: Same as Input 2 (updated in place) - - Output 2: ./update-summary.md (change summary) - - ## Environment Variables - - - CLI_COMMANDS_PATH: Full path to goose-cli-commands.md file (overrides default) - - GOOSE_REPO: Path to goose repository (used if CLI_COMMANDS_PATH not set) - - Start by reading both input files, then apply the updates and generate the summary. - -prompt: | - Update the CLI Commands Guide based on cli-changes.md. - - IMPORTANT: You MUST use the text_editor tool to: - 1. Read cli-changes.md and goose-cli-commands.md - 2. Update goose-cli-commands.md with str_replace - 3. Write update-summary.md - - Remember: - - Document CURRENT state only (not change history) - - Make SURGICAL edits (smallest change needed) - - Only change what's explicitly in cli-changes.md - - Preserve all structure, headings, and content not mentioned in cli-changes.md - - Use EXACT file path from CLI_COMMANDS_PATH environment variable - - Do NOT: - - Rewrite existing descriptions or reorganize sections - - Make "improvements" to content not in cli-changes.md - - Before finalizing, verify: - 1. Did I only change what's in cli-changes.md? - 2. Are all section headings (###, ####) unchanged? - 3. Did I use str_replace with exact matching? - 4. Did I avoid duplicating sections? diff --git a/documentation/automation/cli-command-tracking/scripts/diff-cli-structures.py b/documentation/automation/cli-command-tracking/scripts/diff-cli-structures.py deleted file mode 100755 index 24532bb0a..000000000 --- a/documentation/automation/cli-command-tracking/scripts/diff-cli-structures.py +++ /dev/null @@ -1,355 +0,0 @@ -#!/usr/bin/env python3 -""" -Compare two CLI structure JSON files and output detected changes. - -Usage: - ./diff-cli-structures.py > output/cli-changes.json - -Example: - ./diff-cli-structures.py output/cli-structure-v1.14.0.json \ - output/cli-structure-v1.15.0.json \ - > output/cli-changes.json -""" - -import sys -import json -from datetime import datetime, timezone -from typing import Dict, List - - -def get_command_path(command: Dict, parent_path: str = "") -> str: - """Get the full path of a command (e.g., 'session list').""" - if parent_path: - return f"{parent_path} {command['name']}" - return command['name'] - - -def flatten_commands(commands: List[Dict], parent_path: str = "") -> Dict[str, Dict]: - """ - Flatten nested command structure into a dict keyed by full command path. - - Returns: - Dict mapping command path to command data - """ - result = {} - - for cmd in commands: - cmd_path = get_command_path(cmd, parent_path) - # Store command without subcommands to avoid recursion in comparisons - cmd_copy = cmd.copy() - subcommands = cmd_copy.pop('subcommands', []) - result[cmd_path] = cmd_copy - - # Recursively flatten subcommands - if subcommands: - result.update(flatten_commands(subcommands, cmd_path)) - - return result - - -def compare_options(old_opts: List[Dict], new_opts: List[Dict]) -> Dict: - """ - Compare two lists of options and detect changes. - - Returns dict with: added, removed, modified - """ - # Create dicts keyed by long flag (or short if no long) - old_opts_dict = {opt.get('long') or opt.get('short'): opt for opt in old_opts} - new_opts_dict = {opt.get('long') or opt.get('short'): opt for opt in new_opts} - - old_keys = set(old_opts_dict.keys()) - new_keys = set(new_opts_dict.keys()) - - added = [] - removed = [] - modified = [] - - # Find added options - for key in new_keys - old_keys: - added.append(new_opts_dict[key]) - - # Find removed options - for key in old_keys - new_keys: - removed.append(old_opts_dict[key]) - - # Find modified options - for key in old_keys & new_keys: - old_opt = old_opts_dict[key] - new_opt = new_opts_dict[key] - - changes = {} - - # Check each field for changes - if old_opt.get('short') != new_opt.get('short'): - changes['short'] = {'old': old_opt.get('short'), 'new': new_opt.get('short')} - - if old_opt.get('long') != new_opt.get('long'): - changes['long'] = {'old': old_opt.get('long'), 'new': new_opt.get('long')} - - if old_opt.get('value_name') != new_opt.get('value_name'): - changes['value_name'] = {'old': old_opt.get('value_name'), 'new': new_opt.get('value_name')} - - if old_opt.get('help') != new_opt.get('help'): - changes['help'] = {'old': old_opt.get('help'), 'new': new_opt.get('help')} - - if old_opt.get('default') != new_opt.get('default'): - changes['default'] = {'old': old_opt.get('default'), 'new': new_opt.get('default')} - - if old_opt.get('possible_values') != new_opt.get('possible_values'): - changes['possible_values'] = {'old': old_opt.get('possible_values'), 'new': new_opt.get('possible_values')} - - if changes: - modified.append({ - 'option': key, - 'changes': changes - }) - - return { - 'added': added, - 'removed': removed, - 'modified': modified - } - - -def compare_commands(old_cmds: Dict[str, Dict], new_cmds: Dict[str, Dict]) -> Dict: - """ - Compare two command dictionaries and detect changes. - - Returns dict with: added, removed, modified - """ - old_paths = set(old_cmds.keys()) - new_paths = set(new_cmds.keys()) - - added = [] - removed = [] - modified = [] - - # Find added commands - for path in new_paths - old_paths: - added.append({ - 'command': path, - 'data': new_cmds[path] - }) - - # Find removed commands - for path in old_paths - new_paths: - removed.append({ - 'command': path, - 'data': old_cmds[path] - }) - - # Find modified commands - for path in old_paths & new_paths: - old_cmd = old_cmds[path] - new_cmd = new_cmds[path] - - changes = {} - - # Check about text - if old_cmd.get('about') != new_cmd.get('about'): - changes['about'] = { - 'old': old_cmd.get('about'), - 'new': new_cmd.get('about') - } - - # Check aliases - old_aliases = set(old_cmd.get('aliases', [])) - new_aliases = set(new_cmd.get('aliases', [])) - if old_aliases != new_aliases: - changes['aliases'] = { - 'old': sorted(old_aliases), - 'new': sorted(new_aliases), - 'added': sorted(new_aliases - old_aliases), - 'removed': sorted(old_aliases - new_aliases) - } - - # Check usage - if old_cmd.get('usage') != new_cmd.get('usage'): - changes['usage'] = { - 'old': old_cmd.get('usage'), - 'new': new_cmd.get('usage') - } - - # Check options - option_changes = compare_options( - old_cmd.get('options', []), - new_cmd.get('options', []) - ) - if any(option_changes.values()): - changes['options'] = option_changes - - if changes: - modified.append({ - 'command': path, - 'changes': changes - }) - - return { - 'added': added, - 'removed': removed, - 'modified': modified - } - - -def categorize_breaking_changes(changes: Dict) -> List[Dict]: - """ - Identify changes that are likely breaking changes. - - Returns list of breaking change descriptions. - """ - breaking = [] - - # Removed commands are breaking - for item in changes['commands']['removed']: - breaking.append({ - 'type': 'command_removed', - 'command': item['command'], - 'severity': 'high', - 'description': f"Command '{item['command']}' was removed" - }) - - # Check modified commands for breaking changes - for item in changes['commands']['modified']: - cmd = item['command'] - cmd_changes = item['changes'] - - # Removed options are breaking - if 'options' in cmd_changes: - for opt in cmd_changes['options']['removed']: - opt_name = f"--{opt.get('long')}" if opt.get('long') else f"-{opt.get('short')}" - breaking.append({ - 'type': 'option_removed', - 'command': cmd, - 'option': opt_name, - 'severity': 'high', - 'description': f"Option '{opt_name}' removed from '{cmd}'" - }) - - # Changed option flags are breaking - for mod in cmd_changes['options']['modified']: - if 'short' in mod['changes'] or 'long' in mod['changes']: - breaking.append({ - 'type': 'option_renamed', - 'command': cmd, - 'option': mod['option'], - 'severity': 'high', - 'description': f"Option flags changed in '{cmd}': {mod['option']}" - }) - - # Changed default values might be breaking - if 'default' in mod['changes']: - breaking.append({ - 'type': 'default_changed', - 'command': cmd, - 'option': mod['option'], - 'severity': 'medium', - 'description': f"Default value changed for '{cmd} --{mod['option']}'" - }) - - # Removed possible values are breaking - if 'possible_values' in mod['changes']: - old_vals = set(mod['changes']['possible_values']['old'] or []) - new_vals = set(mod['changes']['possible_values']['new'] or []) - removed_vals = old_vals - new_vals - if removed_vals: - breaking.append({ - 'type': 'enum_values_removed', - 'command': cmd, - 'option': mod['option'], - 'severity': 'high', - 'description': f"Possible values removed from '{cmd} --{mod['option']}': {', '.join(removed_vals)}" - }) - - # Removed aliases might be breaking (users might rely on them) - if 'aliases' in cmd_changes and cmd_changes['aliases']['removed']: - for alias in cmd_changes['aliases']['removed']: - breaking.append({ - 'type': 'alias_removed', - 'command': cmd, - 'alias': alias, - 'severity': 'medium', - 'description': f"Alias '{alias}' removed from '{cmd}'" - }) - - return breaking - - -def main(): - if len(sys.argv) != 3: - print("Usage: diff-cli-structures.py ", file=sys.stderr) - print("Example: diff-cli-structures.py old.json new.json", file=sys.stderr) - sys.exit(1) - - old_file = sys.argv[1] - new_file = sys.argv[2] - - # Load JSON files - try: - with open(old_file, 'r') as f: - old_data = json.load(f) - except Exception as e: - print(f"Error reading {old_file}: {e}", file=sys.stderr) - sys.exit(1) - - try: - with open(new_file, 'r') as f: - new_data = json.load(f) - except Exception as e: - print(f"Error reading {new_file}: {e}", file=sys.stderr) - sys.exit(1) - - print(f"Comparing {old_data['version']} → {new_data['version']}...", file=sys.stderr) - - # Flatten command structures - old_commands = flatten_commands(old_data['commands']) - new_commands = flatten_commands(new_data['commands']) - - print(f"Old version: {len(old_commands)} commands", file=sys.stderr) - print(f"New version: {len(new_commands)} commands", file=sys.stderr) - - # Compare commands - command_changes = compare_commands(old_commands, new_commands) - - # Categorize breaking changes - breaking_changes = categorize_breaking_changes({'commands': command_changes}) - - # Determine if there are any changes - has_changes = ( - len(command_changes['added']) > 0 or - len(command_changes['removed']) > 0 or - len(command_changes['modified']) > 0 - ) - - # Build output - now = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z') - - output = { - 'old_version': old_data['version'], - 'new_version': new_data['version'], - 'compared_at': now, - 'has_changes': has_changes, - 'summary': { - 'commands_added': len(command_changes['added']), - 'commands_removed': len(command_changes['removed']), - 'commands_modified': len(command_changes['modified']), - 'breaking_changes': len([b for b in breaking_changes if b['severity'] == 'high']) - }, - 'changes': { - 'commands': command_changes - }, - 'breaking_changes': breaking_changes - } - - # Output JSON - print(json.dumps(output, indent=2)) - - # Print summary to stderr - print(f"\nSummary:", file=sys.stderr) - print(f" Commands added: {output['summary']['commands_added']}", file=sys.stderr) - print(f" Commands removed: {output['summary']['commands_removed']}", file=sys.stderr) - print(f" Commands modified: {output['summary']['commands_modified']}", file=sys.stderr) - print(f" Breaking changes: {output['summary']['breaking_changes']}", file=sys.stderr) - - -if __name__ == '__main__': - main() diff --git a/documentation/automation/cli-command-tracking/scripts/extract-cli-structure.py b/documentation/automation/cli-command-tracking/scripts/extract-cli-structure.py deleted file mode 100755 index 47cdace86..000000000 --- a/documentation/automation/cli-command-tracking/scripts/extract-cli-structure.py +++ /dev/null @@ -1,363 +0,0 @@ -#!/usr/bin/env python3 -""" -Extract CLI command structure from goose binary using --help output. - -Usage: - ./extract-cli-structure.py > output/cli-structure.json - -Example: - ./extract-cli-structure.py /path/to/goose > output/new-cli-structure.json -""" - -import sys -import subprocess -import json -import re -import os -from datetime import datetime, timezone -from typing import Dict, List, Optional, Tuple - - -def load_skip_commands() -> List[str]: - """Load the list of commands to skip from config file.""" - script_dir = os.path.dirname(os.path.abspath(__file__)) - config_path = os.path.join(script_dir, '..', 'config', 'skip-commands.json') - - try: - with open(config_path, 'r') as f: - config = json.load(f) - return [cmd['name'] for cmd in config.get('skip_commands', [])] - except (FileNotFoundError, json.JSONDecodeError, KeyError) as e: - print(f"Warning: Could not load skip-commands.json: {e}", file=sys.stderr) - return [] - - -SKIP_COMMANDS = load_skip_commands() - - -def run_help_command(binary_path: str, command_path: List[str], short: bool = False) -> str: - """ - Run --help or -h on a command and return the output. - - Args: - binary_path: Path to goose binary - command_path: List of command parts (e.g., ['session', 'list']) - short: If True, use -h instead of --help - - Returns: - Help text output - """ - cmd = [binary_path] + command_path + (['-h'] if short else ['--help']) - try: - result = subprocess.run(cmd, capture_output=True, text=True, timeout=10) - return result.stdout - except subprocess.TimeoutExpired: - print(f"Warning: Command timed out: {' '.join(cmd)}", file=sys.stderr) - return "" - except Exception as e: - print(f"Warning: Failed to run {' '.join(cmd)}: {e}", file=sys.stderr) - return "" - - -def parse_usage_line(help_text: str) -> Optional[str]: - """Extract the usage line from help text.""" - match = re.search(r'^Usage:\s*(.+)$', help_text, re.MULTILINE) - return match.group(1).strip() if match else None - - -def parse_about(help_text: str) -> str: - """Extract the command description (first line before Usage).""" - lines = help_text.strip().split('\n') - - # Find the Usage: line - usage_index = -1 - for i, line in enumerate(lines): - if line.strip().startswith('Usage:'): - usage_index = i - break - - # If Usage is found, look for description before it - if usage_index > 0: - for i in range(usage_index): - line = lines[i].strip() - if line and not line.startswith('Options:') and not line.startswith('Commands:'): - return line - - return "" - - -def parse_aliases(help_text: str) -> List[str]: - """Extract command aliases from help text.""" - # Look for "[aliases: x, y]" pattern in the first few lines - match = re.search(r'\[aliases?:\s*([^\]]+)\]', help_text[:500]) - if match: - aliases_str = match.group(1) - return [a.strip() for a in aliases_str.split(',')] - return [] - - -def parse_options(help_text: str) -> List[Dict]: - """ - Parse options from the Options: section of help text. - - Returns list of option dicts with: short, long, value_name, help, default, possible_values - """ - options = [] - - # Find the Options: section - goes until Commands: section or end of text - # Note: clap help has blank lines between options, so we can't stop at ^$ - options_match = re.search(r'^Options:\s*\n(.+?)(?=^Commands:\s*$|\Z)', - help_text, re.MULTILINE | re.DOTALL) - if not options_match: - return options - - options_text = options_match.group(1) - - # Split into individual option blocks - # Each option starts with whitespace followed by a dash (short or long flag) - # Use lookahead to split at lines that start a new option - option_blocks = re.split(r'\n(?=\s+-)', options_text) - - for block in option_blocks: - block = block.strip() - if not block or not block.startswith('-'): - continue - - option = parse_option_block(block) - if option: - options.append(option) - - return options - - -def parse_option_block(block: str) -> Optional[Dict]: - """Parse a single option block into structured data.""" - lines = block.split('\n') - if not lines: - return None - - # First line has the flags, optional value name, and sometimes inline help (common clap output) - first_line = lines[0].strip() - inline_help = None - - # Split on 2+ spaces to separate flags from inline help text. - # Example: "-o, --output Write output to file" - parts = re.split(r'\s{2,}', first_line, maxsplit=1) - flags_part = parts[0] - if len(parts) == 2: - inline_help = parts[1].strip() or None - - # Extract short flag (e.g., -f) - short_match = re.search(r'-([a-zA-Z])\b', flags_part) - short = short_match.group(1) if short_match else None - - # Extract long flag (e.g., --format) - long_match = re.search(r'--([a-z][a-z0-9-]*)', flags_part) - long = long_match.group(1) if long_match else None - - # Extract value_name (e.g., ) - value_name_match = re.search(r'<([^>]+)>', flags_part) - value_name = value_name_match.group(1) if value_name_match else None - - # Collect help text from subsequent indented lines - help_lines = [] - for line in lines[1:]: - line = line.strip() - if line and not line.startswith('['): - help_lines.append(line) - elif line.startswith('['): - # This might be [default: ...] or [possible values: ...] - break - - help_text = ' '.join(help_lines) - - if inline_help: - help_text = f"{inline_help} {help_text}".strip() if help_text else inline_help - - # Extract default value - default = None - default_match = re.search(r'\[default:\s*([^\]]+)\]', block) - if default_match: - default = default_match.group(1).strip() - - # Extract possible values - possible_values = None - possible_match = re.search(r'\[possible values:\s*([^\]]+)\]', block) - if possible_match: - values_str = possible_match.group(1) - possible_values = [v.strip() for v in values_str.split(',')] - - return { - 'short': short, - 'long': long, - 'value_name': value_name, - 'help': help_text if help_text else None, - 'default': default, - 'possible_values': possible_values - } - - -def parse_subcommands(help_text: str) -> List[Tuple[str, List[str]]]: - """ - Extract subcommand names and their aliases from the Commands: section. - - Returns: - List of tuples: (command_name, [aliases]) - """ - commands = [] - - # Find the Commands: section - commands_match = re.search(r'^Commands:\s*$(.+?)(?:^Options:|\Z)', - help_text, re.MULTILINE | re.DOTALL) - if not commands_match: - return commands - - commands_text = commands_match.group(1) - - # Each command line starts with the command name (not indented or minimally indented) - for raw_line in commands_text.split('\n'): - # Preserve indentation to avoid mis-parsing wrapped description lines. - # In clap help, actual command entries are typically not indented. - if not raw_line.strip(): - continue - - if raw_line.startswith(' ') or raw_line.startswith('\t'): - continue - - line = raw_line.strip() - - # Extract command name (first word) - parts = line.split() - if parts and not parts[0].startswith('-'): - command_name = parts[0] - # Skip "help" command as it's auto-generated - if command_name == 'help': - continue - - # Extract aliases from [aliases: x, y] pattern - aliases = [] - alias_match = re.search(r'\[aliases?:\s*([^\]]+)\]', line) - if alias_match: - aliases_str = alias_match.group(1) - aliases = [a.strip() for a in aliases_str.split(',')] - - commands.append((command_name, aliases)) - - return commands - - -def extract_command_structure(binary_path: str, command_path: List[str] = None, - parent_aliases: List[str] = None) -> Dict: - """ - Recursively extract command structure starting from a command path. - - Args: - binary_path: Path to goose binary - command_path: Current command path (e.g., ['session', 'list']) - parent_aliases: Aliases passed from parent (since they appear in parent's help) - - Returns: - Dict with command structure - """ - if command_path is None: - command_path = [] - - # Get both short and long help - help_text_long = run_help_command(binary_path, command_path, short=False) - - if not help_text_long: - return None - - # Parse command info - command_name = command_path[-1] if command_path else "goose" - about = parse_about(help_text_long) - # Use parent_aliases if provided, otherwise try to parse from own help - aliases = parent_aliases if parent_aliases is not None else parse_aliases(help_text_long) - usage = parse_usage_line(help_text_long) - options = parse_options(help_text_long) - - # Get subcommands with their aliases and recursively process them - subcommand_info = parse_subcommands(help_text_long) - subcommands = [] - - for subcommand_name, subcommand_aliases in subcommand_info: - # Skip commands in the skip list - if subcommand_name in SKIP_COMMANDS: - print(f"Skipping command: {subcommand_name}", file=sys.stderr) - continue - sub_path = command_path + [subcommand_name] - sub_structure = extract_command_structure(binary_path, sub_path, subcommand_aliases) - if sub_structure: - subcommands.append(sub_structure) - - return { - 'name': command_name, - 'about': about, - 'aliases': aliases, - 'usage': usage, - 'options': options, - 'subcommands': subcommands - } - - -def extract_version(binary_path: str) -> str: - """Extract version from goose --version.""" - try: - result = subprocess.run([binary_path, '--version'], - capture_output=True, text=True, timeout=5) - # Output is typically "goose 1.15.0" or similar - version_match = re.search(r'(\d+\.\d+\.\d+)', result.stdout) - return version_match.group(1) if version_match else "unknown" - except Exception as e: - print(f"Warning: Could not extract version: {e}", file=sys.stderr) - return "unknown" - - -def main(): - if len(sys.argv) < 2: - print("Usage: extract-cli-structure.py [source-version]", file=sys.stderr) - print("Example: extract-cli-structure.py /usr/local/bin/goose v1.15.0", file=sys.stderr) - sys.exit(1) - - binary_path = sys.argv[1] - source_version = sys.argv[2] if len(sys.argv) > 2 else None - - # Verify binary exists and is executable - try: - result = subprocess.run([binary_path, '--version'], - capture_output=True, timeout=5) - if result.returncode != 0: - print(f"Error: {binary_path} is not a valid goose binary", file=sys.stderr) - sys.exit(1) - except Exception as e: - print(f"Error: Cannot execute {binary_path}: {e}", file=sys.stderr) - sys.exit(1) - - print("Extracting CLI structure...", file=sys.stderr) - - # Extract version - version = extract_version(binary_path) - print(f"Version: {version}", file=sys.stderr) - - # Extract root command structure (recursively includes all subcommands) - root_structure = extract_command_structure(binary_path, []) - - # Build output JSON - # Use timezone-aware UTC datetime (Python 3.7+) - now = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z') - - output = { - 'version': version, - 'source_version': source_version or version, - 'extracted_at': now, - 'binary_path': binary_path, - 'commands': root_structure['subcommands'] if root_structure else [] - } - - # Output JSON - print(json.dumps(output, indent=2)) - print("Extraction complete!", file=sys.stderr) - - -if __name__ == '__main__': - main() diff --git a/documentation/automation/cli-command-tracking/scripts/extract-cli-structure.sh b/documentation/automation/cli-command-tracking/scripts/extract-cli-structure.sh deleted file mode 100755 index af220a000..000000000 --- a/documentation/automation/cli-command-tracking/scripts/extract-cli-structure.sh +++ /dev/null @@ -1,115 +0,0 @@ -#!/bin/bash -# Extract CLI command structure from goose at a specific version -# Usage: ./extract-cli-structure.sh -# Example: ./extract-cli-structure.sh v1.15.0 -# -# For tagged releases (v*), downloads pre-built binary from GitHub releases. -# For HEAD or non-release refs, builds from source. - -set -e -set -o pipefail - -VERSION=${1:-"HEAD"} -GOOSE_REPO=${GOOSE_REPO:-"$HOME/Development/goose"} -SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" - -# Create a temporary directory -TEMP_DIR=$(mktemp -d) -trap "rm -rf $TEMP_DIR" EXIT - -# Check if version is a release tag (starts with 'v' followed by numbers) -is_release_tag() { - [[ "$1" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] -} - -# Download pre-built binary for a release version -download_release_binary() { - local version=$1 - local safe_version=${version//\//-} - local bin_dir="$TEMP_DIR/bin" - mkdir -p "$bin_dir" - - echo "Downloading goose $version from GitHub releases..." >&2 - - # Use the official download script with custom bin dir and specific version - curl -fsSL "https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh" | \ - CONFIGURE=false GOOSE_BIN_DIR="$bin_dir" GOOSE_VERSION="$version" bash >&2 2>&1 || { - echo "Error: Failed to download goose $version" >&2 - return 1 - } - - echo "$bin_dir/goose" -} - -# Build goose from source -build_from_source() { - local version=$1 - local safe_version=${version//\//-} - - if [ ! -d "$GOOSE_REPO" ]; then - echo "Error: GOOSE_REPO directory not found: $GOOSE_REPO" >&2 - exit 1 - fi - - cd "$GOOSE_REPO" - - if [ "$version" = "HEAD" ]; then - echo "Building goose from HEAD..." >&2 - cargo build --release --quiet >&2 2>&1 || { - echo "Error: Failed to build goose from HEAD" >&2 - return 1 - } - echo "$GOOSE_REPO/target/release/goose" - else - # Verify version exists - if ! git rev-parse "$version" >/dev/null 2>&1; then - echo "Error: Version $version not found in git history" >&2 - return 1 - fi - - echo "Building goose from $version..." >&2 - - # Create a worktree for the version - local worktree_dir="$TEMP_DIR/goose-$safe_version" - git worktree add --quiet "$worktree_dir" "$version" >&2 2>&1 || { - echo "Error: Failed to create worktree for $version" >&2 - return 1 - } - - cd "$worktree_dir" - cargo build --release --quiet >&2 2>&1 || { - echo "Error: Failed to build goose from $version" >&2 - cd "$GOOSE_REPO" - git worktree remove "$worktree_dir" 2>/dev/null || true - return 1 - } - - # Clean up worktree but keep the binary accessible - local bin_path="$worktree_dir/target/release/goose" - local temp_bin="$TEMP_DIR/goose-$safe_version-bin" - cp "$bin_path" "$temp_bin" - - cd "$GOOSE_REPO" - git worktree remove "$worktree_dir" 2>/dev/null || true - - echo "$temp_bin" - fi -} - -# Get the goose binary -if is_release_tag "$VERSION"; then - GOOSE_BIN=$(download_release_binary "$VERSION") -else - GOOSE_BIN=$(build_from_source "$VERSION") -fi - -if [ -z "$GOOSE_BIN" ] || [ ! -x "$GOOSE_BIN" ]; then - echo "Error: Goose binary not found or not executable" >&2 - exit 1 -fi - -echo "Using binary: $GOOSE_BIN" >&2 -echo "Binary version: $($GOOSE_BIN --version 2>&1)" >&2 - -# Run the Python extraction script -python3 "$SCRIPT_DIR/extract-cli-structure.py" "$GOOSE_BIN" "$VERSION" diff --git a/documentation/automation/cli-command-tracking/scripts/run-pipeline.sh b/documentation/automation/cli-command-tracking/scripts/run-pipeline.sh deleted file mode 100755 index 8e051755c..000000000 --- a/documentation/automation/cli-command-tracking/scripts/run-pipeline.sh +++ /dev/null @@ -1,194 +0,0 @@ -#!/bin/bash -# End-to-end pipeline for CLI command tracking -# Usage: ./run-pipeline.sh [old_version] [new_version] -# Example: ./run-pipeline.sh v1.17.0 v1.19.0 -# -# Version detection: -# - If old_version not provided: uses the second-most-recent release tag -# - If new_version not provided: uses the most recent release tag (or RELEASE_TAG env var) -# - HEAD is only used when explicitly passed for testing unreleased changes - -set -e - -GOOSE_REPO=${GOOSE_REPO:-"$HOME/Development/goose"} - -# Function to get release tags using gh CLI -get_latest_release() { - if command -v gh &> /dev/null; then - gh release list --repo aaif-goose/goose --limit 1 --json tagName --jq '.[0].tagName' 2>/dev/null - else - # Fallback: get latest version tag from git - cd "$GOOSE_REPO" && git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1 - fi -} - -get_previous_release() { - if command -v gh &> /dev/null; then - gh release list --repo aaif-goose/goose --limit 2 --json tagName --jq '.[].tagName' 2>/dev/null | sed -n '2p' - else - # Fallback: get second-latest version tag from git - cd "$GOOSE_REPO" && git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sed -n '2p' - fi -} - -# Determine versions -if [ -n "$1" ]; then - OLD_VERSION="$1" -else - OLD_VERSION=$(get_previous_release) - if [ -z "$OLD_VERSION" ]; then - echo "Error: Could not determine previous release version" >&2 - exit 1 - fi -fi - -if [ -n "$2" ]; then - NEW_VERSION="$2" -elif [ -n "$RELEASE_TAG" ]; then - # Used by GitHub Actions release trigger - NEW_VERSION="$RELEASE_TAG" -else - NEW_VERSION=$(get_latest_release) - if [ -z "$NEW_VERSION" ]; then - echo "Error: Could not determine latest release version" >&2 - exit 1 - fi -fi - -echo "==========================================" -echo "CLI Command Documentation Pipeline" -echo "==========================================" -echo "Old Version: $OLD_VERSION" -echo "New Version: $NEW_VERSION" -echo "" - -SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" - -# Change to output directory -OUTPUT_DIR="$SCRIPT_DIR/../output" -mkdir -p "$OUTPUT_DIR" -cd "$OUTPUT_DIR" - -# Use a per-run temp directory for logs to avoid collisions -LOG_DIR=$(mktemp -d) -trap 'rm -rf "$LOG_DIR"' EXIT - -echo "Step 1: Extracting CLI structure from $OLD_VERSION..." -if ! ../scripts/extract-cli-structure.sh "$OLD_VERSION" > old-cli-structure.json 2>"$LOG_DIR/extract-old.log"; then - echo "✗ Failed to extract CLI structure from $OLD_VERSION" >&2 - echo "Error output:" >&2 - cat "$LOG_DIR/extract-old.log" >&2 - exit 1 -fi -echo "✓ Extracted $(jq '.commands | length' old-cli-structure.json) commands" - -echo "" -echo "Step 2: Extracting CLI structure from $NEW_VERSION..." -if ! ../scripts/extract-cli-structure.sh "$NEW_VERSION" > new-cli-structure.json 2>"$LOG_DIR/extract-new.log"; then - echo "✗ Failed to extract CLI structure from $NEW_VERSION" >&2 - echo "Error output:" >&2 - cat "$LOG_DIR/extract-new.log" >&2 - exit 1 -fi -echo "✓ Extracted $(jq '.commands | length' new-cli-structure.json) commands" - -echo "" -echo "Step 3: Comparing CLI structures..." -python3 ../scripts/diff-cli-structures.py old-cli-structure.json new-cli-structure.json > cli-changes.json 2>"$LOG_DIR/diff.log" - -HAS_CHANGES=$(jq -r '.has_changes' cli-changes.json) -echo "✓ Comparison complete. Has changes: $HAS_CHANGES" - -if [ "$HAS_CHANGES" = "true" ]; then - echo "" - echo "Changes detected:" - echo " - Commands added: $(jq '.summary.commands_added' cli-changes.json)" - echo " - Commands removed: $(jq '.summary.commands_removed' cli-changes.json)" - echo " - Commands modified: $(jq '.summary.commands_modified' cli-changes.json)" - echo " - Breaking changes: $(jq '.summary.breaking_changes' cli-changes.json)" - - echo "" - echo "Step 4: Synthesizing CLI changes documentation..." - - # Run goose and capture output, filtering out session logs - goose run --recipe ../recipes/synthesize-cli-changes.yaml 2>&1 | \ - sed -E 's/\x1B\[[0-9;]*[mK]//g' | \ - grep -v "^starting session" | \ - grep -v "^ session id:" | \ - grep -v "^ working directory:" | \ - grep -v "^─── text_editor" | \ - grep -v "^path:" | \ - grep -v "^command:" | \ - grep -v "^Closing session" | \ - grep -v "^Loading recipe:" | \ - grep -v "^Description:" | \ - cat -s > cli-changes.md.tmp - - # If the pipeline fails, surface the goose error (grep can exit 1 when it matches nothing) - if [ ${PIPESTATUS[0]} -ne 0 ]; then - echo "✗ Failed to synthesize CLI changes (goose run failed)" >&2 - exit 1 - fi - - # Check if we got meaningful content - if [ -s cli-changes.md.tmp ] && grep -q "# CLI Command Changes" cli-changes.md.tmp; then - mv cli-changes.md.tmp cli-changes.md - echo "✓ Generated cli-changes.md ($(wc -l < cli-changes.md) lines)" - elif [ -f cli-changes.md ] && [ -s cli-changes.md ]; then - # File was written directly by goose - rm -f cli-changes.md.tmp - echo "✓ Generated cli-changes.md ($(wc -l < cli-changes.md) lines)" - else - echo "✗ Failed to generate cli-changes.md" - rm -f cli-changes.md.tmp - exit 1 - fi - - echo "" - echo "Step 5: Updating CLI commands documentation..." - - # Set environment variables for the update recipe - export CLI_COMMANDS_PATH="${GOOSE_REPO}/documentation/docs/guides/goose-cli-commands.md" - - # Run the update recipe - goose run --recipe ../recipes/update-cli-commands.yaml 2>&1 | \ - sed -E 's/\x1B\[[0-9;]*[mK]//g' | \ - grep -v "^starting session" | \ - grep -v "^ session id:" | \ - grep -v "^ working directory:" | \ - grep -v "^─── text_editor" | \ - grep -v "^path:" | \ - grep -v "^command:" | \ - grep -v "^Closing session" | \ - grep -v "^Loading recipe:" | \ - grep -v "^Description:" | \ - cat -s - - if [ ${PIPESTATUS[0]} -ne 0 ]; then - echo "✗ Failed to update documentation (goose run failed)" >&2 - exit 1 - fi - - echo "✓ Documentation update complete" - - echo "" - echo "==========================================" - echo "Pipeline Complete!" - echo "==========================================" - echo "" - echo "Output files:" - echo " - old-cli-structure.json" - echo " - new-cli-structure.json" - echo " - cli-changes.json" - echo " - cli-changes.md" - echo "" - echo "Review the changes to the CLI commands documentation." -else - echo "" - echo "==========================================" - echo "No Changes Detected" - echo "==========================================" - echo "" - echo "No CLI changes between $OLD_VERSION and $NEW_VERSION." - echo "Documentation update not needed." -fi diff --git a/documentation/blog/2025-12-28-goose-maintains-goose/index.md b/documentation/blog/2025-12-28-goose-maintains-goose/index.md index 0831682a5..46e400fe9 100644 --- a/documentation/blog/2025-12-28-goose-maintains-goose/index.md +++ b/documentation/blog/2025-12-28-goose-maintains-goose/index.md @@ -15,7 +15,7 @@ We embraced this reality and put goose to work on its own backlog. -We actually used goose pre-1.0 to help us build goose 1.0. The original goose was a Python CLI, but we needed to move quickly to Rust, Electron, and an [MCP-native](https://modelcontextprotocol.io) architecture. goose helped us make that transition. Using it to triage issues and review changes felt like a natural extension, so we embedded goose directly into a [GitHub Action](https://github.com/aaif-goose/goose/blob/main/.github/workflows/goose-issue-solver.yml). +We actually used goose pre-1.0 to help us build goose 1.0. The original goose was a Python CLI, but we needed to move quickly to Rust, Electron, and an [MCP-native](https://modelcontextprotocol.io) architecture. goose helped us make that transition. Using it to triage issues and review changes felt like a natural extension, so we embedded goose directly into a [GitHub Action](https://github.com/aaif-goose/goose/blob/c525364c33753ce6e077a33da1e2bd738a7e653c/.github/workflows/goose-issue-solver.yml). :::note Credit That GitHub Action workflow was built by [Tyler Longwell](https://github.com/tlongwell-block), who took an idea we had been exploring manually and turned it into something any maintainer could trigger with a single comment. @@ -59,7 +59,7 @@ Maintainers summon goose with `/goose` followed by a prompt as a comment on an i But there's more happening under the hood than a simple prompt like "/goose fix this." -The workflow uses a [recipe](https://github.com/aaif-goose/goose/blob/main/.github/workflows/goose-issue-solver.yml#L14-L78) that defines phases to ensure goose actually accomplishes the job and doesn't do more than we ask it to. +The workflow uses a [recipe](https://github.com/aaif-goose/goose/blob/c525364c33753ce6e077a33da1e2bd738a7e653c/.github/workflows/goose-issue-solver.yml#L14-L78) that defines phases to ensure goose actually accomplishes the job and doesn't do more than we ask it to. | Phase | What goose does | Why it matters | | ---------- | ----------------------------------------------------- | --------------------------------------------------------------------- | @@ -70,7 +70,7 @@ The workflow uses a [recipe](https://github.com/aaif-goose/goose/blob/main/.gith | Verify | Run tests and linters | Catches obvious failures before a human sees the PR | | Confirm | Reread the original issue and requirements | Prevents the AI from declaring victory while forgetting half the task | -The [recipe](https://github.com/aaif-goose/goose/blob/main/.github/workflows/goose-issue-solver.yml) also gives goose access to the [TODO extension](/docs/mcp/todo-mcp), a built-in tool that acts as external memory. The phases tell goose *what* to do. The TODO helps goose *remember* what it's doing. As goose reads through the codebase and builds a solution, its context window fills up and earlier instructions can be compressed or lost. The TODO persists, so goose can always check what it's done and what's left. +The [recipe](https://github.com/aaif-goose/goose/blob/c525364c33753ce6e077a33da1e2bd738a7e653c/.github/workflows/goose-issue-solver.yml) also gives goose access to the [TODO extension](/docs/mcp/todo-mcp), a built-in tool that acts as external memory. The phases tell goose *what* to do. The TODO helps goose *remember* what it's doing. As goose reads through the codebase and builds a solution, its context window fills up and earlier instructions can be compressed or lost. The TODO persists, so goose can always check what it's done and what's left. The workflow also enforces guardrails around who can invoke `/goose`, which files it's allowed to touch, and the requirement that a maintainer review and approve every PR. @@ -80,7 +80,7 @@ The future we're aiming for isn't one where AI replaces maintainers. It's one wh If that becomes the norm, open source scales differently. -The [GitHub Action workflow](https://github.com/aaif-goose/goose/blob/main/.github/workflows/goose-issue-solver.yml) is public for anyone who wants to explore this pattern in their own CI pipeline. +The [GitHub Action workflow](https://github.com/aaif-goose/goose/blob/c525364c33753ce6e077a33da1e2bd738a7e653c/.github/workflows/goose-issue-solver.yml) is public for anyone who wants to explore this pattern in their own CI pipeline.