feat(ux): report back to user on install in process (#33)

Author: gorillamoe

backend/bun/src/index.ts

@@ -11,7 +11,91 @@ import type {
   NodeHTMLToImageBuffer,
 } from "./types";
 
+import { checkPuppeteerInstalled, installPuppeteer } from "./utils/puppeteer";
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * Handles the health check command
+ * Returns JSON with information about whether Puppeteer is installed
+ */
+const handleHealth = async () => {
+  const cacheDir = path.join(os.homedir(), ".cache", "puppeteer");
+  const { isInstalled, executablePath } = checkPuppeteerInstalled(cacheDir);
+
+  writeJSONToStdout({
+    success: true,
+    debug: false,
+    data: {
+      isInstalled,
+      executablePath,
+    },
+  });
+};
+
+/**
+ * Handles the install command
+ * Installs Puppeteer and sends progress updates as JSON (one line per update)
+ */
+const handleInstall = async () => {
+  const cacheDir = path.join(os.homedir(), ".cache", "puppeteer");
+
+  const progressCallback = (progress: {
+    status: string;
+    message: string;
+    progress?: number;
+  }) => {
+    // Send progress update as JSON on a single line
+    // Write directly - process.stdout.write is non-blocking by default
+    const progressJson = JSON.stringify({
+      success: true,
+      debug: false,
+      data: {
+        type: JSONRequestType.Install,
+        status: progress.status,
+        message: progress.message,
+        progress: progress.progress,
+      },
+    });
+    process.stdout.write(progressJson + "\n");
+  };
+
+  const executablePath = await installPuppeteer(cacheDir, progressCallback);
+
+  if (executablePath) {
+    writeJSONToStdout({
+      success: true,
+      debug: false,
+      data: {
+        type: JSONRequestType.Install,
+        status: "completed",
+        message: "Browser installation completed successfully",
+        executablePath,
+      },
+    });
+  } else {
+    writeJSONToStdout({
+      success: false,
+      error: "Failed to install browser",
+    });
+  }
+};
+
 const main = async () => {
+  // Check for command line arguments
+  const args = process.argv.slice(2);
+  if (args.length > 0) {
+    const command = args[0];
+    if (command === "health") {
+      await handleHealth();
+      return;
+    } else if (command === "install") {
+      await handleInstall();
+      return;
+    }
+  }
+
+  // Default behavior: read from stdin
   const jsonPayload = await getJSONFromStdin();
 
   if ("error" in jsonPayload) {

backend/bun/src/types/index.ts

@@ -7,6 +7,8 @@ export const enum JSONRequestType {
   CodeImageGeneration = "image",
   CodeHTMLGeneration = "html",
   CodeRTFGeneration = "rtf",
+  Health = "health",
+  Install = "install",
 }
 
 interface FontSettingsFont {

backend/bun/src/utils/puppeteer.ts

@@ -14,6 +14,15 @@ import {
 } from "@puppeteer/browsers";
 import { writeJSONToStdout } from "./stdin";
 
+/**
+ * Progress callback type for install operations
+ */
+export type InstallProgressCallback = (progress: {
+  status: string;
+  message: string;
+  progress?: number;
+}) => void;
+
 /**
  * Gets the executable path for the installed Chrome browser.
  * @param cacheDir - The cache directory where browsers are stored
@@ -31,7 +40,6 @@ const getInstalledBrowserPath = (cacheDir: string): string | null => {
     const browserPlatform =
       platformMap[currentPlatform] || BrowserPlatform.LINUX;
 
-    // Try to get the latest installed browser
     const cache = new Cache(cacheDir);
     const installedBrowsers = cache.getInstalledBrowsers();
     const chromeBrowser = installedBrowsers.find(
@@ -57,14 +65,9 @@ const getInstalledBrowserPath = (cacheDir: string): string | null => {
  * Sets up Puppeteer cache directory and ensures browser is installed.
  * This is necessary when running in a bundled binary where the default
  * cache path might not be accessible.
- * Uses platform-specific default cache directories:
- * - Windows: %LOCALAPPDATA%\puppeteer
- * - macOS: ~/Library/Caches/puppeteer
- * - Linux: ~/.cache/puppeteer
  * @returns The executable path of the installed browser, or null if not found
  */
 export const setupPuppeteer = async (): Promise<string | null> => {
-  // Use platform-specific default cache directory
   const cacheDir = path.join(os.homedir(), ".cache", "puppeteer");
 
   // Ensure the cache directory exists
@@ -138,3 +141,149 @@ export const setupPuppeteer = async (): Promise<string | null> => {
 
   return executablePath;
 };
+
+/**
+ * Checks if Puppeteer browser is installed
+ * @param cacheDir - The cache directory where browsers are stored
+ * @returns Object with isInstalled boolean and executablePath if installed
+ */
+export const checkPuppeteerInstalled = (
+  cacheDir: string,
+): { isInstalled: boolean; executablePath: string | null } => {
+  try {
+    const executablePath = getInstalledBrowserPath(cacheDir);
+    if (executablePath && existsSync(executablePath)) {
+      return { isInstalled: true, executablePath };
+    }
+
+    try {
+      const puppeteerPath = puppeteer.executablePath();
+      if (puppeteerPath && existsSync(puppeteerPath)) {
+        return { isInstalled: true, executablePath: puppeteerPath };
+      }
+    } catch (/* eslint-disable-line */ error) {
+      // Browser is not installed
+    }
+
+    return { isInstalled: false, executablePath: null };
+  } catch (/* eslint-disable-line */ error) {
+    return { isInstalled: false, executablePath: null };
+  }
+};
+
+/**
+ * Installs Puppeteer browser with progress updates
+ * @param cacheDir - The cache directory where browsers are stored
+ * @param progressCallback - Callback function to report progress
+ * @returns The executable path of the installed browser, or null if installation failed
+ */
+export const installPuppeteer = async (
+  cacheDir: string,
+  progressCallback?: InstallProgressCallback,
+): Promise<string | null> => {
+  try {
+    await mkdir(cacheDir, { recursive: true });
+
+    const platformMap: Record<string, BrowserPlatform> = {
+      win32: BrowserPlatform.WIN32,
+      darwin: BrowserPlatform.MAC,
+      linux: BrowserPlatform.LINUX,
+    };
+
+    const currentPlatform = process.platform;
+    const browserPlatform =
+      platformMap[currentPlatform] || BrowserPlatform.LINUX;
+
+    if (progressCallback) {
+      progressCallback({
+        status: "resolving",
+        message: "Resolving requirements ...",
+      });
+    }
+
+    const buildId = await resolveBuildId(
+      Browser.CHROME,
+      browserPlatform,
+      BrowserTag.LATEST,
+    );
+
+    if (progressCallback) {
+      progressCallback({
+        status: "installing",
+        message: `Installing requirements ...`,
+        progress: 0,
+      });
+    }
+
+    const installStartTime = Date.now();
+    let periodicUpdateInterval: NodeJS.Timeout | null = null;
+    let isInstalling = true;
+
+    if (progressCallback) {
+      periodicUpdateInterval = setInterval(() => {
+        if (!isInstalling || !progressCallback) {
+          return;
+        }
+
+        const elapsedSeconds = Math.floor(
+          (Date.now() - installStartTime) / 1000,
+        );
+
+        progressCallback({
+          status: "installing",
+          message: `Still installing ... (${elapsedSeconds}s elapsed)`,
+          progress: undefined,
+        });
+      }, 5000);
+    }
+
+    try {
+      await install({
+        browser: Browser.CHROME,
+        buildId: buildId,
+        cacheDir: cacheDir,
+      });
+
+      isInstalling = false;
+      if (periodicUpdateInterval) {
+        clearInterval(periodicUpdateInterval);
+        periodicUpdateInterval = null;
+      }
+    } catch (installErr) {
+      isInstalling = false;
+      if (periodicUpdateInterval) {
+        clearInterval(periodicUpdateInterval);
+        periodicUpdateInterval = null;
+      }
+      throw installErr;
+    }
+
+    if (progressCallback) {
+      progressCallback({
+        status: "completed",
+        message: "Requirements installed successfully.",
+        progress: 100,
+      });
+    }
+
+    const executablePath = computeExecutablePath({
+      cacheDir: cacheDir,
+      browser: Browser.CHROME,
+      platform: browserPlatform,
+      buildId: buildId,
+    });
+
+    return executablePath;
+  } catch (installError) {
+    if (progressCallback) {
+      progressCallback({
+        status: "error",
+        message:
+          installError instanceof Error
+            ? installError.message
+            : String(installError),
+      });
+    }
+    return null;
+  }
+};