dotfiles/docs/superpowers/specs/2026-05-19-proxy-cli-launchers-design.md

# Дизайн: `pclaude` / `pcodex` — явный запуск claude/codex CLI через прокси

Дата: 2026-05-19
Статус: утверждён (дизайн), ожидает плана реализации

## Проблема

`claude` и `codex` CLI должны ходить в сеть через прокси
(`hproxy.local:12334`). Сейчас это обеспечивается ручным `proxy_on` в текущем
shell — легко забыть, и тогда трафик уходит мимо прокси.

## Цель и подход

Цель — **удобство и best-effort**, а не сетевая гарантия: дать одну явную
команду, после которой не нужно помнить про `proxy_on` и которая не стартует
молча, если прокси недоступен. Это **не** fail-closed изоляция — голые
`claude`/`codex` по-прежнему могут уйти мимо прокси (см. «Известные
ограничения»).

**Проверенное допущение:** `claude` и `codex` уважают
`HTTP(S)_PROXY`/`ALL_PROXY` — подтверждено эмпирически (ежедневная работа в
этом режиме). На этом стоит весь env-подход; spike не требуется.

Ввести **отдельные явные команды** `pclaude` и `pcodex`. Бинарники
`claude`/`codex` не переименовываются и не перекрываются — явное `p`-имя
выражает намерение и исключает риск «где-то нет алиаса → запуск мимо прокси».

Подход — **convenience-обёртка** (не сетевая изоляция):

1. выставить proxy-env только для дочернего процесса (не загрязняя
   родительский shell/сессию);
2. **fail-fast pre-flight**: перед запуском быстро проверить, что
   `hproxy.local:12334` доступен; если нет — **не запускать**, выдать
   понятную ошибку и ненулевой код возврата. Семантика проверки —
   *reachability* (порт прокси открыт), а не доказательство, что трафик
   реально проксируется; последнее покрывается проверенным допущением выше.
   Таймаут вынесен в переменную (`PROXY_PREFLIGHT_TIMEOUT`, дефолт 2 c).

Реализация на двух платформах:

- Linux/WSL bash;
- Windows native PowerShell.

Эндпоинт прокси один и тот же на обеих платформах (`hproxy.local:12334`) и
переиспользуется из уже существующих `proxy_on`.

### Не входит в объём (YAGNI)

- Сетевая изоляция / firewall / network namespace (fail-closed).
- Перекрытие/переименование оригинальных `claude`/`codex`.
- Поддержка не-PowerShell оболочек на Windows (cmd.exe и т.п.).
- Изменение существующего поведения `proxy_on`/`proxy_off`/`myip`.

## Ключевой принцип: единый источник правды

Эндпоинт прокси сейчас захардкожен в `proxy_on` дважды (bash и PS-профиль).
Чтобы `pclaude`/`pcodex` не размножили константы ещё в нескольких местах,
значения выносятся в небольшой внутренний хелпер в каждом файле, и
существующий `proxy_on` рефакторится на этот же хелпер. Это единственный
сопутствующий рефактор, ограниченный задачей.

## Компоненты — Linux

Файл: `bash/.bash_functions` (stow → `~/.bash_functions`, уже подключается
через `~/.bash_custom`). Новых установочных шагов нет.

1. `_proxy_export()` — внутренний. Экспортирует `HTTP_PROXY`, `HTTPS_PROXY`,
   `ALL_PROXY`, `NO_PROXY` (+ lower-case дубли) из единого набора локальных
   переменных. `proxy_on()` рефакторится так, чтобы вызывать `_proxy_export`;
   его эхо и проверка внешнего IP остаются без изменений.
2. `_proxy_reachable()` — TCP-connect к `hproxy.local:12334` с таймаутом
   `${PROXY_PREFLIGHT_TIMEOUT:-2}` c
   (`timeout "$t" bash -c '... >/dev/tcp/hproxy.local/12334'`). Возвращает
   0/1, ничего не печатает. Таймаут покрывает и медленный DNS-резолв
   `hproxy.local` (при зависании резолва — false-negative и отказ запуска,
   что является безопасным направлением отказа).
3. `_proxy_run <cmd> [args…]`:
   - `_proxy_reachable` → при неудаче печатает понятное сообщение
     (рус., стиль существующих `❌`/`✅`), `return 1`, **бинарник не
     запускается**;
   - проверка наличия `<cmd>` в PATH (`command -v`) → при отсутствии
     отдельное понятное сообщение, ненулевой код;
   - запуск в subshell: `( _proxy_export; exec command "<cmd>" "$@" )` —
     proxy-env виден только дочернему процессу, не протекает в родительский
     shell; код возврата пробрасывается.
4. `pclaude() { _proxy_run claude "$@"; }`
   `pcodex()  { _proxy_run codex  "$@"; }`

