Add Module

Add Module Skill

Automates creation of new modules in the CLY project following established patterns.

Module Isolation Principle (CRITICAL)

The Portability Test: Before creating a module, ask: "If I copy this module folder to a new repo, how hard would it be to make it work?"

The answer should be: trivially easy.

Requirements for Isolation

• Self-contained: All module logic lives within its directory
• Minimal dependencies: Only depend on stdlib, Bubbletea/Bubbles/Lipgloss, and Cobra
• No cross-module imports: Modules NEVER import from other modules
• Single registration point: Only touch parent's cmd.go for registration
• Own types: Define types locally, don't reach into other packages

What a Module Can Import

✓ Standard library (fmt, strings, etc.)
✓ github.com/charmbracelet/bubbletea
✓ github.com/charmbracelet/bubbles/*
✓ github.com/charmbracelet/lipgloss
✓ github.com/spf13/cobra
✓ github.com/yurifrl/cly/pkg/*  (shared utilities - see below)
✗ github.com/yurifrl/cly/modules/*  (NEVER)

Avoiding Duplication (The Balance)

Isolation doesn't mean blind copy-paste. Use pkg/ for genuinely shared code:

Rule of Three: Only extract to pkg/ when 3+ modules need the same code.

Duplication is OK when:

• Variations exist between modules
• Extraction would create tight coupling

Extract to pkg/ when:

• Exact same code in 3+ places
• Code is substantial and stable
• Changes should propagate everywhere

Module Directory = Complete Unit

modules/demo/spinner/
├── cmd.go        # Registration only
├── spinner.go    # All logic here
└── (optional)    # Helpers if needed, but keep in same package

Copy this folder → paste in new project → change import path → works.

When to Use This Skill

• User wants to add a new demo module showcasing a Bubbletea component
• User wants to create a new utility command
• User mentions "create a module", "add a command", "new demo"

Module Types

Demo Modules (modules/demo/<name>/)

Purpose: Showcase Charm UI components and patterns Examples: chat, spinner, table, list-simple (48 total) Parent: Registered under demo namespace

Utility Modules (modules/<name>/)

Purpose: Provide real functionality Examples: uuid (UUID generator) Parent: Registered directly under root command

Step-by-Step Workflow

Determine Module Type

Ask user if unclear:

• "Is this a demo (showcase component) or utility (real functionality)?"

Find Reference (for demos)

• Check if component exists in references/bubbletea/examples/<name>/
• Read the reference implementation
• Note initialization code in main() function

Create Directory Structure

# For demo:
mkdir -p modules/demo/<name>

# For utility:
mkdir -p modules/<name>

Create cmd.go (Command Registration)

Template for demos:

package <packagename>

import (
	tea "github.com/charmbracelet/bubbletea"
	"github.com/spf13/cobra"
)

func Register(parent *cobra.Command) {
	cmd := &cobra.Command{
		Use:   "<name>",
		Short: "<description>",
		RunE:  run,
	}
	parent.AddCommand(cmd)
}

func run(cmd *cobra.Command, args []string) error {
	p := tea.NewProgram(initialModel())
	if _, err := p.Run(); err != nil {
		return err
	}
	return nil
}

Add tea.Program options if needed:

• tea.WithAltScreen() - For fullscreen demos
• tea.WithMouseAllMotion() - For mouse tracking
• tea.WithReportFocus() - For focus/blur events

Create Implementation File

Extract from reference:

• Copy type definitions (model struct, custom types)
• Copy Init(), Update(), View() methods
• Create initialModel() from main() function's initialization code
• Remove unused imports (fmt, os, log often unused after main() removal)

Template:

package <packagename>

import (
	tea "github.com/charmbracelet/bubbletea"
	// Component imports as needed
)

type model struct {
	// State fields
}

func initialModel() model {
	// Initialization from reference's main()
	return model{}
}

func (m model) Init() tea.Cmd {
	return nil
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyMsg:
		switch msg.String() {
		case "q", "ctrl+c":
			return m, tea.Quit
		}
	}
	return m, nil
}

func (m model) View() string {
	return "Your UI\n"
}

Register Module

For demos - Edit modules/demo/cmd.go:

import (
	yourmodule "github.com/yurifrl/cly/modules/demo/your-module"
)

func init() {
	// ... existing registrations
	yourmodule.Register(DemoCmd)
}

For utilities - Edit cmd/root.go:

import (
	"github.com/yurifrl/cly/modules/yourutil"
)

func init() {
	// ... existing registrations
	yourutil.Register(RootCmd)
}

Validation Checklist

• Compiles: go build
• Shows in help: go run main.go --help or go run main.go demo --help
• Runs: go run main.go <command> (or go run main.go demo <name>)
• Quits cleanly with 'q' or Ctrl+C
• No unused imports

Common Patterns

Package Naming

• Directory with hyphens: list-simple/
• Package name with underscores: package list_simple
• Import alias: listsimple "github.com/yurifrl/cly/modules/demo/list-simple"

Extracting initialModel()

In reference main():

func main() {
	s := spinner.New()
	s.Spinner = spinner.Dot
	m := model{spinner: s}
	tea.NewProgram(m).Run()
}

Extract to:

func initialModel() model {
	s := spinner.New()
	s.Spinner = spinner.Dot
	return model{spinner: s}
}

Helper Functions

If reference has helpers (like getPackages(), filter(), etc.), copy them to the implementation file.

Examples to Reference

Simple: modules/demo/spinner/ - Basic component Complex: modules/demo/list-fancy/ - Multiple files (delegate.go, randomitems.go) Utility: modules/uuid/ - Real functionality with list UI Advanced: modules/demo/chat/ - Multiple components (textarea + viewport)

Quick Reference Commands

# Test compilation
go build

# View help
go run main.go --help
go run main.go demo --help

# Run demo
go run main.go demo <name>

# Run utility
go run main.go <name>

# Clean dependencies
go mod tidy

Best Practices

Start from reference - All 48 Bubbletea examples available in references/ Copy existing module - Fastest way to get structure right Test incrementally - Build and run after each file Clean imports early - Remove fmt/os/log before testing Follow naming - Hyphens in names, underscores in packages

Troubleshooting

Build Errors

• "undefined: initialModel" → Function not created or private (make sure it's initialModel, not InitialModel)
• "unused import" → Remove it from imports
• "package name mismatch" → Check hyphens vs underscores

Runtime Errors

• "could not open TTY" → Normal in non-interactive shells, try in terminal
• Component not responding → Check Update() delegates to component's Update()
• Can't quit → Verify KeyMsg handling for "q" and "ctrl+c"

Module Template

Use this template to add new commands quickly.

Module Categories

Demo Modules (UI Component Showcases)

Location: modules/demo/<name>/ Purpose: Demonstrate Charm components and patterns Examples: chat, spinner, table, list-simple

When to use: Showcasing UI components, TUI patterns, Bubbletea features

Utility Modules (Real Functionality)

Location: modules/<name>/ Purpose: Provide actual utility commands Examples: uuid (UUID generator)

When to use: Commands users will actually use for work

Quick Steps

For Demo Modules

• Find reference: references/bubbletea/examples/<component>/
• Copy pattern: cp -r modules/demo/spinner modules/demo/<newname>
• Adapt implementation from reference
• Register in modules/demo/cmd.go init()
• Test

For Utility Modules

• Copy pattern: cp -r modules/uuid modules/<newname>
• Implement functionality
• Register in cmd/root.go init()
• Test

Demo Module Template

File: modules/demo/<name>/cmd.go

package <packagename>  // Use underscores for hyphens: list_simple for list-simple

import (
	tea "github.com/charmbracelet/bubbletea"
	"github.com/spf13/cobra"
)

func Register(parent *cobra.Command) {
	cmd := &cobra.Command{
		Use:   "<name>",
		Short: "<short description>",
		Long:  "<detailed description>",
		RunE:  run,
	}

	parent.AddCommand(cmd)
}

func run(cmd *cobra.Command, args []string) error {
	p := tea.NewProgram(initialModel())
	if _, err := p.Run(); err != nil {
		return err
	}
	return nil
}

File: modules/demo/<name>/<name>.go

package <packagename>

import (
	tea "github.com/charmbracelet/bubbletea"
	// Add component imports as needed:
	// "github.com/charmbracelet/bubbles/spinner"
	// "github.com/charmbracelet/bubbles/list"
	// "github.com/charmbracelet/bubbles/table"
	// "github.com/charmbracelet/lipgloss"
)

type model struct {
	// Component state
	quitting bool
	err      error
}

func initialModel() model {
	// Initialize your model here
	// Extract this from reference example's main() function
	return model{}
}

func (m model) Init() tea.Cmd {
	return nil
	// Or return component's Init: spinner.Tick, textarea.Blink, etc.
}

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	switch msg := msg.(type) {
	case tea.KeyMsg:
		switch msg.String() {
		case "q", "ctrl+c":
			m.quitting = true
			return m, tea.Quit
		}
	}

	return m, nil
}

func (m model) View() string {
	if m.quitting {
		return "Goodbye!\n"
	}

	return "Your UI here\nPress q to quit\n"
}

Registration Patterns

Demo Module Registration

File: modules/demo/cmd.go

import (
	// ...
	yourmodule "github.com/yurifrl/cly/modules/demo/your-module"
)

func init() {
	// ...
	yourmodule.Register(DemoCmd)
}

Utility Module Registration

File: cmd/root.go

import (
	// ...
	"github.com/yurifrl/cly/modules/yourutil"
)

func init() {
	uuid.Register(RootCmd)
	demo.Register(RootCmd)
	yourutil.Register(RootCmd)  // Add here
}

Bubbletea Program Options

Some demos require special options when creating the tea.Program:

AltScreen (Fullscreen Mode)

func run(cmd *cobra.Command, args []string) error {
	p := tea.NewProgram(initialModel(), tea.WithAltScreen())
	_, err := p.Run()
	return err
}

Use when: Demo should use alternate screen buffer (fullscreen, eyes, cellbuffer) Examples: modules/demo/fullscreen/, modules/demo/eyes/

Mouse Support

p := tea.NewProgram(initialModel(), tea.WithMouseAllMotion())

Use when: Demo needs mouse tracking Example: modules/demo/mouse/

Focus Reporting

p := tea.NewProgram(initialModel(), tea.WithReportFocus())

Use when: Demo needs to know when terminal gains/loses focus Example: modules/demo/focus-blur/

Input Filtering

p := tea.NewProgram(initialModel(), tea.WithFilter(filterFunc))

Use when: Need to intercept/modify messages before Update() Example: modules/demo/prevent-quit/

Reference Examples (48 Available)

All 48 Bubbletea examples are in references/bubbletea/examples/ and modules/demo/:

Core Components

Advanced

All 48 examples are available - explore modules/demo/ for implementations.

Adapting Reference Examples

Step-by-Step Process

Find reference: references/bubbletea/examples/<component>/main.go Read main() function: This has initialization code Extract to initialModel(): Move setup from main() to initialModel() Copy Model implementation: Copy type definitions, Init(), Update(), View() Clean imports: Remove fmt, os, log if unused Create cmd.go: Use template above with Register() function

Example: Adapting Spinner

Reference: references/bubbletea/examples/spinner/main.go

Extract this from main():

s := spinner.New()
s.Spinner = spinner.Dot
s.Style = lipgloss.NewStyle().Foreground(lipgloss.Color("205"))
return model{spinner: s}

Becomes initialModel():

func initialModel() model {
	s := spinner.New()
	s.Spinner = spinner.Dot
	s.Style = lipgloss.NewStyle().Foreground(lipgloss.Color("205"))
	return model{spinner: s}
}

Naming Conventions

Command Names

• Lowercase only
• Hyphens for multi-word: list-simple, credit-card-form, altscreen-toggle

Package Names

• Lowercase, no hyphens
• Use underscores: list_simple, credit_card_form, altscreen_toggle
• Go converts hyphens automatically during import

File Names

• cmd.go - Always this name (command registration)
• <name>.go - Main implementation (e.g., spinner.go, list-simple.go)
• Additional files: delegate.go, helpers.go, types.go (if needed)

Checklist

Before Implementation

• Decided: demo or utility module?
• Found reference example (if demo)
• Command name chosen (lowercase, hyphens if multi-word)

During Implementation

• Created directory in correct location
• Created cmd.go with Register() function
• Created implementation file with initialModel()
• Package name matches conventions
• Imports are clean (no unused)

After Implementation

• Registered in parent cmd.go init()
• Import added to parent cmd.go
• Compiles: go build
• Appears in help: go run main.go --help or go run main.go demo --help
• Runs: go run main.go <command>
• Quits cleanly with 'q' or Ctrl+C

Tips

Start with existing demos - 48 working examples to learn from Copy working code - Don't reinvent, adapt from references Test frequently - Build and run after each change Keep it simple - Single file until complexity demands splitting Use shared styles - Import pkg/style for consistent theming Follow the pattern - Look at 3-4 similar modules before starting

Troubleshooting

"undefined: initialModel"

• Make sure initialModel() function exists in implementation file
• Check it's exported (lowercase 'i' makes it package-private)

"package name mismatch"

• Directory name with hyphens → package name with underscores
• Example: list-simple/ → package list_simple

"unused import"

• Remove fmt, os, log if not actually used
• Check your View() and Update() functions
• Common after removing main() function

"command not showing in help"

• Verify Register() called in parent's init()
• Check import path is correct
• Run go mod tidy

Advanced Patterns

Multiple Files (Complex Modules)

modules/demo/list-fancy/
├── cmd.go           # Command registration
├── list-fancy.go    # Model and main logic
├── delegate.go      # Custom item delegate
└── randomitems.go   # Helper functions

With Flags

var demoType string

func Register(parent *cobra.Command) {
	cmd := &cobra.Command{
		Use:   "demo",
		Short: "Demo with flag",
		RunE:  run,
	}

	cmd.Flags().StringVarP(&demoType, "type", "t", "default", "Demo type")
	parent.AddCommand(cmd)
}

func run(cmd *cobra.Command, args []string) error {
	// Use demoType variable in initialModel()
	p := tea.NewProgram(initialModel(demoType))
	_, err := p.Run()
	return err
}

With Required Args

func Register(parent *cobra.Command) {
	cmd := &cobra.Command{
		Use:   "download <url>",
		Short: "Download with progress",
		Args:  cobra.ExactArgs(1),  // Require 1 argument
		RunE:  run,
	}
	parent.AddCommand(cmd)
}

func run(cmd *cobra.Command, args []string) error {
	url := args[0]
	p := tea.NewProgram(initialModel(url))
	_, err := p.Run()
	return err
}

Converted and distributed by TomeVault — claim your Tome and manage your conversions.