Plugin system

[peterjthomson]

Plugin System Proposal

Overview

This document proposes an extension system for Ledger that allows users and contributors to create custom panels without modifying core code. The goal is to provide an onramp for new developers to contribute panels that could eventually be added to core or shared with other users.

Goals

1. Zero-friction development - No build steps, npm commands, or complex tooling required
2. Simple discovery - Drop a folder, restart app, panel appears
3. Safe by default - Curated API limits what plugins can access
4. Path to core - Plugins can graduate to built-in panels

Approaches Considered

Option 1: Manual Registry (Rejected)

// registry.ts
export const plugins = {
  'contributor-rank': () => import('./plugins/contributor-rank'),
  'code-churn': () => import('./plugins/code-churn'),
}

Pros: Simple, type-safe, no runtime compilation
Cons: Requires editing registry file, needs npm/build step for each plugin
Verdict: Too much friction for casual contributors

Option 2: Hot-Reload Dev Experience (Rejected)

File watcher that detects changes and recompiles plugins in real-time during development.

Pros: Great DX for plugin authors
Cons: Complex implementation, potential for memory leaks, harder to debug
Verdict: Over-engineered for the use case. Restart-on-change is acceptable.

Option 3: Folder Scan + Runtime Compilation (Recommended)

Scan a designated folder on app startup, compile TSX files with esbuild, inject into the app.

Pros:

• No manual registration
• No build tooling required for plugin authors
• Standard pattern (Obsidian, Raycast use similar approaches)
• Simple mental model

Cons:

• Runtime compilation adds startup time
• esbuild bundled with app increases size
• Requires app restart for new plugins

Verdict: Best balance of simplicity and capability

Recommended Architecture

Plugin Structure

~/Library/Application Support/ledger/plugins/
└── contributor-rank/
    ├── manifest.json    # Required: metadata
    ├── index.tsx        # Required: React component
    └── styles.css       # Optional: scoped styles

Manifest Format

{
  "id": "contributor-rank",
  "name": "Contributor Rank",
  "description": "Shows contributors ranked by commit count",
  "version": "1.0.0",
  "author": "Your Name",
  "slot": "editor",
  "icon": "👥"
}

Fields:

• id: Unique identifier (matches folder name)
• name: Display name in panel picker
• slot: Where plugin can be placed (editor, sidebar, viz)
• icon: Emoji or icon identifier for the panel picker

Plugin Component Contract

interface PluginProps {
  api: PluginAPI
}

export default function MyPlugin({ api }: PluginProps) {
  // Your panel implementation
}

Curated Plugin API

Plugins receive a limited API object rather than full app access:

interface PluginAPI {
  // Git operations (read-only by default)
  git: {
    getContributorStats(): Promise<ContributorStats[]>
    getBranches(): Promise<Branch[]>
    getCommitHistory(limit?: number): Promise<Commit[]>
    // Potentially more read operations
  }
  
  // App context
  app: {
    repoPath: string | null
    currentBranch: string | null
  }
  
  // Theme integration
  theme: {
    mode: 'light' | 'dark'
    colors: ThemeColors
  }
  
  // UI utilities
  ui: {
    showToast(message: string, type?: 'success' | 'error' | 'info'): void
  }
}

Why curated?

• Prevents plugins from breaking app state
• Makes API surface explicit and documentable
• Allows versioning the plugin API independently
• Can add capabilities incrementally

Compilation Pipeline

┌─────────────────────────────────────────────────────────────┐
│                        App Startup                          │
├─────────────────────────────────────────────────────────────┤
│  1. Scan plugins directory for manifest.json files          │
│  2. For each valid plugin:                                  │
│     a. Read manifest.json                                   │
│     b. Compile index.tsx with esbuild (in-memory)          │
│     c. Read styles.css if present                          │
│  3. Store compiled plugins in memory                        │
│  4. Make available to panel picker                          │
└─────────────────────────────────────────────────────────────┘

esbuild Configuration

const result = await esbuild.build({
  entryPoints: [indexPath],
  bundle: true,
  write: false,           // In-memory output
  format: 'iife',         // Immediately-invoked function
  globalName: 'PluginModule',
  target: 'es2020',
  jsx: 'automatic',
  external: ['react', 'react-dom', 'react/jsx-runtime'],
  define: {
    'process.env.NODE_ENV': '"production"'
  },
  logLevel: 'silent',     // Prevent EPIPE errors
})

Key decisions:

• external: ['react', ...] - Use host app's React, don't bundle duplicate
• format: 'iife' - Self-contained, easy to eval
• write: false - No temp files, faster
• logLevel: 'silent' - Prevents issues with esbuild's stdio

