@dp-bohrium/widget-cli 0.1.0 → 0.3.0

package/llms.txt

@@ -2,24 +2,75 @@
 
 > Widget 工程的本地创建、校验、开发、构建和打包工具；可由 Bohr CLI 桥接或调度。
 
+要求 Node.js >=20。CLI 发布包固定 SDK/compiler、contracts/Schema、校验器和模板，
+提供文档站地址，不再内置 skills。生成工程仍安装自己的精确版本依赖。
+
+先看全局帮助，再按命令查看参数、默认值、示例和必要提示：
+
+```bash
+pnpm exec bohr-widget --help
+pnpm exec bohr-widget create --help
+pnpm exec bohr-widget help migrate dsh scaffold
+pnpm exec bohr-widget --version --json
+```
+
+无参数、`-h`、`--help`、`help` 显示全局帮助，包含版本、命令、选项、开发流程，
+以及文档站、快速开始、命令行指南和 `llms.txt` 链接。
+`<命令路径> --help` 与 `help <命令路径>` 查看对应层级；例如 `dev -h`、`pack --help` 或
+`migrate dsh --help`。`-v` / `--version` 等价于 `version`，`--version --json` 等价于 `version --json`。
+帮助仅输出本地文本，不执行所选命令或联网获取文档。npm 的全局帮助用
+`npx --no-install bohr-widget --help`，其他命令同样替换前缀；未安装时可用
+`pnpm dlx @dp-bohrium/widget-cli --help` 查看入口。
+
 ## Agent 入口
 
 - [Agent 使用说明](./AGENTS.md): 命令参数、执行顺序、错误恢复和安全边界。
 - [README](./README.md): 安装、模板和公开 core 出口。
