@speedkit/cli 4.47.0 → 4.49.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 (39) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +103 -1
  3. package/dist/commands/onboarding.d.ts +2 -0
  4. package/dist/commands/onboarding.js +1 -0
  5. package/dist/commands/revalidate/jobs.d.ts +16 -0
  6. package/dist/commands/revalidate/jobs.js +80 -0
  7. package/dist/commands/revalidate/start.d.ts +15 -0
  8. package/dist/commands/revalidate/start.js +25 -0
  9. package/dist/commands/revalidate/unblock.d.ts +12 -0
  10. package/dist/commands/revalidate/unblock.js +13 -0
  11. package/dist/commands/revalidate/wait.d.ts +12 -0
  12. package/dist/commands/revalidate/wait.js +13 -0
  13. package/dist/services/browser-fetch/device-emulation.d.ts +16 -3
  14. package/dist/services/browser-fetch/device-emulation.js +32 -17
  15. package/dist/services/browser-fetch/spec/device-emulation.spec.js +20 -0
  16. package/dist/services/onboarding/browser/emulate-device.d.ts +13 -0
  17. package/dist/services/onboarding/browser/emulate-device.js +50 -0
  18. package/dist/services/onboarding/browser/launch-browser.js +7 -2
  19. package/dist/services/onboarding/onboarding-model.d.ts +27 -6
  20. package/dist/services/onboarding/onboarding-model.js +88 -15
  21. package/dist/services/onboarding/onboarding-service-build-context.d.ts +7 -0
  22. package/dist/services/onboarding/onboarding-service-build-context.js +12 -0
  23. package/dist/services/onboarding/onboarding-service-factory.d.ts +7 -0
  24. package/dist/services/onboarding/onboarding-service-factory.js +34 -1
  25. package/dist/services/onboarding/spec/onboarding-model.spec.js +93 -2
  26. package/dist/services/onboarding/spec/onboarding-service-build-context.spec.js +16 -1
  27. package/dist/services/revalidate/index.d.ts +1 -0
  28. package/dist/services/revalidate/index.js +1 -0
  29. package/dist/services/revalidate/revalidate-factory.d.ts +1 -1
  30. package/dist/services/revalidate/revalidate-jobs-build-context.d.ts +56 -0
  31. package/dist/services/revalidate/revalidate-jobs-build-context.js +69 -0
  32. package/dist/services/revalidate/revalidate-model.d.ts +30 -0
  33. package/dist/services/revalidate/revalidate-model.js +22 -0
  34. package/dist/services/revalidate/revalidate-service.d.ts +29 -1
  35. package/dist/services/revalidate/revalidate-service.js +89 -1
  36. package/dist/services/revalidate/spec/revalidate-jobs.spec.d.ts +1 -0
  37. package/dist/services/revalidate/spec/revalidate-jobs.spec.js +130 -0
  38. package/oclif.manifest.json +187 -1
  39. package/package.json +1 -1
@@ -1,13 +1,18 @@
1
- import { CDPSession } from "puppeteer";
1
+ import { CDPSession, Viewport } from "puppeteer";
2
2
  import { Protocol } from "puppeteer-core";
3
3
  import { AbortResponse } from "./browser/abort-response.js";
4
4
  import { task } from "./todo-collector.js";
5
5
  import { VanillaPuppeteer } from "puppeteer-extra";
6
6
  import { ChromeFeatureFinding, ChromeFlagDuplicate } from "../../helpers/chrome-flags.js";
7
7
  import { CliEnvironment } from "../cli/index.js";
8
+ import { DeviceEmulation, FetchDevice } from "../browser-fetch/device-emulation.js";
8
9
  export declare const HEADLESS_PARITY_ARGS: string[];
9
10
  declare const HEADLESS_DEFAULT_ARGS_TO_DROP: string[];
10
11
  export { HEADLESS_DEFAULT_ARGS_TO_DROP };
