@taodigital/agents 0.0.0-stage → 1.2.1

package/dist/document-agent.d.ts

@@ -0,0 +1,10 @@
+import { type LLMConfig } from './llm.js';
+/**
+ * Parses content from Jira/Confluence/Markdown using heuristics
+ * and extracts testing constraints, user stories, and acceptance criteria.
+ */
+export declare function parseDocumentGrounding(content: string, sourceType: 'JIRA' | 'CONFLUENCE' | 'MARKDOWN', llmCfg?: LLMConfig): Promise<{
+    acceptanceCriteria: string[];
+    businessRules: string[];
+    outOfScope: string[];
+}>;

package/dist/document-agent.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDocumentGrounding = parseDocumentGrounding;
+const core_1 = require("@taodigital/core");
+const llm_js_1 = require("./llm.js");
+/**
+ * Parses content from Jira/Confluence/Markdown using heuristics
+ * and extracts testing constraints, user stories, and acceptance criteria.
+ */
+async function parseDocumentGrounding(content, sourceType, llmCfg) {
+    const SYSTEM_DEFAULT = [
+        'You are a QA Requirements Analyst.',
+        'Extract structured testing intelligence from the provided document.',
+        'Identify:',
+        '1. Acceptance Criteria (explicit requirements for test cases)',
+        '2. Business Rules (implicit constraints, e.g., "users under 18 cannot register")',
+        '3. Out of Scope (things explicitly excluded from testing)',
+        'Return valid JSON: { "acceptanceCriteria": string[], "businessRules": string[], "outOfScope": string[] }'
+    ].join('\n');
+    const system = await (0, core_1.getAgentPrompt)('document-grounding') ?? SYSTEM_DEFAULT;
+    const user = `Source Type: ${sourceType}\n\nDocument Content:\n${content.slice(0, 15000)}`;
+    try {
+        const seed = (0, llm_js_1.deterministicSeed)(`doc-grounding:${sourceType}:${content.slice(0, 2000)}`);
+        const { text: raw } = await (0, llm_js_1.askTracked)(system, user, llmCfg, undefined, undefined, { temperature: 0, seed });
+        const cleaned = raw.replace(/^```[\w-]*\n?/m, '').replace(/\n?```$/m, '').trim();
+        return JSON.parse(cleaned);
+    }
+    catch (err) {
+        console.error('[document-agent] Failed to parse document grounding', err);
+        return { acceptanceCriteria: [], businessRules: [], outOfScope: [] };
+    }
+}

package/dist/enhancement-agent.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ZeTa-AI Context Enhancement Agent
+ *
+ * Extracts UI elements from screenshots and Figma components, diffs them
+ * against existing test cases, and proposes/applies enrichment changes.
+ *
+ * Five public entry points:
+ *   analyzeScreenshotForEnhancement   — vision LLM → ExtractedElementInput[]
+ *   diffScreenshotElementsAgainstTestCases — diff → ProposedChange[]
+ *   analyzeFigmaComponentsForEnhancement  — Figma diff → ProposedChange[]
+ *   applyEnhancement                  — write approved changes to DB
+ *   updateProjectContextSources       — recompute contextScore / contextPhase
+ */
+export interface ExtractedElementInput {
+    name?: string;
+    role?: string;
+    selector: string;
+    confidence: number;
+    boundingBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    extractedFrom: 'SCREENSHOT' | 'FIGMA_COMPONENT' | 'DOM';
+}
+export interface ProposedChange {
+    testCaseId: string;
+    changeType: 'ADD_LOCATOR' | 'UPDATE_LOCATOR' | 'ADD_STEP' | 'MODIFY_STEP' | 'ADD_SCENARIO' | 'ADD_TEST_DATA';
+    before: string;
+    after: string;
+    confidence: number;
+    description: string;
+}
+export interface ContextEnhancementPayload {
+    proposedChanges: ProposedChange[];
+    extractedElements: ExtractedElementInput[];
+    summary: string;
+}
+export declare function analyzeScreenshotForEnhancement(tenantId: string, projectId: string, artifactId: string, imageBase64: string): Promise<{
+    elements: ExtractedElementInput[];
+    testDataValues: Record<string, string>;
+    navigationClues: string[];
+}>;
+export declare function diffScreenshotElementsAgainstTestCases(tenantId: string, projectId: string, extractedElements: ExtractedElementInput[], testCases: any[]): Promise<ContextEnhancementPayload>;
+export declare function analyzeFigmaComponentsForEnhancement(tenantId: string, projectId: string, figmaComponents: any[], testCases: any[]): Promise<ContextEnhancementPayload>;
+export declare function applyEnhancement(tenantId: string, enhancementId: string, approvedChangeIndexes?: number[]): Promise<void>;
+export declare function updateProjectContextSources(tenantId: string, projectId: string, sourceType?: 'SCREENSHOT' | 'FIGMA' | 'CRAWL' | 'API_SPEC', payload?: Record<string, unknown>): Promise<void>;

