Refactor flag processing into shared utilities

Introduce `consumeFlagArg`, `matchFlagCategory`, and `consumeFusedFlag`
in `handler.go` to eliminate repetitive flag-parsing logic across all
command handlers. This significantly reduces boilerplate and ensures
consistent handling of subshell preservation and `--flag=value` syntax.

Author: micthiesen

.claude/settings.local.json

@@ -3,7 +3,9 @@
     "allow": [
       "Read(//usr/local/go/bin/**)",
       "Read(//opt/homebrew/bin/**)",
-      "mcp__fff__find_files"
+      "mcp__fff__find_files",
+      "mcp__fff__grep",
+      "mcp__fff__multi_grep"
     ]
   }
 }

.claude/skills/add-handler/SKILL.md

@@ -126,6 +126,11 @@ Key rules:
 - Use `isFlagToken(tok)` to distinguish flags from positionals
 - Use `classifyToken(tok)` for positionals that should get generic classification (usually file paths)
 - Walk tokens with an index variable (`i`), not `range`, when flags consume next args
+- Use the shared utilities from `handler.go` for flag processing (read the file to see what's available):
+  - `consumeFlagArg(tok, args, i, result, "<placeholder>")` to consume a flag and its next token (handles subshell preservation automatically)
+  - `flagCategory` + `matchFlagCategory` to replace repetitive if/else chains when you have 3+ flag categories
+  - `consumeFusedFlag(tok, categories)` to handle `--flag=value` syntax
+- When a handler has 3+ flag categories (e.g. pathFlags, valFlags, numericFlags), define a `categories` slice and use `matchFlagCategory` in the loop instead of sequential if blocks
 
 Reference `handler_grep.go` for a handler with flag-consuming arguments, or `handler_echo.go` for a simple positional-collapsing handler.
 

.github/workflows/ci.yml

@@ -9,9 +9,9 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
           cache: false

handler.go

@@ -1,9 +1,61 @@
 package shellshape
 
+import "strings"
+
 // handlerFunc processes tokens after the executable name.
 // subcommand is the subcommand token (empty if none).
 type handlerFunc func(subcommand string, tokens []string) []string
 
+// flagCategory pairs a set of flag names with the placeholder to use for their values.
+type flagCategory struct {
+	flags       map[string]bool
+	placeholder string
+}
+
+// consumeFlagArg appends a flag and its next-token value (collapsed to placeholder)
+// to result. Subshell tokens are preserved verbatim.
+func consumeFlagArg(tok string, args []string, i int, result []string, placeholder string) ([]string, int) {
+	result = append(result, tok)
+	i++
+	if i < len(args) {
+		if isSubshellToken(args[i]) {
+			result = append(result, args[i])
+		} else {
+			result = append(result, placeholder)
+		}
+		i++
+	}
+	return result, i
+}
+
+// matchFlagCategory checks tok against a list of flag categories and returns
+// the matching placeholder. Returns ("", false) if no category matches.
+func matchFlagCategory(tok string, categories []flagCategory) (string, bool) {
+	for _, cat := range categories {
+		if cat.flags[tok] {
+			return cat.placeholder, true
+		}
+	}
+	return "", false
+}
+
+// consumeFusedFlag handles --flag=value syntax against a list of flag categories.
+// Returns the normalized "flag=<placeholder>" string and true if matched,
+// or ("", false) if the token doesn't contain '=' or doesn't match any category.
+func consumeFusedFlag(tok string, categories []flagCategory) (string, bool) {
+	eqIdx := strings.IndexByte(tok, '=')
+	if eqIdx < 0 {
+		return "", false
+	}
+	key := tok[:eqIdx]
+	for _, cat := range categories {
+		if cat.flags[key] {
+			return key + "=" + cat.placeholder, true
+		}
+	}
+	return "", false
+}
+
 var redirectConsumeNext = map[string]bool{
 	">": true, ">>": true, "<": true,
 	"&>": true, "&>>": true,

handler_apt.go

@@ -48,16 +48,7 @@ func handleApt(subcommand string, tokens []string) []string {
 		}
 
 		if valFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				if isSubshellToken(args[i]) {
-					result = append(result, args[i])
-				} else {
-					result = append(result, "<val>")
-				}
-				i++
-			}
+			result, i = consumeFlagArg(tok, args, i, result, "<val>")
 			continue
 		}
 

