@get-dx/cli 0.1.6 → 0.2.0

package/README.md

@@ -18,6 +18,26 @@ Interactively login and install the AI agent skill:
 dx init
 ```
 
+The CLI uses `app.getdx.com` as the hostname and `api.getdx.com` as the api base url by default.
+
+### Dedicated or managed deployments
+
+If your organization is on a dedicated or managed DX deployment, pass your custom hostname at init time:
+
+```shell
+# Flag (dedicated instance at mycompany.getdx.io)
+dx init --host mycompany.getdx.io
+
+# Env var — useful for CI or scripted setups
+DX_HOST=mycompany.getdx.io dx init
+```
+
+The `DX_HOST` and `--host` values accept:
+
+- `app.getdx.com` — DX Cloud (default)
+- `<account>.getdx.io` — DX dedicated (derives `https://api.<account>.getdx.io` automatically)
+- Any custom domain — you will be prompted for the separate API base URL
+
 Show help text:
 
 ```shell

package/dist/authCodeCallbackServer.js

@@ -0,0 +1,79 @@
+import { createServer } from "node:http";
+import { CliError } from "./errors.js";
+export class AuthCodeCallbackServer {
+    server = null;
+    address = null;
+    async start() {
+        await new Promise((resolve, reject) => {
+            const srv = createServer();
+            srv.on("error", reject);
+            srv.listen(0, "127.0.0.1", () => {
+                this.server = srv;
+                const { address, port } = srv.address();
+                this.address = `http://${address}:${port}`;
+                resolve();
+            });
+        });
+    }
+    getAddress() {
+        if (!this.address) {
+            throw new Error("Unreachable: server not started");
+        }
+        return this.address;
+    }
+    async listenForCode(onCodeReceipt) {
+        return new Promise((resolve, reject) => {
+            if (!this.server) {
+                reject(new Error("Unreachable: server not started"));
+                return;
+            }
+            this.server.on("request", async (req, res) => {
+                this.stop();
+                const url = new URL(req.url ?? "/", this.address);
+                const code = url.searchParams.get("code");
+                const state = url.searchParams.get("state");
+                if (!code) {
+                    const message = "Authentication failed: no code received";
+                    res.writeHead(500, { "Content-Type": "text/plain" }).end(message);
+                    resolve({ type: "ERROR", error: new CliError(message) });
+                    return;
+                }
+                let result;
+                try {
+                    result = await onCodeReceipt(state ?? "", code);
+                }
+                catch (err) {
+                    const message = err instanceof Error
+                        ? err.message
+                        : "Authentication failed: unknown error";
+                    res.writeHead(500, { "Content-Type": "text/plain" }).end(message);
+                    resolve({
+                        type: "ERROR",
+                        error: err instanceof Error ? err : new CliError(message),
+                    });
+                    return;
+                }
+                if (result.type === "SUCCESS") {
+                    if (result.redirectUri) {
+                        res.writeHead(302, { Location: result.redirectUri }).end();
+                    }
+                    else {
+                        res
+                            .writeHead(200, { "Content-Type": "text/plain" })
+                            .end("Authentication successful");
+                    }
+                }
+                else {
+                    res
+                        .writeHead(500, { "Content-Type": "text/plain" })
+                        .end(result.error.message);
+                }
+                resolve(result);
+            });
+        });
+    }
+    stop() {
+        this.server?.close();
+        this.server = null;
+    }
+}

package/dist/commandHelpers.js

