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

package/docs/LIVE_TESTING_RUNBOOK.md

@@ -0,0 +1,41 @@
+# Live GCP validation runbook
+
+Live validation provisions disposable GCP resources, runs the compiled CLI, captures sanitized evidence, and tears down only resources created by the current run. It is operator-triggered and is not part of pull-request CI.
+
+## Prerequisites
+
+- Access to project `dans-project-491920` with permission to create and delete the run-scoped validation resources.
+- ADC credentials from `gcloud auth application-default login`, or equivalent workload identity credentials.
+- A fresh bundle: `npm run build`.
+
+Set the project explicitly:
+
+```sh
+export GCP_PROJECT_ID=dans-project-491920
+node validation/scripts/validate-live-gcp-surfaces.mjs --provision --teardown
+```
+
+## Validation cases
+
+The runner provisions run-marked API Gateway, Cloud Endpoints, and Apigee proxy resources (including a `postman-repo`-labeled config plus two configs sharing a conflict label), then executes these ten cases:
+
+1. `gateway-explicit-api-id`
+2. `gateway-discovery`
+3. `gateway-repo-label` — resolves from the `postman-repo` label and repository identity alone
+4. `gateway-label-conflict` — two configs sharing one `postman-repo` value must stay unresolved
+5. `endpoints-explicit-api-id`
+6. `endpoints-discovery`
+7. `apigee-discovery`
+8. `discover-many`
+9. `iac-single`
+10. `ambiguity`
+
+It writes sanitized evidence only: case name, status, source type, provider type, and specification format. Do not commit resource IDs, hostnames, URLs, credentials, manifests, proxy archives, or specification bodies.
+
+## Safety rules
+
+- `--provision` is required before the script creates resources.
+- `--teardown` removes only resources carrying the exact current-run marker.
+- The runner never deletes shared Apigee organization, environment, environment group, or instance resources.
+- Do not use a production project or broaden cleanup beyond the current run.
+- Use ADC or workload identity; do not record credential material in evidence.

package/docs/PRD.md

