# Развёртывание Codex Skill Для ServerManager

Этот документ описывает текущее состояние интеграции `ServerManager -> Codex`, автоматическое и ручное развёртывание, проверку и все известные edge cases.

Поддерживаемый deployment target для этой интеграции:

- Linux
- macOS
- Windows

## Что именно разворачивается

Интеграция для Codex состоит из трёх слоёв:

1. Общий локальный backend:
   - `~/.server-connections/ssh.py`
   - `~/.server-connections/encryption.py`
   - `~/.server-connections/servers.json`
2. Codex skill package:
   - `~/.codex/skills/server-manager/`
3. Безопасный wrapper для вызова backend из Codex:
   - `~/.server-connections/codex-ssh` на Linux/macOS
   - `~/.server-connections/codex-ssh.cmd` на Windows

В репозитории исходники skill лежат здесь:

- [SKILL.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/SKILL.md)
- [command-matrix.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/references/command-matrix.md)
- [project.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/references/project.md)
- [server-manager-doctor.sh](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/scripts/server-manager-doctor.sh)
- [server-manager-doctor.cmd](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/scripts/server-manager-doctor.cmd)
- [codex-ssh-wrapper.sh](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/scripts/codex-ssh-wrapper.sh)
- [codex-ssh-wrapper.cmd](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/scripts/codex-ssh-wrapper.cmd)

## Как это работает

Модель безопасности та же, что и у Claude integration:

```text
Codex skill -> ~/.server-connections/codex-ssh -> ~/.server-connections/ssh.py -> encrypted servers.json
```

Ключевая идея:

- Codex видит только алиасы и безопасные результаты команд.
- `ssh.py` сам читает credentials из локального зашифрованного хранилища.
- Codex не должен читать `servers.json`, `settings.json` или `encryption.py` напрямую.

## Что уже автоматизировано

Теперь Codex integration встроена в продуктовый setup flow:

- `core/claude_setup.py` ставит `ssh.py`, `encryption.py`, `~/.claude/commands/ssh.md`, `~/.codex/skills/server-manager/`, wrapper `~/.server-connections/codex-ssh` и блок в `~/.claude/CLAUDE.md`
- вкладка `Setup` в GUI показывает отдельные статусы для Claude skill, Codex skill и Codex wrapper
- `build.py` после сборки автоматически синхронизирует Claude- и Codex-артефакты в локальный runtime

Платформенный split такой:

- Linux/macOS: используются `codex-ssh-wrapper.sh` и `server-manager-doctor.sh`
- Windows: используются `codex-ssh-wrapper.cmd` и `server-manager-doctor.cmd`

Ручная установка всё ещё полезна как fallback path, если нужен точечный repair или offline debugging.

## Предварительные условия

Перед установкой Codex skill должны уже существовать или быть установлены через `Setup`:

1. `~/.server-connections/ssh.py`
2. `~/.server-connections/encryption.py`
3. `~/.server-connections/servers.json`
4. `codex` CLI

Проверка:

```bash
ls -la ~/.server-connections
codex --help
```

Если `~/.server-connections/ssh.py` отсутствует:

1. Открыть ServerManager GUI
2. Перейти в `Setup`
3. Нажать `Install Everything`

Это поставит backend, Claude skill и Codex skill целиком.

## Рекомендуемый путь: установка через GUI

1. Открыть ServerManager
2. Перейти в `Setup`
3. Нажать `Install Everything`
4. Проверить, что зелёные статусы появились у:
   - `ssh.py`
   - `Encryption module`
   - `Claude /ssh skill`
   - `Codex skill`
   - `Codex wrapper`
   - `SSH key`

Для точечного ремонта можно использовать отдельные кнопки `Claude skill` и `Codex skill` в той же вкладке.

## Ручная установка Codex Skill

### 1. Скопировать skill package в глобальный Codex home

```bash
mkdir -p ~/.codex/skills
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager
```

### 2. Установить wrapper в shared runtime directory

Linux/macOS:

```bash
install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh
```

Windows:

```bat
copy .codex\skills\server-manager\scripts\codex-ssh-wrapper.cmd %USERPROFILE%\.server-connections\codex-ssh.cmd
```

### 3. Проверить doctor script

Linux/macOS:

```bash
~/.codex/skills/server-manager/scripts/server-manager-doctor.sh
```

Windows:

```bat
%USERPROFILE%\.codex\skills\server-manager\scripts\server-manager-doctor.cmd
```

Ожидается:

- `ssh.py` найден
- `encryption.py` найден
- `codex-ssh` executable

### 4. Проверить wrapper без раскрытия credentials

Linux/macOS:

```bash
~/.server-connections/codex-ssh --list
```

Windows:

```bat
%USERPROFILE%\.server-connections\codex-ssh.cmd --list
```

Это безопасная базовая проверка. Она должна вывести список алиасов и типов серверов.

### 5. Перезапустить Codex

Если у вас уже была открыта интерактивная Codex session, её нужно перезапустить. Новый skill обычно подхватывается новым процессом Codex, а не уже живой сессией.

## Как проверить, что Codex реально видит skill

Самый надёжный способ:

```bash
codex exec --skip-git-repo-check -s read-only -C /tmp \
  "A user asks: Using the locally installed ServerManager integration, what is the safest first command to enumerate configured servers? Reply with only the command."
```

Если skill подхватился корректно, Codex должен сам прочитать `~/.codex/skills/server-manager/SKILL.md` и ответить:

```bash
$HOME/.server-connections/codex-ssh --list
```

## Что Codex должен делать через skill

Правильный workflow для любой server operation:

1. Сначала `--list`
2. Прочитать колонку `Type`
3. Выбрать команду строго по типу сервера
4. Выполнить ровно одно подключение/одно действие
5. Вернуть результат без IP/логинов/паролей/портов

Безопасные discovery-команды:

```bash
$HOME/.server-connections/codex-ssh --list
$HOME/.server-connections/codex-ssh --info ALIAS
$HOME/.server-connections/codex-ssh --status
```

## Источники истины по интеграции

Если меняется поведение интеграции, проверять нужно в таком порядке:

1. [tools/ssh.py](/home/code/Desktop/CODING/server-manager/tools/ssh.py)
2. [tools/skill-ssh.md](/home/code/Desktop/CODING/server-manager/tools/skill-ssh.md)
3. [core/claude_setup.py](/home/code/Desktop/CODING/server-manager/core/claude_setup.py)
4. [build.py](/home/code/Desktop/CODING/server-manager/build.py)
5. [SKILL.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/SKILL.md)
6. [command-matrix.md](/home/code/Desktop/CODING/server-manager/.codex/skills/server-manager/references/command-matrix.md)

Если меняется семантика `ssh.py`, нужно обновлять и Claude skill, и Codex skill.

## Edge Cases

### 1. `python` alias отсутствует

В этой среде `python` отсутствует, но `ssh.py` имеет shebang `#!/usr/bin/env python3` и executable bit.

Поэтому wrapper вызывает `ssh.py` напрямую:

```bash
~/.server-connections/codex-ssh --list
```

Это намеренно лучше, чем завязка на `python ~/.server-connections/ssh.py`.

### 2. `ssh.py --help` не поддерживается

`ssh.py` не имеет полноценного `--help`. Попытка вызвать `--help` возвращает список доступных alias'ов, а не usage.

Поэтому для безопасной проверки используются:

- `--list`
- `--info ALIAS`
- `--status`

### 3. Skill установлен в repo, но не установлен глобально

Наличие `.codex/skills/server-manager/` внутри репозитория полезно как source of truth, но новый Codex процесс по умолчанию ищет глобальные skills в `~/.codex/skills`.

Если skill есть только в repo:

- документация в проекте будет на месте
- глобальный Codex может его не увидеть

Для надёжности нужен именно глобальный install в `~/.codex/skills/server-manager`.

### 4. Wrapper отсутствует, а skill уже установлен

В этом случае Codex прочитает skill, но не сможет выполнить рекомендуемую команду `$HOME/.server-connections/codex-ssh ...`.

Проверка:

```bash
~/.codex/skills/server-manager/scripts/server-manager-doctor.sh
```

Исправление:

```bash
install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh
```

### 5. Backend отсутствует

Если нет `~/.server-connections/ssh.py` или `encryption.py`, skill бесполезен: он знает workflow, но не имеет локального transport layer.

Исправление:

1. Запустить ServerManager
2. `Setup -> Install Everything`

### 6. Интерактивный Codex уже был запущен до установки skill

Новая интерактивная сессия обычно увидит skill, старая может не увидеть.

Исправление:

- закрыть старую Codex session
- запустить новый процесс `codex`

