@kushankurdas/npm-sentinel 0.1.0

package/docs/commands/baseline.md

@@ -0,0 +1,104 @@
+# Command: `baseline`
+
+**Syntax:**
+
+```bash
+npm-sentinel baseline save [flags]
+npm-sentinel baseline diff [flags]
+```
+
+## What “baseline” means here
+
+A **saved snapshot** of your **trusted** dependency picture for **watched** packages only:
+
+- **Watched packages** = names from root `package.json` **`dependencies`**, **`devDependencies`**, **`optionalDependencies`**, **`peerDependencies`**, plus **`watchPackagesExtra`**, or **`watchPackagesOverride`** if set (`lib/config.js`).
+- For each watched name that **resolves** in the lockfile, the snapshot stores:
+  - **Resolved version**
+  - **Direct dependency names** of that package in the tree (children in lockfile)
+  - **Lifecycle script keys** from the registry **packument** for that name at that version (`preinstall`, `install`, `postinstall`, etc., summarized in `lib/packument.js`)
+
+Default file: **`.npm-sentinel-baseline.json`** (override with `--baseline-file`).
+
+## `baseline save`
+
+### Behavior
+
+1. Requires **`package-lock.json`** — otherwise exits **2**.
+2. Loads `package.json`, config, lockfile; computes **`watchNames`**.
+3. For each watched package, **`buildBaselineSnapshot`** (`lib/baseline.js`) resolves the package in the lockfile and **fetches** version metadata from the registry (needs **network**).
+4. Writes JSON snapshot; prints path and count of watched packages (or JSON with `ok`, `path`, `snapshot` if `--json`).
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | Snapshot written. |
+| **2** | Missing lockfile or other failure. |
+
+### How to test
+
+```bash
+cd /path/to/your-app   # has package.json + package-lock.json
+npx npm-sentinel baseline save
+git add .npm-sentinel-baseline.json
+```
+
+Verify the file exists and lists expected packages under **`packages`**.
+
+Use **`--baseline-file /tmp/test-baseline.json`** in throwaway dirs.
+
+---
+
+## `baseline diff`
+
+### Behavior
+
+1. Loads baseline (default path). If **missing**, prints hint and exits **2**.
+2. Requires **`package-lock.json`** — otherwise exits **2**.
+3. Recomputes **`watchNames`** from **current** `package.json` + config.
+4. **`diffAgainstBaseline`** (`lib/diff-signals.js`): for each watched package that existed in the saved baseline, compares saved state vs **current** lockfile + **current** registry scripts.
+
+### Signal types
+
+| `type` | Typical `severity` | Meaning |
+|--------|-------------------|---------|
+| `missing_resolution` | **error** | Watched package no longer resolves under `node_modules` in the lockfile. |
+| `version_change` | **warn** | Resolved version changed vs baseline. |
+| `new_dependency` | **error** | New **direct** child dependency on the watched package (possible injection). |
+| `dependency_removed` | **warn** | A direct child was removed (account takeover / metadata oddity — can be noisy). |
+| `new_lifecycle_script` | **error** | Registry scripts for this name@version include a lifecycle key not present in baseline. |
+
+Messages and `detail` objects are set in **`lib/diff-signals.js`**.
+
+### Output
+
+- Human: one line per signal, prefixed with `[error]` or `[warn]`, or **“No baseline drift detected.”**
+- **`--json`:** `{ "ok": <no error signals>, "signals": [...] }`
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | No signals **or** only **`warn`** signals. |
+| **1** | At least one **`error`** signal. |
+| **2** | No baseline file, missing lockfile, etc. |
+
+**Note:** **`warn` alone does not fail** `baseline diff`.
+
+### How to test
+
+1. `baseline save` on a known-good tree.
+2. **Version bump:** `npm install lodash@<other-version>` (if lodash is a root dep), then `baseline diff` → expect **`version_change`** (warn).
+3. **New transitive shape:** Upgrade a root dep to a release that adds a **new direct** child on that package (e.g. supply-chain style) → **`new_dependency`** (error).
+4. **Clean run:** Immediately `diff` after `save` with no edits → **no drift**, exit **0**.
+
+Combining with **`check`:** use **`check --baseline`** so vulnerability findings and baseline errors fail one command together ([check.md](check.md)).
+
+## Flags
+
+`--cwd`, `--json`, `--baseline-file` — see [../reference/flags.md](../reference/flags.md).
+
+## Requirements
+
+- **`package-lock.json`** (lockfile v1/v2/v3 supported by `lib/parse-npm-lockfile.js`).
+- **Network** for `save` and for `diff` when comparing **lifecycle scripts** (packument fetch for current versions).

