corezoid-alias-manager

# Corezoid Alias Manager

## What aliases are

An alias is a human-readable `short_name` (e.g. `payment-service`, `send-otp`) that
maps to a process (`conv`). Aliases serve two purposes:

1. **Process reference in JSON** — use `@alias-name` as `conv_id` instead of a numeric
   process ID. This makes processes portable across environments and removes hardcoded IDs.
2. **External HTTP entry point** — each alias generates a `callback_hash` used to send
   tasks to the process via the API Gateway URL.

Alias naming rules (same as Corezoid short names):
- Only lowercase letters `[a-z]`, digits `[0-9]`, and hyphens `-`
- Must be at least 3 characters
- Must be unique within the stage
- Good: `payment-checkout`, `send-otp`, `create-user-v2`
- Bad: `MyAlias`, `PAYMENT`, `a`

---

## MCP Tools

| Tool | Purpose |
|------|---------|
| `create-alias` | Create an alias and link it to a process in one step |

> **Note:** `list`, `modify`, `delete`, and `unlink` operations are not yet exposed as
> MCP tools. Use the direct API calls documented below to perform them.

---

## Using aliases in process JSON

Once an alias exists, replace the numeric `conv_id` with `@alias-name` in any node that
calls another process:

### Call a Process node (`api_rpc`)
```json
{
  "type": "api_rpc",
  "conv_id": "@payment-checkout",
  "extra": { "amount": "{{amount}}", "currency": "{{currency}}" },
  "extra_type": { "amount": "number", "currency": "string" },
  "err_node_id": "<error_node_id>"
}
```

### Copy Task node (`api_copy`)
```json
{
  "type": "api_copy",
  "conv_id": "@send-notification",
  "ref": "{{unique_ref}}",
  "mode": "create",
  "err_node_id": "<error_node_id>"
}
```

### State store read in `set_param` or condition
```
{{conv[@user-states].ref[{{task_ref}}].status}}
```

This reads the `status` field of the task with reference `{{task_ref}}` from the
`@user-states` state diagram process.

---

## Workflow: Create an alias

### Step 1 — Resolve the process

Check whether the user provided a file path, process name, or process ID.
If a file path is given, the process ID is the leading number in the filename
(e.g. `1834583_My_Process.conv.json` → `process_id = 1834583`).

If only a name is given, search locally:
```bash
find . -name "*.conv.json" | xargs grep -l '"title": "My Process"'
```

### Step 2 — Check if the alias already exists

Before creating, verify the `short_name` is not taken. Call the list aliases API
(see "Workflow: List aliases" below) and scan the `short_name` fields.
If a conflict is found, suggest an alternative name to the user.

### Step 3 — Decide the short_name

Apply the naming rules: lowercase, hyphens, no spaces or underscores, at least 3 chars.
Suggest a name derived from the process title if the user hasn't specified one.

### Step 4 — Create the alias

Call MCP tool **`create-alias`** with:
- `process_path`: relative path to the `.conv.json` file
- `short_name`: the alias short name

```
create-alias(
  process_path="./671255_develop/1834583_My_Process.conv.json",
  short_name="payment-checkout"
)
```

The tool creates the alias, links it to the process, and returns the `alias_id`.
Requires `COREZOID_STAGE_ID` to be set in `.env`.

### Step 5 — Update and redeploy referencing processes

After creating the alias, replace any numeric `conv_id` references to this process
across the project with `@short-name`:

```bash
grep -rl '"conv_id": 1834583' . --include="*.conv.json"
```

For each file found, replace `"conv_id": 1834583` with `"conv_id": "@payment-checkout"`.
Then for each modified file, run **`lint-process`** and on success **`push-process`**.

> After pushing, tell the user: "Changes deployed. Please **refresh the page** in Corezoid to see the updated process."

---

## Workflow: List aliases

The MCP server does not yet expose a `list-aliases` tool. Use the Corezoid API directly.

**Required fields:**
- `company_id` — workspace ID (from `.env` `WORKSPACE_ID`)
- `project_id` — project ID (from the `*.stage.json` file in the project root)
- `stage_id` — stage ID (from `.env` `COREZOID_STAGE_ID`)

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

{
  "ops": [{
    "type": "list",
    "obj": "aliases",
    "sort": "date",
    "order": "desc",
    "id": "<WORKSPACE_ID>",
    "company_id": "<WORKSPACE_ID>",
    "project_id": <PROJECT_ID>,
    "stage_id": <STAGE_ID>
  }]
}
```

**Response fields per alias:**
| Field | Description |
|-------|-------------|
| `obj_id` | Alias numeric ID (needed for modify/delete/link) |
| `title` | Human-readable display title |
| `short_name` | The `@short-name` used in `conv_id` references |
| `description` | Optional description |
| `obj_to_id` | Process (`conv`) ID this alias points to |
| `obj_to_type` | Always `"conv"` for process aliases |
| `uuid` | Alias UUID |
| `create_time` / `change_time` | Unix timestamps |
| `project_title`, `stage_title` | Context information |

---

## Workflow: Modify an alias

To rename an alias or change its title/description (does NOT change which process it
points to — use unlink + link for that).

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

{
  "ops": [{
    "type": "modify",
    "obj": "alias",
    "obj_id": <ALIAS_ID>,
    "title": "New Display Title",
    "short_name": "new-short-name",
    "description": "Updated description",
    "company_id": "<WORKSPACE_ID>",
    "project_id": <PROJECT_ID>,
    "stage_id": <STAGE_ID>
  }]
}
```

> ⚠️ Changing `short_name` invalidates all `"conv_id": "@old-name"` references
> across every process in the project. Grep all `.conv.json` files and update them,
> then push each modified process.

---

## Workflow: Repoint an alias to a different process

Use two API calls: unlink from the current process, then link to the new one.

### Step 1 — Unlink from current process
```
POST {COREZOID_API_URL}/api/2/json

{
  "