@cursor/july 0.1.1

package/src/internal/playground/toolchain.ts

@@ -0,0 +1,277 @@
+/**
+ * Local Vite toolchain for the playground SPA.
+ *
+ * Published installs ship `dist/playground/` and do not need this — vite is a
+ * devDependency and `playground/` sources may be absent. In a monorepo / source
+ * checkout, `serve` uses this to auto-build a missing bundle and (with `--dev`)
+ * spawn the Vite HMR server.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { playgroundBundleExists } from "./static.js";
+
+const VITE_CONFIG = "playground/vite.config.ts";
+
+/** `@anysphere/agent-serve` package root (works from `src/` or `dist/`). */
+export function packageRoot(): string {
+  // src|dist/internal/playground/toolchain.ts → packages/agent-serve/
+  return fileURLToPath(new URL("../../..", import.meta.url));
+}
+
+export interface PlaygroundToolchain {
+  packageRoot: string;
+  viteCli: string;
+  viteConfig: string;
+}
+
+/** Resolve the absolute path to vite's CLI bin without using blocked package exports. */
+function resolveViteCli(root: string): string | undefined {
+  try {
+    const require = createRequire(join(root, "package.json"));
+    let dir = dirname(require.resolve("vite"));
+    for (let i = 0; i < 6; i++) {
+      const pkgPath = join(dir, "package.json");
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
+          name?: string;
+          bin?: string | Record<string, string>;
+        };
+        if (pkg.name === "vite") {
+          const binRel =
+            typeof pkg.bin === "string"
+              ? pkg.bin
+              : (pkg.bin?.vite ?? "bin/vite.js");
+          const binAbs = join(dir, binRel);
+          return existsSync(binAbs) ? binAbs : undefined;
+        }
+      }
+      const parent = dirname(dir);
+      if (parent === dir) {
+        break;
+      }
+      dir = parent;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+/** True when playground sources + a resolvable `vite` CLI are present. */
+export function resolvePlaygroundToolchain(): PlaygroundToolchain | undefined {
+  const root = packageRoot();
+  const viteConfig = join(root, VITE_CONFIG);
+  if (!existsSync(viteConfig)) {
+    return undefined;
+  }
+  const viteCli = resolveViteCli(root);
+  if (viteCli === undefined) {
+    return undefined;
+  }
+  return { packageRoot: root, viteCli, viteConfig };
+}
+
+export function playgroundToolchainAvailable(): boolean {
+  return resolvePlaygroundToolchain() !== undefined;
+}
+
+/**
+ * `AGENT_SERVE_BASE` for the Vite proxy when serving a single slugged agent.
+ * Multi-agent serve uses path-based HMR (`/<slug>/playground`) unless the
+ * caller pins one slug via {@link playgroundDevBaseFromEnv}.
+ */
+export function playgroundDevBasePath(
+  mounts: ReadonlyArray<{ slug: string }>
+): string | undefined {
+  if (mounts.length === 1 && mounts[0]?.slug !== "") {
+    return `/${mounts[0].slug}`;
+  }
+  return undefined;
+}
+
+/**
+ * Optional pin for multi-agent Vite HMR (SPA at root, rewrite `/v1` → base).
+ * Empty / unset → multi-agent path mode (`AGENT_SERVE_MULTI`).
+ */
+export function playgroundDevBaseFromEnv(
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  const raw = env.AGENT_SERVE_BASE?.trim();
+  if (raw === undefined || raw === "") {
+    return undefined;
+  }
+  const normalized = raw.replace(/\/+$/, "");
+  if (normalized === "" || normalized === "/") {
+    return undefined;
+  }
+  return normalized.startsWith("/") ? normalized : `/${normalized}`;
+}
+
+/** Run `vite build` for the playground; throws on non-zero exit. */
+export async function runPlaygroundBuild(
+  logger: (line: string) => void = console.log
+): Promise<void> {
+  const toolchain = resolvePlaygroundToolchain();
+  if (toolchain === undefined) {
+    throw new Error(
+      "playground vite toolchain unavailable (need playground/ sources and the vite package)"
+    );
+  }
+  logger("[agent-serve] building playground (vite)...");
+  const code = await spawnVite(toolchain, ["build", "--config", VITE_CONFIG], {
+    env: process.env,
+  });
+  if (code !== 0) {
+    throw new Error(`playground vite build failed (exit ${code})`);
+  }
+  if (!playgroundBundleExists()) {
+    throw new Error(
+      "playground vite build finished but dist/playground/index.html is missing"
+    );
+  }
+  logger("[agent-serve] playground build complete");
+}
+
+/**
+ * If the SPA bundle is missing and the local toolchain is available, build it.
+ * No-op when the bundle already exists. Soft-skips (logs) when vite is absent
+ * so published installs without a prebuilt bundle still start.
+ */
+export async function ensurePlaygroundBundle(
+  logger: (line: string) => void = console.log
+): Promise<void> {
+  if (playgroundBundleExists()) {
+    return;
+  }
+  if (resolvePlaygroundToolchain() === undefined) {
+    logger(
+      "[agent-serve] playground bundle missing and vite toolchain unavailable; /playground will show a build hint"
+    );
+    return;
+  }
+  await runPlaygroundBuild(logger);
+}
+
+export interface PlaygroundDevServer {
+  url: string;
+  stop(): void;
+}
+
+/**
+ * Spawn Vite HMR for the playground, proxying API calls at {@link targetUrl}.
+ * Multi-agent mode serves `/<slug>/playground` + the agents index at `/`.
+ * Returns undefined when the toolchain is unavailable.
+ */
+export function startPlaygroundDevServer(options: {
+  targetUrl: string;
+  basePath?: string;
+  /** Path-based multi-agent HMR (no single-slug `/v1` rewrite). */
+  multiAgent?: boolean;
+  logger?: (line: string) => void;
+}): PlaygroundDevServer | undefined {
+  const logger = options.logger ?? console.log;
+  const toolchain = resolvePlaygroundToolchain();
+  if (toolchain === undefined) {
+    return undefined;
+  }
+
+  const port = playgroundDevPort();
+  const multiAgent = options.multiAgent === true;
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    AGENT_SERVE_PLAYGROUND_PORT: String(port),
+    AGENT_SERVE_TARGET: options.targetUrl,
+  };
+  if (multiAgent) {
+    env.AGENT_SERVE_MULTI = "1";
+    delete env.AGENT_SERVE_BASE;
+  } else {
+    delete env.AGENT_SERVE_MULTI;
+    if (options.basePath !== undefined && options.basePath !== "") {
+      env.AGENT_SERVE_BASE = options.basePath;
+    } else {
+      delete env.AGENT_SERVE_BASE;
+    }
+  }
+
+  const modeNote = multiAgent
+    ? " (multi-agent)"
+    : options.basePath
+      ? ` (base ${options.basePath})`
+      : "";
+  logger(
+    `[agent-serve] playground HMR starting on http://127.0.0.1:${port}${modeNote}`
+  );
+
+  const child = spawn(
+    process.execPath,
+    [toolchain.viteCli, "--config", VITE_CONFIG],
+    {
+      cwd: toolchain.packageRoot,
+      env,
+      stdio: "inherit",
+    }
+  );
+
+  let stopped = false;
+  child.on("error", (err) => {
+    if (stopped) {
+      return;
+    }
+    logger(
+      `[agent-serve] playground HMR spawn failed: ${err.message} — static /playground still served when built`
+    );
+  });
+  child.on("exit", (code, signal) => {
+    if (stopped) {
+      return;
+    }
+    if (code !== 0 && code !== null) {
+      logger(
+        `[agent-serve] playground HMR exited (code ${code}${
+          signal ? `, signal ${signal}` : ""
+        }) — static /playground still served when built`
+      );
+    }
+  });
+
+  return {
+    url: `http://127.0.0.1:${port}/`,
+    stop: () => {
+      stopped = true;
+      if (!child.killed) {
+        child.kill("SIGTERM");
+      }
+    },
+  };
+}
+
+export function playgroundDevPort(): number {
+  const parsed = Number(process.env.AGENT_SERVE_PLAYGROUND_PORT ?? "5273");
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    return 5273;
+  }
+  return parsed;
+}
+
+function spawnVite(
+  toolchain: PlaygroundToolchain,
+  args: string[],
+  options: { env: NodeJS.ProcessEnv }
+): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [toolchain.viteCli, ...args], {
+      cwd: toolchain.packageRoot,
+      env: options.env,
+      stdio: "inherit",
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      resolve(code ?? 1);
+    });
+  });
+}