From f17b9a95bdb340880ab9cbf730ff8a4e087c2ff9 Mon Sep 17 00:00:00 2001 From: Mia Bennett Date: Thu, 16 Oct 2025 13:42:21 +0930 Subject: [PATCH 1/4] 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. --- src/placeos-rest-api/controllers/drivers.cr | 45 ++++++++++++++++++++- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/src/placeos-rest-api/controllers/drivers.cr b/src/placeos-rest-api/controllers/drivers.cr index 106989e1..10ea1701 100644 --- a/src/placeos-rest-api/controllers/drivers.cr +++ b/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,11 @@ 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 +78,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)] From 7be3d4be365c4bca8f6dd11529c31c396c21860a Mon Sep 17 00:00:00 2001 From: Mia Bennett Date: Mon, 20 Oct 2025 10:04:18 +0930 Subject: [PATCH 2/4] chore(shard.lock): update shards --- shard.lock | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/shard.lock b/shard.lock index 64d6f8bf..c4c73099 100644 --- a/shard.lock +++ b/shard.lock @@ -7,7 +7,7 @@ shards: action-controller: git: https://github.com/spider-gazelle/action-controller.git - version: 7.6.0 + version: 7.6.1 active-model: git: https://github.com/spider-gazelle/active-model.git @@ -73,6 +73,10 @@ shards: git: https://github.com/spider-gazelle/crystal-dtls.git version: 0.9.1 + ed25519: + git: https://github.com/spider-gazelle/ed25519.git + version: 1.1.0 + email: git: https://github.com/arcage/crystal-email.git version: 0.7.1 @@ -95,7 +99,7 @@ shards: git-repository: git: https://github.com/place-labs/git-repository.git - version: 1.5.0 + version: 1.7.0 google: git: https://github.com/placeos/google.git @@ -131,7 +135,7 @@ shards: jwt: git: https://github.com/crystal-community/jwt.git - version: 1.6.1 + version: 1.7.1 log_helper: git: https://github.com/spider-gazelle/log_helper.git @@ -143,7 +147,7 @@ shards: lucky_router: git: https://github.com/luckyframework/lucky_router.git - version: 0.6.0 + version: 0.6.1 murmur3: git: https://github.com/aca-labs/murmur3.git @@ -163,7 +167,7 @@ shards: openssl_ext: git: https://github.com/spider-gazelle/openssl_ext.git - version: 2.4.4 + version: 2.6.3 pars: # Overridden git: https://github.com/spider-gazelle/pars.git @@ -179,7 +183,7 @@ shards: pg-orm: git: https://github.com/spider-gazelle/pg-orm.git - version: 2.0.3 + version: 2.0.5 pinger: git: https://github.com/spider-gazelle/pinger.git @@ -187,7 +191,7 @@ shards: place_calendar: git: https://github.com/placeos/calendar.git - version: 4.26.0 + version: 4.28.0 placeos-compiler: git: https://github.com/placeos/compiler.git @@ -195,19 +199,19 @@ shards: placeos-core: git: https://github.com/placeos/core.git - version: 4.19.0+git.commit.d62bb48c466089e1e6de6cc747d344d7bbd6cf91 + version: 4.20.1+git.commit.7bbcb3e5b11ac6dab9991e16c689c7594a4f2655 placeos-core-client: # Overridden git: https://github.com/placeos/core-client.git - version: 1.1.0 + version: 1.2.1 placeos-driver: git: https://github.com/placeos/driver.git - version: 7.11.4 + version: 7.13.2 placeos-frontend-loader: git: https://github.com/placeos/frontend-loader.git - version: 2.7.1+git.commit.a7609824cb43c8077d24a97801c6600fa1f6395c + version: 2.7.1+git.commit.528a985032f6f7d184f3e87331d0b518f467a379 placeos-log-backend: git: https://github.com/place-labs/log-backend.git @@ -215,7 +219,7 @@ shards: placeos-models: git: https://github.com/placeos/models.git - version: 9.72.3 + version: 9.76.1 placeos-resource: git: https://github.com/place-labs/resource.git @@ -263,7 +267,7 @@ shards: search-ingest: git: https://github.com/placeos/search-ingest.git - version: 2.11.2+git.commit.6213b2f66d2ff9814cefbfdf9224d0e138505d21 + version: 2.11.3+git.commit.073e390a5a7326658f30f03d73edee9d6f6e5ca6 secrets-env: # Overridden git: https://github.com/spider-gazelle/secrets-env.git From 908b40894a10583f0d76c116272af0d2192bb56c Mon Sep 17 00:00:00 2001 From: Mia Bennett Date: Mon, 20 Oct 2025 10:17:41 +0930 Subject: [PATCH 3/4] doc(openapi): dock gen --- OPENAPI_DOC.yml | 179 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) diff --git a/OPENAPI_DOC.yml b/OPENAPI_DOC.yml index 5044cb71..67f9b6fc 100644 --- a/OPENAPI_DOC.yml +++ b/OPENAPI_DOC.yml @@ -6307,6 +6307,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 @@ -21639,6 +21708,9 @@ components: description: type: string nullable: true + hidden: + type: boolean + nullable: true parent_category_id: type: string nullable: true @@ -21741,6 +21813,58 @@ components: barcode: type: string nullable: true + name: + type: string + nullable: true + client_ids: + type: object + nullable: true + map_id: + type: string + nullable: true + bookable: + type: boolean + nullable: true + accessible: + type: boolean + nullable: true + zones: + type: array + items: + type: string + nullable: true + place_groups: + type: array + items: + type: string + nullable: true + assigned_to: + type: string + nullable: true + assigned_name: + type: string + nullable: true + features: + type: array + items: + type: string + nullable: true + images: + type: array + items: + type: string + nullable: true + notes: + type: string + nullable: true + security_system_groups: + type: array + items: + type: string + nullable: true + parent_id: + type: string + nullable: true asset_type_id: type: string nullable: true @@ -21778,6 +21902,58 @@ components: barcode: type: string nullable: true + name: + type: string + nullable: true + client_ids: + type: object + nullable: true + map_id: + type: string + nullable: true + bookable: + type: boolean + nullable: true + accessible: + type: boolean + nullable: true + zones: + type: array + items: + type: string + nullable: true + place_groups: + type: array + items: + type: string + nullable: true + assigned_to: + type: string + nullable: true + assigned_name: + type: string + nullable: true + features: + type: array + items: + type: string + nullable: true + images: + type: array + items: + type: string + nullable: true + notes: + type: string + nullable: true + security_system_groups: + type: array + items: + type: string + nullable: true + parent_id: + type: string + nullable: true asset_type_id: type: string nullable: true @@ -25156,6 +25332,9 @@ components: - driver - interface nullable: true + root_path: + type: string + nullable: true has_runtime_error: type: boolean nullable: true From 82dd3351c6239938a09384affe4139088d1cc434 Mon Sep 17 00:00:00 2001 From: Mia Bennett Date: Mon, 20 Oct 2025 10:53:46 +0930 Subject: [PATCH 4/4] chore(drivers): crystal tool format --- src/placeos-rest-api/controllers/drivers.cr | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/placeos-rest-api/controllers/drivers.cr b/src/placeos-rest-api/controllers/drivers.cr index 10ea1701..c67099b3 100644 --- a/src/placeos-rest-api/controllers/drivers.cr +++ b/src/placeos-rest-api/controllers/drivers.cr @@ -25,9 +25,8 @@ module PlaceOS::Api getter! current_driver : ::PlaceOS::Model::Driver getter! current_repo : ::PlaceOS::Model::Repository - # class_property repository_dir : String = File.expand_path("./repositories") - + # class_property repository_dir : String = File.expand_path("./repositories") # Response helpers ###############################################################################################