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

package/llms.txt

@@ -0,0 +1,25 @@
+# @dp-bohrium/widget-cli
+
+> Widget 工程的本地创建、校验、开发、构建和打包工具；可由 Bohr CLI 桥接或调度。
+
+## Agent 入口
+
+- [Agent 使用说明](./AGENTS.md): 命令参数、执行顺序、错误恢复和安全边界。
+- [README](./README.md): 安装、模板和公开 core 出口。
+- 自闭环范围：本包负责本地工程闭环；上传、平台预览、版本发布和 Agent 绑定不在本包内执行。
+
+## 本地闭环
+
+- `create`: 创建 vanilla 或 React 工程；工作区文件面板使用 `--panel-id workspace-files`。
+- `check` / `validate`: 校验作者清单、Manifest、entry、samples 和 fixtures；`check all` 以
+  当前工作目录为根，找不到工程时返回 `WIDGET_CLI_NO_WIDGET_PROJECT`，不会静默通过。
+- `dev`: 启动本地开发服务器和 Host Bridge 连接。
+- `build`: 委托工程自己的构建命令，并拒绝“退出 0 但仍有未解析依赖”的结果。
+- `pack`: 生成可交给平台的 ZIP，并输出 SHA-256 digest、Manifest 摘要和 CLI/SDK/Contracts 版本。
+- `doctor`: 输出 Node、SDK、Contracts 和工程状态（`ok` 看工程骨架，`ready` 再看依赖与构建入口）。
+- `schema`: 输出插件 Manifest Schema 路径。
+
+## 平台侧动作
+
+upload、preview、commit、Widget version publish 和 Agent binding 由 Bohr CLI 或平台服务
+负责，Widget CLI 不提供这些动作。

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@dp-bohrium/widget-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Bohrium Widget 插件工程的创建、校验、开发和打包工具。",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "bohrium",
+    "dp-bohrium",
+    "widget",
+    "plugin",
+    "cli"
+  ],
+  "author": "Bohrium",
+  "homepage": "https://www.npmjs.com/package/@dp-bohrium/widget-cli",
+  "bin": {
+    "bohr-widget": "./dist/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/cli.mjs"
+    },
+    "./core": {
+      "types": "./src/core.d.mts",
+      "import": "./dist/core.mjs"
+    },
+    "./development-host": {
+      "types": "./src/development-host.d.mts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/core.d.mts",
+    "src/development-host.d.mts",
+    "README.md",
+    "AGENTS.md",
+    "llms.txt",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "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"
+  },
+  "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",
+    "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"
+  }
 }

package/src/core.d.mts

@@ -0,0 +1,58 @@
+export interface WidgetTemplateContext {
+  readonly name: string;
+  readonly ui?: "vanilla" | "react" | string;
+}
+
+export interface WidgetTemplate {
+  readonly id: string;
+  readonly description?: string;
+  manifest(context: WidgetTemplateContext): Record<string, unknown>;
+  sample(context: WidgetTemplateContext): Record<string, unknown>;
+  readonly source: string | ((context: WidgetTemplateContext) => string);
+}
+
+export interface WidgetTemplateRegistry {
+  register(template: WidgetTemplate): WidgetTemplate;
+  get(id: string): WidgetTemplate | undefined;
+  list(): readonly WidgetTemplate[];
+}
+
+export declare function defineWidgetTemplate(
+  template: WidgetTemplate,
+): WidgetTemplate;
+export declare function createWidgetTemplateRegistry(
+  initialTemplates?: readonly WidgetTemplate[],
+): WidgetTemplateRegistry;
+
+export declare function compileAuthorManifest(
+  manifest: Record<string, unknown>,
+  options?: Record<string, unknown>,
+): Record<string, unknown>;
+export declare function checkWidgetProject(
+  projectRoot: string,
+  options?: Record<string, unknown>,
+): Promise<Record<string, unknown>>;
+export declare function resolveWidgetProjects(input: string): readonly string[];
+export declare function auditDshPlugin(
+  input: string,
+): Promise<Record<string, unknown>>;
+export declare function scaffoldDshWidget(
+  input: string,
+  output: string,
+  options?: Record<string, unknown>,
+): Promise<Record<string, unknown>>;
+export declare function buildWidgetPackage(
+  project: Record<string, unknown>,
+  options?: Record<string, unknown>,
+): Uint8Array;
+
+export declare const widgetCliCore: {
+  readonly buildWidgetPackage: typeof buildWidgetPackage;
+  readonly checkWidgetProject: typeof checkWidgetProject;
+  readonly compileAuthorManifest: typeof compileAuthorManifest;
+  readonly resolveWidgetProjects: typeof resolveWidgetProjects;
+  readonly createWidgetTemplateRegistry: typeof createWidgetTemplateRegistry;
+  readonly defineWidgetTemplate: typeof defineWidgetTemplate;
+  readonly auditDshPlugin: typeof auditDshPlugin;
+  readonly scaffoldDshWidget: typeof scaffoldDshWidget;
+};

