Метаданные и обновления

module.json

Метаданные описывают модуль для менеджера и обновлятора. Пример локального модуля:

{
    "name": "hello-toolbox",
    "author": "Your name",
    "description": "A minimal module",
    "version": "1.0.0",
    "disableAutoUpdate": true,
    "options": {
        "cliName": "Hello",
        "guiName": "Hello Toolbox",
        "settingsVersion": 1
    }
}

Если задан settingsVersion, добавьте мигратор настроек. Иначе уберите это поле из минимального примера.

Менеджер использует ключи dependencies при загрузке, а обновлятор — URL для установки отсутствующих зависимостей. Для mod.require.library зависимость должна называться library. Локальные переключения загрузки/обновлений могут сохраняться отдельно в module.config.json.

manifest.json

Манифест обновлений содержит files: относительный путь → SHA-256 содержимого. Обновлятор приводит хеши к верхнему регистру перед сравнением, поэтому генератор может записывать их в нижнем. Следующий пример показывает схему: вместо обозначенных строк должны быть настоящие хеши файлов.

{
    "files": {
        "index.js": "SHA256_OF_INDEX_JS",
        "module.json": "SHA256_OF_MODULE_JSON",
        "config-example.json": {
            "hash": "SHA256_OF_CONFIG_EXAMPLE",
            "overwrite": false
        }
    }
}

Строка хеша означает обновление при несовпадении. Объект с overwrite: false устанавливает отсутствующий файл, но сохраняет существующий. Не включайте пользовательский module_settings.json в список перезаписываемых файлов.

Автоматический генератор .manifest.js

Генератор создает manifest.json по файлам модуля: вручную рассчитывать и копировать SHA-256 не нужно. Для запуска нужен Node.js; сторонние npm-пакеты не требуются.

Скачать .manifest.js

1. Сохраните скрипт под именем .manifest.js в корень модуля, рядом с module.json и index.js.
2. Явно укажите путь файла настроек в module.json, как показано ниже.
3. Откройте терминал в папке модуля и запустите команду:

node .manifest.js

Результат — созданный или обновленный manifest.json в той же папке. Скрипт работает относительно своего расположения (__dirname), а не текущего каталога терминала. При каждом выпуске запускайте его после окончательного изменения файлов, перед публикацией.

Защита конфигов от перезаписи

Генератор определяет основной конфиг по options.settingsFile в module.json; если это поле не задано, проверяет старое поле settingsFile верхнего уровня. Используйте современный вариант:

{
    "name": "hello-toolbox",
    "options": {
        "settingsVersion": 1,
        "settingsFile": "module_settings.json"
    }
}

Пример предполагает наличие мигратора настроек и самого файла module_settings.json. Допускается вложенный путь, например config/settings.json; в ключах манифеста разделители нормализуются к /.

Для указанного файла генератор записывает объект:

{
    "overwrite": false,
    "hash": "SHA256_OF_SETTINGS_FILE"
}

hash в настоящем результате содержит рассчитанный SHA-256. Конфиг остается в манифесте: при первой установке отсутствующий файл будет скачан, а существующий пользовательский файл не будет перезаписан.

Автоматическая защита применяется именно к указанному settingsFile, а не ко всем JSON-файлам или всем файлам с именем config. Без явного пути генератор не подставляет module_settings.json, хотя сам Toolbox использует это имя по умолчанию. Если конфиг отсутствует или исключен из обхода, генератор предупреждает об этом и не добавляет новую запись.

Для дополнительных конфигов заранее задайте в manifest.json объект с overwrite: false и полем hash, как в примере выше. При повторном запуске генератор обновит хеш существующего объектного описания, сохранив его остальные параметры. Известный генератору основной settingsFile всегда получает overwrite: false.

Какие файлы попадают в манифест

Скрипт рекурсивно обходит папку модуля и рассчитывает хеши содержимого. Новые обычные файлы записываются как путь → хеш.

Из обхода исключаются:

• manifest.json, manifest-generator.js, manifest-generator.bat, manifest-generator.exe, node.exe;
• файлы и папки, чье имя начинается с . или _, на любом уровне вложенности.

Поэтому .manifest.js, .git и папки вроде _backup не добавляются. Обычные папки, включая node_modules, не имеют отдельного исключения: перед запуском проверьте, что в папке модуля лежат только файлы, предназначенные для распространения.

Существующий корректный manifest.json используется как основа: поля верхнего уровня сохраняются, записи отсутствующих файлов удаляются, хеши найденных файлов пересчитываются. Исключение из обхода само по себе не удаляет старую запись, если файл по-прежнему существует; при изменении состава публикации проверьте такие записи вручную. Если манифест отсутствует или не читается, создается новый объект files. Отсутствующий или некорректный module.json останавливает генерацию с ошибкой.

Публикация обновления

Разместите файлы и манифест по базовому URL из servers; адрес должен позволять дописать manifest.json и относительные пути файлов. Обновлятор перебирает серверы при ошибке. Для выпуска измените файлы, запустите node .manifest.js, проверьте список файлов и защиту конфигов, затем опубликуйте результат. Проверьте чистую установку и обновление существующей копии с измененными пользовательскими настройками. После генерации не редактируйте распространяемые файлы без повторного запуска скрипта: их хеши изменятся. Пользователю может быть достаточно исходного module.json для начальной загрузки остальных файлов.

Описание требуемых пакетов в старых манифестах не заменяет совместимость .def и проверку версий на конкретном сервере. Не отключайте проверку хешей ради исправления неверного манифеста.

Источники: .manifest.js, node_modules/tera-mod-management/index.js, bin/update.js, bin/mod.js.