@prsense/workflows 0.1.0

package/src/review/retrieveContext.ts

@@ -0,0 +1,105 @@
+// packages/workflows/src/review/retrieveContext.ts
+
+import type { RetrievedContext, EventBus, ContextChunk } from "@prsense/core";
+import { CoreEvents } from "@prsense/core";
+import type { ResolvedConfig } from "@prsense/config";
+import { PostgresRagChunkRepository } from "@prsense/context";
+import {
+  createOpenAiEmbeddingClient,
+  createOllamaEmbeddingClient,
+} from "@prsense/llm";
+
+export async function retrieveContext(params: {
+  config: ResolvedConfig;
+  query: string;
+  repoProvider: string;
+  repoName: string;
+  repoRef?: string;
+  limit: number;
+  eventBus?: EventBus;
+}): Promise<RetrievedContext> {
+  const { config, query, repoProvider, repoName, repoRef, limit } = params;
+
+  // -------------------------------------------------
+  // Create embedding client
+  // -------------------------------------------------
+
+  const embeddingClient =
+    config.embeddings.provider === "openai"
+      ? createOpenAiEmbeddingClient({
+          apiKey: process.env.OPENAI_API_KEY!,
+          model: config.embeddings.model,
+        })
+      : createOllamaEmbeddingClient({
+          model: config.embeddings.model,
+        });
+
+  const [queryEmbedding] = await embeddingClient.embed([query]);
+
+  params.eventBus?.emit(CoreEvents.WorkflowReviewContextEmbeddingGenerated, {
+    dimension: queryEmbedding?.length,
+  });
+
+  if (!queryEmbedding) {
+    throw new Error("Failed to generate query embedding");
+  }
+
+  // -------------------------------------------------
+  // Query RAG store
+  // -------------------------------------------------
+
+  const repository = new PostgresRagChunkRepository(config.database.url);
+
+  const rows = await repository.searchNearest({
+    repoProvider,
+    repoName,
+    ...(repoRef ? { repoRef } : {}),
+    embedding: queryEmbedding,
+    limit,
+  });
+
+  params.eventBus?.emit(CoreEvents.WorkflowReviewContextRetrieved, {
+    chunks: rows.length,
+    repoProvider,
+    repoName,
+    minDistance: rows[0]?.distance,
+    maxDistance: rows[rows.length - 1]?.distance,
+  });
+
+  // -------------------------------------------------
+  // Map to domain objects
+  // -------------------------------------------------
+
+  const chunks: ContextChunk[] = rows.map((row) => {
+    const chunk: ContextChunk = {
+      id: row.id,
+      source: {
+        kind: "file",
+        path: row.path,
+      },
+      content: row.content,
+      metadata: {
+        path: row.path,
+        ...(row.lineStart != null ? { lineStart: row.lineStart } : {}),
+        ...(row.lineEnd != null ? { lineEnd: row.lineEnd } : {}),
+        ...(row.language != null ? { language: row.language } : {}),
+      },
+    };
+
+    params.eventBus?.emit(CoreEvents.WorkflowReviewContextChunkRetrieved, {
+      source: chunk.source,
+      metadata: chunk.metadata,
+      distance: row.distance,
+    });
+
+    return chunk;
+  });
+
+  return {
+    chunks,
+    stats: {
+      totalChunks: rows.length,
+      truncated: rows.length === limit,
+    },
+  };
+}

package/src/review/reviewWorkflow.ts

