Sync fork to upstream v4 + reapply & fix @mention patch — establish single source of truth

[waynemsmith]

Goal

Establish a single source of truth for the Fizzy CLI we use day-to-day: this fork (Concurrent-Systems/fizzy-cli, master), synced to the latest official release, carrying our @mention patch working end-to-end, built and installed as the only fizzy on the workstation. Remove the parallel/old implementation and point the Agent Skill at this repo only.

Right now mentions silently fail and there are two divergent codebases — this issue makes it clean and reliable.

Current state (the tangle)

• This repo (Concurrent-Systems/fizzy-cli) is a Go fork of basecamp/fizzy-cli. Default branch master, primaryLanguage Go. Not archived.
• Old TypeScript implementation still lives on the main branch (tip 0fd8782 "Update PLAN.md: PR Fix search to be cross-board by default basecamp/fizzy-cli#114 merged upstream") and as a local clone at ~/g/fizzy-cli. This is the superseded "first build" and should be retired.
• The @mention patch is NOT on master. It lives on branch mention-resolution (local + origin), 4 commits ahead of master, never merged:
  • 319e339 Add @mention resolution for comments and descriptions
  • c0b727e Address review feedback on mention resolution
  • dc96a14 Fix search to be cross-board by default
  • f84f9d7 Hoist getClient() before conditional branches
  • Adds internal/commands/mentions.go + internal/commands/mentions_test.go.
• The installed binary (~/.local/bin/fizzy, built 2026-03-28, version v0.0.0-20260328151448-f84f9d79dafe+dirty) was built from a commit that includes the mention code (+dirty = from uncommitted changes), so mention code is compiled in — but see the runtime bug below.
• Mentions are broken at runtime. Any @Name in a comment/description emits:
  Warning: could not fetch mentionable users: Unauthorized: Run 'fizzy auth login TOKEN' or set FIZZY_TOKEN
  The @Name is left as plain text and no Fizzy notification fires. Root cause: fetchMentionUsers fetches mentionables from the /prompts/users endpoint, which returns the Lexxy editor autocomplete HTML (<lexxy-prompt-item search="…" sgid="…">) and is almost certainly session/cookie-authenticated, not API-token — the CLI's fizzy_… token is rejected. So @mentions have effectively never worked end-to-end. (All other commands using JSON/API endpoints — user list, card create, etc. — work fine with the same token.)
