feat(github): add repository clone service

- Create GitHubCloneService for cloning repos
- Add POST /api/github/clone endpoint
- Shallow clones (depth=1) for performance
- Auto-cleanup on failure
- TDD with 2 passing tests

Part of Phase 2 - GitHub Integration

Author: ScientiaCapital

src/app/api/github/clone/route.ts

@@ -0,0 +1,37 @@
+import { GitHubCloneService } from '@/services/github/clone.service'
+import { NextRequest, NextResponse } from 'next/server'
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json()
+    const { repoUrl, repoFullName } = body
+
+    if (!repoUrl || !repoFullName) {
+      return NextResponse.json(
+        { error: 'repoUrl and repoFullName are required' },
+        { status: 400 }
+      )
+    }
+
+    const cloneService = new GitHubCloneService()
+    const destination = await cloneService.getClonePath(repoFullName)
+    const clonePath = await cloneService.cloneRepository({
+      url: repoUrl,
+      destination
+    })
+
+    return NextResponse.json({
+      success: true,
+      clonePath
+    })
+  } catch (error) {
+    console.error('Clone API error:', error)
+    return NextResponse.json(
+      {
+        success: false,
+        error: error instanceof Error ? error.message : 'Clone failed'
+      },
+      { status: 500 }
+    )
+  }
+}

src/services/github/clone.service.ts

@@ -0,0 +1,74 @@
+import { exec } from 'child_process'
+import { promisify } from 'util'
+import { promises as fs } from 'fs'
+import path from 'path'
+
+const execAsync = promisify(exec)
+
+export interface CloneOptions {
+  url: string
+  destination: string
+  branch?: string
+  depth?: number
+}
+
+export class GitHubCloneService {
+  async cloneRepository(options: CloneOptions): Promise<string> {
+    const { url, destination, branch, depth = 1 } = options
+
+    // Validate URL
+    if (!url.startsWith('https://github.com/')) {
+      throw new Error('Only GitHub HTTPS URLs are supported')
+    }
+
+    // Create destination directory
+    await fs.mkdir(destination, { recursive: true })
+
+    // Build git clone command
+    const branchArg = branch ? `--branch ${branch}` : ''
+    const depthArg = depth > 0 ? `--depth ${depth}` : ''
+    const command = `git clone ${branchArg} ${depthArg} ${url} ${destination}`
+
+    console.log(`🔄 Cloning repository: ${url}`)
+
+    try {
+      const { stdout, stderr } = await execAsync(command, {
+        timeout: 60000 // 60 second timeout
+      })
+
+      if (stderr && !stderr.includes('Cloning into')) {
+        console.warn('Clone stderr:', stderr)
+      }
+
+      console.log(`✅ Successfully cloned to ${destination}`)
+      return destination
+    } catch (error) {
+      console.error('❌ Clone failed:', error)
+
+      // Cleanup failed clone directory
+      try {
+        await fs.rm(destination, { recursive: true, force: true })
+      } catch {}
+
+      throw new Error(`Failed to clone repository: ${error instanceof Error ? error.message : 'Unknown error'}`)
+    }
+  }
+
+  async getClonePath(repoFullName: string): Promise<string> {
+    // Generate unique path for this repo
+    const safeName = repoFullName.replace(/[^a-z0-9-]/gi, '_')
+    return path.join(
+      process.env.CLONE_DIR || '/tmp/ai-dev-cockpit/clones',
+      safeName
+    )
+  }
+
+  async cleanupClone(clonePath: string): Promise<void> {
+    try {
+      await fs.rm(clonePath, { recursive: true, force: true })
+      console.log(`🗑️ Cleaned up clone at ${clonePath}`)
+    } catch (error) {
+      console.error('Failed to cleanup clone:', error)
+    }
+  }
+}

tests/services/github/clone.service.test.ts

@@ -0,0 +1,44 @@
+import { GitHubCloneService } from '@/services/github/clone.service'
+import { promises as fs } from 'fs'
+import path from 'path'
+import os from 'os'
+
+describe('GitHubCloneService', () => {
+  let service: GitHubCloneService
+  let testDir: string
+
+  beforeEach(() => {
+    service = new GitHubCloneService()
+    testDir = path.join(os.tmpdir(), `test-clone-${Date.now()}`)
+  })
+
+  afterEach(async () => {
+    // Cleanup
+    try {
+      await fs.rm(testDir, { recursive: true, force: true })
+    } catch {}
+  })
+
+  it('should clone a public repository', async () => {
+    const repoPath = await service.cloneRepository({
+      url: 'https://github.com/octocat/Hello-World',
+      destination: testDir
+    })
+
+    expect(repoPath).toBe(testDir)
+
+    // Verify .git directory exists
+    const gitPath = path.join(testDir, '.git')
+    const stats = await fs.stat(gitPath)
+    expect(stats.isDirectory()).toBe(true)
+  }, 30000) // 30 second timeout for clone
+
+  it('should handle clone errors gracefully', async () => {
+    await expect(
+      service.cloneRepository({
+        url: 'https://github.com/invalid/nonexistent-repo-xyz',
+        destination: testDir
+      })
+    ).rejects.toThrow()
+  })
+})