Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(docs): scope validation to affected generators (#3293)

injaneity7db1eb0d1091
diff --git a/.github/workflows/ci-check-docs.yml b/.github/workflows/ci-check-docs.yml
index a2e08d2691..6bb8254850 100644
--- a/.github/workflows/ci-check-docs.yml
+++ b/.github/workflows/ci-check-docs.yml
@@ -23,6 +23,7 @@ on:
- "libs/cuabot/src/**"
# Documentation files themselves
- "docs/content/docs/reference/cua-driver/**"
+ - "docs/content/docs/reference/lume/**"
- "docs/content/docs/cua/reference/**"
- "docs/content/docs/cuabot/reference/**"
# Generator scripts
@@ -47,9 +48,12 @@ jobs:
uses: pnpm/action-setup@v4
- name: Install Node dependencies
- run: pnpm install
+ run: pnpm install --frozen-lockfile
working-directory: docs
+ - name: Verify generator routing and tool resolution
+ run: docs/node_modules/.bin/tsx scripts/docs-generators/runner.ts --test-routing
+
- name: Setup Python
uses: actions/setup-python@v5
with:
@@ -63,67 +67,15 @@ jobs:
run: |
# Diff all commits in this PR against the base branch
BASE_SHA="${{ github.event.pull_request.base.sha }}"
- CHANGED_FILES=$(git diff --name-only "$BASE_SHA" HEAD)
+ CHANGED_FILES_FILE="${RUNNER_TEMP}/docs-changed-files.txt"
+ git diff --name-only "$BASE_SHA" HEAD > "$CHANGED_FILES_FILE"
echo "Changed files:"
- echo "$CHANGED_FILES"
+ cat "$CHANGED_FILES_FILE"
- # Check which generators need to run
- GENERATORS=""
+ GENERATORS=$(docs/node_modules/.bin/tsx scripts/docs-generators/runner.ts \
+ --changed-files-file "$CHANGED_FILES_FILE")
- # Source changes
- if echo "$CHANGED_FILES" | grep -q "^libs/cua-driver/rust/crates/\|^libs/cua-driver/rust/Cargo.toml\|^libs/cua-driver/rust/Cargo.lock\|^docs/content/docs/reference/cua-driver/"; then
- GENERATORS="$GENERATORS cua-driver"
- fi
- if echo "$CHANGED_FILES" | grep -q "^libs/lume/src/"; then
- GENERATORS="$GENERATORS lume"
- fi
- if echo "$CHANGED_FILES" | grep -q "^libs/typescript/cua-cli/src/"; then
- GENERATORS="$GENERATORS cua-cli"
- fi
- if echo "$CHANGED_FILES" | grep -q "^libs/python/mcp-server/src/"; then
- GENERATORS="$GENERATORS mcp-server"
- fi
- if echo "$CHANGED_FILES" | grep -q "^libs/python/computer/computer/\|^libs/python/agent/agent/"; then
- GENERATORS="$GENERATORS python-sdk"
- fi
- if echo "$CHANGED_FILES" | grep -q "^libs/cuabot/src/"; then
- GENERATORS="$GENERATORS cuabot"
- fi
-
- # Individual generator script changes — only trigger their own generator
- if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/cua-driver\.ts"; then
- GENERATORS="$GENERATORS cua-driver"
- fi
- if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/lume\.ts"; then
- GENERATORS="$GENERATORS lume"
- fi
- if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/python-sdk\.ts"; then
- GENERATORS="$GENERATORS python-sdk"
- fi
- if echo "$CHANGED_FILES" | grep -q "^scripts/docs-generators/cuabot\.ts"; then
- GENERATORS="$GENERATORS cuabot"
- fi
-
- # Only runner.ts changes trigger all generators (it's the orchestration layer)
- # config.json changes only affect whichever generator scripts were also changed
- if echo "$CHANGED_FILES" | grep -qE "^scripts/docs-generators/runner\.ts$"; then
- GENERATORS="all"
- fi
-
- # Deduplicate
- GENERATORS=$(echo "$GENERATORS" | tr ' ' '\n' | sort -u | tr '\n' ' ' | xargs)
-
- echo "generators=$GENERATORS" >> $GITHUB_OUTPUT
-
- - name: Build cua-driver (if needed)
- if: contains(steps.changed.outputs.generators, 'cua-driver') || steps.changed.outputs.generators == 'all'
- run: cargo build -p cua-driver --release
- working-directory: libs/cua-driver/rust
-
- - name: Build Lume (if needed)
- if: contains(steps.changed.outputs.generators, 'lume') || steps.changed.outputs.generators == 'all'
- run: swift build -c release
- working-directory: libs/lume
+ echo "generators=$GENERATORS" >> "$GITHUB_OUTPUT"
- name: Run documentation check
run: |
@@ -134,14 +86,10 @@ jobs:
exit 0
fi
- if [ "$GENERATORS" = "all" ]; then
- npx tsx scripts/docs-generators/runner.ts --check
- else
- for gen in $GENERATORS; do
- echo "Checking generator: $gen"
- npx tsx scripts/docs-generators/runner.ts --library "$gen" --check
- done
- fi
+ for gen in $GENERATORS; do
+ echo "Checking generator: $gen"
+ docs/node_modules/.bin/tsx scripts/docs-generators/runner.ts --library "$gen" --check
+ done
working-directory: .
- name: Show help if check failed
@@ -156,18 +104,17 @@ jobs:
echo "║ ║"
echo "║ To regenerate all docs, run from the repository root: ║"
echo "║ ║"
- echo "║ npx tsx scripts/docs-generators/runner.ts ║"
+ echo "║ pnpm --dir docs docs:generate ║"
echo "║ ║"
echo "║ Or for a specific library: ║"
echo "║ ║"
- echo "║ npx tsx scripts/docs-generators/runner.ts --library lume ║"
- echo "║ npx tsx scripts/docs-generators/runner.ts --library python-sdk ║"
- echo "║ npx tsx scripts/docs-generators/runner.ts --library cuabot ║"
+ echo "║ pnpm --dir docs docs:generate:lume ║"
+ echo "║ pnpm --dir docs docs:generate:cua-driver ║"
echo "║ ║"
echo "║ For versioned docs and changelogs (after tagging a new release): ║"
echo "║ ║"
- echo "║ npx tsx scripts/docs-generators/generate-versioned-docs.ts ║"
- echo "║ npx tsx scripts/docs-generators/generate-changelog.ts ║"
+ echo "║ pnpm --dir docs docs:generate:versions ║"
+ echo "║ pnpm --dir docs docs:generate:changelog ║"
echo "║ ║"
echo "║ Then commit the updated documentation files. ║"
echo "║ ║"
diff --git a/TESTING.md b/TESTING.md
index 374f8fe03c..e58a513c96 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -112,15 +112,16 @@ Run from `docs`:
```bash
pnpm install --frozen-lockfile
-pnpm docs:check
pnpm docs:check-hygiene
pnpm docs:check-links
pnpm build
```
The production build validates MDX compilation and static route generation.
-The generator check prevents generated CLI and API references from drifting
-from source.
+Curated MDX changes do not need a product build. Generated reference changes
+also run `pnpm docs:check:cua-driver` or `pnpm docs:check:lume` for their owning
+component; `pnpm docs:check` is the explicit full audit. See
+[`docs/README.md`](docs/README.md) for details.
## Before Opening a Pull Request
diff --git a/docs/README.md b/docs/README.md
index 70e45c05aa..df4b2723f6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,13 +4,34 @@ Public documentation content and assets live in this repository. The production
renderer, redirects, analytics, and site configuration live in `trycua/cloud`.
This app is a local MDX preview for contributors to the public repository.
-Run the local preview:
+Install the docs dependencies and run the local preview from this directory:
```bash
+pnpm install --frozen-lockfile
pnpm dev
```
-Open http://localhost:8090 with your browser to see the result.
+Open http://localhost:8090 with your browser to see the result. The docs app has
+its own lockfile; installing dependencies at the repository root is not enough.
+
+## Validate a change
+
+Curated MDX pages use the content checks and production build:
+
+```bash
+pnpm docs:check-hygiene
+pnpm docs:check-links
+pnpm build
+```
+
+For generated reference changes, also run the owning component check:
+
+```bash
+pnpm docs:check:cua-driver
+pnpm docs:check:lume
+```
+
+`pnpm docs:check` is the explicit full Cua Driver and Lume audit.
## Docs conventions
diff --git a/docs/package.json b/docs/package.json
index 75a4de380c..fa73693cf9 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -9,6 +9,8 @@
"postinstall": "fumadocs-mdx",
"docs:generate": "tsx ../scripts/docs-generators/runner.ts",
"docs:check": "tsx ../scripts/docs-generators/runner.ts --check",
+ "docs:check:cua-driver": "tsx ../scripts/docs-generators/runner.ts --library cua-driver --check",
+ "docs:check:lume": "tsx ../scripts/docs-generators/runner.ts --library lume --check",
"docs:list": "tsx ../scripts/docs-generators/runner.ts --list",
"docs:generate:lume": "tsx ../scripts/docs-generators/lume.ts",
"docs:generate:cua-driver": "tsx ../scripts/docs-generators/cua-driver.ts",
diff --git a/scripts/docs-generators/runner.ts b/scripts/docs-generators/runner.ts
index c0f37d28e6..f6572e3377 100644
--- a/scripts/docs-generators/runner.ts
+++ b/scripts/docs-generators/runner.ts
@@ -7,11 +7,10 @@
* Reads config.json and runs appropriate generators based on what changed.
*
* Usage:
- * npx tsx scripts/docs-generators/runner.ts # Generate all enabled docs
- * npx tsx scripts/docs-generators/runner.ts --check # Check for drift (CI mode)
- * npx tsx scripts/docs-generators/runner.ts --library lume # Generate specific library
- * npx tsx scripts/docs-generators/runner.ts --list # List all configured generators
- * npx tsx scripts/docs-generators/runner.ts --changed # Only run for changed files (CI)
+ * pnpm --dir docs docs:generate # Generate all enabled docs
+ * pnpm --dir docs docs:check # Check for drift (CI mode)
+ * pnpm --dir docs docs:check:lume # Check one library
+ * pnpm --dir docs docs:list # List configured generators
*/
import { execSync, spawnSync } from 'child_process';
@@ -54,6 +53,17 @@ interface Config {
const ROOT_DIR = path.resolve(__dirname, '../..');
const CONFIG_PATH = path.join(__dirname, 'config.json');
+const DOCS_TSX_PATH = path.join(
+ ROOT_DIR,
+ 'docs',
+ 'node_modules',
+ '.bin',
+ process.platform === 'win32' ? 'tsx.cmd' : 'tsx'
+);
+const SHARED_GENERATOR_FILES = new Set([
+ 'scripts/docs-generators/runner.ts',
+ 'scripts/docs-generators/config.json',
+]);
// ============================================================================
// Main
@@ -66,12 +76,13 @@ async function main() {
const checkOnly = args.includes('--check') || args.includes('--check-only');
const listOnly = args.includes('--list');
const changedOnly = args.includes('--changed');
+ const changedFilesFileIndex = args.indexOf('--changed-files-file');
+ const changedFilesFile =
+ changedFilesFileIndex !== -1 ? args[changedFilesFileIndex + 1] : undefined;
+ const testRouting = args.includes('--test-routing');
const libraryIndex = args.indexOf('--library');
const specificLibrary = libraryIndex !== -1 ? args[libraryIndex + 1] : null;
- console.log('📚 Documentation Generator Runner');
- console.log('==================================\n');
-
// Load config
if (!fs.existsSync(CONFIG_PATH)) {
console.error(`❌ Config file not found: ${CONFIG_PATH}`);
@@ -80,6 +91,24 @@ async function main() {
const config: Config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+ if (testRouting) {
+ testGeneratorRouting(config);
+ return;
+ }
+
+ if (changedFilesFile) {
+ if (!fs.existsSync(changedFilesFile)) {
+ console.error(`Changed-files input not found: ${changedFilesFile}`);
+ process.exit(1);
+ }
+ const changedFiles = fs.readFileSync(changedFilesFile, 'utf-8').split(/\r?\n/).filter(Boolean);
+ console.log(selectGenerators(config, changedFiles).join(' '));
+ return;
+ }
+
+ console.log('📚 Documentation Generator Runner');
+ console.log('==================================\n');
+
// List mode
if (listOnly) {
listGenerators(config);
@@ -145,7 +174,7 @@ async function main() {
if (hasErrors) {
console.error('❌ Some generators failed or detected drift.');
if (checkOnly) {
- console.log("\n💡 Run 'npx tsx scripts/docs-generators/runner.ts' to update documentation");
+ console.log("\n💡 Run 'pnpm --dir docs docs:generate' to update documentation");
}
process.exit(1);
} else {
@@ -172,9 +201,10 @@ async function runGenerator(
}
try {
- // Run the generator
+ // Use the docs app's lockfile-installed tsx; never fall back to npx downloads.
+ requireDocsTsx();
const args = checkOnly ? ['--check'] : [];
- const result = spawnSync('npx', ['tsx', generatorPath, ...args], {
+ const result = spawnSync(DOCS_TSX_PATH, [generatorPath, ...args], {
cwd: ROOT_DIR,
stdio: 'inherit',
encoding: 'utf-8',
@@ -191,9 +221,125 @@ async function runGenerator(
// Changed Files Detection (for CI)
// ============================================================================
-function getChangedGenerators(config: Config): string[] {
- const changedGenerators: string[] = [];
+function requireDocsTsx(): string {
+ if (!fs.existsSync(DOCS_TSX_PATH)) {
+ throw new Error(
+ `Pinned tsx executable not found at ${DOCS_TSX_PATH}. Run pnpm --dir docs install --frozen-lockfile.`
+ );
+ }
+
+ const packagePath = path.join(ROOT_DIR, 'docs', 'node_modules', 'tsx', 'package.json');
+ const lockfilePath = path.join(ROOT_DIR, 'docs', 'pnpm-lock.yaml');
+ const installedVersion = JSON.parse(fs.readFileSync(packagePath, 'utf-8')).version as string;
+ const lockfile = fs.readFileSync(lockfilePath, 'utf-8');
+
+ if (!lockfile.includes(`tsx@${installedVersion}:`)) {
+ throw new Error(`Installed tsx ${installedVersion} is not pinned by docs/pnpm-lock.yaml`);
+ }
+
+ return installedVersion;
+}
+
+function globToRegExp(glob: string): RegExp {
+ let pattern = '';
+
+ for (let index = 0; index < glob.length; index += 1) {
+ const character = glob[index];
+
+ if (character === '*' && glob[index + 1] === '*') {
+ if (glob[index + 2] === '/') {
+ pattern += '(?:.*/)?';
+ index += 2;
+ } else {
+ pattern += '.*';
+ index += 1;
+ }
+ } else if (character === '*') {
+ pattern += '[^/]*';
+ } else {
+ pattern += character.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ }
+ }
+
+ return new RegExp(`^${pattern}$`);
+}
+
+function selectGenerators(config: Config, changedFiles: readonly string[]): string[] {
+ const enabledGenerators = Object.entries(config.generators).filter(([_, cfg]) => cfg.enabled);
+ const normalizedFiles = changedFiles.map((file) => file.replace(/\\/g, '/'));
+
+ if (normalizedFiles.some((file) => SHARED_GENERATOR_FILES.has(file))) {
+ return enabledGenerators.map(([key]) => key);
+ }
+
+ return enabledGenerators.flatMap(([key, generator]) => {
+ const ownedFiles = new Set([
+ generator.generatorScript,
+ ...generator.outputs.map((output) =>
+ path.posix.join(generator.docsOutputPath, output.outputFile)
+ ),
+ ]);
+ const watchPatterns = generator.watchPaths.map(globToRegExp);
+ const selected = normalizedFiles.some(
+ (file) =>
+ file.startsWith(`${generator.sourcePath}/`) ||
+ ownedFiles.has(file) ||
+ watchPatterns.some((pattern) => pattern.test(file))
+ );
+
+ return selected ? [key] : [];
+ });
+}
+
+function assertSelection(
+ config: Config,
+ changedFiles: readonly string[],
+ expected: readonly string[]
+): void {
+ const actual = selectGenerators(config, changedFiles);
+ if (actual.join('\n') !== expected.join('\n')) {
+ throw new Error(
+ `Routing assertion failed for ${changedFiles.join(', ')}: expected ${expected.join(', ')}, got ${actual.join(', ')}`
+ );
+ }
+}
+function testGeneratorRouting(config: Config): void {
+ const tsxVersion = requireDocsTsx();
+
+ assertSelection(
+ config,
+ [
+ 'docs/content/docs/use-cua-with/hermes.mdx',
+ 'docs/content/docs/reference/cua-driver/macos-permissions.mdx',
+ ],
+ []
+ );
+ assertSelection(
+ config,
+ [
+ 'libs/cua-driver/rust/crates/cua-driver/src/main.rs',
+ 'docs/content/docs/reference/cua-driver/cli-reference.mdx',
+ 'scripts/docs-generators/cua-driver.ts',
+ ],
+ ['cua-driver']
+ );
+ assertSelection(
+ config,
+ [
+ 'libs/lume/src/Commands/List.swift',
+ 'docs/content/docs/reference/lume/http-api.mdx',
+ 'scripts/docs-generators/lume.ts',
+ ],
+ ['lume']
+ );
+ assertSelection(config, ['scripts/docs-generators/runner.ts'], ['cua-driver', 'lume']);
+ assertSelection(config, ['scripts/docs-generators/config.json'], ['cua-driver', 'lume']);
+
+ console.log(`Generator routing assertions passed with pinned tsx ${tsxVersion}`);
+}
+
+function getChangedGenerators(config: Config): string[] {
try {
// Get changed files from git
// This works for both PRs (comparing to base) and pushes
@@ -206,31 +352,15 @@ function getChangedGenerators(config: Config): string[] {
console.log(`📝 Changed files: ${changedFiles.length}`);
- for (const [key, generator] of Object.entries(config.generators)) {
- if (!generator.enabled) continue;
-
- // Check if any watch path matches changed files
- const watchPatterns = generator.watchPaths.map(
- (p) => new RegExp(p.replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*').replace(/\//g, '\\/'))
- );
-
- const hasChanges = changedFiles.some((file) =>
- watchPatterns.some((pattern) => pattern.test(file))
- );
-
- if (hasChanges) {
- changedGenerators.push(key);
- console.log(` 📌 ${key}: changes detected`);
- }
- }
+ const changedGenerators = selectGenerators(config, changedFiles);
+ for (const key of changedGenerators) console.log(` 📌 ${key}: changes detected`);
+ return changedGenerators;
} catch (error) {
console.warn('⚠️ Could not detect changed files, running all generators');
return Object.entries(config.generators)
.filter(([_, cfg]) => cfg.enabled)
.map(([key, _]) => key);
}
-
- return changedGenerators;
}
// ============================================================================