race condition in cleanup + better JSDoc in config + dockerfile formatting

Author: Kylejeong2

Dockerfile

@@ -2,23 +2,23 @@
 FROM node:lts-alpine AS builder
 WORKDIR /app
 
-# Copy package and configuration
-COPY package.json pnpm-lock.yaml tsconfig.json ./
+# Copy package files first for dependency caching
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
 
-# Copy source code
+# Copy configuration and source code
+COPY tsconfig.json ./
 COPY src ./src
-
-# Copy config files
 COPY config.d.ts index.d.ts ./
 
-# Install dependencies and build
-RUN corepack enable && pnpm install --frozen-lockfile && pnpm build
+# Build the application
+RUN pnpm build
 
 # ----- Production Stage -----
 FROM node:lts-alpine
 WORKDIR /app
 
-# Copy package.json and install production dependencies
+# Copy package files and install production dependencies
 COPY package.json pnpm-lock.yaml ./
 RUN corepack enable && pnpm install --prod --frozen-lockfile --ignore-scripts
 

config.d.ts

@@ -40,7 +40,8 @@ export type Config = {
     persist?: boolean;
   };
   /**
-   *
+   * The viewport of the browser
+   * @default { browserWidth: 1024, browserHeight: 768 }
    */
   viewPort?: {
     /**
@@ -58,16 +59,30 @@ export type Config = {
    */
   cookies?: Cookie[];
   /**
-   * Whether or not to port to a server
+   * Server configuration for MCP transport layer
+   *
+   * Controls how the MCP server binds and listens for connections.
+   * When port is specified, the server will start an SHTTP transport.
+   * When both port and host are undefined, the server uses stdio transport.
    *
+   * Security considerations:
+   * - Use localhost (default) for local development
+   * - Use 0.0.0.0 only when you need external access and have proper security measures
+   * - Consider firewall rules and network security when exposing the server
    */
   server?: {
     /**
      * The port to listen on for SHTTP or MCP transport.
+     * If undefined, uses stdio transport instead of HTTP.
+     *
+     * @example 3000
      */
     port?: number;
     /**
-     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
+     * The host to bind the server to.
+     *
+     * @default "localhost" - Only accepts local connections
+     * @example "0.0.0.0" - Accepts connections from any interface (use with caution)
      */
     host?: string;
   };

src/program.ts

@@ -85,8 +85,11 @@ program
 function setupExitWatchdog(serverList: ServerList) {
   const handleExit = async () => {
     setTimeout(() => process.exit(0), 15000);
-    await stagehandStore.removeAll();
-    await serverList.closeAll();
+    try {
+      await Promise.all([stagehandStore.removeAll(), serverList.closeAll()]);
+    } catch (error) {
+      console.error("Error during cleanup:", error);
+    }
     process.exit(0);
   };