[API] Add "import/export app" commands

cmd/gendoc/docs.go

@@ -562,6 +562,55 @@ Contains a JSON object with the details of an error.
 				{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
 			},
 		},
+		{
+			OperationId: "importApp",
+			Method:      http.MethodPost,
+			Path:        "/v1/apps/import",
+			Parameters:  nil,
+			Request: (*struct {
+				FolderName string `form:"folder_name" description:"The name of the folder where the app will be stored." validate:"required"`
+				File       []byte `form:"file" description:"The ZIP archive containing the application structure. Must contain app.yaml and python folder." validate:"required"`
+			})(nil),
+			CustomSuccessResponse: &CustomResponseDef{
+				ContentType: "application/json",
+				StatusCode:  http.StatusCreated,
+				DataStructure: struct {
+					ID string `json:"id" description:"The Base64 encoded identifier of the imported application."`
+				}{},
+				Description: "Application imported successfully.",
+			},
+			Description: "Imports a new application from a ZIP file. The system extracts the archive, validates the app.yaml manifest, sanitizes the name, and returns the ID in Base64.",
+			Summary:     "Imports an app from ZIP",
+			Tags:        []Tag{ApplicationTag},
+			PossibleErrors: []ErrorResponse{
+				{StatusCode: http.StatusBadRequest, Reference: "#/components/responses/BadRequest"},
+				{StatusCode: http.StatusConflict, Reference: "#/components/responses/Conflict"},
+				{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
+			},
+		},
+		{
+			OperationId: "exportApp",
+			Method:      http.MethodGet,
+			Path:        "/v1/apps/{id}/export",
+			Request: (*struct {
+				ID string `path:"id" description:"application identifier."`
+			})(nil),
+			Parameters: nil,
+			CustomSuccessResponse: &CustomResponseDef{
+				ContentType:   "application/zip",
+				DataStructure: []byte{},
+				Description:   "The ZIP archive containing the application structure.",
+				StatusCode:    http.StatusOK,
+			},
+			Description: "Exports the application folder structure as a ZIP file.",
+			Summary:     "Exports an app as ZIP",
+			Tags:        []Tag{ApplicationTag},
+			PossibleErrors: []ErrorResponse{
+				{StatusCode: http.StatusBadRequest, Reference: "#/components/responses/BadRequest"},
+				{StatusCode: http.StatusNotFound, Reference: "#/components/responses/NotFound"},
+				{StatusCode: http.StatusInternalServerError, Reference: "#/components/responses/InternalServerError"},
+			},
+		},
 		{
 			OperationId: "getAppEvents",
 			Method:      http.MethodGet,

go.mod

@@ -27,6 +27,7 @@ require (
 	github.com/gofrs/flock v0.12.1
 	github.com/google/go-cmp v0.7.0
 	github.com/google/renameio/v2 v2.0.0
+	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.0
 	github.com/gosimple/slug v1.15.0
 	github.com/jedib0t/go-pretty/v6 v6.6.8
@@ -148,7 +149,6 @@ require (
 	github.com/google/gnostic-models v0.6.8 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
-	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/mux v1.8.1 // indirect
 	github.com/gosimple/unidecode v1.0.1 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.1 // indirect

internal/api/api.go

@@ -74,14 +74,15 @@ func NewHTTPRouter(
 	mux.Handle("GET /v1/apps", handlers.HandleAppList(dockerClient, idProvider, cfg))
 	mux.Handle("POST /v1/apps", handlers.HandleAppCreate(idProvider, cfg))
 	mux.Handle("GET /v1/apps/events", handlers.HandlerAppStatus(dockerClient, idProvider, cfg))
-
 	mux.Handle("GET /v1/apps/{appID}", handlers.HandleAppDetails(dockerClient, bricksIndex, idProvider, cfg))
 	mux.Handle("PATCH /v1/apps/{appID}", handlers.HandleAppDetailsEdits(dockerClient, bricksIndex, idProvider, cfg))
 	mux.Handle("GET /v1/apps/{appID}/logs", handlers.HandleAppLogs(dockerClient, idProvider, staticStore))
 	mux.Handle("POST /v1/apps/{appID}/start", handlers.HandleAppStart(dockerClient, provisioner, modelsIndex, bricksIndex, idProvider, cfg, staticStore))
 	mux.Handle("POST /v1/apps/{appID}/stop", handlers.HandleAppStop(dockerClient, idProvider))
 	mux.Handle("POST /v1/apps/{appID}/clone", handlers.HandleAppClone(dockerClient, idProvider, cfg))
 	mux.Handle("DELETE /v1/apps/{appID}", handlers.HandleAppDelete(dockerClient, idProvider))
+	mux.Handle("GET /v1/apps/{appID}/export", handlers.HandleAppExport(idProvider, cfg))
+	mux.Handle("POST /v1/apps/import", handlers.HandleAppImport(cfg, idProvider))
 	mux.Handle("GET /v1/apps/{appID}/exposed-ports", handlers.HandleAppPorts(bricksIndex, idProvider))
 	mux.Handle("PUT /v1/apps/{appID}/sketch/libraries/{libRef}", handlers.HandleSketchAddLibrary(idProvider))
 	mux.Handle("DELETE /v1/apps/{appID}/sketch/libraries/{libRef}", handlers.HandleSketchRemoveLibrary(idProvider))

internal/api/docs/openapi.yaml

@@ -522,6 +522,35 @@ paths:
       summary: Get application events
       tags:
       - Application
+  /v1/apps/{id}/export:
+    get:
+      description: Exports the application folder structure as a ZIP file.
+      operationId: exportApp
+      parameters:
+      - description: application identifier.
+        in: path
+        name: id
+        required: true
+        schema:
+          description: application identifier.
+          type: string
+      responses:
+        "200":
+          content:
+            application/zip:
+              schema:
+                format: base64
+                type: string
+          description: The ZIP archive containing the application structure.
+        "400":
+          $ref: '#/components/responses/BadRequest'
+        "404":
+          $ref: '#/components/responses/NotFound'
+        "500":
+          $ref: '#/components/responses/InternalServerError'
+      summary: Exports an app as ZIP
+      tags:
+      - Application
   /v1/apps/{id}/logs:
     get:
       description: Obtain a ServerSentEvnt stream of logs. It is possible to apply
@@ -673,6 +702,62 @@ paths:
       summary: Get application events
       tags:
       - Application
+  /v1/apps/import:
+    post:
+      description: Imports a new application from a ZIP file. The system extracts
+        the archive, validates the app.yaml manifest, sanitizes the name, and returns
+        the ID in Base64.
+      operationId: importApp
+      parameters:
+      - description: The name of the folder where the app will be stored.
+        in: query
+        name: folder_name
+        schema:
+          description: The name of the folder where the app will be stored.
+          type: string
+      - description: The ZIP archive containing the application structure. Must contain
+          app.yaml and python folder.
+        in: query
+        name: file
+        schema:
+          description: The ZIP archive containing the application structure. Must
+            contain app.yaml and python folder.
+          format: base64
+          type: string
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              properties:
+                file:
+                  description: The ZIP archive containing the application structure.
+                    Must contain app.yaml and python folder.
+                  format: base64
+                  type: string
+                folder_name:
+                  description: The name of the folder where the app will be stored.
+                  type: string
+              type: object
+      responses:
+        "201":
+          content:
+            application/json:
+              schema:
+                properties:
+                  id:
+                    description: The Base64 encoded identifier of the imported application.
+                    type: string
+                type: object
+          description: Application imported successfully.
+        "400":
+          $ref: '#/components/responses/BadRequest'
+        "409":
+          $ref: '#/components/responses/Conflict'
+        "500":
+          $ref: '#/components/responses/InternalServerError'
+      summary: Imports an app from ZIP
+      tags:
+      - Application
   /v1/bricks:
     get:
       description: Returns all the existing bricks. Bricks that are ready to use are

internal/api/handlers/app_export.go

@@ -0,0 +1,48 @@
+package handlers
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+
+	"github.com/arduino/arduino-app-cli/internal/api/models"
+	"github.com/arduino/arduino-app-cli/internal/orchestrator"
+	"github.com/arduino/arduino-app-cli/internal/orchestrator/app"
+	"github.com/arduino/arduino-app-cli/internal/orchestrator/config"
+	"github.com/arduino/arduino-app-cli/internal/render"
+)
+
+func HandleAppExport(
+	idProvider *app.IDProvider,
+	cfg config.Configuration,
+) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		id, err := idProvider.IDFromBase64(r.PathValue("appID"))
+		if err != nil {
+			render.EncodeResponse(w, http.StatusPreconditionFailed, models.ErrorResponse{Details: "invalid id"})
+			return
+		}
+		app, err := app.Load(id.ToPath())
+		if err != nil {
+			slog.Error("Unable to parse the app.yaml", slog.String("error", err.Error()), slog.String("path", id.String()))
+			if errors.Is(err, os.ErrNotExist) {
+				render.EncodeResponse(w, http.StatusNotFound, models.ErrorResponse{Details: "unable to find the app"})
+			} else {
+				render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "unable to parse the app"})
+			}
+			return
+		}
+
+		zipBytes, fileName, err := orchestrator.ExportAppZip(r.Context(), app)
+		if err != nil {
+			slog.Error("failed to export app", slog.String("app_id", id.String()), slog.String("error", err.Error()))
+			render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{
+				Details: "Failed to generate archive.",
+			})
+			return
+		}
+
+		render.EncodeZipResponse(w, http.StatusOK, zipBytes, fileName)
+	}
+}

