PR #62194: fix(plugin-sdk): normalize bundled entry imports on Windows

• Repository: openclaw/openclaw
• Author: mraleko
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/62194

Description (problem / solution / changelog)

Summary

• Problem: Bundled channel setup/runtime entry loading could hand raw Windows absolute paths like C:\... to Jiti, which triggers ERR_UNSUPPORTED_ESM_URL_SCHEME (Received protocol 'c:') on Windows.
• Why it matters: This breaks channel-related setup/config flows on Windows, including the reported Signal/channel config path.
• What changed: Normalize bundled entry module paths to file:// URLs before passing them to Jiti in src/plugin-sdk/channel-entry-contract.ts, and add a focused regression test for the Windows fallback path in src/plugin-sdk/channel-entry-contract.test.ts.
• What did NOT change (scope boundary): No broader plugin loader refactor, no behavior changes for non-Windows platforms, and no changes to channel/plugin manifests or runtime registration logic.

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 #62083
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: The bundled channel entry contract loader passed resolved Windows absolute paths directly into Jiti. On Windows ESM paths, drive-letter paths must be converted to file:// URLs before import/loading.
• Missing detection / guardrail: The main plugin loader already normalized Windows import paths, but the bundled channel entry contract path did not have equivalent coverage.
• Contributing context (if known): The failure surfaced in a setup/config flow that loads bundled channel sidecar entries through src/plugin-sdk/channel-entry-contract.ts.

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: src/plugin-sdk/channel-entry-contract.test.ts
• Scenario the test should lock in: When the bundled channel entry loader resolves a Windows absolute path and falls back to Jiti, it should pass a file:// URL rather than a raw C:\... path.
• Why this is the smallest reliable guardrail: It exercises the actual bundled entry loading seam without requiring a full Windows E2E setup.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Windows channel setup/config flows that load bundled channel entry sidecars no longer fail with ERR_UNSUPPORTED_ESM_URL_SCHEME from raw drive-letter paths.

Diagram (if applicable)

Before:
[channel setup/config load] -> [resolved C:\...\api.js] -> [Jiti gets raw path] -> [ERR_UNSUPPORTED_ESM_URL_SCHEME]

After:
[channel setup/config load] -> [resolved C:\...\api.js] -> [convert to file:///C:/.../api.js] -> [Jiti load succeeds]

Security Impact (required)

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

Repro + Verification

Environment

• OS: macOS host for development; bug targets Windows path handling
• Runtime/container: Node 22 / pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): Signal / channel config flow
• Relevant config (redacted): N/A

Steps

1. Resolve/load a bundled channel setup/runtime sidecar on Windows through src/plugin-sdk/channel-entry-contract.ts.
2. Hit the Jiti loading path with a Windows absolute path like C:\openclaw\dist\extensions\signal\api.js.
3. Verify the loader receives a file:// URL instead of the raw absolute path.

Expected

• Bundled entry loading succeeds without ERR_UNSUPPORTED_ESM_URL_SCHEME.

Actual

• Before the fix, Jiti could receive a raw Windows path and fail with Received protocol 'c:'.

Evidence

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

Human Verification (required)

• Verified scenarios:
  • Added and ran a focused regression test for the Windows bundled-entry Jiti fallback path.
  • Confirmed the exact focused test passes:
    • corepack pnpm test src/plugin-sdk/channel-entry-contract.test.ts
• Edge cases checked:
  • Non-Windows behavior is unchanged because normalization is gated on process.platform === "win32".
  • Existing missing-sidecar error reporting test still passes.
• What you did not verify:
  • I did not run a full Windows end-to-end channel config flow locally.

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)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: Another Windows import surface outside this bundled entry contract path could still miss the same normalization.
  • Mitigation: This PR scopes the fix to the reported seam and adds regression coverage for that seam specifically.

Changed files

• src/plugin-sdk/channel-entry-contract.test.ts (modified, +69/-4)
• src/plugin-sdk/channel-entry-contract.ts (modified, +17/-3)