amxx-builder 1.5.2 → 1.6.1

package/src/commands/skills-dir.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// Absolute path to the skills/ directory bundled with this amxb installation.
+// Resolved relative to the running code, so it works for any install method
+// (npm -g, install.sh/ps1, linked dev checkout) without consulting npm.
+const SKILLS_DIR = path.join(__dirname, '..', '..', 'skills');
+
+function runSkillsDir() {
+  if (!fs.existsSync(SKILLS_DIR)) {
+    process.stderr.write(`skills directory not found: ${SKILLS_DIR}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  // Pure stdout — consumers (e.g. the opencode bridge plugin) parse exactly this line.
+  process.stdout.write(SKILLS_DIR + '\n');
+}
+
+module.exports = { runSkillsDir, SKILLS_DIR };

package/src/commands/watch.js

@@ -95,13 +95,49 @@ 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) {
@@ -127,6 +163,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`);
@@ -162,7 +203,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 +220,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

@@ -57,9 +57,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 };

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,85 @@ 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
+ * present (downloaded on first use), exactly like fetchCompiler.
+ *
+ * @param {string} [version] - explicit version (else resolved like the CLI: manifest → latest)
+ * @param {object} [options]
+ * @param {boolean} [options.noFetch] - don't download; report cache state only
+ * @returns {Promise<{version: string, platform: string, compilerPath: string|null, includeDir: string|null, cached: boolean}>}
+ */
+async function getCompilerInfo(version, options = {}) {
+  const { noFetch = false } = options;
+  const resolved = version || await fetchLatestVersion({ noFetch });
+  const platform = getPlatform();
+  const cacheDir = path.join(getCacheDir(), 'amxxpc', resolved, platform);
+  const binaryName = platform === 'windows' ? 'amxxpc.exe' : 'amxxpc';
+  const compilerPath = path.join(cacheDir, binaryName);
+  const includeDir = path.join(cacheDir, 'include');
+
+  if (!fs.existsSync(compilerPath) && !noFetch) {
+    await fetchCompiler(resolved);
+  }
+
+  const cached = fs.existsSync(compilerPath);
+  return {
+    version: resolved,
+    platform,
+    compilerPath: cached ? compilerPath : null,
+    includeDir: fs.existsSync(includeDir) ? includeDir : null,
+    cached,
+  };
+}
+
 // "1.10.5428" → { major: '1', minor: '10', build: '5428' }
 function parseVersion(versionStr) {
   const parts = String(versionStr).split('.');
@@ -101,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;
@@ -187,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();
 }
@@ -202,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.
@@ -223,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;
@@ -284,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) {
@@ -324,4 +512,4 @@ function findDir(root, name) {
   return null;
 }
 
-module.exports = { fetchCompiler, getAmxmodxFullDir, getHostPlatform, fetchLatestVersion, resolveAmxmodxVersion };
+module.exports = { fetchCompiler, getCompilerInfo, getAmxmodxFullDir, getHostPlatform, fetchLatestVersion, findNewestCachedCompiler, resolveAmxmodxVersion, resolveStdlibVersion };

package/src/compiler.js

@@ -5,6 +5,7 @@ const micromatch = require('micromatch');
 const logger = require('./logger');
 const { emit, EVENTS } = require('./events');
 const { spawnCompiler, buildIncludeArgs, buildDefineArgs } = require('./compile-utils');
+const { repoKey, normalizeRepo } = require('./deps-resolver');
 
 /**
  * Applies plugin rules to a local .sma file path (relative to scripting/).
@@ -30,17 +31,24 @@ async function compilePlugins(manifest, repoLocalDirs, compilerPath, includeDirs
   const collectedIncDir = path.join(buildDir, 'amxmodx', 'scripting', 'include');
 
   // ── Build unified source list ──────────────────────────────────────────────
-  const sources = manifest.repos.map((repoConfig) => ({
-    label:        repoConfig.repo,
-    ref:          repoConfig._resolvedRef || repoConfig.ref || 'HEAD',
-    scriptingDir: path.join(
-      repoLocalDirs[`${repoConfig.repo}@${repoConfig._resolvedRef || repoConfig.ref || 'HEAD'}`],
-      repoConfig.amxmodx_dir,
-      'scripting'
-    ),
-    exclude: repoConfig.exclude,
-    postfix: repoConfig.plugins_ini_postfix,
-  }));
+  const seenSources = new Set(); // case-insensitive repo identity (dedupe)
+  const sources = [];
+  for (const repoConfig of manifest.repos) {
+    const identity = normalizeRepo(repoConfig);
+    if (seenSources.has(identity)) continue;
+    seenSources.add(identity);
+    sources.push({
+      label:        repoConfig.repo,
+      ref:          repoConfig._resolvedRef || repoConfig.ref || 'HEAD',
+      scriptingDir: path.join(
+        repoLocalDirs[repoKey(repoConfig)],
+        repoConfig.amxmodx_dir,
+        'scripting'
+      ),
+      exclude: repoConfig.exclude,
+      postfix: repoConfig.plugins_ini_postfix,
+    });
+  }
 
   const localScriptingDir = path.join(path.dirname(manifest._path), manifest.amxmodx.dir, 'scripting');
   if (fs.existsSync(localScriptingDir)) {
@@ -194,8 +202,12 @@ async function findExcluded(dir, patterns) {
 /**
  * Compiles a single .sma file. Used by watch mode.
  * Returns the .amxx filename on success, null on failure.
+ *
+ * eventTag (optional) is echoed in the emitted EVENTS.COMPILED payload so a
+ * subscriber can attribute the event to a specific call — needed when several
+ * compiles of same-named files run concurrently (serve compile.single).
  */
-async function compileSingle(manifest, smaPath, compilerPath, includeDirs, buildDir, scriptingRootDir) {
+async function compileSingle(manifest, smaPath, compilerPath, includeDirs, buildDir, scriptingRootDir, eventTag = null) {
   const pluginsDir      = path.join(buildDir, 'amxmodx', 'plugins');
   const collectedIncDir = path.join(buildDir, 'amxmodx', 'scripting', 'include');
 
@@ -217,11 +229,11 @@ async function compileSingle(manifest, smaPath, compilerPath, includeDirs, build
   const { status, output } = await spawnCompiler(compilerPath, [smaPath, `-o${outPath}`, ...includes, ...defines]);
 
   if (status !== 0) {
-    emit(EVENTS.COMPILED, { baseName, ok: false, output, amxxName: null, repo: null, ref: null, outName });
+    emit(EVENTS.COMPILED, { baseName, ok: false, output, amxxName: null, repo: null, ref: null, outName, tag: eventTag });
     return null;
   }
 
-  emit(EVENTS.COMPILED, { baseName, ok: true, output, amxxName: outName, repo: null, ref: null, outName });
+  emit(EVENTS.COMPILED, { baseName, ok: true, output, amxxName: outName, repo: null, ref: null, outName, tag: eventTag });
   return outName;
 }
 

package/src/dep-graph.js

@@ -24,6 +24,8 @@ class DepGraph {
     this._includeDirs = includeDirs;
     // absPath → Set<absPath>: direct includes of each file
     this._deps = new Map();
+    // absPath → [{name, isAngle}]: includes that could not be resolved
+    this._missing = new Map();
     this._parsed = new Set();
   }
 
@@ -34,23 +36,44 @@ class DepGraph {
     if (!fs.existsSync(absPath)) return;
 
     const directs = new Set();
+    const missing = [];
     for (const { name, isAngle } of extractIncludes(absPath)) {
       const resolved = this._resolve(absPath, name, isAngle);
       if (resolved) {
         directs.add(resolved);
         this.parseFile(resolved);
+      } else {
+        missing.push({ name, isAngle });
       }
     }
     this._deps.set(absPath, directs);
+    if (missing.length) this._missing.set(absPath, missing);
+    else this._missing.delete(absPath);
   }
 
   // Re-parse a changed file (drops stale edges, keeps the rest of the graph).
   update(absPath) {
     this._parsed.delete(absPath);
     this._deps.delete(absPath);
+    this._missing.delete(absPath);
     this.parseFile(absPath);
   }
 
+  // Structured snapshot of the parsed graph: every parsed file with its direct
+  // (resolved) includes, plus includes that could not be resolved. Exposed to
+  // interface layers (serve/JSON-RPC) so the graph can be serialized.
+  snapshot() {
+    const files = [];
+    for (const [file, deps] of this._deps) {
+      files.push({ file, isSma: file.endsWith('.sma'), includes: [...deps].sort() });
+    }
+    const missing = [];
+    for (const [file, list] of this._missing) {
+      for (const { name, isAngle } of list) missing.push({ file, name, isAngle });
+    }
+    return { files, missing };
+  }
+
   // Returns Set<absPath> of .sma files that transitively depend on incPath.
   getSmasDependingOn(incPath) {
     const smas    = new Set();
@@ -70,6 +93,33 @@ class DepGraph {
     return smas;
   }
 
+  // A previously-missing include has just appeared (watch 'add' on a new .inc).
+  // Re-resolve outstanding missing includes; files whose include now resolves
+  // to incPath are re-parsed and every depending .sma is returned.
+  reattachMissingIncludes(incPath) {
+    const referencing = [];
+    for (const [file, missingList] of this._missing) {
+      if (referencing.includes(file)) continue;
+      for (const { name, isAngle } of missingList) {
+        if (this._resolve(file, name, isAngle) === incPath) {
+          referencing.push(file);
+          break;
+        }
+      }
+    }
+
+    const smas = new Set();
+    for (const file of referencing) {
+      this.update(file);
+      if (file.endsWith('.sma')) smas.add(file);
+    }
+    for (const file of referencing) {
+      if (file.endsWith('.sma')) continue;
+      for (const sma of this.getSmasDependingOn(file)) smas.add(sma);
+    }
+    return smas;
+  }
+
   _resolve(fromFile, name, isAngle) {
     const withExt = /\.inc$/i.test(name) ? name : name + '.inc';