@get-dx/cli 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# dx-cli
+
+Standalone DX CLI for existing token-authenticated DX web API endpoints.
+
+## Install
+
+```bash
+npm install --global @get-dx/cli
+```
+
+## Commands
+
+- `dx auth login --token <account-web-api-token>`
+- `dx auth logout`
+- `dx auth status`
+- `dx catalog entities info <identifier>`
+
+## Agent Provenance
+
+The CLI can automatically attach agent metadata from:
+
+- `DX_AGENT_NAME`
+- `DX_AGENT_SESSION_ID`
+
+Explicit `--agent` and `--agent-session-id` flags take precedence over the environment.
+
+## Logging
+
+Set `DX_LOG_LEVEL` to one of `debug`, `info`, `warn`, or `error` to enable CLI logs.
+
+Logs are always written to `stderr`. They are human-readable by default, and switch to JSON when `--json` is present or `stderr` is not a TTY.
+
+Deferred in this repo version:
+
+- `dx init`
+- `dx scorecards list|get|create|update`
+- `dx catalog entities list|create|update`
+- `dx workflows list`
+- `dx workflows trigger`
+- `dx studio query`
+
+## Developing the CLI
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).

package/dist/cli.js

@@ -0,0 +1,50 @@
+import { Command, Option } from "commander";
+import { authCommand } from "./commands/auth.js";
+import { catalogCommand } from "./commands/catalog.js";
+import { scorecardsCommand } from "./commands/scorecards.js";
+import { studioCommand } from "./commands/studio.js";
+import { handleError } from "./commandHelpers.js";
+import cliPackage from "../package.json" with { type: "json" };
+export async function run(argv = process.argv) {
+    try {
+        const program = createProgram();
+        if (argv.length <= 2) {
+            program.outputHelp();
+            return;
+        }
+        await program.parseAsync(argv);
+    }
+    catch (error) {
+        handleError(error, undefined, argv);
+    }
+}
+function createProgram() {
+    const program = new Command();
+    program
+        .name("dx")
+        .description("DX CLI")
+        .version(cliPackage.version)
+        .addOption(new Option("--json", "Print machine-readable JSON"))
+        .addOption(new Option("--agent <name>", "Agent name to send as an HTTP header"))
+        .addOption(new Option("--agent-session-id <id>", "Agent session ID to send as an HTTP header"));
+    program.addCommand(authCommand());
+    program.addCommand(catalogCommand());
+    program.addCommand(scorecardsCommand());
+    program.addCommand(studioCommand());
+    applyExitOverride(program);
+    return program;
+}
+/**
+ * Make Commander throw CommanderError instead of calling process.exit(), and
+ * suppress its own stderr writes so we can control all error output ourselves.
+ *
+ * exitOverride() and configureOutput() are not inherited by subcommands, so
+ * apply them to the full command tree after all subcommands are registered.
+ */
+function applyExitOverride(cmd) {
+    cmd.exitOverride();
+    cmd.configureOutput({ writeErr: () => { } });
+    for (const sub of cmd.commands) {
+        applyExitOverride(sub);
+    }
+}

package/dist/commandHelpers.js

