Plugin Development

~/.boo/plugins/my-plugin/
  plugin.json       # Required manifest
  main.js           # Plugin logic

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "icon": "star",
  "description": "A custom sidebar plugin",
  "runtime": "js"
}

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "icon": "star",
  "runtime": "js",
  "settings": [
    { "key": "enabled", "type": "bool", "label": "Enable feature", "default": true, "description": "Turn the feature on or off" },
    { "key": "fontSize", "type": "double", "label": "Font size", "default": 12.0, "min": 8, "max": 32, "step": 1, "group": "Appearance" },
    {
      "key": "fontName",
      "type": "string",
      "label": "Font",
      "default": "",
      "options": "fontPicker:system",
      "group": "Appearance"
    }
  ]
}

AppSettings.shared.pluginBool("my-plugin", "enabled", default: true)
AppSettings.shared.pluginDouble("my-plugin", "fontSize", default: 12.0)
AppSettings.shared.pluginString("my-plugin", "fontName", default: "")
AppSettings.shared.setPluginSetting("my-plugin", "fontSize", 14.0)

function render(ctx) {
  var dir = ctx.cwd.split("/").pop();
  return {
    type: "vstack",
    children: [
      { type: "label", text: "Hello from " + dir, style: "bold" },
      { type: "button", label: "Open in Finder", action: { type: "reveal", path: ctx.cwd } },
    ],
  };
}

function render(ctx) {
  var raw = readFile("package.json");
  if (!raw) return { type: "label", text: "No package.json", style: "muted" };
 
  var pkg = JSON.parse(raw);
  var scripts = pkg.scripts || {};
  var names = Object.keys(scripts);
  if (!names.length) return { type: "label", text: "No scripts defined", style: "muted" };
 
  return {
    type: "list",
    items: names.map(function (name) {
      return {
        label: name,
        icon: "play.circle",
        detail: scripts[name],
        action: { type: "exec", command: "npm run " + name },
      };
    }),
  };
}

{
  label: "main.js",
  icon: "doc",
  action: { type: "open", path: "main.js" },
  contextMenu: [
    { label: "Open in editor", icon: "pencil", action: { type: "open", path: "main.js" } },
    { label: "Copy path", icon: "doc.on.doc", action: { type: "copy", text: "main.js" } },
    { label: "Delete", style: "destructive", action: { type: "exec", command: "rm main.js" } }
  ]
}

function render(ctx) {
  // ctx.cwd is already the new directory — render() is called on every cd
  var hasMakefile = fileExists("Makefile");
  if (!hasMakefile) return { type: "label", text: "No Makefile", style: "muted" };
 
  // Offer an action that runs in the new directory
  return {
    type: "button",
    label: "Run make",
    action: { type: "exec", command: "make" },
  };
}

{
  "menus": [
    {
      "label": "Run Tests",
      "action": "runTests",
      "shortcut": "shift+cmd+t",
      "icon": "checkmark.circle"
    },
    { "separator": true },
    { "label": "Open Coverage", "action": "openCoverage" }
  ]
}

function onAction(name, ctx) {
  if (name === "runTests") return { type: "exec", command: "npm test" };
  if (name === "openCoverage") return { type: "open", path: ctx.cwd + "/coverage/index.html" };
  return null;
}

{
  "statusBar": {
    "template": "{git.branch} ({git.changedCount})",
    "onClick": "showTab"
  }
}

{
  "id": "make-targets",
  "name": "Make Targets",
  "version": "1.0.0",
  "icon": "hammer",
  "description": "Lists Makefile targets. Click to run.",
  "when": "env.local",
  "runtime": "js"
}

function render(ctx) {
  var src = readFile("Makefile");
  if (!src) return { type: "label", text: "No Makefile", style: "muted" };
 
  var targets = [];
  var lines = src.split("\n");
  for (var i = 0; i < lines.length; i++) {
    var m = lines[i].match(/^([a-zA-Z][a-zA-Z0-9_-]*)\s*:/);
    if (m) targets.push(m[1]);
  }
  if (!targets.length) return { type: "label", text: "No targets found", style: "muted" };
 
  return {
    type: "list",
    items: targets.map(function (t) {
      return { label: t, icon: "terminal", action: { type: "exec", command: "make " + t } };
    }),
  };
}

