From be70731f277eac5a5c094665130f0c74743218dd Mon Sep 17 00:00:00 2001 From: heznpc Date: Wed, 1 Jul 2026 15:31:48 +0900 Subject: [PATCH 1/2] fix: publish unscoped starter-series identity --- .github/workflows/publish-mcp-registry.yml | 2 +- .github/workflows/publish.yml | 5 ++ CHANGELOG.md | 12 +++-- README.md | 54 ++++++++++++---------- SECURITY.md | 7 ++- docs/CONNECTOR_DIRECTORY_SUBMISSION.ko.md | 44 ++++++++++-------- docs/CONNECTOR_DIRECTORY_SUBMISSION.md | 44 ++++++++++-------- docs/RELEASING.md | 2 +- docs/graduation-from-vibe-coding.ko.md | 10 ++-- docs/graduation-from-vibe-coding.md | 10 ++-- docs/ko/README.md | 54 ++++++++++++---------- docs/launch-proof-report.ko.md | 14 +++--- docs/launch-proof-report.md | 14 +++--- manifest.json | 6 ++- package-lock.json | 5 +- package.json | 3 +- server.json | 2 +- src/add-component.ts | 2 +- src/cli.ts | 38 +++++++-------- src/proof-report.ts | 2 +- src/seed-security-guidance.ts | 2 +- tests/add-component.test.ts | 2 +- tests/audit-helpers.test.ts | 2 +- tests/package-surface.test.ts | 41 ++++++++++++++-- 24 files changed, 224 insertions(+), 153 deletions(-) diff --git a/.github/workflows/publish-mcp-registry.yml b/.github/workflows/publish-mcp-registry.yml index b0631ed..7be64e2 100644 --- a/.github/workflows/publish-mcp-registry.yml +++ b/.github/workflows/publish-mcp-registry.yml @@ -7,7 +7,7 @@ name: Publish to MCP Registry # to the `starter-series` GitHub org via GitHub OIDC — the registry verifies the # OIDC token's `repository_owner` claim matches the namespace after `io.github.`. # -# Ownership of the npm package `@starter-series/create` is verified by the registry +# Ownership of the npm package `starter-series` is verified by the registry # fetching the published tarball and asserting `package.json#mcpName` equals # `server.json#name`. # diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 80901a0..5ce096c 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -88,6 +88,11 @@ jobs: echo "::error::server.json name ($SERVER_NAME) does not match package.json mcpName ($PKG_MCP_NAME)" exit 1 fi + SERVER_PACKAGE_IDENTIFIER=$(node -e "console.log(require('./server.json').packages?.[0]?.identifier || '')") + if [ "$SERVER_PACKAGE_IDENTIFIER" != "${{ steps.pkg.outputs.name }}" ]; then + echo "::error::server.json npm package identifier ($SERVER_PACKAGE_IDENTIFIER) does not match package.json name (${{ steps.pkg.outputs.name }})" + exit 1 + fi echo "All 4 manifests aligned at v$PKG_VERSION" - uses: actions/setup-node@v6 diff --git a/CHANGELOG.md b/CHANGELOG.md index 7adbafb..f679b21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,13 +21,19 @@ release feed without duplicating maintenance. - **`audit_security` 9th check — `claude-security-guidance`**: detects presence of `claude-security-guidance.md` at repo root (also `.claude-security-guidance.md` and `.claude/security-guidance.md` are accepted). Anthropic's Claude Code Security Guidance Plugin (released 2026-05-26) reads this file as an in-session guard. Positioning: in-session guard (Anthropic plugin) + post-PR diff review (`claude-code-security-review` Action) + repo-level static audit (this tool) are complementary, not competing. - **Graduation guide — Cloudflare Workers agent runtime row**: added to the target-mapping table in both EN/KO docs, reflecting the 2026-05-19 Anthropic × Cloudflare Claude Managed Agents announcement and the 2026-05-26 `@cloudflare/voice` SDK. Current path: `docker-deploy` adapter; dedicated `cloudflare-workers-agent` starter on roadmap. - **README: "Supply-chain security pre-wired" card** (EN + KO) — explicit list of the 9 checks `audit_security` looks for, cross-referenced with the 2026-04-21 Vercel npm supply-chain incident as a real-world timeliness signal. -- `audit_release` — diagnose release-readiness against the Starter Series quality bar. Detects matched starter, version vs last tag drift, CHANGELOG drift vs merged PRs (`git log ..HEAD`), and publish-workflow kind (release-please / publish-on-tag / auto-release). Available as MCP tool (`audit_release`) and CLI (`create-starter audit [path]`). -- `audit_cd` — check whether the local version has been published to its destination registries. Probes npm, PyPI, Open VSX, VS Marketplace, AMO (Firefox), and GitHub Releases via public APIs. Reports per-destination drift (in-sync / needs-publish / local-stale / not-found / unsupported). Available as MCP tool (`audit_cd`) and CLI (`create-starter audit-cd [path]`). CWS, EAS, Railway, Fly, and GHCR are not yet supported (no public read API or auth required). -- `audit_security` — verify baseline CI security hygiene against the Starter Series bar: gitleaks (with pin check), CodeQL, dependency audit, license check, `--ignore-scripts` on every install, Dependabot grouped updates, secret-scanning hint, and the `anthropics/claude-code-security-review` Action. Available as MCP tool (`audit_security`) and CLI (`create-starter audit-security [path]`). +- `audit_release` — diagnose release-readiness against the Starter Series quality bar. Detects matched starter, version vs last tag drift, CHANGELOG drift vs merged PRs (`git log ..HEAD`), and publish-workflow kind (release-please / publish-on-tag / auto-release). Available as MCP tool (`audit_release`) and CLI (`starter-series audit [path]`). +- `audit_cd` — check whether the local version has been published to its destination registries. Probes npm, PyPI, Open VSX, VS Marketplace, AMO (Firefox), and GitHub Releases via public APIs. Reports per-destination drift (in-sync / needs-publish / local-stale / not-found / unsupported). Available as MCP tool (`audit_cd`) and CLI (`starter-series audit-cd [path]`). CWS, EAS, Railway, Fly, and GHCR are not yet supported (no public read API or auth required). +- `audit_security` — verify baseline CI security hygiene against the Starter Series bar: gitleaks (with pin check), CodeQL, dependency audit, license check, `--ignore-scripts` on every install, Dependabot grouped updates, secret-scanning hint, and the `anthropics/claude-code-security-review` Action. Available as MCP tool (`audit_security`) and CLI (`starter-series audit-security [path]`). - Self-hardening: `create-starter` repo now passes its own `audit_security` (HARDENED, 8/8 present). Added `.github/workflows/codeql.yml` and `.github/workflows/claude-security-review.yml` (gated on `CLAUDE_API_KEY` secret presence; pinned to commit SHA, Dependabot-tracked). Native GitHub secret-scanning + push-protection + Dependabot security updates enabled on the repo settings. - `docs/graduation-from-vibe-coding.md` (+ Korean translation) — five-step path for graduating Lovable/Bolt/v0 exports to GitHub Actions + non-platform deploy targets. Uses the three audit primitives to diagnose and CI/CD lift from the matching starter without rewriting app code. Linked from both READMEs. ### Changed +- **npm package identity**: the public npm package name is now the unscoped + product noun `starter-series`. The `create-starter` bin remains as a + compatibility alias while docs and help text prefer `starter-series`. +- **Manifest/package parity gates**: `manifest.json` now lists the full nine-tool + MCP surface including `audit_instructions`, and tests/publish checks guard + package-name drift between `package.json`, `server.json`, and bundle metadata. - **Graduation guide narrative** (EN + KO): shifted from "escape platform lock-in" to **"vendor diversity"**. Reflects 2026-05 reality where Vercel (`bio: "Agentic Infrastructure for apps and agents"`), Cloudflare (Claude Managed Agents + voice SDK), and Netlify are all evolving into agentic infra providers. Graduation is about *choosing* a target per app, not fleeing one. **Followup pass**: removed remaining "universal escape hatch" / "stop paying token costs" language to match the intro. - **`.claude-plugin/plugin.json`**: bumped to 0.4.0 (was stale at 0.3.0; `manifest.json` and `server.json` were already at 0.4.0). Description updated to surface slash commands + audit primitives. Keywords expanded (`audit`, `release`, `publish-drift`, `supply-chain-security`). - **`manifest.json`** (Claude Desktop .mcpb): description + long_description + tools array brought in line with `plugin.json` and `package.json`. Previously read "Scaffold projects from the Starter Series templates — MCP server, Claude Code skill, and CLI" which omitted audit primitives and slash commands; Claude Desktop catalog now surfaces the full feature set. diff --git a/README.md b/README.md index b3ce5e6..5f56a58 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,11 @@ Korean documentation is maintained under [`docs/ko/README.md`](docs/ko/README.md ## Currently implemented -- **CLI** — `npx @starter-series/create my-bot --template discord-bot`. One of 11 templates with Zod-validated input, atomic rename on success, retry + timeout + 50 MB download cap. +- **CLI** — package and binary identity are `starter-series`; after the unscoped npm package is published, `npx starter-series my-bot --template discord-bot` scaffolds one of 11 templates with Zod-validated input, atomic rename on success, retry + timeout + 50 MB download cap. - **MCP server** — nine stdio tools: `list_templates`, `create_project`, `audit_release`, `audit_cd`, `audit_security`, `audit_instructions`, `generate_launch_proof_report`, `seed_security_guidance`, `add_component`. One binary chooses the mode by argv (positional -> CLI, none -> MCP stdio). - **Claude Desktop extension** — `.mcpb` bundle on every release; drag onto the Claude Desktop settings window. - **Claude Code plugin + skill** — `/plugin install create-starter@starter-series` ships the MCP server and the conversational `create` skill together. -- **MCP Registry entry** — `io.github.starter-series/create-starter`, OIDC-verified namespace, npm tarball cross-checked. +- **MCP Registry metadata** — `io.github.starter-series/create-starter`; registry submission is gated on the unscoped npm package being live and tarball-verified. - **`audit_release`** — detects matched starter, version vs last-tag drift, CHANGELOG drift vs merged PRs (`git log ..HEAD`), publish-workflow kind (release-please / publish-on-tag / auto-release). - **`audit_cd`** — probes npm, PyPI, Open VSX, VS Marketplace, AMO, GitHub Releases for per-destination publish drift (in-sync / needs-publish / local-stale / not-found / unsupported). - **`audit_security`** — checks 9 items: 8 core CI primitives (gitleaks with pin check, CodeQL, dependency audit, license check, `--ignore-scripts`, Dependabot grouped, secret-scanning hint, claude-code-security-review Action) plus the optional repo-author `claude-security-guidance.md`. The 8 core checks gate the HARDENED verdict; this repo passes 8/8 core. @@ -43,25 +43,29 @@ Korean documentation is maintained under [`docs/ko/README.md`](docs/ko/README.md ## Quick start — CLI ```bash -npx @starter-series/create my-bot --template discord-bot -# or, after cloning and building: +# After the unscoped npm package is published: +npx starter-series my-bot --template discord-bot + +# Before npm publication, run from source: +npm ci +npm run build node dist/index.js my-bot --template discord-bot ``` ``` -create-starter — scaffold a project from the Starter Series. +starter-series — scaffold a project from the Starter Series. Usage - create-starter --template [options] - create-starter audit [path] - create-starter audit-cd [path] - create-starter audit-security [path] - create-starter audit-instructions [path] - create-starter proof-report [path] [--output ] [--stdout] - create-starter seed-security-guidance [path] [--force] - create-starter add-component [path] [--component ] [--starter ] [--apply] [--force] - create-starter --list - create-starter --help + starter-series --template [options] + starter-series audit [path] + starter-series audit-cd [path] + starter-series audit-security [path] + starter-series audit-instructions [path] + starter-series proof-report [path] [--output ] [--stdout] + starter-series seed-security-guidance [path] [--force] + starter-series add-component [path] [--component ] [--starter ] [--apply] [--force] + starter-series --list + starter-series --help Options -t, --template Template ID (see --list) @@ -98,7 +102,7 @@ Environment | `cloudflare-pages` | Wrangler + Pages | | `docker-deploy` | any language + GHCR + SSH | -Run `create-starter --list` (CLI) or call `list_templates` (MCP) for the authoritative, up-to-date list. +Run `starter-series --list` (CLI) or call `list_templates` (MCP) for the authoritative, up-to-date list. ## Graduating from Lovable / Bolt / v0 @@ -170,13 +174,13 @@ Point at a git clone so edits in `skills/create/SKILL.md` or `dist/index.js` tak ## Use via MCP Registry -This server is published to the [Official MCP Registry](https://registry.modelcontextprotocol.io/) under the namespace: +After registry publication, this server uses the [Official MCP Registry](https://registry.modelcontextprotocol.io/) namespace: ``` io.github.starter-series/create-starter ``` -MCP-compatible clients that integrate registry discovery can install it by name without manual path wiring. The registry entry points at the npm package `@starter-series/create`, so `npx` runs the same stdio server described above. +MCP-compatible clients that integrate registry discovery can install it by name without manual path wiring. The registry entry points at the npm package `starter-series`, so the registry step must run only after the npm package is published and verified. Ownership is verified through GitHub OIDC (namespace `io.github.starter-series/*`) and npm tarball inspection (`package.json#mcpName`). See [`.github/workflows/publish-mcp-registry.yml`](https://github.com/starter-series/create-starter/blob/main/.github/workflows/publish-mcp-registry.yml) for the publish flow. @@ -196,13 +200,13 @@ Scaffolding: Audit (each takes an optional `path` arg, default = MCP server cwd; all read-only): -- **`audit_release`** — release-readiness diagnosis. CLI mirror: `create-starter audit [path]`. -- **`audit_cd`** — per-destination publish-drift probe. CLI mirror: `create-starter audit-cd [path]`. -- **`audit_security`** — baseline CI security hygiene check. CLI mirror: `create-starter audit-security [path]`. -- **`audit_instructions`** — agent-instruction duplicate and surface-overlap review, with advisory keyword risk summaries. CLI mirror: `create-starter audit-instructions [path]`. -- **`generate_launch_proof_report`** — combined Markdown launch handoff from release, CD, security, and instruction-review audits. CLI mirror: `create-starter proof-report [path] [--output ] [--stdout]`. -- **`seed_security_guidance`** — generate a starter-aware `claude-security-guidance.md` draft. CLI mirror: `create-starter seed-security-guidance [path] [--force]`. -- **`add_component`** — propose or apply starter CI/CD components to an existing repo as a dry-run plan. CLI mirror: `create-starter add-component [path] [--component ] [--starter ] [--apply] [--force]`. +- **`audit_release`** — release-readiness diagnosis. CLI mirror: `starter-series audit [path]`. +- **`audit_cd`** — per-destination publish-drift probe. CLI mirror: `starter-series audit-cd [path]`. +- **`audit_security`** — baseline CI security hygiene check. CLI mirror: `starter-series audit-security [path]`. +- **`audit_instructions`** — agent-instruction duplicate and surface-overlap review, with advisory keyword risk summaries. CLI mirror: `starter-series audit-instructions [path]`. +- **`generate_launch_proof_report`** — combined Markdown launch handoff from release, CD, security, and instruction-review audits. CLI mirror: `starter-series proof-report [path] [--output ] [--stdout]`. +- **`seed_security_guidance`** — generate a starter-aware `claude-security-guidance.md` draft. CLI mirror: `starter-series seed-security-guidance [path] [--force]`. +- **`add_component`** — propose or apply starter CI/CD components to an existing repo as a dry-run plan. CLI mirror: `starter-series add-component [path] [--component ] [--starter ] [--apply] [--force]`. ## Safety & reliability diff --git a/SECURITY.md b/SECURITY.md index 35430e5..82dc9f0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -11,10 +11,9 @@ The latest published `0.x` minor on npm receives security fixes. Earlier minors ## Reporting a vulnerability -**Please do not file public GitHub issues for security problems.** Use one of the private channels below. +**Please do not file public GitHub issues for security problems.** Use GitHub private vulnerability reporting. -- **GitHub private advisory** (preferred) — open a draft at . This routes directly to the maintainer and triggers GHSA workflows. -- **Email** — `wantcongz@gmail.com` with subject `[create-starter security] `. +- **GitHub private advisory** — open a draft at . This routes directly to the maintainer and triggers GHSA workflows. Please include: @@ -34,7 +33,7 @@ Please include: In scope: -- The `@starter-series/create` npm package (CLI + MCP server). +- The `starter-series` npm package (CLI + MCP server). - The `.mcpb` Claude Desktop bundle. - The `create-starter` Claude Code plugin and bundled `create` skill. - The `audit_release` / `audit_cd` / `audit_security` MCP tools. diff --git a/docs/CONNECTOR_DIRECTORY_SUBMISSION.ko.md b/docs/CONNECTOR_DIRECTORY_SUBMISSION.ko.md index 2ac7581..2435603 100644 --- a/docs/CONNECTOR_DIRECTORY_SUBMISSION.ko.md +++ b/docs/CONNECTOR_DIRECTORY_SUBMISSION.ko.md @@ -17,13 +17,13 @@ | **Category** | Developer Tools / Scaffolding | | **Author** | heznpc | | **License** | MIT | -| **제출 시 버전** | 0.3.0 | +| **제출 시 버전** | 0.4.0 | | **Homepage URL** | https://github.com/starter-series/create-starter#readme | | **Documentation URL** | https://github.com/starter-series/create-starter#readme | | **Source URL** | https://github.com/starter-series/create-starter | | **Issues / Support URL** | https://github.com/starter-series/create-starter/issues | | **Privacy policy URL** | https://github.com/starter-series/create-starter/blob/main/docs/PRIVACY.md *(TODO: 리뷰어 요청 시 별도 공개. 현재 입장은 "데이터 미수집"으로 본 문서 §3에 인라인)* | -| **npm 패키지** | https://www.npmjs.com/package/@starter-series/create | +| **npm 패키지** | 릴리스 대상: https://www.npmjs.com/package/starter-series (npm 게시 후 검증) | | **MCP Registry 엔트리** | `io.github.starter-series/create-starter` (https://registry.modelcontextprotocol.io/) | ### Short description (≤ 160자) @@ -36,15 +36,15 @@ > > It downloads the selected template tarball from GitHub, substitutes placeholders (project name, description), handles Python package renames (pyproject + `src/` directory), and runs `git init`. Inputs are Zod-validated before any filesystem write. Extraction happens in a sibling tmp directory and the final path only appears after an atomic `rename` — a failed scaffold never leaves half-written state. Downloads have a 30 s timeout, 3-attempt exponential backoff, and a 50 MB size cap. No credentials handled, no telemetry. > -> One tool per action: `list_templates` enumerates templates, `create_project` scaffolds one. A bundled Claude Code skill (`skills/create/SKILL.md`) guides the conversation. Installs as Claude Code plugin, Claude Desktop `.mcpb`, or plain `npx`. +> MCP 표면은 9개 도구를 노출합니다: `list_templates`, `create_project`, `audit_release`, `audit_cd`, `audit_security`, `audit_instructions`, `generate_launch_proof_report`, `seed_security_guidance`, `add_component`. 번들된 Claude Code skill (`skills/create/SKILL.md`)이 대화 흐름을 안내합니다. Claude Code plugin, Claude Desktop `.mcpb`, 일반 `npx`로 설치할 수 있습니다. ### 채널별 설치 명령 | 채널 | 명령 | |---|---| -| Claude Desktop (.mcpb) | [최신 GitHub 릴리스](https://github.com/starter-series/create-starter/releases/latest)의 `create-starter-0.3.0.mcpb`를 Claude Desktop 설정 창에 드래그. | +| Claude Desktop (.mcpb) | [최신 GitHub 릴리스](https://github.com/starter-series/create-starter/releases/latest)의 `create-starter-0.4.0.mcpb`를 Claude Desktop 설정 창에 드래그. | | Claude Code 플러그인 | `/plugin marketplace add starter-series/create-starter` 후 `/plugin install create-starter@starter-series` | -| npm CLI | `npx @starter-series/create --template ` | +| npm CLI | npm 게시 후: `npx starter-series --template ` | | MCP 서버 (수동) | 클라이언트 설정 JSON의 `mcpServers`에 `node /abs/path/dist/index.js` 등록. | | MCP Registry | `io.github.starter-series/create-starter` (registry discovery 지원 클라이언트) | @@ -56,10 +56,10 @@ |---|---| | **Transport** | `stdio` (로컬 전용). **remote endpoint / Streamable-HTTP 서버 없음.** | | **Authentication** | 없음. OAuth, API key, token 모두 없음. | -| **노출 capabilities** | 툴 2개, Claude Code 스킬 1개. resources 없음, prompts 없음. | -| **툴 목록** | `list_templates` (read-only), `create_project` (디스크 쓰기 수행) | +| **노출 capabilities** | 툴 9개, Claude Code 스킬 1개. resources 없음, prompts 없음. | +| **툴 목록** | `list_templates`, `create_project`, `audit_release`, `audit_cd`, `audit_security`, `audit_instructions`, `generate_launch_proof_report`, `seed_security_guidance`, `add_component` | | **툴 어노테이션** | `list_templates` → `readOnlyHint: true`. `create_project` → `destructiveHint: false` (실패 시 전체 롤백되고 성공 시 atomic rename). | -| **런타임** | Node.js ≥ 20, 크로스 플랫폼 (macOS / Linux / Windows). `.mcpb`에 `node_modules/`까지 번들. | +| **런타임** | Node.js ≥ 22, 크로스 플랫폼 (macOS / Linux / Windows). `.mcpb`에 `node_modules/`까지 번들. | | **호출하는 호스트 바이너리** | `git` (선택; 없으면 stderr 경고만 남기고 scaffold 성공). 그 외 서브프로세스 없음. | | **네트워크 egress** | HTTPS GET `github.com/starter-series/