amxx-builder 1.5.1

package/src/deps-tree.js

@@ -0,0 +1,202 @@
+'use strict';
+
+/**
+ * Recursive dependency tree builder.
+ *
+ * Walks a list of dep entries, fetches each repo, reads its DEPS_LIST (or
+ * deps_override callback), and recursively resolves sub-dependencies.
+ *
+ * Used by:
+ *   - CLI: amxb deps-tree
+ *   - MCP: get_dep_tree tool
+ *
+ * No domain-specific logic — pure tree traversal with cycle detection.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { fetchRepo, resolveRef } = require('./repo-fetcher');
+const { parseDepsLines }        = require('./manifest');
+const { normalize }             = require('./deps-resolver');
+
+// ─── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Build a recursive dependency tree.
+ *
+ * @param {Object[]} rootDeps — root dep entries.
+ *   Each entry: { repo, ref, source?, include_path?, asset? }
+ * @param {Object} [options]
+ * @param {string}   [options.token]       — GitHub PAT (falls back to env)
+ * @param {Function} [options.tokenFor]    — (repo) => token; per-owner token resolver.
+ *   When provided, takes precedence over options.token for every dep node.
+ * @param {boolean}  [options.noFetch]     — only use cache, skip network
+ * @param {number}   [options.depth]       — max depth (0 = unlimited)
+ * @param {string}   [options.from]        — origin label for root deps ('manifest')
+ * @param {Function} [options.getDepsOverride] — (repo) => dep[] | null;
+ *   Called for each dep node before reading DEPS_LIST. If it returns an array,
+ *   those entries are used instead of reading the repo's DEPS_LIST file.
+ * @returns {Promise<{ dependencies: Object[] }>}
+ */
+async function buildDepTree(rootDeps, options = {}) {
+  const {
+    token    = null,
+    tokenFor = null,
+    noFetch  = false,
+    depth    = 0,
+    from: rootFrom = 'manifest',
+    getDepsOverride = null,
+  } = options;
+
+  const resolveToken = tokenFor || (() => token);
+
+  const visited   = new Set(); // Set<"owner/repo@resolvedRef"> — already expanded globally
+  const pathStack = new Set(); // current recursion path — a dep seen here is a TRUE cycle
+  const tree = [];
+
+  for (const dep of rootDeps) {
+    const node = await walkDep(dep, {
+      resolveToken, noFetch, depth, visited, pathStack,
+      from: rootFrom,
+      currentDepth: 0,
+      getDepsOverride,
+    });
+    tree.push(node);
+  }
+
+  return { dependencies: tree };
+}
+
+/**
+ * Assemble root deps for the dependency tree from a resolved manifest.
+ * Single source of truth shared by the CLI `amxb deps-tree` command and the
+ * MCP `get_dep_tree` tool.
+ *
+ * Mirrors the historical behavior of both callers:
+ *   - manifest.repos       → { ...repoConfig, _from: 'repo' } (repo/ref plus
+ *     preserved repo fields, tagged with their origin)
+ *   - manifest.globalDeps  → { ...dep, _from: 'manifest' }
+ *   - getDepsOverride(repo) → the repo config's deps_override, or null
+ *
+ * @param {object} manifest - resolved manifest (parseManifest output)
+ * @returns {{ rootDeps: Object[], getDepsOverride: (repo: string) => Object[]|null }}
+ */
+function assembleRootDeps(manifest) {
+  const rootDeps = [];
+  for (const repoConfig of manifest.repos) {
+    rootDeps.push({ ...repoConfig, _from: 'repo' });
+  }
+  for (const dep of manifest.globalDeps) {
+    rootDeps.push({ ...dep, _from: 'manifest' });
+  }
+  const getDepsOverride = (repo) => {
+    const config = manifest.repos.find((r) => r.repo === repo);
+    return config ? config.deps_override : null;
+  };
+  return { rootDeps, getDepsOverride };
+}
+
+// ─── Recursive walk ────────────────────────────────────────────────────────────
+
+async function walkDep(dep, ctx) {
+  const { resolveToken, noFetch, depth, visited, pathStack, getDepsOverride } = ctx;
+
+  const repo = dep.repo;
+  const ref  = dep.ref || 'HEAD';
+  const token = resolveToken(repo);
+
+  // ── Resolve ref (e.g. "latest" → concrete tag) ──────────────────────────
+  let resolvedRef;
+  let refError = null;
+  try {
+    resolvedRef = await resolveRef(repo, dep.ref, token);
+  } catch (err) {
+    resolvedRef = null;
+    refError = err.message;
+  }
+
+  // ── Cycle vs shared detection ───────────────────────────────────────────
+  const normRepo  = normalize(repo);
+  const visitedKey = resolvedRef
+    ? `${normRepo}@${resolvedRef}`
+    : `${normRepo}@${ref}`; // if resolve failed, use original ref
+
+  const isCycle  = pathStack.has(visitedKey); // on the current path → real cycle
+  const isShared = visited.has(visitedKey);   // expanded elsewhere → diamond/shared dep
+  const skipExpand = isCycle || isShared;
+
+  if (resolvedRef) {
+    pathStack.add(visitedKey);
+    visited.add(visitedKey);
+  }
+
+  // ── Check depth ─────────────────────────────────────────────────────────
+  const currentDepth = ctx.currentDepth || 0;
+  const atDepthLimit = depth > 0 && currentDepth >= depth;
+
+  // ── Sub-dependencies ────────────────────────────────────────────────────
+  let subDeps = [];
+  let fetchError = null;
+
+  if (!skipExpand && !atDepthLimit && resolvedRef && dep.source !== 'release') {
+    try {
+      const result = await getSubDeps(dep, resolvedRef, token, noFetch, getDepsOverride);
+      for (const subDep of result.deps) {
+        const childNode = await walkDep(subDep, {
+          ...ctx,
+          from: result.from,
+          currentDepth: currentDepth + 1,
+        });
+        subDeps.push(childNode);
+      }
+    } catch (err) {
+      fetchError = err.message;
+    }
+  }
+
+  if (resolvedRef) pathStack.delete(visitedKey);
+
+  // ── Build node ──────────────────────────────────────────────────────────
+  return {
+    repo,
+    ref:         dep.ref || null,
+    resolvedRef,
+    source:      dep.source || 'git',
+    include_path: dep.include_path || null,
+    asset:       dep.asset != null ? dep.asset : null,
+    from:        ctx.from,
+    error:       refError || fetchError || null,
+    cycle:       isCycle,
+    shared:      isShared,
+    dependencies: subDeps,
+  };
+}
+
+// ─── Read sub-deps from repo or override ──────────────────────────────────────
+
+async function getSubDeps(dep, resolvedRef, token, noFetch, getDepsOverride) {
+  // 1. Check for deps_override first
+  if (typeof getDepsOverride === 'function') {
+    const override = getDepsOverride(dep.repo);
+    if (override && Array.isArray(override) && override.length > 0) {
+      return { deps: override, from: 'deps_override' };
+    }
+  }
+
+  // 2. Clone repo (or use cache) and read DEPS_LIST
+  const repoDir = await fetchRepo(dep.repo, resolvedRef, token, noFetch, false);
+  const depsPath = path.join(repoDir, 'DEPS_LIST');
+
+  if (!fs.existsSync(depsPath)) {
+    return { deps: [], from: 'deps_list' };
+  }
+
+  const lines = fs.readFileSync(depsPath, 'utf8').split(/\r?\n/);
+  const parsed = parseDepsLines(lines);
+  return { deps: parsed, from: 'deps_list' };
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────────
+
+module.exports = { buildDepTree, assembleRootDeps };

package/src/env.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * Load .env from the manifest's directory.
+ *
+ * @param {string} manifestPath - Path to the manifest (absolute or relative).
+ * @param {object} [options] - Extra dotenv config options merged over the defaults
+ *   ({ override: true }). Callers needing different semantics (e.g. the MCP
+ *   build_plan tool's non-overriding quiet load) pass them here.
+ */
+function loadEnv(manifestPath, options = {}) {
+  const manifestDir = path.dirname(path.resolve(manifestPath));
+  require('dotenv').config({ path: path.join(manifestDir, '.env'), override: true, ...options });
+}
+
+module.exports = { loadEnv };

package/src/events.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+
+// Module-level shared event bus. All of src/ emits and subscribes through this
+// single instance, so interface layers (CLI renderer, MCP, serve/JSON-RPC) can
+// observe the same stream of structured events without touching the core.
+const bus = new EventEmitter();
+
+// Thin wrappers bound to the shared instance (EventEmitter methods are
+// unbound, so they must be bound here to work when destructured).
+const on                = bus.on.bind(bus);
+const off               = bus.off.bind(bus);
+const once              = bus.once.bind(bus);
+const emit              = bus.emit.bind(bus);
+const removeAllListeners = bus.removeAllListeners.bind(bus);
+
+// Canonical event names for the core render channel.
+const EVENTS = {
+  LOG:      'log',
+  PROGRESS: 'progress',
+  STAGE:    'stage',
+  COMPILED: 'compiled',
+  DIAG:     'diag',
+  DONE:     'done',
+  ERROR:    'error',
+};
+
+module.exports = { on, off, once, emit, removeAllListeners, EVENTS };

package/src/format.js

@@ -0,0 +1,23 @@
+'use strict';
+
+/**
+ * Format a byte count as a human-readable string.
+ *
+ * Tiers:
+ *   B  — bytes < 1024                  (exact)
+ *   KB — bytes < 1024^2                (default precision 1)
+ *   MB — bytes < 1024^3                (default precision 1)
+ *   GB — bytes >= 1024^3               (default precision 2)
+ *
+ * @param {number} bytes
+ * @param {{ precision?: number }} [opts] - Override the per-tier default precision.
+ * @returns {string}
+ */
+function formatBytes(bytes, { precision } = {}) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 ** 2) return `${(bytes / 1024).toFixed(precision == null ? 1 : precision)} KB`;
+  if (bytes < 1024 ** 3) return `${(bytes / 1024 ** 2).toFixed(precision == null ? 1 : precision)} MB`;
+  return `${(bytes / 1024 ** 3).toFixed(precision == null ? 2 : precision)} GB`;
+}
+
+module.exports = { formatBytes };

