@speedkit/cli 4.23.1 → 4.23.3

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [4.23.3](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.23.2...v4.23.3) (2026-08-25)
+
+
+### Bug Fixes
+
+* **deploy:** match refresh job names by prefix ([c593d9d](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/c593d9d69db8e05ccb71b320cb4f9c7cbda5cdac))
+
+## [4.23.2](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.23.1...v4.23.2) (2026-08-21)
+
+
+### Bug Fixes
+
+* **onboarding:** answer a Document Handler abort with 400, not 500 ([c4473ee](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/c4473eee65011c260caddbd073098cb21e652ae8))
+* **onboarding:** send the abort as errorcode;desc=303, not an invented cause ([0e3beb0](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/0e3beb034ff5a47a4acffcb86191fc9a8f5683ea))
+
 ## [4.23.1](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.23.0...v4.23.1) (2026-08-21)
 
 

package/README.md

@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
 $ sk COMMAND
 running command...
 $ sk (--version)
-@speedkit/cli/4.23.1 linux-x64 node-v22.23.2
+@speedkit/cli/4.23.3 linux-x64 node-v22.23.2
 $ sk --help [COMMAND]
 USAGE
   $ sk COMMAND

package/dist/services/deploy/checks/post-deploy/refresh-deployment-job-check.js

