api: add dedicated /instances/{id}/stat endpoint

Add a separate HTTP endpoint for querying filesystem path info in guests.
This replaces the overloaded 'direction: stat' option in the cp WebSocket
endpoint with a cleaner REST API.

- Add PathInfo schema with exists, is_dir, is_file, is_symlink, etc.
- Add GET /instances/{id}/stat endpoint with path and follow_links params
- Add stat method to stainless.yaml for SDK generation

The new endpoint:
- Uses simple HTTP GET instead of WebSocket overhead
- Enables autogenerated SDK methods (client.Instances.Stat())
- Mirrors the guest agent's separate StatPath RPC
- Is self-documenting via OpenAPI spec

Author: rgarcia

cmd/api/api/cp.go

@@ -27,7 +27,7 @@ func (e *cpErrorSent) Unwrap() error { return e.err }
 
 // CpRequest represents the JSON body for copy requests
 type CpRequest struct {
-	// Direction: "to" copies from client to guest, "from" copies from guest to client, "stat" queries path info
+	// Direction: "to" copies from client to guest, "from" copies from guest to client
 	Direction string `json:"direction"`
 	// Path in the guest filesystem
 	GuestPath string `json:"guest_path"`
@@ -45,19 +45,6 @@ type CpRequest struct {
 	Gid uint32 `json:"gid,omitempty"`
 }
 
-// CpStatResponse contains information about a path in the guest
-type CpStatResponse struct {
-	Type       string `json:"type"` // "stat"
-	Exists     bool   `json:"exists"`
-	IsDir      bool   `json:"is_dir"`
-	IsFile     bool   `json:"is_file"`
-	IsSymlink  bool   `json:"is_symlink,omitempty"`
-	LinkTarget string `json:"link_target,omitempty"`
-	Mode       uint32 `json:"mode"`
-	Size       int64  `json:"size"`
-	Error      string `json:"error,omitempty"`
-}
-
 // CpFileHeader is sent before file data in WebSocket protocol
 type CpFileHeader struct {
 	Type       string `json:"type"` // "header"
@@ -165,10 +152,8 @@ func (s *ApiService) CpHandler(w http.ResponseWriter, r *http.Request) {
 		cpErr = s.handleCopyTo(ctx, ws, inst, cpReq)
 	case "from":
 		cpErr = s.handleCopyFrom(ctx, ws, inst, cpReq)
-	case "stat":
-		cpErr = s.handleStat(ctx, ws, inst, cpReq)
 	default:
-		cpErr = fmt.Errorf("invalid direction: %s (must be 'to', 'from', or 'stat')", cpReq.Direction)
+		cpErr = fmt.Errorf("invalid direction: %s (must be 'to' or 'from')", cpReq.Direction)
 	}
 
 	duration := time.Since(startTime)
@@ -383,34 +368,3 @@ func (s *ApiService) handleCopyFrom(ctx context.Context, ws *websocket.Conn, ins
 	return nil
 }
 
-// handleStat returns information about a path in the guest
-func (s *ApiService) handleStat(ctx context.Context, ws *websocket.Conn, inst *instances.Instance, req CpRequest) error {
-	grpcConn, err := guest.GetOrCreateConnPublic(ctx, inst.VsockSocket)
-	if err != nil {
-		return fmt.Errorf("get grpc connection: %w", err)
-	}
-
-	client := guest.NewGuestServiceClient(grpcConn)
-	resp, err := client.StatPath(ctx, &guest.StatPathRequest{
-		Path:        req.GuestPath,
-		FollowLinks: req.FollowLinks,
-	})
-	if err != nil {
-		return fmt.Errorf("stat path: %w", err)
-	}
-
-	statResp := CpStatResponse{
-		Type:       "stat",
-		Exists:     resp.Exists,
-		IsDir:      resp.IsDir,
-		IsFile:     resp.IsFile,
-		IsSymlink:  resp.IsSymlink,
-		LinkTarget: resp.LinkTarget,
-		Mode:       resp.Mode,
-		Size:       resp.Size,
-		Error:      resp.Error,
-	}
-	respJSON, _ := json.Marshal(statResp)
-	return ws.WriteMessage(websocket.TextMessage, respJSON)
-}
-

cmd/api/api/instances.go

@@ -8,6 +8,7 @@ import (
 	"net/http"
 
 	"github.com/c2h5oh/datasize"
+	"github.com/onkernel/hypeman/lib/guest"
 	"github.com/onkernel/hypeman/lib/instances"
 	"github.com/onkernel/hypeman/lib/logger"
 	mw "github.com/onkernel/hypeman/lib/middleware"
@@ -430,6 +431,73 @@ func (s *ApiService) GetInstanceLogs(ctx context.Context, request oapi.GetInstan
 	return logsStreamResponse{logChan: logChan}, nil
 }
 
+// StatInstancePath returns information about a path in the guest filesystem
+// The id parameter can be an instance ID, name, or ID prefix
+// Note: Resolution is handled by ResolveResource middleware
+func (s *ApiService) StatInstancePath(ctx context.Context, request oapi.StatInstancePathRequestObject) (oapi.StatInstancePathResponseObject, error) {
+	log := logger.FromContext(ctx)
+
+	inst := mw.GetResolvedInstance[instances.Instance](ctx)
+	if inst == nil {
+		return oapi.StatInstancePath500JSONResponse{
+			Code:    "internal_error",
+			Message: "resource not resolved",
+		}, nil
+	}
+
+	if inst.State != instances.StateRunning {
+		return oapi.StatInstancePath409JSONResponse{
+			Code:    "invalid_state",
+			Message: fmt.Sprintf("instance must be running (current state: %s)", inst.State),
+		}, nil
+	}
+
+	// Connect to guest agent
+	grpcConn, err := guest.GetOrCreateConnPublic(ctx, inst.VsockSocket)
+	if err != nil {
+		log.ErrorContext(ctx, "failed to get grpc connection", "error", err)
+		return oapi.StatInstancePath500JSONResponse{
+			Code:    "internal_error",
+			Message: "failed to connect to guest agent",
+		}, nil
+	}
+
+	client := guest.NewGuestServiceClient(grpcConn)
+	followLinks := false
+	if request.Params.FollowLinks != nil {
+		followLinks = *request.Params.FollowLinks
+	}
+
+	resp, err := client.StatPath(ctx, &guest.StatPathRequest{
+		Path:        request.Params.Path,
+		FollowLinks: followLinks,
+	})
+	if err != nil {
+		log.ErrorContext(ctx, "stat path failed", "error", err, "path", request.Params.Path)
+		return oapi.StatInstancePath500JSONResponse{
+			Code:    "internal_error",
+			Message: "failed to stat path in guest",
+		}, nil
+	}
+
+	// Convert types from protobuf to OAPI
+	mode := int(resp.Mode)
+	response := oapi.StatInstancePath200JSONResponse{
+		Exists:     resp.Exists,
+		IsDir:      &resp.IsDir,
+		IsFile:     &resp.IsFile,
+		IsSymlink:  &resp.IsSymlink,
+		LinkTarget: &resp.LinkTarget,
+		Mode:       &mode,
+		Size:       &resp.Size,
+	}
+	// Include error message if stat failed (e.g., permission denied)
+	if resp.Error != "" {
+		response.Error = &resp.Error
+	}
+	return response, nil
+}
+
 // AttachVolume attaches a volume to an instance (not yet implemented)
 func (s *ApiService) AttachVolume(ctx context.Context, request oapi.AttachVolumeRequestObject) (oapi.AttachVolumeResponseObject, error) {
 	return oapi.AttachVolume500JSONResponse{