Enable worktree-based development with auto port detection

- Add findFreePort() to auto-detect available ports 3000-3099
- If PORT env var is set, use it explicitly (fail if busy)
- If PORT is unset, auto-find next free port starting from 3000
- Write .port file so tooling can discover running instance
- Update Playwright config to read PORT from env var
- Add .env, .env.local, .port to .gitignore for per-worktree isolation

This enables multiple independent instances to run on the same machine, each in its own git worktree with automatic port allocation.

Author: H1D

.gitignore

@@ -10,5 +10,10 @@ explore-site.mjs
 public/js/app.js
 public/js/app.js.map
 
+# Per-worktree environment config
+.env
+.env.local
+.port
+
 # Local Netlify folder
 .netlify

playwright.config.ts

@@ -1,15 +1,17 @@
 import { defineConfig } from '@playwright/test';
 
+const PORT = Number(process.env.PORT) || 3000;
+
 export default defineConfig({
   testDir: './e2e',
   timeout: 15000,
   use: {
-    baseURL: 'http://localhost:3000',
+    baseURL: `http://localhost:${PORT}`,
     headless: true,
   },
   webServer: {
-    command: 'bun run start',
-    port: 3000,
+    command: `PORT=${PORT} bun run start`,
+    port: PORT,
     reuseExistingServer: true,
   },
 });

src/server.ts

@@ -1,6 +1,23 @@
-const PORT = Number(process.env.PORT) || 3000;
+const PREFERRED_PORT = Number(process.env.PORT) || 3000;
 const PUBLIC_DIR = new URL("../public", import.meta.url).pathname;
 
+function findFreePort(start: number): number {
+  for (let port = start; port < start + 100; port++) {
+    try {
+      const probe = Bun.serve({ port, fetch: () => new Response() });
+      probe.stop(true);
+      return port;
+    } catch {
+      // Port busy, try next
+    }
+  }
+  throw new Error(`No free port found in range ${start}–${start + 99}`);
+}
+
+const PORT = process.env.PORT
+  ? PREFERRED_PORT // Explicit PORT: use exactly, fail if busy
+  : findFreePort(PREFERRED_PORT); // No PORT set: auto-find free port
+
 const MIME_TYPES: Record<string, string> = {
   ".html": "text/html",
   ".css": "text/css",
@@ -51,7 +68,7 @@ function respond(body: BodyInit, contentType: string): Response {
   });
 }
 
-Bun.serve({
+const server = Bun.serve({
   port: PORT,
   async fetch(req) {
     const url = new URL(req.url);
@@ -72,4 +89,6 @@ Bun.serve({
   },
 });
 
-console.log(`EasyPDF Lite running at http://localhost:${PORT}`);
+// Write port file for tooling (Playwright, etc.) to discover the running instance
+await Bun.write(`${import.meta.dir}/../.port`, String(server.port));
+console.log(`EasyPDF Lite running at http://localhost:${server.port}`);