@dp-bohrium/widget-contracts 0.0.1 → 0.0.3

package/README.md

@@ -1,22 +1,32 @@
 # @dp-bohrium/widget-contracts
 
-Bohrium Widget Platform 的跨仓共享 Contract 包。它是 Manifest、Host
-Runtime Config、Runtime Bridge 消息及其相关类型的唯一事实源，供 Shrimp、
-Host Runtime、SDK Runtime 和 Widget 工具链共同消费。
+Bohrium Widget 平台的跨仓共享 Contract 包。它是 Manifest、Host Runtime Config、
+Runtime Bridge 消息及其相关类型的唯一事实源，供 Host、SDK Runtime 与 Widget
+工具链共同消费。
 
 本包只提供版本化 JSON Schema、由 Schema 生成的 TypeScript 类型和
 conformance fixtures，不提供生产 Runtime、AJV validator 或 Widget UI。
 
 ## 安装
 
-当前版本从 Bohrium 内部 npm Registry 安装，并建议固定到明确版本：
-
 ```bash
-pnpm add @dp-bohrium/widget-contracts@0.0.1 \
-  --registry=https://registry.npmjs.org
+pnpm add @dp-bohrium/widget-contracts
 ```
 
-运行环境要求 Node.js 20 或更高版本。
+运行环境要求 Node.js 20 或更高版本。需要钉死版本时，在消费方自己的
+`package.json` / lockfile 中锁定，而不是照抄过期的安装命令。
+
+### 消费方门禁 CLI
+
+包内附带 `check-no-legacy-bohrium-widget-scope`，用于禁止继续依赖已废弃的
+`@bohrium/widget-contracts` / `@bohrium/widget-sdk`（不影响
+`@bohrium/widget-runtime*`）：
+
+```bash
+pnpm exec check-no-legacy-bohrium-widget-scope
+# 或
+pnpm exec check-no-legacy-bohrium-widget-scope /path/to/consumer-repo
+```
 
 ## TypeScript 类型
 
