@lmzhen/dsh-evolution-skill-health 0.0.0-stage → 0.25.0

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @lmzhen/dsh-evolution-skill-health
 
-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.
+技能健康面板：把体检引擎（`evolution-core` 的 skill-lint／skill-health）的结论**按规则聚合**呈现，
+让"哪条规则在哪些技能上出现、本次改动新引入了什么"一眼可见。**只读**：不写任何技能、不改任何配置。
+
+## 座位与注册（照 `evolution-skill-history` 的成例）
+
+- 侧栏行：`ctx.slots.inject('sidebar.panellist', …)` ＋ `slots.register({ name: 'sidebar.panellist', id, order, label: () => … })`；
+  `label` 必须是 **thunk**（跟语言切换走 ✓），`order` 取 40 一带（与技能历史相邻 ✓）；`sidebar.panellist` 是**列表座位** ⇒ 多个面板可并存 ✓。
+- 主区：`slots.register({ name: 'main', key: <同一个 id>, inject })` —— **同一个 id 注册两次**，这是本家族面板的既定契约 ✓。
+
+## 数据来源与边界
+
+- **数据**：只经只读通道取引擎结论（`healthView()` 一类的**全量行**：`{ name, verdict, dims, findings }` ✓；读不到的技能以 `unreadable-skill` 呈现，**不沉默** ✓）。
+- **呈现**：总览四态（ok／warn／error／不可读）＋ **按规则聚合**的清单 ＋ 与技能历史／技能目录的交叉跳转；
+  `line: …`／`line: UNKNOWN` 两态要写清（未知就是未知 ✓）。
+- **不上屏**：**未标定**的阈值（如 `SUPPORT_SPRAWL_FILES`）**只报规则名、不报数字** ✓ —— 口径冻结之前不许把数字给读者 ✓。
+- 客户端半**不得** import 其它插件的值/类型 ⇒ 只声明自己消费的座位形状（见 `evolution-settings-ui/src/client/seam.ts` 的头注释 ✓）。
+
+## 当前状态
+
+**占名已发布**（npm `@lmzhen/dsh-evolution-skill-health`，占位版本 `0.0.0-stage` ✓）；本包的 `src/` 内容随后补齐，
+**首次真实内容必须发更高版本** ✓（"已发布只能抬版本"）。

package/lib/index.js

