@a4sex/gitemplate

v1.15.3

Published

3 months ago

> Enterprise-ready CLI утилита для работы с шаблонами и фрагментами кода

0High
0Medium
0Low

tebaly

Gitemplate

Enterprise-ready CLI утилита для работы с шаблонами и фрагментами кода

Модульная CLI‑утилита для работы с шаблонами (templates) и фрагментами (fragments) кода, помогающая быстро стартовать новые проекты и поддерживать стандарты в существующих за счёт применения готовых архивов и обязательных блоков конфигурации. Проект развивается по двум стратегическим направлениям охватывающим фундаментальную архитектуру с модульной слоистой структурой Core/Services/Entities/CLI слоями включая comprehensive систему командной строки с интерактивными диалогами централизованные сервисы управления шаблонами и фрагментами унифицированную работу с различиями файлов и управление конфликтами базовые сервисы управления конфигурацией и аутентификацией self-synchronizing логирование инкапсуляцию состояния graceful error handling и Core фасады для стабилизации точек входа, инфраструктурные сервисы и автоматизацию качества включая централизованное управление конфигурацией через ConfigService и обработку форматов YAML/JSON/INI через StructuredContentService и FormatService с настраиваемыми опциями интеграцию markdownlint-cli2 для контроля качества документации достигшей 94% улучшения глобальное архивирование AI-контекста с иерархической структурой и автоматизацией, создавая надежную enterprise-ready экосистему для работы с переиспользуемыми компонентами кода. Поддерживает интерактивный режим и работу в CI.

Содержание

Установка

Глобальная установка (рекомендуется для CLI)

Для использования команды gitemplate в терминале:

# Установка через npm
npm install -g @a4sex/gitemplate

# Или через yarn
yarn global add @a4sex/gitemplate

# Обновление
npm update -g @a4sex/gitemplate
# или
yarn global upgrade @a4sex/gitemplate

После установки команда gitemplate будет доступна глобально:

gitemplate --help
which gitemplate

Локальная установка в проект

Если нужно использовать пакет как зависимость:

# Установка в devDependencies
npm install --save-dev @a4sex/gitemplate
# или
yarn add @a4sex/gitemplate --dev

# Использование через npx/yarn
npx gitemplate --help
yarn gitemplate --help

Разработка (установка из исходников)

Для локальной разработки и тестирования:

# Клонировать репозиторий
git clone git+ssh://[email protected]/a4sex/npm/library/gitemplate.git
cd gitemplate

# Установить зависимости
yarn install
# или
npm install

# Создать глобальную ссылку (важно: использовать npm link, не yarn link!)
npm link
# ИЛИ для одного терминала
alias gt='node ~/GIT/a4sex/npm/library/gitemplate/src/index.mjs'

# Теперь команда gitemplate доступна глобально и использует локальный код
gitemplate --help

Важно: Для CLI инструментов используйте npm link (не yarn link), так как только npm link устанавливает bin команды глобально. yarn link регистрирует пакет только для использования в других проектах.

Для удаления ссылки:

npm unlink -g @a4sex/gitemplate

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

# Применить шаблон по имени из реестра
gitemplate template <name> \
  --registry https://gitlab.com/a4sex/giget-registry/-/raw/main/templates \
  --directory ./my-app

# Применить фрагмент к локальному файлу
gitemplate fragment \
  --link https://example.com/fragment.txt \
  --filename README.md \
  --strategy contains \
  --mode merge

# Выполнить действия из локального .gitemplate (если есть)
gitemplate

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

Основные команды

GitTemplate предоставляет четыре основные команды для работы с шаблонами и фрагментами:

Template — загрузка шаблонов

Загрузка и распаковка шаблона по имени из реестра:

gitemplate template <name> \
  --registry https://example.com/registry \
  --directory ./target-dir \
  --auth <token>

Fragment — применение фрагментов

Применение фрагментов к локальным файлам:

gitemplate fragment \
  --link https://example.com/fragment.txt \
  --filename target-file.yaml \
  --strategy contains \
  --mode merge

Стратегии применения:

contains — проверка наличия содержимого
equals — сравнение полного содержимого файла
block — работа с маркированными блоками

