@get-dx/cli 0.1.0

package/dist/commands/studio/query.js

@@ -0,0 +1,270 @@
+import { once } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+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 { buildRuntime } from "../../runtime.js";
+import * as ui from "../../ui.js";
+import { QueryProgressReporter, renderCsvSaved, renderQueryResultsTable, } from "./queryRendering.js";
+const DEFAULT_RETRY_AFTER_MS = 1000;
+const PENDING_QUERY_RUN_STATUSES = new Set([
+    "queued",
+    "started",
+    "running",
+]);
+export function queryCommand() {
+    return new Command()
+        .name("query")
+        .description("Execute a Data Studio SQL query and wait for the results")
+        .argument("<sql>", "SQL query to execute")
+        .option("--output <filename>", "Save the full result set as CSV to a file")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Run a query and print the results as a table",
+            command: "dx studio query 'SELECT * FROM github_pulls LIMIT 10'",
+        },
+        {
+            label: "Run a query and print the JSON results payload",
+            command: "dx studio query 'SELECT id, name FROM github_repos LIMIT 5' --json",
+        },
+        {
+            label: "Run a query and save the full result set as CSV",
+            command: "dx studio query 'SELECT * FROM github_pulls' --output pulls.csv",
+        },
+    ]))
+        .action(wrapAction(async (sql, options, command) => {
+        const context = getContext(command);
+        if (context.json && options.output) {
+            throw new CliError("--output cannot be used with --json", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = buildRuntime(context);
+        const progress = new QueryProgressReporter();
+        const queryRun = await executeQuery(runtime, progress, sql);
+        await waitForQuery(runtime, progress, queryRun.id);
+        if (options.output) {
+            await downloadStudioQueryResultsCsv(runtime, queryRun.id, options.output);
+            renderCsvSaved(path.resolve(options.output));
+            return;
+        }
+        const response = await getStudioQueryResults(runtime, queryRun.id);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderQueryResultsTable(response.results);
+        }
+    }));
+}
+async function executeQuery(runtime, progress, sql) {
+    try {
+        renderRunningQuery(sql);
+        progress.start(ui.bold("Submitting query"));
+        const executeResponse = await executeStudioQuery(runtime, sql);
+        const queryRun = executeResponse.body.query_run;
+        await waitForRetryAfter(executeResponse.retryAfterMs);
+        return queryRun;
+    }
+    catch (error) {
+        progress.stop();
+        throw error;
+    }
+}
+async function waitForQuery(runtime, progress, queryRunId) {
+    while (true) {
+        let retryAfterMs;
+        try {
+            const infoResponse = await getStudioQueryRun(runtime, queryRunId);
+            const queryRun = infoResponse.body.query_run;
+            retryAfterMs = infoResponse.retryAfterMs;
+            if (queryRun.status === "succeeded") {
+                progress.stop(`${ui.success(ui.GLYPHS.CHECK)} Query completed.`);
+                return queryRun;
+            }
+            if (queryRun.status === "failed") {
+                progress.stop(`${ui.error(ui.GLYPHS.ERROR)} Query failed.`);
+                throw buildFailedQueryError(queryRun.error);
+            }
+            if (queryRun.status === "expired") {
+                progress.stop(`${ui.warning(ui.GLYPHS.WARNING)} Query expired.`);
+                throw new CliError(`Query results expired on ${queryRun.expires_at}.`, EXIT_CODES.RETRY_RECOMMENDED);
+            }
+            if (!PENDING_QUERY_RUN_STATUSES.has(queryRun.status)) {
+                progress.stop(`${ui.error(ui.GLYPHS.ERROR)} Query failed.`);
+                throw new CliError(`Unexpected query status: ${queryRun.status}`, 1);
+            }
+            progress.update(renderPendingQueryStatus(queryRun.id));
+            await waitForRetryAfter(retryAfterMs);
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.status === 429) {
+                progress.update(`${ui.warning(ui.GLYPHS.WARNING)} Polling too quickly; retrying ${ui.dim(`(${queryRunId})`)}`);
+                await waitForRetryAfter(retryAfterMs);
+                continue;
+            }
+            progress.stop(`${ui.error(ui.GLYPHS.ERROR)} Query failed.`);
+            throw error;
+        }
+    }
+}
+function renderRunningQuery(sql) {
+    process.stderr.write(`${ui.bold("Running:")} ${ui.code(sql)}\n`);
+}
+function renderPendingQueryStatus(queryRunId) {
+    return `${ui.bold("Query running")} ${ui.dim(`(${queryRunId})`)}`;
+}
+async function executeStudioQuery(runtime, sql) {
+    return request(runtime, "/studio.queryRuns.execute", {
+        method: "POST",
+        body: { sql },
+    });
+}
+async function getStudioQueryRun(runtime, id) {
+    return request(runtime, "/studio.queryRuns.info", {
+        method: "GET",
+        query: { id },
+    });
+}
+async function getStudioQueryResults(runtime, id) {
+    const response = await request(runtime, "/studio.queryRuns.results", {
+        method: "GET",
+        query: { id },
+    });
+    return response.body;
+}
+async function downloadStudioQueryResultsCsv(runtime, id, filename) {
+    const response = await fetchWithApiHeaders(runtime, `${runtime.baseUrl}/studio.queryRuns.results?id=${encodeURIComponent(id)}&format=csv`, { redirect: "manual" });
+    if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get("location");
+        if (!location) {
+            throw new HttpError("CSV download redirect did not include a Location header.", response.status);
+        }
+        const downloadResponse = await fetchResponse(new URL(location, runtime.baseUrl).toString(), {
+            method: "GET",
+            headers: buildDownloadHeaders(runtime, "text/csv"),
+        });
+        await ensureOkResponse(downloadResponse);
+        await writeResponseBodyToFile(downloadResponse, filename);
+        return;
+    }
+    await ensureOkResponse(response);
+    await writeResponseBodyToFile(response, filename);
+}
+function buildHeaders(runtime, accept) {
+    const headers = new Headers({
+        Accept: accept,
+        "User-Agent": `dx-cli/${runtime.version}`,
+    });
+    headers.set("Authorization", `Bearer ${runtime.token}`);
+    if (runtime.context.agent) {
+        headers.set("X-DX-Agent-Name", runtime.context.agent);
+    }
+    if (runtime.context.agentSessionId) {
+        headers.set("X-DX-Agent-Session-Id", runtime.context.agentSessionId);
+    }
+    return headers;
+}
+function buildDownloadHeaders(runtime, accept) {
+    return new Headers({
+        Accept: accept,
+        "User-Agent": `dx-cli/${runtime.version}`,
+    });
+}
+async function fetchWithApiHeaders(runtime, url, options = {}) {
+    return fetchResponse(url, {
+        method: "GET",
+        headers: buildHeaders(runtime, "text/csv"),
+        ...options,
+    });
+}
+async function fetchResponse(url, init) {
+    let response;
+    try {
+        response = await fetch(url, init);
+    }
+    catch (error) {
+        throw new HttpError(`Request failed: ${error.message}`);
+    }
+    return response;
+}
+async function ensureOkResponse(response) {
+    if (response.ok) {
+        return;
+    }
+    const body = await parseResponseBody(response);
+    const message = extractErrorMessage(body) ||
+        `Request failed with status ${response.status}`;
+    throw new HttpError(message, response.status, body);
+}
+async function parseResponseBody(response) {
+    return parseResponseText(await response.text());
+}
+function extractErrorMessage(body) {
+    if (!body || typeof body !== "object") {
+        return null;
+    }
+    const record = body;
+    if (record.error_details &&
+        typeof record.error_details === "object" &&
+        typeof record.error_details.message ===
+            "string") {
+        return record.error_details.message;
+    }
+    if (typeof record.error === "string") {
+        return record.error;
+    }
+    if (typeof record.message === "string") {
+        return record.message;
+    }
+    return null;
+}
+function parseResponseText(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function waitForRetryAfter(retryAfterMs) {
+    const delayMs = retryAfterMs ?? DEFAULT_RETRY_AFTER_MS;
+    await new Promise((resolve) => {
+        setTimeout(resolve, delayMs);
+    });
+}
+async function writeResponseBodyToFile(response, filename) {
+    if (!response.body) {
+        fs.writeFileSync(filename, "");
+        return;
+    }
+    const output = fs.createWriteStream(filename);
+    const reader = response.body.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (value && !output.write(Buffer.from(value))) {
+                await once(output, "drain");
+            }
+        }
+        output.end();
+        await once(output, "close");
+    }
+    catch (error) {
+        output.destroy();
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function buildFailedQueryError(error) {
+    if (!error) {
+        return new CliError("Query failed.", 1);
+    }
+    return new CliError(`Query failed (${error.code}): ${error.message}`, 1);
+}

package/dist/commands/studio/queryRendering.js

@@ -0,0 +1,99 @@
+import { clearLine, cursorTo } from "node:readline";
+import { renderRichText } from "../../renderers.js";
+import * as ui from "../../ui.js";
+export function renderQueryResultsTable(results) {
+    renderRichText([ui.p(formatAsciiTable(results.columns, results.rows))]);
+}
+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)";
+    }
+    const normalizedRows = rows.map((row) => columns.map((_, index) => formatCell(row[index])));
+    const widths = columns.map((column, index) => Math.max(column.length, ...normalizedRows.map((row) => row[index]?.length ?? 0)));
+    const border = `+${widths.map((width) => "-".repeat(width + 2)).join("+")}+`;
+    const header = `| ${columns.map((column, index) => column.padEnd(widths[index])).join(" | ")} |`;
+    const body = normalizedRows.map((row) => `| ${row.map((cell, index) => cell.padEnd(widths[index])).join(" | ")} |`);
+    return [border, header, border, ...body, border].join("\n");
+}
+function formatCell(value) {
+    if (value === null) {
+        return "NULL";
+    }
+    if (value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return sanitizeCell(value);
+    }
+    if (typeof value === "number" ||
+        typeof value === "bigint" ||
+        typeof value === "boolean") {
+        return String(value);
+    }
+    return sanitizeCell(JSON.stringify(value) ?? String(value));
+}
+function sanitizeCell(value) {
+    return value.replace(/\r?\n/g, "\\n").replace(/\t/g, " ");
+}

