@arizeai/phoenix-cli 1.8.0 → 1.9.0

package/build/setup/copy.js

@@ -0,0 +1,290 @@
+/**
+ * ALL user-facing strings for setup, grouped by the step that emits
+ * them. Control flow references copy; copy never references control flow.
+ * Keep prose here so wording changes never touch step logic.
+ */
+// ---------------------------------------------------------------------------
+// Docs contract — the only doc URLs setup emits.
+// ---------------------------------------------------------------------------
+export const DOCS = {
+    /** Agent-facing quickstart, Python (arize-phoenix-otel). */
+    quickstartPython: "https://arize.com/docs/phoenix/get-started/get-started-tracing",
+    /** Agent-facing quickstart, TypeScript (@arizeai/phoenix-otel). */
+    quickstartTypeScript: "https://arize.com/docs/phoenix/get-started/ts-get-started-tracing",
+    /** phoenix.otel register() reference for custom setups. */
+    phoenixOtelSetup: "https://arize.com/docs/phoenix/tracing/how-to-tracing/setup-tracing/setup-using-phoenix-otel",
+    /** Per-framework/provider auto-instrumentation guides. */
+    integrationsIndex: "https://arize.com/docs/phoenix/integrations",
+    /** Linked from the verification step. */
+    troubleshooting: "https://arize.com/docs/phoenix/tracing/concepts-tracing/faqs-tracing",
+    /** Linked from the manual lane and headless output. */
+    instrumentationIndex: "https://arize.com/docs/phoenix/quickstart",
+};
+export const SUPPORT_LINKS = [
+    `Docs:            ${DOCS.instrumentationIndex}`,
+    `Troubleshooting: ${DOCS.troubleshooting}`,
+    "Issues:          https://github.com/Arize-ai/phoenix/issues",
+    "Community:       https://arize-ai.slack.com",
+].join("\n");
+// ---------------------------------------------------------------------------
+// Shell / lifecycle
+// ---------------------------------------------------------------------------
+export const INTRO = "Phoenix tracing setup";
+export const INTRO_INSTRUMENT = "Phoenix setup — instrument this app and verify traces arrive.";
+export const INTRO_SKILLS = "Install agent skills";
+export const CANCEL_OUTRO = [
+    "Setup cancelled. Nothing else was changed.",
+    "",
+    SUPPORT_LINKS,
+].join("\n");
+export const OUTRO_TITLE = "You're set up.";
+export const OUTRO_BODY = SUPPORT_LINKS;
+// ---------------------------------------------------------------------------
+// Confirm git safety
+// ---------------------------------------------------------------------------
+export const GIT = {
+    notARepoMessage: "This directory is not a git repository. Continue anyway?",
+    notARepoYes: "Yes, continue without git",
+    notARepoNo: "No, stop here (recommended)",
+    notARepoNoHint: "Setup may edit files via a coding agent — git is the undo button.",
+    notARepoYesHint: "You will have no easy way to review or revert changes.",
+    dirtyMessage: (fileCount) => `You have ${fileCount} uncommitted change${fileCount === 1 ? "" : "s"}. Continue anyway?`,
+    dirtyYes: "Yes, continue with a dirty tree",
+    dirtyNo: "No, stop here so I can commit first (recommended)",
+    dirtyNoHint: "A clean tree keeps agent edits separate from your own edits.",
+    dirtyYesHint: "Agent edits will be tangled with your uncommitted work.",
+    dirtyFileListTitle: "Uncommitted changes",
+    andMore: (count) => `…and ${count} more`,
+    headlessDirty: "Refusing to run headless in a dirty git tree. Commit or stash your changes and re-run.",
+    headlessNotARepo: "Refusing to run headless outside a git repository. Run `git init` (or run setup interactively) and re-run.",
+    stopped: "Stopped. Commit your work, then re-run `px setup`.",
+};
+// ---------------------------------------------------------------------------
+// Choose endpoint
+// ---------------------------------------------------------------------------
+export const ENDPOINT = {
+    selectMessage: "Where is your Phoenix instance running?",
+    localLabel: "Local — http://localhost:6006",
+    localHint: "recommended if you just ran `phoenix serve`",
+    remoteLabel: "Remote — paste your instance URL",
+    remoteHint: "any Phoenix instance reachable by URL",
+    remoteUrlMessage: "Phoenix instance URL",
+    remoteUrlInvalid: "Enter a full http:// or https:// URL, e.g. https://phoenix.example.com",
+    probing: (endpoint) => `Checking ${endpoint}…`,
+    unexpectedBody: "unexpected response body",
+    unreachable: (endpoint) => [
+        `Could not reach a Phoenix instance at ${endpoint}.`,
+        "If it's local, is `phoenix serve` running? If it's remote, check the",
+        "URL and that you can reach it from this machine (VPN?).",
+    ].join("\n"),
+    notPhoenix: (endpoint, detail) => [
+        `${endpoint} responded, but not like a Phoenix instance (${detail}).`,
+        "Double-check the URL — it should be the Phoenix root URL, without",
+        "a path like /projects.",
+    ].join("\n"),
+    retryMessage: "Try a different URL?",
+    retryYes: "Yes, enter a URL again",
+    retryNo: "No, exit setup",
+    gaveUp: [
+        "Couldn't establish a connection after several attempts.",
+        `Setup docs: ${DOCS.instrumentationIndex}`,
+    ].join("\n"),
+    authOn: "Authentication is enabled on this instance.",
+    authOff: "Authentication is off — no API key needed.",
+    headlessUnreachable: (endpoint) => `Could not reach Phoenix at ${endpoint}. Is it running and reachable from this machine?`,
+    headlessNeedsEndpoint: [
+        "Missing endpoint. Provide one of:",
+        "  --endpoint <url>",
+        "  PHOENIX_HOST=<url> (or PHOENIX_COLLECTOR_ENDPOINT=<url>)",
+    ].join("\n"),
+};
+// ---------------------------------------------------------------------------
+// Connection
+// ---------------------------------------------------------------------------
+export const CONNECT = {
+    projectNameMessage: "Phoenix project name for this app's traces",
+    projectNameInvalid: "Project names can't contain '/', '?', or '#' and can't be empty.",
+    usingProject: (name) => `Using project "${name}" — Phoenix creates it when the first trace arrives.`,
+    connectFailed: (detail) => `Couldn't connect to Phoenix (${detail}).`,
+    headlessNeedsProject: [
+        "Missing project. Provide one of:",
+        "  --project <name>",
+        "  PHOENIX_PROJECT=<name> (or PHOENIX_PROJECT_NAME=<name>)",
+    ].join("\n"),
+    headlessNeedsApiKey: [
+        "This Phoenix instance has authentication enabled. Headless setup needs an API key. Provide:",
+        "  PHOENIX_API_KEY=<key>",
+        "and a project via --project or PHOENIX_PROJECT.",
+    ].join("\n"),
+    headlessAuthRejected: "The API key was rejected. Check PHOENIX_API_KEY.",
+};
+// ---------------------------------------------------------------------------
+// Auth-on credential entry
+// ---------------------------------------------------------------------------
+export const API_KEY = {
+    instructionsTitle: "Phoenix API key",
+    instructions: [
+        "Create or copy an API key in Phoenix under Settings, then paste it here.",
+        "The key is masked while you type and is only written to local credential files.",
+    ].join("\n"),
+    pasteKeyMessage: "Phoenix API key",
+    pasteKeyInvalid: "API key can't be empty.",
+    pasteKeyRejected: "That API key was rejected by the instance. Try again.",
+};
+// ---------------------------------------------------------------------------
+// Env file
+// ---------------------------------------------------------------------------
+export const ENV_FILE = {
+    wrote: (names) => `Wrote ${names.join(" and ")} into this directory (readable only by you).`,
+    gitignored: (names) => `Added ${names.join(", ")} to .gitignore.`,
+    fileHeaderEnv: (isoDate) => [
+        `# Generated by \`px setup\` on ${isoDate}.`,
+        "# Contains a Phoenix API key — do NOT commit this file.",
+        "# Safe to delete once tracing is verified and production is configured.",
+    ].join("\n"),
+};
+// ---------------------------------------------------------------------------
+// Instrumentation
+// ---------------------------------------------------------------------------
+export const INSTRUMENTATION = {
+    modeMessage: "How do you want to instrument this app?",
+    launchLabel: (agentLabel) => `Hand off to ${agentLabel}`,
+    launchHint: "launches here with the setup prompt pre-loaded",
+    unknownAgent: (agent) => `Unknown agent "${agent}".`,
+    agentNotFound: (agentLabel, binary) => `${agentLabel} isn't on your PATH (looked for \`${binary}\`). Install it, or pick another agent with --agent.`,
+    launchingBackground: (agentLabel) => `Running ${agentLabel} in the background — it will add tracing and emit a test trace.`,
+    backgroundNeedsYolo: (agentLabel) => `${agentLabel} runs without a terminal here, so it cannot ask you to approve its edits. Pass --yolo to let it proceed, or it will likely stall until verification times out.`,
+    launching: (agentLabel) => [
+        `Handing off to ${agentLabel} — it will add tracing and emit a test trace.`,
+        "When you exit the agent, setup resumes and verifies traces arrived.",
+    ].join("\n"),
+    agentExitWarning: (agentLabel) => `${agentLabel} exited with an error — continuing to verification anyway.`,
+    clipboardLabel: "Copy a prompt for my own coding agent",
+    clipboardHint: "paste it into Claude Code, Codex, Cursor — any agent you run yourself",
+    manualLabel: "I'll do it manually",
+    manualHint: "follow the quickstart docs yourself",
+    promptCopied: "Instrumentation prompt copied to your clipboard. Paste it into your agent in this directory.",
+    promptCopyFailed: "Couldn't write to the clipboard — here is the prompt to copy:",
+    clipboardDoneMessage: "When your agent has finished:",
+    clipboardDoneLabel: "I've run the prompt",
+    manualDocs: (url) => `Follow the tracing quickstart: ${url}`,
+    manualDoneMessage: "When you've added instrumentation:",
+    manualDoneLabel: "I've finished instrumenting",
+};
+// ---------------------------------------------------------------------------
+// Verification + production hand-off
+// ---------------------------------------------------------------------------
+export const VERIFY = {
+    title: "Verifying traces",
+    waitingBody: (tracesUrl) => [
+        "Watching Phoenix for your first trace…",
+        "",
+        "If nothing has sent a trace yet, in another terminal:",
+        "  1. Export the vars:  set -a; source .env.phoenix; set +a",
+        "  2. Run your app and make one LLM call.",
+        "",
+        `Traces appear at ${tracesUrl}`,
+    ].join("\n"),
+    received: (tracesUrl) => `✓ Traces are flowing. View them: ${tracesUrl}`,
+    timeoutMessage: "No traces have arrived yet. Keep watching?",
+    keepWatchingLabel: "Keep watching",
+    finishLabel: "Finish setup — I'll verify later",
+    finishHint: "everything else is already configured",
+    notVerifiedHeadless: (tracesUrl) => `No trace arrived within the wait window. The connection and hand-off files are in place; check ${tracesUrl} once your app sends one.`,
+    notVerifiedTitle: "Traces not verified yet",
+    notVerifiedBody: (tracesUrl) => [
+        `Your first trace will appear at ${tracesUrl}`,
+        `Not seeing traces? ${DOCS.troubleshooting}`,
+    ].join("\n"),
+};
+export const PRODUCTION = {
+    title: "Production hand-off",
+    bodyAuthOn: [
+        "Set these in your production environment:",
+        "",
+        "  PHOENIX_COLLECTOR_ENDPOINT — same value as in .env.phoenix",
+        "  PHOENIX_API_KEY            — copy from .env.phoenix into your secret store",
+        "",
+        "The project name is set in code, so no extra env var is needed for it.",
+    ].join("\n"),
+    bodyAuthOff: [
+        "This instance has no auth, so your app only needs:",
+        "",
+        "  PHOENIX_COLLECTOR_ENDPOINT — your Phoenix URL",
+        "",
+        "When you deploy Phoenix for real (with auth), also set PHOENIX_API_KEY.",
+    ].join("\n"),
+};
+// ---------------------------------------------------------------------------
+// Offer px profile
+// ---------------------------------------------------------------------------
+export const PX_PROFILE = {
+    optInMessage: "Also point the px CLI at this project? (lets you query traces from your terminal)",
+    optInYes: "Yes, create a px profile",
+    optInNo: "No thanks",
+    conflictMessage: (profileName, endpoint) => `px is currently using profile "${profileName}" → ${endpoint}. Switch to this project?`,
+    conflictYes: "Yes, switch px to this project",
+    conflictNo: "No, leave px as-is",
+    created: (profileName) => `px profile "${profileName}" created and activated. Try: px trace list`,
+    failed: (detail) => `Couldn't write the px profile (${detail}). You can create one later with \`px profile create\`.`,
+    // Distinct from `failed`: nothing was written, the settings file could not be
+    // *read*, and `px profile create` reads it the same strict way — so pointing
+    // there would hand back a remedy that fails identically. Name the file
+    // instead; repairing or removing it is the only way forward.
+    unreadableSettings: (settingsPath, detail) => `Couldn't read ${settingsPath} (${detail}), so px was left alone. Fix or delete that file, then run \`px profile create\`.`,
+};
+// ---------------------------------------------------------------------------
+// Install tooling (CLI + skills)
+// ---------------------------------------------------------------------------
+/**
+ * The skills repo, named once: the command we spawn and the commands the copy
+ * below tells the user to run by hand have to point at the same place.
+ */
+export const SKILLS_SOURCE = "Arize-ai/phoenix";
+/** One copy group per install offer; both share the shape `ToolingOfferCopy`. */
+export const TOOLING = {
+    cli: {
+        message: "Install the px CLI globally? (`px` isn't on your PATH — it lets you query traces from any terminal)",
+        yes: "Yes, npm install -g @arizeai/phoenix-cli",
+        no: "No thanks",
+        installed: "px CLI installed. Try `px --help` in a new shell.",
+        failed: "CLI install failed — install later with `npm install -g @arizeai/phoenix-cli`.",
+    },
+    skills: {
+        message: "Install agent skills? (opens a skill picker — query traces, debug failures)",
+        yes: `Yes, run npx skills add ${SKILLS_SOURCE}`,
+        no: "No thanks",
+        installed: "Phoenix skills installed. Your coding agent can now query and debug traces.",
+        failed: `Skills install failed — install later with \`npx skills add ${SKILLS_SOURCE}\`.`,
+    },
+};
+// ---------------------------------------------------------------------------
+// Docs prefetch
+// ---------------------------------------------------------------------------
+export const DOCS_PREFETCH = {
+    fetching: "Downloading the Phoenix docs so the agent reads them locally...",
+    // The unknown-workflow warning is not here: it is worded once in
+    // `commands/docs`, next to the list of workflows it has to stay true to, and
+    // reaches this step through the docs seam.
+    wrote: (pages, outputDir) => `Downloaded ${pages} doc page(s) to ${outputDir}.`,
+    failed: (reason) => `Couldn't download the docs (${reason}) — the agent will read them from the web instead.`,
+};
+// ---------------------------------------------------------------------------
+// Headless output
+// ---------------------------------------------------------------------------
+export const HEADLESS = {
+    agentRequired: (agentIds) => [
+        "Missing required flag --agent.",
+        "  Headless setup has no prompt to pick an instrumentation lane from, so it must be told which agent to run.",
+        `  px setup --no-input --instrument --agent <${agentIds.join("|")}> --yolo`,
+        "  To register only — endpoint, project, .env.phoenix, no source changes:",
+        "  px setup --no-input",
+    ].join("\n"),
+    nextSteps: (tracesUrl) => [
+        "Next steps:",
+        "  1. Export the vars:   set -a; source .env.phoenix; set +a",
+        `  2. Instrument your app: ${DOCS.instrumentationIndex}`,
+        `  3. Watch for traces:  ${tracesUrl}`,
+    ].join("\n"),
+};
+//# sourceMappingURL=copy.js.map

