@arizeai/phoenix-cli 1.8.0 → 1.9.0

package/build/setup/steps/prefetchDocs.js

@@ -0,0 +1,49 @@
+/**
+ * Prefetch the Phoenix docs into the repo, so the instrumentation agent reads
+ * package names and APIs from disk instead of fetching URLs mid-run.
+ *
+ * Runs only when instrumentation runs — the docs exist to serve the agent, so
+ * a registration-only run has no reason to write them. Never fatal: a docs
+ * site that is slow or down degrades to the agent fetching pages itself, which
+ * is what it did before this step existed.
+ *
+ * Must run after the git-safety gate: the download writes untracked files
+ * under `.px/`, which a fast headless run could otherwise mistake for
+ * pre-existing user changes.
+ */
+import * as COPY from "../copy.js";
+import { unknownWorkflowWarning, } from "../deps/index.js";
+import { ensureGitignored } from "../util/gitignoreCoverage.js";
+/** The docs land under `.px/`, so that is what gets gitignored. */
+const DOCS_GITIGNORE_ENTRY = ".px/";
+/**
+ * Download the docs and gitignore what they wrote. A failure is reported and
+ * dropped: the connection and hand-off files are real work worth keeping, and
+ * the agent can still read the docs from the web.
+ */
+export async function prefetchDocs(deps, { docs, isGitRepository, }) {
+    if (!docs.enabled) {
+        return undefined;
+    }
+    deps.prompter.line(COPY.DOCS_PREFETCH.fetching);
+    try {
+        const result = await deps.fetchDocs(docs);
+        // A typo'd --workflow filters silently, so name it — otherwise the run
+        // reports "0 pages" with no hint the workflow value was the problem.
+        for (const workflow of result.unknownWorkflows ?? []) {
+            deps.prompter.line(unknownWorkflowWarning(workflow));
+        }
+        const { appended } = ensureGitignored({
+            directory: deps.context.cwd,
+            filenames: [DOCS_GITIGNORE_ENTRY],
+            isGitRepository,
+        });
+        deps.prompter.line(COPY.DOCS_PREFETCH.wrote(result.written, result.outputDir));
+        return { ...result, gitignoreAppended: appended };
+    }
+    catch (error) {
+        deps.prompter.line(COPY.DOCS_PREFETCH.failed(error instanceof Error ? error.message : String(error)));
+        return undefined;
+    }
+}
+//# sourceMappingURL=prefetchDocs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prefetchDocs.js","sourceRoot":"","sources":["../../../src/setup/steps/prefetchDocs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAChC,OAAO,EACL,sBAAsB,GAIvB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,mEAAmE;AACnE,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAEpC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAA2D,EAC3D,EACE,IAAI,EACJ,eAAe,GACyC;IAE1D,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1C,uEAAuE;QACvE,qEAAqE;QACrE,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,gBAAgB,IAAI,EAAE,EAAE,CAAC;YACrD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC;YACpC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;YAC3B,SAAS,EAAE,CAAC,oBAAoB,CAAC;YACjC,eAAe;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,IAAI,CAChB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAC3D,CAAC;QACF,OAAO,EAAE,GAAG,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC;IACpD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,QAAQ,CAAC,IAAI,CAChB,IAAI,CAAC,aAAa,CAAC,MAAM,CACvB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CACF,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,44 @@
+/**
+ * Wait for the first trace to land.
+ *
+ * Setup verifies data flow itself: it polls the Phoenix span-search API
+ * for a span newer than the start of this run until one arrives. The human is
+ * only consulted at the timeout escape hatch ("keep watching / finish
+ * anyway") — never asked to eyeball the UI as the definition of done.
+ */
+import type { SetupDeps } from "../deps/index.js";
+import type { Connection } from "./establishConnection.js";
+/**
+ * The project may not exist until the first trace lands, so link by name via
+ * the redirect route rather than by an id we no longer have.
+ */
+export declare function tracesUrl(connection: Connection): string;
+/**
+ * True when the project already has spans inside the clock-skew window at
+ * `sinceMs`. Checked before instrumentation begins: any span visible at that
+ * point predates this run, so verification must not credit the skew window.
+ */
+export declare function hasSpansInSkewWindow(deps: Pick<SetupDeps, "createClient">, connection: Connection, { sinceMs }: {
+    sinceMs: number;
+}): Promise<boolean>;
+/**
+ * Watch for the first trace since `sinceMs`. Resolves true when a span is
+ * observed via the API, false when the wait ends without one — the user gave
+ * up at the timeout prompt, or, in a headless run, the first window elapsed.
+ *
+ * The "keep watching?" prompt is the only thing that can extend the wait, so a
+ * headless run gets exactly one window: there is no terminal to ask on, and
+ * looping forever would hang an unattended caller.
+ *
+ * @param args.sinceMs - instrumentation start; only spans after it count.
+ * @param args.allowClockSkew - widen the window by the skew tolerance. Pass
+ * false when the project had spans before instrumentation began (see
+ * `hasSpansInSkewWindow`), so stale spans cannot satisfy verification.
+ * @param args.headless - no prompting; give up after one window.
+ */
+export declare function waitForFirstTrace(deps: Pick<SetupDeps, "clock" | "createClient" | "prompter">, connection: Connection, { sinceMs, allowClockSkew, headless, }: {
+    sinceMs: number;
+    allowClockSkew?: boolean;
+    headless?: boolean;
+}): Promise<boolean>;
+//# sourceMappingURL=verifyTraces.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verifyTraces.d.ts","sourceRoot":"","sources":["../../../src/setup/steps/verifyTraces.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAQxD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAIxD;AAOD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EACrC,UAAU,EAAE,UAAU,EACtB,EAAE,OAAO,EAAE,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/B,OAAO,CAAC,OAAO,CAAC,CAMlB;AA0DD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,cAAc,GAAG,UAAU,CAAC,EAC5D,UAAU,EAAE,UAAU,EACtB,EACE,OAAO,EACP,cAAqB,EACrB,QAAgB,GACjB,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GACnE,OAAO,CAAC,OAAO,CAAC,CAoClB"}

