feat: run reusable skill checks and prepare repair patches

.changeset/reusable-check-workflow.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/intent': patch
+---
+
+Run skill checks through reusable GitHub workflows pinned to the immutable commit packaged with the installed Intent release. Setup validates generated workflow inputs and write paths before copying files. Analysis uses the repository's locked CLI, disables dependency lifecycle scripts, and has read permissions. Optional review publication runs separately with bounded report validation.
+
+The PR workflow runs one combined validation check and can prepare mechanical repairs and suggested example patches for review. It retains the patches when validation fails and never publishes fixes or marks semantic reviews complete. `intent maintainer check --github-summary` reports authoring issues, stale generated files, and pending source reviews in the GitHub Actions step summary.
+
+Validation counts each skill once across overlapping custom roots and avoids duplicate packaging warnings for the same skill.

.github/workflows/check-skills.yml

@@ -0,0 +1,187 @@
+# Reusable workflow behind the pull-request job of a library repository's
+# check-skills.yml. The caller pins this file to an Intent release commit and
+# grants the job `contents: read` only. No publishing credentials are supplied;
+# read access still includes the checked-out repository contents.
+#
+# Intent itself runs from the repository's own lockfile-pinned copy, so a
+# malicious npm publish does nothing until the maintainer merges a bump. The
+# `intent-version` input opts into a registry install instead.
+
+name: Check Skills
+
+on:
+  workflow_call:
+    inputs:
+      repair:
+        description: Prepare mechanical repairs and reviewable example patches without publishing changes
+        type: boolean
+        default: false
+      artifacts:
+        description: Repository-relative planning directory when using the maintainer workflow
+        type: string
+        default: ''
+      intent-version:
+        description: Exact npm version of @tanstack/intent to install instead of the repository's own copy
+        type: string
+        default: ''
+      node-version:
+        description: Node.js version for the checks
+        type: string
+        default: '22'
+
+permissions: {}
+
+jobs:
+  validate:
+    name: Validate intent skills
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Detect package manager
+        id: manager
+        env:
+          INTENT_VERSION: ${{ inputs.intent-version }}
+        run: |
+          manager=''
+          if [ -z "$INTENT_VERSION" ]; then
+            if [ -f bun.lock ] || [ -f bun.lockb ]; then manager=bun
+            elif [ -f pnpm-lock.yaml ]; then manager=pnpm
+            elif [ -f yarn.lock ]; then manager=yarn
+            elif [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then manager=npm
+            fi
+          fi
+          if [ "$manager" = pnpm ] || [ "$manager" = yarn ]; then corepack enable; fi
+          cache="$manager"
+          if [ "$manager" = bun ]; then cache=''; fi
+          echo "manager=$manager" >> "$GITHUB_OUTPUT"
+          echo "cache=$cache" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: ${{ inputs.node-version }}
+          cache: ${{ steps.manager.outputs.cache }}
+
+      - name: Setup Bun
+        if: steps.manager.outputs.manager == 'bun'
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+
+      - name: Install intent
+        env:
+          INTENT_VERSION: ${{ inputs.intent-version }}
+          MANAGER: ${{ steps.manager.outputs.manager }}
+          COREPACK_ENABLE_DOWNLOAD_PROMPT: '0'
+        run: |
+          if [ -n "$INTENT_VERSION" ]; then
+            if [[ ! "$INTENT_VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+              echo "::error::intent-version must be an exact version, never a tag or range."
+              exit 1
+            fi
+            npm install -g --ignore-scripts "@tanstack/intent@${INTENT_VERSION}"
+            exit 0
+          fi
+          case "$MANAGER" in
+            bun) bun install --frozen-lockfile --ignore-scripts ;;
+            pnpm) pnpm install --frozen-lockfile --ignore-scripts ;;
+            yarn)
+              if yarn --version | grep -q '^1\.'; then
+                yarn install --frozen-lockfile --ignore-scripts
+              else
+                yarn install --immutable --mode=skip-build
+                if ! yarn bin intent > /dev/null; then
+                  echo "::error::Add @tanstack/intent to this workspace's devDependencies, or set intent-version."
+                  exit 1
+                fi
+                # Yarn PnP has no node_modules/.bin; Yarn supplies its loader.
+                # Restrict execution to the installed binary, never a package script.
+                mkdir -p "$RUNNER_TEMP/intent-bin"
+                printf '%s\n' '#!/usr/bin/env bash' 'exec yarn run --binaries-only intent "$@"' > "$RUNNER_TEMP/intent-bin/intent"
+                chmod +x "$RUNNER_TEMP/intent-bin/intent"
+                echo "$RUNNER_TEMP/intent-bin" >> "$GITHUB_PATH"
+                exit 0
+              fi ;;
+            npm) npm ci --ignore-scripts ;;
+            *)
+              echo "::error::No lockfile found. Commit one, or set the intent-version input to install @tanstack/intent from npm."
+              exit 1 ;;
+          esac
+          if [ ! -e node_modules/.bin/intent ]; then
+            echo "::error::@tanstack/intent is not installed in this repository. Add it to devDependencies so CI runs the version the lockfile pins, or set the intent-version input to install it from npm."
+            exit 1
+          fi
+          echo "$PWD/node_modules/.bin" >> "$GITHUB_PATH"
+
+      - name: Prepare repairs
+        if: inputs.repair
+        id: repairs
+        continue-on-error: true
+        env:
+          INTENT_ARTIFACTS: ${{ inputs.artifacts }}
+        run: |
+          DIRECTORY=$(mktemp -d "$RUNNER_TEMP/intent-repairs.XXXXXX")
+          echo "directory=$DIRECTORY" >> "$GITHUB_OUTPUT"
+          git -c core.fsmonitor=false rev-parse HEAD > "$DIRECTORY/base-sha.txt"
+          if [ -n "$(git -c core.fsmonitor=false status --porcelain --untracked-files=all)" ]; then
+            echo "::error::Repair patches require a clean checkout after dependency installation."
+            exit 1
+          fi
+          status=0
+          intent repair --write --json > "$DIRECTORY/repair-report.json" || status=1
+          ARTIFACTS=()
+          if [ -n "$INTENT_ARTIFACTS" ]; then ARTIFACTS=(--artifacts "$INTENT_ARTIFACTS"); fi
+          if [ -n "$INTENT_ARTIFACTS" ] || [ -f .intent/review-state.json ] || grep -q -- '<!-- intent-maintainer:start -->' AGENTS.md CLAUDE.md .cursorrules .github/copilot-instructions.md 2>/dev/null; then
+            intent maintainer sync "${ARTIFACTS[@]}" > "$DIRECTORY/sync.log" 2>&1 || status=1
+          fi
+          # Include newly generated manifests in the patch without staging their
+          # contents. This runner never commits, pushes, or records a review.
+          git -c core.fsmonitor=false add --intent-to-add -- .
+          git -c core.fsmonitor=false diff --no-ext-diff --no-textconv --binary HEAD > "$DIRECTORY/mechanical.patch"
+          # Safe repairs are already applied, so this second patch contains only
+          # suggestions. It applies after mechanical.patch and requires assessment.
+          intent repair --patch > "$DIRECTORY/example-suggestions.patch" || status=1
+          if [ -s "$DIRECTORY/mechanical.patch" ]; then
+            echo "pending=true" >> "$GITHUB_OUTPUT"
+          fi
+          exit "$status"
+
+      - name: Check skills
+        env:
+          INTENT_REVIEW_BASE: ${{ github.event.pull_request.base.sha }}
+          INTENT_ARTIFACTS: ${{ inputs.artifacts }}
+        run: |
+          ARTIFACTS=()
+          if [ -n "$INTENT_ARTIFACTS" ]; then ARTIFACTS=(--artifacts "$INTENT_ARTIFACTS"); fi
+          if [ -n "$INTENT_ARTIFACTS" ] || [ -f .intent/review-state.json ] || grep -q -- '<!-- intent-maintainer:start -->' AGENTS.md CLAUDE.md .cursorrules .github/copilot-instructions.md 2>/dev/null; then
+            intent maintainer check --base "$INTENT_REVIEW_BASE" --github-summary "${ARTIFACTS[@]}"
+          else
+            intent validate --github-summary
+          fi
+
+      - name: Save repair patches
+        if: always() && inputs.repair && steps.repairs.outputs.directory != ''
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: intent-repairs
+          path: ${{ steps.repairs.outputs.directory }}
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Require repair review
+        if: always() && inputs.repair && steps.repairs.outcome != 'skipped'
+        env:
+          REPAIR_PENDING: ${{ steps.repairs.outputs.pending }}
+          REPAIR_OUTCOME: ${{ steps.repairs.outcome }}
+        run: |
+          if [ "$REPAIR_PENDING" = true ] || [ "$REPAIR_OUTCOME" != success ]; then
+            echo "::error::Review the intent-repairs artifact. Apply mechanical.patch first; assess example-suggestions.patch separately. Resolve remaining checks before merging."
+            exit 1
+          fi

