@get-dx/cli 0.6.2 → 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/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({
@@ -72,6 +72,24 @@ export async function request(runtime, route, options = {}) {
     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.
  *

package/package.json

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