@speedkit/cli 4.21.0 → 4.22.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [4.22.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.21.0...v4.22.0) (2026-08-20)
+
+
+### Bug Fixes
+
+* **customer-config:** contract-check against the CLI's variable inventory ([7ebd2d2](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/7ebd2d28331a59dc3754fa1f6cd859f978febf6c))
+
+
+### Features
+
+* **customer-config:** --mode flag picks the template set ([b471e8b](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/b471e8b8c6de32babfd26f69688409cae04288ae))
+* **customer-config:** graduate an existing pre-PoC config ([28af5e2](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/28af5e2d06c8c9571da3d72563ae229b12f27d56))
+* **customer-config:** pre-poc mode asks only what the baseline needs ([35cbcbd](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/35cbcbd698144ac82dd275dcf63a0e62b03dba24))
+* **customer-config:** render wizard templates from sk-onboarding ([266cbe3](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/266cbe3c68f5e4aafa431e2fa4a5f9311c3e28c9))
+
 # [4.21.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.5...v4.21.0) (2026-08-14)
 
 

package/README.md

@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
 $ sk COMMAND
 running command...
 $ sk (--version)
-@speedkit/cli/4.21.0 linux-x64 node-v22.23.2
+@speedkit/cli/4.22.0 linux-x64 node-v22.23.2
 $ sk --help [COMMAND]
 USAGE
   $ sk COMMAND
