@jtf19/vibecoding-kit 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -8,6 +8,13 @@ This project follows Semantic Versioning before 1.0 with the following interpret
 - Patch versions are for fixes, documentation improvements, and compatible release-check coverage.
 - Breaking changes before 1.0 are still called out explicitly when they affect installed layout, CLI arguments, JSON envelopes, or workflow skill contracts.
 
+## [0.1.1] - 2026-08-29
+
+### Fixed
+
+- Added the `vibecoding-kit` npm bin alias so `npx @jtf19/vibecoding-kit ...` resolves correctly on Windows and other npm environments.
+- Synchronized public install docs and release guidance with the scoped npm package name `@jtf19/vibecoding-kit`.
+
 ## [0.1.0] - 2026-08-03
 
 ### Added

package/README.md

@@ -19,8 +19,8 @@ Vibecoding Kit 让 coding agent 以更安全、可验证的方式工作。
 如果你只是把 Vibecoding Kit 安装到业务项目，优先使用 `npx` 从 npm 临时执行 CLI：
 
 ```bash
-npx vibecoding-kit init --target ../my-project --platform cursor
-npx vibecoding-kit doctor --root ../my-project
+npx @jtf19/vibecoding-kit init --target ../my-project --platform cursor
+npx @jtf19/vibecoding-kit doctor --root ../my-project
 ```
 
 `npx` 会执行发布包里的 `vibe` 命令，不会把 Vibecoding Kit 写入目标项目的依赖。
@@ -41,19 +41,19 @@ npx vibecoding-kit doctor --root ../my-project
 第一次安装建议先预览：
 
 ```bash
-npx vibecoding-kit init --target ../my-project --platform all --dry-run
+npx @jtf19/vibecoding-kit init --target ../my-project --platform all --dry-run
 ```
 
 已有 `CLAUDE.md` 或 `AGENTS.md` 时，先看合并预览：
 
 ```bash
-npx vibecoding-kit init --target ../my-project --platform auto --merge=preview
+npx @jtf19/vibecoding-kit init --target ../my-project --platform auto --merge=preview
 ```
 
 确认后追加 Vibecoding managed block：
 
 ```bash
-npx vibecoding-kit init --target ../my-project --platform auto --merge=append
+npx @jtf19/vibecoding-kit init --target ../my-project --platform auto --merge=append
 ```
 
 如果你正在维护本仓库或需要从源码运行，可以使用本地入口：

package/docs/install.md

@@ -26,8 +26,8 @@ AGENTS.md          # Cursor / Codex 入口，按平台生成
 如果你只是把 Vibecoding Kit 安装到业务项目，优先使用 `npx` 从 npm 临时执行 CLI：
 
 ```bash
-npx vibecoding-kit init --target ../my-project --platform cursor
-npx vibecoding-kit doctor --root ../my-project
+npx @jtf19/vibecoding-kit init --target ../my-project --platform cursor
+npx @jtf19/vibecoding-kit doctor --root ../my-project
 ```
 
 `npx` 会执行发布包里的 `vibe` 命令，不会把 Vibecoding Kit 写入目标项目的依赖。
@@ -43,23 +43,23 @@ node bin/vibe.mjs doctor --root ../my-project
 
 | 平台 | 入口文件 | 安装命令 |
 | --- | --- | --- |
-| Claude | `CLAUDE.md` | `npx vibecoding-kit init --target ../my-project --platform claude` |
-| Cursor | `AGENTS.md` | `npx vibecoding-kit init --target ../my-project --platform cursor` |
-| Codex | `AGENTS.md` | `npx vibecoding-kit init --target ../my-project --platform codex` |
-| 全部 | `CLAUDE.md` + `AGENTS.md` | `npx vibecoding-kit init --target ../my-project --platform all` |
+| Claude | `CLAUDE.md` | `npx @jtf19/vibecoding-kit init --target ../my-project --platform claude` |
+| Cursor | `AGENTS.md` | `npx @jtf19/vibecoding-kit init --target ../my-project --platform cursor` |
+| Codex | `AGENTS.md` | `npx @jtf19/vibecoding-kit init --target ../my-project --platform codex` |
+| 全部 | `CLAUDE.md` + `AGENTS.md` | `npx @jtf19/vibecoding-kit init --target ../my-project --platform all` |
 
 ## 已有入口文件
 
 如果目标项目已有 `CLAUDE.md` 或 `AGENTS.md`，先预览：
 
 ```bash
-npx vibecoding-kit init --target ../my-project --platform auto --merge=preview
+npx @jtf19/vibecoding-kit init --target ../my-project --platform auto --merge=preview
 ```
 
 确认无冲突后追加 managed block：
 
 ```bash
-npx vibecoding-kit init --target ../my-project --platform auto --merge=append
+npx @jtf19/vibecoding-kit init --target ../my-project --platform auto --merge=append
 ```
 
 Vibecoding 不会覆盖用户已有内容；只管理 `<!-- vibecoding:start -->` 到 `<!-- vibecoding:end -->` 之间的块。
