@speedkit/cli 4.32.0 → 4.34.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 (26) hide show
  1. package/.env.sample +5 -0
  2. package/CHANGELOG.md +14 -0
  3. package/README.md +2 -1
  4. package/dist/helpers/chrome-flags.d.ts +65 -0
  5. package/dist/helpers/chrome-flags.js +191 -0
  6. package/dist/helpers/chrome-flags.spec.d.ts +1 -0
  7. package/dist/helpers/chrome-flags.spec.js +234 -0
  8. package/dist/helpers/cli-config.d.ts +2 -0
  9. package/dist/helpers/cli-config.js +6 -0
  10. package/dist/helpers/cli-config.spec.js +34 -0
  11. package/dist/services/onboarding/browser/extension/extension-bridge.d.ts +15 -2
  12. package/dist/services/onboarding/browser/extension/extension-bridge.js +25 -5
  13. package/dist/services/onboarding/browser/extension/extension-downloader.d.ts +6 -2
  14. package/dist/services/onboarding/browser/extension/extension-downloader.js +26 -16
  15. package/dist/services/onboarding/browser/extension/extension-validator.d.ts +16 -1
  16. package/dist/services/onboarding/browser/extension/extension-validator.js +46 -7
  17. package/dist/services/onboarding/error/browser-extension-build-error.d.ts +9 -0
  18. package/dist/services/onboarding/error/browser-extension-build-error.js +11 -0
  19. package/dist/services/onboarding/onboarding-model.d.ts +15 -0
  20. package/dist/services/onboarding/onboarding-model.js +63 -16
  21. package/dist/services/onboarding/onboarding-model.spec.js +57 -0
  22. package/dist/services/onboarding/onboarding-service-factory.js +10 -3
  23. package/dist/services/onboarding/onboarding-service.d.ts +2 -1
  24. package/dist/services/onboarding/onboarding-service.js +5 -1
  25. package/oclif.manifest.json +1 -1
  26. package/package.json +1 -1
package/.env.sample CHANGED
@@ -33,6 +33,11 @@
33
33
  # Chrome Extension Local Paths
34
34
  # CHROME_EXTENSION_PATHS='<SPEED_KIT_EXTENSION_DIST_PATH>,<CHROME_EXTENSION_DIST_PATH_1>,<CHROME_EXTENSION_DIST_PATH_2>'
35
35
 
36
+ # System-specific Chrome flags, appended to the onboarding browser after sk's own and the customer
37
+ # config's chromeFlags. Separate flags by whitespace, or pass a JSON array when a value has a space.
38
+ # A flag that is already set elsewhere is kept, and the CLI warns about it. Replaces "chromeFlags" of config.json.
39
+ # CHROME_FLAGS='--ozone-platform=wayland --enable-features=VaapiVideoDecoder'
40
+
36
41
  # Default SK Test App Name
37
42
  # TEST_APP='<APP_NAME>'
38
43
 
package/CHANGELOG.md CHANGED
@@ -1,3 +1,17 @@
1
+ # [4.34.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.33.0...v4.34.0) (2026-09-23)
2
+
3
+
4
+ ### Features
5
+
6
+ * **browser-extension:** handle specific cases of not usable extensions ([f77634e](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/f77634e5b077bb75a09177bb056f838b8854bc8e))
7
+
8
+ # [4.33.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.32.0...v4.33.0) (2026-09-23)
9
+
10
+
11
+ ### Features
12
+
13
+ * **onboarding:** add settings for chromeFlags ([955109d](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/955109d1c05caab7e6852569b88a52fcdda3861c))
14
+
1
15
  # [4.32.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.31.0...v4.32.0) (2026-09-22)
2
16
 
3
17
 
package/README.md CHANGED
@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
21
21
  $ sk COMMAND
22
22
  running command...
23
23
  $ sk (--version)
24
- @speedkit/cli/4.32.0 linux-x64 node-v22.23.2
24
+ @speedkit/cli/4.34.0 linux-x64 node-v22.23.2
25
25
  $ sk --help [COMMAND]
26
26
  USAGE
27
27
  $ sk COMMAND
@@ -49,6 +49,7 @@ On the first execution of any `sk` command a `config.json` will be created and s
49
49
  "chromePath": "", // local path to the Chrome binary
50
50
  "chromeUserProfilePath": "", // local path to the Custom Chrome User Profile (use if you want to have Chrome's state saved)
51
51
  "chromeExtensionPaths": "", // comma separated list of local paths to unpacked extensions for Chrome to load
52
+ "chromeFlags": [], // system-specific flags appended to the onboarding browser, e.g. ["--ozone-platform=wayland"]; a duplicate is kept and warned about
52
53
  "slackToken": "", // Slack token that will be injected to the deploymentDetection
53
54
  "testApp": "", // name of your Test Speed Kit App
54
55
  "ideaDirectory": "", // local directory path to the IntelliJ's shell binary
