browser-debugger-cli 0.0.1-alpha.0 → 0.1.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (421) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +167 -52
  3. package/dist/__testfixtures__/cdpMessages.d.ts +43 -0
  4. package/dist/__testfixtures__/cdpMessages.d.ts.map +1 -0
  5. package/dist/__testfixtures__/cdpMessages.js +118 -0
  6. package/dist/__testfixtures__/cdpMessages.js.map +1 -0
  7. package/dist/__testfixtures__/connectionTargets.d.ts +21 -0
  8. package/dist/__testfixtures__/connectionTargets.d.ts.map +1 -0
  9. package/dist/__testfixtures__/connectionTargets.js +59 -0
  10. package/dist/__testfixtures__/connectionTargets.js.map +1 -0
  11. package/dist/__tests__/integration/session-files.integration.test.d.ts +2 -0
  12. package/dist/__tests__/integration/session-files.integration.test.d.ts.map +1 -0
  13. package/dist/__tests__/integration/session-files.integration.test.js +66 -0
  14. package/dist/__tests__/integration/session-files.integration.test.js.map +1 -0
  15. package/dist/__testutils__/FakeClock.d.ts +67 -0
  16. package/dist/__testutils__/FakeClock.d.ts.map +1 -0
  17. package/dist/__testutils__/FakeClock.js +132 -0
  18. package/dist/__testutils__/FakeClock.js.map +1 -0
  19. package/dist/__testutils__/FakeWebSocket.d.ts +106 -0
  20. package/dist/__testutils__/FakeWebSocket.d.ts.map +1 -0
  21. package/dist/__testutils__/FakeWebSocket.js +213 -0
  22. package/dist/__testutils__/FakeWebSocket.js.map +1 -0
  23. package/dist/__testutils__/assertions.d.ts +33 -0
  24. package/dist/__testutils__/assertions.d.ts.map +1 -0
  25. package/dist/__testutils__/assertions.js +57 -0
  26. package/dist/__testutils__/assertions.js.map +1 -0
  27. package/dist/__testutils__/index.d.ts +15 -0
  28. package/dist/__testutils__/index.d.ts.map +1 -0
  29. package/dist/__testutils__/index.js +15 -0
  30. package/dist/__testutils__/index.js.map +1 -0
  31. package/dist/__testutils__/testClock.d.ts +28 -0
  32. package/dist/__testutils__/testClock.d.ts.map +1 -0
  33. package/dist/__testutils__/testClock.js +81 -0
  34. package/dist/__testutils__/testClock.js.map +1 -0
  35. package/dist/__testutils__/testFixtures.d.ts +15 -0
  36. package/dist/__testutils__/testFixtures.d.ts.map +1 -0
  37. package/dist/__testutils__/testFixtures.js +23 -0
  38. package/dist/__testutils__/testFixtures.js.map +1 -0
  39. package/dist/__testutils__/testProcess.d.ts +46 -0
  40. package/dist/__testutils__/testProcess.d.ts.map +1 -0
  41. package/dist/__testutils__/testProcess.js +77 -0
  42. package/dist/__testutils__/testProcess.js.map +1 -0
  43. package/dist/cli/collectors/dom.d.ts +8 -0
  44. package/dist/cli/collectors/dom.d.ts.map +1 -0
  45. package/dist/cli/collectors/dom.js +361 -0
  46. package/dist/cli/collectors/dom.js.map +1 -0
  47. package/dist/cli/collectors/helpers/domCache.d.ts +40 -0
  48. package/dist/cli/collectors/helpers/domCache.d.ts.map +1 -0
  49. package/dist/cli/collectors/helpers/domCache.js +79 -0
  50. package/dist/cli/collectors/helpers/domCache.js.map +1 -0
  51. package/dist/cli/collectors/helpers/domQuery.d.ts +45 -0
  52. package/dist/cli/collectors/helpers/domQuery.d.ts.map +1 -0
  53. package/dist/cli/collectors/helpers/domQuery.js +100 -0
  54. package/dist/cli/collectors/helpers/domQuery.js.map +1 -0
  55. package/dist/cli/collectors/helpers/selectorParser.d.ts +20 -0
  56. package/dist/cli/collectors/helpers/selectorParser.d.ts.map +1 -0
  57. package/dist/cli/collectors/helpers/selectorParser.js +20 -0
  58. package/dist/cli/collectors/helpers/selectorParser.js.map +1 -0
  59. package/dist/cli/commands/__tests__/cdp.contract.test.d.ts +24 -0
  60. package/dist/cli/commands/__tests__/cdp.contract.test.d.ts.map +1 -0
  61. package/dist/cli/commands/__tests__/cdp.contract.test.js +467 -0
  62. package/dist/cli/commands/__tests__/cdp.contract.test.js.map +1 -0
  63. package/dist/cli/commands/__tests__/ipcTest.test.d.ts +2 -0
  64. package/dist/cli/commands/__tests__/ipcTest.test.d.ts.map +1 -0
  65. package/dist/cli/commands/__tests__/ipcTest.test.js +37 -0
  66. package/dist/cli/commands/__tests__/ipcTest.test.js.map +1 -0
  67. package/dist/cli/commands/cdp.d.ts +8 -0
  68. package/dist/cli/commands/cdp.d.ts.map +1 -0
  69. package/dist/cli/commands/cdp.js +45 -0
  70. package/dist/cli/commands/cdp.js.map +1 -0
  71. package/dist/cli/commands/cleanup.d.ts +8 -0
  72. package/dist/cli/commands/cleanup.d.ts.map +1 -0
  73. package/dist/cli/commands/cleanup.js +130 -0
  74. package/dist/cli/commands/cleanup.js.map +1 -0
  75. package/dist/cli/commands/console.d.ts +8 -0
  76. package/dist/cli/commands/console.d.ts.map +1 -0
  77. package/dist/cli/commands/console.js +97 -0
  78. package/dist/cli/commands/console.js.map +1 -0
  79. package/dist/cli/commands/details.d.ts +8 -0
  80. package/dist/cli/commands/details.d.ts.map +1 -0
  81. package/dist/cli/commands/details.js +68 -0
  82. package/dist/cli/commands/details.js.map +1 -0
  83. package/dist/cli/commands/dom/helpers/domCache.d.ts +36 -0
  84. package/dist/cli/commands/dom/helpers/domCache.d.ts.map +1 -0
  85. package/dist/cli/commands/dom/helpers/domCache.js +65 -0
  86. package/dist/cli/commands/dom/helpers/domCache.js.map +1 -0
  87. package/dist/cli/commands/dom/helpers/domQuery.d.ts +48 -0
  88. package/dist/cli/commands/dom/helpers/domQuery.d.ts.map +1 -0
  89. package/dist/cli/commands/dom/helpers/domQuery.js +104 -0
  90. package/dist/cli/commands/dom/helpers/domQuery.js.map +1 -0
  91. package/dist/cli/commands/dom/helpers/errorHandler.d.ts +45 -0
  92. package/dist/cli/commands/dom/helpers/errorHandler.d.ts.map +1 -0
  93. package/dist/cli/commands/dom/helpers/errorHandler.js +70 -0
  94. package/dist/cli/commands/dom/helpers/errorHandler.js.map +1 -0
  95. package/dist/cli/commands/dom/helpers/evalHelpers.d.ts +52 -0
  96. package/dist/cli/commands/dom/helpers/evalHelpers.d.ts.map +1 -0
  97. package/dist/cli/commands/dom/helpers/evalHelpers.js +75 -0
  98. package/dist/cli/commands/dom/helpers/evalHelpers.js.map +1 -0
  99. package/dist/cli/commands/dom/helpers/optionsBuilder.d.ts +35 -0
  100. package/dist/cli/commands/dom/helpers/optionsBuilder.d.ts.map +1 -0
  101. package/dist/cli/commands/dom/helpers/optionsBuilder.js +51 -0
  102. package/dist/cli/commands/dom/helpers/optionsBuilder.js.map +1 -0
  103. package/dist/cli/commands/dom/helpers/selectorParser.d.ts +20 -0
  104. package/dist/cli/commands/dom/helpers/selectorParser.d.ts.map +1 -0
  105. package/dist/cli/commands/dom/helpers/selectorParser.js +20 -0
  106. package/dist/cli/commands/dom/helpers/selectorParser.js.map +1 -0
  107. package/dist/cli/commands/dom/index.d.ts +8 -0
  108. package/dist/cli/commands/dom/index.d.ts.map +1 -0
  109. package/dist/cli/commands/dom/index.js +257 -0
  110. package/dist/cli/commands/dom/index.js.map +1 -0
  111. package/dist/cli/commands/ipcTest.d.ts +23 -0
  112. package/dist/cli/commands/ipcTest.d.ts.map +1 -0
  113. package/dist/cli/commands/ipcTest.js +181 -0
  114. package/dist/cli/commands/ipcTest.js.map +1 -0
  115. package/dist/cli/commands/network.d.ts +8 -0
  116. package/dist/cli/commands/network.d.ts.map +1 -0
  117. package/dist/cli/commands/network.js +40 -0
  118. package/dist/cli/commands/network.js.map +1 -0
  119. package/dist/cli/commands/peek.d.ts +8 -0
  120. package/dist/cli/commands/peek.d.ts.map +1 -0
  121. package/dist/cli/commands/peek.js +109 -0
  122. package/dist/cli/commands/peek.js.map +1 -0
  123. package/dist/cli/commands/query.d.ts +9 -0
  124. package/dist/cli/commands/query.d.ts.map +1 -0
  125. package/dist/cli/commands/query.js +127 -0
  126. package/dist/cli/commands/query.js.map +1 -0
  127. package/dist/cli/commands/start.d.ts +9 -0
  128. package/dist/cli/commands/start.d.ts.map +1 -0
  129. package/dist/cli/commands/start.js +78 -0
  130. package/dist/cli/commands/start.js.map +1 -0
  131. package/dist/cli/commands/status.d.ts +9 -0
  132. package/dist/cli/commands/status.d.ts.map +1 -0
  133. package/dist/cli/commands/status.js +84 -0
  134. package/dist/cli/commands/status.js.map +1 -0
  135. package/dist/cli/commands/stop.d.ts +8 -0
  136. package/dist/cli/commands/stop.d.ts.map +1 -0
  137. package/dist/cli/commands/stop.js +146 -0
  138. package/dist/cli/commands/stop.js.map +1 -0
  139. package/dist/cli/formatters/detailsFormatter.d.ts +10 -0
  140. package/dist/cli/formatters/detailsFormatter.d.ts.map +1 -0
  141. package/dist/cli/formatters/detailsFormatter.js +63 -0
  142. package/dist/cli/formatters/detailsFormatter.js.map +1 -0
  143. package/dist/cli/formatters/previewFormatter.d.ts +27 -0
  144. package/dist/cli/formatters/previewFormatter.d.ts.map +1 -0
  145. package/dist/cli/formatters/previewFormatter.js +160 -0
  146. package/dist/cli/formatters/previewFormatter.js.map +1 -0
  147. package/dist/cli/formatters/statusFormatter.d.ts +34 -0
  148. package/dist/cli/formatters/statusFormatter.d.ts.map +1 -0
  149. package/dist/cli/formatters/statusFormatter.js +108 -0
  150. package/dist/cli/formatters/statusFormatter.js.map +1 -0
  151. package/dist/cli/handlers/ChromeBootstrap.d.ts +24 -0
  152. package/dist/cli/handlers/ChromeBootstrap.d.ts.map +1 -0
  153. package/dist/cli/handlers/ChromeBootstrap.js +50 -0
  154. package/dist/cli/handlers/ChromeBootstrap.js.map +1 -0
  155. package/dist/cli/handlers/CommandRunner.d.ts +60 -0
  156. package/dist/cli/handlers/CommandRunner.d.ts.map +1 -0
  157. package/dist/cli/handlers/CommandRunner.js +81 -0
  158. package/dist/cli/handlers/CommandRunner.js.map +1 -0
  159. package/dist/cli/handlers/OutputBuilder.d.ts +60 -0
  160. package/dist/cli/handlers/OutputBuilder.d.ts.map +1 -0
  161. package/dist/cli/handlers/OutputBuilder.js +138 -0
  162. package/dist/cli/handlers/OutputBuilder.js.map +1 -0
  163. package/dist/cli/handlers/OutputWriter.d.ts +15 -0
  164. package/dist/cli/handlers/OutputWriter.d.ts.map +1 -0
  165. package/dist/cli/handlers/OutputWriter.js +34 -0
  166. package/dist/cli/handlers/OutputWriter.js.map +1 -0
  167. package/dist/cli/handlers/PreviewWriter.d.ts +52 -0
  168. package/dist/cli/handlers/PreviewWriter.d.ts.map +1 -0
  169. package/dist/cli/handlers/PreviewWriter.js +119 -0
  170. package/dist/cli/handlers/PreviewWriter.js.map +1 -0
  171. package/dist/cli/handlers/SessionLock.d.ts +16 -0
  172. package/dist/cli/handlers/SessionLock.d.ts.map +1 -0
  173. package/dist/cli/handlers/SessionLock.js +38 -0
  174. package/dist/cli/handlers/SessionLock.js.map +1 -0
  175. package/dist/cli/handlers/SessionLoop.d.ts +19 -0
  176. package/dist/cli/handlers/SessionLoop.d.ts.map +1 -0
  177. package/dist/cli/handlers/SessionLoop.js +47 -0
  178. package/dist/cli/handlers/SessionLoop.js.map +1 -0
  179. package/dist/cli/handlers/ShutdownController.d.ts +38 -0
  180. package/dist/cli/handlers/ShutdownController.d.ts.map +1 -0
  181. package/dist/cli/handlers/ShutdownController.js +83 -0
  182. package/dist/cli/handlers/ShutdownController.js.map +1 -0
  183. package/dist/cli/handlers/SignalHandler.d.ts +35 -0
  184. package/dist/cli/handlers/SignalHandler.d.ts.map +1 -0
  185. package/dist/cli/handlers/SignalHandler.js +81 -0
  186. package/dist/cli/handlers/SignalHandler.js.map +1 -0
  187. package/dist/cli/handlers/TargetSetup.d.ts +42 -0
  188. package/dist/cli/handlers/TargetSetup.d.ts.map +1 -0
  189. package/dist/cli/handlers/TargetSetup.js +87 -0
  190. package/dist/cli/handlers/TargetSetup.js.map +1 -0
  191. package/dist/cli/handlers/commonOptions.d.ts +54 -0
  192. package/dist/cli/handlers/commonOptions.d.ts.map +1 -0
  193. package/dist/cli/handlers/commonOptions.js +64 -0
  194. package/dist/cli/handlers/commonOptions.js.map +1 -0
  195. package/dist/cli/handlers/daemonSessionController.d.ts +23 -0
  196. package/dist/cli/handlers/daemonSessionController.d.ts.map +1 -0
  197. package/dist/cli/handlers/daemonSessionController.js +108 -0
  198. package/dist/cli/handlers/daemonSessionController.js.map +1 -0
  199. package/dist/cli/handlers/sessionController.d.ts +21 -0
  200. package/dist/cli/handlers/sessionController.d.ts.map +1 -0
  201. package/dist/cli/handlers/sessionController.js +55 -0
  202. package/dist/cli/handlers/sessionController.js.map +1 -0
  203. package/dist/cli/registry.d.ts +11 -0
  204. package/dist/cli/registry.d.ts.map +1 -0
  205. package/dist/cli/registry.js +46 -0
  206. package/dist/cli/registry.js.map +1 -0
  207. package/dist/collectors/__tests__/network.contract.test.d.ts +28 -0
  208. package/dist/collectors/__tests__/network.contract.test.d.ts.map +1 -0
  209. package/dist/collectors/__tests__/network.contract.test.js +525 -0
  210. package/dist/collectors/__tests__/network.contract.test.js.map +1 -0
  211. package/dist/collectors/console.d.ts +5 -3
  212. package/dist/collectors/console.d.ts.map +1 -1
  213. package/dist/collectors/console.js +48 -26
  214. package/dist/collectors/console.js.map +1 -1
  215. package/dist/collectors/dom.d.ts +2 -2
  216. package/dist/collectors/dom.d.ts.map +1 -1
  217. package/dist/collectors/dom.js +23 -12
  218. package/dist/collectors/dom.js.map +1 -1
  219. package/dist/collectors/network.d.ts +18 -4
  220. package/dist/collectors/network.d.ts.map +1 -1
  221. package/dist/collectors/network.js +111 -34
  222. package/dist/collectors/network.js.map +1 -1
  223. package/dist/connection/__tests__/cdp.contract.test.d.ts +16 -0
  224. package/dist/connection/__tests__/cdp.contract.test.d.ts.map +1 -0
  225. package/dist/connection/__tests__/cdp.contract.test.js +378 -0
  226. package/dist/connection/__tests__/cdp.contract.test.js.map +1 -0
  227. package/dist/connection/__tests__/finder.contract.test.d.ts +2 -0
  228. package/dist/connection/__tests__/finder.contract.test.d.ts.map +1 -0
  229. package/dist/connection/__tests__/finder.contract.test.js +239 -0
  230. package/dist/connection/__tests__/finder.contract.test.js.map +1 -0
  231. package/dist/connection/__tests__/tabs.contract.test.d.ts +2 -0
  232. package/dist/connection/__tests__/tabs.contract.test.d.ts.map +1 -0
  233. package/dist/connection/__tests__/tabs.contract.test.js +137 -0
  234. package/dist/connection/__tests__/tabs.contract.test.js.map +1 -0
  235. package/dist/connection/cdp.d.ts +165 -16
  236. package/dist/connection/cdp.d.ts.map +1 -1
  237. package/dist/connection/cdp.js +342 -122
  238. package/dist/connection/cdp.js.map +1 -1
  239. package/dist/connection/finder.d.ts +5 -4
  240. package/dist/connection/finder.d.ts.map +1 -1
  241. package/dist/connection/finder.js +10 -16
  242. package/dist/connection/finder.js.map +1 -1
  243. package/dist/connection/launcher.d.ts +18 -11
  244. package/dist/connection/launcher.d.ts.map +1 -1
  245. package/dist/connection/launcher.js +148 -82
  246. package/dist/connection/launcher.js.map +1 -1
  247. package/dist/connection/tabs.d.ts +47 -14
  248. package/dist/connection/tabs.d.ts.map +1 -1
  249. package/dist/connection/tabs.js +493 -132
  250. package/dist/connection/tabs.js.map +1 -1
  251. package/dist/constants.d.ts +209 -0
  252. package/dist/constants.d.ts.map +1 -0
  253. package/dist/constants.js +232 -0
  254. package/dist/constants.js.map +1 -0
  255. package/dist/daemon/__tests__/ipcServer.contract.test.d.ts +23 -0
  256. package/dist/daemon/__tests__/ipcServer.contract.test.d.ts.map +1 -0
  257. package/dist/daemon/__tests__/ipcServer.contract.test.js +401 -0
  258. package/dist/daemon/__tests__/ipcServer.contract.test.js.map +1 -0
  259. package/dist/daemon/__tests__/launcher.unit.test.d.ts +8 -0
  260. package/dist/daemon/__tests__/launcher.unit.test.d.ts.map +1 -0
  261. package/dist/daemon/__tests__/launcher.unit.test.js +20 -0
  262. package/dist/daemon/__tests__/launcher.unit.test.js.map +1 -0
  263. package/dist/daemon/ipcServer.d.ts +83 -0
  264. package/dist/daemon/ipcServer.d.ts.map +1 -0
  265. package/dist/daemon/ipcServer.js +670 -0
  266. package/dist/daemon/ipcServer.js.map +1 -0
  267. package/dist/daemon/launcher.d.ts +31 -0
  268. package/dist/daemon/launcher.d.ts.map +1 -0
  269. package/dist/daemon/launcher.js +137 -0
  270. package/dist/daemon/launcher.js.map +1 -0
  271. package/dist/daemon/startSession.d.ts +51 -0
  272. package/dist/daemon/startSession.d.ts.map +1 -0
  273. package/dist/daemon/startSession.js +149 -0
  274. package/dist/daemon/startSession.js.map +1 -0
  275. package/dist/daemon/worker.d.ts +18 -0
  276. package/dist/daemon/worker.d.ts.map +1 -0
  277. package/dist/daemon/worker.js +623 -0
  278. package/dist/daemon/worker.js.map +1 -0
  279. package/dist/daemon/workerIpc.d.ts +33 -0
  280. package/dist/daemon/workerIpc.d.ts.map +1 -0
  281. package/dist/daemon/workerIpc.js +8 -0
  282. package/dist/daemon/workerIpc.js.map +1 -0
  283. package/dist/daemon.d.ts +10 -0
  284. package/dist/daemon.d.ts.map +1 -0
  285. package/dist/daemon.js +32 -0
  286. package/dist/daemon.js.map +1 -0
  287. package/dist/index.js +41 -420
  288. package/dist/index.js.map +1 -1
  289. package/dist/ipc/__tests__/client.contract.test.d.ts +23 -0
  290. package/dist/ipc/__tests__/client.contract.test.d.ts.map +1 -0
  291. package/dist/ipc/__tests__/client.contract.test.js +466 -0
  292. package/dist/ipc/__tests__/client.contract.test.js.map +1 -0
  293. package/dist/ipc/client.d.ts +109 -0
  294. package/dist/ipc/client.d.ts.map +1 -0
  295. package/dist/ipc/client.js +220 -0
  296. package/dist/ipc/client.js.map +1 -0
  297. package/dist/ipc/commands.d.ts +208 -0
  298. package/dist/ipc/commands.d.ts.map +1 -0
  299. package/dist/ipc/commands.js +69 -0
  300. package/dist/ipc/commands.js.map +1 -0
  301. package/dist/ipc/responseValidator.d.ts +40 -0
  302. package/dist/ipc/responseValidator.d.ts.map +1 -0
  303. package/dist/ipc/responseValidator.js +28 -0
  304. package/dist/ipc/responseValidator.js.map +1 -0
  305. package/dist/ipc/types.d.ts +193 -0
  306. package/dist/ipc/types.d.ts.map +1 -0
  307. package/dist/ipc/types.js +21 -0
  308. package/dist/ipc/types.js.map +1 -0
  309. package/dist/session/BdgSession.d.ts +71 -4
  310. package/dist/session/BdgSession.d.ts.map +1 -1
  311. package/dist/session/BdgSession.js +173 -75
  312. package/dist/session/BdgSession.js.map +1 -1
  313. package/dist/session/chrome.d.ts +46 -0
  314. package/dist/session/chrome.d.ts.map +1 -0
  315. package/dist/session/chrome.js +92 -0
  316. package/dist/session/chrome.js.map +1 -0
  317. package/dist/session/cleanup.d.ts +45 -0
  318. package/dist/session/cleanup.d.ts.map +1 -0
  319. package/dist/session/cleanup.js +230 -0
  320. package/dist/session/cleanup.js.map +1 -0
  321. package/dist/session/index.d.ts +15 -0
  322. package/dist/session/index.d.ts.map +1 -0
  323. package/dist/session/index.js +23 -0
  324. package/dist/session/index.js.map +1 -0
  325. package/dist/session/lock.d.ts +57 -0
  326. package/dist/session/lock.d.ts.map +1 -0
  327. package/dist/session/lock.js +154 -0
  328. package/dist/session/lock.js.map +1 -0
  329. package/dist/session/metadata.d.ts +59 -0
  330. package/dist/session/metadata.d.ts.map +1 -0
  331. package/dist/session/metadata.js +71 -0
  332. package/dist/session/metadata.js.map +1 -0
  333. package/dist/session/output.d.ts +18 -0
  334. package/dist/session/output.d.ts.map +1 -0
  335. package/dist/session/output.js +24 -0
  336. package/dist/session/output.js.map +1 -0
  337. package/dist/session/paths.d.ts +73 -0
  338. package/dist/session/paths.d.ts.map +1 -0
  339. package/dist/session/paths.js +84 -0
  340. package/dist/session/paths.js.map +1 -0
  341. package/dist/session/pid.d.ts +40 -0
  342. package/dist/session/pid.d.ts.map +1 -0
  343. package/dist/session/pid.js +73 -0
  344. package/dist/session/pid.js.map +1 -0
  345. package/dist/session/process.d.ts +45 -0
  346. package/dist/session/process.d.ts.map +1 -0
  347. package/dist/session/process.js +88 -0
  348. package/dist/session/process.js.map +1 -0
  349. package/dist/types.d.ts +114 -38
  350. package/dist/types.d.ts.map +1 -1
  351. package/dist/utils/__tests__/filters.unit.test.d.ts +2 -0
  352. package/dist/utils/__tests__/filters.unit.test.d.ts.map +1 -0
  353. package/dist/utils/__tests__/filters.unit.test.js +239 -0
  354. package/dist/utils/__tests__/filters.unit.test.js.map +1 -0
  355. package/dist/utils/__tests__/session.contract.test.d.ts +2 -0
  356. package/dist/utils/__tests__/session.contract.test.d.ts.map +1 -0
  357. package/dist/utils/__tests__/session.contract.test.js +234 -0
  358. package/dist/utils/__tests__/session.contract.test.js.map +1 -0
  359. package/dist/utils/atomicFile.d.ts +38 -0
  360. package/dist/utils/atomicFile.d.ts.map +1 -0
  361. package/dist/utils/atomicFile.js +71 -0
  362. package/dist/utils/atomicFile.js.map +1 -0
  363. package/dist/utils/cdpHandlers.d.ts +31 -0
  364. package/dist/utils/cdpHandlers.d.ts.map +1 -0
  365. package/dist/utils/cdpHandlers.js +38 -0
  366. package/dist/utils/cdpHandlers.js.map +1 -0
  367. package/dist/utils/chromeDiagnostics.d.ts +28 -0
  368. package/dist/utils/chromeDiagnostics.d.ts.map +1 -0
  369. package/dist/utils/chromeDiagnostics.js +88 -0
  370. package/dist/utils/chromeDiagnostics.js.map +1 -0
  371. package/dist/utils/errors.d.ts +82 -0
  372. package/dist/utils/errors.d.ts.map +1 -0
  373. package/dist/utils/errors.js +88 -0
  374. package/dist/utils/errors.js.map +1 -0
  375. package/dist/utils/exitCodes.d.ts +32 -0
  376. package/dist/utils/exitCodes.d.ts.map +1 -0
  377. package/dist/utils/exitCodes.js +36 -0
  378. package/dist/utils/exitCodes.js.map +1 -0
  379. package/dist/utils/filters.d.ts +108 -0
  380. package/dist/utils/filters.d.ts.map +1 -0
  381. package/dist/utils/filters.js +304 -0
  382. package/dist/utils/filters.js.map +1 -0
  383. package/dist/utils/formatters/network.d.ts +23 -0
  384. package/dist/utils/formatters/network.d.ts.map +1 -0
  385. package/dist/utils/formatters/network.js +35 -0
  386. package/dist/utils/formatters/network.js.map +1 -0
  387. package/dist/utils/http.d.ts +34 -0
  388. package/dist/utils/http.d.ts.map +1 -0
  389. package/dist/utils/http.js +48 -0
  390. package/dist/utils/http.js.map +1 -0
  391. package/dist/utils/logger.d.ts +42 -0
  392. package/dist/utils/logger.d.ts.map +1 -0
  393. package/dist/utils/logger.js +43 -0
  394. package/dist/utils/logger.js.map +1 -0
  395. package/dist/utils/objects.d.ts +23 -0
  396. package/dist/utils/objects.d.ts.map +1 -0
  397. package/dist/utils/objects.js +25 -0
  398. package/dist/utils/objects.js.map +1 -0
  399. package/dist/utils/url/safeParseUrl.d.ts +63 -0
  400. package/dist/utils/url/safeParseUrl.d.ts.map +1 -0
  401. package/dist/utils/url/safeParseUrl.js +84 -0
  402. package/dist/utils/url/safeParseUrl.js.map +1 -0
  403. package/dist/utils/url.d.ts +63 -1
  404. package/dist/utils/url.d.ts.map +1 -1
  405. package/dist/utils/url.js +152 -2
  406. package/dist/utils/url.js.map +1 -1
  407. package/dist/utils/validation.d.ts +1 -1
  408. package/dist/utils/validation.d.ts.map +1 -1
  409. package/dist/utils/version.d.ts +3 -0
  410. package/dist/utils/version.d.ts.map +1 -0
  411. package/dist/utils/version.js +27 -0
  412. package/dist/utils/version.js.map +1 -0
  413. package/package.json +57 -10
  414. package/dist/utils/pageLoad.d.ts +0 -21
  415. package/dist/utils/pageLoad.d.ts.map +0 -1
  416. package/dist/utils/pageLoad.js +0 -85
  417. package/dist/utils/pageLoad.js.map +0 -1
  418. package/dist/utils/session.d.ts +0 -104
  419. package/dist/utils/session.d.ts.map +0 -1
  420. package/dist/utils/session.js +0 -244
  421. package/dist/utils/session.js.map +0 -1
