finished history view implementation

Author: keshon

README.md

@@ -111,12 +111,23 @@ Each archive contains:
 
 <!-- /generated -->
 
+#### `/music` — usage
+
+Subcommands are summarized in the list above; this section expands the main playback flow.
+
+- **`/music play`** — Enter a **URL** (YouTube, SoundCloud, or a direct radio/stream link), a **search query**, or one or more **history ids** (the numbers shown in `/music history`) to queue that track again without a full resolve. Optional **`source`** and **`parser`** override autodetection. You can separate several ids or URLs with spaces, commas, or semicolons (there is a per-command batch limit).
+- **`/music history`** — **`view`**: **Timeline** lists each play in order with a short date; **By URL** merges identical links and shows a **×** multiplier for how often each was played. Use **`page`** to move through long lists. Each row includes an **id** you can pass to **`/music play`**. History is stored per server; very old rows may be removed when the persisted list is trimmed.
+- **`/music next`** — Skip to the next track in the queue.
+- **`/music stop`** — Stop playback and clear the queue.
+
 Example usage:
 
 ```
 /music play Never Gonna Give You Up
 /music play https://www.youtube.com/watch?v=dQw4w9WgXcQ
 /music play http://stream-uk1.radioparadise.com/aac-320
+/music play 42
+/music history
 ```
 
 You must be in a voice channel to use `/music play`.

README.md.tmpl

@@ -84,12 +84,23 @@ Each archive contains:
 
 <!-- /generated -->
 
+#### `/music` — usage
+
+Subcommands are summarized in the list above; this section expands the main playback flow.
+
+- **`/music play`** — Enter a **URL** (YouTube, SoundCloud, or a direct radio/stream link), a **search query**, or one or more **history ids** (the numbers shown in `/music history`) to queue that track again without a full resolve. Optional **`source`** and **`parser`** override autodetection. You can separate several ids or URLs with spaces, commas, or semicolons (there is a per-command batch limit).
+- **`/music history`** — **`view`**: **Timeline** lists each play in order with a short date; **By URL** merges identical links and shows a **×** multiplier for how often each was played. Use **`page`** to move through long lists. Each row includes an **id** you can pass to **`/music play`**. History is stored per server; very old rows may be removed when the persisted list is trimmed.
+- **`/music next`** — Skip to the next track in the queue.
+- **`/music stop`** — Stop playback and clear the queue.
+
 Example usage:
 
 ```
 /music play Never Gonna Give You Up
 /music play https://www.youtube.com/watch?v=dQw4w9WgXcQ
 /music play http://stream-uk1.radioparadise.com/aac-320
+/music play 42
+/music history
 ```
 
 You must be in a voice channel to use `/music play`.

internal/command/music/history_display.go

@@ -0,0 +1,81 @@
+package music
+
+import (
+	"fmt"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/keshon/melodix/internal/domain"
+)
+
+// historyMaxLineBytes caps rendered line length (embed row); long track titles get middle ellipsis.
+const historyMaxLineBytes = 120
+
+const historyMinTitleRunes = 8
+
+func displayTrackTitle(raw string) string {
+	if strings.TrimSpace(raw) == "" {
+		return "(no title)"
+	}
+	return strings.TrimSpace(raw)
+}
+
+// truncateTitleMiddle shortens s to at most maxRunes runes, inserting "..." in the middle when needed.
+func truncateTitleMiddle(s string, maxRunes int) string {
+	if maxRunes < 1 {
+		return ""
+	}
+	r := []rune(s)
+	if len(r) <= maxRunes {
+		return s
+	}
+	if maxRunes <= 3 {
+		return string(r[:maxRunes])
+	}
+	inner := maxRunes - 3
+	left := inner / 2
+	right := inner - left
+	return string(r[:left]) + "..." + string(r[len(r)-right:])
+}
+
+func fitTitleToLineLimit(title string, build func(string) string) string {
+	if len(build(title)) <= historyMaxLineBytes {
+		return title
+	}
+	n := utf8.RuneCountInString(title)
+	for max := n; max >= historyMinTitleRunes; max-- {
+		short := truncateTitleMiddle(title, max)
+		if len(build(short)) <= historyMaxLineBytes {
+			return short
+		}
+	}
+	return truncateTitleMiddle(title, historyMinTitleRunes)
+}
+
+// historyLine: `id` [title](url) `tail` (spaces only; tail is backtick-wrapped date or ×N play count).
+func historyLine(id uint64, title, url, tail string) string {
+	if url != "" {
+		return fmt.Sprintf("`%d` [%s](%s) `%s`", id, title, url, tail)
+	}
+	return fmt.Sprintf("`%d` %s `%s`", id, title, tail)
+}
+
+func formatTimelineLine(m domain.MusicPlayback) string {
+	tail := m.PlayedAt.Format("02 Jan 2006")
+	title := displayTrackTitle(m.Title)
+	build := func(tt string) string {
+		return historyLine(m.ID, tt, m.URL, tail)
+	}
+	title = fitTitleToLineLimit(title, build)
+	return build(title)
+}
+
+func formatCountsLine(r domain.PlaybackCountRow) string {
+	tail := fmt.Sprintf("×%d", r.Count)
+	title := displayTrackTitle(r.Title)
+	build := func(tt string) string {
+		return historyLine(r.RepresentativeID, tt, r.URL, tail)
+	}
+	title = fitTitleToLineLimit(title, build)
+	return build(title)
+}

