High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
refactor: simplify API generator to output clean JSON endpoint list (66 endpoints)
Marioa0d0b45537b8
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex f44e318d..104918b7 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -23,7 +23,7 @@ repos:tests/.*\.md|\.github/.*\.md|skill/.*\.md|- docs/references/api-reference\.md|+ docs/references/.*\.json|README\.md|CONTRIBUTING\.md|CODE_OF_CONDUCT\.md|diff --git a/docs/references/api-reference.json b/docs/references/api-reference.jsonnew file mode 100644index 00000000..50c47b76--- /dev/null+++ b/docs/references/api-reference.json@@ -0,0 +1,337 @@+{+ "version": "1.0",+ "generated": "auto-generated from Go code",+ "count": 66,+ "endpoints": [+ {+ "method": "DELETE",+ "path": "/profiles/{name}",+ "handler": "handleDeleteByPath"+ },+ {+ "method": "GET",+ "path": "/",+ "handler": ""+ },+ {+ "method": "GET",+ "path": "/cookies",+ "handler": "HandleGetCookies"+ },+ {+ "method": "GET",+ "path": "/dashboard",+ "handler": ""+ },+ {+ "method": "GET",+ "path": "/dashboard/",+ "handler": ""+ },+ {+ "method": "GET",+ "path": "/dashboard/agents",+ "handler": "handleAgents"+ },+ {+ "method": "GET",+ "path": "/dashboard/events",+ "handler": "handleSSE"+ },+ {+ "method": "GET",+ "path": "/download",+ "handler": "HandleDownload"+ },+ {+ "method": "GET",+ "path": "/health",+ "handler": "HandleHealth"+ },+ {+ "method": "GET",+ "path": "/instances",+ "handler": "handleList"+ },+ {+ "method": "GET",+ "path": "/instances/tabs",+ "handler": "handleAllTabs"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/cookies",+ "handler": "proxyToInstance"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/download",+ "handler": "proxyToInstance"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/logs",+ "handler": "handleLogsByID"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/pdf",+ "handler": "proxyToInstance"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/proxy/screencast",+ "handler": "handleProxyScreencast"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/screencast",+ "handler": "proxyToInstance"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/screenshot",+ "handler": "proxyToInstance"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/snapshot",+ "handler": "proxyToInstance"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/tabs",+ "handler": "proxyToInstance"+ },+ {+ "method": "GET",+ "path": "/instances/{id}/text",+ "handler": "proxyToInstance"+ },+ {+ "method": "GET",+ "path": "/pdf",+ "handler": "HandlePDF"+ },+ {+ "method": "GET",+ "path": "/profiles",+ "handler": "handleList"+ },+ {+ "method": "GET",+ "path": "/profiles/{id}/instance",+ "handler": "handleProfileInstance"+ },+ {+ "method": "GET",+ "path": "/profiles/{name}/analytics",+ "handler": "handleAnalyticsByPath"+ },+ {+ "method": "GET",+ "path": "/profiles/{name}/logs",+ "handler": "handleLogsByPath"+ },+ {+ "method": "GET",+ "path": "/screencast",+ "handler": "HandleScreencast"+ },+ {+ "method": "GET",+ "path": "/screencast/tabs",+ "handler": "HandleScreencastAll"+ },+ {+ "method": "GET",+ "path": "/screenshot",+ "handler": "HandleScreenshot"+ },+ {+ "method": "GET",+ "path": "/snapshot",+ "handler": "HandleSnapshot"+ },+ {+ "method": "GET",+ "path": "/stealth/status",+ "handler": "HandleStealthStatus"+ },+ {+ "method": "GET",+ "path": "/tabs",+ "handler": "HandleTabs"+ },+ {+ "method": "GET",+ "path": "/text",+ "handler": "HandleText"+ },+ {+ "method": "GET",+ "path": "/welcome",+ "handler": ""+ },+ {+ "method": "PATCH",+ "path": "/profiles/meta",+ "handler": "handleUpdateMeta"+ },+ {+ "method": "PATCH",+ "path": "/profiles/{name}",+ "handler": "handleUpdateByPath"+ },+ {+ "method": "POST",+ "path": "/action",+ "handler": "HandleAction"+ },+ {+ "method": "POST",+ "path": "/actions",+ "handler": "HandleActions"+ },+ {+ "method": "POST",+ "path": "/cookies",+ "handler": "HandleSetCookies"+ },+ {+ "method": "POST",+ "path": "/ensure-chrome",+ "handler": "HandleEnsureChrome"+ },+ {+ "method": "POST",+ "path": "/evaluate",+ "handler": "HandleEvaluate"+ },+ {+ "method": "POST",+ "path": "/fingerprint/rotate",+ "handler": "HandleFingerprintRotate"+ },+ {+ "method": "POST",+ "path": "/instances/launch",+ "handler": "handleLaunchByName"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/action",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/actions",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/cookies",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/ensure-chrome",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/evaluate",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/navigate",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/stop",+ "handler": "handleStopByInstanceID"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/tab",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/tab/lock",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/tab/unlock",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/instances/{id}/upload",+ "handler": "proxyToInstance"+ },+ {+ "method": "POST",+ "path": "/navigate",+ "handler": "HandleNavigate"+ },+ {+ "method": "POST",+ "path": "/profiles/create",+ "handler": "handleCreate"+ },+ {+ "method": "POST",+ "path": "/profiles/import",+ "handler": "handleImport"+ },+ {+ "method": "POST",+ "path": "/profiles/{id}/start",+ "handler": "handleStartByID"+ },+ {+ "method": "POST",+ "path": "/profiles/{id}/stop",+ "handler": "handleStopByID"+ },+ {+ "method": "POST",+ "path": "/profiles/{name}/reset",+ "handler": "handleResetByPath"+ },+ {+ "method": "POST",+ "path": "/start/{id}",+ "handler": "handleStartByID"+ },+ {+ "method": "POST",+ "path": "/stop/{id}",+ "handler": "handleStopByID"+ },+ {+ "method": "POST",+ "path": "/tab",+ "handler": "HandleTab"+ },+ {+ "method": "POST",+ "path": "/tab/lock",+ "handler": "HandleTabLock"+ },+ {+ "method": "POST",+ "path": "/tab/unlock",+ "handler": "HandleTabUnlock"+ },+ {+ "method": "POST",+ "path": "/upload",+ "handler": "HandleUpload"+ }+ ]+}diff --git a/scripts/README.md b/scripts/README.mdindex 1a5c7aec..c29d2faf 100644--- a/scripts/README.md+++ b/scripts/README.md@@ -6,145 +6,101 @@ Utility scripts for PinchTab development, testing, and documentation.### Overview-Generate API reference documentation automatically from Go code.--Two approaches:--1. **Auto-extraction from code routes** — Fast, no comments needed-2. **Structured comments** — Rich documentation with examples+Automatically generate a complete JSON API reference from Go code.### Quick Start```bash-# Generate endpoint list (basic)-go run scripts/gen-api-docs/main.go > docs/references/api-reference.md--# Or with bash-./scripts/generate-api-docs.sh > docs/references/api-reference-bash.md-```+# Generate endpoint list as JSON+go run scripts/gen-api-docs/main.go > docs/references/api-reference.json-### Tools+# Pretty-print+go run scripts/gen-api-docs/main.go | jq .-#### `gen-api-docs/main.go` (Recommended)--Go-based tool using AST parsing.--**Features:**-- ✅ Parses `internal/handlers/handlers.go`-- ✅ Parses `internal/profiles/handlers.go`-- ✅ Parses `internal/orchestrator/handlers.go`-- ✅ Parses `internal/dashboard/dashboard.go`-- ✅ Generates sorted endpoint table-- ✅ Extracts handler names-- ✅ (Ready for) Structured comment parsing--**Usage:**-```bash-# Generate and print to stdout-go run scripts/gen-api-docs/main.go+# Count endpoints+go run scripts/gen-api-docs/main.go | jq '.count'-# Generate to file-go run scripts/gen-api-docs/main.go > docs/references/api-reference.md+# Filter by method+go run scripts/gen-api-docs/main.go | jq '.endpoints[] | select(.method == "POST")'-# Count endpoints-go run scripts/gen-api-docs/main.go | grep "^\| (GET\|POST\|DELETE\|PATCH\|PUT)" | wc -l+# Count by method+go run scripts/gen-api-docs/main.go | jq '.endpoints | group_by(.method) | map({method: .[0].method, count: length})'```-#### `generate-api-docs.sh`+### Tool: `gen-api-docs/main.go`-Bash-based tool using regex patterns.+Go-based tool using AST parsing. **Outputs structured JSON.****Features:**-- ✅ Simple pattern matching-- ✅ No dependencies (pure bash)-- ✅ Quick for CI/CD--**Usage:**-```bash-./scripts/generate-api-docs.sh > docs/references/api-reference-bash.md-```--### Adding Documentation to Handlers--#### Step 1: Review the Format--See `scripts/API_COMMENT_FORMAT.md` for the structured comment format.--#### Step 2: Add Comments to Handlers--Example: Adding documentation to `HandleSnapshot`--```go-// HandleSnapshot returns the accessibility tree of the current tab.-//-// @Endpoint GET /snapshot-// @Description Returns the page structure with clickable elements-//-// @Param tabId string query The tab ID (required)-// @Param filter string query Filter: "interactive" or "all" (optional, default: "all")-// @Param interactive bool query Show only interactive elements (optional)-//-// @Response 200 application/json Returns accessibility tree-//-// @Example curl:-// curl "http://localhost:9867/snapshot?tabId=abc123&filter=interactive"-//-// @Example cli:-// pinchtab snap -i -c-func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {- // implementation...+- ✅ Parses all handler files (handlers, profiles, orchestrator, dashboard)+- ✅ Extracts HTTP method, path, and handler name+- ✅ Removes duplicate endpoints+- ✅ Sorts by method then path+- ✅ Outputs clean JSON for programmatic use++**Output Format:**+```json+{+ "version": "1.0",+ "generated": "auto-generated from Go code",+ "count": 66,+ "endpoints": [+ {+ "method": "GET",+ "path": "/snapshot",+ "handler": "HandleSnapshot"+ },+ {+ "method": "POST",+ "path": "/navigate",+ "handler": "HandleNavigate"+ }+ ]}```-#### Step 3: Regenerate Docs--```bash-go run scripts/gen-api-docs/main.go > docs/references/api-reference.md-```--The tool will automatically extract your comments (once parsing is implemented).--### Priority Endpoints to Document--Add comments in this order:+### JSON File Structure-**Phase 1 (Core Operations):**-- `HandleNavigate` (POST /navigate)-- `HandleSnapshot` (GET /snapshot)-- `HandleAction` (POST /action)-- `HandleText` (GET /text)+**Location:** `docs/references/api-reference.json`-**Phase 2 (Instance/Profile Management):**-- `handleList` in orchestrator (GET /instances, GET /profiles)-- `handleLaunchByName` in orchestrator (POST /instances/launch)-- `handleCreate` in profiles (POST /profiles/create)+**Fields:**+- `version` (string) — API reference version (e.g., "1.0")+- `generated` (string) — Generation info+- `count` (number) — Total number of endpoints+- `endpoints` (array) — List of endpoint objects+ - `method` — HTTP method (GET, POST, PUT, DELETE, PATCH)+ - `path` — URL path pattern (e.g., `/snapshot`, `/instances/{id}/action`)+ - `handler` — Go handler function name-**Phase 3 (Complete Coverage):**-- All remaining endpoints+### Use Cases-### Documentation Files--| File | Purpose |-|------|---------|-| `API_COMMENT_FORMAT.md` | Guide for structured comments |-| `API_DOCS_GENERATION.md` | How the generator works |-| `gen-api-docs/main.go` | Go AST parser |-| `generate-api-docs.sh` | Bash fallback |--### Next Steps+**Programmatic Access:**+```bash+# Find all POST endpoints+jq '.endpoints[] | select(.method == "POST") | .path'-1. **Add comments** to high-value handlers using the format in `API_COMMENT_FORMAT.md`-2. **Run generator:** `go run scripts/gen-api-docs/main.go > docs/references/api-reference.md`-3. **Commit:** Both code changes and generated docs-4. **Iterate:** Add more comments to remaining endpoints+# Find endpoints by path+jq '.endpoints[] | select(.path | contains("instances"))'-### Example Output+# Find endpoints by handler+jq '.endpoints[] | select(.handler | contains("Handle"))'+```-Current generated docs in `docs/references/api-reference.md`:+**Validation:**+```bash+# Verify total count+TOTAL=$(jq '.count' < docs/references/api-reference.json)+ACTUAL=$(jq '.endpoints | length' < docs/references/api-reference.json)+[ "$TOTAL" = "$ACTUAL" ] && echo "Count matches" || echo "Mismatch"+```-- **72 endpoints** extracted from code-- **Sorted by method then path**-- **Ready for enrichment** with structured comments+**CI/CD:**+```bash+# Generate in CI pipeline+go run scripts/gen-api-docs/main.go > /tmp/api-ref.json+# Commit if changed+git diff docs/references/api-reference.json && git add . && git commit -m "docs: update api reference"+```### Technical Details@@ -154,17 +110,28 @@ The Go tool:- Finds all functions named `RegisterHandlers` or `RegisterRoutes`- Extracts `mux.HandleFunc()` and `mux.Handle()` calls- Parses route patterns with regex: `"METHOD /path"`+- Removes duplicates (same method + path)- Sorts results for consistency+- Outputs JSON with proper formatting-Future enhancements:-- Parse `@Param` tags from comments-- Extract parameter types and defaults-- Generate complete examples (curl, CLI, Python, JS)-- Validate against actual handler signatures+### Why JSON?++- ✅ **Structured data** — Easy to parse programmatically+- ✅ **No styling** — Plain facts, no markdown formatting to maintain+- ✅ **Tooling** — Use `jq` or any JSON tool to query/filter+- ✅ **Automation** — CI/CD can validate endpoint counts, check for breaking changes+- ✅ **Flexibility** — Can generate docs in any format from JSON++### For Complete Documentation++For full endpoint documentation with parameters, examples, response types, see:+- `docs/examples/API_DOCUMENTATION_EXAMPLES.md` — Complete workflow examples+- `docs/references/endpoints.md` — Full manual API reference+- `docs/references/curl-commands.md` — cURL examples----For questions, see:-- `scripts/API_COMMENT_FORMAT.md` — How to document handlers-- `scripts/API_DOCS_GENERATION.md` — Technical details-- `docs/references/api-reference.md` — Current generated output+## Other Scripts++Bash-based tools:+- `generate-api-docs.sh` — Regex-based endpoint extraction (fallback)diff --git a/scripts/gen-api-docs/main.go b/scripts/gen-api-docs/main.goindex a9158238..a168bfb3 100644--- a/scripts/gen-api-docs/main.go+++ b/scripts/gen-api-docs/main.go@@ -1,6 +1,7 @@package mainimport (+ "encoding/json""fmt""go/ast""go/parser"@@ -10,61 +11,43 @@ import ("regexp""sort""strings"- "time")type Endpoint struct {- Method string- Path string- Handler string- Doc string- Description string- Params []Param- Examples map[string]string // format -> example code+ Method string `json:"method"`+ Path string `json:"path"`+ Handler string `json:"handler"`}-type Param struct {- Name string- Type string- Location string // query, body, path- Description string+type APIReference struct {+ Version string `json:"version"`+ Generated string `json:"generated"`+ Count int `json:"count"`+ Endpoints []Endpoint `json:"endpoints"`}func main() {- // Parse all relevant files for routes and handler comments+ // Parse all relevant files for routesvar 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 {@@ -87,107 +70,20 @@ func main() {return endpoints[i].Path < endpoints[j].Path})- // Generate markdown- fmt.Println("# API Reference (Auto-Generated)")- fmt.Println("")- fmt.Printf("Generated: %s\n", time.Now().UTC().Format(time.RFC3339))- fmt.Println("")- fmt.Println("---")- fmt.Println("")-- fmt.Println("## Endpoints Summary")- fmt.Println("")- fmt.Println("| Method | Path | Handler | Notes |")- fmt.Println("|--------|------|---------|-------|")-- for _, ep := range endpoints {- notes := ""- if ep.Doc != "" {- // 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)+ // Build API reference+ ref := APIReference{+ Version: "1.0",+ Generated: "auto-generated from Go code",+ Count: len(endpoints),+ Endpoints: endpoints,}- fmt.Println("")- fmt.Println("---")- fmt.Println("")- fmt.Println("## Detailed Endpoints")- fmt.Println("")-- for _, ep := range endpoints {- fmt.Printf("### %s %s\n", ep.Method, ep.Path)- fmt.Println("")-- if ep.Doc != "" {- // Clean up the doc text- docLines := strings.Split(strings.TrimSpace(ep.Doc), "\n")- for _, line := range docLines {- fmt.Println(line)- }- fmt.Println("")- }-- if ep.Handler != "" {- fmt.Printf("**Handler:** `%s`\n", ep.Handler)- fmt.Println("")- }+ // Output as JSON+ encoder := json.NewEncoder(os.Stdout)+ encoder.SetIndent("", " ")+ if err := encoder.Encode(ref); err != nil {+ log.Fatalf("Error encoding JSON: %v", err)}-- fmt.Println("---")- fmt.Println("")- fmt.Println("## Notes")- fmt.Println("")- fmt.Println("- This documentation is auto-generated from Go code")- fmt.Println("- For full implementation details, see `internal/handlers/*.go`")- fmt.Println("- Query parameters and request bodies are defined in each handler")- 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) {@@ -247,41 +143,6 @@ 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