Пакетный режим объединяет обычные модули Topaz с корнем проекта, зависимостями, lock-файлом и локальными копиями внешних пакетов. Он не добавляет новый синтаксис и не ослабляет правила видимости, циклов и инициализации модулей.
Контракт и компоненты
topaz.toml задаёт имя пакета, версию языка, точку входа и зависимости. topaz.lock фиксирует выбранные версии и данные для проверки содержимого. Локальные зависимости задаются путём, а внешние копируются в vendor/<name>/<version>. Если у команды проверки, запуска или сборки не указан файл, используется точка входа пакета.
Рабочий процесс
init создаёт пакет, add добавляет зависимость, lock обновляет lock-файл, а fetch и vendor сохраняют внешние зависимости локально. Храните topaz.toml и topaz.lock в репозитории и используйте --locked для воспроизводимых сборок.
При запуске topaz lsp редактор должен передать каталог пакета в initialize.rootUri. Если lock-файл действителен, диагностика разрешает локальные модули и зависимости из vendor по тому же графу пакета, что и topaz check; содержимое открытых документов имеет приоритет над сохранёнными файлами.
Текущий Topaz включает topaz init --target web-app|http-service, делает [build].target фактической целью package build и использует строгие целевые таблицы [web] и [service]. Web lifecycle v2 применяет явные capabilities, а service-таблица фиксирует конечные бюджеты listener, запроса, очереди, deadline, журнала и завершения. Неизвестные ключи отклоняются; topaz dev запускает обе прикладные цели только на loopback.
Для файлов приложения объявите разрешённые корни в [capabilities.fs] и запускайте готовый продукт из каталога с его data и выходными каталогами. Нативный исполняемый файл и Python-сборка пакетного режима отсчитывают эти корни от рабочего каталога запуска, поэтому исходный пакет во время выполнения не требуется. Python-сборке нужен Python 3.11 или новее; она работает как обычное CLI-приложение с прямыми stdout/stderr, аргументами, stdin и кодом завершения явной функции main.
Текущая поддержка
Topaz поддерживает создание пакетов, добавление зависимостей, блокировку версий, vendoring, компиляцию пакетов и автономные сборки. Публичный пакет topaz-lang устанавливает подходящий исполняемый файл Topaz для текущей платформы.
Границы и ограничения
Зависимость пакета не даёт дополнительных прав среды и не импортирует синтаксис другого языка. Исходные зависимости Topaz используют topaz.toml, topaz.lock и локально сохранённые файлы; npm-пакет служит только установщиком CLI. Для автономной сборки все зафиксированные зависимости должны находиться локально.
topaz emit --target python остаётся поверхностью для просмотра исходного кода и trace-интеграции. Для приложения с физической файловой системой используйте topaz build --target python в пакетном режиме.
Справочник команд
topaz init --root my-app
topaz add utility@1.2.0 --root my-app
topaz lock --root my-app
topaz vendor --root my-app --from ./registry
topaz check --root my-app --locked
topaz build --root my-app --locked --out-dir ./dist/native
topaz build --target python --root my-app --locked --out-dir ./dist/python