@get-dx/cli 0.6.1 → 0.7.0

package/dist/cli.js

@@ -6,6 +6,7 @@ import { scorecardsCommand } from "./commands/scorecards.js";
 import { snapshotsCommand } from "./commands/snapshots.js";
 import { studioCommand } from "./commands/studio.js";
 import { teamsCommand } from "./commands/teams.js";
+import { usersCommand } from "./commands/users.js";
 import { workflowRunsCommand } from "./commands/workflowRuns.js";
 import { workflowsCommand } from "./commands/workflows.js";
 import { handleError } from "./commandHelpers.js";
@@ -54,6 +55,7 @@ function createProgram() {
     program.addCommand(snapshotsCommand());
     program.addCommand(studioCommand());
     program.addCommand(teamsCommand());
+    program.addCommand(usersCommand());
     program.addCommand(workflowRunsCommand());
     program.addCommand(workflowsCommand());
     applyExitOverride(program);

package/dist/commandHelpers.js

@@ -58,7 +58,7 @@ export function handleError(error, command, argv) {
     }
     else {
         if (error instanceof HttpError) {
-            process.stderr.write(pc.red(`The API returned an error with status code ${error.status}:\n\n${JSON.stringify(error.body, null, 2)}\n`));
+            process.stderr.write(pc.red(formatHttpError(error)));
         }
         else if (error instanceof CommanderError &&
             (error.code === "commander.help" || error.message === "(outputHelp)")) {
@@ -82,6 +82,39 @@ export function handleError(error, command, argv) {
     })();
     process.exit(exitCode);
 }
+/**
+ * `status` and `body` are only populated when the API actually answered.
+ * Network, TLS, and non-JSON failures carry their detail in `message` alone, so
+ * these helpers coalesce so we display full details.
+ */
+function formatHttpError(error) {
+    const heading = formatHttpErrorHeading(error);
+    const body = formatHttpErrorBody(error.body);
+    return body === null ? `${heading}\n` : `${heading}\n\n${body}\n`;
+}
+function formatHttpErrorHeading(error) {
+    if (error.status === undefined) {
+        return error.message;
+    }
+    // A successful or redirect status that still failed the request — an
+    // unparseable body, or a redirect missing its Location — isn't an error the
+    // API reported, so don't describe it as one.
+    if (error.status < 400) {
+        return `${error.message} (HTTP ${error.status})`;
+    }
+    return `The API returned an error with status code ${error.status}: ${error.message}`;
+}
+function formatHttpErrorBody(body) {
+    if (body === undefined || body === "") {
+        return null;
+    }
+    // Non-JSON bodies (proxy block pages, HTML error pages) are far more legible
+    // raw than as a JSON string literal full of escaped newlines.
+    if (typeof body === "string") {
+        return body;
+    }
+    return JSON.stringify(body, null, 2) ?? String(body);
+}
 function printJson(value) {
     process.stdout.write(JSON.stringify(value, null, 2) + "\n");
 }

package/dist/commands/studio/query.js

@@ -4,7 +4,7 @@ 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 { describeFetchFailure, request } from "../../http.js";
 import { AsyncProgressReporter, renderJson, renderRichText, } from "../../renderers.js";
 import { buildRuntime } from "../../runtime.js";
 import * as ui from "../../ui.js";
@@ -197,7 +197,7 @@ async function fetchResponse(url, init) {
         response = await fetch(url, init);
     }
     catch (error) {
-        throw new HttpError(`Request failed: ${error.message}`);
+        throw new HttpError(`Could not reach ${url}: ${describeFetchFailure(error)}`);
     }
     return response;
 }

package/dist/commands/users/linkableAccounts.js

@@ -0,0 +1,99 @@
+import { Command } from "commander";
+import { createExampleText, getContext, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
+import { CliError, EXIT_CODES } from "../../errors.js";
+import { requestWithMessages } from "../../http.js";
+import { renderJson, renderRichText } from "../../renderers.js";
+import { buildRuntime } from "../../runtime.js";
+import * as ui from "../../ui.js";
+import { SOURCES } from "./sources.js";
+export function linkableAccountsCommand() {
+    const linkableAccounts = new Command()
+        .name("linkableAccounts")
+        .description("Search accounts that can be linked to DX users");
+    linkableAccounts
+        .command("list")
+        .description("Search the accounts DX has imported from a source, and get the account IDs to pass to `dx users links` commands")
+        .requiredOption("--source <source>", `Source to search (${SOURCES})`)
+        .option("--query <query>", "Case-insensitive text to find in the account's name, email, or username")
+        .option("--external-id <id>", "Only return the account with this ID from the tool itself")
+        .option("--instance-id <id>", "Only return accounts from this instance, organization, workspace, or connection")
+        .option("--linked", "Only return accounts linked to a DX user")
+        .option("--unlinked", "Only return accounts not linked to a DX user")
+        .option("--page <n>", "Page number to return (default is 1)", (value) => parsePositiveIntOption(value, "--page"))
+        .option("--page-size <n>", "Max accounts per page (default and maximum is 100)", (value) => parsePositiveIntOption(value, "--page-size"))
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Search unlinked GitHub accounts matching a name",
+            command: "dx users linkableAccounts list --source github --query jane --unlinked",
+        },
+        {
+            label: "Find a Jira account by its Jira ID and return JSON",
+            command: "dx users linkableAccounts list --source jira --external-id 5b10ac8d82e05b22cc7d4ef5 --json",
+        },
+        {
+            label: "Fetch the next page of results",
+            command: "dx users linkableAccounts list --source github --page 2",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        if (options.linked && options.unlinked) {
+            throw new CliError("--linked and --unlinked are mutually exclusive", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listLinkableAccounts(runtime, {
+            source: options.source,
+            query: options.query,
+            external_id: options.externalId,
+            instance_id: options.instanceId,
+            linked: options.unlinked ? false : options.linked,
+            page: options.page,
+            page_size: options.pageSize,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderLinkableAccounts(response);
+        }
+    }));
+    return linkableAccounts;
+}
+const ERROR_MESSAGES = {
+    query_timeout: "The search timed out. Narrow it with --instance-id, --external-id, or a longer --query, then try again.",
+};
+async function listLinkableAccounts(runtime, params) {
+    return requestWithMessages(runtime, "/users.linkableAccounts.list", {
+        method: "GET",
+        query: params,
+    }, ERROR_MESSAGES);
+}
+function renderLinkableAccounts(response) {
+    const blocks = [ui.h1("Linkable Accounts")];
+    blocks.push(ui.p(`Displaying ${ui.bold(response.accounts.length.toString())} of ${ui.bold(response.total.toString())} accounts.`));
+    if (response.next_page) {
+        blocks.push(ui.p(`Next page: ${ui.code(response.next_page.toString())}`));
+    }
+    for (const account of response.accounts) {
+        blocks.push(ui.h2(`${account.label} (${ui.code(account.id)})`));
+        blocks.push(ui.dl([
+            ...accountDetailItems(account),
+            ui.dli("Linked user", account.linked_user_id
+                ? ui.code(account.linked_user_id)
+                : ui.dim("(Not linked)")),
+        ], { termWidth: 13 }));
+    }
+    renderRichText(blocks);
+}
+export function accountDetailItems(account) {
+    return [
+        ui.dli("Source", account.source),
+        ui.dli("External ID", formatCode(account.external_id)),
+        ui.dli("Instance ID", formatCode(account.instance_id)),
+        ui.dli("Name", account.name ?? ui.dim("(None)")),
+        ui.dli("Email", account.email ?? ui.dim("(None)")),
+        ui.dli("Username", account.username ?? ui.dim("(None)")),
+    ];
+}
+function formatCode(value) {
+    return value ? ui.code(value) : ui.dim("(None)");
+}

package/dist/commands/users/links.js

@@ -0,0 +1,205 @@
+import { Command } from "commander";
+import { createExampleText, getContext, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
+import { requestWithMessages } from "../../http.js";
+import { renderJson, renderRichText } from "../../renderers.js";
+import { buildRuntime } from "../../runtime.js";
+import * as ui from "../../ui.js";
+import { accountDetailItems } from "./linkableAccounts.js";
+import { SOURCES } from "./sources.js";
+export function linksCommand() {
+    const links = new Command()
+        .name("links")
+        .description("Manage the accounts linked to DX users");
+    links
+        .command("create")
+        .description("Link one account to a user, keeping the user's other linked accounts for that source")
+        .argument("<user-id>", "DX user ID")
+        .requiredOption("--source <source>", `Source the account comes from (${SOURCES})`)
+        .requiredOption("--account-id <id>", "Account ID to link, as returned by `dx users linkableAccounts list`")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Link a GitHub account to a user",
+            command: "dx users links create NTEyMDUw --source github --account-id 4812",
+        },
+        {
+            label: "Link an account and return JSON",
+            command: "dx users links create NTEyMDUw --source github --account-id 4812 --json",
+        },
+    ]))
+        .action(wrapAction(async (userId, options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await createLink(runtime, {
+            user_id: userId,
+            source: options.source,
+            account_id: options.accountId,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRichText([
+                ui.p(`${ui.success(ui.GLYPHS.CHECK)} Linked ${options.source} account ${ui.code(options.accountId)} to user ${ui.code(userId)}.`),
+            ]);
+        }
+    }));
+    links
+        .command("delete")
+        .description("Unlink one account from a user, keeping the user's other linked accounts for that source")
+        .argument("<user-id>", "DX user ID")
+        .requiredOption("--source <source>", `Source the account comes from (${SOURCES})`)
+        .requiredOption("--account-id <id>", "Account ID to unlink")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Unlink a GitHub account from a user",
+            command: "dx users links delete NTEyMDUw --source github --account-id 4812",
+        },
+        {
+            label: "Unlink an account and return JSON",
+            command: "dx users links delete NTEyMDUw --source github --account-id 4812 --json",
+        },
+    ]))
+        .action(wrapAction(async (userId, options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await deleteLink(runtime, {
+            user_id: userId,
+            source: options.source,
+            account_id: options.accountId,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRichText([
+                ui.p(`${ui.success(ui.GLYPHS.CHECK)} Unlinked ${options.source} account ${ui.code(options.accountId)} from user ${ui.code(userId)}.`),
+            ]);
+        }
+    }));
+    links
+        .command("list")
+        .description("List the accounts linked to a user")
+        .argument("<user-id>", "DX user ID")
+        .option("--source <source>", `Only return accounts from this source (${SOURCES})`)
+        .option("--page <n>", "Page number to return (default is 1)", (value) => parsePositiveIntOption(value, "--page"))
+        .option("--page-size <n>", "Max links per page (default and maximum is 100)", (value) => parsePositiveIntOption(value, "--page-size"))
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List every account linked to a user",
+            command: "dx users links list NTEyMDUw",
+        },
+        {
+            label: "List a user's GitHub accounts and return JSON",
+            command: "dx users links list NTEyMDUw --source github --json",
+        },
+        {
+            label: "Fetch the next page of links",
+            command: "dx users links list NTEyMDUw --page 2",
+        },
+    ]))
+        .action(wrapAction(async (userId, options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listLinks(runtime, {
+            user_id: userId,
+            source: options.source,
+            page: options.page,
+            page_size: options.pageSize,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderLinks(userId, response);
+        }
+    }));
+    links
+        .command("set")
+        .description("Replace every account linked to a user for one source. Accounts not in the list are unlinked.")
+        .argument("<user-id>", "DX user ID")
+        .requiredOption("--source <source>", `Source the accounts come from (${SOURCES})`)
+        .requiredOption("--account-ids <ids>", 'Comma-separated account IDs to link, up to 100. Pass "" to unlink every account for the source.')
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Link exactly these two GitHub accounts to a user",
+            command: "dx users links set NTEyMDUw --source github --account-ids 4812,4813",
+        },
+        {
+            label: "Unlink every GitHub account from a user",
+            command: 'dx users links set NTEyMDUw --source github --account-ids ""',
+        },
+        {
+            label: "Replace a user's Jira accounts and return JSON",
+            command: "dx users links set NTEyMDUw --source jira --account-ids 991 --json",
+        },
+    ]))
+        .action(wrapAction(async (userId, options, command) => {
+        const accountIds = options.accountIds
+            .split(",")
+            .map((id) => id.trim())
+            .filter((id) => id.length > 0);
+        const runtime = await buildRuntime(getContext(command));
+        const response = await setLinks(runtime, {
+            user_id: userId,
+            source: options.source,
+            account_ids: accountIds,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRichText([
+                ui.p(accountIds.length > 0
+                    ? `${ui.success(ui.GLYPHS.CHECK)} Set the ${options.source} accounts linked to user ${ui.code(userId)} to ${accountIds.map((id) => ui.code(id)).join(", ")}.`
+                    : `${ui.success(ui.GLYPHS.CHECK)} Unlinked every ${options.source} account from user ${ui.code(userId)}.`),
+            ]);
+        }
+    }));
+    return links;
+}
+const NOT_SYNCED = "This user hasn't synced to Data Cloud yet. Try again once their next sync finishes.";
+const ERROR_MESSAGES = {
+    link_update_in_progress: "Another link update for this user and source is still running. Try again in a few seconds.",
+    manual_link_conflict: "An account is manually linked to another user. Remove that link before linking it to this user.",
+    not_found: "The user or account wasn't found. Check the user ID, and look up account IDs with `dx users linkableAccounts list`.",
+    user_not_in_datacloud: NOT_SYNCED,
+    // users.links.set passes Data Cloud's own error string through instead of a code.
+    "User not found in datacloud": NOT_SYNCED,
+};
+async function createLink(runtime, params) {
+    return requestWithMessages(runtime, "/users.links.create", {
+        method: "POST",
+        body: params,
+    }, ERROR_MESSAGES);
+}
+async function deleteLink(runtime, params) {
+    return requestWithMessages(runtime, "/users.links.delete", {
+        method: "POST",
+        body: params,
+    }, ERROR_MESSAGES);
+}
+async function listLinks(runtime, params) {
+    return requestWithMessages(runtime, "/users.links.list", {
+        method: "GET",
+        query: params,
+    }, ERROR_MESSAGES);
+}
+async function setLinks(runtime, params) {
+    return requestWithMessages(runtime, "/users.links.set", {
+        method: "POST",
+        body: params,
+    }, ERROR_MESSAGES);
+}
+function renderLinks(userId, response) {
+    const blocks = [ui.h1("Linked Accounts")];
+    blocks.push(ui.p(`Displaying ${ui.bold(response.links.length.toString())} of ${ui.bold(response.total.toString())} links for user ${ui.code(userId)}.`));
+    if (response.next_page) {
+        blocks.push(ui.p(`Next page: ${ui.code(response.next_page.toString())}`));
+    }
+    for (const link of response.links) {
+        blocks.push(ui.h2(link.account
+            ? `${link.account.label} (${ui.code(link.account_id)})`
+            : `${link.source} account (${ui.code(link.account_id)})`));
+        blocks.push(ui.dl(link.account
+            ? accountDetailItems(link.account)
+            : [ui.dli("Source", link.source)], { termWidth: 13 }));
+    }
+    renderRichText(blocks);
+}

