prd-to-flutter 0.1.0 → 0.1.1

package/README.md

@@ -20,23 +20,29 @@ p2f 是为 PRD 原型页面采集还原数据、生成实现计划的 CLI。它
 ## 环境要求
 
 - Node.js `>= 20`
-- Git 和公司 GitLab SSH 权限
+- Git 和 PRD 原型源码仓库访问权限
 - Flutter SDK
 - YouFi Flutter 项目根目录，通常需要存在 `pubspec.yaml` 和 `lib/app`
-- CLI 会从公司 GitLab 克隆/拉取 PRD 原型仓库到当前项目的 `.p2f-workspace/prd-source`：
-  - 远端：`git@code.nexita.net:inno/youfi/web/TradeAppPrd.git`
-  - 分支：`master`
+- CLI 会把 PRD 原型源码同步到当前项目的 `.p2f-workspace/prd-source`
 
 `p2f init` 会自动安装 PRD 依赖、Playwright Chromium 和内置 p2f skill，不需要手工运行 `npx playwright install chromium`。升级 CLI 或内置 skill 变更后，可以重新执行 `p2f skills-install` 安装/更新 agent 规则。
 
 ## 安装
 
-从公司 GitLab 仓库全局安装，建议使用 tag 固定版本：
+从 npmjs.com 全局安装：
 
 ```bash
-npm install -g git+ssh://git@code.nexita.net/inno/youfi/client/prd-to-flutter.git#v0.1.0
+npm install -g prd-to-flutter
 ```
 