@@ -0,0 +1,83 @@
+//#region lib/types/routes.js
+/**
+* The panel's ONE read-only route: the health rows the browser half renders.
+*
+* Read-only by construction: it never writes a skill, a marker or a config. It also carries the
+* house rule down to the client — a rule whose threshold is NOT calibrated yet is reported with
+* `countIsMeaningful: false`, so the panel can name it without printing a number we do not have.
+* @module @lmzhen/dsh-evolution-skill-health
+*/
+/** Where the panel asks for its rows. */
+const ROUTES = { rows: "/api/dsh-evolution/skill-health/rows" };
+/** Rules whose threshold is not calibrated yet: named on screen, never counted. */
+const UNCALIBRATED_RULES = ["references-sprawl"];
+/**
+* Project the curator's health view into what the panel renders.
+* @param rows - `{ name, verdict, dims, findings }` per skill, as `healthView()` returns them.
+* @returns the same rows, with unreadable skills kept apart and uncalibrated rules uncounted.
+*/
+function toRouteRows(rows) {
+	return rows.map((row) => ({
+		name: row.name,
+		verdict: row.dims?.readable === false ? "unreadable" : row.verdict,
+		findings: row.findings.map((finding) => ({
+			rule: finding.rule,
+			count: finding.count,
+			line: finding.line ?? null,
+			countIsMeaningful: !UNCALIBRATED_RULES.includes(finding.rule)
+		}))
+	}));
+}
+/**
+* Build the panel's routes, in the platform shape: `{ path, handler(req, res) }` — the same objects
+* `ctx.webServer.register` takes for every other row in this family.
+* @param deps - a getter for the curator service (absent until the profile mounts it).
+* @returns one GET route; with no curator it answers an EMPTY row list plus `truncated: true`, which
+*   the panel shows as "cannot decide right now" rather than as a pass.
+*/
+function makeSkillHealthRoutes(deps) {
+	return [{
+		kind: "exact",
+		path: ROUTES.rows,
+		handler: async (_req, res) => {
+			const curator = deps.getCurator();
+			const view = curator?.healthView === void 0 ? void 0 : await curator.healthView();
+			const rows = Array.isArray(view) ? toRouteRows(view) : [];
+			res.writeHead(200, { "content-type": "application/json" });
+			res.end(JSON.stringify({
+				rows,
+				truncated: view === void 0
+			}));
+		}
+	}];
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Host half: ONE read-only route, mounted when the profile gives this row a web server.
+*
+* **Why `ctx.inject` and not `ctx.get`**: profile rows apply in file order, so at this row's apply
+* time the web server may not exist yet — a `ctx.get('webServer')` of undefined is a TIMING fact,
+* not a verdict, and acting on it leaves the route unregistered while the panel renders and every
+* call answers 404. Waiting on the service mounts the route whenever it arrives, and a profile that
+* never gets one simply never runs this callback — inert, never pending.
+* @module @lmzhen/dsh-evolution-skill-health
+*/
+/** No required services: the web server is WAITED ON below, not demanded here. */
+const inject = [];
+/**
+* Mount the route as ONE effect (disposers run on unload and on HMR).
+* @param ctx - the host context; the web server and curator arrive through it.
+*/
+function apply(ctx) {
+	ctx.inject(["webServer"], (scope) => {
+		scope.effect(() => {
+			const disposers = makeSkillHealthRoutes({ getCurator: () => scope.get("evolutionCurator") }).map((route) => scope.webServer.register(route));
+			return () => {
+				for (const dispose of disposers) dispose();
+			};
+		}, "evolution-skill-health: routes");
+	});
+}
+//#endregion
+export { apply, inject };

package/lib/types/client/Panel.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The panel body: a four-state summary plus the list aggregated BY RULE.
+ *
+ * It renders plain data and callbacks handed in by the sidebar (`inject`), never a service, and it
+ * holds no facts of its own. Two rules of the house are visible here: a rule whose threshold is not
+ * calibrated yet is NAMED WITHOUT A NUMBER (the number is the thing we do not have), and a skill
+ * that could not be read is listed as unreadable — silence would read as a pass.
+ * @module @lmzhen/dsh-evolution-skill-health/client
+ */
+import { type ReactNode } from 'react';
+import type { LocaleSeat } from './seam.ts';
+/** One finding, as the host reports it: `line` is null when the position cannot be named. */
+export interface HealthFinding {
+    rule: string;
+    count: number;
+    line: string | null;
+    /** False for a rule whose threshold is not calibrated: the rule is named, the count is not shown. */
+    countIsMeaningful: boolean;
+}
+/** One skill row. `readable: false` is its own verdict — never folded into `ok`. */
+export interface HealthRow {
+    name: string;
+    verdict: 'ok' | 'warn' | 'error' | 'unreadable';
+    findings: HealthFinding[];
+}
+/** What the sidebar hands the component. */
+export interface HealthFace {
+    rows: HealthRow[];
+    /** True when the host could not finish the scan: the counts below are then a lower bound. */
+    truncated: boolean;
+    /** Opens the skill-history panel for one skill, when that panel is present. */
+    openHistory?: (name: string) => void;
+}
+/**
+ * Render the panel.
+ * @param props - the face (`{ rows, truncated, openHistory? }`) and the locale seat's translator.
+ * @returns the panel body.
+ */
+export declare function SkillHealthPanel(props: {
+    face: HealthFace;
+    locale: LocaleSeat;
+}): ReactNode;
+//# sourceMappingURL=Panel.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Browser half: one left-sidebar row (`技能健康`) and the main-column body it opens.
+ *
+ * Two places, one id: `sidebar.panellist` owns the row and the layout's keyed `main` slot owns the
+ * body, dispatched by that same id. Facts arrive through a loader the HOST half supplies, so this
+ * bundle keeps no state of its own and touches no service.
+ * @module @lmzhen/dsh-evolution-skill-health/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type HealthFace } from './Panel.ts';
+/** Required client services: the slot registry and the locale seat. */
+export declare const inject: string[];
+/** The host half hands the panel a way to read its rows (a read-only route on the host side). */
+export type HealthFaceLoader = () => Promise<HealthFace>;
+/**
+ * Register the row and the body.
+ * @param ctx - the client context; it must carry the two seats above.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/messages.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Panel copy, in a zh/en dictionary registered through the platform's locale seat.
+ *
+ * Client copy is locale-owned: the entry label, the group headings, the verdict words, the empty
+ * and failure lines all resolve here, and the panel carries no literal string of its own. Facts come
+ * from the host; only the WORDS live here. Two lines exist to keep silence honest: a rule whose
+ * threshold is NOT calibrated is named without a number, and an unreadable skill is never a pass.
+ * @module @lmzhen/dsh-evolution-skill-health/client
+ */
+/** The locale namespace this bundle registers. */
+export declare const NS = "evolution-skill-health";
+/** Chinese dictionary. */
+export declare const zh: Record<string, string>;
+/** English dictionary. */
+export declare const en: Record<string, string>;
+//# sourceMappingURL=messages.d.ts.map

