corezoid-variable-manager

# Corezoid Variable Manager

## What variables are

Environment variables store constants (URLs, tokens, API keys, IDs, configuration values)
that must not be hardcoded in process logic. The reference syntax `{{env_var[@name]}}` is
resolved at runtime — changing a variable value takes effect immediately without
redeploying any process.

Variables are **stage-scoped**: shared across all processes within a stage.

---

## Variable types

### By data type

| `data_type` | When to use | Value format |
|-------------|-------------|--------------|
| `raw` | Plain string (URL, token, ID, any scalar) | `"https://api.example.com"` |
| `json` | Structured config, multi-field config, feature flags | `{"key":"value","nested":{...}}` |

### By visibility

| `env_var_type` | UI display | Accessible from | Scopes |
|----------------|------------|-----------------|--------|
| `visible` | Value shown in plain text | All node types | `[{"type":"*","fields":"*"}]` |
| `secret` | Value masked, shows only fingerprint | API Call nodes only | `[{"type":"api_call","fields":"*"}]` |

> ⚠️ **Secret variables** are designed for tokens, passwords, and API keys. They are
> never returned in plain text by the API after creation — only an MD5/SHA256 fingerprint
> is available. Use `visible` for non-sensitive configuration.

---

## MCP Tools

| Tool | Purpose |
|------|---------|
| `create-variable` | Create a `raw` + `visible` variable in one step |

> **Note:** `list`, `modify`, `delete`, and creating `secret` or `json` variables are
> not yet exposed as MCP tools. Use the direct API calls documented below.

---

## Using variables in process JSON

Once a variable exists, reference it with `{{env_var[@short-name]}}` anywhere a value
is expected.

### API Call node — URL field
```json
{
  "type": "api",
  "url": "{{env_var[@payment-api-url]}}/charge",
  "method": "POST",
  "err_node_id": "<error_node_id>"
}
```

### API Call node — header field
```json
{
  "type": "api",
  "url": "{{env_var[@payment-api-url]}}/charge",
  "method": "POST",
  "extra": { "Authorization": "Bearer {{env_var[@payment-api-token]}}" },
  "extra_type": { "Authorization": "string" },
  "err_node_id": "<error_node_id>"
}
```

### Set Parameters node
```json
{
  "type": "set_param",
  "extra": {
    "baseUrl": "{{env_var[@service-url]}}",
    "token":   "{{env_var[@service-token]}}"
  },
  "extra_type": {
    "baseUrl": "string",
    "token":   "string"
  },
  "err_node_id": "<error_node_id>"
}
```

### Call a Process node — passing variable as parameter
```json
{
  "type": "api_rpc",
  "conv_id": "@target-process",
  "extra": { "endpoint": "{{env_var[@service-endpoint]}}" },
  "extra_type": { "endpoint": "string" },
  "err_node_id": "<error_node_id>"
}
```

### Condition node (`go_if_const`)

Variable references work in condition expressions as both the left-hand value and the
comparison value:

```json
{
  "type": "go_if_const",
  "conditions": [
    {
      "fun": "equal",
      "arg": "{{env_var[@feature-flag]}}",
      "val": "enabled"
    }
  ],
  "to_node_id": "<next_node_id>"
}
```

### Code node — variables must be pre-loaded via set_param
Variables are not directly accessible inside `api_code` JavaScript. First assign them
to task fields using a `set_param` node upstream, then read via `data.*` in code:
```javascript
// In set_param upstream: "apiUrl": "{{env_var[@my-api-url]}}"
var url = data.apiUrl + "/endpoint";
```

---

## Naming rules

- Only lowercase letters `[a-z]`, digits `[0-9]`, and hyphens `-`
- Name and description must be **at least 3 characters**
- Must be unique within the stage
- Good: `stripe-secret-key`, `payment-api-url`, `db-host-prod`
- Bad: `URL`, `TOKEN`, `x`, `My_Var`

---

## Local cache files

Two files store variable information locally. Check **both** before creating a new variable:

| File | Created by | Contains |
|------|------------|---------|
| `_ENV_VARS_.json` | `pull-folder` (ZIP export from Corezoid) | All variables in the stage |
| `.processes/variables.json` | MCP `create-variable` tool | Only variables created in this session |

If neither file exists, run `pull-folder` or call the list API (see below) to get the
current state.

---

## Workflow: Create a visible raw variable (MCP tool)

### Step 1 — Check if variable already exists

Read `_ENV_VARS_.json` (or `.processes/variables.json`) and search for the `short_name`.
If found, reuse it — do not create a duplicate.

### Step 2 — Create the variable

Call MCP tool **`create-variable`** with:
- `stage_id`: value of `COREZOID_STAGE_ID` from `.env`
- `name`: the `short_name` (kebab-case, e.g. `stripe-api-key`)
- `description`: human-readable label (min 3 chars), used as `title` in the API
- `value`: the actual value

```
create-variable(
  stage_id="671255",
  name="payment-api-url",
  description="Payment Service Base URL",
  value="https://api.payments.example.com"
)
```

The tool creates the variable in Corezoid and appends it to `.processes/variables.json`.

### Step 3 — Reference in process JSON

Use `{{env_var[@payment-api-url]}}` wherever this value is needed.

---

## Workflow: Create a secret variable (direct API)

Use when storing tokens, passwords, API keys — values that must be masked in the UI.

```
POST {COREZOID_API_URL}/api/2/json
Authorization: Simulator {ACCESS_TOKEN}
Content-Type: application/json

{
  "ops": [{
    "type":         "create",
    "obj":          "env_var",
    "obj_type":     0,
    "status":       "active",
    "data_type":    "raw",
    "env_var_type": "secret",
    "title":        "Stripe Secret Key",
    "short_name":   "stripe-secret-key",
    "description":  "",
    "value":        "sk_live_...",
    "company_id":   "<WORKSPACE_ID>",
    "project_id":   <PROJECT_ID>,
    "stage_id":     <STAGE_ID>,
    "scopes":       [{"type": "api_call", "fields": "*"}]
  }]
}
```

Response: `{ "obj_id": 2192, "proc": "ok", "fingerprints": [...] }`

> The value is never returned after creation. Store it securely before