V8 Runner

---
name: v8-runner
description: "Используй когда задача про runtime 1С, информационная база или workspace: v8project.yaml, первый workspace, build/dump/convert source-set, load/make CF/CFE, build/dump/make EPF/ERF external source-set, syntax/tests/launch, extensions. Не используй для точечного чтения или редактирования XML метаданных, форм, СКД, MXL, ролей, подсистем."
argument-hint: "[config-init|init|build|dump|make|load|syntax|test|launch|extensions] [connection|sourceSet|path|output]"
allowed-tools:
  - Bash
  - Read
  - Glob
  - AskUserQuestion
---

# /v8-runner — runtime workflows через MCP Unica

## MCP routing

- Preferred path: use MCP `unica` tool `unica.runtime.execute`; `unica` owns v8-runner execution, workspace events, and cache refresh after successful mutations.
- Do not start internal runner MCP servers or package launchers directly for normal workflows. The runner is an internal adapter behind public MCP `unica`.
- Direct shell runner calls are allowed only for maintainer/debug investigation when MCP itself is broken; do not use them as task examples.
- For mutating operations, pass `dryRun: false` only when the user explicitly requested execution. Default dry run is the safe preview.

## Быстрый выбор операции

| Намерение | MCP `operation` | Cache/event после успешного non-dry-run |
|---|---|---|
| Создать `v8project.yaml` | `config-init` | `SourceSetChanged` |
| Инициализировать базу/workspace | `init` | `SourceSetChanged` |
| Загрузить XML/EDT исходники в базу | `build` | `BuildCompleted` |
| Выгрузить базу в исходники | `dump` | `SourceSetChanged` |
| Конвертировать Designer/EDT sources | `convert` | `SourceSetChanged` |
| Собрать CF/CFE/EPF/ERF артефакт | `make` | без invalidation |
| Загрузить CF/CFE артефакт | `load` | `BuildCompleted` |
| Проверить синтаксис | `syntax` | без invalidation |
| Запустить тесты | `test` | `BuildCompleted` |
| Запустить клиент/Designer/MCP-клиент | `launch` | без invalidation |
| Синхронизировать extension properties | `extensions` | `BuildCompleted` |

## Auth/license stop rules

- Если вывод операции похож на проблему лицензии 1С (`лиценз`, `license`, `HASP`, `nethasp`, `LM`, `No license`, `Лицензия не найдена`), остановись. Не лечи лицензию, не меняй службы, реестр, `nethasp.ini` или программную лицензию.
- Если база без указанного пользователя/пароля, допускается только два предположения: `Администратор` без пароля, затем `Admin` без пароля. Если оба не подходят, спроси пользователя.
- Не сохраняй пароль в `v8project.yaml` молча. Если credentials нужно записать в connection string, предупреди пользователя и не коммить такой файл.

## Workspace init

Для пустого репозитория сначала создай `src/`, затем `v8project.yaml`, затем реши источник правды.

Если исходники отсутствуют или `src/` пустой, считай существующую базу источником правды и сделай полный `dump`. Если исходники уже есть, не выполняй `build` автоматически: спроси, база или Git является источником правды.

### Новый `v8project.yaml`

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "config-init",
      "config": "./v8project.yaml",
      "connection": "File=build/ib",
      "dryRun": false
    }
  }
}
```

### Первичная инициализация runtime state

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "init",
      "dryRun": false
    }
  }
}
```

### Первичная выгрузка в `src/`

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "dump",
      "mode": "full",
      "dryRun": false
    }
  }
}
```

## Configuration examples

### Конфиг с серверной базой

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "config-init",
      "config": "./v8project.yaml",
      "connection": "Srvr=\"srv01\";Ref=\"dev\";",
      "dryRun": false
    }
  }
}
```

### EDT source format

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "config-init",
      "config": "./v8project.yaml",
      "format": "edt",
      "builder": "IBCMD",
      "dryRun": false
    }
  }
}
```

### Локальный overlay

Используй `v8project.local.yaml` для локальных `infobase.connection`, credentials и tool paths. Не добавляй туда `source-set`, `format` или `builder`: эти поля должны жить в основном проектном конфиге.

## Build/load/update

### Обычный build

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "build",
      "dryRun": false
    }
  }
}
```

### Build одного source-set

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "build",
      "sourceSet": "main",
      "dryRun": false
    }
  }
}
```

### Полная пересборка после branch switch/rebase

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "build",
      "fullRebuild": true,
      "dryRun": false
    }
  }
}
```

