@get-dx/cli 0.9.0 → 0.10.0

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/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)})`;
+}

package/dist/commands/catalog/relations.js

@@ -0,0 +1,231 @@
+import { Command } from "commander";
+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 * as ui from "../../ui.js";
+import { renderRelation, renderRelationDeleted, renderRelationList, } from "./relationsRendering.js";
+const RELATION_TYPES = [
+    "consumes",
+    "depends on",
+    "parent of",
+    "part of",
+    "provides",
+    "manages",
+];
+const RELATION_CARDINALITIES = [
+    "one_to_one",
+    "one_to_many",
+    "many_to_one",
+    "many_to_many",
+];
+const RELATION_TYPE_HELP = `Relation type. One of: ${RELATION_TYPES.map((t) => `"${t}"`).join(", ")}`;
+export function relationsCommand() {
+    const relations = new Command()
+        .name("relations")
+        .description("Manage relation definitions between entity types");
+    relations
+        .command("create")
+        .description("Create a new relation definition between two entity types in your software catalog")
+        .requiredOption("--identifier <identifier>", "Unique identifier for the new relation (required)")
+        .requiredOption("--source-type <type>", "Entity type identifier for the source side of the relation (required)")
+        .requiredOption("--target-type <type>", "Entity type identifier for the target side of the relation (required)")
+        .requiredOption("--type <type>", `${RELATION_TYPE_HELP} (required)`)
+        .requiredOption("--cardinality <cardinality>", `Relation cardinality. One of: ${RELATION_CARDINALITIES.join(", ")} (required)`)
+        .option("--description <desc>", "Description of the relation")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Create a relation between services",
+            command: 'dx catalog relations create --identifier service-depends-on-service --source-type service --target-type service --type "depends on" --cardinality many_to_many',
+        },
+        {
+            label: "Create with a description and return JSON",
+            command: 'dx catalog relations create --identifier service-provides-package --source-type service --target-type package --type provides --cardinality one_to_many --description "Service provides a client SDK" --json',
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await createRelation(runtime, {
+            identifier: options.identifier,
+            source_entity_type_identifier: options.sourceType,
+            target_entity_type_identifier: options.targetType,
+            type: options.type,
+            cardinality: options.cardinality,
+            description: options.description,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelation(response.relation, `${ui.success(ui.GLYPHS.CHECK)} Relation created`);
+        }
+    }));
+    relations
+        .command("delete")
+        .description("Delete a relation definition from your software catalog")
+        .argument("<identifier>", "Relation identifier")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Delete the `service-depends-on-service` relation",
+            command: "dx catalog relations delete service-depends-on-service",
+        },
+        {
+            label: "Delete a relation and return JSON",
+            command: "dx catalog relations delete service-depends-on-service --json",
+        },
+    ]))
+        .action(wrapAction(async (identifier, _options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await deleteRelation(runtime, identifier);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelationDeleted(response.relation);
+        }
+    }));
+    relations
+        .command("info")
+        .description("Get information about a relation definition")
+        .argument("<identifier>", "Relation identifier")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Fetch info for the `service-depends-on-service` relation",
+            command: "dx catalog relations info service-depends-on-service",
+        },
+        {
+            label: "Fetch info and return as JSON",
+            command: "dx catalog relations info service-depends-on-service --json",
+        },
+    ]))
+        .action(wrapAction(async (identifier, _options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await getRelation(runtime, identifier);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelation(response.relation);
+        }
+    }));
+    relations
+        .command("list")
+        .description("List relation definitions in your software catalog")
+        .option("--cursor <cursor>", "Cursor for the next page of results")
+        .option("--limit <n>", "Max relations per page (default is 25)", (value) => parsePositiveIntOption(value, "--limit"))
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List the first page of relations",
+            command: "dx catalog relations list",
+        },
+        {
+            label: "List with a limit and return JSON",
+            command: "dx catalog relations list --limit 10 --json",
+        },
+        {
+            label: "Fetch the next page using a cursor from the prior response",
+            command: "dx catalog relations list --cursor avsgf30ccan3",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listRelations(runtime, {
+            cursor: options.cursor,
+            limit: options.limit,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelationList(response.relations, response.response_metadata?.next_cursor ?? null);
+        }
+    }));
+    relations
+        .command("update")
+        .description("Update a relation definition. The identifier, source and target entity types, and cardinality cannot be changed.")
+        .argument("<identifier>", "Relation identifier")
+        .option("--type <type>", RELATION_TYPE_HELP)
+        .option("--description <desc>", "Description of the relation")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Update a relation's description",
+            command: 'dx catalog relations update service-depends-on-service --description "Runtime dependencies between services"',
+        },
+        {
+            label: "Change the relation type and return JSON",
+            command: "dx catalog relations update service-provides-package --type provides --json",
+        },
+    ]))
+        .action(wrapAction(async (identifier, options, command) => {
+        if (options.type === undefined && options.description === undefined) {
+            throw new CliError("Provide at least one of --type or --description to update", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = await buildRuntime(getContext(command));
+        const response = await updateRelation(runtime, identifier, {
+            type: options.type,
+            description: options.description,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderRelation(response.relation, `${ui.success(ui.GLYPHS.CHECK)} Relation updated`);
+        }
+    }));
+    return relations;
+}
+async function createRelation(runtime, params) {
+    const body = {
+        identifier: params.identifier,
+        source_entity_type_identifier: params.source_entity_type_identifier,
+        target_entity_type_identifier: params.target_entity_type_identifier,
+        type: params.type,
+        cardinality: params.cardinality,
+    };
+    if (params.description !== undefined)
+        body.description = params.description;
+    const response = await request(runtime, "/catalog.relations.create", {
+        method: "POST",
+        body,
+    });
+    return response.body;
+}
+async function deleteRelation(runtime, identifier) {
+    const response = await request(runtime, "/catalog.relations.delete", {
+        method: "POST",
+        query: { identifier },
+    });
+    return response.body;
+}
+async function getRelation(runtime, identifier) {
+    const response = await request(runtime, "/catalog.relations.info", {
+        method: "GET",
+        query: { identifier },
+    });
+    return response.body;
+}
+async function listRelations(runtime, params) {
+    const query = {};
+    if (params.cursor !== undefined)
+        query.cursor = params.cursor;
+    if (params.limit !== undefined)
+        query.limit = params.limit;
+    const response = await request(runtime, "/catalog.relations.list", {
+        method: "GET",
+        query,
+    });
+    return response.body;
+}
+async function updateRelation(runtime, identifier, params) {
+    const body = { identifier };
+    if (params.type !== undefined)
+        body.type = params.type;
+    if (params.description !== undefined)
+        body.description = params.description;
+    const response = await request(runtime, "/catalog.relations.update", {
+        method: "POST",
+        body,
+    });
+    return response.body;
+}

package/dist/commands/catalog/relationsRendering.js

@@ -0,0 +1,37 @@
+import { renderRichText } from "../../renderers.js";
+import * as ui from "../../ui.js";
+export function renderRelationList(relations, nextCursor) {
+    const blocks = [ui.h1("Relations")];
+    blocks.push(ui.p(`Displaying ${ui.bold(relations.length.toString())} relations.`));
+    if (nextCursor) {
+        blocks.push(ui.p(`Next cursor: ${ui.code(nextCursor)}`));
+    }
+    for (const relation of relations) {
+        blocks.push(ui.h2(ui.code(relation.identifier)));
+        blocks.push(...relationContent(relation));
+    }
+    renderRichText(blocks);
+}
+export function renderRelation(relation, title = "Relation Information") {
+    renderRichText([ui.h1(title), ...relationContent(relation)]);
+}
+export function renderRelationDeleted(relation) {
+    renderRichText([
+        ui.h1(`${ui.success(ui.GLYPHS.CHECK)} Relation deleted`),
+        ui.p(`The relation ${ui.code(relation.identifier)} has been deleted.`),
+    ]);
+}
+function relationContent(relation) {
+    return [
+        ui.dl([
+            ui.dli("Identifier", ui.code(relation.identifier)),
+            ui.dli("Relation", `${ui.code(relation.source_entity_type_identifier)} ${relation.type} ${ui.code(relation.target_entity_type_identifier)}`),
+            ui.dli("Type", relation.type),
+            ui.dli("Inverse type", relation.inverse_type),
+            ui.dli("Cardinality", ui.code(relation.cardinality)),
+            ui.dli("Description", relation.description || ui.dim("(None)")),
+            ui.dli("Created", ui.timestampSummary(relation.created_at)),
+            ui.dli("Last updated", ui.timestampSummary(relation.updated_at)),
+        ], { termWidth: 15 }),
+    ];
+}

package/dist/commands/catalog.js

@@ -1,11 +1,15 @@
 import { Command } from "commander";
 import { entitiesCommand } from "./catalog/entities.js";
 import { entityTypesCommand } from "./catalog/entityTypes.js";
+import { relationEdgesCommand } from "./catalog/relationEdges.js";
+import { relationsCommand } from "./catalog/relations.js";
 export function catalogCommand() {
     const catalog = new Command()
         .name("catalog")
         .description("Manage the Software Catalog");
     catalog.addCommand(entitiesCommand());
     catalog.addCommand(entityTypesCommand());
+    catalog.addCommand(relationEdgesCommand());
+    catalog.addCommand(relationsCommand());
     return catalog;
 }

package/dist/commands/snapshots.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 } from "../errors.js";
 import { request } from "../http.js";
 import { renderJson, renderRichText } from "../renderers.js";
@@ -165,6 +165,60 @@ export function snapshotsCommand() {
         }
     }));
     snapshots.addCommand(snapshotTeams);
+    const workflowScores = new Command()
+        .name("workflowScores")
+        .description("Work with snapshot workflow scores");
+    workflowScores
+        .command("list")
+        .description("List workflow scores and details for a snapshot")
+        .option("--id <id>", "The unique ID of the snapshot")
+        .option("--team-ids <ids>", "Comma-separated team IDs")
+        .option("--snapshot-team-ids <ids>", "Comma-separated snapshot team IDs")
+        .option("--group-ids <ids>", "Comma-separated group IDs")
+        .option("--branch-ids <ids>", "Comma-separated branch IDs")
+        .option("--attribute-ids <ids>", "Comma-separated attribute IDs")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List workflow scores for a snapshot",
+            command: "dx snapshots workflowScores list --id MjUyNbaY",
+        },
+        {
+            label: "List snapshot workflow scores as JSON",
+            command: "dx --json snapshots workflowScores list --id MjUyNbaY",
+        },
+        {
+            label: "Filter workflow scores by team IDs",
+            command: "dx snapshots workflowScores list --id MjUyNbaY --team-ids MTExNDg5,MTExNDg4",
+        },
+        {
+            label: "Filter workflow scores by snapshot team IDs",
+            command: "dx snapshots workflowScores list --id MjUyNbaY --snapshot-team-ids NTcxMDM",
+        },
+        {
+            label: "Filter workflow scores by group IDs",
+            command: "dx snapshots workflowScores list --id MjUyNbaY --group-ids MzYyMjM",
+        },
+        {
+            label: "Filter workflow scores by attribute IDs",
+            command: "dx snapshots workflowScores list --id MjUyNbaY --attribute-ids NzI4OA",
+        },
+        {
+            label: "Filter workflow scores by branch IDs",
+            command: "dx snapshots workflowScores list --id MjUyNbaY --branch-ids MQ",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const snapshotId = parseRequiredTextOption(options.id, "--id");
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listSnapshotWorkflowScores(runtime, snapshotId, options);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderSnapshotWorkflowScores(response, snapshotId, options, runtime);
+        }
+    }));
+    snapshots.addCommand(workflowScores);
     return snapshots;
 }
 async function listSnapshotDriverComments(runtime, options) {
@@ -196,6 +250,57 @@ async function listSnapshotTeams(runtime, snapshotId) {
     });
     return response.body;
 }
+async function listSnapshotWorkflowScores(runtime, snapshotId, options) {
+    const response = await request(runtime, "/snapshots.workflowScores.list", {
+        method: "GET",
+        query: {
+            snapshot_id: snapshotId,
+            ...snapshotFilterQuery(options, "apiKey"),
+        },
+    });
+    return response.body;
+}
+// The web app names some filter params differently from the API. Attributes
+// have no webKey because the web app only accepts decoded tag IDs.
+const SNAPSHOT_FILTER_KEYS = [
+    { option: "teamIds", apiKey: "team_ids", webKey: "team_ids" },
+    {
+        option: "snapshotTeamIds",
+        apiKey: "snapshot_team_ids",
+        webKey: "snapshot_team_ids",
+    },
+    { option: "groupIds", apiKey: "group_ids", webKey: "group_ids" },
+    { option: "branchIds", apiKey: "branch_ids", webKey: "branch" },
+    { option: "attributeIds", apiKey: "attribute_ids" },
+];
+// The web app can't combine groups with snapshot teams (selecting a group
+// clears snapshot teams) and only selects one branch at a time, so drop those
+// filters from the link and report which ones were left out
+function snapshotWebFilters(options) {
+    const webOptions = { ...options };
+    const omittedFlags = [];
+    if (parseCommaSeparatedValues(options.groupIds) &&
+        parseCommaSeparatedValues(options.snapshotTeamIds)) {
+        webOptions.snapshotTeamIds = undefined;
+        omittedFlags.push("--snapshot-team-ids");
+    }
+    if ((parseCommaSeparatedValues(options.branchIds)?.length ?? 0) > 1) {
+        webOptions.branchIds = undefined;
+        omittedFlags.push("--branch-ids");
+    }
+    if (parseCommaSeparatedValues(options.attributeIds)) {
+        omittedFlags.push("--attribute-ids");
+    }
+    return { query: snapshotFilterQuery(webOptions, "webKey"), omittedFlags };
+}
+function snapshotFilterQuery(options, target) {
+    return Object.fromEntries(SNAPSHOT_FILTER_KEYS.flatMap((keys) => {
+        const key = keys[target];
+        return key
+            ? [[key, parseCommaSeparatedValues(options[keys.option])?.join(",")]]
+            : [];
+    }));
+}
 async function getSnapshotInfo(runtime, snapshotId) {
     const response = await request(runtime, "/snapshots.info", {
         method: "GET",
@@ -314,6 +419,70 @@ function renderSnapshotInfo(snapshot, snapshotId, runtime) {
     }
     renderRichText(blocks);
 }
+function renderSnapshotWorkflowScores(response, snapshotId, filterOptions, runtime) {
+    const { results } = response;
+    const filterDetails = workflowScoresFilterDetails(response.filters);
+    const webFilters = snapshotWebFilters(filterOptions);
+    const blocks = [ui.h1("Snapshot Workflow Scores")];
+    if (filterDetails.length > 0) {
+        blocks.push(ui.dl(filterDetails, { termWidth: 17 }));
+    }
+    blocks.push(ui.p(`Displaying ${ui.bold(results.length.toString())} ${results.length === 1 ? "workflow" : "workflows"}.`), ui.p(ui.link(
+    // Sort the web view by workflow name, ascending (sb = sort by, sr = sort reversed)
+    snapshotWebLink(snapshotId, "workflow", runtime, {
+        sb: "name",
+        sr: "false",
+        ...webFilters.query,
+    }))));
+    if (webFilters.omittedFlags.length > 0) {
+        blocks.push(ui.p(ui.dim(`Web link omits ${webFilters.omittedFlags.join(" and ")}; the web app can't apply those filters.`)));
+    }
+    if (results.length === 0) {
+        blocks.push(ui.p(ui.dim("(None)")));
+        renderRichText(blocks);
+        return;
+    }
+    for (const result of results) {
+        blocks.push(ui.h2(result.workflow.name));
+        blocks.push(ui.p(result.workflow.prompt));
+        if (result.hidden) {
+            blocks.push(ui.p(ui.dim("(Hidden)")));
+            continue;
+        }
+        const benchmark = result.workflow.benchmark;
+        const benchmarkValue = benchmark
+            ? `${benchmark.name} (${benchmark.year}) p50=${benchmark.p_50}, p75=${benchmark.p_75}, p90=${benchmark.p_90}`
+            : ui.dim("(None)");
+        blocks.push(ui.dl([
+            ui.dli("Workflow ID", result.workflow.id),
+            ui.dli("Score", formatNumber(result.score)),
+            optionalDetail("Respondents", formatNumber(result.total_respondents), result.total_respondents),
+            optionalDetail("Cohort size", formatNumber(result.total_cohort), result.total_cohort),
+            ui.dli("Unit", formatText(result.workflow.unit)),
+            ui.dli("Lower is better", result.workflow.lower_is_better ? "Yes" : "No"),
+            ui.dli("Benchmark", benchmarkValue),
+        ].filter((detail) => detail !== null), { termWidth: 17 }));
+        blocks.push(ui.h3("Distribution"));
+        blocks.push(ui.p(formatWorkflowDistributionTable(result.distribution)));
+    }
+    renderRichText(blocks);
+}
+function workflowScoresFilterDetails(filters) {
+    const names = (items) => items.map((item) => item.name).join(", ");
+    const attributes = filters.attribute_groups.flatMap((group) => group.attributes.map((attribute) => ({
+        id: attribute.id,
+        name: `${group.name}: ${attribute.name}`,
+    })));
+    return [
+        ["Teams", filters.teams],
+        ["Snapshot teams", filters.snapshot_teams],
+        ["Groups", filters.groups],
+        ["Branches", filters.branches],
+        ["Attributes", attributes],
+    ]
+        .filter(([, items]) => items.length > 0)
+        .map(([term, items]) => ui.dli(term, names(items)));
+}
 function renderSnapshots(snapshots, runtime) {
     const blocks = [ui.h1("Snapshots")];
     blocks.push(ui.p(`Displaying ${ui.bold(snapshots.length.toString())} snapshots.`));
@@ -466,19 +635,44 @@ function formatBenchmarkTable(teamScore) {
         ["vs_90th", formatBenchmarkNumber(teamScore.vs_90th)],
     ];
     const columns = ["Benchmark", "Value"];
-    const widths = columns.map((column, index) => Math.max(column.length, ...rows.map((row) => row[index].length)));
-    const border = `+${widths.map((width) => "-".repeat(width + 2)).join("+")}+`;
-    const header = `| ${columns.map((column, index) => column.padEnd(widths[index])).join(" | ")} |`;
-    const body = rows.map((row) => `| ${row.map((cell, index) => cell.padEnd(widths[index])).join(" | ")} |`);
-    return [border, header, border, ...body, border].join("\n");
+    return buildTable(columns, rows);
 }
 function formatBenchmarkNumber(value) {
     return typeof value === "number" && Number.isFinite(value)
         ? value.toString()
         : "(None)";
 }
