@taodigital/app-brain 0.0.0-stage → 1.2.0

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @detiq/app-brain — The Moat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Zeta Core is the project's permanent, structured, exportable knowledge.
+
+## Grounding (the important bit)
+`grounding.ts` defines how the AI gets real facts before generating tests.
+- **Default: `DirectLoadGrounding`** — fetch the exact facts for a screen and
+  load them directly. Simple, precise, cheap. Best for a closed workspace.
+- **Later: `VectorSearchGrounding`** (RAG) — added ONLY for `oversized`
+  projects whose knowledge is too big to load directly. Same Zeta Core,
+  smarter finder. Agents don't change — only the strategy swaps.
+
+> Rule: agents call `ground(...)` and never invent elements. If a fact isn't
+> in the returned context, the agent asks instead of guessing.

package/dist/archetype-classification.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Screen-archetype classification + KAG journey-pair suggestion — pure logic,
+ * no I/O, unit-testable in isolation (same shape as orphan-classification.ts).
+ *
+ * Rule-based rather than LLM-based on purpose: this only needs to look at
+ * data already captured during crawl (Element.role/expectedData, Screen.url/
+ * name), so it works with zero LLM provider configured and costs nothing to
+ * run on every project. It is deliberately coarse — good enough to rank
+ * "which screen pairs are worth generating a KAG journey test for" so a user
+ * doesn't have to already know both screen ids, not a general-purpose UI
+ * classifier.
+ */
+export type ScreenArchetype = 'LOGIN' | 'SIGNUP' | 'SEARCH' | 'CHECKOUT' | 'FORM' | 'GENERIC';
+export interface ClassifiableElement {
+    role: string | null;
+    expectedData: string | null;
+}
+export interface ClassifiableScreen {
+    id: string;
+    name: string;
+    url: string | null;
+}
+export interface ArchetypeResult {
+    archetype: ScreenArchetype;
+    reason: string;
+}
+/** Classifies a single screen from its URL/name and the elements crawled on it.
+ *  Checked in priority order — the first matching, most specific signal wins,
+ *  since e.g. a checkout page often also has a form field or two. */
+export declare function classifyScreenArchetype(screen: ClassifiableScreen, elements: ClassifiableElement[]): ArchetypeResult;
+export interface ClassifiedScreen {
+    id: string;
+    name: string;
+    archetype: ScreenArchetype;
+}
+export interface JourneyCandidate {
+    startScreenId: string;
+    startScreenName: string;
+    startArchetype: ScreenArchetype;
+    endScreenId: string;
+    endScreenName: string;
+    endArchetype: ScreenArchetype;
+    label: string;
+}
+/**
+ * Finds every (start, end) screen pair whose archetypes match one of the
+ * interesting-journey rules. Pure and graph-agnostic on purpose — this does
+ * NOT check whether a KAG path actually connects the two screens (that
+ * requires a DB-backed BFS, see AppBrain.suggestJourneys in repository.ts,
+ * which calls this first to get a small, ranked candidate list and only then
+ * pays for a graph traversal per candidate instead of checking every
+ * archetype pair against every other screen).
+ */
+export declare function matchInterestingJourneyPairs(screens: ClassifiedScreen[]): JourneyCandidate[];

