perf: finish the optimization batch — pipeline, network, diff and startup

hermes-base
- a bundleHash mismatch of the entry read over Range is final
  (BundleHashMismatchError): no fallback to the whole archive, no retry;
  the server lookup is retried once, downloads only on transport errors
- cache hits for records without a bytecodeVersion (legacy / native
  package) verify the HBC header; cacheLookup hashes the file streamed
- downloads get a 30 s headers timeout and a 60 s idle timeout; stale
  cachePut staging files (<hash>.<pid>.tmp) are evicted and cleaned

bundle-runner / bundle
- hermes-base-error.log is written next to the intermediate dir instead
  of inside it (it was packed into the ppk)
- the base selection starts after Metro is spawned; its synchronous head
  (hermesc lookup, HBC probe) no longer delays Metro
- the JS bundle is renamed into a work dir and both hermesc runs read it
  there (no copies); the packager map is renamed, not copied
- compose-source-maps runs asynchronously and speculatively during the
  disassembly compare, redone from the plain map if the base is rejected
- one compilePlain helper (runProcess) replaces three spawnSync sites;
  the base attempt passes -w and its stderr is bounded (512 KB head+tail)
- a failed plain compile is reported as such (hermesBasePlainCompileFailed)
  and keeps the base instead of dropping it and compiling a third time
- the compile phase waits at most 60 s (PUSHY_HERMES_BASE_WAIT_MS) for a
  base still being fetched, then compiles plain
- new --resetCache option (default true); false reuses Metro's cache

diff / hbcTransform
- moved-file matching keys on crc32 + uncompressed size (a colliding
  crc could ship the wrong file); manifest format unchanged
- a failing diff destroys the output stream and removes the partial patch
- the streaming diff transforms HBC on disk section by section
  (transformHbcFile); no full bundle copy is held in memory any more

zip-range / zip-entries
- chunk cache merges only on strict overlap, single-chunk entries are
  returned as views (entry memory 3x -> 1x); hinted reads no longer
  re-fetch cached bytes or widen tiny entries to 64 KB
- later Range requests send If-Range and check the Content-Range total;
  the central directory is always prefetched in one request
- every fetch has a timeout (RangeOptions); nested .hap temp dirs are
  removed on failure too

startup / upload / packing
- the npm version check no longer blocks every command: 1-day cache with
  stale fallback, unref'd background request, hints printed after the
  command (`help`: ~0.5 s -> ~0.09 s)
- getBaseUrl and dep versions resolve lazily; tty-table, app-info-parser,
  form-data and progress load on first use
- payload deflate level 9 -> 6 (4x less CPU for 0.6% size)
- uploads get a size-scaled timeout and one retry on transient errors;
  publish overlaps the upload with hashing and git; choosePackage reuses
  the fetched list; native package upload passes the known bundle hash

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: sunnylqm

OPTIMIZATION-PROGRESS.md

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import { doDelete, get, post } from './api';
 import type { Platform } from './types';
-import { question } from './utils';
+import { loadTtyTable, question } from './utils';
 import { t } from './utils/i18n';
 
 interface AppSummary {
@@ -70,7 +70,7 @@ export async function listApp(platform: Platform | '' = '') {
   }
 
   // tty-table is ~25 ms to load; only pay for it when a table is rendered
-  const Table = require('tty-table') as typeof import('tty-table');
+  const Table = loadTtyTable();
   console.log(Table(header, rows).render());
 
   console.log(`\n${t('totalApps', { count: list.length, platform })}`);

src/app.ts

@@ -90,6 +90,9 @@ async function run() {
     } else if (commandHandlers[argv.command]) {
       const handler = commandHandlers[argv.command];
       await handler(argv);
+      // a check still in flight (cold cache) gets a short grace period; the
+      // registry request itself is unref'd, so exiting never waits on it
+      await versionCheck.settle(500);
       versionCheck.printHints();
     } else {
       throw new Error(t('unknownCommand', { command: argv.command }));

src/bin.ts

@@ -10,6 +10,7 @@ import {
   getApkInfo,
   getAppInfo,
   getIpaInfo,
+  loadTtyTable,
   question,
 } from './utils';
 import { getDepVersions } from './utils/dep-versions';
@@ -241,7 +242,7 @@ export async function listPackage(appId: string, packages?: Package[]) {
   }
 
   // tty-table is ~25 ms to load; only pay for it when a table is rendered
-  const Table = require('tty-table') as typeof import('tty-table');
+  const Table = loadTtyTable();
   console.log(Table(header, rows).render());
   console.log(t('totalPackages', { count: allPkgs.length }));
   return allPkgs;

src/package.ts

@@ -20,6 +20,15 @@ function createAppInfoParser(fn: string): AppInfoParserType {
   return new AppInfoParser(fn);
 }
 
+/**
+ * tty-table (~25 ms to load) only when a table is rendered. Bun's require of
+ * a CJS module can hand back a namespace object, so unwrap `default`.
+ */
+export function loadTtyTable(): typeof import('tty-table') {
+  const mod = require('tty-table');
+  return (mod.default ?? mod) as typeof import('tty-table');
+}
+
 type ApkMetaEntry = {
   name?: string;
   value?: string | number | Array<string | number>;
@@ -549,6 +558,8 @@ function latestTag(version: string | undefined) {
 export interface VersionCheck {
   /** settles once the registry check has finished (or failed); never rejects */
   done: Promise<void>;
+  /** wait for the check, but never longer than `graceMs` */
+  settle: (graceMs: number) => Promise<void>;
   /**
    * Print the "newer version available" hints if the check has completed by
    * now; a no-op while it is still pending, when nothing is newer, and after
@@ -635,7 +646,15 @@ export async function printVersionCommand({
     }
   };
 
-  return { done: check, printHints };
+  const settle = (graceMs: number) => {
+    let timer: NodeJS.Timeout | undefined;
+    const grace = new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, graceMs);
+    });
+    return Promise.race([check, grace]).then(() => clearTimeout(timer));
+  };
+
+  return { done: check, settle, printHints };
 }
 
 export { checkPlugins };

src/utils/index.ts

@@ -4,7 +4,7 @@ import { doDelete, get, getAllPackages, post, put, uploadFile } from './api';
 import { getPlatform, getSelectedApp } from './app';
 import { choosePackage } from './package';
 import type { Package, Platform, Version } from './types';
-import { isNonInteractive, question } from './utils';
+import { isNonInteractive, loadTtyTable, question } from './utils';
 import { getDepVersions } from './utils/dep-versions';
 import { getCommitInfo } from './utils/git';
 import { getHbcVersion } from './utils/hbcTransform';
@@ -234,7 +234,7 @@ function printDepsChangesForPackage({
   );
   console.log(summaryText);
   // tty-table is ~25 ms to load; only pay for it when a table is rendered
-  const Table = require('tty-table') as typeof import('tty-table');
+  const Table = loadTtyTable();
   console.log(Table(header, rows).render());
   console.log(chalk.yellow(t('depsChangeRiskWarning')));
   return true;