@pixelbyte-software/pixcode 1.40.2 → 1.40.4

package/dist-server/server/services/managed-runtimes.js

@@ -0,0 +1,313 @@
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildCliSpawnEnv, findExecutableOnPath } from './install-jobs.js';
+const DEFAULT_RUNTIMES_HOME = path.join(os.homedir(), '.pixcode', 'runtimes');
+const MANIFEST_FILE = 'pixcode-runtime.json';
+const installLocks = new Map();
+function runtimesHome(env = process.env) {
+    return env.PIXCODE_MANAGED_RUNTIMES_HOME || DEFAULT_RUNTIMES_HOME;
+}
+function runtimeDir(id, env = process.env) {
+    return path.join(runtimesHome(env), id);
+}
+function manifestPath(id, env = process.env) {
+    return path.join(runtimeDir(id, env), MANIFEST_FILE);
+}
+async function fileExists(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function readManifest(id, env = process.env) {
+    try {
+        const content = await fs.readFile(manifestPath(id, env), 'utf8');
+        const manifest = JSON.parse(content);
+        if (manifest?.executablePath && await fileExists(manifest.executablePath)) {
+            return manifest;
+        }
+    }
+    catch {
+        // Missing or malformed manifests are treated as not installed.
+    }
+    return null;
+}
+function platformTokens() {
+    if (process.platform === 'win32')
+        return ['windows'];
+    if (process.platform === 'darwin')
+        return ['mac', 'darwin'];
+    if (process.platform === 'linux')
+        return ['linux'];
+    return [process.platform];
+}
+function archTokens() {
+    if (process.arch === 'x64')
+        return ['x86_64', 'amd64', 'x64'];
+    if (process.arch === 'arm64')
+        return ['aarch64', 'arm64'];
+    return [process.arch];
+}
+function scoreFrankenPhpAsset(assetName) {
+    const name = assetName.toLowerCase();
+    if (!name.includes('frankenphp'))
+        return -1;
+    if (name.includes('debug'))
+        return -1;
+    if (!platformTokens().some((token) => name.includes(token)))
+        return -1;
+    if (!archTokens().some((token) => name.includes(token)))
+        return -1;
+    let score = 10;
+    if (process.platform === 'win32' && name.endsWith('.zip'))
+        score += 10;
+    if (process.platform !== 'win32' && !name.endsWith('.zip'))
+        score += 10;
+    if (!name.includes('gnu'))
+        score += 2;
+    if (name.endsWith('.tar.gz') || name.endsWith('.tgz'))
+        score += 1;
+    return score;
+}
+function selectFrankenPhpAsset(release) {
+    const assets = Array.isArray(release?.assets) ? release.assets : [];
+    const candidates = assets
+        .map((asset) => ({ asset, score: scoreFrankenPhpAsset(asset.name || '') }))
+        .filter((entry) => entry.score >= 0)
+        .sort((a, b) => b.score - a.score);
+    return candidates[0]?.asset || null;
+}
+async function fetchJson(url, env = process.env) {
+    const headers = {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'Pixcode Live View',
+    };
+    if (env.GITHUB_TOKEN)
+        headers.Authorization = `Bearer ${env.GITHUB_TOKEN}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`Runtime metadata request failed with HTTP ${response.status}`);
+    }
+    return response.json();
+}
+async function downloadFile(url, targetFile, env = process.env) {
+    const headers = { 'User-Agent': 'Pixcode Live View' };
+    if (env.GITHUB_TOKEN && url.includes('github.com'))
+        headers.Authorization = `Bearer ${env.GITHUB_TOKEN}`;
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`Runtime download failed with HTTP ${response.status}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    await fs.writeFile(targetFile, buffer);
+}
+function runProcess(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        let stderr = '';
+        const child = spawn(command, args, {
+            ...options,
+            stdio: ['ignore', 'ignore', 'pipe'],
+            windowsHide: true,
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`${command} exited with code ${code}${stderr ? `: ${stderr.trim()}` : ''}`));
+        });
+    });
+}
+async function extractZip(archivePath, targetDir, env = process.env) {
+    if (process.platform === 'win32') {
+        const shell = env.ComSpec || process.env.ComSpec || 'powershell.exe';
+        const isCmd = shell.toLowerCase().endsWith('cmd.exe');
+        if (isCmd) {
+            await runProcess('powershell.exe', [
+                '-NoProfile',
+                '-ExecutionPolicy',
+                'Bypass',
+                '-Command',
+                'Expand-Archive -Force -LiteralPath $args[0] -DestinationPath $args[1]',
+                archivePath,
+                targetDir,
+            ], { env });
+            return;
+        }
+        await runProcess(shell, [
+            '-NoProfile',
+            '-ExecutionPolicy',
+            'Bypass',
+            '-Command',
+            'Expand-Archive -Force -LiteralPath $args[0] -DestinationPath $args[1]',
+            archivePath,
+            targetDir,
+        ], { env });
+        return;
+    }
+    await runProcess('unzip', ['-q', archivePath, '-d', targetDir], { env });
+}
+async function extractTarGz(archivePath, targetDir, env = process.env) {
+    await runProcess('tar', ['-xzf', archivePath, '-C', targetDir], { env });
+}
+async function findRuntimeExecutable(searchRoot, binaryName) {
+    const expectedNames = process.platform === 'win32'
+        ? [`${binaryName}.exe`, binaryName]
+        : [binaryName];
+    const stack = [searchRoot];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            if (entry.isFile() && expectedNames.includes(entry.name)) {
+                return full;
+            }
+        }
+    }
+    return null;
+}
+async function installFrankenPhp(env = process.env) {
+    const releaseApiUrl = env.PIXCODE_FRANKENPHP_RELEASE_API
+        || 'https://api.github.com/repos/php/frankenphp/releases/latest';
+    const release = env.PIXCODE_FRANKENPHP_URL ? null : await fetchJson(releaseApiUrl, env);
+    const asset = env.PIXCODE_FRANKENPHP_URL
+        ? {
+            name: path.basename(new URL(env.PIXCODE_FRANKENPHP_URL).pathname),
+            browser_download_url: env.PIXCODE_FRANKENPHP_URL,
+        }
+        : selectFrankenPhpAsset(release);
+    if (!asset?.browser_download_url) {
+        throw new Error('No FrankenPHP binary is available for this operating system and CPU architecture.');
+    }
+    const baseDir = runtimeDir('frankenphp', env);
+    const stagingDir = path.join(baseDir, `.staging-${Date.now()}`);
+    const currentDir = path.join(baseDir, 'current');
+    await fs.mkdir(stagingDir, { recursive: true });
+    const archivePath = path.join(stagingDir, asset.name || 'frankenphp');
+    await downloadFile(asset.browser_download_url, archivePath, env);
+    let executablePath = archivePath;
+    const assetName = (asset.name || '').toLowerCase();
+    if (assetName.endsWith('.zip')) {
+        await extractZip(archivePath, stagingDir, env);
+        executablePath = await findRuntimeExecutable(stagingDir, 'frankenphp');
+        if (!executablePath) {
+            throw new Error('Downloaded FrankenPHP archive did not contain a frankenphp executable.');
+        }
+    }
+    else if (assetName.endsWith('.tar.gz') || assetName.endsWith('.tgz')) {
+        await extractTarGz(archivePath, stagingDir, env);
+        executablePath = await findRuntimeExecutable(stagingDir, 'frankenphp');
+        if (!executablePath) {
+            throw new Error('Downloaded FrankenPHP archive did not contain a frankenphp executable.');
+        }
+    }
+    if (process.platform !== 'win32') {
+        await fs.chmod(executablePath, 0o755).catch(() => undefined);
+    }
+    await fs.rm(currentDir, { recursive: true, force: true });
+    await fs.mkdir(currentDir, { recursive: true });
+    const finalName = process.platform === 'win32' ? 'frankenphp.exe' : 'frankenphp';
+    const finalExecutable = path.join(currentDir, finalName);
+    await fs.copyFile(executablePath, finalExecutable);
+    if (process.platform !== 'win32') {
+        await fs.chmod(finalExecutable, 0o755).catch(() => undefined);
+    }
+    const manifest = {
+        id: 'frankenphp',
+        label: 'Pixcode PHP runtime',
+        provider: 'FrankenPHP',
+        version: release?.tag_name || 'custom',
+        executablePath: finalExecutable,
+        sourceUrl: asset.browser_download_url,
+        installedAt: new Date().toISOString(),
+    };
+    await fs.writeFile(manifestPath('frankenphp', env), JSON.stringify(manifest, null, 2));
+    await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+    return manifest;
+}
+export async function getManagedRuntimeStatus(id, options = {}) {
+    const env = options.env || process.env;
+    if (id !== 'frankenphp') {
+        return {
+            id,
+            status: 'unsupported',
+            installable: false,
+            reason: 'Pixcode does not have a managed runtime for this stack yet.',
+        };
+    }
+    const spawnEnv = buildCliSpawnEnv(env);
+    const systemExecutable = findExecutableOnPath('frankenphp', spawnEnv);
+    if (systemExecutable) {
+        return {
+            id,
+            label: 'FrankenPHP',
+            status: 'system',
+            installable: true,
+            executablePath: systemExecutable,
+        };
+    }
+    const manifest = await readManifest(id, env);
+    if (manifest) {
+        return {
+            id,
+            label: manifest.label || 'Pixcode PHP runtime',
+            status: 'installed',
+            installable: true,
+            executablePath: manifest.executablePath,
+            version: manifest.version,
+        };
+    }
+    return {
+        id,
+        label: 'Pixcode PHP runtime',
+        provider: 'FrankenPHP',
+        status: 'missing',
+        installable: true,
+        reason: 'Pixcode will prepare a local PHP runtime automatically before starting this project.',
+    };
+}
+export async function ensureManagedRuntime(id, options = {}) {
+    const env = options.env || process.env;
+    const status = await getManagedRuntimeStatus(id, { env });
+    if (status.executablePath)
+        return status;
+    if (!status.installable) {
+        throw new Error(status.reason || 'This runtime cannot be prepared automatically.');
+    }
+    const lockKey = `${runtimesHome(env)}:${id}`;
+    if (installLocks.has(lockKey))
+        return installLocks.get(lockKey);
+    const installPromise = (async () => {
+        if (id === 'frankenphp') {
+            const manifest = await installFrankenPhp(env);
+            return {
+                id,
+                label: manifest.label,
+                status: 'installed',
+                installable: true,
+                executablePath: manifest.executablePath,
+                version: manifest.version,
+            };
+        }
+        throw new Error(`Unsupported managed runtime: ${id}`);
+    })().finally(() => {
+        installLocks.delete(lockKey);
+    });
+    installLocks.set(lockKey, installPromise);
+    return installPromise;
+}
+//# sourceMappingURL=managed-runtimes.js.map

