docs(proxy-client): спроектирован самостоятельный установщик

- Зачем:
  - отдельный пакет должен устанавливаться без общего dotfiles и обязательного stow.
- Что:
  - зафиксирована единая раскладка симлинков через stow или ln.
  - отделены файлы пакета от машинного конфига и закрытого профиля.
  - добавлены правила конфликтов, настройки Bash и проверки установки.
- Проверка:
  - git diff --cached --check.

docs/specs/2026-07-15-proxy-client-design.md

@@ -2,7 +2,8 @@
 
 Дата: 2026-07-15
 
-Статус: реализация готова к ручной приёмке; публичное имя уточнено 2026-07-21
+Статус: основная реализация принята вручную; самостоятельный установщик
+спроектирован 2026-07-21, но ещё не реализован
 
 ## Проблема
 
@@ -48,8 +49,9 @@ proxy-переменных совместима с локальным Xray бе
   JSON Xray.
 - Сохранить совместимость Bash-функций с внешним Hiddify.
 - Позволить настраивать машинный `NO_PROXY` без правки файлов репозитория.
-- Поддержать выборочную установку после `git clone`: через stow, ручные
-  симлинки или копирование.
+- Поддержать самостоятельную установку из отдельно скопированного каталога
+  `proxy-client/` без зависимости от общего установщика dotfiles и без
+  обязательного stow.
 
 ## Не входит в объём
 
@@ -89,6 +91,22 @@ Bash нужен только там, где необходимо изменит
 требует кода, но не решает основную боль: безопасный запуск `pclaude` и
 `pcodex` из точечной ссылки Hiddify.
 
+### Доставка отдельного пакета
+
+Рассмотрены четыре способа подключить отдельно скопированный каталог:
+
+- оставить только инструкции для stow и ручных симлинков — просто, но сохраняет
+  легко забываемые шаги;
+- копировать файлы в домашний каталог — не требует сохранять исходный каталог,
+  но усложняет обновления и расходится с моделью dotfiles;
+- требовать stow — даёт привычное управление ссылками, но добавляет
+  необязательную зависимость на удалённых серверах;
+- дать пакету собственный установщик, который использует stow при наличии и
+  создаёт те же симлинки напрямую без него.
+
+Выбран последний вариант. Он сохраняет один результат установки при разном
+составе машины и не требует второй копии обновляемых файлов.
+
 ## Рекомендуемое решение
 
 ### Границы компонентов
@@ -376,15 +394,50 @@ CLI раскладывается как `~/.local/bin/proxy-client`. Машин
 `~/.config/proxy-client/`. Шаблоны не подменяют настоящие пользовательские
 файлы.
 
-В корне этого каталога находится самостоятельный `README.md`. Он является
-основной инструкцией клиента и исключается из раскладки stow. README остаётся
-рядом с кодом при выборочном клонировании или копировании каталога. Корневой
-README репозитория только кратко описывает подсистему и ссылается на него.
+В корне этого каталога находятся самостоятельный `README.md` и пакетный
+`install.sh`. Оба файла относятся к исходному каталогу и исключаются из
+раскладки stow. README остаётся рядом с кодом при выборочном клонировании или
+копировании каталога. Корневой README репозитория только кратко описывает
+подсистему и ссылается на него.
 
-После клонирования репозитория пакет можно подключить отдельно от общего
-`install.sh`. README также должен описывать эквивалентные ручные симлинки и
-копирование файлов. Полный `install.sh` подключает этот же stow-пакет вместе с
-остальными dotfiles и не имеет отдельной реализации.
+Пакетный установщик связывает отдельно скопированный каталог с домашним
+каталогом и не зависит от положения или наличия остальных dotfiles. Если stow
+доступен, установщик использует его; если нет — создаёт тот же набор симлинков
+напрямую. Выбранный механизм явно показывается пользователю, но не меняет
+результат. Исходный каталог должен оставаться на прежнем пути всё время
+использования ссылок.
+
+Установщик управляет только тремя публичными артефактами: CLI, `shell.bash` и
+каталогом шаблонов. Машинный `config` и закрытый `default.url` не входят в
+раскладку stow, никогда не создаются, не заменяются и не связываются
+установщиком. Их наличие в исходном каталоге также не должно расширять набор
+управляемых путей.
+
+Домашние `~/.local/bin` и `~/.config/proxy-client` остаются настоящими
+каталогами. Stow не должен сворачивать их или их родителей в одну ссылку на
+исходное дерево: ссылками становятся только три перечисленных артефакта. Это
+одновременно сохраняет место для машинных файлов и делает результат stow
+совпадающим с прямой раскладкой через `ln -s`.
+
+Перед записью установщик проверяет весь набор назначений. Правильная ссылка на
+текущий исходный каталог считается уже установленной; любой другой файл,
+каталог или симлинк считается конфликтом. При конфликте установщик ничего не
+меняет и сообщает все пути, которые пользователь должен разобрать вручную.
+Принудительной замены и автоматических резервных копий нет.
+
+По умолчанию установщик идемпотентно подключает Bash-модуль в `~/.bashrc` и при
+необходимости добавляет `~/.local/bin` в `PATH`. Уже существующее подключение
+через dotfiles не дублируется. Управляемый блок помечается, повторно не
+добавляется и может быть полностью отключён параметром `--no-shell-setup`.
+
+Установщик не выбирает режим прокси, не создаёт конфигурацию, не читает VLESS,
+не устанавливает Xray и не проверяет сеть. После раскладки он проверяет только
+локальные требования и исправность CLI и Bash-модуля, затем печатает краткую
+подсказку для текущей shell-сессии и направляет пользователя в README за
+настройкой режима. Недоступный прокси не делает установку неуспешной.
+
+Полный корневой `install.sh` продолжает подключать тот же stow-пакет вместе с
+остальными dotfiles и не получает отдельной реализации этой логики.
 
 ## Решения и отклонённые альтернативы
 