package/dist/commands/studio.js

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import { queryCommand } from "./studio/query.js";
+export function studioCommand() {
+    const studio = new Command()
+        .name("studio")
+        .description("Perform data studio actions");
+    studio.addCommand(queryCommand());
+    return studio;
+}

package/dist/config.js

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_BASE_URL = "https://api.getdx.com";
+export function getConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg) {
+        return path.join(xdg, "dx");
+    }
+    return path.join(os.homedir(), ".config", "dx");
+}
+export function getConfigPath() {
+    return path.join(getConfigDir(), "config.json");
+}
+export function readConfig() {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return {};
+    }
+    const content = fs.readFileSync(configPath, "utf8");
+    return JSON.parse(content);
+}
+export function writeConfig(config) {
+    fs.mkdirSync(getConfigDir(), { recursive: true });
+    fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+export function resolveBaseUrl() {
+    if (process.env.DX_BASE_URL) {
+        return normalizeBaseUrl(process.env.DX_BASE_URL);
+    }
+    return normalizeBaseUrl(readConfig().baseUrl || DEFAULT_BASE_URL);
+}
+export function persistBaseUrl(baseUrl) {
+    writeConfig({ ...readConfig(), baseUrl: normalizeBaseUrl(baseUrl) });
+}
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+export const EXIT_CODES = {
+    OK: 0,
+    ARGUMENT_ERROR: 2,
+    AUTHENTICATION_ERROR: 3,
+    RETRY_RECOMMENDED: 4,
+};
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT_CODES.RETRY_RECOMMENDED) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}
+export class HttpError extends CliError {
+    status;
+    body;
+    constructor(message, status, body, exitCode = 1) {
+        super(message, exitCode);
+        this.name = "HttpError";
+        this.status = status;
+        this.body = body;
+    }
+}