@@ -1,3 +1,4 @@
+import pc from "picocolors";
 import { CommanderError } from "commander";
 import { CliError, EXIT_CODES, HttpError } from "./errors.js";
 export function getContext(command) {
@@ -56,14 +57,14 @@ export function handleError(error, command, argv) {
     }
     else {
         if (error instanceof HttpError) {
-            process.stderr.write(`The API returned an error with status code ${error.status}:\n\n${JSON.stringify(error.body, null, 2)}\n`);
+            process.stderr.write(pc.red(`The API returned an error with status code ${error.status}:\n\n${JSON.stringify(error.body, null, 2)}\n`));
         }
         else if (error instanceof CommanderError &&
             (error.code === "commander.help" || error.message === "(outputHelp)")) {
             // Commander already printed the relevant help text.
         }
         else {
-            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            process.stderr.write(pc.red(`${error instanceof Error ? error.message : String(error)}\n`));
         }
     }
     const exitCode = (() => {

package/dist/commands/auth.js

@@ -1,11 +1,13 @@
+import { password, select } from "@inquirer/prompts";
 import { Command } from "commander";
 import { deleteToken, setToken } from "../secrets.js";
 import { renderJson } from "../renderers.js";
 import { renderAuthInfo, renderLoggedOut } from "./authRendering.js";
-import { wrapAction } from "../commandHelpers.js";
-import { getContext } from "../commandHelpers.js";
-import { persistBaseUrl, resolveBaseUrl } from "../config.js";
+import { getContext, wrapAction } from "../commandHelpers.js";
+import { persistBaseUrl, resolveBaseUrl, resolveUiUrl } from "../config.js";
+import { CliError } from "../errors.js";
 import { request } from "../http.js";
+import { loginViaBrowser } from "../loginViaBrowser.js";
 import { buildLogger, buildRuntime } from "../runtime.js";
 import cliPackage from "../../package.json" with { type: "json" };
 import { maskToken } from "../ui.js";
@@ -15,25 +17,50 @@ export function authCommand() {
         .description("Manage DX authentication");
     auth
         .command("login")
-        .requiredOption("--token <token>", "Account web API token or personal access token")
+        .option("--token <token>", "Account web API token or personal access token. Omit this option to login interactively by web browser or pasting.")
         .action(wrapAction(async (commandOptions, command) => {
         const context = getContext(command);
         const baseUrl = resolveBaseUrl();
+        let token = commandOptions.token;
+        if (!token) {
+            if (!process.stdin.isTTY || !process.stderr.isTTY) {
+                throw new CliError("`dx auth login` without `--token` requires an interactive terminal; pass `--token` for non-interactive use");
+            }
+            const method = await select({
+                message: "How would you like to log in?",
+                choices: [
+                    { name: "Open browser", value: "browser" },
+                    { name: "Paste API token", value: "token" },
+                ],
+            });
+            if (method === "browser") {
+                token = await loginViaBrowser(resolveUiUrl(baseUrl));
+            }
+            else {
+                token = await password({
+                    message: "Paste your account web API token here:",
+                    mask: true,
+                });
+            }
+            if (!token) {
+                throw new CliError("Account web API token or personal access token is required");
+            }
+        }
         const runtime = {
             baseUrl,
-            token: commandOptions.token,
+            token,
             context,
             version: cliPackage.version,
             logger: buildLogger(context),
         };
         const response = await getAuthInfo(runtime);
         persistBaseUrl(baseUrl);
-        setToken(baseUrl, commandOptions.token);
+        setToken(baseUrl, token);
         if (context.json) {
             renderJson({ ...response, base_url: baseUrl });
             return;
         }
-        renderAuthInfo(response, commandOptions.token, baseUrl);
+        renderAuthInfo(response, token, baseUrl);
     }));
     auth.command("logout").action(wrapAction(async (_options, command) => {
         const context = getContext(command);

package/dist/commands/catalog/entitiesRendering.js

@@ -238,6 +238,9 @@ function propertyValueContent(identifier, value) {
         const matchText = value.match_count === 1 ? "match" : "matches";
         return `File matching rule: ${ui.code(value.status)} (${value.match_count} ${matchText})`;
     }
+    else if (isOpenApiSpec(value)) {
+        return `OpenAPI spec`;
+    }
     else if (isUrl(value)) {
         return ui.link(value);
     }
@@ -284,3 +287,11 @@ function isFileMatchingRule(value) {
         typeof value.status === "string" &&
         ["FOUND_MATCHES", "NO_MATCHES", "FILE_NOT_FOUND"].includes(value.status));
 }
+function isOpenApiSpec(value) {
+    // TODO: consider switching to zod
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value === "object" &&
+        "info" in value &&
+        "paths" in value);
+}

package/dist/commands/init.js

@@ -1,12 +1,13 @@
 import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { input, password, confirm } from "@inquirer/prompts";
+import { input, password, confirm, select } from "@inquirer/prompts";
 import { Command } from "commander";
 import { execa } from "execa";
 import { buildRuntime, buildRuntimeSafe } from "../runtime.js";
 import { getAuthInfo } from "./auth.js";
 import { renderAuthInfo } from "./authRendering.js";
+import { loginViaBrowser } from "../loginViaBrowser.js";
 import { getContext } from "../commandHelpers.js";
 import { wrapAction } from "../commandHelpers.js";
 import { renderRichText } from "../renderers.js";
@@ -50,12 +51,14 @@ export function initCommand() {
     const init = new Command()
         .name("init")
         .description("Initialize the DX CLI")
-        .action(wrapAction(async (_commandOptions, command) => {
+        .option("--host <hostname>", "DX hostname for dedicated or managed deployments (e.g. mycompany.getdx.io)")
+        .action(wrapAction(async (commandOptions, command) => {
         const context = getContext(command);
         let runtime = buildRuntimeSafe(context);
         ensureInteractive();
         showWelcomeBanner();
-        runtime = await ensureLoggedIn(runtime);
+        const host = commandOptions.host || process.env.DX_HOST;
+        runtime = await ensureLoggedIn(runtime, host);
         await optionallySetupSkill(runtime);
         renderRichText([
             ui.blankLine(),
@@ -72,7 +75,7 @@ function ensureInteractive() {
 function showWelcomeBanner() {
     renderRichText([ui.p(ui.success(WELCOME_BANNER))]);
 }
-async function ensureLoggedIn(runtime) {
+async function ensureLoggedIn(runtime, host) {
     renderRichText([ui.h1(`Checking if you are logged in...`), ui.blankLine()]);
     if (runtime) {
         let authInfo = null;
@@ -88,17 +91,9 @@ async function ensureLoggedIn(runtime) {
         }
     }
     renderRichText([ui.p(`You are not logged in yet.`), ui.blankLine()]);
-    let parsed = { type: "invalid" };
-    while (parsed.type === "invalid") {
-        const raw = await input({
-            message: "What is your DX hostname? (leave blank for app.getdx.com)",
-        });
-        parsed = parseHostname(raw);
-        if (parsed.type === "invalid") {
-            renderRichText([
-                ui.p(ui.error(`Could not recognise that hostname. Please try again.`)),
-            ]);
-        }
+    const parsed = host ? parseHostname(host) : { type: "cloud" };
+    if (parsed.type === "invalid") {
+        throw new CliError(`Could not recognize hostname "${host}". Expected app.getdx.com, <account>.getdx.io, or a custom domain.`);
     }
     switch (parsed.type) {
         case "cloud":
@@ -118,11 +113,24 @@ async function ensureLoggedIn(runtime) {
         }
     }
 }
-async function attemptLogin(apiBaseUrl, _uiBaseUrl) {
-    const token = await password({
-        message: "Paste your account web API token here:",
-        mask: true,
+async function attemptLogin(apiBaseUrl, uiBaseUrl) {
+    const method = await select({
+        message: "How would you like to log in?",
+        choices: [
+            { name: "Open browser", value: "browser" },
+            { name: "Paste API token", value: "token" },
+        ],
     });
+    let token;
+    if (method === "browser") {
+        token = await loginViaBrowser(uiBaseUrl);
+    }
+    else {
+        token = await password({
+            message: "Paste your account web API token here:",
+            mask: true,
+        });
+    }
     if (!token) {
         throw new CliError("Account web API token is required");
     }

package/dist/commands/studio/query.js

@@ -5,10 +5,10 @@ import { Command } from "commander";
 import { createExampleText, getContext, wrapAction, } from "../../commandHelpers.js";
 import { CliError, EXIT_CODES, HttpError } from "../../errors.js";
 import { request } from "../../http.js";
-import { renderJson } from "../../renderers.js";
+import { AsyncProgressReporter, renderJson, renderRichText, } from "../../renderers.js";
 import { buildRuntime } from "../../runtime.js";
 import * as ui from "../../ui.js";
-import { QueryProgressReporter, renderCsvSaved, renderQueryResultsTable, } from "./queryRendering.js";
+import { renderCsvSaved, renderQueryResultsTable } from "./queryRendering.js";
 const DEFAULT_RETRY_AFTER_MS = 1000;
 const PENDING_QUERY_RUN_STATUSES = new Set([
     "queued",
@@ -51,7 +51,7 @@ export function queryCommand() {
         }
         const variables = parseVariables(options.variable);
         const runtime = buildRuntime(context);
-        const progress = new QueryProgressReporter();
+        const progress = new AsyncProgressReporter();
         const queryRun = await executeQuery(runtime, progress, sql, variables);
         await waitForQuery(runtime, progress, queryRun.id);
         if (options.output) {
@@ -70,7 +70,9 @@ export function queryCommand() {
 }
 async function executeQuery(runtime, progress, sql, variables) {
     try {
-        renderRunningQuery(sql);
+        renderRichText([ui.p(`${ui.bold("Running:")} ${ui.code(sql)}`)], {
+            useStderr: true,
+        });
         progress.start(ui.bold("Submitting query"));
         const executeResponse = await executeStudioQuery(runtime, sql, variables);
         const queryRun = executeResponse.body.query_run;
@@ -119,9 +121,6 @@ async function waitForQuery(runtime, progress, queryRunId) {
         }
     }
 }
-function renderRunningQuery(sql) {
-    process.stderr.write(`${ui.bold("Running:")} ${ui.code(sql)}\n`);
-}
 function renderPendingQueryStatus(queryRunId) {
     return `${ui.bold("Query running")} ${ui.dim(`(${queryRunId})`)}`;
 }

package/dist/commands/studio/queryRendering.js

@@ -1,4 +1,3 @@
-import { clearLine, cursorTo } from "node:readline";
 import { renderRichText } from "../../renderers.js";
 import * as ui from "../../ui.js";
 export function renderQueryResultsTable(results) {
@@ -7,65 +6,6 @@ export function renderQueryResultsTable(results) {
 export function renderCsvSaved(filename) {
     renderRichText([ui.p(`Saved CSV results to ${ui.code(filename)}.`)]);
 }
-export class QueryProgressReporter {
-    enabled = Boolean(process.stderr.isTTY);
-    frames = [
-        "⠋",
-        "⠙",
-        "⠹",
-        "⠸",
-        "⠼",
-        "⠴",
-        "⠦",
-        "⠧",
-        "⠇",
-        "⠏",
-    ].map((frame) => ui.dim(frame));
-    timer;
-    frameIndex = 0;
-    currentMessage = "";
-    start(message) {
-        if (!this.enabled) {
-            return;
-        }
-        this.currentMessage = message;
-        this.render();
-        this.timer = setInterval(() => this.render(), 80);
-        this.timer.unref?.();
-    }
-    update(message) {
-        if (!this.enabled) {
-            return;
-        }
-        this.currentMessage = message;
-        this.render();
-    }
-    stop(finalMessage) {
-        if (!this.enabled) {
-            return;
-        }
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = undefined;
-        }
-        if (finalMessage) {
-            this.clearCurrentLine();
-            process.stderr.write(`${finalMessage}\n`);
-            return;
-        }
-        this.clearCurrentLine();
-    }
-    render() {
-        const frame = this.frames[this.frameIndex % this.frames.length];
-        this.frameIndex += 1;
-        this.clearCurrentLine();
-        process.stderr.write(`${frame} ${this.currentMessage}`);
-    }
-    clearCurrentLine() {
-        clearLine(process.stderr, 0);
-        cursorTo(process.stderr, 0);
-    }
-}
 function formatAsciiTable(columns, rows) {
     if (columns.length === 0) {
         return "(Query returned no columns)";

package/dist/commands/teams.js

@@ -32,6 +32,36 @@ export function teamsCommand() {
             renderTeamByMembers(response.team);
         }
     }));
+    teams
+        .command("info")
+        .description("Retrieve details for an individual team")
+        .option("--team-id <id>", "DX team ID")
+        .option("--reference-id <id>", "Team ID that is internal to your organization")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Fetch info for a team by DX team ID",
+            command: "dx teams info --team-id NTA4Nzc",
+        },
+        {
+            label: "Fetch info for a team by your organization's reference ID",
+            command: "dx teams info --reference-id 06BEC4E0-5A61-354E-08A6-C39D756058AB",
+        },
+        {
+            label: "Fetch team info and return JSON",
+            command: "dx --json teams info --team-id NTA4Nzc",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const lookup = parseTeamInfoLookup(options);
+        const runtime = buildRuntime(getContext(command));
+        const response = await getTeamInfo(runtime, lookup);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderTeamInfo(response.team);
+        }
+    }));
     teams
         .command("list")
         .description("List all teams in DX")
@@ -72,6 +102,13 @@ async function findTeamByMembers(runtime, teamEmails) {
         throw buildFindByMembersError(error, teamEmails);
     }
 }
+async function getTeamInfo(runtime, lookup) {
+    const response = await request(runtime, "/teams.info", {
+        method: "GET",
+        query: lookup,
+    });
+    return response.body;
+}
 async function listTeams(runtime) {
     const response = await request(runtime, "/teams.list", {
         method: "GET",
@@ -93,6 +130,31 @@ function renderTeamByMembers(team) {
     ];
     renderRichText(blocks);
 }
+function renderTeamInfo(team) {
+    const blocks = [ui.h1("Team Information")];
+    const heading = formatTeamHeading(team);
+    if (heading) {
+        blocks.push(ui.h2(heading));
+    }
+    const details = [];
+    pushDetail(details, "ID", formatText(team.id), team.id !== undefined);
+    pushDetail(details, "Name", team.name ?? ui.dim("(None)"), team.name !== undefined);
+    pushDetail(details, "Reference ID", formatText(team.reference_id), team.reference_id !== undefined);
+    pushDetail(details, "Parent ID", formatText(team.parent_id), team.parent_id !== undefined);
+    pushDetail(details, "Manager ID", formatText(team.manager_id), team.manager_id !== undefined);
+    pushDetail(details, "Parent team", typeof team.parent === "boolean" ? (team.parent ? "Yes" : "No") : "", team.parent !== undefined);
+    pushDetail(details, "Last changed", team.last_changed_at
+        ? ui.timestampSummary(team.last_changed_at)
+        : ui.dim("(None)"), team.last_changed_at !== undefined);
+    pushDetail(details, "Lead", formatTeamMember(team.lead), team.lead !== undefined);
+    pushDetail(details, "Manager", formatTeamMember(team.manager), team.manager !== undefined);
+    if (details.length > 0) {
+        blocks.push(ui.dl(details, { termWidth: 14 }));
+    }
+    blocks.push(ui.h2("Contributors"));
+    blocks.push(formatTeamMemberList(team.contributors));
+    renderRichText(blocks);
+}
 function renderTeams(teams) {
     const blocks = [ui.h1("Teams")];
     blocks.push(ui.p(`Displaying ${ui.bold(teams.length.toString())} teams.`));
@@ -123,12 +185,56 @@ function renderTeams(teams) {
 function formatText(value) {
     return value ? ui.code(value) : ui.dim("(None)");
 }
+function formatTeamHeading(team) {
+    if (team.name && team.id) {
+        return `${team.name} (${ui.code(team.id)})`;
+    }
+    if (team.name) {
+        return team.name;
+    }
+    if (team.id) {
+        return ui.code(team.id);
+    }
+    if (team.reference_id) {
+        return ui.code(team.reference_id);
+    }
+    return null;
+}
 function formatTeamMember(member) {
     if (!member) {
         return ui.dim("(None)");
     }
     return `${member.name} <${member.email}> (${ui.code(member.id)})`;
 }
+function formatTeamMemberList(members) {
+    if (!members || members.length === 0) {
+        return ui.p(ui.dim("(None)"));
+    }
+    return ui.ul(members.map((member) => ui.li(formatTeamMember(member))));
+}
+function pushDetail(details, term, value, shouldInclude) {
+    if (shouldInclude) {
+        details.push(ui.dli(term, value));
+    }
+}
+function parseTeamInfoLookup(options) {
+    const teamId = parseOptionalTextOption(options.teamId);
+    const referenceId = parseOptionalTextOption(options.referenceId);
+    if (!teamId && !referenceId) {
+        throw new CliError("One of --team-id or --reference-id is required", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    if (teamId && referenceId) {
+        throw new CliError("--team-id and --reference-id are mutually exclusive", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return teamId ? { team_id: teamId } : { reference_id: referenceId };
+}
+function parseOptionalTextOption(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
 function parseTeamEmails(value) {
     if (typeof value !== "string") {
         throw new CliError("--team-emails is required", EXIT_CODES.ARGUMENT_ERROR);

package/dist/config.js

@@ -30,6 +30,23 @@ export function resolveBaseUrl() {
     }
     return normalizeBaseUrl(readConfig().baseUrl || DEFAULT_BASE_URL);
 }
+/**
+ * Web UI origin for browser OAuth (`/cli/auth`), inferred from the API base URL.
+ * Dedicated and cloud hostnames map to their app origins; otherwise the API URL origin is used.
+ */
+export function resolveUiUrl(apiBaseUrl) {
+    const normalized = normalizeBaseUrl(apiBaseUrl);
+    const url = new URL(normalized);
+    const host = url.hostname;
+    if (host === "api.getdx.com") {
+        return "https://app.getdx.com";
+    }
+    const dedicated = host.match(/^api\.(.+)\.getdx\.io$/);
+    if (dedicated) {
+        return `https://${dedicated[1]}.getdx.io`;
+    }
+    return url.origin;
+}
 export function persistBaseUrl(baseUrl) {
     writeConfig({ ...readConfig(), baseUrl: normalizeBaseUrl(baseUrl) });
 }

package/dist/loginViaBrowser.js

@@ -0,0 +1,86 @@
+import { createHash, randomBytes } from "node:crypto";
+import open from "open";
+import { AuthCodeCallbackServer, } from "./authCodeCallbackServer.js";
+import { CliError } from "./errors.js";
+import { renderRichText } from "./renderers.js";
+import * as ui from "./ui.js";
+export async function loginViaBrowser(uiBaseUrl) {
+    const server = new AuthCodeCallbackServer();
+    await server.start();
+    const callbackUri = server.getAddress();
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    const state = generateState();
+    const params = new URLSearchParams({
+        callback_uri: callbackUri,
+        state,
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256",
+    });
+    const authUrl = `${uiBaseUrl}/cli/auth?${params.toString()}`;
+    renderRichText([
+        ui.p(`Opening your browser to complete authentication...`),
+        ui.blankLine(),
+    ]);
+    try {
+        await open(authUrl);
+    }
+    catch {
+        renderRichText([
+            ui.p(`Failed to open browser automatically. Visit this URL to continue:`),
+            ui.blankLine(),
+            ui.codeBlock(authUrl),
+            ui.blankLine(),
+        ]);
+    }
+    renderRichText([ui.p(`Waiting for authentication in your browser...`)]);
+    const handleCodeReceipt = async (stateFromResponse, code) => {
+        const valid = validateState(stateFromResponse, state);
+        if (!valid) {
+            return {
+                type: "ERROR",
+                error: new CliError("Authentication failed: state mismatch"),
+            };
+        }
+        const tokenExchangeResponse = await exchangeCodeForToken(uiBaseUrl, code, codeVerifier);
+        if (!tokenExchangeResponse.ok) {
+            return {
+                type: "ERROR",
+                error: new CliError(`Authentication failed: token exchange failed with status ${tokenExchangeResponse.status}`),
+            };
+        }
+        const body = (await tokenExchangeResponse.json());
+        return {
+            type: "SUCCESS",
+            token: body.access_token,
+            redirectUri: body.redirect_uri,
+        };
+    };
+    const serverResult = await server.listenForCode(handleCodeReceipt);
+    if (serverResult.type === "ERROR")
+        throw serverResult.error;
+    return serverResult.token;
+}
+function validateState(stateFromResponse, originalState) {
+    return stateFromResponse === originalState;
+}
+async function exchangeCodeForToken(baseUrl, code, codeVerifier) {
+    return fetch(`${baseUrl}/cli/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ code, code_verifier: codeVerifier }),
+    });
+}
+// RFC 8252 §8.9: random string used to prevent CSRF-style attacks
+function generateState() {
+    return randomBytes(16).toString("base64url");
+}
+// RFC 7636 §4.1 — 32 random bytes base64url-encoded = 43 unreserved chars
+function generateCodeVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+// RFC 7636 §4.2 — SHA256 hex digest, base64-encoded without padding
+function generateCodeChallenge(codeVerifier) {
+    const hexDigest = createHash("sha256").update(codeVerifier).digest("hex");
+    return Buffer.from(hexDigest).toString("base64").replace(/=/g, "");
+}

package/dist/renderers.js

@@ -1,3 +1,5 @@
+import { clearLine, cursorTo } from "node:readline";
+import { dim } from "./ui.js";
 /**
  * Render an object in plain JSON formatting.
  *
@@ -11,7 +13,7 @@ export function renderJson(value) {
  *
  * Should be used when the `--flag` is NOT present.
  */
-export function renderRichText(blocks) {
+export function renderRichText(blocks, options) {
     const normalizedBlocks = blocks
         .filter((block) => block !== null)
         .flatMap((block) => {
@@ -25,5 +27,78 @@ export function renderRichText(blocks) {
         const blockContent = block.render();
         renderedBlocks.push(blockContent);
     }
-    process.stdout.write(renderedBlocks.join("\n"));
+    if (options?.useStderr) {
+        process.stderr.write(renderedBlocks.join("\n"));
+    }
+    else {
+        process.stdout.write(renderedBlocks.join("\n"));
+    }
+}
+/**
+ * Renders a TTY spinner and status on stderr for long-running async work. Does not
+ * use `renderRichText` because stdout is reserved for command results; stderr keeps
+ * auxiliary output separate from the primary stream.
+ */
+export class AsyncProgressReporter {
+    enabled = Boolean(process.stderr.isTTY);
+    intervalMs;
+    frames = [
+        "⠋",
+        "⠙",
+        "⠹",
+        "⠸",
+        "⠼",
+        "⠴",
+        "⠦",
+        "⠧",
+        "⠇",
+        "⠏",
+    ].map((frame) => dim(frame));
+    timer;
+    frameIndex = 0;
+    currentMessage = "";
+    constructor(options) {
+        this.intervalMs = options?.intervalMs ?? 80;
+    }
+    start(message) {
+        if (!this.enabled) {
+            return;
+        }
+        this.currentMessage = message;
+        this.render();
+        this.timer = setInterval(() => this.render(), this.intervalMs);
+        this.timer.unref?.();
+    }
+    update(message) {
+        if (!this.enabled) {
+            return;
+        }
+        this.currentMessage = message;
+        this.render();
+    }
+    stop(finalMessage) {
+        if (!this.enabled) {
+            return;
+        }
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (finalMessage) {
+            this.clearCurrentLine();
+            process.stderr.write(`${finalMessage}\n`);
+            return;
+        }
+        this.clearCurrentLine();
+    }
+    render() {
+        const frame = this.frames[this.frameIndex % this.frames.length];
+        this.frameIndex += 1;
+        this.clearCurrentLine();
+        process.stderr.write(`${frame} ${this.currentMessage}`);
+    }
+    clearCurrentLine() {
+        clearLine(process.stderr, 0);
+        cursorTo(process.stderr, 0);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-dx/cli",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "DX CLI",
   "author": "DX <developers@getdx.com>",
   "bugs": {
@@ -42,6 +42,7 @@
     "commander": "^14.0.1",
     "dayjs": "^1.11.20",
     "execa": "^9.6.1",
+    "open": "^11.0.0",
     "picocolors": "^1.1.1",
     "yaml": "^2.8.3"
   },