@omega.js/manager 0.1.0

package/dist/services/chat/ensure/chat.js

@@ -0,0 +1,106 @@
+/**
+ * Ensure the brand's Chatsy agent has the correct settings + knowledge.
+ *
+ * Knowledge = baseline (data/baseline-knowledge.md with brand values +
+ * generated pricing) + the brand repo's config/chatsy.md when present
+ * (omega-manager read `.brands/{id}/chatsy.md`). The agent image comes
+ * from brand.images.brandmark — omega-manager hardcoded the company CDN;
+ * without a brandmark the image field simply isn't managed.
+ *
+ * Diff-synced on the managed leaf fields and patched with a leaf mask so
+ * Chatsy-owned fields (owner, id, metadata, other settings) survive —
+ * omega-manager merge-wrote on every run with no dry-run guard, and
+ * silently created an orphan agent document when the id was wrong; a
+ * missing agent is a visible error now (agents are created in the Chatsy
+ * dashboard).
+ */
+const { join } = require('node:path');
+const fs = require('node:fs');
+const chalk = require('chalk').default;
+const { getBaselineKnowledge } = require('../lib/baseline-knowledge.js');
+const { absoluteBrandImage } = require('../../../lib/brand.js');
+
+module.exports = async function ensureChat(context) {
+  const { brandConfig, brandRoot, db, agentId, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  const brandName = brandConfig.brand.name;
+  const websiteUrl = brandConfig.brand.url;
+
+  // Brand-specific knowledge file (plain text, appended after the baseline)
+  const knowledgePath = join(brandRoot, 'config', 'chatsy.md');
+  const brandKnowledge = (fs.existsSync(knowledgePath) ? fs.readFileSync(knowledgePath, 'utf8') : '')
+    .trim()
+    .replaceAll('{website}', websiteUrl);
+
+  const baseline = getBaselineKnowledge(brandConfig);
+  const knowledge = brandKnowledge ? `${baseline}\n\n${brandKnowledge}` : baseline;
+
+  const image = absoluteBrandImage(brandConfig, 'brandmark');
+
+  const desired = {
+    name: `${brandName} Support`,
+    settings: {
+      welcomeMessage: `Welcome to the ${brandName} Support chat! How can I help you?`,
+      agent: {
+        language: 'EN',
+        ...(image ? { image } : {}),
+      },
+      autoTranslate: true,
+      brand: {
+        name: brandName,
+        about: brandConfig.brand.description || '',
+        website: websiteUrl,
+        knowledge,
+      },
+    },
+  };
+
+  const fieldPaths = [
+    'name',
+    'settings.welcomeMessage',
+    'settings.agent.language',
+    ...(image ? ['settings.agent.image'] : []),
+    'settings.autoTranslate',
+    'settings.brand.name',
+    'settings.brand.about',
+    'settings.brand.website',
+    'settings.brand.knowledge',
+  ];
+
+  const agent = await db.getDoc(`agents/${agentId}`);
+
+  if (!agent) {
+    console.log(`      ${chalk.red('✗')} Agent ${chalk.cyan(agentId)} not found in Chatsy — check inbound.chat.providers.chatsy.agentId (agents are created at ${chalk.cyan('https://chatsy.ai')})`);
+    return { status: 'error', error: `agent ${agentId} not found` };
+  }
+
+  const settings = agent.settings || {};
+  const drifted = agent.name !== desired.name
+    || settings.welcomeMessage !== desired.settings.welcomeMessage
+    || settings.agent?.language !== 'EN'
+    || (image && settings.agent?.image !== image)
+    || settings.autoTranslate !== true
+    || settings.brand?.name !== brandName
+    || settings.brand?.about !== desired.settings.brand.about
+    || settings.brand?.website !== websiteUrl
+    || settings.brand?.knowledge !== knowledge;
+
+  if (!drifted) {
+    console.log(`      ${chalk.green('✓')} Agent ${chalk.dim(agentId)} in sync ${chalk.dim(`(${desired.name})`)}`);
+    console.log(`        ${chalk.dim(`Knowledge: ${knowledge.length} chars (baseline + ${brandKnowledge.length} brand-specific)`)}`);
+    return { state: { agentId }, output: { chat: { synced: true } } };
+  }
+
+  if (dryRun) {
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would update agent ${chalk.cyan(agentId)} ${chalk.dim(`(${desired.name}, ${knowledge.length} chars knowledge)`)}`);
+    return { output: { chat: { planned: 'update' } } };
+  }
+
+  await db.patchDoc(`agents/${agentId}`, desired, fieldPaths);
+
+  console.log(`      ${chalk.green('✓')} Agent ${chalk.dim(agentId)} updated ${chalk.dim(`(${desired.name})`)}`);
+  console.log(`        ${chalk.dim(`Knowledge: ${knowledge.length} chars (baseline + ${brandKnowledge.length} brand-specific)`)}`);
+
+  return { state: { agentId }, output: { chat: { updated: true } } };
+};

package/dist/services/chat/ensure/user.js

@@ -0,0 +1,45 @@
+/**
+ * Ensure the brand's Chatsy owner account has the configured plan.
+ *
+ * The agent's owner UID identifies the user account; that user's
+ * subscription is set to inbound.chat.providers.chatsy.plan (DEFAULTS: Chatsy's Max top tier)
+ * via the shared owner-plan reconciliation. omega-manager resolved the
+ * plan by reading the chatsy brand's own config from `.brands/` (company
+ * mode); the port takes it from the brand's config with the top tier as
+ * the default.
+ */
+const chalk = require('chalk').default;
+const { ensureOwnerPlan } = require('../../../lib/owner-plan.js');
+
+module.exports = async function ensureUser(context) {
+  const { brandConfig, db, agentId, options } = context;
+
+  const plan = brandConfig.inbound?.chat?.providers?.chatsy?.plan;
+  if (!plan?.id) {
+    console.log(`      ${chalk.red('✗')} No inbound.chat.providers.chatsy.plan configured`);
+    return { status: 'error', error: 'no inbound.chat.providers.chatsy.plan.id configured' };
+  }
+
+  // The agent document carries the owner UID
+  const agent = await db.getDoc(`agents/${agentId}`);
+
+  if (!agent) {
+    console.log(`      ${chalk.red('✗')} Agent ${chalk.cyan(agentId)} not found in Chatsy — check inbound.chat.providers.chatsy.agentId`);
+    return { status: 'error', error: `agent ${agentId} not found` };
+  }
+
+  const ownerUid = agent.owner;
+
+  if (!ownerUid) {
+    console.log(`      ${chalk.red('✗')} Agent ${chalk.cyan(agentId)} has no owner field`);
+    return { status: 'error', error: `agent ${agentId} has no owner` };
+  }
+
+  const result = await ensureOwnerPlan({ db, ownerUid, plan, dryRun: options?.dryRun || false });
+
+  if (result === 'planned') {
+    return { output: { user: { planned: plan.id } } };
+  }
+
+  return { state: { accountId: ownerUid }, output: { user: { plan: plan.id, [result]: true } } };
+};

package/dist/services/chat/index.js

@@ -0,0 +1,139 @@
+/**
+ * Chat service (`inbound.chat.providers.chatsy`) — the brand's support chat
+ * agent on Chatsy (chatsy.ai): keeps the agent's settings + knowledge in sync
+ * (baseline knowledge with brand values filled in + generated pricing + the
+ * brand repo's config/chatsy.md appended) and sets the agent-owner account to
+ * the configured plan (Chatsy's top tier by default) so the brand has full
+ * access. Agents live in Chatsy's own Firestore, so this service is for
+ * the Chatsy operator: it needs a service account for Chatsy's Firebase
+ * project.
+ *
+ * Auth tiers (2b, Ian 2026-07-13):
+ *   1. Operator SA — CHATSY_SERVICE_ACCOUNT in the brand .env (path to the
+ *      service-account JSON, absolute or brand-root-relative). Full create
+ *      + manage: a missing agentId with `inbound.chat.providers.chatsy.templateAgentId` configured
+ *      (the company layer's shape donor) MINTS the brand's own agent —
+ *      product user (email = brand contact email, password via the account
+ *      service's owner channels) + doc shape-templated from the donor —
+ *      and writes the new id back into omega.json5. The ensures then
+ *      converge name/knowledge/plan in the same run.
+ *   2. User API key — CHATSY_API_KEY (the product accepts
+ *      user.api.privateKey): recognized, management via the product's
+ *      public API lands when those routes are verified.
+ *   3. Dashboard — interactive runs offer the setup flow (open chatsy.ai,
+ *      paste the agent id back — comment-preserving writeback, with a
+ *      Disable option that sets `chatsy: false`). Non-interactive and dry
+ *      runs skip cleanly.
+ */
+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 { FirestoreREST, loadServiceAccount } = require('../../lib/firestore-rest.js');
+const { createAuthAdmin } = require('../../lib/auth-admin.js');
+const { resolveConfigValue, landValue } = require('../../lib/config-flow.js');
+const { createProductAsset } = require('../../lib/product-create.js');
+const { createPasswordResolver } = require('../account/lib/resolve-password.js');
+
+const CHATSY_URL = 'https://chatsy.ai';
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const config = context.brandConfig.inbound?.chat?.providers?.chatsy;
+
+    if (config === false || config?.enabled === false) {
+      return { skip: true, reason: 'inbound.chat.providers.chatsy.enabled = false' };
+    }
+
+    // A shared agent managed by another brand must not be rewritten here
+    if (config?.updateAgentInfo === false) {
+      return { skip: true, reason: 'agent managed by another brand (inbound.chat.providers.chatsy.updateAgentInfo = false)' };
+    }
+
+    // The chat widget lives on the brand's website
+    if (!context.brandConfig.targets?.web) {
+      return { skip: true, reason: 'no web target' };
+    }
+
+    // Operator credentials first — create-on-missing needs them before the
+    // id resolution. Tests inject fakes via context.chatsyDb/-AuthAdmin.
+    let db = context.chatsyDb;
+    let authAdmin = context.chatsyAuthAdmin;
+    if (!db) {
+      const envPath = process.env.CHATSY_SERVICE_ACCOUNT;
+      if (envPath) {
+        const serviceAccount = loadServiceAccount(envPath, context.brandRoot);
+        db = new FirestoreREST(serviceAccount);
+        authAdmin = createAuthAdmin(serviceAccount);
+      }
+    }
+
+    const brand = context.brandConfig.brand || {};
+    const dryRun = context.options?.dryRun || false;
+    let agentId = config?.agentId;
+
+    // 2b create-on-missing: operator SA + a template donor → a missing agent
+    // means MINT the brand's own (product user + doc), write the id back,
+    // and let the ensures below converge it in this same run.
+    if (!agentId && db && authAdmin && config?.templateAgentId && brand.contact?.email) {
+      const created = await createProductAsset({
+        db,
+        authAdmin,
+        collection: 'agents',
+        templateId: config.templateAgentId,
+        email: brand.contact.email,
+        resolvePassword: createPasswordResolver({
+          brandRoot: context.brandRoot,
+          domain: new URL(brand.url || 'https://invalid.test').hostname,
+          brand,
+          dryRun,
+        }),
+        dryRun,
+        log: (line) => console.log(`      ${line}`),
+      });
+
+      if (!created) {
+        return { skip: true, reason: 'dry run — agent creation planned (from inbound.chat.providers.chatsy.templateAgentId)' };
+      }
+
+      landValue(context, 'inbound.chat.providers.chatsy.agentId', created.id);
+      console.log(`      ${chalk.green('✓')} inbound.chat.providers.chatsy.agentId = ${chalk.cyan(created.id)} written to omega.json5`);
+      agentId = created.id;
+    }
+
+    if (!agentId) {
+      agentId = await resolveConfigValue(context, {
+        path: 'inbound.chat.providers.chatsy.agentId',
+        label: 'Chatsy chat agent',
+        instructions: [
+          `1. Create an account at ${chalk.cyan(CHATSY_URL)} (if you haven't already)`,
+          `2. Create a chat agent for ${chalk.cyan(brand.name || context.brandId)}`,
+        ],
+        entry: { url: CHATSY_URL, message: 'Chatsy agent ID:' },
+        disablePath: 'inbound.chat.providers.chatsy',
+      });
+    }
+    if (!agentId) {
+      return { skip: true, reason: 'no inbound.chat.providers.chatsy.agentId configured — set inbound.chat.providers.chatsy.templateAgentId + the operator SA to mint one automatically, create one at https://chatsy.ai (paste back interactively), or set it in omega.json5' };
+    }
+
+    if (!db) {
+      if (process.env.CHATSY_API_KEY) {
+        return {
+          skip: true,
+          reason: 'CHATSY_API_KEY recognized, but product-API management is not wired yet — use the operator SA (CHATSY_SERVICE_ACCOUNT) or the dashboard',
+        };
+      }
+
+      // The shared setup contract (#608): the operator SA is asked for right
+      // here — most brands are not the Chatsy operator and answer Disable,
+      // which retires the ask for good.
+      const gate = await requestServiceInput(context, serviceInputSpec('chat'));
+      if (gate) return gate;
+      db = new FirestoreREST(loadServiceAccount(process.env.CHATSY_SERVICE_ACCOUNT, context.brandRoot));
+    }
+
+    return { db, agentId };
+  },
+});

