# Правила работы агента в проекте fission

## ГЛАВНОЕ ПРАВИЛО

**НЕ "СОВЕРШЕНСТВОВАТЬ" РАБОЧИЙ КОД БЕЗ ЯВНОГО УКАЗАНИЯ.**

---

## Файловая система и выполнение команд

### Маппинг путей

Локальная папка `~/remote_dev/` примонтирована через sshfs к `~/terra/` на ВМ `5.172.178.213`.
Это **одна и та же файловая система**:

| Локально (VS Code)              | На ВМ                         |
|----------------------------------|-------------------------------|
| `/home/naeel/remote_dev/fission` | `/home/naeel/terra/fission`   |
| `/home/naeel/remote_dev/sless`   | `/home/naeel/terra/sless`     |
| `/home/naeel/remote_dev/IoT`     | `/home/naeel/terra/IoT`       |

Любой файл, сохранённый локально через VS Code, **мгновенно виден на ВМ**. SCP не нужен.

### Что можно делать локально

- **Редактировать файлы** — через VS Code, replace_string_in_file, create_file и т.д. Изменения сразу на ВМ.
- **Читать файлы** — read_file, grep_search, file_search, semantic_search — всё разрешено.

### Что ЗАПРЕЩЕНО локально

**Все команды выполнять ИСКЛЮЧИТЕЛЬНО через SSH на ВМ:**

```bash
ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 'КОМАНДА'
```

**Причина:** локально может быть активен VPN, что вызывает сбои при выполнении сетевых команд, обращениях к кластеру, Docker и пр.

Запрещено запускать локально (без ssh):
- `go build`, `go test`, `go mod tidy`
- `docker build`, `docker push`
- `kubectl`, `helm`
- `terraform`
- `curl`, `wget` к кластерным сервисам
- `git push`, `git pull` (git операции — через ssh на ВМ)
- Любые bash-скрипты проекта

### Формат работы

1. Отредактировать файлы локально (VS Code / инструменты агента)
2. Запустить команды через SSH на ВМ
3. Ждать результата

---

## Документация

Всё важное фиксировать в `doc/`:
- `doc/thinking/` — лог рассуждений агента (обязательно)
- `doc/progress.md` — трекер задач
- Обновлять после каждого значимого изменения.

## Git

Коммитить и пушить после каждого завершённого этапа.

### Версионирование тегами

После каждого коммита с изменениями — поднимать версию тега:

```bash
# Посмотреть текущий тег
git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0"

# Поднять patch-версию (v0.1.0 → v0.1.1, v0.1.1 → v0.1.2 и т.д.)
git tag vX.Y.Z && git push origin vX.Y.Z
```

**Правила:**
- Patch (Z) — любое изменение: правка кода, новая функция, фикс
- Minor (Y) — новая фича/компонент (новый ресурс провайдера, новый модуль консоли)
- Major (X) — breaking change
- Тег ставить ПОСЛЕ успешного коммита и пуша
- Формат: `vMAJOR.MINOR.PATCH` (например `v0.2.3`)

---

## Как создать и задеплоить новую Fission-функцию через Terraform

### Пошаговая инструкция (ОБЯЗАТЕЛЬНО следовать)

#### Шаг 1: Создать папку с функцией

Создать папку в `examples/` по шаблону. Пример: `examples/my-test/`

Структура:
```
examples/my-test/
├── code/
│   └── main.py       # Код функции
└── main.tf            # Terraform манифест
```

#### Шаг 2: Написать код функции

Файл `code/main.py` — обязательно функция `main()`:

```python
def main():
    return "hello from my-test"
```

Можно сложнее — с аргументами, JSON, вычислениями:

```python
import json

def main():
    result = {"status": "ok", "data": [1, 2, 3]}
    return json.dumps(result)
```

#### Шаг 3: Написать Terraform манифест

Файл `main.tf` — КОПИРОВАТЬ этот шаблон и менять только имена и URL:

```hcl
terraform {
  required_providers {
    fission = {
      source  = "nail/fission"
      version = "~> 0.1.0"
    }
  }
}

provider "fission" {
  kubeconfig_path = "/home/naeel/.kube/config"
  namespace       = "default"
}

resource "fission_environment" "python" {
  name    = "УНИКАЛЬНОЕ-ИМЯ-env"
  image   = "ghcr.io/fission/python-env"
  version = 3
}

resource "fission_package" "pkg" {
  name        = "УНИКАЛЬНОЕ-ИМЯ-pkg"
  environment = fission_environment.python.name
  source_dir  = "${path.module}/code"
}

resource "fission_function" "fn" {
  name         = "УНИКАЛЬНОЕ-ИМЯ-fn"
  environment  = fission_environment.python.name
  package_name = fission_package.pkg.name
  entrypoint   = "main.main"
}

resource "fission_http_trigger" "route" {
  name     = "УНИКАЛЬНОЕ-ИМЯ-route"
  function = fission_function.fn.name
  url      = "/УНИКАЛЬНЫЙ-URL"
  methods  = ["GET"]
}
```

**ВАЖНО:** Все имена ресурсов (name) должны быть **уникальными** по всему кластеру.
Используй префикс, например `tf-mytest-env`, `tf-mytest-pkg`, `tf-mytest-fn`, `tf-mytest-route`.

#### Шаг 4: Задеплоить через SSH

```bash
ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 \
  'cd ~/terra/fission/examples/my-test && TF_CLI_CONFIG_FILE=/tmp/terraformrc-fission terraform apply -auto-approve'
```

**ОБЯЗАТЕЛЬНО:**
- Переменная `TF_CLI_CONFIG_FILE=/tmp/terraformrc-fission` — ВСЕГДА нужна (dev override провайдера)
- `terraform init` НЕ нужен (dev_overrides пропускает init)
- Выполнять ТОЛЬКО через SSH

#### Шаг 5: Проверить функцию через curl

Роутер требует JWT. Паттерн:

```bash
ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 '
PASSWORD=$(kubectl -n fission get secret router -o jsonpath={.data.password} | base64 -d)
TOKEN=$(curl -sk -X POST https://fission.kube5s.ru/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"$PASSWORD\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)[\"accesstoken\"])")
curl -sk -H "Authorization: Bearer $TOKEN" https://fission.kube5s.ru/УНИКАЛЬНЫЙ-URL
'
```

#### Шаг 6: Удалить (если нужно)

```bash
ssh -i ~/.ssh/naeel_vm_id_ed25519 -o StrictHostKeyChecking=no -o ConnectTimeout=10 naeel@5.172.178.213 \
  'cd ~/terra/fission/examples/my-test && TF_CLI_CONFIG_FILE=/tmp/terraformrc-fission terraform destroy -auto-approve'
```

### Уже задеплоенные функции (НЕ ТРОГАТЬ без явного указания)

| Папка | Endpoint | Ответ |
|-------|----------|-------|
| `examples/hello-python/` | `GET /tf-hello` | `hello from fission via terraform` |
| `examples/stress-suite/` | `GET /stress/fast` | `fast-ok` |
| `examples/stress-suite/` | `GET /stress/cpu` | `cpu-ok:NUMBER` |
| `examples/stress-suite/` | `GET /stress/json` | `{"status":"ok","service":"json"}` |

### Частые ошибки

| Ошибка | Причина | Решение |
|--------|---------|---------|
| `unauthorized: malformed token` | curl без JWT | Добавить JWT (см. шаг 5) |
| `terraform init required` | Забыт `TF_CLI_CONFIG_FILE` | Добавить `TF_CLI_CONFIG_FILE=/tmp/terraformrc-fission` |
| `resource already exists` | Имя не уникальное | Сменить имена на уникальные с префиксом |
| `Error: connection refused` | Команда запущена локально | Выполнять ТОЛЬКО через SSH |
| `package not found` | Опечатка в `source_dir` | Проверить path.module/code и файл main.py |