Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add non-interactive setup protocol (#1788)

OwenKephartf06e12e0f4b7
diff --git a/.changeset/tough-setup-headless.md b/.changeset/tough-setup-headless.md
new file mode 100644
index 000000000..655a1c0e9
--- /dev/null
+++ b/.changeset/tough-setup-headless.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add a structured `eve add --non-interactive` flow with stable setup answers, component selection, and resumable setup blockers for coding agents.
diff --git a/apps/docs/registry.json b/apps/docs/registry.json
index bf830149a..1e71092a8 100644
--- a/apps/docs/registry.json
+++ b/apps/docs/registry.json
@@ -1200,7 +1200,7 @@
"bin": "eve",
"args": ["integration", "setup", "slack"]
},
- "requires": ">=0.27.8"
+ "requires": ">=0.31.4"
}
},
"dependencies": ["@vercel/connect@>=0.4.2"]
@@ -1219,7 +1219,7 @@
"bin": "eve",
"args": ["integration", "setup", "discord"]
},
- "requires": ">=0.30.0"
+ "requires": ">=0.31.4"
}
}
},
@@ -1286,7 +1286,7 @@
"bin": "eve",
"args": ["integration", "setup", "github"]
},
- "requires": ">=0.30.7"
+ "requires": ">=0.31.4"
}
},
"dependencies": ["@vercel/connect@>=0.6.0"]
@@ -1304,7 +1304,7 @@
"bin": "eve",
"args": ["integration", "setup", "linear"]
},
- "requires": ">=0.30.6"
+ "requires": ">=0.31.4"
}
},
"dependencies": ["@vercel/connect"]
@@ -1322,7 +1322,7 @@
"bin": "eve",
"args": ["integration", "setup", "web"]
},
- "requires": ">=0.27.8"
+ "requires": ">=0.31.4"
}
},
"dependencies": [
@@ -1758,7 +1758,7 @@
"bin": "eve",
"args": ["integration", "setup", "photon"]
},
- "requires": ">=0.29.0"
+ "requires": ">=0.31.4"
}
}
},
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 675b54daa..796fb305d 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -98,7 +98,7 @@ eve registry view @acme/my-extension
eve add @acme/my-extension
```
-`eve add` asks before running setup declared by an official item and runs multiple declared flows in declaration order. Product-level packages can offer independently installable components: `eve add linear` lets you select the Linear Channel, Linear MCP, or both, with both selected by default. `--yes` installs a package's default components.
+`eve add` asks before running setup declared by an official item and runs multiple declared flows in declaration order. Product-level packages can offer independently installable components: `eve add linear` lets you select the Linear Channel, Linear MCP, or both, with both selected by default. `--yes` installs a package's default components and accepts detected or recommended setup answers.
When setup is skipped or cancelled, eve prints the matching `eve add <item> --skip-install` command. `--skip-install` reruns the selected components' declared flows from the beginning without reinstalling them.
diff --git a/packages/eve/src/cli/commands/integration-connect.test.ts b/packages/eve/src/cli/commands/integration-connect.test.ts
index 434b8b46f..684d977b0 100644
--- a/packages/eve/src/cli/commands/integration-connect.test.ts
+++ b/packages/eve/src/cli/commands/integration-connect.test.ts
@@ -2,7 +2,14 @@ import { afterEach, describe, expect, it, vi } from "vitest";
import { createFakePrompter } from "#internal/testing/fake-prompter.js";
-import { runIntegrationConnect } from "./integration-connect.js";
+import { runIntegrationConnect, runIntegrationConnectCommand } from "./integration-connect.js";
+
+const { isEveProject } = vi.hoisted(() => ({ isEveProject: vi.fn(async () => true) }));
+
+vi.mock("#setup/scaffold/index.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("#setup/scaffold/index.js")>()),
+ isEveProject,
+}));
const PROJECT = { orgId: "team_1", projectId: "prj_1" };
@@ -66,6 +73,50 @@ describe("runIntegrationConnect", () => {
);
});
+ it("requires a linked project without starting the link flow non-interactively", async () => {
+ const deps = dependencies({ readProjectLink: vi.fn(async () => undefined) });
+
+ await expect(
+ runIntegrationConnect({
+ appRoot: "/project",
+ slug: "linear",
+ service: "mcp.linear.app",
+ options: { nonInteractive: true },
+ dependencies: deps,
+ }),
+ ).rejects.toMatchObject({
+ prerequisite: expect.objectContaining({ code: "vercel-project-link", command: "eve link" }),
+ });
+ expect(deps.runLinkFlow).not.toHaveBeenCalled();
+ expect(deps.setupConnectionConnector).not.toHaveBeenCalled();
+ });
+
+ it("emits a structured linked-project prerequisite non-interactively", async () => {
+ const output = {
+ errors: [] as string[],
+ log: vi.fn(),
+ error: vi.fn((message) => output.errors.push(message)),
+ };
+ const deps = dependencies({ readProjectLink: vi.fn(async () => undefined) });
+
+ await runIntegrationConnectCommand(
+ output,
+ "/project",
+ "linear",
+ "mcp.linear.app",
+ undefined,
+ { nonInteractive: true },
+ deps,
+ );
+
+ expect(JSON.parse(output.errors[0]!)).toMatchObject({
+ type: "blocked",
+ status: "prerequisite_required",
+ prerequisite: { code: "vercel-project-link", command: "eve link" },
+ });
+ expect(process.exitCode).toBe(2);
+ });
+
it("cleans up a newly-created connector when the installed file cannot be patched", async () => {
const deps = dependencies({
setupConnectionConnector: vi.fn(async () => ({
diff --git a/packages/eve/src/cli/commands/integration-connect.ts b/packages/eve/src/cli/commands/integration-connect.ts
index fff686a79..c47bc08fc 100644
--- a/packages/eve/src/cli/commands/integration-connect.ts
+++ b/packages/eve/src/cli/commands/integration-connect.ts
@@ -6,6 +6,9 @@ import {
type SetupConnectionConnectorOptions,
} from "#setup/connection-connector.js";
import { runLinkFlow, type LinkFlowDeps } from "#setup/flows/link.js";
+import { createHeadlessPrompter } from "#setup/headless.js";
+import { SetupPrerequisiteRequired } from "#setup/integrations/shared/prerequisite.js";
+import { resolveIntegrationVercelProject } from "#setup/integrations/shared/vercel-project.js";
import { readProjectLink } from "#setup/project-resolution.js";
import { createPrompter, type Prompter } from "#setup/prompter.js";
import { createRegistrySetupClient } from "#setup/registry-setup-client.js";
@@ -14,8 +17,10 @@ import { updateConnectionConnectorUid } from "#setup/scaffold/update/update-conn
import { NOT_AN_AGENT_MESSAGE } from "./preconditions.js";
import type { RegistryCommandLogger } from "./registry.js";
+import { serializeHeadlessSetupEvent } from "./setup-headless.js";
export interface IntegrationConnectOptions {
+ nonInteractive?: boolean;
signal?: AbortSignal;
}
@@ -47,24 +52,36 @@ export async function runIntegrationConnect(input: {
dependencies?: Partial<IntegrationConnectDependencies>;
}): Promise<void> {
const dependencies = { ...defaultDependencies, ...input.dependencies };
- const prompter = dependencies.createPrompter?.() ?? createPrompter();
+ const nonInteractive = input.options?.nonInteractive === true;
+ const prompter =
+ dependencies.createPrompter?.() ??
+ (nonInteractive ? createHeadlessPrompter(() => {}) : createPrompter());
const signal = input.options?.signal;
prompter.intro(`Set up ${input.slug}`);
let project = await dependencies.readProjectLink(input.appRoot);
if (project === undefined) {
- const link = await dependencies.runLinkFlow({
- appRoot: input.appRoot,
- prompter,
- signal,
- projectSelection: "create-or-link",
- teamSelectMessage: () =>
- `You need to link to a project to use ${input.slug} through Vercel Connect.\n\nSelect your team`,
- deps: dependencies.linkFlowDeps,
- });
- if (link.kind === "cancelled") return;
- project = await dependencies.readProjectLink(input.appRoot);
- if (project === undefined) throw new Error("Project link was not found after linking.");
+ if (nonInteractive) {
+ project = await resolveIntegrationVercelProject({
+ appRoot: input.appRoot,
+ integration: input.slug,
+ signal,
+ deps: { readProjectLink: dependencies.readProjectLink },
+ });
+ } else {
+ const link = await dependencies.runLinkFlow({
+ appRoot: input.appRoot,
+ prompter,
+ signal,
+ projectSelection: "create-or-link",
+ teamSelectMessage: () =>
+ `You need to link to a project to use ${input.slug} through Vercel Connect.\n\nSelect your team`,
+ deps: dependencies.linkFlowDeps,
+ });
+ if (link.kind === "cancelled") return;
+ project = await dependencies.readProjectLink(input.appRoot);
+ if (project === undefined) throw new Error("Project link was not found after linking.");
+ }
}
const connectorOptions: SetupConnectionConnectorOptions = {
@@ -126,6 +143,19 @@ export async function runIntegrationConnectCommand(
client?.complete();
} catch (error) {
client?.fail(error);
+ if (client !== undefined) return;
+ if (options.nonInteractive && error instanceof SetupPrerequisiteRequired) {
+ logger.error(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "blocked",
+ status: "prerequisite_required",
+ prerequisite: error.prerequisite,
+ }),
+ );
+ process.exitCode = 2;
+ return;
+ }
logger.error(error instanceof Error ? error.message : String(error));
process.exitCode = 1;
}
diff --git a/packages/eve/src/cli/commands/integration-setup.test.ts b/packages/eve/src/cli/commands/integration-setup.test.ts
index 3b4bd605d..9113b9672 100644
--- a/packages/eve/src/cli/commands/integration-setup.test.ts
+++ b/packages/eve/src/cli/commands/integration-setup.test.ts
@@ -1,6 +1,7 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { createFakePrompter } from "#internal/testing/fake-prompter.js";
+import { InteractionRequired, select } from "#setup/ask.js";
import { ensureVercelProject } from "#setup/flows/ensure-vercel-project.js";
import { runIntegrationSetup } from "#setup/integrations/runner.js";
@@ -9,6 +10,18 @@ import type { RegistryCommandLogger } from "./registry.js";
const { isEveProject } = vi.hoisted(() => ({ isEveProject: vi.fn(async () => true) }));
+class SetupProcess {
+ connected = true;
+ readonly sent: unknown[] = [];
+ send = (message: unknown) => {
+ this.sent.push(message);
+ return true;
+ };
+ disconnect() {}
+ on() {}
+ off() {}
+}
+
vi.mock("#setup/scaffold/index.js", async (importOriginal) => ({
...(await importOriginal<typeof import("#setup/scaffold/index.js")>()),
isEveProject,
@@ -64,4 +77,129 @@ describe("runIntegrationSetupCommand", () => {
});
expect(output.errors).toEqual([]);
});
+
+ it("assumes recommended setup answers with --yes in interactive mode", async () => {
+ vi.mocked(runIntegrationSetup).mockImplementation(async (_kind, options) => {
+ await expect(
+ options.asker?.ask(
+ select({
+ key: "mode",
+ message: "Mode?",
+ options: [{ id: "portable", label: "Portable", value: "environment" }],
+ recommended: "environment",
+ required: true,
+ }),
+ ),
+ ).resolves.toBe("environment");
+ return { kind: "done", completion: { facts: [] } };
+ });
+
+ await runIntegrationSetupCommand(logger(), "/project", "web", { yes: true });
+ });
+
+ it("passes answer-backed headless setup to the runner", async () => {
+ vi.mocked(runIntegrationSetup).mockImplementation(async (_kind, options) => {
+ await expect(
+ options.asker?.ask(
+ select({
+ key: "mode",
+ message: "Mode?",
+ options: [{ id: "portable", label: "Portable", value: "environment" }],
+ required: true,
+ }),
+ ),
+ ).resolves.toBe("environment");
+ expect(options.asker).toBeDefined();
+ return { kind: "done", completion: { facts: [] } };
+ });
+
+ await runIntegrationSetupCommand(logger(), "/project", "web", {
+ nonInteractive: true,
+ answers: { mode: "portable" },
+ });
+ });
+
+ it("marks external actions as blocking while the command keeps running", async () => {
+ const output = logger();
+ const logs: string[] = [];
+ output.log = (message) => logs.push(message);
+ vi.mocked(runIntegrationSetup).mockImplementation(async (_kind, options) => {
+ const action = options.beginExternalAction?.({
+ message: "Authorize Photon",
+ url: "https://example.com/device",
+ userCode: "ABCD1234",
+ });
+ action?.complete();
+ return { kind: "done", completion: { facts: [] } };
+ });
+
+ await runIntegrationSetupCommand(output, "/project", "photon", { nonInteractive: true });
+
+ expect(JSON.parse(logs[0]!)).toMatchObject({
+ version: 1,
+ type: "external_action",
+ blocking: true,
+ message: "Authorize Photon",
+ url: "https://example.com/device",
+ userCode: "ABCD1234",
+ });
+ const started = JSON.parse(logs[0]!) as { id: string };
+ expect(JSON.parse(logs[1]!)).toEqual({
+ version: 1,
+ type: "external_action_resolved",
+ id: started.id,
+ });
+ });
+
+ it("leaves blocked event ownership to the parent setup process", async () => {
+ const previousProtocol = process.env.EVE_SETUP_PROTOCOL;
+ process.env.EVE_SETUP_PROTOCOL = "2";
+ const setupProcess = new SetupProcess();
+ const output = logger();
+ vi.mocked(runIntegrationSetup).mockRejectedValue(
+ new InteractionRequired(
+ select({ key: "mode", message: "Mode?", options: [], required: true }),
+ ),
+ );
+
+ try {
+ await runIntegrationSetupCommand(
+ output,
+ "/project",
+ "web",
+ { nonInteractive: true },
+ {
+ setupProcess,
+ },
+ );
+ } finally {
+ if (previousProtocol === undefined) delete process.env.EVE_SETUP_PROTOCOL;
+ else process.env.EVE_SETUP_PROTOCOL = previousProtocol;
+ }
+
+ expect(output.errors).toEqual([]);
+ expect(setupProcess.sent).toContainEqual(
+ expect.objectContaining({
+ type: "result",
+ outcome: expect.objectContaining({ kind: "blocked" }),
+ }),
+ );
+ });
+
+ it("serializes structured missing input in headless JSON mode", async () => {
+ vi.mocked(runIntegrationSetup).mockRejectedValue(
+ new InteractionRequired(
+ select({ key: "mode", message: "Mode?", options: [], required: true }),
+ ),
+ );
+ const output = logger();
+
+ await runIntegrationSetupCommand(output, "/project", "web", { nonInteractive: true });
+
+ expect(JSON.parse(output.errors[0]!)).toMatchObject({
+ status: "input_required",
+ type: "blocked",
+ question: { key: "mode" },
+ });
+ });
});
diff --git a/packages/eve/src/cli/commands/integration-setup.ts b/packages/eve/src/cli/commands/integration-setup.ts
index 83cda88e6..53c3c5870 100644
--- a/packages/eve/src/cli/commands/integration-setup.ts
+++ b/packages/eve/src/cli/commands/integration-setup.ts
@@ -1,23 +1,38 @@
+import {
+ headlessAsker,
+ InteractionRequired,
+ interactiveAsker,
+ InvalidAnswerError,
+ withAnswers,
+ withPolicy,
+} from "#setup/ask.js";
import { ensureVercelProject } from "#setup/flows/ensure-vercel-project.js";
+import { createHeadlessPrompter } from "#setup/headless.js";
+import { SetupPrerequisiteRequired } from "#setup/integrations/shared/prerequisite.js";
import { createPrompter, type Prompter } from "#setup/prompter.js";
-import { createRegistrySetupClient } from "#setup/registry-setup-client.js";
+import { createRegistrySetupClient, type SetupProcess } from "#setup/registry-setup-client.js";
import {
runIntegrationSetup,
type IntegrationSetupRunnerDeps,
} from "#setup/integrations/runner.js";
import { isEveProject } from "#setup/scaffold/index.js";
+import { setupQuestionToWire } from "#setup/setup-question-wire.js";
import { NOT_AN_AGENT_MESSAGE } from "./preconditions.js";
import type { RegistryCommandLogger } from "./registry.js";
+import { serializeHeadlessSetupEvent } from "./setup-headless.js";
export interface IntegrationSetupOptions {
yes?: boolean;
+ nonInteractive?: boolean;
+ answers?: Record<string, unknown>;
signal?: AbortSignal;
}
export interface IntegrationSetupDependencies {
createPrompter?: () => Prompter;
runnerDeps?: IntegrationSetupRunnerDeps;
+ setupProcess?: SetupProcess;
}
const defaultIntegrationSetupDependencies: IntegrationSetupDependencies = {};
@@ -36,34 +51,111 @@ export async function runIntegrationSetupCommand(
return;
}
- const client = createRegistrySetupClient({ signal: options.signal });
+ const client = createRegistrySetupClient({
+ process: dependencies.setupProcess,
+ signal: options.signal,
+ });
try {
- const prompter = client?.prompter ?? dependencies.createPrompter?.() ?? createPrompter();
+ const nonInteractive = options.nonInteractive === true;
+ const prompter =
+ client?.prompter ??
+ dependencies.createPrompter?.() ??
+ (nonInteractive ? createHeadlessPrompter(() => {}) : createPrompter());
+ const base = nonInteractive ? headlessAsker() : interactiveAsker(prompter);
+ const policy = options.yes ? withPolicy("assume")(base) : base;
+ const asker = withAnswers(options.answers ?? {})(policy);
const result = await runIntegrationSetup(
kind,
{
appRoot,
prompter,
- resolveVercelProject: () =>
- ensureVercelProject({
- appRoot,
- prompter,
- signal: client?.signal ?? options.signal,
- }),
+ asker,
+ resolveVercelProject: nonInteractive
+ ? undefined
+ : () =>
+ ensureVercelProject({
+ appRoot,
+ prompter,
+ signal: client?.signal ?? options.signal,
+ }),
signal: client?.signal ?? options.signal,
+ beginExternalAction: nonInteractive
+ ? (action) => {
+ const id = `external-action-${crypto.randomUUID()}`;
+ logger.log(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "external_action",
+ id,
+ blocking: true,
+ ...action,
+ }),
+ );
+ return {
+ complete() {
+ logger.log(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "external_action_resolved",
+ id,
+ }),
+ );
+ },
+ };
+ }
+ : undefined,
},
dependencies.runnerDeps,
);
if (result.kind === "cancelled") {
client?.cancel();
if (process.env.EVE_SETUP === "1") process.exitCode = 130;
+ else if (nonInteractive)
+ logger.error(serializeHeadlessSetupEvent({ version: 1, type: "cancelled", item: kind }));
return;
}
prompter.outro("Integration set up.");
client?.complete(result.completion);
+ if (nonInteractive && client === undefined) {
+ logger.log(serializeHeadlessSetupEvent({ version: 1, type: "completed", item: kind }));
+ }
} catch (error) {
client?.fail(error);
- logger.error(error instanceof Error ? error.message : String(error));
- process.exitCode = 1;
+ if (client !== undefined) return;
+ if (options.nonInteractive && error instanceof InteractionRequired) {
+ logger.error(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "blocked",
+ status: "input_required",
+ question: setupQuestionToWire(error.question),
+ }),
+ );
+ process.exitCode = 2;
+ } else if (options.nonInteractive && error instanceof InvalidAnswerError) {
+ logger.error(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "blocked",
+ status: "input_required",
+ question: setupQuestionToWire(error.question),
+ issue: { code: "invalid_answer", message: error.message },
+ }),
+ );
+ process.exitCode = 2;
+ } else if (options.nonInteractive && error instanceof SetupPrerequisiteRequired) {
+ logger.error(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "blocked",
+ status: "prerequisite_required",
+ prerequisite: error.prerequisite,
+ }),
+ );
+ process.exitCode = 2;
+ } else {
+ logger.error(error instanceof Error ? error.message : String(error));
+ process.exitCode = 1;
+ }
}
}
diff --git a/packages/eve/src/cli/commands/register-integration-commands.ts b/packages/eve/src/cli/commands/register-integration-commands.ts
index d9fba4dbd..48c15ccab 100644
--- a/packages/eve/src/cli/commands/register-integration-commands.ts
+++ b/packages/eve/src/cli/commands/register-integration-commands.ts
@@ -1,5 +1,7 @@
import type { Command } from "#compiled/commander/index.js";
+import { parseSetupAnswer } from "./setup-answers.js";
+
interface IntegrationCommandLogger {
error(message: string): void;
log(message: string): void;
@@ -18,16 +20,50 @@ export function registerIntegrationCommands(input: {
integration
.command("setup <kind>")
.option("-y, --yes")
- .action(async (kind: string, options: { yes?: boolean }) => {
- const { runIntegrationSetupCommand } = await import("./integration-setup.js");
- await runIntegrationSetupCommand(logger, appRoot, kind, { yes: options.yes });
- });
+ .option(
+ "--non-interactive",
+ "Run without interactive prompts, instead emit structured NDJSON when further input is required",
+ )
+ .option(
+ "--answer <key=value>",
+ "Answer a setup question; requires --non-interactive.",
+ parseSetupAnswer,
+ {},
+ )
+ .action(
+ async (
+ kind: string,
+ options: {
+ yes?: boolean;
+ nonInteractive?: boolean;
+ answer?: Record<string, unknown>;
+ },
+ ) => {
+ const { runIntegrationSetupCommand } = await import("./integration-setup.js");
+ await runIntegrationSetupCommand(logger, appRoot, kind, {
+ yes: options.yes,
+ nonInteractive: options.nonInteractive,
+ answers: options.answer,
+ });
+ },
+ );
integration
.command("connect <slug> <service> [canonical-name]")
.option("-y, --yes")
- .action(async (slug: string, service: string, canonicalName: string | undefined) => {
- const { runIntegrationConnectCommand } = await import("./integration-connect.js");
- await runIntegrationConnectCommand(logger, appRoot, slug, service, canonicalName);
- });
+ .option(
+ "--non-interactive",
+ "Run without interactive prompts, instead emit structured NDJSON when further input is required",
+ )
+ .action(
+ async (
+ slug: string,
+ service: string,
+ canonicalName: string | undefined,
+ options: { nonInteractive?: boolean },
+ ) => {
+ const { runIntegrationConnectCommand } = await import("./integration-connect.js");
+ await runIntegrationConnectCommand(logger, appRoot, slug, service, canonicalName, options);
+ },
+ );
}
diff --git a/packages/eve/src/cli/commands/register-registry-commands.ts b/packages/eve/src/cli/commands/register-registry-commands.ts
index 159ba76dd..704e1bd98 100644
--- a/packages/eve/src/cli/commands/register-registry-commands.ts
+++ b/packages/eve/src/cli/commands/register-registry-commands.ts
@@ -1,5 +1,7 @@
import { InvalidArgumentError, type Command } from "#compiled/commander/index.js";
+import { parseSetupAnswer } from "./setup-answers.js";
+
interface RegistryCommandLogger {
error(message: string): void;
log(message: string): void;
@@ -36,14 +38,33 @@ export function registerRegistryCommands(input: {
.option("-o, --overwrite", "Overwrite existing files.")
.option("--skip-install", "Run the item's setup flow without installing it.")
.option("--skip-setup", "Skip the item's setup flow.")
+ .option(
+ "--non-interactive",
+ "Run without interactive prompts, instead emit structured NDJSON when further input is required",
+ )
+ .option(
+ "--answer <key=value>",
+ "Answer a setup question with JSON; requires --non-interactive; repeat for multiple answers.",
+ parseSetupAnswer,
+ )
.option("-y, --yes", "Run setup and accept its recommended defaults.")
.action(
async (
item: string,
- options: { skipInstall?: boolean; overwrite?: boolean; skipSetup?: boolean; yes?: boolean },
+ options: {
+ skipInstall?: boolean;
+ overwrite?: boolean;
+ skipSetup?: boolean;
+ nonInteractive?: boolean;
+ answer?: Record<string, unknown>;
+ yes?: boolean;
+ },
) => {
+ if (options.answer !== undefined && !options.nonInteractive) {
+ throw new InvalidArgumentError("--answer requires --non-interactive.");
+ }
const { runAddCommand } = await import("./registry.js");
- await runAddCommand(logger, appRoot, item, options);
+ await runAddCommand(logger, appRoot, item, { ...options, answers: options.answer });
},
);
diff --git a/packages/eve/src/cli/commands/registry-declared-setups.ts b/packages/eve/src/cli/commands/registry-declared-setups.ts
index 4c93363bf..64bd306ab 100644
--- a/packages/eve/src/cli/commands/registry-declared-setups.ts
+++ b/packages/eve/src/cli/commands/registry-declared-setups.ts
@@ -1,12 +1,16 @@
+import { createHeadlessPrompter } from "#setup/headless.js";
import { createPrompter, type Prompter } from "#setup/prompter.js";
import { mergeRegistrySetupCompletions } from "#setup/registry-setup-completion.js";
import type { RegistrySetupCompletion } from "#setup/registry-setup-protocol.js";
import type { RegistryCommandLogger, RegistrySetupDependencies } from "./registry.js";
import type { RegistrySetupCommand } from "./registry-setup-command.js";
+import { headlessSetupContinuation, serializeHeadlessSetupEvent } from "./setup-headless.js";
export interface DeclaredSetupOptions {
yes?: boolean;
+ nonInteractive?: boolean;
+ answers?: Record<string, unknown>;
silent?: boolean;
prompter?: Prompter;
signal?: AbortSignal;
@@ -26,12 +30,25 @@ export async function runDeclaredSetups(input: {
let completion: RegistrySetupCompletion = { facts: [] };
if (input.setups === undefined) return completion;
const runSetupCommand = await input.dependencies.loadSetupCommandRunner();
- const prompter = input.options.prompter ?? createPrompter();
+ const prompter =
+ input.options.prompter ??
+ (input.options.nonInteractive ? createHeadlessPrompter(input.logger.log) : createPrompter());
try {
for (const setup of input.setups) {
const result = await runSetupCommand(
input.appRoot,
- { ...setup, args: [...setup.args, ...(input.options.yes ? ["--yes"] : [])] },
+ {
+ ...setup,
+ args: [
+ ...setup.args,
+ ...(input.options.yes ? ["--yes"] : []),
+ ...(input.options.nonInteractive ? ["--non-interactive"] : []),
+ ...Object.entries(input.options.answers ?? {}).flatMap(([key, value]) => [
+ "--answer",
+ `${key}=${JSON.stringify(value)}`,
+ ]),
+ ],
+ },
input.item,
{ prompter, signal: input.options.signal },
);
@@ -39,14 +56,43 @@ export async function runDeclaredSetups(input: {
input.logger.log(input.cancelledReminder);
return false;
}
- if (input.options.silent !== true) {
- for (const fact of result.facts) input.logger.log(`${fact.label}: ${fact.value}`);
+ if (result.kind === "blocked") {
+ if (!input.options.nonInteractive) throw new Error("Setup requires more input.");
+ input.logger.error(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "blocked",
+ item: input.item,
+ installed: true,
+ completedItems: [],
+ ...result.blocker,
+ next: headlessSetupContinuation({ item: input.item, installed: true }),
+ }),
+ );
+ process.exitCode = 2;
+ return false;
}
+ if (input.options.silent !== true)
+ for (const fact of result.facts) input.logger.log(`${fact.label}: ${fact.value}`);
completion = mergeRegistrySetupCompletions(completion, result);
}
return completion;
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
+ if (input.options.nonInteractive) {
+ input.logger.error(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "failed",
+ item: input.item,
+ completedItems: [],
+ message,
+ next: headlessSetupContinuation({ item: input.item, installed: true }),
+ }),
+ );
+ process.exitCode = 1;
+ return false;
+ }
throw new Error(`${message} Try again with \`${input.resumeCommand}\`.`);
}
}
diff --git a/packages/eve/src/cli/commands/registry-package.ts b/packages/eve/src/cli/commands/registry-package.ts
index 2ee028786..f9b8845cf 100644
--- a/packages/eve/src/cli/commands/registry-package.ts
+++ b/packages/eve/src/cli/commands/registry-package.ts
@@ -4,6 +4,7 @@ import {
type RegistryConfig,
} from "#compiled/shadcn-registry/index.js";
import { z } from "#compiled/zod/index.js";
+import { headlessAsker, interactiveAsker, withAnswers, withPolicy } from "#setup/ask.js";
import { createPrompter, type Prompter } from "#setup/prompter.js";
import { mergeRegistrySetupCompletions } from "#setup/registry-setup-completion.js";
import type { RegistrySetupCompletion } from "#setup/registry-setup-protocol.js";
@@ -11,6 +12,7 @@ import type { RegistrySetupCompletion } from "#setup/registry-setup-protocol.js"
import { hasInteractiveTerminal } from "./preconditions.js";
import type { AddCommandOptions, RegistryCommandLogger } from "./registry.js";
import type { RegistrySetupCommand } from "./registry-setup-command.js";
+import { headlessSetupContinuation, serializeHeadlessSetupEvent } from "./setup-headless.js";
export const RegistryPackageComponentSchema = z.object({
item: z.string().min(1),
@@ -18,19 +20,15 @@ export const RegistryPackageComponentSchema = z.object({
description: z.string().optional(),
default: z.boolean().default(false),
});
-
export type RegistryPackageComponent = z.infer<typeof RegistryPackageComponentSchema>;
-
interface PackageMetadata {
requires?: string;
setup?: RegistrySetupCommand[];
}
-
export interface RegistryPackageDependencies {
createPrompter?: () => Prompter;
hasInteractiveTerminal?: () => boolean;
}
-
export interface RegistryPackageOperations {
itemAddress(item: string): string;
metadata(item: unknown): PackageMetadata | undefined;
@@ -44,35 +42,61 @@ export interface RegistryPackageOperations {
}
async function selectComponents(
+ logger: RegistryCommandLogger,
item: string,
components: readonly RegistryPackageComponent[],
options: AddCommandOptions & { prompter?: Prompter },
interactive: boolean,
getPrompter: () => Prompter,
-): Promise<readonly RegistryPackageComponent[]> {
- if (options.prompter === undefined && (options.yes === true || !interactive)) {
+): Promise<readonly RegistryPackageComponent[] | undefined> {
+ if (
+ options.prompter === undefined &&
+ !options.nonInteractive &&
+ (options.yes === true || !interactive)
+ ) {
return components.filter((component) => component.default);
}
- const prompter = getPrompter();
- const selected = await prompter.select<string>({
+ const question = {
+ key: "components",
message: `Add ${item}`,
- description: "Select what you want to add to your agent.",
- multiple: true,
required: true,
- initialValues: components
- .filter((component) => component.default)
- .map((component) => component.item),
+ recommended: components.filter((component) => component.default),
options: components.map((component) => ({
- value: component.item,
+ id: component.item,
+ value: component,
label: component.label,
hint: component.description,
})),
- });
- const selectedItems = new Set(selected);
- return components.filter((component) => selectedItems.has(component.item));
+ };
+ const asker = options.nonInteractive
+ ? withAnswers(options.answers ?? {})(
+ options.yes ? withPolicy("assume")(headlessAsker()) : headlessAsker(),
+ )
+ : interactiveAsker(getPrompter());
+ try {
+ return await asker.askMany(question);
+ } catch (error) {
+ if (!options.nonInteractive || !(error instanceof Error) || error.name !== "InteractionRequired")
+ throw error;
+ const question = (error as import("#setup/ask.js").InteractionRequired).question;
+ const { setupQuestionToWire } = await import("#setup/setup-question-wire.js");
+ logger.error(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "blocked",
+ status: "input_required",
+ item,
+ installed: false,
+ completedItems: [],
+ question: setupQuestionToWire(question),
+ next: headlessSetupContinuation({ item, installed: false }),
+ }),
+ );
+ process.exitCode = 2;
+ return undefined;
+ }
}
-/** Resolves, installs, and configures the selected components of a registry package. */
export async function runRegistryPackage(input: {
logger: RegistryCommandLogger;
appRoot: string;
@@ -88,35 +112,37 @@ export async function runRegistryPackage(input: {
let prompter = options.prompter;
const getPrompter = (): Prompter =>
(prompter ??= dependencies.createPrompter?.() ?? createPrompter());
-
- const selected = await selectComponents(item, components, options, interactive, getPrompter);
+ const selected = await selectComponents(
+ logger,
+ item,
+ components,
+ options,
+ interactive,
+ getPrompter,
+ );
+ if (selected === undefined) return false;
const addresses = selected.map((component) => operations.itemAddress(component.item));
const manifests = await getRegistryItems(addresses, { config });
- if (manifests.length !== selected.length) {
+ if (manifests.length !== selected.length)
throw new Error(`Registry package "${item}" could not resolve all selected components.`);
- }
const entries = manifests.map((manifest) => {
const metadata = operations.metadata(manifest);
operations.assertCompatibleVersion(metadata?.requires);
return metadata;
});
-
- if (options.skipInstall !== true) {
+ if (options.skipInstall !== true)
await addRegistryItems(addresses, {
config,
cwd: appRoot,
overwrite: options.overwrite,
silent: options.silent,
});
- }
let completion: RegistrySetupCompletion = { facts: [] };
if (options.skipSetup === true) return completion;
-
- if (options.yes !== true && options.prompter === undefined && !interactive) {
+ if (!options.nonInteractive && options.yes !== true && options.prompter === undefined && !interactive) {
logger.log(operations.setupReminder(item));
return completion;
}
-
for (const metadata of entries) {
if (metadata?.setup === undefined) continue;
const result = await operations.runSetups({
diff --git a/packages/eve/src/cli/commands/registry-search-presentation.ts b/packages/eve/src/cli/commands/registry-search-presentation.ts
new file mode 100644
index 000000000..3dc14593b
--- /dev/null
+++ b/packages/eve/src/cli/commands/registry-search-presentation.ts
@@ -0,0 +1,83 @@
+import type { RegistrySearchItem } from "#compiled/shadcn-registry/index.js";
+import { createCliTheme, sanitizeForTerminal } from "#cli/ui/output.js";
+import { clipVisible, wrapVisibleLine } from "#cli/ui/terminal-text.js";
+
+export function normalizeRegistryText(value: string): string {
+ return sanitizeForTerminal(value)
+ .replaceAll('\\"', '"')
+ .replaceAll("\\'", "'")
+ .replaceAll(/\s+/gu, " ")
+ .trim();
+}
+
+function registryDescriptionSummary(description: string): string {
+ const normalized = normalizeRegistryText(description);
+ return normalized.match(/^.*?[.!?](?=\s|$)/u)?.[0] ?? normalized;
+}
+
+function renderSearchItem(
+ item: RegistrySearchItem,
+ address: string,
+ width: number,
+ theme: ReturnType<typeof createCliTheme>,
+): string {
+ const valueWidth = Math.max(1, width - 4);
+ const addressLines = wrapVisibleLine(normalizeRegistryText(address), valueWidth);
+ const name = normalizeRegistryText(item.name);
+ const title = name.split("/").at(-1) ?? name;
+ const lines = [` ${theme.label(title)}`, ...addressLines.map((line) => ` ${line}`)];
+ if (!item.description) return lines.join("\n");
+
+ const description = registryDescriptionSummary(item.description);
+ if (description.length === 0) return lines.join("\n");
+
+ const wrapped = wrapVisibleLine(description, valueWidth);
+ const descriptionLines =
+ wrapped.length <= 2
+ ? wrapped
+ : [wrapped[0]!, `${clipVisible(wrapped[1]!, Math.max(1, valueWidth - 1)).trimEnd()}…`];
+ lines.push(...descriptionLines.map((line) => theme.muted(` ${line}`)));
+ return lines.join("\n");
+}
+
+export function printRegistrySearchResults(
+ logger: { log(message: string): void },
+ result: { items: RegistrySearchItem[] },
+ options: {
+ json?: boolean;
+ query: string | undefined;
+ sections: readonly {
+ label: string;
+ items: RegistrySearchItem[];
+ total: number;
+ address(item: RegistrySearchItem): string;
+ }[];
+ },
+): void {
+ if (options.json) {
+ logger.log(JSON.stringify(result, null, 2));
+ return;
+ }
+ if (result.items.length === 0) {
+ const query = options.query && normalizeRegistryText(options.query);
+ logger.log(query ? `No registry items match "${query}".` : "No registry items found.");
+ return;
+ }
+
+ const theme = createCliTheme();
+ const width = Math.max(20, process.stdout.columns ?? 80);
+ const sections = options.sections.flatMap((section) => {
+ if (section.items.length === 0) return [];
+ const count = `${section.total} result${section.total === 1 ? "" : "s"}`;
+ const detail =
+ section.items.length < section.total ? `showing ${section.items.length} of ${count}` : count;
+ const heading = `${theme.label(section.label)} ${theme.muted(`(${detail})`)}`;
+ return [
+ [
+ heading,
+ ...section.items.map((item) => renderSearchItem(item, section.address(item), width, theme)),
+ ].join("\n"),
+ ];
+ });
+ logger.log(sections.join("\n"));
+}
diff --git a/packages/eve/src/cli/commands/registry-setup-command.test.ts b/packages/eve/src/cli/commands/registry-setup-command.test.ts
index 3117987e6..319a3c05c 100644
--- a/packages/eve/src/cli/commands/registry-setup-command.test.ts
+++ b/packages/eve/src/cli/commands/registry-setup-command.test.ts
@@ -86,7 +86,7 @@ describe("runRegistrySetupCommand", () => {
env: expect.objectContaining({
EVE_SETUP: "1",
EVE_SETUP_ITEM: "channel/slack",
- EVE_SETUP_PROTOCOL: "1",
+ EVE_SETUP_PROTOCOL: "2",
}),
stdio: ["ignore", "pipe", "pipe", "ipc"],
}),
@@ -298,6 +298,35 @@ describe("runRegistrySetupCommand", () => {
).rejects.toThrow("exited with code 0 before reporting a result");
});
+ it("returns a structured setup blocker from the child", async () => {
+ spawn.mockReturnValue(
+ protocolChild(0, null, (child) =>
+ child.emit("message", {
+ type: "result",
+ outcome: {
+ kind: "blocked",
+ blocker: {
+ status: "input_required",
+ question: { key: "mode", kind: "confirm", message: "Mode?", required: true },
+ },
+ },
+ }),
+ ),
+ );
+
+ await expect(
+ runRegistrySetupCommand(
+ "/project",
+ { package: "@acme/slack", bin: "acme-slack", args: [] },
+ "channel/slack",
+ options(),
+ ),
+ ).resolves.toMatchObject({
+ kind: "blocked",
+ blocker: { status: "input_required", question: { key: "mode" } },
+ });
+ });
+
it("rejects a binary the installed package does not declare", async () => {
await expect(
runRegistrySetupCommand(
diff --git a/packages/eve/src/cli/commands/registry-setup-command.ts b/packages/eve/src/cli/commands/registry-setup-command.ts
index 07a53cb2e..c2fac721f 100644
--- a/packages/eve/src/cli/commands/registry-setup-command.ts
+++ b/packages/eve/src/cli/commands/registry-setup-command.ts
@@ -13,6 +13,7 @@ import {
type RegistrySetupChildMessage,
type RegistrySetupCompletion,
type RegistrySetupParentMessage,
+ type RegistrySetupBlocker,
} from "#setup/registry-setup-protocol.js";
import { WizardCancelledError } from "#setup/step.js";
@@ -24,6 +25,7 @@ export interface RegistrySetupCommand {
export type RegistrySetupCommandResult =
| ({ kind: "completed" } & RegistrySetupCompletion)
+ | { kind: "blocked"; blocker: RegistrySetupBlocker }
| { kind: "cancelled" };
export interface RegistrySetupCommandOptions {
@@ -295,6 +297,10 @@ export async function runRegistrySetupCommand(
resolveResult(result);
return;
}
+ if (outcome?.kind === "blocked") {
+ resolveResult({ kind: "blocked", blocker: outcome.blocker });
+ return;
+ }
if (outcome?.kind === "cancelled") {
resolveResult({ kind: "cancelled" });
return;
diff --git a/packages/eve/src/cli/commands/registry.test.ts b/packages/eve/src/cli/commands/registry.test.ts
index 37210b24d..3bb123eab 100644
--- a/packages/eve/src/cli/commands/registry.test.ts
+++ b/packages/eve/src/cli/commands/registry.test.ts
@@ -172,6 +172,71 @@ describe("registry commands", () => {
},
);
+ it("returns a structured component question before installing a package headlessly", async () => {
+ const logger = createLogger();
+ getRegistryItems.mockResolvedValueOnce([
+ {
+ meta: {
+ eve: {
+ components: [
+ { item: "channel/linear-agent", label: "Linear Channel", default: true },
+ { item: "connection/linear", label: "Linear MCP", default: true },
+ ],
+ },
+ },
+ },
+ ]);
+
+ await runAddCommand(
+ logger,
+ "/project",
+ "linear",
+ { nonInteractive: true },
+ { loadSetupCommandRunner: vi.fn() },
+ );
+
+ expect(addRegistryItems).not.toHaveBeenCalled();
+ expect(JSON.parse(logger.errors[0]!)).toMatchObject({
+ status: "input_required",
+ item: "linear",
+ installed: false,
+ question: { key: "components" },
+ next: { command: "eve", args: ["add", "linear", "--non-interactive"] },
+ });
+ expect(process.exitCode).toBe(2);
+ });
+
+ it("uses an answered component selection headlessly", async () => {
+ const logger = createLogger();
+ getRegistryItems
+ .mockResolvedValueOnce([
+ {
+ meta: {
+ eve: {
+ components: [
+ { item: "channel/linear-agent", label: "Linear Channel", default: true },
+ { item: "connection/linear", label: "Linear MCP", default: true },
+ ],
+ },
+ },
+ },
+ ])
+ .mockResolvedValueOnce([{ meta: { eve: {} } }]);
+
+ await runAddCommand(
+ logger,
+ "/project",
+ "linear",
+ { nonInteractive: true, answers: { components: ["channel/linear-agent"] } },
+ { loadSetupCommandRunner: vi.fn() },
+ );
+
+ expect(addRegistryItems).toHaveBeenCalledWith(
+ ["https://eve.dev/r/channel/linear-agent.json"],
+ expect.objectContaining({ cwd: "/project" }),
+ );
+ });
+
it("lets interactive users select components from an official registry package", async () => {
const logger = createLogger();
const runSetupCommand = vi.fn(async () => ({ kind: "completed" as const, facts: [] }));
@@ -179,7 +244,6 @@ describe("registry commands", () => {
multiple: (options) => {
expect(options).toMatchObject({
message: "Add linear",
- description: "Select what you want to add to your agent.",
initialValues: ["channel/linear-agent", "connection/linear"],
});
return ["connection/linear"];
diff --git a/packages/eve/src/cli/commands/registry.ts b/packages/eve/src/cli/commands/registry.ts
index 1a6403c62..f2f477cf0 100644
--- a/packages/eve/src/cli/commands/registry.ts
+++ b/packages/eve/src/cli/commands/registry.ts
@@ -5,8 +5,6 @@ import {
type RegistryConfig,
type RegistrySearchItem,
} from "#compiled/shadcn-registry/index.js";
-import { createCliTheme, sanitizeForTerminal } from "#cli/ui/output.js";
-import { clipVisible, wrapVisibleLine } from "#cli/ui/terminal-text.js";
import semver from "#compiled/semver/index.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
import { createPrompter, type Prompter } from "#setup/prompter.js";
@@ -18,7 +16,9 @@ import { hasInteractiveTerminal, NOT_AN_AGENT_MESSAGE } from "./preconditions.js
import { runDeclaredSetups } from "./registry-declared-setups.js";
import { eveMetadataFromRegistryItem } from "./registry-metadata.js";
import { runRegistryPackage } from "./registry-package.js";
+import { printRegistrySearchResults } from "./registry-search-presentation.js";
import type { runRegistrySetupCommand } from "./registry-setup-command.js";
+import { serializeHeadlessSetupEvent } from "./setup-headless.js";
import { addRegistryMappings, readRegistryConfig } from "./registry-project.js";
export interface RegistryCommandLogger {
@@ -31,6 +31,8 @@ export interface AddCommandOptions {
overwrite?: boolean;
skipSetup?: boolean;
yes?: boolean;
+ nonInteractive?: boolean;
+ answers?: Record<string, unknown>;
/** Suppresses the registry SDK's terminal-native progress output. */
silent?: boolean;
}
@@ -220,54 +222,6 @@ function validateRegistrySource(source: string | undefined): void {
}
}
-function normalizeRegistryText(value: string): string {
- return sanitizeForTerminal(value)
- .replaceAll('\\"', '"')
- .replaceAll("\\'", "'")
- .replaceAll(/\s+/gu, " ")
- .trim();
-}
-
-function registryDescriptionSummary(description: string): string {
- const normalized = normalizeRegistryText(description);
- return normalized.match(/^.*?[.!?](?=\s|$)/u)?.[0] ?? normalized;
-}
-
-function searchItemAddress(item: RegistrySearchItem): string {
- const address = item.registry === OFFICIAL_CATALOG ? item.name : item.addCommandArgument;
- return normalizeRegistryText(address);
-}
-
-function searchItemFallbackTitle(item: RegistrySearchItem): string {
- const name = normalizeRegistryText(item.name);
- return name.split("/").at(-1) ?? name;
-}
-
-function renderSearchItem(
- item: RegistrySearchItem,
- width: number,
- theme: ReturnType<typeof createCliTheme>,
-): string {
- const valueWidth = Math.max(1, width - 4);
- const addressLines = wrapVisibleLine(searchItemAddress(item), valueWidth);
- const lines = [
- ` ${theme.label(searchItemFallbackTitle(item))}`,
- ...addressLines.map((line) => ` ${line}`),
- ];
- if (!item.description) return lines.join("\n");
-
- const description = registryDescriptionSummary(item.description);
- if (description.length === 0) return lines.join("\n");
-
- const wrapped = wrapVisibleLine(description, valueWidth);
- const descriptionLines =
- wrapped.length <= 2
- ? wrapped
- : [wrapped[0]!, `${clipVisible(wrapped[1]!, Math.max(1, valueWidth - 1)).trimEnd()}…`];
- lines.push(...descriptionLines.map((line) => theme.muted(` ${line}`)));
- return lines.join("\n");
-}
-
type RegistrySearchResult = Awaited<ReturnType<typeof searchRegistries>>;
function registrySourceLabel(source: string): string {
@@ -276,45 +230,8 @@ function registrySourceLabel(source: string): string {
return source;
}
-function printSearchResults(
- logger: RegistryCommandLogger,
- result: RegistrySearchResult,
- options: {
- json?: boolean;
- query: string | undefined;
- resultsBySource: ReadonlyMap<string, RegistrySearchResult>;
- sources: string[];
- },
-): void {
- if (options.json) {
- logger.log(JSON.stringify(result, null, 2));
- return;
- }
- if (result.items.length === 0) {
- const query = options.query && normalizeRegistryText(options.query);
- logger.log(query ? `No registry items match "${query}".` : "No registry items found.");
- return;
- }
-
- const theme = createCliTheme();
- const width = Math.max(20, process.stdout.columns ?? 80);
- const sections = options.sources.flatMap((source) => {
- const sourceResult = options.resultsBySource.get(source);
- if (sourceResult === undefined || sourceResult.items.length === 0) return [];
- const { pagination } = sourceResult;
- const count = `${pagination.total} result${pagination.total === 1 ? "" : "s"}`;
- const detail =
- sourceResult.items.length < pagination.total
- ? `showing ${sourceResult.items.length} of ${count}`
- : count;
- const heading = `${theme.label(registrySourceLabel(source))} ${theme.muted(`(${detail})`)}`;
- return [
- [heading, ...sourceResult.items.map((item) => renderSearchItem(item, width, theme))].join(
- "\n",
- ),
- ];
- });
- logger.log(sections.join("\n"));
+function searchItemAddress(item: RegistrySearchItem): string {
+ return item.registry === OFFICIAL_CATALOG ? item.name : item.addCommandArgument;
}
async function searchRegistryCatalog(
@@ -437,7 +354,20 @@ async function browseRegistryItems(
});
const errors = result.errors ?? [];
if (options.json || resultsBySource.size > 0) {
- printSearchResults(logger, result, { ...options, query, resultsBySource, sources });
+ const sections = sources.flatMap((source) => {
+ const sourceResult = resultsBySource.get(source);
+ return sourceResult === undefined
+ ? []
+ : [
+ {
+ label: registrySourceLabel(source),
+ items: sourceResult.items,
+ total: sourceResult.pagination.total,
+ address: searchItemAddress,
+ },
+ ];
+ });
+ printRegistrySearchResults(logger, result, { ...options, query, sections });
}
for (const error of errors) {
logger.error(`${error.registry}: ${error.message}`);
@@ -537,7 +467,13 @@ export async function runAddCommand(
appRoot,
item: packageItem,
setups,
- options: { yes: options.yes, prompter, signal: options.signal },
+ options: {
+ yes: options.yes,
+ nonInteractive: options.nonInteractive,
+ answers: options.answers,
+ prompter,
+ signal: options.signal,
+ },
dependencies,
cancelledReminder: setupReminder(packageItem, "cancelled"),
resumeCommand: setupResumeCommand(packageItem),
@@ -576,15 +512,24 @@ export async function runAddCommand(
const interactive =
dependencies.hasInteractiveTerminal?.() ??
defaultAddCommandDependencies.hasInteractiveTerminal!();
+ if (options.nonInteractive) {
+ logger.log(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "progress",
+ message: options.skipInstall ? `Setup ${item}` : `Installed ${item}`,
+ }),
+ );
+ }
if (
options.skipSetup === true ||
- (!options.yes && !interactive && options.setupAuthorized !== true)
+ (!options.nonInteractive && !options.yes && !interactive && options.setupAuthorized !== true)
) {
logger.log(setupReminder(item, "skipped"));
return;
}
- if (!options.yes && options.setupAuthorized !== true) {
+ if (!options.nonInteractive && !options.yes && options.setupAuthorized !== true) {
try {
const prompter =
options.prompter ??
@@ -619,6 +564,16 @@ export async function runAddCommand(
cancelledReminder: setupReminder(item, "cancelled"),
resumeCommand: setupResumeCommand(item),
});
+ if (completion !== false && options.nonInteractive) {
+ logger.log(
+ serializeHeadlessSetupEvent({
+ version: 1,
+ type: "completed",
+ item,
+ completedItems: [item],
+ }),
+ );
+ }
return completion === false ? undefined : completion;
});
}
diff --git a/packages/eve/src/cli/commands/setup-answers.test.ts b/packages/eve/src/cli/commands/setup-answers.test.ts
new file mode 100644
index 000000000..6dda8dfdd
--- /dev/null
+++ b/packages/eve/src/cli/commands/setup-answers.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+
+import { parseSetupAnswer } from "./setup-answers.js";
+import { headlessSetupContinuation } from "./setup-headless.js";
+
+describe("setup answers", () => {
+ it("accumulates JSON values", () => {
+ const first = parseSetupAnswer('mode="portable"');
+ const answers = parseSetupAnswer('events=["issues","pull_request"]', first);
+
+ expect(answers).toEqual({ mode: "portable", events: ["issues", "pull_request"] });
+ });
+
+ it("rejects unquoted string values", () => {
+ expect(() => parseSetupAnswer("mode=portable")).toThrow("must be JSON");
+ });
+
+ it("builds a minimal resume command", () => {
+ expect(headlessSetupContinuation({ item: "channel/github", installed: true })).toEqual({
+ command: "eve",
+ args: ["add", "channel/github", "--non-interactive", "--skip-install"],
+ });
+ });
+});
diff --git a/packages/eve/src/cli/commands/setup-answers.ts b/packages/eve/src/cli/commands/setup-answers.ts
new file mode 100644
index 000000000..e2a6720e4
--- /dev/null
+++ b/packages/eve/src/cli/commands/setup-answers.ts
@@ -0,0 +1,22 @@
+import { InvalidArgumentError } from "#compiled/commander/index.js";
+
+/** Parses one repeatable `--answer key=<JSON value>`. */
+export function parseSetupAnswer(
+ value: string,
+ previous: Record<string, unknown> = {},
+): Record<string, unknown> {
+ const separator = value.indexOf("=");
+ if (separator < 1) throw new InvalidArgumentError('Expected "key=value".');
+ const key = value.slice(0, separator).trim();
+ const raw = value.slice(separator + 1);
+ if (key.length === 0) throw new InvalidArgumentError("Setup answer key cannot be empty.");
+ let answer: unknown;
+ try {
+ answer = JSON.parse(raw);
+ } catch {
+ throw new InvalidArgumentError(
+ `Setup answer for "${key}" must be JSON; quote string values, for example '${key}="value"'.`,
+ );
+ }
+ return { ...previous, [key]: answer };
+}
diff --git a/packages/eve/src/cli/commands/setup-headless.ts b/packages/eve/src/cli/commands/setup-headless.ts
new file mode 100644
index 000000000..75c1f3291
--- /dev/null
+++ b/packages/eve/src/cli/commands/setup-headless.ts
@@ -0,0 +1,74 @@
+import type { RegistrySetupBlocker } from "#setup/registry-setup-protocol.js";
+
+export interface HeadlessSetupCommand {
+ command: string;
+ args: readonly string[];
+}
+
+export type HeadlessSetupEvent =
+ | { version: 1; type: "progress"; level?: "warning"; message: string }
+ | {
+ version: 1;
+ type: "external_action";
+ id: string;
+ blocking: true;
+ message: string;
+ url: string;
+ userCode?: string;
+ }
+ | { version: 1; type: "external_action_resolved"; id: string }
+ | { version: 1; type: "completed"; item: string; completedItems: readonly string[] }
+ | ({
+ version: 1;
+ type: "blocked";
+ item: string;
+ installed: boolean;
+ completedItems: readonly string[];
+ next: HeadlessSetupCommand;
+ } & RegistrySetupBlocker)
+ | {
+ version: 1;
+ type: "failed";
+ item: string;
+ completedItems: readonly string[];
+ message: string;
+ next?: HeadlessSetupCommand;
+ }
+ | {
+ version: 1;
+ type: "cancelled";
+ item: string;
+ completedItems: readonly string[];
+ next?: HeadlessSetupCommand;
+ };
+
+export function headlessSetupContinuation(input: {
+ item: string;
+ installed: boolean;
+}): HeadlessSetupCommand {
+ return {
+ command: "eve",
+ args: ["add", input.item, "--non-interactive", ...(input.installed ? ["--skip-install"] : [])],
+ };
+}
+
+export type HeadlessIntegrationSetupEvent =
+ | {
+ version: 1;
+ type: "external_action";
+ id: string;
+ blocking: true;
+ message: string;
+ url: string;
+ userCode?: string;
+ }
+ | { version: 1; type: "external_action_resolved"; id: string }
+ | { version: 1; type: "completed"; item: string }
+ | { version: 1; type: "cancelled"; item: string }
+ | ({ version: 1; type: "blocked" } & RegistrySetupBlocker);
+
+export function serializeHeadlessSetupEvent(
+ event: HeadlessSetupEvent | HeadlessIntegrationSetupEvent,
+): string {
+ return JSON.stringify(event);
+}
diff --git a/packages/eve/src/setup/integrations/photon/setup-flow.ts b/packages/eve/src/setup/integrations/photon/setup-flow.ts
index 1c6564309..e2652a01e 100644
--- a/packages/eve/src/setup/integrations/photon/setup-flow.ts
+++ b/packages/eve/src/setup/integrations/photon/setup-flow.ts
@@ -196,13 +196,16 @@ async function resolvePhotonProject(
kind: "external-action",
emphasis: "browser",
});
+ let authorizationAction:
+ | ReturnType<SetupApplyContext["presenter"]["beginExternalAction"]>
+ | undefined;
try {
- return await deps.provisionProject({
+ const project = await deps.provisionProject({
projectName: plan.photonProjectName ?? `eve · ${plan.agentName || "agent"}`,
phoneNumber: plan.phoneNumber,
signal: context.signal,
onAuthorization(authorization) {
- context.presenter.beginExternalAction({
+ authorizationAction = context.presenter.beginExternalAction({
message: "Authorize Photon",
url: authorization.verificationUrl,
userCode: authorization.userCode,
@@ -210,6 +213,8 @@ async function resolvePhotonProject(
deps.openUrl(authorization.verificationUrl);
},
});
+ authorizationAction?.complete();
+ return project;
} finally {
spinner?.stop();
}
diff --git a/packages/eve/src/setup/integrations/runner.ts b/packages/eve/src/setup/integrations/runner.ts
index 7b30710e4..9ecc97ced 100644
--- a/packages/eve/src/setup/integrations/runner.ts
+++ b/packages/eve/src/setup/integrations/runner.ts
@@ -14,7 +14,7 @@ import {
import { resolveIntegrationVercelProject } from "./shared/vercel-project.js";
import { createSetupContexts } from "./shared/ui.js";
import { setupIntegration } from "./registry.js";
-import type { IntegrationSetupResult } from "./types.js";
+import type { IntegrationSetupResult, SetupExternalAction } from "./types.js";
/** Inputs shared by every registry-owned integration setup flow. */
export interface RunIntegrationSetupOptions {
@@ -24,7 +24,11 @@ export interface RunIntegrationSetupOptions {
asker?: Asker;
signal?: AbortSignal;
force?: boolean;
- beginExternalAction?: (input: { url: string; userCode?: string; message: string }) => void;
+ beginExternalAction?: (input: {
+ url: string;
+ userCode?: string;
+ message: string;
+ }) => SetupExternalAction;
resolveVercelProject?: SetupProjectResolver;
}
diff --git a/packages/eve/src/setup/integrations/shared/prerequisite.ts b/packages/eve/src/setup/integrations/shared/prerequisite.ts
index 696326cc1..4fc9abe46 100644
--- a/packages/eve/src/setup/integrations/shared/prerequisite.ts
+++ b/packages/eve/src/setup/integrations/shared/prerequisite.ts
@@ -2,7 +2,7 @@ export type SetupPrerequisite =
| { kind: "command"; code: string; message: string; command: string }
| { kind: "environment"; code: string; message: string; variable: string; sensitive: true };
-/** A read-only setup refusal whose prerequisite must be satisfied by the caller. */
+/** A setup blocker whose prerequisite must be satisfied by the caller. */
export class SetupPrerequisiteRequired extends Error {
readonly prerequisite: SetupPrerequisite;
diff --git a/packages/eve/src/setup/integrations/shared/ui.ts b/packages/eve/src/setup/integrations/shared/ui.ts
index 108a65d4d..745bca10a 100644
--- a/packages/eve/src/setup/integrations/shared/ui.ts
+++ b/packages/eve/src/setup/integrations/shared/ui.ts
@@ -1,10 +1,19 @@
import type { Asker } from "../../ask.js";
import type { Prompter } from "../../prompter.js";
-import type { SetupApplyContext, SetupPrepareContext, SetupPresenter } from "../types.js";
+import type {
+ SetupApplyContext,
+ SetupExternalAction,
+ SetupPrepareContext,
+ SetupPresenter,
+} from "../types.js";
export function createSetupPresenter(
prompter: Prompter,
- beginExternalAction?: (input: { url: string; userCode?: string; message: string }) => void,
+ beginExternalAction?: (input: {
+ url: string;
+ userCode?: string;
+ message: string;
+ }) => SetupExternalAction,
): SetupPresenter {
return {
log: prompter.log,
@@ -13,13 +22,11 @@ export function createSetupPresenter(
if (lines.length > 0) prompter.note(lines.join("\n"), "Next steps", { tone: "success" });
},
beginExternalAction(input) {
- if (beginExternalAction !== undefined) {
- beginExternalAction(input);
- return;
- }
+ if (beginExternalAction !== undefined) return beginExternalAction(input);
prompter.log.message(input.message);
prompter.log.message(input.url);
if (input.userCode !== undefined) prompter.log.message(`Code: ${input.userCode}`);
+ return { complete() {} };
},
};
}
@@ -32,7 +39,11 @@ export function createSetupContexts(input: {
resolveVercelProject: SetupPrepareContext["resolveVercelProject"];
signal?: AbortSignal;
force?: boolean;
- beginExternalAction?: (input: { url: string; userCode?: string; message: string }) => void;
+ beginExternalAction?: (input: {
+ url: string;
+ userCode?: string;
+ message: string;
+ }) => SetupExternalAction;
}): { prepare: SetupPrepareContext; apply: SetupApplyContext } {
const presenter = createSetupPresenter(input.prompter, input.beginExternalAction);
const apply: SetupApplyContext = { appRoot: input.appRoot, presenter };
diff --git a/packages/eve/src/setup/integrations/types.ts b/packages/eve/src/setup/integrations/types.ts
index d5331e188..04a7ce66f 100644
--- a/packages/eve/src/setup/integrations/types.ts
+++ b/packages/eve/src/setup/integrations/types.ts
@@ -6,9 +6,17 @@ import { WizardCancelledError } from "#setup/step.js";
import type { IntegrationSetupEnvironment } from "./shared/environment.js";
+export interface SetupExternalAction {
+ complete(): void;
+}
+
export type SetupPresenter = Pick<Prompter, "log" | "note"> & {
nextSteps(lines: readonly string[]): void;
- beginExternalAction(input: { url: string; userCode?: string; message: string }): void;
+ beginExternalAction(input: {
+ url: string;
+ userCode?: string;
+ message: string;
+ }): SetupExternalAction;
};
export interface SetupPrepareContext {
diff --git a/packages/eve/src/setup/registry-setup-client.test.ts b/packages/eve/src/setup/registry-setup-client.test.ts
index 471501b9c..bee215854 100644
--- a/packages/eve/src/setup/registry-setup-client.test.ts
+++ b/packages/eve/src/setup/registry-setup-client.test.ts
@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
import { afterEach, describe, expect, it, vi } from "vitest";
+import { InteractionRequired, select } from "./ask.js";
import { createRegistrySetupClient, type RegistrySetupClient } from "./registry-setup-client.js";
import type { RegistrySetupChildMessage } from "./registry-setup-protocol.js";
@@ -51,6 +52,25 @@ describe("createRegistrySetupClient", () => {
expect(processStub.listenerCount("message")).toBe(0);
});
+ it("reports expected setup blockers separately from failures", () => {
+ const processStub = new SetupProcessStub();
+ const setup = client(processStub);
+
+ setup.fail(
+ new InteractionRequired(
+ select({ key: "mode", message: "Mode?", options: [], required: true }),
+ ),
+ );
+
+ expect(processStub.sent.at(-1)).toMatchObject({
+ type: "result",
+ outcome: {
+ kind: "blocked",
+ blocker: { status: "input_required", question: { key: "mode" } },
+ },
+ });
+ });
+
it("reports only the first terminal outcome", () => {
const processStub = new SetupProcessStub();
const setup = client(processStub);
diff --git a/packages/eve/src/setup/registry-setup-client.ts b/packages/eve/src/setup/registry-setup-client.ts
index c06c3b6a8..d14d57755 100644
--- a/packages/eve/src/setup/registry-setup-client.ts
+++ b/packages/eve/src/setup/registry-setup-client.ts
@@ -1,3 +1,5 @@
+import { InteractionRequired, InvalidAnswerError } from "./ask.js";
+import { SetupPrerequisiteRequired } from "./integrations/shared/prerequisite.js";
import type {
EditableSelectOptions,
MultiSelectOptions,
@@ -6,6 +8,7 @@ import type {
SelectNotice,
SingleSelectOptions,
} from "./prompter.js";
+import { setupQuestionToWire } from "./setup-question-wire.js";
import { WizardCancelledError } from "./step.js";
import {
REGISTRY_SETUP_PROTOCOL_VERSION,
@@ -16,7 +19,7 @@ import {
type RegistrySetupPrompt,
} from "./registry-setup-protocol.js";
-interface SetupProcess {
+export interface SetupProcess {
connected?: boolean;
send?: (message: RegistrySetupChildMessage) => boolean;
disconnect?: () => void;
@@ -31,6 +34,25 @@ function send(process: SetupProcess, message: RegistrySetupChildMessage): void {
process.send(message);
}
+function registrySetupBlocker(
+ error: unknown,
+): import("./registry-setup-protocol.js").RegistrySetupBlocker | undefined {
+ if (error instanceof InteractionRequired) {
+ return { status: "input_required", question: setupQuestionToWire(error.question) };
+ }
+ if (error instanceof InvalidAnswerError) {
+ return {
+ status: "input_required",
+ question: setupQuestionToWire(error.question),
+ issue: { code: "invalid_answer", message: error.message },
+ };
+ }
+ if (error instanceof SetupPrerequisiteRequired) {
+ return { status: "prerequisite_required", prerequisite: error.prerequisite };
+ }
+ return undefined;
+}
+
function registrySetupError(error: unknown): { message: string; details?: readonly string[] } {
if (!(error instanceof Error)) return { message: String(error) };
const details = error.stack
@@ -214,6 +236,13 @@ export function createRegistrySetupClient(
signal: controller.signal,
complete: (completion = { facts: [] }) => finish({ kind: "completed", ...completion }),
cancel: () => finish({ kind: "cancelled" }),
- fail: (error) => finish({ kind: "failed", error: registrySetupError(error) }),
+ fail(error) {
+ const blocker = registrySetupBlocker(error);
+ finish(
+ blocker === undefined
+ ? { kind: "failed", error: registrySetupError(error) }
+ : { kind: "blocked", blocker },
+ );
+ },
};
}
diff --git a/packages/eve/src/setup/registry-setup-protocol.ts b/packages/eve/src/setup/registry-setup-protocol.ts
index b4a046ad8..f8f7b7367 100644
--- a/packages/eve/src/setup/registry-setup-protocol.ts
+++ b/packages/eve/src/setup/registry-setup-protocol.ts
@@ -7,27 +7,30 @@ import type {
SelectOption,
SingleSelectOptions,
} from "./prompter.js";
+import type { SetupPrerequisite } from "./integrations/shared/prerequisite.js";
+import type { SetupWireQuestion } from "./setup-question-wire.js";
-export const REGISTRY_SETUP_PROTOCOL_VERSION = 1;
-
-export type RegistrySetupFact = {
- label: string;
- value: string;
- kind?: "text" | "url" | "phone";
-};
+export const REGISTRY_SETUP_PROTOCOL_VERSION = 2;
+export type RegistrySetupFact = { label: string; value: string; kind?: "text" | "url" | "phone" };
export type RegistrySetupCompletion = {
facts: readonly RegistrySetupFact[];
deploymentRequired?: true;
};
-
+export type RegistrySetupBlocker =
+ | {
+ status: "input_required";
+ question: SetupWireQuestion;
+ issue?: { code: "invalid_answer"; message: string };
+ }
+ | { status: "prerequisite_required"; prerequisite: SetupPrerequisite };
export type RegistrySetupError = {
message: string;
details?: readonly string[];
};
-
export type RegistrySetupOutcome =
| ({ kind: "completed" } & RegistrySetupCompletion)
+ | { kind: "blocked"; blocker: RegistrySetupBlocker }
| { kind: "cancelled" }
| { kind: "failed"; error: RegistrySetupError };
@@ -53,11 +56,7 @@ export type RegistrySetupPrompt =
| { kind: "acknowledge"; options: AcknowledgeOptions }
| {
kind: "choice";
- options: {
- status: string;
- context: string;
- actions: readonly SelectOption<string>[];
- };
+ options: { status: string; context: string; actions: readonly SelectOption<string>[] };
};
export type RegistrySetupChildMessage =
diff --git a/packages/eve/src/setup/state.ts b/packages/eve/src/setup/state.ts
index 6502c1f7a..9a7a5ed07 100644
--- a/packages/eve/src/setup/state.ts
+++ b/packages/eve/src/setup/state.ts
@@ -25,7 +25,7 @@ export type ResolvedProjectPath =
| { kind: "resolved"; inPlace: boolean; path: string };
/**
- * The `--headless` Vercel project flags. Read ONLY on the headless path (see
+ * The `--non-interactive` Vercel project flags. Read ONLY on the headless path (see
* {@link ProvisioningMode}): an interactive run prompts for these decisions
* instead, so the args never reach the prompt code.
*
@@ -42,7 +42,7 @@ export interface ArgsHeadlessProject {
}
/**
- * The `--headless` AI Gateway flags, read only on the headless path alongside
+ * The `--non-interactive` AI Gateway flags, read only on the headless path alongside
* {@link ArgsHeadlessProject}.
*/
export interface ArgsHeadlessAiGateway {