@get-dx/cli 0.8.0 → 0.10.0

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 };
+}

package/dist/doctor/config.js

@@ -0,0 +1,119 @@
+import dayjs from "dayjs";
+import { inspectConfigFile, parseWebBaseUrl, resolveApiBaseUrlWithSource, resolveWebBaseUrlWithSource, } from "../config.js";
+import { getTokenWithSource } from "../secrets.js";
+import { maskToken } from "../ui.js";
+import { formatBytes, tildify } from "./format.js";
+import { check } from "./types.js";
+export async function checkConfig() {
+    const checks = [];
+    checks.push(configFileCheck());
+    const api = resolveApiBaseUrlWithSource();
+    const web = resolveWebBaseUrlWithSource();
+    checks.push(check("api_base_url", "API base URL", "ok", api.url, {
+        source: api.source,
+        data: { url: api.url },
+    }), check("web_base_url", "Web base URL", "ok", web.url, {
+        source: web.source,
+        data: { url: web.url },
+    }));
+    if (process.env.DX_API_BASE_URL && !process.env.DX_WEB_BASE_URL) {
+        checks.push(check("base_url_env", "Base URL env vars", "fail", "DX_API_BASE_URL is set but DX_WEB_BASE_URL is not", {
+            hint: "Set DX_WEB_BASE_URL to your DX web app URL (e.g. https://acme.getdx.io) or unset DX_API_BASE_URL.",
+        }));
+    }
+    checks.push(deploymentCheck(web.url));
+    const { check: tokenCheck, token } = await tokenCheckFor(api.url);
+    checks.push(tokenCheck);
+    return {
+        section: { id: "config", title: "Config", checks },
+        facts: { apiBaseUrl: api.url, webBaseUrl: web.url, token },
+    };
+}
+function configFileCheck() {
+    const inspection = inspectConfigFile();
+    const displayPath = tildify(inspection.path);
+    switch (inspection.status) {
+        case "missing":
+            if (process.env.DX_API_TOKEN) {
+                return check("config_file", "Config file", "ok", `${displayPath} not present (using env/defaults)`, { data: { path: displayPath, exists: false } });
+            }
+            return check("config_file", "Config file", "warn", `${displayPath} not present`, {
+                hint: "This usually means `dx auth login` has never completed. Run `dx auth login`.",
+                data: { path: displayPath, exists: false },
+            });
+        case "invalid":
+            return check("config_file", "Config file", "fail", `${displayPath} could not be read (${inspection.error})`, {
+                hint: "The file is ignored while it is invalid. Fix or delete it, then run `dx auth login`.",
+                data: { path: displayPath, exists: true, error: inspection.error },
+            });
+        case "ok": {
+            const modifiedAt = dayjs(inspection.modifiedAt).format();
+            return check("config_file", "Config file", "ok", `${displayPath} (${formatBytes(inspection.sizeBytes)}, modified ${modifiedAt})`, {
+                data: {
+                    path: displayPath,
+                    exists: true,
+                    size_bytes: inspection.sizeBytes,
+                    modified_at: modifiedAt,
+                },
+            });
+        }
+    }
+}
+function deploymentCheck(webBaseUrl) {
+    const parsed = parseWebBaseUrl(webBaseUrl);
+    switch (parsed.type) {
+        case "cloud":
+            return check("deployment", "Deployment", "ok", "cloud", {
+                data: { type: "cloud" },
+            });
+        case "dedicated":
+            return check("deployment", "Deployment", "ok", `dedicated (${parsed.accountName})`, { data: { type: "dedicated", account: parsed.accountName } });
+        case "managed":
+            return check("deployment", "Deployment", "ok", "managed (custom domain)", {
+                data: { type: "managed" },
+            });
+        case "invalid":
+            return check("deployment", "Deployment", "fail", `could not recognize web base URL "${parsed.input}"`, {
+                hint: "Expected https://app.getdx.com, https://<account>.getdx.io, or a custom domain.",
+                data: { type: "invalid" },
+            });
+    }
+}
+async function tokenCheckFor(apiBaseUrl) {
+    const lookup = await getTokenWithSource(apiBaseUrl);
+    switch (lookup.source) {
+        case "env":
+        case "keychain": {
+            const masked = maskToken(lookup.token);
+            return {
+                token: lookup.token,
+                check: check("token", "Token", "ok", masked ?? "", {
+                    source: lookup.source,
+                    data: { source: lookup.source, masked_token: masked },
+                }),
+            };
+        }
+        case "none":
+            return {
+                token: null,
+                check: check("token", "Token", "fail", `no token found (checked DX_API_TOKEN and ${lookup.storeName})`, {
+                    hint: "Run `dx auth login`, or set DX_API_TOKEN.",
+                    data: { source: null },
+                }),
+            };
+        case "error":
+            return {
+                token: null,
+                check: check("token", "Token", "fail", `could not read ${lookup.storeName ?? "the OS secret store"}: ${lookup.error}`, {
+                    hint: tokenStoreHint(),
+                    data: { source: null, error: lookup.error },
+                }),
+            };
+    }
+}
+function tokenStoreHint() {
+    if (process.platform === "linux") {
+        return "Install `libsecret-tools` and make sure a Secret Service provider (e.g. GNOME Keyring) is running, or set DX_API_TOKEN instead.";
+    }
+    return "Set DX_API_TOKEN in the environment instead of storing the token in the OS secret store.";
+}

