amxx-builder 1.5.2 → 1.6.0

package/src/commands/init.js

@@ -80,28 +80,28 @@ async function runInitInteractive(options) {
   const version = require('../../package.json').version;
   const actionTag = `v${version.split('.')[0]}`;
 
-  writeIfAbsent('amxbuild.yml', renderTemplate('init-manifest.yml', { name, schemaUrl: SCHEMA_URL }));
+  writeIfAbsent('amxbuild.yml', renderTemplate('init-manifest.yml', { name, schemaUrl: SCHEMA_URL }), options.force);
 
   if (doWorkflow) {
     const dest = path.join('.github', 'workflows', 'ci.yml');
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    writeIfAbsent(dest, renderTemplate('init-workflow.yml', { actionTag }));
+    writeIfAbsent(dest, renderTemplate('init-workflow.yml', { actionTag }), options.force);
   }
 
   if (pluginName) {
     const dest = path.join('amxmodx', 'scripting', `${pluginName}.sma`);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    writeIfAbsent(dest, '');
+    writeIfAbsent(dest, '', options.force);
   }
 
   if (doGitignore) {
     writeIfAbsent('.gitignore', [
       '*.amxx', '*.zip', '.env', '.amxb-cache', '.claude', 'build', 'dist', '',
-    ].join('\n'));
+    ].join('\n'), options.force);
   }
 
   if (doDeploy) {
-    writeIfAbsent('.env', renderTemplate('init-deploy.env'));
+    writeIfAbsent('.env', renderTemplate('init-deploy.env'), options.force);
   }
 
   if (doOpencode) {
@@ -109,7 +109,7 @@ async function runInitInteractive(options) {
   }
 
   if (doScript) {
-    writeBuildScripts();
+    writeBuildScripts(options.force);
   }
 }
 
@@ -118,28 +118,28 @@ function runInit(options) {
   const version = require('../../package.json').version;
   const actionTag = `v${version.split('.')[0]}`;
 
-  writeIfAbsent('amxbuild.yml', renderTemplate('init-manifest.yml', { name: pkgName, schemaUrl: SCHEMA_URL }));
+  writeIfAbsent('amxbuild.yml', renderTemplate('init-manifest.yml', { name: pkgName, schemaUrl: SCHEMA_URL }), options.force);
 
   if (options.workflow || options.ci) {
     const dest = path.join('.github', 'workflows', 'ci.yml');
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    writeIfAbsent(dest, renderTemplate('init-workflow.yml', { actionTag }));
+    writeIfAbsent(dest, renderTemplate('init-workflow.yml', { actionTag }), options.force);
   }
 
   if (options.plugin) {
     const dest = path.join('amxmodx', 'scripting', `${options.plugin}.sma`);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    writeIfAbsent(dest, '');
+    writeIfAbsent(dest, '', options.force);
   }
 
   if (options.gitignore) {
     writeIfAbsent('.gitignore', [
       '*.amxx', '*.zip', '.env', '.amxb-cache', '.claude', 'build', 'dist', '',
-    ].join('\n'));
+    ].join('\n'), options.force);
   }
 
   if (options.deploy) {
-    writeIfAbsent('.env', renderTemplate('init-deploy.env'));
+    writeIfAbsent('.env', renderTemplate('init-deploy.env'), options.force);
   }
 
   if (options.opencode) {
@@ -147,13 +147,13 @@ function runInit(options) {
   }
 
   if (options.script) {
-    writeBuildScripts();
+    writeBuildScripts(options.force);
   }
 }
 