@@ -40,7 +50,7 @@ function handleRender(request: RenderRequest) {
 主要导出包括：
 
 - `WidgetManifest`：Widget bundle 的 Manifest；
-- `WidgetHostRuntimeConfig`：Shrimp 为一次运行解析出的 Host Runtime Config；
+- `WidgetHostRuntimeConfig`：控制面为一次运行解析出的 Host Runtime Config；
 - `RenderRequest`：`tool-result`、`file-preview` 和 `panel` 三种 Slot 的渲染请求；
 - `HostToWidgetMessage` / `WidgetToHostMessage`：双向 Bridge 消息联合类型；
 - `CapabilityRequest` / `CapabilityResult`：能力请求与结果；
@@ -71,9 +81,9 @@ function handleRender(request: RenderRequest) {
 - `runtime.origin` 与 `catalogRevision` 由 Host Config 注入，消费者不得写死
   当前 Runtime 域名。
 
-`network.fetch` 只定义 Widget/Host 间的结构化能力契约，不让 Widget Runtime 依赖
-Agent Widget。默认 provider、无头授权控制器和复用 Agent Widget primitives 的默认弹窗
-由 Host 组合；Host 也可以替换 presenter 或整个 provider，因此无需新增独立设计系统。
+`network.fetch` 只定义 Widget/Host 间的结构化能力契约，不规定 Host 的 UI 实现。
+默认 provider、无头授权控制器和授权弹窗由 Host 组合；Host 也可以替换 presenter
+或整个 provider，因此无需新增独立设计系统。
 
 ## JSON Schema
 
@@ -83,7 +93,7 @@ Schema 文件通过包的子路径导出，可交给 AJV 或其他 JSON Schema 2
 | 文件 | 责任 | 主要消费者 |
 | --- | --- | --- |
 | `schemas/widget-manifest.schema.json` | bundle 名称、入口、Slot、能力申请和样例 | 上传与管理侧 |
-| `schemas/host-runtime-config.schema.json` | Shrimp 为一次运行选择的版本、Digest、授权和资源配置 | Host Runtime |
+| `schemas/host-runtime-config.schema.json` | 控制面为一次运行选择的版本、Digest、授权和资源配置 | Host Runtime |
 | `schemas/widget-runtime-contracts.schema.json` | iframe 启动后的 Bridge、Render、Capability、Error 和资源预算消息 | SDK Runtime / Host Runtime |
 
 例如，在支持 JSON module import 的 ESM 工程中：
@@ -98,9 +108,8 @@ import manifestSchema from
 Schema 的 `$id` 使用包内相对标识（例如 `widget-manifest.schema.json`），**不是**可联网拉取的 URL。
 依赖方必须从已安装的 `@dp-bohrium/widget-contracts/schemas/*.json` 本地加载并按 `$id` 注册，再解析 `$ref`；不要假设校验器会访问网络。
 
-公开探测版从 `0.0.1` 起发布到 npmjs（`@dp-bohrium`）。历史内部 prerelease
-（`0.1.0-alpha.*`）曾去掉 schema 文件名的 `.v1` 后缀、增加 Host 托管网络与
-Panel 能力，并移除静态 `outboundOrigins`；那些变更已并入当前 Contract。
+公开探测版发布到 npmjs（`@dp-bohrium`）。当前 Contract 已包含 Host 托管网络与
+Panel 能力，并移除静态 `outboundOrigins`；Schema 文件名不再使用 `.v1` 后缀。
 
 `host-runtime-config.schema.json` 通过包内 `$id`/`$ref` 指向 Manifest 与 Runtime
 Schema。跨语言消费者必须先从已安装的 schema 文件注册这两个 `$id`，再编译
@@ -148,7 +157,7 @@ const fixture = await import(
 
 ## 边界和版本约定
 
-- `host-runtime-config.schema.json` 是 Shrimp 与 Host Runtime 之间的配置
+- `host-runtime-config.schema.json` 是控制面与 Host Runtime 之间的配置
   Contract，不是 Widget 收到的 Bridge 消息；Host Runtime 只将必要视图通过
   `init` 消息传给 Widget。
 - 本包不实现 Runtime 行为，也不负责权限执行、iframe 隔离、CSP、资源治理
@@ -165,26 +174,8 @@ const fixture = await import(
   `resourceBudget.version` 承载，不进 schema 文件名或 `$id`。在进入稳定发布前，
   Contract 只有一套当前定义；如需破坏性调整，直接更新 prerelease 消费者，不创建
   V1/V2 sibling 或 `<name>.v2.schema.json`。
-- 类型由仓库根目录的生成脚本维护，不应直接编辑 `src/generated-*.ts`。
-
-## 仓库开发
-
-在 `bohrium-widget-sdk` monorepo 中运行：
-
-```bash
-pnpm --filter @dp-bohrium/widget-contracts generate:types
-pnpm --filter @dp-bohrium/widget-contracts schema:check
-pnpm --filter @dp-bohrium/widget-contracts typecheck
-pnpm --filter @dp-bohrium/widget-contracts test
-pnpm --filter @dp-bohrium/widget-contracts build
-```
-
-详细的协议设计见
-[`docs/design/widget-contract-v1.md`](../../docs/design/widget-contract-v1.md)。
 
-## 发布状态
+## 许可证
 
-当前 package metadata 配置为 Bohrium 内部受限 prerelease：Registry 为
-`https://registry.npmjs.org/`、访问级别为 `public`、许可证为 `MIT`。
-如果未来要发布到公开 npm Registry，必须先同步确认许可证、访问级别、
-Registry 和 CI 发布规则，再更新本 README 与 package metadata。
+MIT。发布到 [npmjs](https://www.npmjs.com/package/@dp-bohrium/widget-contracts)，
+`publishConfig.access` 为 `public`。

package/package.json

@@ -1,13 +1,29 @@
 {
   "name": "@dp-bohrium/widget-contracts",
-  "version": "0.0.1",
-  "description": "Versioned Widget schemas and generated contract types.",
+  "version": "0.0.3",
+  "description": "Bohrium Widget 平台的版本化 Schema 与生成类型（Manifest / Host Runtime Config / Bridge）。",
   "license": "MIT",
   "type": "module",
   "engines": {
     "node": ">=20"
   },
+  "keywords": [
+    "bohrium",
+    "dp-bohrium",
+    "widget",
+    "contracts",
+    "schema",
+    "json-schema",
+    "typescript",
+    "iframe",
+    "host-runtime"
+  ],
+  "author": "Bohrium",
+  "homepage": "https://www.npmjs.com/package/@dp-bohrium/widget-contracts",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "check-no-legacy-bohrium-widget-scope": "./scripts/check-no-legacy-bohrium-widget-scope.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -21,9 +37,11 @@
     "dist",
     "schemas",
     "conformance",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
+  "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
@@ -43,8 +61,8 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
-    "lint": "biome check src test",
-    "format:check": "biome check --linter-enabled=false src test",
+    "lint": "biome check src test scripts",
+    "format:check": "biome check --linter-enabled=false src test scripts",
     "build": "tsc -b tsconfig.build.json --pretty false",
     "check:surface": "node ../../scripts/quality/check-contract-surface.mjs",
     "check:no-coupling": "node ../../scripts/quality/check-no-coupling.mjs",

package/scripts/check-no-legacy-bohrium-widget-scope.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * Fail if a consumer still depends on or imports deprecated internal packages:
+ *   @bohrium/widget-contracts
+ *   @bohrium/widget-sdk
+ *
+ * Usage:
+ *   node path/to/check-no-legacy-bohrium-widget-scope.mjs [repoRoot]
+ *
+ * Does not flag @bohrium/widget-runtime or @bohrium/widget-runtime-protocol.
+ */
+import { lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const legacyNames = ["@bohrium/widget-contracts", "@bohrium/widget-sdk"];
+const skipDirNames = new Set([
+  ".git",
+  ".next",
+  ".pnpm-store",
+  ".turbo",
+  ".worktrees",
+  "coverage",
+  "dist",
+  "node_modules",
+  ".artifacts",
+]);
+const sourceExt = /\.(cjs|mjs|js|jsx|ts|tsx|json|md|yml|yaml)$/;
+const findings = [];
+const selfPath = resolve(fileURLToPath(import.meta.url));
+
+const root = resolve(process.argv[2] ?? process.cwd());
+
+function scanPackageJson(path) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    findings.push(`${relative(root, path)}: invalid JSON`);
+    return;
+  }
+  for (const field of [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+  ]) {
+    for (const name of Object.keys(pkg[field] ?? {})) {
+      if (legacyNames.includes(name)) {
+        findings.push(`${relative(root, path)} ${field}: ${name}`);
+      }
+    }
+  }
+}
+
+function scanSource(path) {
+  const text = readFileSync(path, "utf8");
+  for (const name of legacyNames) {
+    if (text.includes(name)) {
+      findings.push(`${relative(root, path)} contains ${name}`);
+    }
+  }
+}
+
+function walk(directory) {
+  let entries;
+  try {
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error && (error.code === "ENOENT" || error.code === "EACCES")) return;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (skipDirNames.has(entry.name)) continue;
+    const path = join(directory, entry.name);
+    // Skip dangling / opaque symlinks from package-manager caches.
+    let linkStat;
+    try {
+      linkStat = lstatSync(path);
+    } catch (error) {
+      if (error && (error.code === "ENOENT" || error.code === "EACCES")) continue;
+      throw error;
+    }
+    if (linkStat.isSymbolicLink()) continue;
+    let stat;
+    try {
+      stat = statSync(path);
+    } catch (error) {
+      if (error && (error.code === "ENOENT" || error.code === "EACCES")) continue;
+      throw error;
+    }
+    if (stat.isDirectory()) {
+      walk(path);
+      continue;
+    }
+    if (resolve(path) === selfPath) continue;
+    if (
+      entry.name === "pnpm-lock.yaml" ||
+      entry.name === "package-lock.json" ||
+      entry.name === "yarn.lock" ||
+      entry.name === "bun.lock" ||
+      entry.name === "bun.lockb"
+    ) {
+      // Lockfiles may still list transitive @bohrium/widget-* until upstream
+      // consumers migrate; policy is enforced on package manifests + source.
+      continue;
+    }
+    if (entry.name === "package.json") {
+      scanPackageJson(path);
+      continue;
+    }
+    // Docs that name the banned packages on purpose (migration guide / package README).
+    if (
+      entry.name.endsWith(".md") &&
+      (path.includes(`${join("docs", "superpowers")}`) ||
+        path.includes(`${join("docs", "operations", "consumer-governance")}`) ||
+        path.endsWith(`${join("packages", "contracts", "README.md")}`))
+    ) {
+      continue;
+    }
+    if (sourceExt.test(entry.name)) scanSource(path);
+  }
+}
+
+walk(root);
+
+if (findings.length > 0) {
+  console.error("Legacy @bohrium/widget-{contracts,sdk} references found:");
+  console.error(findings.map((line) => `- ${line}`).join("\n"));
+  console.error(
+    "\nMigrate to @dp-bohrium/widget-* on npmjs. See the @dp-bohrium/widget-contracts README.",
+  );
+  process.exit(1);
+}
+
+console.log("no legacy @bohrium/widget-contracts|widget-sdk OK");