Skip to content

Chrome DevTools for coding agents

5.7 KB
Raw Blame
/**
 * @license
 * Copyright 2026 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import {readFileSync} from 'node:fs';

import type {Argv} from 'yargs';

import {
  yargs,
  hideBin,
  type YargsOptions,
  type InferredOptionTypes,
} from '../third_party/cli.js';
import {getErrorMessage} from '../utils/errorHandling.js';

import {ConfigLocator} from './ConfigLocator.js';
import {
  mcpOptions,
  CLI_EXAMPLES,
  stripYargsPositionalArgs,
  withoutDefaults,
  type ParsedArguments,
} from './mcp-options.js';
import {ServerConfig} from './ServerConfig.js';

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

export class ConfigParser {
  #configPath?: string;
  #cliArgs?: Partial<ParsedArguments>;
  #usageStatisticsNoticeShown = false;
  readonly configLocator: ConfigLocator;

  constructor(
    private version: string,
    private argv: string[] = process.argv,
    private env: NodeJS.ProcessEnv = process.env,
    private exitProcess = true,
    configLocator?: ConfigLocator,
  ) {
    this.configLocator = configLocator ?? new ConfigLocator();
  }

  /**
   * The config file resolved by the last `parse()` call, if any.
   */
  get configPath(): string | undefined {
    return this.#configPath;
  }

  buildCliParser(
    options: Record<string, YargsOptions> = mcpOptions,
  ): Argv<InferredOptionTypes<Record<string, YargsOptions>>> {
    const yargsInstance = yargs(hideBin(this.argv));
    return yargsInstance
      .scriptName('npx chrome-devtools-mcp@latest')
      .parserConfiguration({
        'strip-aliased': true,
        'strip-dashed': true,
      })
      .options(options)
      .showHelpOnFail(false, 'Specify --help for available options')
      .example(CLI_EXAMPLES)
      .wrap(Math.min(120, yargsInstance.terminalWidth()))
      .help()
      .version(this.version);
  }

  /**
   * Step 1: parses the CLI flags without applying defaults, so the result only
   * contains what the user passed. `--help` and `--version` print and exit the
   * process; parse errors throw.
   */
  parseCliArgs(): Partial<ParsedArguments> {
    const parsed = this.buildCliParser(withoutDefaults(mcpOptions))
      .fail(false)
      .parseSync();
    return stripYargsPositionalArgs(parsed);
  }

  /**
   * Step 2: reads the JSON config file and runs it through yargs to reject
   * unknown keys and apply coercions, without applying defaults.
   */
  static parseConfigFile(
    configPath: string,
    rawContent?: string,
  ): Partial<ParsedArguments> {
    try {
      const content = rawContent ?? readFileSync(configPath, 'utf-8');
      // Strip a leading UTF-8 byte order mark (U+FEFF). Windows PowerShell 5.1
      // writes one by default, and JSON.parse rejects it.
      const fileContent: unknown = JSON.parse(content.replace(/^\uFEFF/, ''));
      if (!isPlainObject(fileContent)) {
        throw new Error('Config must be a JSON object');
      }
      const configOptions = withoutDefaults(mcpOptions);
      delete configOptions.config;
      const parsed = yargs([])
        .parserConfiguration({
          'strip-aliased': true,
          'camel-case-expansion': false,
        })
        .options(configOptions)
        .help(false)
        .version(false)
        .config(fileContent)
        .strict()
        .fail(false)
        .exitProcess(false)
        .parseSync([]);
      return stripYargsPositionalArgs(parsed);
    } catch (err) {
      throw new Error(`Invalid JSON config file: ${getErrorMessage(err)}`);
    }
  }

  parseConfigFile(
    configPath: string,
    rawContent?: string,
  ): Partial<ParsedArguments> {
    return ConfigParser.parseConfigFile(configPath, rawContent);
  }

  warnUnknownArgs(cliArgs: Partial<ParsedArguments>): void {
    const allowedArgs = new Set(Object.keys(mcpOptions));
    const unknownArgs = Object.keys(cliArgs).filter(
      arg => !allowedArgs.has(arg),
    );
    if (unknownArgs.length > 0) {
      console.error(`Unknown arguments: ${unknownArgs.map(arg => `--${arg}`)}`);
    }
  }

  /**
   * Parses CLI arguments and the config file into a layered
   * {@link ServerConfig}.
   */
  parseConfig(): ServerConfig {
    try {
      const cliArgs = this.parseCliArgs();
      this.#cliArgs = cliArgs;
      this.#configPath = cliArgs.config ?? this.configLocator.locate(this.env);
      this.warnUnknownArgs(cliArgs);
      return this.#resolveConfig(cliArgs);
    } catch (error) {
      if (this.exitProcess) {
        console.error(getErrorMessage(error));
        process.exit(1);
      }
      throw error;
    }
  }

  parse(): ParsedArguments {
    return this.parseConfig().resolved;
  }

  /**
   * Re-reads the config file resolved by `parse()` and merges it with the CLI
   * arguments again into a new {@link ServerConfig}. Unlike `parseConfig()`, it
   * does not discover a new config file and throws on invalid configuration
   * instead of exiting the process.
   */
  reloadConfig(): ServerConfig {
    this.#cliArgs ??= this.parseCliArgs();
    return this.#resolveConfig(this.#cliArgs);
  }

  /**
   * Re-reads the config file resolved by `parse()` and merges it with the CLI
   * arguments again. Unlike `parse()`, it does not discover a new config file
   * and throws on invalid configuration instead of exiting the process.
   */
  reload(): ParsedArguments {
    return this.reloadConfig().resolved;
  }

  #resolveConfig(cliArgs: Partial<ParsedArguments>): ServerConfig {
    const configPath = this.#configPath;
    const fileArgs = configPath ? this.parseConfigFile(configPath) : {};
    const config = ServerConfig.create({
      cliArgs,
      fileArgs,
      configPath,
      env: this.env,
      suppressUsageStatisticsNotice: this.#usageStatisticsNoticeShown,
    });
    this.#usageStatisticsNoticeShown = true;
    return config;
  }
}