CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-09-09 14:38:59 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
4543b3c66b46c085b5a1aa64d38b55ffc51faea9
gstack/bin/gstack-team-init
T
Benjamin D. SmithandClaude Opus 5 4543b3c66b fix(scripts): stop heredoc bodies deadlocking under Homebrew bash 
`./setup --help` can hang forever on macOS, printing nothing, with no way
to tell it apart from a slow install. Eleven scripts carry the same
latent hang, `setup` itself being the one every user hits first.

bash 5.2+ delivers a heredoc body of 64KiB or less through a pipe: the
forked child writes the entire body before exec, and nothing reads the
other end until the command starts. Under macOS pipe-KVA pressure the
kernel hands a fresh pipe a 512-byte buffer instead of the usual 16-64KiB,
so any body of 512 bytes or more blocks write() permanently. The capacity
check bash would need to notice (F_GETPIPE_SZ) is Linux-only, so it never
fires here. It is pressure-dependent, which is why it reads as "worked on
my machine" — the same script runs fine all day and then wedges.

Homebrew bash is what `#!/usr/bin/env bash` resolves to on a Mac with brew
on PATH, which is most of them. Apple's /bin/bash 3.2 predates the pipe
path and is unaffected, so the bug is invisible to anyone testing with the
system shell.

The fix is `BASH_COMPAT=50` in each affected script, which restores the
pre-5.2 tempfile path:

    $ bash -c 'probe() { [ -p /dev/stdin ] && echo PIPE || echo TEMPFILE; }
               probe <<EOF
    $(printf "x%.0s" $(seq 1 1000))
    EOF'
    PIPE
    $ BASH_COMPAT=50 bash -c '...same...'
    TEMPFILE

- Not a `#!/bin/bash` shebang swap: that pins the script to whatever bash
  lives at /bin (3.2 on macOS, absent on some Linux distributions) and is
  bypassed entirely by `bash script.sh` call sites. The variable survives
  both.
- Not exported, so child processes keep their own compat level.
- Placed below any `--help` sed range that reads $0, so usage output is
  unchanged (verified on all eleven).
- Every guarded script is bash-3.2-clean — no associative arrays, case
  conversion, or mapfile — so compat level 50 costs them nothing.

test/heredoc-pipe-deadlock.test.ts scans every tracked shell script for a
heredoc body in the 512B-64KiB window and fails without the guard, and
proves the mechanism at runtime on bash 5.2+ by asserting the body moves
from PIPE to TEMPFILE. On older bash the runtime half is skipped, since
the pipe path does not exist there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Absorbed from PR #2640 with authorship preserved. Wave adaptations: the pipe-probe test skips on minimal-/dev environments without /dev/stdin (it would report OTHER for an unobservable fd), and one caveat verified during review: on bash 4.3/4.4 (e.g. Git Bash), assigning BASH_COMPAT=50 prints a non-fatal 'invalid value' warning to stderr — those bashes are already on tempfiles, so the guard is a no-op there; windows-setup-e2e exercises this empirically.
2026-08-22 02:14:04 +00:00

217 lines
8.5 KiB
Bash
Executable File
Raw Blame History

