8308de0981
* feat(create-readme): add clickable steps and conditional bash block * docs(repo-readme): document clickable steps params and example * docs(handoff): add handoff and ADR for clickable-steps * docs(handoff): set PR number * docs(project-map): update create-readme params after PR#146 --------- Co-authored-by: opencode-agent <agent@opencode.local>
57 lines
No EOL
4.6 KiB
Markdown
57 lines
No EOL
4.6 KiB
Markdown
# ADR-062: Clickable steps in Quick Start + conditional bash block (PR-146)
|
||
|
||
## Статус
|
||
Accepted (2026-07-29)
|
||
|
||
## Контекст
|
||
Тулза `create-readme` генерировала Quick Start как единый bash code-fence
|
||
(``` ```bash ... ``` ```) с опциональной плоской строкой `Access at {url}` /
|
||
`Доступ: {url}` после него. Два ограничения:
|
||
|
||
1. **Markdown-ссылки внутри code-fence не кликабельны** — для multi-step setup
|
||
(userscript: установить скрипт → получить API-ключ → настроить) bash-блок
|
||
не подходит: нужны кликабельные `[text](url)` шаги.
|
||
2. **Пустой bash-блок портил README** — при `quick_start` пустом и
|
||
`include_clone=false` рендерился пустой ` ```bash ``` ` (визуальный мусор).
|
||
3. **`access_url` был bare URL** — авто-линк GitHub делает его кликабельным,
|
||
но явная markdown-ссылка `[url](url)` надёжнее и в raw-просмотре.
|
||
|
||
## Решение
|
||
1. **Новые параметры** `quick_start_steps_en?: string[]` /
|
||
`quick_start_steps_ru?: string[]` — массивы raw-markdown строк. Каждый
|
||
элемент = один шаг, может содержать `[text](url)`.
|
||
2. **Helper `renderSteps(steps?)`** — возвращает `""` для пустого/undefined
|
||
массива, иначе нумерованный список `\n1. ...\n2. ...\n` с пустыми строками
|
||
вокруг (markdown-разделение от code-fence).
|
||
3. **Рендер шагов** — `${renderSteps(...)}` вставлен ПОСЛЕ bash-блока, ДО
|
||
`accessLine*`, в обеих секциях (EN и RU).
|
||
4. **Условный bash-блок** — `hasBashBlock = include_clone !== false ||
|
||
quick_start !== ""`. Если оба false → bash-fence не рендерится (только
|
||
шаги, если есть). `cloneLine` вынесен в общую переменную. Default behavior
|
||
сохранён (`include_clone` не передан → `!== false` → true → git clone).
|
||
5. **Кликабельный `access_url`** — `[url](url)` вместо bare URL.
|
||
6. **Валидатор** — без изменений: шаги вне delimiter-пар, секции "Quick Start" /
|
||
"Быстрый старт" присутствуют всегда (заголовок рендерится независимо).
|
||
|
||
Backward compatibility: все существующие параметры/вызовы работают как раньше.
|
||
Новые параметры опциональны — если не переданы, Quick Start выглядит как
|
||
раньше (bash-блок + опциональный clickable `access_url`).
|
||
|
||
## Альтернативы
|
||
- **Шаги внутри code-fence** — отвергнуто: markdown-ссылки `[text](url)` НЕ
|
||
кликабельны внутри ``` ```bash ``` (рендерятся как текст). Нужен
|
||
нумерованный markdown-список вне code-fence.
|
||
- **Отдельный параметр `steps_mode: "bash" | "list"`** — отвергнуто: bash-блок
|
||
и steps не взаимоисключающи. Можно рендерить bash-команду (установка) И шаги
|
||
(получить ключ, настроить) вместе. Условный bash-блок через `hasBashBlock`
|
||
покрывает все кейсы.
|
||
- **Ослабить required-чек `quick_start` в `execute()`** — отвергнуто: спека
|
||
не просит менять required-валидацию. Сценарий "только шаги без bash" через
|
||
`execute` требует `quick_start: ""` + `include_clone: false`, но `execute`
|
||
отвергает пустой `quick_start`. `generateReadme` обрабатывает `quick_start=""
|
||
` корректно (bash не рендерится). Ослабление required — отдельное решение,
|
||
вне scope этого PR.
|
||
- **Всегда рендерить bash-блок** — отвергнуто: пустой ` ```bash ``` ` портит
|
||
README (исходная проблема). Условный рендер через `hasBashBlock` чище.
|
||
- **`access_url` как inline `[text](url)` с настраиваемым текстом** — отвергнуто:
|
||
спека явно требует `[url](url)` (URL как text). Простой и предсказуемый. |