@speedkit/cli 4.33.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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,10 @@
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
+
1
8
  # [4.33.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.32.0...v4.33.0) (2026-09-23)
2
9
 
3
10
 
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.34.0 linux-x64 node-v22.23.2
25
25
  $ sk --help [COMMAND]
26
26
  USAGE
27
27
  $ sk COMMAND
@@ -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
+ }
@@ -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}`);
@@ -1651,5 +1651,5 @@
1651
1651
  ]
1652
1652
  }
1653
1653
  },
1654
- "version": "4.33.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.33.0",
4
+ "version": "4.34.0",
5
5
  "author": {
6
6
  "name": "Baqend.com",
7
7
  "email": "info@baqend.com"