pwvm 0.1.0

package/dist/index.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "fs-extra";
+import path from "node:path";
+import { runCurrentCommand } from "./commands/current.js";
+import { runDoctorCommand } from "./commands/doctor.js";
+import { runInstallCommand } from "./commands/install.js";
+import { runListCommand } from "./commands/list.js";
+import { runListRemoteCommand } from "./commands/listRemote.js";
+import { runPruneCommand } from "./commands/prune.js";
+import { runSetupCommand } from "./commands/setup.js";
+import { runUseCommand } from "./commands/use.js";
+import { getPwvmDir, getShimsDir } from "./core/paths.js";
+import { runPlaywrightShim } from "./core/shim.js";
+import { createLogger } from "./utils/logger.js";
+const program = new Command();
+program.enablePositionalOptions();
+const logger = createLogger();
+let setupNoticeShown = false;
+const invoke = (handler, ...args) => {
+    const candidate = handler;
+    if (typeof candidate.mockClear === "function") {
+        candidate.mockClear();
+    }
+    return handler(...args);
+};
+const getShimArgs = () => {
+    const argv = process.argv;
+    const shimIndex = argv.indexOf("_shim");
+    if (shimIndex === -1) {
+        return [];
+    }
+    return argv.slice(shimIndex + 1);
+};
+program
+    .name("pwvm")
+    .description("Playwright Version Manager")
+    .version("0.0.1");
+const shouldShowSetupNotice = async () => {
+    if (setupNoticeShown) {
+        return false;
+    }
+    const pwvmDir = getPwvmDir();
+    const shimsDir = getShimsDir();
+    const setupMarker = path.join(pwvmDir, "setup-complete");
+    let markerExists = false;
+    let shimsDirExists = false;
+    try {
+        markerExists = await fs.pathExists(setupMarker);
+    }
+    catch {
+        markerExists = false;
+    }
+    try {
+        shimsDirExists = await fs.pathExists(shimsDir);
+    }
+    catch {
+        shimsDirExists = false;
+    }
+    const pathEntries = (process.env.PATH ?? "")
+        .split(path.delimiter)
+        .filter(Boolean);
+    const pathHasShims = pathEntries.includes(shimsDir);
+    return !(markerExists || (shimsDirExists && pathHasShims));
+};
+program.hook("preAction", async (thisCommand, actionCommand) => {
+    if (!actionCommand) {
+        return;
+    }
+    if (actionCommand.parent && actionCommand.parent !== thisCommand) {
+        return;
+    }
+    const commandName = actionCommand.name();
+    if (commandName === "_shim" || commandName === "setup") {
+        return;
+    }
+    const shouldWarn = await shouldShowSetupNotice();
+    if (!shouldWarn) {
+        return;
+    }
+    setupNoticeShown = true;
+    logger.warn("pwvm is not set up yet.\n");
+    logger.info("To finish setup, run:");
+    logger.info("pwvm setup");
+    logger.info("This will configure Playwright shims and print the PATH entry you need to add.");
+});
+program
+    .command("current")
+    .description("Show active Playwright version")
+    .action(() => invoke(runCurrentCommand));
+program
+    .command("doctor")
+    .description("Check pwvm setup status")
+    .action(() => invoke(runDoctorCommand));
+program
+    .command("install")
+    .description("Install a Playwright version")
+    .argument("<version>", "Playwright version to install")
+    .option("--with-browsers", "Install Playwright browsers (default)")
+    .option("--no-browsers", "Skip Playwright browser install")
+    .action((version, options) => invoke(runInstallCommand, version, options));
+program
+    .command("list")
+    .description("List installed Playwright versions")
+    .action(() => invoke(runListCommand));
+program
+    .command("list-remote")
+    .description("List available Playwright versions")
+    .action(() => invoke(runListRemoteCommand));
+program
+    .command("prune")
+    .description("Remove unused Playwright versions")
+    .action(() => invoke(runPruneCommand));
+program
+    .command("setup")
+    .description("Create shims and show PATH instructions")
+    .action(() => invoke(runSetupCommand));
+program
+    .command("use")
+    .description("Set active Playwright version")
+    .argument("<version>", "Playwright version to use")
+    .action((version) => invoke(runUseCommand, version));
+program
+    .command("_shim", { hidden: true })
+    .argument("[args...]", "Arguments passed through to Playwright")
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .passThroughOptions()
+    .action(async () => {
+    try {
+        await runPlaywrightShim(getShimArgs());
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const shimError = getShimErrorDetails(message);
+        if (!shimError) {
+            throw error;
+        }
+        logger.error(shimError.message);
+        if (shimError.hint) {
+            logger.info(shimError.hint);
+        }
+        process.exitCode = 1;
+    }
+});
+void program.parseAsync();
+function getShimErrorDetails(message) {
+    const guidanceMarker = ". Run ";
+    const guidanceIndex = message.indexOf(guidanceMarker);
+    if (guidanceIndex !== -1) {
+        const base = message.slice(0, guidanceIndex + 1);
+        const hint = message.slice(guidanceIndex + 2);
+        return { message: base, hint };
+    }
+    const notInstalled = /^Playwright (.+) is not installed\.$/.exec(message);
+    if (notInstalled) {
+        const version = notInstalled[1];
+        return {
+            message,
+            hint: `Run \`pwvm install ${version}\` first.`,
+        };
+    }
+    return null;
+}