internal/command/music/history_display_test.go

@@ -0,0 +1,57 @@
+package music
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/keshon/melodix/internal/domain"
+)
+
+func TestTruncateTitleMiddle(t *testing.T) {
+	t.Parallel()
+	short := "abc"
+	if got := truncateTitleMiddle(short, 10); got != short {
+		t.Fatalf("short: %q", got)
+	}
+	long := "abcdefghijklmnopqrstuvwxyz0123456789"
+	got := truncateTitleMiddle(long, 12)
+	if len([]rune(got)) != 12 {
+		t.Fatalf("rune len: %q len=%d", got, len([]rune(got)))
+	}
+	if !strings.Contains(got, "...") {
+		t.Fatalf("expected ellipsis: %q", got)
+	}
+}
+
+func TestFormatTimelineLineShape(t *testing.T) {
+	t.Parallel()
+	m := domain.MusicPlayback{
+		ID:        7,
+		PlayedAt:  time.Date(2026, 3, 15, 0, 0, 0, 0, time.UTC),
+		URL:       "https://x.test/a",
+		Title:     "Hi",
+	}
+	s := formatTimelineLine(m)
+	if !strings.Contains(s, "`7`") || !strings.Contains(s, "[Hi]") || !strings.Contains(s, "`15 Mar 2026`") {
+		t.Fatalf("got %q", s)
+	}
+}
+
+func TestFormatCountsLineNoDate(t *testing.T) {
+	t.Parallel()
+	r := domain.PlaybackCountRow{
+		RepresentativeID: 9,
+		URL:              "https://y.test/b",
+		Title:            "Song",
+		Count:            4,
+		LastPlayed:       time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC),
+	}
+	s := formatCountsLine(r)
+	if strings.Contains(s, "2020") || strings.Contains(s, "Jan") {
+		t.Fatalf("counts line should not include date: %q", s)
+	}
+	if !strings.HasSuffix(s, "`×4`") || !strings.Contains(s, "`9`") || strings.Contains(s, "last ") {
+		t.Fatalf("got %q", s)
+	}
+}

internal/command/music/slash_music.go

