upstream-radar 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +62 -48
  2. package/README.zh-CN.md +59 -43
  3. package/dist/src/version.d.ts +1 -1
  4. package/dist/src/version.js +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <h1 align="center">Upstream Radar</h1>
9
9
 
10
- <p align="center"><strong>Dependency changes that wake your DSH Agent only when your project is actually affected.</strong></p>
10
+ <p align="center"><strong>Always-on vulnerability and breaking-change radar for DeepSeek Harness plugins.</strong></p>
11
11
 
12
12
  <p align="center">
13
13
  English · <a href="README.zh-CN.md">简体中文</a>
@@ -15,6 +15,7 @@
15
15
 
16
16
  <p align="center">
17
17
  <a href="https://www.npmjs.com/package/upstream-radar"><img alt="npm version" src="https://img.shields.io/npm/v/upstream-radar?style=flat-square&color=2563eb"></a>
18
+ <a href="https://github.com/MicroMilo/upstream-radar/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/MicroMilo/upstream-radar?style=flat-square&color=f59e0b"></a>
18
19
  <a href="https://github.com/MicroMilo/upstream-radar/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/MicroMilo/upstream-radar/ci.yml?branch=main&style=flat-square&label=CI"></a>
19
20
  <a href="examples/dsh/README.md"><img alt="Tested with DSH 0.1.0-rc.6" src="https://img.shields.io/badge/tested_with_DSH-0.1.0--rc.6-5b5bd6?style=flat-square"></a>
20
21
  <a href="https://github.com/MicroMilo/upstream-radar/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/MicroMilo/upstream-radar?style=flat-square"></a>
@@ -22,61 +23,55 @@
22
23
  </p>
23
24
 
24
25
  <p align="center">
25
- <a href="#run-the-proof">Run the proof</a> ·
26
+ <a href="#see-one-incident">See one incident</a> ·
26
27
  <a href="#install-in-dsh">Install in DSH</a> ·
28
+ <a href="#run-the-proof">Run the proof</a> ·
27
29
  <a href="#how-the-loop-works">How it works</a> ·
28
30
  <a href="ROADMAP.md">Roadmap</a>
29
31
  </p>
30
32
 
31
33
  ---
32
34
 
33
- A vulnerability feed can tell you that a package is affected. It usually cannot tell you which DSH plugin brought that exact version into your profile, whether the vulnerable path reaches your project, or whether the available upgrade breaks DSH on the way out.
34
-
35
- Upstream Radar closes that loop inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness):
35
+ A vulnerability feed stops at “package X is affected.” Upstream Radar keeps going: it identifies the exact installed dependency path, maintains one durable incident, and wakes a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Agent with the project evidence needed for a useful investigation.
36
36
 
