@astrofoundry/pi-astro 0.2.11 → 0.3.0

package/skills/playwright-cli/references/test-generation.md

@@ -0,0 +1,88 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with the browser.
+
+## How It Works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test:
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertion
+await expect(page.getByText('Success')).toBeVisible();
+```

package/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

package/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,43 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Start recording
+playwright-cli video-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop demo.webm
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-stop recordings/login-flow-2024-01-15.webm
+playwright-cli video-stop recordings/checkout-test-run-42.webm
+```
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

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.