@get-dx/cli 0.8.0 → 0.10.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/commandHelpers.js

@@ -125,6 +125,16 @@ export function parsePositiveIntOption(value, flag) {
     }
     return n;
 }
+export function parseCommaSeparatedValues(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return parsed.length > 0 ? parsed : undefined;
+}
 export function createExampleText(examples) {
     const lines = [];
     lines.push(""); // separate from the rest of the help text

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/catalog/entities.js

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { createExampleText, getContext, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
+import { createExampleText, getContext, parseCommaSeparatedValues, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
 import { CliError, EXIT_CODES, HttpError } from "../../errors.js";
 import { request } from "../../http.js";
 import { renderJson } from "../../renderers.js";
@@ -655,16 +655,6 @@ function getEntityMutationOptionValues(options) {
         owner_user_ids: parseCommaSeparatedValues(options.ownerUserIds),
     };
 }
-function parseCommaSeparatedValues(value) {
-    if (value === undefined) {
-        return undefined;
-    }
-    const parsed = value
-        .split(",")
-        .map((entry) => entry.trim())
-        .filter((entry) => entry.length > 0);
-    return parsed.length > 0 ? parsed : undefined;
-}
 function buildEntityMutationBody(identifier, params) {
     const body = { identifier };
     if ("type" in params && params.type !== undefined) {

package/dist/commands/catalog/relation-edges-blank-template.yaml

@@ -0,0 +1,19 @@
+# Relation edges for bulk upsert
+#
+# Edit this file, then run:
+#
+# ```
+# dx catalog relationEdges bulkUpsert --relation <relation-identifier> --from-file <path>
+# ```
+#
+# Each key is a source entity identifier, and each value is a list of target
+# entity identifiers.
+#
+# Bulk upsert only adds edges. Existing edges that are not listed here are kept;
+# use `dx catalog relationEdges remove` to delete an edge.
+
+source-entity-identifier-1:
+  - target-entity-identifier-a
+  - target-entity-identifier-b
+source-entity-identifier-2:
+  - target-entity-identifier-c

package/dist/commands/catalog/relationEdges.js

@@ -0,0 +1,285 @@
+import fs from "fs";
+import { Command } from "commander";
+import { parse as parseYaml } from "yaml";
+import { createExampleText, getContext, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
+import { CliError, EXIT_CODES } from "../../errors.js";
+import { request } from "../../http.js";
+import { renderJson } from "../../renderers.js";
+import { buildRuntime } from "../../runtime.js";
+import { renderRelationEdgeAdded, renderRelationEdgeList, renderRelationEdgeRemoved, renderRelationEdgesTemplateWritten, renderRelationEdgesUpserted, } from "./relationEdgesRendering.js";
+const RELATION_EDGES_BLANK_TEMPLATE_YAML = fs.readFileSync(new URL("./relation-edges-blank-template.yaml", import.meta.url), "utf8");
+export function relationEdgesCommand() {
+    const relationEdges = new Command()
+        .name("relationEdges")
+        .description("Manage relation edges between entities");
+    relationEdges
+        .command("add")
+        .description("Add a relation edge between two entities")
+        .requiredOption("--relation <identifier>", "Relation identifier (required)")
+        .requiredOption("--source <identifier>", "Source entity identifier (required)")
+        .requiredOption("--target <identifier>", "Target entity identifier (required)")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Record that `login-frontend` depends on `authn-backend`",
+            command: "dx catalog relationEdges add --relation service-depends-on-service --source login-frontend --target authn-backend",
+        },
+        {
+            label: "Add an edge and return JSON",
+            command: "dx catalog relationEdges add --relation service-depends-on-service --source login-frontend --target authn-backend --json",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const edge = {
+            relation: options.relation,
+            source: options.source,
+            target: options.target,
+        };
+        const runtime = await buildRuntime(getContext(command));
+        const response = await addRelationEdge(runtime, edge);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelationEdgeAdded(edge);
+        }
+    }));
+    relationEdges
+        .command("bulkUpsert")
+        .description("Create or update many relation edges for one relation from a YAML or JSON file or stdin. The file maps each source entity identifier to a list of target entity identifiers.")
+        .requiredOption("--relation <identifier>", "Relation identifier (required)")
+        .option("--from-file <path>", "Path to a YAML or JSON file of edges. Use `initBulkUpsert` to generate a template.")
+        .option("--from-stdin", "Read YAML or JSON edges from stdin")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Generate a template first",
+            command: "dx catalog relationEdges initBulkUpsert ./edges.yaml",
+        },
+        {
+            label: "Upsert edges from a YAML file",
+            command: "dx catalog relationEdges bulkUpsert --relation service-depends-on-service --from-file ./edges.yaml",
+        },
+        {
+            label: "Upsert edges from stdin",
+            command: 'echo \'{"login-frontend": ["authn-backend", "feature-flag-backend"]}\' | dx catalog relationEdges bulkUpsert --relation service-depends-on-service --from-stdin',
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        if (!options.fromFile && !options.fromStdin) {
+            throw new CliError("One of --from-file or --from-stdin is required", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        if (options.fromFile && options.fromStdin) {
+            throw new CliError("--from-file and --from-stdin are mutually exclusive", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const raw = options.fromFile
+            ? readYamlFile(options.fromFile)
+            : await readYamlStdin();
+        const edges = parseEdgesMap(raw, options.fromFile ? options.fromFile : "stdin");
+        const runtime = await buildRuntime(getContext(command));
+        const response = await bulkUpsertRelationEdges(runtime, options.relation, edges);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelationEdgesUpserted(options.relation, edges);
+        }
+    }));
+    relationEdges
+        .command("initBulkUpsert")
+        .description("Write a blank YAML template of relation edges to use with `bulkUpsert`")
+        .argument("<path>", "File path to write the YAML to")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Write a blank relation edges template",
+            command: "dx catalog relationEdges initBulkUpsert ./edges.yaml",
+        },
+        {
+            label: "Upsert edges from the template",
+            command: "dx catalog relationEdges bulkUpsert --relation service-depends-on-service --from-file ./edges.yaml",
+        },
+    ]))
+        .action(wrapAction(async (path, _options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        fs.writeFileSync(path, RELATION_EDGES_BLANK_TEMPLATE_YAML, "utf8");
+        if (runtime.context.json) {
+            renderJson({ ok: true, path });
+        }
+        else {
+            renderRelationEdgesTemplateWritten(path);
+        }
+    }));
+    relationEdges
+        .command("list")
+        .description("List the entities connected to an entity through a relation")
+        .requiredOption("--entity <identifier>", "Entity identifier (required)")
+        .requiredOption("--relation <identifier>", "Relation identifier (required)")
+        .option("--direction <direction>", "Treat the entity as the source (`outgoing`) or target (`incoming`) of the relation (default is outgoing)")
+        .option("--cursor <cursor>", "Cursor for the next page of results")
+        .option("--limit <n>", "Max edges per page, up to 50 (default is 25)", (value) => parsePositiveIntOption(value, "--limit"))
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List the APIs that `payments-service` consumes",
+            command: "dx catalog relationEdges list --entity payments-service --relation service-consumes-api",
+        },
+        {
+            label: "List incoming edges and return JSON",
+            command: "dx catalog relationEdges list --entity core-api --relation service-consumes-api --direction incoming --json",
+        },
+        {
+            label: "Fetch the next page using a cursor from the prior response",
+            command: "dx catalog relationEdges list --entity payments-service --relation service-consumes-api --cursor d0d93f40-e534-51ac-0a0a-c839dfa2ff35",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listRelationEdges(runtime, {
+            entity_identifier: options.entity,
+            relation_identifier: options.relation,
+            direction: options.direction,
+            cursor: options.cursor,
+            limit: options.limit,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelationEdgeList(response.entity_relations, {
+                entity: options.entity,
+                relation: options.relation,
+                direction: options.direction ?? "outgoing",
+            }, response.response_metadata?.next_cursor ?? null);
+        }
+    }));
+    relationEdges
+        .command("remove")
+        .description("Remove a relation edge between two entities")
+        .requiredOption("--relation <identifier>", "Relation identifier (required)")
+        .requiredOption("--source <identifier>", "Source entity identifier (required)")
+        .requiredOption("--target <identifier>", "Target entity identifier (required)")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Remove the edge from `login-frontend` to `authn-backend`",
+            command: "dx catalog relationEdges remove --relation service-depends-on-service --source login-frontend --target authn-backend",
+        },
+        {
+            label: "Remove an edge and return JSON",
+            command: "dx catalog relationEdges remove --relation service-depends-on-service --source login-frontend --target authn-backend --json",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const edge = {
+            relation: options.relation,
+            source: options.source,
+            target: options.target,
+        };
+        const runtime = await buildRuntime(getContext(command));
+        const response = await removeRelationEdge(runtime, edge);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelationEdgeRemoved(edge);
+        }
+    }));
+    return relationEdges;
+}
+async function addRelationEdge(runtime, edge) {
+    const response = await request(runtime, "/catalog.relationEdges.add", {
+        method: "POST",
+        body: edgeBody(edge),
+    });
+    return response.body;
+}
+async function bulkUpsertRelationEdges(runtime, relation, edges) {
+    const response = await request(runtime, "/catalog.relationEdges.bulkUpsert", {
+        method: "POST",
+        body: { relation_identifier: relation, edges },
+    });
+    return response.body;
+}
+async function listRelationEdges(runtime, params) {
+    const query = {
+        entity_identifier: params.entity_identifier,
+        relation_identifier: params.relation_identifier,
+    };
+    if (params.direction !== undefined)
+        query.direction = params.direction;
+    if (params.cursor !== undefined)
+        query.cursor = params.cursor;
+    if (params.limit !== undefined)
+        query.limit = params.limit;
+    const response = await request(runtime, "/catalog.relationEdges.list", {
+        method: "GET",
+        query,
+    });
+    return response.body;
+}
+async function removeRelationEdge(runtime, edge) {
+    const response = await request(runtime, "/catalog.relationEdges.remove", {
+        method: "POST",
+        body: edgeBody(edge),
+    });
+    return response.body;
+}
+function edgeBody(edge) {
+    return {
+        relation_identifier: edge.relation,
+        source_entity_identifier: edge.source,
+        target_entity_identifier: edge.target,
+    };
+}
+// --- Input helpers ---
+function parseEdgesMap(raw, sourceLabel) {
+    if (raw === null || raw === undefined) {
+        throw noEdgesError(sourceLabel);
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CliError("Edges must be an object mapping each source entity identifier to a list of target entity identifiers", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    for (const [source, targets] of Object.entries(raw)) {
+        if (!Array.isArray(targets) ||
+            !targets.every((target) => typeof target === "string")) {
+            throw new CliError(`Targets for source "${source}" must be a list of entity identifiers`, EXIT_CODES.ARGUMENT_ERROR);
+        }
+    }
+    const edges = raw;
+    if (Object.values(edges).every((targets) => targets.length === 0)) {
+        throw noEdgesError(sourceLabel);
+    }
+    return edges;
+}
+function noEdgesError(sourceLabel) {
+    return new CliError(`No edges found in ${sourceLabel}`, EXIT_CODES.ARGUMENT_ERROR);
+}
+function readYamlFile(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new CliError(`Could not read file "${filePath}": ${err.message}`, EXIT_CODES.ARGUMENT_ERROR);
+    }
+    try {
+        return parseYaml(content);
+    }
+    catch (err) {
+        throw new CliError(`Failed to parse YAML from "${filePath}": ${err.message}`, EXIT_CODES.ARGUMENT_ERROR);
+    }
+}
+async function readYamlStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => {
+            const content = Buffer.concat(chunks).toString("utf8");
+            try {
+                resolve(parseYaml(content));
+            }
+            catch (err) {
+                reject(new CliError(`Failed to parse YAML from stdin: ${err.message}`, EXIT_CODES.ARGUMENT_ERROR));
+            }
+        });
+        process.stdin.on("error", (err) => {
+            reject(new CliError(`Failed to read from stdin: ${err.message}`, EXIT_CODES.ARGUMENT_ERROR));
+        });
+    });
+}

