@get-dx/cli 0.1.0

package/dist/commands/catalog/entities.js

@@ -0,0 +1,596 @@
+import { Command } from "commander";
+import { createExampleText, getContext, parsePositiveIntOption, wrapAction, } from "../../commandHelpers.js";
+import { CliError, EXIT_CODES, HttpError } from "../../errors.js";
+import { request } from "../../http.js";
+import { renderJson } from "../../renderers.js";
+import { buildRuntime } from "../../runtime.js";
+import { getEntityType } from "./entityTypes.js";
+import { renderEntity, renderEntityDeleted, renderEntityList, renderEntityScorecardList, renderEntityTaskList, } from "./entitiesRendering.js";
+import * as ui from "../../ui.js";
+export function entitiesCommand() {
+    const entities = new Command()
+        .name("entities")
+        .description("Manage entities");
+    entities
+        .command("create")
+        .description("Create a new entity in your software catalog")
+        .option("--type <type>", "Entity type identifier (required)")
+        .option("--identifier <identifier>", "Unique identifier for the new entity (required)")
+        .option("--name <name>", "Display name of the entity")
+        .option("--description <desc>", "Description of the entity")
+        .option("--owner-team-ids <ids>", "Comma-separated owner team IDs")
+        .option("--owner-user-ids <ids>", "Comma-separated owner user IDs")
+        .option("--property <kv>", "Set a property value as key=value. Repeat for multiple properties.", (val, prev) => [...prev, val], [])
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Create a new service entity",
+            command: "dx catalog entities create --type service --identifier my-service",
+        },
+        {
+            label: "Create with a name and return as JSON",
+            command: 'dx catalog entities create --type service --identifier my-service --name "My Service" --json',
+        },
+        {
+            label: "Create and assign owner teams",
+            command: "dx catalog entities create --type service --identifier my-service --owner-team-ids MzI1NTA,MzI1NTk",
+        },
+        {
+            label: "Create with properties",
+            command: 'dx catalog entities create --type service --identifier my-service --property tier=Tier-1 --property "languages=Ruby,TypeScript"',
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        if (!options.identifier) {
+            throw new CliError("--identifier is required", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        if (!options.type) {
+            throw new CliError("--type is required", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = buildRuntime(getContext(command));
+        const properties = await resolvePropertiesForEntityType(runtime, options.type, options.property);
+        const response = await createEntity(runtime, options.identifier, {
+            type: options.type,
+            name: options.name,
+            description: options.description,
+            owner_team_ids: options.ownerTeamIds
+                ?.split(",")
+                .map((s) => s.trim()),
+            owner_user_ids: options.ownerUserIds
+                ?.split(",")
+                .map((s) => s.trim()),
+            properties,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderEntity(response.entity);
+        }
+    }));
+    entities
+        .command("delete")
+        .description("Delete an entity from your software catalog")
+        .argument("<identifier>", "Entity identifier")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Delete the `login-frontend` entity",
+            command: "dx catalog entities delete login-frontend",
+        },
+        {
+            label: "Delete an entity and return JSON",
+            command: "dx catalog entities delete login-frontend --json",
+        },
+    ]))
+        .action(wrapAction(async (identifier, _options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await deleteEntity(runtime, identifier);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderEntityDeleted(response.entity);
+        }
+    }));
+    entities
+        .command("update")
+        .description("Update an entity in your software catalog")
+        .argument("<identifier>", "Entity identifier")
+        .option("--name <name>", "Display name of the entity")
+        .option("--description <desc>", "Description of the entity")
+        .option("--owner-team-ids <ids>", "Comma-separated owner team IDs")
+        .option("--owner-user-ids <ids>", "Comma-separated owner user IDs")
+        .option("--property <kv>", "Set a property value as key=value. Repeat for multiple properties. Use value null to remove a property.", (val, prev) => [...prev, val], [])
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Rename an entity",
+            command: 'dx catalog entities update my-service --name "My Service"',
+        },
+        {
+            label: "Update owners and return JSON",
+            command: "dx catalog entities update my-service --owner-team-ids MzI1NTA,MzI1NTk --json",
+        },
+        {
+            label: "Update properties",
+            command: 'dx catalog entities update my-service --property tier=Tier-1 --property "languages=Ruby,TypeScript"',
+        },
+    ]))
+        .action(wrapAction(async (identifier, options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const properties = await resolvePropertiesForExistingEntity(runtime, identifier, options.property);
+        const response = await updateEntity(runtime, identifier, {
+            ...getEntityMutationOptionValues(options),
+            properties,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderEntity(response.entity, `${ui.success(ui.GLYPHS.CHECK)} Entity updated`);
+        }
+    }));
+    entities
+        .command("upsert")
+        .description("Create a new entity in your software catalog, or update it if it already exists")
+        .option("--type <type>", "Entity type identifier (required)")
+        .option("--identifier <identifier>", "Unique identifier for the entity (required)")
+        .option("--name <name>", "Display name of the entity")
+        .option("--description <desc>", "Description of the entity")
+        .option("--owner-team-ids <ids>", "Comma-separated owner team IDs")
+        .option("--owner-user-ids <ids>", "Comma-separated owner user IDs")
+        .option("--property <kv>", "Set a property value as key=value. Repeat for multiple properties. Use value null to remove a property.", (val, prev) => [...prev, val], [])
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Create a new service entity if it does not exist",
+            command: "dx catalog entities upsert --type service --identifier my-service --name 'My Service'",
+        },
+        {
+            label: "Update owners and return JSON",
+            command: "dx catalog entities upsert --type service --identifier my-service --owner-team-ids MzI1NTA,MzI1NTk --json",
+        },
+        {
+            label: "Set properties while preserving omitted fields",
+            command: 'dx catalog entities upsert --type service --identifier my-service --property tier=Tier-1 --property "languages=Ruby,TypeScript"',
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        if (!options.type) {
+            throw new CliError("--type is required", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        if (!options.identifier) {
+            throw new CliError("--identifier is required", EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const runtime = buildRuntime(getContext(command));
+        const properties = await resolvePropertiesForEntityType(runtime, options.type, options.property);
+        const response = await upsertEntity(runtime, options.identifier, {
+            type: options.type,
+            ...getEntityMutationOptionValues(options),
+            properties,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            const title = response.result === "created_new_entity"
+                ? `${ui.success(ui.GLYPHS.CHECK)} Created new entity`
+                : `${ui.success(ui.GLYPHS.CHECK)} Updated existing entity`;
+            renderEntity(response.entity, title);
+        }
+    }));
+    entities
+        .command("info")
+        .argument("<identifier>", "Entity identifier")
+        .option("--include <include>", "Show only these comma-separated sections: core, owners, properties, aliases")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Fetch info for the `login-frontend` entity",
+            command: "dx catalog entities info login-frontend",
+        },
+        {
+            label: "Fetch info and return as JSON",
+            command: "dx catalog entities info login-frontend --json",
+        },
+        {
+            label: "Fetch info but only include the `core` and `owners` sections",
+            command: "dx catalog entities info login-frontend --include core,owners",
+        },
+    ]))
+        .action(wrapAction(async (identifier, options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await getEntity(runtime, identifier);
+        const processedResponse = processIncludes(response, options);
+        if (runtime.context.json) {
+            renderJson(processedResponse);
+        }
+        else {
+            renderEntity(processedResponse.entity);
+        }
+    }));
+    entities
+        .command("list")
+        .description("List entities from your software catalog")
+        .option("--cursor <cursor>", "Cursor for the next page of results")
+        .option("--limit <n>", "Max entities per page (default is 50)", (value) => parsePositiveIntOption(value, "--limit"))
+        .option("--type <type>", "Only include entities of this type")
+        .option("--search-term <term>", "Filter by name, identifier, squad owner name, and/or user owner name")
+        .option("--include <include>", "Show only these comma-separated sections: core, owners, properties, aliases")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List the first page of entities",
+            command: "dx catalog entities list",
+        },
+        {
+            label: "List with a limit and return JSON",
+            command: "dx catalog entities list --limit 10 --json",
+        },
+        {
+            label: "Search and fetch the next page",
+            command: "dx catalog entities list --search-term payment --cursor avsgf30ccan3",
+        },
+        {
+            label: "List and only include core and owners sections",
+            command: "dx catalog entities list --include core,owners",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await listEntities(runtime, {
+            cursor: options.cursor,
+            limit: options.limit,
+            type: options.type,
+            search_term: options.searchTerm,
+        });
+        const processedEntities = response.entities.map((entity) => processIncludes({ ok: true, entity: entity }, options)
+            .entity);
+        if (runtime.context.json) {
+            renderJson({ ...response, entities: processedEntities });
+        }
+        else {
+            renderEntityList(processedEntities, response.response_metadata?.next_cursor ?? null);
+        }
+    }));
+    entities
+        .command("tasks")
+        .description("Get outstanding initiative tasks for an entity")
+        .argument("<identifier>", "Entity identifier")
+        .option("--cursor <cursor>", "Cursor for the next page of results")
+        .option("--limit <n>", "Max tasks per page (default is 50)", (value) => parsePositiveIntOption(value, "--limit"))
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Get tasks for the `login-frontend` entity",
+            command: "dx catalog entities tasks login-frontend",
+        },
+        {
+            label: "Get tasks and return as JSON",
+            command: "dx catalog entities tasks login-frontend --json",
+        },
+        {
+            label: "Fetch the next page of tasks",
+            command: "dx catalog entities tasks login-frontend --cursor xuvkgfq9t0ty",
+        },
+    ]))
+        .action(wrapAction(async (identifier, options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await getEntityTasks(runtime, identifier, {
+            cursor: options.cursor,
+            limit: options.limit,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderEntityTaskList(response.tasks, response.response_metadata?.next_cursor ?? null);
+        }
+    }));
+    entities
+        .command("scorecards")
+        .description("Get the current scorecard report for an entity")
+        .argument("<identifier>", "Entity identifier")
+        .option("--cursor <cursor>", "Cursor for the next page of results")
+        .option("--limit <n>", "Max scorecards per page (default is 50)", (value) => parsePositiveIntOption(value, "--limit"))
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Get scorecards for the `login-frontend` entity",
+            command: "dx catalog entities scorecards login-frontend",
+        },
+        {
+            label: "Get scorecards and return as JSON",
+            command: "dx catalog entities scorecards login-frontend --json",
+        },
+        {
+            label: "Fetch the next page of scorecards",
+            command: "dx catalog entities scorecards login-frontend --cursor xuvkgfq9t0ty",
+        },
+    ]))
+        .action(wrapAction(async (identifier, options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await getEntityScorecards(runtime, identifier, {
+            cursor: options.cursor,
+            limit: options.limit,
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderEntityScorecardList(response.scorecards, response.response_metadata?.next_cursor ?? null);
+        }
+    }));
+    return entities;
+}
+async function getEntity(runtime, identifier) {
+    const response = await request(runtime, "/catalog.entities.info", {
+        method: "GET",
+        query: { identifier },
+    });
+    return response.body;
+}
+async function listEntities(runtime, params) {
+    const query = {};
+    if (params.cursor !== undefined)
+        query.cursor = params.cursor;
+    if (params.limit !== undefined)
+        query.limit = params.limit;
+    if (params.type !== undefined)
+        query.type = params.type;
+    if (params.search_term !== undefined)
+        query.search_term = params.search_term;
+    const response = await request(runtime, "/catalog.entities.list", {
+        method: "GET",
+        query,
+    });
+    return response.body;
+}
+async function createEntity(runtime, identifier, params) {
+    const response = await request(runtime, "/catalog.entities.create", {
+        method: "POST",
+        body: buildEntityMutationBody(identifier, params),
+    });
+    return response.body;
+}
+async function updateEntity(runtime, identifier, params) {
+    const response = await request(runtime, "/catalog.entities.update", {
+        method: "POST",
+        body: buildEntityMutationBody(identifier, params),
+    });
+    return response.body;
+}
+async function deleteEntity(runtime, identifier) {
+    const response = await request(runtime, "/catalog.entities.delete", {
+        method: "POST",
+        query: { identifier },
+    });
+    return response.body;
+}
+async function upsertEntity(runtime, identifier, params) {
+    const response = await request(runtime, "/catalog.entities.upsert", {
+        method: "POST",
+        body: buildEntityMutationBody(identifier, params),
+    });
+    return response.body;
+}
+async function getEntityScorecards(runtime, identifier, params) {
+    const query = { identifier };
+    if (params.cursor !== undefined)
+        query.cursor = params.cursor;
+    if (params.limit !== undefined)
+        query.limit = params.limit;
+    const response = await request(runtime, "/catalog.entities.scorecards", {
+        method: "GET",
+        query,
+    });
+    return response.body;
+}
+async function getEntityTasks(runtime, identifier, params) {
+    const query = { identifier };
+    if (params.cursor !== undefined)
+        query.cursor = params.cursor;
+    if (params.limit !== undefined)
+        query.limit = params.limit;
+    const response = await request(runtime, "/catalog.entities.tasks", {
+        method: "GET",
+        query,
+    });
+    return response.body;
+}
+// --- Property parsing helpers ---
+export function parseEntityProperties(entityTypeIdentifier, rawProperties, knownProperties) {
+    const propMap = new Map(knownProperties.map((p) => [p.identifier, p]));
+    const result = {};
+    for (const kv of rawProperties) {
+        const eqIndex = kv.indexOf("=");
+        if (eqIndex === -1) {
+            throw new CliError(`Invalid --property "${kv}": expected format key=value`, EXIT_CODES.ARGUMENT_ERROR);
+        }
+        const key = kv.slice(0, eqIndex);
+        const rawValue = kv.slice(eqIndex + 1);
+        const prop = propMap.get(key);
+        if (!prop) {
+            const availableProperties = Array.from(propMap.keys())
+                .sort()
+                .map((k) => `\`${k}\``)
+                .join(", ");
+            const availablePropertiesText = availableProperties.length > 0 ? availableProperties : "(none)";
+            throw new CliError(`Unknown property \`${key}\` for entity type \`${entityTypeIdentifier}\`. Available properties: ${availablePropertiesText}`, EXIT_CODES.ARGUMENT_ERROR);
+        }
+        result[key] = parsePropertyValue(prop, rawValue);
+    }
+    return result;
+}
+export function parsePropertyValue(prop, rawValue) {
+    if (rawValue === "null")
+        return null;
+    switch (prop.type) {
+        case "text":
+        case "url":
+        case "date":
+        case "email":
+        case "slack_channel":
+        case "msteams_channel":
+        case "select":
+        case "user":
+            return rawValue;
+        case "number": {
+            const n = Number(rawValue);
+            if (isNaN(n)) {
+                throw new CliError(`Invalid number value for property "${prop.identifier}": "${rawValue}"`, EXIT_CODES.ARGUMENT_ERROR);
+            }
+            return n;
+        }
+        case "boolean":
+            if (rawValue === "true")
+                return true;
+            if (rawValue === "false")
+                return false;
+            throw new CliError(`Invalid boolean value for property "${prop.identifier}": expected "true" or "false", got "${rawValue}"`, EXIT_CODES.ARGUMENT_ERROR);
+        case "multi_select":
+        case "list":
+            return rawValue.split(",").map((s) => s.trim());
+        case "json":
+        case "openapi":
+            try {
+                return JSON.parse(rawValue);
+            }
+            catch {
+                throw new CliError(`Invalid JSON value for property "${prop.identifier}": ${rawValue}`, EXIT_CODES.ARGUMENT_ERROR);
+            }
+        case "computed":
+        case "file_matching_rule":
+            throw new CliError(`Property "${prop.identifier}" is read-only (type: ${prop.type}) and cannot be set`, EXIT_CODES.ARGUMENT_ERROR);
+        default:
+            return rawValue;
+    }
+}
+// --- Include helpers ---
+const ENTITY_INCLUDE_SECTIONS = [
+    "core",
+    "owners",
+    "properties",
+    "aliases",
+];
+function processIncludes(response, options) {
+    const includeSections = parseIncludeSections(options.include);
+    if (includeSections.length === 0) {
+        return response;
+    }
+    const sections = uniqueSectionsInOrder(includeSections);
+    const entity = redactEntityByInclude(response.entity, sections);
+    return { ok: true, entity: entity };
+}
+function parseIncludeSections(include) {
+    if (!include) {
+        return [];
+    }
+    const results = include.split(",");
+    for (const result of results) {
+        if (!ENTITY_INCLUDE_SECTIONS.includes(result)) {
+            throw new CliError(`Invalid --include "${result}". Expected one of: ${ENTITY_INCLUDE_SECTIONS.join(", ")}`, EXIT_CODES.ARGUMENT_ERROR);
+        }
+    }
+    return results;
+}
+async function resolvePropertiesForEntityType(runtime, entityTypeIdentifier, rawProperties) {
+    if (rawProperties.length === 0) {
+        return undefined;
+    }
+    let entityTypeResponse;
+    try {
+        entityTypeResponse = await getEntityType(runtime, entityTypeIdentifier);
+    }
+    catch (err) {
+        throw wrapEntityTypeLookupError(entityTypeIdentifier, err);
+    }
+    return parseEntityProperties(entityTypeIdentifier, rawProperties, entityTypeResponse.entity_type.properties);
+}
+async function resolvePropertiesForExistingEntity(runtime, identifier, rawProperties) {
+    if (rawProperties.length === 0) {
+        return undefined;
+    }
+    let entityResponse;
+    try {
+        entityResponse = await getEntity(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 "${identifier}" to resolve property types: ${err instanceof Error ? err.message : String(err)}`, exitCode);
+    }
+    return resolvePropertiesForEntityType(runtime, entityResponse.entity.type, rawProperties);
+}
+function getEntityMutationOptionValues(options) {
+    return {
+        name: options.name,
+        description: options.description,
+        owner_team_ids: parseCommaSeparatedIds(options.ownerTeamIds),
+        owner_user_ids: parseCommaSeparatedIds(options.ownerUserIds),
+    };
+}
+function parseCommaSeparatedIds(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) {
+        body.type = params.type;
+    }
+    if (params.name !== undefined)
+        body.name = params.name;
+    if (params.description !== undefined)
+        body.description = params.description;
+    if (params.owner_team_ids?.length)
+        body.owner_team_ids = params.owner_team_ids;
+    if (params.owner_user_ids?.length)
+        body.owner_user_ids = params.owner_user_ids;
+    if (params.properties !== undefined)
+        body.properties = params.properties;
+    return body;
+}
+function wrapEntityTypeLookupError(entityTypeIdentifier, err) {
+    const exitCode = err instanceof HttpError && err.status !== undefined && err.status < 500
+        ? EXIT_CODES.ARGUMENT_ERROR
+        : EXIT_CODES.RETRY_RECOMMENDED;
+    return new CliError(`Failed to fetch entity type "${entityTypeIdentifier}" to resolve property types: ${err instanceof Error ? err.message : String(err)}`, exitCode);
+}
+function uniqueSectionsInOrder(sections) {
+    const seen = new Set();
+    const ordered = [];
+    for (const s of ENTITY_INCLUDE_SECTIONS) {
+        if (sections.includes(s) && !seen.has(s)) {
+            seen.add(s);
+            ordered.push(s);
+        }
+    }
+    return ordered;
+}
+function redactEntityByInclude(entity, include) {
+    const SECTION_KEYS = {
+        core: [
+            "identifier",
+            "name",
+            "type",
+            "created_at",
+            "updated_at",
+            "description",
+            "domain",
+        ],
+        owners: ["owner_teams", "owner_users"],
+        properties: ["properties"],
+        aliases: ["aliases"],
+    };
+    const sections = uniqueSectionsInOrder(include);
+    const out = {};
+    for (const section of sections) {
+        for (const key of SECTION_KEYS[section]) {
+            if (key in entity) {
+                out[key] = entity[key];
+            }
+        }
+    }
+    return out;
+}