plugs

Maintainers / Template Guide

This is a late-bound plugin system for Go binaries with:

• Self-update from GitHub Releases
• Plugin management via plugctl
• Cross-platform builds (Linux/macOS/Windows, amd64/arm64)
• GitHub Pages documentation (auto-generated from plugin READMEs)

Forking for a New Project

1. Fork or copy this repo
2. Update Taskfile.yml vars:

   vars:
     GITHUB_USER: your-username
     GITHUB_REPO: your-repo-name
   

3. Update internal/version/version.go:

   var (
       GitHubUser = "your-username"
       GitHubRepo = "your-repo-name"
   )
   

4. Add your plugins in cmd/plugins/your-plugin/
5. Add a README.md in each plugin folder (gets merged into docs)
6. Regenerate docs:

   task docs:generate
   

7. Push and tag v0.1.0 to trigger first release

Project Structure

cmd/
  plugctl/           # Client tool - manages plugins
  plugins/
    x1ctl/           # Plugin: Bambu Lab X1 CLI
      main.go
      cmd/           # Cobra subcommands
      README.md      # Plugin docs (merged into index.md)
    fakeprinter/     # Plugin: Mock printer server
      main.go
      README.md
  docgen/            # Generates docs/index.md
internal/
  version/
    version.go       # Self-update logic
    plugin.go        # Plugin management (install, list, update)
docs/
  index.md           # Landing page (GENERATED by docgen)
  *_user.md          # User guides
  *_tech.md          # Technical docs
.github/
  workflows/
    ci.yml           # Build + release on tags

Plugin System

Adding a New Plugin

1. Create cmd/plugins/newplugin/main.go
2. Add a README.md in the plugin folder
3. Run task docs:generate to update docs
4. For self-update support, use internal/version package

Plugin Management

Users install plugins via plugctl:

plugctl list              # list available plugins
plugctl install x1ctl     # install to ~/.plugctl/bin/
plugctl update            # update all installed plugins
plugctl install --local ./dist/x1ctl_darwin_arm64  # local build

Plugins can also self-update:

x1ctl update
x1ctl version --check

Self-Update Mechanism

The internal/version/ package provides:

• version.Info() - returns version string
• version.CheckUpdate() - queries GitHub API for latest release
• version.SelfUpdate(binaryName) - downloads and replaces the running binary
• version.InstallPlugin(name) - downloads plugin to ~/.plugctl/bin/
• version.ListAvailable() - lists plugins from GitHub releases

Build-time version injection via Taskfile:

LD_FLAGS: "-X /internal/version.Version="

CI/CD

GitHub Actions (.github/workflows/ci.yml):

• build job: runs on push, calls task build:all
• release job: runs on v* tags, uploads to GitHub Releases

Key task used by CI: task build:all

GitHub Pages

Pages serve from /docs on main branch (native GitHub markdown rendering).

Setup tasks:

task docs:pages:setup   # configure Pages via gh API
task docs:pages:status  # check configuration
task docs:generate      # regenerate docs from plugin READMEs

Common Tasks

task build:local        # build for current platform
task build:all          # build all platforms
task docs:generate      # regenerate docs
task release:create -- v0.2.0  # tag + push (triggers release)
task run:plugctl -- list

Doc Conventions

• Each plugin has a README.md in its folder
• docs/index.md is GENERATED - edit cmd/docgen/template.md instead
• Plugin READMEs are merged into the generated index.md
• Run task docs:generate after changing plugins or template