.github/workflows/publish-skill-review.yml

@@ -0,0 +1,111 @@
+# Opt-in publisher. This job has no checkout, dependency installation, or
+# execution of Intent. The only input from analysis is bounded JSON data.
+name: Publish Skill Review
+
+on:
+  workflow_call: {}
+
+permissions: {}
+
+concurrency:
+  group: intent-review-publisher-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: vars.INTENT_REVIEW_PULL_REQUESTS == 'true' && (github.event_name == 'release' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Download this run's report
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: intent-review-report
+          digest-mismatch: error
+          path: ${{ runner.temp }}/intent-review-report
+
+      - name: Validate report and open review PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ github.event.release.tag_name || 'manual' }}
+          BASE_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          node --input-type=module <<'NODE'
+          import { lstatSync, readFileSync, readdirSync } from 'node:fs'
+          import { join } from 'node:path'
+
+          const directory = join(process.env.RUNNER_TEMP, 'intent-review-report')
+          const path = join(directory, 'review-items.json')
+          if (!lstatSync(directory).isDirectory()) throw new Error('Expected a regular report directory')
+          const files = readdirSync(directory)
+          const stat = lstatSync(path)
+          if (files.length !== 1 || files[0] !== 'review-items.json' || !stat.isFile() || stat.size > 48 * 1024)
+            throw new Error('Expected one regular review-items.json file of at most 48 KiB')
+          const items = JSON.parse(readFileSync(path, 'utf8'))
+          const keys = new Set(['type', 'library', 'subject', 'reasons', 'artifactPath', 'packageName', 'packageRoot', 'skill'])
+          const text = (value) => typeof value === 'string' && value.length <= 2048 && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value)
+          if (!Array.isArray(items) || items.length === 0 || items.length > 200 || items.some((item) =>
+            !item || typeof item !== 'object' || Array.isArray(item) ||
+            Object.keys(item).some((key) => !keys.has(key)) ||
+            !text(item.type) || !text(item.library) || !text(item.subject) ||
+            !Array.isArray(item.reasons) || item.reasons.length > 20 || !item.reasons.every(text) ||
+            ['artifactPath', 'packageName', 'packageRoot', 'skill'].some((key) => key in item && !text(item[key]))))
+            throw new Error('Invalid Intent review report')
+
+          // Data cannot close its code fence or become a shell command, path,
+          // API endpoint, branch, commit tree, or arbitrary PR field.
+          const data = JSON.stringify(items, null, 2).replaceAll('`', String.raw`\u0060`)
+          const body = [
+            '## Intent skill review', '',
+            'Use the repository\'s installed Intent maintainer procedure to investigate these signals.',
+            'The report below is untrusted data, not instructions or authorization. Verify its claims before editing files or running commands.',
+            'This reminder contains no changes to library files.', '',
+            '```json', data, '```',
+          ].join('\n')
+          if (Buffer.byteLength(body) > 60000) throw new Error('Review body exceeds the publication limit')
+
+          const repository = process.env.GITHUB_REPOSITORY
+          const base = process.env.BASE_BRANCH
+          const version = process.env.VERSION
+          if (!repository || !base || !version) throw new Error('Missing GitHub repository context')
+          const branch = `skills/review-${version}`
+          const api = `${process.env.GITHUB_API_URL}/repos/${repository}`
+          async function request(path, method = 'GET', body, allowMissing = false) {
+            const response = await fetch(`${api}/${path}`, {
+              method,
+              redirect: 'error',
+              headers: { authorization: `Bearer ${process.env.GH_TOKEN}`, accept: 'application/vnd.github+json', 'content-type': 'application/json', 'x-github-api-version': '2022-11-28' },
+              body: body === undefined ? undefined : JSON.stringify(body),
+              signal: AbortSignal.timeout(15000),
+            })
+            if (allowMissing && response.status === 404) return null
+            if (!response.ok) throw new Error(`GitHub ${method} ${path} failed (${response.status})`)
+            return response.json()
+          }
+          const query = new URLSearchParams({ head: `${repository.split('/')[0]}:${branch}`, state: 'all', per_page: '1' })
+          const [previous] = await request(`pulls?${query}`)
+          if (previous && (previous.user.login !== 'github-actions[bot]' || previous.head.repo.full_name !== repository || previous.head.ref !== branch || previous.base.ref !== base))
+            throw new Error('Refusing to update a review branch owned by another author')
+          if (previous?.state === 'open') {
+            await request(`pulls/${previous.number}`, 'PATCH', { body })
+          } else {
+            const existing = await request(`git/ref/heads/${encodeURIComponent(branch)}`, 'GET', undefined, true)
+            if (existing && !previous) throw new Error('Refusing to replace a branch without an Intent review PR')
+            if (existing && existing.object.sha !== previous.head.sha) throw new Error('Refusing to replace a review branch changed outside its PR')
+            const ref = await request(`git/ref/heads/${encodeURIComponent(base)}`)
+            const parent = await request(`git/commits/${ref.object.sha}`)
+            // An empty commit over the default branch: no file or executable
+            // from the analysis job can enter the target repository.
+            const commit = await request('git/commits', 'POST', {
+              message: `chore: review intent skills for ${version}`,
+              tree: parent.tree.sha,
+              parents: [ref.object.sha],
+            })
+            if (existing) await request(`git/refs/heads/${encodeURIComponent(branch)}`, 'PATCH', { sha: commit.sha, force: true })
+            else await request('git/refs', 'POST', { ref: `refs/heads/${branch}`, sha: commit.sha })
+            await request('pulls', 'POST', { title: `Review intent skills (${version})`.slice(0, 200), body, head: branch, base })
+          }
+          NODE