npm package: @ordojs/deploy
Description: Multi-platform deployment and infrastructure automation for OrdoJS applications
Author: OrdoJS Team
Latest version: 0.1.0

# @ordojs/deploy

**Multi-platform deployment and infrastructure automation for OrdoJS applications.**

## Overview

The `@ordojs/deploy` package provides a comprehensive deployment solution supporting multiple
platforms, CI/CD pipeline generation, and monitoring integration. Deploy your OrdoJS applications to
Vercel, Netlify, Cloudflare, AWS, Docker, and Kubernetes with automated infrastructure setup.

## 🚀 Features

### **Multi-Platform Support**

- **Vercel** - Serverless deployment with edge optimization
- **Netlify** - Static sites with edge functions and forms
- **Cloudflare** - Pages and Workers with global edge performance
- **AWS** - Lambda, S3, CloudFront with full AWS ecosystem
- **Docker** - Containerized deployments with multi-stage builds
- **Kubernetes** - Scalable container orchestration

### **Intelligent Platform Detection**

- Automatic platform detection based on project configuration
- Smart recommendations with confidence scoring
- Configuration conflict detection and resolution

### **CI/CD Pipeline Generation**

- **GitHub Actions** workflows with matrix builds and caching
- **GitLab CI** pipelines with auto-DevOps
- **Jenkins** declarative pipelines
- Environment-specific deployment strategies

### **Monitoring & Observability**

- **Prometheus** metrics collection
- **Grafana** dashboards and alerting
- **Jaeger** distributed tracing
- **Datadog**, **New Relic**, **Sentry** integrations

### **Infrastructure as Code**

- Configuration file generation for each platform
- Environment management and secret handling
- Resource provisioning and scaling configuration

## 📦 Installation

```bash
# Using pnpm (recommended)
pnpm add @ordojs/deploy

# Using npm
npm install @ordojs/deploy

# Using yarn
yarn add @ordojs/deploy
```

## 🏗️ Basic Usage

### Quick Deployment

```typescript
import { deployApplication, detectDeploymentPlatform } from '@ordojs/deploy';

// Auto-detect optimal platform
const detection = await detectDeploymentPlatform('./my-project');
console.log('Recommended:', detection.recommendations[0]);

// Deploy to detected platform
const result = await deployApplication({
  platform: 'vercel',
  project: {
    name: 'my-ordojs-app',
    version: '1.0.0',
  },
  build: {
    command: 'pnpm build',
    outputDir: 'dist',
  },
  environment: 'production',
});

if (result.success) {
  console.log(`✅ Deployed to: ${result.url}`);
} else {
  console.error(`❌ Deployment failed: ${result.error?.message}`);
}
```

### Advanced Deployment Manager

```typescript
import { createDeploymentManager } from '@ordojs/deploy';

const manager = await createDeploymentManager({
  workspaceDir: './my-project',
  maxConcurrentDeployments: 3,
  logging: { level: 'info', console: true },
});

// Multi-environment deployment
const environments = ['staging', 'production'];
const deployments = await Promise.all(
  environments.map(env =>
    manager.deploy({
      platform: 'vercel',
      environment: env,
      project: { name: 'my-app', version: '1.0.0' },
      build: { command: 'pnpm build', outputDir: 'dist' },
      env: {
        NODE_ENV: env,
        API_URL: env === 'production' ? 'https://api.myapp.com' : 'https://staging-api.myapp.com',
      },
    })
  )
);

await manager.cleanup();
```

## 🎯 Platform-Specific Examples

### Vercel Deployment

```typescript
import type { VercelConfig } from '@ordojs/deploy';

const vercelConfig: VercelConfig = {
  platform: 'vercel',
  project: { name: 'my-nextjs-app' },
  build: {
    command: 'pnpm build',
    outputDir: '.next',
  },
  platformConfig: {
    framework: 'nextjs',
    regions: ['iad1', 'sfo1'],
    functions: {
      'api/**': { memory: 1024, maxDuration: 30 },
    },
  },
  domains: {
    primary: 'myapp.com',
    aliases: ['www.myapp.com'],
    redirects: [{ source: '/old-page', destination: '/new-page', permanent: true }],
  },
};
```