@@ -0,0 +1,223 @@
+# GCP Spec Discovery Action v1.0.0 PRD
+
+Status: implementation-ready  
+Authoritative plan: `.plans/gcp-spec-discovery-v1-plan.md`  
+Repository: `postman-cs/postman-gcp-spec-discovery-action`  
+Local path: `cse/postman-gcp-spec-discovery-action/`  
+Release: `v1.0.0`; npm `@postman-cse/onboarding-gcp-spec-discovery@1.0.0`
+
+## Product Contract
+
+The action discovers or derives an OpenAPI 3.x or Swagger 2.0 document from one explicitly named Google Cloud project. Resolution order is explicit `api-id` override, then direct repo spec, one local-IaC referenced spec, then cloud candidates. Ambiguity or unsupported source shape returns `unresolved/manual-review` with sanitized evidence and writes no guessed artifact.
+
+### Inputs
+
+`action.yml` and `src/contracts.ts` MUST declare these keys in order:
+
+| Input | Required | Default | Meaning |
+| --- | --- | --- | --- |
+| `mode` | false | `resolve-one` | `resolve-one` or `discover-many`. |
+| `project-id` | true | none | Exact Google Cloud project ID; never inferred from ambient ADC. |
+| `location` | false | `global` | API Gateway location; v1 accepts only `global`. |
+| `api-id` | false | `''` | Exact full resource name of any explicitly selectable source: API Gateway config, Cloud Endpoints config, Apigee proxy revision, API Hub spec, Apigee portal apidoc, Vertex extension, Dialogflow tool, or CES tool/toolset. |
+| `repo-slug` | false | `''` | Repository slug (owner/name) for repository-association matching against `postman-repo` labels; defaults to the CI-detected repository. |
+| `expected-service-name` | false | `''` | Ranking hint; also names manual-review results. |
+| `expected-api-ids-json` | false | `[]` | JSON array of expected full resource names; exact matches rank highest. |
+| `service-mapping-json` | false | `{}` | JSON object mapping resource names to service names. |
+| `output-dir` | false | `discovered-specs` | Confined repository-relative write root. |
+| `postman-api-key` | false | `''` | Optional telemetry enrichment only. |
+| `postman-access-token` | false | `''` | Optional telemetry enrichment only. |
+
+CLI-only controls mirror Azure: repository context, filter regex, candidate cap, dry-run, preflight controls, request timeout, attempts, result JSON, dotenv path, help, and version. Defaults are `max-candidates=50`, `request-timeout-ms=30000`, `max-attempts=3`, `preflight-checks=true`, and `preflight-permission-probe=true`.
+
+### Outputs
+
+The action MUST set all 22 outputs in this order on every successful invocation:
+
+1. `resolution-json`
+2. `resolution-status`
+3. `source-type`
+4. `mapping-confidence`
+5. `spec-path`
+6. `api-id`
+7. `service-name`
+8. `services-json`
+9. `service-count`
+10. `export-summary-json`
+11. `candidates-json`
+12. `provider-type`
+13. `spec-format`
+14. `contract-origin`
+15. `contract-metadata-path`
+16. `variant-count`
+17. `derived-openapi-path`
+18. `derived-openapi-version`
+19. `derived-openapi-completeness`
+20. `derived-openapi-format`
+21. `derived-openapi-evidence-json`
+22. `narrowing-strategy`
+
+Provider types are `api-gateway | cloud-endpoints | apigee | api-hub | app-integration | connectors-custom | apigee-portal | vertex-extensions | agent-engines | dialogflow-tools | ces-toolsets | iac-local`. Source types are `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 | discover-many`. Spec formats are `openapi-json | openapi-yaml`. Compatibility outputs 14-16 are empty in v1. Dotenv names use `POSTMAN_GCP_SPEC_*`.
+
+## Requirements
+
+### R1 - Scaffold, contract, input resolution, and confinement (P0)
+
+- Create an independent Node 24 strict-TypeScript package with ESM source and single-file CommonJS `dist/index.cjs` plus executable `dist/cli.cjs`.
+- Require `project-id`; validate it against `^[a-z][a-z0-9-]{4,28}[a-z0-9]$`. Reject any `location` other than `global` in v1.
+- Confine output/result/dotenv paths beneath `repo-root` lexically and by realpath; reject symlink/path traversal before writing.
+- Keep Action/CLI adapters thin and byte-equivalent at the output surface.
+
+Acceptance:
+
+- **GCP-CONTRACT-001:** manifest and contract inputs/outputs exactly match the ordered lists.
+- **GCP-CONTRACT-002:** defaults and invalid mode/project/location produce exact actionable errors.
+- **GCP-CONTRACT-003:** `../escape` and out-of-root symlink outputs fail with no outside write through runtime and CLI.
+- **GCP-CONTRACT-004:** resolved/unresolved and both modes serialize all 22 outputs with documented empty values.
+- **GCP-CONTRACT-005:** package name/version/Node engine/files and exact dependency pins match the release contract.
+
+### R2 - ADC transport, preflight, retry, pagination, and sanitization (P0)
+
+- Construct exactly one `GoogleAuth({ scopes: ['https://www.googleapis.com/auth/cloud-platform'] })` in production and reuse its authenticated fetch transport.
+- Preflight calls Cloud Resource Manager `projects.get` for the explicit project before provider enumeration. Credential/project failure is fatal; provider 401/403/service-disabled failures are fail-soft typed probes.
+- Every request uses `request-timeout-ms`, at most `max-attempts`, retries only 408/429/5xx, and never retries validation/400/401/403/404 responses.
+- Consume `nextPageToken` until empty; reject a repeated token. URL path segments use `encodeURIComponent`; query strings are constructed with `URLSearchParams`.
+- Sanitize access tokens, credential JSON, project numbers, service-account emails, full resource names, and URL queries from errors/evidence.
+
+Acceptance:
+
+- **GCP-CLIENT-001:** one shared auth object, successful preflight, and fatal preflight failure before providers.
+- **GCP-CLIENT-002:** retry attempt bounds and nonretryable behavior are exact under fake transport.
+- **GCP-CLIENT-003:** two-page lists combine in order; repeated token fails after the second page.
+- **GCP-CLIENT-004:** mixed provider 403/error/success yields ordered `skipped:iam`, `skipped:error`, `available` and continues.
+- **GCP-CLIENT-005:** raw secret/project-number/email/resource/query fixtures are absent after sanitization.
+
+### R3 - API Gateway original-source provider (P0)
+
+- List `projects/{project}/locations/global/apis` and each API's configs with pagination.
+- Retain configs in `ACTIVE`; keep unsupported gRPC-only/non-active configs as `supported=false` evidence rather than silently selecting them.
+- Exact `api-id` must match `projects/{inputProject}/locations/global/apis/{api}/configs/{config}` and is fetched directly; cross-project or non-config names fail before network export.
+- Export with `GET https://apigateway.googleapis.com/v1/{name}?view=FULL`. Decode `openapiDocuments[].document.contents` from base64, enforce at most 10 MiB decoded, validate version and non-empty `paths`, and preserve source JSON/YAML with one trailing newline.
+- Exactly one valid OpenAPI document is exportable. Zero or multiple OpenAPI documents are unsupported/manual review; gRPC/service-config files are never converted.
+
+Acceptance:
+
+- **GCP-GATEWAY-001:** paged APIs/configs yield stable candidates and state/support classifications.
+- **GCP-GATEWAY-002:** FULL export decodes valid JSON and YAML original bytes with correct filename/format.
+- **GCP-GATEWAY-003:** malformed base64, oversize, invalid/empty spec, zero/multiple docs, and gRPC-only configs write nothing and report precise sanitized evidence.
+- **GCP-GATEWAY-004:** explicit cross-project/malformed IDs are rejected; an exact valid ID bypasses list calls and resolves at confidence 100.
+
+### R4 - Cloud Endpoints original-source provider (P0)
+
+- List only managed services with exact `producerProjectId=<inputProject>`, with pagination.
+- List each service's configs newest-first. v1 candidate set contains the newest config per service; exact IDs can target an older config.
+- Export `services/{serviceName}/configs/{configId}?view=FULL` and inspect only `sourceInfo.sourceFiles` whose `fileType` is `OPEN_API_JSON` or `OPEN_API_YAML`.
+- Decode base64, cap 10 MiB, validate, and preserve one source document. Zero/multiple valid source files are unsupported/manual review. Service Config normalization is never converted back into guessed OpenAPI.
+
+Acceptance:
+
+- **GCP-ENDPOINTS-001:** producer filtering, config pagination, newest-per-service selection, and stable IDs are exact.
+- **GCP-ENDPOINTS-002:** FULL sourceInfo JSON/YAML exports preserve valid bytes and format.
+- **GCP-ENDPOINTS-003:** normalized config without sourceInfo, zero/multiple OpenAPI files, malformed/oversize/invalid bytes, and foreign producer project write nothing.
+- **GCP-ENDPOINTS-004:** exact older config ID resolves directly while automatic discovery uses newest only.
+
+### R5 - Repository and GCP IaC discovery (P0)
+
+- Direct repository OpenAPI/Swagger files retain highest precedence after any explicit `api-id` override.
+- Scan at most depth 6 and 200 `.tf`, `.json`, `.yaml`, `.yml` files in lexical order, excluding `.git`, `node_modules`, `dist`, and `output-dir`; do not execute Terraform, gcloud, hooks, or source code.
+- Terraform recognizes only literal `google_api_gateway_api_config` OpenAPI document `path` references and `google_endpoints_service` literal OpenAPI file/content references. Resolve files beneath repo root only.
+- One valid referenced document resolves `iac-embedded`; multiple remain `manual-review`; no match falls through. Extract resource/API/service names only as narrowing fingerprints.
+
+Acceptance:
+
+- **GCP-IAC-001:** exact Terraform fixtures yield the referenced valid docs and fingerprints without process/network calls.
+- **GCP-IAC-002:** one document resolves, two are ambiguous with no write, zero falls through.
+- **GCP-IAC-003:** traversal, symlink escape, depth/file caps, ignored directories, and lexical repeatability are enforced.
+- **GCP-IAC-004:** interpolation, remote URLs, data sources, provisioners, and nonliteral expressions are evidence-only or ignored and never executed/fetched.
+
+### R5b - API Hub, Application Integration, and Integration Connectors providers (P0)
+
+- `api-hub`: walk provisioned hub locations, then `apis -> versions -> specs`; export verbatim bytes via `specs/{spec}:contents`; record the full spec resource name in `api-id` and accept it as an explicit `api-id` input. Non-OpenAPI spec types (proto, WSDL, MCP) stay unsupported/manual-review. Product-specific IAM (`roles/apihub.viewer`) or an unprovisioned hub probes `skipped:iam` fail-soft.
+- `app-integration`: list regional integrations whose ACTIVE version has an `api_trigger/`; generate OpenAPI 3.0 server-side with `locations/{location}:generateOpenApiSpec`; evidence marks the contract as generated, never an uploaded source file.
+- `connectors-custom`: list global custom connectors and versions; fetch only `gs://` `specLocation` objects through the authenticated Cloud Storage JSON API; `https://` locations stay manual-review because the action never fetches arbitrary remote URLs.
+
+Acceptance:
+
+- **GCP-APIHUB-001..005:** strict spec-name parsing, fail-soft probes, verbatim OpenAPI export, unsupported non-OpenAPI types, and project-scoped explicit `api-id` are pinned by tests.
+- **GCP-APPINT-001..003:** fail-soft probes, trigger-scoped listing plus generated-contract export evidence, and non-integration `api-id` yielding no candidates are pinned by tests.
+- **GCP-CONNECTORS-001..004:** strict `gs://` parsing, fail-soft probes, authenticated storage fetch, and https manual-review with no fetch are pinned by tests.
+
+### R5c - Apigee Portal, Vertex AI Extensions, and Dialogflow CX Tools providers (P0)
+
+- `apigee-portal`: list integrated-portal sites and their `apidocs`; fetch each documentation snapshot via `getDocumentation` and decode the stored OpenAPI contents. Candidates carry `api-id` `organizations/{org}/sites/{site}/apidocs/{document}` and source type `apigee-portal-doc`. Missing portal provisioning or product IAM probes `skipped:iam` fail-soft.
+- `vertex-extensions`: list Vertex AI Extensions in the project region; export each extension's stored `apiSpec` manifest (inline YAML or `gs://` object fetched through the authenticated Cloud Storage JSON API) as source type `vertex-extension-manifest`.
+- `dialogflow-tools`: walk Dialogflow CX agents and their OpenAPI-typed tools; export each tool's stored `openApiSpec.textSchema` verbatim as source type `dialogflow-tool-schema`. Non-OpenAPI tool types stay unsupported/manual-review.
+
+Acceptance:
+
+- **GCP-PORTAL-001..003:** fail-soft probes, apidoc listing plus documentation export, and non-OpenAPI documentation manual-review are pinned by tests.
+- **GCP-VERTEX-001..003:** fail-soft probes, inline and `gs://` manifest export, and strict location parsing are pinned by tests.
+- **GCP-DIALOGFLOW-001..003:** fail-soft probes, OpenAPI tool export, and non-OpenAPI tool types unsupported are pinned by tests.
+
+### R6 - Resolution, narrowing, modes, UX, and telemetry (P0)
+
+- Provider order is API Gateway, Cloud Endpoints, Apigee, API Hub, Application Integration, Integration Connectors, Apigee Portal, Vertex AI Extensions, Vertex AI Agent Engines, Dialogflow CX Tools, CES Toolsets, IaC local after direct repo-spec precedence.
+- Narrowing order is `iac-fingerprint`, `project-correlation`, `label-prefilter`, `naming-heuristic`. It partitions without deleting; cap applies after partition. Only explicit ID or one exact label key `postman-repo` with the canonical repo-label value selects. Canonicalization lowercases the full owner/repo slug, replaces `/` with `--`, replaces every other run outside `[a-z0-9_-]` with `-`, trims leading/trailing separators, and declines label selection when the result is empty or exceeds 63 characters.
+- Equal top confidence, multiple local docs, unsupported selected candidates, or no candidate resolve to sanitized manual review, never arbitrary first-item selection.
+- `discover-many` exports every supported candidate in stable order and records attempted/exported/failed/skipped accurately.
+- Ambiguity populates deterministic `candidates-json` and a `## Postman GCP spec discovery` Step Summary. Summary failure is warn-only.
+- Emit at most one best-effort telemetry completion event with `action: 'gcp-spec-discovery'`; no GCP identifiers/specs/URLs/tags enter telemetry.
+
+Acceptance:
+
+- **GCP-NARROW-001:** tier order, zero-intersection fallthrough, partition-never-delete, exact-label-only select, and cap-after-partition are proven.
+- **GCP-RESOLVE-001:** repo spec/local IaC/cloud precedence, ties, unsupported candidates, explicit IDs, and both modes match contracts.
+- **GCP-SUMMARY-001:** golden summary/candidates are stable and contain no project number, service-account email, full resource name, token, or URL query.
+- **GCP-ENTRY-001:** Action and CLI call one runtime and return all 22 byte-equal outputs.
+- **GCP-TELEMETRY-001:** success/failure/transport-failure/opt-out emit at most one safe event without changing runtime status.
+
+### R7 - Documentation, CI, live validation, and release (P0)
+
+- README tables are generated from the contract; docs state exact providers, ADC/WIF setup, IAM permissions, and deferred surfaces without overclaiming.
+- CI is one Node 24 `gate` job with one `npm ci`, one bundle, max two concurrent local checks, read-only dist assertion, and no credentialed live step on pull requests.
+- Live runner uses explicit `GCP_PROJECT_ID=dans-project-491920`, requires `--provision --teardown`, provisions collision-resistant run-marked API Gateway API/config, Cloud Endpoints service/config, and Apigee proxy resources, validates the current compiled CLI, and tears down exact run-scoped identities in `finally`. Apigee teardown verifies remote ownership before deletion and refuses foreign resources.
+- Live cases are exactly `gateway-explicit-api-id`, `gateway-discovery`, `gateway-repo-label`, `gateway-label-conflict`, `endpoints-explicit-api-id`, `endpoints-discovery`, `apigee-discovery`, `discover-many`, `iac-single`, and `ambiguity`. Evidence stores only case name/status/source/provider/format and totals.
+- Release accepts only immutable `v1.0.0` at `origin/main`, runs all gates, publishes npm with provenance, creates GitHub release, then moves only `v1` and `v1.0`. Rolling tags never publish npm.
+
+Acceptance:
+
+- **GCP-DOCS-001:** generated tables have no drift and docs name exactly the v1 providers/non-goals.
+- **GCP-CI-001:** workflow contract test and actionlint pass.
+- **GCP-LIVE-001:** all current-build live cases pass in Dan's project; teardown leaves no current-run active API Gateway/Endpoints resource.
+- **GCP-LIVE-002:** failure/marker mismatch tests prove `finally` cleanup and deletion refusal for foreign resources.
+- **GCP-LIVE-003:** committed evidence totals match and contains no forbidden identifiers/URLs/secrets/spec bodies.
+- **GCP-RELEASE-001:** release workflow tests prove tag/package/main equality, npm idempotence, GitHub release, and dual rolling aliases.
+- **GCP-RELEASE-002:** after publication, npm version, GitHub release, immutable/rolling tag peel, and npm/tag `dist` bytes all verify independently.
+
+## Must Pass
+
+From `cse/postman-gcp-spec-discovery-action/` on the release candidate:
+
+```sh
+npm test
+npm run typecheck
+npm run lint
+npm run build
+npm run verify:dist
+npm run docs:tables
+git diff --exit-code -- README.md
+actionlint .github/workflows/*.yml
+node validation/scripts/validate-live-gcp-surfaces.mjs --provision --teardown
+```
+
+Then judge-sol and judge-fable MUST both return COMPLETE. Release verification MUST prove `v1.0.0 == v1 == v1.0 == origin/main`, npm reports `1.0.0`, the GitHub release exists, and both npm bundle files byte-match the immutable tag.
+
+## Must Not
+
+- No service-account key or credential JSON input, durable secret, token logging, ambient project inference, or personal project validation.
+- API Hub, Application Integration, and Integration Connectors custom connectors are IN scope as fail-soft providers (`api-hub`, `app-integration`, `connectors-custom`). No Cloud Run/Functions runtime probing, arbitrary remote URL fetch, traffic-derived route synthesis (APIM shadow-API observation), legacy Apigee Registry, gRPC/`google.api.Service` conversion, Terraform/gcloud execution, or cross-action TypeScript import in v1. Apigee is explicitly IN SCOPE and release-blocking: the Dan's-project org and its billing org must be fully working (management plane, data plane, spec surfaces) before v1 ships, at any cost.
+- No arbitrary ambiguity selection, destructive narrowing, cap-before-partition, path escape, stale-dist proof, credentialed PR job, rolling-tag npm publish, immutable-tag movement, or release from a commit other than protected `origin/main`.
+
+## Completion Audit
+
+Completion requires a prompt-to-artifact checklist mapping every requirement/AC above to current files, test output, live evidence, judge receipts, commit/CI state, and published artifacts. Missing or indirect evidence remains incomplete.

