@get-dx/cli 0.3.8 → 0.5.0

package/dist/cli.js

@@ -11,6 +11,7 @@ import { workflowsCommand } from "./commands/workflows.js";
 import { handleError } from "./commandHelpers.js";
 import cliPackage from "../package.json" with { type: "json" };
 import { handleTemporaryBaseUrlMigration } from "./config.js";
+import { checkForNewVersion, performUpdate, promptVersionUpdate, } from "./versionCheck.js";
 export async function run(argv = process.argv) {
     try {
         handleTemporaryBaseUrlMigration(argv);
@@ -19,7 +20,20 @@ export async function run(argv = process.argv) {
             program.outputHelp();
             return;
         }
+        let versionCheckResult = { shouldUpdate: false };
+        try {
+            const versionStatus = await checkForNewVersion(argv);
+            if (versionStatus.status === "available") {
+                versionCheckResult = await promptVersionUpdate(versionStatus.latestVersion);
+            }
+        }
+        catch {
+            // Never let a failure with version check or upgrade prompt block a command
+        }
         await program.parseAsync(argv);
+        if (versionCheckResult.shouldUpdate && versionCheckResult.latestVersion) {
+            await performUpdate(versionCheckResult.latestVersion);
+        }
     }
     catch (error) {
         handleError(error, undefined, argv);

package/dist/commands/init.js

@@ -1,6 +1,3 @@
-import { access } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { password, confirm, select } from "@inquirer/prompts";
 import { Command } from "commander";
 import { execa } from "execa";
@@ -13,6 +10,7 @@ import { renderRichText } from "../renderers.js";
 import * as ui from "../ui.js";
 import { CliError } from "../errors.js";
 import { deriveBaseUrlsFromEnv, persistBaseUrls } from "../config.js";
+import { isSkillInstalled } from "../skill.js";
 import { setToken } from "../secrets.js";
 import { renderWelcomeAnimation } from "../welcomeAnimation.js";
 export function initCommand() {
@@ -113,10 +111,7 @@ async function optionallySetupSkill(runtime) {
         ui.h1(`Checking for the DX skill...`),
         ui.blankLine(),
     ]);
-    const skillPath = join(homedir(), ".agents", "skills", "dx-cli");
-    const skillInstalled = await access(skillPath)
-        .then(() => true)
-        .catch(() => false);
+    const skillInstalled = await isSkillInstalled();
     if (skillInstalled) {
         renderRichText([ui.p(`The DX skill is already installed.`)]);
         runtime.logger.debug("To update: npx skills update dx-cli --global");

package/dist/commands/studio/report-blank-template.yaml

@@ -0,0 +1,49 @@
+# Data Studio report configuration
+#
+# Edit this file, then run:
+#
+# ```
+# dx studio reports create --from-file <path>
+# ```
+
+name: ""
+owner_email: ""
+description: ""
+markdown_notes: ""
+
+# view_access_type: owner_and_direct_url_only, specific_users, or everyone
+view_access_type: owner_and_direct_url_only
+# Required only when view_access_type is specific_users
+viewer_emails: []
+
+# edit_access_type: read_only, owner_only, specific_users, or everyone
+edit_access_type: read_only
+# Required only when edit_access_type is specific_users
+editor_emails: []
+
+# Supported chart_type values: line, pie, stacked_bar, scatter, table
+tiles:
+  - title: ""
+    sql: |-
+      SELECT 1 AS value
+    chart_type: table
+    chart_config: {}
+
+  # Line, stacked_bar, and scatter tiles require xAxis and yAxes.
+  # - title: ""
+  #   sql: |-
+  #     SELECT CURRENT_DATE AS week_start, 1 AS value
+  #   chart_type: line
+  #   chart_config:
+  #     xAxis: week_start
+  #     yAxes:
+  #       - value
+
+  # Pie tiles require labelColumn and valueColumn.
+  # - title: ""
+  #   sql: |-
+  #     SELECT 'Example' AS label, 1 AS value
+  #   chart_type: pie
+  #   chart_config:
+  #     labelColumn: label
+  #     valueColumn: value

package/dist/commands/studio/reports.js

@@ -0,0 +1,399 @@
+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";
+export function reportsCommand() {
+    const reports = new Command()
+        .name("reports")
+        .description("Manage Data Studio reports");
+    reports
+        .command("create")
+        .description("Create a Data Studio report from a YAML file or stdin")
+        .option("--from-file <path>", "Read a YAML file and create a report from its contents")
+        .option("--from-stdin", "Read YAML from stdin and create a report from its contents")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Create a studio report from a YAML file",
+            command: "dx studio reports create --from-file ./my-report.yaml",
+        },
+        {
+            label: "Create a studio report from stdin",
+            command: "cat ./my-report.yaml | dx studio reports 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 = await buildRuntime(getContext(command));
+        const raw = options.fromFile
+            ? readYamlFile(options.fromFile)
+            : await readYamlStdin();
+        const payload = buildCreateReportPayload(raw);
+        const response = await createStudioReport(runtime, payload);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderStudioReportCreated(response.report);
+        }
+    }));
+    reports
+        .command("info")
+        .description("Retrieve details for an individual Data Studio report")
+        .argument("<id>", "Studio report ID")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Fetch info for a studio report",
+            command: "dx studio reports info s4525phi3dud",
+        },
+        {
+            label: "Fetch studio report info as JSON",
+            command: "dx --json studio reports info s4525phi3dud",
+        },
+    ]))
+        .action(wrapAction(async (id, _options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await getStudioReportInfo(runtime, id);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderStudioReportInfo(response.report);
+        }
+    }));
+    reports
+        .command("init")
+        .description("Write a Data Studio report YAML file, either from an existing report or as a blank template")
+        .argument("<path>", "File path to write the YAML to")
+        .option("--id <id>", "Fetch an existing report and use it as the template")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Write a blank studio report template",
+            command: "dx studio reports init ./my-report.yaml",
+        },
+        {
+            label: "Initialize from an existing studio report",
+            command: "dx studio reports init ./my-report.yaml --id s4525phi3dud",
+        },
+        {
+            label: "Create a studio report from the template",
+            command: "dx studio reports create --from-file ./my-report.yaml",
+        },
+    ]))
+        .action(wrapAction(async (path, options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        if (options.id) {
+            const id = options.id;
+            let reportResponse;
+            try {
+                reportResponse = await getStudioReportInfo(runtime, id);
+            }
+            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 studio report "${id}": ${err instanceof Error ? err.message : String(err)}`, exitCode);
+            }
+            fs.writeFileSync(path, studioReportToYaml(reportResponse.report), "utf8");
+            if (runtime.context.json) {
+                renderJson({ ok: true, id, path });
+            }
+            else {
+                renderRichText([
+                    ui.p(`${ui.success(ui.GLYPHS.CHECK)} Studio report template written to ${ui.code(path)}.`),
+                    ui.p(`Edit the file, then run: ${ui.code(`dx studio reports create --from-file ${path}`)}`),
+                ]);
+            }
+        }
+        else {
+            fs.writeFileSync(path, STUDIO_REPORT_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 studio reports create --from-file ${path}`)}`),
+                ]);
+            }
+        }
+    }));
+    reports
+        .command("list")
+        .description("List Data Studio reports")
+        .option("--cursor <cursor>", "Cursor for the next page of results")
+        .option("--limit <n>", "Max reports per page (default is 50, max is 100)", (value) => parseLimitOption(value, "--limit"))
+        .option("--search-term <term>", "Search reports by name")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "List studio reports",
+            command: "dx studio reports list",
+        },
+        {
+            label: "List studio reports as JSON",
+            command: "dx --json studio reports list",
+        },
+        {
+            label: "Search studio reports by name",
+            command: "dx studio reports list --search-term deployment",
+        },
+        {
+            label: "Fetch the next page using a cursor from the prior response",
+            command: "dx studio reports list --cursor rpt_123 --limit 100",
+        },
+    ]))
+        .action(wrapAction(async (options, command) => {
+        const runtime = await buildRuntime(getContext(command));
+        const response = await listStudioReports(runtime, {
+            cursor: parseOptionalTextOption(options.cursor),
+            limit: options.limit,
+            search_term: parseOptionalTextOption(options.searchTerm),
+        });
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderStudioReports(response);
+        }
+    }));
+    reports
+        .command("update")
+        .description("Update a Data Studio report from a YAML file or stdin. The `init` command can be used to initialize the report file.")
+        .argument("<id>", "Studio report ID")
+        .option("--from-file <path>", "Read a YAML file and update the report with its contents")
+        .option("--from-stdin", "Read YAML from stdin and update the report with its contents")
+        .addHelpText("afterAll", createExampleText([
+        {
+            label: "Initialize a file first",
+            command: "dx studio reports init ./my-report.yaml --id s4525phi3dud",
+        },
+        {
+            label: "Update a studio report from a YAML file",
+            command: "dx studio reports update s4525phi3dud --from-file ./my-report.yaml",
+        },
+        {
+            label: "Update a studio report from stdin",
+            command: "cat ./my-report.yaml | dx studio reports update s4525phi3dud --from-stdin",
+        },
+    ]))
+        .action(wrapAction(async (id, 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 = buildUpdateReportPayload(id, raw);
+        const response = await updateStudioReport(runtime, payload);
+        if (runtime.context.json) {
+            renderJson(response);
+        }
+        else {
+            renderStudioReportUpdated(response.report);
+        }
+    }));
+    return reports;
+}
+async function createStudioReport(runtime, payload) {
+    const response = await request(runtime, "/studio.reports.create", {
+        method: "POST",
+        body: payload,
+    });
+    return response.body;
+}
+async function updateStudioReport(runtime, payload) {
+    const response = await request(runtime, "/studio.reports.update", {
+        method: "POST",
+        body: payload,
+    });
+    return response.body;
+}
+async function getStudioReportInfo(runtime, id) {
+    const response = await request(runtime, "/studio.reports.info", {
+        method: "GET",
+        query: { id },
+    });
+    return response.body;
+}
+async function listStudioReports(runtime, options) {
+    const response = await request(runtime, "/studio.reports.list", {
+        method: "GET",
+        query: options,
+    });
+    return response.body;
+}
+function renderStudioReportCreated(report) {
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Studio report created`),
+        renderStudioReport(report),
+    ]);
+}
+function renderStudioReportInfo(report) {
+    renderRichText([ui.h1("Studio Report"), renderStudioReport(report)]);
+}
+function renderStudioReportUpdated(report) {
+    renderRichText([
+        ui.p(`${ui.success(ui.GLYPHS.CHECK)} Studio report updated`),
+        renderStudioReport(report),
+    ]);
+}
+function renderStudioReports(response) {
+    const blocks = [ui.h1("Studio Reports")];
+    blocks.push(ui.p(`Displaying ${ui.bold(response.reports.length.toString())} reports.`));
+    if (response.reports.length === 0) {
+        blocks.push(ui.p(ui.dim("(None)")));
+    }
+    for (const report of response.reports) {
+        blocks.push(...renderStudioReport(report));
+    }
+    const nextCursor = response.response_metadata?.next_cursor;
+    if (nextCursor) {
+        blocks.push(ui.p(`Next cursor: ${ui.code(nextCursor)} ${ui.dim(`(use --cursor ${nextCursor})`)}`));
+    }
+    renderRichText(blocks);
+}
+function renderStudioReport(report) {
+    const blocks = [
+        ui.h2(`${formatReportName(report)} (${ui.code(report.id)})`),
+        ui.dl([
+            ui.dli("URL", ui.link(report.url)),
+            ui.dli("Description", formatOptionalText(report.description)),
+            ui.dli("View access", formatViewAccessType(report.view_access_type)),
+            ui.dli("Edit access", formatEditAccessType(report.edit_access_type)),
+            ui.dli("Tiles", report.tiles.length.toString()),
+            ui.dli("Created", ui.timestampSummary(report.created_at)),
+            ui.dli("Updated", ui.timestampSummary(report.updated_at)),
+        ], { termWidth: 13 }),
+    ];
+    if (report.tiles.length > 0) {
+        blocks.push(ui.h3("Tiles"), ui.ul(report.tiles.map((tile) => ui.li(`${formatTileTitle(tile)} ${ui.dim(`(${tile.chart_type})`)}`))));
+    }
+    return blocks;
+}
+function parseOptionalTextOption(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function parseLimitOption(value, flag) {
+    const limit = parsePositiveIntOption(value, flag);
+    if (limit > 100) {
+        throw new CliError(`${flag} must be at most 100`, EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return limit;
+}
+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(`Could not parse YAML from stdin: ${err.message}`, EXIT_CODES.ARGUMENT_ERROR));
+            }
+        });
+        process.stdin.on("error", reject);
+    });
+}
+function buildCreateReportPayload(raw) {
+    const { id: _id, ...rest } = parseYamlObject(raw);
+    return rest;
+}
+function buildUpdateReportPayload(id, raw) {
+    return { ...parseYamlObject(raw), id };
+}
+function parseYamlObject(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CliError("YAML content must be an object", EXIT_CODES.ARGUMENT_ERROR);
+    }
+    return raw;
+}
+const STUDIO_REPORT_BLANK_TEMPLATE_YAML = fs.readFileSync(new URL("./report-blank-template.yaml", import.meta.url), "utf8");
+function studioReportToYaml(report) {
+    const payload = {
+        name: report.name ?? "",
+        owner_email: "",
+        description: report.description ?? "",
+        markdown_notes: report.markdown_notes ?? "",
+        view_access_type: report.view_access_type,
+        viewer_emails: [],
+        edit_access_type: report.edit_access_type,
+        editor_emails: [],
+        tiles: report.tiles.map((tile) => ({
+            title: tile.title,
+            sql: tile.sql,
+            chart_type: tile.chart_type,
+            chart_config: tile.chart_config,
+        })),
+    };
+    return stringifyYaml(payload, { blockQuote: "literal" });
+}
+function formatReportName(report) {
+    return report.name && report.name.trim().length > 0
+        ? report.name
+        : ui.dim("(Untitled)");
+}
+function formatTileTitle(tile) {
+    return tile.title && tile.title.trim().length > 0
+        ? tile.title
+        : ui.dim("(Untitled tile)");
+}
+function formatOptionalText(value) {
+    return value && value.trim().length > 0 ? value : ui.dim("(None)");
+}
+function formatViewAccessType(value) {
+    switch (value) {
+        case "owner_and_direct_url_only":
+            return "Visible via direct URL";
+        case "specific_users":
+            return "Visible to specific users";
+        case "everyone":
+            return "Visible to everyone";
+        default:
+            return value;
+    }
+}
+function formatEditAccessType(value) {
+    switch (value) {
+        case "everyone":
+            return "Editable by everyone";
+        case "specific_users":
+            return "Editable by specific users";
+        case "owner_only":
+            return "Editable by owner only";
+        default:
+            return value;
+    }
+}

