PR #59306: fix(plugins): fail bundled dep postinstall

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59306

Description (problem / solution / changelog)

Summary

• Problem: bundled plugin runtime dependency restore failures during package postinstall were treated as non-fatal, which could leave published installs missing required plugin packages.
• Why it matters: the update/install could appear successful while Telegram, Discord, or other bundled plugins later failed to load with Cannot find module errors.
• What changed: make bundled plugin postinstall throw a clear install-time error when required bundled runtime deps cannot be restored, and add a regression test for the failing restore path.
• What did NOT change (scope boundary): this PR does not add retry logic or change the separate doctor --fix repair flow.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #59286
• Related #59286
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: scripts/postinstall-bundled-plugins.mjs swallowed nested npm install failures and only logged a warning, so published installs could continue with missing bundled plugin runtime deps.
• Missing detection / guardrail: there was no install-time hard failure for missing required bundled runtime deps; the later doctor detection was not enough to prevent a successful-looking broken install.
• Prior context (git blame, prior PR, issue, or refactor if known): issue #59286 reports this after v4.1 updates when bundled plugin deps were left uninstalled.
• Why this regressed now: bundled plugin runtime deps are restored in a separate postinstall step, so any nested install failure left the package in a partially updated state.
• If unknown, what was ruled out: N/A.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: test/scripts/postinstall-bundled-plugins.test.ts
• Scenario the test should lock in: published/package installs fail with a clear error when restoring bundled plugin runtime deps fails.
• Why this is the smallest reliable guardrail: it exercises the exact postinstall code path without needing a full package-manager integration harness.
• Existing test that already covers this (if any): existing postinstall tests covered successful installs and missing-dep discovery only.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• Package installs now fail loudly with a clear bundled-plugin dependency restore error instead of succeeding and leaving broken bundled plugin loads for runtime discovery later.

Diagram (if applicable)

Before:
[package install] -> [bundled dep restore fails] -> [install still succeeds] -> [plugin load fails later]

After:
[package install] -> [bundled dep restore fails] -> [install fails immediately] -> [user sees actionable error]

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS 26.3 arm64
• Runtime/container: local Node/pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): bundled Telegram/Discord plugin runtime deps
• Relevant config (redacted): N/A

Steps

1. Simulate a published install with bundled plugin runtime deps missing.
2. Force the nested postinstall npm install to fail.
3. Verify the postinstall now throws a clear error instead of returning success.

Expected

• The install fails immediately with a clear bundled-plugin dependency restore error.

Actual

• With this patch, the targeted postinstall path fails immediately as intended.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: reproduced the old non-fatal behavior locally with a forced nested-install failure; confirmed the patched path now throws; ran pnpm test -- test/scripts/postinstall-bundled-plugins.test.ts; ran pnpm check; ran pnpm build.
• Edge cases checked: source checkout skip path remains unchanged; no-op path when no bundled deps are missing remains unchanged; successful restore path still passes.
• What you did not verify: full pnpm test is currently red on an unrelated existing failure in src/tts/status-config.test.ts (provider: \"microsoft\" vs \"auto\"), outside this PR's touched surface.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: package installs that previously limped through a broken bundled-plugin restore will now fail hard.
  • Mitigation: this is the intended safeguard because the installed package was already unusable for affected bundled plugins; the thrown error now names the missing restore specs and underlying install failure.

Additional Notes

• Testing degree: lightly to moderately tested on the touched surface (pnpm check, pnpm build, targeted regression test, full pnpm test attempted).
• AI-assisted: yes.

Made with Cursor

Changed files

• scripts/postinstall-bundled-plugins.mjs (modified, +28/-27)
• test/scripts/postinstall-bundled-plugins.test.ts (modified, +64/-1)