Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
fix(docs): scope validation to affected generators (#3293)
injaneity7db1eb0d1091
diff --git a/.github/workflows/ci-check-docs.yml b/.github/workflows/ci-check-docs.ymlindex 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-lockfileworking-directory: docs+ - name: Verify generator routing and tool resolution+ run: docs/node_modules/.bin/tsx scripts/docs-generators/runner.ts --test-routing+- name: Setup Pythonuses: actions/setup-python@v5with:@@ -63,67 +67,15 @@ jobs:run: |# Diff all commits in this PR against the base branchBASE_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 checkrun: |@@ -134,14 +86,10 @@ jobs:exit 0fi- 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+ doneworking-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.mdindex 374f8fe03c..e58a513c96 100644--- a/TESTING.md+++ b/TESTING.md@@ -112,15 +112,16 @@ Run from `docs`:```bashpnpm install --frozen-lockfile-pnpm docs:checkpnpm docs:check-hygienepnpm docs:check-linkspnpm 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 Requestdiff --git a/docs/README.md b/docs/README.mdindex 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 productionrenderer, 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-lockfilepnpm 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 conventionsdiff --git a/docs/package.json b/docs/package.jsonindex 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.tsindex 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 configif (!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 modeif (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;}// ============================================================================