+升级到 npmjs.com 上的最新版本：
+
+```bash
+npm install -g prd-to-flutter@latest
+```
+
+包页面见 [prd-to-flutter](https://www.npmjs.com/package/prd-to-flutter)。
+
 本地开发见 [维护与发布](docs/development.md)。
 
 ## 快速开始
@@ -75,8 +81,6 @@ p2f generate --page "订单详情" "https://example.com/prototype/order-detail"
 | `p2f paths --url "<页面链接>"` | 打印当前项目的 p2f 工作区、共享项目快照、pages 和任务目录路径。 |
 | `p2f screenshots-audit --url "<页面链接>"` | 审计 agent 截图目录，识别重复截图和疑似截到原型平台壳层的错误截图。 |
 | `p2f doctor` | 检查环境、skill、`.p2f-workspace/prd-source` 和 p2f 版本。 |
-| `p2f update --check` | 检查当前 p2f 是否有新版本，不安装。 |
-| `p2f update` | 从公司 GitLab 最新 tag 重新全局安装 p2f CLI。 |
 
 完整命令表见 [使用流程](docs/usage.md#常用命令)。
 

package/docs/development.md

@@ -4,28 +4,16 @@
 
 ## 更新 CLI
 
-p2f 使用公司 GitLab tag 作为版本来源。检查新版本：
+发布版从 npmjs.com 更新：
 
 ```bash
-p2f update --check
+npm install -g prd-to-flutter@latest
 ```
 
-从最新 tag 重新安装 p2f CLI：
+需要确认 npmjs.com 上的最新版本时执行：
 
 ```bash
-p2f update
-```
-
-`p2f update` 会执行全局 npm 安装，效果等同于重新运行：
-
-```bash
-npm install -g git+ssh://git@code.nexita.net/inno/youfi/client/prd-to-flutter.git#<最新tag>
-```
-
-如果 p2f CLI 的 GitLab 安装来源变更，可以临时指定：
-
-```bash
-p2f update --repo git@code.nexita.net:inno/youfi/client/prd-to-flutter.git
+npm view prd-to-flutter version --registry https://registry.npmjs.org/
 ```
 
 ## 发布

package/docs/usage.md

@@ -37,8 +37,6 @@ p2f init
 | `p2f screenshots-audit --url "<页面链接>"` | 审计 agent 截图目录，识别重复截图和疑似截到原型平台壳层的错误截图。 |
 | `p2f doctor` | 检查环境、skill、`.p2f-workspace/prd-source` 和 p2f 版本。 |
 | `p2f doctor --offline` | 跳过远端网络检查，只检查本地状态。 |
-| `p2f update --check` | 检查当前 p2f 是否有新版本，不安装。 |
-| `p2f update` | 从公司 GitLab 最新 tag 重新全局安装 p2f CLI。 |
 | `p2f skills-install` | 把当前 CLI 自带的 p2f skill 安装/更新到当前项目的 agent 目录。 |
 
 ## 标准流程
@@ -174,8 +172,6 @@ p2f 面向人类和 agent 共同使用。所有命令都可以手工执行；执
 | `p2f remove` | `remove` | 删除 `.p2f-workspace/` 和当前项目下的 p2f agent skills；不卸载全局 CLI。 |
 | `p2f screenshots-audit` | `screenshots-audit` | 扫描 agent 写入的 `agent/screenshots/`，输出重复图分组和疑似平台壳层截图告警。 |
 | `p2f doctor` | `environment-checks` -> `skill-check` -> `prd-source-check` -> `update-check` | 检查环境、初始化状态和版本；`--offline` 会跳过网络检查。 |
-| `p2f update --check` | `update-check` | 只检查是否有新版本。 |
-| `p2f update` | `update-check` -> `update-install` | 检查 p2f CLI 版本，并用最新 tag 重新执行全局安装。 |
 | `p2f skills-install` | `skill-install` | 安装/更新内置 p2f skill；不修改 PRD 源码和页面目录。 |
 
 ## Generate 流程

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prd-to-flutter",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "为 PRD 原型页面采集 YouFi Flutter 还原数据并生成实现计划的 CLI。",
   "type": "module",

package/skills/p2f/SKILL.md

@@ -38,8 +38,6 @@ p2f remove
 p2f screenshots-audit --url "<页面链接>"
 p2f doctor
 p2f doctor --offline
-p2f update --check
-p2f update
 ```
 
 `p2f init` 会自动安装 PRD 依赖、Playwright Chromium 和内置 p2f skill，不需要手工执行 `npx playwright install chromium`。
@@ -211,10 +209,9 @@ p2f paths --url "<页面链接>"
 
 ## 更新检查
 
-- `p2f doctor` 会顺带检查 p2f 是否落后公司 GitLab 最新 tag；这只是提醒项，不负责安装。
+- `p2f doctor` 会顺带检查 p2f CLI 版本；这只是提醒项，不负责安装。
 - `p2f doctor --offline` 跳过 PRD 仓库新鲜度和 p2f 版本这类网络检查。
-- `p2f update --check` 只检查新版本。
-- `p2f update` 从公司 GitLab 最新 tag 重新全局安装 p2f CLI，行为和 `lark-cli update` 一致。
+- 发布版升级使用 `npm install -g prd-to-flutter@latest`。
 
 ## 命令阶段
 
@@ -231,8 +228,6 @@ p2f 面向人类和 agent 共同使用，所有命令都可以由人类直接执
 - `p2f remove`：`remove`，用于删除当前项目里的 `.p2f-workspace/` 和 p2f agent skills；不卸载全局 CLI。
 - `p2f screenshots-audit --url "<页面链接>"`：`screenshots-audit`，用于审计 agent 截图目录中的重复图和疑似原型平台壳层截图。
 - `p2f doctor`：`environment-checks` -> `skill-check` -> `prd-source-check` -> `update-check`。
-- `p2f update --check`：`update-check`。
-- `p2f update`：`update-check` -> `update-install`，检查 p2f CLI 版本并用最新 tag 重新执行全局安装。
 - `p2f skills-install`：`skill-install`，用于安装/更新当前 CLI 自带的 p2f skill；不修改 PRD 源码和页面目录。
 
 ## 主题文件

package/skills/p2f-npm-publish/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: p2f-npm-publish
+description: Use when publishing the prd-to-flutter/p2f CLI package to npmjs.com, preparing npm release checks, running the repository publish:npm script, handling npm auth/2FA/version conflicts, and verifying the package contents before upload.
+metadata:
+  short-description: Publish p2f CLI to npmjs.com
+---
+
+# p2f npm Publish
+
+当用户要求把当前 `prd-to-flutter` 仓库里的 p2f CLI 发布到 npmjs.com，或要求“重新发布 npm 包”“检查 npm 发布流程”“跑 publish:npm”时使用本 skill。
+
+## 核心原则
+
+- 只在当前 `prd-to-flutter` 仓库根目录执行发布相关命令。
+- 默认先 dry-run，不要直接真实发布。
+- 真实发布必须显式执行 `npm run publish:npm -- --publish`。
+- 发布前必须确认 `package.json` 里 `private` 不是 `true`，`version` 是要发布的版本，`files` 包含运行所需的 `dist`、`bin`、`skills`、`docs`、`README.md`。
+- 遇到 npm 登录失败、2FA、版本已存在、包名冲突时停止并报告具体阻塞，不要绕过检查强发。
+
+## 标准流程
+
+### 1. 检查当前状态
+
+```bash
+cd <prd-to-flutter-repo-root>
+git status --short
+sed -n '1,90p' package.json
+```
+
+确认重点：
+
+- `<prd-to-flutter-repo-root>` 是包含 `package.json`、`scripts/publish-npm.mjs` 和 `skills/p2f-npm-publish/SKILL.md` 的仓库根目录。
+- `name` 当前是 `prd-to-flutter`。
+- `bin.p2f` 指向 `bin/p2f.mjs`。
+- `publishConfig.registry` 是 `https://registry.npmjs.org/`。
+- `scripts.publish:npm` 是 `node scripts/publish-npm.mjs`。
+
+### 2. 检查版本是否已存在
+
+```bash
+npm view prd-to-flutter@$(node -p "require('./package.json').version") version --registry https://registry.npmjs.org/
+```
+
+如果返回当前版本，说明该版本已经发布过，需要先升级版本号。不要对同一版本重复发布。
+
+如果返回 npm `E404`，表示该版本还不存在，可以继续。
+
+### 3. 先跑 dry-run
+
+```bash
+npm run publish:npm
+```
+
+该命令会：
+
+- 检查 registry 上是否已有当前版本。
+- 执行 `npm run build`。
+- 执行 `npm run typecheck`。
+- 执行 `npm publish --dry-run`。
+
+dry-run 成功后，检查输出里的 Tarball Contents，必须看到：
+
+- `bin/p2f.mjs`
+- `dist/cli.js`
+- `dist/commands/**`
+- `dist/core/**`
+- `skills/p2f/SKILL.md`
+- `skills/p2f-npm-publish/SKILL.md`
+- `docs/**`
+- `README.md`
+- `package.json`
+
+如果 npm 提示会自动修正 `package.json`，先修正本地元数据，再重新 dry-run。
+
+### 4. 登录 npm
+
+真实发布前检查登录：
+
+```bash
+npm whoami --registry https://registry.npmjs.org/
+```
+
+如果未登录，让用户先执行：
+
+```bash
+npm login --registry https://registry.npmjs.org/
+```
+
+CI 环境可以使用 `NPM_TOKEN`，但本地交互发布优先让用户完成 `npm login`。
+
+### 5. 真实发布
+
+```bash
+npm run publish:npm -- --publish
+```
+
+如果 npm 账号开启双因素认证：
+
+```bash
+npm run publish:npm -- --publish --otp <一次性验证码>
+```
+
+如果要使用非 latest 标签：
+
+```bash
+npm run publish:npm -- --publish --tag beta
+```
+
+### 6. 发布后验证
+
+```bash
+npm view prd-to-flutter version versions --json --registry https://registry.npmjs.org/
+npm view prd-to-flutter bin files --json --registry https://registry.npmjs.org/
+```
+
+确认 latest 版本和 `bin.p2f` 正确后，再向用户汇报。
+
+## 常见阻塞
+
+- `npm whoami` 401：未登录或 token 无效。先 `npm login`，不要继续发布。
+- `npm view <name>@<version>` 返回版本号：该版本已存在。先 bump version。
+- `npm publish` 提示 2FA：让用户提供一次性验证码，使用 `--otp` 重新发布。
+- `npm publish --dry-run` 包内容缺 `dist`：先修复 `npm run build` 或 `files` 配置。
+- `npm publish --dry-run` 提示 package metadata 自动修正：先修正 `package.json`，重新 dry-run。
+
+## 相关脚本
+
+- `scripts/publish-npm.mjs`：npmjs.com 发布脚本，默认 dry-run，`--publish` 才真实上传。
+- `scripts/release.mjs`：Git release 脚本，只负责 bump version、commit、tag、push，不负责 npm registry 发布。
+- `docs/development.md`：人类可读的发布说明。