cerber-core 1.0.0

package/.cerber-example/BIBLE.md

@@ -0,0 +1,132 @@
+# PROJECT BIBLE - Master Map
+
+**Project:** Hotel Booking System Example  
+**Owner:** Stefan Pitek  
+**Last Updated:** 2026-01-02
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────┐
+│      Frontend (React/Next.js)           │
+│      - Booking UI                       │
+│      - Price Calculator                 │
+└─────────────────┬───────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────┐
+│         API Layer (Express)             │
+│         /api/bookings                   │
+│         /api/pricing                    │
+└─────────────────┬───────────────────────┘
+                  │
+        ┌─────────┼─────────┐
+        ▼                   ▼
+  pricing-engine    booking-calendar
+        │                   │
+        └─────────┬─────────┘
+                  ▼
+          PostgreSQL Database
+```
+
+## Modules Index
+
+### Core Modules
+
+1. **pricing-engine** - Dynamic pricing calculation
+   - Owner: Stefan Pitek
+   - Status: Active
+   - Files: `src/modules/pricing-engine/`
+   - Purpose: Calculate room prices based on date, occupancy, season
+
+2. **booking-calendar** - Room availability and reservations
+   - Owner: Stefan Pitek
+   - Status: Active
+   - Files: `src/modules/booking-calendar/`
+   - Purpose: Manage room bookings and availability
+
+## Connections Map
+
+- `pricing-engine` → `booking-calendar`: checkAvailability()
+- `booking-calendar` → `pricing-engine`: calculatePrice()
+
+## Team Responsibilities
+
+- **Stefan Pitek**: pricing-engine, booking-calendar
+- **Backend Team**: API layer, database schema
+- **Frontend Team**: Booking UI, integration
+
+## Module Dependencies
+
+```
+booking-calendar
+    ↓
+pricing-engine
+    ↓
+database
+```
+
+## Tech Stack
+
+- **Backend**: Node.js, Express, TypeScript
+- **Database**: PostgreSQL, Prisma ORM
+- **Testing**: Jest, Supertest
+- **Validation**: Cerber TEAM module system
+
+## Development Workflow
+
+1. **Focus Mode**: `bash team/scripts/cerber-focus.sh pricing-engine`
+2. **Validate**: `bash team/scripts/cerber-module-check.sh pricing-engine`
+3. **Check Connections**: `bash team/scripts/cerber-connections-check.sh`
+4. **Commit**: Guardian validates architecture
+5. **Deploy**: Cerber 2.1 validates health
+
+## API Endpoints
+
+### Pricing
+- `GET /api/pricing/calculate` - Calculate room price
+  - Query: `roomType`, `checkIn`, `checkOut`, `guests`
+  - Returns: `{ price: number, breakdown: {...} }`
+
+### Booking
+- `POST /api/bookings` - Create reservation
+  - Body: `{ roomId, checkIn, checkOut, guestInfo }`
+  - Returns: `{ bookingId, confirmationCode }`
+
+- `GET /api/bookings/:id` - Get booking details
+- `DELETE /api/bookings/:id` - Cancel booking
+
+## Database Schema
+
+```sql
+-- Rooms
+CREATE TABLE rooms (
+  id SERIAL PRIMARY KEY,
+  room_number VARCHAR(10) UNIQUE,
+  room_type VARCHAR(50),
+  base_price DECIMAL(10,2)
+);
+
+-- Bookings
+CREATE TABLE bookings (
+  id SERIAL PRIMARY KEY,
+  room_id INTEGER REFERENCES rooms(id),
+  check_in DATE,
+  check_out DATE,
+  guest_name VARCHAR(255),
+  total_price DECIMAL(10,2),
+  status VARCHAR(20)
+);
+```
+
+## Notes
+
+- Pricing engine uses dynamic pricing algorithm based on:
+  - Seasonal multipliers (high/low season)
+  - Day of week (weekends +20%)
+  - Advance booking discount
+  - Length of stay discount
+
+- Booking calendar ensures no double-bookings
+- All changes validated by Guardian pre-commit
+- Production health monitored by Cerber 2.1

package/.cerber-example/CERBER_LAW.md

@@ -0,0 +1,200 @@
+# CERBER LAW - Team Rules
+
+**Project:** Hotel Booking System  
+**Version:** 2.0-team  
+**Last Updated:** 2026-01-02
+
+## Core Principles
+
+1. **Module Boundaries Are Sacred**
+   - Modules communicate only through declared contracts
+   - No direct imports between modules (use public interface)
+   - All connections must have documented contracts
+
+2. **Focus Mode First**
+   - Always use `cerber-focus.sh` before working on a module
+   - Share FOCUS_CONTEXT.md with AI instead of entire codebase
+   - Keep context small and focused
+
+3. **Documentation Is Code**
+   - MODULE.md must be updated with every public interface change
+   - Connection contracts are versioned
+   - Breaking changes must be documented
+
+## Module Rules
+
+### Creating Modules
+
+```bash
+# Always use the official script
+bash team/scripts/cerber-add-module.sh <module-name>
+
+# Never create modules manually
+```
+
+### Module Structure
+
+Each module MUST have:
+- `MODULE.md` - Complete documentation
+- `contract.json` - Public interface definition
+- `dependencies.json` - List of dependencies
+
+### Naming Conventions
+
+- Module names: `kebab-case` (e.g., `pricing-engine`)
+- File names: `camelCase.ts` or `kebab-case.ts`
+- Exports: Named exports only (no default exports)
+
+## Connection Rules
+
+### Creating Connections
+
+1. Define interface in both modules
+2. Create connection contract in `.cerber/connections/contracts/`
+3. Version the contract (semver)
+4. Document breaking changes
+
+### Connection Contract Template
+
+```json
+{
+  "id": "module-a-to-module-b",
+  "from": "module-a",
+  "to": "module-b",
+  "type": "function-call",
+  "interface": { ... },
+  "version": "1.0.0",
+  "breaking_changes": []
+}
+```
+
+### Breaking Changes
+
+When making breaking changes:
+1. Increment major version
+2. Add to `breaking_changes` array
+3. Update both modules
+4. Notify team in PR description
+
+## Validation Rules
+
+### Before Commit
+
+```bash
+# Validate module
+bash team/scripts/cerber-module-check.sh <module-name>
+
+# Validate all connections
+bash team/scripts/cerber-connections-check.sh
+
+# Guardian validates architecture
+git commit
+```
+
+### Before PR
+
+1. All modules pass validation
+2. All connections valid
+3. BIBLE.md updated
+4. FOCUS_CONTEXT.md generated
+5. Tests pass
+6. Guardian pre-commit passed
+
+## Workflow
+
+### Daily Start
+
+```bash
+npm run cerber:morning
+# or
+bash team/scripts/cerber-team-morning.sh
+```
+
+### Working on Module
+
+```bash
+# 1. Enter focus mode
+bash team/scripts/cerber-focus.sh pricing-engine
+
+# 2. Work on module (share FOCUS_CONTEXT.md with AI)
+
+# 3. Validate changes
+bash team/scripts/cerber-module-check.sh pricing-engine
+
+# 4. Commit (Guardian validates)
+git commit -m "feat(pricing-engine): add seasonal pricing"
+```
+
+### Adding Module
+
+```bash
+# 1. Create module
+bash team/scripts/cerber-add-module.sh payment-gateway
+
+# 2. Edit MODULE.md, contract.json, dependencies.json
+
+# 3. Enter focus mode
+bash team/scripts/cerber-focus.sh payment-gateway
+
+# 4. Implement module
+
+# 5. Validate
+bash team/scripts/cerber-module-check.sh payment-gateway
+```
+
+## Forbidden Practices
+
+❌ **DO NOT:**
+- Import directly from another module's internals
+- Skip module validation before committing
+- Modify MODULE.md without updating contract.json
+- Create modules without using `cerber-add-module.sh`
+- Make breaking changes without versioning
+- Work on entire codebase when you could use focus mode
+
+✅ **DO:**
+- Use focus mode for every module
+- Validate before committing
+- Document all public interfaces
+- Version connection contracts
+- Update BIBLE.md with changes
+- Follow module boundaries strictly
+
+## Integration with Guardian + Cerber
+
+Cerber TEAM works alongside existing tools:
+
+```
+Morning:
+  bash team/scripts/cerber-team-morning.sh  (TEAM)
+  
+Development:
+  bash team/scripts/cerber-focus.sh <module>  (TEAM)
+  git commit                                  (Guardian validates)
+  
+Pre-push:
+  npm run cerber:pre-push                     (SOLO checks)
+  
+Deploy:
+  curl /api/health                           (Cerber 2.1 validates)
+```
+
+## Enforcement
+
+- **Guardian**: Pre-commit validation of architecture
+- **Module Check**: Validates module compliance
+- **Connection Check**: Validates contracts
+- **Code Review**: Human review of module boundaries
+- **CI/CD**: Automated validation on PR
+
+## Exceptions
+
+When you need to break the rules:
+1. Document reason in MODULE.md
+2. Add `ARCHITECT_APPROVED:` comment in code
+3. Create issue to fix properly
+4. Notify team in PR
+
+## Contact
+
+Questions? Contact Stefan Pitek or see [docs/TEAM.md](../../docs/TEAM.md)

package/.cerber-example/connections/contracts/booking-to-pricing.json

@@ -0,0 +1,44 @@
+{
+  "id": "booking-to-pricing",
+  "from": "booking-calendar",
+  "to": "pricing-engine",
+  "type": "function-call",
+  "interface": {
+    "function": "calculatePrice",
+    "description": "Booking calendar calls pricing engine when modifying bookings to recalculate total price",
+    "input": {
+      "type": "PriceParams",
+      "fields": {
+        "roomType": "string",
+        "checkIn": "Date",
+        "checkOut": "Date",
+        "guests": "number",
+        "promoCode": "string | undefined"
+      }
+    },
+    "output": {
+      "type": "PriceResult",
+      "fields": {
+        "totalPrice": "number",
+        "basePrice": "number",
+        "breakdown": "PriceBreakdown"
+      }
+    }
+  },
+  "version": "2.0.0",
+  "breaking_changes": [
+    {
+      "version": "2.0.0",
+      "date": "2026-01-02",
+      "description": "Added detailed breakdown to return type",
+      "migration": "Update booking-calendar to handle new breakdown field"
+    },
+    {
+      "version": "2.0.0",
+      "date": "2026-01-02",
+      "description": "Made promoCode parameter optional",
+      "migration": "Can now omit promoCode parameter"
+    }
+  ],
+  "notes": "This connection is used during booking modifications. The booking calendar must recalculate prices with current rates when guests modify their dates."
+}

package/.cerber-example/connections/contracts/pricing-to-booking.json

@@ -0,0 +1,37 @@
+{
+  "id": "pricing-to-booking",
+  "from": "pricing-engine",
+  "to": "booking-calendar",
+  "type": "function-call",
+  "interface": {
+    "function": "checkAvailability",
+    "description": "Pricing engine calls booking calendar to verify room availability before calculating prices",
+    "input": {
+      "type": "AvailabilityParams",
+      "fields": {
+        "roomType": "string",
+        "checkIn": "Date",
+        "checkOut": "Date",
+        "quantity": "number"
+      }
+    },
+    "output": {
+      "type": "AvailabilityResult",
+      "fields": {
+        "available": "boolean",
+        "availableCount": "number",
+        "conflictingBookings": "string[]"
+      }
+    }
+  },
+  "version": "2.0.0",
+  "breaking_changes": [
+    {
+      "version": "2.0.0",
+      "date": "2026-01-02",
+      "description": "Added 'availableCount' to return type",
+      "migration": "Update pricing-engine to handle new field"
+    }
+  ],
+  "notes": "This connection ensures that quoted prices are only for available rooms. Pricing engine must handle the case where availability changes between price quote and booking."
+}

package/.cerber-example/modules/booking-calendar/MODULE.md

@@ -0,0 +1,225 @@
+# Module: booking-calendar
+
+**Owner:** Stefan Pitek  
+**Status:** Active  
+**Last Updated:** 2026-01-02
+
+## Purpose
+
+Manages room availability, bookings, and calendar operations. Ensures no double-bookings and provides real-time availability information.
+
+## Responsibilities
+
+- Track room availability by date
+- Create and manage bookings
+- Prevent double-bookings (conflict detection)
+- Calculate available rooms for date ranges
+- Handle booking cancellations and modifications
+- Generate availability calendars
+
+## Public Interface
+
+Functions/classes that other modules can use:
+
+### `checkAvailability(params: AvailabilityParams): AvailabilityResult`
+
+Checks if rooms are available for the specified dates.
+
+**Parameters:**
+- `roomType` (string) - Type of room to check
+- `checkIn` (Date) - Check-in date
+- `checkOut` (Date) - Check-out date
+- `quantity` (number) - Number of rooms needed
+
+**Returns:**
+- `available` (boolean) - Whether rooms are available
+- `availableCount` (number) - How many rooms available
+- `conflictingBookings` (string[]) - IDs of conflicting bookings (if any)
+
+**Example:**
+```typescript
+import { checkAvailability } from './modules/booking-calendar';
+
+const result = checkAvailability({
+  roomType: 'deluxe',
+  checkIn: new Date('2026-07-15'),
+  checkOut: new Date('2026-07-20'),
+  quantity: 2
+});
+
+if (result.available) {
+  console.log(`${result.availableCount} rooms available`);
+} else {
+  console.log('Rooms not available for these dates');
+}
+```
+
+### `createBooking(params: BookingParams): BookingResult`
+
+Creates a new booking reservation.
+
+**Parameters:**
+- `roomId` (string) - ID of the room to book
+- `checkIn` (Date) - Check-in date
+- `checkOut` (Date) - Check-out date
+- `guestInfo` (GuestInfo) - Guest details
+- `totalPrice` (number) - Total booking price
+
+**Returns:**
+- `bookingId` (string) - Unique booking identifier
+- `confirmationCode` (string) - Human-readable confirmation code
+- `status` (string) - Booking status ('confirmed', 'pending', 'cancelled')
+
+**Example:**
+```typescript
+const booking = createBooking({
+  roomId: 'room-101',
+  checkIn: new Date('2026-07-15'),
+  checkOut: new Date('2026-07-20'),
+  guestInfo: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    phone: '+1234567890'
+  },
+  totalPrice: 850.00
+});
+
+console.log(`Booking confirmed: ${booking.confirmationCode}`);
+```
+
+### `cancelBooking(bookingId: string): CancellationResult`
+
+Cancels an existing booking.
+
+**Parameters:**
+- `bookingId` (string) - ID of booking to cancel
+
+**Returns:**
+- `success` (boolean) - Whether cancellation succeeded
+- `refundAmount` (number) - Amount to be refunded
+- `cancellationFee` (number) - Fee charged for cancellation
+
+### `getBooking(bookingId: string): Booking`
+
+Retrieves booking details.
+
+**Parameters:**
+- `bookingId` (string) - Booking ID or confirmation code
+
+**Returns:**
+- Complete booking object with all details
+
+### `modifyBooking(bookingId: string, changes: BookingChanges): BookingResult`
+
+Modifies an existing booking (dates, room type, etc.).
+
+**Parameters:**
+- `bookingId` (string) - Booking to modify
+- `changes` (BookingChanges) - Fields to update
+
+**Returns:**
+- Updated booking with new confirmation code
+
+## Dependencies
+
+Modules this module uses:
+- `pricing-engine` - To recalculate prices when modifying bookings
+- `database` - To persist bookings and check availability
+
+## File Structure
+
+```
+src/modules/booking-calendar/
+├── index.ts              - Public interface
+├── availability.ts       - Availability checking logic
+├── booking-manager.ts    - Create/modify/cancel bookings
+├── conflict-detector.ts  - Double-booking prevention
+├── types.ts              - Type definitions
+└── validators.ts         - Input validation
+```
+
+## Testing
+
+How to test this module:
+
+```bash
+npm test -- booking-calendar
+
+# Or specific test suites
+npm test -- booking-calendar.availability
+npm test -- booking-calendar.conflicts
+npm test -- booking-calendar.bookings
+```
+
+Test coverage: 98%
+
+## Performance
+
+- Availability check: 10-20ms (with database query)
+- Create booking: 50-100ms (includes conflict check + database write)
+- Conflict detection: < 5ms (optimized query with indexes)
+
+## Database Schema
+
+```sql
+CREATE TABLE bookings (
+  id UUID PRIMARY KEY,
+  room_id VARCHAR(50) NOT NULL,
+  check_in DATE NOT NULL,
+  check_out DATE NOT NULL,
+  guest_name VARCHAR(255),
+  guest_email VARCHAR(255),
+  guest_phone VARCHAR(50),
+  total_price DECIMAL(10,2),
+  status VARCHAR(20),
+  confirmation_code VARCHAR(10) UNIQUE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_bookings_dates ON bookings(room_id, check_in, check_out);
+CREATE INDEX idx_bookings_status ON bookings(status);
+```
+
+## Conflict Detection Rules
+
+- Check-in date must be before check-out date
+- Cannot book if ANY overlap exists with confirmed bookings
+- Overlap includes:
+  - Booking A starts before Booking B ends
+  - Booking B starts before Booking A ends
+- Cancelled bookings are ignored in conflict detection
+- Pending bookings held for 15 minutes before release
+
+## Breaking Changes
+
+### v2.0.0 (2026-01-02)
+- `createBooking` now requires `totalPrice` parameter
+- Changed `status` enum values ('active' → 'confirmed')
+- Removed deprecated `bookRoom()` function
+
+### v1.8.0 (2025-11-15)
+- Added `modifyBooking()` function
+- Changed return type of `checkAvailability` to include count
+
+## Notes
+
+- All dates are stored in UTC, converted to local time for display
+- Confirmation codes are 10-character alphanumeric (e.g., "XY9K4P2M1Q")
+- Bookings automatically cancelled if not paid within 24 hours
+- Same-day bookings require phone confirmation
+- Check-in time: 3:00 PM, Check-out time: 11:00 AM
+
+## Integration Notes
+
+- Pricing engine calls `checkAvailability` before calculating prices
+- Payment gateway triggers `createBooking` after payment success
+- Email service notified on booking creation/cancellation
+- Housekeeping service receives next-day check-in list
+
+## Future Plans
+
+- [ ] Add waitlist functionality for fully booked dates
+- [ ] Implement automatic overbooking prevention with buffer
+- [ ] Add recurring booking support (e.g., weekly stays)
+- [ ] Integration with external booking platforms (Booking.com, Airbnb)