package/dist/services/chat/lib/baseline-knowledge.js

@@ -0,0 +1,137 @@
+/**
+ * Baseline knowledge for Chatsy chat agents — the shared knowledge every
+ * brand agent gets, loaded from baseline-knowledge.md with the brand's
+ * values filled in. Brand-specific knowledge from the brand repo's
+ * config/chatsy.md is appended after this by the chat operation.
+ *
+ * Placeholders: {website} (brand.url), {description} (brand.description),
+ * {pricing} (generated from payment.products), and {sponsorshipsUrl}
+ * (inbound.chat.providers.chatsy.sponsorshipsUrl, default {website}/contact — omega-manager
+ * hardcoded the company sponsorship page here).
+ */
+const { join } = require('node:path');
+const fs = require('node:fs');
+
+const BASELINE_KNOWLEDGE = fs.readFileSync(join(__dirname, '..', 'data', 'baseline-knowledge.md'), 'utf8').trimEnd();
+
+/**
+ * Format what a product promises as a human-readable string
+ * ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)).
+ *
+ * A product's `features` map names only VALUES; the top-level `features`
+ * catalog is what says what each id is CALLED, so the agent quotes the brand's
+ * own words rather than a raw key. A `false` (or absent) value is not part of
+ * the tier and is never mentioned.
+ *
+ * @param {Object} values - the product's `features` map, e.g. { requests: 100, support: true }
+ * @param {Object} catalog - the top-level `features` catalog
+ * @returns {string} - e.g., "100 API Requests, unlimited Saves, Priority support"
+ */
+function formatFeatures(values, catalog) {
+  if (!values) {
+    return '';
+  }
+
+  return Object.entries(values)
+    .filter(([, value]) => value !== false && value !== '' && value !== undefined && value !== null)
+    .map(([key, value]) => {
+      const name = catalog?.[key]?.name || key;
+
+      if (value === -1) {
+        return `unlimited ${name}`;
+      }
+      if (value === true) {
+        return name;
+      }
+      return `${value} ${name}`;
+    })
+    .join(', ');
+}
+
+/**
+ * Format a product's prices as a human-readable string
+ *
+ * @param {Object} prices - e.g., { monthly: 9, annually: 90 }
+ * @returns {string} - e.g., "$9/month or $90/year"
+ */
+function formatPrices(prices) {
+  if (!prices) {
+    return '';
+  }
+
+  const labels = {
+    daily: 'day',
+    weekly: 'week',
+    monthly: 'month',
+    annually: 'year',
+    once: 'one-time',
+  };
+
+  return Object.entries(prices)
+    .map(([interval, amount]) => `$${amount}/${labels[interval] || interval}`)
+    .join(' or ');
+}
+
+/**
+ * Generate the pricing section from payment.products config
+ */
+function generatePricing(brandConfig) {
+  const products = brandConfig.payment?.products;
+
+  if (!products || products.length === 0) {
+    return '';
+  }
+
+  const lines = ['Pricing / plans:'];
+
+  for (const product of products) {
+    if (product.archived) {
+      continue;
+    }
+
+    const parts = [`- ${product.name}`];
+
+    if (product.prices && Object.keys(product.prices).length > 0) {
+      parts.push(`(${formatPrices(product.prices)})`);
+    } else {
+      parts.push('(free)');
+    }
+
+    const features = formatFeatures(product.features, brandConfig.features);
+    if (features) {
+      parts.push(`- ${features}`);
+    }
+
+    if (product.trial?.days) {
+      parts.push(`(${product.trial.days}-day free trial)`);
+    }
+
+    lines.push(parts.join(' '));
+  }
+
+  lines.push('- We offer a risk-free free trial of any paid plan. You can cancel any time during your free trial and you will not be charged.');
+  lines.push(`- You can find more information at {website}/pricing`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Get the baseline knowledge string with placeholders replaced
+ *
+ * @param {Object} brandConfig - The full brand config object
+ * @returns {string} - Baseline knowledge with placeholders replaced
+ */
+function getBaselineKnowledge(brandConfig) {
+  const websiteUrl = brandConfig.brand.url;
+  const pricing = generatePricing(brandConfig);
+  const description = brandConfig.brand.description || brandConfig.brand.name;
+  const sponsorshipsUrl = brandConfig.inbound?.chat?.providers?.chatsy?.sponsorshipsUrl || `${websiteUrl}/contact`;
+
+  return BASELINE_KNOWLEDGE
+    .replace('{description}', description)
+    .replace('{pricing}', pricing)
+    .replace('{sponsorshipsUrl}', sponsorshipsUrl)
+    .replaceAll('{website}', websiteUrl);
+}
+
+module.exports = { getBaselineKnowledge };