bootstrap/docs/plugin_development.md

Plugin Development Guide

Plugins are first-party or third-party applications written to work directly with bootstrap. Unlike installers (or packages) which modify your system by compiling code, downloading binaries, and altering shell configuration files, plugins are lazy-loaded scripts that execute within a sandboxed subshell.

This means downloading and invoking a plugin makes no system modifications other than caching the .sh file itself. They are fetched only the very first time you invoke them.

1. Writing a Plugin Script

A plugin is fundamentally a single Bash script. When executed by a user via b <plugin_name>, bootstrap runs the script in a subshell. This guarantees that any variables or state changes your plugin makes to the shell environment will not leak into the parent shell, preserving the integrity of the user's terminal.

Because plugins execute within the bootstrap context, you automatically have access to all internal library functions (e.g., lib/common.sh, lib/platform.sh). For example, you can safely use logging functions like log_info, log_success, and log_error.

Example my_plugin.sh:

#!/usr/bin/env bash
# My Awesome Plugin

# You can use bootstrap's built-in functions natively:
log_info "Initializing awesome plugin..."

if [ "${1:-}" == "--help" ]; then
    echo "Usage: b my_plugin [args]"
    exit 0
fi

log_success "Task completed successfully!"

2. Creating a Manifest

For your plugin to be discoverable and dynamically updatable by bootstrap, you must provide a JSON manifest. bootstrap uses a robust, native Bash-based JSON parser to read this manifest.

Create a JSON file (e.g., plugins.json) and host it publicly (e.g., as a GitHub raw URL).

Example plugins.json:

{
  "plugins": {
    "my_plugin": {
      "version": "1.0.0",
      "url": "https://raw.githubusercontent.com/yourusername/repo/main/my_plugin.sh",
      "description": "An awesome plugin that prints logs"
    }
  }
}

• version: The current semantic version of your plugin. When bootstrap detects a version change during b up, it automatically clears the cached .sh file, forcing a lazy re-download on the next invocation.
• url: The raw, direct URL to your .sh plugin script.

3. Distribution

To let users install your plugin, simply provide them the raw URL to your JSON manifest.

Users will add it by running:

b plugin sources

They simply append your URL as a new line in the sources file. Once saved, bootstrap will automatically fetch your manifest and build a fast-lookup cache. The user can then immediately invoke your plugin:

b my_plugin