@omega.js/manager 0.1.0

package/dist/services/cloud/lib/project-flow.js

@@ -0,0 +1,102 @@
+/**
+ * Interactive Firebase project selection/creation (config-landing flow):
+ * when cloud.config.projectId is missing in an interactive run, pick from the
+ * projects the authed user can see, or create one — project id + display
+ * name prompted (brand id/name as defaults), with the 30-project quota
+ * shown. The chosen id lands in omega.json5 (comment-preserving writeback).
+ *
+ * The organization is tri-state (#33): cloud.organizationId set → the
+ * project is created inside it (that's what gives the compute service
+ * account its default roles); `false` → standalone, no questions; missing →
+ * pick from the orgs the authed user can see or opt out — either answer
+ * lands in omega.json5, so it's a one-time question. Downloaders without an
+ * org onboard cleanly.
+ */
+const chalk = require('chalk').default;
+const { input } = require('../../../vendor/devkit/prompt.js');
+const { resolveConfigValue } = require('../../../lib/config-flow.js');
+
+const PROJECT_QUOTA = 30;
+const PROJECT_ID_PATTERN = /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/;
+
+/**
+ * Resolve (or interactively land) the organization for a NEW project.
+ * Chained inside the create flow the user already said Yes to, so there is
+ * no Yes/Skip gate — just the selection (orgs + a standalone opt-out).
+ *
+ * @param {Object} context - Service context
+ * @param {Object} api - FirebaseAPI client
+ * @returns {Promise<string|null>} - organization id, or null for standalone
+ */
+async function resolveOrganization(context, api) {
+  return resolveConfigValue(context, {
+    path: 'cloud.organizationId',
+    label: 'Google Cloud organization',
+    gate: false,
+    message: 'Create the project inside a Google Cloud organization?',
+    choices: () => api.listOrganizations(),
+    getName: (org) => `${org.displayName} (${org.name.replace('organizations/', '')})`,
+    getValue: (org) => org.name.replace('organizations/', ''),
+    optOut: { label: 'No organization — create it standalone' },
+  });
+}
+
+/**
+ * Resolve (or interactively land) the Firebase project id.
+ *
+ * @param {Object} context - Service context
+ * @param {Object} api - FirebaseAPI client
+ * @returns {Promise<string|null>} - projectId, or null when skipped
+ */
+async function resolveFirebaseProject(context, api) {
+  return resolveConfigValue(context, {
+    path: 'cloud.config.projectId',
+    label: 'Firebase project',
+    choices: () => api.listProjects(),
+    getName: (project) => `${project.displayName} (${project.projectId})`,
+    getValue: (project) => project.projectId,
+    createNew: {
+      label: 'Firebase project',
+      handler: async () => {
+        const { brand } = context.brandConfig;
+
+        const projects = await api.listProjects();
+        const remaining = PROJECT_QUOTA - projects.length;
+        const color = remaining <= 5 ? chalk.yellow : chalk.dim;
+        const icon = remaining <= 5 ? '⚠' : '→';
+        console.log(`    ${color(`${icon} Firebase project quota: ${projects.length}/${PROJECT_QUOTA} (${remaining} remaining)`)}`);
+
+        const projectId = await input({
+          message: 'Enter project ID (lowercase, numbers, hyphens only):',
+          default: brand.id,
+          validate: (val) => {
+            if (!val?.trim()) {
+              return 'Project ID is required';
+            }
+            if (!PROJECT_ID_PATTERN.test(val)) {
+              return 'Project ID must be 6-30 chars, start with a letter, only lowercase letters, numbers, hyphens';
+            }
+            return true;
+          },
+        });
+
+        const displayName = await input({
+          message: 'Enter display name:',
+          default: brand.name,
+        });
+
+        const organizationId = await resolveOrganization(context, api);
+        console.log(`    Creating Firebase project ${chalk.cyan(projectId)}...`);
+        if (organizationId) {
+          console.log(`    ${chalk.dim('→')} Creating inside organization ${chalk.cyan(organizationId)}`);
+        }
+        await api.createProject(projectId, displayName, organizationId);
+        console.log(`    ${chalk.green('✓')} Created`);
+
+        return projectId;
+      },
+    },
+  });
+}
+
+module.exports = { resolveFirebaseProject };

