ai-inference-stepper 1.0.0

package/dist/config.js

@@ -0,0 +1,251 @@
+/**
+ * Load configuration from environment variables with sensible defaults.
+ * This is the central brain for all timing, retry, and safety-switch logic.
+ */
+/**
+ * Load provider configurations from environment
+ */
+function loadProviderConfigs() {
+    const providers = [];
+    // Helper to add provider config
+    const addProvider = (name, envPrefix) => {
+        const enabled = process.env[`${envPrefix}_ENABLED`] === 'true';
+        if (enabled) {
+            providers.push({
+                name,
+                apiKey: process.env[`${envPrefix}_API_KEY`],
+                baseUrl: process.env[`${envPrefix}_BASE_URL`],
+                modelName: process.env[`${envPrefix}_MODEL`],
+                timeout: parseInt(process.env[`${envPrefix}_TIMEOUT`] || '15000', 10),
+                rateLimitRPS: parseInt(process.env[`${envPrefix}_RPS`] || '5', 10),
+                concurrency: parseInt(process.env[`${envPrefix}_CONCURRENCY`] || '2', 10),
+                enabled: true,
+            });
+        }
+    };
+    // Special case: HuggingFace Space
+    if (process.env.HF_SPACE_ENABLED === 'true') {
+        providers.push({
+            name: 'hf-space',
+            baseUrl: process.env.HF_SPACE_URL,
+            apiKey: process.env.HF_SPACE_API_KEY,
+            timeout: parseInt(process.env.HF_SPACE_TIMEOUT || '30000', 10),
+            rateLimitRPS: parseInt(process.env.HF_SPACE_RPS || '3', 10),
+            concurrency: parseInt(process.env.HF_SPACE_CONCURRENCY || '1', 10),
+            enabled: true,
+        });
+    }
+    // Add all other providers
+    addProvider('gemini', 'GEMINI');
+    addProvider('openai', 'OPENAI');
+    addProvider('anthropic', 'ANTHROPIC');
+    addProvider('cohere', 'COHERE');
+    addProvider('deepseek', 'DEEPSEEK');
+    addProvider('groq', 'GROQ');
+    addProvider('openrouter', 'OPENROUTER');
+    addProvider('mistral', 'MISTRAL');
+    addProvider('perplexity', 'PERPLEXITY');
+    addProvider('together', 'TOGETHER');
+    return providers;
+}
+export function loadConfig() {
+    const redisUrl = process.env.REDIS_URL || 'redis://localhost:6379';
+    // Provider configurations: Rules for how we talk to each AI
+    const providers = [
+        {
+            name: 'hf-space',
+            enabled: process.env.HF_SPACE_ENABLED === 'true',
+            baseUrl: process.env.HF_SPACE_URL || 'https://your-space.hf.space',
+            apiKeyEnvVar: 'HF_SPACE_API_KEY',
+            // RPM (Requests Per Minute): We allow 5 requests every 60 seconds (one every 12 seconds)
+            // high RPM leads to "429 Too Many Requests" errors.
+            rateLimitRPM: parseInt(process.env.HF_SPACE_RPM || '5', 10),
+            // Concurrency: Max 2 active conversations at once. Prevents overloading the AI slot.
+            concurrency: parseInt(process.env.HF_SPACE_CONCURRENCY || '2', 10),
+            // Timeout: Give the AI 1 minute to think before we give up and try another provider.
+            timeout: parseInt(process.env.HF_SPACE_TIMEOUT || '60000', 10),
+        },
+        {
+            name: 'gemini',
+            enabled: process.env.GEMINI_ENABLED === 'true',
+            baseUrl: process.env.GEMINI_BASE_URL || 'https://generativelanguage.googleapis.com/v1',
+            modelName: process.env.GEMINI_MODEL || 'gemini-pro',
+            apiKeyEnvVar: 'GEMINI_API_KEY',
+            rateLimitRPM: parseInt(process.env.GEMINI_RPM || '5', 10),
+            concurrency: parseInt(process.env.GEMINI_CONCURRENCY || '2', 10),
+            timeout: parseInt(process.env.GEMINI_TIMEOUT || '60000', 10),
+        },
+        {
+            name: 'cohere',
+            enabled: process.env.COHERE_ENABLED === 'true',
+            baseUrl: process.env.COHERE_BASE_URL || 'https://api.cohere.ai/v1',
+            modelName: process.env.COHERE_MODEL || 'command',
+            apiKeyEnvVar: 'COHERE_API_KEY',
+            rateLimitRPM: parseInt(process.env.COHERE_RPM || '5', 10),
+            concurrency: parseInt(process.env.COHERE_CONCURRENCY || '2', 10),
+            timeout: parseInt(process.env.COHERE_TIMEOUT || '60000', 10),
+        },
+    ];
+    // Filter enabled providers and enforce order
+    const staticProviders = providers.filter((p) => p.enabled);
+    const dynamicProviders = loadProviderConfigs();
+    // Combine, preferring static if name conflicts
+    const allProviders = [...staticProviders];
+    for (const dp of dynamicProviders) {
+        if (!allProviders.some(sp => sp.name === dp.name)) {
+            allProviders.push(dp);
+        }
+    }
+    return {
+        providers: allProviders,
+        fallback: {
+            enabled: process.env.FALLBACK_ENABLED !== 'false',
+        },
+        redis: {
+            url: redisUrl,
+            keyPrefix: process.env.REDIS_KEY_PREFIX || 'stepper:',
+        },
+        cache: {
+            // TTL: How long the report stays in the database (Default: 2 days)
+            ttlSeconds: parseInt(process.env.CACHE_TTL_SECONDS || '172800', 10),
+            // Stale Threshold: After 24 hours (or effectively never if TTL < 24h), we consider the data "old"
+            staleThresholdSeconds: parseInt(process.env.CACHE_STALE_THRESHOLD || '86400', 10),
+            enableStaleWhileRevalidate: process.env.CACHE_STALE_WHILE_REVALIDATE !== 'false',
+        },
+        queue: {
+            name: process.env.QUEUE_NAME || 'report-generation',
+            // How many total background jobs we run across all providers
+            concurrency: parseInt(process.env.QUEUE_CONCURRENCY || '5', 10),
+        },
+        webhook: {
+            enabled: process.env.WEBHOOK_ENABLED !== 'false', // Enabled by default
+            secret: process.env.WEBHOOK_SECRET || '',
+            maxRetries: parseInt(process.env.WEBHOOK_MAX_RETRIES || '3', 10),
+            retryDelayMs: parseInt(process.env.WEBHOOK_RETRY_DELAY_MS || '5000', 10),
+        },
+        retry: {
+            // Max Attempts: Try a single provider 3 times before moving to the next one.
+            maxAttemptsPerProvider: parseInt(process.env.RETRY_MAX_ATTEMPTS || '3', 10),
+            // Base Delay: After a simple error (like network), wait 40 seconds before retrying.
+            baseDelayMs: parseInt(process.env.RETRY_BASE_DELAY_MS || '40000', 10),
+            // Jitter: Random +/- 10 seconds to prevent multiple retries hitting at once.
+            maxJitterMs: parseInt(process.env.RETRY_MAX_JITTER_MS || '10000', 10),
+            // Rate Limit Fallback: If AI says "Busy" but doesn't say for how long, wait ~2 hours (extreme safety).
+            // Note: User set this to 5400 in .env which is ~90mins.
+            rateLimitFallbackSeconds: parseInt(process.env.RETRY_RATE_LIMIT_FALLBACK || '7200', 10),
+        },
+        circuit: {
+            // Failure Threshold: Kill the provider if 5 requests in a row fail.
+            failureThreshold: parseInt(process.env.CIRCUIT_FAILURE_THRESHOLD || '5', 10),
+            // Window: Only look at failures from the last 5 minutes.
+            windowSeconds: parseInt(process.env.CIRCUIT_WINDOW_SECONDS || '300', 10),
+            // Cooldown: After killing a provider, wait 5 minutes before trying it again.
+            cooldownSeconds: parseInt(process.env.CIRCUIT_COOLDOWN_SECONDS || '300', 10),
+        },
+        security: {
+            redactBeforeSend: process.env.REDACT_BEFORE_SEND !== 'false',
+            // CORS: Control which domains can access your API
+            cors: {
+                enabled: process.env.CORS_ENABLED !== 'false', // Enabled by default
+                allowedOrigins: process.env.CORS_ALLOWED_ORIGINS
+                    ? process.env.CORS_ALLOWED_ORIGINS.split(',').map(s => s.trim())
+                    : ['*'], // Default allows all; in production, specify your domains
+                allowCredentials: process.env.CORS_ALLOW_CREDENTIALS === 'true',
+            },
+            // Rate Limiting: Prevent abuse and DDoS
+            rateLimit: {
+                enabled: process.env.RATE_LIMIT_ENABLED !== 'false', // Enabled by default
+                windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS || '900000', 10), // 15 minutes default
+                maxRequests: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS || '100', 10), // 100 per window per IP
+                maxRequestsPerUser: parseInt(process.env.RATE_LIMIT_MAX_PER_USER || '50', 10), // 50 per window per userId
+                skipHealthEndpoints: process.env.RATE_LIMIT_SKIP_HEALTH !== 'false', // Skip /health & /metrics by default
+            },
+            // Helmet: Security headers (XSS, clickjacking, etc.)
+            helmet: {
+                enabled: process.env.HELMET_ENABLED !== 'false', // Enabled by default
+            },
+            // API Key: Simple authentication for API access
+            apiKey: {
+                enabled: process.env.API_KEY_ENABLED === 'true', // Disabled by default; opt-in
+                headerName: process.env.API_KEY_HEADER || 'x-api-key',
+                skipHealthEndpoints: process.env.API_KEY_SKIP_HEALTH !== 'false', // Skip auth for health/metrics
+            },
+        },
+        server: {
+            port: parseInt(process.env.PORT || '3001', 10),
+            metricsPort: process.env.METRICS_PORT ? parseInt(process.env.METRICS_PORT, 10) : undefined,
+        },
+    };
+}
+function mergeConfig(base, overrides) {
+    return {
+        ...base,
+        ...overrides,
+        providers: overrides.providers ?? base.providers,
+        providerConfigs: overrides.providerConfigs ?? base.providerConfigs,
+        redis: {
+            ...base.redis,
+            ...overrides.redis,
+        },
+        cache: {
+            ...base.cache,
+            ...overrides.cache,
+        },
+        queue: {
+            ...base.queue,
+            ...overrides.queue,
+        },
+        webhook: {
+            ...base.webhook,
+            ...overrides.webhook,
+        },
+        retry: {
+            ...base.retry,
+            ...overrides.retry,
+        },
+        circuit: {
+            ...base.circuit,
+            ...overrides.circuit,
+        },
+        security: {
+            ...base.security,
+            ...overrides.security,
+            cors: {
+                ...base.security.cors,
+                ...overrides.security?.cors,
+            },
+            rateLimit: {
+                ...base.security.rateLimit,
+                ...overrides.security?.rateLimit,
+            },
+            helmet: {
+                ...base.security.helmet,
+                ...overrides.security?.helmet,
+            },
+            apiKey: {
+                ...base.security.apiKey,
+                ...overrides.security?.apiKey,
+            },
+        },
+        server: {
+            ...base.server,
+            ...overrides.server,
+        },
+    };
+}
+export function createConfig(overrides) {
+    const base = loadConfig();
+    if (!overrides) {
+        return base;
+    }
+    return mergeConfig(base, overrides);
+}
+export let config = loadConfig();
+export function applyConfigOverrides(overrides) {
+    if (!overrides) {
+        return config;
+    }
+    config = mergeConfig(loadConfig(), overrides);
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/fallback/templateFallback.d.ts

@@ -0,0 +1,7 @@
+import { PromptInput, ReportOutput } from '../types.js';
+/**
+ * Generate a deterministic, template-based fallback report
+ * Used when all AI providers fail
+ */
+export declare function generateTemplateFallback(input: PromptInput): ReportOutput;
+//# sourceMappingURL=templateFallback.d.ts.map

package/dist/fallback/templateFallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateFallback.d.ts","sourceRoot":"","sources":["../../src/fallback/templateFallback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAyBzE"}

package/dist/fallback/templateFallback.js

@@ -0,0 +1,29 @@
+/**
+ * Generate a deterministic, template-based fallback report
+ * Used when all AI providers fail
+ */
+export function generateTemplateFallback(input) {
+    const { message, files, components, diffSummary, repo } = input;
+    // Extract basic info from commit message
+    const firstLine = message.split('\n')[0] || 'Code changes';
+    const fileCount = files.length;
+    const componentCount = components.length;
+    return {
+        title: `${firstLine.slice(0, 80)}`,
+        summary: `This commit modifies ${fileCount} file${fileCount !== 1 ? 's' : ''} in ${repo}. ` +
+            `The changes affect ${componentCount} component${componentCount !== 1 ? 's' : ''}. ` +
+            `Commit message: "${message.slice(0, 200)}${message.length > 200 ? '...' : ''}"`,
+        changes: files.slice(0, 10).map((f) => `Modified ${f}`),
+        rationale: `Automated fallback: Unable to generate AI-powered analysis. ` +
+            `Diff summary: ${diffSummary.slice(0, 300)}${diffSummary.length > 300 ? '...' : ''}`,
+        impact_and_tests: `Please review the changes manually. Ensure tests are updated for modified files: ${files.slice(0, 5).join(', ')}`,
+        next_steps: [
+            'Review changes manually',
+            'Run test suite',
+            'Verify component integration',
+            'Update documentation if needed',
+        ],
+        tags: components.slice(0, 5).join(', ') || 'general',
+    };
+}
+//# sourceMappingURL=templateFallback.js.map

package/dist/fallback/templateFallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateFallback.js","sourceRoot":"","sources":["../../src/fallback/templateFallback.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAkB;IACzD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAEhE,yCAAyC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC;IAC3D,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;IAC/B,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC;IAEzC,OAAO;QACL,KAAK,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;QAClC,OAAO,EAAE,wBAAwB,SAAS,QAAQ,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,IAAI;YACzF,sBAAsB,cAAc,aAAa,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI;YACpF,oBAAoB,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG;QAClF,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC;QACvD,SAAS,EAAE,8DAA8D;YACvE,iBAAiB,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,WAAW,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;QACtF,gBAAgB,EAAE,oFAAoF,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACpI,UAAU,EAAE;YACV,yBAAyB;YACzB,gBAAgB;YAChB,8BAA8B;YAC9B,gCAAgC;SACjC;QACD,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS;KACrD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+import { PromptInput, ReportOutput, ProviderResult, StepperCallbacks, StepperConfig, ProviderConfig } from './types.js';
+/**
+ * Initialize Stepper with optional config overrides.
+ * Useful for npm consumers who want programmatic config instead of env.
+ */
+export declare function initStepper(options?: {
+    config?: Partial<StepperConfig>;
+    providers?: ProviderConfig[];
+}): StepperConfig;
+/**
+ * Register lifecycle callbacks
+ *
+ * @example
+ * registerCallbacks({
+ *   onSuccess: (jobId, provider, result) => {
+ *     // handle success
+ *   },
+ *   onFallback: (jobId, result, meta) => {
+ *     // handle fallback
+ *   }
+ * });
+ */
+export declare function registerCallbacks(callbacks: StepperCallbacks): void;
+/**
+ * Enqueue a report generation job (async, non-blocking)
+ *
+ * Returns cached result immediately if available (fresh or stale),
+ * or enqueues job and returns 202 status with jobId.
+ *
+ * @param input - Commit information
+ * @returns Promise with either immediate result or job info
+ *
+ * @example
+ * const result = await enqueueReport({
+ *   userId: 'user_123',
+ *   commitSha: 'abc123',
+ *   repo: 'myorg/myrepo',
+ *   message: 'Fix bug in auth',
+ *   files: ['src/auth.ts'],
+ *   components: ['auth'],
+ *   diffSummary: '+ fixed token validation'
+ * });
+ *
+ * if (result.status === 200) {
+ *   // handle cached result
+ * } else {
+ *   // handle enqueued result
+ * }
+ */
+export declare function enqueueReport(input: PromptInput): Promise<{
+    status: 200;
+    data: ReportOutput;
+    cached: true;
+    stale?: boolean;
+} | {
+    status: 202;
+    jobId: string;
+    cached: false;
+}>;
+/**
+ * Generate report synchronously (blocking, immediate)
+ *
+ * Useful for testing or when you need the result immediately.
+ * This bypasses the queue and calls providers directly.
+ *
+ * @param input - Commit information
+ * @returns Promise with generated report and metadata
+ *
+ * @example
+ * const result = await generateReportNow({
+ *   userId: 'user_123',
+ *   commitSha: 'abc123',
+ *   repo: 'myorg/myrepo',
+ *   message: 'Refactor API',
+ *   files: ['src/api.ts'],
+ *   components: ['api'],
+ *   diffSummary: '- old code\n+ new code'
+ * });
+ *
+ * // handle provider and report result
+ */
+export declare function generateReport(input: PromptInput): Promise<ProviderResult>;
+/**
+ * Get job status by ID
+ *
+ * @param jobId - Job identifier returned from enqueueReport
+ * @returns Job status information or null if not found
+ */
+export declare function getJob(jobId: string): Promise<{
+    id: string;
+    state: string;
+    progress?: number;
+    result?: unknown;
+    failedReason?: string;
+    data?: unknown;
+} | null>;
+/**
+ * Delete a cached report entry.
+ *
+ * Call this once you have successfully saved the report to your own database
+ * to keep the Stepper's Redis storage footprint minimal.
+ *
+ * @param userId - User identifier
+ * @param commitSha - Commit SHA
+ * @param template - Template name (optional)
+ */
+export declare function deleteReport(userId: string, commitSha: string, template?: string): Promise<void>;
+/**
+ * Health check - returns provider status and system health
+ */
+export declare function healthcheck(): Promise<{
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    providers: Array<{
+        name: string;
+        healthy: boolean;
+    }>;
+    timestamp: string;
+}>;
+export * from './types.js';
+export { config } from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA6BxH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,cAAc,EAAE,CAAA;CAAE,GAAG,aAAa,CAUtH;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAGnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,aAAa,CAC/B,KAAK,EAAE,WAAW,GACnB,OAAO,CACJ;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAClE;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,CAAA;CAAE,CAClD,CAgDA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAIhF;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,IAAI,CAAC,CAER;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAItG;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC;IACzC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC7C,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACrD,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC,CAmBD;AAGD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,198 @@
+// packages/stepper/src/index.ts
+import { logger } from './logging.js';
+import { buildCacheKey, getReportCache, setDehydrated, isHydratedFresh, isStaleButUsable, deleteCacheEntry, } from './cache/redisCache.js';
+import { enqueueReportJob, getJobStatus } from './queue/producer.js';
+import { generateReportNow, registerCallbacks as registerOrchestratorCallbacks, initializeProviders, getProviderHealth } from './stepper/orchestrator.js';
+import { recordCacheHit, recordCacheMiss } from './metrics/metrics.js';
+import crypto from 'crypto';
+import { applyConfigOverrides } from './config.js';
+let isInitialized = false;
+function ensureInitialized() {
+    if (!isInitialized) {
+        const existingProviders = getProviderHealth();
+        if (existingProviders.length > 0) {
+            isInitialized = true;
+            return;
+        }
+        initStepper();
+    }
+}
+/**
+ * Initialize Stepper with optional config overrides.
+ * Useful for npm consumers who want programmatic config instead of env.
+ */
+export function initStepper(options) {
+    const overrides = options?.config ? { ...options.config } : {};
+    if (options?.providers) {
+        overrides.providers = options.providers;
+    }
+    const nextConfig = applyConfigOverrides(overrides);
+    initializeProviders(nextConfig.providers);
+    isInitialized = true;
+    return nextConfig;
+}
+/**
+ * Compute template hash for cache key
+ */
+function computeTemplateHash(template) {
+    const templateStr = template || 'default';
+    return crypto.createHash('sha256').update(templateStr).digest('hex').slice(0, 16);
+}
+/**
+ * Register lifecycle callbacks
+ *
+ * @example
+ * registerCallbacks({
+ *   onSuccess: (jobId, provider, result) => {
+ *     // handle success
+ *   },
+ *   onFallback: (jobId, result, meta) => {
+ *     // handle fallback
+ *   }
+ * });
+ */
+export function registerCallbacks(callbacks) {
+    registerOrchestratorCallbacks(callbacks);
+    logger.info('Callbacks registered');
+}
+/**
+ * Enqueue a report generation job (async, non-blocking)
+ *
+ * Returns cached result immediately if available (fresh or stale),
+ * or enqueues job and returns 202 status with jobId.
+ *
+ * @param input - Commit information
+ * @returns Promise with either immediate result or job info
+ *
+ * @example
+ * const result = await enqueueReport({
+ *   userId: 'user_123',
+ *   commitSha: 'abc123',
+ *   repo: 'myorg/myrepo',
+ *   message: 'Fix bug in auth',
+ *   files: ['src/auth.ts'],
+ *   components: ['auth'],
+ *   diffSummary: '+ fixed token validation'
+ * });
+ *
+ * if (result.status === 200) {
+ *   // handle cached result
+ * } else {
+ *   // handle enqueued result
+ * }
+ */
+export async function enqueueReport(input) {
+    ensureInitialized();
+    const templateHash = computeTemplateHash(input.template);
+    const cacheKey = buildCacheKey(input.userId, input.commitSha, templateHash);
+    // Check cache
+    const cached = await getReportCache(cacheKey);
+    if (cached && cached.status === 'hydrated' && cached.result) {
+        const fresh = isHydratedFresh(cached);
+        if (fresh) {
+            // Fresh cache hit - return immediately and cleanup
+            recordCacheHit('fresh');
+            logger.info({ cacheKey, userId: input.userId }, 'Cache hit (fresh), returning and clearing');
+            // We clear immediately because caller is expected to save this
+            deleteCacheEntry(cacheKey).catch(err => {
+                logger.error({ err, cacheKey }, 'Failed to cleanup cache after fresh hit');
+            });
+            return { status: 200, data: cached.result, cached: true };
+        }
+        // Stale but usable - return and schedule background refresh
+        if (isStaleButUsable(cached)) {
+            recordCacheHit('stale');
+            logger.info({ cacheKey, userId: input.userId }, 'Cache hit (stale), scheduling refresh');
+            // Schedule low-priority background refresh
+            enqueueReportJob(input, cacheKey, { priority: 10 }).catch((err) => {
+                logger.error({ err, cacheKey }, 'Failed to enqueue background refresh');
+            });
+            return { status: 200, data: cached.result, cached: true, stale: true };
+        }
+    }
+    // Cache miss or dehydrated - enqueue job
+    recordCacheMiss();
+    logger.info({ cacheKey, userId: input.userId }, 'Cache miss, enqueueing job');
+    const jobId = await enqueueReportJob(input, cacheKey);
+    // Create dehydrated placeholder
+    await setDehydrated(cacheKey, jobId);
+    return { status: 202, jobId, cached: false };
+}
+/**
+ * Generate report synchronously (blocking, immediate)
+ *
+ * Useful for testing or when you need the result immediately.
+ * This bypasses the queue and calls providers directly.
+ *
+ * @param input - Commit information
+ * @returns Promise with generated report and metadata
+ *
+ * @example
+ * const result = await generateReportNow({
+ *   userId: 'user_123',
+ *   commitSha: 'abc123',
+ *   repo: 'myorg/myrepo',
+ *   message: 'Refactor API',
+ *   files: ['src/api.ts'],
+ *   components: ['api'],
+ *   diffSummary: '- old code\n+ new code'
+ * });
+ *
+ * // handle provider and report result
+ */
+export async function generateReport(input) {
+    ensureInitialized();
+    const jobId = `sync_${Date.now()}`;
+    return generateReportNow(input, jobId);
+}
+/**
+ * Get job status by ID
+ *
+ * @param jobId - Job identifier returned from enqueueReport
+ * @returns Job status information or null if not found
+ */
+export async function getJob(jobId) {
+    return getJobStatus(jobId);
+}
+/**
+ * Delete a cached report entry.
+ *
+ * Call this once you have successfully saved the report to your own database
+ * to keep the Stepper's Redis storage footprint minimal.
+ *
+ * @param userId - User identifier
+ * @param commitSha - Commit SHA
+ * @param template - Template name (optional)
+ */
+export async function deleteReport(userId, commitSha, template) {
+    const templateHash = computeTemplateHash(template);
+    const cacheKey = buildCacheKey(userId, commitSha, templateHash);
+    await deleteCacheEntry(cacheKey);
+}
+/**
+ * Health check - returns provider status and system health
+ */
+export async function healthcheck() {
+    ensureInitialized();
+    const providerHealth = getProviderHealth();
+    const healthyCount = providerHealth.filter((p) => p.healthy).length;
+    let status;
+    if (healthyCount === 0) {
+        status = 'unhealthy';
+    }
+    else if (healthyCount < providerHealth.length) {
+        status = 'degraded';
+    }
+    else {
+        status = 'healthy';
+    }
+    return {
+        status,
+        providers: providerHealth.map((p) => ({ name: p.name, healthy: p.healthy })),
+        timestamp: new Date().toISOString(),
+    };
+}
+// Re-export types for consumers
+export * from './types.js';
+export { config } from './config.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/logging.d.ts

@@ -0,0 +1,10 @@
+import pino from 'pino';
+/**
+ * Base pino logger instance with structured logging
+ */
+export declare const logger: import("pino").Logger<never>;
+/**
+ * Create a child logger with additional context (e.g., jobId, requestId)
+ */
+export declare function createChildLogger(context: Record<string, unknown>): pino.Logger<never>;
+//# sourceMappingURL=logging.d.ts.map

package/dist/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAIxB;;GAEG;AACH,eAAO,MAAM,MAAM,8BA+BjB,CAAC;AAEH;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,sBAEjE"}