Add Gomplate language tooling

web/apps/playground/plugins/eval-server.ts

@@ -1,13 +1,53 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { createServer } from "node:net";
 import type { Plugin } from "vite";
 
 export interface EvalServerOptions {
   /** Repository root, where `go run` is invoked. */
   repoRoot: string;
+  /** Loopback host the Go server listens on. */
+  host: string;
   /** Port the Go server listens on. */
   port: number;
 }
 
+interface AvailablePortOptions {
+  host: string;
+  preferredPort: number;
+}
+
+export async function findAvailablePort({
+  host,
+  preferredPort,
+}: AvailablePortOptions): Promise<number> {
+  const preferred = await tryPort(host, preferredPort);
+  if (preferred !== undefined) return preferred;
+
+  const available = await tryPort(host, 0);
+  if (available === undefined) throw new Error("operating system did not allocate a loopback port");
+  return available;
+}
+
+function tryPort(host: string, port: number): Promise<number | undefined> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", (error: NodeJS.ErrnoException) => {
+      if (error.code === "EADDRINUSE") resolve(undefined);
+      else reject(error);
+    });
+    server.listen(port, host, () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close();
+        reject(new Error(`could not resolve allocated loopback port for ${host}`));
+        return;
+      }
+      server.close((error) => (error ? reject(error) : resolve(address.port)));
+    });
+  });
+}
+
 /**
  * Runs `go run ./cmd/playground` alongside the dev server, so evaluation goes
  * through the real gomplate engine rather than a reimplementation in the
@@ -17,7 +57,7 @@ export interface EvalServerOptions {
  * when attaching a debugger, or when iterating on Go code that would otherwise
  * be recompiled on every Vite restart.
  */