+- [更新记录](./CHANGELOG.md): 当前 CLI 的使用者可感知变化；配套包职责与 npm 链接见 README。
+- [文档站索引](https://dev.dp.tech/bohrium-widget-sdk/llms.txt): 先按任务选择教程或参考。
+- [完整文档](https://dev.dp.tech/bohrium-widget-sdk/llms-full.txt): 文档站自动生成的全文。
 - 自闭环范围：本包负责本地工程闭环；上传、平台预览、版本发布和 Agent 绑定不在本包内执行。
 
 ## 本地闭环
 
-- `create`: 创建 vanilla 或 React 工程；工作区文件面板使用 `--panel-id workspace-files`。
+- `integration --json`: `interfaceVersion=2`，返回固定 profile、执行器位置、
+  `toolchain.formatVersion=2` 和 `documentation { url, quickStart, cli, llms, llmsFull }`，
+  不返回 `skills`。已有工程加 `--project <目录>` 核对锁定，再读取对应参考。
+- `create`: 创建 vanilla 或 React 工程并写 `widget-toolchain.json`；工作区文件面板使用
+  `--panel-id workspace-files`。
+- `adopt`: 为旧工程显式写入工具链锁，先核对精确依赖、实际 SDK/contracts、Manifest 和 samples。
+- SDK 0.5.0 的任务 Panel 在 Manifest 声明 `capabilities.tasks.list`；需要观察单个任务时再声明
+  `tasks.watch`。列表刷新遵守 grant 的 `minPollMs`，面板不可见后停止轮询；CLI 校验通过不代表
+  目标 Host 已签发 grant，详见 AGENTS.md。
+- SDK 0.5.0 文件读写按需在 Manifest 声明 `capabilities.files.read/write`，再实现
+  `context.files.read/write`；创建命令和模板保持原样。保存使用读取回执的内容版本与 mutationId，
+  缺授权、版本或完整性证据时只读；冲突/未知结果保留草稿且不自动重试，详见 AGENTS.md。
 - `check` / `validate`: 校验作者清单、Manifest、entry、samples 和 fixtures；`check all` 以
   当前工作目录为根，找不到工程时返回 `WIDGET_CLI_NO_WIDGET_PROJECT`，不会静默通过。
-- `dev`: 启动本地开发服务器和 Host Bridge 连接。
-- `build`: 委托工程自己的构建命令，并拒绝“退出 0 但仍有未解析依赖”的结果。
+- `dev`: 启动本地开发服务器和 Host Bridge 连接；每轮重建检查锁定信息和实际依赖，失败时保留上一轮。
+- `build`: 委托工程自己的构建命令，并拒绝“退出 0 但仍有未解析依赖”的结果，写入构建 receipt。
 - `pack`: 生成可交给平台的 ZIP，并输出 SHA-256 digest、Manifest 摘要和 CLI/SDK/Contracts 版本。
-- `doctor`: 输出 Node、SDK、Contracts 和工程状态（`ok` 看工程骨架，`ready` 再看依赖与构建入口）。
+  `--no-build` 要求 `.widget-build-receipt.json` 的工具链、实际依赖、输入和产物摘要全部匹配。
+  执行摘要仅含 `compiler`、`validators`、`schemas`、`templates`；文档站正文更新不影响
+  receipt，也不要求 CLI 发版。
+- `doctor`: 输出 Node、固定 profile 和工程状态；始终核对候选 profile 的精确依赖，已有锁定时再核对
+  profile，`ready` 还要求锁定、依赖和入口。
 - `schema`: 输出插件 Manifest Schema 路径。
 
+工程命令检查工程锁、package.json 精确版本与自身 node_modules 实际安装版本；升级 CLI 不会
+静默迁移工程。`/core` 是底层构建块，调用方自行承担锁定、实际依赖与宿主兼容预检。
+
+## 宿主兼容
+
+`--host-compat <文件>` 接受平台 statement 与调用方 observation。状态 `unknown` 表示无声明，
+`snapshot` 表示匹配的快照或过期声明，`confirmed` 表示调用方报告在线取得、仍有效且匹配当前
+profile；它不代表发布成功。无效声明或不匹配 profile 会报错。当前完成 A、B 本地能力，平台在线
+发现接口和 Bohr 获取声明仍需后续接入。
+
 ## 平台侧动作
 
 upload、preview、commit、Widget version publish 和 Agent binding 由 Bohr CLI 或平台服务
 负责，Widget CLI 不提供这些动作。
+
+当前开发宿主仍提供只读文件能力。sample grant、本地 build/check/pack 不代表目标 Host 已授权写入
+或完成文件持久化；真实保存需 Host 适配。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dp-bohrium/widget-cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Bohrium Widget 插件工程的创建、校验、开发和打包工具。",
   "license": "MIT",
   "type": "module",
@@ -15,7 +15,7 @@
     "cli"
   ],
   "author": "Bohrium",
-  "homepage": "https://www.npmjs.com/package/@dp-bohrium/widget-cli",
+  "homepage": "https://dev.dp.tech/bohrium-widget-sdk/",
   "bin": {
     "bohr-widget": "./dist/cli.mjs"
   },
@@ -34,6 +34,7 @@
   },
   "files": [
     "dist",
+    "assets",
     "src/core.d.mts",
     "src/development-host.d.mts",
     "README.md",
@@ -45,24 +46,24 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@dp-bohrium/widget-contracts": "0.3.0",
-    "@dp-bohrium/widget-sdk": "0.3.0"
-  },
   "devDependencies": {
     "@biomejs/biome": "^2.2.0",
     "@types/node": "^22.15.0",
     "tsdown": "0.22.14",
     "typescript": "5.9.3",
-    "@dp-bohrium/widget-contract-testing": "0.1.0-alpha.0"
+    "@dp-bohrium/widget-contract-testing": "0.1.0-alpha.0",
+    "@dp-bohrium/widget-contracts": "0.5.0",
+    "@dp-bohrium/widget-sdk": "0.5.0"
   },
   "sideEffects": false,
   "scripts": {
-    "build": "tsdown && node --check dist/cli.mjs",
-    "typecheck": "node --check src/cli.mjs && node --check src/core.mjs && node --check src/templates.mjs",
-    "test": "node --test test/*.test.mjs",
-    "lint": "biome check src test",
-    "format:check": "biome check --linter-enabled=false src test",
+    "build:assets": "node scripts/build-assets.mjs",
+    "build:inputs": "pnpm --filter @dp-bohrium/widget-sdk... run build && pnpm --filter @dp-bohrium/widget-contract-testing run build",
+    "build": "pnpm build:inputs && pnpm build:assets && tsdown && node --check dist/cli.mjs",
+    "typecheck": "node --check src/cli.mjs && node --check src/help.mjs && node --check src/core.mjs && node --check src/templates.mjs && node --check src/toolchain.mjs && node --check src/project-executor.mjs && node --check scripts/build-assets.mjs",
+    "test": "pnpm build:inputs && pnpm build:assets && node --test test/*.test.mjs",
+    "lint": "biome check src test scripts",
+    "format:check": "biome check --linter-enabled=false src test scripts",
     "package:contents": "node ../../scripts/quality/check-widget-cli-package-contents.mjs ../../.artifacts/dp-bohrium-widget-cli-*.tgz",
     "check": "pnpm --filter @dp-bohrium/widget-contracts build && pnpm --filter @dp-bohrium/widget-contract-testing build && pnpm --filter widget-project build && pnpm typecheck && pnpm test && pnpm lint && pnpm format:check && pnpm build"
   }