@@ -486,13 +486,18 @@ Generates a customer config guided by a wizard 🧙‍
 
 ```
 USAGE
-  $ sk generate-customer-config [-a <value>] [-d <value>]
+  $ sk generate-customer-config [-a <value>] [-d <value>] [--templates <value>] [--mode customer-config|pre-poc]
 
 FLAGS
   -a, --app=<value>                 The SK app name which is also being used the config output directory name
                                     (kebab-case)
   -d, --customersDirectory=<value>  Name of the sk-onboarding directory where all customer configs are being stored
                                     (default: "customers")
+      --mode=<option>               [default: customer-config] Which config to scaffold: the full acceleration config,
+                                    or the tracking-only pre-PoC config
+                                    <options: customer-config|pre-poc>
+      --templates=<value>           Path to the templates/ root (default: the sk-onboarding checkout the CLI runs in, or
+                                    the sk-onboarding repo on GitLab when run standalone)
 
 DESCRIPTION
   Generates a customer config guided by a wizard 🧙‍

package/dist/commands/generate-customer-config.d.ts

@@ -5,6 +5,8 @@ export default class GenerateCustomerConfig extends Command {
     static flags: {
         app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         customersDirectory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        templates: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        mode: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/generate-customer-config.js

@@ -16,10 +16,18 @@ export default class GenerateCustomerConfig extends Command {
             char: CLIParametersChar.CustomersDirectory,
             description: `Name of the sk-onboarding directory where all customer configs are being stored (default: "${CLIParametersExample.CustomersDirectory}")`,
         }),
+        templates: Flags.string({
+            description: "Path to the templates/ root (default: the sk-onboarding checkout the CLI runs in, or the sk-onboarding repo on GitLab when run standalone)",
+        }),
+        mode: Flags.string({
+            options: ["customer-config", "pre-poc"],
+            default: "customer-config",
+            description: "Which config to scaffold: the full acceleration config, or the tracking-only pre-PoC config",
+        }),
     };
     async run() {
-        const { flags: { app, customersDirectory }, } = await this.parse(GenerateCustomerConfig);
-        const context = new CustomerConfigServiceContext(app, customersDirectory);
+        const { flags: { app, customersDirectory, templates, mode }, } = await this.parse(GenerateCustomerConfig);
+        const context = new CustomerConfigServiceContext(app, customersDirectory, templates, mode);
         const customerConfigService = await new CustomerConfigServiceFactory(context).buildService();
         await customerConfigService.generateConfig();
     }

package/dist/services/customer-config/customer-config-service-context.d.ts

@@ -1,5 +1,13 @@
 export declare class CustomerConfigServiceContext {
     appName: string;
     customersDirectory: string;
-    constructor(appName?: string, customersDirectory?: string);
+    /** Explicit templates/ root; overrides checkout detection and the remote fetch. */
+    templatesPath?: string;
+    /** Template set = wizard mode: "customer-config" (default) or "pre-poc". */
+    mode: string;
+    constructor(appName?: string, customersDirectory?: string, 
+    /** Explicit templates/ root; overrides checkout detection and the remote fetch. */
+    templatesPath?: string, 
+    /** Template set = wizard mode: "customer-config" (default) or "pre-poc". */
+    mode?: string);
 }

package/dist/services/customer-config/customer-config-service-context.js

@@ -2,10 +2,20 @@ import { CLIParametersExample } from "../../models/cli-parameters.js";
 export class CustomerConfigServiceContext {
     appName;
     customersDirectory;
-    constructor(appName = "", customersDirectory = CLIParametersExample.CustomersDirectory) {
+    templatesPath;
+    mode;
+    constructor(appName = "", customersDirectory = CLIParametersExample.CustomersDirectory, 
+    /** Explicit templates/ root; overrides checkout detection and the remote fetch. */
+    templatesPath, 
+    /** Template set = wizard mode: "customer-config" (default) or "pre-poc". */
+    mode = "customer-config") {
         this.appName = appName;
         this.customersDirectory = customersDirectory;
+        this.templatesPath = templatesPath;
+        this.mode = mode;
         this.appName = appName;
         this.customersDirectory = customersDirectory;
+        this.templatesPath = templatesPath;
+        this.mode = mode;
     }
 }

package/dist/services/customer-config/customer-config-service-model.d.ts

@@ -59,3 +59,9 @@ export interface CustomerConfigSettings {
     isPlentymarkets?: boolean;
     addDowntimeDetection?: boolean;
 }
+/**
+ * Every variable this CLI can hand to the wizard templates — the template
+ * manifest in sk-onboarding must be a subset. Extend this together with
+ * `CustomerConfigSettings` when the wizard gains a question.
+ */
+export declare const TEMPLATE_VARIABLES: readonly string[];

package/dist/services/customer-config/customer-config-service-model.js

@@ -32,3 +32,39 @@ export var EnvironmentType;
     EnvironmentType["STAGING"] = "staging";
     EnvironmentType["TEST"] = "test";
 })(EnvironmentType || (EnvironmentType = {}));
+/**
+ * Every variable this CLI can hand to the wizard templates — the template
+ * manifest in sk-onboarding must be a subset. Extend this together with
+ * `CustomerConfigSettings` when the wizard gains a question.
+ */
+export const TEMPLATE_VARIABLES = [
+    "appName",
+    "production.host",
+    "production.forceInstall",
+    "staging.host",
+    "staging.forceInstall",
+    "activateScopedDeployments",
+    "subRouteScope",
+    "includeServiceWorker",
+    "activateImageOptimisation",
+    "removeLazyLoading",
+    "addSSR",
+    "addSSRInnerShadowDomSupport",
+    "addDeviceDetection",
+    "useGATracking",
+    "useScrapingBee",
+    "withGoogleOptimize",
+    "activateCfRocketLoaderPlugin",
+    "hasSoftNavigations",
+    "convertSoftToHardNavigations",
+    "handleUsercentrics",
+    "isPOV",
+    "useDisabledSitesApproach",
+    "shopSystemName",
+    "isShopify",
+    "isShopware",
+    "isSalesforce",
+    "isOxid",
+    "isPlentymarkets",
+    "addDowntimeDetection",
+];

package/dist/services/customer-config/customer-config-service.d.ts

@@ -10,15 +10,20 @@ export declare class CustomerConfigService {
     private set appName(value);
     private set outputDirPath(value);
     private get outputDirPath();
-    private templates;
+    /** Set from the "Downtime Detection" feature answer in the wizard. */
+    private includeDowntimeDetection;
     constructor(context: CustomerConfigServiceContext, cli: CliService);
     private getOutputDirPath;
-    private getHandlebarsOutputFileName;
+    private getOutputFileName;
     private getPathWithChangedDir;
     private isDirNotEmpty;
     private chooseNewOutputDirectoryName;
+    /** A pre-PoC config marks itself via splitTestId "pre_poc" in config_SpeedKit.js. */
+    private isPrePocConfig;
+    /** Parks every config_* file as *_pre-poc (suffix before the extension). */
+    private renamePrePocFiles;
     private selectOutputDirectory;
-    private compileHandlebarsFiles;
+    private compileTemplateFiles;
     private getEnvironmentConfig;
     private shouldFileBeOverwritten;
     private getConfigSettings;

package/dist/services/customer-config/customer-config-service.js

@@ -1,9 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import Handlebars from "handlebars";
 import { analyzeSite, } from "../../helpers/site-analyzer.js";
-import { DirectoryOverwriteOption, EnvironmentType, ShopSystem, } from "./customer-config-service-model.js";
-import { fileURLToPath } from "node:url";
+import { DirectoryOverwriteOption, EnvironmentType, ShopSystem, TEMPLATE_VARIABLES, } from "./customer-config-service-model.js";
+import { findUnknownVariables, resolveTemplateSource, } from "./template-source.js";
 export class CustomerConfigService {
     context;
     cli;
@@ -22,14 +21,8 @@ export class CustomerConfigService {
     get outputDirPath() {
         return this._outputDirPath;
     }
-    templates = [
-        "config_customer.json.hbs",
-        "config_documentHandler.js.hbs",
-        "config_dynamicBlocks.es6.hbs",
-        "config_dynamicStyles.css.hbs",
-        "config_loadHandler.js.hbs",
-        "config_SpeedKit.js.hbs",
-    ];
+    /** Set from the "Downtime Detection" feature answer in the wizard. */
+    includeDowntimeDetection = false;
     constructor(context, cli) {
         this.context = context;
         const { appName } = this.context;
@@ -39,8 +32,8 @@ export class CustomerConfigService {
     getOutputDirPath(directoryName = "") {
         return path.join(process.cwd(), this.context.customersDirectory, directoryName);
     }
-    getHandlebarsOutputFileName(fileName) {
-        return fileName.replace(".hbs", "");
+    getOutputFileName(fileName) {
+        return fileName.replace(/\.njk$/, "");
     }
     getPathWithChangedDir(directoryPath, newDirectory) {
         return path.join(path.dirname(directoryPath), newDirectory);
@@ -65,7 +58,41 @@ export class CustomerConfigService {
         });
         return this.selectOutputDirectory(this.getPathWithChangedDir(directoryPath, newDirectoryName));
     }
+    /** A pre-PoC config marks itself via splitTestId "pre_poc" in config_SpeedKit.js. */
+    isPrePocConfig(directoryPath) {
+        const speedKitConfigPath = path.join(directoryPath, "config_SpeedKit.js");
+        if (!fs.existsSync(speedKitConfigPath)) {
+            return false;
+        }
+        return /["']pre_poc["']/.test(fs.readFileSync(speedKitConfigPath, "utf-8"));
+    }
+    /** Parks every config_* file as *_pre-poc (suffix before the extension). */
+    renamePrePocFiles(directoryPath) {
+        const configFilePattern = /^(config_[^.]+)\.(.+)$/;
+        for (const fileName of fs.readdirSync(directoryPath)) {
+            const match = fileName.match(configFilePattern);
+            if (!match) {
+                continue;
+            }
+            fs.renameSync(path.join(directoryPath, fileName), path.join(directoryPath, `${match[1]}_pre-poc.${match[2]}`));
+        }
+    }
     async selectOutputDirectory(directoryPath) {
+        // Graduation: a full-config run over an existing pre-PoC config parks the
+        // pre-PoC files as *_pre-poc so both versions can be merged afterwards.
+        if (this.context.mode !== "pre-poc" && this.isPrePocConfig(directoryPath)) {
+            this.cli.spacer();
+            this.cli.write(`${directoryPath} holds a pre-PoC config (splitTestId "pre_poc").\n` +
+                "On continue, its config_* files are renamed to *_pre-poc and the full " +
+                "config is scaffolded next to them. Merge the verified trackers into the " +
+                "new config_loadHandler.js afterwards, then delete the *_pre-poc files.\n");
+            const graduate = await this.cli.confirm("Rename the pre-PoC files and continue?");
+            if (graduate) {
+                this.renamePrePocFiles(directoryPath);
+                return directoryPath;
+            }
+            // declined → fall through to the regular not-empty protection
+        }
         // protect output directory if already existing and not empty:
         if (this.isDirNotEmpty(directoryPath)) {
             this.cli.spacer();
@@ -86,13 +113,22 @@ export class CustomerConfigService {
         }
         return directoryPath;
     }
-    async compileHandlebarsFiles(configSettings) {
+    async compileTemplateFiles(configSettings) {
+        const source = await resolveTemplateSource(this.context.templatesPath, this.context.mode);
+        this.cli.write(`Templates: ${source.origin}\n`);
+        // Contract check: the templates may only use variables this CLI knows.
+        const unknown = findUnknownVariables(source.manifest, TEMPLATE_VARIABLES);
+        if (unknown.length > 0) {
+            throw new Error(`The templates use variables this CLI does not know: ${unknown.join(", ")}. ` +
+                "Your sk CLI is older than the templates — update it (npm i) and retry.");
+        }
         // overwriting protection for output directory:
         this.outputDirPath = await this.selectOutputDirectory(this.outputDirPath);
         this.cli.spacer();
+        const templateFiles = source.manifest.files.filter((file) => file !== "downtimeDetection.js.njk" || this.includeDowntimeDetection);
         // write files:
-        for (const templateFile of this.templates) {
-            const outputFileName = this.getHandlebarsOutputFileName(templateFile);
+        for (const templateFile of templateFiles) {
+            const outputFileName = this.getOutputFileName(templateFile);
             this.cli.startAction(`CREATE:CUSTOMER:CONFIG:${outputFileName}`, `Adding ${outputFileName}`);
             try {
                 const outputFilePath = path.join(this.outputDirPath, outputFileName);
@@ -100,11 +136,7 @@ export class CustomerConfigService {
                     this.cli.endAction(`CREATE:CUSTOMER:CONFIG:${outputFileName}`, "skipped!");
                     continue;
                 }
-                const __dirname = path.dirname(fileURLToPath(import.meta.url));
-                const filePath = path.resolve(__dirname, "templates", templateFile);
-                const content = fs.readFileSync(filePath, "utf8");
-                const template = Handlebars.compile(content);
-                const result = template(configSettings);
+                const result = await source.render(templateFile, configSettings);
                 fs.mkdirSync(path.dirname(outputFilePath), { recursive: true });
                 fs.writeFileSync(outputFilePath, result);
                 this.cli.successAction(`CREATE:CUSTOMER:CONFIG:${outputFileName}`);
@@ -238,6 +270,22 @@ export class CustomerConfigService {
             }
             this.cli.spacer();
         }
+        // Pre-PoC: the tracking-only set uses no acceleration answers — stop asking here.
+        if (this.context.mode === "pre-poc") {
+            return {
+                appName: this.appName,
+                production,
+                staging,
+                shopSystemName: selectedShopSystem === ShopSystem.OTHER
+                    ? undefined
+                    : selectedShopSystem,
+                isShopify,
+                isShopware,
+                isSalesforce,
+                isOxid,
+                isPlentymarkets,
+            };
+        }
         const resolve = (feature, fallback) => {
             if (!siteAnalysis)
                 return { label: "", checked: fallback };
@@ -420,10 +468,8 @@ export class CustomerConfigService {
     async generateConfig() {
         this.cli.write("\nLet's generate a config...\n");
         const configSettings = await this.getConfigSettings();
-        if (configSettings.addDowntimeDetection) {
-            this.templates.push("downtimeDetection.js.hbs");
-        }
-        await this.compileHandlebarsFiles(configSettings);
+        this.includeDowntimeDetection = Boolean(configSettings.addDowntimeDetection);
+        await this.compileTemplateFiles(configSettings);
         await this.logWarnings(configSettings);
         this.cli.writeSuccess("\nConfig generation completed 👏\n");
     }

package/dist/services/customer-config/template-source.d.ts

@@ -0,0 +1,33 @@
+/** The templates/<set>/manifest.json contract in sk-onboarding. */
+export interface TemplateManifest {
+    engine: string;
+    engineOptions: Record<string, boolean>;
+    files: string[];
+    partials?: string[];
+    variables: Record<string, {
+        type: "boolean" | "string" | "string?";
+        sample?: unknown;
+    }>;
+}
+export interface TemplateSource {
+    /** Where the templates come from — shown to the user. */
+    origin: string;
+    manifest: TemplateManifest;
+    /** Renders one of manifest.files with the wizard settings ({% include %} resolves). */
+    render(file: string, settings: Record<string, unknown>): Promise<string>;
+}
+/**
+ * Resolves where the wizard templates come from, in order:
+ * 1. an explicit --templates path (the templates/ root),
+ * 2. the sk-onboarding checkout the CLI runs in (walking up from cwd).
+ *
+ * `set` picks the template set (wizard mode), e.g. "customer-config" or "pre-poc".
+ */
+export declare function resolveTemplateSource(explicitPath?: string, set?: string): Promise<TemplateSource>;
+/**
+ * The templates may only use variables this CLI knows — conditional wizard
+ * answers are legitimately absent at runtime, so the contract is checked
+ * against the CLI's variable inventory, not one run's settings object.
+ * A non-empty result means this CLI is older than the templates.
+ */
+export declare function findUnknownVariables(manifest: TemplateManifest, knownVariables: readonly string[]): string[];

package/dist/services/customer-config/template-source.js

@@ -0,0 +1,49 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import nunjucks from "nunjucks";
+const TEMPLATES_DIR = "templates";
+/**
+ * Resolves where the wizard templates come from, in order:
+ * 1. an explicit --templates path (the templates/ root),
+ * 2. the sk-onboarding checkout the CLI runs in (walking up from cwd).
+ *
+ * `set` picks the template set (wizard mode), e.g. "customer-config" or "pre-poc".
+ */
+export async function resolveTemplateSource(explicitPath, set = "customer-config") {
+    if (explicitPath)
+        return localSource(path.resolve(explicitPath), set);
+    for (let dir = process.cwd();; dir = path.dirname(dir)) {
+        const candidate = path.join(dir, TEMPLATES_DIR);
+        if (fs.existsSync(path.join(candidate, set, "manifest.json"))) {
+            return localSource(candidate, set);
+        }
+        if (dir === path.dirname(dir))
+            break;
+    }
+    throw new Error("No wizard templates found. Run inside an sk-onboarding checkout or " +
+        "pass --templates <path>.");
+}
+function buildEnvironment(loader, manifest) {
+    return new nunjucks.Environment(loader, manifest.engineOptions);
+}
+function localSource(templatesRoot, set) {
+    const setDir = path.join(templatesRoot, set);
+    const manifest = JSON.parse(fs.readFileSync(path.join(setDir, "manifest.json"), "utf8"));
+    const env = buildEnvironment(new nunjucks.FileSystemLoader(templatesRoot), manifest);
+    const origin = setDir;
+    return {
+        origin,
+        manifest,
+        render: async (file, settings) => env.renderString(fs.readFileSync(path.join(setDir, file), "utf8"), settings),
+    };
+}
+/**
+ * The templates may only use variables this CLI knows — conditional wizard
+ * answers are legitimately absent at runtime, so the contract is checked
+ * against the CLI's variable inventory, not one run's settings object.
+ * A non-empty result means this CLI is older than the templates.
+ */
+export function findUnknownVariables(manifest, knownVariables) {
+    const known = new Set(knownVariables);
+    return Object.keys(manifest.variables).filter((name) => !known.has(name));
+}

package/dist/services/integration-api/integration-api-model.js

@@ -26,7 +26,9 @@ export const DEFAULT_BLOCKED_FOLDERS = [
     ".idea",
     "page-examples",
 ];
-export const DEFAULT_BLOCKED_FILES = ["page-examples"];
+// "_pre-poc": parked pre-PoC files created by the graduation flow of
+// generate-customer-config — kept for the manual merge, never deployed.
+export const DEFAULT_BLOCKED_FILES = ["page-examples", "_pre-poc"];
 export class IntegrationApiContext {
     basePath;
     configName;

package/oclif.manifest.json

@@ -402,6 +402,25 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "templates": {
+          "description": "Path to the templates/ root (default: the sk-onboarding checkout the CLI runs in, or the sk-onboarding repo on GitLab when run standalone)",
+          "name": "templates",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "mode": {
+          "description": "Which config to scaffold: the full acceleration config, or the tracking-only pre-PoC config",
+          "name": "mode",
+          "default": "customer-config",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "customer-config",
+            "pre-poc"
+          ],
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -1112,5 +1131,5 @@
       ]
     }
   },
-  "version": "4.21.0"
+  "version": "4.22.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@speedkit/cli",
   "description": "Speed Kit CLI",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "author": {
     "name": "Baqend.com",
     "email": "info@baqend.com"
@@ -110,6 +110,7 @@
     "iconv-lite": "^0.7.2",
     "json2csv": "^6.0.0-alpha.2",
     "node-fetch": "^3.3.2",
+    "nunjucks": "^3.2.4",
     "nypm": "^0.6.6",
     "puppeteer": "^24.41.0",
     "puppeteer-extra": "^3.3.6",
@@ -128,6 +129,7 @@
     "@oclif/test": "^4.1.18",
     "@types/chai": "^4.3.10",
     "@types/node": "^25.6.0",
+    "@types/nunjucks": "^3.2.6",
     "@types/uuid": "^9.0.8",
     "chai": "^4.4.1",
     "copyfiles": "^2.4.1",
@@ -154,5 +156,10 @@
     "*.ts": [
       "eslint --fix --quiet"
     ]
+  },
+  "overrides": {
+    "nunjucks": {
+      "chokidar": "$chokidar"
+    }
   }
 }