lockscript-guard

Detect newly introduced npm lifecycle scripts (preinstall, install, postinstall, prepare) when dependencies change.

lockscript-guard helps teams review lockfile-heavy pull requests by surfacing script changes that can execute during install.

Why this exists

Dependency updates can silently introduce install-time code. Reviewing this manually in large package-lock.json diffs is painful and error-prone.

lockscript-guard turns that diff into a focused report.

Install

npm i -D @gilangjavier/lockscript-guard

Or run without installing:

npx @gilangjavier/lockscript-guard scan

CLI usage

lockscript scan [--lockfile package-lock.json] [--format text|json] [--fail-on-risk medium|high]

lockscript diff --base <git-ref> [--head <git-ref>] \
  [--lockfile package-lock.json] \
  [--format text|json] \
  [--fail-on-change] \
  [--fail-on-risk medium|high]

Example: fail CI if new lifecycle scripts appear

lockscript diff --base origin/main --fail-on-change

Example: fail CI on medium/high risk scripts

lockscript diff --base origin/main --fail-on-risk medium

Library API

import {
  parseLockfile,
  collectLifecycleScripts,
  diffLifecycleScripts,
} from "@gilangjavier/lockscript-guard";

const base = collectLifecycleScripts(parseLockfile(baseLockfileText));
const head = collectLifecycleScripts(parseLockfile(headLockfileText));
const issues = diffLifecycleScripts(base, head);

For AI agents

• Use lockscript diff --base <trusted-ref> --format json.
• If count > 0, inspect issues[] and include only changed packages in your report.
• For strict gates, run with --fail-on-change or --fail-on-risk medium.

Example:

lockscript diff --base origin/main --format json --fail-on-risk medium

For humans

• Run this in dependency-update PRs (Renovate/Dependabot or manual updates).
• Prefer diff over scan in CI, because it focuses on newly introduced behavior.
• If a package is flagged, review the script command and changelog before merging.

Example:

lockscript diff --base origin/main

GitHub Actions example

- name: Detect new lifecycle scripts
  run: npx @gilangjavier/lockscript-guard diff --base origin/main --fail-on-change

License

MIT