@get-dx/cli 0.7.0 → 0.9.0

package/dist/commands/workflows.js

@@ -1,15 +1,82 @@
+import fs from "fs";
 import { Command } from "commander";
+import { parse as parseYaml } from "yaml";
 import { createExampleText, getContext, wrapAction, } from "../commandHelpers.js";
 import { CliError, EXIT_CODES } from "../errors.js";
 import { request } from "../http.js";
-import { renderJson } from "../renderers.js";
+import { renderJson, renderRichText } from "../renderers.js";
 import { buildRuntime } from "../runtime.js";
-import { renderWorkflowList } from "./workflowsRendering.js";
+import * as ui from "../ui.js";
+import { renderWorkflowCreated, renderWorkflowList, } from "./workflowsRendering.js";
+const WORKFLOW_BLANK_TEMPLATE_YAML = fs.readFileSync(new URL("./workflow-blank-template.yaml", import.meta.url), "utf8");
 const WORKFLOW_SCOPES = ["GLOBAL", "ENTITY"];
 export function workflowsCommand() {
     const workflows = new Command()
         .name("workflows")
         .description("Manage Self-service workflow definitions");
+    workflows
+        .command("create")
+        .description("Create a Self-service workflow from a YAML or JSON file or stdin. The `init` command can be used to generate a starting template.")
+        .option("--from-file <path>", "Read a YAML or JSON file and create a workflow from its contents")
+        .option("--from-stdin", "Read YAML or JSON from stdin and create a workflow from its contents")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Create a workflow from a file",
+            command: "dx workflows create --from-file workflow.yaml",
+        },
+        {
+            label: "Create a workflow from stdin",
+            command: "cat workflow.json | dx workflows create --from-stdin",
+        },
+        {
+            label: "Same request with JSON output",
+            command: "dx --json workflows create --from-file workflow.yaml",
+        },
+    ]))
+        .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 = await buildRuntime(getContext(command));
+        const raw = options.fromFile
+            ? readYamlFile(options.fromFile)
+            : await readYamlStdin();
+        const payload = parsePayloadObject(raw);
+        const response = await createWorkflow(runtime, payload);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderWorkflowCreated(response.workflow);
+        }
+    }));
+    workflows
+        .command("init")
+        .description("Write a blank Self-service workflow YAML template to a file")
+        .argument("<path>", "File path to write the YAML to")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Write a blank workflow template",
+            command: "dx workflows init ./my-workflow.yaml",
+        },
+    ]))
+        .action(wrapAction(async (path, _options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        fs.writeFileSync(path, WORKFLOW_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 workflows create --from-file ${path}`)}`),
+            ]);
+        }
+    }));
     workflows
         .command("list")
         .description("List Self-service workflows for the account")
@@ -49,6 +116,45 @@ export function workflowsCommand() {
     }));
     return workflows;
 }
