# Telegraph Publisher CLI

Современный инструмент командной строки для публикации Markdown файлов в Telegra.ph с расширенной системой управления зависимостями, метаданными и интеллектуальной обработкой ссылок.

## 🚀 Ключевые особенности

### Основные функции
- 📝 **Полная поддержка Markdown** с прямой конвертацией в Telegraph Node (без промежуточного HTML)
- 🔗 **Умное управление зависимостями** - автоматическая публикация связанных файлов
- 📊 **Система метаданных** - автоматическое добавление YAML front-matter к опубликованным файлам
- 🔄 **Кэширование страниц** - быстрый доступ к информации о публикациях
- ⚡ **Оптимизация производительности** - пропуск публикации неизменённых файлов (hash-based)

### Интеллектуальная обработка ссылок
- 🔍 **Автоматическая проверка ссылок** - валидация локальных и внешних ссылок перед публикацией
- 🔧 **Автоматическое исправление** - интеллектуальный ремонт сломанных ссылок
- 🔄 **Замена локальных ссылок** - автоматическая замена на Telegraph URLs в опубликованном контенте
- 📋 **Подробная отчётность** - детальные отчёты о состоянии всех ссылок

### Расширенные возможности
- 📑 **Table of Contents (ToC)** - автоматическая генерация оглавления с якорными ссылками
- 📊 **Анализ зависимостей** - визуализация дерева зависимостей между файлами
- ⚙️ **Гибкая конфигурация** - настройка по умолчанию для автора, глубины зависимостей и других параметров
- 🛠️ **Режимы работы** - dry-run, debug, force-republish и другие
- 🧪 **Полное покрытие тестами** (472+ тестов) с методологией TDD

### Техническое совершенство
- ⚡ **Bun runtime** - максимальная производительность
- 🔒 **TypeScript** - полная типизация и безопасность
- 📏 **Проактивная валидация** - проверка размера контента (64 КБ лимит)
- 🎯 **Telegraph API** - прямая работа с официальным API

## 📦 Установка

```bash
git clone <repository-url>
cd telegraph-publisher
bun install
```

## 🎯 Быстрый старт

### Первичная настройка
```bash
# Установить автора по умолчанию
telegraph-publisher config --username "Ваше имя"

# Опубликовать первый файл с токеном
telegraph-publisher pub -f article.md --token YOUR_TOKEN
```

### Основное использование
```bash
# Публикация одного файла
telegraph-publisher pub -f article.md -a "Автор"

# Публикация со всеми зависимостями
telegraph-publisher pub -f main.md -a "Автор" --with-dependencies

# Публикация всей директории
telegraph-publisher pub -a "Автор"

# Принудительная перепубликация
telegraph-publisher pub -f article.md --force-republish
```

## 📚 Подробное руководство

### 🎯 Унифицированная команда `publish` (рекомендуется)

Основная команда для всех операций публикации:

```bash
telegraph-publisher publish [опции]
telegraph-publisher pub [опции]  # короткая форма
```

**Основные опции:**
- `-f, --file <path>` - Путь к Markdown файлу (если не указан, публикует всю директорию)
- `-a, --author <name>` - Имя автора (переопределяет настройки по умолчанию)
- `--title <title>` - Заголовок статьи (автоматически извлекается из файла если не указан)
- `--author-url <url>` - URL автора
- `--token <token>` - Access token (сохраняется автоматически после первого использования)

**Управление зависимостями:**
- `--with-dependencies` - Автоматически публиковать связанные файлы (по умолчанию: true)
- `--no-with-dependencies` - Пропустить публикацию зависимостей

**Режимы публикации:**
- `--force-republish` - Принудительная перепубликация даже для неизменённых файлов
- `--force` - Обход проверки ссылок (для отладки)
- `--dry-run` - Предварительный просмотр без фактической публикации
- `--debug` - Сохранить сгенерированный Telegraph JSON в файл (подразумевает --dry-run)

