@stolyarovmn/dsh-ui-registry-aggregator 0.4.17-rc.3 → 0.5.0

package/README.md

@@ -1,227 +1,114 @@
-# Registry Aggregator for DeepSeek Harness
+# Registry Aggregator for DeepSeek Harness 0.2.x
 
-Registry Aggregator is a federated plugin-discovery UI for DeepSeek Harness. It combines trusted plugin registries, GitHub repositories, and compatible JSON catalogs into one normalized index while leaving installation and plugin lifecycle management to the native DSH Plugin Manager.
+This branch is the clean DSH `0.2.0` implementation line. It does **not** carry compatibility code or UI workarounds from DSH `0.1.x`.
 
-## Screenshots
+Current stable version: `0.5.0`  
+Current validation baseline: DSH `v0.2.0-rc.2`. Compatibility checks use the actual running DSH version from the active installation manifest rather than a hardcoded RC.
 
-### Connected sources
+## Install from npm
 
-Built-in npm and GitHub sources are health-checked, counted, and managed from the **Sources** view.
+```powershell
+$DSH_VERSION = "0.2.0-rc.2"
+$PROFILE = "dsh-020-test"
+$env:DSH_HOME = "$env:USERPROFILE\.dsh-020-test"
 
-![Registry Aggregator — connected sources](docs/screenshots/registry-sources.webp)
-
-### Browse and search
-
-Search across connected sources, filter results, inspect evidence, and install a verified DSH bundle without leaving DeepSeek Harness.
-
-![Registry Aggregator — Browse search](docs/screenshots/registry-browse.webp)
-
-## Highlights
-
-- **Federated Sources** — combine npm, GitHub, and compatible JSON catalogs.
-- **Browse** — search all enabled sources as one deduplicated index.
-- **Verified DSH bundles** — npm/GitHub candidates are checked for a root `dsh.bundle.patch` before they are exposed as installable results.
-- **Evidence** — display release channel, GitHub stars, npm 30-day downloads, freshness, source metadata, and declared DSH compatibility when available.
-- **Filters** — stable releases, age, category, and DSH metadata.
-- **Multi-sort** — compose Stars, Downloads, Freshness, and Name; each criterion can be ascending or descending.
-- **Pagination** — 20, 50, or 100 items per page with navigation above and below results.
-- **Native install** — one-click installation through the DSH Plugin Manager Host API.
-- **Fallback command** — installable results also expose their `dsh plugin add …` command.
-- **Responsive popularity metadata** — missing GitHub star counts are hydrated after Browse renders, so GitHub metadata cannot block the initial search result.
-
-## What's new in 0.4.16
-
-0.4.16 brings Registry Aggregator directly into the native DSH Plugins page and hardens Installed/Browse metadata behavior.
-
-- Registry UI self-embeds below native **Installed** on stock DSH; no manual DSH UI patch is required.
-- Native Installed cards gain expandable registry metadata and advisory update badges without replacing DSH controls.
-- Installed metadata uses exact npm package lookup with 30-day downloads, GitHub stars/freshness, bundle verification, and DSH compatibility.
-- Expanded Installed cards reuse the same visual card primitives as Browse while suppressing information already shown by the native card.
-- Missing GitHub stars are resolved before **Stars** sorting, so displayed values and server-side order stay consistent.
-- GitHub stars use the same warning/yellow treatment in Browse and Installed.
-- Browse preferences persist across openings, including query, filters, ordered sorts, and page size.
-- DSH compatibility is resolved from the active runtime and declared DSH peer ranges.
-- Source metadata/evidence caches are bounded and identical in-flight requests are coalesced.
+pnpm dlx "@deepseek-ai/dsh@$DSH_VERSION" plugin --profile $PROFILE add "@stolyarovmn/dsh-ui-registry-aggregator@0.5.0"
+pnpm dlx "@deepseek-ai/dsh@$DSH_VERSION" --profile $PROFILE
+```
 
