pwvm 0.1.0 → 1.0.0

package/README.md

@@ -1,5 +1,7 @@
 # pwvm
 
+![CI](https://github.com/eaccmk/pwvm/actions/workflows/ci.yml/badge.svg)
+
 ### **Playwright Version Manager**
 
 A simple *Playwright Version Manager* that solves a common pain point:
@@ -8,6 +10,8 @@ A simple *Playwright Version Manager* that solves a common pain point:
 
 `pwvm` lets you install, manage, and switch Playwright versions reliably — **one command, predictable behavior**, just like `nvm` for Node.js.
 
+![pwvm icon ](./wiki/pwvm_icon_white.png)
+
 ---
 
 ## Why pwvm
@@ -43,25 +47,41 @@ Follow the printed instructions to add pwvm shims to your `PATH`.
 ## Common usage
 
 ```sh
-pwvm install 1.53.0
-pwvm use 1.53.0
+pwvm install 1.57.0
+pwvm use 1.57.0
+playwright --version
 playwright test
 ```
 
+![pwvm commmands demo](./wiki/switching_playwright_vesions.gif)
+
 Pin versions per project with `.pwvmrc`:
 
 ```text
-1.53.0
+1.57.0
 ```
 
+### Deterministic guarantees pwvm already provides
+•	Playwright installed by exact version (`playwright@x.y.z`)
+•	Versions stored in isolated directories (`~/.pwvm/versions/<version>`)
+•	Browser binaries scoped per Playwright version
+•	`.pwvmrc` pins version per repo
+•	No implicit upgrades (no latest unless explicitly requested)
+
+> [!NOTE] pwvm performs no background network activity and only installs software when explicitly requested.
+
 ---
 
-## CI-friendly
+### CI-friendly
 
 `pwvm` works in GitHub Actions, Azure Pipelines, Bitbucket, and any CI where you control `PATH`.
 
 Install → setup → select version → run Playwright.
 
+### Dockerized
+
+`pwvm` works seamlessly in Docker containers or local development.
+
 ---
 
 ## Support pwvm
@@ -72,7 +92,7 @@ If this tool saves you time, CI hours, or debugging frustration:
 
 * ⭐ [Star the project](https://github.com/eaccmk/pwvm)
 * ❤️ [Sponsor via GitHub](https://github.com/sponsors/eaccmk)
-* 🔁 Share it with your team
+* 🔁 Share it with your team and tag #QualityWithMillan
 
 Your support helps keep pwvm maintained and improving.
 

package/dist/commands/doctor.js

@@ -24,7 +24,7 @@ export const runDoctorCommand = async (deps = {}) => {
     const fsImpl = deps.fs ?? fs;
     const pwvmDir = getPwvmDir();
     const shimsDir = deps.shimsDir ?? getShimsDir();
-    const envPath = deps.envPath ?? process.env.PATH ?? "";
+    const envPath = deps.envPath ?? process.env.PATH ?? process.env.DOCKER_PATH ?? "";
     const shimPath = path.join(shimsDir, "playwright");
     const useColor = process.stdout.isTTY === true;
     const withScope = (message) => message.startsWith(" ") ? `pwvm-doctor${message}` : `pwvm-doctor ${message}`;

package/dist/commands/uninstall.js

@@ -0,0 +1,25 @@
+import { uninstallPlaywrightVersion, } from "../core/uninstall.js";
+import { createLogger, formatError } from "../utils/logger.js";
+export const runUninstallCommand = async (version, deps = {}) => {
+    const logger = deps.logger ?? createLogger();
+    const uninstall = deps.uninstall ?? uninstallPlaywrightVersion;
+    try {
+        await uninstall(version, deps.uninstallOptions);
+        logger.info(`Uninstalled Playwright ${version}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        let hint;
+        if (message.includes("is currently active")) {
+            hint = "Run `pwvm use <version>` to switch first.";
+        }
+        else if (message.includes("is not installed")) {
+            hint = "Run `pwvm list` to see installed versions.";
+        }
+        else if (message.includes("Invalid Playwright version")) {
+            hint = "Use a valid semver like 1.2.3.";
+        }
+        logger.error(formatError(message, hint));
+        process.exitCode = 1;
+    }
+};

package/dist/core/uninstall.js

@@ -0,0 +1,27 @@
+import fs from "fs-extra";
+import path from "node:path";
+import semver from "semver";
+import { getVersionsDir } from "./paths.js";
+import { getGlobalActiveVersion } from "./versions.js";
+export const uninstallPlaywrightVersion = async (version, options = {}) => {
+    if (!semver.valid(version)) {
+        throw new Error(`Invalid Playwright version "${version}".`);
+    }
+    const fsImpl = options.fs ?? fs;
+    const activeVersion = await getGlobalActiveVersion({
+        homeDir: options.homeDir,
+        activeVersionFile: options.activeVersionFile,
+        fs: fsImpl,
+    });
+    if (activeVersion === version) {
+        throw new Error(`Playwright version "${version}" is currently active.`);
+    }
+    const resolveVersionsDir = options.getVersionsDir ?? getVersionsDir;
+    const versionsDir = options.versionsDir ?? resolveVersionsDir(options.homeDir);
+    const targetDir = path.join(versionsDir, version);
+    const exists = await fsImpl.pathExists(targetDir);
+    if (!exists) {
+        throw new Error(`Playwright version "${version}" is not installed.`);
+    }
+    await fsImpl.remove(targetDir);
+};

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import fs from "fs-extra";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { runCurrentCommand } from "./commands/current.js";
 import { runDoctorCommand } from "./commands/doctor.js";
@@ -9,10 +10,13 @@ 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 { runUninstallCommand } from "./commands/uninstall.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 require = createRequire(import.meta.url);
+const { version: pwvmVersion } = require("../package.json");
 const program = new Command();
 program.enablePositionalOptions();
 const logger = createLogger();
@@ -34,8 +38,78 @@ const getShimArgs = () => {
 };
 program
     .name("pwvm")
-    .description("Playwright Version Manager")
-    .version("0.0.1");
+    .description(`Playwright Version Manager (v${pwvmVersion})`)
+    .version(pwvmVersion, "-v, --version");
+program.configureOutput({
+    outputError: () => { },
+});
+program.exitOverride((err) => {
+    // Commander control-flow exits (help / version)
+    if (err.code === "commander.helpDisplayed" ||
+        err.code === "commander.versionDisplayed" ||
+        err.code === "commander.help" ||
+        err.exitCode === 0) {
+        process.exitCode = err.exitCode || 0;
+        return;
+    }
+    let message = err.message;
+    if (message.startsWith("error: ")) {
+        message = message.slice("error: ".length);
+    }
+    message = message.replace(/'([^']+)'/g, "\"$1\"");
+    if (message.length > 0) {
+        message = `${message[0].toUpperCase()}${message.slice(1)}`;
+    }
+    if (!message.endsWith(".")) {
+        message = `${message}.`;
+    }
+    logger.error(message);
+    process.exitCode = err.exitCode || 1;
+});
+program.configureHelp({
+    formatHelp: (cmd, helper) => {
+        const help = Object.getPrototypeOf(helper).formatHelp.call(helper, cmd, helper);
+        if (cmd !== program) {
+            return help;
+        }
+        const sections = help.split("\n\n");
+        if (sections.length < 2 || !sections[0].startsWith("Usage:")) {
+            return help;
+        }
+        let reordered = [sections[1], sections[0], ...sections.slice(2)].join("\n\n");
+        const installLine = "  install         Install a Playwright version";
+        const uninstallLine = "  uninstall <version>     Uninstall a specific Playwright version";
+        if (!reordered.includes(uninstallLine) && reordered.includes(installLine)) {
+            reordered = reordered.replace(`${installLine}\n`, `${installLine}\n${uninstallLine}\n`);
+        }
+        const lines = reordered.split("\n");
+        let inCommands = false;
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i];
+            if (line === "Commands:") {
+                inCommands = true;
+                continue;
+            }
+            if (inCommands) {
+                if (line.trim().length === 0) {
+                    inCommands = false;
+                    continue;
+                }
+                const match = /^  (.+?)( {2,})(\S.*)$/.exec(line);
+                if (match) {
+                    const prefix = "pwvm ";
+                    const term = match[1];
+                    const spacing = match[2];
+                    const desc = match[3];
+                    const adjusted = Math.max(2, spacing.length - prefix.length);
+                    lines[i] = `  ${prefix}${term}${" ".repeat(adjusted)}${desc}`;
+                }
+            }
+        }
+        reordered = lines.join("\n");
+        return `\n${reordered}`;
+    },
+});
 const shouldShowSetupNotice = async () => {
     if (setupNoticeShown) {
         return false;
@@ -99,6 +173,11 @@ program
     .option("--with-browsers", "Install Playwright browsers (default)")
     .option("--no-browsers", "Skip Playwright browser install")
     .action((version, options) => invoke(runInstallCommand, version, options));
+program
+    .command("uninstall")
+    .description("Uninstall a specific Playwright version")
+    .argument("<version>")
+    .action((version) => invoke(runUninstallCommand, version));
 program
     .command("list")
     .description("List installed Playwright versions")
@@ -143,7 +222,9 @@ program
         process.exitCode = 1;
     }
 });
-void program.parseAsync();
+program.parseAsync().catch(() => {
+    // All commander control-flow exits are handled by exitOverride.
+});
 function getShimErrorDetails(message) {
     const guidanceMarker = ". Run ";
     const guidanceIndex = message.indexOf(guidanceMarker);

package/dist/utils/registry.js

@@ -1,5 +1,7 @@
 import https from "node:https";
 const REGISTRY_URL = "https://registry.npmjs.org";
+// NOTE: This function MUST only be called from user-invoked commands
+// such as `list-remote` or `install latest`. No background usage allowed.
 export const fetchPackageMetadata = async (packageName) => new Promise((resolve, reject) => {
     const url = `${REGISTRY_URL}/${encodeURIComponent(packageName)}`;
     const request = https.get(url, {

package/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "pwvm",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Playwright Version Manager",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,7 @@
   "files": [
     "dist",
     "README.md",
+    "wiki",
     "LICENSE"
   ],
   "scripts": {
@@ -25,8 +26,11 @@
     "playwright-version-manager",
     "playwright-cli",
     "version-manager",
+    "version",
+    "manager",
     "testing",
-    "e2e"
+    "ci",
+    "cli"
   ],
   "engines": {
     "node": ">=18"