package/src/development-host.d.mts

@@ -0,0 +1,119 @@
+export interface WidgetDevelopmentEndpointSetV1 {
+  readonly claim: string;
+  readonly status: string;
+  readonly events: string;
+  readonly control: string;
+  readonly profile: string;
+}
+
+export interface WidgetDevelopmentDescriptorV1 {
+  readonly protocol: "bohrium.widget-development-host";
+  readonly protocolVersion: 1;
+  readonly sessionId: string;
+  readonly issuedAt: string;
+  readonly expiresAt: string;
+  readonly origin: string;
+  readonly endpoints: WidgetDevelopmentEndpointSetV1;
+}
+
+export interface WidgetDevelopmentClaimV1 {
+  readonly tokenType: "Bearer";
+  readonly accessToken: string;
+  readonly expiresAt: string;
+}
+
+export interface WidgetDevelopmentAssetV1 {
+  readonly path: string;
+  readonly bytes: number;
+  readonly digest: `sha256:${string}`;
+}
+
+export interface WidgetDevelopmentPresentationRequestV1 {
+  readonly requestId: string;
+  readonly key: string;
+  readonly surface: "workspace" | "floating" | "overlay";
+}
+
+export interface WidgetDevelopmentPanelProjectionV1 {
+  readonly key: string;
+  readonly runId: string;
+  readonly widgetId: string;
+  readonly widgetVersionId: string;
+  readonly snapshot: Readonly<{
+    id: string;
+    title?: string;
+    state: "loading" | "partial" | "complete" | "error";
+    data: unknown;
+  }>;
+  readonly presentation: Readonly<{
+    allowedSurfaces: readonly ("workspace" | "floating" | "overlay")[];
+    defaultSurface: "workspace" | "floating" | "overlay";
+    movable: boolean;
+    resizable: boolean;
+  }>;
+}
+
+export interface WidgetDevelopmentRuntimeDescriptorV1 {
+  readonly profileUrl: string;
+  readonly statusUrl: string;
+  readonly panel?: WidgetDevelopmentPanelProjectionV1;
+  readonly presentationRequests?: readonly WidgetDevelopmentPresentationRequestV1[];
+}
+
+export interface WidgetDevelopmentStatusV1 {
+  readonly protocolVersion: 1;
+  readonly state: "ready" | "stopping" | "build-failed";
+  readonly sessionId: string;
+  readonly revision: number;
+  readonly generation: number;
+  readonly updateAvailable: boolean;
+  readonly descriptor: WidgetDevelopmentRuntimeDescriptorV1;
+  readonly presentationRequests: readonly WidgetDevelopmentPresentationRequestV1[];
+  readonly digest: `sha256:${string}`;
+  readonly assets: readonly WidgetDevelopmentAssetV1[];
+  readonly watch: boolean;
+  readonly lastBuild: Readonly<Record<string, unknown>>;
+  readonly lastBuildError: Readonly<Record<string, unknown>> | null;
+}
+
+export type WidgetDevelopmentEventTypeV1 =
+  | "generation-ready"
+  | "generation-failed"
+  | "reload-requested"
+  | "session-stopping"
+  | "disconnected";
+
+export interface WidgetDevelopmentEventV1 {
+  readonly protocolVersion: 1;
+  readonly eventId: string;
+  readonly type: WidgetDevelopmentEventTypeV1;
+  readonly data: Readonly<Record<string, unknown>>;
+}
+
+export interface WidgetDevelopmentControlRequestV1 {
+  readonly protocolVersion: 1;
+  readonly action: "reload" | "disconnect";
+}
+
+export interface WidgetDevelopmentBridgeRequestV1 {
+  readonly protocol: "bohrium.widget-development-host";
+  readonly protocolVersion: 1;
+  readonly sessionId: string;
+  readonly descriptorUrl: string;
+  readonly expiresAt: string;
+}
+
+export interface WidgetDevelopmentBridgeResponseV1 {
+  readonly accepted: true;
+  readonly protocolVersion: 1;
+  readonly sessionId: string;
+}
+
+export interface WidgetDevelopmentCliEnvelopeV1<
+  T = Readonly<Record<string, unknown>>,
+> {
+  readonly protocol: "bohrium.widget-development-cli";
+  readonly version: 1;
+  readonly type: string;
+  readonly data: T;
+}