fixup: address PR review — README, gofmt, cache schema version

Review feedback on #44:

- **Must fix #1: README.md stale.** Replaced the "no token cache"
  paragraph with the cache location ($XDG_CACHE_HOME), the
  CRONOMETER_NO_CACHE opt-out, the `auth logout` subcommand, and a
  security note ("treat session.json like a password").  Folds in the
  reviewer's nice-to-have #5 (security guidance) at the same time.

- **Must fix #2: gofmt.**  Ran `gofmt -w` on `cmd/format.go` and
  `internal/cronoclient/daterange_test.go` (trailing blank line + struct
  field alignment).  `internal/cronoapi/gwt.go` is also flagged but is
  pre-existing from #37 — landed as a separate chore commit so this
  PR's diff stays scoped to release-blocker work.

- **Nice-to-have #4: cache schema version.**  Added
  `cacheSchemaVersion = 1` and a `Version int` field on cachedSession.
  Old/mismatched versions are silently treated as a miss so a future
  incompatible bump triggers a transparent re-login instead of a
  JSON-shape error.  New test: TestSessionCacheVersionMismatch.

Skipped: race on concurrent fresh logins (#6) — reviewer agreed this is
fine for a single-user CLI.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DTTerastar

README.md

@@ -78,7 +78,17 @@ export CRONOMETER_USERNAME="you@example.com"
 export CRONOMETER_PASSWORD="your-cronometer-password"
 ```
 
-The CLI logs in on every invocation; there's no token cache. Cronometer doesn't (yet) offer SSO or API tokens for individuals, so a real password is the only auth option.
+Cronometer doesn't (yet) offer SSO or API tokens for individuals, so a real password is the only auth option.
+
+After the first successful login, the session (auth token + cookies) is cached at `$XDG_CACHE_HOME/crono-export/session.json` (file mode `0600`, directory mode `0700`; on macOS this resolves to `~/Library/Caches/crono-export/session.json`). Subsequent invocations reuse the cached session and skip the login handshake — useful for LLM-agent workflows that fire several commands in quick succession (a fresh login on every call trips Cronometer's "Too Many Attempts" throttle after ~6 requests). When the cached session goes stale, the CLI transparently re-logs in and retries once.
+
+Escape hatches:
+
+- `CRONOMETER_NO_CACHE=1` forces a fresh login on every invocation (and skips writing the cache).
+- `crono-export auth logout` deletes the cached session.
+- `crono-export auth status` reports whether credentials are set and whether a session is cached.
+
+Treat `session.json` like a password: don't sync it to a shared backup, and don't commit it.
 
 ## Usage
 

cmd/format.go

@@ -413,4 +413,3 @@ func pickKey(row map[string]any, candidates ...string) string {
 	}
 	return ""
 }
-

internal/cronoclient/daterange_test.go

@@ -10,10 +10,10 @@ func TestResolveDateRange(t *testing.T) {
 	day := func(y int, m time.Month, d int) time.Time { return time.Date(y, m, d, 0, 0, 0, 0, time.UTC) }
 
 	cases := []struct {
-		name              string
-		since, until      string
+		name               string
+		since, until       string
 		wantStart, wantEnd time.Time
-		wantEmpty         bool
+		wantEmpty          bool
 	}{
 		{
 			name:      "both empty defaults to 7d ending today",

internal/cronoclient/session.go

@@ -11,10 +11,16 @@ import (
 	"github.com/quantcli/crono-export-cli/internal/cronoapi"
 )
 
+// cacheSchemaVersion is bumped whenever the on-disk session shape
+// changes incompatibly.  An older cache is silently ignored (treated
+// as a miss) so existing users transparently re-login on upgrade.
+const cacheSchemaVersion = 1
+
 // cachedSession is the on-disk representation of a Cronometer login.
 // We key by username so flipping CRONOMETER_USERNAME invalidates the
 // cache automatically instead of replaying another user's session.
 type cachedSession struct {
+	Version   int              `json:"version"`
 	Username  string           `json:"username"`
 	Session   cronoapi.Session `json:"session"`
 	SavedAt   time.Time        `json:"saved_at"`
@@ -60,6 +66,9 @@ func loadCachedSession(user string) (*cachedSession, error) {
 	if err := json.Unmarshal(data, &s); err != nil {
 		return nil, nil
 	}
+	if s.Version != cacheSchemaVersion {
+		return nil, nil
+	}
 	if s.Username != user {
 		return nil, nil
 	}
@@ -81,6 +90,7 @@ func saveCachedSession(user string, snap cronoapi.Session) error {
 		return err
 	}
 	data, err := json.Marshal(cachedSession{
+		Version:  cacheSchemaVersion,
 		Username: user,
 		Session:  snap,
 		SavedAt:  time.Now(),

internal/cronoclient/session_test.go

@@ -3,6 +3,7 @@ package cronoclient
 import (
 	"net/http"
 	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/quantcli/crono-export-cli/internal/cronoapi"
@@ -64,3 +65,31 @@ func TestSessionCacheRoundTrip(t *testing.T) {
 		t.Errorf("delete-when-missing should be no-op, got %v", err)
 	}
 }
+
+// TestSessionCacheVersionMismatch confirms that a cache written under
+// a different schema version is silently treated as a miss, so a
+// future incompatible bump triggers a transparent re-login instead of
+// a JSON-shape error.
+func TestSessionCacheVersionMismatch(t *testing.T) {
+	tmp := t.TempDir()
+	t.Setenv("XDG_CACHE_HOME", tmp)
+	t.Setenv("HOME", tmp)
+
+	p := SessionCachePath()
+	if err := os.MkdirAll(filepath.Dir(p), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	// Hand-written cache pretending to be a future schema version.
+	body := `{"version":999,"username":"alice@example.com","session":{"user_id":1,"auth_token":"deadbeef","cookies":null}}`
+	if err := os.WriteFile(p, []byte(body), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := loadCachedSession("alice@example.com")
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if got != nil {
+		t.Errorf("expected nil cache for mismatched version, got %+v", got)
+	}
+}