@huanlin/dsh-plugin-better-plan 0.4.0

package/lib/types/ws-route.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The `/better-plan/ws/delivery` push WebSocket: the host→browser channel
+ * for the sidebar's Plan tab (query `session=<sessionId>` attaches one view).
+ *
+ * The socket exists because the host half has no `betterSidebar` service —
+ * host→client pushes must ride a route the plugin owns. Two tagged JSON
+ * frames flow server→view:
+ *   `{ kind: 'deliver', id, path, title }`      — one plan delivery;
+ *   `{ kind: 'review', review: ReviewState|null }` — the review state
+ *     (replayed on attach, pushed on every change).
+ *
+ * @module @huanlin/dsh-plugin-better-plan/ws-route
+ */
+import type { PlanDeliveryRegistry } from './delivery-registry.ts';
+import type { LocaleDirectory } from './locale.ts';
+import type { PlanReviewGate } from './review-gate.ts';
+import { type FenceRequest } from './trust-fence.ts';
+/** The exact upgrade path registered on the host webServer. */
+export declare const DELIVERY_WS_PATH = "/better-plan/ws/delivery";
+/** The upgrade request face the route handler receives (headers + url). */
+export interface DeliveryUpgradeRequest extends FenceRequest {
+    url?: string;
+}
+/** The upgrade socket face the attach helper needs (the subset of `ws`'s WebSocket). */
+export interface DeliverySocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: 'close' | 'error', listener: () => void): unknown;
+}
+/**
+ * Wire one delivery socket to the registries: parse `?session=` (and the
+ * view-reported `?locale=`, recorded so the host's user-facing copy follows
+ * the browser's active DSH locale), attach the delivery queue (replaying
+ * queued pushes) and the review gate (replaying the latest review state),
+ * and detach on close/error so later pushes queue instead of accumulating
+ * on a dead socket.
+ * @param registry - the delivery registry.
+ * @param gate - the review gate.
+ * @param ws - the connected socket.
+ * @param req - the upgrade request.
+ * @param directory - the locale directory the reported locale is recorded in.
+ */
+export declare function attachDeliverySocket(registry: PlanDeliveryRegistry, gate: PlanReviewGate, ws: DeliverySocket, req: DeliveryUpgradeRequest, directory: LocaleDirectory): void;
+/**
+ * Register the delivery upgrade route on the host webServer.
+ * @param registerUpgrade - the webServer's route registrar.
+ * @param registry - the delivery registry.
+ * @param gate - the review gate.
+ * @param trustedHosts - non-loopback authorities the deployment serves.
+ * @param directory - the locale directory view reports are recorded in.
+ * @returns the route disposer.
+ */
+export declare function registerDeliveryRoute(registerUpgrade: (route: {
+    path: string;
+    handler: (req: DeliveryUpgradeRequest, socket: {
+        destroy(): void;
+    }, head: Uint8Array) => void | Promise<void>;
+}) => () => void, registry: PlanDeliveryRegistry, gate: PlanReviewGate, trustedHosts: readonly string[], directory: LocaleDirectory): () => void;

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "@huanlin/dsh-plugin-better-plan",
+  "version": "0.4.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "dsh-better-sidebar"
+  ],
+  "description": "取代 DSH 内置 plan mode 的计划交付体验：计划先写成 markdown 文件，经侧边栏「计划面板」展示，聊天里只剩紧凑审批卡（审批流与原版一致）。 | Replaces the built-in plan mode's plan delivery: plans are written to a markdown file first and shown in the better-sidebar plan panel, leaving only a compact review card in chat (approval flow unchanged).",
+  "type": "module",
+  "license": "AGPL-3.0",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/",
+    "!lib/*.map",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-plan-mode": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-user-questions": "^0.1.2-rc.1",
+    "dsh-better-sidebar": "^0.17.1",
+    "react": "^18.2.0",
+    "schemastery": "^3.18.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-primitives": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-plan-mode": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-user-questions": {
+      "optional": true
+    },
+    "dsh-better-sidebar": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "schemastery": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^22.20.1",
+    "@types/react": "~18.3.31",
+    "@types/react-dom": "~18.3.1",
+    "@types/ws": "^8.5.10",
+    "jsdom": "^25.0.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "schemastery": "^3.18.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
+    "test": "vitest run",
+    "build": "tsdown --config tsdown.config.ts && tsc -p tsconfig.build.json",
+    "bundle:client": "tsdown --config tsdown.config.ts"
+  }
+}