@speedkit/cli 4.51.0-run-control.1 → 4.51.0-run-control.2

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 (93) hide show
  1. package/README.md +81 -29
  2. package/dist/build-info.json +3 -3
  3. package/dist/commands/diff.d.ts +1 -0
  4. package/dist/commands/login.d.ts +3 -0
  5. package/dist/commands/login.js +14 -3
  6. package/dist/commands/onboarding/browser/emulate.d.ts +12 -0
  7. package/dist/commands/onboarding/browser/emulate.js +3 -0
  8. package/dist/commands/onboarding/browser/navigate.d.ts +8 -0
  9. package/dist/commands/onboarding/browser/navigate.js +2 -1
  10. package/dist/commands/onboarding/cache/prewarm.js +1 -1
  11. package/dist/commands/onboarding/debug/arm.d.ts +6 -0
  12. package/dist/commands/onboarding/debug/arm.js +2 -1
  13. package/dist/commands/onboarding/files/rebuild.d.ts +6 -6
  14. package/dist/commands/onboarding/logs.js +3 -2
  15. package/dist/commands/onboarding/status.js +2 -2
  16. package/dist/commands/onboarding/stop.d.ts +13 -0
  17. package/dist/commands/onboarding/stop.js +17 -0
  18. package/dist/commands/onboarding.d.ts +1 -1
  19. package/dist/commands/onboarding.js +1 -1
  20. package/dist/services/diff/diff-service-build-context.d.ts +4 -0
  21. package/dist/services/diff/diff-service-build-context.js +5 -0
  22. package/dist/services/diff/diff-service-factory.js +17 -5
  23. package/dist/services/diff/run-runtime-config.d.ts +33 -0
  24. package/dist/services/diff/run-runtime-config.js +74 -0
  25. package/dist/services/diff/spec/run-runtime-config.spec.d.ts +1 -0
  26. package/dist/services/diff/spec/run-runtime-config.spec.js +87 -0
  27. package/dist/services/onboarding/browse/browse-service.d.ts +13 -1
  28. package/dist/services/onboarding/browse/browse-service.js +40 -7
  29. package/dist/services/onboarding/browser/answer-dialogs.d.ts +12 -0
  30. package/dist/services/onboarding/browser/answer-dialogs.js +25 -0
  31. package/dist/services/onboarding/browser/emulate-device.d.ts +12 -1
  32. package/dist/services/onboarding/browser/emulate-device.js +33 -6
  33. package/dist/services/onboarding/browser/launch-browser.d.ts +2 -1
  34. package/dist/services/onboarding/browser/launch-browser.js +3 -1
  35. package/dist/services/onboarding/control/browser-session.d.ts +26 -12
  36. package/dist/services/onboarding/control/browser-session.js +118 -91
  37. package/dist/services/onboarding/control/control-protocol.d.ts +39 -1
  38. package/dist/services/onboarding/control/control-protocol.js +0 -11
  39. package/dist/services/onboarding/control/control-server.d.ts +8 -0
  40. package/dist/services/onboarding/control/control-server.js +22 -2
  41. package/dist/services/onboarding/control/debug-session.d.ts +30 -1
  42. package/dist/services/onboarding/control/debug-session.js +106 -10
  43. package/dist/services/onboarding/control/navigate-wait.d.ts +33 -0
  44. package/dist/services/onboarding/control/navigate-wait.js +56 -0
  45. package/dist/services/onboarding/control/service-worker-tracker.js +1 -0
  46. package/dist/services/onboarding/control/watch.js +9 -1
  47. package/dist/services/onboarding/fetch-event-handler.js +9 -0
  48. package/dist/services/onboarding/inject/inject-service.js +1 -1
  49. package/dist/services/onboarding/onboarding-model.js +2 -1
  50. package/dist/services/onboarding/onboarding-service-build-context.js +1 -1
  51. package/dist/services/onboarding/onboarding-service-factory.js +20 -7
  52. package/dist/services/onboarding/onboarding-service.js +1 -1
  53. package/dist/services/onboarding/spec/browser/answer-dialogs.spec.d.ts +1 -0
  54. package/dist/services/onboarding/spec/browser/answer-dialogs.spec.js +66 -0
  55. package/dist/services/onboarding/spec/control/browser-session.spec.js +127 -2
  56. package/dist/services/onboarding/spec/control/control-server.spec.js +33 -0
  57. package/dist/services/onboarding/spec/control/debug-session.spec.js +58 -0
  58. package/dist/services/onboarding/spec/control/navigate-wait.spec.d.ts +1 -0
  59. package/dist/services/onboarding/spec/control/navigate-wait.spec.js +47 -0
  60. package/dist/services/onboarding/spec/control/watch.spec.js +15 -0
  61. package/dist/services/onboarding/spec/fetch-event-handler.spec.js +17 -0
  62. package/dist/services/onboarding/spec/onboarding-model.spec.js +2 -3
  63. package/dist/services/onboarding/spec/onboarding-service-factory.spec.js +24 -1
  64. package/dist/services/onboarding/spec/virtual-orestes-app/virtual-orestes-app.spec.d.ts +1 -0
  65. package/dist/services/onboarding/spec/virtual-orestes-app/virtual-orestes-app.spec.js +65 -0
  66. package/dist/services/onboarding/virtual-orestes-app/index.d.ts +4 -0
  67. package/dist/services/onboarding/virtual-orestes-app/index.js +31 -0
  68. package/dist/services/origin-request/runtime-config-source.d.ts +6 -0
  69. package/dist/services/origin-request/runtime-config-source.js +6 -0
  70. package/dist/services/run-control/browser/run-browser-contexts.d.ts +16 -0
  71. package/dist/services/run-control/browser/run-browser-contexts.js +14 -1
  72. package/dist/services/run-control/browser/run-browser-service.d.ts +5 -1
  73. package/dist/services/run-control/browser/run-browser-service.js +16 -9
  74. package/dist/services/run-control/debug/run-debug-contexts.d.ts +5 -0
  75. package/dist/services/run-control/debug/run-debug-contexts.js +3 -0
  76. package/dist/services/run-control/debug/run-debug-service.d.ts +1 -0
  77. package/dist/services/run-control/debug/run-debug-service.js +3 -0
  78. package/dist/services/run-control/files/run-files-contexts.d.ts +5 -5
  79. package/dist/services/run-control/inject/run-inject-contexts.js +7 -1
  80. package/dist/services/run-control/inject/run-inject-service.d.ts +2 -2
  81. package/dist/services/run-control/inject/run-inject-service.js +32 -8
  82. package/dist/services/run-control/probe/run-probe-service.js +1 -0
  83. package/dist/services/run-control/session/run-session-service.d.ts +8 -1
  84. package/dist/services/run-control/session/run-session-service.js +58 -2
  85. package/dist/services/run-control/spec/cache/run-cache-service.spec.js +1 -1
  86. package/dist/services/run-control/spec/inject/run-inject-service.spec.js +27 -0
  87. package/dist/services/run-control/spec/session/run-session-service.spec.js +49 -0
  88. package/dist/services/run-log/request-log.d.ts +3 -1
  89. package/dist/services/run-registry/run-registry.d.ts +7 -2
  90. package/dist/services/run-registry/run-registry.js +26 -5
  91. package/dist/services/run-registry/spec/run-registry.spec.js +17 -0
  92. package/oclif.manifest.json +281 -181
  93. package/package.json +1 -1
