@omega.js/manager 0.1.0

package/dist/services/migrations/lib/schema-validator.js

@@ -0,0 +1,154 @@
+/**
+ * Schema Validator for Firestore Documents
+ *
+ * Validates documents against a schema definition.
+ * Used by migration handlers to check data integrity.
+ *
+ * Schema format:
+ * {
+ *   fieldName: {
+ *     type: 'string' | 'number' | 'boolean' | 'object' | 'array',
+ *     required: true | false,
+ *     nullable: true | false,  // if true, null is valid even if type doesn't match
+ *     itemType: 'string',      // for arrays, the expected type of items
+ *     properties: { ... },     // for objects, nested schema
+ *   }
+ * }
+ */
+
+/**
+ * Get the type of a value (more specific than typeof)
+ *
+ * @param {*} value - Value to check
+ * @returns {string} Type string: 'null', 'array', 'object', 'string', 'number', 'boolean', 'undefined'
+ */
+function getType(value) {
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return 'array';
+  }
+  return typeof value;
+}
+
+/**
+ * Format expected type string for error messages
+ *
+ * @param {Object} fieldSchema - Schema for the field
+ * @returns {string} Human-readable type string
+ */
+function formatExpectedType(fieldSchema) {
+  let expected = fieldSchema.type;
+
+  if (fieldSchema.nullable) {
+    expected += '|null';
+  }
+
+  if (fieldSchema.type === 'array' && fieldSchema.itemType) {
+    expected = `array<${fieldSchema.itemType}>`;
+    if (fieldSchema.nullable) {
+      expected += '|null';
+    }
+  }
+
+  return expected;
+}
+
+/**
+ * Validate a single field against its schema
+ *
+ * @param {*} value - The value to validate
+ * @param {Object} fieldSchema - Schema for this field
+ * @param {string} fieldPath - Dot-notation path for error messages
+ * @returns {Array} Array of error objects
+ */
+function validateField(value, fieldSchema, fieldPath) {
+  const errors = [];
+  const actualType = getType(value);
+
+  // Check if field is missing
+  if (actualType === 'undefined') {
+    if (fieldSchema.required) {
+      errors.push({
+        field: fieldPath,
+        expected: formatExpectedType(fieldSchema),
+        actual: 'undefined',
+        message: 'Missing required field',
+      });
+    }
+    return errors;
+  }
+
+  // Check nullable
+  if (actualType === 'null') {
+    if (!fieldSchema.nullable) {
+      errors.push({
+        field: fieldPath,
+        expected: formatExpectedType(fieldSchema),
+        actual: 'null',
+        message: `Expected ${fieldSchema.type}, got null (field is not nullable)`,
+      });
+    }
+    return errors;
+  }
+
+  // Check type match
+  if (actualType !== fieldSchema.type) {
+    errors.push({
+      field: fieldPath,
+      expected: formatExpectedType(fieldSchema),
+      actual: actualType,
+      message: `Expected ${fieldSchema.type}, got ${actualType}`,
+    });
+    return errors; // Don't check nested if type doesn't match
+  }
+
+  // For arrays, check item types
+  if (fieldSchema.type === 'array' && fieldSchema.itemType) {
+    for (let i = 0; i < value.length; i++) {
+      const itemType = getType(value[i]);
+      if (itemType !== fieldSchema.itemType) {
+        errors.push({
+          field: `${fieldPath}[${i}]`,
+          expected: fieldSchema.itemType,
+          actual: itemType,
+          message: `Array item expected ${fieldSchema.itemType}, got ${itemType}`,
+        });
+      }
+    }
+  }
+
+  // For objects with properties schema, validate nested fields
+  if (fieldSchema.type === 'object' && fieldSchema.properties) {
+    for (const [propName, propSchema] of Object.entries(fieldSchema.properties)) {
+      const propErrors = validateField(value[propName], propSchema, `${fieldPath}.${propName}`);
+      errors.push(...propErrors);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a document against a schema
+ *
+ * @param {Object} doc - Document data to validate
+ * @param {Object} schema - Schema definition
+ * @returns {Object} { valid: boolean, errors: Array<{ field, expected, actual, message }> }
+ */
+function validateDocument(doc, schema) {
+  const errors = [];
+
+  for (const [fieldName, fieldSchema] of Object.entries(schema)) {
+    const fieldErrors = validateField(doc[fieldName], fieldSchema, fieldName);
+    errors.push(...fieldErrors);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+module.exports = { validateDocument };

package/dist/services/monitoring/ensure/dsn.js

@@ -0,0 +1,54 @@
+/**
+ * Land each target project's DSN in
+ * targets.<type>.monitoring.providers.sentry.dsn (#425) — the
+ * per-surface override every framework reads through the config merge
+ * chain. DSNs are public by design (schema-pinned), so config is their
+ * home; the writeback is comment-preserving and a converged rerun leaves
+ * the file byte-identical. The resolved value always wins: a hand-set
+ * stale DSN is drift and gets patched.
+ */
+const chalk = require('chalk').default;
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+
+module.exports = async function ensureDsn(context) {
+  const { sentryApi: api, brandConfig, serviceData } = context;
+
+  const org = serviceData.org;
+  const projects = serviceData.projectMap || {};
+  const targets = Object.keys(projects);
+
+  if (!org || targets.length === 0) {
+    console.log(`      ${chalk.dim('⊘ No projects resolved — nothing to land')}`);
+    return {};
+  }
+
+  const edits = {};
+  const dsns = {};
+
+  for (const target of targets) {
+    const { slug } = projects[target];
+    const keys = await api.getProjectKeys(org, slug);
+    const active = (keys || []).find((key) => key.isActive !== false && key.dsn?.public);
+
+    if (!active) {
+      console.log(`      ${chalk.yellow('⚠')} ${chalk.cyan(slug)} has no active client key — create one in Sentry, then rerun`);
+      return { status: 'warned', reason: `${slug} has no active client key — create one in Sentry`, output: { dsn: { missingKey: slug } } };
+    }
+
+    const dsn = active.dsn.public;
+    dsns[target] = dsn;
+
+    const current = brandConfig.targets?.[target]?.monitoring?.providers?.sentry?.dsn;
+    if (current === dsn) {
+      console.log(`      ${chalk.green('✓')} ${chalk.cyan(target)} DSN in place`);
+      continue;
+    }
+
+    edits[`targets.${target}.monitoring.providers.sentry.dsn`] = dsn;
+    console.log(`      ${chalk.yellow('↻')} ${chalk.cyan(target)} DSN ${current ? 'drifted — updating' : 'landing'}`);
+  }
+
+  writeBrandConfig(context, edits);
+
+  return { output: { dsn: { landed: Object.keys(edits).length, targets: dsns } } };
+};

package/dist/services/monitoring/ensure/projects.js

@@ -0,0 +1,135 @@
+/**
+ * Ensure the org, the brand's team, and one Sentry project per enabled
+ * target. Org resolution: monitoring.providers.sentry.org from config wins;
+ * otherwise the token's single org is used and written back there
+ * (self-heal), and a token seeing SEVERAL orgs is asked which one (#635). The team is the brand id; projects are `{brand.id}-{target}`
+ * with the target's Sentry platform. Existing projects (matched by slug)
+ * are converged proof — nothing is renamed or deleted here.
+ */
+const chalk = require('chalk').default;
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { resolveConfigValue } = require('../../../lib/config-flow.js');
+
+// Sentry platform slugs per target type — validated server-side against the
+// integration-docs index (Project.is_valid_platform), so only ids that exist
+// there work: Electron's is the top-level 'electron', NOT the frontend-UI
+// alias 'javascript-electron' (400 Invalid platform — cp136b, live find).
+// Unlisted target types are not monitored.
+const TARGET_PLATFORMS = {
+  web: 'javascript',
+  backend: 'node',
+  desktop: 'electron',
+  extension: 'javascript',
+};
+
+module.exports = async function ensureProjects(context) {
+  const { sentryApi: api, brandConfig, options = {} } = context;
+  const brandId = brandConfig.brand.id;
+
+  // === Resolve the org (config wins; a lone token org self-heals into config) ===
+  const orgs = await api.getOrganizations();
+  const configured = brandConfig.monitoring.providers.sentry.org;
+  let org = configured
+    ? orgs.find((candidate) => candidate.slug === configured)
+    : (orgs.length === 1 ? orgs[0] : null);
+
+  // Ambiguous: the token sees several orgs and config names none. That is a
+  // question, not a warning (#635) — the list IS the answer, so ASK it. Zero
+  // orgs offers no choice, and a configured-but-invisible org is a different
+  // problem, so both keep their warn below. The service already gated on its
+  // token, hence `gate: false`.
+  if (!org && !configured && orgs.length > 0) {
+    const picked = await resolveConfigValue(context, {
+      path: 'monitoring.providers.sentry.org',
+      label: 'Sentry organization',
+      choices: async () => orgs,
+      getName: (candidate) => candidate.slug,
+      getValue: (candidate) => candidate.slug,
+      disablePath: 'monitoring.enabled',
+      gate: false,
+    });
+    org = picked ? orgs.find((candidate) => candidate.slug === picked) : null;
+  }
+
+  if (!org) {
+    if (configured) {
+      console.log(`      ${chalk.yellow('⚠')} monitoring.providers.sentry.org '${configured}' is not visible to this token ${chalk.dim(`(it sees: ${orgs.map((candidate) => candidate.slug).join(', ') || 'none'})`)}`);
+    } else {
+      console.log(`      ${chalk.yellow('⚠')} The token sees ${orgs.length} orgs — set monitoring.providers.sentry.org in omega.json5 to pick one`);
+    }
+    return { status: 'warned', reason: 'no Sentry org resolved — set monitoring.providers.sentry.org', output: { projects: { orgUnresolved: true } } };
+  }
+
+  // Multi-region SaaS: all org-scoped calls go to the org's home region
+  api.setRegionUrl(org.links?.regionUrl);
+
+  // Self-heal — skipped when the ask above already landed the pick (it patches
+  // the in-memory config too, so this reads the CURRENT state, not `configured`)
+  if (!brandConfig.monitoring.providers.sentry.org) {
+    writeBrandConfig(context, { 'monitoring.providers.sentry.org': org.slug });
+  }
+
+  const targets = Object.keys(brandConfig.targets || {}).filter((target) => TARGET_PLATFORMS[target]);
+  if (targets.length === 0) {
+    console.log(`      ${chalk.dim('⊘ No monitorable targets enabled')}`);
+    return { state: { org: org.slug, projectMap: {} } };
+  }
+
+  const existing = await api.getProjects(org.slug);
+
+  const projects = {};
+  const planned = [];
+  let created = 0;
+  let synced = 0;
+  let teamEnsured = false;
+
+  for (const target of targets) {
+    const slug = `${brandId}-${target}`;
+    console.log(`      ${chalk.dim('•')} ${chalk.cyan(slug)} ${chalk.dim(`(${TARGET_PLATFORMS[target]})`)}`);
+
+    const match = existing.find((project) => project.slug === slug);
+    if (match) {
+      console.log(`        ${chalk.green('✓')} Exists`);
+      projects[target] = { id: match.id, slug: match.slug };
+      synced++;
+      continue;
+    }
+
+    if (options.dryRun) {
+      dryRunPlan(`create project ${slug}`);
+      planned.push(slug);
+      continue;
+    }
+
+    // The brand's team carries its projects — ensured once, on first need
+    if (!teamEnsured) {
+      const teams = await api.getTeams(org.slug);
+      if (!teams.find((team) => team.slug === brandId)) {
+        await api.createTeam(org.slug, brandId);
+        console.log(`        ${chalk.green('✓')} Created team ${chalk.cyan(brandId)}`);
+      }
+      teamEnsured = true;
+    }
+
+    const project = await api.createProject(org.slug, brandId, {
+      name: slug,
+      slug,
+      platform: TARGET_PLATFORMS[target],
+    });
+    console.log(`        ${chalk.green('✓')} Created`);
+    projects[target] = { id: project.id, slug: project.slug };
+    created++;
+  }
+
+  const summary = planned.length > 0
+    ? { synced, planned }
+    : { synced, created };
+
+  // State key is projectMap (certificateMap-style) — the output summary key
+  // `projects` would clobber it in the merged serviceData the dsn op reads.
+  return {
+    state: { org: org.slug, projectMap: projects },
+    output: { projects: summary },
+  };
+};

package/dist/services/monitoring/index.js

@@ -0,0 +1,54 @@
+/**
+ * Monitoring service (Sentry provider) — one error-monitoring project per enabled target
+ * (web/backend/desktop/extension), with each project's DSN landed in
+ * targets.<type>.monitoring.providers.sentry.dsn via the comment-preserving
+ * writeback — the exact key every framework's runtime reads through the config
+ * merge chain. DSNs are public by design (schema-pinned); only the auth token
+ * is a secret.
+ *
+ * Gates: `monitoring.providers.sentry` present (the monitor is a KEY under
+ * `providers` since #425 — no entry means none chosen and this service skips,
+ * exactly what a null provider meant) + SENTRY_AUTH_TOKEN in the brand .env —
+ * a PERSONAL auth token with org:read, project:read, project:write, team:read,
+ * team:write (Sentry's "organization tokens" are CI-scoped and cannot create
+ * teams or projects, cp136). The projects operation resolves the org (config
+ * wins, else the token's lone visible org) and writes it back to
+ * monitoring.providers.sentry.org.
+ */
+const { chosenProvider } = require('../../vendor/config/index.js');
+
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { SentryAPI } = require('./lib/sentry-api.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const monitoring = context.brandConfig.monitoring;
+
+    if (monitoring === false || monitoring?.enabled === false) {
+      return { skip: true, reason: 'monitoring disabled' };
+    }
+    if (!monitoring) {
+      return { skip: true, reason: 'no monitoring config' };
+    }
+
+    const provider = chosenProvider(monitoring.providers);
+    if (!provider) {
+      return { skip: true, reason: 'no monitoring.providers entry' };
+    }
+    if (provider !== 'sentry') {
+      return { skip: true, reason: `monitoring.providers.${provider} is not a known monitor` };
+    }
+
+    if (!context.sentryApi) {
+      const gate = await requestServiceInput(context, serviceInputSpec('monitoring'));
+      if (gate) return gate;
+    }
+
+    return {
+      sentryApi: context.sentryApi || new SentryAPI(),
+    };
+  },
+});

package/dist/services/monitoring/lib/sentry-api.js

@@ -0,0 +1,94 @@
+/**
+ * Sentry API client (api/0) — organizations, teams, projects, client keys.
+ * Named-method surface so tests can fake it method-for-method.
+ *
+ * Auth: SENTRY_AUTH_TOKEN in the brand .env (a PERSONAL auth token with
+ * project+team write scopes — org tokens are CI-scoped and cannot create
+ * teams/projects, cp136). Multi-region SaaS: every org carries
+ * links.regionUrl; setRegionUrl() repoints the client so all org-scoped
+ * calls hit the org's home region.
+ */
+const SENTRY_API_BASE = 'https://sentry.io/api/0';
+
+class SentryAPI {
+  constructor(options = {}) {
+    this.authToken = options.authToken || process.env.SENTRY_AUTH_TOKEN;
+    this.apiBase = SENTRY_API_BASE;
+  }
+
+  /** Repoint org-scoped calls at the org's home region (multi-region SaaS). */
+  setRegionUrl(regionUrl) {
+    if (regionUrl) {
+      this.apiBase = `${regionUrl.replace(/\/$/, '')}/api/0`;
+    }
+  }
+
+  async makeRequest(endpoint, options = {}) {
+    const response = await fetch(`${this.apiBase}${endpoint}`, {
+      ...options,
+      headers: {
+        'Authorization': `Bearer ${this.authToken}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+
+    if (response.status === 204) {
+      return null;
+    }
+
+    const text = await response.text();
+    const data = text ? JSON.parse(text) : null;
+
+    if (!response.ok) {
+      // DRF validation errors have no detail/message — they're field-keyed
+      // ({"platform": ["Invalid platform"]}); serialize so the failure names
+      // its field instead of reading as a bare statusText.
+      const message = data?.detail
+        || data?.message
+        || (data ? JSON.stringify(data) : response.statusText);
+      throw new Error(`Sentry API error (${response.status}): ${message}`);
+    }
+
+    return data;
+  }
+
+  /** Organizations the token can see (an org token sees exactly one). */
+  async getOrganizations() {
+    return this.makeRequest('/organizations/');
+  }
+
+  /** Teams in the organization. */
+  async getTeams(orgSlug) {
+    return this.makeRequest(`/organizations/${orgSlug}/teams/`);
+  }
+
+  async createTeam(orgSlug, slug) {
+    return this.makeRequest(`/organizations/${orgSlug}/teams/`, {
+      method: 'POST',
+      body: JSON.stringify({ slug }),
+    });
+  }
+
+  /**
+   * Projects in the organization (first 100 — slugs are matched exactly,
+   * and a colliding create on a beyond-page project 409s honestly).
+   */
+  async getProjects(orgSlug) {
+    return this.makeRequest(`/organizations/${orgSlug}/projects/?per_page=100`);
+  }
+
+  async createProject(orgSlug, teamSlug, { name, slug, platform }) {
+    return this.makeRequest(`/teams/${orgSlug}/${teamSlug}/projects/`, {
+      method: 'POST',
+      body: JSON.stringify({ name, slug, platform }),
+    });
+  }
+
+  /** Client keys for a project (a fresh project always has one). */
+  async getProjectKeys(orgSlug, projectSlug) {
+    return this.makeRequest(`/projects/${orgSlug}/${projectSlug}/keys/`);
+  }
+}
+
+module.exports = { SentryAPI, SENTRY_API_BASE };

package/dist/services/newsletter/ensure/custom-fields.js

@@ -0,0 +1,90 @@
+/**
+ * Ensure @omega.js/backend's custom fields exist on the Beehiiv publication with the
+ * right kinds.
+ *
+ * The field list comes from @omega.js/backend's marketing SSOT (honoring each
+ * field's provider skip list — Beehiiv needs first/last name as custom
+ * fields, but tracks country and UTM source natively). Beehiiv matches
+ * subscriber values by display name, so fields are diffed by `display`. A
+ * kind mismatch can't be patched — the field is deleted and recreated.
+ * Fields @omega.js/backend doesn't own are never touched.
+ */
+const chalk = require('chalk').default;
+const { fieldsFor } = require('../../../lib/backend-marketing.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+const BEEHIIV_FIELDS = fieldsFor('beehiiv');
+
+// @omega.js/backend type → Beehiiv kind
+const KIND_MAP = { text: 'string', number: 'integer', date: 'datetime' };
+
+module.exports = async function ensureCustomFields(context) {
+  const { beehiivApi: api, serviceData, options = {} } = context;
+
+  const publicationId = serviceData.publicationId;
+  if (!publicationId) {
+    console.log(chalk.dim('      ⊘ No publication yet — nothing to provision fields on'));
+    return {};
+  }
+
+  const existing = await api.getCustomFields(publicationId);
+  const existingByDisplay = Object.fromEntries(existing.map((f) => [f.display, f]));
+
+  const missing = [];
+  const mismatched = [];
+
+  for (const field of BEEHIIV_FIELDS) {
+    const bhField = existingByDisplay[field.display];
+
+    if (!bhField) {
+      missing.push(field);
+    } else if (bhField.kind !== KIND_MAP[field.type]) {
+      mismatched.push({ ...field, existingId: bhField.id, existingKind: bhField.kind });
+    }
+  }
+
+  if (missing.length === 0 && mismatched.length === 0) {
+    console.log(`      ${chalk.green('✓')} All ${BEEHIIV_FIELDS.length} custom fields exist`);
+    return { output: { customFields: { total: BEEHIIV_FIELDS.length, created: 0, recreated: 0 } } };
+  }
+
+  if (options.dryRun) {
+    const planned = {
+      create: missing.map((f) => f.display),
+      recreate: mismatched.map((f) => `${f.display} (${f.existingKind} → ${KIND_MAP[f.type]})`),
+    };
+    return dryRunPlan(`create ${planned.create.length}, recreate ${planned.recreate.length} field(s)`, { output: { customFields: { planned } } });
+  }
+
+  // Kind mismatches: delete, then recreate alongside the missing ones
+  for (const field of mismatched) {
+    await api.deleteCustomField(publicationId, field.existingId);
+    console.log(`      ${chalk.yellow('↻')} Deleted ${chalk.cyan(field.display)} ${chalk.dim(`(was ${field.existingKind}, need ${KIND_MAP[field.type]})`)}`);
+    missing.push(field);
+  }
+
+  for (const field of missing) {
+    await api.createCustomField(publicationId, field.name, field.display, KIND_MAP[field.type]);
+    console.log(`      ${chalk.green('✓')} Created ${chalk.cyan(field.display)}`);
+  }
+
+  // Verify everything actually persisted
+  const verify = await api.getCustomFields(publicationId);
+  const verifyByDisplay = new Set(verify.map((f) => f.display));
+  const stillMissing = BEEHIIV_FIELDS.filter((f) => !verifyByDisplay.has(f.display));
+
+  if (stillMissing.length > 0) {
+    console.log(`      ${chalk.yellow('⚠')} ${stillMissing.length} field(s) failed to persist: ${chalk.cyan(stillMissing.map((f) => f.display).join(', '))}`);
+    return { status: 'warned', reason: `${stillMissing.length} field(s) failed to persist: ${stillMissing.map((f) => f.display).join(', ')}`, output: { customFields: { total: BEEHIIV_FIELDS.length, failed: stillMissing.map((f) => f.display) } } };
+  }
+
+  return {
+    output: {
+      customFields: {
+        total: BEEHIIV_FIELDS.length,
+        created: missing.length - mismatched.length,
+        recreated: mismatched.length,
+      },
+    },
+  };
+};

package/dist/services/newsletter/ensure/publication.js

@@ -0,0 +1,94 @@
+/**
+ * Ensure the brand's Beehiiv publication is configured and accessible.
+ *
+ * Resolution: marketing.newsletter.providers.beehiiv.publicationId from
+ * config → auto-match by brand name/id across the account's publications.
+ * Publications can't be created via API — when nothing matches, the exact
+ * values to copy into the dashboard are printed, and interactive runs open
+ * the create page and poll until the new publication auto-matches;
+ * non-interactive/dry runs warn instead. The resolved id is written back
+ * into omega.json5 (marketing.newsletter.providers.beehiiv.publicationId —
+ * comment-preserving), its ONE authoritative home.
+ */
+const chalk = require('chalk').default;
+const { openBrowserAndPoll } = require('../../../vendor/devkit/flows.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { canPrompt } = require('../../../lib/run-gates.js');
+
+const CREATE_URL = 'https://app.beehiiv.com/settings/workspace/overview?create_publication=true';
+
+module.exports = async function ensurePublication(context) {
+  const { beehiivApi: api, brandConfig } = context;
+
+  const brandName = brandConfig.brand?.name || '';
+  const brandId = brandConfig.brand?.id || '';
+  const configuredId = brandConfig.marketing?.newsletter?.providers?.beehiiv?.publicationId;
+
+  // 1. Configured id — verify access
+  if (configuredId) {
+    const publication = await api.getPublication(configuredId);
+
+    if (!publication) {
+      console.log(`      ${chalk.yellow('⚠')} Publication ${chalk.cyan(configuredId)} is not accessible with this API key — fix the id or the key, then rerun`);
+      return { status: 'warned', reason: 'the configured publication is not accessible with this API key', output: { publication: { publicationId: configuredId, accessible: false } } };
+    }
+
+    console.log(`      ${chalk.green('✓')} ${chalk.cyan(publication.name)} ${chalk.dim(`(${publication.id})`)}`);
+    if (publication.id !== configuredId) {
+      writeBrandConfig(context, { 'marketing.newsletter.providers.beehiiv.publicationId': publication.id });
+    }
+    return { state: { publicationId: publication.id, publicationName: publication.name } };
+  }
+
+  // 2. Auto-match by brand name/id
+  const nameLower = brandName.toLowerCase();
+  const idLower = brandId.toLowerCase();
+  const matchesBrand = (pub) => {
+    const pubName = (pub.name || '').toLowerCase();
+    return pubName.includes(nameLower)
+      || pubName.includes(idLower)
+      || nameLower.includes(pubName)
+      || idLower.includes(pubName.replace(/\s+/g, '-'));
+  };
+
+  const publications = await api.listPublications();
+  const match = publications.find(matchesBrand);
+
+  if (match) {
+    console.log(`      ${chalk.green('✓')} Auto-matched ${chalk.cyan(match.name)} ${chalk.dim(`(${match.id})`)}`);
+    writeBrandConfig(context, { 'marketing.newsletter.providers.beehiiv.publicationId': match.id });
+    return { state: { publicationId: match.id, publicationName: match.name } };
+  }
+
+  // 3. Nothing matches — publications are dashboard-only, print the values to copy
+  console.log(`      ${chalk.yellow('⚠')} No publication matches ${chalk.cyan(brandName)} — create one at ${chalk.cyan(CREATE_URL)}:`);
+  console.log(`        ${chalk.dim('Publication name:')}       ${chalk.cyan(brandName)}`);
+  console.log(`        ${chalk.dim('This publication is...:')} ${chalk.cyan(brandConfig.brand?.description || `News and updates from ${brandName}`)}`);
+  console.log(`        ${chalk.dim('Subdomain:')}              ${chalk.cyan(brandId)}`);
+
+  // Interactive runs: open the dashboard and poll until the publication
+  // appears (same auto-match), then land it in omega.json5
+  if (canPrompt(context.options)) {
+    const result = await openBrowserAndPoll({
+      url: CREATE_URL,
+      label: 'the Beehiiv workspace settings',
+      promptMessage: `Create the publication for ${chalk.cyan(brandName)} with the values above.`,
+      waitMessage: 'Waiting for the publication to appear',
+      check: async () => {
+        const fresh = (await api.listPublications()).find(matchesBrand);
+        return fresh ? { done: true, result: fresh } : { done: false };
+      },
+      intervalMs: 10000,
+      indent: '        ',
+    });
+
+    if (result.success && result.result) {
+      const created = result.result;
+      console.log(`      ${chalk.green('✓')} ${chalk.cyan(created.name)} ${chalk.dim(`(${created.id})`)}`);
+      writeBrandConfig(context, { 'marketing.newsletter.providers.beehiiv.publicationId': created.id });
+      return { state: { publicationId: created.id, publicationName: created.name } };
+    }
+  }
+
+  return { status: 'warned', reason: 'no publication yet — create one in the beehiiv dashboard', output: { publication: { missing: true, suggestedName: brandName } } };
+};