adb-ready 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -9,6 +9,20 @@ breaking changes.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-29
+
+### Added
+
+- Add a packaged JSON Schema for the stable JSON result and NDJSON event
+  envelopes, plus an explicit 1.x compatibility, deprecation, migration, and
+  support-claim policy for CLI, configuration, automation, and MCP consumers.
+
+### Changed
+
+- Strengthen package and release verification so the automation schema is
+  always shipped and generated agent contracts cannot drift from the package
+  version.
+
 ## [0.8.0] - 2026-09-29
 
 ### Added
@@ -507,7 +521,8 @@ breaking changes.
   explainable configuration precedence.
 - Human, plain, JSON, and NDJSON output across Node, Bun, and Deno entrypoints.
 
-[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/Adam014/adb-ready/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/Adam014/adb-ready/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/Adam014/adb-ready/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/Adam014/adb-ready/compare/v0.5.1...v0.6.0

package/README.md

@@ -292,6 +292,7 @@ Android transport backend.
 | [Logs and AI context](./docs/logs-and-context.md) | Diagnose a failure with bounded, redacted evidence. |
 | [AI agent integration](./docs/agent-integration.md) | Connect an MCP-capable coding agent. |
 | [Automation](./docs/automation.md) | Use readiness, exit codes, JSON, NDJSON, JUnit, and CI artifacts. |
+| [Stability and versioning](./docs/stability.md) | Understand the 1.x API, schema, deprecation, and migration guarantees. |
 | [Gradle Managed Devices](./docs/gradle-managed-devices.md) | Run build-owned virtual-device and group tests with normalized evidence. |
 | [Firebase Test Lab](./docs/firebase-test-lab.md) | Run explicit remote instrumentation or Robo matrices with bounded evidence. |
 | [Target pools and fan-out](./docs/target-pools.md) | Bound parallel verification across an explicit target set. |

package/dist/cli.js

@@ -3304,7 +3304,7 @@ import process15 from "node:process";
 // package.json
 var package_default = {
   name: "adb-ready",
-  version: "0.8.0",
+  version: "0.9.0",
   description: "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   private: false,
   type: "module",
@@ -61628,4 +61628,4 @@ try {
   process16.removeListener("SIGTERM", abort);
 }
 
-//# debugId=2AD0AEC355B9989464756E2164756E21
+//# debugId=24EB6A0CAE0CFFFC64756E2164756E21

package/docs/automation.md

@@ -62,12 +62,17 @@ JSON commands return this top-level shape:
 Consumers must ignore unknown additive fields and event types within the same
 schema version.
 
-The npm package includes two versioned public artifacts:
+The npm package includes three versioned public artifacts:
 
 - `schema/config-v1.schema.json` validates project configuration; and
+- `schema/automation-v1.schema.json` validates the common JSON result and
+  NDJSON event envelopes; and
 - `schema/agent-tools-v1.json` catalogs every MCP tool's generated input and
   output schemas plus safety annotations for the matching package version.
 
+See [Stability and versioning](./stability.md) for the 1.x compatibility,
+deprecation, and migration policy.
+
 ## Event envelope
 
 NDJSON events include:

package/docs/stability.md

@@ -0,0 +1,68 @@
+# Stability and versioning
+
+ADB Ready follows Semantic Versioning for the npm package and versions its
+machine contracts independently. Version `1.0.0` starts the compatibility
+policy below; pre-1.0 releases remain governed by their changelog.
+
+## Stable in 1.x
+
+Within the `1.x` package line, ADB Ready will not remove or rename a documented
+CLI command, option, configuration field, exit-code category, result-envelope
+field, event-envelope field, MCP tool, or MCP resource without a new major
+version. Existing documented meanings will not be silently reassigned.
+
+Backward-compatible additions may ship in a minor release. These include new
+commands, options, event types, problem codes, optional object fields, enum
+values, MCP tools, and target capabilities. Automation must ignore unknown
+additive fields and handle unknown event or problem types conservatively.
+
+Human terminal layout, animation, color, progress wording, and diagnostic prose
+are presentation rather than an automation API. Do not parse them. Use JSON,
+NDJSON, the packaged schemas, or MCP instead.
+
+## Versioned contracts
+
+The npm package contains three contract artifacts:
+
+- `schema/config-v1.schema.json` — declarative project configuration;
+- `schema/automation-v1.schema.json` — common JSON result and NDJSON event
+  envelopes; and
+- `schema/agent-tools-v1.json` — the exact MCP tool input/output surface for
+  the installed package version.
+
+`schemaVersion` identifies an envelope or configuration shape; it is not the
+npm package version. Additive changes retain the same schema version. An
+incompatible machine-shape change requires a new schema version and a new npm
+major release. ADB Ready 1.x continues to accept configuration schema v1.
+
+The generated agent contract records `packageVersion`. Clients should load the
+artifact from the same installed package that starts the MCP server instead of
+combining contracts from different releases.
+
+## Exit behavior
+
+The category exit codes documented in [Automation](./automation.md#exit-codes)
+are stable in 1.x. A bounded `dev` or `run` child may preserve its own non-zero
+exit code, so callers must not assume every non-zero value belongs to the ADB
+Ready category table. Read the structured `problems` array for classification.
+
+## Deprecation and migration
+
+A deprecated capability remains functional throughout the current major line
+unless retaining it would create a security or data-integrity risk. ADB Ready
+will mark the replacement in CLI help, public documentation, and the changelog
+before removal. Removal or an incompatible semantic change waits for the next
+major release and receives a migration section.
+
+Security fixes, upstream Android/ADB behavior, and hosted-provider changes can
+make an operation unavailable without changing its public shape. Such cases
+must fail explicitly with structured evidence; ADB Ready does not fabricate a
+successful result to preserve compatibility.
+
+## Support claims
+
+API stability does not turn every upstream-capable environment into a tested
+environment. [Compatibility](../COMPATIBILITY.md) distinguishes CI-tested,
+hardware-observed, and upstream-capable tiers. A new host, runtime, transport,
+or Android form factor is promoted only after its stated acceptance evidence
+exists.

package/llms.txt

@@ -45,6 +45,7 @@
 - Logs and diagnostic context: `docs/logs-and-context.md`
 - Configuration: `docs/configuration.md`
 - Automation contract: `docs/automation.md`
+- Stability and versioning: `docs/stability.md`
 - Compatibility: `COMPATIBILITY.md`
 - Security: `SECURITY.md`
 - Threat model: `docs/threat-model.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-ready",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Agent-ready Android CLI for reliable ADB sessions, app automation, and verified evidence.",
   "private": false,
   "type": "module",

package/schema/agent-tools-v1.json

@@ -1,7 +1,7 @@
 {
   "title": "ADB Ready agent tool contract",
   "schemaVersion": 1,
-  "packageVersion": "0.8.0",
+  "packageVersion": "0.9.0",
   "protocolVersion": "2025-11-25",
   "transport": "stdio",
   "tools": [

package/schema/automation-v1.schema.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Adam014/adb-ready/blob/main/schema/automation-v1.schema.json",
+  "title": "ADB Ready automation envelope v1",
+  "description": "Common JSON result and NDJSON event envelopes emitted by ADB Ready.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/event" }],
+  "$defs": {
+    "jsonValue": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      ]
+    },
+    "correlation": {
+      "type": "object",
+      "required": ["commandId"],
+      "properties": {
+        "commandId": { "type": "string", "minLength": 1 },
+        "operationId": { "type": "string", "minLength": 1 },
+        "sessionId": { "type": "string", "minLength": 1 },
+        "targetId": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": true
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["source", "value"],
+      "properties": {
+        "source": { "type": "string", "minLength": 1 },
+        "field": { "type": "string", "minLength": 1 },
+        "value": { "$ref": "#/$defs/jsonValue" },
+        "redacted": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "action": {
+      "type": "object",
+      "required": ["id", "title", "kind", "risk", "automatic"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["command", "user", "documentation"] },
+        "risk": {
+          "enum": [
+            "none",
+            "read-only",
+            "local-additive",
+            "device-reversible",
+            "shared-global",
+            "destructive",
+            "open-world"
+          ]
+        },
+        "automatic": { "type": "boolean" },
+        "idempotent": { "type": "boolean" },
+        "command": {
+          "type": "object",
+          "required": ["executable", "args"],
+          "properties": {
+            "executable": { "type": "string", "minLength": 1 },
+            "args": { "type": "array", "items": { "type": "string" } }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "problem": {
+      "type": "object",
+      "required": [
+        "code",
+        "category",
+        "severity",
+        "summary",
+        "detail",
+        "retryable",
+        "evidence",
+        "actions",
+        "correlation"
+      ],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "category": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["warning", "error"] },
+        "summary": { "type": "string" },
+        "detail": { "type": "string" },
+        "retryable": { "type": "boolean" },
+        "evidence": { "type": "array", "items": { "$ref": "#/$defs/evidence" } },
+        "actions": { "type": "array", "items": { "$ref": "#/$defs/action" } },
+        "correlation": { "$ref": "#/$defs/correlation" }
+      },
+      "additionalProperties": true
+    },
+    "result": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "command",
+        "commandId",
+        "ok",
+        "startedAt",
+        "finishedAt",
+        "durationMs",
+        "data",
+        "problems"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "command": { "type": "string", "minLength": 1 },
+        "commandId": { "type": "string", "minLength": 1 },
+        "ok": { "type": "boolean" },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "finishedAt": { "type": "string", "format": "date-time" },
+        "durationMs": { "type": "number", "minimum": 0 },
+        "data": { "$ref": "#/$defs/jsonValue" },
+        "problems": { "type": "array", "items": { "$ref": "#/$defs/problem" } }
+      },
+      "additionalProperties": true
+    },
+    "event": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "sequence",
+        "timestamp",
+        "type",
+        "source",
+        "severity",
+        "message",
+        "correlation"
+      ],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "sequence": { "type": "integer", "minimum": 1 },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "type": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["debug", "info", "warning", "error"] },
+        "message": { "type": "string" },
+        "correlation": { "$ref": "#/$defs/correlation" },
+        "data": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/skills/adb-ready/SKILL.md

@@ -3,7 +3,7 @@ name: adb-ready
 description: Prepare, automate, debug, and verify one Android target through the ADB Ready MCP server. Use for Android development sessions, app lifecycle work, UI automation, failure evidence, screenshots, and agent-driven device checks.
 ---
 
-<!-- Generated by adb-ready 0.8.0; do not edit. -->
+<!-- Generated by adb-ready 0.9.0; do not edit. -->
 
 # ADB Ready
 
@@ -51,4 +51,4 @@ Use the typed `adb-ready` MCP tools. Do not replace them with generic shell or r
 - `session`: 12 tools
 - `ui`: 29 tools
 
-Contract: ADB Ready 0.8.0, agent schema v1.
+Contract: ADB Ready 0.9.0, agent schema v1.