@speedkit/cli 4.36.2 → 4.38.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 (67) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +12 -5
  3. package/dist/commands/find-pops.js +2 -2
  4. package/dist/commands/generate-pop-config.js +9 -2
  5. package/dist/commands/login.js +0 -1
  6. package/dist/commands/onboarding.d.ts +2 -1
  7. package/dist/commands/onboarding.js +2 -0
  8. package/dist/helpers/origin-proxy.d.ts +2 -2
  9. package/dist/helpers/origin-proxy.js +24 -11
  10. package/dist/helpers/spec/origin-proxy.spec.js +85 -0
  11. package/dist/services/athena/athena-service-build-context.d.ts +8 -0
  12. package/dist/services/athena/athena-service-factory.d.ts +10 -0
  13. package/dist/services/athena/athena-service-factory.js +18 -2
  14. package/dist/services/athena/baqend-athena-service.d.ts +27 -0
  15. package/dist/services/athena/baqend-athena-service.js +69 -7
  16. package/dist/services/athena/error/baqend-query-error.d.ts +4 -0
  17. package/dist/services/athena/error/baqend-query-error.js +4 -0
  18. package/dist/services/athena/error/unreadable-response.d.ts +18 -0
  19. package/dist/services/athena/error/unreadable-response.js +29 -0
  20. package/dist/services/athena/index.d.ts +2 -0
  21. package/dist/services/athena/index.js +2 -0
  22. package/dist/services/athena/spec/baqend-athena-service.spec.js +84 -8
  23. package/dist/services/cli/cli-environment.d.ts +7 -0
  24. package/dist/services/cli/cli-environment.js +7 -0
  25. package/dist/services/config-api/client.js +3 -3
  26. package/dist/services/config-api/config-api-factory.d.ts +12 -1
  27. package/dist/services/config-api/config-api-factory.js +13 -3
  28. package/dist/services/config-api/ensure-login.d.ts +52 -0
  29. package/dist/services/config-api/ensure-login.js +93 -0
  30. package/dist/services/config-api/entity-manager-provider.d.ts +24 -2
  31. package/dist/services/config-api/entity-manager-provider.js +40 -6
  32. package/dist/services/config-api/error/login-error.d.ts +7 -1
  33. package/dist/services/config-api/error/login-error.js +13 -2
  34. package/dist/services/config-api/spec/ensure-login.spec.d.ts +1 -0
  35. package/dist/services/config-api/spec/ensure-login.spec.js +95 -0
  36. package/dist/services/deploy/deploy-service-build-context.d.ts +7 -0
  37. package/dist/services/deploy/deploy-service-factory.js +6 -1
  38. package/dist/services/deploy/mr/merge-request-deploy-service-factory.js +1 -0
  39. package/dist/services/document-handler-runtime/factory/document-handler-runtime-service-factory.js +4 -2
  40. package/dist/services/onboarding/browse/browse-service.d.ts +18 -0
  41. package/dist/services/onboarding/browse/browse-service.js +61 -0
  42. package/dist/services/onboarding/browse/browse-url.d.ts +10 -0
  43. package/dist/services/onboarding/browse/browse-url.js +19 -0
  44. package/dist/services/onboarding/browser/executable/executable-validator.js +3 -1
  45. package/dist/services/onboarding/browser/extension/extension-downloader.js +2 -0
  46. package/dist/services/onboarding/browser/launch-browser.d.ts +9 -0
  47. package/dist/services/onboarding/browser/launch-browser.js +20 -0
  48. package/dist/services/onboarding/error/browse-domain-error.d.ts +6 -0
  49. package/dist/services/onboarding/error/browse-domain-error.js +11 -0
  50. package/dist/services/onboarding/error/missing-customer-path-error.d.ts +6 -0
  51. package/dist/services/onboarding/error/missing-customer-path-error.js +11 -0
  52. package/dist/services/onboarding/onboarding-service-build-context.d.ts +5 -1
  53. package/dist/services/onboarding/onboarding-service-build-context.js +15 -3
  54. package/dist/services/onboarding/onboarding-service-factory.d.ts +34 -1
  55. package/dist/services/onboarding/onboarding-service-factory.js +88 -24
  56. package/dist/services/onboarding/onboarding-service.d.ts +2 -0
  57. package/dist/services/onboarding/onboarding-service.js +5 -16
  58. package/dist/services/onboarding/spec/browse/browse-url.spec.d.ts +1 -0
  59. package/dist/services/onboarding/spec/browse/browse-url.spec.js +28 -0
  60. package/dist/services/onboarding/spec/onboarding-service-factory.spec.d.ts +1 -0
  61. package/dist/services/onboarding/spec/onboarding-service-factory.spec.js +155 -0
  62. package/dist/services/onboarding/spec/virtual-orestes-app/crawler.spec.js +34 -1
  63. package/dist/services/pop-config/pop-config-factory.js +1 -0
  64. package/dist/services/prewarm/auto-pre-warm-factory.js +11 -1
  65. package/dist/services/query-builder/query-builder-factory.js +4 -0
  66. package/oclif.manifest.json +12 -4
  67. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,3 +1,24 @@
1
+ # [4.38.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.37.0...v4.38.0) (2026-10-02)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * check the Baqend login before it is needed, explain what the API answered ([17cbfb8](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/17cbfb8f3bc91da569fbdc39f01c88987f0e7eea))
7
+ * **login:** stop writing ~/.baqend relative to the working directory ([bd067fc](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/bd067fc80413e6af5fcbbc14d441e76c87d089eb))
8
+ * **origin-request:** send no header that fetch adds by spec ([adf6013](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/adf6013ead20217d78291a25fa9e2e62e402301e))
9
+
10
+
11
+ ### Features
12
+
13
+ * **login:** ask early for login on deploy ([b7fcaa8](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/b7fcaa8522e2b1f78ec5d1e4b78dee1cbfb11bd6))
14
+
15
+ # [4.37.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.36.2...v4.37.0) (2026-09-30)
16
+
17
+
18
+ ### Features
19
+
20
+ * **onboarding:** add --browse to open the live site in the onboarding Chrome ([baa3b2e](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/baa3b2e2bfb6215df5cf7791c0d6a6696ce3aafe))
21
+
1
22
  ## [4.36.2](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.36.1...v4.36.2) (2026-09-25)
2
23
 
3
24
 
package/README.md CHANGED
@@ -88,7 +88,7 @@ By either...
88
88
  * [`sk generate-pop-config APP`](#sk-generate-pop-config-app)
89
89
  * [`sk help [COMMAND]`](#sk-help-command)
90
90
  * [`sk login [APP]`](#sk-login-app)
91
- * [`sk onboarding CUSTOMERPATH`](#sk-onboarding-customerpath)
91
+ * [`sk onboarding [CUSTOMERPATH]`](#sk-onboarding-customerpath)
92
92
  * [`sk origin-request CUSTOMERPATH PAGEURL`](#sk-origin-request-customerpath-pageurl)
93
93
  * [`sk param-diff PAGEURL`](#sk-param-diff-pageurl)
94
94
  * [`sk prewarm APP PATH`](#sk-prewarm-app-path)
@@ -712,17 +712,17 @@ EXAMPLES
712
712
  $ sk login appName
713
713
  ```
714
714
 
715
- ## `sk onboarding CUSTOMERPATH`
715
+ ## `sk onboarding [CUSTOMERPATH]`
716
716
 
717
717
  Start a local dev environment for building and testing the Speed Kit configuration
718
718
 
719
719
  ```
720
720
  USAGE
721
- $ sk onboarding CUSTOMERPATH [-c <value>] [-t] [-d <value>] [-l] [-p] [--debugPort <value>] [-v] [-s]
722
- [--headless] [--browserFetch]
721
+ $ sk onboarding [CUSTOMERPATH] [-c <value>] [-t] [-d <value>] [-l] [-p] [--debugPort <value>] [-v] [-s]
722
+ [--headless] [--browse] [--browserFetch]
723
723
 
724
724
  ARGUMENTS
725
- CUSTOMERPATH The customer config path
725
+ [CUSTOMERPATH] The customer config path (optional with --browse)
726
726
 
727
727
  FLAGS
728
728
  -c, --configName=<value> [default: production] The costumer config name
@@ -732,6 +732,9 @@ FLAGS
732
732
  -s, --ignoreContentSecurityPolicy Removes header/meta "content-security-policy" for origin-responses
733
733
  -t, --useTestConfig Override app with configured testApp
734
734
  -v, --verboseLevel Show all messages
735
+ --browse Open the live site in the onboarding Chrome, with its extensions, but without
736
+ request interception or Speed Kit injection. Takes the domain from -d or from the
737
+ customer config.
735
738
  --browserFetch Fetch every origin document with a second headless Chrome instead of a direct
736
739
  request. Only needed when bot protection refuses the CLI outright — a refusal is
737
740
  otherwise detected and rerouted on its own.
@@ -747,6 +750,10 @@ EXAMPLES
747
750
  $ sk onboarding <customerPath> -c <configName> -d <domain>
748
751
 
749
752
  $ sk onboarding customers/decathlon.de -c production -d www.decathlon.de
753
+
754
+ $ sk onboarding --browse -d www.decathlon.de --headless --debugPort 9290
755
+
756
+ $ sk onboarding customers/decathlon.de --browse -p
750
757
  ```
751
758
 
752
759
  ## `sk origin-request CUSTOMERPATH PAGEURL`
@@ -3,7 +3,7 @@ import { SkCommand } from "../base/sk-command.js";
3
3
  import fs from "node:fs";
4
4
  import fetch from "node-fetch";
5
5
  import * as https from "node:https";
6
- import { account } from "baqend/cli";
6
+ import { ensureBaqendLogin } from "../services/config-api/ensure-login.js";
7
7
  import * as airports from "./airports_iata.json" with { type: "json" };
8
8
  const agent = new https.Agent({
9
9
  rejectUnauthorized: false,
@@ -33,7 +33,7 @@ export default class FindPops extends SkCommand {
33
33
  async run() {
34
34
  const { args: { app }, flags: { ips }, } = await this.parse(FindPops);
35
35
  const cli = this.environment.cli;
36
- const database = await account.login({ app });
36
+ const database = await ensureBaqendLogin(app, this.environment.entityManagerProvider, cli);
37
37
  const ranges = ips.split(",");
38
38
  const fetches = [];
39
39
  for (const range of ranges) {
@@ -1,6 +1,7 @@
1
1
  import { Args, Flags } from "@oclif/core";
2
2
  import { SkCommand } from "../base/sk-command.js";
3
3
  import { CLI_QUERY_DAYS_DESCRIPTION } from "../services/query-builder/query-builder-flags.js";
4
+ import { ensureBaqendLogin } from "../services/config-api/ensure-login.js";
4
5
  import { ConfigApiContext, ConfigApiServiceFactory, } from "../services/config-api/index.js";
5
6
  import { PopConfigFactory, PopConfigServiceBuildContext, } from "../services/pop-config/index.js";
6
7
  import { DiffServiceBuildContext, DiffServiceFactory, } from "../services/diff/index.js";
@@ -132,9 +133,11 @@ export default class GeneratePopConfig extends SkCommand {
132
133
  }
133
134
  async deployPrewarmingConfig(app, config, deploy) {
134
135
  const moduleName = "speedKit.Revalidated";
135
- const configService = new ConfigApiServiceFactory(new ConfigApiContext(app)).getService();
136
- const cliService = this.environment.cli;
137
136
  const environment = this.environment;
137
+ // One Baqend session for the whole command: the login settled in run()
138
+ // is the one the deploy of the generated config uses.
139
+ const configService = new ConfigApiServiceFactory(new ConfigApiContext(app), environment.entityManagerProvider).getService();
140
+ const cliService = environment.cli;
138
141
  const diffService = new DiffServiceFactory(new DiffServiceBuildContext({
139
142
  environment,
140
143
  executablePath: environment.settings.diffExec,
@@ -157,6 +160,10 @@ export default class GeneratePopConfig extends SkCommand {
157
160
  }
158
161
  async run() {
159
162
  const { args: { app }, flags: { coverage, deploy, days, "pop-limit": popLimit, "traffic-share": minimalShare, "use-rum": useRum, "force-shield": forceShield, }, } = await this.parse(GeneratePopConfig);
163
+ // Up front rather than at deploy time: the config produced below is
164
+ // always diffed against the deployed module, which needs a session — and
165
+ // with AWS credentials the pop query never asks for one.
166
+ await ensureBaqendLogin(app, this.environment.entityManagerProvider, this.environment.cli);
160
167
  // @todo refactor businessCode from this command to src/pop-config/pop-config-service
161
168
  const popConfigService = await new PopConfigFactory(new PopConfigServiceBuildContext({ environment: this.environment, app })).getService();
162
169
  const result = await popConfigService.getUsedPopsPerOrigin(app, useRum, days);
@@ -23,7 +23,6 @@ export default class Login extends SkCommand {
23
23
  createLoginTokenFileIfNotExists() {
24
24
  if (!existsSync(path.resolve(this.config.home, ".baqend"))) {
25
25
  writeFileSync(path.resolve(this.config.home, ".baqend"), "{}");
26
- writeFileSync("~/.baqend", "{}");
27
26
  }
28
27
  }
29
28
  }
@@ -16,12 +16,13 @@ export default class Onboarding extends SkCommand<OnboardingServiceBuildContext>
16
16
  verboseLevel: import("@oclif/core/interfaces").BooleanFlag<boolean>;
17
17
  ignoreContentSecurityPolicy: import("@oclif/core/interfaces").BooleanFlag<boolean>;
18
18
  headless: import("@oclif/core/interfaces").BooleanFlag<boolean>;
19
+ browse: import("@oclif/core/interfaces").BooleanFlag<boolean>;
19
20
  browserFetch: import("@oclif/core/interfaces").BooleanFlag<boolean>;
20
21
  useTestConfig: import("@oclif/core/interfaces").BooleanFlag<boolean>;
21
22
  configName: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
22
23
  };
23
24
  static examples: string[];
24
25
  /** Onboarding runs the customer's documentHandler, with its node modules. */
25
- protected customerPathForModules(args: Record<string, unknown>): string;
26
+ protected customerPathForModules(args: Record<string, unknown>): string | undefined;
26
27
  run(): Promise<void>;
27
28
  }
@@ -8,6 +8,8 @@ export default class Onboarding extends SkCommand {
8
8
  static examples = [
9
9
  `$ sk onboarding <customerPath> -c <configName> -d <domain>`,
10
10
  `$ sk onboarding customers/decathlon.de -c production -d www.decathlon.de`,
11
+ `$ sk onboarding --browse -d www.decathlon.de --headless --debugPort 9290`,
12
+ `$ sk onboarding customers/decathlon.de --browse -p`,
11
13
  ];
12
14
  /** Onboarding runs the customer's documentHandler, with its node modules. */
13
15
  customerPathForModules(args) {
@@ -106,8 +106,8 @@ export declare function withOriginProxyFlag(chromeFlags?: string[]): string[];
106
106
  * Every request that leaves the CLI for a customer origin has to use this instead of `fetch`, which
107
107
  * carries no proxy support. Requests to Baqend keep their own client and connect directly.
108
108
  *
109
- * Node's built-in `fetch` rejects a dispatcher built by the `undici` package, so a request that
110
- * needs one runs through undici's own `fetch`. A plain direct request keeps the global `fetch`.
109
+ * Node's built-in `fetch` rejects a dispatcher built by the `undici` package, so every request
110
+ * runs through undici's own `fetch`.
111
111
  */
112
112
  export declare function originFetch(url: string, init?: RequestInit, options?: OriginFetchOptions): Promise<Response>;
113
113
  /**
@@ -180,8 +180,8 @@ export function withOriginProxyFlag(chromeFlags = []) {
180
180
  * Every request that leaves the CLI for a customer origin has to use this instead of `fetch`, which
181
181
  * carries no proxy support. Requests to Baqend keep their own client and connect directly.
182
182
  *
183
- * Node's built-in `fetch` rejects a dispatcher built by the `undici` package, so a request that
184
- * needs one runs through undici's own `fetch`. A plain direct request keeps the global `fetch`.
183
+ * Node's built-in `fetch` rejects a dispatcher built by the `undici` package, so every request
184
+ * runs through undici's own `fetch`.
185
185
  */
186
186
  export function originFetch(url, init, options = {}) {
187
187
  return (transport ?? directOriginFetch)(url, init, options);
@@ -193,13 +193,29 @@ export function originFetch(url, init, options = {}) {
193
193
  * transport that needs the network leg it replaces.
194
194
  */
195
195
  export function directOriginFetch(url, init, options = {}) {
196
- const dispatcher = originDispatcher(options.tolerateLegacyTls === true);
197
- if (!dispatcher) {
198
- return fetch(url, init);
199
- }
196
+ const sent = new Headers(init?.headers);
197
+ const added = FETCH_DEFAULT_HEADERS.filter((name) => !sent.has(name));
198
+ const dispatcher = originDispatcher(options.tolerateLegacyTls === true).compose(withoutHeaders(added));
200
199
  const request = { ...init, dispatcher };
201
200
  return undiciFetch(url, request);
202
201
  }
202
+ /**
203
+ * Headers that fetch appends by spec when the caller sets none. The asset server sends no such
204
+ * default, so a header a variation sets to `null` must stay off the wire. `user-agent` and
205
+ * `accept-encoding` are not listed: a caller without headers still needs them.
206
+ */
207
+ const FETCH_DEFAULT_HEADERS = ["accept", "accept-language", "sec-fetch-mode"];
208
+ /**
209
+ * Drops the named headers right before undici writes the request, after fetch added its defaults.
210
+ * Fetch hands the dispatcher its headers as a plain object.
211
+ */
212
+ function withoutHeaders(names) {
213
+ return (dispatch) => (opts, handler) => {
214
+ const headers = Object.entries(opts.headers);
215
+ const kept = headers.filter(([name]) => !names.includes(name.toLowerCase()));
216
+ return dispatch({ ...opts, headers: Object.fromEntries(kept) }, handler);
217
+ };
218
+ }
203
219
  function currentState() {
204
220
  if (!state) {
205
221
  applyOriginProxy();
@@ -209,16 +225,13 @@ function currentState() {
209
225
  /**
210
226
  * Builds the dispatcher for one transport and caches it.
211
227
  *
212
- * `socksDispatcher` connects directly when it gets no proxy, so the same builder serves a tolerant
213
- * direct request. A strict direct request needs no dispatcher at all.
228
+ * `socksDispatcher` connects directly when it gets no proxy, so the same builder serves a direct
229
+ * request.
214
230
  *
215
231
  * @param tolerateLegacyTls - Accept an untrusted certificate and allow legacy renegotiation.
216
232
  */
217
233
  function originDispatcher(tolerateLegacyTls) {
218
234
  const current = currentState();
219
- if (!current.proxy && !tolerateLegacyTls) {
220
- return;
221
- }
222
235
  const proxies = current.proxy ? [current.proxy] : [];
223
236
  const connect = tolerateLegacyTls
224
237
  ? {
@@ -1,6 +1,7 @@
1
1
  import { expect } from "chai";
2
2
  import { describe, beforeEach, afterEach, it } from "mocha";
3
3
  import http from "node:http";
4
+ import zlib from "node:zlib";
4
5
  import { applyOriginProxy, chromeProxyFlag, findProxyInChromeFlags, originFetch, parseSocksProxy, PROXY_ENVIRONMENT_VARIABLE, resetOriginProxy, setOriginProxy, withOriginProxyFlag, } from "../origin-proxy.js";
5
6
  /** Sets or clears the enforcing environment variable. */
6
7
  function setEnvironmentProxy(value) {
@@ -157,6 +158,90 @@ describe("origin proxy", () => {
157
158
  });
158
159
  expect(await response.text()).to.equal("ok");
159
160
  });
161
+ describe("on the wire", () => {
162
+ let echo;
163
+ let echoUrl;
164
+ beforeEach(async () => {
165
+ // Answers the request headers as they arrived, or the response a path asks for.
166
+ echo = http.createServer((request, response) => {
167
+ const body = JSON.stringify(request.headers);
168
+ if (request.url === "/redirect") {
169
+ response.writeHead(302, { location: "/" }).end();
170
+ }
171
+ else if (request.url === "/missing") {
172
+ response.writeHead(404).end(body);
173
+ }
174
+ else if (request.url === "/gzip") {
175
+ response.writeHead(200, { "content-encoding": "gzip" });
176
+ response.end(zlib.gzipSync(body));
177
+ }
178
+ else if (request.url === "/br") {
179
+ response.writeHead(200, { "content-encoding": "br" });
180
+ response.end(zlib.brotliCompressSync(body));
181
+ }
182
+ else if (request.url === "/slow") {
183
+ setTimeout(() => response.end(body), 1000);
184
+ }
185
+ else {
186
+ response.end(body);
187
+ }
188
+ });
189
+ await new Promise((resolve) => echo.listen(0, "127.0.0.1", resolve));
190
+ echoUrl = `http://127.0.0.1:${echo.address().port}/`;
191
+ });
192
+ afterEach(() => {
193
+ echo.closeAllConnections();
194
+ echo.close();
195
+ });
196
+ const received = async (path = "", init, options) => (await (await originFetch(echoUrl + path, init, options)).json());
197
+ it("sends none of the headers fetch adds by spec", async () => {
198
+ const headers = await received();
199
+ expect(headers).to.not.have.property("accept-language");
200
+ expect(headers).to.not.have.property("accept");
201
+ expect(headers).to.not.have.property("sec-fetch-mode");
202
+ expect(headers).to.have.property("user-agent");
203
+ });
204
+ it("sends the headers the caller sets", async () => {
205
+ const headers = await received("", {
206
+ headers: { "Accept-Language": "en-GB", accept: "text/html" },
207
+ });
208
+ expect(headers["accept-language"]).to.equal("en-GB");
209
+ expect(headers.accept).to.equal("text/html");
210
+ });
211
+ it("drops the defaults when legacy tls is tolerated as well", async () => {
212
+ const headers = await received("", undefined, {
213
+ tolerateLegacyTls: true,
214
+ });
215
+ expect(headers).to.not.have.property("accept-language");
216
+ });
217
+ it("drops the defaults on every redirect hop", async () => {
218
+ const response = await originFetch(`${echoUrl}redirect`);
219
+ expect(response.url).to.equal(echoUrl);
220
+ expect(response.redirected).to.equal(true);
221
+ expect(await response.json()).to.not.have.property("accept-language");
222
+ });
223
+ it("answers a redirect itself in manual mode", async () => {
224
+ const response = await originFetch(`${echoUrl}redirect`, {
225
+ redirect: "manual",
226
+ });
227
+ expect(response.status).to.equal(302);
228
+ expect(response.headers.get("location")).to.equal("/");
229
+ });
230
+ it("passes a non-200 status through", async () => {
231
+ const response = await originFetch(`${echoUrl}missing`);
232
+ expect(response.status).to.equal(404);
233
+ });
234
+ it("decompresses gzip and brotli", async () => {
235
+ expect(await received("gzip")).to.have.property("host");
236
+ expect(await received("br")).to.have.property("host");
237
+ });
238
+ it("aborts when the signal times out", async () => {
239
+ const failure = await originFetch(`${echoUrl}slow`, {
240
+ signal: AbortSignal.timeout(50),
241
+ }).then(() => null, (error) => error);
242
+ expect(failure?.name).to.equal("TimeoutError");
243
+ });
244
+ });
160
245
  it("routes through the installed proxy", async () => {
161
246
  // Nothing listens on port 1, so a proxied request must fail to connect.
162
247
  setOriginProxy({ type: 5, host: "127.0.0.1", port: 1 });
@@ -17,6 +17,14 @@ export interface AthenaServiceBuildContextValues extends CommandContextValues {
17
17
  * catalog itself.
18
18
  */
19
19
  readonly catalog?: string;
20
+ /**
21
+ * Whether a missing Baqend login may be asked for while the service is
22
+ * built. On for a command the user is waiting on that cannot do its job
23
+ * without the query (`sk query --execute`, `--count`, `sk auto-prewarm`);
24
+ * off where the query is an extra the command carries on without, such as
25
+ * `sk onboarding`, which must not stop at a login prompt.
26
+ */
27
+ readonly promptForLogin?: boolean;
20
28
  }
21
29
  declare const AthenaServiceBuildContext_base: new (values: AthenaServiceBuildContextValues) => Readonly<AthenaServiceBuildContextValues>;
22
30
  /** Which app, workgroup and catalog an Athena query goes to. */
@@ -12,6 +12,16 @@ export declare class AthenaServiceFactory {
12
12
  * path (which needs an `app`).
13
13
  */
14
14
  private createService;
15
+ /**
16
+ * The provider the Baqend path will take its session from, with the login
17
+ * already settled.
18
+ *
19
+ * Settling it here rather than at the first query is the whole point: the
20
+ * caller is about to build and run a query that cannot work without a login,
21
+ * and a login asked for mid-run arrives as an unreadable API error instead of
22
+ * a prompt.
23
+ */
24
+ private getEntityManagerProvider;
15
25
  /**
16
26
  * Resolve the AWS credential chain (env, SSO cache, ...) without prompting.
17
27
  * Returns a ready client when credentials exist, otherwise `undefined` so the
@@ -4,7 +4,7 @@ import { ATHENA_CONFIG } from "./athena-service-model.js";
4
4
  import { FetchCredentialsError } from "./error/fetch-credentials-error.js";
5
5
  import { AwsAthenaService } from "./athena-service.js";
6
6
  import { BaqendAthenaService } from "./baqend-athena-service.js";
7
- import { EntityManagerProvider } from "../config-api/entity-manager-provider.js";
7
+ import { ensureBaqendLogin } from "../config-api/ensure-login.js";
8
8
  export class AthenaServiceFactory {
9
9
  context;
10
10
  service;
@@ -34,10 +34,26 @@ export class AthenaServiceFactory {
34
34
  return new AwsAthenaService(client, cli, workgroup, catalog);
35
35
  }
36
36
  if (app) {
37
- return new BaqendAthenaService(app, new EntityManagerProvider(), cli, catalog);
37
+ return new BaqendAthenaService(app, await this.getEntityManagerProvider(app, cli), cli, catalog);
38
38
  }
39
39
  throw new FetchCredentialsError("Cannot send Athena queries: no AWS credentials found and no app given for the Baqend API.");
40
40
  }
41
+ /**
42
+ * The provider the Baqend path will take its session from, with the login
43
+ * already settled.
44
+ *
45
+ * Settling it here rather than at the first query is the whole point: the
46
+ * caller is about to build and run a query that cannot work without a login,
47
+ * and a login asked for mid-run arrives as an unreadable API error instead of
48
+ * a prompt.
49
+ */
50
+ async getEntityManagerProvider(app, cli) {
51
+ const entityManagerProvider = this.context.environment.entityManagerProvider;
52
+ if (this.context.promptForLogin) {
53
+ await ensureBaqendLogin(app, entityManagerProvider, cli);
54
+ }
55
+ return entityManagerProvider;
56
+ }
41
57
  /**
42
58
  * Resolve the AWS credential chain (env, SSO cache, ...) without prompting.
43
59
  * Returns a ready client when credentials exist, otherwise `undefined` so the
@@ -6,6 +6,11 @@ export declare class BaqendAthenaService implements AthenaService {
6
6
  private entityManagerProvider;
7
7
  private cli;
8
8
  private static readonly TRIGGERED_BY;
9
+ /**
10
+ * The probe scans nothing, so it costs only a round trip; an hour of reuse
11
+ * keeps a run that fails repeatedly from sending even that more than once.
12
+ */
13
+ private static readonly PROBE_TTL;
9
14
  /** A catalog qualifier in front of a `<db>.<table>` reference. */
10
15
  private readonly catalogPrefix;
11
16
  /** The catalog whose qualifier has to come back out of the query. */
@@ -18,6 +23,28 @@ export declare class BaqendAthenaService implements AthenaService {
18
23
  */
19
24
  catalog?: string);
20
25
  getResult<T>(query: string, parameters?: AthenaParameter[], maxAgeInMinutes?: number, bucket?: AthenaBucket): Promise<T[]>;
26
+ /**
27
+ * The session to query with, which has to exist by now.
28
+ *
29
+ * Deliberately the non-prompting lookup: whoever needs this path is expected
30
+ * to have settled the login while building the service (see
31
+ * `ensureBaqendLogin`), so a session missing *here* is a bug or a
32
+ * deliberately login-less run — either way something to report, not to
33
+ * interrupt a half-finished command with a prompt for.
34
+ */
35
+ private getEntityManager;
36
+ private executeQuery;
37
+ /**
38
+ * Turns what the Baqend SDK threw into something a reader can act on.
39
+ *
40
+ * Most failures already carry the server's own message and only need the app
41
+ * named around them. The exception is the response the SDK could not read
42
+ * (see {@link isUnreadableResponse}), which carries nothing at all — there
43
+ * the only way to learn anything is to ask again with a query that cannot
44
+ * fail for its own reasons, and let the answer say whether the path itself
45
+ * is broken or just this one query.
46
+ */
47
+ private explain;
21
48
  /**
22
49
  * Inline the `?` placeholders with the given parameters (same quoting as the
23
50
  * AWS path) and strip any `live.` catalog prefix. Done in a single
@@ -1,5 +1,8 @@
1
1
  import { athenaCatalog, DEFAULT_MAX_AGE_IN_MINUTES, } from "./athena-service-model.js";
2
+ import { loginError } from "../config-api/ensure-login.js";
2
3
  import { safe } from "../../helpers/safe.js";
4
+ import { BaqendQueryError } from "./error/baqend-query-error.js";
5
+ import { isUnreadableResponse } from "./error/unreadable-response.js";
3
6
  /** A literal for use inside a regular expression. */
4
7
  function escapeRegExp(value) {
5
8
  return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
@@ -9,6 +12,11 @@ export class BaqendAthenaService {
9
12
  entityManagerProvider;
10
13
  cli;
11
14
  static TRIGGERED_BY = "speed-kit-cli";
15
+ /**
16
+ * The probe scans nothing, so it costs only a round trip; an hour of reuse
17
+ * keeps a run that fails repeatedly from sending even that more than once.
18
+ */
19
+ static PROBE_TTL = "60m";
12
20
  /** A catalog qualifier in front of a `<db>.<table>` reference. */
13
21
  catalogPrefix;
14
22
  /** The catalog whose qualifier has to come back out of the query. */
@@ -30,21 +38,75 @@ export class BaqendAthenaService {
30
38
  if (!bucket) {
31
39
  throw new Error("BaqendAthenaService.getResult requires a bucket to target");
32
40
  }
41
+ // before the spinner: a login asked for underneath a running spinner is a
42
+ // prompt the user cannot see, and one that fails there fails unreadably
43
+ const db = await this.getEntityManager();
33
44
  this.cli.startAction("ATHENA:QUERY", "execute athena query via baqend");
34
- const db = await this.entityManagerProvider.getEntityManager(this.app);
35
45
  const sql = this.prepareQuery(query, parameters);
36
46
  const ttl = `${maxAgeInMinutes}m`;
37
- // The bucket entities are not in the SDK's types: an app has the ones its
38
- // schema declares.
39
- const entity = db[bucket];
40
- const result = await safe(entity.executeQuery(sql, BaqendAthenaService.TRIGGERED_BY, ttl));
47
+ const result = await safe(this.executeQuery(db, bucket, sql, ttl));
41
48
  if (result.success === true) {
42
49
  this.cli.successAction("ATHENA:QUERY");
43
50
  return result.data;
44
51
  }
45
52
  this.cli.failAction("ATHENA:QUERY");
46
- this.cli.writeError("Cannot send Athena queries via the Baqend API for this app.");
47
- throw result.errorObj ?? new Error(result.error);
53
+ throw await this.explain(result.errorObj ?? new Error(result.error), db, bucket);
54
+ }
55
+ /**
56
+ * The session to query with, which has to exist by now.
57
+ *
58
+ * Deliberately the non-prompting lookup: whoever needs this path is expected
59
+ * to have settled the login while building the service (see
60
+ * `ensureBaqendLogin`), so a session missing *here* is a bug or a
61
+ * deliberately login-less run — either way something to report, not to
62
+ * interrupt a half-finished command with a prompt for.
63
+ */
64
+ async getEntityManager() {
65
+ const result = await this.entityManagerProvider.tryGetEntityManager(this.app);
66
+ if (result.success !== true) {
67
+ throw loginError(this.app, result.error);
68
+ }
69
+ return result.data;
70
+ }
71
+ executeQuery(db, bucket, sql, ttl) {
72
+ // The bucket entities are not in the SDK's types: an app has the ones its
73
+ // schema declares.
74
+ const entity = db[bucket];
75
+ return entity.executeQuery(sql, BaqendAthenaService.TRIGGERED_BY, ttl);
76
+ }
77
+ /**
78
+ * Turns what the Baqend SDK threw into something a reader can act on.
79
+ *
80
+ * Most failures already carry the server's own message and only need the app
81
+ * named around them. The exception is the response the SDK could not read
82
+ * (see {@link isUnreadableResponse}), which carries nothing at all — there
83
+ * the only way to learn anything is to ask again with a query that cannot
84
+ * fail for its own reasons, and let the answer say whether the path itself
85
+ * is broken or just this one query.
86
+ */
87
+ async explain(error, db, bucket) {
88
+ if (!isUnreadableResponse(error)) {
89
+ return new BaqendQueryError(`Cannot send Athena queries via the Baqend API for app ${this.app}: ${error.message}`, [
90
+ `check that you are logged in: sk login ${this.app}`,
91
+ "or use AWS credentials instead: aws sso login",
92
+ ]);
93
+ }
94
+ this.cli.comment(`The Baqend API did not say what went wrong — asking it for a "select 1" on ${bucket} to find out.`);
95
+ const probe = await safe(this.executeQuery(db, bucket, "select 1", BaqendAthenaService.PROBE_TTL));
96
+ if (probe.success !== true) {
97
+ return new BaqendQueryError(`Cannot send Athena queries via the Baqend API for app ${this.app}. ` +
98
+ `The API did not answer with a readable error; a "select 1" against ${bucket} fails too: ${probe.error}`, [
99
+ `check that you are logged in: sk login ${this.app}`,
100
+ "or use AWS credentials instead: aws sso login",
101
+ ]);
102
+ }
103
+ return new BaqendQueryError(`The Baqend API returned an empty response for this query on app ${this.app}. ` +
104
+ `The login and the ${bucket} permissions are fine — a "select 1" against it answered normally — ` +
105
+ "so it is this query that did not come back, usually because it ran longer than the API waits for an answer.", [
106
+ "narrow the query and try again, e.g. a smaller --days window or a --limit",
107
+ "or run it with AWS credentials, which poll for the result instead of waiting: aws sso login",
108
+ "the result is cached, so a query that did finish server-side answers on the next run",
109
+ ]);
48
110
  }
49
111
  /**
50
112
  * Inline the `?` placeholders with the given parameters (same quoting as the
@@ -0,0 +1,4 @@
1
+ import ApplicationError from "../../error-handling/error/application-error.js";
2
+ export declare class BaqendQueryError extends ApplicationError {
3
+ readonly code = "BAQEND_ATHENA_QUERY_FAILED";
4
+ }
@@ -0,0 +1,4 @@
1
+ import ApplicationError from "../../error-handling/error/application-error.js";
2
+ export class BaqendQueryError extends ApplicationError {
3
+ code = "BAQEND_ATHENA_QUERY_FAILED";
4
+ }
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Recognises the Baqend SDK's stand-in for a response it could not read.
3
+ *
4
+ * The SDK parses every error body as JSON and, when that fails, throws away
5
+ * both the status and the body: `Connector.send` re-wraps whatever went wrong
6
+ * in a `PersistentError`, whose name is the constructor's (hence the
7
+ * "PersistentErrorConstructor" in the output) and whose message is the generic
8
+ * "An unexpected persistent error occurred.". All that is left of the server's
9
+ * answer is the cause, "Response was not valid json: Unexpected end of JSON
10
+ * input" — i.e. "the body was empty, blank or truncated".
11
+ *
12
+ * So this error says nothing about *why* a request failed, only that nobody
13
+ * could read the reason. Every failure the app server itself reports — a
14
+ * refused bucket, an illegal token, a disabled root login — comes back as a
15
+ * `CommunicationError` carrying the server's own message instead, which is why
16
+ * this one has to be explained separately rather than passed on.
17
+ */
18
+ export declare function isUnreadableResponse(error: unknown): boolean;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Recognises the Baqend SDK's stand-in for a response it could not read.
3
+ *
4
+ * The SDK parses every error body as JSON and, when that fails, throws away
5
+ * both the status and the body: `Connector.send` re-wraps whatever went wrong
6
+ * in a `PersistentError`, whose name is the constructor's (hence the
7
+ * "PersistentErrorConstructor" in the output) and whose message is the generic
8
+ * "An unexpected persistent error occurred.". All that is left of the server's
9
+ * answer is the cause, "Response was not valid json: Unexpected end of JSON
10
+ * input" — i.e. "the body was empty, blank or truncated".
11
+ *
12
+ * So this error says nothing about *why* a request failed, only that nobody
13
+ * could read the reason. Every failure the app server itself reports — a
14
+ * refused bucket, an illegal token, a disabled root login — comes back as a
15
+ * `CommunicationError` carrying the server's own message instead, which is why
16
+ * this one has to be explained separately rather than passed on.
17
+ */
18
+ export function isUnreadableResponse(error) {
19
+ return causeChain(error).some((message) => message.includes("was not valid json") ||
20
+ message.includes("an unexpected persistent error occurred"));
21
+ }
22
+ /** The lower-cased message of the error and of every cause behind it. */
23
+ function causeChain(error) {
24
+ const messages = [];
25
+ for (let current = error, depth = 0; current instanceof Error && depth < 10; current = current.cause, depth++) {
26
+ messages.push(current.message.toLowerCase());
27
+ }
28
+ return messages;
29
+ }
@@ -4,4 +4,6 @@ export * from "./baqend-athena-service.js";
4
4
  export * from "./athena-service-factory.js";
5
5
  export * from "./athena-service-build-context.js";
6
6
  export * from "./athena-service-model.js";
7
+ export * from "./error/baqend-query-error.js";
7
8
  export * from "./error/fetch-credentials-error.js";
9
+ export * from "./error/unreadable-response.js";
@@ -4,4 +4,6 @@ export * from "./baqend-athena-service.js";
4
4
  export * from "./athena-service-factory.js";
5
5
  export * from "./athena-service-build-context.js";
6
6
  export * from "./athena-service-model.js";
7
+ export * from "./error/baqend-query-error.js";
7
8
  export * from "./error/fetch-credentials-error.js";
9
+ export * from "./error/unreadable-response.js";