package/dist-server/server/services/managed-runtimes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-runtimes.js","sourceRoot":"","sources":["../../../server/services/managed-runtimes.js"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelbyte-software/pixcode",
-  "version": "1.40.2",
+  "version": "1.40.4",
   "description": "Self-hosted AI coding agent control room for Claude Code, Cursor CLI, OpenAI Codex, Gemini CLI, Qwen Code, and OpenCode with chat, files, shell, Git, orchestration, API keys, Telegram, MCP, plugins, themes, and desktop/server deployment.",
   "type": "module",
   "main": "dist-server/server/index.js",

package/scripts/smoke/live-view-integration.mjs

@@ -79,11 +79,29 @@ assert.ok(
   liveViewPanel.includes('sessionError') && liveViewPanel.includes('status.session.error'),
   'Live View panel should show the actual runner error instead of only an error badge.',
 );
+assert.ok(
+  liveViewPanel.includes('targetUnavailableReason') && liveViewPanel.includes('liveView.runnerUnavailable'),
+  'Live View panel should show a clear unavailable-runner message before launching a missing runtime.',
+);
+assert.ok(
+  liveViewPanel.includes('managedRuntime') && liveViewPanel.includes('liveView.managedRuntimePreparing'),
+  'Live View panel should explain that Pixcode can prepare managed runtimes automatically.',
+);
 assert.ok(
   liveViewPanel.includes("runAction('restart')"),
   'Live View panel should expose a restart action for failed process runners.',
 );
 
