feat(installer): npx installer CLI (@garrytan/gstack) — interactive wizard + team init

[jkrperson]

Summary

Adds installer/ — a small TypeScript CLI that wraps the existing ./setup bash script behind npx @garrytan/gstack. Replaces the paste-prompt install flow with an interactive wizard. ./setup stays the source of truth; the CLI is a thin orchestrator.

Live demo (published by me under my own npm scope while this PR is in review):

npx @jkresabal/gstack

Try it end-to-end: install, init in a project, status, list, enable/disable, uninstall. When you're ready to ship upstream, the only change is the package name (instructions in installer/PUBLISHING.md).

What it does

• npx @garrytan/gstack → interactive @clack/prompts wizard, auto-detects git repo + installed hosts, multi-select host registration
• Verb-based subcommands for scripting: install, init, uninstall [--project], upgrade, doctor, status, list, enable <skill>, disable <skill>
• Writes a fenced <!-- gstack:begin --> / <!-- gstack:end --> block to CLAUDE.md listing every discovered skill (dynamically scanned, never stale)
• uninstall walks ~/.claude, ~/.codex, ~/.factory, ~/.config/opencode, ~/.kiro skills dirs and removes symlinks/dirs pointing into the gstack install (realpath-canonicalized for macOS /var ↔ /private/var), scrubs gstack-only PreToolUse hooks from .claude/settings.json, preserves non-gstack hooks and other settings keys, preserves ~/.gstack/ session state

Design choices

• Wrap ./setup, don't port it. Zero logic duplication. One invocation of ./setup --host <id> per selected host. If setup learns a new flag, I expose it with one line.
• Scoped package (@garrytan/gstack). Safer than unscoped gstack (may be taken); clearly owned.
• Thin runtime. ~2.3K LOC TypeScript → 16KB published tarball. Two deps: @clack/prompts + picocolors. Node 18+.
• Doesn't touch voice. Per CLAUDE.md community guardrails, I did not edit README.md or any existing skill templates. This PR is purely additive — the paste-prompt install flow still works unchanged. If you want to mention the new option alongside it, that's your call to make in a follow-up.

Tests

77 tests, ~3s runtime via bun:test:

• Unit: claude-md (fence insert/update/remove idempotency), skills (YAML frontmatter incl. |, >, quoted, skip dirs), project-config (enable/disable round-trip preserving other keys), cleanup (settings.json scrubbing preserves non-gstack hooks, realpath comparison for symlinked parents), paths (git root walk-up, isInstalled)
• Integration: spawns dist/cli.js against fake HOME fixtures — exit codes, enable/disable name normalization (qa / /qa / gstack-qa), full uninstall cycle preserving user settings, EPIPE handling under gstack list | head, wizard intro without TTY

cd installer && bun test         # 77 pass, 3s

End-to-end dry-run completed

Tested via npm link and npm pack against a real clone + real build on macOS arm64:

• Clone → bun install → bun run build (browse binary 59MB, Playwright Chromium 162MB download)
• 40 skills linked in ~/.claude/skills/
• CLAUDE.md block written
• doctor green across git, bun, install, version, browse binary, skills count, host registration
• Project init --tier required → .claude/hooks/check-gstack.sh + .claude/settings.json PreToolUse hook + staged for commit
• uninstall --yes → all 44 host symlinks removed, ~/.gstack/ preserved, 0 zombies

One real bug was caught and fixed during the dry-run (macOS /var vs /private/var symlink comparison in cleanup) and has a regression test.

How to ship

cd installer
npm install
npm run build
npm publish --access public   # publishes @garrytan/gstack

See installer/PUBLISHING.md for full details.

Known non-issue

upgrade calls ./setup --host auto, which auto-detects installed host CLIs and registers with all of them — so upgrading can broaden host registration beyond the original install --host selection. That matches ./setup --host auto semantics upstream. If you want upgrade to remember the original host selection, I can store it in ~/.gstack/config.yaml in a follow-up.

Test plan

• npx @jkresabal/gstack install --host claude --yes against a fake HOME=$(mktemp -d) completes clean
• gstack doctor is all-green after install
• gstack init --tier required inside a scratch git repo creates the hook + staged commit
• gstack uninstall --yes leaves ~/.claude/skills/ empty and preserves ~/.gstack/
• cd installer && bun test → 77 pass
• npm pack → 16KB tarball with 24 files
• Paste-prompt install flow still works (this PR does not modify setup, README.md, or any existing skill)