package/dist/commands/users/sources.js

@@ -0,0 +1 @@
+export const SOURCES = "ado, amazon_kiro, bitbucket, bitbucket_server, claude_code, codex, cursor, github, gitlab, jira, linear, windsurf";

package/dist/commands/users.js

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import { linkableAccountsCommand } from "./users/linkableAccounts.js";
+import { linksCommand } from "./users/links.js";
+export function usersCommand() {
+    const users = new Command().name("users").description("Manage DX users");
+    users.addCommand(linkableAccountsCommand());
+    users.addCommand(linksCommand());
+    return users;
+}

package/dist/http.js

@@ -1,4 +1,4 @@
-import { HttpError } from "./errors.js";
+import { CliError, HttpError } from "./errors.js";
 export async function request(runtime, route, options = {}) {
     const method = options.method || "GET";
     const headers = new Headers({
@@ -43,7 +43,7 @@ export async function request(runtime, route, options = {}) {
         });
     }
     catch (error) {
-        throw new HttpError(`Request failed: ${error.message}`);
+        throw new HttpError(`Could not reach ${url}: ${describeFetchFailure(error)}`);
     }
     const responseBodyText = await response.text();
     const parsedResponseBody = parseResponseBody(responseBodyText);
@@ -61,12 +61,60 @@ export async function request(runtime, route, options = {}) {
     }
     if (typeof parsedResponseBody === "string" &&
         parsedResponseBody === responseBodyText) {
-        throw new HttpError("Invalid JSON response: Unexpected token");
+        // A 2xx that isn't JSON usually means something other than the API answered
+        // e.g. a proxy block page, a captive portal, etc. Pass the status
+        // and the raw text along so the user can see what actually came back.
+        throw new HttpError(responseBodyText
+            ? `Invalid JSON response from ${url}`
+            : `Empty response body from ${url}`, response.status, responseBodyText);
     }
     const retryAfterMs = parseRetryAfterMs(response.headers);
     const body = parsedResponseBody;
     return retryAfterMs === undefined ? { body } : { body, retryAfterMs };
 }
