heicat-cli 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "heicat-cli",
+  "version": "0.1.0",
+  "description": "CLI tools for Heicat",
+  "bin": {
+    "heicat": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "api",
+    "contract",
+    "validation",
+    "cli",
+    "nodejs"
+  ],
+  "author": "Backend Contract Studio",
+  "license": "MIT",
+  "dependencies": {
+    "heicat-core": "^0.1.0",
+    "chalk": "^5.0.0",
+    "commander": "^11.0.0",
+    "inquirer": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { initCommand } from './commands/init';
+import { validateCommand } from './commands/validate';
+import { statusCommand } from './commands/status';
+import { watchCommand } from './commands/watch';
+import { testCommand } from './commands/test';
+
+const program = new Command();
+
+program
+  .name('heicat')
+  .description('Runtime-enforced API contract system for Node.js')
+  .version('0.1.0');
+
+program
+  .command('init')
+  .description('Initialize contract studio in your project')
+  .option('--contracts-path <path>', 'Path to contracts directory', './contracts')
+  .action(initCommand);
+
+program
+  .command('validate')
+  .description('Validate contracts in your project')
+  .option('--contracts-path <path>', 'Path to contracts directory', './contracts')
+  .action(validateCommand);
+
+program
+  .command('status')
+  .description('Show contract validation status')
+  .option('--contracts-path <path>', 'Path to contracts directory', './contracts')
+  .action(statusCommand);
+
+program
+  .command('watch')
+  .description('Watch contracts and start local GUI server')
+  .option('--contracts-path <path>', 'Path to contracts directory', './contracts')
+  .option('--port <port>', 'Port for GUI server', '3333')
+  .action(watchCommand);
+
+program
+  .command('test')
+  .description('Test contracts against a running server')
+  .argument('<url>', 'Server URL to test against')
+  .option('--contracts-path <path>', 'Path to contracts directory', './contracts')
+  .action(testCommand);
+
+program.parse();

package/src/commands/init.ts

@@ -0,0 +1,103 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { Command } from 'commander';
+import chalk from 'chalk';
+
+export function initCommand(options: { contractsPath: string }) {
+  const contractsPath = resolve(process.cwd(), options.contractsPath);
+
+  try {
+    // Create contracts directory
+    mkdirSync(contractsPath, { recursive: true });
+    console.log(chalk.green(`✅ Created contracts directory: ${contractsPath}`));
+
+    // Create example contracts
+    const usersContract = {
+      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' }
+        }
+      }
+    };
+
+    const authContract = {
+      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' }
+        }
+      }
+    };
+
+    writeFileSync(
+      resolve(contractsPath, 'users.contract.json'),
+      JSON.stringify(usersContract, null, 2)
+    );
+
+    writeFileSync(
+      resolve(contractsPath, 'auth.contract.json'),
+      JSON.stringify(authContract, null, 2)
+    );
+
+    console.log(chalk.green('✅ Created example contracts:'));
+    console.log(chalk.gray('  - users.contract.json'));
+    console.log(chalk.gray('  - auth.contract.json'));
+
+    // Check if package.json exists and suggest middleware setup
+    const packageJsonPath = resolve(process.cwd(), 'package.json');
+    let hasPackageJson = false;
+    try {
+      require(packageJsonPath);
+      hasPackageJson = true;
+    } catch {}
+
+    if (hasPackageJson) {
+      console.log('\n' + chalk.blue('📝 Next steps:'));
+      console.log(chalk.gray('1. Install the core package: npm install @heicat/core'));
+      console.log(chalk.gray('2. Add middleware to your Express app:'));
+      console.log(chalk.gray('   const { contractMiddleware } = require("@heicat/core");'));
+      console.log(chalk.gray('   app.use(contractMiddleware({ contractsPath: "./contracts", mode: "dev" }));'));
+    }
+
+  } catch (error) {
+    console.error(chalk.red('❌ Failed to initialize contract studio:'), error);
+    process.exit(1);
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,75 @@
+import { readdirSync, readFileSync } from 'fs';
+import { resolve, extname } from 'path';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { Contract } from 'heicat-core';
+
+export function statusCommand(options: { contractsPath: string }) {
+  const contractsPath = resolve(process.cwd(), options.contractsPath);
+
+  try {
+    const files = readdirSync(contractsPath)
+      .filter(file => extname(file) === '.json' && file.endsWith('.contract.json'));
+
+    if (files.length === 0) {
+      console.log(chalk.yellow('⚠️  No contract files found in'), contractsPath);
+      return;
+    }
+
+    const contracts: Contract[] = [];
+    const methods = new Set<string>();
+    const paths = new Set<string>();
+
+    for (const file of files) {
+      const filePath = resolve(contractsPath, file);
+      const content = readFileSync(filePath, 'utf-8');
+
+      try {
+        const contract = JSON.parse(content) as Contract;
+        contracts.push(contract);
+
+        if (contract.method) methods.add(contract.method.toUpperCase());
+        if (contract.path) paths.add(contract.path);
+
+      } catch (error) {
+        // Skip invalid contracts
+      }
+    }
+
+    console.log(chalk.blue('📊 Heicat Status'));
+    console.log(chalk.gray('─'.repeat(40)));
+
+    console.log(chalk.green(`📁 Contracts: ${contracts.length}`));
+    console.log(chalk.green(`🔗 Endpoints: ${contracts.length}`));
+    console.log(chalk.green(`📋 Methods: ${Array.from(methods).join(', ')}`));
+
+    // Group by method
+    const byMethod = contracts.reduce((acc, contract) => {
+      const method = contract.method.toUpperCase();
+      if (!acc[method]) acc[method] = [];
+      acc[method].push(contract.path);
+      return acc;
+    }, {} as Record<string, string[]>);
+
+    console.log('\n' + chalk.blue('📋 Endpoints by Method:'));
+    for (const [method, paths] of Object.entries(byMethod)) {
+      console.log(chalk.gray(`  ${method}: ${paths.length} endpoint${paths.length !== 1 ? 's' : ''}`));
+      paths.forEach(path => console.log(chalk.gray(`    ${path}`)));
+    }
+
+    // Check for potential issues
+    const duplicatePaths = contracts
+      .map(c => `${c.method.toUpperCase()} ${c.path}`)
+      .filter((item, index, arr) => arr.indexOf(item) !== index);
+
+    if (duplicatePaths.length > 0) {
+      console.log('\n' + chalk.yellow('⚠️  Potential Issues:'));
+      console.log(chalk.yellow('  Duplicate endpoints found:'));
+      duplicatePaths.forEach(path => console.log(chalk.yellow(`    ${path}`)));
+    }
+
+  } catch (error) {
+    console.error(chalk.red('❌ Failed to read contract status:'), error);
+    process.exit(1);
+  }
+}

package/src/commands/test.ts

@@ -0,0 +1,188 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { readFileSync, readdirSync } from 'fs';
+import { resolve, extname } from 'path';
+import { Contract } from 'heicat-core';
+
+interface TestResult {
+  contract: string;
+  endpoint: string;
+  success: boolean;
+  error?: string;
+  responseTime?: number;
+}
+
+export async function testCommand(url: string, options: { contractsPath: string }) {
+  const contractsPath = resolve(process.cwd(), options.contractsPath);
+  const baseUrl = url.replace(/\/$/, ''); // Remove trailing slash
+
+  console.log(chalk.blue('🧪 Testing Contracts Against Server'));
+  console.log(chalk.gray(`📍 Server: ${baseUrl}`));
+  console.log(chalk.gray(`📁 Contracts: ${contractsPath}`));
+  console.log('');
+
+  try {
+    // Load contracts
+    const files = readdirSync(contractsPath)
+      .filter(file => extname(file) === '.json' && file.endsWith('.contract.json'));
+
+    if (files.length === 0) {
+      console.log(chalk.yellow('⚠️  No contract files found'));
+      return;
+    }
+
+    const contracts: Contract[] = [];
+    for (const file of files) {
+      const filePath = resolve(contractsPath, file);
+      const content = readFileSync(filePath, 'utf-8');
+      contracts.push(JSON.parse(content));
+    }
+
+    console.log(chalk.blue(`📋 Testing ${contracts.length} contract${contracts.length !== 1 ? 's' : ''}`));
+    console.log('');
+
+    const results: TestResult[] = [];
+
+    for (const contract of contracts) {
+      const endpoint = `${contract.method} ${contract.path}`;
+      console.log(chalk.gray(`Testing: ${endpoint}`));
+
+      try {
+        const result = await testContract(baseUrl, contract);
+        results.push(result);
+
+        if (result.success) {
+          console.log(chalk.green(`  ✅ ${endpoint} (${result.responseTime}ms)`));
+        } else {
+          console.log(chalk.red(`  ❌ ${endpoint}: ${result.error}`));
+        }
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+        results.push({
+          contract: contract.path,
+          endpoint,
+          success: false,
+          error: errorMsg
+        });
+        console.log(chalk.red(`  ❌ ${endpoint}: ${errorMsg}`));
+      }
+    }
+
+    // Summary
+    console.log('');
+    console.log(chalk.blue('📊 Test Results'));
+    console.log(chalk.gray('─'.repeat(40)));
+
+    const passed = results.filter(r => r.success).length;
+    const failed = results.filter(r => !r.success).length;
+
+    console.log(chalk.green(`✅ Passed: ${passed}`));
+    console.log(chalk.red(`❌ Failed: ${failed}`));
+
+    if (failed > 0) {
+      console.log('');
+      console.log(chalk.red('❌ Failed Tests:'));
+      results.filter(r => !r.success).forEach(result => {
+        console.log(chalk.red(`  • ${result.endpoint}: ${result.error}`));
+      });
+      process.exit(1);
+    } else {
+      console.log('');
+      console.log(chalk.green('🎉 All contract tests passed!'));
+    }
+
+  } catch (error) {
+    console.error(chalk.red('❌ Test failed:'), error);
+    process.exit(1);
+  }
+}
+
+async function testContract(baseUrl: string, contract: Contract): Promise<TestResult> {
+  const startTime = Date.now();
+  const endpoint = `${contract.method} ${contract.path}`;
+
+  try {
+    // For now, just test that the endpoint exists and returns valid JSON
+    // In a real implementation, this would test the full contract validation
+    const url = `${baseUrl}${contract.path}`;
+
+    const response = await fetch(url, {
+      method: contract.method,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      // For POST requests, send minimal valid body if defined
+      body: contract.method === 'POST' && contract.request?.body
+        ? JSON.stringify(createMinimalBody(contract.request.body))
+        : undefined
+    });
+
+    const responseTime = Date.now() - startTime;
+
+    if (!response.ok) {
+      return {
+        contract: contract.path,
+        endpoint,
+        success: false,
+        error: `HTTP ${response.status}: ${response.statusText}`,
+        responseTime
+      };
+    }
+
+    // Try to parse JSON response
+    try {
+      const data = await response.json();
+      return {
+        contract: contract.path,
+        endpoint,
+        success: true,
+        responseTime
+      };
+    } catch {
+      return {
+        contract: contract.path,
+        endpoint,
+        success: false,
+        error: 'Response is not valid JSON',
+        responseTime
+      };
+    }
+
+  } catch (error) {
+    const responseTime = Date.now() - startTime;
+    const errorMsg = error instanceof Error ? error.message : 'Network error';
+    return {
+      contract: contract.path,
+      endpoint,
+      success: false,
+      error: errorMsg,
+      responseTime
+    };
+  }
+}
+
+function createMinimalBody(schema: Record<string, any>): Record<string, any> {
+  const body: Record<string, any> = {};
+
+  for (const [key, fieldSchema] of Object.entries(schema)) {
+    if (typeof fieldSchema === 'object' && fieldSchema.type) {
+      if (fieldSchema.required === false) continue;
+
+      switch (fieldSchema.type) {
+        case 'string':
+          body[key] = fieldSchema.minLength ? 'a'.repeat(fieldSchema.minLength) : 'test';
+          break;
+        case 'number':
+          body[key] = fieldSchema.minimum || 1;
+          break;
+        case 'boolean':
+          body[key] = true;
+          break;
+        default:
+          body[key] = 'test';
+      }
+    }
+  }
+
+  return body;
+}

package/src/commands/validate.ts

@@ -0,0 +1,73 @@
+import { readdirSync, readFileSync } from 'fs';
+import { resolve, extname } from 'path';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { Contract } from 'heicat-core';
+
+export function validateCommand(options: { contractsPath: string }) {
+  const contractsPath = resolve(process.cwd(), options.contractsPath);
+
+  try {
+    const files = readdirSync(contractsPath)
+      .filter(file => extname(file) === '.json' && file.endsWith('.contract.json'));
+
+    if (files.length === 0) {
+      console.log(chalk.yellow('⚠️  No contract files found in'), contractsPath);
+      return;
+    }
+
+    let validCount = 0;
+    let invalidCount = 0;
+
+    for (const file of files) {
+      const filePath = resolve(contractsPath, file);
+      const content = readFileSync(filePath, 'utf-8');
+
+      try {
+        const contract = JSON.parse(content) as Contract;
+
+        // Basic validation
+        const errors: string[] = [];
+
+        if (!contract.method) {
+          errors.push('Missing required field: method');
+        }
+
+        if (!contract.path) {
+          errors.push('Missing required field: path');
+        }
+
+        if (contract.method && typeof contract.method !== 'string') {
+          errors.push('Method must be a string');
+        }
+
+        if (contract.path && typeof contract.path !== 'string') {
+          errors.push('Path must be a string');
+        }
+
+        if (errors.length > 0) {
+          console.log(chalk.red(`❌ ${file}:`));
+          errors.forEach(error => console.log(chalk.red(`   ${error}`)));
+          invalidCount++;
+        } else {
+          console.log(chalk.green(`✅ ${file}`));
+          validCount++;
+        }
+
+      } catch (error) {
+        console.log(chalk.red(`❌ ${file}: Invalid JSON`));
+        invalidCount++;
+      }
+    }
+
+    console.log('\n' + chalk.blue(`📊 Summary: ${validCount} valid, ${invalidCount} invalid`));
+
+    if (invalidCount > 0) {
+      process.exit(1);
+    }
+
+  } catch (error) {
+    console.error(chalk.red('❌ Failed to validate contracts:'), error);
+    process.exit(1);
+  }
+}