kingkont 0.7.38 → 0.7.40

package/assets/PROJECT_CLAUDE.md

@@ -1,149 +1,48 @@
-# Структура проекта KingKont
+# Это проект KingKont
 
-Эта папка — **проект** (фильм/сериал) редактора **KingKont · Chatium**. Файлы здесь
-создаются и редактируются GUI-приложением, но всё хранится в plain-формате —
-любой инструмент (включая Claude Code) может читать/изменять напрямую.
+Эта папка — проект редактора **KingKont · Chatium** (нод-редактор сцен фильма
+с AI-генерацией картинок/видео/голоса/SFX/музыки/текста).
 
-## Что лежит в корне
+## Для Claude
 
-```
-.
-├── CLAUDE.md              ← этот файл
-├── _characters/           ← персонажи
-│   └── <имя>/             ← одна доска на персонажа
-├── _locations/            ← локации
-│   └── <имя>/             ← одна доска на локацию
-├── <имя сцены>/           ← сцены лежат прямо в корне как папки
-│   └── …                  ← (любое имя кроме начинающихся с `_` и `.`)
-├── _deleted/              ← корзина: удалённые файлы попадают сюда
-│                            (восстанавливаются через Cmd+Z в редакторе)
-└── (любые другие файлы)   ← редактор их не трогает
-```
+**Используй скилл `kingkont`.** Он знает формат `scene.json`, расположение
+досок (`_characters/`, `_locations/`, `<сцена>/`) и умеет управлять нодами +
+запускать генерации через CLI без открытия UI приложения. API-ключи скилл
+берёт автоматически из настроек установленного приложения KingKont.
 
-## Доска (board) — папка персонажа / локации / сцены
+### Установка скилла
 
-Любая доска внутри (`_characters/<имя>/`, `_locations/<имя>/`, `<сцена>/`)
-имеет одинаковую структуру:
+Если приложение `kingkont` ещё не установлено:
 
-```
-<board>/
-├── scene.json             ← вся метаинформация (см. ниже)
-├── clips/                 ← видео-файлы (mp4, mov, webm…)
-├── images/                ← картинки (jpg, png, webp…)
-├── audio/                 ← аудио (mp3, wav, m4a…)
-└── texts/                 ← .md-файлы текстовых нод
+```bash
+npm i -g kingkont
 ```
 
-## Формат `scene.json`
+Установить скилл (положит `~/.claude/skills/kingkont/SKILL.md`):
 
-Главный файл доски. Редактор читает его при открытии и пишет debounced при
-любом изменении. Пример:
-
-```json
-{
-  "nodes": [
-    {
-      "id": "uuid-here",
-      "type": "image" | "video" | "audio" | "text",
-      "name": "опциональное имя для @-ссылок",
-      "file": "images/foo.jpg",      // относительный путь в папке доски
-      "x": 100, "y": 200,            // позиция на холсте (логические px)
-      "width": 280, "height": 320,   // опц., если юзер ресайзил ноду
-      "generated": {                  // опц., если нода создана генерацией
-        "kind": "image" | "video" | "audio" | "text",
-        "prompt": "финальный промпт после resolve mentions",
-        "rawPrompt": "исходный промпт с [@ref]",
-        "model": "nano-banana-2" | "bytedance/seedance-2" | "eleven_v3" | "anthropic/claude-sonnet-4" | …,
-        "modelKey": "ключ модели для KIE",
-        "voiceId": "...",            // для audio
-        "tones": ["шепот", …],       // для audio
-        "refs": [{name, type, file}],
-        "state": "submitting" | "queued" | "generating" | "success" | "error",
-        "taskId": "..."
-      },
-      "status": "generating" | "draft" | "error" | undefined,
-      "error": "текст ошибки если status=error",
-      "history": [...],              // history правок (через ⇄ Заменить)
-      "historyIndex": 0
-    }
-    // ... text-нода: поле "text" в JSON НЕ хранится; контент лежит в texts/<file>.md
-  ],
-  "connections": [
-    { "from": "node-id", "to": "node-id" }
-  ],
-  "view": { "scrollLeft": 0, "scrollTop": 0, "zoom": 1.0 },
-  "character": {                     // только для досок-персонажей
-    "characterSheet": "images/sheet.jpg",
-    "voice": "elevenlabs-voice-id",
-    "tone": "по умолчанию",
-    "commonTones": ["шепот", "крик", …],
-    "lastTones": [],
-    "replicas": [...]
-  },
-  "location": {                      // только для досок-локаций
-    "sheet": "images/sheet.jpg"
-  },
-  "timeline": {                      // монтажный лист сцены
-    "tracks": [
-      {
-        "id": "tv", "name": "Видео", "kind": "video" | "audio",
-        "clips": [
-          {
-            "id": "uuid",
-            "nodeId": "node-id или null",   // привязка к ноде на холсте
-            "type": "video" | "image" | "audio",
-            "file": "clips/foo.mp4",
-            "name": "Foo",
-            "duration": 5.0,                // в секундах
-            "start": 0,                     // позиция начала на дорожке
-            "trimStart": 0,                 // обрезка спереди
-            "sourceDuration": 5.0,          // полная длительность файла
-            "_durationLoaded": true,
-            "groupId": "...",               // опц., группа клипов
-            "disabled": false               // skip при playback
-          }
-        ]
-      }
-    ],
-    "playhead": 0.27
-  },
-  "history": {                        // undo/redo (Cmd+Z / Cmd+Shift+Z)
-    "past":  [{ "ts": 1234567890, "label": "…", "snap": "JSON-string", "movedFiles": [...] }],
-    "future": [...]
-  }
-}
+```bash
+kingkont install-skill
 ```
 