**Table of Contents:**
- `--aside` - Автоматически генерировать оглавление (по умолчанию: true)
- `--no-aside` - Отключить генерацию оглавления

**Проверка ссылок:**
- `--no-verify` - Пропустить обязательную проверку локальных ссылок
- `--no-auto-repair` - Отключить автоматическое исправление ссылок

### 📊 Анализ зависимостей

```bash
telegraph-publisher analyze [опции]
```

**Опции:**
- `-f, --file <path>` - Путь к файлу для анализа
- `--depth <number>` - Максимальная глубина анализа зависимостей (по умолчанию: 1)
- `--show-tree` - Показать визуализацию дерева зависимостей

**Пример вывода:**
```
📊 Dependency Analysis Results:
📄 main.md (PUBLISHED)
├── 📄 chapter1.md (NOT PUBLISHED)
│   ├── 📄 appendix1.md (PUBLISHED)
│   └── 📄 references.md (NOT PUBLISHED)
└── 📄 chapter2.md (PUBLISHED)
    └── 📄 images/diagram.png (EXTERNAL)
```

### ⚙️ Управление конфигурацией

```bash
telegraph-publisher config [опции]
```

**Опции:**
- `--show` - Показать текущую конфигурацию
- `--username <name>` - Установить автора по умолчанию
- `--max-depth <number>` - Установить максимальную глубину зависимостей
- `--auto-deps <boolean>` - Включить/отключить автоматическую публикацию зависимостей
- `--set <key=value>` - Установить значение конфигурации
- `--reset` - Сбросить конфигурацию к настройкам по умолчанию

### 📋 Проверка статуса

```bash
telegraph-publisher status [опции]
```

**Опции:**
- `-f, --file <path>` - Путь к файлу для проверки статуса
- `--show-deps` - Показать статус зависимостей
- `--show-cache` - Показать информацию о кэше

### 🔧 Проверка и исправление ссылок

```bash
telegraph-publisher check-links [path] [опции]
```

**Опции:**
- `--fix` - Автоматически исправить найденные проблемы
- `--apply-fixes` - Применить исправления интерактивно
- `--report` - Создать подробный отчёт о ссылках

### 🔄 Сброс состояния

```bash
telegraph-publisher reset [опции]
```

**Опции:**
- `--cache` - Очистить кэш страниц
- `--metadata` - Удалить метаданные из файлов
- `--config` - Сбросить конфигурацию
- `--all` - Сбросить все данные

### 🧹 Очистка Markdown

```bash
telegraph-publisher clean-md --file <path>
```

Удаляет избыточные пробелы и пустые строки из Markdown файлов.

### 📋 Список страниц (Legacy)

```bash
telegraph-publisher list-pages --token <token>
```

## 🎨 Поддерживаемый Markdown

### Стандартные элементы
- **Заголовки**: `# H1` - `###### H6` с автоматической генерацией якорей
- **Текстовое форматирование**: `**жирный**`, `*курсив*`, `` `код` ``
- **Ссылки**: `[текст](URL)` с автоматической заменой локальных путей
- **Списки**: Нумерованные и маркированные с поддержкой вложенности
- **Цитаты**: `> Блок-цитата`
- **Горизонтальные линии**: `---` или `***`
- **Блоки кода**: Тройные обратные кавычки с подсветкой синтаксиса

### Расширенные функции

#### Table of Contents (ToC)
Автоматическая генерация оглавления в виде `<aside>` блока:
- Поддержка заголовков всех уровней (H1-H6)
- H5/H6 отображаются как H4 с визуальными префиксами (`> H5`, `>> H6`)
- Автоматические якорные ссылки
- Интеллектуальная обработка ссылок в заголовках (предотвращение вложенных ссылок)

#### Таблицы
Автоматическое преобразование в читаемый формат:

**Входные данные:**
```markdown
| Продукт | Цена | Количество |
|---------|------|------------|
| Яблоки  | 100  | 5 кг       |
| Бананы  | 80   | 2 кг       |
```

