@omega.js/manager 0.1.0

package/dist/services/domain/index.js

@@ -0,0 +1,69 @@
+/**
+ * Domain service — points the registrar at Cloudflare. Runs after cloudflare
+ * (the zone must exist so its assigned nameservers are known). API-capable
+ * registrars (namecheap) are reconciled automatically; manual registrars get
+ * printed instructions, and only while the zone is still pending — an active
+ * zone proves the nameservers are already set.
+ *
+ * The email half of `domain` config (email.providers, email.forwarding) is
+ * consumed by the cloudflare service (dns-records MX/SPF + email-routing);
+ * this service owns only the registrar side.
+ *
+ * Auth: NAMECHEAP_USERNAME + NAMECHEAP_API_KEY in the brand .env (namecheap
+ * only), plus CLOUDFLARE_TOKEN to read the zone's assigned nameservers.
+ * Missing credentials → the service skips with guidance.
+ */
+const chalk = require('chalk').default;
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { CloudflareAPI } = require('../edge/lib/cloudflare-api.js');
+const { getApexDomain } = require('../../lib/domain-utils.js');
+const { NamecheapAPI } = require('./lib/namecheap-api.js');
+const { API_PROVIDERS, resolveRegistrar } = require('./lib/registrars.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const domainConfig = context.brandConfig.domain || {};
+
+    if (domainConfig.enabled === false) {
+      return { skip: true, reason: 'domain.enabled = false' };
+    }
+
+    const provider = resolveRegistrar(context.brandConfig);
+    if (!provider) {
+      return { skip: true, reason: 'no domain.providers.<registrar> configured' };
+    }
+
+    const url = (context.brandConfig.brand?.url || '').replace(/^https?:\/\//, '');
+    if (!url) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    // The zone lookup needs Cloudflare even for manual registrars — the
+    // required nameserver values come from the zone
+    // The input descriptors live in the REQUIRES registry (one home): the
+    // Cloudflare token is unconditional, the namecheap credentials are
+    // registrar-specific (their entry-level `when` drops them for the rest)
+    if (!context.cloudflareApi) {
+      const gate = await requestServiceInput(context, serviceInputSpec('domain', { names: ['CLOUDFLARE_TOKEN'] }));
+      if (gate) return gate;
+    }
+
+    if (provider === 'namecheap' && !context.namecheapApi) {
+      const gate = await requestServiceInput(context, serviceInputSpec('domain', { names: ['NAMECHEAP_USERNAME', 'NAMECHEAP_API_KEY'] }));
+      if (gate) return gate;
+    }
+
+    console.log(`    Provider: ${chalk.cyan(provider)}${API_PROVIDERS.has(provider) ? '' : chalk.dim(' (manual)')}`);
+
+    // Tests inject fake clients via context.cloudflareApi / context.namecheapApi
+    return {
+      cloudflareApi: context.cloudflareApi || new CloudflareAPI(),
+      namecheapApi: provider === 'namecheap' ? (context.namecheapApi || new NamecheapAPI()) : null,
+      domain: getApexDomain(url), // nameservers live on the apex's registrar entry
+      provider,
+    };
+  },
+});

package/dist/services/domain/lib/namecheap-api.js

