chore: implement generic CLI flag usage reporting

This change replaces the manual, strictly-typed `FlagUsage` telemetry component with a generic solution that automatically logs all CLI arguments with transformations.

Key changes:
- `FlagUsage` in `types.ts` is now a generic `Record<string, ...>` to support dynamic flag names.
- Added `src/telemetry/flag-utils.ts` to transform CLI arguments into the telemetry payload.
  - Flag names are automatically converted to snake_case using a new `toSnakeCase` utility.
  - Boolean flags are logged directly.
  - Enum flags (strings with `choices`) are logged as uppercase strings to match server-side enums.
  - Other flags log their 'presence' (e.g., `flag_name_present`).
    - `_present` is only logged if the flag has no default value, or if the user-provided value differs from the default, indicating explicit user intent.
- Updated `main.ts` to use the new `computeFlagUsage` function.
- Added tests in `tests/telemetry/flag-utils.test.ts` to ensure 100% coverage of CLI options and detect accidental telemetry payload changes.

Author: ergunsh

src/main.ts

@@ -10,13 +10,14 @@ import process from 'node:process';
 
 import type {Channel} from './browser.js';
 import {ensureBrowserConnected, ensureBrowserLaunched} from './browser.js';
-import {parseArguments} from './cli.js';
+import {cliOptions, parseArguments} from './cli.js';
 import {loadIssueDescriptions} from './issue-descriptions.js';
 import {logger, saveLogsToFile} from './logger.js';
 import {McpContext} from './McpContext.js';
 import {McpResponse} from './McpResponse.js';
 import {Mutex} from './Mutex.js';
 import {ClearcutLogger} from './telemetry/clearcut-logger.js';
