skills

bluefin-mcp — Operational Knowledge

When to Use

Load this skill for any work in projectbluefin/bluefin-mcp — Go backend, tools, tests, testdata, CI.

When NOT to Use

For generic Go patterns → standard Go docs. For Bluefin system facts → check projectbluefin/common, ublue-os/bluefin, docs.projectbluefin.io directly.

---

Design Law — Read Before Changing Anything

Every tool, field, and default value MUST be grounded in:

1. projectbluefin/common source code
2. ublue-os/bluefin source code
3. docs.projectbluefin.io

Never design from generic Linux assumptions:

• Wayland only — X11 is completely unsupported on Bluefin. Never add X11 detection, references, or fallbacks.
• No dnf/rpm/apt — the root filesystem is read-only. Package management = flatpak, brew, ujust only.
• Fully read-only server — bluefin-mcp has no write operations except store_unit_docs. Never add execute functionality.
• Before adding any tool or field: verify it exists in Bluefin source or official docs. If not there, it doesn't belong here.

---

Architecture

bluefin-mcp follows the Ports & Adapters (hexagonal) pattern.

cmd/bluefin-mcp/main.go          Entry point. Wires everything together.
internal/cli/executor.go         Port: CommandRunner interface
internal/cli/real.go             Adapter: RealExecutor (exec.Command)
internal/cli/mock.go             Adapter: MockExecutor (test double)
internal/system/                 Domain: one file per subsystem
internal/tools/tools.go          Thin MCP glue — no business logic
internal/seed/                   Embedded seed data (go:embed)
testdata/                        Golden files from real Bluefin output

CommandRunner interface

Defined in internal/cli/executor.go:

type CommandRunner interface {
    Run(ctx context.Context, name string, args []string) ([]byte, error)
}

• ErrNotInstalled is returned when the binary is absent from PATH.
• All internal/system/ packages receive an injected CommandRunner — they never call exec.Command directly.
• RealExecutor (internal/cli/real.go) runs actual system commands with process-group management so context cancellation can SIGTERM → SIGKILL the process tree.