Review request: dual-mode dispatch + external awk refactor (v1.0.0-rc5)

[nnunley]

@chazu @mparrett — could you take a look at the refactor that shipped in rc5 and flag any concerns?

What changed (full diff, merge e5c0784):

• bin/git-issue (3.2k-line bash CLI) is now dual-mode: sourcing it defines functions and executes nothing; execution goes through a BASH_SOURCE == $0 gate with set -e scoped inside it.
• Busybox-style $0 dispatch: git-issue-status is now a symlink to git-issue; basename $0 routes to status_report(). Its duplicated plumbing helpers were deleted in favor of the canonical ones.
• The three inline awk programs moved verbatim to share/git-issue/awk/*.awk (params via -v only, testable standalone, BSD awk/gawk/mawk-clean); missing files are a hard error via require_awk_file.
• Self-path resolution is a BSD-safe symlink loop (no readlink -f, works on stock macOS and through brew's symlink chains).
• All four installers (Makefile w/ DESTDIR, both formulas, install-git-issue.sh) ship the symlink + awk dir; new CI suites cover dispatch and a staged-install smoke test through a fake-brew symlink chain.

Design/decision record: docs/plans/2026-08-13-modularization-refactor-design.md — includes why we rejected a full libexec module split.

Specific things worth adversarial eyes:

1. The dual-mode gate + set -e scoping — any sourcing side effects we missed?
2. The $0 dispatch — footguns you've hit with multi-call binaries?
3. The awk -v-only contract and the trailing-header parsing semantics (front_matter.awk).

Known issues already found in post-release clean-install testing (fixes incoming, don't burn time on them): install-git-issue.sh quotes its awk glob so the copy fails, and the #!/bin/bash shebang breaks FreeBSD (/bin/bash doesn't exist there).

[mparrett]

I reviewed this by differential testing: worktrees at de53c8ac and e5c0784, a fixture repo of 14 adversarial notes (trailing headers, prose after headers, id: in the body, CRLF, missing trailing newline, control characters in titles, and comments sections), diffing stdout, stderr, and exit codes across both revisions.

Top-line: the refactor preserves behavior across everything I exercised. Read paths (list, show, ready, topo, deps, export over all 14 fixtures) are byte-identical between old and new. Write paths (create, update, comment, dep add, close, compared on the resulting note blobs including auto-unblock) are identical apart from content-hash IDs and 2 seconds of timestamp drift. Moving the awk programs into share/ did not change semantics.

Two things to fix, then answers to your three questions.

1. require_awk_file does not hard-error

exit 1 inside $(...) exits the subshell, not the script. The substitution expands to empty and awk -f "" runs anyway:

$ mkdir -p /tmp/empty
$ GIT_ISSUE_AWK_DIR=/tmp/empty git issue list
Issues:
Error: awk program not found: /tmp/empty/extract_issues.awk — reinstall git-issue or set GIT_ISSUE_AWK_DIR
awk: can't open file
$ echo $?
0

$ GIT_ISSUE_AWK_DIR=/tmp/empty git issue show aaa0000
Issue #aaa0000
title:
status:
priority:
$ echo $?
0

Exit 0, an empty issue list, and a show that renders an existing issue with every field blank.

This composes with the install bug you already know about. mkdir -p creates the awk directory, the quoted cp glob fails, the directory exists but is empty, so the -d test at bin/git-issue:31 passes and GIT_ISSUE_AWK_DIR points at it. A clean install via install-git-issue.sh then reports zero issues and exits 0. That one is worth moving up your list — it fails silently rather than cosmetically.

Related: the if at bin/git-issue:30-36 has no else, so when neither candidate directory exists GIT_ISSUE_AWK_DIR stays unset and the diagnostic reads awk program not found: /extract_issues.awk, pointing at the filesystem root during the exact case it exists to explain.

Validating all three files once at startup, outside any command substitution, fixes both.

2. list and show disagree about trailing headers

Pre-existing: old and new are byte-identical here, so the refactor moved this faithfully. I'm raising it because it's the semantics you asked about, and having the programs side by side in share/ makes the divergence legible in a way the inline versions did not.

front_matter.awk scans backward and skips over arbitrary non-header lines to find the last known header. extract_issues.awk streams forward and resets the trailing block when it hits a prose line. Same note, three answers:

id: aaa1111
title: Trailing header followed by prose
status: open
priority: medium

Body paragraph here.
status: closed
and then a prose line after the trailing header

• show reports status: closed
• list reports open
• body.awk drops and then a prose line after the trailing header from the body

The third is silent content loss: text the user typed appears in no command's output.

Two rules are in play, "scan backward past anything until a header" and "a prose line ends the trailing block", and they agree only when nothing follows the trailing headers. The streaming rule looks like the one to standardize on, since it's the one that cannot swallow body text. A fixture asserting that list and show report the same status for the same note would pin it down.

Minor

• Sourcing leaks 17 unprefixed globals. Sourcing defines RED, GREEN, YELLOW, BLUE, GRAY, NC, STATUSES, PRIORITIES, STATUS_MODE, STORAGE_TYPE, KNOWN_HEADER_FIELDS, CACHED_USER_NAME, BATCH_FLUSH_HASH, ISSUE_REPO_DIR, ORIGINAL_GIT_DIR, GIT_ISSUE_AWK_DIR, and GIT_ISSUE_BIN_DIR. RED, GREEN, and NC will collide with a consumer's own color variables. A GI_ prefix would make sourcing safe to recommend.

• get_issue_id_from_ref is called at bin/git-issue:1358 but never defined (pre-existing, also in the old script). git issue export with no arguments hits it once per issue and exports empty IDs.

• Control characters are stripped in list but not show. gsub(/[[:cntrl:]]/, "") is in extract_issues.awk only, so a tab in a title renders as Tab\there in show and Tabhere in list.

Your three questions

Dual-mode gate and set -e scoping. The gate is sound. After sourcing: no traps installed, errexit off in the caller, cwd unchanged, nothing written to disk. set -e still covers everything main calls, since it's set before _gi_entry runs. The one sourcing side effect is the namespace pollution above.

$0 dispatch. Works through brew-style symlink chains, install prefixes containing spaces, and the git issue subcommand form. Two notes. It keys on the invocation path, not argv[0]: exec -a git-issue-status /path/to/git-issue runs main, because the kernel hands bash the script path and discards the argv[0] override. That's correct for the symlink case but not what a busybox multi-call binary does, and the design doc uses that term. Second, *) falls through silently, so a packager shipping the symlink as git-issue-status.sh gets the usage screen instead of the status report. A git issue status subcommand as the canonical entry, with the symlink as sugar, would drop the dependency on the installed filename.

The awk -v contract and front_matter.awk semantics. Portability holds: all three programs produce byte-identical output under BSD awk 20200816 (stock macOS 26.5), gawk 5.3.2, mawk 1.3.4, and busybox 1.37. I did not test FreeBSD.

The -v-only contract is safe today, and the reason is worth writing down. FIELDS is the only value crossing -v, and it's a fixed internal constant. -v applies backslash escape processing to its values, so the first time user-controlled data (a title, a label, a body) goes through -v, a backslash in that data gets mangled. The contract holds because nothing user-controlled uses it yet — that's a constraint on future changes, not a property of the mechanism.

Trailing-header semantics are finding 2 above.

---

On finding 2: do you want front_matter.awk and body.awk moved onto the streaming rule, or is the backward scan load-bearing somewhere I didn't hit?

[nnunley]

Update for reviewers: both known issues at the bottom of the description are fixed on main (merge 1e05ec5) — the installer glob + shipped hook templates, env-bash shebangs throughout, plus a real hard-fail pre-flight for missing awk programs and a $0-independent hook-template lookup. Verified by clean installs on Ubuntu 24.04 (12/12 suites) and FreeBSD 14.4 (13/13 suites, direct exec, no explicit bash). The dispatch/awk design questions in the description still stand.