@speedkit/cli 4.24.2 → 4.25.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+# [4.25.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.24.2...v4.25.0) (2026-09-08)
+
+
+### Bug Fixes
+
+* **revalidate:** accept the 202 the API answers for a submitted job ([a3ba85e](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/a3ba85e454b51740bfa0b983e41f828b8ac86598))
+
+
+### Features
+
+* **revalidate:** add sk revalidate for post-go-live purges ([5a08843](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/5a0884344bc0dfd007b8eebdb2e70cd90ae068aa))
+* **revalidate:** confirm a job above 100 assets ([f64158f](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/f64158f56d1ba31b21d44051ecf3f87078aaa8e1))
+
+
+### Performance Improvements
+
+* **revalidate:** keep the dry-run prefix filter on the index ([97f057c](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/97f057cfaae8c59b2d888a9fdfee04648c20d046))
+
 ## [4.24.2](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.24.1...v4.24.2) (2026-09-03)
 
 

package/README.md

@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
 $ sk COMMAND
 running command...
 $ sk (--version)
-@speedkit/cli/4.24.2 linux-x64 node-v22.23.2
+@speedkit/cli/4.25.0 linux-x64 node-v22.23.2
 $ sk --help [COMMAND]
 USAGE
   $ sk COMMAND
@@ -92,6 +92,7 @@ By either...
 * [`sk param-diff PAGEURL`](#sk-param-diff-pageurl)
 * [`sk prewarm APP PATH`](#sk-prewarm-app-path)
 * [`sk pull CUSTOMERPATH`](#sk-pull-customerpath)
+* [`sk revalidate APP`](#sk-revalidate-app)
 * [`sk wpt-launcher URLS TESTID`](#sk-wpt-launcher-urls-testid)
 
 ## `sk auto-prewarm CUSTOMERPATH`
@@ -746,6 +747,49 @@ EXAMPLES
   $ sk pull customers/decathlon.de -c production
 ```
 
+## `sk revalidate APP`
+
+Purge or refresh cached assets by prefix and query. Run it after a config that narrows scope goes live, so returning visitors stop receiving the cached HTML.
+
+```
+USAGE
+  $ sk revalidate APP [--pattern <value>...] [--prefix <value>...] [--query <value>] [--type
+    REFRESH|INSTANT|DEPLOYMENT|PURGE] [-d] [--wait] [--yes] [-q]
+
+ARGUMENTS
+  APP  The customer app name
+
+FLAGS
+  -d, --dryRun              Report the assets the filter selects and exit. Changes nothing.
+  -q, --quiet               less output non interactive
+      --pattern=<value>...  URL pattern to purge, as a regex anchored at the scheme — mirror what the config excludes,
+                            e.g. "^https://www.example.com/en/.*-c1234$". Repeatable. The command derives the prefix the
+                            API requires from the pattern's literal head, and MongoDB reads that same literal as index
+                            bounds.
+      --prefix=<value>...   URL prefix, matched against the start of the cached URL. Derived from --pattern by default;
+                            state it only to override that, or to purge a whole path without a pattern.
+      --query=<value>       Raw MongoDB query on the asset fields, as JSON. An escape hatch for a rule --pattern cannot
+                            express, such as a condition on another field. It replaces the query --pattern would build.
+      --type=<option>       [default: PURGE] PURGE drops the entries and does not rebuild them, which is what an
+                            out-of-scope URL needs.
+                            <options: REFRESH|INSTANT|DEPLOYMENT|PURGE>
+      --wait                Poll the job until it finishes.
+      --yes                 Skip the confirmation a job above 100 assets asks for. Required in a non-interactive shell.
+
+DESCRIPTION
+  Purge or refresh cached assets by prefix and query. Run it after a config that narrows scope goes live, so returning
+  visitors stop receiving the cached HTML.
+
+EXAMPLES
+  $ sk revalidate <app> --pattern <regex> [--pattern <regex>] [--dryRun] [--wait]
+
+  $ sk revalidate decathlon --pattern '^https://www\\.decathlon\\.de/damen/.*-c(?:1234|5678)(?:/|\\?|$)' --dryRun
+
+  $ sk revalidate decathlon --pattern '^https://www\\.decathlon\\.de/damen/.*-c1234(?:/|\\?|$)' --wait
+
+  $ sk revalidate decathlon --prefix https://www.decathlon.de/damen/ --dryRun
+```
+
 ## `sk wpt-launcher URLS TESTID`
 
 Analyze the performance impact that Speed Kit has compared to the original version.

package/dist/commands/revalidate.d.ts

@@ -0,0 +1,21 @@
+import { Command } from "@oclif/core";
+export default class Revalidate extends Command {
+    static description: string;
+    static args: {
+        app: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        pattern: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        prefix: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        query: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        type: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        dryRun: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        quiet: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static examples: string[];
+    run(): Promise<void>;
+    /** A malformed query would otherwise reach the backend as an opaque 400. */
+    private parseQuery;
+}

package/dist/commands/revalidate.js

@@ -0,0 +1,128 @@
+import { Args, Command, Flags } from "@oclif/core";
+import { CLIParameters, CLIParametersChar, CLIParametersExample, } from "../models/cli-parameters.js";
+import { isNonInteractive } from "../helpers/environment.js";
+import { CONFIRMATION_THRESHOLD, REVALIDATE_TYPES, RevalidateContext, RevalidateFactory, } from "../services/revalidate/index.js";
+const SAMPLE_SIZE = 10;
+export default class Revalidate extends Command {
+    static description = "Purge or refresh cached assets by prefix and query. Run it after a config that narrows scope goes live, so returning visitors stop receiving the cached HTML.";
+    static args = {
+        [CLIParameters.AppName]: Args.string({
+            name: CLIParameters.AppName,
+            required: true,
+            description: "The customer app name",
+        }),
+    };
+    static flags = {
+        ["pattern"]: Flags.string({
+            multiple: true,
+            description: 'URL pattern to purge, as a regex anchored at the scheme — mirror what the config excludes, e.g. "^https://www.example.com/en/.*-c1234$". Repeatable. The command derives the prefix the API requires from the pattern\'s literal head, and MongoDB reads that same literal as index bounds.',
+        }),
+        ["prefix"]: Flags.string({
+            multiple: true,
+            description: "URL prefix, matched against the start of the cached URL. Derived from --pattern by default; state it only to override that, or to purge a whole path without a pattern.",
+        }),
+        ["query"]: Flags.string({
+            description: "Raw MongoDB query on the asset fields, as JSON. An escape hatch for a rule --pattern cannot express, such as a condition on another field. It replaces the query --pattern would build.",
+        }),
+        ["type"]: Flags.string({
+            options: [...REVALIDATE_TYPES],
+            default: "PURGE",
+            description: "PURGE drops the entries and does not rebuild them, which is what an out-of-scope URL needs.",
+        }),
+        [CLIParameters.DryRun]: Flags.boolean({
+            char: CLIParametersChar.DryRun,
+            default: false,
+            description: "Report the assets the filter selects and exit. Changes nothing.",
+        }),
+        ["wait"]: Flags.boolean({
+            default: false,
+            description: "Poll the job until it finishes.",
+        }),
+        ["yes"]: Flags.boolean({
+            default: false,
+            description: `Skip the confirmation a job above ${CONFIRMATION_THRESHOLD} assets asks for. Required in a non-interactive shell.`,
+        }),
+        [CLIParameters.Quiet]: Flags.boolean({
+            char: CLIParametersChar.Quiet,
+            default: false,
+            description: "less output non interactive",
+        }),
+    };
+    static examples = [
+        `$ sk revalidate <${CLIParameters.AppName}> --pattern <regex> [--pattern <regex>] [--${CLIParameters.DryRun}] [--wait]`,
+        `$ sk revalidate ${CLIParametersExample.AppName} --pattern '^https://www\\\\.decathlon\\\\.de/damen/.*-c(?:1234|5678)(?:/|\\\\?|$)' --${CLIParameters.DryRun}`,
+        `$ sk revalidate ${CLIParametersExample.AppName} --pattern '^https://www\\\\.decathlon\\\\.de/damen/.*-c1234(?:/|\\\\?|$)' --wait`,
+        `$ sk revalidate ${CLIParametersExample.AppName} --prefix ${CLIParametersExample.PageUrl}damen/ --${CLIParameters.DryRun}`,
+    ];
+    async run() {
+        const { args, flags } = await this.parse(Revalidate);
+        const app = args[CLIParameters.AppName];
+        const service = new RevalidateFactory(new RevalidateContext(app, flags[CLIParameters.Quiet])).getService();
+        const patterns = flags["pattern"] ?? [];
+        const prefixes = flags["prefix"] ?? [];
+        if (!patterns.length && !prefixes.length) {
+            this.error("state what to purge: pass --pattern, or --prefix", {
+                exit: 1,
+            });
+        }
+        const filter = service.buildFilter(patterns, prefixes);
+        if (flags["query"]) {
+            filter.query = this.parseQuery(flags["query"]);
+        }
+        service.assertFilter(filter);
+        this.log(`prefixes: ${filter.prefixes.join(", ")}`);
+        const preview = await service.preview(filter, SAMPLE_SIZE);
+        this.log(`filter selects ${preview.count} asset(s)`);
+        for (const url of preview.sample) {
+            this.log(`  ${url}`);
+        }
+        if (preview.count > preview.sample.length) {
+            this.log(`  … ${preview.count - preview.sample.length} more`);
+        }
+        if (flags[CLIParameters.DryRun]) {
+            this.log("dry run — nothing was purged");
+            return;
+        }
+        if (preview.count === 0) {
+            this.log("nothing to do — the filter selects no asset");
+            return;
+        }
+        const type = flags["type"];
+        if (preview.count > CONFIRMATION_THRESHOLD && !flags["yes"]) {
+            if (isNonInteractive()) {
+                this.error(`${preview.count} assets exceed the ${CONFIRMATION_THRESHOLD}-asset threshold, and this shell cannot ask`, {
+                    exit: 1,
+                    suggestions: [
+                        "Check the --dryRun output, then re-run with --yes.",
+                        "Or narrow --pattern until it takes only what the config excludes.",
+                    ],
+                });
+            }
+            if (!(await service.confirmLargeJob(preview.count, type))) {
+                this.log("aborted — nothing was purged");
+                return;
+            }
+        }
+        const statusId = await service.submit(filter, type);
+        this.log(`submitted ${type} job ${statusId}`);
+        if (!flags["wait"]) {
+            return;
+        }
+        const status = await service.waitFor(statusId);
+        this.log(`assets ${status.assetCount ?? 0}, refreshed ${status.refreshedCount ?? 0}, changed ${status.changedCount ?? 0}`);
+        if (status.state !== "FINISHED") {
+            this.error(`job ${statusId} ended as ${status.state}: ${status.error}`);
+        }
+    }
+    /** A malformed query would otherwise reach the backend as an opaque 400. */
+    parseQuery(raw) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            this.error(`--query is not valid JSON: ${error.message}`, {
+                exit: 1,
+            });
+        }
+    }
+}

package/dist/services/revalidate/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./revalidate-model.js";
+export * from "./revalidate-service.js";
+export * from "./revalidate-factory.js";

package/dist/services/revalidate/index.js

@@ -0,0 +1,3 @@
+export * from "./revalidate-model.js";
+export * from "./revalidate-service.js";
+export * from "./revalidate-factory.js";

package/dist/services/revalidate/revalidate-factory.d.ts

@@ -0,0 +1,7 @@
+import { RevalidateContextInterface } from "./revalidate-model.js";
+import { RevalidateService } from "./revalidate-service.js";
+export declare class RevalidateFactory {
+    private context;
+    constructor(context: RevalidateContextInterface);
+    getService(): RevalidateService;
+}

package/dist/services/revalidate/revalidate-factory.js

@@ -0,0 +1,14 @@
+import { CliContext, CliServiceFactory } from "../cli/index.js";
+import { ConfigApiContext, ConfigApiServiceFactory, } from "../config-api/index.js";
+import { RevalidateService } from "./revalidate-service.js";
+export class RevalidateFactory {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    getService() {
+        const cli = new CliServiceFactory(new CliContext(this.context.quiet)).getService();
+        const configApi = new ConfigApiServiceFactory(new ConfigApiContext(this.context.app)).getService();
+        return new RevalidateService(configApi, cli, this.context.app);
+    }
+}

package/dist/services/revalidate/revalidate-model.d.ts

@@ -0,0 +1,44 @@
+export declare const REVALIDATE_TYPES: readonly ["REFRESH", "INSTANT", "DEPLOYMENT", "PURGE"];
+export type RevalidateType = (typeof REVALIDATE_TYPES)[number];
+/**
+ * The asset table the dry run reads. It holds one entry per cached asset, so the
+ * same filter that the job applies also selects the rows to report.
+ */
+export declare const ASSET_TABLE = "speedKit.Asset";
+/**
+ * Above this many assets the command asks before it purges. A filter that takes
+ * more than a page of assets is usually a filter mistake, and a purge cannot be
+ * undone — the entries are gone until traffic caches them again.
+ */
+export declare const CONFIRMATION_THRESHOLD = 100;
+/**
+ * Scope of a revalidation job.
+ *
+ * `prefixes` is mandatory: the backend rejects a filter without it. It bounds which
+ * URLs the job examines. `query` refines that set, and it takes a MongoDB query, so
+ * it can express a rule that a prefix cannot — a trailing category id, for example.
+ */
+export interface RevalidateFilterInterface {
+    prefixes: string[];
+    query?: Record<string, unknown>;
+}
+export interface RevalidateJobStatusInterface {
+    state: "CREATED" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "SCHEDULED" | "DEFERRED";
+    assetCount?: number;
+    refreshedCount?: number;
+    changedCount?: number;
+    error?: string | null;
+}
+export interface RevalidatePreviewInterface {
+    count: number;
+    sample: string[];
+}
+export interface RevalidateContextInterface {
+    app: string;
+    quiet: boolean;
+}
+export declare class RevalidateContext implements RevalidateContextInterface {
+    readonly app: string;
+    readonly quiet: boolean;
+    constructor(app: string, quiet?: boolean);
+}

package/dist/services/revalidate/revalidate-model.js

@@ -0,0 +1,25 @@
+export const REVALIDATE_TYPES = [
+    "REFRESH",
+    "INSTANT",
+    "DEPLOYMENT",
+    "PURGE",
+];
+/**
+ * The asset table the dry run reads. It holds one entry per cached asset, so the
+ * same filter that the job applies also selects the rows to report.
+ */
+export const ASSET_TABLE = "speedKit.Asset";
+/**
+ * Above this many assets the command asks before it purges. A filter that takes
+ * more than a page of assets is usually a filter mistake, and a purge cannot be
+ * undone — the entries are gone until traffic caches them again.
+ */
+export const CONFIRMATION_THRESHOLD = 100;
+export class RevalidateContext {
+    app;
+    quiet;
+    constructor(app, quiet = false) {
+        this.app = app;
+        this.quiet = quiet;
+    }
+}

package/dist/services/revalidate/revalidate-service.d.ts

@@ -0,0 +1,58 @@
+import { CliService } from "../cli/index.js";
+import { ConfigApiService } from "../config-api/index.js";
+import { RevalidateFilterInterface, RevalidateJobStatusInterface, RevalidatePreviewInterface, RevalidateType } from "./revalidate-model.js";
+/**
+ * Reads the literal head of an anchored pattern, which is the prefix the job needs.
+ *
+ * This is the same text MongoDB turns into index bounds, so deriving the prefix
+ * here keeps the two in step: the caller states the pattern once, and the prefix
+ * cannot drift from it. An escaped character counts as literal, so `\.` yields `.`
+ * and the host survives. The walk stops at the first metacharacter.
+ */
+export declare function derivePrefix(pattern: string): string;
+export declare class RevalidateService {
+    private readonly configApi;
+    private readonly cli;
+    private readonly app;
+    constructor(configApi: ConfigApiService, cli: CliService, app: string);
+    /**
+     * Builds the filter the API expects from the patterns the caller stated, and
+     * derives the mandatory prefixes from them.
+     */
+    buildFilter(patterns: string[], explicitPrefixes: string[]): RevalidateFilterInterface;
+    /**
+     * Rejects a filter the backend would reject, before the request goes out. The
+     * check is cheap here and the server-side error does not say which field is at
+     * fault.
+     */
+    assertFilter(filter: RevalidateFilterInterface): void;
+    /**
+     * Reports what the job would take. The Refresh API has no preview mode, so this
+     * runs the job's own filter against the asset table instead.
+     */
+    preview(filter: RevalidateFilterInterface, sampleSize: number): Promise<RevalidatePreviewInterface>;
+    /** Asks before a purge that takes more assets than the threshold allows. */
+    confirmLargeJob(count: number, type: RevalidateType): Promise<boolean>;
+    /** Submits the job and returns its status id. */
+    submit(filter: RevalidateFilterInterface, type: RevalidateType): Promise<string>;
+    status(statusId: string): Promise<RevalidateJobStatusInterface>;
+    /**
+     * Issues the request itself instead of going through the shared client. A
+     * submitted job answers 202, and the shared client reports every status other
+     * than 200 as an error — which turns an accepted job into "Error: Accepted".
+     */
+    private request;
+    /** Polls until the job reaches a terminal state, and reports each state change. */
+    waitFor(statusId: string): Promise<RevalidateJobStatusInterface>;
+    /**
+     * Mirrors the job's filter as one MongoDB query, so the dry run reports the set
+     * the job takes and not every URL the query alone would match.
+     *
+     * Each prefix becomes its own anchored expression, and they combine with `$or`.
+     * One alternation would read `^(?:a|b)`, whose first character after the anchor
+     * is a metacharacter — MongoDB then extracts no literal prefix and scans the
+     * collection. Some asset tables are far too large for that. `^literal` keeps
+     * each branch on the index.
+     */
+    private toMongoFilter;
+}

package/dist/services/revalidate/revalidate-service.js

@@ -0,0 +1,189 @@
+import ApplicationError from "../error-handling/error/application-error.js";
+import { ASSET_TABLE, } from "./revalidate-model.js";
+const POLL_INTERVAL = 3000;
+const TERMINAL_STATES = new Set(["FINISHED", "ERROR", "CANCELLED"]);
+/** Escapes a prefix so it can go into the dry-run query as a literal. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const REGEXP_METACHARACTERS = new Set([
+    ".",
+    "*",
+    "+",
+    "?",
+    "$",
+    "{",
+    "}",
+    "(",
+    ")",
+    "|",
+    "[",
+    "]",
+]);
+/**
+ * Reads the literal head of an anchored pattern, which is the prefix the job needs.
+ *
+ * This is the same text MongoDB turns into index bounds, so deriving the prefix
+ * here keeps the two in step: the caller states the pattern once, and the prefix
+ * cannot drift from it. An escaped character counts as literal, so `\.` yields `.`
+ * and the host survives. The walk stops at the first metacharacter.
+ */
+export function derivePrefix(pattern) {
+    if (!pattern.startsWith("^")) {
+        return "";
+    }
+    let prefix = "";
+    for (let index = 1; index < pattern.length; index++) {
+        const character = pattern[index];
+        if (character === "\\") {
+            const escaped = pattern[index + 1];
+            if (escaped === undefined)
+                break;
+            prefix += escaped;
+            index++;
+            continue;
+        }
+        if (REGEXP_METACHARACTERS.has(character))
+            break;
+        prefix += character;
+    }
+    return prefix;
+}
+export class RevalidateService {
+    configApi;
+    cli;
+    app;
+    constructor(configApi, cli, app) {
+        this.configApi = configApi;
+        this.cli = cli;
+        this.app = app;
+    }
+    /**
+     * Builds the filter the API expects from the patterns the caller stated, and
+     * derives the mandatory prefixes from them.
+     */
+    buildFilter(patterns, explicitPrefixes) {
+        if (!patterns.length) {
+            return { prefixes: explicitPrefixes };
+        }
+        for (const pattern of patterns) {
+            const derived = derivePrefix(pattern);
+            if (!derived.startsWith("http")) {
+                throw new ApplicationError(`cannot derive a prefix from the pattern "${pattern}"`, [
+                    "Anchor the pattern at the scheme, so its literal head is a URL prefix.",
+                    'Example: "^https://www.example.com/en/.*-c1234$".',
+                    "MongoDB reads that same literal as index bounds, so an unanchored pattern would also scan the table.",
+                    "Pass --prefix yourself if the pattern genuinely cannot carry the host.",
+                ]);
+            }
+        }
+        const clauses = patterns.map((pattern) => ({ url: { $regex: pattern } }));
+        return {
+            prefixes: explicitPrefixes.length
+                ? explicitPrefixes
+                : patterns.map((pattern) => derivePrefix(pattern)),
+            query: clauses.length === 1 ? clauses[0] : { $or: clauses },
+        };
+    }
+    /**
+     * Rejects a filter the backend would reject, before the request goes out. The
+     * check is cheap here and the server-side error does not say which field is at
+     * fault.
+     */
+    assertFilter(filter) {
+        if (!filter.prefixes?.length) {
+            throw new ApplicationError("a revalidation filter needs at least one prefix", [
+                "The backend rejects a filter without prefixes.",
+                "Pass --pattern, which derives the prefix, or --prefix to state one.",
+            ]);
+        }
+        for (const prefix of filter.prefixes) {
+            if (!prefix.startsWith("http")) {
+                throw new ApplicationError(`prefix "${prefix}" is not a full URL`, [
+                    "A prefix matches the stored URL, so it carries the scheme and the host.",
+                ]);
+            }
+        }
+    }
+    /**
+     * Reports what the job would take. The Refresh API has no preview mode, so this
+     * runs the job's own filter against the asset table instead.
+     */
+    async preview(filter, sampleSize) {
+        const entityManager = await this.configApi.client.getEntityManager();
+        const mongoFilter = this.toMongoFilter(filter);
+        const count = await entityManager[ASSET_TABLE].find()
+            .where(mongoFilter)
+            .count();
+        const sample = await entityManager[ASSET_TABLE].find()
+            .where(mongoFilter)
+            .limit(sampleSize)
+            .resultList();
+        return {
+            count,
+            sample: sample.map((asset) => asset.url),
+        };
+    }
+    /** Asks before a purge that takes more assets than the threshold allows. */
+    async confirmLargeJob(count, type) {
+        return this.cli.confirm(`${type} ${count} assets? They stay out of the cache until traffic fills it again.`, false);
+    }
+    /** Submits the job and returns its status id. */
+    async submit(filter, type) {
+        const response = await this.request(`https://${this.app}.app.baqend.com/v1/asset/revalidate`, {
+            method: "POST",
+            body: JSON.stringify({ type, filter, triggeredBy: "sk-cli" }),
+        });
+        return response.statusId;
+    }
+    async status(statusId) {
+        return this.request(`https://${this.app}.app.baqend.com/v1/asset/revalidate/${statusId}`);
+    }
+    /**
+     * Issues the request itself instead of going through the shared client. A
+     * submitted job answers 202, and the shared client reports every status other
+     * than 200 as an error — which turns an accepted job into "Error: Accepted".
+     */
+    async request(url, extension = {}) {
+        const requestInit = await this.configApi.client.createRequest(extension);
+        const response = await fetch(url, requestInit);
+        if (!response.ok) {
+            const body = await response.text();
+            throw new ApplicationError(`the revalidation API answered ${response.status} ${response.statusText}`, [body.slice(0, 400)]);
+        }
+        const body = await response.text();
+        return (body ? JSON.parse(body) : {});
+    }
+    /** Polls until the job reaches a terminal state, and reports each state change. */
+    async waitFor(statusId) {
+        let lastState = "";
+        for (;;) {
+            const status = await this.status(statusId);
+            if (status.state !== lastState) {
+                this.cli.write(`revalidation job ${statusId}: ${status.state}`);
+                lastState = status.state;
+            }
+            if (TERMINAL_STATES.has(status.state)) {
+                return status;
+            }
+            await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+        }
+    }
+    /**
+     * Mirrors the job's filter as one MongoDB query, so the dry run reports the set
+     * the job takes and not every URL the query alone would match.
+     *
+     * Each prefix becomes its own anchored expression, and they combine with `$or`.
+     * One alternation would read `^(?:a|b)`, whose first character after the anchor
+     * is a metacharacter — MongoDB then extracts no literal prefix and scans the
+     * collection. Some asset tables are far too large for that. `^literal` keeps
+     * each branch on the index.
+     */
+    toMongoFilter(filter) {
+        const prefixClauses = filter.prefixes.map((prefix) => ({
+            url: { $regex: `^${escapeRegExp(prefix)}` },
+        }));
+        const prefixClause = prefixClauses.length === 1 ? prefixClauses[0] : { $or: prefixClauses };
+        return filter.query ? { $and: [prefixClause, filter.query] } : prefixClause;
+    }
+}

package/oclif.manifest.json

@@ -871,6 +871,100 @@
         "pull.js"
       ]
     },
