safe-dependency-installs

Safe Dependency Installs

Use the local project policy first. This checklist is the fallback when package, dependency, or setup work is involved.

Checklist

1. Identify the ecosystem from project files: README/AGENTS, lockfiles, package-manager config, manifests, and tool versions.
2. Prefer boring, official, repeatable install paths: the existing manager, project-local tools, and the tool's documented setup flow. Avoid global installs or shell startup changes unless the user chooses them.
3. Prefer exact versions for direct installs, high-risk tools, package runners, global tools, and projects without a committed lockfile. In existing projects with a committed lockfile and clear version-range conventions, do not churn the manifest just to change ranges; verify the lockfile diff instead. Avoid floating "latest" installs unless the user explicitly chooses them.
4. Run the basic preflight checks before installing or running downloaded code.
5. For JavaScript package work, prefer scripts-disabled install/restore as the first safety posture (e.g. npm ci --ignore-scripts), then run the narrow rebuild/setup a package actually needs in the foreground. Also prefer dry-run, lockfile-only, or metadata-only modes when useful. Use the flag per command; do not add restrictive project config automatically.
6. Review manifest, lockfile, and config diffs before trusting the new dependency tree.
7. Ask before network, install, global, elevated, destructive, or shell-piped commands.
8. Run lifecycle scripts, rebuilds, generators, and package runners only after the package/version and reason are clear.
9. Verify after install: actual command path/version, lockfile state, audit/signature results when available, and the smallest relevant test/build check.
10. Verify that editor/CLI tool configurations (e.g., ~/.claude/settings.json hooks, .vscode/tasks.json tasks) are free of unexpected auto-run or startup commands.

Basic Preflight Checks

Before an install, package runner, rebuild, generator, or downloaded installer, check:

• •package/tool name matches the user's intent and the official docs or source
• •when a newer version is visible during normal metadata/docs checks, mention it and ask rather than silently changing the version
• •whether lifecycle scripts, native builds, binary downloads, or generated files are involved
• •the expected working directory, and that the command stays project-local unless a machine-level install is chosen

For higher-risk tools, also confirm publisher/maintainer, advisories, dependencies, and integrity/signature — see Inspection Commands below for how.

Inspection Commands

Examples of commands that actually inspect a package instead of only reasoning about it. Use the ones that fit — the right checks depend on the ecosystem and how risky the package is, and some situations call for others. These read metadata and advisories; they do not install or run package code.

npm / JavaScript:

• •npm view <pkg> — latest version, maintainers, repo, license, deprecated flag.
• •npm view <pkg>@<ver> time.modified dist.integrity dist.tarball — publish date plus the integrity hash and tarball URL to cross-check the lockfile. A version published very recently, or a long-dormant package suddenly republished, is worth a second look.
• •npm view <pkg> maintainers repository.url — who can publish, and where the source lives.
• •npm pack <pkg> --dry-run — list the files the tarball would write, without installing.
• •npm install <pkg> --dry-run — preview the dependency and lockfile changes.
• •npm audit — known advisories for the resolved tree.
• •npm audit signatures — verify registry signatures and provenance attestations.

Source and advisories:

• •gh repo view <owner>/<repo> — activity, stars, archived or deprecated status of the source repo.
• •gh api "/advisories?ecosystem=npm&affects=<pkg>" — GitHub Advisory Database.

Other ecosystems (same idea, metadata first):

• •Python: pip index versions <pkg>; the PyPI JSON at https://pypi.org/pypi/<pkg>/json; pip install <pkg> --dry-run.
• •Homebrew: brew info <formula> and brew deps --tree <formula> to see the real blast radius before installing.
• •Cargo: cargo info <crate>; cargo audit when available.
• •Go: go list -m -versions <module>; pkg.go.dev.
• •Downloaded installers: shasum -a 256 <file> against the published checksum, and gpg --verify when a signature exists — read the script before ever piping it to a shell.

Preview The Full Install Path

Before installing system tools, native dependencies, CLIs, package managers, or anything likely to change the machine, preview the whole path:

• •official install method and package manager
• •likely prerequisites and system-level dependencies
• •native build or language runtime requirements
• •whether dependencies are installed automatically or must be installed manually
• •expected disk/machine impact when knowable
• •verification command
• •cleanup or reversal path when practical

Do not make dependency work "safer" by inventing a fragile manual path. If scripts-disabled or manual/source/step-by-step setup requires discovering and installing prerequisites mid-flow, pause and prefer the official supported path with user approval unless there is a concrete reason not to.

Compare total blast radius, not just script risk. A normal Homebrew/package-manager install can be safer than a manual chain that pulls in Ruby, OpenSSL, compilers, or source builds one piece at a time.

Locked Installs And Skipped Scripts

Treat a fresh clone with a committed lockfile differently from adding a new dependency.

When the manifest and lockfile are already committed and in sync, the lockfile is the trust baseline. For npm-style projects, a safer restore flow can be:

1. Prefer installing the locked tree with scripts disabled — npm ci --ignore-scripts (or just npm ci if the project's .npmrc already disables scripts).
2. If the project needs a skipped build, native compile, binary link, generator, or CLI setup step, run the narrow required follow-up command for the already-locked package or project script.
3. Prefer visible/manual script execution when supported, such as a targeted rebuild with foreground scripts, instead of rerunning a broad install with all scripts silently enabled.
4. Explain the difference plainly: "The dependency versions are already pinned by the lockfile. This next command runs the required build/setup step that was skipped."
5. Verify the result with the smallest useful command.

Do not turn this into a full package review again unless the lockfile changed, the package is new, the command reaches outside the project, or the script asks for credentials, elevated permissions, shell profile changes, or remote deployment.

Handoff After Setup

When dependency work, scaffolding, or setup is complete, end with a short user handoff:

• •What changed: packages, lockfiles, config, generated files, skipped scripts, or manual follow-up commands.
• •Fresh-clone install: the exact command to restore dependencies safely with scripts disabled (e.g. npm ci --ignore-scripts), plus the follow-up rebuild/setup command for any package that needs it.
• •Day-to-day start: the normal command(s) to run the project, such as npm run dev, pnpm dev, npx expo start, npm run ios, or the repo's actual script names, plus any required working directory.
• •Any one-time setup still needed: environment variables, local services, native rebuilds, database migrations, credentials, or account login.
• •What was verified: build, test, typecheck, import, CLI version, app launch, or why verification was not run.
• •Any safety note that matters next time, such as which packages need a rebuild/setup step after a scripts-disabled install.
• •Whether a newer package/tool version was noticed and left unchanged because the user did not choose an upgrade.
• •Ask whether the user wants the agent to start the dev server/app now.
• •Ask before adding these instructions to an existing README or creating a README when one is missing.

Red Flags

• •curl ... | sh, wget ... | bash, remote install scripts, or unsigned installers.
• •Casual npx, pnpm dlx, bunx, pip install, brew install, or global npm installs without version/source review.
• •New postinstall/preinstall/prepare hooks, native build files (e.g. binding.gyp / node-gyp), credential prompts, shell profile edits, or broad permission requests.
• •Switching package managers or replacing a lockfile without an explicit reason.
• •Manual/source install paths that quietly expand into multiple system dependencies, language runtimes, compilers, or large native packages when the official path is simpler and documented.