package/docs/commands/check.md

@@ -0,0 +1,92 @@
+# Command: `check`
+
+**Syntax:** `npm-sentinel check [flags]`  
+**Default:** If you run `npm-sentinel` with no subcommand, it runs **`check`** (`bin/cli.js`).
+
+## What it does
+
+Runs the **static** pipeline (no `npm install` / `npm ci` on your machine):
+
+1. **Reads** `package.json` and **`package-lock.json`** in the project root (`--cwd`). Missing either file throws and exits **2**.
+2. **Parses** the lockfile and collects every unique **`(package name, resolved version)`** pair.
+3. **Findings (vulnerability / IOC):**
+   - **OSV** — unless `--offline` or `--no-osv`, POSTs batches to `https://api.osv.dev/v1/querybatch` (npm ecosystem). Each row with matching vulns becomes a finding (`source: osv`).
+   - **Offline IOCs** — **always** evaluated from `lib/offline-iocs.json`: exact name + version matches (`source: offline-ioc`, severity **critical** for filtering purposes).
+   - **`--min-severity`** filters findings (low → critical scale in `lib/merge-findings.js`).
+4. **Baseline (optional):** With **`--baseline`**, if **`.npm-sentinel-baseline.json`** exists under **`--cwd`**, runs **`diffAgainstBaseline`** and appends **signals**. Only the default baseline filename is supported on this code path (see [baseline.md](baseline.md), [gate.md](gate.md)).
+5. **`--npm-audit`:** Spawns **`npm audit --json`** in the project. Results are attached to the output as **`npmAuditFindings`** for display/JSON.
+
+## Output
+
+- **Human:** Count of scanned pairs, list of findings (name, version, source, severity, ids, optional summary), baseline signals, short npm-audit summary (first ~20 entries).
+- **`--json`:** Single object including `ok` (**true** only when no findings **and** no baseline **error**-severity signals), `findings`, `signals`, `npmAuditFindings`, `watchNames`, `packagesScanned`, `cwd`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | No findings after severity filter **and** no baseline signals with **`severity === "error"`**. |
+| **1** | At least one finding **or** at least one **error** baseline signal. |
+| **2** | Missing `package.json` / `package-lock.json`, OSV/network failure, or other thrown error. |
+
+**Note:** **`npm audit` problems do not set exit code 1** by themselves. Only **`findings`** (OSV/IOC) and **baseline error signals** affect success for `check`.
+
+## Flags (summary)
+
+See [../reference/flags.md](../reference/flags.md). Common: `--cwd`, `--json`, `--min-severity`, `--no-osv`, `--offline`, `--baseline`, `--npm-audit`.
+
+## How to test
+
+### Smoke: help and happy path
+
+```bash
+npm-sentinel check --cwd /path/to/project
+```
+
+Use a project with a clean lockfile and no baseline errors — expect exit **0** (or findings if deps are vulnerable).
+
+### IOC / offline path (no OSV)
+
+Use a fixture lockfile that pins a version listed in **`lib/offline-iocs.json`** (e.g. `axios@1.14.1`). This repo’s test uses **`test/fixtures/lock-v3-mini.json`** copied into a temp dir:
+
+```bash
+node bin/cli.js check --cwd /tmp/test-proj --offline --no-osv
+```
+
+Expect exit **1** and output mentioning the IOC package.
+
+### OSV path
+
+Install an old version with a known advisory, ensure **`package-lock.json`** pins it, run **`check`** without `--offline`. Expect findings if OSV has the CVE.
+
+### Severity filter
+
+```bash
+npm-sentinel check --min-severity high
+```
+
+Low/moderate-only findings are dropped; exit **0** if nothing meets the threshold.
+
+### Baseline integration
+
+1. `npm-sentinel baseline save`
+2. Change a watched dependency’s resolved version in the lockfile.
+3. `npm-sentinel check --baseline`
+
+Expect **baseline signals** in output; exit **1** if any signal is **`error`** (e.g. `new_dependency`, `new_lifecycle_script`).
+
+### npm audit attachment
+
+```bash
+npm-sentinel check --npm-audit --json
+```
+
+Inspect **`npmAuditFindings`** in JSON; exit code still follows findings/baseline rules only.
+
+## Typical CI usage
+
+```bash
+npx npm-sentinel@latest check --baseline
+```
+
+Pair with a committed **`.npm-sentinel-baseline.json`** after an intentional `baseline save`.

