@notehub.md/cli 0.1.8 → 0.1.10

package/templates/docs/ru/01-getting-started.md

@@ -0,0 +1,207 @@
+# Начало работы
+
+Это руководство проведет вас через создание вашего первого плагина Notehub.md.
+
+## Предварительные требования
+
+- **Node.js** v18+ с npm/pnpm
+- **TypeScript** (рекомендуется, но JavaScript тоже работает)
+- **Сборщик**: esbuild, Vite или Rollup
+- Хранилище Notehub.md для тестирования
+
+## Структура плагина
+
+Каждый плагин требует как минимум:
+
+```
+my-plugin/
+├── manifest.json    # Метаданные плагина (обязательно)
+├── main.js          # Точка входа (скомпилированная)
+└── src/             # Исходные файлы (опционально)
+    └── index.ts
+```
+
+## manifest.json
+
+Манифест описывает ваш плагин для Notehub:
+
+```json
+{
+    "id": "my-awesome-plugin",
+    "name": "Мой Крутой Плагин",
+    "version": "1.0.0",
+    "main": "main.js",
+    "dependencies": []
+}
+```
+
+| Поле | Обязательно | Описание |
+|------|-------------|----------|
+| `id` | ✅ | Уникальный идентификатор (строчные буквы, дефисы разрешены) |
+| `name` | ✅ | Человекочитаемое имя |
+| `version` | ✅ | Семантическая версия (например, `1.0.0`) |
+| `main` | ❌ | Файл точки входа, по умолчанию `main.js` |
+| `dependencies` | ❌ | Массив ID внутренних плагинов, от которых зависит этот плагин |
+
+---
+
+## Вариант 1: Генератор плагинов (Внутренние плагины)
+
+Если вы разрабатываете плагин **внутри монорепо Notehub**, используйте генератор:
+
+```bash
+pnpm gen:plugin
+```
+
+Интерактивный CLI:
+1. ✔ Запросит имя плагина (kebab-case)
+2. ✔ Предложит выбрать категорию (`system`, `ui`, `features`)
+3. ✔ Сгенерирует полную структуру со всем boilerplate
+
+**Генерируемые файлы:**
+- `package.json` — Конфиг пакета с зависимостью `@notehub/core`
+- `tsconfig.json` — TypeScript конфиг, расширяющий базовый
+- `manifest.json` — Метаданные плагина
+- `src/index.ts` — Класс плагина, реализующий `IPlugin`
+
+---
+
+## Вариант 2: Ручная настройка (Внешние плагины)
+
+Для плагинов, которые живут **вне монорепо** и загружаются в runtime из хранилища:
+
+### Шаг 1: Создайте структуру папок
+
+```bash
+mkdir my-plugin
+cd my-plugin
+npm init -y
+npm install @notehub/api typescript esbuild --save-dev
+```
+
+### Шаг 2: Создайте manifest.json
+
+```json
+{
+    "id": "hello-world",
+    "name": "Hello World",
+    "version": "1.0.0"
+}
+```
+
+### Шаг 3: Создайте src/index.ts
+
+```typescript
+import { NotehubPlugin, PluginContext } from '@notehub/api';
+
+export default class HelloWorldPlugin extends NotehubPlugin {
+    async onload(ctx: PluginContext): Promise<void> {
+        // Логируем сообщение при загрузке плагина
+        await ctx.invokeApi('logger:info', 'HelloWorld', 'Привет из моего плагина!');
+        
+        // Регистрируем кастомный API
+        ctx.registerApi('hello:say', (message: string) => {
+            console.log(`[HelloWorld] ${message}`);
+        });
+        
+        // Подписываемся на события выбора файла
+        ctx.subscribe<{ path: string }>('explorer:file-selected', (payload) => {
+            console.log('Выбран файл:', payload.path);
+        });
+    }
+    
+    async onunload(): Promise<void> {
+        // Ничего делать не нужно - очистка автоматическая!
+        console.log('Плагин HelloWorld выгружен');
+    }
+}
+```
+
+### Шаг 4: Создайте tsconfig.json
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "lib": ["ES2020", "DOM"],
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "declaration": false,
+        "outDir": "./dist"
+    },
+    "include": ["src/**/*"]
+}
+```
+
+### Шаг 5: Создайте скрипт сборки
+
+Добавьте в `package.json`:
+
+```json
+{
+    "scripts": {
+        "build": "esbuild src/index.ts --bundle --format=esm --outfile=main.js --external:@notehub/api --external:react"
+    }
+}
+```
+
+### Шаг 6: Соберите и установите
+
+```bash
+npm run build
+```
+
+Скопируйте папку в ваше хранилище:
+```
+MyVault/.notehub/plugins/hello-world/
+├── manifest.json
+└── main.js
+```
+
+### Шаг 7: Тестирование
+
+1. Откройте Notehub.md с вашим хранилищем
+2. Ваш плагин загрузится автоматически!
+3. Проверьте консоль на сообщение "Привет из моего плагина!"
+
+---
+
+## Важно: Внешние зависимости
+
+Ваш плагин работает в **общей области видимости** с Notehub. Эти пакеты предоставляются хостом:
+
+| Пакет | Описание |
+|-------|----------|
+| `@notehub/api` | API плагинов (`NotehubPlugin`, `PluginContext`) |
+| `react` | Библиотека React |
+| `react-dom` | React DOM рендерер |
+
+**Отметьте их как external** в конфигурации сборщика, чтобы избежать дублирования!
+
+---
+
+## Горячая перезагрузка
+
+Notehub следит за директорией `.notehub/plugins/`. Когда вы обновляете плагин:
+
+1. Старая версия автоматически выгружается
+2. Новая версия загружается
+3. Все ваши регистрации API очищаются автоматически!
+
+---
+
+## Советы по отладке
+
+1. **Откройте DevTools** (Ctrl+Shift+I) чтобы видеть логи консоли
+2. **Используйте `logger:info`** API для структурированного логирования
+3. **Проверьте логи плагина Synapse** для событий загрузки/выгрузки
+
+---
+
+## Следующие шаги
+
+- Прочитайте **[Архитектура](02-architecture.md)** чтобы понять жизненный цикл плагина
+- Изучите **[Справочник API](03-api-reference.md)** для всех доступных методов

package/templates/docs/ru/02-architecture.md

@@ -0,0 +1,228 @@
+# Архитектура плагинов
+
+Этот документ объясняет, как работают плагины Notehub.md под капотом.
+
+## Микроядерная архитектура
+
+Notehub.md следует **микроядерному** дизайну, где ядро минимально, а вся функциональность приходит от плагинов:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    NotehubCore                              │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
+│  │  EventBus   │  │   ApiBus    │  │  Plugin Registry    │ │
+│  │  (pub/sub)  │  │ (RPC вызовы)│  │  (управление ЖЦ)    │ │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+        ▲                 ▲                    ▲
+        │                 │                    │
+   ┌────┴───┐       ┌─────┴────┐        ┌─────┴────┐
+   │ Logger │       │  Editor  │        │ Explorer │
+   │ Plugin │       │  Plugin  │        │  Plugin  │
+   └────────┘       └──────────┘        └──────────┘
+```
+
+## Типы плагинов
+
+### Внутренние плагины (IPlugin)
+
+Основные функции реализуют интерфейс `IPlugin` напрямую:
+
+```typescript
+interface IPlugin {
+    readonly manifest: PluginManifest;
+    load(app: NotehubCore): Promise<void> | void;
+    onReady?(app: NotehubCore): Promise<void> | void;
+    unload(app: NotehubCore): Promise<void> | void;
+}
+```
+
+### Внешние плагины (NotehubPlugin)
+
+Ваши плагины наследуют `NotehubPlugin` и используют `PluginContext`:
+
+```typescript
+abstract class NotehubPlugin {
+    abstract onload(ctx: PluginContext): Promise<void> | void;
+    abstract onunload(): Promise<void> | void;
+}
+```
+
+Ключевое отличие: **внешние плагины получают автоматическую очистку** через `PluginContext`!
+
+---
+
+## Жизненный цикл плагина
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                 Жизненный цикл плагина                   │
+├──────────────────────────────────────────────────────────┤
+│                                                          │
+│  1. ОБНАРУЖЕНИЕ                                          │
+│     └─ Synapse сканирует папку .notehub/plugins/         │
+│     └─ Читает manifest.json для каждого плагина          │
+│                                                          │
+│  2. ЗАГРУЗКА                                             │
+│     └─ SystemJS импортирует модуль main.js               │
+│     └─ Создается экземпляр класса плагина                │
+│     └─ Создается PluginContext (для внешних плагинов)    │
+│                                                          │
+│  3. ИНИЦИАЛИЗАЦИЯ (onload)                               │
+│     └─ Плагин регистрирует API                           │
+│     └─ Плагин подписывается на события                   │
+│     └─ Плагин настраивает UI-компоненты                  │
+│                                                          │
+│  4. РАБОТА                                               │
+│     └─ Плагин реагирует на события                       │
+│     └─ Плагин обрабатывает API-вызовы                    │
+│                                                          │
+│  5. ВЫГРУЗКА (onunload)                                  │
+│     └─ Плагин выполняет ручную очистку (опционально)     │
+│     └─ PluginContext автоматически очищает регистрации   │
+│     └─ Модуль SystemJS выгружается                       │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## PluginContext
+
+`PluginContext` — это ваш шлюз в экосистему Notehub:
+
+```typescript
+interface PluginContext {
+    // Регистрация API, который могут вызывать другие плагины
+    registerApi(name: string, handler: (...args: unknown[]) => unknown): void;
+    
+    // Вызов API, зарегистрированного любым плагином
+    invokeApi<T>(name: string, ...args: unknown[]): Promise<T>;
+    
+    // Подписка на события приложения
+    subscribe<T>(event: string, handler: (payload: T) => void): void;
+}
+```
+
+### Магия автоматической очистки
+
+Когда ваш плагин выгружается, `PluginContext` автоматически:
+
+- ✅ Отменяет регистрацию всех ваших API
+- ✅ Отписывается от всех событий
+- ✅ Удаляет виджеты редактора, которые вы зарегистрировали
+- ✅ Удаляет вкладки/группы/элементы настроек, которые вы добавили
+
+**Вам не нужно вручную это очищать!**
+
+---
+
+## Паттерны коммуникации
+
+### 1. EventBus (Pub/Sub)
+
+Для **broadcast** информации множеству слушателей:
+
+```typescript
+// Подписка на событие
+ctx.subscribe<{ path: string }>('explorer:file-selected', (payload) => {
+    console.log('Выбран файл:', payload.path);
+});
+
+// События испускаются плагинами внутренне
+// Внешние плагины могут только подписываться, не испускать
+```
+
+Частые события:
+- `explorer:file-selected` — пользователь кликнул на файл
+- `editor:file-opened` — контент файла загружен
+- `editor:file-closed` — редактор очищен
+- `vault:opened` — хранилище было открыто
+- `vault:closed` — хранилище было закрыто
+
+### 2. ApiBus (RPC)
+
+Для **прямых вызовов методов** между плагинами:
+
+```typescript
+// Регистрация API
+ctx.registerApi('my-plugin:calculate', (a: number, b: number) => a + b);
+
+// Вызов чужого API
+const result = await ctx.invokeApi<number>('my-plugin:calculate', 5, 3);
+// result = 8
+
+// Все системные API доступны через invokeApi
+const content = await ctx.invokeApi<string>('fs:read-text-file', '/path/to/file.md');
+```
+
+---
+
+## Разрешение зависимостей
+
+Плагины могут объявлять зависимости в `manifest.json`:
+
+```json
+{
+    "id": "my-plugin",
+    "dependencies": ["nh.features.editor"]
+}
+```
+
+Загрузчик гарантирует, что зависимости загрузятся до вашего плагина.
+
+**Примечание:** Для внешних плагинов системные плагины всегда доступны. Обычно вам не нужно объявлять зависимости, если только вы не зависите от другого внешнего плагина.
+
+---
+
+## Горячая перезагрузка
+
+Notehub следит за папкой плагинов. При изменении файла:
+
+1. **Обнаружение** — файловый наблюдатель срабатывает на изменение `.js` или `manifest.json`
+2. **Выгрузка** — старая версия плагина выгружается (вызывается `onunload()`)
+3. **Очистка** — PluginContext удаляет все регистрации
+4. **Перезагрузка** — новая версия загружается (вызывается `onload()`)
+
+Это позволяет **быстро разрабатывать** без перезапуска Notehub!
+
+---
+
+## Лучшие практики
+
+### 1. Используйте пространства имен для API
+
+```typescript
+// ✅ Хорошо — с пространством имен
+ctx.registerApi('my-plugin:do-something', handler);
+
+// ❌ Плохо — может конфликтовать
+ctx.registerApi('do-something', handler);
+```
+
+### 2. Обрабатывайте ошибки корректно
+
+```typescript
+async onload(ctx: PluginContext): Promise<void> {
+    try {
+        const data = await ctx.invokeApi('fs:read-text-file', '/config.json');
+        // ...
+    } catch (error) {
+        await ctx.invokeApi('logger:error', 'MyPlugin', `Ошибка загрузки: ${error}`);
+    }
+}
+```
+
+### 3. Используйте TypeScript для лучшего IntelliSense
+
+Пакет `@notehub/api` включает полные определения типов для всех API.
+
+### 4. Держите onload() быстрым
+
+Не блокируйте инициализацию тяжелой работой. Используйте асинхронные паттерны или отложите работу.
+
+---
+
+## Следующие шаги
+
+Смотрите полный **[Справочник API](03-api-reference.md)** для всех доступных методов.