@swimmingliu/autovpn 1.4.1 → 1.5.0

package/README.md

@@ -24,6 +24,33 @@ autovpn run --project-root . --skip-deploy --skip-verify --output jsonl
 autovpn artifacts latest --project-root .
 ```
 
+## Server Web UI
+
+`autovpn serve` starts a single-user HTTP service that serves the AutoVPN Web UI
+from the same renderer used by the desktop app.
+
+```bash
+autovpn serve --project-root .
+```
+
+Defaults:
+
+- host: `127.0.0.1`
+- port: `8765`
+- auth: token-protected
+
+For server deployment, bind explicitly and provide a token:
+
+```bash
+export AUTOVPN_SERVER_TOKEN="$(openssl rand -base64 24)"
+autovpn serve --project-root /opt/autovpn --host 0.0.0.0 --port 8765 \
+  --token "$AUTOVPN_SERVER_TOKEN"
+```
+
+The server refuses non-loopback binds unless `--token` or `--no-auth` is
+provided. Prefer SSH forwarding, a private reverse proxy, or your own HTTPS
+terminator for internet-facing deployments.
+
 ## Runtime Shape
 
 The CLI is currently Node-first with explicit Python rollback:
@@ -47,6 +74,8 @@ Current Node backend notes:
 - Deploy and verify can be rolled back with `AUTOVPN_STAGE_BACKEND_DEPLOY=python` and `AUTOVPN_STAGE_BACKEND_VERIFY=python`.
 - `AUTOVPN_NO_PYTHON=1` disables implicit Python backend resolution and default Python runtime stage fallback. Use it as a v3 readiness gate. Empty offline runs now complete in Node, and Node has direct HTTP speedtest and availability runtimes. Node also has opt-in Mihomo-backed paths: set `AUTOVPN_SPEEDTEST_RUNTIME=mihomo` for controller delay probing and candidate downloads through the local Mihomo proxy, and set `AUTOVPN_AVAILABILITY_RUNTIME=mihomo` to check provider availability through the same per-node proxy runtime.
 - Project `.env` is loaded before resolving profile and artifact paths. Explicit process environment values still win over `.env`.
+- `autovpn serve` is Node-native and exposes the browser UI plus `/api/health`,
+  `/api/state`, `/api/runs`, `/api/runs/current/stop`, and `/api/events`.
 
 Fallback flags for migrated commands:
 
@@ -96,6 +125,9 @@ For Python-backed commands, the wrapper forwards argv, stdin, stdout, stderr, an
 - `AUTOVPN_DOCTOR_BACKEND`
 - `AUTOVPN_PROFILE_BACKEND`
 - `AUTOVPN_ARTIFACTS_BACKEND`
+- `AUTOVPN_SERVER_HOST`
+- `AUTOVPN_SERVER_PORT`
+- `AUTOVPN_SERVER_TOKEN`
 - `VPN_AUTOMATION_RUNTIME_ROOT`
 - `VPN_AUTOMATION_PROFILE_PATH`
 - `VPN_AUTOMATION_ARTIFACTS_ROOT`

package/dist/cli/commands/index.js

@@ -10,7 +10,8 @@ const TOP_LEVEL_COMMANDS = new Set([
     'jobs',
     'status',
     'logs',
-    'stop'
+    'stop',
+    'serve'
 ]);
 const JOBS_SUBCOMMANDS = new Set(['list', 'status', 'logs', 'stop', 'resume', 'retry']);
 const RESUME_SUBCOMMANDS = new Set(['pipeline', 'speedtest']);
@@ -82,6 +83,9 @@ export function validateCommand(argv) {
         validateChoice('doctor', '--output', readOptionValue(argv, '--output'), ['human', 'json']);
         return;
     }
+    if (command === 'serve') {
+        return;
+    }
     if (command === 'profile') {
         const subcommand = argv[1] ?? '';
         if (!PROFILE_SUBCOMMANDS.has(subcommand)) {

package/dist/cli/main.js

@@ -9,6 +9,9 @@ import { selectBackend } from '../backend/select-backend.js';
 import { loadJob } from '../jobs/read.js';
 import { readOptionValue, resolveProjectRoot } from '../runtime/paths.js';
 import { redactText } from '../runtime/redaction.js';
+import { createAutoVpnServer } from '../server/http.js';
+import { parseServeOptions } from '../server/options.js';
+import { createServerRuntime } from '../server/runtime.js';
 async function defaultReadPackageVersion() {
     // @ts-expect-error The Phase 1 runner is plain ESM JavaScript.
     const runner = await import('../../lib/runner.mjs');
@@ -190,6 +193,33 @@ export async function runCliShell(argv, options = {}) {
         validateCommand(normalizedArgv);
         const createBackend = options.createBackend ?? defaultCreateBackend;
         const backend = createBackend({ env, cwd, runForwarder });
+        if (normalizedArgv[0] === 'serve') {
+            const serveOptions = parseServeOptions(normalizedArgv, { cwd, env });
+            const serverFactory = options.createServer ?? createAutoVpnServer;
+            const runtime = createServerRuntime({
+                projectRoot: serveOptions.projectRoot,
+                env
+            });
+            const server = await serverFactory({
+                ...serveOptions,
+                runtime,
+                version: await resolvePackageVersion(options),
+                backendKind: String(backend.kind ?? '')
+            });
+            io.writeStdout(`AutoVPN server listening on ${server.origin}\n`);
+            if (serveOptions.auth.enabled) {
+                io.writeStdout(`Open ${server.origin}/?token=${encodeURIComponent(serveOptions.auth.token)}\n`);
+            }
+            else {
+                io.writeStderr('autovpn: warning: server authentication is disabled\n');
+            }
+            if (options.serveExitAfterStart) {
+                await server.close();
+                return 0;
+            }
+            await new Promise(() => { });
+            return 0;
+        }
         let pythonFallbackBackend;
         const runExplicitPythonFallback = (fallbackArgv) => {
             pythonFallbackBackend ??= createBackend({

package/dist/cli/native-commands.js

@@ -70,7 +70,7 @@ export async function runNativeCommand(argv, context) {
             return context.pythonFallback(argv);
         if (readOptionValue(argv, '--output') !== 'json')
             return undefined;
-        const result = runDoctor(projectRoot, argv, context.env);
+        const result = await runDoctor(projectRoot, argv, context.env);
         context.io.writeStdout(jsonLine(result.payload));
         return result.code;
     }

package/dist/cli/output.js

@@ -27,5 +27,6 @@ Commands:
   status
   logs
   stop
+  serve
 `;
 }