### 7. `codex exec` не может проверить skill из-за sandbox/network policy

Во время non-interactive проверки Codex может упереться не в skill, а в сетевую политику среды:

- websocket backend заблокирован
- sandbox запрещает соединение

Симптом:

```text
failed to connect to websocket ... Operation not permitted
```

Это не означает, что skill неверный. Это означает, что проверка упёрлась в runtime policy Codex backend.

### 8. Повторная установка поверх существующего skill

GUI installer и `install_codex_skill()` синхронизируют дерево skill поверх существующей директории без полного удаления. Это безопасно для обычных обновлений.

Но при ручном `cp -R` возможен stale state, если какие-то файлы были удалены из repo, а старая глобальная копия осталась.

Полная ручная пересинхронизация нужна только если вы осознанно хотите очистить старые файлы:

1. удалить старую копию осознанно
2. снова скопировать skill целиком

Пример:

```bash
rm -rf ~/.codex/skills/server-manager
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager
```

Делать это только если вы уверены, что хотите полностью пересобрать глобальную копию.

### 9. Изменился `tools/ssh.py`, но глобальная установка осталась старой

Это самый вероятный operational drift.

Что может устареть:

- `~/.server-connections/ssh.py`
- `~/.codex/skills/server-manager/*`
- `~/.server-connections/codex-ssh`

После изменения `tools/ssh.py` или skill docs нужно заново синхронизировать:

```bash
cp tools/ssh.py ~/.server-connections/ssh.py
cp core/encryption.py ~/.server-connections/encryption.py
rm -rf ~/.codex/skills/server-manager
cp -R .codex/skills/server-manager ~/.codex/skills/server-manager
install -m 755 .codex/skills/server-manager/scripts/codex-ssh-wrapper.sh ~/.server-connections/codex-ssh
```

### 10. Windows / macOS / Linux split

Сейчас runtime path intentionally разделён по платформам:

- Linux/macOS: shell wrapper `codex-ssh-wrapper.sh`
- Windows: native wrapper `codex-ssh-wrapper.cmd`

Installer на Windows кладёт wrapper как:

- `~/.server-connections/codex-ssh.cmd`

Installer на Linux/macOS кладёт wrapper как:

- `~/.server-connections/codex-ssh`

Что это закрывает:

- Linux/macOS path без platform-specific разветвления в skill
- запуск через `cmd.exe`
- запуск из PowerShell
- отсутствие bash-зависимости для стандартного Windows deployment path

Ограничение остаётся одно: в текущей среде я прогнал end-to-end smoke только на Linux. macOS и Windows path подготовлены в installer/docs, но не smoke-tested здесь из-за отсутствия соответствующих runner'ов.

### 11. `ssh.py` intentionally не должен читать secrets в контекст AI

Это не баг. Даже если кажется проще открыть `servers.json`, делать этого нельзя.

Skill намеренно запрещает:

- `cat ~/.server-connections/servers.json`
- `cat ~/.server-connections/settings.json`
- `python -c "...read servers.json..."`
- `--list-full`

### 12. fail2ban / anti-bruteforce edge case

Повторные неудачные подключения опасны. Поэтому skill зафиксирован как:

- максимум 1 попытка на действие
- при timeout/ошибке остановиться и сообщить пользователю

Это обязательное правило, а не рекомендация.

## Рекомендуемый Update Workflow

После любых изменений, затрагивающих Codex integration:

1. Обновить исходники в repo:
   - `tools/ssh.py`
   - `.codex/skills/server-manager/*`
   - этот документ
2. Синхронизировать глобальную установку
3. Прогнать doctor
4. Прогнать `~/.server-connections/codex-ssh --list`
5. Прогнать свежий `codex exec` smoke test

## Минимальный Smoke Test

```bash
~/.codex/skills/server-manager/scripts/server-manager-doctor.sh
~/.server-connections/codex-ssh --list
codex exec --skip-git-repo-check -s read-only -C /tmp \
  "A user asks: Using the locally installed ServerManager integration, what is the safest first command to enumerate configured servers? Reply with only the command."
```

## Что ещё желательно автоматизировать позже

Чтобы интеграция стала production-complete, в проект ещё полезно добавить:

1. отдельный smoke test script внутри репозитория для проверки именно Codex integration
2. e2e smoke test на Windows runner
3. e2e smoke test на macOS runner
4. optional PowerShell-native wrapper, если понадобится richer Windows logging