dsh-listen-npm

dsh-listen-npm

dsh-listen-npm is an npm package monitor plugin for DeepSeek Harness (DSH). Query any npm package's full info — with daily install counts highlighted — and watch your own packages for version / download changes.

• Full package info: latest version, dist-tags, description, license, author, maintainers, links, publish times, versions, dependencies, README excerpt
• Daily install counts: day / 7-day / 30-day / year download stats with a 30-day daily chart (daily granularity comes straight from the official api.npmjs.org/downloads/range API)
• Watch list: add packages to monitor; the plugin polls on a configurable interval, records snapshots and version changes (see the History tab), and shows download trends
• Model tools: dsh_npm_info, dsh_npm_downloads, dsh_npm_watch
• Bilingual UI (zh/en), follows the host language

中文文档

Preview

A resident npm Monitor button sits in the sidebar footer (right above the settings area) with a capsule for the watch count. The modal has three tabs: Query (search + full detail), Watch, History.

Features

• Query tab — type a package name (or paste an npmjs.com link): debounced suggestions from the registry search API, full detail on Enter / click:
  • Download stats card: latest day / last 7 days / last 30 days / last year (latest reported day is the hero stat; when npm's data lags, the label shows the real date plus the lag in days) plus a 30-day daily bar chart with peak, average line, and per-bar tooltips
  • Basic info: first publish, last update, latest publish (+publisher), total versions, unpacked size, file count, node engines, maintainers
  • dist-tags chips, recent version list (fixed-height scroll), README excerpt (rendered as Markdown)
  • One-click Watch button
• Watch tab — add/remove packages; each row shows the latest version (a plain version number, no "new version" marker), latest-day/7-day downloads with trend vs the previous snapshot, a mini bar chart of the last 7 days of daily installs (days npm has not reported yet show as grey placeholder bars, keeping the dates continuous), and the last-check time
• History tab — snapshot timeline per package (recorded on watch-add and version changes): time, version, latest-day/week downloads, change type
• Entry visibility — the sidebar footer entry follows a Show in menu preference (default on), toggled from Settings → npm Monitor or the top of the Watch tab. When off the entry renders nothing; the host settings page keeps an Open npm Monitor button so the modal stays reachable (both places share one preference source and stay in sync).
• Dialog palette — the modal follows dsh-get-balance: a rgba(0,0,0,.32) scrim with blur(12px) saturate(1.2), a color-mix(bg-layer-1 78%) glass panel with a border-l2 hairline and 14px radius, border-l1 dividers, solid button-primary-fill primary buttons, a semi-transparent button-primary-fill 18% capsule (plus a 30% outline) for the active tab — whitish in dark theme, and unchanged on hover once selected — bg-base inputs and search popover, bg-layer-2 cards, and state-* tokens for status colours.
• Background polling — the poller runs decoupled from the modal; every refreshMinutes (host config, default 10) it refreshes the whole watch list with 1 lightweight dist-tags request + 1 range/last-week request per package (latest-day / 7-day totals and the mini chart's daily series are both derived from it); a new version is recorded into the snapshots / History timeline with no in-UI notification
• Data files — watch list and snapshots persist to $DSH_HOME/dsh-listen-npm.json (atomic writes, .bak on corruption)
• HTTP API — the browser half talks to /dsh-listen-npm/api (trust-fenced POST JSON), so polling never produces command nodes in the conversation; falls back to the command channel on older hosts
• Model tools — dsh_npm_info / dsh_npm_downloads / dsh_npm_watch (list / add / remove / refresh)

Configuration (host config)

registryUrl: https://registry.npmjs.org   # swap for a mirror, e.g. https://registry.npmmirror.com
downloadsUrl: https://api.npmjs.org/downloads
refreshMinutes: 10                        # watch list auto refresh interval

Data notes

• Daily granularity comes from api.npmjs.org/downloads/range; npm aggregates downloads per day with a T+N delay (3-4 days in practice), so the last day with data is not necessarily yesterday.
• Continuity: every series is padded through "yesterday" (local time) — days the API skips inside its window become 0, and days npm has not reported yet become 0 flagged pending (drawn as grey dashed bars, capped at 14 days), so the date axis never stops a few days short. Padded days exist only to keep the calendar continuous.
• Aggregation: latest-day / last-7-day / last-30-day totals count real data days only (window ending on the last day with data), so npm's reporting lag can never deflate them into fake zeros; the tiles show the actual cut-off date (the label reads "Yesterday" only when the data really is that fresh) plus a line naming the days npm has not reported yet.
• Scoped packages (@scope/name) are supported everywhere; the registry path URL-encodes the slash while the downloads API uses it raw.
• The full registry doc is fetched once per query (react ≈ 7 MB) — the curl collector caps at 32 MB.

File structure

├── src/host/*.ts         # host half: index.ts (entry), npm.ts (curl core), ops.ts (op dispatch), store.ts, fence.ts, types.ts
├── src/shared/*.ts       # pure logic shared by both halves (daily.ts: calendar padding)
├── src/client/*.tsx      # browser half (React TSX): plugin.tsx, i18n, styles, rpc, store, poller, components/*
├── lib/index.js          # host half build artifact (tsdown, ESM), committed for git installs
├── lib/client.js         # browser half build artifact (tsdown → __ModuleLoader__ factory), committed
├── lib/types/            # type declarations (tsc -b)
├── scripts/              # verify-client.mjs (host seed-table simulation)
├── tsdown.config.ts      # tsdown config (node half + client bundle banner wrap)
├── tsconfig.json         # solution: tsconfig.host.json / tsconfig.client.json
├── cordis.patch.yml      # bundle patch (plugin row by package name)
├── package.json          # dsh.bundle + dsh.client(web) manifest + peerDependencies
├── README.md             # this file
└── README.zh.md          # Chinese docs

Install

# local development
dsh plugin --profile web add ./dsh-listen-npm

# published: npm / tarball / GitHub
dsh plugin --profile web add dsh-listen-npm
dsh plugin --profile web add ./dsh-listen-npm-0.1.0.tgz
dsh plugin --profile web add github:you/dsh-listen-npm#<sha>

dsh --profile web --dump-config   # verify the config layer
dsh --profile web                 # start (host half needs a restart)

Local dev dependencies: the host loads lib/index.js with native Node ESM resolution for @deepseek-ai/schemastery, @deepseek-ai/dsh-tools, @deepseek-ai/dsh-settings, so the plugin dir must contain a resolvable node_modules (gitignored). Either run pnpm install here, or link the host's flattened packages:

New-Item -ItemType Directory "$PWD\node_modules\@deepseek-ai" -Force
foreach ($p in 'schemastery','dsh-tools','dsh-settings') {
  New-Item -ItemType Junction "$PWD\node_modules\@deepseek-ai\$p" -Target "$env:DSH_HOME\profiles\node_modules\@deepseek-ai\$p"
}

Build

pnpm install
npm run check    # tsc -b (both programs)
npm run build    # tsc -b && tsdown (lib/index.js + lib/client.js)
npm run verify   # simulate the host loading lib/client.js

License

MIT