Merge pull request #1311 from entireio/read-v1.1

Add checkpoints v1.1 support to entire explain

Author: computermode

cmd/entire/cli/checkpoint/committed.go

@@ -1781,13 +1781,18 @@ func (s *GitStore) getFetchingTree(ctx context.Context) (*FetchingTree, error) {
 	return NewFetchingTree(ctx, tree, s.repo.Storer, s.blobFetcher), nil
 }
 
-// getSessionsBranchTree returns the tree object for the entire/checkpoints/v1 branch.
-// Falls back to origin/entire/checkpoints/v1 if the local branch doesn't exist.
+// getSessionsBranchTree returns the tree object for the configured committed
+// ref (the v1 branch by default, or the v1.1 custom ref for v1.1 read stores).
+// For the default v1 branch it falls back to origin/entire/checkpoints/v1 when
+// the local branch is missing; the v1.1 custom ref is local-only, so no remote
+// fallback applies there.
 func (s *GitStore) getSessionsBranchTree() (*object.Tree, error) {
-	refName := plumbing.NewBranchReferenceName(paths.MetadataBranchName)
-	ref, err := s.repo.Reference(refName, true)
+	ref, err := s.repo.Reference(s.committedReadRef, true)
 	if err != nil {
-		// Local branch doesn't exist, try remote-tracking branch
+		if s.committedReadRef != defaultCommittedReadRef() {
+			return nil, fmt.Errorf("sessions ref %s not found: %w", s.committedReadRef, err)
+		}
+		// Local v1 branch doesn't exist, try remote-tracking branch
 		remoteRefName := plumbing.NewRemoteReferenceName("origin", paths.MetadataBranchName)
 		ref, err = s.repo.Reference(remoteRefName, true)
 		if err != nil {
@@ -2193,11 +2198,12 @@ type Author struct {
 	Email string
 }
 
-// GetCheckpointAuthor retrieves the author of a checkpoint from the entire/checkpoints/v1 commit history.
+// GetCheckpointAuthor retrieves the author of a checkpoint from the configured
+// committed-read ref history.
 // Finds the commit whose subject matches "Checkpoint: <id>" and returns its author.
 // Returns empty Author if the checkpoint is not found or the sessions branch doesn't exist.
 func (s *GitStore) GetCheckpointAuthor(ctx context.Context, checkpointID id.CheckpointID) (Author, error) {
-	return getCheckpointAuthorFromRef(ctx, s.repo, plumbing.NewBranchReferenceName(paths.MetadataBranchName), checkpointID)
+	return getCheckpointAuthorFromRef(ctx, s.repo, s.committedReadRef, checkpointID)
 }
 
 func getCheckpointAuthorFromRef(ctx context.Context, repo *git.Repository, refName plumbing.ReferenceName, checkpointID id.CheckpointID) (Author, error) {

cmd/entire/cli/checkpoint/committed_read_store.go

@@ -0,0 +1,121 @@
+package checkpoint
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+
+	"github.com/go-git/go-git/v6"
+	"github.com/go-git/go-git/v6/plumbing"
+
+	"github.com/entireio/cli/cmd/entire/cli/logging"
+	"github.com/entireio/cli/cmd/entire/cli/paths"
+	"github.com/entireio/cli/cmd/entire/cli/settings"
+)
+
+// NewCommittedReadStore returns a GitStore for reading committed checkpoints:
+// the local-only v1.1 custom ref when checkpoints_version 1.1 is enabled (no v1
+// fallback), else the v1 branch.
+func NewCommittedReadStore(ctx context.Context, repo *git.Repository) *GitStore {
+	if !settings.MirrorsToV1CustomRef(ctx) {
+		return NewGitStore(repo)
+	}
+	return NewGitStoreWithRef(repo, plumbing.ReferenceName(paths.MetadataRefName))
+}
+
+// SyncCommittedReadRef advances the v1.1 custom ref to the v1 tip before a read,
+// a no-op unless checkpoints_version 1.1 is enabled. The ref is local-only, so a
+// git pull updates v1 but not v1.1; this keeps it current. Best-effort.
+func SyncCommittedReadRef(ctx context.Context, repo *git.Repository) {
+	if !settings.MirrorsToV1CustomRef(ctx) {
+		return
+	}
+	syncV1CustomRefForRead(ctx, repo)
+}
+
+// syncV1CustomRefForRead advances the v1.1 custom ref to the v1 tip (local v1
+// branch, or origin's on a fresh clone): seed when missing, advance when an
+// ancestor, no-op when equal, leave a diverged ref as-is. Failures are logged.
+func syncV1CustomRefForRead(ctx context.Context, repo *git.Repository) {
+	v1Hash, ok := resolveV1Tip(repo)
+	if !ok {
+		logging.Debug(ctx, "v1.1 read sync skipped: no v1 tip available")
+		return
+	}
+
+	customRefName := plumbing.ReferenceName(paths.MetadataRefName)
+	customRef, err := repo.Reference(customRefName, false)
+	if errors.Is(err, plumbing.ErrReferenceNotFound) {
+		setCustomRef(ctx, repo, customRefName, v1Hash) // missing — seed at v1 tip
+		return
+	}
+	if err != nil {
+		// Unexpected read error — don't overwrite the ref; read it as-is.
+		logging.Warn(ctx, "v1.1 read sync skipped: custom ref unreadable",
+			slog.String("ref", paths.MetadataRefName),
+			slog.String("error", err.Error()))
+		return
+	}
+
+	if customRef.Hash() == v1Hash {
+		return // already current
+	}
+
+	customCommit, err := repo.CommitObject(customRef.Hash())
+	if err != nil {
+		logging.Warn(ctx, "v1.1 read sync skipped: custom ref commit unreadable",
+			slog.String("ref", paths.MetadataRefName),
+			slog.String("error", err.Error()))
+		return
+	}
+	v1Commit, err := repo.CommitObject(v1Hash)
+	if err != nil {
+		logging.Warn(ctx, "v1.1 read sync skipped: v1 commit unreadable",
+			slog.String("error", err.Error()))
+		return
+	}
+
+	isAncestor, err := customCommit.IsAncestor(v1Commit)
+	if err != nil {
+		logging.Warn(ctx, "v1.1 read sync skipped: ancestry check failed",
+			slog.String("error", err.Error()))
+		return
+	}
+	if !isAncestor {
+		// Diverged from v1: leave the ref untouched and read it as-is.
+		logging.Warn(ctx, "v1.1 custom ref diverged from v1; reading custom ref as-is",
+			slog.String("ref", paths.MetadataRefName),
+			slog.String("custom_hash", customRef.Hash().String()),
+			slog.String("v1_hash", v1Hash.String()))
+		return
+	}
+
+	setCustomRef(ctx, repo, customRefName, v1Hash)
+}
+
+// resolveV1Tip returns the v1 metadata tip, preferring the local v1 branch and
+// falling back to origin's remote-tracking branch (so v1.1 can seed on a fresh
+// clone).
+func resolveV1Tip(repo *git.Repository) (plumbing.Hash, bool) {
+	if ref, err := repo.Reference(plumbing.NewBranchReferenceName(paths.MetadataBranchName), true); err == nil {
+		return ref.Hash(), true
+	}
+	if ref, err := repo.Reference(plumbing.NewRemoteReferenceName("origin", paths.MetadataBranchName), true); err == nil {
+		return ref.Hash(), true
+	}
+	return plumbing.ZeroHash, false
+}
+
+// setCustomRef points refName at hash; failures are logged and swallowed so the
+// read can proceed against the ref as-is.
+func setCustomRef(ctx context.Context, repo *git.Repository, refName plumbing.ReferenceName, hash plumbing.Hash) {
+	if err := repo.Storer.SetReference(plumbing.NewHashReference(refName, hash)); err != nil {
+		logging.Warn(ctx, "v1.1 read sync failed to advance custom ref",
+			slog.String("ref", refName.String()),
+			slog.String("error", err.Error()))
+		return
+	}
+	logging.Debug(ctx, "v1.1 custom ref synced for read",
+		slog.String("ref", refName.String()),
+		slog.String("hash", hash.String()))
+}

cmd/entire/cli/checkpoint/committed_read_store_test.go

@@ -0,0 +1,226 @@
+package checkpoint
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	git "github.com/go-git/go-git/v6"
+	"github.com/go-git/go-git/v6/plumbing"
+	"github.com/go-git/go-git/v6/plumbing/object"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
+	"github.com/entireio/cli/cmd/entire/cli/paths"
+	"github.com/entireio/cli/cmd/entire/cli/testutil"
+	"github.com/entireio/cli/redact"
+)
+
+// newTestRepo creates an isolated repo with a single "init" commit and returns
+// its directory, an open handle, and the commit hash.
+func newTestRepo(t *testing.T) (string, *git.Repository, plumbing.Hash) {
+	t.Helper()
+	dir := t.TempDir()
+	testutil.InitRepo(t, dir)
+	repo, err := git.PlainOpen(dir)
+	require.NoError(t, err)
+	return dir, repo, commitFile(t, repo, dir, "f.txt", "init", "init")
+}
+
+// commitFile commits content to path; successive calls build a linear chain.
+func commitFile(t *testing.T, repo *git.Repository, dir, path, content, msg string) plumbing.Hash {
+	t.Helper()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, path), []byte(content), 0o644))
+	wt, err := repo.Worktree()
+	require.NoError(t, err)
+	_, err = wt.Add(path)
+	require.NoError(t, err)
+	h, err := wt.Commit(msg, &git.CommitOptions{Author: &object.Signature{Name: "Test", Email: "test@test.com"}})
+	require.NoError(t, err)
+	return h
+}
+
+func setRef(t *testing.T, repo *git.Repository, name plumbing.ReferenceName, hash plumbing.Hash) {
+	t.Helper()
+	require.NoError(t, repo.Storer.SetReference(plumbing.NewHashReference(name, hash)))
+}
+
+func v1BranchRef() plumbing.ReferenceName {
+	return plumbing.NewBranchReferenceName(paths.MetadataBranchName)
+}
+func customRef() plumbing.ReferenceName { return plumbing.ReferenceName(paths.MetadataRefName) }
+func originV1Ref() plumbing.ReferenceName {
+	return plumbing.NewRemoteReferenceName("origin", paths.MetadataBranchName)
+}
+
+func customRefHash(t *testing.T, repo *git.Repository) (plumbing.Hash, bool) {
+	t.Helper()
+	ref, err := repo.Reference(customRef(), true)
+	if err != nil {
+		return plumbing.ZeroHash, false
+	}
+	return ref.Hash(), true
+}
+
+// writeV1Checkpoint writes a committed checkpoint to the v1 branch.
+func writeV1Checkpoint(t *testing.T, repo *git.Repository, cpID id.CheckpointID) {
+	t.Helper()
+	require.NoError(t, NewGitStore(repo).WriteCommitted(context.Background(), WriteCommittedOptions{
+		CheckpointID: cpID,
+		SessionID:    "session",
+		Strategy:     "manual-commit",
+		Transcript:   redact.AlreadyRedacted([]byte("transcript\n")),
+		Prompts:      []string{"prompt"},
+		AuthorName:   "Test",
+		AuthorEmail:  "test@test.com",
+	}))
+}
+
+// enableV11 chdirs into dir and opts into checkpoints v1.1.
+func enableV11(t *testing.T, dir string) {
+	t.Helper()
+	t.Chdir(dir)
+	writeSettings(t, dir, `"1.1"`)
+}
+
+// writeSettings writes .entire/settings.json (empty version omits the option).
+func writeSettings(t *testing.T, dir, version string) {
+	t.Helper()
+	body := `{"enabled": true}`
+	if version != "" {
+		body = `{"enabled": true, "strategy_options": {"checkpoints_version": ` + version + `}}`
+	}
+	require.NoError(t, os.MkdirAll(filepath.Join(dir, ".entire"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, ".entire", paths.SettingsFileName), []byte(body), 0o644))
+}
+
+// blockCustomRefWrite occupies refs/entire with a file so refs/entire/* writes fail.
+func blockCustomRefWrite(t *testing.T, dir string) {
+	t.Helper()
+	require.NoError(t, os.WriteFile(filepath.Join(dir, ".git", "refs", "entire"), []byte("blocked"), 0o644))
+}
+
+func TestGitStore_CommittedReadRef(t *testing.T) {
+	t.Parallel()
+	assert.Equal(t, v1BranchRef(), NewGitStore(nil).CommittedReadRef())
+	assert.Equal(t, customRef(), NewGitStoreWithRef(nil, customRef()).CommittedReadRef())
+}
+
+func TestSyncV1CustomRefForRead(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name  string
+		setup func(t *testing.T, dir string, repo *git.Repository, init plumbing.Hash) (want plumbing.Hash, exists bool)
+	}{
+		{"seeds from local v1 when missing", func(t *testing.T, _ string, repo *git.Repository, init plumbing.Hash) (plumbing.Hash, bool) {
+			setRef(t, repo, v1BranchRef(), init)
+			return init, true
+		}},
+		{"seeds from origin when local v1 missing", func(t *testing.T, _ string, repo *git.Repository, init plumbing.Hash) (plumbing.Hash, bool) {
+			setRef(t, repo, originV1Ref(), init)
+			return init, true
+		}},
+		{"no-op when equal", func(t *testing.T, _ string, repo *git.Repository, init plumbing.Hash) (plumbing.Hash, bool) {
+			setRef(t, repo, v1BranchRef(), init)
+			setRef(t, repo, customRef(), init)
+			return init, true
+		}},
+		{"advances when ancestor", func(t *testing.T, dir string, repo *git.Repository, init plumbing.Hash) (plumbing.Hash, bool) {
+			setRef(t, repo, customRef(), init)
+			newHash := commitFile(t, repo, dir, "f2.txt", "more", "second")
+			setRef(t, repo, v1BranchRef(), newHash)
+			return newHash, true
+		}},
+		{"leaves non-ancestor ref", func(t *testing.T, dir string, repo *git.Repository, init plumbing.Hash) (plumbing.Hash, bool) {
+			ahead := commitFile(t, repo, dir, "f2.txt", "more", "second")
+			setRef(t, repo, v1BranchRef(), init) // parent
+			setRef(t, repo, customRef(), ahead)  // child, not an ancestor of v1
+			return ahead, true
+		}},
+		{"no v1 tip", func(_ *testing.T, _ string, _ *git.Repository, _ plumbing.Hash) (plumbing.Hash, bool) {
+			return plumbing.ZeroHash, false
+		}},
+		{"write failure leaves ref unset", func(t *testing.T, dir string, repo *git.Repository, init plumbing.Hash) (plumbing.Hash, bool) {
+			setRef(t, repo, v1BranchRef(), init)
+			blockCustomRefWrite(t, dir)
+			return plumbing.ZeroHash, false
+		}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			dir, repo, init := newTestRepo(t)
+			want, exists := tt.setup(t, dir, repo, init)
+
+			syncV1CustomRefForRead(context.Background(), repo)
+
+			got, ok := customRefHash(t, repo)
+			require.Equal(t, exists, ok)
+			if exists {
+				assert.Equal(t, want, got)
+			}
+		})
+	}
+}
+
+// Not parallel: uses t.Chdir() so settings.Load resolves the test repo.
+func TestNewCommittedReadStore_SelectsRefByVersion(t *testing.T) {
+	dir, repo, h := newTestRepo(t)
+	setRef(t, repo, v1BranchRef(), h)
+	t.Chdir(dir)
+
+	writeSettings(t, dir, "") // v1 only
+	assert.Equal(t, v1BranchRef(), NewCommittedReadStore(context.Background(), repo).CommittedReadRef())
+
+	writeSettings(t, dir, `"1.1"`)
+	assert.Equal(t, customRef(), NewCommittedReadStore(context.Background(), repo).CommittedReadRef())
+}
+
+// v1.1 reads always go through the custom ref (no v1 fallback): a checkpoint is
+// found when the ref can be synced to v1, and not found when it can't.
+// Not parallel: subtests use t.Chdir().
+func TestNewCommittedReadStore_V11Reads(t *testing.T) {
+	tests := []struct {
+		name      string
+		mutate    func(t *testing.T, dir string, repo *git.Repository)
+		wantFound bool
+	}{
+		{"reads v1 data via custom ref", func(_ *testing.T, _ string, _ *git.Repository) {}, true},
+		{"reads remote-only metadata", func(t *testing.T, _ string, repo *git.Repository) {
+			ref, err := repo.Reference(v1BranchRef(), true)
+			require.NoError(t, err)
+			setRef(t, repo, originV1Ref(), ref.Hash())
+			require.NoError(t, repo.Storer.RemoveReference(v1BranchRef()))
+		}, true},
+		{"sync write fails", func(t *testing.T, dir string, _ *git.Repository) {
+			blockCustomRefWrite(t, dir)
+		}, false},
+		{"custom ref diverges", func(t *testing.T, dir string, repo *git.Repository) {
+			setRef(t, repo, customRef(), commitFile(t, repo, dir, "other.txt", "diverged", "diverged"))
+		}, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir, repo, _ := newTestRepo(t)
+			enableV11(t, dir)
+			cpID := id.MustCheckpointID("a1b2c3d4e5f6")
+			writeV1Checkpoint(t, repo, cpID)
+			tt.mutate(t, dir, repo)
+
+			SyncCommittedReadRef(context.Background(), repo)
+			store := NewCommittedReadStore(context.Background(), repo)
+			require.Equal(t, customRef(), store.CommittedReadRef(), "must read the custom ref, not fall back to v1")
+
+			summary, err := store.ReadCommitted(context.Background(), cpID)
+			require.NoError(t, err)
+			if tt.wantFound {
+				require.NotNil(t, summary)
+				assert.Equal(t, cpID, summary.CheckpointID)
+			} else {
+				assert.Nil(t, summary, "must not fall back to v1")
+			}
+		})
+	}
+}