@astrofoundry/pi-astro 0.2.12 → 0.3.0

package/skills/postman-cli/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: postman-cli
+description: Runs Postman collections, sends HTTP requests, manages mock servers, lints API specs, and pushes workspace changes from the command line. Use this skill whenever the user wants to run API tests, execute collection runs, send ad-hoc HTTP requests, test endpoints, check if an API is working, hit a URL, run Postman tests against QA or staging, start mock servers, lint OpenAPI specs, manage Postman workspace sync, or do anything curl-like with environment variables and auth. Trigger even when the user says "test my API", "call this endpoint", "run the collection", or "send a request to..." — this skill replaces curl/wget with Postman's full feature set.
+allowed-tools: Bash(postman:*)
+---
+
+# Postman CLI
+
+## Quick start
+
+```bash
+# run a collection locally with an environment
+postman collection run ./postman/collections/nada-to-odoo -e ./postman/environments/qa.postman_environment.yaml
+# run a specific folder within a collection
+postman collection run ./postman/collections/nada-to-odoo -i "sale.order"
+# send a quick GET request
+postman request https://api.example.com/health
+# send a POST with body and auth
+postman request POST https://api.example.com/orders --body '{"item":"test"}' --auth-bearer-token "$TOKEN"
+```
+
+## Commands
+
+### Collection run
+
+```bash
+# run entire collection from local path
+postman collection run <collectionPath> [options]
+
+# run with environment file
+postman collection run ./collection -e ./env.yaml
+
+# run with environment variable overrides
+postman collection run ./collection -e ./env.yaml --env-var "odoo_base_url=https://odoo.example.com" --env-var "odoo_db=test_db"
+
+# run with global variables
+postman collection run ./collection -g ./globals.json
+postman collection run ./collection --global-var "api_version=v2"
+
+# run specific folder(s) or request(s) by name or ID
+postman collection run ./collection -i "sale.order"
+postman collection run ./collection -i "sale.order" -i "res.partner"
+
+# run with iteration data file (JSON or CSV)
+postman collection run ./collection -d ./test-data.csv -n 5
+
+# stop on first error
+postman collection run ./collection --bail
+postman collection run ./collection --bail --failure
+
+# control timeouts (milliseconds)
+postman collection run ./collection --timeout 60000 --timeout-request 10000 --timeout-script 5000
+
+# add delay between requests
+postman collection run ./collection --delay-request 500
+
+# verbose output
+postman collection run ./collection --verbose
+
+# suppress exit code (always exit 0)
+postman collection run ./collection -x
+
+# use custom working directory for relative file paths
+postman collection run ./collection --working-dir ./postman
+
+# ignore redirects
+postman collection run ./collection --ignore-redirects
+
+# SSL options
+postman collection run ./collection -k
+postman collection run ./collection --ssl-client-cert ./cert.pem --ssl-client-key ./key.pem
+postman collection run ./collection --ssl-extra-ca-certs ./ca.pem
+
+# cookie jar
+postman collection run ./collection --cookie-jar ./cookies.json --export-cookie-jar ./cookies-after.json
+```
+
+### Reporters
+
+```bash
+# default: CLI reporter only
+postman collection run ./collection
+
+# JSON report
+postman collection run ./collection -r json
+
+# multiple reporters
+postman collection run ./collection -r cli,json,junit,html
+
+# custom export path
+postman collection run ./collection -r json --reporter-json-export ./reports/result.json
+postman collection run ./collection -r junit --reporter-junit-export ./reports/result.xml
+postman collection run ./collection -r html --reporter-html-export ./reports/result.html
+
+# newman-compatible JSON structure
+postman collection run ./collection -r json --reporter-json-structure newman
+
+# omit sensitive data from reports
+postman collection run ./collection -r json --reporter-json-omitRequestBodies --reporter-json-omitResponseBodies
+postman collection run ./collection -r json --reporter-json-omitHeaders
+postman collection run ./collection -r json --reporter-json-omitAllHeadersAndBody
+```
+
+Reports are saved to `./postman-cli-reports/` by default. Only the CLI reporter is supported for v3 format (YAML) collections. JSON, JUnit, and HTML reporters require v2 format (JSON) collections.
+
+### Send a single request
+
+```bash
+# basic GET
+postman request https://api.example.com/users
+
+# explicit method
+postman request GET https://api.example.com/users
+postman request POST https://api.example.com/users
+postman request PUT https://api.example.com/users/1
+postman request PATCH https://api.example.com/users/1
+postman request DELETE https://api.example.com/users/1
+
+# with headers
+postman request https://api.example.com/data -H "Content-Type:application/json" -H "X-API-Key:abc123"
+
+# with body (inline, from file, or from stdin)
+postman request POST https://api.example.com/users --body '{"name":"John"}'
+postman request POST https://api.example.com/users --body @data.json
+echo '{"name":"John"}' | postman request POST https://api.example.com/users --body -
+
+# multipart form data
+postman request POST https://api.example.com/upload -f "name=John" -f "avatar=@photo.jpg"
+
+# with environment file (resolves {{variables}} in URL, headers, body)
+postman request POST https://{{base_url}}/api/users -e dev.postman_environment.json --body '{"name":"{{test_user}}"}'
+
+# authentication
+postman request https://api.example.com/data --auth-bearer-token "mytoken123"
+postman request https://api.example.com/data --auth-basic-username user --auth-basic-password pass
+postman request https://api.example.com/data --auth-apikey-key "X-API-Key" --auth-apikey-value "abc123" --auth-apikey-in header
+
+# with pre-request and post-response scripts
+postman request POST https://api.example.com/login --body '{"user":"admin","pass":"secret"}' \
+  --script-post-request "const token = pm.response.json().token; console.log('Token:', token);"
+
+# timeout and retries
+postman request https://api.example.com/health --timeout 5000 --retry 3 --retry-delay 1000
+
+# redirect control
+postman request https://api.example.com/redirect --redirects-ignore
+postman request https://api.example.com/redirect --redirects-max 5
+
+# output control
+postman request https://api.example.com/data --response-only
+postman request https://api.example.com/data --verbose
+postman request https://api.example.com/data --debug
+postman request https://api.example.com/data --output response.json
+
+# pipe response to other tools
+postman request https://api.example.com/data --response-only | jq '.results[]'
+```
+
+### Authentication
+
+```bash
+# sign in via browser
+postman login
+
+# sign in with API key (for CI/CD)
+postman login --with-api-key ABCD-1234-1234-1234-1234-1234
+
+# EU data residency
+postman login --with-api-key ABCD-1234-1234-1234-1234-1234 --region eu
+
+# sign out
+postman logout
+```
+
+### Collection migration
+
+```bash
+# migrate v2.1 (JSON) collection to v3 (YAML) format
+postman collection migrate ./my-collection.json
+postman collection migrate ./my-collection.json --output ./path/to/new-collection
+```
+
+### Mock servers
+
+```bash
+# start a local mock server from a manifest file
+postman mock run ./mock-manifest.json
+
+# start mock in background, run collection against it, then stop
+postman mock run ./postman/mocks/odoo-mock.json &
+MOCK_PID=$!
+postman collection run ./postman/collections/nada-to-odoo \
+  -e ./postman/environments/qa.postman_environment.yaml \
+  --env-var "odoo_base_url=http://localhost:3000"
+kill $MOCK_PID
+```
+
+### Spec linting
+
+```bash
+# lint a local API specification file
+postman spec lint ./openapi.yaml
+postman spec lint ./openapi.json
+
+# lint by specification ID (requires login)
+postman spec lint 12345678-abcd-1234-abcd-1234567890ab
+```
+
+### Flows
+
+```bash
+# list all flows
+postman flows list
+
+# run a flow from a local file
+postman flows run ./path/to/flow.json
+
+# deploy a flow (required before triggering)
+postman flows deploy <flowId>
+
+# trigger a deployed flow
+postman flows trigger <flowId>
+
+# update a deployed flow's settings
+postman flows update <flowId>
+
+# list run history
+postman flows list-runs
+
+# analyze a specific flow run
+postman flows get-run
+```
+
+### Workspace sync
+
+```bash
+# validate and prepare local collections/environments for push
+postman workspace prepare
+
+# push local changes to Postman workspace
+postman workspace push
+```
+
+### Basic
+
+```bash
+# version
+postman --version
+
+# help
+postman --help
+postman <command> --help
+postman collection run --help
+
+# global options (available on all commands)
+postman --silent <command>
+postman --color off <command>
+```
+
+## Exit codes
+
+- `0` — Success (all tests passed, or for `request`: 2xx-3xx response)
+- `N` — Number of failed tests (e.g., exit code 3 means 3 tests failed)
+- `1` — General error (invalid options, file not found, network error)
+
+## Project-specific usage
+
+This project stores Postman collections and environments in the `postman/` directory:
+
+```
+postman/
+  collections/
+    nada-to-odoo/          # Nada API calls to Odoo
+      delivery.carrier/
+      product.template/
+      res.partner/
+      sale.order/
+      stock.location/
+      stock.quant/
+    odoo-to-nada/          # Odoo webhook push calls to Nada
+  environments/
+    qa.postman_environment.yaml
+  flows/
+  globals/
+  mocks/
+  specs/
+```
+
+### Run the nada-to-odoo collection against QA
+
+```bash
+postman collection run ./postman/collections/nada-to-odoo \
+  -e ./postman/environments/qa.postman_environment.yaml \
+  --env-var "odoo_base_url=https://odoo-qa.drops.com" \
+  --env-var "odoo_db=drops_qa"
+```
+
+### Run only the sale.order folder
+
+```bash
+postman collection run ./postman/collections/nada-to-odoo \
+  -e ./postman/environments/qa.postman_environment.yaml \
+  -i "sale.order" \
+  --env-var "odoo_base_url=https://odoo-qa.drops.com"
+```
+
+### Run the odoo-to-nada collection (webhook push tests)
+
+```bash
+postman collection run ./postman/collections/odoo-to-nada \
+  -e ./postman/environments/qa.postman_environment.yaml \
+  --env-var "nada_base_url=https://nada-qa.drops.me"
+```
+
+### Generate a JSON report for CI
+
+```bash
+postman collection run ./postman/collections/nada-to-odoo \
+  -e ./postman/environments/qa.postman_environment.yaml \
+  -r cli,json \
+  --reporter-json-export ./postman-cli-reports/nada-to-odoo.json
+```
+
+### Quick ad-hoc request to Odoo
+
+```bash
+postman request POST "https://odoo-qa.drops.com/json/2/res.partner/search_read" \
+  --auth-bearer-token "$ODOO_API_TOKEN" \
+  -H "Content-Type:application/json" \
+  -H "X-Odoo-Database:drops_qa" \
+  --body '{"domain": [["is_company","=",true]], "fields": ["name","email"], "limit": 5}' \
+  --response-only | jq .
+```
+
+## Specific tasks
+
+* **Reporters and report customization** [references/reporters.md](references/reporters.md) — Read when generating CI reports, customizing output format, or omitting sensitive data from exports
+* **Request scripting and chaining** [references/request-scripting.md](references/request-scripting.md) — Read when writing post-response scripts, chaining multiple requests, or using the pm.* API
+* **Environment and variable management** [references/environments.md](references/environments.md) — Read when working with environment files, variable precedence, Vault secrets, or CLI overrides

