feat(lucebox): hub CLI + autotune/sweep/profile + harness adapters + shell wrapper

.github/workflows/ci.yml

@@ -34,6 +34,35 @@ jobs:
       - name: Lint Python surfaces touched by lucebox tooling
         run: uv run --frozen --extra dev ruff check .
 
+      - name: Install shellcheck (for bash test runner)
+        # ubuntu-latest typically ships shellcheck pre-installed, but pin
+        # the dependency explicitly so the bash test runner can always rely
+        # on `command -v shellcheck` succeeding.
+        run: |
+          if ! command -v shellcheck >/dev/null 2>&1; then
+            sudo apt-get update
+            sudo apt-get install -y shellcheck
+          fi
+          shellcheck --version | head -3
+
+      - name: Typecheck lucebox CLI
+        run: uv run --frozen --extra dev python -m mypy --package lucebox
+
+      - name: Unit-test lucebox CLI
+        # The fast workspace sync above is enough: the suite mocks the
+        # docker / HTTP surfaces, so no torch wheel or GPU is needed.
+        # Keeps the lucebox Python honest on every push.
+        run: uv run --frozen --extra dev pytest lucebox -q
+
+      - name: Smoke-test lucebox.sh wrapper
+        # Catches `set -u` regressions, syntax errors, and stale dispatch
+        # handlers in the host-side wrapper + the in-container entrypoint.
+        # Runs shellcheck --severity=error across every shipped .sh file,
+        # exercises every subcommand dispatch under `set -u`, and drives the
+        # entrypoint's draft-resolution block through every family-glob
+        # branch — all on the bare runner without docker/nvidia/systemd.
+        run: bash scripts/test_lucebox_sh.sh
+
   build:
     name: Build (cmake + uv sync --extra megakernel)
     runs-on: ubuntu-latest

