|
| 1 | +# AGENTS.md — руководство для AI-агентов (OPM) |
| 2 | + |
| 3 | +Документ для агентов, работающих с этим репозиторием. Цель — быстро понять архитектуру, где править код и как проверять изменения. |
| 4 | + |
| 5 | +## Что это за проект |
| 6 | + |
| 7 | +**OPM (OneScript Package Manager)** — менеджер пакетов для [OneScript](https://oscript.io): сборка `.ospx`, установка из хаба/файла/URL, разрешение зависимостей, публикация, scaffold и запуск задач. |
| 8 | + |
| 9 | +- Репозиторий: https://github.com/oscript-library/opm |
| 10 | +- Лицензия: Apache-2.0 |
| 11 | +- Версия продукта: `КонстантыOpm.ВерсияПродукта` (сейчас `1.1.2`) |
| 12 | +- Требуемая среда: OneScript ≥ **1.8.3** (`packagedef`) |
| 13 | +- Хабы: `http://hub.oscript.io`, запасной `http://hub.oscript.ru` |
| 14 | +- Packaging docs: https://hub.oscript.io/packaging |
| 15 | + |
| 16 | +## Стек |
| 17 | + |
| 18 | +| Слой | Технология | |
| 19 | +|------|------------| |
| 20 | +| Язык | OneScript / BSL (`.os`), **русские** идентификаторы | |
| 21 | +| CLI | пакет `cli` | |
| 22 | +| Логи | `logos` (`oscript.app.opm`) | |
| 23 | +| Unit | `1testrunner` | |
| 24 | +| BDD | `1bdd` (Gherkin на русском) | |
| 25 | +| Coverage | `coverage` + `oscript -codestat=` | |
| 26 | +| CI | GitHub Actions + SonarQube (`sonar.openbsl.ru`) | |
| 27 | + |
| 28 | +Runtime-зависимости — в корневом `packagedef`: `fs`, `asserts`, `fluent`, `logos`, `cli`, `tempfiles`, `gitrunner`, `reflector`. |
| 29 | + |
| 30 | +## Структура репозитория |
| 31 | + |
| 32 | +``` |
| 33 | +opm/ |
| 34 | +├── packagedef # манифест пакета OPM |
| 35 | +├── src/ |
| 36 | +│ ├── cmd/ |
| 37 | +│ │ ├── opm.os # точка входа CLI |
| 38 | +│ │ ├── Классы/ # КомандаOpm_*.os, ИсполнительЗадач |
| 39 | +│ │ └── Модули/ # ПараметрыПриложенияOpm |
| 40 | +│ └── core/ |
| 41 | +│ ├── Классы/ # менеджеры, сборщик, установка... |
| 42 | +│ └── Модули/ # КонстантыOpm, РаботаС*, НастройкиOpm |
| 43 | +├── tasks/ # opm run / opm test |
| 44 | +│ ├── test.os # unit + bdd |
| 45 | +│ ├── coverage.os # как в CI |
| 46 | +│ └── oscript.cfg |
| 47 | +├── tests/ # unit-тесты (1testrunner) |
| 48 | +├── features/ # BDD (1bdd) + step_definitions/ |
| 49 | +├── .github/workflows/ # CI / release / rebase |
| 50 | +└── oscript_modules/ # локальные зависимости (vendor, в .gitignore) |
| 51 | +``` |
| 52 | + |
| 53 | +Отдельного каталога `docs/` нет — ориентир: `README.md` и этот файл. |
| 54 | + |
| 55 | +## Архитектура (слои) |
| 56 | + |
| 57 | +``` |
| 58 | +src/cmd/opm.os (cli.КонсольноеПриложение) |
| 59 | + → КомандаOpm_* (ОписаниеКоманды / ВыполнитьКоманду) |
| 60 | + → РаботаСПакетами / СборщикПакета / ИсполнительЗадач / ... |
| 61 | + → МенеджерУстановкиПакетов / МенеджерПолученияПакетов / УстановкаПакета / ... |
| 62 | +``` |
| 63 | + |
| 64 | +### Карта «хочу изменить X» |
| 65 | + |
| 66 | +| Задача | Куда смотреть | |
| 67 | +|--------|----------------| |
| 68 | +| CLI-команда / флаги | `src/cmd/opm.os`, `src/cmd/Классы/КомандаOpm_*.os` | |
| 69 | +| Install / зависимости | `РаботаСПакетами`, `МенеджерУстановкиПакетов`, `УстановкаПакета`, `КэшУстановленныхПакетов` | |
| 70 | +| Скачивание с хаба | `МенеджерПолученияПакетов`, `СерверПакетов`, `КонстантыOpm` | |
| 71 | +| Сборка `.ospx` | `СборщикПакета`, `ОписаниеПакета`, `СериализацияМетаданныхПакета` | |
| 72 | +| Publish | `КомандаOpm_Push` | |
| 73 | +| Версии `Имя@Версия` | `РаботаСВерсиями` | |
| 74 | +| Чтение `packagedef` | `РаботаСОписаниемПакета`, `ОписаниеПакета` | |
| 75 | +| `opm.cfg` / прокси / зеркала | `ПараметрыПриложенияOpm`, `НастройкиOpm` | |
| 76 | +| Версия продукта | `src/core/Модули/КонстантыOpm.os` (+ fallback в `packagedef`) | |
| 77 | + |
| 78 | +### Команды CLI |
| 79 | + |
| 80 | +| Команда | Класс | |
| 81 | +|---------|-------| |
| 82 | +| `a app` | `КомандаOpm_App` | |
| 83 | +| `b build` | `КомандаOpm_Build` | |
| 84 | +| `c config` | `КомандаOpm_Config` | |
| 85 | +| `i install` | `КомандаOpm_Install` | |
| 86 | +| `ls list` | `КомандаOpm_List` | |
| 87 | +| `pre prepare` | `КомандаOpm_Prepare` | |
| 88 | +| `p push` | `КомандаOpm_Push` | |
| 89 | +| `r run` | `КомандаOpm_Run` | |
| 90 | +| `test` | `КомандаOpm_Test` | |
| 91 | +| `u update` | `КомандаOpm_Update` | |
| 92 | +| `version` | `КомандаOpm_Version` | |
| 93 | + |
| 94 | +### Потоки данных (кратко) |
| 95 | + |
| 96 | +**Install:** CLI → `РаботаСПакетами` → download (`МенеджерПолученияПакетов`) → `УстановкаПакета` (unzip `.ospx`) → рекурсивные зависимости → кэш установленных. |
| 97 | + |
| 98 | +**Build:** `СборщикПакета` читает `packagedef` (контекст `Описание` = fluent `ОписаниеПакета`) → hooks → `{Имя}-{Версия}.ospx` = ZIP(`opm-metadata.xml` + `content.zip`). |
| 99 | + |
| 100 | +**Режимы установки:** локально → `./oscript_modules`; глобально → системный `lib` OneScript (`РежимУстановкиПакетов`). |
| 101 | + |
| 102 | +## Окружение и команды |
| 103 | + |
| 104 | +### Подготовка |
| 105 | + |
| 106 | +```powershell |
| 107 | +# Нужен OneScript ≥ 1.8.3 (stable или 1.8.4 как в CI) |
| 108 | +opm install opm |
| 109 | +opm install 1testrunner |
| 110 | +opm install 1bdd |
| 111 | +opm install coverage |
| 112 | +opm install -l --dev |
| 113 | +``` |
| 114 | + |
| 115 | +### Запуск из исходников |
| 116 | + |
| 117 | +```powershell |
| 118 | +oscript src\cmd\opm.os --help |
| 119 | +oscript src\cmd\opm.os version |
| 120 | +oscript src\cmd\opm.os install --local |
| 121 | +oscript src\cmd\opm.os build --mf .\packagedef . |
| 122 | +``` |
| 123 | + |
| 124 | +Отладка: `.vscode/launch.json`, `LOGOS_CONFIG=logger.oscript.app.opm=DEBUG`. |
| 125 | + |
| 126 | +### Тесты |
| 127 | + |
| 128 | +```powershell |
| 129 | +oscript tasks\test.os # unit + bdd |
| 130 | +oscript tasks\coverage.os # как в CI |
| 131 | +opm test # через CLI |
| 132 | +``` |
| 133 | + |
| 134 | +Отчёты: каталог `out/`. |
| 135 | + |
| 136 | +### Типовые CLI-вызовы |
| 137 | + |
| 138 | +```powershell |
| 139 | +opm install asserts |
| 140 | +opm install --local # зависимости packagedef → ./oscript_modules |
| 141 | +opm install --local --dev |
| 142 | +opm install -f my.ospx --local |
| 143 | +opm install Package@1.2.0 |
| 144 | +opm build --mf .\packagedef . |
| 145 | +opm list |
| 146 | +opm list --remote |
| 147 | +opm prepare my-package |
| 148 | +opm update opm |
| 149 | +``` |
| 150 | + |
| 151 | +Полезные переменные: `OSCRIPTBIN`, `OPM_HUB_MIRROR`, `OPM_HUB_CHANNEL`, `GITHUB_OAUTH_TOKEN`, `LOGOS_CONFIG`. |
| 152 | + |
| 153 | +## Соглашения по коду |
| 154 | + |
| 155 | +1. **Русский BSL** — имена процедур, переменных, каталогов `Классы/` / `Модули/`. |
| 156 | +2. Пользовательские строки — через `НСтр("ru='...';en='...')`. |
| 157 | +3. Модули = статический API (`РаботаС*`, `КонстантыOpm`); классы = состояние (`Менеджер*`, `УстановкаПакета`). |
| 158 | +4. Подключения: `#Использовать logos`, `#Использовать "../core"`, `#Использовать cli`. |
| 159 | +5. Публичный API пакета задаётся в `packagedef` через `.ОпределяетКласс` / `.ОпределяетМодуль`. |
| 160 | +6. OneScript подхватывает классы/модули по имени файла из `Классы/` и `Модули/`. |
| 161 | +7. Комментарии — на русском. Не рефакторить стиль «заодно», если задача этого не требует. |
| 162 | + |
| 163 | +### Добавление CLI-команды |
| 164 | + |
| 165 | +1. Создать `src/cmd/Классы/КомандаOpm_Foo.os` по образцу `КомандаOpm_Build.os`: |
| 166 | + - `ОписаниеКоманды(КомандаПриложения)` — опции и аргументы; |
| 167 | + - `ВыполнитьКоманду(КомандаПриложения)` — логика. |
| 168 | +2. Зарегистрировать в `src/cmd/opm.os`: |
| 169 | + `Приложение.ДобавитьКоманду("f foo", НСтр(...), Новый КомандаOpm_Foo);` |
| 170 | +3. При необходимости — unit/BDD и строка в `README.md`. |
| 171 | + |
| 172 | +**Не копировать** `ШаблонКоманды.os-template` — там устаревший cmdline API. Актуальный паттерн — пакет `cli`, как в `КомандаOpm_Build.os`. |
| 173 | + |
| 174 | +### Bump версии OPM |
| 175 | + |
| 176 | +1. `ВерсияПродукта` в `src/core/Модули/КонстантыOpm.os` |
| 177 | +2. Fallback-строка в `packagedef` (`Иначе ВерсияПродукта = "..."`) |
| 178 | +3. Сборка / тесты / release workflow |
| 179 | + |
| 180 | +### Зависимости самого OPM |
| 181 | + |
| 182 | +В корневом `packagedef`: |
| 183 | + |
| 184 | +```bsl |
| 185 | +.ЗависитОт("имя", "min.version") |
| 186 | +.РазработкаЗависитОт("имя", "min.version") |
| 187 | +``` |
| 188 | + |
| 189 | +Затем `opm install -l` / `opm install -l --dev`. |
| 190 | + |
| 191 | +## Тесты: контракт |
| 192 | + |
| 193 | +**Unit** (`tests/*.os`, 1testrunner): |
| 194 | + |
| 195 | +- `ПолучитьСписокТестов(Тестирование)` |
| 196 | +- `ПередЗапускомТеста` / `ПослеЗапускаТеста` |
| 197 | +- методы `ТестДолжен_*` |
| 198 | +- asserts: `#Использовать asserts`, `Ожидаем` |
| 199 | + |
| 200 | +Файлы: `packagedef-test.os`, `versions-test.os`, `mft-serializer-test.os`, `pkg-cache.os`, `packagelist.os`, `download.os`, `build-install-test.os`. |
| 201 | + |
| 202 | +**BDD** (`features/*.feature` + `features/step_definitions/*.os`, `# language: ru`): |
| 203 | + |
| 204 | +- `opm-build.feature`, `install-file.feature`, `Настройки.feature` |
| 205 | + |
| 206 | +При правках логики — добавляй/обновляй ближайший тест в той же области (см. карту выше). |
| 207 | + |
| 208 | +## CI |
| 209 | + |
| 210 | +`.github/workflows/main.yml`: |
| 211 | + |
| 212 | +- матрица: ubuntu / windows / macos × oscript `stable` и `1.8.4` |
| 213 | +- установка deps → `oscript ./tasks/coverage.os` |
| 214 | +- Sonar только на `ubuntu-latest` + `stable` |
| 215 | + |
| 216 | +Release: `.github/workflows/release.yml` (маска `opm-*.ospx`). |
| 217 | + |
| 218 | +Перед PR желательно прогнать `oscript tasks\test.os` (или `coverage.os`). |
| 219 | + |
| 220 | +## Критичные ограничения и ловушки |
| 221 | + |
| 222 | +1. **CLI ≥ 0.15:** опции **до** аргументов. Правильно: `opm build --mf ./packagedef .`. Неправильно: `opm build . -mf ...`. |
| 223 | +2. **Версия продукта** дублируется: `КонстантыOpm` и fallback в `packagedef` — менять согласованно. |
| 224 | +3. Формат `.ospx`: внешний ZIP → `opm-metadata.xml` + `content.zip`; не путать уровни. |
| 225 | +4. Имена пакетов на хабе **регистрозависимы** при скачивании, сравнение имён — нет. |
| 226 | +5. Разрешение зависимостей слабое: для уже установленного пакета фактически проверяется min-версия; max используется ограниченно. |
| 227 | +6. Локальный `-dest` игнорируется при `--local`. |
| 228 | +7. Канал `push` `auto` только из git-ветки **`master`** (не `main`). |
| 229 | +8. Hooks манифеста (`ПередСборкой` / `ПриСборке` / `ПослеСборки`, `ПередУстановкой` / `ПриУстановке`) вызываются через рефлектор — не ломать сигнатуры. |
| 230 | +9. На Linux пользовательский конфиг — **`.opm.cfg`** (с точкой); на Windows — `opm.cfg` в `%USERPROFILE%`. Приоритет: cwd → user → system → каталог opm. |
| 231 | +10. Хабы по умолчанию — **http**, не https. |
| 232 | +11. `oscript_modules` в `.gitignore`, но в `packagedef` есть `.ВключитьФайл("oscript_modules")` (бандл в дистрибутив). |
| 233 | +12. Кириллические пути (`Классы`, `Модули`): на Windows учитывать кодировку консоли при запуске задач. |
0 commit comments