package/skills/postman-cli/references/environments.md

@@ -0,0 +1,92 @@
+# Environment and Variable Management
+
+The Postman CLI resolves `{{variable}}` placeholders in URLs, headers, and request bodies using environment files and CLI overrides.
+
+## Variable precedence (highest to lowest)
+
+1. `--env-var` CLI overrides
+2. `--global-var` CLI overrides
+3. Environment file (`-e`)
+4. Globals file (`-g`)
+5. Postman Vault secrets (only available when signed in)
+
+## Environment files
+
+Environment files are YAML or JSON. Specify with `-e`:
+
+```bash
+postman collection run ./collection -e ./postman/environments/qa.postman_environment.yaml
+```
+
+Example environment file (YAML):
+
+```yaml
+name: QA
+values:
+  - key: odoo_base_url
+    value: "https://odoo-qa.drops.com"
+    enabled: true
+    description: "Base URL without trailing slash"
+  - key: odoo_db
+    value: "drops_qa"
+    enabled: true
+  - key: _odoo_partner_id
+    value: ""
+    enabled: true
+    description: "Script-managed — set after running Create Partner"
+```
+
+## CLI variable overrides
+
+Override individual variables without modifying the environment file:
+
+```bash
+# override environment variables
+postman collection run ./collection -e ./env.yaml \
+  --env-var "odoo_base_url=https://odoo-staging.drops.com" \
+  --env-var "odoo_db=drops_staging"
+
+# override global variables
+postman collection run ./collection \
+  --global-var "api_version=v2" \
+  --global-var "timeout=30000"
+```
+
+## Globals files
+
+Global variables have lower precedence than environment variables and can be overridden by them:
+
+```bash
+postman collection run ./collection -g ./postman/globals/globals.json
+```
+
+## Variable resolution in requests
+
+Variables are resolved in:
+- URLs: `{{odoo_base_url}}/json/2/sale.order/create`
+- Headers: `Authorization: Bearer {{odoo_api_token}}`
+- Body: `{"partner_id": {{_odoo_partner_id}}}`
+
+## Script-managed variables
+
+Variables prefixed with `_` are set dynamically during collection runs via scripts:
+
+```javascript
+// in post-response script
+pm.environment.set('_odoo_order_id', pm.response.json());
+```
+
+These are used to chain requests within a collection run (e.g., create a partner, then use the partner ID to create an order).
+
+## Postman Vault
+
+Secrets like `vault:odoo_api_token` and `vault:nada_x_odoo_api_key` are stored in the Postman Vault (not in environment files). They are only available when signed in to Postman. For local runs without sign-in, pass secrets via `--env-var`:
+
+```bash
+postman collection run ./collection -e ./env.yaml \
+  --env-var "odoo_api_token=$ODOO_API_TOKEN"
+```
+
+## Exporting variables after a run
+
+The Postman CLI does not support exporting the final environment state after a collection run. Script-managed variables (set via `pm.environment.set()`) are only available within the scope of the current run and are not persisted to the environment file.

