upstream-radar 0.26.0 → 0.27.0

package/README.md

@@ -193,7 +193,7 @@ This proof runs in CI on Node.js 22. See the executable [showcase contract](exam
 Before wiring a project into a compatibility gate, run the offline rule benchmark:
 
 ```bash
-pnpm dlx --package=upstream-radar@0.26.0 upstream-radar benchmark compatibility
+pnpm dlx --package=upstream-radar@0.27.0 upstream-radar benchmark compatibility
 ```
 
 It covers six contracts: a safe patch, a change that only needs project analysis, an incompatible DSH peer, a publisher-declared breaking release, a vulnerable candidate dependency, and an incomplete candidate graph. The command does not access the network, install a package, load a plugin, or start DSH. It checks the behavior of Radar's deterministic rules and the `breaking`/`any` gates; it is not a runtime compatibility proof.
@@ -206,7 +206,7 @@ When you have an exact plugin artifact and want to know whether one exact DSH re
 # Pack an exact npm release without running its lifecycle scripts.
 npm pack --ignore-scripts dsh-plugin@1.2.3
 
-pnpm dlx --package=upstream-radar@0.26.0 upstream-radar probe dsh-load \
+pnpm dlx --package=upstream-radar@0.27.0 upstream-radar probe dsh-load \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.6
 ```
@@ -232,7 +232,7 @@ It exercises a loadable bundle, a bundle patch DSH rejects, and a package that r
 To compare a plugin against more than one DSH release, use the matrix form:
 
 ```bash
-pnpm dlx --package=upstream-radar@0.26.0 upstream-radar probe dsh-matrix \
+pnpm dlx --package=upstream-radar@0.27.0 upstream-radar probe dsh-matrix \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.3 \
   --dsh-version 0.1.0-rc.6 \
@@ -243,12 +243,12 @@ The matrix runs versions one at a time in separate temporary profiles and evalua
 
 ## Run it in GitHub Actions
 
-If your team wants a scheduled CI gate before wiring a machine to a live DSH profile, commit the reviewed `upstream-radar.config.json` and copy [the example workflow](examples/github-actions/upstream-radar.yml). The reusable Action keeps the workflow to two meaningful steps:
+If your team wants a scheduled CI gate before wiring a machine to a live DSH profile, commit the reviewed `upstream-radar.config.json` and copy [the example workflow](examples/github-actions/upstream-radar.yml). The reusable Action keeps the workflow to two meaningful steps, with an optional third step for DSH load compatibility:
 
 ```yaml
 steps:
   - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-  - uses: MicroMilo/upstream-radar@v0.26.0
+  - uses: MicroMilo/upstream-radar@v0.27.0
     with:
       config: upstream-radar.config.json
       fail-on: high
@@ -256,16 +256,30 @@ steps:
       fail-on-compatibility: breaking
 ```
 
-The Action is a thin wrapper around `radar check --frozen --state :memory: --fail-on high --json`; when the optional compatibility input is enabled, it also passes `--fail-on-compatibility breaking` or `any`. `--frozen` is deliberate: it uses the graph in the reviewed config and does not try to read a developer's local DSH profile. Each run is independent, exits `2` when an active vulnerability or opted-in compatibility change meets its threshold, and exits `1` for an operational or source error. `breaking` catches confirmed or strong incompatibility signals; `any` catches every active compatibility event. The default is `never`, so vulnerability-only behavior stays unchanged. The Action does not deliver a DSH Agent task or modify a branch; the native DSH bundle remains the always-on analysis path. Pin the Action to a release tag such as `v0.26.0`, and pin the checkout Action in your workflow according to your repository's policy.
+The Action is a thin wrapper around `radar check --frozen --state :memory: --fail-on high --json`; when the optional compatibility input is enabled, it also passes `--fail-on-compatibility breaking` or `any`. `--frozen` is deliberate: it uses the graph in the reviewed config and does not try to read a developer's local DSH profile. Each run is independent, exits `2` when an active vulnerability or opted-in compatibility change meets its threshold, and exits `1` for an operational or source error. `breaking` catches confirmed or strong incompatibility signals; `any` catches every active compatibility event. The default is `never`, so vulnerability-only behavior stays unchanged. The Action does not deliver a DSH Agent task or modify a branch; the native DSH bundle remains the always-on analysis path. Pin the Action to a release tag such as `v0.27.0`, and pin the checkout Action in your workflow according to your repository's policy.
 
 The Action requires the caller to check out the repository first. It does not install the project's dependencies or run their lifecycle scripts; it only reads the committed graph and queries the configured upstream sources. For a fully explicit, lower-level invocation, the equivalent command is:
 
 ```bash
-pnpm dlx --package=upstream-radar@0.26.0 upstream-radar radar check \
+pnpm dlx --package=upstream-radar@0.27.0 upstream-radar radar check \
   ./upstream-radar.config.json --frozen --state :memory: --fail-on high \
   --fail-on-compatibility breaking --json
 ```
 
+To add the optional DSH load matrix for a published plugin, provide an exact npm package and at least two exact DSH versions:
+
+```yaml
+- uses: MicroMilo/upstream-radar@v0.27.0
+  id: radar
+  with:
+    config: upstream-radar.config.json
+    fail-on: high
+    probe-package: dsh-cloudflare-browser-run@0.1.1
+    probe-dsh-versions: 0.1.0-rc.3,0.1.0-rc.6
+```
+
+The Action packs the exact package with `--ignore-scripts`, runs `probe dsh-matrix`, exposes `probe-result`, and fails with the probe's exit code when the result is `incompatible` or `unknown`. This extra step downloads and loads the DSH bundle in temporary profiles; it is a compatibility signal, not a security sandbox or a capability test.
+
 For a runnable consumer example using the real [`dsh-cloudflare-browser-run@0.1.1`](examples/github-actions/consumer/upstream-radar.config.json) graph, see the [consumer smoke README](examples/github-actions/consumer/README.md) and its [copyable workflow](examples/github-actions/consumer/upstream-radar.yml).
 
 Run the same released Action locally from this repository with:
@@ -371,6 +385,7 @@ Advisories, release notes, links, package names, and repository strings remain u
 - automatic selection of the only DSH profile with third-party bundles, plus a network-free `radar status` snapshot;
 - commit-friendly `init` output that records the project workspace as `.` by default;
 - a reusable GitHub Action that turns the reviewed graph into a two-step, frozen CI gate;
+- an opt-in GitHub Action DSH load matrix for exact published plugin versions and exact DSH versions;
 - a real DSH plugin consumer smoke that runs the published Action against 18 exact package versions;
 - an actionable, network-free `radar status` summary with exact active paths, candidate signals, and next steps;
 - a network-free `doctor` command that checks local DSH registration, overlay/config alignment, state readability, and dependency coverage;

package/dist/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const TOOL_VERSION = "0.26.0";
+export declare const TOOL_VERSION = "0.27.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/src/version.js

@@ -1,2 +1,2 @@
-export const TOOL_VERSION = '0.26.0';
+export const TOOL_VERSION = '0.27.0';
 //# sourceMappingURL=version.js.map

package/docs/README.zh-CN.md

@@ -181,7 +181,7 @@ pnpm run try:dsh
 在把项目接入兼容性门禁前，可以先运行离线规则 benchmark：
 
 ```bash
-pnpm dlx --package=upstream-radar@0.26.0 upstream-radar benchmark compatibility
+pnpm dlx --package=upstream-radar@0.27.0 upstream-radar benchmark compatibility
 ```
 
 它覆盖六类契约：安全补丁、只需要项目分析的变化、不兼容的 DSH peer、发布者明确声明 breaking、候选传递依赖漏洞，以及候选依赖图不完整。这个命令不会联网、安装包、加载插件或启动 DSH；它验证的是 Radar 的确定性规则以及 `breaking`/`any` 门禁行为，不是运行时兼容性证明。
@@ -194,7 +194,7 @@ pnpm dlx --package=upstream-radar@0.26.0 upstream-radar benchmark compatibility
 # 打包精确版本，并明确不运行它的 lifecycle script。
 npm pack --ignore-scripts dsh-plugin@1.2.3
 
-pnpm dlx --package=upstream-radar@0.26.0 upstream-radar probe dsh-load \
+pnpm dlx --package=upstream-radar@0.27.0 upstream-radar probe dsh-load \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.6
 ```
@@ -220,7 +220,7 @@ pnpm run showcase:dsh-probe
 如果要比较多个 DSH 版本，可以使用矩阵入口：
 
 ```bash
-pnpm dlx --package=upstream-radar@0.26.0 upstream-radar probe dsh-matrix \
+pnpm dlx --package=upstream-radar@0.27.0 upstream-radar probe dsh-matrix \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.3 \
   --dsh-version 0.1.0-rc.6 \
@@ -233,12 +233,12 @@ JSON 结果结构见[矩阵结果 schema](../schemas/dsh-load-matrix.schema.json
 
 ## 在 GitHub Actions 中运行
 
-如果团队想先用定时 CI 检查，而不是马上在 runner 里安装 DSH，可以把审查过的 `upstream-radar.config.json` 提交到仓库，然后复制[示例 workflow](../examples/github-actions/upstream-radar.yml)。现在可以直接使用可复用的 GitHub Action，workflow 只需要两个关键步骤：
+如果团队想先用定时 CI 检查，而不是马上在 runner 里安装 DSH，可以把审查过的 `upstream-radar.config.json` 提交到仓库，然后复制[示例 workflow](../examples/github-actions/upstream-radar.yml)。现在可以直接使用可复用的 GitHub Action，workflow 只需要两个关键步骤；需要时再增加一个 DSH 加载兼容性步骤：
 
 ```yaml
 steps:
   - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-  - uses: MicroMilo/upstream-radar@v0.26.0
+  - uses: MicroMilo/upstream-radar@v0.27.0
     with:
       config: upstream-radar.config.json
       fail-on: high
@@ -246,16 +246,30 @@ steps:
       fail-on-compatibility: breaking
 ```
 
-这个 Action 只是 `radar check --frozen --state :memory: --fail-on high --fail-on-compatibility breaking --json` 的薄封装。`--frozen` 是有意的：它只使用配置文件里的依赖图，不会尝试读取 runner 上不存在的本地 DSH profile。每次运行彼此独立；发现达到阈值的漏洞或选择的兼容性变化时返回 `2`，运行或漏洞源出错时返回 `1`。`breaking` 只拦截有 confirmed/strong 信号的兼容性事件，`any` 会拦截所有活动兼容性事件，默认值是 `never`。这个入口不会投递 DSH Agent 任务，也不会修改分支；需要持续监控和项目级分析时，仍使用原生 DSH bundle。建议把 Action 固定到类似 `v0.26.0` 的发布标签，并根据团队策略固定 checkout Action。
+这个 Action 只是 `radar check --frozen --state :memory: --fail-on high --fail-on-compatibility breaking --json` 的薄封装。`--frozen` 是有意的：它只使用配置文件里的依赖图，不会尝试读取 runner 上不存在的本地 DSH profile。每次运行彼此独立；发现达到阈值的漏洞或选择的兼容性变化时返回 `2`，运行或漏洞源出错时返回 `1`。`breaking` 只拦截有 confirmed/strong 信号的兼容性事件，`any` 会拦截所有活动兼容性事件，默认值是 `never`。这个入口不会投递 DSH Agent 任务，也不会修改分支；需要持续监控和项目级分析时，仍使用原生 DSH bundle。建议把 Action 固定到类似 `v0.27.0` 的发布标签，并根据团队策略固定 checkout Action。
 
 调用方需要先 checkout 仓库。这个 Action 不会安装项目依赖，也不会执行项目的 lifecycle script；它只读取提交到仓库的依赖图并查询配置中的上游漏洞源。如果需要完全显式的底层命令，等价写法是：
 
 ```bash
-pnpm dlx --package=upstream-radar@0.26.0 upstream-radar radar check \
+pnpm dlx --package=upstream-radar@0.27.0 upstream-radar radar check \
   ./upstream-radar.config.json --frozen --state :memory: --fail-on high \
   --fail-on-compatibility breaking --json
 ```
 
+如果还要检查一个已发布插件能否跨多个 DSH 版本加载，可以增加三个 input：
+
+```yaml
+- uses: MicroMilo/upstream-radar@v0.27.0
+  id: radar
+  with:
+    config: upstream-radar.config.json
+    fail-on: high
+    probe-package: dsh-cloudflare-browser-run@0.1.1
+    probe-dsh-versions: 0.1.0-rc.3,0.1.0-rc.6
+```
+
+Action 会用 `--ignore-scripts` 打包精确 npm 版本，运行 `probe dsh-matrix`，并暴露 `probe-result`。如果结果是 `incompatible` 或 `unknown`，Action 会失败。这个步骤会下载并加载 DSH bundle 到临时 profile；它是兼容性信号，不是安全沙箱，也不是能力测试。
+
 如果想先跑一个真实消费者样例，可以参考使用真实 [`dsh-cloudflare-browser-run@0.1.1`](../examples/github-actions/consumer/upstream-radar.config.json) 依赖图的[consumer smoke 说明](../examples/github-actions/consumer/README.md)和[可复制 workflow](../examples/github-actions/consumer/upstream-radar.yml)。
 
 在本仓库中也可以直接运行同一个已发布 Action：
@@ -332,7 +346,7 @@ DSH Agent 收到的任务要求：只读分析、引用项目证据、保留不
 
 ## 当前能力与边界
 
-已经支持：DSH profile 实际安装树和 npm lock 依赖图、重复版本路径、未解析依赖的覆盖提示、OSV 精确版本匹配、恶意包记录、npm release 监听（只接受高于当前安装版本的候选；npm 的 `latest` 回退不会制造 breaking 告警；最新版本有确定性阻断时会检查历史候选的 OSV 状态和最早一小段传递依赖图，并筛出第一个没有确定性阻断且没有已知漏洞路径、值得交给 DSH 分析的候选；图不完整、图解析或 OSV 失败时不推荐候选）、公开 GitHub Release 说明、OSV 故障时保留已确认状态、连续失败后的 source-health DSH notice、持久事件、DSH 原生投递，以及 Node/peer/exports/入口/bundle/版本边界检查；还包括不联网的 `doctor` 接线检查、默认可提交的相对 workspace、把审查过的图接入 CI 的可复用 GitHub Action、可选的 breaking/any 兼容性门禁、离线的 `benchmark compatibility` 规则契约检查，以及基于真实 DSH 插件的 consumer smoke。
+已经支持：DSH profile 实际安装树和 npm lock 依赖图、重复版本路径、未解析依赖的覆盖提示、OSV 精确版本匹配、恶意包记录、npm release 监听（只接受高于当前安装版本的候选；npm 的 `latest` 回退不会制造 breaking 告警；最新版本有确定性阻断时会检查历史候选的 OSV 状态和最早一小段传递依赖图，并筛出第一个没有确定性阻断且没有已知漏洞路径、值得交给 DSH 分析的候选；图不完整、图解析或 OSV 失败时不推荐候选）、公开 GitHub Release 说明、OSV 故障时保留已确认状态、连续失败后的 source-health DSH notice、持久事件、DSH 原生投递，以及 Node/peer/exports/入口/bundle/版本边界检查；还包括不联网的 `doctor` 接线检查、默认可提交的相对 workspace、把审查过的图接入 CI 的可复用 GitHub Action、可选的 breaking/any 兼容性门禁、可选的 DSH 版本加载矩阵、离线的 `benchmark compatibility` 规则契约检查，以及基于真实 DSH 插件的 consumer smoke。
 
 此外支持一次性的 `probe dsh-load` 和有界的 `probe dsh-matrix`：在临时 DSH profile 中针对一个或多个精确 DSH 版本加载一个精确 tarball，并返回 `compatible`、`incompatible` 或 `unknown`。它是加载兼容性证据，不是安全准入，也不是插件能力 benchmark。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "upstream-radar",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Always-on dependency security monitoring for DeepSeek Harness (DSH) plugins: find exact installed or candidate transitive vulnerable paths and breaking updates, then route evidence to a DSH Agent.",
   "type": "module",
   "license": "Apache-2.0",