**Результат:**
- 1
  - Продукт: Яблоки
  - Цена: 100
  - Количество: 5 кг
- 2
  - Продукт: Бананы
  - Цена: 80
  - Количество: 2 кг

## 🔗 Интеллектуальное управление ссылками

### Типы ссылок
- **Локальные файлы**: `[текст](./file.md)` → автоматическая замена на Telegraph URL
- **Якорные ссылки**: `[текст](#section)` → проверка существования якорей
- **Внешние URL**: `[текст](https://example.com)` → проверка доступности
- **Относительные пути**: `[текст](../folder/file.md)` → разрешение путей

### Автоматические исправления
- Исправление регистра файлов (`File.md` → `file.md`)
- Добавление расширений (`.md`, `.markdown`)
- Исправление путей (`file` → `./file.md`)
- Обновление устаревших ссылок

### Проверки безопасности
- Обнаружение циклических зависимостей
- Валидация существования файлов
- Проверка доступности внешних ресурсов
- Анализ целостности структуры проекта

## 📁 Структура файлов и метаданные

### YAML Front-matter
Автоматически добавляется к опубликованным файлам:

```yaml
---
telegraphUrl: "https://telegra.ph/article-title-01-01"
editPath: "article-title-01-01"
username: "author-name"
publishedAt: "2025-01-01T12:00:00.000Z"
originalFilename: "article.md"
title: "Article Title"
contentHash: "sha256-hash-of-content"
---
```

### Кэш страниц
Система автоматически кэширует информацию о публикациях:
- Быстрый доступ к метаданным
- Отслеживание изменений контента
- Оптимизация повторных публикаций

## 🎯 Практические примеры

### Публикация книги по главам
```bash
# Настройка
telegraph-publisher config --username "Автор Книги" --max-depth 5

# Публикация главной страницы со всеми зависимостями
telegraph-publisher pub -f book/index.md --with-dependencies

# Анализ структуры
telegraph-publisher analyze -f book/index.md --show-tree
```

### Работа с блогом
```bash
# Публикация отдельного поста
telegraph-publisher pub -f posts/2025-01-01-new-post.md

# Проверка и исправление ссылок
telegraph-publisher check-links posts/ --apply-fixes

# Массовая публикация
telegraph-publisher pub posts/
```

### Отладка и тестирование
```bash
# Предварительный просмотр
telegraph-publisher pub -f article.md --dry-run

# Отладка с сохранением JSON
telegraph-publisher pub -f article.md --debug

# Принудительная переиндексация
telegraph-publisher pub -f article.md --force-republish
```

## 🛠️ Разработка

### Запуск тестов
```bash
# Все тесты
bun test

# С покрытием
bun test --coverage

# В режиме наблюдения
bun test --watch

# Только unit тесты
bun test src/**/*.test.ts
```

### Режим разработки
```bash
# Запуск с перезагрузкой
bun --watch src/cli.ts pub --file test-article.md --dry-run

# Сборка
bun run build
```

### Структура проекта
```
telegraph-publisher/
├── src/
│   ├── cli/                     # CLI интерфейс и команды
│   │   ├── EnhancedCommands.ts  # Все современные команды
│   │   └── ProgressIndicator.ts # Индикация прогресса
│   ├── workflow/                # Рабочие процессы
│   │   └── PublicationWorkflowManager.ts
│   ├── publisher/               # Система публикации
│   │   └── EnhancedTelegraphPublisher.ts
│   ├── dependencies/            # Управление зависимостями
│   │   └── DependencyManager.ts
│   ├── links/                   # Система обработки ссылок
│   │   ├── LinkScanner.ts       # Сканирование ссылок
│   │   ├── LinkVerifier.ts      # Проверка ссылок
│   │   ├── AutoRepairer.ts      # Автоисправление
│   │   └── BidirectionalLinkResolver.ts
│   ├── metadata/                # Управление метаданными
│   │   └── MetadataManager.ts
│   ├── cache/                   # Система кэширования
│   │   └── PagesCacheManager.ts
│   ├── content/                 # Обработка контента
│   │   └── ContentProcessor.ts
│   ├── config/                  # Управление конфигурацией
│   │   └── ConfigManager.ts
│   ├── utils/                   # Утилиты
│   ├── types/                   # TypeScript типы
│   ├── markdownConverter.ts     # Конвертация Markdown
│   ├── telegraphPublisher.ts    # Базовый Telegraph API
│   ├── clean_mr.ts              # Очистка Markdown
│   └── cli.ts                   # Главный CLI
├── dist/                        # Собранные файлы
├── tests/                       # Интеграционные тесты
└── package.json
```

