@postman-cse/onboarding-bootstrap 0.10.0 → 0.12.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

@@ -32,6 +32,21 @@ Lifecycle behavior remains backward-compatible except for collection default mod
 
 If you do not set those inputs, the action refreshes collection pointers from the resolved spec and keeps one canonical spec update path.
 
+### Bootstrap phase independence
+
+**Bootstrap succeeds independently** — it creates or updates Postman workspace and collections even if a later stage (repo sync, Insights onboarding) fails. This is intentional:
+
+- **Postman side is self-contained:** Workspace creation, spec upload, and collection generation do not depend on repository access or merge status.
+- **Repository side is async:** Later stages may fail due to repo permissions, branch protection, or pending approval. Bootstrap completion is not blocked by these downstream concerns.
+- **Idempotent reruns:** If a later stage fails, subsequent reruns of the action will reuse existing Postman assets (via `workspace-id`, `spec-id`, collection IDs) and focus on the failed stage without recreating everything.
+
+**When bootstrap fails:** The action stops and does not proceed to repo sync. Postman assets are left in the state they reached before the failure. Clear error messages identify which required bootstrap step failed (for example, spec lint or collection generation). Optional workspace enrichment steps, such as governance assignment and requester invitation, warn and continue so created workspaces and collections remain usable.
+
+This layered design means customers can:
+1. Verify Postman workspace health independently.
+2. Debug repository issues (branch protection, permissions) separately from Postman provisioning.
+3. Reuse existing Postman assets when fixing downstream failures.
+
 ### Team ID derivation
 
 The action automatically derives the Postman Team ID from your `postman-api-key` via the `/me` API. There is no need to supply a separate team ID input. If the environment variable `POSTMAN_TEAM_ID` is set, that value takes precedence.
@@ -81,6 +96,10 @@ Before upload to Spec Hub, the action parses JSON or YAML OpenAPI documents and
 
 This runs in `src/index.ts` before upload. If nothing under `paths` needs changing, the original document bytes are preserved. When normalization runs, the spec is re-serialized (JSON stays JSON; YAML stays YAML). Each fix emits a **warning** in the Actions log so you can improve the source spec over time. Invalid documents that cannot be parsed are left unchanged and a warning is logged.
 
