upstream-radar 0.33.7 → 0.33.9

package/README.md

@@ -91,7 +91,7 @@ The useful part is the exact path and project-specific next step—not another g
 Want to try it on a real published DSH plugin immediately?
 
 ```bash
-npx --yes upstream-radar@0.33.7 inspect dsh-feishu-bot@0.15.4 --deep
+npx --yes upstream-radar@0.33.9 inspect dsh-feishu-bot@0.15.4 --deep
 ```
 
 This runs from an otherwise empty directory and returns a short admission,
@@ -101,7 +101,7 @@ Want to see a real author-actionable result? This exact published DSH plugin
 currently cannot produce a complete dependency graph in a clean npm resolver:
 
 ```bash
-npx --yes upstream-radar@0.33.7 inspect \
+npx --yes upstream-radar@0.33.9 inspect \
   @sanqi-normal/dsh-webui-market-plugin@0.5.4 \
   --deep --fail-on never
 ```
@@ -279,7 +279,7 @@ since then.
 ```text
 targets.yml
   ↓
-GitHub commit + npm package metadata + optional lockfile
+GitHub commit + npm package metadata + auto-detected or explicit lockfile
   ↓
 observations.json
   ↓
@@ -303,11 +303,36 @@ targets:
     lockfileType: pnpm
 ```
 
+For one public repository, skip YAML and pass its GitHub URL directly. The
+first run creates a baseline; later runs compare the ref you provide. The
+observer automatically looks for `pnpm-lock.yaml` or `package-lock.json` and
+uses the real committed graph. Add `--package-path` for a nested plugin,
+`--package` when the npm name differs from the source manifest, or
+`--lockfile` when you want to choose a particular lockfile:
+
+```bash
+npx --yes upstream-radar@0.33.9 observe \
+  https://github.com/PlutoKeating/dsh-lark-bot \
+  --state ./observations.json --report ./upstream-radar-observer.md
+```
+
+The public example below supplies `--package` because this repository's source
+manifest is `dsh-lark-bot`, while its published npm package is
+`dsh-feishu-bot`:
+
+```bash
+npx --yes upstream-radar@0.33.9 observe \
+  https://github.com/PlutoKeating/dsh-lark-bot \
+  --package dsh-feishu-bot \
+  --lockfile pnpm-lock.yaml --lockfile-type pnpm \
+  --state ./observations.json --report ./upstream-radar-observer.md
+```
+
 Then run one cycle:
 
 ```bash
 export GITHUB_TOKEN='a read-only GitHub token'
-npx --yes upstream-radar@0.33.7 observe \
+npx --yes upstream-radar@0.33.9 observe \
   ./targets.yml \
   --state ./observations.json \
   --report ./upstream-radar-observer.md
@@ -319,7 +344,8 @@ This uses the published CLI; pin the exact version in CI rather than relying on
 - the source commit and changed files;
 - the published npm version and integrity value;
 - the package entrypoint, exports, Node requirement, DSH bundle metadata and dependency declarations;
-- the real npm or pnpm lockfile graph, when a lockfile is configured.
+- the real npm or pnpm lockfile graph, when a supported lockfile is committed;
+  the selected path is recorded in the observation state.
 
 README/docs/tests-only changes advance the observation point without waking the
 Agent. Runtime source, DSH bundle, package entry, dependency graph, npm version,
@@ -555,7 +581,7 @@ cd my-dsh-plugin
 pnpm install --ignore-scripts
 
 # Read the exact graph before adding the plugin to a DSH profile.
-pnpm dlx --package=upstream-radar@0.33.7 upstream-radar graph pnpm-lock pnpm-lock.yaml --json
+pnpm dlx --package=upstream-radar@0.33.9 upstream-radar graph pnpm-lock pnpm-lock.yaml --json
 ```
 
 The graph includes the exact DSH package versions and keeps unresolved optional peers visible. It does not load the generated plugin or run lifecycle scripts. After reviewing it, copy this complete workflow into `.github/workflows/upstream-radar.yml`:
@@ -577,7 +603,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: MicroMilo/upstream-radar@v0.33.7
+      - uses: MicroMilo/upstream-radar@v0.33.9
         with:
           fail-on: high
           fail-on-compatibility: breaking
