v0.9.5: cheat on-PATH command (live, never-drifts reference) + verified no-uninstall config-preserving update
- bin/cheat: one-screen reference for ALL short commands, generated live from the bin/ wrapper set + each tool's help block (description from the wrapper header / backing lib line 1; ONE real example from the wrapper's example block / lib Usage form). cheat <filter> + cheat -h. LC_ALL=C em-dash slicing. - Wired into install-larry.sh symlink loop + MANIFEST (auto-synced on update). - Proved the update path: simulated v0.9.0 install with populated config/auth/ site-data -> re-ran installer against v0.9.5 origin -> reached v0.9.5 with bin/cheat on PATH + completion wired + fixtures present, ALL 8 state files byte-identical (sha256), tbn adt + completion working after. Idempotent re-run (no duplicate rc line). NO uninstall needed for an update. - VERSION + LARRY_VERSION -> 0.9.5; MANIFEST regenerated (--check clean, 95 entries); bash -n clean. Deliverables: cheatsheet + update-procedure (myPKA). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
bj
parent
df1810cba7
commit
ba224477e3
29
CHANGELOG.md
29
CHANGELOG.md
@ -4,6 +4,35 @@ All notable changes to `cloverleaf-larry` / `larry-anywhere` are recorded here.
|
||||
Versioning is loose-semver; bumps trigger the in-process self-update on every
|
||||
running client via `LARRY_BASE_URL` + `MANIFEST`.
|
||||
|
||||
## v0.9.5 — 2026-06-08
|
||||
|
||||
**`cheat` — a one-screen, never-drifts reference for every short command — plus a
|
||||
verified config-preserving update procedure (NO uninstall).** (Clover)
|
||||
|
||||
- **`bin/cheat` (on PATH, `-h`).** Prints ALL short commands with a one-line
|
||||
description and ONE real example each. Generated LIVE from the installed `bin/`
|
||||
wrapper set + each tool's own help block (the wrapper's `# <name> — …` header,
|
||||
falling back to the backing `lib/<tool>.sh` line 1 for thin pass-throughs; the
|
||||
first indented `# <cmd> …` example, falling back to the lib tool's first
|
||||
`# Usage:` form), so it can never drift from what is actually on the box.
|
||||
`cheat <filter>` narrows by substring; `cheat -h` explains itself. Added to the
|
||||
installer's wrapper-symlink loop and to the MANIFEST (auto-synced on update).
|
||||
Em-dash header parsing runs under `LC_ALL=C` so the 3-byte em-dash is sliced by
|
||||
byte, not char (a UTF-8-locale awk `substr` would over-skip 2 chars).
|
||||
- **Verified update story (Bryan's #1 concern):** re-running `install-larry.sh`
|
||||
(or relaunching `larry`) pulls v0.9.5 from the Gitea origin and PRESERVES all
|
||||
state (`.api-key`, `.oauth.json`, `.deployment-id`, `.ssh-creds/`, `sessions/`,
|
||||
`log/`, curated `inbound-systems.tsv`) — none of which is in the MANIFEST, so
|
||||
the updater never touches them. Proven by simulating a v0.9.0 install with
|
||||
populated config/auth/site-data, running the update, and confirming v0.9.5 +
|
||||
`bin/cheat` on PATH + completion wired + fixtures present, with all 8 state
|
||||
files byte-identical (sha256) and `tbn adt`/completion working after. The
|
||||
installer's rc-wiring and curated-file handling are idempotent (2nd run = no
|
||||
duplicate completion line, config still intact). No uninstall is needed for an
|
||||
update; `uninstall-larry.sh` is decommission-only. Procedure deliverable:
|
||||
`Deliverables/2026-06-08-cloverleaf-larry-update-procedure.md`; cheatsheet:
|
||||
`Deliverables/2026-06-08-cloverleaf-larry-cheatsheet.md`.
|
||||
|
||||
## v0.9.4 — 2026-06-08
|
||||
|
||||
**Short, directly-invokable commands on PATH + dynamic 3-level tab-completion +
|
||||
|
||||
11
MANIFEST
11
MANIFEST
@ -23,17 +23,17 @@
|
||||
# scripts/make-manifest.sh and bump VERSION.
|
||||
|
||||
# Top-level scripts
|
||||
larry.sh 32c81f6ca2e677756c1efc851337d71cd553f8a0bbf96f2eaeb5e8d8ec68377d
|
||||
larry.sh 93e72650cf031ea3ec6a3cce3a323d2a712bfd7a1cbaed15eac9e0da9cc8f824
|
||||
larry-tunnel.sh 6b050e4eeab15669f4858eaf3b807f168f211ced07815db9521bc40a093f6aaa
|
||||
larry-auth.sh a220cdf7878569dc3028951ee57fc8d5e706a8ca5c6aa45347b58facb386f831
|
||||
larry-rollback.sh 91b5e9aa6c79266bf306dcfba4ca791c07971bd6924d67a779037531648aa6d0
|
||||
install-larry.sh 0a7bc75e75ebfe75eb9c47bda259b31072b79003af42a8e7f40a7e48469a874f
|
||||
install-larry.sh b7ca41ac5b6e3a687ba22d1246dc102fe70a3ed47d6d0a3b0fdedb44cb37debd
|
||||
uninstall-larry.sh c53ad2d8354c7adeb243b541f027f3f481e4a8661eecfd7af14d7ca53cfcaad9
|
||||
|
||||
# Metadata
|
||||
VERSION a61cc7a990558a2b76c4a814eb233267e219158dcf184b6b30ce458d27027674
|
||||
VERSION 8780409dbc52c96276102c5a079a7d3e325510d7bf87af5257508ecc088a3730
|
||||
MANUAL.md 5ff54d6d5fae826f8b3da1eb3be6476076bb15f9b1417a4de285e59ea37e1b1f
|
||||
CHANGELOG.md 8eacdea7711e4e22b1afb0f79f7deb970881a133ca6277732ba4ba16ac1b194f
|
||||
CHANGELOG.md 75e80341189204a3320eb60da1db7c190b5e34f94c3359895ef2744153107dcd
|
||||
|
||||
# Agent personas (system-prompt overlays)
|
||||
agents/larry.md 0a1ef737e7fc133ab35be09f79c3a4df33de814e0404b69b950932d0c8a01be1
|
||||
@ -125,6 +125,9 @@ lib/nc-regression.sh 70999a60608439f7bf1a3abb9f5e9854b5ea03025ef29ddbca683896346
|
||||
# (command/site/thread) completion, enumerated LIVE from the NetConfig tree.
|
||||
bin/_nc_common.sh 591b60d091e9c8a5e1068844dffe2e19f44d262fcf1132dc47e425d4673495e1
|
||||
bin/nc-completion.bash 3a5b1b29f34f2382556d9f8620882ab7edbb2d27dfa35177793889b289d22a9a
|
||||
# v0.9.5: `cheat` — one-screen reference generated LIVE from this bin/ set +
|
||||
# each tool's help block (never drifts). On PATH; `cheat`, `cheat <filter>`, -h.
|
||||
bin/cheat 94a164da2aebe15b68f52ed675ff75547235c35eaa25f96df73fbe1c695b93a2
|
||||
bin/tbn 60e69288a502f1280e6bf4bc6dc19568858b34024ba26c34f8ff7ed52457d02c
|
||||
bin/tbp 8cdc82de0bbbee8da97d4ab958f7b5ead5aed8c7658c3d73ff9106df6383bf29
|
||||
bin/tbh 79556fe72d58393c2a00e744b892c5a1a69bae3be6fcdd0ba46dd108ee67c092
|
||||
|
||||
197
bin/cheat
Executable file
197
bin/cheat
Executable file
@ -0,0 +1,197 @@
|
||||
#!/usr/bin/env bash
|
||||
# cheat — one-screen reference for ALL Cloverleaf-Larry short commands.
|
||||
# Generated LIVE from the bin/ wrapper set + each tool's help block, so it can
|
||||
# NEVER drift from what is actually installed on PATH. No static list.
|
||||
#
|
||||
# cheat # the full table: command · what it does · one example
|
||||
# cheat tbn # just the row(s) whose name contains 'tbn'
|
||||
# cheat hl7 # filter — every command matching 'hl7'
|
||||
# cheat -h # this help
|
||||
#
|
||||
# For each command shown, `cheat` derives:
|
||||
# • the description — from the wrapper's own `# name — …` header line, or (for
|
||||
# the thin nc-*/hl7-* pass-through wrappers) from line 1 of
|
||||
# the underlying lib/<tool>.sh, whichever is more specific.
|
||||
# • ONE real example — the first indented `# <cmd> …` example in the wrapper's
|
||||
# help block; else the first `# Usage:` form of the backing
|
||||
# lib tool, rewritten to the bare on-PATH command; else
|
||||
# `<cmd> -h`.
|
||||
# Run `<cmd> -h` (or `<cmd> --help`) on any row for the full, authoritative help.
|
||||
set -o pipefail
|
||||
|
||||
# --- locate our own bin/ dir (follow one symlink level, like the wrappers) ---
|
||||
_self="${BASH_SOURCE[0]}"; [ -L "$_self" ] && _self="$(readlink "$_self")"
|
||||
_BINDIR="$(cd "$(dirname "$_self")" && pwd)"
|
||||
# Reuse the shared lib resolver so the example-from-lib path finds lib/<tool>.sh.
|
||||
[ -f "$_BINDIR/_nc_common.sh" ] && . "$_BINDIR/_nc_common.sh"
|
||||
|
||||
if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
|
||||
awk 'NR==1{next} /^#/{sub(/^# ?/,""); print; next} {exit}' "${BASH_SOURCE[0]}"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
_filter="${1:-}"
|
||||
|
||||
# Resolve the lib/ dir once (best-effort; example-from-lib degrades gracefully).
|
||||
_LIB=""
|
||||
if command -v _nc_resolve_lib >/dev/null 2>&1; then
|
||||
_LIB="$(_nc_resolve_lib 2>/dev/null || true)"
|
||||
fi
|
||||
|
||||
# --- header line of a wrapper: the `# <name> — <desc>` comment (line 2) -------
|
||||
# Returns the text after the em-dash separator. The codebase convention is a
|
||||
# literal em-dash (—, U+2014) between the command name and its description; we
|
||||
# split ONLY on that so hyphenated command names (csv-to-table, hl7-field) stay
|
||||
# intact. A wrapper whose first comment has no em-dash yields no desc here (the
|
||||
# caller then falls back to the backing lib tool's description).
|
||||
_wrapper_desc() {
|
||||
# LC_ALL=C → byte-oriented index()/substr() so the 3-byte em-dash (—) is
|
||||
# skipped exactly (under a UTF-8 locale substr counts chars and over-skips).
|
||||
LC_ALL=C awk '
|
||||
NR==1 { next } # shebang
|
||||
/^#/ {
|
||||
line = $0
|
||||
sub(/^# ?/, "", line)
|
||||
i = index(line, "\xe2\x80\x94") # UTF-8 bytes for — (em-dash)
|
||||
if (i > 0) {
|
||||
rest = substr(line, i + 3)
|
||||
sub(/^[[:space:]]+/, "", rest)
|
||||
print rest
|
||||
exit
|
||||
}
|
||||
}
|
||||
!/^#/ { exit }
|
||||
' "$1"
|
||||
}
|
||||
|
||||
# Is this wrapper one of the thin pass-through wrappers whose own description is
|
||||
# the generic boilerplate? If so we prefer the backing lib tool's description.
|
||||
_is_boilerplate_desc() {
|
||||
case "$1" in
|
||||
*"direct, on-PATH wrapper for lib/"*) return 0 ;;
|
||||
*) return 1 ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# Description of the backing lib tool (line 1 after its `# tool.sh — `).
|
||||
_lib_desc() {
|
||||
local tool="$1" f="$_LIB/$1.sh"
|
||||
[ -n "$_LIB" ] && [ -f "$f" ] || return 1
|
||||
LC_ALL=C awk '
|
||||
/^#/ {
|
||||
line = $0; sub(/^# ?/, "", line)
|
||||
i = index(line, "\xe2\x80\x94") # UTF-8 bytes for — (em-dash)
|
||||
if (i > 0) {
|
||||
rest = substr(line, i + 3)
|
||||
sub(/^[[:space:]]+/, "", rest)
|
||||
print rest; exit
|
||||
}
|
||||
}
|
||||
!/^#/ { exit }
|
||||
' "$f"
|
||||
}
|
||||
|
||||
# First indented `# <cmd> …` example inside a wrapper's help block. The header
|
||||
# line ("# <cmd> — …") is excluded by requiring (a) at least TWO spaces after the
|
||||
# `#` (real example blocks are indented `# <cmd> …`) and (b) no em-dash on the
|
||||
# line (the header carries the em-dash; example lines never do).
|
||||
_wrapper_example() {
|
||||
local cmd="$1"
|
||||
LC_ALL=C awk -v cmd="$cmd" '
|
||||
NR==1 { next }
|
||||
/^#/ {
|
||||
raw = $0
|
||||
body = raw; sub(/^#/, "", body) # keep indentation
|
||||
if (body !~ ("^[[:space:]][[:space:]]+" cmd "([[:space:]]|$)")) { next }
|
||||
if (index(body, "\xe2\x80\x94") > 0) next # skip the header (has —)
|
||||
sub(/^[[:space:]]+/, "", body)
|
||||
sub(/[[:space:]]+#.*$/, "", body) # drop trailing "# comment"
|
||||
print body; exit
|
||||
}
|
||||
!/^#/ { exit }
|
||||
' "$2"
|
||||
}
|
||||
|
||||
# First `# Usage:` form of the backing lib tool, rewritten to the bare command.
|
||||
# e.g. " nc-find.sh --name PATTERN # …" -> "nc-find --name PATTERN"
|
||||
_lib_example() {
|
||||
local cmd="$1" tool="$2" f="$_LIB/$2.sh"
|
||||
[ -n "$_LIB" ] && [ -f "$f" ] || return 1
|
||||
LC_ALL=C awk -v tool="$tool" -v cmd="$cmd" '
|
||||
/^#[[:space:]]*Usage:/ { inu=1; next }
|
||||
inu && /^#/ {
|
||||
line = $0; sub(/^#/, "", line)
|
||||
if (line ~ /[^[:space:]]/) {
|
||||
sub(/^[[:space:]]+/, "", line)
|
||||
sub(/[[:space:]]+#.*$/, "", line) # drop trailing comment
|
||||
if (line ~ ("^" tool "\\.sh")) {
|
||||
sub("^" tool "\\.sh", cmd, line) # nc-find.sh … -> nc-find …
|
||||
print line; exit
|
||||
}
|
||||
}
|
||||
next
|
||||
}
|
||||
inu && !/^#/ { exit }
|
||||
' "$f"
|
||||
}
|
||||
|
||||
# --- gather the command list (skip helpers / sourced files / fetched bins) ---
|
||||
_cmds=()
|
||||
for _p in "$_BINDIR"/*; do
|
||||
[ -f "$_p" ] && [ -x "$_p" ] || continue
|
||||
_b="$(basename "$_p")"
|
||||
case "$_b" in
|
||||
_nc_common.sh|nc-completion.bash|cheat|jq|jq.exe) continue ;;
|
||||
*.bash) continue ;;
|
||||
esac
|
||||
_cmds+=("$_b")
|
||||
done
|
||||
|
||||
# Sort for stable output.
|
||||
IFS=$'\n' _cmds=($(printf '%s\n' "${_cmds[@]}" | sort)); unset IFS
|
||||
|
||||
# --- build rows -------------------------------------------------------------
|
||||
_rows=""
|
||||
for _c in "${_cmds[@]}"; do
|
||||
if [ -n "$_filter" ] && ! printf '%s' "$_c" | grep -qiF "$_filter"; then
|
||||
continue
|
||||
fi
|
||||
_wf="$_BINDIR/$_c"
|
||||
|
||||
# description
|
||||
_desc="$(_wrapper_desc "$_wf")"
|
||||
if [ -z "$_desc" ] || _is_boilerplate_desc "$_desc"; then
|
||||
_ld="$(_lib_desc "$_c")"
|
||||
[ -n "$_ld" ] && _desc="$_ld"
|
||||
fi
|
||||
[ -z "$_desc" ] && _desc="(no description)"
|
||||
# collapse whitespace, trim to one clause for the table
|
||||
_desc="$(printf '%s' "$_desc" | tr -s '[:space:]' ' ' | sed 's/^ *//; s/ *$//')"
|
||||
|
||||
# example
|
||||
_ex="$(_wrapper_example "$_c" "$_wf")"
|
||||
if [ -z "$_ex" ]; then
|
||||
_ex="$(_lib_example "$_c" "$_c")"
|
||||
fi
|
||||
[ -z "$_ex" ] && _ex="$_c -h"
|
||||
_ex="$(printf '%s' "$_ex" | tr -s '[:space:]' ' ' | sed 's/^ *//; s/ *$//')"
|
||||
|
||||
_rows="${_rows}${_c}"$'\t'"${_desc}"$'\t'"${_ex}"$'\n'
|
||||
done
|
||||
|
||||
if [ -z "$_rows" ]; then
|
||||
echo "cheat: no commands match '${_filter}'" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- render: aligned three-column table -------------------------------------
|
||||
printf 'Cloverleaf-Larry short commands (run <cmd> -h for full help)\n\n'
|
||||
printf '%s' "$_rows" | awk -F'\t' '
|
||||
{ c[NR]=$1; d[NR]=$2; e[NR]=$3; n=NR; if (length($1)>w) w=length($1) }
|
||||
END {
|
||||
for (i=1;i<=n;i++) {
|
||||
printf " %-*s %s\n", w, c[i], d[i]
|
||||
printf " %-*s e.g. %s\n", w, "", e[i]
|
||||
}
|
||||
}
|
||||
'
|
||||
@ -261,7 +261,7 @@ fetch lib/journal.sh "$LARRY_HOME/lib/journal.sh"
|
||||
# completion available immediately, before the first `larry` launch.
|
||||
fetch bin/_nc_common.sh "$LARRY_HOME/bin/_nc_common.sh"
|
||||
fetch bin/nc-completion.bash "$LARRY_HOME/bin/nc-completion.bash"
|
||||
for _w in tbn tbp tbh tbpr where paths route_test \
|
||||
for _w in cheat tbn tbp tbh tbpr where paths route_test \
|
||||
nc-parse nc-paths nc-find nc-inbound nc-status nc-engine nc-xlate nc-table \
|
||||
nc-create-thread nc-set-field nc-insert-protocol nc-make-jump nc-provision-jumps \
|
||||
nc-tclgen nc-document nc-revisions nc-diff-interface nc-smat-diff nc-regression \
|
||||
|
||||
2
larry.sh
2
larry.sh
@ -99,7 +99,7 @@ set -o pipefail
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# Config
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
LARRY_VERSION="0.9.4"
|
||||
LARRY_VERSION="0.9.5"
|
||||
LARRY_HOME="${LARRY_HOME:-$HOME/.larry}"
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
Loading…
Reference in New Issue
Block a user