+    "revalidate": {
+      "aliases": [],
+      "args": {
+        "app": {
+          "description": "The customer app name",
+          "name": "app",
+          "required": true
+        }
+      },
+      "description": "Purge or refresh cached assets by prefix and query. Run it after a config that narrows scope goes live, so returning visitors stop receiving the cached HTML.",
+      "examples": [
+        "$ sk revalidate <app> --pattern <regex> [--pattern <regex>] [--dryRun] [--wait]",
+        "$ sk revalidate decathlon --pattern '^https://www\\\\.decathlon\\\\.de/damen/.*-c(?:1234|5678)(?:/|\\\\?|$)' --dryRun",
+        "$ sk revalidate decathlon --pattern '^https://www\\\\.decathlon\\\\.de/damen/.*-c1234(?:/|\\\\?|$)' --wait",
+        "$ sk revalidate decathlon --prefix https://www.decathlon.de/damen/ --dryRun"
+      ],
+      "flags": {
+        "pattern": {
+          "description": "URL pattern to purge, as a regex anchored at the scheme — mirror what the config excludes, e.g. \"^https://www.example.com/en/.*-c1234$\". Repeatable. The command derives the prefix the API requires from the pattern's literal head, and MongoDB reads that same literal as index bounds.",
+          "name": "pattern",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "prefix": {
+          "description": "URL prefix, matched against the start of the cached URL. Derived from --pattern by default; state it only to override that, or to purge a whole path without a pattern.",
+          "name": "prefix",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "query": {
+          "description": "Raw MongoDB query on the asset fields, as JSON. An escape hatch for a rule --pattern cannot express, such as a condition on another field. It replaces the query --pattern would build.",
+          "name": "query",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "type": {
+          "description": "PURGE drops the entries and does not rebuild them, which is what an out-of-scope URL needs.",
+          "name": "type",
+          "default": "PURGE",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "REFRESH",
+            "INSTANT",
+            "DEPLOYMENT",
+            "PURGE"
+          ],
+          "type": "option"
+        },
+        "dryRun": {
+          "char": "d",
+          "description": "Report the assets the filter selects and exit. Changes nothing.",
+          "name": "dryRun",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "wait": {
+          "description": "Poll the job until it finishes.",
+          "name": "wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "description": "Skip the confirmation a job above 100 assets asks for. Required in a non-interactive shell.",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "quiet": {
+          "char": "q",
+          "description": "less output non interactive",
+          "name": "quiet",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "revalidate",
+      "pluginAlias": "@speedkit/cli",
+      "pluginName": "@speedkit/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "revalidate.js"
+      ]
+    },
     "wpt-launcher": {
       "aliases": [],
       "args": {
@@ -1220,5 +1314,5 @@
       ]
     }
   },
-  "version": "4.24.2"
+  "version": "4.25.0"
 }

package/package.json

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