package/docs/commands/gate.md

@@ -0,0 +1,70 @@
+# Command: `gate`
+
+**Syntax:** `npm-sentinel gate [flags]`
+
+## What it does
+
+A **CI-oriented** orchestration of **static check** and **optional sandbox**:
+
+1. Runs **`runCheck`** with **`withBaselineDiff: true`** always. If **`.npm-sentinel-baseline.json`** exists in the project root, baseline diff runs the same way as **`check --baseline`**.
+
+   **Baseline path limitation:** `runCheck` calls **`loadBaseline(cwd)`** with no custom path (`lib/scan.js`). Only the default filename **`.npm-sentinel-baseline.json`** is loaded for **`check --baseline`** and **`gate`**. The **`--baseline-file`** flag applies to **`baseline save`** / **`baseline diff`** only. For a custom path with static check, the CLI would need a small extension.
+
+2. **Failure (stage `check`):** If **`findings.length > 0`** **or** any baseline signal with **`severity === "error"`**, prints result (human or JSON with `gate: "failed", stage: "check"`), exits **1**.
+
+3. **Success + `--require-sandbox`:** Calls **`cmdSandbox`** with the same `flags` **but forces `json: false`** for the sandbox step — sandbox output is always human-readable even if you passed `--json` to `gate`.
+
+4. **Success without sandbox:** Prints **“Gate OK …”** or minimal JSON with `gate: "ok"`, exits **0**.
+
+## Flags
+
+Inherits **check-related** flags: `--cwd`, `--json`, `--min-severity`, `--no-osv`, `--offline`, `--npm-audit`, plus **`--require-sandbox`**.
+
+Sandbox flags **`--no-build`**, **`--mount-ssh`**, **`--ssh-dir`** apply when **`--require-sandbox`** is set (passed through to **`cmdSandbox`**).
+
+**Note:** There is **no** `--baseline` flag on `gate` — baseline diff is **on by default** when a baseline file is present.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | Check passed (no findings, no baseline **error** signals) and, if requested, sandbox **`ok`**. |
+| **1** | Check failed **or** sandbox failed. |
+| **2** | Thrown error from **`runCheck`** (e.g. missing `package.json` / lockfile). |
+
+## Output (`--json`)
+
+- On check failure: `{ "gate": "failed", "stage": "check", ...fullResult }`
+- On check success without sandbox: `{ "gate": "ok", "stage": "check", "packagesScanned": N }`
+- Sandbox stage does not add JSON when **`--json`** was used (sandbox runs non-JSON).
+
+## How to test
+
+### Static gate only
+
+```bash
+npx npm-sentinel gate --cwd /path/to/project
+```
+
+With no baseline file: behaves like **`check`** without baseline. With baseline: includes diff signals.
+
+### Full gate with sandbox
+
+```bash
+npx npm-sentinel gate --require-sandbox --no-build
+```
+
+Requires Docker; static check must pass first.
+
+### Simulate failure
+
+Introduce an IOC version or baseline **error** (e.g. **`new_dependency`**) and run **`gate`** — expect exit **1** before any sandbox runs.
+
+## When to use vs `check`
+
+| Use **`check`** | Use **`gate`** |
+|-----------------|----------------|
+| Local dev, flexible flags (`--baseline` explicit, no baseline) | CI job that should always consider baseline if present |
+| You never want sandbox | One command: **`gate --require-sandbox`** after tests |
+
+If you need **`--baseline-file`** with **`gate`**, the current implementation may not support it on the **`runCheck`** path; use **`check --baseline --baseline-file …`** until the CLI is extended.

