skills/westudy/references/local-upload.md

# Локальний завантажувач (лише середовище з файловим доступом)

Виконуй ці команди сам за авторизованим запитом користувача, не проси звичайного клієнта запускати термінал. Потрібен Node.js 20+ з fetch/FormData; додаткових npm-пакетів немає. Скрипт: `../scripts/upload-files.cjs` відносно цього документа. Використовуй абсолютний шлях до скрипту з установленого пакета. Не читай серверні репозиторії чи ключ школи.

1. Підготуй у робочій папці новий приватний manifest:
   `node <script> inspect <absolute-source-path> <manifest.json>`
   Для явно запитаних підпапок додай `--recursive`. Символічні посилання не обходяться. Нульові файли не підтримує поточний протокол сховища: скрипт перелічить їх як пропущені. Покажи кількість, сумарний обсяг і пропуски; за визначеного джерела та призначення продовжуй без повторного погодження.
2. Manifest має `files` з `path`, `relativePath`, `name`, `size`, `mime`, `mtimeMs`. Не змінюй локальні файли під час передавання. Невідомий MIME — `application/octet-stream`. Для рекурсивного завантаження створи відповідні папки командою `create_folder`, збережи зіставлення відносного каталогу з UUID. Порожні підпапки автоматично не створюються.
3. Згрупуй файли по папці призначення, пакети до 10. Викликай `create_file_uploads` із новим requestId, точними `name/size/mime`, folderUuid і видимістю. Шляхи й байти у команду не передавай. Для фото в редакторі потрібна public видимість; для інших файлів типово private.
4. Перевір виконання через get_execution і збережи фактичний `result.items` у приватний файл sessions.json (права 0600). Окремо збережи відібрані inspected files у files.json у ТОЧНО ТОМУ САМОМУ порядку. Не друкуй signed URLs і completionToken в чаті. Не використовуй shell-інтерполяцію секретів.
5. `node <script> bind <files.json> <sessions.json> <new-journal.json>`
   `node <script> run <journal.json>`
   Для дозволеного локального тестового сервера є `--allow-local` (лише loopback HTTP). Скрипт послідовно передає чанки до 50 MiB, зберігає прогрес і реєструє готовий файл через обмежений токен сесії. Збережи журнал до підтвердженого завершення всіх файлів. Журнал містить секрети; не додавай його в Git чи пакет плагіна.
6. Після успіху перевір `get_file_transfers` і використовуй отримані fileUuid та URL. Якщо є наступні пакети — продовжуй послідовно. Завантаження не конвертує відео та не прикріплює його до уроку.

`run` може без повторного передавання завершити реєстрацію за збереженою квитанцією або продовжити з надійно записаного next_url. Після втрати відповіді на чанк повертає UNKNOWN і не повторює чанк. Ніколи не стирай цей стан заради повтору. Якщо процес перервався, `.lock` може залишитися: спершу перевір, що відповідного процесу вже немає; тільки тоді прибери цей локальний lock. Самі файли й журнал не видаляй. Адреси чанків мають строк дії, сесія завершення — 24 години.

Якщо середовище вимагає журналювати API-запити, виконуй його вимоги і для завершення завантаження. Для цього `run` можна викликати з програмним адаптером `complete(url, token, body)` замість стандартного HTTP-клієнта; чанк-джерело й підписані адреси не виводь у відкриті логи.