• Upstream has moved a lot: our master is 127 commits behind basecamp/fizzy-cli (now v4.0.0-rc.4+). Major upstream changes: migration to the fizzy SDK (fizzy-sdk v0.2.2, hashicorp/go-version), a dedicated FTS search endpoint (fizzy search repurposed), and a Homebrew transition for Fizzy 4. Our patch will need re-applying on top of a substantially changed client layer.
• Mention patch is NOT upstreamed — basecamp has no @mention support (only markdown-attachment sanitization). The fork patch remains necessary.
• Agent Skill (~/.claude/skills/fizzy/SKILL.md) documents @FirstName mentions (Invariant Fix misleading --account option documentation basecamp/fizzy-cli#8 + "@Mentions") but its only repo reference (line ~1141) points to https://github.com/basecamp/fizzy-cli (upstream), not this fork.

Desired end state (SSOT)

1. master of this repo = latest upstream + our mention patch, all tests green.
2. @mention in comments and descriptions actually resolves and notifies (verified against a real card).
3. One installed fizzy on the workstation, built from this master, version string clean (no +dirty).
4. The old TS implementation retired (branch main + ~/g/fizzy-cli), so there is no parallel codebase.
5. The Agent Skill points only to this fork and documents how to build/install/update it.

Tasks

• Sync to upstream. Rebase/merge master onto basecamp/fizzy-cli latest stable-ish (v4.0.0-rc.4 or the chosen target). Resolve the SDK-migration churn in the client/HTTP layer.
• Reapply the mention patch (mention-resolution: 319e339, c0b727e) on top of the synced master. Adapt mentions.go to the new SDK client (getHtml/equivalent).
• Fix the runtime auth bug. Determine the correct authenticated way to fetch mentionables. Options to investigate: (a) does the new fizzy SDK expose a mentionables/prompt-users call that authenticates with the API token? (b) is there a JSON API endpoint for mentionable users instead of the HTML /prompts/users? (c) if /prompts/users genuinely needs a web session, decide whether that auth path is acceptable for the CLI. The acceptance bar is a real ActionText mention attachment + a delivered notification, not just "no error".
• Tests. Keep/port mentions_test.go; add an e2e that creates a comment with @Name on a throwaway/test card and asserts the stored body contains content-type="application/vnd.actiontext.mention" (not plain @Name), and that the mentioned user is notified.
• Build + install via make (go build -ldflags … -o <bin> ./cmd/fizzy) and install to ~/.local/bin/fizzy. Confirm fizzy version is clean (no +dirty) and from master.
• Retire the old implementation. Archive/delete the TS main branch (and ~/g/fizzy-cli local) once master is the SSOT. Make master unambiguously the only living line.
• Clean the Agent Skill. Update ~/.claude/skills/fizzy/SKILL.md to reference Concurrent-Systems/fizzy-cli as the CLI source, document the build/install/update procedure, and confirm the @mention docs match the working behaviour.
• Merge the result to master via PR; delete the stale mention-resolution / fix-search-default-board branches afterward.

Acceptance criteria

• fizzy comment create --card <test> --body "@Wayne test" produces a stored comment whose HTML contains an ActionText mention attachment and notifies the user — no Unauthorized warning.
• fizzy version reports a clean build off master; ~/.local/bin/fizzy is the only fizzy on PATH.
• go test ./... green, including mention tests.
• No TS implementation remains as a live branch/clone; Skill points only here.

Key references

• Upstream: basecamp/fizzy-cli @ v4.0.0-rc.4 (we are 127 behind).
• Mention branch: mention-resolution (319e339, c0b727e).
• Bug signature: could not fetch mentionable users: Unauthorized; endpoint /prompts/users; attachment markup <action-text-attachment content-type="application/vnd.actiontext.mention">.
• Old impl: main branch (0fd8782) + ~/g/fizzy-cli.
• Skill: ~/.claude/skills/fizzy/SKILL.md (repo ref ~line 1141).

[waynemsmith]

Session findings — root cause corrected (the POST path works; only the fetch is broken)

Synced master → v4.0.0-rc.4 (clean ff, zero divergence) and ported the @mention patch onto the v4/fizzy-sdk base. Branch mention-resolution-v4 (pushed): compiles, unit tests green, wired into comment/card create+update via the resolveRichTextContent chokepoint.

The diagnosis in the issue body ("@mentions have effectively never worked") needs correcting. Proven live this session:

1. The mentionable-users fetch is the only broken step. /prompts/users is fetched with Accept: text/html. The Fizzy API now rejects Accept: text/html globally — even the known-good /{account}/users endpoint returns 401 "HTTP Token: Access denied" with that header. With Accept: application/json the token authenticates fine but /prompts/users returns 500 (it only renders the Lexxy HTML autocomplete partial; no JSON view). So the fetch is a dead end via the API token regardless of Accept header.

2. The post path works perfectly. Posting a comment via the API token with a real, valid mention attachment stores it intact — server validates the HMAC sgid and keeps content-type="application/vnd.actiontext.mention". Verified by harvesting Wayne's real sgid from an existing mention (card #597) and re-posting it on a throwaway card; the attachment survived in the stored HTML.

3. The sgid is stable. Decoded payload: {"_rails":{"data":"gid://fizzy/User/<user_id>?expires_in","pur":"attachable"}} — non-expiring, and <user_id> is the exact id the JSON API already returns. Only the HMAC signature is unforgeable (needs the server secret_key_base).

Conclusion / likely history: mentions almost certainly did work previously — the CLI fetched /prompts/users (HTML+token returned the sgids back then), built the attachment, and posted it. A server-side change that made the API reject Accept: text/html broke only the fetch step; the post step never broke. The original patch's GetHTML using text/html is now the proximate failure.

So the fix is narrower than a redesign — we only need a token-auth way to obtain user sgids. Options:

• (preferred, upstream) ask basecamp to add sgid to the user JSON, or expose a JSON mentionables endpoint (the /prompts/users view can't be reached via the API's content-type rules).
• harvest + cache sgids from existing content (works only for already-mentioned users — partial).
• hold a real web session in the CLI for /prompts/users (against the API-token design).

Acceptance e2e from this issue (assert stored HTML contains the attachment) is exactly the test that would have caught the false-green; the legacy TS suite only mocked /prompts/users.

[waynemsmith]

Merged PR #3 → master is now upstream v4.0.0-rc.4 + the ported @mention patch (sync + reapply tasks done).

Remaining under this issue:

• Make @mentions resolve at runtime — split out to @mentions: resolve end-to-end via a token-auth source of user SGIDs #2 (token-auth SGID source; post path already proven).
• Build + install to ~/.local/bin/fizzy off master.
• Retire the legacy TS implementation (main branch + ~/g/fizzy-cli clone) — gated on a clean installed master build.
• Point the Agent Skill (~/.claude/skills/fizzy/SKILL.md) at this fork.

Stale branches mention-resolution and fix-search-default-board deleted.

[waynemsmith]

Legacy retired + skill repointed + installed off master.

• Installed ~/.local/bin/fizzy = v4.0.0-rc.4-3-g98a3b2d (clean, off master); only fizzy on PATH.
• Agent Skill now points at this fork — both the global ~/.claude/skills/fizzy/SKILL.md and the repo-embedded skills/fizzy/SKILL.md (PR Point embedded skill at this fork #5); the installed binary embeds the fork-pointing skill.
• TS legacy retired: origin/main deleted (preserved permanently as tag ts-legacy-archive → 0fd8782), local clone moved to ~/g/_archive/fizzy-cli-ts-legacy. master is now the only living line.

Acceptance status: 1 ✅ (sync+patch on master) · 2 ❌ runtime @mention resolution → tracked in #2 · 3 ✅ clean install off master · 4 ✅ TS retired · 5 ✅ skill points here.

Only remaining item for this issue is the runtime mention fix (#2). Suggest closing this once #2 lands, or closing now and letting #2 carry it.

[waynemsmith]

Closing — the SSOT is established: master = upstream v4.0.0-rc.4 + the @mention patch (PR #3), installed as the only fizzy (clean off master), TS legacy retired (tag ts-legacy-archive, clone archived), and the Agent Skill points here (PR #5). The one remaining item — making @mentions resolve at runtime (token-auth SGID source) — is carried by #2.