argsbarg 3.1.0 → 3.3.0

package/src/headless.test.ts

@@ -0,0 +1,86 @@
+import { expect, test } from "bun:test";
+import {
+  formatDryRunMessage,
+  requireYesInNonTty,
+  shouldRunHeadless,
+  shouldRunHeadlessWithPositionals,
+  shouldRunHeadlessWithYes,
+  wantsDryRun,
+  wantsExplicitJson,
+} from "./headless.ts";
+
+test("wantsDryRun detects flag", () => {
+  expect(wantsDryRun(true)).toBe(true);
+  expect(wantsDryRun(false)).toBe(false);
+});
+
+test("wantsExplicitJson includes MCP invocation", () => {
+  expect(wantsExplicitJson({ invocation: "cli" }, false)).toBe(false);
+  expect(wantsExplicitJson({ invocation: "mcp" }, false)).toBe(true);
+  expect(wantsExplicitJson({ invocation: "cli" }, true)).toBe(true);
+});
+
+test("shouldRunHeadless is true for MCP and json", () => {
+  expect(shouldRunHeadless({ invocation: "mcp" }, false)).toBe(true);
+  expect(shouldRunHeadless({ invocation: "cli" }, true)).toBe(true);
+  expect(shouldRunHeadless({ invocation: "cli" }, false, true)).toBe(true);
+  expect(shouldRunHeadless({ invocation: "cli" }, false, false, false)).toBe(true);
+});
+
+test("shouldRunHeadlessWithPositionals requires positionals in non-tty", () => {
+  expect(
+    shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, [], false, false),
+  ).toBe(false);
+  expect(
+    shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, ["a"], false, false),
+  ).toBe(true);
+});
+
+test("shouldRunHeadlessWithYes requires yes in non-tty", () => {
+  expect(
+    shouldRunHeadlessWithYes(
+      { invocation: "cli" },
+      { yes: true, hasRequiredArgs: true },
+      false,
+    ),
+  ).toBe(true);
+  expect(
+    shouldRunHeadlessWithYes(
+      { invocation: "cli" },
+      { yes: false, hasRequiredArgs: true },
+      false,
+    ),
+  ).toBe(false);
+  expect(
+    shouldRunHeadlessWithYes(
+      { invocation: "cli" },
+      { yes: false, hasRequiredArgs: true, dryRun: true },
+      false,
+    ),
+  ).toBe(true);
+});
+
+test("formatDryRunMessage prefixes dry-run output", () => {
+  expect(formatDryRunMessage("hello", false)).toBe("hello");
+  expect(formatDryRunMessage("hello", true)).toBe("[DRY RUN] hello");
+});
+
+test("requireYesInNonTty exits without yes in non-tty", () => {
+  const originalExit = process.exit;
+  let code: number | undefined;
+  process.exit = ((c?: number) => {
+    code = c ?? 0;
+    throw new Error("exit");
+  }) as typeof process.exit;
+
+  try {
+    expect(() => {
+      requireYesInNonTty(false, "hint", false, false);
+    }).toThrow("exit");
+    expect(code).toBe(1);
+    requireYesInNonTty(false, "hint", true, false);
+    requireYesInNonTty(true, "hint", false, false);
+  } finally {
+    process.exit = originalExit;
+  }
+});

package/src/headless.ts

