diff --git a/.research/260824_tz-docs-build-https.md b/.research/260824_tz-docs-build-https.md new file mode 100644 index 0000000..32cfc48 --- /dev/null +++ b/.research/260824_tz-docs-build-https.md @@ -0,0 +1,92 @@ +# ТЗ: доки cocoaskills под приватный HTTPS (build_https) + +Дата: 2026-08-24. Основание: feat/build-https-broker влита в main +(be88caa, 9a1f9da, 5381317 поверх 97cfa77), задача борда +TASK-260824-1dop3s принята ревью. Сьют 1576 passed. + +Правки, которые main УЖЕ содержит (переделывать не нужно): +external-build-repositories.md (секция приватного HTTPS: брокер, три +источника токена, скоупы, precheck, кроссплатформенный механизм, +предупреждение про непиненный override), cli.md (группа csk config +build-https add/login/list/remove + CSK_BUILD_HTTPS_TOKEN / +CSK_BUILD_HTTPS_HOST), reference.md (поле build_https: грамматика +скоупов, источники, precedence), CHANGELOG.md (запись в Unreleased). + +## 1. README.md: quickstart для приватных репозиториев (обязательно) + +Рядом с существующим SSH-блоком, тем же тоном, 6-10 строк: +- одна фраза: приватный репозиторий сборки работает и по SSH, и по HTTPS; +- для HTTPS ничего заводить не надо, если человек уже клонирует по HTTPS: + csk предложит переиспользовать его собственные креды при первой + установке (один Enter); +- команда для неинтерактивного случая: + csk config build-https add gitlab.example.com/portals/infra --token git-credentials +- строка про CI: CSK_BUILD_HTTPS_TOKEN (+ CSK_BUILD_HTTPS_HOST, если + билд-репозитории живут на разных хостах); +- закрывающая фраза в духе существующей: пакет скилла креды выбрать не + может. + +## 2. docs/skill-authoring.md §3 (schema v7): транспорт не диктует доступ + +Строки ~326-330 говорят только про SSH. Переписать абзац: +- в build_repositories.*.git допустимы обе формы: git@host:path.git и + https://host/path.git; +- приватный репозиторий в обоих случаях требует явного выбора кредов + оператором: скоупы build_ssh и build_https соответственно; +- выбор транспорта не решает, у кого установка получится: SSH требует + ключ, HTTPS требует существующие креды Git или токен; +- ссылку на docs/external-build-repositories.md сохранить. + +ЯВНО упомянуть: HTTPS URL в манифесте обязан нести суффикс .git. Без +него GitLab отвечает 301, fetch идёт с http.followRedirects=false, и +установка падает build_repository_source_unavailable. Это требование к +манифесту; писать там, где авторы пишут URL. + +## 3. docs/troubleshooting.md: две новые записи + +Формат существующий (симптом, причина, команда). + +build_repository_credential_policy_invalid: скоуп выбран, источник +ничего не дал. Три ветки, по команде на каждую: не установлена +переменная из token_env; token: keyring без сохранённого токена +(лечение: csk config build-https login ); token: git-credentials +без записи у helper'а для хоста (клонировать один раз по HTTPS либо +login). Текст ошибки называет конкретный случай. + +fatal: ... The requested URL returned error: 301: HTTPS URL без +суффикса .git; fetch не следует редиректам by design. Лечение: добавить +.git в build_repositories.*.git. Симптом ловится как +build_repository_source_unavailable, запись должна находиться и по +этому коду. + +Windows-специфика (там же или в записи про login): git credential +approve рапортует успех, даже когда Windows Credential Manager +недоступен; csk ловит это перечитыванием и говорит, что делать; +рецепты: интерактивная сессия либо git config --global +credential.credentialStore dpapi. Проверено на живой Windows-машине. + +## 4. docs/reference.md: матрица установки + +Проверить, упоминает ли матрица вариантов установки, что компилируемые +команды (go-repository-v1) поддерживаются только на macOS и Windows. +Если нет: добавить строку, что на Linux скилл с такой командой не +установится независимо от кредов, отказ происходит до старта воркера. + +## Ограничения + +- Язык каждого файла сохранять, не смешивать внутри файла. +- docs/prose-style.md обязателен; тире как риторическая связка запрещено + в любом языке. +- Секреты в примерах не показывать; токен нигде не принимается флагом. +- Каждый пример прогнать на csk из дерева (.venv/bin/csk, НЕ brew) и + сверить с фактическим выводом. + +## Приёмка + +1. Ссылки из README ведут на новые разделы; проверка ссылок зелёная. +2. Ни одного примера, которого нет в CLI (сверить с + .venv/bin/csk config build-https --help). +3. Автор скилла из одного skill-authoring.md знает про обе формы URL и + обязательный .git в HTTPS. +4. Человек с build_repository_credential_policy_invalid находит свою + ветку и команду в troubleshooting.md. diff --git a/LOGBOOK.md b/LOGBOOK.md index 9e44f92..7e61716 100644 --- a/LOGBOOK.md +++ b/LOGBOOK.md @@ -122,6 +122,28 @@ last members are routinely mid-exit when the first group signal is sent. The reg The failure never reproduced on the fast tier because it is a per-teardown dice roll of roughly one in fourteen, and each E2E job performs a handful of teardowns. Re-running the red job turned it green, which is the shape a flake has and the shape a broken merge does not. +## 2026-08-24 - TASK-260824-2rzwqa troubleshooting entries for build_https and reference matrix fix + +Added two troubleshooting entries in `docs/troubleshooting.md` following the symptom-cause-remedy format and updated `docs/reference.md` installation matrix: + +1. `build_repository_credential_policy_invalid`: documents the three branches (`token_env` with missing env var, `keyring` with no stored token, `git-credentials` with no helper entry) and their resolution commands. Includes the Windows note attributing token verification failure to `csk config build-https login` when Windows Credential Manager is unavailable (`your Git credential helper did not persist the token`), with remedies for interactive sessions and DPAPI (`git config --global credential.credentialStore dpapi`). +2. `build_repository_source_unavailable / fatal: ... The requested URL returned error: 301`: documents HTTPS URL missing `.git` suffix causing HTTP 301 redirects, `http.followRedirects=false` behavior, and remedy of appending `.git` to `build_repositories.*.git`. Findable by both error codes. +3. `docs/reference.md`: updated the installation matrix line to state that compiled commands `go-repository-v1` are supported only on macOS and Windows, and on Linux the installer rejects skills with such commands before checking credentials or launching worker processes. + +All error strings were verified against `src/csk` source files (`installer.py`, `build_https.py`, `git_admission.py`). Formatting strictly adheres to prose style rules (active voice, no em-dashes or en-dashes, no guillemets, clean list blocks). + +## 2026-08-24 - TASK-260824-1d7zbo README HTTPS quickstart for private build repositories + +The quickstart section for private build repositories in `README.md` previously documented only SSH credentials. With the merge of `feat/build-https-broker` into `main`, private build repositories are also supported over HTTPS. + +A 7-line HTTPS quickstart block was added right next to the SSH block, in matching tone and style: +- States that private build repositories work over both SSH and HTTPS. +- Explains that readers cloning over HTTPS need no extra setup: `csk` offers to reuse their Git credentials at first install with one Enter. +- Documents the non-interactive CLI command: `csk config build-https add gitlab.example.com/portals/infra --token git-credentials`. +- Documents CI environment variables `CSK_BUILD_HTTPS_TOKEN` and `CSK_BUILD_HTTPS_HOST`. +- Concludes with the rule that a skill package can never choose credentials (only the operator chooses explicitly). + +All commands and environment variables were verified against `.venv/bin/csk config build-https --help`. The block strictly follows the documentation prose style (active voice, no em-dashes, colon introducing code block, no secret values). ## 2026-08-24 - TASK-260824-2h0vjy a byte pin needs a byte-stable checkout @@ -2720,3 +2742,8 @@ The implemented workflow still has no hosted run because this worktree must remain uncommitted/unpushed; branch lookup and hosted-run lookup both returned empty. A commit-owning mover must publish the scope and attach two green hosted runs before the task can satisfy its hosted acceptance gate. + + +## 2026-08-24 TASK-260824-3gv521: Schema v7 Build Repository Transport Documentation + +Updated `docs/skill-authoring.md` section 3 (schema v7) to document support for both `git@host:path.git` and `https://host/path.git` transport forms in `build_repositories.*.git`. Clarified that credential selection is required for private repositories in both cases (`build_ssh` and `build_https` scopes), and that choice of transport does not dictate installation access. Stated explicitly that HTTPS URLs must carry the `.git` suffix to avoid GitLab 301 redirects failing under `http.followRedirects=false` with `build_repository_source_unavailable`. Verified error identifier in `src/csk/git_admission.py` and ran `tests/test_git_admission.py` green (exit 0). diff --git a/README.md b/README.md index 0fdb564..90049b6 100644 --- a/README.md +++ b/README.md @@ -150,7 +150,15 @@ csk config build-ssh add gitlab.example.com/portals/infra \ --agent auto --identity ~/.ssh/work.pub ``` -Пакет скилла выбрать креды не может: выбор делает только оператор и только явно. +Приватный репозиторий сборки работает и по SSH, и по HTTPS. Для HTTPS ничего заводить не нужно, если вы уже клонируете по HTTPS: `csk` предложит переиспользовать ваши собственные креды Git при первой установке за один Enter. Для неинтерактивного случая выполните команду: + +```bash +csk config build-https add gitlab.example.com/portals/infra --token git-credentials +``` + +В CI задайте переменную `CSK_BUILD_HTTPS_TOKEN` (и `CSK_BUILD_HTTPS_HOST`, если репозитории сборки живут на разных хостах). + +Пакет скилла выбрать креды не может: выбор делает только оператор и только явно. Подробности устройства брокеров кредов и скоупов описаны в [`docs/external-build-repositories.md`](docs/external-build-repositories.md). ## Режимы установки скиллов @@ -303,6 +311,7 @@ csk shell-init # Генерирует или устанав - [`docs/cli.md`](docs/cli.md): справочник команд `csk`, флагов и кодов завершения. - [`docs/reference.md`](docs/reference.md): справочник по матрице установки, зависимостям скиллов, манифестам и аудиту безопасности. +- [`docs/external-build-repositories.md`](docs/external-build-repositories.md): устройство внешних репозиториев сборки, брокеров кредов SSH/HTTPS и моделей доступа. - [`ARCHITECTURE.md`](ARCHITECTURE.md): описание внутренней архитектуры, схемы работы конвейера установки, формата хранилищ и модели безопасности. - [`SECURITY.md`](SECURITY.md): политика безопасности, границы изоляции и рекомендации по настройке. - [`docs/skill-authoring.md`](docs/skill-authoring.md): руководство по структурированию пакетов скиллов, объявлению команд и настройке манифеста `agent-skill.json`. diff --git a/docs/reference.md b/docs/reference.md index d34b0f8..61cc038 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -6,7 +6,7 @@ CocoaSkills является независимой реализацией от ## Матрица вариантов установки -Установщик поддерживается на платформах macOS, Linux и Windows. +Установщик поддерживается на платформах macOS, Linux и Windows. Компилируемые команды `go-repository-v1` поддерживаются только на macOS и Windows. На Linux установщик отклоняет скилл с такой командой до проверки учётных данных и до запуска воркера. ### pipx diff --git a/docs/skill-authoring.md b/docs/skill-authoring.md index 1f9c691..9b41af8 100644 --- a/docs/skill-authoring.md +++ b/docs/skill-authoring.md @@ -325,10 +325,17 @@ build/vendor/ checked-in modules when non-standard packages a `build_root` содержит `go.mod`; модули вендорятся (`go mod vendor`), сборка идёт без сети. Скомпилированный артефакт никогда не коммитится ни в скилл, -ни во внешний репозиторий. Приватные SSH-источники требуют явного выбора -кредов оператором; полный контракт, включая скоупы `build_ssh` в глобальном -конфиге, описан в `docs/external-build-repositories.md`. `go-repository-v1` -поддерживается только на macOS и Windows. +ни во внешний репозиторий. Поле `build_repositories.*.git` принимает обе формы +адреса: `git@host:path.git` и `https://host/path.git`. Приватный репозиторий +требует явного выбора учётных данных оператором через скоупы `build_ssh` для SSH +и `build_https` для HTTPS. Выбор транспорта не определяет доступность установки: +SSH требует SSH-ключ, HTTPS требует сохранённые учётные данные Git или токен. +Адрес HTTPS в манифесте обязан содержать суффикс `.git`. Без суффикса `.git` +сервис GitLab отвечает 301, fetch выполняется с `http.followRedirects=false`, и +установка завершается ошибкой `build_repository_source_unavailable`. Полный +контракт работы с внешними репозиториями описан в +`docs/external-build-repositories.md`. `go-repository-v1` поддерживается только +на macOS и Windows. ### Схема v8: корни first-party модулей и политика выполнения script-команд diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 7b9dc15..24e3e27 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -42,6 +42,53 @@ csk config build-ssh add / --agent auto --identity ~/.ssh/ Команда записывает скоуп в `~/.cocoaskills/config.json` и печатает `Configured build-ssh scope `. Повторите установку: инсталлятор возьмёт креды из скоупа. +## build_repository_credential_policy_invalid + +Скоуп аутентификации `build_https` совпал в конфигурации, но выбранный источник токена не вернул данные. Текст ошибки называет конкретный случай из трёх возможных: + +1. Правило `token_env` указывает незаданную переменную окружения (`build_https scope '' names environment variable '', which is unset`). Экспортируйте значение переменной из хранилища перед запуском: + + ```bash + export CI_TOKEN="$(pass show ci/gitlab)" + csk install + ``` + +2. Правило `token: keyring` не находит токен в хранилище ключей (`build_https scope '' selects a stored token, but none is saved`). Сохраните токен командой входа: + + ```bash + csk config build-https login + ``` + +3. Правило `token: git-credentials` не находит запись у helper Git для хоста (`build_https scope '' selects your Git credentials, but no helper holds one for ''`). Склонируйте целевой репозиторий по HTTPS один раз через системный Git или сохраните токен через `login`: + + ```bash + csk config build-https login + ``` + +На платформе Windows команда `git credential approve` рапортует об успехе даже при недоступности службы Windows Credential Manager (например, в неинтерактивной сессии без графического входа). Команда `csk config build-https login` перечитывает токен после записи и при отказе сохранения выводит ошибку `your Git credential helper did not persist the token`. Для решения запустите команду в интерактивной сессии или настройте хранилище Git: + +```bash +git config --global credential.credentialStore dpapi +``` + +## build_repository_source_unavailable / fatal: ... The requested URL returned error: 301 + +Адрес HTTPS в поле `build_repositories.*.git` не содержит обязательного суффикса `.git`. Сервис GitLab или Git-хост возвращает ответ 301 Redirect, но установщик выполняет `git fetch` с `http.followRedirects=false` и не следует перенаправлениям по соображениям безопасности. Установщик выводит ошибку `build_repository_source_unavailable: exact external source is unavailable`. Запуск команды `git -c http.followRedirects=false ls-remote ` вручную воспроизводит подробное сообщение `fatal: ... The requested URL returned error: 301`. + +Добавьте суффикс `.git` к адресу репозитория в поле `build_repositories.*.git` манифеста `agent-skill.json`: + +```json +{ + "build_repositories": { + "core": { + "git": "https://gitlab.example.com/portals/infra.git" + } + } +} +``` + +Установщик при повторном запуске выполнит `git fetch` по прямому каноническому адресу без HTTP-редиректа. + ## Cannot resolve tag '...' ... Needed a single revision Локальный клон репозитория в `skills_root` не содержит указанного тега. Команда `csk install` работает по локальным refs и не выполняет сетевой fetch.