Boo/Plugins/YourPlugin/
  YourPlugin.swift          # Plugin class (BooPluginProtocol)
  YourPluginDetailView.swift  # SwiftUI detail view (optional)
  YourService.swift          # Supporting service (optional)

Tests/BooTests/Plugins/YourPlugin/
  YourPluginTests.swift

import SwiftUI
 
@MainActor
final class MyPlugin: BooPluginProtocol {
    var hostActions: PluginHostActions?
    var onRequestCycleRerun: (() -> Void)?
 
    let manifest = PluginManifest(
        id: "my-plugin",       // Also used as pluginID (derived automatically)
        name: "My Plugin",
        version: "1.0.0",
        icon: "star",
        description: "Example built-in plugin",
        when: nil,             // nil = always visible; or use "git.active", "!remote", etc.
        runtime: nil,
        capabilities: PluginManifest.Capabilities(statusBarSegment: true, sidebarTab: true),
        statusBar: PluginManifest.StatusBarManifest(position: "right", priority: 25, template: nil),
        settings: [
            PluginManifest.SettingManifest(key: "greeting", type: .string, label: "Greeting text", defaultValue: AnyCodableValue("Hello"), options: nil)
        ]
    )
 
    // MARK: - Status Bar
 
    func makeStatusBarContent(context: PluginContext) -> StatusBarContent? {
        StatusBarContent(
            text: "Hello",
            icon: "star",
            tint: nil,
            accessibilityLabel: "My Plugin"
        )
    }
 
    // MARK: - Detail View
 
    func makeDetailView(context: PluginContext) -> AnyView? {
        AnyView(
            Text("Hello from My Plugin")
                .font(context.fontScale.font(.base))
                .foregroundColor(Color(nsColor: context.theme.chromeText))
        )
    }
}

func makeDetailView(context: PluginContext) -> AnyView? {
    let scale = context.fontScale
 
    return AnyView(
        VStack(alignment: .leading, spacing: 4) {
            // Named scale steps
            Text("File name")  .font(scale.font(.base))   // × 1.0  (default 12 pt)
            Text("Directory")  .font(scale.font(.sm))     // × 0.875 (default ~10 pt)
            Text("Status")     .font(scale.font(.xs))     // × 0.75  (default  9 pt)
            Text("Section")    .font(scale.font(.lg))     // × 1.125 (default ~13 pt)
            Text("Header")     .font(scale.font(.xl))     // × 1.25  (default 15 pt)
 
            // Pass a design to override the font family (e.g. for code/paths)
            Text("abc123").font(scale.font(.sm, design: .monospaced))
 
            // Apply weight on top of the scale font
            Text("Bold label").font(scale.font(.base).weight(.semibold))
 
            // Read the raw point size if you need it (e.g. for image frames)
            Image(systemName: "star")
                .font(.system(size: scale.size(.sm)))
                .frame(width: scale.size(.base))
        }
    )
}

func registerBuiltins() {
    register(LocalFileTreePlugin())
    register(RemoteFileTreePlugin())
    register(GitPlugin())
    register(AgentsPlugin())
    register(DockerPluginNew())
    register(BookmarksPluginNew())
    register(SnippetsPlugin())
    register(SystemInfoPlugin())
    register(DebugPlugin())
    register(MyPlugin())  // Add here
}

// Convenience methods
pluginActions.exec("ls -la")              // Send command + Enter
pluginActions.cd(to: "/some/dir")         // cd + Enter
pluginActions.pastePath("/some/path")     // Insert path without executing
pluginActions.copy("text")                // Copy to clipboard
pluginActions.reveal("/some/file")        // Show in Finder
pluginActions.openInEditor("/some/file")  // Open with default app
 
// Navigation closures
pluginActions.openDirectoryInNewTab?("/some/dir")
pluginActions.openDirectoryInNewPane?("/some/dir")
pluginActions.sendToTerminal?("raw text\r")
 
// Multi-content tab (reusable tab type)
// Register a factory once (e.g. in pluginDidActivate)
pluginActions.registerMultiContentTab?("my-panel") { ctx in
    AnyView(MyPanelView(title: ctx.title, key: ctx.key))
}
// Open an instance
pluginActions.openMultiContentTab?("my-panel", PluginTabContext(title: "Output", icon: "terminal", key: "run-1"))