@@ -1,4 +1,3 @@
-import { Set } from "baqend";
 import ApplicationError from "../../../error-handling/error/application-error.js";
 export class RefreshDeploymentJobCheck {
     entityManager;
@@ -12,8 +11,10 @@ export class RefreshDeploymentJobCheck {
             .find()
             .resultList();
         const requiredJobs = ["HTML", "Landing Page", "CSS, JS, Font"];
-        const foundJobNames = new Set(jobs.map((job) => job?.data?.name || " "));
-        const missingRequiredJobs = requiredJobs.filter((job) => !foundJobNames.has(job));
+        // Job names are free text and sometimes suffixed (e.g. "Landing Page (RegExp)"),
+        // so match on the prefix instead of the full name.
+        const foundJobNames = jobs.map((job) => (job?.data?.name || "").trim().toLowerCase());
+        const missingRequiredJobs = requiredJobs.filter((required) => !foundJobNames.some((name) => name.startsWith(required.toLowerCase())));
         // Deployment jobs: soft warning only
         const deploymentJobsMissing = jobs.filter((job) => job.type === "Deploymentjob" && job.created !== true);
         if (deploymentJobsMissing.length > 0) {

package/dist/services/deploy/checks/post-deploy/refresh-deployment-job-check.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/deploy/checks/post-deploy/refresh-deployment-job-check.spec.js

@@ -0,0 +1,33 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { RefreshDeploymentJobCheck } from "./refresh-deployment-job-check.js";
+import ApplicationError from "../../../error-handling/error/application-error.js";
+function entityManagerWithJobs(names) {
+    const jobs = names.map((name) => ({ data: { name }, type: "Refreshjob" }));
+    return {
+        "jobs.Definition": {
+            find: () => ({ resultList: async () => jobs }),
+        },
+    };
+}
+const cli = { writeWarning: () => undefined };
+async function runCheck(names) {
+    try {
+        await new RefreshDeploymentJobCheck(entityManagerWithJobs(names), cli).check();
+    }
+    catch (error) {
+        return error;
+    }
+    return undefined;
+}
+describe("RefreshDeploymentJobCheck", () => {
+    it("accepts jobs whose names carry a suffix", async () => {
+        // As used by zeg and tectake.
+        expect(await runCheck(["HTML", "Landing Page (RegExp)", "CSS, JS, Font"])).to.equal(undefined);
+    });
+    it("reports jobs that are missing entirely", async () => {
+        const error = await runCheck(["HTML", "Images"]);
+        expect(error).to.be.instanceOf(ApplicationError);
+        expect(error.suggestions[0]).to.equal("Missing required jobs: Landing Page, CSS, JS, Font");
+    });
+});

package/dist/services/document-handler-runtime/document-handler-abort.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Baqend's runtime exposes `Abort` as a global to Document Handler code. Throwing it
+ * signals a deliberate stop — a `blacklistHTML` guard, or a pre-render that came back
+ * non-200 — rather than a fault. Baqend extracts the message and answers a Bad Request,
+ * and the service worker falls back to origin.
+ *
+ * The shape follows `typings/Abort/index.d.ts` in the document-handler repository:
+ * `name` is always `"Abort"`, plus a `status` and an optional `data` payload.
+ */
+export declare class DocumentHandlerAbort<T = unknown> extends Error {
+    readonly name = "Abort";
+    status: number;
+    data?: T;
+    /**
+     * Creates a Document Handler abort.
+     *
+     * @param message - Reason the Document Handler stopped.
+     * @param data - Optional abort payload.
+     */
+    constructor(message?: string, data?: T);
+}
+/**
+ * Status code Baqend answers a Document Handler abort with. It must stay below 500:
+ * the service worker treats 5xx from the Asset API as an infrastructure failure and
+ * disconnects Speed Kit, while a client error is classified from `server-timing`.
+ */
+export declare const ABORT_STATUS_CODE = 400;
+/**
+ * Speed Kit error code for a Document Handler abort. Baqend reports the numeric code,
+ * not a cause name, and the backend resolves 303 to `ServerDocumentHandlerAbort`.
+ *
+ * Sibling code 314 is `ServerDocumentHandlerError`, which is what a Document Handler
+ * that throws an ordinary error produces. Keeping the two apart is the point of this
+ * module.
+ */
+export declare const ABORT_ERROR_CODE = "303";
+/**
+ * `server-timing` value that makes the service worker classify a response as an abort.
+ *
+ * Only the `errorcode` metric is sent, which is what Baqend sends. The service worker
+ * reads `errorCause` and `errorcode` separately and builds the cause as
+ * `` `${errorCause?.desc || ClientError}${errorCode ? `-${errorCode.desc}` : ''}` ``
+ * (`AssetAPIHandler.ts:200-205`). With no `errorCause` metric it therefore reports
+ * `ClientError-303`, and the cause name is resolved from the code further downstream.
+ * Sending an `errorCause` metric instead would invent a cause the backend never sends.
+ */
+export declare const ABORT_SERVER_TIMING = "errorcode;desc=303";
+/**
+ * Whether an error is a Document Handler abort rather than a failure.
+ *
+ * Checks the `name` marker instead of `instanceof`: the error is constructed inside a
+ * `vm` context and is re-wrapped by `DocumentHandlerTransformError` on the way out, so
+ * neither the realm nor the prototype chain survives reliably. `isAbort` covers the
+ * wrapped case.
+ *
+ * @param error - Error to classify.
+ */
+export declare function isDocumentHandlerAbort(error?: Error): boolean;

package/dist/services/document-handler-runtime/document-handler-abort.js

@@ -0,0 +1,66 @@
+/**
+ * Baqend's runtime exposes `Abort` as a global to Document Handler code. Throwing it
+ * signals a deliberate stop — a `blacklistHTML` guard, or a pre-render that came back
+ * non-200 — rather than a fault. Baqend extracts the message and answers a Bad Request,
+ * and the service worker falls back to origin.
+ *
+ * The shape follows `typings/Abort/index.d.ts` in the document-handler repository:
+ * `name` is always `"Abort"`, plus a `status` and an optional `data` payload.
+ */
+export class DocumentHandlerAbort extends Error {
+    name = "Abort";
+    status = ABORT_STATUS_CODE;
+    data;
+    /**
+     * Creates a Document Handler abort.
+     *
+     * @param message - Reason the Document Handler stopped.
+     * @param data - Optional abort payload.
+     */
+    constructor(message, data) {
+        super(message);
+        this.data = data;
+    }
+}
+/**
+ * Status code Baqend answers a Document Handler abort with. It must stay below 500:
+ * the service worker treats 5xx from the Asset API as an infrastructure failure and
+ * disconnects Speed Kit, while a client error is classified from `server-timing`.
+ */
+export const ABORT_STATUS_CODE = 400;
+/**
+ * Speed Kit error code for a Document Handler abort. Baqend reports the numeric code,
+ * not a cause name, and the backend resolves 303 to `ServerDocumentHandlerAbort`.
+ *
+ * Sibling code 314 is `ServerDocumentHandlerError`, which is what a Document Handler
+ * that throws an ordinary error produces. Keeping the two apart is the point of this
+ * module.
+ */
+export const ABORT_ERROR_CODE = "303";
+/**
+ * `server-timing` value that makes the service worker classify a response as an abort.
+ *
+ * Only the `errorcode` metric is sent, which is what Baqend sends. The service worker
+ * reads `errorCause` and `errorcode` separately and builds the cause as
+ * `` `${errorCause?.desc || ClientError}${errorCode ? `-${errorCode.desc}` : ''}` ``
+ * (`AssetAPIHandler.ts:200-205`). With no `errorCause` metric it therefore reports
+ * `ClientError-303`, and the cause name is resolved from the code further downstream.
+ * Sending an `errorCause` metric instead would invent a cause the backend never sends.
+ */
+export const ABORT_SERVER_TIMING = `errorcode;desc=${ABORT_ERROR_CODE}`;
+/**
+ * Whether an error is a Document Handler abort rather than a failure.
+ *
+ * Checks the `name` marker instead of `instanceof`: the error is constructed inside a
+ * `vm` context and is re-wrapped by `DocumentHandlerTransformError` on the way out, so
+ * neither the realm nor the prototype chain survives reliably. `isAbort` covers the
+ * wrapped case.
+ *
+ * @param error - Error to classify.
+ */
+export function isDocumentHandlerAbort(error) {
+    if (!error) {
+        return false;
+    }
+    return (error.name === "Abort" || error.isAbort === true);
+}

package/dist/services/document-handler-runtime/document-handler-abort.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/document-handler-runtime/document-handler-abort.spec.js

@@ -0,0 +1,84 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { ABORT_ERROR_CODE, ABORT_SERVER_TIMING, ABORT_STATUS_CODE, DocumentHandlerAbort, isDocumentHandlerAbort, } from "./document-handler-abort.js";
+import { DocumentHandlerTransformError } from "../onboarding/error/document-handler-transform-error.js";
+/**
+ * Mirrors the service worker's `parseServerTimingHeader`, so the header this module
+ * emits is asserted against the parser that has to read it.
+ */
+function parseServerTiming(header) {
+    const metrics = {};
+    header.split(",").forEach((metric) => {
+        const key = metric.includes(";") ? metric.trim().split(";")[0] : metric;
+        const descMatch = metric.match(/desc=([^;]*)/);
+        metrics[key] = { desc: descMatch ? descMatch[1] : "" };
+    });
+    return metrics;
+}
+/**
+ * Mirrors how the service worker builds the response cause in
+ * `AssetAPIHandler.ts:200-205`, to prove which cause the emitted header produces.
+ */
+function composeResponseCause(header) {
+    const metrics = parseServerTiming(header);
+    const errorCode = metrics.errorcode;
+    const errorCodeString = errorCode ? `-${errorCode.desc}` : "";
+    return `${metrics.errorCause?.desc || "ClientError"}${errorCodeString}`;
+}
+describe("DocumentHandlerAbort", () => {
+    it("matches the runtime contract the Document Handler expects", () => {
+        const abort = new DocumentHandlerAbort("blacklisted", { url: "/a" });
+        expect(abort.name).to.equal("Abort");
+        expect(abort.message).to.equal("blacklisted");
+        expect(abort.status).to.equal(ABORT_STATUS_CODE);
+        expect(abort.data).to.deep.equal({ url: "/a" });
+        expect(abort).to.be.instanceOf(Error);
+    });
+    it("keeps the abort status below the range that disconnects Speed Kit", () => {
+        expect(ABORT_STATUS_CODE).to.be.lessThan(500);
+    });
+});
+describe("isDocumentHandlerAbort", () => {
+    it("recognises an abort by its name marker", () => {
+        expect(isDocumentHandlerAbort(new DocumentHandlerAbort("stop"))).to.equal(true);
+    });
+    it("recognises an abort that only carries the wrapped flag", () => {
+        const wrapped = Object.assign(new Error("stop"), { isAbort: true });
+        expect(isDocumentHandlerAbort(wrapped)).to.equal(true);
+    });
+    it("does not treat an ordinary failure as an abort", () => {
+        expect(isDocumentHandlerAbort(new Error("boom"))).to.equal(false);
+        expect(isDocumentHandlerAbort(undefined)).to.equal(false);
+    });
+});
+describe("DocumentHandlerTransformError", () => {
+    it("carries the abort marker across the wrapper", () => {
+        const wrapped = new DocumentHandlerTransformError(new DocumentHandlerAbort("No category grid"));
+        expect(wrapped.isAbort).to.equal(true);
+        expect(wrapped.message).to.equal("No category grid");
+        expect(isDocumentHandlerAbort(wrapped)).to.equal(true);
+    });
+    it("leaves an ordinary failure unmarked", () => {
+        const wrapped = new DocumentHandlerTransformError(new Error("boom"));
+        expect(wrapped.isAbort).to.equal(false);
+        expect(isDocumentHandlerAbort(wrapped)).to.equal(false);
+    });
+});
+describe("ABORT_SERVER_TIMING", () => {
+    it("sends the error code under the metric name Baqend uses", () => {
+        const metrics = parseServerTiming(ABORT_SERVER_TIMING);
+        expect(metrics.errorcode.desc).to.equal(ABORT_ERROR_CODE);
+    });
+    it("sends no errorCause metric, which Baqend does not send either", () => {
+        expect(parseServerTiming(ABORT_SERVER_TIMING).errorCause).to.equal(undefined);
+    });
+    it("makes the service worker report ClientError-303", () => {
+        expect(composeResponseCause(ABORT_SERVER_TIMING)).to.equal("ClientError-303");
+    });
+    it("is matched by the prewarm error-code selector when a metric follows", () => {
+        // TIMING_HEADER_ERROR_CODE_SELECTOR expects a trailing comma, as production
+        // sends further metrics after the code.
+        const [, code] = `${ABORT_SERVER_TIMING},dur=0`.match(/errorcode;desc=([^,]*),/) || [];
+        expect(code).to.equal(ABORT_ERROR_CODE);
+    });
+});

package/dist/services/document-handler-runtime/document-handler-server.js

@@ -8,6 +8,7 @@ import { INTEGRATION_FILES } from "../../models/files.js";
 import fetch from "node-fetch";
 import { Request } from "./server/request.js";
 import { DocumentHandlerResponse } from "./server/document-handler-response.js";
+import { DocumentHandlerAbort } from "./document-handler-abort.js";
 import { safe } from "../../helpers/safe.js";
 import { VmEmptyResponseError } from "../onboarding/error/vm-empty-response-error.js";
 import { DocumentHandlerTransformError } from "../onboarding/error/document-handler-transform-error.js";
@@ -46,7 +47,7 @@ export class DocumentHandlerServer {
             skInternalResponse,
             skInternalHtml: "",
             skInternalError: {},
-            Abort: Error,
+            Abort: DocumentHandlerAbort,
             APP: this.customerConfig.app,
             DYNAMIC_FETCHER: await this.getDynamicFetcher(),
             DYNAMIC_FETCHER_CONFIG: await this.getDynamicFetcherConfig(),

package/dist/services/document-handler-runtime/templates/test.js

@@ -10,7 +10,9 @@ const database = require('./src/database-mock');
 const documentHandler = require('./src/testDocumentHandler');
 const fs = require('fs');
 const {resolve} = require("path");
-global.Abort = Error;
+global.Abort = class Abort extends Error {
+  constructor(message, data) { super(message); this.name = 'Abort'; this.status = 400; this.data = data; }
+};
 
 const url = '{{domain}}';
 const file = '{{name}}';

package/dist/services/onboarding/error/document-handler-transform-error.d.ts

@@ -1,3 +1,9 @@
 export declare class DocumentHandlerTransformError extends Error {
+    /**
+     * True when the Document Handler stopped deliberately by throwing `Abort`, so the
+     * caller can answer with a client error instead of a 500. The wrapper drops the
+     * original prototype, so the flag has to be carried explicitly.
+     */
+    readonly isAbort: boolean;
     constructor(error: Error);
 }

package/dist/services/onboarding/error/document-handler-transform-error.js

@@ -1,7 +1,15 @@
+import { isDocumentHandlerAbort } from "../../document-handler-runtime/document-handler-abort.js";
 export class DocumentHandlerTransformError extends Error {
+    /**
+     * True when the Document Handler stopped deliberately by throwing `Abort`, so the
+     * caller can answer with a client error instead of a 500. The wrapper drops the
+     * original prototype, so the flag has to be carried explicitly.
+     */
+    isAbort;
     constructor(error) {
         super(error.message);
         this.stack = error.stack;
         this.cause = error.cause;
+        this.isAbort = isDocumentHandlerAbort(error);
     }
 }

package/dist/services/onboarding/virtual-orestes-app/index.d.ts

@@ -52,6 +52,14 @@ export declare class VirtualOrestesApp {
     private recordLocalCacheError;
     private clearLocalCacheError;
     private emitLocalCacheErrors;
+    /**
+     * Answers a Document Handler abort the way Baqend does: a Bad Request carrying the
+     * Speed Kit error code in `server-timing`. The service worker reports
+     * `ClientError-303` and falls back to origin, and the backend resolves 303 to
+     * `ServerDocumentHandlerAbort`. Answering 500 instead makes the service worker treat
+     * the page as an infrastructure failure and disconnect Speed Kit.
+     */
+    private returnAbortResponse;
     private returnErrorResponse;
     private convertResponseHeadersToOrestesFormat;
     private returnRedirect;

package/dist/services/onboarding/virtual-orestes-app/index.js

@@ -1,4 +1,5 @@
 import { BaqendResponse } from "../browser/baqend-response.js";
+import { ABORT_SERVER_TIMING, ABORT_STATUS_CODE, isDocumentHandlerAbort, } from "../../document-handler-runtime/document-handler-abort.js";
 import { safe } from "../../../helpers/safe.js";
 import { META_CONTENT_TYPE_REGEX, } from "../onboarding-model.js";
 import iconv from "iconv-lite";
@@ -142,7 +143,10 @@ export class VirtualOrestesApp {
         }
         const customResponse = await safe(this.documentHandler.transform(`text/html;charset=${textEncoding}`, responseContent, variation, originUrl, this.convertResponseHeadersToOrestesFormat(response)));
         if (customResponse.success === false) {
-            this.recordLocalCacheError(originUrl, requestUrl, variation, customResponse);
+            // An abort is a decision, not a fault, so it must not surface as a cache error.
+            if (!isDocumentHandlerAbort(customResponse.errorObj)) {
+                this.recordLocalCacheError(originUrl, requestUrl, variation, customResponse);
+            }
             return this.returnErrorResponse(customResponse, customHeaders);
         }
         this.clearLocalCacheError(originUrl, variation);
@@ -231,7 +235,23 @@ export class VirtualOrestesApp {
             data: [...this.localCacheErrors.values()],
         });
     }
+    /**
+     * Answers a Document Handler abort the way Baqend does: a Bad Request carrying the
+     * Speed Kit error code in `server-timing`. The service worker reports
+     * `ClientError-303` and falls back to origin, and the backend resolves 303 to
+     * `ServerDocumentHandlerAbort`. Answering 500 instead makes the service worker treat
+     * the page as an infrastructure failure and disconnect Speed Kit.
+     */
+    returnAbortResponse(customResponse, customHeaders) {
+        const message = customResponse.error;
+        this.cli.writeWarning(`[VirtualOrestes]: Document Handler aborted: ${message}`);
+        customHeaders.push({ name: "x-error", value: message }, { name: "server-timing", value: ABORT_SERVER_TIMING });
+        return new BaqendResponse(message, null, customHeaders, ABORT_STATUS_CODE);
+    }
     returnErrorResponse(customResponse, customHeaders) {
+        if (isDocumentHandlerAbort(customResponse.errorObj)) {
+            return this.returnAbortResponse(customResponse, customHeaders);
+        }
         const message = `Could not transform html: - ${customResponse.error}`;
         this.cli.writeError(`[VirtualOrestes]: ${message}`);
         this.cli.comment(customResponse.errorObj.stack);

package/oclif.manifest.json

@@ -1220,5 +1220,5 @@
       ]
     }
   },
-  "version": "4.23.1"
+  "version": "4.23.3"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@speedkit/cli",
   "description": "Speed Kit CLI",
-  "version": "4.23.1",
+  "version": "4.23.3",
   "author": {
     "name": "Baqend.com",
     "email": "info@baqend.com"