amxx-builder 1.5.1

package/src/ini-builder.js

@@ -0,0 +1,44 @@
+const fs   = require('fs');
+const path = require('path');
+const logger = require('./logger');
+
+/**
+ * Groups compiled plugins by plugins_ini_postfix and writes .ini files
+ * into build/amxmodx/configs/.
+ */
+function buildIniFiles(compiledPlugins, buildDir) {
+  if (!compiledPlugins.length) return;
+
+  const configsDir = path.join(buildDir, 'amxmodx', 'configs');
+  fs.mkdirSync(configsDir, { recursive: true });
+
+  const groups = new Map(); // postfix → [plugin]
+  for (const plugin of compiledPlugins) {
+    if (plugin.skipIni) continue;
+    const k = plugin.plugins_ini_postfix;
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k).push(plugin);
+  }
+
+  for (const [postfix, plugins] of groups) {
+    const iniName = postfix ? `plugins-${postfix}.ini` : 'plugins.ini';
+    const iniPath = path.join(configsDir, iniName);
+
+    const lines = ['; Generated by amxx-builder'];
+    let lastRepo = null;
+    for (const p of plugins) {
+      const repoId = `${p.repo} @ ${p.ref}`;
+      if (repoId !== lastRepo) {
+        lines.push('', `; Source: ${repoId}`);
+        lastRepo = repoId;
+      }
+      lines.push(p.amxxName);
+    }
+    lines.push('');
+
+    fs.writeFileSync(iniPath, lines.join('\n'), 'utf8');
+    logger.info(`Generated: ${iniName} (${plugins.length} ${plugins.length === 1 ? 'entry' : 'entries'})`);
+  }
+}
+
+module.exports = { buildIniFiles };