pluginActions.setAgentSessionID?("session-abc123")
let id = pluginActions.getAgentSessionID?()

// In your async callback
SomeService.shared.onDataChanged = { [weak self] in
    DispatchQueue.main.async {
        self?.onRequestCycleRerun?()
    }
}

var subscribedEvents: Set<PluginEvent> {
    [.cwdChanged, .remoteSessionChanged]
}

// Terminal changed working directory
func cwdChanged(newPath: String, context: TerminalContext) {
    refreshData(for: newPath)
}
 
// Remote session started or ended
func remoteSessionChanged(session: RemoteSessionType?, context: TerminalContext) {
    if session != nil {
        // Entering remote session
    } else {
        // Back to local
    }
}
 
// Focus moved to a different pane
func terminalFocusChanged(terminalID: UUID, context: TerminalContext) {
    // Update cached state for the new pane
}
 
// Shell command started / finished (subscribe to .commandStarted / .commandEnded)
func commandStarted(command: String, context: TerminalContext) {}
 
func commandEnded(result: CommandResult, context: TerminalContext) {
    // result.command, result.exitCode, result.duration
}

func pluginDidActivate() {
    // Tab selected — start watchers, timers, background work
    startRefreshTimer()
}
 
func pluginDidDeactivate() {
    // Tab deselected — pause background work to save resources
    stopRefreshTimer()
}

func cwdChanged(newPath: String, context: TerminalContext) {
    let envFile = (newPath as NSString).appendingPathComponent(".envrc")
    if FileManager.default.fileExists(atPath: envFile) {
        pluginActions.exec("direnv allow .")
    }
}

func enrich(context: EnrichmentContext) {
    // Write data visible to all plugins in Phase 2
    context.setData(myValue, forKey: "my-plugin.myKey")
}

func react(context: TerminalContext) {
    if let value = context.enrichedData["my-plugin.myKey"] {
        // Use the value contributed by the other plugin
    }
}

let manifest = PluginManifest(
    id: "my-plugin",
    ...
    when: "git.active && !remote",  // Only visible in local git repos
    ...
)
// whenClause is automatically parsed from manifest.when

var prefersOuterScrollView: Bool { false }

func sectionTitle(context: TerminalContext) -> String? {
    let dirName = (context.cwd as NSString).lastPathComponent
    return dirName.isEmpty ? nil : dirName
}

final class MySegment: StatusBarPlugin {
    let id = "my-segment"
    let position: StatusBarPosition = .left
    let priority = 25
 
    func isVisible(settings: AppSettings, state: StatusBarState) -> Bool { true }
 
    func draw(at x: CGFloat, y: CGFloat, theme: TerminalTheme,
              settings: AppSettings, state: StatusBarState, ctx: CGContext) -> CGFloat {
        let attrs: [NSAttributedString.Key: Any] = [
            .font: NSFont.systemFont(ofSize: 10),
            .foregroundColor: theme.textSecondary  // semantic token on TerminalTheme
        ]
        let str = "Hello" as NSString
        str.draw(at: NSPoint(x: x, y: y), withAttributes: attrs)
        return str.size(withAttributes: attrs).width
    }
 
    func handleClick(at point: NSPoint, in barView: StatusBarView) -> Bool { false }
    func update(state: StatusBarState) {}
 
    // Optional (default nil): hover tooltip and VoiceOver label
    var tooltipText: String? { "My segment" }
}

capabilities: PluginManifest.Capabilities(
    statusBarSegment: true,
    sidebarTab: true
)

func makeSidebarTab(context: PluginContext) -> SidebarTab? {
    SidebarTab(
        id: SidebarTabID("my-plugin"),
        icon: "magnifyingglass",
        label: "My Plugin",
        sections: [
            SidebarSection(
                id: "my-plugin-main",
                name: "My Plugin",
                icon: "magnifyingglass",
                content: makeDetailView(context: context) ?? AnyView(EmptyView()),
                prefersOuterScrollView: true,
                generation: 0
            )
        ]
    )
}

capabilities: PluginManifest.Capabilities(
    statusBarSegment: true,
    sidebarTab: true
)