@@ -0,0 +1,86 @@
+import type { CliContext } from "./context.ts";
+import { isInteractiveTty } from "./utils.ts";
+
+/** Minimal context for headless routing helpers. */
+export type HeadlessContext = Pick<CliContext, "invocation">;
+
+/** True when `--dry-run` was passed. */
+export function wantsDryRun(hasDryRunFlag: boolean): boolean {
+  return hasDryRunFlag;
+}
+
+/** True when `--json` was passed or the handler was invoked via MCP. */
+export function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean {
+  return hasJsonFlag || ctx.invocation === "mcp";
+}
+
+/**
+ * Headless when MCP, `--json`, `--dry-run`, or stdin is not a TTY.
+ * Use for commands that should auto-emit JSON in pipelines.
+ */
+export function shouldRunHeadless(
+  ctx: HeadlessContext,
+  hasJsonFlag: boolean,
+  hasDryRunFlag = false,
+  interactive: boolean = isInteractiveTty,
+): boolean {
+  if (ctx.invocation === "mcp") return true;
+  if (hasJsonFlag || hasDryRunFlag) return true;
+  return !interactive;
+}
+
+/**
+ * Like {@link shouldRunHeadless}, but only auto-headless in non-TTY when positionals are present.
+ * Avoids turning empty invocations into JSON errors.
+ */
+export function shouldRunHeadlessWithPositionals(
+  ctx: HeadlessContext,
+  hasJsonFlag: boolean,
+  positionals: string[],
+  hasDryRunFlag = false,
+  interactive: boolean = isInteractiveTty,
+): boolean {
+  if (ctx.invocation === "mcp") return true;
+  if (hasJsonFlag || hasDryRunFlag) return true;
+  return !interactive && positionals.length > 0;
+}
+
+/**
+ * Headless when MCP, `--dry-run` with required args, or non-TTY with `--yes` and required args.
+ * Use for mutating commands that require explicit `--yes` in scripts.
+ */
+export function shouldRunHeadlessWithYes(
+  ctx: HeadlessContext,
+  opts: { yes: boolean; hasRequiredArgs: boolean; dryRun?: boolean },
+  interactive: boolean = isInteractiveTty,
+): boolean {
+  if (ctx.invocation === "mcp") {
+    return opts.hasRequiredArgs && (opts.yes || Boolean(opts.dryRun));
+  }
+  if (opts.dryRun && opts.hasRequiredArgs) return true;
+  if (!interactive) return opts.yes && opts.hasRequiredArgs;
+  return opts.yes && opts.hasRequiredArgs;
+}
+
+/**
+ * Exits when non-interactive mode is used without `--yes`.
+ * @param hint - Command-specific guidance appended to the error
+ */
+export function requireYesInNonTty(
+  yes: boolean,
+  hint: string,
+  dryRun = false,
+  interactive: boolean = isInteractiveTty,
+): void {
+  if (dryRun) return;
+  if (!interactive && !yes) {
+    process.stderr.write(`Error: non-interactive mode requires --yes. ${hint}\n`);
+    process.exit(1);
+  }
+}
+
+/** Prefixes a success message when running in dry-run mode. */
+export function formatDryRunMessage(message: string, dryRun: boolean): string {
+  if (!dryRun) return message;
+  return `[DRY RUN] ${message}`;
+}

package/src/help.ts

@@ -346,16 +346,12 @@ function usageLines(
 }
 
 /** Table rows for named options, including synthetic built-in rows. */
-function rowsForOptions(defs: CliOption[], color: boolean, isRoot: boolean): HelpRow[] {
+function rowsForOptions(defs: CliOption[], color: boolean): HelpRow[] {
   const rows: HelpRow[] = [];
   const helpLabel = color
     ? style.aquaBold("--help, ") + style.greenBright("-h")
     : "--help, -h";
   rows.push({ label: helpLabel, description: "Show help for this command." });
-  if (isRoot) {
-    const schemaLabel = color ? style.aquaBold("--schema") : "--schema";
-    rows.push({ label: schemaLabel, description: "Print the full command tree as JSON." });
-  }
   for (const o of defs) {
     const desc = o.required ? "(required) " + o.description : o.description;
     rows.push({ label: cliOptionLabel(o, color), description: desc });
@@ -401,7 +397,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
       ).join("\n"),
     );
 
-    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color, true), hw, color);
+    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color), hw, color);
     if (optBox.length > 0) {
       lines.push("");
       lines.push(optBox.join("\n"));
@@ -450,7 +446,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
     ).join("\n"),
   );
 