+export async function requestWithMessages(runtime, route, options, messages) {
+    try {
+        const response = await request(runtime, route, options);
+        return response.body;
+    }
+    catch (error) {
+        throw runtime.context.json ? error : readableError(error, messages);
+    }
+}
+function readableError(error, messages) {
+    if (!(error instanceof HttpError)) {
+        return error;
+    }
+    const code = error.body?.error;
+    return typeof code === "string" && Object.hasOwn(messages, code)
+        ? new CliError(messages[code], error.exitCode)
+        : error;
+}
+/**
+ * Flatten an error thrown by `fetch` into a single readable message.
+ *
+ * Node reports every DNS, proxy, and TLS failure as `TypeError: fetch failed`
+ * and hangs the real reason off `cause`, so the top-level message alone can't
+ * distinguish an untrusted corporate root certificate from an unreachable host.
+ */
+export function describeFetchFailure(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const parts = [];
+    let current = error;
+    while (current instanceof Error) {
+        const { code } = current;
+        const part = code ? `${current.message} (${code})` : current.message;
+        if (!parts.includes(part)) {
+            parts.push(part);
+        }
+        current = current.cause;
+    }
+    // "fetch failed" carries no information once a cause is available.
+    const informative = parts.filter((part) => parts.length === 1 || part !== "fetch failed");
+    return informative.join(": ");
+}
 export function parseRetryAfterMs(headers) {
     const retryAfter = headers.get("retry-after");
     if (!retryAfter) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-dx/cli",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "DX CLI",
   "author": "DX <developers@getdx.com>",
   "bugs": {