Skip to content

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

fix: smoother onboarding from persona testing (session autostart, help, allowlist, hints)

Bosche22a3d5f7c08
diff --git a/cmd/pinchtab/cmd_cli_runtime.go b/cmd/pinchtab/cmd_cli_runtime.go
index 4e89cb24..9d7fe8d3 100644
--- a/cmd/pinchtab/cmd_cli_runtime.go
+++ b/cmd/pinchtab/cmd_cli_runtime.go
@@ -33,6 +33,21 @@ func runCLIEnsuringServer(command string, fn func(cliRuntime)) {
runCLIWithServerCheck(loadConfig(), command, fn)
}
+// runCLIEnsuringServerNoBrowser auto-starts the local control plane if needed but
+// skips the browser preflight, for commands that need the server but not a browser
+// instance (e.g. session create). Without this, the documented "create a session
+// first" step fails cold with a raw "connection refused" on a fresh machine, since
+// only browser commands auto-start the server.
+func runCLIEnsuringServerNoBrowser(command string, fn func(cliRuntime)) {
+ cfg := loadConfig()
+ rt := newCLIRuntime(cfg)
+ if err := ensureServerForCLI(cfg, rt.base, rt.token, command); err != nil {
+ fmt.Fprintf(os.Stderr, "pinchtab: %v\n", err)
+ os.Exit(1)
+ }
+ fn(rt)
+}
+
func runCLIWithServerCheck(cfg *config.RuntimeConfig, command string, fn func(cliRuntime)) {
rt := newCLIRuntime(cfg)
// Only preflight when this command would auto-start the local server. For a
diff --git a/cmd/pinchtab/cmd_session.go b/cmd/pinchtab/cmd_session.go
index 0b360829..59043739 100644
--- a/cmd/pinchtab/cmd_session.go
+++ b/cmd/pinchtab/cmd_session.go
@@ -24,7 +24,7 @@ func init() {
sessionToken := os.Getenv("PINCHTAB_SESSION")
if sessionToken == "" {
fmt.Fprintln(os.Stderr, "Error: no session set")
- output.Hint("create one: export PINCHTAB_SESSION=$(pinchtab session create --agent-id <id> --print-token)")
+ output.Hint("create one: export PINCHTAB_SESSION=$(pinchtab session create --agent-id <id>)")
os.Exit(1)
}
runCLI(func(rt cliRuntime) {
@@ -58,7 +58,10 @@ func init() {
if label != "" {
body["label"] = label
}
- runCLI(func(rt cliRuntime) {
+ // Auto-start the control plane first: the documented "create a session
+ // before any browser command" order otherwise fails cold on a fresh
+ // machine (only browser commands start the server).
+ runCLIEnsuringServerNoBrowser("session create", func(rt cliRuntime) {
if jsonOutput {
apiclient.DoPost(rt.client, rt.base, rt.token, "/sessions", body)
return
diff --git a/docs/reference/sessions.md b/docs/reference/sessions.md
index 799137df..8050e862 100644
--- a/docs/reference/sessions.md
+++ b/docs/reference/sessions.md
@@ -67,9 +67,9 @@ That default is a convenience for trusted automation, not a sandbox. If you need
## CLI Usage
```bash
-# Create a new session (prints token to stdout with --print-token)
-pinchtab session create --agent-id agent-1 --print-token
-export PINCHTAB_SESSION=$(pinchtab session create --agent-id agent-1 --print-token)
+# Create a new session (prints the session token to stdout; use --json for a full JSON object)
+pinchtab session create --agent-id agent-1
+export PINCHTAB_SESSION=$(pinchtab session create --agent-id agent-1)
# CLI automatically uses session auth when PINCHTAB_SESSION is set
pinchtab snap
diff --git a/internal/cli/actions/actions_navigate.go b/internal/cli/actions/actions_navigate.go
index 692dd396..6d49e808 100644
--- a/internal/cli/actions/actions_navigate.go
+++ b/internal/cli/actions/actions_navigate.go
@@ -123,7 +123,7 @@ func Navigate(client *http.Client, base, token string, url string, cmd *cobra.Co
}
if !isIdentifiedCaller() {
- output.Hint("no session set — this tab is shared. Create one with: export PINCHTAB_SESSION=$(pinchtab session create --agent-id <id> --print-token)")
+ output.Hint("no session set — this tab is shared. Create one with: export PINCHTAB_SESSION=$(pinchtab session create --agent-id <id>)")
}
snap, _ := cmd.Flags().GetBool("snap")
diff --git a/internal/cli/report/config_report.go b/internal/cli/report/config_report.go
index 6ab9abd3..4fe3f666 100644
--- a/internal/cli/report/config_report.go
+++ b/internal/cli/report/config_report.go
@@ -27,6 +27,12 @@ func HandleConfigShow(cfg *config.RuntimeConfig) {
fmt.Printf(" Allowed Domains: %v\n", cfg.AllowedDomains)
fmt.Println()
fmt.Println(styleStdout(headingStyle, "Browser / Instance Defaults"))
+ fmt.Printf(" Provider: %s\n", cfg.DefaultBrowser)
+ binary := cfg.BrowserBinary
+ if binary == "" {
+ binary = "(auto-discovered)"
+ }
+ fmt.Printf(" Binary: %s\n", binary)
fmt.Printf(" Headless: %v\n", cfg.Headless)
fmt.Printf(" No Restore: %v\n", cfg.NoRestore)
fmt.Printf(" Profile Dir: %s\n", cfg.ProfileDir)
diff --git a/internal/cli/styles.go b/internal/cli/styles.go
index 539a0d7b..a627a548 100644
--- a/internal/cli/styles.go
+++ b/internal/cli/styles.go
@@ -64,7 +64,8 @@ func SetupUsage(root *cobra.Command) {
{{range .Groups}}{{$group := .ID}}
{{.Title}}:
{{range $.Commands}}{{if eq .GroupID $group}}{{if not .Hidden}} %s {{.Short}}
-{{end}}{{end}}{{end}}{{end}}
+{{end}}{{end}}{{end}}{{end}}{{range $.Commands}}{{if and (eq .GroupID "") .IsAvailableCommand}} %s {{.Short}}
+{{end}}{{end}}
{{if .HasAvailableLocalFlags}}
%s:
{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}
@@ -77,6 +78,7 @@ func SetupUsage(root *cobra.Command) {
headerStyle("Usage"),
headerStyle("Commands"),
cmdStyle("{{rpad .Name .NamePadding}}"),
+ cmdStyle("{{rpad .Name .NamePadding}}"),
headerStyle("Flags"),
headerStyle("Examples")))
}
diff --git a/internal/config/editor_parse.go b/internal/config/editor_parse.go
index 290e3026..0efba068 100644
--- a/internal/config/editor_parse.go
+++ b/internal/config/editor_parse.go
@@ -30,3 +30,19 @@ func parseCSVList(s string) []string {
}
return out
}
+
+// validateAllowlistEntries rejects obviously-invalid domain entries. It exists to
+// catch a user pasting a remediation hint that contains the "…" placeholder
+// literally (the allowlist would otherwise silently accept "…" as a host) and
+// other malformed entries, rather than failing later at navigation time.
+func validateAllowlistEntries(domains []string) error {
+ for _, d := range domains {
+ if strings.ContainsRune(d, '…') || strings.Contains(d, "...") {
+ return fmt.Errorf("invalid domain %q: \"…\" is a placeholder, not a real host — replace it with an actual domain (e.g. example.com)", d)
+ }
+ if strings.ContainsAny(d, " \t/") {
+ return fmt.Errorf("invalid domain %q: a domain must not contain spaces or '/' (use a bare host like example.com or *.example.com)", d)
+ }
+ }
+ return nil
+}
diff --git a/internal/config/editor_set.go b/internal/config/editor_set.go
index 93ef0e6d..6ab6db51 100644
--- a/internal/config/editor_set.go
+++ b/internal/config/editor_set.go
@@ -441,7 +441,11 @@ func setSecurityField(s *SecurityConfig, field, value string) error {
return setIDPIField(s, strings.TrimPrefix(field, "idpi."), value)
}
if field == "allowedDomains" {
- s.AllowedDomains = parseCSVList(value)
+ domains := parseCSVList(value)
+ if err := validateAllowlistEntries(domains); err != nil {
+ return err
+ }
+ s.AllowedDomains = domains
return nil
}
if field == "downloadAllowedDomains" {
diff --git a/internal/config/editor_set_test.go b/internal/config/editor_set_test.go
index 6cf43ed9..08743e97 100644
--- a/internal/config/editor_set_test.go
+++ b/internal/config/editor_set_test.go
@@ -2,6 +2,30 @@ package config
import "testing"
+func TestSetConfigValue_AllowedDomainsValidation(t *testing.T) {
+ tests := []struct {
+ value string
+ wantErr bool
+ }{
+ {"example.com", false},
+ {"localhost,127.0.0.1,example.com", false},
+ {"*.example.com", false},
+ {"…,example.com", true}, // literal placeholder pasted from a hint
+ {"127.0.0.1,…", true}, // placeholder anywhere in the list
+ {"has space.com", true}, // malformed
+ {"http://example.com/x", true}, // URL, not a host
+ }
+ for _, tt := range tests {
+ t.Run(tt.value, func(t *testing.T) {
+ fc := &FileConfig{}
+ err := SetConfigValue(fc, "security.allowedDomains", tt.value)
+ if (err != nil) != tt.wantErr {
+ t.Errorf("SetConfigValue(allowedDomains=%q) error = %v, wantErr %v", tt.value, err, tt.wantErr)
+ }
+ })
+ }
+}
+
func TestSetConfigValue_ServerFields(t *testing.T) {
tests := []struct {
path string
diff --git a/internal/handlers/navigation.go b/internal/handlers/navigation.go
index b40440bd..268caa74 100644
--- a/internal/handlers/navigation.go
+++ b/internal/handlers/navigation.go
@@ -196,8 +196,18 @@ func idpiAllowlistHint(url string) string {
if !ok || strings.TrimSpace(host) == "" {
return ""
}
- return fmt.Sprintf(". To allow it, add the host: `pinchtab config set security.allowedDomains \"…,%s\"` "+
- "then `pinchtab server restart` — this widens what automation may reach (see docs/guides/security.md)", host)
+ return fmt.Sprintf(". To allow it, run: pinchtab config set security.allowedDomains "+
+ "\"$(pinchtab config get security.allowedDomains),%s\" then: pinchtab server restart "+
+ "(this widens what automation may reach — see docs/guides/security.md)", host)
+}
+
+// idpiScannerHint appends remediation to an IDPI content-scanner block, which
+// otherwise states only the cause. Unlike the domain allowlist, a scanner block
+// can be a false positive on legitimate pages, so the fix is to relax strict mode
+// (still scans and wraps, just warns instead of hard-blocking).
+func idpiScannerHint() string {
+ return ". To read pages like this, set strict mode off: `pinchtab config set security.idpi.strictMode false` " +
+ "then `pinchtab server restart` — content is still scanned and wrapped, just warned instead of blocked (see docs/guides/security.md)"
}
// validateNavigateTargets runs URL validation, the IDPI domain guard, and SSRF
diff --git a/internal/handlers/navigation_idpi_hint_test.go b/internal/handlers/navigation_idpi_hint_test.go
index 0adfd860..69c0aef0 100644
--- a/internal/handlers/navigation_idpi_hint_test.go
+++ b/internal/handlers/navigation_idpi_hint_test.go
@@ -16,9 +16,27 @@ func TestIDPIAllowlistHint(t *testing.T) {
if !strings.Contains(hint, "server restart") {
t.Errorf("hint should remind the user to restart; got %q", hint)
}
+ // Must be copy-paste-safe: no "…" placeholder (which users paste literally),
+ // and it should preserve existing domains via a `config get` append.
+ if strings.ContainsRune(hint, '…') {
+ t.Errorf("hint must not contain the … placeholder; got %q", hint)
+ }
+ if !strings.Contains(hint, "config get security.allowedDomains") {
+ t.Errorf("hint should append to existing domains via config get; got %q", hint)
+ }
// Hostless targets (e.g. about:blank) can't be allowlisted, so no hint.
if got := idpiAllowlistHint("about:blank"); got != "" {
t.Errorf("expected empty hint for hostless url; got %q", got)
}
}
+
+func TestIDPIScannerHint(t *testing.T) {
+ hint := idpiScannerHint()
+ if !strings.Contains(hint, "strictMode") {
+ t.Errorf("scanner hint should point at strictMode; got %q", hint)
+ }
+ if !strings.Contains(hint, "server restart") {
+ t.Errorf("scanner hint should remind the user to restart; got %q", hint)
+ }
+}
diff --git a/internal/handlers/snapshot_idpi.go b/internal/handlers/snapshot_idpi.go
index 166b6b73..a702521a 100644
--- a/internal/handlers/snapshot_idpi.go
+++ b/internal/handlers/snapshot_idpi.go
@@ -44,7 +44,7 @@ func (h *Handlers) scanSnapshotIDPI(w http.ResponseWriter, flat []bridge.A11yNod
idpi := h.IDPIGuard.ScanContent(sb.String())
if idpi.Blocked {
httpx.Error(w, http.StatusForbidden,
- fmt.Errorf("snapshot blocked by IDPI scanner: %s", idpi.Reason))
+ fmt.Errorf("snapshot blocked by IDPI scanner: %s%s", idpi.Reason, idpiScannerHint()))
out.Blocked = true
return out
}
diff --git a/internal/handlers/text.go b/internal/handlers/text.go
index 89337c4e..49e57c78 100644
--- a/internal/handlers/text.go
+++ b/internal/handlers/text.go
@@ -116,7 +116,7 @@ func (h *Handlers) writeTextResponse(w http.ResponseWriter, r *http.Request, tCt
// IDPI: scan extracted text for injection patterns and optionally wrap.
result := h.ContentGuard.Scan(text, url)
if result.Blocked {
- httpx.Error(w, http.StatusForbidden, fmt.Errorf("content blocked by IDPI scanner: %s", result.BlockReason))
+ httpx.Error(w, http.StatusForbidden, fmt.Errorf("content blocked by IDPI scanner: %s%s", result.BlockReason, idpiScannerHint()))
return
}
result.SetHeaders(w)