package/dist/doctor/environment.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import { maskToken } from "../ui.js";
+import { redactUrlCredentials, tildify } from "./format.js";
+import { check } from "./types.js";
+const PROXY_VARS = ["HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "NO_PROXY"];
+/** Variable names that likely hold credentials, so their values are masked. */
+const SENSITIVE_NAME_PATTERN = /TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|API_?KEY|PRIVATE_?KEY|AUTH|COOKIE|SESSION_?KEY/i;
+export function isSensitiveEnvName(name) {
+    return SENSITIVE_NAME_PATTERN.test(name);
+}
+export function checkEnvironment(env = process.env) {
+    const checks = [];
+    const names = Object.keys(env).sort();
+    for (const name of names.filter((name) => name.startsWith("DX_"))) {
+        const raw = env[name] ?? "";
+        const sensitive = isSensitiveEnvName(name);
+        const value = sensitive ? (maskToken(raw) ?? "") : raw;
+        checks.push(check(name.toLowerCase(), name, "ok", value, {
+            data: { masked: sensitive },
+        }));
+    }
+    for (const name of names.filter((name) => PROXY_VARS.includes(name.toUpperCase()))) {
+        const value = redactUrlCredentials(env[name] ?? "");
+        checks.push(check(name.toLowerCase(), name, "warn", value, {
+            hint: "dx-cli does not use proxy environment variables. Requests go directly to the DX API.",
+            data: { value },
+        }));
+    }
+    const extraCaCerts = env.NODE_EXTRA_CA_CERTS;
+    if (extraCaCerts) {
+        const displayPath = tildify(extraCaCerts);
+        const exists = fs.existsSync(extraCaCerts);
+        checks.push(exists
+            ? check("node_extra_ca_certs", "NODE_EXTRA_CA_CERTS", "ok", `${displayPath} (file exists)`, { data: { path: displayPath, exists } })
+            : check("node_extra_ca_certs", "NODE_EXTRA_CA_CERTS", "warn", `${displayPath} (file not found)`, {
+                hint: "Node ignores this setting when the file does not exist. Point it at your CA bundle in PEM format.",
+                data: { path: displayPath, exists },
+            }));
+    }
+    const useSystemCa = env.NODE_USE_SYSTEM_CA;
+    if (useSystemCa) {
+        checks.push(check("node_use_system_ca", "NODE_USE_SYSTEM_CA", "ok", useSystemCa));
+    }
+    const rejectUnauthorized = env.NODE_TLS_REJECT_UNAUTHORIZED;
+    if (rejectUnauthorized !== undefined) {
+        checks.push(rejectUnauthorized === "0"
+            ? check("node_tls_reject_unauthorized", "NODE_TLS_REJECT_UNAUTHORIZED", "warn", "0 (certificate verification disabled)", {
+                hint: "This disables TLS certificate checks and is insecure. Use NODE_EXTRA_CA_CERTS to trust your corporate CA instead.",
+            })
+            : check("node_tls_reject_unauthorized", "NODE_TLS_REJECT_UNAUTHORIZED", "ok", rejectUnauthorized));
+    }
+    const nodeOptions = env.NODE_OPTIONS;
+    if (nodeOptions) {
+        checks.push(check("node_options", "NODE_OPTIONS", "ok", nodeOptions));
+    }
+    if (checks.length === 0) {
+        checks.push(check("none", "Variables", "ok", "(none set)"));
+    }
+    return { id: "environment", title: "Environment", checks };
+}

package/dist/doctor/format.js

@@ -0,0 +1,68 @@
+import os from "node:os";
+import { describeFetchFailure } from "../http.js";
+import { CHECK_TIMEOUT_MS, ProbeTimeoutError } from "./probes.js";
+/** Replace the home directory with `~` so paths don't reveal usernames. */
+export function tildify(filePath) {
+    const home = os.homedir();
+    if (home &&
+        (filePath === home ||
+            filePath.startsWith(home + "/") ||
+            filePath.startsWith(home + "\\"))) {
+        return "~" + filePath.slice(home.length);
+    }
+    return filePath;
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    const units = ["KB", "MB", "GB"];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+}
+/** Remove credentials from a URL-like string, e.g. a proxy URL. */
+export function redactUrlCredentials(value) {
+    return value.replace(/\/\/[^/@\s]+@/g, "//***@");
+}
+export function isTimeout(error) {
+    if (error instanceof ProbeTimeoutError) {
+        return true;
+    }
+    let current = error;
+    while (current instanceof Error) {
+        if (current.name === "TimeoutError") {
+            return true;
+        }
+        current = current.cause;
+    }
+    return false;
+}
+/** The error code (e.g. `ECONNRESET`) of an error or anything in its cause chain. */
+export function errorCode(error) {
+    let current = error;
+    while (current instanceof Error) {
+        const { code } = current;
+        if (typeof code === "string") {
+            return code;
+        }
+        current = current.cause;
+    }
+    return null;
+}
+export function describeError(error, action) {
+    if (isTimeout(error)) {
+        const timeoutMs = error instanceof ProbeTimeoutError ? error.timeoutMs : CHECK_TIMEOUT_MS;
+        return `${action} timed out after ${timeoutMs / 1000}s`;
+    }
+    return describeFetchFailure(error);
+}
+export async function timed(fn) {
+    const start = performance.now();
+    const value = await fn();
+    return { value, ms: Math.round(performance.now() - start) };
+}

package/dist/doctor/index.js

@@ -0,0 +1,81 @@
+import { buildLogger } from "../runtime.js";
+import { checkAuth } from "./auth.js";
+import { checkCli, defaultLatestVersionLookup, detectInstall, } from "./cli.js";
+import { checkConfig } from "./config.js";
+import { checkEnvironment } from "./environment.js";
+import { checkNetwork } from "./network.js";
+import { defaultProbes } from "./probes.js";
+import { checkSkill } from "./skill.js";
+import cliPackage from "../../package.json" with { type: "json" };
+const defaultDependencies = {
+    probes: defaultProbes,
+    latestVersion: defaultLatestVersionLookup,
+    install: () => detectInstall(),
+    now: () => new Date(),
+};
+/**
+ * Run every doctor check. Never throws: problems are reported as checks.
+ *
+ * Checks run in dependency order (config before network before auth), but the
+ * report lists sections in reading order.
+ */
+export async function runDoctor(context, options = {}) {
+    const deps = { ...defaultDependencies, ...options.dependencies };
+    const onPhase = options.onPhase ?? (() => { });
+    const now = deps.now();
+    onPhase("config");
+    const environment = checkEnvironment();
+    const config = await checkConfig();
+    const { apiBaseUrl, webBaseUrl, token } = config.facts;
+    const runtime = token
+        ? {
+            apiBaseUrl,
+            webBaseUrl,
+            token,
+            context,
+            version: cliPackage.version,
+            logger: buildLogger(context),
+        }
+        : null;
+    onPhase("network");
+    const network = await checkNetwork({
+        apiBaseUrl,
+        webBaseUrl,
+        version: cliPackage.version,
+        probes: deps.probes,
+    });
+    const { apiReachable } = network.facts;
+    onPhase("auth");
+    const auth = await checkAuth({ runtime, apiReachable, now });
+    onPhase("version");
+    const cli = await checkCli({
+        runtime,
+        apiReachable,
+        install: deps.install(),
+        latestVersion: deps.latestVersion,
+        now,
+    });
+    const skill = await checkSkill();
+    return buildReport([
+        cli,
+        environment,
+        config.section,
+        network.section,
+        auth,
+        skill,
+    ]);
+}
+function buildReport(sections) {
+    const summary = {
+        ok: 0,
+        warn: 0,
+        fail: 0,
+        skip: 0,
+    };
+    for (const section of sections) {
+        for (const check of section.checks) {
+            summary[check.status] += 1;
+        }
+    }
+    return { ok: summary.fail === 0, summary, sections };
+}