Project health

Understand what LPM CLI examines, how health results affect automation, and which automatic fixes change a project.

Project health combines the state of your manifest, installed packages, runtimes, security posture, tools, and connected services.

lpm doctor turns these areas into named results. Use the report to find the cause of an install or environment problem.

This page explains the health model and common workflows. The command page contains the complete syntax, catalog, and flags.

Understand the health layers

LPM CLI separates core project state from broader machine and service state.

Health layer	Default mode	Full mode adds
Project and install	Manifest, linker mode, `node_modules`, lockfiles, dependency synchronization, local sources, and workspace cycles	Store orphans, `.gitattributes`, and manifest compatibility
Runtime and security	Node.js, Bun, policy extensions, auth storage, vault storage, and Sigstore posture	Sandbox and lifecycle-script policy
Project configuration	`lpm.json` structure, runtime pins, tasks, tools, and services	Tunnel ownership and reachability
Tools and machine	None	Lint, format, TypeScript readiness, plugin versions, global installs, PATH, and shims
Connected services	None	Registry health, registry authentication, and tunnel requests

A healthy project does not require every optional tool or service. LPM CLI emits only the results that apply to the current project.

Choose fast or full health

Run the default health report from the project root:

lpm doctor

The default mode reads local project and LPM CLI state. It does not contact a registry or tunnel service.

Runtime detection can run a bounded node --version process. The default mode does not run lint or format tools.

Run the full report for machine, tool, and service health:

lpm doctor --all

Mode	Use case	Cost
Default	An install, runtime, lockfile, or local project state looks incorrect	Local file access and runtime detection
`--all`	You need a complete environment report or CI evidence	Tool processes, machine inspection, and network requests

The full mode includes every default result. Tool timeouts and network conditions can make it take longer.

Use project configuration

LPM CLI reads lpm.json automatically. You do not need a separate doctor flag.

For example:

lpm.json

{
  "runtime": {
    "node": "22"
  },
  "tunnel": {
    "domain": "my-api.lpm.fyi"
  }
}

The default mode examines the runtime pin and relevant project fields. The full mode also examines the configured tunnel domain.

Doctor reports invalid JSON and unrecognized top-level fields. It also reports runtime or workspace problems that the project configuration creates.

See the lpm.json reference for the complete project configuration.

Interpret health results

Each result has a stable code, a severity, a short name, and current details.

Severity	Meaning	Exit code effect
`pass`	The examined state is healthy or informational	None
`warn`	The state needs attention but does not block the command	None
`fail`	The state is broken or required state is unavailable	Exit code `1`

Warnings keep exit code 0. A report with warnings is not clean, but it has no failures.

The default terminal output hides most passing results. It keeps failures, warnings, linker mode, and active policy extensions visible.

The full terminal output includes passing results. If you need every emitted result from either mode, use JSON.

Find the meaning of a result

Use the stable code from terminal or JSON output:

lpm doctor list --code <CODE>

The catalog describes the result, its possible severities, and the recommended action.

List results by category:

lpm doctor list --category "project state"
lpm doctor list --category runtime --json

Match automation on code. Human-readable names and details can change.

Apply fixes and examine the result again

CAUTION: Save your project changes before you use --fix. The command can change project files and installed dependencies.

Apply fixes from the default result set:

lpm doctor --fix
lpm doctor

LPM CLI applies supported fixes immediately. It does not ask for confirmation.

-y and --yes imply --fix. They currently have the same behavior as --fix.

The fix run reports the results that existed before the fixes. It lists completed actions in fixes_applied.

A successful fix does not change the first report or its exit code. Run doctor again to examine the new state.

Use the full fix mode for fixes from the extended result set:

CAUTION: --all --fix can prune the shared store, update installed plugins, and claim a tunnel domain.

lpm doctor --all --fix
lpm doctor --all

Current automatic fixes

Problem	Automatic action
Missing, mixed, legacy, or unmanaged `node_modules` state	Run lpm install
Missing lockfile or dependency drift	Run lpm install
Missing, stale, or corrupt `lpm.lockb`	Reconcile it with `lpm.lock`
Missing managed Node.js version	Install the selected Node.js version
Missing managed Bun version	Install the selected Bun version
Project-level `node_modules` link	Replace only the link with a real directory
Format result from the full mode	Run `lpm fmt`
Missing `lpm.lockb` rule from the full mode	Update `.gitattributes`
Store orphans from the full mode	Prune unreachable store entries
Unclaimed configured tunnel from the full mode	Claim the domain for the current account
Plugin update from the full mode	Update the installed plugin

Some failures require a user decision. For example, doctor does not add TypeScript or change a tunnel domain that another account owns.

In lpm doctor list --json, a non-null auto_fix value identifies the supported action for that code. A null value means no automatic fix exists.

Use auto_fix before a fix run. Use fixes_applied after the run to find the actions that completed.

Use health results in CI

Create a complete JSON report without changing the project:

lpm doctor --all --json > doctor-report.json

If the CI job must not change the workspace, do not add --fix.

Use these fields for automation:

Field	Meaning
`success`	LPM CLI created the diagnostic report
`no_failures`	No result has `fail` severity
`clean`	No result has `warn` or `fail` severity
`has_warnings`	At least one result has `warn` severity
`checks[].code`	Stable identifier for one result
`fixes_applied`	Actions that completed during this run

success: true does not mean that the project is healthy. Read clean for a warning-sensitive policy. Otherwise, read no_failures.

The process exits with code 1 for failures. Warnings alone keep exit code 0.

If warnings must block CI, require clean: true in the JSON report.

Compare project and registry health

Use lpm doctor for project and environment health. Use lpm health for one registry request.

lpm doctor
lpm health --registry https://registry.example.com

Command	Scope	Project files	Network
`lpm doctor`	Fast project and local environment health	Yes	No
`lpm doctor --all`	Complete project, machine, tool, and service health	Yes	Yes
`lpm health`	One selected registry	No	Yes

For lpm health --json, read the healthy field. A reported unhealthy response can still produce success: true and exit code 0.

Know what doctor does not examine

Project health is a diagnostic layer. It does not replace these focused commands:

Need	Command
Run project tests and type checks	`lpm check`
Examine local certificate trust and expiry	`lpm cert status`
Examine package-store content integrity	`lpm store verify`
Examine dependency vulnerabilities	`lpm audit`
Examine one registry only	`lpm health`

Doctor examines TypeScript readiness in full mode. It does not run the complete project type check.

Common workflows

Diagnose an install problem

lpm doctor
lpm doctor list --code <CODE>

Examine a machine after a toolchain change

lpm doctor --all

Repair supported problems

lpm doctor --fix
lpm doctor

Create a warning-sensitive CI gate

lpm doctor --all --json > doctor-report.json

Require clean: true in the next CI step.