docs: описать разделение тулкита, MAME и приложений

docs/project-reorganization.md

@@ -0,0 +1,251 @@
+# Разделение Sprinter-CC, MAME и приложений
+
+Статус: план, без переноса файлов. Дата: 2026-09-15.
+
+## Цель и границы
+
+Тулкит, эмулятор, примеры и реальные приложения должны разрабатываться и
+версионироваться независимо. Приложение собирается из собственного клона,
+если ему указан только путь к установленному Sprinter-CC. Для запуска в
+эмуляторе дополнительно указывается путь к подготовленной среде MAME либо
+необходимые отдельные пути. Ни соседний репозиторий Examples, ни исходники
+MAME приложению не нужны.
+
+Предлагаемая раскладка на машине разработчика:
+
+```text
+~/Projects/DIY/Z80/Sprinter/
+├── C-Compiler/                  # Sprinter-CC
+├── MAME/                        # fork MAME, сборки и локальная среда запуска
+├── Examples/                    # один Git-репозиторий примеров
+├── Applications/                # каталог без собственного Git
+│   ├── SprPoP/                  # самостоятельный Git-репозиторий
+│   ├── Volkov/                  # самостоятельный Git-репозиторий
+│   └── PoP-Archive/             # архивный проект, если история нужна отдельно
+└── VSCode-Sprinter/             # Git-репозиторий расширения VS Code
+```
+
+Имена `C-Compiler`, `Volkov` и `PoP-Archive` здесь рабочие; адреса Git remote
+новых репозиториев и окончательные имена фиксируются до миграции. Папка
+`Applications/` не становится общим репозиторием: каждый продукт имеет свою
+историю, релизы, игнорируемые ресурсы и тесты. Физическое расположение рядом
+удобно, но не входит в контракт сборки.
+
+## Что принадлежит каждому проекту
+
+| Проект | Что остаётся/переходит | Причина |
+|---|---|---|
+| Sprinter-CC | `bin/`, `runtime/`, `libc/`, `libbgi/`, `lib/`, общие `toolchain/`, `tests/`, `testkit/`, `app.mk`, справочник API, платформенные исследования, `release_docs/`, рецепт SDCC в `third_party/` | Это target SDK, его ABI, инструменты и собственные регрессионные тесты. libc/libbgi пока остаются вместе: их версия и ABI тесно связаны с `sprinter-cc`; дальнейшее выделение возможно после стабильного интерфейса. |
+| MAME | Нынешний `mame/sources/MAME` со своим Git, изменения драйвера/OSD, патч debugger backend, общие `mamebridge` и `mame_mcp.py`, рецепты stock/sdbg сборок | Изменения ядра и общий транспорт MCP должны проверяться и выпускаться вместе с конкретной ревизией MAME. |
+| Examples | Нынешние `examples/balls`, `mdview`, `mdview2`, `rpgwalk`, `scroll`, `space` и относящиеся к ним ресурсы/документы | Это демонстрации SDK с общей версией. Один репозиторий избегает множества мелких релизов. |
+| SprPoP | Всё `applications/SprPoP/`: исходники, конверторы, тесты, собственные ресурсы и планы | Уже почти автономное приложение; оригинальные ресурсы и дальше остаются внешними. |
+| Volkov | Всё `applications/Volkov/`: исходники, сценарии MAME, собственные тестовые носители и документы | Продукт и его проверки должны развиваться без дерева тулкита. |
+| PoP-Archive | `applications/PoP/` как архив прежних PoC/roomtest и исследований | Не смешивать прежнюю историю с активным SprPoP. Если архив не нужен как рабочий клон, сохранить Git-историю и документы в отдельном архивном репозитории. |
+| VSCode-Sprinter | Нынешний `toolchain/vscode-sprinter-debug`: extension, задачи сборки, конфигурации и тесты клиентской части | У расширения свои версии, упаковка VSIX и цикл обновления. Отладочный Python backend остаётся в SDK. |
+
+`applications/DN/DosNavigator` и вложенные чужие клоны в PoP/Volkov —
+референсы, не Sprinter-приложения. Их не превращать в продуктовые репозитории
+и не коммитить вместе с портами. Локально их можно хранить в `References/`
+или получать по воспроизводимой инструкции с указанием upstream и revision.
+`docs/sources/`, `docs/extra/` и скачанный SDCC также не являются новым
+проектом: это игнорируемые справочные/загруженные материалы. Отдельно
+проверить, какие tracked файлы `third_party/16x16-RPG-characters` нужны
+`rpgwalk` и старому PoP; каждый потребитель получает собственный ресурс или
+явный рецепт его загрузки. Лицензии и происхождение сохранить.
+
+## Контракт сборки и запуска приложения
+
+`SPRINTER_ROOT` указывает на готовый Sprinter-CC. Это единственный внешний
+путь, обязательный для сборки `.exe`, host-тестов и собственных генераторов
+ресурсов. В `app.mk` убрать вывод MAME из `PROJ_ROOT`; оставить
+совместимый alias `PROJ_ROOT := $(SPRINTER_ROOT)` там, где это необходимо на
+переходный период. Приложения проверяют, что по пути существуют
+`bin/sprinter-cc`, `app.mk` и нужные библиотеки, и сообщают ошибку до начала
+сборки. При отсутствии `SPRINTER_ROOT` не угадывать прежнее `../..`: после
+переноса такой путь может случайно указывать на чужой каталог.
+
+`MAME_HOME` — необязательный для сборки путь к подготовленной **среде запуска**
+MAME, а не к его исходникам. Стандартные пути соответствуют нынешнему
+`mame/v306` и допускают переопределение из окружения, аргументов `make` или
+локального игнорируемого файла настроек. Если `MAME_HOME` не задан,
+необходимые пути можно указать отдельно; отсутствие обоих источников
+диагностировать в цели запуска, не превращая пустое значение в `/mame.arm`:
+
+```make
+MAME_BIN              ?= $(MAME_HOME)/mame.arm
+MAME_ROMPATH          ?= $(MAME_HOME)/roms
+MAME_DSS_IMAGE        ?= $(MAME_HOME)/IMG/dss171u.img
+MAME_SYSTEM_HDD_IMAGE ?= $(MAME_HOME)/IMG/sp_hdd_sys.chd
+MAME_BIOS             ?= v3.06
+```
+
+`MAME_BIOS` — имя варианта для аргумента `-bios`; ROM-файлы MAME ищет в
+`MAME_ROMPATH`. `MAME_SYSTEM_HDD_IMAGE` добавлен потому, что системный CHD
+нужен существующим сценариям. Если используется CD, NeoGS или второй
+системный носитель, пути к ним сделать отдельными необязательными настройками
+профиля запуска; не прибивать их к Makefile каждого приложения. Уточнить по
+фактическим сценариям, когда нужен `MAME_DSS_IMAGE`: обычный `run`, тест и
+DAP-launch должны брать один источник настройки, даже если конкретный профиль
+не монтирует DSS-дискету.
+
+`MAME_HOME/mame.arm` — стандартный установленный бинарник, а stock/sdbg
+сборки находятся отдельно и выбираются явным `MAME_BIN`. Сборка одного
+варианта не перезаписывает другой и не меняет молча активный бинарник.
+Для запуска с нетипичной установкой можно переопределить каждый путь, не
+копируя ROM/CHD в каталог приложения. Все цели запуска валидируют свои
+фактически используемые файлы и выводят проверенный путь в диагностике.
+
+Собственный `.img`/`.chd`, результаты сценариев, снимки, Lua-скрипты и
+журнал приложения лежат в его `build/` (или другом локальном выходном
+каталоге). MAME получает готовый образ аргументом `-flop1`/`-hard2`. Общие
+`IMG/mc.img` и `IMG/test_hdd.chd` больше не являются выходами сборки
+приложения. `make hdd` готовит локальный образ; `make run` запускает его
+без `mame-link`. Для нескольких сценариев создавать отдельные носители и
+state-каталоги, чтобы параллельный запуск не перезаписывал чужой тест.
+Конфигурация разработчика не содержит абсолютных личных путей в Git.
+Для `.img` нужен упаковщик из SDK; для `.chd` нынешний `make_hdd.sh`
+дополнительно использует внешние `mtools` и `chdman`. Зафиксировать эти
+host-зависимости и проверять их перед упаковкой. `chdman` можно находить
+через `PATH` либо переопределяемый `CHDMAN_BIN`; путь к исходникам MAME или
+полная установка эмулятора для самой сборки `.exe` не нужны.
+
+Временное состояние MAME (`cfg`, `nvram`, `diff`, `snapshot`, IPC) создаётся
+в отдельном каталоге сессии. Обычный запуск, автотест и DAP используют одну
+функцию/профиль разрешения путей, но разные режимы жизненного цикла и
+разные локальные диски. Не требовать закрывать все чужие процессы MAME по
+общему шаблону: предотвращать конфликт только за конкретный изменяемый
+носитель/IPC-сеанс. Закрытие MAME не должно терять лог и снимки теста.
+
+## Граница MAME и отладки
+
+В репозитории MAME держать точную базовую ревизию fork, stock сборку и
+патченный `sdbg` backend как явную ветку/патч с рецептом сборки. Локальный
+checkout уже имеет отдельный `.git` и remote
+`https://git.snark13.com/snark13/MAME.git`; переносить его как источник,
+не копировать `.git` внутрь нового репозитория тулкита. ROM, DSS, CHD,
+скачанные assets, исполняемые файлы и пользовательский state игнорировать.
+Инструкция установки создаёт стандартный `MAME_HOME`; она проверяет
+наличие/версию файлов, но не распространяет их через Git без отдельной
+проверки лицензий и источника.
+
+В Sprinter-CC остаются `--src-debug`, C/asm-карта, debug package,
+`toolchain/sdbg*`, Python DAP, launcher и Sprinter-специфичный плагин
+`sdbgbridge`. Приложение знает только debug build и свои файлы. Launcher
+принимает `MAME_HOME` и все переопределяемые пути из общего профиля;
+`-pluginspath`, IPC, ожидание DSS, установка точек и `sdbg` протокол — его
+внутренняя работа. Сочетание с родным окном MAME остаётся опцией:
+`osx` на macOS, `qt`/`imgui` на Linux по возможностям сборки. Stock MAME
+можно выбрать для поддержанного штатного backend; режим `sdbg` требует
+соответствующей патченной сборки и должен проверять её до запуска.
+Native Windows launch/attach пока не обещать: текущий host transport зависит
+от Unix sockets/`fcntl` и не прошёл полный Windows сценарий.
+
+Общий `mamebridge` и `mame_mcp.py` остаются с fork MAME, пока используются
+как общие инструменты MAME. Sprinter-специфичному `sdbgbridge` отдельный Git
+репозиторий сейчас не нужен: он версионируется с DAP-протоколом в SDK и
+загружается через `-pluginspath`. Текущий `toolchain/run-mame-mcp.sh` и
+`.codex/config.toml` убрать от предположения `mame/sources/MAME` внутри
+тулкита; для общего MCP использовать путь к установленному MCP-серверу
+MAME, а для Sprinter C-уровня — DAP/session server SDK. Зафиксировать версию
+протокола bridge и совместимость SDK ↔ MAME; несовпадение показывать как
+ошибку, а не как зависание отладки.
+
+Репозиторий VSCode-Sprinter содержит только extension и клиентские тесты.
+По умолчанию он обнаруживает DAP-инструмент из `SPRINTER_ROOT` либо получает
+явную настройку пути; не ищет `toolchain/sdbg_dap.py` в открытом workspace.
+Build task выполняет `make SRC_DEBUG=1 SPRINTER_ROOT=...` в каталоге
+приложения, F5 передаёт debug package, MAME-профиль и собственные data файлы
+адаптеру SDK. Поиск проектов не должен зависеть только от буквального
+`include $(PROJ_ROOT)/app.mk`: определить простой стабильный признак проекта
+или явный каталог в `launch.json`. Версии VSIX, SDK и поддержанной ревизии
+MAME документируются вместе; extension не копирует Python backend.
+
+## Известные связи, которые нужно заменить
+
+| Сейчас | Замена и причина |
+|---|---|
+| Корневые `Makefile` и `app.mk` собирают examples/MAME и пишут общую floppy/HDD под `mame/v306` | В SDK оставить `make`/`size-check`/собственные тесты; упаковщик принимает выходной путь и MAME-профиль. Примеры собираются в Examples, MAME — в MAME. Удаление корневых целей без замены лишило бы пользователя привычного run: документировать новые команды и при необходимости оставить переходные targets с явной подсказкой. |
+| `make host-tests` SDK запускает `applications/SprPoP/tests/host` | Тесты игры вызываются из SprPoP по `SPRINTER_ROOT`; SDK тестирует только SDK. При этом общий `testkit` остаётся SDK. |
+| SprPoP `mame-link` меняет `MAME_HOME/IMG/test_hdd.chd` | `make run` передаёт `build/hdd/sprpop.chd` как `-hard2`; состояние установки MAME не меняется. |
+| Volkov `hdd-p5-viewer` собирает `examples/mdview2` | Перенести внутрь Volkov небольшой viewer fixture либо зафиксированный тестовый EXE/исходник с лицензией. Предпочтение — локальный fixture, потому что тест проверяет запуск дочерней программы, а не функциональность mdview2. Проверить, какие свойства реального viewer обязательны, перед заменой. |
+| Volkov `tests/run_mame_hdd.sh` и другие сценарии считают MAME `../../mame/v306` | Принять общие переменные MAME и локальный образ, не менять сценарные Lua-файлы без необходимости. |
+| PoP `roomtest`, `bgtest`, `poc` ищут собственные `toolchain/` и `SDLPoP` через корень SDK | Ввести `POP_ROOT`/`APP_ROOT` внутри PoP и локальные пути к референсам; общие SDK-инструменты оставить по `SPRINTER_ROOT`. Не переносить чужие источники и оригинальные игровые данные в Git. |
+| Examples Makefiles и `rpgwalk/conv_sprites.py` рассчитаны на `../..` и тулкитский `third_party/` | Подключать SDK по `SPRINTER_ROOT`, resource fixture держать рядом с примером либо получать по зафиксированному рецепту. |
+| `toolchain/mame_interactive.py`, `tests/sdbg/run_mame_probe.py`, `sdbg_launcher.py` выводят MAME из `PROJECT_ROOT` | Ввести общий профиль путей, локальные образы и явные аргументы; offline `sdbg-tests` не должен требовать MAME. |
+| `toolchain/make_release.sh` включает `examples/` в архив SDK, а README описывает общий диск | Выпускать Examples отдельно либо собирать составной release по зафиксированной версии Examples; сначала определить контракт релиза, затем изменить архив и обе документации. |
+| Исследовательские docs и код библиотек ссылаются на `applications/PoP/...` и `mame/sources/...` | Сохранять контекст исследования, но заменять рабочие инструкции и относительные ссылки ссылками на соответствующий репозиторий/revision. Архивные наблюдения не удалять. |
+
+## История Git, внешние ресурсы и совместимость
+
+До выделения репозиториев инвентаризировать незакоммиченные/неотслеживаемые
+файлы в корне и отдельный dirty checkout MAME. Среди новых файлов сейчас
+находятся DAP, extension, MCP-плагин, MAME patch и документы: простое
+`git subtree split` по старому HEAD их потеряет. Сначала сохранить работу
+в подходящих коммитах/ветках или проверенных патчах; не сбрасывать и не
+перезаписывать пользовательские изменения. Затем выделить историю
+`examples/`, `applications/SprPoP/`, `applications/Volkov/` и PoP через
+`git subtree split` либо `git filter-repo`, проверяя состав каждого нового
+Git дерева. Для MAME использовать его существующую историю, а не историю
+родительского SDK, где `mame/` игнорируется.
+
+Новый `.gitignore` каждого проекта покрывает собственные `.exe`, объекты,
+debug packages, носители, снимки, внешние источники и секреты локального
+конфига. Не переносить автоматически вложенные сторонние `.git` как gitlinks
+или submodules. Для ресурсов, которые не входят в Git, указать источник,
+контрольную сумму/revision и способ восстановления; релиз и CI не должны
+молча зависеть от файлов конкретной машины. Если приложению нужен SDK с
+определённым ABI, фиксировать поддерживаемый релиз/commit SDK в его README
+или manifest, не пытаться угадывать его по соседнему каталогу.
+
+Во время перехода обеспечить минимальный период совместимости старой
+структуры: сначала добавить переменные и альтернативные пути, проверить
+старые вызовы, затем переносить деревья. После миграции убрать fallback на
+старые относительные пути и диагностировать устаревшие команды. Это не
+должно оставлять два параллельных способа записи в общий носитель.
+
+## Порядок работ и критерии готовности
+
+1. **Зафиксировать текущую базу.** Список tracked/untracked файлов,
+   отдельный Git MAME, лицензии/внешние ресурсы, базовые результаты сборок
+   и smoke-тестов. Сохранить незавершённую отладочную и прикладную работу.
+   Критерий: никакой исходник не теряется при выделении истории.
+2. **Стабилизировать контракт SDK.** В `app.mk` разделить build и run,
+   реализовать `SPRINTER_ROOT`, `MAME_HOME` и переопределения, упаковку
+   локального образа с проверкой `mtools`/`chdman`, общий профиль путей
+   и диагностику отсутствующих файлов. Перевести автотесты/launcher без
+   переноса дерева.
+   Критерий: приложение собирается без MAME и запускается с нестандартным
+   `MAME_BIN`/ROM/DSS/System HDD.
+3. **Подготовить MAME отдельно.** Сохранить fork с точной baseline-revision,
+   stock/sdbg сборки и проверенным способом подготовки `MAME_HOME`.
+   Перенести MAME patch/общий MCP к их владельцу, проверить обоих провайдеров.
+   Критерий: два бинарника существуют одновременно, ROM/CHD и state не
+   коммитятся, patched DAP launch проверен.
+4. **Выделить Examples.** Переписать относительные пути и источник RPG
+   графики, определить формат релиза SDK+Examples. Критерий: каждый пример
+   собирается из собственного клона Examples при одном `SPRINTER_ROOT`,
+   локальные диски не затрагивают MAME или соседние проекты.
+5. **Выделить приложения по одному.** Сначала SprPoP как наиболее близкий
+   к автономному контракту, затем Volkov с локальным viewer fixture, затем
+   архив PoP с его референсами. Переписать тесты и run-скрипты, сохраняя
+   их документы и историю. Критерий: каждый продукт собирается и проходит
+   доступные host/MAME проверки из изолированного клона без Examples и
+   других приложений.
+6. **Выделить extension.** Научить VS Code находить SDK DAP независимо от
+   workspace, запускать build/run/debug приложения и показывать ошибки
+   разрешения путей/версий. Проверить VSIX в отдельном workspace SprPoP
+   или Volkov, а не только в `C-Compiler`. Критерий: F5 строит debug package,
+   ждёт DSS, доходит до `main`, принимает breakpoint/logpoint и клавиатуру;
+   опция родного окна MAME работает на macOS. Windows остаётся явно
+   ограниченной до отдельной реализации host transport.
+7. **Очистить SDK и документы.** Заменить корневые цели, release-скрипт,
+   README, `AGENTS.md`, инструкции автотеста/отладки и рабочие ссылки.
+   Проверить `make`, `make -C libc`, `make -C libbgi`, `make size-check`,
+   SDK host/sdbg tests и отдельные проекты. Критерий: в SDK нет tracked
+   приложений/примеров и игнорируемого вложенного MAME; инструкции используют
+   новые пути, а архивные исследования остаются доступны.
+
+Каждый этап заканчивается проверкой в отдельном клоне и просмотром Git diff,
+а не одним успешным запуском в старом общем дереве. Реальные переносы,
+новые Git remote и публикация релизов выполняются отдельной задачей после
+согласования этого плана.