package/lib/types/client/seam.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Structural view of the client seams this bundle consumes: the sidebar's global panel row, the
+ * main-column body it addresses, the slot registry and the locale seat.
+ *
+ * The package ships outside the platform repository, so it DECLARES the seams it uses instead of
+ * importing another plugin's values (forbidden by the client bundle purity rule) or its types
+ * (which would drag platform client sources in). The shapes below are the shell's contract:
+ * `sidebar.panellist` takes `id`/`order`/`label` and owns the button and the layout, while the body
+ * is the root layout's keyed `main` slot dispatched by that SAME id.
+ * @module @lmzhen/dsh-evolution-skill-health/client
+ */
+import type { ReactNode } from 'react';
+/** The panel id. The row and the `main` body MUST share it: the sidebar resolves the body by it. */
+export declare const PANEL_ID = "skill-health";
+/** Row order inside the global panel list: beside the skill-history row (35), after it. */
+export declare const PANEL_ORDER = 40;
+/** Registration options for the global panel row (the sidebar's own shape). */
+export interface PanelRowOptions {
+    name: 'sidebar.panellist';
+    id: string;
+    order: number;
+    /** Lazy label: the sidebar re-reads it on every projection, so the locale can change underneath. */
+    label: () => string;
+}
+/** Registration options for the main-column body: a keyed slot dispatched by sidebar entry id. */
+export interface PanelBodyOptions {
+    name: 'main';
+    key: string;
+    /** The face handed to the component: plain data and callbacks, never a service. */
+    inject: () => unknown;
+}
+/** The locale seat: register this bundle's namespace, bind a translator. */
+export interface LocaleSeat {
+    register(namespace: string, dictionaries: {
+        zh: Record<string, string>;
+        en: Record<string, string>;
+    }): () => void;
+    bind(namespace: string): (key: string) => string;
+}
+/** The slot registry: a generator body may register (and is disposed when it unmounts). */
+export interface SlotsSeat {
+    inject(name: string, body: () => Generator<() => void, void, void>): void;
+    register(options: PanelRowOptions | PanelBodyOptions, component: (props: unknown) => ReactNode): () => void;
+}
+/** Everything this bundle asks the shell for. */
+export interface ClientSeam {
+    slots: SlotsSeat;
+    locale: LocaleSeat;
+}
+//# sourceMappingURL=seam.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Host half: ONE read-only route, mounted when the profile gives this row a web server.
+ *
+ * **Why `ctx.inject` and not `ctx.get`**: profile rows apply in file order, so at this row's apply
+ * time the web server may not exist yet — a `ctx.get('webServer')` of undefined is a TIMING fact,
+ * not a verdict, and acting on it leaves the route unregistered while the panel renders and every
+ * call answers 404. Waiting on the service mounts the route whenever it arrives, and a profile that
+ * never gets one simply never runs this callback — inert, never pending.
+ * @module @lmzhen/dsh-evolution-skill-health
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** No required services: the web server is WAITED ON below, not demanded here. */
+export declare const inject: string[];
+/**
+ * Mount the route as ONE effect (disposers run on unload and on HMR).
+ * @param ctx - the host context; the web server and curator arrive through it.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/routes.d.ts

@@ -0,0 +1,58 @@
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+/**
+ * The panel's ONE read-only route: the health rows the browser half renders.
+ *
+ * Read-only by construction: it never writes a skill, a marker or a config. It also carries the
+ * house rule down to the client — a rule whose threshold is NOT calibrated yet is reported with
+ * `countIsMeaningful: false`, so the panel can name it without printing a number we do not have.
+ * @module @lmzhen/dsh-evolution-skill-health
+ */
+/** Where the panel asks for its rows. */
+export declare const ROUTES: {
+    readonly rows: "/api/dsh-evolution/skill-health/rows";
+};
+/** Rules whose threshold is not calibrated yet: named on screen, never counted. */
+export declare const UNCALIBRATED_RULES: readonly string[];
+/** One finding as the client sees it. `line` is null when the position cannot be named. */
+export interface RouteFinding {
+    rule: string;
+    count: number;
+    line: string | null;
+    countIsMeaningful: boolean;
+}
+/** One row as the client sees it. `readable: false` becomes its own verdict, never `ok`. */
+export interface RouteRow {
+    name: string;
+    verdict: string;
+    findings: RouteFinding[];
+}
+/**
+ * Project the curator's health view into what the panel renders.
+ * @param rows - `{ name, verdict, dims, findings }` per skill, as `healthView()` returns them.
+ * @returns the same rows, with unreadable skills kept apart and uncalibrated rules uncounted.
+ */
+export declare function toRouteRows(rows: ReadonlyArray<{
+    name: string;
+    verdict: string;
+    findings: ReadonlyArray<{
+        rule: string;
+        count: number;
+        line?: string | null;
+    }>;
+    dims?: {
+        readable?: boolean;
+    } | null;
+}>): RouteRow[];
+/**
+ * Build the panel's routes, in the platform shape: `{ path, handler(req, res) }` — the same objects
+ * `ctx.webServer.register` takes for every other row in this family.
+ * @param deps - a getter for the curator service (absent until the profile mounts it).
+ * @returns one GET route; with no curator it answers an EMPTY row list plus `truncated: true`, which
+ *   the panel shows as "cannot decide right now" rather than as a pass.
+ */
+export declare function makeSkillHealthRoutes(deps: {
+    getCurator: () => {
+        healthView?: () => Promise<unknown>;
+    } | undefined;
+}): WebRoute[];
+//# sourceMappingURL=routes.d.ts.map

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@lmzhen/dsh-evolution-skill-health",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Web surface for skill health: the sidebar panel that shows what the linter found (community build)",
+  "version": "0.25.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmzhen/dsh-evolution.git",
+    "directory": "packages/evolution-skill-health"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
+    "react": "^18.2.0",
+    "@lmzhen/dsh-evolution-curator": "^0.25.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.1",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@lmzhen/dsh-evolution-curator": "^0.25.0"
+  }
+}