High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: enhance API doc generator to extract and display handler comments with parameters and examples; exclude auto-generated api-reference.md from linting
Mariobfe9240d8853
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 724c5643..f44e318d 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -23,6 +23,7 @@ repos:tests/.*\.md|\.github/.*\.md|skill/.*\.md|+ docs/references/api-reference\.md|README\.md|CONTRIBUTING\.md|CODE_OF_CONDUCT\.md|diff --git a/docs/references/api-reference.md b/docs/references/api-reference.mdindex f55355b4..9c35efa1 100644--- a/docs/references/api-reference.md+++ b/docs/references/api-reference.md@@ -1,6 +1,6 @@# API Reference (Auto-Generated)-Generated: 2026-03-01T00:24:41Z+Generated: 2026-03-01T00:38:44Z---@@ -15,7 +15,7 @@ Generated: 2026-03-01T00:24:41Z| GET | `/dashboard/` | | || GET | `/dashboard/agents` | handleAgents | || GET | `/dashboard/events` | handleSSE | |-| GET | `/download` | HandleDownload | |+| GET | `/download` | HandleDownload | fetches a URL using the browser's session (cookies, stealth) || GET | `/health` | HandleHealth | || GET | `/instances` | handleList | || GET | `/instances/tabs` | handleAllTabs | |@@ -34,17 +34,17 @@ Generated: 2026-03-01T00:24:41Z| GET | `/profiles/{id}/instance` | handleProfileInstance | || GET | `/profiles/{name}/analytics` | handleAnalyticsByPath | || GET | `/profiles/{name}/logs` | handleLogsByPath | |-| GET | `/screencast` | HandleScreencast | |-| GET | `/screencast/tabs` | HandleScreencastAll | |+| GET | `/screencast` | HandleScreencast | upgrades to WebSocket and streams screencast frames for a ta... |+| GET | `/screencast/tabs` | HandleScreencastAll | returns info for building a multi-tab screencast view. || GET | `/screenshot` | HandleScreenshot | |-| GET | `/snapshot` | HandleSnapshot | |+| GET | `/snapshot` | HandleSnapshot | returns the accessibility tree of a tab. || GET | `/stealth/status` | HandleStealthStatus | || GET | `/tabs` | HandleTabs | || GET | `/text` | HandleText | || GET | `/welcome` | | || PATCH | `/profiles/meta` | handleUpdateMeta | || PATCH | `/profiles/{name}` | handleUpdateByPath | |-| POST | `/action` | HandleAction | |+| POST | `/action` | HandleAction | performs a single action on a tab (click, type, fill, etc). || POST | `/actions` | HandleActions | || POST | `/cookies` | HandleSetCookies | || POST | `/ensure-chrome` | HandleEnsureChrome | |@@ -62,7 +62,7 @@ Generated: 2026-03-01T00:24:41Z| POST | `/instances/{id}/tab/lock` | proxyToInstance | || POST | `/instances/{id}/tab/unlock` | proxyToInstance | || POST | `/instances/{id}/upload` | proxyToInstance | |-| POST | `/navigate` | HandleNavigate | |+| POST | `/navigate` | HandleNavigate | navigates a tab to a URL or creates a new tab. || POST | `/profiles/create` | handleCreate | || POST | `/profiles/import` | handleImport | || POST | `/profiles/{id}/start` | handleStartByID | |@@ -73,7 +73,7 @@ Generated: 2026-03-01T00:24:41Z| POST | `/tab` | HandleTab | || POST | `/tab/lock` | HandleTabLock | || POST | `/tab/unlock` | HandleTabUnlock | |-| POST | `/upload` | HandleUpload | |+| POST | `/upload` | HandleUpload | sets files on an <input type="file"> element via CDP. |---@@ -85,20 +85,14 @@ Generated: 2026-03-01T00:24:41Z### GET /-**Handler:** ``-### GET /cookies**Handler:** `HandleGetCookies`### GET /dashboard-**Handler:** ``-### GET /dashboard/-**Handler:** ``-### GET /dashboard/agents**Handler:** `handleAgents`@@ -109,6 +103,11 @@ Generated: 2026-03-01T00:24:41Z### GET /download+HandleDownload fetches a URL using the browser's session (cookies, stealth)+and returns the content. This preserves authentication and fingerprint.+//+GET /download?url=<url>[&tabId=<id>][&output=file&path=/tmp/file][&raw=true]+**Handler:** `HandleDownload`### GET /health@@ -185,10 +184,15 @@ Generated: 2026-03-01T00:24:41Z### GET /screencast+HandleScreencast upgrades to WebSocket and streams screencast frames for a tab.+Query params: tabId (required), quality (1-100, default 40), maxWidth (default 800), fps (1-30, default 5)+**Handler:** `HandleScreencast`### GET /screencast/tabs+HandleScreencastAll returns info for building a multi-tab screencast view.+**Handler:** `HandleScreencastAll`### GET /screenshot@@ -197,6 +201,42 @@ Generated: 2026-03-01T00:24:41Z### GET /snapshot+HandleSnapshot returns the accessibility tree of a tab.+//+@Endpoint GET /snapshot+@Description Returns the page structure with clickable elements, form fields, and text content+//+@Param tabId string query Tab ID (required)+@Param filter string query Filter type: "interactive" for clickable/inputs only, "all" for everything (optional, default: "all")+@Param interactive bool query Alias for filter=interactive (optional)+@Param compact bool query Compact output (shorter ref names) (optional, default: false)+@Param depth int query Max nesting depth (optional, default: -1 for full tree)+@Param text bool query Include text content (optional, default: true)+@Param format string query Output format: "json" or "yaml" (optional, default: "json")+@Param diff bool query Include diff with previous snapshot (optional, default: false)+@Param output string query Write to file instead of response (optional)+//+@Response 200 application/json Returns accessibility tree with refs+@Response 400 application/json Invalid tabId or parameters+@Response 404 application/json Tab not found+//+@Example curl all elements:+ curl "http://localhost:9867/snapshot?tabId=abc123"+//+@Example curl interactive only:+ curl "http://localhost:9867/snapshot?tabId=abc123&filter=interactive"+//+@Example curl compact:+ curl "http://localhost:9867/snapshot?tabId=abc123&filter=interactive&compact=true"+//+@Example cli:+ pinchtab snap -i -c+//+@Example python:+ import requests+ r = requests.get("http://localhost:9867/snapshot", params={"tabId": "abc123", "filter": "interactive"})+ tree = r.json()+**Handler:** `HandleSnapshot`### GET /stealth/status@@ -213,8 +253,6 @@ Generated: 2026-03-01T00:24:41Z### GET /welcome-**Handler:** ``-### PATCH /profiles/meta**Handler:** `handleUpdateMeta`@@ -225,6 +263,54 @@ Generated: 2026-03-01T00:24:41Z### POST /action+HandleAction performs a single action on a tab (click, type, fill, etc).+//+@Endpoint POST /action+@Description Interact with page elements: click, type text, fill inputs, press keys, hover, focus, scroll, select+//+@Param tabId string body Tab ID (required)+@Param kind string body Action type: "click", "type", "fill", "press", "hover", "focus", "scroll", "select" (required)+@Param ref string body Element reference from snapshot (e.g., "e5") (required)+@Param text string body Text to type or fill (for "type"/"fill" actions)+@Param value string body Value for "select" action (e.g., option index)+@Param key string body Key to press (for "press" action, e.g., "Enter", "Tab")+@Param x int body X coordinate for "scroll" action (optional)+@Param y int body Y coordinate for "scroll" action (optional)+//+@Response 200 application/json Returns {success: true}+@Response 400 application/json Invalid action or parameters+@Response 404 application/json Tab or element not found+@Response 500 application/json Chrome error+//+@Example curl click:+ curl -X POST http://localhost:9867/action \+ -H "Content-Type: application/json" \+ -d '{"tabId":"abc123","kind":"click","ref":"e5"}'+//+@Example curl type:+ curl -X POST http://localhost:9867/action \+ -H "Content-Type: application/json" \+ -d '{"tabId":"abc123","kind":"type","ref":"e3","text":"[email protected]"}'+//+@Example curl fill form:+ curl -X POST http://localhost:9867/action \+ -H "Content-Type: application/json" \+ -d '{"tabId":"abc123","kind":"fill","ref":"e3","text":"John Doe"}'+//+@Example curl press key:+ curl -X POST http://localhost:9867/action \+ -H "Content-Type: application/json" \+ -d '{"tabId":"abc123","kind":"press","ref":"e7","key":"Enter"}'+//+@Example cli click:+ pinchtab click e5+//+@Example cli type:+ pinchtab type e3 "[email protected]"+//+@Example cli fill:+ pinchtab fill e3 "John Doe"+**Handler:** `HandleAction`### POST /actions@@ -297,6 +383,34 @@ Generated: 2026-03-01T00:24:41Z### POST /navigate+HandleNavigate navigates a tab to a URL or creates a new tab.+//+@Endpoint POST /navigate+@Description Navigate to a URL in an existing tab or create a new tab and navigate+//+@Param tabId string body Tab ID to navigate in (optional - creates new if omitted)+@Param url string body URL to navigate to (required)+@Param newTab bool body Force create new tab (optional, default: false)+@Param waitTitle float64 body Wait for title change (ms) (optional, default: 0)+@Param timeout float64 body Timeout for navigation (ms) (optional, default: 30000)+//+@Response 200 application/json Returns {tabId, url, title}+@Response 400 application/json Invalid URL or parameters+@Response 500 application/json Chrome error+//+@Example curl navigate new:+ curl -X POST http://localhost:9867/navigate \+ -H "Content-Type: application/json" \+ -d '{"url":"https://example.com"}'+//+@Example curl navigate existing:+ curl -X POST http://localhost:9867/navigate \+ -H "Content-Type: application/json" \+ -d '{"tabId":"abc123","url":"https://google.com"}'+//+@Example cli:+ pinchtab nav https://example.com+**Handler:** `HandleNavigate`### POST /profiles/create@@ -341,6 +455,19 @@ Generated: 2026-03-01T00:24:41Z### POST /upload+HandleUpload sets files on an <input type="file"> element via CDP.+//+POST /upload?tabId=<id>+//+// {+// "selector": "input[type=file]",+// "files": ["data:image/png;base64,...", "base64:..."],+// "paths": ["/tmp/photo.jpg"]+// }+//+Either "files" (base64 data) or "paths" (local file paths) must be provided.+Both can be combined. Files are written to a temp dir and passed to CDP.+**Handler:** `HandleUpload`---diff --git a/scripts/gen-api-docs/main.go b/scripts/gen-api-docs/main.goindex 09979246..a9158238 100644--- a/scripts/gen-api-docs/main.go+++ b/scripts/gen-api-docs/main.go@@ -31,27 +31,40 @@ type Param struct {}func main() {- // Parse all relevant files for routes+ // Parse all relevant files for routes and handler commentsvar endpoints []Endpoint+ handlerComments := make(map[string]string)++ // Main handlers - first get all handler comments from individual files+ handlerComments = mergeComments(handlerComments, extractAllHandlerComments("internal/handlers/"))- // Main handlersendpoints = append(endpoints, extractEndpoints("internal/handlers/handlers.go")...)// Dashboard handlers+ handlerComments = mergeComments(handlerComments, extractAllHandlerComments("internal/dashboard/"))endpoints = append(endpoints, extractEndpoints("internal/dashboard/dashboard.go")...)// Profiles serviceprofiles, err := findProfilesFile()if err == nil {+ handlerComments = mergeComments(handlerComments, extractAllHandlerComments("internal/profiles/"))endpoints = append(endpoints, extractEndpoints(profiles)...)}// Orchestrator serviceorchestrator, err := findOrchestratorFile()if err == nil {+ handlerComments = mergeComments(handlerComments, extractAllHandlerComments("internal/orchestrator/"))endpoints = append(endpoints, extractEndpoints(orchestrator)...)}+ // Merge handler comments into endpoints+ for i := range endpoints {+ if handlerComments[endpoints[i].Handler] != "" {+ endpoints[i].Doc = handlerComments[endpoints[i].Handler]+ }+ }+// Remove duplicatesendpointMap := make(map[string]Endpoint)for _, ep := range endpoints {@@ -90,9 +103,18 @@ func main() {for _, ep := range endpoints {notes := ""if ep.Doc != "" {- notes = strings.TrimSpace(ep.Doc)- if len(notes) > 50 {- notes = notes[:50] + "..."+ // Extract first line of doc comment+ lines := strings.Split(strings.TrimSpace(ep.Doc), "\n")+ notes = strings.TrimSpace(lines[0])+ // Remove the function name prefix if it exists+ if strings.HasPrefix(notes, "Handle") {+ parts := strings.SplitN(notes, " ", 2)+ if len(parts) > 1 {+ notes = parts[1]+ }+ }+ if len(notes) > 60 {+ notes = notes[:60] + "..."}}fmt.Printf("| %s | `%s` | %s | %s |\n", ep.Method, ep.Path, ep.Handler, notes)@@ -109,12 +131,18 @@ func main() {fmt.Println("")if ep.Doc != "" {- fmt.Printf("%s\n", ep.Doc)+ // Clean up the doc text+ docLines := strings.Split(strings.TrimSpace(ep.Doc), "\n")+ for _, line := range docLines {+ fmt.Println(line)+ }fmt.Println("")}- fmt.Printf("**Handler:** `%s`\n", ep.Handler)- fmt.Println("")+ if ep.Handler != "" {+ fmt.Printf("**Handler:** `%s`\n", ep.Handler)+ fmt.Println("")+ }}fmt.Println("---")@@ -127,6 +155,41 @@ func main() {fmt.Println("")}+func mergeComments(maps ...map[string]string) map[string]string {+ result := make(map[string]string)+ for _, m := range maps {+ for k, v := range m {+ if _, exists := result[k]; !exists {+ result[k] = v+ }+ }+ }+ return result+}++func extractAllHandlerComments(dirPath string) map[string]string {+ comments := make(map[string]string)++ // Read directory+ entries, err := os.ReadDir(dirPath)+ if err != nil {+ return comments+ }++ // Parse all .go files in the directory+ for _, entry := range entries {+ if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".go") && !strings.HasSuffix(entry.Name(), "_test.go") {+ filePath := dirPath + entry.Name()+ fileComments := extractHandlerComments(filePath)+ for k, v := range fileComments {+ comments[k] = v+ }+ }+ }++ return comments+}+func findProfilesFile() (string, error) {// Look for profiles service implementationmatches := []string{@@ -184,6 +247,41 @@ func extractEndpoints(filePath string) []Endpoint {return endpoints}+func extractHandlerComments(filePath string) map[string]string {+ comments := make(map[string]string)++ fset := token.NewFileSet()+ file, err := parser.ParseFile(fset, filePath, nil, parser.ParseComments)+ if err != nil {+ return comments+ }++ // Iterate through all declarations+ for _, decl := range file.Decls {+ funcDecl, ok := decl.(*ast.FuncDecl)+ if !ok {+ continue+ }++ // Look for handler functions (they have "Handle" or "handle" in the name)+ if !strings.Contains(funcDecl.Name.Name, "handle") && !strings.Contains(funcDecl.Name.Name, "Handle") {+ continue+ }++ // Extract doc comment+ if funcDecl.Doc != nil && len(funcDecl.Doc.List) > 0 {+ var docText strings.Builder+ for _, comment := range funcDecl.Doc.List {+ docText.WriteString(strings.TrimPrefix(comment.Text, "// "))+ docText.WriteString("\n")+ }+ comments[funcDecl.Name.Name] = docText.String()+ }+ }++ return comments+}+func extractHandleFuncCalls(body *ast.BlockStmt) []Endpoint {var endpoints []Endpoint