Feature: Project Import/Export with AI-Powered Framework Migration

[pablopunk]

Summary

Add the ability to export projects as ZIP files and import projects from Git repositories or local folders, with automatic framework detection and optional AI-powered transformation to Astro v5.

Motivation

Currently, users cannot easily backup projects, share them, or import existing codebases. This feature enables:

• Project portability and backup
• Reusing existing Git repositories
• Framework-agnostic imports (automatically transform to Astro)

Implementation Plan

1. Export Feature

• User clicks "Export" button on project page
• Triggers project.exportZip queue job
• Generates ZIP of /data/projects/{projectId}/ with all files
• Includes metadata file doce-export.json
• Streams ZIP to browser for download

Files to create/modify:

• src/actions/projects.ts - Add projects.export action
• src/server/queue/handlers/projectExport.ts - Queue handler
• UI button in project header

2. Import Feature - Git Repositories

Flow:

1. User provides GitHub/GitLab URL
2. Queue job project.importGit: Clone to /data/projects/{projectId}/
3. Queue job project.analyzeImportCompatibility:
   • Detect framework (Astro, Next.js, React, Vue, etc.)
   • Check for Docker files
   • Validate package.json
4. If Astro: Proceed to initialization
5. If different framework: Queue job project.transformImportToAstro
   • Send to OpenCode: "Transform this [framework] project to Astro v5 with React, Tailwind, shadcn/ui"
   • AI agent rewrites files
6. Queue job project.finalizeImport:
   • Generate .env with ports
   • Create/update opencode.json
   • Ensure Docker files exist
7. Auto-start: Queue normal initialization pipeline (docker.composeUp → opencode.session → prompt)

3. Import Feature - Folder Upload

Flow:

• HTML5 drag-and-drop with webkitdirectory or .tar/.zip upload
• Extract to temp directory
• Process same as Git import (skip clone step)

4. Database Schema Changes

Add to projects table:

importedFrom?: "git" | "folder";
importSourceUrl?: string;
importedAt?: Date;
transformationStatus?: "analyzing" | "transforming" | "ready" | "failed";
transformationError?: string;

5. Queue Jobs

New job types:

• project.importGit - Clone Git repository
• project.analyzeImportCompatibility - Framework detection
• project.transformImportToAstro - AI migration (uses OpenCode)
• project.finalizeImport - Setup Docker, env, config
• project.exportZip - Generate ZIP download

6. UI Changes

Create Project Screen:

• Add tabs/radio buttons: "From Scratch", "Import from GitHub", "Import from Folder"
• GitHub: Input field for URL + auto-detect indicator
• Folder: Drag-and-drop zone
• Show compatibility report before starting
• Display transformation progress if needed

Project Page:

• Add "Export" button in header
• Show import status/progress for new imports

Security Considerations

• ✅ Validate Git URLs (prevent SSRF)
• ✅ Private repos: Not supported initially (no token storage)
• ✅ ZIP/folder upload: Validate structure, prevent path traversal
• ✅ Permissions: Ensure imported projects are owned by user
• ✅ Cleanup: Remove failed imports from filesystem

Acceptance Criteria

• Export project as ZIP via UI button
• Import from GitHub URL (Astro projects)
• Import from GitHub URL (other frameworks) with AI transformation
• Import from folder upload with same workflow
• Auto-detect framework type (Astro, Next.js, React, Vue, etc.)
• Imported project auto-starts after successful setup
• Transformation errors handled gracefully with user feedback
• Slug/name conflicts automatically resolved

Related Files

• src/server/db/schema.ts - Database schema
• src/server/projects/ - Project management
• src/server/queue/ - Queue system
• src/actions/projects.ts - Project actions
• templates/astro-starter/ - Astro template
• AGENTS.md - Architecture documentation

Technical Details

All import operations use the queue system for durability and observability. Project initialization follows the existing pipeline:
docker.composeUp → docker.waitReady → opencode.sessionCreate → sendInitialPrompt

For transformed projects, the initial prompt can guide the AI to finalize any remaining compatibility work.

[pablopunk]

Re-scoping this issue. Given our Astro-coupled pipeline (templates/astro-starter, productionBuild.ts expects Astro output), we should split this:

Phase 1 (this issue):

• Export project as ZIP
• Import from GitHub/folder with Astro validation only (reject non-Astro with clear message)

Phase 2 (future issue):

• AI-powered framework migration to Astro

This keeps the scope achievable and avoids over-promising on migration complexity.