+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 parseYamlContent(content, `file "${filePath}"`);
+}
+async function readYamlStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => {
+            try {
+                resolve(parseYamlContent(Buffer.concat(chunks).toString("utf8"), "stdin"));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        process.stdin.on("error", (err) => reject(new CliError(`Failed to read from stdin: ${err.message}`, EXIT_CODES.ARGUMENT_ERROR)));
+    });
+}
+function parseYamlContent(content, source) {
+    try {
+        return parseYaml(content);
+    }
+    catch (err) {
+        throw new CliError(`Failed to parse YAML or JSON from ${source}: ${err.message}`, EXIT_CODES.ARGUMENT_ERROR);
+    }
+}
+function parsePayloadObject(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CliError("Content must be a YAML or JSON object", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return raw;
+}
 function parseOptionalTrimmed(value) {
     if (typeof value !== "string") {
         return undefined;
@@ -67,6 +173,10 @@ function parseOptionalScope(value) {
     return raw;
 }
 // --- API ---
+export async function createWorkflow(runtime, payload) {
+    const response = await request(runtime, "/workflows.create", { method: "POST", body: payload });
+    return response.body;
+}
 export async function listWorkflows(runtime, params) {
     const query = {};
     if (params.scope !== undefined)

package/dist/commands/workflowsRendering.js

@@ -38,18 +38,30 @@ export function renderWorkflowList(workflows) {
         ui.p(`Displaying ${ui.bold(workflows.length.toString())} workflows.`),
     ];
     for (const workflow of workflows) {
-        blocks.push(ui.h2(`${workflow.name} (${ui.code(workflow.identifier)})`));
-        blocks.push(ui.h3("Core attributes"));
-        blocks.push(...coreContent(workflow));
-        if (workflow.scope === "ENTITY") {
-            blocks.push(ui.h3("Entity filter"));
-            blocks.push(...entityFilterContent(workflow));
-        }
-        blocks.push(ui.h3("Parameters"));
-        blocks.push(...parametersContent(workflow));
+        blocks.push(...workflowContent(workflow));
     }
     renderRichText(blocks);
 }
+export function renderWorkflowCreated(workflow) {
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Workflow created: ${ui.code(workflow.identifier)}`),
+        ...workflowContent(workflow),
+    ]);
+}
+function workflowContent(workflow) {
+    const blocks = [
+        ui.h2(`${workflow.name} (${ui.code(workflow.identifier)})`),
+        ui.h3("Core attributes"),
+        ...coreContent(workflow),
+    ];
+    if (workflow.scope === "ENTITY") {
+        blocks.push(ui.h3("Entity filter"));
+        blocks.push(...entityFilterContent(workflow));
+    }
+    blocks.push(ui.h3("Parameters"));
+    blocks.push(...parametersContent(workflow));
+    return blocks;
+}
 function coreContent(workflow) {
     const blocks = [];
     const description = workflow.description?.trim()

package/dist/config.js

@@ -41,6 +41,53 @@ export function readConfig() {
     }
     return stored;
 }
+/**
+ * Report on the state of the config file without hiding problems, unlike
+ * `readConfig`, which treats an unparseable file as empty.
+ */
+export function inspectConfigFile() {
+    const configPath = getConfigPath();
+    let stats;
+    let content;
+    try {
+        stats = fs.statSync(configPath);
+        content = fs.readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { status: "missing", path: configPath };
+        }
+        return {
+            status: "invalid",
+            path: configPath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        const parsed = JSON.parse(content);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {
+                status: "invalid",
+                path: configPath,
+                error: "expected a JSON object",
+            };
+        }
+    }
+    catch (error) {
+        return {
+            status: "invalid",
+            path: configPath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return {
+        status: "ok",
+        path: configPath,
+        config: readConfig(),
+        sizeBytes: stats.size,
+        modifiedAt: stats.mtime,
+    };
+}
 export function persistCurrentVersionCache(cache) {
     writeConfig({ ...readConfig(), currentVersionCache: cache });
 }
@@ -89,20 +136,31 @@ function getConfigDir() {
  * Precedence: `DX_API_BASE_URL`, then persisted `apiBaseUrl`, then DX Cloud default.
  */
 export function resolveApiBaseUrl() {
-    if (process.env.DX_API_BASE_URL) {
-        return normalizeUrl(process.env.DX_API_BASE_URL);
-    }
-    return normalizeUrl(readConfig().apiBaseUrl || DEFAULT_API_BASE_URL);
+    return resolveApiBaseUrlWithSource().url;
+}
+/** Like `resolveApiBaseUrl`, but also reports where the value came from. */
+export function resolveApiBaseUrlWithSource() {
+    return resolveBaseUrl(process.env.DX_API_BASE_URL, readConfig().apiBaseUrl, DEFAULT_API_BASE_URL);
 }
 /**
  * Resolved web-app base URL for CLI deep links and browser OAuth.
  * Precedence: `DX_WEB_BASE_URL`, persisted `webBaseUrl`, then DX Cloud default.
  */
 export function resolveWebBaseUrl() {
-    if (process.env.DX_WEB_BASE_URL) {
-        return normalizeUrl(process.env.DX_WEB_BASE_URL);
+    return resolveWebBaseUrlWithSource().url;
+}
+/** Like `resolveWebBaseUrl`, but also reports where the value came from. */
+export function resolveWebBaseUrlWithSource() {
+    return resolveBaseUrl(process.env.DX_WEB_BASE_URL, readConfig().webBaseUrl, DEFAULT_WEB_BASE_URL);
+}
+function resolveBaseUrl(fromEnv, fromConfig, fallback) {
+    if (fromEnv) {
+        return { url: normalizeUrl(fromEnv), source: "env" };
     }
-    return normalizeUrl(readConfig().webBaseUrl || DEFAULT_WEB_BASE_URL);
+    if (fromConfig) {
+        return { url: normalizeUrl(fromConfig), source: "config" };
+    }
+    return { url: normalizeUrl(fallback), source: "default" };
 }
 // --- Deriving base URLs at login time -------------------------------------
 /**
@@ -151,14 +209,17 @@ export function deriveBaseUrlsFromEnv() {
             throw new CliError(`Could not recognize web base URL "${parsed.input}". Expected https://app.getdx.com, https://<account>.getdx.io, or a custom domain.`);
     }
 }
-function parseWebBaseUrl(raw) {
+export function parseWebBaseUrl(raw) {
     const normalized = raw.trim().replace(/\/$/, "");
-    if (!normalized || normalized === "app.getdx.com") {
+    if (!normalized) {
         return { type: "cloud" };
     }
     try {
         const url = new URL(normalized.startsWith("http") ? normalized : `https://${normalized}`);
         const host = url.hostname;
+        if (host === "app.getdx.com") {
+            return { type: "cloud" };
+        }
         const dedicatedMatch = host.match(/^(.+)\.getdx\.io$/);
         if (dedicatedMatch) {
             return { type: "dedicated", accountName: dedicatedMatch[1] };

package/dist/doctor/auth.js

@@ -0,0 +1,133 @@
+import dayjs from "dayjs";
+import { getAuthInfo } from "../commands/auth.js";
+import { HttpError } from "../errors.js";
+import { describeError, timed } from "./format.js";
+import { CHECK_TIMEOUT_MS, DOCTOR_HEADER } from "./probes.js";
+import { check } from "./types.js";
+const EXPIRY_WARNING_DAYS = 7;
+const SECTION = { id: "auth", title: "Auth" };
+export async function checkAuth(options) {
+    const { runtime, apiReachable, now } = options;
+    if (!runtime) {
+        return skipped("no token is configured");
+    }
+    if (!apiReachable) {
+        return skipped("the API is unreachable");
+    }
+    const host = new URL(runtime.apiBaseUrl).host;
+    let info;
+    let ms;
+    try {
+        ({ value: info, ms } = await timed(() => getAuthInfo(runtime, {
+            headers: DOCTOR_HEADER,
+            signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+        })));
+    }
+    catch (error) {
+        return { ...SECTION, checks: [tokenErrorCheck(error, host)] };
+    }
+    const { auth, account } = info;
+    const checks = [
+        check("token_valid", "Token valid", "ok", `${tokenTypeName(auth.token_type)} "${auth.token_name}" (responded in ${ms}ms)`, {
+            data: {
+                token_type: auth.token_type,
+                token_name: auth.token_name,
+                scopes: auth.scopes,
+                created_at: auth.created_at,
+                ms,
+            },
+        }),
+        check("account", "Account", "ok", account.name, {
+            data: { name: account.name },
+        }),
+    ];
+    if (auth.token_type === "personal_access_token") {
+        checks.push(expiryCheck(auth.expires_at, now));
+    }
+    return { ...SECTION, checks };
+}
+function skipped(reason) {
+    return {
+        ...SECTION,
+        checks: [
+            check("token_valid", "Token valid", "skip", `skipped because ${reason}`),
+        ],
+    };
+}
+function tokenErrorCheck(error, host) {
+    if (error instanceof HttpError && error.status === 401) {
+        return check("token_valid", "Token valid", "fail", `token rejected by ${host} (HTTP 401: ${error.message})`, {
+            hint: "The token may be revoked, expired, or issued by a different DX instance. Run `dx auth login` to store a new one.",
+            data: { status: 401 },
+        });
+    }
+    if (error instanceof HttpError && error.status !== undefined) {
+        const { message, hint } = describeHttpFailure(error.status, error.message, host);
+        return check("token_valid", "Token valid", "fail", message, {
+            hint,
+            data: { status: error.status },
+        });
+    }
+    return check("token_valid", "Token valid", "fail", describeError(error, "auth.info request"), {
+        hint: `The API was reachable a moment ago, but this request to ${host} failed. Try again.`,
+        data: { status: null },
+    });
+}
+function describeHttpFailure(status, errorMessage, host) {
+    if (status === 403) {
+        return {
+            message: `access denied by ${host} (HTTP 403: ${errorMessage})`,
+            hint: "The token was recognized but this request was refused. An IP allowlist, proxy, or firewall may be blocking it. Check with your DX admin or network team.",
+        };
+    }
+    if (status === 429) {
+        return {
+            message: `rate limited by ${host} (HTTP 429)`,
+            hint: "Too many requests. Wait a minute and run `dx doctor` again.",
+        };
+    }
+    if (status >= 500) {
+        return {
+            message: `HTTP ${status}: ${errorMessage}`,
+            hint: "The DX API is having problems. Try again in a few minutes, and contact DX support if this persists.",
+        };
+    }
+    return {
+        message: `HTTP ${status}: ${errorMessage}`,
+        hint: "The DX API could not validate the token. Try again, and contact DX support if this persists.",
+    };
+}
+function expiryCheck(expiresAt, now) {
+    if (!expiresAt) {
+        return check("expires", "Expires", "ok", "never", {
+            data: { expires_at: null },
+        });
+    }
+    const expires = dayjs(expiresAt);
+    const days = expires.diff(dayjs(now), "day");
+    const date = expires.format("YYYY-MM-DD");
+    const data = { expires_at: expiresAt, days_remaining: days };
+    if (expires.isBefore(now)) {
+        return check("expires", "Expires", "fail", `expired on ${date}`, {
+            hint: "Create a new personal access token and run `dx auth login`.",
+            data,
+        });
+    }
+    if (days < EXPIRY_WARNING_DAYS) {
+        return check("expires", "Expires", "warn", `${date} (${days}d)`, {
+            hint: "This token expires soon. Create a new one and run `dx auth login`.",
+            data,
+        });
+    }
+    return check("expires", "Expires", "ok", `${date} (${days}d)`, { data });
+}
+function tokenTypeName(tokenType) {
+    switch (tokenType) {
+        case "account_web_api_token":
+            return "organization token";
+        case "personal_access_token":
+            return "personal access token";
+        default:
+            return String(tokenType);
+    }
+}

package/dist/doctor/cli.js

@@ -0,0 +1,154 @@
+import fs from "node:fs";
+import path from "node:path";
+import dayjs from "dayjs";
+import { compareVersions, fetchLatestVersion, fetchLatestVersionFromNpm, } from "../versionCheck.js";
+import { describeError, tildify } from "./format.js";
+import { CHECK_TIMEOUT_MS, DOCTOR_HEADER } from "./probes.js";
+import { check } from "./types.js";
+import cliPackage from "../../package.json" with { type: "json" };
+export const defaultLatestVersionLookup = {
+    fromApi: (runtime) => fetchLatestVersion(runtime, {
+        headers: DOCTOR_HEADER,
+        signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+    }),
+    fromNpm: () => fetchLatestVersionFromNpm({
+        signal: AbortSignal.timeout(CHECK_TIMEOUT_MS),
+    }),
+};
+export async function checkCli(options) {
+    const { runtime, apiReachable, install, latestVersion, now } = options;
+    const checks = [
+        await versionCheck(apiReachable ? runtime : null, install.method, latestVersion),
+        nodeCheck(),
+        check("platform", "Platform", "ok", `${process.platform}/${process.arch}`, {
+            data: { platform: process.platform, arch: process.arch },
+        }),
+        check("install", "Install", "ok", `${installMethodName(install.method)} (${tildify(install.path)})`, { data: { method: install.method, path: tildify(install.path) } }),
+        check("time", "Time", "ok", dayjs(now).format(), {
+            data: { time: dayjs(now).format() },
+        }),
+    ];
+    return { id: "cli", title: "CLI", checks };
+}
+async function versionCheck(runtime, method, lookup) {
+    const current = cliPackage.version;
+    const failures = [];
+    let latest = null;
+    let latestSource = null;
+    if (runtime) {
+        try {
+            latest = await lookup.fromApi(runtime);
+            latestSource = "api";
+        }
+        catch (error) {
+            failures.push(`DX API: ${describeError(error, "request")}`);
+        }
+    }
+    else {
+        failures.push("DX API: skipped (no token or API unreachable)");
+    }
+    if (!latest) {
+        try {
+            latest = await lookup.fromNpm();
+            latestSource = "npm";
+        }
+        catch (error) {
+            failures.push(`npm: ${describeError(error, "request")}`);
+        }
+    }
+    if (!latest) {
+        return check("version", "Version", "fail", `${current} (could not determine the latest version)`, {
+            hint: `Tried the DX API and the npm registry:\n${failures.join("\n")}`,
+            data: { current, latest: null, latest_source: null },
+        });
+    }
+    const data = { current, latest, latest_source: latestSource };
+    const comparison = compareVersions(current, latest);
+    if (comparison < 0) {
+        return check("version", "Version", "warn", `${current} (latest is ${latest})`, {
+            hint: `Upgrade with: ${upgradeCommand(method)}`,
+            data,
+        });
+    }
+    const message = comparison === 0
+        ? `${current} (up to date)`
+        : `${current} (newer than the latest release, ${latest})`;
+    return check("version", "Version", "ok", message, { data });
+}
+function nodeCheck() {
+    const version = process.version;
+    const supportedMajors = [
+        ...cliPackage.engines.node.matchAll(/\^(\d+)\./g),
+    ].map((match) => Number(match[1]));
+    const major = Number(process.versions.node.split(".")[0]);
+    const data = { version, supported: cliPackage.engines.node };
+    if (supportedMajors.length > 0 && !supportedMajors.includes(major)) {
+        return check("node", "Node.js", "warn", `${version} (unsupported)`, {
+            hint: `dx-cli supports Node.js ${cliPackage.engines.node}. Other versions may not work correctly.`,
+            data,
+        });
+    }
+    return check("node", "Node.js", "ok", version, { data });
+}
+export function upgradeCommand(method) {
+    switch (method) {
+        case "npx":
+            return "npx @get-dx/cli@latest";
+        case "dev":
+            return "pull the latest changes and run `make`";
+        case "pnpm":
+            return "pnpm add -g @get-dx/cli@latest";
+        case "npm":
+        case "unknown":
+            return "npm install -g @get-dx/cli@latest";
+    }
+}
+function installMethodName(method) {
+    switch (method) {
+        case "npx":
+            return "npx";
+        case "dev":
+            return "pnpm link (dev)";
+        case "pnpm":
+            return "pnpm global";
+        case "npm":
+            return "npm global";
+        case "unknown":
+            return "unknown";
+    }
+}
+/**
+ * Work out how the CLI was installed from where its entry script lives.
+ */
+export function detectInstall(entryScript = process.argv[1], execPath = process.execPath) {
+    let resolved = entryScript;
+    try {
+        resolved = fs.realpathSync(entryScript);
+    }
+    catch {
+        // Fall back to the unresolved path.
+    }
+    // `dist/index.js` lives one level below the package root.
+    const packageRoot = path.dirname(path.dirname(resolved));
+    const normalized = resolved.split(path.sep).join("/");
+    if (normalized.includes("/_npx/")) {
+        return { method: "npx", path: packageRoot };
+    }
+    if (!normalized.includes("/node_modules/")) {
+        if (fs.existsSync(path.join(packageRoot, ".git"))) {
+            return { method: "dev", path: packageRoot };
+        }
+        return { method: "unknown", path: resolved };
+    }
+    if (normalized.includes("/pnpm/global/") || normalized.includes("/.pnpm/")) {
+        return { method: "pnpm", path: packageRoot };
+    }
+    const npmGlobalRoot = process.platform === "win32"
+        ? path.join(path.dirname(execPath), "node_modules")
+        : path.join(path.dirname(path.dirname(execPath)), "lib", "node_modules");
+    if (resolved.startsWith(npmGlobalRoot + path.sep) ||
+        normalized.includes("/lib/node_modules/@get-dx/cli/")) {
+        return { method: "npm", path: packageRoot };
+    }
+    return { method: "unknown", path: packageRoot };
+}