@@ -588,7 +614,7 @@ The Action auto-detects the one `pnpm-lock.yaml`, checks the same exact graph, a
 To check a real published DSH artifact directly, run one command:
 
 ```bash
-npx --yes upstream-radar@0.33.7 inspect dsh-feishu-bot@0.15.4 --deep
+npx --yes upstream-radar@0.33.9 inspect dsh-feishu-bot@0.15.4 --deep
 ```
 
 The checked result is `REVIEW`: registry integrity, signature, provenance, and
@@ -745,7 +771,7 @@ To see the two-source vulnerability contract without contacting the network, run
 Before wiring a project into a compatibility gate, run the offline rule benchmark:
 
 ```bash
-pnpm dlx --package=upstream-radar@0.33.7 upstream-radar benchmark compatibility
+pnpm dlx --package=upstream-radar@0.33.9 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.
@@ -758,7 +784,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.33.7 upstream-radar probe dsh-load \
+pnpm dlx --package=upstream-radar@0.33.9 upstream-radar probe dsh-load \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.6
 ```
@@ -784,7 +810,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.33.7 upstream-radar probe dsh-matrix \
+pnpm dlx --package=upstream-radar@0.33.9 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 \
@@ -800,7 +826,7 @@ If your team wants the shortest scheduled CI gate before wiring a machine to a l
 ```yaml
 steps:
   - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-  - uses: MicroMilo/upstream-radar@v0.33.7
+  - uses: MicroMilo/upstream-radar@v0.33.9
     with:
       fail-on: high
       # Optional: also fail on deterministic DSH/plugin compatibility breaks.
@@ -809,12 +835,12 @@ steps:
       threat-intel: true
 ```
 
-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. `threat-intel` is false by default so an ordinary CI gate stays lean; set it to `true` when the Job Summary and raw JSON should include CISA KEV and FIRST EPSS prioritization evidence. 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. In addition to the raw JSON log, the Action writes a short escaped summary to the GitHub Job Summary so a scheduled failure immediately shows the affected package, exact path, published fix version when available, one-line priority evidence, and a suggested next step. 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.33.7`, 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. `threat-intel` is false by default so an ordinary CI gate stays lean; set it to `true` when the Job Summary and raw JSON should include CISA KEV and FIRST EPSS prioritization evidence. 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. In addition to the raw JSON log, the Action writes a short escaped summary to the GitHub Job Summary so a scheduled failure immediately shows the affected package, exact path, published fix version when available, one-line priority evidence, and a suggested next step. 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.33.9`, and pin the checkout Action in your workflow according to your repository's policy.
 
 If the repository has no committed Radar config yet, the smallest setup is to omit `config`, `pnpm-lock`, and `npm-lock`. After checkout, the Action automatically uses the only one of `pnpm-lock.yaml` or `package-lock.json` that exists, generates a temporary reviewed config, and runs the same frozen check:
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.33.7
+- uses: MicroMilo/upstream-radar@v0.33.9
   with:
     fail-on: high
 ```
@@ -824,7 +850,7 @@ An existing `config` wins over auto-detection. If both lockfiles exist, or neith
 To review the exact plugin artifact before it enters DSH, add `inspect-package`:
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.33.7
+- uses: MicroMilo/upstream-radar@v0.33.9
   with:
     inspect-package: dsh-cloudflare-browser-run@0.1.1
     # review is the safe default; use block only when incomplete coverage may pass.
@@ -836,7 +862,7 @@ This downloads that exact npm tarball, verifies the registry integrity/signature
 If the repository has a pnpm lockfile but no committed Radar config yet, the Action can generate the config in the same job. See the [copyable pnpm workflow](examples/github-actions/upstream-radar-pnpm.yml):
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.33.7
+- uses: MicroMilo/upstream-radar@v0.33.9
   with:
     pnpm-lock: pnpm-lock.yaml
     fail-on: high
@@ -850,7 +876,7 @@ See the [copyable npm workflow](examples/github-actions/upstream-radar-npm.yml)
 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.33.7 upstream-radar radar check \
+pnpm dlx --package=upstream-radar@0.33.9 upstream-radar radar check \
   ./upstream-radar.config.json --frozen --state :memory: --fail-on high \
   --fail-on-compatibility breaking --json
 ```
@@ -858,7 +884,7 @@ pnpm dlx --package=upstream-radar@0.33.7 upstream-radar radar check \
 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.33.7
+- uses: MicroMilo/upstream-radar@v0.33.9
   id: radar
   with:
     config: upstream-radar.config.json

package/dist/src/cli.js