@@ -0,0 +1,167 @@
+/**
+ * Namecheap API client — XML query API (there is no JSON variant), ported from
+ * omega-manager. Requires the caller's IP to be whitelisted in the Namecheap
+ * dashboard; the client detects its public IP via api.ipify.org.
+ *
+ * Docs: https://www.namecheap.com/support/api/methods/
+ */
+
+const API_BASE = 'https://api.namecheap.com/xml.response';
+
+/**
+ * The Namecheap API access page — enabling the API, resetting the key and the
+ * IP whitelist all live on this ONE page, which is why every rejection in that
+ * family opens the root and never a deep link (#698, Ian 2026-08-30).
+ */
+const API_ACCESS_URL = 'https://ap.www.namecheap.com/settings/tools/apiaccess/';
+
+// Namecheap refuses a caller whose IP is not whitelisted with the API-access
+// error family — the same numbers a disabled API or a stale key answer with,
+// and all three are fixed on the page above.
+const API_ACCESS_ERROR_CODES = new Set(['1011102', '1011150']);
+const API_ACCESS_ERROR_TEXT = /whitelist|api access has not been enabled|invalid request ip/i;
+
+/**
+ * Whether a thrown API error is the IP-whitelist rejection — the walkthrough's
+ * trigger. Reads the error Number the client parses off the <Error> element,
+ * with the message as the second signal.
+ *
+ * @param {Error} error - An error thrown by makeRequest
+ * @returns {boolean}
+ */
+function isWhitelistError(error) {
+  return API_ACCESS_ERROR_CODES.has(error?.namecheapCode)
+    || API_ACCESS_ERROR_TEXT.test(error?.message || '');
+}
+
+class NamecheapAPI {
+  constructor(options = {}) {
+    this.username = options.username || process.env.NAMECHEAP_USERNAME;
+    this.apiKey = options.apiKey || process.env.NAMECHEAP_API_KEY;
+
+    if (!this.username || !this.apiKey) {
+      throw new Error('Namecheap API not configured. Set NAMECHEAP_USERNAME and NAMECHEAP_API_KEY in the brand .env');
+    }
+  }
+
+  async getClientIp() {
+    if (this._clientIp) {
+      return this._clientIp;
+    }
+    const response = await fetch('https://api.ipify.org?format=json');
+    const data = await response.json();
+    this._clientIp = data.ip;
+    return this._clientIp;
+  }
+
+  async makeRequest(command, params = {}) {
+    const clientIp = await this.getClientIp();
+
+    const queryParams = new URLSearchParams({
+      ApiUser: this.username,
+      ApiKey: this.apiKey,
+      UserName: this.username,
+      ClientIp: clientIp,
+      Command: command,
+      ...params,
+    });
+
+    const url = `${API_BASE}?${queryParams.toString()}`;
+    const response = await fetch(url);
+    const xml = await response.text();
+
+    const status = xml.match(/Status="(\w+)"/)?.[1];
+    if (status !== 'OK') {
+      // Namecheap nests the elements (<Errors><Error Number="…">msg</Error>),
+      // so the attribute group must be optional-but-space-led — otherwise the
+      // wrapper matches first and the message carries the inner tag with it.
+      const failure = xml.match(/<Error(\s[^>]*)?>(.*?)<\/Error>/);
+      const error = new Error(`Namecheap API error: ${failure?.[2] || 'Unknown error'}`);
+      // The whitelist walkthrough (#698) needs both: WHICH rejection this is,
+      // and the IP to add — the XML never echoes it, so the client that sent
+      // it is the only source.
+      error.namecheapCode = failure?.[1]?.match(/Number="(\d+)"/)?.[1] || null;
+      error.clientIp = clientIp;
+      throw error;
+    }
+
+    return xml;
+  }
+
+  /**
+   * List all domains in the account
+   * @returns {Array<{domain: string, sld: string, tld: string, expires: string}>}
+   */
+  async listDomains() {
+    const xml = await this.makeRequest('namecheap.domains.getList', {
+      PageSize: 100,
+    });
+
+    const domains = [];
+    const domainRegex = /<Domain\s+([^>]+)\/>/g;
+    let match;
+
+    while ((match = domainRegex.exec(xml)) !== null) {
+      const attrs = match[1];
+      const name = attrs.match(/Name="([^"]+)"/)?.[1];
+
+      if (name) {
+        const parts = name.split('.');
+        const tld = parts.pop();
+        const sld = parts.join('.');
+
+        domains.push({
+          domain: name.toLowerCase(),
+          sld,
+          tld,
+          expires: attrs.match(/Expires="([^"]+)"/)?.[1] || null,
+        });
+      }
+    }
+
+    return domains;
+  }
+
+  /**
+   * Get current DNS settings for a domain
+   * @param {string} sld - Second level domain (e.g. 'mybrand')
+   * @param {string} tld - Top level domain (e.g. 'com', 'co.uk')
+   * @returns {Object} - { usingCustom: boolean, nameservers: string[] }
+   */
+  async getDns(sld, tld) {
+    const xml = await this.makeRequest('namecheap.domains.dns.getList', {
+      SLD: sld,
+      TLD: tld,
+    });
+
+    const isCustom = xml.includes('IsUsingOurDNS="false"');
+    const nameservers = [];
+    const nsRegex = /<Nameserver>(.*?)<\/Nameserver>/g;
+    let match;
+
+    while ((match = nsRegex.exec(xml)) !== null) {
+      nameservers.push(match[1].toLowerCase());
+    }
+
+    return {
+      usingCustom: isCustom,
+      nameservers,
+    };
+  }
+
+  /**
+   * Set custom nameservers for a domain
+   * @param {string} sld - Second level domain
+   * @param {string} tld - Top level domain
+   * @param {string[]} nameservers - Array of nameserver hostnames
+   */
+  async setCustomNameservers(sld, tld, nameservers) {
+    await this.makeRequest('namecheap.domains.dns.setCustom', {
+      SLD: sld,
+      TLD: tld,
+      Nameservers: nameservers.join(','),
+    });
+  }
+}
+
+module.exports = { NamecheapAPI, API_ACCESS_URL, isWhitelistError };