package/dist/services/directory/ensure/entry.js

@@ -0,0 +1,48 @@
+/**
+ * Push the brand's directory entry to the parent project's Firestore at
+ * brands/{brand.id}: identity plus the blocks the brand declares.
+ *
+ * Diff FIRST — an unchanged config performs zero writes, which is what makes
+ * this safe to run on every manage walk.
+ *
+ * MERGE-write, not replace (the server service's registry is a replace, and
+ * the difference is deliberate): the framework owns only its own sections of
+ * the entry, so the write masks exactly those. Whatever the hub keeps on the
+ * same document — order counts, moderation state, anything ITW's marketplace
+ * adds — survives every push, and a section the brand drops from config is
+ * still removed, because the mask names every owned section whether or not it
+ * has a value this run.
+ */
+const { isDeepStrictEqual } = require('node:util');
+const chalk = require('chalk').default;
+
+const { OWNED_SECTIONS, buildEntry, ownedSlice } = require('../lib/blocks.js');
+
+module.exports = async function ensureEntry(context) {
+  const { brandConfig, db, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  const docPath = `brands/${brandConfig.brand.id}`;
+  const desired = buildEntry(brandConfig);
+  const blocks = Object.keys(desired).filter((key) => key !== 'brand' && key !== 'github');
+
+  const current = await db.getDoc(docPath);
+
+  if (isDeepStrictEqual(ownedSlice(current), desired)) {
+    console.log(`      ${chalk.green('✓')} Directory entry ${chalk.dim(docPath)} in sync${blocks.length > 0 ? chalk.dim(` (${blocks.join(', ')})`) : ''}`);
+    return { output: { entry: { synced: true, blocks } } };
+  }
+
+  const action = current ? 'update' : 'create';
+
+  if (dryRun) {
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would ${action} directory entry ${chalk.cyan(docPath)}`);
+    return { output: { entry: { planned: action, blocks } } };
+  }
+
+  await db.patchDoc(docPath, desired, OWNED_SECTIONS);
+
+  console.log(`      ${chalk.green('✓')} Directory entry ${chalk.dim(docPath)} ${action}d${blocks.length > 0 ? chalk.dim(` (${blocks.join(', ')})`) : ''}`);
+
+  return { output: { entry: { [`${action}d`]: true, blocks } } };
+};

package/dist/services/directory/index.js

@@ -0,0 +1,64 @@
+/**
+ * Directory service — the brand PUSHES its own entry into the PARENT
+ * project's Firestore `brands` collection (`brands/{brand.id}`) during its
+ * manage walk, so whatever the parent runs on top of that collection reads a
+ * current directory instead of one that goes stale the day a brand migrates.
+ *
+ * GENERIC and opt-in (#246). The framework owes the fresh ENTRY and nothing
+ * else: the marketplace/hub that consumes it — ITW's guest-post sponsorship
+ * marketplace is the first — is brand code and never enters the framework.
+ * The payload is brand identity plus the opt-in BLOCKS the brand declares
+ * (lib/blocks.js); `sponsorships` is the first block. Field mapping from
+ * legacy omega-manager: docs/manager/directory.md.
+ *
+ * Gates, in order — every one of them is a clean skip:
+ *   1. `directory.enabled: true`. Absent config never pushes: the parent
+ *      declares the collection world-readable in its own rules (the operator
+ *      step in docs/manager/directory.md), so participation is explicit or
+ *      nothing.
+ *   2. `parent` names the relationship. No parent (or `parent: false`) means
+ *      there is no directory to push INTO.
+ *   3. Not a demo-* (emulator-only) brand — the cloud service's gate, for the
+ *      same reason: an offline fixture must never reach a live project.
+ *
+ * Auth: DIRECTORY_SERVICE_ACCOUNT in the brand .env — a path to the PARENT
+ * project's Firebase service-account JSON (absolute, or relative to the brand
+ * root), the server service's mechanism exactly. The service account names the
+ * target project; no config key ever holds a credential.
+ */
+const { isDemoProject } = require('../../vendor/config/index.js');
+
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { FirestoreREST, loadServiceAccount } = require('../../lib/firestore-rest.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const { brandConfig } = context;
+
+    if (brandConfig.directory?.enabled !== true) {
+      return { skip: true, reason: 'directory.enabled is not true (the brand does not participate in a directory)' };
+    }
+
+    if (!brandConfig.parent) {
+      return { skip: true, reason: 'no parent configured — there is no parent directory to push into' };
+    }
+
+    const projectId = brandConfig.cloud?.config?.projectId;
+    if (isDemoProject(projectId)) {
+      return { skip: true, reason: `${projectId} is a demo-* (emulator-only) project — no live directory to push into` };
+    }
+
+    // Tests inject a fake client via context.directoryDb
+    let db = context.directoryDb;
+    if (!db) {
+      const envPath = process.env.DIRECTORY_SERVICE_ACCOUNT;
+      if (!envPath) {
+        return { skip: true, reason: 'no DIRECTORY_SERVICE_ACCOUNT configured (path to the parent project\'s service-account JSON, set it in the brand .env)' };
+      }
+      db = new FirestoreREST(loadServiceAccount(envPath, context.brandRoot));
+    }
+
+    return { db };
+  },
+});

package/dist/services/directory/lib/blocks.js

@@ -0,0 +1,104 @@
+/**
+ * The directory payload — brand IDENTITY plus the opt-in BLOCKS the brand
+ * declares — and the list of sections the framework OWNS in the entry.
+ *
+ * Identity is not optional: a directory entry with no name addresses nothing.
+ * The repo slugs come from @omega.js/config's one derivation (#290) — the same
+ * `{ owner, name, repo }` the backend hands consumers as
+ * `config.resolved.github` — never re-derived here.
+ *
+ * BLOCKS is the extension point (#246). One entry per publishable block,
+ * naming the brand-config section it reads; a block crosses only when the
+ * brand DECLARES that section, which is what "opt-in blocks" means. Adding the
+ * next block is one entry here plus its schema line in @omega.js/config.
+ *
+ * Sections are pushed VERBATIM. Nothing is redacted on the way out, because
+ * nothing secret can be in them: these are schema-known public config keys and
+ * @omega.js/config hard-fails secret-shaped keys before any merge happens.
+ */
+const { brandRepo } = require('../../../vendor/config/index.js');
+
+// Block name → the brand-config section it publishes.
+const BLOCKS = {
+  // Guest-post / link-insertion terms, priced per placement. Legacy
+  // omega-manager carried the same shape at `.brands/<id>/config.json`
+  // `sponsorships` — the field mapping is in docs/manager/directory.md.
+  sponsorships: (config) => config.sponsorships,
+};
+
+// Every top-level field of the entry the framework owns, block or not. The
+// write masks ALL of them, so a section the brand drops from config is
+// removed from the entry too — and every OTHER field of the document (whatever
+// the hub itself owns: order counts, moderation state) survives untouched.
+const OWNED_SECTIONS = ['brand', 'github', ...Object.keys(BLOCKS)];
+
+/**
+ * Whether a config section is declared richly enough to publish. An absent
+ * section and an empty one say the same thing: the brand is not offering it.
+ *
+ * @param {*} section - The raw config value.
+ * @returns {boolean}
+ */
+function isDeclared(section) {
+  return Boolean(section)
+    && typeof section === 'object'
+    && !Array.isArray(section)
+    && Object.keys(section).length > 0;
+}
+
+/**
+ * Build the directory entry for a brand.
+ *
+ * @param {object} config - The resolved brand config.
+ * @returns {object} The entry document — only the sections that resolve.
+ */
+function buildEntry(config) {
+  const entry = {
+    brand: {
+      id: config.brand.id,
+      name: config.brand.name,
+    },
+  };
+
+  if (config.brand.url) {
+    entry.brand.url = config.brand.url;
+  }
+
+  // '' unless BOTH halves resolve (#290) — half an address addresses nothing,
+  // and an entry is better without the key than with a broken one.
+  const github = brandRepo(config);
+  if (github.repo) {
+    entry.github = github;
+  }
+
+  for (const [name, read] of Object.entries(BLOCKS)) {
+    const section = read(config);
+    if (isDeclared(section)) {
+      entry[name] = section;
+    }
+  }
+
+  return entry;
+}
+
+/**
+ * The framework-owned slice of the entry as it stands in the directory today —
+ * what `buildEntry` output is diffed against. Everything else in the document
+ * belongs to the hub and is not this service's business.
+ *
+ * @param {object|null} current - The document read from the directory.
+ * @returns {object} Only the owned sections that are present.
+ */
+function ownedSlice(current) {
+  const slice = {};
+
+  for (const key of OWNED_SECTIONS) {
+    if (current && current[key] !== undefined) {
+      slice[key] = current[key];
+    }
+  }
+
+  return slice;
+}
+
+module.exports = { BLOCKS, OWNED_SECTIONS, buildEntry, ownedSlice };

package/dist/services/disperse/index.js

@@ -0,0 +1,45 @@
+/**
+ * Disperse service — the remnant of omega-manager's disperse after the
+ * config hierarchy dissolved file dispersal: targets read config/omega.json5
+ * directly, so there is no .brands/ mirror and no per-repo config writes
+ * (the old repos/products/pricing-md/cdn operations). What can't ride the
+ * hierarchy is exactly what this service still moves:
+ *
+ *   certs — signing artifacts (binary, never mergeable) copied from the
+ *           certificates service's .omega/certificates/apple/ tree into
+ *           each desktop/mobile target's certs dir. The copy itself is
+ *           devkit's (`@omega.js/devkit/certs`), so a desktop build reaches
+ *           the same artifacts through the same rules (#678).
+ *
+ * The .env composition is GONE (#678): the brand-root .env is the one file
+ * humans and the manager edit, and every verb composes its target's runtime
+ * env from the cascade by schema — no machine writes a target .env. A CUSTOM
+ * target has no @omega.js/config to walk the cascade for it, so it inherits
+ * instead: manage.js loads the env chain into process.env before it spawns
+ * anything, and a custom target started by `omega dev`/`omega deploy` gets the
+ * brand keys that way. A standalone run inside the target dir does not.
+ *
+ * De-ITW'd from omega-manager: the company-wide .output/_shared/ cert tree
+ * and .brands/{id}/.env override layer are gone — artifacts are brand-local
+ * (.omega/certificates/apple/) and manage.js already layers shell env >
+ * brand .env > company .env before any service runs.
+ *
+ * Runs on the DELIVERY lane (config.js BOOT_SERVICES): every `omega dev`
+ * boot, every brand-root `omega deploy`, and the full manage walk — after
+ * certificates (the artifacts must exist) and before update (builds read the
+ * cert files).
+ */
+const { createServiceRunner } = require('../../lib/service-runner.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: (context) => {
+    const mappedTargets = (context.targets || []).filter((entry) => entry.target);
+
+    if (mappedTargets.length === 0) {
+      return { skip: true, reason: 'no target-mapped dirs' };
+    }
+
+    return { mappedTargets };
+  },
+});

package/dist/services/disperse/write/certs.js

@@ -0,0 +1,117 @@
+/**
+ * Copy signing artifacts into desktop/mobile targets.
+ *
+ * The copy itself is devkit's (`@omega.js/devkit/certs`, #678) — the ONE
+ * delivery step every verb rides, so a desktop build reaches the same
+ * artifacts through the same rules. What lives here is the manage-lane
+ * FRAMING: which targets get a pass, the certificates config gate, and the
+ * per-rule reporting.
+ *
+ * Sources are the certificates service's outputs under the signing tree —
+ * {companyRoot||brandRoot}/.omega/certificates/apple/ (company-managed
+ * brands share the company workspace's material); destinations are each
+ * target's certs dir. Optional rules skip silently when the source is
+ * missing; required rules warn (the desktop/mobile build would be unsigned).
+ * A brand with no Apple artifacts at all (certificates disabled or never run)
+ * is a quiet note, not a warning.
+ *
+ * A miss is warn-only: the dests are documented human drop points, so a dest
+ * with no source in the tree is left exactly where the operator put it.
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+
+const { deliverCerts, resolveCertRules, certsSourceDir, CERT_FILE_MAP } = require('../../../vendor/devkit/certs.js');
+
+module.exports = async (context) => {
+  const { brandRoot, companyRoot, brandConfig, mappedTargets, options = {} } = context;
+
+  const certConfig = brandConfig.certificates;
+  if (certConfig === false || certConfig?.enabled === false) {
+    console.log(`      ${chalk.dim('⊘ certificates.enabled = false — no signing artifacts to disperse')}`);
+    return { output: { certs: { reason: 'certificates.enabled = false' } } };
+  }
+
+  const certTargets = mappedTargets.filter((entry) => CERT_FILE_MAP[entry.target]);
+  if (certTargets.length === 0) {
+    console.log(`      ${chalk.dim('⊘ no desktop or mobile targets')}`);
+    return { output: { certs: { reason: 'no desktop or mobile targets' } } };
+  }
+
+  // The certificates service's signing tree — company-shared when the brand
+  // is company-managed, brand-local otherwise (the same resolution rule)
+  const sourceRoot = companyRoot || brandRoot;
+  const appleDir = certsSourceDir(sourceRoot);
+  if (!jetpack.exists(appleDir)) {
+    console.log(`      ${chalk.dim('⊘ no signing artifacts yet (.omega/certificates/apple is empty — the certificates service produces them)')}`);
+    return { output: { certs: { reason: 'no signing artifacts yet' } } };
+  }
+
+  const brand = brandConfig.brand;
+  let copied = 0;
+  let current = 0;
+  let skipped = 0;
+  let warned = 0;
+  let planned = 0;
+
+  for (const entry of certTargets) {
+    console.log(`      ${chalk.cyan(entry.dir)}:`);
+
+    const result = deliverCerts({
+      sourceRoot,
+      targetDir: entry.path,
+      target: entry.target,
+      brand,
+      dryRun: options.dryRun,
+    });
+    const delivered = new Set(result.copied);
+    const unchanged = new Set(result.current);
+
+    // The rules in their declared order — the delivery's own arrays carry the
+    // outcome, the rules carry what a miss MEANS (optional vs required)
+    for (const rule of resolveCertRules({ target: entry.target, brand })) {
+      const destRel = rule.destRel || rule.dest;
+
+      if (unchanged.has(destRel)) {
+        console.log(`        ${chalk.dim(`✓ ${destRel} (current)`)}`);
+        current++;
+        continue;
+      }
+
+      if (delivered.has(destRel)) {
+        if (options.dryRun) {
+          console.log(`        ${chalk.cyan('[DRY RUN]')} Would copy ${chalk.cyan(destRel)}`);
+          planned++;
+        } else {
+          console.log(`        ${chalk.green('✓')} ${chalk.cyan(destRel)}`);
+          copied++;
+        }
+        continue;
+      }
+
+      // A miss: an unset env placeholder (the rule has no real path) or a
+      // source that isn't there
+      const detail = rule.destRel === null
+        ? `env placeholder unset in ${rule.source}`
+        : `source missing: ${join(appleDir, rule.sourceRel)}`;
+
+      if (rule.optional) {
+        console.log(`        ${chalk.dim(`⊘ ${destRel} (${rule.destRel === null ? 'env placeholder unset' : 'source missing'}, optional)`)}`);
+        skipped++;
+      } else {
+        console.log(`        ${chalk.yellow('⚠')} ${chalk.cyan(destRel)} ${chalk.dim(`(${detail})`)}`);
+        warned++;
+      }
+    }
+  }
+
+  const summary = { copied, current, skipped, warned, ...(options.dryRun ? { planned } : {}) };
+  console.log(`      Summary: ${chalk.bold(copied)} copied, ${current} current, ${chalk.dim(skipped)} skipped, ${warned > 0 ? chalk.yellow(warned) : warned} warnings`);
+
+  return {
+    status: warned > 0 ? 'warned' : 'success',
+    ...(warned > 0 ? { reason: `${warned} cert file(s) not dispersed` } : {}),
+    output: { certs: summary },
+  };
+};

package/dist/services/domain/ensure/nameservers.js

@@ -0,0 +1,179 @@
+/**
+ * Ensure the registrar's nameservers point to Cloudflare.
+ *
+ * Flow:
+ * 1. Fetch the Cloudflare zone to get its assigned nameservers
+ * 2. namecheap: read current nameservers via API, set them when mismatched
+ * 3. manual registrars: an active zone proves they're already set (success);
+ *    a pending zone prints the values to set and returns warned
+ *
+ * omega-manager split SLD/TLD by popping the last dot-label, which breaks
+ * multi-part TLDs (mybrand.co.uk → SLD "mybrand.co", TLD "uk"); this port
+ * uses the public suffix list instead.
+ */
+const chalk = require('chalk').default;
+const psl = require('psl');
+const { pollWithSpinner } = require('../../../vendor/devkit/flows.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+const { isWhitelistError } = require('../lib/namecheap-api.js');
+const { walkWhitelist } = require('../lib/whitelist-walkthrough.js');
+
+// A freshly created zone gets its nameservers within seconds; a zone still
+// bare after this many reads is not going to fill in while we watch (#662).
+const ZONE_NS_READS = 6;
+const ZONE_NS_INTERVAL_MS = 5000;
+
+/** The unreadable-nameservers warn — the registrar side steps aside for a run. */
+const warnedRead = (message) => ({
+  status: 'warned',
+  reason: 'could not read the nameservers at Namecheap',
+  output: { nameservers: { error: message } },
+});
+
+/**
+ * The read failed for something the whitelist walk cannot fix — name it, point
+ * at the likeliest cause, and step aside. The walk's own recheck failure lands
+ * here too, so the hint stays reachable on that branch (#698).
+ */
+function warnUnreadable(message) {
+  console.log(`      ${chalk.yellow('⚠')} Could not read nameservers at Namecheap${chalk.dim(`: ${message}`)}`);
+  console.log(`      ${chalk.dim('→')} Domain not in your Namecheap account yet (not purchased?). Rerun after purchase.`);
+  return warnedRead(message);
+}
+
+module.exports = async function ensureNameservers(context) {
+  const { cloudflareApi, namecheapApi, domain, provider, options = {} } = context;
+
+  // Nameservers live at the REGISTRABLE domain — for subdomain projects
+  // (playground.omegajs.dev) that's the parent (omegajs.dev): the zone the
+  // cloudflare service manages, and the domain the registrar actually holds.
+  const zoneName = psl.get(domain) || domain;
+  if (zoneName !== domain) {
+    console.log(`      ${chalk.dim(`Subdomain project — managing nameservers for parent ${zoneName}`)}`);
+  }
+
+  // === READ: Cloudflare's assigned nameservers ===
+  let zone = await cloudflareApi.getZoneByName(zoneName);
+
+  if (!zone) {
+    console.log(`      ${chalk.yellow('⚠')} No Cloudflare zone found for ${chalk.cyan(zoneName)} — rerun once the cloudflare service creates it`);
+    return { status: 'warned', reason: 'no Cloudflare zone found for the zone', output: { nameservers: { note: 'no Cloudflare zone found' } } };
+  }
+
+  // A zone created earlier in THIS walk (the edge service) may still be
+  // initializing — wait for its nameservers instead of leaving the registrar
+  // to a second run (#662). Bounded: the poll gives up on its own.
+  if ((zone.name_servers || []).length === 0 && canPrompt(options)) {
+    zone = await waitForAssignedNameservers(cloudflareApi, zoneName, zone);
+  }
+
+  const required = [...(zone.name_servers || [])].sort();
+
+  if (required.length === 0) {
+    console.log(`      ${chalk.yellow('⚠')} Zone exists but has no assigned nameservers yet (still initializing) — rerun`);
+    return { status: 'warned', reason: 'the zone has no assigned nameservers yet', output: { nameservers: { note: 'zone has no assigned nameservers yet' } } };
+  }
+
+  console.log(`      ${chalk.dim('→')} Cloudflare nameservers: ${required.map((ns) => chalk.cyan(ns)).join(', ')}`);
+
+  if (provider === 'namecheap') {
+    return await ensureNamecheap(zoneName, required, namecheapApi, options);
+  }
+
+  // === Manual registrars — no read API, but the zone status is proof enough:
+  // an active zone means the nameservers already point to Cloudflare
+  if (zone.status === 'active') {
+    console.log(`      ${chalk.green('✓')} Zone is active — nameservers already pointing to Cloudflare`);
+    return { output: { nameservers: { alreadySet: true } } };
+  }
+
+  console.log(`      ${chalk.yellow('⚠')} ${provider} requires manual nameserver configuration`);
+  console.log(`      Set these nameservers at your registrar:`);
+  for (const ns of required) {
+    console.log(`        ${chalk.cyan(ns)}`);
+  }
+
+  return { status: 'warned', reason: `${provider} requires manual nameserver configuration`, output: { nameservers: { manual: true, provider, required } } };
+};
+
+/**
+ * Re-read the zone until Cloudflare has assigned its nameservers, bounded to
+ * ZONE_NS_READS attempts (ENTER checks now, `s` skips).
+ *
+ * @returns {Promise<object>} - The zone: the assigned one, or the bare zone
+ *   handed in when the wait ran out or was skipped.
+ */
+async function waitForAssignedNameservers(api, zoneName, zone) {
+  let reads = 0;
+  let assigned = null;
+
+  const result = await pollWithSpinner({
+    check: async () => {
+      reads += 1;
+      const fresh = await api.getZoneByName(zoneName);
+      if ((fresh?.name_servers || []).length > 0) {
+        assigned = fresh;
+        return { done: true };
+      }
+      return reads >= ZONE_NS_READS ? { done: true, error: 'still initializing' } : { done: false };
+    },
+    intervalMs: ZONE_NS_INTERVAL_MS,
+    message: `Waiting for Cloudflare to assign nameservers for ${zoneName}`,
+    indent: '      ',
+  });
+
+  return result.success && assigned ? assigned : zone;
+}
+
+async function ensureNamecheap(domain, required, api, options) {
+  const { sld, tld } = psl.parse(domain);
+
+  // Read current nameservers. Fails for domains not in the Namecheap account
+  // (e.g. not purchased yet) — warn instead of failing the brand.
+  console.log(`      ${chalk.dim('→')} Checking current nameservers at Namecheap...`);
+  let current;
+  try {
+    current = await api.getDns(sld, tld);
+  } catch (error) {
+    // The IP-whitelist rejection is the ONE read failure this walk can fix in
+    // place (#698): open the API access page, then recheck the refused read.
+    if (!isWhitelistError(error)) {
+      return warnUnreadable(error.message);
+    }
+
+    const recovered = await walkWhitelist(error, () => api.getDns(sld, tld), options);
+    if (recovered.error) {
+      // The recheck cleared the whitelist and failed for its own reason — that
+      // error is the one to report; the pre-walk rejection is stale (#698).
+      return warnUnreadable(recovered.error);
+    }
+    if (!recovered.success) {
+      return warnedRead(error.message);
+    }
+    current = recovered.result;
+  }
+
+  const currentNs = [...current.nameservers].sort();
+  const alreadySet = required.length === currentNs.length
+    && required.every((ns, i) => ns === currentNs[i]);
+
+  if (alreadySet) {
+    console.log(`      ${chalk.green('✓')} Nameservers already pointing to Cloudflare`);
+    return { output: { nameservers: { alreadySet: true } } };
+  }
+
+  console.log(`      ${chalk.dim('→')} Current: ${currentNs.join(', ') || '(default/none)'}`);
+
+  // === WRITE ===
+  if (options.dryRun) {
+    return dryRunPlan('set Cloudflare nameservers at Namecheap', { output: { nameservers: { planned: 'update', current: currentNs, required } } });
+  }
+
+  console.log(`      ${chalk.dim('→')} Setting Cloudflare nameservers at Namecheap...`);
+
+  await api.setCustomNameservers(sld, tld, required);
+
+  console.log(`      ${chalk.green('✓')} Nameservers updated at Namecheap → Cloudflare`);
+
+  return { output: { nameservers: { updated: true, previous: currentNs } } };
+}