@@ -29,10 +29,10 @@ import { createRadarHistory, renderRadarHistory } from './radar-history.js';
 import { loadRadarState, saveRadarState } from './radar-state.js';
 import { createRadarNext, createRadarStatus, renderRadarNext, renderRadarStatus } from './radar-status.js';
 import { renderTextReport } from './render.js';
-import { materializeGitHubRepository } from './repository.js';
+import { materializeGitHubRepository, parseGitHubRepositoryUrl } from './repository.js';
 import { scanDirectory } from './scan.js';
 import { CisaKevClient, EpssClient } from './threat-intel.js';
-import { loadObservationState, parseObserverConfigText, renderObserverReport, runDshAgentCommand, runOpenAiCompatibleAgent, runObserver, saveObservationState, UpstreamObserverClient, } from './upstream-observer.js';
+import { loadObservationState, OBSERVER_TARGETS_SCHEMA, parseObserverConfig, parseObserverConfigText, renderObserverReport, runDshAgentCommand, runOpenAiCompatibleAgent, runObserver, saveObservationState, UpstreamObserverClient, } from './upstream-observer.js';
 import { TOOL_VERSION } from './version.js';
 import { eventsForRadarWebhookTarget, markRadarWebhookEventsDelivered, markRadarWebhookEventsDeliveredForRoute, normalizeRadarWebhookUrl, queueRadarWebhookEvents, queueRadarWebhookEventsForRoute, resolveRadarWebhookTargets, sendRadarWebhook, undeliveredRadarWebhookEvents, undeliveredRadarWebhookEventsForRoute, } from './webhook.js';
 const VALID_THRESHOLDS = new Set(['warn', 'review', 'block', 'never']);
