Skip to content

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.json
index 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.md
new file mode 100644
index 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 status
diff --git a/scripts/gen-api-docs/main.go b/scripts/gen-api-docs/main.go
index 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/RegisterRoutes
for _, decl := range file.Decls {
funcDecl, ok := decl.(*ast.FuncDecl)
if !ok {
@@ -136,13 +177,92 @@ func extractEndpoints(filePath string) []Endpoint {
// Look for RegisterHandlers or RegisterRoutes
if 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