@allwright.dev/core 0.0.37 → 0.0.38

package/dist/bootstrap.d.ts

@@ -1,2 +1,2 @@
-export declare function ensureRuntimeReady(serverAddr: string): Promise<void>;
+export declare function ensureRuntimeReady(serverAddr: string): Promise<string>;
 export declare function shutdownManagedServer(): Promise<void>;

package/dist/bootstrap.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
@@ -18,24 +19,42 @@ const PROTO_ROOT = fileURLToPath(new URL("../proto/", import.meta.url));
 const ENGINE_PROTO_PATH = fileURLToPath(new URL("../proto/engine/v1/engine.proto", import.meta.url));
 let managedServer = null;
 let managedServerAddr = null;
+let managedServerBaseAddr = null;
 export async function ensureRuntimeReady(serverAddr) {
-    if (await pingServer(serverAddr)) {
-        return;
+    const expectedVersion = expectedRuntimeVersion();
+    const status = await pingServer(serverAddr);
+    if (status) {
+        if (status.version === expectedVersion) {
+            return serverAddr;
+        }
+        if (!isLocalServerAddr(serverAddr)) {
+            throw new Error(`allwright server at ${serverAddr} is running version ${displayVersion(status.version)} but this client expects ${expectedVersion}`);
+        }
     }
     if (!isLocalServerAddr(serverAddr)) {
         throw new Error(`allwright could not reach engine server at ${serverAddr}. Automatic startup is only supported for local addresses.`);
     }
-    if (managedServer && !managedServer.killed && managedServer.exitCode === null && managedServerAddr === serverAddr) {
-        await waitForServer(serverAddr);
-        return;
+    if (managedServer && !managedServer.killed && managedServer.exitCode === null && managedServerBaseAddr === serverAddr && managedServerAddr) {
+        return waitForServer(managedServerAddr, expectedVersion);
+    }
+    if (managedServer && !managedServer.killed && managedServer.exitCode === null) {
+        managedServer.kill("SIGTERM");
+        managedServer = null;
+        managedServerAddr = null;
+        managedServerBaseAddr = null;
+    }
+    const cliPath = await ensureCliAvailable(expectedVersion);
+    ensureWebPlugin(cliPath, expectedVersion);
+    let resolvedServerAddr = serverAddr;
+    if (status && status.version !== expectedVersion) {
+        resolvedServerAddr = await allocateManagedServerAddr(serverAddr);
     }
-    const cliPath = await ensureCliAvailable();
-    ensureWebPlugin(cliPath);
-    managedServer = spawn(cliPath, ["serve", "--listen-addr", cliListenAddr(serverAddr)], {
+    managedServer = spawn(cliPath, ["serve", "--listen-addr", cliListenAddr(resolvedServerAddr)], {
         stdio: "ignore",
     });
-    managedServerAddr = serverAddr;
-    await waitForServer(serverAddr);
+    managedServerAddr = resolvedServerAddr;
+    managedServerBaseAddr = serverAddr;
+    return waitForServer(resolvedServerAddr, expectedVersion);
 }
 export async function shutdownManagedServer() {
     if (managedServer && managedServer.exitCode === null && !managedServer.killed) {
@@ -43,17 +62,19 @@ export async function shutdownManagedServer() {
     }
     managedServer = null;
     managedServerAddr = null;
+    managedServerBaseAddr = null;
 }
-async function waitForServer(serverAddr) {
+async function waitForServer(serverAddr, expectedVersion) {
     const deadline = Date.now() + STARTUP_TIMEOUT_MS;
     while (Date.now() < deadline) {
-        if (await pingServer(serverAddr)) {
-            return;
+        const status = await pingServer(serverAddr);
+        if (status?.version === expectedVersion) {
+            return serverAddr;
         }
         await new Promise((resolve) => setTimeout(resolve, 250));
     }
     await shutdownManagedServer();
-    throw new Error(`timed out waiting for allwright server at ${serverAddr} to become ready`);
+    throw new Error(`timed out waiting for allwright server at ${serverAddr} to become ready with version ${expectedVersion}`);
 }
 async function pingServer(serverAddr) {
     const loaded = protoLoader.loadSync(ENGINE_PROTO_PATH, {
@@ -67,23 +88,31 @@ async function pingServer(serverAddr) {
     const proto = grpc.loadPackageDefinition(loaded);
     const client = new proto.allwright.engine.v1.EngineService(serverAddr, grpc.credentials.createInsecure());
     return await new Promise((resolve) => {
-        client.Ping({}, new grpc.Metadata(), { deadline: new Date(Date.now() + PING_TIMEOUT_MS) }, (error) => {
+        client.Ping({}, new grpc.Metadata(), { deadline: new Date(Date.now() + PING_TIMEOUT_MS) }, (error, response) => {
             client.close();
-            resolve(!error);
+            if (error) {
+                resolve(null);
+                return;
+            }
+            resolve({ version: normalizeReleaseVersion(response.version ?? "") });
         });
     });
 }
-async function ensureCliAvailable() {
+async function ensureCliAvailable(expectedVersion) {
     const envPath = process.env[ALLWRIGHT_CLI_PATH_ENV_VAR]?.trim();
-    if (envPath && isFile(envPath)) {
+    if (envPath && isFile(envPath) && cliVersionMatches(envPath, expectedVersion)) {
         return envPath;
     }
     const bundled = path.join(allwrightHome(), "bin", cliFilename());
-    if (isFile(bundled)) {
+    if (isFile(bundled) && cliVersionMatches(bundled, expectedVersion)) {
         return bundled;
     }
+    const repoLocal = repoLocalCliPath();
+    if (repoLocal && cliVersionMatches(repoLocal, expectedVersion)) {
+        return repoLocal;
+    }
     const fromPath = resolveFromPath(cliFilename());
-    if (fromPath) {
+    if (fromPath && cliVersionMatches(fromPath, expectedVersion)) {
         return fromPath;
     }
     if (!autoInstallEnabled()) {
@@ -108,18 +137,20 @@ async function installCli() {
     fs.rmSync(assetPath, { force: true });
     return cliPath;
 }
-function ensureWebPlugin(cliPath) {
+function ensureWebPlugin(cliPath, expectedVersion) {
     const pluginPath = path.join(allwrightHome(), "plugins", "web", "lib", webPluginFilename());
-    if (isFile(pluginPath)) {
+    if (isFile(pluginPath) && installedPluginVersion("web") === expectedVersion) {
         return;
     }
-    const version = process.env[ALLWRIGHT_VERSION_ENV_VAR]?.trim() || DEFAULT_RELEASE_VERSION;
-    const result = spawnSync(cliPath, ["plugin", "install", "web", "--version", normalizeReleaseVersion(version)], {
+    const result = spawnSync(cliPath, ["plugin", "install", "web", "--version", expectedVersion], {
         stdio: "ignore",
     });
     if (result.status !== 0 || !isFile(pluginPath)) {
         throw new Error("allwright attempted to install the `web` plugin automatically, but the install did not complete successfully");
     }
+    if (installedPluginVersion("web") !== expectedVersion) {
+        throw new Error(`allwright attempted to install the \`web\` plugin automatically, but version ${expectedVersion} is still not active`);
+    }
 }
 async function resolveReleaseTag() {
     const version = process.env[ALLWRIGHT_VERSION_ENV_VAR]?.trim() || DEFAULT_RELEASE_VERSION;
@@ -189,13 +220,96 @@ function normalizeReleaseTag(version) {
 function normalizeReleaseVersion(version) {
     return version.replace(/^v/, "");
 }
+function expectedRuntimeVersion() {
+    return normalizeReleaseVersion(process.env[ALLWRIGHT_VERSION_ENV_VAR]?.trim() || DEFAULT_RELEASE_VERSION);
+}
 function cliListenAddr(serverAddr) {
     return serverAddr.replace(/^https?:\/\//, "");
 }
 function isLocalServerAddr(serverAddr) {
-    const host = cliListenAddr(serverAddr).split(":")[0]?.replace(/^\[|\]$/g, "") ?? "";
+    const host = parseServerHost(serverAddr);
     return host === "127.0.0.1" || host === "localhost" || host === "::1";
 }
+function installedPluginVersion(pluginId) {
+    const manifestPath = path.join(allwrightHome(), "plugins.txt");
+    if (!isFile(manifestPath)) {
+        return null;
+    }
+    for (const line of fs.readFileSync(manifestPath, "utf8").split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const [id, , version] = trimmed.split("\t", 3);
+        if (id === pluginId && version) {
+            return normalizeReleaseVersion(version);
+        }
+    }
+    return null;
+}
+async function allocateManagedServerAddr(serverAddr) {
+    const host = localBindingHost(serverAddr);
+    const port = await new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.on("error", reject);
+        server.listen(0, host, () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close(() => reject(new Error("failed to reserve a local port for allwright")));
+                return;
+            }
+            const { port } = address;
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve(port);
+            });
+        });
+    });
+    return host.includes(":") ? `http://[${host}]:${port}` : `http://${host}:${port}`;
+}
+function localBindingHost(serverAddr) {
+    const host = parseServerHost(serverAddr);
+    return host === "::1" ? "::1" : "127.0.0.1";
+}
+function displayVersion(version) {
+    return version || "unknown";
+}
+function repoLocalCliPath() {
+    const repoRoot = fileURLToPath(new URL("../../..", import.meta.url));
+    for (const candidate of [
+        path.join(repoRoot, "target", "debug", cliFilename()),
+        path.join(repoRoot, "target", "release", cliFilename()),
+    ]) {
+        if (isFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function cliVersionMatches(cliPath, expectedVersion) {
+    const result = spawnSync(cliPath, ["--version"], { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" });
+    if (result.status !== 0) {
+        return false;
+    }
+    for (const token of result.stdout.split(/\s+/)) {
+        if (/^\d/.test(token)) {
+            return normalizeReleaseVersion(token) === expectedVersion;
+        }
+    }
+    return false;
+}
+function parseServerHost(serverAddr) {
+    const listenAddr = cliListenAddr(serverAddr);
+    const ipv6Match = listenAddr.match(/^\[([^\]]+)\]/);
+    if (ipv6Match) {
+        return ipv6Match[1] ?? "";
+    }
+    return listenAddr.split(":")[0] ?? "";
+}
 function allwrightHome() {
     return process.env[ALLWRIGHT_HOME_ENV_VAR]?.trim() || path.join(os.homedir(), ".allwright");
 }

package/dist/runtime.js

@@ -78,7 +78,7 @@ export function resolveLaunchBrowserArgs(browserKindOrOptions) {
 }
 async function createRuntime() {
     const serverAddr = configuredServerAddr();
-    await ensureRuntimeReady(serverAddr);
+    const resolvedServerAddr = await ensureRuntimeReady(serverAddr);
     const loaded = protoLoader.loadSync(ENGINE_PROTO_PATH, {
         includeDirs: [PROTO_ROOT],
         keepCase: false,
@@ -89,7 +89,7 @@ async function createRuntime() {
     });
     const proto = grpc.loadPackageDefinition(loaded);
     const ClientCtor = proto.allwright.engine.v1.EngineService;
-    const client = new ClientCtor(serverAddr, grpc.credentials.createInsecure());
+    const client = new ClientCtor(resolvedServerAddr, grpc.credentials.createInsecure());
     return { client };
 }
 function configuredServerAddr() {

package/dist/types.d.ts

@@ -173,6 +173,7 @@ export interface ResolveConfigOptions {
 }
 export interface PingResponse {
     message?: string;
+    version?: string;
 }
 export interface ChromeLaunchedPayload {
     browser?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allwright.dev/core",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "description": "High-level TypeScript client for the allwright automation engine.",
   "license": "MIT",
   "type": "module",

package/proto/core/v1/common.proto

@@ -7,6 +7,7 @@ message PingRequest {}
 
 message PingResponse {
   string message = 1;
+  string version = 2;
 }
 
 message CommandRetryOptions {