# Lilush: the next small thing

![Lilush logo](images/logo.png)

## Overview

_Lilush_ is a statically compiled for Linux [LuaJIT](https://luajit.org/) runtime with
a bundled collection of Lua modules and C libraries. 

It comes in two flavors: slim `lilu` build, and a bigger one `lilush` build.

## `lilu` — Static LuaJIT runtime with batteries

_lilu_ is a minimal _lilush_ build. It comes with

* File system operations and process manipulation
* TCP/UDP networking with TLS 1.3 support; HTTP(S) client, HTTP(S)/1.1 server
* Cryptography: hashing, HMAC, Ed25519, X.509
* Terminal I/O with UTF-8 support, widgets, styling with *TSS* (Terminal Style Sheets)
* Markdown processing/rendering
* [MNEME](docs/MNEME.md) embedded K/V database, supporting full text search and encryption at rest
* Redis & [WireGuard](https://www.wireguard.com/embedding/) clients

For networking, _lilu_ uses [LEV](docs/LEV.md) — a coroutine-based async I/O
runtime built on Linux `epoll` with TLS 1.3 support via [LITLS](docs/LITLS.md).

The binary is smaller than **2MB**, and should work fine on any *x86_64 Linux*
system.

## `lilush` — Linux Lua Shell, Graphics & Audio engines

The full `lilush` build extends `lilu` with a modular Linux Shell (as in Bash, Csh or Fish).
The shell is called _Lilush Shell_, and it

* is there to humour my whims and fancies
* provides a rather handsome CLI interface straight out of the box:

    * Pre-configured prompts: `host`, `user`, `dir`, `git`, `python venv`
    * Command completions, completions scrolling
    * Fast directory navigation and history search, similar to [McFly](https://github.com/cantino/mcfly) and [zoxide](https://github.com/ajeetdsouza/zoxide)
    * [Terminal graphics](https://sw.kovidgoyal.net/kitty/graphics-protocol/) support

* has some handy shell builtins like `kat` (file viewer + pager), `lem` text editor, `netstat`, `dig`, `wgcli`, etc.
* is styled and themeable via TSS
* is easily extendable with plugins
* can do fortune telling and will probably one day save humanity

Besides shell the full `lilush` build includes graphics & audio engines, and can
be used as a game engine framework.

::: warning  

_Lilush Shell_ relies on a bunch of [Kitty's protocol extensions](https://sw.kovidgoyal.net/kitty/protocol-extensions/),
namely keyboard protocol, text sizing, and terminal graphics. Thus all features are only guaranteed to work in **Kitty**,
or terminals that fully implement those extensions.

:::  

# Installation

Download the `lilush`/`lilu` binary and the matching `lilush.sig`/`lilu.sig`
signature file from [Lilush Releases](https://lilush.link/releases/).

```bash
# Latest release; use a version instead of `latest` to pin, e.g. releases/0.8.6/
BINARY="lilu"
curl -fLO "https://lilush.link/releases/latest/${BINARY}"
curl -fLO "https://lilush.link/releases/latest/${BINARY}.sig"
```

## Verify release signature

Lilush release binaries are signed with an SSH key (`namespace=file`). The
signing key is published at [deviant.guru/keys](https://deviant.guru/keys).

```bash
# Create allowed signers file with the release signing key
cat > allowed_signers <<'EOF'
vladimir@deviant.guru ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICEWU0xshVgOIyjzQEOKtjG8sU8sWJPh25CP/ISfJRey
EOF

# Verify signature
ssh-keygen -Y verify \
  -f allowed_signers \
  -I vladimir@deviant.guru \
  -n file \
  -s ${BINARY}.sig < ${BINARY}
```

If verification succeeds, `ssh-keygen` prints `Good "file" signature for vladimir@deviant.guru ...`.

Each release directory also carries a signed `SHA256SUMS`:

```bash
curl -fLO "https://lilush.link/releases/latest/SHA256SUMS"
curl -fLO "https://lilush.link/releases/latest/SHA256SUMS.sig"
ssh-keygen -Y verify -f allowed_signers -I vladimir@deviant.guru \
  -n file -s SHA256SUMS.sig < SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
```

### Install `lilu`

```bash
chmod +x lilu
# Install system-wide:
sudo install -Dm755 lilu /usr/local/bin/lilu
# Or user install, make sure `~/.local/bin` is in your `PATH`
install -Dm755 lilu ~/.local/bin/lilu
# Use
lilu -e 'print("Hello from lilu!")'
lilu /path/to/my_script.lua
```

### Install `lilush`

```bash
chmod +x lilush
# Install system-wide, in /usr/bin/:
sudo install -Dm755 lilush /usr/bin/lilush
# Or under `/usr/local/bin`
sudo install -Dm755 lilush /usr/local/bin/lilush
# or user install somewhere in your `PATH`...
# start Lilush Shell:
lilush
```

## Building from source

See [DEVELOPMENT.md](docs/DEVELOPMENT.md)

## Documentation

[Documentation Index](INDEX.md) references all documents available
in the repository.

Documentation on core Lilush modules API:

* is available at [Lilush API docs website](https://docs.lilush.link)
* available during runtime via wiki mode (**F3**) in _Lilush Shell_

See [LIMAN](https://git.lilush.link/lilpacks/liman/blob/master/README.md) for instructions on how to generate the 
runtime documentation database.

# Status

Right now the project is certainly in beta. 

After `1.0.0` version release the project will abide by the semantic versioning promises,
but until then all bets are off. Meaning that there might be breaking changes of the core 
lilush modules' API even between, say, `0.5.x` and `0.6.x`. Or worse.
But let's hope it won't come to that.