package/build/setup/steps/verifyTraces.js

@@ -0,0 +1,119 @@
+/**
+ * Wait for the first trace to land.
+ *
+ * Setup verifies data flow itself: it polls the Phoenix span-search API
+ * for a span newer than the start of this run until one arrives. The human is
+ * only consulted at the timeout escape hatch ("keep watching / finish
+ * anyway") — never asked to eyeball the UI as the definition of done.
+ */
+import * as COPY from "../copy.js";
+const POLL_INTERVAL_MS = 2_000;
+const POLL_WINDOW_MS = 60_000;
+const POLL_REQUEST_TIMEOUT_MS = 5_000;
+/** Tolerance for clock skew between this machine and the span producer. */
+const START_TIME_SKEW_MS = 60_000;
+/**
+ * The project may not exist until the first trace lands, so link by name via
+ * the redirect route rather than by an id we no longer have.
+ */
+export function tracesUrl(connection) {
+    return `${connection.endpoint}/redirects/projects/${encodeURIComponent(connection.projectName)}`;
+}
+/** Inclusive lower bound of the span search, as the API's ISO timestamp. */
+function searchStartTime(sinceMs, skewMs) {
+    return new Date(sinceMs - skewMs).toISOString();
+}
+/**
+ * True when the project already has spans inside the clock-skew window at
+ * `sinceMs`. Checked before instrumentation begins: any span visible at that
+ * point predates this run, so verification must not credit the skew window.
+ */
+export async function hasSpansInSkewWindow(deps, connection, { sinceMs }) {
+    return hasNewSpans(spanSearchClient(deps, connection), connection.projectName, searchStartTime(sinceMs, START_TIME_SKEW_MS));
+}
+function spanSearchClient(deps, connection) {
+    return deps.createClient({
+        endpoint: connection.endpoint,
+        apiKey: connection.apiKey,
+    });
+}
+/**
+ * One span-search request. Any failure is a "not yet": a 404 means the project
+ * has no spans to have created it, and a network hiccup mid-poll should keep
+ * setup watching rather than abort it.
+ */
+async function hasNewSpans(client, projectName, startTime) {
+    try {
+        const { data } = await client.GET("/v1/projects/{project_identifier}/spans", {
+            params: {
+                path: { project_identifier: projectName },
+                query: { limit: 1, start_time: startTime },
+            },
+            signal: AbortSignal.timeout(POLL_REQUEST_TIMEOUT_MS),
+        });
+        return (data?.data.length ?? 0) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Poll until a span arrives or the window elapses. */
+async function pollWindow(deps, client, connection, startTime) {
+    const deadline = deps.clock.now() + POLL_WINDOW_MS;
+    for (;;) {
+        if (await hasNewSpans(client, connection.projectName, startTime)) {
+            return true;
+        }
+        if (deps.clock.now() >= deadline) {
+            return false;
+        }
+        await deps.clock.sleep(POLL_INTERVAL_MS);
+    }
+}
+/**
+ * Watch for the first trace since `sinceMs`. Resolves true when a span is
+ * observed via the API, false when the wait ends without one — the user gave
+ * up at the timeout prompt, or, in a headless run, the first window elapsed.
+ *
+ * The "keep watching?" prompt is the only thing that can extend the wait, so a
+ * headless run gets exactly one window: there is no terminal to ask on, and
+ * looping forever would hang an unattended caller.
+ *
+ * @param args.sinceMs - instrumentation start; only spans after it count.
+ * @param args.allowClockSkew - widen the window by the skew tolerance. Pass
+ * false when the project had spans before instrumentation began (see
+ * `hasSpansInSkewWindow`), so stale spans cannot satisfy verification.
+ * @param args.headless - no prompting; give up after one window.
+ */
+export async function waitForFirstTrace(deps, connection, { sinceMs, allowClockSkew = true, headless = false, }) {
+    const url = tracesUrl(connection);
+    const startTime = searchStartTime(sinceMs, allowClockSkew ? START_TIME_SKEW_MS : 0);
+    const client = spanSearchClient(deps, connection);
+    deps.prompter.note(COPY.VERIFY.waitingBody(url), COPY.VERIFY.title);
+    for (;;) {
+        if (await pollWindow(deps, client, connection, startTime)) {
+            deps.prompter.line(COPY.VERIFY.received(url));
+            return true;
+        }
+        if (headless) {
+            deps.prompter.line(COPY.VERIFY.notVerifiedHeadless(url));
+            return false;
+        }
+        const keepWatching = await deps.prompter.select({
+            message: COPY.VERIFY.timeoutMessage,
+            options: [
+                { value: true, label: COPY.VERIFY.keepWatchingLabel },
+                {
+                    value: false,
+                    label: COPY.VERIFY.finishLabel,
+                    hint: COPY.VERIFY.finishHint,
+                },
+            ],
+        });
+        if (!keepWatching) {
+            deps.prompter.note(COPY.VERIFY.notVerifiedBody(url), COPY.VERIFY.notVerifiedTitle);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=verifyTraces.js.map

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * Write the hand-off file.
+ *
+ * Writes `.env.phoenix` into cwd (deliberately not the repo root — bounded
+ * blast radius in monorepos), mode 0600, then ensures it is gitignored. The
+ * file emits the SDK env var names — it configures the user's app, not px.
+ */
+import type { SetupDeps } from "../deps/index.js";
+import type { Connection } from "./establishConnection.js";
+export declare const ENV_FILE_NAME = ".env.phoenix";
+export declare function renderEnvFile(connection: Connection, isoDate: string): string;
+export interface WriteEnvFileResult {
+    envFilePath: string;
+    gitignoreAppended: string[];
+}
+export declare function writeEnvFile(deps: Pick<SetupDeps, "clock" | "context">, connection: Connection, { isGitRepository }: {
+    isGitRepository: boolean;
+}): WriteEnvFileResult;
+//# sourceMappingURL=writeEnvFile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writeEnvFile.d.ts","sourceRoot":"","sources":["../../../src/setup/steps/writeEnvFile.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,eAAO,MAAM,aAAa,iBAAiB,CAAC;AAY5C,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAU7E;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC,EAC1C,UAAU,EAAE,UAAU,EACtB,EAAE,eAAe,EAAE,EAAE;IAAE,eAAe,EAAE,OAAO,CAAA;CAAE,GAChD,kBAAkB,CAmBpB"}

package/build/setup/steps/writeEnvFile.js

@@ -0,0 +1,50 @@
+/**
+ * Write the hand-off file.
+ *
+ * Writes `.env.phoenix` into cwd (deliberately not the repo root — bounded
+ * blast radius in monorepos), mode 0600, then ensures it is gitignored. The
+ * file emits the SDK env var names — it configures the user's app, not px.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as COPY from "../copy.js";
+import { ensureGitignored } from "../util/gitignoreCoverage.js";
+export const ENV_FILE_NAME = ".env.phoenix";
+/**
+ * Double-quote a value for a `source`-able env file, escaping the characters
+ * the shell still interprets inside double quotes. Project names may contain
+ * spaces (the default is the cwd basename), and dotenv-style loaders strip
+ * the same quotes.
+ */
+function quoteEnvValue(value) {
+    return `"${value.replace(/[\\"$`]/g, (char) => `\\${char}`)}"`;
+}
+export function renderEnvFile(connection, isoDate) {
+    const lines = [
+        COPY.ENV_FILE.fileHeaderEnv(isoDate),
+        `PHOENIX_COLLECTOR_ENDPOINT=${quoteEnvValue(connection.endpoint)}`,
+        `PHOENIX_PROJECT_NAME=${quoteEnvValue(connection.projectName)}`,
+    ];
+    if (connection.apiKey) {
+        lines.push(`PHOENIX_API_KEY=${quoteEnvValue(connection.apiKey)}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function writeEnvFile(deps, connection, { isGitRepository }) {
+    const isoDate = new Date(deps.clock.now()).toISOString();
+    const envFilePath = path.join(deps.context.cwd, ENV_FILE_NAME);
+    fs.writeFileSync(envFilePath, renderEnvFile(connection, isoDate), {
+        encoding: "utf-8",
+        mode: 0o600,
+    });
+    // Rewrites of an existing file keep its old mode — enforce 0600 anyway.
+    fs.chmodSync(envFilePath, 0o600);
+    // Applied in the auth-off case too: the file may later gain a key.
+    const { appended } = ensureGitignored({
+        directory: deps.context.cwd,
+        filenames: [ENV_FILE_NAME],
+        isGitRepository,
+    });
+    return { envFilePath, gitignoreAppended: appended };
+}
+//# sourceMappingURL=writeEnvFile.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writeEnvFile.js","sourceRoot":"","sources":["../../../src/setup/steps/writeEnvFile.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAEhC,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAG7D,MAAM,CAAC,MAAM,aAAa,GAAG,cAAc,CAAC;AAE5C;;;;;GAKG;AACH,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,UAAsB,EAAE,OAAe;IACnE,MAAM,KAAK,GAAG;QACZ,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC;QACpC,8BAA8B,aAAa,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE;QAClE,wBAAwB,aAAa,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE;KAChE,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,mBAAmB,aAAa,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC;AAOD,MAAM,UAAU,YAAY,CAC1B,IAA0C,EAC1C,UAAsB,EACtB,EAAE,eAAe,EAAgC;IAEjD,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACzD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IAE/D,EAAE,CAAC,aAAa,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE;QAChE,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IACH,wEAAwE;IACxE,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAEjC,mEAAmE;IACnE,MAAM,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC;QACpC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;QAC3B,SAAS,EAAE,CAAC,aAAa,CAAC;QAC1B,eAAe;KAChB,CAAC,CAAC;IAEH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC;AACtD,CAAC"}

package/build/setup/ui/clackPrompter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Clack-backed implementation of setup's `Prompter` seam.
+ *
+ * House rules: setup has no confirm primitive — every
+ * choice, including booleans, is a select. Cancellation (Ctrl-C / Escape)
+ * maps to `SetupCancelledError`, unwinding to the single catch site in the
+ * command handler.
+ */
+import type { Prompter } from "../deps/index.js";
+export declare function createClackPrompter(): Prompter;
+//# sourceMappingURL=clackPrompter.d.ts.map

package/build/setup/ui/clackPrompter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clackPrompter.d.ts","sourceRoot":"","sources":["../../../src/setup/ui/clackPrompter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EAAE,QAAQ,EAAgB,MAAM,SAAS,CAAC;AAWtD,wBAAgB,mBAAmB,IAAI,QAAQ,CAyG9C"}

package/build/setup/ui/clackPrompter.js

@@ -0,0 +1,107 @@
+/**
+ * Clack-backed implementation of setup's `Prompter` seam.
+ *
+ * House rules: setup has no confirm primitive — every
+ * choice, including booleans, is a select. Cancellation (Ctrl-C / Escape)
+ * maps to `SetupCancelledError`, unwinding to the single catch site in the
+ * command handler.
+ */
+import { intro, isCancel, log, outro, password, select, text, } from "@clack/prompts";
+import { SetupCancelledError } from "../errors.js";
+// Nothing this seam writes belongs on stdout: under `--format raw|json` stdout
+// carries the machine-readable report and nothing else, and a banner, a prompt,
+// or a narration line mixed into it is a parse error for whoever is reading.
+// Every clack primitive defaults to stdout and takes an `output`, so every call
+// below passes this — including the prompts, which an interactive `--format
+// json` run would otherwise render into the report.
+const TO_STDERR = { output: process.stderr };
+export function createClackPrompter() {
+    return {
+        async select(args) {
+            // Loop so picking a disabled option explains itself and re-asks
+            // instead of proceeding.
+            for (;;) {
+                // Clack's Option<T> type only resolves for primitive T; the shape
+                // we build is valid for both branches, so the cast is safe.
+                const answer = await select({
+                    ...TO_STDERR,
+                    message: args.message,
+                    options: args.options.map((option) => ({
+                        value: option.value,
+                        label: option.disabled ? `✗ ${option.label}` : option.label,
+                        hint: option.hint,
+                    })),
+                });
+                if (isCancel(answer)) {
+                    throw new SetupCancelledError();
+                }
+                const picked = args.options.find((option) => option.value === answer);
+                if (picked?.disabled) {
+                    log.warn(picked.hint ?? "That option is not available.", TO_STDERR);
+                    continue;
+                }
+                return answer;
+            }
+        },
+        async textInput(args) {
+            const answer = await text({
+                ...TO_STDERR,
+                message: args.message,
+                defaultValue: args.defaultValue,
+                placeholder: args.defaultValue,
+                validate: args.validate
+                    ? (value) => {
+                        // Clack substitutes defaultValue for an empty submission, but
+                        // runs validate on the raw (empty) input — validate what will
+                        // actually be returned.
+                        const effective = !value && args.defaultValue !== undefined
+                            ? args.defaultValue
+                            : (value ?? "");
+                        return args.validate?.(effective);
+                    }
+                    : undefined,
+            });
+            if (isCancel(answer)) {
+                throw new SetupCancelledError();
+            }
+            return answer;
+        },
+        async passwordInput(args) {
+            const answer = await password({
+                ...TO_STDERR,
+                message: args.message,
+                validate: args.validate
+                    ? (value) => args.validate?.(value ?? "")
+                    : undefined,
+            });
+            if (isCancel(answer)) {
+                throw new SetupCancelledError();
+            }
+            return answer;
+        },
+        note(message, title) {
+            // A heading over an indented body, not clack's boxed `note`: clack's guide
+            // rail already sets the block apart, and the box adds a border that has to
+            // reflow on every resize. Untitled, there is no heading to indent under.
+            if (title === undefined) {
+                log.message(message, TO_STDERR);
+                return;
+            }
+            const body = message
+                .split("\n")
+                .map((line) => `  ${line}`)
+                .join("\n");
+            log.message(`${title}\n${body}`, TO_STDERR);
+        },
+        line(message) {
+            log.message(message, TO_STDERR);
+        },
+        intro(message) {
+            intro(message, TO_STDERR);
+        },
+        outro(message) {
+            outro(message, TO_STDERR);
+        },
+    };
+}
+//# sourceMappingURL=clackPrompter.js.map

package/build/setup/ui/clackPrompter.js.map

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

package/build/setup/ui/selectBoolean.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Boolean choice rendered as a labeled select — setup has no bare
+ * confirm. For dangerous choices the "No" option is listed first
+ * so the default cursor position is the safe one.
+ */
+import type { Prompter } from "../deps/index.js";
+export interface SelectBooleanArgs {
+    prompter: Prompter;
+    message: string;
+    yesLabel: string;
+    noLabel: string;
+    yesHint?: string;
+    noHint?: string;
+    /** When true, "No" is listed first (safe default for dangerous choices). */
+    noFirst?: boolean;
+}
+export declare function selectBoolean({ prompter, message, yesLabel, noLabel, yesHint, noHint, noFirst, }: SelectBooleanArgs): Promise<boolean>;
+//# sourceMappingURL=selectBoolean.d.ts.map

package/build/setup/ui/selectBoolean.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectBoolean.d.ts","sourceRoot":"","sources":["../../../src/setup/ui/selectBoolean.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAsB,aAAa,CAAC,EAClC,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,OAAO,EACP,OAAO,EACP,MAAM,EACN,OAAO,GACR,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAOtC"}

package/build/setup/ui/selectBoolean.js

@@ -0,0 +1,14 @@
+/**
+ * Boolean choice rendered as a labeled select — setup has no bare
+ * confirm. For dangerous choices the "No" option is listed first
+ * so the default cursor position is the safe one.
+ */
+export async function selectBoolean({ prompter, message, yesLabel, noLabel, yesHint, noHint, noFirst, }) {
+    const yes = { value: true, label: yesLabel, hint: yesHint };
+    const no = { value: false, label: noLabel, hint: noHint };
+    return prompter.select({
+        message,
+        options: noFirst ? [no, yes] : [yes, no],
+    });
+}
+//# sourceMappingURL=selectBoolean.js.map

package/build/setup/ui/selectBoolean.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectBoolean.js","sourceRoot":"","sources":["../../../src/setup/ui/selectBoolean.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAClC,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,OAAO,EACP,OAAO,EACP,MAAM,EACN,OAAO,GACW;IAClB,MAAM,GAAG,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC5D,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1D,OAAO,QAAQ,CAAC,MAAM,CAAU;QAC9B,OAAO;QACP,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC;KACzC,CAAC,CAAC;AACL,CAAC"}

package/build/setup/util/gitignoreCoverage.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Gitignore coverage check + banner append for setup's hand-off files.
+ *
+ * Coverage is evaluated with the `ignore` package against the existing
+ * patterns — never a naive substring search — so a pattern like `.env*`
+ * already covers `.env.phoenix` and nothing is appended.
+ */
+export declare const GITIGNORE_BANNER = "# Added by px setup \u2014 local Phoenix credentials";
+export interface EnsureGitignoredArgs {
+    /** Directory containing (or to contain) the .gitignore file. */
+    directory: string;
+    /** Bare filenames (relative to `directory`) that must be ignored. */
+    filenames: string[];
+    /** When false (not a git repo), no .gitignore is created or modified. */
+    isGitRepository: boolean;
+}
+export interface EnsureGitignoredResult {
+    /** Names that were appended (empty when everything was already covered). */
+    appended: string[];
+    /** Path to the .gitignore that was modified, when a write happened. */
+    gitignorePath?: string;
+}
+export declare function ensureGitignored({ directory, filenames, isGitRepository, }: EnsureGitignoredArgs): EnsureGitignoredResult;
+//# sourceMappingURL=gitignoreCoverage.d.ts.map

package/build/setup/util/gitignoreCoverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignoreCoverage.d.ts","sourceRoot":"","sources":["../../../src/setup/util/gitignoreCoverage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,eAAO,MAAM,gBAAgB,yDACsB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,yEAAyE;IACzE,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,EAC/B,SAAS,EACT,SAAS,EACT,eAAe,GAChB,EAAE,oBAAoB,GAAG,sBAAsB,CAmC/C"}

package/build/setup/util/gitignoreCoverage.js

@@ -0,0 +1,43 @@
+/**
+ * Gitignore coverage check + banner append for setup's hand-off files.
+ *
+ * Coverage is evaluated with the `ignore` package against the existing
+ * patterns — never a naive substring search — so a pattern like `.env*`
+ * already covers `.env.phoenix` and nothing is appended.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import ignore from "ignore";
+export const GITIGNORE_BANNER = "# Added by px setup — local Phoenix credentials";
+export function ensureGitignored({ directory, filenames, isGitRepository, }) {
+    const gitignorePath = path.join(directory, ".gitignore");
+    const exists = fs.existsSync(gitignorePath);
+    // No .gitignore and not a repo → skip silently.
+    if (!exists && !isGitRepository) {
+        return { appended: [] };
+    }
+    const existingContent = exists ? fs.readFileSync(gitignorePath, "utf-8") : "";
+    const matcher = ignore().add(existingContent);
+    const uncovered = filenames.filter((name) => !matcher.ignores(name));
+    if (uncovered.length === 0) {
+        return { appended: [] };
+    }
+    const banner = [GITIGNORE_BANNER, ...uncovered].join("\n");
+    let updated;
+    if (existingContent === "") {
+        updated = `${banner}\n`;
+    }
+    else if (existingContent.endsWith("\n")) {
+        updated = `${existingContent}\n${banner}\n`;
+    }
+    else {
+        // File didn't end with a newline — terminate the last line, then a
+        // blank separator line before the banner.
+        updated = `${existingContent}\n\n${banner}\n`;
+    }
+    // Exactly one trailing newline.
+    updated = `${updated.replace(/\n+$/, "")}\n`;
+    fs.writeFileSync(gitignorePath, updated, "utf-8");
+    return { appended: uncovered, gitignorePath };
+}
+//# sourceMappingURL=gitignoreCoverage.js.map

package/build/setup/util/gitignoreCoverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignoreCoverage.js","sourceRoot":"","sources":["../../../src/setup/util/gitignoreCoverage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,MAAM,CAAC,MAAM,gBAAgB,GAC3B,iDAAiD,CAAC;AAkBpD,MAAM,UAAU,gBAAgB,CAAC,EAC/B,SAAS,EACT,SAAS,EACT,eAAe,GACM;IACrB,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IAE5C,gDAAgD;IAChD,IAAI,CAAC,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;QAChC,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC1B,CAAC;IAED,MAAM,eAAe,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE9E,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC1B,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,gBAAgB,EAAE,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE3D,IAAI,OAAe,CAAC;IACpB,IAAI,eAAe,KAAK,EAAE,EAAE,CAAC;QAC3B,OAAO,GAAG,GAAG,MAAM,IAAI,CAAC;IAC1B,CAAC;SAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,OAAO,GAAG,GAAG,eAAe,KAAK,MAAM,IAAI,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,mEAAmE;QACnE,0CAA0C;QAC1C,OAAO,GAAG,GAAG,eAAe,OAAO,MAAM,IAAI,CAAC;IAChD,CAAC;IAED,gCAAgC;IAChC,OAAO,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC;IAE7C,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAClD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;AAChD,CAAC"}

package/build/setup/util/paths.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Path humanization for setup output: cwd-relative if under cwd, else
+ * ~/-relative, else basename.
+ */
+export declare function humanizePath(target: string, cwd: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/build/setup/util/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/setup/util/paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAehE"}

package/build/setup/util/paths.js

@@ -0,0 +1,23 @@
+/**
+ * Path humanization for setup output: cwd-relative if under cwd, else
+ * ~/-relative, else basename.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+export function humanizePath(target, cwd) {
+    const absolute = path.resolve(cwd, target);
+    const cwdRelative = path.relative(cwd, absolute);
+    if (cwdRelative && !cwdRelative.startsWith("..")) {
+        return cwdRelative;
+    }
+    if (cwdRelative === "") {
+        return ".";
+    }
+    const home = os.homedir();
+    const homeRelative = path.relative(home, absolute);
+    if (homeRelative && !homeRelative.startsWith("..")) {
+        return `~/${homeRelative}`;
+    }
+    return path.basename(absolute);
+}
+//# sourceMappingURL=paths.js.map

package/build/setup/util/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/setup/util/paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,GAAW;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC3C,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACjD,IAAI,WAAW,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACnD,IAAI,YAAY,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,KAAK,YAAY,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/build/setup/util/redact.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Secret scrubbing for all surfaced subprocess / HTTP error text.
+ * Applied before anything from an external process or response body reaches
+ * the terminal.
+ */
+export declare function redact(text: string): string;
+/**
+ * Redact then truncate for display. All error text from probes, HTTP
+ * responses, and subprocesses goes through this before being shown.
+ */
+export declare function redactForDisplay(text: string): string;
+//# sourceMappingURL=redact.d.ts.map

package/build/setup/util/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/setup/util/redact.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM3C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMrD"}