@omega.js/backend 0.1.0

package/dist/manager/libraries/email/validation.js

@@ -0,0 +1,255 @@
+/**
+ * Email validation — single entry point for all email quality checks
+ *
+ * Available checks (run in this order):
+ * - format     — basic email regex
+ * - disposable — checks against known disposable domain list (~7k domains)
+ * - corporate  — blocks corporate/social-media domains (meta.com, instagram.com, soundcloud.com, etc.)
+ * - localPart  — blocks spam/junk local parts (test, noreply, all-numeric, etc.)
+ * - typo       — catches common domain misspellings (gamil., gmai., aol.con, etc.)
+ * - dns        — verifies domain has MX records (no MX = can't receive email, guaranteed fail)
+ * - mailbox    — verifies mailbox exists via API (costs money, requires NEVERBOUNCE_API_KEY or ZEROBOUNCE_API_KEY)
+ *
+ * Usage:
+ *   validate(email)                                          // All free checks (format + disposable + corporate + localPart + typo)
+ *   validate(email, { checks: ['format', 'disposable'] })    // Only format + disposable
+ *   validate(email, { checks: ALL_CHECKS })                  // Everything including dns + mailbox
+ *
+ * Used by:
+ * - routes/marketing/contact/post.js
+ * - routes/user/signup/post.js (ALL_CHECKS before marketing sync; isDisposable() for affiliate fraud prevention)
+ * - libraries/email/marketing/index.js (safety net before Beehiiv/SendGrid add/sync)
+ */
+const path = require('path');
+const dns = require('dns');
+const { promisify } = require('util');
+const neverbounceProvider = require('./validation-provider-neverbounce');
+const zerobounceProvider = require('./validation-provider-zerobounce');
+
+const resolveMx = promisify(dns.resolveMx);
+
+// All data lives in ./data/ — domains and local-part blocklists are co-located JSON files.
+const DATA_DIR = path.join(__dirname, 'data');
+
+// Load disposable domains: curated vendor list + custom additions.
+// The vendor list comes through ./disposable-domains.js — gitignored refresh
+// cache if present, committed seed otherwise (see that module for the contract).
+const DISPOSABLE_DOMAINS = require('./disposable-domains').load();
+const CUSTOM_DISPOSABLE_DOMAINS = require(path.join(DATA_DIR, 'custom-disposable-domains.json'));
+const DISPOSABLE_SET = new Set([
+  ...DISPOSABLE_DOMAINS.map(d => d.toLowerCase()),
+  ...CUSTOM_DISPOSABLE_DOMAINS.map(d => d.toLowerCase()),
+]);
+
+// Load corporate/social-media domains — real mailboxes we never want on marketing lists
+const CORPORATE_DOMAINS = require(path.join(DATA_DIR, 'corporate-domains.json'));
+const CORPORATE_SET = new Set(CORPORATE_DOMAINS.map(d => d.toLowerCase()));
+
+// Load local-part blocklists from ./data/ (JSON for strings, JS for regex patterns)
+const BLOCKED_LOCAL_PARTS_DATA = require(path.join(DATA_DIR, 'blocked-local-parts.json'));
+const BLOCKED_LOCAL_PARTS = new Set(
+  Object.values(BLOCKED_LOCAL_PARTS_DATA).flat().map(p => p.toLowerCase())
+);
+const BLOCKED_LOCAL_PATTERNS = require(path.join(DATA_DIR, 'blocked-local-patterns.js'));
+
+// Load typo-domain prefixes — common misspellings of major providers
+const TYPO_DOMAIN_PREFIXES = require(path.join(DATA_DIR, 'typo-domains.js'));
+const env = require('../env.js');
+
+// Format regex
+const EMAIL_FORMAT = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// Default checks (all free checks — mailbox excluded because it costs money)
+const DEFAULT_CHECKS = ['format', 'disposable', 'corporate', 'localPart', 'typo'];
+
+// All available checks (dns is free but async/slow — opt-in for bulk validation)
+const ALL_CHECKS = ['format', 'disposable', 'corporate', 'localPart', 'typo', 'dns', 'mailbox'];
+
+/**
+ * Validate an email address through selected checks.
+ *
+ * Returns valid: true on mailbox API errors so emails are never silently dropped.
+ *
+ * @param {string} email
+ * @param {object} [options]
+ * @param {Array<string>} [options.checks] - Which checks to run (default: DEFAULT_CHECKS)
+ * @returns {{ valid: boolean, checks: { format?: object, disposable?: object, corporate?: object, localPart?: object, mailbox?: object } }}
+ */
+async function validate(email, options = {}) {
+  const checks = new Set(options.checks || DEFAULT_CHECKS);
+  const result = { valid: true, checks: {} };
+
+  // 1. Format
+  if (checks.has('format')) {
+    if (!email || !EMAIL_FORMAT.test(email)) {
+      result.valid = false;
+      result.checks.format = { valid: false, reason: 'Invalid email format' };
+      return result;
+    }
+
+    result.checks.format = { valid: true };
+  }
+
+  const [rawLocalPart, domain] = (email || '').toLowerCase().split('@');
+
+  // 2. Disposable domain
+  if (checks.has('disposable') && domain) {
+    if (DISPOSABLE_SET.has(domain)) {
+      result.valid = false;
+      result.checks.disposable = { valid: false, blocked: true, domain };
+      return result;
+    }
+
+    result.checks.disposable = { valid: true, blocked: false };
+  }
+
+  // 3. Corporate / social-media domain (real mailbox, but never wanted on marketing lists)
+  if (checks.has('corporate') && domain) {
+    if (CORPORATE_SET.has(domain)) {
+      result.valid = false;
+      result.checks.corporate = { valid: false, blocked: true, domain, reason: 'Corporate/social-media domain' };
+      return result;
+    }
+
+    result.checks.corporate = { valid: true, blocked: false };
+  }
+
+  // 4. Local part — strip +suffix before checking
+  if (checks.has('localPart') && rawLocalPart) {
+    const localPart = rawLocalPart.split('+')[0];
+
+    if (BLOCKED_LOCAL_PARTS.has(localPart)) {
+      result.valid = false;
+      result.checks.localPart = { valid: false, blocked: true, localPart, reason: 'Blocked local part' };
+      return result;
+    }
+
+    const blockedPattern = BLOCKED_LOCAL_PATTERNS.find((p) => p.test(localPart));
+
+    if (blockedPattern) {
+      result.valid = false;
+      result.checks.localPart = { valid: false, blocked: true, localPart, reason: 'Matches junk pattern' };
+      return result;
+    }
+
+    result.checks.localPart = { valid: true };
+  }
+
+  // 5. Typo domain — common misspellings of major providers
+  if (checks.has('typo') && domain) {
+    const matchedPrefix = TYPO_DOMAIN_PREFIXES.find((prefix) => domain.startsWith(prefix));
+
+    if (matchedPrefix) {
+      result.valid = false;
+      result.checks.typo = { valid: false, domain, matchedPrefix, reason: 'Likely misspelled domain' };
+      return result;
+    }
+
+    result.checks.typo = { valid: true };
+  }
+
+  // 6. DNS — guaranteed-fail checks (no MX, null MX, loopback MX, domain not found)
+  if (checks.has('dns') && domain) {
+    try {
+      const records = await resolveMx(domain);
+
+      if (!records || records.length === 0) {
+        result.valid = false;
+        result.checks.dns = { valid: false, domain, reason: 'No MX records' };
+        return result;
+      }
+
+      // Null MX (RFC 7505): exchange is empty or "." — domain explicitly rejects email
+      const hasNullMx = records.some((r) => !r.exchange || r.exchange === '.');
+      if (hasNullMx) {
+        result.valid = false;
+        result.checks.dns = { valid: false, domain, reason: 'Null MX (domain rejects email)' };
+        return result;
+      }
+
+      // Loopback MX: points to localhost or 0.0.0.0 — can't receive external mail
+      const hasLoopbackMx = records.some((r) =>
+        r.exchange === 'localhost'
+        || r.exchange === '0.0.0.0'
+        || r.exchange.startsWith('127.')
+        || r.exchange.endsWith('.invalid'),
+      );
+      if (hasLoopbackMx) {
+        result.valid = false;
+        result.checks.dns = { valid: false, domain, reason: 'Loopback MX (localhost/invalid)' };
+        return result;
+      }
+
+      result.checks.dns = { valid: true, mxCount: records.length };
+    } catch (e) {
+      if (e.code === 'ENOTFOUND' || e.code === 'ENODATA' || e.code === 'ESERVFAIL') {
+        result.valid = false;
+        result.checks.dns = { valid: false, domain, reason: `DNS lookup failed: ${e.code}` };
+        return result;
+      }
+      // Network error or timeout — don't block the email
+      result.checks.dns = { valid: true, skipped: true, reason: `DNS error: ${e.code}` };
+    }
+  }
+
+  // 7. Mailbox verification (NeverBounce preferred, ZeroBounce fallback)
+  if (checks.has('mailbox')) {
+    const provider = env.get('NEVERBOUNCE_API_KEY')
+      ? neverbounceProvider
+      : (env.get('ZEROBOUNCE_API_KEY') ? zerobounceProvider : null);
+
+    if (!provider) {
+      result.checks.mailbox = { valid: true, skipped: true, reason: 'No API key', provider: null };
+      return result;
+    }
+
+    const mailboxResult = await provider.verify(email);
+    result.checks.mailbox = mailboxResult;
+
+    if (!mailboxResult.valid) {
+      result.valid = false;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Quick check: is this email from a disposable domain?
+ * Works with a full email address or just a domain.
+ *
+ * @param {string} emailOrDomain
+ * @returns {boolean}
+ */
+function isDisposable(emailOrDomain) {
+  if (!emailOrDomain) {
+    return false;
+  }
+
+  const domain = emailOrDomain.includes('@')
+    ? emailOrDomain.split('@')[1]
+    : emailOrDomain;
+
+  return DISPOSABLE_SET.has(domain.toLowerCase());
+}
+
+/**
+ * Quick check: is this email from a blocked corporate/social-media domain?
+ * Works with a full email address or just a domain.
+ *
+ * @param {string} emailOrDomain
+ * @returns {boolean}
+ */
+function isCorporate(emailOrDomain) {
+  if (!emailOrDomain) {
+    return false;
+  }
+
+  const domain = emailOrDomain.includes('@')
+    ? emailOrDomain.split('@')[1]
+    : emailOrDomain;
+
+  return CORPORATE_SET.has(domain.toLowerCase());
+}
+
+module.exports = { validate, isDisposable, isCorporate, DEFAULT_CHECKS, ALL_CHECKS };

package/dist/manager/libraries/env.js

@@ -0,0 +1,198 @@
+/**
+ * The ONE env reader ([#581](https://github.com/Omega-JS-Stack/omega/issues/581)).
+ *
+ * Every framework read of a brand-supplied key goes through here instead of
+ * touching `process.env` directly, so three things stop being possible: a
+ * key nobody declared (`get()` refuses a name the env schema does not know —
+ * a typo used to resolve to `undefined` forever), a required key discovered
+ * at a customer's first action instead of at boot (`assertRequired()`), and
+ * two readers of one secret drifting apart (#569's raw read beside its own
+ * helper).
+ *
+ * The schema is @omega.js/config's `ENV_SCHEMA` — the same list the manager
+ * mints from, groups a brand .env by, and composes `targets/backend/.env`
+ * from — so "what the backend needs" has one home shared with the thing that
+ * provides it. Runtime/platform vars are NOT in it and never come through
+ * here: `FIREBASE_CONFIG`, `FUNCTIONS_EMULATOR`, `GCLOUD_PROJECT`, the
+ * `OMEGA_*_PORT` map, the test-mode switches — those are the runtime's own
+ * facts about itself, not a brand's credentials.
+ *
+ * A key whose value must differ between a local run and a deployed one is NOT
+ * this reader's business ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)):
+ * the brand's `.env.<environment>` overlay supplies the other value and the
+ * cascade resolves it before anything reaches here, so `env.get()` reads ONE
+ * name in every environment.
+ *
+ * Values are never printed. Errors name the KEY and the fix.
+ */
+const { envSchemaEntry, requiredEnvKeys, envEnvironment } = require('../../vendor/config/index.js');
+const { checkEnvRules } = require('../../vendor/config/env-rules.js');
+
+/**
+ * The runtime environment — what the Manager's `getEnvironment()` and the three
+ * `is*()` checks return. It is @omega.js/config's `envEnvironment()`, the ONE
+ * home of the vocabulary: the same three names the `.env.<environment>` overlay
+ * files are spelled with (#586), so a `.env.development` and a
+ * `Manager.isDevelopment()` can never mean different things.
+ *
+ * Re-exported here because the provider libraries below already read the
+ * environment through this reader and hold no Manager handle.
+ *
+ * @returns {'testing'|'production'|'development'} The environment.
+ */
+const environment = envEnvironment;
+
+/** How a missing key gets fixed, by who is supposed to provide it. */
+function remedy(entry) {
+  return entry && typeof entry.generated === 'function'
+    ? 'Run `npx omega manage` at the brand root (it mints the key), then redeploy the backend.'
+    : 'Add it to the brand .env, then redeploy: every backend verb composes dist/.env from the cascade.';
+}
+
+/**
+ * The resolved value of a declared env key: the cascade's value, else the
+ * schema's static default, else undefined. An empty string reads as absent — a
+ * key set to nothing is not set.
+ *
+ * @param {string} name - The env var name.
+ * @returns {string|undefined} The value.
+ * @throws {Error} UnknownEnvKeyError when the schema does not declare `name`.
+ */
+function get(name) {
+  const entry = envSchemaEntry(name);
+
+  if (!entry) {
+    // Programmer error, not configuration: reading an undeclared key can only
+    // ever return undefined, so it fails at the read instead of at the symptom
+    const error = new Error(`${name} is not declared in the env schema (@omega.js/config's env-schema.js) — declare it there, or read a runtime var directly.`);
+    error.name = 'UnknownEnvKeyError';
+    throw error;
+  }
+
+  return process.env[name] || entry.default;
+}
+
+/**
+ * Whether a declared env key resolves to a value — the switch every optional
+ * provider gates on (`env.has('SENDGRID_API_KEY')`).
+ *
+ * @param {string} name - The env var name.
+ * @returns {boolean} True when the key resolves to a non-empty value.
+ */
+function has(name) {
+  return !!get(name);
+}
+
+/**
+ * The value of a key the caller cannot proceed without.
+ *
+ * @param {string} name - The env var name.
+ * @returns {string} The value.
+ * @throws {Error} MissingEnvKeyError (code 500) naming the key and the fix.
+ */
+function require_(name) {
+  const value = get(name);
+  if (value) { return value; }
+
+  const entry = envSchemaEntry(name);
+  // code 500 like the libraries' other faults (errorWithCode): a missing key
+  // is the server's misconfiguration, never the caller's input
+  const error = new Error(`${name} is missing from the .env cascade — ${entry.description} ${remedy(entry)}`);
+  error.name = 'MissingEnvKeyError';
+  error.code = 500;
+  throw error;
+}
+
+/**
+ * Validate every key this target refuses to run without, in ONE pass — the
+ * boot guard. Missing keys are reported together: a brand fixes its .env
+ * once, not once per restart.
+ *
+ * @param {string} [target] - The target whose required keys to check.
+ * @throws {Error} MissingEnvKeysError (code 500) listing every missing key.
+ */
+function assertRequired(target = 'backend') {
+  const missing = requiredEnvKeys(target).filter((name) => !get(name));
+  if (missing.length === 0) { return; }
+
+  const lines = missing.map((name) => `  - ${name}: ${envSchemaEntry(name).description}`);
+  const error = new Error(
+    `${missing.length} required env ${missing.length === 1 ? 'key is' : 'keys are'} missing from the .env cascade:\n${lines.join('\n')}\n`
+    + `${remedy(envSchemaEntry(missing[0]))}`,
+  );
+  error.name = 'MissingEnvKeysError';
+  error.code = 500;
+  error.keys = missing;
+  throw error;
+}
+
+/**
+ * Validate every key this brand's OWN config made mandatory — the schema's
+ * `requiredWhen` rules ([#626](https://github.com/Omega-JS-Stack/omega/issues/626)).
+ *
+ * `assertRequired` above covers the keys OMEGA needs no matter what a brand
+ * configures. This is the other half: a config path that is set makes its key
+ * mandatory (a GA4 Measurement ID with no Measurement Protocol secret sends no
+ * events; a reCAPTCHA site key with no secret half 403s every protected POST).
+ * The rule is declared once in the env schema and evaluated by ONE checker
+ * shared with the manager's manage-time pass — this reader only decides what a
+ * violation costs, which the caller in index.js resolves: production refuses,
+ * everything else warns and continues.
+ *
+ * Violations name the BRAND-LEVEL key (GOOGLE_ANALYTICS_SECRET_BACKEND, not
+ * the GOOGLE_ANALYTICS_SECRET it is delivered as), because that is the name a
+ * human puts in the brand .env.
+ *
+ * @param {object} config - The resolved omega.json5 config.
+ * @param {string} [target] - The target whose rules to check.
+ * @throws {Error} MissingConditionalEnvKeysError (code 500) naming every key
+ *   and the config path that made it mandatory.
+ */
+function assertRules(config, target = 'backend') {
+  // The checker answers for BOTH schema rules; the unconditional `required`
+  // half is assertRequired's above, and reporting a key twice in one boot
+  // would just be noise.
+  const violations = checkEnvRules(config, process.env, { target })
+    .filter((violation) => violation.rule === 'requiredWhen');
+  if (violations.length === 0) { return; }
+
+  const named = violations.map(({ key, path }) => (path ? `${key} (required by ${path})` : key)).join(', ');
+  const error = new Error(
+    `${violations.length} env ${violations.length === 1 ? 'key this brand\'s config requires is' : 'keys this brand\'s config requires are'} missing from the .env cascade: ${named}. `
+    + `${remedy(envSchemaEntry(violations[0].key))}`,
+  );
+  error.name = 'MissingConditionalEnvKeysError';
+  error.code = 500;
+  error.keys = violations.map((violation) => violation.key);
+  throw error;
+}
+
+/**
+ * Whether a boot that FAILED assertRequired() may warn and continue instead
+ * of refusing. Exactly one lane qualifies: a process with no consumer
+ * omega.json5 is not a brand's backend at all — it is the framework booting
+ * itself (its offline unit lanes, a bare require of the package), where there
+ * is no brand for a manage run to have minted keys into. Anything shaped like
+ * a brand refuses in EVERY environment, development included (#569's
+ * production-only branch is gone): the key is one `npx omega manage` away,
+ * and a dev loop that boots without it just moves the crash to a customer.
+ * The self-test fixture IS brand-shaped, so it gets its required keys seeded
+ * the same way a real brand does — see ensureFixtureEnv in cli/commands/test.js.
+ *
+ * @param {object} context
+ * @param {boolean} context.hasConsumerConfig - Whether a consumer omega.json5 resolved.
+ * @returns {boolean} True when the fault is advisory.
+ */
+function guardIsAdvisory({ hasConsumerConfig }) {
+  return !hasConsumerConfig;
+}
+
+module.exports = {
+  environment,
+  get,
+  has,
+  require: require_,
+  assertRequired,
+  assertRules,
+  guardIsAdvisory,
+};

package/dist/manager/libraries/infer-contact.js

@@ -0,0 +1,101 @@
+/**
+ * Shared contact inference library
+ *
+ * Infers first/last name and company from an email address using AI.
+ * Requires OPENAI_API_KEY to be set.
+ *
+ * Usage:
+ *   const { inferContact } = require('./libraries/infer-contact.js');
+ *   const result = await inferContact(email, ctx);
+ *   // { firstName, lastName, company, confidence, method }
+ */
+const path = require('path');
+const env = require('./env.js');
+
+const PROMPT_PATH = path.join(__dirname, 'prompts', 'infer-contact.md');
+
+/**
+ * Infer contact info from email address using AI
+ *
+ * @param {string} email - Email address
+ * @param {object} ctx - Assistant instance (for AI access)
+ * @returns {{ firstName: string, lastName: string, company: string, confidence: number, method: string }}
+ */
+async function inferContact(email, ctx) {
+  if (env.get('OPENAI_API_KEY')) {
+    const aiResult = await inferContactWithAI(email, ctx);
+    if (aiResult) {
+      return aiResult;
+    }
+    ctx?.log(`inferContact: AI returned null for ${email} — falling back to empty result`);
+  } else {
+    ctx?.log(`inferContact: OPENAI_API_KEY not set — skipping AI inference for ${email}`);
+  }
+
+  return { firstName: '', lastName: '', company: '', confidence: 0, method: 'none' };
+}
+
+/**
+ * Use AI to infer contact info from email
+ *
+ * @param {string} email - Email address
+ * @param {object} ctx - Assistant instance
+ * @returns {object|null} Inferred contact or null on failure
+ */
+async function inferContactWithAI(email, ctx) {
+  try {
+    const ai = ctx.Manager.AI(ctx, env.get('OPENAI_API_KEY'));
+    const result = await ai.request({
+      model: 'gpt-5.4-mini',
+      timeout: 60000,
+      maxTokens: 1024 * 2,
+      moderate: false,
+      response: 'json',
+      prompt: {
+        path: PROMPT_PATH,
+      },
+      message: {
+        content: `Email: ${email}`,
+      },
+    });
+
+    const parsed = result?.content;
+    if (parsed?.firstName !== undefined) {
+      const inferred = {
+        firstName: capitalize(parsed.firstName || ''),
+        lastName: capitalize(parsed.lastName || ''),
+        company: capitalize(parsed.company || ''),
+        confidence: typeof parsed.confidence === 'number' ? parsed.confidence : 0.5,
+        method: 'ai',
+      };
+      if (!inferred.firstName && !inferred.lastName && !inferred.company) {
+        ctx?.log(`inferContactWithAI: AI parsed response had ALL fields empty for ${email}. Raw:`, parsed);
+      }
+      return inferred;
+    }
+
+    ctx?.log(`inferContactWithAI: AI response missing firstName for ${email}. Raw result:`, result);
+  } catch (e) {
+    ctx?.error('inferContactWithAI: Failed:', e);
+  }
+
+  return null;
+}
+
+/**
+ * Capitalize first letter of each word
+ *
+ * @param {string} str - String to capitalize
+ * @returns {string} Capitalized string
+ */
+function capitalize(str) {
+  if (!str) {
+    return '';
+  }
+  return str
+    .split(' ')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(' ');
+}
+
+module.exports = { inferContact, capitalize };

package/dist/manager/libraries/load-provider.js

@@ -0,0 +1,65 @@
+/**
+ * Safe dynamic provider loader — the ONE way to require a provider module by name.
+ *
+ * Confines the require() to the given providers directory: names are strictly
+ * lowercase [a-z0-9-], so a caller-controlled value can never traverse out
+ * (`../`, absolute paths, or dots are rejected before any path math happens).
+ */
+const path = require('path');
+
+const NAME_PATTERN = /^[a-z0-9-]+$/;
+const ID_PATTERN = /^[a-z0-9_-]+(?::[a-z0-9_-]+)*$/;
+
+/**
+ * The file `${dir}/${name}.js` resolves to, rejecting any name that could
+ * escape the directory. Split out of loadProvider so a caller that searches
+ * SEVERAL directories (the connections lane: the brand's dir, then the package's)
+ * can ask whether a file is there without owning a second copy of the name
+ * rule ([#771](https://github.com/Omega-JS-Stack/omega/issues/771)).
+ *
+ * @param {string} dir - Absolute path of the providers directory
+ * @param {string} name - Provider name (strictly [a-z0-9-])
+ * @returns {string} Absolute path of the provider file
+ * @throws {Error} When the name is not a valid provider name
+ */
+function providerPath(dir, name) {
+  if (typeof name !== 'string' || !NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid provider name: ${name}`);
+  }
+
+  return path.join(dir, `${name}.js`);
+}
+
+/**
+ * Load `${dir}/${name}.js`, rejecting any name that could escape the directory.
+ *
+ * @param {string} dir - Absolute path of the providers directory
+ * @param {string} name - Provider name (strictly [a-z0-9-])
+ * @returns {*} The required module
+ * @throws {Error} When the name is not a valid provider name
+ */
+function loadProvider(dir, name) {
+  return require(providerPath(dir, name));
+}
+
+/**
+ * Load a module by colon-joined id (e.g. "general:download-app-link" →
+ * `${dir}/general/download-app-link.js`), rejecting any id that could escape
+ * the directory: every segment is strictly [a-z0-9_-].
+ *
+ * @param {string} dir - Absolute path of the modules directory
+ * @param {string} id - Colon-joined module id
+ * @returns {*} The required module
+ * @throws {Error} When the id is not a valid module id
+ */
+function loadTemplate(dir, id) {
+  if (typeof id !== 'string' || !ID_PATTERN.test(id)) {
+    throw new Error(`Invalid template id: ${id}`);
+  }
+
+  return require(path.join(dir, `${id.split(':').join('/')}.js`));
+}
+
+module.exports = loadProvider;
+module.exports.providerPath = providerPath;
+module.exports.loadTemplate = loadTemplate;