## Компоненты — Windows

Файл: `chezmoi/dot_config/powershell/profile.ps1` (уже доставляется chezmoi и
подключается через `Microsoft.PowerShell_profile.ps1.tmpl`). Новых
установочных шагов нет.

1. `Set-ProxyEnv` — внутренний. Ставит `HTTP_PROXY`, `HTTPS_PROXY`,
   `ALL_PROXY`, `NO_PROXY` из единого источника. `proxy_on` рефакторится на
   него (его вывод/`Get-PublicIp` не меняются).
2. `Test-ProxyReachable` — `System.Net.Sockets.TcpClient` к
   `hproxy.local:12334` с таймаутом ~2 c. Возвращает `$true`/`$false`.
3. `Invoke-WithProxy -Exe <name> -CmdArgs $args`:
   - pre-flight `Test-ProxyReachable` → при неудаче `Write-Error` + return,
     **не запускать**;
   - проверка `Get-Command <name>` → при отсутствии понятная ошибка;
   - сохранить текущие значения 4 env-переменных; `Set-ProxyEnv`;
     `& $Exe @CmdArgs`; в `finally` восстановить прежние значения env
     (сессия не остаётся с включённым прокси — поведение симметрично
     subshell в bash); пробросить `$LASTEXITCODE`.
4. `function pclaude { Invoke-WithProxy claude @args }`
   `function pcodex  { Invoke-WithProxy codex  @args }`

   **Passthrough аргументов — known footgun PowerShell.** Флаги вида `-p`,
   `--model` могут перехватываться парсером PS как параметры обёртки.
   Требование: `Invoke-WithProxy` объявляет `[Parameter(ValueFromRemainingArguments)]`
   на `$CmdArgs`, обёртки передают `@args` (splatting, не `$args`), внутри —
   `& $Exe @CmdArgs`. Обязательные тест-кейсы при реализации:
   `pclaude -p "..."`, `pclaude --model ...`, `pcodex --help`, аргумент с
   пробелами и с `--`.

## Обработка ошибок

| Ситуация | Поведение |
|---|---|
| Прокси `hproxy.local:12334` недоступен | Понятное сообщение, ненулевой код, **запуск не происходит** |
| `claude`/`codex` нет в PATH | Отдельное понятное сообщение, ненулевой код |
| Аргументы с пробелами/спецсимволами | Сохраняются (`"$@"` / `@args`-splatting) |
| `NO_PROXY` | Берётся существующий список платформы как есть (bash: с `::1`/`[::1]`; PS: без) — существующее поведение не меняется |

## Известные ограничения

Принимаются осознанно (следствие выбранного convenience-подхода):

- **Аддитивность.** Голые `claude`/`codex` остаются доступны и идут мимо
  прокси без предупреждения. Фича снижает вероятность ошибки, но не
  устраняет её — это удобство, не гарантия.
- **TOCTOU.** Pre-flight проверяет доступность только в момент старта.
  Для долгой интерактивной сессии `claude` прокси может упасть позже —
  обёртка этого не отследит.
- **Pre-flight ≠ доказательство проксирования.** Проверяется открытость
  порта, не факт, что инструмент использует прокси (закрыто проверенным
  допущением о поведении claude/codex, не самим preflight).

## Деплой

Ноль новых установочных шагов. Оба целевых файла уже доставляются (stow /
chezmoi) и подключены в shell-профилях. `run_`-скрипты chezmoi не требуются.

## Тестирование

Зеркалит существующий стиль (`tests/test_install.sh` — простой bash +
assert-хелперы, без bats).

Новый `tests/test_proxy_launchers.sh`:

- `_proxy_run` при недоступном прокси не вызывает бинарник и возвращает
  ненулевой код (мок проверки доступности + мок `command`/PATH);
- proxy-env реально выставлены в дочернем процессе и **не** протекают в
  родительский shell;
- проброс кода возврата дочернего процесса;
- аргументы с пробелами и `--` доходят до бинарника без искажений;
- **регресс `proxy_on`**: после рефактора на общий хелпер `proxy_on`
  экспортирует ровно тот же набор переменных (включая lower-case дубли и
  тот же `NO_PROXY`), что и до рефактора — снимок до/после;
- `shellcheck` на `bash/.bash_functions`.

Windows-часть — без авто-тестов (нет CI под Windows). Ручной чеклист в
плане: `pclaude`/`pcodex` запускаются; при остановленном прокси fail-fast
срабатывает; env не остаётся в сессии после выхода (в т.ч. после Ctrl-C —
если `finally` не отработал, прокси остаётся включённым: безопасное
направление отказа); passthrough-кейсы `pclaude -p "..."`,
`pcodex --help`, аргумент с пробелами; `proxy_on`/`proxy_off` после
рефактора ведут себя как прежде.