@pixelbyte-software/pixcode 1.40.1 → 1.40.3

package/server/routes/live-view.js

@@ -31,6 +31,162 @@ function buildUrls(req, session) {
   };
 }
 
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+function latestErrorFromLogs(logs) {
+  return [...logs].reverse().find((line) => /error|enoent|eaddrinuse|failed|fatal|exception/i.test(line)) || null;
+}
+
+function buildLiveViewSuggestions(session, reason) {
+  const framework = String(session?.framework || session?.label || '').toLowerCase();
+  const status = String(session?.status || '').toLowerCase();
+  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('Check that the project has an index.php or a valid PHP router file in the selected project root.');
+  } else if (
+    framework.includes('javascript')
+    || framework.includes('vite')
+    || framework.includes('next')
+    || framework.includes('nuxt')
+    || framework.includes('astro')
+    || framework.includes('react')
+    || framework.includes('node')
+  ) {
+    suggestions.push('Run the project command in a terminal first and confirm it opens a local HTTP port.');
+    suggestions.push('Install project dependencies if node_modules is missing, then retry Live View.');
+    suggestions.push('If the dev server ignores PORT, set a custom command that binds to 127.0.0.1 and the chosen port.');
+  } else {
+    suggestions.push('Run the displayed command in a terminal and fix the first process error shown there.');
+    suggestions.push('Use a custom command if Pixcode detected the wrong runner for this project.');
+  }
+
+  if (status === 'starting' || reason === 'upstream_not_ready') {
+    suggestions.push('Wait for the app to finish booting, then press Refresh or Restart if the port never opens.');
+  }
+
+  if (reason === 'proxy_failed') {
+    suggestions.push('The Live View session exists, but Pixcode could not reach the local upstream URL.');
+  }
+
+  return suggestions;
+}
+
+export function buildLiveViewUnavailablePayload(session, options = {}) {
+  const logs = Array.isArray(session?.log) ? session.log.slice(-40) : [];
+  const errorDetail = options.errorMessage || session?.error || latestErrorFromLogs(logs);
+  const label = session?.label || session?.framework || 'Live View';
+  const status = session?.status || 'missing';
+
+  return {
+    error: 'Live View session is not available.',
+    message: `${label} is ${status}.`,
+    reason: options.reason || status,
+    status,
+    framework: session?.framework || null,
+    label,
+    projectName: session?.projectName || null,
+    shareId: session?.shareId || options.shareId || null,
+    sharePath: session?.sharePath || null,
+    upstreamUrl: session?.upstreamUrl || null,
+    port: session?.port || null,
+    errorDetail,
+    diagnostics: {
+      command: session?.command?.displayCommand || null,
+      upstreamUrl: session?.upstreamUrl || null,
+      port: session?.port || null,
+      startedAt: session?.startedAt || null,
+      stoppedAt: session?.stoppedAt || null,
+      exitCode: session?.exitCode ?? null,
+      exitSignal: session?.exitSignal ?? null,
+      logs,
+    },
+    suggestions: buildLiveViewSuggestions(session, options.reason),
+  };
+}
+
+export function renderLiveViewDiagnosticHtml(payload) {
+  const suggestions = payload.suggestions?.length
+    ? payload.suggestions.map((item) => `<li>${escapeHtml(item)}</li>`).join('')
+    : '<li>Open the Live View panel, check the latest logs, and restart the session.</li>';
+  const logs = payload.diagnostics?.logs?.length
+    ? payload.diagnostics.logs.map((line) => escapeHtml(line)).join('\n')
+    : 'No process logs were captured yet.';
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Pixcode Live View diagnostics</title>
+  <style>
+    :root { color-scheme: light dark; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    body { margin: 0; min-height: 100vh; background: #0b0f14; color: #e5edf5; }
+    main { box-sizing: border-box; max-width: 980px; margin: 0 auto; padding: 32px 20px; }
+    .eyebrow { color: #f97316; font-size: 12px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; }
+    h1 { margin: 8px 0 10px; font-size: clamp(26px, 5vw, 44px); line-height: 1.05; }
+    p { color: #a8b3c2; line-height: 1.6; }
+    section { margin-top: 18px; border: 1px solid rgba(148, 163, 184, .24); border-radius: 12px; background: rgba(15, 23, 42, .72); padding: 16px; }
+    dl { display: grid; grid-template-columns: minmax(110px, 180px) minmax(0, 1fr); gap: 10px 14px; margin: 0; }
+    dt { color: #94a3b8; font-size: 12px; text-transform: uppercase; }
+    dd { margin: 0; overflow-wrap: anywhere; }
+    pre { margin: 0; max-height: 280px; overflow: auto; white-space: pre-wrap; color: #dbeafe; background: #020617; border-radius: 10px; padding: 14px; }
+    code { color: #bfdbfe; }
+    li { margin: 8px 0; color: #d0d8e4; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="eyebrow">Pixcode Live View</div>
+    <h1>${escapeHtml(payload.message)}</h1>
+    <p>${escapeHtml(payload.errorDetail || 'The preview link is active, but the local runner is not ready.')}</p>
+    <section>
+      <dl>
+        <dt>Status</dt><dd>${escapeHtml(payload.status)}</dd>
+        <dt>Framework</dt><dd>${escapeHtml(payload.framework || 'Unknown')}</dd>
+        <dt>Command</dt><dd><code>${escapeHtml(payload.diagnostics?.command || 'No command captured')}</code></dd>
+        <dt>Upstream</dt><dd>${escapeHtml(payload.upstreamUrl || 'Not ready')}</dd>
+        <dt>Share ID</dt><dd>${escapeHtml(payload.shareId || 'Unknown')}</dd>
+      </dl>
+    </section>
+    <section>
+      <h2>What to check</h2>
+      <ul>${suggestions}</ul>
+    </section>
+    <section>
+      <h2>Process logs</h2>
+      <pre>${logs}</pre>
+    </section>
+  </main>
+</body>
+</html>`;
+}
+
+function requestPrefersHtml(req) {
+  const accept = req.header('accept') || '';
+  return accept.includes('text/html') || (!accept.includes('application/json') && accept.includes('*/*'));
+}
+
+function sendLiveViewDiagnostic(req, res, session, statusCode, options = {}) {
+  const payload = buildLiveViewUnavailablePayload(session, options);
+  res.status(statusCode);
+  if (requestPrefersHtml(req)) {
+    res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+    res.type('html').send(renderLiveViewDiagnosticHtml(payload));
+    return;
+  }
+  res.json(payload);
+}
+
 async function resolveProjectPath(projectName) {
   const projectPath = await extractProjectDirectory(projectName);
   if (!projectPath || typeof projectPath !== 'string') {
@@ -139,7 +295,10 @@ async function sendStaticLiveView(req, res, session) {
 
 async function proxyLiveView(req, res, session) {
   if (!session.upstreamUrl) {
-    res.status(503).json({ error: 'Live View upstream is not ready yet.' });
+    sendLiveViewDiagnostic(req, res, session, 503, {
+      reason: 'upstream_not_ready',
+      errorMessage: 'Live View upstream is not ready yet.',
+    });
     return;
   }
 
@@ -161,7 +320,10 @@ async function proxyLiveView(req, res, session) {
     });
     res.send(Buffer.from(await upstream.arrayBuffer()));
   } catch (error) {
-    res.status(502).json({ error: error.message || 'Live View proxy failed' });
+    sendLiveViewDiagnostic(req, res, session, 502, {
+      reason: 'proxy_failed',
+      errorMessage: error.message || 'Live View proxy failed',
+    });
   }
 }
 
@@ -170,8 +332,31 @@ export function createLiveViewPublicRouter() {
 
   publicRouter.use('/:shareId', async (req, res) => {
     const session = getLiveViewSessionByShareId(req.params.shareId);
-    if (!session || session.status === 'stopped' || session.status === 'error') {
-      res.status(404).json({ error: 'Live View session not found.' });
+    if (!session) {
+      sendLiveViewDiagnostic(req, res, {
+        shareId: req.params.shareId,
+        status: 'missing',
+        label: 'Live View session',
+        log: [],
+      }, 404, {
+        reason: 'missing_session',
+        errorMessage: 'This preview link does not match an active Live View session on this Pixcode server.',
+      });
+      return;
+    }
+
+    if (session.status === 'error') {
+      sendLiveViewDiagnostic(req, res, session, 502, { reason: 'session_error' });
+      return;
+    }
+
+    if (session.status === 'stopped') {
+      sendLiveViewDiagnostic(req, res, session, 410, { reason: 'session_stopped' });
+      return;
+    }
+
+    if (session.status === 'starting') {
+      sendLiveViewDiagnostic(req, res, session, 202, { reason: 'upstream_not_ready' });
       return;
     }
 

package/server/services/live-view.js

@@ -8,6 +8,7 @@ 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 +79,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} executable was not found in PATH.`;
+  if (framework === 'PHP' || command === 'php') {
+    return `${base} Install PHP and add php.exe to PATH, or use a custom command with the full PHP executable path.`;
+  }
+  if (command === 'npm' || command === 'pnpm' || command === 'yarn' || command === 'bun') {
+    return `${base} Install Node.js/package manager support or use a custom command with the full executable path.`;
+  }
+  if (command === 'python' || command === 'python3') {
+    return `${base} Install Python and add it to PATH, or use a custom command with the full Python executable path.`;
+  }
+  return `${base} Install ${framework || command} or use a custom command with the full executable path.`;
+}
+
+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 {
@@ -286,7 +369,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 +380,19 @@ export async function detectLiveViewTarget(projectPath) {
 
   const processCommand = await detectProcessCommand(projectPath);
   if (processCommand) {
+    const runtimeAvailable = await checkCommandAvailability(processCommand.command, options.env || process.env);
+    if (!runtimeAvailable) {
+      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',
@@ -391,6 +487,9 @@ function publicSession(session) {
     upstreamUrl: session.upstreamUrl,
     startedAt: session.startedAt,
     stoppedAt: session.stoppedAt,
+    exitCode: session.exitCode ?? null,
+    exitSignal: session.exitSignal ?? null,
+    spawnErrorCode: session.spawnErrorCode ?? null,
     error: session.error,
     log: session.log.slice(-40),
   };
@@ -453,6 +552,9 @@ export async function startLiveView(projectName, projectPath, options = {}) {
       upstreamUrl: null,
       startedAt: new Date().toISOString(),
       stoppedAt: null,
+      exitCode: null,
+      exitSignal: null,
+      spawnErrorCode: null,
       error: null,
       log: [`Serving static files from ${path.relative(projectPath, target.staticRoot) || '.'}`],
     };
@@ -477,6 +579,9 @@ export async function startLiveView(projectName, projectPath, options = {}) {
     upstreamUrl: `http://127.0.0.1:${port}`,
     startedAt: new Date().toISOString(),
     stoppedAt: null,
+    exitCode: null,
+    exitSignal: null,
+    spawnErrorCode: null,
     error: null,
     log: [`$ ${command.displayCommand}`],
     child: null,
@@ -511,11 +616,14 @@ export async function startLiveView(projectName, projectPath, options = {}) {
   child.on('error', (error) => {
     session.status = 'error';
     session.error = error.message;
+    session.spawnErrorCode = error.code || null;
     appendLog(session, `process error: ${error.message}`);
   });
   child.on('exit', (code, signal) => {
     session.status = code === 0 ? 'stopped' : 'error';
     session.stoppedAt = new Date().toISOString();
+    session.exitCode = code;
+    session.exitSignal = signal;
     session.error = code === 0 ? null : `Process exited with ${signal || `code ${code}`}`;
     appendLog(session, session.error || 'Process stopped.');
   });