cerber-core 1.0.0

package/team/lib/module-system.ts

@@ -0,0 +1,157 @@
+/**
+ * Cerber TEAM - Module System
+ * 
+ * @author Stefan Pitek
+ * @copyright 2026 Stefan Pitek
+ * @license MIT
+ */
+
+export interface Module {
+  name: string;
+  owner: string;
+  status: 'active' | 'deprecated' | 'planned';
+  path: string;
+}
+
+export interface ModuleContract {
+  version: string;
+  publicInterface: Record<string, FunctionSignature>;
+  dependencies: string[];
+}
+
+export interface FunctionSignature {
+  name: string;
+  params: Record<string, string>;
+  returns: string;
+  description: string;
+}
+
+export interface Connection {
+  id: string;
+  from: string;
+  to: string;
+  type: 'function-call' | 'event' | 'data-flow';
+  interface: any;
+  version?: string;
+  breaking_changes?: string[];
+  notes?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Load module metadata from MODULE.md
+ * 
+ * @todo Implementation pending - use bash scripts for now
+ */
+export function loadModule(moduleName: string): Module {
+  // TODO: Implementation would read from .cerber/modules/{moduleName}/MODULE.md
+  // For now, use: bash team/scripts/cerber-focus.sh <module-name>
+  throw new Error('Not implemented - use bash scripts for now');
+}
+
+/**
+ * Load module contract from contract.json
+ * 
+ * @todo Implementation pending - use bash scripts for now
+ */
+export function loadContract(moduleName: string): ModuleContract {
+  // TODO: Implementation would read from .cerber/modules/{moduleName}/contract.json
+  throw new Error('Not implemented - use bash scripts for now');
+}
+
+/**
+ * Validate a single module for compliance
+ * 
+ * @todo Implementation pending - use cerber-module-check.sh
+ */
+export function validateModule(moduleName: string): ValidationResult {
+  // TODO: Implementation would check:
+  // - MODULE.md exists and has required sections
+  // - contract.json is valid JSON with required fields
+  // - dependencies.json references valid modules
+  // - No forbidden cross-module imports
+  // For now, use: bash team/scripts/cerber-module-check.sh <module-name>
+  throw new Error('Not implemented - use cerber-module-check.sh');
+}
+
+/**
+ * Validate all connection contracts
+ * 
+ * @todo Implementation pending - use cerber-connections-check.sh
+ */
+export function validateConnections(): ValidationResult[] {
+  // TODO: Implementation would check:
+  // - All connections have both sides
+  // - Input/output types match
+  // - No circular dependencies
+  // - Breaking changes detected
+  // For now, use: bash team/scripts/cerber-connections-check.sh
+  throw new Error('Not implemented - use cerber-connections-check.sh');
+}
+
+/**
+ * Create focus context for a module
+ * 
+ * Generates FOCUS_CONTEXT.md containing:
+ * - MODULE.md content
+ * - contract.json interface
+ * - dependencies.json
+ * - Connection contracts with other modules
+ * 
+ * @todo Implementation pending - use cerber-focus.sh
+ */
+export function createFocusContext(moduleName: string): string {
+  // TODO: Implementation would concatenate:
+  // - .cerber/modules/{moduleName}/MODULE.md
+  // - .cerber/modules/{moduleName}/contract.json
+  // - .cerber/modules/{moduleName}/dependencies.json
+  // - All connection contracts mentioning this module
+  // For now, use: bash team/scripts/cerber-focus.sh <module-name>
+  throw new Error('Not implemented - use cerber-focus.sh');
+}
+
+/**
+ * Get list of all modules
+ * 
+ * @todo Implementation pending - use bash to list directories
+ */
+export function listModules(): Module[] {
+  // TODO: Implementation would scan .cerber/modules directory
+  throw new Error('Not implemented - use bash to list .cerber/modules');
+}
+
+/**
+ * Get module dependencies
+ * 
+ * @todo Implementation pending - parse dependencies.json
+ */
+export function getModuleDependencies(moduleName: string): string[] {
+  // TODO: Implementation would read dependencies.json
+  throw new Error('Not implemented - parse dependencies.json directly');
+}
+
+/**
+ * Check for circular dependencies
+ * 
+ * @todo Implementation pending - use cerber-connections-check.sh
+ */
+export function detectCircularDependencies(): string[][] {
+  // TODO: Implementation would build dependency graph and detect cycles
+  // For now, use: bash team/scripts/cerber-connections-check.sh
+  throw new Error('Not implemented - use cerber-connections-check.sh');
+}
+
+/**
+ * Get connection contracts for a module
+ * 
+ * @todo Implementation pending - grep connection contracts
+ */
+export function getModuleConnections(moduleName: string): Connection[] {
+  // TODO: Implementation would find all contracts mentioning the module
+  throw new Error('Not implemented - grep .cerber/connections/contracts');
+}

package/team/scripts/cerber-add-module.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+# Cerber TEAM - Add New Module
+# 
+# Author: Stefan Pitek
+# Copyright: 2026 Stefan Pitek
+# License: MIT
+#
+# Creates a new module from template with all required files
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+# Check if module name provided
+if [ -z "$1" ]; then
+    echo -e "${RED}❌ Error: Module name required${NC}"
+    echo ""
+    echo "Usage: bash team/scripts/cerber-add-module.sh <module-name>"
+    echo ""
+    echo "Example:"
+    echo "  bash team/scripts/cerber-add-module.sh payment-gateway"
+    echo ""
+    echo "Module naming conventions:"
+    echo "  - Use kebab-case (lowercase with hyphens)"
+    echo "  - Be descriptive but concise"
+    echo "  - Examples: pricing-engine, user-auth, payment-gateway"
+    exit 1
+fi
+
+MODULE_NAME="$1"
+MODULE_DIR=".cerber/modules/${MODULE_NAME}"
+TEMPLATE_DIR="team/templates"
+
+echo ""
+echo "🆕 Creating new module: ${MODULE_NAME}"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Check if module already exists
+if [ -d "$MODULE_DIR" ]; then
+    echo -e "${RED}❌ Error: Module '${MODULE_NAME}' already exists${NC}"
+    echo ""
+    echo "Module directory: ${MODULE_DIR}"
+    echo ""
+    echo "To work on this module, use:"
+    echo "  bash team/scripts/cerber-focus.sh ${MODULE_NAME}"
+    exit 1
+fi
+
+# Create module directory
+echo "Creating module directory..."
+mkdir -p "$MODULE_DIR"
+echo -e "${GREEN}✅${NC} Created ${MODULE_DIR}/"
+
+# Copy MODULE.md from template
+echo ""
+echo "Creating MODULE.md from template..."
+if [ -f "${TEMPLATE_DIR}/MODULE_TEMPLATE.md" ]; then
+    cp "${TEMPLATE_DIR}/MODULE_TEMPLATE.md" "${MODULE_DIR}/MODULE.md"
+    
+    # Replace placeholder with actual module name
+    # Using sed -i.bak for cross-platform compatibility (works on both Linux and macOS)
+    sed -i.bak "s/\[MODULE_NAME\]/${MODULE_NAME}/g" "${MODULE_DIR}/MODULE.md"
+    rm -f "${MODULE_DIR}/MODULE.md.bak"
+    
+    # Update date
+    CURRENT_DATE=$(date '+%Y-%m-%d')
+    sed -i.bak "s/YYYY-MM-DD/${CURRENT_DATE}/g" "${MODULE_DIR}/MODULE.md"
+    rm -f "${MODULE_DIR}/MODULE.md.bak"
+    
+    echo -e "${GREEN}✅${NC} MODULE.md created from template"
+else
+    echo -e "${YELLOW}⚠️${NC}  Template not found, creating basic MODULE.md"
+    cat > "${MODULE_DIR}/MODULE.md" <<EOF
+# Module: ${MODULE_NAME}
+
+**Owner:** [Your Name]
+**Status:** Active
+**Last Updated:** $(date '+%Y-%m-%d')
+
+## Purpose
+
+What this module does.
+
+## Responsibilities
+
+- Responsibility 1
+- Responsibility 2
+
+## Public Interface
+
+Functions/classes that other modules can use.
+
+## Dependencies
+
+Modules this module uses.
+EOF
+    echo -e "${GREEN}✅${NC} Basic MODULE.md created"
+fi
+
+# Create contract.json
+echo ""
+echo "Creating contract.json..."
+cat > "${MODULE_DIR}/contract.json" <<EOF
+{
+  "version": "1.0.0",
+  "publicInterface": {},
+  "dependencies": []
+}
+EOF
+echo -e "${GREEN}✅${NC} contract.json initialized"
+
+# Create dependencies.json
+echo ""
+echo "Creating dependencies.json..."
+cat > "${MODULE_DIR}/dependencies.json" <<EOF
+{
+  "dependencies": []
+}
+EOF
+echo -e "${GREEN}✅${NC} dependencies.json created"
+
+# Update BIBLE.md if it exists
+BIBLE_PATH=".cerber/BIBLE.md"
+if [ -f "$BIBLE_PATH" ]; then
+    echo ""
+    echo "Updating BIBLE.md..."
+    
+    # Add module entry to BIBLE.md
+    if ! grep -q "${MODULE_NAME}" "$BIBLE_PATH"; then
+        # Try to add after "### Core Modules" section
+        if grep -q "### Core Modules" "$BIBLE_PATH"; then
+            # Find line number and insert after it
+            LINE_NUM=$(grep -n "### Core Modules" "$BIBLE_PATH" | head -1 | cut -d: -f1)
+            LINE_NUM=$((LINE_NUM + 2))
+            
+            # Create backup
+            cp "$BIBLE_PATH" "${BIBLE_PATH}.bak"
+            
+            # Insert new module entry
+            head -n $LINE_NUM "${BIBLE_PATH}.bak" > "$BIBLE_PATH"
+            echo "" >> "$BIBLE_PATH"
+            echo "**${MODULE_NAME}** - [Add description]" >> "$BIBLE_PATH"
+            echo "   - Owner: [Your Name]" >> "$BIBLE_PATH"
+            echo "   - Status: Active" >> "$BIBLE_PATH"
+            echo "   - Files: \`src/modules/${MODULE_NAME}/\`" >> "$BIBLE_PATH"
+            echo "" >> "$BIBLE_PATH"
+            tail -n +$((LINE_NUM + 1)) "${BIBLE_PATH}.bak" >> "$BIBLE_PATH"
+            
+            rm -f "${BIBLE_PATH}.bak"
+            echo -e "${GREEN}✅${NC} BIBLE.md updated with new module"
+        else
+            echo -e "${YELLOW}⚠️${NC}  Could not find '### Core Modules' section in BIBLE.md"
+            echo "     Please manually add module to BIBLE.md"
+        fi
+    else
+        echo -e "${BLUE}ℹ️${NC}  Module already exists in BIBLE.md"
+    fi
+else
+    echo ""
+    echo -e "${YELLOW}⚠️${NC}  BIBLE.md not found at ${BIBLE_PATH}"
+    echo "     Consider creating a project BIBLE.md with:"
+    echo "     cp team/templates/BIBLE_TEMPLATE.md .cerber/BIBLE.md"
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo -e "${GREEN}✅ Module '${MODULE_NAME}' created successfully!${NC}"
+echo ""
+echo "Module location: ${CYAN}${MODULE_DIR}/${NC}"
+echo ""
+echo "Next steps:"
+echo "  1. Edit module documentation:"
+echo "     ${CYAN}nano ${MODULE_DIR}/MODULE.md${NC}"
+echo ""
+echo "  2. Define public interface in:"
+echo "     ${CYAN}nano ${MODULE_DIR}/contract.json${NC}"
+echo ""
+echo "  3. List dependencies in:"
+echo "     ${CYAN}nano ${MODULE_DIR}/dependencies.json${NC}"
+echo ""
+echo "  4. Enter focus mode to work on this module:"
+echo "     ${CYAN}bash team/scripts/cerber-focus.sh ${MODULE_NAME}${NC}"
+echo ""
+echo "  5. Validate your module:"
+echo "     ${CYAN}bash team/scripts/cerber-module-check.sh ${MODULE_NAME}${NC}"
+echo ""
+
+exit 0

package/team/scripts/cerber-connections-check.sh

@@ -0,0 +1,186 @@
+#!/bin/bash
+# Cerber TEAM - Connection Contract Validation
+# 
+# Author: Stefan Pitek
+# Copyright: 2026 Stefan Pitek
+# License: MIT
+#
+# Validates all connection contracts between modules
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+CONNECTIONS_DIR=".cerber/connections/contracts"
+ERRORS=0
+WARNINGS=0
+CHECKED=0
+
+echo ""
+echo "🔗 Checking connection contracts..."
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Check if connections directory exists
+if [ ! -d "$CONNECTIONS_DIR" ]; then
+    echo -e "${YELLOW}⚠️  No connections directory found${NC}"
+    echo ""
+    echo "Expected: ${CONNECTIONS_DIR}"
+    echo ""
+    echo "If you have modules with connections, create connection contracts:"
+    echo "  mkdir -p ${CONNECTIONS_DIR}"
+    echo "  cp team/templates/CONNECTION_TEMPLATE.json ${CONNECTIONS_DIR}/module-a-to-module-b.json"
+    echo ""
+    exit 0
+fi
+
+# Check if any contracts exist
+CONTRACT_COUNT=$(find "$CONNECTIONS_DIR" -name "*.json" 2>/dev/null | wc -l)
+
+if [ "$CONTRACT_COUNT" -eq 0 ]; then
+    echo -e "${BLUE}ℹ️${NC}  No connection contracts found"
+    echo ""
+    echo "This is OK if modules don't communicate yet."
+    echo ""
+    echo "To create a connection contract:"
+    echo "  cp team/templates/CONNECTION_TEMPLATE.json ${CONNECTIONS_DIR}/module-a-to-module-b.json"
+    echo ""
+    exit 0
+fi
+
+echo "Found ${CONTRACT_COUNT} connection contract(s)"
+echo ""
+
+# Track connections for circular dependency detection
+declare -A connections
+
+# Process each contract
+for contract in "$CONNECTIONS_DIR"/*.json; do
+    if [ ! -f "$contract" ]; then
+        continue
+    fi
+    
+    CHECKED=$((CHECKED + 1))
+    CONTRACT_NAME=$(basename "$contract")
+    
+    echo "Checking: ${CONTRACT_NAME}"
+    
+    # Validate JSON syntax
+    if ! python3 -m json.tool "$contract" >/dev/null 2>&1 && \
+       ! node -e "JSON.parse(require('fs').readFileSync('$contract', 'utf8'))" 2>/dev/null; then
+        echo -e "  ${RED}❌${NC} Invalid JSON syntax"
+        ERRORS=$((ERRORS + 1))
+        continue
+    fi
+    
+    # Extract from and to modules
+    FROM_MODULE=$(grep -o '"from"[[:space:]]*:[[:space:]]*"[^"]*"' "$contract" | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+    TO_MODULE=$(grep -o '"to"[[:space:]]*:[[:space:]]*"[^"]*"' "$contract" | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
+    
+    if [ -z "$FROM_MODULE" ] || [ -z "$TO_MODULE" ]; then
+        echo -e "  ${RED}❌${NC} Missing 'from' or 'to' field"
+        ERRORS=$((ERRORS + 1))
+        continue
+    fi
+    
+    # Store connection for circular check
+    connections["${FROM_MODULE}->${TO_MODULE}"]=1
+    
+    # Check if modules exist
+    FROM_EXISTS=false
+    TO_EXISTS=false
+    
+    if [ -d ".cerber/modules/${FROM_MODULE}" ]; then
+        FROM_EXISTS=true
+    fi
+    
+    if [ -d ".cerber/modules/${TO_MODULE}" ]; then
+        TO_EXISTS=true
+    fi
+    
+    if [ "$FROM_EXISTS" = true ] && [ "$TO_EXISTS" = true ]; then
+        echo -e "  ${GREEN}✅${NC} ${FROM_MODULE} → ${TO_MODULE} (valid)"
+    else
+        if [ "$FROM_EXISTS" = false ]; then
+            echo -e "  ${RED}❌${NC} Module '${FROM_MODULE}' not found"
+            ERRORS=$((ERRORS + 1))
+        fi
+        if [ "$TO_EXISTS" = false ]; then
+            echo -e "  ${RED}❌${NC} Module '${TO_MODULE}' not found"
+            ERRORS=$((ERRORS + 1))
+        fi
+    fi
+    
+    # Check required fields
+    HAS_INTERFACE=$(grep -q '"interface"' "$contract" && echo "true" || echo "false")
+    HAS_VERSION=$(grep -q '"version"' "$contract" && echo "true" || echo "false")
+    
+    if [ "$HAS_INTERFACE" = false ]; then
+        echo -e "  ${YELLOW}⚠️${NC}  Missing 'interface' field"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+    
+    if [ "$HAS_VERSION" = false ]; then
+        echo -e "  ${YELLOW}⚠️${NC}  Missing 'version' field"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+    
+    # Check for breaking changes field
+    if ! grep -q '"breaking_changes"' "$contract"; then
+        echo -e "  ${YELLOW}⚠️${NC}  Missing 'breaking_changes' field (recommended for versioning)"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+    
+    echo ""
+done
+
+# Check for circular dependencies (simple check)
+echo "Checking for circular dependencies..."
+CIRCULAR_FOUND=false
+
+for key in "${!connections[@]}"; do
+    FROM=$(echo "$key" | cut -d'-' -f1)
+    TO=$(echo "$key" | cut -d'>' -f2)
+    
+    # Check if reverse connection exists
+    if [ -n "${connections[${TO}->${FROM}]}" ]; then
+        echo -e "${YELLOW}⚠️${NC}  Potential circular dependency: ${FROM} ↔ ${TO}"
+        CIRCULAR_FOUND=true
+        WARNINGS=$((WARNINGS + 1))
+    fi
+done
+
+if [ "$CIRCULAR_FOUND" = false ]; then
+    echo -e "${GREEN}✅${NC} No circular dependencies detected"
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Summary
+if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
+    echo -e "${GREEN}✅ ALL CONNECTION CHECKS PASSED${NC}"
+    echo ""
+    echo "All ${CHECKED} connection contract(s) are valid!"
+    echo ""
+    exit 0
+elif [ $ERRORS -eq 0 ]; then
+    echo -e "${YELLOW}⚠️  CONNECTION CHECKS PASSED WITH WARNINGS${NC}"
+    echo ""
+    echo "Checked ${CHECKED} contract(s)"
+    echo "Found ${WARNINGS} warning(s)"
+    echo ""
+    exit 0
+else
+    echo -e "${RED}❌ CONNECTION CHECK FAILED${NC}"
+    echo ""
+    echo "Checked ${CHECKED} contract(s)"
+    echo "Found ${ERRORS} error(s) and ${WARNINGS} warning(s)"
+    echo ""
+    exit 1
+fi