package/docs/providers.md

@@ -0,0 +1,117 @@
+# Provider contracts
+
+GCP spec discovery probes providers fail-soft 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`. Authorization failures become `skipped:iam`; other provider failures become `skipped:error`; remaining providers continue.
+
+## Repository-association capability
+
+Automatic per-repo selection matches the canonical `postman-repo` label against candidate tags. Providers differ in whether the underlying GCP resource can carry labels at all:
+
+| Capability | Providers | Mechanism |
+| --- | --- | --- |
+| Label-capable (auto-select works) | `api-gateway`, `apigee`, `api-hub`, `connectors-custom` | Resource labels flow into candidate tags (`postman-repo=<owner--repo>` on the API/config, proxy, hub attribute, or connector version) |
+| Label-capable via IaC | `iac-local` | Repository-committed IaC fingerprinting selects without cloud labels |
+| Label-incapable (never auto-selects by label) | `cloud-endpoints`, `app-integration`, `apigee-portal`, `vertex-extensions`, `agent-engines`, `dialogflow-tools`, `ces-toolsets` | The GCP surface exposes no usable label; select with `api-id`, `expected-api-ids-json`, or `service-mapping-json` + `expected-service-name` |
+
+Label-incapable providers still participate in discovery and ranking; they simply cannot be *authorized* for export by repository association alone. See [repository-association.md](repository-association.md).
+
+## `api-gateway`
+
+- Lists API Gateway APIs and configs in the requested project and `global` location.
+- Exports the complete `openapiDocuments` content from the selected config.
+- Produces `api-gateway-config` candidates and records the full config resource name in `api-id`.
+
+## `cloud-endpoints`
+
+- Lists Cloud Endpoints services and available configs in the requested project.
+- Reads `sourceInfo` entries with `OPEN_API_*` source types to recover the OpenAPI source.
+- Produces `cloud-endpoints-config` candidates and records the config resource name in `api-id`.
+
+## `apigee`
+
+- Lists accessible Apigee proxies and revisions for the requested project context.
+- Downloads the selected proxy revision zip and extracts OpenAPI documents only from `resources/oas` or `resources/openapi`.
+- Produces `apigee-proxy` candidates and records the proxy revision resource name in `api-id`.
+- Enumerates environments and exports validated `type=oas` resource files as `apigee-env-oas` candidates.
+- A proxy without a supported embedded document is surfaced for manual review; the action does not synthesize routes or convert gRPC definitions.
+
+## `api-hub`
+
+- Walks the provisioned API Hub locations, then `apis -> versions -> specs`, in the requested project.
+- Exports verbatim spec bytes with `specs/{spec}:contents`; API Hub is the consolidation layer for manually registered specs and Apigee / API Gateway plugin ingestion.
+- Produces `api-hub-spec` candidates and records the full spec resource name in `api-id`.
+- Non-OpenAPI spec types (proto, WSDL, MCP) surface as unsupported candidates for manual review; nothing is converted.
+- IAM note: API Hub uses product-specific roles (`roles/apihub.viewer`); project Owner alone is not sufficient, so unprovisioned or unauthorized hubs probe as `skipped:iam` and discovery continues.
+
+## `app-integration`
+
+- Lists regional Application Integration integrations and keeps only those whose ACTIVE version has an `api_trigger/` trigger.
+- Calls `locations/{location}:generateOpenApiSpec` to have Google generate the OpenAPI 3.0 contract from the trigger request/response schemas.
+- Produces `app-integration-trigger` candidates; the export evidence marks the contract as generated, not an uploaded source file.
+
+## `connectors-custom`
+
+- Lists global custom Integration Connectors and their versions; each version records the `specLocation` of the OpenAPI document it was built from.
+- Fetches `gs://` spec objects through the authenticated Cloud Storage JSON API; `https://` locations are surfaced as manual review because the action never fetches arbitrary remote URLs.
+- Produces `connectors-custom-spec` candidates.
+- Lists regional connections and, when schema metadata is available, derives an OpenAPI 3.0 document as `connectors-generated-spec`. Evidence explicitly identifies generated contracts, which rank below stored specification sources; connections without schema metadata are skipped fail-soft.
+
+## `apigee-portal`
+
+- Lists Apigee portal sites and their published API documents in the requested project-ID organization.
+- Exports the original `oasDocumentation.spec.contents` document.
+- Produces `apigee-portal-doc` candidates whose `api-id` is `organizations/{org}/sites/{site}/apidocs/{document}`.
+- GraphQL, AsyncAPI, missing, and invalid OpenAPI documentation remains visible as unsupported for manual review.
+- IAM note: authorization failures probing portal sites become `skipped:iam`, and discovery continues.
+
+## `vertex-extensions`
+
+- Enumerates Vertex AI project locations and lists extensions in each region.
+- Exports the extension manifest's inline `openApiYaml` or fetches its `openApiGcsUri` through authenticated Cloud Storage.
+- Produces `vertex-extension-manifest` candidates whose `api-id` is the full extension resource name.
+- Manifests with neither source, multiple sources, invalid OpenAPI, or invalid storage locations remain unsupported.
+- IAM note: authorization failures probing Vertex AI extensions become `skipped:iam`, and discovery continues.
+
+## `agent-engines`
+
+- Enumerates the same Vertex AI project regions used for extensions and lists `reasoningEngines` in each region.
+- Assembles an OpenAPI 3.0 document from each engine's `spec.classMethods` declarations as `agent-engine-generated-spec`.
+- Empty declarations produce no candidate; operation-less or invalid assembled documents remain unsupported for manual review.
+- Generated Agent Engine specifications carry lower confidence than stored specification sources, and regional probes fail soft.
+
+## `dialogflow-tools`
+
+- Lists Dialogflow CX agents and their tools in the requested project.
+- Exports the original `openApiSpec.textSchema` stored on each tool.
+- Produces `dialogflow-tool-schema` candidates whose `api-id` is the full tool resource name.
+- Tools without `openApiSpec` are skipped; invalid OpenAPI schemas remain unsupported.
+- IAM note: authorization failures probing Dialogflow become `skipped:iam`, and discovery continues.
+
+## `ces-toolsets`
+
+- Lists Conversational Agents (Agent Studio) apps and OpenAPI toolsets in the global CES location, then retrieves each toolset's tools with `toolsets/{toolset}:retrieveTools`.
+- Exports inline `openApiToolset.openApiSchema` and tool-level `openApiTool.openApiSchema` documents.
+- Produces `ces-tool-schema` candidates for standalone app tools and `ces-toolset-schema` candidates for toolset-scoped tools; each `api-id` identifies the original resource.
+- Disabled, absent, and unauthorized CES surfaces probe fail-soft so discovery continues.
+
+## `iac-local`
+
+- Requires no network probe and scans bounded repository IaC files.
+- Recognizes Terraform `google_api_gateway_api_config` path references and `google_endpoints_service` definitions.
+- Resolves embedded documents or repository-relative path references as `iac-embedded` candidates.
+
+## Ordering and narrowing
+
+A committed `repo-spec` wins before provider probing. All provider candidates enter the same narrowing tiers, in order:
+
+1. `iac-fingerprint`
+2. `project-correlation`
+3. `label-prefilter`
+4. `naming-heuristic`
+
+The `postman-repo` label is an ownership signal for label prefiltering. The selected tier appears in `narrowing-strategy`. If candidates remain indistinguishable, the action reports ranked evidence for manual review instead of choosing arbitrarily.
+
+## Deferred surfaces
+
+Runtime URL probing (`Cloud Run`, `GKE`, `Functions`, Firebase hosting, App Engine `_ah/api/discovery` endpoints) is outside v1 because GCP has no catalog of runtime spec endpoints. Traffic-derived surfaces (APIM shadow-API observation jobs, API Hub discovered observations) yield operations, not contracts, and are not spec sources. Convention-only storage (arbitrary GCS buckets, Secret Manager / Parameter Manager payloads, Artifact Registry generic repos, Cloud Build artifacts) and the legacy Apigee Registry (superseded by API Hub) are also excluded. Service Directory holds endpoint routing metadata with no schema payloads. Google API Discovery documents describe Google's own services, not customer APIs. GKE Gateway `HTTPRoute`/Ingress resources carry path skeletons without schemas, and synthesizing routes from them would violate the no-guessed-contract rule. The action does not fetch arbitrary remote URLs, synthesize routes, or convert gRPC descriptor sets (API Gateway `grpcServices`, Cloud Endpoints `FILE_DESCRIPTOR_SET_PROTO`, `google.api.Service` definitions) — descriptor-to-OpenAPI reconstruction produces an inferred contract, not a stored one.
+
+IaC scanning is likewise bounded. `iac-local` recognizes Terraform `google_api_gateway_api_config` path references and `google_endpoints_service` definitions only. Other IaC shapes are deferred with rationale: Deployment Manager templates and Config Connector CRDs (`apigateway.cnrm.cloud.google.com`, `servicemanagement.cnrm.cloud.google.com`) embed the same config payloads but require YAML/Jinja evaluation the action does not perform; Pulumi and CDK-for-Terraform programs require executing user code, which is forbidden; Terraform `google_apigee_*` resources reference proxy bundles, not spec documents; `gcloud` invocation scripts and Cloud Build steps are arbitrary shell, not declarative references. Executing Terraform, Deployment Manager, or any user code remains out of scope; only static path or document references committed to the repository are read.

