From 5d50ca022f3030363fbf5282eefd505f9a3ceb22 Mon Sep 17 00:00:00 2001 From: jae beller Date: Tue, 10 Mar 2026 18:31:44 -0400 Subject: [PATCH] Move CLI docs generator to scheduled action Currently, generating CLI docs is part of the main CI action. Whenever someone opens a pull request, the bot fetches the latest CLI, generates new docs, and inserts a commit into the PR. The extra commit makes PRs noisier to review and can cause merge conflicts. Instead, run the generator on a weekly schedule. The action has its own branch: `actions/update-cli-docs`. Every monday, the action will checkout main, run the CLI tests, update the docs with the week's CLI changes, and force push to the branch. Finally, the bot either opens a new PR, or updates the previous week's if it hasn't been merged yet. --- .github/workflows/ci.yml | 91 +------------------------ .github/workflows/update-cli-docs.yml | 98 +++++++++++++++++++++++++++ 2 files changed, 99 insertions(+), 90 deletions(-) create mode 100644 .github/workflows/update-cli-docs.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 985048c..9a9cd81 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,7 +8,7 @@ on: - '*.md' permissions: - contents: write + contents: read pull-requests: write jobs: @@ -39,98 +39,9 @@ jobs: - name: Lint run: pnpm lint - - name: Install Sprites CLI - run: | - curl -fsSL https://sprites.dev/install.sh | bash - echo "$HOME/.local/bin" >> $GITHUB_PATH - - - name: Setup Sprites auth - run: sprite auth setup --token "$SPRITES_TEST_TOKEN" - env: - SPRITES_TEST_TOKEN: ${{ secrets.SPRITES_TEST_TOKEN }} - - - name: Generate CLI Docs - run: pnpm generate:cli-docs - env: - SKIP_CLI_TESTS: 'true' - - - name: Commit generated CLI docs - run: | - git config user.name "github-actions[bot]" - git config user.email "github-actions[bot]@users.noreply.github.com" - git add src/content/docs/cli/commands.mdx - if git diff --cached --quiet; then - echo "No changes to CLI docs" - else - git commit -m "Update auto-generated CLI documentation" - git push - fi - - name: Build run: pnpm build - - name: Comment CLI Test Results on PR - if: always() && github.event_name == 'pull_request' - uses: actions/github-script@v7 - with: - script: | - const fs = require('fs'); - const path = './cli-test-report.json'; - - let body = '### CLI Documentation Generator\n\n'; - - if (!fs.existsSync(path)) { - body += '⚠️ No test report found (tests may have been skipped)\n'; - } else { - const report = JSON.parse(fs.readFileSync(path, 'utf8')); - - const allPassed = report.testsFailed === 0; - const emoji = allPassed ? '✅' : '❌'; - - body += `| Metric | Value |\n`; - body += `|--------|-------|\n`; - body += `| CLI Version | \`${report.cliVersion}\` |\n`; - body += `| Commands Generated | ${report.commandsGenerated.length} |\n`; - body += `| Tests | ${emoji} ${report.testsPassed}/${report.testsRun} passed |\n`; - - if (report.errors.length > 0) { - body += `\n
❌ ${report.errors.length} Error(s)\n\n`; - for (const error of report.errors) { - body += `- **${error.command}** (${error.phase}): ${error.message}\n`; - } - body += `\n
\n`; - } - - if (report.commandsGenerated.length > 0) { - body += `\n
📚 Commands documented\n\n`; - body += report.commandsGenerated.map(c => `- \`${c}\``).join('\n'); - body += `\n
\n`; - } - } - - const { data: comments } = await github.rest.issues.listComments({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: context.issue.number, - }); - const existing = comments.find(c => c.body.includes('### CLI Documentation Generator')); - - if (existing) { - await github.rest.issues.updateComment({ - owner: context.repo.owner, - repo: context.repo.repo, - comment_id: existing.id, - body, - }); - } else { - await github.rest.issues.createComment({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: context.issue.number, - body, - }); - } - preview: name: Preview Deployment runs-on: ubuntu-latest diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml new file mode 100644 index 0000000..8c4d651 --- /dev/null +++ b/.github/workflows/update-cli-docs.yml @@ -0,0 +1,98 @@ +name: Update CLI Docs + +on: + schedule: + - cron: "0 8 * * 1" + workflow_dispatch: + +permissions: + contents: write + pull-requests: write + +env: + BRANCH: actions/update-cli-docs + +jobs: + update-cli-docs: + name: Update CLI Docs + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + ref: main + token: ${{ secrets.GITHUB_TOKEN }} + + - uses: pnpm/action-setup@v4 + with: + version: latest + + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: pnpm + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Install Sprites CLI + run: | + curl -fsSL https://sprites.dev/install.sh | bash + echo "$HOME/.local/bin" >> $GITHUB_PATH + + - name: Setup Sprites auth + run: sprite auth setup --token "$SPRITES_TEST_TOKEN" + env: + SPRITES_TEST_TOKEN: ${{ secrets.SPRITES_TEST_TOKEN }} + + - name: Generate CLI Docs + run: pnpm generate:cli-docs + + - name: Check for changes + id: changes + run: | + if git diff --quiet src/content/docs/cli/commands.mdx + then + echo "changed=false" >> $GITHUB_OUTPUT + echo "CLI docs are already up to date." + else + echo "changed=true" >> $GITHUB_OUTPUT + echo "Updated CLI docs" + git diff src/content/docs/cli/commands.mdx + fi + + - name: Commit and push to automated branch + if: steps.changes.outputs.changed == 'true' + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + + git checkout -B "$BRANCH" + git add src/content/docs/cli/commands.mdx + git commit -m "Update auto-generated CLI documentation ($(date -u +%Y-%m-%d))" + + git push origin "$BRANCH" --force + + - name: Open or update PR + if: steps.changes.outputs.changed == 'true' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + cat > /tmp/pr-body.md << EOF + Built from $(sprite --version) on $(date -u +%Y-%m-%d) + + > *Generated by the weekly CLI docs update workflow. This PR is automatically updated when new releases are available.* + EOF + + pr=$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number') + if test -z "$pr" + then + gh pr create \ + --title "Update auto-generated CLI documentation" \ + --body-file /tmp/pr-body.md \ + --head "$BRANCH" \ + --base main + else + gh pr edit "$pr" --body-file /tmp/pr-body.md + echo "Updated existing PR #$pr" + fi