amxx-builder 1.5.2 → 1.6.1

package/src/agent-assets.js

@@ -0,0 +1,206 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const glob = require('fast-glob');
+const yaml = require('js-yaml');
+
+const { fetchDepRoot }  = require('./deps-resolver');
+const { parseDocEntries, parseSkillEntries } = require('./manifest');
+const { findManifestInDir } = require('./manifest-path');
+
+/**
+ * UTF-8 read that never throws. Binary files (NUL byte) 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);
+    const text = buf.toString('utf8');
+    if (text.includes('\u0000')) return `[binary file, ${buf.length} bytes]`;
+    return text;
+  } catch (err) {
+    return `[error reading file: ${err.message}]`;
+  }
+}
+
+/**
+ * Resolve a repo-relative path against the repo root, rejecting traversal.
+ *
+ * @param {string} rootDir - repo root (absolute)
+ * @param {string} rel - declared relative path
+ * @returns {string} absolute path
+ */
+function safeResolve(rootDir, rel) {
+  const abs = path.resolve(rootDir, rel);
+  if (abs !== rootDir && !abs.startsWith(rootDir + path.sep)) {
+    throw new Error(`docs path escapes the repo root: "${rel}"`);
+  }
+  return abs;
+}
+
+function sortBundleFiles(files) {
+  return files.sort((a, b) => {
+    if (a === 'SKILL.md') return b === 'SKILL.md' ? 0 : -1;
+    if (b === 'SKILL.md') return 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+  });
+}
+
+/**
+ * Resolve declared docs/skills against a repo root without reading content.
+ *
+ * Docs and single-file skills that do not exist land in `missing` (no throw);
+ * directory skills are enumerated recursively (SKILL.md first). Paths that
+ * escape rootDir throw.
+ *
+ * @param {{ docs?: Array<object>, skills?: Array<object> }} assets
+ * @param {string} rootDir - absolute repo root
+ * @returns {{ docs: Array<object>, skills: Array<object>, missing: string[] }}
+ */
+function resolveAssets({ docs, skills }, rootDir) {
+  const docInputs   = Array.isArray(docs) ? docs : [];
+  const skillInputs = Array.isArray(skills) ? skills : [];
+  const outDocs     = [];
+  const outSkills   = [];
+  const missing     = [];
+
+  for (const d of docInputs) {
+    const abs = safeResolve(rootDir, d.file);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+      outDocs.push({ name: d.name, description: d.description, file: d.file, abs });
+    } else {
+      missing.push(d.file);
+    }
+  }
+
+  for (const s of skillInputs) {
+    if (s.file) {
+      const abs = safeResolve(rootDir, s.file);
+      if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+        outSkills.push({ name: s.name, description: s.description, kind: 'file', file: s.file, dir: null, abs });
+      } else {
+        missing.push(s.file);
+      }
+      continue;
+    }
+
+    const abs = safeResolve(rootDir, s.dir);
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+      const files = sortBundleFiles(glob.sync('**/*', { cwd: abs, dot: false, onlyFiles: true }));
+      outSkills.push({
+        name: s.name,
+        description: s.description,
+        kind: 'dir',
+        file: null,
+        dir: s.dir,
+        abs,
+        files: files.map((rel) => ({ rel, abs: path.join(abs, rel) })),
+      });
+    } else {
+      missing.push(s.dir);
+    }
+  }
+
+  return { docs: outDocs, skills: outSkills, missing };
+}
+
+/**
+ * Attach file contents to a resolved assets object.
+ *
+ * @param {{ docs: Array<object>, skills: Array<object>, missing: string[] }} resolved
+ * @returns {{ docs: Array<object>, skills: Array<object>, missing: string[] }}
+ */
+function readAssets(resolved) {
+  return {
+    docs: resolved.docs.map((d) => ({ ...d, content: safeRead(d.abs) })),
+    skills: resolved.skills.map((s) => {
+      if (s.kind === 'dir') {
+        return { ...s, files: s.files.map((f) => ({ rel: f.rel, content: safeRead(f.abs) })) };
+      }
+      return { ...s, content: safeRead(s.abs) };
+    }),
+    missing: resolved.missing,
+  };
+}
+
+/**
+ * Fetch a dependency and read its own manifest, if any.
+ *
+ * Lenient: absence or unparseable YAML yields `manifestPath: null, raw: null`
+ * rather than throwing. `fetchRoot` is a test seam.
+ *
+ * @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]
+ * @returns {Promise<{ label: string, rootDir: string, manifestPath: string|null, raw: object|null }>}
+ */
+async function readDepManifest(dep, { token, noFetch, ssh, fetchRoot } = {}) {
+  const fetch = fetchRoot || fetchDepRoot;
+  const { rootDir, label } = await fetch(dep, { token, noFetch, ssh });
+
+  const manifestPath = findManifestInDir(rootDir);
+  let raw = null;
+  if (manifestPath) {
+    try {
+      raw = yaml.load(fs.readFileSync(manifestPath, 'utf8')) || null;
+    } catch (_) {
+      raw = null;
+    }
+  }
+  return { label, rootDir, manifestPath, raw };
+}
+
+/**
+ * Fetch a dependency and collect its declared agent docs/skills with content.
+ *
+ * @param {object} dep - parsed dep object
+ * @param {object} [opts] - same options as readDepManifest
+ * @returns {Promise<{ label: string, manifestPath: string|null, manifestName: string|null, docs: Array<object>, skills: Array<object>, missing: string[] }>}
+ */
+async function collectDepAssets(dep, opts) {
+  const m = await readDepManifest(dep, opts);
+  if (!m.raw) {
+    return { label: m.label, manifestPath: null, manifestName: null, docs: [], skills: [], missing: [] };
+  }
+
+  let docs;
+  let skills;
+  try { docs = parseDocEntries(m.raw.docs || []); } catch (_) { docs = []; }
+  try { skills = parseSkillEntries(m.raw.skills || []); } catch (_) { skills = []; }
+
+  const read = readAssets(resolveAssets({ docs, skills }, m.rootDir));
+  return {
+    label: m.label,
+    manifestPath: m.manifestPath,
+    manifestName: m.raw.name || null,
+    docs: read.docs,
+    skills: read.skills,
+    missing: read.missing,
+  };
+}
+
+/**
+ * Collect the local project's declared agent docs/skills with content.
+ *
+ * @param {object} manifest - parsed manifest (uses `manifest._path` for the root)
+ * @returns {{ docs: Array<object>, skills: Array<object>, missing: string[] }}
+ */
+function collectLocalAssets(manifest) {
+  const rootDir = path.dirname(manifest._path);
+  return readAssets(resolveAssets({ docs: manifest.docs, skills: manifest.skills }, rootDir));
+}
+
+module.exports = {
+  resolveAssets,
+  readAssets,
+  readDepManifest,
+  collectDepAssets,
+  collectLocalAssets,
+};

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

