feat(create-readme): add clickable steps to Quick Start (#146 )

* 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>

2026-07-30 03:07:09 +03:00

4.6 KiB

Raw Permalink Blame History

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} после него. Два ограничения:

Markdown-ссылки внутри code-fence не кликабельны — для multi-step setup (userscript: установить скрипт → получить API-ключ → настроить) bash-блок не подходит: нужны кликабельные [text](url) шаги.
Пустой bash-блок портил README — при quick_start пустом и include_clone=false рендерился пустой ```bash ``` (визуальный мусор).
access_url был bare URL — авто-линк GitHub делает его кликабельным, но явная markdown-ссылка [url](url) надёжнее и в raw-просмотре.

Решение

Новые параметры quick_start_steps_en?: string[] / quick_start_steps_ru?: string[] — массивы raw-markdown строк. Каждый элемент = один шаг, может содержать [text](url).
Helper renderSteps(steps?) — возвращает "" для пустого/undefined массива, иначе нумерованный список \n1. ...\n2. ...\n с пустыми строками вокруг (markdown-разделение от code-fence).
Рендер шагов — ${renderSteps(...)} вставлен ПОСЛЕ bash-блока, ДО accessLine*, в обеих секциях (EN и RU).
Условный bash-блок — hasBashBlock = include_clone !== false || quick_start !== "". Если оба false → bash-fence не рендерится (только шаги, если есть). cloneLine вынесен в общую переменную. Default behavior сохранён (include_clone не передан → !== false → true → git clone).
Кликабельный access_url — [url](url) вместо bare URL.
Валидатор — без изменений: шаги вне 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). Простой и предсказуемый.

4.6 KiB Raw Permalink Blame History Unescape Escape