@speedkit/cli 4.33.0 → 4.35.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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,17 @@
1
+ # [4.35.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.34.0...v4.35.0) (2026-09-23)
2
+
3
+
4
+ ### Features
5
+
6
+ * **devtools:** download and check before switching ([c722d91](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/c722d914ba4c8bc8eb488ccf1cf80ff6e65eeb11))
7
+
8
+ # [4.34.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.33.0...v4.34.0) (2026-09-23)
9
+
10
+
11
+ ### Features
12
+
13
+ * **browser-extension:** handle specific cases of not usable extensions ([f77634e](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/f77634e5b077bb75a09177bb056f838b8854bc8e))
14
+
1
15
  # [4.33.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.32.0...v4.33.0) (2026-09-23)
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.33.0 linux-x64 node-v22.23.2
24
+ @speedkit/cli/4.35.0 linux-x64 node-v22.23.2
25
25
  $ sk --help [COMMAND]
26
26
  USAGE
27
27
  $ sk COMMAND
@@ -80,6 +80,7 @@ By either...
80
80
  * [`sk diff-url-parameters PAGEURL`](#sk-diff-url-parameters-pageurl)
81
81
  * [`sk document-handler CUSTOMERPATH`](#sk-document-handler-customerpath)
82
82
  * [`sk extension add [REF]`](#sk-extension-add-ref)
83
+ * [`sk extension devtools`](#sk-extension-devtools)
83
84
  * [`sk extension list`](#sk-extension-list)
84
85
  * [`sk extension remove [REF]`](#sk-extension-remove-ref)
85
86
  * [`sk extension update`](#sk-extension-update)
@@ -502,6 +503,26 @@ EXAMPLES
502
503
  $ sk extension add
503
504
  ```
504
505
 
506
+ ## `sk extension devtools`
507
+
508
+ Install the integration-devtools extension for the onboarding browser, or update it to the latest release
509
+
510
+ ```
511
+ USAGE
512
+ $ sk extension devtools [--force]
513
+
514
+ FLAGS
515
+ --force reinstall the latest release even when it is up to date
516
+
517
+ DESCRIPTION
518
+ Install the integration-devtools extension for the onboarding browser, or update it to the latest release
519
+
520
+ EXAMPLES
521
+ $ sk extension devtools
522
+
523
+ $ sk extension devtools --force
524
+ ```
525
+
505
526
  ## `sk extension list`
506
527
 
507
528
  List Chrome extensions managed by the setup wizard
@@ -0,0 +1,9 @@
1
+ import { Command } from "@oclif/core";
2
+ export default class ExtensionDevtools extends Command {
3
+ static description: string;
4
+ static examples: string[];
5
+ static flags: {
6
+ force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
7
+ };
8
+ run(): Promise<void>;
9
+ }
@@ -0,0 +1,46 @@
1
+ import { Command, Flags } from "@oclif/core";
2
+ import { CliServiceFactory } from "../../services/cli/index.js";
3
+ import { CliConfig } from "../../helpers/cli-config.js";
4
+ import { ExtensionDownloader } from "../../services/onboarding/browser/extension/extension-downloader.js";
5
+ export default class ExtensionDevtools extends Command {
6
+ static description = "Install the integration-devtools extension for the onboarding browser, or update it to the latest release";
7
+ static examples = [
8
+ "$ sk extension devtools",
9
+ "$ sk extension devtools --force",
10
+ ];
11
+ static flags = {
12
+ force: Flags.boolean({
13
+ description: "reinstall the latest release even when it is up to date",
14
+ default: false,
15
+ }),
16
+ };
17
+ async run() {
18
+ const { flags } = await this.parse(ExtensionDevtools);
19
+ const cli = new CliServiceFactory().getService();
20
+ const userConfig = new CliConfig(this.config).load();
21
+ const downloader = new ExtensionDownloader(userConfig, cli);
22
+ // running the command is the confirmation
23
+ const result = await downloader.installOrUpdate({
24
+ confirm: false,
25
+ force: flags.force,
26
+ });
27
+ switch (result.status) {
28
+ case "installed": {
29
+ cli.writeSuccess(`Installed integration-devtools ${result.version}`);
30
+ break;
31
+ }
32
+ case "updated": {
33
+ cli.writeSuccess(`Updated integration-devtools to ${result.version}`);
34
+ break;
35
+ }
36
+ case "up-to-date": {
37
+ cli.writeSuccess(`integration-devtools ${result.version} is up to date`);
38
+ break;
39
+ }
40
+ default: {
41
+ // the downloader reported why
42
+ this.exit(1);
43
+ }
44
+ }
45
+ }
46
+ }
@@ -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
  }
@@ -1,12 +1,44 @@
1
1
  import { UserCliConfig } from "../../../../helpers/cli-config.js";
2
2
  import { CliServiceInterface } from "../../../cli/index.js";
3
+ interface DevtoolsInstallOptions {
4
+ /** ask before installing or updating, off for an explicit install command */
5
+ confirm?: boolean;
6
+ /** install the latest version even when the installed one is up to date */
7
+ force?: boolean;
8
+ }
9
+ export interface DevtoolsInstallResult {
10
+ /** path of the extension to load, missing when none is installed */
11
+ path?: string;
12
+ version?: string;
13
+ status: "installed" | "updated" | "up-to-date" | "kept" | "declined" | "failed";
14
+ }
3
15
  export declare class ExtensionDownloader {
4
16
  private userConfig;
5
17
  private cli;
6
18
  constructor(userConfig: UserCliConfig, cli: CliServiceInterface);
7
- downloadExtension(): Promise<string>;
19
+ /**
20
+ * path of the devtools extension to load, or undefined when there is none
21
+ */
22
+ downloadExtension(): Promise<string | undefined>;
23
+ /**
24
+ * install the devtools extension or update it to the latest version. An
25
+ * installed version is only replaced by a newer one that downloaded and
26
+ * extracted completely — it stays in use when the update check fails, the
27
+ * update is declined or its download breaks.
28
+ */
29
+ installOrUpdate({ confirm, force, }?: DevtoolsInstallOptions): Promise<DevtoolsInstallResult>;
30
+ private get installedPath();
31
+ private installLatest;
8
32
  private updateLocalDevtools;
9
- private isInstalled;
10
- private checkInstalledVersion;
11
- private getRemoteVersion;
33
+ /**
34
+ * version of the cached devtools extension, or null when it is missing or
35
+ * its manifest is unreadable (e.g. a zero-filled file after an interrupted
36
+ * write) — both count as not installed, so it gets installed again
37
+ */
38
+ private getInstalledVersion;
39
+ /**
40
+ * the latest version when it is newer than `localVersion`, otherwise null
41
+ */
42
+ private getAvailableUpdate;
12
43
  }
44
+ export {};
@@ -3,7 +3,6 @@ import path from "node:path";
3
3
  import semver from "semver";
4
4
  import extract from "extract-zip";
5
5
  import { safe } from "../../../../helpers/safe.js";
6
- import { ValidateExtensionError } from "../../error/validate-extension-error.js";
7
6
  const devtools = "integration-devtools";
8
7
  export class ExtensionDownloader {
9
8
  userConfig;
@@ -12,73 +11,160 @@ export class ExtensionDownloader {
12
11
  this.userConfig = userConfig;
13
12
  this.cli = cli;
14
13
  }
14
+ /**
15
+ * path of the devtools extension to load, or undefined when there is none
16
+ */
15
17
  async downloadExtension() {
18
+ return (await this.installOrUpdate()).path;
19
+ }
20
+ /**
21
+ * install the devtools extension or update it to the latest version. An
22
+ * installed version is only replaced by a newer one that downloaded and
23
+ * extracted completely — it stays in use when the update check fails, the
24
+ * update is declined or its download breaks.
25
+ */
26
+ async installOrUpdate({ confirm = true, force = false, } = {}) {
16
27
  // check for already installed devExtension
17
- const isInstalled = this.isInstalled();
18
- if (isInstalled) {
19
- // check for updates
20
- const remoteVersion = await this.getRemoteVersion();
21
- const localVersion = await this.checkInstalledVersion();
22
- if (semver.compare(remoteVersion, localVersion) > 0) {
23
- const response = await this.cli.confirm(`integration-devtools update available from ${localVersion} to ${remoteVersion} Install?`, true);
24
- if (!response) {
25
- throw new ValidateExtensionError(localVersion, remoteVersion);
26
- }
28
+ const localVersion = this.getInstalledVersion();
29
+ const installed = { path: this.installedPath, version: localVersion };
30
+ if (!localVersion) {
31
+ if (confirm &&
32
+ !(await this.cli.confirm("Do you want to install devtools-extension?", true))) {
33
+ return { status: "declined" };
27
34
  }
35
+ return this.installLatest("installed");
28
36
  }
29
- else {
30
- const response = await this.cli.confirm("Do you want to install devtools-extension?", true);
31
- if (!response) {
32
- return;
33
- }
37
+ if (force) {
38
+ const result = await this.installLatest("updated");
39
+ return result.status === "failed"
40
+ ? { ...installed, status: "kept" }
41
+ : result;
42
+ }
43
+ // check for updates
44
+ const update = await safe(this.getAvailableUpdate(localVersion));
45
+ if (update.success !== true) {
46
+ this.cli.writeWarning(`Could not check for ${devtools} updates, using installed ${localVersion}: ${update.error}`);
47
+ return { ...installed, status: "kept" };
48
+ }
49
+ if (!update.data) {
50
+ return { ...installed, status: "up-to-date" };
34
51
  }
52
+ if (confirm &&
53
+ !(await this.cli.confirm(`${devtools} update available from ${localVersion} to ${update.data}. Install?`, true))) {
54
+ this.cli.writeWarning(`using installed ${devtools} ${localVersion}`);
55
+ return { ...installed, status: "declined" };
56
+ }
57
+ const result = await this.installLatest("updated");
58
+ if (result.status === "failed") {
59
+ this.cli.writeWarning(`keeping installed ${devtools} ${localVersion}`);
60
+ return { ...installed, status: "kept" };
61
+ }
62
+ return result;
63
+ }
64
+ get installedPath() {
65
+ return path.resolve(this.userConfig.tempFolder, devtools);
66
+ }
67
+ async installLatest(status) {
35
68
  this.cli.startAction("ONBOARDING:UPDATE:DEVTOOLS", "update integration-devtools");
36
69
  const response = await safe(this.updateLocalDevtools());
37
70
  if (response.success === false) {
38
71
  this.cli.failAction("ONBOARDING:UPDATE:DEVTOOLS");
39
72
  this.cli.writeError(response.error);
40
- return;
73
+ return { status: "failed" };
41
74
  }
42
75
  this.cli.successAction("ONBOARDING:UPDATE:DEVTOOLS");
43
- return response.data;
76
+ return {
77
+ path: response.data,
78
+ version: this.getInstalledVersion(),
79
+ status,
80
+ };
44
81
  }
45
82
  async updateLocalDevtools() {
46
83
  // downloadExtension
47
84
  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");
50
- // resolve path for unpacked extension
51
- const extensionUnpacked = path.resolve(this.userConfig.tempFolder, devtools);
52
- // resolve path for zipFile
53
- const archivePath = path.resolve(this.userConfig.tempFolder, fileName);
85
+ if (!extensionResponse.ok) {
86
+ throw new Error(`Could not download ${devtools}: ${extensionResponse.status} ${extensionResponse.statusText}`);
87
+ }
88
+ // resolve path for zipFile, it is removed after extraction, so its name
89
+ // does not depend on the response
90
+ const archivePath = path.resolve(this.userConfig.tempFolder, `${devtools}.zip`);
91
+ // extract next to the installed version, which is only replaced once
92
+ // extraction is complete
93
+ const stagingPath = `${this.installedPath}.download`;
54
94
  // getFileBlob
55
95
  const extensionBlob = await extensionResponse.bytes();
96
+ assertZipArchive(extensionBlob, extensionResponse);
97
+ fs.mkdirSync(this.userConfig.tempFolder, { recursive: true });
56
98
  // write zipFile
57
99
  fs.writeFileSync(archivePath, extensionBlob);
58
- // cleanUp older versions
59
- fs.rmSync(extensionUnpacked, { recursive: true, force: true });
60
- // extract zipArchive
61
- await extract(archivePath, { dir: extensionUnpacked });
62
- // remove zipArchive
63
- fs.rmSync(archivePath);
64
- return extensionUnpacked;
65
- }
66
- isInstalled() {
67
- const extensionPath = path.resolve(this.userConfig.tempFolder, devtools, "manifest.json");
68
- return fs.existsSync(extensionPath);
100
+ try {
101
+ fs.rmSync(stagingPath, { recursive: true, force: true });
102
+ // extract zipArchive
103
+ await extract(archivePath, { dir: stagingPath });
104
+ // replace older version
105
+ fs.rmSync(this.installedPath, { recursive: true, force: true });
106
+ fs.renameSync(stagingPath, this.installedPath);
107
+ }
108
+ finally {
109
+ fs.rmSync(stagingPath, { recursive: true, force: true });
110
+ fs.rmSync(archivePath, { force: true });
111
+ }
112
+ return this.installedPath;
69
113
  }
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;
114
+ /**
115
+ * version of the cached devtools extension, or null when it is missing or
116
+ * its manifest is unreadable (e.g. a zero-filled file after an interrupted
117
+ * write) — both count as not installed, so it gets installed again
118
+ */
119
+ getInstalledVersion() {
120
+ const manifestPath = path.resolve(this.installedPath, "manifest.json");
121
+ if (!fs.existsSync(manifestPath)) {
122
+ return null;
123
+ }
124
+ const manifest = safe(() => JSON.parse(fs.readFileSync(manifestPath, "utf8")));
125
+ if (manifest.success !== true ||
126
+ typeof manifest.data?.version !== "string") {
127
+ this.cli.writeWarning(`${devtools} in "${path.dirname(manifestPath)}" has an unreadable manifest.json, treating it as not installed`);
128
+ return null;
129
+ }
130
+ return manifest.data.version;
75
131
  }
76
- async getRemoteVersion() {
132
+ /**
133
+ * the latest version when it is newer than `localVersion`, otherwise null
134
+ */
135
+ async getAvailableUpdate(localVersion) {
77
136
  const versionResponse = await fetch("https://threepointonefour.app.baqend.com/v1/code/webhook_devtools_release");
78
137
  if (!versionResponse.ok) {
79
- throw new Error("Could not find version for" + devtools);
138
+ throw new Error(`Could not find version for ${devtools}: ${versionResponse.status} ${versionResponse.statusText}`);
80
139
  }
81
- const response = await versionResponse.json();
82
- return response.version;
140
+ const { version } = await versionResponse.json();
141
+ return semver.gt(version, localVersion) ? version : null;
142
+ }
143
+ }
144
+ const ZIP_LOCAL_FILE_HEADER = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
145
+ const ZIP_END_OF_CENTRAL_DIRECTORY = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
146
+ // end-of-central-directory record (22 bytes) plus the longest zip comment
147
+ const ZIP_END_OF_CENTRAL_DIRECTORY_MAX_OFFSET = 22 + 0xff_ff;
148
+ /**
149
+ * a zip starts with a local file header and ends with the
150
+ * end-of-central-directory record. Anything else, e.g. an html page from a
151
+ * proxy or a cut-off download, is reported with what actually arrived.
152
+ */
153
+ function assertZipArchive(archive, response) {
154
+ const buffer = Buffer.from(archive);
155
+ const tail = buffer.subarray(Math.max(0, buffer.length - ZIP_END_OF_CENTRAL_DIRECTORY_MAX_OFFSET));
156
+ if (buffer.subarray(0, 4).equals(ZIP_LOCAL_FILE_HEADER) &&
157
+ tail.includes(ZIP_END_OF_CENTRAL_DIRECTORY)) {
158
+ return;
83
159
  }
160
+ const received = [
161
+ `${buffer.length} bytes`,
162
+ `content-type: ${response.headers.get("content-type")}`,
163
+ `content-encoding: ${response.headers.get("content-encoding")}`,
164
+ `content-length: ${response.headers.get("content-length")}`,
165
+ ].join(", ");
166
+ const kind = buffer.subarray(0, 4).equals(ZIP_LOCAL_FILE_HEADER)
167
+ ? "is cut off"
168
+ : `is not a zip, it starts with ${JSON.stringify(buffer.subarray(0, 80).toString("utf8"))}`;
169
+ throw new Error(`Download of ${devtools} ${kind} (${received})`);
84
170
  }
@@ -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
+ }
@@ -82,8 +82,8 @@ export class OnboardingServiceFactory {
82
82
  const speedKitInstallContext = new SpeedKitInstallContext(customerConfig, this.context.configName, files, bundler, skTemplate, this.context.local);
83
83
  await this.buildInstallResource(speedKitInstallContext, files, cli);
84
84
  const extensionDownloader = new ExtensionDownloader(this.cliConfig, cli);
85
- const extensionPaths = await new ExtensionValidator(extensionDownloader, this.cliConfig, cli).getValidBrowserExtensionPaths();
86
- this.cliConfig.chromeExtensionPaths = extensionPaths.join(",");
85
+ const browserExtensions = await new ExtensionValidator(extensionDownloader, this.cliConfig, cli).getValidBrowserExtensions();
86
+ this.cliConfig.chromeExtensionPaths = browserExtensions.paths.join(",");
87
87
  const browserValidator = new ExecutableValidator(this.cliConfig, cli);
88
88
  const browserVersionString = await browserValidator.validateOrInstall();
89
89
  const browserContext = new BrowserContext(domainToStart, browserVersionString, withOriginProxyFlag(customerConfig.chromeFlags), this.cliConfig, undefined, this.context.debuggingPort, this.context.headless, this.context.debugPort);
@@ -104,7 +104,7 @@ export class OnboardingServiceFactory {
104
104
  const messageHandler = await this.prepareMessagehandler(athenaClient, files, customerConfig);
105
105
  const speedKitServiceWorkerJs = new SpeedKitServiceWorkerJs(customerConfig, files.getByName(INTEGRATION_FILES.CUSTOM.SW));
106
106
  const fetchHandler = await this.getFetchEventHandler(files, customerConfig, documentHandler, cache, cli, browserContext, athenaClient, messageHandler, fileWatcher, speedKitServiceWorkerJs);
107
- const extensionBridge = new ExtensionBridge(cli);
107
+ const extensionBridge = new ExtensionBridge(cli, browserExtensions.hasDevtoolsExtension);
108
108
  return new OnboardingService(browserContext, customerConfig, fetchHandler, fileWatcher, cli, messageHandler, extensionBridge, speedKitServiceWorkerJs, browserFetch);
109
109
  }
110
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}`);
@@ -1260,6 +1260,38 @@
1260
1260
  "add.js"
1261
1261
  ]
1262
1262
  },
1263
+ "extension:devtools": {
1264
+ "aliases": [],
1265
+ "args": {},
1266
+ "description": "Install the integration-devtools extension for the onboarding browser, or update it to the latest release",
1267
+ "examples": [
1268
+ "$ sk extension devtools",
1269
+ "$ sk extension devtools --force"
1270
+ ],
1271
+ "flags": {
1272
+ "force": {
1273
+ "description": "reinstall the latest release even when it is up to date",
1274
+ "name": "force",
1275
+ "allowNo": false,
1276
+ "type": "boolean"
1277
+ }
1278
+ },
1279
+ "hasDynamicHelp": false,
1280
+ "hiddenAliases": [],
1281
+ "id": "extension:devtools",
1282
+ "pluginAlias": "@speedkit/cli",
1283
+ "pluginName": "@speedkit/cli",
1284
+ "pluginType": "core",
1285
+ "strict": true,
1286
+ "enableJsonFlag": false,
1287
+ "isESM": true,
1288
+ "relativePath": [
1289
+ "dist",
1290
+ "commands",
1291
+ "extension",
1292
+ "devtools.js"
1293
+ ]
1294
+ },
1263
1295
  "extension:list": {
1264
1296
  "aliases": [],
1265
1297
  "args": {},
@@ -1651,5 +1683,5 @@
1651
1683
  ]
1652
1684
  }
1653
1685
  },
1654
- "version": "4.33.0"
1686
+ "version": "4.35.0"
1655
1687
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@speedkit/cli",
3
3
  "description": "Speed Kit CLI",
4
- "version": "4.33.0",
4
+ "version": "4.35.0",
5
5
  "author": {
6
6
  "name": "Baqend.com",
7
7
  "email": "info@baqend.com"
@@ -1,5 +0,0 @@
1
- import ApplicationError from "../../error-handling/error/application-error.js";
2
- export declare class ValidateExtensionError extends ApplicationError {
3
- readonly code = "VALIDATE_EXTENSION_ERROR";
4
- constructor(localVersion: string, remoteVersion: string);
5
- }
@@ -1,7 +0,0 @@
1
- import ApplicationError from "../../error-handling/error/application-error.js";
2
- export class ValidateExtensionError extends ApplicationError {
3
- code = "VALIDATE_EXTENSION_ERROR";
4
- constructor(localVersion, remoteVersion) {
5
- super(`Unable to validate Versions: "${localVersion}" - "${remoteVersion}"`);
6
- }
7
- }