package/build/setup/copy.js.map

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

package/build/setup/deps/buildDefaultDeps.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The composition root: the one place the capability contracts meet their
+ * real, system-backed implementations. Kept separate from the contract
+ * barrel (`index.ts`) so modules the wiring depends on — like the clack
+ * prompter — can themselves import contracts from `../deps` without forming
+ * a cycle.
+ */
+import type { SetupDeps } from "./index.js";
+export declare function buildDefaultDeps({ apiUrl, }?: {
+    /** Hidden --api-url dev override — see {@link createPhoenixClientFactory}. */
+    apiUrl?: string;
+}): SetupDeps;
+//# sourceMappingURL=buildDefaultDeps.d.ts.map

package/build/setup/deps/buildDefaultDeps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildDefaultDeps.d.ts","sourceRoot":"","sources":["../../../src/setup/deps/buildDefaultDeps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,GACP,GAAE;IACD,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GAAG,SAAS,CAajB"}

package/build/setup/deps/buildDefaultDeps.js

@@ -0,0 +1,29 @@
+/**
+ * The composition root: the one place the capability contracts meet their
+ * real, system-backed implementations. Kept separate from the contract
+ * barrel (`index.ts`) so modules the wiring depends on — like the clack
+ * prompter — can themselves import contracts from `../deps` without forming
+ * a cycle.
+ */
+import { createClackPrompter } from "../ui/clackPrompter.js";
+import { createSystemClipboardWriter } from "./clipboard.js";
+import { createSystemClock } from "./clock.js";
+import { captureRunContext } from "./context.js";
+import { fetchDocs } from "./docs.js";
+import { createPhoenixClientFactory } from "./phoenixClient.js";
+import { createSystemProcessRunner } from "./processes.js";
+export function buildDefaultDeps({ apiUrl, } = {}) {
+    const processes = createSystemProcessRunner();
+    return {
+        context: captureRunContext(),
+        prompter: createClackPrompter(),
+        processes,
+        clock: createSystemClock(),
+        // The clipboard is itself composed from the process runner: pbcopy & co
+        // are subprocesses.
+        writeClipboard: createSystemClipboardWriter(processes.exec),
+        createClient: createPhoenixClientFactory({ apiUrl }),
+        fetchDocs,
+    };
+}
+//# sourceMappingURL=buildDefaultDeps.js.map

