amxx-builder 1.6.0 → 1.7.0

package/src/commands/watch.js

@@ -11,7 +11,8 @@ const { deployBuild, deployPlugin, deployFile, removeDeployedFile } = require('.
 const { sendRconForPlugins } = require('../rcon');
 const { DepGraph }           = require('../dep-graph');
 const { startWatch }         = require('../watcher');
-const { fetchRepo, resolveRepoRefs } = require('../repo-fetcher');
+const { resolveRepoRefs } = require('../repo-fetcher');
+const { ensureRepoDir }   = require('../local-sources');
 const { resolveDeps, repoKey } = require('../deps-resolver');
 const { resolveManifestPath, loadEnv } = require('./shared');
 const { runBuild } = require('./build');
@@ -20,6 +21,13 @@ const { subscribeCompiledRendering } = require('./compile-renderer');
 // Render compiler 'compiled' events (previously direct stdout/stderr writes).
 subscribeCompiledRendering();
 
+// Watch never regenerates INI files, so applyPluginRule is only used as a skip
+// check here; the base only has to be a valid defaults layer.
+function pluginRuleBase(manifest) {
+  const { defaultIni, defaultDebug } = manifest.pluginIni;
+  return { ini: defaultIni, debug: defaultDebug === true };
+}
+
 async function runWatch(options) {
   const manifestPath = resolveManifestPath(options.manifest);
   const buildDir     = path.resolve(options.buildDir || './build');
@@ -52,8 +60,14 @@ async function runWatch(options) {
       for (const repoConfig of manifest.repos) {
         const key = repoKey(repoConfig);
         if (!cloneJobs.has(key)) {
+          // Cache-only, like before; ensureRepoDir returns `_localDir` for
+          // local entries (no network, no noFetch check).
           cloneJobs.set(key,
-            fetchRepo(repoConfig.repo, repoConfig._resolvedRef, resolveGithubToken(manifest, repoConfig.repo), true, manifest.github.ssh)
+            ensureRepoDir(repoConfig, {
+              token: resolveGithubToken(manifest, repoConfig.repo),
+              noFetch: true,
+              ssh: manifest.github.ssh,
+            })
           );
         }
       }
@@ -95,20 +109,56 @@ async function runWatch(options) {
     await deployBuild(state.manifest, buildDir, { incremental: true });
   }
 
-  // Serialize incremental work; full rebuilds flush the queue before wiping build/.
+  // Serialize all incremental work through a single promise chain so no two
+  // tasks ever touch build/ at the same time.
   let queue = Promise.resolve();
   const enqueue = (fn) => {
     queue = queue.then(() => fn()).catch((err) => logger.error(`Watch task error: ${err.message}`));
     return queue;
   };
-  const flushQueue = () => queue.catch(() => {});
+
+  // Full rebuilds (manifest change) run on the same chain. Coalescing: a second
+  // manifest save while a rebuild is queued/running only marks a re-run instead
+  // of starting a second concurrent rebuild over the same build/.
+  let rebuildQueued = false;
+  let rebuildAgain  = false;
+
+  async function performRebuild() {
+    logger.info('Rebuilding...');
+    await runBuild({ manifest: manifestPath, buildDir: options.buildDir });
+    state = await buildWatchState();
+    if (doDeploy && state.manifest.deploy.path) {
+      await deployBuild(state.manifest, buildDir, { incremental: true });
+      const pluginNames = gatherPluginNames(buildDir);
+      await sendRconForPlugins(state.manifest.deploy, pluginNames);
+    }
+    logger.warn('Note: if new watch paths were added, restart amxb watch to pick them up');
+  }
+
+  function scheduleRebuild() {
+    if (rebuildQueued) {
+      rebuildAgain = true;
+      return;
+    }
+    rebuildQueued = true;
+    return enqueue(async () => {
+      try {
+        do {
+          rebuildAgain = false;
+          await performRebuild();
+        } while (rebuildAgain);
+      } finally {
+        rebuildQueued = false;
+      }
+    });
+  }
 
   const handlers = {
     onSmaChange(smaPath) {
       return enqueue(async () => {
         state.depGraph.update(smaPath);
         const smaRel = path.relative(state.scriptingRootDir, smaPath).split(path.sep).join('/');
-        const pluginRule = applyPluginRule(smaRel, state.manifest.pluginRules, state.manifest.globalPostfix);
+        const pluginRule = applyPluginRule(smaRel, state.manifest.plugins.rules, pluginRuleBase(state.manifest));
         if (!pluginRule) {
           logger.dim(`  Skipped by plugin rule: ${smaRel}`);
           return;
@@ -127,6 +177,11 @@ async function runWatch(options) {
       return enqueue(async () => {
         state.depGraph.update(incPath);
         const affected = state.depGraph.getSmasDependingOn(incPath);
+        // A newly-added .inc can satisfy includes that were previously missing
+        // (e.g. a plugin saved with #include <newlib> before newlib.inc existed).
+        for (const smaPath of state.depGraph.reattachMissingIncludes(incPath)) {
+          affected.add(smaPath);
+        }
 
         if (affected.size === 0) {
           logger.dim(`  No plugins depend on ${path.relative(state.manifestDir, incPath)}, skipping`);
@@ -137,7 +192,7 @@ async function runWatch(options) {
           const compiled = [];
           for (const smaPath of affected) {
             const smaRel = path.relative(state.scriptingRootDir, smaPath).split(path.sep).join('/');
-            const pluginRule = applyPluginRule(smaRel, state.manifest.pluginRules, state.manifest.globalPostfix);
+            const pluginRule = applyPluginRule(smaRel, state.manifest.plugins.rules, pluginRuleBase(state.manifest));
             if (!pluginRule) {
               logger.dim(`  Skipped by plugin rule: ${smaRel}`);
               continue;
@@ -162,7 +217,10 @@ async function runWatch(options) {
     onFileChange(relPath, section) {
       return enqueue(() => {
         if (doDeploy && state.manifest.deploy.path) {
-          deployFile(state.manifest, buildDir, relPath, section);
+          const srcRoot = section === 'assets'
+            ? path.join(state.manifestDir, 'assets')
+            : path.join(state.manifestDir, state.manifest.amxmodx.dir);
+          deployFile(state.manifest, buildDir, relPath, section, srcRoot);
         }
       });
     },
@@ -176,22 +234,7 @@ async function runWatch(options) {
     },
 
     onManifestChange() {
-      return (async () => {
-        try {
-          await flushQueue(); // let in-flight compiles finish before build/ is wiped
-          logger.info('Rebuilding...');
-          await runBuild({ manifest: manifestPath, buildDir: options.buildDir });
-          state = await buildWatchState();
-          if (doDeploy && state.manifest.deploy.path) {
-            await deployBuild(state.manifest, buildDir, { incremental: true });
-            const pluginNames = gatherPluginNames(buildDir);
-            await sendRconForPlugins(state.manifest.deploy, pluginNames);
-          }
-          logger.warn('Note: if new watch paths were added, restart amxb watch to pick them up');
-        } catch (err) {
-          logger.error(err.message);
-        }
-      })();
+      return scheduleRebuild();
     },
   };
 

package/src/compile-utils.js

@@ -4,11 +4,113 @@ const fs   = require('fs');
 const path = require('path');
 const { execFile } = require('child_process');
 
+// ─── WSL DrvFs/9p input guard ────────────────────────────────────────────────
+//
+// amxxpc is a 32-bit Linux binary that cannot READ files on WSL DrvFs/9p mounts
+// (/mnt/c, /mnt/d, /mnt/j, …). A source or include dir there makes it fail with
+// "fatal error 100: cannot read from file" (a directory used as -i aborts it
+// with std::bad_alloc), even though the file exists and Node reads it fine.
+// Writing output to such a mount works. Catch this up-front and hand back an
+// actionable message instead of the cryptic compiler output.
+
+let _isWsl;
+let _mountpoints = null;
+
+function isWsl() {
+  if (_isWsl !== undefined) return _isWsl;
+  _isWsl = false;
+  if (process.platform === 'linux') {
+    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) {
+      _isWsl = true;
+    } else {
+      try {
+        _isWsl = /microsoft|wsl/i.test(fs.readFileSync('/proc/version', 'utf8'));
+      } catch (_) { /* no /proc/version — assume not WSL */ }
+    }
+  }
+  return _isWsl;
+}
+
+// "/proc/mounts" text → mountpoints whose fstype is 9p (WSL DrvFs).
+// Mountpoints escape spaces/tabs/backslashes as \040 / \011 / \134.
+function parse9pMountpoints(mountsText) {
+  const out = [];
+  for (const line of String(mountsText).split('\n')) {
+    const parts = line.split(/\s+/);
+    if (parts.length >= 4 && parts[2] === '9p') {
+      out.push(parts[1].replace(/\\([0-7]{3})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8))));
+    }
+  }
+  return out;
+}
+
+function get9pMountpoints() {
+  if (_mountpoints) return _mountpoints;
+  _mountpoints = [];
+  if (process.platform === 'linux') {
+    try { _mountpoints = parse9pMountpoints(fs.readFileSync('/proc/mounts', 'utf8')); }
+    catch (_) { /* no /proc/mounts — nothing to guard */ }
+  }
+  return _mountpoints;
+}
+
+// Compiler argv → the paths amxxpc must READ (source + `-i` include dirs).
+// `-o` output paths are ignored — writing to a 9p mount works.
+function collectCompilerInputs(args) {
+  const inputs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-i') { if (args[i + 1]) inputs.push(args[++i]); continue; }
+    if (arg.startsWith('-i')) { inputs.push(arg.slice(2)); continue; }
+    if (arg === '-o') { i++; continue; }
+    if (arg.startsWith('-o')) continue;
+    if (i === 0 && !arg.startsWith('-')) inputs.push(arg); // source is argv[0]
+  }
+  return inputs.filter(Boolean);
+}
+
+function isUnder(p, dir) {
+  const abs = path.resolve(p);
+  if (abs === dir) return true;
+  return abs.startsWith(dir.endsWith('/') ? dir : dir + '/');
+}
+
+function findNonNativeInputs(args, mountpoints) {
+  return collectCompilerInputs(args).filter((p) => mountpoints.some((mp) => isUnder(p, mp)));
+}
+
+function nonNativeInputError(inputs) {
+  return [
+    'amxxpc cannot read files on WSL DrvFs/9p mounts (/mnt/*).',
+    'Unreadable input(s):',
+    ...inputs.map((p) => `  ${p}`),
+    'The compiler is a 32-bit Linux binary; on these mounts it fails with',
+    '"fatal error 100: cannot read from file" (an include directory aborts it with',
+    'std::bad_alloc), although the file exists and Node can read it.',
+    'Run the build from the Linux-native filesystem instead — copy the project to',
+    'e.g. ~/ (the ~/.cache/amxx-builder cache is shared, nothing re-downloads), or',
+    'run the build on Windows.',
+  ].join('\n');
+}
+
+/**
+ * Preflight for a compiler invocation. On WSL, when the source or any `-i`
+ * include dir sits on a DrvFs/9p mount, `ok` is false and `error` is a
+ * ready-to-print explanation. `wsl`/`mountpoints` are injectable for tests.
+ */
+function checkCompilerInputs(args, { wsl = isWsl(), mountpoints = get9pMountpoints() } = {}) {
+  if (!wsl || !mountpoints.length) return { ok: true, inputs: [], error: null };
+  const inputs = findNonNativeInputs(args, mountpoints);
+  if (!inputs.length) return { ok: true, inputs: [], error: null };
+  return { ok: false, inputs, error: nonNativeInputError(inputs) };
+}
+
 /**
  * Unified compiler spawn. Interface-agnostic core helper (used by the CLI build,
  * watch mode and the MCP compile tool).
  *
  * ALWAYS resolves — never rejects:
+ *  - WSL + input on a DrvFs/9p mount (/mnt/*): { status: 1, output: <explanation> }
  *  - on spawn error (ENOENT etc.): { status: 1, output: String(err.message) }
  *  - on close (including non-zero exit): { status: code, output: stdout+stderr merged }
  *
@@ -16,7 +118,11 @@ const { execFile } = require('child_process');
  * amxxpc needs its bundled libs). windowsHide: true keeps a console from
  * flashing on Windows.
  */
-function spawnCompiler(cmd, args, { maxBuffer = 10 * 1024 * 1024 } = {}) {
+function spawnCompiler(cmd, args, { maxBuffer = 10 * 1024 * 1024, ...guardOptions } = {}) {
+  const guard = checkCompilerInputs(args, guardOptions);
+  if (!guard.ok) {
+    return Promise.resolve({ status: 1, output: guard.error });
+  }
   return new Promise((resolve) => {
     const env = { ...process.env };
     if (process.platform === 'linux') {
@@ -57,9 +163,18 @@ function buildIncludeArgs({ scriptingDir, localIncDir, collectedIncDir, includeD
   return includes;
 }
 
-/** Turns manifest defines (e.g. ['DEBUG']) into `-DDEBUG` compiler flags. */
+/**
+ * Turns manifest defines (e.g. ['DEBUG', 'VERSION=2']) into amxxpc CLI args.
+ *
+ * amxxpc (Pawn compiler fork) does NOT accept `-D<name>` defines: on Linux the
+ * -D flag is compiled out (dead dos_setdrive code) and rejected; on Windows it
+ * is silently treated as chdir. Its only CLI define syntax is a bare
+ * `sym=val` argument (sc1.c parseoptions). A value-less flag is therefore
+ * normalized to `NAME=1` (semantics of `-DNAME` elsewhere: `#if NAME` and
+ * `#if defined NAME` both see it enabled).
+ */
 function buildDefineArgs(defines) {
-  return (defines || []).map((d) => `-D${d}`);
+  return (defines || []).map((d) => (d.includes('=') ? d : `${d}=1`));
 }
 
-module.exports = { spawnCompiler, buildIncludeArgs, buildDefineArgs };
+module.exports = { spawnCompiler, buildIncludeArgs, buildDefineArgs, checkCompilerInputs, parse9pMountpoints };

package/src/compiler-fetcher.js

@@ -7,8 +7,8 @@ const AdmZip = require('adm-zip');
 const chalk = require('chalk');
 const logger = require('./logger');
 const { getCacheDir } = require('./cache-dir');
-const { copyDirContents, safeExtractTar } = require('./fs-utils');
-const { withRetry } = require('./retry');
+const { copyDirContents, safeExtractTar, makeSiblingTmpDir } = require('./fs-utils');
+const { downloadToFile } = require('./download');
 
 const AMXX_DROP = 'https://www.amxmodx.org/amxxdrop/';
 
@@ -31,8 +31,15 @@ async function fetchCompiler(version, options = {}) {
   const binaryName      = platform === 'windows' ? 'amxxpc.exe' : 'amxxpc';
   const binaryPath      = path.join(cacheDir, binaryName);
   const includeDir      = path.join(cacheDir, 'include');
+  const completeFile    = path.join(cacheDir, '.complete');
 
   if (fs.existsSync(binaryPath)) {
+    // Backfill the completion marker on legacy (pre-`.complete`) caches so an
+    // interrupted extraction is detectable going forward; a fresh install only
+    // gains the marker after a successful atomic extract.
+    if (!fs.existsSync(completeFile)) {
+      try { writeFileSyncAtomic(completeFile, resolvedVersion); } catch (_) {}
+    }
     logger.info(`Compiler: amxxpc ${resolvedVersion} (${process.platform}, cached)`);
     return { compilerPath: binaryPath, includeDir: fs.existsSync(includeDir) ? includeDir : null };
   }
@@ -43,15 +50,20 @@ async function fetchCompiler(version, options = {}) {
   logger.step(`Compiler: downloading amxxpc ${resolvedVersion} for ${platform}...`);
   logger.dim(`  ${downloadUrl}`);
 
-  fs.mkdirSync(cacheDir, { recursive: true });
-  const archivePath = path.join(cacheDir, path.basename(downloadUrl));
-
-  await downloadFile(downloadUrl, archivePath);
-  extractWithPrefix(archivePath, cacheDir, {
-    prefix: 'addons/amxmodx/scripting/',
-    onDone: (d) => makeBinaryExecutable(d, platform),
+  await installCompilerCache(cacheDir, {
+    isFinalValid: () => fs.existsSync(binaryPath) && fs.existsSync(completeFile),
+    sentinelName: '.complete',
+    sentinelContent: resolvedVersion,
+    populate: async (stagingDir) => {
+      const archivePath = path.join(stagingDir, path.basename(downloadUrl));
+      await downloadFile(downloadUrl, archivePath);
+      extractWithPrefix(archivePath, stagingDir, {
+        prefix: 'addons/amxmodx/scripting/',
+        onDone: (d) => makeBinaryExecutable(d, platform),
+      });
+      fs.rmSync(archivePath, { force: true });
+    },
   });
-  fs.rmSync(archivePath, { force: true });
 
   if (!fs.existsSync(binaryPath)) {
     throw new Error(
@@ -65,6 +77,52 @@ async function fetchCompiler(version, options = {}) {
   return { compilerPath: binaryPath, includeDir: fs.existsSync(includeDir) ? includeDir : null };
 }
 
+/**
+ * Atomic cache-write path shared by fetchCompiler (scripting/) and
+ * getAmxmodxFullDir (addons/). Stages the download+extract into a unique
+ * sibling temp dir, then:
+ *   - fresh cache dir → whole-dir rename (a kill can only orphan the temp dir,
+ *     never leave a partial cache),
+ *   - cache dir already populated (the two variants share one dir, or a
+ *     concurrent run won) → merge the staged content and write the completion
+ *     sentinel LAST, so an interrupt mid-merge cannot mark partial files valid.
+ * Cleans up its own temp dir on failure.
+ */
+async function installCompilerCache(cacheDir, { isFinalValid, sentinelName, sentinelContent, populate }) {
+  const tmpDir = makeSiblingTmpDir(cacheDir);
+  try {
+    await populate(tmpDir);
+
+    if (!fs.existsSync(cacheDir)) {
+      writeFileSyncAtomic(path.join(tmpDir, sentinelName), sentinelContent);
+      try {
+        fs.renameSync(tmpDir, cacheDir);
+        return;
+      } catch (_) {
+        // A concurrent run created cacheDir between the check and the rename.
+      }
+    }
+
+    if (isFinalValid()) {
+      try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+      return;
+    }
+
+    copyDirContents(tmpDir, cacheDir);
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+    writeFileSyncAtomic(path.join(cacheDir, sentinelName), sentinelContent);
+  } catch (err) {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+    throw err;
+  }
+}
+
+function writeFileSyncAtomic(file, content) {
+  const tmp = file + '.tmp';
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, file);
+}
+
 /**
  * Compiler info without necessarily downloading. With noFetch the report only
  * reflects what is already cached; otherwise the compiler is ensured to be
@@ -134,10 +192,12 @@ async function fetchLatestVersion(options = {}) {
   } catch (_) {} // no/invalid cache file — resolve from web
 
   if (noFetch) {
-    throw new Error(
+    const err = new Error(
       'Latest amxmodx version is not cached and no-fetch is set.\n' +
       'Run once without --no-fetch (or set amxmodx.version explicitly) to populate the cache.'
     );
+    err.code = 'LATEST_NOT_CACHED';
+    throw err;
   }
 
   if (_latestFetch) return _latestFetch;
@@ -220,11 +280,67 @@ async function resolveLatestVersionFromWeb() {
  */
 async function resolveAmxmodxVersion(manifest, options = {}) {
   const { version, noFetch } = options;
-  if (version) return version;
+  if (version) {
+    if (version === 'latest') {
+      return fetchLatestVersion({ noFetch });
+    }
+    try {
+      parseVersion(version); // validate major.minor.build shape
+    } catch (err) {
+      err.code = 'INVALID_AMXMODX_VERSION';
+      throw err;
+    }
+    return version;
+  }
   if (manifest && manifest.amxmodx && manifest.amxmodx.version) return manifest.amxmodx.version;
   return fetchLatestVersion({ noFetch });
 }
 
+/**
+ * Resolve the AMX Mod X version for an informational stdlib lookup with
+ * graceful offline degradation (noFetch). The logic previously lived inline in
+ * src/commands/serve.js (resolveVersionFromParams + resolveStdlibState) and is
+ * duplicated — without the degradation — in the MCP layer.
+ *
+ * Priority: explicit `version` → manifest `amxmodx.version` (unless the literal
+ * 'latest') → the latest release.
+ *
+ * Offline (noFetch) and latest cannot be resolved:
+ *   - nothing cached                 → { version: null, degraded: false } (graceful empty)
+ *   - a cached compiler exists       → { version: <newest cached>, degraded: true }
+ * Invalid explicit versions and other real failures are returned as `error`
+ * (with code INVALID_AMXMODX_VERSION for malformed explicit versions) rather
+ * than thrown, so each interface can shape them per its convention.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.version]      - explicit version override
+ * @param {object|null} [opts.manifest] - parsed manifest (null when absent/unparseable)
+ * @param {boolean} [opts.noFetch=false] - skip network when resolving "latest"
+ * @returns {Promise<{ version: string|null, degraded: boolean, error: Error|null }>}
+ */
+async function resolveStdlibVersion({ version = null, manifest = null, noFetch = false } = {}) {
+  let degraded = false;
+  let resolved;
+  try {
+    const manifestVersion = manifest && manifest.amxmodx && manifest.amxmodx.version;
+    if (version) {
+      resolved = await resolveAmxmodxVersion(null, { version, noFetch });
+    } else if (manifestVersion && manifestVersion !== 'latest') {
+      resolved = manifestVersion;
+    } else {
+      resolved = await resolveAmxmodxVersion(manifestVersion === 'latest' ? null : manifest, { noFetch });
+    }
+  } catch (err) {
+    if (noFetch && err && err.code === 'LATEST_NOT_CACHED') {
+      const fallback = findNewestCachedCompiler();
+      if (!fallback) return { version: null, degraded: false, error: null };
+      return { version: fallback.version, degraded: true, error: null };
+    }
+    return { version: null, degraded: false, error: err };
+  }
+  return { version: resolved, degraded, error: null };
+}
+
 function getPlatform() {
   return getHostPlatform();
 }
@@ -235,6 +351,59 @@ function getHostPlatform() {
   return 'linux';
 }
 
+/**
+ * Find the newest usable cached compiler for a platform, without downloading.
+ *
+ * Cache layout: <cache>/amxxpc/<version>/<platform>/amxxpc[.exe] (+ include/).
+ * Files directly inside amxxpc/ (e.g. .latest-version-<platform>) and any
+ * non-dotted-numeric dirs are ignored. Candidates with an include/ dir are
+ * preferred; otherwise the numerically newest version wins (longer tuple is
+ * newer when the common prefix is equal, e.g. 1.9.0.5299 > 1.9.0).
+ *
+ * @param {string} [platform=getHostPlatform()]
+ * @returns {{version: string, compilerPath: string, includeDir: string}|null}
+ */
+function findNewestCachedCompiler(platform = getHostPlatform()) {
+  const amxxpcDir = path.join(getCacheDir(), 'amxxpc');
+  if (!fs.existsSync(amxxpcDir)) return null;
+
+  const binaryName = platform === 'windows' ? 'amxxpc.exe' : 'amxxpc';
+  const candidates = [];
+
+  for (const entry of fs.readdirSync(amxxpcDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !/^\d+(\.\d+)+$/.test(entry.name)) continue;
+    const verDir      = path.join(amxxpcDir, entry.name);
+    const platformDir = path.join(verDir, platform);
+    const compilerPath = path.join(platformDir, binaryName);
+    if (!fs.existsSync(compilerPath)) continue;
+    const includeDir = path.join(platformDir, 'include');
+    candidates.push({
+      version: entry.name,
+      compilerPath,
+      includeDir,
+      hasInclude: fs.existsSync(includeDir),
+      parts: entry.name.split('.').map(Number),
+    });
+  }
+
+  if (!candidates.length) return null;
+
+  candidates.sort((a, b) => {
+    if (a.hasInclude !== b.hasInclude) return a.hasInclude ? -1 : 1;
+    const common = Math.min(a.parts.length, b.parts.length);
+    for (let i = 0; i < common; i++) {
+      if (a.parts[i] !== b.parts[i]) return b.parts[i] - a.parts[i];
+    }
+    return b.parts.length - a.parts.length; // longer tuple is newer on equal prefix
+  });
+
+  return {
+    version: candidates[0].version,
+    compilerPath: candidates[0].compilerPath,
+    includeDir: candidates[0].includeDir,
+  };
+}
+
 /**
  * Returns the path to the full amxmodx addons/ tree for the given target platform.
  * Downloads and extracts the base package if not yet cached.
@@ -256,15 +425,17 @@ async function getAmxmodxFullDir(version, platform) {
   logger.step(`Assets: downloading amxmodx ${version} (${platform}) for asset extraction...`);
   logger.dim(`  ${downloadUrl}`);
 
-  fs.mkdirSync(cacheDir, { recursive: true });
-  const archivePath = path.join(cacheDir, path.basename(downloadUrl));
-
-  await downloadFile(downloadUrl, archivePath);
-  extractWithPrefix(archivePath, cacheDir, { prefix: 'addons/', destSubdir: 'addons' });
-  fs.rmSync(archivePath, { force: true });
-  const sentinelTmp = sentinel + '.tmp';
-  fs.writeFileSync(sentinelTmp, '');
-  fs.renameSync(sentinelTmp, sentinel);
+  await installCompilerCache(cacheDir, {
+    isFinalValid: () => fs.existsSync(sentinel),
+    sentinelName: '.addons-extracted',
+    sentinelContent: '',
+    populate: async (stagingDir) => {
+      const archivePath = path.join(stagingDir, path.basename(downloadUrl));
+      await downloadFile(downloadUrl, archivePath);
+      extractWithPrefix(archivePath, stagingDir, { prefix: 'addons/', destSubdir: 'addons' });
+      fs.rmSync(archivePath, { force: true });
+    },
+  });
 
   logger.success(`Assets: amxmodx ${version} (${platform}) ready`);
   return cacheDir;
@@ -317,25 +488,9 @@ function extractWithPrefix(archivePath, destDir, opts) {
 
 async function downloadFile(url, dest) {
   const filename = path.basename(url);
-  const bar = require('./progress').createBar(100, `  ${chalk.cyan('Downloading')} ${(filename || 'file').padEnd(30)}`);
-
-  const response = await withRetry(
-    () => axios.get(url, {
-      responseType: 'arraybuffer',
-      maxRedirects: 5,
-      timeout: 600000, // large archives — allow slow links, still bound hangs
-      onDownloadProgress: (e) => {
-        if (bar && e.total) {
-          bar.update(Math.round(e.loaded / e.total * 100));
-        }
-      },
-    }),
-    { label: filename }
-  );
-  if (bar) bar.stop();
-  const part = dest + '.part';
-  fs.writeFileSync(part, Buffer.from(response.data));
-  fs.renameSync(part, dest);
+  return downloadToFile(url, dest, {
+    progressLabel: `  ${chalk.cyan('Downloading')} ${(filename || 'file').padEnd(30)}`,
+  });
 }
 
 function makeBinaryExecutable(destDir, platform) {
@@ -357,4 +512,4 @@ function findDir(root, name) {
   return null;
 }
 
-module.exports = { fetchCompiler, getCompilerInfo, getAmxmodxFullDir, getHostPlatform, fetchLatestVersion, resolveAmxmodxVersion };
+module.exports = { fetchCompiler, getCompilerInfo, getAmxmodxFullDir, getHostPlatform, fetchLatestVersion, findNewestCachedCompiler, resolveAmxmodxVersion, resolveStdlibVersion };