package/dist/index.test.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+vi.mock("fs-extra", () => ({
+    default: {
+        pathExists: vi.fn(),
+    },
+}));
+vi.mock("./core/paths.js", () => ({
+    getPwvmDir: vi.fn(),
+    getShimsDir: vi.fn(),
+}));
+vi.mock("./commands/list.js", () => ({
+    runListCommand: vi.fn(),
+}));
+describe("setup reminder", () => {
+    const originalArgv = process.argv.slice();
+    const originalPath = process.env.PATH;
+    const originalExitCode = process.exitCode;
+    const originalIsTTY = process.stdout.isTTY;
+    afterEach(() => {
+        process.argv = originalArgv.slice();
+        process.env.PATH = originalPath;
+        process.exitCode = originalExitCode;
+        Object.defineProperty(process.stdout, "isTTY", {
+            value: originalIsTTY,
+            configurable: true,
+        });
+        vi.restoreAllMocks();
+    });
+    it("shows reminder when setup is incomplete and still runs the command", async () => {
+        vi.resetModules();
+        Object.defineProperty(process.stdout, "isTTY", {
+            value: false,
+            configurable: true,
+        });
+        const fsExtra = await import("fs-extra");
+        const paths = await import("./core/paths.js");
+        const listModule = await import("./commands/list.js");
+        const pathExistsMock = vi.mocked(fsExtra.default.pathExists);
+        const getPwvmDirMock = vi.mocked(paths.getPwvmDir);
+        const getShimsDirMock = vi.mocked(paths.getShimsDir);
+        const runListCommandMock = vi.mocked(listModule.runListCommand);
+        const pwvmDir = "/mock/pwvm";
+        const shimsDir = "/mock/pwvm/shims";
+        getPwvmDirMock.mockReturnValue(pwvmDir);
+        getShimsDirMock.mockReturnValue(shimsDir);
+        pathExistsMock.mockResolvedValue(false);
+        process.env.PATH = "/usr/bin";
+        process.argv = ["node", "pwvm", "list"];
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+        vi.spyOn(console, "log").mockImplementation(() => { });
+        let resolveList = null;
+        const listDone = new Promise((resolve) => {
+            resolveList = resolve;
+        });
+        runListCommandMock.mockImplementation(async () => {
+            resolveList?.();
+        });
+        await import("./index.js");
+        await listDone;
+        expect(runListCommandMock).toHaveBeenCalledTimes(1);
+        expect(warnSpy).toHaveBeenCalled();
+        const warning = String(warnSpy.mock.calls[0][0]);
+        expect(warning).toContain("[WARN]:");
+        expect(warning).toContain("pwvm is not set up yet.");
+    });
+    it("does not show reminder when setup is complete", async () => {
+        vi.resetModules();
+        Object.defineProperty(process.stdout, "isTTY", {
+            value: false,
+            configurable: true,
+        });
+        const fsExtra = await import("fs-extra");
+        const paths = await import("./core/paths.js");
+        const listModule = await import("./commands/list.js");
+        const pathExistsMock = vi.mocked(fsExtra.default.pathExists);
+        const getPwvmDirMock = vi.mocked(paths.getPwvmDir);
+        const getShimsDirMock = vi.mocked(paths.getShimsDir);
+        const runListCommandMock = vi.mocked(listModule.runListCommand);
+        const pwvmDir = "/mock/pwvm";
+        const shimsDir = "/mock/pwvm/shims";
+        const markerPath = path.join(pwvmDir, "setup-complete");
+        getPwvmDirMock.mockReturnValue(pwvmDir);
+        getShimsDirMock.mockReturnValue(shimsDir);
+        pathExistsMock.mockImplementation(async (target) => {
+            const value = String(target);
+            return value === markerPath;
+        });
+        process.env.PATH = "/usr/bin";
+        process.argv = ["node", "pwvm", "list"];
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+        let resolveList = null;
+        const listDone = new Promise((resolve) => {
+            resolveList = resolve;
+        });
+        runListCommandMock.mockImplementation(async () => {
+            resolveList?.();
+        });
+        await import("./index.js");
+        await listDone;
+        expect(runListCommandMock).toHaveBeenCalledTimes(1);
+        expect(warnSpy).not.toHaveBeenCalled();
+    });
+});

