@postman-cse/onboarding-gcp-spec-discovery 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Postman, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# Postman Onboarding: GCP Spec Discovery
+
+[![CI](https://github.com/postman-cs/postman-gcp-spec-discovery-action/actions/workflows/ci.yml/badge.svg)](https://github.com/postman-cs/postman-gcp-spec-discovery-action/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/postman-cs/postman-gcp-spec-discovery-action?sort=semver)](https://github.com/postman-cs/postman-gcp-spec-discovery-action/releases) [![npm](https://img.shields.io/npm/v/%40postman-cse%2Fonboarding-gcp-spec-discovery)](https://www.npmjs.com/package/@postman-cse/onboarding-gcp-spec-discovery) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Discover and export OpenAPI specifications from GCP services for Postman onboarding. The action uses repository context and Google Cloud credentials to select an existing specification or export one from a supported GCP provider.
+
+## Authentication
+
+Authenticate with Application Default Credentials (ADC) or Workload Identity Federation. In GitHub Actions, use [`google-github-actions/auth`](https://github.com/google-github-actions/auth) before this action. `project-id` is required; `location` defaults to `global`.
+
+```yaml
+jobs:
+  discover:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
+      - id: spec
+        uses: postman-cs/postman-gcp-spec-discovery-action@v1
+        with:
+          project-id: my-gcp-project
+      - run: echo "Resolved ${{ steps.spec.outputs.source-type }} -> ${{ steps.spec.outputs.spec-path }}"
+```
+
+## Usage
+
+### Resolve one service
+
+```yaml
+- id: spec
+  uses: postman-cs/postman-gcp-spec-discovery-action@v1
+  with:
+    project-id: my-gcp-project
+```
+
+### Discover automatically from the gateway (repository association)
+
+Label the deployed GCP resource that owns this repository's API with `postman-repo=<owner--repo>` (canonicalized slug: lowercase, `/` folded to `--`, invalid characters folded to `-`; for `github.com/acme/payments-api` the value is `acme--payments-api`). The action then resolves the right API from repository identity alone — no `api-id`, no service-name hints:
+
+```yaml
+- id: spec
+  uses: postman-cs/postman-gcp-spec-discovery-action@v1
+  with:
+    project-id: my-gcp-project
+    # repo-slug defaults to the CI-detected repository (GITHUB_REPOSITORY);
+    # set it only to resolve on behalf of a different repository.
+```
+
+Exactly one conflict-free exact label match auto-selects. Zero matches, multiple matches, or colliding label values stay `unresolved` (`manual-review`) with the expected label value printed in the evidence — the action never guesses. Colliding repositories (same canonical value, e.g. case-fold or punctuation collisions, or slugs longer than 63 characters) must set `api-id` or `expected-api-ids-json` explicitly.
+
+`postman-repo` is an owner assertion, not a verified binding: anyone with `*.update` on the resource can point it at any repository. Keep IAM label-write privileges scoped to the deployment pipeline; ambiguity still always forces `manual-review`.
+
+A ready-to-distribute per-service-repo workflow using this pattern (adapted from the Fox AWS discovery hub, but hub-less — each repo discovers its own spec) ships in [`templates/postman-gcp-onboard.yml`](templates/postman-gcp-onboard.yml). See [docs/repository-association.md](docs/repository-association.md) for marker placement per provider, ambiguity semantics, and WIF bootstrap.
+
+### Resolve a known config or Apigee proxy revision
+
+```yaml
+- uses: postman-cs/postman-gcp-spec-discovery-action@v1
+  with:
+    project-id: my-gcp-project
+    api-id: projects/my-gcp-project/locations/global/apis/payments/configs/v1
+```
+
+### Export every candidate
+
+```yaml
+- uses: postman-cs/postman-gcp-spec-discovery-action@v1
+  with:
+    project-id: my-gcp-project
+    mode: discover-many
+```
+
+### Portable CLI
+
+```sh
+npx @postman-cse/onboarding-gcp-spec-discovery \
+  --project-id "$GCP_PROJECT_ID" \
+  --result-json postman-gcp-spec-discovery-result.json \
+  --dotenv-path gcp-spec.env
+```
+
+## Inputs
+
+<!-- inputs-table:start -->
+| Name | Description | Required | Default |
+| --- | --- | --- | --- |
+| `mode` | Discovery mode: resolve-one selects the single best service for this repository; discover-many exports every exportable candidate. | no | `resolve-one` |
+| `project-id` | Google Cloud project ID used as the exact discovery and credential preflight scope. | yes | n/a |
+| `location` | Google Cloud API Gateway location. v1 supports global. | no | `global` |
+| `api-id` | Optional full API Gateway config, Cloud Endpoints config, Apigee proxy revision, API Hub spec, Apigee portal apidoc, Vertex extension, Dialogflow tool, or CES tool/toolset resource name. Use this to bypass broader project discovery. | no | n/a |
+| `repo-slug` | Repository slug (owner/name) used for repository-association matching against postman-repo resource labels. Defaults to the CI-detected repository (GITHUB_REPOSITORY). | no | n/a |
+| `expected-service-name` | Optional expected service name used as a ranking hint and as the reported service name when resolution stays manual-review. | no | n/a |
+| `expected-api-ids-json` | Optional JSON array of full resource names that this repository expects to own; exact matches rank highest during resolution. | no | `[]` |
+| `service-mapping-json` | Optional JSON object mapping resource names to service names, used to name exported specs for label-incapable providers. | no | `{}` |
+| `output-dir` | Directory under the repository root where generated specs are written. | no | `discovered-specs` |
+| `postman-api-key` | Optional service-account PMAK used to mint or re-mint a postman-access-token for telemetry enrichment (account_type). Not used for any GCP or Postman asset operation. | no | n/a |
+| `postman-access-token` | Optional Postman service-account access token, used only to enrich anonymous telemetry with the session account_type. When omitted, postman-api-key alone can mint one for the same purpose. Not used for any GCP or Postman asset operation. | no | n/a |
+<!-- inputs-table:end -->
+
+## Outputs
+
+<!-- outputs-table:start -->
+| Name | Description |
+| --- | --- |
+| `resolution-json` | JSON resolution result describing status, source type, confidence, and evidence. |
+| `resolution-status` | Resolution status: resolved or unresolved. |
+| `source-type` | Resolved source type: repo-spec, api-gateway-config, cloud-endpoints-config, apigee-proxy, apigee-env-oas, api-hub-spec, app-integration-trigger, connectors-custom-spec, connectors-generated-spec, apigee-portal-doc, vertex-extension-manifest, agent-engine-generated-spec, dialogflow-tool-schema, ces-tool-schema, ces-toolset-schema, iac-embedded, manual-review, or discover-many. |
+| `mapping-confidence` | Numeric confidence score for the selected service candidate. |
+| `spec-path` | Path to the resolved or generated specification when available. |
+| `api-id` | Full resource name of the exported cloud source (API Gateway config, Cloud Endpoints config, Apigee proxy revision, API Hub spec, Apigee portal apidoc, Vertex extension, Agent Engine, Dialogflow tool, or CES tool/toolset); empty for repo, generated, or IaC-local resolutions. |
+| `service-name` | Resolved service name. |
+| `services-json` | discover-many output: JSON array of exported services. |
+| `service-count` | discover-many output: number of exported services. |
+| `export-summary-json` | JSON summary of attempted, exported, failed, and skipped candidates. |
+| `candidates-json` | Ranked ambiguous candidates as JSON when resolution is unresolved with at least two candidates; empty otherwise. |
+| `provider-type` | Provider that produced the resolved spec: api-gateway, cloud-endpoints, apigee, api-hub, app-integration, connectors-custom, apigee-portal, vertex-extensions, agent-engines, dialogflow-tools, ces-toolsets, or iac-local. |
+| `spec-format` | Format of the resolved spec: openapi-yaml or openapi-json. |
+| `contract-origin` | Compatibility output; always empty in v1. |
+| `contract-metadata-path` | Compatibility output; always empty in v1. |
+| `variant-count` | Compatibility output; always empty in v1. |
+| `derived-openapi-path` | Path to the derived OpenAPI 3.x document when the source was not already OpenAPI 3.x. |
+| `derived-openapi-version` | OpenAPI version of the derived document: 3.0.3 or 3.1.0. |
+| `derived-openapi-completeness` | Whether the derived OpenAPI document is full or partial. |
+| `derived-openapi-format` | Serialization format of the derived OpenAPI document: openapi-json. |
+| `derived-openapi-evidence-json` | JSON array of evidence strings describing how the derived OpenAPI document was produced. |
+| `narrowing-strategy` | Narrowing tier that produced the candidate ordering: iac-fingerprint, project-correlation, label-prefilter, naming-heuristic, or none. |
+<!-- outputs-table:end -->
+
+## Supported providers
+
+| Provider | Source type | Exported format |
+| --- | --- | --- |
+| `api-gateway` | `api-gateway-config` | OpenAPI from the full API Gateway config `openapiDocuments` payload |
+| `cloud-endpoints` | `cloud-endpoints-config` | OpenAPI from Cloud Endpoints `sourceInfo` `OPEN_API_*` sources |
+| `apigee` | `apigee-proxy` | OpenAPI found in an Apigee proxy revision zip under `resources/oas` or `resources/openapi` |
+| `api-hub` | `api-hub-spec` | Verbatim OpenAPI stored in Apigee API Hub, exported via `specs:contents` (manually registered or ingested from Apigee / API Gateway plugins) |
+| `app-integration` | `app-integration-trigger` | OpenAPI 3.0 generated server-side by Application Integration `generateOpenApiSpec` for published integrations with API triggers |
+| `connectors-custom` | `connectors-custom-spec` | The OpenAPI document a custom Integration Connector was built from, fetched from its recorded `gs://` `specLocation` |
+| `apigee-portal` | `apigee-portal-doc` | Original OpenAPI documentation published through an Apigee portal API document |
+| `vertex-extensions` | `vertex-extension-manifest` | Inline or Cloud Storage OpenAPI from a Vertex AI extension manifest |
+| `agent-engines` | `agent-engine-generated-spec` | OpenAPI assembled from Vertex AI Agent Engine classMethods declarations |
+| `dialogflow-tools` | `dialogflow-tool-schema` | Original OpenAPI text schema stored on a Dialogflow CX tool |
+| `ces-toolsets` | `ces-toolset-schema` | Original OpenAPI schema stored on a Conversational Agents app toolset |
+| `iac-local` | `iac-embedded` / path reference | OpenAPI referenced by local Terraform `google_api_gateway_api_config` or `google_endpoints_service` resources |
+
+The resolver probes providers in this order: `api-gateway`, `cloud-endpoints`, `apigee`, `api-hub`, `app-integration`, `connectors-custom`, `apigee-portal`, `vertex-extensions`, `agent-engines`, `dialogflow-tools`, `ces-toolsets`, `iac-local`. A committed `repo-spec` wins before remote discovery. Candidates are narrowed by `iac-fingerprint`, `project-correlation`, `label-prefilter`, then `naming-heuristic`; the `postman-repo` label is an ownership signal. Ambiguous or unsupported results are reported for **manual review** rather than guessed.
+
+## v1 boundaries
+
+v1 does not probe `Cloud Run`, `GKE`, or `Functions` runtime URLs (there is no GCP catalog of runtime specs), does not fetch arbitrary remote URLs, does not synthesize routes from traffic observations (APIM shadow-API discovery yields operations, not contracts), and does not convert gRPC or `google.api.Service` definitions to OpenAPI. Non-OpenAPI `API Hub` spec types (proto, WSDL, MCP) surface as manual review candidates rather than being converted.
+
+## How it works
+
+1. Validate `project-id` and Google credentials.
+2. Prefer a committed repository specification.
+3. Probe supported providers fail-soft and collect candidates.
+4. Narrow and rank candidates using repository and project signals.
+5. Export and validate the selected OpenAPI document inside `output-dir`.
+6. Emit resolution, export, candidate, and narrowing outputs.
+
+## Resources
+
+- [Provider contracts](docs/providers.md)
+- [Repository association](docs/repository-association.md)
+- [Per-service-repo onboarding workflow template](templates/postman-gcp-onboard.yml)
+- [Live testing runbook](docs/LIVE_TESTING_RUNBOOK.md)
+- [RELEASE_POLICY.md](RELEASE_POLICY.md), [SECURITY.md](SECURITY.md), [SUPPORT.md](SUPPORT.md)
+
+## Telemetry
+
+The action emits one anonymous `completion` event per run (action name `gcp-spec-discovery`) through `@postman-cse/automation-telemetry-core`. The payload excludes project identifiers, resource names, labels, specification content, URLs, and credentials. Opt out with `POSTMAN_ACTIONS_TELEMETRY=off` or `DO_NOT_TRACK=1`.
+
+## License
+
+[MIT](LICENSE)

package/RELEASE_POLICY.md

@@ -0,0 +1,43 @@
+# Release Policy
+
+## Source of truth
+
+Git tags and GitHub releases are the public release identifiers for this action. `package.json` versions support npm packaging, but consumers should select action versions by Git tag. The committed `dist/` bundle is part of the released artifact because GitHub Actions runs it verbatim from the tag.
+
+## Tag policy
+
+- Immutable releases use `vMAJOR.MINOR.PATCH` tags.
+- The rolling major and minor aliases (`vMAJOR` and `vMAJOR.MINOR`, i.e. `v1` and `v1.0`) are force-moved by the release workflow's `advance-rolling-aliases` job after a successful immutable publish.
+- Existing immutable release tags are never force-pushed or rewritten.
+- Every release tag commit must equal protected `origin/main`; the release workflow verifies this before publication.
+- `v0` tags stay frozen at the last `v0` release.
+- Every immutable release tag has a GitHub release with generated notes.
+
+## Release checks
+
+Run the package validators from this directory before pushing an immutable tag:
+
+1. Confirm the working tree is clean.
+2. `npm test`
+3. `npm run typecheck`
+4. `npm run lint`
+5. `npm run build`
+6. `npm run verify:dist`
+7. `npm run docs:tables` when `action.yml` changes, then confirm the `README.md` tables still match.
+8. Confirm `SECURITY.md`, `SUPPORT.md`, and this file still describe the release surface.
+
+## npm package
+
+The CLI publishes as `@postman-cse/onboarding-gcp-spec-discovery` with versions that match the GitHub release tag. Rolling major/minor aliases update action channels and skip npm publishing.
+
+## Compatibility
+
+This action emits `spec-path`, `service-name`, and resolution metadata for downstream actions. Changes to output names, output types, required inputs, or resolution semantics are breaking changes and require a new major release.
+
+## Security fixes
+
+Security fixes ship on the latest immutable `vMAJOR.MINOR.PATCH` tag and move onto the rolling major/minor aliases. Older immutable tags stay published for reproducibility. See [Security Policy](SECURITY.md).
+
+## Suite release order
+
+GCP discovery can be released on its own unless a downstream onboarding example depends on a new composite or bootstrap feature. When multiple onboarding actions change together, release the lower-level actions first, then update the composite action after its pinned dependencies are available.

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest `v1.x.y` release (tracked by rolling major and minor aliases such as `v1` and `v1.0`) receives security fixes. Older tags remain published for reproducibility and are never retroactively modified.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for security reports.
+
+- Preferred: use GitHub private vulnerability reporting on this repository (Security tab, "Report a vulnerability").
+- Alternative: email [security@postman.com](mailto:security@postman.com) and mention the repository name.
+
+You should receive an acknowledgement within five business days. Please include reproduction steps, the action version tag, and any relevant (redacted) workflow logs.
+
+## Scope Notes
+
+- This action reads GCP credentials from the runner environment and calls read-only GCP ARM APIs. Prefer GitHub OIDC federation via `gcp/login` with `id-token: write` and least-privilege Reader roles needed for the providers you use.
+- This action does not require a Postman API key or Postman access token. Postman credentials are consumed by downstream onboarding actions after `spec-path` is resolved.
+- Use `postman-resolve-service-token-action` as the primary way to mint a Postman access token and resolve the team ID from a service-account PMAK.
+- When service-account minting is unavailable, use the Postman CLI credential store created by `postman login` as the fallback source. Do not paste copied cookies, DevTools values, or manually harvested session credentials into workflow secrets.
+- Downstream `credential-preflight` supports `warn` and `enforce` only. Do not document or depend on a public opt-out.
+- Reports about secrets you exposed in your own workflow configuration are out of scope; rotate the credential in GCP or Postman immediately.
+
+## Credential Matrix
+
+| Credential | Used by | Recommended source | Notes |
+| --- | --- | --- | --- |
+| GCP credentials | `gcp/login` and this action | GitHub OIDC federated credentials | Grant least-privilege Reader roles for discovery. |
+| `POSTMAN_SERVICE_ACCOUNT_API_KEY` | `postman-resolve-service-token-action` and downstream onboarding actions | GitHub secret | Must be a Postman service-account PMAK when minting an access token. |
+| Postman access token | Downstream onboarding actions | `postman-resolve-service-token-action` output | Pass through `steps.postman_token.outputs.token`; do not store unless your workflow requires it. |
+| Postman team ID | Composite onboarding action | `postman-resolve-service-token-action` output | Pass through `steps.postman_token.outputs.team-id` to the composite action for org-mode handoff. Direct bootstrap workflows should use `workspace-team-id` for workspace creation. |

package/SUPPORT.md

@@ -0,0 +1,30 @@
+# Support
+
+## Before opening an issue
+
+Check the action logs for the selected provider, `resolution-status`, `source-type`, and `mapping-confidence`. The action is read-only against GCP and silently skips providers your role cannot read, so most discovery failures are caused by subscription mismatch, missing RBAC read permissions, missing repo-local specs, or ambiguous service names.
+
+## What to include
+
+- The action version or tag you ran.
+- The `subscription-id` value and provider you expected to resolve.
+- The relevant sanitized workflow step log.
+- The `resolution-json` output with secrets, subscription IDs, and private hostnames redacted.
+- Whether the workflow used gcp/login OIDC federation or preconfigured GCP credentials.
+- Whether the result was handed to `postman-api-onboarding-action` or `postman-bootstrap-action`.
+
+Do not include GCP secrets, Postman API keys, Postman access tokens, private OpenAPI documents, or unredacted account identifiers in public issues.
+
+## Common support paths
+
+| Symptom | First check |
+| --- | --- |
+| `GCP credentials are missing or invalid` | Confirm `gcp/login` ran first and the federated credential covers this repository and environment. |
+| Provider was skipped | Add the provider's read-only IAM permissions from [docs/providers.md](docs/providers.md#security-and-iam). |
+| `manual-review` result | Provide a repo-local spec, an exact APIM `api-id`, a canonical `postman:repo` tag, or a stronger service-name hint. |
+| Downstream Postman onboarding failed | Check the service-token step outputs and downstream `credential-preflight` setting. Valid values are `warn` and `enforce`. |
+| APIM or App Service API was not selected | Confirm the resource group, API type, current APIM revision, and `siteConfig.apiDefinition.url`; then review [docs/providers.md](docs/providers.md). |
+
+## Security reports
+
+Use [SECURITY.md](SECURITY.md) for vulnerability reports or credential exposure concerns. Do not open a public issue for security-sensitive material.

package/action.yml

@@ -0,0 +1,98 @@
+name: 'Postman Onboarding: GCP Spec Discovery'
+description: Discover GCP-hosted API specs and expose a spec path for Postman onboarding. Part of the Postman API Onboarding suite.
+author: Postman
+branding:
+  icon: cloud
+  color: orange
+inputs:
+  mode:
+    description: 'Discovery mode: resolve-one selects the single best service for this repository; discover-many exports every exportable candidate.'
+    required: false
+    default: resolve-one
+  project-id:
+    description: Google Cloud project ID used as the exact discovery and credential preflight scope.
+    required: true
+  location:
+    description: Google Cloud API Gateway location. v1 supports global.
+    required: false
+    default: global
+  api-id:
+    description: Optional full API Gateway config, Cloud Endpoints config, Apigee proxy revision, API Hub spec, Apigee portal apidoc, Vertex extension, Dialogflow tool, or CES tool/toolset resource name. Use this to bypass broader project discovery.
+    required: false
+    default: ''
+  repo-slug:
+    description: Repository slug (owner/name) used for repository-association matching against postman-repo resource labels. Defaults to the CI-detected repository (GITHUB_REPOSITORY).
+    required: false
+    default: ''
+  expected-service-name:
+    description: Optional expected service name used as a ranking hint and as the reported service name when resolution stays manual-review.
+    required: false
+    default: ''
+  expected-api-ids-json:
+    description: Optional JSON array of full resource names that this repository expects to own; exact matches rank highest during resolution.
+    required: false
+    default: '[]'
+  service-mapping-json:
+    description: Optional JSON object mapping resource names to service names, used to name exported specs for label-incapable providers.
+    required: false
+    default: '{}'
+  output-dir:
+    description: Directory under the repository root where generated specs are written.
+    required: false
+    default: discovered-specs
+  postman-api-key:
+    description: Optional service-account PMAK used to mint or re-mint a postman-access-token for telemetry enrichment (account_type). Not used for any GCP or Postman asset operation.
+    required: false
+    default: ''
+  postman-access-token:
+    description: Optional Postman service-account access token, used only to enrich anonymous telemetry with the session account_type. When omitted, postman-api-key alone can mint one for the same purpose. Not used for any GCP or Postman asset operation.
+    required: false
+    default: ''
+outputs:
+  resolution-json:
+    description: JSON resolution result describing status, source type, confidence, and evidence.
+  resolution-status:
+    description: 'Resolution status: resolved or unresolved.'
+  source-type:
+    description: 'Resolved source type: repo-spec, api-gateway-config, cloud-endpoints-config, apigee-proxy, apigee-env-oas, api-hub-spec, app-integration-trigger, connectors-custom-spec, connectors-generated-spec, apigee-portal-doc, vertex-extension-manifest, agent-engine-generated-spec, dialogflow-tool-schema, ces-tool-schema, ces-toolset-schema, iac-embedded, manual-review, or discover-many.'
+  mapping-confidence:
+    description: Numeric confidence score for the selected service candidate.
+  spec-path:
+    description: Path to the resolved or generated specification when available.
+  api-id:
+    description: Full resource name of the exported cloud source (API Gateway config, Cloud Endpoints config, Apigee proxy revision, API Hub spec, Apigee portal apidoc, Vertex extension, Agent Engine, Dialogflow tool, or CES tool/toolset); empty for repo, generated, or IaC-local resolutions.
+  service-name:
+    description: Resolved service name.
+  services-json:
+    description: 'discover-many output: JSON array of exported services.'
+  service-count:
+    description: 'discover-many output: number of exported services.'
+  export-summary-json:
+    description: JSON summary of attempted, exported, failed, and skipped candidates.
+  candidates-json:
+    description: Ranked ambiguous candidates as JSON when resolution is unresolved with at least two candidates; empty otherwise.
+  provider-type:
+    description: 'Provider that produced the resolved spec: api-gateway, cloud-endpoints, apigee, api-hub, app-integration, connectors-custom, apigee-portal, vertex-extensions, agent-engines, dialogflow-tools, ces-toolsets, or iac-local.'
+  spec-format:
+    description: 'Format of the resolved spec: openapi-yaml or openapi-json.'
+  contract-origin:
+    description: Compatibility output; always empty in v1.
+  contract-metadata-path:
+    description: Compatibility output; always empty in v1.
+  variant-count:
+    description: Compatibility output; always empty in v1.
+  derived-openapi-path:
+    description: Path to the derived OpenAPI 3.x document when the source was not already OpenAPI 3.x.
+  derived-openapi-version:
+    description: 'OpenAPI version of the derived document: 3.0.3 or 3.1.0.'
+  derived-openapi-completeness:
+    description: Whether the derived OpenAPI document is full or partial.
+  derived-openapi-format:
+    description: 'Serialization format of the derived OpenAPI document: openapi-json.'
+  derived-openapi-evidence-json:
+    description: JSON array of evidence strings describing how the derived OpenAPI document was produced.
+  narrowing-strategy:
+    description: 'Narrowing tier that produced the candidate ordering: iac-fingerprint, project-correlation, label-prefilter, naming-heuristic, or none.'
+runs:
+  using: node24
+  main: dist/index.cjs