package/build/setup/deps/buildDefaultDeps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildDefaultDeps.js","sourceRoot":"","sources":["../../../src/setup/deps/buildDefaultDeps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAGxD,MAAM,UAAU,gBAAgB,CAAC,EAC/B,MAAM,GACP,GAGG,EAAE;IACJ,MAAM,SAAS,GAAG,yBAAyB,EAAE,CAAC;IAC9C,OAAO;QACL,OAAO,EAAE,iBAAiB,EAAE;QAC5B,QAAQ,EAAE,mBAAmB,EAAE;QAC/B,SAAS;QACT,KAAK,EAAE,iBAAiB,EAAE;QAC1B,wEAAwE;QACxE,oBAAoB;QACpB,cAAc,EAAE,2BAA2B,CAAC,SAAS,CAAC,IAAI,CAAC;QAC3D,YAAY,EAAE,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;QACpD,SAAS;KACV,CAAC;AACJ,CAAC"}

package/build/setup/deps/clipboard.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The clipboard capability. The system implementation is composed from the
+ * process runner — pbcopy & co are subprocesses, not a second effect channel.
+ */
+import type { ProcessRunner } from "./processes.js";
+/**
+ * Write text to the system clipboard. Resolves false on failure — callers
+ * fall back to printing the text.
+ */
+export type ClipboardWriter = (text: string) => Promise<boolean>;
+export declare function createSystemClipboardWriter(exec: ProcessRunner["exec"]): ClipboardWriter;
+//# sourceMappingURL=clipboard.d.ts.map

