Skip to content

fix(script-engine): make the documented plugin globals real - #127

Merged
thangnm93 merged 1 commit into
developfrom
fix/plugin-api-docs
Nov 13, 2026
Merged

thangnm93 merged 1 commit into
developfrom
fix/plugin-api-docs

Conversation

@thangnm93

Copy link
Copy Markdown
Collaborator

The plugin authoring guide documented ui.*, ssh.* and storage.* globals that the script engine never defined. A plugin written from the guide failed at load with ReferenceError: 'ui' is not defined, which is also what silently broke the old bundled Snippets JS plugin.

  • Prelude: a JS prelude now runs before every plugin. It defines the documented globals as thin JSON wrappers over the raw _x host functions:

    • ui.notify, ui.statusbar.*, ui.panel.register (with onMessage), ui.clipboard.copy, ui.addCommand
    • ssh.sessions, ssh.inject
    • storage.get/set/delete

    The wrappers can't bypass PermissionGuard. A function whose permission wasn't granted throws Permission denied: <perm> not granted. Plugins that use the raw _x API keep working.

  • ui.notify: it reached nothing before, because UiBridge was given no callback. It now goes to the plugin console.

  • Guide corrections:

    • There is no JS sftp global; plugins use the panel messages instead.
    • ssh.exec is not exposed, because the raw call is a stub.
    • Storage is synchronous.
    • The permission table, limitations and errors are updated.
    • CLAUDE.md's bridge list is updated to match.

Tests:

  • New plugin_api_prelude_test.dart: 6 of its 7 tests failed before the change with ReferenceError; all 7 pass now.
  • Engine suite: 74 passed. App suite: 2794 passed. Analyzer is clean.

https://claude.ai/code/session_01YGAGXFNiYwvqiuiRKg25y2

…ia JS prelude

Wrap the raw _x host functions so the plugin guide's ui.panel.register,
ui.notify, ui.statusbar.*, ui.clipboard.copy, ui.addCommand, ssh.sessions,
ssh.inject and storage.* work; wrappers throw Permission denied when the
guarded bridge did not register the function. Add onNotify host callback.
Correct the guide and CLAUDE.md: no JS ssh.exec or sftp global.
@thangnm93
thangnm93 merged commit dc99abb into develop Nov 13, 2026
11 checks passed
@thangnm93 thangnm93 mentioned this pull request Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant