High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: enhance JSON structure with description, params, examples, implementation status
Mario1c150ad14543
diff --git a/docs/references/api-reference.json b/docs/references/api-reference.jsonindex 50c47b76..98746355 100644--- a/docs/references/api-reference.json+++ b/docs/references/api-reference.json@@ -6,332 +6,398 @@{"method": "DELETE","path": "/profiles/{name}",- "handler": "handleDeleteByPath"+ "handler": "handleDeleteByPath",+ "examples": {}},{"method": "GET","path": "/",- "handler": ""+ "handler": "",+ "examples": {}},{"method": "GET","path": "/cookies",- "handler": "HandleGetCookies"+ "handler": "HandleGetCookies",+ "examples": {}},{"method": "GET","path": "/dashboard",- "handler": ""+ "handler": "",+ "examples": {}},{"method": "GET","path": "/dashboard/",- "handler": ""+ "handler": "",+ "examples": {}},{"method": "GET","path": "/dashboard/agents",- "handler": "handleAgents"+ "handler": "handleAgents",+ "examples": {}},{"method": "GET","path": "/dashboard/events",- "handler": "handleSSE"+ "handler": "handleSSE",+ "examples": {}},{"method": "GET","path": "/download",- "handler": "HandleDownload"+ "handler": "HandleDownload",+ "examples": {}},{"method": "GET","path": "/health",- "handler": "HandleHealth"+ "handler": "HandleHealth",+ "examples": {}},{"method": "GET","path": "/instances",- "handler": "handleList"+ "handler": "handleList",+ "examples": {}},{"method": "GET","path": "/instances/tabs",- "handler": "handleAllTabs"+ "handler": "handleAllTabs",+ "examples": {}},{"method": "GET","path": "/instances/{id}/cookies",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "GET","path": "/instances/{id}/download",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "GET","path": "/instances/{id}/logs",- "handler": "handleLogsByID"+ "handler": "handleLogsByID",+ "examples": {}},{"method": "GET","path": "/instances/{id}/pdf",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "GET","path": "/instances/{id}/proxy/screencast",- "handler": "handleProxyScreencast"+ "handler": "handleProxyScreencast",+ "examples": {}},{"method": "GET","path": "/instances/{id}/screencast",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "GET","path": "/instances/{id}/screenshot",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "GET","path": "/instances/{id}/snapshot",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "GET","path": "/instances/{id}/tabs",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "GET","path": "/instances/{id}/text",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "GET","path": "/pdf",- "handler": "HandlePDF"+ "handler": "HandlePDF",+ "examples": {}},{"method": "GET","path": "/profiles",- "handler": "handleList"+ "handler": "handleList",+ "examples": {}},{"method": "GET","path": "/profiles/{id}/instance",- "handler": "handleProfileInstance"+ "handler": "handleProfileInstance",+ "examples": {}},{"method": "GET","path": "/profiles/{name}/analytics",- "handler": "handleAnalyticsByPath"+ "handler": "handleAnalyticsByPath",+ "examples": {}},{"method": "GET","path": "/profiles/{name}/logs",- "handler": "handleLogsByPath"+ "handler": "handleLogsByPath",+ "examples": {}},{"method": "GET","path": "/screencast",- "handler": "HandleScreencast"+ "handler": "HandleScreencast",+ "examples": {}},{"method": "GET","path": "/screencast/tabs",- "handler": "HandleScreencastAll"+ "handler": "HandleScreencastAll",+ "examples": {}},{"method": "GET","path": "/screenshot",- "handler": "HandleScreenshot"+ "handler": "HandleScreenshot",+ "examples": {}},{"method": "GET","path": "/snapshot",- "handler": "HandleSnapshot"+ "handler": "HandleSnapshot",+ "examples": {}},{"method": "GET","path": "/stealth/status",- "handler": "HandleStealthStatus"+ "handler": "HandleStealthStatus",+ "examples": {}},{"method": "GET","path": "/tabs",- "handler": "HandleTabs"+ "handler": "HandleTabs",+ "examples": {}},{"method": "GET","path": "/text",- "handler": "HandleText"+ "handler": "HandleText",+ "examples": {}},{"method": "GET","path": "/welcome",- "handler": ""+ "handler": "",+ "examples": {}},{"method": "PATCH","path": "/profiles/meta",- "handler": "handleUpdateMeta"+ "handler": "handleUpdateMeta",+ "examples": {}},{"method": "PATCH","path": "/profiles/{name}",- "handler": "handleUpdateByPath"+ "handler": "handleUpdateByPath",+ "examples": {}},{"method": "POST","path": "/action",- "handler": "HandleAction"+ "handler": "HandleAction",+ "examples": {}},{"method": "POST","path": "/actions",- "handler": "HandleActions"+ "handler": "HandleActions",+ "examples": {}},{"method": "POST","path": "/cookies",- "handler": "HandleSetCookies"+ "handler": "HandleSetCookies",+ "examples": {}},{"method": "POST","path": "/ensure-chrome",- "handler": "HandleEnsureChrome"+ "handler": "HandleEnsureChrome",+ "examples": {}},{"method": "POST","path": "/evaluate",- "handler": "HandleEvaluate"+ "handler": "HandleEvaluate",+ "examples": {}},{"method": "POST","path": "/fingerprint/rotate",- "handler": "HandleFingerprintRotate"+ "handler": "HandleFingerprintRotate",+ "examples": {}},{"method": "POST","path": "/instances/launch",- "handler": "handleLaunchByName"+ "handler": "handleLaunchByName",+ "examples": {}},{"method": "POST","path": "/instances/{id}/action",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/actions",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/cookies",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/ensure-chrome",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/evaluate",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/navigate",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/stop",- "handler": "handleStopByInstanceID"+ "handler": "handleStopByInstanceID",+ "examples": {}},{"method": "POST","path": "/instances/{id}/tab",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/tab/lock",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/tab/unlock",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/instances/{id}/upload",- "handler": "proxyToInstance"+ "handler": "proxyToInstance",+ "examples": {}},{"method": "POST","path": "/navigate",- "handler": "HandleNavigate"+ "handler": "HandleNavigate",+ "examples": {}},{"method": "POST","path": "/profiles/create",- "handler": "handleCreate"+ "handler": "handleCreate",+ "examples": {}},{"method": "POST","path": "/profiles/import",- "handler": "handleImport"+ "handler": "handleImport",+ "examples": {}},{"method": "POST","path": "/profiles/{id}/start",- "handler": "handleStartByID"+ "handler": "handleStartByID",+ "examples": {}},{"method": "POST","path": "/profiles/{id}/stop",- "handler": "handleStopByID"+ "handler": "handleStopByID",+ "examples": {}},{"method": "POST","path": "/profiles/{name}/reset",- "handler": "handleResetByPath"+ "handler": "handleResetByPath",+ "examples": {}},{"method": "POST","path": "/start/{id}",- "handler": "handleStartByID"+ "handler": "handleStartByID",+ "examples": {}},{"method": "POST","path": "/stop/{id}",- "handler": "handleStopByID"+ "handler": "handleStopByID",+ "examples": {}},{"method": "POST","path": "/tab",- "handler": "HandleTab"+ "handler": "HandleTab",+ "examples": {}},{"method": "POST","path": "/tab/lock",- "handler": "HandleTabLock"+ "handler": "HandleTabLock",+ "examples": {}},{"method": "POST","path": "/tab/unlock",- "handler": "HandleTabUnlock"+ "handler": "HandleTabUnlock",+ "examples": {}},{"method": "POST","path": "/upload",- "handler": "HandleUpload"+ "handler": "HandleUpload",+ "examples": {}}]}diff --git a/scripts/ENDPOINT_METADATA.md b/scripts/ENDPOINT_METADATA.mdnew file mode 100644index 00000000..d61bc469--- /dev/null+++ b/scripts/ENDPOINT_METADATA.md@@ -0,0 +1,107 @@+# Endpoint Metadata Format++Add rich metadata to endpoints using structured comments.++## Format++Add comments above handler functions with metadata:++```go+// HandleNavigate navigates a tab to a URL or creates a new tab.+// @Description Navigate to a URL in an existing tab or create a new tab+// @Implemented true+// @Param tabId string body optional Tab ID (creates new if omitted)+// @Param url string body required URL to navigate to+// @Param newTab bool body optional Force create new tab (default: false)+// @Param timeout float64 body optional Timeout in ms (default: 30000)+// @Curl curl -X POST http://localhost:9867/navigate -H "Content-Type: application/json" -d '{"url":"https://example.com"}'+// @CLI pinchtab nav https://example.com+// @Example {"tabId":"tab-123","url":"https://example.com","timeout":30000}+func (h *Handlers) HandleNavigate(w http.ResponseWriter, r *http.Request) {+```++## Tags++| Tag | Format | Example | Purpose |+|-----|--------|---------|---------|+| `@Description` | Text | `@Description Navigate to URL or create new tab` | Brief endpoint description |+| `@Implemented` | true/false | `@Implemented true` | Is this endpoint fully implemented? |+| `@Param` | name type location required/optional description | `@Param url string body required URL to navigate` | Parameter definition |+| `@Curl` | Full curl command | `@Curl curl -X POST http://localhost:9867/...` | Example curl command |+| `@CLI` | CLI command | `@CLI pinchtab nav https://example.com` | Example CLI command |+| `@Example` | JSON | `@Example {"url":"https://example.com"}` | Example request payload |++## Example: Full Handler Documentation++```go+// HandleAction performs a single action on a tab.+// @Description Click, type, fill, hover, focus, scroll, select on page elements+// @Implemented true+// @Param tabId string body required Tab ID+// @Param kind string body required Action: "click", "type", "fill", "press", "hover", "focus", "scroll", "select"+// @Param ref string body required Element ref from snapshot (e.g., "e5")+// @Param text string body optional Text to type or fill+// @Param key string body optional Key for "press" (e.g., "Enter", "Tab")+// @Curl curl -X POST http://localhost:9867/action -H "Content-Type: application/json" -d '{"tabId":"abc","kind":"click","ref":"e5"}'+// @CLI pinchtab click e5+// @Example {"tabId":"abc123","kind":"click","ref":"e5"}+func (h *Handlers) HandleAction(w http.ResponseWriter, r *http.Request) {+```++## Parameter Format++```+@Param {name} {type} {location} {required|optional} {description}+```++**Types:** `string`, `int`, `bool`, `float64`, `json`+**Location:** `query`, `body`, `path`+**Requirement:** `required` or `optional (with defaults)`++## Examples (By Endpoint Type)++### Query Parameters (GET)++```go+// @Param tabId string query required Tab ID+// @Param filter string query optional Filter: "interactive" or "all" (default: "all")+// @Param compact bool query optional Compact output (default: false)+```++### Body Parameters (POST)++```go+// @Param tabId string body required Tab ID+// @Param url string body required URL to navigate to+// @Param timeout float64 body optional Timeout in ms (default: 30000)+```++### Path Parameters++```go+// @Param id string path required Instance ID+// @Param name string path required Profile name+```++## Priority Endpoints to Document++Phase 1 (Core):+- `HandleNavigate` (POST /navigate)+- `HandleSnapshot` (GET /snapshot)+- `HandleAction` (POST /action)+- `HandleText` (GET /text)++Phase 2 (Instance Management):+- `handleList` in orchestrator (GET /instances)+- `handleLaunchByName` in orchestrator (POST /instances/launch)++Phase 3 (Profile Management):+- `handleCreate` in profiles (POST /profiles/create)+- `handleImport` in profiles (POST /profiles/import)++## Current Implementation Status++Check `docs/references/api-reference.json` for the full list. Mark endpoints as:+- `@Implemented true` — Fully working+- `@Implemented false` — Planned/WIP+- (No tag) — Unknown statusdiff --git a/scripts/gen-api-docs/main.go b/scripts/gen-api-docs/main.goindex a168bfb3..369ba0c8 100644--- a/scripts/gen-api-docs/main.go+++ b/scripts/gen-api-docs/main.go@@ -14,9 +14,27 @@ import ()type Endpoint struct {- Method string `json:"method"`- Path string `json:"path"`- Handler string `json:"handler"`+ Method string `json:"method"`+ Path string `json:"path"`+ Handler string `json:"handler"`+ Description string `json:"description,omitempty"`+ Implemented *bool `json:"implemented,omitempty"`+ Params []Parameter `json:"params,omitempty"`+ Examples ExampleGroup `json:"examples,omitempty"`+}++type Parameter struct {+ Name string `json:"name"`+ Type string `json:"type"`+ Location string `json:"location"` // query, body, path+ Required bool `json:"required"`+ Description string `json:"description"`+}++type ExampleGroup struct {+ Curl string `json:"curl,omitempty"`+ CLI string `json:"cli,omitempty"`+ Payload string `json:"payload,omitempty"` // Example JSON payload}type APIReference struct {@@ -125,8 +143,31 @@ func extractEndpoints(filePath string) []Endpoint {}var endpoints []Endpoint+ handlerMetadata := make(map[string]Endpoint)- // Find any RegisterHandlers or RegisterRoutes function+ // First, extract metadata from all handler functions+ for _, decl := range file.Decls {+ funcDecl, ok := decl.(*ast.FuncDecl)+ if !ok {+ continue+ }++ // Look for handler functions and extract their metadata+ if strings.Contains(funcDecl.Name.Name, "Handle") || strings.Contains(funcDecl.Name.Name, "handle") {+ if funcDecl.Doc != nil {+ commentText := ""+ for _, comment := range funcDecl.Doc.List {+ commentText += strings.TrimPrefix(comment.Text, "// ") + "\n"+ }+ metadata := extractMetadata(commentText)+ if metadata.Description != "" || len(metadata.Params) > 0 || metadata.Examples.Curl != "" {+ handlerMetadata[funcDecl.Name.Name] = metadata+ }+ }+ }+ }++ // Then, extract routes from RegisterHandlers/RegisterRoutesfor _, decl := range file.Decls {funcDecl, ok := decl.(*ast.FuncDecl)if !ok {@@ -136,13 +177,92 @@ func extractEndpoints(filePath string) []Endpoint {// Look for RegisterHandlers or RegisterRoutesif funcDecl.Name.Name == "RegisterHandlers" || funcDecl.Name.Name == "RegisterRoutes" {// Extract HandleFunc calls- endpoints = append(endpoints, extractHandleFuncCalls(funcDecl.Body)...)+ routeEndpoints := extractHandleFuncCalls(funcDecl.Body)++ // Merge with metadata+ for _, ep := range routeEndpoints {+ if meta, ok := handlerMetadata[ep.Handler]; ok {+ ep.Description = meta.Description+ ep.Implemented = meta.Implemented+ ep.Params = meta.Params+ ep.Examples = meta.Examples+ }+ endpoints = append(endpoints, ep)+ }}}return endpoints}+func extractMetadata(commentText string) Endpoint {+ ep := Endpoint{}+ lines := strings.Split(commentText, "\n")++ for _, line := range lines {+ // Remove "// " prefix if present, then trim+ line = strings.TrimPrefix(line, "// ")+ line = strings.TrimSpace(line)++ if line == "" || !strings.HasPrefix(line, "@") {+ continue+ }++ // Split on first space after the tag+ parts := strings.SplitN(line, " ", 2)+ if len(parts) < 2 {+ continue+ }++ tag := parts[0]+ value := strings.TrimSpace(parts[1])++ switch tag {+ case "@Description":+ ep.Description = value+ case "@Implemented":+ implemented := value == "true"+ ep.Implemented = &implemented+ case "@Param":+ param := parseParam(value)+ ep.Params = append(ep.Params, param)+ case "@Curl":+ ep.Examples.Curl = value+ case "@CLI":+ ep.Examples.CLI = value+ case "@Example":+ ep.Examples.Payload = value+ }+ }++ return ep+}++func parseParam(paramStr string) Parameter {+ // Format: name type location required/optional description+ // Example: url string body required URL to navigate to+ parts := strings.SplitN(paramStr, " ", 5)++ p := Parameter{}+ if len(parts) >= 1 {+ p.Name = parts[0]+ }+ if len(parts) >= 2 {+ p.Type = parts[1]+ }+ if len(parts) >= 3 {+ p.Location = parts[2]+ }+ if len(parts) >= 4 {+ p.Required = parts[3] == "required"+ }+ if len(parts) >= 5 {+ p.Description = parts[4]+ }++ return p+}+func extractHandleFuncCalls(body *ast.BlockStmt) []Endpoint {var endpoints []Endpoint