Skip to content

Load config-adjacent plugins under Node, not only Bun #193

Open

Description

@mindsocket

Problem. resolveExternalPlugin imports a config-adjacent plugin's directory (src/plugins/loader.ts:49, await import(localPath)). Bun resolves a directory import through the plugin's package.json. Node's ESM loader rejects any directory import:

Directory import '…/plugins/sctx-example' is not supported resolving ES modules

So hosts that run structured-context under plain Node (e.g. the Obsidian plugin, inside Electron) can't load config-adjacent plugins, and spaces that need one fail to load.

Proposal. Resolve the plugin's entry file before importing it: read its package.json (exports["."], then main, falling back to index.js), or use createRequire(join(localPath, 'package.json')).resolve(localPath), and import(pathToFileURL(entry).href). Keep the existing ${localPath}.ts single-file case.

Test. A config-adjacent fixture plugin with a JS entry, loaded in a test that runs under Node (not Bun).

Related. A plugin whose entry is TypeScript still needs Bun; plugins meant for Node hosts should ship JS. Worth a line in the plugin docs.

Activity

  1. mindsocket commented on Oct 29, 2026

    @mindsocket
    OwnerAuthor

    Scoping note (2026-10-29), after checking who calls what.

    measured: loadPlugins (src/plugins/loader.ts:93) imports only the plugins a space names in its own plugins map. A space that does not reference a plugin never triggers an import of it. discoverPlugins (loader.ts:62) imports every sctx-* folder in the config-adjacent plugins/ directory with no registration, but its only callers are CLI commands: plugins (commands/plugins.ts:11), schemas (commands/schemas.ts:301) and render --list without a space (commands/render.ts:97).

    So a host that loads one space at a time (the Obsidian plugin) only hits this for a space that declares a non-bundled plugin. For now the Obsidian plugin treats non-bundled plugins as unsupported. When they are supported there, the space config is what enables one.

    Still to settle: any lookup of "which plugin can handle this path" that works without explicit registration would have to go through discovery, and discovery imports everything it finds. hypothesis: today that lookup exists only in the CLI paths above; cheapest check is to grep the structured-context/api entry points for anything that reaches discoverPlugins.

    This issue stays as proposed: resolve the entry from the plugin's package.json so a plugin that ships JS loads under Node as well as Bun.

  2. mindsocket commented on Oct 29, 2026

    @mindsocket
    OwnerAuthor

    Follow-up (2026-10-29) on how a host could decline non-bundled plugins, and how to keep discovery out of the library path.

    What drives plugin loading. measured: parse, template-sync and render take the plugins a space declares in its plugins map plus the built-ins, via loadPlugins(space.plugins, configDir) (read/read-space.ts:6-7, render/render.ts:13-14, commands/template-sync.ts:6-7). Declared external plugins come first, then built-ins (loader.ts:103-127), and readSpace uses the first plugin whose parse returns non-null. Which plugin handles a space is decided by its own declaration, so no path-to-plugin discovery is involved. discoverPlugins only lists plugins and is called from commands/plugins.ts, commands/schemas.ts and commands/render.ts.

    Declining external plugins in a host. The gate is the external loop in loadPlugins (loader.ts:103-116), which today fails with a raw import error. Wanted: a declared plugin the host doesn't support fails with a typed error the host can turn into its own message.

    The option has to reach loadPlugins from the host. hypothesis: SpaceContext is the carrier, since every caller above already passes it through. createSpaceContext is where it is built and already takes an options object (configDir), so an option there (for example whether non-bundled plugins are allowed) could be stored on the context and read by loadPlugins callers. validateFile, validateSpace and loadSpaceGraph each call createSpaceContext themselves (validate.ts:613, load-space-graph.ts:71), so the option would also need threading through their options. Cheapest check: list every createSpaceContext and loadPlugins call site and confirm none builds a context without going through one of those entry points.

    Keeping discovery on the CLI side. Restrict imports of discoverPlugins (or plugins/loader's discovery export) so only src/commands/** may import it, which covers the three current callers. Core lints with Biome, which has noRestrictedImports; a per-path override could allow src/commands/**. hypothesis: Biome's rule can express "this module, except from these paths"; cheapest check is to try it on discoverPlugins and see whether a deliberate import from src/validate.ts is flagged. If not, no-restricted-imports in ESLint does the same job at the cost of adding ESLint. Either way it is a direct-import check only, so a bundle test (bundle src/api.ts, assert discoverPlugins is absent) would catch a transitive leak.

    Not decided: the option's name and default.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions