context: add copilot instructions and prompts

.github/copilot-instructions.md

@@ -0,0 +1,207 @@
+# CM-Beetle Copilot Instructions
+
+## Project Rules
+
+- **Language & Framework:** Go 1.21+, Echo Framework.
+- **Documentation Style:** Technical accuracy with a friendly and professional tone.
+- **Language Setting:** All responses and explanations must be in **English**.
+- **Code Standards:**
+  - Echo handlers must follow the standard pattern using `context.Bind` and `context.JSON`.
+  - Refer to `pkg/core/common/error.go` for standard error types.
+
+This repository contains the source code for **CM-Beetle** (Computing Infrastructure Migration), a sub-system of the Cloud-Barista platform.
+
+## Project Overview
+
+- **Objectives:** Recommend optimal target computing infrastructure (cloud infrastructure) based on source infrastructure information, and execute migration according to the recommendation.
+- **Languages:** Go (1.25.0+).
+- **Frameworks:** Echo (Web Framework), Viper (Config), Zerolog (Logging), Swag (API Docs).
+- **Dependencies:** `cb-tumblebug`, `cm-model`.
+- **Supported Clouds:** AWS, Azure, GCP, NCP, Alibaba Cloud.
+- **Architecture:** REST API server (Echo) with a modular architecture separating API handlers from core logic (migration, recommendation). It functions as an orchestration layer, tightly integrated with CB-Tumblebug for managing multi-cloud resources.
+
+## Key Dependencies & Integration Patterns
+
+### Key Reference Files
+
+- **API Specification:** `api/swagger.yaml` (Source of truth for API contracts).
+- **Data Models:** `pkg/api/rest/model/` (Request/Response structures).
+- **Configuration:** `conf/config.yaml` (Available configuration options).
+- **Error Definitions:** `pkg/core/common/error.go` (Standard error types).
+
+### CB-Tumblebug Integration
+
+- **Core Model Import:** `tbmodel "github.com/cloud-barista/cb-tumblebug/src/core/model"`
+- **Resource Interface Import:** `tbresource "github.com/cloud-barista/cb-tumblebug/src/interface/rest/server/resource"`
+- **Network Utilities Import:** `"github.com/cloud-barista/cb-tumblebug/src/core/common/netutil"`
+- **Client Package:** `pkg/client/tumblebug/` (Contains all Tumblebug API clients)
+- **Key Components:**
+  - `TumblebugClient`: Main client for interactions (MCI, Namespace, VM, VNet, SecurityGroup, SSH key).
+
+### cm-model Integration
+
+- **Cloud Model Import:** `cloudmodel "github.com/cloud-barista/cm-model/infra/cloud-model"`
+- **On-Premise Model Import:** `onpremmodel "github.com/cloud-barista/cm-model/infra/on-premise-model"`
+- **Usage:** Shared data models for cloud and on-premise infrastructure.
+
+## Architecture & Code Organization
+
+### Core Packages Structure
+
+- `cmd/cm-beetle/`: Main application entry point (`main.go`).
+- `pkg/api/rest/`: REST API handlers (`controller/`), middlewares (`middlewares/`), and models (`model/`).
+- `pkg/client/tumblebug/`: CB-Tumblebug API client implementations.
+- `pkg/core/`: Core logic and algorithms.
+  - `migration/`: Infrastructure migration logic (CreateVMInfra, etc.).
+  - `recommendation/`: Infrastructure recommendation logic (VM Specs, OS Images).
+  - `common/`: Shared utilities.
+- `pkg/config/`: Configuration management (Viper).
+- `pkg/modelconv/`: Model conversion utilities between internal, Tumblebug, and cm-model formats.
+
+### Key Functional Areas
+
+1.  **Infrastructure Migration (`pkg/core/migration/`)**:
+    - Migrate on-premise infrastructure to multi-cloud.
+    - `CreateVMInfra()`: Create target cloud infrastructure via CB-Tumblebug.
+2.  **Infrastructure Recommendation (`pkg/core/recommendation/`)**:
+    - Recommend optimal cloud configurations (VM Specs, OS Images, VNet).
+    - Uses similarity-based matching algorithms.
+
+### Key Design Patterns
+
+- **Middleware Pattern:**
+  - `TumblebugInitChecker`: Ensures Tumblebug is initialized before processing requests.
+  - Authentication and CORS handling.
+- **Model Conversion Pattern:**
+  - Use `modelconv` package for converting between different model formats.
+  - Heavy use of CB-Tumblebug and cm-model structures.
+
+## Coding Standards & Conventions
+
+### General
+
+- Write all code comments and documentation in English.
+- Use English for struct field comments, function comments, inline comments, and TODO/FIXME notes.
+- Ensure consistency and accessibility for international contributors.
+
+### Go
+
+- Detailed Go coding standards are managed in `.github/instructions/go.instructions.md`.
+
+## Common Patterns
+
+### API Handler Pattern
+
+```go
+func HandlerName(c echo.Context) error {
+    nsId := c.Param("nsId")
+    var req RequestModel
+    if err := c.Bind(&req); err != nil {
+        return c.JSON(http.StatusBadRequest, model.Response{Message: err.Error()})
+    }
+
+    // Core logic
+    result, err := coreLogic(nsId, req)
+    if err != nil {
+        log.Error().Err(err).Msg("Operation failed")
+        return c.JSON(http.StatusInternalServerError, model.Response{Message: err.Error()})
+    }
+    return c.JSON(http.StatusOK, result)
+}
+```
+
+### Client Integration Pattern
+
+```go
+// Initialize client
+client := tbclient.NewDefaultClient()
+
+// Execute request with proper error handling
+result, err := client.SomeOperation(params)
+if err != nil {
+    log.Error().Err(err).Msg("Tumblebug operation failed")
+    return nil, err
+}
+return result, nil
+```
+
+### Model Conversion Pattern
+
+```go
+// Convert between different model formats
+targetModel := modelconv.ConvertToTargetFormat(sourceModel)
+
+// Use appropriate imports for model types
+tbModel := tbmodel.SomeModel{}
+cloudModel := cloudmodel.SomeModel{}
+```
+
+## Development Workflow
+
+### Working with External Dependencies
+
+#### CB-Tumblebug Integration
+
+- Always use the client packages in `pkg/client/tumblebug/`.
+- Handle CB-Tumblebug initialization requirements (e.g., using `TumblebugInitChecker`).
+- Respect CB-Tumblebug's REST API patterns and authentication.
+- Use proper namespace management.
+
+#### cm-model Integration
+
+- Import shared models from `cm-model` package.
+- Ensure model compatibility between versions.
+- Use conversion utilities (`pkg/modelconv/`) when transforming data.
+
+### Environment Setup
+
+- **Local Development:** Use `replace` directives in `go.mod` for local dependency testing (e.g., `cb-tumblebug`, `cm-model`).
+- **Production:** Ensure `go.mod` specifies production versions.
+
+## Build and Run Instructions
+
+Always use the `Makefile` for build and run tasks.
+
+- **Build:** `make build` (builds `cm-beetle` binary in `cmd/cm-beetle/`).
+- **Run:** `make run` (sources `conf/setup.env` and runs the binary).
+- **Clean:** `make clean` (removes build artifacts).
+- **Lint:** `make lint` (runs `golangci-lint`).
+- **Test CLI:** `make test-cli` (builds and runs the test CLI).
+
+## API Documentation
+
+- The API is documented using **Swagger**.
+- If you modify API handlers, update the Swagger comments.
+- Regenerate documentation with: `make swag`.
+- Swagger files are located in `api/`.
+- **Example:**
+  ```go
+  // CreateMCI godoc
+  // @ID CreateMCI
+  // @Summary Create Multi-Cloud Infrastructure
+  // @Description Create a multi-cloud infrastructure
+  // @Tags [Migration] Infrastructure
+  // @Accept json
+  // @Produce json
+  // @Param nsId path string true "Namespace ID"
+  // @Success 200 {object} ResponseModel
+  // @Router /migration/ns/{nsId}/mci [post]
+  ```
+
+## Common Tasks
+
+- **Adding a new API endpoint:**
+
+  1. Define the handler in `pkg/api/rest/`.
+  2. Add the route in `cmd/cm-beetle/main.go` (or relevant router setup).
+  3. Add Swagger comments to the handler.
+  4. Run `make swag`.
+
+- **Running locally:**
+
+  1. Ensure `conf/setup.env` and `conf/config.yaml` are configured.
+  2. Run `make run`.
+
+- **Testing:**
+  - Use `go test ./...` for unit tests.
+  - Use `make test-cli` for integration-like testing with the CLI.

