fix(ci): regenerate cua-driver reference docs on release bump - #1863
fix(ci): regenerate cua-driver reference docs on release bump#1863mvanhorn wants to merge 2 commits into
Conversation
After the version bump, regenerate the CLI/MCP reference docs and, if they changed, commit and attach them to the release tag (erroring clearly if no tag is found). Hardens the generator's error reporting. Closes trycua#1522 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
@mvanhorn is attempting to deploy a commit to the Cua Team on Vercel. A member of the Team first needs to authorize it. |
📝 WalkthroughWalkthroughThis PR implements automatic regeneration of cua-driver reference documentation during release-bump operations. The workflow now runs on macOS for cua-driver-rs, executes the doc generator after version bumps, amends the commit to include any generated documentation changes, and improves error handling in the generator itself. Generated docs are updated to version 0.5.1 with a new optional ChangesRelease workflow with auto-generated docs regeneration
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/content/docs/cua-driver/reference/mcp-tools.mdx (1)
527-533:⚠️ Potential issue | 🟡 Minor | ⚡ Quick win
set_agent_cursor_enableddocs are internally inconsistent aboutsessionvscursor_id.Line 527 tells users to pass
session, but the argument list only documentscursor_id+enabled. Please align the prose and schema docs so client authors have one clear contract.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/content/docs/cua-driver/reference/mcp-tools.mdx` around lines 527 - 533, The docs for set_agent_cursor_enabled use both "session" and "cursor_id" inconsistently; update the prose and the Arguments section so they use a single identifier name across the docstring (preferably matching the API parameter name used in the code for set_agent_cursor_enabled), e.g., change the sentence "pass `session` (the same id you start_session / drive actions with)" to use `cursor_id` if that is the canonical parameter, or rename the argument entry to `session` if that is the canonical API; ensure the description and default ('default') and legacy alias note remain accurate and consistent with the chosen name throughout the function's doc block.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/release-bump-version.yml:
- Line 58: The cua-driver docs generator uses a shell pipeline relying on GNU
sort -V so update the tag selection in scripts/docs-generators/cua-driver.ts to
use git's native version sorting: replace the pipeline that uses `git tag | grep
"^${TAG_PREFIX}" | sort -V | tail -1` with a git-native call such as `git tag
--sort=-version:refname` (then pick the first entry) so TAG_PREFIX filtering and
latest-tag selection are done with git and will work on macOS/BSD; ensure you
still apply the TAG_PREFIX filter and fall back behavior remains the same when
no tags are found.
---
Outside diff comments:
In `@docs/content/docs/cua-driver/reference/mcp-tools.mdx`:
- Around line 527-533: The docs for set_agent_cursor_enabled use both "session"
and "cursor_id" inconsistently; update the prose and the Arguments section so
they use a single identifier name across the docstring (preferably matching the
API parameter name used in the code for set_agent_cursor_enabled), e.g., change
the sentence "pass `session` (the same id you start_session / drive actions
with)" to use `cursor_id` if that is the canonical parameter, or rename the
argument entry to `session` if that is the canonical API; ensure the description
and default ('default') and legacy alias note remain accurate and consistent
with the chosen name throughout the function's doc block.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 2ca4d520-9c8d-4975-af05-7521ddf50288
📒 Files selected for processing (4)
.github/workflows/release-bump-version.ymldocs/content/docs/cua-driver/reference/cli-reference.mdxdocs/content/docs/cua-driver/reference/mcp-tools.mdxscripts/docs-generators/cua-driver.ts
| jobs: | ||
| bump-version: | ||
| runs-on: ubuntu-latest | ||
| runs-on: ${{ inputs.service == 'cua-driver-rs' && 'macos-latest' || 'ubuntu-latest' }} |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Does the default macOS BSD sortcommand support the-V flag?
💡 Result:
The default macOS sort command does not support the -V (or --version-sort) flag [1][2]. While the -V flag is a standard feature of the GNU Coreutils sort command—widely available on Linux distributions [3][4]—the version of sort included with macOS is a BSD-based utility that predates the inclusion of this specific option [2]. If you require version-sorting functionality on macOS, you can achieve it by installing GNU Coreutils, which provides a version of sort that supports the -V flag (typically installed as gsort via Homebrew) [1]. Alternatively, you can use workarounds such as custom shell scripts or specific sorting commands (like using -n for simple numeric scenarios) to achieve similar results [1][2].
Citations:
- 1: https://stackoverflow.com/questions/21394536/how-to-simulate-sort-v-on-macos
- 2: https://stackoverflow.com/questions/38276078/unix-sort-files-by-number-version-without-0-padding
- 3: https://www.gnu.org/software/coreutils/manual/html_node/sort-invocation.html
- 4: https://www.gnu.org/software/coreutils/manual/html_node/Using-version-sort-in-GNU-Coreutils.html
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate the generator file
ls -la scripts/docs-generators 2>/dev/null || true
fd -t f 'cua-driver.ts' scripts .github || true
# Search for sort -V usage across repo
rg -n --hidden --no-ignore -S "sort\s+-V|--version-sort|-V\b" .
# Inspect the relevant generator file if present
FILE="$(fd -t f 'cua-driver\.ts$' . | head -n 1 || true)"
if [ -n "${FILE}" ]; then
echo "---- FILE: ${FILE} ----"
# Show area around any sort invocation
rg -n "sort\b" "${FILE}" || true
# Show surrounding lines for the most relevant match(s)
rg -n "sort\s+-V|--version-sort" "${FILE}" -C 5 || true
# Print file (bounded) if it’s small; otherwise sample
LINES=$(wc -l < "${FILE}")
echo "---- ${FILE} has ${LINES} lines ----"
if [ "${LINES}" -le 220 ]; then
cat -n "${FILE}"
else
# show likely top and around matches
head -n 120 "${FILE}" | nl -ba
rg -n "sort\s+-V|--version-sort" "${FILE}" -n | cut -d: -f1 | head -n 1 | while read -r ln; do
start=$((ln-40)); end=$((ln+60))
sed -n "${start},${end}p" "${FILE}" | nl -ba
done
fi
else
echo "Could not find scripts/docs-generators/cua-driver.ts in this repo snapshot."
fiRepository: trycua/cua
Length of output: 11769
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the workflow lines around the runner selection
if [ -f .github/workflows/release-bump-version.yml ]; then
echo "---- .github/workflows/release-bump-version.yml ----"
sed -n '1,120p' .github/workflows/release-bump-version.yml | nl -ba | sed -n '45,90p' || true
# Also locate where the cua-driver docs generator is invoked
rg -n "docs-generators/cua-driver\.ts|npx\s+tsx\s+scripts/docs-generators/cua-driver\.ts|cua-driver\.ts" .github/workflows/release-bump-version.yml || true
# Print the specific command area if found
rg -n -C 6 "docs-generators/cua-driver\.ts|npx\s+tsx\s+scripts/docs-generators/cua-driver\.ts|cua-driver\.ts" .github/workflows/release-bump-version.yml || true
fi
# Inspect the cua-driver generator around the sort -V usage
if [ -f scripts/docs-generators/cua-driver.ts ]; then
echo "---- scripts/docs-generators/cua-driver.ts (sort -V section) ----"
sed -n '120,190p' scripts/docs-generators/cua-driver.ts | nl -ba
echo "---- scripts/docs-generators/cua-driver.ts (how empty output is handled) ----"
sed -n '190,260p' scripts/docs-generators/cua-driver.ts | nl -ba
fiRepository: trycua/cua
Length of output: 885
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "---- .github/workflows/release-bump-version.yml (runner selection) ----"
sed -n '40,75p' .github/workflows/release-bump-version.yml
echo "---- scripts/docs-generators/cua-driver.ts (sort -V usage) ----"
sed -n '130,210p' scripts/docs-generators/cua-driver.ts
echo "---- scripts/docs-generators/cua-driver.ts (latest released version usage) ----"
sed -n '210,280p' scripts/docs-generators/cua-driver.tsRepository: trycua/cua
Length of output: 6342
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Print tag prefix constants and the getLatestReleasedVersion implementation with context
sed -n '1,120p' scripts/docs-generators/cua-driver.ts
echo "---- getLatestReleasedVersion() ----"
sed -n '120,190p' scripts/docs-generators/cua-driver.tsRepository: trycua/cua
Length of output: 4903
macOS runner breaks version-sorting in cua-driver docs generator
scripts/docs-generators/cua-driver.ts uses git tag | grep "^${TAG_PREFIX}" | sort -V | tail -1 to find the latest released tag; BSD sort on macOS doesn’t support -V, so the command will fail and the code falls back to 0.0.0 (potentially producing incorrect versioned docs). Switch to a git-native version sort (e.g., git tag --sort=-version:refname ...) instead of sort -V.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/release-bump-version.yml at line 58, The cua-driver docs
generator uses a shell pipeline relying on GNU sort -V so update the tag
selection in scripts/docs-generators/cua-driver.ts to use git's native version
sorting: replace the pipeline that uses `git tag | grep "^${TAG_PREFIX}" | sort
-V | tail -1` with a git-native call such as `git tag --sort=-version:refname`
(then pick the first entry) so TAG_PREFIX filtering and latest-tag selection are
done with git and will work on macOS/BSD; ensure you still apply the TAG_PREFIX
filter and fall back behavior remains the same when no tags are found.
resolve_cursor_key accepts session before cursor_id, but the tool schema only declared cursor_id, so the description told clients to pass an argument the schema did not expose. Declare session and document cursor_id as its legacy alias, then regenerate mcp-tools.mdx. Signed-off-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
|
Good catch on the The prose was right and the schema was wrong: The schema now declares |
|
Closing this -- The docs regeneration: this branch hooked into The schema fix: the inline JSON literal is gone, and One unrelated note in case it's useful: Thanks for the pointers on the original review. |
1 participant
Summary
The cua-driver CLI/MCP reference docs are generated, but a version bump could ship without regenerating them, leaving the published reference stale (#1522). The release-bump workflow now regenerates the reference docs and attaches them to the release.
Changes
.github/workflows/release-bump-version.yml: after the version bump, run the docs generator (npx tsx scripts/docs-generators/cua-driver.ts), and ifcli-reference.mdx/mcp-tools.mdxchanged, commit them; the regenerated docs are attached to the release tag on the bump commit (the workflow errors out clearly if no release tag is found rather than silently skipping).scripts/docs-generators/cua-driver.ts: hardened error reporting (errorMessage) so generation failures surface clearly in CI.Testing
CI/codegen change. Verified the generator runs and the workflow's no-op (docs already current) and changed-docs paths are handled, plus the missing-tag guard.
Closes #1522
AI was used for assistance.
Summary by CodeRabbit