@get-dx/cli 0.8.0 → 0.9.0

package/dist/cli.js

@@ -1,6 +1,8 @@
 import { Command, Option } from "commander";
+import { attributeGroupsCommand } from "./commands/attributeGroups.js";
 import { authCommand } from "./commands/auth.js";
 import { catalogCommand } from "./commands/catalog.js";
+import { doctorCommand } from "./commands/doctor.js";
 import { initCommand } from "./commands/init.js";
 import { scorecardsCommand } from "./commands/scorecards.js";
 import { snapshotsCommand } from "./commands/snapshots.js";
@@ -48,8 +50,10 @@ function createProgram() {
         .addOption(new Option("--agent <name>", "Agent name to send as an HTTP header"))
         .addOption(new Option("--agent-model <model>", "Agent model name to send as an HTTP header"))
         .addOption(new Option("--agent-session-id <id>", "Agent session ID to send as an HTTP header"));
+    program.addCommand(attributeGroupsCommand());
     program.addCommand(authCommand());
     program.addCommand(catalogCommand());
+    program.addCommand(doctorCommand());
     program.addCommand(initCommand());
     program.addCommand(scorecardsCommand());
     program.addCommand(snapshotsCommand());

package/dist/commands/attributeGroups.js

@@ -0,0 +1,100 @@
+import { Command } from "commander";
+import { createExampleText, getContext, wrapAction, } from "../commandHelpers.js";
+import { request } from "../http.js";
+import { renderJson, renderRichText } from "../renderers.js";
+import { buildRuntime } from "../runtime.js";
+import * as ui from "../ui.js";
+export function attributeGroupsCommand() {
+    const attributeGroups = new Command()
+        .name("attributeGroups")
+        .description("List attribute groups and values for filtering snapshot scores");
+    attributeGroups
+        .command("list")
+        .description("List attribute groups and their attribute values")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List attribute groups in human-readable output",
+            command: "dx attributeGroups list",
+        },
+        {
+            label: "Print raw JSON for automation",
+            command: "dx --json attributeGroups list",
+        },
+    ]))
+        .action(wrapAction(async (_options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listAttributeGroups(runtime);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderAttributeGroups(response.attribute_groups);
+        }
+    }));
+    return attributeGroups;
+}
+export async function listAttributeGroups(runtime) {
+    const response = await request(runtime, "/attributeGroups.list", {
+        method: "GET",
+    });
+    return response.body;
+}
+function renderAttributeGroups(unsortedGroups) {
+    const attributeGroups = [...unsortedGroups].sort(byPosition);
+    const blocks = [ui.h1("Attribute Groups")];
+    blocks.push(ui.p(`Displaying ${ui.bold(attributeGroups.length.toString())} attribute groups.`));
+    if (attributeGroups.length === 0) {
+        blocks.push(ui.p("No attribute groups are available for this account. Create or sync attribute groups in DX before filtering snapshot scores by attribute."));
+        renderRichText(blocks);
+        return;
+    }
+    for (const attributeGroup of attributeGroups) {
+        blocks.push(ui.h2(`${attributeGroup.name} (${ui.code(attributeGroup.id)})`));
+        blocks.push(ui.dl([
+            ui.dli("Type", formatAttributeGroupType(attributeGroup.type)),
+            ui.dli("ID", ui.code(attributeGroup.id)),
+            ...(attributeGroup.position === null
+                ? []
+                : [ui.dli("Position", attributeGroup.position.toString())]),
+            ...(attributeGroup.hidden ? [ui.dli("Hidden", "Yes")] : []),
+            // The API only returns privileged groups the user can see.
+            ...(attributeGroup.privileged ? [ui.dli("Privileged", "Yes")] : []),
+        ], { termWidth: 12 }));
+        if (attributeGroup.attributes.length === 0) {
+            blocks.push(ui.p(`Attributes: ${ui.dim("(None)")}`));
+            continue;
+        }
+        blocks.push(ui.p("Attributes:"));
+        blocks.push(ui.ul([...attributeGroup.attributes]
+            .sort(byPositionThenName)
+            .map((attribute) => ui.li(`${attribute.name} (${ui.code(attribute.id)})`))));
+    }
+    renderRichText(blocks);
+}
+// Items without a position sort last. Ties keep the API's order (a stable
+// sort), which is by id for groups.
+function byPosition(a, b) {
+    if (a.position === b.position)
+        return 0;
+    if (a.position === null)
+        return 1;
+    if (b.position === null)
+        return -1;
+    return a.position - b.position;
+}
+// Attributes are ordered by position, then name.
+function byPositionThenName(a, b) {
+    return byPosition(a, b) || a.name.localeCompare(b.name);
+}
+function formatAttributeGroupType(type) {
+    switch (type.toUpperCase()) {
+        case "ADMIN_MANAGED":
+            return "Admin managed";
+        case "SELF_REPORTED":
+            return "Self reported";
+        case "DX_MANAGED":
+            return "DX managed";
+        default:
+            return type;
+    }
+}

