From 2a6d6eee2a5f5ddfde09a6b3862412542ca420ac Mon Sep 17 00:00:00 2001 From: Sergey <93754860+slaid098@users.noreply.github.com> Date: Wed, 29 Jul 2026 20:50:52 +0300 Subject: [PATCH] feat(create-readme): optional git clone, development block, remove telegram (#130) * feat(create-readme): add include_clone, development_en/ru, remove telegram * docs(readme): update SKILL.md template and params for optional clone and development * docs(readme): add ADR-058, handoff, project map * docs(handoff): set PR number --------- Co-authored-by: opencode-agent --- .opencode/skills/repo-readme/SKILL.md | 26 +++++++++-- .opencode/tools/create-readme.ts | 45 ++++++++++++------- ...0-readme-optional-clone-and-development.md | 33 ++++++++++++++ ...0-readme-optional-clone-and-development.md | 20 +++++++++ docs/project-map/README.md | 4 +- 5 files changed, 106 insertions(+), 22 deletions(-) create mode 100644 docs/decisions/058-pr-130-readme-optional-clone-and-development.md create mode 100644 docs/handoff/pr-130-readme-optional-clone-and-development.md diff --git a/.opencode/skills/repo-readme/SKILL.md b/.opencode/skills/repo-readme/SKILL.md index 211ce17..702d410 100644 --- a/.opencode/skills/repo-readme/SKILL.md +++ b/.opencode/skills/repo-readme/SKILL.md @@ -101,10 +101,11 @@ repos/{owner}/{repo}/contents/README.md` с base64-контентом и SHA. ### ⚡ Quick Start \`\`\`bash -git clone https://github.com/slaid098/{repo_name}.git +{git clone строка, если include_clone !== false} {quick_start} \`\`\` {access_url строка если передан — Access at {url}} +{development_en блок, если передан — ### 🔧 Development + content} --- @@ -130,17 +131,17 @@ git clone https://github.com/slaid098/{repo_name}.git ### ⚡ Быстрый старт \`\`\`bash -git clone https://github.com/slaid098/{repo_name}.git +{git clone строка, если include_clone !== false} {quick_start} \`\`\` {access_url строка если передан — Доступ: {url}} +{development_ru блок, если передан — ### 🔧 Разработка + content} --- ## 💬 Support and contacts / Поддержка и контакты 👉 **[slaid098.dev/support](https://slaid098.dev/support)** -{telegram строка, если передан} ``` `validate` проверяет: наличие всех 4 пар EN/RU разделителей (summary + @@ -168,8 +169,25 @@ Quick Start (EN) и Быстрый старт (RU), language switcher `[English] - `features_en` / `features_ru` — массив `{ emoji, name, description }[]`. - `custom_sections_en` / `custom_sections_ru` — массивы `{ title, content }` (optional). -- `telegram` — username без `@` (optional). - `access_url` — URL для Access/Доступ строки после Quick Start bash-блока (optional). EN: `Access at {url}`, RU: `Доступ: {url}`. Omit if no web access. +- `include_clone` — boolean (optional, default true). `false` убирает `git clone` + из Quick Start. Для userscript, web-app, npm-package. +- `development_en` — raw markdown (optional). `### 🔧 Development` после EN + Quick Start, вне delimiter-тегов (не на slaid098.dev). +- `development_ru` — raw markdown (optional). `### 🔧 Разработка` после RU + Быстрый старт, вне delimiter-тегов (не на slaid098.dev). - `repo` — `owner/name` для удалённой операции (optional). - `file_path` — локальный путь (default `README.md`). + +## 8. Кейс: userscript / web-app / npm-package + +Для репо без клонирования (userscript, web-app с demo URL, npm-package): + +- `include_clone: false` — убирает `git clone` из Quick Start +- `quick_start` — команда установки (npm install, pip install, или ссылка на + установку userscript) +- `access_url` — URL web-доступа (если есть) +- `development_en` / `development_ru` — инструкции для разработчиков (как + собрать, как контрибьютить), рендерятся после Quick Start, вне + delimiter-тегов (не на slaid098.dev) diff --git a/.opencode/tools/create-readme.ts b/.opencode/tools/create-readme.ts index 27c34f8..8590e64 100644 --- a/.opencode/tools/create-readme.ts +++ b/.opencode/tools/create-readme.ts @@ -16,8 +16,10 @@ type CreateArgs = { quick_start: string features_en: Feature[] features_ru: Feature[] - telegram?: string access_url?: string + include_clone?: boolean + development_en?: string + development_ru?: string custom_sections_en?: CustomSection[] custom_sections_ru?: CustomSection[] } @@ -46,11 +48,14 @@ function generateReadme(args: CreateArgs): string { const customRu = (args.custom_sections_ru || []) .map((s) => `\n\n### ${s.title}\n${s.content}`) .join("") - const telegramLine = args.telegram - ? `\n💬 **Direct Telegram:** [@${args.telegram}](https://t.me/${args.telegram})` - : "" const accessLineEn = args.access_url ? `\nAccess at ${args.access_url}\n` : "" const accessLineRu = args.access_url ? `\nДоступ: ${args.access_url}\n` : "" + const developmentBlockEn = args.development_en + ? `\n\n### 🔧 Development\n${args.development_en}\n` + : "" + const developmentBlockRu = args.development_ru + ? `\n\n### 🔧 Разработка\n${args.development_ru}\n` + : "" return `# 🚀 ${args.repo_name} > ${args.tagline} @@ -75,9 +80,8 @@ ${renderFeaturesTable(args.features_en, false)} ### ⚡ Quick Start \`\`\`bash -git clone https://github.com/slaid098/${args.repo_name}.git -${args.quick_start} -\`\`\`${accessLineEn} +${args.include_clone !== false ? `git clone https://github.com/slaid098/${args.repo_name}.git\n` : ""}${args.quick_start} +\`\`\`${accessLineEn}${developmentBlockEn} --- ## 🇷🇺 Русский @@ -96,14 +100,13 @@ ${renderFeaturesTable(args.features_ru, true)} ### ⚡ Быстрый старт \`\`\`bash -git clone https://github.com/slaid098/${args.repo_name}.git -${args.quick_start} -\`\`\`${accessLineRu} +${args.include_clone !== false ? `git clone https://github.com/slaid098/${args.repo_name}.git\n` : ""}${args.quick_start} +\`\`\`${accessLineRu}${developmentBlockRu} --- ## 💬 Support and contacts / Поддержка и контакты -👉 **[slaid098.dev/support](https://slaid098.dev/support)**${telegramLine} +👉 **[slaid098.dev/support](https://slaid098.dev/support)** ` } @@ -212,10 +215,6 @@ export default tool({ ) .optional() .describe("Array of features for RU table. Each: { emoji, name, description }. Required for create mode."), - telegram: tool.schema - .string() - .optional() - .describe("Telegram username without @. Optional; adds Direct Telegram line to Support section."), custom_sections_en: tool.schema .array( tool.schema.object({ @@ -246,6 +245,18 @@ export default tool({ .string() .optional() .describe("Optional URL for Access/Доступ line after Quick Start bash block. EN: 'Access at {url}', RU: 'Доступ: {url}'. Omit if no web access."), + include_clone: tool.schema + .boolean() + .optional() + .describe("If false, omits 'git clone' from Quick Start bash block. Default true (backward compatible). Set false for userscripts, web apps, npm packages."), + development_en: tool.schema + .string() + .optional() + .describe("Raw markdown for ### 🔧 Development section after EN Quick Start (outside delimiters, not shown on slaid098.dev). Omit if no dev section needed."), + development_ru: tool.schema + .string() + .optional() + .describe("Raw markdown for ### 🔧 Разработка section after RU Быстрый старт (outside delimiters, not shown on slaid098.dev). Omit if no dev section needed."), }, async execute(args, context) { try { @@ -279,8 +290,10 @@ export default tool({ quick_start: args.quick_start!, features_en: args.features_en!, features_ru: args.features_ru!, - telegram: args.telegram, access_url: args.access_url, + include_clone: args.include_clone, + development_en: args.development_en, + development_ru: args.development_ru, custom_sections_en: args.custom_sections_en, custom_sections_ru: args.custom_sections_ru, }) diff --git a/docs/decisions/058-pr-130-readme-optional-clone-and-development.md b/docs/decisions/058-pr-130-readme-optional-clone-and-development.md new file mode 100644 index 0000000..6deb158 --- /dev/null +++ b/docs/decisions/058-pr-130-readme-optional-clone-and-development.md @@ -0,0 +1,33 @@ +# ADR-058: README — optional git clone, Development block, remove telegram + +## Статус +Accepted (2026-07-29) + +## Контекст + +Тулза `create-readme` имела 3 проблемы: + +- **`git clone https://github.com/slaid098/{repo}.git` захардкожен** в Quick Start (стр. 78 EN, 99 RU). Не отключается — все README получают clone-строку, даже userscript / web-app / npm-package, где клонирование не имеет смысла. +- **`custom_sections_en/ru` рендерятся ДО Quick Start** (стр. 74, 95) — не подходит для блока «Разработка», который логичен после Quick Start. +- **Параметр `telegram`** — мёртвый: 0 call-sites, 0 тестов, валидатор не проверяет, собственный README репо без него. Ссылки `slaid098.dev/support` достаточно. + +Валидатор `validateReadme()` не проверяет `git clone`, `telegram`, `custom_sections` — изменения не сломают валидацию. + +## Решение + +3 новых optional-параметра + hard removal `telegram` (backward compatible): + +- **`include_clone?: boolean`** (default `true`) — `false` убирает `git clone` из Quick Start bash-блока. `undefined` → включает. Прецедент: `access_url` (ADR-052) — тот же паттерн «optional → условный рендер». +- **`development_en?: string`** — raw markdown, рендерит `### 🔧 Development` после EN Quick Start, вне delimiter-тегов (не на slaid098.dev). Для инструкций разработчикам. +- **`development_ru?: string`** — raw markdown, рендерит `### 🔧 Разработка` после RU Быстрый старт, вне delimiter-тегов. +- **`telegram`** — hard removal: убран из `CreateArgs` type, рендера, JSON schema, pass-through. Support-секция: только `👉 **[slaid098.dev/support]...**`. +- **Валидатор** — без изменений. + +Development-блок вне delimiter-тегов: разделители определяют только то, что парсер slaid098.dev вытягивает для витрины. Development-блок виден только на GitHub — правильно для доп. секции «для разработчиков». + +## Альтернативы + +- **`include_clone` как обязательный параметр** — отвергнуто: не все репо хотят убрать clone (большинству нужен). Default `true` → backward compatible. +- **Development через `custom_sections`** — отвергнуто: `custom_sections` рендерятся ДО Quick Start. Development логичен после. Новый параметр → правильная позиция. +- **Deprecation `telegram` (оставить параметр, игнорировать)** — отвергнуто: мёртвый код вводит в заблуждение. 0 call-sites → hard removal безопасен. +- **Валидатор проверяет development-блок** — отвергнуто: блок optional, валидатор не должен требовать optional-секции. diff --git a/docs/handoff/pr-130-readme-optional-clone-and-development.md b/docs/handoff/pr-130-readme-optional-clone-and-development.md new file mode 100644 index 0000000..be76ebc --- /dev/null +++ b/docs/handoff/pr-130-readme-optional-clone-and-development.md @@ -0,0 +1,20 @@ +--- +pr: 130 +title: feat(create-readme): optional git clone, development block, remove telegram +--- + +## Что сделано +- 3 новых optional-параметра: `include_clone` (default true, backward compatible), `development_en`, `development_ru` — raw markdown, `### 🔧 Development` / `### 🔧 Разработка` после Quick Start, вне delimiter-тегов +- Hard removal `telegram` — убран из CreateArgs type, рендера (telegramLine), шаблона Support, JSON schema, pass-through. Support: только `slaid098.dev/support` +- Валидатор `validateReadme()` — без изменений +- SKILL.md §5 шаблон + §7 параметры обновлены, +§8 userscript-кейс +- ADR-058 создан + +## Почему +`git clone slaid098/{repo}` захардкожен — не отключался для userscript/web-app/npm-package. `custom_sections` рендерились до Quick Start — не подходили для блока «Разработка». `telegram` — мёртвый параметр (0 call-sites, 0 тестов, валидатор не проверяет). + +## Pending +— + +## Watch out +— diff --git a/docs/project-map/README.md b/docs/project-map/README.md index b01274f..e7a3c39 100644 --- a/docs/project-map/README.md +++ b/docs/project-map/README.md @@ -36,7 +36,7 @@ opencode-config/ │ │ ├── python-development/SKILL.md # Python dev patterns │ │ ├── release/SKILL.md # Tag + GitHub Release │ │ ├── repo-init/SKILL.md # New repository bootstrap -│ │ ├── repo-readme/SKILL.md # Standardized README generation (create-readme tool: create vs validate, bilingual Why/What + Features table, GitHub metadata) — PR#112, PR#116, PR#118 +│ │ ├── repo-readme/SKILL.md # Standardized README generation (create-readme tool: create vs validate, bilingual Why/What + Features table, GitHub metadata) — PR#112, PR#116, PR#118, PR#130 │ │ ├── tunnel/SKILL.md # Cloudflare tunnel toggle (tool `tunnel()`: 1-й вызов start, 2-й stop) — PR#63 (восстановлен, удалён в PR#42) │ │ ├── run-tests/SKILL.md # Test runner guide │ │ └── spec/SKILL.md # 9-phase spec generation @@ -45,7 +45,7 @@ opencode-config/ │ │ ├── commit.ts # commit tool wrapper (1 arg message, validates format+staged) — PR#38 │ │ ├── create-issue.ts # create-issue tool wrapper (3 args, validates format+labels; optional repo?: string) — PR#38, PR#65 │ │ ├── create-pr.ts # create-pr tool wrapper (3 args, validates format+Closes #N; optional repo?: string) — PR#38, PR#65 -│ │ ├── create-readme.ts # create-readme tool (TS plugin, modes: create/validate; standardized bilingual README with features table, access_url, RU heading 'Русский' + anchor checks, 4 delimiter pairs for slaid098.dev; local fs + remote gh api) — PR#112, PR#116, PR#118 +│ │ ├── create-readme.ts # create-readme tool (TS plugin, modes: create/validate; standardized bilingual README with features table, include_clone/development_en/ru optional params, RU heading 'Русский' + anchor checks, 4 delimiter pairs for slaid098.dev; local fs + remote gh api) — PR#112, PR#116, PR#118, PR#130 │ │ ├── merge-pr.ts # merge-pr tool wrapper (orchestrator-safe gh pr merge; optional repo?: string) — PR#30, PR#65 │ │ ├── memory-access.ts # memory-access tool (bump frontmatter last_accessed/access_count, regex replace, atomic write tmp+rename) — PR#101 │ │ ├── memory-doctor.ts # memory-doctor tool (read-only diagnostics: rg {lines, rgWorks} G9, allowSystemFallback:true G5, arch-mismatch detection G2, npm-missing hint G3; markdown ✅/❌ report) — PR#101, PR#124