┌─────────────────────────────────────────────────────────────────┐
│           Infrastructure as Code Principles                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐     │
│  │   Version    │───▶│    Test      │───▶│   Deploy     │     │
│  │   Control    │    │  Automation  │    │  Automation  │     │
│  └──────────────┘    └──────────────┘    └──────────────┘     │
│         │                   │                   │                │
│         ▼                   ▼                   ▼                │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐     │
│  │   Audit      │    │   Collaborate│    │   Scale      │     │
│  │   Trail      │    │   & Review   │    │   Confidently│     │
│  └──────────────┘    └──────────────┘    └──────────────┘     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

// workflow-definition.ts
import { Workflow, Node, Connection } from 'n8n-as-code';

export const customerOnboardingWorkflow = new Workflow({
  name: 'Customer Onboarding',
  id: 'customer-onboarding-v2',
  
  nodes: [
    {
      name: 'Webhook Trigger',
      type: 'n8n-nodes-base.webhook',
      parameters: {
        httpMethod: 'POST',
        path: 'onboard-customer',
        responseMode: 'responseNode'
      },
      position: [250, 300]
    },
    {
      name: 'Validate Input',
      type: 'n8n-nodes-base.function',
      parameters: {
        functionCode: `
          const required = ['email', 'company', 'plan'];
          const missing = required.filter(field => !items[0].json[field]);
          
          if (missing.length > 0) {
            throw new Error(\`Missing required fields: \${missing.join(', ')}\`);
          }
          
          return [{
            json: {
              ...items[0].json,
              validated: true,
              timestamp: new Date().toISOString()
            }
          }];
        `
      },
      position: [450, 300]
    },
    {
      name: 'Create CRM Record',
      type: 'n8n-nodes-base.salesforce',
      parameters: {
        resource: 'contact',
        operation: 'create',
        additionalFields: {
          Email: '={{ $input.email }}',
          Company: '={{ $input.company }}',
          LeadSource: 'Web Signup'
        }
      },
      position: [650, 300]
    },
    {
      name: 'Send Welcome Email',
      type: 'n8n-nodes-base.sendGrid',
      parameters: {
        fromEmail: '[email protected]',
        toEmail: '={{ $input.email }}',
        subject: 'Welcome to {{ $input.company }}!',
        html: '<p>Thanks for signing up!</p>'
      },
      position: [850, 300]
    },
    {
      name: 'Success Response',
      type: 'n8n-nodes-base.respondToWebhook',
      parameters: {
        statusCode: 200,
        responseBody: {
          success: true,
          message: 'Onboarding initiated'
        }
      },
      position: [1050, 300]
    }
  ],
  
  connections: {
    'Webhook Trigger': {
      main: [[{ node: 'Validate Input', type: 'main', index: 0 }]]
    },
    'Validate Input': {
      main: [[{ node: 'Create CRM Record', type: 'main', index: 0 }]]
    },
    'Create CRM Record': {
      main: [[{ node: 'Send Welcome Email', type: 'main', index: 0 }]]
    },
    'Send Welcome Email': {
      main: [[{ node: 'Success Response', type: 'main', index: 0 }]]
    }
  },
  
  settings: {
    saveExecutionProgress: true,
    saveManualExecutions: true,
    executionTimeout: 300,
    errorWorkflow: 'error-handling-workflow'
  },
  
  tags: ['customer-success', 'onboarding', 'production']
});

# environments/production.yaml
n8n:
  base_url: https://n8n.company.com
  api_key: ${N8N_API_KEY}
  
webhooks:
  base_url: https://hooks.company.com
  
integrations:
  salesforce:
    instance_url: https://company.my.salesforce.com
    client_id: ${SF_CLIENT_ID}
    client_secret: ${SF_CLIENT_SECRET}
    
  sendgrid:
    api_key: ${SENDGRID_API_KEY}
    from_email: [email protected]
    
  database:
    host: prod-db.company.internal
    port: 5432
    database: n8n_production
    credentials: ${DB_CREDENTIALS}
    
settings:
  execution:
    timeout: 300
    max_retries: 3
    concurrent_limit: 50
    
  security:
    require_auth: true
    mfa_enabled: true
    audit_logging: true

┌─────────────────────────────────────────────────────────────────┐
│                    Git Sync Architecture                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐          ┌──────────────┐                     │
│  │   Local      │◄────────►│   Git Repo   │                     │
│  │   Editor     │   Push   │   (Source)   │                     │
│  │  (VS Code)   │          │   of Truth   │                     │
│  └──────────────┘          └──────┬───────┘                     │
│                                    │                            │
│                                    │ Pull/Merge                  │
│                                    ▼                            │
│                           ┌──────────────┐                      │
│                           │   n8n-as-code│                      │
│                           │     CLI      │                      │
│                           └──────┬───────┘                      │
│                                  │                              │
│              ┌───────────────────┼───────────────────┐         │
│              │                   │                   │          │
│              ▼                   ▼                   ▼          │
│        ┌──────────┐       ┌──────────┐       ┌──────────┐       │
│        │   Dev    │       │  Staging │       │   Prod   │       │
│        │ Instance │       │ Instance │       │ Instance │       │
│        └──────────┘       └──────────┘       └──────────┘       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

