ai-inference-stepper 1.0.0

package/README.md

@@ -0,0 +1,261 @@
+# Stepper: Production-Grade AI Inference Orchestrator
+
+[![CI Status](https://github.com/samuel-adedigba/ai-inference-stepper/actions/workflows/ci.yml/badge.svg)](https://github.com/samuel-adedigba/ai-inference-stepper/actions)
+[![License: Custom](https://img.shields.io/badge/License-Attribution%20Required-blue.svg)](#license)
+[![DeepMind Tech](https://img.shields.io/badge/Built%20With-TypeScript%20%26%20Node.js-informational)](https://www.typescriptlang.org/)
+
+**Stepper** is a resilient, multi-provider AI inference engine designed for high-load production environments. It handles provider fallbacks, intelligent caching, job queuing, and circuit breaking out of the box.
+
+- Back to root: [../../README.md](../../README.md)
+- CommitDiary packages: [../api/README.md](../api/README.md) • [../web-dashboard/README.md](../web-dashboard/README.md) • [../extension/README.md](../extension/README.md) • [../core/README.md](../core/README.md)
+
+## ✅ Standalone Setup (Local)
+
+Stepper is open source and can run independently or inside this monorepo.
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm
+- Redis (required)
+
+### Install
+
+```bash
+cd packages/stepper
+pnpm install
+```
+
+### Configure
+
+```bash
+cp .env.example .env
+```
+
+Add at least one provider key and Redis config in .env.
+
+### Run
+
+```bash
+docker run -d -p 6379:6379 redis:alpine
+pnpm dev
+```
+
+### ✅ Why This Setup Works
+
+- Redis backs cache and queue state for resilient processing
+- Provider adapters allow fallback across multiple AI vendors
+- Callbacks let CommitDiary save reports and notify users reliably
+
+---
+
+## 🏗️ Architecture First
+
+Understanding how Stepper handles your requests is key to using its full power.
+
+![Stepper Architecture](./docs/assets/architecture.png)
+
+### The Core Flow
+
+1.  **Request Capture**: Received via HTTP or internal Library Call.
+2.  **Smart Caching**: Checks Redis. Supports **Stale-While-Revalidate** (returns stale data while refreshing in background).
+3.  **Job Queueing**: If not cached, the request is enqueued via **BullMQ** to prevent overloading providers.
+4.  **Resilient Orchestration**:
+    - **Priority Fallback**: Tries Gemini → Cohere → HF Space in sequence.
+    - **Circuit Breakers**: Stops calling failing providers to allow them to recover.
+    - **Rate Limiting**: Per-provider bottlenecking to respect API quotas.
+5.  **Finalize**: Result is cached, and `onSuccess` callbacks are triggered.
+
+> [!TIP]
+> For a deep dive into the system design, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+---
+
+## 🔗 CommitDiary Integration Flow
+
+```mermaid
+flowchart LR
+  A[API Server] --> B[Stepper enqueueReport]
+  B --> C[Queue + Providers]
+  C --> D[Callback to API]
+  D --> E[Report saved + webhooks]
+```
+
+### How CommitDiary Uses Stepper
+
+- API calls Stepper to generate commit reports
+- Stepper returns a jobId or cached result
+- Stepper posts back to API callbacks for delivery and persistence
+
+See API docs for endpoints and callbacks: [../api/README.md](../api/README.md)
+
+---
+
+## 🧩 Component Deep Dives
+
+Stepper is modular. Explore each subsystem's technical documentation:
+
+| Component         | Purpose                          | Technical Details                           |
+| :---------------- | :------------------------------- | :------------------------------------------ |
+| **⚡ Cache**      | Intelligent Redis strategies     | [Cache Guide](./src/cache/README.md)        |
+| **🤖 Providers**  | Adapter logic for different LLMs | [Provider Specs](./src/providers/README.md) |
+| **📥 Queue**      | Background processing & retries  | [Queue System](./src/queue/README.md)       |
+| **📊 Metrics**    | Prometheus & Observability       | [Metrics Docs](./src/metrics/README.md)     |
+| **🛡️ Alerts**     | Discord & error notifications    | [Alerts System](./src/alerts/README.md)     |
+| **✅ Validation** | Zod-based strict output parsing  | [Validation](./src/validation/README.md)    |
+
+### 🌟 Provider-Specific Optimizations
+
+#### Google Gemini (Gemini 3 Models)
+
+Stepper includes specialized optimizations for Google's Gemini 3 models based on [official Google prompting strategies](https://ai.google.dev/gemini-api/docs/prompting-strategies).
+
+**Why Gemini is Different:**
+- **XML-Structured Prompts**: Uses `<role>`, `<instructions>`, `<context>`, `<task>` tags for better model understanding
+- **Query Parameter Authentication**: API key passed in URL (`?key=YOUR_KEY`) instead of headers
+- **Locked Temperature**: Must use `temperature: 1.0` (Google requirement for optimal Gemini 3 performance)
+- **Increased Token Limit**: 4096 tokens for detailed analysis
+
+**Conditional Implementation:**
+```typescript
+if (provider === 'gemini') {
+    // Use XML-structured prompt
+    prompt = buildGeminiPrompt(input);
+    // Append API key to URL
+    endpoint = `${endpoint}?key=${apiKey}`;
+}
+```
+
+This pattern allows each provider to have unique optimizations while maintaining clean code separation. See [Provider Documentation](./src/providers/README.md#-provider-specific-implementations) for details.
+
+---
+
+## ⚡ Quick Start (3 Minutes)
+
+### 1. Install Dependencies
+
+```bash
+pnpm install
+```
+
+### 2. Configure Environment
+
+Copy the example and add your API keys:
+
+```bash
+cp .env.example .env
+```
+
+### 3. Spin Up Redis & Stepper
+
+```bash
+# Start Redis (Required)
+docker run -d -p 6379:6379 redis:alpine
+
+# Start in Dev Mode
+pnpm dev
+```
+
+---
+
+## 🧭 Monorepo Notes
+
+- API expects Stepper at STEPPER_URL (default http://localhost:3005)
+- If running inside the monorepo, keep API and Stepper dev servers up
+- See root setup guide: [../../README.md](../../README.md)
+
+---
+
+## 🛠️ Usage Modes
+
+### Mode A: As a Library (Direct Integration)
+
+Best for monorepos or when you want to avoid network overhead.
+
+```typescript
+import { enqueueReport, registerCallbacks, initStepper } from "ai-inference-stepper";
+
+// Optional: programmatic config overrides (no env file required)
+initStepper({
+  config: {
+    redis: { url: "redis://localhost:6379" },
+  },
+  providers: [
+    { name: "gemini", enabled: true, apiKey: process.env.GEMINI_API_KEY, baseUrl: "https://generativelanguage.googleapis.com/v1", modelName: "gemini-pro", concurrency: 2, rateLimitRPM: 5 }
+  ]
+});
+
+// 1. Setup notification logic
+registerCallbacks({
+  onSuccess: (id, provider, data) => console.log(`✅ Success via ${provider}`),
+  onFailure: (id, errors) => console.error("❌ Failed:", errors),
+});
+
+// 2. Trigger a request (returns immediately if queued or cached)
+const result = await enqueueReport({
+  commitSha: "abc123",
+  message: "Fix bug",
+  // ...other input
+});
+```
+
+### Mode B: As an HTTP Service
+
+Best for microservices or remote deployments (Render/Railway).
+
+```bash
+# Send a report generation request
+curl -X POST http://localhost:3001/v1/reports \
+  -H "Content-Type: application/json" \
+  -d '{ "message": "Refactor API", "files": ["src/app.ts"] }'
+
+#### CLI (npm)
+
+```bash
+# One-off run
+npx ai-inference-stepper
+
+# Or install and run
+npm i -g ai-inference-stepper
+ai-inference-stepper
+```
+
+#### Environment Setup (Service Mode)
+
+Stepper reads config from environment variables. Use .env for local runs:
+
+```bash
+cp .env.example .env
+```
+
+If you install Stepper as a library, you can either:
+- Provide env variables in your host app process (recommended for deployments), or
+- Call `initStepper({ config, providers })` programmatically to override defaults.
+
+# Response gives you a JobID to poll
+# { "status": "queued", "jobId": "...", "statusUrl": "..." }
+```
+
+---
+
+## 🤝 Contributing & Community
+
+We love contributors! Whether it's a bug report or a new provider adapter:
+
+- **Issues**: Found a bug? [Raise an issue](https://github.com/samuel-adedigba/ai-inference-stepper/issues).
+- **Pull Requests**: Have a fix? [Open a PR](https://github.com/samuel-adedigba/ai-inference-stepper/pulls).
+
+If contributing inside the CommitDiary monorepo, start at [../../README.md](../../README.md) for the full workflow.
+
+---
+
+## 📜 License
+
+**Custom Attribution License**
+
+You are free to use, modify, and distribute this software for personal or commercial projects, provided that:
+
+1.  **Credit is given**: You must attribute the original work to **Samuel Adedigba (@samuel-adedigba)**.
+2.  **Pull Requests**: Contributions and improvements are encouraged back to this core repository.
+
+_For full details, see the [LICENSE](./LICENSE) file (MIT-based with attribution)._

package/dist/alerts/discord.d.ts

@@ -0,0 +1,19 @@
+export interface DiscordAlert {
+    title: string;
+    message: string;
+    severity: 'info' | 'warning' | 'critical';
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Send alert to Discord webhook
+ */
+export declare function sendDiscordAlert(alert: DiscordAlert): Promise<void>;
+/**
+ * Send provider failure alert
+ */
+export declare function alertProviderFailure(provider: string, errorCount: number, error?: unknown): Promise<void>;
+/**
+ * Send circuit breaker alert
+ */
+export declare function alertCircuitOpen(provider: string, lastError?: unknown): Promise<void>;
+//# sourceMappingURL=discord.d.ts.map

package/dist/alerts/discord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discord.d.ts","sourceRoot":"","sources":["../../src/alerts/discord.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCzE;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAS/G;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAU3F"}

package/dist/alerts/discord.js

@@ -0,0 +1,70 @@
+// `packages/stepper/src/alerts/discord.ts
+import { logger } from '../logging.js';
+const DISCORD_WEBHOOK_URL = process.env.DISCORD_WEBHOOK_URL;
+/**
+ * Send alert to Discord webhook
+ */
+export async function sendDiscordAlert(alert) {
+    if (!DISCORD_WEBHOOK_URL) {
+        logger.debug('Discord webhook URL not configured, skipping alert');
+        return;
+    }
+    const emoji = alert.severity === 'critical' ? '🚨' : alert.severity === 'warning' ? '⚠️' : 'ℹ️';
+    const content = `${emoji} **${alert.title}**\n${alert.message}`;
+    const embed = alert.metadata
+        ? {
+            embeds: [
+                {
+                    title: alert.title,
+                    description: alert.message,
+                    color: alert.severity === 'critical' ? 0xff0000 : alert.severity === 'warning' ? 0xffa500 : 0x00ff00,
+                    fields: Object.entries(alert.metadata).map(([key, value]) => ({
+                        name: key,
+                        value: String(value),
+                        inline: true,
+                    })),
+                    timestamp: new Date().toISOString(),
+                },
+            ],
+        }
+        : { content };
+    try {
+        const response = await fetch(DISCORD_WEBHOOK_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(embed),
+        });
+        if (!response.ok) {
+            logger.warn({ status: response.status }, 'Discord webhook request failed');
+        }
+    }
+    catch (error) {
+        logger.error({ error }, 'Failed to send Discord alert');
+    }
+}
+/**
+ * Send provider failure alert
+ */
+export async function alertProviderFailure(provider, errorCount, error) {
+    const errorDetail = error instanceof Error ? error.message : String(error || 'Unknown error');
+    await sendDiscordAlert({
+        title: 'AI Provider Failure',
+        message: `Provider **${provider}** has failed ${errorCount} times\n\n**Error Details:**\n\`${errorDetail}\``,
+        severity: errorCount >= 5 ? 'critical' : 'warning',
+        metadata: { provider, errorCount, error: errorDetail, timestamp: new Date().toISOString() },
+    });
+}
+/**
+ * Send circuit breaker alert
+ */
+export async function alertCircuitOpen(provider, lastError) {
+    const errorDetail = lastError ? (lastError instanceof Error ? lastError.message : String(lastError)) : undefined;
+    const message = `Circuit breaker for provider **${provider}** is now OPEN${errorDetail ? `\n\n**Last Error:**\n\`${errorDetail}\`` : ''}`;
+    await sendDiscordAlert({
+        title: 'Circuit Breaker Opened',
+        message,
+        severity: 'critical',
+        metadata: { provider, lastError: errorDetail, timestamp: new Date().toISOString() },
+    });
+}
+//# sourceMappingURL=discord.js.map

package/dist/alerts/discord.js.map

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

package/dist/cache/redisCache.d.ts

@@ -0,0 +1,45 @@
+import Redis from 'ioredis';
+import { CacheEntry, ReportOutput, ProviderAttemptMeta } from '../types.js';
+/**
+ * Get or create Redis client
+ */
+export declare function getRedisClient(): Redis;
+/**
+ * Build cache key for a report
+ */
+export declare function buildCacheKey(userId: string, commitSha: string, templateHash?: string): string;
+/**
+ * Get cache entry: Looks up a report in the cache using its key. Like asking: "Do we already have a copy of this report?"
+ */
+export declare function getReportCache(key: string): Promise<CacheEntry | null>;
+/**
+ * Set dehydrated cache entry (job enqueued)
+ */
+export declare function setDehydrated(key: string, jobId: string): Promise<void>;
+/**
+ * Set hydrated cache entry (report generated)
+ * Stores a completed report in the cache. This is the "meal is ready!" moment.
+ */
+export declare function setHydrated(key: string, result: ReportOutput, providersAttempted: ProviderAttemptMeta[], fallback?: boolean, ttl?: number): Promise<void>;
+/**
+ * Mark cache entry as failed: Records that report generation failed completely. All AI providers were tried and none worked.
+ */
+export declare function markFailed(key: string, errorMessage: string, providersAttempted: ProviderAttemptMeta[]): Promise<void>;
+/**
+ * Check if hydrated entry is fresh
+ */
+export declare function isHydratedFresh(entry: CacheEntry): boolean;
+/**
+ * Check if entry is stale but usable for stale-while-revalidate: Checks if a report is old but still usable while a new one is being generated in the background.
+ */
+export declare function isStaleButUsable(entry: CacheEntry): boolean;
+/**
+ * Delete cache entry: Removes the record from Redis immediately.
+ * Call this once the backend has successfully saved the report to its database.
+ */
+export declare function deleteCacheEntry(key: string): Promise<void>;
+/**
+ * Close Redis connection (for graceful shutdown)
+ */
+export declare function closeRedis(): Promise<void>;
+//# sourceMappingURL=redisCache.d.ts.map

package/dist/cache/redisCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redisCache.d.ts","sourceRoot":"","sources":["../../src/cache/redisCache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,SAAS,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAO5E;;GAEG;AACH,wBAAgB,cAAc,IAAI,KAAK,CAwBtC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,GAAE,MAAkB,GAAG,MAAM,CAEzG;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAa5E;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB7E;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EACpB,kBAAkB,EAAE,mBAAmB,EAAE,EACzC,QAAQ,GAAE,OAAe,EACzB,GAAG,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB5H;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAQ1D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAK3D;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASjE;AAED;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAMhD"}

package/dist/cache/redisCache.js

@@ -0,0 +1,171 @@
+// packages/stepper/src/cache/redisCache.ts
+import Redis from 'ioredis';
+import { config } from '../config.js';
+import { logger } from '../logging.js';
+import { sendDiscordAlert } from '../alerts/discord.js';
+let redisClient = null;
+/**
+ * Get or create Redis client
+ */
+export function getRedisClient() {
+    if (!redisClient) {
+        redisClient = new Redis(config.redis.url, {
+            maxRetriesPerRequest: null, // Required by BullMQ for blocking operations
+            enableReadyCheck: true,
+            lazyConnect: false,
+        });
+        redisClient.on('error', (err) => {
+            logger.error({ err }, 'Redis client error');
+            void sendDiscordAlert({
+                title: 'Redis Connection Error',
+                message: `Redis client encountered an error: ${err.message}`,
+                severity: 'critical',
+                metadata: { error: err.message, timestamp: new Date().toISOString() }
+            });
+        });
+        redisClient.on('connect', () => {
+            logger.info('Redis client connected');
+        });
+    }
+    return redisClient;
+}
+/**
+ * Build cache key for a report
+ */
+export function buildCacheKey(userId, commitSha, templateHash = 'default') {
+    return `${config.redis.keyPrefix}report:${userId}:${commitSha}:${templateHash}`;
+}
+/**
+ * Get cache entry: Looks up a report in the cache using its key. Like asking: "Do we already have a copy of this report?"
+ */
+export async function getReportCache(key) {
+    const redis = getRedisClient();
+    try {
+        const data = await redis.get(key);
+        if (!data)
+            return null;
+        const entry = JSON.parse(data);
+        return entry;
+    }
+    catch (error) {
+        logger.error({ error, key }, 'Failed to get cache entry');
+        return null;
+    }
+}
+/**
+ * Set dehydrated cache entry (job enqueued)
+ */
+export async function setDehydrated(key, jobId) {
+    const redis = getRedisClient();
+    const entry = {
+        status: 'dehydrated', //Mark it as "in progress"
+        jobId,
+        timestamps: {
+            created: new Date().toISOString(),
+            updated: new Date().toISOString(),
+        },
+    };
+    try {
+        await redis.setex(key, config.cache.ttlSeconds, JSON.stringify(entry)); //Store in Redis with expiration time Default is 604,800 seconds = 7 days
+        logger.debug({ key, jobId }, 'Created dehydrated cache entry');
+    }
+    catch (error) {
+        logger.error({ error, key }, 'Failed to set dehydrated cache');
+        throw error;
+    }
+}
+/**
+ * Set hydrated cache entry (report generated)
+ * Stores a completed report in the cache. This is the "meal is ready!" moment.
+ */
+export async function setHydrated(key, result, providersAttempted, fallback = false, ttl // How long to keep it	604800 (7 days in seconds)
+) {
+    const redis = getRedisClient();
+    const entry = {
+        status: 'hydrated', // Report is complete
+        result,
+        providersAttempted,
+        fallback,
+        timestamps: {
+            created: new Date().toISOString(),
+            updated: new Date().toISOString(),
+        },
+        ttl: ttl || config.cache.ttlSeconds,
+    };
+    try {
+        await redis.setex(key, ttl || config.cache.ttlSeconds, JSON.stringify(entry));
+        logger.debug({ key, fallback }, 'Stored hydrated cache entry');
+    }
+    catch (error) {
+        logger.error({ error, key }, 'Failed to set hydrated cache');
+        throw error;
+    }
+}
+/**
+ * Mark cache entry as failed: Records that report generation failed completely. All AI providers were tried and none worked.
+ */
+export async function markFailed(key, errorMessage, providersAttempted) {
+    const redis = getRedisClient();
+    const entry = {
+        status: 'failed',
+        error: errorMessage,
+        providersAttempted,
+        timestamps: {
+            created: new Date().toISOString(),
+            updated: new Date().toISOString(),
+        },
+    };
+    try {
+        await redis.setex(key, 3600, JSON.stringify(entry)); // Keep failed for 1 hour
+        logger.debug({ key }, 'Marked cache entry as failed');
+    }
+    catch (error) {
+        logger.error({ error, key }, 'Failed to mark cache as failed');
+    }
+}
+/**
+ * Check if hydrated entry is fresh
+ */
+export function isHydratedFresh(entry) {
+    if (entry.status !== 'hydrated')
+        return false; //Is this a complete report?
+    const updatedAt = new Date(entry.timestamps.updated).getTime();
+    const now = Date.now();
+    const ageSeconds = (now - updatedAt) / 1000; //How old is this report?
+    return ageSeconds < config.cache.staleThresholdSeconds; //Is it younger than 24 hours?
+}
+/**
+ * Check if entry is stale but usable for stale-while-revalidate: Checks if a report is old but still usable while a new one is being generated in the background.
+ */
+export function isStaleButUsable(entry) {
+    if (entry.status !== 'hydrated')
+        return false;
+    if (!config.cache.enableStaleWhileRevalidate)
+        return false;
+    return !isHydratedFresh(entry);
+}
+/**
+ * Delete cache entry: Removes the record from Redis immediately.
+ * Call this once the backend has successfully saved the report to its database.
+ */
+export async function deleteCacheEntry(key) {
+    const redis = getRedisClient();
+    try {
+        await redis.del(key);
+        logger.debug({ key }, 'Deleted cache entry after successful delivery');
+    }
+    catch (error) {
+        logger.error({ error, key }, 'Failed to delete cache entry');
+    }
+}
+/**
+ * Close Redis connection (for graceful shutdown)
+ */
+export async function closeRedis() {
+    if (redisClient) {
+        await redisClient.quit();
+        redisClient = null;
+        logger.info('Redis client disconnected');
+    }
+}
+//# sourceMappingURL=redisCache.js.map

package/dist/cache/redisCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redisCache.js","sourceRoot":"","sources":["../../src/cache/redisCache.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAE3C,OAAO,KAAK,MAAM,SAAS,CAAC;AAE5B,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,IAAI,WAAW,GAAiB,IAAI,CAAC;AAErC;;GAEG;AACH,MAAM,UAAU,cAAc;IAC1B,IAAI,CAAC,WAAW,EAAE,CAAC;QACf,WAAW,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;YACtC,oBAAoB,EAAE,IAAI,EAAE,6CAA6C;YACzE,gBAAgB,EAAE,IAAI;YACtB,WAAW,EAAE,KAAK;SACrB,CAAC,CAAC;QAEH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YAC5B,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,oBAAoB,CAAC,CAAC;YAC5C,KAAK,gBAAgB,CAAC;gBAClB,KAAK,EAAE,wBAAwB;gBAC/B,OAAO,EAAE,sCAAsC,GAAG,CAAC,OAAO,EAAE;gBAC5D,QAAQ,EAAE,UAAU;gBACpB,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE;aACxE,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;QAEH,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;YAC3B,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACP,CAAC;IAED,OAAO,WAAW,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,SAAiB,EAAE,eAAuB,SAAS;IAC7F,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,UAAU,MAAM,IAAI,SAAS,IAAI,YAAY,EAAE,CAAC;AACpF,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC5C,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAE/B,IAAI,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QAEvB,MAAM,KAAK,GAAe,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,KAAK,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,2BAA2B,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,KAAa;IAC1D,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAE/B,MAAM,KAAK,GAAe;QACtB,MAAM,EAAE,YAAY,EAAE,0BAA0B;QAChD,KAAK;QACL,UAAU,EAAE;YACR,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACjC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC;KACJ,CAAC;IAEF,IAAI,CAAC;QACD,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,yEAAyE;QACjJ,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,gCAAgC,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,gCAAgC,CAAC,CAAC;QAC/D,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC7B,GAAW,EACX,MAAoB,EACpB,kBAAyC,EACzC,WAAoB,KAAK,EACzB,GAAY,CAAC,iDAAiD;;IAE9D,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAE/B,MAAM,KAAK,GAAe;QACtB,MAAM,EAAE,UAAU,EAAE,qBAAqB;QACzC,MAAM;QACN,kBAAkB;QAClB,QAAQ;QACR,UAAU,EAAE;YACR,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACjC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC;QACD,GAAG,EAAE,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU;KACtC,CAAC;IAEF,IAAI,CAAC;QACD,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9E,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,6BAA6B,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,8BAA8B,CAAC,CAAC;QAC7D,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW,EAAE,YAAoB,EAAE,kBAAyC;IACzG,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAE/B,MAAM,KAAK,GAAe;QACtB,MAAM,EAAE,QAAQ;QAChB,KAAK,EAAE,YAAY;QACnB,kBAAkB;QAClB,UAAU,EAAE;YACR,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACjC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC;KACJ,CAAC;IAEF,IAAI,CAAC;QACD,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,yBAAyB;QAC9E,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,8BAA8B,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,gCAAgC,CAAC,CAAC;IACnE,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC7C,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC,CAAC,4BAA4B;IAE3E,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,UAAU,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,yBAAyB;IAEtE,OAAO,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAE,8BAA8B;AAC3F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B;QAAE,OAAO,KAAK,CAAC;IAE3D,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAW;IAC9C,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAE/B,IAAI,CAAC;QACD,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrB,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,+CAA+C,CAAC,CAAC;IAC3E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,8BAA8B,CAAC,CAAC;IACjE,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC5B,IAAI,WAAW,EAAE,CAAC;QACd,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC;QACzB,WAAW,GAAG,IAAI,CAAC;QACnB,MAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAC7C,CAAC;AACL,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { startServer } from './server/start.js';
+import { logger } from './logging.js';
+startServer().catch((error) => {
+    logger.error({ error }, 'Failed to start Stepper server');
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC5B,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,gCAAgC,CAAC,CAAC;IAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import { StepperConfig } from './types.js';
+export declare function loadConfig(): StepperConfig;
+export declare function createConfig(overrides?: Partial<StepperConfig>): StepperConfig;
+export declare let config: StepperConfig;
+export declare function applyConfigOverrides(overrides?: Partial<StepperConfig>): StepperConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,YAAY,CAAC;AAyD3D,wBAAgB,UAAU,IAAI,aAAa,CAoI1C;AA2DD,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAM9E;AAED,eAAO,IAAI,MAAM,eAAe,CAAC;AAEjC,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAMtF"}