### Загрузка CF/CFE

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "load",
      "path": "build/config.cf",
      "mode": "update",
      "dryRun": false
    }
  }
}
```

### Загрузка с merge settings

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "load",
      "path": "build/config.cf",
      "mode": "merge",
      "settings": "merge-settings.xml",
      "dryRun": false
    }
  }
}
```

### Загрузка расширения

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "load",
      "path": "build/MyExtension.cfe",
      "extension": "MyExtension",
      "mode": "update",
      "dryRun": false
    }
  }
}
```

## Dump/convert/artifacts

Перед `dump` проверь `git status --short`, чтобы не смешать чужие изменения с выгрузкой из базы.

### Incremental dump

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "dump",
      "mode": "incremental",
      "dryRun": false
    }
  }
}
```

### Partial dump объекта

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "dump",
      "mode": "partial",
      "object": "Catalog:Номенклатура",
      "dryRun": false
    }
  }
}
```

### Dump расширения или source-set

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "dump",
      "mode": "full",
      "extension": "MyExtension",
      "sourceSet": "main",
      "dryRun": false
    }
  }
}
```

### Convert Designer/EDT

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "convert",
      "sourceSet": "main",
      "output": "build/convert",
      "dryRun": false
    }
  }
}
```

### Экспорт CF/CFE/EPF/ERF

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "make",
      "sourceSet": "main",
      "output": "build/config.cf",
      "dryRun": false
    }
  }
}
```

### Публикация внешних обработок EPF

Для external source-set `EXTERNAL_DATA_PROCESSORS` параметр `output` задает каталог публикации, а не имя одного файла. Runner сам опубликует `.epf` по именам внешних обработок внутри source-set.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "make",
      "sourceSet": "external-processors",
      "output": "build/external",
      "dryRun": false
    }
  }
}
```

### Публикация внешних отчётов ERF

Для external source-set `EXTERNAL_REPORTS` параметр `output` также задает каталог публикации.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "make",
      "sourceSet": "external-reports",
      "output": "build/external",
      "dryRun": false
    }
  }
}
```

### Выгрузка внешних обработок/отчётов из базы

Выгрузка EPF/ERF теперь идет не через отдельный файл-скрипт, а через configured external source-set в `v8project.yaml`.

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "dump",
      "mode": "full",
      "sourceSet": "external-processors",
      "dryRun": false
    }
  }
}
```

### Загрузка external source-set в базу

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "build",
      "sourceSet": "external-processors",
      "dryRun": false
    }
  }
}
```

## Syntax/tests/extensions

### Designer module syntax

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "syntax",
      "mode": "designer-modules",
      "server": true,
      "thinClient": true,
      "dryRun": false
    }
  }
}
```

### YaXUnit all

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "test",
      "testRunner": "yaxunit",
      "testScope": "all",
      "dryRun": false
    }
  }
}
```

### YaXUnit module

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "test",
      "testRunner": "yaxunit",
      "testScope": "module",
      "module": "CommonModule.МоиТесты",
      "dryRun": false
    }
  }
}
```

### Vanessa Automation

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "test",
      "testRunner": "va",
      "dryRun": false
    }
  }
}
```

### Extension properties

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "extensions",
      "sourceSet": "MyExtension",
      "dryRun": false
    }
  }
}
```

## Launch

### Designer

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "launch",
      "clientMode": "designer",
      "dryRun": false
    }
  }
}
```

### Thin client

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "launch",
      "clientMode": "thin",
      "dryRun": false
    }
  }
}
```

### Client MCP без VA

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "launch",
      "clientMode": "mcp",
      "mode": "thin",
      "mcpPort": 1550,
      "dryRun": false
    }
  }
}
```

### Client MCP с Vanessa Automation

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "unica.runtime.execute",
    "arguments": {
      "cwd": "<workspace>",
      "operation": "launch",
      "clientMode": "mcp-va",
      "mode": "thin",
      "mcpConfig": "tools/client-mcp.json",
      "dryRun": false
    }
  }
}
```

## References

- `references/command-selection.md` — карта intent -> MCP arguments.
- `references/project-workflows.md` — workspace, build, syntax, extensions, launch.
- `references/config-and-backends.md` — `v8project.yaml`, `v8project.local.yaml`, source-set и backend constraints.
- `references/file-and-artifact-workflows.md` — dump/convert/load/make.
- `references/testing.md` — YaXUnit, Vanessa Automation, syntax validation.
- `references/troubleshooting.md` — безопасная диагностика без обхода лицензий и auth.