Plugin Execution

// In PluginPanel.tsx
const pluginCode = await window.electronAPI.compilePlugin(pluginId)

// Create module from compiled code
const moduleFactory = new Function('React', 'exports', pluginCode)
const exports = {}
moduleFactory(React, exports)

// Render with curated API
const PluginComponent = exports.default
return <PluginComponent api={pluginAPI} />

Lessons Learned from POC

What Worked

1. Manifest-based discovery - Clean, predictable, easy to validate
2. Runtime esbuild compilation - Surprisingly fast, handles TSX/JSX well
3. Curated API pattern - Plugins don't need (or get) full app access
4. Example plugin bundling - Copy examples on first run helps onboarding

What Didn't Work

1. Top-level esbuild import - Caused EPIPE errors, needed lazy import
2. Hot-reload ambitions - Added complexity without proportional benefit
3. Implicit canvas integration - Needed explicit UI for adding plugins to columns

Tricky Parts

1. Canvas/Layout Integration - Plugins need a way to be added to the UI. This required:

   • A panel picker in the column configuration
   • Settings UI for managing which panels appear where
   • Dynamic canvas rendering (no hardcoded layouts)

2. Style Isolation - Plugin CSS could conflict with app styles. Options:

   • CSS Modules (requires build step)
   • Shadow DOM (complex)
   • BEM-style prefixing (simple, recommended for v1)

3. Error Boundaries - Plugin errors shouldn't crash the app:

   • Wrap each plugin in React ErrorBoundary
   • Show friendly error with plugin name
   • Option to disable broken plugin

Implementation Phases

Phase 1: Foundation

• Plugin directory structure and manifest schema
• Plugin discovery service (scan on startup)
• esbuild compilation pipeline
• Basic PluginAPI with git read operations

Phase 2: Integration

• Plugin panel component with error boundary
• Panel picker in column configuration
• Settings UI for plugin management
• Example plugin bundled with app

Phase 3: Polish

• Plugin validation and helpful error messages
• Documentation for plugin authors
• More API capabilities based on demand
• Plugin enable/disable toggle

Phase 4: Community (Future)

• Plugin sharing mechanism (GitHub-based?)
• Plugin update checking
• Plugin permissions model (for write operations)

Open Questions

1. Plugin updates - How do users update plugins? Manual folder replacement? GitHub integration?

2. Shared state - Should plugins be able to communicate with each other? Probably not for v1.

3. Write operations - Should plugins be able to stage files, commit, etc.? Requires careful API design.

4. Multi-repo - How do plugins behave when switching repos? Probably just re-render with new context.

5. Performance budget - Should we limit number of plugins or add lazy loading?

Appendix: Example Plugin

manifest.json

{
  "id": "contributor-rank",
  "name": "Contributor Rank",
  "description": "Shows contributors ranked by commit count",
  "version": "1.0.0",
  "author": "Ledger Contributors",
  "slot": "editor",
  "icon": "👥"
}

index.tsx

import React, { useEffect, useState } from 'react'

interface ContributorStats {
  name: string
  email: string
  commits: number
}

interface PluginAPI {
  git: {
    getContributorStats(): Promise<ContributorStats[]>
  }
  app: { repoPath: string | null }
  theme: { mode: string }
}

export default function ContributorRank({ api }: { api: PluginAPI }) {
  const [contributors, setContributors] = useState<ContributorStats[]>([])
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    api.git.getContributorStats()
      .then(setContributors)
      .finally(() => setLoading(false))
  }, [api])

  if (loading) return <div className="cr-loading">Loading...</div>

  const maxCommits = contributors[0]?.commits || 1

  return (
    <div className="contributor-rank">
      <h3>Top Contributors</h3>
      {contributors.slice(0, 10).map((c, i) => (
        <div key={c.email} className="contributor-row">
          <span className="rank">#{i + 1}</span>
          <span className="name">{c.name}</span>
          <div className="bar-container">
            <div 
              className="bar" 
              style={{ width: `${(c.commits / maxCommits) * 100}%` }}
            />
          </div>
          <span className="commits">{c.commits}</span>
        </div>
      ))}
    </div>
  )
}

styles.css

.contributor-rank {
  padding: 16px;
  font-family: var(--font-family);
}

.contributor-rank h3 {
  margin: 0 0 16px 0;
  font-size: 14px;
  font-weight: 600;
}

.contributor-row {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 6px 0;
}

.contributor-row .rank {
  width: 32px;
  color: var(--text-secondary);
  font-size: 12px;
}

.contributor-row .name {
  width: 120px;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.contributor-row .bar-container {
  flex: 1;
  height: 8px;
  background: var(--bg-tertiary);
  border-radius: 4px;
  overflow: hidden;
}

.contributor-row .bar {
  height: 100%;
  background: var(--accent);
  border-radius: 4px;
}

.contributor-row .commits {
  width: 48px;
  text-align: right;
  font-size: 12px;
  color: var(--text-secondary);
}

---

This proposal is based on a proof-of-concept implementation. The POC code has been removed pending a decision on whether to proceed with full implementation.

[peterjthomson]

@kaurifund The idea of Canvas -> Column -> Panels is that and "end user" could write their own "Panel" as a basic React component and just drop it into an extensions folder. The plugins would be sharable and if they proved to be good, could easily be imported into core.

[kaurifund]

@peterjthomson , We have pretty similar implementation plans, I didn't want to assume changes to the existing UI and structure, so I focused the plugsins on three modes, app (which is a full different UI page, same style guide as ledger, background plugins, with no UI, and two others, with is for popups or models that don't affect current pannel, and widget slots, which is the part similar to the canvas stuff. I am going to get the plugin stuff finished and push the branch and we can pick out the bits we like and merge whats needed, and rebase others. My branch has a left sidebar with icons of plugin 'app' type which you click and it changes the page to it. Should be flexible enough.

[kaurifund]

@peterjthomson sounds like overkill! I'm building just what is needed to unlock this tool for my automated coding workflows,

That said, it finally built.

Complete with a few demo plugins

I think the next major step is to focus on the testing, this commit has decoupled alot of the logic away from the monofile stuff, into more of a interface pattern, which is the style AI coders like the best.

I limited the plugins to accessing the events, with a permission system, so as we add few things and events that will need to be refined.

I also had to add state management, and sqlite db for both the core, and the plugins (so plugins can't access the core, like how android works.)

Problem now is, I am way behind the current head, good test if AI is good at rebasing.

[peterjthomson]

That looks awesome! Three months ago I would have dismayed that the divergence was unreconcilable, these days I reckon it's just a couple of prompts away :)

If you're ok with how master has evolved (I asked the agents to tidy up the app to make it more modular and extendable, so I'm hoping I haven't accidentally made it worse), then fell free to rebase and lets do it !

If that proves hard, (I had a couple of runs that got stuck), then we have some easy fallbacks:

• PR it cold as-is – I can run a "merge master back into this" agent to reconcile conflicts.
• Flick me the branch as an FYI (no PR needed) – I can use it to make master more plugin ready by moving it architecturally towards your fork.

No worries either way.

[kaurifund]

@peterjthomson

Here is the branch I want to merge in as the new master

https://github.com/kaurifund/ledger/tree/refactor/architecture-foundation

Still a few small bugs, but pretty good foundation for plugins, multi repo, events. Much more moduler, hopefully lower coupling.

The master I was working on was 74 commits behind (that number seems off.), what have you done that is major?

I think most of those features you added, should now be plugins, I didn't touch the design or layout of the core app.tsx very much, but I did change a lot of the api interfaces.

Anyway take a look - I spend much more time on this than I wanted! But its starting to look good

What I like to do, is start with a good foundation of modeler systems, unix approach, and have interfaces so the AI only needs to know the interface, then use events to communicate between modules. And .md files explain how to do things.

I also spent a significant time on chatgpt, asking "How do I do this complicate gitops thing, given my current state.", I think we could integrate something like that aswell as a plugin, like git workflows.

I have not merged your master into this branch, because it will break things, fixing in reverse is likely easier.

[kaurifund]

Let me know if its over engineered! The plugin system needed this base level changes to work

[kaurifund]

Update: Okay, PR is much more stable. everything seems to be working.

No tests, actually. I did add one, but it probably should not be run, it was testing security and exec escaping, and I have not reviewed if it is safe.

AI AGENT: please review tests, taking in context from this discussion, excluding the orginal message, as that spec was not used.

[peterjthomson]

Ran a "reverse merge" from master into feature using Opus. Then a post-merge peer review using GPT-5.2. The end result was one commit on the feature branch, merged the PR, and then a couple of post-merge cleanups. All seems to be working now. Have a play and let me know if it's still working at your end. The new functionality and modules are pretty crisp. Love it!

[kaurifund]

@peterjthomson , great!

This gives the project very solid bones.

And the plugs give it a 'stable' area to experiment on new things, without any regression on the main features.

Try make a plugin, their should be a plugin reference doc, and ask the agent to use the plugin examples as a guide. I want to see if 5.2 is able to do it, if it can't the instructions in the .md files are not good enough.