@dhruv2mars/mdv 0.0.13 → 0.0.14

package/README.md

@@ -10,6 +10,7 @@ npm i -g @dhruv2mars/mdv
 
 First run downloads native `mdv` binary.
 Assets are resolved from GitHub Releases for your platform/arch.
+Installer keeps verified cache under `~/.mdv/cache`.
 
 ## Usage
 
@@ -17,6 +18,12 @@ Assets are resolved from GitHub Releases for your platform/arch.
 mdv README.md
 ```
 
+Manual upgrade:
+
+```bash
+mdv update
+```
+
 Stream stdin:
 
 ```bash
@@ -37,3 +44,9 @@ tail -f notes.md | mdv --stream
 - `--no-watch` disable file watch
 - `--stream` read markdown from stdin
 - `--perf` show perf stats
+
+## Installer Env
+
+- `MDV_INSTALL_DEBUG=1` local installer debug logs
+- `MDV_INSTALL_TIMEOUT_MS` request timeout (default `15000`)
+- `MDV_INSTALL_RETRY_ATTEMPTS` retries (default `3`)

package/bin/install-lib.js

@@ -1,3 +1,5 @@
+import { join } from 'node:path';
+
 export function assetNameFor(platform = process.platform, arch = process.arch) {
   const ext = platform === 'win32' ? '.exe' : '';
   return `mdv-${platform}-${arch}${ext}`;
@@ -14,6 +16,49 @@ export function checksumsAssetNameFromBinaryAsset(asset) {
   return checksumsAssetNameFor(m[1], m[2]);
 }
 
+function parseIntEnv(value, fallback, min, max) {
+  const parsed = Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isFinite(parsed)) return fallback;
+  if (parsed < min) return min;
+  if (parsed > max) return max;
+  return parsed;
+}
+
+export function installTuningFromEnv(env = process.env) {
+  return {
+    retryAttempts: parseIntEnv(env.MDV_INSTALL_RETRY_ATTEMPTS, 3, 1, 10),
+    timeoutMs: parseIntEnv(env.MDV_INSTALL_TIMEOUT_MS, 15000, 1000, 120000),
+    backoffMs: parseIntEnv(env.MDV_INSTALL_BACKOFF_MS, 250, 50, 5000),
+    backoffJitterMs: parseIntEnv(env.MDV_INSTALL_BACKOFF_JITTER_MS, 100, 0, 2000)
+  };
+}
+
+export function computeBackoffDelay(attempt, backoffMs, backoffJitterMs, rand = Math.random) {
+  const scaled = Math.max(1, attempt) * Math.max(0, backoffMs);
+  if (backoffJitterMs <= 0) return scaled;
+  const jitter = Math.floor(Math.max(0, rand()) * (backoffJitterMs + 1));
+  return scaled + jitter;
+}
+
+export function cachePathsFor(installRoot, version, asset, checksumsAsset) {
+  const root = join(installRoot, 'cache', `v${version}`);
+  return {
+    cacheDir: root,
+    cacheBinary: join(root, asset),
+    cacheChecksums: join(root, checksumsAsset)
+  };
+}
+
+export function buildChecksumMismatchHelp({ asset, expected, actual, cachePath }) {
+  const shortExpected = String(expected || '').slice(0, 12);
+  const shortActual = String(actual || '').slice(0, 12);
+  return [
+    `checksum mismatch for ${asset}`,
+    `expected=${shortExpected}... actual=${shortActual}...`,
+    `clear cache and retry: rm -rf ${cachePath}`
+  ].join('; ');
+}
+
 export function findAssetUrl(release, asset) {
   if (!release || !Array.isArray(release.assets)) return null;
   for (const item of release.assets) {

package/bin/install.js

@@ -8,7 +8,8 @@ import {
   mkdirSync,
   readFileSync,
   rmSync,
-  renameSync
+  renameSync,
+  writeFileSync
 } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
@@ -18,7 +19,11 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import {
   assetNameFor,
+  buildChecksumMismatchHelp,
+  cachePathsFor,
   checksumsAssetNameFor,
+  computeBackoffDelay,
+  installTuningFromEnv,
   parseChecksumForAsset,
   resolveReleaseAssetBundle,
   shouldUseFallbackUrl
@@ -30,9 +35,13 @@ const installRoot = process.env.MDV_INSTALL_ROOT || join(homedir(), '.mdv');
 const binDir = join(installRoot, 'bin');
 const binName = process.platform === 'win32' ? 'mdv.exe' : 'mdv';
 const dest = join(binDir, binName);
-const retryAttempts = Number(process.env.MDV_INSTALL_RETRY_ATTEMPTS || 3);
-const timeoutMs = Number(process.env.MDV_INSTALL_TIMEOUT_MS || 15000);
-const backoffMs = Number(process.env.MDV_INSTALL_BACKOFF_MS || 250);
+const tuning = installTuningFromEnv(process.env);
+const retryAttempts = tuning.retryAttempts;
+const timeoutMs = tuning.timeoutMs;
+const backoffMs = tuning.backoffMs;
+const backoffJitterMs = tuning.backoffJitterMs;
+const debugEnabled = process.env.MDV_INSTALL_DEBUG === '1';
+const installStartedAt = Date.now();
 
 if (process.env.MDV_SKIP_DOWNLOAD === '1') process.exit(0);
 if (existsSync(dest)) process.exit(0);
@@ -42,26 +51,47 @@ mkdirSync(binDir, { recursive: true });
 const version = pkgVersion();
 const asset = assetNameFor();
 const checksumsAsset = checksumsAssetNameFor();
+const cachePaths = cachePathsFor(installRoot, version, asset, checksumsAsset);
 const url = `https://github.com/${REPO}/releases/download/v${version}/${asset}`;
 const checksumsUrl = `https://github.com/${REPO}/releases/download/v${version}/${checksumsAsset}`;
 const tmp = `${dest}.tmp-${Date.now()}`;
+mkdirSync(cachePaths.cacheDir, { recursive: true });
 
 try {
+  trace(`start retry=${retryAttempts} timeout=${timeoutMs}ms backoff=${backoffMs}ms jitter=${backoffJitterMs}ms`);
   console.error(`mdv: download ${asset} v${version}`);
-  await downloadWithFallback(
-    { binaryUrl: url, checksumsUrl },
-    version,
-    asset,
-    checksumsAsset,
-    tmp
-  );
+  let checksumsText = null;
+  const restoredFromCache = await installFromCache(cachePaths, asset, tmp);
+  if (restoredFromCache) {
+    trace('cache-hit');
+  } else {
+    trace('cache-miss');
+    const result = await downloadWithFallback(
+      { binaryUrl: url, checksumsUrl },
+      version,
+      asset,
+      checksumsAsset,
+      tmp
+    );
+    if (result.source === 'primary') {
+      checksumsText = result.checksumsText;
+    }
+  }
   if (process.platform !== 'win32') chmodSync(tmp, 0o755);
   renameSync(tmp, dest);
+  if (checksumsText) {
+    persistCache(cachePaths, checksumsText, dest);
+    trace('cache-store');
+  }
+  trace('success');
   process.exit(0);
 } catch (err) {
   try { rmSync(tmp, { force: true }); } catch {}
-
-  console.error(`mdv: download failed (${String(err)})`);
+  if (err && err.code === 'MDV_CHECKSUM_MISMATCH') {
+    console.error(`mdv: ${err.message}`);
+  } else {
+    console.error(`mdv: download failed (${String(err)})`);
+  }
 
   if (process.env.MDV_ALLOW_CARGO_FALLBACK === '1') {
     if (cargoInstallFallback()) {
@@ -170,7 +200,7 @@ async function withRetry(label, fn) {
     } catch (err) {
       lastErr = err;
       if (attempt >= retryAttempts) break;
-      await sleep(backoffMs * attempt);
+      await sleep(computeBackoffDelay(attempt, backoffMs, backoffJitterMs));
       console.error(`mdv: retry ${label} (${attempt + 1}/${retryAttempts})`);
     }
   }
@@ -201,14 +231,15 @@ async function downloadAndVerify({ binaryUrl, checksumsUrl }, asset, outPath) {
 
   const actual = await sha256File(outPath);
   if (actual !== expected) {
-    throw new Error(`checksum mismatch for ${asset}`);
+    throw checksumMismatchError(asset, expected, actual);
   }
+  return { checksumsText };
 }
 
 async function downloadWithFallback(primary, version, asset, checksumsAsset, outPath) {
   try {
-    await downloadAndVerify(primary, asset, outPath);
-    return;
+    const primaryVerified = await downloadAndVerify(primary, asset, outPath);
+    return { ...primaryVerified, source: 'primary' };
   } catch (primaryErr) {
     const fallback = await resolveReleaseAssetBundle({
       version,
@@ -222,7 +253,8 @@ async function downloadWithFallback(primary, version, asset, checksumsAsset, out
     }
 
     console.error(`mdv: fallback download ${fallback.binaryUrl}`);
-    await downloadAndVerify(fallback, asset, outPath);
+    const fallbackVerified = await downloadAndVerify(fallback, asset, outPath);
+    return { ...fallbackVerified, source: 'fallback' };
   }
 }
 
@@ -270,6 +302,60 @@ function requestJson(url) {
   });
 }
 
+function trace(msg) {
+  if (!debugEnabled) return;
+  const elapsed = Date.now() - installStartedAt;
+  console.error(`mdv:debug +${elapsed}ms ${msg}`);
+}
+
+async function installFromCache(paths, asset, outPath) {
+  if (!existsSync(paths.cacheBinary) || !existsSync(paths.cacheChecksums)) {
+    return false;
+  }
+
+  try {
+    const checksumsText = readFileSync(paths.cacheChecksums, 'utf8');
+    const expected = parseChecksumForAsset(checksumsText, asset);
+    if (!expected) {
+      trace('cache-invalid-missing-checksum-entry');
+      return false;
+    }
+    const actual = await sha256File(paths.cacheBinary);
+    if (actual !== expected) {
+      trace('cache-invalid-checksum-mismatch');
+      try { rmSync(paths.cacheBinary, { force: true }); } catch {}
+      try { rmSync(paths.cacheChecksums, { force: true }); } catch {}
+      return false;
+    }
+    copyFileSync(paths.cacheBinary, outPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function persistCache(paths, checksumsText, sourceBinaryPath) {
+  try {
+    copyFileSync(sourceBinaryPath, paths.cacheBinary);
+    writeFileSync(paths.cacheChecksums, checksumsText, 'utf8');
+  } catch {
+    trace('cache-store-failed');
+  }
+}
+
+function checksumMismatchError(asset, expected, actual) {
+  const err = new Error(
+    buildChecksumMismatchHelp({
+      asset,
+      expected,
+      actual,
+      cachePath: cachePaths.cacheDir
+    })
+  );
+  err.code = 'MDV_CHECKSUM_MISMATCH';
+  return err;
+}
+
 function cargoInstallFallback() {
   const probe = spawnSync('cargo', ['--version'], { stdio: 'ignore' });
   if (probe.status !== 0) return false;

package/bin/mdv-lib.js

@@ -0,0 +1,37 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const PACKAGE_NAME = '@dhruv2mars/mdv@latest';
+
+export function binNameForPlatform(platform = process.platform) {
+  return platform === 'win32' ? 'mdv.exe' : 'mdv';
+}
+
+export function resolveInstallRoot(env = process.env, home = homedir()) {
+  return env.MDV_INSTALL_ROOT || join(home, '.mdv');
+}
+
+export function resolveInstalledBin(env = process.env, platform = process.platform, home = homedir()) {
+  const installRoot = resolveInstallRoot(env, home);
+  const binName = binNameForPlatform(platform);
+  return join(installRoot, 'bin', binName);
+}
+
+export function shouldRunUpdateCommand(args) {
+  return Array.isArray(args) && args.length > 0 && args[0] === 'update';
+}
+
+export function resolveUpdateCommand(env = process.env) {
+  const npmExecPath = env.npm_execpath;
+  if (typeof npmExecPath === 'string' && npmExecPath.endsWith('.js')) {
+    return {
+      command: process.execPath,
+      args: [npmExecPath, 'install', '-g', PACKAGE_NAME]
+    };
+  }
+
+  return {
+    command: 'npm',
+    args: ['install', '-g', PACKAGE_NAME]
+  };
+}

package/bin/mdv.js

@@ -1,18 +1,25 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import {
+  resolveInstalledBin,
+  resolveUpdateCommand,
+  shouldRunUpdateCommand
+} from './mdv-lib.js';
 
 const args = process.argv.slice(2);
 
+if (shouldRunUpdateCommand(args)) {
+  const update = resolveUpdateCommand(process.env);
+  const res = spawnSync(update.command, update.args, { stdio: 'inherit', env: process.env });
+  process.exit(res.status ?? 1);
+}
+
 const envBin = process.env.MDV_BIN;
 if (envBin) run(envBin, args);
 
-const installRoot = process.env.MDV_INSTALL_ROOT || join(homedir(), '.mdv');
-const binName = process.platform === 'win32' ? 'mdv.exe' : 'mdv';
-const installedBin = join(installRoot, 'bin', binName);
+const installedBin = resolveInstalledBin(process.env, process.platform);
 
 if (!existsSync(installedBin)) {
   const here = fileURLToPath(new URL('.', import.meta.url));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhruv2mars/mdv",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Terminal-first markdown visualizer/editor",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "mdv": "node bin/mdv.js",
     "postinstall": "node bin/install.js",
     "selftest": "node bin/selftest.js",
-    "lint": "node --check bin/mdv.js && node --check bin/install.js && node --check bin/install-lib.js && node --check bin/selftest.js",
+    "lint": "node --check bin/mdv.js && node --check bin/mdv-lib.js && node --check bin/install.js && node --check bin/install-lib.js && node --check bin/selftest.js",
     "test": "node scripts/test.js",
     "coverage": "c8 --all --include bin/install-lib.js --reporter text-summary --check-coverage --lines 95 --functions 95 --branches 80 --statements 95 node scripts/test.js"
   },