package/dist/http.js

@@ -0,0 +1,128 @@
+import { HttpError } from "./errors.js";
+export async function request(runtime, route, options = {}) {
+    const method = options.method || "GET";
+    const headers = new Headers({
+        Accept: "application/json",
+        "X-Client-Type": "dx-cli",
+        "X-Client-Version": runtime.version,
+        "User-Agent": `dx-cli/${runtime.version}`,
+    });
+    headers.set("Authorization", `Bearer ${runtime.token}`);
+    if (options.body !== undefined) {
+        headers.set("Content-Type", "application/json");
+    }
+    if (runtime.context.agent) {
+        headers.set("X-DX-Agent-Name", runtime.context.agent);
+    }
+    if (runtime.context.agentSessionId) {
+        headers.set("X-DX-Agent-Session-Id", runtime.context.agentSessionId);
+    }
+    const query = new URLSearchParams();
+    Object.entries(options.query || {}).forEach(([key, value]) => {
+        if (value !== undefined) {
+            query.set(key, String(value));
+        }
+    });
+    const url = `${runtime.baseUrl}${route}${query.size > 0 ? `?${query.toString()}` : ""}`;
+    const requestBody = options.body !== undefined ? JSON.stringify(options.body) : undefined;
+    runtime.logger.debug("Sending HTTP request", {
+        body: options.body ?? null,
+        headers: redactHeaders(headers),
+        method,
+        url,
+    });
+    let response;
+    try {
+        response = await fetch(url, {
+            method,
+            headers,
+            body: requestBody,
+        });
+    }
+    catch (error) {
+        throw new HttpError(`Request failed: ${error.message}`);
+    }
+    const responseBodyText = await response.text();
+    const parsedResponseBody = parseResponseBody(responseBodyText);
+    runtime.logger.debug("Received HTTP response", {
+        body: parsedResponseBody,
+        headers: headersToObject(response.headers),
+        method,
+        status: response.status,
+        url,
+    });
+    if (!response.ok) {
+        const message = extractErrorMessage(parsedResponseBody) ||
+            `Request failed with status ${response.status}`;
+        throw new HttpError(message, response.status, parsedResponseBody);
+    }
+    if (typeof parsedResponseBody === "string" &&
+        parsedResponseBody === responseBodyText) {
+        throw new HttpError("Invalid JSON response: Unexpected token");
+    }
+    const retryAfterMs = parseRetryAfterMs(response.headers);
+    const body = parsedResponseBody;
+    return retryAfterMs === undefined ? { body } : { body, retryAfterMs };
+}
+export function parseRetryAfterMs(headers) {
+    const retryAfter = headers.get("retry-after");
+    if (!retryAfter) {
+        return undefined;
+    }
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.ceil(seconds * 1000);
+    }
+    const retryAt = Date.parse(retryAfter);
+    if (Number.isNaN(retryAt)) {
+        return undefined;
+    }
+    return Math.max(0, retryAt - Date.now());
+}
+function extractErrorMessage(body) {
+    if (!body || typeof body !== "object") {
+        return null;
+    }
+    const record = body;
+    if (record.error_details &&
+        typeof record.error_details === "object" &&
+        typeof record.error_details.message ===
+            "string") {
+        return record.error_details.message;
+    }
+    if (typeof record.error === "string") {
+        return record.error;
+    }
+    if (typeof record.message === "string") {
+        return record.message;
+    }
+    return null;
+}
+function parseResponseBody(bodyText) {
+    try {
+        return JSON.parse(bodyText);
+    }
+    catch {
+        return bodyText;
+    }
+}
+function redactHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        result[key] =
+            key.toLowerCase() === "authorization"
+                ? redactAuthorization(value)
+                : value;
+    });
+    return result;
+}
+function redactAuthorization(value) {
+    return value.replace(/^Bearer\s+.+$/i, "Bearer [REDACTED]");
+}
+function headersToObject(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+await run();

package/dist/logger.js

@@ -0,0 +1,70 @@
+const LOG_LEVELS = ["debug", "info", "warn", "error"];
+const LOG_LEVEL_PRIORITY = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+export function createLogger(options) {
+    const configuredLevel = parseLogLevel(process.env.DX_LOG_LEVEL);
+    if (!configuredLevel) {
+        return createNoopLogger();
+    }
+    return {
+        debug(message, fields) {
+            writeLog(configuredLevel, options, "debug", message, fields);
+        },
+        info(message, fields) {
+            writeLog(configuredLevel, options, "info", message, fields);
+        },
+        warn(message, fields) {
+            writeLog(configuredLevel, options, "warn", message, fields);
+        },
+        error(message, fields) {
+            writeLog(configuredLevel, options, "error", message, fields);
+        },
+    };
+}
+export function parseLogLevel(value) {
+    if (!value) {
+        return null;
+    }
+    const normalized = value.toLowerCase();
+    if (LOG_LEVELS.includes(normalized)) {
+        return normalized;
+    }
+    return null;
+}
+function createNoopLogger() {
+    const noop = () => { };
+    return {
+        debug: noop,
+        error: noop,
+        info: noop,
+        warn: noop,
+    };
+}
+function writeLog(configuredLevel, options, level, message, fields) {
+    if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[configuredLevel]) {
+        return;
+    }
+    const entry = {
+        fields,
+        level,
+        message,
+        time: new Date().toISOString(),
+    };
+    if (options.json) {
+        process.stderr.write(JSON.stringify({
+            time: entry.time,
+            level: entry.level,
+            message: entry.message,
+            ...(entry.fields ?? {}),
+        }) + "\n");
+        return;
+    }
+    const renderedFields = entry.fields && Object.keys(entry.fields).length > 0
+        ? ` ${JSON.stringify(entry.fields)}`
+        : "";
+    process.stderr.write(`${entry.time} ${entry.level.toUpperCase()} ${entry.message}${renderedFields}\n`);
+}