package/docs/commands/help.md

@@ -0,0 +1,28 @@
+# Command: `help`
+
+**Syntax:**
+
+```bash
+npm-sentinel help
+```
+
+**Note:** `npm-sentinel --help` is parsed as **flags** only; the CLI currently dispatches **`check`** before it evaluates `flags.help`, so **`--help` alone may still run `check`** in your tree. Prefer **`npm-sentinel help`** for the usage banner (or `npm-sentinel help` after we reorder dispatch if that gets fixed).
+
+## What it does
+
+Prints a short reference listing **commands**, **flags**, **config** keys, and an example **`preinstall`** one-liner. **Does not** touch `package-lock.json` or network.
+
+## Exit code
+
+**0**
+
+## How to test
+
+```bash
+node bin/cli.js help
+npx npm-sentinel help
+```
+
+Expect the usage banner from `bin/cli.js` (~lines 263–291).
+
+For full documentation, use this **`docs/`** tree and the [main README](../../README.md).

package/docs/commands/sandbox.md

@@ -0,0 +1,101 @@
+# Command: `sandbox`
+
+**Syntax:** `npm-sentinel sandbox [flags]`
+
+## What it does
+
+Runs a **real `npm ci`** inside **Docker** so install **lifecycle scripts** execute in an isolated Linux environment (not on your host). Optionally records **DNS** (UDP port 53) and enforces an **allowlist**.
+
+Implementation: **`runSandbox`** in `lib/sandbox/docker-runner.js` + image `docker/Dockerfile.sandbox` + `docker/entrypoint-sandbox.sh`.
+
+### High-level flow
+
+1. Verifies **`package-lock.json`** exists at `--cwd`.
+2. If **`--mount-ssh`** / **`--ssh-dir`** / config SSH path: resolves mount; errors if path missing.
+3. Runs **`docker info`** — fails if Docker is unavailable.
+4. Unless **`--no-build`**, builds image **`npm-sentinel-sandbox:local`** from `docker/Dockerfile.sandbox`.
+5. **Runs container** with:
+   - Project mounted **read-only** at `/src`, copied to `/work`
+   - **`tcpdump`** on `udp port 53` appended to `/out/dns.log`
+   - **`npm ci`** in `/work` (stdout/stderr → `/out/npm.log`)
+   - Optional: mount host SSH keys for **`git+ssh`**
+6. After the container exits, the CLI reads **`dns.log`**, **`npm.log`**, **`npm-exit.code`**, runs **`extractHostsFromTcpdump`** + **`filterDisallowedHosts`** (`lib/sandbox/dns-parse.js`) using **`resolveDnsAllowlist`** (`lib/sandbox/docker-runner.js`): built-in defaults **`merge`**d with config, or config-only when **`dnsAllowlist.mode`** is **`replace`**.
+
+### Success condition
+
+**`ok`** is true only when:
+
+- **`npm ci`** exit code is **0**, **and**
+- **No** extracted DNS hostname is outside the merged allowlist.
+
+Either failure yields CLI exit **1** (unless preflight errors — see below).
+
+## Output (human)
+
+- Preflight failure: **`res.error`** on stderr (lockfile, Docker, SSH path, docker build).
+- Otherwise: **`npm ci exit:`** code, optional **DNS allowlist violations** list, optional npm log tail on install failure, **“Sandbox OK”** when `ok`.
+
+## Output (`--json`)
+
+Object includes at least: **`ok`**, **`npmExit`**, **`npmLogTail`**, **`dnsHostsSample`**, **`disallowedDns`**, **`sshMounted`**, and on failure **`error`** may be set instead of npm/DNS fields.
+
+Use **`dnsHostsSample`** to debug empty violations (parser/capture issues).
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | `res.ok` — install succeeded and DNS within allowlist. |
+| **1** | DNS violations, `npm ci` failure, or any `ok: false` result. |
+| *(preflight)* **1** | Same exit mapping: `res.ok` false includes `error` string cases. |
+
+**Note:** The entrypoint exits with **`npm ci`’s code** inside the container; the **CLI** still treats non-zero npm or DNS violations as failure.
+
+## Flags
+
+`--cwd`, `--json`, `--no-build`, `--mount-ssh`, `--ssh-dir` — see [../reference/flags.md](../reference/flags.md) and [../reference/config.md](../reference/config.md).
+
+## Limits & caveats
+
+- **Linux image** (`node:20-bookworm-slim`): native addons built for macOS/Windows may **fail** `npm ci` here even when local install works.
+- **DNS parsing** only recognizes certain **tcpdump** line shapes (`A?` / `AAAA?` / `CNAME?` patterns in `dns-parse.js`).
+- **Broad default allowlist** (`lib/dns-allowlist-default.json`): malware using allowed CDNs may **not** trigger DNS violations.
+- **`tcpdump` stderr** is discarded in the entrypoint; silent capture failures can yield **empty** host sets.
+
+## How to test
+
+### Happy path
+
+```bash
+cd /path/to/small-js-project   # valid package-lock.json
+docker info   # ensure daemon is up
+npx npm-sentinel sandbox
+# Second run:
+npx npm-sentinel sandbox --no-build
+```
+
+Expect **Sandbox OK** and exit **0**.
+
+### Force `npm ci` failure
+
+Make `package.json` and `package-lock.json` **out of sync** (add a dependency in `package.json` without updating the lockfile). Run **`sandbox`** → expect non-zero **`npm ci exit`** and log tail.
+
+### Force DNS violation (controlled)
+
+Add a root **`preinstall`** / **`postinstall`** that runs **`require('node:dns').resolve4('example.com', …)`**, run **`npm install`** to refresh the lockfile, then **`sandbox`**. If capture + parser see **`example.com`**, expect **DNS allowlist violations** (see `lib/dns-allowlist-default.json`).
+
+Avoid **`dns.lookupSync`** on Node 25+ (removed); use **`resolve4`** or callback **`lookup`**.
+
+### Private git dependencies
+
+```bash
+npx npm-sentinel sandbox --mount-ssh
+# or
+npx npm-sentinel sandbox --ssh-dir /path/to/deploy-keys
+```
+
+See main README **Docker & SSH** / macOS **UseKeychain** notes.
+
+## Relation to `check`
+
+**`sandbox`** does **not** run OSV or offline IOCs. Use **`check`** (or **`gate`**) for static findings; use **`sandbox`** when you need **install-time behavior** evidence.