package/build/setup/deps/clipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../../../src/setup/deps/clipboard.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEjE,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAC1B,eAAe,CAwBjB"}

package/build/setup/deps/clipboard.js

@@ -0,0 +1,30 @@
+/**
+ * The clipboard capability. The system implementation is composed from the
+ * process runner — pbcopy & co are subprocesses, not a second effect channel.
+ */
+import * as process from "node:process";
+export function createSystemClipboardWriter(exec) {
+    return async (text) => {
+        const platform = process.platform;
+        const candidates = platform === "darwin"
+            ? [{ command: "pbcopy", args: [], stdin: text }]
+            : platform === "win32"
+                ? [{ command: "clip", args: [], stdin: text }]
+                : [
+                    { command: "wl-copy", args: [], stdin: text },
+                    {
+                        command: "xclip",
+                        args: ["-selection", "clipboard"],
+                        stdin: text,
+                    },
+                ];
+        for (const candidate of candidates) {
+            const result = await exec(candidate);
+            if (result.exitCode === 0) {
+                return true;
+            }
+        }
+        return false;
+    };
+}
+//# sourceMappingURL=clipboard.js.map

package/build/setup/deps/clipboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.js","sourceRoot":"","sources":["../../../src/setup/deps/clipboard.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AAUxC,MAAM,UAAU,2BAA2B,CACzC,IAA2B;IAE3B,OAAO,KAAK,EAAE,IAAI,EAAE,EAAE;QACpB,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QAClC,MAAM,UAAU,GACd,QAAQ,KAAK,QAAQ;YACnB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAChD,CAAC,CAAC,QAAQ,KAAK,OAAO;gBACpB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;gBAC9C,CAAC,CAAC;oBACE,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;oBAC7C;wBACE,OAAO,EAAE,OAAO;wBAChB,IAAI,EAAE,CAAC,YAAY,EAAE,WAAW,CAAC;wBACjC,KAAK,EAAE,IAAI;qBACZ;iBACF,CAAC;QACV,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC;YACrC,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/build/setup/deps/clock.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The time capability: reading the clock and waiting on it. Injectable so
+ * trace-verification polling tests run instantly against a scripted clock.
+ */
+export interface Clock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export declare function createSystemClock(): Clock;
+//# sourceMappingURL=clock.d.ts.map

