notify when a new CLI version is available mid-session and improved messages (#50)

Author: roblaszczak

internal/selfupdate.go

@@ -221,7 +221,7 @@ func RunUpdate(ctx context.Context, currentVersion string, opts UpdateOptions) e
 		fmt.Printf("\nUpdate available: %s → %s\n", currentVersion, targetVersion)
 
 		if notes := release.ReleaseNotes; notes != "" {
-			formatted := formatReleaseNotes(notes, 15)
+			formatted := FormatReleaseNotes(notes, 15)
 			if formatted != "" {
 				fmt.Println()
 				fmt.Println("Release notes:")
@@ -362,8 +362,8 @@ func handleBranchInstall(ctx context.Context, branch string, method InstallMetho
 	}
 }
 
-// formatReleaseNotes prepares release notes for terminal display.
-func formatReleaseNotes(body string, maxLines int) string {
+// FormatReleaseNotes prepares release notes for terminal display.
+func FormatReleaseNotes(body string, maxLines int) string {
 	if strings.TrimSpace(body) == "" {
 		return ""
 	}

internal/selfupdate_test.go

@@ -155,13 +155,13 @@ func TestCanWriteBinary(t *testing.T) {
 
 func TestFormatReleaseNotes(t *testing.T) {
 	t.Run("empty body", func(t *testing.T) {
-		assert.Equal(t, "", formatReleaseNotes("", 15))
-		assert.Equal(t, "", formatReleaseNotes("   \n\n  ", 15))
+		assert.Equal(t, "", FormatReleaseNotes("", 15))
+		assert.Equal(t, "", FormatReleaseNotes("   \n\n  ", 15))
 	})
 
 	t.Run("short body under limit", func(t *testing.T) {
 		body := "- Fixed bug in exercise reset\n- Added module skipping"
-		result := formatReleaseNotes(body, 15)
+		result := FormatReleaseNotes(body, 15)
 		assert.Contains(t, result, "Fixed bug in exercise reset")
 		assert.Contains(t, result, "Added module skipping")
 		assert.NotContains(t, result, "see full release notes")
@@ -173,37 +173,37 @@ func TestFormatReleaseNotes(t *testing.T) {
 			lines = append(lines, "- Change number "+string(rune('A'+i)))
 		}
 		body := strings.Join(lines, "\n")
-		result := formatReleaseNotes(body, 5)
+		result := FormatReleaseNotes(body, 5)
 		assert.Contains(t, result, "Change number A")
 		assert.Contains(t, result, "see full release notes")
 		assert.NotContains(t, result, "Change number F")
 	})
 
 	t.Run("strips markdown headers", func(t *testing.T) {
 		body := "## What's Changed\n- Bug fix"
-		result := formatReleaseNotes(body, 15)
+		result := FormatReleaseNotes(body, 15)
 		assert.Contains(t, result, "What's Changed")
 		assert.NotContains(t, result, "##")
 	})
 
 	t.Run("strips bold markers", func(t *testing.T) {
 		body := "**Important**: This is a breaking change"
-		result := formatReleaseNotes(body, 15)
+		result := FormatReleaseNotes(body, 15)
 		assert.Contains(t, result, "Important")
 		assert.NotContains(t, result, "**")
 	})
 
 	t.Run("strips markdown links", func(t *testing.T) {
 		body := "See [the docs](https://example.com) for details"
-		result := formatReleaseNotes(body, 15)
+		result := FormatReleaseNotes(body, 15)
 		assert.Contains(t, result, "the docs")
 		assert.NotContains(t, result, "https://example.com")
 		assert.NotContains(t, result, "[")
 	})
 
 	t.Run("trims leading and trailing blank lines", func(t *testing.T) {
 		body := "\n\n- First line\n- Second line\n\n"
-		result := formatReleaseNotes(body, 15)
+		result := FormatReleaseNotes(body, 15)
 		assert.Contains(t, result, "First line")
 		assert.Contains(t, result, "Second line")
 	})

internal/update.go

@@ -89,6 +89,74 @@ func CheckForUpdate(currentVersion string, commandName string, forcePrompt bool)
 	}
 }
 
+// CheckUpdateAvailable performs a silent update check suitable for background
+// goroutines that poll on a long timer. It never prints and never prompts.
+// Returns whether a newer release is known for currentVersion, along with the
+// new version string and its release notes (if any).
+//
+// Honors TDL_NO_UPDATE_CHECK, skips when currentVersion is empty or "dev",
+// fast-paths the cached state file, and only hits the GitHub API once the
+// updateCheckInterval has elapsed. Respects the on-disk dismissal window so
+// a user who already declined the same version at startup isn't re-notified
+// mid-session.
+//
+// forcePrompt mirrors the semantics of CheckForUpdate's forcePrompt: bypass
+// the interval gate, accept any release that differs from currentVersion
+// (not just newer), and bypass the dismissal window. Intended for the hidden
+// --force-update-prompt testing flag.
+func CheckUpdateAvailable(currentVersion string, forcePrompt bool) (available bool, newVersion string, releaseNotes string) {
+	if os.Getenv("TDL_NO_UPDATE_CHECK") != "" {
+		return false, "", ""
+	}
+	if currentVersion == "" {
+		return false, "", ""
+	}
+	if !forcePrompt && currentVersion == "dev" {
+		return false, "", ""
+	}
+
+	updateInfo, _ := getUpdateInfo()
+
+	if forcePrompt || time.Since(updateInfo.LastChecked) >= updateCheckInterval {
+		if release := getLatestRelease(); release != nil {
+			isNewer := release.Version != "" && isNewerVersion(release.Version, currentVersion)
+			isDifferent := release.Version != "" && release.Version != currentVersion
+			if isNewer || (forcePrompt && isDifferent) {
+				updateInfo.CurrentVersion = currentVersion
+				updateInfo.AvailableVersion = release.Version
+				updateInfo.UpdateAvailable = true
+				updateInfo.ReleaseNotes = release.ReleaseNotes
+			} else {
+				updateInfo.CurrentVersion = currentVersion
+				updateInfo.AvailableVersion = ""
+				updateInfo.UpdateAvailable = false
+				updateInfo.ReleaseNotes = ""
+				updateInfo.DismissedVersion = ""
+				updateInfo.DismissedAt = time.Time{}
+			}
+			updateInfo.LastChecked = time.Now()
+			_ = storeUpdateInfo(updateInfo)
+		}
+	}
+
+	if !updateInfo.UpdateAvailable {
+		return false, "", ""
+	}
+
+	if !forcePrompt {
+		if !isNewerVersion(updateInfo.AvailableVersion, currentVersion) {
+			return false, "", ""
+		}
+		// Respect the existing dismissal window — don't nag a user who already
+		// declined the same version at startup.
+		if !shouldShowBlockingPrompt(updateInfo) {
+			return false, "", ""
+		}
+	}
+
+	return true, updateInfo.AvailableVersion, updateInfo.ReleaseNotes
+}
+
 func showUpdatePromptOrNotice(updateInfo UpdateInfo, currentVersion string, isUpdateCommand bool, forcePrompt bool) {
 	// If user is running "tdl update", skip — they're already updating
 	if isUpdateCommand {
@@ -129,7 +197,7 @@ func showBlockingUpdatePrompt(updateInfo UpdateInfo, currentVersion string) {
 	_, _ = c.Printf("Some features may be missing or not work correctly.\n")
 
 	if updateInfo.ReleaseNotes != "" {
-		formatted := formatReleaseNotes(updateInfo.ReleaseNotes, 15)
+		formatted := FormatReleaseNotes(updateInfo.ReleaseNotes, 15)
 		if formatted != "" {
 			fmt.Println()
 			fmt.Println("Release notes:")

tdl/main.go

@@ -448,15 +448,16 @@ func newHandlers(c *cli.Context) *trainings.Handlers {
 	mcpPort := c.Int("mcp-port")
 
 	return trainings.NewHandlers(trainings.CliMetadata{
-		Version:         version,
-		Commit:          commit,
-		Architecture:    runtime.GOARCH,
-		OS:              runtime.GOOS,
-		OSVersion:       osVersion(),
-		GoVersion:       runtime.Version(),
-		GitVersion:      gitVersionString(),
-		ExecutedCommand: cmd,
-		Interactive:     internal.IsStdinTerminal(),
+		Version:           version,
+		Commit:            commit,
+		Architecture:      runtime.GOARCH,
+		OS:                runtime.GOOS,
+		OSVersion:         osVersion(),
+		GoVersion:         runtime.Version(),
+		GitVersion:        gitVersionString(),
+		ExecutedCommand:   cmd,
+		Interactive:       internal.IsStdinTerminal(),
+		ForceUpdatePrompt: c.Bool("force-update-prompt"),
 	}, mcpPort)
 }
 

trainings/git_helpers.go

@@ -29,10 +29,15 @@ func gitDefaultConfig(cfg *config.TrainingConfig) {
 }
 
 // stageInitialFiles stages the base set of files for an initial commit:
-// .tdl-training, .gitignore, and optionally go.work if a Go workspace exists.
+// .gitignore, and optionally go.work if a Go workspace exists.
 // Extra files (e.g. a cloned exercise directory) can be appended.
+//
+// .tdl-training is intentionally omitted — it's gitignored as local state
+// (see the gitignore template in init.go), so force-adding it here would
+// fail silently. User progress is tracked via per-exercise commits, not
+// via .tdl-training.
 func stageInitialFiles(gitOps *git.Ops, trainingRootDir string, extraFiles ...string) {
-	files := []string{".tdl-training", ".gitignore"}
+	files := []string{".gitignore"}
 	if hasGoWorkspace(trainingRootDir) {
 		files = append(files, "go.work")
 	}

trainings/git_helpers_test.go

@@ -95,13 +95,14 @@ func TestStageInitialFiles_BaseCase(t *testing.T) {
 
 	stageInitialFiles(gitOps, dir)
 
-	// Check that files are staged
 	cmd := exec.Command("git", "diff", "--cached", "--name-only")
 	cmd.Dir = dir
 	out, err := cmd.CombinedOutput()
 	require.NoError(t, err)
-	assert.Contains(t, string(out), ".tdl-training")
 	assert.Contains(t, string(out), ".gitignore")
+	// .tdl-training is local state; it must not land in the initial commit
+	// even when present on disk.
+	assert.NotContains(t, string(out), ".tdl-training")
 }
 
 func TestStageInitialFiles_WithGoWork(t *testing.T) {

trainings/handlers.go

@@ -6,6 +6,7 @@ import (
 	"crypto/x509"
 	"fmt"
 	"runtime"
+	"sync"
 	"time"
 
 	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/retry"
@@ -40,6 +41,15 @@ type Handlers struct {
 	stdinCh   <-chan rune       // centralized stdin channel; non-nil only during interactiveRun with MCP
 
 	pendingMCPResultCh chan<- mcppkg.MCPResult // deferred result for blocking MCP commands (e.g. next exercise)
+
+	// Fallback update-state for when MCP is disabled (loopState == nil).
+	// When loopState is non-nil all update accessors route through it so
+	// MCP tool handlers see the same values as the terminal prompt.
+	updateMu             sync.Mutex
+	updateAvailable      bool
+	updateVersion        string
+	updateReleaseNotes   string
+	updateNoticeShownCLI bool
 }
 
 type CliMetadata struct {
@@ -54,6 +64,11 @@ type CliMetadata struct {
 
 	ExecutedCommand string
 	Interactive     bool
+
+	// ForceUpdatePrompt mirrors the top-level hidden --force-update-prompt
+	// flag so the in-loop background update check can also bypass the
+	// interval/dismissal gates for testing.
+	ForceUpdatePrompt bool
 }
 
 func NewHandlers(cliVersion CliMetadata, mcpPort int) *Handlers {

trainings/init.go

@@ -408,7 +408,8 @@ var gitignore = strings.Join(
 		"# Exercise content is subject to Three Dots Labs' copyright.",
 		"**/" + files.ExerciseFile,
 		"",
-		"# TDL exercise state (managed by CLI)",
+		"# TDL local state (managed by CLI)",
+		".tdl-training",
 		".tdl-exercise",
 		"",
 		"# AI coding tool configs (managed by CLI)",

trainings/mcp/state.go

@@ -99,6 +99,15 @@ type LoopState struct {
 	lastError     string
 
 	transitionContent string // human-readable context from last exercise transition (e.g. diff)
+
+	// Background CLI-update signals. The terminal ("CLI") and MCP surfaces
+	// each render the one-shot notice independently, so their "shown" flags
+	// are tracked separately.
+	updateAvailable      bool
+	updateVersion        string
+	updateReleaseNotes   string
+	updateNoticeShownCLI bool
+	updateNoticeShownMCP bool
 }
 
 func NewLoopState() *LoopState {
@@ -228,3 +237,55 @@ func (s *LoopState) ClearTransitionContent() {
 	defer s.mu.Unlock()
 	s.transitionContent = ""
 }
+
+// SetUpdateAvailable records that a newer CLI release is available.
+// Called from the background update-check goroutine.
+func (s *LoopState) SetUpdateAvailable(version, releaseNotes string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.updateVersion != version {
+		// A different (newer) version than what was previously signaled —
+		// reset the "shown" flags so both surfaces re-notify.
+		s.updateNoticeShownCLI = false
+		s.updateNoticeShownMCP = false
+	}
+	s.updateAvailable = true
+	s.updateVersion = version
+	s.updateReleaseNotes = releaseNotes
+}
+
+// GetUpdateAvailable returns the current background-check result.
+func (s *LoopState) GetUpdateAvailable() (available bool, version, releaseNotes string) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.updateAvailable, s.updateVersion, s.updateReleaseNotes
+}
+
+// ShouldShowUpdateNoticeCLI reports whether the terminal should still print
+// its one-shot "update available" line. Returns false once
+// MarkUpdateNoticeShownCLI has been called for the current version.
+func (s *LoopState) ShouldShowUpdateNoticeCLI() bool {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.updateAvailable && !s.updateNoticeShownCLI
+}
+
+func (s *LoopState) MarkUpdateNoticeShownCLI() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.updateNoticeShownCLI = true
+}
+
+// ShouldShowUpdateNoticeMCP is the MCP-side counterpart — gates the one-shot
+// note appended to tool-result messages.
+func (s *LoopState) ShouldShowUpdateNoticeMCP() bool {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.updateAvailable && !s.updateNoticeShownMCP
+}
+
+func (s *LoopState) MarkUpdateNoticeShownMCP() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.updateNoticeShownMCP = true
+}