Skip to content

api-notes.md

Latest commit

 

History

History
162 lines (126 loc) · 6.06 KB

api-notes.md

File metadata and controls

162 lines (126 loc) · 6.06 KB
Raw

Herdr API Notes

These notes capture the Herdr API surface relevant to herdr-scratch.

Primary References

Plugin Model

Herdr plugins are executable packages declared by herdr-plugin.toml. Actions, event hooks, panes, and link handlers are declared in the manifest. Runtime action registration is not part of Herdr plugin v1.

Important environment variables injected by Herdr for plugin commands include:

  • HERDR_PLUGIN_ID
  • HERDR_PLUGIN_ROOT
  • HERDR_PLUGIN_CONFIG_DIR
  • HERDR_PLUGIN_STATE_DIR
  • HERDR_PLUGIN_ENTRYPOINT_ID
  • HERDR_PLUGIN_CONTEXT_JSON
  • HERDR_BIN_PATH
  • HERDR_SOCKET_PATH

There is no Herdr-managed storage API in v1. HERDR_PLUGIN_CONFIG_DIR and HERDR_PLUGIN_STATE_DIR are path discovery only.

Manifest Surface

herdr-scratch declares:

  • public actions: guide, toggle, open, list, doctor
  • named convenience actions: lazygit, notes
  • one quick-start popup entrypoint: guide
  • one internal pane entrypoint: scratch
  • one internal popup viewer entrypoint: popup

The runtime entrypoint runs the persistent scratchpad process; the popup entrypoint attaches a viewer to its terminal. Users should invoke public actions or CLI commands.

Command Resolution Notes

Herdr stores a linked plugin's plugin_root, but manifest command argv values are preserved. Source inspection shows action commands are spawned from the manifest argv with current_dir(plugin_root), and pane commands are passed to Herdr's pane launcher with a cwd that may be overridden by the caller. Herdr does not rewrite relative binary paths into absolute paths.

For that reason, this manifest must not use the built binary as a relative program path. The current macOS/Linux manifest invokes /bin/sh -c and executes "$HERDR_PLUGIN_ROOT/bin/herdr-scratch" ..., using the plugin-root environment variable Herdr injects for actions and plugin panes.

During herdr plugin install, the manifest build step runs scripts/install-binary.sh. The script downloads a prebuilt binary from GitHub Releases, verifies the SHA256 checksum, and installs it at $HERDR_PLUGIN_ROOT/bin/herdr-scratch. During local linked development, bin/herdr-scratch is a checked-in wrapper that delegates to target/release/herdr-scratch.

Relevant Herdr CLI Commands

Current adapter operations use Herdr CLI commands:

herdr pane current
herdr pane get <pane_id>
herdr pane rename <pane_id> <label>
herdr pane send-text <pane_id> <text>
herdr pane run <pane_id> <command>
herdr tab get <tab_id>
herdr tab focus <tab_id>
herdr --session herdr-scratch workspace create --label scratch:NAME --no-focus ...
herdr --session herdr-scratch plugin pane open --plugin herdr.scratch --entrypoint scratch --placement tab ...
herdr plugin pane open --plugin herdr.scratch --entrypoint popup --placement popup --width 80% --height 80% ...
herdr --session herdr-scratch terminal attach <terminal_id>
herdr plugin pane focus <pane_id>
herdr plugin pane close <pane_id>

Commands that return JSON use Herdr's standard response envelope. Commands that only acknowledge success may produce no stdout; the adapter treats an empty successful response as Ok.

The Herdr CLI does not expose exact pane.focus <pane_id> as a CLI command, but the socket API exposes pane.focus. herdr-scratch uses that socket method when HERDR_SOCKET_PATH is available so hide can return to the previous pane inside the same tab.

Relevant Socket Methods

The socket API methods underlying the Herdr CLI include:

  • pane.current
  • pane.get
  • pane.list
  • pane.focus
  • pane.send_text
  • pane.send_input
  • tab.get
  • tab.focus
  • plugin.pane.open
  • plugin.pane.focus
  • plugin.pane.close

Future adapter implementations can use the socket API directly. The public scratchpad API should not change when that happens.

Capability Matrix

Capability Herdr today herdr-scratch strategy
Create plugin-managed terminal Yes Use adapter open_scratchpad
Focus plugin pane Yes Validate handle, then focus
Rename plugin pane Yes Apply ui.title_template to pane label
Query pane by ID Yes pane.get
Query tab by ID Yes tab.get through opaque focus token
Persist plugin state Yes, plugin-owned files registry.json
Store config Yes, plugin-owned files config.toml
Receive invocation context Yes HERDR_PLUGIN_CONTEXT_JSON
Know workspace/cwd Yes, from context/current pane Resolve scope and cwd
Hide Herdr tabs No hidden-tab API needed Keep backing terminals in a private named session
Floating popup Yes since 0.7.4 Open a popup direct-attach viewer
Persist after popup detach Yes through direct attach Keep the server-owned backing terminal alive
Reopen exact closed PTY No Treat a terminated backing handle as stale

Overlay Investigation Summary

Herdr plugin panes can be opened with an overlay placement, but source inspection showed overlays are temporary zoomed panes tracked internally by Herdr. Closing a plugin pane delegates to the generic pane close path, removes plugin pane records, removes unattached terminal state, and shuts detached runtimes.

Herdr 0.7.4 added a distinct session-modal popup surface. Closing that popup still shuts down the popup runtime, so the plugin does not run the scratchpad shell directly inside it. Instead, it runs the shell in a private named Herdr session and uses terminal attach inside the popup. Detaching the attach client ends the popup command while preserving the server-owned backing terminal.

Stable Contract

The public API exposes:

  • scratchpad names
  • scopes
  • profiles
  • lifecycle states
  • JSON summaries

It does not expose:

  • backend placement
  • Herdr layout internals
  • implementation-specific runtime surface names

Runtime handles in the registry are opaque implementation details.