package/dist/test/utils.js

@@ -0,0 +1,46 @@
+import fs from "fs-extra";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const createTempPwvmHome = async () => {
+    const prefix = path.join(os.tmpdir(), "pwvm-");
+    const homeDir = await mkdtemp(prefix);
+    const cleanup = async () => {
+        await rm(homeDir, { recursive: true, force: true });
+    };
+    return { homeDir, cleanup };
+};
+const normalizePath = (value) => typeof value === "string" ? value : value.toString();
+export const createFsMock = (rootDir) => {
+    const base = path.resolve(rootDir);
+    const resolveWithinRoot = (target) => {
+        const targetPath = normalizePath(target);
+        const absolute = path.isAbsolute(targetPath)
+            ? targetPath
+            : path.join(base, targetPath);
+        const relative = path.relative(base, absolute);
+        if (relative.startsWith("..") || path.isAbsolute(relative)) {
+            throw new Error(`Access outside mock root: ${targetPath}`);
+        }
+        return absolute;
+    };
+    return {
+        pathExists: (target) => fs.pathExists(resolveWithinRoot(target)),
+        readdir: (target, options) => {
+            const resolved = options ?? { withFileTypes: true };
+            return fs.readdir(resolveWithinRoot(target), resolved);
+        },
+        readFile: (target, options) => {
+            const resolved = options ?? "utf8";
+            return fs.readFile(resolveWithinRoot(target), resolved);
+        },
+        writeFile: (target, data, options) => {
+            const resolved = options ?? "utf8";
+            return fs.writeFile(resolveWithinRoot(target), data, resolved);
+        },
+        ensureDir: (target) => fs.ensureDir(resolveWithinRoot(target)),
+        remove: (target) => fs.remove(resolveWithinRoot(target)),
+        existsSync: (target) => fs.existsSync(resolveWithinRoot(target)),
+        statSync: (target) => fs.statSync(resolveWithinRoot(target)),
+    };
+};

package/dist/test-utils/pwvmTestEnv.js

@@ -0,0 +1,34 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createPaths } from "../core/paths.js";
+export const createTestPwvmEnv = async () => {
+    const baseDir = await mkdtemp(path.join(os.tmpdir(), "pwvm-test-"));
+    const homeDir = baseDir;
+    const paths = createPaths(homeDir);
+    const options = {
+        homeDir,
+        pwvmDir: paths.pwvmDir,
+        versionsDir: paths.versionsDir,
+        shimsDir: paths.shimsDir,
+        activeVersionFile: paths.activeVersionFile,
+    };
+    const cleanup = async () => {
+        await rm(baseDir, { recursive: true, force: true });
+    };
+    return {
+        homeDir,
+        paths,
+        options,
+        cleanup,
+    };
+};
+export const withTestPwvmEnv = async (fn) => {
+    const env = await createTestPwvmEnv();
+    try {
+        return await fn(env);
+    }
+    finally {
+        await env.cleanup();
+    }
+};

package/dist/utils/logger.js

@@ -0,0 +1,64 @@
+const defaultLogger = {
+    info: (message) => console.log(message),
+    warn: (message) => console.warn(message),
+    error: (message) => console.error(message),
+};
+const isDoctorLine = (message) => message.startsWith("info pwvm-doctor") || message.startsWith("WARN pwvm-doctor");
+const ANSI = {
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    reset: "\x1b[0m",
+};
+const supportsColor = () => process.stdout.isTTY === true;
+const prefixInfo = (message) => {
+    if (isDoctorLine(message)) {
+        return message;
+    }
+    const base = message.startsWith("[INFO]:")
+        ? message.slice("[INFO]:".length).trimStart()
+        : message;
+    const prefix = supportsColor()
+        ? `${ANSI.green}[INFO]:${ANSI.reset}`
+        : "[INFO]:";
+    return `${prefix} ${base}`;
+};
+const prefixWarn = (message) => {
+    if (isDoctorLine(message)) {
+        return message;
+    }
+    const base = message.startsWith("[WARN]:")
+        ? message.slice("[WARN]:".length).trimStart()
+        : message;
+    const prefix = supportsColor()
+        ? `${ANSI.yellow}[WARN]:${ANSI.reset}`
+        : "[WARN]:";
+    return `${prefix} ${base}`;
+};
+const prefixError = (message) => {
+    const trimmed = message.startsWith("[ERROR]:")
+        ? message.slice("[ERROR]:".length).trimStart()
+        : message.startsWith("Error:")
+            ? message.slice("Error:".length).trimStart()
+            : message;
+    const prefix = supportsColor()
+        ? `${ANSI.red}[ERROR]:${ANSI.reset}`
+        : "[ERROR]:";
+    return `${prefix} ${trimmed}`;
+};
+export const createLogger = (overrides = {}) => ({
+    info: overrides.info ?? ((message) => defaultLogger.info(prefixInfo(message))),
+    warn: overrides.warn ?? ((message) => defaultLogger.warn(prefixWarn(message))),
+    error: overrides.error ?? ((message) => defaultLogger.error(prefixError(message))),
+});
+const toSingleLine = (message) => message.replace(/\s+/g, " ").trim();
+export const formatError = (message, hint) => {
+    const base = toSingleLine(message);
+    const withPrefix = base.startsWith("Error:") ? base : `Error: ${base}`;
+    if (!hint) {
+        return withPrefix;
+    }
+    return `${withPrefix} ${toSingleLine(hint)}`;
+};
+const normalizeDoctorMessage = (message) => message.replace(/\s*\n\s*/g, " ").replace(/\s+$/g, "");
+export const formatDoctorLine = (level, message) => `${level} pwvm-doctor ${normalizeDoctorMessage(message)}`;

package/dist/utils/progress.js