-function snapshotWebLink(snapshotId, section, runtime) {
-    return ui.webLink(`/snapshots/${snapshotId}/${section}`, runtime);
+function formatWorkflowDistributionTable(distribution) {
+    if (distribution.length === 0) {
+        return ui.dim("(None)");
+    }
+    const rows = distribution.map((item) => [
+        item.label.trim(),
+        item.value.toString(),
+        item.count.toString(),
+    ]);
+    const columns = ["Label", "Value", "Count"];
+    return buildTable(columns, rows);
+}
+function buildTable(columns, rows) {
+    const widths = columns.map((column, index) => Math.max(column.length, ...rows.map((row) => row[index].length)));
+    const border = `+${widths.map((width) => "-".repeat(width + 2)).join("+")}+`;
+    const header = `| ${columns.map((column, index) => column.padEnd(widths[index])).join(" | ")} |`;
+    const body = rows.map((row) => `| ${row.map((cell, index) => cell.padEnd(widths[index])).join(" | ")} |`);
+    return [border, header, border, ...body, border].join("\n");
+}
+function snapshotWebLink(snapshotId, section, runtime, queryParams = {}) {
+    let urlPath = `/snapshots/${snapshotId}/${section}`;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(queryParams)) {
+        if (value !== undefined) {
+            params.set(key, value);
+        }
+    }
+    if (params.size > 0) {
+        urlPath += `?${params.toString()}`;
+    }
+    return ui.webLink(urlPath, runtime);
 }
 function parseRequiredTextOption(value, flag) {
     if (typeof value !== "string" || value.trim().length === 0) {

package/dist/commands/studio/reports.js

@@ -370,12 +370,20 @@ function studioReportToYaml(report) {
         viewer_emails: report.viewer_emails ?? [],
         edit_access_type: report.edit_access_type,
         editor_emails: report.editor_emails ?? [],
+        sections: report.sections?.map((section) => ({
+            id: section.id,
+            name: section.name,
+            description: section.description,
+        })),
         tiles: report.tiles.map((tile) => ({
             id: tile.id,
             title: tile.title,
             sql: tile.sql,
             chart_type: tile.chart_type,
             chart_config: tile.chart_config,
+            section_id: tile.section_id,
+            width: tile.width,
+            height: tile.height,
         })),
     };
     return stringifyYaml(payload, { blockQuote: "literal" });

package/dist/commands/workflow-blank-template.yaml

@@ -31,6 +31,12 @@ trigger_type: ANY
 #   - squad_id: "<team id>"                 # user_id or squad_id
 #     squad_linkage_id: null                # optional
 
+# timeout: how long a run can stay in progress before it times out. Only
+# applies when execution_type is EVENT_DRIVEN (ignored for SIMPLE). One of
+# ONE_HOUR, SIX_HOURS, TWELVE_HOURS, ONE_DAY, THREE_DAYS, SEVEN_DAYS,
+# FOURTEEN_DAYS or THIRTY_DAYS. Optional; if not set, a default of 1 hour is used.
+# timeout: ONE_DAY
+
 # Which entities the workflow can run against (only used when scope is ENTITY).
 # entity_filter_type: "ENTITY_TYPES" or "SQL"
 entity_filter_type: ENTITY_TYPES

package/dist/commands/workflowsRendering.js

@@ -72,6 +72,9 @@ function coreContent(workflow) {
         ui.dli("Scope", workflowScopeLabel(workflow.scope)),
         ui.dli("Execution type", workflowExecutionTypeLabel(workflow.execution_type)),
         ui.dli("Who can run", `${workflowTriggerTypeLabel(workflow.trigger_type)}  ${ui.dim(workflowTriggerTypeDescription(workflow.trigger_type))}`),
+        ...(workflow.timeout
+            ? [ui.dli("Timeout", ui.code(workflow.timeout))]
+            : []),
     ], { termWidth: 16 }));
     return blocks;
 }

package/package.json

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