@@ -0,0 +1,65 @@
1
+ /** Chrome flags of one origin, labelled so a duplicate can name where each occurrence came from. */
2
+ export interface ChromeFlagSource {
3
+ source: string;
4
+ flags: string[];
5
+ }
6
+ /** One switch passed more than once, in launch order. Chrome takes the last occurrence. */
7
+ export interface ChromeFlagDuplicate {
8
+ name: string;
9
+ occurrences: {
10
+ source: string;
11
+ flag: string;
12
+ }[];
13
+ }
14
+ /**
15
+ * Reads the system-specific `chromeFlags` setting.
16
+ *
17
+ * config.json holds an array. An environment variable holds a string: a JSON array, or flags
18
+ * separated by whitespace. Commas can't separate flags, because values like
19
+ * `--enable-features=A,B` contain them. A value with a space in it needs the JSON form.
20
+ */
21
+ export declare function parseChromeFlags(value: unknown): string[];
22
+ /** A feature named by one source, as written there: `Foo:param/1` for feature `Foo`. */
23
+ export interface ChromeFeatureOccurrence {
24
+ source: string;
25
+ entry: string;
26
+ }
27
+ /** A feature listed more than once in the same flag, in launch order. */
28
+ export interface ChromeFeatureDuplicate {
29
+ kind: "duplicate";
30
+ flag: string;
31
+ feature: string;
32
+ occurrences: ChromeFeatureOccurrence[];
33
+ }
34
+ /** A feature that is both enabled and disabled. Chrome disables it. */
35
+ export interface ChromeFeatureConflict {
36
+ kind: "conflict";
37
+ feature: string;
38
+ enabled: ChromeFeatureOccurrence[];
39
+ disabled: ChromeFeatureOccurrence[];
40
+ }
41
+ export type ChromeFeatureFinding = ChromeFeatureDuplicate | ChromeFeatureConflict;
42
+ export declare function isFeatureListFlag(flag: string): boolean;
43
+ /** The feature of a list entry, without its override, trial or params: `*Foo<Trial:p/1` → `Foo`. */
44
+ export declare function chromeFeatureName(entry: string): string;
45
+ /**
46
+ * Finds every feature that is listed twice in one flag, or both enabled and disabled,
47
+ * across all sources.
48
+ */
49
+ export declare function findChromeFeatureFindings(sources: ChromeFlagSource[]): ChromeFeatureFinding[];
50
+ /**
51
+ * Folds every occurrence of a feature list flag into one, at the place of the first occurrence.
52
+ * A feature listed twice in one flag keeps its first entry, the one Chrome would use.
53
+ * A feature that is both enabled and disabled stays in both lists.
54
+ */
55
+ export declare function mergeChromeFeatureFlags(flags: string[]): string[];
56
+ export declare function formatChromeFeatureFinding(finding: ChromeFeatureFinding): string;
57
+ /** The switch of a flag, without its value: `--foo=bar` → `--foo`. */
58
+ export declare function chromeFlagName(flag: string): string;
59
+ /**
60
+ * Finds every switch passed more than once across all sources, in launch order.
61
+ * Flags are matched on their name, so `--foo=a` and `--foo=b` are a duplicate too.
62
+ * Feature list flags are left to findChromeFeatureFindings.
63
+ */
64
+ export declare function findDuplicateChromeFlags(sources: ChromeFlagSource[]): ChromeFlagDuplicate[];
65
+ export declare function formatChromeFlagDuplicate({ name, occurrences, }: ChromeFlagDuplicate): string;
@@ -0,0 +1,191 @@
1
+ /**
2
+ * Reads the system-specific `chromeFlags` setting.
3
+ *
4
+ * config.json holds an array. An environment variable holds a string: a JSON array, or flags
5
+ * separated by whitespace. Commas can't separate flags, because values like
6
+ * `--enable-features=A,B` contain them. A value with a space in it needs the JSON form.
7
+ */
8
+ export function parseChromeFlags(value) {
9
+ if (Array.isArray(value)) {
10
+ return value
11
+ .filter((flag) => typeof flag === "string")
12
+ .map((flag) => flag.trim())
13
+ .filter(Boolean);
14
+ }
15
+ if (typeof value !== "string") {
16
+ return [];
17
+ }
18
+ const trimmed = value.trim();
19
+ if (trimmed.startsWith("[")) {
20
+ try {
21
+ return parseChromeFlags(JSON.parse(trimmed));
22
+ }
23
+ catch {
24
+ throw new Error(`chromeFlags is not a valid JSON array: ${trimmed}`);
25
+ }
26
+ }
27
+ return trimmed.split(/\s+/).filter(Boolean);
28
+ }
29
+ /**
30
+ * Chrome flags that each hold a list of features. Puppeteer merges every occurrence of the
31
+ * `*-features` pair into one flag, Chrome itself the `*-blink-features` pair. In both, a disabled
32
+ * feature beats an enabled one, so they are merged here and checked feature by feature instead.
33
+ */
34
+ const FEATURE_LISTS = [
35
+ { enable: "--enable-features", disable: "--disable-features" },
36
+ { enable: "--enable-blink-features", disable: "--disable-blink-features" },
37
+ ];
38
+ const FEATURE_LIST_FLAGS = FEATURE_LISTS.flatMap(({ enable, disable }) => [
39
+ enable,
40
+ disable,
41
+ ]);
42
+ export function isFeatureListFlag(flag) {
43
+ return FEATURE_LIST_FLAGS.includes(chromeFlagName(flag));
44
+ }
45
+ /** The feature of a list entry, without its override, trial or params: `*Foo<Trial:p/1` → `Foo`. */
46
+ export function chromeFeatureName(entry) {
47
+ return entry.replace(/^\*/, "").split(/[<:]/)[0].trim();
48
+ }
49
+ function featureEntries(flag) {
50
+ const separator = flag.indexOf("=");
51
+ if (separator === -1) {
52
+ return [];
53
+ }
54
+ return flag
55
+ .slice(separator + 1)
56
+ .split(",")
57
+ .map((entry) => entry.trim())
58
+ .filter(Boolean);
59
+ }
60
+ function collectFeatures(sources, listFlag) {
61
+ const byFeature = new Map();
62
+ for (const { source, flags } of sources) {
63
+ for (const flag of flags) {
64
+ if (chromeFlagName(flag) !== listFlag) {
65
+ continue;
66
+ }
67
+ for (const entry of featureEntries(flag)) {
68
+ const feature = chromeFeatureName(entry);
69
+ byFeature.set(feature, [
70
+ ...(byFeature.get(feature) ?? []),
71
+ { source, entry },
72
+ ]);
73
+ }
74
+ }
75
+ }
76
+ return byFeature;
77
+ }
78
+ /**
79
+ * Finds every feature that is listed twice in one flag, or both enabled and disabled,
80
+ * across all sources.
81
+ */
82
+ export function findChromeFeatureFindings(sources) {
83
+ const findings = [];
84
+ for (const { enable, disable } of FEATURE_LISTS) {
85
+ const enabled = collectFeatures(sources, enable);
86
+ const disabled = collectFeatures(sources, disable);
87
+ for (const [flag, features] of [
88
+ [enable, enabled],
89
+ [disable, disabled],
90
+ ]) {
91
+ for (const [feature, occurrences] of features) {
92
+ if (occurrences.length > 1) {
93
+ findings.push({ kind: "duplicate", flag, feature, occurrences });
94
+ }
95
+ }
96
+ }
97
+ for (const [feature, occurrences] of enabled) {
98
+ if (disabled.has(feature)) {
99
+ findings.push({
100
+ kind: "conflict",
101
+ feature,
102
+ enabled: occurrences,
103
+ disabled: disabled.get(feature),
104
+ });
105
+ }
106
+ }
107
+ }
108
+ return findings;
109
+ }
110
+ /**
111
+ * Folds every occurrence of a feature list flag into one, at the place of the first occurrence.
112
+ * A feature listed twice in one flag keeps its first entry, the one Chrome would use.
113
+ * A feature that is both enabled and disabled stays in both lists.
114
+ */
115
+ export function mergeChromeFeatureFlags(flags) {
116
+ const merged = [];
117
+ const placed = new Set();
118
+ for (const flag of flags) {
119
+ const name = chromeFlagName(flag);
120
+ if (!FEATURE_LIST_FLAGS.includes(name)) {
121
+ merged.push(flag);
122
+ continue;
123
+ }
124
+ if (placed.has(name)) {
125
+ continue;
126
+ }
127
+ placed.add(name);
128
+ const entries = new Map();
129
+ for (const entry of flags
130
+ .filter((other) => chromeFlagName(other) === name)
131
+ .flatMap((other) => featureEntries(other))) {
132
+ const feature = chromeFeatureName(entry);
133
+ if (!entries.has(feature)) {
134
+ entries.set(feature, entry);
135
+ }
136
+ }
137
+ if (entries.size > 0) {
138
+ merged.push(`${name}=${[...entries.values()].join(",")}`);
139
+ }
140
+ }
141
+ return merged;
142
+ }
143
+ export function formatChromeFeatureFinding(finding) {
144
+ const listed = (occurrences) => occurrences.map(({ source, entry }) => `${entry} (${source})`).join(", ");
145
+ if (finding.kind === "conflict") {
146
+ return `Chrome feature ${finding.feature} is both enabled, ${listed(finding.enabled)}, and disabled, ${listed(finding.disabled)}. Chrome disables it.`;
147
+ }
148
+ const { flag, feature, occurrences } = finding;
149
+ const message = `Chrome feature ${feature} is listed ${occurrences.length} times in ${flag}: ${listed(occurrences)}.`;
150
+ const sameEntry = new Set(occurrences.map(({ entry }) => entry)).size === 1;
151
+ return sameEntry
152
+ ? message
153
+ : `${message} Chrome uses the first one, ${occurrences[0].entry}.`;
154
+ }
155
+ /** The switch of a flag, without its value: `--foo=bar` → `--foo`. */
156
+ export function chromeFlagName(flag) {
157
+ const separator = flag.indexOf("=");
158
+ return separator === -1 ? flag : flag.slice(0, separator);
159
+ }
160
+ /**
161
+ * Finds every switch passed more than once across all sources, in launch order.
162
+ * Flags are matched on their name, so `--foo=a` and `--foo=b` are a duplicate too.
163
+ * Feature list flags are left to findChromeFeatureFindings.
164
+ */
165
+ export function findDuplicateChromeFlags(sources) {
166
+ const byName = new Map();
167
+ for (const { source, flags } of sources) {
168
+ for (const flag of flags) {
169
+ const name = chromeFlagName(flag);
170
+ // Merged instead, and checked by findChromeFeatureFindings.
171
+ if (FEATURE_LIST_FLAGS.includes(name)) {
172
+ continue;
173
+ }
174
+ byName.set(name, [...(byName.get(name) ?? []), { source, flag }]);
175
+ }
176
+ }
177
+ return [...byName]
178
+ .filter(([, occurrences]) => occurrences.length > 1)
179
+ .map(([name, occurrences]) => ({ name, occurrences }));
180
+ }
181
+ export function formatChromeFlagDuplicate({ name, occurrences, }) {
182
+ const listed = occurrences
183
+ .map(({ source, flag }) => `${flag} (${source})`)
184
+ .join(", ");
185
+ const sameValue = new Set(occurrences.map(({ flag }) => flag)).size === 1;
186
+ if (sameValue) {
187
+ return `Chrome flag ${name} is passed ${occurrences.length} times: ${listed}.`;
188
+ }
189
+ const last = occurrences.at(-1);
190
+ return `Chrome flag ${name} is passed ${occurrences.length} times: ${listed}. Chrome uses the last one, ${last.flag}.`;
191
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,234 @@
1
+ import { expect } from "chai";
2
+ import { describe, it } from "mocha";
3
+ import { chromeFeatureName, findChromeFeatureFindings, findDuplicateChromeFlags, formatChromeFeatureFinding, formatChromeFlagDuplicate, mergeChromeFeatureFlags, parseChromeFlags, } from "./chrome-flags.js";
4
+ describe("parseChromeFlags", () => {
5
+ it("keeps an array from config.json, trimmed and without empty entries", () => {
6
+ expect(parseChromeFlags([" --foo ", "", "--bar=1", 3])).to.deep.equal([
7
+ "--foo",
8
+ "--bar=1",
9
+ ]);
10
+ });
11
+ it("splits an environment string on whitespace, not on commas", () => {
12
+ expect(parseChromeFlags(" --enable-features=A,B --ozone-platform=wayland ")).to.deep.equal(["--enable-features=A,B", "--ozone-platform=wayland"]);
13
+ });
14
+ it("reads a JSON array from the environment, so a value may contain spaces", () => {
15
+ expect(parseChromeFlags('["--user-agent=Mozilla/5.0 (X11)", "--foo"]')).to.deep.equal(["--user-agent=Mozilla/5.0 (X11)", "--foo"]);
16
+ });
17
+ it("names the value of a broken JSON array", () => {
18
+ expect(() => parseChromeFlags('["--foo"')).to.throw(/\["--foo"/);
19
+ });
20
+ it("returns no flags for an unset value", () => {
21
+ expect(parseChromeFlags(undefined)).to.deep.equal([]);
22
+ expect(parseChromeFlags("")).to.deep.equal([]);
23
+ });
24
+ });
25
+ describe("findDuplicateChromeFlags", () => {
26
+ it("matches flags on their name across sources, in launch order", () => {
27
+ const duplicates = findDuplicateChromeFlags([
28
+ {
29
+ source: "sk",
30
+ flags: ["--window-size=1,1", "--no-first-run"],
31
+ },
32
+ { source: "customer config", flags: ["--proxy-server=socks5://a"] },
33
+ {
34
+ source: "system",
35
+ flags: ["--window-size=2,2", "--proxy-server=socks5://a"],
36
+ },
37
+ ]);
38
+ expect(duplicates).to.deep.equal([
39
+ {
40
+ name: "--window-size",
41
+ occurrences: [
42
+ { source: "sk", flag: "--window-size=1,1" },
43
+ { source: "system", flag: "--window-size=2,2" },
44
+ ],
45
+ },
46
+ {
47
+ name: "--proxy-server",
48
+ occurrences: [
49
+ { source: "customer config", flag: "--proxy-server=socks5://a" },
50
+ { source: "system", flag: "--proxy-server=socks5://a" },
51
+ ],
52
+ },
53
+ ]);
54
+ });
55
+ it("finds a duplicate within one source", () => {
56
+ const duplicates = findDuplicateChromeFlags([
57
+ { source: "system", flags: ["--mute-audio", "--mute-audio"] },
58
+ ]);
59
+ expect(duplicates.map(({ name }) => name)).to.deep.equal(["--mute-audio"]);
60
+ });
61
+ it("leaves the feature list flags to the feature check", () => {
62
+ expect(findDuplicateChromeFlags([
63
+ {
64
+ source: "sk",
65
+ flags: ["--enable-features=A", "--disable-blink-features=B"],
66
+ },
67
+ {
68
+ source: "system",
69
+ flags: ["--enable-features=C", "--disable-blink-features=D"],
70
+ },
71
+ ])).to.deep.equal([]);
72
+ });
73
+ it("reports nothing for distinct flags", () => {
74
+ expect(findDuplicateChromeFlags([
75
+ { source: "sk", flags: ["--foo"] },
76
+ { source: "system", flags: ["--foobar"] },
77
+ ])).to.deep.equal([]);
78
+ });
79
+ });
80
+ describe("formatChromeFlagDuplicate", () => {
81
+ it("names the flag Chrome uses when the values differ", () => {
82
+ expect(formatChromeFlagDuplicate({
83
+ name: "--enable-features",
84
+ occurrences: [
85
+ { source: "sk", flag: "--enable-features=Translate" },
86
+ { source: "system", flag: "--enable-features=Foo" },
87
+ ],
88
+ })).to.equal("Chrome flag --enable-features is passed 2 times: --enable-features=Translate (sk), --enable-features=Foo (system). Chrome uses the last one, --enable-features=Foo.");
89
+ });
90
+ it("only lists the occurrences when the values match", () => {
91
+ expect(formatChromeFlagDuplicate({
92
+ name: "--mute-audio",
93
+ occurrences: [
94
+ { source: "customer config", flag: "--mute-audio" },
95
+ { source: "system", flag: "--mute-audio" },
96
+ ],
97
+ })).to.equal("Chrome flag --mute-audio is passed 2 times: --mute-audio (customer config), --mute-audio (system).");
98
+ });
99
+ });
100
+ describe("chromeFeatureName", () => {
101
+ it("drops the override, trial and params of an entry", () => {
102
+ expect(chromeFeatureName("Foo")).to.equal("Foo");
103
+ expect(chromeFeatureName("Foo:param/1")).to.equal("Foo");
104
+ expect(chromeFeatureName("*Foo<Trial.Group:param/1")).to.equal("Foo");
105
+ });
106
+ });
107
+ describe("findChromeFeatureFindings", () => {
108
+ it("finds a feature listed twice in one flag, across sources", () => {
109
+ expect(findChromeFeatureFindings([
110
+ { source: "customer config", flags: ["--enable-features=Foo,Bar"] },
111
+ { source: "system", flags: ["--enable-features=Foo:p/1"] },
112
+ ])).to.deep.equal([
113
+ {
114
+ kind: "duplicate",
115
+ flag: "--enable-features",
116
+ feature: "Foo",
117
+ occurrences: [
118
+ { source: "customer config", entry: "Foo" },
119
+ { source: "system", entry: "Foo:p/1" },
120
+ ],
121
+ },
122
+ ]);
123
+ });
124
+ it("finds a feature that is both enabled and disabled", () => {
125
+ expect(findChromeFeatureFindings([
126
+ {
127
+ source: "puppeteer",
128
+ flags: ["--disable-features=Translate,MediaRouter"],
129
+ },
130
+ { source: "system", flags: ["--enable-features=Translate"] },
131
+ ])).to.deep.equal([
132
+ {
133
+ kind: "conflict",
134
+ feature: "Translate",
135
+ enabled: [{ source: "system", entry: "Translate" }],
136
+ disabled: [{ source: "puppeteer", entry: "Translate" }],
137
+ },
138
+ ]);
139
+ });
140
+ it("checks the blink lists apart from the base features", () => {
141
+ const findings = findChromeFeatureFindings([
142
+ {
143
+ source: "sk",
144
+ flags: ["--disable-blink-features=AutomationControlled"],
145
+ },
146
+ {
147
+ source: "system",
148
+ flags: [
149
+ "--enable-features=AutomationControlled",
150
+ "--disable-blink-features=AutomationControlled",
151
+ ],
152
+ },
153
+ ]);
154
+ expect(findings).to.deep.equal([
155
+ {
156
+ kind: "duplicate",
157
+ flag: "--disable-blink-features",
158
+ feature: "AutomationControlled",
159
+ occurrences: [
160
+ { source: "sk", entry: "AutomationControlled" },
161
+ { source: "system", entry: "AutomationControlled" },
162
+ ],
163
+ },
164
+ ]);
165
+ });
166
+ });
167
+ describe("mergeChromeFeatureFlags", () => {
168
+ it("folds each feature list into one flag at its first place", () => {
169
+ expect(mergeChromeFeatureFlags([
170
+ "--no-first-run",
171
+ "--enable-features=A,B",
172
+ "--disable-blink-features=X",
173
+ "--mute-audio",
174
+ "--enable-features=C",
175
+ "--disable-blink-features=Y",
176
+ ])).to.deep.equal([
177
+ "--no-first-run",
178
+ "--enable-features=A,B,C",
179
+ "--disable-blink-features=X,Y",
180
+ "--mute-audio",
181
+ ]);
182
+ });
183
+ it("keeps the first entry of a feature listed twice", () => {
184
+ expect(mergeChromeFeatureFlags([
185
+ "--enable-features=Foo:p/1,Bar",
186
+ "--enable-features=Foo:p/2",
187
+ ])).to.deep.equal(["--enable-features=Foo:p/1,Bar"]);
188
+ });
189
+ it("keeps a feature that is both enabled and disabled in both lists", () => {
190
+ expect(mergeChromeFeatureFlags([
191
+ "--enable-features=Foo",
192
+ "--disable-features=Foo",
193
+ ])).to.deep.equal(["--enable-features=Foo", "--disable-features=Foo"]);
194
+ });
195
+ it("drops a feature list flag without features", () => {
196
+ expect(mergeChromeFeatureFlags(["--enable-features=", "--foo"])).to.deep.equal(["--foo"]);
197
+ });
198
+ it("leaves every other flag as it is, duplicates included", () => {
199
+ const flags = ["--mute-audio", "--window-size=1,1", "--mute-audio"];
200
+ expect(mergeChromeFeatureFlags(flags)).to.deep.equal(flags);
201
+ });
202
+ });
203
+ describe("formatChromeFeatureFinding", () => {
204
+ it("names both sides of a conflict and that the disable wins", () => {
205
+ expect(formatChromeFeatureFinding({
206
+ kind: "conflict",
207
+ feature: "Translate",
208
+ enabled: [{ source: "system", entry: "Translate" }],
209
+ disabled: [{ source: "puppeteer", entry: "Translate" }],
210
+ })).to.equal("Chrome feature Translate is both enabled, Translate (system), and disabled, Translate (puppeteer). Chrome disables it.");
211
+ });
212
+ it("names the entry Chrome uses when a duplicate differs", () => {
213
+ expect(formatChromeFeatureFinding({
214
+ kind: "duplicate",
215
+ flag: "--enable-features",
216
+ feature: "Foo",
217
+ occurrences: [
218
+ { source: "customer config", entry: "Foo" },
219
+ { source: "system", entry: "Foo:p/1" },
220
+ ],
221
+ })).to.equal("Chrome feature Foo is listed 2 times in --enable-features: Foo (customer config), Foo:p/1 (system). Chrome uses the first one, Foo.");
222
+ });
223
+ it("only lists a duplicate with identical entries", () => {
224
+ expect(formatChromeFeatureFinding({
225
+ kind: "duplicate",
226
+ flag: "--disable-blink-features",
227
+ feature: "AutomationControlled",
228
+ occurrences: [
229
+ { source: "sk", entry: "AutomationControlled" },
230
+ { source: "system", entry: "AutomationControlled" },
231
+ ],
232
+ })).to.equal("Chrome feature AutomationControlled is listed 2 times in --disable-blink-features: AutomationControlled (sk), AutomationControlled (system).");
233
+ });
234
+ });
@@ -10,6 +10,8 @@ export interface ManagedExtension {
10
10
  }
11
11
  export interface UserCliConfig {
12
12
  chromeExtensionPaths: string;
13
+ /** system-specific flags, appended to the onboarding browser's launch args */
14
+ chromeFlags: string[];
13
15
  chromePath: string;
14
16
  chromeUserProfilePath: string;
15
17
  diffExec: string;
@@ -1,9 +1,11 @@
1
1
  import * as dotenv from "dotenv";
2
2
  import fs from "node:fs";
3
3
  import path, { resolve } from "node:path";
4
+ import { parseChromeFlags } from "./chrome-flags.js";
4
5
  dotenv.config({ quiet: true });
5
6
  const environmentMapping = {
6
7
  chromeExtensionPaths: "CHROME_EXTENSION_PATHS",
8
+ chromeFlags: "CHROME_FLAGS",
7
9
  chromePath: "CHROME_PATH",
8
10
  chromeUserProfilePath: "CHROME_USER_PROFILE_PATH",
9
11
  diffExec: "DIFF_EXEC",
@@ -23,6 +25,7 @@ export class CliConfig {
23
25
  config;
24
26
  userCliConfig = {
25
27
  chromeExtensionPaths: "",
28
+ chromeFlags: [],
26
29
  chromePath: "",
27
30
  chromeUserProfilePath: "",
28
31
  diffExec: "",
@@ -50,6 +53,8 @@ export class CliConfig {
50
53
  this.loadConfigFromConfigFile();
51
54
  // override config from environment
52
55
  this.loadConfigFromEnvironment();
56
+ // The environment holds a string, config.json an array.
57
+ this.userCliConfig.chromeFlags = parseChromeFlags(this.userCliConfig.chromeFlags);
53
58
  this.resolveExtensionConfigPaths();
54
59
  this.userCliConfig.tempFolder = this.config.cacheDir;
55
60
  this.userCliConfig.runtimeConfig = this.config;
@@ -63,6 +68,7 @@ export class CliConfig {
63
68
  createEmptyUserConfig() {
64
69
  return {
65
70
  chromeExtensionPaths: "",
71
+ chromeFlags: [],
66
72
  chromePath: "",
67
73
  chromeUserProfilePath: "",
68
74
  diffExec: "",
@@ -80,4 +80,38 @@ describe("CliConfig save/load", () => {
80
80
  expect(reloaded.managedChromeExtensions[0].id).to.equal("abc");
81
81
  expect(reloaded.managedChromeExtensions[0].version).to.equal("1.0.0");
82
82
  });
83
+ describe("chromeFlags", () => {
84
+ const previous = process.env.CHROME_FLAGS;
85
+ afterEach(() => {
86
+ if (previous === undefined) {
87
+ delete process.env.CHROME_FLAGS;
88
+ }
89
+ else {
90
+ process.env.CHROME_FLAGS = previous;
91
+ }
92
+ });
93
+ it("reads the array from config.json", () => {
94
+ delete process.env.CHROME_FLAGS;
95
+ new CliConfig(fakeOclifConfig(dir)).save({
96
+ chromeFlags: ["--ozone-platform=wayland"],
97
+ });
98
+ const loaded = new CliConfig(fakeOclifConfig(dir)).load();
99
+ expect(loaded.chromeFlags).to.deep.equal(["--ozone-platform=wayland"]);
100
+ });
101
+ it("lets CHROME_FLAGS replace config.json, parsed into an array", () => {
102
+ new CliConfig(fakeOclifConfig(dir)).save({
103
+ chromeFlags: ["--ozone-platform=wayland"],
104
+ });
105
+ process.env.CHROME_FLAGS = "--enable-features=A,B --mute-audio";
106
+ const loaded = new CliConfig(fakeOclifConfig(dir)).load();
107
+ expect(loaded.chromeFlags).to.deep.equal([
108
+ "--enable-features=A,B",
109
+ "--mute-audio",
110
+ ]);
111
+ });
112
+ it("defaults to no flags", () => {
113
+ delete process.env.CHROME_FLAGS;
114
+ expect(new CliConfig(fakeOclifConfig(dir)).load().chromeFlags).to.deep.equal([]);
115
+ });
116
+ });
83
117
  });
@@ -1,6 +1,11 @@
1
1
  import { Browser } from "puppeteer";
2
2
  import { DevelopmentToolsMessage } from "../../onboarding-model.js";
3
3
  import { CliServiceInterface } from "../../../cli/index.js";
4
+ /**
5
+ * Name heuristic for the devtools extension, shared by ExtensionValidator
6
+ * (is one among the loaded extensions?) and the service-worker lookup below.
7
+ */
8
+ export declare function isDevtoolsExtensionName(name: string): boolean;
4
9
  /**
5
10
  * Writes onboarding state (messages, status) into the devtools extension's
6
11
  * chrome.storage.local via a CDP session against the extension's MV3
@@ -10,13 +15,21 @@ import { CliServiceInterface } from "../../../cli/index.js";
10
15
  *
11
16
  * Lifecycle: construct once per browser, call `init()` after the browser is
12
17
  * launched and the devtools extension has loaded, then call `writeMessages`
13
- * whenever the message list changes.
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.
14
21
  */
15
22
  export declare class ExtensionBridge {
16
23
  private readonly cli;
24
+ private readonly devtoolsExtensionLoaded;
17
25
  private browser;
18
26
  private extensionId;
19
- constructor(cli: CliServiceInterface);
27
+ constructor(cli: CliServiceInterface, devtoolsExtensionLoaded: boolean);
28
+ /**
29
+ * false when the browser is started without a devtools extension, so there
30
+ * is nothing to connect to
31
+ */
32
+ get isAvailable(): boolean;
20
33
  /**
21
34
  * Bind the bridge to a freshly-launched browser, discover the
22
35
  * devtools-extension's service-worker target, and cache its extension ID.
@@ -4,8 +4,15 @@ const PROTOCOL_VERSION = 1;
4
4
  const SW_LOOKUP_RETRY_MS = 250;
5
5
  const INIT_POLL_INTERVAL_MS = 200;
6
6
  const INIT_POLL_TIMEOUT_MS = 4000;
7
- // Same name heuristic as ExtensionValidator.handleDevtoolsExtension.
8
7
  const EXTENSION_NAME_MATCHERS = ["speed-kit devtools", "devtools extension"];
8
+ /**
9
+ * Name heuristic for the devtools extension, shared by ExtensionValidator
10
+ * (is one among the loaded extensions?) and the service-worker lookup below.
11
+ */
12
+ export function isDevtoolsExtensionName(name) {
13
+ const lower = name.toLowerCase();
14
+ return EXTENSION_NAME_MATCHERS.some((matcher) => lower.includes(matcher));
15
+ }
9
16
  /**
10
17
  * Writes onboarding state (messages, status) into the devtools extension's
11
18
  * chrome.storage.local via a CDP session against the extension's MV3
@@ -15,14 +22,25 @@ const EXTENSION_NAME_MATCHERS = ["speed-kit devtools", "devtools extension"];
15
22
  *
16
23
  * Lifecycle: construct once per browser, call `init()` after the browser is
17
24
  * launched and the devtools extension has loaded, then call `writeMessages`
18
- * whenever the message list changes.
25
+ * whenever the message list changes. Constructed with
26
+ * `devtoolsExtensionLoaded: false` (no devtools extension among the browser's
27
+ * extensions) the bridge stays unavailable and never looks for a target.
19
28
  */
20
29
  export class ExtensionBridge {
21
30
  cli;
31
+ devtoolsExtensionLoaded;
22
32
  browser = null;
23
33
  extensionId = null;
24
- constructor(cli) {
34
+ constructor(cli, devtoolsExtensionLoaded) {
25
35
  this.cli = cli;
36
+ this.devtoolsExtensionLoaded = devtoolsExtensionLoaded;
37
+ }
38
+ /**
39
+ * false when the browser is started without a devtools extension, so there
40
+ * is nothing to connect to
41
+ */
42
+ get isAvailable() {
43
+ return this.devtoolsExtensionLoaded;
26
44
  }
27
45
  /**
28
46
  * Bind the bridge to a freshly-launched browser, discover the
@@ -32,6 +50,9 @@ export class ExtensionBridge {
32
50
  * the extension. Throws if no matching SW target is found in time.
33
51
  */
34
52
  async init(browser) {
53
+ if (!this.isAvailable) {
54
+ throw new Error("ExtensionBridge: no devtools extension loaded");
55
+ }
35
56
  this.browser = browser;
36
57
  const deadline = Date.now() + INIT_POLL_TIMEOUT_MS;
37
58
  let target = await this.findDevtoolsServiceWorker();
@@ -129,8 +150,7 @@ export class ExtensionBridge {
129
150
  const name = await safe(this.readManifestName(target));
130
151
  if (!name.success || !name.data)
131
152
  continue;
132
- const lower = name.data.toLowerCase();
133
- if (EXTENSION_NAME_MATCHERS.some((m) => lower.includes(m))) {
153
+ if (isDevtoolsExtensionName(name.data)) {
134
154
  return target;
135
155
  }
136
156
  }
@@ -6,7 +6,11 @@ export declare class ExtensionDownloader {
6
6
  constructor(userConfig: UserCliConfig, cli: CliServiceInterface);
7
7
  downloadExtension(): Promise<string>;
8
8
  private updateLocalDevtools;
9
- private isInstalled;
10
- private checkInstalledVersion;
9
+ /**
10
+ * version of the cached devtools extension, or null when it is missing or
11
+ * its manifest is unreadable (e.g. a zero-filled file after an interrupted
12
+ * write) — both count as not installed, so it gets installed again
13
+ */
14
+ private getInstalledVersion;
11
15
  private getRemoteVersion;
12
16
  }
@@ -14,11 +14,10 @@ export class ExtensionDownloader {
14
14
  }
15
15
  async downloadExtension() {
16
16
  // check for already installed devExtension
17
- const isInstalled = this.isInstalled();
18
- if (isInstalled) {
17
+ const localVersion = this.getInstalledVersion();
18
+ if (localVersion) {
19
19
  // check for updates
20
20
  const remoteVersion = await this.getRemoteVersion();
21
- const localVersion = await this.checkInstalledVersion();
22
21
  if (semver.compare(remoteVersion, localVersion) > 0) {
23
22
  const response = await this.cli.confirm(`integration-devtools update available from ${localVersion} to ${remoteVersion} Install?`, true);
24
23
  if (!response) {
@@ -45,14 +44,17 @@ export class ExtensionDownloader {
45
44
  async updateLocalDevtools() {
46
45
  // downloadExtension
47
46
  const extensionResponse = await fetch("https://threepointonefour.app.baqend.com/v1/code/webhook_devtools_release?download");
48
- // get fileName from header
49
- const fileName = extensionResponse.headers.get("filename");
47
+ if (!extensionResponse.ok) {
48
+ throw new Error(`Could not download ${devtools}: ${extensionResponse.status} ${extensionResponse.statusText}`);
49
+ }
50
50
  // resolve path for unpacked extension
51
51
  const extensionUnpacked = path.resolve(this.userConfig.tempFolder, devtools);
52
- // resolve path for zipFile
53
- const archivePath = path.resolve(this.userConfig.tempFolder, fileName);
52
+ // resolve path for zipFile, it is removed after extraction, so its name
53
+ // does not depend on the response
54
+ const archivePath = path.resolve(this.userConfig.tempFolder, `${devtools}.zip`);
54
55
  // getFileBlob
55
56
  const extensionBlob = await extensionResponse.bytes();
57
+ fs.mkdirSync(this.userConfig.tempFolder, { recursive: true });
56
58
  // write zipFile
57
59
  fs.writeFileSync(archivePath, extensionBlob);
58
60
  // cleanUp older versions
@@ -63,15 +65,23 @@ export class ExtensionDownloader {
63
65
  fs.rmSync(archivePath);
64
66
  return extensionUnpacked;
65
67
  }
66
- isInstalled() {
67
- const extensionPath = path.resolve(this.userConfig.tempFolder, devtools, "manifest.json");
68
- return fs.existsSync(extensionPath);
69
- }
70
- checkInstalledVersion() {
71
- const extensionPath = path.resolve(this.userConfig.tempFolder, devtools, "manifest.json");
72
- const manifestFile = fs.readFileSync(extensionPath, "utf-8");
73
- const manifestConfig = JSON.parse(manifestFile);
74
- return manifestConfig.version;
68
+ /**
69
+ * version of the cached devtools extension, or null when it is missing or
70
+ * its manifest is unreadable (e.g. a zero-filled file after an interrupted
71
+ * write) — both count as not installed, so it gets installed again
72
+ */
73
+ getInstalledVersion() {
74
+ const manifestPath = path.resolve(this.userConfig.tempFolder, devtools, "manifest.json");
75
+ if (!fs.existsSync(manifestPath)) {
76
+ return null;
77
+ }
78
+ const manifest = safe(() => JSON.parse(fs.readFileSync(manifestPath, "utf8")));
79
+ if (manifest.success !== true ||
80
+ typeof manifest.data?.version !== "string") {
81
+ this.cli.writeWarning(`${devtools} in "${path.dirname(manifestPath)}" has an unreadable manifest.json, treating it as not installed`);
82
+ return null;
83
+ }
84
+ return manifest.data.version;
75
85
  }
76
86
  async getRemoteVersion() {
77
87
  const versionResponse = await fetch("https://threepointonefour.app.baqend.com/v1/code/webhook_devtools_release");
@@ -1,12 +1,27 @@
1
1
  import { UserCliConfig } from "../../../../helpers/cli-config.js";
2
2
  import { CliServiceInterface } from "../../../cli/index.js";
3
3
  import { ExtensionDownloader } from "./extension-downloader.js";
4
+ export interface BrowserExtensions {
5
+ paths: string[];
6
+ /** a devtools extension is among `paths`, so ExtensionBridge can connect */
7
+ hasDevtoolsExtension: boolean;
8
+ }
4
9
  export declare class ExtensionValidator {
5
10
  private extensionDownloader;
6
11
  private cliConfig;
7
12
  private cli;
8
13
  constructor(extensionDownloader: ExtensionDownloader, cliConfig: UserCliConfig, cli: CliServiceInterface);
9
- getValidBrowserExtensionPaths(): Promise<string[]>;
14
+ getValidBrowserExtensions(): Promise<BrowserExtensions>;
15
+ /**
16
+ * manifest of a configured extension path. One inside a local npm project
17
+ * was built there (e.g. the devtools), so a missing or unreadable manifest
18
+ * means that build failed or has not run — point at the project to build.
19
+ */
20
+ private getConfiguredManifestConfig;
21
+ /**
22
+ * nearest folder above the build output that holds a package.json
23
+ */
24
+ private findProjectRoot;
10
25
  private getManifestConfig;
11
26
  private handleDevtoolsExtension;
12
27
  }
@@ -3,6 +3,10 @@ import { readFile } from "node:fs/promises";
3
3
  import { safe } from "../../../../helpers/safe.js";
4
4
  import { existsSync } from "node:fs";
5
5
  import { BrowserExtensionError } from "../../error/browser-extension-error.js";
6
+ import { BrowserExtensionBuildError } from "../../error/browser-extension-build-error.js";
7
+ import { isDevtoolsExtensionName } from "./extension-bridge.js";
8
+ // build output sits at most this deep below its project, e.g. `.output/chrome-mv3`
9
+ const MAX_BUILD_FOLDER_DEPTH = 3;
6
10
  export class ExtensionValidator {
7
11
  extensionDownloader;
8
12
  cliConfig;
@@ -12,7 +16,7 @@ export class ExtensionValidator {
12
16
  this.cliConfig = cliConfig;
13
17
  this.cli = cli;
14
18
  }
15
- async getValidBrowserExtensionPaths() {
19
+ async getValidBrowserExtensions() {
16
20
  const validExtensions = [];
17
21
  this.cli.startAction("ONBOARDING:RESOLVE:BROWSER_EXTENSION", "resolve browserExtensions");
18
22
  const browserExtensions = this.cliConfig.chromeExtensionPaths
@@ -22,7 +26,7 @@ export class ExtensionValidator {
22
26
  });
23
27
  for (const extensionPath of browserExtensions) {
24
28
  const cleanedExtensionPath = path.resolve(extensionPath.trim());
25
- const manifestConfig = await this.getManifestConfig(cleanedExtensionPath);
29
+ const manifestConfig = await this.getConfiguredManifestConfig(cleanedExtensionPath);
26
30
  if (!manifestConfig) {
27
31
  continue;
28
32
  }
@@ -39,7 +43,43 @@ export class ExtensionValidator {
39
43
  // @ts-expect-error typeMissMatch
40
44
  this.cli.table(validExtensions, { name: {}, version: {}, path: {} });
41
45
  }
42
- return validExtensions.map((config) => config.path);
46
+ return {
47
+ paths: validExtensions.map((config) => config.path),
48
+ hasDevtoolsExtension: validExtensions.some((config) => isDevtoolsExtensionName(config.name)),
49
+ };
50
+ }
51
+ /**
52
+ * manifest of a configured extension path. One inside a local npm project
53
+ * was built there (e.g. the devtools), so a missing or unreadable manifest
54
+ * means that build failed or has not run — point at the project to build.
55
+ */
56
+ async getConfiguredManifestConfig(extensionPath) {
57
+ const result = await safe(this.getManifestConfig(extensionPath));
58
+ if (result.success === true) {
59
+ return result.data;
60
+ }
61
+ const projectRoot = this.findProjectRoot(extensionPath);
62
+ if (!projectRoot) {
63
+ throw result.errorObj;
64
+ }
65
+ throw new BrowserExtensionBuildError(extensionPath, projectRoot);
66
+ }
67
+ /**
68
+ * nearest folder above the build output that holds a package.json
69
+ */
70
+ findProjectRoot(extensionPath) {
71
+ let directory = extensionPath;
72
+ for (let depth = 0; depth < MAX_BUILD_FOLDER_DEPTH; depth++) {
73
+ const parent = path.dirname(directory);
74
+ if (parent === directory) {
75
+ return null;
76
+ }
77
+ directory = parent;
78
+ if (existsSync(path.join(directory, "package.json"))) {
79
+ return directory;
80
+ }
81
+ }
82
+ return null;
43
83
  }
44
84
  async getManifestConfig(cleanedExtensionPath) {
45
85
  const manifestPath = path.resolve(cleanedExtensionPath, "manifest.json");
@@ -57,8 +97,7 @@ export class ExtensionValidator {
57
97
  }
58
98
  async handleDevtoolsExtension(validExtensions) {
59
99
  // check if devtools extension can be find in current extensionPaths
60
- if (validExtensions.some((config) => config.name.toLowerCase().includes("speed-kit devtools") ||
61
- config.name.toLowerCase().includes("devtools extension"))) {
100
+ if (validExtensions.some((config) => isDevtoolsExtensionName(config.name))) {
62
101
  return;
63
102
  }
64
103
  // download or update extension
@@ -67,8 +106,8 @@ export class ExtensionValidator {
67
106
  this.cli.writeError(result?.error);
68
107
  return;
69
108
  }
70
- if (result.data?.length < 1) {
71
- this.cli.writeError(`found extensionPath seems broken.`);
109
+ // install declined, or it failed and the downloader reported why
110
+ if (!result.data) {
72
111
  return;
73
112
  }
74
113
  // get extensionDetails from manifestFile
@@ -0,0 +1,9 @@
1
+ import ApplicationError from "../../error-handling/error/application-error.js";
2
+ /**
3
+ * a configured browserExtension without a readable manifest.json inside a
4
+ * local npm project — its build failed or has not run
5
+ */
6
+ export declare class BrowserExtensionBuildError extends ApplicationError {
7
+ readonly code = "BROWSER_EXTENSION_BUILD_ERROR";
8
+ constructor(extensionPath: string, projectRoot: string);
9
+ }
@@ -0,0 +1,11 @@
1
+ import ApplicationError from "../../error-handling/error/application-error.js";
2
+ /**
3
+ * a configured browserExtension without a readable manifest.json inside a
4
+ * local npm project — its build failed or has not run
5
+ */
6
+ export class BrowserExtensionBuildError extends ApplicationError {
7
+ code = "BROWSER_EXTENSION_BUILD_ERROR";
8
+ constructor(extensionPath, projectRoot) {
9
+ super(`browserExtension "${extensionPath}" has no readable manifest.json, the build of "${projectRoot}" failed or has not run`, [`run "npm run build" in ${projectRoot}`]);
10
+ }
11
+ }
@@ -5,6 +5,7 @@ import { AbortResponse } from "./browser/abort-response.js";
5
5
  import { task } from "./todo-collector.js";
6
6
  import { VanillaPuppeteer } from "puppeteer-extra";
7
7
  import { Command } from "@oclif/core/command";
8
+ import { ChromeFeatureFinding, ChromeFlagDuplicate } from "../../helpers/chrome-flags.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 };
@@ -44,6 +45,8 @@ export declare class BrowserContext {
44
45
  readonly debuggingPort: boolean;
45
46
  readonly headless: boolean;
46
47
  readonly debugPort: number;
48
+ /** Everything sk passes before the customer's chromeFlags. */
49
+ private readonly skArgs;
47
50
  readonly browserArgs: string[];
48
51
  readonly chromePath: string;
49
52
  constructor(domain: string, browserVersionString?: string, chromeFlags?: string[], userConfig?: UserCliConfig, userAgent?: string, debuggingPort?: boolean, headless?: boolean, debugPort?: number);
@@ -55,6 +58,18 @@ export declare class BrowserContext {
55
58
  private getHeadlessParityArgs;
56
59
  private isChromeBrowser;
57
60
  private getBrowserExtensionPath;
61
+ /** The system-specific chromeFlags of the user config, appended to every other arg. */
62
+ private getSystemChromeFlags;
63
+ private getFlagSources;
64
+ /** Every switch passed more than once to the launch, across sk, customer and system flags. */
65
+ findDuplicateFlags(): ChromeFlagDuplicate[];
66
+ /**
67
+ * Every feature listed twice, or both enabled and disabled. Puppeteer's own feature lists count
68
+ * too: it merges ours into them at launch, and its disabled features win like any other.
69
+ */
70
+ findFeatureFindings(): ChromeFeatureFinding[];
71
+ /** Args that depend on how Chrome is launched, added after the customer's chromeFlags. */
72
+ private getLaunchOnlyArgs;
58
73
  getPuppeteerLaunchOptions(): Parameters<VanillaPuppeteer["launch"]>[0];
59
74
  }
60
75
  export interface FetchRequestPausedEventHandler {
@@ -3,8 +3,11 @@ import { CLI_CONFIG_IS_TEST, CLI_CONFIG_NAME, CLIParameters, CLIParametersChar,
3
3
  import { BrowserConfig } from "./browser/config/browser-config.js";
4
4
  import { buildHeadedUserAgent } from "./browser/executable/headed-user-agent.js";
5
5
  import { resolve } from "node:path";
6
+ import { defaultArgs } from "puppeteer";
7
+ import { findChromeFeatureFindings, findDuplicateChromeFlags, isFeatureListFlag, mergeChromeFeatureFlags, } from "../../helpers/chrome-flags.js";
6
8
  const DEFAULT_BROWSER_ARGS = [
7
- "--enable-features=Translate,NetworkService",
9
+ // No `Translate`: Chrome's translate code has no feature of that name, and Puppeteer disables it anyway.
10
+ "--enable-features=NetworkService",
8
11
  "--no-first-run",
9
12
  "--no-default-browser-check",
10
13
  // Hides the `navigator.webdriver` fingerprint so customer CDN/WAF rules don't treat the session as a bot.
@@ -68,6 +71,8 @@ export class BrowserContext {
68
71
  debuggingPort;
69
72
  headless;
70
73
  debugPort;
74
+ /** Everything sk passes before the customer's chromeFlags. */
75
+ skArgs;
71
76
  browserArgs;
72
77
  chromePath;
73
78
  constructor(domain, browserVersionString = "unknown", chromeFlags, userConfig, userAgent, debuggingPort = false, headless = false, debugPort = 9222) {
@@ -96,11 +101,14 @@ export class BrowserContext {
96
101
  this.userAgent =
97
102
  this.userAgent ?? buildHeadedUserAgent(browserVersionString);
98
103
  }
99
- this.browserArgs = [
104
+ this.skArgs = [
100
105
  ...browserArguments,
101
106
  `--unsafely-treat-insecure-origin-as-secure=${domain}`,
102
107
  ...this.getHeadlessParityArgs(),
103
- // Last, so a customer's chromeFlags override our defaults — Chrome takes the last occurrence.
108
+ ];
109
+ this.browserArgs = [
110
+ ...this.skArgs,
111
+ // After our defaults, so a customer's chromeFlags override them — Chrome takes the last occurrence.
104
112
  ...this.chromeFlags,
105
113
  ];
106
114
  }
@@ -127,6 +135,50 @@ export class BrowserContext {
127
135
  }
128
136
  return [];
129
137
  }
138
+ /** The system-specific chromeFlags of the user config, appended to every other arg. */
139
+ getSystemChromeFlags() {
140
+ return this.userConfig?.chromeFlags ?? [];
141
+ }
142
+ getFlagSources() {
143
+ return [
144
+ { source: "sk", flags: [...this.skArgs, ...this.getLaunchOnlyArgs()] },
145
+ { source: "customer config", flags: this.chromeFlags },
146
+ { source: "system", flags: this.getSystemChromeFlags() },
147
+ ];
148
+ }
149
+ /** Every switch passed more than once to the launch, across sk, customer and system flags. */
150
+ findDuplicateFlags() {
151
+ return findDuplicateChromeFlags(this.getFlagSources());
152
+ }
153
+ /**
154
+ * Every feature listed twice, or both enabled and disabled. Puppeteer's own feature lists count
155
+ * too: it merges ours into them at launch, and its disabled features win like any other.
156
+ */
157
+ findFeatureFindings() {
158
+ const puppeteerFeatureFlags = defaultArgs({
159
+ headless: this.headless,
160
+ }).filter(isFeatureListFlag);
161
+ return findChromeFeatureFindings([
162
+ { source: "puppeteer", flags: puppeteerFeatureFlags },
163
+ ...this.getFlagSources(),
164
+ ]);
165
+ }
166
+ /** Args that depend on how Chrome is launched, added after the customer's chromeFlags. */
167
+ getLaunchOnlyArgs() {
168
+ const args = [];
169
+ if (this.userConfig?.chromeExtensionPaths) {
170
+ if (this.isChromeBrowser()) {
171
+ args.push("--remote-debugging-pipe");
172
+ }
173
+ else {
174
+ args.push(`--load-extension=${this.userConfig?.chromeExtensionPaths}`, `--disable-extensions-except=${this.userConfig?.chromeExtensionPaths}`);
175
+ }
176
+ }
177
+ if (this.debuggingPort || this.headless) {
178
+ args.push(`--remote-debugging-port=${this.debugPort}`);
179
+ }
180
+ return args;
181
+ }
130
182
  getPuppeteerLaunchOptions() {
131
183
  const options = {
132
184
  devtools: !this.headless,
@@ -134,7 +186,11 @@ export class BrowserContext {
134
186
  defaultViewport: null,
135
187
  headless: this.headless,
136
188
  executablePath: this.chromePath,
137
- args: this.browserArgs,
189
+ args: mergeChromeFeatureFlags([
190
+ ...this.browserArgs,
191
+ ...this.getLaunchOnlyArgs(),
192
+ ...this.getSystemChromeFlags(),
193
+ ]),
138
194
  // Strip Puppeteer's default `--enable-automation` so Chrome doesn't show
139
195
  // the "Chrome is being controlled by automated test software" infobar.
140
196
  ignoreDefaultArgs: [
@@ -142,18 +198,9 @@ export class BrowserContext {
142
198
  ...(this.headless ? HEADLESS_DEFAULT_ARGS_TO_DROP : []),
143
199
  ],
144
200
  };
145
- if (this.userConfig?.chromeExtensionPaths) {
146
- if (this.isChromeBrowser()) {
147
- options["enableExtensions"] = this.getBrowserExtensionPath();
148
- options["pipe"] = true;
149
- options.args.push("--remote-debugging-pipe");
150
- }
151
- else {
152
- options.args.push(`--load-extension=${this.userConfig?.chromeExtensionPaths}`, `--disable-extensions-except=${this.userConfig?.chromeExtensionPaths}`);
153
- }
154
- }
155
- if (this.debuggingPort || this.headless) {
156
- options.args.push(`--remote-debugging-port=${this.debugPort}`);
201
+ if (this.userConfig?.chromeExtensionPaths && this.isChromeBrowser()) {
202
+ options["enableExtensions"] = this.getBrowserExtensionPath();
203
+ options["pipe"] = true;
157
204
  }
158
205
  return options;
159
206
  }
@@ -96,3 +96,60 @@ describe("BrowserContext headless/headed parity", () => {
96
96
  expect(launchArgs(true).length).to.equal(first);
97
97
  });
98
98
  });
99
+ describe("BrowserContext system chromeFlags", () => {
100
+ function systemContext(chromeFlags, systemFlags, debuggingPort = false) {
101
+ return new BrowserContext("example.com", "Chrome/120", chromeFlags, { ...userConfig, chromeFlags: systemFlags }, undefined, debuggingPort, false, undefined);
102
+ }
103
+ it("appends the system flags after every other arg", () => {
104
+ const args = systemContext(["--customer"], ["--system-a", "--system-b"], true).getPuppeteerLaunchOptions().args;
105
+ expect(args.slice(-2)).to.deep.equal(["--system-a", "--system-b"]);
106
+ expect(args.indexOf("--customer")).to.be.lessThan(args.indexOf("--remote-debugging-port=9222"));
107
+ });
108
+ it("keeps a duplicate in the launch args", () => {
109
+ const args = systemContext(["--mute-audio"], ["--mute-audio"]).getPuppeteerLaunchOptions().args;
110
+ expect(args.filter((arg) => arg === "--mute-audio")).to.have.length(2);
111
+ });
112
+ it("finds duplicates against sk, customer and launch-only args", () => {
113
+ const duplicates = systemContext(["--mute-audio"], ["--mute-audio", "--no-first-run", "--remote-debugging-port=1234"], true).findDuplicateFlags();
114
+ expect(duplicates.map(({ name, occurrences }) => [
115
+ name,
116
+ occurrences.map(({ source }) => source),
117
+ ])).to.deep.equal([
118
+ ["--no-first-run", ["sk", "system"]],
119
+ ["--remote-debugging-port", ["sk", "system"]],
120
+ ["--mute-audio", ["customer config", "system"]],
121
+ ]);
122
+ });
123
+ it("reports nothing without system flags", () => {
124
+ expect(systemContext([], []).findDuplicateFlags()).to.deep.equal([]);
125
+ });
126
+ it("merges the feature lists of every source into one flag each", () => {
127
+ const args = systemContext(["--enable-features=Customer"], ["--enable-features=System", "--disable-blink-features=Foo"]).getPuppeteerLaunchOptions().args;
128
+ expect(args.filter((arg) => arg.startsWith("--enable-features="))).to.deep.equal(["--enable-features=NetworkService,Customer,System"]);
129
+ expect(args.filter((arg) => arg.startsWith("--disable-blink-features="))).to.deep.equal(["--disable-blink-features=AutomationControlled,Foo"]);
130
+ });
131
+ it("checks features against Puppeteer's own lists", () => {
132
+ const findings = systemContext([], [
133
+ "--enable-features=AcceptCHFrame",
134
+ "--disable-blink-features=AutomationControlled",
135
+ ]).findFeatureFindings();
136
+ expect(findings.map((finding) => finding.kind === "conflict"
137
+ ? [
138
+ "conflict",
139
+ finding.feature,
140
+ finding.disabled.map(({ source }) => source),
141
+ ]
142
+ : [
143
+ "duplicate",
144
+ finding.feature,
145
+ finding.occurrences.map(({ source }) => source),
146
+ ])).to.deep.equal([
147
+ ["conflict", "AcceptCHFrame", ["puppeteer"]],
148
+ ["duplicate", "AutomationControlled", ["sk", "system"]],
149
+ ]);
150
+ });
151
+ it("finds no feature issue in sk's own launch", () => {
152
+ expect(systemContext([], []).findFeatureFindings()).to.deep.equal([]);
153
+ expect(newContext(true).findFeatureFindings()).to.deep.equal([]);
154
+ });
155
+ });
@@ -43,6 +43,7 @@ import { ExecutableValidator } from "./browser/executable/executable-validator.j
43
43
  import { applyOriginProxy, withOriginProxyFlag, } from "../../helpers/origin-proxy.js";
44
44
  import { QueryBuilderFactory } from "../query-builder/query-builder-factory.js";
45
45
  import { QueryType } from "../query-builder/query-builder-model.js";
46
+ import { formatChromeFeatureFinding, formatChromeFlagDuplicate, } from "../../helpers/chrome-flags.js";
46
47
  export class OnboardingServiceFactory {
47
48
  context;
48
49
  cliConfig;
@@ -81,11 +82,17 @@ export class OnboardingServiceFactory {
81
82
  const speedKitInstallContext = new SpeedKitInstallContext(customerConfig, this.context.configName, files, bundler, skTemplate, this.context.local);
82
83
  await this.buildInstallResource(speedKitInstallContext, files, cli);
83
84
  const extensionDownloader = new ExtensionDownloader(this.cliConfig, cli);
84
- const extensionPaths = await new ExtensionValidator(extensionDownloader, this.cliConfig, cli).getValidBrowserExtensionPaths();
85
- this.cliConfig.chromeExtensionPaths = extensionPaths.join(",");
85
+ const browserExtensions = await new ExtensionValidator(extensionDownloader, this.cliConfig, cli).getValidBrowserExtensions();
86
+ this.cliConfig.chromeExtensionPaths = browserExtensions.paths.join(",");
86
87
  const browserValidator = new ExecutableValidator(this.cliConfig, cli);
87
88
  const browserVersionString = await browserValidator.validateOrInstall();
88
89
  const browserContext = new BrowserContext(domainToStart, browserVersionString, withOriginProxyFlag(customerConfig.chromeFlags), this.cliConfig, undefined, this.context.debuggingPort, this.context.headless, this.context.debugPort);
90
+ for (const duplicate of browserContext.findDuplicateFlags()) {
91
+ cli.writeWarning(formatChromeFlagDuplicate(duplicate));
92
+ }
93
+ for (const finding of browserContext.findFeatureFindings()) {
94
+ cli.writeWarning(formatChromeFeatureFinding(finding));
95
+ }
89
96
  if (this.context.debuggingPort || this.context.headless) {
90
97
  cli.writeWarning(`Chrome remote debugging enabled on port ${this.context.debugPort}.`);
91
98
  }
@@ -97,7 +104,7 @@ export class OnboardingServiceFactory {
97
104
  const messageHandler = await this.prepareMessagehandler(athenaClient, files, customerConfig);
98
105
  const speedKitServiceWorkerJs = new SpeedKitServiceWorkerJs(customerConfig, files.getByName(INTEGRATION_FILES.CUSTOM.SW));
99
106
  const fetchHandler = await this.getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher, speedKitServiceWorkerJs);
100
- const extensionBridge = new ExtensionBridge(cli);
107
+ const extensionBridge = new ExtensionBridge(cli, browserExtensions.hasDevtoolsExtension);
101
108
  return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler, extensionBridge, speedKitServiceWorkerJs, browserFetch);
102
109
  }
103
110
  async prepareMessagehandler(athenaClient, files, customerConfig) {
@@ -38,7 +38,8 @@ export declare class OnboardingService {
38
38
  * message updates are mirrored into the devtools extension's
39
39
  * `chrome.storage.local`. A failure here is non-fatal: onboarding still
40
40
  * proceeds, but the devtools panel will not receive live updates from
41
- * sk-cli.
41
+ * sk-cli. Without a loaded devtools extension there is nothing to attach
42
+ * to — ExtensionValidator already reported why — so it is skipped.
42
43
  */
43
44
  private attachExtensionBridge;
44
45
  private findPage;
@@ -84,9 +84,13 @@ export class OnboardingService {
84
84
  * message updates are mirrored into the devtools extension's
85
85
  * `chrome.storage.local`. A failure here is non-fatal: onboarding still
86
86
  * proceeds, but the devtools panel will not receive live updates from
87
- * sk-cli.
87
+ * sk-cli. Without a loaded devtools extension there is nothing to attach
88
+ * to — ExtensionValidator already reported why — so it is skipped.
88
89
  */
89
90
  async attachExtensionBridge(browser) {
91
+ if (!this.extensionBridge.isAvailable) {
92
+ return;
93
+ }
90
94
  const result = await safe(this.extensionBridge.init(browser));
91
95
  if (result.success !== true) {
92
96
  this.cli.writeWarning(`ExtensionBridge unavailable, devtools panel will not receive live updates: ${result.error}`);
@@ -1651,5 +1651,5 @@
1651
1651
  ]
1652
1652
  }
1653
1653
  },
1654
- "version": "4.32.0"
1654
+ "version": "4.34.0"
1655
1655
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@speedkit/cli",
3
3
  "description": "Speed Kit CLI",
4
- "version": "4.32.0",
4
+ "version": "4.34.0",
5
5
  "author": {
6
6
  "name": "Baqend.com",
7
7
  "email": "info@baqend.com"