Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

refactor(eve): simplify project context resolution (#2968)

OwenKephart0e2e10dac280
diff --git a/.changeset/simplify-project-context-resolution.md b/.changeset/simplify-project-context-resolution.md
new file mode 100644
index 000000000..0b2b06672
--- /dev/null
+++ b/.changeset/simplify-project-context-resolution.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Resolve eve project ownership from the nearest `package.json` that declares `dependencies.eve`, then classify its `agent/` or `agents/` shape. This avoids incorrect environment and CLI behavior in repositories that only use eve as development tooling.
diff --git a/packages/eve/src/cli/agent-command.ts b/packages/eve/src/cli/agent-command.ts
index 30e7842fa..a2a8398b7 100644
--- a/packages/eve/src/cli/agent-command.ts
+++ b/packages/eve/src/cli/agent-command.ts
@@ -1,5 +1,5 @@
import type { Command } from "#compiled/commander/index.js";
-import type { AgentWorkspace } from "#internal/agent-workspace.js";
+import type { AgentWorkspace } from "#internal/project-context.js";
import { createPrompter } from "#setup/prompter.js";
import type { CliApplicationContext } from "./application-command.js";
diff --git a/packages/eve/src/cli/commands/build.ts b/packages/eve/src/cli/commands/build.ts
index 5038039d6..1b414a550 100644
--- a/packages/eve/src/cli/commands/build.ts
+++ b/packages/eve/src/cli/commands/build.ts
@@ -6,7 +6,6 @@ import { resolveInternalVercelServiceOutput } from "#cli/vercel-service-output.j
import { createCliTheme, renderCliTaggedLine } from "#cli/ui/output.js";
import { EVE_INTERNAL_AGENT_WORKSPACE_MEMBER_ENV } from "#internal/application/build-output-environment.js";
import type { ApplicationBuildOptions } from "#internal/nitro/host/types.js";
-import { resolveEveProjectContext } from "#internal/project-context.js";
import {
EVE_PUBLIC_ROUTE_PREFIX_ENV,
normalizePublicRoutePrefix,
@@ -35,7 +34,7 @@ export function registerBuildCommand(input: {
input.program
.command("build")
.hook("preAction", async () => {
- const context = await resolveEveProjectContext(input.applicationContext.root);
+ const context = await input.applicationContext.resolveAgent();
if (context.kind !== "workspace") await input.applicationContext.resolve();
})
.description("Build the current eve application.")
@@ -49,7 +48,7 @@ export function registerBuildCommand(input: {
await loadDevelopmentEnvironmentFiles(input.applicationContext.root);
- const projectContext = await resolveEveProjectContext(input.applicationContext.root);
+ const projectContext = await input.applicationContext.resolveAgent();
if (projectContext.kind === "workspace") {
if (options.profile !== undefined || options.skipSandboxPrewarm === true) {
throw new Error(
diff --git a/packages/eve/src/cli/commands/deploy.integration.test.ts b/packages/eve/src/cli/commands/deploy.integration.test.ts
index 8f37b83cd..b45f737d1 100644
--- a/packages/eve/src/cli/commands/deploy.integration.test.ts
+++ b/packages/eve/src/cli/commands/deploy.integration.test.ts
@@ -28,7 +28,11 @@ class TestLogger implements DeployCliLogger {
async function createWorkspaceProject(): Promise<string> {
const projectRoot = await mkdtemp(join(tmpdir(), "eve-deploy-workspace-"));
await mkdir(join(projectRoot, "agents/support/agent"), { recursive: true });
- await writeFile(join(projectRoot, "package.json"), JSON.stringify({ private: true }), "utf8");
+ await writeFile(
+ join(projectRoot, "package.json"),
+ JSON.stringify({ dependencies: { eve: "*" }, private: true }),
+ "utf8",
+ );
return projectRoot;
}
@@ -38,7 +42,7 @@ async function createAgentProject(): Promise<string> {
await writeFile(join(projectRoot, "agent/agent.ts"), "export default {};\n", "utf8");
await writeFile(
join(projectRoot, "package.json"),
- `${JSON.stringify({ name: "my-agent", dependencies: {} }, null, 2)}\n`,
+ `${JSON.stringify({ name: "my-agent", dependencies: { eve: "*" } }, null, 2)}\n`,
"utf8",
);
return projectRoot;
diff --git a/packages/eve/src/cli/commands/init-agent-workspace.ts b/packages/eve/src/cli/commands/init-agent-workspace.ts
index bea4aab81..2652937a8 100644
--- a/packages/eve/src/cli/commands/init-agent-workspace.ts
+++ b/packages/eve/src/cli/commands/init-agent-workspace.ts
@@ -4,7 +4,7 @@ import { join } from "node:path";
import pc from "#compiled/picocolors/index.js";
import { assertValidPublicAgentName } from "#internal/agent-name.js";
-import { resolveAgentWorkspace } from "#internal/agent-workspace.js";
+import { findEveProjectContext } from "#internal/project-context.js";
import { DEFAULT_AGENT_MODEL_ID } from "#shared/default-agent-model.js";
import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
import { validateModelSlug } from "#setup/flows/model-source-change.js";
@@ -79,8 +79,8 @@ export async function addAgentsToWorkspace(
options: InitCommandOptions,
validateModel: typeof validateModelSlug = validateModelSlug,
): Promise<boolean> {
- const workspace = await resolveAgentWorkspace(workspaceRoot);
- if (workspace === undefined) return false;
+ const context = await findEveProjectContext(workspaceRoot);
+ if (context?.kind !== "workspace") return false;
if (options.channelWebNextjs === true) {
throw new Error("--channel-web-nextjs is not supported when adding a workspace agent.");
}
diff --git a/packages/eve/src/cli/commands/init.integration.test.ts b/packages/eve/src/cli/commands/init.integration.test.ts
index 8e9314f62..916d98f71 100644
--- a/packages/eve/src/cli/commands/init.integration.test.ts
+++ b/packages/eve/src/cli/commands/init.integration.test.ts
@@ -171,7 +171,10 @@ describe("runInitCommand", () => {
it("adds only agent files to an existing workspace", async () => {
const workspaceRoot = await mkdtemp(join(tmpdir(), "eve-init-workspace-agent-"));
await mkdir(join(workspaceRoot, "agents", "support", "agent"), { recursive: true });
- await writeFile(join(workspaceRoot, "package.json"), '{"name":"workspace"}\n');
+ await writeFile(
+ join(workspaceRoot, "package.json"),
+ '{"name":"workspace","dependencies":{"eve":"*"}}\n',
+ );
const beforePackageJson = await readFile(join(workspaceRoot, "package.json"), "utf8");
const output = logger();
const deps = dependencies();
diff --git a/packages/eve/src/cli/commands/link.integration.test.ts b/packages/eve/src/cli/commands/link.integration.test.ts
index fd159c96d..2508af07a 100644
--- a/packages/eve/src/cli/commands/link.integration.test.ts
+++ b/packages/eve/src/cli/commands/link.integration.test.ts
@@ -29,7 +29,11 @@ class TestLogger implements LinkCliLogger {
async function createWorkspaceProject(): Promise<string> {
const projectRoot = await mkdtemp(join(tmpdir(), "eve-link-workspace-"));
await mkdir(join(projectRoot, "agents/support/agent"), { recursive: true });
- await writeFile(join(projectRoot, "package.json"), JSON.stringify({ private: true }), "utf8");
+ await writeFile(
+ join(projectRoot, "package.json"),
+ JSON.stringify({ dependencies: { eve: "*" }, private: true }),
+ "utf8",
+ );
return projectRoot;
}
@@ -39,7 +43,7 @@ async function createAgentProject(): Promise<string> {
await writeFile(join(projectRoot, "agent/agent.ts"), "export default {};\n", "utf8");
await writeFile(
join(projectRoot, "package.json"),
- `${JSON.stringify({ name: "my-agent", dependencies: {} }, null, 2)}\n`,
+ `${JSON.stringify({ name: "my-agent", dependencies: { eve: "*" } }, null, 2)}\n`,
"utf8",
);
return projectRoot;
diff --git a/packages/eve/src/cli/commands/preconditions.ts b/packages/eve/src/cli/commands/preconditions.ts
index 9a1c7cb2c..d24ef9d3f 100644
--- a/packages/eve/src/cli/commands/preconditions.ts
+++ b/packages/eve/src/cli/commands/preconditions.ts
@@ -1,5 +1,5 @@
import type { EveProjectContext } from "#internal/project-context.js";
-import { resolveEveProjectContext } from "#internal/project-context.js";
+import { findEveProjectContext } from "#internal/project-context.js";
import { isEveProject } from "#setup/scaffold/index.js";
/**
@@ -22,15 +22,16 @@ export async function validateWorkspaceProjectCommand(input: {
workspace: Extract<EveProjectContext, { kind: "workspace" }>["workspace"],
) => string;
}): Promise<boolean> {
- const projectContext = await resolveEveProjectContext(input.appRoot);
- if (projectContext.kind === "workspace-member") {
+ const projectContext = await findEveProjectContext(input.appRoot);
+ if (projectContext?.kind === "workspace-member") {
input.logger.error(input.workspaceMemberMessage(projectContext.workspace));
process.exitCode = 1;
return false;
}
if (
- projectContext.kind === "standalone" &&
- !(await (input.isEveProject ?? isEveProject)(input.appRoot))
+ projectContext === undefined ||
+ (projectContext.kind === "standalone" &&
+ !(await (input.isEveProject ?? isEveProject)(input.appRoot)))
) {
input.logger.error(NOT_AN_AGENT_MESSAGE);
process.exitCode = 1;
diff --git a/packages/eve/src/cli/dev/environment.ts b/packages/eve/src/cli/dev/environment.ts
index 6c93cca85..428da7ec2 100644
--- a/packages/eve/src/cli/dev/environment.ts
+++ b/packages/eve/src/cli/dev/environment.ts
@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
import { join, resolve } from "node:path";
import { parseEnv } from "node:util";
-import { resolveEveProjectContext } from "#internal/project-context.js";
+import { findEveProjectRoot } from "#internal/eve-project-root.js";
import { isObject } from "#shared/guards.js";
import { readProviderSelectionSync } from "#setup/provider-settings.js";
@@ -55,8 +55,8 @@ export function getDevelopmentEnvironmentFilePaths(appRoot: string): string[] {
*/
export async function loadDevelopmentEnvironmentFiles(appRoot: string): Promise<void> {
const resolvedAppRoot = resolve(appRoot);
- const context = await resolveEveProjectContext(resolvedAppRoot);
- getDevelopmentEnvironmentLoader(resolvedAppRoot, context.environmentRoot).reload();
+ const environmentRoot = await findEveProjectRoot(resolvedAppRoot);
+ getDevelopmentEnvironmentLoader(resolvedAppRoot, environmentRoot).reload();
}
export function stageDevelopmentEnvironmentFiles(appRoot: string): DevelopmentEnvironmentReload {
diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.ts
index 9a1a7cf78..c6ffbbbe2 100644
--- a/packages/eve/src/cli/run.test.ts
+++ b/packages/eve/src/cli/run.test.ts
@@ -22,6 +22,14 @@ vi.mock("#cli/application-root.js", () => ({
}));
vi.mock("#cli/commands/init.js", () => ({ runInitCommand }));
vi.mock("#cli/commands/set.js", () => ({ runSetCommand }));
+vi.mock("#internal/project-context.js", () => ({
+ findEveProjectContext: vi.fn(async () => undefined),
+ resolveEveProjectContext: vi.fn(async (appRoot: string) => ({
+ appRoot,
+ environmentRoot: appRoot,
+ kind: "standalone",
+ })),
+}));
async function withInteractiveTerminal<T>(fn: () => Promise<T>): Promise<T> {
const stdinDescriptor = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
diff --git a/packages/eve/src/cli/run.ts b/packages/eve/src/cli/run.ts
index 247be9a55..2ca4b554b 100644
--- a/packages/eve/src/cli/run.ts
+++ b/packages/eve/src/cli/run.ts
@@ -47,7 +47,7 @@ import {
parseStatsMode,
} from "#cli/option-parsers.js";
import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
-import { resolveEveProjectContext } from "#internal/project-context.js";
+import { findEveProjectContext, resolveEveProjectContext } from "#internal/project-context.js";
import { parseDevelopmentServerUrl } from "#cli/dev/url.js";
import { startCliLiveRow } from "#cli/ui/live-row.js";
import { createCliTheme, renderCliTaggedLine } from "#cli/ui/output.js";
@@ -657,8 +657,8 @@ export async function runCli(
const findApplicationRoot = runtime.findApplicationRoot ?? findCliApplicationRoot;
const appRoot = await findApplicationRoot(applicationContext.root);
if (appRoot === undefined) {
- const projectContext = await resolveEveProjectContext(applicationContext.root);
- input = projectContext.kind === "workspace" ? ["dev"] : ["init"];
+ const projectContext = await findEveProjectContext(applicationContext.root);
+ input = projectContext?.kind === "workspace" ? ["dev"] : ["init"];
} else {
applicationContext.root = appRoot;
input = ["dev"];
diff --git a/packages/eve/src/discover/filesystem.ts b/packages/eve/src/discover/filesystem.ts
index 5b57b744a..e22ff73f1 100644
--- a/packages/eve/src/discover/filesystem.ts
+++ b/packages/eve/src/discover/filesystem.ts
@@ -131,6 +131,16 @@ export function isProjectMarkerEntry(name: string, entryType: DirectoryEntryType
/**
* Classifies a top-level agent-root entry according to the spec-legal grammar.
*/
+export function isDiscoverableAgentRootEntry(name: string, entryType: DirectoryEntryType): boolean {
+ const kind = classifyAgentRootEntry(name, entryType);
+ return (
+ kind !== "unknown" &&
+ kind !== "ignored-directory" &&
+ kind !== "lib-directory" &&
+ kind !== "memory-directory"
+ );
+}
+
export function classifyAgentRootEntry(
name: string,
entryType: DirectoryEntryType,
diff --git a/packages/eve/src/discover/project.ts b/packages/eve/src/discover/project.ts
index 324a509aa..95859e68d 100644
--- a/packages/eve/src/discover/project.ts
+++ b/packages/eve/src/discover/project.ts
@@ -6,13 +6,13 @@ import {
type DiscoverDiagnostic,
} from "#discover/diagnostics.js";
import {
- classifyAgentRootEntry,
type DirectoryEntryType,
getDirectoryEntryType,
+ isDiscoverableAgentRootEntry,
isProjectMarkerEntry,
} from "#discover/filesystem.js";
import { createDiskProjectSource, type ProjectSource } from "#discover/project-source.js";
-import { resolveNamedAgentProjectContext } from "#internal/project-context.js";
+import { findEveProjectContext } from "#internal/project-context.js";
/**
* Supported project layouts for filesystem-based agents.
@@ -159,21 +159,16 @@ async function tryResolveNestedProjectFromAppRoot(
async function isNestedProjectRoot(source: ProjectSource, directoryPath: string): Promise<boolean> {
if (await hasProjectMarkers(source, directoryPath)) return true;
- return (await resolveNamedAgentProjectContext(directoryPath, { source })) !== undefined;
+ const context = await findEveProjectContext(directoryPath, { source });
+ return context?.kind === "workspace-member" && context.member.appRoot === directoryPath;
}
async function isFlatAgentRoot(source: ProjectSource, directoryPath: string): Promise<boolean> {
const entries = await readDirectoryEntryTypes(source, directoryPath);
- return Array.from(entries.entries()).some(([name, entryType]) => {
- const entryKind = classifyAgentRootEntry(name, entryType);
- return (
- entryKind !== "unknown" &&
- entryKind !== "ignored-directory" &&
- entryKind !== "lib-directory" &&
- entryKind !== "memory-directory"
- );
- });
+ return Array.from(entries.entries()).some(([name, entryType]) =>
+ isDiscoverableAgentRootEntry(name, entryType),
+ );
}
async function hasProjectMarkers(source: ProjectSource, directoryPath: string): Promise<boolean> {
diff --git a/packages/eve/src/internal/agent-workspace.integration.test.ts b/packages/eve/src/internal/agent-workspace.integration.test.ts
index e0bc685bc..ab9727bb8 100644
--- a/packages/eve/src/internal/agent-workspace.integration.test.ts
+++ b/packages/eve/src/internal/agent-workspace.integration.test.ts
@@ -6,65 +6,94 @@ import { describe, expect, it } from "vitest";
import { createMemoryProjectSource } from "#discover/project-source.js";
import { resolveDiscoveryProject } from "#discover/project.js";
-import { resolveAgentWorkspace } from "#internal/agent-workspace.js";
-import { resolveEveProjectContext } from "#internal/project-context.js";
+import { findEveProjectContext, resolveEveProjectContext } from "#internal/project-context.js";
async function createWorkspace(): Promise<string> {
const root = await mkdtemp(join(tmpdir(), "eve-workspace-"));
await Promise.all([
mkdir(join(root, "agents", "support", "agent"), { recursive: true }),
mkdir(join(root, "agents", "research", "agent"), { recursive: true }),
+ writeFile(join(root, "package.json"), JSON.stringify({ dependencies: { eve: "*" } })),
]);
return root;
}
-describe("resolveAgentWorkspace", () => {
+describe("resolveEveProjectContext", () => {
it("discovers direct agents/ children in deterministic order", async () => {
const root = await createWorkspace();
- await expect(resolveAgentWorkspace(root)).resolves.toEqual({
- members: [
- { name: "research", appRoot: join(root, "agents", "research") },
- { name: "support", appRoot: join(root, "agents", "support") },
- ],
- root,
+ await expect(resolveEveProjectContext(root)).resolves.toEqual({
+ environmentRoot: root,
+ kind: "workspace",
+ workspace: {
+ members: [
+ { name: "research", appRoot: join(root, "agents", "research") },
+ { name: "support", appRoot: join(root, "agents", "support") },
+ ],
+ root,
+ },
});
});
- it("does not read package.json metadata to discover a workspace", async () => {
- const root = await mkdtemp(join(tmpdir(), "eve-workspace-metadata-"));
- await writeFile(
- join(root, "package.json"),
- JSON.stringify({ eve: { agents: ["products/*"] }, private: true }),
- );
- await mkdir(join(root, "products", "support", "agent"), { recursive: true });
- await expect(resolveAgentWorkspace(root)).resolves.toBeUndefined();
+ it("requires the root package to declare eve as a runtime dependency", async () => {
+ const root = await mkdtemp(join(tmpdir(), "eve-workspace-no-dependency-"));
+ await Promise.all([
+ mkdir(join(root, "agents", "support", "agent"), { recursive: true }),
+ writeFile(join(root, "package.json"), JSON.stringify({ devDependencies: { eve: "*" } })),
+ ]);
+ await expect(findEveProjectContext(root)).resolves.toBeUndefined();
});
- it("rejects agent/ and agents/ at the same root", async () => {
+ it("treats agents in a monorepo that only develops with eve as standalone projects", async () => {
+ const root = await mkdtemp(join(tmpdir(), "eve-agent-monorepo-"));
+ const appRoot = join(root, "agents", "support");
+ await mkdir(join(appRoot, "agent"), { recursive: true });
+ await Promise.all([
+ writeFile(join(root, "package.json"), JSON.stringify({ devDependencies: { eve: "*" } })),
+ writeFile(
+ join(appRoot, "package.json"),
+ JSON.stringify({ dependencies: { eve: "*" }, name: "support" }),
+ ),
+ ]);
+
+ await expect(resolveEveProjectContext(join(appRoot, "agent"))).resolves.toEqual({
+ appRoot,
+ environmentRoot: appRoot,
+ kind: "standalone",
+ });
+ });
+
+ it("treats agent/ as standalone even when agents/ also exists", async () => {
const root = await createWorkspace();
await mkdir(join(root, "agent"));
- await expect(resolveAgentWorkspace(root)).rejects.toThrow(/both agent\/ and agents\//);
+
+ await expect(resolveEveProjectContext(root)).resolves.toEqual({
+ appRoot: root,
+ environmentRoot: root,
+ kind: "standalone",
+ });
});
- it("rejects empty workspaces", async () => {
+ it("allows an empty workspace", async () => {
const root = await mkdtemp(join(tmpdir(), "eve-workspace-empty-"));
await mkdir(join(root, "agents"));
- await expect(resolveAgentWorkspace(root)).rejects.toThrow(/at least one directory/);
+ await writeFile(join(root, "package.json"), JSON.stringify({ dependencies: { eve: "*" } }));
+
+ await expect(resolveEveProjectContext(root)).resolves.toMatchObject({
+ kind: "workspace",
+ workspace: { members: [], root },
+ });
});
- it("rejects children without a nested agent directory", async () => {
+ it("does not validate member authoring layout while resolving a workspace", async () => {
const root = await createWorkspace();
- await mkdir(join(root, "agents", "not-an-agent"));
- await expect(resolveAgentWorkspace(root)).rejects.toThrow(
- /expected agents\/not-an-agent\/agent/,
- );
- });
+ const appRoot = join(root, "agents", "flat");
+ await mkdir(appRoot);
+ await writeFile(join(appRoot, "agent.ts"), "export default {};\n");
- it("rejects flat members with a migration hint", async () => {
- const root = await mkdtemp(join(tmpdir(), "eve-workspace-flat-"));
- await mkdir(join(root, "agents", "support"), { recursive: true });
- await writeFile(join(root, "agents", "support", "agent.ts"), "export default {};\n");
- await expect(resolveAgentWorkspace(root)).rejects.toThrow(/Move flat authored files/);
+ await expect(resolveEveProjectContext(appRoot)).resolves.toMatchObject({
+ kind: "workspace-member",
+ member: { appRoot, name: "flat" },
+ });
});
it("keeps conventional members discoverable without project metadata", async () => {
@@ -82,6 +111,7 @@ describe("resolveAgentWorkspace", () => {
const supportRoot = join(root, "agents", "support");
const source = createMemoryProjectSource({
files: {
+ [join(root, "package.json")]: JSON.stringify({ dependencies: { eve: "*" } }),
[join(supportRoot, "agent", "instructions.md")]: "Support users.",
},
});
@@ -93,10 +123,13 @@ describe("resolveAgentWorkspace", () => {
});
});
- it("resolves a workspace member from its application root", async () => {
+ it("resolves a workspace member from any file in its tree", async () => {
const root = await createWorkspace();
const supportRoot = join(root, "agents", "support");
- await expect(resolveEveProjectContext(supportRoot)).resolves.toMatchObject({
+ const toolPath = join(supportRoot, "agent", "tools", "search.ts");
+ await mkdir(join(supportRoot, "agent", "tools"), { recursive: true });
+ await writeFile(toolPath, "export default {};\n");
+ await expect(resolveEveProjectContext(toolPath)).resolves.toMatchObject({
workspace: { root },
environmentRoot: root,
kind: "workspace-member",
@@ -107,10 +140,9 @@ describe("resolveAgentWorkspace", () => {
it("ignores unrelated agents directories above a standalone project", async () => {
const root = await mkdtemp(join(tmpdir(), "eve-standalone-unrelated-agents-"));
const appRoot = join(root, "eve", "apps", "fixtures", "weather-agent");
- await Promise.all([
- mkdir(join(appRoot, "agent"), { recursive: true }),
- mkdir(join(root, "agents", "apps"), { recursive: true }),
- ]);
+ await mkdir(join(appRoot, "agent"), { recursive: true });
+ await mkdir(join(root, "agents", "apps"), { recursive: true });
+ await writeFile(join(appRoot, "package.json"), JSON.stringify({ dependencies: { eve: "*" } }));
await expect(resolveEveProjectContext(appRoot)).resolves.toEqual({
appRoot,
@@ -122,10 +154,10 @@ describe("resolveAgentWorkspace", () => {
it("preserves a standalone project boundary above an agents directory", async () => {
const root = await mkdtemp(join(tmpdir(), "eve-standalone-boundary-"));
const appRoot = join(root, "agents", "support");
- await Promise.all([
- mkdir(join(root, "agent"), { recursive: true }),
- mkdir(join(appRoot, "agent"), { recursive: true }),
- ]);
+ await mkdir(join(root, "agent"), { recursive: true });
+ await mkdir(join(appRoot, "agent"), { recursive: true });
+ await writeFile(join(root, "package.json"), JSON.stringify({ dependencies: { eve: "*" } }));
+ await writeFile(join(appRoot, "package.json"), JSON.stringify({ dependencies: { eve: "*" } }));
await expect(resolveEveProjectContext(appRoot)).resolves.toEqual({
appRoot,
@@ -133,4 +165,46 @@ describe("resolveAgentWorkspace", () => {
kind: "standalone",
});
});
+
+ it("resolves a flat standalone agent", async () => {
+ const root = await mkdtemp(join(tmpdir(), "eve-flat-agent-"));
+ await Promise.all([
+ writeFile(join(root, "package.json"), JSON.stringify({ dependencies: { eve: "*" } })),
+ writeFile(join(root, "agent.ts"), "export default {};\n"),
+ ]);
+
+ await expect(resolveEveProjectContext(root)).resolves.toEqual({
+ appRoot: root,
+ environmentRoot: root,
+ kind: "standalone",
+ });
+ });
+
+ it("resolves workspace-owned paths outside any member to the workspace", async () => {
+ const root = await createWorkspace();
+ const sourceRoot = join(root, "src");
+ await mkdir(sourceRoot);
+
+ await expect(resolveEveProjectContext(sourceRoot)).resolves.toMatchObject({
+ workspace: { root },
+ environmentRoot: root,
+ kind: "workspace",
+ });
+ });
+
+ it("stops at the nearest non-eve package boundary", async () => {
+ const root = await createWorkspace();
+ const packageRoot = join(root, "packages", "unrelated");
+ await mkdir(packageRoot, { recursive: true });
+ await writeFile(join(packageRoot, "package.json"), JSON.stringify({ dependencies: {} }));
+
+ await expect(findEveProjectContext(packageRoot)).resolves.toBeUndefined();
+ });
+
+ it("rejects an eve package without agent files", async () => {
+ const root = await mkdtemp(join(tmpdir(), "eve-invalid-shape-"));
+ await writeFile(join(root, "package.json"), JSON.stringify({ dependencies: { eve: "*" } }));
+
+ await expect(resolveEveProjectContext(root)).rejects.toThrow(/found no agent files/);
+ });
});
diff --git a/packages/eve/src/internal/agent-workspace.ts b/packages/eve/src/internal/agent-workspace.ts
deleted file mode 100644
index 91d6548f4..000000000
--- a/packages/eve/src/internal/agent-workspace.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import { basename, join, relative, resolve } from "node:path";
-
-import { createDiskProjectSource, type ProjectSource } from "#discover/project-source.js";
-import { assertValidPublicAgentName } from "#internal/agent-name.js";
-
-export interface AgentWorkspaceMember {
- readonly appRoot: string;
- readonly name: string;
-}
-
-export interface AgentWorkspace {
- readonly members: readonly AgentWorkspaceMember[];
- readonly root: string;
-}
-
-/** Discover the direct children of a conventional `agents/` workspace. */
-export async function resolveAgentWorkspace(
- root: string,
- options: { readonly source?: ProjectSource } = {},
-): Promise<AgentWorkspace | undefined> {
- const source = options.source ?? createDiskProjectSource();
- const workspaceRoot = resolve(root);
- const agentsRoot = join(workspaceRoot, "agents");
- if ((await source.stat(agentsRoot)) !== "directory") return undefined;
-
- if ((await source.stat(join(workspaceRoot, "agent"))) === "directory") {
- throw new Error(
- "An eve project cannot contain both agent/ and agents/. Keep a standalone agent or move it into the workspace.",
- );
- }
-
- const members: AgentWorkspaceMember[] = [];
- const entries = (await source.readDirectory(agentsRoot))
- .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
- .sort((left, right) => left.name.localeCompare(right.name));
-
- for (const entry of entries) {
- const appRoot = join(agentsRoot, entry.name);
- const name = basename(appRoot);
- assertValidPublicAgentName(name, "Agent workspace member");
- if ((await source.stat(join(appRoot, "agent"))) !== "directory") {
- const relativeAppRoot = relative(workspaceRoot, appRoot).replaceAll("\\", "/");
- const flatHint =
- (await source.stat(join(appRoot, "agent.ts"))) === "file"
- ? " Move flat authored files under an agent/ directory."
- : "";
- throw new Error(
- `${relativeAppRoot} is not a workspace agent: expected ${relativeAppRoot}/agent/.${flatHint}`,
- );
- }
- members.push({ appRoot, name });
- }
-
- if (members.length === 0) {
- throw new Error("An eve agent workspace requires at least one directory under agents/.");
- }
-
- return { members, root: workspaceRoot };
-}
-
-/** Load a workspace that the caller has already identified as workspace-shaped. */
-export async function loadAgentWorkspace(root: string): Promise<AgentWorkspace> {
- const workspace = await resolveAgentWorkspace(root);
- if (workspace === undefined) {
- throw new Error("An eve agent workspace requires an agents/ directory.");
- }
- return workspace;
-}
diff --git a/packages/eve/src/internal/eve-project-root.ts b/packages/eve/src/internal/eve-project-root.ts
new file mode 100644
index 000000000..e81953e64
--- /dev/null
+++ b/packages/eve/src/internal/eve-project-root.ts
@@ -0,0 +1,57 @@
+import { dirname, join, resolve } from "node:path";
+
+import { createDiskProjectSource, type ProjectSource } from "#discover/project-source.js";
+
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function packageDeclaresEve(
+ packageJsonPath: string,
+ source: ProjectSource,
+): Promise<boolean> {
+ let packageJson: unknown;
+ try {
+ packageJson = JSON.parse(await source.readTextFile(packageJsonPath));
+ } catch (error) {
+ throw new Error(`The package.json at ${packageJsonPath} is not valid JSON.`, { cause: error });
+ }
+
+ if (!isJsonObject(packageJson)) return false;
+ const dependencies = packageJson.dependencies;
+ return isJsonObject(dependencies) && typeof dependencies.eve === "string";
+}
+
+export async function isEveProjectRoot(
+ root: string,
+ options: { readonly source?: ProjectSource } = {},
+): Promise<boolean> {
+ const source = options.source ?? createDiskProjectSource();
+ const packageJsonPath = join(resolve(root), "package.json");
+ if ((await source.stat(packageJsonPath)) !== "file") return false;
+ return packageDeclaresEve(packageJsonPath, source);
+}
+
+/** Find the nearest package boundary and return it only when it owns an eve project. */
+export async function findEveProjectRoot(
+ startPath: string,
+ options: { readonly source?: ProjectSource } = {},
+): Promise<string | undefined> {
+ const source = options.source ?? createDiskProjectSource();
+ const resolvedStartPath = resolve(startPath);
+ let currentDirectory =
+ (await source.stat(resolvedStartPath)) === "directory"
+ ? resolvedStartPath
+ : dirname(resolvedStartPath);
+
+ while (true) {
+ const packageJsonPath = join(currentDirectory, "package.json");
+ if ((await source.stat(packageJsonPath)) === "file") {
+ return (await packageDeclaresEve(packageJsonPath, source)) ? currentDirectory : undefined;
+ }
+
+ const parentDirectory = dirname(currentDirectory);
+ if (parentDirectory === currentDirectory) return undefined;
+ currentDirectory = parentDirectory;
+ }
+}
diff --git a/packages/eve/src/internal/nitro/host/dev-environment-watcher.integration.test.ts b/packages/eve/src/internal/nitro/host/dev-environment-watcher.integration.test.ts
index a352d3081..50c26b624 100644
--- a/packages/eve/src/internal/nitro/host/dev-environment-watcher.integration.test.ts
+++ b/packages/eve/src/internal/nitro/host/dev-environment-watcher.integration.test.ts
@@ -77,6 +77,10 @@ describe("development environment reload transactions", () => {
temporaryDirectories.push(workspaceRoot);
const appRoot = join(workspaceRoot, "agents", "support");
await mkdir(join(appRoot, "agent"), { recursive: true });
+ await writeFile(
+ join(workspaceRoot, "package.json"),
+ JSON.stringify({ dependencies: { eve: "*" } }),
+ );
await writeFile(
join(workspaceRoot, ".env.local"),
"EVE_WATCH_ENV_ROOT_ONLY=from-root\nEVE_WATCH_ENV_SHARED=from-root\n",
@@ -158,6 +162,8 @@ function environmentPaths(root: string): string[] {
async function createEnvironmentApp(): Promise<string> {
const appRoot = await mkdtemp(join(tmpdir(), "eve-dev-env-transaction-"));
temporaryDirectories.push(appRoot);
+ await mkdir(join(appRoot, "agent"));
+ await writeFile(join(appRoot, "package.json"), JSON.stringify({ dependencies: { eve: "*" } }));
await writeFile(
join(appRoot, ".env"),
"EVE_WATCH_ENV_FILE_ONLY=from-env\nEVE_WATCH_ENV_SHARED=from-env\nEVE_WATCH_ENV_SHELL=from-env\n",
diff --git a/packages/eve/src/internal/project-context.ts b/packages/eve/src/internal/project-context.ts
index 8c5459d6b..3e6d64a15 100644
--- a/packages/eve/src/internal/project-context.ts
+++ b/packages/eve/src/internal/project-context.ts
@@ -1,11 +1,19 @@
-import { basename, dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { getDirectoryEntryType, isDiscoverableAgentRootEntry } from "#discover/filesystem.js";
import { createDiskProjectSource, type ProjectSource } from "#discover/project-source.js";
-import {
- resolveAgentWorkspace,
- type AgentWorkspace,
- type AgentWorkspaceMember,
-} from "#internal/agent-workspace.js";
+import { assertValidPublicAgentName } from "#internal/agent-name.js";
+import { findEveProjectRoot } from "#internal/eve-project-root.js";
+
+export interface AgentWorkspaceMember {
+ readonly appRoot: string;
+ readonly name: string;
+}
+
+export interface AgentWorkspace {
+ readonly members: readonly AgentWorkspaceMember[];
+ readonly root: string;
+}
export type EveProjectContext =
| {
@@ -25,47 +33,81 @@ export type EveProjectContext =
readonly kind: "standalone";
};
-function standalone(appRoot: string): Extract<EveProjectContext, { kind: "standalone" }> {
- return { appRoot, environmentRoot: appRoot, kind: "standalone" };
+function containsPath(parent: string, child: string): boolean {
+ const relativePath = relative(parent, child);
+ return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
}
-/** Classify an app root included by the nearest declared agent workspace. */
-export async function resolveNamedAgentProjectContext(
- appRoot: string,
+async function hasFlatAgentRoot(root: string, source: ProjectSource): Promise<boolean> {
+ const entries = await source.readDirectory(root);
+ return entries.some((entry) =>
+ isDiscoverableAgentRootEntry(entry.name, getDirectoryEntryType(entry)),
+ );
+}
+
+async function resolveWorkspace(root: string, source: ProjectSource): Promise<AgentWorkspace> {
+ const agentsRoot = join(root, "agents");
+ const entries = (await source.readDirectory(agentsRoot))
+ .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+ .sort((left, right) => left.name.localeCompare(right.name));
+ const members = entries.map((entry) => {
+ assertValidPublicAgentName(entry.name, "Agent workspace member");
+ return { appRoot: join(agentsRoot, entry.name), name: entry.name };
+ });
+ return { members, root };
+}
+
+/** Try to resolve the owning eve package and classify the input path within it. */
+export async function findEveProjectContext(
+ startPath: string,
options: { readonly source?: ProjectSource } = {},
-): Promise<Extract<EveProjectContext, { kind: "workspace-member" | "standalone" }> | undefined> {
- const resolvedAppRoot = resolve(appRoot);
+): Promise<EveProjectContext | undefined> {
const source = options.source ?? createDiskProjectSource();
- const agentsRoot = dirname(resolvedAppRoot);
- if (basename(agentsRoot) !== "agents") return undefined;
+ const resolvedStartPath = resolve(startPath);
+ const searchDirectory =
+ (await source.stat(resolvedStartPath)) === "directory"
+ ? resolvedStartPath
+ : dirname(resolvedStartPath);
+ const projectRoot = await findEveProjectRoot(searchDirectory, { source });
+ if (projectRoot === undefined) return undefined;
+
+ const hasAgent = (await source.stat(join(projectRoot, "agent"))) === "directory";
+ const hasAgents = (await source.stat(join(projectRoot, "agents"))) === "directory";
+ if (hasAgent) {
+ return { appRoot: projectRoot, environmentRoot: projectRoot, kind: "standalone" };
+ }
- const workspaceRoot = dirname(agentsRoot);
- if ((await source.stat(join(workspaceRoot, "agent"))) === "directory") return undefined;
+ if (!hasAgents) {
+ if (await hasFlatAgentRoot(projectRoot, source)) {
+ return { appRoot: projectRoot, environmentRoot: projectRoot, kind: "standalone" };
+ }
+ throw new Error(`Invalid eve project at ${projectRoot}: found no agent files.`);
+ }
- const workspace = await resolveAgentWorkspace(workspaceRoot, { source });
- const member = workspace?.members.find((candidate) => candidate.appRoot === resolvedAppRoot);
- if (workspace === undefined || member === undefined) return undefined;
+ const workspace = await resolveWorkspace(projectRoot, source);
+ const member = workspace.members.find((candidate) =>
+ containsPath(candidate.appRoot, searchDirectory),
+ );
+ if (member !== undefined) {
+ return {
+ workspace,
+ environmentRoot: workspace.root,
+ kind: "workspace-member",
+ member,
+ };
+ }
- return {
- workspace,
- environmentRoot: workspace.root,
- kind: "workspace-member",
- member,
- };
+ return { workspace, environmentRoot: workspace.root, kind: "workspace" };
}
-/** Classify the current filesystem scope before command-specific policy runs. */
+/** Resolve the owning eve project, throwing when the path has no eve package owner. */
export async function resolveEveProjectContext(
- appRoot: string,
+ startPath: string,
options: { readonly source?: ProjectSource } = {},
): Promise<EveProjectContext> {
- const resolvedAppRoot = resolve(appRoot);
- const source = options.source ?? createDiskProjectSource();
- const namedAgent = await resolveNamedAgentProjectContext(resolvedAppRoot, { source });
- if (namedAgent !== undefined) return namedAgent;
-
- const workspace = await resolveAgentWorkspace(resolvedAppRoot, { source });
- return workspace === undefined
- ? standalone(resolvedAppRoot)
- : { workspace, environmentRoot: workspace.root, kind: "workspace" };
+ const context = await findEveProjectContext(startPath, options);
+ if (context === undefined) {
+ throw new Error(`No eve project contains ${resolve(startPath)}.`);
+ }
+ return context;
}
diff --git a/packages/eve/src/internal/testing/memory-agent-source.ts b/packages/eve/src/internal/testing/memory-agent-source.ts
index b310d3d3a..a761b6989 100644
--- a/packages/eve/src/internal/testing/memory-agent-source.ts
+++ b/packages/eve/src/internal/testing/memory-agent-source.ts
@@ -93,6 +93,7 @@ export function buildMemoryAgentProject(input: MemoryAgentProjectInput = {}): Me
if (input.omitPackageJson !== true) {
files[posix.join(appRoot, "package.json")] = JSON.stringify({
+ dependencies: { eve: "*" },
name: input.packageName ?? DEFAULT_PACKAGE_NAME,
});
}
diff --git a/packages/eve/src/internal/vercel/build-agent-workspace.integration.test.ts b/packages/eve/src/internal/vercel/build-agent-workspace.integration.test.ts
index 96188805b..1a6cfc15a 100644
--- a/packages/eve/src/internal/vercel/build-agent-workspace.integration.test.ts
+++ b/packages/eve/src/internal/vercel/build-agent-workspace.integration.test.ts
@@ -8,14 +8,18 @@ vi.mock("#shared/resolve-eve-binary.js", () => ({
resolveEveBinaryPath: (root: string) => join(root, "node_modules", "eve", "bin", "eve.js"),
}));
-import { loadAgentWorkspace } from "#internal/agent-workspace.js";
+import { resolveEveProjectContext } from "#internal/project-context.js";
import { buildAgentWorkspace } from "#internal/vercel/build-agent-workspace.js";
async function createWorkspace(): Promise<string> {
const root = await mkdtemp(join(tmpdir(), "eve-workspace-build-"));
await writeFile(
join(root, "package.json"),
- JSON.stringify({ packageManager: "[email protected]", private: true }),
+ JSON.stringify({
+ dependencies: { eve: "*" },
+ packageManager: "[email protected]",
+ private: true,
+ }),
);
await Promise.all([
mkdir(join(root, "agents", "support", "agent"), { recursive: true }),
@@ -24,10 +28,16 @@ async function createWorkspace(): Promise<string> {
return root;
}
+async function resolveWorkspace(root: string) {
+ const context = await resolveEveProjectContext(root);
+ if (context.kind !== "workspace") throw new Error("Expected a workspace context.");
+ return context.workspace;
+}
+
describe("buildAgentWorkspace", () => {
it("emits peer services and canonical public routes", async () => {
const root = await createWorkspace();
- const workspace = await loadAgentWorkspace(root);
+ const workspace = await resolveWorkspace(root);
expect(workspace).toBeDefined();
const output = await buildAgentWorkspace(workspace);
@@ -65,7 +75,7 @@ describe("buildAgentWorkspace", () => {
it("keeps digit-bearing public names while encoding the generated service name", async () => {
const root = await createWorkspace();
await mkdir(join(root, "agents", "support2", "agent"), { recursive: true });
- const workspace = await loadAgentWorkspace(root);
+ const workspace = await resolveWorkspace(root);
const output = await buildAgentWorkspace(workspace);
const config = JSON.parse(await readFile(join(output, "config.json"), "utf8"));
const supportServiceName = Object.keys(config.services).find((name) =>
@@ -82,7 +92,7 @@ describe("buildAgentWorkspace", () => {
it("refuses to assemble an authored graph", async () => {
const root = await createWorkspace();
await writeFile(join(root, "vercel.json"), JSON.stringify({ services: {} }));
- const workspace = await loadAgentWorkspace(root);
+ const workspace = await resolveWorkspace(root);
await expect(buildAgentWorkspace(workspace)).rejects.toThrow(/Run `vercel build`/);
});
});
diff --git a/packages/eve/src/internal/vercel/build-agent-workspace.ts b/packages/eve/src/internal/vercel/build-agent-workspace.ts
index 597aa41b9..947622f23 100644
--- a/packages/eve/src/internal/vercel/build-agent-workspace.ts
+++ b/packages/eve/src/internal/vercel/build-agent-workspace.ts
@@ -1,7 +1,7 @@
import { mkdir, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
-import type { AgentWorkspace } from "#internal/agent-workspace.js";
+import type { AgentWorkspace } from "#internal/project-context.js";
import { assembleEveVercelServices } from "#internal/vercel/assemble-eve-services.js";
import { quoteVercelShellArgument, toVercelRelativePath } from "#internal/vercel/build-command.js";
import { readVercelJsonFile } from "#internal/vercel/vercel-services-config.js";
diff --git a/packages/eve/test/scenarios/bin-build-output.scenario.test.ts b/packages/eve/test/scenarios/bin-build-output.scenario.test.ts
index 122be2a23..18fae37da 100644
--- a/packages/eve/test/scenarios/bin-build-output.scenario.test.ts
+++ b/packages/eve/test/scenarios/bin-build-output.scenario.test.ts
@@ -77,6 +77,7 @@ async function createTemporaryAppRoot(input: {
join(appRoot, "package.json"),
`${JSON.stringify(
{
+ dependencies: { eve: "*" },
name: "eve-bin-build-output-test",
private: true,
type: "module",
diff --git a/packages/eve/test/scenarios/cli.scenario.test.ts b/packages/eve/test/scenarios/cli.scenario.test.ts
index bd31c8fbe..b3d62bdc7 100644
--- a/packages/eve/test/scenarios/cli.scenario.test.ts
+++ b/packages/eve/test/scenarios/cli.scenario.test.ts
@@ -57,6 +57,7 @@ async function createMinimalAppRoot(prefix: string): Promise<string> {
join(appRoot, "package.json"),
`${JSON.stringify(
{
+ dependencies: { eve: "*" },
name: "eve-cli-start-health-test",
private: true,
type: "module",
@@ -204,13 +205,20 @@ describe("runCli", () => {
});
it("prints the installed package version when running a CLI command", async () => {
+ const appRoot = await createMinimalAppRoot("eve-cli-version-");
+ const previousCwd = process.cwd();
const logger = {
error: vi.fn(),
log: vi.fn(),
};
const evePackage = resolveInstalledPackageInfo();
- await runCli(["info"], logger);
+ process.chdir(appRoot);
+ try {
+ await runCli(["info"], logger);
+ } finally {
+ process.chdir(previousCwd);
+ }
const output = getLogOutput(logger);
expect(output).toContain("eve");
@@ -218,6 +226,8 @@ describe("runCli", () => {
});
it("does not print the startup banner before JSON eval output", async () => {
+ const appRoot = await createMinimalAppRoot("eve-cli-eval-json-");
+ const previousCwd = process.cwd();
const logger = {
error: vi.fn(),
log: vi.fn(),
@@ -226,20 +236,32 @@ describe("runCli", () => {
logger.log("{}");
});
- await runCli(["eval", "--json"], logger, {
- runEvalCommand,
- });
+ process.chdir(appRoot);
+ try {
+ await runCli(["eval", "--json"], logger, {
+ runEvalCommand,
+ });
+ } finally {
+ process.chdir(previousCwd);
+ }
expect(getLogOutput(logger)).toBe("{}");
});
it("prints fixture information", async () => {
+ const appRoot = await createMinimalAppRoot("eve-cli-info-");
+ const previousCwd = process.cwd();
const logger = {
error: vi.fn(),
log: vi.fn(),
};
- await runCli(["info"], logger);
+ process.chdir(appRoot);
+ try {
+ await runCli(["info"], logger);
+ } finally {
+ process.chdir(previousCwd);
+ }
expect(logger.log).toHaveBeenCalled();
expect(getLogOutput(logger)).not.toContain("eve Info");
@@ -279,6 +301,8 @@ describe("runCli", () => {
});
it("defaults to dev when no command is provided in an eve project", async () => {
+ const appRoot = await createMinimalAppRoot("eve-cli-default-dev-");
+ const previousCwd = process.cwd();
const logger = {
error: vi.fn(),
log: vi.fn(),
@@ -291,12 +315,17 @@ describe("runCli", () => {
close: async () => {},
}));
- await expect(
- runCli([], logger, {
- findApplicationRoot,
- startHost,
- }),
- ).rejects.toThrow("dev started");
+ process.chdir(appRoot);
+ try {
+ await expect(
+ runCli([], logger, {
+ findApplicationRoot,
+ startHost,
+ }),
+ ).rejects.toThrow("dev started");
+ } finally {
+ process.chdir(previousCwd);
+ }
expect(findApplicationRoot).toHaveBeenCalledOnce();
expect(startHost).toHaveBeenCalledOnce();
@@ -442,7 +471,7 @@ describe("runCli", () => {
});
await writeFile(
join(workspaceRoot, "package.json"),
- `${JSON.stringify({ name: "build-diagnostics" }, null, 2)}\n`,
+ `${JSON.stringify({ dependencies: { eve: "*" }, name: "build-diagnostics" }, null, 2)}\n`,
);
await writeFile(
join(workspaceRoot, "agent", "agent.mjs"),
diff --git a/packages/eve/test/scenarios/eval-command-environment.scenario.test.ts b/packages/eve/test/scenarios/eval-command-environment.scenario.test.ts
index 7fa5a3290..ff99968f0 100644
--- a/packages/eve/test/scenarios/eval-command-environment.scenario.test.ts
+++ b/packages/eve/test/scenarios/eval-command-environment.scenario.test.ts
@@ -54,7 +54,7 @@ async function createEnvironmentFixture(): Promise<string> {
await mkdir(join(fixtureRoot, "agent"), { recursive: true });
await writeFile(
join(fixtureRoot, "package.json"),
- `${JSON.stringify({ name: "eve-eval-env-test", private: true, type: "module" })}\n`,
+ `${JSON.stringify({ dependencies: { eve: "*" }, name: "eve-eval-env-test", private: true, type: "module" })}\n`,
);
await writeFile(
join(fixtureRoot, "agent", "agent.mjs"),