Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added guardrails for agents and commit hooks for humans when editing TS files (#14132)

Damian Legawiec0a32e46a0b62
diff --git a/.claude/hooks/post-edit-format.sh b/.claude/hooks/post-edit-format.sh
new file mode 100755
index 0000000000..272f3cda71
--- /dev/null
+++ b/.claude/hooks/post-edit-format.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# PostToolUse hook: auto-run Biome on the file Claude just edited.
+#
+# Reads the Claude Code hook input JSON from stdin, extracts the file_path,
+# filters to TS/JS/JSON family extensions, then runs `biome check --write`.
+# `--files-ignore-unknown=true` belt-and-suspenders for any extension that
+# slips past the grep. `cd` to project root first so pnpm finds the workspace
+# even when the agent is operating from a subdir or outside the repo.
+#
+# Always exits 0 — formatting failures should never block a file edit; the
+# pre-commit gate is the real enforcement layer.
+
+cd "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}" 2>/dev/null || exit 0
+
+file_path=$(jq -r '.tool_input.file_path // empty')
+[ -z "$file_path" ] && exit 0
+
+# Filter to extensions Biome formats.
+case "$file_path" in
+ *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.mts|*.cts|*.json|*.jsonc) ;;
+ *) exit 0 ;;
+esac
+
+# Pass the path as a single argv element via "$file_path" — no word-splitting,
+# spaces and special chars in the path are preserved.
+pnpm exec biome check --write \
+ --no-errors-on-unmatched \
+ --files-ignore-unknown=true \
+ --reporter=summary \
+ "$file_path" >&2 || true
+
+exit 0
diff --git a/.claude/hooks/pre-commit-gate.sh b/.claude/hooks/pre-commit-gate.sh
new file mode 100755
index 0000000000..db61936049
--- /dev/null
+++ b/.claude/hooks/pre-commit-gate.sh
@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Pre-commit/push gate invoked by Claude Code's PreToolUse hook for every Bash
+# tool call. Inspects the command on stdin (Claude hook input JSON) and only
+# enforces when an actual `git commit` or `git push` invocation is detected;
+# all other commands pass through.
+#
+# When triggered, runs Biome (formatting + lint) then turbo typecheck on
+# changed files vs main. Exits 2 to block the Bash tool call when either
+# fails, so the agent gets the diagnostic back and can fix before CI rejects.
+#
+# Tools are run sequentially with short-circuit: if Biome fails, typecheck is
+# skipped (the Biome diagnostic is enough to act on). Each tool's failure is
+# reported separately so the agent knows which to fix.
+
+set -u
+
+# Parse the command out of the Claude hook input JSON.
+cmd=$(jq -r '.tool_input.command // empty')
+
+# Split on shell separators (; && || | &) and check each segment for a real
+# git commit/push invocation. Handles env-var prefixes (FOO=bar, env FOO=bar)
+# and git's top-level option flags (-C path, -c k=v, --no-pager, etc.) so
+# `git -C path commit` and `GIT_AUTHOR_NAME=foo git commit` are caught, while
+# quoted strings (`echo 'git commit later'`) and other git subcommands
+# (`git checkout`, `git diff`) are not.
+#
+# On match, GIT_C_PATH holds the value passed to `-C` (empty when -C wasn't
+# used) so the caller can scope the gate to the repo the command targets.
+GIT_C_PATH=""
+match_segment() {
+ local seg="$1"
+ GIT_C_PATH=""
+ # shellcheck disable=SC2086
+ set -- $seg
+ # Skip leading env-var assignments (FOO=bar git ...)
+ while [ $# -gt 0 ] && [[ "$1" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do shift; done
+ # Skip optional `env` plus its own env assignments (env FOO=bar git ...)
+ if [ "${1:-}" = "env" ]; then
+ shift
+ while [ $# -gt 0 ] && [[ "$1" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do shift; done
+ fi
+ # Must now start with literal `git`
+ [ "${1:-}" = "git" ] || return 1
+ shift
+ # Skip git's top-level options between `git` and the subcommand,
+ # capturing -C path so the gate can validate the target repo.
+ while [ $# -gt 0 ]; do
+ case "$1" in
+ -C) GIT_C_PATH="${2:-}"; shift 2 ;;
+ -c|--git-dir|--work-tree|--namespace|--exec-path|--super-prefix|--config-env)
+ shift 2 ;;
+ --git-dir=*|--work-tree=*|--namespace=*|--exec-path=*|--super-prefix=*|--config-env=*|--paginate|--no-pager|--no-replace-objects|--bare|--literal-pathspecs|--glob-pathspecs|--noglob-pathspecs|--icase-pathspecs)
+ shift ;;
+ -*) shift ;;
+ *) break ;;
+ esac
+ done
+ case "${1:-}" in commit|push) return 0 ;; esac
+ return 1
+}
+
+trigger=0
+while IFS= read -r segment; do
+ if match_segment "$segment"; then trigger=1; break; fi
+done < <(echo "$cmd" | tr ';&|' '\n')
+
+[ $trigger -eq 1 ] || exit 0
+
+# Resolve the project root from CLAUDE_PROJECT_DIR (the env var Claude Code
+# sets to the session's project directory). Falling back to `git rev-parse`
+# from the hook's cwd is unreliable: if the agent's working directory is
+# outside the repo (e.g. /tmp), rev-parse fails and own_root ends up empty,
+# which both bypasses the `git -C` same-repo check and silently lets the
+# commit proceed with the gate running from the wrong directory.
+own_root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+if [ -z "$own_root" ] || [ ! -d "$own_root" ]; then
+ # No way to locate the project — fail closed by blocking the commit. exit 2
+ # is what Claude Code's PreToolUse contract uses to signal "block this tool
+ # call"; exit 1 would silently allow it through.
+ echo "Pre-commit gate could not resolve the project root (\$CLAUDE_PROJECT_DIR unset and not in a git repo)." >&2
+ exit 2
+fi
+own_root=$(cd "$own_root" && git rev-parse --show-toplevel 2>/dev/null)
+
+# If `git -C <path>` targets a different working tree from this project, skip:
+# the gate's lint/typecheck pass is only meaningful for the repo it was set up
+# in. Running it against an unrelated checkout would either block a foreign
+# commit on Spree-specific lint or pass a check that doesn't apply.
+if [ -n "$GIT_C_PATH" ]; then
+ target_root=$(git -C "$GIT_C_PATH" rev-parse --show-toplevel 2>/dev/null)
+ if [ -n "$target_root" ] && [ "$target_root" != "$own_root" ]; then
+ exit 0
+ fi
+fi
+
+cd "$own_root" || { echo "Pre-commit gate could not cd to $own_root" >&2; exit 2; }
+
+# 1. Biome — fast (~1s), covers formatting + lint on changed files only.
+biome_out=$(pnpm exec biome check --changed --since=main \
+ --no-errors-on-unmatched --files-ignore-unknown=true \
+ --reporter=summary 2>&1)
+biome_exit=$?
+
+if [ $biome_exit -ne 0 ]; then
+ echo "Biome check failed on changed files. CI will reject this commit." >&2
+ echo "" >&2
+ echo "$biome_out" >&2
+ echo "" >&2
+ echo "Fix: run 'pnpm exec biome check --changed --since=main --write' to apply safe fixes, then resolve any remaining lint errors before committing." >&2
+ exit 2
+fi
+
+# 2. Turbo typecheck — slower (1-9s depending on cache), runs tsc --noEmit
+# across the affected package graph. No --changed flag: turbo invalidates cache
+# based on file-content hashes, so untouched packages are instant.
+tsc_out=$(pnpm turbo typecheck 2>&1)
+tsc_exit=$?
+
+if [ $tsc_exit -ne 0 ]; then
+ echo "TypeScript check failed. CI will reject this commit." >&2
+ echo "" >&2
+ echo "$tsc_out" >&2
+ echo "" >&2
+ echo "Fix: resolve type errors above, or run 'pnpm turbo typecheck' to see them in context." >&2
+ exit 2
+fi
+
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000000..13167a9963
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,27 @@
+{
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
+ "hooks": {
+ "PostToolUse": [
+ {
+ "matcher": "Write|Edit|MultiEdit",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "exec \"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}/.claude/hooks/post-edit-format.sh\""
+ }
+ ]
+ }
+ ],
+ "PreToolUse": [
+ {
+ "matcher": "Bash",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "exec \"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}/.claude/hooks/pre-commit-gate.sh\""
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/lefthook.yml b/lefthook.yml
index a209c62e6c..9a3edb6fde 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,5 +1,9 @@
pre-commit:
commands:
+ biome:
+ glob: "**/*.{ts,tsx,js,jsx,mjs,cjs,mts,cts,json,jsonc}"
+ stage_fixed: true
+ run: pnpm exec biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}
typelizer-and-zod:
glob: "spree/api/app/serializers/**/*.rb"
run: |
@@ -8,3 +12,12 @@ pre-commit:
cd packages/sdk && pnpm generate:zod && cd ../..
git add packages/sdk/src/types/generated/ packages/sdk/src/zod/generated/
git add packages/admin-sdk/src/types/generated/
+
+pre-push:
+ commands:
+ biome-ci:
+ # No glob filter: biome ci scopes itself via --changed --since=main to
+ # validate the whole branch diff vs main. A glob would skip the check
+ # whenever a push touched zero TS files (e.g. Ruby-only follow-up push),
+ # missing TS issues from earlier commits already in the branch.
+ run: pnpm exec biome ci --changed --since=main --no-errors-on-unmatched --files-ignore-unknown=true