refactor: move and rename files (#2355)

- move utilities to sub-folders where applicable
- changes issue-descriptions to issuesDescriptions.ts and moves it to
devtools/

src/McpPage.ts

@@ -8,7 +8,6 @@ import {
   createTargetUniverse,
   type TargetUniverse,
 } from './devtools/DevtoolsUtils.js';
-import {logger} from './logger.js';
 import {
   ConsoleCollector,
   NetworkCollector,
@@ -43,6 +42,7 @@ import type {
   GeolocationOptions,
   TextSnapshotNode,
 } from './types.js';
+import {logger} from './utils/logger.js';
 import {
   getNetworkMultiplierFromString,
   WaitForHelper,

src/McpResponse.ts

@@ -53,10 +53,10 @@ import type {
 } from './tools/ToolDefinition.js';
 import type {InsightName, TraceResult} from './trace-processing/parse.js';
 import {getInsightOutput, getTraceSummary} from './trace-processing/parse.js';
+import type {PaginationOptions} from './types.js';
 import type {WithSymbolId} from './utils/id.js';
 import {stableIdSymbol} from './utils/id.js';
 import {paginate} from './utils/pagination.js';
-import type {PaginationOptions} from './utils/types.js';
 import type {WaitForEventsResult} from './WaitForHelper.js';
 
 export type DataFormat = 'default' | 'toon' | 'gcf';

src/PageCollector.ts

@@ -5,7 +5,6 @@
  */
 
 import {FakeIssuesManager} from './devtools/DevtoolsUtils.js';
-import {logger} from './logger.js';
 import type {
   CDPSession,
   ConsoleMessage,
@@ -25,6 +24,7 @@ import {
   stableIdSymbol,
   type WithSymbolId,
 } from './utils/id.js';
+import {logger} from './utils/logger.js';
 
 export class UncaughtError {
   readonly details: Protocol.Runtime.ExceptionDetails;

src/TextSnapshot.ts

@@ -4,7 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {logger} from './logger.js';
 import type {McpPage} from './McpPage.js';
 import type {
   Protocol,
@@ -13,6 +12,7 @@ import type {
 } from './third_party/index.js';
 import type {DevToolsData} from './tools/ToolDefinition.js';
 import type {TextSnapshotNode} from './types.js';
+import {logger} from './utils/logger.js';
 
 export class TextSnapshot {
   static nextSnapshotId = 1;

src/ToolHandler.ts

@@ -5,11 +5,9 @@
  */
 
 import type {parseArguments} from './bin/chrome-devtools-mcp-cli-options.js';
-import {logger} from './logger.js';
 import type {McpContext} from './McpContext.js';
 import type {DataFormat} from './McpResponse.js';
 import {McpResponse} from './McpResponse.js';
-import type {Mutex} from './Mutex.js';
 import {SlimMcpResponse} from './SlimMcpResponse.js';
 import {ClearcutLogger} from './telemetry/ClearcutLogger.js';
 import {bucketizeLatency} from './telemetry/transformation.js';
@@ -19,6 +17,8 @@ import type {ToolCategory} from './tools/categories.js';
 import {labels, OFF_BY_DEFAULT_CATEGORIES} from './tools/categories.js';
 import type {DefinedPageTool, ToolDefinition} from './tools/ToolDefinition.js';
 import {pageIdSchema} from './tools/ToolDefinition.js';
+import {logger} from './utils/logger.js';
+import type {Mutex} from './utils/Mutex.js';
 
 export function buildFlag(category: ToolCategory) {
   return `category${category.charAt(0).toUpperCase() + category.slice(1)}`;

src/WaitForHelper.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {logger} from './logger.js';
 import type {Page, Protocol, CdpPage, Dialog} from './third_party/index.js';
 import type {PredefinedNetworkConditions} from './third_party/index.js';
+import {logger} from './utils/logger.js';
 
 export type DialogAction = 'accept' | 'dismiss' | string;
 

src/bin/chrome-devtools-mcp-main.ts

@@ -4,17 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import '../polyfill.js';
+import '../utils/polyfill.js';
 
 import process from 'node:process';
 
 import {closeBrowser} from '../browser.js';
 import {createMcpServer, logDisclaimers} from '../index.js';
-import {logger, saveLogsToFile} from '../logger.js';
 import {ClearcutLogger} from '../telemetry/ClearcutLogger.js';
 import {computeFlagUsage} from '../telemetry/flagUtils.js';
 import {StdioServerTransport} from '../third_party/index.js';
 import {checkForUpdates} from '../utils/check-for-updates.js';
+import {logger, saveLogsToFile} from '../utils/logger.js';
 import {VERSION} from '../version.js';
 
 import {cliOptions, parseArguments} from './chrome-devtools-mcp-cli-options.js';

src/browser.ts

@@ -9,7 +9,6 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import {logger} from './logger.js';
 import type {
   Browser,
   ChromeReleaseChannel,
@@ -17,6 +16,7 @@ import type {
   Target,
 } from './third_party/index.js';
 import {puppeteer} from './third_party/index.js';
+import {logger} from './utils/logger.js';
 
 let browser: Browser | undefined;
 let browserMode: 'launched' | 'connected' | undefined;

src/daemon/client.ts

@@ -8,10 +8,10 @@ import {spawn} from 'node:child_process';
 import fs from 'node:fs';
 import net from 'node:net';
 
-import {logger} from '../logger.js';
 import type {CallToolResult} from '../third_party/index.js';
 import {PipeTransport} from '../third_party/index.js';
 import {getTempFilePath} from '../utils/files.js';
+import {logger} from '../utils/logger.js';
 
 import type {DaemonMessage, DaemonResponse} from './types.js';
 import {

src/daemon/daemon.ts

@@ -12,12 +12,12 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 
-import {logger} from '../logger.js';
 import {
   Client,
   PipeTransport,
   StdioClientTransport,
 } from '../third_party/index.js';
+import {logger} from '../utils/logger.js';
 import {VERSION} from '../version.js';
 
 import type {DaemonMessage} from './types.js';

src/daemon/utils.ts

@@ -9,8 +9,8 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 
-import {logger} from '../logger.js';
 import type {YargsOptions} from '../third_party/index.js';
+import {logger} from '../utils/logger.js';
 
 export const DAEMON_SCRIPT_PATH = path.join(import.meta.dirname, 'daemon.js');
 export const INDEX_SCRIPT_PATH = path.join(

src/devtools/issueDescriptions.ts

@@ -9,7 +9,7 @@ import * as path from 'node:path';
 
 const DESCRIPTIONS_PATH = path.join(
   import.meta.dirname,
-  'third_party/issue-descriptions',
+  '../third_party/issue-descriptions',
 );
 
 let issueDescriptions: Record<string, string> = {};

src/formatters/IssueFormatter.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {ISSUE_UTILS} from '../issue-descriptions.js';
-import {logger} from '../logger.js';
+import {ISSUE_UTILS} from '../devtools/issueDescriptions.js';
 import {DevTools} from '../third_party/index.js';
+import {logger} from '../utils/logger.js';
 
 export interface IssueFormatterOptions {
   requestIdResolver?: (requestId: string) => number | undefined;

src/index.ts

@@ -9,10 +9,8 @@ import type fs from 'node:fs';
 import type {parseArguments} from './bin/chrome-devtools-mcp-cli-options.js';
 import type {Channel} from './browser.js';
 import {ensureBrowserConnected, ensureBrowserLaunched} from './browser.js';
-import {loadIssueDescriptions} from './issue-descriptions.js';
-import {logger} from './logger.js';
+import {loadIssueDescriptions} from './devtools/issueDescriptions.js';
 import {McpContext} from './McpContext.js';
-import {Mutex} from './Mutex.js';
 import {ClearcutLogger} from './telemetry/ClearcutLogger.js';
 import {FilePersistence} from './telemetry/persistence.js';
 import {
@@ -25,6 +23,8 @@ import {
 import {ToolHandler} from './ToolHandler.js';
 import type {DefinedPageTool, ToolDefinition} from './tools/ToolDefinition.js';
 import {createTools} from './tools/tools.js';
+import {logger} from './utils/logger.js';
+import {Mutex} from './utils/Mutex.js';
 import {VERSION} from './version.js';
 
 export {buildFlag} from './ToolHandler.js';

src/telemetry/ClearcutLogger.ts

@@ -7,8 +7,8 @@
 import process from 'node:process';
 
 import {DAEMON_CLIENT_NAME} from '../daemon/utils.js';
-import {logger} from '../logger.js';
 import type {zod, ShapeOutput} from '../third_party/index.js';
+import {logger} from '../utils/logger.js';
 
 import type {ErrorCode} from './errors.js';
 import type {LocalState, Persistence} from './persistence.js';

src/telemetry/WatchdogClient.ts

@@ -7,7 +7,7 @@
 import {spawn, type ChildProcess} from 'node:child_process';
 import {fileURLToPath} from 'node:url';
 
-import {logger} from '../logger.js';
+import {logger} from '../utils/logger.js';
 
 import type {WatchdogMessage, OsType} from './types.js';
 

src/telemetry/persistence.ts

@@ -9,7 +9,7 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 
-import {logger} from '../logger.js';
+import {logger} from '../utils/logger.js';
 
 import {ClearcutLogger} from './ClearcutLogger.js';
 import {ErrorCode} from './errors.js';

src/telemetry/watchdog/ClearcutSender.ts

@@ -6,7 +6,7 @@
 
 import crypto from 'node:crypto';
 
-import {logger} from '../../logger.js';
+import {logger} from '../../utils/logger.js';
 import type {
   ChromeDevToolsMcpExtension,
   LogRequest,

src/telemetry/watchdog/main.ts

@@ -9,7 +9,7 @@ import process from 'node:process';
 import readline from 'node:readline';
 import {parseArgs} from 'node:util';
 
-import {logger, flushLogs, saveLogsToFile} from '../../logger.js';
+import {logger, flushLogs, saveLogsToFile} from '../../utils/logger.js';
 import type {OsType} from '../types.js';
 import {WatchdogMessageType} from '../types.js';
 

src/tools/ToolDefinition.ts

@@ -29,7 +29,7 @@ import type {
   GeolocationOptions,
   ExtensionServiceWorker,
 } from '../types.js';
-import type {PaginationOptions} from '../utils/types.js';
+import type {PaginationOptions} from '../types.js';
 import type {WaitForEventsResult, DialogAction} from '../WaitForHelper.js';
 
 import type {ToolCategory} from './categories.js';

src/tools/input.ts

@@ -4,12 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {logger} from '../logger.js';
 import type {McpContext} from '../McpContext.js';
 import {zod} from '../third_party/index.js';
 import type {ElementHandle, KeyInput} from '../third_party/index.js';
 import type {TextSnapshotNode} from '../types.js';
 import {parseKey} from '../utils/keyboard.js';
+import {logger} from '../utils/logger.js';
 import type {WaitForEventsResult} from '../WaitForHelper.js';
 
 import {ToolCategory} from './categories.js';

src/tools/pages.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {logger} from '../logger.js';
 import type {CdpPage} from '../third_party/index.js';
 import {zod} from '../third_party/index.js';
+import {logger} from '../utils/logger.js';
 
 import {ToolCategory} from './categories.js';
 import {

src/tools/performance.ts

@@ -6,13 +6,13 @@
 
 import zlib from 'node:zlib';
 
-import {logger} from '../logger.js';
 import {zod, DevTools} from '../third_party/index.js';
 import type {InsightName, TraceResult} from '../trace-processing/parse.js';
 import {
   parseRawTraceBuffer,
   traceResultIsSuccess,
 } from '../trace-processing/parse.js';
+import {logger} from '../utils/logger.js';
 
 import {ToolCategory} from './categories.js';
 import type {Context, Response, ContextPage} from './ToolDefinition.js';

src/trace-processing/parse.ts

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {logger} from '../logger.js';
 import {DevTools} from '../third_party/index.js';
+import {logger} from '../utils/logger.js';
 
 const engine = DevTools.TraceEngine.TraceModel.Model.createWithAllHandlers();
 

src/types.ts

@@ -35,3 +35,8 @@ export interface EmulationSettings {
 }
 
 export type Logger = ((...args: unknown[]) => void) | undefined;
+
+export interface PaginationOptions {
+  pageSize?: number;
+  pageIdx?: number;
+}

src/utils/logger.ts

@@ -6,8 +6,8 @@
 
 import fs from 'node:fs';
 
-import {debug} from './third_party/index.js';
-import type {Logger} from './types.js';
+import {debug} from '../third_party/index.js';
+import type {Logger} from '../types.js';
 
 const mcpDebugNamespace = 'mcp:log';
 

src/utils/pagination.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type {PaginationOptions} from './types.js';
+import type {PaginationOptions} from '../types.js';
 
 export interface PaginationResult<Item> {
   items: readonly Item[];

src/utils/polyfill.ts

@@ -5,4 +5,4 @@
  */
 
 // polyfills are now bundled with all other dependencies
-import './third_party/index.js';
+import '../third_party/index.js';

src/utils/types.ts

@@ -1,10 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-export interface PaginationOptions {
-  pageSize?: number;
-  pageIdx?: number;
-}

tests/ToolHandler.test.ts

@@ -12,7 +12,6 @@ import sinon from 'sinon';
 import {parseArguments} from '../src/bin/chrome-devtools-mcp-cli-options.js';
 import {McpContext} from '../src/McpContext.js';
 import {McpPage} from '../src/McpPage.js';
-import {Mutex} from '../src/Mutex.js';
 import {zod} from '../src/third_party/index.js';
 import {ToolHandler} from '../src/ToolHandler.js';
 import {ToolCategory} from '../src/tools/categories.js';
@@ -20,6 +19,7 @@ import type {
   DefinedPageTool,
   ToolDefinition,
 } from '../src/tools/ToolDefinition.js';
+import {Mutex} from '../src/utils/Mutex.js';
 
 describe('ToolHandler', () => {
   afterEach(() => {

tests/formatters/IssueFormatter.test.ts

@@ -9,8 +9,8 @@ import {describe, it, beforeEach, afterEach} from 'node:test';
 
 import sinon from 'sinon';
 
+import {ISSUE_UTILS} from '../../src/devtools/issueDescriptions.js';
 import {IssueFormatter} from '../../src/formatters/IssueFormatter.js';
-import {ISSUE_UTILS} from '../../src/issue-descriptions.js';
 import {getMockAggregatedIssue} from '../utils.js';
 
 describe('IssueFormatter', () => {

tests/setup.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import '../src/polyfill.js';
+import '../src/utils/polyfill.js';
 
 import path from 'node:path';
 import {before, it} from 'node:test';

tests/tools/console.test.ts

@@ -11,7 +11,7 @@ import {before, describe, it} from 'node:test';
 import type {Dialog} from 'puppeteer-core';
 
 import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-options.js';
-import {loadIssueDescriptions} from '../../src/issue-descriptions.js';
+import {loadIssueDescriptions} from '../../src/devtools/issueDescriptions.js';
 import {McpResponse} from '../../src/McpResponse.js';
 import {TextSnapshot} from '../../src/TextSnapshot.js';
 import type {CdpWebWorker} from '../../src/third_party/index.js';
@@ -345,7 +345,7 @@ describe('console', () => {
     });
 
     describe('issues type', () => {
-      it('gets issue details with node id parsing', async t => {
+      it.only('gets issue details with node id parsing', async t => {
         await withMcpContext(async (response, context) => {
           const page = context.getSelectedMcpPage();
           const issuePromise = new Promise<void>(resolve => {