### Cloudflare Pages/Workers

```typescript
import type { CloudflareConfig } from '@ordojs/deploy';

const cloudflareConfig: CloudflareConfig = {
  platform: 'cloudflare',
  project: { name: 'my-worker-app' },
  build: { command: 'pnpm build', outputDir: 'dist' },
  platformConfig: {
    workers: {
      name: 'my-worker',
      script: 'dist/worker.js',
      compatibility_date: '2024-01-01',
      bindings: [
        {
          type: 'kv_namespace',
          name: 'CACHE',
          namespace_id: 'abc123',
        },
        {
          type: 'r2_bucket',
          name: 'ASSETS',
          bucket_name: 'my-assets',
        },
      ],
      routes: [{ pattern: 'myapp.com/api/*', zone_name: 'myapp.com' }],
    },
  },
};
```

### AWS Lambda + S3

```typescript
import type { AWSConfig } from '@ordojs/deploy';

const awsConfig: AWSConfig = {
  platform: 'aws',
  project: { name: 'my-serverless-app' },
  build: { command: 'pnpm build', outputDir: 'build' },
  platformConfig: {
    region: 'us-east-1',
    lambda: {
      runtime: 'nodejs18.x',
      memory: 512,
      timeout: 30,
      environment: {
        NODE_ENV: 'production',
      },
    },
    s3: {
      bucket: 'my-app-static-assets',
      region: 'us-east-1',
    },
    cloudfront: {
      enabled: true,
      caching: {
        defaultTtl: 86400,
        compress: true,
      },
    },
  },
};
```

## 🔄 CI/CD Pipeline Generation

### GitHub Actions

```typescript
import { GitHubActionsGenerator } from '@ordojs/deploy';

const generator = new GitHubActionsGenerator();

const deployConfig = {
  platform: 'vercel' as const,
  project: { name: 'my-app', version: '1.0.0' },
  build: { command: 'pnpm build', outputDir: 'dist' },
  cicd: {
    triggers: {
      push: { branches: ['main'] },
      pullRequest: { branches: ['main'] },
    },
    stages: [
      {
        name: 'Run Tests',
        type: 'test' as const,
        commands: ['pnpm test', 'pnpm test:e2e'],
        cache: {
          enabled: true,
          paths: ['node_modules', '.next/cache'],
        },
      },
      {
        name: 'Deploy to Production',
        type: 'deploy' as const,
        commands: ['echo "Deploying..."'],
        condition: "github.ref == 'refs/heads/main'",
      },
    ],
    notifications: {
      slack: {
        webhook: process.env.SLACK_WEBHOOK!,
        channel: '#deployments',
      },
    },
  },
};

const files = await generator.generateWorkflow(deployConfig, './');
console.log('Generated:', files); // ['.github/workflows/deploy.yml']
```

## 📊 Monitoring Integration

### Multi-Provider Setup

```typescript
import { MonitoringManager } from '@ordojs/deploy';

const monitoring = new MonitoringManager({
  providers: ['prometheus', 'grafana', 'sentry'],
  prometheus: {
    endpoint: 'http://localhost:9090',
    metrics: {
      deployments: 'ordojs_deployments_total',
      duration: 'ordojs_deployment_duration_seconds',
    },
  },
  grafana: {
    url: 'http://localhost:3000',
    apiKey: process.env.GRAFANA_API_KEY,
  },
  sentry: {
    dsn: process.env.SENTRY_DSN,
    environment: 'production',
  },
});

await monitoring.initialize();

// Track deployment lifecycle
await monitoring.trackDeploymentStart('deploy-123', deployConfig);
// ... deployment happens ...
await monitoring.trackDeploymentComplete('deploy-123', result);

// Generate monitoring configs
const configFiles = await monitoring.generateConfigFiles('./monitoring');
// Creates: prometheus.yml, grafana-dashboard.json, sentry.config.js
```

## 🛠️ Advanced Configuration

### Environment Management

```typescript
const config = {
  platform: 'vercel' as const,
  project: { name: 'my-app' },
  environments: {
    staging: {
      build: { command: 'pnpm build:staging' },
      env: {
        NODE_ENV: 'staging',
        API_URL: { value: 'https://staging-api.com', secret: false },
      },
    },
    production: {
      build: { command: 'pnpm build:prod' },
      env: {
        NODE_ENV: 'production',
        API_KEY: { value: process.env.PROD_API_KEY!, secret: true },
      },
    },
  },
};
```