package/src/jsonrpc-transport.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generic JSON-RPC 2.0 server over stdio.
+ *
+ * Line-delimited JSON-RPC 2.0: each line on stdin is one request, response or
+ * notification; each response/notification is written as one JSON line on
+ * stdout. This is pure transport — it knows nothing about MCP, protocols,
+ * or domain methods. Method semantics live in the adapter layer (e.g.
+ * mcp/mcp-server.js), which registers request/notification handlers.
+ *
+ * No external dependencies.
+ *
+ * Usage:
+ *   const { JsonRpcServer } = require('./jsonrpc-transport');
+ *   const rpc = new JsonRpcServer();
+ *   rpc.onRequest('greet', (params) => ({ hello: params?.name || 'world' }));
+ *   rpc.onRequest('fail', () => { const e = new Error('nope'); e.code = -32000; throw e; });
+ *   rpc.onNotification('log', (params) => console.error('log:', params));
+ *   rpc.notify('event', { kind: 'done' });   // server → client push
+ *   rpc.connect();
+ */
+
+const readline = require('readline');
+
+class JsonRpcServer {
+  constructor() {
+    this._requests = new Map();
+    this._notifications = new Map();
+    this._rl = null;
+    this._closed = false;
+    // EPIPE when the client dies — exit cleanly instead of crashing.
+    process.stdout.on('error', () => process.exit(0));
+  }
+
+  /**
+   * Register a handler for a request method (messages WITH id).
+   * Handler receives the decoded params object; may be async.
+   * Its return value is sent as `result`. A thrown Error is sent as
+   * `error` with code -32603 (message = err.message), unless the Error
+   * carries a numeric `.code` property, which is then used verbatim.
+   * Returns this for chaining.
+   */
+  onRequest(method, handler) {
+    this._requests.set(method, handler);
+    return this;
+  }
+
+  /**
+   * Register a handler for a notification method (messages WITHOUT id).
+   * Handler receives the decoded params object; may be async. Errors are
+   * swallowed and logged to stderr (never sent — there is no id to reply to).
+   * Returns this for chaining.
+   */
+  onNotification(method, handler) {
+    this._notifications.set(method, handler);
+    return this;
+  }
+
+  /**
+   * Start listening on stdin. Never resolves (runs until close/EOF).
+   */
+  async connect() {
+    this._rl = readline.createInterface({
+      input: process.stdin,
+      terminal: false,
+    });
+
+    for await (const line of this._rl) {
+      if (this._closed) break;
+      if (!line.trim()) continue;
+
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch (_) {
+        // JSON parse error — try to extract id from the raw line
+        const id = this._extractId(line);
+        if (id != null) {
+          this.sendError(id, -32700, 'Parse error');
+        }
+        continue;
+      }
+
+      // Dispatch without awaiting so a long-running handler does not block
+      // subsequent notifications/requests. stdout writes are queued by Node,
+      // so per-message response order is preserved.
+      Promise.resolve()
+        .then(() => this._handleMessage(msg))
+        .catch((err) => {
+          if (msg.id != null) {
+            this.sendError(msg.id, -32603, 'Internal error: ' + err.message);
+          }
+        });
+    }
+
+    // stdin EOF — client closed the pipe; exit so we don't hang on open stdout.
+    process.exit(0);
+  }
+
+  close() {
+    this._closed = true;
+    if (this._rl) this._rl.close();
+  }
+
+  // ─── Server → client ─────────────────────────────────────────────────────
+
+  /**
+   * Send a server-initiated notification (no id).
+   */
+  notify(method, params) {
+    const msg = { jsonrpc: '2.0', method };
+    if (params !== undefined) msg.params = params;
+    process.stdout.write(JSON.stringify(msg) + '\n');
+  }
+
+  /**
+   * Send a successful response for a request id.
+   */
+  sendResult(id, result) {
+    process.stdout.write(
+      JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n'
+    );
+  }
+
+  /**
+   * Send an error response for a request id.
+   */
+  sendError(id, code, message, data) {
+    const err = { jsonrpc: '2.0', id, error: { code, message } };
+    if (data !== undefined) err.error.data = data;
+    process.stdout.write(JSON.stringify(err) + '\n');
+  }
+
+  // ─── Message dispatch ────────────────────────────────────────────────────
+
+  async _handleMessage(msg) {
+    if (!msg || typeof msg !== 'object' || !msg.method) return;
+
+    const { method, id, params } = msg;
+
+    // Notification (no id): fire handler, swallow errors — nothing to reply to.
+    if (id == null) {
+      const handler = this._notifications.get(method);
+      if (handler) {
+        try {
+          await handler(params);
+        } catch (err) {
+          process.stderr.write(
+            `[jsonrpc] notification "${method}" failed: ${err && err.message ? err.message : String(err)}\n`
+          );
+        }
+      }
+      return;
+    }
+
+    // Request (has id): reply with result, or an error on throw.
+    const handler = this._requests.get(method);
+    if (!handler) {
+      this.sendError(id, -32601, `Method not found: ${method}`);
+      return;
+    }
+
+    let result;
+    try {
+      result = await handler(params);
+    } catch (err) {
+      if (typeof err.code === 'number') {
+        this.sendError(id, err.code, err.message || 'Error');
+      } else {
+        this.sendError(
+          id,
+          -32603,
+          'Internal error: ' + (err && err.message ? err.message : String(err))
+        );
+      }
+      return;
+    }
+    this.sendResult(id, result);
+  }
+
+  /**
+   * Best-effort extraction of JSON-RPC id from a malformed JSON line.
+   */
+  _extractId(raw) {
+    try {
+      const m = raw.match(/"id"\s*:\s*(\d+|"[^"]+")/);
+      if (m) return JSON.parse(m[1]);
+    } catch (_) {}
+    return null;
+  }
+}
+
+module.exports = { JsonRpcServer };

package/src/logger.js

@@ -0,0 +1,50 @@
+const chalk = require('chalk');
+const { emit, EVENTS } = require('./events');
+
+// Respect NO_COLOR env var (https://no-color.org/) and --no-color CLI flag
+const noColor = process.env.NO_COLOR !== undefined
+  || process.argv.includes('--no-color');
+
+if (noColor) chalk.level = 0;
+
+const PREFIX = chalk.bold.white('[amxx-builder]');
+
+let _verbose = false;
+let _stderr  = false;
+
+function out(msg) {
+  if (_stderr) {
+    console.error(`${PREFIX} ${msg}`);
+  } else {
+    console.log(`${PREFIX} ${msg}`);
+  }
+}
+
+function emitLog(level, message) {
+  emit(EVENTS.LOG, { level, message });
+}
+
+const logger = {
+  setVerbose:  (v) => { _verbose = v; },
+  isVerbose:   ()  => _verbose,
+
+  // MCP: stdout is the JSON-RPC channel — logs must go to stderr
+  setStderr:   (v = true) => { _stderr = !!v; },
+  isStderr:    ()  => _stderr,
+
+  info:    (msg) => { out(msg); emitLog('info', msg); },
+  success: (msg) => { out(chalk.green(msg)); emitLog('success', msg); },
+  warn:    (msg) => { out(chalk.yellow(msg)); emitLog('warn', msg); },
+  error:   (msg) => { console.error(`${PREFIX} ${chalk.red(msg)}`); emitLog('error', msg); },
+  step:    (msg) => { out(chalk.cyan(msg)); emitLog('step', msg); },
+  skip:    (msg) => { out(chalk.gray(msg)); emitLog('skip', msg); },
+  dim:     (msg) => { out(chalk.dim(msg)); emitLog('dim', msg); },
+  verbose: (msg) => { if (_verbose) { out(chalk.dim(msg)); emitLog('verbose', msg); } },
+
+  // Verbatim passthrough (compiler output): no [amxx-builder] prefix, no color,
+  // no added newline. The CLI writes exactly what the producer emitted.
+  raw:      (text) => { process.stdout.write(text); emitLog('raw', text); },
+  rawError: (text) => { process.stderr.write(text); emitLog('rawError', text); },
+};
+
+module.exports = logger;

package/src/manifest-path.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const MANIFEST_CANDIDATES = ['amxbuild.yml', 'amxbuild.yaml', 'manifest.yml'];
+
+/**
+ * Resolve the manifest file path from an explicit arg or auto-detection.
+ *
+ * Single-source-of-truth for manifest discovery. Returns ABSOLUTE paths.
+ * No warnings are emitted here — deprecation/fallback rendering is the job of
+ * the calling interface (CLI renders the manifest.yml deprecation warning).
+ *
+ * @param {string} [explicit] - Explicit manifest path (may not exist yet —
+ *   parseManifest will report it).
+ * @returns {{ path: string, usedDefault: boolean }}
+ *   usedDefault: true when a fallback was chosen — either the deprecated
+ *   manifest.yml, or the amxbuild.yml default when nothing was found.
+ */
+function resolveManifestPath(explicit) {
+  if (explicit) return { path: path.resolve(explicit), usedDefault: false };
+
+  const cwd = process.cwd();
+  for (const name of MANIFEST_CANDIDATES) {
+    const p = path.join(cwd, name);
+    if (fs.existsSync(p)) {
+      return { path: p, usedDefault: name === 'manifest.yml' };
+    }
+  }
+  return { path: path.join(cwd, 'amxbuild.yml'), usedDefault: true };
+}
+
+module.exports = { resolveManifestPath };

package/src/manifest.js

@@ -0,0 +1,373 @@
+const fs   = require('fs');
+const yaml = require('js-yaml');
+const path = require('path');
+
+const { validateManifest: validateSchema } = require('./schema');
+
+const DEFAULTS_PATH  = path.join(__dirname, '..', 'defaults', 'amxbuild.defaults.yml');
+
+function loadDefaultsRaw() {
+  if (!fs.existsSync(DEFAULTS_PATH)) return {};
+  return yaml.load(fs.readFileSync(DEFAULTS_PATH, 'utf8')) || {};
+}
+
+function deepMerge(base, overlay) {
+  if (overlay === null || overlay === undefined) return base;
+  if (base  === null || base  === undefined) return overlay;
+  if (Array.isArray(overlay)) return overlay;
+  if (typeof overlay === 'object' && typeof base === 'object') {
+    const result = { ...base };
+    for (const [k, v] of Object.entries(overlay)) {
+      result[k] = deepMerge(base[k], v);
+    }
+    return result;
+  }
+  return overlay;
+}
+
+function validateManifest(raw) {
+  const result = validateSchema(raw);
+  if (!result.valid) {
+    const errors = result.errors.map(e => `  ${e.path}: ${e.message}`);
+    throw new Error(`Manifest validation failed:\n${errors.join('\n')}`);
+  }
+}
+
+function parseManifest(manifestPath) {
+  const absPath = path.resolve(manifestPath);
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`Manifest not found: ${absPath}\n  → Run "amxb init" to create one`);
+  }
+
+  const projectRaw = yaml.load(fs.readFileSync(absPath, 'utf8'));
+  const raw = deepMerge(loadDefaultsRaw(), projectRaw);
+  validateManifest(raw);
+
+  if (!raw.name) throw new Error('manifest: missing required field "name"');
+
+  const platform = parsePlatform(raw.platform);
+  const gh       = raw.github || {};
+  const tokenEnv = gh.token_env || 'GITHUB_TOKEN';
+  const token    = process.env[tokenEnv] || null;
+  const ssh      = !!gh.ssh;
+  const tokens   = parseTokenMap(gh.tokens);
+
+  const globalPostfix = raw.plugins_ini_postfix != null ? String(raw.plugins_ini_postfix) : '';
+  const globalAmxDir  = (raw.amxmodx && raw.amxmodx.dir) || 'amxmodx';
+  const globalDeps    = parseDepsLines(raw.deps || []);
+
+  const repos  = (raw.repos || []).map((r) => parseRepoEntry(r, globalPostfix, globalAmxDir));
+  const output = raw.output || {};
+
+  return {
+    _path:    absPath,
+    name:     raw.name,
+    version:  parseVersion(raw.version),
+    platform,
+    amxmodx: {
+      version: (raw.amxmodx && raw.amxmodx.version) ? String(raw.amxmodx.version) : null,
+      dir:     globalAmxDir,
+      defines: (raw.amxmodx && Array.isArray(raw.amxmodx.defines))
+        ? raw.amxmodx.defines.map(String)
+        : [],
+    },
+    github: { token_env: tokenEnv, tokens, token, ssh },
+    globalDeps,
+    globalPostfix,
+    repos,
+    assets:      parseAssets(raw.assets || {}),
+    pluginRules: parsePluginRules(raw.plugins || []),
+    deploy:      parseDeploy(raw),
+    output: {
+      dir:          String(output.dir),
+      archive_name: String(output.archive_name),
+      amxmodx_path: String(output.amxmodx_path),
+      assets_path:  output.assets_path != null ? String(output.assets_path) : '',
+      readme:       Boolean(output.readme),
+      generate_ini: Boolean(output.generate_ini),
+      pack:         Boolean(output.pack),
+      on_conflict:  validateOnConflict(output.on_conflict),
+    },
+  };
+}
+
+function parseVersion(val) {
+  if (typeof val !== 'string') {
+    throw new Error(`manifest: "version" must be a string — wrap it in quotes: version: "${val}"`);
+  }
+  return val;
+}
+
+function validateOnConflict(val) {
+  const valid = ['last_wins', 'first_wins', 'error'];
+  if (val == null) return 'last_wins';
+  if (!valid.includes(val)) {
+    throw new Error(`manifest: output.on_conflict must be one of: ${valid.join(', ')}`);
+  }
+  return val;
+}
+
+function parseTokenMap(map) {
+  if (map == null) return {};
+  if (typeof map !== 'object' || Array.isArray(map)) {
+    throw new Error(`manifest: github.tokens must be a map of owner → env var name`);
+  }
+  const result = {};
+  for (const [owner, envName] of Object.entries(map)) {
+    if (envName == null || String(envName).trim() === '') {
+      throw new Error(`manifest: github.tokens.${owner} must name an env variable`);
+    }
+    result[String(owner).trim()] = interpolateEnv(String(envName).trim());
+  }
+  return result;
+}
+
+/**
+ * Resolve the GitHub token for a specific "owner/repo" path.
+ *
+ * Priority:
+ *   1. github.tokens[owner]   — per-owner env var (e.g. GITHUB_TOKEN_ORGA)
+ *   2. github.token_env       — global token env var (default "GITHUB_TOKEN")
+ *   3. null                   — anonymous (public repos)
+ *
+ * @param {object} manifest — parsed manifest
+ * @param {string} repoPath — "owner/repo" or any string starting with the owner
+ * @returns {string|null}
+ */
+function resolveGithubToken(manifest, repoPath) {
+  const gh     = manifest.github || {};
+  const owner  = String(repoPath || '').split('/')[0];
+  const envName = (gh.tokens && gh.tokens[owner]) || gh.token_env || 'GITHUB_TOKEN';
+  return process.env[envName] || null;
+}
+
+function parseRepoEntry(r, globalPostfix, globalAmxDir) {
+  // Shorthand: "owner/repo" or "owner/repo@ref"
+  if (typeof r === 'string') {
+    const atIdx = r.indexOf('@');
+    const repo  = atIdx === -1 ? r.trim() : r.slice(0, atIdx).trim();
+    const ref   = atIdx === -1 ? null     : r.slice(atIdx + 1).trim() || null;
+    return makeRepo({ repo, ref }, globalPostfix, globalAmxDir);
+  }
+  if (!r.repo) throw new Error(`manifest: repo entry missing "repo" field: ${JSON.stringify(r)}`);
+  return makeRepo(r, globalPostfix, globalAmxDir);
+}
+
+function makeRepo(r, globalPostfix, globalAmxDir) {
+  return {
+    repo:                r.repo,
+    ref:                 r.ref || null,
+    amxmodx_dir:         r.amxmodx_dir || globalAmxDir,
+    plugins_ini_postfix: r.plugins_ini_postfix != null ? String(r.plugins_ini_postfix) : globalPostfix,
+    exclude:             r.exclude       || [],
+    exclude_files:       r.exclude_files || [],
+    deps_override:       r.deps_override ? parseDepsLines(r.deps_override) : null,
+  };
+}
+
+/**
+ * Dep string shorthand: "owner/repo@ref[:include_path]".
+ * Strict — rejects internal whitespace in the repo and ref parts.
+ */
+const DEP_STRING_RE = /^([^@\s]+)@([^:\s]+)(?::(.+))?$/;
+
+/**
+ * Parse a long-form dep object (manifest `deps` entries).
+ *
+ * @param {object} line
+ * @returns {{ repo: string, ref: string, include_path: string|null, source: string, asset: * }}
+ */
+function parseDepObject(line) {
+  if (!line.repo) throw new Error(`Dep entry missing "repo": ${JSON.stringify(line)}`);
+  if (!line.ref)  throw new Error(`Dep entry missing "ref": ${JSON.stringify(line)}`);
+  const source = line.source || 'git';
+  if (!['git', 'release'].includes(source)) {
+    throw new Error(`Dep entry "source" must be "git" or "release": ${JSON.stringify(line)}`);
+  }
+  return {
+    repo:         String(line.repo).trim(),
+    ref:          String(line.ref).trim(),
+    include_path: line.include_path ? String(line.include_path).trim() : null,
+    source,
+    asset:        line.asset != null ? line.asset : null,
+  };
+}
+
+/**
+ * Strict parse of a SINGLE dep string: "owner/repo@ref[:include_path]".
+ *
+ * @param {string} str
+ * @returns {{ repo: string, ref: string, include_path: string|null, source: string, asset: null }}
+ */
+function parseDepString(str) {
+  const trimmed = String(str).trim();
+  const match = trimmed.match(DEP_STRING_RE);
+  if (!trimmed || !match) {
+    throw new Error(
+      `Invalid dep string: "${trimmed}". Expected format: "owner/repo@ref" or "owner/repo@ref:include_path"`
+    );
+  }
+  const [, repo, ref, includePath] = match;
+  return {
+    repo:         repo.trim(),
+    ref:          ref.trim(),
+    include_path: includePath ? includePath.trim() : null,
+    source:       'git',
+    asset:        null,
+  };
+}
+
+function parseDepsLines(lines) {
+  const result = [];
+  for (const line of lines) {
+    // Long-form object (manifest only — DEPS_LIST files are always strings)
+    if (line && typeof line === 'object') {
+      result.push(parseDepObject(line));
+      continue;
+    }
+    // Short-form string: "owner/repo@ref[:include_path]"  (always git)
+    const trimmed = String(line).trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const match = trimmed.match(DEP_STRING_RE);
+    if (!match) throw new Error(`Invalid dep entry: "${trimmed}"`);
+    const [, repoPath, ref, includePath] = match;
+    result.push({
+      repo:         repoPath.trim(),
+      ref:          ref.trim(),
+      include_path: includePath ? includePath.trim() : null,
+      source:       'git',
+      asset:        null,
+    });
+  }
+  return result;
+}
+
+function parsePlatform(val) {
+  const valid = ['linux', 'windows', 'mac'];
+  if (val == null) return null; // null = auto-detect host at runtime
+  if (!valid.includes(val)) throw new Error(`manifest: platform must be one of: ${valid.join(', ')}`);
+  return val;
+}
+
+function parseAssets(raw) {
+  const valid = ['last_wins', 'first_wins'];
+  const onConflict = raw.on_conflict || 'last_wins';
+  if (!valid.includes(onConflict)) {
+    throw new Error(`manifest: assets.on_conflict must be one of: ${valid.join(', ')}`);
+  }
+  return {
+    on_conflict: onConflict,
+    sources: (raw.sources || []).map(parseAssetSource),
+  };
+}
+
+function parseAssetSource(s) {
+  if (s.source === 'local') {
+    return { type: 'local', map: parseAssetMap(s) };
+  }
+  if (s.source === 'amxmodx') {
+    return { type: 'amxmodx', map: parseAssetMap(s), cache: parseAssetCache(s.cache) };
+  }
+  if (s.source === 'release') {
+    if (!s.repo) throw new Error(`asset source: release requires "repo": ${JSON.stringify(s)}`);
+    if (!s.ref)  throw new Error(`asset source: release requires "ref": ${JSON.stringify(s)}`);
+    return {
+      type:  'release',
+      repo:  String(s.repo).trim(),
+      ref:   String(s.ref).trim(),
+      asset: s.asset != null ? s.asset : null,
+      map:   parseAssetMap(s),
+    };
+  }
+  if (!s.url) throw new Error(`asset source missing "url" or "source": ${JSON.stringify(s)}`);
+  return { type: 'url', url: s.url, map: parseAssetMap(s), cache: parseAssetCache(s.cache) };
+}
+
+function parseAssetMap(s) {
+  if (s.map) return s.map.map(e => ({ from: e.from || null, to: e.to || null }));
+  return [{ from: s.from || null, to: s.to || null }];
+}
+
+function parseAssetCache(val) {
+  const valid = ['none', 'local', 'global'];
+  if (val == null) return 'none';
+  if (!valid.includes(val)) throw new Error(`asset source cache must be one of: ${valid.join(', ')}`);
+  return val;
+}
+
+function parsePluginRules(rules) {
+  if (!Array.isArray(rules)) return [];
+  return rules.map((r, i) => {
+    if (!r.match) throw new Error(`plugins[${i}]: missing "match" field`);
+    const ini = r.ini === false ? false : (r.ini != null ? String(r.ini) : null);
+    return {
+      match:   String(r.match),
+      enabled: r.enabled !== false,
+      ini,
+    };
+  });
+}
+
+function interpolateEnv(val) {
+  if (typeof val !== 'string') return val;
+  return val.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? '');
+}
+
+function parseDeploy(raw) {
+  const d = raw.deploy || {};
+  const r = d.rcon || {};
+  return {
+    path:              interpolateEnv(d.path)         || process.env.AMXB_DEPLOY_PATH         || null,
+    amxmodx_path:      interpolateEnv(d.amxmodx_path) || null,
+    assets_path:       interpolateEnv(d.assets_path)  ?? null,
+    watch_debounce_ms: Number(d.watch_debounce_ms),
+    exclude:           Array.isArray(d.exclude) ? d.exclude.map(String) : [],
+    rcon: {
+      host:     interpolateEnv(r.host)     || process.env.AMXB_DEPLOY_RCON_HOST     || null,
+      port:     Number(r.port || process.env.AMXB_DEPLOY_RCON_PORT),
+      password: interpolateEnv(r.password) || process.env.AMXB_DEPLOY_RCON_PASSWORD || null,
+      command:  interpolateEnv(r.command)  || process.env.AMXB_DEPLOY_RCON_CMD      || null,
+    },
+  };
+}
+
+// ─── Manifest overrides ────────────────────────────────────────────────────────
+
+function applyOverrides(manifest, pairs) {
+  for (const pair of pairs) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx === -1) throw new Error(`--set: invalid format "${pair}" (expected key=value)`);
+    const keys  = pair.slice(0, eqIdx).trim().split('.');
+    const value = parseOverrideValue(pair.slice(eqIdx + 1));
+    let node = manifest;
+    for (let i = 0; i < keys.length - 1; i++) {
+      if (node[keys[i]] == null) node[keys[i]] = {};
+      node = node[keys[i]];
+    }
+    node[keys[keys.length - 1]] = value;
+  }
+}
+
+function parseOverrideValue(str) {
+  if (str === 'true')  return true;
+  if (str === 'false') return false;
+  if (str === 'null')  return null;
+  if (/^\d+$/.test(str)) return parseInt(str, 10);
+  return str;
+}
+
+function resolveManifest(manifestPath, options = {}) {
+  const manifest = parseManifest(manifestPath);
+
+  if (options.set && options.set.length > 0) {
+    applyOverrides(manifest, options.set);
+  }
+
+  if (options.define && options.define.length > 0) {
+    manifest.amxmodx.defines.push(...options.define);
+  }
+
+  return manifest;
+}
+
+module.exports = { parseManifest, parseDepsLines, parseDepString, parseDepObject, applyOverrides, parseOverrideValue, resolveManifest, resolveGithubToken, loadDefaultsRaw, deepMerge };