Skip to content

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

fix: two shipped docs state guarantees the code does not provide — scroll teaches two directions that never existed, and upload promises a basename reduction that skips Windows-style names (PIN-211)

Luigi Agostie4033e903046
diff --git a/cmd/pinchtab/cmd_cli_scroll_test.go b/cmd/pinchtab/cmd_cli_scroll_test.go
index 39b25b75..b45fd043 100644
--- a/cmd/pinchtab/cmd_cli_scroll_test.go
+++ b/cmd/pinchtab/cmd_cli_scroll_test.go
@@ -3,8 +3,11 @@ package main
import (
"os"
"path/filepath"
+ "sort"
"strings"
"testing"
+
+ browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
)
func resetScrollFlags(t *testing.T) {
@@ -115,6 +118,64 @@ func TestScrollRegistersThePixelFlags(t *testing.T) {
}
}
+// directionsEnumeratedAfter extracts the keyword list a line presents after marker, so the
+// prose can keep its own separators and order while the SET is what gets compared.
+func directionsEnumeratedAfter(text, marker string) ([]string, bool) {
+ for _, line := range strings.Split(text, "\n") {
+ idx := strings.Index(line, marker)
+ if idx < 0 {
+ continue
+ }
+ list := line[idx+len(marker):]
+ if cut := strings.Index(list, "("); cut >= 0 {
+ list = list[:cut]
+ }
+ var found []string
+ for _, token := range strings.FieldsFunc(list, func(r rune) bool {
+ return r < 'a' || r > 'z'
+ }) {
+ if len(token) > 1 {
+ found = append(found, token)
+ }
+ }
+ sort.Strings(found)
+ return found, true
+ }
+ return nil, false
+}
+
+// Every prose enumeration of the direction keywords is asserted against the code's own
+// vocabulary, in BOTH directions: the agent-facing reference had invented "top" and
+// "bottom", which fall through to CSS selectors and match nothing, while omitting "left"
+// and "right", which work. A guard pinning one known-bad example would not have caught
+// either half — only comparing the whole set does.
+func TestDocumentedScrollDirectionsAreExactlyTheSupportedOnes(t *testing.T) {
+ want := browseractions.ScrollDirectionKeywords()
+
+ commands, err := os.ReadFile(filepath.Join("..", "..", "skills", "pinchtab", "references", "commands.md"))
+ if err != nil {
+ t.Fatalf("cannot read the agent-facing reference, so this guard would not cover it: %v", err)
+ }
+
+ for _, site := range []struct {
+ name string
+ text string
+ marker string
+ }{
+ {name: "scroll --help", text: scrollCmd.Long, marker: "Direction keyword:"},
+ {name: "skills/pinchtab/references/commands.md", text: string(commands), marker: "named direction:"},
+ } {
+ got, ok := directionsEnumeratedAfter(site.text, site.marker)
+ if !ok {
+ t.Errorf("%s no longer enumerates the directions after %q, so drift there is now unguarded", site.name, site.marker)
+ continue
+ }
+ if strings.Join(got, ",") != strings.Join(want, ",") {
+ t.Errorf("%s documents directions %v, want exactly %v — a keyword it invents falls through to a CSS selector and matches nothing, and one it omits is invisible to the reader", site.name, got, want)
+ }
+ }
+}
+
// 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.
diff --git a/internal/cli/actions/actions_element.go b/internal/cli/actions/actions_element.go
index f3f360df..7ee4563a 100644
--- a/internal/cli/actions/actions_element.go
+++ b/internal/cli/actions/actions_element.go
@@ -3,6 +3,7 @@ package actions
import (
"encoding/json"
"net/http"
+ "sort"
"strconv"
"strings"
@@ -209,21 +210,43 @@ func setPointBody(body map[string]any, x, y float64) {
body["y"] = y
}
+type scrollDirection struct {
+ axis string
+ delta int
+}
+
+// scrollDirections is the whole vocabulary `scroll <direction>` accepts, and the single
+// place the help and the docs are checked against by ScrollDirectionKeywords.
+var scrollDirections = map[string]scrollDirection{
+ "down": {"scrollY", 800},
+ "up": {"scrollY", -800},
+ "right": {"scrollX", 800},
+ "left": {"scrollX", -800},
+}
+
+// ScrollDirectionKeywords returns the accepted direction keywords, sorted. Any prose that
+// enumerates them is asserted against this rather than against a hand-kept list.
+func ScrollDirectionKeywords() []string {
+ keywords := make([]string, 0, len(scrollDirections))
+ for keyword := range scrollDirections {
+ keywords = append(keywords, keyword)
+ }
+ sort.Strings(keywords)
+ return keywords
+}
+
// applyScrollTarget fills a scroll body from --dy/--dx, or from the single positional by
// precedence: integer pixels, then direction keyword, then unified selector. Pixels and
-// directions are short, low-cardinality inputs that would otherwise parse as CSS tag
-// selectors ("up", "down"), so they are intercepted before setSelectorBody.
+// directions would otherwise parse as CSS tag selectors ("up", "down"), so they are
+// intercepted before setSelectorBody.
//
-// The flags are how a NEGATIVE count is reachable at all: cobra reads a leading minus on a
-// positional as shorthand flags, so `scroll -300` — an example in this command's own help —
-// never parsed, and `scroll -- -300` was the only workaround. scrollArgs in cmd/pinchtab
-// rejects the combinations this cannot express, so an empty args slice here means the flags
-// carry the request.
+// A negative count is only reachable through the flags: cobra reads a leading minus on a
+// positional as bundled shorthand flags.
func applyScrollTarget(body map[string]any, args []string, cmd *cobra.Command) {
- if deltaY, ok := readWheelDelta(cmd, "dy"); ok {
+ if deltaY, ok := readIntFlag(cmd, "dy"); ok {
body["scrollY"] = deltaY
}
- if deltaX, ok := readWheelDelta(cmd, "dx"); ok {
+ if deltaX, ok := readIntFlag(cmd, "dx"); ok {
body["scrollX"] = deltaX
}
if len(args) == 0 {
@@ -233,23 +256,14 @@ func applyScrollTarget(body map[string]any, args []string, cmd *cobra.Command) {
body["scrollY"] = px
return
}
- switch strings.ToLower(args[0]) {
- case "down":
- body["scrollY"] = 800
- case "up":
- body["scrollY"] = -800
- case "right":
- body["scrollX"] = 800
- case "left":
- body["scrollX"] = -800
- default:
- // Refs ("e5"), CSS ("#footer"), XPath ("//..."), text: and semantic selectors all
- // work here — the same contract as click, fill and hover.
- setSelectorBody(body, args[0])
+ if direction, ok := scrollDirections[strings.ToLower(args[0])]; ok {
+ body[direction.axis] = direction.delta
+ return
}
+ setSelectorBody(body, args[0])
}
-func readWheelDelta(cmd *cobra.Command, primary string) (int, bool) {
+func readIntFlag(cmd *cobra.Command, primary string) (int, bool) {
if cmd.Flags().Changed(primary) {
if value, err := cmd.Flags().GetInt(primary); err == nil {
return value, true
@@ -333,10 +347,10 @@ func MouseAction(client *http.Client, base, token, kind string, args []string, c
setSelectorBody(body, args[0])
}
}
- if deltaX, ok := readWheelDelta(cmd, "dx"); ok {
+ if deltaX, ok := readIntFlag(cmd, "dx"); ok {
body["deltaX"] = deltaX
}
- if deltaY, ok := readWheelDelta(cmd, "dy"); ok {
+ if deltaY, ok := readIntFlag(cmd, "dy"); ok {
if _, fromArg := body["deltaY"]; fromArg {
cli.Fatal("Usage: pinchtab mouse wheel <dy> [--dx <n>] or pinchtab mouse wheel [selector]")
}
diff --git a/internal/handlers/upload.go b/internal/handlers/upload.go
index 020f4e66..fb784a23 100644
--- a/internal/handlers/upload.go
+++ b/internal/handlers/upload.go
@@ -267,16 +267,15 @@ func uploadFileName(names []string, i int) string {
func stagedUploadName(name string, i int, ext string) string {
generated := fmt.Sprintf("upload-%d%s", i, ext)
- // filepath.Base already guarantees the result carries no separator, so the
- // only rejections left are the values Base returns that are not usable
- // filenames: the empty input, the two relative markers, the root itself, and
- // a NUL, which Base passes through and the filesystem then refuses.
- base := filepath.Base(filepath.FromSlash(strings.TrimSpace(name)))
+ // Reduce on BOTH separators whatever the host is. filepath.Base cannot: on a
+ // Linux server its separator is "/", so a Windows caller's "C:\dir\data.csv"
+ // contains no separator at all and survives whole. The cost is that a literal
+ // backslash in a genuine POSIX filename is treated as a separator too, which is
+ // the same trade a browser makes — it sends the final component and nothing else.
+ trimmed := strings.TrimSpace(name)
+ base := trimmed[strings.LastIndexAny(trimmed, `/\`)+1:]
switch {
- case strings.TrimSpace(name) == "",
- base == ".", base == "..",
- base == string(filepath.Separator),
- strings.ContainsRune(base, 0):
+ case base == "", base == ".", base == "..", strings.ContainsRune(base, 0):
return generated
}
return base
diff --git a/internal/handlers/upload_test.go b/internal/handlers/upload_test.go
index 25626e62..c9e52984 100644
--- a/internal/handlers/upload_test.go
+++ b/internal/handlers/upload_test.go
@@ -688,6 +688,13 @@ func TestStagedUploadNameIsAlwaysOneSafeElement(t *testing.T) {
{" spaced.csv ", "spaced.csv"},
{"../escape.txt", "escape.txt"},
{"a/b/c.json", "c.json"},
+ // A Windows caller reaches a POSIX server with no '/' in its name at all, so
+ // reduction cannot be delegated to the host's separator.
+ {`C:\Users\me\data.csv`, "data.csv"},
+ {`..\..\etc\passwd`, "passwd"},
+ {`sub\dir\nested.txt`, "nested.txt"},
+ {`trailing\`, "upload-3.bin"},
+ {"trailing/", "upload-3.bin"},
{"", "upload-3.bin"},
{" ", "upload-3.bin"},
{".", "upload-3.bin"},
@@ -699,7 +706,7 @@ func TestStagedUploadNameIsAlwaysOneSafeElement(t *testing.T) {
if got != tc.want {
t.Errorf("stagedUploadName(%q) = %q, want %q", tc.name, got, tc.want)
}
- if got == "" || got == "." || got == ".." || strings.ContainsRune(got, filepath.Separator) || strings.ContainsRune(got, '/') {
+ if got == "" || got == "." || got == ".." || strings.ContainsAny(got, `/\`) || strings.ContainsRune(got, filepath.Separator) {
t.Errorf("stagedUploadName(%q) = %q, which is not a single safe path element", tc.name, got)
}
}
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index 58b9de40..2966abbd 100644
--- a/skills/pinchtab/references/commands.md
+++ b/skills/pinchtab/references/commands.md
@@ -143,7 +143,7 @@ Scroll the page or a specific element. Give either `--dy`/`--dx` or one position
pinchtab scroll 800 # scroll page down 800px
pinchtab scroll --dy -300 # scroll page up 300px
pinchtab scroll --dx -120 # scroll page left 120px
-pinchtab scroll down # named direction (also up, top, bottom)
+pinchtab scroll down # named direction: down, left, right, up
pinchtab scroll '#footer' # scroll a CSS selector into view
pinchtab scroll e20 # scroll an element ref into view
pinchtab scroll 800 --snap-diff