@@ -41,8 +41,10 @@ function buildPlanData(manifest, options = {}) {
     })),
     globalDeps: manifest.globalDeps.map((d) => ({
       source: d.source,
-      repo: d.repo,
+      repo: d.source === 'fungun' ? null : d.repo,
       ref: d.ref,
+      id: d.id ?? null,
+      url: d.url ?? null,
       include_path: d.include_path || null,
       asset: d.asset ?? null,
     })),

package/src/build-service.js

@@ -38,7 +38,7 @@ 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 { resolveDeps, repoKey, normalizeRepo } = require('./deps-resolver');
 const { compilePlugins } = require('./compiler');
 const { collectAll }     = require('./collector');
 const { fetchAssets }    = require('./asset-fetcher');
@@ -118,19 +118,27 @@ 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,
+        const identity = normalizeRepo(repoConfig);
+        if (!cloneJobs.has(identity)) {
+          cloneJobs.set(identity,
             fetchRepo(repoConfig.repo, repoConfig._resolvedRef, resolveGithubToken(manifest, repoConfig.repo), noFetch, 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();
     }
 
@@ -166,6 +174,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,9 +251,11 @@ 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('-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 {
@@ -290,6 +298,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/deps-tree.js

@@ -56,7 +56,10 @@ function printNode(node, prefix, isLast) {
   const childPrefix = isLast ? '    ' : '│   ';
 
   const tag = buildNodeTag(node);
-  logger.dim(`${prefix}${connector}${node.repo}@${node.ref || 'HEAD'}${tag}`);
+  const label = node.source === 'fungun'
+    ? `[fungun] plugin #${node.id}`
+    : `${node.repo}@${node.ref || 'HEAD'}`;
+  logger.dim(`${prefix}${connector}${label}${tag}`);
 
   if (node.cycle) return;
 

package/src/commands/dry-run.js

@@ -28,6 +28,10 @@ function printDryRun(manifest) {
   if (manifest.globalDeps.length) {
     logger.info(`\nGlobal deps (${manifest.globalDeps.length}):`);
     for (const d of manifest.globalDeps) {
+      if (d.source === 'fungun') {
+        logger.dim(`  [fungun] plugin #${d.id}  (${d.url})`);
+        continue;
+      }
       const src = d.source === 'release' ? 'release' : 'git';
       logger.dim(`  [${src}] ${d.repo}@${d.ref}${d.include_path ? ':' + d.include_path : ''}`);
     }