claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/stack-hooks/go/go-format-on-edit.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# format-on-edit.sh — PostToolUse hook for Edit/Write
+# Runs gofmt -w on edited Go files.
+# Profile: standard, strict (skip on fast)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [[ ! "$FILE_PATH" =~ \.go$ ]]; then
+  exit 0
+fi
+
+if [ -f "$FILE_PATH" ]; then
+  gofmt -w "$FILE_PATH" 2>/dev/null
+fi
+
+exit 0

package/packages/stack-hooks/go/go-safety-check-on-edit.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# go-safety-check-on-edit.sh — PostToolUse hook for Edit/Write
+# Detects common Go safety traps: nil maps, defer in loops, append aliasing.
+# Profile: standard, strict
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then exit 0; fi
+if [[ ! "$FILE_PATH" =~ \.go$ ]]; then exit 0; fi
+if [ ! -f "$FILE_PATH" ]; then exit 0; fi
+
+WARNINGS=""
+
+# Check 1: Uninitialized map — var m map[...] without make()
+while IFS= read -r line; do
+  LINENO_=$(echo "$line" | cut -d: -f1)
+  NEXT_LINES=$(sed -n "$((LINENO_+1)),$((LINENO_+3))p" "$FILE_PATH" 2>/dev/null)
+  if ! echo "$NEXT_LINES" | grep -q 'make(\|= map\['; then
+    WARNINGS="${WARNINGS}\n  warning: go-safety: line ${LINENO_} — map declared without initialization (nil map panics on write)"
+    WARNINGS="${WARNINGS}\n    Fix: use make(map[K]V) or literal map[K]V{}"
+  fi
+done < <(grep -n 'var [a-zA-Z_]* map\[' "$FILE_PATH" 2>/dev/null)
+
+# Check 2: defer inside for loop
+while IFS= read -r line; do
+  LINENO_=$(echo "$line" | cut -d: -f1)
+  # Look backwards for enclosing 'for' within 20 lines
+  START=$((LINENO_ - 20))
+  if [ "$START" -lt 1 ]; then START=1; fi
+  CONTEXT=$(sed -n "${START},${LINENO_}p" "$FILE_PATH" 2>/dev/null)
+  if echo "$CONTEXT" | grep -q '^\s*for '; then
+    WARNINGS="${WARNINGS}\n  warning: go-safety: line ${LINENO_} — defer inside for loop (accumulates until function exit)"
+    WARNINGS="${WARNINGS}\n    Fix: wrap in closure or extract to separate function"
+  fi
+done < <(grep -n '^\s*defer ' "$FILE_PATH" 2>/dev/null)
+
+if [ -n "$WARNINGS" ]; then
+  echo -e "\nGo safety patterns detected:${WARNINGS}" >&2
+  echo "" >&2
+fi
+
+exit 0

package/packages/stack-hooks/go/go-vet-on-edit.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# go-vet-on-edit.sh — PostToolUse hook for Edit/Write
+# Runs go vet on the package containing the edited .go file.
+# Finds the nearest go.mod to determine the module root.
+# Profile: strict only
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" != "strict" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [[ ! "$FILE_PATH" =~ \.go$ ]]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Find nearest go.mod by walking up from the file's directory
+DIR=$(dirname "$FILE_PATH")
+MODULE_ROOT=""
+SEARCH_DIR="$DIR"
+while [ "$SEARCH_DIR" != "/" ] && [ "$SEARCH_DIR" != "." ]; do
+  if [ -f "$SEARCH_DIR/go.mod" ]; then
+    MODULE_ROOT="$SEARCH_DIR"
+    break
+  fi
+  SEARCH_DIR=$(dirname "$SEARCH_DIR")
+done
+
+if [ -z "$MODULE_ROOT" ]; then
+  exit 0
+fi
+
+cd "$MODULE_ROOT" 2>/dev/null || exit 0
+
+# Compute relative package path from module root
+REL_PKG="./${DIR#$MODULE_ROOT/}"
+
+RESULT=$(go vet "$REL_PKG" 2>&1)
+EXIT_CODE=$?
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "go vet issues:" >&2
+  echo "$RESULT" | head -15 >&2
+fi
+
+exit 0