@@ -152,6 +152,7 @@ export declare const BrowserNavigateBuildContext: {
152
152
  new (values: import("../run-control-context.js").RunControlBuildContextValues<{
153
153
  url: string;
154
154
  } & {
155
+ wait: "load" | "bp1" | "bp2" | "bp3" | "bp4";
155
156
  tab: string;
156
157
  json: boolean | undefined;
157
158
  }>): {
@@ -162,6 +163,7 @@ export declare const BrowserNavigateBuildContext: {
162
163
  readonly input: {
163
164
  url: string;
164
165
  } & {
166
+ wait: "load" | "bp1" | "bp2" | "bp3" | "bp4";
165
167
  tab: string;
166
168
  json: boolean | undefined;
167
169
  };
@@ -174,6 +176,8 @@ export declare const BrowserNavigateBuildContext: {
174
176
  run: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
175
177
  json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
176
178
  timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
179
+ } & {
180
+ wait: import("@oclif/core/interfaces").OptionFlag<"load" | "bp1" | "bp2" | "bp3" | "bp4", import("@oclif/core/interfaces").CustomOptions>;
177
181
  } & {
178
182
  tab: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
179
183
  };
@@ -183,6 +187,7 @@ export declare const BrowserNavigateBuildContext: {
183
187
  run: string;
184
188
  json: boolean | undefined;
185
189
  timeout: number;
190
+ wait: "load" | "bp1" | "bp2" | "bp3" | "bp4";
186
191
  tab: string;
187
192
  }, environment: import("../../cli/cli-environment.js").CliEnvironment): {
188
193
  readonly run?: string;
@@ -192,6 +197,7 @@ export declare const BrowserNavigateBuildContext: {
192
197
  readonly input: {
193
198
  url: string;
194
199
  } & {
200
+ wait: "load" | "bp1" | "bp2" | "bp3" | "bp4";
195
201
  tab: string;
196
202
  json: boolean | undefined;
197
203
  };
@@ -253,6 +259,8 @@ export declare const BrowserEmulateBuildContext: {
253
259
  width: number;
254
260
  height: number;
255
261
  dpr: number;
262
+ "user-agent": string;
263
+ touch: any;
256
264
  reload: any;
257
265
  tab: string;
258
266
  json: boolean | undefined;
@@ -267,6 +275,8 @@ export declare const BrowserEmulateBuildContext: {
267
275
  width: number;
268
276
  height: number;
269
277
  dpr: number;
278
+ "user-agent": string;
279
+ touch: any;
270
280
  reload: any;
271
281
  tab: string;
272
282
  json: boolean | undefined;
@@ -284,6 +294,8 @@ export declare const BrowserEmulateBuildContext: {
284
294
  width: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
285
295
  height: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
286
296
  dpr: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
297
+ "user-agent": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
298
+ touch: import("@oclif/core/interfaces").BooleanFlag<any>;
287
299
  reload: import("@oclif/core/interfaces").BooleanFlag<any>;
288
300
  } & {
289
301
  tab: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
@@ -297,6 +309,8 @@ export declare const BrowserEmulateBuildContext: {
297
309
  width: number;
298
310
  height: number;
299
311
  dpr: number;
312
+ "user-agent": string;
313
+ touch: any;
300
314
  reload: any;
301
315
  tab: string;
302
316
  }, environment: import("../../cli/cli-environment.js").CliEnvironment): {
@@ -310,6 +324,8 @@ export declare const BrowserEmulateBuildContext: {
310
324
  width: number;
311
325
  height: number;
312
326
  dpr: number;
327
+ "user-agent": string;
328
+ touch: any;
313
329
  reload: any;
314
330
  tab: string;
315
331
  json: boolean | undefined;
@@ -15,7 +15,13 @@ export const BrowserNavigateBuildContext = pageControlContext({
15
15
  required: true,
16
16
  description: "Absolute, or relative to the origin the page is on",
17
17
  }),
18
- }, {});
18
+ }, {
19
+ wait: Flags.option({
20
+ options: ["load", "bp1", "bp2", "bp3", "bp4"],
21
+ default: "load",
22
+ description: "Where to return: the load event, or the Speed Kit lifecycle mark of a breakpoint (bp1 before the merge, bp2 after it, bp3 the SSR comparison, bp4 the SSR container removed). It waits for the mark and never pauses; a mark that cannot come returns at once with the reason. --timeout bounds it (default 30000)",
23
+ })(),
24
+ });
19
25
  export const BrowserPanelBuildContext = pageControlContext({}, {});
20
26
  export const BrowserEmulateBuildContext = pageControlContext({
21
27
  device: Args.string({
@@ -30,6 +36,13 @@ export const BrowserEmulateBuildContext = pageControlContext({
30
36
  dpr: Flags.integer({
31
37
  description: "Override the preset's device pixel ratio",
32
38
  }),
39
+ "user-agent": Flags.string({
40
+ description: "Override the preset's user agent, on the page and the service worker; sends no client hints, as Safari does",
41
+ }),
42
+ touch: Flags.boolean({
43
+ allowNo: true,
44
+ description: "Override the preset's touch: --touch or --no-touch",
45
+ }),
33
46
  reload: Flags.boolean({
34
47
  default: true,
35
48
  allowNo: true,
@@ -1,10 +1,13 @@
1
1
  import { EmulatedDevice, BrowserResetScope } from "../../onboarding/control/control-protocol.js";
2
+ import { NavigateWaitPoint } from "../../onboarding/control/navigate-wait.js";
2
3
  import { RunControlServiceDeps } from "../run-control-model.js";
3
4
  export interface EmulateInput {
4
5
  device: EmulatedDevice | "off";
5
6
  width?: number;
6
7
  height?: number;
7
8
  dpr?: number;
9
+ userAgent?: string;
10
+ touch?: boolean;
8
11
  reload?: boolean;
9
12
  }
10
13
  export interface ScreenshotInput {
@@ -30,7 +33,8 @@ export declare class RunBrowserService {
30
33
  /** Put the local build back after the deployed one took over. */
31
34
  reinstallServiceWorker(): Promise<void>;
32
35
  /** Absolute, or relative to the origin the page is on. */
33
- navigate(url: string): Promise<void>;
36
+ /** `timeoutMs` is `--timeout`: it bounds the navigation and the wait. */
37
+ navigate(url: string, wait?: NavigateWaitPoint, timeoutMs?: number): Promise<void>;
34
38
  /**
35
39
  * Present the page as a device until switched off: metrics, touch and user
36
40
  * agent, on the page and on every service worker — where Speed Kit decides
@@ -7,6 +7,8 @@ import { ControlError } from "../control-client.js";
7
7
  * reported a failure for a navigation that had already happened.
8
8
  */
9
9
  const LOAD_BUDGET_MS = 40_000;
10
+ /** How long `navigate --wait <bpN>` waits without `--timeout`. */
11
+ const WAIT_DEFAULT_MS = 30_000;
10
12
  /**
11
13
  * The Chrome a run is driving.
12
14
  *
@@ -49,8 +51,15 @@ export class RunBrowserService {
49
51
  await this.act({ op: "browser.reinstall-sw" }, LOAD_BUDGET_MS);
50
52
  }
51
53
  /** Absolute, or relative to the origin the page is on. */
52
- async navigate(url) {
53
- await this.act({ op: "browser.navigate", url }, LOAD_BUDGET_MS);
54
+ /** `timeoutMs` is `--timeout`: it bounds the navigation and the wait. */
55
+ async navigate(url, wait = "load", timeoutMs) {
56
+ // The run answers a second before the client gives up, so a timeout comes back as an answer.
57
+ const waitMs = timeoutMs !== undefined
58
+ ? Math.max(1000, timeoutMs - 1000)
59
+ : wait === "load"
60
+ ? undefined
61
+ : WAIT_DEFAULT_MS;
62
+ await this.act({ op: "browser.navigate", url, wait, waitMs }, Math.max(LOAD_BUDGET_MS, (waitMs ?? 0) + 5000));
54
63
  }
55
64
  /**
56
65
  * Present the page as a device until switched off: metrics, touch and user
@@ -64,19 +73,17 @@ export class RunBrowserService {
64
73
  width: input.width,
65
74
  height: input.height,
66
75
  dpr: input.dpr,
76
+ userAgent: input.userAgent,
77
+ touch: input.touch,
67
78
  reload: input.reload,
68
79
  }, LOAD_BUDGET_MS);
80
+ // Only the worker in charge of the page: it decides the device.
69
81
  const workers = data.serviceWorkers;
70
- // The worker in charge is the one that decides; when none is known to be,
71
- // every worker on the app's origins counts.
72
- const deciding = workers.some((worker) => worker.active)
73
- ? workers.filter((worker) => worker.active)
74
- : workers;
75
- const missed = deciding.filter((worker) => !worker.emulated);
82
+ const missed = workers.filter((worker) => !worker.emulated);
76
83
  // Said in the summary, because it decides whether the variation can be
77
84
  // trusted: a worker still on the desktop user agent serves desktop.
78
85
  const summary = data.emulation && workers.length === 0
79
- ? `${data.did}. No service worker was running to override; \`browser state\` after the next load shows whether one took over as this device.`
86
+ ? `${data.did}. No service worker is in charge of the page yet; \`browser state\` after the next load shows whether one took over as this device.`
80
87
  : data.emulation && missed.length > 0
81
88
  ? `${data.did}. ${missed.length} service worker${missed.length === 1 ? " still reports" : "s still report"} another user agent, so Speed Kit may serve the old device.`
82
89
  : data.did;
@@ -4,6 +4,7 @@ export declare const DebugArmBuildContext: {
4
4
  } & {
5
5
  bp: number[];
6
6
  then: "none" | "reload" | "next-nav";
7
+ compared: any;
7
8
  tab: string;
8
9
  json: boolean | undefined;
9
10
  }>): {
@@ -16,6 +17,7 @@ export declare const DebugArmBuildContext: {
16
17
  } & {
17
18
  bp: number[];
18
19
  then: "none" | "reload" | "next-nav";
20
+ compared: any;
19
21
  tab: string;
20
22
  json: boolean | undefined;
21
23
  };
@@ -29,6 +31,7 @@ export declare const DebugArmBuildContext: {
29
31
  } & {
30
32
  bp: import("@oclif/core/interfaces").OptionFlag<number[], import("@oclif/core/interfaces").CustomOptions>;
31
33
  then: import("@oclif/core/interfaces").OptionFlag<"none" | "reload" | "next-nav", import("@oclif/core/interfaces").CustomOptions>;
34
+ compared: import("@oclif/core/interfaces").BooleanFlag<any>;
32
35
  } & {
33
36
  tab: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
34
37
  };
@@ -40,6 +43,7 @@ export declare const DebugArmBuildContext: {
40
43
  timeout: number;
41
44
  bp: number[];
42
45
  then: "none" | "reload" | "next-nav";
46
+ compared: any;
43
47
  tab: string;
44
48
  }, environment: import("../../cli/cli-environment.js").CliEnvironment): {
45
49
  readonly run?: string;
@@ -51,6 +55,7 @@ export declare const DebugArmBuildContext: {
51
55
  } & {
52
56
  bp: number[];
53
57
  then: "none" | "reload" | "next-nav";
58
+ compared: any;
54
59
  tab: string;
55
60
  json: boolean | undefined;
56
61
  };
@@ -12,6 +12,9 @@ export const DebugArmBuildContext = pageControlContext({}, {
12
12
  default: "reload",
13
13
  description: "reload: load the page again, as a navigation (Speed Kit does not serve a reload from cache). next-nav: catch the next navigation. none: only arm",
14
14
  })(),
15
+ compared: Flags.boolean({
16
+ description: "Pause BP1 and BP3 where their change-detection pass compares, and expose both sides as window.__skCD",
17
+ }),
15
18
  });
16
19
  export const DebugStatusBuildContext = pageControlContext({}, {});
17
20
  export const DebugAwaitBuildContext = pageControlContext({}, {
@@ -3,6 +3,7 @@ import { RunControlServiceDeps } from "../run-control-model.js";
3
3
  export interface DebugArmInput {
4
4
  bps?: number[];
5
5
  then?: DebugThen;
6
+ compared?: boolean;
6
7
  }
7
8
  /**
8
9
  * Breakpoints in Speed Kit's own page lifecycle: BP1 before the merge and any
@@ -44,6 +44,9 @@ export class RunDebugService {
44
44
  }
45
45
  this.cli.comment(`at ${pause.scriptUrl ?? pause.url ?? "?"}${pause.location ? `:${pause.location.lineNumber}` : ""}`);
46
46
  this.cli.comment(`html ${pause.state.htmlClass ?? "-"} group ${pause.state.skGroup ?? "-"}`);
47
+ if (pause.compared) {
48
+ this.cli.comment(`__skCD ${JSON.stringify(pause.compared)}`);
49
+ }
47
50
  for (const mark of pause.state.marks) {
48
51
  this.cli.write(` ${String(mark.t).padStart(7)} ${mark.name}`);
49
52
  }
@@ -102,7 +102,7 @@ export declare const FilesRebuildBuildContext: {
102
102
  new (values: import("../run-control-context.js").RunControlBuildContextValues<{
103
103
  [x: string]: any;
104
104
  } & {
105
- target: "documentHandler" | "install" | "all";
105
+ target: "documentHandler" | "all" | "install";
106
106
  json: boolean | undefined;
107
107
  }>): {
108
108
  readonly run?: string;
@@ -112,7 +112,7 @@ export declare const FilesRebuildBuildContext: {
112
112
  readonly input: {
113
113
  [x: string]: any;
114
114
  } & {
115
- target: "documentHandler" | "install" | "all";
115
+ target: "documentHandler" | "all" | "install";
116
116
  json: boolean | undefined;
117
117
  };
118
118
  readonly environment: import("../../cli/cli-environment.js").CliEnvironment;
@@ -123,7 +123,7 @@ export declare const FilesRebuildBuildContext: {
123
123
  json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
124
124
  timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
125
125
  } & {
126
- target: import("@oclif/core/interfaces").OptionFlag<"documentHandler" | "install" | "all", import("@oclif/core/interfaces").CustomOptions>;
126
+ target: import("@oclif/core/interfaces").OptionFlag<"documentHandler" | "all" | "install", import("@oclif/core/interfaces").CustomOptions>;
127
127
  };
128
128
  create(parsedArgs: {
129
129
  [x: string]: any;
@@ -131,7 +131,7 @@ export declare const FilesRebuildBuildContext: {
131
131
  run: string;
132
132
  json: boolean | undefined;
133
133
  timeout: number;
134
- target: "documentHandler" | "install" | "all";
134
+ target: "documentHandler" | "all" | "install";
135
135
  }, environment: import("../../cli/cli-environment.js").CliEnvironment): {
136
136
  readonly run?: string;
137
137
  readonly json: boolean;
@@ -140,7 +140,7 @@ export declare const FilesRebuildBuildContext: {
140
140
  readonly input: {
141
141
  [x: string]: any;
142
142
  } & {
143
- target: "documentHandler" | "install" | "all";
143
+ target: "documentHandler" | "all" | "install";
144
144
  json: boolean | undefined;
145
145
  };
146
146
  readonly environment: import("../../cli/cli-environment.js").CliEnvironment;
@@ -23,7 +23,13 @@ export const InjectAddBuildContext = pageControlContext({}, {
23
23
  }),
24
24
  });
25
25
  export const InjectListBuildContext = pageControlContext({}, {});
26
- export const InjectReadBuildContext = pageControlContext({ preload }, {
26
+ export const InjectReadBuildContext = pageControlContext({
27
+ // Optional, so a read without one can name the ids there are.
28
+ preload: Args.string({
29
+ name: "preload",
30
+ description: "The preload id, e.g. p1. Without one, the answer names them",
31
+ }),
32
+ }, {
27
33
  limit: Flags.integer({
28
34
  description: "How many records, newest last. Default 100",
29
35
  }),
@@ -24,8 +24,8 @@ export declare class RunInjectService {
24
24
  recipes(): Promise<void>;
25
25
  add(input: InjectAddInput): Promise<void>;
26
26
  list(): Promise<void>;
27
- /** Drain a preload's buffer, newest last. */
28
- read(preload: string, limit?: number): Promise<void>;
27
+ /** Drain a preload's buffer, newest last. Without an id, names the ids there are. */
28
+ read(preload: string | undefined, limit?: number): Promise<void>;
29
29
  remove(preload: string): Promise<void>;
30
30
  clear(): Promise<void>;
31
31
  }
@@ -52,8 +52,22 @@ export class RunInjectService {
52
52
  }
53
53
  });
54
54
  }
55
- /** Drain a preload's buffer, newest last. */
55
+ /** Drain a preload's buffer, newest last. Without an id, names the ids there are. */
56
56
  async read(preload, limit) {
57
+ if (!preload) {
58
+ const { preloads } = await this.run.request({
59
+ op: "inject.list",
60
+ });
61
+ const ids = preloads.map((entry) => entry.id);
62
+ throw new ControlError("PRELOAD_REQUIRED", ids.length > 0
63
+ ? `Name the preload to read: ${ids.join(", ")}.`
64
+ : "Nothing is injected, so there is nothing to read.", {
65
+ preloads: ids,
66
+ next: ids.length > 0
67
+ ? `\`sk onboarding inject read ${ids[0]}\``
68
+ : "`sk onboarding inject add` injects a script.",
69
+ });
70
+ }
57
71
  const data = await this.run.request({
58
72
  op: "inject.read",
59
73
  preload,
@@ -153,18 +167,21 @@ function summariseRead(data) {
153
167
  ? `${data.dropped} of the oldest dropped — the buffer keeps the newest, so the earliest loads are incomplete`
154
168
  : null,
155
169
  data.error ? `it threw while installing: ${data.error}` : null,
156
- ...unpainted(data),
170
+ ...vitalsNotes(data),
157
171
  ].filter(Boolean);
158
172
  return notes.length > 0 ? `${head}. ${notes.join(". ")}.` : head;
159
173
  }
160
174
  /**
161
- * web-vitals loads that painted nothing.
175
+ * web-vitals loads that painted nothing, and loads that painted without a shift.
162
176
  *
163
177
  * A window the compositor does not draw — a hidden workspace, a minimised
164
178
  * window — produces no frames, so there is no FCP or LCP to record. Reported as
165
179
  * that, because otherwise "no LCP" reads as a measurement.
180
+ *
181
+ * The browser reports no entry for a load without a layout shift, so a CLS of
182
+ * 0 is a missing record. Said, because otherwise it reads as CLS not measured.
166
183
  */
167
- function unpainted(data) {
184
+ function vitalsNotes(data) {
168
185
  if (data.origin !== "web-vitals") {
169
186
  return [];
170
187
  }
@@ -176,16 +193,23 @@ function unpainted(data) {
176
193
  load.page = value;
177
194
  if (value?.metric === "fcp" || value?.metric === "lcp")
178
195
  load.painted = true;
196
+ if (value?.metric === "cls")
197
+ load.shifted = true;
179
198
  loads.set(record.load ?? "", load);
180
199
  }
181
- return [...loads.entries()]
182
- .filter(([, load]) => !load.painted)
183
- .map(([id, load]) => {
200
+ return [...loads.entries()].flatMap(([id, load]) => {
201
+ if (load.painted) {
202
+ return load.shifted
203
+ ? []
204
+ : [`load ${id || "?"} had no layout shift: CLS 0 so far`];
205
+ }
184
206
  const hidden = load.page &&
185
207
  (load.page.visibility !== "visible" || load.page.focused === false)
186
208
  ? ` — the page was ${load.page.visibility}${load.page.focused === false ? " and unfocused" : ""}, so Chrome likely produced no frames`
187
209
  : "";
188
- return `load ${id || "?"} painted nothing yet${hidden}; a missing LCP there is not a measurement`;
210
+ return [
211
+ `load ${id || "?"} painted nothing yet${hidden}; a missing LCP there is not a measurement`,
212
+ ];
189
213
  });
190
214
  }
191
215
  /**
@@ -153,6 +153,7 @@ function summariseWatch(data) {
153
153
  ? `never changed over ${data.durationMs}ms (${data.totalSamples} samples)`
154
154
  : `${data.samples.length} transitions over ${data.durationMs}ms (${data.totalSamples} samples)`;
155
155
  const notes = [
156
+ ...(data.notes ?? []),
156
157
  data.exceptions.length > 0
157
158
  ? `${data.exceptions.length} page exception${data.exceptions.length === 1 ? "" : "s"}`
158
159
  : null,
@@ -21,5 +21,12 @@ export declare class RunSessionService {
21
21
  * The run `--run` names, or the one live run. Refuses rather than guesses
22
22
  * between two live ones, the same way every op on a run does.
23
23
  */
24
- status(selector?: string): void;
24
+ status(selector?: string, probeMs?: number): Promise<void>;
25
+ /**
26
+ * Ends the run the way Ctrl+C does, and waits until its process is gone, so
27
+ * its browser and its files are released when this returns.
28
+ *
29
+ * @throws {ControlError} `STOP_TIMEOUT` when the process outlives `waitMs`.
30
+ */
31
+ stop(selector?: string, waitMs?: number): Promise<void>;
25
32
  }
@@ -1,4 +1,5 @@
1
1
  import { ControlError } from "../control-client.js";
2
+ import { LiveRun } from "../live-run.js";
2
3
  /** The shape a run takes in an answer: its meta, minus what nobody asks for. */
3
4
  function describe(run) {
4
5
  return {
@@ -25,6 +26,31 @@ function describe(run) {
25
26
  dir: run.dir,
26
27
  };
27
28
  }
29
+ /**
30
+ * Whether the page of a live run answers a CDP evaluation within `probeMs`.
31
+ *
32
+ * A live process says nothing about its page: a page blocked by a dialog or a
33
+ * busy renderer kept `live: true` while every tool timed out.
34
+ */
35
+ async function probePage(run, probeMs) {
36
+ const started = Date.now();
37
+ try {
38
+ const data = await new LiveRun(run).request({ op: "debug.eval", expression: "1" }, probeMs);
39
+ return {
40
+ answers: true,
41
+ paused: data.onCallFrame,
42
+ ms: Date.now() - started,
43
+ };
44
+ }
45
+ catch (error) {
46
+ const failed = ControlError.from(error);
47
+ return {
48
+ answers: false,
49
+ code: failed?.code ?? "PROBE_FAILED",
50
+ message: failed?.message ?? String(error),
51
+ };
52
+ }
53
+ }
28
54
  /**
29
55
  * The runs on this machine. Reads the registry only, so it answers with no run
30
56
  * live — which is when it is most often asked.
@@ -63,7 +89,7 @@ export class RunSessionService {
63
89
  * The run `--run` names, or the one live run. Refuses rather than guesses
64
90
  * between two live ones, the same way every op on a run does.
65
91
  */
66
- status(selector) {
92
+ async status(selector, probeMs = 3000) {
67
93
  const live = this.registry.liveRuns();
68
94
  if (!selector && live.length === 0) {
69
95
  throw new ControlError("NO_LIVE_RUN", "No onboarding run is live.", {
@@ -72,7 +98,8 @@ export class RunSessionService {
72
98
  }
73
99
  const run = this.registry.resolve(selector);
74
100
  const described = describe(run);
75
- this.answer.give(`${run.meta.id} — ${run.status}`, { run: described }, () => {
101
+ const page = run.live ? await probePage(run, probeMs) : undefined;
102
+ this.answer.give(`${run.meta.id} — ${run.status}${page && !page.answers ? `, but its page does not answer: ${page.message}` : page?.paused ? ", paused in the debugger" : ""}`, { run: described, ...(page ? { page } : {}) }, () => {
76
103
  for (const field of [
77
104
  "customerPath",
78
105
  "configName",
@@ -92,4 +119,33 @@ export class RunSessionService {
92
119
  }
93
120
  });
94
121
  }
122
+ /**
123
+ * Ends the run the way Ctrl+C does, and waits until its process is gone, so
124
+ * its browser and its files are released when this returns.
125
+ *
126
+ * @throws {ControlError} `STOP_TIMEOUT` when the process outlives `waitMs`.
127
+ */
128
+ async stop(selector, waitMs = 15_000) {
129
+ const run = this.registry.resolve(selector);
130
+ if (!this.registry.processAlive(run)) {
131
+ this.answer.give(`${run.meta.id} had already ended — ${run.status}`, {
132
+ run: describe(run),
133
+ stopped: false,
134
+ });
135
+ return;
136
+ }
137
+ process.kill(run.meta.pid, "SIGTERM");
138
+ const deadline = Date.now() + waitMs;
139
+ while (this.registry.processAlive(run)) {
140
+ if (Date.now() > deadline) {
141
+ throw new ControlError("STOP_TIMEOUT", `${run.meta.id} still runs ${waitMs} ms after SIGTERM.`, { pid: run.meta.pid, next: `kill ${run.meta.pid}` });
142
+ }
143
+ await new Promise((resolve) => setTimeout(resolve, 200));
144
+ }
145
+ const ended = this.registry.resolve(run.meta.id);
146
+ this.answer.give(`${ended.meta.id} stopped — ${ended.status}`, {
147
+ run: describe(ended),
148
+ stopped: true,
149
+ });
150
+ }
95
151
  }
@@ -352,7 +352,7 @@ describe("RunCacheService over the control socket", () => {
352
352
  });
353
353
  await run((cache) => cache.prewarm({ url: "/p" }), true);
354
354
  const again = await answer((cache) => cache.prewarm({ url: "/p" }));
355
- expect(again.entries[0].built, "second call found it already there").to.equal(false);
355
+ expect(again.entries[0], "second call found it already there").to.include({ built: false, alreadyCached: true });
356
356
  });
357
357
  });
358
358
  describe("clear, evict and errors", () => {
@@ -139,6 +139,14 @@ describe("RunInjectService over the control socket", () => {
139
139
  expect(data.records.map((record) => record.v)).to.deep.equal(["a", "b"]);
140
140
  expect(line).to.contain("3 of the oldest dropped");
141
141
  });
142
+ it("should name the preload ids when a read names none", async () => {
143
+ await add({ source: "record(1)" });
144
+ await add({ recipe: "mark-timeline" });
145
+ const failed = await failure(injectOp((inject) => inject.read(undefined)));
146
+ expect(failed.code).to.equal("PRELOAD_REQUIRED");
147
+ expect(failed.message).to.contain("p1, p2");
148
+ expect(failed.detail.preloads).to.deep.equal(["p1", "p2"]);
149
+ });
142
150
  it("should read a param as JSON when it parses, and as a string otherwise", async () => {
143
151
  await add({
144
152
  recipe: "sample",
@@ -200,6 +208,25 @@ describe("RunInjectService over the control socket", () => {
200
208
  expect(source).to.contain("largest-contentful-paint");
201
209
  expect(source).to.contain("buffered: true");
202
210
  });
211
+ it("should say a painted load without a layout shift has a CLS of 0", async () => {
212
+ // The browser reports no layout-shift entry when nothing shifted, so an
213
+ // absent CLS record is a CLS of 0, not a metric left unmeasured.
214
+ await add({ recipe: "web-vitals" });
215
+ browser.page.slots = {
216
+ p1: {
217
+ records: [
218
+ { t: 1, v: { metric: "fcp", value: 300 }, load: "1700" },
219
+ { t: 2, v: { metric: "lcp", value: 500 }, load: "1700" },
220
+ { t: 3, v: { metric: "fcp", value: 280 }, load: "1800" },
221
+ { t: 4, v: { metric: "cls", value: 0.1, total: 0.1 }, load: "1800" },
222
+ ],
223
+ dropped: 0,
224
+ },
225
+ };
226
+ const line = await summary(injectOp((inject) => inject.read("p1")));
227
+ expect(line).to.contain("load 1700 had no layout shift: CLS 0 so far");
228
+ expect(line).to.not.contain("load 1800 had no layout shift");
229
+ });
203
230
  it("should say a load that painted nothing has no LCP to measure", async () => {
204
231
  // A window the compositor does not draw paints nothing; "no LCP" there
205
232
  // is an absence, not a measurement.
@@ -1,4 +1,5 @@
1
1
  import { expect } from "chai";
2
+ import { spawn } from "node:child_process";
2
3
  import { afterEach, beforeEach, describe, it } from "mocha";
3
4
  import { processStartToken } from "../../../run-registry/process-identity.js";
4
5
  import { RunSessionServiceFactory } from "../../session/run-session-service-factory.js";
@@ -89,6 +90,27 @@ describe("RunSessionService", () => {
89
90
  expect(failed.code).to.equal("NO_LIVE_RUN");
90
91
  expect(failed.detail.next).to.contain("sk onboarding <customerPath>");
91
92
  });
93
+ it("should say whether the live run's page answers", async () => {
94
+ const page = (evaluate) => ({ available: true, debug: { evaluate } });
95
+ await fixture.serve("ok-production-1", {
96
+ session: page(async () => ({ onCallFrame: false, value: 1 })),
97
+ });
98
+ await fixture.serve("stuck-production-1", {
99
+ session: page(() => new Promise(() => undefined)),
100
+ });
101
+ const probe = (id) => answer(sessionOp((session) => session.status(id, 300)));
102
+ expect((await probe("ok-production-1")).page).to.include({
103
+ answers: true,
104
+ paused: false,
105
+ });
106
+ // A page blocked by a dialog: the process is live, the page is not.
107
+ const stuck = await probe("stuck-production-1");
108
+ expect(stuck.run.live).to.equal(true);
109
+ expect(stuck.page).to.include({
110
+ answers: false,
111
+ code: "CONTROL_TIMEOUT",
112
+ });
113
+ });
92
114
  it("should describe a finished run when --run names one", async () => {
93
115
  fixture.writeRun({ id: "old-production-1", error: "it broke" });
94
116
  const data = await answer(sessionOp((session) => session.status("old-production-1")));
@@ -98,4 +120,31 @@ describe("RunSessionService", () => {
98
120
  });
99
121
  });
100
122
  });
123
+ describe("stop", () => {
124
+ const stopOp = (selector) => async (sink, json) => new RunSessionServiceFactory(fixture.context(sink, json, {}))
125
+ .buildService()
126
+ .stop(selector, 5000);
127
+ it("should end the run's process and wait until it is gone", async () => {
128
+ const child = spawn(process.execPath, [
129
+ "-e",
130
+ "setInterval(() => {}, 1000)",
131
+ ]);
132
+ const exited = new Promise((resolve) => child.once("exit", resolve));
133
+ await new Promise((resolve) => child.once("spawn", resolve));
134
+ fixture.writeRun({
135
+ id: "shop-production-1",
136
+ status: "running",
137
+ pid: child.pid,
138
+ startToken: processStartToken(child.pid ?? 0) ?? undefined,
139
+ });
140
+ const data = await answer(stopOp("shop"));
141
+ expect(data.stopped).to.equal(true);
142
+ expect(await exited).to.equal(null);
143
+ });
144
+ it("should say a run had already ended, and send nothing", async () => {
145
+ fixture.writeRun({ id: "old-production-1", status: "stopped" });
146
+ const data = await answer(stopOp("old-production-1"));
147
+ expect(data.stopped).to.equal(false);
148
+ });
149
+ });
101
150
  });
@@ -17,7 +17,9 @@ export type RequestOutcome =
17
17
  /** Handed back to Chrome untouched. */
18
18
  | "continued"
19
19
  /** A handler threw. The request was failed so the page sees a network error. */
20
- | "error";
20
+ | "error"
21
+ /** The page dropped the request before the answer, e.g. on a navigation away. Not an error. */
22
+ | "cancelled";
21
23
  export interface RequestRecord {
22
24
  /** Monotonic within a run, from 1. The cursor for tailing. */
23
25
  seq: number;