.github/instructions/analyzer.instructions.md

@@ -0,0 +1,21 @@
+---
+applyTo: "analyzer/**"
+---
+
+# Analyzer Module Instructions
+
+This directory (`analyzer/`) contains the **File System Analysis & Metadata Extraction Module**.
+It is a self-contained Go module with its own `go.mod`.
+
+## Key Constraints
+
+- **Independent Module:** Treat this as a separate library.
+- **No Upstream Dependencies:** Do NOT import packages from `cm-beetle/pkg/...` or `cm-beetle/cmd/...`.
+- **Dependency Management:** Add dependencies to `analyzer/go.mod`, not the root `go.mod`.
+
+## Functionality
+
+- **Directory Scanning:** Recursively list directory contents (`ListDirectory`).
+- **Metadata Extraction:** Analyze file properties (size, permissions, modification time).
+- **Pattern Filtering:** Filter files based on glob patterns (include/exclude).
+- **Usage:** Primarily used to analyze source infrastructure before migration.

.github/instructions/go.instructions.md

@@ -0,0 +1,41 @@
+---
+applyTo: "**/*.go"
+---
+
+# Go Coding Standards
+
+## Style & Conventions
+
+- **Style:** Follow **Effective Go** and **Go Code Review Comments**.
+- **Formatting:** Use `gofmt` or `goimports`.
+- **Linting:** Ensure code passes `golangci-lint` (run `make lint`).
+
+## Logging & Error Handling
+
+- **Logging:** Use `zerolog`.
+  - Pattern: `log.Error().Err(err).Msg("message")`
+- **Error Handling:**
+  - Handle errors explicitly.
+  - Return meaningful error messages and HTTP status codes using `model.Response`.
+
+## Configuration
+
+- **Viper:** Use `viper` for configuration management.
+
+## Import Conventions
+
+```go
+// External dependencies with specific versions
+// CB-Tumblebug imports (version specified in go.mod)
+tbmodel "github.com/cloud-barista/cb-tumblebug/src/core/model"
+tbresource "github.com/cloud-barista/cb-tumblebug/src/interface/rest/server/resource"
+"github.com/cloud-barista/cb-tumblebug/src/core/common/netutil"
+
+// cm-model imports - Two main packages (version specified in go.mod)
+cloudmodel "github.com/cloud-barista/cm-model/infra/cloud-model"
+onpremmodel "github.com/cloud-barista/cm-model/infra/on-premise-model"
+
+// Internal packages
+"github.com/cloud-barista/cm-beetle/pkg/config"
+"github.com/cloud-barista/cm-beetle/pkg/core/common"
+```

