amxx-builder 1.6.0 → 1.7.0

package/src/asset-fetcher.js

@@ -3,16 +3,13 @@
 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 { safeExtractTar, makeSiblingTmpDir, publishDir } = require('./fs-utils');
+const { downloadToFile } = require('./download');
 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');
@@ -91,47 +88,34 @@ async function resolveUrlSource(source, manifestDir, buildDir, noFetch) {
 
   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)}`);
 
+  // Download + extract into a unique sibling temp dir, then rename into place:
+  // an interrupted run leaves only the temp dir (never a sentinel-marked cache)
+  // and concurrent fetches of the same URL cannot interleave writes.
+  const tmpDir = makeSiblingTmpDir(cacheDir);
   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);
+    const downloadPath = path.join(tmpDir, filename);
+    const { headers } = await downloadToFile(source.url, downloadPath, {
+      progressLabel: `  ${chalk.cyan('Downloading')} ${(filename || 'file').padEnd(30)}`,
+    });
+    const contentType = headers['content-type'] || '';
 
     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);
+      extractArchiveFile(downloadPath, tmpDir);
     }
 
-    const sentinelTmp = sentinel + '.tmp';
+    // Sentinel written into tmpDir first: only complete dirs become the cache.
+    const sentinelTmp = path.join(tmpDir, '.cached.tmp');
     fs.writeFileSync(sentinelTmp, JSON.stringify({ url: source.url, cached_at: new Date().toISOString() }));
-    fs.renameSync(sentinelTmp, sentinel);
+    fs.renameSync(sentinelTmp, path.join(tmpDir, '.cached'));
+    publishDir(tmpDir, cacheDir, () => fs.existsSync(sentinel));
     logger.info(`Assets: ${filename} ready`);
     return cacheDir;
   } catch (err) {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
     // 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 (_) {}
+    // by parallel sources or other projects. Only the unique temp dir above is
+    // ours to remove; a stale marker-less cache dir is replaced on next fetch.
     throw new Error(`Failed to fetch asset ${source.url}: ${err.message}`);
   }
 }
@@ -157,25 +141,26 @@ function isArchive(filename, contentType) {
   return /zip|tar|gzip|x-compressed/.test(contentType);
 }
 
-function extractArchive(data, filename, destDir) {
-  const isZip = /\.zip$/i.test(filename) || isZipMagic(data);
+function extractArchiveFile(archivePath, destDir) {
+  const isZip = /\.zip$/i.test(archivePath) || isZipMagicFile(archivePath);
   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 });
+    new AdmZip(archivePath).extractAllTo(destDir, true);
+  } else {
+    safeExtractTar(archivePath, destDir);
   }
+  fs.rmSync(archivePath, { 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;
+function isZipMagicFile(filePath) {
+  try {
+    const fd  = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(2);
+    fs.readSync(fd, buf, 0, 2, 0);
+    fs.closeSync(fd);
+    return buf[0] === 0x50 && buf[1] === 0x4b;
+  } catch { return false; }
 }
 
 // ─── map application ──────────────────────────────────────────────────────────

package/src/build-plan.js

@@ -3,6 +3,7 @@
 const fs   = require('fs');
 const path = require('path');
 const glob = require('fast-glob');
+const { isLocal } = require('./local-sources');
 
 /**
  * Structured build plan — mirrors what printDryRun shows, but as data.
@@ -35,18 +36,23 @@ function buildPlanData(manifest, options = {}) {
     },
     repos: manifest.repos.map((r) => ({
       repo: r.repo,
-      ref: r.ref || 'default branch',
+      source: isLocal(r) ? 'local' : (r.source || 'git'),
+      ref: isLocal(r) ? null : (r.ref || 'default branch'),
       amxmodx_dir: r.amxmodx_dir,
       deps_override: r.deps_override || null,
+      local_dir: r._localDir || null,
+      ...(r.ref_ttl !== undefined ? { ref_ttl: r.ref_ttl } : {}),
     })),
     globalDeps: manifest.globalDeps.map((d) => ({
-      source: d.source,
-      repo: d.source === 'fungun' ? null : d.repo,
-      ref: d.ref,
+      source: isLocal(d) ? 'local' : d.source,
+      repo: isLocal(d) ? d.repo : (d.source === 'fungun' ? null : d.repo),
+      ref: isLocal(d) ? null : d.ref,
       id: d.id ?? null,
       url: d.url ?? null,
       include_path: d.include_path || null,
       asset: d.asset ?? null,
+      local_dir: d._localDir || null,
+      ...(d.ref_ttl !== undefined ? { ref_ttl: d.ref_ttl } : {}),
     })),
     assets: manifest.assets.sources.map((s) => {
       if (detailed) {
@@ -94,7 +100,18 @@ function buildPlanData(manifest, options = {}) {
         : path.join(path.resolve(out.dir), expand(out.archive_name)),
       amxmodx_path: expand(out.amxmodx_path) + '/',
       assets_path: out.assets_path ? expand(out.assets_path) + '/' : null,
-      generate_ini: out.generate_ini,
+      // `pluginIni` is the resolved source of truth; hand-built fixtures
+      // (tests, external callers) may not carry it → fall back to the legacy
+      // raw output flag.
+      generate_ini: manifest.pluginIni ? manifest.pluginIni.enabled : Boolean(out.generate_ini),
+      plugins_ini: manifest.pluginIni
+        ? {
+            enabled: manifest.pluginIni.enabled,
+            default: manifest.pluginIni.defaultIni,
+            debug: manifest.pluginIni.defaultDebug,
+            force_debug: manifest.pluginIni.forceDebug,
+          }
+        : null,
       on_conflict: out.on_conflict,
     },
   };

package/src/build-service.js

@@ -37,14 +37,40 @@ const logger = require('./logger');
 const { emit, EVENTS } = require('./events');
 const { resolveGithubToken } = require('./manifest');
 const { fetchCompiler }  = require('./compiler-fetcher');
-const { fetchRepo, resolveRepoRefs } = require('./repo-fetcher');
-const { resolveDeps, repoKey } = require('./deps-resolver');
+const { resolveRepoRefs } = require('./repo-fetcher');
+const { ensureRepoDir }   = require('./local-sources');
+const { resolveDeps, repoKey, normalizeRepo } = require('./deps-resolver');
 const { compilePlugins } = require('./compiler');
 const { collectAll }     = require('./collector');
 const { fetchAssets }    = require('./asset-fetcher');
 const { buildIniFiles }  = require('./ini-builder');
 const { createArchive, copyOutput } = require('./archiver');
 
+// Legacy manifest knobs (output.generate_ini, *.plugins_ini_postfix) still work
+// but warn. Watch/serve call runBuild repeatedly with the same manifest, so the
+// same warning is emitted only once per process to avoid rebuild-time noise.
+const loggedDeprecations = new Set();
+
+function logDeprecations(manifest) {
+  for (const message of manifest._deprecations || []) {
+    if (loggedDeprecations.has(message)) continue;
+    loggedDeprecations.add(message);
+    logger.warn(message);
+  }
+}
+
+// Same once-per-process dedupe as logDeprecations: watch/serve rebuild often.
+const loggedForcedDebug = new Set();
+
+function logForcedDebug(manifest) {
+  const forceDebug = manifest.pluginIni ? manifest.pluginIni.forceDebug : null;
+  if (forceDebug == null) return;
+  const message = `AMXB_PLUGINS_DEBUG — plugin debug forced ${forceDebug ? 'on' : 'off'} for this build`;
+  if (loggedForcedDebug.has(message)) return;
+  loggedForcedDebug.add(message);
+  logger.dim(message);
+}
+
 /**
  * Run the full build pipeline for an already-resolved manifest.
  *
@@ -86,6 +112,9 @@ async function runBuild(manifest, options = {}) {
     } catch (_) { /* no subscriber — keep the original error surface */ }
   };
 
+  logDeprecations(manifest);
+  logForcedDebug(manifest);
+
   // Cancellation is checked between stages. Compilation itself is atomic per
   // plugin and runs to completion — cancellation only takes effect at the next
   // stage boundary (documented in the module docstring).
@@ -118,19 +147,32 @@ async function runBuild(manifest, options = {}) {
       await resolveRepoRefs(manifest.repos, (repo) => resolveGithubToken(manifest, repo));
       checkCancelled();
 
-      const cloneJobs = new Map();
+      const cloneJobs = new Map(); // normalized repo identity → fetch promise
       for (const repoConfig of manifest.repos) {
-        const key = repoKey(repoConfig);
-        if (!cloneJobs.has(key)) {
-          cloneJobs.set(key,
-            fetchRepo(repoConfig.repo, repoConfig._resolvedRef, resolveGithubToken(manifest, repoConfig.repo), noFetch, manifest.github.ssh)
+        const identity = normalizeRepo(repoConfig);
+        if (!cloneJobs.has(identity)) {
+          // ensureRepoDir returns `_localDir` for local entries (never fetches).
+          cloneJobs.set(identity,
+            ensureRepoDir(repoConfig, {
+              token: resolveGithubToken(manifest, repoConfig.repo),
+              noFetch,
+              ssh: manifest.github.ssh,
+            })
           );
         }
       }
-      const cloned = await Promise.all(
-        [...cloneJobs.entries()].map(async ([key, p]) => ({ key, dir: await p }))
+      const cloned = new Map();
+      await Promise.all(
+        [...cloneJobs.entries()].map(async ([identity, p]) => {
+          const dir = await p;
+          cloned.set(identity, dir);
+        })
       );
-      for (const { key, dir } of cloned) repoLocalDirs[key] = dir;
+      // Map every manifest entry (raw spelling) to its clone dir; duplicate
+      // spellings of the same repo share the clone but each repoKey stays valid.
+      for (const repoConfig of manifest.repos) {
+        repoLocalDirs[repoKey(repoConfig)] = cloned.get(normalizeRepo(repoConfig));
+      }
       checkCancelled();
     }
 
@@ -156,7 +198,7 @@ async function runBuild(manifest, options = {}) {
     );
 
     // ── 7. Generate plugins-*.ini ───────────────────────────────────────────
-    if (manifest.output.generate_ini) {
+    if (manifest.pluginIni.enabled) {
       emitEvent(EVENTS.STAGE, { stage: 'ini', message: 'Generating plugins ini files' });
       buildIniFiles(compiledPlugins, buildDir);
     }
@@ -166,6 +208,7 @@ async function runBuild(manifest, options = {}) {
     if (noArchive) {
       logger.info('--no-archive: skipping zip creation');
       const elapsed = ((Date.now() - buildStart) / 1000).toFixed(1);
+      emitEvent(EVENTS.DONE, { ok: true, elapsed, noArchive: true, message: `Done in ${elapsed}s` });
       return { ok: true, elapsed, noArchive: true };
     }
 

package/src/cli.js

@@ -19,6 +19,8 @@ const { runReleases }         = require('./commands/releases');
 const { runInit, runInitInteractive } = require('./commands/init');
 const { runMcp }                     = require('./commands/mcp');
 const { runServe }                   = require('./commands/serve');
+const { runSkillsDir }               = require('./commands/skills-dir');
+const { runOpencodeSkills }          = require('./commands/opencode-skills');
 
 program
   .name('amxx-builder')
@@ -28,9 +30,13 @@ program
 // ─── Update check ──────────────────────────────────────────────────────────────
 
 program.hook('preAction', async () => {
-  // The MCP server and the serve JSON-RPC server own stdout; an update notice
-  // would corrupt the protocol stream.
-  if (program.args[0] === 'mcp' || program.args[0] === 'serve') return;
+  // The MCP server, the serve JSON-RPC server, skills-dir and opencode-skills
+  // own stdout; an update notice would corrupt the protocol/parseable stream.
+  // The GitHub Action already pins a version and shouldn't make an extra
+  // network call.
+  if (program.args[0] === 'mcp' || program.args[0] === 'serve'
+    || program.args[0] === 'skills-dir' || program.args[0] === 'opencode-skills') return;
+  if (process.env.GITHUB_ACTIONS === 'true') return;
   try {
     const latest = await checkForUpdate();
     if (latest) {
@@ -245,10 +251,13 @@ program
   .option('--ci',           'Alias for --workflow')
   .option('--plugin <name>', 'Create amxmodx/scripting/<name>.sma')
   .option('--gitignore',     'Create .gitignore')
-  .option('--opencode',      'Create .opencode/opencode.json with MCP config (amxb mcp)')
+  .option('--opencode',      'Create .opencode/opencode.json (MCP config) + skills bridge plugin (amxb mcp)')
   .option('--deploy',        'Create .env with deploy stubs (AMXB_DEPLOY_*)')
   .option('--script',        'Create build.bat and build.sh quick-build scripts')
+  .option('--vscode',        'Create .vscode/extensions.json with recommended extensions')
+  .option('--vsc',           'Alias for --vscode')
   .option('-f, --force',     'Overwrite existing files instead of skipping them')
+  .option('--with-manifest', 'With --force, also overwrite an existing amxbuild.yml')
   .option('-i, --interactive', 'Interactive mode with prompts')
   .action(async (options) => {
     try {
@@ -291,6 +300,31 @@ program
     }
   });
 
+// ─── skills-dir ────────────────────────────────────────────────────────────────
+
+program
+  .command('skills-dir')
+  .description('Print the absolute path to the bundled skills directory (used by the opencode skills bridge plugin)')
+  .action(() => {
+    runSkillsDir();
+  });
+
+// ─── opencode-skills ─────────────────────────────────────────────────────────
+
+program
+  .command('opencode-skills')
+  .description('Materialize project + dependency skills for the opencode bridge (stdout: container paths)')
+  .option('--manifest <path>', 'Path to manifest file')
+  .option('--no-fetch',        'Use cached repos without re-cloning')
+  .action(async (options) => {
+    try {
+      await runOpencodeSkills(options);
+    } catch (err) {
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
 // ─── version ───────────────────────────────────────────────────────────────────
 
 program

package/src/collector.js

@@ -2,7 +2,7 @@ const fs   = require('fs');
 const path = require('path');
 const glob = require('fast-glob');
 const logger = require('./logger');
-const { repoKey } = require('./deps-resolver');
+const { repoKey, normalizeRepo } = require('./deps-resolver');
 
 /**
  * Copies everything from each repo's amxmodx_dir into build/amxmodx/,
@@ -25,9 +25,17 @@ async function collectAll(manifest, repoLocalDirs, buildDir) {
   fs.mkdirSync(amxmodxBuildDir, { recursive: true });
 
   const origins = new Map(); // rel path → repo label (conflict tracking)
+  const seenRepos = new Set(); // case-insensitive repo identity (dedupe)
 
   // Copy from each remote repo
   for (const repoConfig of manifest.repos) {
+    const repoIdentity = normalizeRepo(repoConfig);
+    if (seenRepos.has(repoIdentity)) {
+      logger.dim(`  ${repoConfig.repo}: duplicate entry, skipping`);
+      continue;
+    }
+    seenRepos.add(repoIdentity);
+
     const repoDir = repoLocalDirs[repoKey(repoConfig)];
     const srcDir  = path.join(repoDir, repoConfig.amxmodx_dir);
 

package/src/commands/build.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const logger = require('../logger');
-const { parseManifest, applyOverrides } = require('../manifest');
+const { resolveManifest } = require('../manifest');
 const { resolveManifestPath, loadEnv } = require('./shared');
 const { printDryRun } = require('./dry-run');
 const { subscribeCompiledRendering } = require('./compile-renderer');
@@ -29,9 +29,10 @@ async function runBuildCLI(options) {
   const manifestPath = resolveManifestPath(options.manifest);
   loadEnv(manifestPath);
 
-  const manifest = parseManifest(manifestPath);
-  if (options.set?.length)    applyOverrides(manifest, options.set);
-  if (options.define?.length) manifest.amxmodx.defines.push(...options.define);
+  const manifest = resolveManifest(manifestPath, {
+    set:    options.set,
+    define: options.define,
+  });
   logger.info(`Manifest: ${manifest.name} v${manifest.version}`);
 
   if (options.dryRun) {

package/src/commands/dry-run.js

@@ -3,6 +3,7 @@
 const path = require('path');
 const logger = require('../logger');
 const { buildPlanData } = require('../build-plan');
+const { isLocal } = require('../local-sources');
 
 function printDryRun(manifest) {
   const out = manifest.output;
@@ -20,6 +21,10 @@ function printDryRun(manifest) {
   if (manifest.repos.length) {
     logger.info(`\nRepos (${manifest.repos.length}):`);
     for (const r of manifest.repos) {
+      if (isLocal(r)) {
+        logger.dim(`  [local] ${r.repo} -> ${r._localDir}  [dir: ${r.amxmodx_dir}]`);
+        continue;
+      }
       const ref = r.ref || 'default branch';
       logger.dim(`  ${r.repo} @ ${ref}  [dir: ${r.amxmodx_dir}]`);
     }
@@ -28,6 +33,10 @@ function printDryRun(manifest) {
   if (manifest.globalDeps.length) {
     logger.info(`\nGlobal deps (${manifest.globalDeps.length}):`);
     for (const d of manifest.globalDeps) {
+      if (isLocal(d)) {
+        logger.dim(`  [local] ${d.repo} -> ${d._localDir}${d.include_path ? ':' + d.include_path : ''}`);
+        continue;
+      }
       if (d.source === 'fungun') {
         logger.dim(`  [fungun] plugin #${d.id}  (${d.url})`);
         continue;
