@speedkit/cli 4.17.0 → 4.18.0

package/dist/services/setup/index.js

@@ -0,0 +1,10 @@
+export * from "./setup-context.js";
+export * from "./setup-service.js";
+export * from "./setup-service-factory.js";
+export * from "./browser/browser-detector.js";
+export * from "./browser/browser-manager.js";
+export * from "./browser/browser-setup-service.js";
+export * from "./difftool/difftool-detector.js";
+export * from "./difftool/difftool-setup-service.js";
+export * from "./os/tool-registry.js";
+export * from "./os/detector-helper.js";

package/dist/services/setup/os/detector-helper.d.ts

@@ -0,0 +1,29 @@
+import { DetectableTool, Platform } from "./tool-registry.js";
+/**
+ * Result of locating a tool on the current system.
+ */
+export interface DetectedTool {
+    id: string;
+    name: string;
+    /** absolute path to the executable/launcher that was found */
+    executablePath: string;
+}
+/**
+ * Resolves a launcher command on PATH, returning its absolute path or null.
+ * Uses `where` on Windows and `which` elsewhere.
+ */
+export declare function resolveOnPath(command: string, platform: Platform): string | null;
+/**
+ * Returns the first candidate path that exists on disk, after expanding
+ * `~`/`%VAR%` tokens, or null when none exist.
+ */
+export declare function findExistingCandidatePath(candidates: string[], home: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Detects a single tool: first via its known candidate paths (preferred, as it
+ * yields an absolute executable), then falling back to a PATH lookup.
+ */
+export declare function detectTool(tool: DetectableTool, platform: Platform, home: string, env?: NodeJS.ProcessEnv): DetectedTool | null;
+/**
+ * Detects every tool in the list, dropping the ones that are not installed.
+ */
+export declare function detectTools(tools: DetectableTool[], platform: Platform, home: string, env?: NodeJS.ProcessEnv): DetectedTool[];

package/dist/services/setup/os/detector-helper.js

@@ -0,0 +1,65 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { expandCandidatePath, } from "./tool-registry.js";
+/**
+ * Resolves a launcher command on PATH, returning its absolute path or null.
+ * Uses `where` on Windows and `which` elsewhere.
+ */
+export function resolveOnPath(command, platform) {
+    const finder = platform === "win32" ? "where" : "which";
+    try {
+        const output = execFileSync(finder, [command], {
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .toString()
+            .trim();
+        // `where` may return multiple lines; take the first hit
+        const first = output.split(/\r?\n/).find((line) => line.trim().length > 0);
+        if (first && existsSync(first.trim())) {
+            return first.trim();
+        }
+    }
+    catch {
+        // not found on PATH
+    }
+    return null;
+}
+/**
+ * Returns the first candidate path that exists on disk, after expanding
+ * `~`/`%VAR%` tokens, or null when none exist.
+ */
+export function findExistingCandidatePath(candidates, home, env = process.env) {
+    for (const candidate of candidates) {
+        const expanded = expandCandidatePath(candidate, home, env);
+        if (existsSync(expanded)) {
+            return expanded;
+        }
+    }
+    return null;
+}
+/**
+ * Detects a single tool: first via its known candidate paths (preferred, as it
+ * yields an absolute executable), then falling back to a PATH lookup.
+ */
+export function detectTool(tool, platform, home, env = process.env) {
+    const candidatePaths = tool.paths[platform] ?? [];
+    const fromPath = findExistingCandidatePath(candidatePaths, home, env);
+    if (fromPath) {
+        return { id: tool.id, name: tool.name, executablePath: fromPath };
+    }
+    for (const command of tool.commands) {
+        const resolved = resolveOnPath(command, platform);
+        if (resolved) {
+            return { id: tool.id, name: tool.name, executablePath: resolved };
+        }
+    }
+    return null;
+}
+/**
+ * Detects every tool in the list, dropping the ones that are not installed.
+ */
+export function detectTools(tools, platform, home, env = process.env) {
+    return tools
+        .map((tool) => detectTool(tool, platform, home, env))
+        .filter((result) => result !== null);
+}

package/dist/services/setup/os/tool-registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * OS-specific registry of the browsers and diff/editor tools the first-run
+ * wizard knows how to detect. Detection strategies differ per platform, so the
+ * candidate executable paths and PATH launcher names are grouped by platform.
+ *
+ * This module holds only data + pure helpers; the actual filesystem probing
+ * lives in the browser/diff-tool detectors.
+ */
+export type Platform = "darwin" | "win32" | "linux";
+export interface DetectableTool {
+    /** stable identifier persisted to config, e.g. "chrome", "code" */
+    id: string;
+    /** human-readable name shown in prompts */
+    name: string;
+    /** launcher names to resolve on PATH (`which`/`where`) */
+    commands: string[];
+    /** absolute candidate paths per platform (support `~` and `%VAR%` tokens) */
+    paths: Partial<Record<Platform, string[]>>;
+}
+export interface DetectableEditor extends DetectableTool {
+    /**
+     * diff-service template for this tool, using the `$exec`/`$file1`/`$file2`
+     * placeholders understood by DiffService.
+     */
+    diffExecTemplate: string;
+}
+export declare const BROWSERS: DetectableTool[];
+export declare const EDITORS: DetectableEditor[];
+/**
+ * Normalizes an unknown platform string into one of the supported platforms.
+ * Falls back to "linux" for the various *nix variants Node may report.
+ */
+export declare function normalizePlatform(platform: string): Platform;
+/**
+ * Expands `~` (home) and Windows `%VAR%` tokens in a candidate path. Unknown
+ * `%VAR%` tokens are left untouched so a later existence check simply misses.
+ */
+export declare function expandCandidatePath(raw: string, home: string, env?: NodeJS.ProcessEnv): string;

package/dist/services/setup/os/tool-registry.js

@@ -0,0 +1,194 @@
+/**
+ * OS-specific registry of the browsers and diff/editor tools the first-run
+ * wizard knows how to detect. Detection strategies differ per platform, so the
+ * candidate executable paths and PATH launcher names are grouped by platform.
+ *
+ * This module holds only data + pure helpers; the actual filesystem probing
+ * lives in the browser/diff-tool detectors.
+ */
+export const BROWSERS = [
+    {
+        id: "chrome",
+        name: "Google Chrome",
+        commands: ["google-chrome", "google-chrome-stable", "chrome"],
+        paths: {
+            darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"],
+            win32: [
+                "%ProgramFiles%\\Google\\Chrome\\Application\\chrome.exe",
+                "%ProgramFiles(x86)%\\Google\\Chrome\\Application\\chrome.exe",
+                "%LOCALAPPDATA%\\Google\\Chrome\\Application\\chrome.exe",
+            ],
+            linux: [
+                "/usr/bin/google-chrome",
+                "/usr/bin/google-chrome-stable",
+                "/opt/google/chrome/chrome",
+            ],
+        },
+    },
+    {
+        id: "chromium",
+        name: "Chromium",
+        commands: ["chromium", "chromium-browser"],
+        paths: {
+            darwin: ["/Applications/Chromium.app/Contents/MacOS/Chromium"],
+            win32: ["%ProgramFiles%\\Chromium\\Application\\chrome.exe"],
+            linux: [
+                "/usr/bin/chromium",
+                "/usr/bin/chromium-browser",
+                "/snap/bin/chromium",
+            ],
+        },
+    },
+    {
+        id: "edge",
+        name: "Microsoft Edge",
+        commands: ["microsoft-edge", "microsoft-edge-stable", "msedge"],
+        paths: {
+            darwin: [
+                "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+            ],
+            win32: [
+                "%ProgramFiles(x86)%\\Microsoft\\Edge\\Application\\msedge.exe",
+                "%ProgramFiles%\\Microsoft\\Edge\\Application\\msedge.exe",
+            ],
+            linux: [
+                "/usr/bin/microsoft-edge",
+                "/usr/bin/microsoft-edge-stable",
+                "/opt/microsoft/msedge/msedge",
+            ],
+        },
+    },
+    {
+        id: "brave",
+        name: "Brave",
+        commands: ["brave-browser", "brave"],
+        paths: {
+            darwin: ["/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"],
+            win32: [
+                "%ProgramFiles%\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+                "%ProgramFiles(x86)%\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
+            ],
+            linux: [
+                "/usr/bin/brave-browser",
+                "/usr/bin/brave",
+                "/opt/brave.com/brave/brave",
+            ],
+        },
+    },
+];
+export const EDITORS = [
+    {
+        id: "idea",
+        name: "IntelliJ IDEA",
+        commands: ["idea"],
+        diffExecTemplate: '"$exec" diff "$file1" "$file2"',
+        paths: {
+            darwin: [
+                "/Applications/IntelliJ IDEA.app/Contents/MacOS/idea",
+                "/usr/local/bin/idea",
+            ],
+            win32: ["%LOCALAPPDATA%\\JetBrains\\Toolbox\\scripts\\idea.cmd"],
+            linux: ["/usr/local/bin/idea", "/opt/idea/bin/idea.sh"],
+        },
+    },
+    {
+        id: "webstorm",
+        name: "WebStorm",
+        commands: ["webstorm"],
+        diffExecTemplate: '"$exec" diff "$file1" "$file2"',
+        paths: {
+            darwin: [
+                "/Applications/WebStorm.app/Contents/MacOS/webstorm",
+                "/usr/local/bin/webstorm",
+            ],
+            win32: ["%LOCALAPPDATA%\\JetBrains\\Toolbox\\scripts\\webstorm.cmd"],
+            linux: ["/usr/local/bin/webstorm", "/opt/webstorm/bin/webstorm.sh"],
+        },
+    },
+    {
+        id: "pycharm",
+        name: "PyCharm",
+        commands: ["pycharm", "charm"],
+        diffExecTemplate: '"$exec" diff "$file1" "$file2"',
+        paths: {
+            darwin: [
+                "/Applications/PyCharm.app/Contents/MacOS/pycharm",
+                "/usr/local/bin/charm",
+            ],
+            win32: ["%LOCALAPPDATA%\\JetBrains\\Toolbox\\scripts\\pycharm.cmd"],
+            linux: ["/usr/local/bin/charm", "/opt/pycharm/bin/pycharm.sh"],
+        },
+    },
+    {
+        id: "code",
+        name: "Visual Studio Code",
+        commands: ["code"],
+        diffExecTemplate: '"$exec" --diff "$file1" "$file2"',
+        paths: {
+            darwin: [
+                "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
+                "/usr/local/bin/code",
+            ],
+            win32: [
+                "%LOCALAPPDATA%\\Programs\\Microsoft VS Code\\bin\\code.cmd",
+                "%ProgramFiles%\\Microsoft VS Code\\bin\\code.cmd",
+            ],
+            linux: ["/usr/bin/code", "/usr/share/code/bin/code", "/snap/bin/code"],
+        },
+    },
+    {
+        id: "codium",
+        name: "VSCodium",
+        commands: ["codium"],
+        diffExecTemplate: '"$exec" --diff "$file1" "$file2"',
+        paths: {
+            darwin: [
+                "/Applications/VSCodium.app/Contents/Resources/app/bin/codium",
+                "/usr/local/bin/codium",
+            ],
+            win32: ["%LOCALAPPDATA%\\Programs\\VSCodium\\bin\\codium.cmd"],
+            linux: ["/usr/bin/codium", "/snap/bin/codium"],
+        },
+    },
+    {
+        id: "cursor",
+        name: "Cursor",
+        commands: ["cursor"],
+        diffExecTemplate: '"$exec" --diff "$file1" "$file2"',
+        paths: {
+            darwin: [
+                "/Applications/Cursor.app/Contents/Resources/app/bin/cursor",
+                "/usr/local/bin/cursor",
+            ],
+            win32: [
+                "%LOCALAPPDATA%\\Programs\\cursor\\resources\\app\\bin\\cursor.cmd",
+            ],
+            linux: ["/usr/bin/cursor", "/opt/cursor/bin/cursor"],
+        },
+    },
+];
+/**
+ * Normalizes an unknown platform string into one of the supported platforms.
+ * Falls back to "linux" for the various *nix variants Node may report.
+ */
+export function normalizePlatform(platform) {
+    if (platform === "darwin" || platform === "win32") {
+        return platform;
+    }
+    return "linux";
+}
+/**
+ * Expands `~` (home) and Windows `%VAR%` tokens in a candidate path. Unknown
+ * `%VAR%` tokens are left untouched so a later existence check simply misses.
+ */
+export function expandCandidatePath(raw, home, env = process.env) {
+    let expanded = raw;
+    if (expanded.startsWith("~")) {
+        expanded = home + expanded.slice(1);
+    }
+    expanded = expanded.replaceAll(/%([^%]+)%/g, (match, name) => {
+        const value = env[name];
+        return value === undefined ? match : value;
+    });
+    return expanded;
+}

package/dist/services/setup/os/tool-registry.spec.d.ts

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

package/dist/services/setup/os/tool-registry.spec.js

@@ -0,0 +1,26 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { expandCandidatePath, normalizePlatform } from "./tool-registry.js";
+describe("tool-registry.normalizePlatform", () => {
+    it("passes through supported platforms", () => {
+        expect(normalizePlatform("darwin")).to.equal("darwin");
+        expect(normalizePlatform("win32")).to.equal("win32");
+        expect(normalizePlatform("linux")).to.equal("linux");
+    });
+    it("falls back to linux for other *nix variants", () => {
+        expect(normalizePlatform("freebsd")).to.equal("linux");
+        expect(normalizePlatform("openbsd")).to.equal("linux");
+    });
+});
+describe("tool-registry.expandCandidatePath", () => {
+    it("expands a leading ~ to the home directory", () => {
+        expect(expandCandidatePath("~/bin/idea", "/home/tester")).to.equal("/home/tester/bin/idea");
+    });
+    it("expands known %VAR% tokens from env", () => {
+        const env = { LOCALAPPDATA: "C:\\Users\\t\\AppData\\Local" };
+        expect(expandCandidatePath("%LOCALAPPDATA%\\Programs\\code.cmd", "C:\\Users\\t", env)).to.equal("C:\\Users\\t\\AppData\\Local\\Programs\\code.cmd");
+    });
+    it("leaves unknown %VAR% tokens untouched", () => {
+        expect(expandCandidatePath("%NOPE%\\x.exe", "/home", {})).to.equal("%NOPE%\\x.exe");
+    });
+});

package/dist/services/setup/setup-context.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Inputs for the first-run wizard. No logic.
+ */
+export declare class SetupContext {
+    /** true when invoked from the npm postinstall hook */
+    readonly postInstall: boolean;
+    /** re-run even if setup was already completed */
+    readonly force: boolean;
+    constructor(
+    /** true when invoked from the npm postinstall hook */
+    postInstall?: boolean, 
+    /** re-run even if setup was already completed */
+    force?: boolean);
+}

package/dist/services/setup/setup-context.js

@@ -0,0 +1,15 @@
+/**
+ * Inputs for the first-run wizard. No logic.
+ */
+export class SetupContext {
+    postInstall;
+    force;
+    constructor(
+    /** true when invoked from the npm postinstall hook */
+    postInstall = false, 
+    /** re-run even if setup was already completed */
+    force = false) {
+        this.postInstall = postInstall;
+        this.force = force;
+    }
+}

package/dist/services/setup/setup-service-factory.d.ts

@@ -0,0 +1,10 @@
+import { Config } from "@oclif/core";
+import { SetupContext } from "./setup-context.js";
+import { SetupService } from "./setup-service.js";
+export declare class SetupServiceFactory {
+    private readonly oclifConfig;
+    private readonly context;
+    private service?;
+    constructor(oclifConfig: Config, context?: SetupContext);
+    getService(): SetupService;
+}

package/dist/services/setup/setup-service-factory.js

@@ -0,0 +1,37 @@
+import { CliServiceFactory } from "../cli/index.js";
+import { CliConfig } from "../../helpers/cli-config.js";
+import { normalizePlatform } from "./os/tool-registry.js";
+import { BrowserDetector } from "./browser/browser-detector.js";
+import { BrowserManager } from "./browser/browser-manager.js";
+import { BrowserSetupService } from "./browser/browser-setup-service.js";
+import { DiffToolDetector } from "./difftool/difftool-detector.js";
+import { DiffToolSetupService } from "./difftool/difftool-setup-service.js";
+import { SetupContext } from "./setup-context.js";
+import { SetupService } from "./setup-service.js";
+export class SetupServiceFactory {
+    oclifConfig;
+    context;
+    service;
+    constructor(oclifConfig, context = new SetupContext()) {
+        this.oclifConfig = oclifConfig;
+        this.context = context;
+    }
+    getService() {
+        if (this.service instanceof SetupService) {
+            return this.service;
+        }
+        const cli = new CliServiceFactory().getService();
+        const cliConfig = new CliConfig(this.oclifConfig);
+        const userConfig = cliConfig.load();
+        const platform = normalizePlatform(this.oclifConfig.platform);
+        const home = this.oclifConfig.home;
+        const cacheDir = userConfig.tempFolder;
+        const browserDetector = new BrowserDetector(platform, home, cacheDir);
+        const browserManager = new BrowserManager(cacheDir, cli);
+        const browserSetup = new BrowserSetupService(cli, cliConfig, userConfig, browserDetector, browserManager);
+        const diffDetector = new DiffToolDetector(platform, home);
+        const diffSetup = new DiffToolSetupService(cli, cliConfig, userConfig, diffDetector);
+        this.service = new SetupService(cli, cliConfig, userConfig, browserSetup, diffSetup, this.context);
+        return this.service;
+    }
+}

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

@@ -0,0 +1,20 @@
+import { CliServiceInterface } from "../cli/index.js";
+import { CliConfig, UserCliConfig } from "../../helpers/cli-config.js";
+import { BrowserSetupService } from "./browser/browser-setup-service.js";
+import { DiffToolSetupService } from "./difftool/difftool-setup-service.js";
+import { SetupContext } from "./setup-context.js";
+export declare class SetupService {
+    private readonly cli;
+    private readonly cliConfig;
+    private readonly userConfig;
+    private readonly browserSetup;
+    private readonly diffSetup;
+    private readonly context;
+    constructor(cli: CliServiceInterface, cliConfig: CliConfig, userConfig: UserCliConfig, browserSetup: BrowserSetupService, diffSetup: DiffToolSetupService, context: SetupContext);
+    /** Runs the full first-run wizard (browser + diff tool) and marks it done. */
+    run(): Promise<void>;
+    /** True when the first-run wizard has already been completed once. */
+    isFirstRunCompleted(): boolean;
+    /** Update-reminder check for the browser, used by the init hook. */
+    remindBrowserUpdate(): Promise<void>;
+}

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

@@ -0,0 +1,37 @@
+export class SetupService {
+    cli;
+    cliConfig;
+    userConfig;
+    browserSetup;
+    diffSetup;
+    context;
+    constructor(cli, cliConfig, userConfig, browserSetup, diffSetup, context) {
+        this.cli = cli;
+        this.cliConfig = cliConfig;
+        this.userConfig = userConfig;
+        this.browserSetup = browserSetup;
+        this.diffSetup = diffSetup;
+        this.context = context;
+    }
+    /** Runs the full first-run wizard (browser + diff tool) and marks it done. */
+    async run() {
+        this.cli.spacer();
+        this.cli.write(this.cli.style.bold("Speed Kit CLI — setup"));
+        this.cli.comment("Configure the browser and diff tool used for onboarding and deploys.");
+        this.cli.spacer();
+        await this.browserSetup.run();
+        this.cli.spacer();
+        await this.diffSetup.run();
+        this.cliConfig.save({ firstRunCompleted: true });
+        this.cli.spacer();
+        this.cli.writeSuccess("Setup complete. Re-run any time with `sk config setup`.");
+    }
+    /** True when the first-run wizard has already been completed once. */
+    isFirstRunCompleted() {
+        return Boolean(this.userConfig.firstRunCompleted) && !this.context.force;
+    }
+    /** Update-reminder check for the browser, used by the init hook. */
+    async remindBrowserUpdate() {
+        await this.browserSetup.remindIfDue();
+    }
+}

package/oclif.manifest.json

@@ -855,6 +855,87 @@
         "fish.js"
       ]
     },
+    "browser:clean": {
+      "aliases": [],
+      "args": {},
+      "description": "Remove puppeteer-managed browser builds from the cache",
+      "examples": [
+        "$ sk browser clean",
+        "$ sk browser clean --all"
+      ],
+      "flags": {
+        "all": {
+          "char": "a",
+          "description": "Remove all cached browser builds without prompting",
+          "name": "all",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "browser:clean",
+      "pluginAlias": "@speedkit/cli",
+      "pluginName": "@speedkit/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "browser",
+        "clean.js"
+      ]
+    },
+    "browser:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List detected system browsers and puppeteer-managed builds",
+      "examples": [
+        "$ sk browser list"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "browser:list",
+      "pluginAlias": "@speedkit/cli",
+      "pluginName": "@speedkit/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "browser",
+        "list.js"
+      ]
+    },
+    "browser:update": {
+      "aliases": [],
+      "args": {},
+      "description": "Update the puppeteer-managed browser to the latest build of its channel",
+      "examples": [
+        "$ sk browser update"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "browser:update",
+      "pluginAlias": "@speedkit/cli",
+      "pluginName": "@speedkit/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "browser",
+        "update.js"
+      ]
+    },
     "config:edit": {
       "aliases": [],
       "args": {},
@@ -878,7 +959,47 @@
         "config",
         "edit.js"
       ]
+    },
+    "config:setup": {
+      "aliases": [],
+      "args": {},
+      "description": "Run the Speed Kit CLI setup wizard (choose browser and diff tool)",
+      "examples": [
+        "$ sk config setup",
+        "$ sk config setup --force"
+      ],
+      "flags": {
+        "force": {
+          "char": "f",
+          "description": "Re-run even if setup was already completed",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "postInstall": {
+          "description": "Internal flag used by the npm postinstall hook",
+          "hidden": true,
+          "name": "postInstall",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "config:setup",
+      "pluginAlias": "@speedkit/cli",
+      "pluginName": "@speedkit/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config",
+        "setup.js"
+      ]
     }
   },
-  "version": "4.17.0"
+  "version": "4.18.0"
 }

package/package.json

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