-  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color, false), hw, color);
+  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color), hw, color);
   if (optBox.length > 0) {
     lines.push("");
     lines.push(optBox.join("\n"));

package/src/index.test.ts

@@ -500,8 +500,8 @@ test("leaf completion help prints correctly", async () => {
   expect(stderr.toString()).toBe("");
 });
 
-test("--schema exports JSON for nested CLIs", async () => {
-  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts --schema`.nothrow().quiet();
+test("docs schema exports JSON for nested CLIs", async () => {
+  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts docs schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
   expect(stderr.toString()).toBe("");
 
@@ -516,15 +516,20 @@ test("--schema exports JSON for nested CLIs", async () => {
   expect(lookup.positionals[0].name).toBe("path");
 });
 
-test("--schema exports JSON for leaf roots", async () => {
-  const { stdout, exitCode } = await $`bun run examples/minimal.ts --schema`.nothrow().quiet();
+test("docs schema exports JSON for leaf roots", async () => {
+  const { stdout, exitCode } = await $`bun run examples/minimal.ts docs schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
 
   const schema = JSON.parse(stdout.toString());
   expect(schema.key).toBe("minimal.ts");
   expect(schema.positionals[0].name).toBe("name");
   expect(schema.options[0].name).toBe("verbose");
-  expect(schema.commands.map((c: { key: string }) => c.key)).toEqual(["completion", "version", "install"]);
+  expect(schema.commands.map((c: { key: string }) => c.key)).toEqual([
+    "completion",
+    "version",
+    "install",
+    "docs",
+  ]);
 });
 
 test("version builtin prints program version", async () => {
@@ -540,10 +545,15 @@ test("leaf root help lists completion built-in", async () => {
   expect(stdout.toString()).toContain("Generate the autocompletion script for shells.");
 });
 
-test("parse recognizes --schema at the program root", () => {
-  const root= testProgram({
+test("root --schema is no longer a flag", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
+    docs: {
+      enabled: true,
+      topics: { readme: { text: "# readme\n" } },
+    },
     commands: [
       {
         key: "x",
@@ -553,8 +563,8 @@ test("parse recognizes --schema at the program root", () => {
     ],
   });
   cliValidateProgram(root);
-  const pr = parse(root, ["--schema"]);
-  expect(pr.kind).toBe(ParseKind.Schema);
+  const pr = parse(cliPresentationRoot(root), ["--schema"]);
+  expect(pr.kind).not.toBe(ParseKind.Ok);
 });
 
 test("cliSchemaJson omits handlers and completion built-ins", () => {
@@ -587,32 +597,15 @@ test("cliSchemaJson omits handlers and completion built-ins", () => {
   expect(schema).not.toHaveProperty("handler");
 });
 
-test("reserved option name schema is rejected", () => {
-  const root= testProgram({
-    key: "app",
-    description: "",
-    commands: [
-      {
-        key: "x",
-        description: "cmd",
-        options: [
-          {
-            name: "schema",
-            description: "",
-            kind: CliOptionKind.String,
-          },
-        ],
-        handler: () => {},
-      },
-    ],
-  });
-  expect(() => cliValidateProgram(root)).toThrow(/reserved for --schema/);
-});
-
-test("root help lists --schema built-in", () => {
-  const root= testProgram({
+test("docs help lists schema, api, and skill subcommands", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
+    docs: {
+      enabled: true,
+      topics: { readme: { text: "# readme\n" } },
+    },
     commands: [
       {
         key: "x",
@@ -621,14 +614,19 @@ test("root help lists --schema built-in", () => {
       },
     ],
   });
-  const help = cliHelpRender(cliPresentationRoot(root), [], false);
-  expect(help).toContain("--schema");
+  const help = cliHelpRender(cliPresentationRoot(root), ["docs"], false);
+  expect(help).toContain("schema");
   expect(help).toContain("Print the full command tree as JSON.");
+  expect(help).toContain("api");
+  expect(help).toContain("markdown");
+  expect(help).toContain("skill");
+  expect(help).toContain("SKILL.md");
 });
 
-test("nested help omits --schema built-in", () => {
-  const root= testProgram({
+test("root help omits legacy --schema flag", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
     commands: [
       {
@@ -638,37 +636,10 @@ test("nested help omits --schema built-in", () => {
       },
     ],
   });
-  const help = cliHelpRender(cliPresentationRoot(root), ["x"], false);
+  const help = cliHelpRender(cliPresentationRoot(root), [], false);
   expect(help).not.toContain("--schema");
 });
 
-test("completion scripts offer --schema at the program root only", () => {
-  const root= testProgram({
-    key: "myapp",
-    description: "",
-    commands: [
-      {
-        key: "stat",
-        description: "stats",
-        commands: [
-          {
-            key: "show",
-            description: "show",
-            handler: () => {},
-          },
-        ],
-      },
-    ],
-  });
-
-  const bash = completionBashScript(cliPresentationRoot(root));
-  expect(bash).toContain("A_myapp_0_opts+=('--schema')");
-  expect(bash).not.toContain("A_myapp_1_opts+=('--schema')");
-
-  const zsh = completionZshScript(cliPresentationRoot(root));
-  expect(zsh).toContain("'--schema:Print the full command tree as JSON.'");
-});
-
 const nestedMcpFixture = testProgram({
   key: "nested.ts",
   description: "Nested groups demo.",

package/src/index.ts

@@ -20,9 +20,29 @@ export type {
   CliMcpServerConfig,
   CliMcpToolConfig,
   CliInstallConfig,
+  CliUpdateArtifact,
+  CliUpdateGetLatest,
   CliDocsConfig,
   CliDocsTopic,
   CliOption,
   CliPositional,
 } from "./types.ts";
 export { isInteractiveTty } from "./utils.ts";
+export {
+  formatDryRunMessage,
+  requireYesInNonTty,
+  shouldRunHeadless,
+  shouldRunHeadlessWithPositionals,
+  shouldRunHeadlessWithYes,
+  wantsDryRun,
+  wantsExplicitJson,
+} from "./headless.ts";
+export type { HeadlessContext } from "./headless.ts";
+export {
+  createGhFetchLatest,
+  createGhVersionCheck,
+  ghReleaseUpdateGetLatest,
+  isAlreadyCurrent,
+  parseReleaseTag,
+} from "./install/gh-release-update.ts";
+export type { GhReleaseUpdateConfig, GhVersionCheckConfig } from "./install/gh-release-update.ts";

package/src/install/binary.ts

@@ -16,8 +16,13 @@ export interface BinaryInstallResult {
   patchedZshRc: boolean;
 }
 
-/** Copies the running binary to the install path and patches rc files when shells are detected. */
-export function installBinary(root: CliProgram, paths: InstallPaths, dry: boolean): BinaryInstallResult {
+/** Copies a binary to the install path and patches rc files when shells are detected. */
+export function installBinary(
+  root: CliProgram,
+  paths: InstallPaths,
+  dry: boolean,
+  sourcePath: string = process.execPath,
+): BinaryInstallResult {
   const changed: string[] = [];
   const shells = detectShells();
   let patchedBashRc = false;
@@ -25,7 +30,7 @@ export function installBinary(root: CliProgram, paths: InstallPaths, dry: boolea
 
   if (!dry) {
     mkdirSync(paths.bindir, { recursive: true });
-    copyFileSync(process.execPath, paths.binaryPath);
+    copyFileSync(sourcePath, paths.binaryPath);
   }
   changed.push(paths.binaryPath);
 

package/src/install/gh-release-update.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { isAlreadyCurrent, parseReleaseTag } from "./gh-release-update.ts";
+
+test("parseReleaseTag strips leading v", () => {
+  expect(parseReleaseTag("v1.4.3")).toBe("1.4.3");
+});
+
+test("parseReleaseTag leaves bare semver unchanged", () => {
+  expect(parseReleaseTag("1.4.3")).toBe("1.4.3");
+});
+
+test("parseReleaseTag throws on empty tag", () => {
+  expect(() => parseReleaseTag("")).toThrow("Release tag is empty");
+});
+
+test("isAlreadyCurrent returns true when versions match", () => {
+  expect(isAlreadyCurrent("1.4.3", "1.4.3")).toBe(true);
+});
+
+test("isAlreadyCurrent returns false when versions differ", () => {
+  expect(isAlreadyCurrent("1.4.2", "1.4.3")).toBe(false);
+});

package/src/install/gh-release-update.ts

@@ -0,0 +1,229 @@
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import type { CliUpdateGetLatest } from "../types.ts";
+
+/** Config for {@link ghReleaseUpdateGetLatest}. */
+export interface GhReleaseUpdateConfig {
+  /** GitHub `owner/repo` slug. */
+  repo: string;
+  /** Release asset filename (e.g. `myapp`). */
+  asset: string;
+  /** Temp directory name prefix for downloads. */
+  tempPrefix: string;
+  /** Path to the on-disk version-check cache JSON file. */
+  cachePath: string;
+  /** Optional hint when `gh auth` fails or no releases exist. */
+  repoEnvHint?: string;
+}
+
+/** Config for {@link createGhVersionCheck}. */
+export interface GhVersionCheckConfig {
+  /** Installed semver string. */
+  currentVersion: string;
+  /** CLI command name for update notices (e.g. `qa`). */
+  commandName: string;
+  /** Path to the on-disk version-check cache JSON file. */
+  cachePath: string;
+  /** Cache TTL in milliseconds (default 24h). */
+  ttlMs?: number;
+  /** When true, skip background refresh (e.g. test subprocess). */
+  skipRefresh?: () => boolean;
+  /** When true, skip refresh because `gh` is unavailable. */
+  ghAvailable?: () => boolean;
+  /** Fetches latest release version via `gh`. */
+  fetchLatest: () => Promise<string>;
+}
+
+type VersionCheckCache = {
+  fetchedAt: number;
+  latest: string;
+};
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Returns whether the installed version matches the latest release. */
+export function isAlreadyCurrent(current: string, latest: string): boolean {
+  return current === latest;
+}
+
+/** Strips a leading `v` from a release tag. */
+export function parseReleaseTag(tag: string): string {
+  const trimmed = tag.trim();
+  if (!trimmed) {
+    throw new Error("Release tag is empty");
+  }
+  return trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
+}
+
+/** Builds a `CliUpdateGetLatest` hook that downloads a release via `gh`. */
+export function ghReleaseUpdateGetLatest(config: GhReleaseUpdateConfig): CliUpdateGetLatest {
+  const fetchLatest = createGhFetchLatest(config);
+
+  return async ({ version }) => {
+    ensureGhAvailable();
+
+    const latestVersion = await fetchLatest();
+    if (isAlreadyCurrent(version, latestVersion)) {
+      return { path: process.execPath, version: latestVersion };
+    }
+
+    const tempDir = mkdtempSync(join(tmpdir(), config.tempPrefix));
+    try {
+      const downloadedPath = await downloadReleaseAsset(config, tempDir);
+      chmodSync(downloadedPath, 0o755);
+      writeVersionCheckCache(config.cachePath, { fetchedAt: Date.now(), latest: latestVersion });
+      return {
+        path: downloadedPath,
+        version: latestVersion,
+        cleanup: () => {
+          rmSync(tempDir, { recursive: true, force: true });
+        },
+      };
+    } catch (err) {
+      rmSync(tempDir, { recursive: true, force: true });
+      throw err;
+    }
+  };
+}
+
+/** Version-check cache helpers for summary notices and background refresh. */
+export function createGhVersionCheck(config: GhVersionCheckConfig): {
+  getUpdateNotice: () => string | null;
+  refreshIfStale: () => void;
+} {
+  const ttlMs = config.ttlMs ?? DEFAULT_TTL_MS;
+  const ghAvailable = config.ghAvailable ?? (() => Bun.which("gh") !== null);
+
+  return {
+    getUpdateNotice(): string | null {
+      const cached = readVersionCheckCache(config.cachePath);
+      if (cached === null || isAlreadyCurrent(config.currentVersion, cached.latest)) {
+        return null;
+      }
+      return `Update available: v${cached.latest} (you have v${config.currentVersion}). Run \`${config.commandName} update\``;
+    },
+
+    refreshIfStale(): void {
+      if (config.skipRefresh?.()) return;
+      if (!ghAvailable()) return;
+
+      const cached = readVersionCheckCache(config.cachePath);
+      if (cached !== null && Date.now() - cached.fetchedAt < ttlMs) {
+        return;
+      }
+
+      void config.fetchLatest()
+        .then((latest) => {
+          writeVersionCheckCache(config.cachePath, { fetchedAt: Date.now(), latest });
+        })
+        .catch(() => {
+          // Best-effort; summary must never fail because of a version check.
+        });
+    },
+  };
+}
+
+/** Shared `gh release view` fetcher for hooks and version-check refresh. */
+export function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string> {
+  return async () => {
+    const result = await runGh([
+      "release",
+      "view",
+      "--repo",
+      config.repo,
+      "--json",
+      "tagName",
+    ]);
+
+    if (result.exitCode !== 0) {
+      const detail = result.stderr.trim() || result.stdout.trim();
+      const hint = detail.includes("auth") || detail.includes("401")
+        ? " Run `gh auth login` and try again."
+        : detail.includes("release not found") || detail.includes("Not Found")
+          ? config.repoEnvHint
+            ? ` ${config.repoEnvHint}`
+            : ` No releases found for ${config.repo}.`
+          : "";
+      throw new Error(
+        `Failed to fetch latest release from ${config.repo}: ${detail || "unknown error"}.${hint}`,
+      );
+    }
+
+    let parsed: { tagName?: string };
+    try {
+      parsed = JSON.parse(result.stdout) as { tagName?: string };
+    } catch {
+      throw new Error("Failed to parse release metadata from gh");
+    }
+
+    if (!parsed.tagName) {
+      throw new Error("No release tag found for this repository");
+    }
+
+    return parseReleaseTag(parsed.tagName);
+  };
+}
+
+function ensureGhAvailable(): void {
+  if (Bun.which("gh") === null) {
+    throw new Error(
+      "GitHub CLI (gh) is required. Install from https://cli.github.com/ and run `gh auth login`.",
+    );
+  }
+}
+
+async function downloadReleaseAsset(config: GhReleaseUpdateConfig, tempDir: string): Promise<string> {
+  const result = await runGh([
+    "release",
+    "download",
+    "--repo",
+    config.repo,
+    "--pattern",
+    config.asset,
+    "--dir",
+    tempDir,
+  ]);
+
+  if (result.exitCode !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new Error(
+      `Failed to download release from ${config.repo}: ${detail || "unknown error"}`,
+    );
+  }
+
+  const downloadedPath = join(tempDir, config.asset);
+  if (!existsSync(downloadedPath)) {
+    throw new Error(`Release asset "${config.asset}" was not found in the download`);
+  }
+
+  return downloadedPath;
+}
+
+async function runGh(args: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(["gh", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  return { exitCode, stdout, stderr };
+}
+
+function readVersionCheckCache(cachePath: string): VersionCheckCache | null {
+  try {
+    const raw = readFileSync(cachePath, "utf8");
+    const parsed = JSON.parse(raw) as VersionCheckCache;
+    if (typeof parsed.fetchedAt !== "number" || typeof parsed.latest !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeVersionCheckCache(cachePath: string, cache: VersionCheckCache): void {
+  mkdirSync(dirname(cachePath), { recursive: true });
+  writeFileSync(cachePath, JSON.stringify(cache));
+}