Skip to content

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

fix(cli): remember a shown advisory across runs, so the most-run command stops repeating advice about a state the caller chose (PIN-297)

Luigi Agostie3bb865772ac
diff --git a/cmd/pinchtab/tab_state.go b/cmd/pinchtab/tab_state.go
index 554fd9d3..2c970b9d 100644
--- a/cmd/pinchtab/tab_state.go
+++ b/cmd/pinchtab/tab_state.go
@@ -9,6 +9,7 @@ import (
"time"
"github.com/pinchtab/pinchtab/internal/cli/apiclient"
+ "github.com/pinchtab/pinchtab/internal/cli/clistate"
"github.com/spf13/cobra"
)
@@ -43,15 +44,7 @@ func (s tabStateStore) path() string {
return s.dir() + "/current-tab-" + s.serverSlug()
}
-func (tabStateStore) dir() string {
- if dir := os.Getenv("XDG_STATE_HOME"); dir != "" {
- return dir + "/pinchtab"
- }
- if home, err := os.UserHomeDir(); err == nil {
- return home + "/.local/state/pinchtab"
- }
- return "/tmp/pinchtab"
-}
+func (tabStateStore) dir() string { return clistate.Dir() }
// serverSlug turns the resolved base URL into a filename-safe identity. It stays
// readable (127.0.0.1-9930) so an operator can tell which server a state file
diff --git a/internal/cli/actions/advisory_hint_test.go b/internal/cli/actions/advisory_hint_test.go
index ccb52e98..30c9f0f1 100644
--- a/internal/cli/actions/advisory_hint_test.go
+++ b/internal/cli/actions/advisory_hint_test.go
@@ -27,6 +27,10 @@ func anonymousCaller(t *testing.T) {
t.Helper()
t.Setenv("PINCHTAB_SESSION", "")
t.Setenv("PINCHTAB_AGENT_ID", "")
+ // Advisories are remembered under the CLI state directory, so a test that does
+ // not move it would silence itself on its second run and write to the machine
+ // it runs on.
+ t.Setenv("XDG_STATE_HOME", t.TempDir())
output.ResetAdvisories()
t.Cleanup(output.ResetAdvisories)
}
diff --git a/internal/cli/clistate/clistate.go b/internal/cli/clistate/clistate.go
new file mode 100644
index 00000000..1c90353c
--- /dev/null
+++ b/internal/cli/clistate/clistate.go
@@ -0,0 +1,22 @@
+// Package clistate owns where the CLI keeps its own local state: the current-tab
+// file, the advisory markers, and whatever comes next. One resolver, so two
+// features cannot disagree about which directory an operator has to clear.
+package clistate
+
+import (
+ "os"
+ "path/filepath"
+)
+
+// Dir is the CLI's state directory. It is not the server's stateDir: this is
+// per-user, per-machine scratch that belongs to the command line itself, so it
+// follows the XDG state convention and falls back to a path that always exists.
+func Dir() string {
+ if dir := os.Getenv("XDG_STATE_HOME"); dir != "" {
+ return filepath.Join(dir, "pinchtab")
+ }
+ if home, err := os.UserHomeDir(); err == nil {
+ return filepath.Join(home, ".local", "state", "pinchtab")
+ }
+ return filepath.Join(os.TempDir(), "pinchtab")
+}
diff --git a/internal/cli/output/advisory.go b/internal/cli/output/advisory.go
index 38654405..36179e44 100644
--- a/internal/cli/output/advisory.go
+++ b/internal/cli/output/advisory.go
@@ -1,9 +1,14 @@
package output
import (
+ "crypto/sha256"
+ "encoding/hex"
"os"
+ "path/filepath"
"strings"
"sync"
+
+ "github.com/pinchtab/pinchtab/internal/cli/clistate"
)
// HintsEnv silences advisory hints when it is set to HintsOff. It is the only
@@ -15,10 +20,15 @@ const (
)
// SilenceAdvisoryHint is printed once beside the first advisory of a run, so the
-// switch is discoverable from the output it silences. It ends with the command,
-// because its readers lift the last words of a hint verbatim.
+// switch is discoverable from the output it silences. It is printed BEFORE the
+// advisory: both lines end with a command, and their readers lift the last one on
+// the block, which must be the advisory's own remedy rather than the switch.
const SilenceAdvisoryHint = "silence advisory hints like this one: export " + HintsEnv + "=" + HintsOff
+// advisoryMarkerDir holds one empty file per advisory already shown on this
+// machine, named by the digest of its text.
+const advisoryMarkerDir = "advisories"
+
var (
advisoryMu sync.Mutex
advisoryShown = map[string]bool{}
@@ -27,8 +37,9 @@ var (
// Advisory prints a hint about a steady state the caller may have chosen — one
// whose wording is identical on every invocation and whose remedy is a decision,
-// not a reaction. It prints at most once per process and not at all when the
-// caller has silenced hints.
+// not a reaction. It prints once per install, not once per run: a CLI invocation
+// is its own process, so an in-memory guard alone would repeat the same advice on
+// every command forever. Nothing prints when the caller has silenced hints.
//
// A hint that reports what just happened is not advisory: it belongs on Hint,
// which prints every time it fires, because the second occurrence is news too.
@@ -44,13 +55,14 @@ func Advisory(text string) {
silencerShown = silencerShown || first
advisoryMu.Unlock()
- if !first {
+ if !first || advisoryAlreadyShown(text) {
return
}
- Hint(text)
if withSilencer {
Hint(SilenceAdvisoryHint)
}
+ Hint(text)
+ recordAdvisoryShown(text)
}
// AdvisoriesSilenced reports whether the caller has switched advisory hints off.
@@ -58,11 +70,44 @@ func AdvisoriesSilenced() bool {
return strings.EqualFold(strings.TrimSpace(os.Getenv(HintsEnv)), HintsOff)
}
-// ResetAdvisories forgets what this process has already said, for a test that
-// needs a fresh run and for any host that reuses one process across sessions.
+// ResetAdvisories forgets what has already been said, in this process and on
+// disk, so a test — or an operator who wants the advice back — starts from a
+// genuinely fresh install.
func ResetAdvisories() {
advisoryMu.Lock()
advisoryShown = map[string]bool{}
silencerShown = false
advisoryMu.Unlock()
+ _ = os.RemoveAll(filepath.Join(clistate.Dir(), advisoryMarkerDir))
+}
+
+// advisoryAlreadyShown reports whether this text has been printed on an earlier
+// run. Marker I/O never decides anything but suppression: an unreadable state
+// directory answers false, which prints, and printing twice is the behaviour this
+// mechanism improves on rather than a failure of the command.
+func advisoryAlreadyShown(text string) bool {
+ _, err := os.Stat(advisoryMarkerPath(text))
+ return err == nil
+}
+
+// recordAdvisoryShown is best-effort for the same reason: a caller who cannot
+// write the marker keeps hearing the advice, which is the old behaviour, and
+// never sees an error about a hint.
+func recordAdvisoryShown(text string) {
+ path := advisoryMarkerPath(text)
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ return
+ }
+ if file, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY, 0o644); err == nil {
+ _ = file.Close()
+ }
+}
+
+// advisoryMarkerPath keys the marker by the digest of the text, exactly as the
+// in-process map is keyed by the text itself: a new advisory is never
+// pre-suppressed by an unrelated one that already fired, and rewording an
+// advisory makes it new, which is what a changed message deserves.
+func advisoryMarkerPath(text string) string {
+ digest := sha256.Sum256([]byte(text))
+ return filepath.Join(clistate.Dir(), advisoryMarkerDir, hex.EncodeToString(digest[:])+".shown")
}
diff --git a/internal/cli/output/advisory_test.go b/internal/cli/output/advisory_test.go
new file mode 100644
index 00000000..c5252081
--- /dev/null
+++ b/internal/cli/output/advisory_test.go
@@ -0,0 +1,180 @@
+package output
+
+import (
+ "bytes"
+ "io"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+func captureStderr(t *testing.T, fn func()) string {
+ t.Helper()
+
+ old := os.Stderr
+ reader, writer, err := os.Pipe()
+ if err != nil {
+ t.Fatalf("os.Pipe: %v", err)
+ }
+ os.Stderr = writer
+
+ var buf bytes.Buffer
+ done := make(chan struct{})
+ go func() {
+ _, _ = io.Copy(&buf, reader)
+ close(done)
+ }()
+
+ fn()
+
+ _ = writer.Close()
+ os.Stderr = old
+ <-done
+ _ = reader.Close()
+ return buf.String()
+}
+
+// isolatedInstall points the CLI state directory at a temp dir, so a test never
+// reads or writes the markers of the machine it runs on.
+func isolatedInstall(t *testing.T) {
+ t.Helper()
+ t.Setenv("XDG_STATE_HOME", t.TempDir())
+ t.Setenv(HintsEnv, "")
+ ResetAdvisories()
+}
+
+// nextInvocation is the whole point of this card in one helper: a `pinchtab`
+// command is its own process, so the next run starts with an empty in-process map
+// and the SAME state directory. Only the marker can suppress anything here — the
+// in-memory guard is gone the moment the process exits.
+func nextInvocation() {
+ advisoryMu.Lock()
+ advisoryShown = map[string]bool{}
+ silencerShown = false
+ advisoryMu.Unlock()
+}
+
+const testAdvisory = "this tab is shared — no agent session is set: export PINCHTAB_SESSION=$(pinchtab session create --agent-id <id>)"
+
+// The filed defect: every invocation of the most-run command reprinted the same
+// advice about a steady state the caller had already chosen, because the guard
+// lived only in the process that printed it.
+func TestAnAdvisoryPrintedOnceIsNotRepeatedByALaterRun(t *testing.T) {
+ isolatedInstall(t)
+
+ first := captureStderr(t, func() { Advisory(testAdvisory) })
+ if !strings.Contains(first, testAdvisory) {
+ t.Fatalf("the first run printed no advisory: %q", first)
+ }
+
+ nextInvocation()
+ second := captureStderr(t, func() { Advisory(testAdvisory) })
+ if second != "" {
+ t.Errorf("a later run reprinted the advisory: %q", second)
+ }
+
+ nextInvocation()
+ third := captureStderr(t, func() { Advisory(testAdvisory) })
+ if third != "" {
+ t.Errorf("a third run reprinted the advisory: %q", third)
+ }
+}
+
+// The switch has to stay discoverable from the output it silences, and it has to
+// come first: both lines end with a command, and an agent reading the block lifts
+// the last one — which must be the advisory's own remedy, not the way to mute it.
+func TestTheFirstRunPublishesTheSwitchBeforeTheAdvisory(t *testing.T) {
+ isolatedInstall(t)
+
+ out := captureStderr(t, func() { Advisory(testAdvisory) })
+
+ switchAt := strings.Index(out, SilenceAdvisoryHint)
+ adviceAt := strings.Index(out, testAdvisory)
+ if switchAt < 0 || adviceAt < 0 {
+ t.Fatalf("the first run must carry both lines, got %q", out)
+ }
+ if switchAt > adviceAt {
+ t.Errorf("the silencer is printed after the advisory, so the last command in the block mutes the hint instead of following it:\n%s", out)
+ }
+ if !strings.HasSuffix(strings.TrimSpace(SilenceAdvisoryHint), HintsEnv+"="+HintsOff) {
+ t.Errorf("the switch must end its own line so it can be lifted verbatim: %q", SilenceAdvisoryHint)
+ }
+}
+
+// A marker is a suppression, never a dependency: if it cannot be written the
+// caller hears the advice again, which is the behaviour this replaces, and the
+// command itself is untouched.
+func TestAnUnwritableStateDirectoryFallsBackToPrinting(t *testing.T) {
+ if os.Geteuid() == 0 {
+ t.Skip("root writes through the permission this test relies on")
+ }
+ isolatedInstall(t)
+
+ readOnly := filepath.Join(t.TempDir(), "state")
+ if err := os.MkdirAll(readOnly, 0o500); err != nil {
+ t.Fatal(err)
+ }
+ t.Setenv("XDG_STATE_HOME", readOnly)
+
+ first := captureStderr(t, func() { Advisory(testAdvisory) })
+ if !strings.Contains(first, testAdvisory) {
+ t.Fatalf("nothing printed under an unwritable state directory: %q", first)
+ }
+
+ nextInvocation()
+ second := captureStderr(t, func() { Advisory(testAdvisory) })
+ if !strings.Contains(second, testAdvisory) {
+ t.Errorf("the advisory was suppressed although no marker could be written: %q", second)
+ }
+}
+
+// Suppression is keyed per text, exactly as the in-process map is, so shipping a
+// second advisory does not arrive pre-silenced by the first.
+func TestASecondAdvisoryIsNotSuppressedByTheFirst(t *testing.T) {
+ isolatedInstall(t)
+
+ const other = "a different steady state: export PINCHTAB_SOMETHING=1"
+ captureStderr(t, func() { Advisory(testAdvisory) })
+
+ nextInvocation()
+ out := captureStderr(t, func() { Advisory(other) })
+ if !strings.Contains(out, other) {
+ t.Errorf("an advisory that has never been shown was suppressed: %q", out)
+ }
+}
+
+// ResetAdvisories has to reach the marker too, or a test asking for a fresh run
+// gets a machine that has already heard everything.
+func TestResetAdvisoriesClearsThePersistedMarker(t *testing.T) {
+ isolatedInstall(t)
+
+ captureStderr(t, func() { Advisory(testAdvisory) })
+ if _, err := os.Stat(advisoryMarkerPath(testAdvisory)); err != nil {
+ t.Fatalf("the first run wrote no marker (%v), so the reset below would prove nothing", err)
+ }
+
+ ResetAdvisories()
+ if _, err := os.Stat(advisoryMarkerPath(testAdvisory)); err == nil {
+ t.Error("the marker survived ResetAdvisories")
+ }
+ out := captureStderr(t, func() { Advisory(testAdvisory) })
+ if !strings.Contains(out, testAdvisory) {
+ t.Errorf("after a reset the advisory stayed silent: %q", out)
+ }
+}
+
+// The switch still wins over everything: a caller who has already opted out hears
+// nothing on the very first run, and no marker is written to suppress a hint they
+// may want back once they unset it.
+func TestSilencedAdvisoriesPrintNothingAndRecordNothing(t *testing.T) {
+ isolatedInstall(t)
+ t.Setenv(HintsEnv, HintsOff)
+
+ if out := captureStderr(t, func() { Advisory(testAdvisory) }); out != "" {
+ t.Fatalf("hints are silenced but something printed: %q", out)
+ }
+ if _, err := os.Stat(advisoryMarkerPath(testAdvisory)); err == nil {
+ t.Error("a silenced advisory recorded itself as shown, so unsetting the switch would still say nothing")
+ }
+}