Skip to content

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.yaml
index 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.md
index 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.go
index 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 comments
var endpoints []Endpoint
+ handlerComments := make(map[string]string)
+
+ // Main handlers - first get all handler comments from individual files
+ handlerComments = mergeComments(handlerComments, extractAllHandlerComments("internal/handlers/"))
- // Main handlers
endpoints = append(endpoints, extractEndpoints("internal/handlers/handlers.go")...)
// Dashboard handlers
+ handlerComments = mergeComments(handlerComments, extractAllHandlerComments("internal/dashboard/"))
endpoints = append(endpoints, extractEndpoints("internal/dashboard/dashboard.go")...)
// Profiles service
profiles, err := findProfilesFile()
if err == nil {
+ handlerComments = mergeComments(handlerComments, extractAllHandlerComments("internal/profiles/"))
endpoints = append(endpoints, extractEndpoints(profiles)...)
}
// Orchestrator service
orchestrator, 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 duplicates
endpointMap := 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 implementation
matches := []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