@taodigital/agents 0.0.0-stage → 1.2.0

package/dist/github-write-agent.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * GitHub write operations — branch, commit, PR creation.
+ * Uses GitHub REST API v3 (no SDK dependency — just fetch).
+ * Works with PAT, fine-grained PAT, and GitHub App installation tokens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRefSha = getRefSha;
+exports.createBranch = createBranch;
+exports.branchExists = branchExists;
+exports.getFileContent = getFileContent;
+exports.mergeSpecContent = mergeSpecContent;
+exports.createCommitWithFiles = createCommitWithFiles;
+exports.updateBranchRef = updateBranchRef;
+exports.createPullRequest = createPullRequest;
+exports.pushScriptsAsPR = pushScriptsAsPR;
+exports.buildGitHubAppJWT = buildGitHubAppJWT;
+exports.getGitHubAppInstallationToken = getGitHubAppInstallationToken;
+exports.addPRComment = addPRComment;
+exports.verifyGitHubWebhookSignature = verifyGitHubWebhookSignature;
+const GITHUB_API_BASE = process.env.GITHUB_API_BASE_URL ?? 'https://api.github.com';
+function githubHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'Content-Type': 'application/json',
+    };
+}
+async function ghRequest(token, method, path, body) {
+    const res = await fetch(`${GITHUB_API_BASE}${path}`, {
+        method,
+        headers: githubHeaders(token),
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const txt = await res.text().catch(() => '');
+        throw new Error(`GitHub API ${method} ${path} → ${res.status}: ${txt.slice(0, 400)}`);
+    }
+    if (res.status === 204)
+        return undefined;
+    return res.json();
+}
+// ── Ref / branch ────────────────────────────────────────────────────────────
+async function getRefSha(token, repo, ref) {
+    const data = await ghRequest(token, 'GET', `/repos/${repo}/git/ref/heads/${ref}`);
+    return data.object.sha;
+}
+async function createBranch(token, repo, branchName, fromSha) {
+    await ghRequest(token, 'POST', `/repos/${repo}/git/refs`, {
+        ref: `refs/heads/${branchName}`,
+        sha: fromSha,
+    });
+}
+async function branchExists(token, repo, branchName) {
+    try {
+        await getRefSha(token, repo, branchName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Fetch the current content of a file from GitHub (from the default branch).
+ * Returns the decoded text content, or null if the file doesn't exist.
+ */
+async function getFileContent(token, repo, path, ref) {
+    try {
+        const query = ref ? `?ref=${encodeURIComponent(ref)}` : '';
+        const data = await ghRequest(token, 'GET', `/repos/${repo}/contents/${path}${query}`);
+        if (data.content && data.encoding === 'base64') {
+            return Buffer.from(data.content.replace(/\n/g, ''), 'base64').toString('utf-8');
+        }
+        return null;
+    }
+    catch {
+        return null; // file doesn't exist
+    }
+}
+/**
+ * Merge new spec content into existing spec content.
+ * Strategy: append new test() / it() / @Test blocks inside the outermost describe/class wrapper.
+ * If no wrapper found, append at end.
+ * Returns merged content.
+ */
+function mergeSpecContent(existing, incoming) {
+    // Extract test() / it() / scenario calls from incoming content
+    // Strip imports, describe wrappers — keep only the inner test blocks
+    const testBlockRe = /^\s*(test|it|scenario|@Test[^\n]*\n[^\n]*void\s+\w+)\s*[\(\(]/m;
+    if (!testBlockRe.test(incoming)) {
+        // Can't parse incoming — skip merge, use incoming as-is
+        return incoming;
+    }
+    // Find the closing brace of the outermost describe/class block in existing content
+    // Strategy: find the LAST }) or }); or } that closes the file-level block
+    const closingPatterns = [
+        /\}\s*\)\s*;?\s*$/, // JS: }); at end
+        /\}\s*$/, // Java/Python class closing brace at end
+    ];
+    // Extract raw test blocks from incoming (lines that are test/it calls + their bodies)
+    // Simple approach: strip describe wrapper if present
+    let innerContent = incoming;
+    const describeWrapRe = /^.*?(?:describe|test\.describe)\s*\([^)]*\)\s*,?\s*\(\s*\)\s*=>\s*\{([\s\S]*)\}\s*\)\s*;?\s*$/;
+    const describeMatch = innerContent.match(describeWrapRe);
+    if (describeMatch) {
+        innerContent = describeMatch[1];
+    }
+    // For Java: strip class declaration wrapper
+    const javaClassRe = /^[\s\S]*?class\s+\w+[^{]*\{([\s\S]*)\}\s*$/;
+    const javaMatch = innerContent.match(javaClassRe);
+    if (javaMatch) {
+        innerContent = javaMatch[1];
+    }
+    // Trim inner content
+    innerContent = innerContent.trim();
+    // Insert before the last closing } or }); of existing content
+    for (const re of closingPatterns) {
+        const m = existing.match(re);
+        if (m) {
+            const insertPoint = existing.lastIndexOf(m[0]);
+            if (insertPoint !== -1) {
+                return (existing.slice(0, insertPoint) +
+                    '\n\n  // --- ZeTa: appended ---\n' +
+                    innerContent.split('\n').map(l => '  ' + l).join('\n') +
+                    '\n\n' +
+                    existing.slice(insertPoint));
+            }
+        }
+    }
+    // Fallback: append at end
+    return existing + '\n\n// --- ZeTa: appended ---\n' + innerContent;
+}
+async function createCommitWithFiles(token, repo, baseSha, files, message) {
+    // Build tree entries — use base64 for content to handle any encoding
+    const treeEntries = files.map((f) => ({
+        path: f.path,
+        mode: '100644',
+        type: 'blob',
+        content: f.content,
+    }));
+    const tree = await ghRequest(token, 'POST', `/repos/${repo}/git/trees`, {
+        base_tree: baseSha,
+        tree: treeEntries,
+    });
+    const commit = await ghRequest(token, 'POST', `/repos/${repo}/git/commits`, {
+        message,
+        tree: tree.sha,
+        parents: [baseSha],
+    });
+    return { commitSha: commit.sha, treeSha: tree.sha };
+}
+async function updateBranchRef(token, repo, branchName, commitSha) {
+    await ghRequest(token, 'PATCH', `/repos/${repo}/git/refs/heads/${branchName}`, {
+        sha: commitSha,
+        force: false,
+    });
+}
+async function createPullRequest(opts) {
+    const pr = await ghRequest(opts.token, 'POST', `/repos/${opts.repo}/pulls`, {
+        title: opts.title,
+        body: opts.body,
+        head: opts.head,
+        base: opts.base,
+        draft: opts.draft ?? false,
+    });
+    return {
+        prNumber: pr.number,
+        prUrl: pr.html_url,
+        headSha: pr.head.sha,
+        branch: opts.head,
+    };
+}
+async function pushScriptsAsPR(opts) {
+    const baseSha = await getRefSha(opts.token, opts.repo, opts.baseBranch);
+    // If branch already exists, use it; otherwise create
+    const exists = await branchExists(opts.token, opts.repo, opts.branchName);
+    const { commitSha } = await createCommitWithFiles(opts.token, opts.repo, baseSha, opts.files, opts.prTitle);
+    if (exists) {
+        await updateBranchRef(opts.token, opts.repo, opts.branchName, commitSha);
+    }
+    else {
+        // Create branch pointing at new commit
+        await ghRequest(opts.token, 'POST', `/repos/${opts.repo}/git/refs`, {
+            ref: `refs/heads/${opts.branchName}`,
+            sha: commitSha,
+        });
+    }
+    return createPullRequest({
+        token: opts.token,
+        repo: opts.repo,
+        title: opts.prTitle,
+        body: opts.prBody,
+        head: opts.branchName,
+        base: opts.baseBranch,
+        draft: opts.draft,
+    });
+}
+// ── GitHub App JWT token generation ─────────────────────────────────────────
+/**
+ * Generate a short-lived JWT for GitHub App authentication.
+ * APP_ID and privateKeyPem come from env / DB. JWT expires in 10 min.
+ */
+function buildGitHubAppJWT(appId, privateKeyPem) {
+    const { createSign } = require('node:crypto');
+    const now = Math.floor(Date.now() / 1000);
+    const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify({ iat: now - 60, exp: now + 540, iss: appId })).toString('base64url');
+    const data = `${header}.${payload}`;
+    const sign = createSign('RSA-SHA256');
+    sign.update(data);
+    const sig = sign.sign(privateKeyPem, 'base64url');
+    return `${data}.${sig}`;
+}
+/**
+ * Exchange a GitHub App JWT for an installation access token (1-hour expiry).
+ */
+async function getGitHubAppInstallationToken(appId, privateKeyPem, installationId) {
+    const jwt = buildGitHubAppJWT(appId, privateKeyPem);
+    const res = await fetch(`${GITHUB_API_BASE}/app/installations/${installationId}/access_tokens`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+        },
+    });
+    if (!res.ok)
+        throw new Error(`GitHub App token exchange failed: ${res.status} ${await res.text()}`);
+    const data = await res.json();
+    return data.token;
+}
+// ── PR comment ───────────────────────────────────────────────────────────────
+async function addPRComment(token, repo, prNumber, body) {
+    await ghRequest(token, 'POST', `/repos/${repo}/issues/${prNumber}/comments`, { body });
+}
+// ── Verify GitHub webhook signature ─────────────────────────────────────────
+function verifyGitHubWebhookSignature(rawBody, signatureHeader, secret) {
+    const { createHmac, timingSafeEqual } = require('node:crypto');
+    const hmac = createHmac('sha256', secret);
+    hmac.update(rawBody);
+    const expected = `sha256=${hmac.digest('hex')}`;
+    try {
+        return timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/grouping-agent.d.ts

@@ -0,0 +1,18 @@
+interface ScreenInput {
+    id: string;
+    name: string;
+    url?: string | null;
+    elementCount?: number;
+    elements?: any[];
+}
+/**
+ * Post-crawl: groups screens into semantic areas and persists to DB.
+ *
+ * Incremental strategy (stable across recrawls):
+ *   - If groups already exist → only assign NEW unassigned screens using URL-pattern
+ *     matching. Existing assignments are preserved unchanged. Zero LLM cost.
+ *   - If no groups exist yet → run full AI grouping (first crawl only).
+ *   - Pass force=true to wipe and re-run AI grouping regardless (explicit user action).
+ */
+export declare function groupScreensWithAI(tenantId: string, projectId: string, screens: ScreenInput[], _jobId?: string, _jobStartedAt?: Date, force?: boolean): Promise<void>;
+export {};

package/dist/grouping-agent.js

@@ -0,0 +1,338 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupScreensWithAI = groupScreensWithAI;
+const app_brain_1 = require("@taodigital/app-brain");
+const llm_config_js_1 = require("./llm-config.js");
+const llm_js_1 = require("./llm.js");
+const core_1 = require("@taodigital/core");
+const GROUP_COLORS = [
+    '#6FD0E8', // cyan
+    '#4ADE80', // green
+    '#FBBF24', // amber
+    '#F87171', // coral
+    '#A78BFA', // violet
+    '#FB923C', // orange
+    '#38BDF8', // sky
+    '#34D399', // emerald
+];
+// URL pattern → candidate group slugs (first match wins, order matters).
+// Covers ecommerce, banking, fintech, healthcare, pharma, agriculture, saas,
+// legacy-enterprise, and generic SaaS patterns. Aligns with GICS/NAICS/ICB verticals.
+const URL_GROUP_RULES = [
+    // ── Auth (universal) ────────────────────────────────────────────────────
+    { pattern: /\/(login|register|sign-in|signup|sign-up|auth|forgot-password|reset-password|set-password|verify-email|two-factor|2fa|mfa|otp|sso|oauth)/i, slugs: ['authentication', 'auth', 'sign-in', 'login', 'access'] },
+    // ── Home / Landing ───────────────────────────────────────────────────────
+    { pattern: /^\/?(home\/?)?$/i, slugs: ['home-navigation', 'home', 'landing', 'dashboard'] },
+    // ── E-commerce: cart / checkout / orders ────────────────────────────────
+    { pattern: /\/(cart|basket|checkout|payment|order-confirm|order-received|thank-you|place-order|order-success)/i, slugs: ['cart-checkout', 'cart', 'checkout', 'orders'] },
+    { pattern: /\/(orders|my-orders|order-history|order-tracking|returns|return-request|refund-request|wishlist|saved-items)/i, slugs: ['user-account', 'orders', 'account'] },
+    { pattern: /\/(product\/|\/p\/|\/item\/|\/sku\/|\/dp\/)/i, slugs: ['product-details', 'products', 'product-catalog'] },
+    { pattern: /\/(shop|store|products|catalog|collection|category|product-category|browse|listing)/i, slugs: ['product-catalog', 'catalog', 'shop', 'products'] },
+    // ── Banking / Fintech: accounts, transactions, cards ────────────────────
+    { pattern: /\/(accounts|account-summary|my-account|account-detail|savings|current-account|fixed-deposit)/i, slugs: ['accounts', 'user-account', 'account', 'dashboard'] },
+    { pattern: /\/(transactions|transaction-history|ledger|statement|e-statement|passbook)/i, slugs: ['transactions', 'accounts', 'statements'] },
+    { pattern: /\/(transfer|fund-transfer|neft|rtgs|imps|wire|send-money|pay-now|beneficiar)/i, slugs: ['transfers', 'payments', 'accounts'] },
+    { pattern: /\/(cards|debit-card|credit-card|card-management|card-block|card-limit)/i, slugs: ['cards', 'accounts', 'payments'] },
+    { pattern: /\/(kyc|know-your-customer|aml|cdd|onboarding-kyc|identity-verification)/i, slugs: ['kyc-onboarding', 'onboarding', 'compliance'] },
+    { pattern: /\/(wallet|e-wallet|prepaid|balance|topup|load-money)/i, slugs: ['wallet', 'payments', 'accounts'] },
+    { pattern: /\/(loans|loan-application|emi|repayment|credit|lending|borrowing)/i, slugs: ['loans-credit', 'loans', 'accounts'] },
+    { pattern: /\/(invest|investment|portfolio|mutual-fund|stocks|trading|demat|brokerage)/i, slugs: ['investments', 'portfolio', 'accounts'] },
+    { pattern: /\/(dispute|chargeback|complaint|grievance)/i, slugs: ['disputes', 'support', 'compliance'] },
+    // ── Healthcare ───────────────────────────────────────────────────────────
+    { pattern: /\/(patient|patients|patient-lookup|patient-search|patient-profile)/i, slugs: ['patient-management', 'patients', 'records'] },
+    { pattern: /\/(appointment|appointments|schedule|booking|book-appointment|visit|consultation)/i, slugs: ['appointments', 'scheduling', 'patient-management'] },
+    { pattern: /\/(claims|claim|claim-submission|prior-auth|pre-authorization|insurance-claim)/i, slugs: ['claims', 'billing', 'compliance'] },
+    { pattern: /\/(prescription|prescriptions|rx|medication|drug-order|e-prescription)/i, slugs: ['prescriptions', 'clinical', 'patient-management'] },
+    { pattern: /\/(health-record|medical-record|ehr|emr|lab-result|lab-report|pathology|radiology|imaging)/i, slugs: ['health-records', 'records', 'clinical'] },
+    { pattern: /\/(provider|doctor|physician|specialist|nurse|care-team|referral)/i, slugs: ['providers', 'care-team', 'patient-management'] },
+    { pattern: /\/(consent|hipaa|phi|authorization|release-of-information)/i, slugs: ['consent-compliance', 'compliance', 'policies-legal'] },
+    { pattern: /\/(telemedicine|telehealth|video-consult|virtual-visit)/i, slugs: ['telemedicine', 'appointments', 'clinical'] },
+    // ── Pharma ───────────────────────────────────────────────────────────────
+    { pattern: /\/(adverse-event|pharmacovigilance|safety-report|adr|side-effect|signal)/i, slugs: ['pharmacovigilance', 'safety', 'compliance'] },
+    { pattern: /\/(regulatory|submission|dossier|ectd|label|labeling|spc|pil)/i, slugs: ['regulatory-affairs', 'regulatory', 'compliance'] },
+    { pattern: /\/(batch|lot|manufacturing|gmp|quality-control|deviation|capa|audit-trail)/i, slugs: ['manufacturing-quality', 'batch', 'quality'] },
+    { pattern: /\/(clinical-trial|trial|protocol|investigator|site-management|ctms)/i, slugs: ['clinical-trials', 'research', 'clinical'] },
+    // ── Agriculture ──────────────────────────────────────────────────────────
+    { pattern: /\/(crop|field|farm|plot|season|sowing|harvest|yield|pest|disease)/i, slugs: ['farm-management', 'crops', 'farming'] },
+    { pattern: /\/(sensor|iot|weather|soil|irrigation|telemetry|device|alert)/i, slugs: ['sensors-iot', 'monitoring', 'farm-management'] },
+    { pattern: /\/(agri-market|mandi|commodity|price|trade|agriculture-marketplace)/i, slugs: ['agricultural-marketplace', 'marketplace', 'trading'] },
+    { pattern: /\/(subsidy|scheme|government-scheme|kisan|agri-loan|input)/i, slugs: ['subsidies-schemes', 'government', 'support'] },
+    { pattern: /\/(livestock|poultry|dairy|animal-health|veterinary)/i, slugs: ['livestock', 'farm-management', 'farming'] },
+    // ── SaaS / Enterprise ────────────────────────────────────────────────────
+    { pattern: /\/(workspace|organization|org|tenant|instance|environment)/i, slugs: ['workspace', 'settings', 'admin'] },
+    { pattern: /\/(billing|subscription|plan|pricing|invoices|payment-method|upgrade)/i, slugs: ['billing', 'subscription', 'settings'] },
+    { pattern: /\/(integrations|integration|connect|webhooks|api-keys|tokens|oauth-apps)/i, slugs: ['integrations', 'settings', 'admin'] },
+    { pattern: /\/(team|members|users|roles|permissions|access-control|rbac|groups)/i, slugs: ['team-management', 'users', 'admin'] },
+    { pattern: /\/(analytics|metrics|usage|reports|insights|dashboards)/i, slugs: ['analytics-reports', 'analytics', 'dashboard'] },
+    { pattern: /\/(audit-log|activity|history|changelog)/i, slugs: ['audit-logs', 'admin', 'compliance'] },
+    // ── Legacy enterprise ────────────────────────────────────────────────────
+    { pattern: /\/(erp|crm|hris|hrms|payroll|procurement|inventory-mgmt|supply-chain|wms)/i, slugs: ['enterprise-modules', 'admin', 'dashboard'] },
+    { pattern: /\/(report|reports|export|download|print|batch-report)/i, slugs: ['reports', 'analytics-reports', 'dashboard'] },
+    // ── Generic / cross-vertical ─────────────────────────────────────────────
+    { pattern: /\/(profile|my-profile|account-settings|user-settings|preferences|notifications-settings)/i, slugs: ['user-account', 'account', 'profile', 'settings'] },
+    { pattern: /\/(terms|privacy|refund|return|shipping-policy|legal|cookie|disclaimer|policies|gdpr|ccpa)/i, slugs: ['policies-legal', 'legal', 'policies', 'compliance'] },
+    { pattern: /\/(about|our-story|mission|team|careers|blog|news|press|media)/i, slugs: ['company-info', 'about', 'company'] },
+    { pattern: /\/(contact|faq|help|support|customer-service|helpdesk|ticket|raise-ticket)/i, slugs: ['faqs-support', 'support', 'faq', 'help'] },
+    { pattern: /\/(search|find|explore|discover)/i, slugs: ['search-filter', 'search', 'explore'] },
+    { pattern: /\/(admin|cms|manage|management|back-office|backoffice|ops)/i, slugs: ['admin', 'back-office', 'management'] },
+    { pattern: /\/(notification|notifications|inbox|alerts|messages)/i, slugs: ['notifications', 'user-account', 'inbox'] },
+    { pattern: /\/(onboarding|getting-started|setup|wizard|tour)/i, slugs: ['onboarding', 'kyc-onboarding', 'settings'] },
+];
+/**
+ * Assign a single screen to the best-fit existing group by URL-pattern matching.
+ * Falls back to the largest group if no pattern matches.
+ * Returns null if no groups exist at all.
+ */
+function pickBestGroup(url, existingGroups) {
+    if (existingGroups.length === 0)
+        return null;
+    const path = (() => { try {
+        return new URL(url ?? '').pathname;
+    }
+    catch {
+        return url ?? '';
+    } })();
+    for (const rule of URL_GROUP_RULES) {
+        if (rule.pattern.test(path)) {
+            for (const candidateSlug of rule.slugs) {
+                const match = existingGroups.find(g => g.slug === candidateSlug || g.slug.includes(candidateSlug) || candidateSlug.includes(g.slug));
+                if (match)
+                    return match.id;
+            }
+        }
+    }
+    // No URL pattern matched — assign to the group with the most screens (catch-all)
+    return existingGroups.reduce((best, g) => g.screens.length > best.screens.length ? g : best, existingGroups[0]).id;
+}
+const SYSTEM = `You are an expert UX architect who groups app screens into logical feature areas.
+Given a list of screens (name + URL + element hints), produce 3-8 semantic groups that represent distinct product domains or user journeys.
+Detect the app's industry vertical from the URLs and screen names, then apply the matching classification rules below.
+
+Rules:
+- Every screen must be assigned to exactly one group
+- Group names are short (2-3 words max)
+- slug: lowercase-hyphenated version of name
+- icon: single emoji that represents the group
+
+═══ UNIVERSAL (all verticals) ════════════════════════════════════════════════
+- /login /register /sign-in /signup /auth/* /forgot-password /reset-password /2fa /mfa /sso → "Authentication" 🔐
+- / /home (root path) → "Home & Navigation" 🏠
+- /search* /find* /explore* → "Search & Filter" 🔍
+- /admin* /cms* /manage* /back-office* → "Admin" ⚙️
+- /terms* /privacy* /legal* /cookie* /gdpr* /policies* → "Policies & Legal" 📋
+- /about* /team* /careers* /blog* /news* → "Company & Info" ℹ️
+- /contact* /faq* /help* /support* /ticket* → "FAQs & Support" ❓
+- /profile* /account-settings* /preferences* /notifications-settings* → "User Account" 👤
+- /notifications* /inbox* /alerts* → "Notifications" 🔔
+- /onboarding* /getting-started* /setup* /wizard* → "Onboarding" 🚀
+- /audit-log* /activity* /changelog* → "Audit Logs" 📜
+
+═══ E-COMMERCE ════════════════════════════════════════════════════════════════
+- /cart* /basket* /checkout* /payment* /order-confirm* /thank-you* → "Cart & Checkout" 🛒
+- /orders* /my-orders* /order-history* /returns* /refund-request* /wishlist* → "Orders & Returns" 📦
+- /product/* /p/* /item/* /sku/* /dp/* → "Product Details" 🛍️
+- /shop* /store* /catalog* /collection* /category* /product-category* /listing* → "Product Catalog" 📦
+
+═══ BANKING / FINTECH ═════════════════════════════════════════════════════════
+- /accounts* /account-summary* /savings* /current-account* /fixed-deposit* → "Accounts" 🏦
+- /transactions* /transaction-history* /ledger* /statement* /passbook* → "Transactions" 💳
+- /transfer* /fund-transfer* /neft* /rtgs* /send-money* /beneficiar* → "Transfers & Payments" 💸
+- /cards* /debit-card* /credit-card* /card-management* → "Cards" 💳
+- /kyc* /identity-verification* /onboarding-kyc* /aml* → "KYC & Onboarding" 🪪
+- /wallet* /e-wallet* /prepaid* /topup* → "Wallet" 👛
+- /loans* /loan-application* /emi* /repayment* /credit* → "Loans & Credit" 📊
+- /invest* /portfolio* /mutual-fund* /stocks* /trading* → "Investments" 📈
+- /dispute* /chargeback* /complaint* → "Disputes" ⚠️
+
+═══ HEALTHCARE ═════════════════════════════════════════════════════════════════
+- /patient* /patients/* /patient-lookup* → "Patient Management" 🏥
+- /appointment* /schedule* /booking* /book-appointment* /consultation* → "Appointments" 📅
+- /claims* /claim-submission* /prior-auth* /insurance-claim* → "Claims & Billing" 🧾
+- /prescription* /rx/* /medication* /drug-order* → "Prescriptions" 💊
+- /health-record* /medical-record* /ehr* /emr* /lab-result* /imaging* → "Health Records" 📋
+- /provider* /doctor* /physician* /specialist* /care-team* → "Providers" 👩‍⚕️
+- /consent* /hipaa* /phi* /release-of-information* → "Consent & Compliance" 🔒
+- /telemedicine* /telehealth* /video-consult* /virtual-visit* → "Telemedicine" 📹
+
+═══ PHARMA ═════════════════════════════════════════════════════════════════════
+- /adverse-event* /pharmacovigilance* /safety-report* /adr* → "Pharmacovigilance" ⚕️
+- /regulatory* /submission* /dossier* /ectd* /label* /spc* → "Regulatory Affairs" 📑
+- /batch* /lot* /manufacturing* /gmp* /quality-control* /capa* → "Manufacturing & Quality" 🔬
+- /clinical-trial* /trial* /protocol* /investigator* /ctms* → "Clinical Trials" 🧪
+
+═══ AGRICULTURE ════════════════════════════════════════════════════════════════
+- /crop* /field* /farm* /plot* /harvest* /yield* /pest* → "Farm Management" 🌾
+- /sensor* /iot* /weather* /soil* /irrigation* /telemetry* → "Sensors & IoT" 📡
+- /agri-market* /mandi* /commodity* /agriculture-marketplace* → "Agricultural Marketplace" 🏪
+- /subsidy* /scheme* /government-scheme* /kisan* → "Subsidies & Schemes" 🏛️
+- /livestock* /poultry* /dairy* /animal-health* → "Livestock" 🐄
+
+═══ SAAS / ENTERPRISE ══════════════════════════════════════════════════════════
+- /workspace* /organization* /org* /tenant* → "Workspace" 🏢
+- /billing* /subscription* /plan* /invoices* /upgrade* → "Billing & Plans" 💰
+- /integrations* /integration/* /webhooks* /api-keys* → "Integrations" 🔗
+- /team* /members* /users* /roles* /permissions* /rbac* → "Team Management" 👥
+- /analytics* /metrics* /usage* /reports* /insights* → "Analytics & Reports" 📊
+- /erp* /crm* /hris* /payroll* /procurement* /supply-chain* → "Enterprise Modules" 🗄️
+
+Element-hint overrides (when URL pattern is ambiguous):
+- hasCheckoutForm=true → "Cart & Checkout"
+- hasPriceTag=true AND hasAddToCart=true → "Product Details"
+- hasProductGrid=true → "Product Catalog"
+- hasAuthForm=true → "Authentication"
+- hasPatientForm=true → "Patient Management"
+- hasLabResult=true → "Health Records"
+
+Critical rules:
+- Legal/policy pages NEVER belong to "User Account" — always "Policies & Legal"
+- The site root ("/") always belongs to "Home & Navigation"
+- Product listing pages → "Product Catalog", NOT "Cart & Checkout"
+- Banking account pages → "Accounts", NOT "User Account"
+- Healthcare patient pages → "Patient Management", NOT "User Account"
+- If a group would have only 1 screen AND a semantically close group exists, merge them
+- NEVER create a group named "Other", "Miscellaneous", "Misc", "General", or "Uncategorized" — assign those screens to the closest matching group
+- Group names must NOT start with "@", "#", or any special character — use plain words only (e.g. "Workspace" not "@Workspace")
+- Return ONLY valid JSON, no markdown fences`;
+/**
+ * Post-crawl: groups screens into semantic areas and persists to DB.
+ *
+ * Incremental strategy (stable across recrawls):
+ *   - If groups already exist → only assign NEW unassigned screens using URL-pattern
+ *     matching. Existing assignments are preserved unchanged. Zero LLM cost.
+ *   - If no groups exist yet → run full AI grouping (first crawl only).
+ *   - Pass force=true to wipe and re-run AI grouping regardless (explicit user action).
+ */
+async function groupScreensWithAI(tenantId, projectId, screens, _jobId, _jobStartedAt, force = false) {
+    if (screens.length === 0)
+        return;
+    const existingGroups = await app_brain_1.AppBrain.getScreenGroups(tenantId, projectId).catch(() => []);
+    // ── Incremental path: groups exist and force-regroup not requested ────────────
+    if (existingGroups.length > 0 && !force) {
+        const assignedIds = new Set(existingGroups.flatMap(g => g.screens.map(s => s.id)));
+        const unassigned = screens.filter(s => !assignedIds.has(s.id));
+        if (unassigned.length === 0) {
+            console.log(`[grouping-agent] all ${screens.length} screens already grouped — skipping`);
+            return;
+        }
+        console.log(`[grouping-agent] incremental: assigning ${unassigned.length} new screen(s) to existing groups`);
+        for (const screen of unassigned) {
+            const groupId = pickBestGroup(screen.url, existingGroups);
+            if (groupId) {
+                await app_brain_1.AppBrain.assignScreensToGroup(tenantId, [screen.id], groupId).catch(() => { });
+            }
+        }
+        return;
+    }
+    // ── Full AI grouping path: first crawl or force=true ─────────────────────────
+    const llmCfg = await (0, llm_config_js_1.getTaskAgentLLMConfig)(tenantId, 'screenNaming');
+    if (!llmCfg) {
+        console.warn('[grouping-agent] No AI provider configured — skipping screen grouping. Configure one in Workspace → Settings → AI Provider.');
+        return;
+    }
+    function getElementHints(screen) {
+        const els = screen.elements ?? [];
+        const texts = els.map((e) => (e.text ?? e.label ?? '').toLowerCase());
+        const hasAddToCart = texts.some((t) => t.includes('add to cart') || t.includes('add to bag'));
+        const hasPriceTag = els.some((e) => e.type === 'price' || /₹|\$|€|£/.test(e.text ?? ''));
+        const hasProductGrid = els.filter((e) => e.type === 'product-card' || e.type === 'image').length > 4;
+        const hasCheckoutForm = texts.some((t) => t.includes('place order') || t.includes('proceed to checkout') || t.includes('payment'));
+        const hasAuthForm = texts.some((t) => t.includes('sign in') || t.includes('log in') || t.includes('create account'));
+        const hints = [];
+        if (hasAddToCart)
+            hints.push('hasAddToCart=true');
+        if (hasPriceTag)
+            hints.push('hasPriceTag=true');
+        if (hasProductGrid)
+            hints.push('hasProductGrid=true');
+        if (hasCheckoutForm)
+            hints.push('hasCheckoutForm=true');
+        if (hasAuthForm)
+            hints.push('hasAuthForm=true');
+        return hints.length ? ` [${hints.join(', ')}]` : '';
+    }
+    const screenList = screens
+        .map((s) => `${s.id}: ${s.name} | ${s.url ?? ''}${getElementHints(s)}`)
+        .join('\n');
+    const user = `Group these ${screens.length} screens into 3-8 semantic feature areas.
+
+${screenList}
+
+Return JSON exactly like this (no other text):
+{
+  "groups": [
+    {
+      "name": "Authentication",
+      "slug": "authentication",
+      "icon": "🔐",
+      "description": "Login, registration, password flows",
+      "screenIds": ["clxxx1abc", "clxxx2def"]
+    }
+  ]
+}`;
+    try {
+        const seed = (0, llm_js_1.deterministicSeed)(`${tenantId}:group-screens:${screens.map((s) => s.id).sort().join('|').slice(0, 500)}`);
+        const effectiveSystem = await (0, core_1.getAgentPrompt)('screen-grouping', undefined, tenantId) ?? SYSTEM;
+        const result = await (0, llm_js_1.askTracked)(effectiveSystem, user, llmCfg, 4096, undefined, { temperature: 0, seed });
+        const text = result.text.trim();
+        const jsonStart = text.indexOf('{');
+        const jsonEnd = text.lastIndexOf('}');
+        if (jsonStart === -1 || jsonEnd === -1) {
+            console.error('[grouping-agent] LLM did not return valid JSON');
+            return;
+        }
+        const parsed = JSON.parse(text.slice(jsonStart, jsonEnd + 1));
+        if (!Array.isArray(parsed.groups))
+            return;
+        // Normalize group names: strip leading special chars (@, #, etc.) that the LLM
+        // sometimes adds, and drop "Other" catch-all groups by merging into the first group.
+        const normalizeGroupName = (name) => name.replace(/^[@#!]+/, '').trim();
+        const OTHER_NAMES = new Set(['other', 'miscellaneous', 'misc', 'general', 'uncategorized', 'unknown']);
+        // Merge duplicates: same normalized slug → combine screenIds into first occurrence
+        const seenSlugs = new Map();
+        const deduped = [];
+        for (const g of parsed.groups) {
+            g.name = normalizeGroupName(g.name);
+            g.slug = g.name.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+            if (OTHER_NAMES.has(g.slug)) {
+                // Re-assign "Other" screens to the first non-Other group (or last deduped group)
+                const target = deduped[0];
+                if (target) {
+                    target.screenIds = [...(target.screenIds ?? []), ...(g.screenIds ?? [])];
+                }
+                continue;
+            }
+            const existing = seenSlugs.get(g.slug);
+            if (existing) {
+                existing.screenIds = [...(existing.screenIds ?? []), ...(g.screenIds ?? [])];
+            }
+            else {
+                seenSlugs.set(g.slug, g);
+                deduped.push(g);
+            }
+        }
+        if (deduped.length === 0)
+            return;
+        // Wipe old groups only right before saving new ones (atomic as possible)
+        await app_brain_1.AppBrain.clearScreenGroups(tenantId, projectId);
+        for (let i = 0; i < deduped.length; i++) {
+            const g = deduped[i];
+            const color = GROUP_COLORS[i % GROUP_COLORS.length];
+            const group = await app_brain_1.AppBrain.saveScreenGroup(tenantId, projectId, {
+                name: g.name,
+                slug: g.slug || g.name.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+                icon: g.icon || '◈',
+                color,
+                description: g.description,
+                order: i,
+                crawlJobId: _jobId,
+            });
+            if (Array.isArray(g.screenIds) && g.screenIds.length > 0) {
+                await app_brain_1.AppBrain.assignScreensToGroup(tenantId, g.screenIds, group.id);
+            }
+        }
+        console.log(`[grouping-agent] ${force ? 'force-regrouped' : 'created'} ${parsed.groups.length} groups for project ${projectId}`);
+    }
+    catch (err) {
+        console.error('[grouping-agent] grouping failed:', err);
+    }
+}