package/dist/services/domain/lib/registrars.js

@@ -0,0 +1,46 @@
+/**
+ * Domain-role knowledge shared across services — which providers the domain
+ * service can drive via API (their nameservers need no human), the dashboard
+ * nameserver pages for the manual ones (the cloudflare zone flow opens them
+ * while polling for activation), and the two provider resolvers.
+ *
+ * `domain` carries TWO roles, each with its own providers block (#425): the
+ * registrar at `domain.providers.<registrar>` and the mailbox provider at
+ * `domain.email.providers.<provider>`. Presence picks one — @omega.js/config's
+ * chosenProvider owns that rule — and no entry at all means nothing chosen,
+ * exactly what the old null provider meant: the domain service skips and
+ * cloudflare's email operations stay off.
+ */
+const { chosenProvider } = require('../../../vendor/config/index.js');
+
+// Providers whose nameservers the domain service sets via API
+const API_PROVIDERS = new Set(['namecheap']);
+
+// Nameserver-management pages per registrar (manual providers get these
+// opened in the browser during the zone-activation flow)
+const REGISTRAR_NAMESERVER_URLS = {
+  squarespace: (domain) => `https://account.squarespace.com/domains/managed/${domain}/dns/domain-nameservers`,
+  namecheap: (domain) => `https://ap.www.namecheap.com/domains/domaincontrolpanel/${domain}/domain`,
+};
+
+/**
+ * The brand's domain registrar (`domain.providers.<registrar>`).
+ *
+ * @param {Object} brandConfig - Resolved brand config
+ * @returns {string|null} - 'namecheap' | 'squarespace' | … | null
+ */
+function resolveRegistrar(brandConfig) {
+  return chosenProvider(brandConfig?.domain?.providers);
+}
+
+/**
+ * The brand's mailbox provider (`domain.email.providers.<provider>`).
+ *
+ * @param {Object} brandConfig - Resolved brand config
+ * @returns {string|null} - 'cloudflare' | 'squarespace' | 'privateemail' | … | null
+ */
+function resolveEmailProvider(brandConfig) {
+  return chosenProvider(brandConfig?.domain?.email?.providers);
+}
+
+module.exports = { API_PROVIDERS, REGISTRAR_NAMESERVER_URLS, resolveRegistrar, resolveEmailProvider };

package/dist/services/domain/lib/whitelist-walkthrough.js

