@taodigital/app-brain 0.0.0-stage → 1.2.0

package/dist/nav-graph.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildNavigationGraph = buildNavigationGraph;
+exports.toMermaid = toMermaid;
+const database_1 = require("@taodigital/database");
+function classifySection(url, name) {
+    const text = (url ?? name).toLowerCase();
+    if (/\/(login|signin|sign-in|register|signup|sign-up|auth|forgot|reset|verify|otp|mfa|sso)/.test(text))
+        return 'Authentication';
+    if (/\/(admin|administration|manage|management|superuser)/.test(text))
+        return 'Administration';
+    if (/\/(settings|preferences|profile|account|config|configuration)/.test(text))
+        return 'Settings';
+    if (/\/(dashboard|home|overview|summary|analytics|reports|metrics)/.test(text))
+        return 'Dashboard';
+    if (/\/(checkout|cart|basket|payment|order-review|billing)/.test(text))
+        return 'Checkout';
+    if (/\/(product|products|item|items|catalog|shop|store|collection)/.test(text))
+        return 'Catalog';
+    if (/\/(order|orders|history|purchases)/.test(text))
+        return 'Orders';
+    if (/\/(user|users|member|members|team|customers)/.test(text))
+        return 'Users';
+    // Extract primary URL path segment if available (e.g. /inventory -> Inventory)
+    if (url) {
+        try {
+            const parsed = new URL(url.startsWith('http') ? url : `https://example.com${url.startsWith('/') ? '' : '/'}${url}`);
+            const segments = parsed.pathname.split('/').filter(Boolean);
+            if (segments.length > 0) {
+                const seg = segments[0].replace(/[^a-zA-Z0-9_-]/g, '');
+                if (seg.length > 1 && !/^[0-9a-f-]{8,}$/i.test(seg)) {
+                    return seg.charAt(0).toUpperCase() + seg.slice(1).replace(/[-_]/g, ' ');
+                }
+            }
+        }
+        catch { }
+    }
+    return 'Application';
+}
+async function buildNavigationGraph(tenantId, projectId, opts = {}) {
+    return (0, database_1.withTenant)(tenantId, async (tx) => {
+        const [screens, screenGroups] = await Promise.all([
+            tx.screen.findMany({
+                where: { tenantId, projectId, status: 'ACTIVE' },
+                select: {
+                    id: true,
+                    name: true,
+                    url: true,
+                    depth: true,
+                    discoveryMethod: true,
+                    groupId: true,
+                    group: { select: { id: true, name: true, slug: true, color: true } },
+                },
+            }),
+            tx.screenGroup.findMany({
+                where: { tenantId, projectId },
+                orderBy: { order: 'asc' },
+                include: {
+                    screens: {
+                        where: { status: 'ACTIVE' },
+                        select: { id: true, name: true, url: true },
+                    },
+                },
+            }),
+        ]);
+        const linksWhere = { tenantId, projectId };
+        if (opts.jobId)
+            linksWhere.jobId = opts.jobId;
+        const links = await tx.discoveredLink.findMany({
+            where: linksWhere,
+            select: {
+                id: true,
+                fromScreenId: true,
+                toScreenId: true,
+                href: true,
+                text: true,
+                landmark: true,
+                linkType: true,
+                source: true,
+                confidence: true,
+            },
+        });
+        const screenIds = new Set(screens.map((s) => s.id));
+        const inboundCount = new Map();
+        for (const s of screens)
+            inboundCount.set(s.id, 0);
+        for (const l of links) {
+            if (l.toScreenId && screenIds.has(l.toScreenId)) {
+                inboundCount.set(l.toScreenId, (inboundCount.get(l.toScreenId) ?? 0) + 1);
+            }
+        }
+        // Build screen-to-group map and section colors
+        const screenToGroupMap = new Map();
+        const sectionColors = {};
+        for (const g of screenGroups) {
+            if (g.name && g.color) {
+                sectionColors[g.name] = g.color;
+            }
+            for (const sc of (g.screens ?? [])) {
+                screenToGroupMap.set(sc.id, { id: g.id, name: g.name, color: g.color });
+            }
+        }
+        // Compute BFS depth from entry points via discovered link edges
+        const adjacency = new Map(); // fromScreenId -> [toScreenId]
+        for (const l of links) {
+            if (!l.toScreenId)
+                continue;
+            if (!adjacency.has(l.fromScreenId))
+                adjacency.set(l.fromScreenId, []);
+            adjacency.get(l.fromScreenId).push(l.toScreenId);
+        }
+        const depths = new Map();
+        const entryIds = screens
+            .filter((s) => s.discoveryMethod === 'ENTRY_POINT' || s.discoveryMethod === 'SEED_URL')
+            .map((s) => s.id);
+        const bfsQueue = [...entryIds];
+        for (const id of entryIds)
+            depths.set(id, 0);
+        while (bfsQueue.length > 0) {
+            const cur = bfsQueue.shift();
+            const curDepth = depths.get(cur);
+            for (const next of (adjacency.get(cur) ?? [])) {
+                if (!depths.has(next)) {
+                    depths.set(next, curDepth + 1);
+                    bfsQueue.push(next);
+                }
+            }
+        }
+        const nodes = screens.map((s) => {
+            const assignedGroup = s.group ?? screenToGroupMap.get(s.id);
+            let section = assignedGroup?.name;
+            let sectionColor = assignedGroup?.color ?? null;
+            if (!section && screenGroups.length > 0) {
+                const text = `${s.url ?? ''} ${s.name ?? ''}`.toLowerCase();
+                const matched = screenGroups.find((g) => (g.slug && text.includes(g.slug.toLowerCase())) ||
+                    (g.name && text.includes(g.name.toLowerCase())));
+                if (matched) {
+                    section = matched.name;
+                    sectionColor = matched.color;
+                }
+            }
+            if (!section) {
+                section = classifySection(s.url, s.name);
+            }
+            return {
+                id: s.id,
+                name: s.name,
+                url: s.url ?? null,
+                section,
+                sectionColor,
+                groupId: assignedGroup?.id ?? s.groupId ?? null,
+                depth: depths.get(s.id) ?? s.depth ?? null,
+                entryPoint: s.discoveryMethod === 'ENTRY_POINT' || s.discoveryMethod === 'SEED_URL',
+                discoveryMethod: s.discoveryMethod,
+            };
+        });
+        // Detect back-edges: edge goes to a node with lower or equal depth
+        const edges = links.map((l) => {
+            const fromDepth = depths.get(l.fromScreenId) ?? null;
+            const toDepth = l.toScreenId ? (depths.get(l.toScreenId) ?? null) : null;
+            const isBackEdge = fromDepth !== null && toDepth !== null && toDepth <= fromDepth;
+            return {
+                id: l.id,
+                fromScreenId: l.fromScreenId,
+                toScreenId: l.toScreenId ?? null,
+                href: l.href,
+                text: l.text ?? null,
+                landmark: l.landmark ?? null,
+                linkType: l.linkType,
+                source: l.source,
+                confidence: l.confidence,
+                isBackEdge,
+            };
+        });
+        const entryPoints = nodes.filter((n) => n.entryPoint).map((n) => n.id);
+        const orphans = nodes
+            .filter((n) => !n.entryPoint && (inboundCount.get(n.id) ?? 0) === 0)
+            .map((n) => n.id);
+        const sectionMap = {};
+        for (const node of nodes) {
+            if (!sectionMap[node.section])
+                sectionMap[node.section] = [];
+            sectionMap[node.section].push(node.id);
+        }
+        // Ensure all discovered screen groups with matching screens are reflected in sectionMap
+        for (const g of screenGroups) {
+            if (g.name && !sectionMap[g.name] && (g.screens?.length ?? 0) > 0) {
+                const matchingIds = g.screens.map((sc) => sc.id).filter((id) => screenIds.has(id));
+                if (matchingIds.length > 0) {
+                    sectionMap[g.name] = matchingIds;
+                }
+            }
+        }
+        const depths2 = nodes.map((n) => n.depth).filter((d) => d !== null);
+        const maxDepth = depths2.length > 0 ? Math.max(...depths2) : null;
+        return {
+            nodes,
+            edges,
+            entryPoints,
+            orphans,
+            sections: sectionMap,
+            sectionColors,
+            stats: {
+                totalNodes: nodes.length,
+                totalEdges: edges.length,
+                maxDepth,
+                sections: Object.keys(sectionMap),
+            },
+        };
+    });
+}
+function toMermaid(graph) {
+    const lines = ['flowchart TD'];
+    // Group nodes by section as subgraphs
+    const sectionLabels = {
+        auth: 'Authentication',
+        dashboard: 'Dashboard',
+        settings: 'Settings',
+        admin: 'Admin',
+        app: 'Application',
+    };
+    for (const [section, nodeIds] of Object.entries(graph.sections)) {
+        if (!nodeIds.length)
+            continue;
+        const subId = section.replace(/[^a-zA-Z0-9_]/g, '_') || 'sec';
+        lines.push(`  subgraph ${subId}["${sanitizeMermaid(sectionLabels[section] ?? section)}"]`);
+        for (const nodeId of nodeIds) {
+            const node = graph.nodes.find((n) => n.id === nodeId);
+            if (!node)
+                continue;
+            const shape = node.entryPoint ? `([${sanitizeMermaid(node.name)}])` : `[${sanitizeMermaid(node.name)}]`;
+            lines.push(`    ${nodeId}${shape}`);
+        }
+        lines.push('  end');
+    }
+    // Edges
+    for (const edge of graph.edges) {
+        if (!edge.toScreenId)
+            continue;
+        const label = edge.text ? `|"${sanitizeMermaid(edge.text.slice(0, 30))}"| ` : '';
+        const arrow = edge.isBackEdge ? '-.->' : '-->';
+        lines.push(`  ${edge.fromScreenId} ${arrow} ${label}${edge.toScreenId}`);
+    }
+    return lines.join('\n');
+}
+function sanitizeMermaid(s) {
+    return s.replace(/["[\](){}|>]/g, ' ').trim();
+}

package/dist/notifications.d.ts

@@ -0,0 +1,26 @@
+export type NotificationEvent = 'invite.created' | 'invite.received' | 'crawl.done' | 'crawl.failed' | 'test.generated' | 'test.run.done' | 'test.run.failed' | 'review.assigned' | 'token.budget.alert' | string;
+export interface DispatchOptions {
+    tenantId: string;
+    userId: string;
+    type: NotificationEvent;
+    title: string;
+    body: string;
+    metadata?: Record<string, unknown>;
+    /** extra email fields — only used if email pref enabled */
+    email?: {
+        recipientEmail: string;
+        recipientName?: string;
+    };
+}
+export interface DispatchResult {
+    emailSent: boolean;
+    emailReason?: string;
+}
+/** Dispatch a single notification (in-app + email if prefs allow). Fire-and-forget safe. */
+export declare function dispatchNotification(opts: DispatchOptions): Promise<DispatchResult>;
+/** Dispatch to all active members of a tenant (respecting each user's in-app and email preferences) */
+export declare function dispatchToTenantMembers(tenantId: string, opts: Omit<DispatchOptions, 'tenantId' | 'userId' | 'email'>): Promise<void>;
+/** Dispatch to all members of a tenant (alias to dispatchToTenantMembers) */
+export declare function dispatchToTenantAdmins(tenantId: string, opts: Omit<DispatchOptions, 'tenantId' | 'userId' | 'email'>): Promise<void>;
+/** Dispatch to all project members */
+export declare function dispatchToProjectMembers(tenantId: string, _projectId: string, opts: Omit<DispatchOptions, 'tenantId' | 'userId' | 'email'>): Promise<void>;

package/dist/notifications.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchNotification = dispatchNotification;
+exports.dispatchToTenantMembers = dispatchToTenantMembers;
+exports.dispatchToTenantAdmins = dispatchToTenantAdmins;
+exports.dispatchToProjectMembers = dispatchToProjectMembers;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const database_1 = require("@taodigital/database");
+const email_js_1 = require("./email.js");
+/** Dispatch a single notification (in-app + email if prefs allow). Fire-and-forget safe. */
+async function dispatchNotification(opts) {
+    // 1. Check user preference (default: both enabled if no row exists)
+    // Check exact eventType, or normalized (dots vs underscores, e.g. test.run.failed vs test_run_failed)
+    const eventTypesToCheck = [
+        opts.type,
+        opts.type.replace(/_/g, '.'),
+        opts.type.replace(/\./g, '_'),
+    ];
+    if (opts.type === 'invite.created')
+        eventTypesToCheck.push('invite.received');
+    if (opts.type === 'invite.received')
+        eventTypesToCheck.push('invite.created');
+    const pref = await (0, database_1.withTenant)(opts.tenantId, (tx) => tx.notificationPreference.findFirst({
+        where: {
+            userId: opts.userId,
+            tenantId: opts.tenantId,
+            eventType: { in: eventTypesToCheck },
+        },
+    })).catch(() => null);
+    const inAppEnabled = pref ? pref.inApp : true;
+    const emailEnabled = pref ? pref.email : true;
+    // 2. Create in-app notification
+    if (inAppEnabled) {
+        await (0, database_1.withTenant)(opts.tenantId, (tx) => tx.notification.create({
+            data: {
+                id: `notif_${node_crypto_1.default.randomUUID()}`,
+                tenantId: opts.tenantId,
+                userId: opts.userId,
+                type: opts.type,
+                title: opts.title,
+                body: opts.body,
+                metadata: opts.metadata,
+            },
+        })).catch(console.error);
+    }
+    // 3. Send email if enabled
+    if (emailEnabled) {
+        let recipientEmail = opts.email?.recipientEmail;
+        let recipientName = opts.email?.recipientName;
+        // Resolve user's registered email if not explicitly provided
+        if (!recipientEmail && opts.userId) {
+            const u = await (0, database_1.withTenant)(opts.tenantId, (tx) => tx.user.findUnique({
+                where: { id: opts.userId },
+                select: { email: true, name: true },
+            })).catch(() => null);
+            if (u?.email) {
+                recipientEmail = u.email;
+                recipientName = u.name ?? undefined;
+            }
+        }
+        if (recipientEmail) {
+            try {
+                const result = await (0, email_js_1.sendEmail)({
+                    to: recipientEmail,
+                    name: recipientName,
+                    type: opts.type,
+                    title: opts.title,
+                    body: opts.body,
+                    metadata: opts.metadata,
+                    tenantId: opts.tenantId,
+                });
+                return { emailSent: result.sent, emailReason: result.reason };
+            }
+            catch (err) {
+                console.error('[notifications] sendEmail error:', err);
+                return { emailSent: false, emailReason: err?.message ?? String(err) };
+            }
+        }
+    }
+    return { emailSent: false, emailReason: emailEnabled ? 'No recipient email available.' : 'Recipient disabled email for this event.' };
+}
+/** Dispatch to all active members of a tenant (respecting each user's in-app and email preferences) */
+async function dispatchToTenantMembers(tenantId, opts) {
+    const members = await (0, database_1.withTenant)(tenantId, (tx) => tx.membership.findMany({
+        where: { tenantId, status: 'ACTIVE' },
+        include: { user: { select: { email: true, name: true } } },
+    })).catch(() => []);
+    await Promise.all(members.map((m) => dispatchNotification({
+        ...opts,
+        tenantId,
+        userId: m.userId,
+        email: m.user?.email ? { recipientEmail: m.user.email, recipientName: m.user.name ?? undefined } : undefined,
+    })));
+}
+/** Dispatch to all members of a tenant (alias to dispatchToTenantMembers) */
+async function dispatchToTenantAdmins(tenantId, opts) {
+    return dispatchToTenantMembers(tenantId, opts);
+}
+/** Dispatch to all project members */
+async function dispatchToProjectMembers(tenantId, _projectId, opts) {
+    return dispatchToTenantMembers(tenantId, opts);
+}

package/dist/orphan-classification.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Orphan-page classification — pure logic, no I/O, so it's unit-testable in
+ * isolation. See docs/research/25-orphan-page-detection-industry-comparison.md
+ * for the industry comparison and design rationale this implements.
+ */
+export type DiscoveryMethod = 'ENTRY_POINT' | 'LINK_FOLLOW' | 'SEED_URL' | 'SKYVERN_AI';
+export type OrphanClassification = 'REACHABLE' | 'GRAPH_ORPHAN' | 'SITEMAP_ORPHAN' | 'UNVERIFIED_ORPHAN';
+/** Classifies a single screen given its discovery method and whether the KAG graph
+ *  has at least one inbound Element.transitionsToScreenId edge pointing to it. */
+export declare function classifyScreen(discoveryMethod: string, hasInboundEdge: boolean): OrphanClassification;
+export interface OrphanScreenResult {
+    id: string;
+    name: string;
+    url: string | null;
+    discoveryMethod: string;
+    classification: OrphanClassification;
+}
+export interface OrphanReport {
+    screens: OrphanScreenResult[];
+    totalScreens: number;
+    reachableCount: number;
+    orphanCount: number;
+    /** orphanCount / totalScreens as a percentage, 0 when there are no screens at all. */
+    orphanPercent: number;
+}
+/** Builds the full per-project orphan report from raw screen + inbound-edge data. */
+export declare function buildOrphanReport(screens: Array<{
+    id: string;
+    name: string;
+    url: string | null;
+    discoveryMethod: string;
+}>, screenIdsWithInboundEdge: Set<string>): OrphanReport;

package/dist/orphan-classification.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Orphan-page classification — pure logic, no I/O, so it's unit-testable in
+ * isolation. See docs/research/25-orphan-page-detection-industry-comparison.md
+ * for the industry comparison and design rationale this implements.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyScreen = classifyScreen;
+exports.buildOrphanReport = buildOrphanReport;
+// less trustworthy until KAG link-wiring covers that path too
+/** Classifies a single screen given its discovery method and whether the KAG graph
+ *  has at least one inbound Element.transitionsToScreenId edge pointing to it. */
+function classifyScreen(discoveryMethod, hasInboundEdge) {
+    if (discoveryMethod === 'ENTRY_POINT' || hasInboundEdge)
+        return 'REACHABLE';
+    if (discoveryMethod === 'SEED_URL')
+        return 'SITEMAP_ORPHAN';
+    if (discoveryMethod === 'SKYVERN_AI')
+        return 'UNVERIFIED_ORPHAN';
+    return 'GRAPH_ORPHAN';
+}
+/** Builds the full per-project orphan report from raw screen + inbound-edge data. */
+function buildOrphanReport(screens, screenIdsWithInboundEdge) {
+    const classified = screens.map((s) => ({
+        id: s.id,
+        name: s.name,
+        url: s.url,
+        discoveryMethod: s.discoveryMethod,
+        classification: classifyScreen(s.discoveryMethod, screenIdsWithInboundEdge.has(s.id)),
+    }));
+    const reachableCount = classified.filter((s) => s.classification === 'REACHABLE').length;
+    const orphanCount = classified.length - reachableCount;
+    return {
+        screens: classified,
+        totalScreens: classified.length,
+        reachableCount,
+        orphanCount,
+        orphanPercent: classified.length > 0 ? Math.round((orphanCount / classified.length) * 1000) / 10 : 0,
+    };
+}