chaakoo

README

chaakoo

1. Introduction
2. Configuration
3. Using Chaakoo
4. Examples
5. Download
6. License

Introduction

Chaakoo is a wrapper over TMUX that can create sessions, windows and panes from a grid based layout. The idea here is inspired by the CSS grid template areas.

For example, this grid:

vim  vim  vim  term
vim  vim  vim  term
play play play play

will create the following layout:

The layout can be a little complex too based on the further pane divisions, like,

arandr  arandr  bzip    cat
vim     vim     err     cat
vim     vim     file    file
grafana grafana grafana grafana
grafana grafana grafana grafana

Configuration

A configuration yaml for one window with 3 panes, like, the first example, is here:

name: code-environment
windows:
  - grid: |
      vim  vim  vim  term
      vim  vim  vim  term
      play play play play
    name: window1
    commands:
      - pane: vim
        command: |
          vim
      - pane: term
        command: |
          cd ~
          systemctl status
        workdir: /home/waterbottle/code
      - pane: play
        command: |
          tail -f /var/log/messages

• name is the TMUX session name
• windows is an array of windows
• Each window contains
  • name - The name of the window
  • grid - 2D layout or the grid, each distinct name in the layout represents a pane.
  • commands is an array of the commands that will be executed in a pane
  • Each command object contains:
    • pane - Name of the pane
    • command - Can contain multi line text for the commands
    • workdir - Pane's first directory. It can further be changed by cd present in command

Note: The commands section or commands for a pane are not a required field. Chaakoo can just be used to create the pane layout and then the user can take over and execute their commands.

Using Chaakoo

• Starting a session

# Start a TMUX server
$ tmux start-server

# and then pass the config to Chaakoo
$ chaakoo -c examples/1/chaakoo.yaml 
4:43PM ERR github.com/NoF0rte/chaakoo/tmux_wrapper.go:349 > unable to get the list of the present sessions error="exit status 1" sessionName=code-environment stderr="no server running on /tmp/tmux-1000/default\n" stdout=
4:43PM INF github.com/NoF0rte/chaakoo/cmd/chaakoo.go:66 > session created successfully, it can be attached by executing:
4:43PM INF github.com/NoF0rte/chaakoo/cmd/chaakoo.go:67 > tmux a -t code-environment

# Attach the TMUX session
$ tmux a -t code-environment

• Starting with the --verbose or -v flag will set the log level to DEBUG and time format to RFC3339

$ chaakoo -c examples/1/chaakoo.yaml -v
2021-09-26T16:47:50+05:30 DBG github.com/NoF0rte/chaakoo/cmd/chaakoo.go:128 > setting global log level to DEBUG as verbose log is enabled
2021-09-26T16:47:50+05:30 DBG github.com/NoF0rte/chaakoo/cmd/chaakoo.go:98 > using examples/1/chaakoo.yaml
2021-09-26T16:47:50+05:30 DBG github.com/NoF0rte/chaakoo/cmd/chaakoo.go:114 > using config file: examples/1/chaakoo.yaml
2021-09-26T16:47:50+05:30 DBG github.com/NoF0rte/chaakoo/cmd/chaakoo.go:50 > finding the dimensions
2021-09-26T16:47:50+05:30 DBG github.com/NoF0rte/chaakoo/cmd/chaakoo.go:56 > found dimensions height=81 width=274
-- more logs --

• For more info:

$ chaakoo --help
chaakoo converts the 2D grids or matrix into TMUX windows and panes

Usage:
  chaakoo [flags]

Flags:
  -c, --config string   config file (default is ./chaakoo.yaml)
  -d, --dry-run         if true then commands will only be shown and not executed
  -e, --exit-on-error   if true then chaakoo will exit after it encounters the first error during command execution
  -r, --height int      terminal dimension for rows or height, if 0 then rows and cols will be found internally
  -h, --help            help for chaakoo
  -v, --verbose         enable verbose logging
  -V, --version         print the version
  -w, --width int       terminal dimension for cols or width

Examples

There are more examples present in the examples directory with configurations and snapshots.

Download