@@ -0,0 +1,110 @@
+import { CommanderError } from "commander";
+import { CliError, EXIT_CODES, HttpError } from "./errors.js";
+export function getContext(command) {
+    const root = command.optsWithGlobals();
+    return {
+        json: Boolean(root.json),
+        agent: root.agent || process.env.DX_AGENT_NAME,
+        agentSessionId: root.agentSessionId || process.env.DX_AGENT_SESSION_ID,
+    };
+}
+export function wrapAction(action) {
+    return async (...args) => {
+        try {
+            await action(...args);
+        }
+        catch (error) {
+            const command = args[args.length - 1];
+            handleError(error, command, undefined);
+        }
+    };
+}
+export function handleError(error, command, argv) {
+    if (error instanceof CommanderError && error.exitCode === 0) {
+        // help or version was displayed.
+        // Commander already printed the output, so just exit cleanly.
+        process.exit(0);
+    }
+    const context = inferContext(command, argv);
+    if (context.json) {
+        if (error instanceof HttpError) {
+            printJson({
+                ok: false,
+                error: error.message,
+                http_status: error.status,
+                body: error.body,
+            });
+        }
+        else if (error instanceof CliError) {
+            printJson({
+                ok: false,
+                error: error.message,
+            });
+        }
+        else if (error instanceof CommanderError) {
+            // Strip the "error: " prefix Commander adds — it's terminal formatting,
+            // not appropriate in a JSON payload.
+            const message = error.message.replace(/^error:\s+/i, "");
+            printJson({ ok: false, error: message });
+        }
+        else {
+            printJson({
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    else {
+        if (error instanceof HttpError) {
+            process.stderr.write(`The API returned an error with status code ${error.status}:\n\n${JSON.stringify(error.body, null, 2)}\n`);
+        }
+        else {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
+    const exitCode = (() => {
+        if (error instanceof CliError) {
+            return error.exitCode;
+        }
+        else if (error instanceof CommanderError) {
+            return EXIT_CODES.ARGUMENT_ERROR;
+        }
+        else {
+            // Should be unreachable
+            return 1;
+        }
+    })();
+    process.exit(exitCode);
+}
+function printJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+export function parsePositiveIntOption(value, flag) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new CliError(`${flag} must be a positive integer`, EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return n;
+}
+export function createExampleText(examples) {
+    const lines = [];
+    lines.push(""); // separate from the rest of the help text
+    lines.push("Examples:");
+    for (const example of examples) {
+        lines.push(`  ${example.label}:`);
+        lines.push(`    ${example.command}`);
+    }
+    return lines.join("\n");
+}
+function inferContext(command, argv) {
+    if (command) {
+        return getContext(command);
+    }
+    else {
+        const rawArgv = argv && argv.length > 0 ? argv : process.argv;
+        const hasJsonFlag = Boolean(rawArgv.find((arg) => arg === "--json"));
+        return {
+            json: hasJsonFlag,
+        };
+    }
+}

package/dist/commands/auth.js

@@ -0,0 +1,70 @@
+import { Command } from "commander";
+import { deleteToken, setToken } from "../secrets.js";
+import { renderJson } from "../renderers.js";
+import { renderAuthInfo, renderLoggedOut } from "./authRendering.js";
+import { wrapAction } from "../commandHelpers.js";
+import { getContext } from "../commandHelpers.js";
+import { persistBaseUrl, resolveBaseUrl } from "../config.js";
+import { request } from "../http.js";
+import { buildLogger, buildRuntime } from "../runtime.js";
+import cliPackage from "../../package.json" with { type: "json" };
+import { maskToken } from "../ui.js";
+export function authCommand() {
+    const auth = new Command()
+        .name("auth")
+        .description("Manage DX authentication");
+    auth
+        .command("login")
+        .requiredOption("--token <token>", "Account web API token")
+        .action(wrapAction(async (commandOptions, command) => {
+        const context = getContext(command);
+        const baseUrl = resolveBaseUrl();
+        const runtime = {
+            baseUrl,
+            token: commandOptions.token,
+            context,
+            version: cliPackage.version,
+            logger: buildLogger(context),
+        };
+        const response = await getAuthInfo(runtime);
+        persistBaseUrl(baseUrl);
+        setToken(baseUrl, commandOptions.token);
+        if (context.json) {
+            renderJson({ ...response, base_url: baseUrl });
+            return;
+        }
+        renderAuthInfo(response, commandOptions.token, baseUrl);
+    }));
+    auth.command("logout").action(wrapAction(async (_options, command) => {
+        const context = getContext(command);
+        const baseUrl = resolveBaseUrl();
+        deleteToken(baseUrl);
+        if (context.json) {
+            renderJson({ ok: true, base_url: baseUrl, logged_out: true });
+        }
+        else {
+            renderLoggedOut(baseUrl);
+        }
+    }));
+    auth.command("status").action(wrapAction(async (_options, command) => {
+        const runtime = buildRuntime(getContext(command));
+        const response = await getAuthInfo(runtime);
+        if (runtime.context.json) {
+            renderJson({
+                ...response,
+                token: maskToken(runtime.token),
+                base_url: runtime.baseUrl,
+            });
+        }
+        else {
+            renderAuthInfo(response, runtime.token, runtime.baseUrl);
+        }
+    }));
+    return auth;
+}
+async function getAuthInfo(runtime) {
+    const response = await request(runtime, "/auth.info", {
+        method: "GET",
+    });
+    return response.body;
+}

package/dist/commands/authRendering.js

@@ -0,0 +1,40 @@
+import { renderRichText } from "../renderers.js";
+import * as ui from "../ui.js";
+export function renderAuthInfo(authInfo, token, baseUrl) {
+    const maskedToken = ui.maskToken(token) ?? "not configured";
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Logged in to ${ui.link(baseUrl)} account ${ui.bold(authInfo.account.name)}`),
+        ui.dl([
+            ui.dli("Token", ui.code(maskedToken)),
+            ui.dli("Token type", tokenTypeName(authInfo.auth.token_type)),
+            ui.dli("Token name", authInfo.auth.token_name),
+            ui.dli("Token created at", ui.timestampSummary(authInfo.auth.created_at)),
+        ], { termWidth: 18 }),
+        ui.p(ui.bold("Token scopes:"), false),
+        ...scopesContent(authInfo.auth.scopes),
+    ]);
+}
+export function renderLoggedOut(baseUrl) {
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Logged out of ${ui.link(baseUrl)} successfully`),
+    ]);
+}
+function scopesContent(scopes) {
+    if (scopes.length === 0) {
+        return [ui.p("(none)", false)];
+    }
+    else {
+        return [
+            ui.p("", false),
+            ui.ul(scopes.map((scope) => ui.li(ui.code(scope)))),
+        ];
+    }
+}
+function tokenTypeName(tokenType) {
+    switch (tokenType) {
+        case "account_web_api_token":
+            return "Account-level web API token";
+        default:
+            throw new Error(`Unknown token type: ${tokenType}`);
+    }
+}