-## Текстовые ноды
-
-Текст ноды хранится не в `scene.json`, а в `texts/<имя>.md`. Поле `node.file`
-указывает путь, поле `node.text` в JSON отсутствует (грузится при загрузке
-доски). Это удобно для редактирования: можно править .md руками, и редактор
-подхватит изменения при следующем открытии.
+После `/reload` в Claude Code скилл `kingkont` станет доступен.
 
-## Файловые операции редактора
+### Если скилл недоступен
 
-- **Удаление ноды**: файл (если был) переезжает в `<root>/_deleted/<уникальное-имя>`.
-  Cmd+Z восстанавливает обратно (movedFiles в history).
-- **Замена/перегенерация**: новый файл записывается в соответствующую
-  подпапку, старый сохраняется в `node.history[]` для отката.
-- **Импорт через drag-drop**: файлы копируются в правильную подпапку
-  (clips/images/audio) с уникальным именем.
+Краткая шпаргалка (полный API — в `kingkont --help` и в самом скилле):
 
-## Что НЕ трогать руками (если хочешь долго жить)
+```bash
+kingkont open <project>                    # JSON со структурой проекта
+kingkont board <project> <board>           # одна доска (--json)
+kingkont add-node <project> <board> --kind=image|video|audio|text [--name=...]
+kingkont gen <project> <board> --kind=... --prompt="..." [--model=...] [--refs=@a,@b]
+kingkont connect <project> <board> <fromId> <toId>
+kingkont rm-node <project> <board> <nodeId>
+```
 
-- Поля с `id` в формате UUID — на них завязаны connections, timeline-clips,
-  history. Меняй name, prompt, x/y свободно.
-- `history.past`/`future` — снимки всей сцены. Лучше не редактировать, иначе
-  Cmd+Z восстановит мусор.
+Где `<board>` — это `Scene1`, `_characters/Anna` или `_locations/Office`.
 
-## Совет для AI-агентов
+---
 