install.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# install.sh — Bootstrap installer for the lucebox host wrapper.
+#
+# Canonical install (Luce-Org main, stable channel):
+#
+#   curl -fsSL https://raw.githubusercontent.com/Luce-Org/lucebox-hub/main/install.sh | bash
+#
+# Install from a different fork / branch (dev channel). Note the env var
+# is on the `bash` side of the pipe — `VAR=val curl … | bash` would attach
+# it to the `curl` process, leaving `bash` with the canonical default:
+#
+#   curl -fsSL https://raw.githubusercontent.com/easel/lucebox-hub/feat/lucebox-docker/install.sh | \
+#     LUCEBOX_INSTALL_URL=https://raw.githubusercontent.com/easel/lucebox-hub/feat/lucebox-docker/lucebox.sh bash
+#
+# The installer bakes the source URL into the installed `lucebox.sh` as
+# `LUCEBOX_INSTALLED_FROM=...`, so `lucebox update` later re-pulls from the
+# same channel without the user having to remember which fork they used.
+#
+# Override the install destination via $LUCEBOX_INSTALL_DEST (default
+# $HOME/.local/bin/lucebox). This is what `lucebox update` uses to replace
+# the file in place.
+
+set -euo pipefail
+
+LUCEBOX_INSTALL_URL="${LUCEBOX_INSTALL_URL:-https://raw.githubusercontent.com/Luce-Org/lucebox-hub/main/lucebox.sh}"
+DEST="${LUCEBOX_INSTALL_DEST:-$HOME/.local/bin/lucebox}"
+
+# ── helpers ───────────────────────────────────────────────────────────────
+C_OK=$'\033[1;32m' ; C_ERR=$'\033[1;31m' ; C_DIM=$'\033[2m' ; C_RST=$'\033[0m'
+if [ ! -t 1 ] || [ "${NO_COLOR:-}" ]; then
+    C_OK="" ; C_ERR="" ; C_DIM="" ; C_RST=""
+fi
+info() { printf '%s[install]%s %s\n' "$C_DIM" "$C_RST" "$*"; }
+ok()   { printf '%s[install] ✓%s %s\n' "$C_OK"  "$C_RST" "$*"; }
+die()  { printf '%s[install] ✗%s %s\n' "$C_ERR" "$C_RST" "$*" >&2; exit 1; }
+
+command -v curl >/dev/null 2>&1 || die "curl is required (apt-get install curl)"
+
+# ── fetch ─────────────────────────────────────────────────────────────────
+tmp=$(mktemp -t lucebox.XXXXXX) || die "couldn't create temp file"
+# shellcheck disable=SC2064  # we want $tmp expanded now, not at trap time
+trap "rm -f '$tmp' '$tmp.bak'" EXIT
+info "fetching $LUCEBOX_INSTALL_URL"
+curl -fsSL "$LUCEBOX_INSTALL_URL" -o "$tmp" \
+    || die "download failed from $LUCEBOX_INSTALL_URL"
+
+# ── sanity check ──────────────────────────────────────────────────────────
+# Refuse to install something that isn't recognizably lucebox.sh. Catches
+# 404 pages, redirects to HTML, and accidental URL typos.
+head -1 "$tmp" | grep -q '^#!/usr/bin/env bash$' \
+    || die "downloaded file does not look like a bash script (got: $(head -1 "$tmp"))"
+grep -q '^VERSION=' "$tmp" \
+    || die "downloaded file is missing VERSION marker — not lucebox.sh?"
+
+# ── decide what gets baked in as the persisted channel ───────────────────
+# `lucebox update` reads LUCEBOX_INSTALLED_FROM from the installed copy and
+# re-fetches from it. Persisting a SHA-pinned URL is a footgun — every
+# future update would re-install the same frozen SHA forever, defeating
+# the point of `update`. So:
+#
+#   1. If $LUCEBOX_INSTALL_CHANNEL is set, that's the persisted URL
+#      (caller takes responsibility for picking a real branch URL).
+#   2. Else if LUCEBOX_INSTALL_URL has a 40-char hex SHA segment, refuse
+#      to persist it — tell the user to set LUCEBOX_INSTALL_CHANNEL.
+#      Common case: someone curl'd from /raw/<sha>/ to bypass a stale CDN
+#      cache during dev; they meant for updates to track the branch.
+#   3. Else persist LUCEBOX_INSTALL_URL as-is (branch or canonical main).
+channel_url="${LUCEBOX_INSTALL_CHANNEL:-}"
+if [ -z "$channel_url" ]; then
+    # Match a full 40-char hex SHA in the URL path, not the broader
+    # {7,40} range — a 7-39 char hex segment is more likely a branch
+    # name shaped like a short SHA (e.g. `feat/abc1234-hotfix`) than an
+    # actual SHA-pin. Keeping the gate at exactly 40 chars matches what
+    # `git rev-parse HEAD` emits and what `/raw/<sha>/` URLs from
+    # GitHub's CDN actually carry.
+    if [[ "$LUCEBOX_INSTALL_URL" =~ /[0-9a-fA-F]{40}/[^/]+\.sh$ ]]; then
+        die "$(cat <<EOM
+LUCEBOX_INSTALL_URL is SHA-pinned ($LUCEBOX_INSTALL_URL).
+Persisting that as LUCEBOX_INSTALLED_FROM would freeze \`lucebox update\`
+to that specific commit forever. Set LUCEBOX_INSTALL_CHANNEL to the
+branch URL you want \`update\` to track, e.g.:
+
+  curl -fsSL <sha-pinned>/install.sh | \\
+    LUCEBOX_INSTALL_URL=<sha-pinned>/lucebox.sh \\
+    LUCEBOX_INSTALL_CHANNEL=https://raw.githubusercontent.com/<org>/<repo>/<branch>/lucebox.sh \\
+    bash
+EOM
+)"
+    fi
+    channel_url="$LUCEBOX_INSTALL_URL"
+fi
+
+# Bake the channel URL into the file. Use a `|` delimiter since URLs
+# contain `/`. The line is expected to exist in lucebox.sh with a `:-`
+# default; we rewrite the whole assignment.
+#
+# The URL ends up inside a bash double-quoted literal in the installed
+# script, so any of $ ` " \ in `channel_url` would break the installed
+# file (or worse, allow command substitution to run at next sourcing).
+# Validate that the URL is plain http(s)+ASCII-URL-safe characters; we
+# don't expect arbitrary content here, only an upstream raw.github URL
+# (or a forked equivalent). Escape the sed metachars (\&|) separately so
+# the substitution itself round-trips.
+case "$channel_url" in
+    *['"$`\']*) die "channel URL contains unsafe characters: $channel_url" ;;
+esac
+escaped_url=$(printf '%s' "$channel_url" | sed 's/[\\&|]/\\&/g')
+sed "s|^LUCEBOX_INSTALLED_FROM=.*|LUCEBOX_INSTALLED_FROM=\"$escaped_url\"|" "$tmp" > "$tmp.baked"
+mv "$tmp.baked" "$tmp"
+grep -q "^LUCEBOX_INSTALLED_FROM=\"$escaped_url\"$" "$tmp" \
+    || die "failed to bake install source into the downloaded script"
+
+# ── install ───────────────────────────────────────────────────────────────
+mkdir -p "$(dirname "$DEST")"
+chmod +x "$tmp"
+mv "$tmp" "$DEST"
+trap - EXIT
+ok "installed lucebox → $DEST"
+info "  fetched from:    $LUCEBOX_INSTALL_URL"
+info "  update channel:  $channel_url"
+if [ "$LUCEBOX_INSTALL_URL" != "$channel_url" ]; then
+    info "  (lucebox update will track the channel URL, not the fetch URL)"
+fi
+
+# ── PATH hint ─────────────────────────────────────────────────────────────
+case ":${PATH:-}:" in
+    *":$(dirname "$DEST"):"*) ;;
+    *) info "  hint: add $(dirname "$DEST") to PATH so 'lucebox' is on the path" ;;
+esac
+
+cat <<EOF
+
+Next:
+  ${C_DIM}lucebox check${C_RST}            verify host prereqs (docker + NVIDIA CTK + driver)
+  ${C_DIM}lucebox install${C_RST}          install the user systemd unit
+  ${C_DIM}lucebox start${C_RST}            start the server
+  ${C_DIM}lucebox update${C_RST}           re-run this installer to fetch the latest lucebox.sh
+EOF