handler_at.go

@@ -20,6 +20,13 @@ func handleAt(subcommand string, tokens []string) []string {
 	timeArgFlags := map[string]bool{"-t": true}
 	jobFlags := map[string]bool{"-c": true}
 
+	categories := []flagCategory{
+		{fileFlags, "<path>"},
+		{queueFlags, "<queue>"},
+		{timeArgFlags, "<time>"},
+		{jobFlags, "<job-id>"},
+	}
+
 	deleteMode := false
 
 	var result []string
@@ -36,43 +43,8 @@ func handleAt(subcommand string, tokens []string) []string {
 			continue
 		}
 
-		if fileFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<path>")
-				i++
-			}
-			continue
-		}
-
-		if queueFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<queue>")
-				i++
-			}
-			continue
-		}
-
-		if timeArgFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<time>")
-				i++
-			}
-			continue
-		}
-
-		if jobFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<job-id>")
-				i++
-			}
+		if placeholder, ok := matchFlagCategory(tok, categories); ok {
+			result, i = consumeFlagArg(tok, args, i, result, placeholder)
 			continue
 		}
 
@@ -119,12 +91,7 @@ func handleAtq(subcommand string, tokens []string) []string {
 		tok := args[i]
 
 		if tok == "-q" {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<queue>")
-				i++
-			}
+			result, i = consumeFlagArg(tok, args, i, result, "<queue>")
 			continue
 		}
 

handler_awk.go

@@ -43,22 +43,12 @@ func handleAwk(subcommand string, tokens []string) []string {
 		}
 
 		if fsFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<val>")
-				i++
-			}
+			result, i = consumeFlagArg(tok, args, i, result, "<val>")
 			continue
 		}
 
 		if varFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<val>")
-				i++
-			}
+			result, i = consumeFlagArg(tok, args, i, result, "<val>")
 			continue
 		}
 

handler_aws.go

@@ -57,6 +57,12 @@ func handleAws(subcommand string, tokens []string) []string {
 		"--ca-bundle": true,
 	}
 
+	categories := []flagCategory{
+		{queryFlags, "<query>"},
+		{numericFlags, "N"},
+		{pathFlags, "<path>"},
+	}
+
 	var result []string
 	subcmdAssigned := false
 
@@ -85,58 +91,14 @@ func handleAws(subcommand string, tokens []string) []string {
 			result = append(result, tok)
 			i++
 			if i < len(args) {
-				if isSubshellToken(args[i]) {
-					result = append(result, args[i])
-				} else {
-					result = append(result, args[i])
-				}
-				i++
-			}
-			continue
-		}
-
-		// Query flags: collapse value to <query>.
-		if queryFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				if isSubshellToken(args[i]) {
-					result = append(result, args[i])
-				} else {
-					result = append(result, "<query>")
-				}
+				result = append(result, args[i])
 				i++
 			}
 			continue
 		}
 
-		// Numeric flags: collapse value to N.
-		if numericFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				if isSubshellToken(args[i]) {
-					result = append(result, args[i])
-				} else {
-					result = append(result, "N")
-				}
-				i++
-			}
-			continue
-		}
-
-		// Path flags: collapse value to <path>.
-		if pathFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				if isSubshellToken(args[i]) {
-					result = append(result, args[i])
-				} else {
-					result = append(result, "<path>")
-				}
-				i++
-			}
+		if placeholder, ok := matchFlagCategory(tok, categories); ok {
+			result, i = consumeFlagArg(tok, args, i, result, placeholder)
 			continue
 		}
 

handler_base64.go

@@ -35,22 +35,12 @@ func handleBase64(subcommand string, tokens []string) []string {
 		}
 
 		if pathFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<path>")
-				i++
-			}
+			result, i = consumeFlagArg(tok, args, i, result, "<path>")
 			continue
 		}
 
 		if numericFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "N")
-				i++
-			}
+			result, i = consumeFlagArg(tok, args, i, result, "N")
 			continue
 		}
 

handler_biome.go

@@ -33,12 +33,7 @@ func handleBiome(subcommand string, tokens []string) []string {
 		}
 
 		if valueFlags[tok] {
-			result = append(result, tok)
-			i++
-			if i < len(args) {
-				result = append(result, "<val>")
-				i++
-			}
+			result, i = consumeFlagArg(tok, args, i, result, "<val>")
 			continue
 		}