.github/instructions/markdown.instructions.md

@@ -0,0 +1,25 @@
+---
+applyTo: "**/*.md"
+---
+
+# Project documentation writing guidelines
+
+## General Guidelines
+
+- Write clear and concise documentation.
+- Use consistent terminology and style.
+- Include code examples where applicable.
+
+## Grammar
+
+- Use present tense verbs (is, open) instead of past tense (was, opened).
+- Write factual statements and direct commands. Avoid hypotheticals like "could" or "would".
+- Use active voice where the subject performs the action.
+- Write in second person (you) to speak directly to readers.
+
+## Markdown Guidelines
+
+- Use headings to organize content.
+- Use bullet points for lists.
+- Include links to related resources.
+- Use code blocks for code snippets.

.github/instructions/transx.instructions.md

@@ -0,0 +1,19 @@
+---
+applyTo: "transx/**"
+---
+
+# TransX Library Instructions
+
+This directory (`transx/`) contains the **Data Migration Library**.
+It is a self-contained Go module with its own `go.mod`.
+
+## Key Constraints
+
+- **Independent Module:** Treat this as a separate library.
+- **No Upstream Dependencies:** Do NOT import packages from `cm-beetle/pkg/...` or `cm-beetle/cmd/...`.
+- **Dependency Management:** Add dependencies to `transx/go.mod`, not the root `go.mod`.
+
+## Functionality
+
+- Supports `rsync` and `object-storage-api` transfer methods.
+- Supports Direct and Relay migration modes.

.github/prompts/api-guide.prompt.md

@@ -0,0 +1,70 @@
+---
+name: api-guide
+description: Generate API usage guide with JSON examples from Swagger specification
+argument-hint: Enter API path (e.g., /migration/ns/{nsId}/mci)
+agent: agent
+model: "Claude Sonnet 4.5"
+---
+
+You are the Lead Technical Writer for the Cloud-Barista project.
+
+[Target API Path]
+{{api_path}}
+_(If the above is empty or contains a placeholder, extract the API path from the user's chat message)_
+
+[Instructions]
+
+1. **Identify API Path:**
+
+   - If `{{api_path}}` is provided (replaced by CLI), use it.
+   - Otherwise, identify the API path (e.g., `/migration/...`) from the user's request.
+
+2. **Read Specification (Step-by-step):**
+   a. Read `api/swagger.yaml` and find the API path section
+   b. Identify the request body schema (e.g., `controller.MigrateInfraRequest`)
+   c. For each `$ref` in the request body, read that definition section
+   d. Repeat for nested `$ref` (e.g., `cloudmodel.MciReq` → `cloudmodel.CreateSubGroupReq`)
+   e. Do the same for response schema
+   f. Collect at least 3-4 levels of nested definitions to understand the complete structure
+
+3. **Generate Guide:**
+
+   - **Overview:** Briefly explain what this API does based on the Swagger summary/description. Include key features and purpose.
+   - **Request Example:** Create a realistic, detailed JSON request body example with meaningful values
+   - **Response Example:** Create a realistic JSON response example
+   - **Notes:** Add important notes about:
+     - Prerequisites or dependencies
+     - Resource creation order
+     - Error handling behaviors
+     - Best practices
+
+4. **Style:**
+   - Write in **English**.
+   - Use Markdown for clear formatting.
+   - Be thorough and detailed.
+
+[Output Format]
+
+## 🚀 API Guide: {{api_path}}
+
+### 📖 Overview
+
+(Detailed description with key features)
+
+### 📦 Request Example (JSON)
+
+```json
+...
+```
+
+### 📦 Response Example (JSON)
+
+```json
+...
+```
+
+### 📝 Notes
+
+1. **[Topic]:** (Important information)
+2. **[Topic]:** (Important information)
+   ...