@@ -197,14 +197,22 @@ should remain visible without failing CI.
         observe: `Upstream Radar — watch DSH plugin repositories and packages for meaningful upstream changes
 
 Usage:
-  upstream-radar observe <targets.yml> [--state <observations.json>]
+  upstream-radar observe <targets.yml|github-url> [--state <observations.json>]
     [--report <report.md>] [--dsh-agent-command <executable>]
-    [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending] [--json]
+    [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending]
+    [--ecosystem <dsh|codex|pi>] [--id <id>] [--package <name>]
+    [--package-path <path>] [--lockfile <path>] [--lockfile-type <npm|pnpm>]
+    [--ref <branch>] [--json]
 
 The first run creates a baseline. Later runs compare source commits, published
 npm metadata, package manifests, and an optional npm/pnpm dependency graph. A
 DSH Agent is called only for meaningful changes. Safety: does not install packages, run lifecycle scripts, load plugin code, or invoke a shell.
 
+When the target is an HTTPS GitHub repository URL, Radar builds one target in
+memory and does not require a targets.yml file. The default package path is
+package.json; pass --package-path for a nested plugin and --lockfile to include
+the committed npm/pnpm graph.
+
 The Agent executable receives one read-only task prompt on stdin and should
 return one JSON conclusion on stdout. If it is not configured, the task stays
 in observations.json for a later explicit retry. As a simpler alternative,
@@ -410,7 +418,7 @@ Usage:
   upstream-radar doctor [config.json] [options]
   upstream-radar scan <directory-or-github-url> [--json] [--fail-on <warn|review|block|never>]
   upstream-radar inspect [npm:]<package>@<exact-version> [--deep] [--json] [--fail-on <warn|review|block|never>]
-  upstream-radar observe <targets.yml> [--state <observations.json>] [--report <report.md>] [--dsh-agent-command <executable>] [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending] [--json]
+  upstream-radar observe <targets.yml|github-url> [--state <observations.json>] [--report <report.md>] [--dsh-agent-command <executable>] [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending] [--ecosystem <dsh|codex|pi>] [--id <id>] [--package <name>] [--package-path <path>] [--lockfile <path>] [--lockfile-type <npm|pnpm>] [--ref <branch>] [--json]
   upstream-radar graph <npm-lock|pnpm-lock> <lockfile> [--root <package>@<exact-version>] [--json]
   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]
@@ -1400,7 +1408,7 @@ async function runRadar(args) {
 async function runObserve(args) {
     const targetsPath = args[0];
     if (targetsPath === undefined || targetsPath.startsWith('-'))
-        throw new Error('observe requires a targets.yml file');
+        throw new Error('observe requires a targets.yml file or an HTTPS GitHub repository URL');
     let statePath = 'observations.json';
     let reportPath;
     let agentCommand;
@@ -1409,6 +1417,14 @@ async function runObserve(args) {
     let registry;
     let retryPending = false;
     let json = false;
+    let inlineEcosystem;
+    let inlineId;
+    let inlinePackage;
+    let inlinePackagePath;
+    let inlineLockfile;
+    let inlineLockfileType;
+    let inlineRef;
+    let inlineOptionsUsed = false;
     for (let index = 1; index < args.length; index += 1) {
         const argument = args[index];
         if (argument === '--json') {
@@ -1417,11 +1433,25 @@ async function runObserve(args) {
         else if (argument === '--retry-pending') {
             retryPending = true;
         }
-        else if (argument === '--state' || argument === '--report' || argument === '--dsh-agent-command' || argument === '--dsh-agent-arg' || argument === '--llm-env-file' || argument === '--registry') {
+        else if (argument === '--ecosystem' || argument === '--id' || argument === '--package' || argument === '--package-path' || argument === '--lockfile' || argument === '--lockfile-type' || argument === '--ref' || argument === '--state' || argument === '--report' || argument === '--dsh-agent-command' || argument === '--dsh-agent-arg' || argument === '--llm-env-file' || argument === '--registry') {
             const value = args[index + 1];
             if (value === undefined || (value.startsWith('-') && argument !== '--dsh-agent-arg'))
                 throw new Error(`${argument} requires a value`);
-            if (argument === '--state')
+            if (argument === '--ecosystem')
+                inlineEcosystem = value;
+            else if (argument === '--id')
+                inlineId = value;
+            else if (argument === '--package')
+                inlinePackage = value;
+            else if (argument === '--package-path')
+                inlinePackagePath = value;
+            else if (argument === '--lockfile')
+                inlineLockfile = value;
+            else if (argument === '--lockfile-type')
+                inlineLockfileType = value;
+            else if (argument === '--ref')
+                inlineRef = value;
+            else if (argument === '--state')
                 statePath = value;
             else if (argument === '--report')
                 reportPath = value;
@@ -1433,14 +1463,42 @@ async function runObserve(args) {
                 llmEnvFile = value;
             else
                 registry = value;
+            if (argument !== '--state' && argument !== '--report' && argument !== '--dsh-agent-command' && argument !== '--dsh-agent-arg' && argument !== '--llm-env-file' && argument !== '--registry')
+                inlineOptionsUsed = true;
             index += 1;
         }
         else {
             throw new Error(`unknown option for observe: ${argument}`);
         }
     }
-    const targetText = await readBoundedFile(targetsPath, 256 * 1024);
-    const config = parseObserverConfigText(targetText);
+    const githubTarget = parseGitHubRepositoryUrl(targetsPath);
+    let config;
+    if (githubTarget !== undefined) {
+        if (inlineLockfileType !== undefined && inlineLockfile === undefined) {
+            throw new Error('--lockfile-type requires --lockfile when observe receives a GitHub URL');
+        }
+        config = parseObserverConfig({
+            schema: OBSERVER_TARGETS_SCHEMA,
+            targets: [{
+                    id: inlineId ?? `${githubTarget.owner}-${githubTarget.repository}`,
+                    ecosystem: inlineEcosystem ?? 'dsh',
+                    repository: `${githubTarget.owner}/${githubTarget.repository}`,
+                    ref: inlineRef ?? 'main',
+                    packageName: inlinePackage,
+                    packagePath: inlinePackagePath ?? 'package.json',
+                    ...(inlineLockfile === undefined ? {} : { lockfile: inlineLockfile }),
+                    ...(inlineLockfileType === undefined ? {} : { lockfileType: inlineLockfileType }),
+                }],
+        });
+    }
+    else {
+        if (/^https?:\/\//i.test(targetsPath))
+            throw new Error('observe URL must be an HTTPS GitHub repository URL');
+        if (inlineOptionsUsed)
+            throw new Error('--ecosystem, --id, --package, --package-path, --lockfile, --lockfile-type and --ref require a GitHub URL target');
+        const targetText = await readBoundedFile(targetsPath, 256 * 1024);
+        config = parseObserverConfigText(targetText);
+    }
     const previousState = await loadObservationState(statePath);
     const source = new UpstreamObserverClient({
         ...(process.env.GITHUB_TOKEN === undefined ? {} : { githubToken: process.env.GITHUB_TOKEN }),