Skip to content

Commit 356dfe4

Browse files
author
NagyVikt
committed
feat(scripts): add --help/--version flags to cap-probe, score-checkpoint, force-claim
Wires a small shared lib/version.sh (FLEET_VERSION + handle_help_version_flags) into the three entry-point scripts so each accepts --help/-h and --version before its real argv parsing runs. Adds tests/scripts/test-script-help.sh as a smoke test that asserts exit 0 + non-empty, name-bearing output for every flag/script combination. Implements PROTOCOL.md section 22.4.1 (PROPOSED → done) without touching any other script logic.
1 parent 7db998d commit 356dfe4

5 files changed

Lines changed: 221 additions & 0 deletions

File tree

‎scripts/codex-fleet/cap-probe.sh‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,32 @@
1717
# Usage: bash cap-probe.sh <need_n> email1 email2 ...
1818
set -eo pipefail
1919

20+
# --help / --version plumbing (see lib/version.sh).
21+
FLEET_USAGE="cap-probe.sh — verify candidate codex accounts are usable.
22+
23+
Usage:
24+
bash cap-probe.sh <need_n> email1 email2 ...
25+
bash cap-probe.sh --help | --version
26+
27+
Args:
28+
need_n minimum number of healthy accounts required (exit 3 otherwise)
29+
email1 email2 ... candidate accounts to probe (cached per email)
30+
31+
Env:
32+
CACHE_DIR cache root (default /tmp/claude-viz/cap-probe-cache)
33+
CACHE_TTL_HEALTHY healthy verdict TTL seconds (default 60)
34+
CODEX_FLEET_CAP_CACHE_TTL alias for healthy TTL (operator pin)
35+
CACHE_TTL_UNKNOWN unknown verdict TTL seconds (default 60)
36+
BRINGUP_FAILURE_MARKER presence forces cold re-probe
37+
PROBE_TIMEOUT per-account codex exec timeout (default 60s)
38+
LOG log path (default /tmp/claude-viz/cap-probe.log)
39+
40+
Flags:
41+
-h, --help print this help and exit 0
42+
--version print '<basename> <FLEET_VERSION>' and exit 0"
43+
source "$(dirname "${BASH_SOURCE[0]}")/lib/version.sh"
44+
handle_help_version_flags "$@"
45+
2046
NEED="${1:-1}"; shift
2147

2248
CACHE_DIR="${CACHE_DIR:-/tmp/claude-viz/cap-probe-cache}"

‎scripts/codex-fleet/force-claim.sh‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,44 @@
5252
# CODEX_FLEET_CLAIM_MODE=both|event|poll # default: both
5353
set -eo pipefail
5454

55+
# --help / --version plumbing (see lib/version.sh). Handled before sourcing
56+
# _tmux.sh / claim-fence.sh so docs work even when those libs misbehave.
57+
FLEET_USAGE="force-claim.sh — dispatch ready plan sub-tasks across all
58+
non-empty openspec plans onto idle codex panes.
59+
60+
Usage:
61+
bash scripts/codex-fleet/force-claim.sh # one-shot
62+
bash scripts/codex-fleet/force-claim.sh --dry-run # show plan, no dispatch
63+
bash scripts/codex-fleet/force-claim.sh --loop # event + poll every 15s
64+
bash scripts/codex-fleet/force-claim.sh --loop --quit-when-empty
65+
bash scripts/codex-fleet/force-claim.sh --loop --empty-threshold=5
66+
bash scripts/codex-fleet/force-claim.sh --no-token-check
67+
bash scripts/codex-fleet/force-claim.sh --help | --version
68+
69+
Env:
70+
FORCE_CLAIM_REPO / CODEX_FLEET_REPO_ROOT repo root (default: derived)
71+
FORCE_CLAIM_SESSION tmux session (default: codex-fleet)
72+
FORCE_CLAIM_WINDOW tmux window (default: overview)
73+
FORCE_CLAIM_PLAN_JSON pin to a single plan
74+
FORCE_CLAIM_INTERVAL loop poll seconds (default: 15)
75+
FORCE_CLAIM_EMPTY_THRESHOLD consecutive empties to quit (default: 3)
76+
CODEX_FLEET_CLAIM_MODE both | event | poll (default: both)
77+
FORCE_CLAIM_TOKEN_METER path to token-meter.sh
78+
FORCE_CLAIM_TOKEN_MIN_5H / _MIN_WK cap thresholds for skipping panes
79+
FORCE_CLAIM_SKIP_READY_CHECK=1 bypass worker-ready gate
80+
81+
Flags:
82+
--dry-run show plan; do not dispatch
83+
--loop event + poll backstop
84+
--interval=N poll interval (seconds)
85+
--quit-when-empty exit 0 after empty-streak
86+
--empty-threshold=N consecutive empty passes required
87+
--no-token-check bypass token-meter cap filter
88+
-h, --help print this help and exit 0
89+
--version print '<basename> <FLEET_VERSION>' and exit 0"
90+
source "$(dirname "${BASH_SOURCE[0]}")/lib/version.sh"
91+
handle_help_version_flags "$@"
92+
5593
# Route every `tmux ...` call through scripts/codex-fleet/lib/_tmux.sh — when
5694
# CODEX_FLEET_TMUX_SOCKET is set in the env (e.g. by full-bringup.sh), this
5795
# transparently rewrites the call to `tmux -L $SOCKET ...`. Default behavior