package/build/setup/deps/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../src/setup/deps/clock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,KAAK;IACpB,GAAG,IAAI,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAED,wBAAgB,iBAAiB,IAAI,KAAK,CAKzC"}

package/build/setup/deps/clock.js

@@ -0,0 +1,11 @@
+/**
+ * The time capability: reading the clock and waiting on it. Injectable so
+ * trace-verification polling tests run instantly against a scripted clock.
+ */
+export function createSystemClock() {
+    return {
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    };
+}
+//# sourceMappingURL=clock.js.map

package/build/setup/deps/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../../src/setup/deps/clock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QACrB,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;KACjE,CAAC;AACJ,CAAC"}

package/build/setup/deps/context.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The ambient facts of a run, captured once at startup.
+ *
+ * Plain data, not behavior: steps read these values, they never call through
+ * them. Keeping the snapshot in one place is what stops `process.env` and
+ * `process.cwd()` reads from leaking into steps.
+ */
+export interface RunContext {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    /**
+     * How PATH is spelled in {@link env}. `process.env` resolves names
+     * case-insensitively on Windows, where the variable is conventionally
+     * "Path"; the plain copy below is an ordinary object and does not, so the
+     * spelling is resolved once here rather than by each reader. Read PATH as
+     * `env[pathKey]`, and when overriding it for a child process use this key —
+     * spawning with "PATH" while the inherited environment carries "Path" hands
+     * the child two of them.
+     */
+    pathKey: string;
+    stdinIsTTY: boolean;
+    /** Override the px settings file location (tests only). */
+    settingsPath?: string;
+}
+/** The key PATH is spelled under, or "PATH" when the env carries none. */
+export declare function resolvePathKey(env: Record<string, string | undefined>): string;
+export declare function captureRunContext(): RunContext;
+//# sourceMappingURL=context.d.ts.map

