weave

What this skill does

# INFYNON Weave — API Flow Testing

## Think of This as a New Language

INFYNON Weave is a **domain-specific language for API flow testing**. Like any programming language, it has precise syntax rules and you must use the exact commands — you cannot "write the source files by hand" any more than you would hand-edit compiled bytecode.

The language has three noun types:
- **node** — one HTTP request (the smallest unit)
- **flow** — a directed graph of nodes connected by edges
- **edge** — a directed connection that carries context variables between nodes

And a small set of verbs: `create`, `run`, `attach`, `detach`, `validate`, `import`, `export`, `list`, `get`, `remove`, `clone`, `assertion`, `prompt`, `ai`.

**Learn the syntax. Use only these commands. Never hand-write the files.**

---

## CRITICAL RULE — Commands Only, Never Write Files Directly

> **You must NEVER create, edit, or write `.infynon/` files manually** (no YAML, TOML, JSON, or any other format).
> Every node, flow, edge, assertion, extraction, prompt input, body, header, and env variable must be created and modified **exclusively through `infynon weave` CLI commands**.
>
> **Why this matters:** The files follow a precise internal schema that the CLI owns and manages. Manually written files use a different structure that either fails to load silently or produces wrong behavior that is very hard to debug.
>
> **If you find yourself about to write or edit a file — STOP.** Find the correct `infynon weave` command instead. If no command covers the use case, report the limitation — never work around it with manual file edits.
>
> **If a command fails:** Show the exact error output and stop. Do not attempt to fix it by writing files manually. Diagnose the command invocation instead.
>
> **If the user asks to "just create the file":** Explain that the command is the only correct path. Hand-written `.infynon/` files are not a valid alternative — they are a different format.
>
> This rule applies in ALL situations, no exceptions.

---

You are helping the user work with **INFYNON** (`infynon weave`) — an AI-driven, node-based API flow testing system built into the INFYNON CLI.

Instead of testing a single endpoint in isolation, INFYNON Weave models your backend as a **directed graph**:
- **Node** = one API call (method, path, headers, body, assertions, extractions)
- **Edge** = directed connection between two nodes, carrying context variables between them
- **Flow** = named graph of nodes + edges representing a complete test scenario
- **Context** = variables extracted from responses (e.g., `token`, `user_id`) and threaded forward through edges

---

## Core Concept — Flow Testing

```
[POST /auth/login] ──token──▶ [POST /cart/create] ──cart_id──▶ [POST /cart/checkout]
      ↑ extracts token                ↑ uses token                    ↑ uses token + cart_id
```

Every node automatically receives the variables it needs from the upstream context. You don't manually wire JSON — the AI infers which variables to carry based on variable names, URL structure, and HTTP method conventions.

---

## Prerequisites — Install INFYNON

```bash
infynon --version

# If not installed:
npm install -g infynon                                               # All platforms
cargo install --git https://github.com/d4rkNinja/infynon-cli        # From source
```

---

## Validate — Check Nodes and Flows

Run before testing to catch missing references, bad paths, broken flows:

```bash
infynon weave validate
```

**Checks performed:**
- Every node: method is valid, path starts with `/`, body is valid JSON, extractions formatted correctly
- Every flow: entry node exists in library, every edge node exists, no circular dependencies
- Returns exit code 1 if any **errors** found (warnings don't fail)

**Output:**
```
✔  api-v1-onboarding-branches    valid
⚠  my-incomplete-node            WARNING: no assertions defined
✘  broken-flow                   ERROR: entry node 'missing-node' not found

Summary: 7 nodes (6 valid, 1 warning) | 1 flow (0 valid, 1 error)
```

---

## OpenAPI / Swagger Import

Import an entire API spec in one command — generates nodes, extractions, assertions, and optionally a wired flow.

```bash
# Dry-run preview — nothing is saved
infynon weave import openapi.yaml --dry-run
infynon weave import swagger.json --dry-run

# Import all nodes
infynon weave import openapi.yaml

# Import and create a flow
infynon weave import openapi.yaml --flow "my-api-flow"

# Filter to specific path prefix only
infynon weave import openapi.yaml --prefix /api/v1

# Override base URL from spec
infynon weave import openapi.yaml --base-url http://staging.myapi.com
```

**What gets auto-generated per operation:**
- Node ID from `operationId` (camelCase → kebab-case) or `METHOD-path`
- `Content-Type: application/json` for POST/PUT/PATCH
- `Authorization: Bearer {$AUTH_TOKEN}` for non-auth endpoints (reads from env)
- Body template from `requestBody` schema — string fields become `{field_name}` placeholders
- Extractions from response schema (id, token, *_id, *_token, *_url fields)
- `status == 2xx` assertion + `body exists` assertion

Supports: OpenAPI 3.x (.yaml/.json) and Swagger 2.x, with `$ref` resolution.

---

## Env Variables vs Prompt Inputs — Know the Difference

This is the most important design decision when modeling an API as a Weave flow.

### Rule of thumb

| Type | Use when | Example |
|------|----------|---------|
| **Env var** `{$KEY}` | Static, shared across ALL APIs in the project. Set once, never changes between test runs. | `BASE_URL`, `API_VERSION`, `STAGING_TOKEN`, `X_API_KEY` |
| **Prompt input** `{var}` | Per-run user data. Changes with every test. The person running the test supplies it. | `email`, `phone_number`, `otp_code`, `password` |

### Never put these in `.infynon/.env`
- Email addresses, phone numbers — these are test user data, not project config
- OTP codes, 2FA tokens — these expire; env would always be stale
- Passwords — if running multiple users, each run has different credentials

### Always use prompt inputs for
- User identity: `email`, `phone_number`, `country_code`
- Authentication secrets: `password` (mark `--secret` so input is masked)
- One-time codes: OTP, 2FA, CAPTCHA, confirmation tokens
- Any value that a human needs to supply fresh for each test

### Env vars: only for project-wide static config

```bash
infynon weave env set BASE_URL http://localhost:8001
infynon weave env set API_VERSION v1
infynon weave env set SHARED_API_KEY abc123
```

These appear as `{$BASE_URL}`, `{$API_VERSION}`, `{$SHARED_API_KEY}` in node fields.

**The `.infynon/.env` file is managed by the CLI — never hand-edit it:**
```bash
infynon weave env set BASE_URL http://staging.example.com   # Add or update
infynon weave env list                                       # List (sensitive values masked)
infynon weave env get BASE_URL                              # Show value
infynon weave env get BASE_URL --reveal                     # Show full value
infynon weave env delete OLD_KEY                            # Remove
```

**Resolution order:** `.infynon/.env` file → process environment variables.

### Context variables: carry between nodes in a flow

When a value is prompted or extracted in an upstream node, it's in the flow context and automatically available to downstream nodes without re-prompting.

```
send-email prompts for {email}
    ↓ carries email in context
verify-email uses {email} from context — NOT prompted again
    ↓ carries email + email_code in context
register uses {email} from context — NOT prompted again
```

This means:
- Prompt for `email` ONCE on the first node that needs it
- All downstream nodes just use `{email}` — the runtime system fills it from context

---

## Node Commands

Nodes are stored in `.infynon/api/nodes/` (format auto-detected from existing project files).

### Create a node

```bash
# Interactive wizard
infynon weave node create

# AI-generated from natural la