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

📦 Установка

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

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

Первичная настройка

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

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

Основное использование

# Публикация одного файла
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 (рекомендуется)

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

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 - Отключить автоматическое исправление ссылок

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

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)

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

telegraph-publisher config [опции]

Опции:

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

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

telegraph-publisher status [опции]

Опции:

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

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

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

Опции:

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

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

telegraph-publisher reset [опции]

Опции:

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

🧹 Очистка Markdown

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

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

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

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

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

Стандартные элементы

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

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

Table of Contents (ToC)

Автоматическая генерация оглавления в виде <aside> блока:

• Поддержка заголовков всех уровней (H1-H6)
• H5/H6 отображаются как H4 с визуальными префиксами (> H5, >> H6)
• Автоматические якорные ссылки
• Интеллектуальная обработка ссылок в заголовках (предотвращение вложенных ссылок)

Таблицы

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

Входные данные:

| Продукт | Цена | Количество |
|---------|------|------------|
| Яблоки  | 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

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

---
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"
---

Кэш страниц

Система автоматически кэширует информацию о публикациях:

• Быстрый доступ к метаданным
• Отслеживание изменений контента
• Оптимизация повторных публикаций

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

Публикация книги по главам

# Настройка
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

Работа с блогом

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

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

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

Отладка и тестирование

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

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

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

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

Запуск тестов

# Все тесты
bun test

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

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

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

Режим разработки

# Запуск с перезагрузкой
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

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

import { DependencyManager } from "./src/dependencies/DependencyManager";

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

LinkVerifier

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)

{
  "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