The Open Framework for Building Agents
Improve duplicate eve dev process hint (#52)
JJ Kasper432503d4e5b0
diff --git a/.changeset/dev-process-connect-hint.md b/.changeset/dev-process-connect-hint.mdnew file mode 100644index 000000000..43b5bd785--- /dev/null+++ b/.changeset/dev-process-connect-hint.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Clarify the duplicate `eve dev` process error with a copyable package-manager command for connecting to the existing local server instead of stopping it.diff --git a/packages/eve/src/internal/nitro/host/start-development-server.test.ts b/packages/eve/src/internal/nitro/host/start-development-server.test.tsindex 9e8cfa9cf..409a8a7f7 100644--- a/packages/eve/src/internal/nitro/host/start-development-server.test.ts+++ b/packages/eve/src/internal/nitro/host/start-development-server.test.ts@@ -58,6 +58,11 @@ const mocks = vi.hoisted(() => {rm: vi.fn(async (path: string) => {files.delete(path);}),+ stat: vi.fn(async (path: string) => {+ if (!files.has(path)) {+ throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });+ }+ }),startDevelopmentSandboxPrewarmInBackground: vi.fn(() => undefined),pruneLocalSandboxTemplatesInBackground: vi.fn(() => undefined),stopDevelopmentSandboxResources: vi.fn(async () => undefined),@@ -78,6 +83,7 @@ vi.mock("node:fs/promises", () => ({mkdir: mocks.mkdir,readFile: mocks.readFile,rm: mocks.rm,+ stat: mocks.stat,writeFile: mocks.writeFile,}));@@ -153,6 +159,7 @@ function createSocket(): Socket {}const developmentProcessIdPath = join("/tmp/eve-test", ".eve", "dev-process.pid");+const developmentServerMetadataPath = join("/tmp/eve-test", ".eve", "dev-server.json");async function startServer(): Promise<{close(): Promise<void>;@@ -327,10 +334,15 @@ describe("startDevelopmentServer", () => {const server = await startDevelopmentServer("/tmp/eve-test");expect(mocks.files.get(developmentProcessIdPath)).toBe(`${process.pid}\n`);+ expect(JSON.parse(mocks.files.get(developmentServerMetadataPath) ?? "{}")).toMatchObject({+ pid: process.pid,+ url: "http://localhost:2000/",+ });await server.close();expect(mocks.files.has(developmentProcessIdPath)).toBe(false);+ expect(mocks.files.has(developmentServerMetadataPath)).toBe(false);});it("refuses to start when the agent already has a running dev process", async () => {@@ -340,6 +352,35 @@ describe("startDevelopmentServer", () => {await expect(startDevelopmentServer("/tmp/eve-test")).rejects.toThrow([`A dev server is already running for this eve agent (pid ${process.pid}).`,+ "To connect to the existing instance, run: pnpm exec eve dev http://localhost:PORT",+ `To stop it, run: ${+ process.platform === "win32" ? "taskkill /PID" : "kill"+ } ${process.pid}`,+ ].join("\n"),+ );+ expect(mocks.createApplicationNitro).not.toHaveBeenCalled();+ });++ it("prints a copyable connect command with the detected package manager and server URL", async () => {+ const { startDevelopmentServer } = await import("./start-development-server.js");+ mocks.files.set(+ join("/tmp/eve-test", "package.json"),+ JSON.stringify({ packageManager: "[email protected]" }),+ );+ mocks.files.set(developmentProcessIdPath, `${process.pid}\n`);+ mocks.files.set(+ developmentServerMetadataPath,+ JSON.stringify({+ pid: process.pid,+ updatedAt: "2026-06-17T00:00:00.000Z",+ url: "http://127.0.0.1:4321/",+ }),+ );++ await expect(startDevelopmentServer("/tmp/eve-test")).rejects.toThrow(+ [+ `A dev server is already running for this eve agent (pid ${process.pid}).`,+ "To connect to the existing instance, run: npm exec -- eve dev http://127.0.0.1:4321/",`To stop it, run: ${process.platform === "win32" ? "taskkill /PID" : "kill"} ${process.pid}`,diff --git a/packages/eve/src/internal/nitro/host/start-development-server.ts b/packages/eve/src/internal/nitro/host/start-development-server.tsindex e44d99c58..5db5a10ef 100644--- a/packages/eve/src/internal/nitro/host/start-development-server.ts+++ b/packages/eve/src/internal/nitro/host/start-development-server.ts@@ -31,13 +31,27 @@ import {DEFAULT_DEVELOPMENT_SERVER_PORT,MAX_DEVELOPMENT_SERVER_PORT_ATTEMPTS,} from "#internal/nitro/host/ports.js";+import { detectPackageManager, type PackageManagerKind } from "#setup/package-manager.js";+import { eveDevArguments } from "#setup/primitives/index.js";const MAX_ALLOWED_DEVELOPMENT_SERVER_PORT = 65_535;const WORKFLOW_LOCAL_BASE_URL_ENV = "WORKFLOW_LOCAL_BASE_URL";const PORT_ENV = "PORT";const DEVELOPMENT_PROCESS_ID_FILE = "dev-process.pid";+const DEVELOPMENT_SERVER_METADATA_FILE = "dev-server.json";const DEFAULT_DEVELOPMENT_SERVER_HOST = "127.0.0.1";const IPV6_LOOPBACK_HOSTNAME = "[::1]";+const DEVELOPMENT_SERVER_URL_PLACEHOLDER = "http://localhost:PORT";++interface DevelopmentServerMetadata {+ readonly processId: number;+ readonly url: string;+}++interface ActiveDevelopmentProcess {+ readonly processId: number;+ readonly url?: string;+}/*** Hostnames Nitro/srvx surface when listening on an IPv6 wildcard interface.@@ -111,6 +125,10 @@ function resolveDevelopmentProcessIdPath(appRoot: string): string {return join(appRoot, ".eve", DEVELOPMENT_PROCESS_ID_FILE);}+function resolveDevelopmentServerMetadataPath(appRoot: string): string {+ return join(appRoot, ".eve", DEVELOPMENT_SERVER_METADATA_FILE);+}+function parseProcessId(value: string): number | undefined {const trimmed = value.trim();@@ -141,7 +159,60 @@ function formatKillCommand(processId: number): string {return `kill ${processId}`;}-async function readActiveDevelopmentProcessId(appRoot: string): Promise<number | undefined> {+function parseDevelopmentServerMetadata(value: string): DevelopmentServerMetadata | undefined {+ let parsed: unknown;++ try {+ parsed = JSON.parse(value);+ } catch {+ return undefined;+ }++ if (+ typeof parsed !== "object" ||+ parsed === null ||+ !("pid" in parsed) ||+ typeof parsed.pid !== "number" ||+ !Number.isSafeInteger(parsed.pid) ||+ parsed.pid <= 0 ||+ !("url" in parsed) ||+ typeof parsed.url !== "string"+ ) {+ return undefined;+ }++ const url = normalizeDevelopmentServerClientUrl(parsed.url);++ try {+ const parsedUrl = new URL(url);+ if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {+ return undefined;+ }+ } catch {+ return undefined;+ }++ return {+ processId: parsed.pid,+ url,+ };+}++async function readDevelopmentServerMetadata(+ appRoot: string,+): Promise<DevelopmentServerMetadata | undefined> {+ try {+ return parseDevelopmentServerMetadata(+ await readFile(resolveDevelopmentServerMetadataPath(appRoot), "utf8"),+ );+ } catch {+ return undefined;+ }+}++async function readActiveDevelopmentProcess(+ appRoot: string,+): Promise<ActiveDevelopmentProcess | undefined> {let processId: number | undefined;try {@@ -154,18 +225,61 @@ async function readActiveDevelopmentProcessId(appRoot: string): Promise<number |return undefined;}- return processId;+ const metadata = await readDevelopmentServerMetadata(appRoot);++ return {+ processId,+ url: metadata?.processId === processId ? metadata.url : undefined,+ };+}++async function detectDevelopmentCommandPackageManager(+ appRoot: string,+): Promise<PackageManagerKind> {+ try {+ return (await detectPackageManager(appRoot)).kind;+ } catch {+ return "pnpm";+ }+}++async function formatDevelopmentServerConnectCommand(+ appRoot: string,+ serverUrl: string,+): Promise<string> {+ const packageManager = await detectDevelopmentCommandPackageManager(appRoot);+ return [packageManager, ...eveDevArguments(packageManager), serverUrl].join(" ");+}++async function writeDevelopmentServerMetadata(appRoot: string, serverUrl: string): Promise<void> {+ await writeFile(+ resolveDevelopmentServerMetadataPath(appRoot),+ `${JSON.stringify(+ {+ pid: process.pid,+ updatedAt: new Date().toISOString(),+ url: normalizeDevelopmentServerClientUrl(serverUrl),+ },+ null,+ 2,+ )}\n`,+ "utf8",+ );}async function writeDevelopmentProcessId(appRoot: string): Promise<() => Promise<void>> {const processIdPath = resolveDevelopmentProcessIdPath(appRoot);- const activeProcessId = await readActiveDevelopmentProcessId(appRoot);+ const metadataPath = resolveDevelopmentServerMetadataPath(appRoot);+ const activeProcess = await readActiveDevelopmentProcess(appRoot);- if (activeProcessId !== undefined) {+ if (activeProcess !== undefined) {+ const connectUrl = activeProcess.url ?? DEVELOPMENT_SERVER_URL_PLACEHOLDER;+ const connectCommand = await formatDevelopmentServerConnectCommand(appRoot, connectUrl);throw new Error([- `A dev server is already running for this eve agent (pid ${activeProcessId}).`,- `To stop it, run: ${formatKillCommand(activeProcessId)}`,+ `A dev server is already running for this eve agent (pid ${activeProcess.processId}).`,+ `To connect to the existing instance, run: ${connectCommand}`,+ `To stop it, run: ${formatKillCommand(activeProcess.processId)}`,].join("\n"),);}@@ -184,6 +298,13 @@ async function writeDevelopmentProcessId(appRoot: string): Promise<() => Promiseif (currentProcessId === process.pid) {await rm(processIdPath, { force: true });+ await rm(metadataPath, { force: true });+ return;+ }++ const metadata = await readDevelopmentServerMetadata(appRoot);+ if (metadata?.processId === process.pid) {+ await rm(metadataPath, { force: true });}};}@@ -395,7 +516,9 @@ export async function startDevelopmentServer(throw new Error("Nitro dev server did not expose a URL.");}- restoreWorkflowLocalQueueEnvironment = installWorkflowLocalQueueEnvironment(server.url);+ const serverUrl = normalizeDevelopmentServerClientUrl(server.url);+ await writeDevelopmentServerMetadata(preparedHost.appRoot, serverUrl);+ restoreWorkflowLocalQueueEnvironment = installWorkflowLocalQueueEnvironment(serverUrl);await prepare(nitro);await buildNitro(nitro);@@ -431,7 +554,7 @@ export async function startDevelopmentServer(restoreDevelopmentSandboxRunId(previousDevelopmentSandboxRunId);}},- url: normalizeDevelopmentServerClientUrl(server.url),+ url: serverUrl,};} catch (error) {await authoredSourceWatcher?.close().catch(() => {});