@taodigital/app-brain 0.0.0-stage → 1.2.0

package/dist/email.js

@@ -0,0 +1,234 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEmailDiagnostics = getEmailDiagnostics;
+exports.sendEmail = sendEmail;
+const nodemailer_1 = __importDefault(require("nodemailer"));
+const repository_js_1 = require("./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() {
+    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}`,
+        };
+    }
+}
+async function getTenantConfig(tenantId) {
+    if (!tenantId)
+        return null;
+    try {
+        return await repository_js_1.AppBrain.getTenantEmailConfig(tenantId);
+    }
+    catch {
+        return null;
+    }
+}
+async function getEmailDiagnostics(tenantId) {
+    const { getSystemConfig } = await import('@taodigital/core');
+    const smtpCfg = await getSystemConfig('smtp').catch(() => ({}));
+    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);
+        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);
+        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.',
+    };
+}
+async function sendEmail(payload) {
+    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(() => ({}));
+    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, cfg, to, subject, html, brandName = DEFAULT_BRAND_NAME) {
+    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) {
+        console.error('[email] Resend error:', err);
+        return { sent: false, reason: `Resend request failed: ${err?.message ?? err}` };
+    }
+}
+async function sendViaSMTP(cfg, to, subject, html, brandName = DEFAULT_BRAND_NAME) {
+    try {
+        const transport = nodemailer_1.default.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) {
+        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, branding) {
+    const { brandName, brandColor, appUrl } = branding;
+    const joinUrl = p.metadata?.joinUrl;
+    // 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/dist/grounding.d.ts

@@ -0,0 +1,30 @@
+import type { GroundingContext } from '@taodigital/core';
+/**
+ * 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>;
+}
+export declare class DirectLoadGrounding implements GroundingStrategy {
+    ground(tenantId: string, projectId: string, screenId: string): Promise<GroundingContext>;
+}
+/** BM25-backed grounding for oversized projects (300+ screens). */
+export declare class VectorSearchGrounding implements GroundingStrategy {
+    ground(tenantId: string, projectId: string, screenId: string): Promise<GroundingContext>;
+}
+/** Pick grounding strategy. Oversized (300+ screens) uses BM25; others load directly. */
+export declare function groundingFor(oversized: boolean): GroundingStrategy;

package/dist/grounding.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VectorSearchGrounding = exports.DirectLoadGrounding = void 0;
+exports.groundingFor = groundingFor;
+const repository_js_1 = require("./repository.js");
+const reranker_1 = require("@taodigital/reranker");
+const skill_file_kinds_js_1 = require("./skill-file-kinds.js");
+const SELECTIVE_KINDS = new Set(skill_file_kinds_js_1.SKILL_FILE_SELECTIVE_KINDS);
+const MAX_SELECTIVE = 5;
+class DirectLoadGrounding {
+    async ground(tenantId, projectId, screenId) {
+        const [screen, rawSkillFiles, probeObs, outgoingTransitions] = await Promise.all([
+            repository_js_1.AppBrain.getScreenWithElements(tenantId, screenId),
+            repository_js_1.AppBrain.getRelevantSkillFilesForScreen(tenantId, projectId, screenId),
+            repository_js_1.AppBrain.getProbeObservations(tenantId, screenId),
+            repository_js_1.AppBrain.getScreenOutgoingTransitions(tenantId, screenId),
+        ]);
+        if (!screen)
+            throw new Error(`Screen ${screenId} not found in Zeta Core`);
+        const s = screen;
+        const global = rawSkillFiles.filter((sf) => !SELECTIVE_KINDS.has(sf.kind));
+        const selective = rawSkillFiles.filter((sf) => SELECTIVE_KINDS.has(sf.kind));
+        // 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) => e.meaning)].filter(Boolean).join(' ');
+            try {
+                const reranked = await (0, reranker_1.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 = [...global, ...rankedSelective].map((sf) => ({
+            kind: sf.kind,
+            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) => ({
+                meaning: e.meaning,
+                role: e.role,
+                expectedData: e.expectedData ?? undefined,
+                notes: e.notes ?? undefined,
+                boundingRect: e.boundingRect ?? undefined,
+                ariaState: e.ariaState ?? undefined,
+                parentLandmark: e.parentLandmark ?? undefined,
+            })),
+            relatedFlows: outgoingTransitions.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 : undefined,
+            viewport: undefined,
+        };
+    }
+}
+exports.DirectLoadGrounding = DirectLoadGrounding;
+/** BM25-backed grounding for oversized projects (300+ screens). */
+class VectorSearchGrounding {
+    async ground(tenantId, projectId, screenId) {
+        const [screen, probeObs, outgoingTransitions] = await Promise.all([
+            repository_js_1.AppBrain.getScreenWithElements(tenantId, screenId),
+            repository_js_1.AppBrain.getProbeObservations(tenantId, screenId),
+            repository_js_1.AppBrain.getScreenOutgoingTransitions(tenantId, screenId),
+        ]);
+        if (!screen)
+            throw new Error(`Screen ${screenId} not found`);
+        const globalFiles = await repository_js_1.AppBrain.listSkillFiles(tenantId, projectId, skill_file_kinds_js_1.SKILL_FILE_GLOBAL_KINDS);
+        const query = [screen.name, ...screen.elements.map((e) => e.meaning)].filter(Boolean).join(' ');
+        const searchResults = await repository_js_1.AppBrain.searchKnowledge(tenantId, projectId, query, 5);
+        const globalEntries = globalFiles.map((sf) => ({
+            kind: sf.kind,
+            summary: sf.summary ?? undefined,
+            content: sf.content,
+            version: sf.version,
+            approvedBy: sf.approvedBy ?? undefined,
+        }));
+        const selectiveEntries = searchResults
+            .filter((r) => r.source === 'SKILL_FILE')
+            .map((r) => ({
+            kind: r.label,
+            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;
+        return {
+            screenName: sv.name,
+            url: sv.url ?? undefined,
+            elements: sv.elements.map((e) => ({
+                meaning: e.meaning,
+                role: e.role,
+                expectedData: e.expectedData ?? undefined,
+                notes: e.notes ?? undefined,
+                boundingRect: e.boundingRect ?? undefined,
+                ariaState: e.ariaState ?? undefined,
+                parentLandmark: e.parentLandmark ?? undefined,
+            })),
+            relatedFlows: outgoingTransitions.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 : undefined,
+            viewport: undefined,
+        };
+    }
+}
+exports.VectorSearchGrounding = VectorSearchGrounding;
+/** Pick grounding strategy. Oversized (300+ screens) uses BM25; others load directly. */
+function groundingFor(oversized) {
+    return oversized ? new VectorSearchGrounding() : new DirectLoadGrounding();
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+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';
+export declare function rebuildGherkinOutlineForCase(tenantId: string, testCaseId: string): Promise<void>;

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rerankStrings = exports.toMermaid = exports.buildNavigationGraph = void 0;
+exports.rebuildGherkinOutlineForCase = rebuildGherkinOutlineForCase;
+__exportStar(require("./repository.js"), exports);
+var nav_graph_js_1 = require("./nav-graph.js");
+Object.defineProperty(exports, "buildNavigationGraph", { enumerable: true, get: function () { return nav_graph_js_1.buildNavigationGraph; } });
+Object.defineProperty(exports, "toMermaid", { enumerable: true, get: function () { return nav_graph_js_1.toMermaid; } });
+__exportStar(require("./grounding.js"), exports);
+__exportStar(require("./token-ledger.js"), exports);
+__exportStar(require("./cloud-storage.js"), exports);
+__exportStar(require("./orphan-classification.js"), exports);
+__exportStar(require("./email.js"), exports);
+__exportStar(require("./notifications.js"), exports);
+__exportStar(require("./run-notifications.js"), exports);
+__exportStar(require("./traceability.js"), exports);
+var reranker_1 = require("@taodigital/reranker");
+Object.defineProperty(exports, "rerankStrings", { enumerable: true, get: function () { return reranker_1.rerankStrings; } });
+// R2/H4: Standalone export so callers can import rebuildGherkinOutlineForCase by name
+const repository_js_1 = require("./repository.js");
+function rebuildGherkinOutlineForCase(tenantId, testCaseId) {
+    return repository_js_1.AppBrain.rebuildGherkinOutlineForCase(tenantId, testCaseId);
+}

package/dist/nav-graph.d.ts

@@ -0,0 +1,42 @@
+export interface NavGraphNode {
+    id: string;
+    name: string;
+    url: string | null;
+    section: string;
+    sectionColor?: string | null;
+    groupId?: string | null;
+    depth: number | null;
+    entryPoint: boolean;
+    discoveryMethod: string;
+}
+export interface NavGraphEdge {
+    id: string;
+    fromScreenId: string;
+    toScreenId: string | null;
+    href: string;
+    text: string | null;
+    landmark: string | null;
+    linkType: string;
+    source: string;
+    confidence: number;
+    isBackEdge: boolean;
+}
+export interface NavGraph {
+    nodes: NavGraphNode[];
+    edges: NavGraphEdge[];
+    entryPoints: string[];
+    orphans: string[];
+    sections: Record<string, string[]>;
+    sectionColors?: Record<string, string>;
+    stats: {
+        totalNodes: number;
+        totalEdges: number;
+        maxDepth: number | null;
+        sections: string[];
+    };
+}
+export declare function buildNavigationGraph(tenantId: string, projectId: string, opts?: {
+    jobId?: string;
+    maxDepth?: number;
+}): Promise<NavGraph>;
+export declare function toMermaid(graph: NavGraph): string;