amxx-builder 1.5.2 → 1.6.0

package/src/dep-docs.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { fetchRepo, resolveRefIfLatest } = require('./repo-fetcher');
+const { fetchReleaseDep } = require('./release-fetcher');
+const { fetchDepRoot }    = require('./deps-resolver');
+const { parseDepString, parseDepObject } = require('./manifest');
+
+// Fallback doc files a dependency repo may ship when it declares no explicit
+// `docs:` paths. Checked in order at the repo root.
+// Deliberately NOT AGENTS.md: that file is instructions for agents working
+// INSIDE the repo (build commands, contribution rules), not consumer-facing
+// API docs — feeding it to an outside agent leaks the wrong context.
+const DOCS_CONVENTIONS = ['docs/API.md', 'API.md'];
+
+/**
+ * Normalize a raw dep value (string or dep object) into a parsed dep object.
+ * @param {string|object} raw
+ * @returns {object} parsed dep object
+ */
+function normalizeDep(raw) {
+  if (typeof raw === 'string') return parseDepString(raw);
+  if (raw && typeof raw === 'object') return parseDepObject(raw);
+  throw new Error('Dep must be a string or an object');
+}
+
+/**
+ * Resolve which agent-facing doc files exist for a dependency inside rootDir.
+ * Declared `dep.docs` paths come first (in array order), then convention
+ * candidates that exist on disk. Deduped by rel path — declared wins.
+ *
+ * @param {object} dep - parsed dep object ({ docs: string[]|null, ... })
+ * @param {string} rootDir - local root of the fetched repo/asset
+ * @returns {{ files: Array<{ rel: string, abs: string, origin: 'declared'|'convention' }>, missing: string[] }}
+ */
+function resolveDepDocs(dep, rootDir) {
+  const files   = [];
+  const missing = [];
+  const seen    = new Set();
+
+  const declared = Array.isArray(dep.docs) ? dep.docs : [];
+
+  for (const rel of declared) {
+    const abs = path.resolve(rootDir, rel);
+    if (abs !== rootDir && !abs.startsWith(rootDir + path.sep)) {
+      throw new Error(`docs path escapes the repo root: "${rel}"`);
+    }
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+      files.push({ rel, abs, origin: 'declared' });
+    } else {
+      missing.push(rel);
+    }
+  }
+
+  for (const rel of DOCS_CONVENTIONS) {
+    if (seen.has(rel)) continue;
+    const abs = path.join(rootDir, rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+      seen.add(rel);
+      files.push({ rel, abs, origin: 'convention' });
+    }
+  }
+
+  return { files, missing };
+}
+
+/**
+ * UTF-8 read that never throws: binary files and read errors are returned as
+ * descriptive placeholder strings instead.
+ * @param {string} abs - absolute file path
+ * @returns {string}
+ */
+function safeRead(abs) {
+  try {
+    const buf = fs.readFileSync(abs);
+    try {
+      const text = buf.toString('utf8');
+      if (text.includes('\u0000')) return `[binary file, ${buf.length} bytes]`;
+      return text;
+    } catch (_) {
+      return `[binary file, ${buf.length} bytes]`;
+    }
+  } catch (err) {
+    return `[error reading file: ${err.message}]`;
+  }
+}
+
+/**
+ * Fetch a dependency and collect its agent-facing doc files with contents.
+ * `fetchRoot` is a test seam — defaults to the core fetchDepRoot.
+ *
+ * @param {object} dep - parsed dep object
+ * @param {object} [opts]
+ * @param {string} [opts.token]
+ * @param {boolean} [opts.noFetch]
+ * @param {boolean} [opts.ssh]
+ * @param {Function} [opts.fetchRoot] - ({ dep, ... }) => Promise<{ rootDir, label }>
+ * @returns {Promise<{ label: string, files: Array<{ rel: string, content: string, origin: string }>, missing: string[] }>}
+ */
+async function collectDepDocs(dep, { token, noFetch, ssh, fetchRoot } = {}) {
+  const fetch = fetchRoot || fetchDepRoot;
+  const { rootDir, label } = await fetch(dep, { token, noFetch, ssh });
+  const { files, missing } = resolveDepDocs(dep, rootDir);
+  return {
+    label,
+    files: files.map((f) => ({ rel: f.rel, content: safeRead(f.abs), origin: f.origin })),
+    missing,
+  };
+}
+
+module.exports = { DOCS_CONVENTIONS, resolveDepDocs, collectDepDocs, normalizeDep };

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();