## 🔧 API для разработчиков

### EnhancedTelegraphPublisher
```typescript
import { EnhancedTelegraphPublisher } from "./src/publisher/EnhancedTelegraphPublisher";

const publisher = new EnhancedTelegraphPublisher();

// Публикация с метаданными
const result = await publisher.publishWithMetadata(
  "article.md", 
  "author-name",
  {
    withDependencies: true,
    generateAside: true,
    dryRun: false
  }
);
```

### DependencyManager
```typescript
import { DependencyManager } from "./src/dependencies/DependencyManager";

const manager = new DependencyManager(config, pathResolver);
const analysis = await manager.analyzeDependencies("main.md");
console.log(analysis.publishOrder); // Порядок публикации
```

### LinkVerifier
```typescript
import { LinkVerifier } from "./src/links/LinkVerifier";

const verifier = new LinkVerifier();
const results = await verifier.verifyFile("article.md");
console.log(results.brokenLinks); // Сломанные ссылки
```

## ⚡ Производительность и оптимизация

### Кэширование
- Автоматическое кэширование метаданных страниц
- Hash-based определение изменений контента
- Пропуск публикации неизменённых файлов

### Оптимизация сети
- Batch-обработка зависимостей
- Параллельная проверка ссылок
- Rate limiting для Telegraph API

### Память и производительность
- Потоковая обработка больших файлов
- Эффективное управление памятью
- Быстрый Bun runtime

## 🔒 Безопасность

### Валидация контента
- Проверка на недопустимый HTML
- Валидация размера контента (64 КБ лимит)
- Санитизация пользовательского ввода

### Управление токенами
- Автоматическое сохранение access token
- Безопасное хранение конфигурации
- Поддержка переменных окружения

## 📋 Конфигурация

### Файл конфигурации (`.telegraph-publisher-config.json`)
```json
{
  "accessToken": "your-access-token",
  "defaultUsername": "Default Author",
  "maxDependencyDepth": 10,
  "autoPublishDependencies": true
}
```

### Переменные окружения
- `TELEGRAPH_TOKEN` - Access token
- `TELEGRAPH_USERNAME` - Автор по умолчанию
- `TELEGRAPH_MAX_DEPTH` - Максимальная глубина зависимостей

## 📈 Статистика проекта

- **Тестов**: 472+ (100% покрытие критического кода)
- **Файлов**: 50+ TypeScript модулей
- **Команд**: 8 основных команд CLI
- **Функций**: 200+ документированных функций
- **Типов**: 50+ TypeScript интерфейсов

## 🏆 Преимущества

- **Полная автоматизация** рабочего процесса публикации
- **Интеллектуальное управление** зависимостями и ссылками
- **Высокая производительность** благодаря кэшированию и оптимизации
- **Безопасность и надёжность** с комплексной валидацией
- **Гибкость конфигурации** под любые потребности
- **Отличное покрытие тестами** для стабильности

## 🤝 Вклад в проект

Проект развивается с использованием методологии Test-Driven Development (TDD). 
Приветствуются pull requests, bug reports и предложения по улучшению.

## 📄 Лицензия

MIT

## 👨‍💻 Автор

Создано с использованием современных подходов к разработке CLI инструментов и методологии TDD.

---

*Response generated using Claude 3.5 Sonnet*