#!/usr/bin/env bash
# gstack-team-init — generate repo-level bootstrap files for team mode
#
# Usage:
# gstack-team-init optional # gentle CLAUDE.md suggestion, one-time offer
# gstack-team-init required # CLAUDE.md enforcement + PreToolUse hook
#
# Run from the root of your team's repo (not from the gstack directory).
# Heredoc delivery guard. bash 5.2+ writes a heredoc body <=64KiB through a
# pipe in the forked child before exec, with no reader on the other end. On
# macOS under pipe-KVA pressure a fresh pipe gets a 512-byte buffer, so any
# body >=512B blocks write() forever and the script hangs at startup with no
# output. Compat level 50 restores the tempfile path. These scripts are
# bash-3.2-clean, so the compat level costs them nothing. Not exported: the
# guard is per-script, and it survives `bash script.sh` call sites that
# bypass the shebang.
BASH_COMPAT=50
set -euo pipefail
MODE="${1:-}"
if [ "$MODE" != "optional" ] && [ "$MODE" != "required" ]; then
echo "Usage: gstack-team-init {optional|required}" >&2
echo "" >&2
echo " optional — suggest gstack install once per developer (gentle)" >&2
echo " required — enforce gstack install, block work without it" >&2
exit 1
fi
# Must be in a git repo
if ! git rev-parse --show-toplevel >/dev/null 2>&1; then
echo "Error: not in a git repository. Run from your project root." >&2
exit 1
fi
REPO_ROOT=$(git rev-parse --show-toplevel)
CLAUDE_MD="$REPO_ROOT/CLAUDE.md"
GENERATED=()
# ── Migrate vendored copy if present ──────────────────────────
if [ -d "$REPO_ROOT/.claude/skills/gstack" ] && [ ! -L "$REPO_ROOT/.claude/skills/gstack" ]; then
if [ -f "$REPO_ROOT/.claude/skills/gstack/VERSION" ] || [ -d "$REPO_ROOT/.claude/skills/gstack/.git" ]; then
echo " Found vendored gstack copy at $REPO_ROOT/.claude/skills/gstack"
echo " Team mode uses the global install — removing vendored copy..."
( cd "$REPO_ROOT" && git rm -r --cached .claude/skills/gstack/ 2>/dev/null ) || true
if [ -f "$REPO_ROOT/.gitignore" ]; then
if ! grep -qF '.claude/skills/gstack/' "$REPO_ROOT/.gitignore" 2>/dev/null; then
echo '.claude/skills/gstack/' >> "$REPO_ROOT/.gitignore"
fi
else
echo '.claude/skills/gstack/' > "$REPO_ROOT/.gitignore"
fi
rm -rf "$REPO_ROOT/.claude/skills/gstack"
GENERATED+=(".gitignore")
echo " Removed vendored copy and added .claude/skills/gstack/ to .gitignore"
fi
fi
# ── CLAUDE.md snippet ──────────────────────────────────────────
if [ "$MODE" = "optional" ]; then
SNIPPET='## gstack (recommended)
This project uses [gstack](https://github.com/garrytan/gstack) for AI-assisted workflows.
Install it for the best experience:
```bash
git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup --team
```
Skills like /qa, /ship, /review, /investigate, and /browse become available after install.
Use /browse for all web browsing. Use ~/.claude/skills/gstack/... for gstack file paths.'
else
SNIPPET='## gstack (REQUIRED — global install)
**Before doing ANY work, verify gstack is installed:**
```bash
_GS=""
for _D in "${GSTACK_ROOT:-}" "$HOME/.claude/skills/gstack" "$HOME/.codex/skills/gstack" "$HOME/.factory/skills/gstack" "$HOME/.kiro/skills/gstack" "$HOME/.config/opencode/skills/gstack" "$HOME/.slate/skills/gstack" "$HOME/.cursor/skills/gstack" "$HOME/.openclaw/skills/gstack" "$HOME/.hermes/skills/gstack" "$HOME/.gbrain/skills/gstack" "$HOME/.gstack/repos/gstack"; do
[ -z "$_GS" ] && [ -n "$_D" ] && [ -d "$_D/bin" ] && _GS="$_D"
done
[ -n "$_GS" ] && echo "GSTACK_OK: $_GS" || echo "GSTACK_MISSING"
```
If GSTACK_MISSING: STOP. Do not proceed. Tell the user:
> gstack is required for all AI-assisted work in this repo.
> Install it:
> ```bash
> git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
> cd ~/.claude/skills/gstack && ./setup --team
> ```
> Then restart your AI coding tool.
Do not skip skills, ignore gstack errors, or work around missing gstack.
Using gstack skills: After install, skills like /qa, /ship, /review, /investigate,
and /browse are available. Use /browse for all web browsing.
Use the resolved install path above for gstack file paths
(default: ~/.claude/skills/gstack).'
fi
# Check if CLAUDE.md already has a gstack section
if [ -f "$CLAUDE_MD" ] && grep -q "## gstack" "$CLAUDE_MD" 2>/dev/null; then
echo "CLAUDE.md already has a gstack section. Skipping CLAUDE.md update."
echo " To replace it, remove the existing ## gstack section and re-run."
else
if [ -f "$CLAUDE_MD" ]; then
echo "" >> "$CLAUDE_MD"
fi
echo "$SNIPPET" >> "$CLAUDE_MD"
GENERATED+=("CLAUDE.md")
echo " + CLAUDE.md — added gstack $MODE section"
fi
# ── Required mode: enforcement hook ────────────────────────────
if [ "$MODE" = "required" ]; then
HOOKS_DIR="$REPO_ROOT/.claude/hooks"
SETTINGS="$REPO_ROOT/.claude/settings.json"
# Create enforcement hook script
mkdir -p "$HOOKS_DIR"
cat > "$HOOKS_DIR/check-gstack.sh" << 'HOOK_EOF'
#!/bin/bash
# Block skill usage when gstack is not installed globally.
#
# Resolve the install root the way gstack skill preambles do: the GSTACK_ROOT
# env var first, then every host's global install location, then the migrated
# repo location. Block only when NONE exist (#2500 — hardcoding
# ~/.claude/skills/gstack false-blocked Codex-host and migrated-repo installs).
_GSTACK_ROOT=""
for _D in "${GSTACK_ROOT:-}" "$HOME/.claude/skills/gstack" "$HOME/.codex/skills/gstack" "$HOME/.factory/skills/gstack" "$HOME/.kiro/skills/gstack" "$HOME/.config/opencode/skills/gstack" "$HOME/.slate/skills/gstack" "$HOME/.cursor/skills/gstack" "$HOME/.openclaw/skills/gstack" "$HOME/.hermes/skills/gstack" "$HOME/.gbrain/skills/gstack" "$HOME/.gstack/repos/gstack"; do
[ -z "$_GSTACK_ROOT" ] && [ -n "$_D" ] && [ -d "$_D/bin" ] && _GSTACK_ROOT="$_D"
done
if [ -z "$_GSTACK_ROOT" ]; then
cat >&2 <<'MSG'
BLOCKED: gstack is not installed globally.
gstack is required for AI-assisted work in this repo.
Install it:
git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup --team
Then restart your AI coding tool.
MSG
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"gstack is required but not installed. See stderr for install instructions."}}'
exit 2
fi
echo '{}'
HOOK_EOF
chmod +x "$HOOKS_DIR/check-gstack.sh"
GENERATED+=(".claude/hooks/check-gstack.sh")
echo " + .claude/hooks/check-gstack.sh — enforcement hook"
# Add hook to project-level settings.json
if command -v bun >/dev/null 2>&1; then
GSTACK_SETTINGS_PATH="$SETTINGS" bun -e "
const fs = require('fs');
const settingsPath = process.env.GSTACK_SETTINGS_PATH;
let settings = {};
try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
if (!settings.hooks) settings.hooks = {};
if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
// Dedup
const exists = settings.hooks.PreToolUse.some(entry =>
entry.matcher === 'Skill' &&
entry.hooks && entry.hooks.some(h => h.command && h.command.includes('check-gstack'))
);
if (!exists) {
settings.hooks.PreToolUse.push({
matcher: 'Skill',
hooks: [{
type: 'command',
command: '\"\$CLAUDE_PROJECT_DIR/.claude/hooks/check-gstack.sh\"'
}]
});
}
const tmp = settingsPath + '.tmp';
fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
fs.renameSync(tmp, settingsPath);
" 2>/dev/null
GENERATED+=(".claude/settings.json")
echo " + .claude/settings.json — PreToolUse hook registered"
else
echo " ! bun not found — manually add the PreToolUse hook to .claude/settings.json"
fi
fi
# ── Summary ────────────────────────────────────────────────────
echo ""
echo "Team mode ($MODE) initialized."
echo ""
if [ ${#GENERATED[@]} -gt 0 ]; then
echo "Commit the generated files:"
echo " git add ${GENERATED[*]}"
echo " git commit -m \"chore: require gstack for AI-assisted work\""
fi
echo ""
echo "Each developer then runs:"
echo " git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack"
echo " cd ~/.claude/skills/gstack && ./setup --team"
Reference in New Issue View Git Blame Copy Permalink