@@ -412,6 +465,14 @@ README репозитория только кратко описывает по
   автоматическое распределение портов отложены до появления реальной нужды.
 - Официальный системный установщик отклонён: он требует root и создаёт
   systemd-службы. Пользовательская установка соответствует выбранной модели.
+- Копирование файлов пакета отклонено: оно создаёт отдельные экземпляры,
+  усложняет обновление и нарушает общую с dotfiles модель симлинков.
+- Обязательный stow отклонён как лишняя зависимость. Прямые симлинки дают тот же
+  результат на машине без stow, а автоматический выбор механизма не меняет
+  публичное поведение пакета.
+- Автоматическая настройка режима, установка Xray и проверка сети отклонены для
+  установщика пакета. Эти операции зависят от машины, могут требовать секретов
+  или сети и уже имеют отдельные явные команды и инструкции.
 - Готовые JSON и полный импорт Hiddify отклонены как основной интерфейс: точечная
   VLESS-ссылка проще для пользователя и ограничивает область преобразования.
 
@@ -428,6 +489,15 @@ README репозитория только кратко описывает по
   истинное значение сопровождается предупреждением.
 - Старые дистрибутивы могут иметь Python ниже 3.8. CLI проверяет версию до
   основной работы и сообщает обнаруженную и требуемую версии.
+- Симлинки зависят от постоянного пути исходного каталога. Установщик явно
+  сообщает эту зависимость и при повторном запуске принимает только ссылки на
+  текущий источник.
+- Изменение `~/.bashrc` может конфликтовать с пользовательским способом загрузки
+  оболочки. Установщик распознаёт собственный блок и известное подключение из
+  dotfiles, не дублирует их и предоставляет `--no-shell-setup`.
+- Частичная установка может оставить неоднозначное состояние. Все конфликты
+  назначений проверяются до изменений; проверки охватывают отсутствие новых
+  ссылок и правок shell при отказе.
 - `NO_PROXY` реализуется программами неодинаково. README рекомендует точные IP
   и домены, а CIDR описывает как совместимость best-effort.
 - Разные пользователи делят сетевое пространство имён. Настраиваемый порт и
@@ -463,6 +533,22 @@ README репозитория только кратко описывает по
 - Регрессионные Bash-тесты подтверждают прежнее поведение Hiddify при отсутствии
   машинного конфига, оба регистра proxy-переменных, настраиваемый `NO_PROXY` и
   отсутствие автоматического запроса внешнего IP в `proxy_on`/`proxy_off`.
+- Проверки самостоятельной установки покрывают путь со stow и без него,
+  одинаковый набор итоговых ссылок, запуск не из каталога пакета и каталог с
+  пробелами в пути.
+- В обоих путях домашние каталоги остаются обычными каталогами, а пакетные
+  `README.md` и `install.sh` не появляются в домашнем каталоге через stow.
+- Повторный запуск не меняет уже правильную установку. Конфликт любого
+  назначения обнаруживается до записи; чужие файлы, каталоги и ссылки остаются
+  неизменными.
+- Машинный `config` и закрытый `default.url` не управляются установщиком даже
+  при их наличии в исходном каталоге или домашнем каталоге.
+- Настройка Bash проверяется для нового `~/.bashrc`, уже помеченного блока,
+  подключения из полного dotfiles и режима `--no-shell-setup`. Добавление
+  `~/.local/bin` не дублируется.
+- Локальная проверка установки не обращается к сети и не требует доступного
+  прокси. Неисправный или отсутствующий машинный конфиг не отменяет успешную
+  раскладку пакета.
 - Ручная проверка выполняется минимум на Ubuntu с Python 3.10 и на одной целевой
   удалённой системе. РЕД ОС, Astra Linux и Alt Linux проверяются по мере
   доступности: недоступная среда явно записывается как неподтверждённая, а
@@ -474,7 +560,11 @@ README репозитория только кратко описывает по
 реализацией. Она должна описывать:
 
 - различие внешнего Hiddify и управляемого Xray;
-- выборочная установка через stow, ручные симлинки и копирование;
+- самостоятельный `install.sh`, его автоматический выбор stow или прямых
+  симлинков, требование сохранять исходный каталог и режим
+  `--no-shell-setup`;
+- границу между управляемыми файлами пакета и создаваемыми вручную машинным
+  конфигом и закрытым профилем;
 - создание машинного INI из шаблона и отдельного файла VLESS-ссылки;
 - команды управления, `proxy_on/off`, `pclaude/pcodex`;
 - настройка `NO_PROXY`, ограничения CIDR и диагностика;