postman-bootstrap

Build a release gate that proves a modernized system still behaves like the one it replaced.

Rewrites, ports and framework upgrades are often graded on whether the new code compiles, lints and starts. None of that is a claim about behavior. This package records what the original system actually did, before it changes, and turns that recording into a gate your CI runs against the replacement.

Before you start

Run the bootstrap on an untouched pre-transform checkout. Governance and contract tests can be rebuilt from code later; the original system's behavior survives only in what you capture before it changes.

The common prerequisites are:

• Python 3.11 or newer;
• the Postman CLI; and
• Spectral CLI.

Install them without cloning this package's repository:

python3 -m pip install postman-bootstrap
npm install -g postman-cli
npm install -g @stoplight/spectral-cli

Then make every required executable answer before capturing anything:

python3 --version                 # must be 3.11+
postman-bootstrap --version
postman --version
spectral --version

Treat a missing tool as a failed preflight, not as a reduced but successful run. Without the Postman CLI, the collection-based contract and regression checks cannot execute. Without Spectral, governance cannot execute. If you ignore the preflight and run the gate anyway, the affected command normally fails and the verdict is FAILED; it is not evidence of compatibility.

POSTMAN_API_KEY is different: it is optional. It unlocks publishing, mocks, monitors and checks against a live workspace. If you will not supply one, run this after init in the path you choose so those features are out of scope instead of outstanding:

postman-bootstrap set --repo . --decline api_key

The committed-file gate still runs without a key. Never paste a key into the manifest or a command committed to the repository.

Choose one execution path

The four paths produce the same gate. They differ only in who makes the judgment calls and who drives the loop. Choose one; they are alternatives, not four steps to run in order.

Paths 3 and 4 have no public console entry point today. If an organization provides one, follow its deployment or runner instructions. The explicit CLI workflow below is useful on its own, but it is not a silent substitute for either orchestrator.

Path 1 requires a custom definition

pip install does not create or publish an AWS Transform custom definition. Before the first run, obtain definition source from your organization or workshop facilitator and publish it to the AWS account that will execute the transform:

TRANSFORMATION_NAME=postman-gate-bootstrap

atx --version
atx custom def publish -n "$TRANSFORMATION_NAME" \
  --sd /path/to/definition-source \
  --description "Capture the pre-transform system and build its release gate"

Then initialize the untouched target repository with the skill enabled, and record the exact definition name. Both commands are required:

postman-bootstrap init --repo . \
  --api-name "Orders" \
  --legacy-interface http_service \
  --baseline-url http://127.0.0.1:4000 \
  --boot-command "python3 app.py" \
  --atx-skill

postman-bootstrap set --repo . \
  --transformation-name "$TRANSFORMATION_NAME"

ATX_SHELL_TIMEOUT=3600 atx custom def exec \
  -n "$TRANSFORMATION_NAME" \
  -p . \
  -g file://.aws/atx/exec.bootstrap.yaml \
  --limit 60

The paths, port, boot command and ready endpoint are properties of your application; verify them rather than copying the example blindly. If the definition has not been published in your account, stop there. The generated skill cannot make that account-level prerequisite true.

Recommended path: two short Bedrock sessions

This is the pip-only equivalent of a Part 1 / Part 2 fixture runbook. The first model session authors the contract and capture plan. You review and capture the irreplaceable evidence. The second session builds from that sealed corpus. Capture is deliberately never delegated to the agent that will judge the resulting gate.

Install the optional agent runtime and verify its entry point:

python3 -m pip install "postman-bootstrap[agent]"
postman-bootstrap-author --help

This path also needs AWS credentials with access to the configured Bedrock model. Set an AWS region if your environment does not already provide one:

export AWS_REGION=us-east-1

Part 1: describe, plan and capture the original

First inspect the repository, then initialize it with values a human has verified:

postman-bootstrap scan --repo .

postman-bootstrap init --repo . \
  --api-name "Orders" \
  --legacy-interface http_service \
  --baseline-url http://127.0.0.1:4000 \
  --boot-command "python3 app.py" \
  --ready-path /health

For a database or seed file, add a confirmed reset command with --state-command. For a service whose state exists only in memory, tell replay to restart the service instead:

postman-bootstrap set --repo . --state-mode restart

Now run the installed author. It reads the code, writes an OpenAPI document, chooses business-rule cases, and sets the capture plan. It stops before starting the system:

postman-bootstrap-author --repo .
postman-bootstrap review --repo .
postman-bootstrap gate-status --repo .

Do not replace the author with a bare capture-plan command. With no case file it can only seed happy paths from an existing spec; it cannot infer the negative cases and business rules that make a behavioral oracle useful. If you are supplying your own reviewed spec and case set, the deterministic equivalent is explicit:

postman-bootstrap init --repo . \
  --api-name "Orders" \
  --legacy-interface http_service \
  --baseline-url http://127.0.0.1:4000 \
  --boot-command "python3 app.py" \
  --spec openapi.yaml

postman-bootstrap capture-plan --repo . --cases cases.json
postman-bootstrap review --repo .

cases.json is a JSON array. Every case needs name, method and path; query, headers and body are optional. Put query parameters in query, not after ? in path.

Review is a real approval boundary. The plan is the ceiling on what the gate can catch. Once it is satisfactory, record the untouched system:

postman-bootstrap capture --repo . --boot
postman-bootstrap gate-status --repo .

--boot executes the boot command stored in the manifest. The package will not infer one. Confirm the command, baseline URL and reset behavior before running it so an error response from a misstarted system does not become golden output.

Part 2: build the yardstick and prove it

The second installed session infers response schemas, emits the gate, points its target at the baseline, and runs the corpus self-test:

postman-bootstrap-author --repo . --build

If you want the mechanical build with no model judgment, run the same deterministic stages yourself:

postman-bootstrap infer-schemas --repo .
postman-bootstrap build-gate --repo .

Whichever builder you chose, independently point the ordinary target checks at the original and prove the current corpus replays against the system that produced it:

postman-bootstrap set --repo . --target-url http://127.0.0.1:4000
postman-bootstrap check --repo . --selftest
postman-bootstrap gate-status --repo .

A PASS means every applicable gate step passed. INCOMPLETE means a declared input or proof is still missing, or a required check skipped; it is not a weaker spelling of pass. Fix or explicitly decline the missing input and run the check again.

This first green run proves only that the yardstick works against its own origin. It does not prove that the transformed system is compatible. Keep the original unchanged and available until oracle-integrity and corpus-selftest pass. That is especially important for frozen-snapshot Mode B: after the original is replaced, its evidence cannot be recaptured or honestly reconstructed. Mode C has no replayable original I/O, so the self-test is not an applicable claim there.

Transform, then run the second check

After the transformation, start the replacement, point the gate at its real URL, and run the gate without --selftest:

postman-bootstrap set --repo . --target-url http://127.0.0.1:5000
postman-bootstrap check --repo .
postman-bootstrap gate-status --repo .

This is the release verdict. A green baseline self-test followed by a red target run means the gate worked and found a compatibility change; do not re-record the corpus to make the replacement pass. Begin with exact comparison and add normalization only for a difference a human has established is legitimate and recorded.

What the gate leaves behind

The repository now contains postman/ and ci/gate.sh:

The generated gate does not depend on this Python package. ci/gate.sh runs the committed collections, environments and helper scripts with the Postman CLI and Spectral. The live Postman workspace, when you choose to publish one, is a projection of those files rather than a second source of truth.

Licence

Apache-2.0. Built by Postman Field Engineering.