package/dist/archetype-classification.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Screen-archetype classification + KAG journey-pair suggestion — pure logic,
+ * no I/O, unit-testable in isolation (same shape as orphan-classification.ts).
+ *
+ * Rule-based rather than LLM-based on purpose: this only needs to look at
+ * data already captured during crawl (Element.role/expectedData, Screen.url/
+ * name), so it works with zero LLM provider configured and costs nothing to
+ * run on every project. It is deliberately coarse — good enough to rank
+ * "which screen pairs are worth generating a KAG journey test for" so a user
+ * doesn't have to already know both screen ids, not a general-purpose UI
+ * classifier.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyScreenArchetype = classifyScreenArchetype;
+exports.matchInterestingJourneyPairs = matchInterestingJourneyPairs;
+const LOGIN_URL_RE = /login|signin|sign-in/i;
+const SIGNUP_URL_RE = /signup|sign-up|register|onboard/i;
+const CHECKOUT_URL_RE = /checkout|cart|basket/i;
+// Element.role values observed at crawl time (crawler.ts) are lowercase HTML
+// input types or tag/aria names — see that file for exactly how they're set.
+const FORM_FIELD_ROLES = new Set(['text', 'email', 'tel', 'number', 'date', 'textarea', 'select']);
+/** Classifies a single screen from its URL/name and the elements crawled on it.
+ *  Checked in priority order — the first matching, most specific signal wins,
+ *  since e.g. a checkout page often also has a form field or two. */
+function classifyScreenArchetype(screen, elements) {
+    const hasPassword = elements.some((e) => e.role === 'password' || e.expectedData === 'password');
+    const hasEmail = elements.some((e) => e.role === 'email' || e.expectedData === 'valid_email');
+    const hasSearch = elements.some((e) => e.role === 'search' || e.expectedData === 'search_term');
+    const urlOrName = `${screen.url ?? ''} ${screen.name ?? ''}`;
+    if (CHECKOUT_URL_RE.test(urlOrName)) {
+        return { archetype: 'CHECKOUT', reason: "URL/name matches checkout/cart/basket" };
+    }
+    if (SIGNUP_URL_RE.test(urlOrName) && hasEmail && hasPassword) {
+        return { archetype: 'SIGNUP', reason: 'URL/name matches signup/register, with email + password fields present' };
+    }
+    if (hasPassword) {
+        return { archetype: 'LOGIN', reason: 'Has a password-type input element' };
+    }
+    if (LOGIN_URL_RE.test(urlOrName)) {
+        return { archetype: 'LOGIN', reason: 'URL/name matches login/signin' };
+    }
+    if (hasSearch) {
+        return { archetype: 'SEARCH', reason: 'Has a search-type input element' };
+    }
+    if (elements.some((e) => e.role && FORM_FIELD_ROLES.has(e.role))) {
+        return { archetype: 'FORM', reason: 'Has one or more data-entry form fields' };
+    }
+    return { archetype: 'GENERIC', reason: 'No distinguishing signals found' };
+}
+/** Archetype pairs worth generating a cross-screen journey test for, ranked
+ *  by how commonly they represent a real user flow. Order matters — earlier
+ *  entries are suggested before later ones when a project has many candidate
+ *  pairs. GENERIC is deliberately excluded from both sides: with no
+ *  distinguishing signal, pairing it with anything is a guess, not a
+ *  suggestion. */
+const INTERESTING_JOURNEYS = [
+    { from: 'LOGIN', to: 'CHECKOUT', label: 'Login → Checkout' },
+    { from: 'SIGNUP', to: 'LOGIN', label: 'Signup → Login' },
+    { from: 'SEARCH', to: 'CHECKOUT', label: 'Search → Checkout' },
+    { from: 'LOGIN', to: 'FORM', label: 'Login → Form submission' },
+    { from: 'SEARCH', to: 'FORM', label: 'Search → Form submission' },
+];
+/**
+ * Finds every (start, end) screen pair whose archetypes match one of the
+ * interesting-journey rules. Pure and graph-agnostic on purpose — this does
+ * NOT check whether a KAG path actually connects the two screens (that
+ * requires a DB-backed BFS, see AppBrain.suggestJourneys in repository.ts,
+ * which calls this first to get a small, ranked candidate list and only then
+ * pays for a graph traversal per candidate instead of checking every
+ * archetype pair against every other screen).
+ */
+function matchInterestingJourneyPairs(screens) {
+    const candidates = [];
+    for (const rule of INTERESTING_JOURNEYS) {
+        const starts = screens.filter((s) => s.archetype === rule.from);
+        const ends = screens.filter((s) => s.archetype === rule.to);
+        for (const start of starts) {
+            for (const end of ends) {
+                if (start.id === end.id)
+                    continue;
+                candidates.push({
+                    startScreenId: start.id,
+                    startScreenName: start.name,
+                    startArchetype: start.archetype,
+                    endScreenId: end.id,
+                    endScreenName: end.name,
+                    endArchetype: end.archetype,
+                    label: rule.label,
+                });
+            }
+        }
+    }
+    return candidates;
+}