# Install globally
npm install -g n8n-as-code

# Or use npx for one-off commands
npx n8n-as-code --help

# Verify installation
n8nac --version
# Output: n8n-as-code v2.1.0

# Create new project
n8nac init my-automation-project

cd my-automation-project

# Project structure created:
# .
# ├── n8n.config.yaml
# ├── workflows/
# │   ├── index.ts
# │   └── examples/
# ├── credentials/
# │   └── index.yaml
# ├── environments/
# │   ├── development.yaml
# │   ├── staging.yaml
# │   └── production.yaml
# ├── tests/
# │   └── workflows/
# ├── scripts/
# │   ├── deploy.sh
# │   └── validate.sh
# └── .github/
#     └── workflows/
#         └── ci-cd.yaml

# n8n.config.yaml
project:
  name: "Company Automation Platform"
  version: "2.0.0"
  description: "Production workflow automation"

instances:
  development:
    url: http://localhost:5678
    api_key: ${N8N_DEV_API_KEY}
    
  staging:
    url: https://n8n-staging.company.com
    api_key: ${N8N_STAGING_API_KEY}
    
  production:
    url: https://n8n.company.com
    api_key: ${N8N_PROD_API_KEY}

sync:
  mode: bidirectional  # or 'push-only', 'pull-only'
  conflict_resolution: manual  # or 'auto-accept-local', 'auto-accept-remote'
  backup_before_sync: true
  
validation:
  strict_mode: true
  require_tests: true
  max_workflow_size: 10MB
  forbidden_nodes:
    - n8n-nodes-base.executeCommand
    - n8n-nodes-base.ssh
    
git:
  commit_message_template: "[n8n] {action}: {workflow_name}"
  auto_commit: false
  branch_naming:
    pattern: "n8n/{workflow_name}/{action}"

# Initialize Git
git init

# Create .gitignore
cat > .gitignore << 'EOF'
# Dependencies
node_modules/

# Environment files
.env
.env.local
.env.*.local

