cerber-core 1.0.0

package/.cerber-example/modules/booking-calendar/contract.json

@@ -0,0 +1,106 @@
+{
+  "version": "2.0.0",
+  "publicInterface": {
+    "checkAvailability": {
+      "name": "checkAvailability",
+      "params": {
+        "roomType": "string",
+        "checkIn": "Date",
+        "checkOut": "Date",
+        "quantity": "number"
+      },
+      "returns": "AvailabilityResult",
+      "description": "Checks if rooms are available for the specified dates"
+    },
+    "createBooking": {
+      "name": "createBooking",
+      "params": {
+        "roomId": "string",
+        "checkIn": "Date",
+        "checkOut": "Date",
+        "guestInfo": "GuestInfo",
+        "totalPrice": "number"
+      },
+      "returns": "BookingResult",
+      "description": "Creates a new booking reservation"
+    },
+    "cancelBooking": {
+      "name": "cancelBooking",
+      "params": {
+        "bookingId": "string"
+      },
+      "returns": "CancellationResult",
+      "description": "Cancels an existing booking"
+    },
+    "getBooking": {
+      "name": "getBooking",
+      "params": {
+        "bookingId": "string"
+      },
+      "returns": "Booking",
+      "description": "Retrieves booking details by ID or confirmation code"
+    },
+    "modifyBooking": {
+      "name": "modifyBooking",
+      "params": {
+        "bookingId": "string",
+        "changes": "BookingChanges"
+      },
+      "returns": "BookingResult",
+      "description": "Modifies an existing booking"
+    }
+  },
+  "types": {
+    "AvailabilityParams": {
+      "roomType": "string",
+      "checkIn": "Date",
+      "checkOut": "Date",
+      "quantity": "number"
+    },
+    "AvailabilityResult": {
+      "available": "boolean",
+      "availableCount": "number",
+      "conflictingBookings": "string[]"
+    },
+    "BookingParams": {
+      "roomId": "string",
+      "checkIn": "Date",
+      "checkOut": "Date",
+      "guestInfo": "GuestInfo",
+      "totalPrice": "number"
+    },
+    "BookingResult": {
+      "bookingId": "string",
+      "confirmationCode": "string",
+      "status": "string"
+    },
+    "GuestInfo": {
+      "name": "string",
+      "email": "string",
+      "phone": "string"
+    },
+    "Booking": {
+      "id": "string",
+      "roomId": "string",
+      "checkIn": "Date",
+      "checkOut": "Date",
+      "guestInfo": "GuestInfo",
+      "totalPrice": "number",
+      "status": "string",
+      "confirmationCode": "string"
+    },
+    "CancellationResult": {
+      "success": "boolean",
+      "refundAmount": "number",
+      "cancellationFee": "number"
+    },
+    "BookingChanges": {
+      "checkIn": "Date | undefined",
+      "checkOut": "Date | undefined",
+      "roomId": "string | undefined"
+    }
+  },
+  "dependencies": [
+    "pricing-engine"
+  ]
+}

package/.cerber-example/modules/booking-calendar/dependencies.json

@@ -0,0 +1,8 @@
+{
+  "dependencies": [
+    "pricing-engine"
+  ],
+  "reason": {
+    "pricing-engine": "When modifying bookings, need to recalculate prices with current pricing rules"
+  }
+}

package/.cerber-example/modules/pricing-engine/MODULE.md

