Add @mention resolution for comments and descriptions

internal/client/client.go

@@ -170,6 +170,50 @@ func (c *Client) Delete(path string) (*APIResponse, error) {
 	return c.request("DELETE", path, nil)
 }
 
+// GetHTML performs a GET request expecting an HTML response.
+// Unlike Get, it sets Accept: text/html and does not attempt JSON parsing.
+func (c *Client) GetHTML(path string) (*APIResponse, error) {
+	requestURL := c.buildURL(path)
+	req, err := http.NewRequestWithContext(context.Background(), "GET", requestURL, nil)
+	if err != nil {
+		return nil, errors.NewNetworkError(fmt.Sprintf("Failed to create request: %v", err))
+	}
+
+	req.Header.Set("Authorization", "Bearer "+c.Token)
+	req.Header.Set("Accept", "text/html")
+	req.Header.Set("User-Agent", "fizzy-cli/1.0")
+
+	if c.Verbose {
+		fmt.Fprintf(os.Stderr, "> GET %s (HTML)\n", requestURL)
+	}
+
+	resp, err := c.doWithRetry(req)
+	if err != nil {
+		return nil, errors.NewNetworkError(fmt.Sprintf("Request failed: %v", err))
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, errors.NewNetworkError(fmt.Sprintf("Failed to read response: %v", err))
+	}
+
+	if c.Verbose {
+		fmt.Fprintf(os.Stderr, "< %d %s\n", resp.StatusCode, http.StatusText(resp.StatusCode))
+	}
+
+	apiResp := &APIResponse{
+		StatusCode: resp.StatusCode,
+		Body:       respBody,
+	}
+
+	if resp.StatusCode >= 400 {
+		return apiResp, c.errorFromResponse(resp.StatusCode, respBody, resp.Header)
+	}
+
+	return apiResp, nil
+}
+
 func (c *Client) request(method, path string, body any) (*APIResponse, error) {
 	requestURL := c.buildURL(path)
 

internal/client/interface.go

@@ -13,6 +13,7 @@ type API interface {
 	FollowLocation(location string) (*APIResponse, error)
 	UploadFile(filePath string) (*APIResponse, error)
 	DownloadFile(urlPath string, destPath string) error
+	GetHTML(path string) (*APIResponse, error)
 }
 
 // Ensure Client implements API interface

internal/commands/card.go

@@ -293,9 +293,9 @@ var cardCreateCmd = &cobra.Command{
 			if descErr != nil {
 				return descErr
 			}
-			description = markdownToHTML(string(descContent))
+			description = markdownToHTML(resolveMentions(string(descContent), getClient()))
 		} else if cardCreateDescription != "" {
-			description = markdownToHTML(cardCreateDescription)
+			description = markdownToHTML(resolveMentions(cardCreateDescription, getClient()))
 		}
 
 		ac := getSDK()
@@ -384,9 +384,9 @@ var cardUpdateCmd = &cobra.Command{
 			if err != nil {
 				return err
 			}
-			description = markdownToHTML(string(content))
+			description = markdownToHTML(resolveMentions(string(content), getClient()))
 		} else if cardUpdateDescription != "" {
-			description = markdownToHTML(cardUpdateDescription)
+			description = markdownToHTML(resolveMentions(cardUpdateDescription, getClient()))
 		}
 
 		// Build breadcrumbs

internal/commands/comment.go

@@ -149,9 +149,9 @@ var commentCreateCmd = &cobra.Command{
 			if err != nil {
 				return err
 			}
-			body = markdownToHTML(string(content))
+			body = markdownToHTML(resolveMentions(string(content), getClient()))
 		} else if commentCreateBody != "" {
-			body = markdownToHTML(commentCreateBody)
+			body = markdownToHTML(resolveMentions(commentCreateBody, getClient()))
 		} else {
 			return newRequiredFlagError("body or body_file")
 		}
@@ -209,9 +209,9 @@ var commentUpdateCmd = &cobra.Command{
 			if err != nil {
 				return err
 			}
-			body = markdownToHTML(string(content))
+			body = markdownToHTML(resolveMentions(string(content), getClient()))
 		} else if commentUpdateBody != "" {
-			body = markdownToHTML(commentUpdateBody)
+			body = markdownToHTML(resolveMentions(commentUpdateBody, getClient()))
 		}
 
 		commentID := args[0]

internal/commands/mentions.go

@@ -0,0 +1,207 @@
+package commands
+
+import (
+	"fmt"
+	"os"
+	"regexp"
+	"strings"
+	"sync"
+	"unicode"
+
+	"github.com/basecamp/fizzy-cli/internal/client"
+)
+
+// mentionUser represents a mentionable user parsed from the /prompts/users endpoint.
+type mentionUser struct {
+	FirstName string // e.g. "Wayne"
+	FullName  string // e.g. "Wayne Smith"
+	SGID      string // signed global ID for ActionText
+	AvatarSrc string // e.g. "/6103476/users/03f5awg7.../avatar"
+}
+
+// Package-level cache: populated once per CLI invocation.
+var (
+	mentionUsers []mentionUser
+	mentionOnce  sync.Once
+	mentionErr   error
+)
+
+// resetMentionCache resets the cache for testing.
+func resetMentionCache() {
+	mentionOnce = sync.Once{}
+	mentionUsers = nil
+	mentionErr = nil
+}
+
+// mentionRegex matches @Name patterns not preceded by word characters or dots
+// (to avoid matching emails like user@example.com).
+var mentionRegex = regexp.MustCompile(`(?:^|[^a-zA-Z0-9_.])@([a-zA-Z][a-zA-Z0-9_]*)`)
+
+// promptItemRegex parses <lexxy-prompt-item> tags from the /prompts/users HTML.
+var promptItemRegex = regexp.MustCompile(`<lexxy-prompt-item\s+search="([^"]+)"\s+sgid="([^"]+)"[^>]*>`)
+
+// avatarRegex extracts the src attribute from the first <img> in editor template.
+var avatarRegex = regexp.MustCompile(`<img[^>]+src="([^"]+)"`)
+
+// resolveMentions scans text for @FirstName patterns and replaces them with
+// ActionText mention HTML. If the text contains no @ characters, it is returned
+// unchanged. On any error fetching users, the original text is returned with a
+// warning printed to stderr.
+func resolveMentions(text string, c client.API) string {
+	if !strings.Contains(text, "@") {
+		return text
+	}
+
+	mentionOnce.Do(func() {
+		mentionUsers, mentionErr = fetchMentionUsers(c)
+	})
+
+	if mentionErr != nil {
+		fmt.Fprintf(os.Stderr, "Warning: could not fetch mentionable users: %v\n", mentionErr)
+		return text
+	}
+
+	if len(mentionUsers) == 0 {
+		return text
+	}
+
+	// Find all @Name matches with positions
+	type mentionMatch struct {
+		start int // start of @Name (the @ character)
+		end   int // end of @Name
+		name  string
+	}
+
+	allMatches := mentionRegex.FindAllStringSubmatchIndex(text, -1)
+	var matches []mentionMatch
+	for _, loc := range allMatches {
+		// loc[2]:loc[3] is the capture group (the name without @)
+		nameStart := loc[2]
+		nameEnd := loc[3]
+		// The @ is one character before the name
+		atStart := nameStart - 1
+		name := text[nameStart:nameEnd]
+		matches = append(matches, mentionMatch{start: atStart, end: nameEnd, name: name})
+	}
+
+	// Process from end to start so replacements don't shift indices
+	for i := len(matches) - 1; i >= 0; i-- {
+		m := matches[i]
+
+		// Find matching user by first name (case-insensitive)
+		var found []mentionUser
+		for _, u := range mentionUsers {
+			if strings.EqualFold(u.FirstName, m.name) {
+				found = append(found, u)
+			}
+		}
+
+		switch len(found) {
+		case 1:
+			html := buildMentionHTML(found[0])
+			text = text[:m.start] + html + text[m.end:]
+		case 0:
+			fmt.Fprintf(os.Stderr, "Warning: could not resolve mention @%s\n", m.name)
+		default:
+			names := make([]string, len(found))
+			for j, u := range found {
+				names[j] = u.FullName
+			}
+			fmt.Fprintf(os.Stderr, "Warning: ambiguous mention @%s — matches: %s\n", m.name, strings.Join(names, ", "))
+		}
+	}
+
+	return text
+}
+
+// fetchMentionUsers fetches the list of mentionable users from the API.
+func fetchMentionUsers(c client.API) ([]mentionUser, error) {
+	resp, err := c.GetHTML("/prompts/users")
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("unexpected status %d from /prompts/users", resp.StatusCode)
+	}
+	return parseMentionUsers(resp.Body), nil
+}
+
+// parseMentionUsers extracts mentionable users from the /prompts/users HTML.
+// Each user is represented as a <lexxy-prompt-item> element with search and sgid
+// attributes, containing <img> tags with avatar URLs.
+func parseMentionUsers(html []byte) []mentionUser {
+	htmlStr := string(html)
+	items := promptItemRegex.FindAllStringSubmatch(htmlStr, -1)
+	if len(items) == 0 {
+		return nil
+	}
+
+	var users []mentionUser
+	for _, item := range items {
+		search := strings.TrimSpace(item[1])
+		sgid := item[2]
+
+		if search == "" || sgid == "" {
+			continue
+		}
+
+		// Parse name from search attribute.
+		// Format: "Full Name INITIALS [me]"
+		// Strip trailing "me" and all-uppercase words (initials like "WS", "FMA").
+		words := strings.Fields(search)
+		for len(words) > 1 {
+			last := words[len(words)-1]
+			if last == "me" || isAllUpper(last) {
+				words = words[:len(words)-1]
+			} else {
+				break
+			}
+		}
+
+		fullName := strings.Join(words, " ")
+		firstName := words[0]
+
+		// Extract avatar URL: find the <img> after this sgid in the HTML.
+		avatarSrc := ""
+		sgidIdx := strings.Index(htmlStr, `sgid="`+sgid+`"`)
+		if sgidIdx >= 0 {
+			// Search for the first <img> after the sgid
+			remainder := htmlStr[sgidIdx:]
+			if m := avatarRegex.FindStringSubmatch(remainder); len(m) > 1 {
+				avatarSrc = m[1]
+			}
+		}
+
+		users = append(users, mentionUser{
+			FirstName: firstName,
+			FullName:  fullName,
+			SGID:      sgid,
+			AvatarSrc: avatarSrc,
+		})
+	}
+
+	return users
+}
+
+// buildMentionHTML creates the ActionText attachment HTML for a mention.
+func buildMentionHTML(u mentionUser) string {
+	return fmt.Sprintf(
+		`<action-text-attachment sgid="%s" content-type="application/vnd.actiontext.mention">`+
+			`<img title="%s" src="%s" width="48" height="48">%s`+
+			`</action-text-attachment>`,
+		u.SGID, u.FullName, u.AvatarSrc, u.FirstName,
+	)
+}
+
+// isAllUpper returns true if s is non-empty and all uppercase letters.
+func isAllUpper(s string) bool {
+	if s == "" {
+		return false
+	}
+	for _, r := range s {
+		if !unicode.IsUpper(r) {
+			return false
+		}
+	}
+	return true
+}