ai-inference-stepper 1.0.0

package/src/utils/redaction.ts

@@ -0,0 +1,50 @@
+/**
+ * Redact sensitive information from text before sending to AI providers
+ */
+export function redactSecrets(text: string): string {
+  if (!text) return text;
+
+  let redacted = text;
+
+  // AWS access keys
+  redacted = redacted.replace(/(A?KIA|AKIA)[A-Z0-9]{16}/g, '[REDACTED_AWS_KEY]');
+
+  // Generic API keys and tokens (common patterns)
+  redacted = redacted.replace(/[a-zA-Z0-9_-]{32,}/g, (match) => {
+    // Don't redact commit SHAs (typically 40 chars) or very long base64
+    if (match.length === 40 || match.length > 200) return match;
+    return '[REDACTED_TOKEN]';
+  });
+
+  // Password/secret assignments in env-style
+  redacted = redacted.replace(
+    /(password|passwd|secret|api_key|apikey|token|auth)(\s*[:=]\s*)(\S+)/gi,
+    '$1$2[REDACTED]'
+  );
+
+  // Email addresses
+  redacted = redacted.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[REDACTED_EMAIL]');
+
+  // Base64 encoded secrets (long base64 strings)
+  redacted = redacted.replace(/[A-Za-z0-9+/]{100,}={0,2}/g, '[REDACTED_BASE64]');
+
+  return redacted;
+}
+
+/**
+ * Redact sensitive fields from an object
+ */
+export function redactObject<T extends Record<string, unknown>>(obj: T): T {
+  const result: Record<string, unknown> = { ...obj };
+  const sensitiveKeys = ['apiKey', 'api_key', 'token', 'password', 'secret', 'authorization'];
+
+  for (const key of Object.keys(result)) {
+    if (sensitiveKeys.includes(key.toLowerCase())) {
+      result[key] = '[REDACTED]';
+    } else if (typeof result[key] === 'string') {
+      result[key] = redactSecrets(result[key] as string);
+    }
+  }
+
+  return result as T;
+}

package/src/utils/safeRequest.ts

@@ -0,0 +1,140 @@
+import axios, { AxiosError, AxiosRequestConfig, AxiosResponse } from 'axios';
+import { logger } from '../logging.js';
+
+export interface SafeRequestOptions extends AxiosRequestConfig {
+  timeout?: number;
+  retryAfterHeader?: boolean;
+}
+
+export interface SafeRequestResult<T = unknown> {
+  data: T;
+  status: number;
+  headers: Record<string, string>;
+  retryAfter?: number;
+}
+
+export class RequestError extends Error {
+  constructor(
+    message: string,
+    public status?: number,
+    public code?: string,
+    public retryAfter?: number
+  ) {
+    super(message);
+    this.name = 'RequestError';
+  }
+}
+
+/**
+ * Make an HTTP request with timeout and retry-after header parsing
+ */
+export async function safeRequest<T = unknown>(
+  url: string,
+  options: SafeRequestOptions = {}
+): Promise<SafeRequestResult<T>> {
+  const timeout = options.timeout || 15000;
+
+  try {
+    const response: AxiosResponse<T> = await axios({
+      ...options,
+      url,
+      timeout,
+      validateStatus: (status) => status < 600, // Don't throw on any status
+    });
+
+    // Parse Retry-After header if present
+    let retryAfter: number | undefined;
+    const retryAfterHeader = response.headers['retry-after'];
+    if (retryAfterHeader) {
+      const parsed = parseInt(retryAfterHeader, 10);
+      retryAfter = isNaN(parsed) ? undefined : parsed;
+    }
+
+    // Throw on error statuses
+    if (response.status >= 400) {
+      throw new RequestError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        response.status,
+        `HTTP_${response.status}`,
+        retryAfter
+      );
+    }
+
+    return {
+      data: response.data,
+      status: response.status,
+      headers: response.headers as Record<string, string>,
+      retryAfter,
+    };
+  } catch (error) {
+    if (error instanceof RequestError) {
+      throw error;
+    }
+
+    if (axios.isAxiosError(error)) {
+      const axiosError = error as AxiosError;
+
+      // Timeout
+      if (axiosError.code === 'ECONNABORTED' || axiosError.code === 'ETIMEDOUT') {
+        throw new RequestError('Request timeout', 408, 'TIMEOUT');
+      }
+
+      // Network errors
+      if (axiosError.code === 'ENOTFOUND' || axiosError.code === 'ECONNREFUSED') {
+        throw new RequestError('Network error', 503, 'NETWORK_ERROR');
+      }
+
+      // Parse response error
+      const status = axiosError.response?.status;
+      const retryAfter = axiosError.response?.headers['retry-after']
+        ? parseInt(axiosError.response.headers['retry-after'], 10)
+        : undefined;
+
+      throw new RequestError(
+        axiosError.message,
+        status,
+        status ? `HTTP_${status}` : 'UNKNOWN',
+        retryAfter
+      );
+    }
+
+    logger.error({ error }, 'Unexpected request error');
+    throw new RequestError('Unexpected error', undefined, 'UNKNOWN');
+  }
+}
+
+/**
+ * Parse error and extract retry-after information
+ */
+export function parseRetryAfter(error: unknown): number | undefined {
+  if (error instanceof RequestError && error.retryAfter) {
+    return error.retryAfter;
+  }
+  return undefined;
+}
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (!(error instanceof RequestError)) return false;
+
+  const retryableCodes = [408, 429, 500, 502, 503, 504];
+  return error.status ? retryableCodes.includes(error.status) : false;
+}
+
+/**
+ * Check if error is auth-related
+ */
+export function isAuthError(error: unknown): boolean {
+  if (!(error instanceof RequestError)) return false;
+  return error.status === 401 || error.status === 403;
+}
+
+/**
+ * Check if error is rate limit
+ */
+export function isRateLimitError(error: unknown): boolean {
+  if (!(error instanceof RequestError)) return false;
+  return error.status === 429;
+}