package/src/fs-utils.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Recursively copy all contents from srcDir to destDir.
+ * Creates destDir if it does not exist.
+ */
+function copyDirContents(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath  = path.join(src,  entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isSymbolicLink()) {
+      // Recreate the link; fall back to copying the file content when the
+      // target cannot be recreated (e.g. no symlink privilege on Windows).
+      let target;
+      try { target = fs.readlinkSync(srcPath); } catch { continue; }
+      try {
+        fs.symlinkSync(target, destPath);
+      } catch {
+        const st = fs.statSync(srcPath);
+        if (st.isFile()) {
+          fs.copyFileSync(srcPath, destPath);
+          copyMode(srcPath, destPath);
+        }
+      }
+      continue;
+    }
+    if (entry.isDirectory()) {
+      copyDirContents(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      copyMode(srcPath, destPath);
+    }
+  }
+}
+
+// copyFileSync creates files with 0666 & ~umask — restore the source mode
+// so executable bits survive (needed for binaries shipped via assets/).
+function copyMode(src, dest) {
+  try {
+    const mode = fs.statSync(src).mode & 0o777;
+    fs.chmodSync(dest, mode);
+  } catch (_) {}
+}
+
+/**
+ * Recursively count files inside a directory (excludes directories themselves).
+ */
+function countFiles(dir) {
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      count += countFiles(p);
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Safe tar extraction — uses spawnSync to avoid shell injection.
+ * Supports .tar.gz / .tgz and .tar.bz2 archives.
+ * stripComponents > 0 drops that many leading path segments (GitHub tarballs
+ * wrap everything in a single {repo}-{sha}/ top-level dir → strip 1).
+ * Throws on non-zero exit.
+ */
+function safeExtractTar(archivePath, destDir, { stripComponents = 0 } = {}) {
+  const flag = archivePath.endsWith('.tar.bz2') ? 'j' : 'z';
+  const args = ['-x' + flag, '-f', archivePath, '-C', destDir];
+  if (stripComponents > 0) args.push(`--strip-components=${stripComponents}`);
+  const result = spawnSync('tar', args, { stdio: 'pipe' });
+  if (result.error) {
+    throw new Error(`tar extraction failed for ${path.basename(archivePath)}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const msg = (result.stderr || result.stdout || '').toString().trim();
+    throw new Error(`tar extraction failed for ${path.basename(archivePath)}: ${msg || 'unknown error'}`);
+  }
+}
+
+module.exports = { copyDirContents, countFiles, safeExtractTar };