why-broke is a command-line utility designed for causal debugging of build failures in JavaScript/TypeScript projects. It tackles the common problem of "it worked yesterday, but not today" by detecting subtle environmental and dependency changes that conventional version control systems like Git might miss. The tool operates by taking a "good state" snapshot of the system, which includes critical factors like Node.js version, operating system, lockfile hashes, package manifest versions, key configuration files (e.g., `tsconfig`, `webpack`), and essential environment variable keys. When a build subsequently fails, why-broke compares the current "bad state" against the last known good state to pinpoint the root cause, such as silent dependency updates, missing environment variables, or unexpected Node.js version discrepancies. As of version 1.4.2, it incorporates a causal inference engine with specialized detectors for runtime, dependencies, configuration, environment, and Git status. The package is actively maintained and appears to follow a typical semantic versioning release cadence based on its version history. Its primary differentiator is its focus on diagnosing *why* a build failed rather than merely *where* it failed, offering actionable fixes.
npm install why-brokeVerified import paths — ran on the pinned version, not inferred.
This TypeScript example demonstrates installing, initializing, and using `why-broke` to wrap a build command programmatically, typical for CI/CD pipelines or automated development scripts.
Add `.why-broke.json` to your project's `.gitignore` file immediately after initializing `why-broke` to prevent accidental commits.
Manually re-record a verified good state by running `npx why-broke record` whenever you are certain the project is building and running correctly.
Corroborate findings from the `GitDetector` with manual inspection of `git status` and `git log` for a more certain diagnosis regarding Git-related drift.
Install `why-broke` globally via `npm install -g why-broke` or as a dev dependency with `npm install --save-dev why-broke`. Ensure `npx` is available and in your system's PATH.
Run `npx why-broke record` when your project is in a verified working condition to establish a fresh, reliable baseline for future comparisons.
Ensure the user has write permissions in the project root. Avoid running `npm` or `npx` commands with `sudo` unless absolutely necessary, as this can lead to incorrect file ownership and permissions.
No dependency data recorded yet.