Giget

Ported functionality from https://github.com/unjs/giget for own use.

Концепты

Registry - содержит метаописание для шаблона. Как минимум это имя шаблона и путь по которому искать архив с исходными файлами шаблона. Регистр представляет собой публичный список файлов метаописания шаблонов. Это нужно для создания абстракции по поиску исходников. Проще всего, и подразумевается, что регистр будет опубликован в GitLab или GitHub.

Archive - требуется указать ссылку на архив который будет доступен для скачивания по ссылке. Это позволяет сохранить его где угодно. Использование утилиты подразумевает что код шаблонов и архивы будут сохранены в GitLab или GitHub.

Используется для получения начального кода из архива, поэтому что это за код и для чего он будет скопирован - не имеет значения. Без разницы на каком языке написаны файлы шаблона, их структура и так далее.

{
  "name": "some-template", 
  "tar": "https://gitlab.com/super-vendor/npm/library/super-template/-/archive/master/super-template.tar.gz", 
  "url": "https://awesome.net", 
  "defaultDir": "awesome" 
}

Абстракция

some-template -> super-template -> awesome

В данном случае при запросе шаблона с именем some-template копирование произойдет из репозитория с любым другим имененем, например super-template из организации super-vendor, в указанную папку с произвольным названием или указанным в метаописании названием по умолчанию awesome.

Ссылка на архив позволяет создать шаблоны с разными именами, но указывающими на один и тотже репозиторий, но разные ветки или коммиты, или даже подпапки.

В таком случае разные имена шаблона(разные шаблоны по факту) будут указывать на разные ветки одного репозитория, однако копирование исходников произойдет в папку с одним и тем же названием.

Версионирование

Концепция утилиты не подразумевает версионирования шаблонов изначально.

Вместо:

• awesome
• awesome#dev
• [email protected]
• [email protected]#dev

Необходимо использовать любое возможное, но понятное именование

• template
• edge-template
• template-v1
• legacy-template

Версионирование необходимо производить на уровне метаописания, где для ссылки на архив можно указать разные версии или ветки репозитория. Так задумано, чтобы пользователь утилиты не думал о версиях шаблона. Тем более, сама концепция загрузки кода шаблона для старта нового проекта не подразумевает "обновления" или отслеживания изменений в шаблоне.

Подпуть

Когда нужно запускать собственный CI для шаблона, код удобно положить в подпапку, например src. Чтобы вручную не переносить код после извлечения шаблона, можно указать подпуть в описании шаблона

{
  ...
  "subpath": "src" // or src/ or src/some or src/some/
}

Registry built in

Адрес регистра прописан в коде. Можно указать опцию --registry для замены.

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

npx @a4sex/giget some-template --registry https://gitlab.com/a4sex/giget-registry/-/raw/main/templates

Авторизация при получении архива

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

• Приоритет источников токена:

  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 (заголовок Authorization: Bearer <token>)
  4. GitLab CI: CI_JOB_TOKEN (используется с заголовком JOB-TOKEN)

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

  • Для обычных токенов: PRIVATE-TOKEN: <token>
  • Для OAuth/Bearer токенов: Authorization: Bearer <token>
  • Для CI_JOB_TOKEN: JOB-TOKEN: <token>

Примеры:

# CLI аргумент имеет максимальный приоритет
npx @a4sex/giget some-template --auth <read-access-token>

# Через переменную окружения (локально)
export REGISTRY_TOKEN=<read-access-token>
npx @a4sex/giget some-template

# В GitLab CI автоматически подхватится CI_JOB_TOKEN
npx @a4sex/giget some-template