Skip to content

fix(apps): install npm deps where a node backend's package.json lives - #30460

Merged
bolichen97 merged 1 commit into
mainfrom
fix/10583-node-backend-subdir-npm-install
Nov 5, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/10583-node-backend-subdir-npm-install

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Node app whose backend keeps its own package.json in a subdirectory starts on the first enable, with its npm dependencies installed, instead of failing with ERR_MODULE_NOT_FOUND.

The app in the issue declares backend/dist/server.js as its entry point and lists its dependencies in backend/package.json. An install never copies node_modules, and the gateway's own npm install before a Node backend start looked only at the app root's package.json. So backend/node_modules was never created, and the backend exited at once with ERR_MODULE_NOT_FOUND on every start. npm's exit status was not read either, so a failed install left nothing in the log.

Why it matters

Every Node backend laid out as its own package in a subdirectory fails on every start until the user runs npm install by hand inside the installed copy in the data home. Nothing in the gateway log points there, so the cause is hard to find.

Not a goal

  • Running setup.onInstall on a local-path install. The docs say it is not run there; whether it should be, and behind which gate, is a maintainer decision that fix(apps): run setup.onInstall on local-dir installs and gate enable on it #10599 proposes an answer to. This PR does not change it.
  • Running onEnable before the backend starts. That order is documented and stays.
  • Changing the npm flags, the timeout or the sandbox the install runs in.

What changed (motivation → approach → change)

A Node backend with a package.json beside its entry point in a subdirectory gets its dependencies installed before it starts.

The cause was that the gateway's pre-start install checked only <app>/package.json. Node looks an entry's imports up in the node_modules of every directory above the entry, so before a Node backend starts the gateway takes those directories, from the app root down to the entry's own, and runs the same sandboxed npm install --production in each one that has a package.json and no node_modules. The root keeps its install and backend/ gets one too. The directories come from the resolved entry path, so a candidate is never above the app root.

A non-zero npm exit is logged as a warning that names the app, the directory and the exit code, and the backend still starts, as it does when npm cannot run at all. The manifest reference documents the install, including that it is how a local-path install gets its npm dependencies.

Backwards compatibility

Compatible: the app-root install runs as before; the only added work is an install in a directory on the entry point's path that has a package.json and no node_modules, which got none before.

Removes nothing: no path, key, check or record is taken away; the start still goes ahead whatever npm does.

Tests

  • test_npm_installs_the_root_and_the_entry_points_own_package_directory: with a package.json at the root and in backend/, an entry at backend/dist/server.js runs npm twice, in the root first and then in backend/.
  • test_npm_never_runs_above_the_app_root: an entry point spelled through .. back into the root still spawns, and the package.json in the directory above the root is never installed.
  • test_a_nonzero_npm_exit_is_logged_and_the_spawn_goes_ahead: npm exiting 1 logs a warning naming the exit code, and node is still spawned.
  • The existing root-install, skip-when-node_modules-exists and failed-install tests pass unchanged.

Proof: PROVEN test/test_apps_backend_coverage_dispatch.py::TestNodeDispatch::test_npm_installs_the_root_and_the_entry_points_own_package_directory, test/test_apps_backend_coverage_dispatch.py::TestNodeDispatch::test_a_nonzero_npm_exit_is_logged_and_the_spawn_goes_ahead (head d8319ad)

Determinism: the three new tests passed 20 runs at -n0 and 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 beside test_apps_backend_coverage_boot.py and test_apps_backend_coverage_stop.py; the whole file passed in a shuffled order (seed 21983). test_npm_never_runs_above_the_app_root passes on main too: it pins that the new walk stays inside the app root.

Manual verification

N/A — unit coverage sufficient: the change is which directories the existing sandboxed install runs in and a log line; the tests drive the real spawn body up to the process launch.

Screenshots / video

N/A — no user-visible frontend surface is touched.

Related Issues

Closes #10583

Sibling sweep

Swept: git grep -nE '"npm"|npm_bin|_find_npm_binary|package.json' -- 'src/kiro_crew/apps/.py' 'src/kiro_crew/apps/**/.py'
Sibling: src/kiro_crew/apps/registry.py:137 -- not affected -- the clone-time build step runs before the copy, which drops node_modules, so runtime dependencies come only from the pre-start install changed here

Pattern harvest

Not generalizable: the one runtime npm installer assumed the npm project sits at the app root; no second installer makes that assumption.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 5, 2026 14:33
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision d8319ad3653babe5b7bf8e059889fbff4234ca19 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d8319ad3653babe5b7bf8e059889fbff4234ca19 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. The change fixes the cause: the pre-start install assumed the npm project sits at the app root.

