feat(drivers): [PPT-2232] add endpoint to fetch driver readme files (#416)

* feat(drivers): add endpoint to fetch driver readme files

Add GET /:id/readme endpoint that retrieves readme markdown files for drivers from their git repository. The endpoint constructs the readme path from the driver's file_name, validates file existence at the driver's commit, and returns the file contents.

* chore(shard.lock): update shards

* doc(openapi): dock gen

* chore(drivers): crystal tool format

Author: chillfox

OPENAPI_DOC.yml

@@ -7476,6 +7476,75 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
+  /api/engine/v2/drivers/{id}/readme:
+    get:
+      summary: get the readme for a driver
+      tags:
+      - Drivers
+      operationId: PlaceOS::Api::Drivers_readme
+      parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+      responses:
+        200:
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/String'
+        409:
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
+        401:
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
+        403:
+          description: Forbidden
+        404:
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
+        408:
+          description: Request Timeout
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
+        400:
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
+        422:
+          description: Unprocessable Entity
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
+        406:
+          description: Not Acceptable
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
+        415:
+          description: Unsupported Media Type
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
   /api/engine/v2/drivers/{id}/recompile:
     post:
       summary: force recompile a driver, useful if libraries and supporting files

src/placeos-rest-api/controllers/drivers.cr

@@ -1,4 +1,5 @@
 require "./application"
+require "git-repository"
 
 module PlaceOS::Api
   class Drivers < Application
@@ -7,10 +8,10 @@ module PlaceOS::Api
     # Scopes
     ###############################################################################################
 
-    before_action :can_read, only: [:index, :show]
+    before_action :can_read, only: [:index, :show, :readme]
     before_action :can_write, only: [:create, :update, :destroy, :remove]
 
-    before_action :check_admin, except: [:index, :show]
+    before_action :check_admin, except: [:index, :show, :readme]
 
     ###############################################################################################
 
@@ -23,6 +24,10 @@ module PlaceOS::Api
 
     getter! current_driver : ::PlaceOS::Model::Driver
 
+    getter! current_repo : ::PlaceOS::Model::Repository
+
+    # class_property repository_dir : String = File.expand_path("./repositories")
+
     # Response helpers
     ###############################################################################################
 
@@ -72,6 +77,41 @@ module PlaceOS::Api
       current_driver
     end
 
+    # get the readme for a driver
+    @[AC::Route::GET("/:id/readme")]
+    def readme : String
+      # Get the repository for the current driver
+      if (repository = current_driver.repository).nil?
+        Log.error { {repository_id: current_driver.repository_id, message: "failed to load driver's repository"} }
+        raise "failed to load driver's repository"
+      end
+
+      # Construct the readme file path from the driver's file_name
+      # e.g., "drivers/place/auto_release.cr" -> "drivers/place/auto_release_readme.md"
+      driver_file_name = current_driver.file_name
+      readme_path = driver_file_name.chomp(".cr") + "_readme.md"
+
+      # Create GitRepository instance
+      repository_path = File.join(Repositories.repository_dir, repository.folder_name)
+      git_repo = GitRepository.new(repository_path)
+
+      # Check if the readme file exists using the driver's commit
+      files = git_repo.file_list(ref: current_driver.commit, path: readme_path)
+      file_exists = !files.empty?
+
+      if file_exists
+        # Use file_contents to fetch the readme file
+        begin
+          git_repo.file_contents(ref: current_driver.commit, path: readme_path)
+        rescue e
+          Log.error(exception: e) { {readme_path: readme_path, message: "failed to fetch readme file contents"} }
+          raise Error::NotFound.new("Failed to fetch README file contents: #{e.message}")
+        end
+      else
+        raise Error::NotFound.new("README file not found: #{readme_path}")
+      end
+    end
+
     # udpate a drivers details
     @[AC::Route::PATCH("/:id", body: :driver)]
     @[AC::Route::PUT("/:id", body: :driver)]