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.mdnew file mode 100644index 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.jsonindex 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.mdindex 675b54daa..796fb305d 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -98,7 +98,7 @@ eve registry view @acme/my-extensioneve 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.tsindex 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.tsindex 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-connimport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.jsimport { 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 {