package/dist/cloud-storage.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Cloud Storage integration for ZeTa-AI artifacts.
+ *
+ * Folder convention:
+ *   {prefix}/{tenantId}/{projectId}/screenshots/{filename}
+ *   {prefix}/{tenantId}/{projectId}/test-plans/{filename}
+ *   {prefix}/{tenantId}/{projectId}/test-data/{filename}
+ *   {prefix}/{tenantId}/{projectId}/reports/{runId}/{filename}
+ *
+ * Industry reference: Playwright Cloud, BrowserStack, Cypress Cloud all use
+ * tenant→project→type→artifact path hierarchies for multi-tenant isolation.
+ */
+type StorageKind = 'S3' | 'R2' | 'GDRIVE' | 'DROPBOX';
+interface StorageConfig {
+    kind: StorageKind;
+    creds: Record<string, string>;
+    prefix: string;
+}
+export interface TenantStorageConfig {
+    provider: 'S3' | 'R2';
+    bucket: string;
+    region?: string;
+    accountId?: string;
+    endpointUrl?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    publicUrl?: string;
+    prefix?: string;
+}
+/**
+ * Resolves the storage config to use for a tenant's screenshots/artifacts:
+ * the tenant's own connector if they've configured one, otherwise the
+ * platform-managed default bucket (if configured via env vars), otherwise
+ * null — meaning the caller should leave the artifact on local disk.
+ */
+export declare function getTenantStorageConfig(tenantId: string): Promise<TenantStorageConfig | null>;
+/**
+ * Upload a screenshot to tenant-level S3/R2 storage.
+ * Returns public URL if publicUrl configured, otherwise returns the storage key
+ * (callers should use resolveCloudUrl() to generate presigned URLs on demand).
+ */
+export declare function uploadScreenshotToTenantStorage(cfg: TenantStorageConfig, localPath: string, screenshotKey: string): Promise<string>;
+/**
+ * Upload any file to tenant-level S3/R2 storage.
+ * Returns public URL if publicUrl configured, otherwise returns the storage key.
+ */
+export declare function uploadFileToTenantStorage(cfg: TenantStorageConfig, localPath: string, storageKey: string, contentType: string): Promise<string>;
+/**
+ * Resolve a stored cloudUrl to a usable URL for the browser.
+ * - If it starts with https:// → return as-is (public URL, no expiry).
+ * - Otherwise → treat as storage key and generate a presigned GET URL.
+ */
+export declare function resolveCloudUrl(cfg: TenantStorageConfig, cloudUrl: string, expiresIn?: number): Promise<string | null>;
+export declare function getProjectStorageConfig(tenantId: string, projectId: string): Promise<StorageConfig | null>;
+/** Build the cloud storage key for an artifact. */
+export declare function buildArtifactKey(tenantId: string, projectId: string, type: string, filename: string, prefix?: string): string;
+/** Upload a single file to the configured cloud storage provider. Returns storage key/path. */
+export declare function uploadArtifact(cfg: StorageConfig, localPath: string, storageKey: string, contentType?: string): Promise<string>;
+/** Upload a Buffer (for generated content like test plans, scripts). */
+export declare function uploadArtifactBuffer(cfg: StorageConfig, buffer: Buffer, storageKey: string, contentType?: string): Promise<string>;
+/**
+ * Generate a presigned GET URL for S3/R2 (time-limited, auth-gated).
+ * GDrive/Dropbox: returns null (caller must use downloadBufferFromTenantStorage + proxy).
+ */
+export declare function generatePresignedGetUrl(cfg: TenantStorageConfig, storageKey: string, expiresIn?: number): Promise<string | null>;
+/**
+ * Download raw bytes from tenant storage (for GDrive/Dropbox proxy, or fallback).
+ */
+export declare function downloadBufferFromTenantStorage(cfg: TenantStorageConfig, storageKey: string): Promise<Buffer>;
+/** Upload a buffer to tenant storage. Returns the storage key. */
+export declare function uploadBufferToTenantStorage(cfg: TenantStorageConfig, buffer: Buffer, storageKey: string, contentType?: string): Promise<string>;
+/** Build the canonical storage key for a knowledge artifact. */
+export declare function buildKnowledgeKey(tenantId: string, projectId: string, artifactId: string, filename: string, prefix?: string): string;
+export interface StorageObject {
+    key: string;
+    size: number;
+    lastModified: string | null;
+}
+/** List all S3/R2 objects under a project prefix. Paginates automatically. */
+export declare function listProjectStorageObjects(cfg: TenantStorageConfig, tenantId: string, projectId: string): Promise<StorageObject[]>;
+/**
+ * Delete all S3/R2 objects under a project prefix (GDPR cleanup on project delete).
+ * Batch-deletes in groups of 1 000 (S3 DeleteObjects limit).
+ * No-ops silently when cfg is null.
+ */
+export declare function deleteProjectStorageObjects(tenantId: string, projectId: string): Promise<void>;
+/**
+ * Delete all S3/R2 objects for an entire tenant (GDPR cleanup on tenant delete).
+ * Lists by tenant prefix and batch-deletes everything found.
+ * No-ops silently when cfg is null.
+ */
+export declare function deleteTenantStorageObjects(tenantId: string): Promise<void>;
+/** Build a content object key for a specific entity type. */
+export declare function buildContentKey(tenantId: string, projectId: string, type: 'scripts' | 'artifacts' | 'testcases', entityId: string, ext: string, prefix?: string): string;
+/**
+ * Persist string content to tenant S3 if configured.
+ * Returns the storage key on success, or null if no S3 is configured
+ * (caller should keep content in the DB column in that case).
+ */
+export declare function persistContent(tenantId: string, projectId: string, type: 'scripts' | 'artifacts' | 'testcases', entityId: string, ext: string, content: string, mimeType?: string): Promise<string | null>;
+/**
+ * Resolve content: if a storage key is provided, download from S3.
+ * Otherwise (or on error) return the fallback DB content.
+ */
+export declare function resolveContent(tenantId: string, storageKey: string | null | undefined, fallback: string): Promise<string>;
+export {};