dsh-dep-audit

dsh-dep-audit

Dependency supply-chain hygiene audit for DeepSeek Harness (dsh) projects and profiles.

It answers: “can I trust the dependency graph of this dsh plugin / profile?” — peer ranges that resolve to nothing, dist-tags that contradict declared ranges, stale or unlicensed dependencies, non-registry sources, and installed versions that silently drifted from what package.json declares.

Complements the rest of the zoahdev security suite:

Install

dsh plugin add dsh-dep-audit

Or run it standalone without installing into dsh:

npx dsh-dep-audit .

Checks

ok is true only when every check passes (no fail items). Warnings are real signals but not blockers.

CLI

dsh-dep-audit [dir] [options]

  --json               print the machine-readable report
  --offline            skip registry network calls
  --all                include devDependencies
  --registry <url>     npm registry base URL (default: NPM_CONFIG_REGISTRY or registry.npmjs.org)
  --stale-days <n>     warn when latest release is older than n days (default 365)
  --help               show help

Exit codes: 0 all pass, 1 at least one fail, 2 usage/IO error.

npx dsh-dep-audit . --json
npx dsh-dep-audit ~/.dsh/profiles/web --offline

In-harness usage (agent-callable)

After install, ask your dsh agent:

审计一下当前插件的依赖健康：dep_audit，目录指向项目根目录。

Run a dependency audit on this plugin: dep_audit with dir set to the project root.

The agent calls the dep_audit tool (dir, optional options), which returns a dsh-dep-audit/v1 report:

{
  "schema": "dsh-dep-audit/v1",
  "target": ".",
  "offline": false,
  "ok": true,
  "summary": { "total": 8, "pass": 8, "warn": 0, "fail": 0 },
  "checks": [ ... ]
}

Examples

Audit a profile without network access:

npx dsh-dep-audit ~/.dsh/profiles/web --offline

Gate CI on dependency hygiene:

- run: npx dsh-dep-audit .

Why it exists

• pnpm can silently link an older RC into a plugin's peer slot; “loads fine” ≠ “matches the declared peer range”. drift turns that precondition into a checked fact.
• The npm latest dist-tag can point at an old, broken build while next has the real release — dsh plugin add <name> then resolves something unexpected for everyone. dist-tag flags the contradiction before it bites (the discussion #2763 failure class).
• A dependency whose latest release is years old, or that lacks a license, is a red flag in a supply chain that grows by thousands of plugins per week.
• An unlicensed or stale dependency is not malware — that is poison-guard's job. This plugin is the “healthy diet” half of the supply-chain story.

Report envelope

Every check carries { id, status, title, detail, items }; items are { name, issue, level } with level: warn | fail. The schema version (dsh-dep-audit/v1) is stable and machine-readable for CI.

Development

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

CI runs the dsh-plugin-doctor preflight, unit tests, a packed-artifact integration that installs the real tarball and invokes the real dep_audit handler, and a fresh-profile dsh web boot smoke on Windows.

License

MIT © 2026 zoahdev

dsh-dep-audit（中文）

DeepSeek Harness（dsh）项目与 profile 的依赖供应链卫生审计。

回答一个具体问题：“这个 dsh 插件 / profile 的依赖图能信吗？” —— peer 范围在注册表上解析不到、dist-tag 与声明的范围互相矛盾、依赖长期不更新或没有许可证、用了 git/file/workspace 来源，以及安装版本与 package.json 声明悄悄漂移。

与 zoahdev 安全套件的分工：

安装

dsh plugin add dsh-dep-audit

不装进 dsh 也能单独用：

npx dsh-dep-audit .

检查项

只有所有检查都没有 fail 项时 ok 才为 true。warn 是真实信号，但不是硬阻塞。

CLI

dsh-dep-audit [dir] [options]

  --json               输出机器可读报告
  --offline            跳过注册表网络请求
  --all                把 devDependencies 也纳入审计
  --registry <url>     npm 注册表地址（默认 NPM_CONFIG_REGISTRY 或 registry.npmjs.org）
  --stale-days <n>     超过 n 天未发布即告警（默认 365）
  --help               帮助

退出码：0 全过，1 有 fail，2 用法/IO 错误。

npx dsh-dep-audit . --json
npx dsh-dep-audit ~/.dsh/profiles/web --offline

在 harness 内使用（agent 可调用）

装好后对 agent 说：

审计一下当前插件的依赖健康：dep_audit，目录指向项目根目录。

agent 会调用 dep_audit 工具（dir，可选 options），返回 dsh-dep-audit/v1 报告：

{
  "schema": "dsh-dep-audit/v1",
  "target": ".",
  "offline": false,
  "ok": true,
  "summary": { "total": 8, "pass": 8, "warn": 0, "fail": 0 },
  "checks": [ ... ]
}

为什么需要它

• pnpm 可能把旧 RC 静默链进插件的 peer 槽；“能加载”≠“符合声明的 peer 范围”。drift 把这条前置条件变成可核验的事实。
• npm 的 latest dist-tag 可能指向旧坏包，而 next 才是真版本——dsh plugin add <name> 会让所有人解析到意外结果。dist-tag 在踩坑前先标出矛盾（讨论 #2763 的失败类别）。
• 最新版本几年没动、或没有许可证的依赖，在以每周千计增长的插件供应链里都是红旗。
• 没许可证、长期不更新不等于恶意——那是 poison-guard 的事。本插件负责供应链“健康饮食”这一半。

报告结构

每个检查带 { id, status, title, detail, items }；items 是 { name, issue, level }，level 为 warn | fail。schema 版本 dsh-dep-audit/v1 稳定、可给 CI 解析。

开发

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm test:integration

CI 跑 dsh-plugin-doctor 预检、单元测试、打包集成（真实安装 tarball 并调用真实 dep_audit handler）、以及 Windows 上全新 profile 的 dsh web 启动冒烟。

许可证

MIT © 2026 zoahdev

Related ecosystem tools

• dsh-dep-audit - dependency supply-chain hygiene
• dsh-quality-score - plugin quality scorecard + full-registry leaderboard
• dsh-ecosystem - health scan, impact, trend, live dashboard
• dsh-tutorials - bilingual plugin pipeline tutorials

FAQ

• How do I install? dsh plugin add dsh-dep-audit or run the CLI directly (see README).
• Does it need an API key? No.
• Is it read-only? Yes by default; any write/apply is an explicit flag.