package/skills/postman-cli/references/reporters.md

@@ -0,0 +1,94 @@
+# Reporters and Report Customization
+
+The Postman CLI has built-in reporters to generate collection run reports. Four reporters are available: CLI, JSON, JUnit, and HTML.
+
+**Important:** JSON, JUnit, and HTML reporters only work with v2 format (JSON) collections. v3 format (YAML) collections only support the CLI reporter.
+
+## Available reporters
+
+### CLI (default)
+
+Displays a report in the terminal. Always shown unless `--silent` is used.
+
+```bash
+postman collection run ./collection -r cli
+```
+
+### JSON
+
+Creates a JSON file with full run details including request/response data.
+
+```bash
+postman collection run ./collection -r json
+postman collection run ./collection -r json --reporter-json-export ./reports/result.json
+
+# use Newman-compatible JSON structure
+postman collection run ./collection -r json --reporter-json-structure newman
+```
+
+### JUnit
+
+Creates an XML file compatible with CI/CD tools that consume JUnit format.
+
+```bash
+postman collection run ./collection -r junit
+postman collection run ./collection -r junit --reporter-junit-export ./reports/result.xml
+```
+
+### HTML
+
+Creates an interactive HTML report. You can filter iterations by test failures or errors.
+
+```bash
+postman collection run ./collection -r html
+postman collection run ./collection -r html --reporter-html-export ./reports/result.html
+```
+
+## Multiple reporters
+
+Combine reporters with comma-separated list:
+
+```bash
+postman collection run ./collection -r cli,json,junit,html
+```
+
+## Custom export paths
+
+By default, reports are saved to `./postman-cli-reports/` with filenames like `collection-name-yyyy-mm-dd-hh-mm-ss`. Override with:
+
+```bash
+--reporter-json-export <path>
+--reporter-junit-export <path>
+--reporter-html-export <path>
+```
+
+If the path is an existing directory, the report file is saved inside it. If the directory does not exist, it is created automatically.
+
+## Omitting sensitive data
+
+Remove request/response bodies and headers from reports:
+
+```bash
+# omit request bodies
+--reporter-json-omitRequestBodies
+--reporter-html-omitRequestBodies
+
+# omit response bodies
+--reporter-json-omitResponseBodies
+--reporter-html-omitResponseBodies
+
+# omit all headers
+--reporter-json-omitHeaders
+--reporter-html-omitHeaders
+
+# omit everything (headers + bodies)
+--reporter-json-omitAllHeadersAndBody
+--reporter-html-omitAllHeadersAndBody
+```
+
+## CI/CD usage
+
+```bash
+# generate JUnit report for CI consumption, fail on test errors
+postman collection run ./collection -r junit --reporter-junit-export ./test-results/postman.xml --bail
+```

