[sidecar] Improve CommonJS parity and dependency diagnostics #222

New issue

Closed

opened 2026-06-02 09:43:41 +00:00 by steve · 0 comments

steve commented

2026-06-02 09:43:41 +00:00

Owner

Problem

Electron sidecar plugin loading is intentionally narrower than renderer loading, but sidecar CommonJS behavior and dependency failures should be predictable during the dual-format rollout.

Goal

Improve sidecar CommonJS diagnostics and decide the v1 sidecar local module policy without blocking renderer ESM.

Scope

Decide and document bundled-only sidecar v1 versus preloaded local module graph support.
If local graph support is chosen, preload local require() dependencies before executing the CommonJS wrapper.
Keep hosted sidecar dependencies intentionally narrow: lapis and @lapis-notes/api.
Improve missing dependency diagnostics for sidecar plugins.
Add tests for the hosted facade and local graph behavior or clear bundle-required errors.

Non-goals

Do not expose Svelte, DOM modules, CodeMirror view, or UI packages inside the sidecar.
Do not implement Node ESM sidecar support in this issue.
Do not use async file reads inside synchronous CommonJS require().

Acceptance Criteria

Bundled desktop.cjs sidecar plugins load reliably.
Unsupported sidecar imports fail with clear messages.
Sidecar does not expose renderer UI, Svelte, or CodeMirror-view modules.
Local requires either work through a preloaded graph or fail with a clear bundle-your-plugin message.

Implementation Notes

Recommended v1 policy is bundled-only sidecar plugins unless the preloaded graph loader is completed.
Hosted sidecar facade should stay small and capability-oriented.
Sidecar diagnostics should include host, selected format, and rejected dependency specifier.
Adopt bundled-only sidecar CommonJS for v1. Local relative require() calls must fail with an explicit "bundle your sidecar plugin" diagnostic instead of a generic missing dependency error.
Align sidecar hosted module resolution with the generated sidecar host-module catalogue: support the narrow lapis and @lapis-notes/api aliases only, and keep Obsidian renderer compatibility plus renderer UI/Svelte/CodeMirror modules unavailable.
Pass selected runtime metadata from the API host into the Electron bridge request and wrap sidecar evaluation failures with host/format/entry context so PluginManager diagnostics preserve the rejected specifier.
Update specs and tests for the bundled-only policy, supported sidecar aliases, unsupported renderer imports, and clear local-graph errors.

Suggested Files or Specs To Inspect

spec/src/30-cross-package-contracts/plugin-host-boundary.md
spec/src/20-packages/desktop-electron/index.md
packages/desktop-electron/src-electron/plugin-sidecar-child.ts
packages/desktop-electron/src-electron/generated/plugin-sidecar-host-modules.generated.ts

Validation Commands

pnpm --filter @lapis-notes/desktop-electron check:all
pnpm check:all

Follow-up Tasks

Implementation Summary

Implemented bundled-only Electron sidecar CommonJS v1 diagnostics, narrowed sidecar host-module aliases to lapis and @lapis-notes/api, passed selected runtime metadata through the native bridge, wrapped sidecar evaluation failures with host/format/entry context, added focused API/runtime-validation coverage, regenerated host-module metadata, and updated the runtime/desktop specs.

## Problem Electron sidecar plugin loading is intentionally narrower than renderer loading, but sidecar CommonJS behavior and dependency failures should be predictable during the dual-format rollout. ## Goal Improve sidecar CommonJS diagnostics and decide the v1 sidecar local module policy without blocking renderer ESM. ## Scope - Decide and document bundled-only sidecar v1 versus preloaded local module graph support. - If local graph support is chosen, preload local `require()` dependencies before executing the CommonJS wrapper. - Keep hosted sidecar dependencies intentionally narrow: `lapis` and `@lapis-notes/api`. - Improve missing dependency diagnostics for sidecar plugins. - Add tests for the hosted facade and local graph behavior or clear bundle-required errors. ## Non-goals - Do not expose Svelte, DOM modules, CodeMirror view, or UI packages inside the sidecar. - Do not implement Node ESM sidecar support in this issue. - Do not use async file reads inside synchronous CommonJS `require()`. ## Acceptance Criteria - Bundled `desktop.cjs` sidecar plugins load reliably. - Unsupported sidecar imports fail with clear messages. - Sidecar does not expose renderer UI, Svelte, or CodeMirror-view modules. - Local requires either work through a preloaded graph or fail with a clear bundle-your-plugin message. ## Implementation Notes - Recommended v1 policy is bundled-only sidecar plugins unless the preloaded graph loader is completed. - Hosted sidecar facade should stay small and capability-oriented. - Sidecar diagnostics should include host, selected format, and rejected dependency specifier. - Adopt bundled-only sidecar CommonJS for v1. Local relative `require()` calls must fail with an explicit "bundle your sidecar plugin" diagnostic instead of a generic missing dependency error. - Align sidecar hosted module resolution with the generated sidecar host-module catalogue: support the narrow `lapis` and `@lapis-notes/api` aliases only, and keep Obsidian renderer compatibility plus renderer UI/Svelte/CodeMirror modules unavailable. - Pass selected runtime metadata from the API host into the Electron bridge request and wrap sidecar evaluation failures with host/format/entry context so `PluginManager` diagnostics preserve the rejected specifier. - Update specs and tests for the bundled-only policy, supported sidecar aliases, unsupported renderer imports, and clear local-graph errors. ## Suggested Files or Specs To Inspect - `spec/src/30-cross-package-contracts/plugin-host-boundary.md` - `spec/src/20-packages/desktop-electron/index.md` - `packages/desktop-electron/src-electron/plugin-sidecar-child.ts` - `packages/desktop-electron/src-electron/generated/plugin-sidecar-host-modules.generated.ts` ## Validation Commands - `pnpm --filter @lapis-notes/desktop-electron check:all` - `pnpm check:all` ## Related Issues ## Follow-up Tasks ## Implementation Summary Implemented bundled-only Electron sidecar CommonJS v1 diagnostics, narrowed sidecar host-module aliases to lapis and @lapis-notes/api, passed selected runtime metadata through the native bridge, wrapped sidecar evaluation failures with host/format/entry context, added focused API/runtime-validation coverage, regenerated host-module metadata, and updated the runtime/desktop specs.

steve added this to the Dual ESM/CJS plugin loader milestone

2026-06-02 09:43:41 +00:00

steve

2026-06-02 09:43:41 +00:00