From 28b1b46d94b36858c475d687474eba29f5067a84 Mon Sep 17 00:00:00 2001 From: Codex Date: Sat, 18 Jul 2026 03:35:01 -0400 Subject: [PATCH] Add adoption-safe open-source launch workflow --- .github/workflows/validate.yml | 19 ++++++ CHANGELOG.md | 21 +++++++ README.md | 22 ++++--- SKILL.md | 87 +++++++++++++++++++++----- references/description-guide.md | 2 +- references/discovery-and-promotion.md | 53 ++++++++++++++++ references/pr-and-release-workflow.md | 54 ++++++++++++++++ references/release-and-distribution.md | 6 +- scripts/validate_repo.py | 69 ++++++++++++++++++++ 9 files changed, 305 insertions(+), 28 deletions(-) create mode 100644 .github/workflows/validate.yml create mode 100644 references/discovery-and-promotion.md create mode 100644 references/pr-and-release-workflow.md create mode 100644 scripts/validate_repo.py diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..b3ced69 --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,19 @@ +name: Validate skill + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: python3 scripts/validate_repo.py diff --git a/CHANGELOG.md b/CHANGELOG.md index ea6f277..7398426 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,25 @@ # Changelog +## [1.4.0] - 2026-07-18 + +### Added + +- Added project positioning, five-minute proof and adoption-readiness checks before repository publication. +- Added a `public-safe` branch/Draft PR/CI workflow and an explicit low-risk `solo-fast` option. +- Added provenance, asset licensing, clean-clone reproducibility and version-consistency release gates. +- Added repository discoverability, Launch Kit, channel selection and post-launch feedback guidance. +- Added self-modification safeguards for skills that prepare or publish themselves. + +### Changed + +- Replaced the rigid “only fill missing files” rule with approval-gated audits and improvements of weak existing files. +- Separated authorization for repository publishing, Releases, package registries and external promotion. +- Reframed Community Profile completeness as a baseline rather than the definition of release readiness. + +### Security + +- Removed the remaining example that embedded a GitHub Token in a remote URL. + ## [1.3.0] - 2026-07-18 ### Added @@ -20,3 +40,4 @@ - Removed token-bearing Git remote URLs and instructions that display credentials. [1.3.0]: https://github.com/hyt315/github-oss-prep/releases/tag/v1.3.0 +[1.4.0]: https://github.com/hyt315/github-oss-prep/releases/tag/v1.4.0 diff --git a/README.md b/README.md index d2ec6f5..f1978a6 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ **One-click polish any project into a professional GitHub open-source repo with full community health files** [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -[![Version](https://img.shields.io/badge/version-1.3.0-green.svg)](https://github.com/hyt315/github-oss-prep/releases/tag/v1.3.0) +[![Version](https://img.shields.io/badge/version-1.4.0-green.svg)](https://github.com/hyt315/github-oss-prep/releases/tag/v1.4.0) [![SKILL.md](https://img.shields.io/badge/Agent%20Skill-SKILL.md-green)](SKILL.md) [English](#english) | [中文](#中文) @@ -27,9 +27,12 @@ | 特性 | 说明 | |------|------| | 🔍 **智能扫描** | 自动识别项目类型（Skill/代码/文档），逐项检查 GitHub Community Profile 考核项 | -| 📝 **补齐文件** | 一键生成 LICENSE、README、.gitignore、CONTRIBUTING、Issue/PR 模板等全套社区健康文件 | +| 📝 **审计与改进** | 补齐缺失文件，也会识别过时、残缺或不可运行的已有文档，经确认后改进 | | 🛡️ **隐私保护** | 自动扫描 API Key、邮箱、私网 IP、真实路径等敏感信息，推送前二次验证 | +| ✅ **采用性验证** | 用干净 clone 验证安装、最小示例、测试、构建、来源许可与版本一致性 | | 📤 **灵活交付** | 无认证也能完成整理并导出 ZIP；发布时支持官方 GitHub 连接器或 `gh` CLI | +| 🔀 **安全发布** | 公开项目默认走分支、Draft PR、CI 与人工合并；单人低风险改动可选择直推 | +| 📣 **发现与推广** | 生成 Topics、社交预览、演示素材、Launch Kit、渠道计划和反馈闭环 | | 🌐 **中英双语** | 所有生成文件支持中英双语，符合 GitHub 全球社区最佳实践 | | 📦 **多平台分发** | 代码项目支持 npm、PyPI、crates.io、Docker Hub、Homebrew 等多渠道发布 | @@ -52,7 +55,7 @@ ### 怎么用 -安装后直接告诉 AI 助手你的意图，Skill 会自动执行 **扫描 → 补齐 → 审查 → Description → 交付/发布 → Release → 优化** 这 7 步工作流。整理和 ZIP 交付不需要 GitHub 认证；只有远程发布需要授权。 +安装后直接告诉 AI 助手你的意图，Skill 会自动执行 **定位 → 扫描 → 整理 → 验证 → 仓库门面 → PR/发布 → Release → 发现与增长**。整理和 ZIP 交付不需要 GitHub 认证；远程发布、Release 和外部推广分别确认。 --- @@ -96,10 +99,11 @@ ## 💡 核心理念 -- **只补缺，不覆盖**：已有文件不修改，只补充缺失项 +- **先审后改**：保留有效内容；已有文件存在质量或安全问题时，展示差异后再修改 - **按类型适配**：Skill 项目、代码项目、文档项目各有侧重 -- **对齐标准**：目标是通过 GitHub Community Profile 100% 考核 -- **确认后推送**：生成内容先展示，用户确认后才创建仓库 +- **可运行优先**：Community Profile 只是底线，干净环境可安装、可运行、可贡献才算完成 +- **PR 默认**：公开维护项目走分支、Draft PR、CI 和人工复核 +- **分步授权**：推送、Release、包发布和对外推广互不默认包含 --- @@ -127,6 +131,8 @@ github-oss-prep/ ├── mcp-push-guide.md # 推送方案指南 ├── templates-and-formats.md # 模板与格式合集 ├── release-and-distribution.md # Release 与分发指南 + ├── pr-and-release-workflow.md # PR、CI、验证和发布门禁 + ├── discovery-and-promotion.md # 可发现性、Launch Kit 与推广闭环 ├── github-pat-setup.md # PAT 配置教程 └── github-pat-comparison.md # PAT 类型对比 ``` @@ -196,7 +202,7 @@ In one sentence: **turn any local project into a professional GitHub open-source ### How to use -Once installed, simply tell your AI assistant what you want. The Skill runs a 7-step workflow: **Scan → Fill → Review → Description → Deliver/Publish → Release → Optimize**. Preparation and ZIP delivery never require GitHub authentication. It never overwrites existing files, and confirms with you before remote publication. +Once installed, tell your AI assistant what you want. The Skill runs an adoption-focused workflow: **Position → Scan → Improve → Validate → Repository Surface → PR/Publish → Release → Discover**. Preparation and ZIP delivery never require GitHub authentication. Public projects default to a reviewable branch and Draft PR; remote publication, releases and external promotion require separate approval. --- @@ -217,7 +223,7 @@ github-oss-prep/ │ ├── bug_report.yml # Bug report form │ ├── feature_request.yml # Feature request form │ └── doc_improvement.yml # Docs improvement form -└── references/ # Reference documents (8 files) +└── references/ # Reference documents ``` --- diff --git a/SKILL.md b/SKILL.md index 043f410..3ffdcbf 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,6 +1,6 @@ --- name: github-oss-prep -description: "Use when preparing a project for open-source release on GitHub, including license selection, community health files, README structure, privacy scanning, release packaging, and approval-gated repository publishing. Triggers include GitHub 开源准备、准备发布到 GitHub、美化项目准备开源、开源化、oss prep、publish to GitHub, and prepare for open source." +description: "Use when preparing, publishing, launching, or improving a project for open-source adoption on GitHub, including positioning, licensing, community health files, README quality, privacy and provenance scanning, clean-clone validation, PR workflows, release packaging, discoverability, and approval-gated promotion. Triggers include GitHub 开源准备、准备发布到 GitHub、美化项目准备开源、开源化、开源推广、oss prep、publish to GitHub, launch an open-source project, and prepare for open source." --- # GitHub 开源准备 @@ -9,10 +9,12 @@ description: "Use when preparing a project for open-source release on GitHub, in ## 核心理念 -- **只补缺，不覆盖**：已有文件不修改，只补充缺失项 +- **先审后改，不盲目覆盖**：保留有效内容；已有文件若过时、残缺或存在风险，先展示差异与理由，获批后再修改 - **按项目类型适配**：Skill 项目、代码项目、文档项目的侧重点不同 - **对齐 GitHub 社区配置文件标准**：目标是通过 Insights → Community 中 100% 的考核 -- **确认后再推送**：生成内容后展示给用户确认，收到明确同意才创建仓库 +- **可运行比“文件齐全”更重要**：用干净环境验证安装、最小示例、测试与打包路径 +- **PR 默认、直推可选**：公开维护项目默认走分支、PR、CI 和人工复核；个人引导期可在明确授权后直推 +- **确认后再发布**：生成内容后展示给用户确认，远程仓库、Release、包平台和外部推广分别授权 --- @@ -40,21 +42,34 @@ description: "Use when preparing a project for open-source release on GitHub, in ## 工作流程 ``` -Step 1: 扫描（识别类型 + 检查缺失文件） +Step 0: 定位（目标用户 + 核心价值 + 可验证结果） ↓ -Step 2: 补齐（生成缺失的标准文件） +Step 1: 扫描（识别类型 + 检查缺失、薄弱与风险项） ↓ -Step 3: 审查（内容质量 + SKILL.md 合规） +Step 2: 整理（补齐缺失文件 + 经确认改进薄弱文件） ↓ -Step 4: 生成 Description（按规则 + 模板，详见 references/description-guide.md） +Step 3: 验证（内容 + 隐私 + 来源许可 + 干净环境运行） ↓ -Step 5: 发布确认 → 连接器 / gh CLI / 手动交付三选一 +Step 4: 仓库门面（README + Description + Topics + 社交预览） ↓ -Step 6: Release + 多平台分发（详见 references/release-and-distribution.md） +Step 5: 发布确认 → 分支/PR（默认）或个人直推（可选） ↓ -Step 7: 发布后优化（仓库设置 + CI/CD + 推广） +Step 6: Release + 多平台分发 + 版本一致性验证 + ↓ +Step 7: 发现与增长（Launch Kit + 定向发布 + 反馈闭环） ``` +## Step 0: 定位与成功标准 + +开始改文件前先用现有项目资料回答四个问题；能从仓库推断时不要反复询问： + +1. **谁会用**：首要用户只能有一类，次要用户最多两类。 +2. **解决什么**：用“用户在什么场景下，原来多麻烦，现在少几步”描述。 +3. **五分钟证明**：确定一个新用户可复现的最小示例和预期输出。 +4. **本次边界**：区分“准备开源”“发布 GitHub”“创建 Release”“对外推广”，不得把前一步授权扩展到后一步。 + +输出一张简短定位卡：目标用户、核心承诺、最小示例、证据、非目标。详见 `references/discovery-and-promotion.md`。 + --- ## Step 1: 扫描项目 @@ -135,7 +150,7 @@ GitHub 官方 Community Profile 考核项（Insights → Community）： --- -## Step 2: 补齐缺失文件 +## Step 2: 补齐并改进文件 > **检查点**：向用户展示 Step 1 的结果（项目类型 + 缺失清单），确认后进入补齐。 @@ -143,6 +158,8 @@ GitHub 官方 Community Profile 考核项（Insights → Community）： - 中英双语（中文项目可全中文，建议保留英文摘要） - 内容精准适配项目类型，不套通用模板 - 生成前先简要说明将要创建的内容，获得用户认可 +- 已有文件先按“准确、清楚、可运行、可维护”评分；只在确有收益时提出修改，并展示摘要或 diff +- 不因文件存在就自动判定合格，也不为统一模板而抹掉项目原有表达 | 文件 | 生成要点 | |------|----------| @@ -160,7 +177,7 @@ GitHub 官方 Community Profile 考核项（Insights → Community）： ### 项目类型速查 -根据 Step 1 识别的类型，按以下清单生成（跳过已存在的文件）： +根据 Step 1 识别的类型，按以下清单生成；已存在的文件进入质量审查，不机械跳过： | 类型 | 需要生成的文件 | |------|--------------| @@ -172,7 +189,7 @@ GitHub 官方 Community Profile 考核项（Insights → Community）： --- -## Step 3: 审查改进 +## Step 3: 验证与审查 > **检查点**：向用户展示 Step 2 生成的文件列表和内容摘要，确认后进行审查。 @@ -209,9 +226,20 @@ GitHub 官方 Community Profile 考核项（Insights → Community）： - [ ] 无残留 ``/`` 等未替换占位符（README、`.github/ISSUE_TEMPLATE/config.yml` 等交付文件） - [ ] 下载链接（ZIP/Tar/raw 单文件）的分支名与仓库实际默认分支一致（main 或 master） +### 3.4 来源、许可与可复现性门禁 + +- [ ] 项目代码、逆向分析产物、图片、字体、音频、数据集和示例内容均有可公开分发的权利或许可证 +- [ ] 第三方依赖、NOTICE、字体/素材署名与许可证文件完整；无法确认的资产不进入发布包 +- [ ] 不只扫描工作区，还检查将要提交的 Git 树与可访问历史中是否含秘密；发现历史泄露时先轮换凭据，再制定历史清理方案 +- [ ] 从干净目录或全新 clone 按 README 完成安装、最小示例、测试和构建 +- [ ] Windows/macOS/Linux 支持范围写清楚；未测试的平台明确标为未验证 +- [ ] 一键脚本失败时有可执行的手动步骤和故障排查，不把本机缓存当成依赖 + +验证方法与发布门禁见 `references/pr-and-release-workflow.md`。任何 P0（秘密、许可不明、无法复现）失败都必须阻止公开发布。 + --- -## Step 4: 生成 Description +## Step 4: 仓库门面与 Description 按规则生成仓库简介。**规则 + 模板 + 案例 + Topics 建议** 详见 `references/description-guide.md`。 @@ -220,6 +248,13 @@ GitHub 官方 Community Profile 考核项（Insights → Community）： - 禁止「一个用于…的项目」式废话、版本号 - 按项目类型选用模板 +同时准备： + +- 5–12 个准确 Topics，优先使用目标用户会搜索的成熟词，不堆砌近义词； +- 1280×640 社交预览图方案，展示用途或结果，不只放 Logo； +- README 首屏的“一句话价值 + 结果图/GIF + 最短安装 + 最小示例”； +- 3 个真实示例或一个 60–90 秒演示，证明项目确实能解决问题。 + --- ## Step 5: 推送到 GitHub @@ -234,6 +269,18 @@ GitHub 官方 Community Profile 考核项（Insights → Community）： 如未登录，只暂停远程发布，不暂停本地整理和交付。让用户在受信任终端中完成 `gh auth login --web`，或选择手动上传。只有用户明确要求了解 PAT 时才读取 `references/github-pat-setup.md`。 +### 5.3 选择变更路径 + +默认使用 `public-safe`： + +1. 从最新默认分支创建短生命周期分支； +2. AI 修改、运行验证并提交； +3. 推送分支并创建 Draft PR； +4. 展示 diff、验证结果和剩余风险，由人复核； +5. CI 通过后 Squash Merge；受保护默认分支不得绕过规则。 + +仅当项目由单人维护、改动低风险且用户明确同意时使用 `solo-fast` 直推。秘密处理、许可证、发布工作流、依赖升级和可执行代码默认不属于低风险。完整决策表见 `references/pr-and-release-workflow.md`。 + --- ## Step 6: Release + 多平台分发 @@ -280,10 +327,20 @@ GitHub 官方 Community Profile 考核项（Insights → Community）： --- -## Step 7: 发布后优化 +## Step 7: 发现、推广与发布后优化 > 推送和分发完成后，建议进行以下优化。非必须，但能显著提升项目专业度和可维护性。 +发布完成不等于会被发现。先生成 `Launch Kit`，再按目标用户选择少量渠道。未经单独确认，不代表用户发布帖子、评论、私信或批量投放。详见 `references/discovery-and-promotion.md`。 + +Launch Kit 至少包含： + +- 一句介绍、100 字短介绍、完整发布帖三种长度； +- 社交预览图、演示 GIF/视频、三张功能截图及替代文本； +- 安装命令、最小示例、常见问题、已知限制和反馈入口； +- 渠道清单与适配版本，禁止同一文案无差别群发； +- 发布后 7/30 天检查表：访问、README→安装转化、成功运行、Issue、贡献者与留存反馈。 + ### 7.1 仓库设置优化 引导用户在 GitHub 仓库 Settings 中配置： diff --git a/references/description-guide.md b/references/description-guide.md index 3c6f31f..10d4c2b 100644 --- a/references/description-guide.md +++ b/references/description-guide.md @@ -1,6 +1,6 @@ # Description 生成指南 -仓库 Description 是 GitHub 搜索排名和「第一眼」的关键。写好后在 Step 5 通过 MCP 直接设置。 +仓库 Description 是 GitHub 搜索和「第一眼」理解项目的重要信息。写好后在 Step 5 通过已授权的官方 GitHub 连接器或 GitHub CLI 设置；无认证时将文案交给用户手动填写。 --- diff --git a/references/discovery-and-promotion.md b/references/discovery-and-promotion.md new file mode 100644 index 0000000..75ce19c --- /dev/null +++ b/references/discovery-and-promotion.md @@ -0,0 +1,53 @@ +# 开源项目发现与推广 + +## 先做可采用性，再做流量 + +推广前先通过“陌生人测试”：没有作者帮助的新用户，能否在五分钟内理解价值、完成安装、跑出一个结果，并知道失败后去哪里求助。不能通过时，先修 README、示例或安装流程。 + +## 仓库内可发现性 + +- Description 写清“为谁解决什么问题”，不写空泛口号； +- 选择 5–12 个准确 Topics，覆盖品类、技术栈、用户场景和兼容平台； +- 设置 1280×640 社交预览图； +- README 首屏放结果图/GIF、最短安装和最小示例； +- 创建真实的 `good first issue`，任务要小、边界清楚、可独立验证； +- 首个 Release 提供可复制的安装方式、变化、限制和升级说明。 + +## Launch Kit + +为每个渠道从同一事实卡改写，而不是复制粘贴同一广告： + +1. **一句话**：用户 + 痛点 + 可验证结果； +2. **短帖**：问题、演示、链接、一个明确提问； +3. **长帖**：为什么做、关键取舍、演示、限制、路线图； +4. **素材**：社交卡、GIF/视频、3 张截图、替代文本； +5. **支持**：安装、FAQ、Known issues、Issue/Discussion 链接。 + +## 渠道选择 + +| 目标用户 | 优先渠道 | 内容重点 | +|---|---|---| +| 开发者/Agent 用户 | GitHub Topics、相关项目 Discussions、技术社区、Show HN | 可运行演示、架构、限制、贡献入口 | +| 中文开发者 | 掘金、V2EX、知乎、公众号/视频平台 | 使用场景、教程、真实效果和源码链接 | +| 创作者/非技术用户 | B 站、小红书、Product Hunt、垂直社群 | 前后对比、操作视频、模板和上手成本 | + +只选择目标用户真实存在的 2–3 个首发渠道。遵守社区自我推广规则，不伪装用户反馈，不买 Star，不批量私信，不在无关 Issue/Discussion 植入链接。 + +## 发布节奏 + +- **T-7 到 T-1**：陌生人测试、修安装、准备演示与 FAQ； +- **T0**：发布 Release，更新 Topics/社交卡，再发首批渠道； +- **T+1 到 T+7**：快速回复 Issue，记录安装失败点，发布一次改进说明； +- **T+30**：按有效反馈决定路线图，不用 Star 数代替真实采用。 + +## 最小指标 + +记录趋势即可，不承诺虚假增长： + +- 仓库访问到 README 互动； +- README 到安装/下载； +- 安装到首次成功运行； +- Issue 首次响应时间与解决率； +- 复访、真实使用案例和外部贡献者。 + +对早期项目，三位陌生用户成功跑通，比一次短期曝光更有价值。 diff --git a/references/pr-and-release-workflow.md b/references/pr-and-release-workflow.md new file mode 100644 index 0000000..5f63fbe --- /dev/null +++ b/references/pr-and-release-workflow.md @@ -0,0 +1,54 @@ +# PR、验证与发布门禁 + +## AI 改代码是不是主流 + +AI 直接修改代码已经常见；成熟协作的关键不是“是否由 AI 写”，而是变更是否经过可审查的分支、自动检查和人工合并。默认路径是： + +`AI 研究与计划 → 工作分支 → 修改 → 测试 → Draft PR → 人工审查 → CI → 合并 → Tag/Release` + +## 两种模式 + +| 模式 | 适用 | 默认动作 | +|---|---|---| +| `public-safe` | 已公开、多人协作、准备长期维护 | 分支 + Draft PR + CI + 人工合并 | +| `solo-fast` | 单人引导期、文档小修、可快速回滚 | 展示 diff 和测试后，可经明确同意直推 | + +以下改动即使在单人项目也优先走 PR：认证/秘密、许可证、构建与发布、依赖升级、可执行脚本、数据迁移、权限设置。 + +## 发布前门禁 + +### P0：任一失败即停止 + +- 无秘密、私人数据或真实凭据进入当前树与待推送历史； +- 所有代码和资产有分发权，第三方许可证与 NOTICE 完整； +- 干净 clone 可按 README 安装并运行最小示例； +- 测试、构建、lint 和项目自带验证通过； +- 仓库可见性、Owner、名称、许可证已经用户确认。 + +### P1：公开前应完成 + +- README 首屏能说明用户、问题、结果与安装方式； +- 支持平台、依赖版本、已知限制、排障与卸载方式明确； +- Issue/PR 模板、CONTRIBUTING、SECURITY 和反馈渠道可用； +- CI 在默认分支与 PR 上运行，Ruleset 要求 PR 和必要检查； +- 版本号、CHANGELOG、Badge、Tag、Release 标题与安装链接一致。 + +## AI 变更的审查摘要 + +每次请求合并或直推前输出： + +1. 改了什么及为什么； +2. 文件级 diff 摘要； +3. 实际运行的命令与结果； +4. 未运行的验证及原因； +5. 风险、回滚方式和是否涉及外部状态； +6. 需要用户确认的精确动作。 + +## 自修改保护 + +当本 Skill 准备、修改或发布自身时： + +- 在独立 clone/worktree 中操作，不直接覆盖已安装且正在运行的副本； +- 先验证新副本，再更新安装副本； +- 不从正在处理的项目中读取或保存认证凭据； +- 源码推送、Tag、Release 分开验证，任何一步失败都保留可恢复状态。 diff --git a/references/release-and-distribution.md b/references/release-and-distribution.md index eaf17c7..dd211d4 100644 --- a/references/release-and-distribution.md +++ b/references/release-and-distribution.md @@ -45,13 +45,11 @@ gh release create v0.1.0 --title "v0.1.0" --notes "首个版本" ./dist/*.exe ./ 1. 在项目目录打 tag 并推送： ```bash git tag v0.1.0 - -# 由于 Step 5 推送后 origin 已被清除，需要临时添加 remote 推送 tag -git remote add origin "https://${GITHUB_TOKEN}@github.com//.git" git push origin v0.1.0 -git remote remove origin ``` +远程地址必须保持无凭据形式（如 `https://github.com//.git`）。认证由官方连接器、GitHub CLI 凭据助手或 SSH 代理完成；不要把 Token 拼进 URL、命令参数或脚本。 + 2. 去 GitHub 仓库 → Releases → Create a new release 3. 选择刚推的 tag，填写： diff --git a/scripts/validate_repo.py b/scripts/validate_repo.py new file mode 100644 index 0000000..2a7d3dc --- /dev/null +++ b/scripts/validate_repo.py @@ -0,0 +1,69 @@ +#!/usr/bin/env python3 +"""Dependency-free repository checks for github-oss-prep.""" + +from __future__ import annotations + +import re +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +TEXT_SUFFIXES = {".md", ".yaml", ".yml", ".json", ".py", ".txt"} +REQUIRED = [ + "SKILL.md", + "README.md", + "LICENSE", + "CONTRIBUTING.md", + "CODE_OF_CONDUCT.md", + "SECURITY.md", + "references/pr-and-release-workflow.md", + "references/discovery-and-promotion.md", +] + + +def fail(message: str) -> None: + print(f"ERROR: {message}") + raise SystemExit(1) + + +for relative in REQUIRED: + if not (ROOT / relative).is_file(): + fail(f"missing required file: {relative}") + +skill = (ROOT / "SKILL.md").read_text(encoding="utf-8") +if not re.match(r"^---\n(?s:.*?)\n---\n", skill): + fail("SKILL.md frontmatter is missing or malformed") +frontmatter = skill.split("---", 2)[1] +for key in ("name:", "description:"): + if key not in frontmatter: + fail(f"SKILL.md frontmatter is missing {key[:-1]}") + +readme = (ROOT / "README.md").read_text(encoding="utf-8") +changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8") +badge = re.search(r"version-([0-9]+\.[0-9]+\.[0-9]+)-", readme) +if not badge: + fail("README version badge not found") +version = badge.group(1) +if f"releases/tag/v{version}" not in readme: + fail("README badge link does not match badge version") +if f"## [{version}]" not in changelog: + fail("CHANGELOG does not contain README badge version") + +secret_patterns = { + "GitHub classic PAT": re.compile(r"ghp_[A-Za-z0-9]{30,}"), + "GitHub fine-grained PAT": re.compile(r"github_pat_[A-Za-z0-9_]{30,}"), + "OpenAI-style key": re.compile(r"sk-[A-Za-z0-9]{32,}"), +} +for path in ROOT.rglob("*"): + if not path.is_file() or ".git" in path.parts or path.suffix not in TEXT_SUFFIXES: + continue + content = path.read_text(encoding="utf-8", errors="replace") + for label, pattern in secret_patterns.items(): + if pattern.search(content): + fail(f"possible {label} in {path.relative_to(ROOT)}") + +for placeholder in ("", ""): + if placeholder in readme: + fail(f"unresolved README placeholder: {placeholder}") + +print(f"OK: repository checks passed for v{version}")