+import {computeFlagUsage} from './telemetry/flag-utils.js';
 import {
   McpServer,
   StdioServerTransport,
@@ -220,11 +221,5 @@ await loadIssueDescriptions();
 const transport = new StdioServerTransport();
 await server.connect(transport);
 logger('Chrome DevTools MCP Server connected');
-void clearcutLogger?.logServerStart({
-  browser_url_present: !!args.browserUrl,
-  headless: args.headless,
-  executable_path_present: !!args.executablePath,
-  isolated: args.isolated,
-  log_file_present: !!args.logFile,
-});
 logDisclaimers();
+void clearcutLogger?.logServerStart(computeFlagUsage(args, cliOptions));

src/telemetry/clearcut-logger.ts

@@ -5,9 +5,7 @@
  */
 
 import {ClearcutSender} from './clearcut-sender.js';
-import type {
-  FlagUsage,
-} from './types.js';
+import type {FlagUsage} from './types.js';
 
 export class ClearcutLogger {
   #sender: ClearcutSender;

src/telemetry/flag-utils.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {cliOptions} from '../cli.js';
+import {toSnakeCase} from '../utils/string.js';
+
+import type {FlagUsage} from './types.js';
+
+type CliOptions = typeof cliOptions;
+
+/**
+ * Computes telemetry flag usage from parsed arguments and CLI options.
+ *
+ * Iterates over the defined CLI options to construct a payload:
+ * - Flag names are converted to snake_case (e.g. `browserUrl` -> `browser_url`).
+ * - A flag is logged as `{flag_name}_present` if:
+ *    - It has no default value, OR
+ *    - The provided value differs from the default value.
+ * - Boolean flags are logged with their literal value.
+ * - String flags with defined `choices` (Enums) are logged as their uppercase value.
+ */
+export function computeFlagUsage(
+  args: Record<string, unknown>,
+  options: CliOptions,
+): FlagUsage {
+  const usage: FlagUsage = {};
+
+  for (const [flagName, config] of Object.entries(options)) {
+    const value = args[flagName];
+    const snakeCaseName = toSnakeCase(flagName);
+
+    // If there isn't a default value provided for the flag,
+    // we're going to log whether it's present on the args user
+    // provided or not. If there is a default value, we only log presence
+    // if the value differs from the default, implying explicit user intent.
+    if (!('default' in config) || value !== config.default) {
+      usage[`${snakeCaseName}_present`] = value !== undefined && value !== null;
+    }
+
+    if (config.type === 'boolean' && typeof value === 'boolean') {
+      // For boolean options, we're going to log the value directly.
+      usage[snakeCaseName] = value;
+    } else if (
+      config.type === 'string' &&
+      typeof value === 'string' &&
+      'choices' in config &&
+      config.choices
+    ) {
+      // For enums, log the value as uppercase
+      // We're going to have an enum for such flags with choices represented
+      // as an `enum` where the keys of the enum will map to the uppercase `choice`.
+      usage[snakeCaseName] = value.toUpperCase();
+    }
+  }
+
+  return usage;
+}

src/telemetry/types.ts

@@ -32,14 +32,7 @@ export interface DailyActive {
 
 export type FirstTimeInstallation = Record<string, never>;
 
-export interface FlagUsage {
-  browser_url_present?: boolean;
-  headless?: boolean;
-  executable_path_present?: boolean;
-  isolated?: boolean;
-  channel?: ChromeChannel;
-  log_file_present?: boolean;
-}
+export type FlagUsage = Record<string, boolean | string | number | undefined>;
 
 // Clearcut API interfaces
 export interface LogRequest {

src/utils/string.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Converts a given string to snake_case.
+ * This function handles camelCase, PascalCase, and acronyms, including transitions between letters and numbers.
+ * It uses Unicode-aware regular expressions (`\p{L}`, `\p{N}`, `\p{Lu}`, `\p{Ll}` with the `u` flag)
+ * to correctly process letters and numbers from various languages.
+ *
+ * @param text The input string to convert to snake_case.
+ * @returns The snake_case version of the input string.
+ */
+export function toSnakeCase(text: string): string {
+  if (!text) {
+    return '';
+  }
+  // First, handle case-based transformations to insert underscores correctly.
+  // 1. Add underscore between a letter and a number.
+  //    e.g., "version2" -> "version_2"
+  // 2. Add underscore between an uppercase letter sequence and a following uppercase+lowercase sequence.
+  //    e.g., "APIFlags" -> "API_Flags"
+  // 3. Add underscore between a lowercase/number and an uppercase letter.
+  //    e.g., "lastName" -> "last_Name", "version_2Update" -> "version_2_Update"
+  // 4. Replace sequences of non-alphanumeric with a single underscore
+  // 5. Remove any leading or trailing underscores.
+  const result = text
+    .replace(/(\p{L})(\p{N})/gu, '$1_$2') // 1
+    .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, '$1_$2') // 2
+    .replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, '$1_$2') // 3
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '_') // 4
+    .replace(/^_|_$/g, ''); // 5
+
+  return result;
+}

tests/telemetry/flag-utils.test.js.snapshot

@@ -0,0 +1,37 @@
+exports[`computeFlagUsage > matches snapshot for all current CLI options 1`] = `
+{
+  "auto_connect_present": true,
+  "auto_connect": true,
+  "browser_url_present": true,
+  "ws_endpoint_present": true,
+  "ws_headers_present": true,
+  "headless_present": true,
+  "headless": true,
+  "executable_path_present": true,
+  "isolated_present": true,
+  "isolated": true,
+  "user_data_dir_present": true,
+  "channel_present": true,
+  "channel": "STABLE",
+  "log_file_present": true,
+  "viewport_present": true,
+  "proxy_server_present": true,
+  "accept_insecure_certs_present": true,
+  "accept_insecure_certs": true,
+  "experimental_devtools_present": true,
+  "experimental_devtools": true,
+  "experimental_vision_present": true,
+  "experimental_vision": true,
+  "experimental_structured_content_present": true,
+  "experimental_structured_content": true,
+  "experimental_include_all_pages_present": true,
+  "experimental_include_all_pages": true,
+  "chrome_arg_present": true,
+  "ignore_default_chrome_arg_present": true,
+  "category_emulation": true,
+  "category_performance": true,
+  "category_network": true,
+  "usage_statistics_present": true,
+  "usage_statistics": true
+}
+`;

tests/telemetry/flag-utils.test.ts

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert/strict';
+import {describe, it} from 'node:test';
+
+import type {cliOptions} from '../../src/cli.js';
+import {computeFlagUsage} from '../../src/telemetry/flag-utils.js';
+
+describe('computeFlagUsage', () => {
+  const mockOptions = {
+    boolFlag: {
+      type: 'boolean' as const,
+      description: 'A boolean flag',
+    },
+    stringFlag: {
+      type: 'string' as const,
+      description: 'A string flag',
+    },
+    enumFlag: {
+      type: 'string' as const,
+      description: 'An enum flag',
+      choices: ['a', 'b'],
+    },
+    flagWithDefault: {
+      type: 'boolean' as const,
+      description: 'A flag with a default value',
+      default: false,
+    },
+  } as unknown as typeof cliOptions;
+
+  it('logs boolean flags directly with snake_case keys', () => {
+    const args = {boolFlag: true};
+    const usage = computeFlagUsage(args, mockOptions);
+    assert.equal(usage.bool_flag, true);
+  });
+
+  it('logs boolean flags as false when false', () => {
+    const args = {boolFlag: false};
+    const usage = computeFlagUsage(args, mockOptions);
+    assert.equal(usage.bool_flag, false);
+  });
+
+  it('logs enum flags as uppercase', () => {
+    const args = {enumFlag: 'a'};
+    const usage = computeFlagUsage(args, mockOptions);
+    assert.equal(usage.enum_flag, 'A');
+  });
+
+  it('logs other flags as present with snake_case keys', () => {
+    const args = {stringFlag: 'value'};
+    const usage = computeFlagUsage(args, mockOptions);
+    assert.equal(usage.string_flag, undefined);
+    assert.equal(usage.string_flag_present, true);
+  });
+
+  it('handles undefined/null values', () => {
+    const args = {stringFlag: undefined};
+    const usage = computeFlagUsage(args, mockOptions);
+    assert.equal(usage.string_flag_present, false);
+  });
+
+  describe('defaults behavior', () => {
+    it('logs presence when default exists and user provides different value', () => {
+      // Case 1: Default exists, and a value is provided by the user.
+      // default is false, user provides true.
+      const args = {flagWithDefault: true};
+      const usage = computeFlagUsage(args, mockOptions);
+      assert.equal(usage.flag_with_default, true);
+      assert.equal(usage.flag_with_default_present, true);
+    });
+
+    it('does not log presence when default exists and user provides no value', () => {
+      // Case 2a: Default exists, and a value is not provided by the user.
+      // Argument parsing would populate with default.
+      const args = {flagWithDefault: false};
+      const usage = computeFlagUsage(args, mockOptions);
+      assert.equal(usage.flag_with_default, false);
+      assert.equal(usage.flag_with_default_present, undefined);
+    });
+
+    it('does not log presence when default exists and user explicitly provides the default value', () => {
+      // Case 2b: User explicitly provides 'false', which matches default.
+      const args = {flagWithDefault: false};
+      const usage = computeFlagUsage(args, mockOptions);
+      assert.equal(usage.flag_with_default, false);
+      assert.equal(usage.flag_with_default_present, undefined);
+    });
+
+    it('logs presence when no default exists and user provides value', () => {
+      // Case 3: No default, user provides value.
+      const args = {stringFlag: 'value'};
+      const usage = computeFlagUsage(args, mockOptions);
+      assert.equal(usage.string_flag_present, true);
+    });
+
+    it('logs non-presence when no default exists and user provides no value', () => {
+      // Case 4: No default, user provides nothing.
+      const args = {};
+      const usage = computeFlagUsage(args, mockOptions);
+      assert.equal(usage.string_flag_present, false);
+    });
+  });
+
+  it('matches snapshot for all current CLI options', async t => {
+    // Import the real options to test against the actual CLI definition
+    const {cliOptions} = await import('../../src/cli.js');
+
+    const mockArgs: Record<string, unknown> = {};
+    for (const [key, config] of Object.entries(cliOptions)) {
+      if ('choices' in config && config.choices) {
+        mockArgs[key] = config.choices[0];
+      } else if (config.type === 'boolean') {
+        mockArgs[key] = true;
+      } else if (config.type === 'string') {
+        mockArgs[key] = '/mock/path';
+      } else if (config.type === 'array') {
+        mockArgs[key] = ['--mock-arg'];
+      } else {
+        mockArgs[key] = 'mock-value';
+      }
+    }
+
+    const usage = computeFlagUsage(mockArgs, cliOptions);
+    t.assert.snapshot(JSON.stringify(usage, null, 2));
+  });
+});