reeflective / console

Closed-loop application library for Cobra commands (powerful, ready-to-run and easy to use)

Console

Closed-loop application library for Cobra commands

(ready-to-use menus, prompts, completions, and more)

Console is an all-in-one console application library built on top of a readline shell and using Cobra commands. It aims to provide users with a modern interface at at minimal cost while allowing them to focus on developing their commands and application core: the console will then transparently interface with these commands, and provide the various features below almost for free.

Features

Menus & Commands

• Bind cobra commands to provide the core functionality.
• Multiple menus with their own command tree, prompt engines and special handlers.
• All cobra settings can be modified, set and used freely, like in normal CLI workflows.
• Bind handlers to special interrupt errors (eg. CtrlC/CtrlD), per menu.

Shell interface

• Shell is powered by a readline instance, with full inputrc support and extended functionality.
• All features of readline are supported in the console. It also allows the console to give:
• Configurable bind keymaps, commands and options, sane defaults, and per-application configuration.
• Out-of-the-box, advanced completions for commands, flags, positional and flag arguments.
• Provided by readline and carapace: automatic usage & validation command/flags/args hints.
• Syntax highlighting for commands (might be extended in the future).

Others

• Support for an arbitrary number of history sources, per menu.
• Support for oh-my-posh prompts, per menu and with custom configuration files for each.
• Also with oh-my-posh, write and bind application/menu-specific prompt segments.
• Set of ready-to-use commands (commands/ directory) for readline binds/options manipulation.

Documentation

You can install and use the example application console. This example application will give you a taste of the behavior and supported features. The following documentation is also available in the wiki:

• Getting started
• Menus
• Prompts
• Binding commands
• Interrupt handlers
• History Sources
• Logging
• Readline shell
• Other utilities

Showcase

Status

The library is in a pre-release candidate status:

• Although quite simple and small, it has not been tested heavily.
• There are probably some features/improvements to be made.
• The API is quite stable. It is unlikely to change much in future versions.

Please open a PR or an issue if you wish to bring enhancements to it. Other contributions, as well as bug fixes and reviews are also welcome.

Possible Improvements

The following is a currently moving list of possible enhancements to be made in order to reach v1.0:

• Ensure to the best extent possible a thread-safe access to the command API.
• Clearer integration/alignment of the various I/O references between readline and commands.
• Clearer and sane model for asynchronous control/cancel of commands.
• Allow users to run the console command trees in one-exec style, with identical behavior.
• Test suite for most important or risky code paths.
• Set of helper functions for application-related directories.

console's Issues

Entering backslash character '\' on windows causes null byte input '\x00'

I was debating whether to post this here or on the readline issue page.

Affects

Windows only - works fine on Ubuntu and MacOS
I'm using version 0.1.6 of console and 1.0.12 of readline.

Issue

Whenever entering the backslash character, nothing seems to happen. However invisible null chars are sent the prompt, so that when I hit 'enter' I'll get 'unknown command "\x00" for ...'.

Now Sliver uses the same library and doesn't seem to share this issue for Windows builds. What I've also noticed is that my typing prompt (on cmd.exe) is a block cursor, while Sliver's is a regular line cursor. So perhaps it is a setting that I haven't explored. Note too, that the same versions of both readline and console are in use. Your support would be appreciated!

can't install example

go install github.com/reeflective/console/example

github.com/reeflective/console

/home/tester/go/pkg/mod/github.com/reeflective/[email protected]/tab-completer.go:34:27: undefined: carapace.Complete

Inconsistent treatment of backslashes in completion context.

SUMMARY

Currently this library might suffer from sometimes slightly inconsistent behaviors between the buffer being executed and the one being completed. These inconsistencies are almost invariably due to backslash management. Some of these have been raised in #38.

Here I aim to do a recap so that anyone facing a behavior/bug that is not acceptable to them, might be able to at least burn a couple brain calories on how to fix all of this uniformly. Best case scenario being a code contribution.

State of the buffer before EXECUTION

Currently, the input line buffer is parsed with the github.com/mvdan/sh package, so that the console enables users to include comments in their command lines (saved in history), with those comments stripped before exec:

example [main] > root subcommand --flag value-for-flag \
                 --another-flag file.json # With a comment here, saved in hist but stripped before exec.

The executed line is in effect:

root subcommand --flag value-for-flag --another-flag file.json

The following example will even work in the example app:

example [main] in playground/console/example
> git checkout # This is a comment
  --create testing # And this is another
  --force                                                                                         12:29:42.649

Running git checkout command with branch: testing

State of the buffer before COMPLETION

The parsing code for the line in the completion context is entirely different (copied from this package and slightly modified). This is so that we can take more freedoms on what to pass to the completion context. The added cost however have been until now some inconsistent behavior here and there.

The line splitting code used before sending arguments to the completion engine is here.

Console incompatible with bubbletea progress bar.

bubbletea progress bar

When using console with bubbletea progress bar, a new prompt line will display incorrectly, and cannot read input lines.

Reusing a command after using the 'help' flag fails

Details

After running <cmd> --help once, the command does not work again. It simply continues to show the help message.

ApplicationName > help
Usage:
   [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  hw          

Flags:
  -h, --help   help for this command

Use " [command] --help" for more information about a command.
ApplicationName > hw
Hello World!
ApplicationName > hw -h
Usage:
   hw [flags]

Flags:
  -h, --help   help for hw
ApplicationName > hw
Usage:
   hw [flags]

Flags:
  -h, --help   help for hw

Failed to use import the module and run it locally

haha@ubuntu:~/Documents/testconsole$ tree
.
├── go.mod
├── go.sum
└── main.go

0 directories, 3 files
haha@ubuntu:~/Documents/testconsole$ cat main.go
package main

import (
        "github.com/reeflective/console"
)

func main() {
        app := console.New("start")
        app.Start()
}
haha@ubuntu:~/Documents/testconsole$ go run .
# github.com/reeflective/console
../../go/pkg/mod/github.com/reeflective/[email protected]/completer.go:32:27: undefined: carapace.Complete
h

Run the console/example without no problem. But when I tried to test the code outside the console folder, it failed with the same message. Then I tried with minimal app.Start() provides the same error message.
What should I do to make my code run using the console library?