12
+ /** A device as `--device` emulates it: always with a viewport, also for the desktop. */
13
+ export type BrowserDeviceEmulation = DeviceEmulation & {
14
+ viewport: Viewport;
15
+ };
11
16
  export declare const BROWSER_EVENTS: {
12
17
  DISCONNECTED: string;
13
18
  FETCH_AUTH_REQUIRED: string;
@@ -44,17 +49,33 @@ export declare class BrowserContext {
44
49
  readonly debuggingPort: boolean;
45
50
  readonly headless: boolean;
46
51
  readonly debugPort: number;
52
+ readonly device?: FetchDevice;
47
53
  /** Everything sk passes before the customer's chromeFlags. */
48
54
  private readonly skArgs;
49
55
  readonly browserArgs: string[];
50
56
  readonly chromePath: string;
51
- constructor(domain: string, browserVersionString?: string, chromeFlags?: string[], environment?: CliEnvironment, userAgent?: string, debuggingPort?: boolean, headless?: boolean, debugPort?: number);
57
+ /** The device of `--device`, or undefined to leave Chrome as it launches. */
58
+ readonly emulation?: BrowserDeviceEmulation;
59
+ constructor(domain: string, browserVersionString?: string, chromeFlags?: string[], environment?: CliEnvironment, userAgent?: string, debuggingPort?: boolean, headless?: boolean, debugPort?: number, device?: FetchDevice);
60
+ /**
61
+ * The user agent is a launch flag rather than only a CDP override on purpose: a per-page
62
+ * `Network.setUserAgentOverride` never reaches a Service Worker that no CDP client holds, so
63
+ * Speed Kit would resolve the wrong device there, and in headless the dynamic-block refetch
64
+ * would leak the headless token and re-poison the merged body.
65
+ *
66
+ * Pointer, hover and touch are launch flags for the same reason: they apply browser-wide.
67
+ */
68
+ private getEmulationArgs;
52
69
  /**
53
- * Applied as a launch flag rather than over CDP on purpose: a per-page
54
- * `Network.setUserAgentOverride` never reaches the Service Worker, so Speed Kit's dynamic-block
55
- * refetch would still leak the headless token and re-poison the merged body.
70
+ * Device metrics for `Emulation.setDeviceMetricsOverride`, or null without `--device`.
71
+ *
72
+ * `screenWidth`/`screenHeight` are set explicitly, unlike Puppeteer's own `setViewport`: the Speed
73
+ * Kit snippet persists `window.screen.width` and `devicePixelRatio` into the Service Worker cache,
74
+ * and the Asset API derives image downscaling from exactly those two values.
56
75
  */
57
- private getHeadlessParityArgs;
76
+ getDeviceMetricsOverride(): Protocol.Emulation.SetDeviceMetricsOverrideRequest | null;
77
+ /** The touch override that goes with the metrics, or null without `--device`. */
78
+ getTouchEmulation(): Protocol.Emulation.SetTouchEmulationEnabledRequest | null;
58
79
  private getBrowserExtensionPath;
59
80
  /** The system-specific chromeFlags of the user config, appended to every other arg. */
60
81
  private getSystemChromeFlags;
@@ -3,6 +3,7 @@ import { buildHeadedUserAgent } from "./browser/executable/headed-user-agent.js"
3
3
  import { resolve } from "node:path";
4
4
  import { defaultArgs } from "puppeteer";
5
5
  import { findChromeFeatureFindings, findDuplicateChromeFlags, isFeatureListFlag, mergeChromeFeatureFlags, } from "../../helpers/chrome-flags.js";
6
+ import { DEVICE_VIEWPORTS, deviceEmulation, } from "../browser-fetch/device-emulation.js";
6
7
  const DEFAULT_BROWSER_ARGS = [
7
8
  // No `Translate`: Chrome's translate code has no feature of that name, and Puppeteer disables it anyway.
8
9
  "--enable-features=NetworkService",
@@ -14,13 +15,16 @@ const DEFAULT_BROWSER_ARGS = [
14
15
  // triggered by the flag above. Value is arbitrary and only used as an identifier.
15
16
  "--test-type=speed-kit-cli",
16
17
  ];
18
+ // Blink enums: HoverType kNone=1, kHover=2; PointerType kCoarse=2, kFine=4.
19
+ const FINE_POINTER_SETTINGS = "--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4";
20
+ const COARSE_POINTER_SETTINGS = "--blink-settings=primaryHoverType=1,availableHoverTypes=1,primaryPointerType=2,availablePointerTypes=2";
17
21
  // Headless Chrome differs from headed in ways customer bot detection and responsive layout both
18
22
  // key on, so a page can render differently — or not at all — depending on the mode. Each entry
19
23
  // below erases one measured difference; see HEADLESS_DEFAULT_ARGS_TO_DROP for the counterpart.
20
24
  export const HEADLESS_PARITY_ARGS = [
21
25
  // Headless exposes no pointing device, so `hover: none` / `any-pointer: coarse` send sites down
22
26
  // their touch code path.
23
- "--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4",
27
+ FINE_POINTER_SETTINGS,
24
28
  // Headless otherwise pins the screen to 800x600, i.e. a tablet breakpoint. --screen-info is what
25
29
  // overrides it; Chrome's own --ozone-override-screen-size is not reachable via ignoreDefaultArgs.
26
30
  "--window-size=1920,1200",
@@ -33,6 +37,12 @@ const HEADLESS_DEFAULT_ARGS_TO_DROP = [
33
37
  "--hide-scrollbars",
34
38
  ];
35
39
  export { HEADLESS_DEFAULT_ARGS_TO_DROP };
40
+ /** `--device desktop` presents Chrome on Windows, the most common Chrome desktop in RUM (60%). */
41
+ const DESKTOP_PLATFORM = "win32";
42
+ /** Room next to an emulated viewport for the DevTools panel that `devtools: true` docks in headed mode. */
43
+ const DEVTOOLS_GUTTER = 520;
44
+ /** What Chrome reports for a touchscreen phone or tablet. */
45
+ const MAX_TOUCH_POINTS = 5;
36
46
  export const BROWSER_EVENTS = {
37
47
  DISCONNECTED: "disconnected",
38
48
  FETCH_AUTH_REQUIRED: "Fetch.authRequired",
@@ -69,11 +79,14 @@ export class BrowserContext {
69
79
  debuggingPort;
70
80
  headless;
71
81
  debugPort;
82
+ device;
72
83
  /** Everything sk passes before the customer's chromeFlags. */
73
84
  skArgs;
74
85
  browserArgs;
75
86
  chromePath;
76
- constructor(domain, browserVersionString = "unknown", chromeFlags, environment, userAgent, debuggingPort = false, headless = false, debugPort = 9222) {
87
+ /** The device of `--device`, or undefined to leave Chrome as it launches. */
88
+ emulation;
89
+ constructor(domain, browserVersionString = "unknown", chromeFlags, environment, userAgent, debuggingPort = false, headless = false, debugPort = 9222, device) {
77
90
  this.domain = domain;
78
91
  this.browserVersionString = browserVersionString;
79
92
  this.chromeFlags = chromeFlags;
@@ -82,6 +95,7 @@ export class BrowserContext {
82
95
  this.debuggingPort = debuggingPort;
83
96
  this.headless = headless;
84
97
  this.debugPort = debugPort;
98
+ this.device = device;
85
99
  this.domain = domain;
86
100
  this.chromeFlags = chromeFlags || [];
87
101
  this.chromePath = resolve(environment.settings.chromePath);
@@ -95,14 +109,19 @@ export class BrowserContext {
95
109
  const temporaryProfileDirectory = browserConfig.loadProfileTempDir();
96
110
  browserArguments.push(`--user-data-dir=${temporaryProfileDirectory}`);
97
111
  }
98
- if (this.headless) {
99
- this.userAgent =
100
- this.userAgent ?? buildHeadedUserAgent(browserVersionString);
112
+ if (device) {
113
+ this.emulation = {
114
+ ...deviceEmulation(browserVersionString, device, DESKTOP_PLATFORM),
115
+ viewport: DEVICE_VIEWPORTS[device],
116
+ };
101
117
  }
118
+ this.userAgent ??=
119
+ this.emulation?.userAgent ??
120
+ (this.headless ? buildHeadedUserAgent(browserVersionString) : undefined);
102
121
  this.skArgs = [
103
122
  ...browserArguments,
104
123
  `--unsafely-treat-insecure-origin-as-secure=${domain}`,
105
- ...this.getHeadlessParityArgs(),
124
+ ...this.getEmulationArgs(),
106
125
  ];
107
126
  this.browserArgs = [
108
127
  ...this.skArgs,
@@ -111,18 +130,68 @@ export class BrowserContext {
111
130
  ];
112
131
  }
113
132
  /**
114
- * Applied as a launch flag rather than over CDP on purpose: a per-page
115
- * `Network.setUserAgentOverride` never reaches the Service Worker, so Speed Kit's dynamic-block
116
- * refetch would still leak the headless token and re-poison the merged body.
133
+ * The user agent is a launch flag rather than only a CDP override on purpose: a per-page
134
+ * `Network.setUserAgentOverride` never reaches a Service Worker that no CDP client holds, so
135
+ * Speed Kit would resolve the wrong device there, and in headless the dynamic-block refetch
136
+ * would leak the headless token and re-poison the merged body.
137
+ *
138
+ * Pointer, hover and touch are launch flags for the same reason: they apply browser-wide.
117
139
  */
118
- getHeadlessParityArgs() {
140
+ getEmulationArgs() {
141
+ const userAgentArgs = this.userAgent
142
+ ? [`--user-agent=${this.userAgent}`]
143
+ : [];
144
+ if (this.emulation) {
145
+ const { width, height, hasTouch } = this.emulation.viewport;
146
+ const windowWidth = this.headless ? width : width + DEVTOOLS_GUTTER;
147
+ return [
148
+ hasTouch ? COARSE_POINTER_SETTINGS : FINE_POINTER_SETTINGS,
149
+ // Makes `'ontouchend' in document` match the device. The Speed Kit snippet persists it into
150
+ // the Service Worker as `supportsTouch`, and every RuleSet of the config is built with it.
151
+ `--touch-events=${hasTouch ? "enabled" : "disabled"}`,
152
+ `--window-size=${windowWidth},${height}`,
153
+ // Headless otherwise pins the screen to 800x600; --screen-info is what overrides it.
154
+ ...(this.headless ? [`--screen-info={${windowWidth}x${height}}`] : []),
155
+ ...userAgentArgs,
156
+ ];
157
+ }
119
158
  if (!this.headless) {
120
159
  return [];
121
160
  }
122
- return [
123
- ...HEADLESS_PARITY_ARGS,
124
- ...(this.userAgent ? [`--user-agent=${this.userAgent}`] : []),
125
- ];
161
+ return [...HEADLESS_PARITY_ARGS, ...userAgentArgs];
162
+ }
163
+ /**
164
+ * Device metrics for `Emulation.setDeviceMetricsOverride`, or null without `--device`.
165
+ *
166
+ * `screenWidth`/`screenHeight` are set explicitly, unlike Puppeteer's own `setViewport`: the Speed
167
+ * Kit snippet persists `window.screen.width` and `devicePixelRatio` into the Service Worker cache,
168
+ * and the Asset API derives image downscaling from exactly those two values.
169
+ */
170
+ getDeviceMetricsOverride() {
171
+ if (!this.emulation) {
172
+ return null;
173
+ }
174
+ const { width, height, deviceScaleFactor, isMobile, isLandscape } = this.emulation.viewport;
175
+ return {
176
+ width,
177
+ height,
178
+ screenWidth: width,
179
+ screenHeight: height,
180
+ deviceScaleFactor,
181
+ mobile: isMobile,
182
+ screenOrientation: isLandscape
183
+ ? { type: "landscapePrimary", angle: 90 }
184
+ : { type: "portraitPrimary", angle: 0 },
185
+ };
186
+ }
187
+ /** The touch override that goes with the metrics, or null without `--device`. */
188
+ getTouchEmulation() {
189
+ if (!this.emulation) {
190
+ return null;
191
+ }
192
+ return this.emulation.viewport.hasTouch
193
+ ? { enabled: true, maxTouchPoints: MAX_TOUCH_POINTS }
194
+ : { enabled: false };
126
195
  }
127
196
  getBrowserExtensionPath() {
128
197
  if (this.environment?.settings.chromeExtensionPaths) {
@@ -188,7 +257,11 @@ export class BrowserContext {
188
257
  // the "Chrome is being controlled by automated test software" infobar.
189
258
  ignoreDefaultArgs: [
190
259
  "--enable-automation",
191
- ...(this.headless ? HEADLESS_DEFAULT_ARGS_TO_DROP : []),
260
+ // Keep Puppeteer's --hide-scrollbars for a touch device: it has overlay scrollbars, so
261
+ // restoring the 15px desktop ones would be the wrong parity to fix.
262
+ ...(this.headless && !this.emulation?.viewport.hasTouch
263
+ ? HEADLESS_DEFAULT_ARGS_TO_DROP
264
+ : []),
192
265
  ],
193
266
  };
194
267
  // One way for every Chromium build. Branded Chrome ignores
@@ -1,5 +1,6 @@
1
1
  import { Interfaces } from "@oclif/core";
2
2
  import { CliEnvironment, CommandContextValues } from "../cli/index.js";
3
+ import { FetchDevice } from "../browser-fetch/device-emulation.js";
3
4
  /**
4
5
  * Gives a bare `--inject` its default value, because oclif knows no flag with an optional value.
5
6
  * A value is the next argument, unless that argument is a flag.
@@ -18,6 +19,8 @@ declare const flags: {
18
19
  verboseLevel: Interfaces.BooleanFlag<boolean>;
19
20
  ignoreContentSecurityPolicy: Interfaces.BooleanFlag<boolean>;
20
21
  headless: Interfaces.BooleanFlag<boolean>;
22
+ device: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
23
+ mobile: Interfaces.BooleanFlag<boolean>;
21
24
  browse: Interfaces.BooleanFlag<boolean>;
22
25
  inject: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
23
26
  app: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
@@ -38,6 +41,8 @@ export interface OnboardingServiceBuildContextValues extends CommandContextValue
38
41
  readonly debuggingPort: boolean;
39
42
  readonly headless: boolean;
40
43
  readonly debugPort: number;
44
+ /** The device `--device` or `--mobile` emulates. */
45
+ readonly device?: FetchDevice;
41
46
  readonly browserFetch: boolean;
42
47
  readonly browse: boolean;
43
48
  readonly inject: boolean;
@@ -62,6 +67,8 @@ export declare class OnboardingServiceBuildContext extends OnboardingServiceBuil
62
67
  verboseLevel: Interfaces.BooleanFlag<boolean>;
63
68
  ignoreContentSecurityPolicy: Interfaces.BooleanFlag<boolean>;
64
69
  headless: Interfaces.BooleanFlag<boolean>;
70
+ device: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
71
+ mobile: Interfaces.BooleanFlag<boolean>;
65
72
  browse: Interfaces.BooleanFlag<boolean>;
66
73
  inject: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
67
74
  app: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
@@ -1,6 +1,7 @@
1
1
  import { Args, Flags } from "@oclif/core";
2
2
  import { CLI_CONFIG_IS_TEST, CLI_CONFIG_NAME, } from "../integration-api/customer-config-flags.js";
3
3
  import { Context } from "../../models/context.js";
4
+ import { FETCH_DEVICES, } from "../browser-fetch/device-emulation.js";
4
5
  /** The value `--inject` gets when it is passed without one. */
5
6
  const LATEST_INSTALLATION = "latest";
6
7
  /**
@@ -64,6 +65,15 @@ const flags = {
64
65
  default: false,
65
66
  description: "Run Chrome in headless mode (for CI environments). Implicitly enables remote debugging port.",
66
67
  }),
68
+ device: Flags.string({
69
+ options: [...FETCH_DEVICES],
70
+ description: "Emulate a device in every page and Service Worker: user agent, client hints, viewport, pointer and touch. Without it, Chrome runs as it launches.",
71
+ }),
72
+ mobile: Flags.boolean({
73
+ char: "m",
74
+ exclusive: ["device"],
75
+ description: "Same as --device mobile",
76
+ }),
67
77
  browse: Flags.boolean({
68
78
  default: false,
69
79
  description: "Open the live site in the onboarding Chrome, with its extensions, but without request interception or Speed Kit injection. Takes the domain from -d or from the customer config.",
@@ -99,6 +109,8 @@ export class OnboardingServiceBuildContext extends Context() {
99
109
  debuggingPort: parsedFlags.debuggingPort,
100
110
  headless: parsedFlags.headless,
101
111
  debugPort: parsedFlags.debugPort,
112
+ device: parsedFlags.device ??
113
+ (parsedFlags.mobile ? "mobile" : undefined),
102
114
  browserFetch: parsedFlags.browserFetch,
103
115
  browse: parsedFlags.browse,
104
116
  app: parsedFlags.app,
@@ -50,6 +50,13 @@ export declare class OnboardingServiceFactory {
50
50
  customerChromeFlags?: string[];
51
51
  }): BrowserContext;
52
52
  private getOnboardingService;
53
+ /**
54
+ * `--device` only changes what Speed Kit does if the config derives the device from the user
55
+ * agent. `RequestContext.getDevice` short-circuits on a pinned `customDevice` and returns nothing
56
+ * at all when `userAgentDetection` is off. In both cases no `bqvariation` is appended and the
57
+ * emulated device silently gets desktop assets. Say so up front.
58
+ */
59
+ private warnAboutDeviceDetection;
53
60
  private prepareMessagehandler;
54
61
  /**
55
62
  * The app token for the devtools extension, or `null` when nobody is logged
@@ -201,11 +201,15 @@ export class OnboardingServiceFactory {
201
201
  if (this.context.headless) {
202
202
  cli.writeWarning("Running in headless mode.");
203
203
  }
204
+ if (browserContext.emulation) {
205
+ const { device, userAgent, viewport } = browserContext.emulation;
206
+ cli.writeWarning(`Emulating ${device} (${viewport.width}x${viewport.height} @${viewport.deviceScaleFactor}x) with ${userAgent}`);
207
+ }
204
208
  return { browserContext, browserExtensions };
205
209
  }
206
210
  /** The launch for `domain`. It reads no mode of the build context, so browse mode cannot drift from onboarding. */
207
211
  buildBrowserContext({ domain, browserVersionString, customerChromeFlags, }) {
208
- return new BrowserContext(domain, browserVersionString, withOriginProxyFlag(customerChromeFlags), this.context.environment, undefined, this.context.debuggingPort, this.context.headless, this.context.debugPort);
212
+ return new BrowserContext(domain, browserVersionString, withOriginProxyFlag(customerChromeFlags), this.context.environment, undefined, this.context.debuggingPort, this.context.headless, this.context.debugPort, this.context.device);
209
213
  }
210
214
  async getOnboardingService() {
211
215
  const cli = this.context.environment.cli;
@@ -236,6 +240,9 @@ export class OnboardingServiceFactory {
236
240
  const speedKitInstallContext = new SpeedKitInstallContext(customerConfig, this.context.configName, files, bundler, skTemplate);
237
241
  await this.buildInstallResource(speedKitInstallContext, files, cli);
238
242
  const { browserContext, browserExtensions } = await this.prepareBrowser(domainToStart, customerConfig.chromeFlags);
243
+ if (this.context.device) {
244
+ await this.warnAboutDeviceDetection(files, customerConfig, domainToStart);
245
+ }
239
246
  const fileWatcher = new FileWatcher(cli, customerConfig, files, documentHandler, browserContext, cache);
240
247
  const athenaClient = (await this.getAthenaClient(customerConfig.app)) || null;
241
248
  const messageHandler = await this.prepareMessagehandler(athenaClient, files, customerConfig);
@@ -244,6 +251,32 @@ export class OnboardingServiceFactory {
244
251
  const extensionBridge = new ExtensionBridge(cli, browserExtensions.hasDevtoolsExtension);
245
252
  return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler, extensionBridge, speedKitServiceWorkerJs, browserFetch);
246
253
  }
254
+ /**
255
+ * `--device` only changes what Speed Kit does if the config derives the device from the user
256
+ * agent. `RequestContext.getDevice` short-circuits on a pinned `customDevice` and returns nothing
257
+ * at all when `userAgentDetection` is off. In both cases no `bqvariation` is appended and the
258
+ * emulated device silently gets desktop assets. Say so up front.
259
+ */
260
+ async warnAboutDeviceDetection(files, customerConfig, domain) {
261
+ const cli = this.context.environment.cli;
262
+ const speedKitConfig = files.getSpeedKitConfig();
263
+ if (!speedKitConfig) {
264
+ return;
265
+ }
266
+ const config = await safe(speedKitConfig.evaluate(customerConfig.app, new URL(domain).origin));
267
+ if (config.success !== true) {
268
+ cli.writeWarning(`Could not check the Speed Kit config for device detection: ${config.error}`);
269
+ return;
270
+ }
271
+ // `raw` for the pin: `SSRPlugin` wraps `detectDevice` in `effective` for every config.
272
+ const { raw, effective } = config.data;
273
+ if (!effective.userAgentDetection && this.context.device !== "desktop") {
274
+ cli.writeWarning(`userAgentDetection is off in the Speed Kit config — Speed Kit resolves the desktop variation regardless of --device ${this.context.device}.`);
275
+ }
276
+ if (raw.customDevice || raw.detectDevice) {
277
+ cli.writeWarning("The Speed Kit config pins the device via customDevice/detectDevice, which takes precedence over the emulated user agent.");
278
+ }
279
+ }
247
280
  async prepareMessagehandler(athenaClient, files, customerConfig) {
248
281
  const messageHandler = new DevtoolsExtensionApi();
249
282
  messageHandler.addMessage({
@@ -1,6 +1,7 @@
1
1
  import { expect } from "chai";
2
2
  import { describe, it } from "mocha";
3
3
  import { BrowserContext, HEADLESS_DEFAULT_ARGS_TO_DROP, } from "../onboarding-model.js";
4
+ import { DEVICE_VIEWPORTS, deviceEmulation, } from "../../browser-fetch/device-emulation.js";
4
5
  import { buildHeadedUserAgent } from "../browser/executable/headed-user-agent.js";
5
6
  // Providing chromeUserProfilePath keeps BrowserContext off the filesystem
6
7
  // (it skips the temp-profile branch in the constructor).
@@ -10,8 +11,8 @@ const environment = {
10
11
  chromeUserProfilePath: "/tmp/sk-test-profile",
11
12
  },
12
13
  };
13
- function newContext(headless, { chromeFlags = [], userAgent, browserVersionString = "Google Chrome for Testing 146.0.7680.165", } = {}) {
14
- return new BrowserContext("example.com", browserVersionString, chromeFlags, environment, userAgent, false, headless, undefined);
14
+ function newContext(headless, { chromeFlags = [], userAgent, browserVersionString = "Google Chrome for Testing 146.0.7680.165", device, } = {}) {
15
+ return new BrowserContext("example.com", browserVersionString, chromeFlags, environment, userAgent, false, headless, undefined, device);
15
16
  }
16
17
  function launchArgs(headless, overrides = {}) {
17
18
  return newContext(headless, overrides).getPuppeteerLaunchOptions()
@@ -98,6 +99,96 @@ describe("BrowserContext headless/headed parity", () => {
98
99
  expect(launchArgs(true).length).to.equal(first);
99
100
  });
100
101
  });
102
+ describe("BrowserContext device emulation", () => {
103
+ const VERSION = "Google Chrome for Testing 146.0.7680.165";
104
+ const argOf = (args, name) => args.find((arg) => arg.startsWith(`--${name}=`));
105
+ for (const device of ["mobile", "tablet", "desktop"]) {
106
+ // A Service Worker resolves the device from its own navigator.userAgent, which only a launch
107
+ // flag reaches, so headed mode carries the flag too.
108
+ it(`sets the ${device} user agent as a launch flag in headed mode`, () => {
109
+ expect(argOf(launchArgs(false, { device }), "user-agent")).to.equal(`--user-agent=${deviceEmulation(VERSION, device, "win32").userAgent}`);
110
+ });
111
+ it(`sizes the headless window and screen to the ${device}`, () => {
112
+ const { width, height } = newContext(true, { device }).emulation.viewport;
113
+ expect(launchArgs(true, { device })).to.include.members([
114
+ `--window-size=${width},${height}`,
115
+ `--screen-info={${width}x${height}}`,
116
+ ]);
117
+ });
118
+ }
119
+ it("asks for a coarse pointer, no hover and touch events on a touch device", () => {
120
+ for (const device of ["mobile", "tablet"]) {
121
+ const args = launchArgs(true, { device });
122
+ expect(argOf(args, "blink-settings")).to.equal("--blink-settings=primaryHoverType=1,availableHoverTypes=1,primaryPointerType=2,availablePointerTypes=2");
123
+ expect(args).to.include("--touch-events=enabled");
124
+ }
125
+ });
126
+ it("asks for a fine pointer and no touch events on the desktop", () => {
127
+ const args = launchArgs(false, { device: "desktop" });
128
+ expect(argOf(args, "blink-settings")).to.equal("--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4");
129
+ expect(args).to.include("--touch-events=disabled");
130
+ });
131
+ it("gives the desktop an explicit viewport", () => {
132
+ expect(newContext(false, { device: "desktop" }).emulation.viewport).to.equal(DEVICE_VIEWPORTS.desktop);
133
+ });
134
+ it("presents the desktop as Chrome on Windows, whatever the host", () => {
135
+ const { userAgent, metadata } = newContext(false, {
136
+ device: "desktop",
137
+ }).emulation;
138
+ expect(userAgent).to.equal("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36");
139
+ expect(metadata).to.include({ platform: "Windows", mobile: false });
140
+ });
141
+ it("wins over the headless user agent", () => {
142
+ expect(argOf(launchArgs(true, { device: "tablet" }), "user-agent")).to.include("Android");
143
+ });
144
+ it("still prefers an explicitly provided user agent", () => {
145
+ expect(argOf(launchArgs(false, { device: "mobile", userAgent: "custom" }), "user-agent")).to.equal("--user-agent=custom");
146
+ });
147
+ it("leaves room for docked devtools in headed mode", () => {
148
+ const [width] = argOf(launchArgs(false, { device: "mobile" }), "window-size")
149
+ .split("=")[1]
150
+ .split(",")
151
+ .map(Number);
152
+ expect(width).to.be.greaterThan(newContext(false, { device: "mobile" }).emulation.viewport.width);
153
+ });
154
+ // A phone has overlay scrollbars, so Puppeteer's headless default is right there.
155
+ it("keeps --hide-scrollbars only for a headless touch device", () => {
156
+ const ignored = (device) => newContext(true, { device }).getPuppeteerLaunchOptions()
157
+ .ignoreDefaultArgs;
158
+ expect(ignored("mobile")).to.not.include("--hide-scrollbars");
159
+ expect(ignored("desktop")).to.include("--hide-scrollbars");
160
+ });
161
+ it("lets customer chromeFlags win over the device defaults", () => {
162
+ const args = launchArgs(false, {
163
+ device: "mobile",
164
+ chromeFlags: ["--user-agent=pinned-agent"],
165
+ });
166
+ expect(args.lastIndexOf("--user-agent=pinned-agent")).to.be.greaterThan(args.findIndex((arg) => arg.startsWith("--user-agent=Mozilla/5.0")));
167
+ });
168
+ it("emulates nothing without a device", () => {
169
+ const context = newContext(false);
170
+ expect(context.emulation).to.equal(undefined);
171
+ expect(context.getDeviceMetricsOverride()).to.equal(null);
172
+ expect(context.getTouchEmulation()).to.equal(null);
173
+ });
174
+ // screenWidth/screenHeight matter beyond the viewport: the snippet persists window.screen.width and
175
+ // devicePixelRatio into the SW cache, where they drive Asset API image downscaling.
176
+ it("overrides the screen and orientation along with the viewport", () => {
177
+ expect(newContext(false, { device: "tablet" }).getDeviceMetricsOverride()).to.deep.equal({
178
+ width: 1280,
179
+ height: 800,
180
+ screenWidth: 1280,
181
+ screenHeight: 800,
182
+ deviceScaleFactor: 1.5,
183
+ mobile: true,
184
+ screenOrientation: { type: "landscapePrimary", angle: 90 },
185
+ });
186
+ });
187
+ it("enables touch for a touch device and disables it for the desktop", () => {
188
+ expect(newContext(false, { device: "mobile" }).getTouchEmulation()).to.deep.equal({ enabled: true, maxTouchPoints: 5 });
189
+ expect(newContext(false, { device: "desktop" }).getTouchEmulation()).to.deep.equal({ enabled: false });
190
+ });
191
+ });
101
192
  describe("BrowserContext system chromeFlags", () => {
102
193
  function systemContext(chromeFlags, systemFlags, debuggingPort = false) {
103
194
  return new BrowserContext("example.com", "Chrome/120", chromeFlags, {
@@ -1,6 +1,6 @@
1
1
  import { expect } from "chai";
2
2
  import { describe, it } from "mocha";
3
- import { withInjectDefault } from "../onboarding-service-build-context.js";
3
+ import { OnboardingServiceBuildContext, withInjectDefault, } from "../onboarding-service-build-context.js";
4
4
  describe("withInjectDefault", () => {
5
5
  it("gives --inject at the end the latest installation", () => {
6
6
  expect(withInjectDefault(["customers/shop", "--inject"])).to.deep.equal([
@@ -20,3 +20,18 @@ describe("withInjectDefault", () => {
20
20
  expect(withInjectDefault(argv)).to.deep.equal(argv);
21
21
  });
22
22
  });
23
+ describe("OnboardingServiceBuildContext.create device", () => {
24
+ const environment = { oclif: { root: "/cli" } };
25
+ function deviceOf(flags) {
26
+ return OnboardingServiceBuildContext.create({ customerPath: undefined }, flags, environment).device;
27
+ }
28
+ it("takes the device of --device", () => {
29
+ expect(deviceOf({ device: "tablet" })).to.equal("tablet");
30
+ });
31
+ it("reads --mobile as --device mobile", () => {
32
+ expect(deviceOf({ mobile: true })).to.equal("mobile");
33
+ });
34
+ it("emulates no device without either flag", () => {
35
+ expect(deviceOf({ mobile: false })).to.equal(undefined);
36
+ });
37
+ });
@@ -2,3 +2,4 @@ export * from "./revalidate-service-build-context.js";
2
2
  export * from "./revalidate-model.js";
3
3
  export * from "./revalidate-service.js";
4
4
  export * from "./revalidate-factory.js";
5
+ export * from "./revalidate-jobs-build-context.js";
@@ -2,3 +2,4 @@ export * from "./revalidate-service-build-context.js";
2
2
  export * from "./revalidate-model.js";
3
3
  export * from "./revalidate-service.js";
4
4
  export * from "./revalidate-factory.js";
5
+ export * from "./revalidate-jobs-build-context.js";
@@ -2,6 +2,6 @@ import { RevalidateServiceBuildContext } from "./revalidate-service-build-contex
2
2
  import { RevalidateService } from "./revalidate-service.js";
3
3
  export declare class RevalidateFactory {
4
4
  private readonly context;
5
- constructor(context: RevalidateServiceBuildContext);
5
+ constructor(context: Pick<RevalidateServiceBuildContext, "app" | "environment">);
6
6
  getService(): RevalidateService;
7
7
  }
@@ -0,0 +1,56 @@
1
+ import { Interfaces } from "@oclif/core";
2
+ import { CliEnvironment, CommandContextValues } from "../cli/index.js";
3
+ export interface RevalidateAppBuildContextValues extends CommandContextValues {
4
+ readonly app: string;
5
+ }
6
+ declare const appArgs: {
7
+ app: Interfaces.Arg<string, Record<string, unknown>>;
8
+ };
9
+ declare const RevalidateAppBuildContext_base: new (values: RevalidateAppBuildContextValues) => Readonly<RevalidateAppBuildContextValues>;
10
+ /** `sk revalidate unblock` and `sk revalidate wait`: the app alone. */
11
+ export declare class RevalidateAppBuildContext extends RevalidateAppBuildContext_base {
12
+ static readonly args: {
13
+ app: Interfaces.Arg<string, Record<string, unknown>>;
14
+ };
15
+ static readonly flags: {};
16
+ static create(parsedArgs: Interfaces.InferredArgs<typeof appArgs>, _parsedFlags: object, environment: CliEnvironment): RevalidateAppBuildContext;
17
+ }
18
+ declare const jobsArgs: {
19
+ app: Interfaces.Arg<string, Record<string, unknown>>;
20
+ revId: Interfaces.Arg<string, Record<string, unknown>>;
21
+ };
22
+ declare const jobsFlags: {
23
+ state: Interfaces.OptionFlag<string[], Interfaces.CustomOptions>;
24
+ };
25
+ declare const RevalidateJobsBuildContext_base: new (values: RevalidateAppBuildContextValues) => Readonly<RevalidateAppBuildContextValues>;
26
+ /** `sk revalidate jobs`: the app, one job to show, and the states to list. */
27
+ export declare class RevalidateJobsBuildContext extends RevalidateJobsBuildContext_base {
28
+ static readonly args: {
29
+ app: Interfaces.Arg<string, Record<string, unknown>>;
30
+ revId: Interfaces.Arg<string, Record<string, unknown>>;
31
+ };
32
+ static readonly flags: {
33
+ state: Interfaces.OptionFlag<string[], Interfaces.CustomOptions>;
34
+ };
35
+ static create(parsedArgs: Interfaces.InferredArgs<typeof jobsArgs>, _parsedFlags: Interfaces.InferredFlags<typeof jobsFlags>, environment: CliEnvironment): RevalidateJobsBuildContext;
36
+ }
37
+ declare const startArgs: {
38
+ app: Interfaces.Arg<string, Record<string, unknown>>;
39
+ revId: Interfaces.Arg<string, Record<string, unknown>>;
40
+ };
41
+ declare const startFlags: {
42
+ wait: Interfaces.BooleanFlag<boolean>;
43
+ };
44
+ declare const RevalidateStartBuildContext_base: new (values: RevalidateAppBuildContextValues) => Readonly<RevalidateAppBuildContextValues>;
45
+ /** `sk revalidate start`: the app and the scheduled job to start. */
46
+ export declare class RevalidateStartBuildContext extends RevalidateStartBuildContext_base {
47
+ static readonly args: {
48
+ app: Interfaces.Arg<string, Record<string, unknown>>;
49
+ revId: Interfaces.Arg<string, Record<string, unknown>>;
50
+ };
51
+ static readonly flags: {
52
+ wait: Interfaces.BooleanFlag<boolean>;
53
+ };
54
+ static create(parsedArgs: Interfaces.InferredArgs<typeof startArgs>, _parsedFlags: Interfaces.InferredFlags<typeof startFlags>, environment: CliEnvironment): RevalidateStartBuildContext;
55
+ }
56
+ export {};