Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions content/docs/dev/run.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ lpm run test -- --run
Without `lpm.json`, LPM CLI uses the scripts in `package.json`.
It adds project and workspace executables from `node_modules/.bin` to the command's `PATH`.

If npm is installed beside `node`, a script also finds npm's `node-gyp` command, after the project's executables and before the rest of `PATH`. A script such as `node-gyp rebuild` then runs without `node-gyp` in `devDependencies`, as it does under `npm run`. If `npm_config_node_gyp` names a script, the command runs that script instead. LPM CLI keeps the command in `cache/node-gyp-bin` under the LPM home.

You can run the command from a subdirectory. An ordinary run acts on the nearest directory at or above the current one that has a `package.json` or an `lpm.json`, stopping before your home directory. LPM CLI prints that directory when it is not the current one. Scripts run in that directory, as npm runs them.

| Mode | Behavior |
Expand Down
6 changes: 6 additions & 0 deletions content/docs/packages/install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -527,6 +527,10 @@ Package additions do not run this root lifecycle.
Root scripts are separate from dependency script policy and do not use the dependency sandbox.
There is no `--ignore-scripts` option for install.

A project with a `binding.gyp` file at its root gets the `install` script `node-gyp rebuild` when its manifest names no `install` and no `preinstall` script, as npm gives it. Workspace members follow the same rule. To leave the file unbuilt, set `"gypfile": false` in `package.json`. If no `node-gyp` is available, the install stops and says where it looked.

Root scripts find `node-gyp` in the places [lpm run](/docs/dev/run) describes.

### Commands inside workspace hooks

Workspace lifecycle hooks cannot start another command that needs the same install lock. The child command fails with a parent-installation conflict.
Expand All @@ -548,6 +552,8 @@ lpm rebuild
The executable dependency phases are `preinstall`, `install`, and `postinstall`.
Other detected phases, including dependency `prepare`, do not run during install.

A dependency with a `binding.gyp` file at its root, no `install` script and no `preinstall` script has the `install` script `node-gyp rebuild`, unless its manifest sets `"gypfile": false`. LPM CLI blocks, lists and runs that script like one the manifest names.

| Policy | Behavior |
| --- | --- |
| `deny` (default) | Block unapproved dependency scripts |
Expand Down
22 changes: 20 additions & 2 deletions content/docs/packages/rebuild.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,8 @@ Project capability changes require their own authorization. A script-policy gran

Dry runs retain policy and authorization checks. They skip execution, engine enforcement, and sandbox or native-cache preparation.

A dry run does not ask for the approval that `--no-sandbox` or a weaker sandbox mode needs, because it starts no script. It names that approval and the command that grants it, so the run itself does not stop at a prompt you did not expect.

## Dependency tools and script context

With the default store, each dependency script first finds executables from its own dependencies and peers. Project executables and the inherited `PATH` follow.
Expand All @@ -172,6 +174,8 @@ LPM CLI takes the package from the script package's own dependencies, or else fr

No other package's executable is on that `PATH`, and neither is the project's `node_modules/.bin`. From the inherited `PATH`, LPM CLI keeps the absolute directories that are not under a `node_modules` directory or the project's `.lpm/` directory. The project's own directories stay, such as a Python environment kept in the project. On Windows, the script's shell does not look for a command in the package's own directory. If a script fails there because it needs another dependency's tool, approve the package with [lpm approve-scripts](/docs/packages/approve-scripts). An approved package runs with the full `PATH` described above.

If no package supplies `node-gyp` and npm is installed beside `node`, an approved script finds npm's `node-gyp` after every package's executables and before the inherited `PATH`. The script also gets `npm_config_node_gyp`, which build tools such as node-pre-gyp read. A script that runs on its green label gets both only when its command leads to `node-gyp`. A `node` inside a package does not count: LPM CLI looks beside the first `node` on the inherited `PATH` entries that are outside every `node_modules` directory.

The sandbox permits reads from those installed dependencies. These read grants do not permit writes to dependency tools or their helper packages.

Each script receives its own [npm context](/docs/packages/npm-compatibility#script-execution). `INIT_CWD` remains the directory where the CLI command started.
Expand Down Expand Up @@ -338,12 +342,26 @@ lpm rebuild --dry-run --json
lpm rebuild --json > rebuild.json
```

Dry-run reports contain `success`, `dry_run`, `count`, and `packages`. Each package includes its name, version, scripts, and trust status.
Dry-run reports contain `success`, `dry_run`, `count`, `packages`, and `approvals_required`. Each package includes its name, version, scripts, and trust status. `approvals_required` lists each approval the run itself needs and the dry run did not ask for, with `message`, `requested_scopes`, `project_root`, and `suggested_command`. It is empty when the run needs none.

Live reports contain `success`, `built`, `failed`, and `build_cache` metrics. Security posture fields appear when a security floor or suppression needs reporting.
Live reports contain `success`, `built`, `failed`, `failures`, and `build_cache` metrics. Security posture fields appear when a security floor or suppression needs reporting.

`built` counts packages whose scripts completed successfully in this invocation. Cache reuse has separate metrics.

`failures` has one entry for each package that failed:

```json
{
"name": "bufferutil",
"version": "4.0.9",
"script": "install",
"reason": "exit code 1",
"hints": []
}
```

`script` is the lifecycle script that failed. It is `null` when the build stopped outside its scripts, for example when the package directory is missing. `hints` holds the notes that the terminal output prints under a failed package. LPM CLI also writes one line for each failure to stderr.

Script output goes to stderr. Stdout contains one JSON report, including when a script fails. Failed builds report `success: false` and exit `1`.

During install auto-build, rebuild leaves the JSON report to [lpm install](/docs/packages/install).
Expand Down
6 changes: 3 additions & 3 deletions lib/generated/content-dates.json
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@
},
"dev/run.mdx": {
"published": "2026-05-01T09:47:04+01:00",
"modified": "2026-11-14T23:22:25Z"
"modified": "2026-11-16T16:03:32Z"
},
"dev/task-runner.mdx": {
"published": "2026-05-01T09:47:04+01:00",
Expand Down Expand Up @@ -329,7 +329,7 @@
},
"packages/install.mdx": {
"published": "2026-05-01T09:47:04+01:00",
"modified": "2026-11-14T23:22:25Z"
"modified": "2026-11-16T16:03:32Z"
},
"packages/licenses.mdx": {
"published": "2026-07-03T01:08:02+01:00",
Expand Down Expand Up @@ -377,7 +377,7 @@
},
"packages/rebuild.mdx": {
"published": "2026-05-01T13:51:26+01:00",
"modified": "2026-11-15T03:14:42Z"
"modified": "2026-11-16T16:03:32Z"
},
"packages/release.mdx": {
"published": "2026-07-03T10:46:26+01:00",
Expand Down