package/dist/commands/auth.js

@@ -154,8 +154,9 @@ export function authCommand() {
     return auth;
 }
 // TODO: should we move this somewhere more central, since `init` needs it?
-export async function getAuthInfo(runtime) {
+export async function getAuthInfo(runtime, options) {
     const response = await request(runtime, "/auth.info", {
+        ...options,
         method: "GET",
     });
     return response.body;

package/dist/commands/doctor.js

@@ -0,0 +1,85 @@
+import { Command } from "commander";
+import { createExampleText, getContext, wrapAction, } from "../commandHelpers.js";
+import { runDoctor } from "../doctor/index.js";
+import { AsyncProgressReporter, renderJson, renderRichText, } from "../renderers.js";
+import * as ui from "../ui.js";
+const MIN_LABEL_WIDTH = 26;
+const PHASE_MESSAGES = {
+    config: "Checking configuration…",
+    network: "Checking network…",
+    auth: "Checking authentication…",
+    version: "Checking for updates…",
+};
+export function doctorCommand() {
+    return new Command("doctor")
+        .description("Diagnose problems with your CLI instance's installation, configuration, networking, and authentication")
+        .addHelpText("afterAll", createExampleText([
+        { label: "Check your setup", command: "dx doctor" },
+        { label: "Print the report as JSON", command: "dx doctor --json" },
+    ]))
+        .action(wrapAction(async (_options, command) => {
+        const context = getContext(command);
+        const progress = new AsyncProgressReporter();
+        progress.start(PHASE_MESSAGES.config);
+        let report;
+        try {
+            report = await runDoctor(context, {
+                onPhase: (phase) => progress.update(PHASE_MESSAGES[phase]),
+            });
+        }
+        finally {
+            progress.stop();
+        }
+        if (context.json) {
+            renderJson(report);
+        }
+        else {
+            renderDoctorReport(report);
+        }
+        if (!report.ok) {
+            process.exitCode = 1;
+        }
+    }));
+}
+export function renderDoctorReport(report) {
+    const labelWidth = Math.max(MIN_LABEL_WIDTH, ...report.sections.flatMap((section) => section.checks.map((check) => check.label.length + 2)));
+    renderRichText([
+        ...report.sections.map((section) => ui.statusList(section.title, section.checks.map((check) => ({
+            status: check.status,
+            label: check.label,
+            detail: formatDetail(check),
+            hint: check.hint,
+        })), { labelWidth })),
+        ui.p(summaryLine(report)),
+    ]);
+}
+function formatDetail(check) {
+    if (!check.source) {
+        return check.message;
+    }
+    return `${check.message} ${ui.dim(`[from ${sourceName(check.source)}]`)}`;
+}
+function sourceName(source) {
+    switch (source) {
+        case "env":
+            return "env";
+        case "config":
+            return "config file";
+        case "default":
+            return "default";
+        case "keychain":
+            return "keychain";
+    }
+}
+function summaryLine(report) {
+    const { fail, warn } = report.summary;
+    const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+    if (fail > 0) {
+        const failed = ui.error(`${plural(fail, "check")} failed`);
+        return warn > 0 ? `${failed}, ${plural(warn, "warning")}.` : `${failed}.`;
+    }
+    if (warn > 0) {
+        return ui.warning(`All required checks passed, ${plural(warn, "warning")}.`);
+    }
+    return ui.success("All checks passed.");
+}

package/dist/commands/snapshots.js

@@ -4,6 +4,7 @@ import { CliError, EXIT_CODES } from "../errors.js";
 import { request } from "../http.js";
 import { renderJson, renderRichText } from "../renderers.js";
 import { buildRuntime } from "../runtime.js";
+import { formatTeamMember } from "./teams.js";
 import * as ui from "../ui.js";
 export function snapshotsCommand() {
     const snapshots = new Command()
@@ -135,6 +136,35 @@ export function snapshotsCommand() {
             renderSnapshots(response.snapshots, runtime);
         }
     }));
