StrixScripts/AGENTS.md

AGENTS.md — StrixScripts

Инструкции за AI coding агенти (Claude Code, GitHub Copilot, Cursor и др.), работещи в този repo. Ако инструментът ти чете CLAUDE.md вместо този файл — CLAUDE.md е кратък pointer към този документ; съдържанието не се дублира умишлено, за да не се разсинхронизира.

Какво е проектът

Колекция от самостоятелни bash скриптове, организирани по функционални папки. Всеки скрипт решава една конкретна задача и има собствена .md документация до себе си.

Задължителна структура при всеки нов скрипт

Когато създаваш нов скрипт, следните стъпки са ЗАДЪЛЖИТЕЛНИ, не опционални — пропускането на която и да е от тях е непълна задача, не "готово с TODO":

1. Скриптът и неговият .md файл имат еднакво basename, в една и съща папка: deploy/restart-nginx.sh → deploy/restart-nginx.md. Виж templates/script-template.md за структурата, която .md файлът трябва да следва.

2. Скриптът source-ва lib/common.sh и извиква common::show_help_if_requested "$@" веднага след дефиниране на SCRIPT_HELP heredoc-а, преди какъвто и да е друг argument parsing. Виж templates/script-template.sh за точния pattern и examples/hello-world.sh за работещ пример.

3. --help (и -h) работи и показва пълна информация — какво прави скриптът, какви опции приема, поне един пример за извикване. Това е съдържанието на SCRIPT_HELP, не отделна имплементация — не пиши ръчен if [[ "$1" == "--help" ]] в скрипта, common.sh вече го прави.

4. В README.md (корена на проекта) се добавя ред в секцията на съответната категория папка — кратко описание (едно изречение) + relative link към .md файла на скрипта. Пълното описание живее само в скрипт-специфичния .md, README не го дублира.

5. В началото се проверяват всички задължителни команди и програми. След common::show_help_if_requested "$@" и преди основната работа извикай common::require_cmd за всяка външна команда, без която скриптът не може да изпълни предназначението си. При липсваща команда helper-ът извежда разбираемо съобщение и прекратява изпълнението. Незадължителните команди се проверяват условно и трябва да имат fallback или описано ограничено поведение; липсата им не бива да спира скрипта без причина. Изброй задължителните и незадължителните зависимости в съответния .md.

6. Скриптът минава shellcheck без warnings (виж .shellcheckrc в корена). Ако warning-ът е false positive, добави # shellcheck disable=SCxxxx с коментар защо точно на реда, не глобално в файла.

7. set -euo pipefail в началото на всеки скрипт, веднага след shebang реда и коментарния блок. Без изключения — ако скрипт умишлено трябва да продължи след грешка в конкретна команда, обгради само тази команда с || true или явна проверка, не маха global set -e.

Конвенции за именуване и стил

• Файлови имена: kebab-case, описателни глагол+обект (backup-nextcloud.sh, не backup.sh или script1.sh).
• Категория папки: функционална група (напр. backup/, network/, deploy/) — създавай нова папка само когато скриптовете вътре наистина споделят функционален домейн, не по проект или по дата.
• Всички коментари в кода — само на английски, независимо от езика на разговора с агента. .md документацията и README.md могат да остават на български — те са за човека, не за компилатора/shellcheck.
• Грешки: винаги през common::die "message", никога суров echo ... >&2; exit 1 — за консистентен формат на грешките между скриптове.
• Статус/progress съобщения: през common::log, който пише на stderr, за да остане stdout чист за реален output, който може да бъде pipe-нат или captured от друг скрипт/потребител.

lib/common.sh — НЕ дублирай логика от него

Ако скрипт се нуждае от поведение, което common.sh не предоставя (напр. retry logic, temp file cleanup trap, конкретен validation helper) — разшири common.sh, не пиши локална версия вътре в отделния скрипт. Целта е всеки скрипт да остава кратък и всички споделят едно и също поведение за грешки/help/logging.

examples/ и templates/ — само референция

examples/hello-world.sh е работещ демонстрационен скрипт, показващ пълната конвенция накратко. templates/ съдържа празни шаблони за копиране. Нито едната папка не съдържа реални production скриптове — не ги викай от други скриптове или automation, и не добавяй реални utility скриптове там.

Статус

Проектът е в начален етап — само structural скелет (lib/common.sh, templates/, examples/hello-world.sh) съществува. Реални функционални категории папки и скриптове предстои да бъдат създадени.