37
- - **Exact path, not a package-name guess.** It preserves physical dependency nodes, duplicate versions, and the root-to-package path that actually matched.
38
- - **An incident, not alert spam.** It stores `new`, `updated`, and `resolved` state and keeps only the current task for each incident.
39
- - **Program facts before model judgment.** Version matching and compatibility boundaries stay deterministic; the DSH Agent investigates only project-specific reachability and migration impact.
40
-
41
- ## Run the proof
42
-
43
- Boot a real DSH `headless` profile with the packed Upstream Radar bundle installed:
44
-
45
- ```bash
46
- git clone https://github.com/MicroMilo/upstream-radar.git
47
- cd upstream-radar
48
- corepack enable
49
- pnpm install --frozen-lockfile
50
- pnpm run try:dsh
37
+ ```text
38
+ OSV advisory or npm release
39
+ -> exact installed plugin path
40
+ -> new / updated / resolved incident
41
+ -> project-specific DSH Agent analysis task
51
42
  ```
52
43
 
53
- No DeepSeek API key is required. The paid model endpoint is replaced by a deterministic local DeepSeek-compatible stub; the Cordis loader, DSH Agent, Session, persistence stack, bundle installation, and plugin delivery are real.
44
+ **No matching installed path means no Agent wake-up.** Version matching and compatibility facts are calculated by code; the model handles only repository-specific judgment.
54
45
 
55
- The command fails unless DSH proves all four facts:
46
+ ## See one incident
56
47
 
57
- ```json
58
- {
59
- "bundleInstalled": true,
60
- "radarTaskReachedModel": true,
61
- "pluginSourcePreserved": true,
62
- "pendingTasksAfterDelivery": 0
63
- }
64
- ```
48
+ If an advisory affects only one of two installed `parser` versions, Radar reports the path that actually matched:
65
49
 
66
- This proof runs in CI on Node.js 22. See the executable [showcase contract](examples/dsh/README.md) and its checked-in [result](examples/dsh/reports/headless-smoke.json).
50
+ ```text
51
+ [HIGH][NEW] Dependency vulnerability
52
+ Project: Payments API (payments-api)
53
+ Plugin: plugin@1.0.0
54
+ Affected: parser@2.9.0
55
+ Advisory: GHSA-demo-2026-parser / CVE-2026-1234
56
+ Paths:
57
+ plugin@1.0.0 -> logger@4.0.2 -> parser@2.9.0
58
+ Fixed versions: 3.0.0
59
+ Route: payments-platform via feishu:payments-security
60
+ ```
67
61
 
68
- To include a current OSV and npm poll before the DSH handoff:
62
+ That incident becomes a plugin-originated DSH notice. It is not copied into a generic chatbot prompt.
69
63
 
70
- ```bash
71
- pnpm run try:dsh:live
72
- ```
64
+ | Upstream signal | Radar proves deterministically | DSH Agent investigates |
65
+ | --- | --- | --- |
66
+ | Vulnerability or malicious package | affected `name@version`, every installed path, fixed versions, incident state | whether project code reaches it, attacker input can reach it, and the least disruptive fix |
67
+ | Candidate npm release | version boundary and Node.js, peer, export, entrypoint, bundle, and dependency changes | which APIs or Cordis configuration would break and what migration is appropriate |
73
68
 
74
69
  ## Install in DSH
75
70
 
76
71
  Upstream Radar is an npm-published DSH bundle, so no install-time build permission is required:
77
72
 
78
73
  ```bash
79
- dsh plugin --profile web add upstream-radar@0.4.0
74
+ dsh plugin --profile web add upstream-radar@latest
80
75
  ```
81
76
 
82
77
  Point the bundle at an explicit project inventory, choose a durable state file, then boot the profile:
@@ -92,6 +87,35 @@ dsh --profile web
92
87
 
93
88
  Start from [the example inventory](examples/radar/config.json). If `UPSTREAM_RADAR_CONFIG` is not set, the bundle stays dormant and performs no polling.
94
89
 
90
+ Once running, Radar polls OSV and npm, persists incident state before delivery, and submits only changed incidents to the first live root DSH Agent.
91
+
92
+ ## Run the proof
93
+
94
+ Boot a real DSH `headless` profile with the packed Upstream Radar bundle installed:
95
+
96
+ ```bash
97
+ git clone https://github.com/MicroMilo/upstream-radar.git
98
+ cd upstream-radar
99
+ corepack enable
100
+ pnpm install --frozen-lockfile
101
+ pnpm run try:dsh
102
+ ```
103
+
104
+ No DeepSeek API key is required. The paid model endpoint is replaced by a deterministic local DeepSeek-compatible stub; the Cordis loader, DSH Agent, Session, persistence stack, bundle installation, and plugin delivery are real.
105
+
106
+ The command fails unless DSH proves all four facts:
107
+
108
+ ```json
109
+ {
110
+ "bundleInstalled": true,
111
+ "radarTaskReachedModel": true,
112
+ "pluginSourcePreserved": true,
113
+ "pendingTasksAfterDelivery": 0
114
+ }
115
+ ```
116
+
117
+ This proof runs in CI on Node.js 22. See the executable [showcase contract](examples/dsh/README.md) and its checked-in [result](examples/dsh/reports/headless-smoke.json). Run `pnpm run try:dsh:live` to include a current OSV and npm poll before the DSH handoff.
118
+
95
119
  ## How the loop works
96
120
 
97
121
  1. Read the project inventory and exact installed npm graph.
@@ -114,7 +138,7 @@ The handoff uses `ctx.agents.roots()[0].followup(...)` with:
114
138
 
115
139
  It is a native DSH lifecycle integration—not a chat bridge or a remote-control bot.
116
140
 
117
- ## One vulnerable path, not a false-positive package name
141
+ ## Why package-name alerts are not enough
118
142
 
119
143
  Given this installed graph:
120
144
 
@@ -127,18 +151,7 @@ plugin@1.0.0
127
151
  └── parser@2.9.0
128
152
  ```