The latest binary can be downloaded from the latest GitHub release. The binaries are statically linked.

Or

$ go install github.com/NoF0rte/chaakoo/cmd/chaakoo@v0.0.4

License

Copyright 2021 Pallav Jha

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Documentation

Index

• Variables
• func PrepareGrid(gridKey string) ([][]string, error)
• type Command
• type CommandExecutor
  • func NewCommandExecutor() *CommandExecutor
  • func (c *CommandExecutor) Execute(name string, args ...string) (string, string, int, error)
• type Config
  • func (c *Config) Parse() error
  • func (c *Config) Validate() error
• type Dimension
  • func NewDimension(width int, height int) *Dimension
• type DimensionUsingTerm
  • func (d *DimensionUsingTerm) Dimension() (*Dimension, error)
• type ICommandExecutor
• type NOOPExecutor
  • func NewNOOPExecutor() *NOOPExecutor
  • func (c *NOOPExecutor) Execute(name string, args ...string) (string, string, int, error)
• type Pane
  • func PrepareGraph(grid [][]string) (*Pane, error)
  • func (p *Pane) AddBottomPane(bottomPane *Pane)
  • func (p *Pane) AddLeftPane(leftPane *Pane)
  • func (p *Pane) AsGrid() [][]string
  • func (p *Pane) Height() int
  • func (p *Pane) Width() int
• type Session
• type TerminalDimension
• type TmuxCmdResponse
• type TmuxError
  • func NewTmuxError(stdout, stderr string, err error) *TmuxError
  • func (t *TmuxError) Error() string
• type TmuxWrapper
  • func NewTmuxWrapper(config *Config, dimensions *Dimension) *TmuxWrapper
  • func (t *TmuxWrapper) Apply() error
• type Window
  • func (w *Window) Parse() error
  • func (w *Window) Validate() error
• type WindowOptions

Variables

var CommandName = "tmux"

CommandName contains the tmux name. Not hardcoded in the command itself because it can be used in testcases to run a mock command

var ErrInvalidDimensionError = errors.New("invalid grid found! all rows must have same number of columns and vice versa")

ErrInvalidDimensionError is returned if the grid has invalid dimensions

Functions

func PrepareGrid

func PrepareGrid(gridKey string) ([][]string, error)

PrepareGrid converts the freetext grid into a 2D string array

Types

type Command

type Command struct {
	Name             string `mapstructure:"pane"`
	CommandText      string `mapstructure:"command"`
	WorkingDirectory string `mapstructure:"workdir"`
}

Command represents a command fragment that will be executed in the pane whose name will be same as name in this struct. WorkingDirectory is the location in which all the commands will be executed. The working directory can be passed to tmux split-window command with -c flag but doing that will not create the pane if the working directory is wrong. So, in this implementation, passing the working directory is deferred until the pane has been created.

type CommandExecutor

type CommandExecutor struct {
}

CommandExecutor implements the command execution on a shell

func NewCommandExecutor

func NewCommandExecutor() *CommandExecutor

NewCommandExecutor constructs a CommandExecutor

func (*CommandExecutor) Execute

func (c *CommandExecutor) Execute(name string, args ...string) (string, string, int, error)

Execute the provided command The first arg is the command name.

type Config

type Config struct {
	Sessions    []*Session `mapstructure:"sessions"`
	DryRun      bool
	ExitOnError bool
}

Config holds the entire config

func (*Config) Parse

func (c *Config) Parse() error

Parse delegates to Window.Parse

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the config The error messages contain contextual information related to the validation issues

type Dimension

type Dimension struct {
	Width  int
	Height int
}

Dimension represents the dimension of the terminal in which binary is executed in.

func NewDimension

func NewDimension(width int, height int) *Dimension

NewDimension constructs a dimension

type DimensionUsingTerm

type DimensionUsingTerm struct {
}

DimensionUsingTerm uses golang/x/term to find the dimensions of the current shell. There can be other implementations using:

• tput cols and tput size
• stty size

func (*DimensionUsingTerm) Dimension

func (d *DimensionUsingTerm) Dimension() (*Dimension, error)