@@ -0,0 +1,366 @@
+// packages/workflows/src/review/reviewWorkflow.ts
+
+import { CoreEvents, EventBus, buildReviewPrompt } from "@prsense/core";
+import type { ReviewSignal, DiffProvider } from "@prsense/core";
+import type { ResolvedConfig, CredentialContext } from "@prsense/config";
+import { PostgresIndexMetadataRepository } from "@prsense/context";
+import {
+  createOpenAiClient,
+  createOllamaClient,
+  createGoogleClient,
+  createAnthropicClient,
+  type LlmClient,
+  type LlmUsage,
+} from "@prsense/llm";
+import type { ReviewWorkflowResult } from "./types.js";
+import { validateReviewOutput } from "./validateReviewOutput.js";
+import { buildDiffEmbeddingQuery } from "./buildDiffEmbeddingQuery.js";
+import { dedupeSignals } from "./dedupeSignals.js";
+import { retrieveContext } from "./retrieveContext.js";
+import { normalizeSignal } from "./normalizeSignal.js";
+import { extractJson } from "./extractJson.js";
+
+export async function runReviewWorkflow({
+  config,
+  credentials,
+  diffProvider,
+  eventBus,
+}: {
+  config: ResolvedConfig;
+  credentials: CredentialContext;
+  diffProvider: DiffProvider;
+  eventBus: EventBus;
+}): Promise<ReviewWorkflowResult> {
+  eventBus.emit(CoreEvents.WorkflowReviewStarted);
+
+  try {
+    // -------------------------------------------------
+    // Load diff from provider
+    // -------------------------------------------------
+
+    const { diff, revision, repositoryIdentity, metadata } =
+      await diffProvider.load();
+
+    const metadataRepository = new PostgresIndexMetadataRepository(
+      config.database.url,
+    );
+
+    const storedMetadata = await metadataRepository.load(
+      repositoryIdentity.provider,
+      repositoryIdentity.id,
+    );
+
+    let contextualReviewAvailable = false;
+
+    if (storedMetadata) {
+      const embeddingMatches =
+        storedMetadata.embedding.provider === config.embeddings.provider &&
+        storedMetadata.embedding.model === config.embeddings.model;
+
+      if (embeddingMatches) {
+        contextualReviewAvailable = true;
+
+        if (storedMetadata.revision.commitSha !== revision) {
+          eventBus.emit(CoreEvents.WorkflowReviewIndexOutdated, {
+            indexedCommit: storedMetadata.revision.commitSha,
+            currentCommit: revision,
+          });
+        }
+      }
+    }
+
+    if (!storedMetadata) {
+      eventBus.emit(CoreEvents.WorkflowReviewContextUnavailable);
+    } else if (!contextualReviewAvailable) {
+      eventBus.emit(CoreEvents.WorkflowReviewIndexOutdated, {
+        indexedCommit: storedMetadata.revision.commitSha,
+        currentCommit: revision,
+      });
+    } else {
+      eventBus.emit(CoreEvents.WorkflowReviewContextAvailable);
+    }
+
+    if (diff.files.length === 0) {
+      eventBus.emit(CoreEvents.WorkflowReviewFinished);
+      return {
+        outcome: "success",
+        payload: { signals: [] },
+      };
+    }
+
+    // -------------------------------------------------
+    // Retrieve contextual chunks (RAG) if available
+    // -------------------------------------------------
+
+    let contextText = "";
+
+    if (contextualReviewAvailable) {
+      const retrievalQuery = buildDiffEmbeddingQuery({
+        diff,
+        ...(metadata?.title ? { title: metadata.title } : {}),
+        ...(metadata?.description ? { description: metadata.description } : {}),
+      });
+      eventBus.emit(CoreEvents.WorkflowReviewContextQueryBuilt, {
+        preview: retrievalQuery.slice(0, 500),
+      });
+
+      const retrieved = await retrieveContext({
+        config,
+        query: retrievalQuery,
+        repoProvider: repositoryIdentity.provider,
+        repoName: repositoryIdentity.id,
+        limit: config.context.maxChunks,
+        eventBus,
+      });
+
+      // context size guard
+      const MAX_CONTEXT_CHARS = 20000;
+
+      let accumulated = "";
+      for (const chunk of retrieved.chunks) {
+        if (accumulated.length + chunk.content.length > MAX_CONTEXT_CHARS)
+          break;
+        accumulated += chunk.content + "\n\n";
+      }
+
+      contextText = accumulated;
+
+      eventBus.emit(CoreEvents.WorkflowReviewContextRetrieved, {
+        chunks: retrieved.stats.totalChunks,
+        truncated: retrieved.stats.truncated,
+        contextChars: contextText.length,
+      });
+    }
+
+    // -------------------------------------------------
+    // Create LLM client
+    // -------------------------------------------------
+
+    let llmClient: LlmClient;
+
+    switch (config.llm.provider) {
+      case "openai": {
+        const apiKey = credentials.openai?.apiKey;
+        if (!apiKey) {
+          throw new Error("OpenAI credentials missing");
+        }
+
+        llmClient = createOpenAiClient({
+          apiKey,
+          model: config.llm.model,
+          temperature: config.llm.temperature,
+        });
+        break;
+      }
+
+      case "google": {
+        const apiKey = credentials.google?.apiKey;
+        if (!apiKey) {
+          throw new Error("Google credentials missing");
+        }
+
+        llmClient = createGoogleClient({
+          apiKey,
+          model: config.llm.model,
+          temperature: config.llm.temperature,
+        });
+        break;
+      }
+
+      case "anthropic": {
+        const apiKey = credentials.anthropic?.apiKey;
+        if (!apiKey) {
+          throw new Error("Anthropic credentials missing");
+        }
+
+        llmClient = createAnthropicClient({
+          apiKey,
+          model: config.llm.model,
+          temperature: config.llm.temperature,
+        });
+        break;
+      }
+
+      case "ollama":
+      default:
+        llmClient = createOllamaClient({
+          model: config.llm.model,
+          temperature: config.llm.temperature,
+        });
+    }
+
+    // -------------------------------------------------
+    // Generate review
+    // -------------------------------------------------
+
+    const allSignals: ReviewSignal[] = [];
+    let totalUsage: LlmUsage | undefined;
+
+    for (const file of diff.files) {
+      // Skip empty or trivial patches
+      if (!file.patch || file.patch.length < 40) {
+        continue;
+      }
+
+      // skip binary/non code files
+      if (
+        file.path.endsWith(".png") ||
+        file.path.endsWith(".jpg") ||
+        file.path.endsWith(".svg") ||
+        file.path.endsWith(".lock")
+      ) {
+        continue;
+      }
+
+      eventBus.emit(CoreEvents.WorkflowReviewFileStarted, {
+        file: file.path,
+      });
+      const fileDiff = {
+        files: [file],
+      };
+      const prompt = buildReviewPrompt({
+        diff: fileDiff,
+        context: contextText,
+        ...(metadata ?? {}),
+      });
+
+      eventBus.emit(CoreEvents.WorkflowReviewPromptBuilt, {
+        model: config.llm.model,
+        provider: config.llm.provider,
+        promptChars: JSON.stringify(prompt).length,
+        preview: JSON.stringify(prompt).slice(0, 2000),
+      });
+      eventBus.emit(CoreEvents.WorkflowReviewLlmRequestStarted);
+
+      const start = Date.now();
+
+      const response = await llmClient.generate({ prompt });
+
+      eventBus.emit(CoreEvents.WorkflowReviewLlmResponseReceived, {
+        outputChars: response.text.length,
+        usage: response.usage,
+        durationMs: Date.now() - start,
+      });
+      eventBus.emit(CoreEvents.WorkflowReviewLlmRawResponse, {
+        preview: response.text.slice(0, 1000),
+        fullLength: response.text.length,
+      });
+
+      if (response.usage) {
+        if (!totalUsage) {
+          totalUsage = { ...response.usage };
+        } else {
+          totalUsage.promptTokens += response.usage.promptTokens;
+          totalUsage.completionTokens += response.usage.completionTokens;
+          totalUsage.totalTokens += response.usage.totalTokens;
+        }
+      }
+
+      const cleaned = extractJson(response.text);
+      const trimmed = cleaned.trim();
+      if (!(trimmed.endsWith("}") || trimmed.endsWith("]}"))) {
+        throw new Error("LLM response truncated");
+      }
+
+      let parsed: any;
+
+      try {
+        parsed = JSON.parse(cleaned);
+      } catch {
+        eventBus.emit(CoreEvents.WorkflowReviewInvalidJson, {
+          rawResponsePreview: response.text.slice(0, 2000),
+        });
+        throw new Error("LLM returned invalid JSON");
+      }
+      let validated: ReturnType<typeof validateReviewOutput>;
+
+      try {
+        validated = validateReviewOutput(parsed);
+      } catch {
+        const correctionPrompt = `
+The previous output did not match the required schema.
+
+Convert the following into valid JSON matching this schema:
+
+{
+  "signals": [
+    {
+      "type": "bug" | "risk" | "test" | "style",
+      "severity": "low" | "medium" | "high",
+      "confidence": number,
+      "file": string,
+      "lineStart": number | null,
+      "lineEnd": number | null,
+      "message": string,
+      "rationale": string | null,
+      "suggestedFix": string | null
+    }
+  ]
+}
+
+Output only valid JSON.
+
+Previous output:
+${cleaned}
+`;
+
+        const retry = await llmClient.generate({
+          prompt: {
+            system: "You are correcting malformed JSON output.",
+            user: correctionPrompt,
+          },
+        });
+
+        const retryCleaned = extractJson(retry.text);
+        parsed = JSON.parse(retryCleaned);
+        validated = validateReviewOutput(parsed);
+      }
+
+      allSignals.push(...validated.signals);
+    }
+
+    // -------------------------------------------------
+    // Normalize + filter signals
+    // -------------------------------------------------
+
+    const rawSignals = allSignals;
+
+    const normalized = rawSignals
+      .map(normalizeSignal)
+      .filter((s): s is ReviewSignal => s != null);
+
+    const thresholded = normalized.filter(
+      (s) => s.confidence >= config.review.confidenceThreshold,
+    );
+
+    const signals = dedupeSignals(thresholded);
+
+    eventBus.emit(CoreEvents.SignalCompiled, {
+      count: signals.length,
+    });
+
+    eventBus.emit(CoreEvents.WorkflowReviewFinished);
+
+    if (totalUsage) {
+      return {
+        outcome: "success",
+        payload: { signals, usage: totalUsage },
+      };
+    }
+    return {
+      outcome: "success",
+      payload: { signals },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    eventBus.emit(CoreEvents.WorkflowReviewFailed, {
+      error: message,
+    });
+
+    return {
+      outcome: "failure",
+      payload: { signals: [] },
+    };
+  }
+}

package/src/review/types.ts

@@ -0,0 +1,18 @@
+// packages/workflows/src/review/types.ts
+
+import type { ReviewSignal, RetrievedContext } from "@prsense/core";
+import type { LlmUsage } from "@prsense/llm";
+import { WorkflowResult } from "../types/core.js";
+
+export type ReviewPayload = {
+  signals: ReviewSignal[];
+  usage?: LlmUsage;
+};
+
+export type ReviewWorkflowResult = WorkflowResult<ReviewPayload>;
+
+export type RetrievalWorkflowResult = {
+  outcome: "success" | "failure";
+  payload?: RetrievedContext;
+  error?: string;
+};

package/src/review/validateReviewOutput.ts

@@ -0,0 +1,13 @@
+export function validateReviewOutput(parsed: any): {
+  signals: any[];
+} {
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Review output must be an object");
+  }
+
+  if (!Array.isArray(parsed.signals)) {
+    throw new Error("Review output missing 'signals' array");
+  }
+
+  return parsed;
+}

