The questions everyone actually asks.

Why doesn't phi run lifecycle scripts by default?

preinstall / install / postinstall in package.json is the single most-abused attack vector in npm. A compromised package can do anything as soon as you install it: download more code, exfiltrate environment variables, drop a backdoor. npm install runs these unconditionally.

phi treats lifecycle scripts as opt-in. Most packages don't need them; the ones that do (esbuild, sharp, native-binding installs) you allow per-package with --allow-scripts esbuild,sharp. This single decision closes the most common supply-chain vector.

How does phi differ from npm audit?

npm audit checks resolved dependencies against npm's vulnerability database after installation. phi does that plus:

• Behavioral pattern matching — regex + AST, looking for malware signatures the audit DB doesn't know about
• Smart, context-aware checks (own-config skip, lifecycle-script scoping)
• OSV lookup (which mirrors GHSA, the source npm audit draws from)
• All checks happen before code is on disk, not after

Can I use phi alongside npm / yarn / pnpm?

Yes — phi reads package.json like the others and writes a separate phi.lock. You can keep your existing package-lock.json / yarn.lock / pnpm-lock.yaml for tools that expect them. phi never modifies them.

phi installs into node_modules/ the same way the others do, so any tool that resolves modules from node_modules/ (your bundler, your test runner, Node itself) just works.

What happens when phi blocks or flags a package I trust?

REVIEW-flagged packages prompt you. Read the report card to see which detector fired and decide.

BLOCKED packages refuse to install entirely. If you genuinely trust the package, you can lower the verdict by inspecting and opening an issue — phi's defaults are conservative and detector tuning is a public process.

What if osv.dev is down or I'm offline?

Network failures are non-fatal. phi prints a warning that advisory data is unavailable and proceeds with just the static detectors. To skip the network call entirely (e.g. air-gapped CI), pass --no-advisories.

Does phi work on Windows?

Yes. The scanner, lockfile, cache, and resolver all work identically on Windows. node_modules/.bin/ shims are written as .cmd files; workspace siblings link as junctions (no admin privilege needed).

What about ARM64 (Apple Silicon, Linux ARM, AWS Graviton)?

Pre-built binaries are published for darwin-arm64 and linux-arm64. The install script auto-detects.

How do I install a private package from a self-hosted registry?

Add a .npmrc to your project (or $HOME) declaring the registry and an auth token. phi reads it the same way npm does:

@my-org:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_PAT}

The ${GITHUB_PAT} placeholder is substituted from your environment, so you can commit the .npmrc safely.

What's not supported?

• Git, file, and tarball dependency specs (git+https://..., file:./local, https://x/y.tgz) — phi warns and skips them in resolution
• Older lockfile formats (npm v6 package-lock.json) — phi reads phi.lock only
• Sandboxed dynamic analysis — phi is static-analysis only at this point

Why isn't there a detector for X?

Likely either it's planned (open an issue), or it produces too many false positives at the regex/AST level (phi is conservative about what fires). The ten detectors are tuned against a 20-package real-world corpus to keep noise low; expanding the set requires the same tuning work.

Is phi production-ready?

v0.1.0 is feature-complete for typical Node.js projects (libraries, monorepos, projects with peer-dep heavy frameworks). It installs the 20-package real-world corpus cleanly with zero false-positive blocks. Expect breaking changes in 0.x as the detection model evolves — pin to a specific version in CI.

Where do I report bugs / feature requests?

github.com/philtechs-org/phi/issues. Especially valuable: false-positive reports against real-world packages, and missed-malware reports against known-bad packages.