+### OpenAPI spec URL fetch safety
+
+The root `spec-url` must be HTTPS and is fetched with pinned DNS resolution. The action blocks credential-bearing URLs, localhost/private/link-local/internal destinations, unsafe redirects, DNS rebinding attempts, and oversized OpenAPI resources before uploading content to Spec Hub. Root fetches are capped at 25 MiB, and fetch errors redact URL credentials, query strings, and fragments before logging.
+
 ## Usage
 
 ```yaml
@@ -122,6 +141,76 @@ jobs:
 
 If you want the action to discover prior bootstrap state automatically on reruns, commit `.postman/resources.yaml` and run the action on the ref whose state you want to reuse.
 
+## Dynamic contract tests
+
+Dynamic contract tests harden the generated `[Contract]` collection against the resolved OpenAPI 3.0/3.1 document before any durable contract collection is overwritten.
+
+Scope:
+
+- Safely fetch and bundle HTTPS OpenAPI specs and HTTPS external refs.
+- Validate the bundled OpenAPI document with external and file resolution disabled during validation.
+- Match generated collection requests by method and canonical server/path candidates only; suffix path matching is not used.
+- Require one generated request for every eligible `paths` operation.
+- Validate response status codes, body presence, `Content-Type`, JSON response schemas, text/string schemas, and simple response header schemas.
+- Perform static checks for required non-security query/header parameters and required request bodies.
+
+Non-goals and limitations:
+
+- Swagger 2.0, OAS webhooks, callbacks, and arbitrary user-authored collection requests are not fully validated.
+- Security/auth requirements are not proven at runtime. API-key parameters derived from `securitySchemes` are warned as `CONTRACT_SECURITY_NOT_VALIDATED`.
+- Complex non-JSON object schemas, header `content`, unsupported schema dialects, unsupported keywords, and discriminator-heavy schemas fail closed instead of generating weak tests.
+- Generated scripts target Newman/Postman runtime support for ES2020-compatible JavaScript and use compiled schemasafe IIFE validators. They do not use `pm.response.to.have.jsonSchema`, `eval`, or `new Function`.
+
+OpenAPI semantics:
+
+- OAS 3.0 `$ref` siblings are ignored, `nullable` is converted to JSON Schema unions, boolean exclusive min/max is converted, and response `writeOnly` properties are removed from response validation.
+- OAS 3.1 `$ref` siblings are applied, the default dialect is JSON Schema 2020-12, supported `$schema` values are preserved, and unsupported custom dialects fail closed.
+
+Security and size limits:
+
+- Only HTTPS spec URLs and external refs are allowed.
+- Localhost, loopback, link-local, RFC1918, RFC6598, IANA special-use IPv4/IPv6 ranges, IPv4-mapped IPv6, `.local`, and `.internal` destinations are blocked.
+- DNS results are vetted and pinned into the HTTPS socket; redirects are fully revalidated.
+- Limits: 5 redirects, 100 external refs, ref depth 20, 25 MiB per fetched resource, and 25 MiB total fetched bytes.
+- Generated request scripts warn above 256 KiB and fail above 900 KiB; instrumented contract collection uploads fail above 4 MiB before upload. The bundled action is also reviewed for dependency-driven size growth.
+
+Rollback behavior:
+
+- Spec preflight runs before Postman mutations.
+- For existing spec updates, the previous normalized spec content is fetched and hashed before update.
+- If linting, collection generation, instrumentation, tagging, or linking fails after an existing spec update, the action best-effort restores the previous spec content.
+- If rollback fails, the action emits `CONTRACT_SPEC_ROLLBACK_FAILED` with the previous content SHA-256 for manual restoration.
+- Refresh mode stages generated baseline, smoke, and contract collections and instruments the temporary contract collection before updating any durable tracked collection. If a durable refresh update fails after another durable collection was updated, the action best-effort restores previously updated collection snapshots. Collection mutations after the refresh stage, such as later tagging/linking side effects, are not automatically rolled back; rerun the action after resolving the failure to reconcile generated collections with the restored spec.
+
+| Error code | Meaning | Remediation |
+| --- | --- | --- |
+| `CONTRACT_SPEC_FETCH_BLOCKED` | Spec URL, ref URL, DNS result, redirect, or socket destination was not allowed. | Use public HTTPS spec/ref URLs that do not resolve to private or local networks. |
+| `CONTRACT_SPEC_FETCH_FAILED` | Allowed HTTPS fetch failed or redirected too many times. | Check availability, status codes, and redirect chains. |
+| `CONTRACT_REF_LIMIT_EXCEEDED` | External ref count exceeded the configured limit. | Reduce external ref fan-out or bundle the spec upstream. |
+| `CONTRACT_REF_DEPTH_EXCEEDED` | Ref nesting exceeded the configured limit. | Flatten recursive/deep ref chains. |
+| `CONTRACT_REF_SIZE_EXCEEDED` | A fetched resource or total fetched bytes exceeded limits. | Reduce spec/ref size or pre-bundle the document. |
+| `CONTRACT_SPEC_PARSE_FAILED` | The fetched document was not valid JSON/YAML object content. | Fix the source document syntax. |
+| `CONTRACT_SPEC_VALIDATION_FAILED` | The bundled document failed OpenAPI validation. | Fix OpenAPI validation errors. |
+| `CONTRACT_UNSUPPORTED_OPENAPI_VERSION` | The document was not OpenAPI 3.0 or 3.1. | Provide an OpenAPI 3.0/3.1 document. |
+| `CONTRACT_NO_ELIGIBLE_OPERATIONS` | No eligible `paths` operations with responses were found. | Add path operations with responses. |
+| `CONTRACT_OPERATION_NO_RESPONSES` | A `paths` operation had no response definitions. | Add at least one OpenAPI response to each path operation. |
+| `CONTRACT_UNRESOLVED_REF` | A ref remained unresolved after secure bundling. | Fix the ref target or make the external ref HTTPS-accessible. |
+| `CONTRACT_UNSUPPORTED_SCHEMA_DIALECT` | A schema declared an unsupported JSON Schema dialect. | Use draft-07 or 2020-12-compatible schemas. |
+| `CONTRACT_SCHEMA_COMPILE_FAILED` | schemasafe could not compile a response/header schema. | Simplify or correct the unsupported schema. |
+| `CONTRACT_STATIC_REQUEST_CHECK_FAILED` | Generated request missed a required non-security parameter or body. | Adjust generation options or the spec so generated requests include required shape. |
+| `CONTRACT_SECURITY_NOT_VALIDATED` | Security requirements were detected but dynamic tests cannot prove auth at runtime. | Run dedicated auth tests and review generated requests for required credentials. |
+| `CONTRACT_WEBHOOKS_NOT_VALIDATED` | OpenAPI webhooks were present but are not included in dynamic contract coverage. | Validate webhook behavior separately or model required behavior under `paths`. |
+| `CONTRACT_CALLBACKS_NOT_VALIDATED` | Operation callbacks were present but are not included in dynamic contract coverage. | Validate callback behavior separately or add dedicated tests. |
+| `CONTRACT_DUPLICATE_OPERATION_MATCH` | Multiple OpenAPI operations share the same canonical request mapping candidate. | Disambiguate paths, server prefixes, or templated routes. |
+| `CONTRACT_DUPLICATE_OPERATION_REQUEST` | More than one generated request mapped to the same contract operation. | Disambiguate paths/operations or generated requests. |
+| `CONTRACT_OPERATION_COVERAGE_FAILED` | Generated contract collection did not cover every eligible operation. | Regenerate the collection or fix operation paths. |
+| `CONTRACT_FORBIDDEN_SCRIPT_CONSTRUCT` | Generated script included a forbidden dynamic validation construct. | Report the schema that triggered unsafe generation. |
+| `CONTRACT_SCRIPT_SIZE_EXCEEDED` | A generated request test script exceeded the per-script size gate. | Reduce schema complexity or split the API. |
+| `CONTRACT_COLLECTION_SIZE_EXCEEDED` | Instrumented contract collection exceeded the size gate. | Reduce schema/operation count or split the API. |
+| `CONTRACT_COLLECTION_ID_COLLISION` | Baseline, smoke, and contract IDs were not pairwise distinct. | Pass distinct collection IDs or clear stale IDs. |
+| `CONTRACT_PLAN_MISSING` | Contract instrumentation ran without a preflight-generated contract plan. | Rerun with dynamic contract preflight enabled and report the failure if it persists. |
+| `CONTRACT_SPEC_ROLLBACK_FAILED` | Best-effort previous spec restoration failed after a later error. | Restore the previous spec content manually using the emitted SHA-256. |
+
 ## CLI Usage (Non-GitHub CI)
 
 The CLI is available for GitLab CI, Bitbucket Pipelines, Azure DevOps, and other CI systems.
@@ -130,9 +219,11 @@ GitHub Actions users should continue using the `action.yml` interface.
 Install globally:
 
 ```bash