package/src/validation/README.md

@@ -0,0 +1,25 @@
+# ✅ Validation & Schemas
+
+AI models are non-deterministic; they can sometimes return malformed JSON or skip required fields. This module ensures that every report returned by the **Inference Stepper** follows a strict, predictable format.
+
+## 🎯 Purpose
+
+- **Reliability**: Guarantees the API always returns data that matches the frontend's expectations.
+- **Data Integrity**: Uses **Zod** to validate types and string lengths.
+- **Fail-fast**: If an AI returns bad data, we catch it early and try a different provider.
+
+## 📋 The Report Schema
+
+Every report must contain:
+
+- `title`: A concise summary of the change.
+- `summary`: A detailed explanation.
+- `changes`: A list of specific file/logic modifications.
+- `rationale`: Why the change was made.
+- `impact_and_tests`: What was affected and how it was verified.
+- `next_steps`: Future tasks or related work.
+- `tags`: Keywords for categorization.
+
+## 🛠️ Usage
+
+This module is used by every provider adapter. After the AI returns a string, the adapter calls `parseAndValidateReport()` to transform that string into a validated object.

package/src/validation/report.schema.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { ReportOutput } from '../types.js';
+
+/**
+ * Comprehensive Zod schema for validating AI-generated report output
+ * with detailed error messages
+ */
+export const ReportOutputSchema = z.object({
+  title: z.string()
+    .min(10, 'Title must be at least 10 characters')
+    .max(120, 'Title must not exceed 120 characters')
+    .refine(
+      (val) => val.trim().length > 0,
+      'Title cannot be empty or whitespace only'
+    ),
+
+  summary: z.string()
+    .min(50, 'Summary must be at least 50 characters')
+    .max(2000, 'Summary must not exceed 2000 characters'),
+
+  changes: z.array(z.string().min(5, 'Each change must be at least 5 characters'))
+    .min(1, 'At least one change must be listed')
+    .max(50, 'Maximum 50 changes allowed'),
+
+  rationale: z.string()
+    .min(20, 'Rationale must be at least 20 characters')
+    .max(2000, 'Rationale must not exceed 2000 characters'),
+
+  impact_and_tests: z.string()
+    .min(20, 'Impact and tests section must be at least 20 characters')
+    .max(2000, 'Impact and tests section must not exceed 2000 characters'),
+
+  next_steps: z.array(z.string().min(5, 'Each next step must be at least 5 characters'))
+    .max(20, 'Maximum 20 next steps allowed'),
+
+  tags: z.string()
+    .max(200, 'Tags must not exceed 200 characters')
+    .refine(
+      (val) => val.split(',').every(tag => tag.trim().length > 0),
+      'Tags must be comma-separated with no empty values'
+    ),
+});
+
+/**
+ * Validate report output against schema
+ */
+export function validateReportOutput(data: unknown): {
+  valid: boolean;
+  result?: ReportOutput;
+  error?: string;
+} {
+  try {
+    const validated = ReportOutputSchema.parse(data);
+    return { valid: true, result: validated as ReportOutput };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        valid: false,
+        error: error.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join('; '),
+      };
+    }
+    return { valid: false, error: 'Unknown validation error' };
+  }
+}
+
+/**
+ * Safely parse JSON and validate
+ */
+export function parseAndValidateReport(jsonString: string): {
+  valid: boolean;
+  result?: ReportOutput;
+  error?: string;
+} {
+  try {
+    // Clean up common AI model output issues
+    let cleaned = jsonString.trim();
+
+    // Remove markdown code blocks if present
+    cleaned = cleaned.replace(/^```json\s*/i, '').replace(/```\s*$/, '');
+    cleaned = cleaned.replace(/^```\s*/i, '').replace(/```\s*$/, '');
+
+    // Remove any leading/trailing text that isn't JSON
+    const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      cleaned = jsonMatch[0];
+    }
+
+    const parsed = JSON.parse(cleaned);
+    return validateReportOutput(parsed);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return { valid: false, error: `Invalid JSON: ${error.message}` };
+    }
+    return { valid: false, error: 'Failed to parse JSON' };
+  }
+}