129
153
 
130
- an advisory affecting only `parser@2.9.0` produces:
131
-
132
- ```text
133
- [HIGH][NEW] Dependency vulnerability
134
- Project: Payments API (payments-api)
135
- Plugin: plugin@1.0.0
136
- Affected: parser@2.9.0
137
- Path: plugin@1.0.0 -> logger@4.0.2 -> parser@2.9.0
138
- Fixed versions: 3.0.0
139
- ```
140
-
141
- The unaffected `parser@3.2.1` remains a distinct node.
154
+ an advisory affecting `parser@2.9.0` matches only the `plugin -> logger -> parser` branch. The unaffected `parser@3.2.1` remains a distinct physical node instead of becoming a package-name false positive.
142
155
 
143
156
  ## Vulnerabilities are only half the upstream problem
144
157
 
@@ -214,6 +227,7 @@ Upstream Radar is alpha software built for the developer-preview DSH ecosystem.
214
227
  - [Threat model](docs/threat-model.md)
215
228
  - [Roadmap](ROADMAP.md)
216
229
  - [Changelog](CHANGELOG.md)
230
+ - [Release process](docs/releasing.md)
217
231
  - [Contributing](CONTRIBUTING.md)
218
232
  - [Security policy](SECURITY.md)
219
233
 
package/README.zh-CN.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <h1 align="center">Upstream Radar</h1>
9
9
 
10
- <p align="center"><strong>只有当上游变化真正命中项目时，才唤醒你的 DSH Agent。</strong></p>
10
+ <p align="center"><strong>面向 DeepSeek Harness 插件的常驻漏洞与破坏性更新雷达。</strong></p>
11
11
 
12
12
  <p align="center">
13
13
  <a href="README.md">English</a> · 简体中文
@@ -15,56 +15,55 @@
15
15
 
16
16
  <p align="center">
17
17
  <a href="https://www.npmjs.com/package/upstream-radar"><img alt="npm 版本" src="https://img.shields.io/npm/v/upstream-radar?style=flat-square&color=2563eb"></a>
18
+ <a href="https://github.com/MicroMilo/upstream-radar/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/MicroMilo/upstream-radar?style=flat-square&color=f59e0b"></a>
18
19
  <a href="https://github.com/MicroMilo/upstream-radar/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/MicroMilo/upstream-radar/ci.yml?branch=main&style=flat-square&label=CI"></a>
19
20
  <a href="examples/dsh/README.md"><img alt="已使用 DSH 0.1.0-rc.6 验证" src="https://img.shields.io/badge/tested_with_DSH-0.1.0--rc.6-5b5bd6?style=flat-square"></a>
21
+ <a href="https://github.com/MicroMilo/upstream-radar/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/MicroMilo/upstream-radar?style=flat-square"></a>
20
22
  <a href="LICENSE"><img alt="Apache-2.0 许可证" src="https://img.shields.io/badge/license-Apache--2.0-0f766e?style=flat-square"></a>
21
23
  </p>
22
24
 
23
25
  ---
24
26
 
25
- 普通漏洞源只能告诉你“某个包有问题”。它通常无法回答：这个精确版本是被哪个 DSH 插件带进来的、真实依赖路径是什么、项目是否会触发漏洞，以及升级时会不会顺手破坏 DSH 兼容性。
27
+ 普通漏洞源到“某个包有问题”就结束了。Upstream Radar 会继续找到实际安装的依赖路径，维护一个可持续更新的事件，再把带有项目证据的调查任务交给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Agent。
26
28
 