@@ -0,0 +1,160 @@
+# Module: pricing-engine
+
+**Owner:** Stefan Pitek  
+**Status:** Active  
+**Last Updated:** 2026-01-02
+
+## Purpose
+
+Calculates dynamic room pricing based on date, occupancy, season, and other factors. Provides pricing intelligence for the booking system.
+
+## Responsibilities
+
+- Calculate base room price
+- Apply seasonal multipliers (high/low season)
+- Apply day-of-week adjustments (weekend premiums)
+- Calculate advance booking discounts
+- Apply length-of-stay discounts
+- Provide price breakdowns and explanations
+
+## Public Interface
+
+Functions/classes that other modules can use:
+
+### `calculatePrice(params: PriceParams): PriceResult`
+
+Calculates the total price for a room booking.
+
+**Parameters:**
+- `roomType` (string) - Type of room (e.g., 'standard', 'deluxe', 'suite')
+- `checkIn` (Date) - Check-in date
+- `checkOut` (Date) - Check-out date
+- `guests` (number) - Number of guests
+- `promoCode` (string, optional) - Promotional code for discounts
+
+**Returns:**
+- `totalPrice` (number) - Final calculated price
+- `basePrice` (number) - Base room price
+- `breakdown` (object) - Detailed price breakdown
+  - `nightlyRates` (number[]) - Price per night
+  - `seasonalAdjustment` (number) - Seasonal multiplier applied
+  - `weekendPremium` (number) - Weekend surcharge
+  - `advanceBookingDiscount` (number) - Discount for booking in advance
+  - `lengthOfStayDiscount` (number) - Discount for extended stays
+  - `promoDiscount` (number) - Promotional code discount
+
+**Example:**
+```typescript
+import { calculatePrice } from './modules/pricing-engine';
+
+const result = calculatePrice({
+  roomType: 'deluxe',
+  checkIn: new Date('2026-07-15'),
+  checkOut: new Date('2026-07-20'),
+  guests: 2,
+  promoCode: 'SUMMER20'
+});
+
+console.log(result.totalPrice); // 850.00
+console.log(result.breakdown); // { nightlyRates: [180, 180, ...], ... }
+```
+
+### `getSeasonalMultiplier(date: Date): number`
+
+Returns the seasonal pricing multiplier for a given date.
+
+**Parameters:**
+- `date` (Date) - Date to check
+
+**Returns:**
+- Multiplier (number) - 1.0 = normal, 1.5 = high season, 0.8 = low season
+
+**Example:**
+```typescript
+const multiplier = getSeasonalMultiplier(new Date('2026-12-25'));
+console.log(multiplier); // 1.5 (Christmas is high season)
+```
+
+### `validatePromoCode(code: string): PromoCodeResult`
+
+Validates a promotional code and returns discount information.
+
+**Parameters:**
+- `code` (string) - Promo code to validate
+
+**Returns:**
+- `valid` (boolean) - Whether code is valid
+- `discount` (number) - Discount percentage (0-100)
+- `minNights` (number) - Minimum nights required
+- `expiryDate` (Date) - When code expires
+
+## Dependencies
+
+Modules this module uses:
+- `booking-calendar` - To check availability during pricing calculation
+- `database` - To fetch base room prices and seasonal rules
+
+## File Structure
+
+```
+src/modules/pricing-engine/
+├── index.ts              - Public interface (exports calculatePrice, etc.)
+├── calculator.ts         - Core pricing logic
+├── seasonal.ts           - Seasonal multiplier logic
+├── discounts.ts          - Discount calculations
+├── types.ts              - TypeScript type definitions
+└── constants.ts          - Pricing constants and rules
+```
+
+## Testing
+
+How to test this module:
+
+```bash
+npm test -- pricing-engine
+
+# Or specific test suites
+npm test -- pricing-engine.calculator
+npm test -- pricing-engine.seasonal
+npm test -- pricing-engine.discounts
+```
+
+Test coverage: 95%
+
+## Performance
+
+- Average calculation time: 5-10ms
+- Caching: Seasonal multipliers cached for 24h
+- Database queries: 1-2 per calculation (base price + seasonal rules)
+
+## Configuration
+
+Pricing rules configured in:
+- `config/pricing-rules.json` - Seasonal dates and multipliers
+- Database table `pricing_rules` - Dynamic rules
+- Environment variable `WEEKEND_PREMIUM` - Default 1.2 (20% premium)
+
+## Breaking Changes
+
+### v2.0.0 (2026-01-02)
+- Changed `calculatePrice` return type to include `breakdown`
+- Removed deprecated `getPrice()` function
+- `promoCode` parameter now optional (was required)
+
+### v1.5.0 (2025-12-01)
+- Added `lengthOfStayDiscount` to breakdown
+
+## Notes
+
+- Pricing engine does NOT handle payment processing (see payment-gateway module)
+- All prices in USD, conversion happens at payment layer
+- Seasonal rules can be overridden by database entries
+- Price calculations are deterministic - same inputs = same output
+- Consider caching results for identical requests within 1 hour
+
+## Future Plans
+
+- [ ] Add AI-powered dynamic pricing based on demand
+- [ ] Implement competitor price monitoring
+- [ ] Add group booking discounts
+- [ ] Support multiple currencies natively