package/src/webhooks/delivery.ts

@@ -0,0 +1,162 @@
+// packages/stepper/src/webhooks/delivery.ts
+
+import crypto from 'crypto';
+import { logger, createChildLogger } from '../logging.js';
+
+export interface WebhookPayload {
+    jobId: string;
+    status: 'completed' | 'failed';
+    result?: unknown;
+    error?: string;
+    timestamp: number;
+}
+
+export interface WebhookConfig {
+    url: string;
+    secret: string;
+    maxRetries?: number;
+    retryDelayMs?: number;
+}
+
+/**
+ * Generate HMAC-SHA256 signature for webhook payload
+ */
+function generateSignature(payload: string, secret: string): string {
+    return crypto
+        .createHmac('sha256', secret)
+        .update(payload)
+        .digest('hex');
+}
+
+/**
+ * Send webhook notification with bearer token + HMAC signature
+ * Implements retry logic for failed deliveries
+ */
+export async function sendWebhook(
+    config: WebhookConfig,
+    payload: WebhookPayload,
+    attempt: number = 1
+): Promise<{ success: boolean; statusCode?: number; error?: string }> {
+    const log = createChildLogger({ jobId: payload.jobId, webhookAttempt: attempt });
+
+    const maxRetries = config.maxRetries || 3;
+    const retryDelayMs = config.retryDelayMs || 5000;
+
+    try {
+        const payloadString = JSON.stringify(payload);
+        const signature = generateSignature(payloadString, config.secret);
+
+        log.info({ url: config.url, attempt, maxRetries }, 'Sending webhook');
+
+        const response = await fetch(config.url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${config.secret}`,
+                'X-Webhook-Signature': signature,
+                'X-Webhook-Timestamp': payload.timestamp.toString(),
+                'User-Agent': 'Stepper/1.0'
+            },
+            body: payloadString,
+            signal: AbortSignal.timeout(10000) // 10s timeout
+        });
+
+        if (response.ok) {
+            log.info({ statusCode: response.status }, 'Webhook delivered successfully');
+            return { success: true, statusCode: response.status };
+        }
+
+        // Non-OK response
+        const errorBody = await response.text().catch(() => 'Unable to read response');
+        log.warn({ statusCode: response.status, errorBody }, 'Webhook delivery failed with non-OK status');
+
+        // Retry on 5xx errors or specific 4xx errors
+        const shouldRetry = response.status >= 500 || response.status === 408 || response.status === 429;
+
+        if (shouldRetry && attempt < maxRetries) {
+            log.info({ nextAttempt: attempt + 1, delayMs: retryDelayMs }, 'Retrying webhook delivery');
+            await new Promise(resolve => setTimeout(resolve, retryDelayMs * attempt)); // Exponential backoff
+            return sendWebhook(config, payload, attempt + 1);
+        }
+
+        return {
+            success: false,
+            statusCode: response.status,
+            error: `HTTP ${response.status}: ${errorBody.substring(0, 200)}`
+        };
+
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error({ error: errorMessage, attempt }, 'Webhook delivery error');
+
+        // Retry on network errors
+        if (attempt < maxRetries) {
+            log.info({ nextAttempt: attempt + 1, delayMs: retryDelayMs }, 'Retrying webhook after error');
+            await new Promise(resolve => setTimeout(resolve, retryDelayMs * attempt));
+            return sendWebhook(config, payload, attempt + 1);
+        }
+
+        return {
+            success: false,
+            error: `Network error after ${maxRetries} attempts: ${errorMessage}`
+        };
+    }
+}
+
+/**
+ * Send success webhook notification
+ */
+export async function notifyWebhookSuccess(
+    webhookUrl: string,
+    webhookSecret: string,
+    jobId: string,
+    result: unknown
+): Promise<void> {
+    const payload: WebhookPayload = {
+        jobId,
+        status: 'completed',
+        result,
+        timestamp: Date.now()
+    };
+
+    const webhookResult = await sendWebhook(
+        { url: webhookUrl, secret: webhookSecret },
+        payload
+    );
+
+    if (!webhookResult.success) {
+        logger.warn(
+            { jobId, error: webhookResult.error },
+            'Webhook delivery failed after all retries - job completed but notification not delivered'
+        );
+    }
+}
+
+/**
+ * Send failure webhook notification
+ */
+export async function notifyWebhookFailure(
+    webhookUrl: string,
+    webhookSecret: string,
+    jobId: string,
+    error: string
+): Promise<void> {
+    const payload: WebhookPayload = {
+        jobId,
+        status: 'failed',
+        error,
+        timestamp: Date.now()
+    };
+
+    const webhookResult = await sendWebhook(
+        { url: webhookUrl, secret: webhookSecret },
+        payload
+    );
+
+    if (!webhookResult.success) {
+        logger.warn(
+            { jobId, error: webhookResult.error },
+            'Failure webhook delivery failed - job failed and notification not delivered'
+        );
+    }
+}

package/tests/integration/full-flow.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { enqueueReport, generateReport, deleteReport, registerCallbacks } from '../../src/index.js';
+import { initializeProviders } from '../../src/stepper/orchestrator.js';
+import { PromptInput, StepperCallbacks } from '../../src/types.js';
+
+// Mock provider adapter for controlled testing
+const mockProviderCall = vi.fn();
+
+vi.mock('../../src/providers/hfSpace.adapter.js', () => ({
+    HuggingFaceSpaceAdapter: class {
+        name = 'hf-space';
+        async call(_input: PromptInput) {
+            return mockProviderCall();
+        }
+    },
+}));
+
+// Mock Redis operations
+vi.mock('../../src/cache/redisCache.js', async () => {
+    const actual = await vi.importActual<typeof import('../../src/cache/redisCache.js')>('../../src/cache/redisCache.js');
+    const cache = new Map<string, any>();
+
+    return {
+        ...actual,
+        getReportCache: vi.fn(async (key: string) => cache.get(key) ?? null),
+        setDehydrated: vi.fn(async (key: string, jobId: string) => {
+            cache.set(key, { status: 'dehydrated', jobId });
+        }),
+        setHydrated: vi.fn(async (key: string, result: any) => {
+            cache.set(key, {
+                status: 'hydrated',
+                result,
+                timestamps: { created: new Date().toISOString(), updated: new Date().toISOString() }
+            });
+        }),
+        deleteCacheEntry: vi.fn(async (key: string) => {
+            cache.delete(key);
+        }),
+        isHydratedFresh: vi.fn(() => true),
+        isStaleButUsable: vi.fn(() => false),
+        buildCacheKey: actual.buildCacheKey,
+    };
+});
+
+// Mock queue operations
+vi.mock('../../src/queue/producer.js', () => ({
+    enqueueReportJob: vi.fn(async () => 'mock-job-id'),
+    getJobStatus: vi.fn(async () => null),
+}));
+
+describe('Full Report Generation Flow', () => {
+    const testInput: PromptInput = {
+        userId: 'integration-test-user',
+        commitSha: 'int123abc',
+        repo: 'test/integration-repo',
+        message: 'Integration test commit message',
+        files: ['src/app.ts', 'src/utils.ts'],
+        components: ['app', 'utils'],
+        diffSummary: '+ added new feature\n- removed deprecated code',
+    };
+
+    const mockReport = {
+        title: 'Integration Test Report',
+        summary: 'This is a test report generated during integration testing',
+        changes: ['Added new feature', 'Removed deprecated code'],
+        rationale: 'To improve code quality and add requested functionality',
+        impact_and_tests: 'Medium impact, unit tests added',
+        next_steps: ['Review PR', 'Deploy to staging'],
+        tags: 'feature, cleanup',
+    };
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+
+        // Initialize providers with test config
+        initializeProviders([
+            {
+                name: 'hf-space',
+                enabled: true,
+                baseUrl: 'http://test.local',
+                rateLimitRPS: 10,
+                concurrency: 1,
+                timeout: 5000,
+            },
+        ]);
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe('generateReport (synchronous)', () => {
+        it('should generate report end-to-end with provider', async () => {
+            mockProviderCall.mockResolvedValueOnce(mockReport);
+
+            const result = await generateReport(testInput);
+
+            expect(result.result).toBeDefined();
+            expect(result.result.title).toBe('Integration Test Report');
+            expect(result.result.summary).toBeTruthy();
+            expect(result.usedProvider).toBe('hf-space');
+            expect(result.fallback).toBe(false);
+            expect(result.timings).toBeDefined();
+            expect(result.timings.totalMs).toBeGreaterThanOrEqual(0);
+        });
+
+        it('should invoke all lifecycle callbacks in correct order', async () => {
+            const callOrder: string[] = [];
+
+            const callbacks: StepperCallbacks = {
+                onStart: vi.fn(() => { callOrder.push('start'); }),
+                onProviderAttempt: vi.fn(() => { callOrder.push('attempt'); }),
+                onSuccess: vi.fn(() => { callOrder.push('success'); }),
+                onFallback: vi.fn(() => { callOrder.push('fallback'); }),
+            };
+
+            registerCallbacks(callbacks);
+            mockProviderCall.mockResolvedValueOnce(mockReport);
+
+            await generateReport(testInput);
+
+            expect(callOrder).toEqual(['start', 'attempt', 'success']);
+            expect(callbacks.onStart).toHaveBeenCalledTimes(1);
+            expect(callbacks.onProviderAttempt).toHaveBeenCalledTimes(1);
+            expect(callbacks.onSuccess).toHaveBeenCalledTimes(1);
+            expect(callbacks.onFallback).not.toHaveBeenCalled();
+        });
+
+        it('should fallback when all providers fail', async () => {
+            mockProviderCall.mockRejectedValueOnce(new Error('Provider unavailable'));
+
+            const result = await generateReport(testInput);
+
+            expect(result.fallback).toBe(true);
+            expect(result.usedProvider).toBe('fallback');
+            expect(result.result).toBeDefined();
+            // Fallback should still produce a valid report structure
+            expect(result.result.title).toBeTruthy();
+            expect(result.result.summary).toBeTruthy();
+        });
+    });
+
+    describe('enqueueReport (asynchronous)', () => {
+        it('should enqueue job on cache miss', async () => {
+            const result = await enqueueReport(testInput);
+
+            // On cache miss, should return 202 with jobId
+            expect(result.status).toBe(202);
+            if (result.status === 202) {
+                expect(result.jobId).toBeDefined();
+                expect(result.cached).toBe(false);
+            }
+        });
+    });
+
+    describe('deleteReport', () => {
+        it('should not throw when deleting non-existent report', async () => {
+            await expect(
+                deleteReport('non-existent-user', 'non-existent-sha')
+            ).resolves.not.toThrow();
+        });
+    });
+
+    describe('Error handling', () => {
+        it('should handle provider timeout gracefully', async () => {
+            mockProviderCall.mockImplementationOnce(() =>
+                new Promise((_, reject) =>
+                    setTimeout(() => reject(new Error('Timeout')), 100)
+                )
+            );
+
+            const result = await generateReport(testInput);
+
+            // Should fallback on timeout
+            expect(result.fallback).toBe(true);
+            expect(result.providersAttempted.length).toBeGreaterThan(0);
+        });
+
+        it('should track all provider attempts in metadata', async () => {
+            mockProviderCall.mockRejectedValueOnce(new Error('First failure'));
+
+            const result = await generateReport(testInput);
+
+            expect(result.providersAttempted).toBeDefined();
+            expect(result.providersAttempted.length).toBeGreaterThan(0);
+
+            const attempt = result.providersAttempted[0];
+            expect(attempt.provider).toBe('hf-space');
+            expect(attempt.error).toBeDefined();
+        });
+    });
+});