package/dist/doctor/checks.js

@@ -5,6 +5,9 @@ import { spawnSync } from 'node:child_process';
 import { parse } from '@iarna/toml';
 import { profileSummary } from '../config/profile.js';
 import { resolveArtifactsRoot, resolveProfilePath } from '../runtime/paths.js';
+import { normalizeManagedToolCommandForSpawn, resolveManagedNpmTool } from '../runtime/managed-tools.js';
+const JAVASCRIPT_OBFUSCATOR_VERSION = '5.4.3';
+const WRANGLER_VERSION = '4.106.0';
 function check(name, status, message, details = {}) {
     return { name, status, message, details };
 }
@@ -21,19 +24,27 @@ function pathWritable(targetPath) {
         return false;
     }
 }
-function commandPath(name, env) {
+function commandPath(name, env, platform = process.platform) {
     const pathValue = String(env.PATH ?? process.env.PATH ?? '');
+    const extensions = platform === 'win32'
+        ? String(env.PATHEXT ?? process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
+            .split(';')
+            .filter(Boolean)
+        : [''];
     for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
-        const candidate = path.join(dir, name);
-        if (fs.existsSync(candidate)) {
-            return candidate;
+        for (const extension of extensions) {
+            const candidate = path.join(dir, `${name}${extension}`);
+            if (fs.existsSync(candidate)) {
+                return candidate;
+            }
         }
     }
     return '';
 }
 function safeRun(command, env) {
     try {
-        const result = spawnSync(command[0], command.slice(1), {
+        const { executable, args } = normalizeManagedToolCommandForSpawn(command);
+        const result = spawnSync(executable, args, {
             encoding: 'utf8',
             env: { ...process.env, ...env },
             timeout: 5000
@@ -110,8 +121,8 @@ function checkProxyRuntime(env) {
     checks.push(check('proxy_environment', 'pass', 'Proxy environment inspected', { configured_keys: configuredKeys }));
     return checks;
 }
-function checkNodeTools(projectRoot, env) {
-    const missing = ['node', 'npm', 'npx'].filter((name) => !commandPath(name, env));
+async function checkNodeTools(projectRoot, env, options = {}) {
+    const missing = ['node', 'npm'].filter((name) => !commandPath(name, env, options.platform));
     const checks = [
         check('node_binaries', missing.length ? 'fail' : 'pass', missing.length ? 'Node.js command line tools are missing' : 'Node.js command line tools are available', { missing })
     ];
@@ -120,17 +131,22 @@ function checkNodeTools(projectRoot, env) {
         path.join(projectRoot, 'electron', 'runtime', 'node-vendor', 'node_modules', 'playwright')
     ].some((candidate) => fs.existsSync(candidate));
     checks.push(check('playwright', hasPlaywright ? 'pass' : 'warn', hasPlaywright ? 'Playwright package is installed' : 'Playwright package was not found; run npx playwright install --with-deps chromium-headless-shell'));
-    const npx = commandPath('npx', env);
-    if (!npx) {
-        checks.push(check('javascript_obfuscator', 'fail', 'npx is missing'));
+    try {
+        const obfuscator = await (options.resolveManagedNpmTool ?? resolveManagedNpmTool)({
+            packageName: 'javascript-obfuscator',
+            binaryName: 'javascript-obfuscator',
+            version: JAVASCRIPT_OBFUSCATOR_VERSION,
+            projectRoot,
+            installMissing: false
+        });
+        checks.push(check('javascript_obfuscator', 'pass', 'javascript-obfuscator is available', { source: obfuscator.source, version: obfuscator.version, path: obfuscator.command }));
     }
-    else {
-        const result = safeRun([npx, 'javascript-obfuscator', '--version'], env);
-        checks.push(check('javascript_obfuscator', result.ok ? 'pass' : 'fail', result.ok ? 'javascript-obfuscator is available' : 'javascript-obfuscator is not available', { result: result.message }));
+    catch (error) {
+        checks.push(check('javascript_obfuscator', 'fail', error instanceof Error ? error.message : String(error)));
     }
     return checks;
 }
-function checkCloudflare(summary, deploy, env) {
+async function checkCloudflare(summary, deploy, env, projectRoot, options = {}) {
     const checks = [];
     const deploySummary = summary.deploy ?? {};
     const hasCredentials = deploySummary.cloudflare_api_token === 'set'
@@ -143,17 +159,23 @@ function checkCloudflare(summary, deploy, env) {
     const pagesProjectUrl = String(deploySummary.pages_project_url ?? '');
     const hasDeployUrl = Boolean(String(deploySummary.project_name ?? '').trim() && URL.canParse(pagesProjectUrl));
     checks.push(check('deploy_urls', hasDeployUrl ? 'pass' : (deploy ? 'fail' : 'warn'), hasDeployUrl ? 'Deploy URL settings are internally consistent' : 'Deploy URL settings are incomplete', { has_project_name: Boolean(String(deploySummary.project_name ?? '').trim()), has_pages_url: URL.canParse(pagesProjectUrl) }));
-    const npx = commandPath('npx', env);
-    if (!npx) {
-        checks.push(check('wrangler', deploy ? 'fail' : 'warn', 'npx is missing'));
+    try {
+        const wrangler = await (options.resolveManagedNpmTool ?? resolveManagedNpmTool)({
+            packageName: 'wrangler',
+            binaryName: 'wrangler',
+            version: WRANGLER_VERSION,
+            projectRoot,
+            installMissing: false
+        });
+        const result = (options.safeRun ?? safeRun)([wrangler.command, 'pages', 'deploy', '--help'], env);
+        checks.push(check('wrangler', result.ok ? 'pass' : (deploy ? 'fail' : 'warn'), result.ok ? 'Wrangler Pages deploy command is available' : 'Wrangler Pages deploy command is not available', { source: wrangler.source, version: wrangler.version, path: wrangler.command, result: result.message, deploy_required: deploy }));
     }
-    else {
-        const result = safeRun([npx, 'wrangler', 'pages', 'deploy', '--help'], env);
-        checks.push(check('wrangler', result.ok ? 'pass' : (deploy ? 'fail' : 'warn'), result.ok ? 'Wrangler Pages deploy command is available' : 'Wrangler Pages deploy command is not available', { result: result.message, deploy_required: deploy }));
+    catch (error) {
+        checks.push(check('wrangler', deploy ? 'fail' : 'warn', error instanceof Error ? error.message : String(error), { deploy_required: deploy }));
     }
     return checks;
 }
-export function runDoctor(projectRoot, argv, env = process.env) {
+export async function runDoctor(projectRoot, argv, env = process.env, options = {}) {
     const deploy = argv.includes('--deploy');
     const strict = argv.includes('--strict');
     const profilePath = resolveProfilePath(projectRoot, env);
@@ -162,6 +184,8 @@ export function runDoctor(projectRoot, argv, env = process.env) {
     const summary = profileSummary(projectRoot, env);
     const sourceValues = Object.values((summary.sources ?? {}));
     const configuredSources = sourceValues.filter((source) => source.enabled && source.url === 'set' && source.key === 'set');
+    const nodeToolChecks = await checkNodeTools(projectRoot, env, options);
+    const cloudflareChecks = await checkCloudflare(summary, deploy, env, projectRoot, options);
     const checks = [
         check('node_version', 'pass', `Node ${process.versions.node}`, { required: '>=20' }),
         check('project_root', 'pass', 'Project root resolved', { path: projectRoot }),
@@ -174,8 +198,8 @@ export function runDoctor(projectRoot, argv, env = process.env) {
             : check('sources', 'warn', 'No enabled source has both URL and key configured', { configured_count: 0, key_state: 'missing' }),
         checkSpeedTestConfig(profile),
         ...checkProxyRuntime(env),
-        ...checkNodeTools(projectRoot, env),
-        ...checkCloudflare(summary, deploy, env)
+        ...nodeToolChecks,
+        ...cloudflareChecks
     ];
     const hasFailures = checks.some((item) => item.status === 'fail');
     const hasWarnings = checks.some((item) => item.status === 'warn');

package/dist/pipeline/deploy.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { spawn as defaultSpawn } from 'node:child_process';
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { mergeProjectEnv } from '../runtime/env.js';
+import { normalizeManagedToolCommandForSpawn, resolveManagedNpmTool } from '../runtime/managed-tools.js';
 const PYTHON_DEPLOY_HELPER = `
 import json
 import sys
@@ -77,8 +78,8 @@ function nonNegativeInt(value) {
 function getString(source, key) {
     return clean(source[key]);
 }
-export function buildPagesDeployCommand(bundleDir, projectName) {
-    return ['npx', 'wrangler', 'pages', 'deploy', bundleDir, '--project-name', projectName, '--branch', PAGES_PRODUCTION_BRANCH];
+export function buildPagesDeployCommand(wranglerExecutable, bundleDir, projectName) {
+    return [wranglerExecutable, 'pages', 'deploy', bundleDir, '--project-name', projectName, '--branch', PAGES_PRODUCTION_BRANCH];
 }
 export function derivePagesProjectUrl(projectName) {
     return `https://${projectName}.pages.dev`;
@@ -405,7 +406,7 @@ async function stageShareProjectWorkerBundle(projectRoot, env) {
     return { sourcePath, bundleDir, workerEntry };
 }
 function runCommandWithSpawn(command, options, spawnImpl = defaultSpawn) {
-    const [executable, ...args] = command;
+    const { executable, args } = normalizeManagedToolCommandForSpawn(command);
     const child = spawnImpl(executable, args, {
         cwd: options.cwd,
         env: { ...process.env, ...options.env },
@@ -848,7 +849,7 @@ async function syncShareProjectSub(deploy, options) {
     const shareCustomDomains = typeof options.client.listPagesDomains === 'function'
         ? (await options.client.listPagesDomains(requestedName)).map((item) => clean(item.name)).filter(Boolean)
         : [];
-    const deployShareProject = async (projectName) => runPagesDeployAttempts(buildPagesDeployCommand(shareBundle.bundleDir, projectName), buildWranglerAuthEnv(options.credentials), resolveDeployProxyUrl(options.env), {
+    const deployShareProject = async (projectName) => runPagesDeployAttempts(buildPagesDeployCommand(options.wranglerExecutable, shareBundle.bundleDir, projectName), buildWranglerAuthEnv(options.credentials), resolveDeployProxyUrl(options.env), {
         cwd: shareBundle.bundleDir,
         runCommand: options.runCommand
     });
@@ -946,9 +947,15 @@ export async function deployPagesWithBackend(input, options = {}) {
             VPN_AUTOMATION_DEFAULT_PAGES_SECRET_ADMIN: getString(deploy, 'pages_secret_admin') || 'swimmingliu'
         };
         const credentials = resolveCloudflareCredentials(deploy, runtimeEnv);
-        const command = buildPagesDeployCommand(input.bundleDir, projectName);
         const baseEnv = buildWranglerAuthEnv(credentials);
         const runCommand = options.runCommand ?? ((commandToRun, runOptions) => runCommandWithSpawn(commandToRun, runOptions, options.spawn));
+        const wrangler = await (options.resolveManagedNpmTool ?? resolveManagedNpmTool)({
+            packageName: 'wrangler',
+            binaryName: 'wrangler',
+            version: '4.106.0',
+            projectRoot: input.projectRoot
+        });
+        const command = buildPagesDeployCommand(wrangler.command, input.bundleDir, projectName);
         const proxyUrl = resolveDeployProxyUrl(env);
         let activeCommand = command;
         let finalProjectName = projectName;
@@ -984,7 +991,7 @@ export async function deployPagesWithBackend(input, options = {}) {
                 await ensureCustomDomainBound(client, finalProjectName, customDomain, { previousProjectName: projectName });
                 customDomainBound = true;
             }
-            activeCommand = buildPagesDeployCommand(input.bundleDir, finalProjectName);
+            activeCommand = buildPagesDeployCommand(wrangler.command, input.bundleDir, finalProjectName);
             const fallbackDeploy = await runPagesDeployAttempts(activeCommand, baseEnv, proxyUrl, {
                 cwd: input.bundleDir,
                 runCommand
@@ -1010,7 +1017,8 @@ export async function deployPagesWithBackend(input, options = {}) {
                 credentials,
                 client,
                 env,
-                runCommand
+                runCommand,
+                wranglerExecutable: wrangler.command
             });
         }
         if (result.returncode === 0 && customDomain) {

package/dist/runtime/managed-tools.js

@@ -0,0 +1,269 @@
+import { spawn as defaultSpawn } from 'node:child_process';
+import path from 'node:path';
+import { access, mkdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolveUserRuntimeRoot } from './paths.js';
+export class ManagedToolError extends Error {
+    code;
+    constructor(message, code = 'MANAGED_TOOL_ERROR') {
+        super(message);
+        this.name = 'ManagedToolError';
+        this.code = code;
+    }
+}
+export async function resolveManagedNpmTool(options) {
+    const packageName = validatePackageName(options.packageName);
+    const binaryName = validateSinglePathPart(options.binaryName, 'binaryName');
+    const version = validateSinglePathPart(options.version, 'version');
+    const toolsRoot = path.resolve(options.toolsRoot ?? path.join(resolveUserRuntimeRoot(), 'tools'));
+    const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+    const timeoutMs = validateTimeoutMs(options.timeoutMs ?? 120000);
+    const platform = options.platform ?? process.platform;
+    const runCommand = options.runCommand ??
+        ((command, commandOptions) => runCommandWithSpawn(command, { ...commandOptions, timeoutMs }));
+    const managed = managedToolPaths(toolsRoot, packageName, version, binaryName);
+    const allowProjectFallback = options.allowProjectFallback ?? true;
+    const installMissing = options.installMissing ?? true;
+    const managedBinary = await firstExecutable(resolveManagedNpmToolBinaryCandidates(managed.binDir, binaryName, platform));
+    if (managedBinary) {
+        const verifiedVersion = await verifyToolVersion(managedBinary, managed.installDir, runCommand, 'managed');
+        return {
+            command: managedBinary,
+            args: [],
+            source: 'managed',
+            packageName,
+            version: verifiedVersion,
+            requestedVersion: version
+        };
+    }
+    if (allowProjectFallback) {
+        const projectBinDir = path.join(projectRoot, 'node_modules', '.bin');
+        const projectBinary = await firstExecutable(resolveManagedNpmToolBinaryCandidates(projectBinDir, binaryName, platform));
+        if (projectBinary) {
+            const verifiedVersion = await verifyToolVersion(projectBinary, projectRoot, runCommand, 'project');
+            return {
+                command: projectBinary,
+                args: [],
+                source: 'project',
+                packageName,
+                version: verifiedVersion,
+                requestedVersion: version
+            };
+        }
+    }
+    if (!installMissing) {
+        throw new ManagedToolError(`Managed npm tool ${packageName}@${version} is not installed`, 'MANAGED_TOOL_MISSING');
+    }
+    await installManagedTool(packageName, version, managed.installDir, runCommand);
+    const installedBinary = await firstExecutable(resolveManagedNpmToolBinaryCandidates(managed.binDir, binaryName, platform));
+    if (!installedBinary) {
+        throw new ManagedToolError(`npm install completed but ${binaryName} was not found at the managed tool path`, 'MANAGED_TOOL_BINARY_MISSING');
+    }
+    const verifiedVersion = await verifyToolVersion(installedBinary, managed.installDir, runCommand, 'managed');
+    return {
+        command: installedBinary,
+        args: [],
+        source: 'managed',
+        packageName,
+        version: verifiedVersion,
+        requestedVersion: version
+    };
+}
+export function resolveManagedNpmToolBinaryCandidates(binDir, binaryName, platform = process.platform) {
+    const safeBinaryName = validateSinglePathPart(binaryName, 'binaryName');
+    const primary = path.join(binDir, safeBinaryName);
+    if (platform === 'win32' && !safeBinaryName.toLowerCase().endsWith('.cmd')) {
+        return [primary, `${primary}.cmd`];
+    }
+    return [primary];
+}
+export function normalizeManagedToolCommandForSpawn(command, platform = process.platform) {
+    const [executable, ...args] = command;
+    if (platform === 'win32' && /\.(?:cmd|bat)$/i.test(executable)) {
+        return {
+            executable: 'cmd.exe',
+            args: ['/d', '/s', '/c', [executable, ...args].map(quoteWindowsCmdArgument).join(' ')]
+        };
+    }
+    return { executable, args };
+}
+function managedToolPaths(toolsRoot, packageName, version, binaryName) {
+    const installDir = path.join(toolsRoot, 'npm', packageName, version);
+    return {
+        installDir,
+        binDir: path.join(installDir, 'node_modules', '.bin')
+    };
+}
+async function installManagedTool(packageName, version, installDir, runCommand) {
+    await mkdir(installDir, { recursive: true });
+    let result;
+    try {
+        result = await runCommand(['npm', 'install', '--no-save', '--no-audit', '--no-fund', `${packageName}@${version}`], {
+            cwd: installDir,
+            env: { NPM_CONFIG_YES: 'true' }
+        });
+    }
+    catch (error) {
+        throw new ManagedToolError(`npm install failed for ${packageName}@${version}: ${safeErrorMessage(error)}`, 'MANAGED_TOOL_INSTALL_FAILED');
+    }
+    if (result.returncode !== 0) {
+        throw new ManagedToolError(`npm install failed for ${packageName}@${version}: ${safeCommandMessage(result)}`, 'MANAGED_TOOL_INSTALL_FAILED');
+    }
+}
+async function verifyToolVersion(binaryPath, cwd, runCommand, source) {
+    let result;
+    try {
+        result = await runCommand([binaryPath, '--version'], { cwd, env: {} });
+    }
+    catch (error) {
+        throw new ManagedToolError(`Managed npm tool ${source} verification failed: ${safeErrorMessage(error)}`, 'MANAGED_TOOL_VERSION_FAILED');
+    }
+    if (result.returncode !== 0) {
+        throw new ManagedToolError(`Managed npm tool ${source} verification failed: ${safeCommandMessage(result)}`, 'MANAGED_TOOL_VERSION_FAILED');
+    }
+    return firstOutputLine(result.stdout || result.stderr) || 'unknown';
+}
+async function isExecutable(filePath) {
+    try {
+        await access(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function firstExecutable(candidates) {
+    for (const candidate of candidates) {
+        if (await isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function runCommandWithSpawn(command, options, spawnImpl = defaultSpawn) {
+    const { executable, args } = normalizeManagedToolCommandForSpawn(command);
+    const child = spawnImpl(executable, args, {
+        cwd: options.cwd,
+        env: { ...process.env, ...options.env },
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => {
+        stdout += String(chunk);
+    });
+    child.stderr?.on('data', (chunk) => {
+        stderr += String(chunk);
+    });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            killTimedOutChild(child);
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            resolve({
+                returncode: 1,
+                stdout,
+                stderr: `${stderr}${stderr ? '\n' : ''}command timed out after ${options.timeoutMs}ms`
+            });
+        }, options.timeoutMs);
+        child.on('error', (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.on('close', (exitCode) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve({ returncode: exitCode ?? 1, stdout, stderr });
+        });
+    });
+}
+function quoteWindowsCmdArgument(value) {
+    const escaped = value.replace(/(["^&|<>()%!])/g, '^$1');
+    return `"${escaped}"`;
+}
+function firstOutputLine(value) {
+    return value.trim().split(/\r?\n/)[0]?.trim() ?? '';
+}
+function killTimedOutChild(child) {
+    if (process.platform !== 'win32' && child.pid) {
+        try {
+            process.kill(-child.pid, 'SIGKILL');
+            return;
+        }
+        catch {
+            // Fall back to killing the direct child below.
+        }
+    }
+    child.kill('SIGKILL');
+}
+function safeCommandMessage(result) {
+    const output = [result.stderr, result.stdout].filter((value) => value.trim()).join('\n').trim();
+    const message = output || `exit code ${result.returncode}`;
+    return truncate(message.replace(/\s+/g, ' '), 640);
+}
+function safeErrorMessage(error) {
+    if (error instanceof Error) {
+        return truncate(error.message.replace(/\s+/g, ' '), 640);
+    }
+    return truncate(String(error).replace(/\s+/g, ' '), 640);
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength)}...`;
+}
+function validatePackageName(value) {
+    const packageName = requireNonEmpty(value, 'packageName');
+    if (path.isAbsolute(packageName) || packageName.includes('\\')) {
+        throw new ManagedToolError('packageName contains unsafe path characters', 'MANAGED_TOOL_INVALID_OPTIONS');
+    }
+    const parts = packageName.split('/');
+    const scoped = packageName.startsWith('@');
+    if ((scoped && parts.length !== 2) || (!scoped && parts.length !== 1)) {
+        throw new ManagedToolError('packageName contains unsafe path segments', 'MANAGED_TOOL_INVALID_OPTIONS');
+    }
+    for (const part of parts) {
+        rejectUnsafePathPart(part, 'packageName');
+    }
+    return packageName;
+}
+function validateSinglePathPart(value, name) {
+    const part = requireNonEmpty(value, name);
+    if (path.isAbsolute(part) || part.includes('/') || part.includes('\\')) {
+        throw new ManagedToolError(`${name} contains unsafe path characters`, 'MANAGED_TOOL_INVALID_OPTIONS');
+    }
+    rejectUnsafePathPart(part, name);
+    return part;
+}
+function rejectUnsafePathPart(part, name) {
+    if (!part || part === '.' || part === '..') {
+        throw new ManagedToolError(`${name} contains unsafe path segments`, 'MANAGED_TOOL_INVALID_OPTIONS');
+    }
+}
+function validateTimeoutMs(value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new ManagedToolError('timeoutMs must be a positive number', 'MANAGED_TOOL_INVALID_OPTIONS');
+    }
+    return value;
+}
+function requireNonEmpty(value, name) {
+    const trimmed = String(value ?? '').trim();
+    if (!trimmed) {
+        throw new ManagedToolError(`${name} is required`, 'MANAGED_TOOL_INVALID_OPTIONS');
+    }
+    return trimmed;
+}