@arizeai/phoenix-cli 1.9.0 → 1.10.0

package/build/setup/steps/establishConnection.js

@@ -5,8 +5,11 @@
  * first ingestion, so setup only needs to settle on a *name* and hand it
  * to the app via `PHOENIX_PROJECT_NAME`. What remains is credential
  * acquisition: the auth-on lanes verify the key with a read-only probe so a
- * bad paste is caught here rather than at first trace. Future OAuth
- * acquisition plugs into the auth-on interactive lane unchanged.
+ * bad paste is caught here rather than at first trace. When the instance runs
+ * the OAuth2 authorization server, the interactive lane offers a streamlined
+ * path first — log in with the browser, mint an API key over REST, revoke the
+ * grant that login created — and every failure along it falls back to the
+ * paste prompt rather than aborting setup.
  */
 import * as path from "node:path";
 import { HttpError } from "@arizeai/phoenix-client";
@@ -38,6 +41,18 @@ async function promptForProjectName(deps, inputs) {
         }));
     return name.trim();
 }
+/** A REST failure, as a short phrase to show the user. */
+function describeRestError(error) {
+    if (error instanceof HttpError) {
+        return `HTTP ${error.status}`;
+    }
+    // A 2xx whose body will not parse: something answered, but not the Phoenix
+    // API. The raw parser message would only confuse.
+    if (error instanceof SyntaxError) {
+        return COPY.ENDPOINT.unexpectedBody;
+    }
+    return redactForDisplay(String(error));
+}
 /**
  * Read-only probe: list one project. Only the credential matters here — an
  * instance with no projects yet still answers 200.
@@ -52,13 +67,11 @@ async function checkApiKey(deps, endpoint, apiKey) {
         return { kind: "ok" };
     }
     catch (error) {
-        if (error instanceof HttpError) {
-            if (error.status === 401 || error.status === 403) {
-                return { kind: "rejected", status: error.status };
-            }
-            return { kind: "error", detail: `HTTP ${error.status}` };
+        if (error instanceof HttpError &&
+            (error.status === 401 || error.status === 403)) {
+            return { kind: "rejected", status: error.status };
         }
-        return { kind: "error", detail: redactForDisplay(String(error)) };
+        return { kind: "error", detail: describeRestError(error) };
     }
 }
 // ---------------------------------------------------------------------------
@@ -78,13 +91,109 @@ async function promptForApiKey(deps) {
     return apiKey.trim();
 }
 /**
- * A rejected key returns to the masked credential prompt without asking for
- * the project name again.
+ * Log in via the browser, then mint a personal API key over REST. Every
+ * failure returns `undefined` after narrating why, sending the lane to the
+ * paste prompt — the login is a shortcut, never a wall.
+ */
+async function acquireApiKeyViaLogin(deps, endpoint, projectName) {
+    // Ctrl-C here means "give up on the browser", not "abandon setup" — the
+    // paste prompt below is still a way forward, and the project name the user
+    // already gave is still good.
+    const outcome = await deps.prompter.runInterruptible((signal) => deps.oauthLogin.login({
+        endpoint,
+        onAuthorizationUrl: (url) => deps.prompter.note(COPY.CREDENTIALS.authorizationUrl(url)),
+        onBrowserOpenFailed: (detail) => deps.prompter.line(COPY.CREDENTIALS.browserOpenFailed(redactForDisplay(detail))),
+        signal,
+    }));
+    if (outcome.status === "cancelled") {
+        deps.prompter.line(COPY.CREDENTIALS.loginCancelled);
+        return undefined;
+    }
+    if (outcome.status === "error") {
+        deps.prompter.line(COPY.CREDENTIALS.loginFailed(redactForDisplay(outcome.detail)));
+        return undefined;
+    }
+    try {
+        const client = deps.createClient({
+            endpoint,
+            apiKey: outcome.accessToken,
+        });
+        const name = `px-setup ${projectName}`;
+        const response = await client.POST("/v1/user/api_keys", {
+            body: {
+                data: {
+                    name,
+                    description: `Created by px setup for project "${projectName}".`,
+                },
+            },
+            signal: AbortSignal.timeout(REST_TIMEOUT_MS),
+        });
+        const key = response.data?.data.key;
+        if (!key) {
+            deps.prompter.line(COPY.CREDENTIALS.keyCreateFailed("empty key in response"));
+            return undefined;
+        }
+        deps.prompter.line(COPY.CREDENTIALS.keyCreated(name));
+        return key;
+    }
+    catch (error) {
+        deps.prompter.line(COPY.CREDENTIALS.keyCreateFailed(describeRestError(error)));
+        return undefined;
+    }
+    finally {
+        // The access token has served its one purpose. Ending the grant leaves the
+        // key in local files as the only credential this run created — without it,
+        // a refresh token setup no longer holds stays live for its full lifetime
+        // (a week by default). This does not touch an existing `px auth login`.
+        await outcome.revoke().catch(() => { });
+    }
+}
+/**
+ * The project name comes first so the browser-login path can stamp it into
+ * the minted key's name. A rejected key returns to the masked credential
+ * prompt without asking for the project name again.
  */
 async function connectAuthOnInteractive(deps, endpoint, inputs) {
+    // Start the probe before the prompt so it can run while the user types (when
+    // --project is given there is no prompt, and this is simply awaited below).
+    // The `catch` is not redundant: the contract returns Promise<boolean>, and an
+    // implementation that rejected would otherwise go unhandled on the path where
+    // the prompt throws SetupCancelledError before the await below is reached.
+    const supportsLogin = deps.oauthLogin
+        .isSupported(endpoint)
+        .catch(() => false);
+    const projectName = await promptForProjectName(deps, inputs);
+    if (await supportsLogin) {
+        const method = await deps.prompter.select({
+            message: COPY.CREDENTIALS.methodMessage,
+            options: [
+                {
+                    value: "login",
+                    label: COPY.CREDENTIALS.loginLabel,
+                    hint: COPY.CREDENTIALS.loginHint,
+                },
+                {
+                    value: "paste",
+                    label: COPY.CREDENTIALS.pasteLabel,
+                    hint: COPY.CREDENTIALS.pasteHint,
+                },
+            ],
+        });
+        if (method === "login") {
+            const apiKey = await acquireApiKeyViaLogin(deps, endpoint, projectName);
+            if (apiKey !== undefined) {
+                // The key was just minted by an authenticated call to this same
+                // endpoint, so a probe could only re-prove what the mint proved. It
+                // could, however, fail transiently — and the ephemeral session is
+                // already revoked, so a throw here would strand a live key the user
+                // never received and cannot name.
+                deps.prompter.line(COPY.CONNECT.usingProject(projectName));
+                return { endpoint, projectName, apiKey };
+            }
+        }
+    }
     deps.prompter.note(COPY.API_KEY.instructions, COPY.API_KEY.instructionsTitle);
     let apiKey = await promptForApiKey(deps);
-    const projectName = await promptForProjectName(deps, inputs);
     for (;;) {
         const result = await checkApiKey(deps, endpoint, apiKey);
         if (result.kind === "ok") {

package/build/setup/steps/establishConnection.js.map

@@ -1 +1 @@
-{"version":3,"file":"establishConnection.js","sourceRoot":"","sources":["../../../src/setup/steps/establishConnection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"establishConnection.js","sourceRoot":"","sources":["../../../src/setup/steps/establishConnection.ts"],"names":[],"mappings":"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"}

package/build/setup/steps/instrumentApp.d.ts

@@ -7,13 +7,20 @@
  * lanes converge on the trace-verification step — setup's definition of
  * done is API-verified data flow, not agent self-report.
  *
+ * The lane is resolved before anything docs-related happens: the docs MCP
+ * offer targets exactly the agent being launched, and taking it replaces the
+ * `.px/docs` download outright — the agent searches the docs server on demand
+ * instead of reading prefetched pages. The clipboard and manual lanes have no
+ * known agent to configure, so they keep the prefetch.
+ *
  * `--agent` pre-answers the lane, which is what makes an unattended run
  * possible: with no TTY there is no prompt to pick a lane from, and the agent
  * runs in background mode (no TUI to hand the terminal to).
  */
 import { type AgentRunMode, type CodingAgent, type CodingAgentId } from "../agents/registry.js";
-import type { DocsPrefetchResult, SetupDeps } from "../deps/index.js";
+import type { DocsPrefetchOptions, DocsPrefetchResult, SetupDeps } from "../deps/index.js";
 import type { Connection } from "./establishConnection.js";
+import { type DocsMcpResult } from "./offerDocsMcp.js";
 export interface InstrumentAppArgs {
     authEnabled: boolean;
     /** Started at setup launch so the probes never block this prompt. */
@@ -24,8 +31,13 @@ export interface InstrumentAppArgs {
     languages: string[];
     /** How to run the agent — see {@link AgentRunMode}. */
     mode: AgentRunMode;
-    /** Where the prefetched docs landed, when the docs step ran. */
-    docs?: DocsPrefetchResult;
+    /** Docs prefetch options; the download runs unless the MCP replaces it. */
+    docs: DocsPrefetchOptions;
+    /** `--docs-mcp` / `--no-docs-mcp`; undefined means ask (when we can). */
+    docsMcp?: boolean;
+    headless: boolean;
+    /** Gates the prefetch's .gitignore append, as in the docs step itself. */
+    isGitRepository: boolean;
 }
 /** Which lane instrumentation actually took — reported in the summary. */
 export type InstrumentationLane = {
@@ -37,5 +49,12 @@ export type InstrumentationLane = {
 } | {
     kind: "manual";
 };
-export declare function instrumentApp(deps: Pick<SetupDeps, "context" | "processes" | "prompter" | "writeClipboard">, connection: Connection, args: InstrumentAppArgs): Promise<InstrumentationLane>;
+export interface InstrumentAppResult {
+    lane: InstrumentationLane;
+    /** The docs download, when it ran (the MCP taking its place omits it). */
+    docs?: DocsPrefetchResult;
+    /** The docs MCP offer, when a launched agent was there to make it to. */
+    docsMcp?: DocsMcpResult;
+}
+export declare function instrumentApp(deps: Pick<SetupDeps, "context" | "processes" | "prompter" | "writeClipboard" | "fetchDocs">, connection: Connection, args: InstrumentAppArgs): Promise<InstrumentAppResult>;
 //# sourceMappingURL=instrumentApp.d.ts.map

package/build/setup/steps/instrumentApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instrumentApp.d.ts","sourceRoot":"","sources":["../../../src/setup/steps/instrumentApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,kBAAkB,EAAgB,SAAS,EAAE,MAAM,SAAS,CAAC;AAG3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAQxD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,qEAAqE;IACrE,cAAc,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACvC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,yEAAyE;IACzE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uDAAuD;IACvD,IAAI,EAAE,YAAY,CAAC;IACnB,gEAAgE;IAChE,IAAI,CAAC,EAAE,kBAAkB,CAAC;CAC3B;AAED,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvB,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,CACR,SAAS,EACT,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,gBAAgB,CACxD,EACD,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAgG9B"}
+{"version":3,"file":"instrumentApp.d.ts","sourceRoot":"","sources":["../../../src/setup/steps/instrumentApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAElB,SAAS,EACV,MAAM,SAAS,CAAC;AAGjB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AASlE,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,qEAAqE;IACrE,cAAc,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACvC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,yEAAyE;IACzE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uDAAuD;IACvD,IAAI,EAAE,YAAY,CAAC;IACnB,2EAA2E;IAC3E,IAAI,EAAE,mBAAmB,CAAC;IAC1B,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvB,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,0EAA0E;IAC1E,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,yEAAyE;IACzE,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,CACR,SAAS,EACT,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,gBAAgB,GAAG,WAAW,CACtE,EACD,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAuI9B"}

package/build/setup/steps/instrumentApp.js

@@ -7,6 +7,12 @@
  * lanes converge on the trace-verification step — setup's definition of
  * done is API-verified data flow, not agent self-report.
  *
+ * The lane is resolved before anything docs-related happens: the docs MCP
+ * offer targets exactly the agent being launched, and taking it replaces the
+ * `.px/docs` download outright — the agent searches the docs server on demand
+ * instead of reading prefetched pages. The clipboard and manual lanes have no
+ * known agent to configure, so they keep the prefetch.
+ *
  * `--agent` pre-answers the lane, which is what makes an unattended run
  * possible: with no TTY there is no prompt to pick a lane from, and the agent
  * runs in background mode (no TUI to hand the terminal to).
@@ -15,10 +21,78 @@ import { buildLaunchSpec, getCodingAgent, probeBinary, } from "../agents/registr
 import * as COPY from "../copy.js";
 import { SetupFatalError } from "../errors.js";
 import { buildInstrumentationPrompt } from "../prompts/instrumentationPrompt.js";
+import { offerDocsMcp } from "./offerDocsMcp.js";
+import { prefetchDocs } from "./prefetchDocs.js";
 import { tracesUrl } from "./verifyTraces.js";
 const DEFAULT_LOCAL_ENDPOINT = "http://localhost:6006";
 export async function instrumentApp(deps, connection, args) {
     const { authEnabled, agentDetection, languages, mode } = args;
+    // Resolve the lane before the docs steps: the MCP offer needs to know which
+    // agent is doing the work, and only then can "skip the download" be decided.
+    let chosenAgent;
+    let fallbackLane = "manual";
+    if (args.agent) {
+        // `--agent` short-circuits the lane prompt. The binary is probed rather
+        // than taken from the detection sweep so a named-but-missing agent fails
+        // with "not on your PATH" instead of silently dropping to another lane.
+        const agent = getCodingAgent(args.agent);
+        if (!agent) {
+            throw new SetupFatalError(COPY.INSTRUMENTATION.unknownAgent(args.agent));
+        }
+        if (!(await probeBinary(deps, agent.binary))) {
+            throw new SetupFatalError(COPY.INSTRUMENTATION.agentNotFound(agent.label, agent.binary));
+        }
+        chosenAgent = agent;
+    }
+    else {
+        const detectedAgents = await agentDetection;
+        const options = [
+            ...detectedAgents.map((agent) => ({
+                value: `agent:${agent.id}`,
+                label: COPY.INSTRUMENTATION.launchLabel(agent.label),
+                hint: COPY.INSTRUMENTATION.launchHint,
+            })),
+            {
+                value: "clipboard",
+                label: COPY.INSTRUMENTATION.clipboardLabel,
+                hint: COPY.INSTRUMENTATION.clipboardHint,
+            },
+            {
+                value: "manual",
+                label: COPY.INSTRUMENTATION.manualLabel,
+                hint: COPY.INSTRUMENTATION.manualHint,
+            },
+        ];
+        const choice = await deps.prompter.select({
+            message: COPY.INSTRUMENTATION.modeMessage,
+            options,
+        });
+        chosenAgent = detectedAgents.find((agent) => choice === `agent:${agent.id}`);
+        fallbackLane = choice === "clipboard" ? "clipboard" : "manual";
+    }
+    // The offer is an optimization and never takes setup down with it — that
+    // contract lives inside offerDocsMcp, which reports any failure and returns
+    // "failed" instead of throwing. Only a user cancel unwinds.
+    let docsMcp;
+    if (chosenAgent) {
+        docsMcp = await offerDocsMcp(deps, {
+            docsMcp: args.docsMcp,
+            agent: chosenAgent,
+            headless: args.headless,
+            docsEnabled: args.docs.enabled,
+        });
+    }
+    else if (args.docsMcp === true) {
+        // An explicit --docs-mcp deserves a word when the lane can't honor it,
+        // same as a pinned agent with no MCP install path.
+        deps.prompter.line(COPY.DOCS_MCP.noAgentLane);
+    }
+    const docs = docsMcp?.outcome === "configured"
+        ? undefined
+        : await prefetchDocs(deps, {
+            docs: args.docs,
+            isGitRepository: args.isGitRepository,
+        });
     const prompt = buildInstrumentationPrompt({
         projectName: connection.projectName,
         endpoint: connection.endpoint,
@@ -35,48 +109,22 @@ export async function instrumentApp(deps, connection, args) {
         // Only advertise the local docs dir when it holds pages — an empty one
         // (docs site down, over-narrow workflow filter) would send the agent to
         // read a directory with nothing in it instead of the web.
-        ...(args.docs?.hasPagesOnDisk ? { localDocsDir: args.docs.outputDir } : {}),
+        ...(docs?.hasPagesOnDisk ? { localDocsDir: docs.outputDir } : {}),
+        ...(docsMcp?.outcome === "configured" ? { docsMcpConfigured: true } : {}),
     });
-    // `--agent` short-circuits the lane prompt. The binary is probed rather
-    // than taken from the detection sweep so a named-but-missing agent fails
-    // with "not on your PATH" instead of silently dropping to another lane.
-    if (args.agent) {
-        const agent = getCodingAgent(args.agent);
-        if (!agent) {
-            throw new SetupFatalError(COPY.INSTRUMENTATION.unknownAgent(args.agent));
-        }
-        if (!(await probeBinary(deps, agent.binary))) {
-            throw new SetupFatalError(COPY.INSTRUMENTATION.agentNotFound(agent.label, agent.binary));
-        }
-        return launchAgent(deps, connection, { agent, prompt, mode });
-    }
-    const detectedAgents = await agentDetection;
-    const options = [
-        ...detectedAgents.map((agent) => ({
-            value: `agent:${agent.id}`,
-            label: COPY.INSTRUMENTATION.launchLabel(agent.label),
-            hint: COPY.INSTRUMENTATION.launchHint,
-        })),
-        {
-            value: "clipboard",
-            label: COPY.INSTRUMENTATION.clipboardLabel,
-            hint: COPY.INSTRUMENTATION.clipboardHint,
-        },
-        {
-            value: "manual",
-            label: COPY.INSTRUMENTATION.manualLabel,
-            hint: COPY.INSTRUMENTATION.manualHint,
-        },
-    ];
-    const choice = await deps.prompter.select({
-        message: COPY.INSTRUMENTATION.modeMessage,
-        options,
-    });
-    const chosenAgent = detectedAgents.find((agent) => choice === `agent:${agent.id}`);
     if (chosenAgent) {
-        return launchAgent(deps, connection, { agent: chosenAgent, prompt, mode });
+        const lane = await launchAgent(deps, connection, {
+            agent: chosenAgent,
+            prompt,
+            mode,
+        });
+        return {
+            lane,
+            ...(docs ? { docs } : {}),
+            ...(docsMcp ? { docsMcp } : {}),
+        };
     }
-    if (choice === "clipboard") {
+    if (fallbackLane === "clipboard") {
         const copied = await deps.writeClipboard(prompt);
         if (copied) {
             deps.prompter.line(COPY.INSTRUMENTATION.promptCopied);
@@ -91,14 +139,14 @@ export async function instrumentApp(deps, connection, args) {
                 { value: true, label: COPY.INSTRUMENTATION.clipboardDoneLabel },
             ],
         });
-        return { kind: "clipboard" };
+        return { lane: { kind: "clipboard" }, ...(docs ? { docs } : {}) };
     }
     deps.prompter.line(COPY.INSTRUMENTATION.manualDocs(COPY.DOCS.instrumentationIndex));
     await deps.prompter.select({
         message: COPY.INSTRUMENTATION.manualDoneMessage,
         options: [{ value: true, label: COPY.INSTRUMENTATION.manualDoneLabel }],
     });
-    return { kind: "manual" };
+    return { lane: { kind: "manual" }, ...(docs ? { docs } : {}) };
 }
 /**
  * Run the agent with the prompt pre-loaded. A non-zero exit is a warning, not

package/build/setup/steps/instrumentApp.js.map

@@ -1 +1 @@
-{"version":3,"file":"instrumentApp.js","sourceRoot":"","sources":["../../../src/setup/steps/instrumentApp.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instrumentApp.js","sourceRoot":"","sources":["../../../src/setup/steps/instrumentApp.ts"],"names":[],"mappings":"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"}

package/build/setup/steps/offerDocsMcp.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Offer to connect the Phoenix docs MCP server to the coding agent taking the
+ * hand-off, instead of downloading the docs.
+ *
+ * Taking the offer is the fast path: one small config step replaces the
+ * ~100-page `.px/docs` download, and the agent then searches the docs server
+ * on demand — pulling only the sections it needs instead of reading whole
+ * pages. Declining (or any failure) degrades to the docs prefetch, which is
+ * what setup did before this step existed.
+ *
+ * The offer is an optimization and must never take setup down with it:
+ * whatever goes wrong (an agent CLI whose flags drifted, a config format we
+ * no longer understand), this step reports it, returns a "failed" result, and
+ * the caller carries on with the docs download. The only throw that leaves
+ * this function is a user cancel.
+ *
+ * The offer targets exactly one agent — the lane the user chose (or `--agent`
+ * pinned) — so setup never sprays MCP config for agents that aren't doing the
+ * work. How the entry lands is the agent's own affair ({@link DocsMcpInstall}):
+ * agents with an MCP subcommand register it through their own CLI, the rest
+ * get a merge into their documented config file. Headless runs never touch
+ * agent config unless `--docs-mcp` asked for it.
+ */
+import { type CodingAgent } from "../agents/registry.js";
+import type { SetupDeps } from "../deps/index.js";
+export type DocsMcpOutcome = "configured" | "declined" | "skipped" | "failed";
+/** What the offer did — reported in the setup summary. */
+export interface DocsMcpResult {
+    outcome: DocsMcpOutcome;
+    /** Agents whose config now names the server. */
+    agents: CodingAgent["id"][];
+    /** Repo-relative config files written (empty for a CLI-side install). */
+    files: string[];
+}
+export interface OfferDocsMcpArgs {
+    /** `--docs-mcp` / `--no-docs-mcp`; undefined means ask (when we can). */
+    docsMcp?: boolean;
+    /** The agent taking the hand-off — the only one the offer configures. */
+    agent: CodingAgent;
+    headless: boolean;
+    /**
+     * Whether the docs prefetch would actually run on decline/failure — with
+     * `--no-docs` it won't, and the offer must not promise a download.
+     */
+    docsEnabled: boolean;
+}
+export declare function offerDocsMcp(deps: Pick<SetupDeps, "context" | "prompter" | "processes">, args: OfferDocsMcpArgs): Promise<DocsMcpResult>;
+//# sourceMappingURL=offerDocsMcp.d.ts.map

package/build/setup/steps/offerDocsMcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offerDocsMcp.d.ts","sourceRoot":"","sources":["../../../src/setup/steps/offerDocsMcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKzC,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9E,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,CAAC;IACxB,gDAAgD;IAChD,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;IAC5B,yEAAyE;IACzE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAOD,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC,EAC3D,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,aAAa,CAAC,CAaxB"}

package/build/setup/steps/offerDocsMcp.js

@@ -0,0 +1,134 @@
+/**
+ * Offer to connect the Phoenix docs MCP server to the coding agent taking the
+ * hand-off, instead of downloading the docs.
+ *
+ * Taking the offer is the fast path: one small config step replaces the
+ * ~100-page `.px/docs` download, and the agent then searches the docs server
+ * on demand — pulling only the sections it needs instead of reading whole
+ * pages. Declining (or any failure) degrades to the docs prefetch, which is
+ * what setup did before this step existed.
+ *
+ * The offer is an optimization and must never take setup down with it:
+ * whatever goes wrong (an agent CLI whose flags drifted, a config format we
+ * no longer understand), this step reports it, returns a "failed" result, and
+ * the caller carries on with the docs download. The only throw that leaves
+ * this function is a user cancel.
+ *
+ * The offer targets exactly one agent — the lane the user chose (or `--agent`
+ * pinned) — so setup never sprays MCP config for agents that aren't doing the
+ * work. How the entry lands is the agent's own affair ({@link DocsMcpInstall}):
+ * agents with an MCP subcommand register it through their own CLI, the rest
+ * get a merge into their documented config file. Headless runs never touch
+ * agent config unless `--docs-mcp` asked for it.
+ */
+import * as path from "node:path";
+import { DOCS_MCP_SERVER_URL } from "../agents/registry.js";
+import * as COPY from "../copy.js";
+import { SetupCancelledError } from "../errors.js";
+import { selectBoolean } from "../ui/selectBoolean.js";
+import { writeMcpConfig } from "../util/mcpConfig.js";
+const SKIPPED = { outcome: "skipped", agents: [], files: [] };
+/** Registering a server is one config write; a slow CLI start is still fine. */
+const CLI_INSTALL_TIMEOUT_MS = 30_000;
+export async function offerDocsMcp(deps, args) {
+    try {
+        return await runOffer(deps, args);
+    }
+    catch (error) {
+        if (error instanceof SetupCancelledError) {
+            throw error;
+        }
+        return reportFailure(deps, args, error instanceof Error ? error.message : String(error));
+    }
+}
+/** The single failure path: say what broke, say what happens instead. */
+function reportFailure(deps, { agent, docsEnabled }, reason) {
+    deps.prompter.line(COPY.DOCS_MCP.failedFor(agent.label, reason));
+    deps.prompter.line(docsEnabled ? COPY.DOCS_MCP.fallback : COPY.DOCS_MCP.fallbackWithoutDownload);
+    return { outcome: "failed", agents: [], files: [] };
+}
+async function runOffer(deps, args) {
+    const { docsMcp, agent, headless, docsEnabled } = args;
+    if (docsMcp === false) {
+        return SKIPPED;
+    }
+    const install = agent.docsMcpInstall;
+    if (!install) {
+        // Only worth a line when the caller asked by flag — a pinned agent with
+        // no MCP install path (Codex) would otherwise silently ignore it.
+        if (docsMcp === true) {
+            deps.prompter.line(COPY.DOCS_MCP.unsupported(agent.label));
+        }
+        return SKIPPED;
+    }
+    // An unattended run never edits agent config unless --docs-mcp said so.
+    if (docsMcp === undefined && headless) {
+        return SKIPPED;
+    }
+    const optedIn = docsMcp ??
+        (await selectBoolean({
+            prompter: deps.prompter,
+            message: COPY.DOCS_MCP.message(agent.label),
+            yesLabel: COPY.DOCS_MCP.yes,
+            yesHint: COPY.DOCS_MCP.yesHint,
+            noLabel: docsEnabled ? COPY.DOCS_MCP.no : COPY.DOCS_MCP.noWithoutDownload,
+            noHint: docsEnabled
+                ? COPY.DOCS_MCP.noHint
+                : COPY.DOCS_MCP.noWithoutDownloadHint,
+        }));
+    if (!optedIn) {
+        return { outcome: "declined", agents: [], files: [] };
+    }
+    if (install.kind === "cli") {
+        const exec = (execArgs) => deps.processes.exec({
+            command: agent.binary,
+            args: execArgs,
+            cwd: deps.context.cwd,
+            timeoutMs: CLI_INSTALL_TIMEOUT_MS,
+        });
+        // `add` first: the clean path is one registration plus the read-back.
+        // Only when `add` is refused AND the agent's own listing shows an entry
+        // under our name is that entry removed and the add retried — removing
+        // before knowing the add works would destroy a working registration
+        // that a failed retry can't put back.
+        let added = await exec(install.addArgs(DOCS_MCP_SERVER_URL));
+        if (added.exitCode !== 0) {
+            const existing = await exec(install.verifyArgs);
+            if (existing.exitCode !== 0) {
+                return reportFailure(deps, args, added.stderr.trim() || `exit code ${added.exitCode}`);
+            }
+            await exec(install.removeArgs);
+            added = await exec(install.addArgs(DOCS_MCP_SERVER_URL));
+            if (added.exitCode !== 0) {
+                return reportFailure(deps, args, added.stderr.trim() || `exit code ${added.exitCode}`);
+            }
+        }
+        // Don't trust the add's exit code alone: read the entry back through the
+        // agent's own listing, so a drifted command that "succeeds" without
+        // registering anything is caught here instead of silently costing the
+        // agent its docs.
+        const verified = await exec(install.verifyArgs);
+        if (verified.exitCode !== 0) {
+            return reportFailure(deps, args, COPY.DOCS_MCP.verifyFailed);
+        }
+        deps.prompter.line(COPY.DOCS_MCP.configuredCli(agent.label));
+        return { outcome: "configured", agents: [agent.id], files: [] };
+    }
+    // A write that throws (unparseable existing file, permissions) is handled
+    // by the catch-all in offerDocsMcp.
+    writeMcpConfig({
+        filePath: path.join(deps.context.cwd, install.relativePath),
+        displayPath: install.relativePath,
+        patch: install.patch(DOCS_MCP_SERVER_URL),
+        ...(install.createDefaults
+            ? { createDefaults: install.createDefaults }
+            : {}),
+    });
+    deps.prompter.line(COPY.DOCS_MCP.configured([install.relativePath]));
+    return {
+        outcome: "configured",
+        agents: [agent.id],
+        files: [install.relativePath],
+    };
+}
+//# sourceMappingURL=offerDocsMcp.js.map