pagecraft-folders

PageCraft Folders

Этот skill учит агента управлять папками страниц в PageCraft через V1 REST API: создавать иерархию, переименовывать, перемещать между папками, удалять (каскадно).

Когда применять

• Пользователь просит организовать страницы в папки — построить структуру/иерархию.
• Нужно переименовать или переместить папку.
• Нужно удалить папку — отдельную или вместе со всем содержимым.
• Нужен срез существующей иерархии (плоский список или дерево).

Жёсткие правила

1. Перед folders-delete.mjs без --yes ВСЕГДА вызывай folders-get.mjs <id> — если total_pages_count + total_subfolders_count > 0, скрипт сам остановится и выведет counts. Это защита от случайного каскадного удаления.
2. Перемещение СТРАНИЦЫ между папками — НЕ в этом скилле. Используй pagecraft-pages/scripts/pages-update.mjs с { "folder_id": N | null } в payload. Этот скилл двигает только сами папки.
3. Контракт PUT — точный: «поле не передано» = не менять. «parent_id: null» = переместить папку в корень. Не путай с отсутствием поля.
4. Cross-site move запрещён: parent_id должен указывать на папку того же сайта, иначе 422.
5. Циклы запрещены: нельзя сделать папку потомком самой себя (прямо или транзитивно), иначе 422.

Окружение

• PAGECRAFT_API_KEY — обязательная переменная: API-ключ pb_xxxx... (UI PageCraft → API keys).
• PAGECRAFT_API_URL — опциональная: базовый host, по умолчанию https://page-craft.4partners.io (префикс /api/v1 добавляется автоматически). Legacy-имя PAGE_CRAFT_API (host с /api/v1) ещё поддерживается как fallback.

Скрипты

Команда	Endpoint	Когда вызывать
node scripts/folders-list.mjs <site_id> [--as-tree]	GET /folders	Снять срез иерархии. --as-tree собирает children.
node scripts/folders-get.mjs <id>	GET /folders/{id}	Перед folders-delete.mjs — узнать counts.
node scripts/folders-create.mjs <payload.json>	POST /folders	Создать одну папку.
node scripts/folders-update.mjs <id> <payload.json>	PUT /folders/{id}	Переименовать и/или переместить.
node scripts/folders-delete.mjs <id> [--yes]	DELETE /folders/{id}	Удалить. Непустая папка — только с --yes.

Формы payload-ов

folders-create.mjs

{ "site_id": 3, "name": "Лендинги", "parent_id": null }

Поле	Тип	Обязательное	Заметка
site_id	integer	✓	ID сайта (см. sites-list.mjs в pagecraft-pages)
name	string	✓	Название папки
parent_id	integer/null	—	ID родителя или null для корневой

folders-update.mjs

Оба поля опциональны.

{ "name": "Новое название" }

{ "parent_id": 5 }

{ "parent_id": null }

Поле	Что значит
name отсутствует	не переименовывать
name: "X"	переименовать на X (пустая строка → 422)
parent_id отсутствует	не перемещать
parent_id: null	переместить в корень
parent_id: 5	сделать ребёнком папки 5

Workflow

Построить иерархию «Каталог → Женское / Мужское»

# 1. Создать корневую
echo '{"site_id":3,"name":"Каталог"}' > /tmp/catalog.json
ROOT=$(node scripts/folders-create.mjs /tmp/catalog.json | jq -r '.folder.id')

# 2. Создать детей
echo "{\"site_id\":3,\"name\":\"Женское\",\"parent_id\":$ROOT}" > /tmp/women.json
node scripts/folders-create.mjs /tmp/women.json
echo "{\"site_id\":3,\"name\":\"Мужское\",\"parent_id\":$ROOT}" > /tmp/men.json
node scripts/folders-create.mjs /tmp/men.json

# 3. Проверить
node scripts/folders-list.mjs 3 --as-tree

Безопасно удалить папку

# 1. Узнать counts (ответ содержит total_pages_count/total_subfolders_count — рекурсивные totals)
node scripts/folders-get.mjs 12

# 2a. Пусто → DELETE проходит сразу
node scripts/folders-delete.mjs 12

# 2b. Не пусто — скрипт откажет, покажет РЕКУРСИВНЫЕ totals (реальный объём удаления):
node scripts/folders-delete.mjs 12
# stderr: { "error": "Папка не пустая...", "will_delete": { "pages": 142, "subfolders": 17 } }

# 3. Подтвердить осознанно
node scripts/folders-delete.mjs 12 --yes
# → { "success": true, "deleted_pages": 142, "deleted_subfolders": 17 }

Перенести папку в корень

echo '{"parent_id": null}' > /tmp/to-root.json
node scripts/folders-update.mjs 12 /tmp/to-root.json

Композиция с другими скиллами

• pagecraft-pages — после создания структуры папок передавай folder_id в payload создания/обновления страниц.
• pagecraft-provider, pagecraft-s3 — независимы от этого скилла.

Коды ошибок

Код	Причина
400	Нет site_id в GET /folders, невалидный payload в POST
401	Нет / неверный PAGECRAFT_API_KEY
404	Папка, сайт или родительская папка не принадлежит владельцу ключа
422	Пустое имя, цикл в иерархии, cross-site parent