Режимы обработки:

notify — только уведомление о различиях
merge — автоматическое слияние изменений
error — остановка при обнаружении различий

Registry — управление реестром

Просмотр дерева и генерация registry.yaml:

# Просмотр дерева реестра
gitemplate registry \
  --url https://example.com/registry

# Генерация registry.yaml
gitemplate registry \
  --url https://example.com/registry \
  --save

Config — конфигурация

Печать и инициализация локального .gitemplate:

# Показать текущую конфигурацию
gitemplate config

# Инициализировать новую конфигурацию
gitemplate config --init

Подробнее со сценариями и примерами см. CLI Documentation.

Ключевые возможности

Модульная архитектура

Слоистая архитектура с четким разделением ответственности:

CLI слой — фасад для пользовательских команд
Core слой — бизнес-логика и orchestration
Services слой — адаптеры I/O и внешних систем
Entities слой — модели данных и DTO
Utils слой — вспомогательные утилиты

Интерактивные диалоги

6 специализированных интерактивных диалогов для всех основных операций:

Выбор шаблона из реестра
Настройка параметров применения
Управление фрагментами
Конфигурирование режимов обработки
Работа с аутентификацией
Просмотр и управление реестром

Унифицированная работа с различиями

Централизованная система управления диффами через GitDiffService:

Режимы diff: brief, full, none
Глобальные glob-фильтры для include/exclude
Консистентное форматирование через DiffPrinter
Интеграция с нативным git для максимальной точности

Гибкая обработка фрагментов

Comprehensive система стратегий и режимов:

Стратегии: contains, equals, block для различных сценариев
Режимы: notify, merge, error для контроля поведения
Форматы: YAML, JSON, INI, text с автоопределением
Array merge для умного слияния массивов

Централизованная конфигурация

ConfigService для единой точки управления настройками:

Singleton pattern для глобального доступа
Автоматическая нормализация параметров
Поддержка .gitemplate файлов
CLI флаги с приоритетом над конфигом

Безопасная аутентификация

Unified authentication через AuthManager:

Поддержка GitLab токенов (Private, OAuth, CI)
Приоритетная цепочка источников токенов
Безопасное хранение без логирования
Работа с приватными реестрами

Enterprise-grade качество

94% улучшение качества markdown документации через markdownlint-cli2
Comprehensive тестирование с высоким покрытием
Graceful error handling с fallback стратегиями
Self-synchronizing логирование с автоматической настройкой

Документация

Концепции и руководства

Обзор и концепции — основные понятия и термины
Шаблоны (Templates) — работа с шаблонами проектов
Фрагменты (Fragments) — применение фрагментов конфигураций
Реестр и форматы — управление реестром шаблонов
Интерактивный режим — использование диалогов
Конфигурация — настройка .gitemplate

Разработка

Архитектура — техническая архитектура проекта
Стиль CLI — стандарты CLI и тексты помощи
Архитектурные решения — ADR и принятые решения
Технические решения — история технических решений

Аутентификация и безопасность

Аутентификация — управление токенами и секретами

Генерация и проверка документации кода

Проект использует единые стандарты документирования кода с автоматической генерацией и валидацией.

Стандарты документирования

JavaScript/TypeScript: TSDoc с JSDoc-совместимыми тегами
Видимость: @public/@beta/@alpha/@internal для контроля API
Обязательные блоки: @remarks, @example, @throws для публичных API
Типы: не дублировать из сигнатур, фокус на назначении и примерах

Инструменты

Линтинг: eslint-plugin-jsdoc с правилами для TSDoc
Генерация: TypeDoc для HTML/Markdown документации
API контроль: @microsoft/api-extractor для стабильности публичного API

Команды

# Генерация полной документации (TypeDoc + API отчеты)
yarn docs

# Только TypeDoc (HTML/Markdown)
yarn docs:js

# API Extractor отчет (контроль публичного API)
yarn api:report

# Линтинг JSDoc комментариев
yarn lint:jsdoc

CI/CD интеграция

Документация автоматически проверяется в CI:

