docs(scratch): план упрощения proxy-client

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 09:21:39 -04:00
1 parent 205e995f26
commit fb23b031bc
@@ -0,0 +1,64 @@
+# 01. Упростить CLI proxy-client и его Python-тесты
+
+Status: ready-for-agent
+
+Спецификация: `../spec.md` (читать целиком — там список того, что сохраняем).
+
+## Файлы
+
+- `proxy-client/.local/bin/proxy-client`
+- `tests/test_proxy_client.py`, `tests/test_proxy_client_managed.py`
+  (можно слить, переименовать или разнести по-новому — как станет проще)
+- `proxy-client/README.md` — все разделы, **кроме** «Установка» и «Ручное
+  подключение без установщика» (их правит задача 02; при конфликте правки
+  перечитай файл и повтори).
+- `proxy-client/.config/proxy-client/examples/` — если нужно.
+
+Не трогать: `proxy-client/install.sh`, `shell.bash`, shell-тесты.
+
+## Что сделать
+
+Пункты 1–4 и 6 спецификации для CLI. Затем привести тесты к пяти местам
+проверок из спецификации:
+
+- Все проверки разбора ссылки (ALPN, legacy insecure, некорректные ссылки,
+  соответствие полей REALITY/XHTTP, pcs/vcn, extra, шифрование) — табличные
+  тесты `parse_vless`/`build_xray_config`, без запуска процессов.
+- CLI-тесты управляемого Xray: один полный жизненный цикл (start → status/env/
+  run → stop → файлы удалены, права 600/700, секретов нет в выводе), Ctrl+C,
+  SIGKILL супервизора → `stop` добивает Xray, устаревшие файлы после смерти
+  процессов, занятый порт, не-loopback адрес, права профиля (с новой
+  подсказкой), сбой `xray run -test` не оставляет файлов, сбой определения
+  внешнего IP — лишь предупреждение, второй `start` при работающем — отказ.
+  Каждый сценарий — один запуск. Готовность ждать по строке вывода, а не
+  опросом `status` в цикле, если это упрощает.
+- Удалить тесты-пустышки: проверку тестовой подделки сокета, проверку, что
+  поддельный xray отвергает не-JSON, тесты порядка внутренних вызовов, всё,
+  что подменяет функции модуля через `__globals__`. Подделку сокета
+  (`checking_socket_setup`/`run_cli_with_socket_setup` через runpy) заменить
+  настоящим слушающим сокетом на 127.0.0.1 (и закрытым портом для «недоступен»).
+- Тесты удалённых возможностей (ограничения размера, строгий `.dgst`,
+  запрет заглавных букв в хеше, «каталог установки внутри HOME», boot_id,
+  повторный PID, подмена xray_path, способы вызова супервизора и т. п.) уходят
+  вместе с возможностями.
+- Новая подсказка о правах — тест первым (красный → зелёный).
+
+Упрощай и сам код: если функция после правок становится проходной — встрой.
+Сообщения об ошибках — на русском, коротко, с путём к файлу там, где речь о
+файле. Сохраняй совместимость с Python 3.8 (без `match`, `str.removeprefix`,
+`|` в типах и т. п.).
+
+## Готово, когда
+
+- `python3 -m unittest discover -s tests` зелёный; прогон Python-тестов
+  proxy-client заметно быстрее нынешних ~75 с.
+- Если есть `uv`: `uv run --python 3.8 python -m unittest discover -s tests`
+  тоже зелёный.
+- Реальная проверка: сгенерированный конфиг для синтетических ссылок REALITY
+  и XHTTP с шифрованием проходит `xray run -test` (xray 26.3.27 есть в
+  `~/.local/bin/xray`).
+- README описывает текущее поведение, без упоминаний удалённого.
+- Не коммитить: коммиты делает оркестратор.
+
+Отчёт: что удалено из кода и тестов (строки до/после, время прогона до/после),
+какие решения принял сам, что осталось спорным.
@@ -0,0 +1,58 @@
+# 02. Упростить установщик пакета, shell-тесты и запускалку
+
+Status: ready-for-agent
+
+Спецификация: `../spec.md` (читать целиком).
+
+## Файлы
+
+- `proxy-client/install.sh`
+- `proxy-client/.config/proxy-client/shell.bash` — только если упрощение
+  очевидно; поведение `proxy_on`/`proxy_off`/`pclaude`/`pcodex` не меняется.
+- `tests/test_proxy_client_install.sh`, `tests/test_proxy_launchers.sh`,
+  `tests/test_proxy_client_full.sh`
+- `proxy-client/README.md` — только разделы «Установка» и «Ручное подключение
+  без установщика» (остальное правит задача 01; при конфликте правки
+  перечитай файл и повтори).
+
+Не трогать: `proxy-client/.local/bin/proxy-client`, Python-тесты, корневой
+`install.sh` и `tests/test_install.sh` (кроме случая, если они ломаются от
+твоих правок — тогда минимально поправь и сообщи).
+
+## Что сделать
+
+1. Пункт 5 спецификации: `install.sh` ставит три симлинка напрямую (`ln -s`),
+   без Stow и `STOW_IGNORE_PATTERNS`. Повторный запуск — ничего не меняет.
+   Чужие файлы не перезаписывает и перечисляет все конфликты сразу (битая
+   ссылка — тоже конфликт). `~/.local` и `~/.config`, которые сами ссылки,
+   допустимы. Блок в `~/.bashrc` — дописать, если нет маркера;
+   `--no-shell-setup` сохраняется. Машинные `config` и `default.url` никогда
+   не ссылаются из пакета.
+2. Тесты установщика: свежая установка (три ссылки, права, `bash -ic` после
+   установки находит `proxy-client` и `proxy_on`), повторный запуск ничего не
+   меняет, конфликты (включая битую ссылку) без частичной установки, машинные
+   файлы сохраняются, `--no-shell-setup`, родительские каталоги-ссылки
+   работают. Тесты удалённого поведения — удалить.
+3. Тесты функций Bash: вместо переопределения внутренней `_proxy_cli` —
+   поддельный исполняемый файл через `PROXY_CLIENT_BIN` (посмотри, как это
+   сделано в `tests/test_chatgpt_proxy_launcher.sh`). Удалить тест голого
+   `declare -F`, тест «владение перенесено» (охрана давнего рефакторинга) и
+   ловушки `curl`. Сохранить: `proxy_on` применяет переменные, неуспешный
+   `env` не меняет окружение, `proxy_off` чистит восемь переменных,
+   `pclaude`/`pcodex` передают аргументы и код выхода, `.bash_custom`
+   подключает модули.
+4. `tests/test_proxy_client_full.sh` запускает только тесты proxy-client
+   (Python-тесты proxy-client, env_sync, shell-тесты proxy-client). Прогон
+   под Python 3.8 через `uv` — если `uv` есть, иначе предупреждение и пропуск.
+   В README (раздел «Установка» или новый короткий раздел в конце —
+   согласуй с задачей 01 через простоту: одна строка команды) — как запускать.
+
+## Готово, когда
+
+- Все изменённые shell-тесты зелёные; `tests/test_install.sh` тоже зелёный.
+- Тесты не требуют установленного `stow`.
+- `bash -n` и (если есть) `shellcheck` для изменённых скриптов чистые.
+- Не коммитить: коммиты делает оркестратор.
+
+Отчёт: строки до/после, время до/после, принятые самостоятельно решения,
+что осталось спорным.