@speedkit/cli 4.39.0 → 4.41.0

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 (37) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +10 -1
  3. package/dist/commands/airports_iata.json +9202 -1
  4. package/dist/commands/generate-customer-config.d.ts +2 -0
  5. package/dist/commands/generate-customer-config.js +7 -1
  6. package/dist/services/customer-config/customer-config-service-build-context.d.ts +8 -0
  7. package/dist/services/customer-config/customer-config-service-build-context.js +8 -0
  8. package/dist/services/customer-config/customer-config-service-factory.js +3 -1
  9. package/dist/services/customer-config/customer-config-service.d.ts +10 -7
  10. package/dist/services/customer-config/customer-config-service.js +138 -308
  11. package/dist/services/customer-config/index.d.ts +2 -0
  12. package/dist/services/customer-config/index.js +2 -0
  13. package/dist/services/customer-config/spec/wizard-answers.spec.d.ts +1 -0
  14. package/dist/services/customer-config/spec/wizard-answers.spec.js +207 -0
  15. package/dist/services/customer-config/wizard-answers.d.ts +48 -0
  16. package/dist/services/customer-config/wizard-answers.js +67 -0
  17. package/dist/services/customer-config/wizard-questions.d.ts +86 -0
  18. package/dist/services/customer-config/wizard-questions.js +400 -0
  19. package/dist/services/onboarding/browser/executable/executable-validator.js +1 -1
  20. package/dist/services/onboarding/browser/extension/devtools-panel.d.ts +36 -0
  21. package/dist/services/onboarding/browser/extension/devtools-panel.js +82 -0
  22. package/dist/services/onboarding/browser/extension/extension-bridge.d.ts +55 -24
  23. package/dist/services/onboarding/browser/extension/extension-bridge.js +161 -66
  24. package/dist/services/onboarding/onboarding-model.d.ts +29 -1
  25. package/dist/services/onboarding/onboarding-model.js +7 -13
  26. package/dist/services/onboarding/onboarding-service-factory.d.ts +1 -0
  27. package/dist/services/onboarding/onboarding-service-factory.js +24 -3
  28. package/dist/services/onboarding/onboarding-service.d.ts +8 -0
  29. package/dist/services/onboarding/onboarding-service.js +28 -0
  30. package/dist/services/onboarding/spec/browser/extension/devtools-panel.spec.d.ts +1 -0
  31. package/dist/services/onboarding/spec/browser/extension/devtools-panel.spec.js +99 -0
  32. package/dist/services/onboarding/spec/browser/extension/extension-bridge.spec.d.ts +1 -0
  33. package/dist/services/onboarding/spec/browser/extension/extension-bridge.spec.js +235 -0
  34. package/dist/services/onboarding/spec/onboarding-model.spec.js +29 -0
  35. package/dist/templates/speedKit.Revalidated.js +5 -1
  36. package/oclif.manifest.json +17 -2
  37. package/package.json +1 -1
