npm-safe-forDSH

npm-safe-forDSH re-architects the local-first npm supply-chain security engine
@npm-safe/core as a DeepSeek Harness (dsh) tool plugin. AI agents can
call package security scans directly inside a conversation, acting as a
"check before you install" gate. The engine's full capability — checking,
search, watchlist, refresh, rules, settings, and CI gate scans — is mapped to
14 dsh tools, including a background refresh_all job.

Original Repository

• This repository: https://github.com/nisconder/npm-safe-forDSH
• Original engine repository (read-only reference for @npm-safe/core source): https://github.com/nisconder/npm-safe
• dsh platform (DeepSeek Harness): https://github.com/deepseek-ai/deepseek-harness

Quick Start

Requires Node.js 22.19 or later and pnpm 11.7.0 (via Corepack).

corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm install

better-sqlite3 build allowlist: better-sqlite3 is a native module and
pnpm 11 blocks its build scripts by default. Allowlist is configured in
pnpm-workspace.yaml (pnpm.onlyBuiltDependencies / allowBuilds) and
.npmrc (only-built-dependencies[]=better-sqlite3). If still blocked, run
pnpm approve-builds and select better-sqlite3.

Static verification (build first so the plugin can resolve
packages/core/dist):

pnpm run build
pnpm run typecheck
pnpm run test

One-shot smoke tests (network required — hits the live npm registry):

node scripts/smoke.mjs lodash                  # prints level / score / findings
node scripts/smoke.mjs definitely-not-real-xyz # missing package → exists:false
node scripts/smoke-facade.mjs                  # watchlist / settings / ciScan

Installation

Both packages are published to the npm registry:

pnpm add @npm-safe/core-dsh           # engine
pnpm add @npm-safe/dsh-tool-npm-safe  # dsh plugin

The original @npm-safe/core belongs to the
npm-safe repository and is
untouched by this fork.

• Source & releases: https://github.com/nisconder/npm-safe-forDSH
  (latest release)
• Engine original repository (read-only reference):
  https://github.com/nisconder/npm-safe

Build from source

Follow the Quick Start steps above to install dependencies and
build the workspace:

corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm install
pnpm run build

After building, the engine output lives in packages/core/dist and the dsh
plugin output in packages/tool-npm-safe/lib. Reference them via pnpm
workspace links or point your tooling at the built paths directly.

Using the plugin in a dsh runtime

DEEPSEEK_API_KEY is required. Export it in your environment or place it
in a .env file at the project root before launching dsh.

pnpm dsh web --patch ./packages/tool-npm-safe/cordis.patch.yml
# Web UI: http://127.0.0.1:3080 — ask "check lodash"

# Or run headless:
pnpm dsh --profile headless "check lodash"

All dsh peer packages must belong to the same RC family (@deepseek-ai/dsh-tools
/ dsh-jobs-local 0.1.0-rc.x, @deepseek-ai/cordis ^4.0.1). Upgrades must
stay aligned across the whole repo.

Using the engine as a library

import { NpmSafeEngine } from "@npm-safe/core-dsh";

const engine = new NpmSafeEngine();
const result = await engine.checkPackage("lodash");
console.log(result);
await engine.close();

Tools

The @npm-safe/dsh-tool-npm-safe plugin registers the following tools in a
dsh session:

Architecture

A pnpm workspace monorepo with two packages:

npm-safe-forDSH/
├── package.json                 # Private root: pnpm@11.7.0, aggregate scripts
├── pnpm-workspace.yaml          # workspace = packages/*; better-sqlite3 allowlist
├── tsconfig.base.json           # Shared strict TS config
├── .npmrc                       # only-built-dependencies[]=better-sqlite3
├── .github/workflows/ci.yml     # Node 22.19 + 24 matrix: build → typecheck → test
├── scripts/
│   ├── smoke.mjs                # checkPackage smoke (live registry)
│   └── smoke-facade.mjs         # watchlist / settings / ciScan smoke
└── packages/
    ├── core/                    # @npm-safe/core-dsh engine (CLI/desktop/telemetry stripped)
    └── tool-npm-safe/           # @npm-safe/dsh-tool-npm-safe plugin (14 tools)

CI

.github/workflows/ci.yml runs on every push / PR: Node 22.19 and 24 matrix,
Corepack enabled, pnpm install → pnpm run build →
pnpm run typecheck → pnpm run test.

Manual dsh Verification

End-to-end verification in dsh (Web UI / headless) needs the dsh CLI and an API
key. The plugin is not published to npm yet, so cordis.patch.yml — which
names @npm-safe/dsh-tool-npm-safe — cannot be resolved until it is published.
For local verification, mount the plugin source directly with a temporary patch.

Configure the API key in a root .env file:

# DEEPSEEK_API_KEY=sk-...

Create a temporary local patch at the repo root (replace <abs> with the repo's
absolute path):

# local.patch.yml
- insert:
    - id: tool-npm-safe
      name: 'file://<abs>/packages/tool-npm-safe/src/index.ts'

Run headless (verified working on 0.1.0-rc.6):

pnpm dlx @deepseek-ai/dsh@0.1.0-rc.6 --profile headless \
  --patch ./local.patch.yml \
  "Use the check_package tool to check lodash"

Once the plugin is published, cordis.patch.yml can be used directly:

pnpm dsh web --patch ./packages/tool-npm-safe/cordis.patch.yml
pnpm dsh --profile headless "check lodash"

All dsh packages are pinned to the same RC family (0.1.0-rc.6, cordis
^4.0.1). Upgrades must stay aligned across the whole repo.

Documentation

• packages/core/API.md — engine API reference
• packages/core/ARCHITECTURE.md — engine architecture
• packages/core/SCANNER_RULES.md — scanner rules reference

License

Apache-2.0 — Copyright 2026 Nisconder, InfiniteScope, Escap1ng, StoryBegins.