‎scripts/codex-fleet/lib/version.sh‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#!/usr/bin/env bash
2+
# version.sh — shared --help / --version plumbing for codex-fleet scripts.
3+
#
4+
# Source via:
5+
# source "$(dirname "${BASH_SOURCE[0]}")/lib/version.sh"
6+
#
7+
# Exports:
8+
# FLEET_VERSION version string (env override > nearest git tag > "0.0.0-dev")
9+
# print_usage_and_exit USAGE print USAGE to stdout and exit 0
10+
# handle_help_version_flags scan "$@" for --help/-h/--version; if found,
11+
# print the appropriate banner and exit 0
12+
#
13+
# Conventions:
14+
# - Scripts pre-set FLEET_USAGE (a heredoc string) before sourcing or before
15+
# calling handle_help_version_flags.
16+
# - $0's basename is used in the --version banner.
17+
18+
# Resolve FLEET_VERSION once per process. Env wins so CI can pin without git.
19+
if [ -z "${FLEET_VERSION:-}" ]; then
20+
_fleet_version_git=""
21+
if command -v git >/dev/null 2>&1; then
22+
_fleet_version_git=$(git -C "$(dirname "${BASH_SOURCE[0]}")" describe --tags --abbrev=0 2>/dev/null || true)
23+
fi
24+
if [ -n "$_fleet_version_git" ]; then
25+
FLEET_VERSION="$_fleet_version_git"
26+
else
27+
FLEET_VERSION="0.0.0-dev"
28+
fi
29+
unset _fleet_version_git
30+
fi
31+
export FLEET_VERSION
32+
33+
print_usage_and_exit() {
34+
printf '%s\n' "$1"
35+
exit 0
36+
}
37+
38+
# Scan args for --help/-h or --version and act on the first match.
39+
# Callers MUST set FLEET_USAGE before invoking. Returns silently if no match
40+
# so the host script keeps processing its real flags.
41+
handle_help_version_flags() {
42+
local arg
43+
for arg in "$@"; do
44+
case "$arg" in
45+
-h|--help)
46+
print_usage_and_exit "${FLEET_USAGE:-no usage text provided}"
47+
;;
48+
--version)
49+
printf '%s %s\n' "$(basename "$0")" "$FLEET_VERSION"
50+
exit 0
51+
;;
52+
esac
53+
done
54+
}

‎scripts/codex-fleet/score-checkpoint.sh‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,26 @@
2727

2828
set -euo pipefail
2929

