---

name: app description: Create, modify, and manage shizuku app configurations. Use when the user wants to create a new app, add template files to an app, or modify existing app structure.

Shizuku App Manager

This skill helps create and manage shizuku application configurations.

What This Skill Does

When invoked, this skill helps you:

1. Scaffold new apps - Create complete directory structure and registration
2. Add template files - Create and manage .tmpl files in app contents
3. Modify existing apps - Update app configurations and template data
4. Add installer logic - Implement Install() method for Homebrew packages

App Structure Overview

Each shizuku app follows this pattern:

apps/{appName}/
├── {appName}.go           # App struct with methods
└── contents/              # Template files and assets (optional)
    ├── file.conf          # Regular files (copied as-is)
    └── file.tmpl          # Go templates (processed)

Modern App Architecture

Apps use an interface-based design with optional capabilities:

Core Interface (Required)

All apps must implement the App interface:

• Name() string - Returns the app name
• Enabled(config *shizukuconfig.Config) bool - Checks if app is enabled

Optional Interfaces

Apps can optionally implement:

• FileSyncer - For apps that sync configuration files
  • Sync(outDir string, config *shizukuconfig.Config) error
• Installer - For apps that need installation
  • Install(config *shizukuconfig.Config) error
• EnvProvider - For apps that provide environment variables/aliases
  • Env() (*shizukuapp.EnvSetup, error)

Creating a New App

Step 1: Gather Requirements

Ask the user:

1. App name - What is the name of the application? (e.g., "tmux", "alacritty")
2. Default enabled - Should this app be enabled by default? (most apps: true, optional services: false)
3. Installation - Does the app need installation via Homebrew? (y/n)
   • If yes: package name, cask vs formula, any taps needed?
4. File syncing - Does the app need to sync configuration files? (y/n)
   • If yes: destination path (e.g., "~/.config/tmux/")
5. Template data - Does the app need any template variables? (y/n)
6. Remote files - Does the app need to download any remote resources like plugins? (y/n)
7. Environment - Does the app need environment variables or aliases? (y/n)

Step 2: Create Directory Structure

mkdir -p apps/{appName}
# Only create contents/ if the app will sync files
mkdir -p apps/{appName}/contents

Step 3: Create the Go File

Create apps/{appName}/{appName}.go with the appropriate template:

Minimal App (No File Syncing)

package {appName}

import (
	"github.com/eleonorayaya/shizuku/internal/shizukuconfig"
)

type App struct{}

func New() *App {
	return &App{}
}

func (a *App) Name() string {
	return "{appName}"
}

func (a *App) Enabled(config *shizukuconfig.Config) bool {
	return config.GetAppConfigBool(a.Name(), "enabled", {defaultEnabled})
}

App with Installation

package {appName}

import (
	"fmt"

	"github.com/eleonorayaya/shizuku/internal/shizukuconfig"
	"github.com/eleonorayaya/shizuku/internal/util"
)

type App struct{}

func New() *App {
	return &App{}
}

func (a *App) Name() string {
	return "{appName}"
}

func (a *App) Enabled(config *shizukuconfig.Config) bool {
	return config.GetAppConfigBool(a.Name(), "enabled", {defaultEnabled})
}

func (a *App) Install(config *shizukuconfig.Config) error {
	// For Homebrew formula
	if err := util.InstallBrewPackage("{packageName}"); err != nil {
		return fmt.Errorf("failed to install {packageName}: %w", err)
	}

	// For Homebrew cask
	// if err := util.InstallCask("{caskName}"); err != nil {
	//     return fmt.Errorf("failed to install {caskName}: %w", err)
	// }

	// For custom tap
	// if err := util.AddTap("{tapName}"); err != nil {
	//     return fmt.Errorf("failed to add tap: %w", err)
	// }

	return nil
}

App with File Syncing

package {appName}

import (
	"fmt"

	"github.com/eleonorayaya/shizuku/internal/shizukuapp"
	"github.com/eleonorayaya/shizuku/internal/shizukuconfig"
)

type App struct{}

func New() *App {
	return &App{}
}

func (a *App) Name() string {
	return "{appName}"
}

func (a *App) Enabled(config *shizukuconfig.Config) bool {
	return config.GetAppConfigBool(a.Name(), "enabled", {defaultEnabled})
}

func (a *App) Sync(outDir string, config *shizukuconfig.Config) error {
	data := map[string]any{}

	fileMap, err := shizukuapp.GenerateAppFiles("{appName}", data, outDir)
	if err != nil {
		return fmt.Errorf("failed to generate app files: %w", err)
	}

	if err := shizukuapp.SyncAppFiles(fileMap, "{destinationPath}"); err != nil {
		return fmt.Errorf("failed to sync app files: %w", err)
	}

	return nil
}

App with Remote Files

func (a *App) Sync(outDir string, config *shizukuconfig.Config) error {
	data := map[string]any{}

	fileMap, err := shizukuapp.GenerateAppFiles("{appName}", data, outDir)
	if err != nil {
		return fmt.Errorf("failed to generate app files: %w", err)
	}

	remoteFiles := map[string]string{
		"plugins/file.wasm": "https://example.com/file.wasm",
	}
	pluginMap, err := internal.FetchRemoteAppFiles(outDir, "{appName}", remoteFiles)
	if err != nil {
		return fmt.Errorf("failed to fetch remote files: %w", err)
	}
	maps.Copy(fileMap, pluginMap)

	if err := shizukuapp.SyncAppFiles(fileMap, "{destinationPath}"); err != nil {
		return fmt.Errorf("failed to sync app files: %w", err)
	}

	return nil
}

