upstream-radar 0.40.0 → 0.41.0

package/README.md

@@ -2,258 +2,155 @@
 
 [![CI](https://github.com/MicroMilo/upstream-radar/actions/workflows/ci.yml/badge.svg)](https://github.com/MicroMilo/upstream-radar/actions)
 [![npm](https://img.shields.io/npm/v/upstream-radar)](https://www.npmjs.com/package/upstream-radar)
+[![GitHub stars](https://img.shields.io/github/stars/MicroMilo/upstream-radar)](https://github.com/MicroMilo/upstream-radar/stargazers)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-**The upstream dependency radar built into [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugins.**
+**Compatibility evidence for the [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugin ecosystem.**
 
-Upstream Radar is not another package-name vulnerability scanner. It follows one DSH plugin from admission to maintenance:
+A plugin repository can look healthy while its published artifact has drifted
+from the DSH host it actually runs in. Upstream Radar joins what a plugin
+declares with what an isolated DSH profile really resolves, then keeps that
+relationship current as DSH and plugins change.
 
-| Product job | What Radar establishes |
-| --- | --- |
-| **DSH compatibility / admission** | Whether the exact published bundle can be installed, registered, and loaded by the DSH releases you care about, with an isolated execution lane for behavior evidence. |
-| **Real dependency graph** | Which exact package versions and physical paths the plugin brings into the DSH profile, including unresolved edges. |
-| **Continuous upstream monitoring** | Whether an advisory, npm release, DSH/Cordis change, or breaking signal changes the old → new situation. |
-| **Author-facing repair** | Which plugin, dependency path, version, lockfile, or DSH declaration gives the author a concrete next fix. |
-
-The deterministic scanner establishes package, graph, advisory, and compatibility facts. Only a meaningful affected change is handed to the DSH Agent for read-only, project-specific analysis; the model does not guess version matches or replace the evidence.
+The core object is an exact environment, not a package name or a diff:
 
-## The product loop
-
-```mermaid
-flowchart TD
-  A["DSH plugin source or exact npm artifact"] --> B["Static review + DSH compatibility check"]
-  B --> C["Build the real plugin → dependency graph"]
-  C --> D["Monitor advisories, npm, DSH and Cordis changes"]
-  D --> E{"Meaningful affected change?"}
-  E -- "No" --> F["Update observation point and stay quiet"]
-  E -- "Yes" --> G["Calculate exact old → new impact paths"]
-  G --> H["Send bounded evidence to the DSH Agent"]
-  H --> I["Return a repairable action to the plugin author"]
+```text
+plugin tarball SHA-256 × DSH version × Node/pnpm baseline × approved dependency builds
 ```
 
-This is the boundary: Radar decides **what changed and which exact path is involved**; DSH decides **what that means for the project**. A later website can visualize the saved graph, but the evidence and impact index are already useful without one.
-
-## The upstream/downstream alignment IR
-
-Every observer snapshot now carries a small, machine-readable alignment record:
+## How the system fits together
 
-```text
-upstream:   Git commit + package.json coordinate
-downstream: npm coordinate + lockfile graph root + graph coverage
-result:     aligned | mismatch | unknown
+```mermaid
+flowchart TB
+  Artifact["Exact plugin tarball"] --> Static["Static: peer declaration + literal import evidence"]
+  DSH["Exact DSH + Node runtime"] --> Runtime["Fresh VM + restricted container"]
+  Static --> Runtime
+  Runtime --> Resolve["Dynamic: install → register → profile resolver → import → headless boot"]
+  Resolve --> IR["Compatibility IR: declared range ↔ resolved host version"]
+  IR --> Ledger["Current-cell ledger"]
+  IR --> Impact["Reverse impact index + author-facing repair"]
+  Ledger --> Incident["Managed compatibility incident"]
+  Incident --> Repair["Plugin or DSH repair"]
+  Repair --> Artifact
 ```
 
-This catches a class of problems that a vulnerability scanner cannot: the source
-package, published package, and dependency graph may no longer describe the
-same thing. For example, the public DSH/Feishu target currently reports:
+Radar establishes deterministic facts; an optional Agent may explain project
+impact afterward. A model never decides whether versions match or turns missing
+evidence into a green result.
 
-```text
-source:    dsh-lark-bot@0.15.8
-published: dsh-feishu-bot@0.15.8
-graph root: dsh-lark-bot@0.15.8
-result:    mismatch
-```
+## What it answers
 
-That is not a claim of malware or runtime incompatibility. It is an evidence
-gap: Radar cannot safely say that the source it watched produced the artifact
-users install. The IR is stored in `observations.json`, rendered in the first
-baseline report, and defined in [`schemas/upstream-downstream-ir.schema.json`](schemas/upstream-downstream-ir.schema.json).
+| Question | Evidence returned |
+| --- | --- |
+| Does the declared plugin contract align with this DSH release? | Exact tarball, Node contract, install/registration/load evidence, and every direct peer's resolved host version. |
+| Is it a runtime break or a declaration drift? | Static literal-import classification beside the dynamic resolver result. |
+| What enters the DSH profile? | Exact npm/pnpm nodes, host-plane joins, duplicate versions, paths, and unresolved edges. |
+| Which plugins are exposed to an upstream dependency change? | A materialized reverse index from host package to exact plugin cells. |
+| What can the author repair? | One package/range/API boundary with the evidence needed to reproduce it. |
+| What happens after a break is found? | One managed issue is created, updated on repeat failures, reopened on regression, and closed only after a clean retest. |
+
+## Proven on real DSH plugins
+
+- Imported a commit-pinned cohort of **8 repositories** from
+  [`awesome-dsh-plugin`](examples/dsh/awesome-observer/README.md); 6 independently
+  matched npm artifacts enter the isolated matrix and 2 remain correctly
+  GitHub-only.
+- In a fresh VM, tested `@zseven-w/dsh-openpencil@0.1.0-rc.1` against current
+  DSH `0.1.1-rc.1` on Node 24. Install, registration, direct import, and
+  headless boot passed; the exact host-contract check found **12/14** peers
+  aligned, one type-only peer declaration missing, and one runtime `react-dom`
+  range drift. [Read the reproducible case.](examples/dsh/install-observer/reports/2026-08-22-openpencil-node24.md)
+- Proved `dsh-better-sidebar@0.14.0` succeeds only after the documented
+  `node-pty` build is explicitly approved and the native toolchain is present.
+- Found that `@sanqi-normal/dsh-webui-market-plugin@0.5.4` could not form a
+  clean DSH dependency graph, gave the author an exact repair path, and added
+  the published `0.5.5` repair to the maintained isolated matrix.
+  [See the author-confirmed case.](https://github.com/Sanqi-normal/dsh-webui-market-plugin/issues/5)
+- Built a reverse index from **37 real plugin graphs and 1,025 dependency
+  coordinates**, while preserving 13 missing-graph targets as evidence gaps.
+
+Read the [live isolated matrix and negative controls](examples/dsh/install-observer/reports/2026-08-21-dsh-0.1.1-rc.1.md)
+or inspect the [first 50-plugin corpus](examples/dsh/first-batch/README.md).
 
 ## Try it in 60 seconds
 
 ```bash
-# No DSH profile, API key, or network state required
-npx --yes upstream-radar@0.40.0 demo
+# Network-free product walkthrough
+npx --yes upstream-radar@0.41.0 demo
 
-# Scan a public DSH plugin repository without installing it
-npx --yes upstream-radar@0.40.0 scan \
+# Static review of a public DSH plugin; no install or plugin execution
+npx --yes upstream-radar@0.41.0 scan \
   https://github.com/PlutoKeating/dsh-lark-bot \
   --fail-on never
 
-# Review a real browser plugin users would install, then check two DSH releases
-npx --yes upstream-radar@0.40.0 review dsh-plugin dsh-cloudflare-browser-run@0.1.1 \
-  --dsh-version 0.1.0-rc.6,0.1.0-rc.7
-```
-
-The important output is evidence, not a green badge: exact package identity, dependency paths, unresolved edges, install-time scripts, npm integrity/signature/provenance, advisory matches, and DSH load results.
-
-## The isolated execution lane
-
-Static metadata tells us that a lifecycle script exists; it cannot tell us what
-actually ran. The new [`dsh-install` workflow](.github/workflows/observe-dsh-plugin-install.yml)
-therefore uses a separate, deliberately untrusted lane:
-
-```text
-fresh GitHub-hosted VM (no secrets, read-only repository token)
-  → restricted container (no host workspace or Docker socket)
-  → npm pack exact package@version with scripts disabled
-  → enforce the artifact's declared Node range before plugin code can run
-  → record the exact Node and pnpm runtime used by the check
-  → DSH installs that same tarball with only the declared dependency-build approvals
-  → strace records child processes, network destinations and file writes
-  → DSH loads the registered bundle under the same exact release
-  → bounded JSON report survives and a non-compatible pair fails the check
-  → the container and VM are discarded
-```
-
-Use **Actions → Observe one DSH plugin install** and supply one exact plugin and
-one exact DSH version. The CLI also exposes `probe dsh-install`, but it refuses
-to run unless both `--execute` and `UPSTREAM_RADAR_ISOLATED_RUNNER=1` are present;
-it is not intended as a normal laptop command.
-
-This lane is wired into the always-on observer. Radar now watches the official
-`@deepseek-ai/dsh` `next` release channel (current DSH releases are prereleases
-rather than npm `latest`). A new exact DSH publication fans out the
-[nine-plugin maintained corpus](examples/dsh/install-observer/targets.json), one
-fresh VM per plugin. Six of those targets come from an identity-checked,
-[commit-pinned `awesome-dsh-plugin` cohort](examples/dsh/awesome-observer/README.md);
-two additional catalog targets are source-only because their real distribution
-is GitHub rather than npm. A mapped plugin publication retests only that plugin. Unchanged
-evidence keeps `observations.json` byte-stable, persistent source/publish drift
-does not wake the Agent again, and the DSH Agent/API key never enters the execution job.
-Build-script approvals are exact package names stored in the maintained target
-and copied into every report; an absent list approves nothing.
-
-The first implementation is intentionally honest about its limit: a container
-shares the hosted VM's kernel, and same-container `strace` evidence is not
-tamper-proof against determined malicious code. The outer VM is disposable and
-secret-free; a Firecracker collector is the later high-assurance backend, not a
-claim made by this report. See the [execution boundary and result semantics](examples/dsh/install-observer/README.md)
-and [`dsh-install-observation.schema.json`](schemas/dsh-install-observation.schema.json).
-
-## What we have already found
-
-These are real, reproducible cases in this repository—not synthetic “vulnerable package” demos.
-
-| Case | Finding | Why it matters |
-| --- | --- | --- |
-| [Live DSH `0.1.1-rc.1` isolated matrix](examples/dsh/install-observer/reports/2026-08-21-dsh-0.1.1-rc.1.md) | Eight exact artifacts install/register/load under their recorded contracts; OpenPencil is stopped before execution because it requires Node ≥24.11 while the isolated runner is Node 22.23; Better Sidebar passes only with its documented `node-pty` build approval and a real native toolchain | The imported awesome cohort found both a genuine runtime-pair incompatibility and a test-environment defect, while preserving the evidence that distinguishes them. |
-| [`dsh-cloudflare-browser-run@0.1.1`](examples/reports/dsh-cloudflare-browser-run-0.1.1.txt) | 18 resolved packages, 2 unresolved optional Cordis edges, 0 known vulnerabilities, and DSH rc.6/rc.7 both loaded the bundle | A real browser plugin demonstrates the DSH admission boundary and why incomplete edges stay visible. |
-| [50-plugin batch](examples/dsh/reports/dsh-batch-50-2026-08-17.md) / [real graph corpus](examples/dsh/first-batch/README.md) | 50 source scans, 30 exact npm reviews, 37 real plugin graphs indexed; 13 targets kept as missing evidence | The reverse index is now built from real DSH plugins, and missing graphs are not treated as clean. |
-| [`dsh-feishu-bot@0.15.8`](examples/dsh/reports/dsh-feishu-bot-0.15.8-review-2026-08-18.md) | 89-package graph, 12 unresolved optional edges, reachable `protobufjs` `postinstall`, DSH rc.6/rc.7 compatible | “No known CVE” is not the same as “no installation trust boundary.” |
-| [DSH-TUI source vs npm](examples/dsh/reports/dsh-tui-source-vs-npm-2026-08-18.md) | Source has `prepare`; published artifact does not | Source-only and artifact-only reviews answer different questions. |
-| [dsh-composer-expand](examples/dsh/reports/dsh-composer-expand-lockfile-feedback.md) | Committed lockfile root says `0.1.0` while source says `0.1.2` | A small author-fix can restore the identity of the monitored graph. |
-
-We report a confirmed vulnerability only when the affected exact version and runtime path are supported by the available evidence. Development-only hits, missing data, and advisory-source outages remain visibly different states.
-
-## Monitor the findings we already found
-
-The repository now has a focused watch for seven real DSH plugins from the first
-batch. It re-runs the source scan and the exact npm artifact review, then stores
-only trusted observations in [`state.json`](examples/dsh/finding-watch/state.json)
-and writes the current author-facing result to
-[`report.md`](examples/dsh/finding-watch/report.md).
-
-```bash
-pnpm run monitor:dsh-findings
-```
-
-The watch distinguishes `persisting`, `added`, `resolved`, `changed`, and
-`unknown`. A failed registry request never becomes “resolved”; a source fix also
-does not erase a finding that remains in the published npm artifact. The same
-loop runs daily in [the dedicated GitHub Actions workflow](.github/workflows/dsh-finding-watch.yml)
-and commits the state only when a trusted observation changes. It does not install
-plugins, execute lifecycle scripts, load DSH, or call an LLM.
-
-The current run is already useful: `dsh-msg-hub@0.1.8` has removed the old source
-lockfile findings, but its npm artifact still reaches `protobufjs@7.6.5` with a
-`postinstall`; `dsh-wsl-workspace` now resolves `koffi@3.1.6`, while the native
-install step remains. The other reviewed install/lifecycle findings persist.
-
-## The dependency graph behind every alert
-
-```text
-plugin@1.0.0
-├── framework@2.4.7
-│   ├── parser@3.2.1
-│   └── archive@1.8.0
-└── logger@4.0.2
-    └── parser@2.9.0  ← the affected physical node
+# Exact artifact review plus a DSH load matrix
+npx --yes upstream-radar@0.41.0 review dsh-plugin \
+  dsh-cloudflare-browser-run@0.1.3 \
+  --dsh-version 0.1.0-rc.8,0.1.1-rc.1
 ```
 
-Two copies of `parser` are different nodes. An alert names the exact version and path that entered the DSH profile; it does not page every plugin that happens to use the same package name.
-
-For a collection of saved reports, build the reverse index that turns an upstream package update into affected plugins:
-
-```bash
-npx --yes upstream-radar@0.40.0 graph reverse ./reports \
-  --output reverse-dependency-index.json
-
-# Ask: which plugins currently depend on this exact package?
-npx --yes upstream-radar@0.40.0 graph reverse ./reports \
-  --package parser@2.9.0
-
-# Rebuild the checked-in index from the real first 50 DSH plugin reports
-pnpm run refresh:dsh-batch
-```
-
-The generated JSON preserves exact paths such as:
-
-```text
-plugin@1.0.0 → logger@4.0.2 → parser@2.9.0
-```
-
-It also preserves whether the graph is complete or has unresolved optional/peer edges. A later website can visualize this index; the index and evidence remain the product foundation.
-
-To route an upstream old → new change to that index, pass it to the always-on
-observer:
-
-```bash
-npx --yes upstream-radar@0.40.0 observe ./targets.yml \
-  --reverse-index ./reverse-dependency-index.json \
-  --state ./observations.json \
-  --report ./upstream-radar-observer.md
-```
-
-The observer matches by package name, not only by the new exact version. If
-`parser@1.0.0` becomes `parser@2.0.0` upstream while a downstream plugin still
-uses `parser@1.0.0`, the report names that plugin and its path as a possible
-impact. `complete` or `incomplete` coverage stays attached to the result; this
-is an evidence-based routing signal, not a claim that the plugin is already
-broken. See the persisted index definition in
-[`schemas/reverse-dependency-index.schema.json`](schemas/reverse-dependency-index.schema.json).
-
-The checked-in real-corpus replay makes this concrete: an observed
-`@deepseek-ai/cordis@4.0.1 → 4.0.2` change routes to 17 DSH plugins from the
-first 50-plugin batch. The route is marked `incomplete` because 26 of the 37
-reconstructed graphs contain unresolved edges; the other 13 targets are kept
-outside the index as missing evidence. Run `pnpm run showcase:observer` to
-replay baseline → one Agent task → quiet run without network access.
-
-## GitHub Action
-
-The repository already contains a reusable, composite Action in [`action.yml`](action.yml). It runs the same frozen Radar check in CI and writes a short Job Summary.
-
-```yaml
-- uses: MicroMilo/upstream-radar@v0.40.0
-  with:
-    config: upstream-radar.config.json
-    fail-on: high
-```
-
-See the [consumer workflow](examples/github-actions/consumer/README.md) for config and lockfile examples. The GitHub Marketplace prompt is a distribution opportunity, not a separate scanning engine: the Action listing should follow a reviewed stable release, while exact tags remain copyable and auditable.
-
-## What it does—and does not do
-
-| It does | It does not claim |
+The code-executing path is deliberately separate. Run **Actions → Observe one
+DSH plugin install** to give one exact pair its own secret-free GitHub-hosted VM
+and restricted container.
+
+## Always-on now
+
+The scheduled observer watches DSH, plugin source/npm/lockfile evidence every
+day, then reconciles a checked-in **compatibility ledger** against the desired
+current matrix. An isolated run is selected when its exact cell is missing,
+older than seven days, or invalidated by a DSH/plugin coordinate, source graph,
+runtime, or build-policy change. A package update therefore accelerates a
+retest; it is no longer the only trigger.
+
+Every report must prove its exact plugin × DSH × Node runtime × build-approval
+cell before it can update the [ledger](compatibility-ledger.json). The Action
+also materializes a bounded [compatibility IR](compatibility-ir.json) and
+[reverse index](compatibility-reverse-index.json). The IR does not copy the
+entire pnpm tree: it preserves the compatibility frontier—the plugin's declared
+non-optional peer range, static use evidence, and concrete package version that
+the final DSH profile resolves.
+
+A Node-engine mismatch stops before plugin execution; a maintained target can
+also select its required Node profile explicitly. The profile lockfile and
+effective profile-plus-DSH-host graph are compared on every retest. An
+install/load green result cannot close a cell while a required direct host peer
+is missing, outside its declared range, or indeterminate.
+
+When all cells are current, the runtime lane stays quiet. Missing or malformed
+reports never turn green: they remain unsatisfied and are selected again.
+
+Actionable incompatibilities become managed issues in the Radar repository.
+The same stable cell owns the issue across plugin and DSH releases: repeated
+failures update it, a regression reopens it, and a later compatible isolated
+run comments with fresh evidence and closes it. `unknown` is deliberately not
+an accusation against a plugin; it fails the observer lane and waits for a
+trustworthy rerun instead of opening an incident.
+
+## Safety boundary
+
+| Radar does | Radar does not claim |
 | --- | --- |
-| Reconstruct exact npm/pnpm dependency paths | An empty finding list is a safety certificate |
-| Query OSV and GitHub Advisory evidence for exact versions | A missing provenance statement proves maliciousness |
-| Compare source and published artifact evidence | Static review replaces runtime evidence |
-| Observe exact install/load behavior in a disposable VM and restricted container | One observed run proves adversarial code is safe |
-| Check DSH bundle/profile compatibility without business actions | “Compatible” means the plugin is secure |
-| Monitor old → new upstream observations | An LLM can repair evidence that was never collected |
+| Static graph and artifact checks without importing plugin code | An empty finding list proves safety |
+| Dynamic checks in a fresh VM and restricted, secret-free container | A shared-kernel container proves hostile code is harmless |
+| Exact-version advisory matching and dependency paths | Every matched plugin is exploitable |
+| Exact-pair compatibility results with explicit coverage | One successful load covers every plugin business action |
 
-## Install and connect to DSH
+An external symlink in a DSH profile never expands static read scope. Radar only
+uses an outside host plane after it has been discovered from the verified DSH
+process that is actually running the profile.
 
-```bash
-pnpm add upstream-radar
+## Use it in DSH or CI
 
-# Generate a reviewable DSH profile inventory from the installed profile
-npx --yes upstream-radar@0.40.0 setup
+```bash
+# Generate a reviewable DSH inventory and wiring
+npx --yes upstream-radar@0.41.0 setup
 ```
 
-For Feishu/webhook routing, DSH Agent handoff, observer state, report schemas, and troubleshooting, use the [full Chinese guide](docs/README.zh-CN.md). The [architecture notes](docs/architecture.md) explain the boundaries and evidence model.
+The repository also ships a [reusable GitHub Action](action.yml), maintained
+[observer workflow](.github/workflows/upstream-observer.yml), and machine-readable
+[schemas](schemas/). See the [Chinese guide](docs/README.zh-CN.md) for complete
+configuration and [architecture notes](docs/architecture.md) for evidence and
+trust boundaries.
 
 ## Development
 
@@ -263,4 +160,5 @@ pnpm test
 pnpm run release:check
 ```
 
-The project is Apache-2.0 licensed. Contributions that improve a real DSH plugin report, dependency resolution, advisory matching, or reproducible author feedback are especially welcome.
+Apache-2.0 licensed. Contributions backed by a reproducible DSH plugin case are
+especially welcome.

package/dist/src/cli.js

@@ -477,7 +477,7 @@ Usage:
   upstream-radar profile-check [profile-directory] [--patch <path>] [--report <path>] [--summary] [--json]
   upstream-radar probe dsh-load <package.tgz> [--dsh-version <exact-version>] [--timeout <seconds>] [--keep-profile] [--json]
   upstream-radar probe dsh-matrix <package.tgz> --dsh-version <v1>[,<v2>,...] [--timeout <seconds>] [--keep-profile] [--json]
-  upstream-radar probe dsh-install [npm:]<package>@<exact-version> --dsh-version <exact-version> --isolation-provider <github-actions-hosted-runner|firecracker|other> --execute [--allow-build <package>]... [--timeout <seconds>] [--report <report.json>] [--json]
+  upstream-radar probe dsh-install [npm:]<package>@<exact-version> --dsh-version <exact-version> [--case-id <stable-label>] --isolation-provider <github-actions-hosted-runner|firecracker|other> --execute [--allow-build <package>]... [--timeout <seconds>] [--report <report.json>] [--json]
   upstream-radar review dsh-plugin [npm:]<package>@<exact-version> --dsh-version <v1>,<v2>,... [--json]
   upstream-radar demo [--json]
   upstream-radar case dsh-web-ui [--json]
@@ -1284,6 +1284,7 @@ async function runDshInstallObservation(args) {
         throw new Error('probe dsh-install requires an exact npm package');
     }
     let dshVersion;
+    let caseId;
     let isolationProvider;
     let timeoutSeconds = 180;
     let reportPath;
@@ -1298,7 +1299,7 @@ async function runDshInstallObservation(args) {
         else if (argument === '--json') {
             json = true;
         }
-        else if (argument === '--dsh-version' || argument === '--isolation-provider' || argument === '--allow-build' || argument === '--timeout' || argument === '--report') {
+        else if (argument === '--dsh-version' || argument === '--case-id' || argument === '--isolation-provider' || argument === '--allow-build' || argument === '--timeout' || argument === '--report') {
             const value = args[index + 1];
             if (value === undefined || value.startsWith('-'))
                 throw new Error(`${argument} requires a value`);
@@ -1307,6 +1308,13 @@ async function runDshInstallObservation(args) {
                     throw new Error('probe dsh-install accepts only one --dsh-version');
                 dshVersion = value;
             }
+            else if (argument === '--case-id') {
+                if (caseId !== undefined)
+                    throw new Error('probe dsh-install accepts only one --case-id');
+                if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(value))
+                    throw new Error('--case-id must be a short lowercase label');
+                caseId = value;
+            }
             else if (argument === '--isolation-provider') {
                 if (value !== 'github-actions-hosted-runner' && value !== 'firecracker' && value !== 'other') {
                     throw new Error('--isolation-provider must be github-actions-hosted-runner, firecracker or other');
@@ -1344,6 +1352,7 @@ async function runDshInstallObservation(args) {
     const report = await observeDshPluginInstall({
         packageSpec,
         dshVersion,
+        ...(caseId === undefined ? {} : { caseId }),
         allowExecution: true,
         isolationProvider,
         allowedBuilds,