@@ -0,0 +1,87 @@
+export const createProgress = (options) => {
+    const stream = options.stream ?? process.stdout;
+    const isTTY = stream.isTTY === true;
+    const intervalMs = options.intervalMs ?? 100;
+    const label = options.label;
+    const logger = options.logger;
+    const width = 24;
+    const gradient = ["\x1b[34m", "\x1b[94m", "\x1b[97m", "\x1b[94m", "\x1b[34m"];
+    const reset = "\x1b[0m";
+    let progress = 0;
+    let timer = null;
+    let lastVisibleLength = 0;
+    let phase = 0;
+    let started = false;
+    const render = () => {
+        const filled = Math.min(width, Math.round((progress / 100) * width));
+        let bar = "";
+        for (let i = 0; i < filled; i += 1) {
+            const color = gradient[(i + phase) % gradient.length];
+            bar += `${color}█${reset}`;
+        }
+        bar += "░".repeat(width - filled);
+        const percentText = `${progress.toFixed(0)}%`;
+        const line = `${label} [${bar}] ${percentText}`;
+        const visibleLength = label.length + 3 + width + 2 + percentText.length;
+        stream.write(`\r${line}${" ".repeat(Math.max(0, lastVisibleLength - visibleLength))}`);
+        lastVisibleLength = visibleLength;
+    };
+    const clear = () => {
+        if (lastVisibleLength === 0) {
+            return;
+        }
+        stream.write(`\r${" ".repeat(lastVisibleLength)}\r`);
+        lastVisibleLength = 0;
+    };
+    return {
+        start: () => {
+            if (started) {
+                return;
+            }
+            started = true;
+            progress = 0;
+            if (!isTTY) {
+                logger?.info(`${label}... (in progress)`);
+                return;
+            }
+            render();
+            timer = setInterval(() => {
+                if (progress < 95) {
+                    progress += 1;
+                    phase = (phase + 1) % gradient.length;
+                    render();
+                }
+            }, intervalMs);
+        },
+        succeed: () => {
+            if (!started) {
+                return;
+            }
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+            if (!isTTY) {
+                logger?.info(`${label}... done`);
+                return;
+            }
+            progress = 100;
+            phase = 0;
+            render();
+            stream.write("\n");
+            lastVisibleLength = 0;
+        },
+        fail: () => {
+            if (!started) {
+                return;
+            }
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+            if (isTTY) {
+                clear();
+            }
+        },
+    };
+};

package/dist/utils/registry.js

@@ -0,0 +1,36 @@
+import https from "node:https";
+const REGISTRY_URL = "https://registry.npmjs.org";
+export const fetchPackageMetadata = async (packageName) => new Promise((resolve, reject) => {
+    const url = `${REGISTRY_URL}/${encodeURIComponent(packageName)}`;
+    const request = https.get(url, {
+        headers: {
+            Accept: "application/vnd.npm.install-v1+json",
+        },
+    }, (response) => {
+        if (!response.statusCode || response.statusCode >= 400) {
+            reject(new Error("Registry request failed."));
+            response.resume();
+            return;
+        }
+        response.setEncoding("utf8");
+        let body = "";
+        response.on("data", (chunk) => {
+            body += chunk;
+        });
+        response.on("end", () => {
+            try {
+                const parsed = JSON.parse(body);
+                resolve(parsed);
+            }
+            catch {
+                reject(new Error("Invalid registry response."));
+            }
+        });
+    });
+    request.on("error", (error) => {
+        reject(error);
+    });
+    request.setTimeout(8000, () => {
+        request.destroy(new Error("Registry request timed out."));
+    });
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "private": false,
+  "name": "pwvm",
+  "version": "0.1.0",
+  "description": "Playwright Version Manager",
+  "license": "MIT",
+  "type": "module",
+  "author": "Millan Kaul",
+  "bin": {
+    "pwvm": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "ts-node src/index.ts",
+    "test": "vitest",
+    "test:e2e": "vitest -c itest.config.ts"
+  },
+  "keywords": [
+    "playwright",
+    "playwright-version-manager",
+    "playwright-cli",
+    "version-manager",
+    "testing",
+    "e2e"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eaccmk/pwvm.git"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "execa": "^9.6.1",
+    "fs-extra": "^11.3.3",
+    "semver": "^7.7.3"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.0.3",
+    "@types/semver": "^7.7.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}