Note: If using maps.Copy, add import: "maps"

App with Environment Variables

func (a *App) Env() (*shizukuapp.EnvSetup, error) {
	return &shizukuapp.EnvSetup{
		Variables: []shizukuapp.EnvVar{
			{Key: "EDITOR", Value: "nvim"},
		},
		Aliases: []shizukuapp.Alias{
			{Name: "vim", Command: "nvim"},
		},
	}, nil
}

Step 4: Register the App

1. Open apps/app.go
2. Add import: "github.com/eleonorayaya/shizuku/apps/{appName}"
3. Add to the return slice in GetApps():

   {appName}.New(),
   

IMPORTANT: Apps are registered in apps/app.go, NOT in cmd/sync/sync.go or cmd/install/install.go. Those commands automatically load all apps via apps.GetApps().

Step 5: Build and Test

task build
task run -- list        # Verify app appears
task run -- install     # Test installation (if implemented)
task run -- sync        # Test file syncing (if implemented)

Configuration System

Checking if App is Enabled

All apps implement Enabled() which checks the config:

func (a *App) Enabled(config *shizukuconfig.Config) bool {
	return config.GetAppConfigBool(a.Name(), "enabled", true)  // default: true
}

• Most apps default to true (core functionality)
• Optional services default to false (protonpass, protonvpn, sfsymbols)

User Config Example

Users can control apps in ~/.config/shizuku/shizuku.yml:

apps:
  nvim:
    enabled: false
  terraform:
    enabled: false
  protonpass:
    enabled: true

Using Other Config Values

Use config.GetAppConfigBool() for boolean values:

useNerdFont := config.GetAppConfigBool(a.Name(), "nerd_font", true)

Use config.GetAppConfig() for other types:

theme, ok := config.GetAppConfig(a.Name(), "theme")
if ok {
	themeStr, ok := theme.(string)
	if ok {
		data["Theme"] = themeStr
	}
}

Adding Template Files

When the user wants to add configuration files to an app:

1. Ask for file path - Relative to contents/ directory (e.g., "config.conf")
2. Ask if it's a template - Does it need variable substitution? (y/n)
3. Create the file - If template, use .tmpl extension
4. Update template data - If template, add necessary variables to the data map in the Sync method

Template Example

If creating contents/config.conf.tmpl:

# {{ .AppName }} Configuration
theme = "{{ .Theme }}"

Update the Sync method:

data := map[string]any{
	"AppName": "MyApp",
	"Theme":   "monade",
}

Modifying Existing Apps

When modifying an app:

1. Read the current Go file to understand existing structure
2. List contents/ to see existing files (if applicable)
3. Make requested changes while preserving the app pattern
4. Ensure all required interfaces are still implemented

Important Notes

• No comments - Don't add comments unless explicitly requested (per CLAUDE.md)
• Error wrapping - Always use fmt.Errorf("context: %w", err) pattern
• Template extension - .tmpl files are processed, extension is removed in output
• File syncing - SyncAppFiles handles directory creation and file copying
• App struct - Always use type App struct{} with New() *App constructor
• Interface implementation - Implement only the interfaces the app needs
• Registration - Apps are registered in apps/app.go, not in command files

Installation Utilities

Available Homebrew utilities in internal/util/homebrew.go:

• InstallBrewPackage(packageName string) error - Install formula (auto-checks if exists)
• InstallCask(caskName string) error - Install cask (auto-checks if exists)
• AddTap(tapName string) error - Add Homebrew tap (auto-checks if exists)
• BrewPackageExists(packageName string) (bool, error) - Check if package is installed

All utilities are idempotent - safe to call multiple times.

Workflow

1. Use TodoWrite to track the scaffolding steps
2. Ask clarifying questions using AskUserQuestion
3. Create all necessary files
4. Update apps/app.go registration
5. Suggest running task build and task run -- list to verify

Examples

Simple App (Installation Only)

• App: rust
• Default enabled: true
• Installation: InstallBrewPackage("rustup")
• No file syncing

App with File Syncing

• App: nvim
• Default enabled: true
• Installation: InstallBrewPackage("neovim")
• Syncs to: ~/.config/nvim/
• Provides: Environment variables (EDITOR=nvim, alias vim=nvim)

Optional Service App

• App: protonpass
• Default enabled: false
• Installation: InstallCask("proton-pass")
• No file syncing

App with Templates

• App: sketchybar
• Default enabled: true
• Installation: Tap + formula
• Syncs to: ~/.config/sketchybar/
• Templates: Uses {{ .Theme }} and other variables

App with Remote Files

• App: zellij
• Default enabled: true
• Installation: InstallBrewPackage("zellij")
• Syncs to: ~/.config/zellij/
• Remote: Downloads zjstatus.wasm plugin from GitHub

App with Custom Installer

• App: kitty
• Default enabled: true
• Installation: Uses curl installation script (not Homebrew)
• Syncs to: ~/.config/kitty/