@get-dx/cli 0.1.0

package/dist/commands/catalog/entityTypes.js

@@ -0,0 +1,402 @@
+import fs from "fs";
+import { Command } from "commander";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { createExampleText, getContext, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
+import { CliError, EXIT_CODES, HttpError } from "../../errors.js";
+import { request } from "../../http.js";
+import { renderJson, renderRichText } from "../../renderers.js";
+import { buildRuntime } from "../../runtime.js";
+import * as ui from "../../ui.js";
+import { renderEntityType, renderEntityTypeDeleted, renderEntityTypeList, } from "./entityTypesRendering.js";
+export function entityTypesCommand() {
+    const entityTypes = new Command()
+        .name("entityTypes")
+        .description("Manage catalog entity types");
+    entityTypes
+        .command("create")
+        .description("Create a new entity type from a YAML file or stdin. The `init` command can be used to generate a starting template.")
+        .option("--from-file <path>", "Read a YAML file and create an entity type from its contents")
+        .option("--from-stdin", "Read YAML from stdin and create an entity type from its contents")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Generate a blank template first",
+            command: "dx catalog entityTypes init ./my-entity-type.yaml",
+        },
+        {
+            label: "Create an entity type from a YAML file",
+            command: "dx catalog entityTypes create --from-file ./my-entity-type.yaml",
+        },
+        {
+            label: "Create an entity type from stdin",
+            command: "cat ./my-entity-type.yaml | dx catalog entityTypes create --from-stdin",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const modeCount = [options.fromFile, options.fromStdin].filter(Boolean).length;
+        if (modeCount === 0) {
+            throw new CliError("One of --from-file or --from-stdin is required", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        if (modeCount > 1) {
+            throw new CliError("--from-file and --from-stdin are mutually exclusive", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = buildRuntime(getContext(command));
+        let raw;
+        if (options.fromFile) {
+            raw = readYamlFile(options.fromFile);
+        }
+        else {
+            raw = await readYamlStdin();
+        }
+        const payload = buildCreatePayload(raw);
+        const response = await createEntityType(runtime, payload);
+        if (runtime.context.json) {
+            renderJson({ ok: true, entity_type: response.entity_type });
+        }
+        else {
+            renderEntityType(response.entity_type, `${ui.success(ui.GLYPHS.CHECK)} Entity type created`);
+        }
+    }));
+    entityTypes
+        .command("delete")
+        .description("Delete an entity type from your software catalog")
+        .argument("<identifier>", "Entity type identifier")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Delete the `service` entity type",
+            command: "dx catalog entityTypes delete service",
+        },
+        {
+            label: "Delete an entity type and return JSON",
+            command: "dx catalog entityTypes delete service --json",
+        },
+    ]))
+        .action(wrapAction(async (identifier, _options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await deleteEntityType(runtime, identifier);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderEntityTypeDeleted(response.entity_type);
+        }
+    }));
+    entityTypes
+        .command("info")
+        .argument("<identifier>", "Entity type identifier")
+        .option("--include <include>", "Show only these comma-separated sections: core, properties, aliases")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Fetch info for the `service` entity type",
+            command: "dx catalog entityTypes info service",
+        },
+        {
+            label: "Fetch info and return as JSON",
+            command: "dx catalog entityTypes info service --json",
+        },
+        {
+            label: "Fetch info but only include the `core` and `properties` sections",
+            command: "dx catalog entityTypes info service --include core,properties",
+        },
+    ]))
+        .action(wrapAction(async (identifier, options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await getEntityType(runtime, identifier);
+        const processedEntityType = processEntityTypeIncludes(response.entity_type, options);
+        if (runtime.context.json) {
+            renderJson(processedEntityType);
+        }
+        else {
+            renderEntityType(processedEntityType);
+        }
+    }));
+    entityTypes
+        .command("init")
+        .description("Write an entity type YAML file, either from an existing entity type or as a blank template")
+        .argument("<path>", "File path to write the YAML to")
+        .option("--identifier <identifier>", "Fetch an existing entity type and use it as the template")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Write a blank entity type template",
+            command: "dx catalog entityTypes init ./my-entity-type.yaml",
+        },
+        {
+            label: "Initialize from an existing entity type",
+            command: "dx catalog entityTypes init ./my-entity-type.yaml --identifier service",
+        },
+    ]))
+        .action(wrapAction(async (path, options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        if (options.identifier) {
+            const identifier = options.identifier;
+            let entityTypeResponse;
+            try {
+                entityTypeResponse = await getEntityType(runtime, identifier);
+            }
+            catch (err) {
+                const exitCode = err instanceof HttpError &&
+                    err.status !== undefined &&
+                    err.status < 500
+                    ? EXIT_CODES.ARGUMENT_ERROR
+                    : EXIT_CODES.RETRY_RECOMMENDED;
+                throw new CliError(`Failed to fetch entity type "${identifier}": ${err instanceof Error ? err.message : String(err)}`, exitCode);
+            }
+            const yaml = entityTypeToYaml(entityTypeResponse.entity_type);
+            fs.writeFileSync(path, yaml, "utf8");
+            if (runtime.context.json) {
+                renderJson({ ok: true, identifier, path });
+            }
+            else {
+                renderRichText([
+                    ui.p(`${ui.success(ui.GLYPHS.CHECK)} Entity type written to ${ui.code(path)}.`),
+                    ui.p(`Edit the file, then run: ${ui.code(`dx catalog entityTypes update ${identifier} --from-file ${path}`)}`),
+                ]);
+            }
+        }
+        else {
+            fs.writeFileSync(path, ENTITY_TYPE_BLANK_TEMPLATE_YAML, "utf8");
+            if (runtime.context.json) {
+                renderJson({ ok: true, path });
+            }
+            else {
+                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 entityTypes create --from-file ${path}`)}`),
+                ]);
+            }
+        }
+    }));
+    entityTypes
+        .command("list")
+        .description("List all entity types in your software catalog")
+        .option("--cursor <cursor>", "Cursor for the next page of results")
+        .option("--limit <n>", "Max entity types per page (default is 50)", (value) => parsePositiveIntOption(value, "--limit"))
+        .option("--include <include>", "Show only these comma-separated sections: core, properties, aliases")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List the first page of entity types",
+            command: "dx catalog entityTypes list",
+        },
+        {
+            label: "List with a limit and return JSON",
+            command: "dx catalog entityTypes list --limit 10 --json",
+        },
+        {
+            label: "Fetch the next page using a cursor from the prior response",
+            command: "dx catalog entityTypes list --cursor avsgf30ccan3",
+        },
+        {
+            label: "List and only include the core section",
+            command: "dx catalog entityTypes list --include core",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await listEntityTypes(runtime, {
+            cursor: options.cursor,
+            limit: options.limit,
+        });
+        const processedEntityTypes = response.entity_types.map((entityType) => processEntityTypeIncludes(entityType, options));
+        if (runtime.context.json) {
+            renderJson({ ...response, entity_types: processedEntityTypes });
+        }
+        else {
+            renderEntityTypeList(processedEntityTypes, response.response_metadata?.next_cursor ?? null);
+        }
+    }));
+    entityTypes
+        .command("update")
+        .description("Update an existing entity type from a YAML file or stdin. The `init` command can be used to initialize the entity type file.")
+        .argument("<identifier>", "The unique identifier of the entity type")
+        .option("--from-file <path>", "Read a YAML file and update the entity type with its contents")
+        .option("--from-stdin", "Read YAML from stdin and update the entity type with its contents")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Initialize a file first",
+            command: "dx catalog entityTypes init --identifier service ./my-entity-type.yaml",
+        },
+        {
+            label: "Update an entity type from a YAML file",
+            command: "dx catalog entityTypes update service --from-file ./my-entity-type.yaml",
+        },
+        {
+            label: "Update an entity type from stdin",
+            command: "cat ./my-entity-type.yaml | dx catalog entityTypes update service --from-stdin",
+        },
+    ]))
+        .action(wrapAction(async (identifier, options, command) => {
+        const modeCount = [options.fromFile, options.fromStdin].filter(Boolean).length;
+        if (modeCount === 0) {
+            throw new CliError("One of --from-file or --from-stdin is required", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        if (modeCount > 1) {
+            throw new CliError("--from-file and --from-stdin are mutually exclusive", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = buildRuntime(getContext(command));
+        let raw;
+        if (options.fromFile) {
+            raw = readYamlFile(options.fromFile);
+        }
+        else {
+            raw = await readYamlStdin();
+        }
+        const payload = buildUpdatePayload(identifier, raw);
+        const response = await updateEntityType(runtime, payload);
+        if (runtime.context.json) {
+            renderJson({ ok: true, entity_type: response.entity_type });
+        }
+        else {
+            renderEntityType(response.entity_type, `${ui.success(ui.GLYPHS.CHECK)} Entity type updated`);
+        }
+    }));
+    return entityTypes;
+}
+export async function getEntityType(runtime, identifier) {
+    const response = await request(runtime, "/catalog.entityTypes.info", {
+        method: "GET",
+        query: { identifier },
+    });
+    return response.body;
+}
+async function deleteEntityType(runtime, identifier) {
+    const response = await request(runtime, "/catalog.entityTypes.delete", {
+        method: "POST",
+        query: { identifier },
+    });
+    return response.body;
+}
+async function listEntityTypes(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.entityTypes.list", {
+        method: "GET",
+        query,
+    });
+    return response.body;
+}
+async function createEntityType(runtime, payload) {
+    const response = await request(runtime, "/catalog.entityTypes.create", {
+        method: "POST",
+        body: payload,
+    });
+    return response.body;
+}
+async function updateEntityType(runtime, payload) {
+    const response = await request(runtime, "/catalog.entityTypes.update", {
+        method: "POST",
+        body: payload,
+    });
+    return response.body;
+}
+// --- Include helpers ---
+const ENTITY_TYPE_INCLUDE_SECTIONS = ["core", "properties", "aliases"];
+const ENTITY_TYPE_SECTION_KEYS = {
+    core: [
+        "identifier",
+        "name",
+        "description",
+        "icon",
+        "ordering",
+        "created_at",
+        "updated_at",
+    ],
+    properties: ["properties"],
+    aliases: ["aliases"],
+};
+function processEntityTypeIncludes(entityType, options) {
+    const includeSections = parseEntityTypeIncludeSections(options.include);
+    if (includeSections.length === 0) {
+        return entityType;
+    }
+    const out = {};
+    for (const section of includeSections) {
+        for (const key of ENTITY_TYPE_SECTION_KEYS[section]) {
+            if (key in entityType) {
+                out[key] = entityType[key];
+            }
+        }
+    }
+    return out;
+}
+function parseEntityTypeIncludeSections(include) {
+    if (!include) {
+        return [];
+    }
+    const results = include.split(",");
+    for (const result of results) {
+        if (!ENTITY_TYPE_INCLUDE_SECTIONS.includes(result)) {
+            throw new CliError(`Invalid --include "${result}". Expected one of: ${ENTITY_TYPE_INCLUDE_SECTIONS.join(", ")}`, EXIT_CODES.ARGUMENT_ERROR);
+        }
+    }
+    return results;
+}
+// --- YAML helpers ---
+const ENTITY_TYPE_BLANK_TEMPLATE_YAML = fs.readFileSync(new URL("./entity-type-blank-template.yaml", import.meta.url), "utf8");
+const ENTITY_TYPE_IGNORED_KEYS = [
+    // Reporting on state
+    "created_at",
+    "updated_at",
+];
+const PROPERTY_IGNORED_KEYS = [
+    // Reporting on state
+    "created_at",
+    "updated_at",
+];
+function entityTypeToYaml(entityType) {
+    const obj = { ...entityType };
+    for (const key of ENTITY_TYPE_IGNORED_KEYS) {
+        delete obj[key];
+    }
+    if (obj.properties) {
+        obj.properties = obj.properties.map((prop) => {
+            const p = { ...prop };
+            for (const key of PROPERTY_IGNORED_KEYS) {
+                delete p[key];
+            }
+            return p;
+        });
+    }
+    return stringifyYaml(obj, { blockQuote: "literal" });
+}
+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);
+    }
+    return parseYaml(content);
+}
+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));
+        });
+    });
+}
+function buildCreatePayload(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CliError("YAML content must be an object", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return raw;
+}
+function buildUpdatePayload(identifier, raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CliError("YAML content must be an object", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return { ...raw, identifier };
+}

package/dist/commands/catalog/entityTypesRendering.js

@@ -0,0 +1,159 @@
+import { renderRichText } from "../../renderers.js";
+import * as ui from "../../ui.js";
+export function renderEntityTypeList(entityTypes, nextCursor) {
+    const blocks = [ui.h1("Entity Types")];
+    blocks.push(ui.p(`Displaying ${ui.bold(entityTypes.length.toString())} entity types.`));
+    if (nextCursor) {
+        blocks.push(ui.p(`Next cursor: ${ui.code(nextCursor)}`));
+    }
+    for (const entityType of entityTypes) {
+        if (entityType.name && entityType.identifier) {
+            blocks.push(ui.h2(`${entityType.name} (${ui.code(entityType.identifier)})`));
+        }
+        else if (entityType.identifier) {
+            blocks.push(ui.h2(ui.code(entityType.identifier)));
+        }
+        else {
+            blocks.push(ui.h2("Entity Type"));
+        }
+        if (entityType.identifier) {
+            blocks.push(ui.h3("Core attributes"));
+            blocks.push(...coreContent(entityType));
+        }
+        if (entityType.properties) {
+            blocks.push(ui.h3("Properties"));
+            blocks.push(...propertiesContent(entityType.properties));
+        }
+        if (entityType.aliases) {
+            blocks.push(ui.h3("Aliases"));
+            blocks.push(...aliasesContent(entityType.aliases));
+        }
+    }
+    renderRichText(blocks);
+}
+export function renderEntityType(entityType, title = "Entity Type Information") {
+    renderRichText([
+        ui.h1(title),
+        entityType.identifier
+            ? [ui.h2("Core attributes"), ...coreContent(entityType)]
+            : null,
+        entityType.properties
+            ? [ui.h2("Properties"), ...propertiesContent(entityType.properties)]
+            : null,
+        entityType.aliases
+            ? [ui.h2("Aliases"), ...aliasesContent(entityType.aliases)]
+            : null,
+    ]);
+}
+export function renderEntityTypeDeleted(entityType) {
+    renderRichText([
+        ui.h1(`${ui.success("✓")} Entity type deleted`),
+        ui.p(`The entity type ${ui.code(entityType.identifier)} has been deleted.`),
+    ]);
+}
+function coreContent(entityType) {
+    return [
+        ui.dl([
+            ui.dli("Name", [ui.p(entityType.name ?? ui.dim("(None)"), false)]),
+            ui.dli("Identifier", [ui.p(ui.code(entityType.identifier), false)]),
+            ui.dli("Description", [
+                ui.p(entityType.description || ui.dim("(None)"), false),
+            ]),
+            ui.dli("Icon", [ui.p(entityType.icon ?? ui.dim("(None)"), false)]),
+            ui.dli("Ordering", [
+                ui.p(entityType.ordering?.toString() ?? ui.dim("(None)"), false),
+            ]),
+            ui.dli("Created", [
+                ui.p(ui.timestampSummary(entityType.created_at), false),
+            ]),
+            ui.dli("Last updated", [
+                ui.p(ui.timestampSummary(entityType.updated_at)),
+            ]),
+        ], { termWidth: 14 }),
+    ];
+}
+function propertiesContent(properties) {
+    if (properties.length === 0) {
+        return [ui.p(ui.dim("(No properties defined)"))];
+    }
+    return [ui.ul(properties.map(propertyListItem))];
+}
+function propertyListItem(property) {
+    const badges = [];
+    if (property.visibility === "hidden")
+        badges.push(ui.dim("[hidden]"));
+    if (property.is_required)
+        badges.push(ui.bold("[required]"));
+    const header = [
+        ui.bold(property.name),
+        `(${ui.code(property.identifier)}):`,
+        ui.code(property.type),
+        ...badges,
+    ].join(" ");
+    const lines = [ui.p(header, false)];
+    if (property.description) {
+        lines.push(ui.p(ui.dim(property.description), false));
+    }
+    lines.push(...propertyDefinitionLines(property));
+    return ui.li(lines);
+}
+function propertyDefinitionLines(property) {
+    const { type, definition } = property;
+    if (type === "select" || type === "multi_select") {
+        const options = definition.options;
+        if (options && options.length > 0) {
+            return [
+                ui.p(`Options: ${options.map((o) => o.value).join(", ")}`, false),
+            ];
+        }
+    }
+    if (type === "computed") {
+        const sql = definition.sql;
+        const outputType = definition.output_type;
+        const aggregation = definition.output_aggregation;
+        const lines = [];
+        if (outputType) {
+            const outputLine = aggregation
+                ? `Output: ${ui.code(outputType)} ${ui.dim(`(aggregation: ${aggregation})`)}`
+                : `Output: ${ui.code(outputType)}`;
+            lines.push(ui.p(outputLine, false));
+        }
+        if (sql) {
+            const firstLine = sql.split("\n")[0];
+            const isLong = firstLine.length > 80 || sql.includes("\n");
+            const truncated = firstLine.length > 80 ? firstLine.slice(0, 80) : firstLine;
+            const display = isLong ? truncated + ui.dim(" …") : truncated;
+            lines.push(ui.p(`SQL: ${ui.code(display)}`, false));
+        }
+        return lines;
+    }
+    if (type === "file_matching_rule") {
+        const filePath = definition.file_path;
+        const ruleType = definition.rule_type;
+        const matchExpression = definition.match_expression;
+        return [
+            ui.p(`Rule type: ${ui.code(ruleType ?? "(none)")}`, false),
+            ui.p(`File path: ${ui.code(filePath ?? "(none)")}`, false),
+            ui.p(`Expression: ${ui.code(matchExpression ?? "(none)")}`, false),
+        ];
+    }
+    if (type === "url") {
+        const cta = definition.call_to_action;
+        const ctaType = definition.call_to_action_type;
+        if (cta) {
+            return [ui.p(`CTA: ${ui.code(cta)} ${ui.dim(`(${ctaType})`)}`, false)];
+        }
+    }
+    if (Object.keys(definition).length === 0) {
+        return [];
+    }
+    return [ui.json(definition)];
+}
+function aliasesContent(aliases) {
+    if (Object.keys(aliases).length === 0) {
+        return [ui.p(ui.dim("(No aliases defined)"))];
+    }
+    else {
+        return [ui.ul(Object.keys(aliases).map((aliasKey) => ui.li(aliasKey)))];
+    }
+}

package/dist/commands/catalog.js

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

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

@@ -0,0 +1,82 @@
+# Scorecard configuration
+#
+# Edit this file, then run:
+#
+# ```
+# dx scorecards create --from-file <path>
+# ```
+#
+# After the scorecard is created, make updates by running:
+#
+# ```
+# dx scorecards update --id <id> --from-file <path>
+# ```
+
+name: ""
+description: ""
+published: false
+
+# type: "LEVEL" (levels-based) or "POINTS" (points-based)
+type: LEVEL
+
+# Filter which entities this scorecard assesses.
+# entity_filter_type: "entity_types" or "sql"
+entity_filter_type: entity_types
+# List of entity type identifiers to include (when entity_filter_type is "entity_types")
+entity_filter_type_identifiers:
+  - service
+# SQL filter expression (when entity_filter_type is "sql")
+entity_filter_sql: ""
+
+# User IDs of editors
+editors: []
+
+# Tags to apply to the scorecard
+tags: []
+
+# --- LEVEL-type fields (remove if using POINTS type) ---
+empty_level_label: "Incomplete"
+empty_level_color: "#cbd5e1"
+levels:
+  - key: bronze
+    name: Bronze
+    color: "#fb923c"
+    rank: 1
+  - key: silver
+    name: Silver
+    color: "#9ca3af"
+    rank: 2
+  - key: gold
+    name: Gold
+    color: "#fbbf24"
+    rank: 3
+
+# --- POINTS-type fields (remove if using LEVEL type) ---
+# check_groups:
+#   - key: reliability
+#     name: Reliability
+#     ordering: 0
+
+# Checks apply to both LEVEL and POINTS scorecards
+checks:
+  - name: ""
+    description: ""
+    sql: |-
+      select 'PASS' as status
+    ordering: 0
+    published: false
+    estimated_dev_days: null
+    external_url: ""
+    # Entity filter: restrict which entities this check runs against
+    filter_sql: ""
+    filter_message: ""
+    # Output settings: capture a value from the check query
+    output_enabled: false
+    output_type: null
+    output_custom_options: null
+    output_aggregation: null
+    # For LEVEL type: reference a level key from the levels list above
+    scorecard_level_key: bronze
+    # For POINTS type: reference a check group key and assign points
+    # scorecard_check_group_key: reliability
+    # points: 10