@@ -60,7 +69,25 @@ function printDryRun(manifest) {
     logger.dim(`  amxmodx path in archive: ${expand(out.amxmodx_path)}/`);
   }
   if (out.assets_path) logger.dim(`  assets path: ${expand(out.assets_path)}/`);
-  logger.dim(`  generate_ini: ${out.generate_ini}  |  on_conflict: ${out.on_conflict}`);
+
+  if (manifest.pluginIni) {
+    const { enabled, defaultIni, defaultDebug, forceDebug } = manifest.pluginIni;
+    const base = defaultIni === false
+      ? 'none'
+      : (defaultIni === '' ? 'plugins.ini' : `plugins-${defaultIni}.ini`);
+    const debug = forceDebug != null
+      ? `${forceDebug} (forced by AMXB_PLUGINS_DEBUG)`
+      : defaultDebug;
+    logger.dim(`  plugins ini: ${enabled ? 'enabled' : 'disabled'}  |  default: ${base}  |  debug: ${debug}`);
+    logger.dim(`  on_conflict: ${out.on_conflict}`);
+  } else {
+    logger.dim(`  generate_ini: ${out.generate_ini}  |  on_conflict: ${out.on_conflict}`);
+  }
+
+  if (manifest._deprecations && manifest._deprecations.length) {
+    logger.info(`\nDeprecations (${manifest._deprecations.length}):`);
+    for (const d of manifest._deprecations) logger.warn(`  ${d}`);
+  }
 
   logger.info(`\n=== END DRY RUN ===`);
 }