-Tested with DSH `0.1.7-rc.2`.
+The package declares DSH compatibility as `>=0.2.0-rc.2 <0.3.0`. Registry compatibility badges are evaluated against the DSH version that is actually running.
+
+## Current milestone
+
+The native Plugin Manager remains responsible for package lifecycle. Registry Aggregator adds discovery capabilities around it.
+
+Implemented in this milestone:
+
+- native `plugins.bundle.config` integration;
+- `Sources | Browse | Updates` navigation;
+- live source configuration through `ctx.configForms.get('registry-aggregator')`; the bundle slot is presentation-only because DSH does not guarantee a single `form` for bundle-wide pages;
+- built-in npm and GitHub sources;
+- custom JSON and corporate catalog sources;
+- Host-side health checks and discovered-item counts;
+- per-source enable/disable, add, remove, refresh, copy-address, count, and error state;
+- DSH 0.2-native switch geometry and icon-action sizing copied under the plugin namespace;
+- authenticated Host RPC over the DSH Connection service;
+- bounded responses, request timeouts, redirect validation, DNS pinning, and private-network blocking;
+- no duplicate `Installed` view;
+- live federated Browse search across enabled npm, GitHub, custom JSON, and corporate sources;
+- compact single-row source/release/freshness/tag/compatibility/page-size filters on desktop, with responsive wrapping below 900px, multi-source metadata, and 20/50/100 pagination; compatibility uses the native DSH shield contour as its neutral filter icon;
+- combinable multi-sort criteria for relevance, stars, downloads, freshness, and name with per-criterion direction; when several are active they contribute equally through percentile-normalized composite ranking, so every selected criterion can affect the order;
+- npm 30-day download enrichment plus lazy paired `30d | total` stats for visible npm rows; lifetime totals are summed from the package creation date (or npm's 2015-01-10 data floor) in bounded windows, and the UI never presents a partial lifetime sum as a real total;
+- package freshness distinguishes npm release time from GitHub repository push time, so GitHub metadata churn does not make every item look newly released;
+- best-effort package artwork discovery from the DSH top-level manifest `icon` field, returned to the Client as bounded data URLs with the same SVG/PNG/JPEG/WebP and 256 KiB policy as native DSH metadata;
+- popular/default Browse results when the query is empty;
+- real npm/GitHub source marks and a package icon exposed through the DSH 0.2 manifest contract;
+- horizontal layout containment for narrow Plugin Manager detail panes;
+- one-click Browse installation through the native DSH `remote.pluginManager` service: `inspect` → `installBundle`, installed-state synchronization via `listBundles` / `plugin-manager/changed`, and inline failure reporting;
+- icon-only Browse install states using the same local DSH-style glyph language as the rest of the page;
+- explicit `v<version>` package versions plus lazy manifest evidence for GitHub/npm rows;
+- compatibility evidence against the actual running DSH version, following DSH peer semantics for `@deepseek-ai/dsh` and `@deepseek-ai/dsh-*`; Browse shows `Compatible`, `Incompatible`, or neutral `Not verified` as plain colored text, and can filter by compatibility;
+- live Updates discovery from native installed bundles plus latest npm manifests, with per-package update through `remote.pluginManager.installBundle`;
+- no runtime import of Harness Client implementation packages;
+- Harness-provided React and DSH theme tokens.
+
+Known limitations in `0.5.0`:
+
+- build-script approval UI remains in the native **Add plugin** dialog;
+- bulk **Update all** / cancel orchestration is not part of the DSH 0.2 line yet;
+- update discovery for GitHub-only installed dependencies without npm package identity is not implemented yet.
 
 ## Architecture
 
 ```text
-Plugins → Installed → @stolyarovmn/dsh-ui-registry-aggregator
-  ├─ Sources / Browse UI
-  ├─ ctx.configForms → source configuration
-  ├─ authenticated Connection RPC (/api/plugin-sources/*)
-  │    └─ Host adapters
-  │         └─ normalize → deduplicate → verify → filter → sort → paginate
-  └─ ctx.remote.pluginManager
+DSH Plugins
+  └─ Installed
+      └─ Registry Aggregator
+          └─ plugins.bundle.config
+              ├─ Sources
+              ├─ Browse
+              └─ Updates
+
+Sources UI
+  ├─ ctx.configForms.get('registry-aggregator')
+  │    ├─ snapshot subscription
+  │    └─ form.mutate(...) → Host Config.sources
+  └─ ctx.connection.rpc.call
+       └─ /api/plugin-sources/{health,counts,browse,icons,metadata,download-stats}
+            └─ Host source adapters
+                 ├─ npm
+                 ├─ GitHub
+                 ├─ custom-json
+                 └─ corporate
+
+Browse Install / Updates
+  └─ native DSH remote.pluginManager
        ├─ inspect(spec)
-       └─ installBundle(spec)
-```
-
-The browser does not fetch arbitrary catalog URLs directly. External source access happens on the Host side through the authenticated DSH Connection RPC boundary.
-
-GitHub star enrichment is intentionally separate from the Browse critical path:
-
-```text
-Browse request
-  → discover / verify / filter / sort / paginate
-  → render cards
-  → request missing GitHub stars for visible repositories
-  → update cards in place
-```
-
-## Install
-
-### npm
+       ├─ installBundle(spec)
+       └─ listBundles() / plugin-manager/changed
 
-```sh
-dsh plugin --profile web add @stolyarovmn/dsh-ui-registry-aggregator
+Enable / disable / uninstall
+  └─ native DSH Plugin Manager
 ```
 
-If you run DSH through `pnpm dlx`:
+## Test from GitHub
 
-```sh
-pnpm dlx @deepseek-ai/dsh@0.1.7-rc.2 plugin --profile web add @stolyarovmn/dsh-ui-registry-aggregator
-```
+Use a commit SHA from this branch rather than publishing a test package:
 
-### GitHub
+```powershell
+$DSH_VERSION = "0.2.0-rc.2"
+$PROFILE = "dsh-020-test"
+$COMMIT = "<commit-sha>"
+$env:DSH_HOME = "$env:USERPROFILE\.dsh-020-test"
 
-```sh
-pnpm dlx @deepseek-ai/dsh@0.1.7-rc.2 plugin --profile web add "git+https://github.com/Stolyarovmn/dsh-ui-registry-aggregator.git"
+pnpm dlx "@deepseek-ai/dsh@$DSH_VERSION" plugin --profile $PROFILE add "github:Stolyarovmn/dsh-ui-registry-aggregator#$COMMIT"
+pnpm dlx "@deepseek-ai/dsh@$DSH_VERSION" --profile $PROFILE
 ```
 
-Enable the installed bundle, then open:
-
-```text
-Plugins → Installed → @stolyarovmn/dsh-ui-registry-aggregator
-```
-
-npm and GitHub sources are added automatically on first use.
-
-## Source types
-
-| Type | Behavior |
-| --- | --- |
-| `npm` | npm registry discovery using DSH-related package metadata and keywords. |
-| `github` | GitHub repository discovery using DeepSeek-Harness-specific topic intersections. |
-| `dsh-plugin-shop` | JSON catalog adapter for a compatible source endpoint. |
-| `dshplugin-app` | JSON catalog adapter for a dshplugin.app-compatible endpoint. |
-| `custom-json` | Public JSON catalog. |
-| `corporate` | JSON catalog with Host-controlled private-network and credential permissions. |
-
-A JSON source may return a bare array or an object containing `plugins`, `items`, or `results`.
-
-Example:
-
-```json
-{
-  "plugins": [
-    {
-      "id": "pdf-tools",
-      "name": "PDF Tools",
-      "description": "Extract and merge PDF documents.",
-      "version": "1.2.0",
-      "package": "@example/dsh-plugin-pdf",
-      "repository": "https://github.com/example/dsh-plugin-pdf",
-      "install": {
-        "type": "npm",
-        "spec": "@example/dsh-plugin-pdf@1.2.0"
-      }
-    }
-  ]
-}
-```
-
-Identity precedence is npm package, canonical repository URL, then source-specific id. Duplicate records preserve source attribution, versions, and normalized category tags.
-
-## Discovery quality
-
-Registry Aggregator treats registry search hits as **candidates**, not automatically as installable DSH plugins.
-
-- npm candidates are verified against their published package metadata.
-- Exact npm package names can be resolved from the registry packument instead of relying only on the eventually-consistent search index.
-- Short and partial queries combine cached discovery with query-specific npm/GitHub discovery.
-- GitHub discovery uses DeepSeek-Harness-specific topic intersections instead of the broad `dsh-plugin` topic alone.
-- npm/GitHub candidates must declare a root `dsh.bundle.patch` before the UI exposes **Install** or the fallback command.
-- Candidates that are not valid DSH bundles are removed before totals, sorting, pagination, and rendering.
-- npm/GitHub source counters represent verified installable bundle candidates rather than raw keyword/topic cardinality.
-
-## Popularity evidence
-
-- npm download counts come from npm package/download metadata.
-- GitHub stars are taken from GitHub discovery when the result already contains them.
-- If a visible npm-discovered plugin has a GitHub repository but no star count, the client requests the missing repository statistics **after the Browse result is rendered**.
-- Async star lookup is cached and limited to visible results; failures are ignored rather than failing Browse.
-
-## Sorting
-
-Sorting criteria are independent and composable:
-
-- **Stars**
-- **Downloads**
-- **Freshness**
-- **Name**
-
-Clicking a criterion cycles:
-
-```text
-off → descending → ascending → off
-```
-
-The order in which criteria are enabled defines priority.
-
-## Compatibility
-
-- DSH: `>=0.1.7-rc.2 <0.2.0`
-- Tested with DSH `0.1.7-rc.2`
-
-Exact package compatibility is read from package metadata when a publisher declares it. Installation is validated again by the native DSH Plugin Manager.
-
-## Security
-
-Browser-editable source settings never contain credentials.
-
-Host protections include:
-
-- HTTP(S)-only source URLs;
-- rejection of URL-embedded credentials;
-- blocking of loopback, link-local, private, multicast, reserved, and other non-global-unicast destinations by default;
-- DNS pinning and redirect destination revalidation;
-- source, response-size, result-count, concurrency, and RPC-size limits;
-- Host-controlled allowlists for private sources and environment-based bearer tokens;
-- install-spec validation before a command is exposed or sent to the Plugin Manager.
-
-The Install action executes third-party code through the native DSH Plugin Manager. Review the source and package before installation.
-
-## Host configuration
-
-```yaml
-- id: registry-aggregator
-  name: '@stolyarovmn/dsh-ui-registry-aggregator'
-  config:
-    timeoutMs: 10000
-    maxResponseBytes: 2097152
-    maxPlugins: 2000
-    maxSources: 20
-    maxTotalPlugins: 5000
-    maxRpcBytes: 4194304
-    concurrency: 4
-    privateSourceIds:
-      - corporate
-    auth:
-      - sourceId: corporate
-        tokenEnv: DSH_CORPORATE_REGISTRY_TOKEN
-```
-
-## Development
-
-```sh
-npm install
-npm test
-npm run test:pack
-```
+Then open **Plugins → Installed → Registry Aggregator** and verify **Sources**, **Browse**, installation, compatibility filtering, download statistics, and **Updates** in the real Harness UI.
 
-## License
+## Historical lines
 
-MIT
+- `dsh-0.1.7` — stable `v0.4.17` line for DSH `0.1.7-rc.2`.
+- `dsh-0.1.5` — historical DSH `0.1.5-rc.3` compatibility line.
+- `main` — neutral project landing branch.