@@ -1,10 +1,11 @@
1
1
  /**
2
- * Validate that a target still exists in Chrome.
2
+ * Validate that a CDP target still exists.
3
3
  *
4
- * Used to detect when a tab has been closed during collection.
4
+ * This function polls Chrome's target list to verify the target hasn't been closed.
5
+ * Used during long-running sessions to detect tab closures.
5
6
  *
6
- * @param targetId - CDP target ID to validate
7
- * @param port - Chrome debugging port
7
+ * @param targetId - Target ID to validate
8
+ * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
8
9
  * @returns True if target still exists, false otherwise
9
10
  */
10
11
  export declare function validateTarget(targetId: string, port?: number): Promise<boolean>;
@@ -1 +1 @@
1
- {"version":3,"file":"finder.d.ts","sourceRoot":"","sources":["../../src/connection/finder.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,SAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAWpF"}
1
+ {"version":3,"file":"finder.d.ts","sourceRoot":"","sources":["../../src/connection/finder.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,SAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAGhG"}
@@ -1,23 +1,17 @@
1
+ import { DEFAULT_CDP_PORT } from '../constants.js';
2
+ import { fetchCDPTargets } from '../utils/http.js';
1
3
  /**
2
- * Validate that a target still exists in Chrome.
4
+ * Validate that a CDP target still exists.
3
5
  *
4
- * Used to detect when a tab has been closed during collection.
6
+ * This function polls Chrome's target list to verify the target hasn't been closed.
7
+ * Used during long-running sessions to detect tab closures.
5
8
  *
6
- * @param targetId - CDP target ID to validate
7
- * @param port - Chrome debugging port
9
+ * @param targetId - Target ID to validate
10
+ * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
8
11
  * @returns True if target still exists, false otherwise
9
12
  */
10
- export async function validateTarget(targetId, port = 9222) {
11
- try {
12
- const response = await fetch(`http://127.0.0.1:${port}/json/list`);
13
- if (!response.ok) {
14
- return false;
15
- }
16
- const targets = await response.json();
17
- return targets.some(t => t.id === targetId);
18
- }
19
- catch {
20
- return false;
21
- }
13
+ export async function validateTarget(targetId, port = DEFAULT_CDP_PORT) {
14
+ const targets = await fetchCDPTargets(port);
15
+ return targets.some((t) => t.id === targetId);
22
16
  }
23
17
  //# sourceMappingURL=finder.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"finder.js","sourceRoot":"","sources":["../../src/connection/finder.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB,EAAE,IAAI,GAAG,IAAI;IAChE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,oBAAoB,IAAI,YAAY,CAAC,CAAC;QACnE,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,OAAO,GAAgB,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"finder.js","sourceRoot":"","sources":["../../src/connection/finder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB,EAAE,IAAI,GAAG,gBAAgB;IAC5E,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC;AAChD,CAAC"}
@@ -1,9 +1,22 @@
1
- import { LaunchedChrome } from '../types.js';
2
- export interface LaunchOptions {
1
+ import type { Options as ChromeLaunchOptions } from 'chrome-launcher';
2
+ import type { LaunchedChrome } from '../types.js';
3
+ /**
4
+ * Options that control how Chrome is launched for CDP sessions.
5
+ * Extended to support chrome-launcher advanced features.
6
+ */
7
+ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'connectionPollInterval' | 'maxConnectionRetries' | 'portStrictMode' | 'envVars' | 'handleSIGINT' | 'ignoreDefaultFlags' | 'chromeFlags'> {
8
+ /** Remote debugging port (defaults to 9222 when omitted) */
3
9
  port?: number;
4
- userDataDir?: string;
10
+ /** Directory for Chrome profile data. Falls back to persistent ~/.bdg/chrome-profile directory */
11
+ userDataDir?: string | undefined;
12
+ /** When true, launches Chrome in headless mode. Defaults to standard windowed experience */
5
13
  headless?: boolean;
14
+ /** Initial URL to open. Defaults to about:blank and is typically replaced during session setup */
6
15
  url?: string;
16
+ /** Chrome preferences object to override default settings */
17
+ prefs?: Record<string, unknown> | undefined;
18
+ /** Path to JSON file containing Chrome preferences */
19
+ prefsFile?: string | undefined;
7
20
  }
8
21
  /**
9
22
  * Launch Chrome with remote debugging enabled using chrome-launcher.
@@ -13,18 +26,12 @@ export interface LaunchOptions {
13
26
  *
14
27
  * @param options - Launch configuration options
15
28
  * @returns LaunchedChrome instance with PID and kill method
16
- * @throws Error if Chrome fails to launch or CDP doesn't become available
29
+ * @throws ChromeLaunchError if Chrome fails to launch or CDP doesn't become available
30
+ * @throws Error if port is invalid or user data directory cannot be created
17
31
  *
18
32
  * @remarks
19
33
  * Chrome 136+ requires --user-data-dir with a non-default directory.
20
34
  * Uses chrome-launcher for cross-platform Chrome detection and launching.
21
35
  */
22
36
  export declare function launchChrome(options?: LaunchOptions): Promise<LaunchedChrome>;
23
- /**
24
- * Check if Chrome is already running with CDP on the specified port.
25
- *
26
- * @param port - Chrome debugging port to check
27
- * @returns True if Chrome is running and CDP is available
28
- */
29
- export declare function isChromeRunning(port?: number): Promise<boolean>;
30
37
  //# sourceMappingURL=launcher.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../../src/connection/launcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAK7C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqDvF;AA4DD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,GAAE,MAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAS3E"}
1
+ {"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../../src/connection/launcher.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAWtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA6C9C;;;GAGG;AACH,MAAM,WAAW,aACf,SAAQ,IAAI,CACV,mBAAmB,EACjB,UAAU,GACV,wBAAwB,GACxB,sBAAsB,GACtB,gBAAgB,GAChB,SAAS,GACT,cAAc,GACd,oBAAoB,GACpB,aAAa,CAChB;IACD,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC5C,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CA8CvF"}
@@ -1,7 +1,24 @@
1
- import * as chromeLauncher from 'chrome-launcher';
1
+ import * as fs from 'fs';
2
2
  import * as os from 'os';
3
3
  import * as path from 'path';
4
- import * as fs from 'fs';
4
+ import * as chromeLauncher from 'chrome-launcher';
5
+ import { BDG_CHROME_FLAGS, BDG_CHROME_PREFS, DEFAULT_CDP_PORT, DEFAULT_CHROME_LOG_LEVEL, DEFAULT_CHROME_HANDLE_SIGINT, CHROME_PROFILE_DIR, HEADLESS_FLAG, } from '../constants.js';
6
+ import { ChromeLaunchError, getErrorMessage } from '../utils/errors.js';
7
+ import { filterDefined } from '../utils/objects.js';
8
+ const CHROME_LAUNCH_START_MESSAGE = (port) => `Launching Chrome with CDP on port ${port}...`;
9
+ const CHROME_LAUNCH_SUCCESS_MESSAGE = (pid, duration) => `Chrome launched successfully (PID: ${pid})\nLaunch duration: ${duration}ms`;
10
+ // Error Messages
11
+ const INVALID_PORT_ERROR = (port) => `Invalid port number: ${port}. Port must be between 1 and 65535.`;
12
+ const USER_DATA_DIR_ERROR = (dir, error) => `Failed to create user data directory at ${dir}: ${error}`;
13
+ const PREFS_FILE_NOT_FOUND_ERROR = (file) => `Chrome preferences file not found: ${file}`;
14
+ const INVALID_PREFS_FORMAT_ERROR = (file, type) => `Invalid Chrome preferences format in ${file}: expected object, got ${type}`;
15
+ const PREFS_LOAD_ERROR = (file, error) => `Failed to load Chrome preferences from ${file}: ${error}`;
16
+ const CHROME_LAUNCH_ERROR = (error) => `Failed to launch Chrome: ${error}`;
17
+ // Other Constants
18
+ const FILE_NOT_EXIST_ERROR = 'File does not exist';
19
+ const INVALID_JSON_STRUCTURE_ERROR = 'Invalid JSON structure';
20
+ const USER_DATA_DIR_LOG = (dir) => `User data directory: ${dir}`;
21
+ const REMOTE_DEBUGGING_FLAG = (port) => `--remote-debugging-port=${port}`;
5
22
  /**
6
23
  * Launch Chrome with remote debugging enabled using chrome-launcher.
7
24
  *
@@ -10,125 +27,174 @@ import * as fs from 'fs';
10
27
  *
11
28
  * @param options - Launch configuration options
12
29
  * @returns LaunchedChrome instance with PID and kill method
13
- * @throws Error if Chrome fails to launch or CDP doesn't become available
30
+ * @throws ChromeLaunchError if Chrome fails to launch or CDP doesn't become available
31
+ * @throws Error if port is invalid or user data directory cannot be created
14
32
  *
15
33
  * @remarks
16
34
  * Chrome 136+ requires --user-data-dir with a non-default directory.
17
35
  * Uses chrome-launcher for cross-platform Chrome detection and launching.
18
36
  */
19
37
  export async function launchChrome(options = {}) {
20
- const port = options.port ?? 9222;
21
- const headless = options.headless ?? false;
22
- const startingUrl = options.url ?? 'about:blank';
23
- // Use persistent user-data-dir if not provided
24
- const userDataDir = options.userDataDir ?? getPersistentUserDataDir();
25
- console.error(`Launching Chrome with CDP on port ${port}...`);
26
- console.error(`User data directory: ${userDataDir}`);
27
- // Build Chrome launch flags
28
- const chromeFlags = [
29
- `--remote-debugging-port=${port}`,
30
- `--user-data-dir=${userDataDir}`,
31
- '--no-first-run',
32
- '--no-default-browser-check',
33
- '--disable-search-engine-choice-screen',
34
- ];
35
- if (headless) {
36
- chromeFlags.push('--headless=new');
38
+ const port = options.port ?? DEFAULT_CDP_PORT;
39
+ // Validate port range
40
+ if (port < 1 || port > 65535) {
41
+ throw new Error(INVALID_PORT_ERROR(port));
37
42
  }
43
+ const userDataDir = options.userDataDir ?? getPersistentUserDataDir();
44
+ console.error(CHROME_LAUNCH_START_MESSAGE(port));
45
+ console.error(USER_DATA_DIR_LOG(userDataDir));
46
+ const chromeOptions = buildChromeOptions(options);
47
+ const launcher = new chromeLauncher.Launcher(chromeOptions);
38
48
  try {
39
- const chrome = await chromeLauncher.launch({
40
- port,
41
- chromePath: findChromeBinary(), // Let chrome-launcher find Chrome
42
- chromeFlags,
43
- startingUrl,
44
- ignoreDefaultFlags: false,
45
- });
46
- console.error(`Chrome launched successfully (PID: ${chrome.pid})`);
47
- // Wait for CDP to be fully available
48
- await waitForCDP(port);
49
- // Return LaunchedChrome instance
49
+ const launchStart = Date.now();
50
+ await launcher.launch();
51
+ await launcher.waitUntilReady();
52
+ const launchDurationMs = Date.now() - launchStart;
53
+ const chromeProcessPid = launcher.pid ?? 0;
54
+ console.error(CHROME_LAUNCH_SUCCESS_MESSAGE(chromeProcessPid, launchDurationMs));
50
55
  return {
51
- pid: chrome.pid,
52
- port: chrome.port,
56
+ pid: chromeProcessPid,
57
+ port: launcher.port ?? port,
58
+ userDataDir: launcher.userDataDir,
59
+ process: launcher.chromeProcess ?? null,
53
60
  kill: async () => {
54
- try {
55
- await chrome.kill();
56
- }
57
- catch (error) {
58
- console.error(`Error killing Chrome: ${error instanceof Error ? error.message : String(error)}`);
59
- }
61
+ return Promise.resolve().then(() => {
62
+ launcher.kill();
63
+ launcher.destroyTmp();
64
+ });
60
65
  },
61
66
  };
62
67
  }
63
68
  catch (error) {
64
- throw new Error(`Failed to launch Chrome: ${error instanceof Error ? error.message : String(error)}`);
69
+ launcher.kill();
70
+ launcher.destroyTmp();
71
+ throw new ChromeLaunchError(CHROME_LAUNCH_ERROR(getErrorMessage(error)), error instanceof Error ? error : undefined);
65
72
  }
66
73
  }
67
- /**
68
- * Find Chrome binary path for the current platform.
69
- *
70
- * Returns undefined to let chrome-launcher use its own detection logic.
71
- * Can be extended to support custom paths if needed.
72
- *
73
- * @returns Chrome binary path or undefined for auto-detection
74
- */
75
- function findChromeBinary() {
76
- // Let chrome-launcher handle Chrome detection
77
- // It already supports macOS, Linux, Windows, and various Chrome flavors
78
- return undefined;
79
- }
80
74
  /**
81
75
  * Get the default persistent user-data-dir path.
82
76
  *
83
- * Uses ~/.bdg/chrome-profile to persist cookies, settings, and other
84
- * browser state across bdg sessions. This allows cookies to be saved
85
- * and avoids showing cookie consent dialogs on every run.
77
+ * We use a persistent directory to maintain browser state (cookies, localStorage,
78
+ * session storage) across bdg sessions. This prevents users from having to
79
+ * repeatedly log in or accept cookie consent dialogs during debugging workflows.
86
80
  *
87
81
  * @returns Absolute path to persistent user-data-dir
82
+ * @throws Error if user data directory cannot be created due to permission issues
88
83
  */
89
84
  function getPersistentUserDataDir() {
90
85
  const homeDir = os.homedir();
91
- const userDataDir = path.join(homeDir, '.bdg', 'chrome-profile');
92
- // Create directory if it doesn't exist
86
+ const userDataDir = path.join(homeDir, CHROME_PROFILE_DIR);
93
87
  if (!fs.existsSync(userDataDir)) {
94
- fs.mkdirSync(userDataDir, { recursive: true });
88
+ try {
89
+ fs.mkdirSync(userDataDir, { recursive: true });
90
+ }
91
+ catch (error) {
92
+ throw new Error(USER_DATA_DIR_ERROR(userDataDir, getErrorMessage(error)));
93
+ }
95
94
  }
96
95
  return userDataDir;
97
96
  }
98
97
  /**
99
- * Wait for Chrome CDP to become available.
98
+ * Load Chrome preferences from options.
100
99
  *
101
- * Polls the CDP version endpoint until it responds successfully.
100
+ * File-based preferences take precedence over inline preferences because
101
+ * files allow for complex, reusable configurations that can be version
102
+ * controlled and shared across team members or CI environments.
102
103
  *
103
- * @param port - CDP port to check
104
- * @param maxWaitMs - Maximum time to wait in milliseconds
105
- * @throws Error if CDP doesn't become available within timeout
104
+ * @param options - Launch options containing prefs or prefsFile
105
+ * @returns Chrome preferences object or undefined if no preferences specified
106
+ * @throws ChromeLaunchError if prefs file cannot be read, parsed, or doesn't exist
106
107
  */
107
- async function waitForCDP(port, maxWaitMs = 10000) {
108
- const startTime = Date.now();
109
- while (Date.now() - startTime < maxWaitMs) {
110
- if (await isChromeRunning(port)) {
111
- return; // CDP is ready!
108
+ function loadChromePrefs(options) {
109
+ if (options.prefsFile) {
110
+ // Validate file exists before attempting to read
111
+ if (!fs.existsSync(options.prefsFile)) {
112
+ throw new ChromeLaunchError(PREFS_FILE_NOT_FOUND_ERROR(options.prefsFile), new Error(FILE_NOT_EXIST_ERROR));
113
+ }
114
+ try {
115
+ const prefsContent = fs.readFileSync(options.prefsFile, 'utf8');
116
+ const parsed = JSON.parse(prefsContent);
117
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
118
+ throw new ChromeLaunchError(INVALID_PREFS_FORMAT_ERROR(options.prefsFile, typeof parsed), new Error(INVALID_JSON_STRUCTURE_ERROR));
119
+ }
120
+ return parsed;
121
+ }
122
+ catch (error) {
123
+ if (error instanceof ChromeLaunchError) {
124
+ throw error;
125
+ }
126
+ throw new ChromeLaunchError(PREFS_LOAD_ERROR(options.prefsFile, getErrorMessage(error)), error instanceof Error ? error : undefined);
112
127
  }
113
- await new Promise(resolve => setTimeout(resolve, 200));
114
128
  }
115
- throw new Error(`CDP not available on port ${port} after ${maxWaitMs}ms`);
129
+ return options.prefs;
116
130
  }
117
131
  /**
118
- * Check if Chrome is already running with CDP on the specified port.
132
+ * Build Chrome flags array from launch options.
133
+ *
134
+ * Uses chrome-launcher default flags as base (unless ignoreDefaultFlags is true)
135
+ * and layers bdg-specific overrides on top. Headless mode uses the new headless
136
+ * implementation for better compatibility.
119
137
  *
120
- * @param port - Chrome debugging port to check
121
- * @returns True if Chrome is running and CDP is available
138
+ * @param options - Launch options containing flag preferences
139
+ * @returns Array of Chrome command-line flags
122
140
  */
123
- export async function isChromeRunning(port = 9222) {
124
- try {
125
- const response = await fetch(`http://127.0.0.1:${port}/json/version`, {
126
- signal: AbortSignal.timeout(2000), // 2 second timeout
127
- });
128
- return response.ok;
141
+ function buildChromeFlags(options) {
142
+ const port = options.port ?? DEFAULT_CDP_PORT;
143
+ const baseFlags = options.ignoreDefaultFlags ? [] : chromeLauncher.Launcher.defaultFlags();
144
+ const bdgFlags = [REMOTE_DEBUGGING_FLAG(port), ...BDG_CHROME_FLAGS];
145
+ if (options.headless) {
146
+ bdgFlags.push(HEADLESS_FLAG);
129
147
  }
130
- catch {
131
- return false;
148
+ return [...baseFlags, ...bdgFlags, ...(options.chromeFlags ?? [])];
149
+ }
150
+ /**
151
+ * Type-safe conversion for Chrome preferences from unknown to JSONLike.
152
+ *
153
+ * chrome-launcher requires preferences to match its internal JSONLike type constraint
154
+ * for type safety. This conversion is safe because preferences should always be
155
+ * JSON-serializable values loaded from JSON files or constructed with compatible types.
156
+ *
157
+ * @param prefs - Preferences object with unknown values from JSON parsing
158
+ * @returns Preferences compatible with chrome-launcher's JSONLike constraint, or undefined
159
+ */
160
+ function ensureJSONCompatiblePrefs(prefs) {
161
+ if (prefs === undefined) {
162
+ return undefined;
132
163
  }
164
+ // Safe cast because preferences come from JSON.parse or compatible sources
165
+ return prefs;
166
+ }
167
+ /**
168
+ * Build chrome-launcher options from bdg launch options.
169
+ *
170
+ * Maps LaunchOptions to chrome-launcher API format using a clean utility approach
171
+ * that filters out undefined values automatically. User preferences override bdg
172
+ * defaults to allow customization while maintaining sensible base configuration.
173
+ *
174
+ * @param options - bdg launch options to convert
175
+ * @returns chrome-launcher compatible options object
176
+ * @throws ChromeLaunchError if preference loading fails
177
+ */
178
+ function buildChromeOptions(options) {
179
+ const userPrefs = loadChromePrefs(options);
180
+ const userDataDir = options.userDataDir ?? getPersistentUserDataDir();
181
+ // User preferences take precedence over bdg defaults
182
+ const mergedPrefs = userPrefs ? { ...BDG_CHROME_PREFS, ...userPrefs } : BDG_CHROME_PREFS;
183
+ return {
184
+ logLevel: options.logLevel ?? DEFAULT_CHROME_LOG_LEVEL,
185
+ handleSIGINT: options.handleSIGINT ?? DEFAULT_CHROME_HANDLE_SIGINT,
186
+ ignoreDefaultFlags: options.ignoreDefaultFlags ?? false,
187
+ chromeFlags: buildChromeFlags(options),
188
+ userDataDir,
189
+ ...filterDefined({
190
+ port: options.port,
191
+ startingUrl: options.url,
192
+ connectionPollInterval: options.connectionPollInterval,
193
+ maxConnectionRetries: options.maxConnectionRetries,
194
+ portStrictMode: options.portStrictMode,
195
+ prefs: ensureJSONCompatiblePrefs(mergedPrefs),
196
+ envVars: options.envVars,
197
+ }),
198
+ };
133
199
  }
134
200
  //# sourceMappingURL=launcher.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/connection/launcher.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/connection/launcher.ts"],"names":[],"mappings":"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"}
@@ -1,46 +1,79 @@
1
- import { CDPConnection } from './cdp.js';
2
- import { CDPTarget } from '../types.js';
1
+ import type { CDPConnection } from './cdp.js';
2
+ import type { CDPTarget } from '../types.js';
3
3
  /**
4
4
  * Find the best matching target from a list of tabs.
5
5
  *
6
- * @param url - Target URL to find (will be normalized)
6
+ * Filters to page-type targets only because other target types (extensions,
7
+ * service workers, etc.) cannot be navigated to user URLs. The scoring
8
+ * system handles ambiguous matches by warning users when multiple tabs
9
+ * have identical non-perfect scores, helping debug URL matching issues.
10
+ *
11
+ * @param normalizedUrl - Target URL to find (must be pre-normalized)
7
12
  * @param targets - List of available targets
8
13
  * @returns Best matching target or null if no match found
9
14
  */
10
- export declare function findBestTarget(url: string, targets: CDPTarget[]): CDPTarget | null;
15
+ export declare function findBestTarget(normalizedUrl: string, targets: CDPTarget[]): CDPTarget | null;
11
16
  /**
12
17
  * Create a new tab with the specified URL using CDP.
13
18
  *
14
- * @param url - URL to open in the new tab
19
+ * Uses a two-phase approach with enhanced error handling:
20
+ * - CDP command failures → HTTP fallback (prevents total failure)
21
+ * - Verification timeouts → Fail fast with targeted error (prevents duplicate tabs)
22
+ *
23
+ * Configurable verification timeout via BDG_TARGET_VERIFY_TIMEOUT environment
24
+ * variable to handle slow Chrome registration in enterprise/headless environments.
25
+ *
26
+ * @param normalizedUrl - URL to open in the new tab (must be pre-normalized)
15
27
  * @param cdp - CDP connection instance
16
28
  * @returns Target information for the new tab
29
+ * @throws Error if tab creation fails or verification times out
17
30
  */
18
- export declare function createNewTab(url: string, cdp: CDPConnection): Promise<CDPTarget>;
31
+ export declare function createNewTab(normalizedUrl: string, cdp: CDPConnection): Promise<CDPTarget>;
19
32
  /**
20
33
  * Navigate an existing tab to a new URL using CDP.
21
34
  *
35
+ * Requires attaching to the target first because Page.navigate commands
36
+ * must be sent within a target session context. The flatten:true option
37
+ * simplifies session management by avoiding nested session hierarchies
38
+ * that can complicate cleanup and event handling.
39
+ *
22
40
  * @param targetId - CDP target ID to navigate
23
- * @param url - URL to navigate to
41
+ * @param normalizedUrl - URL to navigate to (must be pre-normalized)
24
42
  * @param cdp - CDP connection instance
43
+ * @throws Error if navigation fails (e.g., network error, invalid URL, blocked by browser)
25
44
  */
26
- export declare function navigateToUrl(targetId: string, url: string, cdp: CDPConnection): Promise<void>;
45
+ export declare function navigateToUrl(targetId: string, normalizedUrl: string, cdp: CDPConnection): Promise<void>;
27
46
  /**
28
47
  * Wait for a target to be ready (URL matches expected).
29
48
  *
49
+ * Polling is necessary because tab navigation is asynchronous and Chrome
50
+ * may report intermediate states (like about:blank) before the final URL
51
+ * loads. The 500ms additional wait for about:blank handles the common case
52
+ * where Chrome briefly shows a blank page before starting navigation.
53
+ *
54
+ * Uses HTTP endpoint instead of CDP for target status because the HTTP
55
+ * interface provides more reliable target state information during
56
+ * navigation transitions.
57
+ *
30
58
  * @param targetId - CDP target ID to wait for
31
- * @param expectedUrl - Expected URL (normalized)
59
+ * @param normalizedUrl - Expected URL (must be pre-normalized)
32
60
  * @param cdp - CDP connection instance
33
61
  * @param maxWaitMs - Maximum time to wait in milliseconds
62
+ * @throws Error if target doesn't become ready within maxWaitMs timeout
34
63
  */
35
- export declare function waitForTargetReady(targetId: string, expectedUrl: string, cdp: CDPConnection, maxWaitMs?: number): Promise<void>;
64
+ export declare function waitForTargetReady(targetId: string, normalizedUrl: string, cdp: CDPConnection, maxWaitMs?: number): Promise<void>;
36
65
  /**
37
66
  * Create a new tab or find existing tab with the target URL.
38
67
  *
39
- * This is the main entry point for tab management.
40
- * It tries to find an existing tab first, and if not found,
41
- * creates a new one.
68
+ * This is the main entry point for tab management with a clear workflow:
69
+ * when reuseTab=true, attempts to find and navigate existing tabs to avoid
70
+ * creating unnecessary browser tabs. When reuseTab=false or no suitable
71
+ * tab exists, creates a new tab for isolated testing scenarios.
72
+ *
73
+ * URL normalization happens once at entry to ensure consistent matching
74
+ * and navigation behavior throughout the entire workflow.
42
75
  *
43
- * @param url - Target URL
76
+ * @param url - Target URL (will be normalized once at entry)
44
77
  * @param cdp - CDP connection instance
45
78
  * @param reuseTab - If true, navigate existing tab instead of creating new one
46
79
  * @returns Target information
@@ -1 +1 @@
1
- {"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../src/connection/tabs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EACL,SAAS,EAKV,MAAM,aAAa,CAAC;AA8DrB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,EAAE,GACnB,SAAS,GAAG,IAAI,CAgClB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,SAAS,CAAC,CA0CpB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,aAAa,EAClB,SAAS,SAAQ,GAChB,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,aAAa,EAClB,QAAQ,UAAQ,GACf,OAAO,CAAC,SAAS,CAAC,CAqCpB"}
1
+ {"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../src/connection/tabs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAgBzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAsJzC;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,CA+B5F;AA0MD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAkChG;AA2CD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,aAAa,EAClB,SAAS,SAAkC,GAC1C,OAAO,CAAC,IAAI,CAAC,CA0Bf;AA+HD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,aAAa,EAClB,QAAQ,UAAoB,GAC3B,OAAO,CAAC,SAAS,CAAC,CAgCpB"}