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.goindex 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 adiff --git a/cmd/pinchtab/cmd_session.go b/cmd/pinchtab/cmd_session.goindex 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)returndiff --git a/docs/reference/sessions.md b/docs/reference/sessions.mdindex 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 setpinchtab snapdiff --git a/internal/cli/actions/actions_navigate.go b/internal/cli/actions/actions_navigate.goindex 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.goindex 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.goindex 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.goindex 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.goindex 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 = domainsreturn nil}if field == "downloadAllowedDomains" {diff --git a/internal/config/editor_set_test.go b/internal/config/editor_set_test.goindex 6cf43ed9..08743e97 100644--- a/internal/config/editor_set_test.go+++ b/internal/config/editor_set_test.go@@ -2,6 +2,30 @@ package configimport "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 stringdiff --git a/internal/handlers/navigation.go b/internal/handlers/navigation.goindex 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 SSRFdiff --git a/internal/handlers/navigation_idpi_hint_test.go b/internal/handlers/navigation_idpi_hint_test.goindex 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.goindex 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.A11yNodidpi := 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 = truereturn out}diff --git a/internal/handlers/text.go b/internal/handlers/text.goindex 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)