@stacksjs/ts-cloud-core 0.1.1

package/src/preview/github.test.ts

@@ -0,0 +1,249 @@
+import { describe, expect, it } from 'bun:test'
+import { generatePreviewWorkflow, generateCleanupWorkflow, generateCostReportWorkflow } from './github'
+
+describe('GitHub Workflow Generation', () => {
+  describe('generatePreviewWorkflow', () => {
+    it('should generate basic preview workflow', () => {
+      const workflow = generatePreviewWorkflow()
+
+      expect(workflow).toContain('name: Preview Environment')
+      expect(workflow).toContain('pull_request:')
+      expect(workflow).toContain('types: [opened, synchronize, reopened, closed]')
+      expect(workflow).toContain('bun run cloud env:preview')
+    })
+
+    it('should include custom workflow name', () => {
+      const workflow = generatePreviewWorkflow({
+        workflowName: 'Custom Preview',
+      })
+
+      expect(workflow).toContain('name: Custom Preview')
+    })
+
+    it('should configure trigger type', () => {
+      const workflow = generatePreviewWorkflow({
+        trigger: 'push',
+      })
+
+      expect(workflow).toContain('push:')
+      expect(workflow).not.toContain('pull_request:')
+    })
+
+    it('should configure branch filters', () => {
+      const workflow = generatePreviewWorkflow({
+        branches: ['main', 'develop', 'staging'],
+      })
+
+      expect(workflow).toContain('- main')
+      expect(workflow).toContain('- develop')
+      expect(workflow).toContain('- staging')
+    })
+
+    it('should configure AWS region', () => {
+      const workflow = generatePreviewWorkflow({
+        awsRegion: 'eu-west-1',
+      })
+
+      expect(workflow).toContain('AWS_REGION: eu-west-1')
+    })
+
+    it('should use IAM role when provided', () => {
+      const workflow = generatePreviewWorkflow({
+        awsRole: 'arn:aws:iam::123456789012:role/github-actions',
+      })
+
+      expect(workflow).toContain('role-to-assume: arn:aws:iam::123456789012:role/github-actions')
+      expect(workflow).not.toContain('AWS_ACCESS_KEY_ID')
+      expect(workflow).not.toContain('AWS_SECRET_ACCESS_KEY')
+    })
+
+    it('should use access keys when IAM role not provided', () => {
+      const workflow = generatePreviewWorkflow()
+
+      expect(workflow).toContain('AWS_ACCESS_KEY_ID')
+      expect(workflow).toContain('AWS_SECRET_ACCESS_KEY')
+      expect(workflow).not.toContain('role-to-assume')
+    })
+
+    it('should configure TTL', () => {
+      const workflow = generatePreviewWorkflow({
+        ttl: 48,
+      })
+
+      expect(workflow).toContain('TTL_HOURS: 48')
+    })
+
+    it('should include deploy step', () => {
+      const workflow = generatePreviewWorkflow()
+
+      expect(workflow).toContain('Deploy preview environment')
+      expect(workflow).toContain('--branch=${{ github.head_ref }}')
+      expect(workflow).toContain('--pr=${{ github.event.pull_request.number }}')
+      expect(workflow).toContain('--commit=${{ github.event.pull_request.head.sha }}')
+      expect(workflow).toContain('--ttl=${{ env.TTL_HOURS }}')
+    })
+
+    it('should include PR comment step', () => {
+      const workflow = generatePreviewWorkflow()
+
+      expect(workflow).toContain('Comment PR with preview URL')
+      expect(workflow).toContain('actions/github-script@v7')
+      expect(workflow).toContain('github.rest.issues.createComment')
+      expect(workflow).toContain('Preview environment deployed')
+    })
+
+    it('should include destroy step', () => {
+      const workflow = generatePreviewWorkflow()
+
+      expect(workflow).toContain('Destroy preview environment')
+      expect(workflow).toContain('github.event.action == \'closed\'')
+      expect(workflow).toContain('--destroy')
+    })
+
+    it('should include cleanup job', () => {
+      const workflow = generatePreviewWorkflow()
+
+      expect(workflow).toContain('cleanup:')
+      expect(workflow).toContain('Cleanup stale environments')
+      expect(workflow).toContain('bun run cloud env:cleanup')
+    })
+
+    it('should use latest Bun version', () => {
+      const workflow = generatePreviewWorkflow()
+
+      expect(workflow).toContain('uses: oven-sh/setup-bun@v1')
+      expect(workflow).toContain('bun-version: latest')
+    })
+
+    it('should include proper permissions', () => {
+      const workflow = generatePreviewWorkflow()
+
+      expect(workflow).toContain('permissions:')
+      expect(workflow).toContain('id-token: write')
+      expect(workflow).toContain('contents: read')
+      expect(workflow).toContain('pull-requests: write')
+    })
+  })
+
+  describe('generateCleanupWorkflow', () => {
+    it('should generate basic cleanup workflow', () => {
+      const workflow = generateCleanupWorkflow()
+
+      expect(workflow).toContain('name: Cleanup Stale Preview Environments')
+      expect(workflow).toContain('schedule:')
+      expect(workflow).toContain('workflow_dispatch:')
+      expect(workflow).toContain('bun run cloud env:cleanup')
+    })
+
+    it('should use default schedule', () => {
+      const workflow = generateCleanupWorkflow()
+
+      expect(workflow).toContain('cron: \'0 0 * * *\'') // Daily at midnight
+    })
+
+    it('should configure custom schedule', () => {
+      const workflow = generateCleanupWorkflow({
+        schedule: '0 2 * * *', // 2am daily
+      })
+
+      expect(workflow).toContain('cron: \'0 2 * * *\'')
+    })
+
+    it('should configure max age', () => {
+      const workflow = generateCleanupWorkflow({
+        maxAge: 72,
+      })
+
+      expect(workflow).toContain('--max-age=72')
+    })
+
+    it('should configure keep count', () => {
+      const workflow = generateCleanupWorkflow({
+        keepCount: 5,
+      })
+
+      expect(workflow).toContain('--keep-count=5')
+    })
+
+    it('should include default maxAge and keepCount', () => {
+      const workflow = generateCleanupWorkflow()
+
+      expect(workflow).toContain('--max-age=48')
+      expect(workflow).toContain('--keep-count=10')
+    })
+
+    it('should include report step', () => {
+      const workflow = generateCleanupWorkflow()
+
+      expect(workflow).toContain('Report cleanup results')
+      expect(workflow).toContain('bun run cloud env:list --status=destroyed')
+    })
+
+    it('should use ubuntu-latest runner', () => {
+      const workflow = generateCleanupWorkflow()
+
+      expect(workflow).toContain('runs-on: ubuntu-latest')
+    })
+  })
+
+  describe('generateCostReportWorkflow', () => {
+    it('should generate basic cost report workflow', () => {
+      const workflow = generateCostReportWorkflow()
+
+      expect(workflow).toContain('name: Preview Environment Cost Report')
+      expect(workflow).toContain('schedule:')
+      expect(workflow).toContain('workflow_dispatch:')
+      expect(workflow).toContain('bun run cloud env:cost --json')
+    })
+
+    it('should use default schedule', () => {
+      const workflow = generateCostReportWorkflow()
+
+      expect(workflow).toContain('cron: \'0 8 * * 1\'') // Monday at 8am
+    })
+
+    it('should configure custom schedule', () => {
+      const workflow = generateCostReportWorkflow({
+        schedule: '0 9 * * 5', // Friday at 9am
+      })
+
+      expect(workflow).toContain('cron: \'0 9 * * 5\'')
+    })
+
+    it('should include cost generation step', () => {
+      const workflow = generateCostReportWorkflow()
+
+      expect(workflow).toContain('Generate cost report')
+      expect(workflow).toContain('COST_JSON=$(bun run cloud env:cost --json)')
+      expect(workflow).toContain('echo "cost_json=$COST_JSON" >> $GITHUB_OUTPUT')
+    })
+
+    it('should send to Slack when webhook provided', () => {
+      const workflow = generateCostReportWorkflow({
+        webhookUrl: 'https://hooks.slack.com/services/xxx/yyy/zzz',
+      })
+
+      expect(workflow).toContain('Send cost report to Slack')
+      expect(workflow).toContain('SLACK_WEBHOOK_URL: https://hooks.slack.com/services/xxx/yyy/zzz')
+      expect(workflow).toContain('curl -X POST')
+      expect(workflow).toContain('Preview Environment Cost Report')
+    })
+
+    it('should echo cost when webhook not provided', () => {
+      const workflow = generateCostReportWorkflow()
+
+      expect(workflow).toContain('Send cost report')
+      expect(workflow).toContain('echo "${{ steps.cost.outputs.cost_json }}"')
+      expect(workflow).not.toContain('SLACK_WEBHOOK_URL')
+      expect(workflow).not.toContain('curl')
+    })
+
+    it('should include proper permissions', () => {
+      const workflow = generateCostReportWorkflow()
+
+      expect(workflow).toContain('permissions:')
+      expect(workflow).toContain('id-token: write')
+      expect(workflow).toContain('contents: read')
+    })
+  })
+})