package/.cerber-example/modules/pricing-engine/contract.json

@@ -0,0 +1,64 @@
+{
+  "version": "2.0.0",
+  "publicInterface": {
+    "calculatePrice": {
+      "name": "calculatePrice",
+      "params": {
+        "roomType": "string",
+        "checkIn": "Date",
+        "checkOut": "Date",
+        "guests": "number",
+        "promoCode": "string | undefined"
+      },
+      "returns": "PriceResult",
+      "description": "Calculates the total price for a room booking with detailed breakdown"
+    },
+    "getSeasonalMultiplier": {
+      "name": "getSeasonalMultiplier",
+      "params": {
+        "date": "Date"
+      },
+      "returns": "number",
+      "description": "Returns the seasonal pricing multiplier for a given date"
+    },
+    "validatePromoCode": {
+      "name": "validatePromoCode",
+      "params": {
+        "code": "string"
+      },
+      "returns": "PromoCodeResult",
+      "description": "Validates a promotional code and returns discount information"
+    }
+  },
+  "types": {
+    "PriceParams": {
+      "roomType": "string",
+      "checkIn": "Date",
+      "checkOut": "Date",
+      "guests": "number",
+      "promoCode": "string | undefined"
+    },
+    "PriceResult": {
+      "totalPrice": "number",
+      "basePrice": "number",
+      "breakdown": "PriceBreakdown"
+    },
+    "PriceBreakdown": {
+      "nightlyRates": "number[]",
+      "seasonalAdjustment": "number",
+      "weekendPremium": "number",
+      "advanceBookingDiscount": "number",
+      "lengthOfStayDiscount": "number",
+      "promoDiscount": "number"
+    },
+    "PromoCodeResult": {
+      "valid": "boolean",
+      "discount": "number",
+      "minNights": "number",
+      "expiryDate": "Date"
+    }
+  },
+  "dependencies": [
+    "booking-calendar"
+  ]
+}

package/.cerber-example/modules/pricing-engine/dependencies.json

@@ -0,0 +1,8 @@
+{
+  "dependencies": [
+    "booking-calendar"
+  ],
+  "reason": {
+    "booking-calendar": "Pricing engine needs to check room availability during price calculation to ensure quoted prices are for available rooms"
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-03
+
+### Added
+- **Guardian 1.0**: Pre-commit architecture validator
+  - Forbidden pattern detection with architect approval system
+  - Required file validation
+  - Required import checking
+  - package.json rules validation
+  - Recursive directory scanning
+  - Detailed error/warning reporting
+  - CLI with `--schema`, `--verbose`, `--fail-on-warning` options
+
+- **Cerber 2.1**: Runtime health monitoring
+  - Flexible health check system
+  - Multiple severity levels (critical, error, warning, info)
+  - Parallel and sequential check execution
+  - Detailed diagnostics with fix suggestions
+  - JSON output for CI/CD integration
+  - CLI with `--checks`, `--url`, `--parallel` options
+
+- **Architect Approval System**:
+  - Comment-based approval format: `// ARCHITECT_APPROVED: reason - YYYY-MM-DD - Name`
+  - Automatic parsing and tracking
+  - Integration with Guardian validation
+
+- **Examples**:
+  - Frontend schema (React/Vue patterns)
+  - Backend schema (Node.js/Express patterns)
+  - Health check templates (DB, disk, memory, env vars)
+
+- **Documentation**:
+  - Comprehensive README with real-world metrics
+  - Contributing guidelines
+  - API documentation
+  - MIT License
+
+- **Production Testing**:
+  - Extracted from Eliksir project
+  - Real metrics: 18 commits, 43 issues detected, 4.5 hours saved
+  - 95% bug detection rate pre-production
+  - 2 commits blocked by Guardian
+
+### Technical Details
+- TypeScript with ES2022 target
+- ESNext modules for modern bundlers
+- Commander.js for CLI
+- Chalk for colored output
+- Full type definitions included
+- Zero runtime dependencies (except CLI deps)
+
+## [Unreleased]
+
+### Planned
+- Web dashboard for health check visualization
+- Slack/Discord notifications
+- Custom reporter plugins
+- VS Code extension
+- Git hooks integration (Husky)
+- More built-in health checks
+- Performance monitoring
+- Metrics export (Prometheus, DataDog)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Pitek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.