@drakulavich/kesha-voice-kit 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {
@@ -109,18 +109,18 @@
   },
   "kesha": {
     "engine": {
-      "version": "2.0.0",
+      "version": "2.1.0",
       "sha256": {
-        "kesha-engine-darwin-arm64": "2d75bc773fb81917a0dd996124c0e18eea3b15ecc8f04fe274d41c68bda9276c",
-        "kesha-engine-linux-x64": "09082a1f3eb07d8f8051806a057669f098856d84541f087a1e614ca80d8235b2",
-        "kesha-engine-windows-x64.exe": "de86f350bfd3d076cf339d99d892605b1a37a99085e8ff4c8ef87057618193f3",
+        "kesha-engine-darwin-arm64": "51446285f272a3d5060aa2dd21d2d16a5c31682a8554f29c944fe1af27677008",
+        "kesha-engine-linux-x64": "8728b467ca31640739dcbe18e53eadd27e795033075f6442fc14b729e0014a62",
+        "kesha-engine-windows-x64.exe": "82515821a6b424ff9c75462721f7723891705a2f1edcba0a1eb5c1704cfadbec",
         "say-avspeech-darwin-arm64": "a3aa5b75ddff68a48f1158e838310b37cac72ef86841d9cfcdf1ee233cb7451a",
         "kesha-textlang-darwin-arm64": "e45e2822248b14dd72aa79e2def8fa6b9c07c97423f11c841508769225d72da4"
       },
       "size": {
-        "kesha-engine-darwin-arm64": 73623152,
-        "kesha-engine-linux-x64": 67392296,
-        "kesha-engine-windows-x64.exe": 66550272,
+        "kesha-engine-darwin-arm64": 73639664,
+        "kesha-engine-linux-x64": 67394344,
+        "kesha-engine-windows-x64.exe": 66586112,
         "say-avspeech-darwin-arm64": 64208,
         "kesha-textlang-darwin-arm64": 57648
       }

package/src/cli/init.ts

@@ -176,14 +176,7 @@ export async function promptInitSelection(
   };
 }
 
-/** Mirrors the guard in `performInstall`: a preview must not describe an install this platform rejects (#684). */
-async function printPlan(selection: InitSelection): Promise<boolean> {
-  const backendError = unavailableBackendRefusal(selection.backend);
-  if (backendError) {
-    log.error(errorMessage(backendError));
-    process.exitCode = exitCodeFor(backendError);
-    return false;
-  }
+async function printPlan(selection: InitSelection): Promise<void> {
   log.info(
     await renderInstallPlan({
       noCache: selection.noCache,
@@ -193,7 +186,6 @@ async function printPlan(selection: InitSelection): Promise<boolean> {
       diarize: selection.diarize,
     }),
   );
-  return true;
 }
 
 async function runNonInteractive(selection: InitSelection): Promise<void> {
@@ -203,7 +195,7 @@ async function runNonInteractive(selection: InitSelection): Promise<void> {
     log.warn("--diarize is currently darwin-arm64 only; omitting it from non-interactive examples.");
   }
   log.info(renderInitOverview(canDiarize));
-  if (!(await printPlan(printableSelection))) return;
+  await printPlan(printableSelection);
   log.info("Run one of these commands from an interactive terminal:");
   for (const command of initSuggestionCommands(printableSelection, canDiarize)) {
     log.info(`  ${command.join(" ")}`);
@@ -262,6 +254,13 @@ export const initCommand = defineCommand({
     const noCache = resolveNoCacheFlag(args, rawArgs);
     const selection = resolveInitSelection(args, backend, noCache);
 
+    const backendError = args.yes && !args.plan ? null : unavailableBackendRefusal(backend);
+    if (backendError) {
+      log.error(errorMessage(backendError));
+      process.exitCode = exitCodeFor(backendError);
+      return;
+    }
+
     if (args.plan) {
       log.info(renderInitOverview());
       await printPlan(selection);
@@ -293,7 +292,7 @@ export const initCommand = defineCommand({
       noCache,
     );
     log.info("");
-    if (!(await printPlan(prompted))) return;
+    await printPlan(prompted);
     const confirmed = await promptConfirm(
       `Run \`${initInstallArgs(prompted).join(" ")}\` now?`,
       true,

package/src/cli/install.ts

@@ -246,7 +246,7 @@ export async function performInstall(options: PerformInstallOptions) {
       throw backendError;
     }
     await installEngine({ noCache, backend, ttsLangs, vad, diarize, version: engineVersion });
-    await maybeAskForStar(getEngineBinPath(), packageVersion, log);
+    if (!log.quietEnabled) await maybeAskForStar(getEngineBinPath(), packageVersion, { info: log.progress, warn: log.warn });
     finishInstallDiagnostic(diagnosticLog, startedAt, "success");
   } catch (err: unknown) {
     const signalExitCode = getPendingSignalExitCode();

package/src/cli/support-bundle.ts

@@ -1,5 +1,6 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
+import { exitCodeFor, KeshaError } from "../engine/events";
 import { createSupportBundle } from "../support-bundle";
 import { log } from "../log";
 
@@ -35,7 +36,7 @@ export const supportBundleCommand = defineCommand({
       log.status(`Size: ${bundle.sizeBytes} bytes`);
     } catch (err) {
       log.error(errorMessage(err));
-      process.exit(1);
+      process.exit(err instanceof KeshaError ? exitCodeFor(err) : 1);
     }
   },
 });

package/src/engine-install.ts

@@ -19,6 +19,7 @@ import { runEngineProcess } from "./engine/spawn";
 import { acquireInstallLock } from "./install-lock";
 import { log } from "./log";
 import { engineVersion, injectedEnginePins } from "./package-info";
+import { PATH_ERRNOS } from "./path-errnos";
 import { keshaCacheDir } from "./paths";
 import { createLiveStatus, streamResponseToFile } from "./progress";
 import { interruptedRun } from "./process-tree";
@@ -37,6 +38,8 @@ export {
 } from "./engine-version-marker";
 
 const GITHUB_REPO = "drakulavich/kesha-voice-kit";
+const NETWORK_HINT = "check your network connection and try again.";
+const MISMATCH_HINT = `re-run \`kesha install\`; if the mismatch persists, report it at https://github.com/${GITHUB_REPO}/issues.`;
 
 interface ExpectedSha256 {
   sha256: string;
@@ -51,30 +54,46 @@ export interface AssetPins {
 }
 
 /** Without `--engine-version` nothing but the maintainer can make an unverifiable pinned release verifiable. */
-function unverifiableFix(version: string): string {
+function unverifiableFix(version: string, pins: AssetPins | undefined): string {
+  if (!pins) {
+    return version === engineVersion
+      ? `this source checkout installs its own version v${engineVersion}, which may not be released yet: run ` +
+          `\`kesha install --engine-version <version>\` with a published release that ships SHA256SUMS (https://github.com/${GITHUB_REPO}/releases).`
+      : `pass --engine-version a published release that ships SHA256SUMS (https://github.com/${GITHUB_REPO}/releases).`;
+  }
   return version === engineVersion
     ? `report it at https://github.com/${GITHUB_REPO}/issues: the pinned engine release v${version} must publish its checksums.`
     : `pick a release that ships SHA256SUMS (https://github.com/${GITHUB_REPO}/releases), or run ` +
         `\`kesha install\` without --engine-version to install the pinned v${engineVersion}.`;
 }
 
-async function fetchSha256Sums(version: string): Promise<Map<string, string>> {
+async function fetchSha256Sums(version: string, pins: AssetPins | undefined): Promise<Map<string, string>> {
   const url = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/SHA256SUMS`;
   let res: Response;
   try {
     res = await fetch(url, { redirect: "follow" });
   } catch (e) {
-    throw new Error(
-      `Failed to fetch SHA256SUMS for release v${version}: ${errorMessage(e)}\n  Fix: Check your network connection and try again`,
-    );
+    throw new KeshaError("E_MODEL_DOWNLOAD", `Failed to fetch SHA256SUMS for release v${version}: ${errorMessage(e)}`, {
+      hint: NETWORK_HINT,
+    });
   }
   if (!res.ok) {
-    throw new Error(
+    throw new KeshaError(
+      "E_MODEL_DOWNLOAD",
       `Cannot verify engine v${version}: release v${version} publishes no SHA256SUMS (HTTP ${res.status}), ` +
-        `so its binaries cannot be checked before they are installed.\n  Fix: ${unverifiableFix(version)}`,
+        "so its binaries cannot be checked before they are installed.",
+      { hint: unverifiableFix(version, pins) },
     );
   }
-  return parseSha256Sums(await res.text());
+  let body: string;
+  try {
+    body = await res.text();
+  } catch (e) {
+    throw new KeshaError("E_MODEL_DOWNLOAD", `Failed to read SHA256SUMS for release v${version}: ${errorMessage(e)}`, {
+      hint: NETWORK_HINT,
+    });
+  }
+  return parseSha256Sums(body);
 }
 
 /**
@@ -92,12 +111,14 @@ export function releaseChecksums(
       if (!pinned) throw new Error(`No pinned SHA-256 for ${assetName} of engine v${version}; this CLI build is incomplete.\n  Fix: report it at https://github.com/${GITHUB_REPO}/issues.`);
       return { sha256: pinned, source: "its pinned SHA-256" };
     }
-    sums ??= fetchSha256Sums(version);
+    sums ??= fetchSha256Sums(version, pins);
     const sha256 = (await sums).get(assetName);
     if (!sha256) {
-      throw new Error(
+      throw new KeshaError(
+        "E_MODEL_DOWNLOAD",
         `Cannot verify ${assetName}: the SHA256SUMS of release v${version} does not list it, ` +
-          `so it cannot be checked before it is installed.\n  Fix: ${unverifiableFix(version)}`,
+          "so it cannot be checked before it is installed.",
+        { hint: unverifiableFix(version, pins) },
       );
     }
     return { sha256, source: `the SHA-256 in the SHA256SUMS of release v${version}` };
@@ -129,25 +150,44 @@ async function rejectMismatchedDownload(
   return (
     `${what} from release v${version} does not match ${expected.source}: ` +
     `expected sha256 ${expected.sha256}, got ${actual}. The download was corrupted or altered, ` +
-    "so it was deleted instead of installed.\n" +
-    `  Fix: re-run \`kesha install\`; if the mismatch persists, report it at https://github.com/${GITHUB_REPO}/issues.`
+    "so it was deleted instead of installed."
   );
 }
 
 /**
  * Whether a cached asset of the pinned release still hashes to its pin; one that does not is
- * deleted so the verified download replaces it. `--engine-version` caches are not re-hashed.
+ * deleted so the verified download replaces it, or refused when its directory is read-only.
+ * `--engine-version` caches are not re-hashed.
  */
-async function cachedAssetMatchesPin(path: string, assetName: string, what: string, version: string): Promise<boolean> {
+async function cachedAssetMatchesPin(
+  path: string,
+  assetName: string,
+  what: string,
+  version: string,
+  canRepair: boolean,
+): Promise<boolean> {
   // KESHA_ENGINE_BIN names the user's own build, which no release pin describes.
   if (version !== engineChecksums.pins?.version || process.env.KESHA_ENGINE_BIN || !existsSync(path)) return true;
   const expected = await engineChecksums.forRelease(version)(assetName);
-  const actual = await sha256OfFile(path);
+  let actual: string;
+  try {
+    actual = await sha256OfFile(path);
+  } catch (e) {
+    throw canRepair ? e : unreadableInReadOnlyDir(path, e);
+  }
   if (actual === expected.sha256) return true;
-  log.warn(
-    `Installed ${what} ${assetName} does not match ${expected.source} (expected sha256 ${expected.sha256}, ` +
-      `got ${actual}); deleting it and downloading a verified copy.`,
-  );
+  const mismatch =
+    `Installed ${what} ${assetName} at ${path} does not match ${expected.source} ` +
+    `(expected sha256 ${expected.sha256}, got ${actual})`;
+  if (!canRepair) {
+    const dir = dirname(path);
+    throw new KeshaError("E_CACHE_CORRUPT", `${mismatch}; ${dir} is read-only, so it cannot be replaced.`, {
+      hint:
+        `make ${dir} writable and re-run \`kesha install\` to replace it with a verified copy, ` +
+        "or point KESHA_CACHE_DIR at a writable directory and re-run `kesha install`.",
+    });
+  }
+  log.warn(`${mismatch}; deleting it and downloading a verified copy.`);
   rmSync(path, { force: true });
   return false;
 }
@@ -209,7 +249,7 @@ export function cleanupRetiredSidecars(engineDir: string): string[] {
   }
 
   if (removed.length > 0) {
-    log.success(`Removed retired sidecars: ${removed.join(", ")}.`);
+    log.progress(`Removed retired sidecars: ${removed.join(", ")}.`);
   }
 
   return removed;
@@ -320,12 +360,12 @@ async function downloadSidecar(
     await streamResponseToFile(res, sidecarPath, spec.displayName);
     const refusal = await rejectMismatchedDownload(sidecarPath, `${spec.displayName} ${spec.assetName}`, version, expected);
     if (refusal) {
-      log.warn(`${refusal}\n  ${spec.displayName} not installed; ${spec.unavailableHint}.`);
+      log.warn(`${refusal}\n  Fix: ${MISMATCH_HINT}\n  ${spec.displayName} not installed; ${spec.unavailableHint}.`);
       return;
     }
     chmodSync(sidecarPath, 0o755);
     darwinTrustBinary(sidecarPath, spec.displayName);
-    log.success(`${spec.displayName} installed (${spec.availableHint}).`);
+    log.progress(`${spec.displayName} installed (${spec.availableHint}).`);
   } catch (e) {
     log.warn(
       `${spec.displayName} install failed (${errorMessage(e)}); ${spec.unavailableHint}.`,
@@ -376,7 +416,7 @@ export async function warmDarwinKokoro(binPath: string, timeoutMs = 180_000): Pr
       return;
     }
 
-    log.success(
+    log.progress(
       `FluidAudio Kokoro warmed (${Math.round(performance.now() - startedAt)}ms).`,
     );
   } catch (e) {
@@ -446,19 +486,18 @@ async function refreshCachedEngine(
 ): Promise<void> {
   const engineDir = dirname(binPath);
   if (noCache && !canWriteEngineDir) {
-    log.info(
+    log.warn(
       `Engine binary at v${version} is on a read-only filesystem; --no-cache skipped for engine (still forwarded to model installs).`,
     );
   } else {
-    log.success(`Engine binary already installed (v${version}).`);
+    log.progress(`Engine binary already installed (v${version}).`);
   }
   // Re-trust on cache hit: a user who upgraded to Sequoia after install would still have
   // com.apple.provenance attached; idempotent (~10ms no-op if already correct).
   if (canWriteEngineDir && existsSync(binPath)) {
     darwinTrustBinary(binPath, "kesha-engine binary");
   }
-  // Top up missing or broken sidecars (pre-#141/#199 cached binaries never had them);
-  // skip on read-only fs (Nix-store) to avoid confusing "install failed" warnings.
+  // Top up missing or broken sidecars (pre-#141/#199 cached binaries never had them).
   if (canWriteEngineDir) {
     const checksums = engineChecksums.forRelease(version);
     await Promise.all(
@@ -468,7 +507,7 @@ async function refreshCachedEngine(
         // sidecar is SIGKILLed on spawn, and re-downloading it would not lift the block.
         let pinned = false;
         try {
-          pinned = existsSync(path) && (await cachedAssetMatchesPin(path, spec.assetName, spec.displayName, version));
+          pinned = existsSync(path) && (await cachedAssetMatchesPin(path, spec.assetName, spec.displayName, version, true));
         } catch (e) {
           log.warn(`Could not read ${spec.displayName} at ${path} (${errorMessage(e)}); removing it and downloading it again.`);
           rmSync(path, { force: true });
@@ -479,6 +518,10 @@ async function refreshCachedEngine(
         }
       }),
     );
+  } else {
+    for (const spec of SIDECARS) {
+      await cachedAssetMatchesPin(join(engineDir, spec.fileBasename), spec.assetName, spec.displayName, version, false);
+    }
   }
 }
 
@@ -602,32 +645,35 @@ async function fetchEngineBinary(
     res = await fetch(url, { redirect: "follow" });
   } catch (e) {
     muteSidecarRejections();
-    throw new Error(
-      `Failed to fetch engine binary: ${errorMessage(e)}\n  Fix: Check your network connection and try again`,
-    );
+    throw new KeshaError("E_MODEL_DOWNLOAD", `Failed to fetch engine binary: ${errorMessage(e)}`, { hint: NETWORK_HINT });
   }
 
   if (!res.ok) {
     muteSidecarRejections();
     // Names the tag: nothing falls back to the pin, so the caller must see which release 404ed.
-    throw new Error(
-      `Failed to download engine binary from release v${version} (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
-    );
+    throw new KeshaError("E_MODEL_DOWNLOAD", `Failed to download engine binary from release v${version} (HTTP ${res.status})`, {
+      hint: `check https://github.com/${GITHUB_REPO}/releases for available versions.`,
+    });
   }
 
-  await streamResponseToFile(res, binPath, "kesha-engine binary");
+  try {
+    await streamResponseToFile(res, binPath, "kesha-engine binary");
+  } catch (e) {
+    muteSidecarRejections();
+    throw e instanceof KeshaError ? e : (engineWriteFailure(binPath, e) ?? e);
+  }
   const refusal = await rejectMismatchedDownload(binPath, `kesha-engine binary ${binaryName}`, version, expected);
   if (refusal) {
     muteSidecarRejections();
     rmSync(getVersionMarkerPath(binPath), { force: true });
-    throw new Error(refusal);
+    throw new KeshaError("E_CACHE_CORRUPT", refusal, { hint: MISMATCH_HINT });
   }
   chmodSync(binPath, 0o755);
   darwinTrustBinary(binPath, "kesha-engine binary");
   // Marker last: writing it first sends the retry down the cacheValid branch, which never waits.
   await waitUntilSpawnable(binPath);
   writeInstalledEngineVersion(binPath, version);
-  log.success(`Engine binary downloaded (v${version}).`);
+  log.progress(`Engine binary downloaded (v${version}).`);
   await Promise.all(sidecarPromises);
 }
 
@@ -807,17 +853,28 @@ async function assertRequestedVersionLanded(binPath: string, version: string): P
   );
 }
 
-/** mkdir errnos that mean the configured path is itself wrong; anything else is not a bad argument. */
-const ENGINE_DIR_PATH_ERRNOS: Record<string, string> = {
-  EACCES: "permission denied",
-  EPERM: "permission denied",
-  ENOTDIR: "a component of it is a file, not a directory",
-  // mkdir(recursive) raises this, not ENOTDIR, when the engine directory itself is an existing file.
-  EEXIST: "it already exists as a file, not a directory",
-  EROFS: "the filesystem is read-only",
-  ELOOP: "the path loops through symlinks",
-  ENAMETOOLONG: "the path is too long",
-};
+function engineDirSetting(): { name: string; value: string } | null {
+  if (process.env.KESHA_ENGINE_BIN) return { name: "KESHA_ENGINE_BIN", value: process.env.KESHA_ENGINE_BIN };
+  if (process.env.KESHA_CACHE_DIR) return { name: "KESHA_CACHE_DIR", value: process.env.KESHA_CACHE_DIR };
+  if (process.env.KESHA_HOME) return { name: "KESHA_HOME", value: process.env.KESHA_HOME };
+  return null;
+}
+
+function unreadableInReadOnlyDir(path: string, e: unknown): unknown {
+  const errno = (e as NodeJS.ErrnoException).code ?? "";
+  const why = PATH_ERRNOS[errno];
+  if (!why) return e;
+  const dir = dirname(path);
+  return new KeshaError(
+    "E_INVALID_ARG",
+    `Cannot verify ${path} against its pinned SHA-256: ${why} (${errno}), and ${dir} is read-only, so it cannot be replaced.`,
+    {
+      hint:
+        `make ${path} readable and ${dir} writable, then re-run \`kesha install\`. Or ` +
+        engineDirFix(engineDirSetting()?.name, false, dir),
+    },
+  );
+}
 
 /** `KESHA_ENGINE_BIN` names the binary file, so "point it at a writable directory" breaks the next install. */
 function engineDirFix(setting: string | undefined, notADir: boolean, engineDir: string): string {
@@ -847,15 +904,9 @@ function ensureEngineDirCreatable(binPath: string): void {
   try {
     mkdirSync(engineDir, { recursive: true });
   } catch (e) {
-    const setting = process.env.KESHA_ENGINE_BIN
-      ? { name: "KESHA_ENGINE_BIN", value: process.env.KESHA_ENGINE_BIN }
-      : process.env.KESHA_CACHE_DIR
-        ? { name: "KESHA_CACHE_DIR", value: process.env.KESHA_CACHE_DIR }
-        : process.env.KESHA_HOME
-          ? { name: "KESHA_HOME", value: process.env.KESHA_HOME }
-          : null;
+    const setting = engineDirSetting();
     const errno = (e as NodeJS.ErrnoException).code ?? "";
-    const why = ENGINE_DIR_PATH_ERRNOS[errno];
+    const why = PATH_ERRNOS[errno];
     const what = setting
       ? `${setting.name}="${setting.value}" cannot hold the engine directory ${engineDir}: ${why ?? errorMessage(e)}`
       : `cannot create the engine directory ${engineDir}: ${why ?? errorMessage(e)}`;
@@ -871,6 +922,28 @@ function ensureEngineDirCreatable(binPath: string): void {
   }
 }
 
+function engineWriteFailure(binPath: string, e: unknown): KeshaError | null {
+  const engineDir = dirname(binPath);
+  const errno = (e as NodeJS.ErrnoException).code ?? "";
+  const setting = engineDirSetting();
+  const into = setting ? `${engineDir} (from ${setting.name}="${setting.value}")` : engineDir;
+  const why = PATH_ERRNOS[errno];
+  if (why) {
+    return new KeshaError("E_INVALID_ARG", `Cannot write the engine binary into ${into}: ${why}`, {
+      hint: engineDirFix(setting?.name, errno === "ENOTDIR" || errno === "EEXIST", engineDir),
+    });
+  }
+  if (!errno) return null;
+  if (errno === "ENOSPC") {
+    return new KeshaError("E_INTERNAL", `Cannot write the engine binary into ${into}: no space left on its disk (ENOSPC)`, {
+      hint: `the disk is full: free space on the volume that holds ${engineDir}, then re-run \`kesha install\`.`,
+    });
+  }
+  return new KeshaError("E_INTERNAL", `Cannot write the engine binary into ${into}: ${errorMessage(e)}`, {
+    hint: `resolve that filesystem error on ${engineDir} and re-run \`kesha install\`; if it persists, file a bug with \`kesha support-bundle\`.`,
+  });
+}
+
 export interface EngineInstallRequest extends InstallOptions {
   noCache?: boolean;
   backend?: string;
@@ -913,7 +986,7 @@ async function installLockedEngine(
   const engineDir = dirname(binPath);
 
   if (version !== engineVersion) {
-    log.info(
+    log.warn(
       `Installing engine v${version} instead of the pinned v${engineVersion}; ` +
         "a later `kesha install` without --engine-version restores the pin.",
     );
@@ -923,15 +996,14 @@ async function installLockedEngine(
   const canWriteEngineDir = checkEngineWritable(engineDir);
 
   const markerMatches = existsSync(binPath) && installedVersion === version;
-  // The marker vouches for a file, not for a working binary. Skipped on a read-only engine
-  // dir: nothing there can be repaired, so a failed probe would only turn a usable Nix
+  // The marker vouches for a file, not for a working binary. The probe is skipped on a read-only
+  // engine dir: nothing there can be repaired, so a failed probe would only turn a usable Nix
   // install into a hard error.
   // Hashed before the health probe, so an altered binary is never run.
   const versionMatches =
     markerMatches &&
-    (!canWriteEngineDir ||
-      ((await cachedAssetMatchesPin(binPath, getEngineBinaryName(), "kesha-engine binary", version)) &&
-        (await engineWorks(binPath))));
+    (await cachedAssetMatchesPin(binPath, getEngineBinaryName(), "kesha-engine binary", version, canWriteEngineDir)) &&
+    (!canWriteEngineDir || (await engineWorks(binPath)));
   // On read-only fs, --no-cache can't re-download; treat as cache-valid and forward flag to model install.
   const cacheValid = versionMatches && (!noCache || !canWriteEngineDir);
 

package/src/path-errnos.ts

@@ -0,0 +1,11 @@
+/** Errnos that mean the path itself is wrong for writing, so the fix is a different path; anything else is not a bad argument. */
+export const PATH_ERRNOS: Record<string, string> = {
+  EACCES: "permission denied",
+  EPERM: "permission denied",
+  ENOTDIR: "a component of it is a file, not a directory",
+  // mkdir(recursive) raises this, not ENOTDIR, when the directory itself is an existing file.
+  EEXIST: "it already exists as a file, not a directory",
+  EROFS: "the filesystem is read-only",
+  ELOOP: "the path loops through symlinks",
+  ENAMETOOLONG: "the path is too long",
+};

package/src/progress.ts

@@ -1,6 +1,7 @@
 import { copyFileSync, readdirSync, renameSync, rmSync, statSync } from "fs";
 import { basename, dirname, join } from "path";
 import { errorMessage } from "./error-utils";
+import { KeshaError } from "./engine/events";
 import { log } from "./log";
 
 const BAR_WIDTH = 20;
@@ -172,11 +173,15 @@ export async function applyBackpressure(
  */
 const STALE_STAGING_MS = 24 * 60 * 60 * 1000;
 
+export function stagingPrefix(destPath: string): string {
+  return `${destPath}.part.`;
+}
+
 /** A Ctrl-C kills the process before any cleanup runs, so last run's staging file is swept by the next one (#770). */
 function sweepStagingFiles(destPath: string): void {
   if (process.platform === "win32") return;
   const dir = dirname(destPath);
-  const prefix = `${basename(destPath)}.part.`;
+  const prefix = basename(stagingPrefix(destPath));
   const cutoffMs = Date.now() - STALE_STAGING_MS;
 
   let names: string[];
@@ -225,32 +230,44 @@ export async function streamResponseToFile(
   destPath: string,
   label: string,
 ): Promise<number> {
-  if (!res.body) {
-    throw new Error(
-      `Download failed: empty response for ${label}\n  Fix: Try again — the server may be temporarily unavailable`,
-    );
-  }
+  const emptyResponse = () =>
+    new KeshaError("E_MODEL_DOWNLOAD", `Download failed: empty response for ${label}`, {
+      hint: "try again; the server may be temporarily unavailable.",
+    });
+  if (!res.body) throw emptyResponse();
 
   const totalBytes = Number(res.headers.get("content-length") || 0);
   const progress = createProgressBar(label, totalBytes);
 
   sweepStagingFiles(destPath);
-  const stagingPath = `${destPath}.part.${process.pid}.${stagingSeq++}`;
-  const writer = Bun.file(stagingPath).writer();
+  const stagingPath = `${stagingPrefix(destPath)}${process.pid}.${stagingSeq++}`;
+  const reader = res.body.getReader();
   let bytes = 0;
   try {
+    const writer = Bun.file(stagingPath).writer();
     try {
-      for await (const chunk of res.body) {
-        await applyBackpressure(writer, writer.write(chunk));
-        bytes += chunk.length;
-        progress.update(chunk.length);
+      for (;;) {
+        let next: Awaited<ReturnType<typeof reader.read>>;
+        try {
+          next = await reader.read();
+        } catch (err) {
+          throw new KeshaError("E_MODEL_DOWNLOAD", `Download of ${label} broke off after ${bytes} bytes: ${errorMessage(err)}`, {
+            hint: "check your network connection and try again.",
+          });
+        }
+        if (next.done) break;
+        await applyBackpressure(writer, writer.write(next.value));
+        bytes += next.value.length;
+        progress.update(next.value.length);
       }
     } finally {
       // Must await: an open write handle makes the freshly-downloaded engine unspawnable — EBUSY on Windows, ETXTBSY on Linux.
       await writer.end();
     }
+    if (bytes === 0) throw emptyResponse();
     publishStaging(stagingPath, destPath);
   } catch (err) {
+    reader.cancel().catch(() => {});
     rmSync(stagingPath, { force: true });
     throw err;
   }
@@ -272,7 +289,7 @@ export function createProgressBar(label: string, totalBytes: number): {
     return {
       update() {},
       finish() {
-        log.success(`Downloaded ${label} ✓`);
+        log.progress(`Downloaded ${label} ✓`);
       },
     };
   }

package/src/support-bundle.ts

@@ -1,8 +1,11 @@
-import { existsSync, mkdirSync, statSync, writeFileSync } from "fs";
-import { basename, dirname, resolve } from "path";
+import { lstatSync, mkdirSync, statSync, writeFileSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
 import { gzipSync } from "node:zlib";
 import { collectDoctorReport, formatDoctorReport } from "./doctor";
 import { readDiagnosticLogTail } from "./diagnostic-log";
+import { KeshaError } from "./engine/events";
+import { errorMessage } from "./error-utils";
+import { PATH_ERRNOS } from "./path-errnos";
 
 interface SupportBundleOptions {
   output?: string;
@@ -99,6 +102,66 @@ function createTarArchive(entries: TarEntry[]): Uint8Array {
   return archive;
 }
 
+function existsAsLink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function fileInTheWay(dir: string): string | null {
+  for (let d = dir; ; d = dirname(d)) {
+    try {
+      return statSync(d).isDirectory() ? null : d;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code === "ENOENT" && existsAsLink(d)) return d;
+      if (dirname(d) === d) return null;
+    }
+  }
+}
+
+function mkdirReason(dir: string, errno: string): string {
+  if (errno !== "EEXIST") return errno;
+  try {
+    statSync(dir);
+    return errno;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code ?? errno;
+  }
+}
+
+function bundleWriteFailure(outputPath: string, e: unknown): unknown {
+  const dir = dirname(outputPath);
+  const errno = mkdirReason(dir, (e as NodeJS.ErrnoException).code ?? "");
+  const blocker = fileInTheWay(dir);
+  if (blocker) {
+    return new KeshaError("E_INVALID_ARG", `Cannot write the support bundle to ${outputPath}: ${blocker} exists and is not a directory`, {
+      hint: `remove or rename the file blocking ${blocker}, or pass --output a path under a directory.`,
+    });
+  }
+  if (errno === "EISDIR") {
+    return new KeshaError("E_INVALID_ARG", `Cannot write the support bundle to ${outputPath}: it is a directory (EISDIR)`, {
+      hint: `pass --output a .tar.gz file path, for example ${join(outputPath, "kesha-support-bundle.tar.gz")}.`,
+    });
+  }
+  const why = PATH_ERRNOS[errno];
+  if (why) {
+    return new KeshaError("E_INVALID_ARG", `Cannot write the support bundle to ${outputPath}: ${why} (${errno})`, {
+      hint: `pass --output a path in a directory you can write to.`,
+    });
+  }
+  if (!errno) return e;
+  if (errno === "ENOSPC") {
+    return new KeshaError("E_INTERNAL", `Cannot write the support bundle to ${outputPath}: no space left on its disk (ENOSPC)`, {
+      hint: `the disk is full: free space on the volume that holds ${dir}, or pass --output a path on another disk.`,
+    });
+  }
+  return new KeshaError("E_INTERNAL", `Cannot write the support bundle to ${outputPath}: ${errorMessage(e)}`, {
+    hint: `resolve that filesystem error on ${dir}, or pass --output a path elsewhere.`,
+  });
+}
+
 export async function createSupportBundle(
   options: SupportBundleOptions = {},
 ): Promise<SupportBundleResult> {
@@ -180,16 +243,17 @@ export async function createSupportBundle(
     );
   }
 
-  mkdirSync(dirname(outputPath), { recursive: true });
-  writeFileSync(outputPath, gzipSync(createTarArchive(files)));
-
-  if (!existsSync(outputPath)) {
-    throw new Error(`failed to create support bundle: ${outputPath}`);
+  const archive = gzipSync(createTarArchive(files));
+  try {
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, archive);
+  } catch (e) {
+    throw bundleWriteFailure(outputPath, e);
   }
 
   return {
     path: outputPath,
-    sizeBytes: statSync(outputPath).size,
+    sizeBytes: archive.byteLength,
     entries: files.map((file) => file.name),
   };
 }