Skip to content

Chrome DevTools for coding agents

chore(build): expand devtools-frontend sparse checkout and add gclient-sync (#3326)

Nikolay Vitkov3d6bc742afd8
diff --git a/.gitignore b/.gitignore
index 73b74a1a..6c2fa350 100644
--- a/.gitignore
+++ b/.gitignore
@@ -151,3 +151,9 @@ log.txt
.DS_Store
mcp-heap-profiles/
+
+# gclient and depot_tools
+third_party/.cipd/
+third_party/.gclient*
+third_party/.gcs_entries
+third_party/depot_tools/
diff --git a/.prettierignore b/.prettierignore
index 85b7594e..434ead6e 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -1,7 +1,7 @@
# Prettier-only ignores.
CHANGELOG.md
src/third_party/lighthouse-devtools-mcp-bundle.js
-third_party/devtools-frontend
+third_party
# Release-please formatting breaks CI checks
.claude-plugin/plugin.json
diff --git a/eslint.config.js b/eslint.config.js
index 7c1342bc..0d98e934 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -30,7 +30,7 @@ export default defineConfig([
globalIgnores([
'**/node_modules',
'**/build/',
- 'third_party/devtools-frontend/**',
+ 'third_party/**',
'tests/tools/fixtures/',
'tests/fixtures/',
'src/third_party/lighthouse-devtools-mcp-bundle.js',
@@ -558,7 +558,7 @@ export default defineConfig([
},
{
name: 'Scripts files',
- files: ['scripts/**/*'],
+ files: ['scripts/**/*.{js,mjs,cjs,ts}'],
rules: {
'no-console': 'off',
'no-restricted-syntax': 'off',
diff --git a/package.json b/package.json
index 547e50d4..4c89f3e5 100644
--- a/package.json
+++ b/package.json
@@ -28,6 +28,7 @@
"test:only": "npm run build && node scripts/test.js --test-only",
"test:update-snapshots": "npm run build && node scripts/test.js --test-update-snapshots",
"prepare": "node scripts/prepare.ts",
+ "gclient-sync": "node scripts/gclient-sync.ts",
"sync": "npm ci && git submodule update --init",
"verify-server-json-version": "node scripts/verify-server-json-version.ts",
"update-lighthouse": "node scripts/update-lighthouse.ts",
diff --git a/scripts/gclient-sync.ts b/scripts/gclient-sync.ts
new file mode 100644
index 00000000..f98198e1
--- /dev/null
+++ b/scripts/gclient-sync.ts
@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {spawnSync} from 'node:child_process';
+import {appendFileSync, existsSync, writeFileSync} from 'node:fs';
+import {delimiter, dirname, join, resolve} from 'node:path';
+
+const isWindows = process.platform === 'win32';
+const projectRoot = process.cwd();
+const thirdPartyDir = resolve(projectRoot, 'third_party');
+const devtoolsDir = resolve(thirdPartyDir, 'devtools-frontend');
+
+const GCLIENT_SPEC = `solutions = [
+ {
+ "name": "devtools-frontend",
+ "url": None,
+ "deps_file": "DEPS",
+ "managed": False,
+ "custom_deps": {
+ "third_party/chrome/chrome-linux": None,
+ "third_party/chrome/chrome-mac-x64": None,
+ "third_party/chrome/chrome-mac-arm64": None,
+ "third_party/chrome/chrome-win": None,
+ "third_party/depot_tools": None,
+ },
+ },
+]
+`;
+
+interface RunOptions {
+ cwd: string;
+ env: NodeJS.ProcessEnv;
+ shell?: boolean;
+}
+
+// Windows stores PATH under a case-insensitive key such as `Path`.
+function getPathKey(env: NodeJS.ProcessEnv): string {
+ return Object.keys(env).find(key => key.toUpperCase() === 'PATH') ?? 'PATH';
+}
+
+function findOnPath(
+ command: string,
+ env: NodeJS.ProcessEnv,
+): string | undefined {
+ const names = isWindows ? [`${command}.bat`, `${command}.exe`] : [command];
+ for (const dir of (env[getPathKey(env)] ?? '').split(delimiter)) {
+ if (!dir) {
+ continue;
+ }
+ for (const name of names) {
+ const candidate = join(dir, name);
+ if (existsSync(candidate)) {
+ return candidate;
+ }
+ }
+ }
+ return undefined;
+}
+
+function prependToPath(env: NodeJS.ProcessEnv, dir: string): void {
+ const key = getPathKey(env);
+ const current = env[key];
+ env[key] = current ? `${dir}${delimiter}${current}` : dir;
+}
+
+function run(
+ command: string,
+ args: string[],
+ {cwd, env, shell}: RunOptions,
+): void {
+ const commandLine = [command, ...args].join(' ');
+ console.log(`> ${commandLine} (in ${cwd})`);
+ const result = shell
+ ? spawnSync(commandLine, {cwd, env, stdio: 'inherit', shell: true})
+ : spawnSync(command, args, {cwd, env, stdio: 'inherit'});
+ if (result.error) {
+ throw new Error(
+ `Failed to start "${commandLine}" in ${cwd}: ${result.error.message}`,
+ );
+ }
+ if (result.status !== 0) {
+ const exit = result.status ?? result.signal;
+ throw new Error(`"${commandLine}" in ${cwd} exited with ${exit}`);
+ }
+}
+
+// depot_tools uses `.bat` launchers on Windows, which only a shell can run.
+// Callers pass fixed arguments without spaces, so joining them is safe.
+function runDepotTool(tool: string, args: string[], options: RunOptions): void {
+ run(tool, args, {...options, shell: isWindows});
+}
+
+const env: NodeJS.ProcessEnv = {...process.env, DEPOT_TOOLS_WIN_TOOLCHAIN: '0'};
+
+console.log(`Setting up gclient in ${thirdPartyDir}`);
+
+let depotToolsDir: string;
+const gclientOnPath = findOnPath('gclient', env);
+if (gclientOnPath) {
+ depotToolsDir = dirname(gclientOnPath);
+ console.log(`Using depot_tools from PATH (${depotToolsDir}).`);
+} else {
+ depotToolsDir = resolve(thirdPartyDir, 'depot_tools');
+ if (existsSync(depotToolsDir)) {
+ console.log(`depot_tools already exists in ${depotToolsDir}.`);
+ } else {
+ console.log('Cloning depot_tools...');
+ run(
+ 'git',
+ [
+ 'clone',
+ 'https://chromium.googlesource.com/chromium/tools/depot_tools.git',
+ depotToolsDir,
+ ],
+ {cwd: projectRoot, env},
+ );
+ }
+ prependToPath(env, depotToolsDir);
+
+ const githubPath = process.env['GITHUB_PATH'];
+ if (githubPath) {
+ console.log('Adding depot_tools to GITHUB_PATH...');
+ appendFileSync(githubPath, `${depotToolsDir}\n`);
+ }
+}
+
+const gclientFile = join(thirdPartyDir, '.gclient');
+console.log(`Writing ${gclientFile}...`);
+writeFileSync(gclientFile, GCLIENT_SPEC);
+
+console.log('Running gclient sync...');
+runDepotTool('gclient', ['sync', '--nohooks'], {cwd: devtoolsDir, env});
+
+const pythonPath = env['PYTHONPATH'];
+runDepotTool(
+ 'vpython3',
+ ['build/util/lastchange.py', '-o', 'build/util/LASTCHANGE'],
+ {
+ cwd: devtoolsDir,
+ env: {
+ ...env,
+ PYTHONPATH: pythonPath
+ ? `${depotToolsDir}${delimiter}${pythonPath}`
+ : depotToolsDir,
+ },
+ },
+);
+
+if (
+ existsSync(resolve(devtoolsDir, 'scripts', 'deps', 'ensure_node_modules.py'))
+) {
+ runDepotTool('vpython3', ['scripts/deps/ensure_node_modules.py'], {
+ cwd: devtoolsDir,
+ env,
+ });
+}
diff --git a/scripts/prepare.ts b/scripts/prepare.ts
index b12a2a5c..73295d28 100644
--- a/scripts/prepare.ts
+++ b/scripts/prepare.ts
@@ -38,6 +38,23 @@ function removeConflictingGlobalDeclaration(): void {
console.log('Successfully removed conflicting global declaration.');
}
+const SPARSE_CHECKOUT_PATTERNS = [
+ '"/*"',
+ '"!/*/"',
+ '"/build_overrides/"',
+ '"/config/"',
+ '"/front_end/"',
+ '"!/front_end/panels/"',
+ '"!/front_end/ui/"',
+ '"/mcp/"',
+ '"/extension-api/"',
+ '"/node_modules/"',
+ '"/scripts/"',
+ '"/third_party/"',
+ '"/**/BUILD.gn"',
+ '"/**/*.gni"',
+].join(' ');
+
function ensureSubmodule(): void {
const devtoolsFrontendDir = resolve(
projectRoot,
@@ -45,12 +62,32 @@ function ensureSubmodule(): void {
'devtools-frontend',
);
const mcpEntry = resolve(devtoolsFrontendDir, 'mcp', 'mcp.ts');
+ const gnScriptsDir = resolve(devtoolsFrontendDir, 'scripts', 'build');
- if (existsSync(mcpEntry)) {
+ if (existsSync(mcpEntry) && existsSync(gnScriptsDir)) {
console.log('devtools-frontend submodule is ready.');
return;
}
+ if (existsSync(mcpEntry) && !existsSync(gnScriptsDir)) {
+ console.log('Updating devtools-frontend sparse checkout patterns...');
+ try {
+ execSync(
+ `git sparse-checkout set --no-cone ${SPARSE_CHECKOUT_PATTERNS}`,
+ {
+ cwd: devtoolsFrontendDir,
+ stdio: 'inherit',
+ },
+ );
+ return;
+ } catch (error) {
+ console.warn(
+ 'Failed to update sparse checkout in place, re-initializing:',
+ error,
+ );
+ }
+ }
+
console.log(
'Initializing devtools-frontend submodule with sparse checkout...',
);
@@ -81,13 +118,10 @@ function ensureSubmodule(): void {
);
// 2. Set the sparse checkout configuration
- execSync(
- 'git sparse-checkout set --no-cone "/*" "!/*/" "/front_end/" "!/front_end/panels/" "!/front_end/ui/" "/mcp/" "/extension-api/"',
- {
- cwd: devtoolsFrontendDir,
- stdio: 'inherit',
- },
- );
+ execSync(`git sparse-checkout set --no-cone ${SPARSE_CHECKOUT_PATTERNS}`, {
+ cwd: devtoolsFrontendDir,
+ stdio: 'inherit',
+ });
// 3. Move the submodule's .git directory to the superproject's .git/modules
execSync('git submodule absorbgitdirs third_party/devtools-frontend', {