amxx-builder 1.5.1

package/mcp/symbol-index.js

@@ -0,0 +1,171 @@
+'use strict';
+
+/**
+ * Symbol index for AMXX include/source files.
+ * Extracts declarations (native, stock, forward, public, #define, enum members,
+ * const, plain functions) for search_symbol.
+ *
+ * No caching: parsing the whole AMXX stdlib takes ~20ms, so the index is
+ * rebuilt on every call. Network fetches (clones, releases, compiler) have
+ * their own cache in src/.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const glob = require('fast-glob');
+
+const KEYWORDS = new Set([
+  'assert', 'break', 'case', 'continue', 'default', 'do', 'else', 'emit',
+  'exit', 'for', 'goto', 'if', 'new', 'return', 'sizeof', 'sleep', 'state',
+  'switch', 'typedef', 'while',
+]);
+
+function stripComments(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/\/\/[^\n]*/g, '');
+}
+
+function collectEnumMembers(chunk, lineNo, found) {
+  for (const item of chunk.split(',')) {
+    const m = item.match(/([A-Za-z_]\w*)/);
+    if (m) found.push({ name: m[1], kind: 'enum', line: lineNo, signature: 'enum member' });
+  }
+}
+
+/**
+ * Parse .sma/.inc source text into symbol declarations.
+ * Heuristic line-based parser covering AMXX declaration forms:
+ * tags (Float:), operator overloads, stacked modifiers (public stock const),
+ * functag, const arrays, multi-line enums.
+ */
+function parseInclude(text) {
+  const clean = stripComments(text);
+  const lines = clean.split('\n');
+  const found = [];
+  let inEnum = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const lineNo = i + 1;
+
+    if (inEnum) {
+      const closeIdx = raw.indexOf('}');
+      collectEnumMembers(closeIdx === -1 ? raw : raw.slice(0, closeIdx), lineNo, found);
+      if (closeIdx !== -1) inEnum = null;
+      continue;
+    }
+
+    // operator overloads: native Float:operator*(...) = floatmul;
+    let m = raw.match(/^\s*(native|stock|forward|public)\s+(?:const\s+)?(?:[A-Za-z_]\w*\s*:)?operator\s*([*+\-/%=!<>^&|~]+)/);
+    if (m) {
+      found.push({ name: 'operator' + m[2], kind: m[1], line: lineNo, signature: raw.trim() });
+      continue;
+    }
+
+    m = raw.match(/^\s*(native|forward|public)\s+(?:(?:const|stock)\s+)*(?:[A-Za-z_]\w*\s*:)?(\w+)/);
+    if (m) {
+      found.push({ name: m[2], kind: m[1], line: lineNo, signature: raw.trim() });
+      continue;
+    }
+
+    m = raw.match(/^\s*stock\s+(?:const\s+)?(?:[A-Za-z_]\w*\s*:)?(\w+)/);
+    if (m) {
+      const kind = /\(/.test(raw) ? 'stock' : 'stock const';
+      found.push({ name: m[1], kind, line: lineNo, signature: raw.trim() });
+      continue;
+    }
+
+    m = raw.match(/^\s*functag\s+(?:(?:public|native)\s+)?(\w+)/);
+    if (m) {
+      found.push({ name: m[1], kind: 'functag', line: lineNo, signature: raw.trim() });
+      continue;
+    }
+
+    m = raw.match(/^\s*#define\s+(\w+)/);
+    if (m) {
+      found.push({ name: m[1], kind: 'define', line: lineNo, signature: raw.trim() });
+      continue;
+    }
+
+    m = raw.match(/^\s*enum\s*(?:\(\s*[+\-*/=]+\s*\))?\s*(\w*)\s*\{/);
+    if (m) {
+      const name = m[1];
+      const rest = raw.slice(raw.indexOf('{') + 1);
+      const closeIdx = rest.indexOf('}');
+      if (name) found.push({ name, kind: 'enum', line: lineNo, signature: raw.trim() });
+      collectEnumMembers(closeIdx === -1 ? rest : rest.slice(0, closeIdx), lineNo, found);
+      if (closeIdx === -1) inEnum = { name, lineNo };
+      continue;
+    }
+
+    m = raw.match(/^\s*const\s+(\w+)(?:\[[^\]]*\])*\s*=/);
+    if (m) {
+      found.push({ name: m[1], kind: 'const', line: lineNo, signature: raw.trim() });
+      continue;
+    }
+
+    m = raw.match(/^([A-Za-z_]\w*(?:\s*:\s*[A-Za-z_]\w*)?)\s*\([^)]*\)\s*\{/);
+    if (m) {
+      const name = m[1].split(':').pop().trim();
+      if (name && !KEYWORDS.has(name)) {
+        found.push({ name, kind: 'function', line: lineNo, signature: raw.trim() });
+      }
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Scan dirs and build { symbols: Map<name, [{file, line, kind, signature}]>, fileCount }.
+ */
+async function buildIndex(dirs, pattern = '**/*.{inc,sma}') {
+  const symbolMap = new Map();
+  let fileCount = 0;
+
+  for (const dir of dirs) {
+    let files;
+    try {
+      files = await glob(pattern, { cwd: dir, dot: false });
+    } catch (_) {
+      continue;
+    }
+    for (const rel of files) {
+      fileCount++;
+      let text;
+      try {
+        text = fs.readFileSync(path.join(dir, rel), 'utf8');
+      } catch (_) {
+        continue;
+      }
+      for (const s of parseInclude(text)) {
+        const entry = { file: rel, line: s.line, kind: s.kind, signature: s.signature };
+        if (!symbolMap.has(s.name)) symbolMap.set(s.name, []);
+        symbolMap.get(s.name).push(entry);
+      }
+    }
+  }
+
+  return { symbols: symbolMap, fileCount };
+}
+
+/**
+ * Search an index for a symbol.
+ * Exact (case-sensitive) by default; `partial` does case-insensitive substring.
+ */
+function searchIndex(index, query, { partial = false } = {}) {
+  const results = [];
+  if (partial) {
+    const q = query.toLowerCase();
+    for (const [name, matches] of index.symbols) {
+      if (name.toLowerCase().includes(q)) results.push({ name, matches });
+    }
+  } else if (index.symbols.has(query)) {
+    results.push({ name: query, matches: index.symbols.get(query) });
+  }
+  results.sort((a, b) => a.name.localeCompare(b.name));
+  return results;
+}
+
+module.exports = { parseInclude, buildIndex, searchIndex };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "amxx-builder",
+  "version": "1.5.1",
+  "author": {
+    "name": "ArKaNeMaN"
+  },
+  "description": "CLI tool to build and package AMX Mod X server plugins",
+  "repository": {
+    "url": "git+https://github.com/AmxxModularEcosystem/amxx-builder.git"
+  },
+  "keywords": [
+    "amxx",
+    "amxmodx",
+    "cs",
+    "hlds",
+    "builder",
+    "amxx-builder",
+    "amxb",
+    "mcp",
+    "amxbuild",
+    "half-life"
+  ],
+  "main": "index.js",
+  "bin": {
+    "amxx-builder": "index.js",
+    "amxb": "index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test",
+    "bundle": "esbuild action-entry.js --bundle --platform=node --target=node24 --format=cjs --minify --legal-comments=inline --outfile=dist/index.js && node scripts/gen-licenses.js"
+  },
+  "dependencies": {
+    "@actions/core": "3.0.1",
+    "adm-zip": "^0.6.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "archiver": "^7.0.1",
+    "axios": "^1.7.2",
+    "chalk": "^4.1.2",
+    "chokidar": "^3.6.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^12.1.0",
+    "dotenv": "^17.4.2",
+    "enquirer": "^2.4.1",
+    "fast-glob": "^3.3.2",
+    "js-yaml": "^4.3.1",
+    "simple-git": "^3.22.0"
+  },
+  "files": [
+    "index.js",
+    "mcp/",
+    "src/",
+    "action.yml",
+    "action-entry.js",
+    "templates/",
+    "defaults/",
+    "package.json",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  }
+}

package/src/archiver.js

@@ -0,0 +1,140 @@
+const fs      = require('fs');
+const path    = require('path');
+const archiver = require('archiver');
+const logger  = require('./logger');
+const { createBar } = require('./progress');
+const { countFiles, copyDirContents } = require('./fs-utils');
+
+/**
+ * Creates the output .zip.
+ *
+ * {name} and {version} are expanded in amxmodx_path and assets_path.
+ *
+ *   build/amxmodx/**  → <amxmodx_path>/**   e.g. "addons/amxmodx" or "{name}/addons/amxmodx"
+ *   build/assets/**   → <assets_path>/**     e.g. "" (root) or "{name}"
+ *   README.md         → <assets_path>/       if output.readme = true
+ */
+async function createArchive(manifest, buildDir) {
+  const out = manifest.output;
+
+  const expand = (tpl) => tpl
+    .replaceAll('{name}',    manifest.name)
+    .replaceAll('{version}', manifest.version);
+
+  const archiveName  = sanitizeArchiveName(expand(out.archive_name));
+  const amxmodxDest  = expand(out.amxmodx_path).replace(/\/?$/, '/');
+  const assetsDest   = expand(out.assets_path);  // '' = root
+
+  fs.mkdirSync(path.resolve(out.dir), { recursive: true });
+  const archivePath = path.join(path.resolve(out.dir), archiveName);
+
+  const output  = fs.createWriteStream(archivePath);
+  const archive = archiver('zip', { zlib: { level: 9 } });
+
+  const fileList = [];
+
+  // Count files for progress bar
+  const amxmodxBuildDir = path.join(buildDir, 'amxmodx');
+  const assetsBuildDir  = path.join(buildDir, 'assets');
+  let totalFiles = 0;
+  if (fs.existsSync(amxmodxBuildDir)) totalFiles += countFiles(amxmodxBuildDir);
+  if (fs.existsSync(assetsBuildDir))  totalFiles += countFiles(assetsBuildDir);
+  if (out.readme && fs.existsSync(path.join(path.dirname(manifest._path), 'README.md'))) totalFiles++;
+
+  const bar = createBar(totalFiles || 1, '  Archiving files');
+  let archivedCount = 0;
+
+  archive.on('entry', (entry) => {
+    if (!entry.stats || !entry.stats.isDirectory()) {
+      fileList.push(entry.name);
+      archivedCount++;
+      if (bar) bar.update(archivedCount);
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    output.on('close', () => { if (bar) bar.stop(); resolve(); });
+    archive.on('error', reject);
+    archive.pipe(output);
+
+    if (fs.existsSync(amxmodxBuildDir)) {
+      archive.directory(amxmodxBuildDir + path.sep, amxmodxDest);
+    }
+
+    if (fs.existsSync(assetsBuildDir)) {
+      archive.directory(assetsBuildDir + path.sep, assetsDest || false);
+    }
+
+    if (out.readme) {
+      const readmeSrc = path.join(path.dirname(manifest._path), 'README.md');
+      if (fs.existsSync(readmeSrc)) {
+        archive.file(readmeSrc, { name: 'README.md' });
+      } else {
+        logger.warn('readme: true but README.md not found next to manifest');
+      }
+    }
+
+    archive.finalize();
+  });
+
+  const sizeKb = Math.round(fs.statSync(archivePath).size / 1024);
+  logger.success(`Archive: ${path.join(out.dir, archiveName)} (${sizeKb} KB)`);
+  printFileListing(fileList);
+}
+
+// Keeps the archive filename inside out.dir: strips any directory components
+// (both / and \ separators) and removes characters illegal on Windows.
+function sanitizeArchiveName(name) {
+  const base = String(name).replace(/\\/g, '/').split('/').pop() || '';
+  if (!base || base === '.' || base === '..') return 'archive.zip';
+  return base.replace(/[<>:"|?*]/g, '_');
+}
+
+function printFileListing(files) {  const grouped = new Map();
+  for (const f of files) {
+    const parts = f.split('/');
+    const key   = parts.length > 1 ? parts.slice(0, parts.length - 1).join('/') : '.';
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key).push(f);
+  }
+  for (const [dir, dirFiles] of grouped) {
+    if (dirFiles.length === 1) logger.dim(`  ${dirFiles[0]}`);
+    else                       logger.dim(`  ${dir}/ (${dirFiles.length} files)`);
+  }
+}
+
+/**
+ * Same layout as createArchive but copies files to output.dir instead of zipping.
+ * Used when output.pack = false (e.g. in CI to avoid artifact double-wrapping).
+ */
+function copyOutput(manifest, buildDir) {
+  const out    = manifest.output;
+  const expand = (tpl) => tpl
+    .replaceAll('{name}',    manifest.name)
+    .replaceAll('{version}', manifest.version);
+
+  const outDir     = path.resolve(out.dir);
+  const amxmodxDst = path.join(outDir, expand(out.amxmodx_path));
+  const assetsDst  = out.assets_path
+    ? path.join(outDir, expand(out.assets_path))
+    : outDir;
+
+  const amxmodxSrc = path.join(buildDir, 'amxmodx');
+  if (fs.existsSync(amxmodxSrc)) copyDirContents(amxmodxSrc, amxmodxDst);
+
+  const assetsSrc = path.join(buildDir, 'assets');
+  if (fs.existsSync(assetsSrc)) copyDirContents(assetsSrc, assetsDst);
+
+  if (out.readme) {
+    const readmeSrc = path.join(path.dirname(manifest._path), 'README.md');
+    if (fs.existsSync(readmeSrc)) {
+      fs.copyFileSync(readmeSrc, path.join(outDir, 'README.md'));
+    } else {
+      logger.warn('readme: true but README.md not found next to manifest');
+    }
+  }
+
+  logger.success(`Output dir: ${out.dir}`);
+}
+
+module.exports = { createArchive, copyOutput };

package/src/asset-fetcher.js

@@ -0,0 +1,277 @@
+'use strict';
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+const axios  = require('axios');
+// Default for API calls; download sites pass their own longer timeout.
+axios.defaults.timeout = 30000;
+const AdmZip = require('adm-zip');
+
+const chalk = require('chalk');
+const { safeExtractTar } = require('./fs-utils');
+const logger = require('./logger');
+const { getCacheDir }        = require('./cache-dir');
+const { withRetry }          = require('./retry');
+const { getAmxmodxFullDir, getHostPlatform } = require('./compiler-fetcher');
+const { getReleaseCacheDir } = require('./release-fetcher');
+const { resolveGithubToken } = require('./manifest');
+
+/**
+ * Processes all asset sources defined in manifest.assets.sources in order.
+ * Sources are written directly to build/assets/ with on_conflict resolution.
+ * source: local copies from assets/ next to the manifest.
+ */
+async function fetchAssets(manifest, buildDir, noFetch = false) {
+  const { sources, on_conflict } = manifest.assets;
+  if (!sources.length) return;
+
+  const manifestDir = path.dirname(manifest._path);
+  const assetsDir   = path.join(buildDir, 'assets');
+
+  fs.mkdirSync(assetsDir, { recursive: true });
+
+  logger.info(`Assets: processing ${sources.length} source(s)...`);
+
+  const origins = new Map(); // relPath → source label (for conflict tracking)
+
+  // Resolve all sources in parallel (network-bound: release, url), apply maps sequentially
+  const resolved = await Promise.all(
+    sources.map(src => resolveSource(src, manifest, manifestDir, buildDir, noFetch))
+  );
+  for (let i = 0; i < sources.length; i++) {
+    const srcDir = resolved[i];
+    if (!srcDir) continue;
+    applyMap(srcDir, assetsDir, sources[i].map, sourceLabel(sources[i]), on_conflict, origins);
+  }
+}
+
+function sourceLabel(source) {
+  if (source.type === 'local')   return 'local';
+  if (source.type === 'amxmodx') return 'amxmodx';
+  if (source.type === 'release') return `${source.repo}@${source.ref}`;
+  return source.url;
+}
+
+// ─── source resolution ────────────────────────────────────────────────────────
+
+async function resolveSource(source, manifest, manifestDir, buildDir, noFetch) {
+  if (source.type === 'local') {
+    const localAssetsDir = path.join(manifestDir, 'assets');
+    if (!fs.existsSync(localAssetsDir)) return null;
+    logger.dim(`  local assets/`);
+    return localAssetsDir;
+  }
+  if (source.type === 'amxmodx') {
+    const version  = manifest.amxmodx.version;
+    const platform = manifest.platform || getHostPlatform();
+    if (!version) throw new Error('assets: source: amxmodx requires amxmodx.version to be set');
+    logger.step(`Assets: amxmodx ${version} (${platform})...`);
+    return getAmxmodxFullDir(version, platform);
+  }
+  if (source.type === 'release') {
+    return getReleaseCacheDir(source, resolveGithubToken(manifest, source.repo), noFetch);
+  }
+  return resolveUrlSource(source, manifestDir, buildDir, noFetch);
+}
+
+async function resolveUrlSource(source, manifestDir, buildDir, noFetch) {
+  const cacheDir = getCacheDirForUrl(source.url, source.cache, manifestDir, buildDir);
+  const sentinel = path.join(cacheDir, '.cached');
+
+  if (fs.existsSync(sentinel)) {
+    logger.dim(`  ${source.url} (cached)`);
+    return cacheDir;
+  }
+
+  if (noFetch) {
+    logger.warn(`Assets: skipping ${source.url} (--no-fetch, cache: none)`);
+    return null;
+  }
+
+  const filename = getFilenameFromUrl(source.url);
+  logger.step(`Assets: downloading ${filename}...`);
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const bar = require('./progress').createBar(100, `  ${chalk.cyan('Downloading')} ${(filename || 'file').padEnd(30)}`);
+
+  try {
+    const response    = await withRetry(
+      () => axios.get(source.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 contentType = response.headers['content-type'] || '';
+    const data        = Buffer.from(response.data);
+
+    if (isArchive(filename, contentType)) {
+      extractArchive(data, filename, cacheDir);
+    } else {
+      const filePath = path.join(cacheDir, filename);
+      const part     = filePath + '.part';
+      fs.writeFileSync(part, data);
+      fs.renameSync(part, filePath);
+    }
+
+    const sentinelTmp = sentinel + '.tmp';
+    fs.writeFileSync(sentinelTmp, JSON.stringify({ url: source.url, cached_at: new Date().toISOString() }));
+    fs.renameSync(sentinelTmp, sentinel);
+    logger.info(`Assets: ${filename} ready`);
+    return cacheDir;
+  } catch (err) {
+    // Never rmSync the whole cache dir: it may be a shared 'global' entry used
+    // by parallel sources or other projects. Invalidate the sentinel only and
+    // leave the content to be overwritten on the next fetch.
+    try { fs.rmSync(sentinel, { force: true }); } catch (_) {}
+    throw new Error(`Failed to fetch asset ${source.url}: ${err.message}`);
+  }
+}
+
+function getCacheDirForUrl(url, cacheType, manifestDir, buildDir) {
+  const hash = crypto.createHash('sha256').update(url).digest('hex').slice(0, 16);
+  if (cacheType === 'global') return path.join(getCacheDir(), 'assets', hash);
+  if (cacheType === 'local')  return path.join(manifestDir, '.amxb-cache', 'assets', hash);
+  return path.join(buildDir, '_assets_dl', hash); // 'none'
+}
+
+// ─── archive detection & extraction ──────────────────────────────────────────
+
+function getFilenameFromUrl(url) {
+  try {
+    const base = path.basename(new URL(url).pathname) || 'download';
+    try { return decodeURIComponent(base); } catch { return base; }
+  } catch { return 'download'; }
+}
+
+function isArchive(filename, contentType) {
+  if (/\.(zip|tar\.gz|tgz|tar\.bz2)$/i.test(filename)) return true;
+  return /zip|tar|gzip|x-compressed/.test(contentType);
+}
+
+function extractArchive(data, filename, destDir) {
+  const isZip = /\.zip$/i.test(filename) || isZipMagic(data);
+  if (isZip) {
+    new AdmZip(data).extractAllTo(destDir, true);
+    return;
+  }
+  const tmpFile = path.join(destDir, filename);
+  fs.writeFileSync(tmpFile, data);
+  try {
+    safeExtractTar(tmpFile, destDir);
+  } finally {
+    fs.rmSync(tmpFile, { force: true });
+  }
+}
+
+// ZIP archives start with "PK" — filename extensions are unreliable for
+// CDN/redirect URLs, so sniff the actual bytes when the name is inconclusive.
+function isZipMagic(buf) {
+  return buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b;
+}
+
+// ─── map application ──────────────────────────────────────────────────────────
+
+function applyMap(srcDir, destDir, mapEntries, label, onConflict, origins) {
+  for (const entry of mapEntries) {
+    applyMapEntry(srcDir, destDir, entry, label, onConflict, origins);
+  }
+}
+
+/**
+ * Trailing-slash semantics (rsync-style):
+ *
+ *   from: null        → take entire srcDir contents
+ *   from: "models/"   → take contents of srcDir/models/
+ *   from: "models"    → take srcDir/models itself (dir placed as destDir/models/)
+ *   from: "a/b.wav"   → take single file srcDir/a/b.wav
+ *
+ *   to: null          → place into destDir root
+ *   to: "models/"     → place into destDir/models/
+ *   to: "models"      → same as "models/" for dirs; for single file, rename to "models"
+ */
+function applyMapEntry(baseDir, destBase, { from, to }, label, onConflict, origins) {
+  const fromTrailing = from && from.endsWith('/');
+  const fromRel      = from ? from.replace(/\/$/, '') : null;
+  const fromPath     = fromRel ? path.join(baseDir, fromRel) : baseDir;
+
+  if (!fs.existsSync(fromPath)) {
+    logger.warn(`Assets: path not found in source: ${from || '(root)'}`);
+    return;
+  }
+
+  const toRel      = to ? to.replace(/\/$/, '') : null;
+  const toTrailing = !to || to.endsWith('/');
+  const destPath   = toRel ? path.join(destBase, toRel) : destBase;
+
+  const stat = fs.statSync(fromPath);
+
+  if (!fromRel || fromTrailing || stat.isDirectory()) {
+    // Copy directory contents or the directory itself
+    const contentsOnly = !fromRel || fromTrailing;
+    const actualDest   = contentsOnly ? destPath : path.join(destPath, path.basename(fromPath));
+    copyDirWithConflict(fromPath, actualDest, destBase, label, onConflict, origins);
+  } else {
+    // Single file
+    const fileDest = toTrailing
+      ? path.join(destPath, path.basename(fromPath))
+      : destPath; // no trailing slash on to → rename
+
+    const relKey = path.relative(destBase, fileDest).replace(/\\/g, '/');
+    if (origins.has(relKey)) {
+      const prev = origins.get(relKey);
+      if (onConflict === 'error') {
+        throw new Error(`Asset conflict: "${relKey}" — provided by both "${prev}" and "${label}"`);
+      }
+      if (onConflict === 'first_wins') {
+        logger.warn(`Asset conflict (kept "${prev}"): ${relKey}`);
+        return;
+      }
+      logger.warn(`Asset conflict (overwriting "${prev}"): ${relKey}`);
+    }
+    fs.mkdirSync(path.dirname(fileDest), { recursive: true });
+    fs.copyFileSync(fromPath, fileDest);
+    origins.set(relKey, label);
+  }
+}
+
+function copyDirWithConflict(srcDir, destDir, trackBase, label, onConflict, origins) {
+  if (!fs.existsSync(srcDir)) return;
+  fs.mkdirSync(destDir, { recursive: true });
+
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath  = path.join(srcDir,  entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirWithConflict(srcPath, destPath, trackBase, label, onConflict, origins);
+    } else {
+      const relKey = path.relative(trackBase, destPath).replace(/\\/g, '/');
+      if (origins.has(relKey)) {
+        const prev = origins.get(relKey);
+        if (onConflict === 'error') {
+          throw new Error(`Asset conflict: "${relKey}" — provided by both "${prev}" and "${label}"`);
+        }
+        if (onConflict === 'first_wins') {
+          logger.warn(`Asset conflict (kept "${prev}"): ${relKey}`);
+          continue;
+        }
+        logger.warn(`Asset conflict (overwriting "${prev}"): ${relKey}`);
+      }
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+      origins.set(relKey, label);
+    }
+  }
+}
+
+
+module.exports = { fetchAssets };