package/skills/postman-cli/references/request-scripting.md

@@ -0,0 +1,69 @@
+# Request Scripting and Chaining
+
+The `postman request` command supports pre-request and post-response scripts using the Postman scripting sandbox (pm.* API).
+
+## Post-response scripts
+
+Use `--script-post-request` to run JavaScript after receiving the response:
+
+```bash
+# validate response
+postman request https://api.example.com/health \
+  --script-post-request "pm.test('Health check', function() { pm.expect(pm.response.json().status).to.equal('healthy'); });"
+
+# extract and log data
+postman request POST https://api.example.com/login \
+  --body '{"user":"admin","pass":"secret"}' \
+  --script-post-request "const token = pm.response.json().token; console.log('Token:', token);"
+```
+
+## Chaining requests
+
+Use shell command substitution with `--response-only` to chain requests:
+
+```bash
+# get a token, then use it in the next request
+TOKEN=$(postman request POST https://api.example.com/login \
+  --body '{"username":"admin","password":"pass"}' \
+  --response-only | jq -r '.token')
+
+postman request https://api.example.com/protected \
+  --auth-bearer-token "$TOKEN"
+```
+
+## Collection scripts
+
+Collection files (.yaml or .json) can include scripts at the collection, folder, and request levels:
+
+```yaml
+# in a request YAML file
+scripts:
+  - type: afterResponse
+    code: |-
+      pm.test('Status 200', () => pm.response.to.have.status(200));
+      const res = pm.response.json();
+      pm.environment.set('_odoo_order_id', res);
+    language: text/javascript
+```
+
+Script-managed variables (prefixed with `_`) are set during collection runs and chained between requests using `pm.environment.set()` and `{{variable}}` syntax.
+
+## Available pm.* API in scripts
+
+- `pm.response.json()` — parsed JSON response body
+- `pm.response.to.have.status(code)` — assert status code
+- `pm.expect(value)` — Chai BDD assertion
+- `pm.environment.set(key, value)` — set environment variable for subsequent requests
+- `pm.environment.get(key)` — get environment variable
+- `pm.globals.set(key, value)` — set global variable
+- `pm.globals.get(key)` — get global variable
+- `console.log(...)` — log to terminal output
+
+## Exit codes from tests
+
+When scripts contain `pm.test()` assertions, the exit code equals the number of failed tests. This makes it suitable for CI/CD pipelines:
+
+```bash
+postman collection run ./collection --bail --failure
+echo "Exit code: $?"
+```