-При работе с этой папкой:
-1. Читай `scene.json` чтобы понять структуру нод и связей.
-2. Текст текстовых нод — в `texts/`. Читай и пиши .md напрямую.
-3. Если меняешь `scene.json` — сохраняй валидный JSON и не трогай поля
-   которые не понимаешь (особенно `history`).
-4. Бинарные ресурсы (клипы/картинки/аудио) лежат в подпапках по типу.
-   Импорт через drag-drop в редакторе автоматически кладёт в правильное
-   место и регистрирует ноду на холсте.
+*Этот файл создан KingKont автоматически и обновляется при каждом открытии
+проекта. Безопасно удалить — приложение положит его обратно. Если хочешь
+свою документацию — переименуй файл (например в `NOTES.md`).*

package/bin/kingkont.js

@@ -1,26 +1,59 @@
 #!/usr/bin/env node
-// CLI launcher для KingKont. Без аргументов — запускает Electron-приложение.
-// С `serve [path]` — поднимает только HTTP-сервер для запуска редактора в браузере.
+// CLI launcher для KingKont.
+//   `kingkont`              — запустить Electron-приложение
+//   `kingkont serve`        — поднять только HTTP-сервер для Chrome
+//   `kingkont install-skill`— положить SKILL.md для Claude Code
+//   `kingkont <node-cmd>`   — управление нодами проекта без UI
+//                             (open / list / board / add-node / gen / generate /
+//                              status / connect / rm-node / voices / balance / upload)
+//
+// Полный help: `kingkont --help`.
+// Подробная документация по нод-командам — в SKILL.md.
+
+'use strict';
+
 const path = require('node:path');
 const { spawn } = require('node:child_process');
 
 const root = path.resolve(__dirname, '..');
 const args = process.argv.slice(2);
 
+const settingsLib = require(path.join(root, 'lib', 'settings.js'));
+
 function showHelp() {
   console.log(`
 KingKont · Chatium — видео-редактор сериала
 
-Запуск:
-  npx kingkont                запустить Electron-приложение (рекомендуется)
-  npx kingkont serve          запустить только HTTP-сервер; URL для Chrome
-  npx kingkont serve <path>   то же, путь к проекту/cwd по умолчанию
-  npx kingkont install-skill  установить Skill для Claude Code (~/.claude/skills/kingkont)
+Запуск редактора:
+  npx kingkont                 запустить Electron-приложение (рекомендуется)
+  npx kingkont serve           запустить HTTP-сервер; URL для Chrome
+  npx kingkont serve <path>    то же, путь к проекту/cwd по умолчанию
+  npx kingkont install-skill   установить Skill для Claude Code
+
+Управление нодами без UI (правит scene.json напрямую):
+  kingkont open <project>                   структура проекта (JSON с --json)
+  kingkont list <project>                   список досок
+  kingkont board <project> <board>          одна доска (--json для машины)
+  kingkont add-node <project> <board> --kind=image|video|audio|text [--name=...]
+  kingkont gen <project> <board> --kind=... --prompt="..." [--model=...] [--refs=@a,@b]
+  kingkont generate <project> <board> <nodeId>   перезапустить draft-ноду
+  kingkont status <project> <board> <nodeId>     прогресс in-flight задачи
+  kingkont connect <project> <board> <fromId> <toId>
+  kingkont rm-node <project> <board> <nodeId>
+
+Утилиты:
+  kingkont voices              список голосов ElevenLabs (нужен ключ)
+  kingkont balance             балансы всех включённых провайдеров
+  kingkont upload <file>       загрузить файл в storage, печатает URL
 
 Опции:
-  --port <N>   порт сервера (по умолчанию 17893)
-  --project    install-skill: положить в .claude/skills/ текущей папки
-  --help, -h   эта справка
+  --port <N>          порт HTTP-сервера (по умолчанию 17893)
+  --json              машино-читаемый вывод (для cli/Claude)
+  --project           install-skill: положить в .claude/skills/ текущей папки
+  --help, -h          эта справка
+
+Где CLI берёт API-ключи: ~/Library/Application Support/KingKont/settings.json
+(те же ключи, что подключены через UI приложения).
 `);
 }
 
