@pranshulsoni/flowwatch 1.0.0

package/dist/ai/groqInsightService.js

@@ -0,0 +1,230 @@
+import { getGroqApiKey, getGroqModel } from "../utils/flowwatchEnvStore.js";
+const GROQ_CHAT_COMPLETIONS_URL = "https://api.groq.com/openai/v1/chat/completions";
+const GROQ_MODELS_URL = "https://api.groq.com/openai/v1/models";
+const DEFAULT_GROQ_MODEL = "llama-3.3-70b-versatile";
+const ALLOWED_CHAT_ROLES = new Set(["user", "assistant"]);
+const MODEL_ID_PATTERN = /^[a-zA-Z0-9._:/-]{1,128}$/;
+const OUT_OF_SCOPE_RESPONSE = [
+    "### Server context only",
+    "",
+    "Ask Flowwatch AI can only help with this service's workflows, executions, traces, errors, feature flags, health checks, and backend runtime behavior.",
+    "",
+    "Try asking about:",
+    "- Recent failed workflow executions",
+    "- Slow traces or request latency",
+    "- Captured server errors",
+    "- Feature flag rollout impact",
+    "- Health check failures",
+].join("\n");
+const SERVER_QUESTION_TERMS = [
+    "api",
+    "backend",
+    "bullmq",
+    "cache",
+    "database",
+    "db",
+    "deployment",
+    "endpoint",
+    "error",
+    "exception",
+    "execution",
+    "express",
+    "failure",
+    "feature flag",
+    "flag",
+    "health",
+    "incident",
+    "latency",
+    "log",
+    "metric",
+    "migration",
+    "postgres",
+    "queue",
+    "redis",
+    "request",
+    "retry",
+    "route",
+    "server",
+    "service",
+    "span",
+    "status",
+    "throughput",
+    "trace",
+    "workflow",
+];
+function normalizeInsight(value, context) {
+    return {
+        summary: String(value?.summary || "No summary returned."),
+        likelyCause: String(value?.likelyCause || value?.likely_cause || "Unknown"),
+        impact: String(value?.impact || "Unknown"),
+        evidence: Array.isArray(value?.evidence) ? value.evidence.map(String).slice(0, 8) : [],
+        recommendedActions: Array.isArray(value?.recommendedActions)
+            ? value.recommendedActions.map(String).slice(0, 8)
+            : Array.isArray(value?.recommended_actions)
+                ? value.recommended_actions.map(String).slice(0, 8)
+                : [],
+        confidence: Math.max(0, Math.min(100, Number(value?.confidence ?? 0))),
+        sourceCounts: {
+            workflows: context.workflows.length,
+            executions: context.executions.length,
+            errors: context.errors.length,
+            traces: context.traces.length,
+            flags: context.flags.length,
+            health: context.health.length,
+        },
+    };
+}
+function parseInsightJson(content) {
+    const trimmed = content.trim();
+    const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/);
+    return JSON.parse(fenced?.[1] || trimmed);
+}
+function selectedModel(model) {
+    const value = model || getGroqModel() || DEFAULT_GROQ_MODEL;
+    if (!MODEL_ID_PATTERN.test(value)) {
+        throw new Error("Invalid Groq model id");
+    }
+    return value;
+}
+function sanitizeChatHistory(history) {
+    return (history || [])
+        .filter((message) => ALLOWED_CHAT_ROLES.has(message?.role))
+        .map((message) => ({
+        role: message.role,
+        content: String(message.content || "").slice(0, 4096),
+    }))
+        .slice(-50);
+}
+export function isServerObservabilityQuestion(message) {
+    const normalized = String(message || "").toLowerCase().replace(/\s+/g, " ").trim();
+    if (!normalized)
+        return false;
+    return SERVER_QUESTION_TERMS.some((term) => normalized.includes(term));
+}
+export function outOfScopeFlowwatchResponse() {
+    return OUT_OF_SCOPE_RESPONSE;
+}
+export async function listGroqModels() {
+    const apiKey = getGroqApiKey();
+    if (!apiKey) {
+        throw new Error("GROQ_API_KEY is not configured");
+    }
+    const response = await fetch(GROQ_MODELS_URL, {
+        headers: {
+            "Authorization": `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        const message = await response.text();
+        throw new Error(`Groq model request failed: ${response.status} ${message}`);
+    }
+    const models = await response.json();
+    return Array.isArray(models?.data)
+        ? models.data
+            .map((model) => ({
+            id: String(model?.id || ""),
+            ownedBy: model?.owned_by ? String(model.owned_by) : undefined,
+        }))
+            .filter((model) => model.id)
+        : [];
+}
+export async function generateGroqInsight(context, model) {
+    const apiKey = getGroqApiKey();
+    if (!apiKey) {
+        throw new Error("GROQ_API_KEY is not configured");
+    }
+    const response = await fetch(GROQ_CHAT_COMPLETIONS_URL, {
+        method: "POST",
+        headers: {
+            "Authorization": `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: selectedModel(model),
+            temperature: 0.2,
+            response_format: { type: "json_object" },
+            messages: [
+                {
+                    role: "system",
+                    content: [
+                        "You are Flowwatch's backend reliability AI.",
+                        "Use only the provided JSON context.",
+                        "Do not invent workflow names, trace IDs, errors, metrics, services, or incidents.",
+                        "Return valid JSON with these exact keys: summary, likelyCause, impact, evidence, recommendedActions, confidence.",
+                        "evidence and recommendedActions must be arrays of strings. confidence must be a number from 0 to 100.",
+                    ].join(" "),
+                },
+                {
+                    role: "user",
+                    content: JSON.stringify(context),
+                },
+            ],
+        }),
+    });
+    if (!response.ok) {
+        const message = await response.text();
+        throw new Error(`Groq insight request failed: ${response.status} ${message}`);
+    }
+    const completion = await response.json();
+    const content = completion.choices?.[0]?.message?.content;
+    if (!content) {
+        throw new Error("Groq returned an empty insight response");
+    }
+    return normalizeInsight(parseInsightJson(content), context);
+}
+export async function askGroqAi(context, message, history, model) {
+    if (!isServerObservabilityQuestion(message)) {
+        return outOfScopeFlowwatchResponse();
+    }
+    const apiKey = getGroqApiKey();
+    if (!apiKey) {
+        throw new Error("GROQ_API_KEY is not configured");
+    }
+    const safeHistory = sanitizeChatHistory(history);
+    const messages = [
+        {
+            role: "system",
+            content: [
+                "You are Flowwatch's backend reliability AI.",
+                "You help developers diagnose errors, traces, feature flags, workflows, and health checks.",
+                "Only answer questions about the current server, backend application, Flowwatch data, reliability, observability, or operational debugging.",
+                "If the user asks for unrelated general knowledge, personal advice, creative writing, jokes, math homework, trivia, or anything outside this server context, refuse briefly and redirect them to ask about server health, errors, traces, workflows, feature flags, or latency.",
+                "Use the provided JSON context of the system which contains recent workflows, executions, errors, traces, feature flags, and health check statuses.",
+                "Answer the user's question accurately. Focus on diagnostics, suggestions, and resolving issues.",
+                "Keep answers developer-friendly, clear, and actionable. Use markdown formatting for lists, codes, and code snippets.",
+            ].join(" "),
+        },
+        {
+            role: "system",
+            content: `Here is the current system context: ${JSON.stringify(context)}`,
+        },
+        ...safeHistory,
+        {
+            role: "user",
+            content: message,
+        }
+    ];
+    const response = await fetch(GROQ_CHAT_COMPLETIONS_URL, {
+        method: "POST",
+        headers: {
+            "Authorization": `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: selectedModel(model),
+            temperature: 0.5,
+            messages,
+        }),
+    });
+    if (!response.ok) {
+        const msg = await response.text();
+        throw new Error(`Groq chat request failed: ${response.status} ${msg}`);
+    }
+    const completion = await response.json();
+    const content = completion.choices?.[0]?.message?.content;
+    if (!content) {
+        throw new Error("Groq returned an empty response");
+    }
+    return content;
+}

package/dist/createFlowwatch.d.ts

@@ -0,0 +1,17 @@
+import type { FlowwatchConfig } from "./types/index.js";
+import type { RegisterWorkflow, TriggerWorkflow } from "./engine/workflows/types.js";
+import type { EvaluateFlag } from "./engine/flags/types.js";
+import { type TraceFunction } from "./engine/trace/traceEngine.js";
+import { type CaptureErrorFunction } from "./engine/errors/errorEngine.js";
+import type { ErrorRequestHandler, RequestHandler, Router } from "express";
+export interface Flowwatch {
+    dashboard: Router;
+    workflow: RegisterWorkflow;
+    trigger: TriggerWorkflow;
+    flag: EvaluateFlag;
+    requestTracer: RequestHandler;
+    trace: TraceFunction;
+    errorHandler: ErrorRequestHandler;
+    captureError: CaptureErrorFunction;
+}
+export declare function createFlowwatch(config: FlowwatchConfig): Promise<Flowwatch>;

package/dist/createFlowwatch.js

@@ -0,0 +1,90 @@
+import { loadFlowwatchEnv } from "./utils/flowwatchEnvStore.js";
+import { createDashboardRouter } from "./dashboard/routes/router.js";
+import { validateConfig } from "./runtime/config/validationConfig.js";
+import { normalizeConfig } from "./runtime/config/normalizeConfig.js";
+import { createPostgresPool } from "./persistence/db/postgres.js";
+import { createElasticsearchClient } from "./search/elasticsearch/client.js";
+import { runMigrations } from "./persistence/migrations/migrationRunner.js";
+import { migrations } from "./persistence/migrations/migrations.js";
+import { createWorkflowEngine } from "./engine/workflows/workflowEngine.js";
+import { createWorkflowQueue } from "./engine/background/queues/workflowQueue.js";
+import { createWorkflowWorker } from "./engine/background/workers/workflowWorker.js";
+import { createFlagEngine } from "./engine/flags/flagEngine.js";
+import { createRequestTracingMiddleware } from "./runtime/tracing/tracingMiddleware.js";
+import { createTraceEngine } from "./engine/trace/traceEngine.js";
+import { captureError, createErrorHandler } from "./engine/errors/errorEngine.js";
+import { createMissingMappings } from "./search/elasticsearch/mappingChecker.js";
+import { createRedisClient } from "./persistence/cache/redisClient.js";
+export async function createFlowwatch(config) {
+    await loadFlowwatchEnv();
+    const validConfig = validateConfig(config);
+    const normalizedConfig = await normalizeConfig(validConfig);
+    const postgresPool = createPostgresPool(normalizedConfig.db);
+    if (normalizedConfig.migrations.autoRun) {
+        await runMigrations(postgresPool, migrations);
+    }
+    const redisClient = createRedisClient(normalizedConfig.redis.url);
+    const elasticsearchClient = createElasticsearchClient(normalizedConfig.elasticsearch.node);
+    // BullMQ requires Redis ≥ 5. Gracefully degrade on older versions.
+    let workflowQueue = null;
+    try {
+        workflowQueue = createWorkflowQueue(normalizedConfig.redis.url);
+        // Probe the connection — BullMQ throws synchronously on version check
+        await workflowQueue.waitUntilReady();
+    }
+    catch (err) {
+        const reason = err?.message ?? String(err);
+        console.warn(`[Flowwatch] ⚠️  Workflow queue unavailable (${reason}). Workflows will be registered but cannot be executed until Redis ≥ 5 is available.`);
+        workflowQueue = null;
+    }
+    const traceEngine = createTraceEngine({
+        pool: postgresPool,
+        elasticsearchClient,
+    });
+    const workflowEngine = createWorkflowEngine({
+        pool: postgresPool,
+        workflowQueue,
+        traceEngine,
+    });
+    const requestTracer = createRequestTracingMiddleware(postgresPool);
+    const errorEngineOptions = {
+        pool: postgresPool,
+        elasticsearchClient,
+    };
+    const errorHandler = createErrorHandler(errorEngineOptions);
+    const captureFlowwatchError = (error, options) => {
+        return captureError(errorEngineOptions, error, options);
+    };
+    const flagEngine = createFlagEngine(postgresPool, traceEngine, captureFlowwatchError, redisClient);
+    await createMissingMappings(elasticsearchClient);
+    if (normalizedConfig.worker.enabled && workflowQueue !== null) {
+        try {
+            createWorkflowWorker({
+                redisUrl: normalizedConfig.redis.url,
+                pool: postgresPool,
+                getWorkflow: workflowEngine.getWorkflow,
+                traceEngine,
+                captureError: captureFlowwatchError,
+            });
+        }
+        catch (err) {
+            console.warn(`[Flowwatch] ⚠️  Workflow worker could not start: ${err?.message}`);
+        }
+    }
+    const dashboard = createDashboardRouter({
+        config: normalizedConfig,
+        postgresPool,
+        redisClient,
+        elasticsearchClient,
+    });
+    return {
+        dashboard,
+        workflow: workflowEngine.workflow,
+        trigger: workflowEngine.trigger,
+        flag: flagEngine.flag,
+        requestTracer,
+        trace: traceEngine.trace,
+        errorHandler,
+        captureError: captureFlowwatchError,
+    };
+}

package/dist/dashboard/routes/dashboardResponse.d.ts

@@ -0,0 +1,204 @@
+import type { NormalizedFlowwatchConfig } from "../../types/index.js";
+export declare function serializeFlag(flag: any, ruleCount?: number): {
+    id: any;
+    key: any;
+    description: any;
+    enabled: any;
+    rollout: any;
+    rolloutPercentage: any;
+    rules: number;
+    changedBy: any;
+    createdAt: string | null;
+    updatedAt: string | null;
+};
+export declare function serializeRule(rule: any): {
+    id: any;
+    flagId: any;
+    attribute: any;
+    operator: any;
+    value: any;
+    enabled: any;
+    createdAt: string | null;
+    updatedAt: string | null;
+};
+export declare function serializeAuditLog(log: any): {
+    id: any;
+    flagId: any;
+    action: any;
+    before: any;
+    after: any;
+    changedBy: any;
+    createdAt: string | null;
+};
+export declare function serializeError(error: any): {
+    id: any;
+    message: any;
+    name: any;
+    category: any;
+    level: any;
+    source: any;
+    status: any;
+    statusCode: any;
+    trace: any;
+    traceId: any;
+    spanId: any;
+    fingerprint: any;
+    metadata: any;
+    stack: any;
+    occurred: string;
+    occurredAt: string | null;
+    createdAt: string | null;
+};
+export declare function serializeTrace(trace: any, spans?: any[]): {
+    id: any;
+    method: any;
+    path: any;
+    status: any;
+    statusCode: any;
+    ip: any;
+    duration: any;
+    durationMs: any;
+    userId: any;
+    userAgent: any;
+    metadata: any;
+    startedAt: string | null;
+    endedAt: string | null;
+    createdAt: string | null;
+    spans: {
+        id: any;
+        traceId: any;
+        parentSpanId: any;
+        name: any;
+        type: any;
+        status: string;
+        duration: any;
+        durationMs: any;
+        metadata: any;
+        startedAt: string | null;
+        endedAt: string | null;
+    }[];
+};
+export declare function serializeExecution(execution: any, steps?: any[]): {
+    id: any;
+    workflowId: any;
+    workflow: any;
+    workflowName: any;
+    workflowVersion: any;
+    status: any;
+    input: any;
+    output: any;
+    error: any;
+    started: string;
+    finished: string;
+    failedStep: any;
+    attempts: any;
+    duration: string;
+    createdAt: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    failedAt: string | null;
+    durationMs: number | null;
+    steps: {
+        id: any;
+        executionId: any;
+        workflowStepId: any;
+        stepIndex: any;
+        stepName: any;
+        name: any;
+        status: any;
+        input: any;
+        output: any;
+        error: any;
+        attempts: any;
+        attemptCount: any;
+        maxRetries: any;
+        startedAt: string | null;
+        completedAt: string | null;
+        failedAt: string | null;
+        nextRetryAt: string | null;
+        durationMs: number | null;
+        duration: string;
+    }[];
+};
+export declare function serializeSettings(config: NormalizedFlowwatchConfig): {
+    serviceName: string;
+    environment: string;
+    dashboard: {
+        path: string;
+        enabled: boolean;
+        authEnabled: boolean;
+    };
+    worker: {
+        concurrency: number;
+        enabled: boolean;
+        workflowConcurrency: number;
+        errorIndexingConcurrency: number;
+        maintenanceConcurrency: number;
+        queuePrefix: string;
+    };
+    migrations: Required<import("../../types/index.js").FlowwatchMigrationConfig>;
+    ai: {
+        groqApiKeyConfigured: boolean;
+        groqModel: string;
+    };
+};
+export declare function serializeWorkflowSummary(workflow: any, executions: any[], definitionSteps: any[], latestExecution?: any, latestExecutionSteps?: any[]): {
+    id: any;
+    name: any;
+    version: any;
+    steps: number;
+    created: string;
+    createdAt: string | null;
+    updatedAt: string | null;
+    lastStatus: any;
+    totalRuns: number;
+    completedRuns: number;
+    failedRuns: number;
+    runningRuns: number;
+    failures: number;
+    pinned: boolean;
+    chain: any[];
+    latestExecution: {
+        id: any;
+        workflowId: any;
+        workflow: any;
+        workflowName: any;
+        workflowVersion: any;
+        status: any;
+        input: any;
+        output: any;
+        error: any;
+        started: string;
+        finished: string;
+        failedStep: any;
+        attempts: any;
+        duration: string;
+        createdAt: string | null;
+        startedAt: string | null;
+        completedAt: string | null;
+        failedAt: string | null;
+        durationMs: number | null;
+        steps: {
+            id: any;
+            executionId: any;
+            workflowStepId: any;
+            stepIndex: any;
+            stepName: any;
+            name: any;
+            status: any;
+            input: any;
+            output: any;
+            error: any;
+            attempts: any;
+            attemptCount: any;
+            maxRetries: any;
+            startedAt: string | null;
+            completedAt: string | null;
+            failedAt: string | null;
+            nextRetryAt: string | null;
+            durationMs: number | null;
+            duration: string;
+        }[];
+    } | undefined;
+};
+export declare function latestByWorkflow(executions: any[]): Map<string, any>;