Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat(cache): add cache clear command (#414)

Dataf924a3c279e5
diff --git a/cmd/pinchtab/cmd_cli_cache.go b/cmd/pinchtab/cmd_cli_cache.go
new file mode 100644
index 00000000..b0d3b9ab
--- /dev/null
+++ b/cmd/pinchtab/cmd_cli_cache.go
@@ -0,0 +1,39 @@
+package main
+
+import (
+ browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
+ "github.com/spf13/cobra"
+)
+
+var cacheCmd = &cobra.Command{
+ Use: "cache",
+ Short: "Manage browser cache",
+ Long: "Commands for managing the browser's HTTP disk cache.",
+}
+
+var cacheClearCmd = &cobra.Command{
+ Use: "clear",
+ Short: "Clear browser HTTP cache",
+ Long: "Clear the browser's HTTP disk cache. This affects all origins and ensures fresh resources are fetched on subsequent navigations.",
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.CacheClear(rt.client, rt.base, rt.token, cmd)
+ })
+ },
+}
+
+var cacheStatusCmd = &cobra.Command{
+ Use: "status",
+ Short: "Check cache status",
+ Long: "Check if the browser cache can be cleared.",
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.CacheStatus(rt.client, rt.base, rt.token, cmd)
+ })
+ },
+}
+
+func init() {
+ cacheCmd.AddCommand(cacheClearCmd)
+ cacheCmd.AddCommand(cacheStatusCmd)
+}
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index d3abc351..948df62c 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -44,6 +44,7 @@ func registerBrowserCommands() {
consoleCmd,
errorsCmd,
clipboardCmd,
+ cacheCmd,
)
tabsCmd.AddCommand(tabNewCmd, tabCloseCmd)
@@ -89,6 +90,7 @@ func registerBrowserCommands() {
consoleCmd,
errorsCmd,
clipboardCmd,
+ cacheCmd,
)
}
diff --git a/docs/commands.md b/docs/commands.md
index 4160a386..8c1c5bfd 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -131,6 +131,8 @@ pinchtab clipboard read # Read server-side clipboard text
pinchtab clipboard write <text> # Write clipboard text
pinchtab clipboard copy <text> # Alias for write
pinchtab clipboard paste # Alias for read
+pinchtab cache clear # Clear browser HTTP disk cache
+pinchtab cache status # Check if cache can be cleared
```
## Capture And Export
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 938eb56e..3c9e9488 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -214,6 +214,8 @@ GET /clipboard/read
POST /clipboard/write
POST /clipboard/copy
GET /clipboard/paste
+POST /cache/clear
+GET /cache/status
```
Notes:
diff --git a/docs/reference/cache.md b/docs/reference/cache.md
new file mode 100644
index 00000000..44885d4a
--- /dev/null
+++ b/docs/reference/cache.md
@@ -0,0 +1,55 @@
+# Cache
+
+Clear the browser's HTTP disk cache.
+
+## Clear Cache
+
+```bash
+curl -X POST http://localhost:9867/cache/clear
+# CLI Alternative
+pinchtab cache clear
+# Response
+{
+ "status": "cleared"
+}
+```
+
+## Check Status
+
+```bash
+curl http://localhost:9867/cache/status
+# CLI Alternative
+pinchtab cache status
+# Response
+{
+ "canClear": true
+}
+```
+
+## Notes
+
+- Clears the HTTP disk cache for all origins
+- Does not affect cookies, localStorage, or sessionStorage
+- Useful after app redeployments to ensure fresh JS/CSS bundles are fetched
+- Can be called without an active tab
+
+## Use Cases
+
+**After app redeployments:** When a Vite/webpack app is rebuilt with new JS bundle hashes, stale cached bundles can cause issues. Clear the cache to ensure fresh resources are fetched:
+
+```bash
+pinchtab cache clear
+pinchtab nav http://localhost:3000
+```
+
+**Debugging cache issues:** If you suspect cached resources are causing problems:
+
+```bash
+pinchtab cache clear
+pinchtab reload
+```
+
+## Related Pages
+
+- [Navigate](./navigate.md)
+- [Profiles](./profiles.md)
diff --git a/internal/bridge/api.go b/internal/bridge/api.go
index 2d6c1f1a..5beb79c4 100644
--- a/internal/bridge/api.go
+++ b/internal/bridge/api.go
@@ -61,6 +61,10 @@ type BridgeAPI interface {
ClearConsoleLogs(tabID string)
GetErrorLogs(tabID string, limit int) []ErrorEntry
ClearErrorLogs(tabID string)
+
+ // Cache management
+ ClearCache(ctx context.Context) error
+ CanClearCache(ctx context.Context) (bool, error)
}
type LockInfo = bridgetabs.LockInfo
diff --git a/internal/bridge/cache.go b/internal/bridge/cache.go
new file mode 100644
index 00000000..e10acc3c
--- /dev/null
+++ b/internal/bridge/cache.go
@@ -0,0 +1,30 @@
+package bridge
+
+import (
+ "context"
+
+ "github.com/chromedp/chromedp"
+)
+
+// ClearCache clears the browser's HTTP disk cache.
+// This affects all origins and does not require an active tab.
+func (b *Bridge) ClearCache(ctx context.Context) error {
+ return chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
+ return chromedp.FromContext(ctx).Target.Execute(ctx, "Network.clearBrowserCache", nil, nil)
+ }))
+}
+
+// CanClearCache checks if the browser cache can be cleared.
+// This is a legacy CDP method that always returns true in modern Chrome.
+func (b *Bridge) CanClearCache(ctx context.Context) (bool, error) {
+ var result struct {
+ Result bool `json:"result"`
+ }
+ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
+ return chromedp.FromContext(ctx).Target.Execute(ctx, "Network.canClearBrowserCache", nil, &result)
+ }))
+ if err != nil {
+ return false, err
+ }
+ return result.Result, nil
+}
diff --git a/internal/bridge/cache_test.go b/internal/bridge/cache_test.go
new file mode 100644
index 00000000..adda7054
--- /dev/null
+++ b/internal/bridge/cache_test.go
@@ -0,0 +1,28 @@
+package bridge
+
+import (
+ "context"
+ "testing"
+)
+
+func TestClearCache_RequiresContext(t *testing.T) {
+ b := &Bridge{}
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel() // immediately cancel
+
+ err := b.ClearCache(ctx)
+ if err == nil {
+ t.Error("expected error with cancelled context")
+ }
+}
+
+func TestCanClearCache_RequiresContext(t *testing.T) {
+ b := &Bridge{}
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel() // immediately cancel
+
+ _, err := b.CanClearCache(ctx)
+ if err == nil {
+ t.Error("expected error with cancelled context")
+ }
+}
diff --git a/internal/cli/actions/actions_cache.go b/internal/cli/actions/actions_cache.go
new file mode 100644
index 00000000..53174379
--- /dev/null
+++ b/internal/cli/actions/actions_cache.go
@@ -0,0 +1,39 @@
+package actions
+
+import (
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "os"
+
+ "github.com/pinchtab/pinchtab/internal/cli/apiclient"
+ "github.com/spf13/cobra"
+)
+
+// CacheClear clears the browser's HTTP disk cache.
+func CacheClear(client *http.Client, base, token string, cmd *cobra.Command) {
+ // DoPost already prints the JSON response
+ result := apiclient.DoPost(client, base, token, "/cache/clear", nil)
+ if result == nil {
+ fmt.Fprintln(os.Stderr, "Failed to clear cache")
+ os.Exit(1)
+ }
+}
+
+// CacheStatus checks if the browser cache can be cleared.
+func CacheStatus(client *http.Client, base, token string, cmd *cobra.Command) {
+ result := apiclient.DoGetRaw(client, base, token, "/cache/status", nil)
+ if result == nil {
+ fmt.Fprintln(os.Stderr, "Failed to get cache status")
+ os.Exit(1)
+ }
+
+ var buf map[string]any
+ if err := json.Unmarshal(result, &buf); err != nil {
+ fmt.Fprintf(os.Stderr, "Failed to parse response: %v\n", err)
+ os.Exit(1)
+ }
+
+ out, _ := json.MarshalIndent(buf, "", " ")
+ fmt.Println(string(out))
+}
diff --git a/internal/handlers/cache.go b/internal/handlers/cache.go
new file mode 100644
index 00000000..01a1afee
--- /dev/null
+++ b/internal/handlers/cache.go
@@ -0,0 +1,47 @@
+package handlers
+
+import (
+ "fmt"
+ "net/http"
+
+ "github.com/pinchtab/pinchtab/internal/httpx"
+)
+
+// HandleCacheClear clears the browser's HTTP disk cache.
+// POST /cache/clear
+func (h *Handlers) HandleCacheClear(w http.ResponseWriter, r *http.Request) {
+ if err := h.ensureChrome(); err != nil {
+ httpx.Error(w, http.StatusServiceUnavailable, err)
+ return
+ }
+
+ if err := h.Bridge.ClearCache(r.Context()); err != nil {
+ if h.writeBridgeUnavailable(w, err) {
+ return
+ }
+ httpx.Error(w, http.StatusInternalServerError, fmt.Errorf("clear cache: %w", err))
+ return
+ }
+
+ httpx.JSON(w, http.StatusOK, map[string]any{"status": "cleared"})
+}
+
+// HandleCacheStatus checks if the browser cache can be cleared.
+// GET /cache/status
+func (h *Handlers) HandleCacheStatus(w http.ResponseWriter, r *http.Request) {
+ if err := h.ensureChrome(); err != nil {
+ httpx.Error(w, http.StatusServiceUnavailable, err)
+ return
+ }
+
+ canClear, err := h.Bridge.CanClearCache(r.Context())
+ if err != nil {
+ if h.writeBridgeUnavailable(w, err) {
+ return
+ }
+ httpx.Error(w, http.StatusInternalServerError, fmt.Errorf("cache status: %w", err))
+ return
+ }
+
+ httpx.JSON(w, http.StatusOK, map[string]any{"canClear": canClear})
+}
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
index ee7ab02d..9da2d984 100644
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -221,6 +221,8 @@ func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {
w.Header().Set("Content-Type", "text/html; charset=utf-8")
_, _ = w.Write([]byte(assets.WelcomeHTML))
})
+ mux.HandleFunc("POST /cache/clear", h.HandleCacheClear)
+ mux.HandleFunc("GET /cache/status", h.HandleCacheStatus)
if h.Profiles != nil {
h.Profiles.RegisterHandlers(mux)
diff --git a/tests/e2e/scenarios-cli/cache-basic.sh b/tests/e2e/scenarios-cli/cache-basic.sh
new file mode 100755
index 00000000..fc1e8ec6
--- /dev/null
+++ b/tests/e2e/scenarios-cli/cache-basic.sh
@@ -0,0 +1,31 @@
+#!/bin/bash
+# cache-basic.sh — CLI cache management scenarios.
+
+GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${GROUP_DIR}/../helpers/cli.sh"
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab cache clear"
+
+pt_ok nav "${FIXTURES_URL}/form.html"
+pt_ok cache clear
+assert_output_contains "cleared" "cache clear response"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab cache status"
+
+pt_ok cache status
+assert_json_field ".canClear" "true" "cache can be cleared"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "pinchtab cache clear is idempotent"
+
+pt_ok cache clear
+pt_ok cache clear
+assert_output_contains "cleared" "cache clear works multiple times"
+
+end_test