Notes

  • Item 3 — rides along: reading npm's exit code is not needed to fix ERR_MODULE_NOT_FOUND. It is declared and small: "npm's exit status was not read either, so a failed install left nothing in the log."

What this change ships

Inventory (4 items) — 3 justified

Intent: a Node app whose backend has its own package.json in a subdirectory starts on first enable. This is a FIX for #10583.

  1. Before start, npm installs in every directory with a package.json from the app root down to the entry point's own directory, not only the root — justified
  2. No install runs above the app root, even when the entry point is spelled with .. — justified
  3. A non-zero npm exit is now logged as a warning naming the app, directory and exit code — rides along
  4. The manifest reference explains the pre-start install and how a local-path install gets its npm dependencies — justified

[FIRST-PRINCIPLES-REVIEWED] d8319ad

Description read

[DESCRIPTION-READ] e532548c1e93f3f7a8d7da5eafe407de25fda66e41c5d8df8bc67a9fc696e760

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of d8319ad3653babe5b7bf8e059889fbff4234ca19 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change fixes the root cause. The pre-start install now finds every package.json on the entry point's path, not only the root's, and keeps the same sandbox, flags and fail-open start.

Notes

  • Each install still has its own 120s timeout, so an app with a root and a backend/ package can now hold up backend start for about 240s on a slow network. A user can recover from this, but the doc paragraph should say so.

[DESIGN-REVIEWED] d8319ad

Description read

[DESCRIPTION-READ] 63af4e992cf59817d4b090672d3c33ac00dc07cef3d6b89ca15a79e9850dc183

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of d8319ad3653babe5b7bf8e059889fbff4234ca19 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d8319ad

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d8319ad3653babe5b7bf8e059889fbff4234ca19 false-positive: <reason, 20 to 500 characters>

@bolichen97
bolichen97 enabled auto-merge (squash) November 5, 2026 14:43
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed d8319ad3653babe5b7bf8e059889fbff4234ca19 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] d8319ad

Verdict parsed from the review's SHA-scoped output markers for commit d8319ad3653babe5b7bf8e059889fbff4234ca19.

False positive or not applicable? A repository writer can comment:
/ai-review override fable d8319ad3653babe5b7bf8e059889fbff4234ca19 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 5, 2026

@buluoray buluoray left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

Approve. A Node app that keeps its backend as its own package (for example backend/dist/server.js with backend/package.json) now gets backend/node_modules before it starts. Before this change it failed every start with ERR_MODULE_NOT_FOUND. A failed npm run now also leaves a warning with the directory and exit code.

What I checked on d8319ad:

  • Inside the app directory: the candidate directories are the resolved entry's parents, filtered to the resolved app root and the directories below it. The entry itself is already refused upstream by file_entry_point_refusal if it resolves outside the root, so this is a second fence. Dropping the filter makes test_npm_never_runs_above_the_app_root install in the directory above the root.
  • Same restrictions: each run uses the same wrap_argv(..., mode="standard"), cgroup ceiling, env, flags and 120s timeout as before. Only cwd changes, and only to directories inside the app.
  • Root-level apps unchanged: for an entry at the root the walk is just the root, with the same skip-when-node_modules-exists rule. The existing root-install, skip and failure tests pass unchanged.

Evidence: test_apps_backend_coverage_dispatch.py gives 49 passed. I ran three mutations, one at a time, and each reddened a named test:

  • Containment filter removed: test_npm_never_runs_above_the_app_root failed.
  • Root-only walk: test_npm_installs_the_root_and_the_entry_points_own_package_directory failed.
  • Exit-code warning removed: test_a_nonzero_npm_exit_is_logged_and_the_spawn_goes_ahead failed.

CI is green: 77 success, 16 skipped, PR Readiness success. Merge-tree against main is clean. I did not run a real npm install or the full suite. Windows and macOS were checked against source only.

Non-blocking follow-up: each package directory has its own 120s budget, so an app with several on its entry path can wait a few minutes before its backend starts. Only that app is affected, because the wait sits under its own lifecycle lock. The manifest reference could say so.

@bolichen97
bolichen97 merged commit 087043e into main Nov 5, 2026
134 of 140 checks passed
@bolichen97
bolichen97 deleted the fix/10583-node-backend-subdir-npm-install branch November 5, 2026 20:03
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 5, 2026
buluoray pushed a commit that referenced this pull request Nov 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

setup.onInstall command not executed during app installation

2 participants