package/build/setup/deps/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/setup/deps/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC;;;;;;;;OAQG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,MAAM,CAER;AAED,wBAAgB,iBAAiB,IAAI,UAAU,CAU9C"}

package/build/setup/deps/context.js

@@ -0,0 +1,24 @@
+/**
+ * The ambient facts of a run, captured once at startup.
+ *
+ * Plain data, not behavior: steps read these values, they never call through
+ * them. Keeping the snapshot in one place is what stops `process.env` and
+ * `process.cwd()` reads from leaking into steps.
+ */
+import * as process from "node:process";
+/** The key PATH is spelled under, or "PATH" when the env carries none. */
+export function resolvePathKey(env) {
+    return Object.keys(env).find((key) => key.toUpperCase() === "PATH") ?? "PATH";
+}
+export function captureRunContext() {
+    // Copied, not aliased — a mid-run mutation of process.env (a spawned
+    // tool, a late dotenv load) must not change what this run resolved.
+    const env = { ...process.env };
+    return {
+        cwd: process.cwd(),
+        env,
+        pathKey: resolvePathKey(env),
+        stdinIsTTY: Boolean(process.stdin.isTTY),
+    };
+}
+//# sourceMappingURL=context.js.map

package/build/setup/deps/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/setup/deps/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AAoBxC,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAC5B,GAAuC;IAEvC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,qEAAqE;IACrE,oEAAoE;IACpE,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC/B,OAAO;QACL,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,GAAG;QACH,OAAO,EAAE,cAAc,CAAC,GAAG,CAAC;QAC5B,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;KACzC,CAAC;AACJ,CAAC"}

