diff --git a/content/docs/dev/run.mdx b/content/docs/dev/run.mdx index 3f9dcf25..397202f3 100644 --- a/content/docs/dev/run.mdx +++ b/content/docs/dev/run.mdx @@ -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 | diff --git a/content/docs/packages/install.mdx b/content/docs/packages/install.mdx index b004c7b8..db0250c4 100644 --- a/content/docs/packages/install.mdx +++ b/content/docs/packages/install.mdx @@ -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. @@ -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 | diff --git a/content/docs/packages/rebuild.mdx b/content/docs/packages/rebuild.mdx index 3b015ec4..45a56c44 100644 --- a/content/docs/packages/rebuild.mdx +++ b/content/docs/packages/rebuild.mdx @@ -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. @@ -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. @@ -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). diff --git a/lib/generated/content-dates.json b/lib/generated/content-dates.json index c6381d7d..62d94420 100644 --- a/lib/generated/content-dates.json +++ b/lib/generated/content-dates.json @@ -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", @@ -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", @@ -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",