package/docs/repository-association.md

@@ -0,0 +1,70 @@
+# Repository association
+
+How a service repository is matched to the deployed GCP resource that owns its API, without `api-id` and without service-name hints. This is the GCP adaptation of the Fox AWS discovery-hub pattern (`postman-cs/fox-postman-onboarding`) — inverted: Fox runs a central hub that scans every AWS gateway and pushes workflows into repos; here each service repo discovers its own spec directly, so there is no hub repository, no cross-repo PAT, and no estate scan.
+
+## Marker
+
+Label the deployed resource with `postman-repo=<canonical slug>`.
+
+Canonicalization of the repository slug (`owner/name`):
+
+- lowercase
+- `/` folds to `--`
+- every other character outside `[a-z0-9_-]` folds to `-`
+- leading/trailing `-`/`_` are stripped
+- values longer than 63 characters (the GCP label limit) are rejected, never truncated
+
+`github.com/Acme/Payments.API` → `postman-repo=acme--payments-api`.
+
+## Where to place the marker
+
+| Provider | Resource to label |
+| --- | --- |
+| `api-gateway` | The API and/or API config (`gcloud api-gateway apis create --labels` / `api-configs create --labels`); config labels override API labels on conflict |
+| `apigee` | The API proxy (proxy `labels`, surfaced through the proxy list with metadata) |
+| `api-hub` | A user-defined string attribute named `postman-repo` on the API/version/spec. API Hub attributes are `map<string, AttributeValues>`, not GCP labels; the action flattens each attribute's first scalar (`stringValues`/`uriValues`/`enumValues`) into candidate tags |
+| `connectors-custom` | The custom connector version labels |
+| `iac-local` | No cloud label needed — committed IaC in the repo fingerprints the API config directly |
+
+`cloud-endpoints`, `app-integration`, `apigee-portal`, `vertex-extensions`, `dialogflow-tools`, and `ces-toolsets` expose no usable label surface. Repos served by those providers select with `api-id`, `expected-api-ids-json`, or `service-mapping-json` + `expected-service-name`.
+
+Label the resource at deploy time from your IaC (Terraform `labels = { postman-repo = "acme--payments-api" }`) so the association ships with the deployment instead of being hand-applied.
+
+## Selection semantics
+
+Precedence: explicit `api-id` → spec committed in the repo (`repo-spec`) → single local IaC reference → repository association.
+
+- Exactly one conflict-free exact `postman-repo` match auto-selects and exports.
+- Zero matches: `unresolved` (`manual-review`); the evidence prints the exact label value the action expected, ready to paste into IaC.
+- Multiple resources carrying the same value: candidates are narrowed and ranked but never auto-selected — `unresolved` (`manual-review`).
+- Colliding canonical values (case-fold or punctuation collisions such as `Org/Payments` vs `org/payments`, or `org/pay.ments` vs `org/pay-ments`, or slugs past 63 characters): affected repos must set `api-id` or `expected-api-ids-json` explicitly.
+- Generic `repo`/`repository`/`service` labels and name heuristics only reorder candidates; they never authorize an export.
+
+## Trust model
+
+`postman-repo` is an owner assertion, not a verified binding. Anyone with update permission on the resource can point it at any repository slug. Mitigations:
+
+- Keep label-write IAM (`apigateway.apiconfigs.update`, `apigee.proxies.update`, and friends) scoped to the deployment pipeline.
+- Ambiguity always degrades to `manual-review`; a second resource claiming the same repo can redirect nothing silently.
+- The exported spec is written into the calling repository's workspace only; a hostile label can at worst feed that repo its own gateway's spec.
+
+## Per-service-repo workflow (spoke)
+
+[`templates/postman-gcp-onboard.yml`](../templates/postman-gcp-onboard.yml) is a ready-to-distribute workflow for service repos:
+
+1. `google-github-actions/auth` with Workload Identity Federation (org-level variables `GCP_WORKLOAD_IDENTITY_PROVIDER`, `GCP_SERVICE_ACCOUNT`, `GCP_PROJECT_ID`; keyless, no exported SA keys).
+2. This action with `project-id` and an explicit `repo-slug: ${{ github.repository }}` (the same value `GITHUB_REPOSITORY` would supply by default).
+3. A guard step that fails the run when `resolution-status != resolved`, echoing the resolution evidence (including the expected label) instead of guessing.
+4. `postman-cs/postman-api-onboarding-action` with the resolved `spec-path`/`service-name` and the org-level `POSTMAN_API_KEY` secret.
+
+Triggers: push to spec/IaC paths, weekly schedule (catches gateway-side drift with no repo change), `workflow_dispatch`, and self-bootstrap on the workflow file itself so onboarding runs the moment the file merges.
+
+## Differences from Fox (AWS)
+
+| | Fox (AWS) | This action (GCP) |
+| --- | --- | --- |
+| Topology | Central hub repo scans gateways, distributes workflows via PRs | Hub-less; each repo self-discovers |
+| Mapping source | `GithubOrg`/`GithubRepo` gateway tags read by the hub | `postman-repo` canonical label read by the repo's own workflow |
+| Spec source of truth | Spec committed in the repo (no AWS export) | Deployed gateway/proxy config exported on demand (repo spec still wins when present) |
+| Credentials | Org secret `POSTMAN_API_KEY` only | Same, plus keyless WIF for GCP reads |
+| Drift | On spec-change push | Push + weekly re-discovery against the live gateway |

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@postman-cse/onboarding-gcp-spec-discovery",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/postman-cs/postman-gcp-spec-discovery-action"
+  },
+  "description": "Discover GCP-hosted API specs and hand the result to Postman API onboarding.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "bin": {
+    "postman-gcp-spec-discovery": "dist/cli.cjs"
+  },
+  "files": [
+    "action.yml",
+    "dist",
+    "README.md",
+    "docs",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "RELEASE_POLICY.md"
+  ],
+  "scripts": {
+    "prepare": "git config core.hooksPath .githooks",
+    "bundle": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --target=node24 --format=cjs --outfile=dist/index.cjs && esbuild src/cli.ts --bundle --platform=node --target=node24 --format=cjs --banner:js='#!/usr/bin/env node' --outfile=dist/cli.cjs && chmod 755 dist/cli.cjs",
+    "build": "npm run typecheck && npm run bundle",
+    "verify:dist:assert": "git diff --ignore-space-at-eol --text --exit-code -- dist && node scripts/verify-dist-artifact.mjs",
+    "verify:dist": "npm run build && npm run verify:dist:assert",
+    "docs:tables": "node scripts/render-action-tables.mjs",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "keywords": [
+    "github-action",
+    "postman",
+    "gcp",
+    "google-cloud",
+    "api-gateway",
+    "cloud-endpoints",
+    "openapi",
+    "api-onboarding"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@actions/core": "3.0.1",
+    "@postman-cse/automation-telemetry-core": "0.2.0",
+    "google-auth-library": "10.9.0",
+    "yaml": "2.9.0"
+  },
+  "overrides": {
+    "uuid": "11.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^24.0.0",
+    "esbuild": "0.28.1",
+    "eslint": "^9.17.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}