From a0dc09b98fc4ffeb57a7b5f9747f53406b17f204 Mon Sep 17 00:00:00 2001 From: Pavel Tarnopolsky Date: Thu, 12 Feb 2026 14:18:09 +0200 Subject: [PATCH] fix: split README check into PR-comment + main-update jobs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two issues with the current README check workflow: 1. PR comments were a single long unreadable line — now the PR job only posts a nicely formatted bulleted list of issues (no push) 2. The commit never actually got pushed because checkout used the merge ref (detached HEAD) instead of the PR branch New approach: - **PR job**: read-only check, posts a comment listing discrepancies. No commits pushed to the PR branch (keeps PRs clean). - **Main job**: triggers on push to main, actually updates README.md and pushes a commit with a descriptive bullet-list message. Closes #240 Co-Authored-By: Claude Opus 4.6 --- .github/workflows/readme-check.yml | 83 ++++++++++++++++++++++++++---- 1 file changed, 72 insertions(+), 11 deletions(-) diff --git a/.github/workflows/readme-check.yml b/.github/workflows/readme-check.yml index 769a4cf1..97f9f8b5 100644 --- a/.github/workflows/readme-check.yml +++ b/.github/workflows/readme-check.yml @@ -8,14 +8,21 @@ on: - "src/core/**" - "package.json" - "README.md" + push: + branches: [main] + paths: + - "src/cli/**" + - "src/core/**" + - "package.json" workflow_dispatch: # Run from Actions tab to test: use a branch that has an open PR, or run on default to see check result in the job log only. jobs: - readme-check: + readme-check-pr: + if: github.event_name == 'pull_request' runs-on: ubuntu-latest permissions: - contents: write + contents: read pull-requests: write issues: read id-token: write @@ -25,10 +32,8 @@ jobs: uses: actions/checkout@v4 with: fetch-depth: 1 - token: ${{ secrets.GITHUB_TOKEN }} - name: Run Claude README Check - id: claude-readme-check uses: anthropics/claude-code-action@v1 with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} @@ -47,13 +52,69 @@ jobs: - Installation section: Package name and Node version mentioned must match package.json. - Quick start: The example commands (e.g. base44 login, base44 create) must still exist as commands in the codebase. - PR number for this run (use this exact number in gh pr comment; if blank/empty, do not comment—print conclusion to the terminal only): ${{ github.event.pull_request.number }} + PR number: ${{ github.event.pull_request.number }} + + RULES: + 1. If everything matches: post a PR comment saying "README check ran. README is up to date." + 2. If you find discrepancies: Do NOT update the file or push commits. Instead, post a PR comment listing the issues in a readable format. Use this template: + + README check ran. **N issue(s) found:** + - Issue one description + - Issue two description + + These will be fixed automatically when this PR is merged to main. + + 3. Post the comment with: gh pr comment --body "" + 4. Do not paste full diffs or long suggestion lists. Keep each bullet to one sentence. + claude_args: '--allowed-tools Read Glob Grep "Bash(gh pr comment:*)"' + allowed_bots: 'claude[bot]' + + readme-update-main: + if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' + runs-on: ubuntu-latest + permissions: + contents: write + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + ref: main + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Run Claude README Update + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + prompt: | + You are checking whether README.md is still accurate after recent changes to main. + + GROUND TRUTH (read from the repo): + 1. Read src/cli/program.ts to get all registered commands. Note which are registered with { hidden: true } — those should NOT appear in the README command table. + 2. For each command, read the corresponding factory file under src/cli/commands/ to get: + - Command name and subcommand names (e.g. "dashboard open", "site deploy") + - The .description() string for each command/subcommand + 3. Read package.json for: the "name" field (install command) and "engines"."node" if present (Node.js requirement). + + COMPARE AGAINST README.md: + - Command table: Every non-hidden command/subcommand must be listed. Descriptions in the table should match the code. Remove any row for a command that no longer exists. + - Installation section: Package name and Node version mentioned must match package.json. + - Quick start: The example commands (e.g. base44 login, base44 create) must still exist as commands in the codebase. RULES: - 1. If everything matches: If the PR number line above has a number, run: gh pr comment --body "README check ran. README is up to date." If it is empty (manual run), print "README check ran. README is up to date." to the terminal and exit. - 2. If you find discrepancies: Update README.md with the correct content (use the Write tool). If the PR number line above has a number (i.e. this is a PR-triggered run), commit and push the fix: git config user.name "github-actions[bot]"; git config user.email "github-actions[bot]@users.noreply.github.com"; git add README.md; git commit -m "docs: update README to match CLI (command table, install, or quick start)"; git push. Then post one short comment with gh pr comment --body "..." summarizing what was fixed (e.g. "README check ran. N issue(s) found and applied: [brief list]. README.md has been updated in this branch."; escape the body for the shell). If the PR number is empty (manual/workflow_dispatch run), do NOT run git push. Instead, print the summary of discrepancies to the terminal so the user can review them. - 3. The PR comment or terminal output must only state that the check ran and the conclusion. Do not paste full diffs or long suggestion lists. - claude_args: '--allowed-tools Read Glob Grep Write "Bash(gh pr comment:*)" "Bash(git config *)" "Bash(git add *)" "Bash(git commit *)" "Bash(git push *)"' + 1. If everything matches: print "README is up to date." and exit. + 2. If you find discrepancies: Update README.md with the correct content (use the Write tool). Then commit and push: + - git config user.name "github-actions[bot]" + - git config user.email "github-actions[bot]@users.noreply.github.com" + - git add README.md + - git commit with a message that lists what was fixed, e.g.: + docs: update README to match CLI + + - Added missing eject command + - Updated deploy description to match code + - git push + 3. Keep the commit message concise. Use a bullet list in the commit body for each fix. + claude_args: '--allowed-tools Read Glob Grep Write "Bash(git config *)" "Bash(git add *)" "Bash(git commit *)" "Bash(git push *)"' allowed_bots: 'claude[bot]' - # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md - # or https://code.claude.com/docs/en/cli-reference for available options