dsh-composition-doctor 0.1.0 → 0.1.3

package/README.md

@@ -1,63 +1,59 @@
 # dsh-composition-doctor
 
-DeepSeek Harness (DSH) 的本地组合与升级预检插件。它只读取用户明确指定的 profile 元数据，输出有证据的 Cordis/插件组合诊断，并在独立临时目录中演练升级；不会修改真实 profile、安装或卸载插件，也不会扩大权限。
+[![npm version](https://img.shields.io/npm/v/dsh-composition-doctor)](https://www.npmjs.com/package/dsh-composition-doctor)
+[![CI](https://github.com/lemonxiny55/dsh-composition-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/lemonxiny55/dsh-composition-doctor/actions)
 
-## 中文
+English | [中文](README.zh.md)
 
-### 功能
+Composition and upgrade preflight doctor for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`). It reads an explicitly selected profile and explains observable Cordis/plugin composition risks with concrete evidence. It never edits a real profile or silently changes permissions.
 
-- `scan`：分析显式 profile 的 composition，输出 JSON/Markdown。
-- `snapshot`：生成脱敏、可比较的 profile 快照和 lockfile 哈希。
-- `diff`：比较两个快照，识别插件升降级、rows、hooks、UI、peer/platform 变化。
-- `preflight`：在 OS 临时目录中进行离线解析和最小 smoke test；没有 `--allow-build` 时只输出构建计划。
-- DSH Settings 页面：只读显示最近报告、冲突关系和本地导出按钮。
+## What the model gets
 
-### 安装与卸载
+| Command | Purpose |
+|---|---|
+| `dsh-doctor scan` | Detect duplicate Cordis rows, hook-order risks, UI slot/route ownership conflicts, bundle overrides, peer/platform mismatches, and profile drift. |
+| `dsh-doctor snapshot` | Create a redacted, comparable profile snapshot with lockfile hashes. |
+| `dsh-doctor diff` | Summarize added/removed/upgraded plugins, rows, hooks, UI claims, peers, and platforms. |
+| `dsh-doctor preflight` | Rehearse a target DSH upgrade in an isolated temporary profile. |
 
-```powershell
-pnpm install
-pnpm build
-dsh plugin --profile <profile> add C:\path\to\dsh-composition-doctor
-dsh plugin --profile <profile> remove dsh-composition-doctor
-```
+The Web Settings page is display/export only: it reads the latest local report, shows a conflict graph, and exports JSON/Markdown. It has no repair, install, or uninstall action.
 
-命令行也可直接运行 `node dist/cli/main.js`（或 `pnpm dsh-doctor`）。
+## Reports and evidence boundaries
 
-### 使用
+`scan --output <dir>` writes only to the requested directory. To make the same report visible to the read-only Settings page, opt in explicitly: `--publish` copies it to the default plugin directory `.dsh-composition-doctor/reports`, while `--report-dir <dir>` publishes to a configured plugin directory. Use `--format both` so the Web route has `report.json` and Markdown remains exportable. Do not use a profile directory, `.env` location, or any directory containing keys, tokens, or other secrets as a report directory.
 
-```powershell
-dsh-doctor scan --profile .\test\fixtures\healthy --format both --output .\reports\healthy
-dsh-doctor snapshot --profile .\test\fixtures\healthy --output .\reports\before.json
-dsh-doctor diff --before .\reports\before.json --after .\reports\after.json --format both
-dsh-doctor preflight --profile .\test\fixtures\preflight-real-profile --target-dsh 0.1.0-rc.6 --candidate example-plugin@2.0.0
-```
+Reports declare `evidenceMode`: `static` means allow-listed root YAML/manifest metadata only; `resolved` requires an injected public runtime provider; `mixed` is reserved for an adapter that supplies both. Static findings and the bounded metadata coverage are not proof of the final runtime composition. This release has no stable public DSH runtime provider bundled.
 
-`--online` 只记录用户明确选择在线适配器的意图；当前实现仍不调用网络。`--allow-build` 是显式闸门，当前版本没有第三方构建 runner，因此不会执行生命周期脚本。
+`preflight --candidate package@version` inserts a validated exact reference into an isolated temporary `package.json` and includes that declared metadata in static analysis. It never downloads, installs, loads, or runs candidate lifecycle scripts; peer/platform facts inside an uninstalled candidate and runtime compatibility remain unverified. `--allow-build` is only a recorded future runner gate and still executes no third-party script.
 
-### 输出示例
+## Install
 
-```text
-warning  runtime-composition-unavailable
-  evidence: cordis.yml (static)
-  explanation: 未注入公开的 resolved-composition provider，静态 YAML 不能证明运行时加载结果。
-  remediation: 在隔离 fixture 中提供公开 provider 后重跑。
+```powershell
+npm install -g dsh-composition-doctor
+npx @deepseek-ai/dsh plugin --profile web add dsh-composition-doctor
 ```
 
-完整示例见 [`docs/examples/scan-report.md`](docs/examples/scan-report.md)。
+Restart the Web UI (`npx @deepseek-ai/dsh web`) after changing a profile. The CLI can also run from a checkout with `node dist/cli/main.js`.
 
-### 权限与隐私边界
+## Example
 
-默认只读，只读取显式 profile 根目录的 `cordis.yml`、`cordis.patch.yml`、`package.json` 和 lockfile 元数据，并拒绝符号链接。不会读取 `.env`、密钥、token、环境变量值、会话正文或工作区文件内容，不联网，不安装/卸载/迁移，不切换权限模式。快照递归脱敏敏感字段并只保留结构摘要与 SHA-256。工具不提供“安全评分”，也不声称插件本身安全。
+```powershell
+dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile --publish
+dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\archive --report-dir C:\safe\doctor-reports
+dsh-doctor snapshot --profile C:\path\to\profile --output .\reports\before.json
+dsh-doctor diff --before .\reports\before.json --after .\reports\after.json --format both
+dsh-doctor preflight --profile C:\path\to\profile --target-dsh 0.1.0-rc.6
+```
 
-### 支持范围与限制
+Each finding is `info`, `warning`, or `error` and includes evidence, explanation, and the smallest remediation. Missing runtime evidence is reported as a warning, never as a confirmed failure.
 
-当前验证过的开发预览范围：DSH `>=0.1.0-rc.5 <0.2.0`、Cordis `>=4 <5`、Node `>=20`，Windows 优先且可在 macOS/Linux 使用。DSH 尚未公开稳定的 resolved composition introspection API；未注入 provider 时结果明确标记为 static，不能证明启动成功或失败。Settings 页面依赖公开 `settings.plugins.tab` slot，不使用私有图标或 loader API。
+## Safety and privacy
 
-## English
+Default operations are read-only or isolated under the OS temporary directory. The plugin does not modify profiles, install/remove plugins, migrate configuration, escalate permissions, or perform network I/O by default. It never reads `.env`, keys, tokens, environment values, session bodies, or workspace file contents.
 
-`dsh-composition-doctor` is a local, read-only composition and upgrade preflight plugin for DeepSeek Harness. It analyses an explicitly selected profile, reports evidence-backed Cordis and plugin risks, snapshots redacted metadata, diffs snapshots, and rehearses upgrades in an isolated temporary directory. It never edits a real profile, installs or removes plugins, changes permissions, reads `.env`/keys/tokens/session/workspace contents, or performs network I/O by default. Findings are `info`, `warning`, or `error`; incomplete evidence is a warning, not a confirmed failure.
+## Support and limitations
 
-Commands are `dsh-doctor scan`, `snapshot`, `diff`, and `preflight`; invocation examples are above. The Web Settings section is display/export only. Verified preview range: DSH `>=0.1.0-rc.5 <0.2.0`, Cordis `>=4 <5`, Node `>=20`. Runtime composition introspection is an injected public-provider boundary; static findings are labelled accordingly. See [`docs/compatibility.md`](docs/compatibility.md) and [`docs/examples/scan-report.md`](docs/examples/scan-report.md).
+Verified preview range: DSH `>=0.1.0-rc.5 <0.2.0`, Cordis `>=4 <5`, Node.js `>=20`; Windows is first-class and macOS/Linux are supported. DSH has not yet exposed a stable resolved-composition introspection API, so static findings are explicitly labelled when no public provider is available.
 
 ## Development
 
@@ -67,4 +63,4 @@ pnpm typecheck
 pnpm build
 ```
 
-Fixtures under `test/fixtures` cover healthy, duplicate row id, hook order, UI conflict, peer mismatch, redaction, and preflight isolation cases.
+See [`README.zh.md`](README.zh.md), [`docs/compatibility.md`](docs/compatibility.md), and [`docs/examples/scan-report.md`](docs/examples/scan-report.md). MIT licensed.

package/README.zh.md

@@ -0,0 +1,36 @@
+# dsh-composition-doctor（中文）
+
+[English](README.md) | 中文
+
+面向 DeepSeek Harness（DSH）的本地只读组合与升级预检插件。它读取明确指定的 profile，分析 Cordis/plugin 组合风险，生成脱敏快照，比较升级差异，并在独立临时目录中演练升级。
+
+## 功能
+
+| 命令 | 作用 |
+|---|---|
+| `dsh-doctor scan` | 检测重复 row、hook 顺序风险、UI slot/route 冲突、bundle 覆盖、peer/platform 不匹配和 profile 漂移。 |
+| `dsh-doctor snapshot` | 生成脱敏、可比较的 profile 快照和 lockfile 哈希。 |
+| `dsh-doctor diff` | 比较插件、rows、hooks、UI、peer 和平台变化。 |
+| `dsh-doctor preflight` | 在独立临时目录预演目标 DSH 升级。 |
+
+Web Settings 只读显示最近报告、冲突图并导出 JSON/Markdown，不提供修复、安装或卸载操作。
+
+## 报告与证据边界
+
+`scan --output <目录>` 只写入该显式目录。要让只读 Settings 页面看到同一份报告，必须显式加 `--publish`，它会发布到插件默认目录 `.dsh-composition-doctor/reports`；或者用 `--report-dir <目录>` 发布到配置的目录。请使用 `--format both`，这样 Web route 可读取 `report.json`，同时保留 Markdown 导出。报告目录不得是 profile、`.env` 所在目录，或任何包含密钥、token 等敏感信息的目录。
+
+报告的 `evidenceMode` 表示证据来源：`static` 仅为允许列表中的根级 YAML/manifest 元数据；`resolved` 必须来自注入的公开 runtime provider；`mixed` 留给同时具有两类来源的适配器。静态发现和有限的 metadata coverage 不是最终 runtime composition 的证明；当前版本未内置稳定公开的 DSH runtime provider。
+
+`preflight --candidate package@version` 会将合法的精确引用放入隔离临时 `package.json`，使其声明元数据参与静态分析。它不会下载、安装、加载候选包，也不会执行第三方生命周期脚本；未安装候选包内部的 peer/platform 元数据与 runtime 兼容性仍未验证。`--allow-build` 目前仅记录未来 runner 的显式门槛，仍不会执行任何第三方脚本。
+
+## 安装与使用
+
+```powershell
+npm install -g dsh-composition-doctor
+npx @deepseek-ai/dsh plugin --profile web add dsh-composition-doctor
+dsh-doctor scan --profile C:\path\to\profile --format both --output .\reports\profile --publish
+```
+
+默认操作只读或写入操作系统临时目录，不修改真实 profile，不扩大权限，不默认联网，不读取 `.env`、密钥、token、环境变量值、会话正文或工作区文件内容。证据不足时只报告 warning。
+
+已验证范围：DSH `>=0.1.0-rc.5 <0.2.0`、Cordis `>=4 <5`、Node.js `>=20`；Windows 优先，同时支持 macOS/Linux。

package/dist/cli/main.js

@@ -1,6 +1,6 @@
 import { fileURLToPath } from 'node:url';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { resolveComposition } from '../core/composition-adapter.js';
 import { diffSnapshots, renderSnapshotDiffMarkdown } from '../core/diff.js';
 import { readProfile } from '../core/profile-reader.js';
@@ -8,6 +8,7 @@ import { createSnapshot } from '../core/snapshot.js';
 import { analyseComposition } from '../core/rules.js';
 import { renderJson } from '../reports/json.js';
 import { renderMarkdown } from '../reports/markdown.js';
+import { resolveReportDirectory } from '../reports/location.js';
 import { runPreflight } from '../core/preflight.js';
 const usage = 'Usage: dsh-doctor <scan | snapshot | diff | preflight>';
 const commands = new Set(['scan', 'snapshot', 'diff', 'preflight']);
@@ -30,6 +31,8 @@ function invalid(io, message) {
 async function scan(argv, io) {
     const profile = option(argv, '--profile');
     const output = option(argv, '--output');
+    const configuredReportDir = option(argv, '--report-dir');
+    const publish = argv.includes('--publish') || configuredReportDir !== undefined;
     const format = option(argv, '--format') ?? 'json';
     if (profile === undefined || output === undefined)
         return invalid(io, 'scan requires --profile and --output');
@@ -37,12 +40,17 @@ async function scan(argv, io) {
         return invalid(io, '--format must be json, markdown, or both');
     const report = analyseComposition(await resolveComposition(await readProfile({ profileDir: resolve(profile) })));
     const destination = resolve(output);
-    await mkdir(destination, { recursive: true });
-    if (format === 'json' || format === 'both')
-        await writeFile(resolve(destination, 'report.json'), renderJson(report), 'utf8');
-    if (format === 'markdown' || format === 'both')
-        await writeFile(resolve(destination, 'report.md'), renderMarkdown(report), 'utf8');
+    const destinations = [destination, ...(publish ? [resolveReportDirectory(configuredReportDir)] : [])];
+    for (const directory of destinations) {
+        await mkdir(directory, { recursive: true });
+        if (format === 'json' || format === 'both')
+            await writeFile(resolve(directory, 'report.json'), renderJson(report), 'utf8');
+        if (format === 'markdown' || format === 'both')
+            await writeFile(resolve(directory, 'report.md'), renderMarkdown(report), 'utf8');
+    }
     io.write(`Wrote reports to ${destination}`);
+    if (publish)
+        io.write(`Published reports to ${destinations[1]}`);
     return 0;
 }
 async function snapshot(argv, io) {
@@ -51,6 +59,7 @@ async function snapshot(argv, io) {
     if (profile === undefined || output === undefined)
         return invalid(io, 'snapshot requires --profile and --output');
     const destination = resolve(output);
+    await mkdir(dirname(destination), { recursive: true });
     await writeFile(destination, `${JSON.stringify(await createSnapshot(await readProfile({ profileDir: resolve(profile) })), null, 2)}\n`, 'utf8');
     io.write(`Wrote snapshot to ${destination}`);
     return 0;
@@ -96,7 +105,7 @@ async function preflight(argv, io) {
         io.write(rendered);
     else {
         const destination = resolve(output);
-        await mkdir(resolve(destination, '..'), { recursive: true });
+        await mkdir(dirname(destination), { recursive: true });
         await writeFile(destination, rendered, 'utf8');
         io.write(`Wrote preflight report to ${destination}`);
     }

package/dist/client/index.js

@@ -1,9 +1,10 @@
-import { createReportView } from './report-view.js';
+import { createElement } from 'react';
+import { ReportView } from './report-view.js';
 export const name = 'dsh-composition-doctor';
 export const registration = Object.freeze({
     id: name,
     actions: ['export-json', 'export-markdown'],
-    component: () => createReportView()
+    component: () => createElement(ReportView, { translate: (key) => key })
 });
 export const apply = Object.assign((ctx) => {
     const messages = {
@@ -15,7 +16,7 @@ export const apply = Object.assign((ctx) => {
     const disposeSlot = ctx.slots.inject('settings.plugins.tab', () => ctx.slots.register({
         name: 'settings.plugins.tab', id: registration.id, order: 70,
         locale: 'dshCompositionDoctor', label: () => t('title')
-    }, () => createReportView(undefined, t)));
+    }, () => createElement(ReportView, { translate: t })));
     return () => {
         if (typeof disposeSlot === 'function')
             disposeSlot();

package/dist/client/report-view.js

@@ -1,5 +1,7 @@
+import { createElement, useEffect, useRef } from 'react';
 import { renderMarkdown } from '../reports/markdown.js';
 export const clientReportPath = '/dsh-composition-doctor/reports/latest';
+export const downloadRevokeDelayMs = 1000;
 export function buildConflictGraph(report) {
     const nodes = new Map();
     const edges = [];
@@ -47,12 +49,37 @@ async function fetchReport(fetcher = globalThis.fetch) {
         throw new Error('The latest report has an unsupported schema.');
     return value;
 }
-function download(document, content, filename, mime) {
+const browserDownloadHooks = {
+    createObjectURL: (blob) => URL.createObjectURL(blob),
+    revokeObjectURL: (url) => URL.revokeObjectURL(url),
+    schedule: (callback, delay) => globalThis.setTimeout(callback, delay)
+};
+/** Create a local browser download without sending report data anywhere. */
+export function download(document, content, filename, mime, hooks = browserDownloadHooks) {
+    const blob = new Blob([content], { type: mime });
     const link = document.createElement('a');
-    link.href = URL.createObjectURL(new Blob([content], { type: mime }));
+    const objectUrl = hooks.createObjectURL(blob);
+    link.hidden = true;
+    link.href = objectUrl;
     link.download = filename;
-    link.click();
-    URL.revokeObjectURL(link.href);
+    document.body.append(link);
+    try {
+        link.click();
+    }
+    finally {
+        link.remove();
+        hooks.schedule(() => hooks.revokeObjectURL(objectUrl), downloadRevokeDelayMs);
+    }
+}
+export async function exportReport(document, format, dependencies = {}) {
+    const report = await fetchReport(dependencies.fetcher);
+    if (format === 'json') {
+        ;
+        (dependencies.download ?? download)(document, `${JSON.stringify(report, null, 2)}\n`, 'dsh-composition-doctor-report.json', 'application/json');
+        return;
+    }
+    ;
+    (dependencies.download ?? download)(document, renderMarkdown(report), 'dsh-composition-doctor-report.md', 'text/markdown');
 }
 /**
  * Browser-native settings section. It only performs a GET and offers local
@@ -60,7 +87,7 @@ function download(document, content, filename, mime) {
  */
 export function createReportView(document = globalThis.document, translate = (key) => ({
     title: 'DSH Composition Doctor', exportJson: 'Export JSON', exportMarkdown: 'Export Markdown', loading: 'Loading the latest local report…', unavailable: 'The latest report is unavailable.'
-}[key] ?? key)) {
+}[key] ?? key), dependencies = {}) {
     const root = document.createElement('section');
     root.dataset.plugin = nameForDom;
     root.setAttribute('aria-labelledby', 'dsh-composition-doctor-title');
@@ -72,21 +99,52 @@ export function createReportView(document = globalThis.document, translate = (ke
     status.textContent = translate('loading');
     root.append(status);
     const actions = document.createElement('p');
-    actions.append(button(document, translate('exportJson'), () => { void fetchReport().then((report) => download(document, `${JSON.stringify(report, null, 2)}\n`, 'dsh-composition-doctor-report.json', 'application/json')).catch(() => undefined); }), text(document, ' '), button(document, translate('exportMarkdown'), () => { void fetchReport().then((report) => download(document, renderMarkdown(report), 'dsh-composition-doctor-report.md', 'text/markdown')).catch(() => undefined); }));
+    actions.append(button(document, translate('exportJson'), () => { void exportReport(document, 'json', dependencies).catch(() => undefined); }), text(document, ' '), button(document, translate('exportMarkdown'), () => { void exportReport(document, 'markdown', dependencies).catch(() => undefined); }));
     root.append(actions);
     void fetchReport().then((report) => {
         const model = toReportViewModel(report);
-        status.textContent = `Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info. Conflict graph: ${model.graph.nodes.length} evidence nodes.`;
+        status.textContent = `Generated: ${report.generatedAt}. Profile: ${report.profileDir}. Evidence mode: ${report.evidenceMode}. Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info.`;
         const list = document.createElement('ul');
         for (const diagnostic of report.diagnostics) {
             const item = document.createElement('li');
-            item.textContent = `[${diagnostic.severity}] ${diagnostic.title}`;
+            const details = document.createElement('details');
+            const summary = document.createElement('summary');
+            summary.textContent = `[${diagnostic.severity}] ${diagnostic.title}`;
+            details.append(summary);
+            const explanation = document.createElement('p');
+            explanation.textContent = diagnostic.explanation;
+            const evidence = document.createElement('pre');
+            evidence.textContent = diagnostic.evidence.map((entry) => `${entry.source}: ${entry.detail}`).join('\n') || 'No concrete evidence.';
+            const remediation = document.createElement('p');
+            remediation.textContent = `Remediation: ${diagnostic.remediation}`;
+            details.append(explanation, evidence, remediation);
+            item.append(details);
             list.append(item);
         }
         root.append(list);
-    }).catch((error) => {
-        status.textContent = error instanceof Error ? error.message : translate('unavailable');
+    }).catch(() => {
+        status.textContent = translate('unavailable');
     });
     return root;
 }
+/**
+ * DSH settings slots are rendered by React. Keep the browser-native report
+ * view as the implementation detail, but mount it through a React component
+ * rather than returning an HTMLElement directly to the slot renderer.
+ */
+export function ReportView({ translate }) {
+    const host = useRef(null);
+    useEffect(() => {
+        const container = host.current;
+        if (container === null)
+            return;
+        const view = createReportView(globalThis.document, translate);
+        container.replaceChildren(view);
+        return () => {
+            view.remove();
+            container.replaceChildren();
+        };
+    }, [translate]);
+    return createElement('div', { className: 'dsh-composition-doctor-report-view', ref: host });
+}
 const nameForDom = 'dsh-composition-doctor';

package/dist/client.js

@@ -32,6 +32,10 @@ window.__ModuleLoader__.load({
 		  registration: () => registration
 		});
 		module.exports = __toCommonJS(index_exports);
+		var import_react2 = require("react");
+		
+		// src/client/report-view.ts
+		var import_react = require("react");
 		
 		// src/reports/markdown.ts
 		function formatEvidence(item) {
@@ -53,6 +57,9 @@ window.__ModuleLoader__.load({
 		function renderMarkdown(report) {
 		  const summary = ["error", "warning", "info"].map((severity) => `${severity}: ${report.diagnostics.filter((item) => item.severity === severity).length}`).join(", ");
 		  const body = report.diagnostics.length === 0 ? "No diagnostics were produced." : report.diagnostics.map(formatDiagnostic).join("\n\n");
+		  const coverage = report.metadataCoverage === void 0 ? "" : `
+		Metadata coverage: ${report.metadataCoverage.mode}; unscanned: ${report.metadataCoverage.unscannedSurfaces.join("; ")}
+		`;
 		  return `# DSH Composition Doctor Report
 		
 		Schema: ${report.schemaVersion}
@@ -61,6 +68,8 @@ window.__ModuleLoader__.load({
 		
 		Generated: ${report.generatedAt}
 		
+		Evidence mode: ${report.evidenceMode}
+		${coverage}
 		Summary: ${summary}
 		
 		${body}
@@ -69,6 +78,7 @@ window.__ModuleLoader__.load({
 		
 		// src/client/report-view.ts
 		var clientReportPath = "/dsh-composition-doctor/reports/latest";
+		var downloadRevokeDelayMs = 1e3;
 		function buildConflictGraph(report) {
 		  const nodes = /* @__PURE__ */ new Map();
 		  const edges = [];
@@ -112,12 +122,36 @@ window.__ModuleLoader__.load({
 		  if (!isReport(value)) throw new Error("The latest report has an unsupported schema.");
 		  return value;
 		}
-		function download(document, content, filename, mime) {
+		var browserDownloadHooks = {
+		  createObjectURL: (blob) => URL.createObjectURL(blob),
+		  revokeObjectURL: (url) => URL.revokeObjectURL(url),
+		  schedule: (callback, delay) => globalThis.setTimeout(callback, delay)
+		};
+		function download(document, content, filename, mime, hooks = browserDownloadHooks) {
+		  const blob = new Blob([content], { type: mime });
 		  const link = document.createElement("a");
-		  link.href = URL.createObjectURL(new Blob([content], { type: mime }));
+		  const objectUrl = hooks.createObjectURL(blob);
+		  link.hidden = true;
+		  link.href = objectUrl;
 		  link.download = filename;
-		  link.click();
-		  URL.revokeObjectURL(link.href);
+		  document.body.append(link);
+		  try {
+		    link.click();
+		  } finally {
+		    link.remove();
+		    hooks.schedule(() => hooks.revokeObjectURL(objectUrl), downloadRevokeDelayMs);
+		  }
+		}
+		async function exportReport(document, format, dependencies = {}) {
+		  const report = await fetchReport(dependencies.fetcher);
+		  if (format === "json") {
+		    ;
+		    (dependencies.download ?? download)(document, `${JSON.stringify(report, null, 2)}
+		`, "dsh-composition-doctor-report.json", "application/json");
+		    return;
+		  }
+		  ;
+		  (dependencies.download ?? download)(document, renderMarkdown(report), "dsh-composition-doctor-report.md", "text/markdown");
 		}
 		function createReportView(document = globalThis.document, translate = (key) => ({
 		  title: "DSH Composition Doctor",
@@ -125,7 +159,7 @@ window.__ModuleLoader__.load({
 		  exportMarkdown: "Export Markdown",
 		  loading: "Loading the latest local report\u2026",
 		  unavailable: "The latest report is unavailable."
-		})[key] ?? key) {
+		})[key] ?? key, dependencies = {}) {
 		  const root = document.createElement("section");
 		  root.dataset.plugin = nameForDom;
 		  root.setAttribute("aria-labelledby", "dsh-composition-doctor-title");
@@ -139,30 +173,54 @@ window.__ModuleLoader__.load({
 		  const actions = document.createElement("p");
 		  actions.append(
 		    button(document, translate("exportJson"), () => {
-		      void fetchReport().then((report) => download(document, `${JSON.stringify(report, null, 2)}
-		`, "dsh-composition-doctor-report.json", "application/json")).catch(() => void 0);
+		      void exportReport(document, "json", dependencies).catch(() => void 0);
 		    }),
 		    text(document, " "),
 		    button(document, translate("exportMarkdown"), () => {
-		      void fetchReport().then((report) => download(document, renderMarkdown(report), "dsh-composition-doctor-report.md", "text/markdown")).catch(() => void 0);
+		      void exportReport(document, "markdown", dependencies).catch(() => void 0);
 		    })
 		  );
 		  root.append(actions);
 		  void fetchReport().then((report) => {
 		    const model = toReportViewModel(report);
-		    status.textContent = `Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info. Conflict graph: ${model.graph.nodes.length} evidence nodes.`;
+		    status.textContent = `Generated: ${report.generatedAt}. Profile: ${report.profileDir}. Evidence mode: ${report.evidenceMode}. Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info.`;
 		    const list = document.createElement("ul");
 		    for (const diagnostic of report.diagnostics) {
 		      const item = document.createElement("li");
-		      item.textContent = `[${diagnostic.severity}] ${diagnostic.title}`;
+		      const details = document.createElement("details");
+		      const summary = document.createElement("summary");
+		      summary.textContent = `[${diagnostic.severity}] ${diagnostic.title}`;
+		      details.append(summary);
+		      const explanation = document.createElement("p");
+		      explanation.textContent = diagnostic.explanation;
+		      const evidence = document.createElement("pre");
+		      evidence.textContent = diagnostic.evidence.map((entry) => `${entry.source}: ${entry.detail}`).join("\n") || "No concrete evidence.";
+		      const remediation = document.createElement("p");
+		      remediation.textContent = `Remediation: ${diagnostic.remediation}`;
+		      details.append(explanation, evidence, remediation);
+		      item.append(details);
 		      list.append(item);
 		    }
 		    root.append(list);
-		  }).catch((error) => {
-		    status.textContent = error instanceof Error ? error.message : translate("unavailable");
+		  }).catch(() => {
+		    status.textContent = translate("unavailable");
 		  });
 		  return root;
 		}
+		function ReportView({ translate }) {
+		  const host = (0, import_react.useRef)(null);
+		  (0, import_react.useEffect)(() => {
+		    const container = host.current;
+		    if (container === null) return;
+		    const view = createReportView(globalThis.document, translate);
+		    container.replaceChildren(view);
+		    return () => {
+		      view.remove();
+		      container.replaceChildren();
+		    };
+		  }, [translate]);
+		  return (0, import_react.createElement)("div", { className: "dsh-composition-doctor-report-view", ref: host });
+		}
 		var nameForDom = "dsh-composition-doctor";
 		
 		// src/client/index.ts
@@ -170,7 +228,7 @@ window.__ModuleLoader__.load({
 		var registration = Object.freeze({
 		  id: name,
 		  actions: ["export-json", "export-markdown"],
-		  component: () => createReportView()
+		  component: () => (0, import_react2.createElement)(ReportView, { translate: (key) => key })
 		});
 		var apply = Object.assign(
 		  (ctx) => {
@@ -186,7 +244,7 @@ window.__ModuleLoader__.load({
 		      order: 70,
 		      locale: "dshCompositionDoctor",
 		      label: () => t("title")
-		    }, () => createReportView(void 0, t)));
+		    }, () => (0, import_react2.createElement)(ReportView, { translate: t })));
 		    return () => {
 		      if (typeof disposeSlot === "function") disposeSlot();
 		      if (typeof disposeLocale === "function") disposeLocale();

package/dist/core/composition-adapter.js

@@ -66,18 +66,49 @@ function staticRows(file) {
         return [row];
     });
 }
+function staticManifestFacts(file) {
+    if (file.relativePath !== 'package.json')
+        return {};
+    try {
+        const manifest = JSON.parse(file.text);
+        const dependencies = manifest.dependencies !== null && typeof manifest.dependencies === 'object' ? manifest.dependencies : {};
+        const bundles = Object.entries(dependencies)
+            .filter((entry) => typeof entry[1] === 'string')
+            .map(([name, version]) => ({ name, version, source: file.relativePath, evidenceKind: 'static' }));
+        const peer = manifest.peerDependencies !== null && typeof manifest.peerDependencies === 'object' ? manifest.peerDependencies : {};
+        const peerRequirements = typeof manifest.name === 'string' ? [{
+                packageName: manifest.name, source: file.relativePath, evidenceKind: 'static',
+                ...(typeof peer.dsh === 'string' ? { dsh: peer.dsh } : {}),
+                ...(typeof peer.cordis === 'string' ? { cordis: peer.cordis } : {}),
+                ...(typeof peer.node === 'string' ? { node: peer.node } : {})
+            }] : [];
+        const supported = Array.isArray(manifest.os) ? manifest.os.filter((value) => typeof value === 'string') : [];
+        const platforms = typeof manifest.name === 'string' && supported.length > 0 ? [{ packageName: manifest.name, source: file.relativePath, evidenceKind: 'static', supported }] : [];
+        return { bundles, peerRequirements, platforms };
+    }
+    catch {
+        return {};
+    }
+}
 export async function resolveComposition(input, provider) {
     if (provider) {
         const providedRows = await provider.resolve(input);
         return {
             profileDir: input.profileDir,
             rows: providedRows.map((row) => ({ ...cloneProviderValue(row), evidenceKind: 'resolved' })),
-            adapterDiagnostics: []
+            adapterDiagnostics: [], evidenceMode: 'resolved', metadataCoverage: input.metadataCoverage
         };
     }
     const rows = [];
+    const bundles = [];
+    const peerRequirements = [];
+    const platforms = [];
     const adapterDiagnostics = [runtimeUnavailableDiagnostic()];
     for (const file of input.files) {
+        const facts = staticManifestFacts(file);
+        bundles.push(...(facts.bundles ?? []));
+        peerRequirements.push(...(facts.peerRequirements ?? []));
+        platforms.push(...(facts.platforms ?? []));
         if (file.relativePath !== 'cordis.yml' && file.relativePath !== 'cordis.patch.yml')
             continue;
         try {
@@ -87,5 +118,5 @@ export async function resolveComposition(input, provider) {
             adapterDiagnostics.push(parseFailedDiagnostic(file, error));
         }
     }
-    return { profileDir: input.profileDir, rows, adapterDiagnostics };
+    return { profileDir: input.profileDir, rows, bundles, peerRequirements, platforms, adapterDiagnostics, evidenceMode: 'static', metadataCoverage: input.metadataCoverage };
 }

package/dist/core/diff.js

@@ -1,3 +1,4 @@
+import { satisfies as semverSatisfies } from 'semver';
 function formatChange(change) {
     const before = change.before === undefined ? '' : ` before=${JSON.stringify(change.before)}`;
     const after = change.after === undefined ? '' : ` after=${JSON.stringify(change.after)}`;
@@ -20,19 +21,22 @@ export function renderSnapshotDiffMarkdown(diff) {
 function compareVersions(left, right) {
     if (left === undefined || right === undefined)
         return undefined;
-    const parse = (value) => /^(\d+)\.(\d+)\.(\d+)/.exec(value)?.slice(1).map(Number);
-    const a = parse(left);
-    const b = parse(right);
-    if (a === undefined || b === undefined)
+    try {
+        if (semverSatisfies(left, `<${right}`, { includePrerelease: true }))
+            return -1;
+        if (semverSatisfies(left, `>${right}`, { includePrerelease: true }))
+            return 1;
+        if (semverSatisfies(left, `=${right}`, { includePrerelease: true }))
+            return 0;
         return undefined;
-    for (let index = 0; index < 3; index += 1)
-        if (a[index] !== b[index])
-            return a[index] < b[index] ? -1 : 1;
-    return 0;
+    }
+    catch {
+        return undefined;
+    }
 }
-function changes(before, after, key) {
-    const previous = new Map(before.map((item) => [key(item), item]));
-    const next = new Map(after.map((item) => [key(item), item]));
+function changes(before, after, beforeKey, afterKey = beforeKey) {
+    const previous = new Map(before.map((item) => [beforeKey(item), item]));
+    const next = new Map(after.map((item) => [afterKey(item), item]));
     const result = [];
     for (const itemKey of [...new Set([...previous.keys(), ...next.keys()])].sort()) {
         const left = previous.get(itemKey);
@@ -47,11 +51,13 @@ function changes(before, after, key) {
     return result;
 }
 export function diffSnapshots(before, after) {
-    const pluginChanges = changes(before.plugins, after.plugins, (item) => item.name).map((change) => {
+    const pluginKey = (profile, item) => `${profile.path}:${profile.packageName ?? ''}:${item.name}:${item.source}`;
+    const pluginChanges = changes(before.plugins, after.plugins, (item) => pluginKey(before.profile, item), (item) => pluginKey(after.profile, item)).map((change) => {
+        const name = change.before?.name ?? change.after?.name ?? change.key;
         if (change.kind !== 'changed')
-            return { ...change, name: change.key };
+            return { ...change, name };
         const comparison = compareVersions(change.before?.version, change.after?.version);
-        return { ...change, name: change.key, kind: comparison === undefined ? 'changed' : comparison < 0 ? 'upgraded' : comparison > 0 ? 'downgraded' : 'changed' };
+        return { ...change, name, kind: comparison === undefined ? 'changed' : comparison < 0 ? 'upgraded' : comparison > 0 ? 'downgraded' : 'changed' };
     });
     const rowChanges = changes(before.rows, after.rows, (item) => `${item.source}:${item.id ?? item.name ?? ''}`);
     const hookChanges = changes(before.hooks, after.hooks, (item) => `${item.source}:${item.hook}:${item.packageName ?? ''}`);

package/dist/core/preflight.js

@@ -30,6 +30,10 @@ function safeCandidate(value) {
     const version = value.slice(at + 1);
     return packageNamePattern.test(name) && versionPattern.test(version);
 }
+function candidateParts(value) {
+    const at = value.lastIndexOf('@');
+    return { name: value.slice(0, at), version: value.slice(at + 1) };
+}
 function safeMetadataText(relativePath, text) {
     try {
         if (relativePath === 'package.json') {
@@ -45,7 +49,8 @@ function safeMetadataText(relativePath, text) {
     }
     return undefined;
 }
-async function prepareIsolatedProfile(input, directory, evidenceItems) {
+async function prepareIsolatedProfile(input, directory, candidates, evidenceItems) {
+    let wroteManifest = false;
     for (const file of input.files) {
         if (lockFiles.has(file.relativePath)) {
             evidenceItems.push(evidence(file.relativePath, 'lockfile-not-copied', 'Lockfile content is excluded from the rehearsal directory; its source hash remains available in snapshots.'));
@@ -56,7 +61,28 @@ async function prepareIsolatedProfile(input, directory, evidenceItems) {
             evidenceItems.push(evidence(file.relativePath, 'metadata-not-copied', 'Metadata was not copied because it could not be safely parsed.'));
             continue;
         }
+        if (file.relativePath === 'package.json' && candidates.length > 0) {
+            const manifest = JSON.parse(safeText);
+            const dependencies = manifest.dependencies !== null && typeof manifest.dependencies === 'object' ? manifest.dependencies : {};
+            for (const candidate of candidates) {
+                const { name, version } = candidateParts(candidate);
+                dependencies[name] = version;
+            }
+            manifest.dependencies = dependencies;
+            await writeFile(join(directory, file.relativePath), `${JSON.stringify(manifest, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+            wroteManifest = true;
+            continue;
+        }
         await writeFile(join(directory, file.relativePath), safeText, { encoding: 'utf8', flag: 'wx' });
+        if (file.relativePath === 'package.json')
+            wroteManifest = true;
+    }
+    if (!wroteManifest && candidates.length > 0) {
+        const dependencies = Object.fromEntries(candidates.map((candidate) => {
+            const { name, version } = candidateParts(candidate);
+            return [name, version];
+        }));
+        await writeFile(join(directory, 'package.json'), `${JSON.stringify({ name: 'dsh-doctor-isolated-profile', private: true, dependencies }, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
     }
 }
 function runtimeForTarget(model, targetDsh) {
@@ -111,11 +137,19 @@ export async function runPreflight(options) {
         const candidates = options.candidates.filter(safeCandidate);
         evidenceItems.push(evidence(profileDir, 'target-dsh', `Rehearsal target is DSH ${options.targetDsh}.`));
         evidenceItems.push(evidence(profileDir, 'candidate-plugins', `${candidates.length} validated candidate plugin reference(s) supplied; values are not copied into the real profile.`));
+        for (const candidate of candidates) {
+            evidenceItems.push(evidence(profileDir, 'candidate-accepted', `${candidate} was accepted as an exact package@version reference.`));
+            evidenceItems.push(evidence(profileDir, 'candidate-metadata-inspected', `${candidate} was injected into the isolated package metadata and included in static manifest analysis.`));
+            evidenceItems.push(evidence(profileDir, 'candidate-package-not-installed', `${candidate} was not downloaded or installed.`));
+            evidenceItems.push(evidence(profileDir, 'candidate-runtime-unverified', `${candidate} was not loaded, so runtime compatibility is unverified.`, 'warning'));
+        }
+        if (candidates.length > 0)
+            extraWarning = true;
         evidenceItems.push(evidence(profileDir, 'network-policy', options.online ? 'Online mode was requested, but this adapter performs no network operation.' : 'Offline mode enforced; no network operation was attempted.'));
         if (options.online)
             extraWarning = true;
         tempDirectory = await mkdtemp(join(tmpdir(), 'dsh-doctor-'));
-        await prepareIsolatedProfile(input, tempDirectory, evidenceItems);
+        await prepareIsolatedProfile(input, tempDirectory, candidates, evidenceItems);
         evidenceItems.push(evidence(tempDirectory, 'isolated-profile', 'Only redacted, allow-listed composition metadata was copied into the temporary profile.'));
         try {
             const isolatedInput = await readProfile({ profileDir: tempDirectory });

package/dist/core/profile-reader.js

@@ -52,5 +52,13 @@ export async function readProfile({ profileDir }) {
             throw error;
         }
     }
-    return { profileDir: resolvedRoot, files };
+    return {
+        profileDir: resolvedRoot,
+        files,
+        metadataCoverage: {
+            mode: 'allow-listed-root-metadata',
+            scannedFiles: files.map((file) => file.relativePath).sort(),
+            unscannedSurfaces: ['nested plugin manifests and bundle metadata', 'environment files and values', 'private keys, tokens, sessions, and workspace source files']
+        }
+    };
 }

package/dist/core/rules.js

@@ -106,5 +106,7 @@ export function analyseComposition(model) {
         }
     }
     diagnostics.sort((left, right) => left.id.localeCompare(right.id) || left.title.localeCompare(right.title) || left.evidence[0]?.source.localeCompare(right.evidence[0]?.source ?? '') || 0);
-    return { schemaVersion: 1, generatedAt: new Date().toISOString(), profileDir: model.profileDir, diagnostics };
+    const evidenceMode = model.evidenceMode ?? 'static';
+    const unverifiedFindings = diagnostics.filter((item) => item.id === 'runtime-composition-unavailable' || item.evidence.some((entry) => entry.evidenceKind === 'static')).map((item) => item.id);
+    return { schemaVersion: 1, generatedAt: new Date().toISOString(), profileDir: model.profileDir, evidenceMode, ...(model.metadataCoverage === undefined ? {} : { metadataCoverage: model.metadataCoverage }), unverifiedFindings, diagnostics };
 }

package/dist/plugin/index.js

@@ -1,13 +1,14 @@
 import { lstat, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import z from '@deepseek-ai/schemastery';
+import { defaultReportDirectory, resolveReportDirectory } from '../reports/location.js';
 export const name = 'dsh-composition-doctor';
 /** Public Cordis service dependency supplied by dsh-host-webserver. */
 export const inject = ['webServer'];
-export const Config = z.object({ reportDir: z.string() });
+export const Config = z.object({ reportDir: z.string().default(defaultReportDirectory) });
 export const latestReportPath = '/dsh-composition-doctor/reports/latest';
 function reportDirectory(config) {
-    return resolve(config.reportDir ?? '.dsh-composition-doctor/reports');
+    return resolveReportDirectory(config.reportDir);
 }
 function send(response, status, body) {
     response.statusCode = status;

package/dist/reports/location.js

@@ -0,0 +1,9 @@
+import { resolve } from 'node:path';
+/**
+ * Relative to the DSH host process working directory. This directory is owned
+ * by the doctor plugin and is deliberately separate from a scanned profile.
+ */
+export const defaultReportDirectory = '.dsh-composition-doctor/reports';
+export function resolveReportDirectory(reportDir = defaultReportDirectory) {
+    return resolve(reportDir);
+}

package/dist/reports/markdown.js

@@ -10,5 +10,6 @@ function formatDiagnostic(item) {
 export function renderMarkdown(report) {
     const summary = ['error', 'warning', 'info'].map((severity) => `${severity}: ${report.diagnostics.filter((item) => item.severity === severity).length}`).join(', ');
     const body = report.diagnostics.length === 0 ? 'No diagnostics were produced.' : report.diagnostics.map(formatDiagnostic).join('\n\n');
-    return `# DSH Composition Doctor Report\n\nSchema: ${report.schemaVersion}\n\nProfile: \`${report.profileDir}\`\n\nGenerated: ${report.generatedAt}\n\nSummary: ${summary}\n\n${body}\n`;
+    const coverage = report.metadataCoverage === undefined ? '' : `\nMetadata coverage: ${report.metadataCoverage.mode}; unscanned: ${report.metadataCoverage.unscannedSurfaces.join('; ')}\n`;
+    return `# DSH Composition Doctor Report\n\nSchema: ${report.schemaVersion}\n\nProfile: \`${report.profileDir}\`\n\nGenerated: ${report.generatedAt}\n\nEvidence mode: ${report.evidenceMode}\n${coverage}\nSummary: ${summary}\n\n${body}\n`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-composition-doctor",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "private": false,
   "description": "Read-only DSH and Cordis composition diagnostics, snapshots, diffs, and isolated preflight.",
   "license": "MIT",
@@ -8,12 +8,14 @@
   "exports": {
     ".": "./dist/plugin/index.js",
     "./client": "./dist/client.js",
-    "./cli": "./dist/cli/main.js"
+    "./cli": "./dist/cli/main.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "cordis.patch.yml",
     "README.md",
+    "README.zh.md",
     "LICENSE"
   ],
   "dsh": {
@@ -37,7 +39,7 @@
   },
   "packageManager": "pnpm@10.17.1",
   "scripts": {
-    "test": "vitest run",
+    "test": "pnpm build && vitest run",
     "typecheck": "tsc --noEmit",
     "build": "tsc && node scripts/build-client.mjs",
     "dsh-doctor": "node dist/cli/main.js"