Gitemplate

Модульная CLI‑утилита для работы с шаблонами (templates) и фрагментами (fragments) кода. Помогает быстро стартовать новые проекты и поддерживать стандарты в существующих за счёт применения готовых архивов и обязательных блоков конфигурации. Поддерживает интерактивный режим и работу в CI.

Содержание

• Установка
• Быстрый старт
• Использование
• Документация
• Конфигурация
• Дорожная карта
• Вклад
• Безопасность
• Лицензия

Установка

yarn add @a4sex/gitemplate --dev

yarn global add @a4sex/gitemplate

yarn global upgrade @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

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

Краткий справочник по командам и флагам доступен в руководстве.

• Команда template — загрузка и распаковка шаблона по имени из реестра
• Команда fragment — применение фрагментов к локальным файлам
• Команда registry — просмотр дерева и генерация registry.yaml
• Команда config — печать/инициализация локального .gitemplate

Подробнее со сценариями и примерами см. docs/cli.md.

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

• Обзор и концепции: docs/concepts.md
• Шаблоны: docs/templates.md
• Фрагменты: docs/fragments.md
• Реестр и форматы: docs/registry.md
• Интерактивный режим: docs/interactive.md
• Стиль CLI/тексты помощи: docs/develop/cli-styleguide.md
• Аутентификация/секреты: docs/security/authentication.md

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

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

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

• 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

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

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

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

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

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

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

См. ROADMAP.md.

Вклад

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

• Стиль CLI и тексты помощи: docs/develop/cli-styleguide.md
• Архитектурные материалы: docs/develop/architecture.md
• Разделы для разработчиков: docs/develop/*

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

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

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

Лицензия

MIT — см. LICENSE.