High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: add pinchtab audit command and multi-page POST /audit runner
Luigi Agosti58d96c498476
diff --git a/cmd/pinchtab/cmd_audit.go b/cmd/pinchtab/cmd_audit.gonew file mode 100644index 00000000..b030db50--- /dev/null+++ b/cmd/pinchtab/cmd_audit.go@@ -0,0 +1,28 @@+package main++import (+ browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"+ "github.com/spf13/cobra"+)++var auditCmd = &cobra.Command{+ Use: "audit <url>",+ Short: "Run a browser-level site audit",+ Long: `Audit one or more pages with full browser enrichment: screenshots,+console logs, network requests and broken assets, interactive elements,+accessibility score, and timing metrics.++The argument is a page URL, or a sitemap URL with --sitemap (pages are then+discovered from it). With --output-dir the report is written to+<dir>/report.json and screenshots to <dir>/screenshots/; --json prints the+full report to stdout.++Pages that fail to load do not fail the run: the command still exits 0 and+the failing page's report entry carries an "error" field.`,+ Args: cobra.ExactArgs(1),+ Run: func(cmd *cobra.Command, args []string) {+ runCLI(func(rt cliRuntime) {+ browseractions.Audit(rt.client, rt.base, rt.token, cmd, args[0])+ })+ },+}diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.goindex c24ec6b7..c2bff8ef 100644--- a/cmd/pinchtab/cmd_cli_register.go+++ b/cmd/pinchtab/cmd_cli_register.go@@ -25,7 +25,7 @@ func browserRootCommands() []*cobra.Command {downloadCmd, uploadCmd, findCmd, selectCmd, checkCmd, uncheckCmd, networkCmd, waitCmd,keyboardCmd, keydownCmd, keyupCmd, scrollintoviewCmd, dialogCmd, consoleCmd, errorsCmd,clipboardCmd, cacheCmd, cookiesCmd, setCmd, storageCmd, stateCmd, closeCmd, handoffCmd,- resumeCmd, handoffStatusCmd, recordCmd,+ resumeCmd, handoffStatusCmd, recordCmd, auditCmd,}}@@ -355,6 +355,14 @@ func configureBrowserFlags() {errorsCmd.Flags().Bool("clear", false, "Clear error logs")errorsCmd.Flags().String("limit", "", "Maximum entries to return")+ auditCmd.Flags().Bool("sitemap", false, "Treat the URL as a sitemap.xml and audit the discovered pages")+ auditCmd.Flags().Int("sample-size", 0, "Cap the number of audited pages (0 = no cap)")+ auditCmd.Flags().Bool("screenshot", true, "Capture page screenshots")+ auditCmd.Flags().Bool("network-monitor", true, "Collect network requests and broken assets")+ auditCmd.Flags().String("output-dir", "", "Write report.json and screenshots/ to this directory")+ auditCmd.Flags().Int("concurrency", 0, "Pages audited in parallel (default 2, max 8)")+ auditCmd.Flags().Bool("json", false, "Print the full report JSON to stdout")+addTabFlag(consoleCmd, errorsCmd)}diff --git a/internal/audit/run.go b/internal/audit/run.gonew file mode 100644index 00000000..2029a4af--- /dev/null+++ b/internal/audit/run.go@@ -0,0 +1,173 @@+package audit++import (+ "encoding/xml"+ "errors"+ "fmt"+ "sync"+ "time"+)++// DefaultConcurrency is the number of pages audited in parallel when the+// caller does not choose one; MaxConcurrency caps what a caller may request+// (each worker drives its own browser tab).+const (+ DefaultConcurrency = 2+ MaxConcurrency = 8+)++// RunOptions configures a multi-page audit run.+type RunOptions struct {+ // SampleSize caps the number of audited pages, 0 = no cap. (Per-group+ // sampling lands with page grouping; this is a plain truncation.)+ SampleSize int+ // Concurrency is the number of pages audited in parallel, clamped to+ // [1, MaxConcurrency].+ Concurrency int+ // Page selects the collectors for every page.+ Page PageOptions+}++// SitemapFetcher discovers page URLs from a sitemap URL. Isolated behind a+// function type so a richer discovery (e.g. seaportal.FlattenSitemap) can be+// swapped in.+type SitemapFetcher func(sitemapURL string) ([]string, error)++// PageAuditor audits a single URL. Failures must come back as a PageAudit+// with the Error field set, never as a panic.+type PageAuditor func(url string, opts PageOptions) PageAudit++// PlanURLs dedupes the URL list preserving first-occurrence order, so the+// entry URL stays first. Empty strings are dropped.+func PlanURLs(urls []string) []string {+ seen := make(map[string]bool, len(urls))+ plan := make([]string, 0, len(urls))+ for _, u := range urls {+ if u == "" || seen[u] {+ continue+ }+ seen[u] = true+ plan = append(plan, u)+ }+ return plan+}++type sitemapURLSet struct {+ URLs []struct {+ Loc string `xml:"loc"`+ } `xml:"url"`+}++// ParseSitemap extracts the <loc> URLs from a sitemap.xml document.+func ParseSitemap(data []byte) ([]string, error) {+ var set sitemapURLSet+ if err := xml.Unmarshal(data, &set); err != nil {+ return nil, fmt.Errorf("parse sitemap: %w", err)+ }+ urls := make([]string, 0, len(set.URLs))+ for _, u := range set.URLs {+ if u.Loc != "" {+ urls = append(urls, u.Loc)+ }+ }+ return urls, nil+}++// clampConcurrency normalizes a requested concurrency into [1, MaxConcurrency].+func clampConcurrency(n int) int {+ switch {+ case n < 1:+ return DefaultConcurrency+ case n > MaxConcurrency:+ return MaxConcurrency+ default:+ return n+ }+}++// RunAudit audits every planned URL and assembles the versioned AuditReport.+// The entry URL (first in the plan) is always audited first, synchronously;+// the rest run with bounded concurrency. Page failures are report data, not+// errors — RunAudit only errors when there is nothing to audit.+func RunAudit(input AuditInput, opts RunOptions, discover SitemapFetcher, auditPage PageAuditor) (AuditReport, error) {+ urls := input.URLs+ if len(urls) == 0 && input.SitemapURL != "" {+ if discover == nil {+ return AuditReport{}, errors.New("sitemap input requires a sitemap fetcher")+ }+ discovered, err := discover(input.SitemapURL)+ if err != nil {+ return AuditReport{}, fmt.Errorf("sitemap discovery: %w", err)+ }+ urls = discovered+ }++ plan := PlanURLs(urls)+ if opts.SampleSize > 0 && len(plan) > opts.SampleSize {+ plan = plan[:opts.SampleSize]+ }+ if len(plan) == 0 {+ return AuditReport{}, errors.New("no URLs to audit")+ }++ concurrency := clampConcurrency(opts.Concurrency)+ results := make([]PageAudit, len(plan))+ results[0] = auditPage(plan[0], opts.Page)++ sem := make(chan struct{}, concurrency)+ var wg sync.WaitGroup+ for i := 1; i < len(plan); i++ {+ wg.Add(1)+ go func(i int) {+ defer wg.Done()+ sem <- struct{}{}+ defer func() { <-sem }()+ results[i] = auditPage(plan[i], opts.Page)+ }(i)+ }+ wg.Wait()++ report := NewAuditReport()+ report.GeneratedAt = time.Now().UTC()+ report.Input = input+ report.Options = AuditOptions{+ SampleSize: opts.SampleSize,+ Screenshot: opts.Page.Screenshot,+ NetworkMonitor: opts.Page.Network,+ Concurrency: concurrency,+ }+ report.Pages = make([]PageResult, len(results))+ for i, pa := range results {+ report.Pages[i] = pa.ToPageResult()+ }+ report.SummaryScore = summaryScore(results)+ return report, nil+}++// ToPageResult converts a single-page audit into the report page shape.+func (pa PageAudit) ToPageResult() PageResult {+ return PageResult{+ URL: pa.URL,+ Title: pa.Title,+ Error: pa.Error,+ Screenshot: pa.Screenshot,+ Browser: pa.BrowserPageData,+ }+}++// summaryScore is the mean accessibility score across pages that were+// audited without error, 0 when none were.+func summaryScore(results []PageAudit) int {+ sum, n := 0, 0+ for _, pa := range results {+ if pa.Error != "" {+ continue+ }+ sum += pa.AccessibilityScore+ n+++ }+ if n == 0 {+ return 0+ }+ return sum / n+}diff --git a/internal/audit/run_test.go b/internal/audit/run_test.gonew file mode 100644index 00000000..a346a646--- /dev/null+++ b/internal/audit/run_test.go@@ -0,0 +1,216 @@+package audit++import (+ "errors"+ "reflect"+ "sync"+ "sync/atomic"+ "testing"+)++func TestPlanURLs(t *testing.T) {+ got := PlanURLs([]string{"a", "b", "a", "", "c", "b"})+ want := []string{"a", "b", "c"}+ if !reflect.DeepEqual(got, want) {+ t.Errorf("PlanURLs = %v, want %v", got, want)+ }+ if got := PlanURLs(nil); len(got) != 0 {+ t.Errorf("PlanURLs(nil) = %v", got)+ }+}++func TestParseSitemap(t *testing.T) {+ data := []byte(`<?xml version="1.0" encoding="UTF-8"?>+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">+ <url><loc>http://fixtures/a.html</loc></url>+ <url><loc>http://fixtures/b.html</loc></url>+ <url><loc></loc></url>+</urlset>`)+ got, err := ParseSitemap(data)+ if err != nil {+ t.Fatalf("ParseSitemap: %v", err)+ }+ want := []string{"http://fixtures/a.html", "http://fixtures/b.html"}+ if !reflect.DeepEqual(got, want) {+ t.Errorf("ParseSitemap = %v, want %v", got, want)+ }++ if _, err := ParseSitemap([]byte("not xml at all <")); err == nil {+ t.Error("ParseSitemap should error on malformed XML")+ }+}++func fakeAuditor() (PageAuditor, *[]string, *sync.Mutex) {+ var mu sync.Mutex+ var calls []string+ return func(url string, opts PageOptions) PageAudit {+ mu.Lock()+ calls = append(calls, url)+ mu.Unlock()+ return PageAudit{URL: url, BrowserPageData: BrowserPageData{AccessibilityScore: 100}}+ }, &calls, &mu+}++func TestRunAuditOrderingAndDedupe(t *testing.T) {+ auditor, calls, _ := fakeAuditor()+ report, err := RunAudit(+ AuditInput{URLs: []string{"http://x/home", "http://x/a", "http://x/home", "http://x/b"}},+ RunOptions{Concurrency: 1},+ nil, auditor,+ )+ if err != nil {+ t.Fatalf("RunAudit: %v", err)+ }+ if report.SchemaVersion != SchemaVersion {+ t.Errorf("SchemaVersion = %q", report.SchemaVersion)+ }+ if (*calls)[0] != "http://x/home" {+ t.Errorf("entry URL not audited first: %v", *calls)+ }+ var urls []string+ for _, p := range report.Pages {+ urls = append(urls, p.URL)+ }+ want := []string{"http://x/home", "http://x/a", "http://x/b"}+ if !reflect.DeepEqual(urls, want) {+ t.Errorf("page order = %v, want %v", urls, want)+ }+ if report.SummaryScore != 100 {+ t.Errorf("SummaryScore = %d, want 100", report.SummaryScore)+ }+}++func TestRunAuditEntryFirstSynchronously(t *testing.T) {+ var entryDone atomic.Bool+ auditor := func(url string, opts PageOptions) PageAudit {+ if url == "http://x/entry" {+ entryDone.Store(true)+ } else if !entryDone.Load() {+ t.Errorf("page %s started before entry finished", url)+ }+ return PageAudit{URL: url}+ }+ if _, err := RunAudit(+ AuditInput{URLs: []string{"http://x/entry", "http://x/a", "http://x/b", "http://x/c"}},+ RunOptions{Concurrency: 4},+ nil, auditor,+ ); err != nil {+ t.Fatalf("RunAudit: %v", err)+ }+}++func TestRunAuditConcurrencyBound(t *testing.T) {+ var active, peak atomic.Int32+ auditor := func(url string, opts PageOptions) PageAudit {+ cur := active.Add(1)+ for {+ p := peak.Load()+ if cur <= p || peak.CompareAndSwap(p, cur) {+ break+ }+ }+ defer active.Add(-1)+ return PageAudit{URL: url}+ }+ var urls []string+ for i := range 20 {+ urls = append(urls, "http://x/p"+string(rune('a'+i)))+ }+ report, err := RunAudit(AuditInput{URLs: urls}, RunOptions{Concurrency: 3}, nil, auditor)+ if err != nil {+ t.Fatalf("RunAudit: %v", err)+ }+ if len(report.Pages) != 20 {+ t.Errorf("pages = %d, want 20", len(report.Pages))+ }+ if peak.Load() > 3 {+ t.Errorf("peak concurrency = %d, want <= 3", peak.Load())+ }+ if report.Options.Concurrency != 3 {+ t.Errorf("Options.Concurrency = %d", report.Options.Concurrency)+ }+}++func TestRunAuditConcurrencyYieldsSameURLSet(t *testing.T) {+ urls := []string{"http://x/1", "http://x/2", "http://x/3", "http://x/4", "http://x/5"}+ pageSet := func(concurrency int) map[string]bool {+ auditor, _, _ := fakeAuditor()+ report, err := RunAudit(AuditInput{URLs: urls}, RunOptions{Concurrency: concurrency}, nil, auditor)+ if err != nil {+ t.Fatalf("RunAudit(concurrency=%d): %v", concurrency, err)+ }+ set := map[string]bool{}+ for _, p := range report.Pages {+ set[p.URL] = true+ }+ return set+ }+ if !reflect.DeepEqual(pageSet(1), pageSet(3)) {+ t.Error("concurrency 1 and 3 yield different URL sets")+ }+}++func TestRunAuditSitemapMode(t *testing.T) {+ auditor, _, _ := fakeAuditor()+ discover := func(sitemapURL string) ([]string, error) {+ if sitemapURL != "http://x/sitemap.xml" {+ t.Errorf("sitemapURL = %q", sitemapURL)+ }+ return []string{"http://x/a", "http://x/b"}, nil+ }+ report, err := RunAudit(AuditInput{SitemapURL: "http://x/sitemap.xml"}, RunOptions{}, discover, auditor)+ if err != nil {+ t.Fatalf("RunAudit: %v", err)+ }+ if len(report.Pages) != 2 {+ t.Errorf("pages = %d, want 2", len(report.Pages))+ }++ if _, err := RunAudit(AuditInput{SitemapURL: "http://x/sitemap.xml"}, RunOptions{}, func(string) ([]string, error) {+ return nil, errors.New("fetch failed")+ }, auditor); err == nil {+ t.Error("RunAudit should surface sitemap fetch errors")+ }+}++func TestRunAuditSampleSizeAndEmpty(t *testing.T) {+ auditor, _, _ := fakeAuditor()+ report, err := RunAudit(+ AuditInput{URLs: []string{"http://x/1", "http://x/2", "http://x/3"}},+ RunOptions{SampleSize: 2},+ nil, auditor,+ )+ if err != nil {+ t.Fatalf("RunAudit: %v", err)+ }+ if len(report.Pages) != 2 {+ t.Errorf("pages = %d, want 2 (sample size)", len(report.Pages))+ }++ if _, err := RunAudit(AuditInput{}, RunOptions{}, nil, auditor); err == nil {+ t.Error("RunAudit with no input should error")+ }+}++func TestRunAuditErrorsAreData(t *testing.T) {+ auditor := func(url string, opts PageOptions) PageAudit {+ if url == "http://x/down" {+ return NewPageAuditError(url, errors.New("connection refused"))+ }+ return PageAudit{URL: url, BrowserPageData: BrowserPageData{AccessibilityScore: 80}}+ }+ report, err := RunAudit(+ AuditInput{URLs: []string{"http://x/up", "http://x/down"}},+ RunOptions{},+ nil, auditor,+ )+ if err != nil {+ t.Fatalf("RunAudit: %v", err)+ }+ if report.Pages[1].Error != "connection refused" {+ t.Errorf("failed page Error = %q", report.Pages[1].Error)+ }+ if report.SummaryScore != 80 {+ t.Errorf("SummaryScore = %d, want 80 (failed pages excluded)", report.SummaryScore)+ }+}diff --git a/internal/audit/types.go b/internal/audit/types.goindex 5976976d..b9f508b3 100644--- a/internal/audit/types.go+++ b/internal/audit/types.go@@ -162,6 +162,11 @@ type PageResult struct {Title string `json:"title,omitempty"`// StatusCode is the HTTP status of the page navigation, when known.StatusCode int `json:"statusCode,omitempty"`+ // Error describes a navigation or collection failure; empty on success.+ Error string `json:"error,omitempty"`+ // Screenshot is the base64-encoded PNG when captured inline; consumers+ // writing artifacts move it to Browser.ScreenshotPath.+ Screenshot string `json:"screenshot,omitempty"`// Seaportal holds SeaPortal per-page summary fields passed through// verbatim when the input was a SeaPortal results file.Seaportal map[string]any `json:"seaportal,omitempty"`diff --git a/internal/cli/actions/actions_audit.go b/internal/cli/actions/actions_audit.gonew file mode 100644index 00000000..8c704add--- /dev/null+++ b/internal/cli/actions/actions_audit.go@@ -0,0 +1,135 @@+package actions++import (+ "encoding/base64"+ "encoding/json"+ "fmt"+ "net/http"+ "os"+ "path/filepath"+ "time"++ "github.com/pinchtab/pinchtab/internal/cli/apiclient"+ "github.com/spf13/cobra"+)++// auditTimeout bounds a whole multi-page audit run; well above the default+// per-request client timeout, which a site audit easily exceeds.+const auditTimeout = 10 * time.Minute++// Audit runs a multi-page site audit via POST /audit and writes artifacts.+func Audit(client *http.Client, base, token string, cmd *cobra.Command, target string) {+ body := map[string]any{}+ if v, _ := cmd.Flags().GetBool("sitemap"); v {+ body["sitemapUrl"] = target+ } else {+ body["urls"] = []string{target}+ }++ screenshot, _ := cmd.Flags().GetBool("screenshot")+ network, _ := cmd.Flags().GetBool("network-monitor")+ body["options"] = map[string]any{"screenshot": screenshot, "network": network}+ if v, _ := cmd.Flags().GetInt("concurrency"); v > 0 {+ body["concurrency"] = v+ }+ if v, _ := cmd.Flags().GetInt("sample-size"); v > 0 {+ body["sampleSize"] = v+ }++ longClient := &http.Client{Transport: client.Transport, Timeout: auditTimeout}+ raw := apiclient.DoPostRaw(longClient, base, token, "/audit", body)++ var report map[string]any+ if err := json.Unmarshal(raw, &report); err != nil {+ fmt.Fprintf(os.Stderr, "parse audit report: %v\n", err)+ os.Exit(1)+ }++ if dir, _ := cmd.Flags().GetString("output-dir"); dir != "" {+ if err := writeAuditArtifacts(dir, report); err != nil {+ fmt.Fprintf(os.Stderr, "write artifacts: %v\n", err)+ os.Exit(1)+ }+ fmt.Fprintf(os.Stderr, "report written to %s\n", filepath.Join(dir, "report.json"))+ }++ if v, _ := cmd.Flags().GetBool("json"); v {+ out, _ := json.MarshalIndent(report, "", " ")+ fmt.Println(string(out))+ return+ }+ printAuditSummary(report)+}++// writeAuditArtifacts writes report.json and screenshots/ under dir. Inline+// base64 screenshots are moved to files and each page's browser entry gets+// the relative screenshotPath instead.+func writeAuditArtifacts(dir string, report map[string]any) error {+ shotsDir := filepath.Join(dir, "screenshots")+ if err := os.MkdirAll(shotsDir, 0o755); err != nil {+ return err+ }++ pages, _ := report["pages"].([]any)+ for i, p := range pages {+ page, ok := p.(map[string]any)+ if !ok {+ continue+ }+ b64, _ := page["screenshot"].(string)+ if b64 == "" {+ continue+ }+ data, err := base64.StdEncoding.DecodeString(b64)+ if err != nil {+ continue+ }+ relPath := filepath.Join("screenshots", fmt.Sprintf("page-%03d.png", i+1))+ if err := os.WriteFile(filepath.Join(dir, relPath), data, 0o644); err != nil {+ return err+ }+ delete(page, "screenshot")+ if browser, ok := page["browser"].(map[string]any); ok {+ browser["screenshotPath"] = relPath+ }+ }++ out, err := json.MarshalIndent(report, "", " ")+ if err != nil {+ return err+ }+ return os.WriteFile(filepath.Join(dir, "report.json"), out, 0o644)+}++func printAuditSummary(report map[string]any) {+ pages, _ := report["pages"].([]any)+ failed := 0+ broken := 0+ for _, p := range pages {+ page, ok := p.(map[string]any)+ if !ok {+ continue+ }+ if e, _ := page["error"].(string); e != "" {+ failed+++ }+ if browser, ok := page["browser"].(map[string]any); ok {+ if assets, ok := browser["brokenAssets"].([]any); ok {+ broken += len(assets)+ }+ }+ }+ fmt.Printf("Audited %d page(s) · summary score %v · %d broken asset(s) · %d failed page(s)\n",+ len(pages), report["summaryScore"], broken, failed)+ for _, p := range pages {+ page, ok := p.(map[string]any)+ if !ok {+ continue+ }+ status := "ok"+ if e, _ := page["error"].(string); e != "" {+ status = "error: " + e+ }+ fmt.Printf(" %s · %s\n", page["url"], status)+ }+}diff --git a/internal/handlers/audit.go b/internal/handlers/audit.gonew file mode 100644index 00000000..3cfd10eb--- /dev/null+++ b/internal/handlers/audit.go@@ -0,0 +1,92 @@+package handlers++import (+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "time"++ "github.com/pinchtab/pinchtab/internal/audit"+ "github.com/pinchtab/pinchtab/internal/config"+ "github.com/pinchtab/pinchtab/internal/httpx"+)++const maxSitemapBytes = 5 << 20++type auditRequest struct {+ URLs []string `json:"urls"`+ SitemapURL string `json:"sitemapUrl"`+ Options *auditPageOptionsBody `json:"options"`+ Concurrency int `json:"concurrency"`+ SampleSize int `json:"sampleSize"`+}++// @Endpoint POST /audit+func (h *Handlers) HandleAudit(w http.ResponseWriter, r *http.Request) {+ var req auditRequest+ if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, maxBodySize)).Decode(&req); err != nil {+ httpx.Error(w, 400, fmt.Errorf("decode: %w", err))+ return+ }+ if len(req.URLs) == 0 && req.SitemapURL == "" {+ httpx.Error(w, 400, fmt.Errorf("urls or sitemapUrl required"))+ return+ }++ routing, ok := h.resolveNavigateBrowser(w, r, "", "")+ if !ok {+ return+ }+ if !h.ensureBrowserOrRespond(w, routing.EffectiveCfg) {+ return+ }++ auditor := func(url string, opts audit.PageOptions) audit.PageAudit {+ targets, err := h.validateAuditTarget(url, routing.EffectiveCfg)+ if err != nil {+ return audit.NewPageAuditError(url, err)+ }+ return h.auditPage(r.Context(), url, opts, routing.EffectiveCfg, targets)+ }++ report, err := audit.RunAudit(+ audit.AuditInput{URLs: req.URLs, SitemapURL: req.SitemapURL},+ audit.RunOptions{+ SampleSize: req.SampleSize,+ Concurrency: req.Concurrency,+ Page: req.Options.pageOptions(),+ },+ h.fetchSitemap(routing.EffectiveCfg),+ auditor,+ )+ if err != nil {+ httpx.Error(w, 400, err)+ return+ }+ httpx.JSON(w, 200, report)+}++// fetchSitemap returns a SitemapFetcher that applies the same URL/IDPI/SSRF+// validation as page navigation before fetching over plain HTTP.+func (h *Handlers) fetchSitemap(cfg *config.RuntimeConfig) audit.SitemapFetcher {+ return func(sitemapURL string) ([]string, error) {+ if _, err := h.validateAuditTarget(sitemapURL, cfg); err != nil {+ return nil, err+ }+ client := &http.Client{Timeout: 15 * time.Second}+ resp, err := client.Get(sitemapURL)+ if err != nil {+ return nil, fmt.Errorf("fetch sitemap: %w", err)+ }+ defer func() { _ = resp.Body.Close() }()+ if resp.StatusCode != http.StatusOK {+ return nil, fmt.Errorf("fetch sitemap: HTTP %d", resp.StatusCode)+ }+ data, err := io.ReadAll(io.LimitReader(resp.Body, maxSitemapBytes))+ if err != nil {+ return nil, fmt.Errorf("read sitemap: %w", err)+ }+ return audit.ParseSitemap(data)+ }+}diff --git a/internal/handlers/audit_page.go b/internal/handlers/audit_page.goindex 6627ed77..085886ae 100644--- a/internal/handlers/audit_page.go+++ b/internal/handlers/audit_page.go@@ -11,26 +11,27 @@ import ("github.com/pinchtab/pinchtab/internal/audit""github.com/pinchtab/pinchtab/internal/bridge""github.com/pinchtab/pinchtab/internal/bridge/observe"+ "github.com/pinchtab/pinchtab/internal/config""github.com/pinchtab/pinchtab/internal/httpx"+ "github.com/pinchtab/pinchtab/internal/navguard")const auditCollectTimeout = 60 * time.Second-type auditPageRequest struct {- URL string `json:"url"`- Options *struct {- Screenshot *bool `json:"screenshot"`- Network *bool `json:"network"`- Console *bool `json:"console"`- A11y *bool `json:"a11y"`- Timing *bool `json:"timing"`- Elements *bool `json:"elements"`- } `json:"options"`+// auditPageOptionsBody is the JSON options shape shared by POST /audit/page+// and POST /audit. Unset fields keep their defaults (all collectors on).+type auditPageOptionsBody struct {+ Screenshot *bool `json:"screenshot"`+ Network *bool `json:"network"`+ Console *bool `json:"console"`+ A11y *bool `json:"a11y"`+ Timing *bool `json:"timing"`+ Elements *bool `json:"elements"`}-func (req auditPageRequest) pageOptions() audit.PageOptions {+func (o *auditPageOptionsBody) pageOptions() audit.PageOptions {opts := audit.DefaultPageOptions()- if req.Options == nil {+ if o == nil {return opts}apply := func(dst *bool, src *bool) {@@ -38,15 +39,20 @@ func (req auditPageRequest) pageOptions() audit.PageOptions {*dst = *src}}- apply(&opts.Screenshot, req.Options.Screenshot)- apply(&opts.Network, req.Options.Network)- apply(&opts.Console, req.Options.Console)- apply(&opts.A11y, req.Options.A11y)- apply(&opts.Timing, req.Options.Timing)- apply(&opts.Elements, req.Options.Elements)+ apply(&opts.Screenshot, o.Screenshot)+ apply(&opts.Network, o.Network)+ apply(&opts.Console, o.Console)+ apply(&opts.A11y, o.A11y)+ apply(&opts.Timing, o.Timing)+ apply(&opts.Elements, o.Elements)return opts}+type auditPageRequest struct {+ URL string `json:"url"`+ Options *auditPageOptionsBody `json:"options"`+}+// @Endpoint POST /audit/pagefunc (h *Handlers) HandleAuditPage(w http.ResponseWriter, r *http.Request) {var req auditPageRequest@@ -72,14 +78,43 @@ func (h *Handlers) HandleAuditPage(w http.ResponseWriter, r *http.Request) {return}+ httpx.JSON(w, 200, h.auditPage(r.Context(), req.URL, req.Options.pageOptions(), routing.EffectiveCfg, targets))+}++// validateAuditTarget is the non-writing sibling of validateNavigateTargets+// for batch audits: the same URL/IDPI/SSRF validation, but failures come back+// as errors so the caller can turn them into per-page report entries.+func (h *Handlers) validateAuditTarget(url string, cfg *config.RuntimeConfig) (navTargets, error) {+ allowFile := cfg != nil && cfg.AllowFileScheme+ if err := validateNavigateURL(url, allowFile); err != nil {+ return navTargets{}, err+ }+ domainResult := h.IDPIGuard.CheckDomain(url)+ if domainResult.Blocked {+ return navTargets{}, fmt.Errorf("navigation blocked by IDPI: %s", domainResult.Reason)+ }+ if allowFile && navguard.IsFileURL(url) {+ return navTargets{target: &validatedNavigateTarget{AllowInternal: true}, trustedCIDRs: buildNavigateTrustedProxyCIDRs(cfg)}, nil+ }+ target, err := validateNavigateTarget(url, h.IDPIGuard.DomainAllowed(url), parseCIDRs(cfg.TrustedResolveCIDRs))+ if err != nil {+ return navTargets{}, err+ }+ return navTargets{target: target, trustedCIDRs: buildNavigateTrustedProxyCIDRs(cfg)}, nil+}++// auditPage navigates a fresh tab to url and assembles the single-page+// audit. Per-page failures are data, not crashes: navigation errors come+// back as a structured entry with the error field set. The tab is always+// closed before returning.+func (h *Handlers) auditPage(clientCtx context.Context, url string, opts audit.PageOptions, cfg *config.RuntimeConfig, targets navTargets) audit.PageAudit {tabID, tabCtx, _, err := h.Bridge.CreateTab("")if err != nil {- httpx.Error(w, 500, fmt.Errorf("new tab: %w", err))- return+ return audit.NewPageAuditError(url, fmt.Errorf("new tab: %w", err))}defer func() { _ = h.Bridge.CloseTab(tabID) }()- navTimeout := routing.EffectiveCfg.NavigateTimeout+ navTimeout := cfg.NavigateTimeoutif navTimeout <= 0 {navTimeout = 30 * time.Second}@@ -88,28 +123,23 @@ func (h *Handlers) HandleAuditPage(w http.ResponseWriter, r *http.Request) {navGuard, err := installNavigateRuntimeGuardWithBridge(h.Bridge, navCtx, navCancel, targets.target, targets.trustedCIDRs)if err != nil {- httpx.Error(w, 500, fmt.Errorf("navigation guard: %w", err))- return+ return audit.NewPageAuditError(url, fmt.Errorf("navigation guard: %w", err))}- // Per-page failures are data, not crashes: navigation errors come back- // as a structured entry with the error field set, never a 5xx.- if _, navErr := h.Bridge.Navigate(navCtx, req.URL, bridge.NavigateParams{MaxRedirects: routing.EffectiveCfg.MaxRedirects}); navErr != nil {+ if _, navErr := h.Bridge.Navigate(navCtx, url, bridge.NavigateParams{MaxRedirects: cfg.MaxRedirects}); navErr != nil {if navGuard != nil {if blockedErr := navGuard.blocked(); blockedErr != nil {navErr = blockedErr}}- httpx.JSON(w, 200, audit.NewPageAuditError(req.URL, navErr))- return+ return audit.NewPageAuditError(url, navErr)}// Chrome renders net-level failures (connection refused, DNS) as an// error page without failing the navigation; detect it and report the// underlying net error from the network capture as page data.if cur, urlErr := h.Bridge.CurrentURL(navCtx); urlErr == nil && strings.HasPrefix(cur, "chrome-error://") {- httpx.JSON(w, 200, audit.NewPageAuditError(req.URL, h.documentNetError(tabID, req.URL)))- return+ return audit.NewPageAuditError(url, h.documentNetError(tabID, url))}// Paint metrics only fire on visible pages.@@ -117,13 +147,12 @@ func (h *Handlers) HandleAuditPage(w http.ResponseWriter, r *http.Request) {cCtx, cCancel := context.WithTimeout(tabCtx, auditCollectTimeout)defer cCancel()- go httpx.CancelOnClientDone(r.Context(), cCancel)+ go httpx.CancelOnClientDone(clientCtx, cCancel)// Let late subresources (async fetches, images) land before collecting._, _ = observe.WaitForQuietWindow(cCtx, 500*time.Millisecond, 5*time.Second)- pageAudit := audit.EnrichPage(req.URL, req.pageOptions(), h.auditCollectors(cCtx, tabID))- httpx.JSON(w, 200, pageAudit)+ return audit.EnrichPage(url, opts, h.auditCollectors(cCtx, tabID))}// documentNetError recovers the document request's net error from thediff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.goindex efef1762..d45c2dff 100644--- a/internal/handlers/handlers.go+++ b/internal/handlers/handlers.go@@ -323,6 +323,7 @@ func (h *Handlers) bridgeBindings() []routeBinding {{pattern: "GET /timing", root: h.HandleTiming, tab: h.HandleTabTiming},{pattern: "GET /a11y/audit", root: h.HandleA11yAudit, tab: h.HandleTabA11yAudit},{pattern: "POST /audit/page", root: h.HandleAuditPage},+ {pattern: "POST /audit", root: h.HandleAudit},{pattern: "GET /network", root: h.HandleNetwork, tab: h.HandleTabNetwork},{pattern: "GET /network/stream", root: h.HandleNetworkStream, tab: h.HandleTabNetworkStream},{pattern: "GET /network/export", root: h.HandleNetworkExport, tab: h.HandleTabNetworkExport},diff --git a/internal/routes/routes.go b/internal/routes/routes.goindex 845386c8..2bcb3b46 100644--- a/internal/routes/routes.go+++ b/internal/routes/routes.go@@ -125,6 +125,7 @@ var coreEndpoints = []Endpoint{{"GET", "/timing", "Page timing and Core Web Vitals", CapNone, true},{"GET", "/a11y/audit", "Accessibility findings and score", CapNone, true},{"POST", "/audit/page", "Audit a single page with browser enrichment", CapNone, false},+ {"POST", "/audit", "Run a multi-page site audit", CapNone, false},{"GET", "/network", "Network log", CapNone, true},{"GET", "/network/stream", "Network SSE stream", CapNone, true},diff --git a/tests/e2e/scenarios/api/audit-basic.sh b/tests/e2e/scenarios/api/audit-basic.shnew file mode 100755index 00000000..1004c94a--- /dev/null+++ b/tests/e2e/scenarios/api/audit-basic.sh@@ -0,0 +1,81 @@+#!/bin/bash+# audit-basic.sh — POST /audit multi-page site audit runs.++GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+source "${GROUP_DIR}/../../helpers/api.sh"++# ─────────────────────────────────────────────────────────────────+start_test "url-list run returns a versioned AuditReport"++pt_post /audit -d "{\"urls\":[\"${FIXTURES_URL}/audit-site/index.html\",\"${FIXTURES_URL}/audit-site/clean.html\"]}"+assert_ok "audit two pages"+assert_json_exists "$RESULT" '.schemaVersion' "has schemaVersion"+assert_json_exists "$RESULT" '.generatedAt' "has generatedAt"+assert_json_length "$RESULT" '.pages' 2 "two page entries"+assert_json_contains "$RESULT" '.pages[0].url' "index.html" "entry URL first"+assert_json_exists "$RESULT" '.summaryScore' "has summaryScore"++end_test++# ─────────────────────────────────────────────────────────────────+start_test "sitemap mode discovers and audits >=10 pages"++pt_post /audit -d "{\"sitemapUrl\":\"${FIXTURES_URL}/audit-site/sitemap.xml\",\"options\":{\"screenshot\":false},\"concurrency\":3}"+assert_ok "audit from sitemap"+assert_json_length_gte "$RESULT" '.pages' 10 "at least 10 pages audited"++FAILED=$(echo "$RESULT" | jq '[.pages[] | select(.error)] | length')+if [ "$FAILED" -eq 0 ]; then+ pass_assert "no page entry has an error"+else+ fail_assert "no page entry has an error (got $FAILED: $(echo "$RESULT" | jq -c '[.pages[] | select(.error) | {url, error}]'))"+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "concurrency 3 and 1 audit the same URL set"++BODY_URLS="[\"${FIXTURES_URL}/audit-site/index.html\",\"${FIXTURES_URL}/audit-site/clean.html\",\"${FIXTURES_URL}/audit-site/products/p1.html\",\"${FIXTURES_URL}/audit-site/products/p2.html\",\"${FIXTURES_URL}/audit-site/products/p3.html\"]"++pt_post /audit -d "{\"urls\":${BODY_URLS},\"options\":{\"screenshot\":false},\"concurrency\":1}"+assert_ok "audit with concurrency 1"+SET_ONE=$(echo "$RESULT" | jq -S '[.pages[].url] | sort')++pt_post /audit -d "{\"urls\":${BODY_URLS},\"options\":{\"screenshot\":false},\"concurrency\":3}"+assert_ok "audit with concurrency 3"+SET_THREE=$(echo "$RESULT" | jq -S '[.pages[].url] | sort')++if [ "$SET_ONE" = "$SET_THREE" ]; then+ pass_assert "same page URL set for concurrency 1 and 3"+else+ fail_assert "URL sets differ: $SET_ONE vs $SET_THREE"+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "run with one unreachable URL completes with error entry"++pt_post /audit -d "{\"urls\":[\"${FIXTURES_URL}/audit-site/clean.html\",\"http://fixtures:9/down.html\"],\"options\":{\"screenshot\":false}}"+assert_ok "mixed run returns 200"+assert_json_length "$RESULT" '.pages' 2 "both pages present"++CLEAN_ERR=$(echo "$RESULT" | jq -r '.pages[0].error // empty')+if [ -z "$CLEAN_ERR" ]; then+ pass_assert "reachable page has no error"+else+ fail_assert "reachable page has no error (got: $CLEAN_ERR)"+fi++DOWN_ERR=$(echo "$RESULT" | jq -r '.pages[1].error // empty')+if [ -n "$DOWN_ERR" ]; then+ pass_assert "unreachable page carries error ($DOWN_ERR)"+else+ fail_assert "unreachable page carries error"+fi++pt_get /health+assert_ok "server healthy after mixed run"++end_testdiff --git a/tests/e2e/scenarios/cli/audit-cli-basic.sh b/tests/e2e/scenarios/cli/audit-cli-basic.shnew file mode 100755index 00000000..8dddd1ea--- /dev/null+++ b/tests/e2e/scenarios/cli/audit-cli-basic.sh@@ -0,0 +1,74 @@+#!/bin/bash+# audit-cli-basic.sh — pinchtab audit CLI happy path.++GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+source "${GROUP_DIR}/../../helpers/cli.sh"++OUT_DIR=$(mktemp -d /tmp/audit-cli.XXXXXX)++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab audit <url> --output-dir writes report and screenshots"++pt_ok audit "${FIXTURES_URL}/audit-site/index.html" --output-dir "$OUT_DIR"++REPORT="$OUT_DIR/report.json"+if [ -f "$REPORT" ]; then+ pass_assert "report.json exists"+else+ fail_assert "report.json exists"+fi++if jq -e '.schemaVersion' "$REPORT" >/dev/null 2>&1; then+ pass_assert "schemaVersion set ($(jq -r '.schemaVersion' "$REPORT"))"+else+ fail_assert "schemaVersion set"+fi++if jq -e '.pages | length == 1' "$REPORT" >/dev/null 2>&1; then+ pass_assert "one page entry"+else+ fail_assert "one page entry (got: $(jq '.pages | length' "$REPORT"))"+fi++if jq -e '.pages[0].browser.screenshotPath' "$REPORT" >/dev/null 2>&1; then+ pass_assert "page entry has screenshotPath"+else+ fail_assert "page entry has screenshotPath"+fi++PNG_COUNT=$(ls "$OUT_DIR/screenshots/"*.png 2>/dev/null | wc -l | tr -d ' ')+if [ "$PNG_COUNT" -ge 1 ]; then+ pass_assert "screenshots/*.png exist ($PNG_COUNT)"+else+ fail_assert "screenshots/*.png exist"+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "pinchtab audit --sitemap audits >=10 discovered pages"++pt_ok audit "${FIXTURES_URL}/audit-site/sitemap.xml" --sitemap --screenshot=false --concurrency 3 --json+PAGE_COUNT=$(echo "$PT_OUT" | jq '.pages | length' 2>/dev/null)+if [ "${PAGE_COUNT:-0}" -ge 10 ] 2>/dev/null; then+ pass_assert "audited $PAGE_COUNT pages from sitemap"+else+ fail_assert "audited >=10 pages from sitemap (got: $PAGE_COUNT)"+fi++end_test++# ─────────────────────────────────────────────────────────────────+start_test "run with unreachable URL still exits 0 with error entry"++pt_ok audit "http://fixtures:9/down.html" --screenshot=false --json+ERR=$(echo "$PT_OUT" | jq -r '.pages[0].error // empty' 2>/dev/null)+if [ -n "$ERR" ]; then+ pass_assert "page entry carries error ($ERR)"+else+ fail_assert "page entry carries error"+fi++end_test++rm -rf "$OUT_DIR"