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>
78 lines
No EOL
5.8 KiB
Markdown
78 lines
No EOL
5.8 KiB
Markdown
---
|
||
pr: 146
|
||
title: "feat(create-readme): add clickable steps to Quick Start"
|
||
---
|
||
|
||
## Что сделано
|
||
Расширение тулзы `create-readme` (`.opencode/tools/create-readme.ts`) —
|
||
кликабельные шаги-ссылки в Quick Start, условный bash-блок, кликабельный
|
||
`access_url`. Backward-compatible.
|
||
|
||
1. **Новые параметры** — `quick_start_steps_en?: string[]` и
|
||
`quick_start_steps_ru?: string[]` добавлены в тип `CreateArgs` (строки 25-26)
|
||
и в `tool.schema` (после `quick_start`, строки 214-220). Каждый элемент =
|
||
raw-markdown строка, может содержать `[text](url)`. `.optional()`.
|
||
2. **Helper `renderSteps`** (строки 46-50) — если массив пуст/undefined → `""`,
|
||
иначе нумерованный список `1. ...\n2. ...\n` с пустыми строками вокруг для
|
||
markdown-разделения от code-fence.
|
||
3. **Рендер шагов** — `${renderSteps(args.quick_start_steps_*)}` вставлен после
|
||
bash-блока, до `accessLine*` в обеих секциях (EN: строка 102, RU: строка 120).
|
||
4. **Условный bash-блок** — `hasBashBlock = include_clone !== false ||
|
||
quick_start !== ""` (строка 70). Если оба условия false → bash-fence НЕ
|
||
рендерится (только шаги). `cloneLine` вынесен в общую переменную (строки
|
||
67-69). Применено к EN (`bashBlockEn`, строки 71-73) и RU (`bashBlockRu`,
|
||
строки 74-76). Default behavior сохранён: `include_clone` не передан →
|
||
`!== false` → true → git clone рендерится.
|
||
5. **Кликабельный `access_url`** (строки 59-60) — bare URL заменён на
|
||
`[url](url)`. EN: `Access at [url](url)`, RU: `Доступ: [url](url)`.
|
||
6. **Передача параметров** — `quick_start_steps_en/ru` прокинуты в вызов
|
||
`generateReadme({...})` в `execute()` (строки 324-325).
|
||
7. **Валидатор** — `validateReadme` НЕ изменён: шаги рендерятся вне delimiter-пар
|
||
(summary/features) и не влияют ни на одну проверку (секции "Quick Start" /
|
||
"Быстрый старт" присутствуют). Проверено smoke-тестом: все 28 checks PASS,
|
||
`validate` проходит на всех сгенерированных README.
|
||
8. **Документация** — `.opencode/skills/repo-readme/SKILL.md` обновлён: новые
|
||
параметры в секции 7, кликабельный `access_url` отмечен, reference-шаблон
|
||
(секция 5) отражает шаги + clickable access, секция 8 (кейс userscript)
|
||
расширена, добавлен пример вызова + ожидаемый вывод.
|
||
|
||
### Smoke-test
|
||
Прогнан через `npx tsx` с реальным `@opencode-ai/plugin` из
|
||
`.opencode/node_modules/` (mock не понадобился — плагин установлен). 5
|
||
сценариев, 28 assertions:
|
||
- S1: default (backward compat) — bash + git clone, no steps, no access.
|
||
- S2: steps + clickable access (main spec scenario) — вывод точно совпадает с
|
||
примером из issue.
|
||
- S3: asymmetric (steps only on RU).
|
||
- S4: `include_clone=false` + non-empty `quick_start` → bash без git clone.
|
||
- S5: empty steps array → no list rendered.
|
||
Все `validate` PASS на сгенерированных README.
|
||
|
||
## Почему
|
||
Quick Start умел только bash-блок (markdown-ссылки внутри code-fence НЕ
|
||
кликабельны) и плоский `access_url`. Для multi-step setup (userscript:
|
||
установить → получить API-ключ → настроить) нужен нумерованный список
|
||
кликабельных шагов. Условный bash-блок убирает пустой ` ```bash ``` ` когда
|
||
установки нет (только шаги). Кликабельный `access_url` улучшает UX.
|
||
|
||
## Pending
|
||
—
|
||
|
||
## Watch out
|
||
- **`quick_start` остаётся required** для `create` mode в `execute()` (строки
|
||
296-301). Сценарий "пустой quick_start + только steps" через `execute`
|
||
невозможен без ослабления required-чеков — спека этого НЕ просит. Чтобы
|
||
рендерить только шаги (без bash), передай `quick_start: ""` + `include_clone:
|
||
false` — НО `execute` отвергнет пустой `quick_start`. Обход: передать
|
||
минимальный `quick_start` (например пробел/коммент) или ослабить required в
|
||
отдельном issue. В `generateReadme` напрямую логика `hasBashBlock` корректна
|
||
для `quick_start=""`.
|
||
- **`access_url` визуально почти идентичен** на GitHub: был bare URL (auto-link)
|
||
→ стал `[url](url)` (markdown-ссылка). Оба кликабельны. На raw-text
|
||
просмотрах (не GitHub) markdown-синтаксис виден.
|
||
- **tsconfig.smoke.json и smoke-harness** созданы в `/tmp/opencode/` (вне
|
||
репо) — не коммитятся. Mock `@opencode-ai/plugin` не понадобился (реальный
|
||
плагин установлен в `.opencode/node_modules/`, gitignored).
|
||
- **`renderSteps` использует `1-based` нумерацию** через `${i + 1}.` — markdown
|
||
ordered list, нумерация авто-пересчитывается рендерером, но явные числа
|
||
соответствуют порядку массива. |