package/packages/stack-hooks/go/golangci-lint-on-edit.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# golangci-lint-on-edit.sh — PostToolUse hook for Edit/Write
+# Runs golangci-lint on the package containing the edited .go file.
+# Profile: strict only (too slow for standard, ~2-5s)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" != "strict" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then exit 0; fi
+if [[ ! "$FILE_PATH" =~ \.go$ ]]; then exit 0; fi
+if [ ! -f "$FILE_PATH" ]; then exit 0; fi
+
+# Check golangci-lint is available
+if ! command -v golangci-lint &>/dev/null; then
+  exit 0
+fi
+
+# Find nearest go.mod
+DIR=$(dirname "$FILE_PATH")
+MODULE_ROOT=""
+SEARCH_DIR="$DIR"
+while [ "$SEARCH_DIR" != "/" ] && [ "$SEARCH_DIR" != "." ]; do
+  if [ -f "$SEARCH_DIR/go.mod" ]; then
+    MODULE_ROOT="$SEARCH_DIR"
+    break
+  fi
+  SEARCH_DIR=$(dirname "$SEARCH_DIR")
+done
+
+if [ -z "$MODULE_ROOT" ]; then exit 0; fi
+
+cd "$MODULE_ROOT" 2>/dev/null || exit 0
+
+REL_PKG="./${DIR#$MODULE_ROOT/}"
+
+RESULT=$(golangci-lint run --fast "$REL_PKG" 2>&1 | head -10)
+if [ -n "$RESULT" ]; then
+  echo "golangci-lint issues:" >&2
+  echo "$RESULT" >&2
+  echo "" >&2
+fi
+
+exit 0