Dimension fails if the binary is being executed in a terminal

type ICommandExecutor

type ICommandExecutor interface {
	Execute(name string, args ...string) (string, string, int, error)
}

ICommandExecutor is implemented by command executor

type NOOPExecutor

type NOOPExecutor struct {
}

NOOPExecutor is used for dry runs

func NewNOOPExecutor

func NewNOOPExecutor() *NOOPExecutor

NewNOOPExecutor is a constructor for NOOPExecutor

func (*NOOPExecutor) Execute

func (c *NOOPExecutor) Execute(name string, args ...string) (string, string, int, error)

Execute just logs the command TODO: return the result based on some logic and conditions instead of hard coded results

type Pane

type Pane struct {
	Name    string  // Name of the pane
	XStart  int     // First index in the horizontal direction
	XEnd    int     // Last index in the horizontal direction
	YStart  int     // First index in the vertical direction
	YEnd    int     // Last index in the vertical direction
	Visited bool    // If this node was visited while traversal
	Left    []*Pane // Collection of the panes to the left of the current pane
	Bottom  []*Pane // Collection of the panes to the bottom of the current pane
	// contains filtered or unexported fields
}

Pane represents a TMUX pane in a 2D grid

func PrepareGraph

func PrepareGraph(grid [][]string) (*Pane, error)

PrepareGraph converts a 2D grid into a graph of panes It returns the first pane that will contain further panes based on the hierarchy

func (*Pane) AddBottomPane

func (p *Pane) AddBottomPane(bottomPane *Pane)

AddBottomPane appends a bottom pane to the current pane

func (*Pane) AddLeftPane

func (p *Pane) AddLeftPane(leftPane *Pane)

AddLeftPane appends left pane to the current pane

func (*Pane) AsGrid

func (p *Pane) AsGrid() [][]string

AsGrid returns the 2D string array representation of the Pane

func (*Pane) Height

func (p *Pane) Height() int

Height returns the height of the pane

func (*Pane) Width

func (p *Pane) Width() int

Width returns the width of the pane

type Session

type Session struct {
	Name    string    `mapstructure:"name"`
	Windows []*Window `mapstructure:"windows"`
}

Session represents one TMUX session from the config

type TerminalDimension

type TerminalDimension interface {
	Dimension() (*Dimension, error)
}

TerminalDimension can be implemented by the providers of terminal dimensions

type TmuxCmdResponse

type TmuxCmdResponse struct {
	SessionID string
	WindowID  string
	PaneID    string
}

TmuxCmdResponse is a parsed response from Tmux commands

type TmuxError

type TmuxError struct {
	// contains filtered or unexported fields
}

TmuxError is returned after the execution of TMUX commands

func NewTmuxError

func NewTmuxError(stdout, stderr string, err error) *TmuxError

NewTmuxError is a constructor TmuxError

func (*TmuxError) Error

func (t *TmuxError) Error() string

Error implemented for error interface

type TmuxWrapper

type TmuxWrapper struct {
	// contains filtered or unexported fields
}

TmuxWrapper implements the logic to convert the pane and config into TMUX panes and command executions

func NewTmuxWrapper

func NewTmuxWrapper(config *Config, dimensions *Dimension) *TmuxWrapper

NewTmuxWrapper constructs a TmuxWrapper

func (*TmuxWrapper) Apply

func (t *TmuxWrapper) Apply() error

Apply does on each session:

• checks if the requested session is already present
• creates a new session for the current config
• creates windows and panes
• executes the command of the provided config

type Window

type Window struct {
	Name      string `mapstructure:"name"`
	Grid      string `mapstructure:"grid"`
	FirstPane *Pane
	Commands  []*Command     `mapstructure:"commands"`
	Options   *WindowOptions `mapstructure:"options"`
}

Window represents one TMUX window from the config

func (*Window) Parse

func (w *Window) Parse() error

Parse - parses the config

func (*Window) Validate

func (w *Window) Validate() error

Validate validates a Window related config

type WindowOptions

type WindowOptions struct {
	SynchronizePanes bool `mapstructure:"sync"`
}