Metadata-Version: 2.4
Name: postman-bootstrap
Version: 0.15.0
Summary: AWS Transform agent that bootstraps a Postman validation workspace and release gate from a pre-transform repository
Author: Postman Field Engineering
License: Apache-2.0
Project-URL: Homepage, https://www.postman.com
Keywords: aws-transform,postman,api-governance,regression-testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Provides-Extra: agent
Requires-Dist: agent-builder-sdk-aws-transform>=0.1; extra == "agent"
Requires-Dist: agent-builder-agentic-mcp-aws-transform>=0.1; extra == "agent"
Requires-Dist: strands-agents>=1.0; extra == "agent"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: jsonschema>=4.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.6; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# 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](https://learning.postman.com/docs/postman-cli/postman-cli-installation/);
  and
- [Spectral CLI](https://www.npmjs.com/package/@stoplight/spectral-cli).

Install them without cloning this package's repository:

```bash
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:

```bash
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:

```bash
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.

| Path | Who drives it | Additional setup | Available from the public package? |
| --- | --- | --- | --- |
| **1. AWS Transform + skill** | AWS Transform follows a skill emitted into the target repository | `atx`, AWS credentials, and a custom transformation definition supplied by your organization | **Yes**, after that definition exists |
| **2. Bedrock subagents** | Separate spec, plan and gate-building agents, with operator-owned capture between them | `pip install "postman-bootstrap[agent]"`, AWS credentials and Bedrock model access | **Yes; recommended public path** |
| **3. Bedrock orchestrator** | A deployed chooser delegates the phases | An organization-provided AgentCore runtime, invocation path and repository transport | **Not as a standalone pip workflow** |
| **4. Native orchestrator** | A local model runner chooses and executes restricted phases | The repository's native runner and a compatible local model CLI | **Not installed by the public package** |

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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
postman-bootstrap-author --repo . --build
```

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

```bash
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:

```bash
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`:

```bash
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`:

| Artifact | What it proves |
| --- | --- |
| OpenAPI 3.1 spec | the contract exposed by the estate |
| Governance ruleset | whether that contract is well formed |
| Golden corpus | what the pre-transform system actually did |
| Regression suite | whether the replacement matches it case by case |
| Contract tests | whether each endpoint honors its contract |
| Environments | the `baseline`, `target` and optional `mock` locations |

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.
