amxx-builder 1.5.1

package/src/repo-fetcher.js

@@ -0,0 +1,273 @@
+const fs   = require('fs');
+const path = require('path');
+const axios = require('axios');
+// Default for API calls; download sites pass their own longer timeout.
+axios.defaults.timeout = 30000;
+const simpleGit = require('simple-git');
+const logger = require('./logger');
+const { getCacheDir } = require('./cache-dir');
+
+function getRepoCacheDir(repo, ref) {
+  // Lowercased key: GitHub repo names are case-insensitive, but filesystems
+  // (NTFS/APFS) and the repo/ref dedup may not be — normalize to avoid
+  // duplicate clones on Linux and dir collisions on Windows/macOS.
+  // Lazy require: deps-resolver imports us, so a top-level import would cycle.
+  const { normalize } = require('./deps-resolver');
+  const key = normalize(repo).replace('/', '__') + '__' + String(ref).replace(/[^a-zA-Z0-9._-]/g, '_');
+  return path.join(getCacheDir(), 'repos', key);
+}
+
+// Matches full or abbreviated commit SHAs (7-40 hex chars).
+const SHA_REF_RE = /^[0-9a-f]{7,40}$/i;
+
+const LATEST_TAG_TTL_MS = 60 * 60 * 1000; // releases update rarely
+
+function latestTagIndexPath() {
+  return path.join(getCacheDir(), '.latest-tags.json');
+}
+
+function readLatestTagIndex() {
+  try { return JSON.parse(fs.readFileSync(latestTagIndexPath(), 'utf8')); } catch { return {}; }
+}
+
+function writeLatestTagIndex(index) {
+  try {
+    fs.mkdirSync(path.dirname(latestTagIndexPath()), { recursive: true });
+    const tmp = latestTagIndexPath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(index));
+    fs.renameSync(tmp, latestTagIndexPath());
+  } catch (_) { /* best-effort */ }
+}
+
+/**
+ * Resolves "latest" ref to the actual release tag via GitHub API.
+ * Cached per-repo (1h TTL) so repeated builds don't burn the rate limit.
+ */
+async function resolveRef(repo, ref, token) {
+  if (ref !== 'latest') return ref;
+
+  // Lazy require: deps-resolver imports us, so a top-level import would cycle.
+  const { normalize } = require('./deps-resolver');
+  const key = normalize(repo);
+  const index = readLatestTagIndex();
+  const cached = index[key];
+  if (cached && Date.now() - cached.at < LATEST_TAG_TTL_MS) {
+    logger.dim(`  ${repo}: latest = ${cached.tag} (cached)`);
+    return cached.tag;
+  }
+
+  logger.dim(`  ${repo}: resolving latest release tag...`);
+  const headers = token ? { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json' } : {};
+  try {
+    const { data } = await axios.get(
+      `https://api.github.com/repos/${repo}/releases/latest`,
+      { headers }
+    );
+    logger.dim(`  ${repo}: latest = ${data.tag_name}`);
+    logger.verbose(`  ${repo}: resolved via GET /repos/${repo}/releases/latest`);
+    index[key] = { tag: data.tag_name, at: Date.now() };
+    writeLatestTagIndex(index);
+    return data.tag_name;
+  } catch (err) {
+    throw new Error(`Failed to resolve latest release for ${repo}: ${err.message}`);
+  }
+}
+
+/**
+ * Resolve a ref to a concrete tag only when it is 'latest'.
+ * Single-source-of-truth for the `ref === 'latest' ? resolveRef(...) : ref`
+ * pattern shared by the build pipeline, include-tree and MCP.
+ */
+async function resolveRefIfLatest(ref, repo, token) {
+  return ref !== 'latest' ? ref : resolveRef(repo, ref, token);
+}
+
+/**
+ * Resolve the ref for every manifest repo and record it as `_resolvedRef`.
+ * Single source of the "for each repo: ref === 'latest' → resolve tag" loop
+ * shared by the build pipeline, deps-tree and include-tree. Repos with a
+ * concrete ref get `_resolvedRef = repoConfig.ref`; `latest` refs are resolved
+ * via the GitHub API (cached 1h). Rejects if any resolution fails.
+ *
+ * @param {Object[]} repos - manifest.repos entries ({ repo, ref, ... })
+ * @param {(repo: string) => string|null} tokenFor - per-repo token resolver,
+ *   e.g. (repo) => resolveGithubToken(manifest, repo)
+ */
+async function resolveRepoRefs(repos, tokenFor) {
+  await Promise.all(repos.map(async (repoConfig) => {
+    repoConfig._resolvedRef = await resolveRefIfLatest(
+      repoConfig.ref,
+      repoConfig.repo,
+      tokenFor(repoConfig.repo)
+    );
+  }));
+}
+
+/**
+ * Ensures the repo is available locally. Returns the local path.
+ *
+ * Two paths:
+ *   ssh=true  → clone via system git (simple-git): URL is always
+ *               git@github.com:owner/repo.git, no token handling.
+ *   otherwise → download the GitHub tarball (codeload) over plain HTTP and
+ *               extract it — no system git needed. A 404 with a token present
+ *               retries once through the API tarball endpoint (private repos).
+ */
+async function fetchRepo(repo, ref, token, noFetch, ssh = false) {
+  const resolvedRef = ref || null;  // null = default branch
+  const cacheKey    = resolvedRef || 'HEAD';
+  const cacheDir    = getRepoCacheDir(repo, cacheKey);
+
+  if (await isCacheValid(cacheDir, resolvedRef, ssh)) {
+    logger.dim(`  ${repo} @ ${cacheKey} (cached)`);
+    return cacheDir;
+  }
+
+  if (noFetch) {
+    throw new Error(
+      `Repo cache missing for ${repo}@${cacheKey} and --no-fetch is set.\n` +
+      `Run without --no-fetch to populate the cache.`
+    );
+  }
+
+  logger.step(`Fetching ${repo} @ ${cacheKey} ...`);
+
+  // Fetch into a temp dir and atomically rename into place: a concurrent build
+  // fetching the same repo never sees — or deletes — a half-written cache.
+  const tmpDir = `${cacheDir}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+  fs.mkdirSync(path.dirname(tmpDir), { recursive: true });
+
+  try {
+    if (ssh) {
+      await cloneViaGit(repo, resolvedRef, tmpDir);
+    } else {
+      await fetchTarball(repo, resolvedRef, token, tmpDir);
+    }
+
+    try {
+      fs.renameSync(tmpDir, cacheDir);
+    } catch {
+      // cacheDir already exists — a concurrent fetch (valid) or stale junk.
+      if (await isCacheValid(cacheDir, resolvedRef, ssh)) {
+        try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+      } else {
+        try { fs.rmSync(cacheDir, { recursive: true, force: true }); } catch (_) {}
+        fs.renameSync(tmpDir, cacheDir);
+      }
+    }
+  } catch (err) {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+    throw wrapFetchError(err, repo, cacheKey, token);
+  }
+
+  logger.info(`Fetching ${repo} @ ${cacheKey} ... done`);
+  return cacheDir;
+}
+
+/**
+ * SSH path (github.ssh: true): clone via system git — kept verbatim.
+ * Shallow clone of the default branch (--branch for tags/branches); SHA refs
+ * are fetched + checked out explicitly because shallow clones cannot fetch
+ * arbitrary SHAs via --branch.
+ */
+async function cloneViaGit(repo, resolvedRef, tmpDir) {
+  const isShaRef  = SHA_REF_RE.test(resolvedRef || '');
+  // Windows: allow >260-char paths and keep file contents identical across OSes
+  // (core.autocrlf would rewrite .sma/.inc/.cfg to CRLF and break hashing/output).
+  const cloneArgs = ['--depth=1', '-c', 'core.longpaths=true', '-c', 'core.autocrlf=false'];
+  if (resolvedRef && !isShaRef) cloneArgs.push('--branch', resolvedRef);
+
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'echo' };
+  const git = simpleGit({ env });
+  await git.clone(`git@github.com:${repo}.git`, tmpDir, cloneArgs);
+  if (isShaRef) {
+    const shaGit = simpleGit({ baseDir: tmpDir, env });
+    await shaGit.fetch(['--depth=1', 'origin', resolvedRef]);
+    await shaGit.checkout(resolvedRef);
+  }
+}
+
+/**
+ * Non-ssh path: download the repo tarball as a plain HTTP GET and extract it
+ * into tmpDir. downloadRef is passed straight to codeload — it accepts
+ * branches, tags, short/full SHAs and HEAD, so no SHA-resolution calls.
+ * A 404 with a token present means the repo is private (or the ref needs
+ * auth): retry once via the API tarball endpoint, which 302-redirects to a
+ * signed codeload URL (axios follows the redirect). The token only ever
+ * travels in request headers — never in a URL or on disk.
+ */
+async function fetchTarball(repo, resolvedRef, token, tmpDir) {
+  const downloadRef = resolvedRef || 'HEAD';
+  // Lazy require: release-fetcher imports repo-fetcher at top level.
+  const { downloadAsset } = require('./release-fetcher');
+  const { safeExtractTar } = require('./fs-utils');
+
+  // downloadAsset writes <archivePath>.part — the parent dir must exist.
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  const archivePath = path.join(tmpDir, 'repo.tar.gz');
+  try {
+    await downloadAsset(`https://codeload.github.com/${repo}/tar.gz/${downloadRef}`, archivePath, {});
+  } catch (err) {
+    if (!(err.response && err.response.status === 404 && token)) throw err;
+    await downloadAsset(
+      `https://api.github.com/repos/${repo}/tarball/${downloadRef}`,
+      archivePath,
+      { Accept: 'application/vnd.github+json', Authorization: `Bearer ${token}` }
+    );
+  }
+
+  safeExtractTar(archivePath, tmpDir, { stripComponents: 1 });
+  fs.rmSync(archivePath, { force: true });
+  // Sentinel written inside tmpDir BEFORE the rename: only complete dirs
+  // ever become the cache.
+  const sentinelTmp = path.join(tmpDir, '.extracted.tmp');
+  fs.writeFileSync(sentinelTmp, downloadRef, 'utf8');
+  fs.renameSync(sentinelTmp, path.join(tmpDir, '.extracted'));
+}
+
+/**
+ * True when the fetch cache at cacheDir exists and is usable.
+ * gitBased (github.ssh: true) → a real git clone whose ref resolves
+ * (guards against partial clones left by a crashed process).
+ * Non-git → an extracted tarball (sentinel) or a legacy git clone — old
+ * caches stay valid so no mass re-download after upgrading.
+ */
+async function isCacheValid(cacheDir, ref, gitBased = false) {
+  if (!gitBased) {
+    return fs.existsSync(path.join(cacheDir, '.extracted')) ||
+           fs.existsSync(path.join(cacheDir, '.git'));
+  }
+  if (!fs.existsSync(path.join(cacheDir, '.git'))) return false;
+  try {
+    const verifyRef = ref && ref !== 'HEAD' ? `${ref}^{commit}` : 'HEAD';
+    await simpleGit({ baseDir: cacheDir }).revparse(['--verify', verifyRef]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function redactToken(msg, token) {
+  return token ? String(msg).split(token).join('***') : String(msg);
+}
+
+/**
+ * Maps failures to the established hints: HTTP status when available
+ * (axios errors), otherwise treat as a network problem.
+ */
+function wrapFetchError(err, repo, cacheKey, token) {
+  const msg    = redactToken(err.message || '', token);
+  const status = err.response && err.response.status;
+  let hint;
+  if (status === 404) {
+    hint = '\n  → Check the repo name/ref, or set github.token_env if the repo is private';
+  } else if (status === 401 || status === 403) {
+    hint = '\n  → Check your GitHub token (github.token_env / GITHUB_TOKEN)';
+  } else {
+    hint = '\n  → Check your internet connection';
+  }
+  return new Error(`Failed to fetch ${repo}@${cacheKey}: ${msg}${hint}`);
+}
+
+module.exports = { fetchRepo, resolveRef, resolveRefIfLatest, resolveRepoRefs, getRepoCacheDir, isCacheValid };

package/src/retry.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const logger = require('./logger');
+
+/**
+ * Retries an async function up to `attempts` times with exponential backoff.
+ * Retries on network/timeout errors, 5xx, 408/429 and GitHub rate-limit 403s;
+ * other 4xx responses are NOT retried.
+ */
+async function withRetry(fn, { attempts = 3, baseDelayMs = 1000, label = '' } = {}) {
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isTransient(err)) throw err;
+
+      if (i < attempts - 1) {
+        const delay = retryDelayMs(err, baseDelayMs, i);
+        const tag   = label ? ` (${label})` : '';
+        logger.warn(`Retrying${tag} in ${Math.round(delay / 1000)}s... (attempt ${i + 2}/${attempts})`);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+  throw lastErr;
+}
+
+// 408/429 and GitHub rate-limit 403s (X-RateLimit-Remaining: 0) are transient;
+// any other 4xx is a permanent failure.
+function isTransient(err) {
+  const status = err.response?.status;
+  if (!status || status >= 500) return true;
+  if (status === 408 || status === 429) return true;
+  if (status === 403 && String(err.response?.headers?.['x-ratelimit-remaining']) === '0') return true;
+  return false;
+}
+
+function retryDelayMs(err, baseDelayMs, attempt) {
+  const retryAfter = err.response?.headers?.['retry-after'];
+  const secs = retryAfter !== undefined ? parseInt(retryAfter, 10) : NaN;
+  if (Number.isFinite(secs) && secs >= 0) {
+    return Math.min(secs, 60) * 1000; // HTTP-date Retry-After falls back below
+  }
+  const exp = baseDelayMs * 2 ** attempt;
+  return Math.random() * exp; // full jitter — parallel calls don't retry in lockstep
+}
+
+module.exports = { withRetry };

package/src/schema.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * Shared AJV-based manifest validation.
+ *
+ * Loads the JSON schema once (cached), compiles AJV with all errors and
+ * format support. Used by both manifest.js (parse-time validation, throws)
+ * and validate.js (diagnostic validation, returns structured result).
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const Ajv     = require('ajv');
+const addFormats = require('ajv-formats');
+
+const SCHEMA_PATH = path.join(__dirname, '..', 'schema', 'amxbuild.schema.json');
+
+let schemaCache = null;
+try {
+  if (fs.existsSync(SCHEMA_PATH)) {
+    schemaCache = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));
+  }
+} catch { /* no schema file — AJV validation skipped */ }
+
+/**
+ * Validate a raw manifest object against the JSON schema.
+ *
+ * @param {object} raw  — parsed YAML manifest merged with defaults
+ * @returns {{ valid: boolean, errors: Array<{ path: string, message: string }> }}
+ */
+function validateManifest(raw) {
+  if (!schemaCache) return { valid: true, errors: [] };
+
+  const ajv = new Ajv({ allErrors: true });
+  addFormats(ajv);
+  const validate = ajv.compile(schemaCache);
+  const valid = validate(raw);
+
+  if (valid) return { valid: true, errors: [] };
+
+  return {
+    valid: false,
+    errors: validate.errors.map((e) => ({
+      path: e.instancePath || '(root)',
+      message: e.message,
+    })),
+  };
+}
+
+function getManifestSchema() {
+  return schemaCache;
+}
+
+module.exports = { validateManifest, getManifestSchema };

package/src/update-check.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * Checks npm-style (GitHub) version once per 24h and returns newer version if found.
+ * Fires a single GET to GitHub API — respects rate limits by caching check timestamps.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const https = require('https');
+const { getCacheDir } = require('./cache-dir');
+
+const PKG = require('../package.json');
+const CHECK_FILE = 'update-check.json';
+const CHECK_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const GITHUB_API = 'https://api.github.com/repos/AmxxModularEcosystem/amxx-builder/releases/latest';
+
+/**
+ * Simple semver compare (major.minor.patch).
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function cmpVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va > vb) return 1;
+    if (va < vb) return -1;
+  }
+  return 0;
+}
+
+function readCheckCache() {
+  const cacheDir = getCacheDir();
+  const file = path.join(cacheDir, CHECK_FILE);
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function writeCheckCache(data) {
+  const cacheDir = getCacheDir();
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const file = path.join(cacheDir, CHECK_FILE);
+  fs.writeFileSync(file, JSON.stringify(data));
+}
+
+/**
+ * Fetch latest release tag from GitHub API.
+ * Returns tag string (e.g. "v1.4.0") or null on failure.
+ */
+function fetchLatestTag() {
+  return new Promise((resolve) => {
+    const req = https.get(GITHUB_API, {
+      headers: {
+        'User-Agent': 'amxx-builder',
+        Accept: 'application/vnd.github.v3+json',
+      },
+      timeout: 5000,
+    }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) return resolve(null);
+        try {
+          const data = JSON.parse(body);
+          if (data.tag_name) return resolve(data.tag_name);
+        } catch { /* ignore parse errors */ }
+        resolve(null);
+      });
+      res.on('error', () => resolve(null));
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+/**
+ * Check for a newer version. Returns the newer version string or null.
+ * Respects 24h cache — does not call GitHub API if checked recently.
+ */
+async function checkForUpdate() {
+  // Respect opt-out env
+  if (process.env.AMXB_NO_UPDATE_CHECK) return null;
+
+  const cached = readCheckCache();
+  const now = Date.now();
+
+  if (cached && (now - cached.ts) < CHECK_TTL_MS) {
+    // Still within cooldown
+    return null;
+  }
+
+  // Mark checked even if API call fails — prevents retry on every command
+  writeCheckCache({ ts: now });
+
+  const latestTag = await fetchLatestTag();
+  if (!latestTag) return null;
+
+  const latestVer = latestTag.replace(/^v/i, '');
+  const currentVer = PKG.version;
+
+  if (cmpVersions(latestVer, currentVer) > 0) {
+    return latestVer;
+  }
+
+  return null;
+}
+
+module.exports = { checkForUpdate };

package/src/validate.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const { validateManifest: validateSchema } = require('./schema');
+const { loadDefaultsRaw, deepMerge } = require('./manifest');
+
+/**
+ * Validate a manifest file and return structured diagnostics.
+ * Never throws — returns { valid, errors, warnings }.
+ */
+function validateManifestFile(manifestPath) {
+  const errors   = [];
+  const warnings = [];
+
+  // 1. File exists
+  const absPath = path.resolve(manifestPath);
+  if (!fs.existsSync(absPath)) {
+    errors.push({ path: '(root)', message: `Manifest not found: ${absPath}` });
+    return { valid: false, errors, warnings };
+  }
+
+  // 2. Parse YAML
+  let projectRaw;
+  try {
+    projectRaw = yaml.load(fs.readFileSync(absPath, 'utf8'));
+  } catch (err) {
+    errors.push({ path: '(root)', message: `YAML parse error: ${err.message}` });
+    return { valid: false, errors, warnings };
+  }
+
+  if (!projectRaw || typeof projectRaw !== 'object' || Array.isArray(projectRaw)) {
+    errors.push({ path: '(root)', message: 'Manifest is empty or not a valid YAML object' });
+    return { valid: false, errors, warnings };
+  }
+
+  // 3. Check name
+  if (!projectRaw.name || typeof projectRaw.name !== 'string') {
+    errors.push({ path: '/name', message: 'Missing required field "name"' });
+  }
+
+  // 4. Merge with defaults
+  const defaults = loadDefaultsRaw();
+  const raw = deepMerge(defaults, projectRaw);
+
+  // 5. AJV schema validation (via shared schema module)
+  const schemaResult = validateSchema(raw);
+  for (const e of schemaResult.errors) {
+    errors.push(e);
+  }
+
+  // 6. version must be a string (common mistake: YAML parses unquoted as number)
+  if (raw.version != null && typeof raw.version !== 'string') {
+    errors.push({
+      path: '/version',
+      message: `"version" must be a quoted string in YAML, got ${typeof raw.version}`,
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+module.exports = { validateManifestFile };

package/src/watcher.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+const logger = require('./logger');
+
+const fileHashes = new Map();
+
+function contentChanged(filePath) {
+  let data;
+  try { data = fs.readFileSync(filePath); } catch { return false; }
+  const hash = crypto.createHash('sha1').update(data).digest('hex');
+  if (fileHashes.get(filePath) === hash) return false;
+  fileHashes.set(filePath, hash);
+  return true;
+}
+
+/**
+ * Starts watching local project files for changes.
+ *
+ * Uses chokidar's awaitWriteFinish as the debounce mechanism —
+ * a file is only reported stable after it hasn't changed for debounceMs.
+ * This handles VSCode auto-save correctly: rapid saves are coalesced.
+ *
+ * Watch targets:
+ *   - amxmodx/scripting/**‌/*.sma  → onSmaChange(absPath)
+ *   - amxmodx/**  (non-.sma)      → onFileChange(relPath, 'amxmodx')
+ *   - assets/**                   → onFileChange(relPath, 'assets')
+ *   - amxbuild.yml / amxbuild.yaml → onManifestChange()
+ *
+ * Returns the chokidar watcher instance.
+ */
+function startWatch(manifest, manifestPath, handlers) {
+  const chokidar = require('chokidar');
+
+  const debounceMs  = manifest.deploy.watch_debounce_ms;
+  const manifestDir = path.dirname(path.resolve(manifestPath));
+
+  const localAmxmodxDir = path.join(manifestDir, manifest.amxmodx.dir);
+  const localAssetsDir  = path.join(manifestDir, 'assets');
+
+  const watchPaths = [path.resolve(manifestPath)];
+  if (fs.existsSync(localAmxmodxDir)) watchPaths.push(localAmxmodxDir);
+  if (fs.existsSync(localAssetsDir))  watchPaths.push(localAssetsDir);
+
+  logger.info('Watching for changes (Ctrl+C to stop)...');
+  for (const p of watchPaths) logger.dim(`  ${p}`);
+
+  const watcher = chokidar.watch(watchPaths, {
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: debounceMs,
+      pollInterval: 100,
+    },
+  });
+
+  const caseNorm = process.platform === 'win32' ? (p) => p.toLowerCase() : (p) => p;
+
+  // Invoke a watch handler without letting a rejection/throw kill the process.
+  const safeCall = (fn) => {
+    try {
+      const p = fn();
+      if (p && typeof p.catch === 'function') {
+        p.catch((err) => logger.error(`Watch handler error: ${err.message}`));
+      }
+    } catch (err) {
+      logger.error(`Watch handler error: ${err.message}`);
+    }
+  };
+
+  watcher.on('all', (event, filePath) => {
+    const absPath = path.resolve(filePath);
+    const rel     = path.relative(manifestDir, absPath);
+
+    // Deleted file → remove it from the deploy target (Windows rename fires
+    // unlink+add, so handling unlink also covers renames of the old name).
+    if (event === 'unlink') {
+      if (absPath === path.resolve(manifestPath)) return;
+      fileHashes.delete(absPath);
+      const inAmxmodx = caseNorm(absPath).startsWith(caseNorm(localAmxmodxDir) + path.sep);
+      if (!inAmxmodx && !caseNorm(absPath).startsWith(caseNorm(localAssetsDir) + path.sep)) return;
+      const section   = inAmxmodx ? 'amxmodx' : 'assets';
+      const baseDir   = inAmxmodx ? localAmxmodxDir : localAssetsDir;
+      let relToBase   = path.relative(baseDir, absPath);
+      if (inAmxmodx && caseNorm(relToBase).endsWith('.inc')) return; // includes are never deployed
+      if (inAmxmodx && caseNorm(relToBase).endsWith('.sma')) {
+        // A deleted .sma should remove its compiled output, not the source copy.
+        relToBase = relToBase.replace(/\.sma$/i, '').replace(/^scripting\//, 'plugins/') + '.amxx';
+      }
+      if (typeof handlers.onFileDelete === 'function') {
+        logger.step(`Deleted: ${rel}`);
+        safeCall(() => handlers.onFileDelete(relToBase, section));
+      }
+      return;
+    }
+
+    if (!['add', 'change'].includes(event)) return;
+
+    if (!contentChanged(absPath)) return;
+
+    // Manifest changed → full rebuild
+    if (absPath === path.resolve(manifestPath)) {
+      logger.step(`Manifest changed → full rebuild`);
+      safeCall(() => handlers.onManifestChange());
+      return;
+    }
+
+    const inAmxmodx = caseNorm(absPath).startsWith(caseNorm(localAmxmodxDir) + path.sep);
+    const section   = inAmxmodx ? 'amxmodx' : 'assets';
+    const baseDir   = inAmxmodx ? localAmxmodxDir : localAssetsDir;
+    const relToBase = path.relative(baseDir, absPath);
+
+    if (inAmxmodx && caseNorm(filePath).endsWith('.sma')) {
+      logger.step(`Changed: ${rel}`);
+      safeCall(() => handlers.onSmaChange(absPath));
+      return;
+    }
+
+    if (inAmxmodx && caseNorm(filePath).endsWith('.inc')) {
+      logger.step(`Include changed: ${rel}`);
+      safeCall(() => handlers.onIncChange(absPath));
+      return;
+    }
+
+    logger.step(`Changed: ${rel}`);
+    safeCall(() => handlers.onFileChange(relToBase, section));
+  });
+
+  watcher.on('error', (err) => logger.warn(`Watcher error: ${err.message}`));
+
+  return watcher;
+}
+
+module.exports = { startWatch };