@@ -0,0 +1,76 @@
+/**
+ * The Namecheap IP-whitelist walkthrough (#698).
+ *
+ * Namecheap refuses every API call from an IP that is not on its whitelist, so
+ * a new machine — or the same machine on a new network — fails the domain
+ * service on every run. Rather than warn forever, an interactive walk drives
+ * the fix in place: the house open-and-poll idiom gates on Enter, opens the
+ * apiaccess ROOT page (enable, key reset and whitelist all live there), names
+ * the IP to add, and RE-CHECKS the refused call — ENTER checks now, `s` steps
+ * aside.
+ *
+ * Non-interactive and dry runs never sit here: they print the page and the IP
+ * and hand the warn back to the caller, exactly as before.
+ */
+const chalk = require('chalk').default;
+const { openBrowserAndPoll } = require('../../../vendor/devkit/flows.js');
+const { canPrompt } = require('../../../lib/run-gates.js');
+const { API_ACCESS_URL, isWhitelistError } = require('./namecheap-api.js');
+
+/**
+ * Walk the user through whitelisting the caller IP, retrying the refused call
+ * until it passes or the user steps aside.
+ *
+ * @param {Error} error - The rejection (carries `clientIp` from the client).
+ * @param {Function} retry - Async () => the refused call, run again.
+ * @param {object} [options] - Run options (a dry run or no TTY never prompts).
+ * @returns {Promise<{ success: boolean, result?: any, error?: string }>} -
+ *   `result` is the retried call's value once Namecheap accepts it; `error` is
+ *   the recheck's OWN failure when it got past the whitelist and failed anyway.
+ */
+async function walkWhitelist(error, retry, options = {}) {
+  const { clientIp } = error;
+
+  console.log(`      ${chalk.yellow('⚠')} Namecheap refused this machine's IP ${chalk.cyan(clientIp)} — it is not on the API whitelist`);
+
+  if (!canPrompt(options)) {
+    console.log(`      ${chalk.dim(`→ Add it under "Whitelisted IPs" at ${API_ACCESS_URL}, then rerun`)}`);
+    return { success: false };
+  }
+
+  const result = await openBrowserAndPoll({
+    url: API_ACCESS_URL,
+    label: 'the Namecheap API access page',
+    promptMessage: `Add ${clientIp} under "Whitelisted IPs" (the same page enables API access and resets the key).`,
+    waitMessage: 'Rechecking the Namecheap API',
+    check: async () => {
+      try {
+        return { done: true, result: await retry() };
+      } catch (retryError) {
+        // Still refused — keep waiting. Any other failure is the walk's answer.
+        return isWhitelistError(retryError) ? { done: false } : { done: true, error: retryError.message };
+      }
+    },
+    intervalMs: 10000,
+    indent: '      ',
+  });
+
+  if (result.success) {
+    console.log(`      ${chalk.green('✓')} Namecheap accepted the call — the IP is whitelisted`);
+    return { success: true, result: result.result };
+  }
+
+  // The recheck got PAST the whitelist and failed for its own reason — say so,
+  // and hand it back: it is the truer answer, not the stale rejection (#698).
+  // The whitelist closer would be false here, so it only prints when the walk
+  // really ended on the rejection.
+  if (result.error) {
+    console.log(`      ${chalk.yellow('⚠')} The recheck failed${chalk.dim(`: ${result.error}`)}`);
+    return { success: false, error: result.error };
+  }
+
+  console.log(`      ${chalk.dim('⊘ Still refused — rerun once the IP is whitelisted')}`);
+  return { success: false };
+}
+
+module.exports = { walkWhitelist };

package/dist/services/edge/ensure/cache-rules.js