-npm install -g postman-bootstrap-action
+npm install -g @postman-cse/onboarding-bootstrap
 ```
 
+The CLI package supports Node.js 20+. The examples below use Node.js 24 to match the GitHub Action runtime.
+
 Basic usage:
 
 ```bash
@@ -153,9 +244,9 @@ Example GitLab CI job:
 
 ```yaml
 bootstrap:
-  image: node:20
+  image: node:24
   script:
-    - npm install -g postman-bootstrap-action
+    - npm install -g @postman-cse/onboarding-bootstrap
     - postman-bootstrap --project-name core-payments --spec-url "$SPEC_URL" --postman-api-key "$POSTMAN_API_KEY" --postman-access-token "$POSTMAN_ACCESS_TOKEN" --result-json bootstrap-result.json --dotenv-path bootstrap.env
   artifacts:
     paths:
@@ -169,9 +260,9 @@ Example Bitbucket Pipelines step:
 pipelines:
   default:
     - step:
-        image: node:20
+        image: node:24
         script:
-          - npm install -g postman-bootstrap-action
+          - npm install -g @postman-cse/onboarding-bootstrap
           - postman-bootstrap --project-name core-payments --spec-url "$SPEC_URL" --postman-api-key "$POSTMAN_API_KEY" --postman-access-token "$POSTMAN_ACCESS_TOKEN" --result-json bootstrap-result.json --dotenv-path bootstrap.env
         artifacts:
           - bootstrap-result.json
@@ -184,9 +275,9 @@ Example Azure DevOps job:
 steps:
   - task: NodeTool@0
     inputs:
-      versionSpec: '20.x'
+      versionSpec: '24.x'
   - script: |
-      npm install -g postman-bootstrap-action
+      npm install -g @postman-cse/onboarding-bootstrap
       postman-bootstrap --project-name core-payments --spec-url "$(SPEC_URL)" --postman-api-key "$(POSTMAN_API_KEY)" --postman-access-token "$(POSTMAN_ACCESS_TOKEN)" --result-json bootstrap-result.json --dotenv-path bootstrap.env
     displayName: Bootstrap Postman assets
   - publish: bootstrap-result.json
@@ -202,7 +293,8 @@ steps:
 | `baseline-collection-id` | | Reuse an existing baseline collection. |
 | `smoke-collection-id` | | Reuse an existing smoke collection. |
 | `contract-collection-id` | | Reuse an existing contract collection. |
-| `collection-sync-mode` | `refresh` | Collection lifecycle policy. `reuse` keeps existing collections, `refresh` regenerates the current collection set from the latest spec, and `version` creates or reuses release-scoped collections. |
+| `sync-examples` | `true` | Whether linked spec/collection relations should enable example syncing during cloud linkage. |
+| `collection-sync-mode` | `refresh` | Collection lifecycle policy. `refresh` keeps the tracked collection IDs while updating them from the latest spec, and `version` creates or reuses release-scoped collections. |
 | `spec-sync-mode` | `update` | Spec lifecycle policy. `update` keeps one canonical spec current in Spec Hub, while `version` creates or reuses a release-scoped spec asset. |
 | `release-label` | | Optional release label used for versioned specs and collections. When omitted for versioned sync, the action derives one from GitHub tag or branch metadata. |
 | `project-name` | | Service name used in workspace and asset naming. |
@@ -221,7 +313,7 @@ steps:
 
 ### Collection sync
 
-- `reuse`: existing collection IDs are reused when available.
+- `reuse`: legacy alias for `refresh`; existing collection IDs are reused when available and updated from the resolved spec.
 - `refresh`: baseline, smoke, and contract collections are regenerated from the resolved spec and become the current/default collection pointers.
 - `version`: a release-scoped collection set is created or reused from the checked-out ref's state when available.
 
@@ -244,9 +336,17 @@ If versioned sync is requested and no usable label can be derived, the run fails
 
 Current Postman asset state lives in `.postman/resources.yaml`.
 
-- `update` and `reuse` modes resolve current-state mappings from the checked-out ref.
+- `update`, `refresh`, and legacy `reuse` modes resolve current-state mappings from the checked-out ref.
 - `version` mode reuses only the checked-out ref's mappings; release history lives in git history and tags, not in a separate manifest file or repository variables.
 
+### Cloud spec-to-collection syncing
+
+After collections exist, bootstrap links them to the cloud specification and triggers a spec-side collection sync when `postman-access-token` is available.
+
+- `sync-examples: true` (default) enables example syncing in that relation setup.
+- `sync-examples: false` keeps the relation but disables example syncing.
+- If `postman-access-token` is missing, bootstrap warns and skips the cloud link/sync step.
+
 ### Contract smoke monitoring
 
 This repo includes `.github/workflows/contract-smoke.yml`, a scheduled live contract check for the upstream Postman APIs used by bootstrap.

package/action.yml

@@ -17,8 +17,12 @@ inputs:
   contract-collection-id:
     description: Existing contract collection ID
     required: false
+  sync-examples:
+    description: Whether linked spec/collection relations should enable example syncing
+    required: false
+    default: 'true'
   collection-sync-mode:
-    description: Collection lifecycle policy (reuse, refresh, or version)
+    description: Collection lifecycle policy (refresh or version)
     required: false
     default: refresh
   spec-sync-mode:
@@ -52,6 +56,10 @@ inputs:
   spec-url:
     description: URL to the OpenAPI document to bootstrap
     required: true
+  openapi-version:
+    description: OpenAPI specification version override (3.0 or 3.1). When not set, the version is auto-detected from the spec content.
+    required: false
+    default: ''
   governance-mapping-json:
     description: JSON map of business domain to governance group name
     required: false
@@ -66,6 +74,18 @@ inputs:
     description: Integration backend for downstream workspace connectivity
     required: false
     default: bifrost
+  folder-strategy:
+    description: Folder organization strategy for generated collections (Paths or Tags)
+    required: false
+    default: Paths
+  nested-folder-hierarchy:
+    description: When folder-strategy is Tags, enables nested folder hierarchy
+    required: false
+    default: 'false'
+  request-name-source:
+    description: Determines how requests are named in generated collections (Fallback or URL)
+    required: false
+    default: Fallback
 outputs:
   workspace-id:
     description: Postman workspace ID
@@ -86,5 +106,5 @@ outputs:
   lint-summary-json:
     description: JSON summary of lint errors and warnings
 runs:
-  using: node20
+  using: node24
   main: dist/index.cjs