@@ -0,0 +1,400 @@
1
+ import { ShopSystem, } from "./customer-config-service-model.js";
2
+ export const DEFAULT_RULES = {
3
+ appFlag: "the value of the -a flag",
4
+ detectedShopSystem: "the shop system that the site analysis detected; no default when it detected none",
5
+ japaneseHost: "true for a production host that ends in .jp, else false",
6
+ preCheckedFeatures: "every feature choice whose own default resolves to true",
7
+ };
8
+ const notShopify = {
9
+ key: "shopSystem",
10
+ notEquals: ShopSystem.SHOPIFY,
11
+ };
12
+ const fullConfig = { mode: "customer-config" };
13
+ export const WIZARD_QUESTIONS = [
14
+ {
15
+ key: "appName",
16
+ type: "string",
17
+ prompt: "[App] Enter desired Speed Kit app name:",
18
+ description: "The Speed Kit app name, in kebab-case. It also names the output directory.",
19
+ default: { rule: "appFlag" },
20
+ phase: "settings",
21
+ },
22
+ {
23
+ key: "productionHost",
24
+ type: "string",
25
+ prompt: "[Production] Enter production host (without https://):",
26
+ description: "The production host, without https://. The site analysis runs against it.",
27
+ suggestion: "www.<app>.de",
28
+ phase: "settings",
29
+ },
30
+ {
31
+ key: "analyzeSite",
32
+ type: "boolean",
33
+ prompt: "[Analysis] Analyze production site to auto-detect settings?",
34
+ description: "Whether the wizard fetches the production home to detect the shop system, the install.js and the feature defaults.",
35
+ default: true,
36
+ phase: "settings",
37
+ },
38
+ {
39
+ key: "shopSystem",
40
+ type: "select",
41
+ prompt: "[Shop System] Which shop system is in use?",
42
+ description: "The shop platform behind the storefront. It selects platform plugins, for example ShopifyPlugin.",
43
+ choices: [
44
+ ...Object.values(ShopSystem).filter((value) => value !== ShopSystem.OTHER),
45
+ ShopSystem.OTHER,
46
+ ].map((value) => ({ value })),
47
+ default: { rule: "detectedShopSystem" },
48
+ skipPromptWhenDefaulted: true,
49
+ phase: "settings",
50
+ },
51
+ {
52
+ key: "productionInstallJsPresent",
53
+ type: "boolean",
54
+ prompt: "[Production] Is the install.js already present?",
55
+ description: "Whether the production pages already load the Speed Kit install.js. If not, local testing force-installs it.",
56
+ default: { fromAnalysis: "hasInstallJs", fallback: false },
57
+ phase: "settings",
58
+ },
59
+ {
60
+ key: "staging",
61
+ type: "object",
62
+ prompt: "[Staging] Should a staging config also be added?",
63
+ description: 'A staging host to scaffold a second config for: { "host": "<host>", "installJsPresent": <bool> }, or null for none.',
64
+ default: null,
65
+ when: notShopify,
66
+ phase: "settings",
67
+ },
68
+ {
69
+ key: "needsCustomerApproval",
70
+ type: "boolean",
71
+ prompt: "[Approval] Must the customer approve a change before it may be activated?",
72
+ description: "Whether the customer signs off every change before sk deploy may activate a split above 0.",
73
+ default: { rule: "japaneseHost" },
74
+ engineerDecision: true,
75
+ phase: "settings",
76
+ },
77
+ {
78
+ key: "features",
79
+ type: "multiSelect",
80
+ prompt: "[Features] Select features to enable:",
81
+ description: "The features to scaffold. Each choice names the fact that decides it.",
82
+ default: { rule: "preCheckedFeatures" },
83
+ when: fullConfig,
84
+ phase: "settings",
85
+ choices: [
86
+ {
87
+ value: "removeLazyLoading",
88
+ label: "Lazy-Loading Removal / Preloading",
89
+ description: "Above-the-fold images arrive lazy-loaded in the server HTML (loading=lazy, data-src).",
90
+ default: { fromAnalysis: "removeLazyLoading", fallback: true },
91
+ },
92
+ {
93
+ value: "hasSoftNavigations",
94
+ label: "Soft Navigation Tracking",
95
+ description: "Any navigation changes the URL without a new document request: between page types, a PLP filter or sort, a PDP variant, or a checkout step.",
96
+ default: { fromAnalysis: "hasSoftNavigations", fallback: false },
97
+ },
98
+ {
99
+ value: "includeServiceWorker",
100
+ label: "Include existing Service Worker",
101
+ description: "The site registers its own service worker, and Speed Kit has to include it.",
102
+ default: { fromAnalysis: "includeServiceWorker", fallback: false },
103
+ },
104
+ {
105
+ value: "useGATracking",
106
+ label: "GA DataLayer Tracking",
107
+ description: "The site pushes its e-commerce events to a GA dataLayer, and Speed Kit reads them from there.",
108
+ default: { fromAnalysis: "useGATracking", fallback: true },
109
+ when: notShopify,
110
+ },
111
+ {
112
+ value: "withGoogleOptimize",
113
+ label: "Google Optimize Support",
114
+ description: "The site runs Google Optimize experiments.",
115
+ default: { fromAnalysis: "withGoogleOptimize", fallback: false },
116
+ },
117
+ {
118
+ value: "activateCfRocketLoaderPlugin",
119
+ label: "Cloudflare Rocket Loader Plugin",
120
+ description: "Cloudflare Rocket Loader defers the site's scripts.",
121
+ default: {
122
+ fromAnalysis: "activateCfRocketLoaderPlugin",
123
+ fallback: false,
124
+ },
125
+ },
126
+ {
127
+ value: "handleUsercentrics",
128
+ label: "Usercentrics Handling",
129
+ description: "The site loads the Usercentrics CMP (uc-block.bundle.js), which must run as a safe script.",
130
+ default: { fromAnalysis: "handleUsercentrics", fallback: false },
131
+ },
132
+ {
133
+ value: "useDisabledSitesApproach",
134
+ label: "Disabled Sites approach",
135
+ description: "The URLs do not tell the page types apart, so a whitelist of enabled pages is impractical.",
136
+ },
137
+ {
138
+ value: "activateImageOptimisation",
139
+ label: "Image Optimisation",
140
+ description: "Speed Kit should optimise images: no image CDN serves WebP already, and the app is no PoV.",
141
+ },
142
+ {
143
+ value: "addSSR",
144
+ label: "Server-Side Rendering (SSR)",
145
+ description: "Above-the-fold content is missing from the server HTML and renders client-side. Also enables device detection.",
146
+ },
147
+ {
148
+ value: "addDeviceDetection",
149
+ label: "Device Detection",
150
+ description: "The origin serves different HTML to mobile and desktop for the same URL.",
151
+ },
152
+ {
153
+ value: "isPOV",
154
+ label: "Enhanced PoV Tracking",
155
+ description: "The handover marks the engagement as a Proof of Value.",
156
+ },
157
+ {
158
+ value: "useScrapingBee",
159
+ label: "ScrapingBee",
160
+ description: "The origin answers by visitor geo-location, so the renderer must fetch through ScrapingBee.",
161
+ },
162
+ {
163
+ value: "addDowntimeDetection",
164
+ label: "Downtime Detection",
165
+ description: "The app needs the downtime detection script.",
166
+ },
167
+ ],
168
+ },
169
+ {
170
+ key: "serviceWorkerPath",
171
+ type: "string",
172
+ prompt: "[Service Worker] Enter path of Service Worker to be included:",
173
+ description: "The path of the site's own service worker script.",
174
+ default: "/sw.js",
175
+ when: { key: "features", includes: "includeServiceWorker" },
176
+ phase: "settings",
177
+ },
178
+ {
179
+ key: "ssrInnerShadowDomSupport",
180
+ type: "boolean",
181
+ prompt: "[SSR] Activate handling for customer-utilized Shadow DOMs?",
182
+ description: "The site renders content inside its own shadow roots, which the SSR snapshot must keep.",
183
+ default: false,
184
+ when: { key: "features", includes: "addSSR" },
185
+ phase: "settings",
186
+ },
187
+ {
188
+ key: "convertSoftToHardNavigations",
189
+ type: "boolean",
190
+ prompt: "[Soft Navigations] Convert soft navigations between home, PLP and PDP to hard navigations?",
191
+ description: "A soft navigation between home, PLP and PDP, or between PLP categories, becomes a hard one so cached documents serve it. Every other soft navigation stays soft.",
192
+ default: false,
193
+ when: { key: "features", includes: "hasSoftNavigations" },
194
+ phase: "settings",
195
+ },
196
+ {
197
+ key: "graduatePrePoc",
198
+ type: "boolean",
199
+ prompt: "Rename the pre-PoC files and continue?",
200
+ description: "Asked when the output directory holds a pre-PoC config: park its files as *_pre-poc next to the new config.",
201
+ engineerDecision: true,
202
+ phase: "output",
203
+ },
204
+ {
205
+ key: "existingDirectory",
206
+ type: "select",
207
+ prompt: "Output directory is not empty. How to proceed?",
208
+ description: "Asked when the output directory is not empty.",
209
+ choices: [
210
+ { value: "new-name", description: "Scaffold into a new directory." },
211
+ {
212
+ value: "overwrite-file-wise",
213
+ description: "Keep the directory, and answer per existing file.",
214
+ },
215
+ { value: "empty", description: "Delete the directory's content first." },
216
+ ],
217
+ engineerDecision: true,
218
+ phase: "output",
219
+ },
220
+ {
221
+ key: "newDirectoryName",
222
+ type: "string",
223
+ prompt: "Please enter new output directory name:",
224
+ description: 'The new directory name, when existingDirectory is "new-name".',
225
+ suggestion: "<app>-2",
226
+ phase: "output",
227
+ },
228
+ {
229
+ key: "overwriteExistingFiles",
230
+ type: "boolean",
231
+ prompt: "File already exists. Overwrite?",
232
+ description: 'Answers every "file already exists" question, when existingDirectory is "overwrite-file-wise".',
233
+ engineerDecision: true,
234
+ phase: "output",
235
+ },
236
+ ];
237
+ export function wizardQuestion(key) {
238
+ return WIZARD_QUESTIONS.find((question) => question.key === key);
239
+ }
240
+ /** Whether a condition holds for the answers so far and the wizard mode. */
241
+ export function conditionHolds(condition, answers, mode) {
242
+ if (!condition)
243
+ return true;
244
+ if ("allOf" in condition) {
245
+ return condition.allOf.every((c) => conditionHolds(c, answers, mode));
246
+ }
247
+ if ("mode" in condition)
248
+ return condition.mode === mode;
249
+ const value = answers[condition.key];
250
+ if ("equals" in condition && value !== condition.equals)
251
+ return false;
252
+ if ("notEquals" in condition && value === condition.notEquals)
253
+ return false;
254
+ if (condition.includes !== undefined &&
255
+ !(Array.isArray(value) && value.includes(condition.includes))) {
256
+ return false;
257
+ }
258
+ return true;
259
+ }
260
+ const DETECTED_SHOP_SYSTEMS = {
261
+ shopify: ShopSystem.SHOPIFY,
262
+ shopware: ShopSystem.SHOPWARE,
263
+ salesforce: ShopSystem.SALESFORCE,
264
+ oxid: ShopSystem.OXID,
265
+ plentymarkets: ShopSystem.PLENTYMARKETS,
266
+ magento: ShopSystem.MAGENTO,
267
+ woocommerce: ShopSystem.WOOCOMMERCE,
268
+ bigcommerce: ShopSystem.BIGCOMMERCE,
269
+ prestashop: ShopSystem.PRESTASHOP,
270
+ jtl: ShopSystem.JTL,
271
+ commercetools: ShopSystem.COMMERCETOOLS,
272
+ spryker: ShopSystem.SPRYKER,
273
+ shoptet: ShopSystem.SHOPTET,
274
+ ecforce: ShopSystem.ECFORCE,
275
+ futureshop: ShopSystem.FUTURESHOP,
276
+ };
277
+ /** The choices of a question that apply to the answers so far. */
278
+ export function applicableChoices(question, context) {
279
+ return (question.choices ?? []).filter((choice) => conditionHolds(choice.when, context.answers, context.mode));
280
+ }
281
+ /** Resolves a default to a value; `undefined` means the question has none here. */
282
+ export function resolveDefault(question, value, context) {
283
+ if (value === undefined || value === null || typeof value !== "object") {
284
+ return value;
285
+ }
286
+ if ("fromAnalysis" in value) {
287
+ return context.analysis
288
+ ? Boolean(context.analysis[value.fromAnalysis]) || value.fallback
289
+ : value.fallback;
290
+ }
291
+ switch (value.rule) {
292
+ case "appFlag":
293
+ return context.appName || undefined;
294
+ case "detectedShopSystem":
295
+ return context.analysis?.shopSystem
296
+ ? DETECTED_SHOP_SYSTEMS[context.analysis.shopSystem]
297
+ : undefined;
298
+ case "japaneseHost":
299
+ return /\.jp$/i.test((context.answers.productionHost ?? "").trim().replace(/\/.*$/, ""));
300
+ case "preCheckedFeatures":
301
+ return applicableChoices(question, context)
302
+ .filter((choice) => resolveDefault(question, choice.default, context) === true)
303
+ .map((choice) => choice.value);
304
+ }
305
+ }
306
+ /** Checks one answer against its question; returns the problem, or undefined. */
307
+ export function validateAnswer(question, value, context) {
308
+ const allowed = applicableChoices(question, context).map((c) => c.value);
309
+ switch (question.type) {
310
+ case "string":
311
+ if (typeof value !== "string" || value === "") {
312
+ return `"${question.key}" must be a non-empty string.`;
313
+ }
314
+ if (question.key === "appName" &&
315
+ !/^[\da-z]+(?:-[\da-z]+)*$/.test(value)) {
316
+ return `The app name "${value}" is no valid kebab-case.`;
317
+ }
318
+ return undefined;
319
+ case "boolean":
320
+ return typeof value === "boolean"
321
+ ? undefined
322
+ : `"${question.key}" must be true or false.`;
323
+ case "select":
324
+ return allowed.includes(value)
325
+ ? undefined
326
+ : `Unknown ${question.key} "${String(value)}". Use one of: ${allowed.join(", ")}.`;
327
+ case "multiSelect": {
328
+ if (!Array.isArray(value))
329
+ return `"${question.key}" must be a list.`;
330
+ const unknown = value.filter((v) => !allowed.includes(v));
331
+ return unknown.length === 0
332
+ ? undefined
333
+ : `Unknown ${question.key} here: ${unknown.join(", ")}. Use any of: ${allowed.join(", ")}.`;
334
+ }
335
+ case "object":
336
+ if (value === null)
337
+ return undefined;
338
+ if (typeof value !== "object" ||
339
+ typeof value.host !== "string") {
340
+ return `"${question.key}" must be null or an object with a "host".`;
341
+ }
342
+ return undefined;
343
+ }
344
+ }
345
+ /** The template variables that the answers decide. */
346
+ export function settingsFromAnswers(answers, mode) {
347
+ const shop = answers.shopSystem;
348
+ const settings = {
349
+ appName: answers.appName,
350
+ production: {
351
+ host: answers.productionHost,
352
+ forceInstall: !answers.productionInstallJsPresent,
353
+ },
354
+ staging: answers.staging
355
+ ? {
356
+ host: answers.staging.host,
357
+ forceInstall: !answers.staging.installJsPresent,
358
+ }
359
+ : undefined,
360
+ needsCustomerApproval: answers.needsCustomerApproval,
361
+ shopSystemName: shop === ShopSystem.OTHER ? undefined : shop,
362
+ isShopify: shop === ShopSystem.SHOPIFY || undefined,
363
+ isShopware: shop === ShopSystem.SHOPWARE || undefined,
364
+ isSalesforce: shop === ShopSystem.SALESFORCE || undefined,
365
+ isOxid: shop === ShopSystem.OXID || undefined,
366
+ isPlentymarkets: shop === ShopSystem.PLENTYMARKETS || undefined,
367
+ };
368
+ if (mode === "pre-poc")
369
+ return settings;
370
+ const features = answers.features ?? [];
371
+ const featureChoices = wizardQuestion("features").choices;
372
+ for (const choice of featureChoices) {
373
+ if (choice.value !== "includeServiceWorker") {
374
+ settings[choice.value] = features.includes(choice.value);
375
+ }
376
+ }
377
+ // SSR always implies device detection
378
+ settings.addDeviceDetection = settings.addSSR || settings.addDeviceDetection;
379
+ settings.includeServiceWorker = features.includes("includeServiceWorker")
380
+ ? answers.serviceWorkerPath
381
+ : undefined;
382
+ settings.addSSRInnerShadowDomSupport = settings.addSSR
383
+ ? answers.ssrInnerShadowDomSupport
384
+ : undefined;
385
+ settings.convertSoftToHardNavigations = settings.hasSoftNavigations
386
+ ? answers.convertSoftToHardNavigations
387
+ : undefined;
388
+ return settings;
389
+ }
390
+ /** The table as `--print-questions` prints it. */
391
+ export function describeWizardQuestions(cliVersion) {
392
+ return {
393
+ cliVersion,
394
+ usage: "Answer the settings questions whose `when` holds, then run sk generate-customer-config -a <app> --answers <file>. " +
395
+ "A key you leave out takes its default; a question without a default must be answered. " +
396
+ "Ask the engineer before you answer a question marked engineerDecision.",
397
+ defaultRules: DEFAULT_RULES,
398
+ questions: WIZARD_QUESTIONS,
399
+ };
400
+ }
@@ -57,7 +57,7 @@ export class ExecutableValidator {
57
57
  // on windows executing chrome to gather the version will spawn a chromeProcess
58
58
  // so we use a powershell instead. Emit `<ProductName> <FileVersion>` so the
59
59
  // output is shape-compatible with `chrome --version` on macOS/Linux —
60
- // downstream consumers (isChromeBrowser, log lines) can stay OS-agnostic.
60
+ // downstream consumers (the headed user agent, log lines) can stay OS-agnostic.
61
61
  if (this.environment.oclif.windows) {
62
62
  return this.cli.execSync(`$i = (Get-Item '${this.environment.settings.chromePath}').VersionInfo; "$($i.ProductName) $($i.FileVersion)"`, { shell: "powershell.exe" });
63
63
  }
@@ -0,0 +1,36 @@
1
+ import { Page } from "puppeteer";
2
+ export interface ShownPanel {
3
+ /** The DevTools tab id, `chrome-extension://<id><panel title>`. */
4
+ panel: string;
5
+ /** DevTools was closed and this opened it, rather than switching tabs. */
6
+ openedDevTools: boolean;
7
+ }
8
+ export declare class PanelNotFoundError extends Error {
9
+ /** The tabs DevTools did show, so a missing panel can be told from a renamed one. */
10
+ readonly tabs: string[];
11
+ constructor(message: string,
12
+ /** The tabs DevTools did show, so a missing panel can be told from a renamed one. */
13
+ tabs: string[]);
14
+ }
15
+ /**
16
+ * Open DevTools for `page` and bring the devtools extension's panel to the
17
+ * front.
18
+ *
19
+ * There is no public way to do this. `chrome.devtools.panels` cannot select a
20
+ * panel, and CDP can open DevTools but knows nothing about what is in it. So
21
+ * this reaches into the DevTools frontend itself — `page.openDevTools()` hands
22
+ * back the DevTools window as a page, and its own `InspectorView` does the
23
+ * switching. That is internal API and may move in a Chrome update, which is why
24
+ * every caller treats a failure here as a missing convenience, never as a
25
+ * failed run.
26
+ *
27
+ * `openDevTools` returns the window already open for the page when there is
28
+ * one, so this never stacks a second DevTools on a headed run, where
29
+ * `devtools: true` has opened one for every tab.
30
+ *
31
+ * Polls, for two things that each take a moment on a DevTools window this has
32
+ * just opened: its frontend has to initialise before `InspectorView` exists at
33
+ * all — asking earlier throws — and the extension registers its panel only
34
+ * once its devtools page has loaded, after that.
35
+ */
36
+ export declare function showDevtoolsPanel(page: Page, extensionId: string, timeoutMs?: number): Promise<ShownPanel>;
@@ -0,0 +1,82 @@
1
+ const POLL_INTERVAL_MS = 200;
2
+ const DEFAULT_TIMEOUT_MS = 10_000;
3
+ export class PanelNotFoundError extends Error {
4
+ tabs;
5
+ constructor(message,
6
+ /** The tabs DevTools did show, so a missing panel can be told from a renamed one. */
7
+ tabs) {
8
+ super(message);
9
+ this.tabs = tabs;
10
+ }
11
+ }
12
+ /**
13
+ * Open DevTools for `page` and bring the devtools extension's panel to the
14
+ * front.
15
+ *
16
+ * There is no public way to do this. `chrome.devtools.panels` cannot select a
17
+ * panel, and CDP can open DevTools but knows nothing about what is in it. So
18
+ * this reaches into the DevTools frontend itself — `page.openDevTools()` hands
19
+ * back the DevTools window as a page, and its own `InspectorView` does the
20
+ * switching. That is internal API and may move in a Chrome update, which is why
21
+ * every caller treats a failure here as a missing convenience, never as a
22
+ * failed run.
23
+ *
24
+ * `openDevTools` returns the window already open for the page when there is
25
+ * one, so this never stacks a second DevTools on a headed run, where
26
+ * `devtools: true` has opened one for every tab.
27
+ *
28
+ * Polls, for two things that each take a moment on a DevTools window this has
29
+ * just opened: its frontend has to initialise before `InspectorView` exists at
30
+ * all — asking earlier throws — and the extension registers its panel only
31
+ * once its devtools page has loaded, after that.
32
+ */
33
+ export async function showDevtoolsPanel(page, extensionId, timeoutMs = DEFAULT_TIMEOUT_MS) {
34
+ const openedDevTools = !(await page.hasDevTools());
35
+ const devtools = await page.openDevTools();
36
+ const prefix = `chrome-extension://${extensionId}`;
37
+ const deadline = Date.now() + timeoutMs;
38
+ let tabs = [];
39
+ let notReady;
40
+ // Puppeteer drops the arguments of a string expression, so the prefix is
41
+ // spliced in rather than passed.
42
+ const expression = `(${SELECT_PANEL})(${JSON.stringify(prefix)})`;
43
+ for (;;) {
44
+ try {
45
+ const answer = (await devtools.evaluate(expression));
46
+ notReady = null;
47
+ tabs = answer.tabs;
48
+ if (answer.selected) {
49
+ return { panel: answer.selected, openedDevTools };
50
+ }
51
+ }
52
+ catch (error) {
53
+ notReady = error;
54
+ }
55
+ if (Date.now() >= deadline)
56
+ break;
57
+ await sleep(POLL_INTERVAL_MS);
58
+ }
59
+ // Still throwing at the deadline is not a frontend that is starting: it is
60
+ // one whose internals are not the ones this was written against.
61
+ if (notReady) {
62
+ throw notReady;
63
+ }
64
+ throw new PanelNotFoundError(`the Speed Kit panel did not appear in DevTools within ${timeoutMs}ms`, tabs);
65
+ }
66
+ /**
67
+ * Runs inside the DevTools frontend, whose modules resolve relative to
68
+ * `devtools://devtools/bundled/`. A string, because TypeScript would try to
69
+ * resolve the import against this repository.
70
+ */
71
+ const SELECT_PANEL = `async (prefix) => {
72
+ const { InspectorView } = await import("./ui/legacy/legacy.js");
73
+ const view = InspectorView.InspectorView.instance();
74
+ const tabs = view.tabbedPane.tabIds();
75
+ const panel = tabs.find((id) => id.startsWith(prefix));
76
+ if (!panel) return { tabs, selected: null };
77
+ await view.showPanel(panel);
78
+ return { tabs, selected: view.tabbedPane.selectedTabId };
79
+ }`;
80
+ function sleep(ms) {
81
+ return new Promise((resolve) => setTimeout(resolve, ms));
82
+ }
@@ -3,27 +3,41 @@ import { DevelopmentToolsMessage } from "../../onboarding-model.js";
3
3
  import { CliServiceInterface } from "../../../cli/index.js";
4
4
  /**
5
5
  * Name heuristic for the devtools extension, shared by ExtensionValidator
6
- * (is one among the loaded extensions?) and the service-worker lookup below.
6
+ * (is one among the loaded extensions?) and the extension lookup below.
7
7
  */
8
8
  export declare function isDevtoolsExtensionName(name: string): boolean;
9
9
  /**
10
10
  * Writes onboarding state (messages, status) into the devtools extension's
11
- * chrome.storage.local via a CDP session against the extension's MV3
12
- * service-worker target. The devtools extension subscribes via
11
+ * chrome.storage.local, which the panel subscribes to via
13
12
  * chrome.storage.onChanged. Replaces the legacy `window.skCliMessages` page
14
13
  * injection — no more customer-visible global state.
15
14
  *
15
+ * **The write does not go through the extension's service worker.** It used
16
+ * to, and an MV3 worker that has stopped is not a target anyone can attach to:
17
+ * nothing restarted it, so every write after it stopped failed for the rest of
18
+ * the run and the panel kept showing whatever it had last received.
19
+ * `Extensions.setStorageItems` writes the storage from the browser side, works
20
+ * whether the worker runs or not, and restarts it as a side effect. It has to
21
+ * be sent from a session on a page the extension can access — an http(s) page,
22
+ * given its `<all_urls>` — because a browser-level session is refused. The
23
+ * worker stays as the fallback for a Chrome that refuses the command.
24
+ *
16
25
  * Lifecycle: construct once per browser, call `init()` after the browser is
17
- * launched and the devtools extension has loaded, then call `writeMessages`
18
- * whenever the message list changes. Constructed with
19
- * `devtoolsExtensionLoaded: false` (no devtools extension among the browser's
20
- * extensions) the bridge stays unavailable and never looks for a target.
26
+ * launched, then call `writeMessages` whenever the message list changes.
27
+ * Constructed with `devtoolsExtensionLoaded: false` (no devtools extension
28
+ * among the browser's extensions) the bridge stays unavailable and never
29
+ * looks for one.
21
30
  */
22
31
  export declare class ExtensionBridge {
23
32
  private readonly cli;
24
33
  private readonly devtoolsExtensionLoaded;
25
34
  private browser;
26
35
  private extensionId;
36
+ /** The newest snapshot not yet stored. Older ones are never worth writing. */
37
+ private pending;
38
+ private writing;
39
+ /** Set while writes fail, so an outage is reported once, not per write. */
40
+ private failing;
27
41
  constructor(cli: CliServiceInterface, devtoolsExtensionLoaded: boolean);
28
42
  /**
29
43
  * false when the browser is started without a devtools extension, so there
@@ -31,33 +45,50 @@ export declare class ExtensionBridge {
31
45
  */
32
46
  get isAvailable(): boolean;
33
47
  /**
34
- * Bind the bridge to a freshly-launched browser, discover the
35
- * devtools-extension's service-worker target, and cache its extension ID.
36
- * Polls for ~INIT_POLL_TIMEOUT_MS because MV3 service workers are
37
- * sometimes not registered as targets until Chrome has finished loading
38
- * the extension. Throws if no matching SW target is found in time.
48
+ * Bind the bridge to a freshly-launched browser and find the devtools
49
+ * extension's ID.
50
+ *
51
+ * Polls, because Puppeteer's `launch` returns before `enableExtensions` has
52
+ * finished installing. Throws if the extension does not show up in time.
39
53
  */
40
54
  init(browser: Browser): Promise<void>;
41
55
  /**
42
- * Write the current messages snapshot into chrome.storage.local. One retry
43
- * on transient failures (MV3 service workers can briefly disappear during
44
- * respawn). Failures are surfaced via `cli.writeError` but do not throw —
45
- * a missed write is degraded UX, not a fatal onboarding failure.
56
+ * Store the current messages snapshot in chrome.storage.local.
57
+ *
58
+ * Only the newest snapshot is written: one write is in flight at a time, and
59
+ * a snapshot that arrives meanwhile replaces the one waiting behind it, so an
60
+ * older snapshot can never land after a newer one. A snapshot that fails
61
+ * stays pending and is retried on the next page load. Failures are reported
62
+ * but never thrown — a missed write is degraded UX, not a fatal onboarding
63
+ * failure.
46
64
  */
47
65
  writeMessages(messages: DevelopmentToolsMessage[]): Promise<void>;
48
- private evaluateInServiceWorker;
66
+ /** Whether the bridge found an extension to talk to at all. */
67
+ get available(): boolean;
68
+ /** The devtools extension's ID, once `init()` has found it. */
69
+ get devtoolsExtensionId(): string | null;
70
+ private drain;
71
+ private writePending;
72
+ private store;
73
+ private reportFailure;
74
+ private reportRecovery;
75
+ private setStorageItems;
76
+ private findWebPage;
49
77
  /**
50
- * Look up the service-worker target by cached extension ID. Returns null
51
- * when the SW is dormant — callers handle that via retry.
78
+ * Run an expression inside the devtools extension's service worker, waiting
79
+ * briefly for one when none is running. Only the fallback: waiting does not
80
+ * start a worker, it only catches one that is starting anyway.
52
81
  */
53
- private getServiceWorkerTarget;
82
+ private evaluateInServiceWorker;
54
83
  /**
55
- * Scan service-worker targets, evaluate `chrome.runtime.getManifest().name`
56
- * on each, and return the first whose name matches the devtools-extension
57
- * heuristic. We discover the extension by name (not by computing the ID
58
- * from the unpacked path) because unpacked-extension IDs depend on the
84
+ * The devtools extension's ID, from `Extensions.getExtensions` — which needs
85
+ * no running worker — or, when Chrome refuses that, from the manifest name
86
+ * of a running extension worker. Discovered by name rather than computed
87
+ * from the unpacked path, because unpacked-extension IDs depend on the
59
88
  * absolute path and OS path normalization.
60
89
  */
90
+ private findExtensionId;
91
+ private listExtensions;
61
92
  private findDevtoolsServiceWorker;
62
93
  private readManifestName;
63
94
  private extractExtensionId;