deepseek-tui 0.8.16 → 0.8.18

package/README.md

@@ -17,8 +17,10 @@ npm install deepseek-tui
 npx deepseek-tui --help
 ```
 
-`postinstall` downloads platform binaries into `bin/downloads/` and exposes
-`deepseek` and `deepseek-tui` commands.
+`postinstall` tries to download platform binaries into `bin/downloads/` and
+exposes `deepseek` and `deepseek-tui` commands. If GitHub release assets are
+temporarily unreachable, install continues and the wrapper retries the download
+on first run.
 
 ## First run
 
@@ -60,8 +62,9 @@ Prebuilt binaries for the GitHub release are downloaded automatically:
 - Windows x64
 
 Other platform/architecture combinations (musl, riscv64, FreeBSD, …) aren't
-shipped as prebuilts. The `postinstall` will exit with a clear error pointing
-you at `cargo install deepseek-tui-cli deepseek-tui --locked` and the full
+shipped as prebuilts. Unsupported platforms, checksum failures, and glibc
+compatibility problems still fail with a clear error pointing you at
+`cargo install deepseek-tui-cli deepseek-tui --locked` and the full
 [docs/INSTALL.md](https://github.com/Hmbown/DeepSeek-TUI/blob/main/docs/INSTALL.md)
 build-from-source guide.
 
@@ -70,9 +73,13 @@ build-from-source guide.
 - Default binary version comes from `deepseekBinaryVersion` in `package.json`.
 - Set `DEEPSEEK_TUI_VERSION` or `DEEPSEEK_VERSION` to override the release version.
 - Set `DEEPSEEK_TUI_GITHUB_REPO` or `DEEPSEEK_GITHUB_REPO` to override the source repo (defaults to `Hmbown/DeepSeek-TUI`).
+- Set `DEEPSEEK_TUI_RELEASE_BASE_URL` to use an internal or mirrored
+  release-asset directory when GitHub Releases is unavailable. The directory
+  must contain `deepseek-artifacts-sha256.txt` and the platform binaries.
 - Set `DEEPSEEK_TUI_FORCE_DOWNLOAD=1` to force download even when the cached binary is already present.
 - Set `DEEPSEEK_TUI_DISABLE_INSTALL=1` to skip install-time download.
-- Set `DEEPSEEK_TUI_OPTIONAL_INSTALL=1` to make the `postinstall` step warn and exit `0` on download/extract errors instead of failing `npm install` (useful in CI matrices).
+- Set `DEEPSEEK_TUI_OPTIONAL_INSTALL=1` to make install-time retryable download
+  failures warn and exit `0` instead of failing `npm install`.
 
 ## Release integrity
 
@@ -80,5 +87,3 @@ build-from-source guide.
   exist for the target GitHub release before publishing.
 - Install-time downloads are verified against the release checksum manifest before
   the wrapper marks them executable.
-- Set `DEEPSEEK_TUI_RELEASE_BASE_URL` to point the installer at a local or
-  staged release-asset directory for smoke tests.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "deepseek-tui",
-  "version": "0.8.16",
-  "deepseekBinaryVersion": "0.8.16",
+  "version": "0.8.18",
+  "deepseekBinaryVersion": "0.8.18",
   "description": "Install and run deepseek and deepseek-tui binaries from GitHub release artifacts.",
   "author": "Hmbown",
   "license": "MIT",
@@ -28,9 +28,10 @@
   },
   "scripts": {
     "release:check": "node scripts/verify-release-assets.js",
-    "postinstall": "node scripts/install.js",
+    "postinstall": "node scripts/install.js --optional",
     "prepublishOnly": "node scripts/verify-release-assets.js",
-    "prepack": "node scripts/install.js"
+    "prepack": "node scripts/install.js",
+    "test": "node --test test/*.test.js"
   },
   "engines": {
     "node": ">=18"
@@ -42,6 +43,7 @@
   "files": [
     "bin/*.js",
     "scripts/*.js",
+    "test/*.js",
     "README.md",
     "package.json"
   ]

package/scripts/install.js

@@ -1,3 +1,18 @@
+function assertSupportedNode() {
+  const version = process.versions && process.versions.node ? process.versions.node : "unknown";
+  const major = Number.parseInt(String(version).split(".")[0], 10);
+  if (Number.isNaN(major) || major < 18) {
+    process.stderr.write(
+      "deepseek-tui: Node.js 18 or newer is required for npm installation. " +
+      `Current Node.js version is ${version}. ` +
+      "Please upgrade Node.js and rerun `npm install -g deepseek-tui`.\n",
+    );
+    process.exit(1);
+  }
+}
+
+assertSupportedNode();
+
 const fs = require("fs");
 const https = require("https");
 const http = require("http");
@@ -20,14 +35,19 @@ const pkg = require("../package.json");
 
 const DEFAULT_TIMEOUT_MS = 300_000; // 5 minutes per attempt
 const DEFAULT_STALL_MS = 30_000; // abort if no bytes for 30s
+const OPTIONAL_TIMEOUT_MS = 15_000; // fail fast during optional npm postinstall
+const OPTIONAL_STALL_MS = 5_000; // avoid long hangs when install can recover on first run
 const MAX_ATTEMPTS = 5;
+const OPTIONAL_MAX_ATTEMPTS = 1; // runtime keeps the full retry budget on first launch
 const BASE_BACKOFF_MS = 1_000;
 
 const RETRYABLE_NET_CODES = new Set([
   "ECONNRESET",
   "ECONNREFUSED",
+  "EDOWNLOADTIMEOUT",
   "ETIMEDOUT",
   "EAI_AGAIN",
+  "ENOTFOUND",
   "ENETUNREACH",
   "EHOSTUNREACH",
   "EPIPE",
@@ -71,6 +91,38 @@ function resolveRepo() {
   return process.env.DEEPSEEK_TUI_GITHUB_REPO || process.env.DEEPSEEK_GITHUB_REPO || "Hmbown/DeepSeek-TUI";
 }
 
+function isOptionalInstall(argv = process.argv.slice(2), env = process.env) {
+  return (
+    argv.includes("--optional") ||
+    env.DEEPSEEK_TUI_OPTIONAL_INSTALL === "1" ||
+    env.DEEPSEEK_OPTIONAL_INSTALL === "1"
+  );
+}
+
+function isInstallContext(context) {
+  return context === "install";
+}
+
+// Optional install only relaxes npm postinstall behavior. Runtime downloads
+// keep the normal retry/timeout budget so first-run recovery stays resilient.
+function defaultTimeoutMs(context = "runtime", env = process.env) {
+  return isInstallContext(context) && isOptionalInstall(undefined, env)
+    ? OPTIONAL_TIMEOUT_MS
+    : DEFAULT_TIMEOUT_MS;
+}
+
+function defaultStallMs(context = "runtime", env = process.env) {
+  return isInstallContext(context) && isOptionalInstall(undefined, env)
+    ? OPTIONAL_STALL_MS
+    : DEFAULT_STALL_MS;
+}
+
+function maxAttempts(context = "runtime", env = process.env) {
+  return isInstallContext(context) && isOptionalInstall(undefined, env)
+    ? OPTIONAL_MAX_ATTEMPTS
+    : MAX_ATTEMPTS;
+}
+
 function binaryPaths() {
   const { deepseek, tui } = detectBinaryNames();
   const releaseDir = releaseBinaryDirectory();
@@ -105,6 +157,48 @@ function logInfo(message) {
   process.stderr.write(`deepseek-tui: ${message}\n`);
 }
 
+function installFailureHint(error) {
+  const message = error && error.message ? String(error.message) : "";
+  const code = error && error.code ? String(error.code) : "";
+  const releaseBase =
+    process.env.DEEPSEEK_TUI_RELEASE_BASE_URL ||
+    process.env.DEEPSEEK_RELEASE_BASE_URL;
+  const networkMarkers = [
+    "github.com",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "EDOWNLOADTIMEOUT",
+  ];
+  const looksLikeNetworkDownloadFailure = networkMarkers.some(
+    (marker) => message.includes(marker) || code === marker,
+  );
+  if (!looksLikeNetworkDownloadFailure) {
+    return "";
+  }
+
+  if (releaseBase) {
+    return [
+      "deepseek-tui install hint:",
+      `  DEEPSEEK_TUI_RELEASE_BASE_URL is set to ${releaseBase}`,
+      "  Verify that this directory contains deepseek-artifacts-sha256.txt",
+      "  plus the deepseek/deepseek-tui binary assets for your platform.",
+    ].join("\n");
+  }
+
+  return [
+    "deepseek-tui install hint:",
+    "  The npm package downloads prebuilt binaries from GitHub Releases.",
+    "  If GitHub is unavailable on this network, mirror the release assets and set:",
+    "    DEEPSEEK_TUI_RELEASE_BASE_URL=https://<mirror>/<release-asset-directory>/",
+    "  The directory must contain deepseek-artifacts-sha256.txt and the platform binaries.",
+    "  See docs/INSTALL.md#npm-download-is-slow-or-times-out-from-mainland-china.",
+  ].join("\n");
+}
+
 function envInt(name, fallback) {
   const raw = process.env[name];
   if (!raw) {
@@ -117,17 +211,17 @@ function envInt(name, fallback) {
   return parsed;
 }
 
-function downloadTimeoutMs() {
+function downloadTimeoutMs(context = "runtime") {
   return envInt(
     "DEEPSEEK_TUI_DOWNLOAD_TIMEOUT_MS",
-    envInt("DEEPSEEK_DOWNLOAD_TIMEOUT_MS", DEFAULT_TIMEOUT_MS),
+    envInt("DEEPSEEK_DOWNLOAD_TIMEOUT_MS", defaultTimeoutMs(context)),
   );
 }
 
-function downloadStallMs() {
+function downloadStallMs(context = "runtime") {
   return envInt(
     "DEEPSEEK_TUI_DOWNLOAD_STALL_MS",
-    envInt("DEEPSEEK_DOWNLOAD_STALL_MS", DEFAULT_STALL_MS),
+    envInt("DEEPSEEK_DOWNLOAD_STALL_MS", defaultStallMs(context)),
   );
 }
 
@@ -355,8 +449,16 @@ function connectThroughProxy(proxy, targetHost, targetPort, timeoutMs) {
 // ────────────────────────────────────────────────────────────────────────────
 
 function httpRequest(rawUrl, opts = {}) {
-  const totalTimeoutMs = opts.totalTimeoutMs ?? downloadTimeoutMs();
-  const stallMs = opts.stallMs ?? downloadStallMs();
+  const context =
+    opts.context === undefined || opts.context === null ? "runtime" : opts.context;
+  const totalTimeoutMs =
+    opts.totalTimeoutMs === undefined || opts.totalTimeoutMs === null
+      ? downloadTimeoutMs(context)
+      : opts.totalTimeoutMs;
+  const stallMs =
+    opts.stallMs === undefined || opts.stallMs === null
+      ? downloadStallMs(context)
+      : opts.stallMs;
 
   return new Promise((resolve, reject) => {
     let url;
@@ -645,7 +747,12 @@ function isRetryable(err) {
   if (err.nonRetryable) return false;
   if (err instanceof NonRetryableError) return false;
   if (err instanceof DownloadTimeoutError) return true;
-  if (err instanceof HttpStatusError) {
+  // withRetry() rethrows a plain Error while preserving name/status, so wrapped
+  // HTTP 5xx failures still classify as retryable during optional postinstall.
+  if (
+    (err instanceof HttpStatusError || err.name === "HttpStatusError") &&
+    typeof err.status === "number"
+  ) {
     return err.status >= 500;
   }
   if (err.code && RETRYABLE_NET_CODES.has(err.code)) return true;
@@ -668,27 +775,42 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function withRetry(label, fn) {
+async function withRetry(label, fn, context = "runtime") {
   let lastErr;
-  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+  const attemptLimit = maxAttempts(context);
+  for (let attempt = 1; attempt <= attemptLimit; attempt++) {
     try {
       return await fn(attempt);
     } catch (err) {
       lastErr = err;
-      if (!isRetryable(err) || attempt === MAX_ATTEMPTS) {
+      if (!isRetryable(err) || attempt === attemptLimit) {
         break;
       }
       const wait = backoffDelay(attempt);
       logInfo(
-        `${label} failed (attempt ${attempt}/${MAX_ATTEMPTS}): ${err.message}; retrying in ${wait} ms`,
+        `${label} failed (attempt ${attempt}/${attemptLimit}): ${err.message}; retrying in ${wait} ms`,
       );
       await sleep(wait);
     }
   }
   const msg = lastErr && lastErr.message ? lastErr.message : String(lastErr);
   const wrapped = new Error(
-    `${label} failed after ${MAX_ATTEMPTS} attempt(s): ${msg}`,
+    `${label} failed after ${attemptLimit} attempt(s): ${msg}`,
   );
+  // Preserve retry classification metadata because the install entrypoint uses
+  // the wrapped error to decide whether optional postinstall may ignore it.
+  if (lastErr && lastErr.code) {
+    wrapped.code = lastErr.code;
+  }
+  if (lastErr && lastErr.name) {
+    wrapped.name = lastErr.name;
+  }
+  if (lastErr && typeof lastErr.status === "number") {
+    wrapped.status = lastErr.status;
+  }
+  if (lastErr && lastErr.nonRetryable) {
+    wrapped.nonRetryable = true;
+  }
   if (lastErr && lastErr.stack) {
     wrapped.cause = lastErr;
   }
@@ -699,7 +821,7 @@ async function withRetry(label, fn) {
 // Public download primitives (now retry + progress aware)
 // ────────────────────────────────────────────────────────────────────────────
 
-async function followRedirects(url, opts) {
+async function followRedirects(url, opts = {}) {
   const maxRedirects = 10;
   let current = url;
   for (let hop = 0; hop < maxRedirects; hop++) {
@@ -744,17 +866,21 @@ function streamToFile(response, destination, progress) {
 async function download(url, destination, options = {}) {
   await mkdir(path.dirname(destination), { recursive: true });
   const assetName = options.assetName || path.basename(destination);
+  const context =
+    options.context === undefined || options.context === null ? "runtime" : options.context;
+  const attemptLimit = maxAttempts(context);
   await withRetry(`download ${assetName}`, async (attempt) => {
     const result = await followRedirects(url, {
-      totalTimeoutMs: downloadTimeoutMs(),
-      stallMs: downloadStallMs(),
+      context,
+      totalTimeoutMs: downloadTimeoutMs(context),
+      stallMs: downloadStallMs(context),
     });
     const response = result.response;
     const lenHeader = response.headers["content-length"];
     const total = lenHeader ? Number.parseInt(lenHeader, 10) : 0;
     const progress = createProgressReporter(assetName, Number.isFinite(total) ? total : 0);
     if (attempt > 1) {
-      logInfo(`retry attempt ${attempt}/${MAX_ATTEMPTS} for ${assetName}`);
+      logInfo(`retry attempt ${attempt}/${attemptLimit} for ${assetName}`);
     }
     try {
       await streamToFile(response, destination, progress);
@@ -768,14 +894,17 @@ async function download(url, destination, options = {}) {
       throw err;
     }
     progress.finish();
-  });
+  }, context);
 }
 
-async function downloadText(url) {
+async function downloadText(url, options = {}) {
+  const context =
+    options.context === undefined || options.context === null ? "runtime" : options.context;
   return withRetry(`fetch ${url}`, async () => {
     const result = await followRedirects(url, {
-      totalTimeoutMs: downloadTimeoutMs(),
-      stallMs: downloadStallMs(),
+      context,
+      totalTimeoutMs: downloadTimeoutMs(context),
+      stallMs: downloadStallMs(context),
     });
     const response = result.response;
     response.setEncoding("utf8");
@@ -798,7 +927,7 @@ async function downloadText(url) {
       });
       response.on("error", reject);
     });
-  });
+  }, context);
 }
 
 async function readLocalVersion(file) {
@@ -850,11 +979,11 @@ async function verifyChecksum(filePath, assetName, checksums) {
   }
 }
 
-async function loadChecksums(version, repo) {
-  return parseChecksumManifest(await downloadText(checksumManifestUrl(version, repo)));
+async function loadChecksums(version, repo, options = {}) {
+  return parseChecksumManifest(await downloadText(checksumManifestUrl(version, repo), options));
 }
 
-async function ensureBinary(targetPath, assetName, version, repo, getChecksums) {
+async function ensureBinary(targetPath, assetName, version, repo, getChecksums, options = {}) {
   const marker = `${targetPath}.version`;
   const downloadIfNeeded =
     process.env.DEEPSEEK_TUI_FORCE_DOWNLOAD === "1" || process.env.DEEPSEEK_FORCE_DOWNLOAD === "1";
@@ -870,7 +999,7 @@ async function ensureBinary(targetPath, assetName, version, repo, getChecksums)
   const checksums = await getChecksums();
   const url = releaseAssetUrl(assetName, version, repo);
   const destination = `${targetPath}.${process.pid}.${Date.now()}.download`;
-  await download(url, destination, { assetName });
+  await download(url, destination, { assetName, context: options.context });
   try {
     await verifyChecksum(destination, assetName, checksums);
     preflightGlibc(destination);
@@ -886,7 +1015,21 @@ async function ensureBinary(targetPath, assetName, version, repo, getChecksums)
   return targetPath;
 }
 
-async function run() {
+// Optional install may only downgrade retryable download failures to warnings.
+// Unsupported platforms, checksum mismatches, glibc compatibility errors, and
+// malformed release metadata must still fail with actionable diagnostics.
+function shouldIgnoreInstallFailure(
+  context,
+  error,
+  argv = process.argv.slice(2),
+  env = process.env,
+) {
+  return isInstallContext(context) && isOptionalInstall(argv, env) && isRetryable(error);
+}
+
+async function run(options = {}) {
+  const context =
+    options.context === undefined || options.context === null ? "runtime" : options.context;
   if (process.env.DEEPSEEK_TUI_DISABLE_INSTALL === "1" || process.env.DEEPSEEK_DISABLE_INSTALL === "1") {
     return;
   }
@@ -899,19 +1042,19 @@ async function run() {
   let checksumsPromise;
   const getChecksums = () => {
     if (!checksumsPromise) {
-      checksumsPromise = loadChecksums(version, repo);
+      checksumsPromise = loadChecksums(version, repo, { context });
     }
     return checksumsPromise;
   };
 
   await Promise.all([
-    ensureBinary(paths.deepseek.target, paths.deepseek.asset, version, repo, getChecksums),
-    ensureBinary(paths.tui.target, paths.tui.asset, version, repo, getChecksums),
+    ensureBinary(paths.deepseek.target, paths.deepseek.asset, version, repo, getChecksums, { context }),
+    ensureBinary(paths.tui.target, paths.tui.asset, version, repo, getChecksums, { context }),
   ]);
 }
 
 async function getBinaryPath(name) {
-  await run();
+  await run({ context: "runtime" });
   const paths = binaryPaths();
   if (name === "deepseek") {
     return paths.deepseek.target;
@@ -924,15 +1067,28 @@ async function getBinaryPath(name) {
 
 module.exports = {
   getBinaryPath,
+  installFailureHint,
   run,
+  _internal: {
+    isOptionalInstall,
+    shouldIgnoreInstallFailure,
+    defaultTimeoutMs,
+    defaultStallMs,
+    maxAttempts,
+    withRetry,
+  },
 };
 
 if (require.main === module) {
-  run().catch((error) => {
+  run({ context: "install" }).catch((error) => {
     console.error("deepseek-tui install failed:", error.message);
-    if (process.env.DEEPSEEK_TUI_OPTIONAL_INSTALL === "1") {
+    const hint = installFailureHint(error);
+    if (hint) {
+      console.error(hint);
+    }
+    if (shouldIgnoreInstallFailure("install", error)) {
       console.error(
-        "DEEPSEEK_TUI_OPTIONAL_INSTALL=1 set; continuing without a usable binary.",
+        "Optional install enabled; continuing without a usable binary. The download will be retried on first run.",
       );
       process.exit(0);
     }

package/scripts/run.js

@@ -3,9 +3,8 @@ const { getBinaryPath } = require("./install");
 
 const pkg = require("../package.json");
 
-function isVersionFlag() {
-  const args = process.argv.slice(2);
-  return args.includes("--version") || args.includes("-v") || args.includes("-V");
+function isVersionFlag(args = process.argv.slice(2)) {
+  return args.includes("--version") || args.includes("-V");
 }
 
 function handleVersionFallback(binaryName) {
@@ -46,6 +45,7 @@ module.exports = {
   run,
   runDeepseek,
   runDeepseekTui,
+  _internal: { isVersionFlag },
 };
 
 if (require.main === module) {

package/test/install.test.js

@@ -0,0 +1,71 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const test = require("node:test");
+
+const installScript = fs.readFileSync(
+  path.join(__dirname, "..", "scripts", "install.js"),
+  "utf8",
+);
+const { installFailureHint } = require("../scripts/install");
+
+test("install script checks Node support before loading helpers", () => {
+  const guardIndex = installScript.indexOf("assertSupportedNode();");
+  const firstRequireIndex = installScript.indexOf("require(");
+
+  assert.notEqual(guardIndex, -1);
+  assert.notEqual(firstRequireIndex, -1);
+  assert.ok(guardIndex < firstRequireIndex);
+});
+
+test("install script remains parseable before the Node support guard runs", () => {
+  assert.equal(installScript.includes("??"), false);
+  assert.equal(installScript.includes("?."), false);
+});
+
+test("install failure hint explains release base override for blocked GitHub downloads", () => {
+  const previous = process.env.DEEPSEEK_TUI_RELEASE_BASE_URL;
+  delete process.env.DEEPSEEK_TUI_RELEASE_BASE_URL;
+  try {
+    const error = Object.assign(
+      new Error(
+        "fetch https://github.com/Hmbown/DeepSeek-TUI/releases/download/v0.8.18/deepseek-artifacts-sha256.txt failed after 5 attempts:\ngetaddrinfo ENOTFOUND github.com",
+      ),
+      { code: "ENOTFOUND" },
+    );
+
+    const hint = installFailureHint(error);
+
+    assert.match(hint, /DEEPSEEK_TUI_RELEASE_BASE_URL/);
+    assert.match(hint, /deepseek-artifacts-sha256\.txt/);
+    assert.match(hint, /platform binaries/);
+  } finally {
+    if (previous === undefined) {
+      delete process.env.DEEPSEEK_TUI_RELEASE_BASE_URL;
+    } else {
+      process.env.DEEPSEEK_TUI_RELEASE_BASE_URL = previous;
+    }
+  }
+});
+
+test("install failure hint checks configured release base when override is already set", () => {
+  const previous = process.env.DEEPSEEK_TUI_RELEASE_BASE_URL;
+  process.env.DEEPSEEK_TUI_RELEASE_BASE_URL = "https://mirror.example/deepseek/";
+  try {
+    const error = Object.assign(new Error("download stalled"), {
+      code: "EDOWNLOADTIMEOUT",
+    });
+
+    const hint = installFailureHint(error);
+
+    assert.match(hint, /is set to https:\/\/mirror\.example\/deepseek\//);
+    assert.match(hint, /deepseek-artifacts-sha256\.txt/);
+    assert.doesNotMatch(hint, /If GitHub is unavailable/);
+  } finally {
+    if (previous === undefined) {
+      delete process.env.DEEPSEEK_TUI_RELEASE_BASE_URL;
+    } else {
+      process.env.DEEPSEEK_TUI_RELEASE_BASE_URL = previous;
+    }
+  }
+});

package/test/postinstall.test.js

@@ -0,0 +1,91 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const pkg = require("../package.json");
+const { _internal } = require("../scripts/install");
+
+test("postinstall opts into optional install mode", () => {
+  assert.equal(pkg.scripts.postinstall, "node scripts/install.js --optional");
+});
+
+test("optional install can be enabled by command-line flag or env", () => {
+  assert.equal(_internal.isOptionalInstall(["--optional"], {}), true);
+  assert.equal(_internal.isOptionalInstall([], {}), false);
+  assert.equal(_internal.isOptionalInstall([], { DEEPSEEK_TUI_OPTIONAL_INSTALL: "1" }), true);
+  assert.equal(_internal.isOptionalInstall([], { DEEPSEEK_OPTIONAL_INSTALL: "1" }), true);
+});
+
+test("optional mode only changes install-time defaults", () => {
+  assert.equal(_internal.maxAttempts("install", { DEEPSEEK_TUI_OPTIONAL_INSTALL: "1" }), 1);
+  assert.equal(_internal.maxAttempts("runtime", { DEEPSEEK_TUI_OPTIONAL_INSTALL: "1" }), 5);
+  assert.equal(_internal.defaultTimeoutMs("install", { DEEPSEEK_TUI_OPTIONAL_INSTALL: "1" }), 15_000);
+  assert.equal(_internal.defaultTimeoutMs("runtime", { DEEPSEEK_TUI_OPTIONAL_INSTALL: "1" }), 300_000);
+  assert.equal(_internal.defaultStallMs("install", { DEEPSEEK_TUI_OPTIONAL_INSTALL: "1" }), 5_000);
+  assert.equal(_internal.defaultStallMs("runtime", { DEEPSEEK_TUI_OPTIONAL_INSTALL: "1" }), 30_000);
+});
+
+test("optional install only swallows retryable download failures", () => {
+  const socketHangUp = new Error("socket hang up");
+  assert.equal(
+    _internal.shouldIgnoreInstallFailure("install", socketHangUp, ["--optional"], {}),
+    true,
+  );
+
+  const timedOut = new Error("download exceeded total timeout of 15000 ms");
+  timedOut.code = "EDOWNLOADTIMEOUT";
+  assert.equal(
+    _internal.shouldIgnoreInstallFailure("install", timedOut, ["--optional"], {}),
+    true,
+  );
+
+  const unsupported = new Error("Unsupported platform: freebsd");
+  assert.equal(
+    _internal.shouldIgnoreInstallFailure("install", unsupported, ["--optional"], {}),
+    false,
+  );
+
+  const badChecksum = new Error("Checksum mismatch for deepseek-linux-x64");
+  badChecksum.nonRetryable = true;
+  assert.equal(
+    _internal.shouldIgnoreInstallFailure("install", badChecksum, ["--optional"], {}),
+    false,
+  );
+
+  const glibc = new Error("requires glibc 2.34 or newer");
+  glibc.nonRetryable = true;
+  assert.equal(
+    _internal.shouldIgnoreInstallFailure("install", glibc, ["--optional"], {}),
+    false,
+  );
+});
+
+test("optional install still swallows wrapped http 5xx failures", async () => {
+  const previous = process.env.DEEPSEEK_TUI_OPTIONAL_INSTALL;
+  process.env.DEEPSEEK_TUI_OPTIONAL_INSTALL = "1";
+  const http5xx = new Error("Request failed with status 502: https://example.invalid");
+  http5xx.name = "HttpStatusError";
+  http5xx.status = 502;
+
+  try {
+    await assert.rejects(
+      _internal.withRetry("fetch https://example.invalid", async () => {
+        throw http5xx;
+      }, "install"),
+      (wrapped) => {
+        assert.equal(wrapped.name, "HttpStatusError");
+        assert.equal(wrapped.status, 502);
+        assert.equal(
+          _internal.shouldIgnoreInstallFailure("install", wrapped, ["--optional"], {}),
+          true,
+        );
+        return true;
+      },
+    );
+  } finally {
+    if (previous === undefined) {
+      delete process.env.DEEPSEEK_TUI_OPTIONAL_INSTALL;
+    } else {
+      process.env.DEEPSEEK_TUI_OPTIONAL_INSTALL = previous;
+    }
+  }
+});

package/test/run.test.js

@@ -0,0 +1,11 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { _internal } = require("../scripts/run");
+
+test("version fallback handles only version flags", () => {
+  assert.equal(_internal.isVersionFlag(["--version"]), true);
+  assert.equal(_internal.isVersionFlag(["-V"]), true);
+  assert.equal(_internal.isVersionFlag(["-v"]), false);
+  assert.equal(_internal.isVersionFlag(["--verbose"]), false);
+});