+    const snapshotTeams = new Command()
+        .name("snapshotTeams")
+        .description("Work with snapshot teams");
+    snapshotTeams
+        .command("list")
+        .description("List teams for a snapshot")
+        .option("--id <id>", "The unique ID of the snapshot")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List teams for a snapshot",
+            command: "dx snapshots snapshotTeams list --id MjUyNbaY",
+        },
+        {
+            label: "List snapshot teams as JSON",
+            command: "dx --json snapshots snapshotTeams list --id MjUyNbaY",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const snapshotId = parseRequiredTextOption(options.id, "--id");
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listSnapshotTeams(runtime, snapshotId);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderSnapshotTeams(response.snapshot_teams, snapshotId, runtime);
+        }
+    }));
+    snapshots.addCommand(snapshotTeams);
     return snapshots;
 }
 async function listSnapshotDriverComments(runtime, options) {
@@ -159,6 +189,13 @@ async function listSnapshotCsatComments(runtime, options) {
     });
     return response.body;
 }
+async function listSnapshotTeams(runtime, snapshotId) {
+    const response = await request(runtime, "/snapshots.snapshotTeams.list", {
+        method: "GET",
+        query: { snapshot_id: snapshotId },
+    });
+    return response.body;
+}
 async function getSnapshotInfo(runtime, snapshotId) {
     const response = await request(runtime, "/snapshots.info", {
         method: "GET",
@@ -237,6 +274,22 @@ function renderSnapshotCsatComments(comments, nextCursor, snapshotId, runtime) {
     }
     renderRichText(blocks);
 }
+function renderSnapshotTeams(teams, snapshotId, runtime) {
+    const blocks = [ui.h1("Snapshot Teams")];
+    blocks.push(ui.p(`Displaying ${ui.bold(teams.length.toString())} teams.`));
+    blocks.push(ui.p(`Snapshot Team IDs are only valid within this snapshot and feed ${ui.code("snapshot_team_ids")} score filters. Use ${ui.code("team_id")} with ${ui.code("dx teams info --team-id")}.`));
+    blocks.push(ui.p(ui.link(snapshotWebLink(snapshotId, "drivers", runtime))));
+    if (teams.length === 0) {
+        blocks.push(ui.p(ui.dim("(None)")));
+        renderRichText(blocks);
+        return;
+    }
+    const rootTeams = buildSnapshotTeamTree(teams);
+    rootTeams.forEach((rootTeam) => {
+        appendSnapshotTeamBlock(blocks, rootTeam, 0);
+    });
+    renderRichText(blocks);
+}
 function renderSnapshotInfo(snapshot, snapshotId, runtime) {
     const teamScores = snapshot.team_scores ?? [];
     const blocks = [ui.h1("Snapshot Information")];
@@ -298,6 +351,69 @@ function extractCsatComments(response) {
         response.comments ??
         []);
 }
+class SnapshotTeamTreeNode {
+    team;
+    children = [];
+    constructor(team) {
+        this.team = team;
+    }
+}
+function buildSnapshotTeamTree(teams) {
+    const nodes = new Map();
+    teams.forEach((team) => {
+        nodes.set(team.id, new SnapshotTeamTreeNode(team));
+    });
+    const rootTeams = [];
+    teams.forEach((team) => {
+        const currentNode = nodes.get(team.id);
+        if (currentNode.team.parent_id === null) {
+            // It's a top-level root node
+            rootTeams.push(currentNode);
+        }
+        else {
+            // Append it to its parent's children array
+            nodes.get(currentNode.team.parent_id).children.push(currentNode);
+        }
+    });
+    const sortNodes = (items) => {
+        items.sort((left, right) => compareSnapshotTeams(left.team, right.team));
+        for (const item of items) {
+            sortNodes(item.children);
+        }
+    };
+    sortNodes(rootTeams);
+    return rootTeams;
+}
+function compareSnapshotTeams(left, right) {
+    const leftName = left.name.toLocaleLowerCase();
+    const rightName = right.name.toLocaleLowerCase();
+    if (leftName !== rightName) {
+        return leftName.localeCompare(rightName);
+    }
+    // If the names are the same, compare the IDs
+    const leftId = left.id.toLocaleLowerCase();
+    const rightId = right.id.toLocaleLowerCase();
+    return leftId.localeCompare(rightId);
+}
+function appendSnapshotTeamBlock(blocks, node, depth) {
+    blocks.push(depth === 0
+        ? ui.h2(node.team.name)
+        : ui.h3(`${"↳".repeat(depth)} ${node.team.name}`));
+    const details = [
+        optionalDetail("Snapshot Team ID", formatText(node.team.id), node.team.id),
+        optionalDetail("Team ID", formatText(node.team.team_id), node.team.team_id),
+        // Match `dx teams info`: show "(None)" when the API returns a null manager,
+        // omit the row only when the field is absent entirely.
+        ui.dli("Manager", formatTeamMember(node.team.manager)),
+        optionalDetail("Parent ID", formatText(node.team.parent_id), node.team.parent_id),
+    ].filter((detail) => detail !== null);
+    if (details.length > 0) {
+        blocks.push(ui.dl(details, { termWidth: 18 }));
+    }
+    node.children.forEach((child) => {
+        appendSnapshotTeamBlock(blocks, child, depth + 1);
+    });
+}
 function formatCommentHeading(comment) {
     const heading = comment.item_name ??
         comment.driver_name ??

package/dist/commands/teams.js

@@ -200,7 +200,7 @@ function formatTeamHeading(team) {
     }
     return null;
 }
-function formatTeamMember(member) {
+export function formatTeamMember(member) {
     if (!member) {
         return ui.dim("(None)");
     }

package/dist/config.js

@@ -41,6 +41,53 @@ export function readConfig() {
     }
     return stored;
 }
+/**
+ * Report on the state of the config file without hiding problems, unlike
+ * `readConfig`, which treats an unparseable file as empty.
+ */
+export function inspectConfigFile() {
+    const configPath = getConfigPath();
+    let stats;
+    let content;
+    try {
+        stats = fs.statSync(configPath);
+        content = fs.readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { status: "missing", path: configPath };
+        }
+        return {
+            status: "invalid",
+            path: configPath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        const parsed = JSON.parse(content);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {
+                status: "invalid",
+                path: configPath,
+                error: "expected a JSON object",
+            };
+        }
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            path: configPath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return {
+        status: "ok",
+        path: configPath,
+        config: readConfig(),
+        sizeBytes: stats.size,
+        modifiedAt: stats.mtime,
+    };
+}
 export function persistCurrentVersionCache(cache) {
     writeConfig({ ...readConfig(), currentVersionCache: cache });
 }
@@ -89,20 +136,31 @@ function getConfigDir() {
  * Precedence: `DX_API_BASE_URL`, then persisted `apiBaseUrl`, then DX Cloud default.
  */
 export function resolveApiBaseUrl() {
-    if (process.env.DX_API_BASE_URL) {
-        return normalizeUrl(process.env.DX_API_BASE_URL);
-    }
-    return normalizeUrl(readConfig().apiBaseUrl || DEFAULT_API_BASE_URL);
+    return resolveApiBaseUrlWithSource().url;
+}
+/** Like `resolveApiBaseUrl`, but also reports where the value came from. */
+export function resolveApiBaseUrlWithSource() {
+    return resolveBaseUrl(process.env.DX_API_BASE_URL, readConfig().apiBaseUrl, DEFAULT_API_BASE_URL);
 }
 /**
  * Resolved web-app base URL for CLI deep links and browser OAuth.
  * Precedence: `DX_WEB_BASE_URL`, persisted `webBaseUrl`, then DX Cloud default.
  */
 export function resolveWebBaseUrl() {
-    if (process.env.DX_WEB_BASE_URL) {
-        return normalizeUrl(process.env.DX_WEB_BASE_URL);
+    return resolveWebBaseUrlWithSource().url;
+}
+/** Like `resolveWebBaseUrl`, but also reports where the value came from. */
+export function resolveWebBaseUrlWithSource() {
+    return resolveBaseUrl(process.env.DX_WEB_BASE_URL, readConfig().webBaseUrl, DEFAULT_WEB_BASE_URL);
+}
+function resolveBaseUrl(fromEnv, fromConfig, fallback) {
+    if (fromEnv) {
+        return { url: normalizeUrl(fromEnv), source: "env" };
     }
-    return normalizeUrl(readConfig().webBaseUrl || DEFAULT_WEB_BASE_URL);
+    if (fromConfig) {
+        return { url: normalizeUrl(fromConfig), source: "config" };
+    }
+    return { url: normalizeUrl(fallback), source: "default" };
 }
 // --- Deriving base URLs at login time -------------------------------------
 /**
@@ -151,14 +209,17 @@ export function deriveBaseUrlsFromEnv() {
             throw new CliError(`Could not recognize web base URL "${parsed.input}". Expected https://app.getdx.com, https://<account>.getdx.io, or a custom domain.`);
     }
 }
-function parseWebBaseUrl(raw) {
+export function parseWebBaseUrl(raw) {
     const normalized = raw.trim().replace(/\/$/, "");
-    if (!normalized || normalized === "app.getdx.com") {
+    if (!normalized) {
         return { type: "cloud" };
     }
     try {
         const url = new URL(normalized.startsWith("http") ? normalized : `https://${normalized}`);
         const host = url.hostname;
+        if (host === "app.getdx.com") {
+            return { type: "cloud" };
+        }
         const dedicatedMatch = host.match(/^(.+)\.getdx\.io$/);
         if (dedicatedMatch) {
             return { type: "dedicated", accountName: dedicatedMatch[1] };

package/dist/doctor/auth.js

@@ -0,0 +1,133 @@
+import dayjs from "dayjs";
+import { getAuthInfo } from "../commands/auth.js";
+import { HttpError } from "../errors.js";
+import { describeError, timed } from "./format.js";
+import { CHECK_TIMEOUT_MS, DOCTOR_HEADER } from "./probes.js";
+import { check } from "./types.js";
+const EXPIRY_WARNING_DAYS = 7;
+const SECTION = { id: "auth", title: "Auth" };
+export async function checkAuth(options) {
+    const { runtime, apiReachable, now } = options;
+    if (!runtime) {
+        return skipped("no token is configured");
+    }
+    if (!apiReachable) {
+        return skipped("the API is unreachable");
+    }
+    const host = new URL(runtime.apiBaseUrl).host;
+    let info;
+    let ms;
+    try {
+        ({ value: info, ms } = await timed(() => getAuthInfo(runtime, {
+            headers: DOCTOR_HEADER,
+            signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+        })));
+    }
+    catch (error) {
+        return { ...SECTION, checks: [tokenErrorCheck(error, host)] };
+    }
+    const { auth, account } = info;
+    const checks = [
+        check("token_valid", "Token valid", "ok", `${tokenTypeName(auth.token_type)} "${auth.token_name}" (responded in ${ms}ms)`, {
+            data: {
+                token_type: auth.token_type,
+                token_name: auth.token_name,
+                scopes: auth.scopes,
+                created_at: auth.created_at,
+                ms,
+            },
+        }),
+        check("account", "Account", "ok", account.name, {
+            data: { name: account.name },
+        }),
+    ];
+    if (auth.token_type === "personal_access_token") {
+        checks.push(expiryCheck(auth.expires_at, now));
+    }
+    return { ...SECTION, checks };
+}
+function skipped(reason) {
+    return {
+        ...SECTION,
+        checks: [
+            check("token_valid", "Token valid", "skip", `skipped because ${reason}`),
+        ],
+    };
+}
+function tokenErrorCheck(error, host) {
+    if (error instanceof HttpError && error.status === 401) {
+        return check("token_valid", "Token valid", "fail", `token rejected by ${host} (HTTP 401: ${error.message})`, {
+            hint: "The token may be revoked, expired, or issued by a different DX instance. Run `dx auth login` to store a new one.",
+            data: { status: 401 },
+        });
+    }
+    if (error instanceof HttpError && error.status !== undefined) {
+        const { message, hint } = describeHttpFailure(error.status, error.message, host);
+        return check("token_valid", "Token valid", "fail", message, {
+            hint,
+            data: { status: error.status },
+        });
+    }
+    return check("token_valid", "Token valid", "fail", describeError(error, "auth.info request"), {
+        hint: `The API was reachable a moment ago, but this request to ${host} failed. Try again.`,
+        data: { status: null },
+    });
+}
+function describeHttpFailure(status, errorMessage, host) {
+    if (status === 403) {
+        return {
+            message: `access denied by ${host} (HTTP 403: ${errorMessage})`,
+            hint: "The token was recognized but this request was refused. An IP allowlist, proxy, or firewall may be blocking it. Check with your DX admin or network team.",
+        };
+    }
+    if (status === 429) {
+        return {
+            message: `rate limited by ${host} (HTTP 429)`,
+            hint: "Too many requests. Wait a minute and run `dx doctor` again.",
+        };
+    }
+    if (status >= 500) {
+        return {
+            message: `HTTP ${status}: ${errorMessage}`,
+            hint: "The DX API is having problems. Try again in a few minutes, and contact DX support if this persists.",
+        };
+    }
+    return {
+        message: `HTTP ${status}: ${errorMessage}`,
+        hint: "The DX API could not validate the token. Try again, and contact DX support if this persists.",
+    };
+}
+function expiryCheck(expiresAt, now) {
+    if (!expiresAt) {
+        return check("expires", "Expires", "ok", "never", {
+            data: { expires_at: null },
+        });
+    }
+    const expires = dayjs(expiresAt);
+    const days = expires.diff(dayjs(now), "day");
+    const date = expires.format("YYYY-MM-DD");
+    const data = { expires_at: expiresAt, days_remaining: days };
+    if (expires.isBefore(now)) {
+        return check("expires", "Expires", "fail", `expired on ${date}`, {
+            hint: "Create a new personal access token and run `dx auth login`.",
+            data,
+        });
+    }
+    if (days < EXPIRY_WARNING_DAYS) {
+        return check("expires", "Expires", "warn", `${date} (${days}d)`, {
+            hint: "This token expires soon. Create a new one and run `dx auth login`.",
+            data,
+        });
+    }
+    return check("expires", "Expires", "ok", `${date} (${days}d)`, { data });
+}
+function tokenTypeName(tokenType) {
+    switch (tokenType) {
+        case "account_web_api_token":
+            return "organization token";
+        case "personal_access_token":
+            return "personal access token";
+        default:
+            return String(tokenType);
+    }
+}