@postman-cse/onboarding-azure-spec-discovery 1.0.1

package/docs/LIVE_TESTING_RUNBOOK.md

@@ -0,0 +1,51 @@
+# Live Azure validation runbook
+
+Live validation provisions disposable real Azure resources, exercises the compiled `dist/cli.cjs` against them, captures sanitized evidence, and tears the resources down. Provisioning is operator-triggered and runs in the shared Azure DevOps deployment context; it is never wired into pull-request CI.
+
+## Deployment context
+
+- Azure DevOps organization: `https://dev.azure.com/PostmanDevOps`
+- Project: `CSE Pilots`
+- Azure Resource Manager service connection: `azure-cse-pilot-builders`
+- Scope: the service connection's `Active Azure Subscription`
+- Resource group: `CSE-Azure-Team` (the connection's Contributor scope)
+
+Do not provision live-validation resources from a personal Azure subscription. The Azure DevOps `AzureCLI@2` task authenticates with the workload-identity service connection and derives `AZURE_SUBSCRIPTION_ID` from `az account show`; no personal login, tenant, or subscription ID belongs in the pipeline or committed evidence.
+
+## Prerequisites
+
+- Permission to queue the `PostmanDevOps` live-validation pipeline in `CSE Pilots`.
+- The `azure-cse-pilot-builders` service connection remains ready and authorized for the pipeline.
+- A fresh build: `npm run build`.
+
+## Run
+
+Queue the `postman-azure-spec-discovery-live-validation` pipeline in `PostmanDevOps/CSE Pilots`. Its `AzureCLI@2` task checks out the requested GitHub ref, builds it, derives the service-connection subscription, and runs:
+
+```sh
+node validation/scripts/validate-live-azure-surfaces.mjs --provision --teardown
+```
+
+Download the sanitized `azure-spec-discovery-live-evidence` pipeline artifact and commit only `live-azure-surfaces.json` after reviewing it against `validation/evidence/README.md`.
+
+The runner:
+
+1. Derives and pins the subscription supplied by `azure-cse-pilot-builders` (`az account show` then `az account set`).
+2. Deploys collision-resistant, run-tagged resources into `CSE-Azure-Team` using `validation/fixtures/azure/live-stack.bicep` (APIM Consumption + current HTTP API + App Service plan/site).
+3. Deploys the local App Service stub zip and points `siteConfig.apiDefinition.url` at the stub's `/openapi.json`.
+4. Polls APIM until export is available (5-minute ceiling, 10-second interval).
+5. Runs six CLI cases: explicit APIM `api-id`; APIM discovery; App Service API definition; `discover-many`; local IaC single resolve; ambiguity fixture.
+6. Writes sanitized evidence to `validation/evidence/live-azure-surfaces.json` (schema 1: totals plus per-case `{name,status,sourceType,providerType,specFormat}` — no IDs, hosts, URLs, or spec bodies).
+7. In `finally`, deletes only the exact App Service site, plan, and APIM service whose identity and run-marker tag match the manifest, removes the deployment record, and polls for up to five minutes before failing if any resource with that run marker remains. It never deletes the shared resource group. Outside ADO, the fallback dedicated-group mode retains its guarded group deletion.
+
+## Flags
+
+- `--provision` — required to create any Azure resource.
+- `--teardown` — required to delete the run-created resources.
+- Omit both to re-validate an existing stack from a `.local.json` manifest within the same service-connection subscription.
+
+## Safety rules
+
+- Shared-group mode deletes only exact run-created resources verified by name, type, subscription, group, and run marker. Dedicated-group mode deletes only the group it created, verified by run marker and subscription.
+- Raw manifests, deployment outputs, and zips are gitignored (`validation/.gitignore`); only sanitized evidence is committed.
+- Never substitute a personal service connection, personal `az login`, or production subscription.

package/docs/providers.md

@@ -0,0 +1,26 @@
+# Provider contracts
+
+Azure spec discovery ships three providers in v1. Each implements the same `SpecProvider` seam (`probe`, `listCandidates`, `exportSpec`) and is probed fail-soft: authorization failures map to `skipped:iam`, other failures to `skipped:error`, and discovery continues with the remaining providers.
+
+## `apim` — Azure API Management
+
+- Enumerates every visible APIM service (subscription-wide or scoped by `resource-group`) plus each service workspace and lists both service- and workspace-scoped APIs.
+- Only **current revisions** are candidates; non-current revisions are dropped at enumeration.
+- Only **HTTP** APIs are exportable. SOAP, GraphQL, WebSocket, gRPC, and OData APIs stay visible as unsupported candidates so ambiguity output can name them, but selecting one resolves to manual review and never writes a file.
+- Export uses the ARM export protocol: the management call returns a short-lived Storage SAS link, and the document is fetched from that link immediately. A 403 discards the expired link and repeats the whole export/fetch cycle within `max-attempts`; links are never logged. The exported document is validated (`Swagger 2.0`/`OpenAPI 3.x`, non-empty `paths`) before it is written.
+- The full APIM API ARM resource ID appears only in the `api-id` output and `resolution-json.apiId`. Logs, evidence, and Step Summaries redact it.
+
+## `app-service` — App Service API definition
+
+- Lists App Service sites and reads `siteConfig.apiDefinition.url`.
+- A site is a candidate when its API definition URL is set. Export fetches the URL over HTTPS with a bounded, redirect-limited, content-validated fetch (private-address and non-HTTPS URLs are refused).
+- The fetched document is validated the same way as APIM exports before it is written.
+
+## `iac-local` — repository Azure IaC
+
+- Always `available` (no network probe). Scans a bounded set of repository files: ARM templates (`*.json` with `Microsoft.ApiManagement` resources carrying inline OpenAPI), Bicep-compiled JSON, and `azure.yaml` service hints.
+- A single embedded spec resolves directly; multiple hits become ranked candidates like any other provider.
+
+## Ordering and narrowing
+
+Probe order is `apim`, `app-service`, `iac-local`. Candidates from all available providers enter the same four-tier narrowing pipeline (`iac-fingerprint`, `rg-correlation`, `tag-prefilter`, `naming-heuristic`); the chosen tier is reported in the `narrowing-strategy` output. Tags in the `postman:*` namespace (`postman:repo`, `postman:project-name`) are the strongest ownership signals.

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@postman-cse/onboarding-azure-spec-discovery",
+  "version": "1.0.1",
+  "description": "Discover Azure-hosted API specs and hand the result to Postman API onboarding.",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "bin": {
+    "postman-azure-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",
+    "azure",
+    "azure-api-management",
+    "apim",
+    "app-service",
+    "openapi",
+    "api-onboarding"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/postman-cs/postman-azure-spec-discovery-action"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@actions/core": "^3.0.1",
+    "@azure/arm-apimanagement": "10.0.0",
+    "@azure/arm-appservice": "19.0.0",
+    "@azure/arm-resourcegraph": "4.2.1",
+    "@azure/arm-resources": "8.0.0",
+    "@azure/arm-subscriptions": "6.0.0",
+    "@azure/identity": "4.13.1",
+    "@postman-cse/automation-telemetry-core": "^0.2.0",
+    "yaml": "^2.6.1"
+  },
+  "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"
+  }
+}