27
- Upstream Radar 把这条链路闭合在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 内部：
28
-
29
- - **看精确路径，不按包名猜。** 保留物理依赖节点、重复版本和真正命中的完整路径。
30
- - **维护事件状态，不制造告警洪水。** 记录 `new`、`updated`、`resolved`，同一事件只保留当前任务。
31
- - **程序先确定事实，模型只做判断。** 版本命中和兼容边界由程序计算；DSH Agent 只调查项目可达性和迁移影响。
32
-
33
- ## 在真实 DSH 中运行证明
34
-
35
- ```bash
36
- git clone https://github.com/MicroMilo/upstream-radar.git
37
- cd upstream-radar
38
- corepack enable
39
- pnpm install --frozen-lockfile
40
- pnpm run try:dsh
29
+ ```text
30
+ OSV 漏洞公告或 npm 新版本
31
+ -> 真正命中的插件依赖路径
32
+ -> new / updated / resolved 事件
33
+ -> 面向具体项目的 DSH Agent 分析任务
41
34
  ```
42
35
 
43
- 这个命令会把打包后的 bundle 安装进全新的 DSH `headless` profile。只有付费模型端点被本地确定性 stub 替代；Cordis loader、DSH Agent、Session、持久化和插件投递都是真实组件。
36
+ **没有命中实际安装路径，就不会唤醒 Agent。** 版本匹配和兼容性事实由程序计算；模型只负责结合仓库做判断。
44
37
 
45
- 验证不满足以下四项就会失败：
38
+ ## 先看一个真实事件
46
39
 
47
- ```json
48
- {
49
- "bundleInstalled": true,
50
- "radarTaskReachedModel": true,
51
- "pluginSourcePreserved": true,
52
- "pendingTasksAfterDelivery": 0
53
- }
40
+ 同一个插件里安装了两个 `parser` 版本，而公告只影响其中一个时，Radar 会报告真正命中的路径：
41
+
42
+ ```text
43
+ [HIGH][NEW] Dependency vulnerability
44
+ Project: Payments API (payments-api)
45
+ Plugin: plugin@1.0.0
46
+ Affected: parser@2.9.0
47
+ Advisory: GHSA-demo-2026-parser / CVE-2026-1234
48
+ Paths:
49
+ plugin@1.0.0 -> logger@4.0.2 -> parser@2.9.0
50
+ Fixed versions: 3.0.0
51
+ Route: payments-platform via feishu:payments-security
54
52
  ```
55
53
 
56
- 要把当前 OSV 和 npm 数据也加入启动轮询：
54
+ 这个事件会成为带有插件身份的 DSH notice，而不是被复制进一段泛泛的聊天提示词。
57
55
 
58
- ```bash
59
- pnpm run try:dsh:live
60
- ```
56
+ | 上游信号 | Radar 用程序确定 | DSH Agent 结合项目调查 |
57
+ | --- | --- | --- |
58
+ | 漏洞或恶意软件包 | 受影响的精确版本、每条安装路径、修复版本和事件状态 | 项目是否调用、攻击者输入能否到达、代价最低的修复办法 |
59
+ | npm 候选版本 | 版本边界，以及 Node、peer、exports、入口、bundle 和依赖变化 | 哪些 API 或 Cordis 配置会受影响、应该如何迁移 |
61
60
 
62
61
  ## 安装到 DSH
63
62
 
64
63
  Upstream Radar 发布的是已经构建好的 npm bundle，不需要开放安装期构建权限：
65
64
 
66
65
  ```bash
67
- dsh plugin --profile web add upstream-radar@0.4.0
66
+ dsh plugin --profile web add upstream-radar@latest
68
67
  ```
69
68
 
70
69
  指定项目清单和持久化状态文件后启动 profile：