package/packages/stack-hooks/python/ruff-on-edit.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# ruff-on-edit.sh — PostToolUse hook for Edit/Write
+# Runs ruff check --fix + ruff format on edited .py files.
+# Profile: standard, strict (skip on fast)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [[ ! "$FILE_PATH" =~ \.py$ ]]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Check if ruff is available
+if ! command -v ruff &>/dev/null; then
+  # Try via uvx or pipx as fallback
+  if command -v uvx &>/dev/null; then
+    RUFF="uvx ruff"
+  elif command -v pipx &>/dev/null; then
+    RUFF="pipx run ruff"
+  else
+    exit 0  # ruff not available, skip silently
+  fi
+else
+  RUFF="ruff"
+fi
+
+# Run ruff check with auto-fix (safe fixes only)
+$RUFF check --fix --select I "$FILE_PATH" 2>/dev/null
+
+# Run ruff format
+RESULT=$($RUFF format "$FILE_PATH" 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "ruff format issues:" >&2
+  echo "$RESULT" | head -10 >&2
+fi
+
+# Run ruff check (lint) and report remaining issues
+LINT_RESULT=$($RUFF check "$FILE_PATH" 2>&1)
+LINT_EXIT=$?
+
+if [ $LINT_EXIT -ne 0 ]; then
+  echo "ruff lint issues:" >&2
+  echo "$LINT_RESULT" | head -15 >&2
+fi
+
+exit 0

package/packages/stack-hooks/rust/cargo-check-on-edit.sh

@@ -0,0 +1,64 @@
+#!/bin/bash
+# cargo-check-on-edit.sh — PostToolUse hook for Edit/Write
+# Runs cargo check in the nearest Cargo.toml directory after .rs file edits.
+# Profile: standard, strict (skip on fast)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [[ ! "$FILE_PATH" =~ \.rs$ ]]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Find nearest Cargo.toml by walking up from the file's directory
+DIR=$(dirname "$FILE_PATH")
+CARGO_ROOT=""
+SEARCH_DIR="$DIR"
+while [ "$SEARCH_DIR" != "/" ] && [ "$SEARCH_DIR" != "." ]; do
+  if [ -f "$SEARCH_DIR/Cargo.toml" ]; then
+    CARGO_ROOT="$SEARCH_DIR"
+    break
+  fi
+  SEARCH_DIR=$(dirname "$SEARCH_DIR")
+done
+
+if [ -z "$CARGO_ROOT" ]; then
+  exit 0
+fi
+
+cd "$CARGO_ROOT" 2>/dev/null || exit 0
+
+# Run cargo check (faster than cargo build, catches type/borrow errors)
+RESULT=$(cargo check --message-format=short 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "cargo check errors in $CARGO_ROOT:" >&2
+  # Show only error lines (not warnings) first, then warnings
+  echo "$RESULT" | grep "^error" | head -10 >&2
+  WARN_COUNT=$(echo "$RESULT" | grep -c "^warning")
+  if [ "$WARN_COUNT" -gt 0 ]; then
+    echo "($WARN_COUNT warnings)" >&2
+  fi
+fi
+
+exit 0

package/packages/stack-hooks/typescript/typecheck-on-edit.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# typecheck-on-edit.sh — PostToolUse hook for Edit/Write
+# Runs tsc --noEmit after .ts/.tsx edits.
+# Finds the nearest tsconfig.json to determine the TypeScript project root.
+# Uses SHA256 hash cache to skip tsc if file unchanged since last successful check.
+# Profile: standard, strict (skip on fast)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+if [[ ! "$FILE_PATH" =~ \.(ts|tsx)$ ]]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# --- Hash cache: skip tsc if file unchanged since last successful check ---
+CACHE_DIR="$HOME/.cache/claude-typecheck"
+mkdir -p "$CACHE_DIR" 2>/dev/null
+
+HASH=$(shasum -a 256 "$FILE_PATH" 2>/dev/null | cut -d' ' -f1)
+CACHE_KEY="$CACHE_DIR/$(echo "$FILE_PATH" | tr '/' '_').hash"
+if [ -n "$HASH" ] && [ -f "$CACHE_KEY" ] && [ "$(cat "$CACHE_KEY" 2>/dev/null)" = "$HASH" ]; then
+  exit 0  # Unchanged since last successful check — skip tsc
+fi
+
+# Find nearest tsconfig.json by walking up from the file's directory
+DIR=$(dirname "$FILE_PATH")
+TS_ROOT=""
+SEARCH_DIR="$DIR"
+while [ "$SEARCH_DIR" != "/" ] && [ "$SEARCH_DIR" != "." ]; do
+  if [ -f "$SEARCH_DIR/tsconfig.json" ]; then
+    TS_ROOT="$SEARCH_DIR"
+    break
+  fi
+  SEARCH_DIR=$(dirname "$SEARCH_DIR")
+done
+
+if [ -z "$TS_ROOT" ]; then
+  exit 0
+fi
+
+cd "$TS_ROOT" 2>/dev/null || exit 0
+
+RESULT=$(npx tsc --noEmit 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "TypeScript errors in $TS_ROOT:" >&2
+  echo "$RESULT" | head -20 >&2
+  rm -f "$CACHE_KEY" 2>/dev/null
+else
+  # Save hash on successful check
+  if [ -n "$HASH" ] && [ -n "$CACHE_KEY" ]; then
+    echo "$HASH" > "$CACHE_KEY" 2>/dev/null
+  fi
+fi
+
+exit 0

package/packages/stack-rules/go/go-conventions.md

@@ -0,0 +1,44 @@
+---
+alwaysApply: false
+applyWhenPaths:
+  - "**/*.go"
+tokens: 409
+---
+
+# Go Conventions
+
+## Naming
+- MixedCaps for all names (not snake_case, not SCREAMING_CASE). Acronyms fully capitalized: `HTTPClient`, `userID`, `parseURL`
+- Package names: lowercase, single word, no underscores. Never `util`, `common`, `base`, `helpers`
+- Interfaces: verb or -er suffix (`Reader`, `Validator`, `Closer`). Max 3 methods. Declare at consumer side
+- Error variables: `ErrNotFound`, `ErrValidation` (Err prefix + PascalCase)
+- Avoid stuttering: `http.Client` not `http.HTTPClient`, `user.New()` not `user.NewUser()`
+
+## Patterns
+- Constructors: `NewX(deps) *X`, validate inside, return error if validation can fail
+- >3 optional params: use functional options pattern (`func WithTimeout(d time.Duration) Option`)
+- Enums: `iota` with `Unknown = 0` as zero value. Always include `String()` method
+- Early returns (guard clauses), not deep nesting. Happy path at lowest indentation
+- Accept interfaces, return structs. Keep interfaces small
+
+## Error Handling
+- Always wrap with caller context: `fmt.Errorf("Type.Method: %w", err)` — free-text parts lowercase, no trailing punctuation
+
+```go
+// BAD — logs AND returns, no context
+log.Printf("save failed: %v", err)
+return err
+// GOOD — wrap with caller name, return only
+return fmt.Errorf("UserRepo.Save: %w", err)
+```
+
+- Log OR return, never both. Handlers log; services/repos return
+- Sentinel errors (`var ErrNotFound = errors.New(...)`) for expected domain conditions
+- `errors.Is()` / `errors.As()` for inspection, never `==` or type assertion
+- Domain errors map to HTTP status in handlers only — services return domain errors
+
+## Context
+- `ctx context.Context` always first parameter, always named `ctx`
+- Never store context in structs — pass explicitly
+- `context.Background()` only in main, init, tests
+- `defer cancel()` immediately after `context.WithCancel` / `WithTimeout` / `WithDeadline`

package/packages/stack-rules/go/go-safety.md

@@ -0,0 +1,35 @@
+---
+alwaysApply: false
+applyWhenPaths:
+  - "**/*.go"
+tokens: 512
+---
+
+# Go Safety Guardrails
+
+Apply to every Go file you write or edit. In reviews, a violation of these is at least WARNING; panic, data-race, or leak paths are CRITICAL.
+
+## Nil Traps
+- Always `make()` maps before write — nil map panics: `m := make(map[K]V)`
+- Typed nil pointer in interface is NOT nil — `var p *MyType; var i MyInterface = p; i != nil` is TRUE
+- Check pointer receivers for nil in public methods of exported types
+
+## Concurrency
+- Every goroutine needs a shutdown mechanism: `ctx.Done()`, done channel, or explicit signal
+- Only senders close channels — closing a closed channel panics
+- Every `select` that can block, in code where a `ctx` is in scope, needs a `ctx.Done()` case. Exempt: non-blocking `select` with `default`, and code with no context available
+- No `time.After` in loops — creates new timer (and leak) per iteration. Use `time.NewTimer` + `Reset()`
+
+## Memory
+- `append` may grow into a new array or reuse the old one — always assign the result back to the SAME slice: `s = append(s, x)`. Hazard: `b := append(a, x)` compiles but `b` can share `a`'s backing array, so a write through one mutates the other. Need an independent slice → `copy` explicitly
+- `defer` in loops accumulates all defers until function exit — wrap body in closure or extract to function
+- Sub-slice of large slice retains entire backing array in memory — copy if keeping small piece of large data
+
+## Numeric
+- `int64` -> `int32` truncates silently — use explicit conversion with bounds check
+- Float `==` comparison unreliable — use epsilon: `math.Abs(a-b) < epsilon`
+- Integer overflow wraps silently — check bounds before arithmetic on user input
+
+## Linter Suppression
+- `//nolint` directives MUST name the specific linter AND carry a justification comment (nolintlint style: `//nolint:gosec // reason`). A bare or unjustified `//nolint` is at least WARNING
+- NEVER suppress a security linter (`gosec`, `bodyclose`, `sqlclosecheck`) without a documented strong reason — a suppressed security linter with no documented reason is CRITICAL