@taodigital/app-brain 0.0.0-stage → 1.2.1

package/src/email.ts

@@ -0,0 +1,268 @@
+import nodemailer from 'nodemailer';
+import { AppBrain } from './repository.js';
+
+// Branding defaults — overridden by DB-backed admin config (getSystemConfig('branding')) at send time.
+const DEFAULT_BRAND_NAME = 'ZeTa-AI';
+const DEFAULT_BRAND_COLOR = '#0ff';
+
+async function getBranding(): Promise<{ brandName: string; brandColor: string; appUrl: string }> {
+  try {
+    const { getSystemConfig } = await import('@taodigital/core');
+    const cfg = (await getSystemConfig('branding')) ?? {};
+    return {
+      brandName: String(cfg.brandName ?? DEFAULT_BRAND_NAME),
+      brandColor: String(cfg.brandColor ?? DEFAULT_BRAND_COLOR),
+      appUrl: String(cfg.appUrl ?? process.env.APP_URL ?? `http://localhost:${process.env.PORT ?? 3000}`),
+    };
+  } catch {
+    return {
+      brandName: DEFAULT_BRAND_NAME,
+      brandColor: DEFAULT_BRAND_COLOR,
+      appUrl: process.env.APP_URL ?? `http://localhost:${process.env.PORT ?? 3000}`,
+    };
+  }
+}
+
+export interface EmailPayload {
+  to: string;
+  name?: string;
+  type: string;
+  title: string;
+  body: string;
+  metadata?: Record<string, unknown>;
+  tenantId?: string;
+}
+
+export interface SendEmailResult {
+  sent: boolean;
+  reason?: string;
+}
+
+export interface EmailDiagnostics {
+  configured: boolean;
+  provider: 'platform-smtp' | 'tenant-smtp' | 'tenant-resend' | 'env-resend' | 'none';
+  missing: string[];
+  message: string;
+}
+
+async function getTenantConfig(tenantId?: string) {
+  if (!tenantId) return null;
+  try { return await AppBrain.getTenantEmailConfig(tenantId); } catch { return null; }
+}
+
+export async function getEmailDiagnostics(tenantId?: string): Promise<EmailDiagnostics> {
+  const { getSystemConfig } = await import('@taodigital/core');
+  const smtpCfg = await getSystemConfig('smtp').catch(() => ({} as Record<string, string>));
+  const smtpHost = (smtpCfg?.host && smtpCfg.host.trim()) || process.env.SMTP_HOST || '';
+  const smtpUser = (smtpCfg?.username && smtpCfg.username.trim()) || process.env.SMTP_USERNAME || process.env.SMTP_USER || '';
+  const smtpPass = (smtpCfg?.password && smtpCfg.password.trim()) || process.env.SMTP_PASSWORD || process.env.SMTP_PASS || '';
+
+  if (smtpHost || smtpUser || smtpPass) {
+    const missing = [
+      !smtpHost ? 'Platform SMTP host' : null,
+      !smtpUser ? 'Platform SMTP username' : null,
+      !smtpPass ? 'Platform SMTP password' : null,
+    ].filter(Boolean) as string[];
+    return {
+      configured: missing.length === 0,
+      provider: 'platform-smtp',
+      missing,
+      message: missing.length === 0
+        ? 'Platform SMTP is configured.'
+        : `Platform SMTP is incomplete: ${missing.join(', ')}.`,
+    };
+  }
+
+  const tenantCfg = await getTenantConfig(tenantId);
+  if (tenantCfg?.provider === 'resend' || tenantCfg?.resendApiKey) {
+    const missing = tenantCfg.resendApiKey ? [] : ['Workspace Resend API key'];
+    return {
+      configured: missing.length === 0,
+      provider: 'tenant-resend',
+      missing,
+      message: missing.length === 0
+        ? 'Workspace Resend email is configured.'
+        : `Workspace Resend email is incomplete: ${missing.join(', ')}.`,
+    };
+  }
+  if (tenantCfg?.smtpHost || tenantCfg?.smtpUser || tenantCfg?.smtpPass) {
+    const missing = [
+      !tenantCfg.smtpHost ? 'Workspace SMTP host' : null,
+      !tenantCfg.smtpUser ? 'Workspace SMTP username' : null,
+      !tenantCfg.smtpPass ? 'Workspace SMTP password' : null,
+    ].filter(Boolean) as string[];
+    return {
+      configured: missing.length === 0,
+      provider: 'tenant-smtp',
+      missing,
+      message: missing.length === 0
+        ? 'Workspace SMTP email is configured.'
+        : `Workspace SMTP email is incomplete: ${missing.join(', ')}.`,
+    };
+  }
+
+  if (process.env.RESEND_API_KEY) {
+    return {
+      configured: true,
+      provider: 'env-resend',
+      missing: [],
+      message: 'Environment Resend email is configured.',
+    };
+  }
+
+  return {
+    configured: false,
+    provider: 'none',
+    missing: ['Email provider'],
+    message: 'No email provider configured. Configure Workspace email, platform SMTP, or RESEND_API_KEY.',
+  };
+}
+
+export async function sendEmail(payload: EmailPayload): Promise<SendEmailResult> {
+  const branding = await getBranding();
+  const html = buildHtml(payload, branding);
+
+  // Platform-level SMTP from DB (admin panel) or env fallback — always wins over tenant config.
+  const { getSystemConfig } = await import('@taodigital/core');
+  const smtpCfg = await getSystemConfig('smtp').catch(() => ({} as Record<string, string>));
+  const smtpHost = (smtpCfg?.host && smtpCfg.host.trim()) || process.env.SMTP_HOST || '';
+  const smtpUser = (smtpCfg?.username && smtpCfg.username.trim()) || process.env.SMTP_USERNAME || process.env.SMTP_USER || '';
+  const smtpPass = (smtpCfg?.password && smtpCfg.password.trim()) || process.env.SMTP_PASSWORD || process.env.SMTP_PASS || '';
+  const smtpPort = Number(smtpCfg?.port || process.env.SMTP_PORT || 587);
+  const smtpFrom = (smtpCfg?.from && smtpCfg.from.trim()) || process.env.SMTP_FROM || process.env.EMAIL_FROM || 'noreply@tucdesk.app';
+  const smtpFromName = (smtpCfg?.fromName && smtpCfg.fromName.trim()) || process.env.SMTP_FROM_NAME || branding.brandName;
+
+  if (smtpHost && smtpUser && smtpPass) {
+    return sendViaSMTP({
+      smtpHost,
+      smtpPort,
+      smtpUser,
+      smtpPass,
+      fromEmail: smtpFrom,
+      fromName: smtpFromName,
+    }, payload.to, payload.title, html, branding.brandName);
+  }
+
+  // Tenant-level config (Workspace → Integrations → Email).
+  const tenantCfg = await getTenantConfig(payload.tenantId);
+  if (tenantCfg?.smtpHost && tenantCfg.smtpUser && tenantCfg.smtpPass) {
+    return sendViaSMTP(tenantCfg, payload.to, payload.title, html, branding.brandName);
+  }
+  if (tenantCfg?.resendApiKey) {
+    return sendViaResend(tenantCfg.resendApiKey, tenantCfg, payload.to, payload.title, html, branding.brandName);
+  }
+
+  // Last resort: env Resend key.
+  const resendKey = process.env.RESEND_API_KEY;
+  if (resendKey) {
+    return sendViaResend(resendKey, null, payload.to, payload.title, html, branding.brandName);
+  }
+  console.warn(`[email] No email provider configured — "${payload.title}" to ${payload.to} not sent.`);
+  return { sent: false, reason: 'No email provider configured. Configure one in Workspace → Integrations → Email, or set RESEND_API_KEY / SMTP_* on the server.' };
+}
+
+async function sendViaResend(
+  apiKey: string,
+  cfg: { fromEmail?: string; fromName?: string } | null,
+  to: string, subject: string, html: string,
+  brandName: string = DEFAULT_BRAND_NAME,
+): Promise<SendEmailResult> {
+  const from = cfg?.fromEmail
+    ? `${cfg.fromName ?? brandName} <${cfg.fromEmail}>`
+    : (process.env.EMAIL_FROM || `${brandName} <onboarding@resend.dev>`);
+  try {
+    const resp = await fetch('https://api.resend.com/emails', {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ from, to: [to], subject, html }),
+    });
+    if (!resp.ok) {
+      const detail = await resp.text();
+      let hint = '';
+      if (resp.status === 403) hint = ' — likely cause: sending domain not verified in Resend dashboard, or API key lacks send permission.';
+      if (resp.status === 422) hint = ' — likely cause: "from" domain not verified in Resend. Add & verify your domain at resend.com/domains.';
+      console.error(`[email] Resend ${resp.status}:`, detail);
+      return { sent: false, reason: `Resend rejected the email (${resp.status})${hint} Detail: ${detail}` };
+    }
+    return { sent: true };
+  } catch (err: any) {
+    console.error('[email] Resend error:', err);
+    return { sent: false, reason: `Resend request failed: ${err?.message ?? err}` };
+  }
+}
+
+async function sendViaSMTP(
+  cfg: { smtpHost?: string; smtpPort?: number; smtpUser?: string; smtpPass?: string; fromEmail?: string; fromName?: string },
+  to: string, subject: string, html: string,
+  brandName: string = DEFAULT_BRAND_NAME,
+): Promise<SendEmailResult> {
+  try {
+    const transport = nodemailer.createTransport({
+      host: cfg.smtpHost,
+      port: cfg.smtpPort ?? 587,
+      secure: (cfg.smtpPort ?? 587) === 465,
+      auth: { user: cfg.smtpUser, pass: cfg.smtpPass },
+    });
+    // Use EMAIL_FROM env var if set; otherwise fall back to smtpUser address (standard practice).
+    // Set EMAIL_FROM=Name <user@domain.com> in env for a clean sender display name.
+    const from = cfg.fromEmail
+      ? `${cfg.fromName ?? brandName} <${cfg.fromEmail}>`
+      : (process.env.EMAIL_FROM ?? `${brandName} <${cfg.smtpUser ?? ''}>`);
+    await transport.sendMail({ from, to, subject, html });
+    return { sent: true };
+  } catch (err: any) {
+    console.error('[email] SMTP error:', err);
+    return { sent: false, reason: `SMTP send failed: ${err?.message ?? err}` };
+  }
+}
+
+/** Internal metadata keys that should never be shown as raw table rows in emails. */
+const HIDDEN_META_KEYS = new Set(['tenantId', 'joinUrl', 'projectId', 'runId']);
+
+function buildHtml(p: EmailPayload, branding: { brandName: string; brandColor: string; appUrl: string }): string {
+  const { brandName, brandColor, appUrl } = branding;
+  const joinUrl = p.metadata?.joinUrl as string | undefined;
+
+  // For invite emails, fall back to the workspace dashboard when no explicit joinUrl is set.
+  const ctaUrl = (p.type === 'invite.created')
+    ? (joinUrl ?? `${appUrl}/dashboard`)
+    : joinUrl;
+
+  const metaHtml = p.metadata
+    ? Object.entries(p.metadata)
+      .filter(([k, v]) => v != null && !HIDDEN_META_KEYS.has(k))
+      .map(([k, v]) => `<tr><td style="color:#888;padding:4px 0;width:120px">${k}</td><td>${v}</td></tr>`)
+      .join('')
+    : '';
+
+  const ctaHtml = ctaUrl
+    ? `<div style="margin-top:24px;text-align:center">
+        <a href="${ctaUrl}"
+           style="display:inline-block;background:${brandColor};color:#000;font-weight:700;font-size:14px;
+                  text-decoration:none;padding:12px 28px;border-radius:8px;letter-spacing:0.3px">
+          Go to Workspace
+        </a>
+      </div>`
+    : '';
+
+  return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"/><meta name="viewport" content="width=device-width"/></head>
+<body style="font-family:system-ui,sans-serif;background:#0d0d0d;color:#e0e0e0;margin:0;padding:32px 16px">
+<div style="max-width:560px;margin:0 auto">
+  <div style="margin-bottom:24px">
+    <span style="font-size:22px;font-weight:700;letter-spacing:-0.5px;color:${brandColor}">${brandName}</span>
+  </div>
+  <div style="background:#161616;border:1px solid #2a2a2a;border-radius:12px;padding:28px">
+    <h2 style="margin:0 0 12px;font-size:18px;font-weight:600">${p.title}</h2>
+    <p style="margin:0 0 20px;color:#bbb;line-height:1.6">${p.body}</p>
+    ${metaHtml ? `<table style="font-size:13px;border-collapse:collapse;width:100%">${metaHtml}</table>` : ''}
+    ${ctaHtml}
+  </div>
+  <p style="font-size:11px;color:#555;margin-top:20px;text-align:center">
+    ${brandName} Quality Intelligence · <a href="${appUrl}/settings/notifications" style="color:#555">Manage notifications</a>
+  </p>
+</div>
+</body>
+</html>`;
+}

package/src/grounding.ts

@@ -0,0 +1,172 @@
+import type { GroundingContext, SkillFileEntry } from '@taodigital/core';
+import { AppBrain } from './repository.js';
+import { rerankStrings } from '@taodigital/reranker';
+import { SKILL_FILE_GLOBAL_KINDS, SKILL_FILE_SELECTIVE_KINDS } from './skill-file-kinds.js';
+
+/**
+ * GROUNDING — how the AI gets real facts before it generates anything.
+ *
+ * Strategy is swappable. Two tiers exist:
+ *
+ *  DirectLoadGrounding (default):
+ *    Loads ALL relevant skill files for a screen in one query.
+ *    Fast and precise for < 300 screens. No vector DB needed.
+ *    Taxonomy retrieval: PLATFORM+FUNCTION+DESIGN+THEME always,
+ *    COMPONENT+ELEMENT filtered to matching screenIds.
+ *
+ *  VectorSearchGrounding (Phase 2+):
+ *    For projects flagged `oversized = true` (300+ screens).
+ *    Runs a semantic similarity search on skill file summaries to find
+ *    the top-K most relevant COMPONENT/ELEMENT files.
+ *    Global tier (PLATFORM/FUNCTION/DESIGN/THEME) still loads directly.
+ */
+export interface GroundingStrategy {
+  ground(tenantId: string, projectId: string, screenId: string): Promise<GroundingContext>;
+}
+
+const SELECTIVE_KINDS = new Set(SKILL_FILE_SELECTIVE_KINDS);
+const MAX_SELECTIVE = 5;
+
+export class DirectLoadGrounding implements GroundingStrategy {
+  async ground(tenantId: string, projectId: string, screenId: string): Promise<GroundingContext> {
+    const [screen, rawSkillFiles, probeObs, outgoingTransitions] = await Promise.all([
+      AppBrain.getScreenWithElements(tenantId, screenId),
+      AppBrain.getRelevantSkillFilesForScreen(tenantId, projectId, screenId),
+      AppBrain.getProbeObservations(tenantId, screenId),
+      AppBrain.getScreenOutgoingTransitions(tenantId, screenId),
+    ]);
+
+    if (!screen) throw new Error(`Screen ${screenId} not found in Zeta Core`);
+
+    const s = screen as any;
+    const global = rawSkillFiles.filter((sf) => !SELECTIVE_KINDS.has(sf.kind as string));
+    const selective = rawSkillFiles.filter((sf) => SELECTIVE_KINDS.has(sf.kind as string));
+
+    // Rerank selective skill files by semantic relevance when multiple candidates exist
+    let rankedSelective = selective;
+    if (selective.length > MAX_SELECTIVE) {
+      const screenQuery = [s.name, s.url, ...s.elements.map((e: any) => e.meaning)].filter(Boolean).join(' ');
+      try {
+        const reranked = await rerankStrings(
+          screenQuery,
+          selective.map((sf) => `${sf.kind} ${sf.summary ?? ''} ${sf.content.slice(0, 400)}`),
+          MAX_SELECTIVE,
+          0,
+        );
+        rankedSelective = reranked.map(({ index }) => selective[index]);
+      } catch {
+        rankedSelective = selective.slice(0, MAX_SELECTIVE);
+      }
+    }
+
+    const skillFiles: SkillFileEntry[] = [...global, ...rankedSelective].map((sf) => ({
+      kind: sf.kind as any,
+      summary: sf.summary ?? undefined,
+      content: sf.content,
+      version: sf.version,
+      approvedBy: sf.approvedBy ?? undefined,
+    }));
+
+    const skillFile = skillFiles.length > 0
+      ? skillFiles.map((sf) => `### ${sf.kind}\n${sf.content}`).join('\n\n')
+      : undefined;
+
+    return {
+      screenName: s.name,
+      url: s.url ?? undefined,
+      elements: s.elements.map((e: any) => ({
+        meaning: e.meaning,
+        role: e.role,
+        expectedData: e.expectedData ?? undefined,
+        notes: e.notes ?? undefined,
+        boundingRect: e.boundingRect as any ?? undefined,
+        ariaState: e.ariaState as any ?? undefined,
+        parentLandmark: e.parentLandmark ?? undefined,
+      })),
+      relatedFlows: (outgoingTransitions as any[]).map((t) => {
+        const dest = t.toScreen?.name ?? 'unknown screen';
+        const action = typeof t.action === 'object' && t.action?.description
+          ? t.action.description
+          : JSON.stringify(t.action ?? {});
+        return `Navigate to "${dest}" via: ${action}`;
+      }),
+      skillFiles,
+      skillFile,
+      recentChanges: [],
+      probeObservations: probeObs.length > 0 ? probeObs as any : undefined,
+      viewport: undefined,
+    };
+  }
+}
+
+/** BM25-backed grounding for oversized projects (300+ screens). */
+export class VectorSearchGrounding implements GroundingStrategy {
+  async ground(tenantId: string, projectId: string, screenId: string): Promise<GroundingContext> {
+    const [screen, probeObs, outgoingTransitions] = await Promise.all([
+      AppBrain.getScreenWithElements(tenantId, screenId),
+      AppBrain.getProbeObservations(tenantId, screenId),
+      AppBrain.getScreenOutgoingTransitions(tenantId, screenId),
+    ]);
+    if (!screen) throw new Error(`Screen ${screenId} not found`);
+
+    const globalFiles = await AppBrain.listSkillFiles(tenantId, projectId, SKILL_FILE_GLOBAL_KINDS) as any[];
+
+    const query = [(screen as any).name, ...(screen as any).elements.map((e: any) => e.meaning)].filter(Boolean).join(' ');
+    const searchResults = await AppBrain.searchKnowledge(tenantId, projectId, query, 5);
+
+    const globalEntries: SkillFileEntry[] = globalFiles.map((sf: any) => ({
+      kind: sf.kind as any,
+      summary: sf.summary ?? undefined,
+      content: sf.content,
+      version: sf.version,
+      approvedBy: sf.approvedBy ?? undefined,
+    }));
+
+    const selectiveEntries: SkillFileEntry[] = searchResults
+      .filter((r: any) => r.source === 'SKILL_FILE')
+      .map((r: any) => ({
+        kind: r.label as any,
+        content: r.content,
+        summary: undefined,
+        version: 1,
+        approvedBy: undefined,
+      }));
+
+    const skillFiles = [...globalEntries, ...selectiveEntries];
+    const skillFile = skillFiles.length > 0
+      ? skillFiles.map((sf) => `### ${sf.kind}\n${sf.content}`).join('\n\n')
+      : undefined;
+
+    const sv = screen as any;
+    return {
+      screenName: sv.name,
+      url: sv.url ?? undefined,
+      elements: sv.elements.map((e: any) => ({
+        meaning: e.meaning,
+        role: e.role,
+        expectedData: e.expectedData ?? undefined,
+        notes: e.notes ?? undefined,
+        boundingRect: e.boundingRect as any ?? undefined,
+        ariaState: e.ariaState as any ?? undefined,
+        parentLandmark: e.parentLandmark ?? undefined,
+      })),
+      relatedFlows: (outgoingTransitions as any[]).map((t) => {
+        const dest = t.toScreen?.name ?? 'unknown screen';
+        const action = typeof t.action === 'object' && t.action?.description
+          ? t.action.description
+          : JSON.stringify(t.action ?? {});
+        return `Navigate to "${dest}" via: ${action}`;
+      }),
+      skillFiles,
+      skillFile,
+      recentChanges: [],
+      probeObservations: probeObs.length > 0 ? probeObs as any : undefined,
+      viewport: undefined,
+    };
+  }
+}
+
+/** Pick grounding strategy. Oversized (300+ screens) uses BM25; others load directly. */
+export function groundingFor(oversized: boolean): GroundingStrategy {
+  return oversized ? new VectorSearchGrounding() : new DirectLoadGrounding();
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export * from './repository.js';
+export { buildNavigationGraph, toMermaid } from './nav-graph.js';
+export type { NavGraph, NavGraphNode, NavGraphEdge } from './nav-graph.js';
+export * from './grounding.js';
+export * from './token-ledger.js';
+export * from './cloud-storage.js';
+export * from './orphan-classification.js';
+export * from './email.js';
+export * from './notifications.js';
+export * from './run-notifications.js';
+export * from './traceability.js';
+export { rerankStrings } from '@taodigital/reranker';
+
+// R2/H4: Standalone export so callers can import rebuildGherkinOutlineForCase by name
+import { AppBrain } from './repository.js';
+export function rebuildGherkinOutlineForCase(tenantId: string, testCaseId: string): Promise<void> {
+  return AppBrain.rebuildGherkinOutlineForCase(tenantId, testCaseId);
+}