ci: auto-sync tools.json on merge instead of failing PRs (#849)

* ci: auto-sync tools.json on merge instead of failing PRs

Move tools.json sync enforcement from a PR-time unit test to a
post-merge workflow. The test_docs_in_sync check (added in #839)
causes false CI failures on any PR that touches tool source files
when another tool PR merges first — and since the repo doesn't
require branches to be up-to-date before merging, stale tools.json
silently lands on master anyway.

New approach:
- sync-tool-docs.yml runs on push to master when tool source files
  or the extract script change, regenerates tools.json + README, and
  commits if there's a diff (using the same GitHub App token pattern
  as the existing changelog sync in semver-release.yml)
- test_docs_in_sync removed from unit tests (was advisory anyway —
  not in required status checks)
- test_no_legacy_tags_in_annotations kept — still validates tool
  source conventions at PR time

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: add concurrency group and fix push logic in sync workflow

- Add concurrency group to prevent race conditions when multiple
  tool PRs merge in quick succession
- Fix commit/push logic to use if/fi block instead of chained ||
  (the original pattern would never push because staged changes
  are gone after commit)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kingpanther13

.github/workflows/sync-tool-docs.yml

@@ -0,0 +1,57 @@
+name: Sync Tool Documentation
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'src/ha_mcp/tools/**'
+      - 'scripts/extract_tools.py'
+
+# Restrict permissions by default
+permissions:
+  contents: read
+
+# Prevent overlapping runs if multiple tool PRs merge in quick succession
+concurrency:
+  group: sync-tool-docs
+  cancel-in-progress: true
+
+jobs:
+  sync-tools-json:
+    name: Regenerate tools.json & README
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    timeout-minutes: 2
+
+    steps:
+    - name: Generate GitHub App token
+      id: app-token
+      uses: actions/create-github-app-token@v3
+      with:
+        app-id: ${{ secrets.RELEASE_APP_ID }}
+        private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+      continue-on-error: true
+
+    - uses: actions/checkout@v6
+      with:
+        # Use app token to bypass branch protection ruleset
+        token: ${{ steps.app-token.outputs.token || secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.13'
+
+    - name: Regenerate tool documentation
+      run: python scripts/extract_tools.py
+
+    - name: Commit and push if changed
+      run: |
+        git config user.name "github-actions[bot]"
+        git config user.email "github-actions[bot]@users.noreply.github.com"
+        git add site/src/data/tools.json README.md
+        if ! git diff --staged --quiet; then
+          git commit -m "chore(internal): sync tool docs after merge [skip ci]"
+          git push
+        fi

tests/src/unit/test_tool_docs_sync.py

@@ -1,18 +1,19 @@
-"""Tests that tool documentation artifacts stay in sync with source code.
+"""Tests that tool source code follows documentation conventions.
 
-Run `python scripts/extract_tools.py` to regenerate if this fails.
+Legacy tag detection ensures tools use native FastMCP tags parameter.
+Sync enforcement (tools.json ↔ source) is handled by the post-merge
+sync-tool-docs.yml workflow rather than a PR-time unit test, because
+PRs that pass CI can go stale when other tool PRs merge first.
 """
 
 import re
-import subprocess
-import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).parent.parent.parent.parent
 
 
 class TestToolDocsSync:
-    """README.md and tools.json must stay in sync with tool source code."""
+    """Tool source code must follow documentation conventions."""
 
     def test_no_legacy_tags_in_annotations(self):
         """Tags should be native FastMCP parameter, not inside annotations dict."""
@@ -34,23 +35,3 @@ def test_no_legacy_tags_in_annotations(self):
             + "\n".join(f"  - {loc}" for loc in legacy)
             + "\n\nUse tags={'Category'} as a direct @mcp.tool() parameter instead."
         )
-
-    def test_docs_in_sync(self):
-        """Verify generated artifacts match current tool definitions.
-
-        If this fails, run: python scripts/extract_tools.py
-        """
-        result = subprocess.run(
-            [sys.executable, "scripts/extract_tools.py", "--check"],
-            capture_output=True,
-            text=True,
-            cwd=str(REPO_ROOT),
-            timeout=30,
-        )
-
-        assert result.returncode == 0, (
-            "Tool documentation is out of sync with source code.\n\n"
-            + result.stderr
-            + "\nRun this command to fix:\n"
-            + "  python scripts/extract_tools.py\n"
-        )