# Credentials (use n8n native credential store)
credentials/*.key
credentials/*.secret

# Runtime
dist/
build/
.cache/

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db
EOF

# Initial commit
git add .
git commit -m "[n8n] Initial project setup"

// workflows/lead-scoring.ts
import { Workflow, Node, If, Merge } from 'n8n-as-code';
import { nodes, logic } from 'n8n-as-code/stdlib';

export default new Workflow({
  name: 'Lead Scoring Automation',
  id: 'lead-scoring-v1',
  
  // Workflow-level settings
  settings: {
    saveExecutionProgress: true,
    executionTimeout: 120,
    errorWorkflow: 'error-handler'
  },
  
  // Trigger nodes
  triggers: [
    nodes.webhook({
      name: 'Lead Webhook',
      method: 'POST',
      path: 'score-lead',
      responseMode: 'responseNode'
    })
  ],
  
  // Processing nodes
  nodes: [
    // Data validation
    nodes.function({
      name: 'Validate Lead Data',
      code: `
        const lead = items[0].json;
        const required = ['email', 'company', 'source'];
        const missing = required.filter(f => !lead[f]);
        
        if (missing.length > 0) {
          return [{ json: { error: \`Missing: \${missing.join(', ')}\` }, pairedItem: 0 }];
        }
        
        // Calculate initial score
        let score = 0;
        if (lead.company?.includes('Enterprise')) score += 20;
        if (lead.source === 'LinkedIn') score += 15;
        if (lead.email?.includes('@company.com')) score += 10;
        
        return [{
          json: {
            ...lead,
            initialScore: score,
            validatedAt: new Date().toISOString()
          }
        }];
      `
    }),
    
    // Enrich with Clearbit
    nodes.httpRequest({
      name: 'Enrich Company Data',
      method: 'GET',
      url: 'https://company.clearbit.com/v2/companies/find',
      authentication: 'genericCredentialType',
      genericAuthType: 'httpHeaderAuth',
      sendQuery: true,
      queryParameters: {
        parameters: [
          {
            name: 'domain',
            value: '={{ $input.email.split("@")[1] }}'
          }
        ]
      }
    }),
    
    // Calculate final score
    nodes.function({
      name: 'Calculate Final Score',
      code: `
        const lead = items[0].json;
        const enrichment = items[0].json.clearbit || {};
        
        let finalScore = lead.initialScore || 0;
        
        // Add enrichment points
        if (enrichment.metrics?.employees) {
          if (enrichment.metrics.employees > 1000) finalScore += 30;
          else if (enrichment.metrics.employees > 500) finalScore += 20;
          else if (enrichment.metrics.employees > 100) finalScore += 10;
        }
        
        if (enrichment.metrics?.raised) {
          const raised = parseInt(enrichment.metrics.raised);
          if (raised > 100000000) finalScore += 25;
          else if (raised > 50000000) finalScore += 15;
          else if (raised > 10000000) finalScore += 10;
        }
        
        // Determine tier
        let tier = 'cold';
        if (finalScore >= 80) tier = 'hot';
        else if (finalScore >= 50) tier = 'warm';
        
        return [{
          json: {
            ...lead,
            finalScore,
            tier,
            enrichment: {
              company: enrichment.name,
              industry: enrichment.category?.industry,
              employees: enrichment.metrics?.employees
            }
          }
        }];
      `
    }),
    
    // Conditional routing based on tier
    new If({
      name: 'Route by Tier',
      conditions: {
        hot: '={{ $input.tier === "hot" }}',
        warm: '={{ $input.tier === "warm" }}',
        cold: '={{ $input.tier === "cold" }}'
      }
    }),
    
    // Hot leads: Immediate Slack alert
    nodes.slack({
      name: 'Alert Sales Team',
      channel: '#hot-leads',
      text: `
        🔥 Hot Lead Alert!
        
        Company: {{ $input.company }}
        Score: {{ $input.finalScore }}/100
        Tier: {{ $input.tier }}
        Email: {{ $input.email }}
        
        Enrichment: {{ JSON.stringify($input.enrichment) }}
      `
    }),
    
    // Warm leads: Add to nurturing sequence
    nodes.activeCampaign({
      name: 'Add to Nurture Sequence',
      operation: 'create',
      resource: 'contact',
      additionalFields: {
        email: '={{ $input.email }}',
        firstName: '={{ $input.firstName }}',
        tags: 'warm-lead, nurturing'
      }
    }),
    
    // Cold leads: Log for analysis
    nodes.postgres({
      name: 'Log Cold Lead',
      operation: 'insert',
      table: 'cold_leads',
      columns: {
        email: '={{ $input.email }}',
        company: '={{ $input.company }}',
        score: '={{ $input.finalScore }}',
        created_at: '={{ new Date().toISOString() }}'
      }
    }),
    
    // Merge branches
    new Merge({
      name: 'Combine Results',
      mode: 'waitAll'
    }),
    
    // Final response
    nodes.respondToWebhook({
      name: 'Return Score',
      statusCode: 200,
      responseBody: {
        scored: true,
        score: '={{ $input.finalScore }}',
        tier: '={{ $input.tier }}'
      }
    })
  ],
  
  // Define connections
  connections: [
    // Linear flow
    { from: 'Lead Webhook', to: 'Validate Lead Data' },
    { from: 'Validate Lead Data', to: 'Enrich Company Data' },
    { from: 'Enrich Company Data', to: 'Calculate Final Score' },
    { from: 'Calculate Final Score', to: 'Route by Tier' },
    
    // Conditional branches
    { from: 'Route by Tier', to: 'Alert Sales Team', condition: 'hot' },
    { from: 'Route by Tier', to: 'Add to Nurture Sequence', condition: 'warm' },
    { from: 'Route by Tier', to: 'Log Cold Lead', condition: 'cold' },
    
    // Merge back
    { from: 'Alert Sales Team', to: 'Combine Results' },
    { from: 'Add to Nurture Sequence', to: 'Combine Results' },
    { from: 'Log Cold Lead', to: 'Combine Results' },
    { from: 'Combine Results', to: 'Return Score' }
  ],
  
  tags: ['sales', 'lead-scoring', 'enrichment']
});

# Pull workflows from n8n instance
n8nac sync pull --instance development

# Push workflow to n8n
n8nac sync push --instance development --workflow lead-scoring

# Sync all workflows
n8nac sync push --instance development --all

# Dry run to see what would change
n8nac sync push --instance development --dry-run

# .github/workflows/n8n-cicd.yaml
name: n8n CI/CD Pipeline

on:
  push:
    branches: [main, develop]
    paths:
      - 'workflows/**'
      - 'environments/**'
      - '.github/workflows/n8n-cicd.yaml'
  pull_request:
    branches: [main]
    paths:
      - 'workflows/**'

jobs:
  validate:
    name: Validate Workflows
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run TypeScript compiler
        run: npx tsc --noEmit
      
      - name: Lint workflows
        run: n8nac lint
      
      - name: Validate workflow schemas
        run: n8nac validate --strict
      
      - name: Check for security issues
        run: n8nac security-scan
        env:
          N8N_SECURITY_RULES: strict

  test:
    name: Test Workflows
    runs-on: ubuntu-latest
    needs: validate
    services:
      n8n:
        image: n8nio/n8n:latest
        env:
          N8N_BASIC_AUTH_ACTIVE: "false"
          WEBHOOK_URL: http://localhost:5678/
        ports:
          - 5678:5678
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: n8n_test
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Deploy to test instance
        run: n8nac sync push --instance test --all
        env:
          N8N_TEST_API_KEY: ${{ secrets.N8N_TEST_API_KEY }}
      
      - name: Run integration tests
        run: npm run test:integration
        env:
          N8N_BASE_URL: http://localhost:5678
          N8N_API_KEY: ${{ secrets.N8N_TEST_API_KEY }}
      
      - name: Run workflow-specific tests
        run: n8nac test --coverage
      
      - name: Upload coverage
        uses: codecov/codecov-action@v4

  deploy-staging:
    name: Deploy to Staging
    runs-on: ubuntu-latest
    needs: [validate, test]
    if: github.ref == 'refs/heads/develop'
    environment:
      name: staging
      url: https://n8n-staging.company.com
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Deploy to staging
        run: |
          n8nac sync push --instance staging --all
          n8nac activate --instance staging --all
        env:
          N8N_STAGING_API_KEY: ${{ secrets.N8N_STAGING_API_KEY }}
      
      - name: Run smoke tests
        run: n8nac test --instance staging --smoke

  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: [validate, test]
    if: github.ref == 'refs/heads/main'
    environment:
      name: production
      url: https://n8n.company.com
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Backup current production workflows
        run: |
          n8nac backup create --instance production \
            --name "pre-deploy-${{ github.sha }}"
        env:
          N8N_PROD_API_KEY: ${{ secrets.N8N_PROD_API_KEY }}
      
      - name: Deploy to production
        run: |
          n8nac sync push --instance production --all
          n8nac activate --instance production --all
        env:
          N8N_PROD_API_KEY: ${{ secrets.N8N_PROD_API_KEY }}
      
      - name: Verify deployment
        run: |
          n8nac health-check --instance production
          n8nac test --instance production --smoke
        env:
          N8N_PROD_API_KEY: ${{ secrets.N8N_PROD_API_KEY }}
      
      - name: Notify on success
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "✅ n8n workflows deployed to production",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "*n8n Deployment Complete*\nCommit: ${{ github.sha }}\nWorkflows deployed successfully to production"
                  }
                }
              ]
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
      
      - name: Rollback on failure
        if: failure()
        run: |
          n8nac backup restore --instance production \
            --name "pre-deploy-${{ github.sha }}"
        env:
          N8N_PROD_API_KEY: ${{ secrets.N8N_PROD_API_KEY }}

// tests/workflows/lead-scoring.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { WorkflowTester } from 'n8n-as-code/testing';
import leadScoringWorkflow from '../../workflows/lead-scoring';

describe('Lead Scoring Workflow', () => {
  let tester: WorkflowTester;
  
  beforeEach(() => {
    tester = new WorkflowTester(leadScoringWorkflow);
  });
  
  describe('Input Validation', () => {
    it('should reject leads without required fields', async () => {
      const result = await tester.run({
        json: { email: '[email protected]' } // Missing company and source
      });
      
      expect(result[0].json.error).toContain('Missing');
    });
    
    it('should accept valid lead data', async () => {
      const result = await tester.run({
        json: {
          email: '[email protected]',
          company: 'Enterprise Corp',
          source: 'LinkedIn',
          firstName: 'John'
        }
      });
      
      expect(result[0].json.validatedAt).toBeDefined();
      expect(result[0].json.initialScore).toBeGreaterThan(0);
    });
  });
  
  describe('Score Calculation', () => {
    it('should score enterprise companies higher', async () => {
      const result = await tester.run({
        json: {
          email: '[email protected]',
          company: 'Enterprise Solutions Inc',
          source: 'Website'
        }
      });
      
      expect(result[0].json.initialScore).toBeGreaterThanOrEqual(20);
    });
    
    it('should categorize hot leads correctly', async () => {
      const result = await tester.run({
        json: {
          email: '[email protected]',
          company: 'Unicorn Startup',
          source: 'LinkedIn'
        },
        clearbit: {
          metrics: {
            employees: 5000,
            raised: '$150,000,000'
          }
        }
      });
      
      expect(result[0].json.tier).toBe('hot');
      expect(result[0].json.finalScore).toBeGreaterThanOrEqual(80);
    });
  });
  
  describe('Integration Points', () => {
    it('should call Slack for hot leads', async () => {
      const mockSlack = tester.mock('slack');
      
      await tester.run({
        json: {
          email: '[email protected]',
          company: 'Big Corp',
          source: 'LinkedIn'
        },
        clearbit: {
          metrics: { employees: 10000 }
        }
      });
      
      expect(mockSlack).toHaveBeenCalledWith(
        expect.objectContaining({
          channel: '#hot-leads'
        })
      );
    });
  });
});

// tests/integration/workflow-execution.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { N8nClient } from 'n8n-as-code/client';

describe('Integration Tests', () => {
  let client: N8nClient;
  
  beforeAll(async () => {
    client = new N8nClient({
      baseUrl: process.env.N8N_BASE_URL || 'http://localhost:5678',
      apiKey: process.env.N8N_API_KEY
    });
  });
  
  describe('Webhook Workflows', () => {
    it('should execute customer onboarding end-to-end', async () => {
      const webhookUrl = `${client.baseUrl}/webhook/onboard-customer`;
      
      const response = await fetch(webhookUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          email: '[email protected]',
          company: 'Test Corp',
          plan: 'enterprise'
        })
      });
      
      expect(response.status).toBe(200);
      const data = await response.json();
      expect(data.success).toBe(true);
      expect(data.message).toContain('Onboarding');
    });
    
    it('should handle errors gracefully', async () => {
      const webhookUrl = `${client.baseUrl}/webhook/onboard-customer`;
      
      // Missing required field
      const response = await fetch(webhookUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email: '[email protected]' }) // Missing company and plan
      });
      
      expect(response.status).toBe(400);
      const data = await response.json();
      expect(data.error).toBeDefined();
    });
  });
  
  describe('Scheduled Workflows', () => {
    it('should trigger scheduled workflows manually', async () => {
      const result = await client.executeWorkflow({
        id: 'daily-report',
        trigger: 'manual'
      });
      
      expect(result.executionId).toBeDefined();
      expect(result.status).toBe('running');
      
      // Wait for completion
      const execution = await client.waitForExecution(result.executionId);
      expect(execution.status).toBe('success');
    });
  });
  
  describe('Error Handling', () => {
    it('should trigger error workflow on failure', async () => {
      // Execute a workflow designed to fail
      const result = await client.executeWorkflow({
        id: 'failing-workflow',
        trigger: 'manual'
      });
      
      await client.waitForExecution(result.executionId);
      
      // Check error workflow was triggered
      const errorExecutions = await client.getExecutions({
        workflowId: 'error-handler',
        limit: 1
      });
      
      expect(errorExecutions.data.length).toBeGreaterThan(0);
    });
  });
});

// lib/environment.ts
import { Environment, EnvironmentConfig } from 'n8n-as-code';

interface DatabaseConfig {
  host: string;
  port: number;
  database: string;
  credentials: string;
}

interface IntegrationConfig {
  salesforce?: {
    instanceUrl: string;
    clientId: string;
    clientSecret: string;
  };
  sendgrid?: {
    apiKey: string;
    fromEmail: string;
  };
  slack?: {
    botToken: string;
    webhookUrl: string;
  };
}

export const environments: Record<string, EnvironmentConfig> = {
  development: {
    n8n: {
      baseUrl: 'http://localhost:5678',
      apiKey: process.env.N8N_DEV_API_KEY!
    },
    database: {
      host: 'localhost',
      port: 5432,
      database: 'n8n_dev',
      credentials: 'postgres-dev'
    },
    integrations: {
      salesforce: {
        instanceUrl: 'https://test.salesforce.com',
        clientId: process.env.SF_SANDBOX_CLIENT_ID!,
        clientSecret: process.env.SF_SANDBOX_CLIENT_SECRET!
      },
      sendgrid: {
        apiKey: process.env.SENDGRID_DEV_API_KEY!,
        fromEmail: '[email protected]'
      },
      slack: {
        botToken: process.env.SLACK_DEV_BOT_TOKEN!,
        webhookUrl: process.env.SLACK_DEV_WEBHOOK_URL!
      }
    },
    settings: {
      executionTimeout: 60,
      saveManualExecutions: true,
      logLevel: 'debug'
    }
  },
  
  staging: {
    n8n: {
      baseUrl: 'https://n8n-staging.company.com',
      apiKey: process.env.N8N_STAGING_API_KEY!
    },
    database: {
      host: 'staging-db.company.internal',
      port: 5432,
      database: 'n8n_staging',
      credentials: 'postgres-staging'
    },
    integrations: {
      salesforce: {
        instanceUrl: 'https://staging.company.my.salesforce.com',
        clientId: process.env.SF_STAGING_CLIENT_ID!,
        clientSecret: process.env.SF_STAGING_CLIENT_SECRET!
      },
      sendgrid: {
        apiKey: process.env.SENDGRID_STAGING_API_KEY!,
        fromEmail: '[email protected]'
      },
      slack: {
        botToken: process.env.SLACK_STAGING_BOT_TOKEN!,
        webhookUrl: process.env.SLACK_STAGING_WEBHOOK_URL!
      }
    },
    settings: {
      executionTimeout: 120,
      saveManualExecutions: true,
      logLevel: 'info'
    }
  },
  
  production: {
    n8n: {
      baseUrl: 'https://n8n.company.com',
      apiKey: process.env.N8N_PROD_API_KEY!
    },
    database: {
      host: 'prod-db.company.internal',
      port: 5432,
      database: 'n8n_production',
      credentials: 'postgres-production'
    },
    integrations: {
      salesforce: {
        instanceUrl: 'https://company.my.salesforce.com',
        clientId: process.env.SF_PROD_CLIENT_ID!,
        clientSecret: process.env.SF_PROD_CLIENT_SECRET!
      },
      sendgrid: {
        apiKey: process.env.SENDGRID_PROD_API_KEY!,
        fromEmail: '[email protected]'
      },
      slack: {
        botToken: process.env.SLACK_PROD_BOT_TOKEN!,
        webhookUrl: process.env.SLACK_PROD_WEBHOOK_URL!
      }
    },
    settings: {
      executionTimeout: 300,
      saveManualExecutions: false,
      logLevel: 'warn',
      errorWorkflow: 'error-handler-production'
    }
  }
};

// Environment-specific credential injection
export function getCredential(
  env: string,
  name: string
): { name: string; data: Record<string, string> } {
  const config = environments[env];
  
  switch (name) {
    case 'postgres':
      return {
        name: 'Postgres Production',
        data: {
          host: config.database.host,
          database: config.database.database,
          user: config.database.credentials.split(':')[0],
          password: config.database.credentials.split(':')[1],
          port: config.database.port.toString()
        }
      };
      
    case 'salesforce':
      return {
        name: 'Salesforce OAuth',
        data: {
          clientId: config.integrations.salesforce!.clientId,
          clientSecret: config.integrations.salesforce!.clientSecret,
          instanceUrl: config.integrations.salesforce!.instanceUrl
        }
      };
      
    case 'sendgrid':
      return {
        name: 'SendGrid API',
        data: {
          apiKey: config.integrations.sendgrid!.apiKey
        }
      };
      
    default:
      throw new Error(`Unknown credential: ${name}`);
  }
}

// lib/config-validator.ts
import { z } from 'zod';

const workflowSchema = z.object({
  name: z.string().min(1).max(255),
  id: z.string().regex(/^[a-z0-9-]+$/),
  nodes: z.array(z.object({
    name: z.string(),
    type: z.string().startsWith('n8n-nodes-'),
    parameters: z.record(z.any()).optional(),
    position: z.tuple([z.number(), z.number()]).optional()
  })).min(1),
  connections: z.array(z.object({
    from: z.string(),
    to: z.string(),
    condition: z.string().optional()
  })).optional(),
  settings: z.object({
    executionTimeout: z.number().min(1).max(3600).optional(),
    saveExecutionProgress: z.boolean().optional(),
    errorWorkflow: z.string().optional()
  }).optional(),
  tags: z.array(z.string()).max(10).optional()
});

const environmentSchema = z.object({
  n8n: z.object({
    baseUrl: z.string().url(),
    apiKey: z.string().min(32)
  }),
  database: z.object({
    host: z.string(),
    port: z.number().int().min(1).max(65535),
    database: z.string(),
    credentials: z.string()
  }),
  integrations: z.record(z.any()),
  settings: z.object({
    executionTimeout: z.number().optional(),
    saveManualExecutions: z.boolean().optional(),
    logLevel: z.enum(['debug', 'info', 'warn', 'error']).optional()
  })
});

export class ConfigValidator {
  static validateWorkflow(workflow: unknown): void {
    const result = workflowSchema.safeParse(workflow);
    
    if (!result.success) {
      const errors = result.error.errors.map(e => 
        `${e.path.join('.')}: ${e.message}`
      ).join('\n');
      
      throw new Error(`Workflow validation failed:\n${errors}`);
    }
  }
  
  static validateEnvironment(env: string, config: unknown): void {
    const result = environmentSchema.safeParse(config);
    
    if (!result.success) {
      const errors = result.error.errors.map(e =>
        `${e.path.join('.')}: ${e.message}`
      ).join('\n');
      
      throw new Error(`Environment '${env}' validation failed:\n${errors}`);
    }
  }
  
  static validateSecurity(workflow: unknown): string[] {
    const warnings: string[] = [];
    const wf = workflow as any;
    
    // Check for hardcoded credentials
    const workflowJson = JSON.stringify(workflow);
    const sensitivePatterns = [
      { pattern: /api[_-]?key["\s]*[:=]["\s]*["']\w{20,}/gi, name: 'API Key' },
      { pattern: /password["\s]*[:=]["\s]*["']\S{8,}/gi, name: 'Password' },
      { pattern: /token["\s]*[:=]["\s]*["']\w{20,}/gi, name: 'Token' },
      { pattern: /secret["\s]*[:=]["\s]*["']\w{20,}/gi, name: 'Secret' }
    ];
    
    for (const { pattern, name } of sensitivePatterns) {
      if (pattern.test(workflowJson)) {
        warnings.push(`Potential hardcoded ${name} detected. Use credentials feature instead.`);
      }
    }
    
    // Check for HTTP nodes without authentication
    const httpNodes = wf.nodes?.filter((n: any) => 
      n.type === 'n8n-nodes-base.httpRequest'
    ) || [];
    
    for (const node of httpNodes) {
      if (!node.parameters?.authentication) {
        warnings.push(`HTTP node '${node.name}' has no authentication configured.`);
      }
    }
    
    // Check for production settings
    if (wf.settings?.saveManualExecutions && !process.env.ALLOW_MANUAL_EXECUTIONS) {
      warnings.push('Manual execution saving enabled. Consider disabling in production.');
    }
    
    return warnings;
  }
}

main (production)
  │
  ├── develop (staging)
  │     │
  │     ├── feature/user-onboarding
  │     │
  │     ├── feature/lead-scoring
  │     │
  │     └── hotfix/critical-bug
  │
  └── release/v2.1.0

Workflow Naming Convention:
- n8n/{workflow-name}/{action}
- Examples:
  - n8n/lead-scoring/add-clearbit-enrichment
  - n8n/customer-onboarding/fix-email-validation
  - n8n/error-handler/improve-logging

# n8n Code Review Checklist

## Functionality
- [ ] Workflow achieves the stated business objective
- [ ] All nodes are properly connected
- [ ] Error handling is implemented
- [ ] Edge cases are considered

## Security
- [ ] No hardcoded credentials or secrets
- [ ] HTTP requests use proper authentication
- [ ] Input validation is in place
- [ ] SQL injection prevention (parameterized queries)

## Performance
- [ ] No unnecessary API calls
- [ ] Pagination implemented for large datasets
- [ ] Timeouts configured appropriately
- [ ] Batch processing used where possible

## Maintainability
- [ ] Workflow name is descriptive
- [ ] Nodes have clear, descriptive names
- [ ] Comments explain complex logic
- [ ] Tags are applied appropriately

## Testing
- [ ] Unit tests cover core logic
- [ ] Integration tests verify end-to-end flow
- [ ] Error scenarios are tested
- [ ] Documentation is updated

## Deployment
- [ ] Environment-specific configuration is externalized
- [ ] Credentials are properly configured
- [ ] Webhook URLs are correct for target environment
- [ ] Dependencies are documented

# .github/workflows/governance.yaml
name: Workflow Governance

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - 'workflows/**'

jobs:
  governance-checks:
    name: Governance Checks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check naming conventions
        run: |
          # Verify workflow filenames follow convention
          for file in workflows/*.ts; do
            if [[ ! $file =~ ^workflows/[a-z0-9-]+\.ts$ ]]; then
              echo "❌ Invalid filename: $file"
              exit 1
            fi
          done
          echo "✅ Naming conventions validated"
      
      - name: Check for required tags
        run: |
          # Ensure all workflows have required tags
          node scripts/check-tags.js
      
      - name: Validate against security policy
        run: |
          # Check for forbidden nodes
          if grep -r "executeCommand\|ssh" workflows/; then
            echo "❌ Forbidden nodes detected"
            exit 1
          fi
          echo "✅ Security policy validated"
      
      - name: Check test coverage
        run: |
          # Ensure modified workflows have tests
          node scripts/check-tests.js
      
      - name: Validate documentation
        run: |
          # Check README is updated for new workflows
          node scripts/check-docs.js
      
      - name: Post PR comment
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## 🤖 Workflow Governance Report\n\nAll automated governance checks passed. ✅\n\nPlease ensure:\n- [ ] Business logic is correct\n- [ ] Security review completed\n- [ ] Performance impact assessed\n- [ ] Documentation is accurate'
            });

// lib/monitoring.ts
import { Client } from '@opentelemetry/api';

interface ExecutionMetrics {
  workflowId: string;
  workflowName: string;
  executionTime: number;
  nodeCount: number;
  errorCount: number;
  dataVolume: number;
  timestamp: Date;
}

export class WorkflowMonitor {
  private tracer: Client;
  
  constructor() {
    // Initialize OpenTelemetry tracer
    this.tracer = require('@opentelemetry/api').trace.getTracer('n8n-workflows');
  }
  
  async trackExecution(executionId: string): Promise<void> {
    const span = this.tracer.startSpan('workflow_execution');
    
    try {
      // Fetch execution details from n8n API
      const execution = await this.fetchExecution(executionId);
      
      // Record metrics
      span.setAttributes({
        'workflow.id': execution.workflowId,
        'workflow.name': execution.workflowName,
        'execution.duration_ms': execution.executionTime,
        'execution.node_count': execution.nodeCount,
        'execution.error_count': execution.errorCount,
        'execution.data_volume_bytes': execution.dataVolume
      });
      
      // Alert on anomalies
      if (execution.executionTime > 300000) { // 5 minutes
        await this.sendAlert('SLOW_EXECUTION', execution);
      }
      
      if (execution.errorCount > 0) {
        await this.sendAlert('EXECUTION_ERRORS', execution);
      }
      
    } catch (error) {
      span.recordException(error);
      throw error;
    } finally {
      span.end();
    }
  }
  
  async generateDashboard(): Promise<Record<string, unknown>> {
    const metrics = await this.aggregateMetrics({
      period: '24h',
      groupBy: 'workflow'
    });
    
    return {
      summary: {
        totalExecutions: metrics.total,
        successRate: (metrics.successful / metrics.total * 100).toFixed(2),
        avgDuration: metrics.avgDuration.toFixed(0),
        errorRate: (metrics.errors / metrics.total * 100).toFixed(2)
      },
      workflows: metrics.byWorkflow.map(w => ({
        name: w.name,
        executions: w.count,
        successRate: (w.successful / w.count * 100).toFixed(2),
        avgDuration: w.avgDuration.toFixed(0),
        lastExecution: w.lastExecution
      })),
      alerts: metrics.alerts.map(a => ({
        type: a.type,
        workflow: a.workflowName,
        timestamp: a.timestamp,
        details: a.details
      }))
    };
  }
  
  private async sendAlert(type: string, execution: ExecutionMetrics): Promise<void> {
    // Send to PagerDuty, Slack, etc.
    const webhookUrl = process.env.ALERT_WEBHOOK_URL;
    
    await fetch(webhookUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        type,
        severity: type === 'EXECUTION_ERRORS' ? 'critical' : 'warning',
        message: `Workflow "${execution.workflowName}" ${type.toLowerCase().replace('_', ' ')}`,
        details: execution,
        timestamp: new Date().toISOString()
      })
    });
  }
}

// lib/audit.ts
import { createHash } from 'crypto';

interface AuditEvent {
  eventType: 'WORKFLOW_CREATED' | 'WORKFLOW_UPDATED' | 'WORKFLOW_DELETED' |
             'EXECUTION_STARTED' | 'EXECUTION_COMPLETED' | 'EXECUTION_FAILED' |
             'CREDENTIAL_ACCESSED' | 'CONFIG_CHANGED';
  workflowId?: string;
  workflowName?: string;
  userId: string;
  userEmail: string;
  ipAddress: string;
  userAgent: string;
  timestamp: Date;
  changes?: Record<string, { old: unknown; new: unknown }>;
  metadata?: Record<string, unknown>;
}

export class AuditLogger {
  private readonly storage: AuditStorage;
  
  constructor(storage: AuditStorage) {
    this.storage = storage;
  }
  
  async log(event: AuditEvent): Promise<void> {
    // Create tamper-evident hash
    const eventHash = this.createEventHash(event);
    
    const record = {
      ...event,
      hash: eventHash,
      previousHash: await this.getPreviousHash()
    };
    
    // Store to multiple backends for redundancy
    await Promise.all([
      this.storage.write(record),
      this.sendToSIEM(record)
    ]);
  }
  
  async query(filters: {
    eventType?: string;
    workflowId?: string;
    userId?: string;
    startDate?: Date;
    endDate?: Date;
  }): Promise<AuditEvent[]> {
    return this.storage.query(filters);
  }
  
  async verifyIntegrity(): Promise<boolean> {
    const events = await this.storage.query({});
    
    for (let i = 1; i < events.length; i++) {
      const current = events[i];
      const previous = events[i - 1];
      
      if (current.previousHash !== previous.hash) {
        return false;
      }
      
      const calculatedHash = this.createEventHash(current);
      if (calculatedHash !== current.hash) {
        return false;
      }
    }
    
    return true;
  }
  
  private createEventHash(event: Omit<AuditEvent, 'hash' | 'previousHash'>): string {
    const data = JSON.stringify({
      eventType: event.eventType,
      workflowId: event.workflowId,
      workflowName: event.workflowName,
      userId: event.userId,
      timestamp: event.timestamp.toISOString(),
      changes: event.changes
    });
    
    return createHash('sha256').update(data).digest('hex');
  }
  
  private async getPreviousHash(): Promise<string | null> {
    const lastEvent = await this.storage.getLastEvent();
    return lastEvent?.hash || null;
  }
  
  private async sendToSIEM(event: AuditEvent & { hash: string }): Promise<void> {
    // Send to Splunk, Datadog, etc.
    const siemUrl = process.env.SIEM_WEBHOOK_URL;
    if (!siemUrl) return;
    
    await fetch(siemUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event)
    });
  }
}

// workflows/composite/order-processing.ts
import { WorkflowComposer } from 'n8n-as-code/patterns';
import { inventoryCheck } from './steps/inventory-check';
import { paymentProcessing } from './steps/payment-processing';
import { fulfillment } from './steps/fulfillment';
import { notification } from './steps/notification';

export const orderProcessingWorkflow = WorkflowComposer
  .create('Order Processing Pipeline')
  
  // Add sequential steps
  .step(inventoryCheck)
  .step(paymentProcessing, {
    condition: '={{ $input.inventoryAvailable }}',
    timeout: 30000
  })
  .step(fulfillment, {
    parallel: [
      { step: notification, config: { channel: 'email' } },
      { step: notification, config: { channel: 'slack' } }
    ]
  })
  
  // Add error handling
  .onError('paymentProcessing', {
    action: 'retry',
    maxRetries: 3,
    backoff: 'exponential'
  })
  .onError('inventoryCheck', {
    action: 'compensate',
    compensateWith: 'release-reserved-inventory'
  })
  
  // Add monitoring
  .onComplete(data => {
    console.log(`Order ${data.orderId} processed successfully`);
  })
  .onFailure((error, context) => {
    console.error(`Order processing failed:`, error);
    // Send alert, trigger compensation, etc.
  })
  
  .build();

// Individual step definitions
export const inventoryCheck = {
  name: 'Check Inventory',
  nodes: [
    {
      type: 'n8n-nodes-base.postgres',
      parameters: {
        operation: 'select',
        query: `
          SELECT sku, quantity_available 
          FROM inventory 
          WHERE sku = $1
          FOR UPDATE
        `,
        options: {
          parameters: ['={{ $input.sku }}']
        }
      }
    },
    {
      type: 'n8n-nodes-base.function',
      parameters: {
        functionCode: `
          const requested = $input.quantity;
          const available = $input.inventory.quantity_available;
          
          return [{
            json: {
              inventoryAvailable: available >= requested,
              availableQuantity: available,
              reservedQuantity: Math.min(requested, available)
            }
          }];
        `
      }
    }
  ]
};

// lib/feature-flags.ts
import { createClient } from '@launchdarkly/node-server-sdk';

interface FeatureFlags {
  'new-lead-scoring': boolean;
  'enhanced-enrichment': boolean;
  'ai-powered-routing': boolean;
  'parallel-processing': boolean;
}

export class WorkflowFeatureFlags {
  private client: ReturnType<typeof createClient>;
  
  constructor(sdkKey: string) {
    this.client = createClient(sdkKey);
  }
  
  async isEnabled(flag: keyof FeatureFlags, context?: Record<string, unknown>): Promise<boolean> {
    const ldContext = {
      kind: 'workflow',
      key: context?.workflowId || 'default',
      ...context
    };
    
    return await this.client.variation(flag, ldContext, false);
  }
  
  async getWorkflowVariation(workflowId: string): Promise<string> {
    const context = {
      kind: 'workflow',
      key: workflowId
    };
    
    return await this.client.variation('workflow-version', context, 'v1');
  }
}

// Usage in workflow
export async function getLeadScoringWorkflow(): Promise<Workflow> {
  const flags = new WorkflowFeatureFlags(process.env.LD_SDK_KEY!);
  
  if (await flags.isEnabled('new-lead-scoring')) {
    return import('./workflows/lead-scoring-v2');
  }
  
  return import('./workflows/lead-scoring-v1');
}