Линтинг комментариев на каждый PR
Генерация и публикация артефактов
Контроль breaking changes в публичном API

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

Локальный файл .gitemplate описывает реестр, шаблоны и фрагменты, которые нужно применить за один запуск.

# .gitemplate
registry:
  url: https://gitlab.com/a4sex/giget-registry/-/raw/main/templates

templates:
  - name: npm-lib-startpoint
    directory: ./lib
    # subpath, ignore, files — при необходимости

fragments:
  - link: https://example.com/fragment.txt
    strategy: block
    mode: merge
    filename: .gitlab-ci.yml
    markerStart: "# BEGIN: JOB: deploy"
    markerEnd:   "# END: JOB: deploy"

# По желанию: глобальный режим поведения для fragments
fragmentsMode: notify

Авторизация при доступе к реестру/архивам

Поддерживаются несколько типов токенов. Источники в порядке приоритета:

CLI: --auth <token>
Переменные окружения: REGISTRY_TOKEN, GITLAB_TOKEN, PRIVATE_TOKEN, GL_TOKEN, GITLAB_PRIVATE_TOKEN
OAuth/Bearer: GITLAB_OAUTH_TOKEN, OAUTH_TOKEN, ACCESS_TOKEN, BEARER_TOKEN
GitLab CI: CI_JOB_TOKEN

Заголовки запроса:

Обычные токены: PRIVATE-TOKEN: <token>
OAuth/Bearer: Authorization: Bearer <token>
GitLab CI: JOB-TOKEN: <token>

Архитектура

Проект построен на слоистой модульной системе с современными паттернами:

Слои архитектуры

CLI слой — фасад для пользовательских команд:

TemplateCommand, FragmentCommand, RegistryCommand, ConfigCommand
Валидация входных параметров
Интерактивные диалоги

Core слой — бизнес-логика и orchestration:

TemplateService, FragmentsService, RegistryBuilder
TemplatesHandler, FragmentsFacade для стабилизации точек входа
Централизация правил и workflow

Services слой — адаптеры I/O и внешних систем:

DownloadService для загрузки шаблонов
GitDiffService для работы с различиями
ConfigService для управления настройками
AuthManager для unified аутентификации
StructuredContentService и FormatService для обработки форматов

Entities слой — модели данных:

DTO и value objects
Типы конфигураций
Метаданные шаблонов и фрагментов

Utils слой — вспомогательные утилиты:

Форматирование и парсинг
Работа с файловой системой
Логирование

Ключевые паттерны

Singleton: ConfigService для глобального доступа к конфигурации
Strategy: обработчики форматов файлов (YAML/JSON/INI)
Facade: FragmentsFacade, TemplatesHandler для упрощения интерфейсов
Dependency Injection: передача зависимостей через параметры
Private Fields: инкапсуляция через ES2022 # поля

Подробнее см. Архитектура проекта и ADR.

Дорожная карта

Проект развивается по двум стратегическим направлениям:

THEME-01: Core Architecture & Services (❎ Завершено):

Модульная слоистая архитектура
Интерактивные CLI диалоги
Download Service с поддержкой merge
GitDiff Service с унификацией работы с диффами
Processing Mode Service для управления конфликтами
Core фасады для стабилизации точек входа

THEME-02: Infrastructure & Quality Services (❎ Завершено):

Markdownlint integration (94% улучшение)
AI Context Archiving System
ConfigService centralization
Structured content services unification

Планируемые улучшения (Q1-Q2 2026):

Dry-run режим для безопасного предварительного просмотра
Улучшенный diff для фрагментов с подсветкой
Кэширование архивов шаблонов
Прогресс-бары и телеметрия
Расширенная валидация
Параллельная обработка
JSON отчеты для CI/CD

Подробнее см. ROADMAP.md.

Вклад

Приветствуются pull‑request'ы и улучшения документации. Соблюдайте локальные правила и стиль CLI.

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

Не храните токены/пароли в коде и истории git
Используйте переменные окружения и .env (см. Аутентификация)
Перед коммитом можно выполнить проверку:

git diff --cached | grep -iE "(api_key|token|password|secret)" || true

Лицензия

MIT — см. LICENSE.

Навигация: