SLD-789: Add PowerShell Proxy OpenAPI spec by Kh4lil · Pull Request #199 · Software-Hardware-Integration-Lab/OpenAPI

Khalil O. (Kh4lil) · 2026-08-19T21:30:26Z

Hi! This is related to this ticket: https://asg-shicorp.atlassian.net/browse/SLD-789?focusedCommentId=49205

The PR adds the PowerShell Proxy to the central OpenAPI repo, I followed the existing SHIELD/Data Gateway/URL Shortener SDK pattern.

Adds the OpenAPI 3.1.1 contract for POST /api/proxy
Adds @software-hardware-integration-lab/sdk-powershell-proxy
Adds the service to the existing build/publish workflows and API docs
Keeps PowerShell cmdlet output untyped so Microsoft response fields are preserved

Copilot

Pull request overview

Adds the SHIELD PowerShell Proxy service to this central OpenAPI repository by introducing a new OpenAPI 3.1.1 spec and a generated TypeScript SDK package, and wiring both into existing publishing/documentation workflows.

Changes:

Added specs/PowerShell-Proxy.json describing POST /api/proxy (authenticated allowlisted cmdlet execution).
Added a new TypeScript SDK package at src/powershellProxy/TypeScript (Kiota-generated client + factory/export surface).
Registered the service in API docs and CI publish/build workflows.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`src/powershellProxy/TypeScript/tsconfig.json`	TypeScript build configuration for the new SDK package.
`src/powershellProxy/TypeScript/README.md`	Usage and installation documentation for the new SDK.
`src/powershellProxy/TypeScript/package.json`	Package metadata, scripts, and dependencies for publishing the SDK.
`src/powershellProxy/TypeScript/LICENSE`	MIT license for the new SDK package.
`src/powershellProxy/TypeScript/index.ts`	Public SDK entrypoint: client factory + type exports.
`src/powershellProxy/TypeScript/eslint.config.js`	Lint configuration for the new SDK package.
`src/powershellProxy/TypeScript/.npmrc`	npm configuration for the new SDK package.
`src/powershellProxy/TypeScript/.npmignore`	Publish-time ignore rules for the new SDK package.
`specs/PowerShell-Proxy.json`	New OpenAPI 3.1.1 contract for the PowerShell Proxy endpoint.
`apis.yaml`	Adds PowerShell Proxy to the API catalog for documentation/discovery.
`.github/workflows/Publish-Specs.yml`	Adds PowerShell Proxy spec to the Swagger UI list on GitHub Pages.
`.github/workflows/Publish-NPM.yml`	Adds the new SDK path to the NPM publish matrix.
`.github/workflows/Build.yml`	Adds the new SDK path to the build/generate matrix.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+                    - name: PowerShellProxy
+                      sdkPath: 'src/powershellProxy/TypeScript'
+                      specPath: 'specs/PowerShell-Proxy.json'


+                    - name: PowerShellProxy
+                      sdkPath: 'src/powershellProxy/TypeScript'
+                      specPath: 'specs/PowerShell-Proxy.json'


