From 66c38f5a60cca1acdc694ccf5f9f09ab7e81f2d1 Mon Sep 17 00:00:00 2001
From: Michael Chus <mike@mchus.pro>
Date: Sun, 1 Mar 2026 17:45:53 +0300
Subject: [PATCH] Add app binary contract

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 rules/patterns/app-binary/contract.md | 117 ++++++++++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 rules/patterns/app-binary/contract.md

diff --git a/rules/patterns/app-binary/contract.md b/rules/patterns/app-binary/contract.md
new file mode 100644
index 0000000..93cec34
--- /dev/null
+++ b/rules/patterns/app-binary/contract.md
@@ -0,0 +1,117 @@
+# Contract: Application Binary
+
+Version: 1.0
+
+## Purpose
+
+Правила сборки, упаковки ресурсов и первого запуска Go-приложений.
+
+---
+
+## Бинарник
+
+Бинарник самодостаточен — все ресурсы встроены через `//go:embed`:
+
+- HTML-шаблоны
+- Статика (JS, CSS, иконки)
+- Шаблон конфиг-файла (`config.template.yaml`)
+- Миграции БД
+
+Никаких внешних папок рядом с бинарником не требуется для запуска.
+
+---
+
+## Конфиг-файл
+
+Создаётся автоматически при первом запуске, если не существует.
+
+### Расположение
+
+| Режим приложения | Путь |
+|---|---|
+| Однопользовательское | `~/.config/<appname>/config.yaml` |
+| Серверное / многопользовательское | `/etc/<appname>/config.yaml` или рядом с бинарником |
+
+Приложение само определяет путь и создаёт директорию если её нет.
+
+### Содержимое
+
+Конфиг хранит:
+
+- Настройки приложения (порт, язык, таймауты, feature flags)
+- Параметры подключения к централизованной СУБД (host, port, user, password, dbname)
+
+Конфиг **не хранит**:
+
+- Данные пользователя
+- Кеш или состояние
+- Что-либо что относится к SQLite (см. ниже)
+
+### Шаблон
+
+Шаблон конфига встроен в бинарник. При создании файла шаблон копируется в целевой путь.
+Шаблон содержит все ключи с комментариями и дефолтными значениями.
+
+```yaml
+# <appname> configuration
+# Generated on first run. Edit as needed.
+
+server:
+  port: 8080
+
+database:
+  host: localhost
+  port: 5432
+  user: ""
+  password: ""
+  dbname: ""
+
+# ... остальные настройки
+```
+
+---
+
+## SQLite (однопользовательский режим)
+
+Если приложение использует локальную SQLite:
+
+- Файл хранится рядом с конфигом: `~/.config/<appname>/<appname>.db`
+- Путь к файлу не выносится в конфиг — приложение вычисляет его из пути конфига
+- SQLite **не хранит** параметры подключения к централизованной СУБД — только локальные данные приложения
+
+---
+
+## Первый запуск — алгоритм
+
+```
+Старт приложения
+│
+├── Конфиг существует? → Нет → создать директорию → скопировать шаблон → сообщить пользователю путь
+│                                                                        → завершить с кодом 0
+│                                                                          (пользователь заполняет конфиг)
+└── Конфиг существует? → Да → валидировать → запустить приложение
+```
+
+При первом создании конфига приложение **не запускается** — выводит сообщение:
+
+```
+Config created: ~/.config/<appname>/config.yaml
+Edit the file and restart the application.
+```
+
+---
+
+## Сборка
+
+Финальный бинарник собирается без CGO если это возможно (для SQLite — с CGO):
+
+```
+CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/<appname> ./cmd/<appname>
+```
+
+С SQLite:
+```
+CGO_ENABLED=1 go build -ldflags="-s -w" -o bin/<appname> ./cmd/<appname>
+```
+
+Бинарник не зависит от рабочей директории запуска.