eva index: README & kick-aliases Generation

ELI5

eva index is a librarian who walks the shelves and re-prints two things: the catalog page in the README (between two bookmarks) and the shortcut card in kick-aliases.sh (between two perforated edges). Anything outside those edges is left alone; anything inside is rewritten end-to-end.

Technical Deep Dive

Two Outputs (bin/eva:458-543)

flowchart LR
  iter["iter_prompts() — group by status"] --> readme["README.md INDEX block"]
  iter --> aliases["bin/kick-aliases.sh AUTO block"]

  subgraph README
    A["<!-- INDEX:START -->"] --> B["status tables (ready, tested, draft)"]
    B --> C["<!-- INDEX:END -->"]
  end

  subgraph kick-aliases
    D["static header (hand-edited)"] --> E["# >>> AUTO-GENERATED by eva index >>>"]
    E --> F["alias() { kick id #quot;$@#quot;; } per verb"]
    F --> G["# <<< AUTO-GENERATED <<<"]
  end

README

INDEX_RE (bin/eva:57) captures (<!-- INDEX:START -->)(.*?)(<!-- INDEX:END -->) non-greedy. The body between the markers is replaced with one h3 + table per status, in the canonical order ready/tested/draft. If the markers are missing, eva index prints eva: README.md missing <!-- INDEX:START --> markers; skipping to stderr and leaves the file untouched.

kick-aliases.sh

The file is split on the literal sentinels ALIAS_BEGIN (# >>> AUTO-GENERATED by eva index — do not edit by hand >>>) and ALIAS_END (bin/eva:58-59). Everything outside the sentinels is preserved verbatim and treated as the static header. If the file does not yet exist, eva writes a default header that puts bin/ on PATH and exposes prompts, prompt-where, prompt-edit (bin/eva:514-523).

For each prompt with an aliases file, every line passing ALIAS_RE = ^[A-Za-z_][A-Za-z0-9_-]*$ is materialised as:

<verb>() { kick <id> "$@"; }

Invalid aliases are skipped with a stderr warning; collision detection is the doctor’s job (eva-009).

Key Terms

• INDEX_RE — the non-greedy regex that scopes README edits to the marker block.
• ALIAS_BEGIN / ALIAS_END — string sentinels that fence the regenerated block in kick-aliases.sh.
• ALIAS_RE — ^[A-Za-z_][A-Za-z0-9_-]*$; the validity gate for a single line in aliases.

Q&A

Q: Which markers does eva index look for in README.md? A: <!-- INDEX:START --> and <!-- INDEX:END -->; the regex captures the body in between (bin/eva:57).

Q: What does eva index do if the markers are missing? A: Prints README.md missing <!-- INDEX:START --> markers; skipping to stderr and leaves the file unchanged (bin/eva:502-503).

Q: Which part of bin/kick-aliases.sh is hand-edited and which is regenerated? A: Everything outside the # >>> AUTO-GENERATED … >>> / # <<< AUTO-GENERATED <<< fence is preserved as the static header; everything inside is rewritten on every run (bin/eva:507-540).

Examples

Sample regenerated alias block:

# >>> AUTO-GENERATED by `eva index` — do not edit by hand >>>
refactor() { kick refactor-with-constraints "$@"; }
handbook() { kick handbook-section-generator "$@"; }
# <<< AUTO-GENERATED <<<