@pixelbyte-software/pixcode 1.40.5 → 1.40.8

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

@@ -1,4 +1,4 @@
-import { chmod, mkdtemp, writeFile } from 'node:fs/promises';
+import { access, chmod, mkdtemp, readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -9,6 +9,7 @@ const read = async (relativePath) => {
   const { readFile } = await import('node:fs/promises');
   return readFile(path.join(repoRoot, relativePath), 'utf8');
 };
+const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
 
 const appTypes = await read('src/types/app.ts');
 assert.ok(
@@ -113,6 +114,12 @@ assert.ok(
   managedRuntimes.includes("id === 'npm'") && managedRuntimes.includes('installNpmRuntime'),
   'Managed runtimes should include a Pixcode-owned npm runner for JavaScript projects when npm is not on PATH.',
 );
+assert.ok(
+  managedRuntimes.includes('buildPowerShellExpandArchiveArgs')
+    && managedRuntimes.includes('param([string]$archive, [string]$destination)')
+    && !managedRuntimes.includes('LiteralPath $args[0]'),
+  'Windows zip extraction should pass archive paths through a PowerShell param block instead of unreliable $args indexing.',
+);
 
 const serverIndex = await read('server/index.js');
 assert.ok(
@@ -134,6 +141,7 @@ const {
   startLiveView,
   stopLiveView,
 } = await import('../../server/services/live-view.js');
+const { ensureManagedRuntime, getManagedRuntimeStatus } = await import('../../server/services/managed-runtimes.js');
 const workspace = await mkdtemp(path.join(tmpdir(), 'pixcode-live-view-smoke-'));
 const staticProject = path.join(workspace, 'static');
 const viteProject = path.join(workspace, 'vite');
@@ -217,6 +225,164 @@ assert.equal(phpSystemRuntimeTarget.available, true, 'PHP projects should stay r
 assert.equal(phpSystemRuntimeTarget.command?.id, 'frankenphp-php-server', 'PHP projects should still use the Pixcode-managed runtime even when external php exists.');
 assert.equal(phpSystemRuntimeTarget.managedRuntime?.id, 'frankenphp', 'PHP projects should prefer the Pixcode-owned FrankenPHP runtime instead of external php.');
 
+const tar = await import('tar');
+const npmPackageRoot = path.join(workspace, 'npm-package-root');
+const npmPackageDir = path.join(npmPackageRoot, 'package');
+await mkdir(path.join(npmPackageDir, 'bin'), { recursive: true });
+await writeFile(path.join(npmPackageDir, 'package.json'), JSON.stringify({ name: 'npm', version: '10.0.0' }));
+await writeFile(path.join(npmPackageDir, 'bin', 'npm-cli.js'), '#!/usr/bin/env node\nconsole.log("npm smoke");\n');
+const npmTarball = path.join(workspace, 'npm-runtime.tgz');
+await tar.c({ cwd: npmPackageRoot, file: npmTarball, gzip: true }, ['package']);
+const npmTarballBuffer = await readFile(npmTarball);
+const originalFetch = globalThis.fetch;
+const metadataAcceptHeaders = [];
+globalThis.fetch = async (url, options = {}) => {
+  const requestUrl = String(url);
+  const headers = options.headers || {};
+  const accept = typeof headers.get === 'function' ? headers.get('Accept') : headers.Accept;
+  if (requestUrl === 'https://registry.test/npm/latest') {
+    metadataAcceptHeaders.push(String(accept || ''));
+    if (!String(accept || '').includes('application/json')) {
+      return new Response(JSON.stringify({ error: 'not acceptable' }), { status: 406 });
+    }
+    return new Response(JSON.stringify({
+      version: '10.0.0',
+      dist: { tarball: 'https://registry.test/npm/-/npm-10.0.0.tgz' },
+    }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+  }
+  if (requestUrl === 'https://registry.test/npm/-/npm-10.0.0.tgz') {
+    return new Response(npmTarballBuffer, { status: 200 });
+  }
+  return originalFetch(url, options);
+};
+try {
+  const npmRuntime = await ensureManagedRuntime('npm', {
+    preferManaged: true,
+    env: {
+      ...process.env,
+      PATH: '',
+      Path: '',
+      PIXCODE_MANAGED_RUNTIMES_HOME: path.join(workspace, 'managed-runtimes'),
+      PIXCODE_NPM_RUNTIME_REGISTRY: 'https://registry.test/npm/latest',
+    },
+  });
+  assert.equal(npmRuntime.status, 'installed', 'Managed npm runtime should install from npm registry metadata.');
+  assert.ok(
+    metadataAcceptHeaders.every((accept) => accept.includes('application/json')),
+    'Managed npm runtime metadata requests should use an npm-compatible JSON Accept header.',
+  );
+} finally {
+  globalThis.fetch = originalFetch;
+}
+
+const depsProject = path.join(workspace, 'vite-needs-install');
+await mkdir(depsProject, { recursive: true });
+await writeFile(path.join(depsProject, 'package.json'), JSON.stringify({
+  scripts: { dev: 'vite --host 127.0.0.1' },
+  dependencies: { vite: '^7.0.0' },
+}, null, 2));
+const fakeNpmCli = path.join(workspace, 'fake-npm-cli.js');
+await writeFile(fakeNpmCli, [
+  '#!/usr/bin/env node',
+  'const fs = require("node:fs");',
+  'const path = require("node:path");',
+  'if (process.argv[2] === "install") {',
+  '  fs.mkdirSync(path.join(process.cwd(), "node_modules", ".bin"), { recursive: true });',
+  '  fs.writeFileSync(path.join(process.cwd(), "node_modules", ".bin", process.platform === "win32" ? "vite.cmd" : "vite"), "ok");',
+  '  process.exit(0);',
+  '}',
+  'process.exit(0);',
+  '',
+].join('\n'));
+if (process.platform !== 'win32') {
+  await chmod(fakeNpmCli, 0o755);
+}
+const { preparePackageDependencies } = await import('../../server/services/live-view.js');
+const prepLogs = [];
+await preparePackageDependencies(
+  depsProject,
+  {
+    id: 'npm-dev-vite',
+    label: 'Vite dev server',
+    framework: 'Vite',
+    packageManager: 'npm',
+    scriptName: 'dev',
+    command: process.execPath,
+    args: [fakeNpmCli, 'run', 'dev'],
+    displayCommand: 'npm run dev',
+    managedRuntime: { id: 'npm', status: 'installed' },
+  },
+  process.env,
+  (line) => prepLogs.push(line),
+);
+assert.ok(
+  await fileExists(path.join(depsProject, 'node_modules', '.bin', process.platform === 'win32' ? 'vite.cmd' : 'vite')),
+  'Live View should install missing Vite project dependencies before running npm dev.',
+);
+assert.ok(
+  prepLogs.some((line) => line.includes('Installing project dependencies')),
+  'Live View should log dependency preparation before launching package scripts.',
+);
+
+const frankenPackageRoot = path.join(workspace, 'frankenphp-package-root');
+const frankenPackageDir = path.join(frankenPackageRoot, 'package');
+await mkdir(frankenPackageDir, { recursive: true });
+await writeFile(path.join(frankenPackageDir, process.platform === 'win32' ? 'frankenphp.exe' : 'frankenphp'), '#!/bin/sh\nexit 0\n');
+await writeFile(path.join(frankenPackageDir, 'sidecar-runtime.dll'), 'sidecar');
+if (process.platform !== 'win32') {
+  await chmod(path.join(frankenPackageDir, 'frankenphp'), 0o755);
+}
+const frankenTarball = path.join(workspace, 'frankenphp-runtime.tgz');
+await tar.c({ cwd: frankenPackageRoot, file: frankenTarball, gzip: true }, ['package']);
+const frankenTarballBuffer = await readFile(frankenTarball);
+globalThis.fetch = async (url) => {
+  if (String(url) === 'https://runtime.test/frankenphp-runtime.tgz') {
+    return new Response(frankenTarballBuffer, { status: 200 });
+  }
+  return originalFetch(url);
+};
+try {
+  const frankenHome = path.join(workspace, 'managed-frankenphp');
+  const frankenRuntime = await ensureManagedRuntime('frankenphp', {
+    preferManaged: true,
+    env: {
+      ...process.env,
+      PIXCODE_MANAGED_RUNTIMES_HOME: frankenHome,
+      PIXCODE_FRANKENPHP_URL: 'https://runtime.test/frankenphp-runtime.tgz',
+    },
+  });
+  assert.equal(frankenRuntime.status, 'installed', 'Managed FrankenPHP runtime should install from the downloaded archive.');
+  assert.ok(
+    await fileExists(path.join(frankenHome, 'frankenphp', 'current', 'sidecar-runtime.dll')),
+    'Managed FrankenPHP install should preserve sidecar DLLs/files next to the executable.',
+  );
+} finally {
+  globalThis.fetch = originalFetch;
+}
+
+const brokenRuntimeHome = path.join(workspace, 'broken-frankenphp');
+const brokenCurrent = path.join(brokenRuntimeHome, 'frankenphp', 'current');
+await mkdir(brokenCurrent, { recursive: true });
+const brokenExecutable = path.join(brokenCurrent, process.platform === 'win32' ? 'frankenphp.cmd' : 'frankenphp');
+await writeFile(brokenExecutable, process.platform === 'win32' ? '@echo off\r\nexit /b 1\r\n' : '#!/bin/sh\nexit 1\n');
+if (process.platform !== 'win32') {
+  await chmod(brokenExecutable, 0o755);
+}
+await writeFile(path.join(brokenRuntimeHome, 'frankenphp', 'pixcode-runtime.json'), JSON.stringify({
+  id: 'frankenphp',
+  label: 'Pixcode PHP runtime',
+  executablePath: brokenExecutable,
+  version: 'broken',
+}, null, 2));
+const brokenStatus = await getManagedRuntimeStatus('frankenphp', {
+  preferManaged: true,
+  env: {
+    ...process.env,
+    PIXCODE_MANAGED_RUNTIMES_HOME: brokenRuntimeHome,
+  },
+});
+assert.equal(brokenStatus.status, 'missing', 'Broken managed FrankenPHP manifests should be treated as missing so Pixcode can reinstall them.');
+
 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/scripts/smoke/orchestration-model-sync.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+
+const page = readFileSync('src/components/orchestration/OrchestrationPage.tsx', 'utf8');
+const runner = readFileSync('server/modules/orchestration/workflows/workflow-runner.ts', 'utf8');
+
+assert.ok(
+  page.includes("from '../../hooks/useProviderModels'") || page.includes('from "@/hooks/useProviderModels"'),
+  'Orchestration page should use the same live provider model catalog hook as chat.',
+);
+
+assert.ok(
+  page.includes('providerModelCatalogs') && page.includes('sanitizeAgentModel'),
+  'Orchestration agents should sanitize stale selected models against the live catalog before starting runs.',
+);
+
+assert.ok(
+  runner.includes('resolveWorkflowModel') && runner.includes('modelCatalogsByProvider'),
+  'Workflow runner should validate provider models server-side before submitting A2A tasks.',
+);
+
+assert.ok(
+  runner.includes('Original user request')
+    && runner.indexOf('Original user request') < runner.lastIndexOf('workspaceContextPrompt(workspaceTarget)'),
+  'Workflow runner should place a labeled original user request before workspace context so agents do not answer the context header.',
+);
+
+console.log('orchestration model sync smoke passed');

package/scripts/smoke/provider-models-opencode-live.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { mkdtemp } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const tempHome = await mkdtemp(path.join(os.tmpdir(), 'pixcode-provider-models-'));
+process.env.HOME = tempHome;
+process.env.OPENCODE_MODELS_URL = 'https://models.dev/test-api.json';
+
+const calls = [];
+globalThis.fetch = async (url) => {
+  calls.push(String(url));
+  return {
+    ok: true,
+    status: 200,
+    async json() {
+      return {
+        opencode: {
+          name: 'OpenCode Zen',
+          models: {
+            'big-pickle': {
+              name: 'Big Pickle',
+              cost: { input: 0, output: 0 },
+              limit: { context: 128000 },
+            },
+            'fresh-free': {
+              name: 'Fresh Free',
+              cost: { input: 0, output: 0 },
+              limit: { context: 64000 },
+            },
+          },
+        },
+      };
+    },
+  };
+};
+
+const { getProviderModels } = await import('../../server/services/provider-models.js');
+
+const staleStatic = [
+  { value: 'opencode/hy3-preview-free', label: 'Stale Hy3 Preview' },
+  { value: 'opencode/ling-2.6-flash-free', label: 'Stale Ling 2.6 Flash' },
+];
+
+const refreshed = await getProviderModels('opencode', {
+  forceRefresh: true,
+  staticList: staleStatic,
+});
+const refreshedValues = refreshed.models.map((model) => model.value);
+assert.equal(calls.length, 1, 'force refresh should fetch the OpenCode live catalog once');
+assert.ok(refreshedValues.includes('opencode/fresh-free'), 'live OpenCode models should be returned');
+assert.ok(!refreshedValues.includes('opencode/hy3-preview-free'), 'stale static OpenCode models must not be merged into a successful live catalog');
+assert.ok(!refreshedValues.includes('opencode/ling-2.6-flash-free'), 'stale static OpenCode models must not survive a successful live refresh');
+
+const cached = await getProviderModels('opencode', {
+  staticList: staleStatic,
+});
+const cachedValues = cached.models.map((model) => model.value);
+assert.equal(calls.length, 1, 'fresh cache should be used without another network request');
+assert.ok(cachedValues.includes('opencode/fresh-free'), 'cached live OpenCode models should be returned');
+assert.ok(!cachedValues.includes('opencode/hy3-preview-free'), 'cached live OpenCode catalog must stay free of stale static models');
+assert.ok(!cachedValues.includes('opencode/ling-2.6-flash-free'), 'cached live OpenCode catalog must stay free of stale static models');
+
+console.log('provider OpenCode live model catalog smoke passed');

package/server/modules/orchestration/workflows/workflow-runner.ts

@@ -13,6 +13,17 @@ import {
   workspaceTargetMetadata,
 } from '@/modules/orchestration/workflows/workspace-target.js';
 import { workflowStore } from '@/modules/orchestration/workflows/workflow-store.js';
+// @ts-ignore — plain-JS service
+import { getProviderModels } from '@/services/provider-models.js';
+
+import {
+  CLAUDE_MODELS,
+  CODEX_MODELS,
+  CURSOR_MODELS,
+  GEMINI_MODELS,
+  OPENCODE_MODELS,
+  QWEN_MODELS,
+} from '../../../../shared/modelConstants.js';
 
 const TERMINAL = new Set(['completed', 'failed', 'canceled']);
 const SKIPPED = 'skipped';
@@ -106,6 +117,34 @@ type AgentAssignment = {
 
 type KnownAgentRole = typeof KNOWN_AGENT_ROLES[number];
 type AgentRole = string;
+type ProviderId = 'claude' | 'cursor' | 'codex' | 'gemini' | 'qwen' | 'opencode';
+type ProviderModel = {
+  value: string;
+  label?: string;
+  source?: 'static' | 'api';
+  free?: boolean;
+};
+
+const adapterProviderMap: Record<string, ProviderId | undefined> = {
+  'claude-code': 'claude',
+  cursor: 'cursor',
+  codex: 'codex',
+  gemini: 'gemini',
+  qwen: 'qwen',
+  opencode: 'opencode',
+};
+
+const modelCatalogsByProvider: Record<ProviderId, {
+  staticList: ProviderModel[];
+  defaultModel?: string;
+}> = {
+  claude: { staticList: CLAUDE_MODELS.OPTIONS, defaultModel: CLAUDE_MODELS.DEFAULT },
+  cursor: { staticList: CURSOR_MODELS.OPTIONS, defaultModel: CURSOR_MODELS.DEFAULT },
+  codex: { staticList: CODEX_MODELS.OPTIONS, defaultModel: CODEX_MODELS.DEFAULT },
+  gemini: { staticList: GEMINI_MODELS.OPTIONS, defaultModel: GEMINI_MODELS.DEFAULT },
+  qwen: { staticList: QWEN_MODELS.OPTIONS, defaultModel: QWEN_MODELS.DEFAULT },
+  opencode: { staticList: OPENCODE_MODELS.OPTIONS, defaultModel: OPENCODE_MODELS.DEFAULT },
+};
 
 function readAgentRole(value: unknown): AgentRole | undefined {
   return typeof value === 'string' && value.trim() && value.trim() !== 'auto'
@@ -133,6 +172,44 @@ function readBoolean(value: unknown): boolean | undefined {
   return typeof value === 'boolean' ? value : undefined;
 }
 
+function modelValueSet(models: ProviderModel[]): Set<string> {
+  return new Set(models.map((model) => model.value).filter(Boolean));
+}
+
+function preferredFallbackModel(models: ProviderModel[], defaultModel?: string): string | undefined {
+  const values = modelValueSet(models);
+  if (defaultModel && values.has(defaultModel)) return defaultModel;
+  return models.find((model) => model.source === 'api' && model.free)?.value
+    ?? models.find((model) => model.source === 'api')?.value
+    ?? models.find((model) => model.free)?.value
+    ?? models[0]?.value
+    ?? defaultModel;
+}
+
+async function resolveWorkflowModel(adapterId: string, requestedModel?: string): Promise<string | undefined> {
+  const provider = adapterProviderMap[adapterId];
+  if (!provider) return requestedModel;
+
+  const catalog = modelCatalogsByProvider[provider];
+  if (!requestedModel) return catalog.defaultModel;
+
+  try {
+    const result = await getProviderModels(provider, {
+      staticList: catalog.staticList,
+    });
+    const models = Array.isArray(result?.models) ? result.models as ProviderModel[] : [];
+    if (modelValueSet(models).has(requestedModel)) {
+      return requestedModel;
+    }
+    return preferredFallbackModel(models, catalog.defaultModel) ?? requestedModel;
+  } catch {
+    const staticValues = modelValueSet(catalog.staticList);
+    return staticValues.has(requestedModel)
+      ? requestedModel
+      : preferredFallbackModel(catalog.staticList, catalog.defaultModel) ?? requestedModel;
+  }
+}
+
 function readIsolation(value: unknown): 'host' | 'worktree' | 'docker' | undefined {
   return value === 'host' || value === 'worktree' || value === 'docker' ? value : undefined;
 }
@@ -1408,15 +1485,42 @@ class WorkflowRunner {
 
     const inputContext = node.inputs.map((input) => outputs.get(input)).filter(Boolean).join('\n\n');
     const workspaceTarget = resolveWorkflowWorkspace(run.metadata);
-    const prompt = [workspaceContextPrompt(workspaceTarget), run.input, inputContext, node.prompt]
-      .filter(Boolean)
-      .join('\n\n');
+    const prompt = [
+      'Original user request (primary task; answer this directly even if the workspace is empty):',
+      run.input?.trim() || '(No original user request was provided.)',
+      inputContext
+        ? `Upstream workflow context from prior agents:\n${inputContext}`
+        : '',
+      `Current workflow step instructions:\n${node.prompt}`,
+      workspaceContextPrompt(workspaceTarget),
+    ].filter(Boolean).join('\n\n');
     const settings = getMetadataRecord(run.metadata, 'settings');
     const projectPath = workspaceTarget.projectPath;
     const isolation = readIsolation(settings.isolation) ?? node.isolation ?? 'host';
     const keepAfterCompletion = readBoolean(settings.keepWorkspace) ?? true;
     const baseRef = readString(settings.baseRef) ?? 'HEAD';
     const effectivePermissionMode = resolveNodePermissionMode(node, workspaceTarget);
+    const effectiveModel = await resolveWorkflowModel(node.adapterId, node.model);
+    if (effectiveModel !== node.model) {
+      nodeRun.model = effectiveModel;
+      const modelFallbackEvents = Array.isArray(run.metadata?.modelFallbackEvents)
+        ? run.metadata.modelFallbackEvents
+        : [];
+      run.metadata = {
+        ...run.metadata,
+        modelFallbackEvents: [
+          ...modelFallbackEvents,
+          {
+            nodeId: node.id,
+            adapterId: node.adapterId,
+            requestedModel: node.model,
+            effectiveModel,
+            changedAt: Date.now(),
+          },
+        ],
+      };
+      workflowStore.setRun(run);
+    }
     let body: { id?: string; error?: { message?: string } };
     try {
       const submit = await fetch(`${localA2ABaseUrl()}/tasks`, {
@@ -1436,7 +1540,7 @@ class WorkflowRunner {
             agentInstanceId: node.agentInstanceId,
             agentLabel: node.agentLabel,
             assignment: node.assignment,
-            model: node.model,
+            model: effectiveModel,
             permissionMode: effectivePermissionMode,
             toolsSettings: node.toolsSettings,
             projectPath,

package/server/services/live-view.js

@@ -208,6 +208,120 @@ function buildManagedPackageCommand(command, runtimeStatus) {
   };
 }
 
+function packageBinCandidates(binName) {
+  return process.platform === 'win32'
+    ? [binName, `${binName}.cmd`, `${binName}.ps1`, `${binName}.exe`]
+    : [binName];
+}
+
+function expectedPackageBin(command) {
+  if (command.framework === 'Vite' || command.id === 'npm-dev-vite') return 'vite';
+  if (command.framework === 'Next.js' || command.id === 'npm-dev-next') return 'next';
+  if (command.framework === 'Nuxt' || command.id === 'npm-dev-nuxt') return 'nuxt';
+  if (command.framework === 'Astro' || command.id === 'npm-dev-astro') return 'astro';
+  return null;
+}
+
+async function packageDependenciesReady(projectPath, command) {
+  if (!command?.scriptName && !command?.packageManager) return true;
+  if (!(await dirExists(path.join(projectPath, 'node_modules')))) return false;
+
+  const binName = expectedPackageBin(command);
+  if (!binName) return true;
+
+  const binDir = path.join(projectPath, 'node_modules', '.bin');
+  for (const candidate of packageBinCandidates(binName)) {
+    if (await fileExists(path.join(binDir, candidate))) return true;
+  }
+  return false;
+}
+
+function packageInstallInvocation(command) {
+  if (!command || command.packageManager !== 'npm') return null;
+
+  if (
+    command.managedRuntime?.id === 'npm'
+    && command.args?.[0]
+    && String(command.args[0]).endsWith('npm-cli.js')
+  ) {
+    return {
+      command: command.command,
+      args: [command.args[0], 'install', '--no-audit', '--no-fund'],
+      displayCommand: 'npm install --no-audit --no-fund',
+    };
+  }
+
+  if (command.command === 'npm' || path.basename(command.command || '').startsWith('npm')) {
+    return {
+      command: command.command,
+      args: ['install', '--no-audit', '--no-fund'],
+      displayCommand: 'npm install --no-audit --no-fund',
+    };
+  }
+
+  return null;
+}
+
+function runPrepProcess(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      shell: shouldUseShell({ command }),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    const timeoutMs = Number.parseInt(process.env.PIXCODE_LIVE_VIEW_INSTALL_TIMEOUT_MS || '', 10) || 300000;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      callback(value);
+    };
+    const timer = setTimeout(() => {
+      try {
+        child.kill();
+      } catch {
+        // Process may already be gone.
+      }
+      finish(reject, new Error(`Dependency install timed out after ${Math.round(timeoutMs / 1000)}s.`));
+    }, timeoutMs);
+
+    child.stdout.on('data', (chunk) => {
+      chunk.toString().split(/\r?\n/).forEach((line) => options.onLog?.(line));
+    });
+    child.stderr.on('data', (chunk) => {
+      chunk.toString().split(/\r?\n/).forEach((line) => options.onLog?.(line));
+    });
+    child.on('error', (error) => finish(reject, error));
+    child.on('exit', (code, signal) => {
+      if (code === 0) {
+        finish(resolve);
+        return;
+      }
+      finish(reject, new Error(`Dependency install exited with ${signal || `code ${code}`}.`));
+    });
+  });
+}
+
+export async function preparePackageDependencies(projectPath, command, env = process.env, onLog = () => {}) {
+  if (!command || command.packageManager !== 'npm') return false;
+  if (await packageDependenciesReady(projectPath, command)) return false;
+
+  const install = packageInstallInvocation(command);
+  if (!install) return false;
+
+  onLog(`Installing project dependencies: ${install.displayCommand}`);
+  await runPrepProcess(install.command, install.args, {
+    cwd: projectPath,
+    env,
+    onLog,
+  });
+  onLog('Project dependencies are ready.');
+  return true;
+}
+
 function buildManagedPhpCommand(runtimeStatus) {
   const executable = runtimeStatus?.executablePath || 'frankenphp';
   return {
@@ -718,6 +832,20 @@ export async function startLiveView(projectName, projectPath, options = {}) {
     BROWSER: 'none',
     NEXT_TELEMETRY_DISABLED: '1',
   };
+
+  sessionsByProject.set(projectName, session);
+  sessionsByShareId.set(shareId, session);
+
+  try {
+    await preparePackageDependencies(projectPath, command, env, (line) => appendLog(session, line));
+  } catch (error) {
+    session.status = 'error';
+    session.stoppedAt = new Date().toISOString();
+    session.error = error instanceof Error ? error.message : String(error);
+    appendLog(session, session.error);
+    return publicSession(session);
+  }
+
   const child = spawn(command.command, command.args, {
     cwd: projectPath,
     env,
@@ -726,8 +854,6 @@ export async function startLiveView(projectName, projectPath, options = {}) {
   });
 
   session.child = child;
-  sessionsByProject.set(projectName, session);
-  sessionsByShareId.set(shareId, session);
 
   child.stdout.on('data', (chunk) => {
     chunk.toString().split(/\r?\n/).forEach((line) => appendLog(session, line));