Files
gstack/bin/gstack-team-init
T
6f1b4cad0f fix(team-init): make the required-mode hook shell-neutral (node CommonJS, no shell variables)
Rewrite of #2217. Required team mode wrote a bash check-gstack.sh and
registered it as "$CLAUDE_PROJECT_DIR/.claude/hooks/check-gstack.sh", which
only works when the hook runner is a POSIX shell. Under cmd.exe or PowerShell
(Windows, Copilot CLI) the variable is not expanded and the .sh cannot run, so
an intended allow or deny became a hook error.

- The hook is now .claude/hooks/check-gstack.cjs: the same root search
  (GSTACK_ROOT, every host's global root, the migrated repo), with the home
  directory from HOME, then USERPROFILE, then os.homedir(). It prints {} when
  gstack resolves and the PreToolUse deny JSON with exit 2 when not.
- The registered command is `node -e "require(require('path').resolve(
  process.env.CLAUDE_PROJECT_DIR || '.', '.claude', 'hooks',
  'check-gstack.cjs'))"`: no `$` or `%`, so sh, cmd.exe and PowerShell all
  pass it through unchanged.
- An existing check-gstack registration (matcher Skill or Skill|skill) is
  replaced in place; duplicates are dropped and unrelated hooks in the same
  entry kept. The legacy .sh is deleted only after the settings write
  succeeds (a tracked one joins the suggested git add), and is kept when bun
  is missing or the write fails, which now reports instead of claiming success.

Tests: team-mode and the hook-schema test run the command as registered;
test/team-init-hook-shell-neutral.test.ts runs it through the platform's
default shell (cmd.exe on the Windows lane, which curates it in) and through
PowerShell when installed (verified here in the pwsh 7 container). The
routing-probe check for the bash `_GSTACK_ROOT` gate now pins the same
contract in the .cjs: every host root probed, block only when none resolves.

Co-authored-by: neallee2012 <1499497+neallee2012@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-10-08 06:29:09 +00:00

251 lines
11 KiB
Bash
Executable File

#!/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 (Aside first, the bundled gstack browser as fallback). 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/.copilot/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 (Aside first, the bundled gstack browser as fallback).
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 the enforcement hook. Claude Code and Copilot CLI may run hook
# commands through sh, cmd.exe or PowerShell, so the hook is CommonJS run by
# node, and the registered command holds no shell variable syntax: it reads
# CLAUDE_PROJECT_DIR through process.env. `.cjs` keeps a project's
# package.json "type" from changing how node loads it.
mkdir -p "$HOOKS_DIR"
cat > "$HOOKS_DIR/check-gstack.cjs" << 'HOOK_EOF'
'use strict';
// 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).
const fs = require('fs');
const os = require('os');
const path = require('path');
const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
const roots = [process.env.GSTACK_ROOT || ''].concat([
'.claude/skills/gstack', '.codex/skills/gstack', '.factory/skills/gstack', '.kiro/skills/gstack',
'.config/opencode/skills/gstack', '.slate/skills/gstack', '.cursor/skills/gstack', '.openclaw/skills/gstack',
'.hermes/skills/gstack', '.gbrain/skills/gstack', '.copilot/skills/gstack', '.gstack/repos/gstack',
].map((rel) => path.join(home, rel)));
const gstackRoot = roots.find((root) => {
try { return root !== '' && fs.statSync(path.join(root, 'bin')).isDirectory(); } catch { return false; }
});
if (gstackRoot) {
process.stdout.write('{}\n');
} else {
process.stderr.write(`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.
`);
// Exit 2 denies on Claude Code (#2413) and on Copilot CLI, which treats a
// preToolUse exit 2 as deny (#2229).
process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny',
permissionDecisionReason: 'gstack is required but not installed. See stderr for install instructions.' } }) + '\n');
process.exitCode = 2;
}
HOOK_EOF
chmod +x "$HOOKS_DIR/check-gstack.cjs"
GENERATED+=(".claude/hooks/check-gstack.cjs")
echo " + .claude/hooks/check-gstack.cjs — enforcement hook"
# Add hook to project-level settings.json
HOOK_COMMAND="node -e \"require(require('path').resolve(process.env.CLAUDE_PROJECT_DIR || '.', '.claude', 'hooks', 'check-gstack.cjs'))\""
if ! command -v bun >/dev/null 2>&1; then
echo " ! bun not found — manually add this PreToolUse hook (matcher Skill|skill) to .claude/settings.json:"
echo " $HOOK_COMMAND"
elif GSTACK_SETTINGS_PATH="$SETTINGS" GSTACK_HOOK_COMMAND="$HOOK_COMMAND" bun -e "
const fs = require('fs');
const settingsPath = process.env.GSTACK_SETTINGS_PATH;
const command = process.env.GSTACK_HOOK_COMMAND;
let settings = {};
try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
if (!settings.hooks) settings.hooks = {};
if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
// Claude Code's skill tool is Skill; Copilot CLI's is skill, which no
// Claude tool name maps to, so a bare 'Skill' never fired there (#2229).
// A registration an older team-init wrote (the .sh hook, matcher Skill)
// is replaced in place: exactly one check-gstack handler remains, and
// unrelated hooks in the same entry are kept.
const MATCHER = 'Skill|skill';
const isOurs = h => h && typeof h.command === 'string' && h.command.includes('check-gstack');
let placed = false;
settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(entry => {
if (entry.matcher !== 'Skill' && entry.matcher !== MATCHER) return true;
if (!Array.isArray(entry.hooks) || !entry.hooks.some(isOurs)) return true;
entry.matcher = MATCHER;
const kept = [];
for (const h of entry.hooks) {
if (!isOurs(h)) kept.push(h);
else if (!placed) { kept.push({ type: 'command', command }); placed = true; }
}
entry.hooks = kept;
return kept.length > 0;
});
if (!placed) settings.hooks.PreToolUse.push({ matcher: MATCHER, hooks: [{ type: 'command', command }] });
const tmp = settingsPath + '.tmp';
fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
fs.renameSync(tmp, settingsPath);
"; then
GENERATED+=(".claude/settings.json")
echo " + .claude/settings.json — PreToolUse hook registered"
# The bash hook an older team-init wrote goes only once its replacement is
# registered; a tracked one is staged as a deletion by the git add below.
if [ -e "$HOOKS_DIR/check-gstack.sh" ]; then
rm -f "$HOOKS_DIR/check-gstack.sh"
git -C "$REPO_ROOT" ls-files --error-unmatch -- .claude/hooks/check-gstack.sh >/dev/null 2>&1 \
&& GENERATED+=(".claude/hooks/check-gstack.sh")
echo " - .claude/hooks/check-gstack.sh — replaced by check-gstack.cjs"
fi
else
echo " ! could not update .claude/settings.json — add this PreToolUse hook (matcher Skill|skill) manually:"
echo " $HOOK_COMMAND"
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"