30+
# --help / --version plumbing (see lib/version.sh).
31+
FLEET_USAGE="score-checkpoint.sh — score uncommitted diffs in active Guardex
32+
agent worktrees against their plan's acceptance criteria.
33+
34+
Usage:
35+
./scripts/codex-fleet/score-checkpoint.sh # scan all active worktrees
36+
./scripts/codex-fleet/score-checkpoint.sh <worktree> # score a single worktree
37+
./scripts/codex-fleet/score-checkpoint.sh --help | --version
38+
39+
Env:
40+
ANTHROPIC_API_KEY required (consumed by lib/score-diff.py)
41+
CODEX_FLEET_CHECKPOINT_PATH sink path (default /tmp/claude-viz/fleet-checkpoint-warnings.json)
42+
CODEX_FLEET_REPO_ROOT repo root (default: git toplevel)
43+
44+
Flags:
45+
-h, --help print this help and exit 0
46+
--version print '<basename> <FLEET_VERSION>' and exit 0"
47+
source "$(dirname "${BASH_SOURCE[0]}")/lib/version.sh"
48+
handle_help_version_flags "$@"
49+
3050
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
3151
SCORER="$SCRIPT_DIR/lib/score-diff.py"
3252
REPO_ROOT="${CODEX_FLEET_REPO_ROOT:-$(git rev-parse --show-toplevel)}"

‎tests/scripts/test-script-help.sh‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
#!/usr/bin/env bash
2+
# test-script-help.sh — smoke test for the --help / --version flags added to
3+
# cap-probe.sh, score-checkpoint.sh, and force-claim.sh.
4+
#
5+
# Asserts, for each script:
6+
# * --help exits 0 with non-empty stdout that mentions the script name
7+
# * --version exits 0, mentions the script name, and emits something that
8+
# looks like a version token
9+
#
10+
# Run from the repo root: `bash tests/scripts/test-script-help.sh`
11+
# Exits 0 on success, non-zero on the first failure.
12+
13+
set -uo pipefail
14+
15+
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
16+
SCRIPTS_DIR="$REPO_ROOT/scripts/codex-fleet"
17+
18+
SCRIPTS=(
19+
cap-probe.sh
20+
score-checkpoint.sh
21+
force-claim.sh
22+
)
23+
24+
fail=0
25+
pass=0
26+
27+
check() {
28+
local script="$1" flag="$2" want_token="$3"
29+
local out rc
30+
out=$(bash "$SCRIPTS_DIR/$script" "$flag" 2>&1)
31+
rc=$?
32+
if [ "$rc" -ne 0 ]; then
33+
printf 'FAIL: %s %s exited %d\n' "$script" "$flag" "$rc" >&2
34+
printf ' stdout/stderr:\n%s\n' "$out" >&2
35+
fail=$((fail + 1))
36+
return 1
37+
fi
38+
if [ -z "$out" ]; then
39+
printf 'FAIL: %s %s produced empty stdout\n' "$script" "$flag" >&2
40+
fail=$((fail + 1))
41+
return 1
42+
fi
43+
if ! printf '%s' "$out" | grep -qF "$want_token"; then
44+
printf 'FAIL: %s %s output missing token %q\n' "$script" "$flag" "$want_token" >&2
45+
printf ' output:\n%s\n' "$out" >&2
46+
fail=$((fail + 1))
47+
return 1
48+
fi
49+
pass=$((pass + 1))
50+
return 0
51+
}
52+
53+
for s in "${SCRIPTS[@]}"; do
54+
# --help: must mention the script name somewhere in usage.
55+
check "$s" "--help" "$s"
56+
# --version: must mention the script name. Additionally assert a digit
57+
# appears (covers both "0.0.0-dev" and any future "vX.Y.Z" tag).
58+
out=$(bash "$SCRIPTS_DIR/$s" --version 2>&1)
59+
rc=$?
60+
if [ "$rc" -ne 0 ]; then
61+
printf 'FAIL: %s --version exited %d\n' "$s" "$rc" >&2
62+
printf ' output:\n%s\n' "$out" >&2
63+
fail=$((fail + 1))
64+
continue
65+
fi
66+
if ! printf '%s' "$out" | grep -qF "$s"; then
67+
printf 'FAIL: %s --version missing script name; got: %s\n' "$s" "$out" >&2
68+
fail=$((fail + 1))
69+
continue
70+
fi
71+
if ! printf '%s' "$out" | grep -qE '[0-9]'; then
72+
printf 'FAIL: %s --version missing version token; got: %s\n' "$s" "$out" >&2
73+
fail=$((fail + 1))
74+
continue
75+
fi
76+
pass=$((pass + 1))
77+
done
78+
79+
printf 'test-script-help: %d passed, %d failed\n' "$pass" "$fail"
80+
if [ "$fail" -ne 0 ]; then
81+
exit 1
82+
fi
83+
exit 0

0 commit comments

Comments
 (0)