dsh-dep-audit

Name: dsh-dep-audit
Author: zoahdev

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:

Tool	Focus
dsh-poison-guard	malware / obfuscation scan of plugin code
dsh-plugin-doctor	publish readiness: manifest/patch/build/pack/install
dsh-dep-audit	dependency graph hygiene: resolvability, dist-tags, staleness, sources, licenses, drift

Install

dsh plugin add dsh-dep-audit

Or run it standalone without installing into dsh:

npx dsh-dep-audit .

Checks

Check	What it verifies	Status when triggered
`manifest`	`package.json` exists, parses, declares `name` / `version`	fail
`peer-resolvable`	every `peerDependencies` range matches at least one published version on the registry	fail
`dist-tag`	`dist-tags.latest` does not contradict a declared range (the broken-`latest` / ERESOLVE class, e.g. discussion #2763)	warn
`source`	audited dependencies use registry specifiers, not `git:` / `file:` / `link:` / `workspace:`	warn
`license`	registry dependencies declare a license in their latest published metadata	warn
`freshness`	registry dependencies have a release within the last 365 days (configurable)	warn
`drift`	installed versions in `node_modules` satisfy the declared ranges (ERESOLVE / host-shadowing class)	fail
`outdated`	installed versions are not behind the registry `latest`	warn

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

dsh-dep-audit（中文）

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

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

与 zoahdev 安全套件的分工：

工具	定位
dsh-poison-guard	插件代码的恶意/混淆扫描
dsh-plugin-doctor	发布就绪：manifest/patch/build/pack/install
dsh-dep-audit	依赖图卫生：可解析性、dist-tag、过期、来源、许可证、漂移

安装

dsh plugin add dsh-dep-audit

不装进 dsh 也能单独用：

npx dsh-dep-audit .

检查项

检查	验证内容	触发级别
`manifest`	`package.json` 存在、可解析、有 `name` / `version`	fail
`peer-resolvable`	每个 `peerDependencies` 范围在注册表上至少有一个已发布版本	fail
`dist-tag`	`dist-tags.latest` 不与声明范围矛盾（坏 `latest` / ERESOLVE 一类，见讨论 #2763）	warn
`source`	依赖使用注册表来源，而非 `git:` / `file:` / `link:` / `workspace:`	warn
`license`	注册表依赖的最新元数据声明了许可证	warn
`freshness`	注册表依赖在 365 天内有新发布（可配置）	warn
`drift`	`node_modules` 里的实际版本满足声明范围（ERESOLVE / 宿主遮蔽类）	fail
`outdated`	已安装版本不落后于注册表 `latest`	warn

只有所有检查都没有 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 启动冒烟。

许可证

dsh-dep-audit

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

Complements the rest of the zoahdev security suite:

Tool	Focus
dsh-poison-guard	malware / obfuscation scan of plugin code
dsh-plugin-doctor	publish readiness: manifest/patch/build/pack/install
dsh-dep-audit	dependency graph hygiene: resolvability, dist-tags, staleness, sources, licenses, drift

Install

dsh plugin add dsh-dep-audit

Or run it standalone without installing into dsh:

npx dsh-dep-audit .

Checks

Check	What it verifies	Status when triggered
`manifest`	`package.json` exists, parses, declares `name` / `version`	fail
`peer-resolvable`	every `peerDependencies` range matches at least one published version on the registry	fail
`dist-tag`	`dist-tags.latest` does not contradict a declared range (the broken-`latest` / ERESOLVE class, e.g. discussion #2763)	warn
`source`	audited dependencies use registry specifiers, not `git:` / `file:` / `link:` / `workspace:`	warn
`license`	registry dependencies declare a license in their latest published metadata	warn
`freshness`	registry dependencies have a release within the last 365 days (configurable)	warn
`drift`	installed versions in `node_modules` satisfy the declared ranges (ERESOLVE / host-shadowing class)	fail
`outdated`	installed versions are not behind the registry `latest`	warn

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

Development

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

License

dsh-dep-audit（中文）

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

与 zoahdev 安全套件的分工：

工具	定位
dsh-poison-guard	插件代码的恶意/混淆扫描
dsh-plugin-doctor	发布就绪：manifest/patch/build/pack/install
dsh-dep-audit	依赖图卫生：可解析性、dist-tag、过期、来源、许可证、漂移

安装

dsh plugin add dsh-dep-audit

不装进 dsh 也能单独用：

npx dsh-dep-audit .

检查项

检查	验证内容	触发级别
`manifest`	`package.json` 存在、可解析、有 `name` / `version`	fail
`peer-resolvable`	每个 `peerDependencies` 范围在注册表上至少有一个已发布版本	fail
`dist-tag`	`dist-tags.latest` 不与声明范围矛盾（坏 `latest` / ERESOLVE 一类，见讨论 #2763）	warn
`source`	依赖使用注册表来源，而非 `git:` / `file:` / `link:` / `workspace:`	warn
`license`	注册表依赖的最新元数据声明了许可证	warn
`freshness`	注册表依赖在 365 天内有新发布（可配置）	warn
`drift`	`node_modules` 里的实际版本满足声明范围（ERESOLVE / 宿主遮蔽类）	fail
`outdated`	已安装版本不落后于注册表 `latest`	warn

只有所有检查都没有 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 启动冒烟。

dsh-dep-audit

dsh-dep-audit

Install

Checks

CLI

In-harness usage (agent-callable)

Examples

Why it exists

Report envelope

Development

License

dsh-dep-audit（中文）

安装

检查项

CLI

在 harness 内使用（agent 可调用）

为什么需要它

报告结构

开发

许可证

社区评论

dsh-dep-audit

dsh-dep-audit

Install

Checks

CLI

In-harness usage (agent-callable)

Examples

Why it exists

Report envelope

Development

License

dsh-dep-audit（中文）

安装

检查项

CLI

在 harness 内使用（agent 可调用）

为什么需要它

报告结构

开发

许可证

社区评论