lefthook.yml

@@ -0,0 +1,59 @@
+# lefthook.yml — git hook config for the lucebox-hub monorepo.
+#
+# Install once per checkout:
+#
+#     # Option A: standalone binary (recommended)
+#     curl -sSfL https://raw.githubusercontent.com/evilmartians/lefthook/master/install.sh | sh
+#     lefthook install
+#
+#     # Option B: via npm
+#     npm install -g lefthook && lefthook install
+#
+# After `lefthook install`, git's hook dir is wired so the pre-commit
+# block below fires on every `git commit`. Skip a one-off with
+# `LEFTHOOK=0 git commit ...`.
+#
+# What we enforce here is the same surface CI does — keeping commits
+# from breaking the bash scripts that ship with the image. The goal is
+# specifically to prevent another `unbound variable` regression like the
+# DRAFT_FAMILY_GLOB / LUCEBOX_HOST_HAS_SYSTEMD ones from landing.
+
+pre-commit:
+  parallel: true
+  commands:
+    shellcheck:
+      # Run shellcheck on every staged *.sh file with the same
+      # `--severity=error` gate the CI test runner uses
+      # (scripts/test_lucebox_sh.sh). Warning-level findings are
+      # informational; errors fail the commit.
+      #
+      # `--external-sources` lets shellcheck follow `source` directives
+      # — needed for harness/clients/common.sh consumers. The exclude
+      # below skips vendored llama.cpp scripts under server/deps/ so we
+      # don't trip on upstream style.
+      glob: "**/*.sh"
+      exclude:
+        - "server/deps/**"
+      run: shellcheck --severity=error --external-sources {staged_files}
+
+    bash-parse:
+      # `bash -n` catches syntax errors that shellcheck can miss when
+      # configured to error-only. Cheap second pass — runs in parallel.
+      glob: "**/*.sh"
+      exclude:
+        - "server/deps/**"
+      run: |
+        rc=0
+        for f in {staged_files}; do
+          bash -n "$f" || rc=1
+        done
+        exit "$rc"
+
+# pre-push runs the full bash smoke test — more thorough, slower than
+# pre-commit. Covers every subcommand dispatch under `set -u` plus the
+# entrypoint's draft-resolution branches. Skip with `LEFTHOOK=0 git push`
+# if you really need to push without local validation (CI still catches it).
+pre-push:
+  commands:
+    bash-smoke:
+      run: bash scripts/test_lucebox_sh.sh