package/dist/enhancement-agent.js

@@ -0,0 +1,342 @@
+"use strict";
+/**
+ * ZeTa-AI Context Enhancement Agent
+ *
+ * Extracts UI elements from screenshots and Figma components, diffs them
+ * against existing test cases, and proposes/applies enrichment changes.
+ *
+ * Five public entry points:
+ *   analyzeScreenshotForEnhancement   — vision LLM → ExtractedElementInput[]
+ *   diffScreenshotElementsAgainstTestCases — diff → ProposedChange[]
+ *   analyzeFigmaComponentsForEnhancement  — Figma diff → ProposedChange[]
+ *   applyEnhancement                  — write approved changes to DB
+ *   updateProjectContextSources       — recompute contextScore / contextPhase
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeScreenshotForEnhancement = analyzeScreenshotForEnhancement;
+exports.diffScreenshotElementsAgainstTestCases = diffScreenshotElementsAgainstTestCases;
+exports.analyzeFigmaComponentsForEnhancement = analyzeFigmaComponentsForEnhancement;
+exports.applyEnhancement = applyEnhancement;
+exports.updateProjectContextSources = updateProjectContextSources;
+const database_1 = require("@taodigital/database");
+const core_1 = require("@taodigital/core");
+const llm_js_1 = require("./llm.js");
+// ─── Phase ordering (used by updateProjectContextSources) ─────────────────────
+const PHASE_ORDER = [
+    'PENDING_CONTEXT',
+    'CONTEXT_PARTIAL',
+    'CONTEXT_ENRICHED',
+    'DIFF_PENDING_APPROVAL',
+    'ALL_DIFFS_APPROVED',
+    'READY_FOR_SCRIPT_GEN',
+];
+// ─── 1. analyzeScreenshotForEnhancement ──────────────────────────────────────
+async function analyzeScreenshotForEnhancement(tenantId, projectId, artifactId, imageBase64) {
+    const empty = { elements: [], testDataValues: {}, navigationClues: [] };
+    if (!imageBase64)
+        return empty;
+    const promptText = await (0, core_1.getAgentPrompt)('screenshot-enhance-extract').catch(() => 'Extract all interactive UI elements from this screenshot as JSON: { elements: [{name, role, selector, confidence, boundingBox, extractedFrom: "SCREENSHOT"}], testDataValues: {}, navigationClues: [] }');
+    let rawText;
+    try {
+        const result = await (0, llm_js_1.askTrackedWithImages)(promptText ?? 'Extract all interactive UI elements from this screenshot as JSON: { elements: [], testDataValues: {}, navigationClues: [] }', 'Analyze this screenshot and return the JSON.', [{ base64: imageBase64, mediaType: 'image/png' }]);
+        rawText = result.text;
+    }
+    catch {
+        return empty;
+    }
+    try {
+        const parsed = JSON.parse(rawText);
+        return {
+            elements: (parsed.elements ?? []),
+            testDataValues: (parsed.testDataValues ?? {}),
+            navigationClues: (parsed.navigationClues ?? []),
+        };
+    }
+    catch {
+        return empty;
+    }
+}
+// ─── 2. diffScreenshotElementsAgainstTestCases ────────────────────────────────
+async function diffScreenshotElementsAgainstTestCases(tenantId, projectId, extractedElements, testCases) {
+    const proposedChanges = [];
+    for (const element of extractedElements) {
+        if (element.confidence <= 0.6)
+            continue;
+        const elementLabel = element.name ?? element.role ?? '';
+        // Find a test case whose steps mention this element
+        const matchedTestCase = testCases.find((tc) => {
+            const steps = Array.isArray(tc.steps) ? tc.steps : [];
+            return steps.some((s) => {
+                const text = typeof s === 'string' ? s : (s?.text ?? s?.description ?? '');
+                return ((elementLabel && text.toLowerCase().includes(elementLabel.toLowerCase())) ||
+                    (element.role && text.toLowerCase().includes(element.role.toLowerCase())));
+            });
+        });
+        if (matchedTestCase) {
+            const locatorsJson = (matchedTestCase.locatorsJson ?? {});
+            const alreadyPresent = Object.values(locatorsJson).some((v) => {
+                if (typeof v === 'string')
+                    return v === element.selector;
+                if (typeof v === 'object' && v !== null) {
+                    return v.selector === element.selector;
+                }
+                return false;
+            });
+            if (!alreadyPresent) {
+                proposedChanges.push({
+                    testCaseId: matchedTestCase.id,
+                    changeType: 'ADD_LOCATOR',
+                    before: '',
+                    after: JSON.stringify({ [element.selector]: element }),
+                    confidence: element.confidence,
+                    description: `Add locator for element "${elementLabel}" (${element.selector}) extracted from screenshot`,
+                });
+            }
+        }
+        else if (element.confidence > 0.8 && testCases.length > 0) {
+            // High-confidence element not referenced anywhere — propose a new scenario
+            const anchorTestCase = testCases[0];
+            proposedChanges.push({
+                testCaseId: anchorTestCase.id,
+                changeType: 'ADD_SCENARIO',
+                before: '',
+                after: JSON.stringify({
+                    title: `Verify interaction with "${elementLabel}" element`,
+                    locator: element.selector,
+                    extractedFrom: element.extractedFrom,
+                }),
+                confidence: element.confidence,
+                description: `No existing test references "${elementLabel}" (confidence ${element.confidence.toFixed(2)}) — propose new scenario`,
+            });
+        }
+    }
+    return {
+        proposedChanges,
+        extractedElements,
+        summary: `Found ${extractedElements.length} elements, ${proposedChanges.length} proposed changes`,
+    };
+}
+// ─── 3. analyzeFigmaComponentsForEnhancement ─────────────────────────────────
+async function analyzeFigmaComponentsForEnhancement(tenantId, projectId, figmaComponents, testCases) {
+    const proposedChanges = [];
+    for (const component of figmaComponents) {
+        const componentName = component.name ?? '';
+        if (component.suggestedLocator) {
+            // Look for test cases whose steps mention this component
+            const matchedTestCase = testCases.find((tc) => {
+                const steps = Array.isArray(tc.steps) ? tc.steps : [];
+                return steps.some((s) => {
+                    const text = typeof s === 'string' ? s : (s?.text ?? s?.description ?? '');
+                    return componentName && text.toLowerCase().includes(componentName.toLowerCase());
+                });
+            });
+            if (matchedTestCase) {
+                const locatorsJson = (matchedTestCase.locatorsJson ?? {});
+                const existing = locatorsJson[componentName];
+                const existingStr = existing !== undefined ? (typeof existing === 'string' ? existing : JSON.stringify(existing)) : null;
+                const suggestedStr = typeof component.suggestedLocator === 'string'
+                    ? component.suggestedLocator
+                    : JSON.stringify(component.suggestedLocator);
+                if (existingStr !== suggestedStr) {
+                    proposedChanges.push({
+                        testCaseId: matchedTestCase.id,
+                        changeType: 'UPDATE_LOCATOR',
+                        before: existingStr ?? '',
+                        after: suggestedStr,
+                        confidence: component.confidence ?? 0.9,
+                        description: `Update locator for Figma component "${componentName}"`,
+                    });
+                }
+            }
+        }
+        if (component.suggestedTestId) {
+            const testIdPattern = `getByTestId(${component.suggestedTestId})`;
+            const alreadyReferenced = testCases.some((tc) => {
+                const steps = Array.isArray(tc.steps) ? tc.steps : [];
+                return steps.some((s) => {
+                    const text = typeof s === 'string' ? s : (s?.text ?? s?.description ?? '');
+                    return text.includes(testIdPattern);
+                });
+            });
+            if (!alreadyReferenced) {
+                const anchorTestCase = testCases.find((tc) => {
+                    const steps = Array.isArray(tc.steps) ? tc.steps : [];
+                    return steps.some((s) => {
+                        const text = typeof s === 'string' ? s : (s?.text ?? s?.description ?? '');
+                        return componentName && text.toLowerCase().includes(componentName.toLowerCase());
+                    });
+                }) ?? testCases[0];
+                if (anchorTestCase) {
+                    proposedChanges.push({
+                        testCaseId: anchorTestCase.id,
+                        changeType: 'ADD_LOCATOR',
+                        before: '',
+                        after: JSON.stringify({
+                            [`[data-testid="${component.suggestedTestId}"]`]: {
+                                selector: `[data-testid="${component.suggestedTestId}"]`,
+                                name: componentName,
+                                extractedFrom: 'FIGMA_COMPONENT',
+                            },
+                        }),
+                        confidence: component.confidence ?? 0.85,
+                        description: `Add data-testid locator for Figma component "${componentName}"`,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        proposedChanges,
+        extractedElements: [],
+        summary: `Analyzed ${figmaComponents.length} Figma components, ${proposedChanges.length} proposed changes`,
+    };
+}
+// ─── 4. applyEnhancement ─────────────────────────────────────────────────────
+async function applyEnhancement(tenantId, enhancementId, approvedChangeIndexes) {
+    const record = await database_1.prismaAdmin.contextEnhancement.findUniqueOrThrow({
+        where: { id: enhancementId },
+    });
+    const changes = record.proposedChanges ?? [];
+    const toApply = approvedChangeIndexes !== undefined
+        ? changes.filter((_, i) => approvedChangeIndexes.includes(i))
+        : changes;
+    for (const change of toApply) {
+        switch (change.changeType) {
+            case 'ADD_LOCATOR':
+            case 'UPDATE_LOCATOR': {
+                const testCase = await database_1.prismaAdmin.testCase.findUniqueOrThrow({
+                    where: { id: change.testCaseId },
+                });
+                const locatorsJson = { ...testCase.locatorsJson };
+                const incoming = JSON.parse(change.after);
+                Object.assign(locatorsJson, incoming);
+                await database_1.prismaAdmin.testCase.update({
+                    where: { id: change.testCaseId },
+                    data: { locatorsJson: locatorsJson },
+                });
+                break;
+            }
+            case 'ADD_STEP': {
+                const testCase = await database_1.prismaAdmin.testCase.findUniqueOrThrow({
+                    where: { id: change.testCaseId },
+                });
+                const steps = Array.isArray(testCase.steps) ? [...testCase.steps] : [];
+                steps.push(JSON.parse(change.after));
+                await database_1.prismaAdmin.testCase.update({
+                    where: { id: change.testCaseId },
+                    data: { steps },
+                });
+                break;
+            }
+            case 'MODIFY_STEP': {
+                const testCase = await database_1.prismaAdmin.testCase.findUniqueOrThrow({
+                    where: { id: change.testCaseId },
+                });
+                const steps = Array.isArray(testCase.steps) ? [...testCase.steps] : [];
+                const beforeStep = JSON.parse(change.before);
+                const afterStep = JSON.parse(change.after);
+                const idx = steps.findIndex((s) => JSON.stringify(s) === JSON.stringify(beforeStep));
+                if (idx !== -1)
+                    steps[idx] = afterStep;
+                await database_1.prismaAdmin.testCase.update({
+                    where: { id: change.testCaseId },
+                    data: { steps },
+                });
+                break;
+            }
+            case 'ADD_SCENARIO': {
+                const afterPayload = JSON.parse(change.after);
+                await database_1.prismaAdmin.testCase.create({
+                    data: {
+                        tenantId: record.tenantId,
+                        projectId: record.projectId,
+                        title: afterPayload.title ?? 'Untitled scenario',
+                        status: 'PENDING_REVIEW',
+                        kind: 'POSITIVE',
+                        steps: [],
+                        groundedOn: [],
+                        suite: { connect: [] },
+                    },
+                });
+                break;
+            }
+            case 'ADD_TEST_DATA': {
+                const testCase = await database_1.prismaAdmin.testCase.findUniqueOrThrow({
+                    where: { id: change.testCaseId },
+                });
+                const existing = testCase.testDataInline ?? {};
+                const incoming = JSON.parse(change.after);
+                await database_1.prismaAdmin.testCase.update({
+                    where: { id: change.testCaseId },
+                    data: { testDataInline: { ...existing, ...incoming } },
+                });
+                break;
+            }
+        }
+    }
+    await database_1.prismaAdmin.contextEnhancement.update({
+        where: { id: enhancementId },
+        data: { status: 'APPLIED', appliedAt: new Date() },
+    });
+}
+// ─── 5. updateProjectContextSources ──────────────────────────────────────────
+const CONTEXT_THRESHOLDS = {
+    WEB: 80,
+    API: 40,
+    NATIVE: 60,
+    HYBRID: 70,
+};
+async function updateProjectContextSources(tenantId, projectId, sourceType, payload) {
+    await database_1.prismaAdmin.$transaction(async (tx) => {
+        const project = await tx.project.findUniqueOrThrow({
+            where: { id: projectId, tenantId },
+            select: {
+                contextSources: true,
+                contextScore: true,
+                contextPhase: true,
+                contextSourceRequirements: true,
+                projectKind: true,
+            },
+        });
+        const src = { ...(project.contextSources ?? {}) };
+        if (sourceType && payload) {
+            const key = sourceType.toLowerCase();
+            src[key] = { ...(src[key] ?? {}), ...payload };
+        }
+        // Recompute score
+        let score = 0;
+        if (src.screenshot?.approvedAt)
+            score += 20;
+        else if ((src.screenshot?.count ?? 0) > 0)
+            score += 5;
+        if (src.figma?.approvedAt)
+            score += 25;
+        else if (src.figma?.importedAt)
+            score += 8;
+        if (src.crawl?.approvedAt)
+            score += 40;
+        else if ((src.crawl?.screenCount ?? 0) > 0)
+            score += 12;
+        if (src.api_spec?.approvedAt)
+            score += 15;
+        else if (src.api_spec?.uploadedAt)
+            score += 5;
+        // Recompute phase — never regress a more advanced phase
+        const threshold = CONTEXT_THRESHOLDS[project.projectKind ?? 'WEB'] ?? 80;
+        void threshold; // used by caller (recomputeApprovalGateSummary) after this
+        let phase = 'PENDING_CONTEXT';
+        if (score > 0 && score < 30)
+            phase = 'CONTEXT_PARTIAL';
+        else if (score >= 30)
+            phase = 'CONTEXT_ENRICHED';
+        // Phase transitions to DIFF_PENDING_APPROVAL / ALL_DIFFS_APPROVED / READY_FOR_SCRIPT_GEN
+        // are driven by recomputeApprovalGateSummary in crawl-diff-agent.ts — don't regress here
+        const currentIdx = PHASE_ORDER.indexOf((project.contextPhase ?? 'PENDING_CONTEXT'));
+        const newIdx = PHASE_ORDER.indexOf(phase);
+        const finalPhase = newIdx > currentIdx ? phase : (project.contextPhase ?? 'PENDING_CONTEXT');
+        await tx.project.update({
+            where: { id: projectId, tenantId },
+            data: { contextSources: src, contextScore: score, contextPhase: finalPhase },
+        });
+    });
+}

package/dist/field-detector-agent.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ZeTa-AI Field Detector Agent
+ *
+ * Drafts an AppField catalog from one of three inputs:
+ *   (1) Rendered HTML — DOM detector reads form controls
+ *   (2) OpenAPI/Swagger JSON/YAML — schema detector reads request bodies
+ *   (3) Sample JSON payload — shape detector infers types from values
+ *
+ * Output is always FieldSchema[] in "unconfirmed" status.
+ * Persist via AppBrain.upsertAppField() after user review.
+ */
+import type { FieldSchema } from '@taodigital/core';
+export declare function detectFieldsFromHtml(opts: {
+    tenantId: string;
+    projectId: string;
+    html: string;
+}): Promise<FieldSchema[]>;
+export declare function detectFieldsFromApi(opts: {
+    tenantId: string;
+    projectId: string;
+    input: string;
+}): Promise<FieldSchema[]>;
+/**
+ * Merge auto-detected fields into the project catalog.
+ * Preserves human-edited piiClass, notes, and status on existing rows.
+ */
+export declare function mergeIntoCatalog(opts: {
+    tenantId: string;
+    projectId: string;
+    detected: FieldSchema[];
+}): Promise<{
+    added: number;
+    updated: number;
+    unchanged: number;
+}>;