package/build/setup/deps/docs.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The docs-prefetch capability: the network+fs seam for the docs step.
+ */
+export { unknownWorkflowWarning } from "../../commands/docs.js";
+export interface DocsPrefetchOptions {
+    /** --no-docs turns the prefetch off; it is on by default. */
+    enabled: boolean;
+    /** --workflow: repeatable workflow filter; defaults to the docs defaults. */
+    workflows?: string[];
+    /** --refresh-docs: clear the output directory before downloading. */
+    refresh?: boolean;
+    /** --workers: concurrent downloads. */
+    workers?: number;
+}
+/** What the docs prefetch actually wrote — reported in the setup summary. */
+export interface DocsPrefetchResult {
+    outputDir: string;
+    workflows: string[];
+    written: number;
+    /** Pages the docs site did not serve; the agent falls back to the web for these. */
+    failed: number;
+    /** Paths the step appended to a .gitignore, folded into the setup report. */
+    gitignoreAppended?: string[];
+    /** `--workflow` names that aren't recognized — surfaced as a warning. */
+    unknownWorkflows?: string[];
+    /**
+     * Whether the docs directory holds pages the agent can read — which is not
+     * the same as `written > 0`. A re-run whose downloads all fail still leaves
+     * the previous run's tree in place, and the agent should be pointed at that
+     * rather than back at a docs site that has just failed us.
+     */
+    hasPagesOnDisk: boolean;
+}
+export type DocsFetcher = (options: DocsPrefetchOptions) => Promise<DocsPrefetchResult>;
+/**
+ * Download the docs the same way `px docs fetch` does, into the same
+ * `.px/docs` directory, so a user who later runs the command by hand refreshes
+ * the tree setup already laid down.
+ */
+export declare function fetchDocs(options: DocsPrefetchOptions): Promise<DocsPrefetchResult>;
+//# sourceMappingURL=docs.d.ts.map

package/build/setup/deps/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/setup/deps/docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG,CACxB,OAAO,EAAE,mBAAmB,KACzB,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEjC;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAiB7B"}

package/build/setup/deps/docs.js

