novac 2.1.1 → 2.2.0

package/novac/kits/kitrequire/kitdef.js

@@ -0,0 +1,1599 @@
+'use strict';
+
+// ============================================================
+//  kitrequires.js  —  Runtime requirements, guards & assertions
+//  Cross-platform. Async-capable. Bulk-report failures.
+//  module.exports = { kitdef: { ...all exports } }
+// ============================================================
+
+const os   = require('os');
+const fs   = require('fs');
+const path = require('path');
+const { execSync, spawnSync } = require('child_process');
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 1: RESULT TYPE
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Create a passing result.
+ * @param {*} [value]
+ * @returns {{ ok: true, value: * }}
+ */
+function pass(value) { return { ok: true, value }; }
+
+/**
+ * Create a failing result.
+ * @param {string} reason
+ * @param {*} [value]
+ * @returns {{ ok: false, reason: string, value: * }}
+ */
+function fail(reason, value) { return { ok: false, reason, value }; }
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 2: REQUIRE ENGINE
+// ────────────────────────────────────────────────────────────
+
+/**
+ * RequireEngine — bulk assertion collector.
+ *
+ * Usage:
+ *   const kr = new RequireEngine();
+ *   await kr.require(
+ *     kr.admin.isAdmin(),
+ *     kr.internet.connected(),
+ *     kr.commands.has('git'),
+ *   );
+ *   // throws KitRequireError listing ALL failures if any
+ *
+ *   // Or soft check:
+ *   const result = await kr.check(kr.node.version('>=18'));
+ */
+class RequireEngine {
+  constructor(options = {}) {
+    this._options = {
+      exitOnFail:  options.exitOnFail  || false,
+      exitCode:    options.exitCode    || 1,
+      logger:      options.logger      || null,
+    };
+
+    // Bind namespaces
+    this.admin    = _bindNS(adminChecks,    this);
+    this.os       = _bindNS(osChecks,       this);
+    this.cpu      = _bindNS(cpuChecks,      this);
+    this.memory   = _bindNS(memoryChecks,   this);
+    this.env      = _bindNS(envChecks,      this);
+    this.node     = _bindNS(nodeChecks,     this);
+    this.commands = _bindNS(commandChecks,  this);
+    this.fs       = _bindNS(fsChecks,       this);
+    this.network  = _bindNS(networkChecks,  this);
+    this.process  = _bindNS(processChecks,  this);
+    this.display  = _bindNS(displayChecks,  this);
+    this.io       = new IOHelper(this._options);
+    this.tty      = _bindNS(ttyChecks,      this);
+    this.user     = _bindNS(userChecks,     this);
+    this.arch     = _bindNS(archChecks,     this);
+    this.ci       = _bindNS(ciChecks,       this);
+    this.container= _bindNS(containerChecks,this);
+    this.vm       = _bindNS(vmChecks,       this);
+    this.time     = _bindNS(timeChecks,     this);
+    this.pkg      = _bindNS(pkgChecks,      this);
+  }
+
+  /**
+   * Assert all given checks pass. Collects ALL failures, then throws.
+   * Accepts sync results, async promises, or bare booleans.
+   *
+   * @param {...(Result|Promise<Result>|boolean)} checks
+   * @throws {KitRequireError}
+   */
+  async require(...checks) {
+    const results = await Promise.all(checks.map(c => Promise.resolve(c)));
+    const failures = results.filter(r => {
+      if (typeof r === 'boolean') return !r;
+      return r && r.ok === false;
+    }).map(r => (typeof r === 'boolean' ? fail('check returned false') : r));
+
+    if (failures.length > 0) {
+      const err = new KitRequireError(failures);
+      if (this._options.exitOnFail) {
+        this.io.error(err.message);
+        process.exit(this._options.exitCode);
+      }
+      throw err;
+    }
+    return true;
+  }
+
+  /**
+   * Soft check — returns { ok, failures, results } without throwing.
+   * @param {...(Result|Promise<Result>|boolean)} checks
+   * @returns {Promise<{ ok: boolean, failures: Result[], results: Result[] }>}
+   */
+  async check(...checks) {
+    const results = await Promise.all(checks.map(c => Promise.resolve(c)));
+    const normalized = results.map(r => typeof r === 'boolean' ? (r ? pass(r) : fail('check returned false')) : r);
+    const failures = normalized.filter(r => !r.ok);
+    return { ok: failures.length === 0, failures, results: normalized };
+  }
+
+  /**
+   * Assert a single check and throw immediately if it fails.
+   * @param {Result|Promise<Result>|boolean} check
+   * @param {string} [message]
+   */
+  async assert(check, message) {
+    const r = await Promise.resolve(check);
+    const result = typeof r === 'boolean' ? (r ? pass(r) : fail(message || 'assertion failed')) : r;
+    if (!result.ok) {
+      const err = new KitRequireError([result]);
+      if (message) err.message = message;
+      throw err;
+    }
+    return true;
+  }
+
+  /**
+   * Guard: run fn only if all checks pass, otherwise run fallback.
+   * @param {Array} checks
+   * @param {function} fn
+   * @param {function} [fallback]
+   */
+  async guard(checks, fn, fallback) {
+    const { ok, failures } = await this.check(...checks);
+    if (ok) return fn();
+    if (fallback) return fallback(failures);
+  }
+
+  /**
+   * isTTY — direct shorthand.
+   */
+  isTTY() { return ttyChecks.isTTY(); }
+}
+
+function _bindNS(ns, engine) {
+  const bound = {};
+  for (const [k, fn] of Object.entries(ns)) {
+    bound[k] = (...args) => fn(...args);
+  }
+  return bound;
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 3: ERROR TYPE
+// ────────────────────────────────────────────────────────────
+
+class KitRequireError extends Error {
+  /**
+   * @param {Array<{ok:false, reason:string}>} failures
+   */
+  constructor(failures) {
+    const lines = failures.map((f, i) => `  [${i+1}] ${f.reason}`).join('\n');
+    super(`kitrequires: ${failures.length} requirement(s) not met:\n${lines}`);
+    this.name = 'KitRequireError';
+    this.failures = failures;
+    this.count = failures.length;
+  }
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 4: IO HELPER
+// ────────────────────────────────────────────────────────────
+
+const ANSI = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  red:     '\x1b[31m',
+  yellow:  '\x1b[33m',
+  green:   '\x1b[32m',
+  cyan:    '\x1b[36m',
+  gray:    '\x1b[90m',
+  bgRed:   '\x1b[41m',
+  bgYellow:'\x1b[43m',
+  bgGreen: '\x1b[42m',
+};
+
+function _color(code, str) {
+  if (!process.stdout.isTTY) return str;
+  return code + str + ANSI.reset;
+}
+
+class IOHelper {
+  constructor(opts = {}) { this._opts = opts; }
+
+  log(msg, ...args) {
+    console.log(_color(ANSI.cyan, '  ℹ'), msg, ...args);
+  }
+
+  warn(msg, ...args) {
+    console.warn(_color(ANSI.yellow + ANSI.bold, '  ⚠'), _color(ANSI.yellow, msg), ...args);
+  }
+
+  error(msg, ...args) {
+    console.error(_color(ANSI.red + ANSI.bold, '  ✖'), _color(ANSI.red, msg), ...args);
+  }
+
+  success(msg, ...args) {
+    console.log(_color(ANSI.green + ANSI.bold, '  ✔'), _color(ANSI.green, msg), ...args);
+  }
+
+  /** Print a formatted requirements report */
+  report(checkResult) {
+    const { ok, results } = checkResult;
+    console.log(_color(ANSI.bold, '\n── Requirements Report ──────────────────'));
+    for (const r of results) {
+      const icon = r.ok
+        ? _color(ANSI.green,  '  ✔')
+        : _color(ANSI.red,    '  ✖');
+      const msg = r.ok
+        ? _color(ANSI.green,  String(r.value ?? 'ok'))
+        : _color(ANSI.red,    r.reason);
+      console.log(`${icon}  ${msg}`);
+    }
+    const summary = ok
+      ? _color(ANSI.green + ANSI.bold, '\n  All requirements met.')
+      : _color(ANSI.red   + ANSI.bold, `\n  ${checkResult.failures.length} requirement(s) failed.`);
+    console.log(summary + '\n');
+  }
+
+  /** Prompt user (sync, TTY only) */
+  prompt(question) {
+    if (!process.stdin.isTTY) return null;
+    try {
+      const result = spawnSync('node', ['-e',
+        `process.stdout.write(${JSON.stringify(question)});
+         const buf = Buffer.alloc(256);
+         const n = require('fs').readSync(0, buf, 0, 256);
+         process.stdout.write(buf.slice(0, n).toString().replace(/\\r?\\n$/, ''));`
+      ], { stdio: ['inherit', 'pipe', 'inherit'] });
+      return result.stdout ? result.stdout.toString().trim() : null;
+    } catch { return null; }
+  }
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 5: ADMIN / PRIVILEGE CHECKS
+// ────────────────────────────────────────────────────────────
+
+const adminChecks = {
+  /** Check if running as root/Administrator */
+  isAdmin() {
+    try {
+      if (process.platform === 'win32') {
+        const r = spawnSync('net', ['session'], { stdio: 'pipe' });
+        return r.status === 0 ? pass('Running as Administrator') : fail('Not running as Administrator');
+      }
+      // Unix: uid 0 = root
+      return process.getuid() === 0
+        ? pass('Running as root (uid=0)')
+        : fail(`Not running as root (uid=${process.getuid()})`);
+    } catch {
+      return fail('Could not determine admin status');
+    }
+  },
+
+  /** Check if running with elevated privileges (broader check) */
+  isElevated() {
+    return adminChecks.isAdmin();
+  },
+
+  /** Check effective user ID on Unix */
+  isRoot() {
+    if (process.platform === 'win32') return fail('isRoot is Unix-only');
+    try {
+      return process.getuid() === 0
+        ? pass('uid=0 (root)')
+        : fail(`uid=${process.getuid()} (not root)`);
+    } catch { return fail('Could not get UID'); }
+  },
+
+  /** Request elevation — launches a new process with sudo/runas */
+  request(scriptPath, args = []) {
+    scriptPath = scriptPath || process.argv[1];
+    try {
+      if (process.platform === 'win32') {
+        // Windows: use PowerShell Start-Process with RunAs
+        const ps = `Start-Process -Verb RunAs -FilePath node -ArgumentList '${scriptPath} ${args.join(' ')}'`;
+        spawnSync('powershell', ['-Command', ps], { stdio: 'inherit' });
+      } else {
+        spawnSync('sudo', ['node', scriptPath, ...args], { stdio: 'inherit' });
+      }
+      return pass('Elevation requested');
+    } catch (e) {
+      return fail(`Elevation failed: ${e.message}`);
+    }
+  },
+
+  /** Check if sudo is available (Unix) */
+  hasSudo() {
+    if (process.platform === 'win32') return fail('sudo not applicable on Windows');
+    return commandChecks.has('sudo');
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 6: OS / PLATFORM CHECKS
+// ────────────────────────────────────────────────────────────
+
+const osChecks = {
+  isWindows()  { return process.platform === 'win32'  ? pass('Windows')  : fail(`Not Windows (${process.platform})`); },
+  isLinux()    { return process.platform === 'linux'   ? pass('Linux')   : fail(`Not Linux (${process.platform})`);   },
+  isMac()      { return process.platform === 'darwin'  ? pass('macOS')   : fail(`Not macOS (${process.platform})`);   },
+  isAndroid()  {
+    const r = osChecks.isLinux();
+    if (!r.ok) return fail('Not Android');
+    try {
+      const v = fs.readFileSync('/proc/version', 'utf8');
+      return v.toLowerCase().includes('android') ? pass('Android') : fail('Linux but not Android');
+    } catch { return fail('Could not detect Android'); }
+  },
+  isBSD() {
+    return ['freebsd','openbsd','netbsd'].includes(process.platform)
+      ? pass(process.platform) : fail(`Not BSD (${process.platform})`);
+  },
+  isFreeBSD()  { return process.platform === 'freebsd' ? pass('FreeBSD') : fail(`Not FreeBSD`); },
+  isOpenBSD()  { return process.platform === 'openbsd' ? pass('OpenBSD') : fail(`Not OpenBSD`); },
+  isSunOS()    { return process.platform === 'sunos'   ? pass('SunOS')   : fail(`Not SunOS`);   },
+  isUnix()     {
+    return ['linux','darwin','freebsd','openbsd','netbsd','sunos','aix'].includes(process.platform)
+      ? pass(process.platform) : fail(`Not Unix (${process.platform})`);
+  },
+  is64Bit()    { return os.arch() === 'x64' || os.arch() === 'arm64' ? pass(os.arch()) : fail(`Not 64-bit (${os.arch()})`); },
+  is32Bit()    { return os.arch() === 'ia32' || os.arch() === 'arm'  ? pass(os.arch()) : fail(`Not 32-bit (${os.arch()})`); },
+
+  /** Check platform string directly */
+  is(platform) {
+    return process.platform === platform
+      ? pass(platform) : fail(`Platform is '${process.platform}', expected '${platform}'`);
+  },
+
+  /** Get OS release info */
+  info() {
+    return pass({
+      platform: process.platform,
+      arch:     os.arch(),
+      release:  os.release(),
+      type:     os.type(),
+      version:  os.version ? os.version() : 'unknown',
+      hostname: os.hostname(),
+      homedir:  os.homedir(),
+      tmpdir:   os.tmpdir(),
+      endian:   os.endianness(),
+    });
+  },
+
+  /** Check OS uptime >= minSeconds */
+  uptimeAtLeast(minSeconds) {
+    const up = os.uptime();
+    return up >= minSeconds
+      ? pass(`uptime=${up}s`)
+      : fail(`Uptime ${up}s < required ${minSeconds}s`);
+  },
+
+  /** Check kernel release matches regex */
+  releaseMatches(pattern) {
+    const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+    const rel = os.release();
+    return re.test(rel) ? pass(rel) : fail(`OS release '${rel}' does not match ${re}`);
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 7: CPU CHECKS
+// ────────────────────────────────────────────────────────────
+
+const cpuChecks = {
+  /** Check architecture */
+  isArch(arch) {
+    const a = os.arch();
+    return a === arch ? pass(a) : fail(`CPU arch is '${a}', expected '${arch}'`);
+  },
+  isX64()    { return cpuChecks.isArch('x64');  },
+  isX86()    { return cpuChecks.isArch('ia32'); },
+  isARM()    { const a = os.arch(); return a.startsWith('arm') ? pass(a) : fail(`Not ARM (${a})`); },
+  isARM64()  { return cpuChecks.isArch('arm64'); },
+  isRISCV()  { return cpuChecks.isArch('riscv64'); },
+  isMIPS()   { const a = os.arch(); return a.startsWith('mips') ? pass(a) : fail(`Not MIPS (${a})`); },
+
+  /** Check minimum core count */
+  atLeastCores(n) {
+    const c = os.cpus().length;
+    return c >= n ? pass(`${c} cores`) : fail(`Only ${c} CPU core(s), need ${n}`);
+  },
+
+  /** Check max load average (Unix, 1-min) */
+  loadBelow(max) {
+    if (process.platform === 'win32') return pass('load average N/A on Windows');
+    const load = os.loadavg()[0];
+    return load < max ? pass(`load=${load.toFixed(2)}`) : fail(`Load ${load.toFixed(2)} >= ${max}`);
+  },
+
+  /** Get CPU model string */
+  model() {
+    const cpus = os.cpus();
+    return cpus.length ? pass(cpus[0].model) : fail('No CPU info available');
+  },
+
+  /** Endianness */
+  isBigEndian()    { return os.endianness() === 'BE' ? pass('Big-endian')    : fail('Not big-endian (LE)');    },
+  isLittleEndian() { return os.endianness() === 'LE' ? pass('Little-endian') : fail('Not little-endian (BE)'); },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 8: MEMORY CHECKS
+// ────────────────────────────────────────────────────────────
+
+const memoryChecks = {
+  /** Check free memory >= bytes */
+  freeAtLeast(bytes) {
+    const free = os.freemem();
+    return free >= bytes
+      ? pass(`${_humanBytes(free)} free`)
+      : fail(`Only ${_humanBytes(free)} free, need ${_humanBytes(bytes)}`);
+  },
+
+  /** Check free memory >= MB */
+  freeMBAtLeast(mb) { return memoryChecks.freeAtLeast(mb * 1024 * 1024); },
+
+  /** Check total memory >= bytes */
+  totalAtLeast(bytes) {
+    const total = os.totalmem();
+    return total >= bytes
+      ? pass(`${_humanBytes(total)} total`)
+      : fail(`Total RAM ${_humanBytes(total)}, need ${_humanBytes(bytes)}`);
+  },
+
+  totalGBAtLeast(gb) { return memoryChecks.totalAtLeast(gb * 1024 ** 3); },
+
+  /** Check free memory percentage */
+  freePercentAtLeast(pct) {
+    const free = os.freemem(), total = os.totalmem();
+    const actual = (free / total) * 100;
+    return actual >= pct
+      ? pass(`${actual.toFixed(1)}% free`)
+      : fail(`Only ${actual.toFixed(1)}% RAM free, need ${pct}%`);
+  },
+
+  /** Get memory info */
+  info() {
+    const total = os.totalmem(), free = os.freemem();
+    return pass({ total, free, used: total-free, freePct: ((free/total)*100).toFixed(1) });
+  },
+
+  /** Node.js heap usage check */
+  heapBelow(bytes) {
+    const used = process.memoryUsage().heapUsed;
+    return used < bytes
+      ? pass(`heap=${_humanBytes(used)}`)
+      : fail(`Heap usage ${_humanBytes(used)} >= ${_humanBytes(bytes)}`);
+  },
+
+  heapMBBelow(mb) { return memoryChecks.heapBelow(mb * 1024 * 1024); },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 9: ENVIRONMENT CHECKS
+// ────────────────────────────────────────────────────────────
+
+const envChecks = {
+  /** Check env var is set (non-empty) */
+  has(name) {
+    const val = process.env[name];
+    return val !== undefined && val !== ''
+      ? pass(`${name}=${val}`)
+      : fail(`Environment variable '${name}' is not set`);
+  },
+
+  /** Check env var equals value */
+  equals(name, value) {
+    const val = process.env[name];
+    return val === String(value)
+      ? pass(`${name}=${val}`)
+      : fail(`${name}='${val}', expected '${value}'`);
+  },
+
+  /** Check env var matches regex */
+  matches(name, pattern) {
+    const val = process.env[name] || '';
+    const re = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+    return re.test(val)
+      ? pass(`${name}=${val}`)
+      : fail(`${name}='${val}' does not match ${re}`);
+  },
+
+  /** Check env var is NOT set */
+  notSet(name) {
+    return process.env[name] === undefined
+      ? pass(`${name} not set`)
+      : fail(`Environment variable '${name}' should not be set (value: '${process.env[name]}')`);
+  },
+
+  /** Check NODE_ENV */
+  isProduction()  { return envChecks.equals('NODE_ENV', 'production'); },
+  isDevelopment() { return envChecks.equals('NODE_ENV', 'development'); },
+  isTest()        { return envChecks.equals('NODE_ENV', 'test'); },
+
+  /** Get all env vars matching a prefix */
+  withPrefix(prefix) {
+    const matches = Object.entries(process.env)
+      .filter(([k]) => k.startsWith(prefix))
+      .reduce((a,[k,v]) => { a[k]=v; return a; }, {});
+    return Object.keys(matches).length > 0
+      ? pass(matches)
+      : fail(`No environment variables with prefix '${prefix}'`);
+  },
+
+  /** Check PATH includes a directory */
+  pathIncludes(dir) {
+    const pathDirs = (process.env.PATH || '').split(path.delimiter);
+    return pathDirs.some(d => d === dir)
+      ? pass(`PATH includes '${dir}'`)
+      : fail(`PATH does not include '${dir}'`);
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 10: NODE.JS CHECKS
+// ────────────────────────────────────────────────────────────
+
+const nodeChecks = {
+  /** Check Node.js version constraint (semver-like: >=18, ^16, =20) */
+  version(constraint) {
+    const current = process.versions.node;
+    const ok = _semverSatisfies(current, constraint);
+    return ok
+      ? pass(`Node.js v${current} satisfies ${constraint}`)
+      : fail(`Node.js v${current} does not satisfy ${constraint}`);
+  },
+
+  /** Check minimum version */
+  atLeast(major, minor = 0, patch = 0) {
+    const [cMaj, cMin, cPat] = process.versions.node.split('.').map(Number);
+    const ok = cMaj > major || (cMaj === major && cMin > minor) ||
+               (cMaj === major && cMin === minor && cPat >= patch);
+    return ok
+      ? pass(`Node.js v${process.versions.node}`)
+      : fail(`Node.js v${process.versions.node} < required v${major}.${minor}.${patch}`);
+  },
+
+  /** Check if worker_threads is available */
+  hasWorkerThreads() {
+    try { require('worker_threads'); return pass('worker_threads available'); }
+    catch { return fail('worker_threads not available'); }
+  },
+
+  /** Check if ESM (import/export) is supported */
+  hasESM() {
+    const [maj] = process.versions.node.split('.').map(Number);
+    return maj >= 12 ? pass('ESM supported') : fail(`ESM requires Node >=12 (have ${process.versions.node})`);
+  },
+
+  /** Check if async/await is available */
+  hasAsync() {
+    const [maj] = process.versions.node.split('.').map(Number);
+    return maj >= 8 ? pass('async/await supported') : fail(`async/await requires Node >=8`);
+  },
+
+  /** Check if a core module is available */
+  hasModule(name) {
+    try { require(name); return pass(`module '${name}' available`); }
+    catch { return fail(`module '${name}' not available`); }
+  },
+
+  /** Check if an npm package is installed */
+  hasPackage(name) {
+    try { require.resolve(name); return pass(`package '${name}' installed`); }
+    catch { return fail(`package '${name}' not installed (run: npm install ${name})`); }
+  },
+
+  /** Check V8 version */
+  v8Version() { return pass(process.versions.v8); },
+
+  /** Check if running in strict mode */
+  isStrict() {
+    try {
+      // In strict mode, arguments.callee throws
+      (function() { 'use strict'; (function() { return arguments.callee; })(); })();
+      return fail('Not in strict mode');
+    } catch {
+      return pass('Strict mode active');
+    }
+  },
+
+  /** Check if TypeScript types are available (ts-node / tsx) */
+  hasTypeScript() {
+    return nodeChecks.hasPackage('typescript');
+  },
+
+  /** Check if running under ts-node */
+  isTsNode() {
+    return process[Symbol.for('ts-node.register.instance')]
+      ? pass('Running under ts-node')
+      : fail('Not running under ts-node');
+  },
+
+  /** Get all Node.js version info */
+  versions() { return pass(process.versions); },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 11: COMMAND / BINARY CHECKS
+// ────────────────────────────────────────────────────────────
+
+const commandChecks = {
+  /** Check if a command exists on PATH */
+  has(cmd) {
+    try {
+      const which = process.platform === 'win32' ? 'where' : 'which';
+      const r = spawnSync(which, [cmd], { stdio: 'pipe' });
+      return r.status === 0
+        ? pass(`'${cmd}' found at ${r.stdout.toString().trim().split('\n')[0]}`)
+        : fail(`Command '${cmd}' not found in PATH`);
+    } catch {
+      return fail(`Could not check for command '${cmd}'`);
+    }
+  },
+
+  /** Check multiple commands exist */
+  hasAll(...cmds) {
+    const results = cmds.map(c => commandChecks.has(c));
+    const missing = results.filter(r => !r.ok).map(r => r.reason);
+    return missing.length === 0
+      ? pass(`All commands found: ${cmds.join(', ')}`)
+      : fail(missing.join('; '));
+  },
+
+  /** Check command version output matches constraint */
+  version(cmd, versionFlag = '--version', constraint) {
+    try {
+      const r = spawnSync(cmd, [versionFlag], { stdio: 'pipe' });
+      if (r.status !== 0) return fail(`'${cmd}' exited with code ${r.status}`);
+      const output = r.stdout.toString().trim();
+      if (!constraint) return pass(output);
+      const match = output.match(/(\d+\.\d+(?:\.\d+)?)/);
+      if (!match) return fail(`Could not parse version from: ${output}`);
+      return _semverSatisfies(match[1], constraint)
+        ? pass(`${cmd} ${match[1]} satisfies ${constraint}`)
+        : fail(`${cmd} ${match[1]} does not satisfy ${constraint}`);
+    } catch (e) {
+      return fail(`Failed to run '${cmd}': ${e.message}`);
+    }
+  },
+
+  /** Check git is available and in a repo */
+  inGitRepo() {
+    try {
+      const r = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'pipe' });
+      return r.status === 0 ? pass('Inside a git repository') : fail('Not inside a git repository');
+    } catch { return fail('git not available'); }
+  },
+
+  /** Check npm is available */
+  hasNpm()  { return commandChecks.has('npm');  },
+  hasYarn() { return commandChecks.has('yarn'); },
+  hasPnpm() { return commandChecks.has('pnpm'); },
+  hasGit()  { return commandChecks.has('git');  },
+  hasCurl() { return commandChecks.has('curl'); },
+  hasWget() { return commandChecks.has('wget'); },
+  hasMake() { return commandChecks.has('make'); },
+  hasPython() {
+    const r = commandChecks.has('python3');
+    return r.ok ? r : commandChecks.has('python');
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 12: FILESYSTEM CHECKS
+// ────────────────────────────────────────────────────────────
+
+const fsChecks = {
+  /** Check path exists */
+  exists(p) {
+    return fs.existsSync(p) ? pass(`'${p}' exists`) : fail(`Path '${p}' does not exist`);
+  },
+
+  /** Check path is a file */
+  isFile(p) {
+    try {
+      return fs.statSync(p).isFile() ? pass(`'${p}' is a file`) : fail(`'${p}' is not a file`);
+    } catch { return fail(`'${p}' does not exist`); }
+  },
+
+  /** Check path is a directory */
+  isDir(p) {
+    try {
+      return fs.statSync(p).isDirectory() ? pass(`'${p}' is a directory`) : fail(`'${p}' is not a directory`);
+    } catch { return fail(`'${p}' does not exist`); }
+  },
+
+  /** Check path is readable */
+  isReadable(p) {
+    try { fs.accessSync(p, fs.constants.R_OK); return pass(`'${p}' is readable`); }
+    catch { return fail(`'${p}' is not readable`); }
+  },
+
+  /** Check path is writable */
+  isWritable(p) {
+    try { fs.accessSync(p, fs.constants.W_OK); return pass(`'${p}' is writable`); }
+    catch { return fail(`'${p}' is not writable`); }
+  },
+
+  /** Check path is executable */
+  isExecutable(p) {
+    try { fs.accessSync(p, fs.constants.X_OK); return pass(`'${p}' is executable`); }
+    catch { return fail(`'${p}' is not executable`); }
+  },
+
+  /** Check file size >= bytes */
+  sizeAtLeast(p, bytes) {
+    try {
+      const size = fs.statSync(p).size;
+      return size >= bytes ? pass(`${p}: ${_humanBytes(size)}`) : fail(`${p}: ${_humanBytes(size)} < ${_humanBytes(bytes)}`);
+    } catch { return fail(`'${p}' does not exist`); }
+  },
+
+  /** Check file is not empty */
+  notEmpty(p) { return fsChecks.sizeAtLeast(p, 1); },
+
+  /** Check disk space free >= bytes on a path's filesystem */
+  diskFreeAtLeast(dir, bytes) {
+    try {
+      if (process.platform === 'win32') {
+        const drive = path.parse(path.resolve(dir)).root;
+        const r = spawnSync('wmic', ['logicaldisk', 'where', `DeviceID='${drive.slice(0,-1)}'`, 'get', 'FreeSpace'], { stdio: 'pipe' });
+        const lines = r.stdout.toString().trim().split('\n');
+        const free = parseInt(lines[lines.length-1].trim(), 10);
+        return free >= bytes ? pass(`${_humanBytes(free)} free on ${drive}`) : fail(`Only ${_humanBytes(free)} free, need ${_humanBytes(bytes)}`);
+      } else {
+        const r = spawnSync('df', ['-k', dir], { stdio: 'pipe' });
+        const lines = r.stdout.toString().trim().split('\n');
+        const cols = lines[1].trim().split(/\s+/);
+        const freeKB = parseInt(cols[3], 10);
+        const freeBytes = freeKB * 1024;
+        return freeBytes >= bytes ? pass(`${_humanBytes(freeBytes)} free on ${dir}`) : fail(`Only ${_humanBytes(freeBytes)} free, need ${_humanBytes(bytes)}`);
+      }
+    } catch (e) {
+      return fail(`Could not check disk space: ${e.message}`);
+    }
+  },
+
+  diskFreeMBAtLeast(dir, mb) { return fsChecks.diskFreeAtLeast(dir, mb * 1024 * 1024); },
+  diskFreeGBAtLeast(dir, gb) { return fsChecks.diskFreeAtLeast(dir, gb * 1024 ** 3); },
+
+  /** Check symlink target */
+  isSymlink(p) {
+    try {
+      return fs.lstatSync(p).isSymbolicLink() ? pass(`'${p}' is a symlink`) : fail(`'${p}' is not a symlink`);
+    } catch { return fail(`'${p}' does not exist`); }
+  },
+
+  /** Check file modified within last N seconds */
+  modifiedWithin(p, seconds) {
+    try {
+      const stat = fs.statSync(p);
+      const age = (Date.now() - stat.mtimeMs) / 1000;
+      return age <= seconds
+        ? pass(`'${p}' modified ${age.toFixed(0)}s ago`)
+        : fail(`'${p}' was modified ${age.toFixed(0)}s ago (limit: ${seconds}s)`);
+    } catch { return fail(`'${p}' does not exist`); }
+  },
+
+  /** Check current working directory */
+  cwdIs(p) {
+    const cwd = process.cwd();
+    const resolved = path.resolve(p);
+    return cwd === resolved ? pass(`cwd=${cwd}`) : fail(`cwd='${cwd}', expected '${resolved}'`);
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 13: NETWORK CHECKS (async)
+// ────────────────────────────────────────────────────────────
+
+const networkChecks = {
+  /** Check internet connectivity by DNS lookup */
+  async connected(hostname = 'dns.google') {
+    const dns = require('dns').promises;
+    try {
+      await dns.lookup(hostname);
+      return pass(`Internet reachable (resolved ${hostname})`);
+    } catch (e) {
+      return fail(`No internet connection: ${e.message}`);
+    }
+  },
+
+  /** Check DNS resolution for a hostname */
+  async resolves(hostname) {
+    const dns = require('dns').promises;
+    try {
+      const result = await dns.lookup(hostname);
+      return pass(`'${hostname}' resolves to ${result.address}`);
+    } catch (e) {
+      return fail(`DNS resolution failed for '${hostname}': ${e.message}`);
+    }
+  },
+
+  /** Check if a TCP port is open on a host */
+  async portOpen(host, port, timeoutMs = 3000) {
+    const net = require('net');
+    return new Promise(resolve => {
+      const socket = new net.Socket();
+      const timer = setTimeout(() => {
+        socket.destroy();
+        resolve(fail(`Port ${host}:${port} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      socket.connect(port, host, () => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(pass(`Port ${host}:${port} is open`));
+      });
+      socket.on('error', (e) => {
+        clearTimeout(timer);
+        resolve(fail(`Port ${host}:${port} is closed: ${e.message}`));
+      });
+    });
+  },
+
+  /** Check if a local port is free (not in use) */
+  async portFree(port) {
+    const r = await networkChecks.portOpen('127.0.0.1', port, 500);
+    return r.ok
+      ? fail(`Port ${port} is in use`)
+      : pass(`Port ${port} is free`);
+  },
+
+  /** Check network latency <= maxMs to a host */
+  async latencyBelow(host, port, maxMs, timeoutMs = 5000) {
+    const net = require('net');
+    return new Promise(resolve => {
+      const start = Date.now();
+      const socket = new net.Socket();
+      const timer = setTimeout(() => {
+        socket.destroy();
+        resolve(fail(`Latency check to ${host}:${port} timed out`));
+      }, timeoutMs);
+      socket.connect(port, host, () => {
+        const ms = Date.now() - start;
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(ms <= maxMs
+          ? pass(`Latency to ${host}:${port} = ${ms}ms`)
+          : fail(`Latency to ${host}:${port} = ${ms}ms > ${maxMs}ms`));
+      });
+      socket.on('error', (e) => {
+        clearTimeout(timer);
+        resolve(fail(`Could not connect to ${host}:${port}: ${e.message}`));
+      });
+    });
+  },
+
+  /** Check HTTP/HTTPS URL responds with expected status */
+  async urlResponds(url, expectedStatus = 200, timeoutMs = 5000) {
+    const mod = url.startsWith('https') ? require('https') : require('http');
+    return new Promise(resolve => {
+      const req = mod.get(url, { timeout: timeoutMs }, (res) => {
+        res.resume();
+        resolve(res.statusCode === expectedStatus
+          ? pass(`${url} → ${res.statusCode}`)
+          : fail(`${url} → ${res.statusCode} (expected ${expectedStatus})`));
+      });
+      req.on('timeout', () => { req.destroy(); resolve(fail(`${url} timed out`)); });
+      req.on('error', (e) => resolve(fail(`${url} failed: ${e.message}`)));
+    });
+  },
+
+  /** Get all network interfaces */
+  interfaces() {
+    return pass(os.networkInterfaces());
+  },
+
+  /** Check if any non-loopback network interface is up */
+  hasNetworkInterface() {
+    const ifaces = os.networkInterfaces();
+    const up = Object.values(ifaces).flat().some(i => !i.internal);
+    return up ? pass('Network interface available') : fail('No external network interface found');
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 14: PROCESS CHECKS
+// ────────────────────────────────────────────────────────────
+
+const processChecks = {
+  /** Check a PID exists */
+  pidExists(pid) {
+    try {
+      process.kill(pid, 0);
+      return pass(`PID ${pid} exists`);
+    } catch (e) {
+      return e.code === 'EPERM'
+        ? pass(`PID ${pid} exists (no permission to signal)`)
+        : fail(`PID ${pid} does not exist`);
+    }
+  },
+
+  /** Check current process PID */
+  pid() { return pass(process.pid); },
+
+  /** Check if a signal is supported */
+  supportsSignal(sig) {
+    const supported = Object.keys(process.binding ? process.binding('constants').os.signals || {} : {})
+      .concat(['SIGTERM','SIGINT','SIGHUP','SIGKILL','SIGABRT','SIGUSR1','SIGUSR2','SIGPIPE','SIGQUIT']);
+    const sigName = typeof sig === 'number' ? `SIG${sig}` : sig.toUpperCase();
+    return supported.includes(sigName) || (process.platform !== 'win32')
+      ? pass(`Signal ${sigName} supported`)
+      : fail(`Signal ${sig} not supported on ${process.platform}`);
+  },
+
+  /** Check process uptime >= seconds */
+  uptimeAtLeast(seconds) {
+    const up = process.uptime();
+    return up >= seconds ? pass(`Process uptime ${up.toFixed(1)}s`) : fail(`Uptime ${up.toFixed(1)}s < ${seconds}s`);
+  },
+
+  /** Check exit code of a command */
+  commandSucceeds(cmd, args = []) {
+    try {
+      const r = spawnSync(cmd, args, { stdio: 'pipe' });
+      return r.status === 0
+        ? pass(`'${cmd}' exited 0`)
+        : fail(`'${cmd}' exited ${r.status}: ${(r.stderr||'').toString().trim()}`);
+    } catch (e) {
+      return fail(`Failed to run '${cmd}': ${e.message}`);
+    }
+  },
+
+  /** Check if running in a subprocess (parent is not shell) */
+  hasParent() {
+    return process.ppid && process.ppid !== process.pid
+      ? pass(`Parent PID: ${process.ppid}`)
+      : fail('No parent process or parent is self');
+  },
+
+  /** Check if process was started with a specific argv flag */
+  hasArgv(flag) {
+    return process.argv.includes(flag)
+      ? pass(`argv includes '${flag}'`)
+      : fail(`argv does not include '${flag}'`);
+  },
+
+  /** Check if running as a daemon (no TTY) */
+  isDaemon() {
+    return !process.stdin.isTTY && !process.stdout.isTTY
+      ? pass('Running as daemon (no TTY)')
+      : fail('Not a daemon (TTY detected)');
+  },
+
+  /** Get process memory usage */
+  memoryUsage() { return pass(process.memoryUsage()); },
+
+  /** Check if process can write to stdout */
+  hasStdout() {
+    return process.stdout.writable ? pass('stdout is writable') : fail('stdout is not writable');
+  },
+
+  /** Check if process has stdin */
+  hasStdin() {
+    return process.stdin.readable ? pass('stdin is readable') : fail('stdin is not readable');
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 15: DISPLAY CHECKS
+// ────────────────────────────────────────────────────────────
+
+const displayChecks = {
+  /** Check if DISPLAY env var is set (X11) */
+  hasDisplay() {
+    const d = process.env.DISPLAY || process.env.WAYLAND_DISPLAY;
+    return d
+      ? pass(`Display: ${d}`)
+      : fail('No DISPLAY or WAYLAND_DISPLAY set');
+  },
+
+  /** Check if running headless */
+  isHeadless() {
+    const d = process.env.DISPLAY || process.env.WAYLAND_DISPLAY;
+    return !d
+      ? pass('Headless (no display server)')
+      : fail(`Display server present (${d})`);
+  },
+
+  /** Check X11 specifically */
+  hasX11() {
+    const d = process.env.DISPLAY;
+    return d ? pass(`X11 DISPLAY=${d}`) : fail('DISPLAY not set (no X11)');
+  },
+
+  /** Check Wayland */
+  hasWayland() {
+    const d = process.env.WAYLAND_DISPLAY;
+    return d ? pass(`Wayland WAYLAND_DISPLAY=${d}`) : fail('WAYLAND_DISPLAY not set');
+  },
+
+  /** Check if running in a graphical session (X11 or Wayland) */
+  hasGUI() {
+    const has = !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY || process.env.MIR_SOCKET);
+    return has ? pass('GUI session detected') : fail('No GUI session (headless)');
+  },
+
+  /** Check TERM is set */
+  hasTerm() {
+    const t = process.env.TERM;
+    return t ? pass(`TERM=${t}`) : fail('TERM not set');
+  },
+
+  /** Check TERM supports colors */
+  termSupportsColor() {
+    const t = (process.env.TERM || '').toLowerCase();
+    const ct = (process.env.COLORTERM || '').toLowerCase();
+    const ok = t.includes('color') || t.includes('xterm') || ct === 'truecolor' || ct === '24bit' || !!process.env.WT_SESSION;
+    return ok ? pass(`Color terminal: TERM=${t}`) : fail(`Terminal '${t}' may not support colors`);
+  },
+
+  /** Check if running in a GUI app context (Electron / NW.js) */
+  isElectron() {
+    return process.versions && process.versions.electron
+      ? pass(`Electron v${process.versions.electron}`)
+      : fail('Not running in Electron');
+  },
+
+  /** Get display info */
+  info() {
+    return pass({
+      DISPLAY:          process.env.DISPLAY,
+      WAYLAND_DISPLAY:  process.env.WAYLAND_DISPLAY,
+      TERM:             process.env.TERM,
+      COLORTERM:        process.env.COLORTERM,
+      isHeadless:       !(process.env.DISPLAY || process.env.WAYLAND_DISPLAY),
+    });
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 16: TTY CHECKS
+// ────────────────────────────────────────────────────────────
+
+const ttyChecks = {
+  isTTY() {
+    return process.stdout.isTTY
+      ? pass('stdout is a TTY')
+      : fail('stdout is not a TTY (piped or redirected)');
+  },
+  isInteractive() {
+    return process.stdin.isTTY && process.stdout.isTTY
+      ? pass('Interactive terminal')
+      : fail('Not interactive (stdin/stdout not TTY)');
+  },
+  stdinIsTTY()  { return process.stdin.isTTY  ? pass('stdin is TTY')  : fail('stdin is not TTY');  },
+  stderrIsTTY() { return process.stderr.isTTY ? pass('stderr is TTY') : fail('stderr is not TTY'); },
+  termWidth(min = 80) {
+    const cols = process.stdout.columns || 0;
+    return cols >= min ? pass(`Terminal width: ${cols}`) : fail(`Terminal width ${cols} < ${min}`);
+  },
+  termHeight(min = 24) {
+    const rows = process.stdout.rows || 0;
+    return rows >= min ? pass(`Terminal height: ${rows}`) : fail(`Terminal height ${rows} < ${min}`);
+  },
+  info() {
+    return pass({
+      isTTY:    !!process.stdout.isTTY,
+      columns:  process.stdout.columns,
+      rows:     process.stdout.rows,
+      type:     process.env.TERM,
+    });
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 17: USER CHECKS
+// ────────────────────────────────────────────────────────────
+
+const userChecks = {
+  /** Get current username */
+  username() {
+    try {
+      const info = os.userInfo();
+      return pass(info.username);
+    } catch { return fail('Could not get username'); }
+  },
+
+  /** Check username equals value */
+  is(name) {
+    try {
+      const info = os.userInfo();
+      return info.username === name
+        ? pass(`User is '${name}'`)
+        : fail(`User is '${info.username}', expected '${name}'`);
+    } catch { return fail('Could not get username'); }
+  },
+
+  /** Check UID (Unix) */
+  uid(expected) {
+    if (process.platform === 'win32') return fail('UID not applicable on Windows');
+    try {
+      const uid = process.getuid();
+      return uid === expected ? pass(`UID=${uid}`) : fail(`UID=${uid}, expected ${expected}`);
+    } catch { return fail('Could not get UID'); }
+  },
+
+  /** Check GID (Unix) */
+  gid(expected) {
+    if (process.platform === 'win32') return fail('GID not applicable on Windows');
+    try {
+      const gid = process.getgid();
+      return gid === expected ? pass(`GID=${gid}`) : fail(`GID=${gid}, expected ${expected}`);
+    } catch { return fail('Could not get GID'); }
+  },
+
+  /** Check home directory exists */
+  hasHomeDir() {
+    const home = os.homedir();
+    return fs.existsSync(home) ? pass(`Home: ${home}`) : fail(`Home directory '${home}' does not exist`);
+  },
+
+  /** Check user is in a group (Unix) */
+  inGroup(groupName) {
+    if (process.platform === 'win32') return fail('Group check not supported on Windows');
+    try {
+      const r = spawnSync('id', ['-Gn'], { stdio: 'pipe' });
+      const groups = r.stdout.toString().trim().split(/\s+/);
+      return groups.includes(groupName)
+        ? pass(`User is in group '${groupName}'`)
+        : fail(`User is not in group '${groupName}' (groups: ${groups.join(', ')})`);
+    } catch { return fail('Could not check groups'); }
+  },
+
+  /** Get user info */
+  info() {
+    try {
+      return pass(os.userInfo());
+    } catch { return fail('Could not get user info'); }
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 18: ARCHITECTURE CHECKS
+// ────────────────────────────────────────────────────────────
+
+const archChecks = {
+  is(arch) { return cpuChecks.isArch(arch); },
+  isX64()   { return cpuChecks.isX64();   },
+  isX86()   { return cpuChecks.isX86();   },
+  isARM()   { return cpuChecks.isARM();   },
+  isARM64() { return cpuChecks.isARM64(); },
+
+  /** Check process architecture */
+  processArch(expected) {
+    return process.arch === expected
+      ? pass(`process.arch=${process.arch}`)
+      : fail(`process.arch='${process.arch}', expected '${expected}'`);
+  },
+
+  /** Check if running in 64-bit process */
+  is64BitProcess() {
+    return process.arch === 'x64' || process.arch === 'arm64'
+      ? pass(`64-bit process (${process.arch})`)
+      : fail(`Not a 64-bit process (${process.arch})`);
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 19: CI / CD ENVIRONMENT CHECKS
+// ────────────────────────────────────────────────────────────
+
+const CI_VARS = {
+  'CI':               'Generic CI',
+  'CONTINUOUS_INTEGRATION': 'Generic CI',
+  'GITHUB_ACTIONS':   'GitHub Actions',
+  'TRAVIS':           'Travis CI',
+  'CIRCLECI':         'CircleCI',
+  'JENKINS_URL':      'Jenkins',
+  'GITLAB_CI':        'GitLab CI',
+  'BITBUCKET_BUILD_NUMBER': 'Bitbucket Pipelines',
+  'TEAMCITY_VERSION': 'TeamCity',
+  'BUILDKITE':        'Buildkite',
+  'DRONE':            'Drone CI',
+  'SEMAPHORE':        'Semaphore CI',
+  'APPVEYOR':         'AppVeyor',
+  'BUDDY':            'Buddy CI',
+  'HEROKU_TEST_RUN_ID':'Heroku CI',
+  'TF_BUILD':         'Azure DevOps',
+  'CODEBUILD_BUILD_ID':'AWS CodeBuild',
+  'GOOGLE_CLOUD_BUILD':'Google Cloud Build',
+};
+
+const ciChecks = {
+  /** Check if running in any CI environment */
+  isCI() {
+    for (const [key, name] of Object.entries(CI_VARS)) {
+      if (process.env[key]) return pass(`Running in ${name} (${key}=${process.env[key]})`);
+    }
+    return fail('Not running in a CI environment');
+  },
+
+  /** Check specific CI provider */
+  is(provider) {
+    const entry = Object.entries(CI_VARS).find(([,name]) => name.toLowerCase().includes(provider.toLowerCase()));
+    if (!entry) return fail(`Unknown CI provider: ${provider}`);
+    const [key, name] = entry;
+    return process.env[key]
+      ? pass(`Running in ${name}`)
+      : fail(`Not running in ${name}`);
+  },
+
+  isGitHub()   { return ciChecks.is('GitHub');   },
+  isTravis()   { return ciChecks.is('Travis');   },
+  isCircle()   { return ciChecks.is('CircleCI'); },
+  isJenkins()  { return ciChecks.is('Jenkins');  },
+  isGitLab()   { return ciChecks.is('GitLab');   },
+  isAzure()    { return ciChecks.is('Azure');    },
+
+  /** Detect CI name */
+  name() {
+    for (const [key, name] of Object.entries(CI_VARS)) {
+      if (process.env[key]) return pass(name);
+    }
+    return fail('Not in CI');
+  },
+
+  /** Check if running in a pull request */
+  isPR() {
+    const pr =
+      process.env.GITHUB_EVENT_NAME === 'pull_request' ||
+      !!process.env.TRAVIS_PULL_REQUEST ||
+      !!process.env.CI_PULL_REQUEST ||
+      !!process.env.CIRCLE_PULL_REQUEST ||
+      !!process.env.CHANGE_ID; // Jenkins
+    return pr ? pass('Running in a pull request') : fail('Not running in a pull request');
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 20: CONTAINER / VIRTUALIZATION CHECKS
+// ────────────────────────────────────────────────────────────
+
+const containerChecks = {
+  /** Check if running inside Docker */
+  isDocker() {
+    try {
+      if (fs.existsSync('/.dockerenv')) return pass('Running in Docker (/.dockerenv)');
+      const cgroup = fs.readFileSync('/proc/1/cgroup', 'utf8');
+      if (cgroup.includes('docker')) return pass('Running in Docker (cgroup)');
+      return fail('Not in Docker');
+    } catch { return fail('Not in Docker'); }
+  },
+
+  /** Check if running inside a container (Docker, Podman, LXC, etc.) */
+  isContainer() {
+    const dockerResult = containerChecks.isDocker();
+    if (dockerResult.ok) return dockerResult;
+    try {
+      const cgroup = fs.readFileSync('/proc/1/cgroup', 'utf8');
+      if (cgroup.includes('lxc'))    return pass('Running in LXC');
+      if (cgroup.includes('kubepods')) return pass('Running in Kubernetes pod');
+      if (cgroup.includes('containerd')) return pass('Running in containerd');
+      if (fs.existsSync('/run/.containerenv')) return pass('Running in Podman');
+    } catch {}
+    return fail('Not in a container');
+  },
+
+  /** Check if running in Kubernetes */
+  isKubernetes() {
+    return process.env.KUBERNETES_SERVICE_HOST
+      ? pass(`Kubernetes (service=${process.env.KUBERNETES_SERVICE_HOST})`)
+      : fail('Not in Kubernetes');
+  },
+
+  /** Check WSL (Windows Subsystem for Linux) */
+  isWSL() {
+    if (process.platform !== 'linux') return fail('Not on Linux');
+    try {
+      const ver = fs.readFileSync('/proc/version', 'utf8').toLowerCase();
+      const r = fs.existsSync('/proc/sys/fs/binfmt_misc/WSLInterop');
+      return (ver.includes('microsoft') || ver.includes('wsl') || r)
+        ? pass('Running in WSL')
+        : fail('Not in WSL');
+    } catch { return fail('Could not detect WSL'); }
+  },
+
+  /** Check if running in WSL2 specifically */
+  isWSL2() {
+    if (!containerChecks.isWSL().ok) return fail('Not in WSL');
+    try {
+      const ver = fs.readFileSync('/proc/version', 'utf8');
+      return ver.includes('WSL2') || ver.includes('microsoft-standard-WSL2')
+        ? pass('Running in WSL2')
+        : fail('WSL1 (not WSL2)');
+    } catch { return fail('Could not detect WSL version'); }
+  },
+
+  /** Check if running under systemd-nspawn */
+  isNspawn() {
+    try {
+      const env = fs.readFileSync('/proc/1/environ', 'utf8');
+      return env.includes('container=systemd-nspawn')
+        ? pass('Running in systemd-nspawn')
+        : fail('Not in nspawn');
+    } catch { return fail('Not in nspawn'); }
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 21: VM DETECTION
+// ────────────────────────────────────────────────────────────
+
+const vmChecks = {
+  /** Check if running in a virtual machine (best-effort) */
+  isVM() {
+    if (process.platform === 'linux') {
+      try {
+        const r = spawnSync('systemd-detect-virt', ['--vm'], { stdio: 'pipe' });
+        if (r.status === 0) {
+          const virt = r.stdout.toString().trim();
+          return virt !== 'none' ? pass(`VM detected: ${virt}`) : fail('Not a VM (systemd-detect-virt)');
+        }
+      } catch {}
+      try {
+        // Check DMI info
+        const dmi = spawnSync('cat', ['/sys/class/dmi/id/product_name'], { stdio: 'pipe' });
+        const name = (dmi.stdout || '').toString().toLowerCase();
+        const vmSignals = ['virtualbox','vmware','kvm','qemu','xen','hyper-v','microsoft corporation'];
+        const found = vmSignals.find(s => name.includes(s));
+        if (found) return pass(`VM detected: ${found}`);
+      } catch {}
+    }
+    if (process.platform === 'win32') {
+      try {
+        const r = spawnSync('wmic', ['computersystem', 'get', 'model'], { stdio: 'pipe' });
+        const model = r.stdout.toString().toLowerCase();
+        if (model.includes('virtual') || model.includes('vmware') || model.includes('hyper-v'))
+          return pass(`VM detected: ${model.trim()}`);
+      } catch {}
+    }
+    return fail('Could not confirm VM environment');
+  },
+
+  isVirtualBox() {
+    return _checkDMI(['virtualbox','innotek']) ? pass('VirtualBox') : fail('Not VirtualBox');
+  },
+  isVMware() {
+    return _checkDMI(['vmware']) ? pass('VMware') : fail('Not VMware');
+  },
+  isKVM() {
+    return _checkDMI(['kvm','qemu']) ? pass('KVM/QEMU') : fail('Not KVM');
+  },
+  isHyperV() {
+    return _checkDMI(['microsoft','hyper-v']) ? pass('Hyper-V') : fail('Not Hyper-V');
+  },
+  isXen() {
+    return _checkDMI(['xen']) ? pass('Xen') : fail('Not Xen');
+  },
+};
+
+function _checkDMI(signals) {
+  if (process.platform !== 'linux') return false;
+  try {
+    const files = [
+      '/sys/class/dmi/id/product_name',
+      '/sys/class/dmi/id/sys_vendor',
+      '/sys/class/dmi/id/board_vendor',
+    ];
+    for (const f of files) {
+      try {
+        const content = fs.readFileSync(f, 'utf8').toLowerCase();
+        if (signals.some(s => content.includes(s))) return true;
+      } catch {}
+    }
+  } catch {}
+  return false;
+}
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 22: TIME / CLOCK CHECKS
+// ────────────────────────────────────────────────────────────
+
+const timeChecks = {
+  /** Check current hour is within range (local time) */
+  hourBetween(from, to) {
+    const h = new Date().getHours();
+    const ok = from <= to ? (h >= from && h < to) : (h >= from || h < to);
+    return ok ? pass(`Hour ${h} is within ${from}–${to}`) : fail(`Hour ${h} is outside ${from}–${to}`);
+  },
+
+  /** Check current day of week (0=Sun, 6=Sat) */
+  isDayOfWeek(day) {
+    const d = new Date().getDay();
+    return d === day ? pass(`Day of week: ${d}`) : fail(`Day ${d} !== ${day}`);
+  },
+
+  /** Check it's a weekday */
+  isWeekday() {
+    const d = new Date().getDay();
+    return d >= 1 && d <= 5 ? pass('Weekday') : fail('Not a weekday');
+  },
+
+  /** Check Unix timestamp is in a range */
+  timestampBetween(from, to) {
+    const now = Date.now();
+    return now >= from && now <= to
+      ? pass(`timestamp ${now} in [${from}, ${to}]`)
+      : fail(`timestamp ${now} outside [${from}, ${to}]`);
+  },
+
+  /** Check system clock is approximately synced (offset from Date.now vs process start) */
+  clockSynced() {
+    // Best-effort: check NTP service is running on Linux
+    if (process.platform === 'linux') {
+      try {
+        const r = spawnSync('timedatectl', ['status'], { stdio: 'pipe' });
+        const out = r.stdout.toString();
+        if (out.includes('synchronized: yes') || out.includes('NTP synchronized: yes'))
+          return pass('Clock is NTP synchronized');
+        if (out.includes('synchronized: no'))
+          return fail('Clock is NOT NTP synchronized');
+      } catch {}
+    }
+    return pass('Clock sync unknown (assume ok)');
+  },
+
+  /** Current timestamp info */
+  now() { return pass({ ts: Date.now(), iso: new Date().toISOString(), uptime: process.uptime() }); },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 23: PACKAGE / LOCK FILE CHECKS
+// ────────────────────────────────────────────────────────────
+
+const pkgChecks = {
+  /** Check package.json exists in cwd */
+  hasPackageJson() {
+    const p = path.join(process.cwd(), 'package.json');
+    return fs.existsSync(p) ? pass(`package.json found at ${p}`) : fail(`No package.json in ${process.cwd()}`);
+  },
+
+  /** Check lock file exists */
+  hasLockFile() {
+    const locks = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'shrinkwrap.json'];
+    const found = locks.find(l => fs.existsSync(path.join(process.cwd(), l)));
+    return found ? pass(`Lock file: ${found}`) : fail('No lock file found (npm/yarn/pnpm)');
+  },
+
+  /** Check node_modules exists */
+  hasNodeModules() {
+    const p = path.join(process.cwd(), 'node_modules');
+    return fs.existsSync(p) ? pass(`node_modules found`) : fail(`No node_modules in ${process.cwd()} (run npm install)`);
+  },
+
+  /** Read and return package.json contents */
+  packageJson() {
+    const p = path.join(process.cwd(), 'package.json');
+    try {
+      return pass(JSON.parse(fs.readFileSync(p, 'utf8')));
+    } catch (e) { return fail(`Could not read package.json: ${e.message}`); }
+  },
+
+  /** Check package.json has a specific field */
+  hasField(field) {
+    const r = pkgChecks.packageJson();
+    if (!r.ok) return r;
+    return r.value[field] !== undefined
+      ? pass(`package.json has field '${field}'`)
+      : fail(`package.json missing field '${field}'`);
+  },
+
+  /** Check engines.node constraint */
+  enginesNode() {
+    const r = pkgChecks.packageJson();
+    if (!r.ok) return r;
+    const engines = r.value.engines;
+    if (!engines || !engines.node) return pass('No engines.node constraint');
+    return nodeChecks.version(engines.node);
+  },
+};
+
+// ────────────────────────────────────────────────────────────
+//  SECTION 24: SEMVER UTILITIES
+// ────────────────────────────────────────────────────────────
+
+/**
+ * Very lightweight semver constraint checker.
+ * Supports: >=, <=, >, <, =, ^, ~, exact
+ */
+function _semverSatisfies(version, constraint) {
+  const [cMaj, cMin = 0, cPat = 0] = _parseSemver(version);
+  constraint = constraint.trim();
+
+  if (constraint.startsWith('>=')) {
+    const [rMaj, rMin=0, rPat=0] = _parseSemver(constraint.slice(2).trim());
+    return _semverCompare(cMaj,cMin,cPat, rMaj,rMin,rPat) >= 0;
+  }
+  if (constraint.startsWith('<=')) {
+    const [rMaj, rMin=0, rPat=0] = _parseSemver(constraint.slice(2).trim());
+    return _semverCompare(cMaj,cMin,cPat, rMaj,rMin,rPat) <= 0;
+  }
+  if (constraint.startsWith('>')) {
+    const [rMaj, rMin=0, rPat=0] = _parseSemver(constraint.slice(1).trim());
+    return _semverCompare(cMaj,cMin,cPat, rMaj,rMin,rPat) > 0;
+  }
+  if (constraint.startsWith('<')) {
+    const [rMaj, rMin=0, rPat=0] = _parseSemver(constraint.slice(1).trim());
+    return _semverCompare(cMaj,cMin,cPat, rMaj,rMin,rPat) < 0;
+  }
+  if (constraint.startsWith('^')) {
+    // Compatible with: same major, >= minor.patch
+    const [rMaj, rMin=0, rPat=0] = _parseSemver(constraint.slice(1).trim());
+    return cMaj === rMaj && _semverCompare(cMaj,cMin,cPat, rMaj,rMin,rPat) >= 0;
+  }
+  if (constraint.startsWith('~')) {
+    // Approximately: same major.minor, >= patch
+    const [rMaj, rMin=0, rPat=0] = _parseSemver(constraint.slice(1).trim());
+    return cMaj === rMaj && cMin === rMin && cPat >= rPat;
+  }
+  if (constraint.startsWith('=')) {
+    const [rMaj, rMin=0, rPat=0] = _parseSemver(constraint.slice(1).trim());
+    return _semverCompare(cMaj,cMin,cPat, rMaj,rMin,rPat) === 0;
+  }
+  // exact
+  const [rMaj, rMin=0, rPat=0] = _parseSemver(constraint);
+  return _semverCompare(cMaj,cMin,cPat, rMaj,rMin,rPat) === 0;
+}
+
+function _parseSemver(s) {
+  return (s.replace(/^v/, '').match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/) || [0,0,0,0])
+    .slice(1).map(n => parseInt(n || '0', 10));
+}
+
+function _semverCompare(aMaj,aMin,aPat, bMaj,bMin,bPat) {
+  if (aMaj !== bMaj) return aMaj - bMaj;
+  if (aMin !== bMin) return aMin - bMin;
+  return aPat - bPat;
+}
+
+function _humanBytes(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024**2) return `${(bytes/1024).toFixed(1)}KB`;
+  if (bytes < 1024**3) return `${(bytes/1024**2).toFixed(1)}MB`;
+  return `${(bytes/1024**3).toFixed(1)}GB`;
+}
+
+// ────────────────────────────────────────────────────────────
+//  EXPORTS
+// ────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    // Core types
+    pass, fail,
+    KitRequireError,
+    RequireEngine,
+    IOHelper,
+
+    // Namespace check objects (for use without an engine instance)
+    adminChecks,
+    osChecks,
+    cpuChecks,
+    memoryChecks,
+    envChecks,
+    nodeChecks,
+    commandChecks,
+    fsChecks,
+    networkChecks,
+    processChecks,
+    displayChecks,
+    ttyChecks,
+    userChecks,
+    archChecks,
+    ciChecks,
+    containerChecks,
+    vmChecks,
+    timeChecks,
+    pkgChecks,
+
+    // Semver util
+    semverSatisfies: _semverSatisfies,
+
+    // Factory shorthand
+    create: (opts) => new RequireEngine(opts),
+  }
+};