internal/api/handlers/app_import.go

@@ -0,0 +1,88 @@
+// This file is part of arduino-app-cli.
+//
+// Copyright 2025 ARDUINO SA (http://www.arduino.cc/)
+// ... (License header standard) ...
+
+package handlers
+
+import (
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"os"
+	"strings"
+
+	"github.com/arduino/arduino-app-cli/internal/api/models"
+	"github.com/arduino/arduino-app-cli/internal/orchestrator"
+	"github.com/arduino/arduino-app-cli/internal/orchestrator/app"
+	"github.com/arduino/arduino-app-cli/internal/orchestrator/config"
+	"github.com/arduino/arduino-app-cli/internal/render"
+)
+
+type ImportResponse struct {
+	ID string `json:"id"`
+}
+
+func HandleAppImport(
+	cfg config.Configuration,
+	idProvider *app.IDProvider,
+) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		folderName := strings.TrimSpace(r.FormValue("folder_name"))
+		if folderName == "" {
+			render.EncodeResponse(w, http.StatusBadRequest, models.ErrorResponse{Details: "missing required 'folder_name' parameter"})
+			return
+		}
+
+		file, _, err := r.FormFile("file")
+		if err != nil {
+			slog.Error("missing file parameter", slog.String("error", err.Error()))
+			render.EncodeResponse(w, http.StatusBadRequest, models.ErrorResponse{Details: "missing required file parameter"})
+			return
+		}
+		defer file.Close()
+
+		tempFile, err := os.CreateTemp("", "app-import-*.zip")
+		if err != nil {
+			slog.Error("unable to create temp file", slog.String("error", err.Error()))
+			render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "internal server error"})
+			return
+		}
+		tempPath := tempFile.Name()
+		defer os.Remove(tempPath)
+
+		if _, err := io.Copy(tempFile, file); err != nil {
+			tempFile.Close()
+			slog.Error("unable to save upload to temp file", slog.String("error", err.Error()))
+			render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "failed to save uploaded file"})
+			return
+		}
+		tempFile.Close()
+
+		appID, err := orchestrator.ImportAppFromZip(cfg, tempPath, folderName, idProvider)
+		if err != nil {
+			handleImportError(w, err)
+			return
+		}
+
+		slog.Info("app imported successfully", slog.String("app_id", appID))
+		render.EncodeResponse(w, http.StatusCreated, ImportResponse{ID: appID})
+	}
+}
+
+func handleImportError(w http.ResponseWriter, err error) {
+	slog.Error("import failed", slog.String("error", err.Error()))
+
+	if errors.Is(err, orchestrator.ErrAppAlreadyExists) {
+		render.EncodeResponse(w, http.StatusConflict, models.ErrorResponse{Details: err.Error()})
+		return
+	}
+	if errors.Is(err, orchestrator.ErrBadRequest) ||
+		strings.Contains(err.Error(), "not a valid zip file") {
+		render.EncodeResponse(w, http.StatusBadRequest, models.ErrorResponse{Details: err.Error()})
+		return
+	}
+
+	render.EncodeResponse(w, http.StatusInternalServerError, models.ErrorResponse{Details: "failed to process the archive: " + err.Error()})
+}