package/dist/renderers.js

@@ -0,0 +1,29 @@
+/**
+ * Render an object in plain JSON formatting.
+ *
+ * Should be used when the `--flag` is present.
+ */
+export function renderJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+/**
+ * Render rich text to the terminal.
+ *
+ * Should be used when the `--flag` is NOT present.
+ */
+export function renderRichText(blocks) {
+    const normalizedBlocks = blocks
+        .filter((block) => block !== null)
+        .flatMap((block) => {
+        if (Array.isArray(block)) {
+            return block;
+        }
+        return [block];
+    });
+    const renderedBlocks = [];
+    for (const block of normalizedBlocks) {
+        const blockContent = block.render();
+        renderedBlocks.push(blockContent);
+    }
+    process.stdout.write(renderedBlocks.join("\n"));
+}

package/dist/runtime.js

@@ -0,0 +1,22 @@
+import { resolveBaseUrl } from "./config.js";
+import { CliError } from "./errors.js";
+import { getToken } from "./secrets.js";
+import { createLogger } from "./logger.js";
+import cliPackage from "../package.json" with { type: "json" };
+export function buildLogger(context) {
+    return createLogger({ json: context.json || !process.stderr.isTTY });
+}
+export function buildRuntime(context) {
+    const baseUrl = resolveBaseUrl();
+    const token = getToken(baseUrl);
+    if (!token) {
+        throw new CliError("No API token configured. Run `dx auth login --token <token>` or set DX_API_TOKEN.");
+    }
+    return {
+        baseUrl,
+        token,
+        context,
+        version: cliPackage.version,
+        logger: buildLogger(context),
+    };
+}