LILPACK -- Package System for Lilush

Required keys

Optional keys

Builtin descriptors

A package can provide shell builtins by declaring them in the manifest:

[{"module": "shell.builtins.k8s", "commands": ["ktl"]}]

The module field names the module within the package that returns a builtin family table (same format as built-in families like shell.builtins.fs). The module is loaded via require() during shell startup.

Mode descriptors

A package can provide shell modes:

[{
    "name": "agent",
    "path": "agent.mode.agent",
    "history": true,
    "prompt": "agent.mode.agent.prompt",
    "completion": {
        "path": "agent.completion.slash",
        "sources": ["agent.completion.source.slash"]
    }
}]

Mode descriptors do NOT include shortcut assignments. Users map F-keys to package modes via ~/.config/lilush/modes.json:

{
    "F4": "agent",
    "F5": "k8s-dashboard"
}

Each key is an F-key, each value is a LILPACK name whose first mode descriptor is activated on that key.

CLI script descriptors

A package can provide standalone CLI commands that are installed as executable scripts in ~/.local/bin/:

["mytool", "myutil"]

Each entry is a command name. The corresponding Lua source must exist in the cli/ subdirectory of the source tree (e.g. cli/mytool.lua). On install, each script is written to ~/.local/bin/<command> with a #!/usr/bin/env lilush shebang prepended (if not already present) and made executable.

CLI scripts are independent files -- they do not participate in module loading. Scripts that need LILPACK modules must initialise the searcher chain themselves:

local lilpack = require("lilpack")
lilpack.init()
local mylib = require("mypackage.utils")

Theme descriptors

A package can extend the theme system by providing section builders (styles for a specific mode) and/or complete theme definitions (palette + overrides).

The theme manifest field is an object with two optional sub-fields:

Section builders — provide styles for a named theme section:

{
    "theme": {
        "sections": [
            {"name": "agent", "builder": "agent.theme"}
        ]
    }
}

The builder field names a module that returns a function. The function receives the active palette table and returns an RSS table for the section. It is called each time the theme changes to rebuild section styles from the new palette.

Theme definitions — provide a complete selectable theme:

{
    "theme": {
        "definition": {
            "name": "solarized",
            "module": "solarized.theme"
        }
    }
}

The module field names a module that returns a table in the same format as bundled catalog entries: { palette = {...}, shell = {...}, markdown = {...} }.

A single package can declare both sections and definition if needed.

See THEMES for the full theme architecture and API.

Official Lilush Packages repo

By default lilpack install will try to install remote packages from the official Lilush Packages HTTP Repo. This can be overriden with the LILPACK_REPO_URL environment variable.

Packages in the official HTTP repo are built from the lilpacks repositories listed at git.lilush.link.

Repo layout and serving

The repo is a flat directory of static files served over HTTP. Each package contributes exactly one file, <name>.lilpack, holding its latest published version. lilpack install <name> is a plain GET <repo>/<name>.lilpack. There is no index file and no per-version history: publishing a new version overwrites the file. Dependency version constraints are therefore satisfied against whatever is current — see Dependencies.

Publishing (tag-driven)

Publishing is tied to git tags, not to commits. The published version is taken from the tag, overriding the version in lilpack.json (which then serves only as a dev/local default). Tags are bare X.Y.Z (no v prefix).

lilpack pack supports two options for this:

• --version <X.Y.Z> — set the packed pkg_version (and thus the signed digest), overriding lilpack.json.

• --publish <dir> — after packing+signing, write the artifact to <dir>/<name>.lilpack (the name comes from the manifest), using the same atomic temp+rename as a normal pack.

A package repo couples tags to releases with a git reference-transaction hook (git has no native post-tag hook). On creation of a bare semver tag it packs and publishes; non-semver tags and branch updates are ignored. The hook needs line parsing and a loop, which LSH does not provide, so it is a lilush Lua script (lilush runs any file passed to it as Lua, with the hook arguments in the global arg table):

#!/usr/bin/env lilush
-- .githooks/reference-transaction  (git config core.hooksPath .githooks)
-- arg[1] is the transaction state; ref updates arrive on stdin as
-- "<old> <new> <refname>" lines.
if arg[1] ~= "committed" then
    os.exit(0)
end
local site = os.getenv("LILPACK_SITE_DIR")
if not site then
    os.exit(0)
end
local lilpack = require("shell.builtins.lilpack")
for line in io.lines() do
    local _, _, ref = line:match("^(%S+)%s+(%S+)%s+(%S+)$")
    local tag = ref and ref:match("^refs/tags/(%d+%.%d+%.%d+%S*)$")
    if tag then
        lilpack["lilpack"].func("lilpack", { "pack", ".", "--version", tag, "--publish", site })
    end
end

LILPACK_SITE_DIR is the document root served at the repo URL, and LILPACK_SIGN_KEY must be set for the hook's signing step.

Environment variables

Signing (lilpack pack)

lilpack pack requires LILPACK_SIGN_KEY to be set:

1. Reads the OpenSSH ed25519 private key (must be unencrypted)

2. Computes a canonical SHA-256 digest over all package content

3. Signs the digest with Ed25519

4. Stores the 64-byte signature and 32-byte pubkey in __lilpack

The embedded pubkey must exactly match the trusted verification key. Packages with a mismatched embedded key are rejected.

Verification (lilpack install)

lilpack install always verifies signatures before installing:

• Verification passes -- installed

• Verification fails -- rejected

• No trusted key available -- rejected

Verification at load time (lilpack.init)

Every package is verified when the package system initialises. The built-in public key is used by default; LILPACK_PUB_KEY overrides it. Verification requires both:

• the embedded pubkey matches the trusted key

• the signature verifies against that key

• Verification passes -- loaded

• Verification fails -- skipped with error

• No trusted key available -- no packages loaded

Canonical digest algorithm

The digest is a SHA-256 hash over a deterministic serialization of all package content (excluding signature and pubkey):

1. Manifest fields in fixed order: version, name, pkg_version, description, modules, author, license, dependencies, builtins, modes, cli, theme, min_lilush_version. Each present field contributes key=tostring(value)\0.

2. Module sources in sorted name order. Each module contributes module:name=source\0.

3. CLI script sources in sorted name order. Each script contributes cli:name=source\0.

4. All parts are concatenated and hashed with SHA-256.

Key fingerprints

Public key fingerprints are the first 16 hex characters of SHA-256 over the raw 32-byte public key. Displayed by lilpack info and lilpack verify.

Examples

# Pack and sign a source directory:
setenv LILPACK_SIGN_KEY ${HOME}/.ssh/lilpack_sign.ed
lilpack pack /path/to/lilpack/source

# Pack with a tag-derived version, publishing to the repo doc root:
lilpack pack . --version 0.3.0 --publish ${LILPACK_SITE_DIR}

# Install a package from the repo (pulls dependencies automatically):
lilpack install llm

# Install a local file (verified against the built-in key):
lilpack install llm-0.1.0.lilpack

# Install with a custom trusted key:
setenv LILPACK_PUB_KEY ${HOME}/.ssh/lilpack_sign.pub
lilpack install llm-0.1.0.lilpack

# Verify a package without installing:
lilpack verify llm-0.1.0.lilpack -k ~/.ssh/lilpack_sign.pub