package/dist/commands/studio.js

@@ -1,9 +1,11 @@
 import { Command } from "commander";
 import { queryCommand } from "./studio/query.js";
+import { reportsCommand } from "./studio/reports.js";
 export function studioCommand() {
     const studio = new Command()
         .name("studio")
         .description("Perform data studio actions");
     studio.addCommand(queryCommand());
+    studio.addCommand(reportsCommand());
     return studio;
 }

package/dist/config.js

@@ -15,17 +15,36 @@ export function readConfig() {
     }
     const content = fs.readFileSync(configPath, "utf8");
     const raw = JSON.parse(content);
-    const api = raw.apiBaseUrl;
-    const web = raw.webBaseUrl;
     const stored = {};
-    if (web) {
-        stored.webBaseUrl = web;
+    if (typeof raw.webBaseUrl === "string") {
+        stored.webBaseUrl = raw.webBaseUrl;
+    }
+    if (typeof raw.apiBaseUrl === "string") {
+        stored.apiBaseUrl = raw.apiBaseUrl;
+    }
+    if (raw.currentVersionCache && typeof raw.currentVersionCache === "object") {
+        stored.currentVersionCache = raw.currentVersionCache;
     }
-    if (api) {
-        stored.apiBaseUrl = api;
+    if (raw.versionPromptSelection &&
+        typeof raw.versionPromptSelection === "object") {
+        stored.versionPromptSelection =
+            raw.versionPromptSelection;
     }
     return stored;
 }
+export function persistCurrentVersionCache(cache) {
+    writeConfig({ ...readConfig(), currentVersionCache: cache });
+}
+export function persistVersionPromptSelection(prompt) {
+    const config = readConfig();
+    if (prompt === undefined) {
+        delete config.versionPromptSelection;
+    }
+    else {
+        config.versionPromptSelection = prompt;
+    }
+    writeConfig(config);
+}
 /**
  * Responsible for handling the migration from `baseUrl` to `apiBaseUrl` and `webBaseUrl`,
  * so the upgrade to 0.3.x will be non-breaking for `cloud` and `dedicated` deployments.

package/dist/skill.js

@@ -0,0 +1,9 @@
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export async function isSkillInstalled() {
+    const skillPath = join(homedir(), ".agents", "skills", "dx-cli");
+    return access(skillPath)
+        .then(() => true)
+        .catch(() => false);
+}

package/dist/versionCheck.js

@@ -0,0 +1,203 @@
+import { select } from "@inquirer/prompts";
+import dayjs from "dayjs";
+import { execa } from "execa";
+import { persistCurrentVersionCache, persistVersionPromptSelection, readConfig, } from "./config.js";
+import { request } from "./http.js";
+import { renderRichText } from "./renderers.js";
+import { buildRuntimeSafe } from "./runtime.js";
+import { isSkillInstalled } from "./skill.js";
+import * as ui from "./ui.js";
+import cliPackage from "../package.json" with { type: "json" };
+const VERSION_CHECK_INTERVAL_HOURS = 24;
+const SNOOZE_DAYS = 7;
+const SKIP_COMMANDS = new Set(["auth", "init"]);
+/**
+ * Compares two semver strings (e.g. "1.2.3").
+ * Returns a negative number if a < b, 0 if equal, positive if a > b.
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => v.split(".").map((n) => parseInt(n, 10));
+    const [aMajor = 0, aMinor = 0, aPatch = 0] = parse(a);
+    const [bMajor = 0, bMinor = 0, bPatch = 0] = parse(b);
+    return aMajor - bMajor || aMinor - bMinor || aPatch - bPatch;
+}
+/**
+ * Returns true if a version fetch should be attempted — i.e. no cached result
+ * exists or the cached result is older than VERSION_CHECK_INTERVAL_HOURS.
+ */
+export function shouldPerformVersionCheck(config) {
+    const cache = config.currentVersionCache;
+    if (!cache?.updatedAt) {
+        return true;
+    }
+    const age = dayjs().diff(dayjs(cache.updatedAt), "hour");
+    return age >= VERSION_CHECK_INTERVAL_HOURS;
+}
+/**
+ * Returns true if the upgrade prompt should be shown to the user, taking into
+ * account any previously persisted SKIP or SNOOZE state.
+ */
+export function shouldShowVersionPrompt(latestVersion, versionPromptSelection) {
+    if (!versionPromptSelection) {
+        return true;
+    }
+    if (versionPromptSelection.type === "SKIP" &&
+        versionPromptSelection.skipVersion === latestVersion) {
+        return false;
+    }
+    if (versionPromptSelection.type === "SNOOZE" &&
+        dayjs().isBefore(dayjs(versionPromptSelection.snoozeUntil))) {
+        return false;
+    }
+    return true;
+}
+async function fetchLatestVersion(runtime) {
+    const response = await request(runtime, "/cli.currentVersion", { method: "GET" });
+    return response.body.versions.cli;
+}
+/**
+ * Checks whether a newer CLI version is available.
+ *
+ * Returns:
+ *   "available"  — a newer version exists and the user should be prompted
+ *   "up-to-date" — the installed version is current (or the user has snoozed/skipped)
+ *   "disabled"   — the check was skipped or could not run (env var, skip command, no token, network error)
+ */
+export async function checkForNewVersion(argv) {
+    if (process.env.DX_DISABLE_VERSION_CHECK) {
+        return { status: "disabled" };
+    }
+    const topLevelCommand = argv.slice(2).find((arg) => !arg.startsWith("-"));
+    if (topLevelCommand && SKIP_COMMANDS.has(topLevelCommand)) {
+        return { status: "disabled" };
+    }
+    const context = {
+        json: argv.includes("--json"),
+        agent: undefined,
+        agentSessionId: undefined,
+    };
+    const runtime = await buildRuntimeSafe(context);
+    if (!runtime) {
+        return { status: "disabled" };
+    }
+    const config = readConfig();
+    let latestVersion;
+    if (!shouldPerformVersionCheck(config)) {
+        latestVersion = config.currentVersionCache.contents.cli;
+    }
+    else {
+        try {
+            latestVersion = await fetchLatestVersion(runtime);
+        }
+        catch {
+            return { status: "disabled" };
+        }
+        persistCurrentVersionCache({
+            updatedAt: new Date().toISOString(),
+            contents: { cli: latestVersion },
+        });
+    }
+    if (compareVersions(latestVersion, cliPackage.version) <= 0) {
+        return { status: "up-to-date" };
+    }
+    if (!shouldShowVersionPrompt(latestVersion, readConfig().versionPromptSelection)) {
+        return { status: "up-to-date" };
+    }
+    return { status: "available", latestVersion };
+}
+/**
+ * Notifies the user that a new version is available and, in interactive
+ * sessions, prompts them to update, snooze, or skip.
+ *
+ * Returns a result indicating whether the user chose to update immediately,
+ * so the caller can invoke performUpdate() after the command finishes.
+ */
+export async function promptVersionUpdate(latestVersion) {
+    const noUpdate = { shouldUpdate: false };
+    const currentVersion = cliPackage.version;
+    const isInteractive = process.stdin.isTTY && process.stderr.isTTY;
+    if (!isInteractive) {
+        renderRichText([
+            ui.blankLine(),
+            ui.p(ui.warning(`A new version of the DX CLI is available: ${currentVersion} → ${latestVersion}`)),
+            ui.p(`Run: ${ui.code(`npm install -g @get-dx/cli@${latestVersion}`)}`),
+            ui.blankLine(),
+        ], { useStderr: true });
+        return noUpdate;
+    }
+    renderRichText([
+        ui.blankLine(),
+        ui.p(ui.warning(`A new version of the DX CLI is available: ${currentVersion} → ${latestVersion}`)),
+        ui.blankLine(),
+    ], { useStderr: true });
+    const choice = await select({
+        message: "What would you like to do?",
+        choices: [
+            { name: "Update now", value: "update" },
+            { name: `Remind me later (in ${SNOOZE_DAYS} days)`, value: "snooze" },
+            { name: "Skip this version", value: "skip" },
+        ],
+    });
+    if (choice === "update") {
+        persistVersionPromptSelection(undefined);
+        return { shouldUpdate: true, latestVersion };
+    }
+    if (choice === "snooze") {
+        persistVersionPromptSelection({
+            type: "SNOOZE",
+            snoozeUntil: dayjs().add(SNOOZE_DAYS, "day").toISOString(),
+        });
+    }
+    else {
+        persistVersionPromptSelection({ type: "SKIP", skipVersion: latestVersion });
+    }
+    return noUpdate;
+}
+/**
+ * Performs the actual CLI + skill upgrade after the user's command has finished.
+ */
+export async function performUpdate(latestVersion) {
+    if (await isSkillInstalled()) {
+        renderRichText([
+            ui.blankLine(),
+            ui.p(ui.bold("Updating the DX skill.")),
+            ui.p("This will run the following command:", false),
+            ui.codeBlock("npx --yes -- skills@latest update dx-cli --global"),
+            ui.blankLine(),
+        ], {
+            useStderr: true,
+        });
+        try {
+            await execa({
+                stdout: "inherit",
+                stderr: "inherit",
+                stdin: "inherit",
+            }) `npx --yes -- skills@latest update dx-cli --global`;
+        }
+        catch {
+            renderRichText([
+                ui.p(ui.warning("Warning: failed to update the DX skill. You can update it manually with: " +
+                    ui.code("npx skills update dx-cli --global"))),
+            ], { useStderr: true });
+        }
+    }
+    renderRichText([
+        ui.blankLine(),
+        ui.p(ui.bold(`Updating the DX CLI to ${latestVersion}.`)),
+        ui.p("This will run the following command:", false),
+        ui.codeBlock(`npm install -g @get-dx/cli@${latestVersion}`),
+        ui.blankLine(),
+    ], { useStderr: true });
+    try {
+        await execa({
+            stdout: "inherit",
+            stderr: "inherit",
+        }) `npm install -g @get-dx/cli@${latestVersion}`;
+    }
+    catch {
+        renderRichText([
+            ui.p(ui.warning(`Warning: failed to update the DX CLI. You can update it manually with: ` +
+                ui.code(`npm install -g @get-dx/cli@${latestVersion}`))),
+        ], { useStderr: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@get-dx/cli",
-  "version": "0.3.8",
+  "version": "0.5.0",
   "description": "DX CLI",
   "author": "DX <developers@getdx.com>",
   "bugs": {