+const managedRuntimes = await read('server/services/managed-runtimes.js');
+assert.ok(
+  managedRuntimes.includes("process.platform === 'win32'") && managedRuntimes.includes("process.platform === 'darwin'") && managedRuntimes.includes("process.platform === 'linux'"),
+  'Managed runtime selection should explicitly handle Windows, macOS, and Linux assets.',
+);
+assert.ok(
+  managedRuntimes.includes('extractZip') && managedRuntimes.includes('extractTarGz'),
+  'Managed runtime installation should handle common Windows zip and macOS/Linux tarball assets.',
+);
+
 const serverIndex = await read('server/index.js');
 assert.ok(
   serverIndex.includes("app.use('/api/live-view', authenticateToken, liveViewRoutes)"),
@@ -108,6 +126,7 @@ const workspace = await mkdtemp(path.join(tmpdir(), 'pixcode-live-view-smoke-'))
 const staticProject = path.join(workspace, 'static');
 const viteProject = path.join(workspace, 'vite');
 const djangoProject = path.join(workspace, 'django');
+const phpProject = path.join(workspace, 'php');
 await writeFile(path.join(staticProject, 'index.html'), '<main>hello</main>', { recursive: true }).catch(async (error) => {
   if (error.code !== 'ENOENT') throw error;
   const { mkdir } = await import('node:fs/promises');
@@ -122,6 +141,8 @@ await writeFile(path.join(viteProject, 'package.json'), JSON.stringify({
 }, null, 2));
 await mkdir(djangoProject, { recursive: true });
 await writeFile(path.join(djangoProject, 'manage.py'), '#!/usr/bin/env python\n');
+await mkdir(phpProject, { recursive: true });
+await writeFile(path.join(phpProject, 'index.php'), '<?php echo "hello";');
 
 const staticTarget = await detectLiveViewTarget(staticProject);
 assert.equal(staticTarget.available, true, 'Static HTML projects should be available.');
@@ -135,6 +156,22 @@ const djangoTarget = await detectLiveViewTarget(djangoProject);
 assert.equal(djangoTarget.available, true, 'Django projects should be detected from manage.py.');
 assert.equal(djangoTarget.command?.id, 'python-django', 'Django projects should get a runserver command.');
 
+const phpMissingRuntimeTarget = await detectLiveViewTarget(phpProject, {
+  env: {
+    ...process.env,
+    PATH: '',
+  },
+});
+assert.equal(phpMissingRuntimeTarget.available, true, 'PHP projects should remain runnable through a Pixcode-managed runtime when php is missing from PATH.');
+assert.equal(phpMissingRuntimeTarget.framework, 'PHP', 'Missing PHP runtime diagnostics should keep the detected framework.');
+assert.equal(phpMissingRuntimeTarget.managedRuntime?.id, 'frankenphp', 'Missing PHP should select the Pixcode-managed FrankenPHP runtime.');
+assert.equal(phpMissingRuntimeTarget.managedRuntime?.status, 'missing', 'Missing PHP should report that the managed runtime still needs preparation.');
+assert.equal(phpMissingRuntimeTarget.command?.id, 'frankenphp-php-server', 'Missing PHP should use a managed FrankenPHP server command.');
+assert.ok(
+  !/PATH/i.test(phpMissingRuntimeTarget.reason || ''),
+  'Missing PHP should use product language instead of exposing PATH setup as the primary message.',
+);
+
 const staticSession = await startLiveView('static-smoke', staticProject);
 assert.equal(staticSession.status, 'running', 'Static Live View should start without a child process.');
 assert.match(staticSession.sharePath, /^\/live\/[a-f0-9]{24}\/$/, 'Live View should expose a random public share path.');

package/server/routes/live-view.js

@@ -50,8 +50,8 @@ function buildLiveViewSuggestions(session, reason) {
   const suggestions = [];
 
   if (framework.includes('php')) {
-    suggestions.push('Run `php --version` in the same machine and make sure the PHP executable is available in PATH.');
-    suggestions.push('If PHP is installed outside PATH, use Live View custom command with the full php executable path.');
+    suggestions.push('Pixcode can prepare a local PHP runtime automatically and keep it under your user profile.');
+    suggestions.push('If the automatic runtime download fails, check the Live View panel logs and retry.');
     suggestions.push('Check that the project has an index.php or a valid PHP router file in the selected project root.');
   } else if (
     framework.includes('javascript')

package/server/services/live-view.js

@@ -4,10 +4,13 @@ import { promises as fs } from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 
+import { ensureManagedRuntime, getManagedRuntimeStatus } from './managed-runtimes.js';
+
 const sessionsByProject = new Map();
 const sessionsByShareId = new Map();
 const READY_TIMEOUT_MS = 12000;
 const LOG_LIMIT = 200;
+const RUNTIME_CHECK_TIMEOUT_MS = 1800;
 
 const localUrlRegex = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[[^\]]+\])(?::(\d+))?[^\s"'<>]*/i;
 
@@ -78,6 +81,88 @@ function buildDisplayCommand(command, args) {
   return [command, ...args].join(' ');
 }
 
+function quoteForPosixShell(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function quoteForWindowsShell(value) {
+  return `"${String(value).replaceAll('"', '""')}"`;
+}
+
+function isPathLikeCommand(command) {
+  return path.isAbsolute(command) || command.includes('/') || command.includes('\\');
+}
+
+function runtimeMissingReason(command, framework) {
+  const base = `${command} is not available on this machine.`;
+  if (framework === 'PHP' || command === 'php') {
+    return 'Pixcode can prepare a local PHP runtime automatically before starting this project.';
+  }
+  if (command === 'npm' || command === 'pnpm' || command === 'yarn' || command === 'bun') {
+    return `${base} Pixcode will use its bundled Node runtime when possible; otherwise install the package manager or use a custom command.`;
+  }
+  if (command === 'python' || command === 'python3') {
+    return `${base} Pixcode does not have a managed Python runtime for this stack yet.`;
+  }
+  return `${base} Pixcode does not have a managed ${framework || command} runtime for this stack yet.`;
+}
+
+async function checkCommandAvailability(command, env = process.env) {
+  if (!command || command.includes('\n') || command.includes('\r')) return true;
+
+  if (isPathLikeCommand(command)) {
+    try {
+      await fs.access(command);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  const checker = process.platform === 'win32'
+    ? {
+      command: process.env.ComSpec || 'cmd.exe',
+      args: ['/d', '/s', '/c', `where ${quoteForWindowsShell(command)}`],
+    }
+    : {
+      command: '/bin/sh',
+      args: ['-lc', `command -v ${quoteForPosixShell(command)}`],
+    };
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let child = null;
+    const finish = (available) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(available);
+    };
+
+    const timer = setTimeout(() => {
+      try {
+        child?.kill();
+      } catch {
+        // Ignore a raced process exit.
+      }
+      finish(true);
+    }, RUNTIME_CHECK_TIMEOUT_MS);
+
+    child = spawn(checker.command, checker.args, {
+      env,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+
+    child.on('error', (error) => {
+      finish(error?.code === 'ENOENT' ? false : true);
+    });
+    child.on('exit', (code) => {
+      finish(code === 0);
+    });
+  });
+}
+
 function buildPackageCommand(packageManager, scriptName, id, label, framework, extraArgs = []) {
   const args = packageRunArgs(packageManager, scriptName, extraArgs);
   return {
@@ -90,6 +175,25 @@ function buildPackageCommand(packageManager, scriptName, id, label, framework, e
   };
 }
 
+function buildManagedPhpCommand(runtimeStatus) {
+  const executable = runtimeStatus?.executablePath || 'frankenphp';
+  return {
+    id: 'frankenphp-php-server',
+    label: 'Pixcode PHP runtime',
+    framework: 'PHP',
+    command: executable,
+    args: ['php-server', '-r', '.'],
+    displayCommand: `${executable} php-server -r .`,
+    env: {
+      SERVER_NAME: 'http://127.0.0.1:$PORT',
+    },
+    managedRuntime: {
+      id: 'frankenphp',
+      status: runtimeStatus?.status || 'missing',
+    },
+  };
+}
+
 function detectPackageCommand(packageJson, packageManager) {
   const scripts = packageJson.scripts || {};
   const devScript = String(scripts.dev || '');
@@ -160,9 +264,22 @@ function withPort(command, port) {
     ...command,
     args: command.args.map((arg) => arg.replaceAll('$PORT', String(port))),
     displayCommand: command.displayCommand.replaceAll('$PORT', String(port)),
+    env: command.env
+      ? Object.fromEntries(Object.entries(command.env).map(([key, value]) => [
+        key,
+        String(value).replaceAll('$PORT', String(port)),
+      ]))
+      : undefined,
   };
 }
 
+function shouldUseShell(command) {
+  if (command.shell) return true;
+  if (process.platform !== 'win32') return false;
+  if (path.isAbsolute(command.command) && command.command.toLowerCase().endsWith('.exe')) return false;
+  return true;
+}
+
 async function detectStaticRoot(projectPath) {
   const candidates = [
     projectPath,
@@ -286,7 +403,7 @@ async function detectProcessCommand(projectPath) {
   return null;
 }
 
-export async function detectLiveViewTarget(projectPath) {
+export async function detectLiveViewTarget(projectPath, options = {}) {
   if (!projectPath || !(await dirExists(projectPath))) {
     return {
       available: false,
@@ -297,6 +414,35 @@ export async function detectLiveViewTarget(projectPath) {
 
   const processCommand = await detectProcessCommand(projectPath);
   if (processCommand) {
+    const runtimeAvailable = await checkCommandAvailability(processCommand.command, options.env || process.env);
+    if (!runtimeAvailable) {
+      if (processCommand.framework === 'PHP' || processCommand.command === 'php') {
+        const managedRuntime = await getManagedRuntimeStatus('frankenphp', { env: options.env || process.env });
+        const command = buildManagedPhpCommand(managedRuntime);
+        return {
+          available: true,
+          kind: 'process',
+          label: command.label,
+          framework: command.framework,
+          command,
+          managedRuntime,
+          reason: managedRuntime.status === 'missing'
+            ? 'Pixcode will prepare a local PHP runtime automatically before starting this project.'
+            : 'Pixcode will run this project with its managed PHP runtime.',
+        };
+      }
+
+      return {
+        available: false,
+        kind: 'process',
+        label: processCommand.label,
+        framework: processCommand.framework,
+        command: processCommand,
+        missingRuntime: processCommand.command,
+        reason: runtimeMissingReason(processCommand.command, processCommand.framework),
+      };
+    }
+
     return {
       available: true,
       kind: 'process',
@@ -387,6 +533,7 @@ function publicSession(session) {
       label: session.command.label,
       displayCommand: session.command.displayCommand,
     } : null,
+    managedRuntime: session.managedRuntime || null,
     port: session.port,
     upstreamUrl: session.upstreamUrl,
     startedAt: session.startedAt,
@@ -468,7 +615,16 @@ export async function startLiveView(projectName, projectPath, options = {}) {
   }
 
   const port = await findFreePort();
-  const command = withPort(target.command, port);
+  let runtimeStatus = target.managedRuntime || target.command?.managedRuntime || null;
+  let targetCommand = target.command;
+  if (runtimeStatus?.id && runtimeStatus.status !== 'system' && runtimeStatus.status !== 'installed') {
+    runtimeStatus = await ensureManagedRuntime(runtimeStatus.id);
+    if (runtimeStatus.id === 'frankenphp') {
+      targetCommand = buildManagedPhpCommand(runtimeStatus);
+    }
+  }
+
+  const command = withPort(targetCommand, port);
   const session = {
     projectName,
     projectPath,
@@ -478,6 +634,7 @@ export async function startLiveView(projectName, projectPath, options = {}) {
     framework: target.framework,
     label: target.label,
     command,
+    managedRuntime: runtimeStatus,
     port,
     host: '127.0.0.1',
     upstreamUrl: `http://127.0.0.1:${port}`,
@@ -493,6 +650,7 @@ export async function startLiveView(projectName, projectPath, options = {}) {
 
   const env = {
     ...process.env,
+    ...(command.env || {}),
     PORT: String(port),
     HOST: '127.0.0.1',
     VITE_HOST: '127.0.0.1',
@@ -503,7 +661,7 @@ export async function startLiveView(projectName, projectPath, options = {}) {
   const child = spawn(command.command, command.args, {
     cwd: projectPath,
     env,
-    shell: Boolean(command.shell) || process.platform === 'win32',
+    shell: shouldUseShell(command),
     stdio: ['ignore', 'pipe', 'pipe'],
   });