package/src/deployer.js

@@ -92,9 +92,11 @@ function deployPlugin(manifest, buildDir, amxxName) {
 /**
  * Deploy a single changed local file (watch mode for amxmodx/ or assets/).
  * relPath is relative to the section root (amxmodx/ or assets/).
+ * Returns the destination path, or null when not deployed (no deploy path,
+ * missing source, or excluded).
  */
 function deployFile(manifest, buildDir, relPath, section) {
-  if (!manifest.deploy.path) return;
+  if (!manifest.deploy.path) return null;
 
   const { amxmodxDest, assetsDest, deployRoot } = resolveDeployDirs(manifest);
 
@@ -104,24 +106,26 @@ function deployFile(manifest, buildDir, relPath, section) {
   const src  = path.join(srcBase, relPath);
   const dest = path.join(destBase, relPath);
 
-  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(src)) return null;
   if (isExcluded(dest, deployRoot, manifest.deploy.exclude || [])) {
     logger.verbose(`  skip (excluded): ${relPath}`);
-    return;
+    return null;
   }
 
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   fs.copyFileSync(src, dest);
   logger.success(`Deployed: ${relPath}`);
   logger.verbose(`  → ${dest}`);
+  return dest;
 }
 
 /**
  * Removes a deployed file that was deleted locally (watch mode).
  * relPath is relative to the section root. Honours deploy.exclude.
+ * Returns the removed destination path, or null when nothing was removed.
  */
 function removeDeployedFile(manifest, buildDir, relPath, section) {
-  if (!manifest.deploy.path) return;
+  if (!manifest.deploy.path) return null;
 
   const { amxmodxDest, assetsDest, deployRoot } = resolveDeployDirs(manifest);
 
@@ -130,12 +134,13 @@ function removeDeployedFile(manifest, buildDir, relPath, section) {
 
   if (isExcluded(dest, deployRoot, manifest.deploy.exclude || [])) {
     logger.verbose(`  skip delete (excluded): ${relPath}`);
-    return;
+    return null;
   }
 
-  if (!fs.existsSync(dest)) return;
+  if (!fs.existsSync(dest)) return null;
   fs.rmSync(dest, { force: true });
   logger.success(`Removed: ${relPath}`);
+  return dest;
 }
 
 // ─── helpers ─────────────────────────────────────────────────────────────────

package/src/deps-resolver.js

@@ -5,6 +5,7 @@ const logger = require('./logger');
 const { parseDepsLines, resolveGithubToken } = require('./manifest');
 const { fetchRepo, resolveRefIfLatest } = require('./repo-fetcher');
 const { fetchReleaseDep } = require('./release-fetcher');
+const { fetchFungunDep } = require('./fungun-fetcher');
 
 /**
  * Resolves all deps, clones them, copies .inc files to build/_includes/,
@@ -52,11 +53,14 @@ async function resolveDeps(manifest, repoLocalDirs, noFetch, buildDir) {
   const includeDirs = [];
 
   for (const [k, dep] of merged) {
-    const token = resolveGithubToken(manifest, dep.repo);
     let srcDir;
     if (dep.source === 'release') {
+      const token = resolveGithubToken(manifest, dep.repo);
       srcDir = await fetchReleaseDep(dep, token, noFetch);
+    } else if (dep.source === 'fungun') {
+      srcDir = await fetchFungunDep(dep, noFetch);
     } else {
+      const token = resolveGithubToken(manifest, dep.repo);
       const resolvedDepRef = await resolveRefIfLatest(dep.ref, dep.repo, token);
       const depDir = await fetchRepo(dep.repo, resolvedDepRef, token, noFetch, manifest.github.ssh);
       srcDir = resolveIncludePath(depDir, dep.include_path, dep.repo);
@@ -72,7 +76,7 @@ async function resolveDeps(manifest, repoLocalDirs, noFetch, buildDir) {
       fs.copyFileSync(path.join(srcDir, f), dest);
     }
 
-    logger.dim(`  ${dep.repo}@${dep.ref}: ${files.length} .inc files`);
+    logger.dim(`  ${depLabel(dep)}: ${files.length} .inc files`);
     includeDirs.push(destDir);
   }
 
@@ -106,10 +110,57 @@ function resolveIncludePath(repoDir, explicitPath, repoName) {
   return repoDir;
 }
 
+/**
+ * Fetch a dependency's root directory and return a human-readable label for it.
+ * Single source of truth shared by the build pipeline, the MCP server and
+ * dep-docs resolution.
+ *
+ * `dep` is a parsed dep OBJECT ({ repo, ref, source, include_path, asset }).
+ * GitHub token resolution (per-owner fallbacks) is an interface-layer concern —
+ * callers pass the already-resolved token, this function never calls fallbackToken.
+ *
+ * @param {object} dep - parsed dep object
+ * @param {object} [opts]
+ * @param {string} [opts.token]     - GitHub token or null (anonymous)
+ * @param {boolean} [opts.noFetch]  - only use cache, skip network fetches
+ * @param {boolean} [opts.ssh]      - clone via system git instead of tarball
+ * @returns {Promise<{ rootDir: string, label: string }>}
+ */
+async function fetchDepRoot(dep, { token, noFetch, ssh = false } = {}) {
+  if (dep.source === 'release') {
+    const dir = await fetchReleaseDep(dep, token, noFetch);
+    return { rootDir: dir, label: `${dep.repo}@${dep.ref} (release)` };
+  }
+
+  if (dep.source === 'fungun') {
+    const dir = await fetchFungunDep(dep, noFetch);
+    return { rootDir: dir, label: depLabel(dep) };
+  }
+
+  const resolvedRef = await resolveRefIfLatest(dep.ref, dep.repo, token);
+  const repoDir = await fetchRepo(dep.repo, resolvedRef, token, noFetch, ssh);
+  if (dep.include_path) {
+    const sub = path.join(repoDir, dep.include_path);
+    if (!fs.existsSync(sub)) {
+      throw new Error(`include_path "${dep.include_path}" not found in ${dep.repo}`);
+    }
+    return { rootDir: sub, label: `${dep.repo}@${dep.ref || 'default branch'}` };
+  }
+  return { rootDir: repoDir, label: `${dep.repo}@${dep.ref || 'default branch'}` };
+}
+
 // Single source of truth for repo-name normalization (used for cache keys
 // and dedup by core modules that previously inlined repo.toLowerCase()).
 function normalize(repo) { return repo.toLowerCase(); }
 
+// Human-readable dep label (fungun deps: no repo@ref — addressed by shop page id).
+function depLabel(dep) {
+  if (dep && dep.source === 'fungun') {
+    return `fungun.net plugin #${dep.id}`;
+  }
+  return `${dep.repo}@${dep.ref || 'default branch'}`;
+}
+
 function repoKey(repoConfig) {
   return `${repoConfig.repo}@${repoConfig._resolvedRef || repoConfig.ref || 'HEAD'}`;
 }
@@ -124,4 +175,4 @@ function countIncFiles(dir) {
   return n;
 }
 
-module.exports = { resolveDeps, readDepsListFile, normalize, repoKey };
+module.exports = { resolveDeps, readDepsListFile, normalize, repoKey, fetchDepRoot, depLabel };

package/src/deps-tree.js

@@ -100,6 +100,24 @@ function assembleRootDeps(manifest) {
 // ─── Recursive walk ────────────────────────────────────────────────────────────
 
 async function walkDep(dep, ctx) {
+  // Fungun: closed-source page dep — no repo to resolve a ref on, no DEPS_LIST to recurse into.
+  if (dep.source === 'fungun') {
+    return {
+      repo:         dep.repo || `fungun.net/#${dep.id}`,
+      ref:          null,
+      resolvedRef:  null,
+      id:           dep.id,
+      source:       'fungun',
+      include_path: null,
+      asset:        null,
+      from:         ctx.from,
+      error:        null,
+      cycle:        false,
+      shared:       false,
+      dependencies: [],
+    };
+  }
+
   const { resolveToken, noFetch, depth, visited, pathStack, getDepsOverride } = ctx;
 
   const repo = dep.repo;

package/src/fungun-fetcher.js

@@ -0,0 +1,347 @@
+'use strict';
+
+/**
+ * Fungun dep source (fungun.net) — closed-source AMXX plugin shop.
+ *
+ * Plugins ship no archives and no direct file URLs. The only public artifact
+ * is the plugin "show" page, which always embeds one Bootstrap modal per
+ * shipped file (configs, lang, and — when the plugin exposes an API — exactly
+ * the .inc include). Modal DOM ids are page-specific (`ModalText<number>`),
+ * so a plugin is addressed by its page index and the .inc payload is located
+ * by scanning every modal for a `modal-title` filename ending in `.inc`:
+ *
+ *   <div class="modal fade" id="ModalText267" ...>
+ *     <div class="modal-body ...">
+ *       <button ... close ...></button>
+ *       <h3 class="modal-title">bonusmenu_rbs.inc</h3>
+ *       <div class="border_text"></div>
+ *       <pre class="language-cpp"><code>... include text ...</code></pre>
+ *
+ * Ownership (single source of truth for everything fungun):
+ *   - id/url normalization and validation (parsePluginRef)
+ *   - page fetch + modal extraction (fetchFungunPage, extractIncFiles)
+ *   - on-disk cache: <CACHE_DIR>/fungun/<plugin-id>/ (sentinel `.fungun`)
+ *
+ * Manifest/dep parsing (`src/manifest.js`) and the fetch entry points in
+ * deps-resolver / include-tree delegate here — no other module re-parses
+ * fungun references or re-implements the extraction.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const axios = require('axios');
+
+const logger = require('./logger');
+const { getCacheDir } = require('./cache-dir');
+const { withRetry } = require('./retry');
+
+const FUNGUN_BASE_URL  = 'https://fungun.net';
+const FUNGUN_SHOW_PATH = '/shop/?p=show&id=';
+
+// fungun serves plain HTML to browsers; a bare axios UA may get a different
+// (login/captcha) response. Keep a realistic browser UA on every request.
+const BROWSER_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+  '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+const SENTINEL_FILE = '.fungun'; // content: plugin id — mirrors release-deps `.extracted`
+
+// Fungun pages pin no version/ref — refetch the page cache daily (--no-fetch still uses the stale copy).
+const FUNGUN_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+function pluginPageUrl(id) {
+  return `${FUNGUN_BASE_URL}${FUNGUN_SHOW_PATH}${id}`;
+}
+
+/**
+ * Normalize a fungun plugin reference.
+ *
+ * Accepts:
+ *   - a positive integer id (number or numeric string) — `106`
+ *   - a full plugin page URL — `https://fungun.net/shop/?p=show&id=106`
+ *
+ * Returns `{ id, url }` (id as a numeric string; url is the canonical page URL
+ * for bare ids and the caller-provided URL otherwise). Throws on anything
+ * else — this is the single validation point used by both manifest parsing
+ * and the fetcher, so error messages are user-facing.
+ *
+ * @param {number|string} value
+ * @returns {{ id: string, url: string }|null}
+ */
+function parsePluginRef(value) {
+  if (value == null || value === '') return null;
+
+  let str;
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error(
+        `Invalid fungun plugin id: ${value} — expected a positive plugin index`
+      );
+    }
+    str = String(value);
+    return { id: str, url: pluginPageUrl(str) };
+  }
+
+  if (typeof value !== 'string') {
+    throw new Error(
+      `Invalid fungun plugin reference: ${JSON.stringify(value)} — expected a plugin id or fungun.net URL`
+    );
+  }
+  str = value.trim();
+  if (!str) return null;
+
+  // Bare plugin index
+  if (/^\d+$/.test(str)) return { id: str, url: pluginPageUrl(str) };
+
+  // Full page URL
+  if (/^https?:\/\//i.test(str)) {
+    let hostname;
+    try {
+      hostname = new URL(str).hostname;
+    } catch {
+      throw new Error(`Invalid fungun plugin URL: "${str}"`);
+    }
+    if (hostname !== 'fungun.net' && !hostname.endsWith('.fungun.net')) {
+      throw new Error(
+        `Invalid fungun dep URL "${str}" — expected a fungun.net page (host: ${hostname})`
+      );
+    }
+    const idMatch = str.match(/[?&]id=(\d+)/);
+    if (!idMatch) {
+      throw new Error(
+        `Invalid fungun plugin URL "${str}" — missing "id=<index>" parameter`
+      );
+    }
+    return { id: idMatch[1], url: str };
+  }
+
+  throw new Error(
+    `Invalid fungun plugin reference "${str}" — ` +
+    `expected a plugin index (e.g. 106) or a fungun.net page URL`
+  );
+}
+
+/**
+ * Fetch a fungun plugin page. `ref` is the output of parsePluginRef.
+ *
+ * @param {{ id: string, url: string }} ref
+ * @returns {Promise<string>} page HTML (UTF-8)
+ */
+async function fetchFungunPage(ref) {
+  const url = ref.url || pluginPageUrl(ref.id);
+  const response = await withRetry(
+    () => axios.get(url, {
+      headers: {
+        'User-Agent': BROWSER_UA,
+        Accept: 'text/html,application/xhtml+xml',
+      },
+      responseType: 'text',
+      timeout: 30000,
+      maxRedirects: 5,
+    }),
+    { label: `fungun plugin #${ref.id}` }
+  );
+
+  if (response.status !== 200) {
+    throw new Error(`Failed to fetch fungun plugin page #${ref.id} — HTTP ${response.status}`);
+  }
+  return String(response.data);
+}
+
+// ─── HTML extraction ──────────────────────────────────────────────────────────
+// Deliberately regex-based: the target markup is a fixed two-level shape
+// (modal div → h3.modal-title + pre > code) inside page-generated ids.
+// No HTML parser dependency is needed to stay correct on Node 18 + offline CI.
+
+/**
+ * Parse every "file modal" out of a plugin page. Returns entries in page
+ * order: `{ modalId, filename, content }` (entities decoded, content trimmed).
+ * Modals without an h3 filename or a code block are skipped.
+ *
+ * @param {string} html
+ * @returns {Array<{ modalId: string, filename: string, content: string }>}
+ */
+function extractIncModals(html) {
+  const opens = [];
+  const modalRe = /<div[^>]*\sid="(ModalText[^"]+)"[^>]*>/g;
+  let m;
+  while ((m = modalRe.exec(html))) opens.push({ id: m[1], start: m.index });
+
+  const modals = [];
+  for (let i = 0; i < opens.length; i++) {
+    const end = i + 1 < opens.length ? opens[i + 1].start : html.length;
+    const seg = html.slice(opens[i].start, end);
+
+    const filename = matchModalFilename(seg);
+    const content  = matchModalCode(seg);
+    if (!filename || content === null) continue;
+
+    modals.push({ modalId: opens[i].id, filename, content: content.trim() });
+  }
+  return modals;
+}
+
+function matchModalFilename(seg) {
+  const m = seg.match(/<h3[^>]*>([\s\S]*?)<\/h3>/);
+  return m ? decodeEntities(m[1]).trim() : null;
+}
+
+function matchModalCode(seg) {
+  const m = seg.match(/<pre[^>]*>[\s\S]*?<code[^>]*>([\s\S]*?)<\/code>[\s\S]*?<\/pre>/);
+  return m ? decodeEntities(m[1]) : null;
+}
+
+/**
+ * Extract the include files (.inc modals) from a plugin page.
+ *
+ * @param {string} html
+ * @returns {Array<{ modalId: string, filename: string, content: string }>}
+ */
+function extractIncFiles(html) {
+  return extractIncModals(html).filter((m) => m.filename.toLowerCase().endsWith('.inc'));
+}
+
+function decodeEntities(str) {
+  return String(str)
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex) => codePointToString(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, dec) => codePointToString(parseInt(dec, 10)))
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&');
+}
+
+function codePointToString(cp) {
+  try {
+    return String.fromCodePoint(cp);
+  } catch {
+    return '\uFFFD';
+  }
+}
+
+/**
+ * Fetch the .inc payload of a fungun plugin into the local cache.
+ *
+ * Cache: <CACHE_DIR>/fungun/<plugin-id>/ — one file per .inc modal, named
+ * after the modal title (path traversal is stripped via basename). The
+ * sentinel `.fungun` marks a complete fetch. Because fungun pages have no
+ * version to pin, the cache expires after FUNGUN_CACHE_TTL_MS and is
+ * refetched on the next build. A refetch that fails (network, or the page
+ * no longer exposing the include) falls back to the last known-good copy,
+ * so an expired cache never breaks a build by itself.
+ *
+ * @param {object|number|string} dep - parsed fungun dep ({ id } / { url }) or a raw reference
+ * @param {boolean} [noFetch=false] - only use the cache, skip network
+ * @returns {Promise<string>} cache directory containing the .inc file(s)
+ */
+async function fetchFungunDep(dep, noFetch = false) {
+  if (dep && typeof dep === 'object' && dep.id == null && dep.url == null) {
+    throw new Error(
+      `Fungun dep entry missing a plugin reference (expected "id" or "url"): ${JSON.stringify(dep)}`
+    );
+  }
+  const raw = (dep && dep.id != null) ? dep.id
+    : (dep && dep.url != null) ? dep.url
+    : dep;
+  const ref = parsePluginRef(raw);
+  if (!ref) {
+    throw new Error(
+      `Fungun dep entry missing a plugin reference (expected "id" or "url"): ${JSON.stringify(dep)}`
+    );
+  }
+
+  const cacheDir     = path.join(getCacheDir(), 'fungun', ref.id);
+  const sentinelFile = path.join(cacheDir, SENTINEL_FILE);
+
+  if (fs.existsSync(sentinelFile) && isFreshSentinel(sentinelFile)) {
+    logger.dim(`  fungun.net plugin #${ref.id} (cached)`);
+    return cacheDir;
+  }
+
+  const staleCache = fs.existsSync(sentinelFile);
+
+  if (noFetch) {
+    if (staleCache) {
+      // CI reuse: a day-old include is still a valid include.
+      logger.dim(`  fungun.net plugin #${ref.id} (cached, stale — --no-fetch)`);
+      return cacheDir;
+    }
+    throw new Error(
+      `Fungun dep cache missing for plugin #${ref.id} and --no-fetch is set.\n` +
+      `Run without --no-fetch to populate the cache.`
+    );
+  }
+
+  if (staleCache) {
+    logger.dim(`  fungun.net plugin #${ref.id}: cache expired, refetching...`);
+  }
+  logger.step(`Fungun dep: plugin #${ref.id} @ ${ref.url || pluginPageUrl(ref.id)}`);
+
+  try {
+    const html = await fetchFungunPage(ref);
+    const incs = extractIncFiles(html);
+
+    if (incs.length === 0) {
+      const pageUrl = ref.url || pluginPageUrl(ref.id);
+      const titles  = extractIncModals(html).map((m) => m.filename);
+      throw new Error(
+        `No .inc include found on fungun.net plugin page #${ref.id} (${pageUrl}).\n` +
+        `Shipped file modals: ${titles.length ? titles.join(', ') : 'none'} — this plugin exposes no include file.`
+      );
+    }
+
+    fs.mkdirSync(cacheDir, { recursive: true });
+    for (const inc of incs) {
+      fs.writeFileSync(path.join(cacheDir, safeFileName(inc.filename)), inc.content, 'utf8');
+    }
+    touchSentinel(sentinelFile, ref.id);
+
+    logger.info(`Fungun dep: plugin #${ref.id} ready (${incs.map((f) => f.filename).join(', ')})`);
+    return cacheDir;
+  } catch (err) {
+    if (staleCache) {
+      // Refetch failed but the previous copy is still on disk — keep the build
+      // green and reset freshness so we don't hammer the site on every build.
+      logger.warn(`Fungun dep: refetch of plugin #${ref.id} failed (${err.message}) — using cached copy`);
+      touchSentinel(sentinelFile, ref.id);
+      return cacheDir;
+    }
+    throw err;
+  }
+}
+
+function isFreshSentinel(sentinelFile) {
+  try {
+    return Date.now() - fs.statSync(sentinelFile).mtimeMs < FUNGUN_CACHE_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+function touchSentinel(sentinelFile, id) {
+  fs.mkdirSync(path.dirname(sentinelFile), { recursive: true });
+  const sentinelTmp = sentinelFile + '.tmp';
+  fs.writeFileSync(sentinelTmp, id, 'utf8');
+  fs.renameSync(sentinelTmp, sentinelFile);
+}
+
+function safeFileName(filename) {
+  const base = path.basename(String(filename || '').trim());
+  if (!base || base === '.' || base === '..') {
+    throw new Error(`Unsafe filename in fungun modal: ${JSON.stringify(filename)}`);
+  }
+  return base;
+}
+
+module.exports = {
+  FUNGUN_BASE_URL,
+  pluginPageUrl,
+  parsePluginRef,
+  fetchFungunPage,
+  extractIncModals,
+  extractIncFiles,
+  fetchFungunDep,
+};