Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: set geo rejects negative coordinates, so the western hemisphere and everything south of the equator are unreachable (PIN-213)

Luigi Agosti84a418c137fd
diff --git a/cmd/pinchtab/cmd_cli_browser_actions.go b/cmd/pinchtab/cmd_cli_browser_actions.go
index 23446483..6abffd94 100644
--- a/cmd/pinchtab/cmd_cli_browser_actions.go
+++ b/cmd/pinchtab/cmd_cli_browser_actions.go
@@ -123,10 +123,10 @@ var scrollCmd = &cobra.Command{
Long: `Scroll the page. Give either --dy/--dx or one positional argument.
1. Pixels: --dy <n> vertically, --dx <n> horizontally (positive down/right).
- A negative count needs the flag — cobra reads a leading minus on a
- positional as a bundle of shorthand flags, so "scroll -300" cannot parse.
+ A negative count works either way; both forms take --tab in any position.
pinchtab scroll --dy 800
pinchtab scroll --dy -300
+ pinchtab scroll -300
2. Direction keyword: up | down | left | right (defaults to 800px per step).
pinchtab scroll down
@@ -152,15 +152,16 @@ Precedence: integer and direction keywords win over selector parsing so that
}
// scrollArgs refuses a second positional, which is what made a mistyped scroll
-// silently scroll the WRONG tab: the only spelling of a negative count used to be
+// silently scroll the WRONG tab: a negative count used to be spellable only as
// `scroll -- -300`, everything after `--` is a positional, and MinimumNArgs(1)
// accepted `--tab <id>` as args[1:] and dropped it — so the action ran on the
-// current tab and reported OK. It also refuses the empty and the doubly-specified
-// forms, since --dy/--dx and the positional are two spellings of one argument.
+// current tab and reported OK. A hand-written `--` still lands here, and still
+// refuses. It also refuses the empty and the doubly-specified forms, since
+// --dy/--dx and the positional are two spellings of one argument.
func scrollArgs(cmd *cobra.Command, args []string) error {
byFlag := cmd.Flags().Changed("dy") || cmd.Flags().Changed("dx")
if len(args) > 1 {
- return fmt.Errorf("accepts at most 1 positional argument, received %d (%s); a negative count is --dy <n>, and flags must not follow --", len(args), strings.Join(args, " "))
+ return fmt.Errorf("accepts at most 1 positional argument, received %d (%s); a negative count needs no escape (pinchtab scroll -300), and flags must not follow --", len(args), strings.Join(args, " "))
}
if len(args) == 0 && !byFlag {
return fmt.Errorf("needs a positional <pixels|direction|selector> or --dy/--dx")
diff --git a/cmd/pinchtab/cmd_cli_emulation.go b/cmd/pinchtab/cmd_cli_emulation.go
index 13f97697..2b0860ac 100644
--- a/cmd/pinchtab/cmd_cli_emulation.go
+++ b/cmd/pinchtab/cmd_cli_emulation.go
@@ -26,8 +26,14 @@ var setViewportCmd = &cobra.Command{
var setGeoCmd = &cobra.Command{
Use: "geo <latitude> <longitude>",
Short: "Set browser geolocation",
- Long: "Set the browser geolocation using CDP emulation. Accepts optional --accuracy flag.",
- Args: cobra.ExactArgs(2),
+ Long: `Set the browser geolocation using CDP emulation. Accepts optional --accuracy flag.
+
+Negative coordinates need no escaping, so the western hemisphere and everything
+south of the equator are written the same way as anywhere else:
+
+ pinchtab set geo 51.5 -0.12 --tab <id> # London
+ pinchtab set geo -33.8 151.2 --tab <id> # Sydney`,
+ Args: cobra.ExactArgs(2),
Run: func(cmd *cobra.Command, args []string) {
runCLI(func(rt cliRuntime) {
browseractions.SetGeolocation(rt.client, rt.base, rt.token, cmd, args)
diff --git a/cmd/pinchtab/cmd_cli_scroll_test.go b/cmd/pinchtab/cmd_cli_scroll_test.go
index 585776c0..a67975e4 100644
--- a/cmd/pinchtab/cmd_cli_scroll_test.go
+++ b/cmd/pinchtab/cmd_cli_scroll_test.go
@@ -204,36 +204,3 @@ func TestDocumentedScrollDirectionsAreExactlyTheSupportedOnes(t *testing.T) {
}
}
}
-
-// scroll -300 was an example in this help and in the agent-facing reference, and it never
-// parsed — cobra reads the leading minus as shorthand flags. Both sites are checked here
-// because a doc that teaches an unparseable command is how this reached a user.
-func TestNoDocumentedScrollExampleUsesABareNegativePositional(t *testing.T) {
- docs := map[string]string{"scroll --help": scrollCmd.Long}
-
- for _, path := range []string{
- filepath.Join("..", "..", "skills", "pinchtab", "references", "commands.md"),
- filepath.Join("..", "..", "docs", "reference", "scroll.md"),
- } {
- raw, err := os.ReadFile(path)
- if err != nil {
- t.Fatalf("cannot read %s, so this guard would not cover the doc site it names: %v", path, err)
- }
- docs[filepath.ToSlash(path)] = string(raw)
- }
-
- for site, text := range docs {
- for _, line := range strings.Split(text, "\n") {
- fields := strings.Fields(line)
- for i, field := range fields {
- if field != "scroll" || i+1 >= len(fields) {
- continue
- }
- next := fields[i+1]
- if len(next) > 1 && next[0] == '-' && next[1] >= '0' && next[1] <= '9' {
- t.Errorf("%s teaches %q, which cobra reads as shorthand flags and refuses; a negative count is --dy <n>", site, strings.TrimSpace(line))
- }
- }
- }
- }
-}
diff --git a/cmd/pinchtab/negative_positionals.go b/cmd/pinchtab/negative_positionals.go
new file mode 100644
index 00000000..dc646d9c
--- /dev/null
+++ b/cmd/pinchtab/negative_positionals.go
@@ -0,0 +1,163 @@
+package main
+
+import (
+ "strings"
+
+ "github.com/spf13/cobra"
+ "github.com/spf13/pflag"
+)
+
+// A leading-minus positional is parsed by pflag as a bundle of shorthand flags, so
+// `pinchtab set geo -33.8 151.2` failed with "unknown shorthand flag: `3`" and the whole
+// southern hemisphere was unreachable. The same one-line failure hit `scroll -300`,
+// `mouse wheel -200` and `mouse move -5 -5`.
+//
+// The escape cobra offers is `--`, but it also stops flag parsing, so the caller has to
+// write flags FIRST — `set geo --tab X -- -33.8 151.2` — which is undocumented and the
+// reverse of the ordering every example teaches. This rewrites the caller's arguments
+// into exactly that working order, once, for every command, rather than giving four
+// commands signed flags and leaving the fifth to be forgotten.
+//
+// THE PROPERTY IT RESTS ON: no shorthand flag registered anywhere in this CLI is a digit,
+// so a token whose first character after the minus is a digit or a decimal point is
+// unambiguously a number and never a flag. negative_positionals_test.go asserts that over
+// the whole command tree, because a future digit shorthand would silently make this
+// rewrite wrong.
+//
+// It fires ONLY when such a token is present and would be read as a positional. Every
+// other invocation is returned byte-identical, which is what keeps a rewrite this broad
+// safe.
+func rewriteNegativeNumberArgs(root *cobra.Command, args []string) []string {
+ path, flags, positionals, ok := classifyArgs(root, args)
+ if !ok || !holdsNegativeNumber(positionals) {
+ return args
+ }
+
+ rewritten := make([]string, 0, len(args)+1)
+ rewritten = append(rewritten, path...)
+ rewritten = append(rewritten, flags...)
+ rewritten = append(rewritten, "--")
+ return append(rewritten, positionals...)
+}
+
+func subcommandNamed(cmd *cobra.Command, name string) *cobra.Command {
+ for _, sub := range cmd.Commands() {
+ if sub.Name() == name || sub.HasAlias(name) {
+ return sub
+ }
+ }
+ return nil
+}
+
+// classifyArgs sorts every token into the command path, the flags, and the positionals in
+// ONE pass, descending as it goes — a flag may legitimately precede a subcommand
+// (`pinchtab --json set geo …`), so the path and the flags have to be recognised together
+// rather than in two phases.
+//
+// Tokens are classified the way pflag will classify them, so a negative number that is a
+// flag's VALUE (`--dy -300`) stays with its flag and only a genuine positional moves. The
+// first token that is neither a flag nor a subcommand ends the path: from there on every
+// non-flag token is data, so a positional spelling some command's name is never mistaken
+// for one.
+//
+// ok is false when the caller already wrote `--` — they have chosen the argument order
+// themselves and nothing here should second-guess it.
+func classifyArgs(root *cobra.Command, args []string) (path, flags, positionals []string, ok bool) {
+ cmd := root
+ pathOpen := true
+ for i := 0; i < len(args); i++ {
+ arg := args[i]
+ switch {
+ case arg == "--":
+ return nil, nil, nil, false
+ case strings.HasPrefix(arg, "-") && arg != "-" && !looksNumeric(arg):
+ flags = append(flags, arg)
+ if consumesNextToken(cmd, arg) && i+1 < len(args) {
+ i++
+ flags = append(flags, args[i])
+ }
+ default:
+ if sub := subcommandNamed(cmd, arg); pathOpen && sub != nil {
+ path = append(path, arg)
+ cmd = sub
+ continue
+ }
+ pathOpen = false
+ positionals = append(positionals, arg)
+ }
+ }
+ return path, flags, positionals, true
+}
+
+// looksNumeric reports a token pflag would read as shorthand flags but a human wrote as a
+// number. Only the leading minus matters: the digit-shorthand property above is what makes
+// the first character decisive, so this does not need to parse the whole token — `-3abc`
+// is not a number, but it is not a flag either, and letting it through as a positional
+// gives a refusal that names it instead of one naming the character `3`.
+func looksNumeric(arg string) bool {
+ rest := strings.TrimPrefix(arg, "-")
+ if rest == arg || rest == "" {
+ return false
+ }
+ rest = strings.TrimPrefix(rest, ".")
+ return rest != "" && rest[0] >= '0' && rest[0] <= '9'
+}
+
+// consumesNextToken reports whether a flag token takes its value from the FOLLOWING
+// token, which is the only case where the next token must travel with it. A flag written
+// --name=value or -nvalue carries its own, and a boolean carries none.
+func consumesNextToken(cmd *cobra.Command, arg string) bool {
+ if strings.HasPrefix(arg, "--") {
+ name, attached := cutFlagValue(arg[2:])
+ if attached {
+ return false
+ }
+ return takesValue(cmd.Flags().Lookup(name), cmd.InheritedFlags().Lookup(name))
+ }
+
+ // A shorthand bundle: pflag walks the characters and gives the REST of the token to
+ // the first one that wants a value, so only a value-taking flag in final position
+ // reaches for the next token.
+ shorthands := arg[1:]
+ for i := 0; i < len(shorthands); i++ {
+ c := shorthands[i : i+1]
+ if c[0] >= 0x80 {
+ // pflag only looks up single ASCII shorthands and panics on anything else, so a
+ // non-ASCII byte is not a flag this walk can reason about.
+ return false
+ }
+ if !takesValue(cmd.Flags().ShorthandLookup(c), cmd.InheritedFlags().ShorthandLookup(c)) {
+ continue
+ }
+ return i == len(shorthands)-1
+ }
+ return false
+}
+
+func takesValue(candidates ...*pflag.Flag) bool {
+ for _, flag := range candidates {
+ if flag != nil {
+ return flag.NoOptDefVal == ""
+ }
+ }
+ // An unknown flag is about to be refused by cobra whatever we do here; assuming it
+ // takes no value keeps the following token a positional, so the refusal names the
+ // flag rather than an argument count.
+ return false
+}
+
+func cutFlagValue(name string) (string, bool) {
+ if i := strings.IndexByte(name, '='); i >= 0 {
+ return name[:i], true
+ }
+ return name, false
+}
+
+func holdsNegativeNumber(args []string) bool {
+ for _, arg := range args {
+ if looksNumeric(arg) {
+ return true
+ }
+ }
+ return false
+}
diff --git a/cmd/pinchtab/negative_positionals_test.go b/cmd/pinchtab/negative_positionals_test.go
new file mode 100644
index 00000000..7248b8b2
--- /dev/null
+++ b/cmd/pinchtab/negative_positionals_test.go
@@ -0,0 +1,360 @@
+package main
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/spf13/cobra"
+ "github.com/spf13/pflag"
+
+ "github.com/pinchtab/pinchtab/internal/srccensus"
+)
+
+// The four commands measured as broken at HEAD, each with the coordinate or delta that
+// could not be expressed. Every one failed with "unknown shorthand flag" on the first
+// digit of its own argument.
+func TestNegativeArgumentsAreMovedBehindTheFlags(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ args []string
+ want []string
+ }{
+ {
+ name: "a southern latitude and a western longitude in one command",
+ args: []string{"set", "geo", "-33.8", "-151.2", "--tab", "T"},
+ want: []string{"set", "geo", "--tab", "T", "--", "-33.8", "-151.2"},
+ },
+ {
+ name: "the house ordering, flag last",
+ args: []string{"set", "geo", "51.5", "-0.12", "--tab", "T"},
+ want: []string{"set", "geo", "--tab", "T", "--", "51.5", "-0.12"},
+ },
+ {
+ name: "scroll up by pixels",
+ args: []string{"scroll", "-300", "--tab", "T"},
+ want: []string{"scroll", "--tab", "T", "--", "-300"},
+ },
+ {
+ name: "a negative wheel delta",
+ args: []string{"mouse", "wheel", "-200"},
+ want: []string{"mouse", "wheel", "--", "-200"},
+ },
+ {
+ name: "two negative viewport coordinates",
+ args: []string{"mouse", "move", "-5", "-5"},
+ want: []string{"mouse", "move", "--", "-5", "-5"},
+ },
+ {
+ name: "a flag before the subcommand still parses as a flag",
+ args: []string{"set", "geo", "-33.8", "151.2", "--json"},
+ want: []string{"set", "geo", "--json", "--", "-33.8", "151.2"},
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ got := rewriteNegativeNumberArgs(rootCmd, tc.args)
+ if strings.Join(got, " ") != strings.Join(tc.want, " ") {
+ t.Errorf("rewrite = %v, want %v", got, tc.want)
+ }
+ })
+ }
+}
+
+// The safety property that makes a rewrite this broad acceptable: an invocation with no
+// negative-number positional comes back byte-identical, so nothing else in the CLI can
+// change shape because of this.
+func TestEveryOtherInvocationIsUntouched(t *testing.T) {
+ for _, args := range [][]string{
+ {"set", "geo", "51.5", "0.12", "--tab", "T"},
+ {"set", "viewport", "800", "600"},
+ {"scroll", "800"},
+ {"scroll", "down"},
+ {"scroll", "--dy", "-300", "--tab", "T"},
+ {"mouse", "wheel", "--dy", "-200"},
+ {"config", "get", "server.port"},
+ {"config", "set", "browser.proxy.username", "bob"},
+ {"screenshot", "-o", "shot.png"},
+ {"text", "--tab", "T"},
+ {"scroll", "--", "-300"},
+ // PIN-136's trap, which must stay refused: after a hand-written `--` the tab flag is
+ // a positional, so scroll sees three and says so. Rewriting this form would silently
+ // turn it into a working command aimed at that tab, changing a landed refusal.
+ {"scroll", "--", "-300", "--tab", "T"},
+ {"set", "geo", "--tab", "T", "--", "51.5", "-0.12"},
+ {"--help"},
+ {},
+ } {
+ t.Run(strings.Join(args, "_"), func(t *testing.T) {
+ got := rewriteNegativeNumberArgs(rootCmd, args)
+ if strings.Join(got, "\x00") != strings.Join(args, "\x00") {
+ t.Errorf("rewrite changed an invocation it has no business touching:\n in %v\n out %v", args, got)
+ }
+ })
+ }
+}
+
+// A negative number that is a flag's VALUE must stay with its flag. Moving it would hand
+// --dy nothing and turn the delta into a positional the command never asked for.
+func TestAFlagValueThatLooksNegativeStaysWithItsFlag(t *testing.T) {
+ got := rewriteNegativeNumberArgs(rootCmd, []string{"scroll", "--dy", "-300", "--tab", "T"})
+ if strings.Join(got, " ") != "scroll --dy -300 --tab T" {
+ t.Fatalf("rewrite = %v, want the input unchanged — -300 belongs to --dy", got)
+ }
+}
+
+// The end of the claim: the rewritten form actually parses, on the real commands, through
+// the real pflag parser. The original form is asserted to FAIL in the same test, so this
+// cannot pass on a build where the defect was never there.
+func TestTheRewrittenFormParsesWhereTheOriginalDoesNot(t *testing.T) {
+ for _, tc := range []struct {
+ path []string
+ args []string
+ want []string
+ flag string
+ value string
+ }{
+ {path: []string{"set", "geo"}, args: []string{"-33.8", "151.2", "--tab", "T"}, want: []string{"-33.8", "151.2"}, flag: "tab", value: "T"},
+ {path: []string{"scroll"}, args: []string{"-300", "--tab", "T"}, want: []string{"-300"}, flag: "tab", value: "T"},
+ {path: []string{"mouse", "wheel"}, args: []string{"-200"}, want: []string{"-200"}},
+ {path: []string{"mouse", "move"}, args: []string{"-5", "-5"}, want: []string{"-5", "-5"}},
+ } {
+ t.Run(strings.Join(tc.path, " "), func(t *testing.T) {
+ cmd := commandAt(t, tc.path...)
+
+ if err := freshFlagSet(t, cmd).Parse(tc.args); err == nil {
+ t.Fatalf("%v parsed as written, so this build never had the defect and the rewrite proves nothing", tc.args)
+ }
+
+ full := append(append([]string{}, tc.path...), tc.args...)
+ rewritten := rewriteNegativeNumberArgs(rootCmd, full)
+ flags := freshFlagSet(t, cmd)
+ if err := flags.Parse(rewritten[len(tc.path):]); err != nil {
+ t.Fatalf("the rewritten form still does not parse: %v (%v)", err, rewritten)
+ }
+ if strings.Join(flags.Args(), " ") != strings.Join(tc.want, " ") {
+ t.Errorf("positionals = %v, want %v", flags.Args(), tc.want)
+ }
+ if tc.flag != "" {
+ if got := flags.Lookup(tc.flag).Value.String(); got != tc.value {
+ t.Errorf("--%s = %q, want %q — a flag after the positional must still reach the command", tc.flag, got, tc.value)
+ }
+ }
+ })
+ }
+}
+
+// The whole rewrite rests on a token starting -<digit> being unambiguously a number. A
+// digit shorthand would make that false, silently, for every command at once — so the
+// assumption is asserted over the tree rather than written down and hoped for.
+func TestNoShorthandFlagIsADigit(t *testing.T) {
+ checked := 0
+ visitAllCommands(rootCmd, func(cmd *cobra.Command) {
+ inspect := func(flag *pflag.Flag) {
+ checked++
+ if flag.Shorthand == "" {
+ return
+ }
+ if flag.Shorthand[0] >= '0' && flag.Shorthand[0] <= '9' {
+ t.Errorf("%s registers -%s as a shorthand for --%s; a digit shorthand makes a negative number ambiguous and breaks the rewrite in negative_positionals.go for EVERY command — pick a letter",
+ cmd.CommandPath(), flag.Shorthand, flag.Name)
+ }
+ }
+ cmd.Flags().VisitAll(inspect)
+ cmd.PersistentFlags().VisitAll(inspect)
+ })
+ if checked == 0 {
+ t.Fatal("no flag was inspected; this guard would pass vacuously")
+ }
+}
+
+// The census the card corrected: the predicate is a positional whose value range includes
+// negatives, not an argument-count shape. These are the four it found, and each must
+// accept its negative without the caller writing `--`.
+func TestTheFourMeasuredCommandsAllAcceptANegativePositional(t *testing.T) {
+ for _, args := range [][]string{
+ {"set", "geo", "-33.8", "151.2"},
+ {"scroll", "-300"},
+ {"mouse", "wheel", "-200"},
+ {"mouse", "move", "-5", "-5"},
+ } {
+ t.Run(strings.Join(args, "_"), func(t *testing.T) {
+ rewritten := rewriteNegativeNumberArgs(rootCmd, args)
+ if !containsToken(rewritten, "--") {
+ t.Fatalf("%v was left as written, so it still fails on its own first digit", args)
+ }
+ })
+ }
+}
+
+func commandAt(t *testing.T, path ...string) *cobra.Command {
+ t.Helper()
+ cmd, _, err := rootCmd.Find(path)
+ if err != nil || cmd.CommandPath() != "pinchtab "+strings.Join(path, " ") {
+ t.Fatalf("cannot find %q in the command tree (got %q, err %v)", strings.Join(path, " "), cmd.CommandPath(), err)
+ }
+ return cmd
+}
+
+// freshFlagSet is a copy of the command's own flags, so parsing here cannot leave values
+// behind on the shared command tree for the next test to read.
+func freshFlagSet(t *testing.T, cmd *cobra.Command) *pflag.FlagSet {
+ t.Helper()
+ set := pflag.NewFlagSet(cmd.Name(), pflag.ContinueOnError)
+ set.SetOutput(discardWriter{})
+ copyFlag := func(flag *pflag.Flag) {
+ clone := *flag
+ value := stringValue(flag.Value.String())
+ clone.Value = &value
+ set.AddFlag(&clone)
+ }
+ cmd.Flags().VisitAll(copyFlag)
+ cmd.InheritedFlags().VisitAll(func(flag *pflag.Flag) {
+ if set.Lookup(flag.Name) == nil {
+ copyFlag(flag)
+ }
+ })
+ return set
+}
+
+type discardWriter struct{}
+
+func (discardWriter) Write(p []byte) (int, error) { return len(p), nil }
+
+type stringValue string
+
+func (s *stringValue) String() string { return string(*s) }
+func (s *stringValue) Set(v string) error { *s = stringValue(v); return nil }
+func (s *stringValue) Type() string { return "string" }
+
+func visitAllCommands(cmd *cobra.Command, visit func(*cobra.Command)) {
+ visit(cmd)
+ for _, sub := range cmd.Commands() {
+ visitAllCommands(sub, visit)
+ }
+}
+
+func containsToken(args []string, want string) bool {
+ for _, arg := range args {
+ if arg == want {
+ return true
+ }
+ }
+ return false
+}
+
+// The doc sites an agent reads, plus every command's own help. This replaces the
+// scroll-local ban that stood here before: that guard forbade documenting a negative
+// positional because it could not parse, which the rewrite above makes false. The
+// property worth guarding is the same one either way — a documented example must work —
+// so it is now asserted by RUNNING each documented example through the rewrite and the
+// real parser, rather than by banning a spelling.
+var documentedExampleSites = []string{
+ "skills/pinchtab/references/commands.md",
+ "docs/reference/scroll.md",
+}
+
+func TestEveryDocumentedNegativeExampleParses(t *testing.T) {
+ examples := documentedPinchtabExamples(t)
+ if len(examples) == 0 {
+ t.Fatal("no pinchtab example was found in any doc site or help text; this guard would pass vacuously")
+ }
+
+ negatives := 0
+ for _, example := range examples {
+ if !holdsNegativeNumber(example.args) {
+ continue
+ }
+ negatives++
+ t.Run(strings.Join(example.args, "_"), func(t *testing.T) {
+ rewritten := rewriteNegativeNumberArgs(rootCmd, example.args)
+ path, _, positionals, ok := classifyArgs(rootCmd, rewritten)
+ if !ok {
+ // The example wrote its own `--`; cobra handles it and nothing here applies.
+ return
+ }
+ cmd := commandAt(t, path...)
+ flags := freshFlagSet(t, cmd)
+ if err := flags.Parse(rewritten[len(path):]); err != nil {
+ t.Errorf("%s documents %q, which does not parse: %v", example.site, strings.Join(example.args, " "), err)
+ return
+ }
+ if strings.Join(flags.Args(), " ") != strings.Join(positionals, " ") {
+ t.Errorf("%s documents %q, whose positionals reach the command as %v rather than %v", example.site, strings.Join(example.args, " "), flags.Args(), positionals)
+ }
+ })
+ }
+ if negatives == 0 {
+ t.Error("no documented example uses a negative number any more; the working spelling stopped being taught, which is how the last reader learned it was impossible")
+ }
+}
+
+type documentedExample struct {
+ site string
+ args []string
+}
+
+// documentedPinchtabExamples collects every `pinchtab …` line from the agent-facing docs
+// and from every command's own Long text, so a command that gains an example is covered
+// without editing this list.
+func documentedPinchtabExamples(t *testing.T) []documentedExample {
+ t.Helper()
+
+ texts := map[string]string{}
+ for _, site := range documentedExampleSites {
+ raw, err := os.ReadFile(filepath.Join("..", "..", filepath.FromSlash(site)))
+ if err != nil {
+ t.Fatalf("cannot read %s, so this guard would not cover the doc site it names: %v", site, err)
+ }
+ texts[site] = string(raw)
+ }
+ visitAllCommands(rootCmd, func(cmd *cobra.Command) {
+ if cmd.Long != "" {
+ texts[cmd.CommandPath()+" --help"] = cmd.Long
+ }
+ })
+
+ var examples []documentedExample
+ for site, text := range texts {
+ for _, line := range strings.Split(text, "\n") {
+ fields := strings.Fields(strings.TrimPrefix(strings.TrimSpace(line), "$ "))
+ if len(fields) < 2 || fields[0] != "pinchtab" {
+ continue
+ }
+ examples = append(examples, documentedExample{site: site, args: stripComment(fields[1:])})
+ }
+ }
+ return examples
+}
+
+// stripComment drops the trailing `# what this does` every example in these docs carries.
+func stripComment(fields []string) []string {
+ for i, field := range fields {
+ if strings.HasPrefix(field, "#") {
+ return fields[:i]
+ }
+ }
+ return fields
+}
+
+// The rewrite is only worth anything if Execute installs it. Nothing else in this file
+// can see that wiring — every other test calls the function directly — so it is pinned
+// where the call is made.
+func TestExecuteInstallsTheRewrite(t *testing.T) {
+ pkg := srccensus.Load(t, ".", cliSourceFileFloor)
+
+ execute, ok := pkg.Func("Execute")
+ if !ok {
+ t.Fatalf("Execute is not declared anywhere in %s; this guard is pinned to a function that no longer exists — re-point it at whatever runs the CLI rather than deleting it", pkg.Dir())
+ }
+ for _, site := range pkg.Calls(t, "rewriteNegativeNumberArgs") {
+ if pkg.Contains(execute, site) {
+ return
+ }
+ }
+ t.Errorf("%s does not call rewriteNegativeNumberArgs, so every negative positional fails on its own first digit again no matter what the tests above prove", execute.Name)
+}
+
+// Well under the real count, so ordinary growth does not trip it while a scan that lost
+// the package still fails.
+const cliSourceFileFloor = 40
diff --git a/cmd/pinchtab/root.go b/cmd/pinchtab/root.go
index 7cd88c5f..fbb0eec1 100644
--- a/cmd/pinchtab/root.go
+++ b/cmd/pinchtab/root.go
@@ -55,6 +55,7 @@ func maybeRunWizard() {
func Execute() {
safelog.InstallDefault()
installUnknownSubcommandGuard(rootCmd)
+ rootCmd.SetArgs(rewriteNegativeNumberArgs(rootCmd, os.Args[1:]))
if err := rootCmd.Execute(); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(commandExitCode(err))
diff --git a/docs/reference/scroll.md b/docs/reference/scroll.md
index fde0cc69..d8dce5ce 100644
--- a/docs/reference/scroll.md
+++ b/docs/reference/scroll.md
@@ -16,14 +16,15 @@ pinchtab scroll down --snap # scroll and output snapshot
pinchtab scroll 800 --snap-diff # scroll and output snapshot diff
pinchtab scroll 800 --json # Full JSON response
-pinchtab scroll --dy -300 # scroll up 300px
+pinchtab scroll -300 # scroll up 300px
+pinchtab scroll --dy -300 # the same, as a flag
pinchtab scroll --dx -120 # scroll left 120px
```
Notes:
-- a negative pixel count uses `--dy` / `--dx`: a leading minus on a positional argument is
- read as a bundle of shorthand flags and refused before the command runs
+- a negative pixel count works either way — `pinchtab scroll -300` and `pinchtab scroll --dy -300`
+ are the same scroll, and `--tab` may sit in any position in both
- give either the flags or one positional, never both, and only one positional is accepted —
so `--tab` stays a flag and must not be placed after `--`, where it would be read as a
positional
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index 683e8ddf..ea160a47 100644
--- a/skills/pinchtab/references/commands.md
+++ b/skills/pinchtab/references/commands.md
@@ -130,6 +130,8 @@ pinchtab mouse down --button left
pinchtab mouse up e5 --button left
pinchtab mouse up --button left
pinchtab mouse wheel 240 --dx 40
+pinchtab mouse wheel -200
+pinchtab mouse move -5 -5
pinchtab mouse move --x 400 --y 320
pinchtab drag e5 400,320
```
@@ -137,11 +139,12 @@ pinchtab drag e5 400,320
Use these for drag handles, canvas controls, precise hover choreography, or sites that require exact pointer sequencing.
### `pinchtab scroll <pixels|direction|selector>`
-Scroll the page or a specific element. Give either `--dy`/`--dx` or one positional argument, never both. A negative pixel count must use the flag: a leading minus on a positional is read as a bundle of shorthand flags and refused. Only one positional is accepted, so `--tab` must be a flag, never placed after `--`.
+Scroll the page or a specific element. Give either `--dy`/`--dx` or one positional argument, never both. A negative pixel count works in either spelling. Only one positional is accepted, so `--tab` must be a flag, never placed after `--`.
```bash
pinchtab scroll 800 # scroll page down 800px
-pinchtab scroll --dy -300 # scroll page up 300px
+pinchtab scroll -300 # scroll page up 300px
+pinchtab scroll --dy -300 # the same, as a flag
pinchtab scroll --dx -120 # scroll page left 120px
pinchtab scroll down # named direction: down, left, right, up
pinchtab scroll '#footer' # scroll a CSS selector into view