package/src/preview/github.ts

@@ -0,0 +1,297 @@
+/**
+ * GitHub integration for preview environments
+ * Generates GitHub Actions workflows for automated preview deployments
+ */
+
+export interface GitHubWorkflowOptions {
+  workflowName?: string
+  trigger?: 'pull_request' | 'push' | 'workflow_dispatch'
+  branches?: string[]
+  awsRegion?: string
+  awsRole?: string
+  configFile?: string
+  ttl?: number
+}
+
+/**
+ * Generate GitHub Actions workflow for preview environments
+ */
+export function generatePreviewWorkflow(options: GitHubWorkflowOptions = {}): string {
+  const {
+    workflowName = 'Preview Environment',
+    trigger = 'pull_request',
+    branches = ['main', 'develop'],
+    awsRegion = 'us-east-1',
+    awsRole,
+    configFile = 'cloud.config.ts',
+    ttl = 24,
+  } = options
+
+  return `name: ${workflowName}
+
+on:
+  ${trigger}:
+    types: [opened, synchronize, reopened, closed]
+    branches:
+${branches.map(b => `      - ${b}`).join('\n')}
+
+env:
+  AWS_REGION: ${awsRegion}
+  TTL_HOURS: ${ttl}
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      ${awsRole
+        ? `- name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${awsRole}
+          aws-region: \${{ env.AWS_REGION }}`
+        : `- name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: \${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: \${{ env.AWS_REGION }}`}
+
+      - name: Deploy preview environment
+        if: github.event.action != 'closed'
+        id: deploy
+        run: |
+          # Create preview environment
+          bun run cloud env:preview \\
+            --branch=\${{ github.head_ref }} \\
+            --pr=\${{ github.event.pull_request.number }} \\
+            --commit=\${{ github.event.pull_request.head.sha }} \\
+            --ttl=\${{ env.TTL_HOURS }}
+
+          # Get preview URL
+          PREVIEW_URL=\$(bun run cloud env:preview --get-url \${{ github.head_ref }})
+          echo "preview_url=\$PREVIEW_URL" >> $GITHUB_OUTPUT
+
+      - name: Comment PR with preview URL
+        if: github.event.action != 'closed' && steps.deploy.outputs.preview_url
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const previewUrl = '\${{ steps.deploy.outputs.preview_url }}';
+            const body = \`:rocket: Preview environment deployed!\\n\\n\` +
+              \`**URL:** \${previewUrl}\\n\\n\` +
+              \`**Branch:** \${{ github.head_ref }}\\n\` +
+              \`**Commit:** \${{ github.event.pull_request.head.sha }}\\n\` +
+              \`**Expires:** \${{ env.TTL_HOURS }} hours from now\\n\\n\` +
+              \`_This preview will be automatically destroyed after \${{ env.TTL_HOURS }} hours or when the PR is closed._\`;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body
+            });
+
+      - name: Destroy preview environment
+        if: github.event.action == 'closed'
+        run: |
+          bun run cloud env:preview --destroy \\
+            --branch=\${{ github.head_ref }} \\
+            --pr=\${{ github.event.pull_request.number }}
+
+      - name: Comment PR on destruction
+        if: github.event.action == 'closed'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = ':wastebasket: Preview environment destroyed.';
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body
+            });
+
+  # Cleanup stale preview environments
+  cleanup:
+    runs-on: ubuntu-latest
+    if: github.event.action == 'closed'
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      ${awsRole
+        ? `- name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${awsRole}
+          aws-region: \${{ env.AWS_REGION }}`
+        : `- name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: \${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: \${{ env.AWS_REGION }}`}
+
+      - name: Cleanup stale environments
+        run: |
+          # Clean up environments older than TTL
+          bun run cloud env:cleanup --max-age=\${{ env.TTL_HOURS }}
+`
+}
+
+/**
+ * Generate scheduled cleanup workflow
+ */
+export function generateCleanupWorkflow(options: {
+  schedule?: string
+  maxAge?: number
+  keepCount?: number
+} = {}): string {
+  const {
+    schedule = '0 0 * * *', // Daily at midnight
+    maxAge = 48, // 48 hours
+    keepCount = 10,
+  } = options
+
+  return `name: Cleanup Stale Preview Environments
+
+on:
+  schedule:
+    - cron: '${schedule}'
+  workflow_dispatch:
+
+env:
+  AWS_REGION: us-east-1
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: \${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: \${{ env.AWS_REGION }}
+
+      - name: Cleanup stale environments
+        run: |
+          bun run cloud env:cleanup \\
+            --max-age=${maxAge} \\
+            --keep-count=${keepCount}
+
+      - name: Report cleanup results
+        run: |
+          bun run cloud env:list --status=destroyed
+`
+}
+
+/**
+ * Generate cost report workflow
+ */
+export function generateCostReportWorkflow(options: {
+  schedule?: string
+  webhookUrl?: string
+} = {}): string {
+  const {
+    schedule = '0 8 * * 1', // Weekly on Monday at 8am
+    webhookUrl,
+  } = options
+
+  return `name: Preview Environment Cost Report
+
+on:
+  schedule:
+    - cron: '${schedule}'
+  workflow_dispatch:
+
+env:
+  AWS_REGION: us-east-1
+
+jobs:
+  cost-report:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: \${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: \${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: \${{ env.AWS_REGION }}
+
+      - name: Generate cost report
+        id: cost
+        run: |
+          COST_JSON=\$(bun run cloud env:cost --json)
+          echo "cost_json=\$COST_JSON" >> $GITHUB_OUTPUT
+
+      - name: Send cost report${webhookUrl ? ' to Slack' : ''}
+        ${webhookUrl
+          ? `env:
+          SLACK_WEBHOOK_URL: ${webhookUrl}
+        run: |
+          curl -X POST -H 'Content-type: application/json' \\
+            --data '{"text":"Preview Environment Cost Report\\n\${{ steps.cost.outputs.cost_json }}"}' \\
+            \$SLACK_WEBHOOK_URL`
+          : `run: |
+          echo "\${{ steps.cost.outputs.cost_json }}"`}
+`
+}

package/src/preview/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Preview Environments
+ * Ephemeral environments for PR/branch previews
+ */
+
+export {
+  PreviewEnvironmentManager,
+  previewManager,
+} from './manager'
+
+export type {
+  PreviewEnvironment,
+  PreviewEnvironmentOptions,
+  PreviewCleanupOptions,
+} from './manager'
+
+export {
+  generatePreviewWorkflow,
+  generateCleanupWorkflow,
+  generateCostReportWorkflow,
+} from './github'
+
+export type { GitHubWorkflowOptions } from './github'
+
+export {
+  PreviewNotificationService,
+  previewNotifications,
+} from './notifications'
+
+export type {
+  NotificationChannel,
+  SlackConfig,
+  DiscordConfig,
+  EmailConfig,
+  WebhookConfig,
+  NotificationEvent,
+} from './notifications'