@@ -0,0 +1,33 @@
+/**
+ * The docs-prefetch capability: the network+fs seam for the docs step.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { DEFAULT_OUTPUT_DIR, DEFAULT_WORKERS, downloadDocs, fetchDocsIndex, filterByWorkflows, resolveWorkflows, } from "../../commands/docs.js";
+// This module is setup's only door onto the docs command, so the warning the
+// prefetch step prints for a bad `--workflow` comes through here rather than
+// the step reaching into `commands/` for it.
+export { unknownWorkflowWarning } from "../../commands/docs.js";
+/**
+ * Download the docs the same way `px docs fetch` does, into the same
+ * `.px/docs` directory, so a user who later runs the command by hand refreshes
+ * the tree setup already laid down.
+ */
+export async function fetchDocs(options) {
+    const { workflows, unknown } = resolveWorkflows(options.workflows);
+    const entries = filterByWorkflows(await fetchDocsIndex(), workflows);
+    const outputDir = DEFAULT_OUTPUT_DIR;
+    const { succeeded, failed } = await downloadDocs(entries, {
+        outputDir,
+        workers: options.workers ?? DEFAULT_WORKERS,
+        refresh: options.refresh,
+    });
+    return {
+        outputDir,
+        workflows,
+        written: succeeded.length,
+        failed: failed.length,
+        unknownWorkflows: unknown,
+        hasPagesOnDisk: existsSync(outputDir) && readdirSync(outputDir).length > 0,
+    };
+}
+//# sourceMappingURL=docs.js.map

package/build/setup/deps/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../../src/setup/deps/docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAElD,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,6EAA6E;AAC7E,6EAA6E;AAC7E,6CAA6C;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAqC7D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,OAA4B;IAE5B,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACnE,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,cAAc,EAAE,EAAE,SAAS,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,kBAAkB,CAAC;IACrC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE;QACxD,SAAS;QACT,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,eAAe;QAC3C,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IACH,OAAO;QACL,SAAS;QACT,SAAS;QACT,OAAO,EAAE,SAAS,CAAC,MAAM;QACzB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,gBAAgB,EAAE,OAAO;QACzB,cAAc,EAAE,UAAU,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC;KAC3E,CAAC;AACJ,CAAC"}

package/build/setup/deps/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Dependency seam for setup.
+ *
+ * Every side effect setup performs — env access, network, subprocesses,
+ * clipboard, time — goes through `SetupDeps`. No other module under `setup/`
+ * may touch `process.env`, `fetch`, `child_process`, or the clipboard
+ * directly. This is what makes setup unit-testable with fakes.
+ *
+ * Each capability's contract (and, where it is a few lines of system glue,
+ * its real implementation) lives in its own module in this directory. This
+ * barrel re-exports the contracts so consumers address the seam as one
+ * module; it exports types only, so importing it can never form a runtime
+ * cycle. The wiring lives in `buildDefaultDeps.ts`.
+ */
+import type { ClipboardWriter } from "./clipboard.js";
+import type { Clock } from "./clock.js";
+import type { RunContext } from "./context.js";
+import type { DocsFetcher } from "./docs.js";
+import type { PhoenixClientFactory } from "./phoenixClient.js";
+import type { ProcessRunner } from "./processes.js";
+import type { Prompter } from "./prompter.js";
+export interface SetupDeps {
+    /** Ambient facts of the run — data steps read, never call. */
+    context: RunContext;
+    /** Real: clack-backed ui/clackPrompter.ts; tests: scripted answers. */
+    prompter: Prompter;
+    processes: ProcessRunner;
+    clock: Clock;
+    writeClipboard: ClipboardWriter;
+    /** Typed Phoenix client; tests inject a fake transport beneath it. */
+    createClient: PhoenixClientFactory;
+    fetchDocs: DocsFetcher;
+}
+export type { ClipboardWriter } from "./clipboard.js";
+export type { Clock } from "./clock.js";
+export type { RunContext } from "./context.js";
+export { unknownWorkflowWarning } from "./docs.js";
+export type { DocsFetcher, DocsPrefetchOptions, DocsPrefetchResult, } from "./docs.js";
+export type { PhoenixClientArgs, PhoenixClientFactory } from "./phoenixClient.js";
+export type { CommandSpec, ExecResult, ProcessRunner } from "./processes.js";
+export type { Prompter, SelectOption } from "./prompter.js";
+//# sourceMappingURL=index.d.ts.map