PR #77842: fix(plugins): explain source-only package diagnostics (#77835)

• Repository: openclaw/openclaw
• Author: hclsys
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/77842

Description (problem / solution / changelog)

Summary

Fixes #77835.

Source-only TypeScript package diagnostics currently say an installed plugin package requires compiled runtime output, but they do not tell operators what action is available. For packages such as @tencent-weixin/[email protected], the missing compiled JS is a publisher packaging issue rather than a local config problem.

This PR makes that diagnostic actionable by telling users to update/reinstall after the publisher ships compiled JavaScript, or disable/uninstall the plugin until then. It also documents the same recovery path in the general plugin docs and WeChat troubleshooting page.

Changes

• src/plugins/package-entry-resolution.ts: extend the missing compiled runtime output diagnostic with user action and scope.
• src/plugins/discovery.test.ts: assert startup/discovery warnings include the actionable guidance.
• src/plugins/install.test.ts: assert install-time rejection includes the same guidance.
• src/cli/plugins-install-config.test.ts: keep official reinstall recovery tolerant of the new longer diagnostic.
• docs/tools/plugin.md and docs/channels/wechat.md: document the publisher-package fix path.

Scout audit

• Audit A (existing helper): reused existing missingCompiledRuntimeEntryMessage; no new classifier/predicate added.
• Audit B (shared callers): one shared diagnostic helper, contract preserved; message text becomes more actionable without changing severity or control flow.
• Audit C (broader rival): no fresh open PR found for #77835 or the exact source-only compiled-output diagnostic.

Real behavior proof

• Behavior or issue addressed: Operators who hit a source-only TypeScript managed plugin package now receive an actionable diagnostic explaining the missing compiled output is a plugin packaging issue and giving update/reinstall or disable/uninstall recovery steps.
• Real environment tested: Local OpenClaw checkout on branch fix/77835-plugin-source-only-actionable-diagnostic, based on origin/main 0c977cd687; repository plugin discovery/install and CLI install-config test shards.
• Exact steps or command run after this patch:
  • pnpm test src/plugins/discovery.test.ts src/plugins/install.test.ts src/cli/plugins-install-config.test.ts src/cli/plugins-cli.install.test.ts
  • pnpm exec oxlint CHANGELOG.md src/plugins/package-entry-resolution.ts src/plugins/discovery.test.ts src/plugins/install.test.ts src/cli/plugins-install-config.test.ts src/cli/plugins-cli.install.test.ts
  • pnpm exec oxfmt --check --threads=1 src/plugins/package-entry-resolution.ts src/plugins/discovery.test.ts src/plugins/install.test.ts src/cli/plugins-install-config.test.ts src/cli/plugins-cli.install.test.ts docs/tools/plugin.md docs/channels/wechat.md CHANGELOG.md
  • pnpm check:changed
• Evidence after fix: Terminal output from after-patch runs:

Test Files  2 passed (2)
Tests  89 passed (89)
Test Files  2 passed (2)
Tests  150 passed (150)
[test] passed 2 Vitest shards in 9.84s

Found 0 warnings and 0 errors.
All matched files use the correct format.
pnpm check:changed exited 0.

• Observed result after fix: Discovery/install diagnostics now include plugin packaging issue and disable/uninstall the plugin; all focused plugin/CLI tests and changed-file guardrails passed.
• What was not tested: Did not install the broken @tencent-weixin/[email protected] package in a live Gateway; verification used repository package discovery/install coverage and docs checks.

Additional real behavior proof after maintainer-bot review

After the initial review requested real plugin output, I reproduced the source-only package shape against this branch with actual plugin install and discovery code paths:

node --import tsx --input-type=module <<'NODE'
# creates a temp plugin package with openclaw.extensions=["./src/index.ts"]
# and no compiled JS, then runs installPluginFromDir() and discoverOpenClawPlugins()
NODE

Observed after-fix output:

scenario=install-source-only-package
install.ok=false
install.error=package install requires compiled runtime output for TypeScript entry ./src/index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, ./src/index.js, ./src/index.mjs, ./src/index.cjs. This is a plugin packaging issue, not a local config problem; update or reinstall the plugin after the publisher ships compiled JavaScript, or disable/uninstall the plugin until then. TypeScript source fallback is only supported for source checkouts and local development paths.
scenario=discover-managed-source-only-package
candidates=<none>
warn:source-only-pack:installed plugin package requires compiled runtime output for TypeScript entry src/index.ts: expected ./dist/index.js, ./dist/index.mjs, ./dist/index.cjs, src/index.js, src/index.mjs, src/index.cjs. This is a plugin packaging issue, not a local config problem; update or reinstall the plugin after the publisher ships compiled JavaScript, or disable/uninstall the plugin until then. TypeScript source fallback is only supported for source checkouts and local development paths.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/channels/wechat.md (modified, +5/-0)
• docs/tools/plugin.md (modified, +6/-0)
• src/cli/plugins-install-config.test.ts (modified, +1/-1)
• src/plugins/discovery.test.ts (modified, +3/-1)
• src/plugins/install.test.ts (modified, +2/-0)
• src/plugins/package-entry-resolution.ts (modified, +1/-1)