package/dist/commands/catalog/relationEdgesRendering.js

@@ -0,0 +1,45 @@
+import { renderRichText } from "../../renderers.js";
+import * as ui from "../../ui.js";
+export function renderRelationEdgeAdded(edge) {
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Added edge ${edgeSummary(edge)}`),
+    ]);
+}
+export function renderRelationEdgeRemoved(edge) {
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Removed edge ${edgeSummary(edge)}`),
+    ]);
+}
+export function renderRelationEdgesUpserted(relation, edges) {
+    const count = Object.values(edges).reduce((sum, targets) => sum + targets.length, 0);
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Upserted ${ui.bold(count.toString())} ${count === 1 ? "edge" : "edges"} for ${ui.code(relation)}`),
+    ]);
+}
+export function renderRelationEdgesTemplateWritten(path) {
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Blank template written to ${ui.code(path)}.`),
+        ui.p(`Edit the file, then run: ${ui.code(`dx catalog relationEdges bulkUpsert --relation <relation-identifier> --from-file ${path}`)}`),
+    ]);
+}
+export function renderRelationEdgeList(entities, query, nextCursor) {
+    const blocks = [ui.h1("Relation Edges")];
+    blocks.push(ui.dl([
+        ui.dli("Entity", ui.code(query.entity)),
+        ui.dli("Relation", ui.code(query.relation)),
+        ui.dli("Direction", query.direction),
+    ], { termWidth: 11 }));
+    blocks.push(ui.p(`Displaying ${ui.bold(entities.length.toString())} related entities.`));
+    if (nextCursor) {
+        blocks.push(ui.p(`Next cursor: ${ui.code(nextCursor)}`));
+    }
+    if (entities.length > 0) {
+        blocks.push(ui.ul(entities.map((entity) => ui.li(entity.name
+            ? `${entity.name} (${ui.code(entity.identifier)})`
+            : ui.code(entity.identifier)))));
+    }
+    renderRichText(blocks);
+}
+function edgeSummary(edge) {
+    return `${ui.code(edge.source)} -> ${ui.code(edge.target)} (${ui.code(edge.relation)})`;
+}