@@ -87,12 +87,12 @@ func (c *MusicCommand) SlashDefinition() *discordgo.ApplicationCommand {
 				Options: []*discordgo.ApplicationCommandOption{
 					{
 						Type:        discordgo.ApplicationCommandOptionString,
-						Name:        "mode",
-						Description: "Timeline (chronological) or counts grouped by URL",
+						Name:        "view",
+						Description: "Chronological list or plays per link",
 						Required:    false,
 						Choices: []*discordgo.ApplicationCommandOptionChoice{
-							{Name: "Timeline (chronological)", Value: "timeline"},
-							{Name: "Counts (by URL)", Value: "counts"},
+							{Name: "Timeline", Value: "timeline"},
+							{Name: "By URL", Value: "counts"},
 						},
 					},
 					{
@@ -148,19 +148,19 @@ func (c *MusicCommand) Run(ctx interface{}) error {
 		return c.runStop(s, e)
 
 	case "history":
-		mode := "timeline"
+		view := "timeline"
 		var page int64 = 1
 		for _, opt := range sub.Options {
 			switch opt.Name {
-			case "mode":
+			case "view":
 				if v := strings.TrimSpace(opt.StringValue()); v != "" {
-					mode = v
+					view = v
 				}
 			case "page":
 				page = opt.IntValue()
 			}
 		}
-		return c.runHistory(s, e, page, mode, store)
+		return c.runHistory(s, e, page, view, store)
 
 	default:
 		return discord.RespondEmbedEphemeral(s, e, &discordgo.MessageEmbed{
@@ -309,31 +309,10 @@ func (c *MusicCommand) runPlay(s *discordgo.Session, e *discordgo.InteractionCre
 
 const historyLinesPerPage = 15
 
-func formatTimelineLine(m domain.MusicPlayback) string {
-	title := m.Title
-	if title == "" {
-		title = "(no title)"
-	}
-	t := m.PlayedAt.Format("2006-01-02 15:04")
-	if m.URL != "" {
-		return fmt.Sprintf("`%d` — [%s](%s) — %s", m.ID, title, m.URL, t)
-	}
-	return fmt.Sprintf("`%d` — %s — %s", m.ID, title, t)
-}
-
-func formatCountsLine(r domain.PlaybackCountRow) string {
-	title := r.Title
-	if title == "" {
-		title = "(no title)"
-	}
-	t := r.LastPlayed.Format("2006-01-02 15:04")
-	if r.URL != "" {
-		return fmt.Sprintf("`%d` — ×%d — [%s](%s) — last %s", r.RepresentativeID, r.Count, title, r.URL, t)
-	}
-	return fmt.Sprintf("`%d` — ×%d — %s — last %s", r.RepresentativeID, r.Count, title, t)
-}
+// Shown in /music history footer for replay hint (counts view uses the same sentence as timeline).
+const historyFooterReplay = "replay with `/music play <id>`."
 
-func (c *MusicCommand) runHistory(s *discordgo.Session, e *discordgo.InteractionCreate, page int64, mode string, store *storage.Storage) error {
+func (c *MusicCommand) runHistory(s *discordgo.Session, e *discordgo.InteractionCreate, page int64, view string, store *storage.Storage) error {
 	if err := s.InteractionRespond(e.Interaction, &discordgo.InteractionResponse{
 		Type: discordgo.InteractionResponseDeferredChannelMessageWithSource,
 	}); err != nil {
@@ -375,29 +354,29 @@ func (c *MusicCommand) runHistory(s *discordgo.Session, e *discordgo.Interaction
 		return nil
 	}
 
-	mode = strings.ToLower(strings.TrimSpace(mode))
-	if mode == "" {
-		mode = "timeline"
+	view = strings.ToLower(strings.TrimSpace(view))
+	if view == "" {
+		view = "timeline"
 	}
 
 	var lines []string
 	var totalRows int
-	var title string
+	var embedTitle string
 	var footerExtra string
 
-	switch mode {
+	switch view {
 	case "counts":
 		counts := domain.AggregatePlaybackCounts(rows)
 		totalRows = len(counts)
-		title = "🎵 Playback history (counts by URL)"
-		footerExtra = "Distinct URLs; replay id is the latest play for that link."
+		embedTitle = "🎵 Playback history (by URL)"
+		footerExtra = historyFooterReplay
 		for _, r := range counts {
 			lines = append(lines, formatCountsLine(r))
 		}
 	default:
 		totalRows = len(rows)
-		title = "🎵 Playback history (timeline)"
-		footerExtra = "Chronological; replay with `/music play <id>`."
+		embedTitle = "🎵 Playback history (timeline)"
+		footerExtra = "Chronological; " + historyFooterReplay
 		for _, m := range rows {
 			lines = append(lines, formatTimelineLine(m))
 		}
@@ -435,7 +414,7 @@ func (c *MusicCommand) runHistory(s *discordgo.Session, e *discordgo.Interaction
 	}
 
 	embed := &discordgo.MessageEmbed{
-		Title:       title,
+		Title:       embedTitle,
 		Description: desc,
 		Footer: &discordgo.MessageEmbedFooter{
 			Text: fmt.Sprintf("Page %d/%d (%d rows). %s", page, totalPages, totalRows, footerExtra),

internal/discord/bot.go

@@ -13,7 +13,7 @@ import (
 	"github.com/keshon/melodix/internal/command"
 	"github.com/keshon/melodix/internal/config"
 	"github.com/keshon/melodix/internal/discord/voice"
-	"github.com/keshon/melodix/internal/docs"
+	"github.com/keshon/melodix/internal/readme"
 	"github.com/keshon/melodix/internal/storage"
 )
 
@@ -236,7 +236,7 @@ func (b *Bot) onReady(s *discordgo.Session, r *discordgo.Ready) {
 	// Background services start once across all reconnects.
 	b.once.Do(func() {
 		log.Println("[INFO] Starting background services...")
-		if err := docs.UpdateReadme(commandkit.DefaultRegistry, config.CategoryWeights); err != nil {
+		if err := readme.UpdateReadme(commandkit.DefaultRegistry, config.CategoryWeights); err != nil {
 			log.Println("[ERR] Failed to update README:", err)
 		}
 	})

internal/docs/readme.go internal/readme/readme.gointernal/docs/readme.go renamed to internal/readme/readme.go

@@ -1,4 +1,4 @@
-package docs
+package readme
 
 import (
 	"bytes"

internal/storage/storage_commands.go internal/storage/commands.gointernal/storage/storage_commands.go renamed to internal/storage/commands.go

@@ -0,0 +1,5 @@
+@echo off
+setlocal
+cd /d "%~dp0"
+go test ./... -count=1 -timeout=120s
+exit /b %ERRORLEVEL%