@@ -51,21 +84,27 @@ if (args.includes('--help') || args.includes('-h')) {
 const portIdx = args.indexOf('--port');
 const port = portIdx >= 0 ? parseInt(args[portIdx + 1], 10) : 17893;
 
-if (args[0] === 'install-skill') {
+// Подгружаем ключи из settings.json в env (для всех режимов).
+settingsLib.applySettingsToEnv(settingsLib.loadSettings());
+
+const cmd = args[0];
+
+if (cmd === 'install-skill') {
   installSkill();
   process.exit(0);
 }
 
-if (args[0] === 'serve') {
-  // Только Node-сервер. FSAH-API в Chrome требует user-gesture для
-  // showDirectoryPicker — юзер сам выбирает папку через UI.
+// Нод-команды — делегируем в lib/cli.
+const NODE_COMMANDS = require(path.join(root, 'lib', 'cli.js')).COMMANDS;
+if (cmd && NODE_COMMANDS[cmd]) {
+  const cliLib = require(path.join(root, 'lib', 'cli.js'));
+  cliLib.run(args).then(
+    () => process.exit(0),
+    err => { console.error('Ошибка:', err.message); process.exit(1); }
+  );
+} else if (cmd === 'serve') {
   process.env.PORT = String(port);
-  // Если задан путь — на старте просто печатаем подсказку, открыть его
-  // через FSAH юзер должен руками (нельзя без gesture).
   const targetPath = args[1] && !args[1].startsWith('--') ? path.resolve(args[1]) : null;
-  // Подгружаем сервер. Если ключи не в env — попробуем взять из userData
-  // (так же как делает main.js).
-  applySettingsToEnv();
   const { start } = require(path.join(root, 'server.js'));
   start(port).then(actualPort => {
     const url = `http://localhost:${actualPort}/`;
@@ -77,13 +116,7 @@ if (args[0] === 'serve') {
     process.exit(1);
   });
 } else {
-  // Electron-приложение.
-  applySettingsToEnv();
-  // Self-heal: если postinstall не отработал (npm 9+ иногда тихо пропускает
-  // scripts при глобал-install под некоторыми node-prefix'ами), Electron.app
-  // в node_modules останется не переименованным → в menubar macOS «Electron»
-  // вместо «KingKont». Запустим патч-скрипт прямо сейчас, idempotent — если
-  // уже переименовано, выйдет no-op. Ошибку проглатываем — это cosmetic.
+  // Electron-приложение (default).
   if (process.platform === 'darwin') {
     try {
       const patch = require(path.join(root, 'scripts', 'patch-electron-name.js'));
@@ -92,7 +125,6 @@ if (args[0] === 'serve') {
   }
   const electronPath = (() => {
     try {
-      // Сбрасываем кэш — postinstall мог только что переписать path.txt.
       delete require.cache[require.resolve('electron')];
       return require('electron');
     }
@@ -105,25 +137,3 @@ if (args[0] === 'serve') {
   const proc = spawn(electronPath, [root], { stdio: 'inherit', env: process.env });
   proc.on('exit', code => process.exit(code || 0));
 }
-
-// Прокидываем сохранённые ключи из userData/settings.json в process.env,
-// чтобы server.js (handleGenerate/Tts/Sfx/Music/Text) их подхватил.
-function applySettingsToEnv() {
-  try {
-    const fs = require('node:fs');
-    const os = require('node:os');
-    // На macOS userData = ~/Library/Application Support/KingKont
-    const candidates = [
-      path.join(os.homedir(), 'Library', 'Application Support', 'KingKont', 'settings.json'),
-      path.join(os.homedir(), '.config', 'KingKont', 'settings.json'),
-    ];
-    for (const p of candidates) {
-      if (!fs.existsSync(p)) continue;
-      const s = JSON.parse(fs.readFileSync(p, 'utf-8'));
-      if (s.kieKey)        process.env.KIE_API_KEY = s.kieKey;
-      if (s.elevenKey)     process.env.ELEVENLABS_API_KEY = s.elevenKey;
-      if (s.openrouterKey) process.env.OPENROUTER_API_KEY = s.openrouterKey;
-      break;
-    }
-  } catch {}
-}