@@ -80,6 +79,33 @@ dsh --profile web
80
79
 
81
80
  可以从[示例清单](examples/radar/config.json)开始。如果没有设置 `UPSTREAM_RADAR_CONFIG`，插件会保持休眠，不发起轮询。
82
81
 
82
+ 启动后，Radar 会轮询 OSV 与 npm，先把事件状态持久化，再把有变化的事件交给第一个在线的根 DSH Agent。
83
+
84
+ ## 在真实 DSH 中运行证明
85
+
86
+ ```bash
87
+ git clone https://github.com/MicroMilo/upstream-radar.git
88
+ cd upstream-radar
89
+ corepack enable
90
+ pnpm install --frozen-lockfile
91
+ pnpm run try:dsh
92
+ ```
93
+
94
+ 这个命令会把打包后的 bundle 安装进全新的 DSH `headless` profile。只有付费模型端点被本地确定性 stub 替代；Cordis loader、DSH Agent、Session、持久化和插件投递都是真实组件。
95
+
96
+ 验证不满足以下四项就会失败：
97
+
98
+ ```json
99
+ {
100
+ "bundleInstalled": true,
101
+ "radarTaskReachedModel": true,
102
+ "pluginSourcePreserved": true,
103
+ "pendingTasksAfterDelivery": 0
104
+ }
105
+ ```
106
+
107
+ 运行 `pnpm run try:dsh:live`，可以在 DSH 投递前加入一次当前 OSV 与 npm 数据轮询。
108
+
83
109
  ## 闭环如何工作
84
110
 
85
111
  1. 读取项目清单和实际安装的 npm 依赖图。
@@ -102,7 +128,7 @@ dsh --profile web
102
128
 
103
129
  这是 DSH 原生生命周期集成，不是聊天机器人，也不是远程控制入口。
104
130
 
105
- ## 一个真实命中的路径
131
+ ## 为什么只按包名告警不够
106
132
 
107
133
  ```text
108
134
  plugin@1.0.0
@@ -113,18 +139,7 @@ plugin@1.0.0
113
139
  └── parser@2.9.0
114
140
  ```
115
141
 
116
- 如果公告只影响 `parser@2.9.0`，Radar 输出的是：
117
-
118
- ```text
119
- [HIGH][NEW] Dependency vulnerability
120
- Project: Payments API (payments-api)
121
- Plugin: plugin@1.0.0
122
- Affected: parser@2.9.0
123
- Path: plugin@1.0.0 -> logger@4.0.2 -> parser@2.9.0
124
- Fixed versions: 3.0.0
125
- ```
126
-
127
- 不受影响的 `parser@3.2.1` 仍然是独立节点。
142
+ 如果公告只影响 `parser@2.9.0`，它只会命中 `plugin -> logger -> parser` 这条分支。不受影响的 `parser@3.2.1` 仍然是独立的物理节点，不会变成按包名产生的误报。
128
143
 
129
144
  ## 不只监控漏洞，也监控 breaking changes
130
145
 
@@ -162,6 +177,7 @@ Upstream Radar 目前是面向 DSH developer preview 生态的 alpha 软件，
162
177
  - [威胁模型](docs/threat-model.md)
163
178
  - [Roadmap](ROADMAP.md)
164
179
  - [Changelog](CHANGELOG.md)
180
+ - [发布流程](docs/releasing.md)
165
181
  - [贡献指南](CONTRIBUTING.md)
166
182
  - [安全策略](SECURITY.md)
167
183
 
package/dist/src/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const TOOL_VERSION = "0.4.0";
1
+ export declare const TOOL_VERSION = "0.4.1";
2
2
  //# sourceMappingURL=version.d.ts.map
package/dist/src/version.js CHANGED
@@ -1,2 +1,2 @@
1
- export const TOOL_VERSION = '0.4.0';
1
+ export const TOOL_VERSION = '0.4.1';
2
2
  //# sourceMappingURL=version.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "upstream-radar",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "Always-on vulnerability and breaking-change impact monitoring for DeepSeek Harness plugins.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",