mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-20 15:13:47 +01:00
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>
251 lines
11 KiB
Bash
Executable File
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"
|