+
+```TypeScript
+/** Custom host and endpoint base to as an example for something behind a layer 7 load balancer, E.g. Azure App Gateway or Azure API Gateway. If in debug mode, run against localhost. */
+const customBaseUrl = debugMode ? new URL('http://localhost:7071') : new URL('https://custom-host.example.com/Ballance/Instance1/');


Copilot

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/powershellProxy/TypeScript/README.md:62

Typo/grammar in the example URL and comment: "Ballance" should be "Balance", and the sentence reads as "base to as an example" which is ungrammatical.

/** Custom host and endpoint base to as an example for something behind a layer 7 load balancer, E.g. Azure App Gateway or Azure API Gateway. If in debug mode, run against localhost. */
const customBaseUrl = debugMode ? new URL('http://localhost:7071') : new URL('https://custom-host.example.com/Ballance/Instance1/');

Co-authored-by: Kh4lil <23207971+Kh4lil@users.noreply.github.com>

Pasha Zayko (pasha-zayko)

This is partial review, still a couple of files to get through.

Also, update OpenAPI.code-workspace file so the folder for powershellProxy shows up in the UI in VSC

Pasha Zayko (pasha-zayko) · 2026-09-22T15:16:33Z

+    },
+    "info": {
+        "contact": {
+            "email": "elliot_huffman@shi.com",


This is not going to be accurate, please use some form of group contact.
As we are migrating into corp the name is likely to become either just SHI or something very specific to our organization (like ASG).

Pasha Zayko (pasha-zayko) · 2026-09-22T19:55:52Z

+                    "value": {
+                        "description": "Arbitrary JSON-compatible parameter value, retained as opaque data. The server owns command-specific parameter validation; this value is never inspected, typed, or transformed by the contract."
+                    }
+                }


examples section missing, it would be a good place to showcase what values "value" prop can be

Pasha Zayko (pasha-zayko) · 2026-09-22T19:57:37Z

+                    "result": {
+                        "$ref": "#/components/schemas/ProxyExecutionResult"
+                    }
+                }


examples section missing

Pasha Zayko (pasha-zayko) · 2026-09-22T19:58:40Z

+                        "minItems": 0,
+                        "items": {
+                            "description": "Arbitrary JSON-compatible command output item."
+                        }


examples section missing

Pasha Zayko (pasha-zayko) · 2026-09-22T19:58:49Z

+                        "minItems": 0,
+                        "items": {
+                            "$ref": "#/components/schemas/ProxyWarning"
+                        }


examples section missing

Pasha Zayko (pasha-zayko) · 2026-09-22T20:01:19Z

+                            "The requested cmdlet is not allowed."
+                        ]
+                    }
+                }


overall examples section missing for the object

Pasha Zayko (pasha-zayko) · 2026-09-22T20:01:32Z

+                    "result": {
+                        "$ref": "#/components/schemas/ProxyInfoResult"
+                    }
+                }


examples section missing

Pasha Zayko (pasha-zayko) · 2026-09-22T20:02:53Z

+                    "version": {
+                        "description": "Semantic version of the deployed proxy application.",
+                        "type": "string",
+                        "minLength": 1,


should this have a defined pattern since its semantic version ?

Pasha Zayko (pasha-zayko) · 2026-09-22T20:04:39Z

+    },
+    "openapi": "3.1.1",
+    "paths": {
+        "/api/proxy": {


So far for Shield the path had each segment starting with capital first letter. Does this work intend to deviate?

Pasha Zayko (pasha-zayko) · 2026-09-22T20:38:28Z

@@ -0,0 +1,7 @@
+import { defineConfig, globalIgnores } from 'eslint/config'
+import { eslintConfig } from '@shi-corp/development-utilities/optimized/lint/base.js'


This should be changed to reference of the new package location SHI - Lab (@Software-Hardware-Integration-Lab)

Pasha Zayko (pasha-zayko)

Additional comments

Pasha Zayko (pasha-zayko) · 2026-09-23T20:48:36Z

I am not certain about the changes here as we have reachability working fine elsewhere without these. I would avoid the modification at the moment unless we have some supported documentation to reference.

Pasha Zayko (pasha-zayko) · 2026-09-23T20:49:26Z

This file should be regenerated before merge

feat: add PowerShell Proxy OpenAPI SDK

d3f6b3f

Copilot AI lite review requested due to automatic review settings August 19, 2026 21:30

Copilot started reviewing on behalf of Khalil O. (Kh4lil) August 19, 2026 21:30 View session

Copilot AI reviewed Aug 19, 2026

View reviewed changes

fix: declare Kiota HTTP dependency

17b595b

Khalil O. (Kh4lil) requested a lite review from Copilot August 19, 2026 21:48

Copilot started reviewing on behalf of Khalil O. (Kh4lil) August 19, 2026 21:48 View session

Copilot AI reviewed Aug 19, 2026

View reviewed changes

Khalil O. (Kh4lil) added 2 commits September 15, 2026 14:57

Update PowerShell Proxy OpenAPI contract

7cc1d30

Fix Socket PR reachability scan

1b159f0

Copilot started work on behalf of Khalil O. (Kh4lil) September 15, 2026 20:15 View session

Fix reachability workflow PR comment permissions

8554b19

Co-authored-by: Kh4lil <23207971+Kh4lil@users.noreply.github.com>

Copilot finished work on behalf of Khalil O. (Kh4lil) September 15, 2026 20:19

Khalil O. (Kh4lil) assigned Pasha Zayko (pasha-zayko) and pr0uxx Sep 16, 2026

Pasha Zayko (pasha-zayko) requested changes Sep 22, 2026

View reviewed changes

Pasha Zayko (pasha-zayko) requested changes Sep 23, 2026

View reviewed changes

		@@ -0,0 +1,7 @@
		import { defineConfig, globalIgnores } from 'eslint/config'
		import { eslintConfig } from '@shi-corp/development-utilities/optimized/lint/base.js'

Conversation

Khalil O. (Kh4lil) commented Aug 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Pasha Zayko (pasha-zayko) left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Pasha Zayko (pasha-zayko) left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants