SDK examples

The repository ships runnable examples under examples/sdk/ — the fastest way to learn the host contract without reading the CLI source.

Clone nodehunter and run any example from the repo root:

pnpm install
pnpm run core:build    # required when importing @nodehunter/core from dist
pnpm tsx examples/sdk/scan/runScan.ts

During monorepo development, TypeScript resolves @nodehunter/core from source via tsconfig paths. At runtime, tsx uses the built package in packages/core/dist/ — run pnpm run core:build once after clone.

Layout

Path	Role
_shared/hostContext.ts	Build HostOperationContext + fixture root
_shared/hooks.ts	ScanRequestHooks (onWalkDebug, onPerfDebug, onSizeNotice)
_shared/envelope.ts	buildAnalysisCommandEnvelope — same shape as CLI --json
fixtures/workspace/	Committed sample monorepo (react semver drift, zod, lodash)
<op>/run*.ts	Runnable script per command
<op>/README.md	Op-specific notes and CLI mapping

Examples by core operation

Every public run* entry point has a dedicated example:

Core API	Example	CLI equivalent
runScan	examples/sdk/scan/runScan.ts	nodehunter scan
runSize	examples/sdk/size/runSize.ts	nodehunter size
runList	examples/sdk/list/runList.ts	nodehunter list
runFind	examples/sdk/find/runFind.ts	nodehunter find <pkg>
runWhy	examples/sdk/why/runWhy.ts	nodehunter why <pkg>
runInspect	examples/sdk/inspect/runInspect.ts	nodehunter inspect
runDeletePreview	examples/sdk/delete/runDeletePreview.ts	Sized preview before confirm
runDeleteRefused	(in runDeletePreview.ts)	Non-interactive without --yes
runDeleteDeclined	examples/sdk/delete/runDeleteDeclined.ts	User answered no at confirm
buildWorkspaceIndex	examples/sdk/workspace/buildWorkspaceIndex.ts	Lower-level inventory (no presentation)

runDeleteExecute is intentionally not demonstrated in examples — hosts must gate execution behind explicit user consent or policy.

Run all read-only examples

pnpm tsx examples/sdk/scan/runScan.ts
pnpm tsx examples/sdk/size/runSize.ts
pnpm tsx examples/sdk/list/runList.ts
pnpm tsx examples/sdk/find/runFind.ts
pnpm tsx examples/sdk/why/runWhy.ts
pnpm tsx examples/sdk/inspect/runInspect.ts
pnpm tsx examples/sdk/workspace/buildWorkspaceIndex.ts
pnpm tsx examples/sdk/delete/runDeletePreview.ts
pnpm tsx examples/sdk/delete/runDeleteDeclined.ts

run* vs buildWorkspaceIndex

Need	Use
Human-style lines, tips, footer timing	runScan, runSize, runList, …
Custom UI, MCP tool, your own JSON	buildWorkspaceIndex + query helpers (findPackage, inspectDuplicates, …)
Identical CLI --json envelope	buildAnalysisCommandEnvelope via _shared/envelope.ts

Fixtures

fixtures/workspace/ contains three projects (apps/web, apps/api, packages/lib) with intentional react version drift for inspect --focus duplicates.

buildExampleHostContext() defaults scan.path to this tree and sets noDu: true so examples behave consistently in CI without relying on GNU du.

Compare with the CLI host

Each example mirrors a file under packages/cli/src/commands/<op>/run.ts. The CLI adds:

• Commander argv → HostOperationContext
• renderHostOutput() → chalk / logger
• canAsk() + Inquirer around delete confirm
• --json serialization on stdout

Core logic is identical.

Safety

• Read-only ops use committed fixtures only.
• Delete examples call preview, refused, and declined — never runDeleteExecute by default.
• Import only from @nodehunter/core (public API). Avoid @nodehunter/core/internal in application code — see SDK exports.

Related

• SDK overview
• Platforms and sizing
• JSON output