package/docs/reference/config.md

@@ -0,0 +1,39 @@
+# Configuration file
+
+Optional. First matching file in the project root (`--cwd`) wins:
+
+1. `npm-sentinel.config.json`
+2. `.npm-sentinelsrc.json`
+
+Parsed as JSON in `lib/config.js`. Invalid JSON yields an empty object for that file.
+
+## Keys
+
+| Key | Type | Used by | Description |
+|-----|------|---------|-------------|
+| `watchPackagesExtra` | `string[]` | baseline, `check --baseline`, `gate` | Add package names to the **watch list** in addition to root `dependencies` / `devDependencies` / optional / peer deps. |
+| `watchPackagesOverride` | `string[]` \| null | same | If set, **replace** the default watch list entirely (only these names are watched). |
+| `dnsAllowlist` | object | `sandbox` | **`mode`** optional: **`merge`** (default) — defaults from `lib/dns-allowlist-default.json` **plus** your `suffixes` / `exactHosts`; **`replace`** — **only** your lists (no built-in suffixes/hosts). Invalid `mode` values behave as **`merge`**. |
+| `sandbox.mountSsh` | boolean | `sandbox` | Same as CLI `--mount-ssh`. |
+| `sandbox.sshDir` | string | `sandbox` | Same as `--ssh-dir`; wins over `mountSsh` when set. |
+
+## Example
+
+```json
+{
+  "watchPackagesExtra": ["some-transitive-parent"],
+  "watchPackagesOverride": null,
+  "dnsAllowlist": {
+    "mode": "merge",
+    "suffixes": ["my-registry.example.com"],
+    "exactHosts": []
+  },
+  "sandbox": {
+    "mountSsh": true
+  }
+}
+```
+
+### Strict allowlist (`replace`)
+
+For a minimal allowlist (e.g. private registry only), set **`"mode": "replace"`** and list every **suffix** and **exact host** your `npm ci` legitimately resolves (often start by copying defaults from `lib/dns-allowlist-default.json`, then trim). Empty **`suffixes`** / **`exactHosts`** under **`replace`** allow **no** names by those rules until you add them.

