@dp-bohrium/widget-cli 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,94 @@
+# Widget CLI Agent 使用说明
+
+`@dp-bohrium/widget-cli` 是 Widget 工程的本地执行器。Agent 应先读取本文件和
+`llms.txt`，再根据任务选择一个命令；不要猜测参数，也不要把 CLI 的成功输出解释为
+平台 已渲染或已发布。
+
+## 入口
+
+```bash
+bohr-widget create <目录> --template panel|file-preview --ui vanilla|react [--panel-id <id>] [--json]
+bohr-widget check|validate <目录|manifest.json|all> [--json]
+bohr-widget build <目录> [--json]
+bohr-widget dev <目录> [--watch] [--open] [--no-build] [--json]
+bohr-widget pack <目录> [--out <zip>] [--include-preview-fixtures] [--no-build] [--json]
+bohr-widget doctor [目录] [--json]
+bohr-widget schema
+bohr-widget migrate dsh audit <plugin-dir> [--json]
+bohr-widget migrate dsh scaffold <plugin-dir> --out <widget-dir> [--json]
+bohr-widget version [--json]
+bohr-widget help | -h | --help
+```
+
+## 执行顺序
+
+1. `create` 创建工程后检查返回的 `projectRoot`、`manifestPath`、`packagePath`、`name` 和可选
+   `panelId`；工作区文件面板固定使用 `--panel-id workspace-files`，CLI 会补齐三项只读文件能力。
+   `warnings` 说明目录名不是合法标识符时 `manifest.name` 已回退为 `widget-<hash>`。
+2. 安装工程依赖（`pnpm install` 或 `npm install`）。
+3. 执行工程 `build`（或 `bohr-widget build .`）。失败时先读取 JSON 里的 `error.message`（已带构建器
+   stderr 摘要）、`stdout` 和 `stderr`，不要直接重复执行。
+4. 执行 `check` 或 `validate`。`check` 要求入口已构建，未构建会报
+   `entry file is missing: dist/widget.js`，回到第 3 步。
+5. `pack --json` 成功后保存 `path`、`bytes`、`sha256`、`toolchain` 版本和 `manifest` 摘要。
+6. Bohr CLI 或平台侧必须继续使用同一份 ZIP 和 digest；Widget CLI 不负责 upload、preview、
+   commit、版本发布或 Agent binding。
+
+## check all
+
+`check all` 以当前工作目录为根，查找 `examples/sdk`、`examples/integration` 和当前目录的
+`manifest.json`；一个工程都没找到时返回 `error.code=WIDGET_CLI_NO_WIDGET_PROJECT`（退出码 1），
+不得把"没校验任何工程"当成通过。`--json` 输出单个汇总文档（`checked` / `passed` / `failed` /
+`results[]`）；传入单个目录或 `manifest.json` 时输出该工程的校验结果。`label` 是相对当前工作
+目录的路径，只在仓库外退化成绝对路径。
+
+## doctor
+
+`doctor --json` 的 `ok` 要求 Node 版本受支持、`package.json` 存在且
+`manifest.json` 是有效 JSON；`ready` 在此基础上还要求 `node_modules` 与构建入口存在。
+未安装依赖或未构建时 `ok=true` / `ready=false`，manifest 语法错误时 `ok=false`，原因在
+`warnings` 里。
+
+## 错误处理
+
+使用 `--json` 时，失败结果必须按 `ok=false` 处理。至少记录：
+
+- `command`：失败的命令；
+- `error.code`：机器分类；
+- `error.message`：给人的具体原因；
+- `error.context`：目录、Manifest、入口或构建阶段等上下文；
+- `error.recovery`：下一步可执行动作。
+
+常见 `error.code`：
+
+- `WIDGET_CLI_MANIFEST_INVALID`：作者清单本身有错（`version` 缺失或不是 semver、`displayName`
+  不是字符串、顶层有未知字段）。这类错误不再回落到宿主 schema，直接按 `errors` 里的字段名修。
+- `WIDGET_CLI_NO_WIDGET_PROJECT`：`check all` 没有匹配到工程。
+- `WIDGET_CLI_BUILD_FAILED`：工程 `build` 脚本失败；`error.message` 带构建器 stderr 首行，
+  `code=127` 通常意味着依赖没装。
+- `WIDGET_CLI_BUILD_UNRESOLVED_IMPORT`：构建器虽然退出 0，但输出仍包含未解析依赖；修正依赖和
+  bundler 配置后再构建，不能继续打包外置全局变量产物。
+- 其他命令失败是 `WIDGET_CLI_<COMMAND>_FAILED`，命令名已净化成大写标识符片段。
+
+`check` 失败通常先修 Manifest、entry、sample 或 fixture；`workspace-files` 还要求目录 fixture 中
+每个文件都有 `files.read` 内容，且 list/metadata 的 size 与实际字节数一致。`build` 失败先读取构建器输出；
+`pack` 失败先保留原工程和校验结果，不要上传不完整 ZIP。CLI 本地 `ok=true` 只说明本地
+检查或打包成功，不代表浏览器 iframe 已渲染、Widget 已发布或已绑定 Agent。
+
+`dev --json` 输出 `bohrium.widget-development-cli` v1 的逐行 NDJSON envelope；`session-ready`
+里带 `profileUrl`、`statusUrl`、`hostUrl`、digest 和 assets，不得把整个 stdout 当作单个 JSON
+文档解析。watch 重建失败时从 `statusUrl` 读取 `lastBuildError`，修复工程后重新保存源码或重新
+执行 build。`statusUrl` 是本地诊断接口，不是生产 Host API。
+
+`--open` 优先协商 Widget Development Host v1，旧宿主才回落 legacy profile 并告警。
+descriptor、status、events、control、一次性 claim 和 session token 都通过命令返回的 URL
+与类型声明表达；不要依赖源码仓库中的内部设计文档来猜测协议。
+
+DSH 迁移命令只读取源目录，不执行 Cordis patch 或源插件安装脚本；它不会把 Cordis runtime、
+tool、Skill、system prompt、文件系统、网络或 DSH client UI 嵌入 Widget。`source.fingerprint`
+变化、未知 profile 和阻断能力必须回到 `audit`，不得自动 scaffold。
+
+## 安全边界
+
+不要把 AccessKey、签名 URL、主机内部绝对路径或 Agent 凭据写入 Manifest、sample、ZIP、
+日志或错误上下文。上传、preview、commit、发布和绑定必须由 Bohr CLI 与平台服务执行。

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# `@dp-bohrium/widget-cli` 变更记录
+
+本文件记录使用者可感知的命令、工程模板、校验与打包能力变化。
+
+## 0.1.0
+
+### 新增
+
+**1. 创建可直接开发的 Widget 工程**
+
+- `create` 提供 Vanilla 与 React 模板，并生成 Manifest、构建配置、Host 入口和示例数据。
+- 生成项目只需要实现 `activate(context)`，无需手写 Bridge 或宿主加载字段。
+
+**2. 覆盖校验、开发、构建和打包闭环**
+
+- `check`、`build`、`dev`、`pack` 与 `doctor` 提供一致的命令行体验和结构化 JSON 输出。
+- `pack` 输出可追踪的 ZIP、SHA-256 摘要、工具链版本和 Manifest 摘要，便于 Agent 与自动化流程安全接续。
+
+**3. 提供明确的诊断与恢复信息**
+
+- 校验和构建失败会返回稳定的错误代码、具体原因、上下文与下一步恢复动作。
+- `doctor` 区分工程骨架是否有效与依赖、构建产物是否就绪，减少重复尝试。
+
+**4. 支持生成可直接绑定的工作区文件面板**
+
+- `create --panel-id workspace-files` 会生成稳定的 Panel id、完整的只读文件能力声明和对应 sample。
+- 生成工程统一执行 TypeScript 类型检查，避免错误源码被 bundler 当作可发布产物。
+
+### 修复
+
+**5. 阻止未解析依赖和不可点击的文件 fixture 混入产物**
+
+- `build` 会识别构建器退出码为 0 时仍存在的未解析依赖，并返回稳定错误码。
+- `check` 会校验 `workspace-files` 所需能力，以及目录 fixture 中每个文件的读取内容和字节大小。
+- `check` 与 `pack` 会在 Manifest 编译失败时保留原始契约错误，不再被二次异常覆盖。
+- DSH scaffold 会生成完整 TypeScript 配置；未解析依赖报错会指向实际命中的诊断行。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DP Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# @dp-bohrium/widget-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent 使用入口：先读 [`llms.txt`](./llms.txt) 获取文档索引，再读
+[`AGENTS.md`](./AGENTS.md) 获取命令、参数、错误和恢复规则。
+
+Bohrium Widget 插件工程工具。它把创建、校验、开发预览和打包收敛为一个开发者入口，
+不参与 Widget 运行时，也不暴露 Host 的 Bridge、iframe 或内部面板实现。
+
+```bash
+pnpm dlx @dp-bohrium/widget-cli create my-widget --template panel --ui react \
+  --panel-id workspace-files
+cd my-widget
+pnpm install
+bohr-widget build .
+bohr-widget check .
+bohr-widget pack .
+```
+
+`bohr-widget pack` 默认先执行工程自己的 `build` 脚本，再把作者维护的插件清单编译为宿主可加载的
+插件清单，并自动生成宿主入口、读取当前安装的 SDK 版本。开发者不需要填写构建后的 `dist`
+路径、`widgetSdkVersion`、`contribution` 或 Bridge 字段；需要复用已有构建产物时可使用 `--no-build`。
+`pack --out ./artifacts/release/widget.zip` 会自动创建父目录；`--json` 结果里的
+`fixtures.requested` / `fixtures.included` 说明 `preview/fixtures.json` 是否真的打进了 ZIP，
+被跳过时会出现在 `warnings` 中，不再静默忽略。
+
+`--ui vanilla` 生成原生 DOM 模板，`--ui react` 生成 React + TypeScript + `createRoot` 模板。
+两种模板都只导出 `activate(context)`；CLI 另外生成 `src/widget-host.ts`，由独立的
+Widget Host 启动边界调用 SDK。React 只是可替换的开发层，不会改变插件生命周期。
+
+创建工作区文件面板时使用 `--panel-id workspace-files`。CLI 会自动补齐
+`files.list`、`files.metadata`、`files.read` 和目录根 sample；其他 Panel id 只有在 Host
+已经注册并绑定对应路由时才能显示。
+
+生成的工程自带 `tsconfig.json`（含 `allowImportingTsExtensions`，React 模板附带 `jsx: react-jsx`）、
+`.gitignore` 和 `README.md`，`tsdown` 配置默认开启 `minify`（React 产物约 258 KB，未压缩约 1.06 MB）。
+工程 `build` 会先运行 `tsc --noEmit`；即便 bundler 返回退出码 0，CLI 也会拒绝包含未解析依赖
+诊断的构建结果。
+`create` 会把目录名规范化为 `manifest.name` 和 `contributes.widget.id`；目录名不是合法标识符
+（例如中文目录名）时回退为 `widget-<hash>` 并通过 `warnings` 说明。
+
+如果需要封装自己的 CLI，可以使用稳定的核心出口，不需要导入内部实现：
+
+```ts
+import {
+  createWidgetTemplateRegistry,
+  defineWidgetTemplate,
+  checkWidgetProject,
+  buildWidgetPackage,
+} from "@dp-bohrium/widget-cli/core";
+```
+
+`core` 提供模板注册、清单编译、工程校验和插件包打包；官方 `bohr-widget` 负责默认模板和命令行
+参数，社区工具可以自行选择 Vite、Webpack、esbuild 或其他 bundler。
+
+`@dp-bohrium/widget-cli/development-host` 只导出开发宿主的**类型**（`exports` 里只有 `types`
+条件），运行时 `import` 会抛 `ERR_PACKAGE_PATH_NOT_EXPORTED`；它是给类型检查用的，不是可执行入口。
+
+`bohr-widget dev` 提供本地开发服务器，`--watch` 可在源码变化后重新构建，`--open` 可连接
+Widget Development Host v1。SciX bridge 优先使用
+`POST /widget-host/desktop/v1/development-sessions`，不支持 v1 时回落 legacy profile 并告警。
+`bohr-widget dev --json` 输出 `bohrium.widget-development-cli` v1 的逐行 NDJSON envelope
+（`session-ready` 里带 `profileUrl`/`statusUrl`/`hostUrl`/`digest`/`assets`），不是单个 JSON
+文档；`--watch` 会在重建后继续追加 envelope。协议、安全 token、descriptor/status/events/control
+和不可变 generation 约束会通过 `session-ready`、状态接口与错误 envelope 返回；Agent 可按
+[`AGENTS.md`](./AGENTS.md) 的错误处理规则读取并恢复，不需要依赖仓库内部文档。
+
+`bohr-widget doctor --json` 适合接入 CI 和问题诊断：`ok` 表示 Node 版本、`package.json` 和
+有效的 `manifest.json` 都存在，`ready` 在此基础上还要求 `node_modules` 与构建入口存在，原因
+写在 `warnings` 里。尚未安装依赖或尚未构建时 `ok=true` / `ready=false`。
+
+## Bohr CLI 桥接契约
+
+Bohr CLI 可以把 Widget CLI 作为本地工程执行器调用。`widget-cli` 只负责工程创建、校验、
+构建、开发预览和 Bundle 打包；上传、preview、commit、版本发布和 Agent 绑定由 Bohr CLI
+及平台服务负责。
+
+需要机器消费结果时使用 `--json`：
+
+```bash
+bohr-widget create ./my-widget --template panel --json
+bohr-widget validate ./my-widget --json
+bohr-widget version --json
+bohr-widget pack ./my-widget --out ./artifacts/widget.zip --json
+```
+
+`validate` 是 `check` 的桥接别名。`check all` 以**当前工作目录**为根，依次查找
+`examples/sdk`、`examples/integration` 和当前目录的 `manifest.json`；找不到任何工程时返回
+`error.code=WIDGET_CLI_NO_WIDGET_PROJECT` 并以退出码 1 结束，不会静默通过。`check all --json`
+输出单个汇总文档（`checked` / `passed` / `failed` / `results[]`）；传入单个目录或
+`manifest.json` 时仍输出该工程的校验结果，与既有桥接契约一致。
+
+`check` / `validate` 会先补一遍作者清单检查：`version` 必填且为 semver、`displayName` 必须是
+字符串、顶层不允许未知字段、`entry` 指向的源文件必须存在（缺失只告警）。这些字段不会进入宿主
+清单，写错过去不会报错；现在直接返回 `error.code=WIDGET_CLI_MANIFEST_INVALID` 和具体字段名，
+而不是套用宿主 schema 后产生一串 `must NOT have additional properties`。
+对于 `workspace-files`，还会要求三项只读文件能力完整；存在 preview fixture 时，目录清单中的
+每个文件必须有 `files.read` 内容，声明的大小也必须与实际字节数一致。
+
+`pack --json` 返回产物路径、字节数、`sha256:<hex>`、
+CLI/SDK/Contracts `toolchain` 版本、Manifest 摘要和校验结果；Bohr CLI 应继续使用同一份 ZIP 和 digest，不要重新构建或替换
+产物字节。CLI 返回 `ok=true` 只证明本地校验或打包成功，不代表 平台 浏览器已经渲染，
+也不代表 Widget 已发布或绑定 Agent。
+
+## DeepSeek Harness 迁移
+
+迁移命令只读取 DSH 源目录，不执行 Cordis patch 或源插件安装脚本：
+
+```bash
+bohr-widget migrate dsh audit /path/to/dsh-plugin --json
+bohr-widget migrate dsh scaffold /path/to/dsh-plugin --out ./my-dsh-widget
+```
+
+审计结果包含 `rulesetVersion`、DSH profile、来源指纹、peer 版本范围和能力分级。只有已审查
+的精确来源指纹才允许 scaffold；指纹变化会进入 `source-changed`/`requires-review`，避免 DSH
+破坏式更新静默生成错误 Widget。工具执行、Skill、system prompt、文件、网络和 DSH client UI
+不会被嵌入 Widget，须由平台宿主适配器承接。`migration-report.json` 仅作旁车资料。
+
+`dsh-better-sidebar` 的已审查配方会生成声明 `capabilities.region` 的 `session.rightRail` Widget
+shell，并把文件树、编辑器、任务和侧聊继续标为 Host adapter 工作；审计状态仍是
+`requires-host-work`，因为生成 shell 不等于这些后端服务已经迁移。
+
+生成工程仍走普通 `check → build → pack`；上传、preview、commit、版本发布和 Agent binding
+由 Bohr CLI/平台执行，必须继续使用同一份 ZIP 与 digest。