-function writeBuildScripts() {
-  const batCreated = writeIfAbsent('build.bat', renderTemplate('init-build.bat').replace(/\r?\n/g, '\r\n'));
-  const shCreated  = writeIfAbsent('build.sh',  renderTemplate('init-build.sh'));
+function writeBuildScripts(force) {
+  const batCreated = writeIfAbsent('build.bat', renderTemplate('init-build.bat').replace(/\r?\n/g, '\r\n'), force);
+  const shCreated  = writeIfAbsent('build.sh',  renderTemplate('init-build.sh'), force);
 
   if (shCreated && process.platform !== 'win32') {
     try {
@@ -167,13 +167,14 @@ function writeBuildScripts() {
   return batCreated || shCreated;
 }
 
-function writeIfAbsent(filePath, content) {
-  if (fs.existsSync(filePath)) {
+function writeIfAbsent(filePath, content, force) {
+  const existed = fs.existsSync(filePath);
+  if (existed && !force) {
     logger.warn(`${filePath} already exists, skipping`);
     return false;
   }
   fs.writeFileSync(filePath, content);
-  logger.success(`Created ${filePath}`);
+  logger.success(existed ? `Overwritten ${filePath}` : `Created ${filePath}`);
   return true;
 }
 

package/src/commands/serve.js

@@ -22,12 +22,20 @@
  *   amxmodx.include.get     → compiler-fetcher fetchCompiler + glob + read
  *   deps.tree               → deps-tree buildDepTree + assembleRootDeps
  *   releases.list           → release-lister listReleases / listTags
+ *   repos.info              → github-api getRepoInfo
+ *   repos.branches          → github-api listBranches
+ *   repos.structure         → github-api getRepoStructure
  *   cache.info              → cache-info getCacheInfo
+ *   compiler.info           → compiler-fetcher getCompilerInfo
+ *   dep-graph.get           → dep-graph DepGraph
  *   build.plan              → build-plan buildPlanData
  *   build.start             → build-service runBuild (+ event notifications)
  *   build.cancel            → abort the running build (AbortController)
- *   compile.single          → compiler.compileSingle
+ *   compile.single          → compiler.compileSingle (+ captured output)
+ *   deploy.start / deploy.file / deploy.remove → deployer deployBuild/deployFile/removeDeployedFile
+ *   rcon.send               → rcon sendRcon
  *   watch.start / watch.stop → watcher.startWatch (+ watch.changed notifications)
+ *   serve.ping              → process info (health check)
  */
 
 const fs   = require('fs');
@@ -46,14 +54,23 @@ const { resolveManifestPath } = require('../manifest-path');
 const { resolveManifest, parseManifest, resolveGithubToken, parseDepString } = require('../manifest');
 const { validateManifestFile } = require('../validate');
 const { fetchDepIncludeDir, collectIncFiles, parseIncludeDirective, searchIncludeFile } = require('../include-tree');
-const { fetchCompiler, resolveAmxmodxVersion } = require('../compiler-fetcher');
+const { depLabel } = require('../deps-resolver');
+const { fetchCompiler, resolveAmxmodxVersion, getCompilerInfo } = require('../compiler-fetcher');
 const { buildDepTree, assembleRootDeps } = require('../deps-tree');
 const { listReleases, listTags } = require('../release-lister');
+const {
+  getRepoInfo, listBranches, getRepoStructure,
+  GithubError, isValidRepo, validateRepoStructureOptions,
+} = require('../github-api');
 const { getCacheInfo } = require('../cache-info');
 const { buildPlanData } = require('../build-plan');
 const { runBuild } = require('../build-service');
 const { compileSingle } = require('../compiler');
+const { deployBuild, deployFile, removeDeployedFile } = require('../deployer');
+const { sendRcon } = require('../rcon');
+const { DepGraph } = require('../dep-graph');
 const { startWatch } = require('../watcher');
+const pkg = require('../../package.json');
 
 // ─── Small interface helpers (no domain logic) ────────────────────────────────
 
@@ -86,6 +103,69 @@ function manifestPathFor(params) {
   return params?.manifest ? path.resolve(params.manifest) : resolveManifestPath().path;
 }
 
+/**
+ * GitHub token for repo-scope methods. Manifest tokens win: the .env next to
+ * the manifest is loaded first (it overrides the cwd .env loaded at startup —
+ * per the env convention: manifest .env is primary, cwd is the fallback).
+ * Then the explicit `token` param, then the process env, then anonymous.
+ */
+function resolveGithubTokenFor(params, repo) {
+  const manifestPath = manifestPathFor(params);
+  if (fs.existsSync(manifestPath)) {
+    loadEnvQuiet(manifestPath);
+    try {
+      const fromManifest = resolveGithubToken(parseManifest(manifestPath), repo);
+      if (fromManifest) return fromManifest;
+    } catch { /* unparseable manifest — fall back to explicit/env token */ }
+  }
+  return params?.token || process.env.GITHUB_TOKEN || null;
+}
+
+/**
+ * Shape a GitHub API error into the JSON-RPC error contract: -32603 with
+ * error.data = { status, repo, message }. Returns null for non-GitHub errors
+ * so the caller rethrows them unchanged.
+ */
+function githubRpcError(err, repo) {
+  if (err instanceof GithubError) {
+    err.code = -32603;
+    err.data = { status: err.status, repo, message: err.message };
+    return err;
+  }
+  if (err && err.response && typeof err.response.status === 'number') {
+    // Raw axios error (release-lister path) — normalize to the same contract.
+    const message = (err.response.data && err.response.data.message) || err.message;
+    const shaped = new Error(message);
+    shaped.code = -32603;
+    shaped.data = { status: err.response.status, repo, message };
+    return shaped;
+  }
+  return null;
+}
+
+function repoParamError(params) {
+  if (!params?.repo) return 'Missing required "repo" field';
+  if (!isValidRepo(params.repo)) return 'Invalid "repo": expected "owner/repo"';
+  return null;
+}
+
+// dotenv@17 prints an "injected env" line to stdout by default, which would
+// break the pure-JSON-RPC stdout contract — always load quietly here.
+function loadEnvQuiet(manifestPath) {
+  loadEnv(manifestPath, { quiet: true });
+}
+
+// Full manifest (defaults merged, set/define applied) for deploy methods.
+function deployRequestManifest(params) {
+  const manifestPath = manifestPathFor(params);
+  loadEnvQuiet(manifestPath);
+  return resolveManifest(manifestPath, { set: params?.set, define: params?.define });
+}
+
+function buildDirFor(params) {
+  return params?.buildDir ? path.resolve(params.buildDir) : path.join(process.cwd(), 'build');
+}
+
 /**
  * Create and configure the JSON-RPC server with all methods wired to core.
  * Does NOT connect or set up the environment — call runServe() for that.
@@ -97,6 +177,15 @@ function createServeServer() {
   let activeBuild   = null; // AbortController for the running build
   let activeWatcher = null; // chokidar watcher instance
 
+  // ─── Health check ────────────────────────────────────────────────────────
+
+  server.onRequest('serve.ping', () => ({
+    ok: true,
+    pid: process.pid,
+    version: pkg.version,
+    node: process.version,
+  }));
+
   // ─── Read-only: manifest ──────────────────────────────────────────────────
 
   server.onRequest('manifest.validate', (params) => {
@@ -105,7 +194,7 @@ function createServeServer() {
 
   server.onRequest('manifest.resolve', (params) => {
     const manifestPath = manifestPathFor(params);
-    loadEnv(manifestPath);
+    loadEnvQuiet(manifestPath);
     return resolveManifest(manifestPath, { set: params?.set, define: params?.define });
   });
 
@@ -138,6 +227,7 @@ function createServeServer() {
     let manifest = null;
     const manifestPath = manifestPathFor(params);
     if (fs.existsSync(manifestPath)) {
+      loadEnvQuiet(manifestPath);
       try {
         manifest = parseManifest(manifestPath);
         for (const dep of manifest.globalDeps) {
@@ -146,9 +236,9 @@ function createServeServer() {
               dep, resolveGithubToken(manifest, dep.repo),
               params?.noFetch === true, manifest.github.ssh
             );
-            searchPaths.push({ path: depDir, label: `${dep.repo}@${dep.ref}` });
+            searchPaths.push({ path: depDir, label: depLabel(dep) });
           } catch (err) {
-            errors.push(`${dep.repo}@${dep.ref}: ${err.message}`);
+            errors.push(`${depLabel(dep)}: ${err.message}`);
           }
         }
       } catch (err) {
@@ -186,10 +276,14 @@ function createServeServer() {
       err.code = -32602;
       throw err;
     }
+    loadEnvQuiet(manifestPath);
     const manifest = parseManifest(manifestPath);
 
     const deps = [];
     for (const dep of manifest.globalDeps) {
+      const base = dep.source === 'fungun'
+        ? { source: 'fungun', id: dep.id, url: dep.url }
+        : { source: dep.source || 'git', repo: dep.repo, ref: dep.ref };
       try {
         const includeDir = await fetchDepIncludeDir(
           dep, resolveGithubToken(manifest, dep.repo),
@@ -197,15 +291,14 @@ function createServeServer() {
         );
         const files = await collectIncFiles(includeDir);
         deps.push({
-          repo: dep.repo,
-          ref: dep.ref,
+          ...base,
           include_path: dep.include_path || null,
           include_dir: includeDir,
           count: files.length,
           files: files.map((f) => ({ rel: f.rel, abs: f.abs })),
         });
       } catch (err) {
-        deps.push({ repo: dep.repo, ref: dep.ref, error: err.message, files: [], count: 0 });
+        deps.push({ ...base, error: err.message, files: [], count: 0 });
       }
     }
     return { manifest: manifestPath, deps };
@@ -266,7 +359,7 @@ function createServeServer() {
     }
 
     const manifestPath = manifestPathFor(params);
-    loadEnv(manifestPath);
+    loadEnvQuiet(manifestPath);
     const manifest = parseManifest(manifestPath);
     const assembled = assembleRootDeps(manifest);
     return buildDepTree(assembled.rootDeps, {
@@ -279,18 +372,141 @@ function createServeServer() {
     });
   });
 
-  // ─── Releases / cache / plan ─────────────────────────────────────────────
+  // ─── Include dependency graph ────────────────────────────────────────────
+
+  server.onRequest('dep-graph.get', async (params) => {
+    if (!params?.sma_file) {
+      const err = new Error('Missing required "sma_file" parameter');
+      err.code = -32602;
+      throw err;
+    }
+    const smaPath = path.resolve(params.sma_file);
+    if (!fs.existsSync(smaPath)) {
+      const err = new Error(`File not found: ${smaPath}`);
+      err.code = -32602;
+      throw err;
+    }
+
+    const noFetch = params?.noFetch === true;
+
+    const manifestPath = manifestPathFor(params);
+    let manifest = null;
+    if (fs.existsSync(manifestPath)) {
+      loadEnvQuiet(manifestPath);
+      try { manifest = parseManifest(manifestPath); } catch { manifest = null; }
+    }
+
+    const version = await resolveVersionFromParams(params);
+    const { includeDir } = await fetchCompiler(version);
+
+    // Dep includes come BEFORE the stdlib — matching the real build's search order.
+    const includeDirs = [];
+    if (manifest) {
+      for (const dep of manifest.globalDeps) {
+        try {
+          includeDirs.push(await fetchDepIncludeDir(
+            dep, resolveGithubToken(manifest, dep.repo), noFetch, manifest.github.ssh
+          ));
+        } catch (err) { /* keep the rest of the dirs on partial failure */ }
+      }
+    }
+    if (includeDir) includeDirs.push(includeDir);
+    for (const d of (params?.include_dirs || [])) includeDirs.push(path.resolve(d));
+
+    const graph = new DepGraph(includeDirs);
+    graph.parseFile(smaPath);
+
+    const result = {
+      sma_file: smaPath,
+      version,
+      include_dirs: includeDirs,
+      ...graph.snapshot(),
+    };
+
+    // Reverse query: which .sma files transitively depend on this .inc?
+    if (params?.inc) {
+      const incAbs = path.resolve(params.inc);
+      result.smas_depending_on = [...graph.getSmasDependingOn(incAbs)].sort();
+    }
+
+    return result;
+  });
+
+  // ─── Releases / repos / cache / plan ─────────────────────────────────────
 
   server.onRequest('releases.list', async (params) => {
-    if (!params?.repo) {
-      const err = new Error('Missing required "repo" field');
+    const invalid = repoParamError(params);
+    if (invalid) {
+      const err = new Error(invalid);
       err.code = -32602;
       throw err;
     }
-    const token = params?.token || process.env.GITHUB_TOKEN || null;
+    const repo = params.repo;
+    const token = resolveGithubTokenFor(params, repo);
     const limit = params?.limit || 10;
-    if (params?.tags) return listTags(params.repo, { token, limit });
-    return listReleases(params.repo, { token, limit, includeAssets: params?.includeAssets });
+    try {
+      if (params?.tags) return await listTags(repo, { token, limit });
+      return await listReleases(repo, { token, limit, includeAssets: params?.includeAssets });
+    } catch (err) {
+      throw githubRpcError(err, repo) || err;
+    }
+  });
+
+  server.onRequest('repos.info', async (params) => {
+    const invalid = repoParamError(params);
+    if (invalid) {
+      const err = new Error(invalid);
+      err.code = -32602;
+      throw err;
+    }
+    const repo = params.repo;
+    const token = resolveGithubTokenFor(params, repo);
+    try {
+      return await getRepoInfo(repo, { token });
+    } catch (err) {
+      throw githubRpcError(err, repo) || err;
+    }
+  });
+
+  server.onRequest('repos.branches', async (params) => {
+    const invalid = repoParamError(params);
+    if (invalid) {
+      const err = new Error(invalid);
+      err.code = -32602;
+      throw err;
+    }
+    const repo = params.repo;
+    const token = resolveGithubTokenFor(params, repo);
+    const limit = Math.min(100, Math.max(1, params?.limit ?? 10));
+    const page = Math.max(1, params?.page ?? 1);
+    try {
+      return await listBranches(repo, { token, limit, page });
+    } catch (err) {
+      throw githubRpcError(err, repo) || err;
+    }
+  });
+
+  server.onRequest('repos.structure', async (params) => {
+    const invalid = repoParamError(params) || validateRepoStructureOptions(params);
+    if (invalid) {
+      const err = new Error(invalid);
+      err.code = -32602;
+      throw err;
+    }
+    const repo = params.repo;
+    const token = resolveGithubTokenFor(params, repo);
+    try {
+      return await getRepoStructure(repo, {
+        token,
+        ref: params?.ref || null,
+        depth: params?.depth,
+        dirsOnly: params?.dirsOnly === true,
+        ext: params?.ext,
+        maxEntries: params?.maxEntries,
+      });
+    } catch (err) {
+      throw githubRpcError(err, repo) || err;
+    }
   });
 
   server.onRequest('cache.info', (params) => {
@@ -298,6 +514,11 @@ function createServeServer() {
     return getCacheInfo(manifestPath);
   });
 
+  server.onRequest('compiler.info', async (params) => {
+    const version = await resolveVersionFromParams(params);
+    return getCompilerInfo(version, { noFetch: params?.noFetch === true });
+  });
+
   server.onRequest('build.plan', (params) => {
     const manifestPath = manifestPathFor(params);
     loadEnv(manifestPath, { quiet: true, override: false });
@@ -321,7 +542,7 @@ function createServeServer() {
     activeBuild = controller;
 
     const manifestPath = manifestPathFor(params);
-    loadEnv(manifestPath);
+    loadEnvQuiet(manifestPath);
     const manifest = resolveManifest(manifestPath, { set: params?.set, define: params?.define });
 
     // Forward core lifecycle events as server→client notifications while the
@@ -361,6 +582,85 @@ function createServeServer() {
     return { ok: true };
   });
 
+  // ─── Deploy ──────────────────────────────────────────────────────────────
+
+  server.onRequest('deploy.start', async (params) => {
+    const manifest = deployRequestManifest(params);
+    if (!manifest.deploy || !manifest.deploy.path) {
+      return { ok: false, message: 'Deploy path not configured.\n  → Set AMXB_DEPLOY_PATH in .env, or add deploy.path to your manifest' };
+    }
+    const copied = await deployBuild(manifest, buildDirFor(params), {
+      incremental: params?.incremental === true,
+    });
+    return { ok: true, copied };
+  });
+
+  server.onRequest('deploy.file', (params) => {
+    if (!params?.relPath) {
+      const err = new Error('Missing required "relPath" parameter');
+      err.code = -32602;
+      throw err;
+    }
+    const section = params?.section === 'assets' ? 'assets' : 'amxmodx';
+    const manifest = deployRequestManifest(params);
+    if (!manifest.deploy || !manifest.deploy.path) {
+      return { ok: false, message: 'Deploy path not configured' };
+    }
+    const dest = deployFile(manifest, buildDirFor(params), params.relPath, section);
+    return { ok: dest != null, dest: dest || null };
+  });
+
+  server.onRequest('deploy.remove', (params) => {
+    if (!params?.relPath) {
+      const err = new Error('Missing required "relPath" parameter');
+      err.code = -32602;
+      throw err;
+    }
+    const section = params?.section === 'assets' ? 'assets' : 'amxmodx';
+    const manifest = deployRequestManifest(params);
+    if (!manifest.deploy || !manifest.deploy.path) {
+      return { ok: false, message: 'Deploy path not configured' };
+    }
+    const dest = removeDeployedFile(manifest, buildDirFor(params), params.relPath, section);
+    return { ok: dest != null, dest: dest || null };
+  });
+
+  // ─── RCON ────────────────────────────────────────────────────────────────
+
+  server.onRequest('rcon.send', async (params) => {
+    if (!params?.command) {
+      const err = new Error('Missing required "command" parameter');
+      err.code = -32602;
+      throw err;
+    }
+
+    let host = params?.host;
+    let port = params?.port;
+    let password = params?.password;
+
+    // Fall back to the manifest's deploy.rcon config when host/password are omitted.
+    if ((host == null || password == null) && fs.existsSync(manifestPathFor(params))) {
+      try {
+        const rconCfg = parseManifest(manifestPathFor(params)).deploy?.rcon;
+        if (rconCfg) {
+          if (host == null) host = rconCfg.host;
+          if (port == null) port = rconCfg.port;
+          if (password == null) password = rconCfg.password;
+        }
+      } catch { /* unparseable manifest — explicit params only */ }
+    }
+    if (port == null) port = 27015;
+
+    if (!host || !password) {
+      const err = new Error('RCON host/password not provided (pass explicitly or configure deploy.rcon in the manifest)');
+      err.code = -32602;
+      throw err;
+    }
+
+    const response = await sendRcon({ host, port, password, command: params.command });
+    return { ok: true, response };
+  });
+
   // ─── Single-file compile ─────────────────────────────────────────────────
 
   server.onRequest('compile.single', async (params) => {
@@ -381,6 +681,7 @@ function createServeServer() {
     const manifestPath = manifestPathFor(params);
     let manifest = null;
     if (fs.existsSync(manifestPath)) {
+      loadEnvQuiet(manifestPath);
       try { manifest = parseManifest(manifestPath); } catch { manifest = null; }
     }
 
@@ -397,7 +698,7 @@ function createServeServer() {
             dep, resolveGithubToken(manifest, dep.repo), noFetch, manifest.github.ssh
           ));
         } catch (err) {
-          depErrors.push(`${dep.repo}@${dep.ref}: ${err.message}`);
+          depErrors.push(`${depLabel(dep)}: ${err.message}`);
         }
       }
     }
@@ -408,18 +709,30 @@ function createServeServer() {
 
     const buildDir = path.join(os.tmpdir(), 'amxb-serve-compile');
     const compileManifest = manifest || { amxmodx: { defines: [] } };
-    const amxxName = await compileSingle(
-      compileManifest,
-      smaPath,
-      compilerPath,
-      includeDirs,
-      buildDir,
-      params?.scripting_root ? path.resolve(params.scripting_root) : undefined
-    );
+
+    // Capture the compiler output emitted as an event by compileSingle.
+    const baseName = path.basename(smaPath);
+    let compiled = null;
+    const onCompiled = (p) => { if (p.baseName === baseName) compiled = p; };
+    on(EVENTS.COMPILED, onCompiled);
+    let amxxName;
+    try {
+      amxxName = await compileSingle(
+        compileManifest,
+        smaPath,
+        compilerPath,
+        includeDirs,
+        buildDir,
+        params?.scripting_root ? path.resolve(params.scripting_root) : undefined
+      );
+    } finally {
+      off(EVENTS.COMPILED, onCompiled);
+    }
 
     return {
       ok: amxxName != null,
       amxxName,
+      output: compiled ? compiled.output : undefined,
       output_path: amxxName ? path.join(buildDir, 'amxmodx', 'plugins', amxxName) : null,
       dep_errors: depErrors.length ? depErrors : undefined,
     };

package/src/compiler-fetcher.js

@@ -65,6 +65,39 @@ async function fetchCompiler(version, options = {}) {
   return { compilerPath: binaryPath, includeDir: fs.existsSync(includeDir) ? includeDir : null };
 }
 
+/**
+ * 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('.');
@@ -324,4 +357,4 @@ function findDir(root, name) {
   return null;
 }
 
-module.exports = { fetchCompiler, getAmxmodxFullDir, getHostPlatform, fetchLatestVersion, resolveAmxmodxVersion };
+module.exports = { fetchCompiler, getCompilerInfo, getAmxmodxFullDir, getHostPlatform, fetchLatestVersion, resolveAmxmodxVersion };