ose-plugin 0.1.0 → 0.1.2

package/README.md

@@ -7,9 +7,10 @@
 
 | Файл | Зачем |
 |---|---|
-| `bin/ose-plugin.mjs` | единая команда `npx ose-plugin create` / `npx ose-plugin check` |
+| `bin/ose-plugin.mjs` | единая команда `npx ose-plugin create` / `check` / `pack` |
 | `create.mjs` | создаёт рабочий пакет виджета или темы |
 | `validate.mjs` | проверяет пакет по тем же правилам, что `src-tauri/src/plugins.rs` |
+| `pack.mjs` | собирает пакет в zip для установки из панели |
 | `index.d.ts` | типы `window.OSE`, `BaseWidget`, событий и манифестов |
 | `schema/` | JSON-схемы `widget.json` и `theme.json` для редактора |
 | `templates/` | то, из чего `create` собирает пакет |
@@ -32,10 +33,13 @@ npx ose-plugin create plain --theme --name "Plain"
 # проверить готовый пакет или весь каталог
 npx ose-plugin check hello
 npx ose-plugin check config/plugins
+
+# собрать архив для установки из панели
+npx ose-plugin pack hello
 ```
 
-В репозитории OSE то же самое без сети: `node sdk/create.mjs` и
-`node sdk/validate.mjs`.
+В репозитории OSE то же самое без сети: `node sdk/create.mjs`,
+`node sdk/validate.mjs` и `node sdk/pack.mjs`.
 
 ### Команды
 
@@ -58,16 +62,30 @@ npx ose-plugin check config/plugins
 
 Код возврата `1` — есть ошибки; предупреждения его не меняют.
 
-Пакет сразу рабочий: скопируйте папку в каталог пакетов, перезапустите OSE и
-добавьте карточку из библиотеки.
+`ose-plugin pack <папка>`:
+
+| Параметр | Что делает |
+|---|---|
+| `<папка>` | папка готового пакета; сначала прогоняется та же проверка, что у `check` |
+| `--out <файл>` | куда положить архив; по умолчанию `<id>.zip` в текущем каталоге |
+
+В архив не попадают `node_modules`, `.git` и служебные файлы Finder и Windows.
+Манифест лежит в корне архива.
+
+Пакет сразу рабочий: скопируйте папку в каталог пакетов или поставьте архив
+через «Настройки → Пакеты» → «Установить из ZIP», обновите страницу панели
+(или источник в OBS) и добавьте карточку из библиотеки.
 
 - разработка (`npm run tauri:dev`) — `config/plugins/<id>/`;
 - установленное приложение — каталог данных `com.openstreamenvironment.app`
   (Windows: `%APPDATA%\com.openstreamenvironment.app\plugins\`).
 
-Манифесты читаются при старте, поэтому после правки `widget.json`/`theme.json`
-приложение нужно перезапустить. Код и CSS сервер отдаёт с диска — здесь хватает
-обновить источник в OBS или переоткрыть превью.
+Манифесты перечитываются, когда панель или оверлей запрашивают `/api/plugins`
+при загрузке страницы. После установки или правки `widget.json`/`theme.json`
+перезапуск приложения не нужен: панель при возврате фокуса заметит новый список
+и сама перезагрузит страницу; источник в OBS обновите вручную — оверлей не
+трогаем, чтобы не рвать эфир. Код и CSS сервер отдаёт с диска, поэтому правки
+видны сразу после обновления.
 
 ## Виджет
 
@@ -282,8 +300,8 @@ npx ose-plugin check <папка> --json # для скриптов и CI
 
 ## Если пакет не появился
 
-- Манифесты читаются при старте: перезапустите OSE после установки или правки
-  `widget.json`/`theme.json`.
+- Обновите страницу панели или источник в OBS: панель замечает новый список
+  при возврате фокуса и перезагружается сама; оверлей обновляют вручную.
 - Папка должна называться так же, как `id`, и лежать в каталоге пакетов; в ней
   ровно один манифест — `widget.json` **или** `theme.json`.
 - Ошибки загрузки пишутся в терминал приложения (`[ose] пакет <id>: …`) и
@@ -313,3 +331,12 @@ npm publish
 Версию поднимайте в `sdk/package.json` (semver), после — коммит в репозиторий.
 Версия SDK не связана с версией приложения: контракт пакетов держится на
 `apiVersion: 1`, а не на номере npm-пакета.
+
+Имя пакета и имя команды в `bin` должны совпадать: `npx` первым словом ищет
+пакет, поэтому `npx ose-plugin` сработает только у пакета `ose-plugin`. Если на
+аккаунте включена 2FA, публикуйте с `--otp=<код>` или automation-токеном —
+иначе npm оставит версию в очереди и следующая попытка получит 409.
+
+После публикации проверьте `npx --yes ose-plugin@latest --help`, а старое имя
+пакета пометьте `npm deprecate` (или `npm unpublish` в первые 72 часа), чтобы в
+поиске не висели два одинаковых SDK.

package/bin/ose-plugin.mjs

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 
 /*
-  Одна команда для SDK: `npx ose-plugin create` и `npx ose-plugin check`.
+  Одна команда для SDK: `npx ose-plugin create`, `check` и `pack`.
 
-  Разделение на подкоманды — чтобы установленный пакет не требовал помнить два
-  имени: `create` собирает заготовку, `check` проверяет манифест и файлы.
+  Разделение на подкоманды — чтобы установленный пакет не требовал помнить три
+  имени: `create` собирает заготовку, `check` проверяет манифест и файлы,
+  `pack` кладёт пакет в zip для установки из панели.
 */
 
 import process from "node:process";
 
 import { main as create } from "../create.mjs";
+import { main as pack } from "../pack.mjs";
 import { main as check } from "../validate.mjs";
 
 const USAGE = [
@@ -17,6 +19,7 @@ const USAGE = [
   "",
   "  ose-plugin create <id> [--theme] [--name «Имя»] [--dir <каталог>] [--force]",
   "  ose-plugin check [<папка | каталог>] [--json]   (по умолчанию — текущая папка)",
+  "  ose-plugin pack <папка> [--out <файл>]          — zip для «Установить из ZIP»",
   "",
   "Документация: https://github.com/Halantar-git/open-stream-environment/tree/main/sdk",
 ].join("\n");
@@ -31,6 +34,9 @@ switch (command) {
   case "validate":
     check(rest.length > 0 ? rest : ["."]);
     break;
+  case "pack":
+    pack(rest);
+    break;
   case undefined:
   case "help":
   case "--help":

package/create.mjs

@@ -4,8 +4,8 @@
   Создать заготовку пакета виджета или темы.
 
   Заготовка — рабочий пакет, а не пустой скелет: его можно сразу положить в
-  config/plugins, перезапустить OSE и увидеть карточку в библиотеке. Дальше
-  остаётся переписать код, стили и схему настроек.
+  config/plugins и увидеть карточку в библиотеке после обновления страницы.
+  Дальше остаётся переписать код, стили и схему настроек.
 
   Использование:
     npx ose-plugin create <id> [параметры]
@@ -152,8 +152,10 @@ function main(argv) {
   }
   console.log("Дальше:");
   console.log("  1. Скопируйте папку в config/plugins/ (разработка) или в каталог данных приложения.");
-  console.log("  2. Перезапустите OSE — манифесты читаются при старте.");
+  console.log("  2. Обновите страницу панели — манифесты перечитываются при загрузке.");
+  console.log("     Оверлей в OBS обновите вручную, чтобы не рвать эфир.");
   console.log(`  3. Проверка после правок: npx ose-plugin check «${target}»`);
+  console.log(`  4. Архив для установки: npx ose-plugin pack «${target}»`);
 }
 
 export { main };

package/pack.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+/*
+  Собрать пакет в zip для установки из панели («Настройки → Пакеты»).
+
+  Архив — обычный zip без внешних зависимостей: пакет собирается из папки, а
+  в него не попадают служебные файлы Finder и Windows, `node_modules` и `.git`.
+  Манифест кладётся в корень, поэтому архив принимается и плоским, и вместе с
+  одноимённой папкой.
+
+  Использование:
+    npx ose-plugin pack <папка пакета> [--out <файл>]
+    node sdk/pack.mjs <папка пакета> [--out <файл>]   — в репозитории OSE
+
+  Код возврата 1 — пакет не прошёл проверку или архив не собрался.
+*/
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import zlib from "node:zlib";
+import { fileURLToPath } from "node:url";
+
+import { validatePackage } from "./validate.mjs";
+
+// Мусор, который не должен уезжать в архив: зависимости, служебные каталоги
+// системы контроля версий и файлы Finder/Windows.
+const SKIP = new Set(["node_modules", ".git", ".svn", "__MACOSX"]);
+
+const USAGE = [
+  "Использование: ose-plugin pack <папка пакета> [--out <файл>]",
+  "  --out <файл>  — куда положить архив (по умолчанию <id>.zip в текущем каталоге)",
+].join("\n");
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let index = 0; index < 256; index += 1) {
+    let value = index;
+    for (let bit = 0; bit < 8; bit += 1) {
+      value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+    table[index] = value >>> 0;
+  }
+  return table;
+})();
+
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Файлы пакета: относительные пути с «/» — так их понимает приложение. */
+function collect(dir, base = "", out = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const name = entry.name;
+    if (SKIP.has(name) || name === ".DS_Store" || name === "Thumbs.db" || name.startsWith("._")) continue;
+    const full = path.join(dir, name);
+    const relative = base ? `${base}/${name}` : name;
+    if (entry.isDirectory()) collect(full, relative, out);
+    else if (entry.isFile()) out.push({ relative, full });
+  }
+  return out;
+}
+
+/*
+  Минимальный zip: локальные заголовки, центральный каталог и конец каталога.
+  Deflate берётся только когда он правда уменьшает файл — иначе файл кладётся
+  как есть, и архив читается любым распаковщиком.
+*/
+function zip(files) {
+  const parts = [];
+  const central = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const data = fs.readFileSync(file.full);
+    const deflated = zlib.deflateRawSync(data);
+    const packed = deflated.length < data.length;
+    const body = packed ? deflated : data;
+    const name = Buffer.from(file.relative, "utf8");
+    const checksum = crc32(data);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6); // имена в UTF-8
+    local.writeUInt16LE(packed ? 8 : 0, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(0x21, 12);
+    local.writeUInt32LE(checksum, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    parts.push(local, name, body);
+
+    const header = Buffer.alloc(46);
+    header.writeUInt32LE(0x02014b50, 0);
+    header.writeUInt16LE(20, 4);
+    header.writeUInt16LE(20, 6);
+    header.writeUInt16LE(0x0800, 8);
+    header.writeUInt16LE(packed ? 8 : 0, 10);
+    header.writeUInt16LE(0, 12);
+    header.writeUInt16LE(0x21, 14);
+    header.writeUInt32LE(checksum, 16);
+    header.writeUInt32LE(body.length, 20);
+    header.writeUInt32LE(data.length, 24);
+    header.writeUInt16LE(name.length, 28);
+    header.writeUInt16LE(0, 30);
+    header.writeUInt16LE(0, 32);
+    header.writeUInt16LE(0, 34);
+    header.writeUInt16LE(0, 36);
+    header.writeUInt32LE((0o100644 << 16) >>> 0, 38);
+    header.writeUInt32LE(offset, 42);
+    central.push(header, name);
+
+    offset += local.length + name.length + body.length;
+  }
+
+  const centralSize = central.reduce((sum, part) => sum + part.length, 0);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(files.length, 8);
+  end.writeUInt16LE(files.length, 10);
+  end.writeUInt32LE(centralSize, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...parts, ...central, end]);
+}
+
+function fail(message) {
+  console.error(`[OSE] ${message}`);
+  process.exitCode = 1;
+}
+
+export function main(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(USAGE);
+    return;
+  }
+  const options = { target: "", out: "" };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--out") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) {
+        fail("у --out нет значения");
+        return;
+      }
+      options.out = value;
+      index += 1;
+    } else if (arg.startsWith("--")) {
+      fail(`неизвестный параметр: ${arg}`);
+      return;
+    } else if (!options.target) {
+      options.target = arg;
+    } else {
+      fail("нужна одна папка пакета");
+      return;
+    }
+  }
+  if (!options.target) {
+    console.log(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+
+  const folder = path.resolve(options.target);
+  if (!fs.existsSync(folder) || !fs.statSync(folder).isDirectory()) {
+    fail(`нет папки пакета: ${options.target}`);
+    return;
+  }
+  // Архив с ошибкой в манифесте приложение всё равно отвергнет — лучше сказать
+  // об этом сразу, а не после установки.
+  const report = validatePackage(folder);
+  if (report.errors.length > 0) {
+    report.errors.forEach((error) => console.error(`[OSE] ошибка: ${error}`));
+    process.exitCode = 1;
+    return;
+  }
+  report.warnings.forEach((warning) => console.log(`[OSE] предупреждение: ${warning}`));
+
+  const files = collect(folder);
+  if (files.length === 0) {
+    fail("в папке нет файлов");
+    return;
+  }
+  const id = path.basename(folder);
+  const out = options.out ? path.resolve(options.out) : path.join(process.cwd(), `${id}.zip`);
+  const archive = zip(files);
+  fs.writeFileSync(out, archive);
+  console.log(`[OSE] Архив готов: ${out} (файлов: ${files.length}, ${archive.length} байт)`);
+  console.log("Установка: «Настройки → Пакеты» → «Установить из ZIP».");
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ose-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold and validate Open Stream Environment widget and theme packages, with types for window.OSE.",
   "license": "GPL-3.0-or-later",
   "type": "module",
@@ -11,6 +11,7 @@
     "bin",
     "create.mjs",
     "validate.mjs",
+    "pack.mjs",
     "index.d.ts",
     "schema",
     "templates",

package/templates/theme/README.md

@@ -9,7 +9,9 @@
 
 ## Установка
 
-Скопируйте папку `{{id}}` в каталог пакетов и перезапустите приложение:
+Скопируйте папку `{{id}}` в каталог пакетов — перезапуск приложения не нужен:
+панель сама перезагрузится, когда вернёте ей фокус, а источник в OBS обновите
+вручную:
 
 - разработка (`npm run tauri:dev`) — `config/plugins/` в корне репозитория;
 - установленное приложение — каталог данных `com.openstreamenvironment.app`

package/templates/widget/README.md

@@ -10,14 +10,15 @@
 
 ## Установка
 
-Скопируйте папку `{{id}}` в каталог пакетов и перезапустите приложение — манифесты
-читаются при старте:
+Скопируйте папку `{{id}}` в каталог пакетов — перезапуск приложения не нужен:
+панель сама перезагрузится, когда вернёте ей фокус, а источник в OBS обновите
+вручную:
 
 - разработка (`npm run tauri:dev`) — `config/plugins/` в корне репозитория;
 - установленное приложение — каталог данных `com.openstreamenvironment.app`
   (Windows: `%APPDATA%\com.openstreamenvironment.app\plugins\`).
 
-После перезапуска виджет появится в колонке виджетов под своим именем.
+После обновления страницы виджет появится в колонке виджетов под своим именем.
 
 ## Проверка
 

package/validate.mjs

@@ -3,9 +3,9 @@
 /*
   Проверка пакета виджета или темы до установки.
 
-  Правила повторяют src-tauri/src/plugins.rs: приложение читает манифесты при
-  старте и отвергает пакет, который их не проходит. Ошибку лучше увидеть здесь,
-  чем после перезапуска — с сообщением в терминале и пустой карточкой.
+  Правила повторяют src-tauri/src/plugins.rs: приложение перечитывает манифесты
+  при загрузке страницы и отвергает пакет, который их не проходит. Ошибку лучше
+  увидеть здесь, чем в терминале приложения и пустой карточкой.
 
   Использование:
     npx ose-plugin check <папка пакета | каталог пакетов> [--json]