### Custom Deployment Hooks

```typescript
import { DeploymentManager } from '@ordojs/deploy';

const manager = new DeploymentManager();

// Listen to deployment events
manager.onDeploymentEvent('deployment-started', ({ deploymentId }) => {
  console.log(`🚀 Starting deployment: ${deploymentId}`);
});

manager.onDeploymentEvent('deployment-completed', ({ result }) => {
  console.log(`✅ Deployment completed: ${result.url}`);
  // Send notification, update database, etc.
});

manager.onDeploymentEvent('deployment-failed', ({ error }) => {
  console.error(`❌ Deployment failed: ${error?.message}`);
  // Alert team, rollback, etc.
});
```

## 🔧 Platform Detection

```typescript
import { detectDeploymentPlatform } from '@ordojs/deploy';

const detection = await detectDeploymentPlatform('./my-project');

console.log('Detected platforms:', detection.platforms);
console.log('Confidence scores:', detection.confidence);
console.log('Found config files:', detection.configFiles);

// Get top recommendation
const topRec = detection.recommendations[0];
console.log(`Recommended: ${topRec.platform} (${topRec.score}%)`);
console.log(`Reason: ${topRec.reason}`);
```

## 📋 CLI Integration

The deploy package integrates with the OrdoJS CLI:

```bash
# Auto-detect and deploy
ordojs deploy

# Deploy to specific platform
ordojs deploy --platform vercel --env production

# Generate CI/CD pipeline
ordojs deploy generate-pipeline --provider github-actions

# Platform detection
ordojs deploy detect

# Generate deployment config
ordojs deploy config --platform cloudflare --output ./deploy
```

## 🔐 Environment Variables

### Required by Platform

**Vercel:**

```bash
VERCEL_TOKEN=your_token_here
VERCEL_ORG_ID=optional_org_id
VERCEL_PROJECT_ID=optional_project_id
```

**Netlify:**

```bash
NETLIFY_AUTH_TOKEN=your_auth_token
NETLIFY_SITE_ID=your_site_id
```

**Cloudflare:**

```bash
CLOUDFLARE_API_TOKEN=your_api_token
CLOUDFLARE_ACCOUNT_ID=optional_account_id
CLOUDFLARE_ZONE_ID=optional_zone_id
```

**AWS:**

```bash
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
```

## 🎨 Examples

Check out our [examples repository](../examples/) for complete deployment examples:

- **Basic Static Site** - Simple deployment to Netlify/Vercel
- **Full-Stack App** - API + frontend deployment to multiple platforms
- **Multi-Environment** - Staging + production with environment management
- **Microservices** - Docker + Kubernetes deployment
- **Edge Computing** - Cloudflare Workers with KV/D1 integration

## 📚 API Reference

### Core Classes

- **`DeploymentManager`** - Main deployment orchestration
- **`VercelAdapter`** - Vercel platform integration
- **`CloudflareAdapter`** - Cloudflare Pages/Workers integration
- **`AWSAdapter`** - AWS Lambda/S3/CloudFront integration
- **`GitHubActionsGenerator`** - CI/CD pipeline generation
- **`MonitoringManager`** - Multi-provider monitoring integration

### Types

```typescript
interface DeploymentConfig {
  platform: DeploymentPlatform;
  project: ProjectConfig;
  build: BuildConfig;
  environment?: string;
  env?: EnvironmentVariables;
  domains?: DomainsConfig;
  cicd?: CICDConfig;
  monitoring?: MonitoringConfig;
}
```

See [types documentation](./src/types/index.ts) for complete type definitions.

## 🤝 Contributing

We welcome contributions! Please see our [contributing guide](../../CONTRIBUTING.md) for details on
how to:

- Report bugs and request features
- Submit pull requests
- Add new platform adapters
- Improve documentation

## 📄 License

MIT © OrdoJS Team

---

**Ready to deploy?** Get started with `pnpm add @ordojs/deploy` and deploy your OrdoJS applications
to any platform with confidence! 🚀