package/docs/reference/flags.md

@@ -0,0 +1,45 @@
+# CLI flags reference
+
+Parsed in `bin/cli.js` (`parseArgs`). Boolean flags can appear as `--flag` or `--flag=true`-style where noted.
+
+## All commands
+
+| Flag | Type | Applies to | Description |
+|------|------|------------|-------------|
+| `--cwd <dir>` | path | all | Project root; must contain `package.json` (and usually `package-lock.json`). |
+| `--json` | boolean | `check`, `baseline`, `sandbox`, `gate` | Machine-readable JSON on stdout (shape varies by command). |
+| `--help` / `help` | — | `npm-sentinel help` | Prints usage and exits 0. |
+
+## `check` and `gate`
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--min-severity` | `low` | Filter findings: `low`, `moderate`, `high`, `critical`. |
+| `--no-osv` | off | Do not call the OSV batch API. |
+| `--offline` | off | Skip OSV entirely (offline IOCs in `lib/offline-iocs.json` still apply). |
+| `--baseline` | off | **`check` only:** if **`.npm-sentinel-baseline.json`** exists, run baseline diff and merge signals into output. Custom paths are **not** wired into `runCheck` / **`gate`**. |
+| `--npm-audit` | off | Run `npm audit --json` in the project and attach summary to results (**does not** change exit code by itself; see [check.md](../commands/check.md)). |
+
+## `gate` only
+
+| Flag | Description |
+|------|-------------|
+| `--require-sandbox` | After a successful check, run **`sandbox`** (Docker). **`gate` forces `json: false` for the sandbox stage** even if `--json` was passed. |
+
+## `sandbox` only
+
+| Flag | Description |
+|------|-------------|
+| `--no-build` | Skip `docker build`; reuse existing `npm-sentinel-sandbox:local` image. |
+| `--mount-ssh` | Mount host `~/.ssh` read-only at `/root/.ssh` in the container. |
+| `--ssh-dir <path>` | Mount this directory instead of `~/.ssh` (for `git+ssh` deps). |
+
+Config can also set `sandbox.mountSsh`, `sandbox.sshDir`, and `dnsAllowlist` (see [config.md](config.md)).
+
+## `baseline` subcommands
+
+| Flag | Description |
+|------|-------------|
+| `--baseline-file <path>` | Read/write baseline JSON at this path instead of **`.npm-sentinel-baseline.json`**. |
+
+`baseline save` and `baseline diff` also accept `--cwd` and `--json`. (**Not** passed through from `check` / `gate` today.)

package/docs/testing.md

@@ -0,0 +1,19 @@
+# Testing npm-sentinel
+
+End-to-end ideas are split by command so they stay next to behavior and exit codes:
+
+| Goal | Doc |
+|------|-----|
+| Static scan, OSV, IOCs, severity, `npm audit` | [commands/check.md — How to test](commands/check.md#how-to-test) |
+| Baseline save/diff, signal types | [commands/baseline.md — How to test](commands/baseline.md#how-to-test) |
+| Docker `npm ci`, DNS allowlist, SSH | [commands/sandbox.md — How to test](commands/sandbox.md#how-to-test) |
+| CI gate + optional sandbox | [commands/gate.md — How to test](commands/gate.md#how-to-test) |
+
+**This repo’s automated tests:**
+
+```bash
+npm ci
+npm test
+```
+
+Fixtures live under **`test/fixtures/`** (e.g. lockfile mini IOC case in **`cli-smoke.test.js`**).

package/lib/baseline.js

@@ -0,0 +1,83 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  parseNpmLockfile,
+  getRootDependencyResolution,
+} from "./parse-npm-lockfile.js";
+import { fetchVersionScripts, summarizeLifecycleScripts } from "./packument.js";
+
+export const DEFAULT_BASELINE_PATH = ".npm-sentinel-baseline.json";
+
+/**
+ * @param {string} cwd
+ * @param {string} [relPath]
+ */
+export function baselinePath(cwd, relPath = DEFAULT_BASELINE_PATH) {
+  return join(cwd, relPath);
+}
+
+/**
+ * @param {object} pkg
+ * @param {ReturnType<import('./parse-npm-lockfile.js').parseNpmLockfile>} parsed
+ * @param {string[]} watchNames
+ * @param {typeof fetch} [fetchImpl]
+ */
+export async function buildBaselineSnapshot(
+  pkg,
+  parsed,
+  watchNames,
+  fetchImpl = fetch
+) {
+  /** @type {Record<string, object>} */
+  const packages = {};
+
+  for (const name of watchNames) {
+    const res = getRootDependencyResolution(parsed, name);
+    if (!res) {
+      packages[name] = {
+        resolvedVersion: null,
+        directDependencyNames: [],
+        lifecycleScriptKeys: [],
+        scriptHashes: {},
+        missingInLockfile: true,
+      };
+      continue;
+    }
+
+    const scripts = await fetchVersionScripts(name, res.version, fetchImpl);
+    const sum =
+      scripts === null
+        ? { keys: [], hashes: {} }
+        : summarizeLifecycleScripts(scripts);
+
+    packages[name] = {
+      resolvedVersion: res.version,
+      directDependencyNames: [...(res.directDependencyNames || [])].sort(),
+      lifecycleScriptKeys: sum.keys.sort(),
+      scriptHashes: sum.hashes,
+      missingInLockfile: false,
+    };
+  }
+
+  return {
+    version: 1,
+    savedAt: new Date().toISOString(),
+    packages,
+  };
+}
+
+export function loadBaseline(cwd, relPath = DEFAULT_BASELINE_PATH) {
+  const p = baselinePath(cwd, relPath);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function saveBaseline(snapshot, cwd, relPath = DEFAULT_BASELINE_PATH) {
+  const p = baselinePath(cwd, relPath);
+  writeFileSync(p, JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+  return p;
+}

package/lib/config.js

@@ -0,0 +1,49 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const CONFIG_NAMES = [
+  "npm-sentinel.config.json",
+  ".npm-sentinelsrc.json",
+];
+
+/**
+ * @param {string} cwd
+ * @returns {object}
+ */
+export function loadConfig(cwd) {
+  for (const name of CONFIG_NAMES) {
+    const p = join(cwd, name);
+    if (existsSync(p)) {
+      try {
+        return JSON.parse(readFileSync(p, "utf8"));
+      } catch {
+        return {};
+      }
+    }
+  }
+  return {};
+}
+
+/**
+ * @param {object} pkg - package.json parsed
+ * @param {object} config
+ * @returns {string[]}
+ */
+export function getWatchPackageNames(pkg, config) {
+  if (Array.isArray(config.watchPackagesOverride)) {
+    return [...config.watchPackagesOverride].sort();
+  }
+  const extra = config.watchPackagesExtra || [];
+  const root = new Set(
+    [
+      ...Object.keys(pkg.dependencies || {}),
+      ...Object.keys(pkg.devDependencies || {}),
+      ...Object.keys(pkg.optionalDependencies || {}),
+      ...Object.keys(pkg.peerDependencies || {}),
+    ].filter(Boolean)
+  );
+  if (Array.isArray(extra)) {
+    for (const e of extra) root.add(e);
+  }
+  return [...root].sort();
+}