heicat 0.1.2

package/.eslintrc.js

@@ -0,0 +1,29 @@
+module.exports = {
+  env: {
+    node: true,
+    es2020: true
+  },
+  extends: [
+    'eslint:recommended',
+    '@typescript-eslint/recommended'
+  ],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module'
+  },
+  plugins: [
+    '@typescript-eslint'
+  ],
+  rules: {
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'off'
+  },
+  ignorePatterns: [
+    'dist/',
+    'node_modules/',
+    '*.js'
+  ]
+};

package/README.md

@@ -0,0 +1,346 @@
+# Heicat
+
+Runtime-enforced API contract system for Node.js. Catches bugs that TypeScript cannot.
+
+[![npm version](https://badge.fury.io/js/%40heicat%2Fcore.svg)](https://badge.fury.io/js/%40heicat%2Fcore)
+[![npm version](https://badge.fury.io/js/%40heicat%2Fcli.svg)](https://badge.fury.io/js/%40heicat%2Fcli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install both packages
+npm install @heicat/core @heicat/cli
+
+# Or install individually
+npm install @heicat/core
+npm install -D @heicat/cli
+```
+
+### Setup
+
+Initialize contracts in your project:
+
+```bash
+npx heicat init
+```
+
+Add middleware to your Express app:
+
+```typescript
+import { contractMiddleware } from "@heicat/core";
+
+app.use(
+  contractMiddleware({
+    contractsPath: "./contracts",
+    mode: "dev"
+  })
+);
+```
+
+That's it! Your API now has runtime contract enforcement.
+
+## What It Does
+
+- **Validates requests** before they reach your handlers
+- **Validates responses** before they're sent to clients
+- **Validates errors** to ensure consistent error shapes
+- **Logs violations** with clear, actionable messages
+- **Works in dev, strict, and CI modes**
+
+## Example Violation
+
+```
+❌ POST /users: Response missing field: email
+```
+
+## CLI Commands
+
+```bash
+# Initialize contracts in your project
+heicat init [--contracts-path <path>]
+
+# Validate contract files (syntax + schema)
+heicat validate [--contracts-path <path>]
+
+# Show contract status and statistics
+heicat status [--contracts-path <path>]
+
+# Watch contracts and validate in real-time
+heicat watch [--contracts-path <path>] [--port <port>]
+
+# Test contracts against running server
+heicat test <url> [--contracts-path <path>]
+```
+
+## Contract Format
+
+Contracts are simple JSON files:
+
+```json
+{
+  "method": "POST",
+  "path": "/users",
+  "request": {
+    "body": {
+      "email": { "type": "string", "required": true },
+      "password": { "type": "string", "minLength": 8 }
+    }
+  },
+  "response": {
+    "200": {
+      "id": "string",
+      "email": "string"
+    }
+  },
+  "errors": {
+    "400": { "message": "string" }
+  }
+}
+```
+
+## Modes
+
+- **`dev`**: Logs warnings, doesn't block responses
+- **`strict`**: Blocks invalid responses (implemented)
+- **`ci`**: Fails process on violations (implemented)
+
+## Why This Works
+
+TypeScript validates at compile time. This validates at runtime.
+
+- Catches silent API drift
+- Enforces backend behavior consistency
+- Makes contracts the source of truth
+- Requires almost zero adoption effort
+
+## Project Structure
+
+```
+your-project/
+ ├─ contracts/
+ │   ├─ users.contract.json
+ │   ├─ auth.contract.json
+ ├─ src/
+ │   ├─ routes/
+ └─ package.json
+```
+
+## Testing
+
+### Testing Contracts
+
+#### 1. Validate Contract Syntax
+```bash
+# Validate all contract files
+heicat validate
+
+# Validate specific contracts directory
+heicat validate --contracts-path ./my-contracts
+```
+
+#### 2. Test Against Running Server
+```bash
+# Start your server first
+npm start
+
+# Test all contracts against localhost:3000
+heicat test http://localhost:3000
+
+# Test specific contracts
+heicat test http://localhost:3000 --contracts-path ./contracts
+```
+
+#### 3. Watch Mode with Live GUI
+```bash
+# Start watch mode with GUI dashboard
+heicat watch
+
+# Opens http://localhost:3333 with live violations dashboard
+```
+
+### Manual Testing
+
+#### Testing the Middleware
+1. Start the example app:
+```bash
+cd examples/express-app
+npm install
+npm start
+```
+
+2. Test valid request:
+```bash
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"password123","name":"Test User"}'
+```
+
+3. Test invalid request (missing required field):
+```bash
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"password":"password123"}'
+# Should return 400 with validation error
+```
+
+4. Test login:
+```bash
+curl -X POST http://localhost:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"password123"}'
+```
+
+### Unit Testing
+
+#### Running Tests
+```bash
+# Test all packages
+npm test
+
+# Test specific package
+cd packages/core
+npm test
+
+cd packages/cli
+npm test
+```
+
+#### Writing Tests
+Tests use Jest and are located in `__tests__/` directories or `*.test.ts` files.
+
+Example test structure:
+```
+packages/core/
+  src/
+    __tests__/
+      validation-engine.test.ts
+      middleware.test.ts
+```
+
+### Integration Testing
+
+#### End-to-End Testing
+1. Start the example server
+2. Run contract tests:
+```bash
+contract-studio test http://localhost:3000
+```
+
+#### CI/CD Testing
+Add to your CI pipeline:
+```yaml
+- name: Validate Contracts
+  run: npx heicat validate
+
+- name: Test Contracts
+  run: |
+    npm start &
+    sleep 5
+    npx heicat test http://localhost:3000
+```
+
+## Local Developer GUI
+
+Start the interactive dashboard for real-time contract monitoring:
+
+```bash
+npx heicat watch --port 3333
+```
+
+**Features:**
+- **Dark Mode**: Modern ShadCN-inspired dark theme
+- **Real-time Monitoring**: Auto-updates every 3 seconds
+- **Violation Dashboard**: Live statistics and detailed violation logs
+- **Contract Status**: Shows loaded contracts and monitoring status
+- **Responsive Design**: Works on desktop and mobile devices
+
+**Dashboard Includes:**
+- **Statistics Cards**: Total violations, errors, and warnings with icons
+- **Status Indicator**: Live monitoring status with animated pulse
+- **Violation Details**: Formatted error messages with severity badges
+- **Clear Function**: Reset violation logs for fresh monitoring
+- **Auto-scroll**: Smooth scrolling for long violation lists
+
+**Design System:**
+- ShadCN-inspired components with proper dark mode colors
+- Inter font for modern typography
+- Consistent spacing and border radius
+- Subtle shadows and hover effects
+- Accessible focus states and keyboard navigation
+
+Runs locally at `http://localhost:3333` with no authentication required.
+
+## Development
+
+### Monorepo Setup
+
+This is a monorepo managed with NPM workspaces.
+
+```bash
+# Install all dependencies
+npm install
+
+# Build all packages
+npm run build
+
+# Build individual packages
+npm run build:core
+npm run build:cli
+
+# Run tests
+npm test
+
+# Clean build artifacts
+npm run clean
+```
+
+### Publishing
+
+```bash
+# Bump version and publish all packages
+npm run release
+
+# Or publish individually
+cd packages/core && npm publish
+cd packages/cli && npm publish
+```
+
+### Example App
+
+```bash
+# Run the example Express app
+cd examples/express-app
+npm install
+npm start
+
+# Start GUI dashboard
+npm run watch
+```
+
+## Project Structure
+
+```
+heicat/
+├── packages/
+│   ├── core/           # Runtime middleware package
+│   └── cli/            # CLI tools package
+├── examples/
+│   └── express-app/    # Example implementation
+├── package.json        # Monorepo root
+└── README.md
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT

package/examples/express-app/README.md

@@ -0,0 +1,72 @@
+# Contract Studio Example
+
+A simple Express.js app demonstrating Backend Contract Studio.
+
+## Setup
+
+```bash
+npm install
+```
+
+## Initialize Contracts
+
+The contracts are already created, but you can regenerate them:
+
+```bash
+npm run init-contracts
+```
+
+## Validate Contracts
+
+Check that your contracts are valid:
+
+```bash
+npm run validate-contracts
+```
+
+## View Status
+
+See contract statistics:
+
+```bash
+npm run status
+```
+
+## Run the App
+
+```bash
+npm start
+```
+
+Or for development with auto-restart:
+
+```bash
+npm run dev
+```
+
+## Test the Contracts
+
+Try these requests:
+
+### Create a user (valid):
+```bash
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"password123","name":"John Doe"}'
+```
+
+### Create a user (missing password - should fail):
+```bash
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user2@example.com","name":"Jane Doe"}'
+```
+
+### Login (valid):
+```bash
+curl -X POST http://localhost:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"password123"}'
+```
+
+Watch the console for contract validation messages! ⚡

package/examples/express-app/contracts/auth.contract.json

@@ -0,0 +1,38 @@
+{
+  "method": "POST",
+  "path": "/auth/login",
+  "request": {
+    "body": {
+      "email": {
+        "type": "string",
+        "required": true
+      },
+      "password": {
+        "type": "string",
+        "required": true
+      }
+    }
+  },
+  "response": {
+    "200": {
+      "token": {
+        "type": "string"
+      },
+      "user": {
+        "id": {
+          "type": "string"
+        },
+        "email": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "errors": {
+    "401": {
+      "message": {
+        "type": "string"
+      }
+    }
+  }
+}

package/examples/express-app/contracts/users.contract.json

@@ -0,0 +1,49 @@
+{
+  "method": "POST",
+  "path": "/users",
+  "auth": "jwt",
+  "request": {
+    "body": {
+      "email": {
+        "type": "string",
+        "required": true
+      },
+      "password": {
+        "type": "string",
+        "minLength": 8,
+        "required": true
+      },
+      "name": {
+        "type": "string"
+      }
+    }
+  },
+  "response": {
+    "201": {
+      "id": {
+        "type": "string"
+      },
+      "email": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "createdAt": {
+        "type": "string"
+      }
+    }
+  },
+  "errors": {
+    "400": {
+      "message": {
+        "type": "string"
+      }
+    },
+    "409": {
+      "message": {
+        "type": "string"
+      }
+    }
+  }
+}

package/examples/express-app/debug.js

@@ -0,0 +1,13 @@
+const { loadContracts } = require('@contract-studio/core');
+
+async function debug() {
+  try {
+    console.log('Loading contracts from ./contracts...');
+    const contracts = await loadContracts('./contracts');
+    console.log(`Found ${contracts.length} contracts:`, contracts.map(c => `${c.method} ${c.path}`));
+  } catch (error) {
+    console.error('Error loading contracts:', error);
+  }
+}
+
+debug();