Generate a single-page React SPA using React, Tailwind CSS, and necessary state management libraries (e.g., Zustand or Redux Toolkit) to create a developer tool that automates the migration of projects from GitHub to Codeberg. The application should be named 'Code Transition Wizard' and focus on migrating issues, pull requests, releases, CI/CD configurations, and static hosting setups.
PROJECT OVERVIEW:
The goal of the 'Code Transition Wizard' is to significantly reduce the friction and manual effort involved in migrating projects from GitHub to Codeberg. Many developers are hesitant to switch due to the perceived complexity and time commitment of moving issues, pull requests, CI/CD pipelines, and static hosting. This application provides a streamlined, guided, and automated process, offering a seamless transition experience. The core value proposition is saving developers time and hassle, enabling them to embrace open-source platforms like Codeberg with greater ease.
TECH STACK:
- Frontend Framework: React (using Vite for fast development setup)
- Styling: Tailwind CSS for utility-first styling
- State Management: Zustand for efficient and simple global state management
- Routing: React Router DOM for client-side routing (if multiple views are needed, though aiming for a single-page experience)
- API Interaction: Axios for making HTTP requests to GitHub and Codeberg APIs (or simulating them for MVP)
- UI Components: Potentially a lightweight component library like Headless UI or Radix UI for accessible components, or custom-built components.
- Icons: React Icons
CORE FEATURES:
1. **Repository Import Orchestration**:
* **User Flow**: User connects their GitHub account (via OAuth or token). User selects repositories to migrate. The application fetches repository details (issues, PRs, releases). It then initiates the Codeberg repository import process, passing the necessary GitHub repository URL. It monitors the import status.
* **Details**: This feature leverages Codeberg's built-in GitHub import functionality. The app will guide the user to authenticate, select repositories, and trigger the import. It will display the progress and status (e.g., 'Importing...', 'Completed', 'Failed').
2. **CI/CD Pipeline Migration Assistant**:
* **User Flow**: After repository import, the user selects their CI/CD setup (e.g., GitHub Actions YAML files). The application analyzes the GitHub Actions workflow file(s). It provides recommended Codeberg CI configurations or generates basic `drone.yml` (or Codeberg CI equivalent) files based on common patterns (e.g., build, test, deploy steps).
* **Details**: This will involve parsing YAML and identifying key stages. For MVP, it will focus on generating starter templates for common scenarios. More advanced analysis of complex workflows might be out of scope for MVP but should be considered for future iterations.
3. **Static Hosting Transition Helper**:
* **User Flow**: If the project uses GitHub Pages, the user indicates this. The application guides them to configure Codeberg's `codeberg.page` or a specified alternative (like `grebedoc.dev`, `statichost.eu`). This might involve setting up a branch for static content or configuring build outputs.
* **Details**: Provide clear instructions and potentially helper scripts or configuration file templates for setting up static hosting on Codeberg or chosen alternatives. This feature will primarily offer guidance and link to relevant documentation or configuration examples.
4. **Migration Progress Dashboard**:
* **User Flow**: A central dashboard displays all selected repositories and their migration status for each component (Codeberg repo, CI/CD, Static Hosting). Users can see a checklist or progress bar for each step.
* **Details**: Aggregates status information from the other features. Provides a clear overview of the entire migration process. Highlights any errors encountered and provides links to detailed logs or troubleshooting steps.
UI/UX DESIGN:
- **Layout**: A clean, minimalist, single-page application layout. A sidebar or top navigation for project selection and feature modules. A main content area displaying the current step, forms, status updates, and instructions. Focus on clarity and guiding the user through a step-by-step process.
- **Color Palette**: A modern, developer-friendly palette. Primary colors could be deep blues or purples associated with code and technology, with accent colors (e.g., vibrant green for success, orange/red for warnings/errors) for feedback. Use `hsl()` for easier manipulation and accessibility.
- **Typography**: Clean, readable sans-serif fonts like Inter or Open Sans for body text and a slightly more distinct font for headings. Ensure good contrast ratios.
- **Responsive Design**: Mobile-first approach. The layout should adapt seamlessly to various screen sizes (desktops, tablets, mobile phones). Use Tailwind CSS's responsive modifiers (e.g., `md:`, `lg:`).
- **Component Hierarchy**: Header -> Navigation/Sidebar -> Main Content Area -> Footer (optional). Main content area will dynamically render different components based on the selected migration step.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up routing (if any) and global layout.
- `Header.jsx`: Displays the app title and potentially user authentication status.
- `Navigation.jsx` / `Sidebar.jsx`: Allows users to select repositories and navigate between migration steps.
- `ProjectSelector.jsx`: Component for connecting GitHub account and selecting repositories.
* Props: `onRepoSelect` (callback function), `githubToken` (state).
- `RepoImportStep.jsx`: Handles the initiation and monitoring of Codeberg repository import.
* Props: `repoDetails` (selected repository info), `importStatus` (state).
* State: `importProgress`, `codebergRepoUrl`, `errorMessage`.
- `CICDStep.jsx`: Assistant for migrating CI/CD configurations.
* Props: `repoPath` (e.g., 'owner/repo'), `githubActionsYaml` (content).
* State: `generatedCICDConfig`, `selectedTemplate`, `errorMessage`.
- `StaticHostingStep.jsx`: Helper for static hosting setup.
* Props: `repoPath`.
* State: `hostingPlatform`, `configurationInstructions`, `errorMessage`.
- `MigrationDashboard.jsx`: Aggregates status from all steps.
* Props: `migrationStatus` (object containing status for all steps).
- `StatusIndicator.jsx`: Reusable component to show status (e.g., loading spinner, checkmark, cross icon).
* Props: `status` (string: 'loading', 'success', 'error', 'idle').
- `CodeInput.jsx`: Displays code snippets (e.g., CI/CD config) with syntax highlighting.
* Props: `code` (string), `language` (string).
- `Button.jsx`: Custom styled button component.
* Props: `onClick`, `children`, `variant`, `isLoading`.
- `Input.jsx`: Custom styled input field.
* Props: `label`, `value`, `onChange`, `type`.
DATA MODEL (State Management with Zustand):
- `migrationStore.js`:
* `githubToken`: string | null
* `selectedRepositories`: Array<{ id: string, name: string, owner: string, githubUrl: string, migrationStatus: MigrationStatusObject }>
* `currentStep`: string ('githubAuth', 'repoSelect', 'import', 'cicd', 'hosting', 'complete')
* `MigrationStatusObject`: {
`repoImport`: 'idle' | 'pending' | 'success' | 'error',
`ciConfig`: 'idle' | 'pending' | 'success' | 'error',
`staticHosting`: 'idle' | 'pending' | 'success' | 'error',
`errorMessage`: string | null
}
* `actions`: {
`setGithubToken`, `addRepository`, `updateRepoStatus`, `setStep` etc.
}
- **Mock Data Format (for `selectedRepositories`)**:
```json
[
{
"id": "repo123",
"name": "awesome-project",
"owner": "developer-xyz",
"githubUrl": "https://github.com/developer-xyz/awesome-project",
"migrationStatus": {
"repoImport": "success",
"ciConfig": "pending",
"staticHosting": "idle",
"errorMessage": null
}
},
{
"id": "repo456",
"name": "utility-library",
"owner": "developer-xyz",
"githubUrl": "https://github.com/developer-xyz/utility-library",
"migrationStatus": {
"repoImport": "error",
"ciConfig": "idle",
"staticHosting": "idle",
"errorMessage": "Failed to authenticate with Codeberg API."
}
}
]
```
ANIMATIONS & INTERACTIONS:
- **Page Transitions**: Subtle fade-in/fade-out transitions between steps using CSS animations or libraries like Framer Motion (if complexity allows).
- **Button States**: Visual feedback on button clicks (slight scale/opacity change). Loading state for buttons submitting actions (e.g., `isLoading` prop on `Button.jsx` showing a spinner).
- **Loading Indicators**: Use spinners or pulsing animations for indeterminate loading states (e.g., while importing). Skeleton loaders for data fetching.
- **Hover Effects**: Subtle background color changes or slight elevation changes on interactive elements like repository cards or navigation items.
- **Micro-interactions**: Smooth expansion/collapse for details, visual confirmation when an item is selected.
EDGE CASES:
- **Authentication**: Handle GitHub token expiration or invalid tokens gracefully. Provide clear instructions for re-authentication.
- **API Errors**: Implement robust error handling for GitHub and Codeberg API requests. Display user-friendly error messages, suggesting potential solutions (e.g., "Permissions issue", "Rate limit exceeded").
- **Empty States**: Display informative messages and clear calls to action when no repositories are selected, or when a specific migration step has no data to process (e.g., "No GitHub Actions found in this repository.").
- **Validation**: Validate user inputs, especially when manually providing configuration details or URLs.
- **Rate Limiting**: Be mindful of GitHub and Codeberg API rate limits. Implement exponential backoff or queuing mechanisms for sequential requests if necessary.
- **Accessibility (a11y)**: Ensure all interactive elements are keyboard-navigable. Use semantic HTML5 elements. Provide ARIA attributes where necessary. Ensure sufficient color contrast.
SAMPLE DATA (for GitHub API Responses / Mocking):
1. **Repository List**:
```json
[
{"id": "MDEwOlJlcGılığı1", "name": "Project Alpha", "full_name": "user/Project Alpha", "html_url": "https://github.com/user/Project Alpha"},
{"id": "MDEwOlJlcGılığı2", "name": "Beta Tool", "full_name": "user/Beta Tool", "html_url": "https://github.com/user/Beta Tool"}
]
```
2. **Issue List**:
```json
[
{"number": 1, "title": "Bug Fix Needed", "user": {"login": "dev1"}, "labels": [{"name": "bug"}], "html_url": "..."},
{"number": 2, "title": "Feature Request", "user": {"login": "dev2"}, "labels": [{"name": "enhancement"}], "html_url": "..."}
]
```
3. **Pull Request List**:
```json
[
{"number": 5, "title": "Implement new login", "user": {"login": "dev3"}, "state": "open", "html_url": "..."}
]
```
4. **Release List**:
```json
[
{"tag_name": "v1.0.0", "name": "Version 1.0.0", "published_at": "2023-01-15T10:00:00Z", "html_url": "..."}
]
```
5. **GitHub Actions Workflow File (Example)**:
```yaml
name: CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run a one-line script
run: echo Hello, world!
- name: Run a multi-line script
run: |
echo Add other commands to make this a complete CI
echo another line
```
6. **Codeberg CI Configuration (Target Example)**:
```yaml
kind: pipeline
type: github
name: default
steps:
- name: checkout
git:
depth: 1
- name: build_and_test
image: plugins/docker
settings:
repo: {{build.repo.link}}
// Additional settings based on analysis
```
7. **Static Hosting Config (Example for `codeberg.page`)**:
Indication that content should be pushed to a specific branch (e.g., `gh-pages` or `docs`) and that `codeberg.page` is enabled for that repo.
DEPLOYMENT NOTES:
- **Build Command**: `npm run build` (or `yarn build` if using Yarn).
- **Environment Variables**: Use `VITE_` prefix for Vite-compatible environment variables (e.g., `VITE_GITHUB_CLIENT_ID`, `VITE_CODEBERG_API_URL`). Store sensitive keys like GitHub tokens securely, preferably server-side if scaling beyond a simple SPA or using a backend-for-frontend pattern.
- **Performance Optimizations**: Code splitting for different sections/steps, lazy loading components, image optimization (if any are used), efficient state management to prevent unnecessary re-renders. Ensure Tailwind CSS is configured for production builds (PurgeCSS).
- **Hosting**: Can be deployed as a static site on platforms like Netlify, Vercel, GitHub Pages itself, or Codeberg Pages.