@@ -0,0 +1,105 @@
+/**
+ * Ensure cache rules match `edge.providers.cloudflare.cacheRules`.
+ *
+ * 1. Reads the http_request_cache_settings entrypoint ruleset (or notes it needs creating).
+ * 2. Diffs each configured rule by description — creates missing, updates stale, removes unconfigured.
+ * 3. POSTs a new ruleset if missing; PUTs the merged ruleset if updating.
+ */
+const chalk = require('chalk').default;
+const { cacheRead } = require('../lib/read-cache.js');
+const { fetchRuleset, applyRuleset, getZoneId, zoneGate } = require('../lib/ruleset-helper.js');
+
+module.exports = async function ensureCacheRules(context) {
+  const { cloudflareApi: api, brandRoot, brandConfig, options = {} } = context;
+  const zoneId = getZoneId(context);
+  const gated = zoneGate(context, 'cacheRules');
+  if (gated) return gated;
+
+  // === READ ===
+  const { ruleset, needsCreate } = await fetchRuleset(api, zoneId, 'http_request_cache_settings');
+  const readCount = ruleset?.rules?.length || 0;
+  console.log(`      ${chalk.green('✓')} Read ${chalk.dim(`(${readCount} items)`)}`);
+  cacheRead(brandRoot, 'cache-rules', { count: readCount, ruleset, needsCreate });
+
+  // === DIFF ===
+  const cacheRulesConfig = brandConfig?.edge?.providers?.cloudflare?.cacheRules;
+  if (!cacheRulesConfig || !Array.isArray(cacheRulesConfig) || cacheRulesConfig.length === 0) {
+    console.log(`      ${chalk.dim('⊘ No changes needed')}`);
+    return;
+  }
+
+  const modifiedRules = ruleset?.rules ? [...ruleset.rules] : [];
+  let hasChanges = false;
+
+  for (const configRule of cacheRulesConfig) {
+    const ruleName = configRule.name;
+    const ruleIndex = modifiedRules.findIndex((rule) => rule.description === ruleName);
+    const currentRule = ruleIndex >= 0 ? modifiedRules[ruleIndex] : null;
+
+    const expectedRule = {
+      ...(currentRule || {}),
+      action: 'set_cache_settings',
+      action_parameters: {
+        cache: true,
+        // Nullish, never falsy: 0 is a legal TTL a brand can mean (#754)
+        edge_ttl: { mode: 'override_origin', default: configRule.edgeTtl ?? 31536000 },
+        browser_ttl: { mode: 'override_origin', default: configRule.browserTtl ?? 14400 },
+      },
+      expression: configRule.expression || currentRule?.expression,
+      description: ruleName,
+      enabled: configRule.enabled !== undefined ? configRule.enabled : (currentRule?.enabled ?? true),
+    };
+
+    if (!currentRule) {
+      console.log(`      ${chalk.dim('·')} create ${chalk.cyan(`"${ruleName}"`)}`);
+      modifiedRules.push(expectedRule);
+      hasChanges = true;
+      continue;
+    }
+
+    const currentEdgeTtl = currentRule.action_parameters?.edge_ttl?.default;
+    const currentBrowserTtl = currentRule.action_parameters?.browser_ttl?.default;
+    const needsUpdate =
+      currentEdgeTtl !== expectedRule.action_parameters.edge_ttl.default
+      || currentBrowserTtl !== expectedRule.action_parameters.browser_ttl.default
+      || currentRule.enabled !== expectedRule.enabled
+      || currentRule.expression !== expectedRule.expression;
+
+    if (needsUpdate) {
+      console.log(`      ${chalk.dim('·')} update ${chalk.cyan(`"${ruleName}"`)}`);
+      modifiedRules[ruleIndex] = expectedRule;
+      hasChanges = true;
+    }
+  }
+
+  // Remove stale rules (in Cloudflare but not in config)
+  const configNames = new Set(cacheRulesConfig.map((r) => r.name));
+  const staleIndices = [];
+  for (let i = modifiedRules.length - 1; i >= 0; i--) {
+    if (modifiedRules[i].description && !configNames.has(modifiedRules[i].description)) {
+      console.log(`      ${chalk.dim('·')} remove ${chalk.cyan(`"${modifiedRules[i].description}"`)}`);
+      staleIndices.push(i);
+      hasChanges = true;
+    }
+  }
+  for (const i of staleIndices) modifiedRules.splice(i, 1);
+
+  if (!hasChanges && !needsCreate) {
+    console.log(`      ${chalk.dim('⊘ No changes needed')}`);
+    return;
+  }
+
+  // === WRITE ===
+  const output = await applyRuleset(api, zoneId, {
+    ruleset,
+    needsCreate,
+    rules: modifiedRules,
+    phase: 'http_request_cache_settings',
+    name: 'Cache Rules',
+    description: 'Cache rules managed by Omega Manager',
+    label: 'Cache rules',
+    dryRun: options.dryRun,
+  });
+
+  return { output: { cacheRules: output } };
+};