-export function evalServer({ repoRoot, port }: EvalServerOptions): Plugin {
+export function evalServer({ repoRoot, host, port }: EvalServerOptions): Plugin {
   let child: ChildProcess | undefined;
 
   const stop = () => {
@@ -41,7 +81,7 @@ export function evalServer({ repoRoot, port }: EvalServerOptions): Plugin {
         return;
       }
 
-      child = spawn("go", ["run", "./cmd/playground", "-addr", `:${port}`], {
+      child = spawn("go", ["run", "./cmd/playground", "-addr", `${host}:${port}`], {
         cwd: repoRoot,
         stdio: ["ignore", "pipe", "pipe"],
       });

web/apps/playground/test/viteConfig.test.ts

@@ -0,0 +1,64 @@
+import { createServer } from "node:net";
+import { describe, expect, it } from "vitest";
+
+import { findAvailablePort } from "../plugins/eval-server";
+import { createPlaygroundConfig } from "../vite.config";
+
+const SELECTED_EVAL_PORT = 49_153;
+
+describe("playground Vite configuration", () => {
+  it.each([
+    { command: "serve" as const, mode: "development", clickySourceAvailable: true, expected: true },
+    { command: "serve" as const, mode: "test", clickySourceAvailable: true, expected: false },
+    { command: "serve" as const, mode: "development", clickySourceAvailable: false, expected: false },
+    { command: "build" as const, mode: "production", clickySourceAvailable: true, expected: false },
+  ])(
+    "sets dependency re-optimization to $expected for command=$command mode=$mode source=$clickySourceAvailable",
+    ({ command, mode, clickySourceAvailable, expected }) => {
+      const config = createPlaygroundConfig({
+        command,
+        mode,
+        clickySourceAvailable,
+        evalPort: SELECTED_EVAL_PORT,
+      });
+
+      expect(config.optimizeDeps?.force).toBe(expected);
+    },
+  );
+
+  it("proxies API requests to the selected eval-server port", () => {
+    const config = createPlaygroundConfig({
+      command: "serve",
+      mode: "development",
+      clickySourceAvailable: false,
+      evalPort: SELECTED_EVAL_PORT,
+    });
+
+    expect(config.server?.proxy?.["/api"]).toMatchObject({
+      target: `http://127.0.0.1:${SELECTED_EVAL_PORT}`,
+    });
+  });
+
+  it("selects another loopback port when the preferred port is occupied", async () => {
+    const occupied = createServer();
+    await new Promise<void>((resolve, reject) => {
+      occupied.once("error", reject);
+      occupied.listen(0, "127.0.0.1", resolve);
+    });
+
+    try {
+      const address = occupied.address();
+      if (!address || typeof address === "string") throw new Error("test listener has no TCP port");
+      const selectedPort = await findAvailablePort({
+        host: "127.0.0.1",
+        preferredPort: address.port,
+      });
+
+      expect(selectedPort).not.toBe(address.port);
+    } finally {
+      await new Promise<void>((resolve, reject) => {
+        occupied.close((error) => (error ? reject(error) : resolve()));
+      });
+    }
+  });
+});

web/apps/playground/vite.config.ts

@@ -3,13 +3,14 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
-import { defineConfig } from "vite";
+import { defineConfig, type UserConfig } from "vite";
 
-import { evalServer } from "./plugins/eval-server";
+import { evalServer, findAvailablePort } from "./plugins/eval-server";
 
 const root = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(root, "../../..");
 
+const EVAL_HOST = "127.0.0.1";
 const EVAL_PORT = 8321;
 const DEV_PORT = 5280;
 
@@ -37,14 +38,26 @@ const clickyAliases = [
   { find: /^@flanksource\/clicky-ui$/, replacement: resolve(clickySrc, "index.ts") },
 ];
 
-export default defineConfig(({ command, mode }) => {
+interface PlaygroundConfigOptions {
+  command: "build" | "serve";
+  mode: string;
+  clickySourceAvailable: boolean;
+  evalPort: number;
+}
+
+export function createPlaygroundConfig({
+  command,
+  mode,
+  clickySourceAvailable,
+  evalPort,
+}: PlaygroundConfigOptions): UserConfig {
   // Vitest also runs in `serve`, and it is the one mode that must not alias:
   // tests assert against the surface the package publishes, not against
   // whatever a sibling checkout happens to have mid-edit.
-  const useClickySource = clickySourceAvailable && mode !== "test";
+  const useClickySource = command === "serve" && clickySourceAvailable && mode !== "test";
 
   return {
-    plugins: [react(), tailwindcss(), evalServer({ repoRoot, port: EVAL_PORT })],
+    plugins: [react(), tailwindcss(), evalServer({ repoRoot, host: EVAL_HOST, port: evalPort })],
     resolve: {
       dedupe: ["react", "react-dom"],
       alias: command === "serve" && useClickySource ? clickyAliases : [],
@@ -54,18 +67,31 @@ export default defineConfig(({ command, mode }) => {
       strictPort: true,
       proxy: {
         "/api": {
-          target: `http://127.0.0.1:${EVAL_PORT}`,
+          target: `http://${EVAL_HOST}:${evalPort}`,
           changeOrigin: false,
         },
       },
       // Vite refuses to serve files outside the project root unless told to.
       fs: { allow: [root, resolve(root, "../.."), ...(useClickySource ? [clickySrc] : [])] },
     },
     optimizeDeps: {
+      // The sibling lockfile is outside Vite's cache inputs, so dependency
+      // paths can otherwise remain stale after clicky-ui upgrades a package.
+      force: useClickySource,
       exclude: [
         "@flanksource/gomplate-lang",
         ...(useClickySource ? ["@flanksource/clicky-ui"] : []),
       ],
     },
   };
+}
+
+export default defineConfig(async ({ command, mode }) => {
+  const managesEvalServer = process.env.GOMPLATE_PLAYGROUND_SERVER !== "0";
+  const evalPort =
+    command === "serve" && mode !== "test" && managesEvalServer
+      ? await findAvailablePort({ host: EVAL_HOST, preferredPort: EVAL_PORT })
+      : EVAL_PORT;
+
+  return createPlaygroundConfig({ command, mode, clickySourceAvailable, evalPort });
 });

web/package.json

@@ -10,5 +10,5 @@
     "typecheck": "pnpm -r typecheck",
     "dev:playground": "pnpm --filter gomplate-playground dev"
   },
-  "packageManager": "pnpm@10.34.5"
+  "packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621"
 }