@speedkit/cli 4.20.4 → 4.21.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [4.21.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.5...v4.21.0) (2026-08-14)
+
+
+### Features
+
+* implement extensionManagement ([17e65b7](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/17e65b72c8e7791ba1174dd7c948daffe4a9b9cc))
+
+## [4.20.5](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.4...v4.20.5) (2026-08-10)
+
+
+### Bug Fixes
+
+* **onboarding:** keep watching a config file after git replaces it ([ef2571a](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/ef2571a5fa07862382c338096e3311c107f20a74))
+
 ## [4.20.4](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.20.3...v4.20.4) (2026-08-10)
 
 

package/README.md

@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
 $ sk COMMAND
 running command...
 $ sk (--version)
-@speedkit/cli/4.20.4 linux-x64 node-v22.23.2
+@speedkit/cli/4.21.0 linux-x64 node-v22.23.2
 $ sk --help [COMMAND]
 USAGE
   $ sk COMMAND
@@ -78,6 +78,10 @@ By either...
 * [`sk deploy CUSTOMERPATH`](#sk-deploy-customerpath)
 * [`sk diff-url-parameters PAGEURL`](#sk-diff-url-parameters-pageurl)
 * [`sk document-handler CUSTOMERPATH`](#sk-document-handler-customerpath)
+* [`sk extension add [REF]`](#sk-extension-add-ref)
+* [`sk extension list`](#sk-extension-list)
+* [`sk extension remove [REF]`](#sk-extension-remove-ref)
+* [`sk extension update`](#sk-extension-update)
 * [`sk find-pops APP`](#sk-find-pops-app)
 * [`sk generate-customer-config`](#sk-generate-customer-config)
 * [`sk generate-pop-config APP`](#sk-generate-pop-config-app)
@@ -381,6 +385,78 @@ EXAMPLES
   $ sk deploy customers/decathlon.de -c production
 ```
 
+## `sk extension add [REF]`
+
+Install a Chrome extension into the onboarding browser by Web Store link or id
+
+```
+USAGE
+  $ sk extension add [REF]
+
+ARGUMENTS
+  [REF]  Chrome Web Store link or extension id
+
+DESCRIPTION
+  Install a Chrome extension into the onboarding browser by Web Store link or id
+
+EXAMPLES
+  $ sk extension add fmkadmapgofadopljbjfkapdkoienihi
+
+  $ sk extension add https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi
+
+  $ sk extension add
+```
+
+## `sk extension list`
+
+List Chrome extensions managed by the setup wizard
+
+```
+USAGE
+  $ sk extension list
+
+DESCRIPTION
+  List Chrome extensions managed by the setup wizard
+
+EXAMPLES
+  $ sk extension list
+```
+
+## `sk extension remove [REF]`
+
+Remove a managed Chrome extension
+
+```
+USAGE
+  $ sk extension remove [REF]
+
+ARGUMENTS
+  [REF]  Chrome Web Store link or extension id
+
+DESCRIPTION
+  Remove a managed Chrome extension
+
+EXAMPLES
+  $ sk extension remove
+
+  $ sk extension remove <id>
+```
+
+## `sk extension update`
+
+Check managed Chrome extensions for updates and install them
+
+```
+USAGE
+  $ sk extension update
+
+DESCRIPTION
+  Check managed Chrome extensions for updates and install them
+
+EXAMPLES
+  $ sk extension update
+```
+
 ## `sk find-pops APP`
 
 Get IPs for all fastly PoPs

package/dist/commands/extension/add.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "@oclif/core";
+export default class ExtensionAdd extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        ref: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/extension/add.js

@@ -0,0 +1,41 @@
+import { Args, Command } from "@oclif/core";
+import { CliServiceFactory } from "../../services/cli/index.js";
+import { SetupServiceFactory } from "../../services/setup/index.js";
+export default class ExtensionAdd extends Command {
+    static description = "Install a Chrome extension into the onboarding browser by Web Store link or id";
+    static examples = [
+        "$ sk extension add fmkadmapgofadopljbjfkapdkoienihi",
+        "$ sk extension add https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi",
+        "$ sk extension add",
+    ];
+    static args = {
+        ref: Args.string({
+            name: "ref",
+            required: false,
+            description: "Chrome Web Store link or extension id",
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(ExtensionAdd);
+        const cli = new CliServiceFactory().getService();
+        const { extensions } = new SetupServiceFactory(this.config).getService();
+        let ref = args.ref;
+        if (!ref) {
+            ref = await cli.prompt("Paste a Chrome Web Store link or extension id", {
+                defaultAnswer: "",
+            });
+        }
+        if (!ref?.trim()) {
+            cli.writeWarning("No extension provided.");
+            return;
+        }
+        cli.writeWarning("Only add extensions you trust — they are loaded into the onboarding browser.");
+        try {
+            const ext = await extensions.addFromInput(ref);
+            cli.writeSuccess(`Installed ${ext.name} ${ext.version}`);
+        }
+        catch (error) {
+            cli.writeError(`Could not install extension: ${error?.message ?? error}`);
+        }
+    }
+}

package/dist/commands/extension/list.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class ExtensionList extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/extension/list.js

@@ -0,0 +1,27 @@
+import { Command } from "@oclif/core";
+import { CliServiceFactory } from "../../services/cli/index.js";
+import { SetupServiceFactory } from "../../services/setup/index.js";
+export default class ExtensionList extends Command {
+    static description = "List Chrome extensions managed by the setup wizard";
+    static examples = ["$ sk extension list"];
+    async run() {
+        const cli = new CliServiceFactory().getService();
+        const { extensions } = new SetupServiceFactory(this.config).getService();
+        const list = extensions.list();
+        if (list.length === 0) {
+            cli.writeWarning("No managed extensions installed.");
+            return;
+        }
+        cli.table(list.map((ext) => ({
+            name: ext.name,
+            version: ext.version,
+            id: ext.id,
+            path: ext.path,
+        })), {
+            name: { header: "Name" },
+            version: { header: "Version" },
+            id: { header: "Id" },
+            path: { header: "Path" },
+        });
+    }
+}

package/dist/commands/extension/remove.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "@oclif/core";
+export default class ExtensionRemove extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        ref: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/extension/remove.js

@@ -0,0 +1,38 @@
+import { Args, Command } from "@oclif/core";
+import { CliServiceFactory } from "../../services/cli/index.js";
+import { parseExtensionId, SetupServiceFactory, } from "../../services/setup/index.js";
+export default class ExtensionRemove extends Command {
+    static description = "Remove a managed Chrome extension";
+    static examples = ["$ sk extension remove", "$ sk extension remove <id>"];
+    static args = {
+        ref: Args.string({
+            name: "ref",
+            required: false,
+            description: "Chrome Web Store link or extension id",
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(ExtensionRemove);
+        const cli = new CliServiceFactory().getService();
+        const { extensions } = new SetupServiceFactory(this.config).getService();
+        const list = extensions.list();
+        if (list.length === 0) {
+            cli.writeWarning("No managed extensions to remove.");
+            return;
+        }
+        let id = args.ref ? parseExtensionId(args.ref) : null;
+        if (!id) {
+            id = await cli.select("Which extension should be removed?", list.map((ext) => ({
+                name: `${ext.name} (${ext.version})`,
+                value: ext.id,
+            })));
+        }
+        const removed = await extensions.remove(id);
+        if (removed) {
+            cli.writeSuccess(`Removed extension ${id}`);
+        }
+        else {
+            cli.writeWarning(`Extension not found: ${id}`);
+        }
+    }
+}

package/dist/commands/extension/update.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "@oclif/core";
+export default class ExtensionUpdate extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/extension/update.js

@@ -0,0 +1,20 @@
+import { Command } from "@oclif/core";
+import { CliServiceFactory } from "../../services/cli/index.js";
+import { SetupServiceFactory } from "../../services/setup/index.js";
+export default class ExtensionUpdate extends Command {
+    static description = "Check managed Chrome extensions for updates and install them";
+    static examples = ["$ sk extension update"];
+    async run() {
+        const cli = new CliServiceFactory().getService();
+        const { extensions } = new SetupServiceFactory(this.config).getService();
+        const list = extensions.list();
+        if (list.length === 0) {
+            cli.writeWarning("No managed extensions to update.");
+            return;
+        }
+        cli.startAction("EXT:CHECK", "Checking extensions for updates…");
+        cli.endAction("EXT:CHECK");
+        await extensions.updateAll();
+        cli.writeSuccess("Extension update check complete.");
+    }
+}

package/dist/helpers/cli-config.d.ts

@@ -1,4 +1,13 @@
 import { Config } from "@oclif/core";
+/** A Chrome extension installed via the setup wizard and tracked for updates. */
+export interface ManagedExtension {
+    /** Chrome Web Store extension id */
+    id: string;
+    name: string;
+    version: string;
+    /** absolute path to the unpacked extension directory */
+    path: string;
+}
 export interface UserCliConfig {
     chromeExtensionPaths: string;
     chromePath: string;
@@ -14,6 +23,8 @@ export interface UserCliConfig {
     browserAutoUpdate: boolean;
     updateReminderDays: number;
     lastBrowserUpdateCheck: string;
+    managedChromeExtensions: ManagedExtension[];
+    lastExtensionUpdateCheck: string;
     firstRunCompleted: boolean;
     tempFolder: string;
     runtimeConfig: Config;

package/dist/helpers/cli-config.js

@@ -36,6 +36,8 @@ export class CliConfig {
         browserAutoUpdate: false,
         updateReminderDays: 3,
         lastBrowserUpdateCheck: "",
+        managedChromeExtensions: [],
+        lastExtensionUpdateCheck: "",
         firstRunCompleted: false,
         tempFolder: "/tmp",
         runtimeConfig: {},
@@ -74,6 +76,8 @@ export class CliConfig {
             browserAutoUpdate: false,
             updateReminderDays: 3,
             lastBrowserUpdateCheck: "",
+            managedChromeExtensions: [],
+            lastExtensionUpdateCheck: "",
             firstRunCompleted: false,
         };
     }

package/dist/helpers/cli-config.spec.js

@@ -67,4 +67,17 @@ describe("CliConfig save/load", () => {
         const reloaded = new CliConfig(fakeOclifConfig(dir)).load();
         expect(reloaded.browserAutoUpdate).to.equal(false);
     });
+    it("round-trips the managedChromeExtensions array", () => {
+        const cfg = new CliConfig(fakeOclifConfig(dir));
+        cfg.load();
+        cfg.save({
+            managedChromeExtensions: [
+                { id: "abc", name: "Ext", version: "1.0.0", path: "/tmp/ext/abc" },
+            ],
+        });
+        const reloaded = new CliConfig(fakeOclifConfig(dir)).load();
+        expect(reloaded.managedChromeExtensions).to.have.length(1);
+        expect(reloaded.managedChromeExtensions[0].id).to.equal("abc");
+        expect(reloaded.managedChromeExtensions[0].version).to.equal("1.0.0");
+    });
 });

package/dist/hooks/init/first-run.js

@@ -28,6 +28,7 @@ const hook = async function (opts) {
         }
         const service = new SetupServiceFactory(config).getService();
         await service.remindBrowserUpdate();
+        await service.remindExtensionUpdates();
     }
     catch {
         // never block a command because of setup housekeeping

package/dist/services/integration-api/spec/file-watch.spec.d.ts

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

package/dist/services/integration-api/spec/file-watch.spec.js

@@ -0,0 +1,81 @@
+import { expect } from "chai";
+import { describe, it, afterEach } from "mocha";
+import { mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// via the model barrel, not struct/file.js directly: the struct modules form an
+// import cycle that only resolves in this order.
+import { File } from "../integration-api-model.js";
+// chokidar needs a real filesystem, so these run against a temp dir rather than memfs.
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Wait until the change callback has fired at least `count` times. */
+async function waitForCalls(getCalls, count, timeoutMs = 5000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (getCalls() >= count)
+            return;
+        await delay(50);
+    }
+}
+describe("File onChange", function () {
+    // real filesystem events plus chokidar's write-finish debounce
+    this.timeout(20000);
+    let dir;
+    let controller;
+    afterEach(() => {
+        controller?.abort();
+        controller = undefined;
+        if (dir) {
+            rmSync(dir, { recursive: true, force: true });
+            dir = undefined;
+        }
+    });
+    it("keeps reporting edits after the file is replaced instead of written in place", async () => {
+        dir = mkdtempSync(join(tmpdir(), "sk-file-watch-"));
+        const path = join(dir, "config_documentHandler.js");
+        writeFileSync(path, "v0");
+        const file = new File("config_documentHandler", path, "v0");
+        controller = new AbortController();
+        let calls = 0;
+        file.onChange(async () => {
+            calls += 1;
+        }, { signal: controller.signal });
+        await delay(700); // let the watcher attach
+        writeFileSync(path, "v1");
+        await waitForCalls(() => calls, 1);
+        expect(calls, "an in-place write is reported").to.be.at.least(1);
+        // git checkout / reset / rebase / stash / pull replace the file rather than
+        // writing into it. A single-file watch stops firing for good at this point.
+        const callsBeforeReplace = calls;
+        unlinkSync(path);
+        writeFileSync(path, "v2");
+        await waitForCalls(() => calls, callsBeforeReplace + 1);
+        expect(calls, "the replacement itself is reported").to.be.at.least(callsBeforeReplace + 1);
+        // The regression: every edit after the replacement used to be dropped, so
+        // onboarding kept serving the previous build until it was restarted.
+        const callsAfterReplace = calls;
+        writeFileSync(path, "v3");
+        await waitForCalls(() => calls, callsAfterReplace + 1);
+        expect(calls, "an edit after the replacement is still reported").to.be.at.least(callsAfterReplace + 1);
+    });
+    it("ignores changes to sibling files in the same directory", async () => {
+        dir = mkdtempSync(join(tmpdir(), "sk-file-watch-"));
+        const path = join(dir, "config_documentHandler.js");
+        const sibling = join(dir, "config_SpeedKit.js");
+        writeFileSync(path, "v0");
+        writeFileSync(sibling, "other");
+        const file = new File("config_documentHandler", path, "v0");
+        controller = new AbortController();
+        let calls = 0;
+        file.onChange(async () => {
+            calls += 1;
+        }, { signal: controller.signal });
+        await delay(700);
+        writeFileSync(sibling, "other-changed");
+        await delay(900);
+        expect(calls, "a sibling write is not reported").to.equal(0);
+        writeFileSync(path, "v1");
+        await waitForCalls(() => calls, 1);
+        expect(calls, "the watched file is still reported").to.be.at.least(1);
+    });
+});

package/dist/services/integration-api/struct/file.js

@@ -1,4 +1,5 @@
 import { readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { watch as chokidarWatch } from "chokidar";
 import { FILE_TYPE, } from "../integration-api-model.js";
 export class File {
@@ -47,15 +48,26 @@ export class File {
         if (signal?.aborted) {
             return;
         }
-        // chokidar over node's fs.watch: handles atomic write-then-rename
-        // (Claude Code, VS Code's atomicSave, vim writebackup, …) which fs.watch
-        // misses because inotify is inode-bound and the new file gets a new inode.
-        const watcher = chokidarWatch(this.path, {
+        // Watch the containing directory, not the file: a single-file watch stops
+        // firing for good once the file is *replaced* rather than written in place,
+        // which is what git does on checkout/reset/rebase/stash/pull. The replace
+        // itself still arrives, so the breakage is silent — every later edit is
+        // dropped, no rebuild and no cache clear run, and onboarding keeps serving
+        // the previous build until it is restarted.
+        // depth 0 keeps this to the directory's own entries, and chokidar's atomic
+        // option still folds write-then-rename (Claude Code, VS Code atomicSave,
+        // vim writebackup, …) into a single change event.
+        const target = resolve(this.path);
+        const watcher = chokidarWatch(dirname(target), {
             ignoreInitial: true,
             atomic: true,
+            depth: 0,
             awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
         });
-        const handle = async () => {
+        const handle = async (changedPath) => {
+            if (resolve(changedPath) !== target) {
+                return;
+            }
             const content = await readFile(this.path, "utf-8");
             if (content === this.content) {
                 return;

package/dist/services/setup/extension/crx.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A CRX file is a ZIP archive prefixed with a header. Because the header shifts
+ * the archive's byte offsets, a plain unzip cannot read it directly — the header
+ * has to be stripped first. This returns the byte offset at which the embedded
+ * ZIP begins. A buffer without the `Cr24` magic is assumed to already be a ZIP
+ * (offset 0).
+ */
+export declare function getZipOffset(buffer: Buffer): number;
+/**
+ * Extracts a CRX (or plain ZIP) buffer into `destDir` as an unpacked extension.
+ * The destination is cleared first so re-installs/updates replace it cleanly.
+ */
+export declare function extractCrx(crxBuffer: Buffer, destDir: string, tempFolder: string): Promise<void>;

package/dist/services/setup/extension/crx.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import extract from "extract-zip";
+/**
+ * A CRX file is a ZIP archive prefixed with a header. Because the header shifts
+ * the archive's byte offsets, a plain unzip cannot read it directly — the header
+ * has to be stripped first. This returns the byte offset at which the embedded
+ * ZIP begins. A buffer without the `Cr24` magic is assumed to already be a ZIP
+ * (offset 0).
+ */
+export function getZipOffset(buffer) {
+    const magic = buffer.toString("utf8", 0, 4);
+    if (magic !== "Cr24") {
+        return 0;
+    }
+    const version = buffer.readUInt32LE(4);
+    // CRX2: magic(4) version(4) pubKeyLen(4) sigLen(4) pubKey sig zip
+    if (version === 2) {
+        const publicKeyLength = buffer.readUInt32LE(8);
+        const signatureLength = buffer.readUInt32LE(12);
+        return 16 + publicKeyLength + signatureLength;
+    }
+    // CRX3: magic(4) version(4) headerLen(4) header zip
+    if (version === 3) {
+        const headerLength = buffer.readUInt32LE(8);
+        return 12 + headerLength;
+    }
+    throw new Error(`Unsupported CRX version: ${version}`);
+}
+/**
+ * Extracts a CRX (or plain ZIP) buffer into `destDir` as an unpacked extension.
+ * The destination is cleared first so re-installs/updates replace it cleanly.
+ */
+export async function extractCrx(crxBuffer, destDir, tempFolder) {
+    const offset = getZipOffset(crxBuffer);
+    const zipBuffer = offset > 0 ? crxBuffer.subarray(offset) : crxBuffer;
+    const resolvedDest = path.resolve(destDir);
+    // extract-zip needs a file path, so stage the embedded zip on disk first
+    const tempZipPath = path.resolve(tempFolder, `${path.basename(resolvedDest)}.crx.zip`);
+    fs.writeFileSync(tempZipPath, zipBuffer);
+    fs.rmSync(resolvedDest, { recursive: true, force: true });
+    try {
+        await extract(tempZipPath, { dir: resolvedDest });
+    }
+    finally {
+        fs.rmSync(tempZipPath, { force: true });
+    }
+}

package/dist/services/setup/extension/crx.spec.d.ts

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

package/dist/services/setup/extension/crx.spec.js

@@ -0,0 +1,38 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { getZipOffset } from "./crx.js";
+function crx3Header(headerLength) {
+    const buffer = Buffer.alloc(12);
+    buffer.write("Cr24", 0, "utf8");
+    buffer.writeUInt32LE(3, 4);
+    buffer.writeUInt32LE(headerLength, 8);
+    return buffer;
+}
+function crx2Header(publicKeyLength, signatureLength) {
+    const buffer = Buffer.alloc(16);
+    buffer.write("Cr24", 0, "utf8");
+    buffer.writeUInt32LE(2, 4);
+    buffer.writeUInt32LE(publicKeyLength, 8);
+    buffer.writeUInt32LE(signatureLength, 12);
+    return buffer;
+}
+describe("crx.getZipOffset", () => {
+    it("returns 0 for a plain zip (no Cr24 magic)", () => {
+        const zip = Buffer.from([0x50, 0x4b, 0x03, 0x04, 0, 0, 0, 0]);
+        expect(getZipOffset(zip)).to.equal(0);
+    });
+    it("computes the offset for a CRX3 file", () => {
+        // 12 fixed bytes + headerLength
+        expect(getZipOffset(crx3Header(42))).to.equal(54);
+    });
+    it("computes the offset for a CRX2 file", () => {
+        // 16 fixed bytes + pubKeyLen + sigLen
+        expect(getZipOffset(crx2Header(3, 4))).to.equal(23);
+    });
+    it("throws on an unsupported CRX version", () => {
+        const buffer = Buffer.alloc(12);
+        buffer.write("Cr24", 0, "utf8");
+        buffer.writeUInt32LE(9, 4);
+        expect(() => getZipOffset(buffer)).to.throw(/Unsupported CRX version/);
+    });
+});

package/dist/services/setup/extension/extension-installer.d.ts

@@ -0,0 +1,31 @@
+import { ManagedExtension } from "../../../helpers/cli-config.js";
+/**
+ * Derives the Chrome major version to send as `prodversion` to Google's update
+ * service. Prefers the configured puppeteer build, falling back to a recent
+ * constant (the endpoint is lenient about this value).
+ */
+export declare function resolveChromeMajorVersion(browserBuildId: string): string;
+/**
+ * Downloads, extracts and inspects Chrome Web Store extensions. Purely handles
+ * files and network; persistence/prompts live in the setup service.
+ */
+export declare class ExtensionInstaller {
+    private readonly tempFolder;
+    private readonly chromeMajorVersion;
+    constructor(tempFolder: string, chromeMajorVersion: string);
+    get extensionsDir(): string;
+    /**
+     * Installs an extension from a bare id or a Web Store URL and returns its
+     * tracked metadata. Throws on an unparseable input or a failed download.
+     */
+    install(input: string): Promise<ManagedExtension>;
+    /**
+     * Returns the latest available version for an extension, or null when the
+     * check fails or reports no update.
+     */
+    checkLatestVersion(id: string): Promise<string | null>;
+    /** Removes an unpacked extension directory from disk. */
+    removeFiles(extensionPath: string): void;
+    private download;
+    private readManifest;
+}