package/src/setup/setupWorkflow.ts

@@ -0,0 +1,110 @@
+// packages/workflows/src/setup/runSetupWorkflow.ts
+import type { Capability, CapabilityContext } from "@prsense/preflight";
+import type { EventBus } from "@prsense/core";
+import { CoreEvents } from "@prsense/core";
+
+import type { SetupWorkflowResult, SetupStepResult } from "./types.js";
+
+export async function runSetupWorkflow({
+  capabilities,
+  ctx,
+  eventBus,
+}: {
+  capabilities: Capability[];
+  ctx: CapabilityContext;
+  eventBus: EventBus;
+}): Promise<SetupWorkflowResult> {
+  eventBus.emit(CoreEvents.WorkflowSetupStarted);
+
+  const steps: SetupStepResult[] = [];
+
+  for (const cap of capabilities) {
+    eventBus.emit(CoreEvents.CapabilityCheckStarted, {
+      capability: cap.id,
+    });
+
+    const status = await cap.check(ctx);
+
+    eventBus.emit(CoreEvents.CapabilityCheckFinished, {
+      capability: cap.id,
+      status: status.kind,
+    });
+
+    // 1️⃣ Not applicable → skip silently
+    if (status.kind === "non-applicable") {
+      steps.push({ id: cap.id, outcome: "skipped" });
+      continue;
+    }
+
+    // 2️⃣ Already ready → skip
+    if (status.kind === "ready") {
+      steps.push({ id: cap.id, outcome: "skipped" });
+      continue;
+    }
+
+    // 3️⃣ Partial → never auto-fix
+    if (status.kind === "partial") {
+      steps.push({
+        id: cap.id,
+        outcome: "failed",
+        error: status.reason,
+      });
+      break;
+    }
+
+    // 4️⃣ Missing → attempt apply if possible
+    if (status.kind === "missing") {
+      if (!cap.apply) {
+        steps.push({
+          id: cap.id,
+          outcome: "failed",
+          error: status.reason,
+        });
+        break;
+      }
+
+      eventBus.emit(CoreEvents.TaskStarted, {
+        taskId: `setup.${cap.id}`,
+        label: `Setting up ${cap.description}`,
+      });
+
+      try {
+        await cap.apply(ctx);
+
+        eventBus.emit(CoreEvents.TaskSucceeded, {
+          taskId: `setup.${cap.id}`,
+        });
+
+        steps.push({
+          id: cap.id,
+          outcome: "applied",
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+
+        eventBus.emit(CoreEvents.TaskFailed, {
+          taskId: `setup.${cap.id}`,
+          error: message,
+        });
+
+        steps.push({
+          id: cap.id,
+          outcome: "failed",
+          error: message,
+        });
+        break;
+      }
+    }
+  }
+
+  const failed = steps.some((s) => s.outcome === "failed");
+
+  eventBus.emit(CoreEvents.WorkflowSetupFinished, {
+    outcome: failed ? "failure" : "success",
+  });
+
+  return {
+    outcome: failed ? "failure" : "success",
+    steps,
+  };
+}

package/src/setup/types.ts

@@ -0,0 +1,9 @@
+export type SetupStepResult =
+  | { id: string; outcome: "skipped" }
+  | { id: string; outcome: "applied" }
+  | { id: string; outcome: "failed"; error: string };
+
+export type SetupWorkflowResult = {
+  outcome: "success" | "failure";
+  steps: SetupStepResult[];
+};

package/src/types/core.ts

@@ -0,0 +1,18 @@
+/**
+ * High-level outcome of a workflow.
+ * This is NOT presentation and NOT process exit.
+ */
+export type WorkflowOutcome = "success" | "failure";
+
+/**
+ * Base shape returned by all workflows.
+ */
+export type WorkflowResult<TPayload> = {
+  outcome: WorkflowOutcome;
+
+  /**
+   * Structured payload produced by the workflow.
+   * Interpretation is workflow-specific.
+   */
+  payload: TPayload;
+};

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+
+    "composite": true,
+    "tsBuildInfoFile": "tsconfig.tsbuildinfo"
+  },
+  "include": ["src"]
+}