feat: freeze CLI automation contract

Author: SysAdminDoc

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Changelog
 
+- Added: the headless CLI and localhost bridge now publish a versioned v1 JSON contract with a forward-compatible schema, stable exit codes, documented selectors/routes, and release-packaged schema fixtures.
 - Added: release builds now emit an offline-verifiable manifest with payload and ZIP SHA-256 hashes, source commit, runtime metadata, and a CycloneDX SBOM. Tagged CI builds publish GitHub artifact provenance; releases remain intentionally unsigned.
 - Added: an opt-in, notify-only update check under **System > Overview**. It queries the GitHub releases API with an `ETag` cache, compares the release tag with the installed version, and offers dismissible links to the release page without downloading or executing anything; failures stay silent beyond diagnostics.
 - Added: the UI now selects the Windows display language by default, resolves static, runtime, tray, dialog, and automation-accessible text through invariant resource keys with English fallback, and formats displayed values with the selected culture. A `-Culture` override and expanded/accented `qps-ploc` pseudo-locale exercise localization without requiring a translated build.

README.md

@@ -192,6 +192,12 @@ best-effort rollback from the GUI transaction path. JSON mode emits exactly one
 {"SchemaVersion":1,"Command":"get","Success":true,"ExitCode":0,"Data":{"Identity":"winrt:0123456789abcdef","Vcp":"0x10","Current":50,"Maximum":100,"Type":0},"Error":null}
 ```
 
+The envelope contract is versioned in [`schemas/monitorcontrol-cli-v1.schema.json`](schemas/monitorcontrol-cli-v1.schema.json)
+and is also packaged as `monitorcontrol-cli-v1.schema.json` in release ZIPs. Readers must use
+`SchemaVersion` and tolerate unknown fields; a breaking change requires a new schema version.
+Error objects always contain a stable `Code` and a human-readable `Message`, and the JSON output
+never includes bridge keys or other credentials.
+
 | Exit code | Meaning |
 |---:|---|
 | `0` | Success, including an `-IfNeeded` no-op |
@@ -202,6 +208,14 @@ best-effort rollback from the GUI transaction path. JSON mode emits exactly one
 | `6` | Risky write denied by the shared per-identity safety policy |
 | `10` | Unexpected internal or worker-start failure |
 
+The localhost bridge shares the same stable monitor selectors and uses these routes: an exact,
+body-free `GET /api/health` returns `{ "ok": true }` without authentication; authenticated
+`GET /api/monitors`, `/api/profiles`, and `/api/brightness` read state; authenticated `POST
+/api/brightness` accepts a percentage `value` and optional `monitor`; authenticated `POST
+/api/profile` accepts a profile `name`. Credentials are accepted only through
+`X-MonitorControl-Key` or `Authorization: Bearer`, never query strings or JSON bodies. Unknown
+routes and malformed requests return deterministic 4xx JSON responses.
+
 ### Build a Release ZIP
 ```powershell
 .\tools\build-release.ps1

schemas/monitorcontrol-cli-v1.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/SysAdminDoc/MonitorControl/schemas/monitorcontrol-cli-v1.schema.json",
+  "title": "MonitorControl Pro CLI JSON envelope v1",
+  "description": "Stable JSON output for the portable headless CLI. Unknown fields are intentionally allowed for forward-compatible readers.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["SchemaVersion", "Command", "Success", "ExitCode", "Data", "Error"],
+  "properties": {
+    "SchemaVersion": { "const": 1 },
+    "Command": {
+      "type": "string",
+      "enum": ["list", "get", "set", "profile", "diagnostics", "b", "s"]
+    },
+    "Success": { "type": "boolean" },
+    "ExitCode": { "type": "integer", "enum": [0, 2, 3, 4, 5, 6, 10] },
+    "Data": {},
+    "Error": {
+      "anyOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["Code", "Message"],
+          "properties": {
+            "Code": { "type": "string", "minLength": 1 },
+            "Message": { "type": "string" }
+          }
+        }
+      ]
+    }
+  }
+}

tests/MonitorControl.NoHardware.Tests.ps1

@@ -5436,6 +5436,19 @@ Describe "Headless CLI contract" {
         (($result.Envelope | ConvertTo-Json -Depth 10 -Compress) | ConvertFrom-Json).Error | Should -BeNullOrEmpty
     }
 
+    It "ships a forward-compatible CLI envelope schema" {
+        $schemaPath = Join-Path $script:RepoRoot "schemas\monitorcontrol-cli-v1.schema.json"
+        Test-Path -LiteralPath $schemaPath -PathType Leaf | Should -BeTrue
+        $schema = Get-Content -LiteralPath $schemaPath -Raw | ConvertFrom-Json
+        $schema.properties.SchemaVersion.const | Should -Be 1
+        @($schema.required) | Should -Contain "SchemaVersion"
+        @($schema.required) | Should -Contain "Error"
+        $schema.additionalProperties | Should -BeTrue
+        @($schema.properties.ExitCode.enum) | Should -Contain 10
+        @($schema.properties.Command.enum) | Should -Contain "diagnostics"
+        $schema.properties.Error.anyOf[1].additionalProperties | Should -BeTrue
+    }
+
     It "requires a stable monitor selector when more than one target is usable" {
         $monitors = @((New-CliTestMonitor), (New-CliTestMonitor -Identity "winrt:stable-b" -Label "Side display" -Handle ([IntPtr]0x7002)))
         $result = Invoke-MonitorControlCli -Command get -Argument 0x10 -MonitorData $monitors -ReadAction { throw "must not read" }

tools/build-release.ps1

@@ -17,8 +17,9 @@ $readmePath = Join-Path $repoRoot "README.md"
 $licensePath = Join-Path $repoRoot "LICENSE"
 $iconPath = Join-Path $repoRoot "icon.ico"
 $screenshotPath = Join-Path $repoRoot "screenshot.png"
+$cliSchemaPath = Join-Path $repoRoot "schemas\monitorcontrol-cli-v1.schema.json"
 
-foreach ($required in @($metadataPath, $scriptPath, $compilePath, $readmePath, $licensePath, $iconPath, $screenshotPath)) {
+foreach ($required in @($metadataPath, $scriptPath, $compilePath, $readmePath, $licensePath, $iconPath, $screenshotPath, $cliSchemaPath)) {
     if (-not (Test-Path -LiteralPath $required -PathType Leaf)) { throw "Missing release input: $required" }
 }
 
@@ -247,6 +248,7 @@ Copy-Item -LiteralPath $readmePath -Destination (Join-Path $stageRoot "README.md
 Copy-Item -LiteralPath $licensePath -Destination (Join-Path $stageRoot "LICENSE") -Force
 Copy-Item -LiteralPath $iconPath -Destination (Join-Path $stageRoot "icon.ico") -Force
 Copy-Item -LiteralPath $screenshotPath -Destination (Join-Path $stageRoot "screenshot.png") -Force
+Copy-Item -LiteralPath $cliSchemaPath -Destination (Join-Path $stageRoot "monitorcontrol-cli-v1.schema.json") -Force
 
 # Scoop resolves `shortcuts` against a file it can execute. A bare .ps1 is not one, and a GUI
 # app should not get a `bin` shim either, so the ZIP carries a launcher that starts the script