@@ -67,7 +67,7 @@ Vibecoding 不会覆盖用户已有内容；只管理 `<!-- vibecoding:start -->
 ## 验证安装
 
 ```bash
-npx vibecoding-kit doctor --root ../my-project
+npx @jtf19/vibecoding-kit doctor --root ../my-project
 ```
 
 `doctor` 使用 summary-first 输出：
@@ -83,9 +83,9 @@ npx vibecoding-kit doctor --root ../my-project
 安装后可以用 lifecycle 命令预览升级、修复或卸载。它们默认是 dry-run，不会写文件：
 
 ```bash
-npx vibecoding-kit update --root ../my-project --dry-run
-npx vibecoding-kit repair --root ../my-project --dry-run
-npx vibecoding-kit uninstall --root ../my-project --dry-run
+npx @jtf19/vibecoding-kit update --root ../my-project --dry-run
+npx @jtf19/vibecoding-kit repair --root ../my-project --dry-run
+npx @jtf19/vibecoding-kit uninstall --root ../my-project --dry-run
 ```
 
 输出会先显示 `Impact summary` 和 `Safety boundary`，再按 `[planned]`、`[info]`、`[blocking]` 标注每个动作。只有确认计划符合预期时，才使用 `--confirm`。

package/docs/quick-recipes.md

@@ -4,7 +4,7 @@
 
 文档层级：L1 用户入口层。这里的命令用于安全观察和解释下一步；如果你要建立团队交付证据链，再进入 `docs/team-adoption.md`、`docs/evidence-authoring.md` 和 `docs/ci-evidence-onboarding.md`。
 
-安装、doctor、update、repair 和 uninstall 等 CLI 命令可以按 `docs/install.md` 使用 `npx vibecoding-kit ...`。本页的 `tools/vibe-runtime/index.mjs` recipe 面向源码仓库内的只读 runtime 观察，仍使用本地源码路径。
+安装、doctor、update、repair 和 uninstall 等 CLI 命令可以按 `docs/install.md` 使用 `npx @jtf19/vibecoding-kit ...`。本页的 `tools/vibe-runtime/index.mjs` recipe 面向源码仓库内的只读 runtime 观察，仍使用本地源码路径。
 
 ## 1. 只读入口判断
 

package/docs/release-guide.md

@@ -7,8 +7,8 @@
 第一阶段发布物应满足：
 
 - 可被用户阅读：从 `README.md` 能进入安装、诊断、验收和示例路径。
-- 可被用户安装：通过 `node bin/vibe.mjs init` 安装到业务项目，或兼容使用 `tools/vibe-init/index.mjs`。
-- 可被用户复验：通过 `node bin/vibe.mjs doctor` 检查 repo layout 或 installed layout，或兼容使用 `tools/vibe-doctor/index.mjs`。
+- 可被用户安装：通过 `npx @jtf19/vibecoding-kit init` 从 npm 安装到业务项目，或在源码仓库中通过 `node bin/vibe.mjs init` 本地安装。
+- 可被用户复验：通过 `npx @jtf19/vibecoding-kit doctor` 检查 installed layout，或在源码仓库中通过 `node bin/vibe.mjs doctor` 检查 repo layout / installed layout。
 - 可被维护者说明：明确哪些内容属于发布包，哪些内容只是参考或临时产物。
 
 ## 发布包应包含
@@ -46,7 +46,7 @@ examples/
 - `adapters/`：Claude、Codex、Cursor 平台适配文件。
 - `hooks/`：会话入口 bootstrap、handoff 检查和后续自动化预留。
 - `templates/`：安装到业务项目根目录的入口文件模板，以及产品发现、产品规格、UI contract、产品验收、场景验收、架构设计、交付追踪矩阵和 implementation plan artifact 模板。
-- `bin/` 和 `package.json`：无依赖 `vibe` CLI wrapper，负责路由到现有工具。
+- `bin/` 和 `package.json`：无依赖 `vibe` CLI wrapper，负责路由到现有工具；npm 包名为 `@jtf19/vibecoding-kit`，并发布 `vibe` 与 `vibecoding-kit` 两个 bin 名，保证 `npx @jtf19/vibecoding-kit ...` 和安装后的 `vibe ...` 入口都可用。
 - `tools/`：无依赖 Node.js 工具，包括 `vibe-init`、`vibe-doctor`、`vibe-lifecycle`、`vibe-plugin-pack`、`vibe-compact`、`vibe-runtime-check`、`vibe-runtime` 和 `vibe-release-check`。
 - `docs/`：安装、验收、发布和实现说明。
 - `examples/`：平台最小接入示例说明、`examples/golden-path/` team-mode readiness demo、`examples/full-chain/` full compliance reference、`examples/ci/` CI evidence producer recipe，以及 runtime fixtures。`examples/runtime-fixtures/negative/` 保存只读负例输入，用于证明缺 architecture、traceability ref 不存在、test evidence 缺 `output_digest`、diff coverage 出现 `unexpected_files`、commit boundary 扩权、changed file 缺 task_ref、required task 未覆盖、operation mismatch、风险 task 缺测试证据时 release fast smoke 会得到 `ok=false`。
@@ -131,7 +131,47 @@ AGENTS.md
 - 默认安装不启用 runtime。
 - 平台插件安装不等同于项目级 `vibe init`。
 - `.cursor-plugin` / `.codex-plugin` / `.claude-plugin` 当前是 `vibe plugin pack` 生成的草案产物，不作为常驻手写副本进入源码事实来源。
-- 当前推荐入口是 `node bin/vibe.mjs init`、`node bin/vibe.mjs doctor`、`node bin/vibe.mjs repair --dry-run`、`node bin/vibe.mjs uninstall --dry-run` 和 `node bin/vibe.mjs plugin pack --platform all --out .tmp/vibe-plugins --check`；原 `node tools/vibe-init/index.mjs` 和 `node tools/vibe-doctor/index.mjs` 继续作为兼容入口。
+- 当前推荐的 npm 用户入口是 `npx @jtf19/vibecoding-kit init`、`npx @jtf19/vibecoding-kit doctor`、`npx @jtf19/vibecoding-kit repair --dry-run` 和 `npx @jtf19/vibecoding-kit uninstall --dry-run`。源码仓库维护入口是 `node bin/vibe.mjs init`、`node bin/vibe.mjs doctor`、`node bin/vibe.mjs repair --dry-run`、`node bin/vibe.mjs uninstall --dry-run` 和 `node bin/vibe.mjs plugin pack --platform all --out .tmp/vibe-plugins --check`；原 `node tools/vibe-init/index.mjs` 和 `node tools/vibe-doctor/index.mjs` 继续作为兼容入口。
+
+## npm 发布步骤
+
+当前公开 npm 包名是 `@jtf19/vibecoding-kit`，必须作为 public scoped package 发布。发布前确认 `package.json` 包含：
+
+```json
+{
+  "name": "@jtf19/vibecoding-kit",
+  "bin": {
+    "vibe": "./bin/vibe.mjs",
+    "vibecoding-kit": "./bin/vibe.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+`vibecoding-kit` bin alias 是 npx smoke 的兼容入口；不要只保留 `vibe`，否则 `npx @jtf19/vibecoding-kit ...` 在部分 npm 环境中可能无法解析到命令。
+
+发布前运行：
+
+```bash
+npm run release:fast
+npm run release:install
+npm run pack:dry-run
+```
+
+发布命令：
+
+```bash
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+发布后验证：
+
+```bash
+npm view @jtf19/vibecoding-kit version --registry=https://registry.npmjs.org/
+npx --yes @jtf19/vibecoding-kit --help
+```
 
 ## 标准验证脚本
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jtf19/vibecoding-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Workflow skills and install tooling for safe, evidence-driven coding agents.",
   "type": "module",
   "license": "Apache-2.0",
@@ -24,7 +24,8 @@
     "evidence"
   ],
   "bin": {
-    "vibe": "./bin/vibe.mjs"
+    "vibe": "./bin/vibe.mjs",
+    "vibecoding-kit": "./bin/vibe.mjs"
   },
   "files": [
     "AGENTS.md",

package/tools/vibe-release-check/release-check-package-boundary-smoke.mjs

@@ -1,6 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+const expectedPackageName = '@jtf19/vibecoding-kit';
+const expectedBinEntries = Object.freeze({
+  vibe: './bin/vibe.mjs',
+  'vibecoding-kit': './bin/vibe.mjs',
+});
+
 const requiredPackageFiles = [
   'package.json',
   'README.md',
@@ -51,7 +57,25 @@ function normalizePackagePath(value) {
   return String(value || '').replaceAll('\\\\', '/').replaceAll('\\', '/');
 }
 
+function assertPackageEntryContract(packageJson) {
+  if (packageJson.name !== expectedPackageName) {
+    throw new Error(`package.json name must be ${expectedPackageName} for public npm npx entry`);
+  }
+
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(String(packageJson.version || ''))) {
+    throw new Error('package.json version must be a valid semver-like version for npm publication');
+  }
+
+  const bin = packageJson.bin || {};
+  for (const [name, target] of Object.entries(expectedBinEntries)) {
+    if (bin[name] !== target) {
+      throw new Error(`package.json bin.${name} must point to ${target}`);
+    }
+  }
+}
+
 function assertPackageMetadata(packageJson) {
+  assertPackageEntryContract(packageJson);
   if (packageJson.private === true) throw new Error('package.json must not set private=true for npm publication');
   if (packageJson.license !== 'Apache-2.0') throw new Error('package.json license must be Apache-2.0');
   if (!packageJson.repository?.url) throw new Error('package.json repository.url is required');